mindcache 2.2.0 → 2.4.0

package/dist/{index-XM7bmK7C.d.mts → CloudAdapter-B04-OWx3.d.mts}

@@ -6,12 +6,17 @@
 type AccessLevel = 'user' | 'system';
 /**
  * Known system tags that control key behavior
- * - 'prompt': Include in system prompt (replaces visible)
- * - 'readonly': Cannot be modified by AI tools (replaces readonly)
+ * - 'SystemPrompt': Include in system prompt
+ * - 'LLMRead': LLM can read this key (visible to LLMs)
+ * - 'LLMWrite': LLM can write to this key via tools
  * - 'protected': Cannot be deleted (replaces hardcoded)
- * - 'template': Process value through template injection
+ * - 'ApplyTemplate': Process value through template injection
+ *
+ * @deprecated 'prompt' - Use 'SystemPrompt' instead
+ * @deprecated 'readonly' - Use absence of 'LLMWrite' instead (if LLMWrite not present, readonly=true)
+ * @deprecated 'template' - Use 'ApplyTemplate' instead
  */
-type SystemTag = 'prompt' | 'readonly' | 'protected' | 'template';
+type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'protected' | 'ApplyTemplate' | 'prompt' | 'readonly' | 'template';
 /**
  * Attributes that can be set on a MindCache key
  */
