@march-ai/history-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,759 @@
+import { z } from 'zod';
+
+/**
+ * Retry configuration options
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Exponential backoff multiplier */
+    backoffFactor: number;
+    /** HTTP status codes that should trigger a retry */
+    retryStatusCodes: number[];
+    /** Maximum backoff delay in seconds */
+    maxBackoffSeconds: number;
+}
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Internal client configuration
+ */
+interface ClientConfig {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Retry configuration */
+    retryConfig: RetryConfig;
+    /** Optional API key for X-API-Key header (backend) */
+    apiKey?: string;
+    /** Optional JWT bearer token for Authorization header (frontend) */
+    bearerToken?: string;
+    /** Custom headers to include in all requests */
+    customHeaders?: Record<string, string>;
+}
+/**
+ * User-facing client options (all fields optional except those required)
+ */
+interface MarchHistoryClientOptions {
+    /** Base URL of the API (default: http://localhost:8000) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Custom retry configuration (overrides maxRetries if provided) */
+    retryConfig?: Partial<RetryConfig>;
+    /** Optional API key for X-API-Key header (backend use) */
+    apiKey?: string;
+    /** Optional JWT bearer token for Authorization header (frontend use) */
+    bearerToken?: string;
+    /** Custom headers to include in all requests */
+    customHeaders?: Record<string, string>;
+}
+
+/**
+ * Base HTTP client with fetch API and retry logic
+ */
+declare class BaseHTTPClient {
+    private config;
+    private abortController;
+    constructor(config: ClientConfig);
+    /**
+     * Build headers for requests
+     */
+    private getHeaders;
+    /**
+     * Wrapper around native fetch with timeout support
+     */
+    private fetch;
+    /**
+     * Handle response and parse JSON or throw error
+     */
+    private handleResponse;
+    /**
+     * GET request with retry logic
+     */
+    get<T>(path: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * POST request with retry logic
+     */
+    post<T>(path: string, body?: Record<string, any>): Promise<T>;
+    /**
+     * PATCH request with retry logic
+     */
+    patch<T>(path: string, body?: Record<string, any>): Promise<T>;
+    /**
+     * DELETE request with retry logic
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Close the client and abort any in-flight requests
+     */
+    close(): void;
+}
+
+/**
+ * Base resource class with HTTP client methods
+ */
+declare abstract class BaseResource {
+    protected config: ClientConfig;
+    protected httpClient: BaseHTTPClient;
+    constructor(config: ClientConfig);
+    /**
+     * GET request helper
+     */
+    protected get<T>(path: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * POST request helper
+     */
+    protected post<T>(path: string, body?: Record<string, any>): Promise<T>;
+    /**
+     * PATCH request helper
+     */
+    protected patch<T>(path: string, body?: Record<string, any>): Promise<T>;
+    /**
+     * DELETE request helper
+     */
+    protected delete(path: string): Promise<void>;
+    /**
+     * Close the HTTP client
+     */
+    close(): void;
+}
+
+/**
+ * Tenant schema
+ */
+declare const TenantSchema: z.ZodObject<{
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+} & {
+    id: z.ZodNumber;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    created_at: string;
+    updated_at: string;
+    id: number;
+    name: string;
+}, {
+    created_at: string;
+    updated_at: string;
+    id: number;
+    name: string;
+}>;
+/**
+ * Tenant type
+ */
+type Tenant = z.infer<typeof TenantSchema>;
+
+/**
+ * Message role constants
+ */
+declare const MessageRole: {
+    readonly USER: "user";
+    readonly ASSISTANT: "assistant";
+    readonly SYSTEM: "system";
+};
+/**
+ * Message role type
+ */
+type MessageRole = typeof MessageRole[keyof typeof MessageRole];
+/**
+ * Message schema
+ */
+declare const MessageSchema: z.ZodObject<{
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+} & {
+    id: z.ZodNumber;
+    conversation_id: z.ZodNumber;
+    sequence_number: z.ZodNumber;
+    role: z.ZodEnum<["user", "assistant", "system"]>;
+    content: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    created_at: string;
+    updated_at: string;
+    id: number;
+    conversation_id: number;
+    sequence_number: number;
+    role: "user" | "assistant" | "system";
+    content: string;
+    metadata: Record<string, any>;
+}, {
+    created_at: string;
+    updated_at: string;
+    id: number;
+    conversation_id: number;
+    sequence_number: number;
+    role: "user" | "assistant" | "system";
+    content: string;
+    metadata?: Record<string, any> | undefined;
+}>;
+/**
+ * Message type
+ */
+type Message = z.infer<typeof MessageSchema>;
+
+/**
+ * Conversation status constants
+ */
+declare const ConversationStatus: {
+    readonly ACTIVE: "active";
+    readonly ARCHIVED: "archived";
+};
+/**
+ * Conversation status type
+ */
+type ConversationStatus = typeof ConversationStatus[keyof typeof ConversationStatus];
+/**
+ * Conversation schema
+ * Note: Uses z.lazy() for the messages array to handle circular reference
+ */
+declare const ConversationSchema: z.ZodObject<{
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+} & {
+    id: z.ZodNumber;
+    tenant_id: z.ZodNumber;
+    user_id: z.ZodString;
+    agent_identifier: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodEnum<["active", "archived"]>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    messages: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodLazy<z.ZodObject<{
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    } & {
+        id: z.ZodNumber;
+        conversation_id: z.ZodNumber;
+        sequence_number: z.ZodNumber;
+        role: z.ZodEnum<["user", "assistant", "system"]>;
+        content: z.ZodString;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        created_at: string;
+        updated_at: string;
+        id: number;
+        conversation_id: number;
+        sequence_number: number;
+        role: "user" | "assistant" | "system";
+        content: string;
+        metadata: Record<string, any>;
+    }, {
+        created_at: string;
+        updated_at: string;
+        id: number;
+        conversation_id: number;
+        sequence_number: number;
+        role: "user" | "assistant" | "system";
+        content: string;
+        metadata?: Record<string, any> | undefined;
+    }>>, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    created_at: string;
+    updated_at: string;
+    status: "active" | "archived";
+    id: number;
+    metadata: Record<string, any>;
+    tenant_id: number;
+    user_id: string;
+    agent_identifier?: string | null | undefined;
+    title?: string | null | undefined;
+    messages?: {
+        created_at: string;
+        updated_at: string;
+        id: number;
+        conversation_id: number;
+        sequence_number: number;
+        role: "user" | "assistant" | "system";
+        content: string;
+        metadata: Record<string, any>;
+    }[] | null | undefined;
+}, {
+    created_at: string;
+    updated_at: string;
+    status: "active" | "archived";
+    id: number;
+    tenant_id: number;
+    user_id: string;
+    metadata?: Record<string, any> | undefined;
+    agent_identifier?: string | null | undefined;
+    title?: string | null | undefined;
+    messages?: {
+        created_at: string;
+        updated_at: string;
+        id: number;
+        conversation_id: number;
+        sequence_number: number;
+        role: "user" | "assistant" | "system";
+        content: string;
+        metadata?: Record<string, any> | undefined;
+    }[] | null | undefined;
+}>;
+/**
+ * Conversation type
+ */
+type Conversation = z.infer<typeof ConversationSchema>;
+
+/**
+ * Create conversation request schema
+ */
+declare const CreateConversationRequestSchema: z.ZodObject<{
+    tenant_name: z.ZodString;
+    user_id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    agent_identifier: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["active", "archived"]>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+    tenant_name: string;
+    status?: "active" | "archived" | undefined;
+    metadata?: Record<string, any> | undefined;
+    agent_identifier?: string | undefined;
+    title?: string | undefined;
+}, {
+    user_id: string;
+    tenant_name: string;
+    status?: "active" | "archived" | undefined;
+    metadata?: Record<string, any> | undefined;
+    agent_identifier?: string | undefined;
+    title?: string | undefined;
+}>;
+type CreateConversationRequest = z.infer<typeof CreateConversationRequestSchema>;
+/**
+ * Update conversation request schema
+ */
+declare const UpdateConversationRequestSchema: z.ZodObject<{
+    user_id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["active", "archived"]>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    status?: "active" | "archived" | undefined;
+    metadata?: Record<string, any> | undefined;
+    user_id?: string | undefined;
+    title?: string | undefined;
+}, {
+    status?: "active" | "archived" | undefined;
+    metadata?: Record<string, any> | undefined;
+    user_id?: string | undefined;
+    title?: string | undefined;
+}>;
+type UpdateConversationRequest = z.infer<typeof UpdateConversationRequestSchema>;
+/**
+ * Create message request schema
+ */
+declare const CreateMessageRequestSchema: z.ZodObject<{
+    role: z.ZodEnum<["user", "assistant", "system"]>;
+    content: z.ZodString;
+    sequence_number: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    role: "user" | "assistant" | "system";
+    content: string;
+    sequence_number?: number | undefined;
+    metadata?: Record<string, any> | undefined;
+}, {
+    role: "user" | "assistant" | "system";
+    content: string;
+    sequence_number?: number | undefined;
+    metadata?: Record<string, any> | undefined;
+}>;
+type CreateMessageRequest = z.infer<typeof CreateMessageRequestSchema>;
+/**
+ * Batch messages request schema
+ */
+declare const BatchMessagesRequestSchema: z.ZodObject<{
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant", "system"]>;
+        content: z.ZodString;
+        sequence_number: z.ZodOptional<z.ZodNumber>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        role: "user" | "assistant" | "system";
+        content: string;
+        sequence_number?: number | undefined;
+        metadata?: Record<string, any> | undefined;
+    }, {
+        role: "user" | "assistant" | "system";
+        content: string;
+        sequence_number?: number | undefined;
+        metadata?: Record<string, any> | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    messages: {
+        role: "user" | "assistant" | "system";
+        content: string;
+        sequence_number?: number | undefined;
+        metadata?: Record<string, any> | undefined;
+    }[];
+}, {
+    messages: {
+        role: "user" | "assistant" | "system";
+        content: string;
+        sequence_number?: number | undefined;
+        metadata?: Record<string, any> | undefined;
+    }[];
+}>;
+type BatchMessagesRequest = z.infer<typeof BatchMessagesRequestSchema>;
+
+/**
+ * Container for a single page of results
+ */
+declare class Page<T> {
+    items: T[];
+    offset: number;
+    limit: number;
+    total: number | null;
+    hasMore: boolean;
+    constructor(items: T[], offset: number, limit: number, total?: number | null);
+    /**
+     * Make the page iterable
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Get the number of items in this page
+     */
+    get length(): number;
+}
+
+/**
+ * Async paginator that automatically fetches pages and yields individual items
+ */
+declare class AsyncPaginator<T> {
+    private fetchPage;
+    private pageSize;
+    private maxItems;
+    private offset;
+    private totalFetched;
+    constructor(fetchPage: (offset: number, limit: number) => Promise<T[]>, pageSize?: number, maxItems?: number | null);
+    /**
+     * Make this class async iterable for use with "for await...of"
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Iterate over pages instead of individual items
+     */
+    pages(): AsyncIterator<Page<T>>;
+}
+
+/**
+ * Tenant resource for managing tenants
+ */
+declare class TenantResource extends BaseResource {
+    /**
+     * List tenants with pagination
+     */
+    list(params?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<Tenant[]>;
+    /**
+     * List tenants with auto-pagination
+     */
+    listIter(pageSize?: number, maxItems?: number | null): AsyncPaginator<Tenant>;
+    /**
+     * Get a tenant by ID
+     */
+    getById(tenantId: number): Promise<Tenant>;
+    /**
+     * Get a tenant by name
+     */
+    getByName(tenantName: string): Promise<Tenant>;
+}
+
+/**
+ * Parameters for creating a conversation
+ */
+interface CreateConversationParams {
+    tenant_name: string;
+    user_id: string;
+    title?: string;
+    agent_identifier?: string;
+    status?: ConversationStatus;
+    metadata?: Record<string, any>;
+}
+/**
+ * Parameters for listing conversations
+ */
+interface ListConversationsParams {
+    tenant_name?: string;
+    tenant_id?: number;
+    user_id?: string;
+    agent_identifier?: string;
+    status?: ConversationStatus;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Parameters for searching conversations
+ */
+interface SearchConversationsParams {
+    q?: string;
+    metadata_key?: string;
+    metadata_value?: string;
+    tenant_name?: string;
+    tenant_id?: number;
+    user_id?: string;
+    agent_identifier?: string;
+    status?: ConversationStatus;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Conversation resource for managing conversations
+ */
+declare class ConversationResource extends BaseResource {
+    /**
+     * Create a new conversation
+     */
+    create(params: CreateConversationParams): Promise<Conversation>;
+    /**
+     * List conversations with optional filters
+     */
+    list(params?: ListConversationsParams): Promise<Conversation[]>;
+    /**
+     * List conversations with auto-pagination
+     */
+    listIter(params?: Omit<ListConversationsParams, 'offset' | 'limit'>, pageSize?: number, maxItems?: number | null): AsyncPaginator<Conversation>;
+    /**
+     * Get a conversation by ID
+     */
+    getById(conversationId: number, includeMessages?: boolean): Promise<Conversation>;
+    /**
+     * Update a conversation
+     */
+    update(conversationId: number, updates: {
+        user_id?: string;
+        title?: string;
+        status?: ConversationStatus;
+        metadata?: Record<string, any>;
+    }): Promise<Conversation>;
+    /**
+     * Archive a conversation
+     */
+    archive(conversationId: number): Promise<Conversation>;
+    /**
+     * Unarchive a conversation
+     */
+    unarchive(conversationId: number): Promise<Conversation>;
+    /**
+     * Delete a conversation
+     */
+    deleteById(conversationId: number): Promise<void>;
+    /**
+     * Search conversations
+     */
+    search(params?: SearchConversationsParams): Promise<Conversation[]>;
+    /**
+     * Search conversations with auto-pagination
+     */
+    searchIter(params?: Omit<SearchConversationsParams, 'offset' | 'limit'>, pageSize?: number, maxItems?: number | null): AsyncPaginator<Conversation>;
+}
+
+/**
+ * Parameters for creating a message
+ */
+interface CreateMessageParams {
+    conversation_id: number;
+    role: MessageRole;
+    content: string;
+    sequence_number?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Parameters for batch creating messages
+ */
+interface BatchCreateMessageParams {
+    role: MessageRole;
+    content: string;
+    sequence_number?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Parameters for listing messages
+ */
+interface ListMessagesParams {
+    conversation_id: number;
+    role?: MessageRole;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Parameters for searching messages in a conversation
+ */
+interface SearchMessagesParams {
+    conversation_id: number;
+    q: string;
+    role?: MessageRole;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Parameters for searching messages globally
+ */
+interface SearchMessagesGlobalParams {
+    q: string;
+    conversation_id?: number;
+    role?: MessageRole;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Message resource for managing messages
+ */
+declare class MessageResource extends BaseResource {
+    /**
+     * Create a single message
+     */
+    create(params: CreateMessageParams): Promise<Message>;
+    /**
+     * Batch create multiple messages
+     */
+    createBatch(conversationId: number, messages: BatchCreateMessageParams[]): Promise<Message[]>;
+    /**
+     * List messages in a conversation
+     */
+    list(params: ListMessagesParams): Promise<Message[]>;
+    /**
+     * List messages with auto-pagination
+     */
+    listIter(params: Omit<ListMessagesParams, 'offset' | 'limit'>, pageSize?: number, maxItems?: number | null): AsyncPaginator<Message>;
+    /**
+     * Get a message by ID
+     */
+    getById(messageId: number): Promise<Message>;
+    /**
+     * Search messages in a conversation
+     */
+    search(params: SearchMessagesParams): Promise<Message[]>;
+    /**
+     * Search messages globally across all conversations
+     */
+    searchGlobal(params: SearchMessagesGlobalParams): Promise<Message[]>;
+}
+
+/**
+ * Main client for the March History API
+ *
+ * Works in both Node.js and browser environments.
+ * Supports dual authentication: API key (backend) and JWT bearer token (frontend).
+ *
+ * @example
+ * // Backend with API key
+ * const client = new MarchHistoryClient({
+ *   baseUrl: 'http://localhost:8000',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * @example
+ * // Frontend with JWT
+ * const client = new MarchHistoryClient({
+ *   baseUrl: 'https://api.example.com',
+ *   bearerToken: jwtToken
+ * });
+ *
+ * @example
+ * // Both API key and JWT
+ * const client = new MarchHistoryClient({
+ *   baseUrl: 'https://api.example.com',
+ *   apiKey: 'project-key',
+ *   bearerToken: userJWT
+ * });
+ */
+declare class MarchHistoryClient {
+    /**
+     * Tenant resource for managing tenants
+     */
+    readonly tenants: TenantResource;
+    /**
+     * Conversation resource for managing conversations
+     */
+    readonly conversations: ConversationResource;
+    /**
+     * Message resource for managing messages
+     */
+    readonly messages: MessageResource;
+    /**
+     * Create a new March History API client
+     *
+     * @param options - Client configuration options
+     */
+    constructor(options?: MarchHistoryClientOptions);
+    /**
+     * Close all HTTP connections and cancel in-flight requests
+     *
+     * This is optional - connections are managed automatically.
+     * Use this for explicit cleanup when you're done with the client.
+     */
+    close(): void;
+}
+
+/**
+ * Base error class for all March History SDK errors
+ */
+declare class MarchHistoryError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for API errors with HTTP status codes
+ */
+declare class APIError extends MarchHistoryError {
+    statusCode?: number;
+    responseBody: Record<string, any>;
+    errorCode?: string;
+    details: any[];
+    constructor(message: string, statusCode?: number, responseBody?: Record<string, any>);
+    toString(): string;
+}
+/**
+ * 400 Bad Request error
+ */
+declare class BadRequestError extends APIError {
+    constructor(message: string, statusCode: number, responseBody: Record<string, any>);
+}
+/**
+ * 404 Not Found error
+ */
+declare class NotFoundError extends APIError {
+    constructor(message: string, statusCode: number, responseBody: Record<string, any>);
+}
+/**
+ * 409 Conflict error (e.g., duplicate sequence number)
+ */
+declare class ConflictError extends APIError {
+    constructor(message: string, statusCode: number, responseBody: Record<string, any>);
+}
+/**
+ * 422 Validation error (invalid request data)
+ */
+declare class ValidationError extends APIError {
+    constructor(message: string, statusCode: number, responseBody: Record<string, any>);
+}
+/**
+ * 500+ Server error
+ */
+declare class ServerError extends APIError {
+    constructor(message: string, statusCode: number, responseBody: Record<string, any>);
+}
+/**
+ * Network error (connection failed, timeout, etc.)
+ */
+declare class NetworkError extends MarchHistoryError {
+    constructor(message: string);
+}
+/**
+ * Retry exhausted error (after max retries)
+ */
+declare class RetryError extends MarchHistoryError {
+    lastException: Error;
+    constructor(message: string, lastException: Error);
+    toString(): string;
+}
+
+export { APIError, AsyncPaginator, BadRequestError, type BatchCreateMessageParams, type BatchMessagesRequest, type ClientConfig, ConflictError, type Conversation, ConversationSchema, ConversationStatus, type CreateConversationParams, type CreateConversationRequest, type CreateMessageParams, type CreateMessageRequest, DEFAULT_RETRY_CONFIG, type ListConversationsParams, type ListMessagesParams, MarchHistoryClient, type MarchHistoryClientOptions, MarchHistoryError, type Message, MessageRole, MessageSchema, NetworkError, NotFoundError, Page, type RetryConfig, RetryError, type SearchConversationsParams, type SearchMessagesGlobalParams, type SearchMessagesParams, ServerError, type Tenant, TenantSchema, type UpdateConversationRequest, ValidationError };