@anuma/sdk 3.0.0 → 3.1.1

package/dist/react/index.d.mts

@@ -4232,6 +4232,33 @@ interface CachedServerTools {
     /** Checksum from the server for cache invalidation */
     checksum?: string;
 }
+/**
+ * Pluggable persistence for the fetched server-tools list.
+ *
+ * The default backend ({@link localStorageToolsCache}) writes to browser
+ * `localStorage` and is a silent no-op where `localStorage` is undefined
+ * (Node, React Native). Pass a custom backend to `getServerTools` to cache
+ * somewhere that survives on those platforms — e.g. an AsyncStorage/MMKV
+ * adapter on RN, or an in-memory `Map` on a server. Methods may be sync or
+ * async; `getServerTools` awaits them either way.
+ *
+ * The stored payload carries a `version`; `getServerTools` discards any entry
+ * whose version does not match the current cache format, so a stale custom
+ * backend can never feed an incompatible shape back into selection.
+ */
+interface ToolsCacheBackend {
+    /** Return the cached payload, or null when absent/unreadable. */
+    get(): CachedServerTools | null | Promise<CachedServerTools | null>;
+    /** Persist the payload. Implementations should swallow write failures. */
+    set(value: CachedServerTools): void | Promise<void>;
+    /**
+     * Remove the cached payload. Optional — a read/write-only backend may omit it,
+     * in which case `clearServerToolsCache` (and the version-mismatch
+     * invalidation) is a no-op for that backend. The default
+     * {@link localStorageToolsCache} implements it.
+     */
+    clear?(): void | Promise<void>;
+}
 /**
  * Options for fetching server tools
  */
@@ -4246,6 +4273,12 @@ interface ServerToolsOptions {
     getToken?: () => Promise<string | null>;
     /** Direct API key for server-side usage (uses X-API-Key header) */
     apiKey?: string;
+    /**
+     * Where to read/write the cached tools list. Defaults to
+     * {@link localStorageToolsCache} (browser `localStorage`; no-op elsewhere).
+     * Provide a backend to enable caching on Node / React Native.
+     */
+    cache?: ToolsCacheBackend;
 }
 /** Default cache expiration: 1 day */
 declare const DEFAULT_CACHE_EXPIRATION_MS: number;
