@laintern/chat-sdk 0.1.0

package/dist/conversation-7VzVDT95.d.cts

@@ -0,0 +1,284 @@
+type ContentType = "forum_topic" | "article";
+interface SearchResult {
+    content_id: string;
+    content_type: ChatContentType;
+    title: string;
+    url: string;
+    imageUrl?: string | null;
+    similarity: number;
+    snippet?: string;
+    reply_count?: number;
+    author_first_name?: string;
+    /** ISO 8601 — forum: topic created_at; article: updated_at_source or created_at (for display/sort) */
+    posted_at?: string;
+    /** Kennisbank articles only */
+    read_time_minutes?: number;
+    /**
+     * Where inside the source this result sits — e.g. a `kb_chunk`'s heading
+     * path ("Traject › Aanmelden"). Lets a citation name the passage, not just
+     * the document. Absent for whole-document sources.
+     */
+    section?: string;
+}
+/**
+ * What a chat citation can point at. `kb_chunk` is a passage from the chunked
+ * knowledge base: it has no public URL, so consumers must render it as a
+ * non-navigable source (document title + `section`) rather than a link.
+ */
+type ChatContentType = ContentType | "medical_web" | "kb_chunk";
+interface CitationSource {
+    source_id: string;
+    title: string;
+    url: string;
+    content_type: ChatContentType;
+    /** Passage location within the source (see {@link SearchResult.section}). */
+    section?: string;
+}
+type StepEvent = {
+    status: "started";
+    tool: string;
+} | {
+    status: "completed";
+    tool: string;
+    count?: number;
+};
+type ExternalSourceType = ContentType;
+interface ExternalSourcesEvent {
+    type: "external_sources";
+    source_type: ExternalSourceType;
+    items: SearchResult[];
+}
+/**
+ * Where the medical input guardrail wants to point the user.
+ * - `112` / `113` are HARD blocks: the agent does not respond.
+ * - `huisarts` / `huisartsenpost` / `null` are SOFT advisories: the agent
+ *   responds normally and the widget shows a less-invasive notice.
+ */
+type GuardrailRedirect = "112" | "113" | "huisarts" | "huisartsenpost" | null;
+type ChatStreamEvent = {
+    type: "session";
+    session_id: string;
+} | {
+    type: "mode";
+    mode: "search" | "medical";
+} | {
+    type: "step";
+    step: StepEvent;
+} | {
+    type: "delta";
+    content: string;
+} | {
+    type: "citation";
+    index: number;
+    source: CitationSource;
+} | {
+    type: "sources";
+    items: SearchResult[];
+} | ExternalSourcesEvent
+/**
+ * Soft guardrail notice emitted alongside a normal agent response. The
+ * widget renders this as an unobtrusive info bar; the assistant message
+ * itself still streams as usual. Hard blocks stay on the `error` event
+ * with code `GUARDRAIL_TRIGGERED`.
+ */
+ | {
+    type: "advisory";
+    redirect: Exclude<GuardrailRedirect, "112" | "113">;
+    message: string;
+} | {
+    type: "done";
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+    message_id?: string;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+    guardrail_slug?: string;
+};
+
+/**
+ * Refresh this long before a token expires. It mirrors the margin the API
+ * applies when it clamps a chat token to a credential inside it: the server
+ * guarantees the token dies *after* the credential's own refresh point, and
+ * this buffer is what makes the client come back in time to use that.
+ */
+declare const DEFAULT_REFRESH_BUFFER_MS = 60000;
+interface TokenResponse {
+    token: string;
+    /** ISO-8601 or epoch ms, if the endpoint reports one. */
+    expiresAt?: string | number | null;
+}
+/** Minimal storage surface — `sessionStorage`, `localStorage` or your own. */
+interface TokenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface TokenManagerOptions {
+    /**
+     * Fetches a fresh token from YOUR backend. This is the one integration
+     * point that cannot be generic: only your server may hold the API key that
+     * mints Laintern tokens, and only it knows who the current user is.
+     */
+    fetchToken: () => Promise<TokenResponse | string>;
+    storage?: TokenStorage | null;
+    storageKey?: string;
+    refreshBufferMs?: number;
+    onWarning?: (message: string, detail?: Record<string, unknown>) => void;
+}
+interface TokenManager {
+    /** Cached token when still valid, otherwise a freshly fetched one. */
+    get(): Promise<string>;
+    /** Drop the cached token — the next `get()` fetches. */
+    clear(): void;
+    /** Expiry of the cached token, in epoch ms. Null when nothing is cached. */
+    expiresAt(): number | null;
+}
+/** Read a JWT's `exp` claim (epoch ms) without verifying the signature. */
+declare function decodeJwtExpiryMs(token: string): number | null;
+/**
+ * Caches the chat token and refreshes it before it dies.
+ *
+ * Concurrent callers share one in-flight fetch: a page that opens a stream
+ * while another request is already refreshing must not mint two sessions.
+ */
+declare function createTokenManager(options: TokenManagerOptions): TokenManager;
+
+interface LainternClientOptions {
+    /** Base URL of the Laintern API, e.g. "https://api.laintern.com". */
+    apiBase: string;
+    /**
+     * How to get a chat token. Either your own function, or the URL of an
+     * endpoint on your backend that returns `{ token, expires_at }`.
+     *
+     * Never put a Laintern API key in the browser: the key mints tokens for any
+     * user, so it belongs on your server, behind your own session check.
+     */
+    token: TokenManagerOptions["fetchToken"] | {
+        endpoint: string;
+        init?: RequestInit;
+    };
+    storage?: TokenManagerOptions["storage"];
+    refreshBufferMs?: number;
+    onWarning?: TokenManagerOptions["onWarning"];
+    /** Injectable for tests and non-browser runtimes. */
+    fetch?: typeof globalThis.fetch;
+}
+interface SendMessageOptions {
+    /** Continues an existing conversation. Omit to start a new one. */
+    sessionId?: string | null;
+    /** Base64 data URLs, for agents with image input enabled. */
+    images?: string[];
+    /** Force a specific tool on this turn, when the agent allows it. */
+    forceTool?: string;
+    signal?: AbortSignal;
+}
+interface AgentConfig {
+    /** Transparency notice to show before the conversation starts (EU AI Act). */
+    disclaimer: {
+        enabled: boolean;
+        text: string | null;
+    };
+}
+interface LainternClient {
+    /**
+     * Send one message and iterate the response as it streams.
+     *
+     * Yields typed events (`delta`, `citation`, `sources`, `step`, `done`, …).
+     * Prefer {@link createConversation} unless you want to assemble the turn
+     * yourself.
+     */
+    sendMessage(message: string, options?: SendMessageOptions): AsyncGenerator<ChatStreamEvent>;
+    /** Per-agent presentation config. Best-effort: throws on transport errors. */
+    getConfig(): Promise<AgentConfig>;
+    submitFeedback(messageId: string, feedback: "positive" | "negative"): Promise<void>;
+    /** The token cache, exposed so a host can clear it on logout. */
+    tokens: TokenManager;
+}
+declare function createLainternClient(options: LainternClientOptions): LainternClient;
+
+/** Soft advisory alongside an answer — the agent flagged the topic, but answered. */
+interface TurnAdvisory {
+    redirect: string | null;
+    message: string;
+}
+/** A guardrail refused the turn. The agent produced no answer. */
+interface TurnBlock {
+    /** Which guardrail fired, when the server names one. */
+    slug: string | null;
+    /** Copy meant for the end user, written by the guardrail's configuration. */
+    message: string;
+}
+interface TurnError {
+    code: string;
+    message: string;
+    rateLimitScope?: "user" | "agent";
+    rateLimitWindow?: "minute" | "hour" | "day";
+}
+interface Turn {
+    id: string;
+    userMessage: string;
+    userImages?: string[];
+    assistantContent: string;
+    /** Citation number (the `[1]` in the text) → the source it points at. */
+    citations: Map<number, CitationSource>;
+    /** Everything the agent cited or consulted, in the order the server ranked it. */
+    sources: SearchResult[];
+    /** Sidebar suggestions per content type — not necessarily cited. */
+    externalSources: Partial<Record<ExternalSourceType, SearchResult[]>>;
+    mode: string | null;
+    steps: StepEvent[];
+    isStreaming: boolean;
+    error?: TurnError;
+    blocked?: TurnBlock;
+    advisory?: TurnAdvisory;
+    messageId?: string;
+    feedback?: "positive" | "negative" | null;
+}
+interface ConversationState {
+    turns: Turn[];
+    sessionId: string | null;
+    isStreaming: boolean;
+}
+interface SendOptions {
+    images?: string[];
+    forceTool?: string;
+}
+interface Conversation {
+    getState(): ConversationState;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: (state: ConversationState) => void): () => void;
+    /** Send a message and stream the answer into state. Never throws. */
+    send(message: string, options?: SendOptions): Promise<void>;
+    /** Stop the current stream. The partial answer stays in state. */
+    abort(): void;
+    /** Drop all turns and start a new server-side session on the next send. */
+    reset(): void;
+    setFeedback(turnId: string, feedback: "positive" | "negative"): Promise<void>;
+}
+interface ConversationOptions {
+    /** Resume an existing server-side session. */
+    sessionId?: string | null;
+    /** Restore turns from your own storage. */
+    initialTurns?: Turn[];
+    /** Called whenever the session id changes, so you can persist it. */
+    onSessionId?: (sessionId: string) => void;
+}
+/**
+ * Stateful conversation on top of {@link LainternClient}.
+ *
+ * Holds the turn list, applies each stream event to the turn in flight, and
+ * notifies subscribers. Framework-agnostic on purpose: the React binding in
+ * `@laintern/chat-sdk/react` is a thin `useSyncExternalStore` wrapper, and any
+ * other UI layer can subscribe the same way.
+ *
+ * `send()` never throws. A failed turn is part of the conversation — it lands
+ * on `turn.error` (or `turn.blocked` for a guardrail) so the UI can render it
+ * in place, which is what you want in a chat transcript.
+ */
+declare function createConversation(client: LainternClient, options?: ConversationOptions): Conversation;
+
+export { type AgentConfig as A, type ChatStreamEvent as C, DEFAULT_REFRESH_BUFFER_MS as D, type ExternalSourceType as E, type LainternClient as L, type SearchResult as S, type TokenManager as T, type ChatContentType as a, type CitationSource as b, type ContentType as c, type Conversation as d, type ConversationOptions as e, type ConversationState as f, type LainternClientOptions as g, type SendMessageOptions as h, type SendOptions as i, type StepEvent as j, type TokenManagerOptions as k, type TokenResponse as l, type TokenStorage as m, type Turn as n, type TurnAdvisory as o, type TurnBlock as p, type TurnError as q, createConversation as r, createLainternClient as s, createTokenManager as t, decodeJwtExpiryMs as u };

