@ziggs-ai/api-client 0.1.4 → 0.1.5

package/src/http/ArtifactsClient.ts

@@ -0,0 +1,133 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+
+export type ArtifactVisibility = 'chat' | 'agent-private';
+
+export interface ListArtifactsOptions {
+  after?: string;
+  limit?: number;
+}
+
+export interface ListArtifactsQuery {
+  chatId?: string;
+  agreementId?: string;
+}
+
+export interface ListArtifactsResult {
+  artifacts: unknown[];
+  latestSequence: string | null;
+}
+
+export interface WriteArtifactInput {
+  text: string;
+  content_type?: string;
+  visibility?: ArtifactVisibility;
+  /** When the artifact is associated with a chat. */
+  chatId?: string;
+  /** When the artifact is associated with an agreement (and optionally a task). */
+  agreementId?: string;
+  taskId?: string;
+  service?: Record<string, unknown>;
+}
+
+/**
+ * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
+ * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
+ * they persist, are searchable, but are not visible to other chat parties.
+ */
+export class ArtifactsClient {
+  private readonly operatorKey: string;
+  private readonly agentId: string;
+
+  constructor(operatorKey: string, agentId: string) {
+    if (!operatorKey) throw new Error('ArtifactsClient: operatorKey is required');
+    if (!agentId)
+      throw new Error(
+        'ArtifactsClient: agentId is required (operator-token impersonation)',
+      );
+    this.operatorKey = operatorKey;
+    this.agentId = agentId;
+  }
+
+  async list(
+    q: ListArtifactsQuery,
+    opts: ListArtifactsOptions = {},
+  ): Promise<ListArtifactsResult> {
+    if ((q.chatId && q.agreementId) || (!q.chatId && !q.agreementId)) {
+      throw new Error(
+        'ArtifactsClient.list: pass exactly one of chatId or agreementId',
+      );
+    }
+    const url = new URL(`${getBackendUrl()}/artifacts`);
+    if (q.chatId) url.searchParams.set('chatId', q.chatId);
+    if (q.agreementId) url.searchParams.set('agreementId', q.agreementId);
+    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(
+        `ArtifactsClient.list ${res.status} ${res.statusText} ${body.slice(0, 200)}`,
+      );
+    }
+    return (await res.json()) as ListArtifactsResult;
+  }
+
+  /**
+   * Record an agent thought as an `agent-private` artifact. Replaces the
+   * `ContextWriter.recordEvent({ kind: 'thought' })` hack.
+   *
+   * Note: the artifact write endpoint lives in the existing chat/agreement
+   * write paths; this helper is the SDK contract. Until the backend write
+   * endpoint is updated to accept `visibility`, this falls back to logging
+   * locally (operators can still wire their own sink).
+   */
+  async recordThought(chatId: string, text: string): Promise<void> {
+    return this.write({
+      chatId,
+      text,
+      content_type: 'thought',
+      visibility: 'agent-private',
+    });
+  }
+
+  async write(input: WriteArtifactInput): Promise<void> {
+    if (!input.text || !input.text.trim()) return;
+    if ((input.chatId && input.agreementId) || (!input.chatId && !input.agreementId)) {
+      throw new Error(
+        'ArtifactsClient.write: pass exactly one of chatId or agreementId',
+      );
+    }
+    const url = `${getBackendUrl()}/artifacts`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify({
+        text: input.text.trim(),
+        content_type: input.content_type ?? 'text',
+        visibility: input.visibility ?? 'chat',
+        chatId: input.chatId,
+        agreementId: input.agreementId,
+        taskId: input.taskId,
+        service: input.service,
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      // Soft-fail: artifact writes are breadcrumbs, not load-bearing.
+      runtimeLog.warn(
+        'ArtifactsClient',
+        `⚠️ write failed ${res.status} ${res.statusText} ${body.slice(0, 200)}`,
+      );
+    }
+  }
+
+  private _headers(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      Authorization: `Bearer ${this.operatorKey}`,
+      'X-Agent-Id': this.agentId,
+    };
+  }
+}

package/src/http/ChatClient.ts

