useGatelit

Import

import { useGatelit } from "@gatelit/sdk-vue"

Signature

function useGatelit(config: GatelitClientConfig): {
  messages:    Readonly<Ref<ChatMessageWithId[]>>
  isStreaming:  Readonly<Ref<boolean>>
  error:        Readonly<Ref<GatelitError | null>>
  send(userMessage: string, model: string, options?: Partial<ChatOptions>): Promise<void>
  stop(): void
  clear(): void
}

Configuration

useGatelit accepts a GatelitClientConfig object — the same configuration used by the core JS SDK.

string

required

Base URL of your deployed Gatelit gateway, e.g. "https://gateway.yourapp.com".

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

required

Called before each request to obtain a fresh auth token. Return the token string and the authentication scheme:

Scheme	When to use
`"GatelitSigned"`	Backend-issued HMAC signed token (recommended for client apps)
`"Bearer"`	OIDC token from Clerk, Supabase, Auth0, etc.
`"GatelitKey"`	Long-lived service key (backend-to-backend only)

Implement token caching inside this function to avoid a fetch on every message.

Returned values

Reactive state

All state properties are readonly refs — mutate them only through the provided functions.

Readonly<Ref<ChatMessageWithId[]>>

The full conversation history in chronological order. Each entry is a ChatMessageWithId:

Show ChatMessageWithId

string

Unique identifier generated client-side (msg_<random>). Stable across re-renders — use as the :key in v-for.

"user" | "assistant" | "system"

The author of the message.

string

The message text. For assistant messages, this grows incrementally while isStreaming is true.

Readonly<Ref<boolean>>

true while an assistant response is being streamed. send() is a no-op when this is true.

Readonly<Ref<GatelitError | null>>

The last error, or null if no error has occurred (or after clear() is called). A GatelitError has three properties:

Show GatelitError

string

Machine-readable error code, e.g. "unauthorized", "provider_error", "gateway_error".

string

Human-readable description of the error.

number

HTTP status code returned by the gateway.

Functions

(userMessage: string, model: string, options?: Partial<ChatOptions>) => Promise<void>

Appends the user message to messages, opens a streaming request, and appends a live-updating assistant message.

Does nothing if isStreaming is already true.
Clears error before each new request.
If the stream is aborted via stop(), no error is set — the partial assistant message is kept if it contains any content; an empty assistant placeholder is removed.
If the stream fails with a GatelitError, error is populated.

Parameters:

Name	Type	Description
`userMessage`	`string`	The user’s message text.
`model`	`string`	Model in `"provider/model-name"` format, e.g. `"openai/gpt-4o"`.
`options`	`Partial<ChatOptions>`	Optional overrides: `maxTokens`, `temperature`, `outputSchema`, `promptId`. Cannot override `messages`, `model`, or `signal` (those are managed internally).

() => void

Aborts the current stream by calling AbortController.abort(). isStreaming returns to false. Any content streamed so far is kept in messages.

() => void

Clears all messages and resets error to null. If a stream is in progress, it is aborted first.

Examples

Full chat interface

A complete Vue SFC with message history, a streaming indicator, error display, and stop button.

<script setup lang="ts">
import { ref } from "vue"
import { useGatelit } from "@gatelit/sdk-vue"

const input = ref("")

const { messages, isStreaming, error, send, stop, clear } = useGatelit({
  gatewayUrl: "https://gateway.yourapp.com",
  getToken: async () => {
    const res = await fetch("/api/ai-token").then((r) => r.json())
    return { token: res.token, scheme: "GatelitSigned" }
  },
})

async function handleSend() {
  const text = input.value.trim()
  if (!text) return
  input.value = ""
  await send(text, "openai/gpt-4o")
}
</script>

<template>
  <div class="messages">
    <div
      v-for="msg in messages"
      :key="msg.id"
      :class="['message', msg.role]"
    >
      <strong>{{ msg.role }}</strong>
      <p>{{ msg.content }}</p>
    </div>
  </div>

  <div v-if="error" class="error">
    {{ error.message }} ({{ error.code }})
  </div>

  <div class="controls">
    <input v-model="input" @keydown.enter="handleSend" :disabled="isStreaming" />
    <button @click="handleSend" :disabled="isStreaming">Send</button>
    <button v-if="isStreaming" @click="stop">Stop</button>
    <button @click="clear">Clear</button>
  </div>
</template>

The assistant message object is replaced in the array on every chunk (to trigger Vue’s reactivity system), so :key="msg.id" ensures the DOM node is reused rather than recreated. Always bind id as the key.

Usage with Nuxt

In a Nuxt application, use $fetch (provided by Nuxt’s runtime) inside getToken to call your server route:

<script setup lang="ts">
import { useGatelit } from "@gatelit/sdk-vue"

const { messages, isStreaming, error, send, stop } = useGatelit({
  gatewayUrl: useRuntimeConfig().public.gatewayUrl,
  getToken: async () => {
    const res = await $fetch<{ token: string }>("/api/ai-token")
    return { token: res.token, scheme: "GatelitSigned" }
  },
})
</script>

Your server/api/ai-token.ts route signs and returns a short-lived token using signToken from @gatelit/sdk.

JavaScript SDK

Vue SDK

Gateway API

Import

Signature

Configuration

Returned values

Reactive state

Functions

Examples

Full chat interface

Usage with Nuxt

​Import

​Signature

​Configuration

​Returned values

​Reactive state

​Functions

​Examples

​Full chat interface

​Usage with Nuxt

Import

Signature

Configuration

Returned values

Reactive state

Functions

Examples

Full chat interface

Usage with Nuxt