@ziggs-ai/api-client 0.1.20 → 0.1.22

package/dist/http/AgentSearchClient.d.ts

@@ -34,9 +34,13 @@ export interface AgentProfile {
 }
 export declare class AgentSearchClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId: 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);
     searchAgents(query: string, options?: AgentSearchOptions): Promise<AgentSearchResult>;
     getAgentById(agentId: string): Promise<AgentSearchResult & Partial<AgentProfile>>;
     private _buildHeaders;

package/dist/http/AgentSearchClient.js

@@ -1,15 +1,18 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 export class AgentSearchClient {
     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) {
         if (!operatorKey)
             throw new Error('AgentSearchClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('AgentSearchClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = getBackendUrl();
@@ -63,10 +66,8 @@ export class AgentSearchClient {
         }
     }
     _buildHeaders() {
-        return {
+        return buildOperatorHeaders(this.operatorKey, this.agentId, {
             'Content-Type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
-        };
+        });
     }
 }

package/dist/http/AgreementClient.d.ts

@@ -176,7 +176,11 @@ export declare function linkUserToAgreement(agreementId: string, userId: string,
 export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare class AgreementClient {
     private creds;
-    constructor(operatorKey: string, agentId: 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);
     propose(data: ProposeDirectInput): Promise<Agreement>;
     proposeDirect(data: ProposeDirectInput): Promise<Agreement>;
     proposeBroadcast(data: ProposeBroadcastInput): Promise<Agreement>;

package/dist/http/AgreementClient.js

@@ -289,25 +289,31 @@ export async function getAgreement(agreementId, creds) {
     if (!agreementId)
         return null;
     assertCreds(creds, 'get agreement');
+    // ZIG-698 — a genuine 404 (and 200-with-no-agreement) is a real "not found"
+    // and returns null. Every other failure (403/5xx/network) must throw so the
+    // caller can tell "does not exist" from "could not fetch" instead of a 403
+    // masquerading as not-found. The MCP tool classifies the thrown status via
+    // toolError; the message keeps the status whitespace-delimited for that.
+    let res;
     try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}`, {
+        res = await fetch(`${getAgreementBaseUrl()}/${agreementId}`, {
             method: 'GET',
             headers: buildHeaders(creds),
         });
-        if (res.status === 404)
-            return null;
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return null;
-        }
-        const data = await res.json().catch(() => null);
-        return data?.['agreement'] ?? null;
     }
     catch (e) {
         runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${e.message}`);
+        throw new Error(`GET /agreements/${agreementId} network error: ${e.message}`);
+    }
+    if (res.status === 404)
         return null;
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+        throw new Error(`GET /agreements/${agreementId} ${res.status} ${body?.slice(0, 200)}`);
     }
