@realtimex/sdk 1.1.1 → 1.1.3

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
      */
@@ -147,20 +150,23 @@ 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;
     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 +196,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
      */
@@ -258,6 +265,7 @@ declare class PortModule {
  * - Provider/model listing
  * - Vector storage (upsert, query, delete)
  */
+
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
@@ -267,6 +275,9 @@ interface ChatOptions {
     provider?: string;
     temperature?: number;
     max_tokens?: number;
+    response_format?: {
+        type: string;
+    };
 }
 interface ChatResponse {
     success: boolean;
@@ -317,6 +328,7 @@ interface ProvidersResponse {
     success: boolean;
     llm?: Provider[];
     embedding?: Provider[];
+    providers?: Provider[];
     error?: string;
     code?: string;
 }
@@ -385,9 +397,10 @@ interface VectorListWorkspacesResponse {
     error?: string;
     code?: string;
 }
-declare class LLMPermissionError extends Error {
-    permission: string;
-    code: string;
+/**
+ * @deprecated Use PermissionRequiredError from api module instead
+ */
+declare class LLMPermissionError extends PermissionRequiredError {
     constructor(permission: string, code?: string);
 }
 declare class LLMProviderError extends Error {
@@ -397,8 +410,18 @@ declare class LLMProviderError extends Error {
 declare class VectorStore {
     private baseUrl;
     private appId;
-    constructor(baseUrl: string, appId: string);
+    private appName;
+    private apiKey?;
+    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
      *
@@ -449,19 +472,39 @@ declare class VectorStore {
 declare class LLMModule {
     private baseUrl;
     private appId;
+    private appName;
+    private apiKey?;
     vectors: VectorStore;
-    constructor(baseUrl: string, appId: string);
+    constructor(baseUrl: string, appId: string, appName?: string, apiKey?: string | undefined);
     private get headers();
     /**
-     * Get available LLM and embedding providers/models
+     * 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
+     *
+     * @example
+     * ```ts
+     * const { providers } = await sdk.llm.chatProviders();
+     * console.log('Available chat models:', providers[0].models);
+     * ```
+     */
+    chatProviders(): Promise<ProvidersResponse>;
+    /**
+     * Get only configured embedding providers
      *
      * @example
      * ```ts
-     * const { llm, embedding } = await sdk.llm.getProviders();
-     * console.log('Available LLM models:', llm[0].models);
+     * const { providers } = await sdk.llm.embedProviders();
+     * console.log('Available embedding models:', providers[0].models);
      * ```
      */
-    getProviders(): Promise<ProvidersResponse>;
+    embedProviders(): Promise<ProvidersResponse>;
     /**
      * Send a chat completion request (synchronous)
      *
@@ -556,6 +599,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 +613,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
      */
@@ -147,20 +150,23 @@ 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;
     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 +196,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
      */
@@ -258,6 +265,7 @@ declare class PortModule {
  * - Provider/model listing
  * - Vector storage (upsert, query, delete)
  */
+
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
@@ -267,6 +275,9 @@ interface ChatOptions {
     provider?: string;
     temperature?: number;
     max_tokens?: number;
+    response_format?: {
+        type: string;
+    };
 }
 interface ChatResponse {
     success: boolean;
@@ -317,6 +328,7 @@ interface ProvidersResponse {
     success: boolean;
     llm?: Provider[];
     embedding?: Provider[];
+    providers?: Provider[];
     error?: string;
     code?: string;
 }
@@ -385,9 +397,10 @@ interface VectorListWorkspacesResponse {
     error?: string;
     code?: string;
 }
-declare class LLMPermissionError extends Error {
-    permission: string;
-    code: string;
+/**
+ * @deprecated Use PermissionRequiredError from api module instead
+ */
+declare class LLMPermissionError extends PermissionRequiredError {
     constructor(permission: string, code?: string);
 }
 declare class LLMProviderError extends Error {
@@ -397,8 +410,18 @@ declare class LLMProviderError extends Error {
 declare class VectorStore {
     private baseUrl;
     private appId;
-    constructor(baseUrl: string, appId: string);
+    private appName;
+    private apiKey?;
+    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
      *
@@ -449,19 +472,39 @@ declare class VectorStore {
 declare class LLMModule {
     private baseUrl;
     private appId;
+    private appName;
+    private apiKey?;
     vectors: VectorStore;
-    constructor(baseUrl: string, appId: string);
+    constructor(baseUrl: string, appId: string, appName?: string, apiKey?: string | undefined);
     private get headers();
     /**
-     * Get available LLM and embedding providers/models
+     * 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
+     *
+     * @example
+     * ```ts
+     * const { providers } = await sdk.llm.chatProviders();
+     * console.log('Available chat models:', providers[0].models);
+     * ```
+     */
+    chatProviders(): Promise<ProvidersResponse>;
+    /**
+     * Get only configured embedding providers
      *
      * @example
      * ```ts
-     * const { llm, embedding } = await sdk.llm.getProviders();
-     * console.log('Available LLM models:', llm[0].models);
+     * const { providers } = await sdk.llm.embedProviders();
+     * console.log('Available embedding models:', providers[0].models);
      * ```
      */
-    getProviders(): Promise<ProvidersResponse>;
+    embedProviders(): Promise<ProvidersResponse>;
     /**
      * Send a chat completion request (synchronous)
      *
@@ -556,6 +599,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 +613,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 };