@runappsai/sdk 0.7.0 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runappsai/sdk",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "JavaScript / TypeScript client for the RunApps AI Gateway",
   "license": "MIT",
   "author": "RunApps",

package/src/audio.ts

@@ -90,7 +90,10 @@ export interface TranscribeParams {
    */
   url?: string;
   language?: string;
-  prompt?: string;
+
+  /** A vocabulary hint for the model, as text or a private prompt
+   *  `{ id, vars }` (or a list; see `PromptInput`). */
+  prompt?: string | PromptInput;
   response_format?: string;
   timestamp_granularities?: ("segment" | "word")[];
   user?: string;
@@ -406,7 +409,7 @@ function buildTranscribeForm(model: string, params: TranscribeParams): FormData
   const form = new FormData();
   form.set("model", model);
   if (params.language) form.set("language", params.language);
-  if (params.prompt) form.set("prompt", params.prompt);
+  if (params.prompt) form.set("prompt", typeof params.prompt === "string" ? params.prompt : JSON.stringify(params.prompt));
   if (params.response_format) form.set("response_format", params.response_format);
   if (params.timestamp_granularities) {
     for (const g of params.timestamp_granularities) {

package/src/realtime.ts

@@ -30,6 +30,15 @@ import type { Transport } from "./transport.js";
  * Audio input must arrive at real-time pace (send ~20 ms chunks as they
  * are captured); the model also expects a steady stream, so keep sending
  * silence — or `mute()` — while the microphone is off.
+ *
+ * Transcription models (e.g. "Doubao ASR 2.0 Streaming") use the same
+ * session for live speech-to-text: `session.created` carries
+ * `session.mode: "transcription"`, `session.hotwords` (array or
+ * comma-separated string) favours words, and only the
+ * `…input_audio_transcription.started / .delta / .completed` events come
+ * back — `.delta` holds the sentence so far, `.completed` a finished
+ * sentence with `start_ms` / `end_ms`. `commitAudio()` or `close()` ends
+ * the audio; the last sentence settles before the session closes.
  */
 
 /** One protocol event. `type` names it; the rest depends on the event. */
@@ -50,8 +59,9 @@ export interface RealtimeUsage {
 
 /** How a session ended. */
 export interface RealtimeCloseInfo {
-  /** WebSocket close code: 1000 when the session completed; 4000+N for an
-   *  upstream HTTP error N (e.g. 4429); 4408 idle or over-long session. */
+  /** WebSocket close code: 1000 when the session completed; 4402 when the
+   *  spending cap was reached (`maxCost`, or the account's balance); 4000+N
+   *  for an upstream HTTP error N (e.g. 4429); 4408 idle or over-long session. */
   code: number;
   reason: string;
   /** Null when the session ended before the cost could be reported. */
@@ -69,7 +79,8 @@ export interface WebSocketLike {
 export type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
 
 export interface RealtimeConnectOptions {
-  /** Realtime model name (e.g. "Doubao Realtime Voice"); omit for the platform default. */
+  /** Realtime model name (e.g. "Doubao Realtime Voice", or "Doubao ASR 2.0
+   *  Streaming" for live speech-to-text); omit for the platform default. */
   model?: string;
   /**
    * Session settings sent in the opening `session.create`, e.g.
@@ -78,6 +89,12 @@ export interface RealtimeConnectOptions {
   session?: Record<string, unknown>;
   /** Model-specific extension block (Doubao: `{ asr, tts, dialog }`). */
   extension?: Record<string, unknown>;
+  /**
+   * End the session (close code 4402) once it has cost this many USD. The
+   * account's remaining balance always caps a session; this sets a lower
+   * cap. Checked after each turn, so the last turn may go slightly over.
+   */
+  maxCost?: number;
   /** Extra query parameters for the handshake. */
   query?: Record<string, string>;
   /**
@@ -174,7 +191,9 @@ export class RealtimeSession {
     this.send({ type: "input_audio_buffer.append", audio: bytesToBase64(asBytes(pcm16)) });
   }
 
-  /** Tell the model the user has finished speaking (skips end-of-speech detection). */
+  /** Tell the model the user has finished speaking (skips end-of-speech
+   *  detection). For a transcription model this ends the audio: the last
+   *  sentence settles, then the session closes. */
   commitAudio(): void {
     this.send({ type: "input_audio_buffer.commit" });
   }
@@ -336,7 +355,10 @@ export class RealtimeService {
           ws.send(JSON.stringify(openingEvent(options)));
         });
         void session.closed.then((info) => {
-          fail(new Error(`runapps: realtime connection closed (${info.code}${info.reason ? " " + info.reason : ""})`));
+          // A refused handshake (bad key, unknown model, low balance) reaches
+          // a WebSocket client only as 1006 — the HTTP status is hidden.
+          const hint = info.code === 1006 ? " — check the API key, the model name and the account balance" : "";
+          fail(new Error(`runapps: realtime connection closed (${info.code}${info.reason ? " " + info.reason : ""})${hint}`));
         });
       });
     } catch (err) {
@@ -380,6 +402,7 @@ function realtimeURL(baseURL: string, options: RealtimeConnectOptions): string {
   u.protocol = u.protocol === "http:" ? "ws:" : "wss:";
   for (const [k, v] of Object.entries(options.query ?? {})) u.searchParams.set(k, v);
   if (options.model) u.searchParams.set("model", options.model);
+  if (options.maxCost !== undefined && options.maxCost > 0) u.searchParams.set("max_cost", String(options.maxCost));
   return u.toString();
 }