@rimelabs/sdk 0.1.0-alpha.22 → 0.1.0-alpha.23

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.0-alpha.23](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.22...typescript-v0.1.0-alpha.23) (2026-10-27)
+
+
+### Bug Fixes
+
+* preserve Prism handshake error categories and diagnostics ([#110](https://github.com/rimelabs/rime-sdk/issues/110)) ([75568b2](https://github.com/rimelabs/rime-sdk/commit/75568b278afddd265a0a4f2c26c716ccb6b29514))
+
 ## [0.1.0-alpha.22](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.21...typescript-v0.1.0-alpha.22) (2026-10-24)
 
 

package/README.md

@@ -28,6 +28,12 @@ STT use the SDK and Node.js built-ins.
 
 ## Prism: send recorded speech
 
+If Prism refuses the connection with HTTP 429, `realtime.connect()` throws
+`RimeResourceLimitError`. HTTP 503 throws `RimeUnavailableError`. Handshake
+errors include the HTTP status, the server request ID when supplied, and a
+short server explanation when available. Missing or invalid error bodies use
+a default message. The SDK does not retry the connection automatically.
+
 With `RIME_API_KEY` set, the SDK connects to
 `wss://prism.api.rime.ai/v1/realtime` and uses the server's default voice.
 Pass `endpoint` or `voice` to select another deployment or voice.

package/dist/realtime/transport.d.ts

@@ -6,6 +6,8 @@ export declare class RealtimeConnection {
     private readonly ended;
     private closing;
     private connected;
+    private failed;
+    private refusal;
     readonly ready: Promise<void>;
     onMessage: (raw: string) => void;
     onFailure: (error: RimeError) => void;

package/dist/realtime/transport.js

@@ -1,6 +1,42 @@
 import WebSocket from "ws";
-import { RimeAuthenticationError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
+import { RimeAuthenticationError, RimeResourceLimitError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
 import { Deferred } from "./async.js";
+function handshakeError(status, body, requestId) {
+    let errorType = RimeUnavailableError;
+    let reason = "Realtime endpoint rejected the connection";
+    if ([401, 403].includes(status)) {
+        errorType = RimeAuthenticationError;
+        reason = "Realtime endpoint rejected credentials";
+    }
+    else if (status === 429) {
+        errorType = RimeResourceLimitError;
+        reason = "Realtime connection or rate limit reached";
+    }
+    else if (status === 503) {
+        reason = "Realtime endpoint is unavailable";
+    }
+    let message = `${reason} (HTTP ${status})`;
+    if (body.length > 0 && body.length < 1024) {
+        try {
+            let detail = new TextDecoder("utf-8", { fatal: true })
+                .decode(body)
+                .trim();
+            if (typeof detail === "string" && /^[{[]/.test(detail))
+                detail = JSON.parse(detail)?.error?.message;
+            if (typeof detail === "string" &&
+                !detail.trimStart().startsWith("<") &&
+                !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(detail)) {
+                detail = detail.trim().replace(/\s+/gu, " ");
+                if (detail)
+                    message += `: ${detail}`;
+            }
+        }
+        catch {
+            // Invalid response bodies do not change the HTTP error category.
+        }
+    }
+    return new errorType(message, requestId);
+}
 /** Private transport. The public declarations do not require ws types. */
 export class RealtimeConnection {
     socket;
@@ -8,6 +44,8 @@ export class RealtimeConnection {
     ended = new Deferred();
     closing = null;
     connected = false;
+    failed = false;
+    refusal;
     ready = this.opened.promise;
     onMessage = () => { };
     onFailure = () => { };
@@ -26,17 +64,39 @@ export class RealtimeConnection {
             this.opened.resolve();
         });
         this.socket.on("unexpected-response", (request, response) => {
-            const error = [401, 403].includes(response.statusCode ?? 0)
-                ? new RimeAuthenticationError("Realtime endpoint rejected credentials")
-                : new RimeUnavailableError("Realtime endpoint rejected the connection");
-            this.failure(error);
-            response.destroy();
-            request.destroy();
-            this.socket.terminate();
+            const chunks = [];
+            let size = 0;
+            let finished = false;
+            const finish = (complete = false) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                this.refusal = undefined;
+                const id = response.headers["x-request-id"];
+                this.failure(handshakeError(response.statusCode ?? 0, complete ? Buffer.concat(chunks) : Buffer.alloc(0), typeof id === "string" ? id : null));
+                response.destroy();
+                request.destroy();
+                this.socket.terminate();
+            };
+            const timer = setTimeout(finish, 1000);
+            this.refusal = finish;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size >= 1024)
+                    finish();
+                else
+                    chunks.push(chunk);
+            });
+            response.on("end", () => finish(true));
+            response.on("error", () => finish());
+            response.on("aborted", () => finish());
         });
-        this.socket.on("error", () => this.failure(!this.connected
-            ? new RimeUnavailableError("Realtime handshake failed")
-            : new RimeStreamError("Invalid event or lost realtime connection")));
+        this.socket.on("error", () => this.refusal
+            ? this.refusal()
+            : this.failure(!this.connected
+                ? new RimeUnavailableError("Realtime handshake failed")
+                : new RimeStreamError("Invalid event or lost realtime connection")));
         this.socket.on("message", (data, binary) => {
             if (binary) {
                 this.failure(new RimeStreamError("Expected a JSON text event"));
@@ -45,11 +105,15 @@ export class RealtimeConnection {
             this.onMessage(data.toString());
         });
         this.socket.on("close", () => {
+            this.refusal?.();
             this.ended.resolve();
             this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic"));
         });
     }
     failure(error) {
+        if (this.failed)
+            return;
+        this.failed = true;
         this.opened.reject(error);
         this.onFailure(error);
     }
@@ -66,6 +130,7 @@ export class RealtimeConnection {
     close() {
         if (!this.closing) {
             this.closing = (async () => {
+                this.refusal?.();
                 if (this.socket.readyState === WebSocket.CLOSED)
                     return;
                 const timer = setTimeout(() => this.socket.terminate(), 2000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelabs/sdk",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.23",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",