package/dist/conversation-7VzVDT95.d.ts

@@ -0,0 +1,284 @@
+type ContentType = "forum_topic" | "article";
+interface SearchResult {
+    content_id: string;
+    content_type: ChatContentType;
+    title: string;
+    url: string;
+    imageUrl?: string | null;
+    similarity: number;
+    snippet?: string;
+    reply_count?: number;
+    author_first_name?: string;
+    /** ISO 8601 — forum: topic created_at; article: updated_at_source or created_at (for display/sort) */
+    posted_at?: string;
+    /** Kennisbank articles only */
+    read_time_minutes?: number;
+    /**
+     * Where inside the source this result sits — e.g. a `kb_chunk`'s heading
+     * path ("Traject › Aanmelden"). Lets a citation name the passage, not just
+     * the document. Absent for whole-document sources.
+     */
+    section?: string;
+}
+/**
+ * What a chat citation can point at. `kb_chunk` is a passage from the chunked
+ * knowledge base: it has no public URL, so consumers must render it as a
+ * non-navigable source (document title + `section`) rather than a link.
+ */
+type ChatContentType = ContentType | "medical_web" | "kb_chunk";
+interface CitationSource {
+    source_id: string;
+    title: string;
+    url: string;
+    content_type: ChatContentType;
+    /** Passage location within the source (see {@link SearchResult.section}). */
+    section?: string;
+}
+type StepEvent = {
+    status: "started";
+    tool: string;
+} | {
+    status: "completed";
+    tool: string;
+    count?: number;
+};
+type ExternalSourceType = ContentType;
+interface ExternalSourcesEvent {
+    type: "external_sources";
+    source_type: ExternalSourceType;
+    items: SearchResult[];
+}
+/**
+ * Where the medical input guardrail wants to point the user.
+ * - `112` / `113` are HARD blocks: the agent does not respond.
+ * - `huisarts` / `huisartsenpost` / `null` are SOFT advisories: the agent
+ *   responds normally and the widget shows a less-invasive notice.
+ */
+type GuardrailRedirect = "112" | "113" | "huisarts" | "huisartsenpost" | null;
+type ChatStreamEvent = {
+    type: "session";
+    session_id: string;
+} | {
+    type: "mode";
+    mode: "search" | "medical";
+} | {
+    type: "step";
+    step: StepEvent;
+} | {
+    type: "delta";
+    content: string;
+} | {
+    type: "citation";
+    index: number;
+    source: CitationSource;
+} | {
+    type: "sources";
+    items: SearchResult[];
+} | ExternalSourcesEvent
+/**
+ * Soft guardrail notice emitted alongside a normal agent response. The
+ * widget renders this as an unobtrusive info bar; the assistant message
+ * itself still streams as usual. Hard blocks stay on the `error` event
+ * with code `GUARDRAIL_TRIGGERED`.
+ */
+ | {
+    type: "advisory";
+    redirect: Exclude<GuardrailRedirect, "112" | "113">;
+    message: string;
+} | {
+    type: "done";
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+    message_id?: string;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+    guardrail_slug?: string;
+};
+
+/**
+ * Refresh this long before a token expires. It mirrors the margin the API
+ * applies when it clamps a chat token to a credential inside it: the server
+ * guarantees the token dies *after* the credential's own refresh point, and
+ * this buffer is what makes the client come back in time to use that.
+ */
+declare const DEFAULT_REFRESH_BUFFER_MS = 60000;
+interface TokenResponse {
+    token: string;
+    /** ISO-8601 or epoch ms, if the endpoint reports one. */
+    expiresAt?: string | number | null;
+}
+/** Minimal storage surface — `sessionStorage`, `localStorage` or your own. */
+interface TokenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface TokenManagerOptions {
+    /**
+     * Fetches a fresh token from YOUR backend. This is the one integration
+     * point that cannot be generic: only your server may hold the API key that
+     * mints Laintern tokens, and only it knows who the current user is.
+     */
+    fetchToken: () => Promise<TokenResponse | string>;
+    storage?: TokenStorage | null;
+    storageKey?: string;
+    refreshBufferMs?: number;
+    onWarning?: (message: string, detail?: Record<string, unknown>) => void;
+}
+interface TokenManager {
+    /** Cached token when still valid, otherwise a freshly fetched one. */
+    get(): Promise<string>;
+    /** Drop the cached token — the next `get()` fetches. */
+    clear(): void;
+    /** Expiry of the cached token, in epoch ms. Null when nothing is cached. */
+    expiresAt(): number | null;
+}
+/** Read a JWT's `exp` claim (epoch ms) without verifying the signature. */
+declare function decodeJwtExpiryMs(token: string): number | null;
+/**
+ * Caches the chat token and refreshes it before it dies.
+ *
+ * Concurrent callers share one in-flight fetch: a page that opens a stream
+ * while another request is already refreshing must not mint two sessions.
+ */
+declare function createTokenManager(options: TokenManagerOptions): TokenManager;
+
+interface LainternClientOptions {
+    /** Base URL of the Laintern API, e.g. "https://api.laintern.com". */
+    apiBase: string;
+    /**
+     * How to get a chat token. Either your own function, or the URL of an
+     * endpoint on your backend that returns `{ token, expires_at }`.
+     *
+     * Never put a Laintern API key in the browser: the key mints tokens for any
+     * user, so it belongs on your server, behind your own session check.
+     */
+    token: TokenManagerOptions["fetchToken"] | {
+        endpoint: string;
+        init?: RequestInit;
+    };
+    storage?: TokenManagerOptions["storage"];
+    refreshBufferMs?: number;
+    onWarning?: TokenManagerOptions["onWarning"];
+    /** Injectable for tests and non-browser runtimes. */
+    fetch?: typeof globalThis.fetch;
+}
+interface SendMessageOptions {
+    /** Continues an existing conversation. Omit to start a new one. */
+    sessionId?: string | null;
+    /** Base64 data URLs, for agents with image input enabled. */
+    images?: string[];
+    /** Force a specific tool on this turn, when the agent allows it. */
+    forceTool?: string;
+    signal?: AbortSignal;
+}
+interface AgentConfig {
+    /** Transparency notice to show before the conversation starts (EU AI Act). */
+    disclaimer: {
+        enabled: boolean;
+        text: string | null;
+    };
+}
+interface LainternClient {
+    /**
+     * Send one message and iterate the response as it streams.
+     *
+     * Yields typed events (`delta`, `citation`, `sources`, `step`, `done`, …).
+     * Prefer {@link createConversation} unless you want to assemble the turn
+     * yourself.
+     */
+    sendMessage(message: string, options?: SendMessageOptions): AsyncGenerator<ChatStreamEvent>;
+    /** Per-agent presentation config. Best-effort: throws on transport errors. */
+    getConfig(): Promise<AgentConfig>;
+    submitFeedback(messageId: string, feedback: "positive" | "negative"): Promise<void>;
+    /** The token cache, exposed so a host can clear it on logout. */
+    tokens: TokenManager;
+}
+declare function createLainternClient(options: LainternClientOptions): LainternClient;
+
+/** Soft advisory alongside an answer — the agent flagged the topic, but answered. */
+interface TurnAdvisory {
+    redirect: string | null;
+    message: string;
+}
+/** A guardrail refused the turn. The agent produced no answer. */
+interface TurnBlock {
+    /** Which guardrail fired, when the server names one. */
+    slug: string | null;
+    /** Copy meant for the end user, written by the guardrail's configuration. */
+    message: string;
+}
+interface TurnError {
+    code: string;
+    message: string;
+    rateLimitScope?: "user" | "agent";
+    rateLimitWindow?: "minute" | "hour" | "day";
+}
+interface Turn {
+    id: string;
+    userMessage: string;
+    userImages?: string[];
+    assistantContent: string;
+    /** Citation number (the `[1]` in the text) → the source it points at. */
+    citations: Map<number, CitationSource>;
+    /** Everything the agent cited or consulted, in the order the server ranked it. */
+    sources: SearchResult[];
+    /** Sidebar suggestions per content type — not necessarily cited. */
+    externalSources: Partial<Record<ExternalSourceType, SearchResult[]>>;
+    mode: string | null;
+    steps: StepEvent[];
+    isStreaming: boolean;
+    error?: TurnError;
+    blocked?: TurnBlock;
+    advisory?: TurnAdvisory;
+    messageId?: string;
+    feedback?: "positive" | "negative" | null;
+}
+interface ConversationState {
+    turns: Turn[];
+    sessionId: string | null;
+    isStreaming: boolean;
+}
+interface SendOptions {
+    images?: string[];
+    forceTool?: string;
+}
+interface Conversation {
+    getState(): ConversationState;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: (state: ConversationState) => void): () => void;
+    /** Send a message and stream the answer into state. Never throws. */
+    send(message: string, options?: SendOptions): Promise<void>;
+    /** Stop the current stream. The partial answer stays in state. */
+    abort(): void;
+    /** Drop all turns and start a new server-side session on the next send. */
+    reset(): void;
+    setFeedback(turnId: string, feedback: "positive" | "negative"): Promise<void>;
+}
+interface ConversationOptions {
+    /** Resume an existing server-side session. */
+    sessionId?: string | null;
+    /** Restore turns from your own storage. */
+    initialTurns?: Turn[];
+    /** Called whenever the session id changes, so you can persist it. */
+    onSessionId?: (sessionId: string) => void;
+}
+/**
+ * Stateful conversation on top of {@link LainternClient}.
+ *
+ * Holds the turn list, applies each stream event to the turn in flight, and
+ * notifies subscribers. Framework-agnostic on purpose: the React binding in
+ * `@laintern/chat-sdk/react` is a thin `useSyncExternalStore` wrapper, and any
+ * other UI layer can subscribe the same way.
+ *
+ * `send()` never throws. A failed turn is part of the conversation — it lands
+ * on `turn.error` (or `turn.blocked` for a guardrail) so the UI can render it
+ * in place, which is what you want in a chat transcript.
+ */
+declare function createConversation(client: LainternClient, options?: ConversationOptions): Conversation;
+
+export { type AgentConfig as A, type ChatStreamEvent as C, DEFAULT_REFRESH_BUFFER_MS as D, type ExternalSourceType as E, type LainternClient as L, type SearchResult as S, type TokenManager as T, type ChatContentType as a, type CitationSource as b, type ContentType as c, type Conversation as d, type ConversationOptions as e, type ConversationState as f, type LainternClientOptions as g, type SendMessageOptions as h, type SendOptions as i, type StepEvent as j, type TokenManagerOptions as k, type TokenResponse as l, type TokenStorage as m, type Turn as n, type TurnAdvisory as o, type TurnBlock as p, type TurnError as q, createConversation as r, createLainternClient as s, createTokenManager as t, decodeJwtExpiryMs as u };