mindcache 2.4.0 → 3.1.0

package/dist/{CloudAdapter-B04-OWx3.d.mts → CloudAdapter-Bx-ITNdi.d.mts}

@@ -1,3 +1,5 @@
+import * as Y from 'yjs';
+
 /**
  * Access level for MindCache operations
  * - 'user': Can only manage content tags (default)
@@ -22,7 +24,7 @@ type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'protected' | 'ApplyT
  */
 interface KeyAttributes {
     /** The type of value stored */
-    type: 'text' | 'image' | 'file' | 'json';
+    type: 'text' | 'image' | 'file' | 'json' | 'document';
     /** MIME type for files/images */
     contentType?: string;
     /** User-defined tags for organizing keys */
@@ -69,6 +71,26 @@ type GlobalListener = () => void;
  * Default attributes for new keys
  */
 declare const DEFAULT_KEY_ATTRIBUTES: KeyAttributes;
+/**
+ * A single entry in the global history log
+ */
+interface HistoryEntry {
+    /** Unique identifier for this history entry */
+    id: string;
+    /** Timestamp when the change occurred */
+    timestamp: number;
+    /** Keys that were affected by this change */
+    keysAffected?: string[];
+}
+/**
+ * History options for offline and cloud modes
+ */
+interface HistoryOptions {
+    /** Max history entries to keep (default: 100) */
+    maxEntries?: number;
+    /** Save full snapshot every N entries for fast restore (default: 10) */
+    snapshotInterval?: number;
+}
 
 /**
  * Cloud configuration options for MindCache constructor
@@ -99,206 +121,174 @@ interface MindCacheIndexedDBOptions {
  * Constructor options for MindCache
  */
 interface MindCacheOptions {
-    /** Cloud sync configuration. If omitted, runs in local-only mode. */
+    /** Cloud sync configuration. If omitted, runs in local-only mode. IndexedDB auto-enabled for offline support. */
     cloud?: MindCacheCloudOptions;
-    /** IndexedDB configuration */
+    /** IndexedDB configuration. Ignored in cloud mode (auto-enabled). */
     indexedDB?: MindCacheIndexedDBOptions;
+    /** History tracking options (enabled in IndexedDB and Cloud modes) */
+    history?: HistoryOptions;
     /** Access level for tag operations. 'system' allows managing system tags. */
     accessLevel?: AccessLevel;
 }
 type ConnectionState$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
 declare class MindCache {
-    private stm;
+    doc: Y.Doc;
+    private rootMap;
     private listeners;
     private globalListeners;
+    readonly version = "3.1.0";
     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;
+    private _idbProvider;
+    private _undoManagers;
+    private _globalUndoManager;
+    private _history;
+    private _historyOptions;
+    private _historyEnabled;
     constructor(options?: MindCacheOptions);
+    private getUndoManager;
     /**
-     * Get the current access level
+     * Undo changes for a specific key
      */
-    get accessLevel(): AccessLevel;
+    undo(key: string): void;
     /**
-     * Check if this instance has system-level access
+     * Redo changes for a specific key
      */
-    get hasSystemAccess(): boolean;
-    private _initCloud;
-    private _initIndexedDB;
-    protected _getIndexedDBAdapterClass(): Promise<any>;
+    redo(key: string): void;
+    getHistory(key: string): any[];
+    private initGlobalUndoManager;
     /**
-     * Get the current cloud connection state
+     * Undo all recent local changes (across all keys)
+     * Only undoes YOUR changes, not changes from other users in cloud mode
      */
-    get connectionState(): ConnectionState$1;
+    undoAll(): void;
     /**
-     * Check if data is loaded (true for local, true after sync for cloud)
+     * Redo previously undone local changes
      */
-    get isLoaded(): boolean;
+    redoAll(): void;
     /**
-     * Protected method to load CloudAdapter class.
-     * Can be overridden/mocked for testing.
+     * Check if there are changes to undo globally
      */
-    protected _getCloudAdapterClass(): Promise<any>;
+    canUndoAll(): boolean;
     /**
-     * Check if this instance is connected to cloud
+     * Check if there are changes to redo globally
      */
-    get isCloud(): boolean;
+    canRedoAll(): boolean;
+    private enableHistory;
+    private generateId;
     /**
-     * Wait for initial sync to complete (or resolve immediately if already synced/local).
-     * Useful for scripts or linear execution flows.
+     * Get global history of all changes (available in IndexedDB and Cloud modes)
      */
-    waitForSync(): Promise<void>;
+    getGlobalHistory(): HistoryEntry[];
     /**
-     * Disconnect from cloud (if connected)
+     * Check if history tracking is enabled
      */
+    get historyEnabled(): boolean;
+    /**
+     * Restore to a specific version (time travel)
+     * Note: Full implementation requires storing update binaries, which is not yet implemented.
+     * @returns false - not yet fully implemented
+     */
+    restoreToVersion(_versionId: string): boolean;
+    get accessLevel(): AccessLevel;
+    get hasSystemAccess(): boolean;
+    private _initCloud;
+    private _initYIndexedDB;
+    private _initIndexedDB;
+    protected _getIndexedDBAdapterClass(): Promise<any>;
+    get connectionState(): ConnectionState$1;
+    get isLoaded(): boolean;
+    protected _getCloudAdapterClass(): Promise<any>;
+    get isCloud(): boolean;
+    waitForSync(): Promise<void>;
     disconnect(): void;
+    isRemoteUpdate(): boolean;
+    serialize(): STM;
+    deserialize(data: STM): void;
     private encodeFileToBase64;
     private createDataUrl;
     private validateContentType;
-    /** @deprecated Use get_value instead */
-    get(key: string): any;
+    private injectSTM;
+    getAll(): STM;
     get_value(key: string, _processingStack?: Set<string>): any;
     get_attributes(key: string): KeyAttributes | undefined;
     set_value(key: string, value: any, attributes?: Partial<KeyAttributes>): void;
-    _setFromRemote(key: string, value: any, attributes: KeyAttributes): void;
-    isRemoteUpdate(): boolean;
-    _deleteFromRemote(key: string): void;
-    _clearFromRemote(): void;
-    set_attributes(key: string, attributes: Partial<KeyAttributes>): boolean;
-    set(key: string, value: any): void;
-    set_file(key: string, file: File, attributes?: Partial<KeyAttributes>): Promise<void>;
-    set_base64(key: string, base64Data: string, contentType: string, type?: 'image' | 'file', attributes?: Partial<KeyAttributes>): void;
-    add_image(key: string, base64Data: string, contentType?: string, attributes?: Partial<KeyAttributes>): void;
-    get_data_url(key: string): string | undefined;
-    get_base64(key: string): string | undefined;
-    has(key: string): boolean;
-    delete(key: string): boolean;
+    delete_key(key: string): void;
     clear(): void;
+    set_file(key: string, file: File, attributes?: Partial<KeyAttributes>): Promise<void>;
+    set_image(key: string, file: File, attributes?: Partial<KeyAttributes>): Promise<void>;
     /**
-     * Get keys sorted by zIndex (ascending), then by key name
-     */
-    private getSortedKeys;
-    keys(): string[];
-    values(): any[];
-    entries(): [string, any][];
-    size(): number;
-    getAll(): Record<string, any>;
-    update(newValues: Record<string, any>): void;
-    subscribe(key: string, listener: Listener): void;
-    unsubscribe(key: string, listener: Listener): void;
-    subscribeToAll(listener: GlobalListener): void;
-    unsubscribeFromAll(listener: GlobalListener): void;
-    private notifyGlobalListeners;
-    injectSTM(template: string, _processingStack?: Set<string>): string;
-    getSTM(): string;
-    getSTMObject(): Record<string, any>;
-    getSTMForAPI(): Array<{
-        key: string;
-        value: any;
-        type: string;
-        contentType?: string;
-    }>;
-    getVisibleImages(): Array<{
-        type: 'file';
-        mediaType: string;
-        url: string;
-        filename?: string;
-    }>;
-    toJSON(): string;
-    fromJSON(jsonString: string): void;
-    serialize(): Record<string, STMEntry>;
-    deserialize(data: Record<string, STMEntry>): void;
-    get_system_prompt(): string;
-    private findKeyFromToolName;
-    get_aisdk_tools(): Record<string, any>;
-    executeToolCall(toolName: string, value: any): {
-        result: string;
-        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
+     * Create or get a collaborative document key.
+     * Uses Y.Text for character-level concurrent editing.
+     *
+     * Note: This exposes Yjs Y.Text directly for editor bindings (y-quill, y-codemirror, etc.)
      */
-    getTagged(tag: string): string;
+    set_document(key: string, initialText?: string, attributes?: Partial<KeyAttributes>): void;
     /**
-     * Get all keys with a specific content tag
+     * Get the Y.Text object for a document key.
+     * Use this to bind to editors (Quill, CodeMirror, Monaco, etc.)
+     *
+     * @returns Y.Text or undefined if key doesn't exist or isn't a document
      */
-    getKeysByTag(tag: string): string[];
+    get_document(key: string): Y.Text | undefined;
     /**
-     * Add a system tag to a key (requires system access)
-     * System tags: 'prompt', 'readonly', 'protected', 'template'
+     * Get plain text content of a document key.
+     * For collaborative editing, use get_document() and bind to an editor.
      */
-    systemAddTag(key: string, tag: SystemTag): boolean;
+    get_document_text(key: string): string | undefined;
     /**
-     * Remove a system tag from a key (requires system access)
+     * Insert text at a position in a document key.
      */
-    systemRemoveTag(key: string, tag: SystemTag): boolean;
+    insert_text(key: string, index: number, text: string): void;
     /**
-     * Get all system tags for a key (requires system access)
+     * Delete text from a document key.
      */
-    systemGetTags(key: string): SystemTag[];
+    delete_text(key: string, index: number, length: number): void;
     /**
-     * Check if a key has a specific system tag (requires system access)
+     * Replace all text in a document key.
+     * Uses diff-based updates when changes are < diffThreshold (default 80%).
+     * This preserves concurrent edits and provides better undo granularity.
+     *
+     * @param key - The document key
+     * @param newText - The new text content
+     * @param diffThreshold - Percentage (0-1) of change above which full replace is used (default: 0.8)
      */
-    systemHasTag(key: string, tag: SystemTag): boolean;
+    replace_document_text(key: string, newText: string, diffThreshold?: number): void;
+    subscribe(key: string, listener: Listener): () => void;
+    subscribeToAll(listener: GlobalListener): () => void;
+    unsubscribeFromAll(listener: GlobalListener): void;
+    private notifyGlobalListeners;
+    private sanitizeKeyForTool;
+    private findKeyFromSanitizedTool;
     /**
-     * Set all system tags for a key at once (requires system access)
+     * Generate Vercel AI SDK compatible tools for writable keys.
+     * For document type keys, generates additional tools: append_, insert_, edit_
      */
-    systemSetTags(key: string, tags: SystemTag[]): boolean;
+    get_aisdk_tools(): Record<string, any>;
     /**
-     * Get all keys with a specific system tag (requires system access)
+     * Generate a system prompt containing all visible STM keys and their values.
+     * Indicates which tools can be used to modify writable keys.
      */
-    systemGetKeysByTag(tag: SystemTag): string[];
+    get_system_prompt(): string;
     /**
-     * Helper to sync legacy boolean attributes from system tags
+     * Execute a tool call by name with the given value.
+     * Returns the result or null if tool not found.
      */
-    private syncLegacyFromSystemTags;
-    toMarkdown(): string;
-    fromMarkdown(markdown: string): void;
+    executeToolCall(toolName: string, value: any): {
+        result: string;
+        key: string;
+        value?: any;
+    } | null;
+    _setFromRemote(_key: string, _value: any, _attributes: KeyAttributes): void;
+    _deleteFromRemote(_key: string): void;
+    _clearFromRemote(): void;
 }
-declare const mindcache: MindCache;
 
 /**
  * Configuration for connecting to MindCache Cloud
@@ -346,24 +336,9 @@ interface CloudAdapterEvents {
     synced: () => void;
 }
 
-/**
- * CloudAdapter connects a MindCache instance to the cloud service
- * for real-time sync and persistence.
- *
- * 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;
     private ws;
-    private queue;
     private mindcache;
     private unsubscribe;
     private reconnectAttempts;
@@ -372,64 +347,20 @@ declare class CloudAdapter {
     private listeners;
     private token;
     constructor(config: CloudConfig);
-    /**
-     * Set auth token (short-lived, from /api/ws-token)
-     * Call this before connect() or use setTokenProvider for auto-refresh
-     */
     setToken(token: string): void;
-    /**
-     * Set a function that returns a fresh token
-     * Used for automatic token refresh on reconnect
-     */
     setTokenProvider(provider: () => Promise<string>): void;
-    /**
-     * Get current connection state
-     */
     get state(): ConnectionState;
-    /**
-     * Attach to a MindCache instance and start syncing
-     */
     attach(mc: MindCache): void;
-    /**
-     * 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
-     */
     connect(): Promise<void>;
-    /**
-     * Disconnect from the cloud service
-     */
     disconnect(): void;
-    /**
-     * Push an operation to the cloud
-     */
-    push(op: Operation): void;
-    /**
-     * Add event listener
-     */
     on<K extends keyof CloudAdapterEvents>(event: K, listener: CloudAdapterEvents[K]): void;
-    /**
-     * Remove event listener
-     */
     off<K extends keyof CloudAdapterEvents>(event: K, listener: CloudAdapterEvents[K]): void;
     private emit;
     private setupWebSocket;
-    private handleMessage;
-    private flushQueue;
+    private sendBinary;
     private scheduleReconnect;
-    private syncLocalChanges;
 }
 
-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 };
+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 };