Safeguard Docs
Safeguard AI SDKs

TypeScript reference

API reference for @safeguard-sh/sdk, the Safeguard AI SDK for Node.js and TypeScript.

TypeScript reference

Package @safeguard-sh/sdk, version 0.1.0. ESM and CommonJS, Node 18 or newer. Property names are camelCase; the SDK converts the API's snake_case.

import { Safeguard, SafeguardError, isEvent, VERSION } from "@safeguard-sh/sdk";

new Safeguard(options?)

OptionTypeDefault
apiKeystringprocess.env.SAFEGUARD_API_KEY. Throws SafeguardError with code MISSING_API_KEY if neither is set.
baseUrlstringhttps://api.safeguard.sh/gpt/v1/ai
productIdstringnone. Used by create and query when a call names no product.
timeoutMsnumber120000. 0 disables it.
maxRetriesnumber2. 0 disables retries.
fetchtypeof fetchthe global fetch

The key is held privately, so it does not appear in console.log(client). Properties: baseUrl, productId, conversations.

Methods

MethodReturns
context(opts?)Promise<Context>
query(prompt, opts?)Promise<QueryResult>
stream(prompt, opts?)SafeguardStream
conversations.create(opts?)Promise<Conversation>; opts: title, productId
conversations.list(opts?)Promise<ConversationPage>; opts: limit (1 to 100), offset
conversations.listAll(opts?)AsyncGenerator<Conversation>; opts: pageSize (1 to 100, default 50)
conversations.get(id, opts?)Promise<Conversation>
conversations.messages(id, opts?)Promise<MessagePage>; opts: limit, offset

Every opts also takes signal?: AbortSignal. query and stream options: conversationId, productId, model, signal.

SafeguardStream

Async-iterable of StreamEvent, iterated once. result() reads to the end and returns a QueryResult; finalAnswer() returns the answer text. Both throw SafeguardError if the stream carried an error event or ended without a final answer (STREAM_INCOMPLETE).

Types

interface Context { tenantId: string; orgId: string; userId: string; email: string | null;
  productId: string | null; products: { id: string; name: string | null }[]; scopes: string[] }
interface Conversation { id: string; title: string | null; messageCount: number | null;
  createdAt: string | null; updatedAt: string | null }
interface ConversationPage { conversations: Conversation[]; total: number }
interface Message { id: string; createdAt: string | null; prompt: string; answer: string }
interface MessagePage { messages: Message[]; total: number }
interface QueryResult { conversationId: string; queryId: string | null; answer: string; model: string | null }

type StreamEvent =
  | { type: "start"; conversationId: string; sessionId: string | null }
  | { type: "thinking"; content: string }
  | { type: "tool"; name: string; status: "started" | "completed" }
  | { type: "final"; conversationId: string; queryId: string | null; answer: string }
  | { type: "error"; code: string; message: string }
  | { type: "done" }
  | { type: string; raw: unknown };   // an event type this version does not know

isEvent(ev, "final") narrows a StreamEvent to one known type.

SafeguardError

FieldMeaning
statusHTTP status, or 0 when no response arrived
codeAPI code (for example RATE_LIMITED) or client code (TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE, STREAM_INCOMPLETE, MISSING_API_KEY)
messageText from the API
retryAfterSeconds from Retry-After, else null
requestIdThe server's request id, else null

A call you abort rejects with the signal's reason. Bad arguments (empty prompt, limit outside 1 to 100) throw TypeError or RangeError before any request. See Errors and retries.

On this page