@@ -0,0 +1,147 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { type Creds, ApiError } from '../types.js';
+
+function buildHeaders(creds: Creds): Record<string, string> {
+  return {
+    'content-type': 'application/json',
+    Authorization: `Bearer ${creds.operatorKey}`,
+    'X-Agent-Id': creds.agentId,
+  };
+}
+
+function assertCreds(creds: Creds | undefined | null, op: string): asserts creds is Creds {
+  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: Response, responseBody: string, defaultMessage: string): never {
+  let message = defaultMessage;
+  if (responseBody) {
+    try {
+      const d = JSON.parse(responseBody) as Record<string, unknown>;
+      message = (d['details'] as string) || (d['error'] as string) || (d['message'] as string) || defaultMessage;
+    } catch { message = responseBody || defaultMessage; }
+  }
+  throw new ApiError(message, response.status, responseBody);
+}
+
+export interface ChatSummary {
+  chatId: string;
+  userIds?: string[];
+  agentIds?: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  [key: string]: unknown;
+}
+
+export async function openConversation(
+  participantId: string,
+  creds: Creds,
+): Promise<{ chatId: string }> {
+  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) as Record<string, unknown> | null;
+  if (!data?.['chatId'] || typeof data['chatId'] !== 'string') {
+    throw new Error('Invalid response: expected { chatId } from POST /chats');
+  }
+  return { chatId: data['chatId'] as string };
+}
+
+export interface SendChatMessageInput {
+  chatId: string;
+  receiverId: string;
+  text: string;
+  messageId: string;
+  entryType?: string;
+  contentType?: string;
+  underAgreementId?: string;
+}
+
+export interface SendChatMessageResult {
+  success: boolean;
+  message: string;
+  messageId: string;
+  chatId: string;
+}
+
+/**
+ * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * Requires operator token + X-Agent-Id (ZIG-222).
+ */
+export async function sendChatMessage(
+  input: SendChatMessageInput,
+  creds: Creds,
+): Promise<SendChatMessageResult> {
+  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)) as Record<string, unknown> | 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: Creds): Promise<ChatSummary[]> {
+  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) as Record<string, unknown> | null;
+    return Array.isArray(data?.['chats']) ? (data['chats'] as ChatSummary[]) : [];
+  } catch (e) {
+    runtimeLog.warn('ChatClient', `⚠️ listMyChats failed: ${(e as Error).message}`);
+    return [];
+  }
+}

package/src/http/ContextDiscoveryClient.ts

@@ -0,0 +1,52 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+
+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 class ContextDiscoveryClient {
+  private readonly operatorKey: string;
+  private readonly agentId: string;
+  private readonly baseUrl: string;
+
+  constructor(operatorKey: string, agentId: string, baseUrl?: string) {
+    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(): Promise<ContextReachDescriptor[]> {
+    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) as { reach?: ContextReachDescriptor[] };
+    return parsed.reach ?? [];
+  }
+}

package/src/http/ContextReadClient.ts

@@ -0,0 +1,83 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+
+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 class ContextReadClient {
+  private readonly operatorKey: string;
+  private readonly agentId: string;
+  private readonly baseUrl: string;
+
+  constructor(operatorKey: string, agentId: string, baseUrl?: string) {
+    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<T = unknown>(
+    type: ContextReadType,
+    query: ContextReadQuery,
+  ): Promise<ContextReadEnvelope<T>> {
+    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: Record<string, string> = {
+      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) as ContextReadEnvelope<T>;
+  }
+}

package/src/http/MarketplaceClient.ts

@@ -0,0 +1,94 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { type Creds, type Agreement, ApiError } from '../types.js';
+
+function getMarketplaceBaseUrl(): string { return `${getBackendUrl()}/marketplace`; }
+
+function buildHeaders(creds: Creds): Record<string, string> {
+  return {
+    'content-type': 'application/json',
+    Authorization: `Bearer ${creds.operatorKey}`,
+    'X-Agent-Id': creds.agentId,
+  };
+}
+
+function assertCreds(creds: Creds | undefined | null, op: string): asserts creds is Creds {
+  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: Response, body: string, defaultMsg: string): never {
+  let msg = defaultMsg;
+  try {
+    const d = JSON.parse(body) as Record<string, unknown>;
+    msg = (d['details'] as string) || (d['error'] as string) || (d['message'] as string) || defaultMsg;
+  } catch { /**/ }
+  throw new ApiError(msg, response.status);
+}
+
+// ---------------------------------------------------------------------------
+// Seller-broadcast offers
+// ---------------------------------------------------------------------------
+
+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 async function publishOffer(payload: PublishOfferPayload, creds: Creds): Promise<Agreement> {
+  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) as Record<string, unknown> | null;
+  return (data?.['offer'] ?? data) as Agreement;
+}
+
+export interface PullOffersOptions {
+  limit?: number;
+  since?: string;
+}
+
+export async function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]> {
+  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) as Record<string, unknown> | null;
+  return (data?.['offers'] as Agreement[]) ?? [];
+}
+
+export async function claimOffer(agreementId: string, creds: Creds): Promise<Agreement> {
+  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) as Record<string, unknown> | null;
+  if (!data?.['ok']) throw new Error((data?.['error'] as string) || 'Claim failed');
+  return data['offer'] as Agreement;
+}

package/src/http/MessagesClient.ts

@@ -0,0 +1,71 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+
+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 class MessagesClient {
+  private readonly operatorKey: string;
+  private readonly agentId: string;
+
+  constructor(operatorKey: string, agentId: string) {
+    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: string,
+    opts: ListMessagesOptions = {},
+  ): Promise<ListMessagesResult> {
+    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()) as ListMessagesResult;
+  }
+
+  private _headers(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      Authorization: `Bearer ${this.operatorKey}`,
+      'X-Agent-Id': this.agentId,
+    };
+  }
+}

package/src/http/ScopeClient.ts

@@ -0,0 +1,64 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+
+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 class ScopeClient {
+  private readonly operatorKey: string;
+  private readonly agentId: string;
+
+  constructor(operatorKey: string, agentId: string) {
+    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: ScopeKind, id: string): Promise<ScopeResult> {
+    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()) as ScopeResult;
+  }
+
+  private _headers(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      Authorization: `Bearer ${this.operatorKey}`,
+      'X-Agent-Id': this.agentId,
+    };
+  }
+}