@ziggs-ai/api-client 0.1.3 → 0.1.4

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,22 @@
+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 `GET /messages?chatId=&after=&limit=`. Replaces the
+ * `history[]` slice of the old context blob.
+ */
+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,41 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/**
+ * Read-side client for `GET /messages?chatId=&after=&limit=`. Replaces the
+ * `history[]` slice of the old context blob.
+ */
+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()}/messages`);
+        url.searchParams.set('chatId', chatId);
+        if (opts.after)
+            url.searchParams.set('after', opts.after);
+        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>;
+}

package/dist/http/TaskClient.js

@@ -0,0 +1,343 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { ApiError } from '../types.js';
+function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
+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 parseErrorMessage(responseBody, defaultMessage) {
+    if (!responseBody)
+        return defaultMessage;
+    try {
+        const d = JSON.parse(responseBody);
+        return d['details'] || d['error'] || d['message'] || 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;
+    const d = data;
+    if (d['task'] && typeof d['task'] === 'object' && d['task']['taskId']) {
+        return d['task'];
+    }
+    if (d['taskId'])
+        return d;
+    return null;
+}
+export async function createTask(taskData, creds) {
+    if (!taskData)
+        throw new Error('Task data is required for task creation');
+    assertCreds(creds, 'task creation');
+    const { idempotencyKey, ...bodyData } = taskData;
+    const headers = buildHeaders(creds);
+    if (idempotencyKey)
+        headers['Idempotency-Key'] = idempotencyKey;
+    const res = await fetch(getTaskBaseUrl(), {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(bodyData),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Task creation failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const task = extractTask(data);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function getTask(taskId, creds) {
+    if (!taskId)
+        throw new Error('getTask: taskId is required');
+    assertCreds(creds, 'task retrieval');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}`, {
+        method: 'GET',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Task get failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const task = extractTask(data);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function updateTaskState(taskId, state, data = {}, creds) {
+    if (!taskId)
+        throw new Error('updateTaskState: taskId is required');
+    if (!state)
+        throw new Error('updateTaskState: state is required');
+    assertCreds(creds, 'task state update');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/state`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ state, ...data }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Task state update failed: ${res.status} ${res.statusText}`);
+    }
+    const result = await res.json().catch(() => null);
+    const task = extractTask(result);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function getActiveTasksForAgent(agentId, creds) {
+    if (!agentId)
+        throw new Error('getActiveTasksForAgent: agentId is required');
+    assertCreds(creds, 'getting active tasks for agent');
+    const url = new URL(`${getBackendUrl()}/agents/${encodeURIComponent(agentId)}/tasks`);
+    url.searchParams.set('state', 'active');
+    const res = await fetch(url.toString(), {
+        method: 'GET',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Get active tasks for agent failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
+}
+// Backend deliberately has no `/chats/:id/tasks` route — it's composable
+// from links → per-agreement tasks. We do the composition here so callers
+// don't have to.
+export async function getActiveTasksForChat(chatId, creds) {
+    if (!chatId)
+        throw new Error('getActiveTasksForChat: chatId is required');
+    assertCreds(creds, 'getting active tasks for chat');
+    const linksRes = await fetch(`${getBackendUrl()}/agreements/by-chat/${encodeURIComponent(chatId)}`, { method: 'GET', headers: buildHeaders(creds) });
+    if (!linksRes.ok) {
+        const body = await linksRes.text().catch(() => '');
+        throwApiError(linksRes, body, `Get agreements for chat failed: ${linksRes.status} ${linksRes.statusText}`);
+    }
+    const linksData = await linksRes.json().catch(() => null);
+    const rawLinks = linksData?.['links'] ?? linksData?.['agreements'];
+    const agreements = Array.isArray(rawLinks) ? rawLinks : [];
+    const agreementIds = Array.from(new Set(agreements.map((a) => a['agreementId']).filter(Boolean)));
+    if (agreementIds.length === 0)
+        return [];
+    const lists = await Promise.all(agreementIds.map(async (aid) => {
+        const url = new URL(`${getBackendUrl()}/agreements/${encodeURIComponent(aid)}/tasks`);
+        url.searchParams.set('state', 'active');
+        const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throwApiError(res, body, `Get tasks for agreement ${aid} failed: ${res.status}`);
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
+    }));
+    return lists.flat();
+}
+export async function cancelTask(taskId, creds) {
+    if (!taskId)
+        throw new Error('cancelTask: taskId is required');
+    assertCreds(creds, 'task cancellation');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/cancel`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Task cancel failed: ${res.status} ${res.statusText}`);
+    }
+    const result = await res.json().catch(() => null);
+    const task = extractTask(result);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function getSubtasks(parentTaskId, creds) {
+    if (!parentTaskId)
+        throw new Error('getSubtasks: parentTaskId is required');
+    assertCreds(creds, 'getting subtasks');
+    const url = new URL(`${getTaskBaseUrl()}/${encodeURIComponent(parentTaskId)}/subtasks`);
+    const res = await fetch(url.toString(), {
+        method: 'GET',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Get subtasks failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
+}
+export async function replaceTaskPlan(taskId, steps, creds) {
+    if (!taskId)
+        throw new Error('replaceTaskPlan: taskId is required');
+    if (!steps || !Array.isArray(steps))
+        throw new Error('replaceTaskPlan: steps must be an array');
+    assertCreds(creds, 'plan replace');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/plan`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ steps }),
+    });
+    if (!res.ok) {
+        const responseBody = await res.text().catch(() => '');
+        throwApiError(res, responseBody, `Plan replace failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const task = extractTask(data);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function publishToLedger(payload, creds) {
+    assertCreds(creds, 'quest publish');
+    const res = await fetch(`${getMarketplaceBaseUrl()}/quests/publish`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(payload || {}),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Quest publish failed: ${res.status}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement'])
+        throw new Error('Quest publish returned no agreement');
+    return data['agreement'];
+}
+export async function pullFromLedger(options, creds) {
+    assertCreds(creds, 'quest pull');
+    const res = await fetch(`${getMarketplaceBaseUrl()}/quests/pull`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(options || {}),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Quest pull failed: ${res.status}`);
+    }
+    const data = await res.json().catch(() => null);
+    return data?.['agreements'] ?? [];
+}
+export async function claimLedgerTask(agreementId, creds, options) {
+    if (!agreementId)
+        throw new Error('agreementId is required');
+    assertCreds(creds, 'quest claim');
+    const headers = buildHeaders(creds);
+    if (options?.idempotencyKey)
+        headers['Idempotency-Key'] = options.idempotencyKey;
+    const res = await fetch(`${getMarketplaceBaseUrl()}/quests/claim`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ agreementId }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Quest claim failed: ${res.status}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['ok'])
+        throw new Error(data?.['error'] || 'Claim failed');
+    return data['agreement'];
+}
+// ---------------------------------------------------------------------------
+// Reporting & satisfaction
+// ---------------------------------------------------------------------------
+export async function reportTask(taskId, message = '', creds) {
+    if (!taskId)
+        throw new Error('reportTask: taskId is required');
+    assertCreds(creds, 'task report');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/report`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ message }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Task report failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const task = extractTask(data);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function setTaskSatisfaction(taskId, satisfaction, creds) {
+    if (!taskId)
+        throw new Error('setTaskSatisfaction: taskId is required');
+    if (!satisfaction)
+        throw new Error('setTaskSatisfaction: satisfaction is required');
+    assertCreds(creds, 'task satisfaction');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/satisfaction`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ satisfaction }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Task satisfaction failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const task = extractTask(data);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
+export async function countTasks(filters = {}, creds) {
+    assertCreds(creds, 'count tasks');
+    const res = await fetch(`${getTaskBaseUrl()}/countTasks`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(filters),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Count tasks failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    return typeof data?.['count'] === 'number' ? data['count'] : 0;
+}
+// ---------------------------------------------------------------------------
+// TaskClient class — bind creds once
+// ---------------------------------------------------------------------------
+export class TaskClient {
+    creds;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('TaskClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('TaskClient: agentId is required');
+        this.creds = { operatorKey, agentId };
+    }
+    createTask(data) { return createTask(data, this.creds); }
+    getTask(taskId) { return getTask(taskId, this.creds); }
+    updateTaskState(taskId, state, data) { return updateTaskState(taskId, state, data ?? {}, this.creds); }
+    getActiveTasksForAgent(agentId) { return getActiveTasksForAgent(agentId, this.creds); }
+    getActiveTasksForChat(chatId) { return getActiveTasksForChat(chatId, this.creds); }
+    cancelTask(taskId) { return cancelTask(taskId, this.creds); }
+    getSubtasks(parentTaskId) { return getSubtasks(parentTaskId, this.creds); }
+    replaceTaskPlan(taskId, steps) { return replaceTaskPlan(taskId, steps, this.creds); }
+    publishToLedger(payload) { return publishToLedger(payload, this.creds); }
+    pullFromLedger(options) { return pullFromLedger(options, this.creds); }
+    claimLedgerTask(taskId, options) { return claimLedgerTask(taskId, this.creds, options); }
+    reportTask(taskId, message) { return reportTask(taskId, message, this.creds); }
+    setTaskSatisfaction(taskId, satisfaction) { return setTaskSatisfaction(taskId, satisfaction, this.creds); }
+    countTasks(filters) { return countTasks(filters, this.creds); }
+}

package/dist/http/TelemetryClient.d.ts

@@ -0,0 +1,11 @@
+import 'dotenv/config';
+export declare class TelemetryClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    private _queue;
+    private _flushing;
+    constructor(operatorKey: string, agentId: string);
+    send(payload: unknown): Promise<void>;
+    private _flush;
+    private _post;
+}