@ziggs-ai/api-client 0.1.3 → 0.1.5

package/dist/http/ChatClient.js

@@ -0,0 +1,104 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+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}`);
+}
+function throwApiError(response, responseBody, defaultMessage) {
+    let message = defaultMessage;
+    if (responseBody) {
+        try {
+            const d = JSON.parse(responseBody);
+            message = d['details'] || d['error'] || d['message'] || defaultMessage;
+        }
+        catch {
+            message = responseBody || defaultMessage;
+        }
+    }
+    throw new ApiError(message, response.status, responseBody);
+}
+export async function openConversation(participantId, creds) {
+    if (!participantId)
+        throw new Error('participantId is required for openConversation');
+    assertCreds(creds, 'open conversation');
+    // Canonical REST: POST /chats with { participantId }, returns { chatId }.
+    const res = await fetch(`${getBackendUrl()}/chats`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ participantId }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `openConversation failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['chatId'] || typeof data['chatId'] !== 'string') {
+        throw new Error('Invalid response: expected { chatId } from POST /chats');
+    }
+    return { chatId: data['chatId'] };
+}
+/**
+ * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * Requires operator token + X-Agent-Id (ZIG-222).
+ */
+export async function sendChatMessage(input, creds) {
+    assertCreds(creds, 'send chat message');
+    const entryType = input.entryType ?? 'message';
+    const contentType = input.contentType ?? 'text';
+    const res = await fetch(`${getBackendUrl()}/chats/${encodeURIComponent(input.chatId)}/messages`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({
+            chatId: input.chatId,
+            messageId: input.messageId,
+            text: input.text,
+            entryType,
+            contentType,
+            receiver: input.receiverId,
+            underAgreementId: input.underAgreementId,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `sendChatMessage failed: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json().catch(() => null));
+    return {
+        success: Boolean(data?.['success']),
+        message: String(data?.['message'] ?? 'ok'),
+        messageId: String(data?.['messageId'] ?? input.messageId),
+        chatId: String(data?.['chatId'] ?? input.chatId),
+    };
+}
+export async function listMyChats(creds) {
+    assertCreds(creds, 'list my chats');
+    try {
+        // Canonical REST: GET /chats/mine.
+        const res = await fetch(`${getBackendUrl()}/chats/mine`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('ChatClient', `⚠️ listMyChats failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['chats']) ? data['chats'] : [];
+    }
+    catch (e) {
+        runtimeLog.warn('ChatClient', `⚠️ listMyChats failed: ${e.message}`);
+        return [];
+    }
+}

package/dist/http/ContextDiscoveryClient.d.ts

@@ -0,0 +1,23 @@
+import 'dotenv/config';
+export interface ContextReachDescriptor {
+    grantId: string;
+    scope: {
+        kind: 'chat' | 'agreement' | 'org';
+        id: string;
+    };
+    temporal: 'from-now' | 'from-start';
+    watermarkAt: string;
+    expiresAt: string | null;
+    parentGrantId: string | null;
+    createdAt: string;
+}
+/**
+ * ZIG-412 discovery — scope descriptors only, no content.
+ */
+export declare class ContextDiscoveryClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId: string, baseUrl?: string);
+    discover(): Promise<ContextReachDescriptor[]>;
+}

package/dist/http/ContextDiscoveryClient.js

@@ -0,0 +1,35 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/**
+ * ZIG-412 discovery — scope descriptors only, no content.
+ */
+export class ContextDiscoveryClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    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,
+            },
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`ContextDiscoveryClient.discover ${res.status} ${body.slice(0, 200)}`);
+        }
+        const parsed = JSON.parse(body);
+        return parsed.reach ?? [];
+    }
+}

package/dist/http/ContextReadClient.d.ts

