SDK インストール
TypeScript SDK (@nanoterm/sdk) は HTTP API の薄いラッパーです。Agent 側のコードから、他のクライアントライブラリと同じ感覚で使えます — ワークスペースを作成して、コマンドを実行して、ターミナルをストリームする。
インストール
npm install @nanoterm/sdk
# または
pnpm add @nanoterm/sdk
# または
bun add @nanoterm/sdk
初期化
import { NanoTermClient } from '@nanoterm/sdk'
const client = new NanoTermClient({
apiKey: process.env.NANOTERM_API_KEY!,
})
| オプション | デフォルト | 設定するタイミング |
|---|---|---|
apiKey | — | 常に必須。ダッシュボードから発行します。 |
baseUrl | https://api.nanoterm.dev | ローカル開発や staging を使う場合 (http://localhost:3000)。 |
clientName | nanoterm-sdk | 監査ログとバージョンゲート判定で自分のアプリを識別したいとき。 |
clientVersion | （現 SDK バージョン） | SDK を再パッケージして独自の値を入れたいときのみ上書き。 |
SDK はすべてのリクエストに X-Client-Name と X-Client-Version
を送ります。サーバー側はこれを監査ログに記録し、最低 CLI バージョン
ゲート（426 CLI_VERSION_TOO_OLD）の判定にも使用します。ゲートは
clientName === "nanoterm-cli" のときだけ発火するため、アプリケー
ションコードからの利用ではデフォルト nanoterm-sdk のままが安全です。
注記
SDK は環境変数を暗黙に読みません。apiKey は明示的に渡して、キーの出所が呼び出し箇所から見えるようにしてください。
エラーハンドリング
SDK はネイティブ fetch を使い、ネットワーク失敗時に例外を投げます。HTTP エラーは共通エラーエンベロープで返ります：
try {
const ws = await client.createWorkspace({ image: 'ubuntu:22.04' })
} catch (err) {
// ネットワークエラーまたは非 2xx レスポンス
console.error(err)
}
一時的失敗の自動リトライ
SDK は一時的な失敗（502 / 503 / 504、ネットワークエラー、CDN の
非 JSON エラーページなど）に対して [500ms, 1500ms, 4000ms] の
バックオフで最大 3 回まで透過的にリトライします。構造化された
4xx / 5xx エラーエンベロープは リトライしません — 即座に throw
してアプリ側で対処できるようにします。これにより上流プロキシの
ヒックアップで Unexpected end of JSON input がアプリに届くこと
は実質ありません。