SDK

# npm
npm install @jinba-toolbox/sdk

# pnpm
pnpm add @jinba-toolbox/sdk

# yarn
yarn add @jinba-toolbox/sdk

interface JinbaTBClientConfig {
  /** API base URL (default: https://toolbox-api.jinba.dev) */
  baseUrl?: string;
  /** API key for authentication */
  apiKey: string;
  /** Default organization ID (optional, can be overridden per request) */
  organizationId?: string;
  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;
}

const client = createClient({
  baseUrl: "https://toolbox-api.jinba.io",
  apiKey: "jtb_xxxxxxxxxxxx",
  organizationId: "org_abc123",
  timeout: 60000,
});

// List organizations the authenticated user belongs to
const orgs = await client.listOrganizations();
// Returns: OrganizationWithRole[]

// Get organization details
const org = await client.getOrganization("org-id");
// Returns: Organization

// List toolsets in an organization
const toolSets = await client.listToolSets();
// Returns: ToolSet[]

// Get a toolset by slug (includes tools)
const toolSet = await client.getToolSet("slack-tools");
// Returns: ToolSet & { tools: Tool[] }

// Create a new toolset
const newToolSet = await client.createToolSet({
  slug: "slack-tools",
  name: { default: "Slack Tools" },
  description: { default: "Slack integration tools" },
  sandbox: {
    provider: "e2b",
    language: "typescript",
    packages: [{ name: "@slack/web-api" }],
    resources: { timeout: 60000 },
  },
  visibility: "private",
  tags: ["slack"],
});

// Update a toolset
await client.updateToolSet("slack-tools", {
  visibility: "public",
  tags: ["slack", "messaging"],
});

// Delete a toolset
await client.deleteToolSet("slack-tools");

// List tools in a toolset
const tools = await client.listTools("slack-tools");
// Returns: Tool[]

// Get a tool by slug
const tool = await client.getTool("slack-tools", "post-message");
// Returns: Tool

// Create a new tool
// inputSchema / outputSchema are part of the SDK type but ignored by the API:
// both schemas are extracted from the `input` / `output` definitions in `code`.
const newTool = await client.createTool("slack-tools", {
  slug: "post-message",
  name: { default: "Post Message" },
  description: { default: "Post a message to a Slack channel" },
  inputSchema: { type: "object", properties: {} },
  outputSchema: { type: "object", properties: {} },
  code: `import { z } from "zod";

export const input = z.object({
  channel: z.string().describe("Channel name or ID"),
  text: z.string().describe("Message text"),
});

export const output = z.object({
  ts: z.string(),
  channel: z.string(),
});

export async function run(data: z.infer<typeof input>) {
  // tool implementation code
  return { ts: "1234567890.123456", channel: data.channel };
}`,
});

// Update a tool
await client.updateTool("slack-tools", "post-message", {
  description: { default: "Post a message to any Slack channel" },
});

// Delete a tool
await client.deleteTool("slack-tools", "post-message");

// Execute a published tool
const result = await client.run("slack-tools", "post-message", {
  channel: "#general",
  text: "Hello!",
});
// Returns: RunResult

console.log(result.success);    // true
console.log(result.output);     // { ts: "...", channel: "..." }
console.log(result.durationMs); // 1234

// Execute a specific version
const result = await client.run(
  "slack-tools",
  "post-message",
  { channel: "#general", text: "Hello!" },
  { version: "1.2.0" }
);

// Test a tool (runs draft code, no published version required)
// Note: the test endpoint requires a signed-in user session and returns 401
// when called with an API key; use the console's Test panel instead.
const testResult = await client.test("slack-tools", "post-message", {
  channel: "#test",
  text: "Testing...",
});

// List versions of a toolset
const versions = await client.listVersions("slack-tools");
// Returns: ToolSetVersion[]

// Publish a new version
// Note: publishing requires a signed-in user session (the API records the
// publisher); with an API key the call fails. Publish from the console instead.
const version = await client.publishVersion("slack-tools", {
  version: "1.3.0",
  releaseNotes: "Added thread reply support",
});
// Returns: ToolSetVersion

// List runs in an organization
const runs = await client.listRuns();
// Returns: Run[]

// Get run details
const run = await client.getRun("run_abc123");
// Returns: Run

interface RunResult {
  runId: string;
  version: string;
  success: boolean;
  output?: Record<string, unknown>;
  error?: { name: string; message: string; traceback?: string };
  logs?: { stdout: string[]; stderr: string[] };
  durationMs?: number;
}

interface ToolSet {
  id: string;
  organizationId: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  icon?: string | null;
  tags: string[];
  sandbox: SandboxConfig;
  visibility: "public" | "private" | "restricted"; // the API only returns "public" | "private"
  mcpEnabled: boolean;
  latestVersion?: string | null;
  publishedVersion?: string | null;
  createdAt: string;
  updatedAt: string;
  publishedAt?: string | null;
}

interface Tool {
  id: string;
  toolSetId: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  code: string;
  entrypoint?: string | null;
  createdAt: string;
  updatedAt: string;
}

import { JinbaTBError } from "@jinba-toolbox/sdk";

try {
  const result = await client.run("my-toolset", "my-tool", { input: "data" });
} catch (error) {
  if (error instanceof JinbaTBError) {
    console.error(`Status: ${error.statusCode}`);
    console.error(`Message: ${error.message}`);
    console.error(`Details: ${JSON.stringify(error.details)}`);
  }
}