+    const data = await res.json().catch(() => null);
+    return data?.['agreement'] ?? null;
 }
 export async function createAgreement(body, creds) {
     if (!body)
@@ -551,11 +557,15 @@ export async function getUsersForAgreement(agreementId, creds) {
 }
 export class AgreementClient {
     creds;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('AgreementClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('AgreementClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     propose(data) { return proposeAgreement(data, this.creds); }

package/dist/http/ArtifactsClient.d.ts

@@ -31,8 +31,12 @@ export interface WriteArtifactInput {
  */
 export declare class ArtifactsClient {
     private readonly operatorKey;
-    private readonly agentId;
-    constructor(operatorKey: string, agentId: string);
+    private readonly agentId?;
+    /**
+     * @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);
     list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;
     /**
      * Record an agent thought as an `agent-private` artifact. Replaces the

package/dist/http/ArtifactsClient.js

@@ -1,6 +1,7 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
@@ -9,11 +10,13 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 export class ArtifactsClient {
     operatorKey;
     agentId;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('ArtifactsClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('ArtifactsClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
     }
@@ -81,10 +84,8 @@ export class ArtifactsClient {
         }
     }
     _headers() {
-        return {
+        return buildOperatorHeaders(this.operatorKey, this.agentId, {
             'content-type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
-        };
+        });
     }
 }

package/dist/http/ChatClient.d.ts

@@ -70,7 +70,11 @@ export declare function sendChatMessage(input: SendChatMessageInput, creds: Cred
 export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;
 export declare class ChatClient {
     private creds;
-    constructor(operatorKey: string, agentId: 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);
     open(participantId: string): Promise<{
         chatId: string;
     }>;

package/dist/http/ChatClient.js

@@ -132,11 +132,15 @@ export async function listMyChats(creds) {
 }
 export class ChatClient {
     creds;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('ChatClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('ChatClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     open(participantId) { return openConversation(participantId, this.creds); }

package/dist/http/ContextDiscoveryClient.d.ts

@@ -16,8 +16,12 @@ export interface ContextReachDescriptor {
  */
 export declare class ContextDiscoveryClient {
     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);
     discover(): Promise<ContextReachDescriptor[]>;
 }

package/dist/http/ContextDiscoveryClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * ZIG-412 discovery — scope descriptors only, no content.
  */
@@ -7,23 +8,21 @@ export class ContextDiscoveryClient {
     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('ContextDiscoveryClient: operatorKey is required');
         }
-        if (!agentId) {
-            throw new Error('ContextDiscoveryClient: agentId is required (operator-token impersonation)');
-        }
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
     }
     async discover() {
         const res = await fetch(`${this.baseUrl}/context/discovery`, {
-            headers: {
-                Authorization: `Bearer ${this.operatorKey}`,
-                'X-Agent-Id': this.agentId,
-            },
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {

package/dist/http/ContextGrantsClient.d.ts

@@ -36,9 +36,13 @@ export interface DelegateContextGrantInput {
  */
 export declare class ContextGrantsClient {
     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);
     issueGrant(input: IssueContextGrantInput): Promise<ContextGrantRecord>;
     delegateGrant(parentGrantId: string, input: DelegateContextGrantInput): Promise<ContextGrantRecord>;
     revokeGrant(grantId: string): Promise<{

package/dist/http/ContextGrantsClient.js

@@ -1,19 +1,7 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { ApiError } from '../types.js';
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-    };
-}
-function assertCreds(creds, op) {
-    if (!creds?.operatorKey)
-        throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId)
-        throw new Error(`agentId is required for ${op}`);
-}
+import { buildOperatorHeaders } from './operatorHeaders.js';
 function throwApiError(response, responseBody, defaultMessage) {
     let message = defaultMessage;
     if (responseBody) {
@@ -38,24 +26,23 @@ export class ContextGrantsClient {
     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('ContextGrantsClient: operatorKey is required');
         }
-        if (!agentId) {
-            throw new Error('ContextGrantsClient: agentId is required (operator-token impersonation)');
-        }
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
     }
     async issueGrant(input) {
-        assertCreds({ operatorKey: this.operatorKey, agentId: this.agentId }, 'issueGrant');
         const res = await fetch(`${this.baseUrl}/context/grants`, {
             method: 'POST',
-            headers: buildHeaders({
-                operatorKey: this.operatorKey,
-                agentId: this.agentId,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
             }),
             body: JSON.stringify({
                 holderId: input.holderId,
@@ -75,12 +62,10 @@ export class ContextGrantsClient {
         return parsed.grant;
     }
     async delegateGrant(parentGrantId, input) {
-        assertCreds({ operatorKey: this.operatorKey, agentId: this.agentId }, 'delegateGrant');
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(parentGrantId)}/delegate`, {
             method: 'POST',
-            headers: buildHeaders({
-                operatorKey: this.operatorKey,
-                agentId: this.agentId,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
             }),
             body: JSON.stringify(input),
         });
@@ -95,12 +80,10 @@ export class ContextGrantsClient {
         return parsed.grant;
     }
     async revokeGrant(grantId) {
-        assertCreds({ operatorKey: this.operatorKey, agentId: this.agentId }, 'revokeGrant');
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {
             method: 'DELETE',
-            headers: buildHeaders({
-                operatorKey: this.operatorKey,
-                agentId: this.agentId,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
             }),
         });
         const body = await res.text().catch(() => '');

package/dist/http/MarketplaceClient.d.ts

@@ -40,7 +40,11 @@ export interface PullQuestsOptions {
 export declare function pullQuests(options: PullQuestsOptions | undefined, creds: Creds): Promise<Agreement[]>;
 export declare class MarketplaceClient {
     private creds;
-    constructor(operatorKey: string, agentId: 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);
     publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
     pullOffers(options?: PullOffersOptions): Promise<Agreement[]>;
     claimOffer(agreementId: string): Promise<Agreement>;

package/dist/http/MarketplaceClient.js

@@ -112,11 +112,15 @@ export async function pullQuests(options, creds) {
 }
 export class MarketplaceClient {
     creds;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('MarketplaceClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('MarketplaceClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     publishOffer(payload) { return publishOffer(payload, this.creds); }

package/dist/http/ScopeClient.d.ts

@@ -26,8 +26,12 @@ export interface ScopeResult {
  */
 export declare class ScopeClient {
     private readonly operatorKey;
-    private readonly agentId;
-    constructor(operatorKey: string, agentId: string);
+    private readonly agentId?;
+    /**
+     * @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);
     get(kind: ScopeKind, id: string): Promise<ScopeResult>;
     private _headers;
 }

package/dist/http/ScopeClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * Client for `GET /scope?via=<kind>:<id>`. Returns the access graph reachable
  * from an entry point for the impersonated agent. Used by `runTurn` to
@@ -9,11 +10,13 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 export class ScopeClient {
     operatorKey;
     agentId;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('ScopeClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('ScopeClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
     }
@@ -30,10 +33,8 @@ export class ScopeClient {
         return (await res.json());
     }
     _headers() {
-        return {
+        return buildOperatorHeaders(this.operatorKey, this.agentId, {
             'content-type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
-        };
+        });
     }
 }

package/dist/http/TaskClient.d.ts

@@ -50,7 +50,11 @@ export interface CountTasksFilters {
 export declare function countTasks(filters: CountTasksFilters | undefined, creds: Creds): Promise<number>;
 export declare class TaskClient {
     private creds;
-    constructor(operatorKey: string, agentId: 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);
     createTask(data: CreateTaskData): Promise<Task>;
     getTask(taskId: string): Promise<Task>;
     updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<Task>;

package/dist/http/TaskClient.js

@@ -303,11 +303,15 @@ export async function countTasks(filters = {}, creds) {
 // ---------------------------------------------------------------------------
 export class TaskClient {
     creds;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('TaskClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('TaskClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     createTask(data) { return createTask(data, this.creds); }

package/dist/http/TelemetryClient.d.ts

@@ -1,10 +1,14 @@
 import 'dotenv/config';
 export declare class TelemetryClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private _queue;
     private _flushing;
-    constructor(operatorKey: string, agentId: 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);
     send(payload: unknown): Promise<void>;
     private _flush;
     private _post;

package/dist/http/TelemetryClient.js

@@ -1,16 +1,19 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 export class TelemetryClient {
     operatorKey;
     agentId;
     _queue;
     _flushing;
+    /**
+     * @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) {
         if (!operatorKey)
             throw new Error('TelemetryClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('TelemetryClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this._queue = [];
@@ -34,11 +37,9 @@ export class TelemetryClient {
         try {
             const res = await fetch(url, {
                 method: 'POST',
-                headers: {
+                headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
                     'content-type': 'application/json',
-                    Authorization: `Bearer ${this.operatorKey}`,
-                    'X-Agent-Id': this.agentId,
-                },
+                }),
                 body: JSON.stringify({ payload }),
             });
             if (!res.ok) {

package/dist/http/operatorHeaders.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
+ * 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>;

package/dist/http/operatorHeaders.js

@@ -0,0 +1,12 @@
+/**
+ * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
+ * an agentId is present — agent-scoped keys identify the agent themselves;
+ * fleet keys must pass one (ZIG-642).
+ */
+export function buildOperatorHeaders(operatorKey, agentId, extra) {
+    return {
+        Authorization: `Bearer ${operatorKey}`,
+        ...(agentId ? { 'X-Agent-Id': agentId } : {}),
+        ...extra,
+    };
+}

package/package.json

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