@@ -0,0 +1,33 @@
+import 'dotenv/config';
+export type ContextReadType = 'messages' | 'artifacts' | 'agreements' | 'tasks';
+export interface ContextReadQuery {
+    via: string;
+    cursor?: string;
+    limit?: number;
+    after?: string;
+    direction?: 'forward';
+    state?: string;
+    contextGrantId?: string;
+}
+export interface ContextReadEnvelope<T = unknown> {
+    type: ContextReadType;
+    via: {
+        kind: string;
+        id: string;
+    };
+    items: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+    latestSequence?: string | null;
+}
+/**
+ * Protocol-first uniform context reads (ZIG-427).
+ * Wraps `GET /context/read/:type` — one client, one envelope, four types.
+ */
+export declare class ContextReadClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId: string, baseUrl?: string);
+    read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
+}

package/dist/http/ContextReadClient.js

@@ -0,0 +1,54 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/**
+ * Protocol-first uniform context reads (ZIG-427).
+ * Wraps `GET /context/read/:type` — one client, one envelope, four types.
+ */
+export class ContextReadClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    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();
+    }
+    async read(type, query) {
+        if (!query.via?.trim()) {
+            throw new Error('ContextReadClient.read: via is required');
+        }
+        const url = new URL(`${this.baseUrl}/context/read/${encodeURIComponent(type)}`);
+        url.searchParams.set('via', query.via.trim());
+        if (query.cursor)
+            url.searchParams.set('cursor', query.cursor);
+        if (query.limit != null)
+            url.searchParams.set('limit', String(query.limit));
+        if (query.after)
+            url.searchParams.set('after', query.after);
+        if (query.direction)
+            url.searchParams.set('direction', query.direction);
+        if (query.state)
+            url.searchParams.set('state', query.state);
+        if (query.contextGrantId) {
+            url.searchParams.set('contextGrantId', query.contextGrantId);
+        }
+        const headers = {
+            Authorization: `Bearer ${this.operatorKey}`,
+            'X-Agent-Id': this.agentId,
+        };
+        if (query.contextGrantId) {
+            headers['X-Context-Grant-Id'] = query.contextGrantId;
+        }
+        const res = await fetch(url.toString(), { headers });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`ContextReadClient.read ${type} ${res.status} ${body.slice(0, 200)}`);
+        }
+        return JSON.parse(body);
+    }
+}

package/dist/http/MarketplaceClient.d.ts

@@ -0,0 +1,19 @@
+import 'dotenv/config';
+import { type Creds, type Agreement } from '../types.js';
+export interface PublishOfferPayload {
+    description: string;
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    /** `hire` = claimer becomes the provider's principal on claim. Defaults to `service` server-side. */
+    engagementKind?: 'hire' | 'service';
+    metadata?: Record<string, unknown>;
+}
+export declare function publishOffer(payload: PublishOfferPayload, creds: Creds): Promise<Agreement>;
+export interface PullOffersOptions {
+    limit?: number;
+    since?: string;
+}
+export declare function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]>;
+export declare function claimOffer(agreementId: string, creds: Creds): Promise<Agreement>;

package/dist/http/MarketplaceClient.js

@@ -0,0 +1,72 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { ApiError } from '../types.js';
+function getMarketplaceBaseUrl() { return `${getBackendUrl()}/marketplace`; }
+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}`);
+}
+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`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(payload || {}),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Marketplace offer publish failed: ${res.status}`);
+    }
+    const data = await res.json().catch(() => null);
+    return (data?.['offer'] ?? data);
+}
+export async function pullOffers(options, creds) {
+    assertCreds(creds, 'marketplace offers pull');
+    const res = await fetch(`${getMarketplaceBaseUrl()}/offers/pull`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(options || {}),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Marketplace offers pull failed: ${res.status}`);
+    }
+    const data = await res.json().catch(() => null);
+    return data?.['offers'] ?? [];
+}
+export async function claimOffer(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required');
+    assertCreds(creds, 'marketplace offer claim');
+    const res = await fetch(`${getMarketplaceBaseUrl()}/offers/claim`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ agreementId }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Marketplace offer claim failed: ${res.status}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['ok'])
+        throw new Error(data?.['error'] || 'Claim failed');
+    return data['offer'];
+}

