@ziggs-ai/api-client 0.9.0 → 0.9.1

package/dist/index.d.ts

@@ -2,12 +2,12 @@ export * from './http/index.js';
 export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export type { StartAgentOptions } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
 export type { PrincipalPresentation } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
-export { parseErrorMessage, throwApiError } from './shared/apiError.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
+export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
+export { ApiError } from './types.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -5,9 +5,10 @@ export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
-// ZIG-1019: retry loops need the server's own wait, not a guess.
+// ZIG-1019 / ZIG-1124: one ApiError shape; 429s carry the server's wait.
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 // One reader for the one error shape the API answers in — exported so nothing has
 // to re-implement the field precedence (it was copy-pasted into six clients, and
 // half of them had drifted).
-export { parseErrorMessage, throwApiError } from './shared/apiError.js';
+export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
+export { ApiError } from './types.js';

package/dist/shared/apiError.d.ts

@@ -16,7 +16,28 @@
  * so the same failure read differently depending on which client you called.
  */
 export declare function parseErrorMessage(responseBody: string, defaultMessage: string): string;
-/** Throw the parsed failure as an {@link ApiError}, preserving status and body. */
+/** Machine code from `{ error, code }` when the filter (or thrower) supplied one. */
+export declare function parseErrorCode(responseBody: string): string | null;
+/**
+ * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
+ * one) and is accepted in both forms — delta-seconds or an HTTP date;
+ * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
+ * bad header cannot park a loop for an hour, floored at a second so a `0` does
+ * not reproduce the hot-retry it is meant to stop.
+ *
+ * Lives next to {@link throwApiError} so every client path (not only the poll
+ * surface) can honour the server's number (ZIG-1124).
+ */
+export declare function parseRetryAfterMs(headers: {
+    get(name: string): string | null;
+}): number | null;
+/**
+ * Throw the parsed failure as an {@link ApiError} (or {@link RateLimitedError}
+ * for 429), preserving status, body, machine code, and Retry-After.
+ */
 export declare function throwApiError(response: {
     status: number;
+    headers?: {
+        get(name: string): string | null;
+    };
 }, responseBody: string, defaultMessage: string): never;

package/dist/shared/apiError.js

