@protoboxai/sdk

Connect SaaS integrations with managed per-user auth and hand their tools to any LLM — OpenAI, Anthropic, or the Vercel AI SDK. Tool execution runs through the Protobox platform, which calls the SaaS API using the stored credential server-side; tokens never reach the SDK.

Supersedes the legacy @protoboxai/sdk-v1. See Migrating.

Install

npm install @protoboxai/sdk

Quick start

import { ProtoboxSDK } from '@protoboxai/sdk';

const sdk = new ProtoboxSDK({ apiKey: process.env.PROTOBOX_API_KEY! });

// 1. Scope to one of YOUR end-users (an "entity" — the platform's caller/userId)
const user = sdk.entity('user_123');

// 2. Connect their GitHub via managed OAuth — redirect them to `authorizeUrl`
const { authorizeUrl } = await user.connect('github');
// ...user completes the Protobox-hosted OAuth flow in the browser...
await user.waitUntilActive('github'); // poll until the connection is active

// 3. Hand GitHub's tools to Claude
const gh = user.forLLM('anthropic', { integrationId: 'github' });
const tools = await gh.tools();

const message = await anthropic.messages.create({ model, messages, tools });
const toolResults = await gh.run(message.content); // executed server-side, per-user creds

GitHub App integrations use await user.install('github') (returns installUrl) instead of connect.

Core concepts

| Concept | What it is | |---------|-----------| | Integration | A connectable app in the catalog (github, gmail, …) and its actions. | | Entity | One of your end-users. Connections + tool calls are isolated per entity. | | Connection | A connected account with a managed, auto-refreshed credential. | | Adapter | One-line handoff of tools to OpenAI / Anthropic / Vercel AI SDK. |

Modules

sdk.integrations.list()                                  // browse the catalog
sdk.integrations.actions('github')                       // an integration's tools + schemas

sdk.connections.initiateOAuth({ integrationId, userId }) // hosted OAuth → { authorizeUrl }
sdk.connections.initiateInstall({ integrationId, userId })// GitHub App → { installUrl }
sdk.connections.connectApiKey({ integrationId, apiKey }) // workspace-level API key
sdk.connections.listForUser(userId)                      // a user's connections
sdk.connections.waitUntilActive(integrationId, userId)   // poll until connected
sdk.connections.disconnectUser(appCredentialsId, userId) // revoke a user's connection

sdk.tools.listTools({ integrationId })                   // an integration's tools
sdk.tools.execute({ name, arguments, entityId })         // run through the platform
sdk.tools.forLLM('openai' | 'anthropic' | 'vercel')      // framework adapters

sdk.sessions.create({ userId, toolsetSlug })             // mint a per-end-user MCP session
                                                         // → { id, token, mcpUrl } (token shown ONCE)
sdk.sessions.list({ search: userId })                    // find a user's sessions (no tokens)
sdk.sessions.revoke(sessionId)                           // kill it (user sign-out / offboarding)
sdk.sessions.listEvents(sessionId)                       // 90-day activity log → { items, nextCursor }

These map onto the platform's /api/v1/tools/integrations + /api/v1/tools/actions routes. End-user identity is the userId (the backend "caller"), sent in-band — as the request body for connect/OAuth and as context.externalReferenceIds.customerId for execution — never as a header.

Entity-scoped (recommended)

const user = sdk.entity('user_123');
await user.connect('gmail');            // → { authorizeUrl }
await user.waitUntilActive('gmail');
const tools = await user.forLLM('openai', { integrationId: 'gmail' }).tools();

Embed Protobox in your product (MCP sessions)

Give each of YOUR end-users a scoped, revocable MCP endpoint their agent can connect to — meta-tools only, bound to that user, restricted to one toolset:

const session = await sdk.sessions.create({ userId: 'user_123', toolsetSlug: 'support' });
// session.token is shown ONCE — store it server-side, never log it.
// Hand the user's agent: session.mcpUrl with header `Authorization: Bearer <token>`.

Full partner runbook (concepts, agent config snippets, the auth_required connect flow, lifecycle & security): https://docs.protobox.ai/sdk/embed

Adapters

// OpenAI
const oa = user.forLLM('openai');
const tools = await oa.tools();                     // ChatCompletionTool[]
const toolMsgs = await oa.run(msg.tool_calls ?? []); // role:'tool' messages

// Anthropic
const an = user.forLLM('anthropic');
const results = await an.run(response.content);      // tool_result blocks

// Vercel AI SDK
const vc = user.forLLM('vercel');
const { text } = await generateText({ model, prompt, tools: await vc.tools(), maxSteps: 5 });

Errors