@@ -4261,14 +4294,21 @@ interface ParsedServerToolsResponse {
  */
 declare function getCachedServerTools(): CachedServerTools | null;
 /**
- * Clear the server tools cache
+ * Clear the cached server tools. Defaults to the browser-`localStorage` backend;
+ * pass the SAME {@link ToolsCacheBackend} you gave `getServerTools` to invalidate
+ * a custom backend (a no-op when that backend defines no `clear`). Returns the
+ * backend's clear result, which may be async.
  */
 declare function clearServerToolsCache(): void;
+declare function clearServerToolsCache(cache: ToolsCacheBackend): void | Promise<void>;
 /**
- * Get the checksum of currently cached tools.
- * Returns undefined if no cache or no checksum stored.
+ * Get the checksum of the currently cached tools, or undefined when there is no
+ * cache / no stored checksum. Defaults to the browser-`localStorage` backend;
+ * pass the SAME backend you gave `getServerTools` to read a custom backend's
+ * checksum (an async backend yields a promise).
  */
 declare function getToolsChecksum(): string | undefined;
+declare function getToolsChecksum(cache: ToolsCacheBackend): string | undefined | Promise<string | undefined>;
 /**
  * Check if tools should be refreshed based on checksum comparison.
  * Returns true if:
@@ -4280,11 +4320,12 @@ declare function getToolsChecksum(): string | undefined;
  * - Checksums match
  */
 declare function shouldRefreshTools(responseChecksum: string | undefined): boolean;
+declare function shouldRefreshTools(responseChecksum: string | undefined, cache: ToolsCacheBackend | undefined): boolean | Promise<boolean>;
 /**
  * Get server tools with caching support.
  *
  * Flow:
- * 1. Check localStorage cache
+ * 1. Check the cache backend (localStorage by default; override via `cache`)
  * 2. If cache valid and not force refresh, return cached tools
  * 3. Otherwise, fetch from API, cache, and return
  * 4. On fetch failure, return cached tools if available (stale-while-error)
@@ -4574,6 +4615,11 @@ interface SelectServerToolsForPromptOptions {
     embeddingModel?: string;
     /** Cache expiration in ms for the server-tools catalog fetch. */
     cacheExpirationMs?: number;
+    /**
+     * Where to read/write the cached catalog. Defaults to browser `localStorage`
+     * (a no-op on Node/RN); pass a backend to persist on those platforms.
+     */
+    cache?: ToolsCacheBackend;
     /**
      * Phase 3 defer-loading. When `enabled`, this helper returns the FULL catalog (skipping semantic/
      * static filtering) to mirror useChatStorage's responses send path, which swaps in the full catalog
@@ -4993,6 +5039,13 @@ interface BaseUseChatStorageOptions {
          * {@link DeferLoadingConfig}.
          */
         deferLoading?: DeferLoadingConfig;
+        /**
+         * Where to read/write the cached server-tools catalog. Defaults to browser
+         * `localStorage`, which is a silent no-op on React Native — so on RN pass an
+         * AsyncStorage/MMKV-backed {@link ToolsCacheBackend} here or every send
+         * refetches the whole catalog. Forwarded to `getServerTools`.
+         */
+        cache?: ToolsCacheBackend;
     };
     /**
      * Automatically generate embeddings for messages after saving.
@@ -7064,14 +7117,14 @@ declare function createChunkVectorCache(maxSize?: number): ChunkVectorCache;
 declare function recall(query: string, ctx: RecallContext, options?: RecallOptions): Promise<RecallResult>;
 
 /**
- * Unified Recall Tool
+ * Recall tool constants — deliberately dependency-free.
  *
- * Single chat-completion tool that searches both vault facts and
- * conversation chunks via `recall()`. Replaces the legacy pair of
- * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
- * longer has to route between two tools.
+ * Split out of `recallTool.ts` so the tool NAME can be referenced from
+ * node/React-Native-safe modules (e.g. the client-tool selector in
+ * `../tools/clientToolSelection`) without dragging `recall()` and its
+ * WatermelonDB-backed operations into the module graph. `recallTool.ts`
+ * re-exports these to preserve their public identity.
  */
-
 /** Tool name surfaced to the LLM. Exported so bench harnesses and chat
  * clients reference the same string — drift between prod and bench would
  * mask tool-routing bugs in eval. */
@@ -7079,6 +7132,16 @@ declare const RECALL_TOOL_NAME = "recall_memory";
 /** Maximum results the executor will return to the LLM, regardless of
  * the LLM-supplied `limit`. */
 declare const RECALL_MAX_LIMIT = 50;
