zanii-connect — TypeScript SDK

TypeScript/JavaScript client for Zanii Connect: OAuth connections, encrypted token vault, and audited tool execution for AI agents.

Zero runtime dependencies — uses the platform fetch (Node 18+, browsers, edge runtimes).

Install

npm install zanii-connect

Requires Node 18+ (or any runtime with a global fetch). Ships with TypeScript types.

Quickstart

import { ZaniiClient } from "zanii-connect";

// Agents/services authenticate with a scoped API key:
const nc = new ZaniiClient({ apiKey: "nsk_..." });

// Or as a user (JWT):
const nc = new ZaniiClient();
await nc.login("[email protected]", "password");

console.log((await nc.me()).organization.name);

// Connect a provider (open the returned URL in a browser to complete OAuth):
const { url } = await nc.connect("gmail",
  "https://vault.zanii.agency/api/v1/connect/oauth/callback");

// Discover tools and execute one:
const conn = (await nc.connections()).connections[0];
const found = await nc.execute("gmail.search", conn.id, { query: "invoice" });

// Actions that need human approval return an approval link instead of executing:
const res = await nc.execute("gmail.sendEmail", conn.id,
  { to: "[email protected]", subject: "Hi", body: "Hello" });
if (res.requires_approval) console.log("Ask a human to confirm:", res.approval_url);

// Long-running work goes through the job queue:
const job = await nc.executeAsync("browser.run", conn.id, { /* ... */ });
const result = await nc.waitForJob(job.job_id, 300);

Behavior

• Retries: 429/502/503/504 are retried up to 3 times with exponential backoff.
• Idempotency: pass { idempotencyKey } to execute() to make retries safe for side-effecting actions.
• Errors: non-2xx responses throw ZaniiError with .statusCode and .detail.
• MCP: AI agents that speak MCP don't need this SDK — point them at POST https://vault.zanii.agency/api/v1/mcp with an X-API-Key header.

Surface

Mirrors the Python SDK (sdk/python), camelCased — covers the full API:

• Account: signup, login, me, updateProfile, changePassword, forgotPassword, resetPassword, email verification, MFA (mfaEnroll/mfaEnable/mfaDisable)
• API keys: createApiKey (plaintext returned once), apiKeys, deleteApiKey (soft revoke)
• Org & team: org, usage, updateOrg, exportOrg, deleteOrg, users, inviteUser, updateUser, deactivateUser, roles (permissions, roles, upsertRole, deleteRole), workspaces/projects/environments
• Registry: providers, provider, providerActions, actions, action, tools, tool, dynamic-registry admin (registerProvider, registerAction, unregisterAction)
• Connections: connect, connections, connectionsHealth, deleteConnection, shareConnection
• Execution: execute, executeAsync, job, waitForJob · approvals (approvals, approve)
• Browser sandbox: createBrowserSession, browserSession, browserRun, browserRunAsync
• Secrets / automation: secrets, setSecret, deleteSecret, triggers, webhook subscriptions
• Observability: executions (each row carries receipt_hash + proof_url), audit, auditExportCsv, health
• Proof-of-action: receiptsBundle (offline-verifiable audit bundle), complianceReport (json/markdown)

License

MIT © Zanii Agency