TypeScript API Reference

Required Configuration

All TypeScript snippets on this page use an API key that is validated at application startup:

const apiKey = process.env.JOY_TOKEN_API_KEY;
if (!apiKey) throw new Error("JOY_TOKEN_API_KEY is required");

Imports

import { JoyTokenClient, JoyTokenAPIError } from "@joytoken/client-sdk-ts";

JoyTokenClient

const joytoken = new JoyTokenClient({
  apiKey,
  apiBaseUrl: process.env.JOY_TOKEN_API_BASE_URL,
  timeoutMs: 60_000,
});

Model calls, model metadata and pricing require apiKey. If it is missing, the SDK throws a clear error before sending a request. models.list() is the only unauthenticated catalog method.

One JoyTokenClient exposes Chat Completions, Responses, and Anthropic-compatible Messages methods without a global protocol switch. Chat and Responses use the Gateway’s native OpenAI endpoints. Messages are converted locally and sent through Chat Completions.

Compatible API Methods

await joytoken.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello" }],
});

for await (const chunk of joytoken.chat.completions.stream({
  model: "auto",
  messages: [{ role: "user", content: "Hello" }],
})) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
}

const response = await joytoken.responses.create({
  model: "auto",
  input: "Explain JoyToken in one sentence.",
});
console.log(response.output?.[0]?.content?.[0]?.text);

for await (const event of joytoken.responses.stream({
  model: "auto",
  input: "Say hello",
})) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta ?? "");
  }
}

const image = await joytoken.images.generate({
  model: "auto",
  prompt: "A neon JoyToken logo on a black background",
  size: "1024x1024",
});
console.log(image.data[0]?.url ?? image.data[0]?.b64_json);

const edited = await joytoken.images.edit({
  model: "auto",
  image: "https://picsum.photos/512/512",
  prompt: "Add a neon JoyToken logo in the top-right corner",
  size: "1024x1024",
});
console.log(edited.data[0]?.url ?? edited.data[0]?.b64_json);

Tools

Client tool options

Tool execution methods

Primitive create and stream methods never execute request-level or Client-registered tools. create() may auto-run SDK defaults only when no user tool source exists.

chat.completions

responses

Responses methods send native flat tool declarations and preserve native output items and SSE events.

Response.output_text joins all output_text content. Tool loops append function_call_output input items. Hosted tools preserve their native Responses shape.

messages

Messages methods expose Anthropic-compatible inputs, outputs, tool_use blocks, and streaming events while sending Gateway requests through Chat Completions.

Anthropic tool_choice maps as follows:

Tool types and helpers

import {
  calculator,
  dateTime,
  defineTool,
  fileRead,
  fileSearch,
  fileWrite,
  listDir,
  shell,
  type Tool,
  type ToolCall,
  type ToolCallResult,
  type ToolRunStreamOptions,
} from "@joytoken/client-sdk-ts";

defineTool() returns the supplied tool unchanged and preserves generic types. A Tool has a name, optional description and JSON Schema parameters, plus an optional execute(input, context) handler.

ToolCall.extra_content?: Record<string, unknown> stores opaque provider extensions. The SDK preserves this field through non-streaming and streaming Chat continuations, Responses function_call items, Messages tool_use blocks, and tool handler context. Gemini thought_signature is one example; the type and forwarding behavior are provider-neutral.

When implementing a tool loop manually, reuse the complete returned ToolCall, Responses function_call, or Messages tool_use item. Do not reconstruct it from only id, name, and arguments.

const options: ToolRunStreamOptions = {
  onTextDelta: (delta) => process.stdout.write(delta),
  onToolResult: (result: ToolCallResult) => {
    console.log(result.tool_name, result.is_error);
  },
  onOrchestrationEvent: (event) => {
    if (event.type === "plan") console.log("plan", event.plan.length);
    else console.log("stage", event.task_id, event.final);
  },
};

Tool precedence

request.tools !== undefined
  → use exactly request.tools (including [])
  → explicit runner may use only matching Client handlers
else Client tools exist
  → use exactly Client tools
  → execute only through an explicit runner
else
  → inject SDK defaults
  → default automatic loop is allowed

Hosted Responses file_search requires a non-empty vector_store_ids; the SDK never creates IDs. Local function file_search uses { type: "function", name: "file_search", ... } and is a different tool.

models.list

const models = await joytoken.models.list({ locale: "en" });

Calls the unauthenticated GET /api/v1/models endpoint. Use { locale: "zh" } for Chinese descriptions. Omitting locale uses the API default of English. The SDK preserves the HTTP envelope, so catalog entries are in models.data.models.

models.meta

const metadata = await joytoken.models.meta();

Calls GET /api/v1/models/meta with the configured API key and returns tiers, SKUs, capability tags, industry packs, providers, and the catalog update time.

pricing.retrieve

const pricing = await joytoken.pricing.retrieve();

Calls GET /api/v1/pricing with the configured API key and returns customer-facing tier exchange pricing metadata.

Orchestration

When the gateway plans and runs multiple sub-tasks for a model: "auto" turn, the SDK aggregates the result instead of exposing a raw JSON payload.

import {
  ORCHESTRATION_FINAL_TASK_ID,
  type OrchestrationResult,
  type OrchestrationInfo,
  type OrchestrationEvent,
} from "@joytoken/client-sdk-ts";

Non-streaming create() still returns the final answer text in choices[0].message.content; the breakdown lives on orchestration. Streaming chunks include intermediate sub-task text, so filter on chunk.orchestration?.task_id === ORCHESTRATION_FINAL_TASK_ID to render only the reply, or use runStream whose onTextDelta already emits only final-answer text.

JoyTokenAPIError

try {
  await joytoken.chat.completions.create({
    model: "auto",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  if (error instanceof JoyTokenAPIError) {
    console.error(error.status, error.requestId, error.body);
  }
}

A failed orchestration run can arrive as an HTTP 200 response whose body or SSE stream carries an error envelope ({ "error": { ... }, "choices": [] }). The SDK detects this envelope on both non-streaming and streaming Chat paths and raises the same JoyTokenAPIError, with the gateway error object exposed on body.