@realtimex/sdk 1.1.4 → 1.2.0

package/dist/index.d.mts

@@ -79,6 +79,24 @@ interface Task {
     updated_at: string;
     runs: TaskRun[];
 }
+interface TTSOptions {
+    voice?: string;
+    model?: string;
+    speed?: number;
+    provider?: string;
+}
+interface TTSProvider {
+    id: string;
+    name: string;
+    type: 'remote' | 'local';
+    voices: string[];
+}
+interface TTSProvidersResponse {
+    success: boolean;
+    providers: TTSProvider[];
+    default: string;
+    error?: string;
+}
 
 /**
  * Activities Module - HTTP Proxy to RealtimeX Main App
@@ -636,6 +654,49 @@ declare class LLMModule {
     search(query: string, options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
 }
 
+declare class TTSModule {
+    private baseUrl;
+    private appId;
+    private appName;
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
+    private get headers();
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Internal request wrapper that handles automatic permission prompts
+     */
+    private request;
+    /**
+     * Generate speech from text (returns full buffer)
+     *
+     * @example
+     * ```ts
+     * const buffer = await sdk.tts.speak("Hello world");
+     * // Play buffer...
+     * ```
+     */
+    speak(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
+    /**
+     * Generate speech from text (returns stream)
+     *
+     * @example
+     * ```ts
+     * const stream = await sdk.tts.speakStream("Hello world");
+     * for await (const chunk of stream) {
+     *   // Play chunk...
+     * }
+     * ```
+     */
+    speakStream(text: string, options?: TTSOptions): AsyncGenerator<Uint8Array>;
+    /**
+     * List available TTS providers
+     */
+    listProviders(): Promise<TTSProvider[]>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -650,6 +711,7 @@ declare class RealtimeXSDK {
     task: TaskModule;
     port: PortModule;
     llm: LLMModule;
+    tts: TTSModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -683,4 +745,4 @@ declare class RealtimeXSDK {
     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 };
+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, TTSModule, type TTSOptions, type TTSProvider, type TTSProvidersResponse, 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

@@ -79,6 +79,24 @@ interface Task {
     updated_at: string;
     runs: TaskRun[];
 }
+interface TTSOptions {
+    voice?: string;
+    model?: string;
+    speed?: number;
+    provider?: string;
+}
+interface TTSProvider {
+    id: string;
+    name: string;
+    type: 'remote' | 'local';
+    voices: string[];
+}
+interface TTSProvidersResponse {
+    success: boolean;
+    providers: TTSProvider[];
+    default: string;
+    error?: string;
+}
 
 /**
  * Activities Module - HTTP Proxy to RealtimeX Main App
@@ -636,6 +654,49 @@ declare class LLMModule {
     search(query: string, options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
 }
 
+declare class TTSModule {
+    private baseUrl;
+    private appId;
+    private appName;
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
+    private get headers();
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Internal request wrapper that handles automatic permission prompts
+     */
+    private request;
+    /**
+     * Generate speech from text (returns full buffer)
+     *
+     * @example
+     * ```ts
+     * const buffer = await sdk.tts.speak("Hello world");
+     * // Play buffer...
+     * ```
+     */
+    speak(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
+    /**
+     * Generate speech from text (returns stream)
+     *
+     * @example
+     * ```ts
+     * const stream = await sdk.tts.speakStream("Hello world");
+     * for await (const chunk of stream) {
+     *   // Play chunk...
+     * }
+     * ```
+     */
+    speakStream(text: string, options?: TTSOptions): AsyncGenerator<Uint8Array>;
+    /**
+     * List available TTS providers
+     */
+    listProviders(): Promise<TTSProvider[]>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -650,6 +711,7 @@ declare class RealtimeXSDK {
     task: TaskModule;
     port: PortModule;
     llm: LLMModule;
+    tts: TTSModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -683,4 +745,4 @@ declare class RealtimeXSDK {
     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 };
+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, TTSModule, type TTSOptions, type TTSProvider, type TTSProvidersResponse, 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

@@ -39,6 +39,7 @@ __export(index_exports, {
   PermissionRequiredError: () => PermissionRequiredError,
   PortModule: () => PortModule,
   RealtimeXSDK: () => RealtimeXSDK,
+  TTSModule: () => TTSModule,
   TaskModule: () => TaskModule,
   VectorStore: () => VectorStore,
   WebhookModule: () => WebhookModule
@@ -980,6 +981,129 @@ var LLMModule = class {
   }
 };
 
+// src/modules/tts.ts
+var TTSModule = class {
+  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;
+  }
+  get headers() {
+    if (this.apiKey) {
+      return {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      };
+    }
+    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.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;
+    }
+  }
+  /**
+   * Internal request wrapper that handles automatic permission prompts
+   */
+  async request(method, endpoint, body, isStream = false) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      const data = await response.json();
+      if (data.code === "PERMISSION_REQUIRED") {
+        const permission = data.permission || "tts.speak";
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          return this.request(method, endpoint, body, isStream);
+        }
+        throw new PermissionDeniedError(permission);
+      }
+      throw new Error(data.error || `Request failed: ${response.status}`);
+    }
+    if (isStream) {
+      return response.body;
+    }
+    const contentType = response.headers.get("content-type");
+    if (contentType && contentType.includes("application/json")) {
+      return response.json();
+    }
+    return response.arrayBuffer();
+  }
+  /**
+   * Generate speech from text (returns full buffer)
+   * 
+   * @example
+   * ```ts
+   * const buffer = await sdk.tts.speak("Hello world");
+   * // Play buffer...
+   * ```
+   */
+  async speak(text, options = {}) {
+    return this.request("POST", "/sdk/tts", {
+      text,
+      ...options
+    });
+  }
+  /**
+   * Generate speech from text (returns stream)
+   * 
+   * @example
+   * ```ts
+   * const stream = await sdk.tts.speakStream("Hello world");
+   * for await (const chunk of stream) {
+   *   // Play chunk...
+   * }
+   * ```
+   */
+  async *speakStream(text, options = {}) {
+    const body = await this.request("POST", "/sdk/tts/stream", {
+      text,
+      ...options
+    }, true);
+    if (!body) throw new Error("No response body");
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield value;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * List available TTS providers
+   */
+  async listProviders() {
+    const data = await this.request("GET", "/sdk/tts/providers");
+    return data.providers || [];
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -997,6 +1121,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     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.appName, this.apiKey);
+    this.tts = new TTSModule(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);
@@ -1105,6 +1230,7 @@ var RealtimeXSDK = _RealtimeXSDK;
   PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
+  TTSModule,
   TaskModule,
   VectorStore,
   WebhookModule

package/dist/index.mjs

@@ -933,6 +933,129 @@ var LLMModule = class {
   }
 };
 
+// src/modules/tts.ts
+var TTSModule = class {
+  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;
+  }
+  get headers() {
+    if (this.apiKey) {
+      return {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      };
+    }
+    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.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;
+    }
+  }
+  /**
+   * Internal request wrapper that handles automatic permission prompts
+   */
+  async request(method, endpoint, body, isStream = false) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      const data = await response.json();
+      if (data.code === "PERMISSION_REQUIRED") {
+        const permission = data.permission || "tts.speak";
+        const granted = await this.requestPermission(permission);
+        if (granted) {
+          return this.request(method, endpoint, body, isStream);
+        }
+        throw new PermissionDeniedError(permission);
+      }
+      throw new Error(data.error || `Request failed: ${response.status}`);
+    }
+    if (isStream) {
+      return response.body;
+    }
+    const contentType = response.headers.get("content-type");
+    if (contentType && contentType.includes("application/json")) {
+      return response.json();
+    }
+    return response.arrayBuffer();
+  }
+  /**
+   * Generate speech from text (returns full buffer)
+   * 
+   * @example
+   * ```ts
+   * const buffer = await sdk.tts.speak("Hello world");
+   * // Play buffer...
+   * ```
+   */
+  async speak(text, options = {}) {
+    return this.request("POST", "/sdk/tts", {
+      text,
+      ...options
+    });
+  }
+  /**
+   * Generate speech from text (returns stream)
+   * 
+   * @example
+   * ```ts
+   * const stream = await sdk.tts.speakStream("Hello world");
+   * for await (const chunk of stream) {
+   *   // Play chunk...
+   * }
+   * ```
+   */
+  async *speakStream(text, options = {}) {
+    const body = await this.request("POST", "/sdk/tts/stream", {
+      text,
+      ...options
+    }, true);
+    if (!body) throw new Error("No response body");
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield value;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * List available TTS providers
+   */
+  async listProviders() {
+    const data = await this.request("GET", "/sdk/tts/providers");
+    return data.providers || [];
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -950,6 +1073,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     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.appName, this.apiKey);
+    this.tts = new TTSModule(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);
@@ -1057,6 +1181,7 @@ export {
   PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
+  TTSModule,
   TaskModule,
   VectorStore,
   WebhookModule

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.1.4",
+    "version": "1.2.0",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -40,4 +40,4 @@
     "engines": {
         "node": ">=18.0.0"
     }
-}
+}