mindcache 2.0.0 → 2.3.0

package/dist/{index-CFJtj3DL.d.mts → index-DXb0fL3e.d.mts}

@@ -1,20 +1,40 @@
+/**
+ * Access level for MindCache operations
+ * - 'user': Can only manage content tags (default)
+ * - 'system': Can manage both content tags and system tags
+ */
+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)
+ * - 'protected': Cannot be deleted (replaces hardcoded)
+ * - 'template': Process value through template injection
+ */
+type SystemTag = 'prompt' | 'readonly' | 'protected' | 'template';
 /**
  * Attributes that can be set on a MindCache key
  */
 interface KeyAttributes {
-    /** If true, the key cannot be modified by AI tools */
-    readonly: boolean;
-    /** If true, the key is included in system prompts */
-    visible: boolean;
-    /** If true, the key is a system key that cannot be deleted */
-    hardcoded: boolean;
-    /** If true, the value will be processed through template injection */
-    template: boolean;
     /** The type of value stored */
     type: 'text' | 'image' | 'file' | 'json';
     /** MIME type for files/images */
     contentType?: string;
-    /** Tags for categorizing keys */
+    /** User-defined tags for organizing keys */
+    contentTags: string[];
+    /** System tags that control key behavior (requires system access) */
+    systemTags: SystemTag[];
+    /** Z-index for ordering keys (lower values appear first) */
+    zIndex: number;
+    /** @deprecated Use systemTags.includes('readonly') instead */
+    readonly: boolean;
+    /** @deprecated Use systemTags.includes('prompt') instead */
+    visible: boolean;
+    /** @deprecated Use systemTags.includes('protected') instead */
+    hardcoded: boolean;
+    /** @deprecated Use systemTags.includes('template') instead */
+    template: boolean;
+    /** @deprecated Use contentTags instead */
     tags?: string[];
 }
 /**
@@ -31,9 +51,15 @@ type STM = {
     [key: string]: STMEntry;
 };
 /**
- * A function that is called when a key changes
+ * Listener callback for key-specific subscriptions
+ * Receives the new value when the key changes
+ */
+type Listener = (value: unknown) => void;
+/**
+ * Global listener callback for all changes
+ * Called when any key changes (no parameters - use getAll() to get current state)
  */
-type Listener = () => void;
+type GlobalListener = () => void;
 /**
  * Default attributes for new keys
  */
@@ -60,6 +86,8 @@ interface MindCacheCloudOptions {
 interface MindCacheOptions {
     /** Cloud sync configuration. If omitted, runs in local-only mode. */
     cloud?: MindCacheCloudOptions;
+    /** Access level for tag operations. 'system' allows managing system tags. */
+    accessLevel?: AccessLevel;
 }
 type ConnectionState$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
 declare class MindCache {
@@ -71,7 +99,17 @@ declare class MindCache {
     private _connectionState;
     private _isLoaded;
     private _cloudConfig;
+    private _accessLevel;
+    private _initPromise;
     constructor(options?: MindCacheOptions);
+    /**
+     * Get the current access level
+     */
+    get accessLevel(): AccessLevel;
+    /**
+     * Check if this instance has system-level access
+     */
+    get hasSystemAccess(): boolean;
     private _initCloud;
     /**
      * Get the current cloud connection state
@@ -81,10 +119,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)
      */
@@ -111,6 +159,10 @@ declare class MindCache {
     has(key: string): boolean;
     delete(key: string): boolean;
     clear(): void;
+    /**
+     * Get keys sorted by zIndex (ascending), then by key name
+     */
+    private getSortedKeys;
     keys(): string[];
     values(): any[];
     entries(): [string, any][];
@@ -119,8 +171,8 @@ declare class MindCache {
     update(newValues: Record<string, any>): void;
     subscribe(key: string, listener: Listener): void;
     unsubscribe(key: string, listener: Listener): void;
-    subscribeToAll(listener: Listener): void;
-    unsubscribeFromAll(listener: Listener): void;
+    subscribeToAll(listener: GlobalListener): void;
+    unsubscribeFromAll(listener: GlobalListener): void;
     private notifyGlobalListeners;
     injectSTM(template: string, _processingStack?: Set<string>): string;
     getSTM(): string;
@@ -149,12 +201,63 @@ declare class MindCache {
         key: string;
         value: any;
     } | null;
+    /**
+     * Add a content tag to a key (user-level organization)
+     */
     addTag(key: string, tag: string): boolean;
+    /**
+     * Remove a content tag from a key
+     */
     removeTag(key: string, tag: string): boolean;
+    /**
+     * Get all content tags for a key
+     */
     getTags(key: string): string[];
+    /**
+     * Get all unique content tags across all keys
+     */
     getAllTags(): string[];
+    /**
+     * Check if a key has a specific content tag
+     */
     hasTag(key: string, tag: string): boolean;
+    /**
+     * Get all keys with a specific content tag as formatted string
+     */
     getTagged(tag: string): string;
+    /**
+     * Get all keys with a specific content tag
+     */
+    getKeysByTag(tag: string): string[];
+    /**
+     * Add a system tag to a key (requires system access)
+     * System tags: 'prompt', 'readonly', 'protected', 'template'
+     */
+    systemAddTag(key: string, tag: SystemTag): boolean;
+    /**
+     * Remove a system tag from a key (requires system access)
+     */
+    systemRemoveTag(key: string, tag: SystemTag): boolean;
+    /**
+     * Get all system tags for a key (requires system access)
+     */
+    systemGetTags(key: string): SystemTag[];
+    /**
+     * Check if a key has a specific system tag (requires system access)
+     */
+    systemHasTag(key: string, tag: SystemTag): boolean;
+    /**
+     * Set all system tags for a key at once (requires system access)
+     */
+    systemSetTags(key: string, tags: SystemTag[]): boolean;
+    /**
+     * Get all keys with a specific system tag (requires system access)
+     */
+    systemGetKeysByTag(tag: SystemTag): string[];
+    /**
+     * Helper to sync legacy boolean attributes from system tags
+     */
+    private syncLegacyFromSystemTags;
     toMarkdown(): string;
     fromMarkdown(markdown: string): void;
 }
@@ -210,9 +313,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;
@@ -248,6 +357,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
      */

package/dist/{index-CFJtj3DL.d.ts → index-DXb0fL3e.d.ts}

@@ -1,20 +1,40 @@
+/**
+ * Access level for MindCache operations
+ * - 'user': Can only manage content tags (default)
+ * - 'system': Can manage both content tags and system tags
+ */
+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)
+ * - 'protected': Cannot be deleted (replaces hardcoded)
+ * - 'template': Process value through template injection
+ */
+type SystemTag = 'prompt' | 'readonly' | 'protected' | 'template';
 /**
  * Attributes that can be set on a MindCache key
  */
 interface KeyAttributes {
-    /** If true, the key cannot be modified by AI tools */
-    readonly: boolean;
-    /** If true, the key is included in system prompts */
-    visible: boolean;
-    /** If true, the key is a system key that cannot be deleted */
-    hardcoded: boolean;
-    /** If true, the value will be processed through template injection */
-    template: boolean;
     /** The type of value stored */
     type: 'text' | 'image' | 'file' | 'json';
     /** MIME type for files/images */
     contentType?: string;
-    /** Tags for categorizing keys */
+    /** User-defined tags for organizing keys */
+    contentTags: string[];
+    /** System tags that control key behavior (requires system access) */
+    systemTags: SystemTag[];
+    /** Z-index for ordering keys (lower values appear first) */
+    zIndex: number;
+    /** @deprecated Use systemTags.includes('readonly') instead */
+    readonly: boolean;
+    /** @deprecated Use systemTags.includes('prompt') instead */
+    visible: boolean;
+    /** @deprecated Use systemTags.includes('protected') instead */
+    hardcoded: boolean;
+    /** @deprecated Use systemTags.includes('template') instead */
+    template: boolean;
+    /** @deprecated Use contentTags instead */
     tags?: string[];
 }
 /**
@@ -31,9 +51,15 @@ type STM = {
     [key: string]: STMEntry;
 };
 /**
- * A function that is called when a key changes
+ * Listener callback for key-specific subscriptions
+ * Receives the new value when the key changes
+ */
+type Listener = (value: unknown) => void;
+/**
+ * Global listener callback for all changes
+ * Called when any key changes (no parameters - use getAll() to get current state)
  */
-type Listener = () => void;
+type GlobalListener = () => void;
 /**
  * Default attributes for new keys
  */
@@ -60,6 +86,8 @@ interface MindCacheCloudOptions {
 interface MindCacheOptions {
     /** Cloud sync configuration. If omitted, runs in local-only mode. */
     cloud?: MindCacheCloudOptions;
+    /** Access level for tag operations. 'system' allows managing system tags. */
+    accessLevel?: AccessLevel;
 }
 type ConnectionState$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
 declare class MindCache {
@@ -71,7 +99,17 @@ declare class MindCache {
     private _connectionState;
     private _isLoaded;
     private _cloudConfig;
+    private _accessLevel;
+    private _initPromise;
     constructor(options?: MindCacheOptions);
+    /**
+     * Get the current access level
+     */
+    get accessLevel(): AccessLevel;
+    /**
+     * Check if this instance has system-level access
+     */
+    get hasSystemAccess(): boolean;
     private _initCloud;
     /**
      * Get the current cloud connection state
@@ -81,10 +119,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)
      */
@@ -111,6 +159,10 @@ declare class MindCache {
     has(key: string): boolean;
     delete(key: string): boolean;
     clear(): void;
+    /**
+     * Get keys sorted by zIndex (ascending), then by key name
+     */
+    private getSortedKeys;
     keys(): string[];
     values(): any[];
     entries(): [string, any][];
@@ -119,8 +171,8 @@ declare class MindCache {
     update(newValues: Record<string, any>): void;
     subscribe(key: string, listener: Listener): void;
     unsubscribe(key: string, listener: Listener): void;
-    subscribeToAll(listener: Listener): void;
-    unsubscribeFromAll(listener: Listener): void;
+    subscribeToAll(listener: GlobalListener): void;
+    unsubscribeFromAll(listener: GlobalListener): void;
     private notifyGlobalListeners;
     injectSTM(template: string, _processingStack?: Set<string>): string;
     getSTM(): string;
@@ -149,12 +201,63 @@ declare class MindCache {
         key: string;
         value: any;
     } | null;
+    /**
+     * Add a content tag to a key (user-level organization)
+     */
     addTag(key: string, tag: string): boolean;
+    /**
+     * Remove a content tag from a key
+     */
     removeTag(key: string, tag: string): boolean;
+    /**
+     * Get all content tags for a key
+     */
     getTags(key: string): string[];
+    /**
+     * Get all unique content tags across all keys
+     */
     getAllTags(): string[];
+    /**
+     * Check if a key has a specific content tag
+     */
     hasTag(key: string, tag: string): boolean;
+    /**
+     * Get all keys with a specific content tag as formatted string
+     */
     getTagged(tag: string): string;
+    /**
+     * Get all keys with a specific content tag
+     */
+    getKeysByTag(tag: string): string[];
+    /**
+     * Add a system tag to a key (requires system access)
+     * System tags: 'prompt', 'readonly', 'protected', 'template'
+     */
+    systemAddTag(key: string, tag: SystemTag): boolean;
+    /**
+     * Remove a system tag from a key (requires system access)
+     */
+    systemRemoveTag(key: string, tag: SystemTag): boolean;
+    /**
+     * Get all system tags for a key (requires system access)
+     */
+    systemGetTags(key: string): SystemTag[];
+    /**
+     * Check if a key has a specific system tag (requires system access)
+     */
+    systemHasTag(key: string, tag: SystemTag): boolean;
+    /**
+     * Set all system tags for a key at once (requires system access)
+     */
+    systemSetTags(key: string, tags: SystemTag[]): boolean;
+    /**
+     * Get all keys with a specific system tag (requires system access)
+     */
+    systemGetKeysByTag(tag: SystemTag): string[];
+    /**
+     * Helper to sync legacy boolean attributes from system tags
+     */
+    private syncLegacyFromSystemTags;
     toMarkdown(): string;
     fromMarkdown(markdown: string): void;
 }
@@ -210,9 +313,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;
@@ -248,6 +357,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
      */

package/dist/index.d.mts

@@ -1 +1 @@
-export { a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, i as DEFAULT_KEY_ATTRIBUTES, K as KeyAttributes, L as Listener, M as MindCache, h as MindCacheCloudOptions, g as MindCacheOptions, e as STM, f as STMEntry, m as mindcache } from './index-CFJtj3DL.mjs';
+export { a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, i as DEFAULT_KEY_ATTRIBUTES, K as KeyAttributes, L as Listener, M as MindCache, h as MindCacheCloudOptions, g as MindCacheOptions, e as STM, f as STMEntry, m as mindcache } from './index-DXb0fL3e.mjs';

package/dist/index.d.ts

@@ -1 +1 @@
-export { a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, i as DEFAULT_KEY_ATTRIBUTES, K as KeyAttributes, L as Listener, M as MindCache, h as MindCacheCloudOptions, g as MindCacheOptions, e as STM, f as STMEntry, m as mindcache } from './index-CFJtj3DL.js';
+export { a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, i as DEFAULT_KEY_ATTRIBUTES, K as KeyAttributes, L as Listener, M as MindCache, h as MindCacheCloudOptions, g as MindCacheOptions, e as STM, f as STMEntry, m as mindcache } from './index-DXb0fL3e.js';