@realtimex/sdk 1.1.1 → 1.1.2

package/README.md

@@ -25,6 +25,9 @@ Before using this SDK, ensure your Supabase database is set up:
 import { RealtimeXSDK } from '@realtimex/sdk';
 
 const sdk = new RealtimeXSDK({
+  // Development Mode: Use API key for full access
+  realtimex: { apiKey: 'sk-abc123...' }, 
+  // OR Production Mode: Declare permissions
   permissions: ['activities.read', 'activities.write', 'webhook.trigger']
 });
 
@@ -59,8 +62,9 @@ When you start your Local App from the RealtimeX Main App:
 const sdk = new RealtimeXSDK({
   realtimex: {
     url: 'http://custom-host:3001',  // Default: localhost:3001
-    appId: 'custom-id',               // Override auto-detected
-    appName: 'My App',                // Override auto-detected
+    apiKey: 'sk-abc123...',           // Development mode
+    appId: 'custom-id',               // Production mode (override)
+    appName: 'My App',                // Optional
   }
 });
 ```
@@ -133,11 +137,18 @@ const sdk = new RealtimeXSDK({
 #### List Providers & Models
 
 ```typescript
-const { llm, embedding } = await sdk.llm.getProviders();
-// llm[]: Array of LLM providers with models
-// embedding[]: Array of embedding providers with models
+
+
+// Get only configured Chat providers (recommended)
+const chatRes = await sdk.llm.chatProviders();
+// chatRes.providers: Array of chat providers with models
+
+// Get only configured Embedding providers (recommended)
+const embedRes = await sdk.llm.embedProviders();
+// embedRes.providers: Array of embedding providers with models
 ```
 
+
 #### Chat Completion
 
 ```typescript

package/dist/index.d.mts

@@ -6,6 +6,7 @@ interface SDKConfig {
         url?: string;
         appId?: string;
         appName?: string;
+        apiKey?: string;
     };
     defaultPort?: number;
     permissions?: string[];
