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?)
| Option | Type | Default |
|---|---|---|
apiKey | string | process.env.SAFEGUARD_API_KEY. Throws SafeguardError with code MISSING_API_KEY if neither is set. |
baseUrl | string | https://api.safeguard.sh/gpt/v1/ai |
productId | string | none. Used by create and query when a call names no product. |
timeoutMs | number | 120000. 0 disables it. |
maxRetries | number | 2. 0 disables retries. |
fetch | typeof fetch | the global fetch |
The key is held privately, so it does not appear in console.log(client). Properties: baseUrl, productId, conversations.
Methods
| Method | Returns |
|---|---|
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 knowisEvent(ev, "final") narrows a StreamEvent to one known type.
SafeguardError
| Field | Meaning |
|---|---|
status | HTTP status, or 0 when no response arrived |
code | API code (for example RATE_LIMITED) or client code (TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE, STREAM_INCOMPLETE, MISSING_API_KEY) |
message | Text from the API |
retryAfter | Seconds from Retry-After, else null |
requestId | The 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.