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

# GatelitClient

> Full reference for the GatelitClient class — the main entry point for sending AI requests through the Gatelit gateway.

`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

```typescript theme={null}
import { GatelitClient } from "@gatelit/sdk"

const client = new GatelitClient(config: GatelitClientConfig)
```

<ParamField body="gatewayUrl" type="string" required>
  Base URL of your deployed Gatelit gateway. For example: `"https://gateway.yourapp.com"`.
</ParamField>

<ParamField body="getToken" type="() => 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) |
</ParamField>

### Example

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

```typescript theme={null}
async chat(options: ChatOptions): Promise<ChatResponse>
```

#### Options

<ParamField body="model" type="string" required>
  Model in `"provider/model-name"` format. For example: `"openai/gpt-4o"` or `"anthropic/claude-3-5-sonnet-20241022"`.
</ParamField>

<ParamField body="messages" type="ChatMessage[]" required>
  Array of messages in the conversation. Each message has a `role` (`"system"`, `"user"`, or `"assistant"`) and a `content` string.
</ParamField>

<ParamField body="maxTokens" type="number">
  Maximum number of tokens to generate in the response.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature. Higher values produce more varied output.
</ParamField>

<ParamField body="outputSchema" type="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.
</ParamField>

<ParamField body="promptId" type="string">
  Links this request to a saved prompt in the dashboard for log correlation.
</ParamField>

<ParamField body="signal" type="AbortSignal">
  An `AbortSignal` to cancel the in-flight request.
</ParamField>

#### Returns: `ChatResponse`

<ResponseField name="content" type="string" required>
  The assistant's response text.
</ResponseField>

<ResponseField name="model" type="string" required>
  Resolved model identifier in `"provider/model-name"` format. May differ from the requested model if a fallback was triggered.
</ResponseField>

<ResponseField name="usage" type="Usage | null">
  Token usage for the request.

  <Expandable title="Usage properties">
    <ResponseField name="inputTokens" type="number">
      Number of tokens in the input (prompt).
    </ResponseField>

    <ResponseField name="outputTokens" type="number">
      Number of tokens in the output (completion).
    </ResponseField>

    <ResponseField name="totalTokens" type="number">
      Total tokens consumed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="finishReason" type="string | null">
  The reason the model stopped generating. Common values: `"stop"`, `"length"`, `"content_filter"`.
</ResponseField>

<ResponseField name="meta" type="GatelitMeta">
  Gatelit-specific metadata.

  <Expandable title="GatelitMeta properties">
    <ResponseField name="requestId" type="string">
      Gatelit request ID. Use this to look up the request in the dashboard logs.
    </ResponseField>

    <ResponseField name="model" type="string">
      Resolved model that handled the request.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example

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

```typescript theme={null}
async chatJson<T = unknown>(options: ChatOptions): Promise<T>
```

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

#### Example

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

```typescript theme={null}
async *stream(options: ChatOptions): AsyncGenerator<StreamChunk>
```

Accepts the same options as [`chat()`](#chat-options).

#### Returns: `AsyncGenerator<StreamChunk>`

<ResponseField name="delta" type="string" required>
  Incremental text produced by this chunk. Empty string on the final (usage) chunk.
</ResponseField>

<ResponseField name="model" type="string | undefined">
  Resolved model identifier. May be `undefined` on early chunks.
</ResponseField>

<ResponseField name="finishReason" type="string | null">
  Non-null on the final chunk. Common values: `"stop"`, `"length"`.
</ResponseField>

<ResponseField name="usage" type="Usage | null">
  Token usage — only present on the final chunk.

  <Expandable title="Usage properties">
    <ResponseField name="inputTokens" type="number">
      Number of tokens in the input (prompt).
    </ResponseField>

    <ResponseField name="outputTokens" type="number">
      Number of tokens in the output (completion).
    </ResponseField>

    <ResponseField name="totalTokens" type="number">
      Total tokens consumed.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example

```typescript theme={null}
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`](/sdk/conversation) tied to this client. The conversation accumulates the full message history and sends it with each request automatically.

```typescript theme={null}
conversation(options: ConversationOptions): Conversation
```

<ParamField body="model" type="string" required>
  Model in `"provider/model-name"` format.
</ParamField>

<ParamField body="systemPrompt" type="string">
  Optional system prompt prepended to every request.
</ParamField>

<ParamField body="maxTokens" type="number">
  Maximum output tokens per request.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature applied to every request in the conversation.
</ParamField>

See the [`Conversation` reference](/sdk/conversation) for the full API.

#### Example

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

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

<ResponseField name="code" type="string">
  Machine-readable error code returned by the gateway. For example: `"unauthorized"`, `"gateway_error"`, `"provider_error"`, `"invalid_json"`. See the [Errors reference](/api/errors) for the full list.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable error description.
</ResponseField>

<ResponseField name="status" type="number">
  HTTP status code from the gateway response.
</ResponseField>