@space3-npm/cybersoul-client 1.4.9 → 1.4.12

package/dist/client.js

@@ -1,6 +1,7 @@
 import { InteractRequestType, } from "./types.js";
 import { robustJsonParse } from "./utils/json.utils.js";
 import { GenericLLMProvider } from "./llm.provider.js";
+import { CyberSoulApiError, CyberSoulAuthError, CyberSoulError, CyberSoulInsufficientPointsError, CyberSoulNetworkError, CyberSoulTimeoutError, CyberSoulWalletError, } from "./errors.js";
 export class CyberSoulClient {
     config;
     llm;
@@ -47,10 +48,12 @@ export class CyberSoulClient {
             }
             catch (error) {
                 if (error instanceof Error && error.name === "AbortError") {
-                    lastError = new Error(`Request timed out after ${this.requestTimeoutMs}ms: ${method} ${endpoint}`);
+                    lastError = new CyberSoulTimeoutError(endpoint, method, this.requestTimeoutMs);
                 }
                 else {
-                    lastError = error;
+                    lastError = new CyberSoulNetworkError(endpoint, method, error instanceof Error
+                        ? `Network request failed: ${method} ${endpoint}: ${error.message}`
+                        : `Network request failed: ${method} ${endpoint}`, { cause: error });
                 }
                 if (attempt >= retryLimit) {
                     throw lastError;
@@ -60,14 +63,34 @@ export class CyberSoulClient {
                 clearTimeout(timeout);
             }
         }
+        // Defensive: the loop above either returns a Response, throws the
+        // wrapped network error, or continues to the next attempt. Reaching
+        // this point means the retry budget was exhausted without ever
+        // populating `lastError` (logically unreachable, but TypeScript
+        // cannot prove that).
         throw lastError instanceof Error
             ? lastError
-            : new Error("Request failed unexpectedly");
+            : new CyberSoulNetworkError(endpoint, method, `Request failed unexpectedly: ${method} ${endpoint}`);
     }
     async fetchRemoteState() {
-        const res = await this.apiFetch("/api/v1/cyber-soul/state");
-        if (!res.ok)
-            throw new Error("Failed to fetch character state");
+        const endpoint = "/api/v1/cyber-soul/state";
+        const res = await this.apiFetch(endpoint);
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = undefined;
+            }
+            const detail = (body && typeof body === "object" && "error" in body
+                ? String(body.error)
+                : undefined) ?? `HTTP ${res.status}`;
+            if (res.status === 401 || res.status === 403) {
+                throw new CyberSoulAuthError(endpoint, "GET", res.status, `Character credential rejected by backend (${detail}). The character may have been deleted.`, body);
+            }
+            throw new CyberSoulApiError(endpoint, "GET", res.status, `Failed to fetch character state: ${detail}`, body);
+        }
         const json = await res.json();
         return json.data;
     }
@@ -99,7 +122,8 @@ export class CyberSoulClient {
         return availableOutfits;
     }
     async generatePrimitive(type, payload) {
-        const res = await this.apiFetch(`/api/v1/cyber-soul/${type}/generate`, {
+        const endpoint = `/api/v1/cyber-soul/${type}/generate`;
+        const res = await this.apiFetch(endpoint, {
             method: "POST",
             body: JSON.stringify(payload),
         });
@@ -110,9 +134,23 @@ export class CyberSoulClient {
             }
             catch (e) { }
             const msg = errData?.message || errData?.error || `Status ${res.status}`;
-            const err = new Error(`Failed to generate ${type}: ${msg}`);
-            err.code = errData?.code || "UNKNOWN_ERROR";
-            throw err;
+            const code = errData?.code || "UNKNOWN_ERROR";
+            const detailedMessage = `Failed to generate ${type}: ${msg}`;
+            if (res.status === 402 || code === "INSUFFICIENT_POINTS") {
+                throw new CyberSoulInsufficientPointsError(endpoint, "POST", res.status, detailedMessage, errData, code);
+            }
+            if (code === "WALLET_DEDUCTION_ERROR") {
+                throw new CyberSoulWalletError(endpoint, "POST", res.status, detailedMessage, errData, code);
+            }
+            if (res.status === 401 || res.status === 403) {
+                throw new CyberSoulAuthError(endpoint, "POST", res.status, detailedMessage, errData);
+            }
+            const apiErr = new CyberSoulApiError(endpoint, "POST", res.status, detailedMessage, errData);
+            // Preserve the legacy duck-typed `code` field so existing callers
+            // that branch on `e.code` (including this SDK's own `interact()`
+            // mediaTasks catch block) keep working unchanged.
+            apiErr.code = code;
+            throw apiErr;
         }
         return res.json();
     }
@@ -764,6 +802,14 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             };
         }
         catch (error) {
+            // Typed SDK errors (insufficient points, wallet failure, auth, etc.)
+            // are part of the public contract — let callers branch on
+            // `instanceof` instead of string-sniffing a generic status:"error"
+            // envelope. Only truly-unexpected throws fall back to the legacy
+            // envelope so we don't break callers that don't yet handle throws.
+            if (error instanceof CyberSoulError) {
+                throw error;
+            }
             console.error("[CyberSoulClient] Interface Error: ", error);
             return {
                 status: "error",
@@ -1016,6 +1062,10 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
             };
         }
         catch (error) {
+            // Mirror `interact()`: preserve typed SDK errors for the caller.
+            if (error instanceof CyberSoulError) {
+                throw error;
+            }
             console.error("[CyberSoulClient] Proactive Interact Error: ", error);
             return { status: "error", error: error.message };
         }