@@ -26,13 +31,13 @@ interface KeyAttributes {
     systemTags: SystemTag[];
     /** Z-index for ordering keys (lower values appear first) */
     zIndex: number;
-    /** @deprecated Use systemTags.includes('readonly') instead */
+    /** @deprecated Use !systemTags.includes('LLMWrite') instead */
     readonly: boolean;
-    /** @deprecated Use systemTags.includes('prompt') instead */
+    /** @deprecated Use systemTags.includes('SystemPrompt') instead */
     visible: boolean;
     /** @deprecated Use systemTags.includes('protected') instead */
     hardcoded: boolean;
-    /** @deprecated Use systemTags.includes('template') instead */
+    /** @deprecated Use systemTags.includes('ApplyTemplate') instead */
     template: boolean;
     /** @deprecated Use contentTags instead */
     tags?: string[];
@@ -80,12 +85,24 @@ interface MindCacheCloudOptions {
     /** WebSocket base URL (defaults to production) */
     baseUrl?: string;
 }
+interface MindCacheIndexedDBOptions {
+    /** Database name (defaults to 'mindcache_db') */
+    dbName?: string;
+    /** Store name (defaults to 'mindcache_store') */
+    storeName?: string;
+    /** Storage key (defaults to 'mindcache_data') */
+    key?: string;
+    /** Debounce time in ms for saving (defaults to 1000) */
+    debounceMs?: number;
+}
 /**
  * Constructor options for MindCache
  */
 interface MindCacheOptions {
     /** Cloud sync configuration. If omitted, runs in local-only mode. */
     cloud?: MindCacheCloudOptions;
+    /** IndexedDB configuration */
+    indexedDB?: MindCacheIndexedDBOptions;
     /** Access level for tag operations. 'system' allows managing system tags. */
     accessLevel?: AccessLevel;
 }
@@ -95,11 +112,30 @@ declare class MindCache {
     private listeners;
     private globalListeners;
     private _isRemoteUpdate;
+    /**
+     * Normalize system tags: migrate old tags to new ones
+     * - 'prompt' → 'SystemPrompt'
+     * - 'readonly' → remove 'LLMWrite' (or add if not readonly)
+     */
+    private normalizeSystemTags;
+    /**
+     * Check if key should be visible in system prompt
+     */
+    private hasSystemPrompt;
+    /**
+     * Check if key can be read by LLM (has LLMRead or SystemPrompt)
+     */
+    private hasLLMRead;
+    /**
+     * Check if key can be written by LLM (has LLMWrite and not readonly)
+     */
+    private hasLLMWrite;
     private _cloudAdapter;
     private _connectionState;
     private _isLoaded;
     private _cloudConfig;
     private _accessLevel;
+    private _initPromise;
     constructor(options?: MindCacheOptions);
     /**
      * Get the current access level
@@ -110,6 +146,8 @@ declare class MindCache {
      */
     get hasSystemAccess(): boolean;
     private _initCloud;
+    private _initIndexedDB;
+    protected _getIndexedDBAdapterClass(): Promise<any>;
     /**
      * Get the current cloud connection state
      */
@@ -118,10 +156,20 @@ declare class MindCache {
      * Check if data is loaded (true for local, true after sync for cloud)
      */
     get isLoaded(): boolean;
+    /**
+     * Protected method to load CloudAdapter class.
+     * Can be overridden/mocked for testing.
+     */
+    protected _getCloudAdapterClass(): Promise<any>;
     /**
      * Check if this instance is connected to cloud
      */
     get isCloud(): boolean;
+    /**
+     * Wait for initial sync to complete (or resolve immediately if already synced/local).
+     * Useful for scripts or linear execution flows.
+     */
+    waitForSync(): Promise<void>;
     /**
      * Disconnect from cloud (if connected)
      */
@@ -302,9 +350,15 @@ interface CloudAdapterEvents {
  * CloudAdapter connects a MindCache instance to the cloud service
  * for real-time sync and persistence.
  *
- * Auth modes:
- * 1. Token (recommended): Pass a short-lived token from /api/ws-token
- * 2. API Key (server-to-server): Pass apiKey for direct connections
+ * Auth flow:
+ * 1. SDK calls POST /api/ws-token with apiKey to get short-lived token
+ * 2. SDK connects to WebSocket with token in query string
+ * 3. Server validates token and upgrades to WebSocket
+ *
+ * Usage patterns:
+ * - apiKey: SDK fetches tokens automatically (simple, good for demos)
+ * - tokenEndpoint: Your backend fetches tokens (secure, apiKey stays server-side)
+ * - tokenProvider: Custom token logic (advanced)
  */
 declare class CloudAdapter {
     private config;
@@ -340,6 +394,16 @@ declare class CloudAdapter {
      * Detach from the MindCache instance
      */
     detach(): void;
+    /**
+     * Fetch a short-lived WebSocket token from the API using the API key.
+     * This keeps the API key secure by only using it for a single HTTPS request,
+     * then using the short-lived token for the WebSocket connection.
+     *
+     * Supports two key formats:
+     * - API keys: mc_live_xxx or mc_test_xxx → Bearer token
+     * - Delegate keys: del_xxx:sec_xxx → ApiKey format
+     */
+    private fetchTokenWithApiKey;
     /**
      * Connect to the cloud service
      */
@@ -368,4 +432,4 @@ declare class CloudAdapter {
     private syncLocalChanges;
 }
 
-export { type CloudConfig as C, type DeleteOperation as D, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type SetOperation as S, CloudAdapter as a, type ConnectionState as b, type CloudAdapterEvents as c, type ClearOperation as d, type STM as e, type STMEntry as f, type MindCacheOptions as g, type MindCacheCloudOptions as h, DEFAULT_KEY_ATTRIBUTES as i, mindcache as m };
+export { CloudAdapter as C, DEFAULT_KEY_ATTRIBUTES as D, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type STM as S, type MindCacheOptions as a, type STMEntry as b, type MindCacheCloudOptions as c, type MindCacheIndexedDBOptions as d, type CloudConfig as e, type ConnectionState as f, type CloudAdapterEvents as g, type SetOperation as h, type DeleteOperation as i, type ClearOperation as j, mindcache as m };

package/dist/{index-XM7bmK7C.d.ts → CloudAdapter-B04-OWx3.d.ts}

@@ -6,12 +6,17 @@
 type AccessLevel = 'user' | 'system';
 /**
  * Known system tags that control key behavior
- * - 'prompt': Include in system prompt (replaces visible)
- * - 'readonly': Cannot be modified by AI tools (replaces readonly)
+ * - 'SystemPrompt': Include in system prompt
+ * - 'LLMRead': LLM can read this key (visible to LLMs)
+ * - 'LLMWrite': LLM can write to this key via tools
  * - 'protected': Cannot be deleted (replaces hardcoded)
- * - 'template': Process value through template injection
+ * - 'ApplyTemplate': Process value through template injection
+ *
+ * @deprecated 'prompt' - Use 'SystemPrompt' instead
+ * @deprecated 'readonly' - Use absence of 'LLMWrite' instead (if LLMWrite not present, readonly=true)
+ * @deprecated 'template' - Use 'ApplyTemplate' instead
  */
-type SystemTag = 'prompt' | 'readonly' | 'protected' | 'template';
+type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'protected' | 'ApplyTemplate' | 'prompt' | 'readonly' | 'template';
 /**
  * Attributes that can be set on a MindCache key
  */
@@ -26,13 +31,13 @@ interface KeyAttributes {
     systemTags: SystemTag[];
     /** Z-index for ordering keys (lower values appear first) */
     zIndex: number;
-    /** @deprecated Use systemTags.includes('readonly') instead */
+    /** @deprecated Use !systemTags.includes('LLMWrite') instead */
     readonly: boolean;
-    /** @deprecated Use systemTags.includes('prompt') instead */
+    /** @deprecated Use systemTags.includes('SystemPrompt') instead */
     visible: boolean;
     /** @deprecated Use systemTags.includes('protected') instead */
     hardcoded: boolean;
-    /** @deprecated Use systemTags.includes('template') instead */
+    /** @deprecated Use systemTags.includes('ApplyTemplate') instead */
     template: boolean;
     /** @deprecated Use contentTags instead */
     tags?: string[];
@@ -80,12 +85,24 @@ interface MindCacheCloudOptions {
     /** WebSocket base URL (defaults to production) */
     baseUrl?: string;
 }
+interface MindCacheIndexedDBOptions {
+    /** Database name (defaults to 'mindcache_db') */
+    dbName?: string;
+    /** Store name (defaults to 'mindcache_store') */
+    storeName?: string;
+    /** Storage key (defaults to 'mindcache_data') */
+    key?: string;
+    /** Debounce time in ms for saving (defaults to 1000) */
+    debounceMs?: number;
+}
 /**
  * Constructor options for MindCache
  */
 interface MindCacheOptions {
     /** Cloud sync configuration. If omitted, runs in local-only mode. */
     cloud?: MindCacheCloudOptions;
+    /** IndexedDB configuration */
+    indexedDB?: MindCacheIndexedDBOptions;
     /** Access level for tag operations. 'system' allows managing system tags. */
     accessLevel?: AccessLevel;
 }
@@ -95,11 +112,30 @@ declare class MindCache {
     private listeners;
     private globalListeners;
     private _isRemoteUpdate;
+    /**
+     * Normalize system tags: migrate old tags to new ones
+     * - 'prompt' → 'SystemPrompt'
+     * - 'readonly' → remove 'LLMWrite' (or add if not readonly)
+     */
+    private normalizeSystemTags;
+    /**
+     * Check if key should be visible in system prompt
+     */
+    private hasSystemPrompt;
+    /**
+     * Check if key can be read by LLM (has LLMRead or SystemPrompt)
+     */
+    private hasLLMRead;
+    /**
+     * Check if key can be written by LLM (has LLMWrite and not readonly)
+     */
+    private hasLLMWrite;
     private _cloudAdapter;
     private _connectionState;
     private _isLoaded;
     private _cloudConfig;
     private _accessLevel;
+    private _initPromise;
     constructor(options?: MindCacheOptions);
     /**
      * Get the current access level
@@ -110,6 +146,8 @@ declare class MindCache {
      */
     get hasSystemAccess(): boolean;
     private _initCloud;
+    private _initIndexedDB;
+    protected _getIndexedDBAdapterClass(): Promise<any>;
     /**
      * Get the current cloud connection state
      */
@@ -118,10 +156,20 @@ declare class MindCache {
      * Check if data is loaded (true for local, true after sync for cloud)
      */
     get isLoaded(): boolean;
+    /**
+     * Protected method to load CloudAdapter class.
+     * Can be overridden/mocked for testing.
+     */
+    protected _getCloudAdapterClass(): Promise<any>;
     /**
      * Check if this instance is connected to cloud
      */
     get isCloud(): boolean;
+    /**
+     * Wait for initial sync to complete (or resolve immediately if already synced/local).
+     * Useful for scripts or linear execution flows.
+     */
+    waitForSync(): Promise<void>;
     /**
      * Disconnect from cloud (if connected)
      */
@@ -302,9 +350,15 @@ interface CloudAdapterEvents {
  * CloudAdapter connects a MindCache instance to the cloud service
  * for real-time sync and persistence.
  *
- * Auth modes:
- * 1. Token (recommended): Pass a short-lived token from /api/ws-token
- * 2. API Key (server-to-server): Pass apiKey for direct connections
+ * Auth flow:
+ * 1. SDK calls POST /api/ws-token with apiKey to get short-lived token
+ * 2. SDK connects to WebSocket with token in query string
+ * 3. Server validates token and upgrades to WebSocket
+ *
+ * Usage patterns:
+ * - apiKey: SDK fetches tokens automatically (simple, good for demos)
+ * - tokenEndpoint: Your backend fetches tokens (secure, apiKey stays server-side)
+ * - tokenProvider: Custom token logic (advanced)
  */
 declare class CloudAdapter {
     private config;
@@ -340,6 +394,16 @@ declare class CloudAdapter {
      * Detach from the MindCache instance
      */
     detach(): void;
+    /**
+     * Fetch a short-lived WebSocket token from the API using the API key.
+     * This keeps the API key secure by only using it for a single HTTPS request,
+     * then using the short-lived token for the WebSocket connection.
+     *
+     * Supports two key formats:
+     * - API keys: mc_live_xxx or mc_test_xxx → Bearer token
+     * - Delegate keys: del_xxx:sec_xxx → ApiKey format
+     */
+    private fetchTokenWithApiKey;
     /**
      * Connect to the cloud service
      */
@@ -368,4 +432,4 @@ declare class CloudAdapter {
     private syncLocalChanges;
 }
 
-export { type CloudConfig as C, type DeleteOperation as D, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type SetOperation as S, CloudAdapter as a, type ConnectionState as b, type CloudAdapterEvents as c, type ClearOperation as d, type STM as e, type STMEntry as f, type MindCacheOptions as g, type MindCacheCloudOptions as h, DEFAULT_KEY_ATTRIBUTES as i, mindcache as m };
+export { CloudAdapter as C, DEFAULT_KEY_ATTRIBUTES as D, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type STM as S, type MindCacheOptions as a, type STMEntry as b, type MindCacheCloudOptions as c, type MindCacheIndexedDBOptions as d, type CloudConfig as e, type ConnectionState as f, type CloudAdapterEvents as g, type SetOperation as h, type DeleteOperation as i, type ClearOperation as j, mindcache as m };

package/dist/cloud/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../index-XM7bmK7C.mjs';
-export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../index-XM7bmK7C.mjs';
+import { M as MindCache, e as CloudConfig, C as CloudAdapter } from '../CloudAdapter-B04-OWx3.mjs';
+export { j as ClearOperation, g as CloudAdapterEvents, f as ConnectionState, i as DeleteOperation, O as Operation, h as SetOperation } from '../CloudAdapter-B04-OWx3.mjs';
 
 /**
  * Connect a MindCache instance to the cloud for real-time sync.

package/dist/cloud/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../index-XM7bmK7C.js';
-export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../index-XM7bmK7C.js';
+import { M as MindCache, e as CloudConfig, C as CloudAdapter } from '../CloudAdapter-B04-OWx3.js';
+export { j as ClearOperation, g as CloudAdapterEvents, f as ConnectionState, i as DeleteOperation, O as Operation, h as SetOperation } from '../CloudAdapter-B04-OWx3.js';
 
 /**
  * Connect a MindCache instance to the cloud for real-time sync.