@ziggs-ai/api-client 0.1.3 → 0.1.5

package/src/http/TaskClient.js

@@ -1,612 +0,0 @@
-/**
- * HTTP client for the Tasks API.
- *
- * Every function returns a Task object matching the backend ITask shape:
- * { taskId, description, chatId, agentId, executorId, payerId, contract,
- *   perspective, state, proposal, processing, deleted, result, errorMessage,
- *   createdAt, updatedAt, parentTaskId, rootTaskId, plan, history }
- *
- * ⚠️  SYNC: Field names must match backend/src/tasks/task-core.ts ITask interface.
- */
-
-import 'dotenv/config';
-import { getBackendUrl } from '../utils/urlUtils.js';
-
-const baseUrl = getBackendUrl();
-const TASK_BASE_URL = `${baseUrl}/tasks`;
-
-/**
- * @typedef {{ operatorKey: string, agentId: string }} Creds
- */
-
-function buildHeaders(creds) {
-  const { operatorKey, agentId } = creds || {};
-  if (!operatorKey) {
-    throw new Error('operatorKey is required for task service requests');
-  }
-  if (!agentId) {
-    throw new Error('agentId is required for task service requests (operator-token impersonation)');
-  }
-  return {
-    'content-type': 'application/json',
-    Authorization: `Bearer ${operatorKey}`,
-    'X-Agent-Id': 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}`);
-}
-
-/**
- * Parse error message from API response.
- * Checks for details, error, or message fields in JSON response.
- * Falls back to raw body or default message.
- */
-function parseErrorMessage(responseBody, defaultMessage) {
-  if (!responseBody) return defaultMessage;
-  try {
-    const errorData = JSON.parse(responseBody);
-    return errorData.details || errorData.error || errorData.message || defaultMessage;
-  } catch {
-    return responseBody || defaultMessage;
-  }
-}
-
-function throwApiError(response, responseBody, defaultMessage) {
-  const errorMessage = parseErrorMessage(responseBody, defaultMessage);
-  const error = new Error(errorMessage);
-  error.status = response.status;
-  error.body = responseBody;
-  throw error;
-}
-
-/**
- * Extract the Task object from an API response.
- * Handles both shapes: `{ task: {...} }` (POST /tasks, PATCH) and direct task (GET, proposal endpoints).
- * @returns {Object|null} The task object, or null if not found.
- */
-function extractTask(data) {
-  if (!data) return null;
-  // Wrapped: { status: '...', task: { taskId, ... } }
-  if (data.task && data.task.taskId) return data.task;
-  // Direct: { taskId, description, ... }
-  if (data.taskId) return data;
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// CRUD
-// ---------------------------------------------------------------------------
-
-/**
- * Create a standalone task (state='active').
- * POST /tasks
- *
- * @param {Object} taskData
- * @param {string}  taskData.description
- * @param {string}  [taskData.chatId]
- * @param {string}  [taskData.executorId]
- * @param {string}  [taskData.payerId]
- * @param {string}  [taskData.parentTaskId]
- * @param {Object}  [taskData.contract]
- * @param {Object}  [taskData.perspective]
- * @param {Object}  [taskData.plan]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} Task object
- */
-export async function createTask(taskData, creds) {
-  if (!taskData) throw new Error('Task data is required for task creation');
-  assertCreds(creds, 'task creation');
-
-  const res = await fetch(`${TASK_BASE_URL}`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify(taskData),
-  });
-
-  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;
-}
-
-/**
- * Get a single task by ID.
- * GET /tasks/:taskId
- *
- * @param {string} taskId
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Task object or null
- */
-export async function getTask(taskId, creds) {
-  if (!taskId) return null;
-  assertCreds(creds, 'task retrieval');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}`, {
-      method: 'GET',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task get failed: ${res.status} ${res.statusText} ${body}`);
-      return null;
-    }
-
-    const data = await res.json().catch(() => null);
-    return extractTask(data);
-  } catch (e) {
-    console.warn(`⚠️ Task get failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Update a task's state.
- * PATCH /tasks/:taskId/state
- *
- * Valid transitions (enforced by backend):
- *   proposal → active | cancelled
- *   active   → completed | failed | cancelled
- *
- * @param {string} taskId
- * @param {'proposal'|'active'|'completed'|'failed'|'cancelled'} state
- * @param {Object} [data]
- * @param {*}      [data.result]
- * @param {string} [data.errorMessage]
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Updated task or null
- */
-export async function updateTaskState(taskId, state, data = {}, creds) {
-  if (!taskId || !state) return null;
-  assertCreds(creds, 'task state update');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/state`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-      body: JSON.stringify({ state, ...data }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task state update failed: ${res.status} ${res.statusText} ${body}`);
-      return null;
-    }
-
-    const result = await res.json().catch(() => null);
-    return extractTask(result);
-  } catch (e) {
-    console.warn(`⚠️ Task state update failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Get active tasks, optionally filtered by chatId and/or agentId.
- * GET /tasks?state=active[&chatId=...][&agentId=...]
- *
- * @param {string|null} chatId
- * @param {string}      operatorKey
- * @param {string|null} [agentId]
- * @returns {Promise<Object[]>} Array of Task objects
- */
-export async function getActiveTasks(chatId = null, creds, filterAgentId = null) {
-  assertCreds(creds, 'getting active tasks');
-
-  try {
-    const url = new URL(`${TASK_BASE_URL}`);
-    url.searchParams.set('state', 'active');
-    if (chatId) url.searchParams.set('chatId', chatId);
-    if (filterAgentId) url.searchParams.set('agentId', filterAgentId);
-
-    const res = await fetch(url.toString(), {
-      method: 'GET',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Get active tasks failed: ${res.status} ${res.statusText} ${body}`);
-      return [];
-    }
-
-    const data = await res.json().catch(() => null);
-    return Array.isArray(data?.tasks) ? data.tasks : [];
-  } catch (e) {
-    console.warn(`⚠️ Get active tasks failed: ${e.message}`);
-    return [];
-  }
-}
-
-/**
- * Acquire or release the atomic processing lock on a task.
- * PATCH /tasks/:taskId/processing
- *
- * @param {string}  taskId
- * @param {boolean} processing - true to acquire, false to release
- * @param {string}  operatorKey
- * @returns {Promise<{acquired: boolean, task: Object|null}>}
- */
-export async function markTaskProcessing(taskId, processing, creds) {
-  if (!taskId) return { acquired: false, task: null };
-  assertCreds(creds, 'task processing lock');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/processing`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-      body: JSON.stringify({ processing }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task processing lock failed: ${res.status} ${res.statusText} ${body}`);
-      return { acquired: false, task: null };
-    }
-
-    const data = await res.json().catch(() => null);
-    return {
-      acquired: data?.acquired ?? false,
-      task: data?.task || null,
-    };
-  } catch (e) {
-    console.warn(`⚠️ Task processing lock failed: ${e.message}`);
-    return { acquired: false, task: null };
-  }
-}
-
-/**
- * Cancel a task (transitions to state='cancelled').
- * PATCH /tasks/:taskId/cancel
- *
- * @param {string} taskId
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Cancelled task or null
- */
-export async function cancelTask(taskId, creds) {
-  if (!taskId) return null;
-  assertCreds(creds, 'task cancellation');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/cancel`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task cancel failed: ${res.status} ${res.statusText} ${body}`);
-      return null;
-    }
-
-    const result = await res.json().catch(() => null);
-    return extractTask(result);
-  } catch (e) {
-    console.warn(`⚠️ Task cancel failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Get subtasks for a parent task.
- * GET /tasks?parentTaskId=...
- *
- * @param {string} parentTaskId
- * @param {string} operatorKey
- * @returns {Promise<Object[]>} Array of Task objects
- */
-export async function getSubtasks(parentTaskId, creds) {
-  if (!parentTaskId) return [];
-  assertCreds(creds, 'getting subtasks');
-
-  try {
-    const url = new URL(`${TASK_BASE_URL}`);
-    url.searchParams.set('parentTaskId', parentTaskId);
-
-    const res = await fetch(url.toString(), {
-      method: 'GET',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Get subtasks failed: ${res.status} ${res.statusText} ${body}`);
-      return [];
-    }
-
-    const data = await res.json().catch(() => null);
-    return Array.isArray(data?.tasks) ? data.tasks : [];
-  } catch (e) {
-    console.warn(`⚠️ Get subtasks failed: ${e.message}`);
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Proposal workflow
-// ---------------------------------------------------------------------------
-
-/**
- * Propose work to a user or agent for approval.
- * POST /tasks/proposeToDoWork
- *
- * Creates a task with state='proposal', proposal.status='pending'.
- *
- * @param {Object} proposalData
- * @param {string}  proposalData.description
- * @param {string}  proposalData.proposedTo     - userId or agentId to approve
- * @param {string}  proposalData.chatId
- * @param {Object}  [proposalData.contract]
- * @param {Object}  [proposalData.perspective]
- * @param {string}  [proposalData.parentTaskId]
- * @param {string}  [proposalData.payerId]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function proposeToDoWork(proposalData, creds) {
-  if (!proposalData) throw new Error('Proposal data is required for proposal creation');
-  assertCreds(creds, 'proposal creation');
-
-  const { description, proposedTo, chatId, contract, perspective, parentTaskId, payerId } = proposalData;
-  const res = await fetch(`${baseUrl}/tasks/proposeToDoWork`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ description, proposedTo, chatId, contract, perspective, parentTaskId, payerId }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Proposal creation failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: proposal data not found');
-  return task;
-}
-
-/**
- * Assign task directly (no proposal step). Requires parentTaskId.
- * POST /tasks/assignTask
- *
- * Creates a task with state='active' immediately.
- *
- * @param {Object} assignData
- * @param {string}  assignData.description
- * @param {string}  assignData.executorId
- * @param {string}  assignData.chatId
- * @param {string}  assignData.parentTaskId     - required (proves user approval)
- * @param {Object}  [assignData.contract]
- * @param {Object}  [assignData.perspective]
- * @param {string}  [assignData.payerId]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function assignTask(assignData, creds) {
-  if (!assignData) throw new Error('Assign data is required');
-  assertCreds(creds, 'task assignment');
-
-  const { description, executorId, chatId, contract, perspective, parentTaskId, payerId } = assignData;
-  const res = await fetch(`${baseUrl}/tasks/assignTask`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ description, executorId, chatId, contract, perspective, parentTaskId, payerId }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Task assignment failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: assignment data not found');
-  return task;
-}
-
-/**
- * Delegate task to another agent (creates proposal to executor). Requires parentTaskId.
- * POST /tasks/delegateToAgent
- *
- * Creates a task with state='proposal', proposedTo=executorId.
- *
- * @param {Object} proposalData
- * @param {string}  proposalData.description
- * @param {string}  proposalData.executorId
- * @param {string}  proposalData.chatId
- * @param {string}  proposalData.parentTaskId   - required (proves user approval)
- * @param {Object}  [proposalData.contract]
- * @param {Object}  [proposalData.perspective]
- * @param {string}  [proposalData.payerId]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function delegateToAgent(proposalData, creds) {
-  if (!proposalData) throw new Error('Proposal data is required for delegation');
-  assertCreds(creds, 'proposal creation');
-
-  const { description, executorId, chatId, contract, perspective, parentTaskId, payerId } = proposalData;
-  const res = await fetch(`${baseUrl}/tasks/delegateToAgent`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ description, executorId, chatId, contract, perspective, parentTaskId, payerId }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Delegation failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: delegation data not found');
-  return task;
-}
-
-/**
- * Update a plan step within a task.
- * PATCH /tasks/:taskId/plan
- *
- * @param {string} taskId
- * @param {string} stepId
- * @param {'pending'|'in_progress'|'completed'|'skipped'} status
- * @param {*}      [result]
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Updated task or null
- */
-export async function updatePlanStep(taskId, stepId, status, result, creds) {
-  if (!taskId || !stepId || !status) return null;
-  assertCreds(creds, 'plan step update');
-
-  try {
-    const body = { stepId, status };
-    if (result !== undefined) body.result = result;
-
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/plan`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-      body: JSON.stringify(body),
-    });
-
-    if (!res.ok) {
-      const responseBody = await res.text().catch(() => '');
-      console.warn(`⚠️ Plan step update failed: ${res.status} ${res.statusText} ${responseBody}`);
-      return null;
-    }
-
-    const data = await res.json().catch(() => null);
-    return extractTask(data);
-  } catch (e) {
-    console.warn(`⚠️ Plan step update failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Respond to a proposal — approve or reject.
- * POST /tasks/respondToProposal
- *
- * approve: state proposal→active, proposal.status='approved'
- * reject:  state proposal→cancelled, proposal.status='rejected'
- *
- * @param {string} taskId
- * @param {'approve'|'reject'} action
- * @param {string} operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function respondToProposal(taskId, action, creds) {
-  if (!taskId || !action) throw new Error('Task ID and action are required for proposal response');
-  assertCreds(creds, 'proposal response');
-
-  const res = await fetch(`${baseUrl}/tasks/respondToProposal`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ taskId, action }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Proposal response failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: proposal response data not found');
-  return task;
-}
-
-// ---------------------------------------------------------------------------
-// Shared Task Ledger (Pub/Sub)
-// ---------------------------------------------------------------------------
-
-/**
- * Publish a task to the shared ledger (open for any agent to pull/claim).
- * POST /tasks/ledger/publish
- *
- * Creates a task with state='proposal', proposal.proposedTo='everyone'.
- *
- * @param {Object} payload
- * @param {string}  payload.description
- * @param {string}  [payload.chatId]
- * @param {string}  [payload.payerId]
- * @param {string}  [payload.parentTaskId]
- * @param {Object}  [payload.contract]
- * @param {Object}  [payload.perspective]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} Task object
- */
-export async function publishToLedger(payload, creds) {
-  assertCreds(creds, 'ledger publish');
-  const res = await fetch(`${TASK_BASE_URL}/ledger/publish`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify(payload || {}),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Ledger publish failed: ${res.status}`);
-  }
-  const data = await res.json().catch(() => null);
-  return extractTask(data);
-}
-
-/**
- * Pull open tasks from the ledger (for agents to accept/ignore or claim).
- * POST /tasks/ledger/pull
- *
- * @param {Object}  [options]
- * @param {number}  [options.limit]   - max tasks to return (default 50, max 100)
- * @param {string}  [options.since]   - ISO date string, only return tasks created after this
- * @param {string}  operatorKey
- * @returns {Promise<Object[]>} Array of Task objects
- */
-export async function pullFromLedger(options, creds) {
-  const headers = buildHeaders(creds);
-  const res = await fetch(`${TASK_BASE_URL}/ledger/pull`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify(options || {}),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Ledger pull failed: ${res.status}`);
-  }
-  const data = await res.json().catch(() => null);
-  return data?.tasks ?? [];
-}
-
-/**
- * Claim a ledger task so only this agent works on it.
- * POST /tasks/ledger/claim
- *
- * Atomically sets executorId and transitions state proposal→active.
- *
- * @param {string} taskId
- * @param {string} operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function claimLedgerTask(taskId, creds) {
-  if (!taskId) throw new Error('taskId is required');
-  assertCreds(creds, 'ledger claim');
-  const res = await fetch(`${TASK_BASE_URL}/ledger/claim`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ taskId }),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Ledger claim failed: ${res.status}`);
-  }
-  const data = await res.json().catch(() => null);
-  if (!data?.ok) throw new Error(data?.error || 'Claim failed');
-  return data.task;
-}

package/src/http/index.js

@@ -1,6 +0,0 @@
-// HTTP API Clients
-export * from './TaskClient.js';
-export { ContextReader } from './ContextReader.js';
-export { ContextWriter } from './ContextWriter.js';
-export { AgentSearchClient } from './AgentSearchClient.js';
-export { TelemetryClient } from './TelemetryClient.js';

package/src/types.js

@@ -1,28 +0,0 @@
-/**
- * Type constants for the Ziggs API
- * These types are used when interacting with the backend timeline/history API
- */
-
-// Entry Types (entryType) - The kind of timeline entry
-export const EntryTypes = {
-  MESSAGE: 'message',
-  NOTIFICATION: 'notification',
-  ARTIFACT: 'artifact',
-  TASK_HISTORY: 'task_history',
-};
-
-// Content Types (content_type) - The type of content within an entry
-export const ContentTypes = {
-  TEXT: 'text',
-  OPERATION: 'operation',
-  CONTEXT: 'context',
-  RESULT: 'result',
-  TASK_UPDATE: 'task_update',
-  THOUGHT: 'thought',
-};
-
-/**
- * Open ledger proposals: proposal.proposedTo === this value means any agent can claim (approve).
- * ⚠️  SYNC: Keep in sync with backend/src/tasks/task-core.ts and agent-sdk/src/tasks/taskCore.js
- */
-export const OPEN_PROPOSAL_TARGET = 'everyone';

package/src/utils/urlUtils.js

@@ -1,17 +0,0 @@
-/**
- * Gets the HTTP backend URL from HTTP_URL env var or defaults to api.ziggsai.com
- */
-export function getBackendUrl() {
-  const url = process.env.HTTP_URL || 'https://api.ziggsai.com';
-  // Ensure it has a protocol
-  return url.startsWith('http') ? url : `https://${url}`;
-}
-
-/**
- * Gets the WebSocket URL from WS_URL env var or defaults to wss://api.ziggsai.com
- */
-export function getWebSocketUrl() {
-  const wsUrl = process.env.WS_URL || 'wss://api.ziggsai.com';
-  // Ensure it has a protocol
-  return wsUrl.startsWith('ws') ? wsUrl : `wss://${wsUrl}`;
-}