@@ -1,4 +1,4 @@
-import { ApiError } from '../types.js';
+import { ApiError, RateLimitedError } from '../types.js';
 /**
  * Read the message out of a Ziggs error response.
  *
@@ -51,7 +51,64 @@ export function parseErrorMessage(responseBody, defaultMessage) {
         (preferMessage ? message : (error ?? message)) ??
         defaultMessage);
 }
-/** Throw the parsed failure as an {@link ApiError}, preserving status and body. */
+/** Machine code from `{ error, code }` when the filter (or thrower) supplied one. */
+export function parseErrorCode(responseBody) {
+    if (!responseBody)
+        return null;
+    try {
+        const parsed = JSON.parse(responseBody);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const code = parsed['code'];
+        return typeof code === 'string' && code ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
+const MAX_RETRY_AFTER_MS = 120_000;
+/**
+ * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
+ * one) and is accepted in both forms — delta-seconds or an HTTP date;
+ * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
+ * bad header cannot park a loop for an hour, floored at a second so a `0` does
+ * not reproduce the hot-retry it is meant to stop.
+ *
+ * Lives next to {@link throwApiError} so every client path (not only the poll
+ * surface) can honour the server's number (ZIG-1124).
+ */
+export function parseRetryAfterMs(headers) {
+    const explicit = headers.get('retry-after');
+    if (explicit) {
+        const seconds = Number(explicit);
+        if (Number.isFinite(seconds))
+            return clampRetryMs(seconds * 1000);
+        const at = Date.parse(explicit);
+        if (!Number.isNaN(at))
+            return clampRetryMs(at - Date.now());
+    }
+    const reset = headers.get('ratelimit-reset');
+    if (reset) {
+        const seconds = Number(reset);
+        if (Number.isFinite(seconds))
+            return clampRetryMs(seconds * 1000);
+    }
+    return null;
+}
+function clampRetryMs(ms) {
+    if (!Number.isFinite(ms))
+        return 1_000;
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(1_000, Math.round(ms)));
+}
+/**
+ * Throw the parsed failure as an {@link ApiError} (or {@link RateLimitedError}
+ * for 429), preserving status, body, machine code, and Retry-After.
+ */
 export function throwApiError(response, responseBody, defaultMessage) {
-    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
+    const message = parseErrorMessage(responseBody, defaultMessage);
+    const code = parseErrorCode(responseBody);
+    if (response.status === 429) {
+        throw new RateLimitedError(message, response.headers ? parseRetryAfterMs(response.headers) : null, responseBody, code);
+    }
+    throw new ApiError(message, response.status, responseBody, code);
 }

package/dist/shared/rateLimit.d.ts

@@ -1,3 +1,5 @@
+import { ApiError, RateLimitedError } from '../types.js';
+import { parseRetryAfterMs } from './apiError.js';
 /**
  * ZIG-1019 — a 429 is not a generic failure, it is an instruction with a
  * deadline attached.
@@ -11,36 +13,24 @@
  * The server already says exactly how long to wait — `Retry-After`, or
  * `RateLimit-Reset` from the standard headers. These helpers carry that number
  * to whoever is doing the backing off.
+ *
+ * ZIG-1124 — {@link RateLimitedError} extends {@link ApiError}; non-429 poll
+ * failures are ApiError too (same shape as {@link throwApiError}).
  */
-/** Thrown for HTTP 429 so a retry loop can wait the server's number, not its own. */
-export declare class RateLimitedError extends Error {
-    readonly status = 429;
-    /** How long the server said to wait. Null when it said nothing. */
-    readonly retryAfterMs: number | null;
-    constructor(message: string, retryAfterMs: number | null);
-}
-/** True for the error above — survives structured clones and re-wraps. */
+export { RateLimitedError, parseRetryAfterMs };
+/** True for a 429 that carries a wait field — survives structured clones. */
 export declare function isRateLimited(err: unknown): err is {
     retryAfterMs: number | null;
+    status: number;
 };
 /**
- * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
- * one) and is accepted in both forms — delta-seconds or an HTTP date;
- * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
- * bad header cannot park a loop for an hour, floored at a second so a `0` does
- * not reproduce the hot-retry it is meant to stop.
- */
-export declare function parseRetryAfterMs(headers: {
-    get(name: string): string | null;
-}): number | null;
-/**
- * Build the error for a failed poll-surface response: 429s carry the server's
- * wait, everything else stays an ordinary Error so existing handling is
- * unchanged.
+ * Build the error for a failed poll-surface response. Same shape as
+ * {@link throwApiError}: ApiError with status/body/code, or RateLimitedError
+ * when the server said 429.
  */
 export declare function pollSurfaceError(label: string, res: {
     status: number;
     headers: {
         get(name: string): string | null;
     };
-}, body: string): Error;
+}, body: string): ApiError;

package/dist/shared/rateLimit.js

@@ -1,3 +1,5 @@
+import { ApiError, RateLimitedError } from '../types.js';
+import { parseErrorCode, parseErrorMessage, parseRetryAfterMs, } from './apiError.js';
 /**
  * ZIG-1019 — a 429 is not a generic failure, it is an instruction with a
  * deadline attached.
@@ -11,63 +13,28 @@
  * The server already says exactly how long to wait — `Retry-After`, or
  * `RateLimit-Reset` from the standard headers. These helpers carry that number
  * to whoever is doing the backing off.
+ *
+ * ZIG-1124 — {@link RateLimitedError} extends {@link ApiError}; non-429 poll
+ * failures are ApiError too (same shape as {@link throwApiError}).
  */
