SDK

The @fold-run/sdk package provides a typed JavaScript/TypeScript client for the fold.run API.

Installation

npm install @fold-run/sdk

Quick Start

import { FoldClient } from '@fold-run/sdk';

const fold = new FoldClient({
  apiKey: 'your-api-key',
  // baseUrl: 'https://api.fold.run'  // default
});

// Deploy a function
const result = await fold.deploy({
  name: 'hello-world',
  code: 'export default { fetch: () => new Response("Hello!") }',
});
console.log(`Deployed ${result.id} @ v${result.version}`);

Authentication

Pass either an API key or a JWT token:

// API key (recommended for production)
const fold = new FoldClient({ apiKey: 'fld_...' });

// JWT token (from fold login or API)
const fold = new FoldClient({ token: 'eyJ...' });

Functions

// List functions
const { functions } = await fold.listFunctions();

// Get function details
const fn = await fold.getFunction('fn-123');

// Delete a function
await fold.deleteFunction('fn-123');

// Rollback to a previous version
await fold.rollback('fn-123', 2);

Activations

// List activations
const { activations } = await fold.listActivations({
  status: 'error',
  limit: 50,
});

// Get activation details
const activation = await fold.getActivation('act-123');

// Replay an activation
await fold.replayActivation('act-123');

// Stream real-time activations
for await (const activation of fold.streamActivations()) {
  console.log(`${activation.status}: ${activation.function_id}`);
}

Secrets

// List secrets (names only, values are never exposed)
const { secrets } = await fold.listSecrets();

// Set a secret
await fold.setSecret('API_KEY', 'sk-...');

// Delete a secret
await fold.deleteSecret('secret_abc123');

Schedules

// List schedules
const { schedules } = await fold.listSchedules();

// Create a schedule (cron expression)
await fold.createSchedule({
  function_id: 'fn-123',
  cron_expression: '*/5 * * * *',
});

// Toggle a schedule
await fold.updateSchedule('fn-123', { enabled: false });

Usage

// Get usage for last 30 days
const usage = await fold.getUsage(30);
console.log(`Total activations: ${usage.totals.activations}`);

Invoking Functions

Call deployed functions directly:

// Simple GET
const response = await fold.invoke('my-tenant', 'hello-world');

// POST with body
const response = await fold.invoke('my-tenant', 'my-api', {
  method: 'POST',
  body: { message: 'hello' },
});

Hooks (Webhooks)

// List hooks
const { hooks } = await fold.listHooks();

// Create a hook
await fold.createHook({
  event: 'deploy.success',
  url: 'https://example.com/hook',
  secret: 'optional-hmac-secret',
});

// Toggle a hook
await fold.updateHook('hook_abc', { active: false });

// Test a hook
await fold.testHook('hook_abc');

// Delete a hook
await fold.deleteHook('hook_abc');

Custom Roles

// List custom roles
const { roles } = await fold.listRoles();

// Create a custom role
await fold.createRole({
  name: 'release-manager',
  permissions: ['deploy', 'view_logs', 'view_activations'],
});

// Update a role
await fold.updateRole('role_abc', { permissions: ['deploy', 'view_logs'] });

// Delete a role
await fold.deleteRole('role_abc');

Error Groups

// List error groups
const { error_groups } = await fold.listErrorGroups({ status: 'open' });

// Resolve an error group
await fold.resolveErrorGroup('eg_abc');

Notification Preferences

// Global preferences
const prefs = await fold.getNotificationPreferences();
await fold.updateNotificationPreferences({ deploy_success: false });

// Workspace-specific preferences
const { preferences } = await fold.getWorkspaceNotificationPreferences('ws_abc');
await fold.updateWorkspaceNotificationPreferences('ws_abc', [
  { event_type: 'deploy_success', enabled: false },
]);

Inbox

// List inbox notifications
const { notifications, unread_count } = await fold.getInbox({ unread: true });

// Get unread count
const { unread_count } = await fold.getInboxCount();

// Mark as read
await fold.markInboxRead('inb_abc');
await fold.markAllInboxRead();

// Delete
await fold.deleteInboxItem('inb_abc');

Tool Recommendations

Find the right tool for a task using natural language:

const { recommendations } = await fold.recommendTools('fetch web page content', 5);
for (const tool of recommendations) {
  console.log(`${tool.tool_name} (score: ${tool.score})`);
}

Framework Adapters

Use Fold tools directly in popular agent frameworks:

LangChain

npm install @fold-run/langchain @langchain/core

import { FoldToolkit } from '@fold-run/langchain';
import { FoldClient } from '@fold-run/sdk';

const client = new FoldClient({ apiKey: 'fold_...' });
const tools = await FoldToolkit.fromClient(client, 'my-org');
// Pass tools to any LangChain agent

Vercel AI SDK

npm install @fold-run/vercel-ai ai

import { createFoldTools } from '@fold-run/vercel-ai';
import { FoldClient } from '@fold-run/sdk';
import { generateText } from 'ai';

const client = new FoldClient({ apiKey: 'fold_...' });
const tools = await createFoldTools(client, 'my-org');
const result = await generateText({ model, tools, prompt: '...' });

Both adapters auto-discover all deployed MCP tools and wrap them as framework-native tool objects with typed schemas.

Error Handling

import { FoldClient, FoldApiError } from '@fold-run/sdk';

try {
  await fold.deploy({ name: 'fn', code: '...' });
} catch (err) {
  if (err instanceof FoldApiError) {
    console.error(`${err.status}: ${err.message} (${err.code})`);
  }
}