@ziggs-ai/api-client 0.7.1 → 0.9.0

package/dist/http/ContextReadClient.d.ts

@@ -1,5 +1,28 @@
 import 'dotenv/config';
-export type ContextReadType = 'messages' | 'artifacts' | 'agreements' | 'tasks';
+export declare const CONTEXT_READ_TYPES: readonly ["messages", "artifacts", "agreements", "tasks"];
+export type ContextReadType = (typeof CONTEXT_READ_TYPES)[number];
+/**
+ * Entry points a read can name as `via=<kind>:<id>` — the server's `parseVia`
+ * grammar. `counterparty` parses but reads nothing: it resolves a scope graph,
+ * not content, which is why {@link CONTEXT_READ_VIA} admits it for no type.
+ */
+export declare const VIA_KINDS: readonly ["chat", "agreement", "task", "counterparty", "artifact"];
+export type ViaKind = (typeof VIA_KINDS)[number];
+/**
+ * Which entry points each read type actually accepts, mirroring the server's
+ * `CONTEXT_READ_VIA`. Stated once here so the tool descriptions, the argument
+ * check, and this type all read off the same list instead of three prose
+ * copies that drift — and so a wrong pairing is refused with the reason rather
+ * than as a bare 400 from a round-trip away.
+ */
+export declare const CONTEXT_READ_VIA: Record<ContextReadType, readonly ViaKind[]>;
+/** `chat:<id>, agreement:<id>` — the accepted entries for one read type, for humans. */
+export declare function viaHint(type: ContextReadType): string;
+/** Split `chat:abc` into its parts, or null when it is not a `via` at all. */
+export declare function parseVia(via: string): {
+    kind: ViaKind;
+    id: string;
+} | null;
 export interface ContextReadQuery {
     via: string;
     cursor?: string;
@@ -12,7 +35,7 @@ export interface ContextReadQuery {
 export interface ContextReadEnvelope<T = unknown> {
     type: ContextReadType;
     via: {
-        kind: string;
+        kind: ViaKind;
         id: string;
     };
     items: T[];
@@ -44,11 +67,15 @@ export declare class ContextReadClient {
     private readonly operatorKey;
     private readonly agentId?;
     private readonly baseUrl;
+    private readonly laneId?;
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     * @param laneId ZIG-1092 — the wake's lane, sent as X-Ziggs-Lane. This is the
+     *   path the dogfood leak ran through: `via=artifact:<other customer's spec>`
+     *   was authorised purely because the same agent had authored it.
      */
-    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
     /**
      * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The

package/dist/http/ContextReadClient.js

@@ -1,6 +1,54 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
+export const CONTEXT_READ_TYPES = [
+    'messages',
+    'artifacts',
+    'agreements',
+    'tasks',
+];
+/**
+ * Entry points a read can name as `via=<kind>:<id>` — the server's `parseVia`
+ * grammar. `counterparty` parses but reads nothing: it resolves a scope graph,
+ * not content, which is why {@link CONTEXT_READ_VIA} admits it for no type.
+ */
+export const VIA_KINDS = [
+    'chat',
+    'agreement',
+    'task',
+    'counterparty',
+    'artifact',
+];
+/**
+ * Which entry points each read type actually accepts, mirroring the server's
+ * `CONTEXT_READ_VIA`. Stated once here so the tool descriptions, the argument
+ * check, and this type all read off the same list instead of three prose
+ * copies that drift — and so a wrong pairing is refused with the reason rather
+ * than as a bare 400 from a round-trip away.
+ */
+export const CONTEXT_READ_VIA = {
+    messages: ['chat'],
+    artifacts: ['chat', 'agreement', 'task', 'artifact'],
+    agreements: ['chat', 'agreement'],
+    tasks: ['agreement', 'task'],
+};
+/** `chat:<id>, agreement:<id>` — the accepted entries for one read type, for humans. */
+export function viaHint(type) {
+    return CONTEXT_READ_VIA[type].map((k) => `${k}:<id>`).join(', ');
+}
+/** Split `chat:abc` into its parts, or null when it is not a `via` at all. */
+export function parseVia(via) {
+    const at = via.indexOf(':');
+    if (at <= 0)
+        return null;
+    const kind = via.slice(0, at);
+    const id = via.slice(at + 1);
+    if (!id)
+        return null;
+    return VIA_KINDS.includes(kind)
+        ? { kind: kind, id }
+        : null;
+}
 /**
  * Protocol-first uniform context reads (ZIG-427).
  * Wraps `GET /context/read/:type` — one client, one envelope, four types.
@@ -9,16 +57,21 @@ export class ContextReadClient {
     operatorKey;
     agentId;
     baseUrl;
+    laneId;
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     * @param laneId ZIG-1092 — the wake's lane, sent as X-Ziggs-Lane. This is the
+     *   path the dogfood leak ran through: `via=artifact:<other customer's spec>`
+     *   was authorised purely because the same agent had authored it.
      */
-    constructor(operatorKey, agentId, baseUrl) {
+    constructor(operatorKey, agentId, baseUrl, laneId) {
         if (!operatorKey)
             throw new Error('ContextReadClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.laneId = laneId;
     }
     async read(type, query) {
         if (!query.via?.trim()) {
@@ -44,6 +97,8 @@ export class ContextReadClient {
         };
         if (this.agentId)
             headers['X-Agent-Id'] = this.agentId;
+        if (this.laneId)
+            headers['X-Ziggs-Lane'] = this.laneId;
         if (query.contextGrantId) {
             headers['X-Context-Grant-Id'] = query.contextGrantId;
         }
@@ -88,6 +143,8 @@ export class ContextReadClient {
         };
         if (this.agentId)
             headers['X-Agent-Id'] = this.agentId;
+        if (this.laneId)
+            headers['X-Ziggs-Lane'] = this.laneId;
         if (opts.contextGrantId) {
             headers['X-Context-Grant-Id'] = opts.contextGrantId;
         }

package/dist/http/InboxClient.d.ts

@@ -1,11 +1,21 @@
 import 'dotenv/config';
+/**
+ * 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';
 /**
  * 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 {
-    /** 'message' | 'artifact' | 'task-state' | 'agreement'. */
-    kind: string;
+    kind: InboxDeliveryKind;
     resourceId: string;
     chatId: string | null;
     agreementId: string | null;
@@ -24,16 +34,35 @@ 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;
-    requesterAgentId: 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 {

package/dist/http/MarketplaceClient.d.ts

@@ -31,7 +31,6 @@ export interface PublishQuestPayload {
     description: string;
     chatId?: string;
     payerId?: string;
-    parentTaskId?: string;
     price?: number;
     lifecycle?: string;
     expiresAt?: string;

package/dist/http/MarketplaceClient.js

@@ -1,12 +1,15 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { ApiError } from '../types.js';
+import { throwApiError } from '../shared/apiError.js';
 function getMarketplaceBaseUrl() { return `${getBackendUrl()}/marketplace`; }
 function buildHeaders(creds) {
     return {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {
@@ -15,15 +18,6 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-function throwApiError(response, body, defaultMsg) {
-    let msg = defaultMsg;
-    try {
-        const d = JSON.parse(body);
-        msg = d['details'] || d['error'] || d['message'] || defaultMsg;
-    }
-    catch { /**/ }
-    throw new ApiError(msg, response.status);
-}
 export async function publishOffer(payload, creds) {
     assertCreds(creds, 'marketplace offer publish');
     const res = await fetch(`${getMarketplaceBaseUrl()}/offers/publish`, {

package/dist/http/PaymentsClient.js

@@ -2,20 +2,10 @@ import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { GrantsClient } from './GrantsClient.js';
+import { parseErrorMessage } from '../shared/apiError.js';
 function randomIdempotencyKey(prefix = 'op') {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
-function parseError(text, fallback) {
-    if (!text)
-        return fallback;
-    try {
-        const parsed = JSON.parse(text);
-        return parsed['error'] || parsed['message'] || text;
-    }
-    catch {
-        return text;
-    }
-}
 /**
  * ZIG-894 — the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
@@ -227,7 +217,7 @@ export class PaymentsClient {
         const response = await fetch(`${this.baseUrl}${path}`, init);
         const text = await response.text();
         if (!response.ok) {
-            const err = new Error(parseError(text, `HTTP ${response.status}`));
+            const err = new Error(parseErrorMessage(text, `HTTP ${response.status}`));
             err.status = response.status;
             err.body = text;
             throw err;

package/dist/http/TaskClient.d.ts

@@ -1,10 +1,18 @@
 import 'dotenv/config';
 import { type Creds, type Task, type TaskState } from '../types.js';
+/**
+ * When the buyer reviews a task's plan. Task-rail only — an agreement has no
+ * plan to review, which is why ZIG-1095 cut this from the propose/counter/
+ * subcontract inputs rather than teaching those routes to keep one.
+ */
+export type PlanReviewTiming = 'with_proposal' | 'before_execution';
 export interface CreateTaskData {
     description: string;
     agreementId: string;
     parentTaskId?: string;
     plan?: unknown;
+    planReviewTiming?: PlanReviewTiming;
+    requireMidWorkPlanAck?: boolean;
     idempotencyKey?: string;
     /** Explicit delegation target (ZIG-586) — must be a party to the agreement; validated server-side. */
     assigneeId?: string;

package/dist/http/TaskClient.js

@@ -1,12 +1,15 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { ApiError } from '../types.js';
+import { throwApiError } from '../shared/apiError.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
 function buildHeaders(creds) {
     return {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {
@@ -15,26 +18,6 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-function parseErrorMessage(responseBody, defaultMessage) {
-    if (!responseBody)
-        return defaultMessage;
-    try {
-        const d = JSON.parse(responseBody);
-        // NestJS ValidationPipe returns { message: string[] | string, error: 'Bad
-        // Request', statusCode }. Prefer the detailed `message` over the generic
-        // `error` so the real cause (which field failed validation) is surfaced
-        // instead of a bare "Bad Request". (ZIG-832)
-        const msg = d['message'];
-        const detailed = Array.isArray(msg) ? msg.join('; ') : (typeof msg === 'string' ? msg : undefined);
-        return d['details'] || detailed || d['error'] || defaultMessage;
-    }
-    catch {
-        return responseBody || defaultMessage;
-    }
-}
-function throwApiError(response, responseBody, defaultMessage) {
-    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
-}
 function extractTask(data) {
     if (!data || typeof data !== 'object')
         return null;

package/dist/http/grants.d.ts

@@ -11,7 +11,18 @@
  * watermark are presented as `temporal` / `watermark_at` caveats.
  */
 export type GrantHealth = 'active' | 'expired' | 'revoked';
-export type GrantScopeKind = 'chat' | 'agreement' | 'org' | 'connection' | 'wallet';
+/**
+ * The context rail's scope kinds, as VALUES — the type below is derived from
+ * them, so widening the rail is one edit rather than a type change plus however
+ * many hand-written literal lists happen to exist. A literal subset still
+ * typechecks against the union, which is how the CLI's grant listings silently
+ * stopped showing a whole scope kind after `artifact` was added; anything that
+ * means "every context scope" should read this.
+ */
+export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact"];
+/** Every scope kind across every rail: context + connection + payment. */
+export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "connection", "wallet"];
+export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
 export interface GrantScopeView {
     kind: GrantScopeKind;
     id: string;

package/dist/http/grants.js

@@ -1,3 +1,24 @@
+/**
+ * The context rail's scope kinds, as VALUES — the type below is derived from
+ * them, so widening the rail is one edit rather than a type change plus however
+ * many hand-written literal lists happen to exist. A literal subset still
+ * typechecks against the union, which is how the CLI's grant listings silently
+ * stopped showing a whole scope kind after `artifact` was added; anything that
+ * means "every context scope" should read this.
+ */
+export const CONTEXT_GRANT_SCOPE_KINDS = [
+    'chat',
+    'agreement',
+    'org',
+    // ZIG-1037: narrowest context scope
+    'artifact',
+];
+/** Every scope kind across every rail: context + connection + payment. */
+export const GRANT_SCOPE_KINDS = [
+    ...CONTEXT_GRANT_SCOPE_KINDS,
+    'connection',
+    'wallet',
+];
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export function grantCaveat(grant, type) {
     return grant.caveats.find((c) => c.type === type)?.value;

package/dist/http/index.d.ts

@@ -7,15 +7,15 @@ 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';
 export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, DelegateContextGrantResult, ReachEntry, GrantReachResult, } from './ContextGrantsClient.js';
-export { grantCaveat } from './grants.js';
+export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.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, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';

package/dist/http/index.js

@@ -7,11 +7,11 @@ 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';
-export { grantCaveat } from './grants.js';
+export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, } from './OrgsClient.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

@@ -3,9 +3,11 @@ 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 type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -2,8 +2,12 @@ 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.
 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';

package/dist/shared/apiError.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read the message out of a Ziggs error response.
+ *
+ * The API answers every failure in one shape — `{ error: "<what went wrong>" }`,
+ * plus `code` when the server supplied a machine-readable one — because one global
+ * exception filter builds it (backend `common/http-exception.filter.ts`, pinned in
+ * `common/error-response.spec.ts`). So `error` is read first and is normally the
+ * whole answer.
+ *
+ * `message` and `details` remain as fallbacks for responses that did NOT come from
+ * that filter: a proxy, a gateway, or a Nest-shaped body from some other service.
+ * On a Nest-shaped body `error` holds the reason phrase ("Bad Request") while
+ * `message` holds the real cause, so when both are present the more specific one
+ * wins — that ordering is why this lives in ONE place. It used to be copy-pasted
+ * into five clients, two of which had been fixed for it and three of which had not,
+ * 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. */
+export declare function throwApiError(response: {
+    status: number;
+}, responseBody: string, defaultMessage: string): never;

package/dist/shared/apiError.js

@@ -0,0 +1,57 @@
+import { ApiError } from '../types.js';
+/**
+ * Read the message out of a Ziggs error response.
+ *
+ * The API answers every failure in one shape — `{ error: "<what went wrong>" }`,
+ * plus `code` when the server supplied a machine-readable one — because one global
+ * exception filter builds it (backend `common/http-exception.filter.ts`, pinned in
+ * `common/error-response.spec.ts`). So `error` is read first and is normally the
+ * whole answer.
+ *
+ * `message` and `details` remain as fallbacks for responses that did NOT come from
+ * that filter: a proxy, a gateway, or a Nest-shaped body from some other service.
+ * On a Nest-shaped body `error` holds the reason phrase ("Bad Request") while
+ * `message` holds the real cause, so when both are present the more specific one
+ * wins — that ordering is why this lives in ONE place. It used to be copy-pasted
+ * into five clients, two of which had been fixed for it and three of which had not,
+ * so the same failure read differently depending on which client you called.
+ */
+export function parseErrorMessage(responseBody, defaultMessage) {
+    if (!responseBody)
+        return defaultMessage;
+    let parsed;
+    try {
+        parsed = JSON.parse(responseBody);
+    }
+    catch {
+        // Not JSON at all — an HTML error page or a bare string is still better than
+        // nothing, so hand back what the server actually said.
+        return responseBody || defaultMessage;
+    }
+    // Valid JSON that is not an object: a quoted string IS the message; anything
+    // else (null, a number) carries no message, and echoing its raw text would put
+    // "null" in front of a caller.
+    if (typeof parsed !== 'object' || parsed === null) {
+        return typeof parsed === 'string' && parsed ? parsed : defaultMessage;
+    }
+    const body = parsed;
+    const text = (value) => {
+        if (Array.isArray(value)) {
+            const joined = value.map(String).filter(Boolean).join('; ');
+            return joined || undefined;
+        }
+        return typeof value === 'string' && value ? value : undefined;
+    };
+    const error = text(body['error']);
+    const message = text(body['message']);
+    // A Nest-shaped body carries both: prefer the specific `message` over the
+    // reason phrase sitting in `error`.
+    const preferMessage = !!message && !!body['statusCode'];
+    return (text(body['details']) ??
+        (preferMessage ? message : (error ?? message)) ??
+        defaultMessage);
+}
+/** Throw the parsed failure as an {@link ApiError}, preserving status and body. */
+export function throwApiError(response, responseBody, defaultMessage) {
+    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
+}