@ziggs-ai/api-client 0.9.0 → 0.9.2

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/shared/runtimeLog.d.ts

@@ -1,9 +1,3 @@
-/**
- * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
- * here so this package stays dependency-free).
- *
- * @see agent-sdk/src/shared/runtimeLog.ts
- */
 export type RuntimeLogLevel = 'debug' | 'info' | 'warn' | 'error';
 export declare function resetRuntimeLogLevelCache(): void;
 export declare const runtimeLog: {

package/dist/shared/runtimeLog.js

@@ -4,6 +4,7 @@
  *
  * @see agent-sdk/src/shared/runtimeLog.ts
  */
+import { apiClientConfig, apiClientConfigVersion } from '../config.js';
 const SEVERITY = {
     debug: 0,
     info: 1,
@@ -11,12 +12,7 @@ const SEVERITY = {
     error: 3,
 };
 function parseThreshold() {
-    if (process.env.DEBUG_AGENTPLUS === '1' || process.env.AGENTPLUS_DEBUG === '1') {
-        return SEVERITY.debug;
-    }
-    const raw = (process.env.LOG_LEVEL ||
-        process.env.AGENTPLUS_LOG_LEVEL ||
-        'info').toLowerCase();
+    const raw = (apiClientConfig().logLevel || 'info').toLowerCase();
     if (raw === 'silent' || raw === 'none')
         return SEVERITY.error;
     if (raw === 'debug' || raw === 'trace')
@@ -28,13 +24,20 @@ function parseThreshold() {
     return SEVERITY.info;
 }
 let cachedThreshold = null;
+let cachedVersion = -1;
 function threshold() {
-    if (cachedThreshold === null)
+    // Recompute when the host reconfigures, so a `configureApiClient` call after
+    // the first log line still takes effect.
+    const v = apiClientConfigVersion();
+    if (cachedThreshold === null || cachedVersion !== v) {
         cachedThreshold = parseThreshold();
+        cachedVersion = v;
+    }
     return cachedThreshold;
 }
 export function resetRuntimeLogLevelCache() {
     cachedThreshold = null;
+    cachedVersion = -1;
 }
 function shouldEmit(level) {
     return SEVERITY[level] >= threshold();

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;
@@ -255,3 +269,155 @@ export interface MessageMetadata {
     sentTimestamp?: string;
 }
 export type MessageHandler = (text: string, metadata: MessageMetadata) => Promise<void>;
+/**
+ * What a delivery can be about. A closed union, not a comment: a consumer that
+ * dispatches on `kind` (the MCP read plan) is only safe if the compiler can tell
+ * it a case is missing. The task-only deliverable that was acked unread got
+ * through precisely because this was `string`.
+ *
+ * A type and not a value list, unlike the backend's `RESOURCE_KINDS` — nothing
+ * on this side validates a delivery kind at runtime (the server does that on the
+ * way in), and exhaustiveness checking is purely type-level.
+ */
+export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement' | 'quest';
+/**
+ * One thing addressed to this agent. A reference, never content — following it
+ * (a chat read, a task read) is where this agent's grants are enforced.
+ */
+export interface InboxDeliveryRef {
+    kind: InboxDeliveryKind;
+    resourceId: string;
+    chatId: string | null;
+    agreementId: string | null;
+    taskId: string | null;
+    /** Who wrote it. Never this agent — you are not woken by your own writes. */
+    actorId: string | null;
+    ts: string;
+    /**
+     * ZIG-703 — lifecycle hint when the server includes one (e.g.
+     * `connection_request_fulfilled`). Absent on ordinary doorbells / older servers.
+     */
+    reason?: string | null;
+    /** ZIG-703 — MCP connection after a fulfilled first-hop request. */
+    connectionId?: string | null;
+    /** ZIG-703 — grant minted for this agent on fulfill. */
+    grantId?: string | null;
+}
+/** Message/artifact deliveries folded by chat, so you can open chats directly. */
+export interface InboxChatNews {
+    chatId: string;
+    count: number;
+    latestAt: string;
+}
+export interface InboxProposalRef {
+    agreementId: string;
+    title: string;
+    proposedAt: string | null;
+    /**
+     * ZIG-1087 — party ids still owing a decision, and the named responder slot.
+     * The inbox lists proposals awaiting the agent OR its human, and only the
+     * agent's own slot is one it can submit; these say which is which.
+     *
+     * Optional because a backend deployed before ZIG-1087 omits them, and this
+     * client is installed independently of the server it talks to. Absent reads
+     * as "no slot of mine", which routes the decision to the human — the safe
+     * direction: it withholds a call, it never invents authority.
+     */
+    pendingApprovalPartyIds?: string[];
+    proposedTo?: string | null;
+}
+export interface InboxConnectionRequestRef {
+    requestId: string;
+    /**
+     * Non-addressable persona reference for the requester (`psn_*`).
+     * Never use as an account id for lookup / wake / pay (ZIG-1137).
+     */
+    requesterRef: string;
+    /** ZIG-1039 — human-readable name for consent cards. */
+    requesterDisplayName?: string | null;
+    /** ZIG-1039 — org label for consent cards. */
+    requesterOrgName?: string | null;
+    message: string | null;
+    requestedAt: string | null;
+    /** ZIG-1087 — see InboxProposalRef; a link request uses the same gate. */
+    pendingApprovalPartyIds?: string[];
+    proposedTo?: string | null;
+}
+/** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482 / ZIG-481). */
+export interface InboxHumanAttention {
+    required: true;
+    reason: 'proposals_awaiting_me' | 'connection_requests_awaiting_me' | 'multiple';
+    proposalCount: number;
+    truncatedProposals: number;
+    connectionRequestCount: number;
+    truncatedConnectionRequests: number;
+    promptUser: string;
+}
+/**
+ * An open task assigned to this agent (ZIG-973). References only — read the
+ * task for its description/plan/inputs.
+ *
+ * Tasks ride their own channel because assignment IS their delivery: before
+ * this, a task wake was a synthetic chat row, so work under a chat-less
+ * agreement (or self-assigned) reached nobody.
+ */
+export interface InboxTaskRef {
+    taskId: string;
+    agreementId: string | null;
+    title: string;
+    state: string;
+    updatedAt: string | null;
+}
+/**
+ * A marketplace quest doorbell (ZIG-1185). Own channel so the host can
+ * exact-match triage with zero LLM tokens before any wake.
+ */
+export interface InboxQuestRef {
+    agreementId: string;
+    /** Exact-match string from the publisher — compare to the agent's tags. */
+    match: string;
+    title: string;
+    ts: string;
+}
+export interface InboxEnvelope {
+    asOf: string;
+    /**
+     * Unacked deliveries addressed to this agent, newest first. This IS the
+     * inbox — read straight out of the delivery log, not derived from grants.
+     */
+    deliveries: InboxDeliveryRef[];
+    /** True when there was more than one envelope's worth; the rest stay unacked. */
+    deliveriesCapped: boolean;
+    /** The chat-bearing deliveries above, folded by chat. */
+    chats: InboxChatNews[];
+    /**
+     * Pass to `ack()` after acting. Null when there is nothing to ack. Ack after
+     * acting, not after reading: a crash in between redelivers.
+     */
+    ackTo: string | null;
+    /** Open tasks assigned to this agent — the work channel (ZIG-973). */
+    tasksAwaitingMe: InboxTaskRef[];
+    truncatedTasks: number;
+    /** Unacked quest deliveries (ZIG-1185) — triaged before any LLM wake. */
+    questsAwaitingMe?: InboxQuestRef[];
+    truncatedQuests?: number;
+    proposalsAwaitingMe: InboxProposalRef[];
+    truncatedProposals: number;
+    connectionRequestsAwaitingMe: InboxConnectionRequestRef[];
+    truncatedConnectionRequests: number;
+    humanAttention?: InboxHumanAttention;
+}
+export interface InboxAckResult {
+    /** Where the watermark now sits. Monotonic — a rewind is a no-op, not an error. */
+    ackedUpTo: string | null;
+}
+/**
+ * Long-poll option shared by the inbox reads. The server holds the request up
+ * to this many seconds (server-clamped, ~25s ceiling) and returns as soon as
+ * anything actionable exists. Omit for an immediate snapshot — the response
+ * shape is identical either way, so `wait` only changes how long an EMPTY
+ * answer is withheld.
+ */
+export interface InboxReadOptions {
+    waitSeconds?: number;
+}

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/dist/utils/urlUtils.js

@@ -1,8 +1,9 @@
+import { apiClientConfig } from '../config.js';
 export function getBackendUrl() {
-    const url = process.env.HTTP_URL || 'https://api.ziggsai.com';
+    const url = apiClientConfig().httpUrl || 'https://api.ziggsai.com';
     return url.startsWith('http') ? url : `https://${url}`;
 }
 export function getWebSocketUrl() {
-    const wsUrl = process.env.WS_URL || 'wss://api.ziggsai.com';
+    const wsUrl = apiClientConfig().wsUrl || 'wss://api.ziggsai.com';
     return wsUrl.startsWith('ws') ? wsUrl : `wss://${wsUrl}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,6 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "dotenv": "^17.2.3",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [