mindcache 3.5.3 → 3.7.0

package/dist/index.d.ts

@@ -1,8 +1,44 @@
-import { e as MindCacheOptions, M as MindCache } from './CloudAdapter-DK4YecbV.js';
-export { A as AccessLevel, a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, h as ContextRules, n as DEFAULT_KEY_ATTRIBUTES, G as GlobalListener, H as HistoryEntry, k as HistoryOptions, K as KeyAttributes, j as KeyEntry, f as KeyType, L as Listener, l as MindCacheCloudOptions, m as MindCacheIndexedDBOptions, i as STM, j as STMEntry, g as SystemTag, o as SystemTagHelpers } from './CloudAdapter-DK4YecbV.js';
+import { e as CustomTypeDefinition, f as MindCacheOptions, M as MindCache } from './CloudAdapter-PLGvGjoA.js';
+export { A as AccessLevel, a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, i as ContextRules, o as CustomTypeField, p as DEFAULT_KEY_ATTRIBUTES, G as GlobalListener, H as HistoryEntry, l as HistoryOptions, K as KeyAttributes, k as KeyEntry, g as KeyType, L as Listener, m as MindCacheCloudOptions, n as MindCacheIndexedDBOptions, j as STM, k as STMEntry, h as SystemTag, q as SystemTagHelpers } from './CloudAdapter-PLGvGjoA.js';
 export { IndexedDBAdapter, IndexedDBConfig } from './server.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
 import 'yjs';
 
+/**
+ * Parses markdown-based schema definitions into structured CustomTypeDefinition objects.
+ *
+ * Schema format:
+ * ```
+ * #TypeName
+ * * fieldName: description of the field
+ * * anotherField: description
+ * ```
+ */
+declare class SchemaParser {
+    /**
+     * Parse a markdown schema string into a CustomTypeDefinition
+     * @param schema - Markdown schema string
+     * @returns Parsed type definition
+     * @throws Error if schema format is invalid
+     */
+    static parse(schema: string): CustomTypeDefinition;
+    /**
+     * Generate a markdown representation of a type definition
+     * Useful for including in LLM prompts
+     */
+    static toMarkdown(typeDef: CustomTypeDefinition): string;
+    /**
+     * Generate a prompt-friendly description of the type
+     * More verbose than toMarkdown, better for LLM guidance
+     */
+    static toPromptDescription(typeDef: CustomTypeDefinition): string;
+    /**
+     * Generate an example value structure based on the type definition
+     */
+    static generateExample(typeDef: CustomTypeDefinition): string;
+}
+
 /**
  * MindCache OAuth Client
  *
@@ -12,23 +48,17 @@ import 'yjs';
 interface OAuthConfig {
     /** Client ID from developer portal */
     clientId: string;
+    /**
+     * MindCache API base URL - REQUIRED!
+     * All OAuth endpoints are derived from this.
+     * - Production: 'https://api.mindcache.dev'
+     * - Local dev:  'http://localhost:8787'
+     */
+    baseUrl: string;
     /** Redirect URI (defaults to current URL) */
     redirectUri?: string;
     /** Scopes to request (default: ['read', 'write']) */
     scopes?: string[];
-    /**
-     * MindCache API base URL (default: 'https://api.mindcache.dev')
-     * This is the ONLY URL you need to set! All OAuth endpoints are derived from this.
-     * - authUrl = baseUrl + '/oauth/authorize'
-     * - tokenUrl = baseUrl + '/oauth/token'
-     */
-    baseUrl?: string;
-    /** @deprecated Use baseUrl instead. MindCache authorize URL */
-    authUrl?: string;
-    /** @deprecated Use baseUrl instead. MindCache token URL */
-    tokenUrl?: string;
-    /** @deprecated Use baseUrl instead. MindCache API URL */
-    apiUrl?: string;
     /** Use PKCE for security (default: true) */
     usePKCE?: boolean;
     /** Storage key prefix (default: 'mindcache_oauth') */
