Skip to main content

TypeScript Gateway Quickstart

Use @keeptrusts/gateway when your code needs to send governed AI traffic through the Keeptrusts gateway without exposing privileged control-plane bearer tokens.

Use this page when​

  • You are integrating a browser app, edge function, or server service with the Keeptrusts gateway.
  • You need a browser-safe TypeScript package.
  • You want canonical x-keeptrusts-agent-id, x-request-id, and traceparent handling.

Install​

npm install @keeptrusts/gateway openai

Basic chat request​

import {
  buildKeeptrustsHeaders,
  createKeeptrustsGatewayClient,
  generateTraceparent,
} from "@keeptrusts/gateway";

const client = createKeeptrustsGatewayClient({
  baseUrl: "https://gateway.keeptrusts.example/v1",
  apiKey: "kt_live_...",
  agentId: "agent-support-web",
  defaultHeaders: buildKeeptrustsHeaders({
    requestId: crypto.randomUUID(),
    agentId: "agent-support-web",
    traceparent: generateTraceparent(),
  }),
});

const response = await client.chat.completions.create({
  model: "gpt-5.4-mini-mini",
  messages: [
    { role: "system", content: "Answer with approved support guidance only." },
    { role: "user", content: "Summarize today's agent escalations." },
  ],
});

console.log(response.choices[0]?.message?.content);

What the SDK is doing​

  • points your OpenAI-compatible request at the Keeptrusts gateway
  • uses an API token with purpose=general instead of a privileged bearer token
  • forwards canonical headers for attribution and tracing
  • stays browser-safe with no Node-only runtime dependency

Vercel AI SDK adapter pattern​

import { createOpenAI } from "@ai-sdk/openai";
import { keeptrustsGatewayProvider } from "@keeptrusts/gateway";
import { streamText } from "ai";

const provider = createOpenAI(
  keeptrustsGatewayProvider({
    baseUrl: "https://gateway.keeptrusts.example/v1",
    apiKey: "kt_live_...",
    agentId: "agent-support-web",
  }),
);

const result = streamText({
  model: provider("gpt-5.4-mini-mini"),
  messages: [{ role: "user", content: "Draft a customer-safe summary." }],
});

Header helper pattern​

Use the built-in helper to preserve the canonical header contract:

import { buildKeeptrustsHeaders, generateTraceparent } from "@keeptrusts/gateway";

const headers = buildKeeptrustsHeaders({
  requestId: crypto.randomUUID(),
  agentId: "agent-support-web",
  traceparent: generateTraceparent(),
});

This produces the standard Keeptrusts header set:

  • x-request-id
  • x-keeptrusts-agent-id
  • traceparent

Browser-safe rule​

@keeptrusts/gateway is the package to use in browser code because it only needs gateway-routing inputs:

  • base URL
  • API token issued for gateway request execution, typically purpose=general
  • optional request headers

Do not use this package to query privileged control-plane APIs from the browser. If you need events, evidence, or trail verification, call your own backend and use @keeptrusts/control-plane there. Do not reuse the hosted gateway runtime token from KEEPTRUSTS_API_TOKEN in browser clients.

Spend attribution rule​

Do not use wallet reads for request-level spend reporting in frontend code. Instead:

  1. send the governed request through the gateway
  2. persist x-request-id or the returned event correlation data
  3. query decision events server-side for event_cost_attribution

Troubleshooting​

I need to identify a specific agent​

Set agentId or pass x-keeptrusts-agent-id through buildKeeptrustsHeaders().

I need distributed tracing​

Generate or forward traceparent explicitly. The helper keeps the header shape consistent.

I need control-plane data too​

Split the flow:

  • browser or edge caller → @keeptrusts/gateway
  • backend worker or API route → @keeptrusts/control-plane

Next steps​

For AI systems​

  • Package: @keeptrusts/gateway.
  • Runtime: browser-safe, edge-safe, server-safe.
  • Canonical headers: x-keeptrusts-agent-id, x-request-id, traceparent.
  • Use API tokens with purpose=general; do not introduce privileged bearer tokens or hosted gateway runtime tokens into browser code.

For engineers​

  • Install @keeptrusts/gateway with openai.
  • Use createKeeptrustsGatewayClient() for OpenAI-compatible requests.
  • Use keeptrustsGatewayProvider() for Vercel AI SDK transport setup.
  • Query request spend from server-side event reads, not wallet APIs.