@thaliq/sdk 1.0.0

package/types/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @thaliq/sdk - Error Types
+ * @module types/errors
+ */
+/**
+ * SDK error codes used in `ThaliqError.code`.
+ * Use these to programmatically distinguish error types.
+ */
+export type ErrorCode = 'AUTH_ERROR' | 'RATE_LIMIT' | 'VALIDATION_ERROR' | 'SERVICE_ERROR' | 'STREAM_ERROR' | 'TIMEOUT_ERROR' | 'CONNECTION_ERROR' | 'UNKNOWN_ERROR';
+/** Base error class for all SDK errors */
+export declare class ThaliqError extends Error {
+    readonly code: ErrorCode;
+    readonly status?: number;
+    constructor(message: string, code: ErrorCode, status?: number);
+}
+/** Authentication or authorization error (401/403) */
+export declare class AuthError extends ThaliqError {
+    constructor(message: string, status?: number);
+}
+/** Rate limit exceeded (429) */
+export declare class RateLimitError extends ThaliqError {
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter?: number);
+}
+/** Request validation error (400) */
+export declare class ValidationError extends ThaliqError {
+    constructor(message: string);
+}
+/** Service unavailable (503) */
+export declare class ServiceError extends ThaliqError {
+    constructor(message: string);
+}
+/** Error during SSE streaming */
+export declare class StreamError extends ThaliqError {
+    constructor(message: string);
+}
+/** Request timeout */
+export declare class TimeoutError extends ThaliqError {
+    constructor(message?: string);
+}
+/** Network/connection error */
+export declare class ConnectionError extends ThaliqError {
+    constructor(message?: string);
+}
+/**
+ * Maps an HTTP status code to the appropriate ThaliqError subclass.
+ * Used internally by the HTTP client; also useful for custom providers.
+ */
+export declare function mapHttpError(status: number, message: string, headers?: Headers): ThaliqError;

package/types/events.d.ts

@@ -0,0 +1,70 @@
+import { PendingAction } from './actions';
+import { Insight, ResponseMetadata } from './responses';
+/** Metadata event — sent first, carries the conversation ID */
+export interface MetaEvent {
+    type: 'meta';
+    conversationId: string;
+}
+/** Status update — shows progress text (e.g. "Thinking...") */
+export interface StatusEvent {
+    type: 'status';
+    text: string;
+}
+/** Content delta — incremental text chunk */
+export interface ContentDeltaEvent {
+    type: 'content.delta';
+    delta: string;
+}
+/** Tool execution started */
+export interface ToolStartEvent {
+    type: 'tool.start';
+    tool: string;
+}
+/** Tool execution ended */
+export interface ToolEndEvent {
+    type: 'tool.end';
+    tool: string;
+    success: boolean;
+}
+/** Action required — HITL event, stream pauses until user responds */
+export interface ActionEvent {
+    type: 'action';
+    action: PendingAction;
+}
+/** Stream completed — final event with full response data */
+export interface ResponseCompletedEvent {
+    type: 'response.completed';
+    message: string;
+    conversationId: string;
+    insights: Insight[];
+    metadata: ResponseMetadata;
+}
+/** Error during streaming */
+export interface ErrorEvent {
+    type: 'error';
+    message: string;
+}
+/** Keepalive ping — sent periodically to keep connection open */
+export interface KeepaliveEvent {
+    type: 'keepalive';
+    ts: number;
+}
+/**
+ * Discriminated union of all possible stream events.
+ * Use `event.type` in a switch statement for type narrowing.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of stream) {
+ *   switch (event.type) {
+ *     case 'content.delta':
+ *       process.stdout.write(event.delta);
+ *       break;
+ *     case 'tool.start':
+ *       console.log(`Running: ${event.tool}`);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamEvent = MetaEvent | StatusEvent | ContentDeltaEvent | ToolStartEvent | ToolEndEvent | ActionEvent | ResponseCompletedEvent | ErrorEvent | KeepaliveEvent;

package/types/identity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @thaliq/sdk - Identity Types
+ * @module types/identity
+ */
+/** User identity for authenticated B2B scenarios */
+export interface UserIdentity {
+    /** Unique user ID in the tenant's system */
+    userId: string;
+    /** User email (optional, for display/tracking) */
+    email?: string;
+    /** User display name (optional) */
+    name?: string;
+    /** JWT or bearer token (passthrough for MCP servers) */
+    token?: string;
+    /** Per-MCP-server tokens: { "server-id": "token" } */
+    mcpTokens?: Record<string, string>;
+    /** Participant ID for conversation tracking */
+    participantId?: string;
+    /** Arbitrary metadata attached to requests */
+    metadata?: Record<string, unknown>;
+}