@@ -88,7 +89,8 @@ declare class ActivitiesModule {
     private baseUrl;
     private appId;
     private appName;
-    constructor(realtimexUrl: string, appId: string, appName?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
     /**
      * Request a single permission from Electron via internal API
      */
@@ -124,7 +126,8 @@ declare class WebhookModule {
     private realtimexUrl;
     private appName?;
     private appId?;
-    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
      * Request a single permission from Electron via internal API
      */
@@ -160,7 +163,8 @@ declare class ApiModule {
     private realtimexUrl;
     private appId;
     private appName;
-    constructor(realtimexUrl: string, appId: string, appName?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
     private getHeaders;
     /**
      * Request a single permission from Electron via internal API
@@ -190,7 +194,8 @@ declare class TaskModule {
     private realtimexUrl;
     private appName?;
     private appId?;
-    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
      * Mark task as processing
      */
@@ -317,6 +322,7 @@ interface ProvidersResponse {
     success: boolean;
     llm?: Provider[];
     embedding?: Provider[];
+    providers?: Provider[];
     error?: string;
     code?: string;
 }
@@ -397,7 +403,8 @@ declare class LLMProviderError extends Error {
 declare class VectorStore {
     private baseUrl;
     private appId;
-    constructor(baseUrl: string, appId: string);
+    private apiKey?;
+    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
     private get headers();
     /**
      * Upsert (insert or update) vectors into storage
@@ -449,19 +456,30 @@ declare class VectorStore {
 declare class LLMModule {
     private baseUrl;
     private appId;
+    private apiKey?;
     vectors: VectorStore;
-    constructor(baseUrl: string, appId: string);
+    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
     private get headers();
     /**
-     * Get available LLM and embedding providers/models
+     * Get only configured chat (LLM) providers
      *
      * @example
      * ```ts
-     * const { llm, embedding } = await sdk.llm.getProviders();
-     * console.log('Available LLM models:', llm[0].models);
+     * const { providers } = await sdk.llm.chatProviders();
+     * console.log('Available chat models:', providers[0].models);
      * ```
      */
-    getProviders(): Promise<ProvidersResponse>;
+    chatProviders(): Promise<ProvidersResponse>;
+    /**
+     * Get only configured embedding providers
+     *
+     * @example
+     * ```ts
+     * const { providers } = await sdk.llm.embedProviders();
+     * console.log('Available embedding models:', providers[0].models);
+     * ```
+     */
+    embedProviders(): Promise<ProvidersResponse>;
     /**
      * Send a chat completion request (synchronous)
      *
@@ -556,6 +574,7 @@ declare class RealtimeXSDK {
     llm: LLMModule;
     readonly appId: string;
     readonly appName: string | undefined;
+    readonly apiKey: string | undefined;
     private readonly realtimexUrl;
     private readonly permissions;
     private static DEFAULT_REALTIMEX_URL;
@@ -569,6 +588,16 @@ declare class RealtimeXSDK {
      * Get environment variable (works in Node.js and browser)
      */
     private getEnvVar;
+    /**
+     * Ping RealtimeX server to verify connection and authentication.
+     * Works in both development (API Key) and production (App ID) modes.
+     */
+    ping(): Promise<{
+        success: boolean;
+        mode: 'development' | 'production';
+        appId?: string;
+        timestamp: 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

@@ -6,6 +6,7 @@ interface SDKConfig {
         url?: string;
         appId?: string;
         appName?: string;
+        apiKey?: string;
     };
     defaultPort?: number;
     permissions?: string[];
@@ -88,7 +89,8 @@ declare class ActivitiesModule {
     private baseUrl;
     private appId;
     private appName;
-    constructor(realtimexUrl: string, appId: string, appName?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
     /**
      * Request a single permission from Electron via internal API
      */
@@ -124,7 +126,8 @@ declare class WebhookModule {
     private realtimexUrl;
     private appName?;
     private appId?;
-    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
      * Request a single permission from Electron via internal API
      */
@@ -160,7 +163,8 @@ declare class ApiModule {
     private realtimexUrl;
     private appId;
     private appName;
-    constructor(realtimexUrl: string, appId: string, appName?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
     private getHeaders;
     /**
      * Request a single permission from Electron via internal API
@@ -190,7 +194,8 @@ declare class TaskModule {
     private realtimexUrl;
     private appName?;
     private appId?;
-    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
      * Mark task as processing
      */
@@ -317,6 +322,7 @@ interface ProvidersResponse {
     success: boolean;
     llm?: Provider[];
     embedding?: Provider[];
+    providers?: Provider[];
     error?: string;
     code?: string;
 }
@@ -397,7 +403,8 @@ declare class LLMProviderError extends Error {
 declare class VectorStore {
     private baseUrl;
     private appId;
-    constructor(baseUrl: string, appId: string);
+    private apiKey?;
+    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
     private get headers();
     /**
      * Upsert (insert or update) vectors into storage
@@ -449,19 +456,30 @@ declare class VectorStore {
 declare class LLMModule {
     private baseUrl;
     private appId;
+    private apiKey?;
     vectors: VectorStore;
-    constructor(baseUrl: string, appId: string);
+    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
     private get headers();
     /**
-     * Get available LLM and embedding providers/models
+     * Get only configured chat (LLM) providers
      *
      * @example
      * ```ts
-     * const { llm, embedding } = await sdk.llm.getProviders();
-     * console.log('Available LLM models:', llm[0].models);
+     * const { providers } = await sdk.llm.chatProviders();
+     * console.log('Available chat models:', providers[0].models);
      * ```
      */
-    getProviders(): Promise<ProvidersResponse>;
+    chatProviders(): Promise<ProvidersResponse>;
+    /**
+     * Get only configured embedding providers
+     *
+     * @example
+     * ```ts
+     * const { providers } = await sdk.llm.embedProviders();
+     * console.log('Available embedding models:', providers[0].models);
+     * ```
+     */
+    embedProviders(): Promise<ProvidersResponse>;
     /**
      * Send a chat completion request (synchronous)
      *
@@ -556,6 +574,7 @@ declare class RealtimeXSDK {
     llm: LLMModule;
     readonly appId: string;
     readonly appName: string | undefined;
+    readonly apiKey: string | undefined;
     private readonly realtimexUrl;
     private readonly permissions;
     private static DEFAULT_REALTIMEX_URL;
@@ -569,6 +588,16 @@ declare class RealtimeXSDK {
      * Get environment variable (works in Node.js and browser)
      */
     private getEnvVar;
+    /**
+     * Ping RealtimeX server to verify connection and authentication.
+     * Works in both development (API Key) and production (App ID) modes.
+     */
+    ping(): Promise<{
+        success: boolean;
+        mode: 'development' | 'production';
+        appId?: string;
+        timestamp: 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

@@ -61,12 +61,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
@@ -145,10 +152,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
@@ -176,8 +184,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,
@@ -264,10 +274,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
@@ -292,12 +303,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) {
@@ -356,10 +373,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
@@ -380,9 +398,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,
@@ -493,11 +517,18 @@ var LLMProviderError = class extends Error {
   }
 };
 var VectorStore = class {
-  constructor(baseUrl, appId) {
+  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
@@ -602,28 +633,55 @@ var VectorStore = class {
   }
 };
 var LLMModule = class {
-  constructor(baseUrl, appId) {
+  constructor(baseUrl, appId, apiKey) {
     this.baseUrl = baseUrl;
     this.appId = appId;
-    this.vectors = new VectorStore(baseUrl, 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 available LLM and embedding providers/models
+   * Get only configured chat (LLM) providers
    * 
    * @example
    * ```ts
-   * const { llm, embedding } = await sdk.llm.getProviders();
-   * console.log('Available LLM models:', llm[0].models);
+   * const { providers } = await sdk.llm.chatProviders();
+   * console.log('Available chat models:', providers[0].models);
    * ```
    */
-  async getProviders() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/providers`, {
+  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
     });
@@ -812,13 +870,19 @@ var LLMModule = class {
         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: `${idPrefix}_${i}`,
+      id: `${uniquePrefix}_${i}`,
       vector: embedResult.embeddings[i],
       metadata: {
         text,
         documentId,
-        workspaceId
+        workspaceId,
+        embeddingModel: embedResult.model || model || "unknown"
       }
     }));
     return this.vectors.upsert(vectors, { workspaceId });
@@ -846,7 +910,10 @@ var LLMModule = class {
     if (!embedResult.success || !embedResult.embeddings?.[0]) {
       throw new LLMProviderError("Failed to embed query");
     }
-    const queryResult = await this.vectors.query(embedResult.embeddings[0], options);
+    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");
     }
@@ -859,17 +926,19 @@ 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);
-    this.llm = new LLMModule(this.realtimexUrl, this.appId);
-    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);
       });
@@ -913,6 +982,31 @@ 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;

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,
@@ -446,11 +470,18 @@ var LLMProviderError = class extends Error {
   }
 };
 var VectorStore = class {
-  constructor(baseUrl, appId) {
+  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
@@ -555,28 +586,55 @@ var VectorStore = class {
   }
 };
 var LLMModule = class {
-  constructor(baseUrl, appId) {
+  constructor(baseUrl, appId, apiKey) {
     this.baseUrl = baseUrl;
     this.appId = appId;
-    this.vectors = new VectorStore(baseUrl, 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 available LLM and embedding providers/models
+   * Get only configured chat (LLM) providers
    * 
    * @example
    * ```ts
-   * const { llm, embedding } = await sdk.llm.getProviders();
-   * console.log('Available LLM models:', llm[0].models);
+   * const { providers } = await sdk.llm.chatProviders();
+   * console.log('Available chat models:', providers[0].models);
    * ```
    */
-  async getProviders() {
-    const response = await fetch(`${this.baseUrl}/sdk/llm/providers`, {
+  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
     });
@@ -765,13 +823,19 @@ var LLMModule = class {
         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: `${idPrefix}_${i}`,
+      id: `${uniquePrefix}_${i}`,
       vector: embedResult.embeddings[i],
       metadata: {
         text,
         documentId,
-        workspaceId
+        workspaceId,
+        embeddingModel: embedResult.model || model || "unknown"
       }
     }));
     return this.vectors.upsert(vectors, { workspaceId });
@@ -799,7 +863,10 @@ var LLMModule = class {
     if (!embedResult.success || !embedResult.embeddings?.[0]) {
       throw new LLMProviderError("Failed to embed query");
     }
-    const queryResult = await this.vectors.query(embedResult.embeddings[0], options);
+    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");
     }
@@ -812,17 +879,19 @@ 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);
-    this.llm = new LLMModule(this.realtimexUrl, this.appId);
-    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);
       });
@@ -866,6 +935,31 @@ 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;

package/package.json

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