Typed subclasses of ProtoboxError: ValidationError (400), AuthenticationError (401), AuthorizationError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), ServerError (5xx), plus ConnectionNotReadyError and TimeoutError. Guards: isProtoboxError, isNotFoundError, isConnectionNotReadyError, …

Roadmap

• Triggers/webhooks — the sdk.triggers namespace is reserved; calls throw NotImplementedError until delivery ships.
• Python SDK — mirrors this surface.

Implementation status (v2 surface)

The sdk.connectors / authConfigs / secrets / toolsets / mcpServers / actions / approvals / executions / webhooks namespaces are the session-centric v2 contract surface (see CONVENTIONS.md). Every method is either bound to a real endpoint or an honest stub that throws ProtoboxNotImplemented('<method>', '<phase>') naming the program phase it arrives in — never a silent no-op. The table below is generated directly from the client (pnpm generate:stub-map), not hand-maintained.

Generated by pnpm generate:stub-map (scripts/generate-stub-map.js) on 2026-09-02 — do not hand-edit between the markers.

179 methods — 50 implemented, 126 delegate, 3 stub.

| Method | Status | | --- | --- | | actions.execute | DELEGATE | | actions.getSchema | DELEGATE | | actions.search | DELEGATE | | approvals.approve | DELEGATE | | approvals.deny | DELEGATE | | approvals.get | DELEGATE | | approvals.list | DELEGATE | | authConfigs.create | DELEGATE | | authConfigs.list | DELEGATE | | automations.create | DELEGATE | | automations.delete | DELEGATE | | automations.disable | DELEGATE | | automations.enable | DELEGATE | | automations.get | DELEGATE | | automations.list | DELEGATE | | automations.runs | DELEGATE | | automations.update | DELEGATE | | connections.connectApiKey | IMPLEMENTED | | connections.create | IMPLEMENTED | | connections.createConnectToken | IMPLEMENTED | | connections.delete | IMPLEMENTED | | connections.disconnect | IMPLEMENTED | | connections.disconnectUser | IMPLEMENTED | | connections.get | IMPLEMENTED | | connections.initiate | IMPLEMENTED | | connections.initiateInstall | IMPLEMENTED | | connections.initiateOAuth | IMPLEMENTED | | connections.list | IMPLEMENTED | | connections.listAppCredentials | IMPLEMENTED | | connections.listForUser | IMPLEMENTED | | connections.request | STUB(phase-4) | | connections.status | IMPLEMENTED | | connections.waitUntilActive | IMPLEMENTED | | connectors.disable | STUB(backlog) | | connectors.enable | STUB(backlog) | | connectors.get | DELEGATE | | connectors.invokeTest | DELEGATE | | connectors.list | DELEGATE | | connectors.registerCode | DELEGATE | | connectors.registerOpenApi | DELEGATE | | connectors.setRegistrationStatus | DELEGATE | | connectors.syncOpenApi | DELEGATE | | connectors.unregister | DELEGATE | | databases.add | DELEGATE | | databases.addQuery | DELEGATE | | databases.list | DELEGATE | | databases.listQueries | DELEGATE | | databases.remove | DELEGATE | | databases.removeQuery | DELEGATE | | executions.get | DELEGATE | | executions.list | DELEGATE | | executions.trace | DELEGATE | | feedback.list | DELEGATE | | feedback.submit | DELEGATE | | integrations.actions | IMPLEMENTED | | integrations.get | IMPLEMENTED | | integrations.list | IMPLEMENTED | | knowledge.ask | DELEGATE | | knowledge.askPublic | DELEGATE | | knowledge.create | DELEGATE | | knowledge.delete | DELEGATE | | knowledge.deleteAll | DELEGATE | | knowledge.deleteAllPreview | DELEGATE | | knowledge.exportAll | DELEGATE | | knowledge.exportStatus | DELEGATE | | knowledge.gallery | DELEGATE | | knowledge.get | DELEGATE | | knowledge.getPublicPack | DELEGATE | | knowledge.import | DELEGATE | | knowledge.importStatus | DELEGATE | | knowledge.list | DELEGATE | | knowledge.listStale | DELEGATE | | knowledge.listSynced | DELEGATE | | knowledge.proposalStatus | DELEGATE | | knowledge.proposeAppend | DELEGATE | | knowledge.proposeUpdate | DELEGATE | | knowledge.publishFolder | DELEGATE | | knowledge.search | DELEGATE | | knowledge.setFolderAccess | DELEGATE | | knowledge.setOwner | DELEGATE | | knowledge.taskStatus | DELEGATE | | knowledge.unpublishFolder | DELEGATE | | knowledge.unverify | DELEGATE | | knowledge.update | DELEGATE | | knowledge.upsertFile | DELEGATE | | knowledge.verify | DELEGATE | | mcpServers.create | DELEGATE | | mcpServers.delete | DELEGATE | | mcpServers.get | DELEGATE | | mcpServers.list | DELEGATE | | mcpServers.update | DELEGATE | | mcpServers.keys.create | DELEGATE | | mcpServers.keys.list | DELEGATE | | mcpServers.keys.revoke | DELEGATE | | memory.entities | DELEGATE | | memory.entity | DELEGATE | | memory.forget | DELEGATE | | memory.history | DELEGATE | | memory.import | DELEGATE | | memory.listRecent | DELEGATE | | memory.recall | DELEGATE | | memory.search | DELEGATE | | memory.store | DELEGATE | | prompts.create | DELEGATE | | prompts.delete | DELEGATE | | prompts.get | DELEGATE | | prompts.getRatings | DELEGATE | | prompts.importGithub | DELEGATE | | prompts.list | DELEGATE | | prompts.rate | DELEGATE | | prompts.update | DELEGATE | | secrets.delete | DELEGATE | | secrets.list | DELEGATE | | secrets.set | DELEGATE | | sessions.create | IMPLEMENTED | | sessions.delete | IMPLEMENTED | | sessions.get | IMPLEMENTED | | sessions.list | IMPLEMENTED | | sessions.listEvents | IMPLEMENTED | | sessions.revoke | IMPLEMENTED | | sessions.update | IMPLEMENTED | | sessions.use | IMPLEMENTED | | tools.create | IMPLEMENTED | | tools.createBatch | IMPLEMENTED | | tools.createDefaults | IMPLEMENTED | | tools.delete | IMPLEMENTED | | tools.execute | IMPLEMENTED | | tools.executeById | IMPLEMENTED | | tools.forLLM | IMPLEMENTED | | tools.generate | IMPLEMENTED | | tools.get | IMPLEMENTED | | tools.getSchema | IMPLEMENTED | | tools.list | IMPLEMENTED | | tools.listTools | IMPLEMENTED | | tools.propose | IMPLEMENTED | | tools.proposeFromUrl | IMPLEMENTED | | tools.search | IMPLEMENTED | | tools.update | IMPLEMENTED | | toolsets.addSkill | DELEGATE | | toolsets.create | DELEGATE | | toolsets.delete | DELEGATE | | toolsets.get | DELEGATE | | toolsets.list | DELEGATE | | toolsets.setToolAccess | DELEGATE | | toolsets.setToolPolicy | DELEGATE | | toolsets.tools | DELEGATE | | toolsets.update | DELEGATE | | triggers.create | IMPLEMENTED | | triggers.delete | IMPLEMENTED | | triggers.disable | IMPLEMENTED | | triggers.enable | IMPLEMENTED | | triggers.get | IMPLEMENTED | | triggers.list | IMPLEMENTED | | triggers.runs | IMPLEMENTED | | triggers.update | IMPLEMENTED | | webhooks.delete | DELEGATE | | webhooks.get | DELEGATE | | webhooks.register | DELEGATE | | webhooks.verify | DELEGATE | | workspace.claim | DELEGATE | | workspace.claimVerify | DELEGATE | | workspace.get | DELEGATE | | workspace.invitations | DELEGATE | | workspace.invite | DELEGATE | | workspace.members | DELEGATE | | workspace.referral | DELEGATE | | workspace.removeMember | DELEGATE | | workspace.revokeInvitation | DELEGATE | | workspace.onboarding.answer | DELEGATE | | workspace.onboarding.get | DELEGATE | | workspace.storage.get | DELEGATE | | workspace.storage.remove | DELEGATE | | workspace.storage.set | DELEGATE | | session(handle).authorize | DELEGATE | | session(handle).buildToolProvider | DELEGATE | | session(handle).execute | DELEGATE | | session(handle).fetchDetail | DELEGATE | | session(handle).resolveIdentity | DELEGATE | | session(handle).tools | DELEGATE |

Migrating from @protoboxai/sdk-v1

@protoboxai/sdk-v1 (the legacy chanl grab-bag package, formerly published as @protoboxai/sdk) is deprecated in favor of this package. The new SDK leads with the agent-tooling surface (integrations, connections, entity-scoped tool calls, framework adapters). Knowledge and prompts modules landed in 2.2.0; workspace management is not ported.

Configuration

new ProtoboxSDK({
  apiKey: '...',                 // required
  baseUrl: 'http://localhost:3100', // default: https://platform.protobox.ai
  entityId: 'user_123',          // optional default entity for all calls
  timeout: 30000,
  debug: false,
});

License

MIT