package/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @thaliq/sdk - Type Exports
+ */
+export type { ThaliqConfig, ResolvedConfig, Logger, LogLevel, } from './config';
+export type { UserIdentity, } from './identity';
+export type { ActionType, RejectBehavior, FieldType, ActionOption, ActionField, PendingAction, ActionResponse, } from './actions';
+export type { InsightSeverity, InsightType, Insight, ResponseMetadata, ChatResponse, } from './responses';
+export type { StreamEvent, MetaEvent, StatusEvent, ContentDeltaEvent, ToolStartEvent, ToolEndEvent, ActionEvent, ResponseCompletedEvent, ErrorEvent, KeepaliveEvent, } from './events';
+export type { AgentType, ChatOptions, StreamOptions, AgentStream, } from './agent';
+export type { ConversationRef, } from './conversations';
+export type { ErrorCode, } from './errors';
+export { ThaliqError, AuthError, RateLimitError, ValidationError, ServiceError, StreamError, TimeoutError, ConnectionError, mapHttpError, } from './errors';
+export type { Provider, ProviderRequest, ResolvedHeaders, } from './provider';

package/types/provider.d.ts

@@ -0,0 +1,52 @@
+import { ActionResponse } from './actions';
+import { AgentType } from './agent';
+import { StreamEvent } from './events';
+import { ChatResponse } from './responses';
+/** Resolved headers ready to be sent with the request */
+export interface ResolvedHeaders {
+    /** API Key header */
+    'x-api-key': string;
+    /** Integration type */
+    'x-integration-type': string;
+    /** User ID (optional) */
+    'x-user-id'?: string;
+    /** Participant ID (optional) */
+    'x-participant-id'?: string;
+    /** Authorization bearer token (optional) */
+    authorization?: string;
+    /** MCP tokens JSON (optional) */
+    'x-mcp-tokens'?: string;
+    /** Any additional custom headers */
+    [key: string]: string | undefined;
+}
+/** Request object passed to the provider */
+export interface ProviderRequest {
+    /** User message */
+    message: string;
+    /** Conversation ID (optional) */
+    conversationId?: string;
+    /** Agent type */
+    agentType?: AgentType;
+    /** Response to a pending action */
+    actionResponse?: ActionResponse;
+    /** Resolved headers */
+    headers: ResolvedHeaders;
+    /** AbortSignal */
+    signal?: AbortSignal;
+    /** Request timeout in ms */
+    timeout: number;
+}
+/**
+ * Provider interface — the core abstraction for backend communication.
+ *
+ * Implement this interface to connect the SDK to any AI backend.
+ * The SDK ships with `ThaliqNativeProvider` as the default.
+ */
+export interface Provider {
+    /** Unique name of the provider */
+    readonly name: string;
+    /** Send a message and return the complete response */
+    chat(request: ProviderRequest): Promise<ChatResponse>;
+    /** Send a message and return a stream of events */
+    stream(request: ProviderRequest): AsyncIterable<StreamEvent>;
+}

package/types/responses.d.ts

@@ -0,0 +1,48 @@
+import { PendingAction } from './actions';
+/** Insight severity levels, from informational to critical. */
+export type InsightSeverity = 'low' | 'medium' | 'high' | 'critical';
+/** Categories of insights the agent can extract from a conversation. */
+export type InsightType = 'warning' | 'opportunity' | 'info' | 'achievement';
+/** An insight extracted from the agent's response */
+export interface Insight {
+    /** Type of insight */
+    type: InsightType;
+    /** Severity level */
+    severity: InsightSeverity;
+    /** Short title */
+    title: string;
+    /** Detailed description */
+    description: string;
+    /** Optional category */
+    category?: string;
+    /** Optional amount (for financial insights) */
+    amount?: string;
+}
+/** Metadata about the response */
+export interface ResponseMetadata {
+    /** Conversation ID */
+    conversationId: string;
+    /** Model used for generation */
+    model: string;
+    /** Number of input/prompt tokens */
+    promptTokens: number;
+    /** Number of output/completion tokens */
+    completionTokens: number;
+    /** Total processing time in ms */
+    processingTimeMs: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+}
+/** Complete chat response (non-streaming or accumulated) */
+export interface ChatResponse {
+    /** The agent's text response */
+    message: string;
+    /** Conversation ID */
+    conversationId: string;
+    /** Extracted insights */
+    insights: Insight[];
+    /** Response metadata */
+    metadata: ResponseMetadata;
+    /** Pending action if HITL is required */
+    action?: PendingAction;
+}