@@ -69,8 +99,14 @@ declare class OAuthClient {
     private tokens;
     private refreshPromise;
     constructor(config: OAuthConfig);
+    /** Derived auth URL */
+    private get authUrl();
+    /** Derived token URL */
+    private get tokenUrl();
+    /** Derived userinfo URL */
+    private get userinfoUrl();
     /**
-     * Validate the API is reachable and warn about common misconfigurations
+     * Validate the API is reachable
      */
     private validateApi;
     /**
@@ -123,13 +159,12 @@ declare class OAuthClient {
     private clearAuth;
     /**
      * Token provider for MindCache cloud config
-     * This fetches a WebSocket token (short-lived) using the OAuth access token
+     * This fetches a WebSocket token using the OAuth access token
      * Use this with MindCacheCloudOptions.tokenProvider
      */
     tokenProvider: () => Promise<string>;
     /**
      * Get raw OAuth access token (for API calls, not WebSocket)
-     * Use getAccessToken() for most cases
      */
     accessTokenProvider: () => Promise<string>;
     private getStorage;
@@ -173,6 +208,369 @@ interface UseMindCacheResult {
  */
 declare function useMindCache(options?: MindCacheOptions): UseMindCacheResult;
 
+/** Supported AI providers */
+type AIProvider = 'openai' | 'anthropic' | 'custom';
+/**
+ * Configuration for local-first sync
+ */
+interface LocalFirstSyncConfig {
+    /** Optional server URL for real-time sync when online */
+    serverUrl?: string;
+    /** GitStore configuration for GitHub backup */
+    gitstore?: {
+        owner: string;
+        repo: string;
+        path?: string;
+        /** Token provider function or direct token */
+        token: string | (() => Promise<string>);
+    };
+    /** Auto-sync interval in ms (default: 30000 = 30s) */
+    autoSyncInterval?: number;
+    /** Debounce delay for saves in ms (default: 2000) */
+    saveDebounceMs?: number;
+}
+/**
+ * AI configuration for client-side chat
+ */
+interface AIConfig {
+    /**
+     * AI provider: 'openai' | 'anthropic' | 'custom'
+     * If using 'custom', you must provide modelProvider
+     * @default 'openai'
+     */
+    provider?: AIProvider;
+    /**
+     * Model name (e.g., 'gpt-4o', 'gpt-4o-mini', 'claude-3-5-sonnet')
+     * @default 'gpt-4o'
+     */
+    model?: string;
+    /** API key - stored in localStorage if keyStorage is 'localStorage' */
+    apiKey?: string;
+    /** Where to store the API key: 'localStorage' | 'memory' | 'prompt' */
+    keyStorage?: 'localStorage' | 'memory' | 'prompt';
+    /** localStorage key for API key (default: 'ai_api_key') */
+    storageKey?: string;
+    /**
+     * Custom model provider function (advanced usage)
+     * Use this for providers not built-in or custom configurations
+     * @example
+     * ```ts
+     * import { createOpenAI } from '@ai-sdk/openai';
+     * modelProvider: (apiKey) => createOpenAI({ apiKey, baseURL: '...' })('gpt-4o')
+     * ```
+     */
+    modelProvider?: (apiKey: string) => any;
+}
+/**
+ * MindCache Provider configuration
+ */
+interface MindCacheProviderConfig {
+    /** MindCache options (IndexedDB config, etc.) */
+    mindcache?: MindCacheOptions;
+    /** Local-first sync configuration */
+    sync?: LocalFirstSyncConfig;
+    /** AI configuration for client-side chat */
+    ai?: AIConfig;
+    /** Children components */
+    children: ReactNode;
+}
+/**
+ * MindCache context value
+ */
+interface MindCacheContextValue {
+    /** The MindCache instance */
+    mindcache: MindCache | null;
+    /** Whether MindCache is loaded and ready */
+    isLoaded: boolean;
+    /** Any error during initialization */
+    error: Error | null;
+    /** AI configuration */
+    aiConfig: AIConfig;
+    /** Sync configuration */
+    syncConfig: LocalFirstSyncConfig | undefined;
+    /** Get the API key (from storage or prompt) */
+    getApiKey: () => string | null;
+    /** Set the API key */
+    setApiKey: (key: string) => void;
+    /** Whether API key is configured */
+    hasApiKey: boolean;
+    /** Get the AI model (uses API key from storage) */
+    getModel: () => any;
+    /** Trigger a manual sync to GitStore */
+    syncToGitStore: () => Promise<void>;
+    /** Last sync timestamp */
+    lastSyncAt: Date | null;
+    /** Whether currently syncing */
+    isSyncing: boolean;
+}
+/**
+ * Hook to access MindCache context
+ */
+declare function useMindCacheContext(): MindCacheContextValue;
+/**
+ * MindCacheProvider - Context provider for local-first MindCache apps
+ *
+ * @example
+ * ```tsx
+ * <MindCacheProvider
+ *   mindcache={{ indexedDB: { dbName: 'my-app' } }}
+ *   ai={{ keyStorage: 'localStorage' }}
+ *   sync={{ gitstore: { owner: 'me', repo: 'data', token: 'ghp_...' } }}
+ * >
+ *   <App />
+ * </MindCacheProvider>
+ * ```
+ */
+declare function MindCacheProvider({ mindcache: mcOptions, sync: syncConfig, ai: aiConfig, children }: MindCacheProviderConfig): react_jsx_runtime.JSX.Element;
+
+/**
+ * Message part types (compatible with AI SDK UIMessage)
+ */
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+interface ToolCallPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+interface ToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+}
+type MessagePart = TextPart | ToolCallPart | ToolResultPart;
+/**
+ * Chat message structure (compatible with AI SDK UIMessage)
+ */
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    parts?: MessagePart[];
+    createdAt: Date;
+}
+/**
+ * Chat status
+ */
+type ChatStatus = 'idle' | 'loading' | 'streaming' | 'error';
+/**
+ * useClientChat options
+ */
+interface UseClientChatOptions {
+    /** MindCache instance (uses context if not provided) */
+    mindcache?: MindCache;
+    /** Initial messages */
+    initialMessages?: ChatMessage[];
+    /** Custom system prompt (overrides MindCache system prompt) */
+    systemPrompt?: string;
+    /** Callback when AI modifies MindCache */
+    onMindCacheChange?: () => void;
+    /** Callback when message is complete */
+    onFinish?: (message: ChatMessage) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Max tool call iterations (default: 5) */
+    maxToolCalls?: number;
+}
+/**
+ * useClientChat return value
+ */
+interface UseClientChatReturn {
+    /** All messages in the conversation */
+    messages: ChatMessage[];
+    /** Current status */
+    status: ChatStatus;
+    /** Current error if any */
+    error: Error | null;
+    /** Send a message */
+    sendMessage: (content: string) => Promise<void>;
+    /** Clear all messages */
+    clearMessages: () => void;
+    /** Whether currently loading/streaming */
+    isLoading: boolean;
+    /** Add a message programmatically */
+    addMessage: (message: Omit<ChatMessage, 'id' | 'createdAt'>) => void;
+    /** Stop the current generation */
+    stop: () => void;
+    /** Current streaming text (updates in real-time) */
+    streamingContent: string;
+}
+/**
+ * useClientChat - Client-side AI chat hook with real-time streaming
+ *
+ * Runs AI entirely in the browser using the Vercel AI SDK.
+ * Automatically integrates with MindCache for context and tool execution.
+ * Shows text streaming in real-time as it's generated.
+ *
+ * @example
+ * ```tsx
+ * function Chat() {
+ *   const { messages, sendMessage, isLoading, streamingContent } = useClientChat();
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(m => <div key={m.id}>{m.content}</div>)}
+ *       {streamingContent && <div>{streamingContent}</div>}
+ *       <input onSubmit={e => sendMessage(e.target.value)} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useClientChat(options?: UseClientChatOptions): UseClientChatReturn;
+
+/**
+ * Chat theme configuration
+ */
+interface ChatTheme {
+    /** Container background */
+    background?: string;
+    /** User message background */
+    userBubble?: string;
+    /** Assistant message background */
+    assistantBubble?: string;
+    /** Text color */
+    textColor?: string;
+    /** Secondary text color */
+    secondaryTextColor?: string;
+    /** Border color */
+    borderColor?: string;
+    /** Primary/accent color */
+    primaryColor?: string;
+    /** Font family */
+    fontFamily?: string;
+}
+/**
+ * MindCacheChat props
+ */
+interface MindCacheChatProps extends Omit<UseClientChatOptions, 'mindcache'> {
+    /** Custom theme */
+    theme?: ChatTheme;
+    /** Placeholder text for input */
+    placeholder?: string;
+    /** Welcome message (shown when no messages) */
+    welcomeMessage?: string;
+    /** Show API key input if not configured */
+    showApiKeyInput?: boolean;
+    /** Custom class name for container */
+    className?: string;
+    /** Custom styles for container */
+    style?: React.CSSProperties;
+    /** Render custom message component */
+    renderMessage?: (message: ChatMessage) => React.ReactNode;
+    /** Header component */
+    header?: React.ReactNode;
+    /** Footer component (below input) */
+    footer?: React.ReactNode;
+}
+/**
+ * MindCacheChat - Ready-to-use chat component for local-first AI
+ *
+ * @example
+ * ```tsx
+ * <MindCacheProvider ai={{ keyStorage: 'localStorage' }}>
+ *   <MindCacheChat
+ *     welcomeMessage="Hello! How can I help you today?"
+ *     placeholder="Ask me anything..."
+ *   />
+ * </MindCacheProvider>
+ * ```
+ */
+declare function MindCacheChat({ theme: customTheme, placeholder, welcomeMessage, showApiKeyInput, className, style, renderMessage, header, footer, initialMessages, ...chatOptions }: MindCacheChatProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * GitStore sync configuration
+ */
+interface GitStoreSyncConfig {
+    /** GitHub repository owner */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** File path in repo (default: 'mindcache.md') */
+    path?: string;
+    /** GitHub token or token provider */
+    token: string | (() => Promise<string>);
+    /** Branch to sync to (default: 'main') */
+    branch?: string;
+}
+/**
+ * Server sync configuration
+ */
+interface ServerSyncConfig {
+    /** Server URL for sync endpoint */
+    url: string;
+    /** Optional auth token */
+    authToken?: string;
+}
+/**
+ * useLocalFirstSync options
+ */
+interface UseLocalFirstSyncOptions {
+    /** MindCache instance to sync */
+    mindcache: MindCache | null;
+    /** GitStore configuration */
+    gitstore?: GitStoreSyncConfig;
+    /** Optional server sync configuration */
+    server?: ServerSyncConfig;
+    /** Auto-sync interval in ms (0 = disabled, default: 0) */
+    autoSyncInterval?: number;
+    /** Debounce delay for auto-save in ms (default: 5000) */
+    saveDebounceMs?: number;
+    /** Load from remote on mount (default: true) */
+    loadOnMount?: boolean;
+    /** Merge remote data with local (default: true) */
+    mergeOnLoad?: boolean;
+}
+/**
+ * Sync status
+ */
+type SyncStatus = 'idle' | 'loading' | 'saving' | 'syncing' | 'error';
+/**
+ * useLocalFirstSync return value
+ */
+interface UseLocalFirstSyncReturn {
+    /** Current sync status */
+    status: SyncStatus;
+    /** Last error */
+    error: Error | null;
+    /** Last successful sync timestamp */
+    lastSyncAt: Date | null;
+    /** Whether there are unsaved local changes */
+    hasLocalChanges: boolean;
+    /** Load data from remote (GitStore or server) */
+    load: () => Promise<void>;
+    /** Save current state to remote */
+    save: (message?: string) => Promise<void>;
+    /** Full sync: load then save if changes */
+    sync: () => Promise<void>;
+    /** Mark local changes as saved (for manual tracking) */
+    markSaved: () => void;
+}
+/**
+ * useLocalFirstSync - Hook for local-first sync with GitStore
+ *
+ * Provides automatic syncing between local MindCache and GitHub via GitStore.
+ * Data is always available locally via IndexedDB, with async GitHub backup.
+ *
+ * @example
+ * ```tsx
+ * const { status, save, load, hasLocalChanges } = useLocalFirstSync({
+ *   mindcache,
+ *   gitstore: {
+ *     owner: 'myuser',
+ *     repo: 'my-data',
+ *     token: process.env.GITHUB_TOKEN,
+ *   },
+ *   autoSyncInterval: 60000, // Sync every minute
+ * });
+ * ```
+ */
+declare function useLocalFirstSync(options: UseLocalFirstSyncOptions): UseLocalFirstSyncReturn;
+
 declare const mindcache: MindCache;
 
-export { MindCache, MindCacheOptions, type MindCacheUser, OAuthClient, type OAuthConfig, type OAuthTokens, type UseMindCacheResult, createOAuthClient, mindcache, useMindCache };
+export { type AIConfig, type ChatMessage, type ChatStatus, type ChatTheme, CustomTypeDefinition, type GitStoreSyncConfig, type LocalFirstSyncConfig, MindCache, MindCacheChat, type MindCacheChatProps, type MindCacheContextValue, MindCacheOptions, MindCacheProvider, type MindCacheProviderConfig, type MindCacheUser, OAuthClient, type OAuthConfig, type OAuthTokens, SchemaParser, type ServerSyncConfig, type SyncStatus, type UseClientChatOptions, type UseClientChatReturn, type UseLocalFirstSyncOptions, type UseLocalFirstSyncReturn, type UseMindCacheResult, createOAuthClient, mindcache, useClientChat, useLocalFirstSync, useMindCache, useMindCacheContext };