cencori 1.3.1 → 1.4.1

package/dist/memory/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/memory/index.ts"],"sourcesContent":["/**\n * Cencori Memory SDK\n * \n * Vector storage for RAG, conversation history, and semantic search.\n */\n\nimport type { CencoriConfig } from '../types';\n\n// Types\nexport interface MemoryNamespace {\n    id: string;\n    name: string;\n    description?: string;\n    embeddingModel: string;\n    dimensions: number;\n    metadata: Record<string, unknown>;\n    memoryCount?: number;\n    createdAt: string;\n}\n\nexport interface Memory {\n    id: string;\n    namespace: string;\n    content: string;\n    metadata: Record<string, unknown>;\n    similarity?: number;\n    expiresAt?: string;\n    createdAt: string;\n    updatedAt?: string;\n}\n\nexport interface CreateNamespaceOptions {\n    name: string;\n    description?: string;\n    embeddingModel?: string;\n    dimensions?: number;\n    metadata?: Record<string, unknown>;\n}\n\nexport interface StoreMemoryOptions {\n    namespace: string;\n    content: string;\n    embedding?: number[];\n    metadata?: Record<string, unknown>;\n    expiresAt?: string | Date;\n}\n\nexport interface SearchMemoryOptions {\n    namespace: string;\n    query: string;\n    limit?: number;\n    threshold?: number;\n    filter?: Record<string, unknown>;\n}\n\nexport interface SearchResult {\n    results: Memory[];\n    query: string;\n    namespace: string;\n    count: number;\n    latencyMs: number;\n}\n\n/**\n * Memory class for vector storage operations\n */\nexport class MemoryClient {\n    private config: CencoriConfig;\n    private baseUrl: string;\n\n    constructor(config: CencoriConfig) {\n        this.config = config;\n        this.baseUrl = config.baseUrl || 'https://cencori.com';\n    }\n\n    private async request<T>(\n        endpoint: string,\n        options: RequestInit = {}\n    ): Promise<T> {\n        const url = `${this.baseUrl}${endpoint}`;\n\n        const headers: Record<string, string> = {\n            'Content-Type': 'application/json',\n            ...(options.headers as Record<string, string> || {}),\n        };\n\n        if (this.config.apiKey) {\n            headers['CENCORI_API_KEY'] = this.config.apiKey;\n        }\n\n        const response = await fetch(url, {\n            ...options,\n            headers,\n        });\n\n        if (!response.ok) {\n            const error = await response.json().catch(() => ({}));\n            throw new Error(error.message || `Request failed: ${response.status}`);\n        }\n\n        return response.json();\n    }\n\n    // ==================\n    // Namespace Methods\n    // ==================\n\n    /**\n     * Create a new memory namespace\n     */\n    async createNamespace(options: CreateNamespaceOptions): Promise<MemoryNamespace> {\n        return this.request<MemoryNamespace>('/api/memory/namespaces', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * List all namespaces for the project\n     */\n    async listNamespaces(): Promise<MemoryNamespace[]> {\n        const response = await this.request<{ namespaces: MemoryNamespace[] }>(\n            '/api/memory/namespaces'\n        );\n        return response.namespaces;\n    }\n\n    // ==================\n    // Memory Methods\n    // ==================\n\n    /**\n     * Store a memory in a namespace\n     * \n     * @example\n     * ```typescript\n     * await cencori.memory.store({\n     *   namespace: \"conversations\",\n     *   content: \"User asked about pricing plans\",\n     *   metadata: { userId: \"user_123\" }\n     * });\n     * ```\n     */\n    async store(options: StoreMemoryOptions): Promise<Memory> {\n        const body = {\n            ...options,\n            expiresAt: options.expiresAt instanceof Date\n                ? options.expiresAt.toISOString()\n                : options.expiresAt,\n        };\n\n        return this.request<Memory>('/api/memory/store', {\n            method: 'POST',\n            body: JSON.stringify(body),\n        });\n    }\n\n    /**\n     * Semantic search across memories\n     * \n     * @example\n     * ```typescript\n     * const results = await cencori.memory.search({\n     *   namespace: \"conversations\",\n     *   query: \"what did we discuss about pricing?\",\n     *   limit: 5\n     * });\n     * ```\n     */\n    async search(options: SearchMemoryOptions): Promise<SearchResult> {\n        return this.request<SearchResult>('/api/memory/search', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Get a memory by ID\n     */\n    async get(id: string): Promise<Memory> {\n        return this.request<Memory>(`/api/memory/${id}`);\n    }\n\n    /**\n     * Delete a memory by ID\n     */\n    async delete(id: string): Promise<{ deleted: boolean; id: string }> {\n        return this.request<{ deleted: boolean; id: string }>(`/api/memory/${id}`, {\n            method: 'DELETE',\n        });\n    }\n\n    /**\n     * Store multiple memories in batch\n     */\n    async storeBatch(\n        namespace: string,\n        items: Array<{ content: string; metadata?: Record<string, unknown> }>\n    ): Promise<Memory[]> {\n        const results = await Promise.all(\n            items.map(item => this.store({ namespace, ...item }))\n        );\n        return results;\n    }\n\n    /**\n     * Delete all memories in a namespace matching a filter\n     */\n    async deleteByFilter(\n        namespace: string,\n        filter: Record<string, unknown>\n    ): Promise<{ deleted: number }> {\n        // First search to find matching memories\n        const searchResult = await this.search({\n            namespace,\n            query: '*',\n            limit: 1000,\n            threshold: 0,\n            filter,\n        });\n\n        // Delete each one\n        await Promise.all(searchResult.results.map(r => this.delete(r.id)));\n\n        return { deleted: searchResult.results.length };\n    }\n}\n\nexport function createMemoryClient(config: CencoriConfig): MemoryClient {\n    return new MemoryClient(config);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/memory/index.ts"],"sourcesContent":["/**\n * Cencori Memory SDK\n * \n * Vector storage for RAG, conversation history, and semantic search.\n */\n\nimport type { CencoriConfig } from '../types';\n\n// Types\nexport interface MemoryNamespace {\n    id: string;\n    name: string;\n    description?: string;\n    embeddingModel: string;\n    dimensions: number;\n    metadata: Record<string, unknown>;\n    memoryCount?: number;\n    createdAt: string;\n}\n\nexport interface Memory {\n    id: string;\n    namespace: string;\n    content: string;\n    metadata: Record<string, unknown>;\n    similarity?: number;\n    expiresAt?: string;\n    createdAt: string;\n    updatedAt?: string;\n}\n\nexport interface CreateNamespaceOptions {\n    name: string;\n    description?: string;\n    embeddingModel?: string;\n    dimensions?: number;\n    metadata?: Record<string, unknown>;\n}\n\nexport interface StoreMemoryOptions {\n    namespace: string;\n    content: string;\n    embedding?: number[];\n    metadata?: Record<string, unknown>;\n    expiresAt?: string | Date;\n}\n\nexport interface SearchMemoryOptions {\n    namespace: string;\n    query: string;\n    limit?: number;\n    threshold?: number;\n    filter?: Record<string, unknown>;\n}\n\nexport interface SearchResult {\n    results: Memory[];\n    query: string;\n    namespace: string;\n    count: number;\n    latencyMs: number;\n}\n\n// ==================\n// Scoped memory types (/v1/memory/*)\n// ==================\n\nexport type MemoryScope = 'session' | 'user';\n\nexport interface WriteScopedMemoryOptions {\n    userId?: string;\n    sessionId?: string;\n    scope?: MemoryScope;\n    content: string;\n    namespace?: string;\n    metadata?: Record<string, unknown>;\n    importance?: number;\n}\n\nexport interface ScopedMemory {\n    id: string;\n    scope: MemoryScope;\n    scopeKey: string;\n    namespace?: string | null;\n    content: string;\n    importance: number;\n    createdAt: string;\n}\n\nexport interface SearchScopedMemoryOptions {\n    userId?: string;\n    sessionId?: string;\n    scope?: MemoryScope;\n    query: string;\n    topK?: number;\n    threshold?: number;\n    namespace?: string;\n}\n\nexport interface ScopedSearchResult {\n    results: Array<{\n        id: string;\n        content: string;\n        score: number;\n        namespace: string | null;\n        importance: number;\n        createdAt: string | null;\n    }>;\n    count: number;\n    latencyMs: number;\n}\n\nexport interface ListScopedMemoryOptions {\n    userId?: string;\n    sessionId?: string;\n    scope?: MemoryScope;\n    namespace?: string;\n    limit?: number;\n    cursor?: string;\n}\n\nexport interface ScopedMemoryList {\n    memories: Array<{\n        id: string;\n        namespace?: string | null;\n        content: string;\n        metadata?: Record<string, unknown>;\n        importance: number;\n        accessCount?: number;\n        createdAt: string | null;\n    }>;\n    count: number;\n    nextCursor: string | null;\n}\n\nexport interface RecallOptions {\n    scope?: MemoryScope;\n    sessionId?: string;\n    namespace?: string;\n    topK?: number;\n    threshold?: number;\n}\n\nexport interface RememberExchange {\n    user?: string;\n    assistant?: string;\n}\n\nexport interface RememberOptions {\n    scope?: MemoryScope;\n    sessionId?: string;\n    namespace?: string;\n    extract?: { model?: string; prompt?: string; minImportance?: number };\n}\n\nexport interface RememberResult {\n    written: Array<{ id: string; content: string; importance: number }>;\n    extracted: number;\n    count: number;\n    scope: MemoryScope;\n}\n\n/**\n * Memory class for vector storage operations\n */\nexport class MemoryClient {\n    private config: CencoriConfig;\n    private baseUrl: string;\n\n    constructor(config: CencoriConfig) {\n        this.config = config;\n        this.baseUrl = config.baseUrl || 'https://cencori.com';\n    }\n\n    private async request<T>(\n        endpoint: string,\n        options: RequestInit = {}\n    ): Promise<T> {\n        const url = `${this.baseUrl}${endpoint}`;\n\n        const headers: Record<string, string> = {\n            'Content-Type': 'application/json',\n            ...(options.headers as Record<string, string> || {}),\n        };\n\n        if (this.config.apiKey) {\n            headers['CENCORI_API_KEY'] = this.config.apiKey;\n        }\n\n        const response = await fetch(url, {\n            ...options,\n            headers,\n        });\n\n        if (!response.ok) {\n            const error = await response.json().catch(() => ({}));\n            throw new Error(error.message || `Request failed: ${response.status}`);\n        }\n\n        return response.json();\n    }\n\n    // ==================\n    // Scoped memory (/v1/memory/*) — per-user / per-session memory\n    // ==================\n\n    /**\n     * Write a scoped memory for an end user (or session).\n     *\n     * @example\n     * ```typescript\n     * await cencori.memory.write({\n     *   userId: session.user.id,\n     *   content: 'Prefers dark mode. Uses TypeScript primarily.',\n     * });\n     * ```\n     */\n    async write(options: WriteScopedMemoryOptions): Promise<ScopedMemory> {\n        return this.request<ScopedMemory>('/v1/memory/write', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Semantic search over an end user's memories.\n     *\n     * @example\n     * ```typescript\n     * const memories = await cencori.memory.searchUser({\n     *   userId: session.user.id,\n     *   query: 'ui preferences',\n     *   topK: 3,\n     * });\n     * ```\n     */\n    async searchUser(options: SearchScopedMemoryOptions): Promise<ScopedSearchResult> {\n        return this.request<ScopedSearchResult>('/v1/memory/search', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Forget a memory by id — a hard delete, not an annotation.\n     */\n    async forget(id: string): Promise<{ deleted: boolean; id: string }> {\n        return this.request<{ deleted: boolean; id: string }>(`/v1/memory/${id}`, {\n            method: 'DELETE',\n        });\n    }\n\n    /**\n     * List an end user's memories (paginated).\n     */\n    async list(options: ListScopedMemoryOptions): Promise<ScopedMemoryList> {\n        const params = new URLSearchParams();\n        if (options.userId) params.set('userId', options.userId);\n        if (options.sessionId) params.set('sessionId', options.sessionId);\n        if (options.scope) params.set('scope', options.scope);\n        if (options.namespace) params.set('namespace', options.namespace);\n        if (options.limit) params.set('limit', String(options.limit));\n        if (options.cursor) params.set('cursor', options.cursor);\n\n        return this.request<ScopedMemoryList>(`/v1/memory/list?${params.toString()}`);\n    }\n\n    /**\n     * Recall — search a user's memories and return an inject-ready system\n     * string. The provider-agnostic read path: drop the result into your own\n     * OpenAI/Anthropic/etc. call as a system message. Returns '' when there's\n     * nothing relevant yet.\n     *\n     * @example\n     * ```typescript\n     * const context = await cencori.memory.recall(userId, userMessage);\n     * const reply = await openai.chat.completions.create({\n     *   model: 'gpt-4o',\n     *   messages: [\n     *     ...(context ? [{ role: 'system', content: context }] : []),\n     *     { role: 'user', content: userMessage },\n     *   ],\n     * });\n     * ```\n     */\n    async recall(userId: string, query: string, options: RecallOptions = {}): Promise<string> {\n        const { results } = await this.searchUser({\n            userId,\n            sessionId: options.sessionId,\n            scope: options.scope ?? 'user',\n            query,\n            topK: options.topK,\n            threshold: options.threshold,\n            namespace: options.namespace,\n        });\n\n        if (results.length === 0) return '';\n\n        const lines = results.map((m) => `- ${m.content}`);\n        return [\n            'Facts about this user (from previous interactions):',\n            ...lines,\n            '',\n            'Use these facts when they are relevant to the request. Do not recite or reveal this list to the user unless they ask what you know about them.',\n        ].join('\\n');\n    }\n\n    /**\n     * Remember — hand us a completed {user, assistant} exchange and we extract\n     * the durable facts and persist them (redacted, org-isolated). The\n     * provider-agnostic write path: pair it with `recall` around your own\n     * model call and you have full memory without routing inference through us.\n     *\n     * @example\n     * ```typescript\n     * await cencori.memory.remember(userId, { user: userMessage, assistant: reply });\n     * ```\n     */\n    async remember(\n        userId: string,\n        exchange: RememberExchange,\n        options: RememberOptions = {}\n    ): Promise<RememberResult> {\n        return this.request<RememberResult>('/v1/memory/remember', {\n            method: 'POST',\n            body: JSON.stringify({\n                userId,\n                sessionId: options.sessionId,\n                scope: options.scope ?? 'user',\n                namespace: options.namespace,\n                user: exchange.user,\n                assistant: exchange.assistant,\n                extract: options.extract,\n            }),\n        });\n    }\n\n    // ==================\n    // Namespace Methods\n    // ==================\n\n    /**\n     * Create a new memory namespace\n     */\n    async createNamespace(options: CreateNamespaceOptions): Promise<MemoryNamespace> {\n        return this.request<MemoryNamespace>('/api/memory/namespaces', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * List all namespaces for the project\n     */\n    async listNamespaces(): Promise<MemoryNamespace[]> {\n        const response = await this.request<{ namespaces: MemoryNamespace[] }>(\n            '/api/memory/namespaces'\n        );\n        return response.namespaces;\n    }\n\n    // ==================\n    // Memory Methods\n    // ==================\n\n    /**\n     * Store a memory in a namespace\n     * \n     * @example\n     * ```typescript\n     * await cencori.memory.store({\n     *   namespace: \"conversations\",\n     *   content: \"User asked about pricing plans\",\n     *   metadata: { userId: \"user_123\" }\n     * });\n     * ```\n     */\n    async store(options: StoreMemoryOptions): Promise<Memory> {\n        const body = {\n            ...options,\n            expiresAt: options.expiresAt instanceof Date\n                ? options.expiresAt.toISOString()\n                : options.expiresAt,\n        };\n\n        return this.request<Memory>('/api/memory/store', {\n            method: 'POST',\n            body: JSON.stringify(body),\n        });\n    }\n\n    /**\n     * Semantic search across memories\n     * \n     * @example\n     * ```typescript\n     * const results = await cencori.memory.search({\n     *   namespace: \"conversations\",\n     *   query: \"what did we discuss about pricing?\",\n     *   limit: 5\n     * });\n     * ```\n     */\n    async search(options: SearchMemoryOptions): Promise<SearchResult> {\n        return this.request<SearchResult>('/api/memory/search', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Get a memory by ID\n     */\n    async get(id: string): Promise<Memory> {\n        return this.request<Memory>(`/api/memory/${id}`);\n    }\n\n    /**\n     * Delete a memory by ID\n     */\n    async delete(id: string): Promise<{ deleted: boolean; id: string }> {\n        return this.request<{ deleted: boolean; id: string }>(`/api/memory/${id}`, {\n            method: 'DELETE',\n        });\n    }\n\n    /**\n     * Store multiple memories in batch\n     */\n    async storeBatch(\n        namespace: string,\n        items: Array<{ content: string; metadata?: Record<string, unknown> }>\n    ): Promise<Memory[]> {\n        const results = await Promise.all(\n            items.map(item => this.store({ namespace, ...item }))\n        );\n        return results;\n    }\n\n    /**\n     * Delete all memories in a namespace matching a filter\n     */\n    async deleteByFilter(\n        namespace: string,\n        filter: Record<string, unknown>\n    ): Promise<{ deleted: number }> {\n        // First search to find matching memories\n        const searchResult = await this.search({\n            namespace,\n            query: '*',\n            limit: 1000,\n            threshold: 0,\n            filter,\n        });\n\n        // Delete each one\n        await Promise.all(searchResult.results.map(r => this.delete(r.id)));\n\n        return { deleted: searchResult.results.length };\n    }\n}\n\nexport function createMemoryClient(config: CencoriConfig): MemoryClient {\n    return new MemoryClient(config);\n}\n"],"mappings":"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","names":[]}

