@ziggs-ai/api-client 0.1.8 → 0.1.10

package/dist/http/ContextReadClient.d.ts

@@ -26,8 +26,12 @@ export interface ContextReadEnvelope<T = unknown> {
  */
 export declare class ContextReadClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId: string, baseUrl?: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
 }

package/dist/http/ContextReadClient.js

@@ -8,12 +8,13 @@ export class ContextReadClient {
     operatorKey;
     agentId;
     baseUrl;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId, baseUrl) {
         if (!operatorKey)
             throw new Error('ContextReadClient: operatorKey is required');
-        if (!agentId) {
-            throw new Error('ContextReadClient: agentId is required (operator-token impersonation)');
-        }
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
@@ -39,8 +40,9 @@ export class ContextReadClient {
         }
         const headers = {
             Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
         };
+        if (this.agentId)
+            headers['X-Agent-Id'] = this.agentId;
         if (query.contextGrantId) {
             headers['X-Context-Grant-Id'] = query.contextGrantId;
         }

package/dist/http/InboxClient.d.ts

@@ -0,0 +1,66 @@
+import 'dotenv/config';
+export type InboxScopeKind = 'chat' | 'agreement' | 'org';
+export interface InboxScopeEntry {
+    scope: {
+        kind: InboxScopeKind;
+        id: string;
+    };
+    newMessages: number;
+    newArtifacts: number;
+    latestAt: string | null;
+    since: string;
+}
+export interface InboxProposalRef {
+    agreementId: string;
+    title: string;
+    proposedAt: string | null;
+}
+/** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482). */
+export interface InboxHumanAttention {
+    required: true;
+    reason: 'proposals_awaiting_me';
+    proposalCount: number;
+    truncatedProposals: number;
+    promptUser: string;
+}
+export interface InboxEnvelope {
+    asOf: string;
+    scopes: InboxScopeEntry[];
+    truncatedScopes: number;
+    countCap: number;
+    proposalsAwaitingMe: InboxProposalRef[];
+    truncatedProposals: number;
+    humanAttention?: InboxHumanAttention;
+}
+export interface InboxAck {
+    kind: InboxScopeKind;
+    id: string;
+    upTo: string;
+}
+export interface InboxAckResult {
+    acked: Array<{
+        scope: {
+            kind: InboxScopeKind;
+            id: string;
+        };
+        ackedUpTo: string;
+    }>;
+}
+/**
+ * The doorbell, not the door (ZIG-434): references and counts since the
+ * agent's last ack — never content. Flow: inbox → read → act → ack (ZIG-446).
+ * Wraps `GET /agent-api/v1/inbox` and `POST /agent-api/v1/inbox/ack`.
+ */
+export declare class InboxClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    private headers;
+    getInbox(): Promise<InboxEnvelope>;
+    ack(scopes: InboxAck[]): Promise<InboxAckResult>;
+}

package/dist/http/InboxClient.js

@@ -0,0 +1,56 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/**
+ * The doorbell, not the door (ZIG-434): references and counts since the
+ * agent's last ack — never content. Flow: inbox → read → act → ack (ZIG-446).
+ * Wraps `GET /agent-api/v1/inbox` and `POST /agent-api/v1/inbox/ack`.
+ */
+export class InboxClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey)
+            throw new Error('InboxClient: operatorKey is required');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    headers() {
+        const headers = {
+            Authorization: `Bearer ${this.operatorKey}`,
+            'Content-Type': 'application/json',
+        };
+        if (this.agentId)
+            headers['X-Agent-Id'] = this.agentId;
+        return headers;
+    }
+    async getInbox() {
+        const res = await fetch(`${this.baseUrl}/agent-api/v1/inbox`, {
+            headers: this.headers(),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`InboxClient.getInbox ${res.status} ${body.slice(0, 200)}`);
+        }
+        return JSON.parse(body);
+    }
+    async ack(scopes) {
+        if (!scopes.length)
+            throw new Error('InboxClient.ack: scopes are required');
+        const res = await fetch(`${this.baseUrl}/agent-api/v1/inbox/ack`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ scopes }),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`InboxClient.ack ${res.status} ${body.slice(0, 200)}`);
+        }
+        return JSON.parse(body);
+    }
+}

