> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK

> @jinba-toolbox/sdkパッケージを使用してTypeScriptおよびJavaScriptアプリケーションからJinba Toolboxを操作する

## 概要

`@jinba-toolbox/sdk` パッケージは、Jinba Toolboxに登録されたToolを利用するための型安全なクライアントライブラリです。REST APIをラップし、ToolSetの一覧取得、Toolの実行、Versionの管理、実行履歴の取得などの便利なメソッドを提供します。

**想定される利用者:**

* Toolを実行するAIエージェント
* 自動化のためのCLIツール
* Jinba Toolboxと統合するサードパーティアプリケーション
* Jinba Toolbox上で開発する開発者

## インストール

```bash theme={null}
# npm
npm install @jinba-toolbox/sdk

# pnpm
pnpm add @jinba-toolbox/sdk

# yarn
yarn add @jinba-toolbox/sdk
```

## クイックスタート

<Steps>
  <Step title="インポートしてクライアントを作成する">
    ```typescript theme={null}
    import { createClient } from "@jinba-toolbox/sdk";

    const client = createClient({
      apiKey: process.env.JINBA_TB_API_KEY!,
      organizationId: "org-id", // optional default
    });
    ```
  </Step>

  <Step title="ToolSetの一覧を取得する">
    ```typescript theme={null}
    const toolSets = await client.listToolSets();
    console.log(toolSets);
    ```
  </Step>

  <Step title="Toolを実行する">
    ```typescript theme={null}
    const result = await client.run("slack-tools", "post-message", {
      channel: "#general",
      text: "Hello from Jinba Toolbox!",
    });

    console.log(result.output);
    // { ts: "1234567890.123456", channel: "C01234567" }
    ```
  </Step>
</Steps>

## クライアント設定

`createClient` 関数は `JinbaTBClientConfig` オブジェクトを受け取ります：

```typescript theme={null}
interface JinbaTBClientConfig {
  /** APIベースURL（デフォルト: https://toolbox-api.jinba.dev） */
  baseUrl?: string;
  /** 認証用APIキー */
  apiKey: string;
  /** デフォルトの組織ID（省略可能、リクエストごとにオーバーライド可能） */
  organizationId?: string;
  /** リクエストタイムアウト（ミリ秒、デフォルト: 30000） */
  timeout?: number;
}
```

すべてのオプションを指定した**例**：

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

コンストラクタで `organizationId` を設定すると、個々のメソッド呼び出しで省略できます。すべてのメソッドには、デフォルトをオーバーライドするためのオプションの `orgId` パラメータも用意されています。

## APIリファレンス

### 組織

```typescript theme={null}
// 認証済みユーザーが所属する組織の一覧を取得
const orgs = await client.listOrganizations();
// Returns: OrganizationWithRole[]

// 組織の詳細を取得
const org = await client.getOrganization("org-id");
// Returns: Organization
```

### ToolSet

```typescript theme={null}
// 組織内のToolSet一覧を取得
const toolSets = await client.listToolSets();
// Returns: ToolSet[]

// スラッグでToolSetを取得（Toolを含む）
const toolSet = await client.getToolSet("slack-tools");
// Returns: ToolSet & { tools: Tool[] }

// 新しい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"],
});

// ToolSetを更新
await client.updateToolSet("slack-tools", {
  visibility: "public",
  tags: ["slack", "messaging"],
});

// ToolSetを削除
await client.deleteToolSet("slack-tools");
```

### Tool

```typescript theme={null}
// ToolSet内のTool一覧を取得
const tools = await client.listTools("slack-tools");
// Returns: Tool[]

// スラッグでToolを取得
const tool = await client.getTool("slack-tools", "post-message");
// Returns: Tool

// 新しいToolを作成
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: {
      channel: { type: "string", description: "Channel name or ID" },
      text: { type: "string", description: "Message text" },
    },
    required: ["channel", "text"],
  },
  outputSchema: {
    type: "object",
    properties: {
      ts: { type: "string" },
      channel: { type: "string" },
    },
  },
  code: `// tool implementation code`,
});

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

// Toolを削除
await client.deleteTool("slack-tools", "post-message");
```

### 実行

```typescript theme={null}
// 公開済み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

// 特定のVersionを指定して実行
const result = await client.run(
  "slack-tools",
  "post-message",
  { channel: "#general", text: "Hello!" },
  { version: "1.2.0" }
);

// Toolをテスト（ドラフトコードを実行、公開Versionは不要）
const testResult = await client.test("slack-tools", "post-message", {
  channel: "#test",
  text: "Testing...",
});
```

### Version

```typescript theme={null}
// ToolSetのVersion一覧を取得
const versions = await client.listVersions("slack-tools");
// Returns: ToolSetVersion[]

// 新しいVersionを公開
const version = await client.publishVersion("slack-tools", {
  version: "1.3.0",
  releaseNotes: "Added thread reply support",
});
// Returns: ToolSetVersion
```

### 実行履歴

```typescript theme={null}
// 組織内のRun一覧を取得
const runs = await client.listRuns();
// Returns: Run[]

// Runの詳細を取得
const run = await client.getRun("run_abc123");
// Returns: Run
```

## 主要な型

### RunResult

`run()` と `test()` から返されるオブジェクト：

```typescript theme={null}
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;
}
```

### ToolSet

```typescript theme={null}
interface ToolSet {
  id: string;
  organizationId: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  sandbox: SandboxConfig;
  visibility: "public" | "private" | "restricted";
  mcpEnabled: boolean;
  tags: string[];
  latestVersion?: string | null;
  publishedVersion?: string | null;
  createdAt: string;
  updatedAt: string;
}
```

### Tool

```typescript theme={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;
}
```

## エラーハンドリング

SDKは非2xxレスポンスに対して `JinbaTBError` をスローします：

```typescript theme={null}
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)}`);
  }
}
```

リクエストが設定されたタイムアウトを超えた場合、408ステータスコードがスローされます。

## ベストプラクティス

* **コンストラクタでデフォルトの `organizationId` を設定する** -- すべてのメソッドに渡す手間を省けます。
* **APIキーには環境変数を使用する** -- 認証情報を絶対にハードコードしないでください。
* **`JinbaTBError` を適切にハンドリングする** -- クライアントエラー（4xx）とサーバーエラー（5xx）を区別できます。
* **`timeout` を延長する** -- 複雑なSandboxワークロードを実行するToolの場合に有効です。
* **`run()` 呼び出し時にVersionを指定する** -- アプリケーションが決定論的な動作に依存する場合に推奨します。

## 関連ドキュメント

* [REST API](/ja/pages/toolbox/developer/api) -- 完全なエンドポイントリファレンス
* [MCP統合](/ja/pages/toolbox/developer/mcp) -- ToolSetをAIエージェント向けMCPサーバーとして使用
* [バージョニングと公開](/ja/pages/toolbox/advanced/versioning) -- Versionのライフサイクルを理解する