API reference
Every symbol the SDK exports, by entry.
The published surface, checked against the package's own export lists on every build — nothing here can drift from what @oprag/sdk actually exports. Each symbol also carries TSDoc with examples, so your editor shows the same thing on hover.
@oprag/sdk
| Symbol | Kind | Signature | Summary |
|---|---|---|---|
createClient | function | createClient(options: CreateClientOptions): OpragClient | Creates the typed client for chat, leads, and escalation. Throws OpragConfigError if given an sk_* key in a browser. |
isBrowser | function | isBrowser(): boolean | True in a browser, false in Node. A Node process with a DOM shim counts as not-a-browser, because it checks process.versions.node too. |
citationDisplayLabel | function | citationDisplayLabel(source: CitationSource): string | Formats one citation for display, picking the best of title, document title, and location and appending a page number when there is one. |
statusToCode | function | statusToCode(status: number): string | undefined | Maps an HTTP status to the SDK's client-side error code. undefined for statuses the SDK does not name. |
OpragError | class | class OpragError extends Error { status: number; code?: string } | The API refused a request. status is what came back; code is derived client-side from it. |
OpragConfigError | class | class OpragConfigError extends Error | The SDK was configured in a way that cannot work — most often an sk_* key in browser code. No request was sent. |
CreateClientOptions | type | { apiUrl: string; apiKey: string } | What createClient takes: the environment's API base URL and a key. |
OpragClient | type | { chat: {...}; leads: {...}; conversations: {...} } | The client's three namespaces. |
ChatInput | type | { question: string; sessionId?: string; conversationId?: string; visitorId?: string } | One turn. Echo the ids back from the previous response to keep context. |
ChatAskOptions | type | { signal?: AbortSignal } | Per-call options for chat.ask. |
ChatStreamOptions | type | { onToken?: (token, accumulated) => void; onSources?: (sources) => void; signal?: AbortSignal } | Callbacks for chat.stream. onToken gets the accumulated text as well, so the UI needs no buffer of its own. |
ChatResponse | type | { type: "answer"; ... } | { type: "lead_capture_prompt"; ... } | A discriminated union. Branch on type — the lead-capture branch has no answer field. |
CitationSource | type | { documentTitle?; excerpt?; location?; pageNumber?; score?; title? } — every field optional | One passage an answer was grounded in. Render it with citationDisplayLabel. |
LeadCreateInput | type | { projectId: string; visitorId: string; name?; email?; conversationId?; sourceQuestion? } | What leads.create takes. |
@oprag/sdk/widget
Browser only. Importing this entry on a server throws.
| Symbol | Kind | Signature | Summary |
|---|---|---|---|
mountWidget | function | mountWidget(options: MountWidgetOptions): Promise<WidgetHandle> | Mounts the chat widget and resolves with its handle. Rejects an sk_* key. Only one widget is active at a time. |
MountWidgetOptions | type | { projectId; embedKey; apiUrl; target?; launcher?; theme?; onReady?; onOpen?; onClose?; onLead?; onEscalate?; onError? } | Everything mountWidget accepts. |
WidgetHandle | type | { open(); close(); toggle(); isOpen(); sendMessage(text); abort(); destroy() } | Control surface for a mounted widget. |
WidgetTheme | type | { primaryColor: string; position: "bottom-right" | "bottom-left"; mode?: "auto" | "light" | "dark" } | Theme override, merged over whatever the project's widget config already sets. |
Ready to ship?
Get started free