package/dist/http/index.d.ts

@@ -16,3 +16,5 @@ export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, } from './ContextGrantsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
+export { InboxClient } from './InboxClient.js';
+export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxEnvelope, InboxAck, InboxAckResult, } from './InboxClient.js';

package/dist/http/index.js

@@ -10,3 +10,4 @@ export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
+export { InboxClient } from './InboxClient.js';

package/dist/types.d.ts

@@ -99,6 +99,8 @@ export declare function isValidContentType(contentType: string, entryType: strin
 export declare const OPEN_AGREEMENT_TARGET: "everyone";
 export interface MessageMetadata {
     chatId: string;
+    /** Stable id for dedup across push + inbox catch-up (ZIG-454). */
+    messageId?: string;
     userId: string;
     sender: {
         id: string;

package/dist/websocket/WebSocketClient.d.ts

@@ -41,6 +41,8 @@ export interface SendOptions {
      * Requires backend streaming support.
      */
     partial?: boolean;
+    /** Pre-allocated messageId for streaming continuity — links chunks to the final message. */
+    messageId?: string;
 }
 export declare class WebSocketClient {
     private wsUrl;
@@ -60,6 +62,13 @@ export declare class WebSocketClient {
      * `event.kind` + ids. Replaces cursor-based polling for delta detection.
      */
     setResourceEventHandler(handler: ResourceEventHandler): void;
+    private connectHandlers;
+    /**
+     * Called on every socket connect, including socket.io reconnects.
+     * Used for inbox catch-up (ZIG-454) so missed pushes are recovered from MongoDB.
+     */
+    onConnect(handler: () => void | Promise<void>): void;
+    private _emitConnect;
     private _connect;
     connectAsync(timeout?: number): Promise<this>;
     disconnect(): void;

package/dist/websocket/WebSocketClient.js

@@ -33,6 +33,25 @@ export class WebSocketClient {
     setResourceEventHandler(handler) {
         this.resourceEventHandler = handler;
     }
+    connectHandlers = [];
+    /**
+     * Called on every socket connect, including socket.io reconnects.
+     * Used for inbox catch-up (ZIG-454) so missed pushes are recovered from MongoDB.
+     */
+    onConnect(handler) {
+        this.connectHandlers.push(handler);
+    }
+    async _emitConnect() {
+        for (const handler of this.connectHandlers) {
+            try {
+                await handler();
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                runtimeLog.warn(this.label, `connect handler error: ${msg}`);
+            }
+        }
+    }
     _connect() {
         if (this.socket?.connected)
             return;
@@ -41,6 +60,7 @@ export class WebSocketClient {
         this.socket = io(this.wsUrl, socketOptions);
         this.socket.on('connect', () => {
             runtimeLog.info(this.label, 'Connected');
+            void this._emitConnect();
         });
         this.socket.on('connect_error', (error) => {
             runtimeLog.error(this.label, `Connection error: ${error.message}`);
@@ -119,7 +139,7 @@ export class WebSocketClient {
             throw new Error('send: socket is not initialized. Call connect() first.');
         if (!this.socket.connected)
             throw new Error('send: socket is not connected. Call connect() and wait for connection.');
-        const messageId = this.generateMessageId();
+        const messageId = options.messageId ?? this.generateMessageId();
         if (!messageId || typeof messageId !== 'string')
             throw new Error('send: failed to generate valid messageId');
         const message = {
@@ -174,6 +194,7 @@ export class WebSocketClient {
         runtimeLog.info(this.label, `[wire-debug] incoming chatId=${chatId} sender=${senderId} content_type=${p['content_type'] ?? p['contentType'] ?? '<none>'} entryType=${p['entryType'] ?? '<none>'} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'} operation?=${operation ?? 'no'}`);
         const metadata = {
             chatId,
+            messageId: typeof p['messageId'] === 'string' ? p['messageId'] : undefined,
             userId: senderId,
             sender: { id: senderId, type: senderType },
             senderId,

package/package.json

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