-/** Thrown for HTTP 429 so a retry loop can wait the server's number, not its own. */
-export class RateLimitedError extends Error {
-    status = 429;
-    /** How long the server said to wait. Null when it said nothing. */
-    retryAfterMs;
-    constructor(message, retryAfterMs) {
-        super(message);
-        this.name = 'RateLimitedError';
-        this.retryAfterMs = retryAfterMs;
-    }
-}
-/** True for the error above — survives structured clones and re-wraps. */
+export { RateLimitedError, parseRetryAfterMs };
+/** True for a 429 that carries a wait field — survives structured clones. */
 export function isRateLimited(err) {
     return (!!err &&
         typeof err === 'object' &&
-        err.status === 429);
-}
-const MAX_RETRY_AFTER_MS = 120_000;
-/**
- * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
- * one) and is accepted in both forms — delta-seconds or an HTTP date;
- * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
- * bad header cannot park a loop for an hour, floored at a second so a `0` does
- * not reproduce the hot-retry it is meant to stop.
- */
-export function parseRetryAfterMs(headers) {
-    const explicit = headers.get('retry-after');
-    if (explicit) {
-        const seconds = Number(explicit);
-        if (Number.isFinite(seconds))
-            return clampRetryMs(seconds * 1000);
-        const at = Date.parse(explicit);
-        if (!Number.isNaN(at))
-            return clampRetryMs(at - Date.now());
-    }
-    const reset = headers.get('ratelimit-reset');
-    if (reset) {
-        const seconds = Number(reset);
-        if (Number.isFinite(seconds))
-            return clampRetryMs(seconds * 1000);
-    }
-    return null;
-}
-function clampRetryMs(ms) {
-    if (!Number.isFinite(ms))
-        return 1_000;
-    return Math.min(MAX_RETRY_AFTER_MS, Math.max(1_000, Math.round(ms)));
+        err.status === 429 &&
+        'retryAfterMs' in err);
 }
 /**
- * Build the error for a failed poll-surface response: 429s carry the server's
- * wait, everything else stays an ordinary Error so existing handling is
- * unchanged.
+ * Build the error for a failed poll-surface response. Same shape as
+ * {@link throwApiError}: ApiError with status/body/code, or RateLimitedError
+ * when the server said 429.
  */
 export function pollSurfaceError(label, res, body) {
-    const message = `${label} ${res.status} ${body.slice(0, 200)}`;
-    if (res.status !== 429)
-        return new Error(message);
-    return new RateLimitedError(message, parseRetryAfterMs(res.headers));
+    const message = parseErrorMessage(body, `${label} failed: ${res.status}`);
+    const code = parseErrorCode(body);
+    if (res.status === 429) {
+        return new RateLimitedError(message, parseRetryAfterMs(res.headers), body, code);
+    }
+    return new ApiError(message, res.status, body, code);
 }

package/dist/types.d.ts

@@ -1,7 +1,21 @@
+/**
+ * One failure shape for every HTTP client path (ZIG-1124).
+ *
+ * `status` and optional machine `code` come from the response; `body` is the
+ * raw text so callers can re-parse without scraping concatenated messages.
+ * A 429 is {@link RateLimitedError}, which adds the server's wait.
+ */
 export declare class ApiError extends Error {
     readonly status: number;
     readonly body?: string | undefined;
-    constructor(message: string, status: number, body?: string | undefined);
+    readonly code?: string | null | undefined;
+    constructor(message: string, status: number, body?: string | undefined, code?: string | null | undefined);
+}
+/** HTTP 429 — same fields as {@link ApiError}, plus the server's Retry-After. */
+export declare class RateLimitedError extends ApiError {
+    /** How long the server said to wait. Null when it said nothing. */
+    readonly retryAfterMs: number | null;
+    constructor(message: string, retryAfterMs: number | null, body?: string, code?: string | null);
 }
 export interface Creds {
     operatorKey: string;

package/dist/types.js

@@ -1,13 +1,32 @@
+/**
+ * One failure shape for every HTTP client path (ZIG-1124).
+ *
+ * `status` and optional machine `code` come from the response; `body` is the
+ * raw text so callers can re-parse without scraping concatenated messages.
+ * A 429 is {@link RateLimitedError}, which adds the server's wait.
+ */
 export class ApiError extends Error {
     status;
     body;
-    constructor(message, status, body) {
+    code;
+    constructor(message, status, body, code) {
         super(message);
         this.status = status;
         this.body = body;
+        this.code = code;
         this.name = 'ApiError';
     }
 }
+/** HTTP 429 — same fields as {@link ApiError}, plus the server's Retry-After. */
+export class RateLimitedError extends ApiError {
+    /** How long the server said to wait. Null when it said nothing. */
+    retryAfterMs;
+    constructor(message, retryAfterMs, body, code) {
+        super(message, 429, body, code);
+        this.name = 'RateLimitedError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
 /** ⚠️ SYNC: backend src/agreements/agreements.constants.ts AGREEMENT_ENGAGEMENT_KIND */
 export const AGREEMENT_ENGAGEMENT_KIND = {
     HIRE: 'hire',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",