realtime-avatar 0.7.2 → 0.7.3

package/dist/{chunk-ARILC2U3.js → chunk-2V333KRZ.js}

@@ -43,7 +43,7 @@ function isTransient(cause) {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.7.2";
+var SDK_VERSION = "0.7.3";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;

package/dist/{chunk-MQQKAUOB.js → chunk-OMOEUVO5.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-ARILC2U3.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-2V333KRZ.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-MQQKAUOB.js';
-import './chunk-ARILC2U3.js';
+import { createProxyHandler } from './chunk-OMOEUVO5.js';
+import './chunk-2V333KRZ.js';
 
 // ../proxy/src/express.ts
 function realtimeAvatarExpress(config) {

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-MQQKAUOB.js';
-import './chunk-ARILC2U3.js';
+import { createProxyHandler } from './chunk-OMOEUVO5.js';
+import './chunk-2V333KRZ.js';
 
 // ../proxy/src/hono.ts
 function realtimeAvatarHono(config) {

package/dist/index.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript } from './chunk-ARILC2U3.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript } from './chunk-2V333KRZ.js';

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-MQQKAUOB.js';
-import './chunk-ARILC2U3.js';
+import { createProxyHandler } from './chunk-OMOEUVO5.js';
+import './chunk-2V333KRZ.js';
 
 // ../proxy/src/nextjs.ts
 function createRealtimeAvatarRoute(config) {

package/dist/react-native.js

@@ -131,6 +131,43 @@ function timeoutSetter(fn, ms) {
 }
 
 // ../client/src/errors.ts
+var RealtimeAvatarApiError = class _RealtimeAvatarApiError extends Error {
+  constructor(message, status, body, response, metadata = {}) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.response = response;
+    this.name = "RealtimeAvatarApiError";
+    this.code = metadata.code;
+    this.retryable = metadata.retryable;
+    this.billingUrl = metadata.billingUrl;
+    this.rawMessage = metadata.rawMessage ?? null;
+  }
+  status;
+  body;
+  response;
+  code;
+  retryable;
+  billingUrl;
+  /** Debug detail returned by the API. Do not render directly in user-facing UI. */
+  rawMessage;
+  get isBillingRequired() {
+    return this.status === 402 || this.code === "insufficient_credits" || this.code === "spend_limit_exceeded";
+  }
+  static async fromResponse(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    const body = contentType.includes("application/json") ? await response.clone().json().catch(() => null) : await response.clone().text().catch(() => "");
+    const rawMessage = (extractErrorMessage(body) ?? response.statusText) || null;
+    const metadata = extractErrorMetadata(body, response.status, rawMessage);
+    return new _RealtimeAvatarApiError(
+      metadata.message,
+      response.status,
+      body,
+      response,
+      metadata
+    );
+  }
+};
 var RealtimeAvatarCapacityError = class extends Error {
   constructor(message, busy) {
     super(message);
@@ -151,6 +188,107 @@ var RealtimeAvatarCapacityError = class extends Error {
     return this.busy.recommended_retry_ms;
   }
 };
+function extractErrorMessage(body) {
+  if (!body || typeof body !== "object") return typeof body === "string" && body ? body : null;
+  const record = body;
+  const detail = readMessageValue(record.detail);
+  if (detail) return detail;
+  const error = readMessageValue(record.error);
+  if (error) return error;
+  const message = readMessageValue(record.message);
+  if (message) return message;
+  return null;
+}
+function normalizeRealtimeAvatarError(input) {
+  const status = input.status ?? 0;
+  const rawCode = input.code?.trim() || null;
+  const rawMessage = input.message?.trim() || "";
+  const blob = `${rawCode ?? ""} ${rawMessage}`.toLowerCase();
+  if (rawCode === "insufficient_credits" || rawCode === "spend_limit_exceeded" || status === 402) {
+    return {
+      code: rawCode ?? "billing_required",
+      message: rawMessage && !hasInternalDetail(rawMessage) ? rawMessage : "Add credits to continue using realtime avatars.",
+      retryable: false
+    };
+  }
+  if (status === 401) {
+    return { code: "unauthorized", message: "Authentication is required to use Realtime Avatar.", retryable: false };
+  }
+  if (status === 403) {
+    return { code: "forbidden", message: "This API key does not have access to that action.", retryable: false };
+  }
+  if (status === 404 || blob.includes("unknown avatar_id") || blob.includes("avatar not found")) {
+    return { code: "not_found", message: "We could not find that avatar or resource.", retryable: false };
+  }
+  if (status === 409) {
+    return { code: "conflict", message: "That request is already in progress. Try again in a moment.", retryable: true };
+  }
+  if (status === 429) {
+    return { code: "rate_limited", message: "Too many realtime requests. Please slow down and retry.", retryable: true };
+  }
+  if (isWarmingMessage(blob)) {
+    return { code: "service_unavailable", message: "Realtime Avatar is warming up. Try again in a moment.", retryable: true };
+  }
+  if (status === 400 || status === 422) {
+    return { code: "invalid_request", message: userSafeMessage(rawMessage) ?? "Check the request and try again.", retryable: false };
+  }
+  if (status >= 500) {
+    return { code: "service_unavailable", message: "Realtime Avatar is temporarily unavailable. Try again in a moment.", retryable: true };
+  }
+  return {
+    code: isPublicErrorCode(rawCode) ? rawCode : "request_failed",
+    message: userSafeMessage(rawMessage) ?? "Realtime Avatar request failed. Try again.",
+    retryable: status === 0 || status >= 500
+  };
+}
+function extractErrorMetadata(body, status, rawMessage) {
+  if (!body || typeof body !== "object") {
+    const normalized2 = normalizeRealtimeAvatarError({ status, message: rawMessage });
+    return { ...normalized2, rawMessage };
+  }
+  const record = body;
+  const code = typeof record.code === "string" ? record.code : null;
+  const normalized = normalizeRealtimeAvatarError({ status, code, message: rawMessage });
+  return {
+    code: normalized.code,
+    retryable: typeof record.retryable === "boolean" ? record.retryable : normalized.retryable,
+    ...typeof record.billingUrl === "string" ? { billingUrl: record.billingUrl } : {},
+    rawMessage,
+    message: normalized.message
+  };
+}
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "billing_required",
+  "invalid_request",
+  "unauthorized",
+  "forbidden",
+  "not_found",
+  "conflict",
+  "rate_limited",
+  "service_unavailable",
+  "request_failed",
+  "network_error"
+]);
+function isPublicErrorCode(code) {
+  return Boolean(code && PUBLIC_ERROR_CODES.has(code));
+}
+function readMessageValue(value) {
+  if (typeof value === "string") return value.trim() || null;
+  if (!value || typeof value !== "object") return null;
+  const record = value;
+  return readMessageValue(record.message) ?? readMessageValue(record.error) ?? readMessageValue(record.detail);
+}
+function userSafeMessage(message) {
+  if (!message || hasInternalDetail(message)) return null;
+  return message.length > 180 ? `${message.slice(0, 177)}...` : message;
+}
+function isWarmingMessage(blob) {
+  return blob.includes("warming") || blob.includes("not ready") || blob.includes("starting up");
+}
+var MACHINE_SHAPED = /[_=<>{}\[\]|\\$`]|\w+\.\w+\.\w|\S:\d|\w\(\)|^\s*(?:at|File)\b/mu;
+function hasInternalDetail(message) {
+  return MACHINE_SHAPED.test(message);
+}
 function splitCallTranscript(all, localIdentity) {
   if (!localIdentity) return { user: [], agent: all };
   const user = [];
@@ -2390,8 +2528,7 @@ function createProxyClient(options) {
         return { status: "busy", busy };
       }
       if (!response.ok) {
-        const detail = await response.text().catch(() => "");
-        throw new Error(`realtime-avatar: proxy refused the call (${response.status}) ${detail}`.trim());
+        throw await RealtimeAvatarApiError.fromResponse(response);
       }
       return { status: "ready", grant: await response.json() };
     },

package/dist/react.js

@@ -90,6 +90,43 @@ function timeoutSetter(fn, ms) {
 }
 
 // ../client/src/errors.ts
+var RealtimeAvatarApiError = class _RealtimeAvatarApiError extends Error {
+  constructor(message, status, body, response, metadata = {}) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.response = response;
+    this.name = "RealtimeAvatarApiError";
+    this.code = metadata.code;
+    this.retryable = metadata.retryable;
+    this.billingUrl = metadata.billingUrl;
+    this.rawMessage = metadata.rawMessage ?? null;
+  }
+  status;
+  body;
+  response;
+  code;
+  retryable;
+  billingUrl;
+  /** Debug detail returned by the API. Do not render directly in user-facing UI. */
+  rawMessage;
+  get isBillingRequired() {
+    return this.status === 402 || this.code === "insufficient_credits" || this.code === "spend_limit_exceeded";
+  }
+  static async fromResponse(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    const body = contentType.includes("application/json") ? await response.clone().json().catch(() => null) : await response.clone().text().catch(() => "");
+    const rawMessage = (extractErrorMessage(body) ?? response.statusText) || null;
+    const metadata = extractErrorMetadata(body, response.status, rawMessage);
+    return new _RealtimeAvatarApiError(
+      metadata.message,
+      response.status,
+      body,
+      response,
+      metadata
+    );
+  }
+};
 var RealtimeAvatarCapacityError = class extends Error {
   constructor(message, busy) {
     super(message);
@@ -110,6 +147,107 @@ var RealtimeAvatarCapacityError = class extends Error {
     return this.busy.recommended_retry_ms;
   }
 };
+function extractErrorMessage(body) {
+  if (!body || typeof body !== "object") return typeof body === "string" && body ? body : null;
+  const record = body;
+  const detail = readMessageValue(record.detail);
+  if (detail) return detail;
+  const error = readMessageValue(record.error);
+  if (error) return error;
+  const message = readMessageValue(record.message);
+  if (message) return message;
+  return null;
+}
+function normalizeRealtimeAvatarError(input) {
+  const status = input.status ?? 0;
+  const rawCode = input.code?.trim() || null;
+  const rawMessage = input.message?.trim() || "";
+  const blob = `${rawCode ?? ""} ${rawMessage}`.toLowerCase();
+  if (rawCode === "insufficient_credits" || rawCode === "spend_limit_exceeded" || status === 402) {
+    return {
+      code: rawCode ?? "billing_required",
+      message: rawMessage && !hasInternalDetail(rawMessage) ? rawMessage : "Add credits to continue using realtime avatars.",
+      retryable: false
+    };
+  }
+  if (status === 401) {
+    return { code: "unauthorized", message: "Authentication is required to use Realtime Avatar.", retryable: false };
+  }
+  if (status === 403) {
+    return { code: "forbidden", message: "This API key does not have access to that action.", retryable: false };
+  }
+  if (status === 404 || blob.includes("unknown avatar_id") || blob.includes("avatar not found")) {
+    return { code: "not_found", message: "We could not find that avatar or resource.", retryable: false };
+  }
+  if (status === 409) {
+    return { code: "conflict", message: "That request is already in progress. Try again in a moment.", retryable: true };
+  }
+  if (status === 429) {
+    return { code: "rate_limited", message: "Too many realtime requests. Please slow down and retry.", retryable: true };
+  }
+  if (isWarmingMessage(blob)) {
+    return { code: "service_unavailable", message: "Realtime Avatar is warming up. Try again in a moment.", retryable: true };
+  }
+  if (status === 400 || status === 422) {
+    return { code: "invalid_request", message: userSafeMessage(rawMessage) ?? "Check the request and try again.", retryable: false };
+  }
+  if (status >= 500) {
+    return { code: "service_unavailable", message: "Realtime Avatar is temporarily unavailable. Try again in a moment.", retryable: true };
+  }
+  return {
+    code: isPublicErrorCode(rawCode) ? rawCode : "request_failed",
+    message: userSafeMessage(rawMessage) ?? "Realtime Avatar request failed. Try again.",
+    retryable: status === 0 || status >= 500
+  };
+}
+function extractErrorMetadata(body, status, rawMessage) {
+  if (!body || typeof body !== "object") {
+    const normalized2 = normalizeRealtimeAvatarError({ status, message: rawMessage });
+    return { ...normalized2, rawMessage };
+  }
+  const record = body;
+  const code = typeof record.code === "string" ? record.code : null;
+  const normalized = normalizeRealtimeAvatarError({ status, code, message: rawMessage });
+  return {
+    code: normalized.code,
+    retryable: typeof record.retryable === "boolean" ? record.retryable : normalized.retryable,
+    ...typeof record.billingUrl === "string" ? { billingUrl: record.billingUrl } : {},
+    rawMessage,
+    message: normalized.message
+  };
+}
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "billing_required",
+  "invalid_request",
+  "unauthorized",
+  "forbidden",
+  "not_found",
+  "conflict",
+  "rate_limited",
+  "service_unavailable",
+  "request_failed",
+  "network_error"
+]);
+function isPublicErrorCode(code) {
+  return Boolean(code && PUBLIC_ERROR_CODES.has(code));
+}
+function readMessageValue(value) {
+  if (typeof value === "string") return value.trim() || null;
+  if (!value || typeof value !== "object") return null;
+  const record = value;
+  return readMessageValue(record.message) ?? readMessageValue(record.error) ?? readMessageValue(record.detail);
+}
+function userSafeMessage(message) {
+  if (!message || hasInternalDetail(message)) return null;
+  return message.length > 180 ? `${message.slice(0, 177)}...` : message;
+}
+function isWarmingMessage(blob) {
+  return blob.includes("warming") || blob.includes("not ready") || blob.includes("starting up");
+}
+var MACHINE_SHAPED = /[_=<>{}\[\]|\\$`]|\w+\.\w+\.\w|\S:\d|\w\(\)|^\s*(?:at|File)\b/mu;
+function hasInternalDetail(message) {
+  return MACHINE_SHAPED.test(message);
+}
 function splitCallTranscript(all, localIdentity) {
   if (!localIdentity) return { user: [], agent: all };
   const user = [];
@@ -2695,8 +2833,7 @@ function createProxyClient(options) {
         return { status: "busy", busy };
       }
       if (!response.ok) {
-        const detail = await response.text().catch(() => "");
-        throw new Error(`realtime-avatar: proxy refused the call (${response.status}) ${detail}`.trim());
+        throw await RealtimeAvatarApiError.fromResponse(response);
       }
       return { status: "ready", grant: await response.json() };
     },

package/dist/server.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript } from './chunk-ARILC2U3.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript } from './chunk-2V333KRZ.js';

package/dist/tanstack-start.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-MQQKAUOB.js';
-import './chunk-ARILC2U3.js';
+import { createProxyHandler } from './chunk-OMOEUVO5.js';
+import './chunk-2V333KRZ.js';
 
 // src/tanstack-start.ts
 function realtimeAvatarServerRoute(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",