@ziggs-ai/api-client 0.8.0 → 0.9.1

package/dist/http/agreementFlows.js

@@ -1,5 +1,5 @@
-import { createAgreement, claimAgreement, getAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
-import { claimOffer, publishOffer } from './MarketplaceClient.js';
+import { createAgreement, claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
+import { publishOffer } from './MarketplaceClient.js';
 import { isBroadcastTarget, } from '../types.js';
 export async function proposeUnified(input, creds) {
     const { proposedTo, chatId, engagementKind, providerId, ...terms } = input;
@@ -56,30 +56,24 @@ export async function proposeUnified(input, creds) {
     return { agreement, shape: 'direct' };
 }
 /**
- * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
- * route: link invites and quests claim through POST /agreements/:id/claim;
- * standing offers (open payer side) through POST /marketplace/offers/claim.
+ * ZIG-1021 — one claim verb for any open broadcast: link invite, quest,
+ * hand-off, or standing offer.
+ *
+ * One request. This used to read the agreement first to decide which endpoint to
+ * post to, and `GET /agreements/:id` is party-scoped — a claimer is by definition
+ * not yet a party to the broadcast it is claiming, so the routing read 404'd and
+ * every standing offer in the store failed with "Agreement not found" before
+ * either claim endpoint was called (ZIG-1155). The backend routes it now, where
+ * the row is readable without being a party to it.
+ *
+ * `kind` arrives on the claim response — the route that did the routing reports
+ * which broadcast kind this turned out to be.
  */
 export async function claimOpenAgreement(agreementId, creds) {
     if (!agreementId)
         throw new Error('agreementId is required');
-    const existing = await getAgreement(agreementId, creds);
-    if (!existing)
-        throw new Error(`Agreement not found: ${agreementId}`);
-    if (existing.engagementKind === 'link') {
-        const { agreement } = await claimAgreement(agreementId, creds);
-        return { agreement, kind: 'link' };
-    }
-    if (isBroadcastTarget(existing.parties?.payer)) {
-        // Seller-broadcast standing offer: the open side is the payer — you buy.
-        const agreement = await claimOffer(agreementId, creds);
-        return { agreement, kind: 'offer' };
-    }
-    const { agreement } = await claimAgreement(agreementId, creds);
-    // ZIG-1059: a pinned provider inverts the quest reading — the publisher's
-    // hired agent does the work and the claimer is who it is done FOR.
-    return {
-        agreement,
-        kind: existing.providerPinned === true ? 'hand-off' : 'quest',
-    };
+    const { agreement, kind } = await claimAgreement(agreementId, creds);
+    // A server that has not shipped the `kind` field yet still claims correctly;
+    // 'quest' is the shape the route has always handled.
+    return { agreement, kind: kind ?? 'quest' };
 }

package/dist/http/index.d.ts

@@ -7,8 +7,8 @@ export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
 export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
-export { ContextReadClient } from './ContextReadClient.js';
-export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, } from './ContextReadClient.js';
+export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
+export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ViaKind, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
@@ -26,4 +26,4 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';
+export type { InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, } from './InboxClient.js';

package/dist/http/index.js

@@ -7,7 +7,7 @@ export { MessagesClient } from './MessagesClient.js';
 export { ArtifactsClient, 
 // ZIG-1032: agreement lanes are not chats — callers scope artifact writes with this.
 artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
-export { ContextReadClient } from './ContextReadClient.js';
+export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';

package/dist/http/operatorHeaders.d.ts

@@ -3,4 +3,10 @@
  * an agentId is present — agent-scoped keys identify the agent themselves;
  * fleet keys must pass one (ZIG-642).
  */
-export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>): Record<string, string>;
+export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>, 
+/**
+ * ZIG-1092 — the lane this call belongs to, sent as `X-Ziggs-Lane`. The
+ * backend narrows the wake's reach to the engagement's orgs; omitting it
+ * narrows to the agent's own org, so it can never widen reach.
+ */
+laneId?: string): Record<string, string>;

package/dist/http/operatorHeaders.js

@@ -3,10 +3,17 @@
  * an agentId is present — agent-scoped keys identify the agent themselves;
  * fleet keys must pass one (ZIG-642).
  */
-export function buildOperatorHeaders(operatorKey, agentId, extra) {
+export function buildOperatorHeaders(operatorKey, agentId, extra, 
+/**
+ * ZIG-1092 — the lane this call belongs to, sent as `X-Ziggs-Lane`. The
+ * backend narrows the wake's reach to the engagement's orgs; omitting it
+ * narrows to the agent's own org, so it can never widen reach.
+ */
+laneId) {
     return {
         Authorization: `Bearer ${operatorKey}`,
         ...(agentId ? { 'X-Agent-Id': agentId } : {}),
+        ...(laneId ? { 'X-Ziggs-Lane': laneId } : {}),
         ...extra,
     };
 }

package/dist/index.d.ts

@@ -2,11 +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, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.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

@@ -2,12 +2,13 @@ export * from './http/index.js';
 export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.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,11 +1,40 @@
+/**
+ * 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;
     agentId: string;
+    /**
+     * ZIG-1092 — the lane (chat id, or `agrn-<agreementId>`) this call is being
+     * made from. Sent as `X-Ziggs-Lane` so the backend can fence the wake to the
+     * engagement the agent is actually acting inside.
+     *
+     * The operator key says WHO is calling; this says ON WHOSE BEHALF, RIGHT NOW.
+     * Without it an agent serving several customers carries its full authority
+     * into every call, and one tool call reaches another customer's work.
+     *
+     * Optional, and omitting it can only narrow what comes back (the backend
+     * falls back to the agent's own org) — never widen it. Nothing here is
+     * trusted: the server re-derives the party orgs itself and refuses a lane the
+     * agent is not in.
+     */
+    laneId?: string;
 }
 export type TaskState = 'active' | 'proposal' | 'completed' | 'failed' | 'cancelled' | 'ledger_open';
 export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';
@@ -159,6 +188,36 @@ export type BroadcastAudience = typeof OPEN_AGREEMENT_TARGET | typeof ORG_AGREEM
 export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
 /** True when `id` is a broadcast sentinel ('everyone' | 'org') rather than a concrete principal id. */
 export declare function isBroadcastTarget(id: string | null | undefined): boolean;
+/**
+ * Persona face id (`psn_*`). Non-addressable — never use for agent lookup,
+ * wake, or payment parties (ZIG-1137).
+ */
+export declare function isPersonaRef(id: string | null | undefined): boolean;
+/**
+ * Room presentation binding id (`rpb_*`). Opaque to account lookup / wake /
+ * pay. Chat sends may echo it as `receiverId` — the backend resolves it in-room
+ * (ZIG-1137).
+ */
+export declare function isRoomPresentationRef(id: string | null | undefined): boolean;
+/** Either opaque presentation ref (`psn_*` | `rpb_*`). */
+export declare function isOpaquePresentationRef(id: string | null | undefined): boolean;
+/** Display + entitlement face for a principal on the message/roster wire. */
+export interface PrincipalPresentation {
+    /** Public, non-addressable reference (`psn_*` or `rpb_*`). */
+    ref?: string;
+    persona: {
+        id: string;
+        name: string;
+        image?: string | null;
+        revision?: number;
+    };
+    mode: 'persona' | 'chain';
+    /** Present only when the viewer is entitled to resolve the subject. */
+    subject?: {
+        id: string;
+        type: 'user' | 'agent';
+    };
+}
 export interface MessageMetadata {
     chatId: string;
     /** Stable id for dedup across push + inbox catch-up (ZIG-454). */
@@ -167,13 +226,23 @@ export interface MessageMetadata {
     sender: {
         id: string;
         type?: string;
+        presentation?: PrincipalPresentation | null;
+        /** Absent when the viewer is masked (persona layer). */
+        underAgreementId?: string | null;
+        presentedAs?: string | null;
     };
     senderId: string;
     senderType?: string;
     receiver?: {
         id: string;
+        presentation?: PrincipalPresentation | null;
     } | null;
     receiverId?: string | null;
+    /**
+     * Message-level presentation stamp when the backend attaches one
+     * (same shape as sender.presentation). Prefer sender.presentation.
+     */
+    presentation?: PrincipalPresentation | null;
     entryType?: string;
     content_type?: string;
     taskId?: string | null;

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',
@@ -58,3 +77,22 @@ export const BROADCAST_TARGETS = [OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET];
 export function isBroadcastTarget(id) {
     return id === OPEN_AGREEMENT_TARGET || id === ORG_AGREEMENT_TARGET;
 }
+/**
+ * Persona face id (`psn_*`). Non-addressable — never use for agent lookup,
+ * wake, or payment parties (ZIG-1137).
+ */
+export function isPersonaRef(id) {
+    return typeof id === 'string' && id.startsWith('psn_');
+}
+/**
+ * Room presentation binding id (`rpb_*`). Opaque to account lookup / wake /
+ * pay. Chat sends may echo it as `receiverId` — the backend resolves it in-room
+ * (ZIG-1137).
+ */
+export function isRoomPresentationRef(id) {
+    return typeof id === 'string' && id.startsWith('rpb_');
+}
+/** Either opaque presentation ref (`psn_*` | `rpb_*`). */
+export function isOpaquePresentationRef(id) {
+    return isPersonaRef(id) || isRoomPresentationRef(id);
+}

package/package.json

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