package/dist/errors.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed error hierarchy thrown by the CyberSoul SDK.
+ *
+ * Consumers should branch on `instanceof` rather than parsing error
+ * messages — message strings are not a stable API.
+ */
+export declare class CyberSoulError extends Error {
+    /** Stable discriminator usable in serialized logs / event payloads. */
+    readonly kind: string;
+    constructor(kind: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The underlying fetch call never produced a response (DNS failure,
+ * connection refused, TLS error, offline, etc.). The remote service may
+ * or may not have processed the request; callers should treat this as a
+ * transient failure and retry later when connectivity is restored.
+ */
+export declare class CyberSoulNetworkError extends CyberSoulError {
+    readonly endpoint: string;
+    readonly method: string;
+    constructor(endpoint: string, method: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The request was aborted because it exceeded the configured
+ * `requestTimeoutMs`. A specialization of network error — callers that
+ * want to distinguish "no connection" from "slow connection" can use
+ * `instanceof CyberSoulTimeoutError`.
+ */
+export declare class CyberSoulTimeoutError extends CyberSoulNetworkError {
+    readonly timeoutMs: number;
+    constructor(endpoint: string, method: string, timeoutMs: number);
+}
+/**
+ * The backend returned a non-2xx HTTP response. Callers can inspect
+ * `status` to decide how to react (e.g. surface a user-facing message
+ * for 4xx vs. retry on 5xx).
+ */
+export declare class CyberSoulApiError extends CyberSoulError {
+    readonly status: number;
+    readonly endpoint: string;
+    readonly method: string;
+    /** Parsed JSON body when available, otherwise `undefined`. */
+    readonly body?: unknown;
+    constructor(endpoint: string, method: string, status: number, message: string, body?: unknown, kind?: string);
+}
+/**
+ * The backend rejected the SDK's character credential (HTTP 401/403 on
+ * a character-scoped endpoint). The most common cause is that the
+ * character profile bound to this `characterKey` has been deleted on
+ * the backend; the binding is effectively terminal for this client.
+ */
+export declare class CyberSoulAuthError extends CyberSoulApiError {
+    constructor(endpoint: string, method: string, status: number, message: string, body?: unknown);
+}
+/**
+ * The backend rejected a paid action because the user's wallet does
+ * not have enough points to cover it (HTTP 402 / `INSUFFICIENT_POINTS`).
+ * Callers should surface a top-up prompt rather than retrying.
+ */
+export declare class CyberSoulInsufficientPointsError extends CyberSoulApiError {
+    /**
+     * Backend-supplied machine code. Always `"INSUFFICIENT_POINTS"` today;
+     * kept as a field so future variants (e.g. per-feature paywalls) can
+     * piggy-back on the same class.
+     */
+    readonly code: string;
+    constructor(endpoint: string, method: string, status: number, message: string, body?: unknown, code?: string);
+}
+/**
+ * The wallet-deduction call failed for a reason *other than* insufficient
+ * balance (e.g. wallet service unavailable, accounting bug). Distinct from
+ * `CyberSoulInsufficientPointsError` because the user can't fix this by
+ * topping up — it's an upstream infrastructure issue.
+ */
+export declare class CyberSoulWalletError extends CyberSoulApiError {
+    readonly code: string;
+    constructor(endpoint: string, method: string, status: number, message: string, body?: unknown, code?: string);
+}

package/dist/errors.js

@@ -0,0 +1,110 @@
+/**
+ * Typed error hierarchy thrown by the CyberSoul SDK.
+ *
+ * Consumers should branch on `instanceof` rather than parsing error
+ * messages — message strings are not a stable API.
+ */
+export class CyberSoulError extends Error {
+    /** Stable discriminator usable in serialized logs / event payloads. */
+    kind;
+    constructor(kind, message, options) {
+        super(message);
+        this.name = new.target.name;
+        this.kind = kind;
+        if (options?.cause !== undefined) {
+            // ES2022 `cause` field. We assign defensively so older targets
+            // don't drop it on the floor.
+            this.cause = options.cause;
+        }
+        // Preserve prototype chain for downlevel-transpiled `extends`.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * The underlying fetch call never produced a response (DNS failure,
+ * connection refused, TLS error, offline, etc.). The remote service may
+ * or may not have processed the request; callers should treat this as a
+ * transient failure and retry later when connectivity is restored.
+ */
+export class CyberSoulNetworkError extends CyberSoulError {
+    endpoint;
+    method;
+    constructor(endpoint, method, message, options) {
+        super("network", message, options);
+        this.endpoint = endpoint;
+        this.method = method;
+    }
+}
+/**
+ * The request was aborted because it exceeded the configured
+ * `requestTimeoutMs`. A specialization of network error — callers that
+ * want to distinguish "no connection" from "slow connection" can use
+ * `instanceof CyberSoulTimeoutError`.
+ */
+export class CyberSoulTimeoutError extends CyberSoulNetworkError {
+    timeoutMs;
+    constructor(endpoint, method, timeoutMs) {
+        super(endpoint, method, `Request timed out after ${timeoutMs}ms: ${method} ${endpoint}`);
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * The backend returned a non-2xx HTTP response. Callers can inspect
+ * `status` to decide how to react (e.g. surface a user-facing message
+ * for 4xx vs. retry on 5xx).
+ */
+export class CyberSoulApiError extends CyberSoulError {
+    status;
+    endpoint;
+    method;
+    /** Parsed JSON body when available, otherwise `undefined`. */
+    body;
+    constructor(endpoint, method, status, message, body, kind = "api") {
+        super(kind, message);
+        this.status = status;
+        this.endpoint = endpoint;
+        this.method = method;
+        this.body = body;
+    }
+}
+/**
+ * The backend rejected the SDK's character credential (HTTP 401/403 on
+ * a character-scoped endpoint). The most common cause is that the
+ * character profile bound to this `characterKey` has been deleted on
+ * the backend; the binding is effectively terminal for this client.
+ */
+export class CyberSoulAuthError extends CyberSoulApiError {
+    constructor(endpoint, method, status, message, body) {
+        super(endpoint, method, status, message, body, "auth");
+    }
+}
+/**
+ * The backend rejected a paid action because the user's wallet does
+ * not have enough points to cover it (HTTP 402 / `INSUFFICIENT_POINTS`).
+ * Callers should surface a top-up prompt rather than retrying.
+ */
+export class CyberSoulInsufficientPointsError extends CyberSoulApiError {
+    /**
+     * Backend-supplied machine code. Always `"INSUFFICIENT_POINTS"` today;
+     * kept as a field so future variants (e.g. per-feature paywalls) can
+     * piggy-back on the same class.
+     */
+    code;
+    constructor(endpoint, method, status, message, body, code = "INSUFFICIENT_POINTS") {
+        super(endpoint, method, status, message, body, "insufficient-points");
+        this.code = code;
+    }
+}
+/**
+ * The wallet-deduction call failed for a reason *other than* insufficient
+ * balance (e.g. wallet service unavailable, accounting bug). Distinct from
+ * `CyberSoulInsufficientPointsError` because the user can't fix this by
+ * topping up — it's an upstream infrastructure issue.
+ */
+export class CyberSoulWalletError extends CyberSoulApiError {
+    code;
+    constructor(endpoint, method, status, message, body, code = "WALLET_DEDUCTION_ERROR") {
+        super(endpoint, method, status, message, body, "wallet");
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './client.js';
 export * from './llm.provider.js';
+export * from './errors.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './client.js';
 export * from './llm.provider.js';
+export * from './errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.4.9",
+  "version": "1.4.12",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",