@realtimex/sdk 1.0.9 → 1.1.2

package/dist/index.mjs

@@ -14,12 +14,19 @@ var PermissionRequiredError = class extends Error {
   }
 };
 var ApiModule = class {
-  constructor(realtimexUrl, appId, appName) {
+  constructor(realtimexUrl, appId, appName, apiKey) {
     this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
     this.appId = appId;
     this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+    this.apiKey = apiKey;
   }
   getHeaders() {
+    if (this.apiKey) {
+      return {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      };
+    }
     return {
       "Content-Type": "application/json",
       "x-app-id": this.appId
@@ -98,10 +105,11 @@ var ApiModule = class {
 
 // src/modules/activities.ts
 var ActivitiesModule = class {
-  constructor(realtimexUrl, appId, appName) {
+  constructor(realtimexUrl, appId, appName, apiKey) {
     this.baseUrl = realtimexUrl.replace(/\/$/, "");
     this.appId = appId;
     this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+    this.apiKey = apiKey;
   }
   /**
    * Request a single permission from Electron via internal API
@@ -129,8 +137,10 @@ var ActivitiesModule = class {
     const headers = {
       "Content-Type": "application/json"
     };
-    if (this.appId) {
-      headers["X-App-Id"] = this.appId;
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    } else if (this.appId) {
+      headers["x-app-id"] = this.appId;
     }
     const response = await fetch(url, {
       ...options,
@@ -217,10 +227,11 @@ var ActivitiesModule = class {
 
 // src/modules/webhook.ts
 var WebhookModule = class {
-  constructor(realtimexUrl, appName, appId) {
+  constructor(realtimexUrl, appName, appId, apiKey) {
     this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
     this.appName = appName;
     this.appId = appId;
+    this.apiKey = apiKey;
   }
   /**
    * Request a single permission from Electron via internal API
@@ -245,12 +256,18 @@ var WebhookModule = class {
   }
   async request(path, options = {}) {
     const url = `${this.realtimexUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    } else if (this.appId) {
+      headers["x-app-id"] = this.appId;
+    }
     const response = await fetch(url, {
       ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers
-      }
+      headers
     });
     const data = await response.json();
     if (response.status === 403) {
@@ -309,10 +326,11 @@ var WebhookModule = class {
 
 // src/modules/task.ts
 var TaskModule = class {
-  constructor(realtimexUrl, appName, appId) {
+  constructor(realtimexUrl, appName, appId, apiKey) {
     this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
     this.appName = appName;
     this.appId = appId;
+    this.apiKey = apiKey;
   }
   /**
    * Mark task as processing
@@ -333,9 +351,15 @@ var TaskModule = class {
     return this._sendEvent("task-fail", taskUuid, { error, machine_id: machineId });
   }
   async _sendEvent(event, taskUuid, extra) {
+    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}/webhooks/realtimex`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers,
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
@@ -429,21 +453,445 @@ 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, apiKey) {
+    this.baseUrl = baseUrl;
+    this.appId = appId;
+    this.apiKey = apiKey;
+  }
+  get headers() {
+    if (this.apiKey) {
+      return {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      };
+    }
+    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, apiKey) {
+    this.baseUrl = baseUrl;
+    this.appId = appId;
+    this.apiKey = apiKey;
+    this.vectors = new VectorStore(baseUrl, appId, apiKey);
+  }
+  get headers() {
+    if (this.apiKey) {
+      return {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      };
+    }
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Get only configured chat (LLM) providers
+   * 
+   * @example
+   * ```ts
+   * const { providers } = await sdk.llm.chatProviders();
+   * console.log('Available chat models:', providers[0].models);
+   * ```
+   */
+  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;
+  }
+  /**
+   * Get only configured embedding providers
+   * 
+   * @example
+   * ```ts
+   * const { providers } = await sdk.llm.embedProviders();
+   * console.log('Available embedding models:', providers[0].models);
+   * ```
+   */
+  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;
+  }
+  /**
+   * 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
+      };
+    }
+    let uniquePrefix = idPrefix;
+    if (idPrefix === "chunk") {
+      const randomSuffix = Math.random().toString(36).substring(2, 6);
+      uniquePrefix = `chunk_${randomSuffix}`;
+    }
+    const vectors = texts.map((text, i) => ({
+      id: `${uniquePrefix}_${i}`,
+      vector: embedResult.embeddings[i],
+      metadata: {
+        text,
+        documentId,
+        workspaceId,
+        embeddingModel: embedResult.model || model || "unknown"
+      }
+    }));
+    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,
+      model: options.model || embedResult.model
+    });
+    if (!queryResult.success) {
+      throw new LLMProviderError(queryResult.error || "Vector search failed");
+    }
+    return queryResult.results || [];
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
     const envAppId = this.getEnvVar("RTX_APP_ID");
     const envAppName = this.getEnvVar("RTX_APP_NAME");
+    const envApiKey = this.getEnvVar("RTX_API_KEY");
     this.appId = config.realtimex?.appId || envAppId || "";
     this.appName = config.realtimex?.appName || envAppName;
+    this.apiKey = config.realtimex?.apiKey || envApiKey;
     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.activities = new ActivitiesModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
+    this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
+    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);
-    if (this.permissions.length > 0) {
+    this.llm = new LLMModule(this.realtimexUrl, this.appId, this.apiKey);
+    if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
       });
@@ -487,16 +935,45 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     }
     return void 0;
   }
+  /**
+   * Ping RealtimeX server to verify connection and authentication.
+   * Works in both development (API Key) and production (App ID) modes.
+   */
+  async ping() {
+    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/ping`, {
+        method: "GET",
+        headers
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || "Ping failed");
+      }
+      return data;
+    } catch (error) {
+      throw new Error(`Connection failed: ${error.message}`);
+    }
+  }
 };
 _RealtimeXSDK.DEFAULT_REALTIMEX_URL = "http://localhost:3001";
 var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
   ApiModule,
+  LLMModule,
+  LLMPermissionError,
+  LLMProviderError,
   PermissionDeniedError,
   PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
   TaskModule,
+  VectorStore,
   WebhookModule
 };

package/package.json

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