mindcache 3.5.2 → 3.6.0

package/dist/index.js

@@ -6,6 +6,8 @@ var decoding = require('lib0/decoding');
 var Y = require('yjs');
 var yIndexeddb = require('y-indexeddb');
 var diff = require('fast-diff');
+var ai = require('ai');
+var zod = require('zod');
 var react = require('react');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -212,7 +214,6 @@ var init_CloudAdapter = __esm({
         if (!config.baseUrl) {
           throw new Error("MindCache Cloud: baseUrl is required. Please provide the cloud API URL in your configuration.");
         }
-        this.validateConfig(config);
         this.setupNetworkDetection();
       }
       ws = null;
@@ -228,43 +229,6 @@ var init_CloudAdapter = __esm({
       handleOnline = null;
       handleOffline = null;
       _synced = false;
-      /**
-       * Validate configuration and warn about common mistakes
-       */
-      validateConfig(config) {
-        const baseUrl = config.baseUrl;
-        if (!baseUrl) {
-          return;
-        }
-        console.log("\u2601\uFE0F MindCache Cloud Config:", {
-          baseUrl,
-          instanceId: config.instanceId,
-          hasTokenProvider: !!config.tokenProvider,
-          hasApiKey: !!config.apiKey
-        });
-        try {
-          const url = new URL(baseUrl);
-          if (url.hostname === "mindcache.dev") {
-            console.error(
-              '\u26A0\uFE0F MindCache Cloud WARNING: baseUrl is set to "mindcache.dev" but the API is at "api.mindcache.dev".\n   Current: ' + baseUrl + "\n   Expected: https://api.mindcache.dev\n   This will cause WebSocket connection failures (404 errors)."
-            );
-          }
-          if (url.protocol === "ws:" || url.protocol === "wss:") {
-            console.warn(
-              "\u26A0\uFE0F MindCache Cloud: baseUrl uses WebSocket protocol (" + url.protocol + "). Consider using http:// or https:// - CloudAdapter will handle the WebSocket upgrade automatically."
-            );
-          }
-          if (url.hostname === "localhost" && url.port !== "8787" && url.port !== "3000") {
-            console.warn(
-              "\u26A0\uFE0F MindCache Cloud: localhost URL detected with non-standard port " + url.port + ". Default MindCache dev server runs on port 8787."
-            );
-          }
-          const wsUrl = baseUrl.replace("https://", "wss://").replace("http://", "ws://");
-          console.log("\u2601\uFE0F WebSocket will connect to:", wsUrl + "/sync/" + config.instanceId);
-        } catch (e) {
-          console.error("\u26A0\uFE0F MindCache Cloud: Invalid baseUrl format:", baseUrl);
-        }
-      }
       /** Browser network status - instantly updated via navigator.onLine */
       get isOnline() {
         return this._isOnline;
@@ -517,6 +481,76 @@ var SystemTagHelpers = {
   hasTemplateInjection: (attrs) => attrs.systemTags.includes("ApplyTemplate")
 };
 
+// src/core/SchemaParser.ts
+var SchemaParser = class {
+  /**
+   * 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) {
+    const lines = schema.trim().split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+    if (lines.length === 0) {
+      throw new Error("Schema cannot be empty");
+    }
+    const typeNameMatch = lines[0].match(/^#\s*(\w+)$/);
+    if (!typeNameMatch) {
+      throw new Error(`Invalid schema: first line must be "#TypeName", got "${lines[0]}"`);
+    }
+    const typeName = typeNameMatch[1];
+    const fields = [];
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      const fieldMatch = line.match(/^\*\s*([^:]+):\s*(.+)$/);
+      if (fieldMatch) {
+        fields.push({
+          name: fieldMatch[1].trim(),
+          description: fieldMatch[2].trim()
+        });
+      }
+    }
+    if (fields.length === 0) {
+      throw new Error(`Schema "${typeName}" must have at least one field`);
+    }
+    return {
+      name: typeName,
+      fields,
+      rawSchema: schema
+    };
+  }
+  /**
+   * Generate a markdown representation of a type definition
+   * Useful for including in LLM prompts
+   */
+  static toMarkdown(typeDef) {
+    const lines = [`#${typeDef.name}`];
+    for (const field of typeDef.fields) {
+      lines.push(`* ${field.name}: ${field.description}`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Generate a prompt-friendly description of the type
+   * More verbose than toMarkdown, better for LLM guidance
+   */
+  static toPromptDescription(typeDef) {
+    const fieldDescs = typeDef.fields.map((f) => `  - ${f.name}: ${f.description}`).join("\n");
+    return `Type "${typeDef.name}" with fields:
+${fieldDescs}`;
+  }
+  /**
+   * Generate an example value structure based on the type definition
+   */
+  static generateExample(typeDef) {
+    const lines = [`#${typeDef.name.toLowerCase()}`];
+    for (const field of typeDef.fields) {
+      lines.push(`* ${field.name}: [${field.description}]`);
+    }
+    return lines.join("\n");
+  }
+};
+
 // src/core/MarkdownSerializer.ts
 var MarkdownSerializer = class {
   /**
@@ -863,18 +897,16 @@ var MarkdownSerializer = class {
     return result;
   }
 };
-
-// src/core/AIToolBuilder.ts
 var AIToolBuilder = class _AIToolBuilder {
   /**
-     * Sanitize key name for use in tool names
-     */
+   * Sanitize key name for use in tool names
+   */
   static sanitizeKeyForTool(key) {
     return key.replace(/[^a-zA-Z0-9_-]/g, "_");
   }
   /**
-     * Find original key from sanitized tool name
-     */
+   * Find original key from sanitized tool name
+   */
   static findKeyFromSanitizedTool(mc, sanitizedKey) {
     for (const key of mc.keys()) {
       if (_AIToolBuilder.sanitizeKeyForTool(key) === sanitizedKey) {
@@ -884,15 +916,174 @@ var AIToolBuilder = class _AIToolBuilder {
     return void 0;
   }
   /**
-     * Generate Vercel AI SDK compatible tools for writable keys.
-     * For document type keys, generates additional tools: append_, insert_, edit_
-     *
-     * Security: All tools use llm_set_key internally which:
-     * - Only modifies VALUES, never attributes/systemTags
-     * - Prevents LLMs from escalating privileges
-     */
+   * Generate framework-agnostic tools with raw JSON Schema.
+   * Works with: OpenAI SDK, Anthropic SDK, LangChain, etc.
+   *
+   * Tool format:
+   * {
+   *   description: string,
+   *   parameters: { type: 'object', properties: {...}, required: [...] },
+   *   execute: async (args) => result
+   * }
+   */
+  static createTools(mc) {
+    return _AIToolBuilder._buildTools(mc);
+  }
+  /**
+   * Generate Vercel AI SDK v5 compatible tools using Zod schemas.
+   * Uses tool() helper with Zod for full AI SDK v5 compatibility.
+   *
+   * Use this with: generateText(), streamText() from 'ai' package
+   */
   static createVercelAITools(mc) {
     const tools = {};
+    const registeredTypes = mc.getRegisteredTypes();
+    const typeDesc = registeredTypes.length > 0 ? `Optional type: ${registeredTypes.join(" | ")}` : "No types registered";
+    tools["create_key"] = ai.tool({
+      description: `Create a new key in MindCache. ${registeredTypes.length > 0 ? `Available types: ${registeredTypes.join(", ")}` : ""}`,
+      inputSchema: zod.z.object({
+        key: zod.z.string().describe('The key name (e.g., "contact_john_doe")'),
+        value: zod.z.string().describe("The value (JSON string for structured data)"),
+        type: zod.z.string().optional().describe(typeDesc)
+      }),
+      execute: async ({ key, value, type }) => {
+        if (mc.has(key)) {
+          return { result: `Key "${key}" exists. Use write_${_AIToolBuilder.sanitizeKeyForTool(key)}`, error: true };
+        }
+        if (type && !mc.getTypeSchema(type)) {
+          return { result: `Type "${type}" not registered`, error: true };
+        }
+        mc.set_value(key, value, { systemTags: ["SystemPrompt", "LLMRead", "LLMWrite"] });
+        if (type) {
+          mc.setType(key, type);
+        }
+        return { result: `Created "${key}"${type ? ` (${type})` : ""}`, key, value };
+      }
+    });
+    for (const key of mc.keys()) {
+      if (key.startsWith("$") || !mc.keyMatchesContext(key)) {
+        continue;
+      }
+      const attrs = mc.get_attributes(key);
+      if (!attrs?.systemTags?.includes("LLMWrite")) {
+        continue;
+      }
+      const sanitized = _AIToolBuilder.sanitizeKeyForTool(key);
+      const customTypeName = mc.getKeyType(key);
+      const customType = customTypeName ? mc.getTypeSchema(customTypeName) : void 0;
+      let desc = `Write to "${key}"`;
+      if (customType) {
+        desc = `Write to "${key}" (${customTypeName}). ${SchemaParser.toPromptDescription(customType)}`;
+      }
+      tools[`write_${sanitized}`] = ai.tool({
+        description: desc,
+        inputSchema: zod.z.object({
+          value: zod.z.string().describe(customType ? `JSON following ${customTypeName} schema` : "Value to write")
+        }),
+        execute: async ({ value }) => {
+          const success = mc.llm_set_key(key, value);
+          return success ? { result: `Wrote to ${key}`, key, value } : { result: `Failed to write to ${key}`, error: true };
+        }
+      });
+      if (attrs?.type === "document") {
+        tools[`append_${sanitized}`] = ai.tool({
+          description: `Append to "${key}" document`,
+          inputSchema: zod.z.object({ text: zod.z.string().describe("Text to append") }),
+          execute: async ({ text }) => {
+            const yText = mc.get_document(key);
+            if (yText) {
+              yText.insert(yText.length, text);
+              return { result: "Appended", key };
+            }
+            return { result: "Not found", error: true };
+          }
+        });
+        tools[`insert_${sanitized}`] = ai.tool({
+          description: `Insert text at position in "${key}" document`,
+          inputSchema: zod.z.object({
+            index: zod.z.number().describe("Position (0 = start)"),
+            text: zod.z.string().describe("Text to insert")
+          }),
+          execute: async ({ index, text }) => {
+            mc.insert_text(key, index, text);
+            return { result: `Inserted at ${index}`, key };
+          }
+        });
+        tools[`edit_${sanitized}`] = ai.tool({
+          description: `Find and replace in "${key}" document`,
+          inputSchema: zod.z.object({
+            find: zod.z.string().describe("Text to find"),
+            replace: zod.z.string().describe("Replacement")
+          }),
+          execute: async ({ find, replace }) => {
+            const yText = mc.get_document(key);
+            if (yText) {
+              const text = yText.toString();
+              const idx = text.indexOf(find);
+              if (idx !== -1) {
+                yText.delete(idx, find.length);
+                yText.insert(idx, replace);
+                return { result: `Replaced "${find}"`, key };
+              }
+              return { result: `"${find}" not found`, error: true };
+            }
+            return { result: "Document not found", error: true };
+          }
+        });
+      }
+    }
+    return tools;
+  }
+  /**
+   * Internal: Build tools with raw JSON Schema (framework-agnostic).
+   */
+  static _buildTools(mc) {
+    const tools = {};
+    const registeredTypes = mc.getRegisteredTypes();
+    const typeInfo = registeredTypes.length > 0 ? `Available types: ${registeredTypes.join(", ")}` : "No custom types registered";
+    tools["create_key"] = {
+      description: `Create a new key in MindCache. ${typeInfo}. The new key will be readable and writable by the LLM.`,
+      parameters: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: 'The key name to create (e.g., "contact_john_doe")' },
+          value: { type: "string", description: "The value to store (use JSON string for structured data)" },
+          type: {
+            type: "string",
+            description: registeredTypes.length > 0 ? `Optional: custom type name (${registeredTypes.join(" | ")})` : "Optional: custom type name (none registered)"
+          }
+        },
+        required: ["key", "value"]
+      },
+      execute: async ({ key, value, type }) => {
+        if (mc.has(key)) {
+          return {
+            result: `Key "${key}" already exists. Use write_${_AIToolBuilder.sanitizeKeyForTool(key)} to update it.`,
+            key,
+            error: true
+          };
+        }
+        if (type && !mc.getTypeSchema(type)) {
+          return {
+            result: `Type "${type}" is not registered. Available types: ${registeredTypes.join(", ") || "none"}`,
+            key,
+            error: true
+          };
+        }
+        mc.set_value(key, value, {
+          systemTags: ["SystemPrompt", "LLMRead", "LLMWrite"]
+        });
+        if (type) {
+          mc.setType(key, type);
+        }
+        return {
+          result: `Successfully created key "${key}"${type ? ` with type "${type}"` : ""}`,
+          key,
+          value,
+          type
+        };
+      }
+    };
     for (const key of mc.keys()) {
       if (key.startsWith("$")) {
         continue;
@@ -907,12 +1098,28 @@ var AIToolBuilder = class _AIToolBuilder {
       }
       const sanitizedKey = _AIToolBuilder.sanitizeKeyForTool(key);
       const isDocument = attributes?.type === "document";
+      const customTypeName = mc.getKeyType(key);
+      const customType = customTypeName ? mc.getTypeSchema(customTypeName) : void 0;
+      let writeDescription;
+      if (customType) {
+        const schemaGuidance = SchemaParser.toPromptDescription(customType);
+        const example = SchemaParser.generateExample(customType);
+        writeDescription = `Write a value to "${key}" that must follow this schema:
+${schemaGuidance}
+
+Example format:
+${example}`;
+      } else if (isDocument) {
+        writeDescription = `Rewrite the entire "${key}" document`;
+      } else {
+        writeDescription = `Write a value to the STM key: ${key}`;
+      }
       tools[`write_${sanitizedKey}`] = {
-        description: isDocument ? `Rewrite the entire "${key}" document` : `Write a value to the STM key: ${key}`,
-        inputSchema: {
+        description: writeDescription,
+        parameters: {
           type: "object",
           properties: {
-            value: { type: "string", description: isDocument ? "New document content" : "The value to write" }
+            value: { type: "string", description: customType ? `Value following ${customTypeName} schema` : isDocument ? "New document content" : "The value to write" }
           },
           required: ["value"]
         },
@@ -935,7 +1142,7 @@ var AIToolBuilder = class _AIToolBuilder {
       if (isDocument) {
         tools[`append_${sanitizedKey}`] = {
           description: `Append text to the end of "${key}" document`,
-          inputSchema: {
+          parameters: {
             type: "object",
             properties: {
               text: { type: "string", description: "Text to append" }
@@ -960,7 +1167,7 @@ var AIToolBuilder = class _AIToolBuilder {
         };
         tools[`insert_${sanitizedKey}`] = {
           description: `Insert text at a position in "${key}" document`,
-          inputSchema: {
+          parameters: {
             type: "object",
             properties: {
               index: { type: "number", description: "Position to insert at (0 = start)" },
@@ -983,7 +1190,7 @@ var AIToolBuilder = class _AIToolBuilder {
         };
         tools[`edit_${sanitizedKey}`] = {
           description: `Find and replace text in "${key}" document`,
-          inputSchema: {
+          parameters: {
             type: "object",
             properties: {
               find: { type: "string", description: "Text to find" },
@@ -1020,11 +1227,16 @@ var AIToolBuilder = class _AIToolBuilder {
     return tools;
   }
   /**
-     * Generate a system prompt containing all visible STM keys and their values.
-     * Indicates which tools can be used to modify writable keys.
-     */
+   * Generate a system prompt containing all visible STM keys and their values.
+   * Indicates which tools can be used to modify writable keys.
+   */
   static getSystemPrompt(mc) {
     const lines = [];
+    const registeredTypes = mc.getRegisteredTypes();
+    if (registeredTypes.length > 0) {
+      lines.push(`[create_key tool available - registered types: ${registeredTypes.join(", ")}]`);
+      lines.push("");
+    }
     for (const key of mc.keys()) {
       if (key.startsWith("$")) {
         continue;
@@ -1042,8 +1254,18 @@ var AIToolBuilder = class _AIToolBuilder {
       const isWritable = attributes?.systemTags?.includes("LLMWrite");
       const isDocument = attributes?.type === "document";
       const sanitizedKey = _AIToolBuilder.sanitizeKeyForTool(key);
+      const customTypeName = mc.getKeyType(key);
+      const customType = customTypeName ? mc.getTypeSchema(customTypeName) : void 0;
       if (isWritable) {
-        if (isDocument) {
+        if (customType) {
+          const schemaInfo = SchemaParser.toMarkdown(customType);
+          lines.push(
+            `${key} (type: ${customTypeName}): ${displayValue}
+Schema:
+${schemaInfo}
+Tool: write_${sanitizedKey}`
+          );
+        } else if (isDocument) {
           lines.push(
             `${key}: ${displayValue}. Document tools: write_${sanitizedKey}, append_${sanitizedKey}, edit_${sanitizedKey}`
           );
@@ -1054,15 +1276,19 @@ var AIToolBuilder = class _AIToolBuilder {
           );
         }
       } else {
-        lines.push(`${key}: ${displayValue}`);
+        if (customTypeName) {
+          lines.push(`${key} (type: ${customTypeName}): ${displayValue}`);
+        } else {
+          lines.push(`${key}: ${displayValue}`);
+        }
       }
     }
     return lines.join("\n");
   }
   /**
-     * Execute a tool call by name with the given value.
-     * Returns the result or null if tool not found.
-     */
+   * Execute a tool call by name with the given value.
+   * Returns the result or null if tool not found.
+   */
   static executeToolCall(mc, toolName, value) {
     const match = toolName.match(/^(write|append|insert|edit)_(.+)$/);
     if (!match) {
@@ -1389,7 +1615,7 @@ var MindCache = class {
   listeners = {};
   globalListeners = [];
   // Metadata
-  version = "3.3.2";
+  version = "3.6.0";
   // Internal flag to prevent sync loops when receiving remote updates
   // (Less critical with Yjs but kept for API compat)
   normalizeSystemTags(tags) {
@@ -1426,6 +1652,8 @@ var MindCache = class {
   _history = [];
   _historyOptions = { maxEntries: 100, snapshotInterval: 10 };
   _historyEnabled = false;
+  // Custom type registry
+  _typeRegistry = /* @__PURE__ */ new Map();
   constructor(options) {
     this.doc = options?.doc || new Y__namespace.Doc();
     this.rootMap = this.doc.getMap("mindcache");
@@ -2382,6 +2610,71 @@ var MindCache = class {
   systemGetKeysByTag(tag) {
     return TagManager.systemGetKeysByTag(this, tag);
   }
+  // ============================================
+  // Custom Type Methods
+  // ============================================
+  /**
+   * Register a custom type with a markdown schema definition.
+   *
+   * Schema format:
+   * ```
+   * #TypeName
+   * * fieldName: description of the field
+   * * anotherField: description
+   * ```
+   *
+   * @param name - Type name (e.g., 'Contact')
+   * @param schema - Markdown schema definition
+   * @throws Error if schema format is invalid
+   */
+  registerType(name, schema) {
+    const typeDef = SchemaParser.parse(schema);
+    typeDef.name = name;
+    this._typeRegistry.set(name, typeDef);
+  }
+  /**
+   * Assign a custom type to a key.
+   * The key must exist and the type must be registered.
+   * Also sets the underlying type to 'json' since custom types are structured JSON data.
+   *
+   * @param key - Key to assign type to
+   * @param typeName - Registered type name
+   * @throws Error if key doesn't exist or type is not registered
+   */
+  setType(key, typeName) {
+    if (!this.rootMap.has(key)) {
+      throw new Error(`Key "${key}" does not exist`);
+    }
+    if (!this._typeRegistry.has(typeName)) {
+      throw new Error(`Type "${typeName}" is not registered. Use registerType() first.`);
+    }
+    this.set_attributes(key, { type: "json", customType: typeName });
+  }
+  /**
+   * Get a registered type schema definition.
+   *
+   * @param typeName - Type name to look up
+   * @returns The type definition or undefined if not registered
+   */
+  getTypeSchema(typeName) {
+    return this._typeRegistry.get(typeName);
+  }
+  /**
+   * Get all registered type names.
+   */
+  getRegisteredTypes() {
+    return Array.from(this._typeRegistry.keys());
+  }
+  /**
+   * Get the custom type assigned to a key.
+   *
+   * @param key - Key to check
+   * @returns Type name or undefined if no custom type assigned
+   */
+  getKeyType(key) {
+    const attrs = this.get_attributes(key);
+    return attrs?.customType;
+  }
   /**
    * Helper to get sorted keys (by zIndex).
    * Respects context filtering when set.
@@ -2643,9 +2936,28 @@ var MindCache = class {
   findKeyFromSanitizedTool(sanitizedKey) {
     return AIToolBuilder.findKeyFromSanitizedTool(this, sanitizedKey);
   }
+  /**
+   * Generate framework-agnostic tools with raw JSON Schema.
+   * Works with: OpenAI SDK, Anthropic SDK, LangChain, and other frameworks.
+   *
+   * Tool format:
+   * {
+   *   description: string,
+   *   parameters: { type: 'object', properties: {...}, required: [...] },
+   *   execute: async (args) => result
+   * }
+   *
+   * Security: All tools use llm_set_key internally which:
+   * - Only modifies VALUES, never attributes/systemTags
+   * - Prevents LLMs from escalating privileges
+   */
+  create_tools() {
+    return AIToolBuilder.createTools(this);
+  }
   /**
    * Generate Vercel AI SDK compatible tools for writable keys.
-   * For document type keys, generates additional tools: append_, insert_, edit_
+   * Wraps parameters with jsonSchema() for AI SDK v5 compatibility.
+   * Use this with: generateText(), streamText() from 'ai' package.
    *
    * Security: All tools use llm_set_key internally which:
    * - Only modifies VALUES, never attributes/systemTags
@@ -2688,9 +3000,6 @@ init_CloudAdapter();
 init_CloudAdapter();
 
 // src/cloud/OAuthClient.ts
-var DEFAULT_AUTH_URL = "https://api.mindcache.dev/oauth/authorize";
-var DEFAULT_TOKEN_URL = "https://api.mindcache.dev/oauth/token";
-var DEFAULT_USERINFO_URL = "https://api.mindcache.dev/oauth/userinfo";
 var TOKEN_REFRESH_BUFFER = 5 * 60 * 1e3;
 function generateRandomString(length2) {
   const array = new Uint8Array(length2);
@@ -2719,6 +3028,21 @@ var OAuthClient = class {
   tokens = null;
   refreshPromise = null;
   constructor(config) {
+    if (!config.baseUrl) {
+      throw new Error(
+        'MindCache OAuth: baseUrl is required!\n  For production: baseUrl: "https://api.mindcache.dev"\n  For local dev:  baseUrl: "http://localhost:8787"'
+      );
+    }
+    try {
+      const url = new URL(config.baseUrl);
+      if (url.hostname === "mindcache.dev") {
+        console.error(
+          '\u274C MindCache OAuth ERROR: baseUrl should be "api.mindcache.dev" not "mindcache.dev"\n   Current: ' + config.baseUrl + "\n   Correct: https://api.mindcache.dev"
+        );
+      }
+    } catch {
+      throw new Error("MindCache OAuth: Invalid baseUrl format: " + config.baseUrl);
+    }
     let redirectUri = config.redirectUri;
     if (!redirectUri && typeof window !== "undefined") {
       const url = new URL(window.location.href);
@@ -2726,19 +3050,57 @@ var OAuthClient = class {
       url.hash = "";
       redirectUri = url.toString();
     }
+    const baseUrl = config.baseUrl.replace(/\/$/, "");
     this.config = {
       clientId: config.clientId,
+      baseUrl,
       redirectUri: redirectUri || "",
       scopes: config.scopes || ["read", "write"],
-      authUrl: config.authUrl || DEFAULT_AUTH_URL,
-      tokenUrl: config.tokenUrl || DEFAULT_TOKEN_URL,
-      apiUrl: config.apiUrl || (config.tokenUrl || DEFAULT_TOKEN_URL).replace("/oauth/token", ""),
       usePKCE: config.usePKCE !== false,
       // Default true
       storagePrefix: config.storagePrefix || "mindcache_oauth"
     };
+    console.log("\u{1F510} MindCache OAuth:", {
+      baseUrl: this.config.baseUrl,
+      authUrl: this.authUrl,
+      tokenUrl: this.tokenUrl,
+      clientId: this.config.clientId.substring(0, 20) + "..."
+    });
+    this.validateApi();
     this.loadTokens();
   }
+  /** Derived auth URL */
+  get authUrl() {
+    return this.config.baseUrl + "/oauth/authorize";
+  }
+  /** Derived token URL */
+  get tokenUrl() {
+    return this.config.baseUrl + "/oauth/token";
+  }
+  /** Derived userinfo URL */
+  get userinfoUrl() {
+    return this.config.baseUrl + "/oauth/userinfo";
+  }
+  /**
+   * Validate the API is reachable
+   */
+  async validateApi() {
+    try {
+      const response = await fetch(`${this.config.baseUrl}/oauth/apps/info`, {
+        method: "GET",
+        headers: { "Accept": "application/json" }
+      });
+      if (response.status === 404) {
+        console.error(
+          "\u274C MindCache OAuth ERROR: API not found at " + this.config.baseUrl + '\n   The server returned 404. Common causes:\n   - Wrong domain: Use "api.mindcache.dev" not "mindcache.dev"\n   - Wrong port: Local dev server is usually on port 8787\n   - Server not running: Make sure the MindCache server is started'
+        );
+      }
+    } catch (error) {
+      console.error(
+        "\u274C MindCache OAuth ERROR: Cannot reach API at " + this.config.baseUrl + "\n   Error: " + (error instanceof Error ? error.message : String(error))
+      );
+    }
+  }
   /**
      * Check if user is authenticated
      */
@@ -2764,7 +3126,7 @@ var OAuthClient = class {
   async authorize(options) {
     const state = options?.state || generateRandomString(32);
     this.setStorage("state", state);
-    const url = new URL(this.config.authUrl);
+    const url = new URL(this.authUrl);
     url.searchParams.set("response_type", "code");
     url.searchParams.set("client_id", this.config.clientId);
     url.searchParams.set("redirect_uri", this.config.redirectUri);
@@ -2827,7 +3189,7 @@ var OAuthClient = class {
       }
       body.code_verifier = codeVerifier;
     }
-    const response = await fetch(this.config.tokenUrl, {
+    const response = await fetch(this.tokenUrl, {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
@@ -2879,7 +3241,7 @@ var OAuthClient = class {
       throw new Error("No refresh token available");
     }
     try {
-      const response = await fetch(this.config.tokenUrl, {
+      const response = await fetch(this.tokenUrl, {
         method: "POST",
         headers: {
           "Content-Type": "application/json"
@@ -2913,7 +3275,7 @@ var OAuthClient = class {
      */
   async getUserInfo() {
     const token = await this.getAccessToken();
-    const response = await fetch(DEFAULT_USERINFO_URL, {
+    const response = await fetch(this.userinfoUrl, {
       headers: {
         Authorization: `Bearer ${token}`
       }
@@ -2935,7 +3297,7 @@ var OAuthClient = class {
   async logout() {
     if (this.tokens?.accessToken) {
       try {
-        await fetch(this.config.tokenUrl.replace("/token", "/revoke"), {
+        await fetch(this.tokenUrl.replace("/token", "/revoke"), {
           method: "POST",
           headers: {
             "Content-Type": "application/json"
@@ -2958,7 +3320,7 @@ var OAuthClient = class {
   }
   /**
    * 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 = async () => {
@@ -2967,7 +3329,7 @@ var OAuthClient = class {
     if (!instanceId) {
       throw new Error("No instance ID available. Complete OAuth flow first.");
     }
-    const response = await fetch(`${this.config.apiUrl}/api/ws-token`, {
+    const response = await fetch(`${this.config.baseUrl}/api/ws-token`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -2987,7 +3349,6 @@ var OAuthClient = class {
   };
   /**
    * Get raw OAuth access token (for API calls, not WebSocket)
-   * Use getAccessToken() for most cases
    */
   accessTokenProvider = async () => {
     return this.getAccessToken();
@@ -3079,6 +3440,7 @@ var mindcache = new MindCache();
 exports.DEFAULT_KEY_ATTRIBUTES = DEFAULT_KEY_ATTRIBUTES;
 exports.MindCache = MindCache;
 exports.OAuthClient = OAuthClient;
+exports.SchemaParser = SchemaParser;
 exports.SystemTagHelpers = SystemTagHelpers;
 exports.createOAuthClient = createOAuthClient;
 exports.mindcache = mindcache;