@ziggs-ai/api-client 0.1.3 → 0.1.5

package/dist/http/TaskClient.js

@@ -0,0 +1,352 @@
+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');
+    // Canonical REST: GET /tasks/count.
+    const url = new URL(`${getTaskBaseUrl()}/count`);
+    if (filters.chatId)
+        url.searchParams.set('chatId', filters.chatId);
+    if (filters.state)
+        url.searchParams.set('state', filters.state);
+    if (filters.userId)
+        url.searchParams.set('userId', filters.userId);
+    if (filters.agentId)
+        url.searchParams.set('agentId', filters.agentId);
+    const res = await fetch(url.toString(), {
+        method: 'GET',
+        headers: buildHeaders(creds),
+    });
+    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;
+}

package/dist/http/TelemetryClient.js

@@ -0,0 +1,53 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+export class TelemetryClient {
+    operatorKey;
+    agentId;
+    _queue;
+    _flushing;
+    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 = [];
+        this._flushing = false;
+    }
+    async send(payload) {
+        this._queue.push(payload);
+        if (!this._flushing)
+            this._flush();
+    }
+    async _flush() {
+        this._flushing = true;
+        while (this._queue.length > 0) {
+            const batch = this._queue.splice(0, 10);
+            await Promise.allSettled(batch.map((p) => this._post(p)));
+        }
+        this._flushing = false;
+    }
+    async _post(payload) {
+        const url = `${getBackendUrl()}/agents/monitoring/ingest`;
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    Authorization: `Bearer ${this.operatorKey}`,
+                    'X-Agent-Id': this.agentId,
+                },
+                body: JSON.stringify({ payload }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                runtimeLog.warn('TelemetryClient', `⚠️ ingest failed agent=${this.agentId} ${res.status} ${res.statusText} body=${body.slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            runtimeLog.warn('TelemetryClient', `⚠️ ingest error agent=${this.agentId} message=${err.message}`);
+        }
+    }
+}

package/dist/http/index.d.ts

@@ -0,0 +1,16 @@
+export * from './TaskClient.js';
+export * from './AgreementClient.js';
+export * from './MarketplaceClient.js';
+export * from './ChatClient.js';
+export { MessagesClient } from './MessagesClient.js';
+export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
+export { ArtifactsClient } from './ArtifactsClient.js';
+export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
+export { ScopeClient } from './ScopeClient.js';
+export type { ScopeKind, ScopeResult, PartyRef } from './ScopeClient.js';
+export { ContextReadClient } from './ContextReadClient.js';
+export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, } from './ContextReadClient.js';
+export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
+export type { ContextReachDescriptor } from './ContextDiscoveryClient.js';
+export { AgentSearchClient } from './AgentSearchClient.js';
+export { TelemetryClient } from './TelemetryClient.js';

package/dist/http/index.js

@@ -0,0 +1,11 @@
+export * from './TaskClient.js';
+export * from './AgreementClient.js';
+export * from './MarketplaceClient.js';
+export * from './ChatClient.js';
+export { MessagesClient } from './MessagesClient.js';
+export { ArtifactsClient } from './ArtifactsClient.js';
+export { ScopeClient } from './ScopeClient.js';
+export { ContextReadClient } from './ContextReadClient.js';
+export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
+export { AgentSearchClient } from './AgentSearchClient.js';
+export { TelemetryClient } from './TelemetryClient.js';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './http/index.js';
+export { WebSocketClient } from './websocket/index.js';
+export { createControlSocket } from './websocket/ControlSocket.js';
+export { ConnectionManager } from './ConnectionManager.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
+export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
+export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/{src → dist}/index.js

@@ -1,17 +1,7 @@
-// Main entry point for @ziggs-ai/api-client
-
-// HTTP Clients
 export * from './http/index.js';
-
-// WebSocket Client
 export { WebSocketClient } from './websocket/index.js';
 export { createControlSocket } from './websocket/ControlSocket.js';
-
-// Connection management (optional — generic pool + control socket)
 export { ConnectionManager } from './ConnectionManager.js';
-
-// Types
-export { EntryTypes, ContentTypes } from './types.js';
-
-// Utilities
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/shared/runtimeLog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
+ * here so this package stays dependency-free).
+ *
+ * @see agent-sdk/src/shared/runtimeLog.ts
+ */
+export type RuntimeLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function resetRuntimeLogLevelCache(): void;
+export declare const runtimeLog: {
+    debug(scope: string, msg: string, ...rest: unknown[]): void;
+    info(scope: string, msg: string, ...rest: unknown[]): void;
+    warn(scope: string, msg: string, ...rest: unknown[]): void;
+    error(scope: string, msg: string, ...rest: unknown[]): void;
+};

package/dist/shared/runtimeLog.js

@@ -0,0 +1,64 @@
+/**
+ * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
+ * here so this package stays dependency-free).
+ *
+ * @see agent-sdk/src/shared/runtimeLog.ts
+ */
+const SEVERITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function parseThreshold() {
+    if (process.env.DEBUG_AGENTPLUS === '1' || process.env.AGENTPLUS_DEBUG === '1') {
+        return SEVERITY.debug;
+    }
+    const raw = (process.env.LOG_LEVEL ||
+        process.env.AGENTPLUS_LOG_LEVEL ||
+        'info').toLowerCase();
+    if (raw === 'silent' || raw === 'none')
+        return SEVERITY.error;
+    if (raw === 'debug' || raw === 'trace')
+        return SEVERITY.debug;
+    if (raw === 'warn')
+        return SEVERITY.warn;
+    if (raw === 'error')
+        return SEVERITY.error;
+    return SEVERITY.info;
+}
+let cachedThreshold = null;
+function threshold() {
+    if (cachedThreshold === null)
+        cachedThreshold = parseThreshold();
+    return cachedThreshold;
+}
+export function resetRuntimeLogLevelCache() {
+    cachedThreshold = null;
+}
+function shouldEmit(level) {
+    return SEVERITY[level] >= threshold();
+}
+function fmt(scope, msg) {
+    return `[${scope}] ${msg}`;
+}
+export const runtimeLog = {
+    debug(scope, msg, ...rest) {
+        if (!shouldEmit('debug'))
+            return;
+        console.log(fmt(scope, msg), ...rest);
+    },
+    info(scope, msg, ...rest) {
+        if (!shouldEmit('info'))
+            return;
+        console.log(fmt(scope, msg), ...rest);
+    },
+    warn(scope, msg, ...rest) {
+        if (!shouldEmit('warn'))
+            return;
+        console.warn(fmt(scope, msg), ...rest);
+    },
+    error(scope, msg, ...rest) {
+        console.error(fmt(scope, msg), ...rest);
+    },
+};