@realtimex/sdk 1.1.2 → 1.1.4

package/dist/index.d.mts

@@ -150,14 +150,16 @@ declare class WebhookModule {
  */
 declare class PermissionDeniedError extends Error {
     readonly permission: string;
-    constructor(permission: string, message?: string);
+    readonly code: string;
+    constructor(permission: string, message?: string, code?: string);
 }
 /**
  * Error thrown when a permission needs to be granted
  */
 declare class PermissionRequiredError extends Error {
     readonly permission: string;
-    constructor(permission: string, message?: string);
+    readonly code: string;
+    constructor(permission: string, message?: string, code?: string);
 }
 declare class ApiModule {
     private realtimexUrl;
@@ -263,6 +265,7 @@ declare class PortModule {
  * - Provider/model listing
  * - Vector storage (upsert, query, delete)
  */
+
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
@@ -272,6 +275,9 @@ interface ChatOptions {
     provider?: string;
     temperature?: number;
     max_tokens?: number;
+    response_format?: {
+        type: string;
+    };
 }
 interface ChatResponse {
     success: boolean;
@@ -390,10 +396,41 @@ interface VectorListWorkspacesResponse {
     workspaces?: string[];
     error?: string;
     code?: string;
+    error_message?: string;
 }
-declare class LLMPermissionError extends Error {
-    permission: string;
-    code: string;
+interface VectorRegisterResponse {
+    success: boolean;
+    message?: string;
+    error?: string;
+    code?: string;
+}
+interface VectorConfigResponse {
+    success: boolean;
+    provider?: string;
+    config?: Record<string, any>;
+    error?: string;
+    code?: string;
+}
+interface VectorProviderField {
+    name: string;
+    label: string;
+    type: 'string' | 'password';
+    placeholder?: string;
+}
+interface VectorProviderMetadata {
+    name: string;
+    label: string;
+    description?: string;
+    fields: VectorProviderField[];
+}
+interface VectorProvidersResponse {
+    success: boolean;
+    providers: VectorProviderMetadata[];
+}
+/**
+ * @deprecated Use PermissionRequiredError from api module instead
+ */
+declare class LLMPermissionError extends PermissionRequiredError {
     constructor(permission: string, code?: string);
 }
 declare class LLMProviderError extends Error {
@@ -403,9 +440,18 @@ declare class LLMProviderError extends Error {
 declare class VectorStore {
     private baseUrl;
     private appId;
+    private appName;
     private apiKey?;
-    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
+    constructor(baseUrl: string, appId: string, appName?: string, apiKey?: string | undefined);
     private get headers();
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Internal request wrapper that handles automatic permission prompts
+     */
+    private request;
     /**
      * Upsert (insert or update) vectors into storage
      *
@@ -452,14 +498,46 @@ declare class VectorStore {
      * ```
      */
     listWorkspaces(): Promise<VectorListWorkspacesResponse>;
+    /**
+     * Register a custom vector database configuration for this app
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.vectors.registerConfig('lancedb', { });
+     * ```
+     */
+    registerConfig(provider: string, config: Record<string, any>): Promise<VectorRegisterResponse>;
+    /**
+     * List all supported vector database providers and their configuration requirements
+     */
+    listProviders(): Promise<VectorProvidersResponse>;
+    /**
+     * Get the current vector database configuration for this app
+     *
+     * @example
+     * ```ts
+     * const { provider, config } = await sdk.llm.vectors.getConfig();
+     * console.log(`App is using ${provider}`);
+     * ```
+     */
+    getConfig(): Promise<VectorConfigResponse>;
 }
 declare class LLMModule {
     private baseUrl;
     private appId;
+    private appName;
     private apiKey?;
     vectors: VectorStore;
-    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
+    constructor(baseUrl: string, appId: string, appName?: string, apiKey?: string | undefined);
     private get headers();
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Internal request wrapper that handles automatic permission prompts
+     */
+    private request;
     /**
      * Get only configured chat (LLM) providers
      *
@@ -598,6 +676,11 @@ declare class RealtimeXSDK {
         appId?: string;
         timestamp: string;
     }>;
+    /**
+     * Get the absolute path to the data directory for this app.
+     * Path: ~/.realtimex.ai/Resources/local-apps/{appId}
+     */
+    getAppDataDir(): Promise<string>;
 }
 
 export { ActivitiesModule, type Activity, type Agent, ApiModule, type ChatMessage, type ChatOptions, type ChatResponse, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type StreamChunk, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };

package/dist/index.d.ts

@@ -150,14 +150,16 @@ declare class WebhookModule {
  */
 declare class PermissionDeniedError extends Error {
     readonly permission: string;
-    constructor(permission: string, message?: string);
+    readonly code: string;
+    constructor(permission: string, message?: string, code?: string);
 }
 /**
  * Error thrown when a permission needs to be granted
  */
 declare class PermissionRequiredError extends Error {
     readonly permission: string;
-    constructor(permission: string, message?: string);
+    readonly code: string;
+    constructor(permission: string, message?: string, code?: string);
 }
 declare class ApiModule {
     private realtimexUrl;
@@ -263,6 +265,7 @@ declare class PortModule {
  * - Provider/model listing
  * - Vector storage (upsert, query, delete)
  */
+
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
@@ -272,6 +275,9 @@ interface ChatOptions {
     provider?: string;
     temperature?: number;
     max_tokens?: number;
+    response_format?: {
+        type: string;
+    };
 }
 interface ChatResponse {
     success: boolean;
@@ -390,10 +396,41 @@ interface VectorListWorkspacesResponse {
     workspaces?: string[];
     error?: string;
     code?: string;
+    error_message?: string;
 }
-declare class LLMPermissionError extends Error {
-    permission: string;
-    code: string;
+interface VectorRegisterResponse {
+    success: boolean;
+    message?: string;
+    error?: string;
+    code?: string;
+}
+interface VectorConfigResponse {
+    success: boolean;
+    provider?: string;
+    config?: Record<string, any>;
+    error?: string;
+    code?: string;
+}
+interface VectorProviderField {
+    name: string;
+    label: string;
+    type: 'string' | 'password';
+    placeholder?: string;
+}
+interface VectorProviderMetadata {
+    name: string;
+    label: string;
+    description?: string;
+    fields: VectorProviderField[];
+}
+interface VectorProvidersResponse {
+    success: boolean;
+    providers: VectorProviderMetadata[];
+}
+/**
+ * @deprecated Use PermissionRequiredError from api module instead
+ */
+declare class LLMPermissionError extends PermissionRequiredError {
     constructor(permission: string, code?: string);
 }
 declare class LLMProviderError extends Error {
@@ -403,9 +440,18 @@ declare class LLMProviderError extends Error {
 declare class VectorStore {
     private baseUrl;
     private appId;
+    private appName;
     private apiKey?;
-    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
+    constructor(baseUrl: string, appId: string, appName?: string, apiKey?: string | undefined);
     private get headers();
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Internal request wrapper that handles automatic permission prompts
+     */
+    private request;
     /**
      * Upsert (insert or update) vectors into storage
      *
@@ -452,14 +498,46 @@ declare class VectorStore {
      * ```
      */
     listWorkspaces(): Promise<VectorListWorkspacesResponse>;
+    /**
+     * Register a custom vector database configuration for this app
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.vectors.registerConfig('lancedb', { });
+     * ```
+     */
+    registerConfig(provider: string, config: Record<string, any>): Promise<VectorRegisterResponse>;
+    /**
+     * List all supported vector database providers and their configuration requirements
+     */
+    listProviders(): Promise<VectorProvidersResponse>;
+    /**
+     * Get the current vector database configuration for this app
+     *
+     * @example
+     * ```ts
+     * const { provider, config } = await sdk.llm.vectors.getConfig();
+     * console.log(`App is using ${provider}`);
+     * ```
+     */
+    getConfig(): Promise<VectorConfigResponse>;
 }
 declare class LLMModule {
     private baseUrl;
     private appId;
+    private appName;
     private apiKey?;
     vectors: VectorStore;
-    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
+    constructor(baseUrl: string, appId: string, appName?: string, apiKey?: string | undefined);
     private get headers();
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Internal request wrapper that handles automatic permission prompts
+     */
+    private request;
     /**
      * Get only configured chat (LLM) providers
      *
@@ -598,6 +676,11 @@ declare class RealtimeXSDK {
         appId?: string;
         timestamp: string;
     }>;
+    /**
+     * Get the absolute path to the data directory for this app.
+     * Path: ~/.realtimex.ai/Resources/local-apps/{appId}
+     */
+    getAppDataDir(): Promise<string>;
 }
 
 export { ActivitiesModule, type Activity, type Agent, ApiModule, type ChatMessage, type ChatOptions, type ChatResponse, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type StreamChunk, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };

package/dist/index.js

@@ -47,17 +47,19 @@ module.exports = __toCommonJS(index_exports);
 
 // src/modules/api.ts
 var PermissionDeniedError = class extends Error {
-  constructor(permission, message) {
+  constructor(permission, message, code = "PERMISSION_DENIED") {
     super(message || `Permission '${permission}' was denied`);
     this.name = "PermissionDeniedError";
     this.permission = permission;
+    this.code = code;
   }
 };
 var PermissionRequiredError = class extends Error {
-  constructor(permission, message) {
+  constructor(permission, message, code = "PERMISSION_REQUIRED") {
     super(message || `Permission '${permission}' is required`);
     this.name = "PermissionRequiredError";
     this.permission = permission;
+    this.code = code;
   }
 };
 var ApiModule = class {
@@ -501,11 +503,9 @@ var PortModule = class {
 };
 
 // src/modules/llm.ts
-var LLMPermissionError = class extends Error {
+var LLMPermissionError = class extends PermissionRequiredError {
   constructor(permission, code = "PERMISSION_REQUIRED") {
-    super(`Permission required: ${permission}`);
-    this.permission = permission;
-    this.code = code;
+    super(permission, void 0, code);
     this.name = "LLMPermissionError";
   }
 };
@@ -517,9 +517,10 @@ var LLMProviderError = class extends Error {
   }
 };
 var VectorStore = class {
-  constructor(baseUrl, appId, apiKey) {
+  constructor(baseUrl, appId, appName = "Local App", apiKey) {
     this.baseUrl = baseUrl;
     this.appId = appId;
+    this.appName = appName;
     this.apiKey = apiKey;
   }
   get headers() {
@@ -534,6 +535,52 @@ var VectorStore = class {
       "x-app-id": this.appId
     };
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/local-apps/request-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permission
+        })
+      });
+      const data = await response.json();
+      return data.granted === true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Internal request wrapper that handles automatic permission prompts
+   */
+  async request(method, endpoint, body) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      const permission = data.permission || "vectors.read";
+      const granted = await this.requestPermission(permission);
+      if (granted) {
+        return this.request(method, endpoint, body);
+      }
+      throw new PermissionDeniedError(permission);
+    }
+    if (!data.success && data.error) {
+      if (data.code === "LLM_ERROR") {
+        throw new LLMProviderError(data.error);
+      }
+      throw new Error(data.error);
+    }
+    return data;
+  }
   /**
    * Upsert (insert or update) vectors into storage
    * 
@@ -545,19 +592,10 @@ var VectorStore = class {
    * ```
    */
   async upsert(vectors, options = {}) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/upsert`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        vectors,
-        workspaceId: options.workspaceId
-      })
+    return this.request("POST", "/sdk/llm/vectors/upsert", {
+      vectors,
+      workspaceId: options.workspaceId
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.write");
-    }
-    return data;
   }
   /**
    * Query similar vectors by embedding
@@ -572,21 +610,12 @@ var VectorStore = class {
    * ```
    */
   async query(vector, options = {}) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/query`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        vector,
-        topK: options.topK ?? 5,
-        filter: options.filter,
-        workspaceId: options.workspaceId
-      })
+    return this.request("POST", "/sdk/llm/vectors/query", {
+      vector,
+      topK: options.topK ?? 5,
+      filter: options.filter,
+      workspaceId: options.workspaceId
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.read");
-    }
-    return data;
   }
   /**
    * Delete vectors from storage
@@ -600,16 +629,7 @@ var VectorStore = class {
    * ```
    */
   async delete(options) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/delete`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify(options)
-    });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.write");
-    }
-    return data;
+    return this.request("POST", "/sdk/llm/vectors/delete", options);
   }
   /**
    * List all available workspaces (namespaces) for this app
@@ -621,23 +641,48 @@ var VectorStore = class {
    * ```
    */
   async listWorkspaces() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/workspaces`, {
-      method: "GET",
-      headers: this.headers
+    return this.request("GET", "/sdk/llm/vectors/workspaces");
+  }
+  /**
+   * Register a custom vector database configuration for this app
+   * 
+   * @example
+   * ```ts
+   * await sdk.llm.vectors.registerConfig('lancedb', { });
+   * ```
+   */
+  async registerConfig(provider, config) {
+    return this.request("POST", "/sdk/llm/vectors/register", {
+      provider,
+      config
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.read");
-    }
-    return data;
+  }
+  /**
+   * List all supported vector database providers and their configuration requirements
+   */
+  async listProviders() {
+    return this.request("GET", "/sdk/llm/vectors/providers");
+  }
+  /**
+   * Get the current vector database configuration for this app
+   * 
+   * @example
+   * ```ts
+   * const { provider, config } = await sdk.llm.vectors.getConfig();
+   * console.log(`App is using ${provider}`);
+   * ```
+   */
+  async getConfig() {
+    return this.request("GET", "/sdk/llm/vectors/config");
   }
 };
 var LLMModule = class {
-  constructor(baseUrl, appId, apiKey) {
+  constructor(baseUrl, appId, appName = "Local App", apiKey) {
     this.baseUrl = baseUrl;
     this.appId = appId;
+    this.appName = appName;
     this.apiKey = apiKey;
-    this.vectors = new VectorStore(baseUrl, appId, apiKey);
+    this.vectors = new VectorStore(baseUrl, appId, appName, apiKey);
   }
   get headers() {
     if (this.apiKey) {
@@ -651,6 +696,52 @@ var LLMModule = class {
       "x-app-id": this.appId
     };
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/local-apps/request-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permission
+        })
+      });
+      const data = await response.json();
+      return data.granted === true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Internal request wrapper that handles automatic permission prompts
+   */
+  async request(method, endpoint, body) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      const permission = data.permission || "llm.chat";
+      const granted = await this.requestPermission(permission);
+      if (granted) {
+        return this.request(method, endpoint, body);
+      }
+      throw new PermissionDeniedError(permission);
+    }
+    if (!data.success && data.error) {
+      if (data.code === "LLM_ERROR") {
+        throw new LLMProviderError(data.error);
+      }
+      throw new Error(data.error);
+    }
+    return data;
+  }
   /**
    * Get only configured chat (LLM) providers
    * 
@@ -661,15 +752,7 @@ var LLMModule = class {
    * ```
    */
   async chatProviders() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/providers/chat`, {
-      method: "GET",
-      headers: this.headers
-    });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.providers");
-    }
-    return data;
+    return this.request("GET", "/sdk/llm/providers/chat");
   }
   /**
    * Get only configured embedding providers
@@ -681,15 +764,7 @@ var LLMModule = class {
    * ```
    */
   async embedProviders() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/providers/embed`, {
-      method: "GET",
-      headers: this.headers
-    });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.providers");
-    }
-    return data;
+    return this.request("GET", "/sdk/llm/providers/embed");
   }
   /**
    * Send a chat completion request (synchronous)
@@ -705,25 +780,14 @@ var LLMModule = class {
    * ```
    */
   async chat(messages, options = {}) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/chat`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        messages,
-        model: options.model,
-        provider: options.provider,
-        temperature: options.temperature ?? 0.7,
-        max_tokens: options.max_tokens ?? 1e3
-      })
+    return this.request("POST", "/sdk/llm/chat", {
+      messages,
+      model: options.model,
+      provider: options.provider,
+      temperature: options.temperature ?? 0.7,
+      max_tokens: options.max_tokens ?? 1e3,
+      response_format: options.response_format
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.chat");
-    }
-    if (data.code === "LLM_ERROR") {
-      throw new LLMProviderError(data.error || "LLM request failed");
-    }
-    return data;
   }
   /**
    * Send a streaming chat completion request (SSE)
@@ -749,13 +813,20 @@ var LLMModule = class {
         model: options.model,
         provider: options.provider,
         temperature: options.temperature ?? 0.7,
-        max_tokens: options.max_tokens ?? 1e3
+        max_tokens: options.max_tokens ?? 1e3,
+        response_format: options.response_format
       })
     });
     if (!response.ok) {
       const errorData = await response.json();
       if (errorData.code === "PERMISSION_REQUIRED") {
-        throw new LLMPermissionError(errorData.permission || "llm.chat");
+        const permission = errorData.permission || "llm.chat";
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          yield* this.chatStream(messages, options);
+          return;
+        }
+        throw new PermissionDeniedError(permission);
       }
       throw new LLMProviderError(errorData.error || "Stream request failed");
     }
@@ -830,23 +901,11 @@ var LLMModule = class {
    */
   async embed(input, options = {}) {
     const inputArray = Array.isArray(input) ? input : [input];
-    const response = await fetch(`${this.baseUrl}/sdk/llm/embed`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        input: inputArray,
-        provider: options.provider,
-        model: options.model
-      })
+    return this.request("POST", "/sdk/llm/embed", {
+      input: inputArray,
+      provider: options.provider,
+      model: options.model
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.embed");
-    }
-    if (data.code === "PROVIDER_UNAVAILABLE") {
-      throw new LLMProviderError(data.error || "Embedding provider not available");
-    }
-    return data;
   }
   /**
    * Helper: Embed text and store as vectors in one call
@@ -937,7 +996,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.port = new PortModule(config.defaultPort);
-    this.llm = new LLMModule(this.realtimexUrl, this.appId, this.apiKey);
+    this.llm = new LLMModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -1007,6 +1066,31 @@ var _RealtimeXSDK = class _RealtimeXSDK {
       throw new Error(`Connection failed: ${error.message}`);
     }
   }
+  /**
+   * Get the absolute path to the data directory for this app.
+   * Path: ~/.realtimex.ai/Resources/local-apps/{appId}
+   */
+  async getAppDataDir() {
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      } else if (this.appId) {
+        headers["x-app-id"] = this.appId;
+      }
+      const response = await fetch(`${this.realtimexUrl.replace(/\/$/, "")}/sdk/local-apps/data-dir`, {
+        method: "GET",
+        headers
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || "Failed to get data directory");
+      }
+      return data.dataDir;
+    } catch (error) {
+      throw new Error(`Failed to get app data directory: ${error.message}`);
+    }
+  }
 };
 _RealtimeXSDK.DEFAULT_REALTIMEX_URL = "http://localhost:3001";
 var RealtimeXSDK = _RealtimeXSDK;

package/dist/index.mjs

@@ -1,16 +1,18 @@
 // src/modules/api.ts
 var PermissionDeniedError = class extends Error {
-  constructor(permission, message) {
+  constructor(permission, message, code = "PERMISSION_DENIED") {
     super(message || `Permission '${permission}' was denied`);
     this.name = "PermissionDeniedError";
     this.permission = permission;
+    this.code = code;
   }
 };
 var PermissionRequiredError = class extends Error {
-  constructor(permission, message) {
+  constructor(permission, message, code = "PERMISSION_REQUIRED") {
     super(message || `Permission '${permission}' is required`);
     this.name = "PermissionRequiredError";
     this.permission = permission;
+    this.code = code;
   }
 };
 var ApiModule = class {
@@ -454,11 +456,9 @@ var PortModule = class {
 };
 
 // src/modules/llm.ts
-var LLMPermissionError = class extends Error {
+var LLMPermissionError = class extends PermissionRequiredError {
   constructor(permission, code = "PERMISSION_REQUIRED") {
-    super(`Permission required: ${permission}`);
-    this.permission = permission;
-    this.code = code;
+    super(permission, void 0, code);
     this.name = "LLMPermissionError";
   }
 };
@@ -470,9 +470,10 @@ var LLMProviderError = class extends Error {
   }
 };
 var VectorStore = class {
-  constructor(baseUrl, appId, apiKey) {
+  constructor(baseUrl, appId, appName = "Local App", apiKey) {
     this.baseUrl = baseUrl;
     this.appId = appId;
+    this.appName = appName;
     this.apiKey = apiKey;
   }
   get headers() {
@@ -487,6 +488,52 @@ var VectorStore = class {
       "x-app-id": this.appId
     };
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/local-apps/request-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permission
+        })
+      });
+      const data = await response.json();
+      return data.granted === true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Internal request wrapper that handles automatic permission prompts
+   */
+  async request(method, endpoint, body) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      const permission = data.permission || "vectors.read";
+      const granted = await this.requestPermission(permission);
+      if (granted) {
+        return this.request(method, endpoint, body);
+      }
+      throw new PermissionDeniedError(permission);
+    }
+    if (!data.success && data.error) {
+      if (data.code === "LLM_ERROR") {
+        throw new LLMProviderError(data.error);
+      }
+      throw new Error(data.error);
+    }
+    return data;
+  }
   /**
    * Upsert (insert or update) vectors into storage
    * 
@@ -498,19 +545,10 @@ var VectorStore = class {
    * ```
    */
   async upsert(vectors, options = {}) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/upsert`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        vectors,
-        workspaceId: options.workspaceId
-      })
+    return this.request("POST", "/sdk/llm/vectors/upsert", {
+      vectors,
+      workspaceId: options.workspaceId
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.write");
-    }
-    return data;
   }
   /**
    * Query similar vectors by embedding
@@ -525,21 +563,12 @@ var VectorStore = class {
    * ```
    */
   async query(vector, options = {}) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/query`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        vector,
-        topK: options.topK ?? 5,
-        filter: options.filter,
-        workspaceId: options.workspaceId
-      })
+    return this.request("POST", "/sdk/llm/vectors/query", {
+      vector,
+      topK: options.topK ?? 5,
+      filter: options.filter,
+      workspaceId: options.workspaceId
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.read");
-    }
-    return data;
   }
   /**
    * Delete vectors from storage
@@ -553,16 +582,7 @@ var VectorStore = class {
    * ```
    */
   async delete(options) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/delete`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify(options)
-    });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.write");
-    }
-    return data;
+    return this.request("POST", "/sdk/llm/vectors/delete", options);
   }
   /**
    * List all available workspaces (namespaces) for this app
@@ -574,23 +594,48 @@ var VectorStore = class {
    * ```
    */
   async listWorkspaces() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/workspaces`, {
-      method: "GET",
-      headers: this.headers
+    return this.request("GET", "/sdk/llm/vectors/workspaces");
+  }
+  /**
+   * Register a custom vector database configuration for this app
+   * 
+   * @example
+   * ```ts
+   * await sdk.llm.vectors.registerConfig('lancedb', { });
+   * ```
+   */
+  async registerConfig(provider, config) {
+    return this.request("POST", "/sdk/llm/vectors/register", {
+      provider,
+      config
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "vectors.read");
-    }
-    return data;
+  }
+  /**
+   * List all supported vector database providers and their configuration requirements
+   */
+  async listProviders() {
+    return this.request("GET", "/sdk/llm/vectors/providers");
+  }
+  /**
+   * Get the current vector database configuration for this app
+   * 
+   * @example
+   * ```ts
+   * const { provider, config } = await sdk.llm.vectors.getConfig();
+   * console.log(`App is using ${provider}`);
+   * ```
+   */
+  async getConfig() {
+    return this.request("GET", "/sdk/llm/vectors/config");
   }
 };
 var LLMModule = class {
-  constructor(baseUrl, appId, apiKey) {
+  constructor(baseUrl, appId, appName = "Local App", apiKey) {
     this.baseUrl = baseUrl;
     this.appId = appId;
+    this.appName = appName;
     this.apiKey = apiKey;
-    this.vectors = new VectorStore(baseUrl, appId, apiKey);
+    this.vectors = new VectorStore(baseUrl, appId, appName, apiKey);
   }
   get headers() {
     if (this.apiKey) {
@@ -604,6 +649,52 @@ var LLMModule = class {
       "x-app-id": this.appId
     };
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/local-apps/request-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permission
+        })
+      });
+      const data = await response.json();
+      return data.granted === true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Internal request wrapper that handles automatic permission prompts
+   */
+  async request(method, endpoint, body) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      const permission = data.permission || "llm.chat";
+      const granted = await this.requestPermission(permission);
+      if (granted) {
+        return this.request(method, endpoint, body);
+      }
+      throw new PermissionDeniedError(permission);
+    }
+    if (!data.success && data.error) {
+      if (data.code === "LLM_ERROR") {
+        throw new LLMProviderError(data.error);
+      }
+      throw new Error(data.error);
+    }
+    return data;
+  }
   /**
    * Get only configured chat (LLM) providers
    * 
@@ -614,15 +705,7 @@ var LLMModule = class {
    * ```
    */
   async chatProviders() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/providers/chat`, {
-      method: "GET",
-      headers: this.headers
-    });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.providers");
-    }
-    return data;
+    return this.request("GET", "/sdk/llm/providers/chat");
   }
   /**
    * Get only configured embedding providers
@@ -634,15 +717,7 @@ var LLMModule = class {
    * ```
    */
   async embedProviders() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/providers/embed`, {
-      method: "GET",
-      headers: this.headers
-    });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.providers");
-    }
-    return data;
+    return this.request("GET", "/sdk/llm/providers/embed");
   }
   /**
    * Send a chat completion request (synchronous)
@@ -658,25 +733,14 @@ var LLMModule = class {
    * ```
    */
   async chat(messages, options = {}) {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/chat`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        messages,
-        model: options.model,
-        provider: options.provider,
-        temperature: options.temperature ?? 0.7,
-        max_tokens: options.max_tokens ?? 1e3
-      })
+    return this.request("POST", "/sdk/llm/chat", {
+      messages,
+      model: options.model,
+      provider: options.provider,
+      temperature: options.temperature ?? 0.7,
+      max_tokens: options.max_tokens ?? 1e3,
+      response_format: options.response_format
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.chat");
-    }
-    if (data.code === "LLM_ERROR") {
-      throw new LLMProviderError(data.error || "LLM request failed");
-    }
-    return data;
   }
   /**
    * Send a streaming chat completion request (SSE)
@@ -702,13 +766,20 @@ var LLMModule = class {
         model: options.model,
         provider: options.provider,
         temperature: options.temperature ?? 0.7,
-        max_tokens: options.max_tokens ?? 1e3
+        max_tokens: options.max_tokens ?? 1e3,
+        response_format: options.response_format
       })
     });
     if (!response.ok) {
       const errorData = await response.json();
       if (errorData.code === "PERMISSION_REQUIRED") {
-        throw new LLMPermissionError(errorData.permission || "llm.chat");
+        const permission = errorData.permission || "llm.chat";
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          yield* this.chatStream(messages, options);
+          return;
+        }
+        throw new PermissionDeniedError(permission);
       }
       throw new LLMProviderError(errorData.error || "Stream request failed");
     }
@@ -783,23 +854,11 @@ var LLMModule = class {
    */
   async embed(input, options = {}) {
     const inputArray = Array.isArray(input) ? input : [input];
-    const response = await fetch(`${this.baseUrl}/sdk/llm/embed`, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({
-        input: inputArray,
-        provider: options.provider,
-        model: options.model
-      })
+    return this.request("POST", "/sdk/llm/embed", {
+      input: inputArray,
+      provider: options.provider,
+      model: options.model
     });
-    const data = await response.json();
-    if (data.code === "PERMISSION_REQUIRED") {
-      throw new LLMPermissionError(data.permission || "llm.embed");
-    }
-    if (data.code === "PROVIDER_UNAVAILABLE") {
-      throw new LLMProviderError(data.error || "Embedding provider not available");
-    }
-    return data;
   }
   /**
    * Helper: Embed text and store as vectors in one call
@@ -890,7 +949,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.port = new PortModule(config.defaultPort);
-    this.llm = new LLMModule(this.realtimexUrl, this.appId, this.apiKey);
+    this.llm = new LLMModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -960,6 +1019,31 @@ var _RealtimeXSDK = class _RealtimeXSDK {
       throw new Error(`Connection failed: ${error.message}`);
     }
   }
+  /**
+   * Get the absolute path to the data directory for this app.
+   * Path: ~/.realtimex.ai/Resources/local-apps/{appId}
+   */
+  async getAppDataDir() {
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      } else if (this.appId) {
+        headers["x-app-id"] = this.appId;
+      }
+      const response = await fetch(`${this.realtimexUrl.replace(/\/$/, "")}/sdk/local-apps/data-dir`, {
+        method: "GET",
+        headers
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || "Failed to get data directory");
+      }
+      return data.dataDir;
+    } catch (error) {
+      throw new Error(`Failed to get app data directory: ${error.message}`);
+    }
+  }
 };
 _RealtimeXSDK.DEFAULT_REALTIMEX_URL = "http://localhost:3001";
 var RealtimeXSDK = _RealtimeXSDK;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.1.2",
+    "version": "1.1.4",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",