+
+/**
+ * Unified Recall Tool
+ *
+ * Single chat-completion tool that searches both vault facts and
+ * conversation chunks via `recall()`. Replaces the legacy pair of
+ * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
+ * longer has to route between two tools.
+ */
+
 interface RecallToolOptions {
     /** Lanes to search. Default: ["fact", "chunk"]. */
     types?: MemoryKind[];
@@ -7382,11 +7445,26 @@ declare function chunkText(text: string, options?: ChunkingOptions): TextChunk[]
 declare function shouldChunkMessage(content: string, chunkSize?: number): boolean;
 
 /**
- * Memory Retrieval Embeddings
+ * Embedding generation — dependency-free core.
+ *
+ * The raw "text → embedding" calls, split out of `embeddings.ts` so they can be
+ * imported by node/React-Native-safe modules (the server-tool + client-tool
+ * selection engine in `../tools`) WITHOUT pulling in the WatermelonDB-backed
+ * `db/chat/operations` that `embeddings.ts` needs for its message-persistence
+ * helpers (`embedMessage`, `embedAllMessages`, `chunkAndEmbed*`).
  *
- * Functions for generating and storing embeddings for conversation messages.
+ * Nothing here touches the database; the only I/O is the HTTP embeddings
+ * endpoint. `embeddings.ts` re-exports these so existing importers of
+ * `../memoryEngine/embeddings` (and the `../memoryEngine` barrel) keep working.
  */
 
+/**
+ * Generate an embedding for text using the API
+ *
+ * Supports two auth methods:
+ * - `apiKey`: Uses X-API-Key header (for server-side/CLI usage)
+ * - `getToken`: Uses Authorization: Bearer header (for Privy identity tokens)
+ */
 declare function generateEmbedding(text: string, options: EmbeddingOptions): Promise<number[]>;
 /**
  * Generate embeddings for multiple texts, automatically chunking large inputs.
@@ -7401,6 +7479,18 @@ declare function generateEmbedding(text: string, options: EmbeddingOptions): Pro
  * @returns Array of embeddings in the same order as input texts
  */
 declare function generateEmbeddings(texts: string[], options: EmbeddingOptions): Promise<number[][]>;
+
+/**
+ * Memory Retrieval Embeddings
+ *
+ * Message-level embedding + persistence helpers: find messages via the
+ * WatermelonDB-backed `db/chat/operations`, embed their content, and store the
+ * vectors/chunks back. The raw "text → embedding" calls live in `./generate`
+ * (dependency-free so the tool-selection engine can import them without the DB
+ * layer) and are re-exported here so existing importers of
+ * `../memoryEngine/embeddings` and the `../memoryEngine` barrel keep working.
+ */
+
 /**
  * Embed a single message and store the embedding in the database
  *
@@ -7688,6 +7778,7 @@ declare function previewToolSelection(options: {
     serverToolsConfig?: {
         cacheExpirationMs?: number;
         deferLoading?: DeferLoadingConfig;
+        cache?: ToolsCacheBackend;
     };
     /** Bearer-token auth (browser sessions). Provide this or `apiKey`. */
     getToken?: () => Promise<string | null>;

package/dist/react/index.d.ts

@@ -4232,6 +4232,33 @@ interface CachedServerTools {
     /** Checksum from the server for cache invalidation */
     checksum?: string;
 }
+/**
+ * Pluggable persistence for the fetched server-tools list.
+ *
+ * The default backend ({@link localStorageToolsCache}) writes to browser
+ * `localStorage` and is a silent no-op where `localStorage` is undefined
+ * (Node, React Native). Pass a custom backend to `getServerTools` to cache
+ * somewhere that survives on those platforms — e.g. an AsyncStorage/MMKV
+ * adapter on RN, or an in-memory `Map` on a server. Methods may be sync or
+ * async; `getServerTools` awaits them either way.
+ *
+ * The stored payload carries a `version`; `getServerTools` discards any entry
+ * whose version does not match the current cache format, so a stale custom
+ * backend can never feed an incompatible shape back into selection.
+ */
+interface ToolsCacheBackend {
+    /** Return the cached payload, or null when absent/unreadable. */
+    get(): CachedServerTools | null | Promise<CachedServerTools | null>;
+    /** Persist the payload. Implementations should swallow write failures. */
+    set(value: CachedServerTools): void | Promise<void>;
+    /**
+     * Remove the cached payload. Optional — a read/write-only backend may omit it,
+     * in which case `clearServerToolsCache` (and the version-mismatch
+     * invalidation) is a no-op for that backend. The default
+     * {@link localStorageToolsCache} implements it.
+     */
+    clear?(): void | Promise<void>;
+}
 /**
  * Options for fetching server tools
  */
@@ -4246,6 +4273,12 @@ interface ServerToolsOptions {
     getToken?: () => Promise<string | null>;
     /** Direct API key for server-side usage (uses X-API-Key header) */
     apiKey?: string;
+    /**
+     * Where to read/write the cached tools list. Defaults to
+     * {@link localStorageToolsCache} (browser `localStorage`; no-op elsewhere).
+     * Provide a backend to enable caching on Node / React Native.
+     */
+    cache?: ToolsCacheBackend;
 }
 /** Default cache expiration: 1 day */
 declare const DEFAULT_CACHE_EXPIRATION_MS: number;
@@ -4261,14 +4294,21 @@ interface ParsedServerToolsResponse {
  */
 declare function getCachedServerTools(): CachedServerTools | null;
 /**
- * Clear the server tools cache
+ * Clear the cached server tools. Defaults to the browser-`localStorage` backend;
+ * pass the SAME {@link ToolsCacheBackend} you gave `getServerTools` to invalidate
+ * a custom backend (a no-op when that backend defines no `clear`). Returns the
+ * backend's clear result, which may be async.
  */
 declare function clearServerToolsCache(): void;
+declare function clearServerToolsCache(cache: ToolsCacheBackend): void | Promise<void>;
 /**
- * Get the checksum of currently cached tools.
- * Returns undefined if no cache or no checksum stored.
+ * Get the checksum of the currently cached tools, or undefined when there is no
+ * cache / no stored checksum. Defaults to the browser-`localStorage` backend;
+ * pass the SAME backend you gave `getServerTools` to read a custom backend's
+ * checksum (an async backend yields a promise).
  */
 declare function getToolsChecksum(): string | undefined;
+declare function getToolsChecksum(cache: ToolsCacheBackend): string | undefined | Promise<string | undefined>;
 /**
  * Check if tools should be refreshed based on checksum comparison.
  * Returns true if:
@@ -4280,11 +4320,12 @@ declare function getToolsChecksum(): string | undefined;
  * - Checksums match
  */
 declare function shouldRefreshTools(responseChecksum: string | undefined): boolean;
+declare function shouldRefreshTools(responseChecksum: string | undefined, cache: ToolsCacheBackend | undefined): boolean | Promise<boolean>;
 /**
  * Get server tools with caching support.
  *
  * Flow:
- * 1. Check localStorage cache
+ * 1. Check the cache backend (localStorage by default; override via `cache`)
  * 2. If cache valid and not force refresh, return cached tools
  * 3. Otherwise, fetch from API, cache, and return
  * 4. On fetch failure, return cached tools if available (stale-while-error)
@@ -4574,6 +4615,11 @@ interface SelectServerToolsForPromptOptions {
     embeddingModel?: string;
     /** Cache expiration in ms for the server-tools catalog fetch. */
     cacheExpirationMs?: number;
+    /**
+     * Where to read/write the cached catalog. Defaults to browser `localStorage`
+     * (a no-op on Node/RN); pass a backend to persist on those platforms.
+     */
+    cache?: ToolsCacheBackend;
     /**
      * Phase 3 defer-loading. When `enabled`, this helper returns the FULL catalog (skipping semantic/
      * static filtering) to mirror useChatStorage's responses send path, which swaps in the full catalog
@@ -4993,6 +5039,13 @@ interface BaseUseChatStorageOptions {
          * {@link DeferLoadingConfig}.
          */
         deferLoading?: DeferLoadingConfig;
+        /**
+         * Where to read/write the cached server-tools catalog. Defaults to browser
+         * `localStorage`, which is a silent no-op on React Native — so on RN pass an
+         * AsyncStorage/MMKV-backed {@link ToolsCacheBackend} here or every send
+         * refetches the whole catalog. Forwarded to `getServerTools`.
+         */
+        cache?: ToolsCacheBackend;
     };
     /**
      * Automatically generate embeddings for messages after saving.
@@ -7064,14 +7117,14 @@ declare function createChunkVectorCache(maxSize?: number): ChunkVectorCache;
 declare function recall(query: string, ctx: RecallContext, options?: RecallOptions): Promise<RecallResult>;
 
 /**
- * Unified Recall Tool
+ * Recall tool constants — deliberately dependency-free.
  *
- * Single chat-completion tool that searches both vault facts and
- * conversation chunks via `recall()`. Replaces the legacy pair of
- * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
- * longer has to route between two tools.
+ * Split out of `recallTool.ts` so the tool NAME can be referenced from
+ * node/React-Native-safe modules (e.g. the client-tool selector in
+ * `../tools/clientToolSelection`) without dragging `recall()` and its
+ * WatermelonDB-backed operations into the module graph. `recallTool.ts`
+ * re-exports these to preserve their public identity.
  */
-
 /** Tool name surfaced to the LLM. Exported so bench harnesses and chat
  * clients reference the same string — drift between prod and bench would
  * mask tool-routing bugs in eval. */
@@ -7079,6 +7132,16 @@ declare const RECALL_TOOL_NAME = "recall_memory";
 /** Maximum results the executor will return to the LLM, regardless of
  * the LLM-supplied `limit`. */
 declare const RECALL_MAX_LIMIT = 50;
+
+/**
+ * Unified Recall Tool
+ *
+ * Single chat-completion tool that searches both vault facts and
+ * conversation chunks via `recall()`. Replaces the legacy pair of
+ * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
+ * longer has to route between two tools.
+ */
+
 interface RecallToolOptions {
     /** Lanes to search. Default: ["fact", "chunk"]. */
     types?: MemoryKind[];
@@ -7382,11 +7445,26 @@ declare function chunkText(text: string, options?: ChunkingOptions): TextChunk[]
 declare function shouldChunkMessage(content: string, chunkSize?: number): boolean;
 
 /**
- * Memory Retrieval Embeddings
+ * Embedding generation — dependency-free core.
+ *
+ * The raw "text → embedding" calls, split out of `embeddings.ts` so they can be
+ * imported by node/React-Native-safe modules (the server-tool + client-tool
+ * selection engine in `../tools`) WITHOUT pulling in the WatermelonDB-backed
+ * `db/chat/operations` that `embeddings.ts` needs for its message-persistence
+ * helpers (`embedMessage`, `embedAllMessages`, `chunkAndEmbed*`).
  *
- * Functions for generating and storing embeddings for conversation messages.
+ * Nothing here touches the database; the only I/O is the HTTP embeddings
+ * endpoint. `embeddings.ts` re-exports these so existing importers of
+ * `../memoryEngine/embeddings` (and the `../memoryEngine` barrel) keep working.
  */
 
+/**
+ * Generate an embedding for text using the API
+ *
+ * Supports two auth methods:
+ * - `apiKey`: Uses X-API-Key header (for server-side/CLI usage)
+ * - `getToken`: Uses Authorization: Bearer header (for Privy identity tokens)
+ */
 declare function generateEmbedding(text: string, options: EmbeddingOptions): Promise<number[]>;
 /**
  * Generate embeddings for multiple texts, automatically chunking large inputs.
@@ -7401,6 +7479,18 @@ declare function generateEmbedding(text: string, options: EmbeddingOptions): Pro
  * @returns Array of embeddings in the same order as input texts
  */
 declare function generateEmbeddings(texts: string[], options: EmbeddingOptions): Promise<number[][]>;
+
+/**
+ * Memory Retrieval Embeddings
+ *
+ * Message-level embedding + persistence helpers: find messages via the
+ * WatermelonDB-backed `db/chat/operations`, embed their content, and store the
+ * vectors/chunks back. The raw "text → embedding" calls live in `./generate`
+ * (dependency-free so the tool-selection engine can import them without the DB
+ * layer) and are re-exported here so existing importers of
+ * `../memoryEngine/embeddings` and the `../memoryEngine` barrel keep working.
+ */
+
 /**
  * Embed a single message and store the embedding in the database
  *
@@ -7688,6 +7778,7 @@ declare function previewToolSelection(options: {
     serverToolsConfig?: {
         cacheExpirationMs?: number;
         deferLoading?: DeferLoadingConfig;
+        cache?: ToolsCacheBackend;
     };
     /** Bearer-token auth (browser sessions). Provide this or `apiKey`. */
     getToken?: () => Promise<string | null>;