package/dist/http/MessagesClient.d.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+export interface ListMessagesOptions {
+    /** ISO timestamp; only entries with `timestamp > after` are returned. */
+    after?: string;
+    /** Page size, default 100, hard cap 1000. */
+    limit?: number;
+}
+export interface ListMessagesResult {
+    messages: unknown[];
+    latestSequence: string | null;
+}
+/**
+ * Read-side client for forward-delta message reads.
+ *
+ * Hits the canonical `GET /chats/:chatId/messages?after=&direction=forward&limit=`
+ * endpoint and returns a `{ messages, latestSequence }` envelope
+ * (`chat-messaging.controller.listMessagesForward` →
+ * `MessagesService.listForChat`).
+ */
+export declare class MessagesClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    constructor(operatorKey: string, agentId: string);
+    list(chatId: string, opts?: ListMessagesOptions): Promise<ListMessagesResult>;
+    private _headers;
+}

package/dist/http/MessagesClient.js

@@ -0,0 +1,49 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/**
+ * Read-side client for forward-delta message reads.
+ *
+ * Hits the canonical `GET /chats/:chatId/messages?after=&direction=forward&limit=`
+ * endpoint and returns a `{ messages, latestSequence }` envelope
+ * (`chat-messaging.controller.listMessagesForward` →
+ * `MessagesService.listForChat`).
+ */
+export class MessagesClient {
+    operatorKey;
+    agentId;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('MessagesClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('MessagesClient: agentId is required (operator-token impersonation)');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+    }
+    async list(chatId, opts = {}) {
+        if (!chatId)
+            return { messages: [], latestSequence: null };
+        const url = new URL(`${getBackendUrl()}/chats/${encodeURIComponent(chatId)}/messages`);
+        // Forward-delta read mode. Backend routes to `listMessagesForward`
+        // only when BOTH `after` and `direction=forward` are present; without
+        // `after` the same handler falls into backward pagination and returns
+        // a different envelope. Default `after` to the unix epoch so the
+        // forward branch always wins when callers want "from the beginning".
+        url.searchParams.set('direction', 'forward');
+        url.searchParams.set('after', opts.after || '1970-01-01T00:00:00.000Z');
+        if (opts.limit != null)
+            url.searchParams.set('limit', String(opts.limit));
+        const res = await fetch(url.toString(), { headers: this._headers() });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`MessagesClient.list ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+        }
+        return (await res.json());
+    }
+    _headers() {
+        return {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${this.operatorKey}`,
+            'X-Agent-Id': this.agentId,
+        };
+    }
+}

package/dist/http/ScopeClient.d.ts

@@ -0,0 +1,33 @@
+import 'dotenv/config';
+export type ScopeKind = 'chat' | 'agreement' | 'task' | 'counterparty';
+export interface PartyRef {
+    id: string;
+    role: 'payer' | 'provider' | 'creator' | 'proposedTo' | 'providerPrincipal';
+}
+export interface ScopeResult {
+    via: {
+        kind: ScopeKind;
+        id: string;
+    };
+    agent: string;
+    accessible: {
+        chats: string[];
+        agreements: string[];
+        tasks: string[];
+        counterparties: PartyRef[];
+    };
+    permissions: string[];
+}
+/**
+ * Client for `GET /scope?via=<kind>:<id>`. Returns the access graph reachable
+ * from an entry point for the impersonated agent. Used by `runTurn` to
+ * bootstrap "what does my current session-key resolve to" before fanning out
+ * to primitive reads.
+ */
+export declare class ScopeClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    constructor(operatorKey: string, agentId: string);
+    get(kind: ScopeKind, id: string): Promise<ScopeResult>;
+    private _headers;
+}