package/utils/action-response-builder.d.ts

@@ -0,0 +1,29 @@
+import { ActionResponse } from '../types/actions';
+export declare class ActionResponseBuilder {
+    /**
+     * Accept a consent or confirm action.
+     *
+     * @param instructionId - The instruction ID from `pendingAction.instructionId`
+     */
+    static accept(instructionId: string): ActionResponse;
+    /**
+     * Reject a consent or confirm action.
+     *
+     * @param instructionId - The instruction ID from `pendingAction.instructionId`
+     */
+    static reject(instructionId: string): ActionResponse;
+    /**
+     * Select an option from a select action.
+     *
+     * @param instructionId - The instruction ID from `pendingAction.instructionId`
+     * @param value - The selected option value
+     */
+    static select(instructionId: string, value: string): ActionResponse;
+    /**
+     * Submit form values for a form action.
+     *
+     * @param instructionId - The instruction ID from `pendingAction.instructionId`
+     * @param values - Key-value map of form field names to values
+     */
+    static submitForm(instructionId: string, values: Record<string, string>): ActionResponse;
+}

package/utils/event-emitter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Typed EventEmitter — zero-dependency, type-safe event system.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new TypedEventEmitter<SDKEventMap>();
+ * emitter.on('error', (err) => console.error(err));
+ * emitter.once('identify', (userId) => console.log('Identified:', userId));
+ * ```
+ */
+/** Callback function type */
+type Callback = (...args: any[]) => void;
+export declare class TypedEventEmitter<T extends {
+    [K in keyof T]: Callback;
+}> {
+    private readonly _listeners;
+    /** Register a listener for an event */
+    on<K extends keyof T>(event: K, listener: T[K]): this;
+    /** Register a one-time listener */
+    once<K extends keyof T>(event: K, listener: T[K]): this;
+    /** Remove a listener */
+    off<K extends keyof T>(event: K, listener: T[K]): this;
+    /** Emit an event to all registered listeners */
+    emit<K extends keyof T>(event: K, ...args: Parameters<T[K]>): void;
+    /** Remove all listeners for an event, or all listeners if no event specified */
+    removeAllListeners(event?: keyof T): this;
+    /** Get the count of listeners for a specific event */
+    listenerCount(event: keyof T): number;
+}
+export {};

package/utils/logger.d.ts

@@ -0,0 +1,2 @@
+import { Logger, LogLevel } from '../types/config';
+export declare function createDefaultLogger(minLevel: LogLevel): Logger;

package/utils/retry.d.ts

@@ -0,0 +1,32 @@
+import { ResolvedRetryConfig, Logger } from '../types/config';
+import { ThaliqError } from '../types/errors';
+/**
+ * Check if an error is retryable.
+ * Returns `true` for server errors (5xx), timeouts, and connection errors.
+ * Returns `false` for auth errors (401/403), validation (400), and rate limits (429).
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Calculate the retry delay with exponential backoff and jitter.
+ * Formula: `min(baseDelay * 2^attempt, maxDelay) + random(0..50%)`.
+ */
+export declare function calculateBackoff(attempt: number, baseDelay: number, maxDelay: number): number;
+/** Options for the retry wrapper */
+export interface RetryOptions {
+    config: ResolvedRetryConfig;
+    logger: Logger;
+    /** Called before each retry attempt */
+    onRetry?: (attempt: number, error: ThaliqError, delayMs: number) => void;
+    /** AbortSignal to cancel retries */
+    signal?: AbortSignal;
+}
+/**
+ * Execute an async function with automatic retry on retryable errors.
+ * Uses exponential backoff with jitter between attempts.
+ *
+ * @param fn - The async function to execute (and potentially retry)
+ * @param options - Retry configuration, logger, and optional callbacks
+ * @returns The result of `fn()` on success
+ * @throws The last error after all retries are exhausted
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;

package/utils/uuid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate a UUID v4 using crypto.randomUUID when available,
+ * falling back to a manual implementation.
+ */
+export declare function uuid(): string;