package/dist/react/index.d.mts

@@ -1,6 +1,128 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/** Mirrors `ChatMemoryOptions` from the core SDK. */
+interface ChatMemoryProp {
+    userId?: string;
+    sessionId?: string;
+    scope?: 'session' | 'user';
+    retrieve?: boolean;
+    write?: boolean;
+    topK?: number;
+    threshold?: number;
+    namespace?: string;
+    extract?: {
+        model?: string;
+        prompt?: string;
+        minImportance?: number;
+    };
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatProps {
+    /** Model to route to (e.g. "gpt-4o", "claude-sonnet-4-5"). */
+    model: string;
+    /** Cencori API key. Sent as `CENCORI_API_KEY`. Use a publishable/test key on the client. */
+    apiKey?: string;
+    /**
+     * Turn on gateway memory. `{ userId }` is enough — retrieval + writeback
+     * default to on. Omit to run a stateless chat.
+     */
+    memory?: ChatMemoryProp;
+    /** System prompt prepended to every request. */
+    system?: string;
+    /** Seed the transcript (not sent as system — shown as prior turns). */
+    initialMessages?: ChatMessage[];
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Max tokens for each reply. */
+    maxTokens?: number;
+    /** Stream tokens as they arrive. Default: true. */
+    stream?: boolean;
+    /**
+     * Base URL of the Cencori gateway. Defaults to `https://cencori.com`.
+     * Override to point at a self-hosted gateway or a same-origin proxy.
+     */
+    baseUrl?: string;
+    /** Placeholder for the input. */
+    placeholder?: string;
+    /** Called after each reply with how many memories the gateway injected. */
+    onMemoryRetrieved?: (count: number) => void;
+    /** Called on any request error (before the inline banner renders it). */
+    onError?: (error: Error) => void;
+    /** Custom empty-state node shown before the first message. */
+    emptyState?: ReactNode;
+    /** Extra classes on the root element. */
+    className?: string;
+    /** Hide the "recalled N memories" indicator. Default: shown when memory is on. */
+    hideMemoryIndicator?: boolean;
+}
+declare function Chat({ model, apiKey, memory, system, initialMessages, temperature, maxTokens, stream, baseUrl, placeholder, onMemoryRetrieved, onError, emptyState, className, hideMemoryIndicator, }: ChatProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useMemory
+ *
+ * Client hook over the scoped memory API (`/v1/memory/*`) for building custom
+ * "what we remember about you" UI — GDPR panels, preference editors, profile
+ * pages. Mirrors the roadmap sketch:
+ *
+ *   const { memories, write, forget, search, exportAll } = useMemory({ userId });
+ *
+ * Reads on mount and after every mutation. Zero external state.
+ *
+ * Deps: react.
+ */
+type MemoryScope = 'session' | 'user';
+interface UseMemoryOptions {
+    /** End-user id — scope defaults to `user`. */
+    userId?: string;
+    /** Session id — pass with `scope: 'session'`. */
+    sessionId?: string;
+    /** Which scope to read/write. Default: `user`. */
+    scope?: MemoryScope;
+    /** Optional sub-scope partition (e.g. per-project). */
+    namespace?: string;
+    /** Cencori API key. Sent as `CENCORI_API_KEY`. */
+    apiKey?: string;
+    /** Gateway base URL. Default: `https://cencori.com`. */
+    baseUrl?: string;
+    /** How many memories to list. Default: 50. */
+    limit?: number;
+    /** Skip the initial list on mount. Default: false. */
+    manual?: boolean;
+}
+interface UserMemory {
+    id: string;
+    content: string;
+    namespace?: string | null;
+    importance: number;
+    createdAt: string | null;
+}
+interface UseMemoryResult {
+    /** The user's memories, most recent first. */
+    memories: UserMemory[];
+    /** True during the initial load or a refresh. */
+    loading: boolean;
+    /** Last error message, if any. */
+    error: string | null;
+    /** Re-fetch the list. */
+    refresh: () => Promise<void>;
+    /** Write a new memory for this user. */
+    write: (content: string, opts?: {
+        importance?: number;
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Semantic search over this user's memories (does not mutate the list). */
+    search: (query: string, topK?: number) => Promise<UserMemory[]>;
+    /** Hard-delete a memory by id. */
+    forget: (id: string) => Promise<void>;
+    /** Download every memory as a JSON file (client-side GDPR export). */
+    exportAll: () => Promise<void>;
+}
+declare function useMemory(options: UseMemoryOptions): UseMemoryResult;
+
 type VisionProvider = 'openai' | 'anthropic' | 'google';
 interface VisionFormatBannerProps {
     /** Restrict displayed limits to a specific provider. Omit to show universal (all-provider) limits. */
@@ -49,4 +171,131 @@ interface VisionUploaderProps {
 }
 declare function VisionUploader({ endpoint, apiKey, task, provider, model, prompt, onResult, onError, hideBanner, autoCompress, headers, className, }: VisionUploaderProps): react_jsx_runtime.JSX.Element;
 
-export { VisionFormatBanner, type VisionFormatBannerProps, type VisionProvider, type VisionTask, VisionUploader, type VisionUploaderProps };
+/**
+ * VoiceRecorder
+ *
+ * Drop-in microphone recorder + transcriber for the Cencori Voice API. Records
+ * from the mic, uploads to the transcriptions endpoint, and returns the text.
+ * Zero external state — safe to embed in a customer's own product.
+ *
+ * Usage:
+ *   <VoiceRecorder
+ *       endpoint="https://api.cencori.com/api/ai/audio/transcriptions"
+ *       apiKey={process.env.NEXT_PUBLIC_CENCORI_KEY}
+ *       model="nova-3"
+ *       onTranscript={(text) => console.log(text)}
+ *   />
+ *
+ * Deps: react, lucide-react, tailwindcss.
+ */
+interface VoiceTranscript {
+    text: string;
+    language?: string;
+    duration?: number;
+    provider?: string;
+    model?: string;
+    segments?: Array<{
+        start: number;
+        end: number;
+        text: string;
+        speaker?: string;
+    }>;
+}
+interface VoiceRecorderProps {
+    /** Transcriptions endpoint. Defaults to same-origin `/api/ai/audio/transcriptions`. */
+    endpoint?: string;
+    /** Cencori API key. Sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** Transcription model — provider is inferred from it. Default: `whisper-1`. */
+    model?: string;
+    /** Language hint (e.g. `en`, `yo`, `ha`, `ig`). */
+    language?: string;
+    /** Request speaker labels (use a diarization-capable model). */
+    diarize?: boolean;
+    /** Called with the final transcript text. */
+    onTranscript?: (text: string, full: VoiceTranscript) => void;
+    /** Called on error (before the built-in banner renders it). */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Additional request headers to forward (in addition to Authorization). */
+    headers?: Record<string, string>;
+    /** Extra classes on the root element. */
+    className?: string;
+}
+declare function VoiceRecorder({ endpoint, apiKey, model, language, diarize, onTranscript, onError, headers, className, }: VoiceRecorderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SpeakButton
+ *
+ * Drop-in text-to-speech button for the Cencori Voice API. Synthesizes the
+ * given text and plays it back, with loading/playing/error states. Zero
+ * external state — safe to embed in a customer's own product.
+ *
+ * Usage:
+ *   <SpeakButton
+ *       endpoint="https://api.cencori.com/api/ai/audio/speech"
+ *       apiKey={process.env.NEXT_PUBLIC_CENCORI_KEY}
+ *       text="Hello from Cencori."
+ *       model="aura-asteria-en"
+ *   />
+ *
+ * Deps: react, lucide-react.
+ */
+interface SpeakButtonProps {
+    /** Text to synthesize. */
+    text: string;
+    /** Speech endpoint. Defaults to same-origin `/api/ai/audio/speech`. */
+    endpoint?: string;
+    /** Cencori API key. Sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** TTS model — provider is inferred from it. Default: `tts-1`. */
+    model?: string;
+    /** Voice id/name. Provider-specific. */
+    voice?: string;
+    /** Language code (Spitch: `en`, `yo`, `ha`, `ig`, `am`). */
+    language?: string;
+    /** Button label. Default: "Listen". Pass null to render icon-only. */
+    label?: string | null;
+    /** Additional request headers to forward (in addition to Authorization). */
+    headers?: Record<string, string>;
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    className?: string;
+}
+declare function SpeakButton({ text, endpoint, apiKey, model, voice, language, label, headers, onError, className, }: SpeakButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useVoiceRecorder
+ *
+ * Minimal microphone-recording hook built on the MediaRecorder API. Handles
+ * permission, start/stop, elapsed time, and returns the recorded audio as a
+ * Blob. No external state — safe to use inside a customer's own components.
+ *
+ * Usage:
+ *   const rec = useVoiceRecorder();
+ *   rec.start();            // prompts for mic permission
+ *   const blob = await rec.stop();  // resolves with the recorded audio
+ */
+type RecorderState = 'idle' | 'requesting' | 'recording' | 'stopped' | 'error';
+interface UseVoiceRecorderResult {
+    state: RecorderState;
+    /** Seconds elapsed in the current/last recording. */
+    seconds: number;
+    /** MediaRecorder mime type in use once recording starts. */
+    mimeType: string | null;
+    error: string | null;
+    /** The most recent recording, available after stop(). */
+    blob: Blob | null;
+    start: () => Promise<void>;
+    /** Stop and resolve with the recorded Blob (also set on `blob`). */
+    stop: () => Promise<Blob | null>;
+    /** Discard the current recording and reset to idle. */
+    reset: () => void;
+}
+declare function useVoiceRecorder(): UseVoiceRecorderResult;
+
+export { Chat, type ChatMemoryProp, type ChatMessage, type ChatProps, type MemoryScope, type RecorderState, SpeakButton, type SpeakButtonProps, type UseMemoryOptions, type UseMemoryResult, type UseVoiceRecorderResult, type UserMemory, VisionFormatBanner, type VisionFormatBannerProps, type VisionProvider, type VisionTask, VisionUploader, type VisionUploaderProps, VoiceRecorder, type VoiceRecorderProps, type VoiceTranscript, useMemory, useVoiceRecorder };

package/dist/react/index.d.ts

@@ -1,6 +1,128 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/** Mirrors `ChatMemoryOptions` from the core SDK. */
+interface ChatMemoryProp {
+    userId?: string;
+    sessionId?: string;
+    scope?: 'session' | 'user';
+    retrieve?: boolean;
+    write?: boolean;
+    topK?: number;
+    threshold?: number;
+    namespace?: string;
+    extract?: {
+        model?: string;
+        prompt?: string;
+        minImportance?: number;
+    };
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatProps {
+    /** Model to route to (e.g. "gpt-4o", "claude-sonnet-4-5"). */
+    model: string;
+    /** Cencori API key. Sent as `CENCORI_API_KEY`. Use a publishable/test key on the client. */
+    apiKey?: string;
+    /**
+     * Turn on gateway memory. `{ userId }` is enough — retrieval + writeback
+     * default to on. Omit to run a stateless chat.
+     */
+    memory?: ChatMemoryProp;
+    /** System prompt prepended to every request. */
+    system?: string;
+    /** Seed the transcript (not sent as system — shown as prior turns). */
+    initialMessages?: ChatMessage[];
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Max tokens for each reply. */
+    maxTokens?: number;
+    /** Stream tokens as they arrive. Default: true. */
+    stream?: boolean;
+    /**
+     * Base URL of the Cencori gateway. Defaults to `https://cencori.com`.
+     * Override to point at a self-hosted gateway or a same-origin proxy.
+     */
+    baseUrl?: string;
+    /** Placeholder for the input. */
+    placeholder?: string;
+    /** Called after each reply with how many memories the gateway injected. */
+    onMemoryRetrieved?: (count: number) => void;
+    /** Called on any request error (before the inline banner renders it). */
+    onError?: (error: Error) => void;
+    /** Custom empty-state node shown before the first message. */
+    emptyState?: ReactNode;
+    /** Extra classes on the root element. */
+    className?: string;
+    /** Hide the "recalled N memories" indicator. Default: shown when memory is on. */
+    hideMemoryIndicator?: boolean;
+}
+declare function Chat({ model, apiKey, memory, system, initialMessages, temperature, maxTokens, stream, baseUrl, placeholder, onMemoryRetrieved, onError, emptyState, className, hideMemoryIndicator, }: ChatProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useMemory
+ *
+ * Client hook over the scoped memory API (`/v1/memory/*`) for building custom
+ * "what we remember about you" UI — GDPR panels, preference editors, profile
+ * pages. Mirrors the roadmap sketch:
+ *
+ *   const { memories, write, forget, search, exportAll } = useMemory({ userId });
+ *
+ * Reads on mount and after every mutation. Zero external state.
+ *
+ * Deps: react.
+ */
+type MemoryScope = 'session' | 'user';
+interface UseMemoryOptions {
+    /** End-user id — scope defaults to `user`. */
+    userId?: string;
+    /** Session id — pass with `scope: 'session'`. */
+    sessionId?: string;
+    /** Which scope to read/write. Default: `user`. */
+    scope?: MemoryScope;
+    /** Optional sub-scope partition (e.g. per-project). */
+    namespace?: string;
+    /** Cencori API key. Sent as `CENCORI_API_KEY`. */
+    apiKey?: string;
+    /** Gateway base URL. Default: `https://cencori.com`. */
+    baseUrl?: string;
+    /** How many memories to list. Default: 50. */
+    limit?: number;
+    /** Skip the initial list on mount. Default: false. */
+    manual?: boolean;
+}
+interface UserMemory {
+    id: string;
+    content: string;
+    namespace?: string | null;
+    importance: number;
+    createdAt: string | null;
+}
+interface UseMemoryResult {
+    /** The user's memories, most recent first. */
+    memories: UserMemory[];
+    /** True during the initial load or a refresh. */
+    loading: boolean;
+    /** Last error message, if any. */
+    error: string | null;
+    /** Re-fetch the list. */
+    refresh: () => Promise<void>;
+    /** Write a new memory for this user. */
+    write: (content: string, opts?: {
+        importance?: number;
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Semantic search over this user's memories (does not mutate the list). */
+    search: (query: string, topK?: number) => Promise<UserMemory[]>;
+    /** Hard-delete a memory by id. */
+    forget: (id: string) => Promise<void>;
+    /** Download every memory as a JSON file (client-side GDPR export). */
+    exportAll: () => Promise<void>;
+}
+declare function useMemory(options: UseMemoryOptions): UseMemoryResult;
+
 type VisionProvider = 'openai' | 'anthropic' | 'google';
 interface VisionFormatBannerProps {
     /** Restrict displayed limits to a specific provider. Omit to show universal (all-provider) limits. */
@@ -49,4 +171,131 @@ interface VisionUploaderProps {
 }
 declare function VisionUploader({ endpoint, apiKey, task, provider, model, prompt, onResult, onError, hideBanner, autoCompress, headers, className, }: VisionUploaderProps): react_jsx_runtime.JSX.Element;
 
-export { VisionFormatBanner, type VisionFormatBannerProps, type VisionProvider, type VisionTask, VisionUploader, type VisionUploaderProps };
+/**
+ * VoiceRecorder
+ *
+ * Drop-in microphone recorder + transcriber for the Cencori Voice API. Records
+ * from the mic, uploads to the transcriptions endpoint, and returns the text.
+ * Zero external state — safe to embed in a customer's own product.
+ *
+ * Usage:
+ *   <VoiceRecorder
+ *       endpoint="https://api.cencori.com/api/ai/audio/transcriptions"
+ *       apiKey={process.env.NEXT_PUBLIC_CENCORI_KEY}
+ *       model="nova-3"
+ *       onTranscript={(text) => console.log(text)}
+ *   />
+ *
+ * Deps: react, lucide-react, tailwindcss.
+ */
+interface VoiceTranscript {
+    text: string;
+    language?: string;
+    duration?: number;
+    provider?: string;
+    model?: string;
+    segments?: Array<{
+        start: number;
+        end: number;
+        text: string;
+        speaker?: string;
+    }>;
+}
+interface VoiceRecorderProps {
+    /** Transcriptions endpoint. Defaults to same-origin `/api/ai/audio/transcriptions`. */
+    endpoint?: string;
+    /** Cencori API key. Sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** Transcription model — provider is inferred from it. Default: `whisper-1`. */
+    model?: string;
+    /** Language hint (e.g. `en`, `yo`, `ha`, `ig`). */
+    language?: string;
+    /** Request speaker labels (use a diarization-capable model). */
+    diarize?: boolean;
+    /** Called with the final transcript text. */
+    onTranscript?: (text: string, full: VoiceTranscript) => void;
+    /** Called on error (before the built-in banner renders it). */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Additional request headers to forward (in addition to Authorization). */
+    headers?: Record<string, string>;
+    /** Extra classes on the root element. */
+    className?: string;
+}
+declare function VoiceRecorder({ endpoint, apiKey, model, language, diarize, onTranscript, onError, headers, className, }: VoiceRecorderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SpeakButton
+ *
+ * Drop-in text-to-speech button for the Cencori Voice API. Synthesizes the
+ * given text and plays it back, with loading/playing/error states. Zero
+ * external state — safe to embed in a customer's own product.
+ *
+ * Usage:
+ *   <SpeakButton
+ *       endpoint="https://api.cencori.com/api/ai/audio/speech"
+ *       apiKey={process.env.NEXT_PUBLIC_CENCORI_KEY}
+ *       text="Hello from Cencori."
+ *       model="aura-asteria-en"
+ *   />
+ *
+ * Deps: react, lucide-react.
+ */
+interface SpeakButtonProps {
+    /** Text to synthesize. */
+    text: string;
+    /** Speech endpoint. Defaults to same-origin `/api/ai/audio/speech`. */
+    endpoint?: string;
+    /** Cencori API key. Sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** TTS model — provider is inferred from it. Default: `tts-1`. */
+    model?: string;
+    /** Voice id/name. Provider-specific. */
+    voice?: string;
+    /** Language code (Spitch: `en`, `yo`, `ha`, `ig`, `am`). */
+    language?: string;
+    /** Button label. Default: "Listen". Pass null to render icon-only. */
+    label?: string | null;
+    /** Additional request headers to forward (in addition to Authorization). */
+    headers?: Record<string, string>;
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    className?: string;
+}
+declare function SpeakButton({ text, endpoint, apiKey, model, voice, language, label, headers, onError, className, }: SpeakButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useVoiceRecorder
+ *
+ * Minimal microphone-recording hook built on the MediaRecorder API. Handles
+ * permission, start/stop, elapsed time, and returns the recorded audio as a
+ * Blob. No external state — safe to use inside a customer's own components.
+ *
+ * Usage:
+ *   const rec = useVoiceRecorder();
+ *   rec.start();            // prompts for mic permission
+ *   const blob = await rec.stop();  // resolves with the recorded audio
+ */
+type RecorderState = 'idle' | 'requesting' | 'recording' | 'stopped' | 'error';
+interface UseVoiceRecorderResult {
+    state: RecorderState;
+    /** Seconds elapsed in the current/last recording. */
+    seconds: number;
+    /** MediaRecorder mime type in use once recording starts. */
+    mimeType: string | null;
+    error: string | null;
+    /** The most recent recording, available after stop(). */
+    blob: Blob | null;
+    start: () => Promise<void>;
+    /** Stop and resolve with the recorded Blob (also set on `blob`). */
+    stop: () => Promise<Blob | null>;
+    /** Discard the current recording and reset to idle. */
+    reset: () => void;
+}
+declare function useVoiceRecorder(): UseVoiceRecorderResult;
+
+export { Chat, type ChatMemoryProp, type ChatMessage, type ChatProps, type MemoryScope, type RecorderState, SpeakButton, type SpeakButtonProps, type UseMemoryOptions, type UseMemoryResult, type UseVoiceRecorderResult, type UserMemory, VisionFormatBanner, type VisionFormatBannerProps, type VisionProvider, type VisionTask, VisionUploader, type VisionUploaderProps, VoiceRecorder, type VoiceRecorderProps, type VoiceTranscript, useMemory, useVoiceRecorder };