@rimelabs/sdk 0.1.0-alpha.25 → 0.1.0-alpha.26

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.0-alpha.26](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.25...typescript-v0.1.0-alpha.26) (2026-10-30)
+
+
+### Features
+
+* expose realtime connection diagnostics across SDKs ([#116](https://github.com/rimelabs/rime-sdk/issues/116)) ([da50cf4](https://github.com/rimelabs/rime-sdk/commit/da50cf41b0ca4631c0c71e48ef31cd207ab5e713))
+
 ## [0.1.0-alpha.25](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.24...typescript-v0.1.0-alpha.25) (2026-10-28)
 
 

package/dist/errors.d.ts

@@ -1,6 +1,18 @@
+/** Optional connection diagnostics. These fields do not initiate retries. */
+export interface RimeErrorOptions extends ErrorOptions {
+    /** Refused HTTP upgrade status, such as 503; null when unavailable. */
+    statusCode?: number | null;
+    /** Received WebSocket close code, such as 1013; null when unavailable. */
+    closeCode?: number | null;
+    /** Server-requested delay in seconds. Zero is valid; null means unavailable. */
+    retryAfterSeconds?: number | null;
+}
 export declare class RimeError extends Error {
     readonly requestId: string | null;
-    constructor(message: string, requestId?: string | null, options?: ErrorOptions);
+    readonly statusCode: number | null;
+    readonly closeCode: number | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, requestId?: string | null, options?: RimeErrorOptions);
 }
 export declare class RimeAuthenticationError extends RimeError {
 }

package/dist/errors.js

@@ -1,9 +1,15 @@
 export class RimeError extends Error {
     requestId;
+    statusCode;
+    closeCode;
+    retryAfterSeconds;
     constructor(message, requestId = null, options) {
         super(message, options);
         this.name = new.target.name;
         this.requestId = requestId;
+        this.statusCode = options?.statusCode ?? null;
+        this.closeCode = options?.closeCode ?? null;
+        this.retryAfterSeconds = options?.retryAfterSeconds ?? null;
     }
 }
 export class RimeAuthenticationError extends RimeError {

package/dist/realtime/transport.js

@@ -1,7 +1,83 @@
 import WebSocket from "ws";
 import { RimeAuthenticationError, RimeResourceLimitError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
 import { Deferred } from "./async.js";
-function handshakeError(status, body, requestId) {
+const months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+const dayName = "(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)";
+const monthName = `(?:${months.join("|")})`;
+const clock = "([0-9]{2}):([0-9]{2}):([0-9]{2})";
+const imfDate = new RegExp(`^${dayName}, ([0-9]{2}) (${monthName}) ([0-9]{4}) ${clock} GMT$`);
+const rfc850Date = new RegExp(`^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), ([0-9]{2})-(${monthName})-([0-9]{2}) ${clock} GMT$`);
+const asctimeDate = new RegExp(`^${dayName} (${monthName}) ([0-9]{2}| [0-9]) ${clock} ([0-9]{4})$`);
+function httpDate(value, now) {
+    let parts = imfDate.exec(value);
+    let shortYear = false;
+    if (!parts) {
+        parts = rfc850Date.exec(value);
+        shortYear = parts !== null;
+    }
+    if (!parts) {
+        const legacy = asctimeDate.exec(value);
+        if (!legacy)
+            return null;
+        parts = [
+            legacy[0],
+            legacy[2],
+            legacy[1],
+            legacy[6],
+            legacy[3],
+            legacy[4],
+            legacy[5],
+        ];
+    }
+    const day = Number(parts[1]);
+    const month = months.indexOf(parts[2]);
+    let year = Number(parts[3]);
+    const hour = Number(parts[4]);
+    const minute = Number(parts[5]);
+    const second = Number(parts[6]);
+    if (shortYear) {
+        const current = new Date(now);
+        const limit = [
+            current.getUTCFullYear() + 50,
+            current.getUTCMonth(),
+            current.getUTCDate(),
+            current.getUTCHours(),
+            current.getUTCMinutes(),
+            current.getUTCSeconds(),
+        ];
+        year += Math.floor(limit[0] / 100) * 100;
+        const candidate = [year, month, day, hour, minute, second];
+        const difference = candidate.findIndex((part, index) => part !== limit[index]);
+        if (difference !== -1 && candidate[difference] > limit[difference])
+            year -= 100;
+    }
+    // Use setters so years 0000–0099 aren't silently changed to 1900–1999.
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    date.setUTCHours(hour, minute, second, 0);
+    if (year < 1 ||
+        date.getUTCFullYear() !== year ||
+        date.getUTCMonth() !== month ||
+        date.getUTCDate() !== day ||
+        date.getUTCHours() !== hour ||
+        date.getUTCMinutes() !== minute ||
+        date.getUTCSeconds() !== second)
+        return null;
+    return date.getTime();
+}
+function retryAfter(values) {
+    if (values?.length !== 1 || values[0].length > 256)
+        return null;
+    const value = values[0].trim();
+    if (/^[0-9]+$/.test(value)) {
+        const seconds = Number(value);
+        return Number.isFinite(seconds) ? seconds : null;
+    }
+    const now = Date.now();
+    const date = httpDate(value, now);
+    return date === null ? null : Math.max(0, (date - now) / 1000);
+}
+function handshakeError(status, body, requestId, retryAfterSeconds) {
     let errorType = RimeUnavailableError;
     let reason = "Realtime endpoint rejected the connection";
     if ([401, 403].includes(status)) {
@@ -35,7 +111,10 @@ function handshakeError(status, body, requestId) {
             // Invalid response bodies do not change the HTTP error category.
         }
     }
-    return new errorType(message, requestId);
+    return new errorType(message, requestId, {
+        statusCode: status,
+        retryAfterSeconds,
+    });
 }
 /** Private transport. The public declarations do not require ws types. */
 export class RealtimeConnection {
@@ -74,7 +153,7 @@ export class RealtimeConnection {
                 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));
+                this.failure(handshakeError(response.statusCode ?? 0, complete ? Buffer.concat(chunks) : Buffer.alloc(0), typeof id === "string" ? id : null, retryAfter(response.headersDistinct["retry-after"])));
                 response.destroy();
                 request.destroy();
                 this.socket.terminate();
@@ -104,10 +183,10 @@ export class RealtimeConnection {
             }
             this.onMessage(data.toString());
         });
-        this.socket.on("close", () => {
+        this.socket.on("close", (code) => {
             this.refusal?.();
             this.ended.resolve();
-            this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic"));
+            this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic", null, { closeCode: code === 1005 || code === 1006 ? null : code }));
         });
     }
     failure(error) {

package/docs/realtime.md

@@ -452,6 +452,20 @@ The voice examples report actual playback.
 
 ## Timeouts and failures
 
+`RimeError` exposes `statusCode` for a refused HTTP upgrade, `closeCode` for a
+received WebSocket close code, and `retryAfterSeconds` for the server's requested
+delay. For example, a busy endpoint can return `statusCode=503` and
+`retryAfterSeconds=2`. Missing values are `null`; zero is a valid delay. The
+existing `requestId` retains the server's request ID on an HTTP refusal.
+Invalid or duplicate `Retry-After` headers are ignored. HTTP dates become a delay
+relative to the client clock, with past dates becoming zero.
+
+Error categories stay the same. A WebSocket closure uses `RimeStreamError`;
+no received close code means `closeCode=null`, including a lost connection or
+an empty close frame. These fields require a release with structured connection
+diagnostics. The SDK does not retry startup automatically. These fields do not
+make replay of an accepted request safe.
+
 Configure positive, finite seconds through `timeouts`. `connectS` bounds the
 WebSocket handshake and initial session event. `readyS` bounds turn admission,
 tool readiness, and waiting for generation to end before a playback report.

package/package.json

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