@space3-npm/cybersoul-client 1.4.8 → 1.4.11

package/dist/client.d.ts

@@ -79,7 +79,15 @@ export declare class CyberSoulClient {
     ondemandEvent(params: OndemandEventParams): Promise<OndemandEventResponse>;
     /**
      * Generates a proactive message when the user hasn't responded.
-     * Safely prevents spamming, and adjusts its approach based on relationship dynamics.
+     *
+     * Design:
+     *  - Code owns ONE objective rule: don't spam (cap consecutive un-replied
+     *    messages). Everything else is a social judgment.
+     *  - The LLM owns the social judgment — given full character context
+     *    (stage, temperature, traits, ongoing scene, time since last
+     *    interaction, recent history), it answers a single question:
+     *    "Would I, as this person right now, actually reach out?"
+     *    Skip is the default; speaking is the exception.
      */
     proactiveInteract(params: ProactiveParams): Promise<ProactiveResponse>;
     /**

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, 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();
     }
@@ -861,137 +899,139 @@ CRITICAL: Output MUST be ONLY valid JSON with no markdown block wrappers. Do NOT
     }
     /**
      * Generates a proactive message when the user hasn't responded.
-     * Safely prevents spamming, and adjusts its approach based on relationship dynamics.
+     *
+     * Design:
+     *  - Code owns ONE objective rule: don't spam (cap consecutive un-replied
+     *    messages). Everything else is a social judgment.
+     *  - The LLM owns the social judgment — given full character context
+     *    (stage, temperature, traits, ongoing scene, time since last
+     *    interaction, recent history), it answers a single question:
+     *    "Would I, as this person right now, actually reach out?"
+     *    Skip is the default; speaking is the exception.
      */
     async proactiveInteract(params) {
         try {
-            // 1. Cold Interaction Protection (Logic-based fallback)
+            // 1. Spam guard (the only hard-coded gate). Counts assistant messages
+            //    since the last user reply; bails out if the user has clearly
+            //    stopped responding.
             const history = params.history || [];
             const maxUnreplied = params.maxUnreplied ?? 2;
             let consecutiveProactive = 0;
-            // Start from the most recent message
             for (let i = history.length - 1; i >= 0; i--) {
                 const msg = history[i];
-                if (msg.role === 'user') {
-                    break; // User responded, streak broken
-                }
-                if (msg.role === 'assistant') {
+                if (msg.role === "user")
+                    break;
+                if (msg.role === "assistant")
                     consecutiveProactive++;
-                }
             }
             if (consecutiveProactive >= maxUnreplied) {
                 return {
                     status: "skipped",
-                    reason: `User is busy. ${consecutiveProactive} consecutive proactive messages ignored.`
+                    reason: `Spam guard: ${consecutiveProactive} consecutive un-replied messages already sent.`,
                 };
             }
-            // 2. Fetch current character state
+            // 2. Fetch state. baseContext below already includes stage,
+            //    temperature, traits, ongoing scene, active/next event, current
+            //    time, and lastInteractionAt — the LLM has everything it needs to
+            //    make the social call without us restating it.
             const [state, availableOutfits] = await Promise.all([
                 this.fetchRemoteState(),
-                this.getWardrobePromptStr()
+                this.getWardrobePromptStr(),
             ]);
-            // 3. Evaluate behavioral approach based on relationship and personality
-            const dyn = state.dynamic_context || {};
-            const stage = state.relationship_stage || "STRANGER";
-            const temperature = dyn.temperature ?? 0;
-            const userTraits = state.user_codex?.psychological?.traits?.join(", ") || "";
-            let interrogationStrategy = "Do not ask 'are you there?' or 'why aren't you answering?'. Just share your current status, a passing thought, complain whimsically, or tease the user naturally like a real partner.";
-            if (stage === "PARTNER" || (stage === "INTIMATE" && temperature > 70)) {
-                // PARTNER (>85) or High INTIMATE (>70)
-                interrogationStrategy = "Because you are deeply intimate and highly affectionate, you MISS them. You MAY organically 'interrogate' or pout playfully about why they are ignoring you (e.g., 'Are you too busy for me?', 'Still ignoring your girl?'). Act like a real, slightly needy/attached partner.";
-            }
-            else if (stage === "INTIMATE" || stage === "WARM") {
-                // Low INTIMATE (60-70) or WARM (40-60)
-                interrogationStrategy = "Because you are close but currently feeling neglected or cold, you notice they are ignoring you. You MAY be passive-aggressive or cross-examine them coldly (e.g., 'So we're just not talking today?', 'Fine, keep ignoring me.').";
-            }
-            else if (stage === "COLD" || stage === "ACQUAINTANCE" || stage === "STRANGER") {
-                // COLD (<40)
-                interrogationStrategy = "You are distant. Do NOT double-text with neediness. If you must speak, make it a detached observation or a cold administrative remark.";
-            }
-            // History/Context awareness prompt
-            const historyAwarenessPrompt = `CRITICAL CONTEXT AWARENESS: Read the CHAT HISTORY above carefully. Remember that YOU sent the last message. Your new message MUST feel organically connected to the flow of what you two were previously talking about, or naturally bring up a known event/topic from your [CORE MEMORY]. Do not sound like a robot reading a log.`;
-            // 4. Build a Proactive-specific System Prompt
             const baseContext = this.buildStateContextPrompt(state, true);
             const types = this.normalizeRequestTypes(params.requestTypes);
             const requestedOthers = types.filter((t) => t !== InteractRequestType.AUTO && t !== InteractRequestType.TEXT);
-            // Determine modalities (reusing logic from interact)
-            let modalitiesInstruction = "You are initiating conversation without a preceding user message.\\n";
-            if (requestedOthers.includes(InteractRequestType.IMAGE)) {
-                modalitiesInstruction += "  - Include 'imageParams' for visual/photo moments. CRITICAL POLICY: NEVER send pictures to strangers! If Stage is STRANGER or COLD, or Familiarity is very low (< 10), ALWAYS set 'imageParams' to null.\\n";
-            }
-            else {
-                modalitiesInstruction += "  - ALWAYS set 'imageParams' to null.\\n";
-            }
+            const imageAllowed = requestedOthers.includes(InteractRequestType.IMAGE);
+            // 3. Build the prompt. We deliberately ask ONE coherent question
+            //    framed in-character ("would I text right now?") rather than
+            //    handing the LLM a checklist. The character's own traits,
+            //    relationship state, and recent transcript are the inputs.
             const systemPrompt = `${baseContext}
 
-[PROACTIVE INITIATION TASK]
-The user has NOT spoken to you recently. You sent the last message in the chat history, and they haven't replied. You are deciding to follow up proactively.
-If you decide that based on your current mood and the relationship stage it's better not to send a message right now (e.g. you are cold and giving them space), you can skip this proactive message by setting "shouldSkipProactive" to true.
-${interrogationStrategy}
-${historyAwarenessPrompt}
-Consider the user's known traits (${userTraits}) when choosing how to act. Need to keep it strictly under 2-3 sentences max.
+[PROACTIVE OPPORTUNITY]
+Time has passed since the last message in [CHAT HISTORY] and the user has not replied. You have an OPPORTUNITY (not an obligation) to send them a message. Decide, in character, whether you would actually do that.
+
+[HOW TO DECIDE — THINK LIKE THE PERSON YOU ARE]
+Real humans rarely send unprompted messages. Most of the time, silence is the right answer. Reach out ONLY if a real person with YOUR personality, in YOUR relationship to this user, at THIS moment, would genuinely feel moved to text.
+
+Reasons NOT to reach out (set "shouldSkipProactive": true):
+  - The last exchange ended on a note that closes the door — a farewell, a brush-off, a fight, a "talk later", an explicit dismissal — from either side. If YOU pushed them away last turn (because of your traits or a fight), staying quiet IS the in-character choice; flipping to friendly now makes you look bipolar.
+  - Your relationship is too distant for unsolicited contact (e.g. STRANGER, COLD) or your current mood is too low to want to reach out.
+  - Too little time has passed since the last message for a follow-up to feel natural. Use the time gap shown in [CHAT HISTORY] — minutes after the last turn is almost always too soon.
+  - There is no genuine reason to text — no shared thread, no event, no thought that would actually push a real person to pick up the phone.
+  - It's the wrong time of day for this relationship.
+
+When in doubt: SKIP. The bar for reaching out is high.
+
+[IF YOU DO DECIDE TO REACH OUT]
+Speak strictly in character — your traits, communication style, and current mood dictate the tone. Do NOT default to needy/cheerful unless that's who you are. Connect naturally to the last topic or to your current scene/event. Keep it to 2-3 short sentences. Never ask "are you there?" or "why aren't you answering?".
 
 Available Wardrobe Outfits:
 ${availableOutfits}
 
-${modalitiesInstruction}
-You MUST output ONLY a valid JSON object matching exactly this structure:
+Modalities:
+  - 'textResponse' is required when you proceed.
+  - ${imageAllowed
+                ? "'imageParams' may be included only if sending a photo right now would feel natural for this character in this relationship — otherwise set null. Do not attach a photo just because you can."
+                : "ALWAYS set 'imageParams' to null."}
+  - ALWAYS set 'voiceArgs' to null.
+
+Output ONLY a valid JSON object matching exactly this structure (no markdown wrappers).
+If "shouldSkipProactive" is true, set "skipReason" to one short sentence and set every other field to null.
+If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate" must be provided; include "ongoingScene" only if your scene/outfit actually changed, otherwise omit it.
 {
   "shouldSkipProactive": false,
-  "skipReason": "(Optional. Reason for skipping if shouldSkipProactive is true)",
+  "skipReason": null,
   "actionText": "(Scene descriptions, physical actions, expressions, inner feelings) ONLY.",
   "textResponse": "Spoken dialogue ONLY.",
-  "stateUpdate": { "temperatureDelta": 1, "ongoingScene": { "scene": "...", "outfit": "..." } },
-  ${this.getImageSchemaParams(requestedOthers.includes(InteractRequestType.IMAGE))},
+  "stateUpdate": { "temperatureDelta": 0, "ongoingScene": { "scene": "...", "outfit": "..." } },
+  ${this.getImageSchemaParams(imageAllowed)},
   "voiceArgs": null
 }`;
-            const transcript = params.history && params.history.length > 0 ? this.buildHistoryTranscript(params.history, state) : "";
-            const harnessContext = params.localContext ? `[ADDITIONAL SCENE CONTEXT]\n${params.localContext}\n\n` : "";
+            const transcript = params.history && params.history.length > 0
+                ? this.buildHistoryTranscript(params.history, state)
+                : "";
+            const harnessContext = params.localContext
+                ? `[ADDITIONAL SCENE CONTEXT]\n${params.localContext}\n\n`
+                : "";
             const promptMessages = [
                 { role: "system", content: systemPrompt },
                 {
                     role: "user",
-                    content: `${harnessContext}${transcript}\n[TRIGGER PROACTIVE MESSAGE]\nBased on your active event and environment, send a new message to the user.\n\nCRITICAL: Output ONLY valid JSON matching the schema. DO NOT wrap the JSON in \`\`\`json.`
-                }
+                    content: `${harnessContext}${transcript}\n[DECIDE NOW]\nWould you, as this character, actually send a message right now? Answer in the JSON schema above.`,
+                },
             ];
-            // 5. Generate with LLM using a confident temperature
-            const rawLlmResponse = await this.llm.generate(promptMessages, 800, 0.7);
-            let parsedIntent;
-            try {
-                parsedIntent = robustJsonParse(rawLlmResponse, "Proactive fallback");
-            }
-            catch (e) {
-                parsedIntent = { textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim() };
-            }
+            // 4. LLM decides. Lower temperature than `interact` because this is a
+            //    judgment call, not creative reply.
+            const rawLlmResponse = await this.llm.generate(promptMessages, 800, 0.5);
+            // Fail fast on parse error. A proactive message is opt-in by design;
+            // if the LLM produced unparseable output we'd rather skip than ship
+            // raw scaffolding to the user.
+            const parsedIntent = robustJsonParse(rawLlmResponse, "Proactive fallback");
             if (parsedIntent.shouldSkipProactive) {
                 return {
                     status: "skipped",
-                    reason: parsedIntent.skipReason || "Character decided to skip proactive message based on mood/stage."
+                    reason: parsedIntent.skipReason || "Character chose not to reach out.",
+                };
+            }
+            if (typeof parsedIntent.textResponse !== "string" || parsedIntent.textResponse.trim().length === 0) {
+                return {
+                    status: "skipped",
+                    reason: "LLM produced no textResponse (treated as implicit skip).",
                 };
             }
-            // Update Remote state if needed (capture promise for authoritative
-            // server snapshot — see notes in interact()).
+            // 5. Persist state and optionally generate image, in parallel.
             let persistedStatePromise = Promise.resolve(null);
             if (parsedIntent.stateUpdate) {
                 persistedStatePromise = this._updateDynamicContextInternal(parsedIntent.stateUpdate);
             }
-            const resolvedTextResponse = typeof parsedIntent.textResponse === "string" &&
-                parsedIntent.textResponse.trim().length > 0
-                ? parsedIntent.textResponse
-                : "...";
-            // Fire text ready callback if provided
-            if (params.onTextReady && (resolvedTextResponse || parsedIntent.actionText)) {
-                params.onTextReady(resolvedTextResponse, parsedIntent.actionText, {
+            if (params.onTextReady) {
+                params.onTextReady(parsedIntent.textResponse, parsedIntent.actionText, {
                     stateUpdate: parsedIntent.stateUpdate,
-                    userAnalysis: parsedIntent.userAnalysis,
-                    isEndTurn: parsedIntent.isEndTurn,
-                    triggerEvent: parsedIntent.triggerEvent,
-                    likePreviousPicture: parsedIntent.likePreviousPicture,
                 });
             }
-            // Handle Optional Media (Image only for proactive to save compute normally, but you can extend)
-            let finalImageUrl = undefined;
-            let finalImageMediaId = undefined;
+            let finalImageUrl;
+            let finalImageMediaId;
             if (parsedIntent.imageParams) {
                 try {
                     const res = await this.generatePrimitive("image", parsedIntent.imageParams);

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.8",
+  "version": "1.4.11",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",