クライアント

クライアントは、createClient() が返すオブジェクトです。NodaroClient は、あなたのベース URL、認証プロバイダー、設定を保持し、client.workflows や client.nodes のように、Nodaro API のあらゆる部分をリソースとして公開します。クライアントは 1 回作成し、すべての呼び出しで再利用します。

クライアントを作成する

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  timeoutMs: 120_000,
})

createClient(options: ClientOptions): NodaroClient

NodaroClient はクラスとしてもエクスポートされているため、クライアントを受け取る関数の型を書けます。

import type { NodaroClient } from "@nodaro/sdk"

async function countWorkflows(client: NodaroClient, projectId: string) {
  const { data } = await client.workflows.list({ projectId })
  return data.length
}

クライアントのリソース

各リソースは createClient によって作成され、client.<resource> としてアクセスします。

クライアント自体には、さらに 3 つのメソッドがあります。me()、withWorkspace()、request() です。

メソッドが返すもの

• エンベロープはそのまま保たれます。エンドポイントが { "data": ... } で応答する場合、メソッドはそのエンベロープをそのまま返すため、const { data } = await client.workflows.get(id) のように書きます。ページ分割された一覧では、data の横に nextCursor のようなカーソルが加わります。
• 一部のリソースは、内容をそのまま返します。いくつかのメソッドは、レスポンスを展開して返します。たとえば client.characters.list() は { characters, nextCursor } を返し、client.credits.balance() は残高そのものを返します。正確な戻り値の型は、各リファレンスページに示されています。
• 削除とキャンセルは、通常 { success: true } を返します。
• フィールド名は、通信時の形式に従います。Job は、API がその形で送るため、output_data や created_at のような snake_case のフィールドを使います。Workflow と WorkflowExecution は camelCase を使います。

すべてのレスポンスと入力の型はエクスポートされているため、import type でインポートできます。型を参照してください。

me()

me(): Promise<UserIdentity & MeOrganizations>

現在のトークンの持ち主の情報を返します（GET /v1/me）。有効なトークンであれば、API トークン、OAuth アクセストークン、ブラウザーセッションのいずれであっても、その所有者を返します。トークンがない場合や無効な場合は、UnauthorizedError をスローします。

const me = await client.me()
console.log(me.email, me.tier)

組織機能のある Nodaro Cloud インスタンスでは、結果に organizations、workspaces、lastWorkspaceId、organizationsUnavailable も含まれます。この 3 つの状態は、それぞれ異なる扱いが必要です。

withWorkspace(workspaceId)

withWorkspace(workspaceId: string | null): NodaroClient

workspaceId で動作する新しいクライアントを返します。新しいクライアントは、元のクライアントの認証、ベース URL、タイムアウト、fetch を共有します。個人スペースを使うには null を渡します。

const classroom = client.withWorkspace(workspaceId)

await classroom.workflows.run(workflowId) // runs in the workspace
await client.workflows.run(workflowId)    // runs in the personal space

このメソッドは、現在のクライアントを変更するのではなく、新しいクライアントを返します。そのため、1 つのクライアントで同時に実行される 2 つの操作が、ワークスペースを取り違えることはありません。

ワークスペースが決めるのはスコープであって、アクセス権ではありません。一覧がどのワークスペースから読み取るか、新しいアイテムがどこに作られるかを決めます。ID で指定したアイテムの読み取り、変更、削除、実行は、そのアイテム自身のワークスペースによって決まります。ワークスペースの指定を忘れても自分の作業が見えなくなることはなく、間違ったワークスペースを指定しても、ほかの人の作業にアクセスすることはできません。

ワークスペースは、Nodaro Cloud の組織に属します。組織とワークスペースとワークスペースを参照してください。

request(method, path, options)

request<T>(method: string, path: string, options?: {
  body?: unknown
  query?: Record<string, string | number | boolean | undefined>
  headers?: Record<string, string>
  signal?: AbortSignal
}): Promise<T>

任意のエンドポイントにリクエストを送ります。まだリソースメソッドがない、ごく一部のエンドポイント向けです。あなたの認証ヘッダーとワークスペースを追加し、body を JSON として送信し、timeoutMs を適用して、リソースメソッドと同じ型付きエラーをスローします。

// The same request that client.jobs.list() sends
const page = await client.request<{ data: unknown[]; next: string | null }>("GET", "/v1/jobs", {
  query: { type: "llm-structured", limit: 20 },
})

FormData のボディは、マルチパートアップロードとして送信されます。undefined のクエリ値は除外されます。すべてのエンドポイントとそのフィールドは、REST API リファレンスに一覧があります。

タイムアウトと独自の fetch

timeoutMs は、上限（デフォルトは 60 秒）を超えたリクエストを中断します。ほとんどの生成は、妥当な HTTP タイムアウトよりも長くかかるため、生成を開始してジョブをポーリングしてください。client.nodes.runAndWait() は、その両方を代わりに行います。ストリーミングを行うメソッドである client.copilot.stream() と client.media.downloadVideoProgress() は、数分間開いたままになることを想定しているため、タイムアウトを適用しません。

独自の fetch を渡すと、リクエストの送り方を変えられます。

• テスト。モックから、用意した Response オブジェクトを返します。
• リトライ。グローバルな fetch を、5xx の応答でリトライするヘルパーでラップします。
• トレーシング。トレーシングやモニタリングのライブラリでラップします。

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  fetch: (input, init) => tracedFetch(input, init),
})

ランタイムとブラウザー

SDK が使うのは fetch と URL だけです。これらは、Node.js 20 以降、最新のブラウザー、React Native、Cloudflare Workers、Deno、Bun でグローバルに使えます。ポリフィルは必要ありません。

• OAuth トークンでの CORS。OAuth アクセストークンで Nodaro を呼び出すブラウザーアプリは、開発者アプリの allowedOrigins に登録されたオリジンで動作する必要があります。OAuth と開発者アプリを参照してください。
• セッションでの CORS。supabaseAuth を使うブラウザーアプリは、そのリストと照合されません。
• クライアントラベル。サーバーでは、SDK は X-Nodaro-Client: sdk/<version> を送信し、Nodaro はこれを各ジョブの発信元として記録します。ブラウザーでは、ブラウザーの Origin ヘッダーが既にあなたのアプリを示しているため、デフォルトのラベルは送信されません。自分で設定した clientLabel は、常に送信されます。