GatelitClient

GatelitClient routes chat requests to any model through your Gatelit gateway. The gateway handles provider routing, authentication, policy enforcement, spend tracking, and logging. Your client only needs a model name and messages.

Constructor

import { GatelitClient } from "@gatelit/sdk"

const client = new GatelitClient(config: GatelitClientConfig)

string

required

Base URL of your deployed Gatelit gateway. For example: "https://gateway.yourapp.com".

() => Promise<{ token: string; scheme: TokenScheme }>

required

Called before each request to retrieve a fresh auth token. Return an object with a token string and a scheme value.Cache the token internally and only re-fetch when it is close to expiry to avoid unnecessary round-trips.scheme accepts one of three values:

Value	Auth type
`"Bearer"`	OIDC token (Clerk, Supabase, Auth0)
`"GatelitSigned"`	Backend-issued HMAC-signed token
`"GatelitKey"`	Long-lived service key (backend-to-backend)

Example

const client = new GatelitClient({
  gatewayUrl: "https://gateway.yourapp.com",
  getToken: async () => {
    const { token } = await fetch("/api/ai-token").then(r => r.json())
    return { token, scheme: "GatelitSigned" }
  },
})

Methods

`chat(options)`

Sends a chat request and returns the full response once the model finishes.

async chat(options: ChatOptions): Promise<ChatResponse>

Options

string

required

Model in "provider/model-name" format. For example: "openai/gpt-4o" or "anthropic/claude-3-5-sonnet-20241022".

ChatMessage[]

required

Array of messages in the conversation. Each message has a role ("system", "user", or "assistant") and a content string.

number

Maximum number of tokens to generate in the response.

number

Sampling temperature. Higher values produce more varied output.

object

Structured output configuration. Use { mode: "json_object" } to instruct the model to return valid JSON of any shape, or { mode: "json_schema", ... } to constrain the output to a specific schema.

string

Links this request to a saved prompt in the dashboard for log correlation.

AbortSignal

An AbortSignal to cancel the in-flight request.

Returns: `ChatResponse`

string

required

The assistant’s response text.

string

required

Resolved model identifier in "provider/model-name" format. May differ from the requested model if a fallback was triggered.

Usage | null

Token usage for the request.

Show Usage properties

number

Number of tokens in the input (prompt).

number

Number of tokens in the output (completion).

number

Total tokens consumed.

string | null

The reason the model stopped generating. Common values: "stop", "length", "content_filter".

GatelitMeta

Gatelit-specific metadata.

Show GatelitMeta properties

string

Gatelit request ID. Use this to look up the request in the dashboard logs.

string

Resolved model that handled the request.

Example

const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
})

console.log(response.content)
console.log(response.usage?.totalTokens)
console.log(response.meta.requestId)

`chatJson<T>(options)`

Like chat(), but parses the response content as JSON and returns it as type T. Pair with outputSchema: { mode: "json_object" } or mode: "json_schema" to instruct the model to return valid JSON.

async chatJson<T = unknown>(options: ChatOptions): Promise<T>

Accepts the same options as chat(). Throws a GatelitError with code "invalid_json" if the model returns content that cannot be parsed.

Example

const result = await client.chatJson<{ score: number; reason: string }>({
  model: "openai/gpt-4o",
  messages: [
    { role: "user", content: "Rate this product review on a scale of 1-10 and explain why." },
  ],
  outputSchema: { mode: "json_object" },
})

console.log(result.score, result.reason)

`stream(options)`

Sends a chat request and returns an async generator that yields incremental StreamChunk values as the model produces output.

async *stream(options: ChatOptions): AsyncGenerator<StreamChunk>

Accepts the same options as chat().

Returns: `AsyncGenerator<StreamChunk>`

string

required

Incremental text produced by this chunk. Empty string on the final (usage) chunk.

string | undefined

Resolved model identifier. May be undefined on early chunks.

string | null

Non-null on the final chunk. Common values: "stop", "length".

Usage | null

Token usage — only present on the final chunk.

Show Usage properties

number

Number of tokens in the input (prompt).

number

Number of tokens in the output (completion).

number

Total tokens consumed.

Example

const messages = [{ role: "user", content: "Write a short poem about the sea." }]

let fullText = ""
for await (const chunk of client.stream({ model: "openai/gpt-4o", messages })) {
  fullText += chunk.delta
  process.stdout.write(chunk.delta)

  if (chunk.usage) {
    console.log("\ntokens:", chunk.usage.totalTokens)
  }
}

`conversation(options)`

Creates a Conversation tied to this client. The conversation accumulates the full message history and sends it with each request automatically.

conversation(options: ConversationOptions): Conversation

string

required

Model in "provider/model-name" format.

string

Optional system prompt prepended to every request.

number

Maximum output tokens per request.

number

Sampling temperature applied to every request in the conversation.

See the Conversation reference for the full API.

Example

const conv = client.conversation({
  model: "openai/gpt-4o",
  systemPrompt: "You are a helpful travel assistant.",
})

const r1 = await conv.send("What is the capital of France?")
const r2 = await conv.send("What is a good time of year to visit?")

console.log(conv.messages) // full history of all turns

Error handling

All methods throw GatelitError when the gateway returns a non-2xx response.

import { GatelitError } from "@gatelit/sdk"

try {
  const response = await client.chat({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  })
} catch (err) {
  if (err instanceof GatelitError) {
    console.error(err.code)    // machine-readable error code
    console.error(err.message) // human-readable description
    console.error(err.status)  // HTTP status code
  }
}

string

Machine-readable error code returned by the gateway. For example: "unauthorized", "gateway_error", "provider_error", "invalid_json". See the Errors reference for the full list.

string

Human-readable error description.

number

HTTP status code from the gateway response.

JavaScript SDK

Vue SDK

Gateway API

Constructor

Example

Methods

`chat(options)`

Options

Returns: `ChatResponse`

Example

`chatJson<T>(options)`

Example

`stream(options)`

Returns: `AsyncGenerator<StreamChunk>`

Example

`conversation(options)`

Example

Error handling

​Constructor

​Example

​Methods

​chat(options)

​Options

​Returns: ChatResponse

​Example

​chatJson<T>(options)

​Example

​stream(options)

​Returns: AsyncGenerator<StreamChunk>

​Example

​conversation(options)

​Example

​Error handling

Constructor

Example

Methods

`chat(options)`

Options

Returns: `ChatResponse`

Example

`chatJson<T>(options)`

Example

`stream(options)`

Returns: `AsyncGenerator<StreamChunk>`

Example

`conversation(options)`

Example

Error handling