package/dist/http/ScopeClient.js

@@ -0,0 +1,39 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.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
+ * bootstrap "what does my current session-key resolve to" before fanning out
+ * to primitive reads.
+ */
+export class ScopeClient {
+    operatorKey;
+    agentId;
+    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;
+    }
+    async get(kind, id) {
+        if (!id)
+            throw new Error('ScopeClient.get: id is required');
+        const url = new URL(`${getBackendUrl()}/scope`);
+        url.searchParams.set('via', `${kind}:${id}`);
+        const res = await fetch(url.toString(), { headers: this._headers() });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`ScopeClient.get ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+        }
+        return (await res.json());
+    }
+    _headers() {
+        return {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${this.operatorKey}`,
+            'X-Agent-Id': this.agentId,
+        };
+    }
+}

package/dist/http/TaskClient.d.ts

@@ -0,0 +1,75 @@
+import 'dotenv/config';
+import { type Creds, type Task, type TaskState, type Agreement } from '../types.js';
+export interface CreateTaskData {
+    description: string;
+    agreementId: string;
+    parentTaskId?: string;
+    plan?: unknown;
+    idempotencyKey?: string;
+}
+export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
+export declare function getTask(taskId: string, creds: Creds): Promise<Task>;
+export interface UpdateTaskStateData {
+    result?: unknown;
+    errorMessage?: string;
+}
+export declare function updateTaskState(taskId: string, state: TaskState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<Task>;
+export declare function getActiveTasksForAgent(agentId: string, creds: Creds): Promise<Task[]>;
+export declare function getActiveTasksForChat(chatId: string, creds: Creds): Promise<Task[]>;
+export declare function cancelTask(taskId: string, creds: Creds): Promise<Task>;
+export declare function getSubtasks(parentTaskId: string, creds: Creds): Promise<Task[]>;
+export interface PlanReplaceStep {
+    stepId: string;
+    description: string;
+    order: number;
+}
+export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<Task>;
+export interface PublishToLedgerPayload {
+    description: string;
+    chatId?: string;
+    payerId?: string;
+    parentTaskId?: string;
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    agreementDescription?: string;
+}
+export declare function publishToLedger(payload: PublishToLedgerPayload, creds: Creds): Promise<Agreement>;
+export interface PullFromLedgerOptions {
+    limit?: number;
+    since?: string;
+}
+export declare function pullFromLedger(options: PullFromLedgerOptions | undefined, creds: Creds): Promise<Agreement[]>;
+export declare function claimLedgerTask(agreementId: string, creds: Creds, options?: {
+    idempotencyKey?: string;
+}): Promise<Agreement>;
+export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<Task>;
+export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<Task>;
+export interface CountTasksFilters {
+    chatId?: string;
+    state?: string;
+    userId?: string;
+    agentId?: string;
+}
+export declare function countTasks(filters: CountTasksFilters | undefined, creds: Creds): Promise<number>;
+export declare class TaskClient {
+    private creds;
+    constructor(operatorKey: string, agentId: string);
+    createTask(data: CreateTaskData): Promise<Task>;
+    getTask(taskId: string): Promise<Task>;
+    updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<Task>;
+    getActiveTasksForAgent(agentId: string): Promise<Task[]>;
+    getActiveTasksForChat(chatId: string): Promise<Task[]>;
+    cancelTask(taskId: string): Promise<Task>;
+    getSubtasks(parentTaskId: string): Promise<Task[]>;
+    replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<Task>;
+    publishToLedger(payload: PublishToLedgerPayload): Promise<Agreement>;
+    pullFromLedger(options?: PullFromLedgerOptions): Promise<Agreement[]>;
+    claimLedgerTask(taskId: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<Agreement>;
+    reportTask(taskId: string, message?: string): Promise<Task>;
+    setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<Task>;
+    countTasks(filters?: CountTasksFilters): Promise<number>;
+}