@realtimex/sdk 1.0.8 → 1.1.1

package/dist/index.mjs

@@ -1,8 +1,128 @@
+// src/modules/api.ts
+var PermissionDeniedError = class extends Error {
+  constructor(permission, message) {
+    super(message || `Permission '${permission}' was denied`);
+    this.name = "PermissionDeniedError";
+    this.permission = permission;
+  }
+};
+var PermissionRequiredError = class extends Error {
+  constructor(permission, message) {
+    super(message || `Permission '${permission}' is required`);
+    this.name = "PermissionRequiredError";
+    this.permission = permission;
+  }
+};
+var ApiModule = class {
+  constructor(realtimexUrl, appId, appName) {
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appId = appId;
+    this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+  }
+  getHeaders() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.realtimexUrl}/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;
+    }
+  }
+  /**
+   * Make an API call with automatic permission handling
+   */
+  async apiCall(method, endpoint, options) {
+    const url = `${this.realtimexUrl}${endpoint}`;
+    const response = await fetch(url, {
+      method,
+      headers: this.getHeaders(),
+      ...options
+    });
+    const data = await response.json();
+    if (response.status === 403) {
+      const errorCode = data.error;
+      const permission = data.permission;
+      const message = data.message;
+      if (errorCode === "PERMISSION_REQUIRED" && permission) {
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          return this.apiCall(method, endpoint, options);
+        } else {
+          throw new PermissionDeniedError(permission, message);
+        }
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+      throw new Error(data.error || "Permission denied");
+    }
+    if (!response.ok) {
+      throw new Error(data.error || `API call failed: ${response.status}`);
+    }
+    return data;
+  }
+  async getAgents() {
+    const data = await this.apiCall("GET", "/agents");
+    return data.agents;
+  }
+  async getWorkspaces() {
+    const data = await this.apiCall("GET", "/workspaces");
+    return data.workspaces;
+  }
+  async getThreads(workspaceSlug) {
+    const data = await this.apiCall("GET", `/workspaces/${encodeURIComponent(workspaceSlug)}/threads`);
+    return data.threads;
+  }
+  async getTask(taskUuid) {
+    const data = await this.apiCall("GET", `/task/${encodeURIComponent(taskUuid)}`);
+    return { ...data.task, runs: data.runs };
+  }
+};
+
 // src/modules/activities.ts
 var ActivitiesModule = class {
-  constructor(realtimexUrl, appId) {
+  constructor(realtimexUrl, appId, appName) {
     this.baseUrl = realtimexUrl.replace(/\/$/, "");
     this.appId = appId;
+    this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+  }
+  /**
+   * 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) {
+      console.error("[SDK] Permission request failed:", error);
+      return false;
+    }
   }
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
@@ -20,6 +140,22 @@ var ActivitiesModule = class {
       }
     });
     const data = await response.json();
+    if (response.status === 403) {
+      const errorCode = data.error;
+      const permission = data.permission;
+      const message = data.message;
+      if (errorCode === "PERMISSION_REQUIRED" && permission) {
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          return this.request(path, options);
+        } else {
+          throw new PermissionDeniedError(permission, message);
+        }
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+    }
     if (!response.ok) {
       throw new Error(data.error || `Request failed: ${response.status}`);
     }
@@ -86,13 +222,64 @@ var WebhookModule = class {
     this.appName = appName;
     this.appId = appId;
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.realtimexUrl}/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) {
+      console.error("[SDK] Permission request failed:", error);
+      return false;
+    }
+  }
+  async request(path, options = {}) {
+    const url = `${this.realtimexUrl}${path}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+    const data = await response.json();
+    if (response.status === 403) {
+      const errorCode = data.error;
+      const permission = data.permission;
+      const message = data.message;
+      if (errorCode === "PERMISSION_REQUIRED" && permission) {
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          return this.request(path, options);
+        } else {
+          throw new PermissionDeniedError(permission, message);
+        }
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+    }
+    if (!response.ok) {
+      throw new Error(data.error || `Request failed: ${response.status}`);
+    }
+    return data;
+  }
   async triggerAgent(payload) {
     if (payload.auto_run && (!payload.agent_name || !payload.workspace_slug)) {
       throw new Error("auto_run requires agent_name and workspace_slug");
     }
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    return this.request("/webhooks/realtimex", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
@@ -107,69 +294,16 @@ var WebhookModule = class {
         }
       })
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to trigger agent");
-    return data;
   }
   async ping() {
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    return this.request("/webhooks/realtimex", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
         event: "ping"
       })
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Ping failed");
-    return data;
-  }
-};
-
-// src/modules/api.ts
-var ApiModule = class {
-  constructor(realtimexUrl, appId) {
-    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
-    this.appId = appId;
-  }
-  getHeaders() {
-    return {
-      "Content-Type": "application/json",
-      "x-app-id": this.appId
-    };
-  }
-  async getAgents() {
-    const response = await fetch(`${this.realtimexUrl}/agents`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get agents");
-    return data.agents;
-  }
-  async getWorkspaces() {
-    const response = await fetch(`${this.realtimexUrl}/workspaces`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get workspaces");
-    return data.workspaces;
-  }
-  async getThreads(workspaceSlug) {
-    const response = await fetch(`${this.realtimexUrl}/workspaces/${encodeURIComponent(workspaceSlug)}/threads`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get threads");
-    return data.threads;
-  }
-  async getTask(taskUuid) {
-    const response = await fetch(`${this.realtimexUrl}/task/${encodeURIComponent(taskUuid)}`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get task");
-    return { ...data.task, runs: data.runs };
   }
 };
 
@@ -295,6 +429,384 @@ var PortModule = class {
   }
 };
 
+// src/modules/llm.ts
+var LLMPermissionError = class extends Error {
+  constructor(permission, code = "PERMISSION_REQUIRED") {
+    super(`Permission required: ${permission}`);
+    this.permission = permission;
+    this.code = code;
+    this.name = "LLMPermissionError";
+  }
+};
+var LLMProviderError = class extends Error {
+  constructor(message, code = "LLM_ERROR") {
+    super(message);
+    this.code = code;
+    this.name = "LLMProviderError";
+  }
+};
+var VectorStore = class {
+  constructor(baseUrl, appId) {
+    this.baseUrl = baseUrl;
+    this.appId = appId;
+  }
+  get headers() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Upsert (insert or update) vectors into storage
+   * 
+   * @example
+   * ```ts
+   * await sdk.llm.vectors.upsert([
+   *   { id: 'chunk-1', vector: embeddings[0], metadata: { text: 'Hello', documentId: 'doc-1' } }
+   * ], { workspaceId: 'ws-123' });
+   * ```
+   */
+  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
+      })
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.write");
+    }
+    return data;
+  }
+  /**
+   * Query similar vectors by embedding
+   * 
+   * @example
+   * ```ts
+   * const results = await sdk.llm.vectors.query(queryVector, {
+   *   topK: 5,
+   *   filter: { documentId: 'doc-1' },
+   *   workspaceId: 'ws-123'
+   * });
+   * ```
+   */
+  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
+      })
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.read");
+    }
+    return data;
+  }
+  /**
+   * Delete vectors from storage
+   * 
+   * Note: Currently only supports deleteAll: true
+   * Use workspaceId to scope deletion to a specific workspace
+   * 
+   * @example
+   * ```ts
+   * await sdk.llm.vectors.delete({ deleteAll: true, workspaceId: 'ws-123' });
+   * ```
+   */
+  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;
+  }
+  /**
+   * List all available workspaces (namespaces) for this app
+   * 
+   * @example
+   * ```ts
+   * const { workspaces } = await sdk.llm.vectors.listWorkspaces();
+   * console.log('Workspaces:', workspaces);
+   * ```
+   */
+  async listWorkspaces() {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/workspaces`, {
+      method: "GET",
+      headers: this.headers
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.read");
+    }
+    return data;
+  }
+};
+var LLMModule = class {
+  constructor(baseUrl, appId) {
+    this.baseUrl = baseUrl;
+    this.appId = appId;
+    this.vectors = new VectorStore(baseUrl, appId);
+  }
+  get headers() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Get available LLM and embedding providers/models
+   * 
+   * @example
+   * ```ts
+   * const { llm, embedding } = await sdk.llm.getProviders();
+   * console.log('Available LLM models:', llm[0].models);
+   * ```
+   */
+  async getProviders() {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/providers`, {
+      method: "GET",
+      headers: this.headers
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "llm.providers");
+    }
+    return data;
+  }
+  /**
+   * Send a chat completion request (synchronous)
+   * 
+   * @example
+   * ```ts
+   * const response = await sdk.llm.chat([
+   *   { role: 'system', content: 'You are a helpful assistant.' },
+   *   { role: 'user', content: 'Hello!' }
+   * ], { model: 'gpt-4o', temperature: 0.7 });
+   * 
+   * console.log(response.response?.content);
+   * ```
+   */
+  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
+      })
+    });
+    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)
+   * 
+   * @example
+   * ```ts
+   * for await (const chunk of sdk.llm.chatStream([
+   *   { role: 'user', content: 'Tell me a story' }
+   * ])) {
+   *   process.stdout.write(chunk.textResponse || '');
+   * }
+   * ```
+   */
+  async *chatStream(messages, options = {}) {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/chat/stream`, {
+      method: "POST",
+      headers: {
+        ...this.headers,
+        "Accept": "text/event-stream"
+      },
+      body: JSON.stringify({
+        messages,
+        model: options.model,
+        provider: options.provider,
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens ?? 1e3
+      })
+    });
+    if (!response.ok) {
+      const errorData = await response.json();
+      if (errorData.code === "PERMISSION_REQUIRED") {
+        throw new LLMPermissionError(errorData.permission || "llm.chat");
+      }
+      throw new LLMProviderError(errorData.error || "Stream request failed");
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new LLMProviderError("Response body is not readable");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let isErrorEvent = false;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmedLine = line.trim();
+          if (!trimmedLine || trimmedLine.startsWith(":")) continue;
+          if (trimmedLine.startsWith("event: error")) {
+            isErrorEvent = true;
+            continue;
+          }
+          if (trimmedLine.startsWith("data: ")) {
+            const jsonStr = trimmedLine.slice(6);
+            if (jsonStr === "[DONE]") {
+              isErrorEvent = false;
+              continue;
+            }
+            try {
+              const data = JSON.parse(jsonStr);
+              if (isErrorEvent) {
+                isErrorEvent = false;
+                throw new LLMProviderError(
+                  data.error || "Stream error",
+                  data.code || "LLM_STREAM_ERROR"
+                );
+              }
+              const chunk = data;
+              if (chunk.error) {
+                throw new LLMProviderError(
+                  chunk.message || "Stream error"
+                );
+              }
+              yield chunk;
+            } catch (parseError) {
+              isErrorEvent = false;
+              if (jsonStr !== "[DONE]") {
+                console.warn("[LLM Stream] Parse error:", jsonStr);
+              }
+              if (parseError instanceof LLMProviderError) throw parseError;
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * Generate vector embeddings from text
+   * 
+   * @example
+   * ```ts
+   * // Single text
+   * const { embeddings } = await sdk.llm.embed('Hello world');
+   * 
+   * // Multiple texts
+   * const { embeddings } = await sdk.llm.embed(['Hello', 'World']);
+   * ```
+   */
+  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
+      })
+    });
+    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
+   * 
+   * @example
+   * ```ts
+   * await sdk.llm.embedAndStore({
+   *   texts: ['Hello world', 'Goodbye world'],
+   *   documentId: 'doc-123',
+   *   workspaceId: 'ws-456'
+   * });
+   * ```
+   */
+  async embedAndStore(params) {
+    const { texts, documentId, workspaceId, idPrefix = "chunk", provider, model } = params;
+    const embedResult = await this.embed(texts, { provider, model });
+    if (!embedResult.success || !embedResult.embeddings) {
+      return {
+        success: false,
+        error: embedResult.error || "Embedding failed",
+        code: embedResult.code
+      };
+    }
+    const vectors = texts.map((text, i) => ({
+      id: `${idPrefix}_${i}`,
+      vector: embedResult.embeddings[i],
+      metadata: {
+        text,
+        documentId,
+        workspaceId
+      }
+    }));
+    return this.vectors.upsert(vectors, { workspaceId });
+  }
+  /**
+   * Helper: Search similar documents by text query
+   * 
+   * @example
+   * ```ts
+   * const results = await sdk.llm.search('What is RealtimeX?', {
+   *   topK: 5,
+   *   workspaceId: 'ws-123'
+   * });
+   * 
+   * for (const result of results) {
+   *   console.log(result.metadata?.text, result.score);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const embedResult = await this.embed(query, {
+      provider: options.provider,
+      model: options.model
+    });
+    if (!embedResult.success || !embedResult.embeddings?.[0]) {
+      throw new LLMProviderError("Failed to embed query");
+    }
+    const queryResult = await this.vectors.query(embedResult.embeddings[0], options);
+    if (!queryResult.success) {
+      throw new LLMProviderError(queryResult.error || "Vector search failed");
+    }
+    return queryResult.results || [];
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -302,12 +814,45 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     const envAppName = this.getEnvVar("RTX_APP_NAME");
     this.appId = config.realtimex?.appId || envAppId || "";
     this.appName = config.realtimex?.appName || envAppName;
-    const realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
-    this.activities = new ActivitiesModule(realtimexUrl, this.appId);
-    this.webhook = new WebhookModule(realtimexUrl, this.appName, this.appId);
-    this.api = new ApiModule(realtimexUrl, this.appId);
-    this.task = new TaskModule(realtimexUrl, this.appName, this.appId);
+    this.permissions = config.permissions || [];
+    this.realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
+    this.activities = new ActivitiesModule(this.realtimexUrl, this.appId, this.appName);
+    this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId);
+    this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName);
+    this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId);
     this.port = new PortModule(config.defaultPort);
+    this.llm = new LLMModule(this.realtimexUrl, this.appId);
+    if (this.permissions.length > 0) {
+      this.register().catch((err) => {
+        console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
+      });
+    }
+  }
+  /**
+   * Register app with RealtimeX hub and request declared permissions upfront.
+   * This is called automatically if permissions are provided in constructor.
+   */
+  async register(permissions) {
+    const perms = permissions || this.permissions;
+    if (perms.length === 0) return;
+    try {
+      const response = await fetch(`${this.realtimexUrl.replace(/\/$/, "")}/sdk/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permissions: perms
+        })
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || "Registration failed");
+      }
+      console.log(`[RealtimeX SDK] App registered successfully (${data.message})`);
+    } catch (error) {
+      throw new Error(`Failed to register app: ${error.message}`);
+    }
   }
   /**
    * Get environment variable (works in Node.js and browser)
@@ -327,8 +872,14 @@ var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
   ApiModule,
+  LLMModule,
+  LLMPermissionError,
+  LLMProviderError,
+  PermissionDeniedError,
+  PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
   TaskModule,
+  VectorStore,
   WebhookModule
 };