@pingagent/sdk 0.1.7 → 0.1.9

package/src/client.ts

@@ -1,582 +0,0 @@
-import type { Envelope, ApiResponse, TaskState, InboxBoxType } from '@pingagent/schemas';
-import { SCHEMA_TASK, SCHEMA_CONTACT_REQUEST, SCHEMA_RESULT, SCHEMA_RECEIPT, SCHEMA_TEXT } from '@pingagent/schemas';
-import {
-  type Identity,
-  buildUnsignedEnvelope,
-  signEnvelope,
-  generateArtifactRef,
-} from '@pingagent/protocol';
-import { HttpTransport } from './transport.js';
-import type { LocalStore } from './store.js';
-import { ContactManager } from './contacts.js';
-import { HistoryManager, type StoredMessage } from './history.js';
-
-export interface ClientOptions {
-  serverUrl: string;
-  identity: Identity;
-  accessToken: string;
-  mode?: 'long-running' | 'one-shot';
-  onTokenRefreshed?: (token: string, expiresAt: number) => void;
-  store?: LocalStore;
-}
-
-export interface SendResponse {
-  message_id: string;
-  seq: number;
-  receipt: { status: string; reason?: string; server_ts_ms: number };
-}
-
-export interface FetchResponse {
-  messages: any[];
-  next_since_seq: number;
-  has_more: boolean;
-}
-
-export interface TaskResult {
-  status: 'ok' | 'error';
-  task_id: string;
-  result?: { summary?: string; artifacts?: any[]; structured_data?: any };
-  error?: { code: string; message: string };
-  elapsed_ms: number;
-}
-
-export interface SubscriptionUsage {
-  relay_today: number;
-  relay_limit: number;
-  artifact_bytes: number;
-  artifact_limit_bytes: number;
-  alias_count: number;
-  alias_limit: number;
-}
-
-export interface SubscriptionResponse {
-  tier: string;
-  limits: { relay_per_day: number; max_group_size: number; artifact_storage_mb: number; audit_export_allowed: boolean; alias_limit: number };
-  usage: SubscriptionUsage;
-  has_stripe_customer: boolean;
-}
-
-export interface ConversationEntry {
-  conversation_id: string;
-  type: string;
-  target_did: string;
-  trusted: boolean;
-  created_at: number;
-  /** Server-side last message write time (ms). Omitted or null when unknown; client should fetch when missing. */
-  last_activity_at?: number | null;
-}
-
-export interface ConversationListResponse {
-  conversations: ConversationEntry[];
-}
-
-export interface AgentProfile {
-  did: string;
-  alias?: string;
-  display_name?: string;
-  bio?: string;
-  capabilities?: string[];
-  tags?: string[];
-  verification_status?: string;
-  discoverable?: boolean;
-}
-
-export interface DirectoryBrowseResponse {
-  agents: AgentProfile[];
-  total?: number;
-}
-
-export interface FeedPost {
-  post_id: string;
-  text: string;
-  artifact_ref?: string | null;
-  ts_ms: number;
-}
-
-export interface FeedPublicResponse {
-  posts: Array<FeedPost & { did: string }>;
-  next_since?: number;
-}
-
-export interface FeedByDidResponse {
-  did: string;
-  posts: FeedPost[];
-}
-
-export class PingAgentClient {
-  private transport: HttpTransport;
-  private identity: Identity;
-  private contactManager?: ContactManager;
-  private historyManager?: HistoryManager;
-
-  constructor(private opts: ClientOptions) {
-    this.identity = opts.identity;
-    this.transport = new HttpTransport({
-      serverUrl: opts.serverUrl,
-      accessToken: opts.accessToken,
-      onTokenRefreshed: opts.onTokenRefreshed,
-    });
-    if (opts.store) {
-      this.contactManager = new ContactManager(opts.store);
-      this.historyManager = new HistoryManager(opts.store);
-    }
-  }
-
-  getContactManager(): ContactManager | undefined { return this.contactManager; }
-  getHistoryManager(): HistoryManager | undefined { return this.historyManager; }
-
-  /** Update the in-memory access token (e.g. after proactive refresh from disk). */
-  setAccessToken(token: string): void {
-    this.transport.setToken(token);
-  }
-
-  async register(developerToken?: string): Promise<ApiResponse> {
-    let binary = '';
-    for (const b of this.identity.publicKey) binary += String.fromCharCode(b);
-    const publicKeyBase64 = btoa(binary);
-
-    return this.transport.request('POST', '/v1/agent/register', {
-      device_id: this.identity.deviceId,
-      public_key: publicKeyBase64,
-      developer_token: developerToken,
-    }, true);
-  }
-
-  async openConversation(targetDid: string): Promise<ApiResponse<{
-    conversation_id: string;
-    type: string;
-    trusted: boolean;
-    relay_ws_url: string;
-  }>> {
-    return this.transport.request('POST', '/v1/conversations/open', {
-      targets: [targetDid],
-    });
-  }
-
-  async sendMessage(
-    conversationId: string,
-    schema: string,
-    payload: Record<string, unknown>,
-  ): Promise<ApiResponse<SendResponse>> {
-    const ttlMs = schema === SCHEMA_TEXT ? 604_800_000 : undefined; // 7 days for chat, default 24h for others
-    const unsigned = buildUnsignedEnvelope({
-      type: 'message',
-      conversationId,
-      senderDid: this.identity.did,
-      senderDeviceId: this.identity.deviceId,
-      schema,
-      payload,
-      ttlMs,
-    });
-    const signed = signEnvelope(unsigned, this.identity.privateKey);
-    const res = await this.transport.request<SendResponse>('POST', '/v1/messages/send', signed);
-
-    if (res.ok && this.historyManager) {
-      this.historyManager.save([{
-        conversation_id: conversationId,
-        message_id: signed.message_id,
-        seq: res.data?.seq,
-        sender_did: this.identity.did,
-        schema,
-        payload,
-        ts_ms: signed.ts_ms,
-        direction: 'sent',
-      }]);
-    }
-
-    return res;
-  }
-
-  async sendTask(
-    conversationId: string,
-    task: { task_id: string; title: string; description?: string; input?: any; timeout_ms?: number },
-  ): Promise<ApiResponse<SendResponse>> {
-    return this.sendMessage(conversationId, SCHEMA_TASK, {
-      ...task,
-      idempotency_key: task.task_id,
-      expected_output_schema: SCHEMA_RESULT,
-    });
-  }
-
-  async sendContactRequest(
-    conversationId: string,
-    message?: string,
-  ): Promise<ApiResponse<SendResponse>> {
-    const { v7: uuidv7 } = await import('uuid');
-    return this.sendMessage(conversationId, SCHEMA_CONTACT_REQUEST, {
-      request_id: `r_${uuidv7()}`,
-      from_did: this.identity.did,
-      to_did: '',
-      capabilities: ['task', 'result', 'files'],
-      message,
-      expires_ms: 86400000,
-    });
-  }
-
-  async fetchInbox(
-    conversationId: string,
-    opts?: { sinceSeq?: number; limit?: number; box?: InboxBoxType },
-  ): Promise<ApiResponse<FetchResponse>> {
-    const params = new URLSearchParams({
-      conversation_id: conversationId,
-      since_seq: String(opts?.sinceSeq ?? 0),
-      limit: String(opts?.limit ?? 50),
-      box: opts?.box ?? 'ready',
-    });
-    const res = await this.transport.request<FetchResponse>('GET', `/v1/inbox/fetch?${params}`);
-
-    if (res.ok && res.data && this.historyManager) {
-      const msgs: StoredMessage[] = res.data.messages.map((msg: any) => ({
-        conversation_id: conversationId,
-        message_id: msg.message_id,
-        seq: msg.seq,
-        sender_did: msg.sender_did,
-        schema: msg.schema,
-        payload: msg.payload,
-        ts_ms: msg.ts_ms,
-        direction: msg.sender_did === this.identity.did ? 'sent' as const : 'received' as const,
-      }));
-      if (msgs.length > 0) {
-        this.historyManager.save(msgs);
-        const maxSeq = Math.max(...msgs.map(m => m.seq ?? 0));
-        if (maxSeq > 0) this.historyManager.setLastSyncedSeq(conversationId, maxSeq);
-      }
-    }
-
-    return res;
-  }
-
-  async ack(
-    conversationId: string,
-    forMessageId: string,
-    status: string,
-    opts?: { forTaskId?: string; reason?: string; detail?: Record<string, unknown> },
-  ): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/receipts/ack', {
-      conversation_id: conversationId,
-      for_message_id: forMessageId,
-      for_task_id: opts?.forTaskId,
-      status,
-      reason: opts?.reason,
-      detail: opts?.detail,
-    });
-  }
-
-  async approveContact(conversationId: string): Promise<ApiResponse<{ trusted: boolean; dm_conversation_id?: string }>> {
-    const res = await this.transport.request<{ trusted: boolean; dm_conversation_id?: string }>('POST', '/v1/control/approve_contact', {
-      conversation_id: conversationId,
-    });
-
-    if (res.ok && this.contactManager) {
-      const pendingMessages = this.historyManager?.list(conversationId, { limit: 1 });
-      const senderDid = pendingMessages?.[0]?.sender_did;
-      if (senderDid && senderDid !== this.identity.did) {
-        this.contactManager.add({
-          did: senderDid,
-          conversation_id: res.data?.dm_conversation_id ?? conversationId,
-          trusted: true,
-        });
-      }
-    }
-
-    return res;
-  }
-
-  async revokeConversation(conversationId: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/control/revoke_conversation', {
-      conversation_id: conversationId,
-    });
-  }
-
-  async cancelTask(conversationId: string, taskId: string): Promise<ApiResponse<{ task_state: TaskState }>> {
-    return this.transport.request('POST', '/v1/control/cancel_task', {
-      conversation_id: conversationId,
-      task_id: taskId,
-    });
-  }
-
-  async blockSender(conversationId: string, senderDid: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/control/block_sender', {
-      conversation_id: conversationId,
-      sender_did: senderDid,
-    });
-  }
-
-  async acquireLease(conversationId: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/lease/acquire', {
-      conversation_id: conversationId,
-    });
-  }
-
-  async renewLease(conversationId: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/lease/renew', {
-      conversation_id: conversationId,
-    });
-  }
-
-  async releaseLease(conversationId: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/lease/release', {
-      conversation_id: conversationId,
-    });
-  }
-
-  async uploadArtifact(content: Buffer): Promise<{ artifact_ref: string; sha256: string; size: number }> {
-    const presignRes = await this.transport.request<any>('POST', '/v1/artifacts/presign_upload', {
-      size: content.length,
-      content_type: 'application/octet-stream',
-    });
-
-    if (!presignRes.ok || !presignRes.data) throw new Error('Failed to presign upload');
-
-    const { upload_url, artifact_ref } = presignRes.data;
-
-    await this.transport.fetchWithAuth(upload_url, {
-      method: 'PUT',
-      body: content,
-      contentType: 'application/octet-stream',
-    });
-
-    const { createHash } = await import('node:crypto');
-    const hash = createHash('sha256').update(content).digest('hex');
-
-    return { artifact_ref, sha256: hash, size: content.length };
-  }
-
-  async downloadArtifact(artifactRef: string, expectedSha256: string, expectedSize: number): Promise<Buffer> {
-    const presignRes = await this.transport.request<any>('POST', '/v1/artifacts/presign_download', {
-      artifact_ref: artifactRef,
-    });
-
-    if (!presignRes.ok || !presignRes.data) throw new Error('Failed to presign download');
-
-    const buffer = Buffer.from(await this.transport.fetchWithAuth(presignRes.data.download_url));
-
-    if (buffer.length !== expectedSize) {
-      throw new Error(`Size mismatch: expected ${expectedSize}, got ${buffer.length}`);
-    }
-
-    const { createHash } = await import('node:crypto');
-    const hash = createHash('sha256').update(buffer).digest('hex');
-    if (hash !== expectedSha256) {
-      throw new Error(`SHA256 mismatch: expected ${expectedSha256}, got ${hash}`);
-    }
-
-    return buffer;
-  }
-
-  async getSubscription(): Promise<ApiResponse<SubscriptionResponse>> {
-    return this.transport.request<SubscriptionResponse>('GET', '/v1/subscription');
-  }
-
-  async resolveAlias(alias: string): Promise<ApiResponse<{ did: string; alias: string }>> {
-    return this.transport.request('GET', `/v1/directory/resolve?alias=${encodeURIComponent(alias)}`);
-  }
-
-  async registerAlias(alias: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/directory/alias', { alias });
-  }
-
-  async listConversations(opts?: { type?: string }): Promise<ApiResponse<ConversationListResponse>> {
-    const params = new URLSearchParams();
-    if (opts?.type) params.set('type', opts.type);
-    const qs = params.toString();
-    return this.transport.request('GET', `/v1/conversations/list${qs ? '?' + qs : ''}`);
-  }
-
-  async getProfile(): Promise<ApiResponse<AgentProfile>> {
-    return this.transport.request('GET', '/v1/directory/profile');
-  }
-
-  async updateProfile(profile: { display_name?: string; bio?: string; capabilities?: string[]; tags?: string[]; discoverable?: boolean }): Promise<ApiResponse<AgentProfile>> {
-    return this.transport.request('POST', '/v1/directory/profile', profile);
-  }
-
-  async enableDiscovery(): Promise<ApiResponse<{ discoverable: boolean }>> {
-    return this.transport.request('POST', '/v1/directory/enable_discovery');
-  }
-
-  async disableDiscovery(): Promise<ApiResponse<{ discoverable: boolean }>> {
-    return this.transport.request('POST', '/v1/directory/disable_discovery');
-  }
-
-  async browseDirectory(opts?: { tag?: string; query?: string; limit?: number; offset?: number; sort?: 'default' | 'updated' }): Promise<ApiResponse<DirectoryBrowseResponse>> {
-    const params = new URLSearchParams();
-    if (opts?.tag) params.set('tag', opts.tag);
-    if (opts?.query) params.set('q', opts.query);
-    if (opts?.limit != null) params.set('limit', String(opts.limit));
-    if (opts?.offset != null) params.set('offset', String(opts.offset));
-    if (opts?.sort) params.set('sort', opts.sort);
-    const qs = params.toString();
-    return this.transport.request('GET', `/v1/directory/browse${qs ? '?' + qs : ''}`);
-  }
-
-  async publishPost(opts: { text: string; artifact_ref?: string }): Promise<ApiResponse<{ post_id: string; ts_ms: number }>> {
-    return this.transport.request('POST', '/v1/feed/publish', { text: opts.text, artifact_ref: opts.artifact_ref });
-  }
-
-  async listFeedPublic(opts?: { limit?: number; since?: number }): Promise<ApiResponse<FeedPublicResponse>> {
-    const params = new URLSearchParams();
-    if (opts?.limit != null) params.set('limit', String(opts.limit));
-    if (opts?.since != null) params.set('since', String(opts.since));
-    const qs = params.toString();
-    return this.transport.request('GET', `/v1/feed/public${qs ? '?' + qs : ''}`, undefined, true);
-  }
-
-  async listFeedByDid(did: string, opts?: { limit?: number }): Promise<ApiResponse<FeedByDidResponse>> {
-    const params = new URLSearchParams({ did });
-    if (opts?.limit != null) params.set('limit', String(opts.limit));
-    return this.transport.request('GET', `/v1/feed/by_did?${params.toString()}`, undefined, true);
-  }
-
-  async createChannel(opts: { name: string; alias?: string; description?: string; discoverable?: boolean }): Promise<
-    ApiResponse<{ conversation_id: string; alias: string; name: string; discoverable: boolean; relay_ws_url: string }>
-  > {
-    return this.transport.request('POST', '/v1/channels/create', {
-      name: opts.name,
-      alias: opts.alias,
-      description: opts.description,
-      join_policy: 'open',
-      discoverable: opts.discoverable,
-    });
-  }
-
-  async updateChannel(opts: { alias: string; name?: string; description?: string; discoverable?: boolean }): Promise<
-    ApiResponse<{ alias: string; name: string; description?: string | null; discoverable: boolean }>
-  > {
-    const alias = opts.alias.replace(/^@ch\//, '');
-    return this.transport.request('PATCH', '/v1/channels/update', {
-      alias,
-      name: opts.name,
-      description: opts.description,
-      discoverable: opts.discoverable,
-    });
-  }
-
-  async deleteChannel(alias: string): Promise<ApiResponse<{ deleted: boolean; alias: string }>> {
-    const a = alias.replace(/^@ch\//, '');
-    return this.transport.request('DELETE', '/v1/channels/delete', { alias: a });
-  }
-
-  async discoverChannels(opts?: { limit?: number; query?: string }): Promise<
-    ApiResponse<{ channels: Array<{ alias: string; name: string; description?: string | null; owner_did: string }> }>
-  > {
-    const params = new URLSearchParams();
-    if (opts?.limit != null) params.set('limit', String(opts.limit));
-    if (opts?.query) params.set('q', opts.query);
-    const qs = params.toString();
-    return this.transport.request('GET', `/v1/channels/discover${qs ? '?' + qs : ''}`, undefined, true);
-  }
-
-  async joinChannel(alias: string): Promise<
-    ApiResponse<{ conversation_id: string; alias: string; owner_did: string; relay_ws_url: string }>
-  > {
-    return this.transport.request('POST', '/v1/channels/join', { alias });
-  }
-
-  getDid(): string {
-    return this.identity.did;
-  }
-
-  // === Billing: device linking ===
-
-  async createBillingLinkCode(): Promise<ApiResponse<{ code: string; expires_in_seconds: number }>> {
-    return this.transport.request('POST', '/v1/billing/link-code');
-  }
-
-  async redeemBillingLink(code: string): Promise<ApiResponse<{ primary_did: string }>> {
-    return this.transport.request('POST', '/v1/billing/link', { code });
-  }
-
-  async unlinkBillingDevice(did: string): Promise<ApiResponse> {
-    return this.transport.request('POST', '/v1/billing/unlink', { did });
-  }
-
-  async getLinkedDevices(): Promise<ApiResponse<{ primary_did: string; linked_dids: string[]; is_primary: boolean }>> {
-    return this.transport.request('GET', '/v1/billing/linked-devices');
-  }
-
-  // P0: High-level send-task-and-wait
-  async sendTaskAndWait(
-    targetDid: string,
-    task: { title: string; description?: string; input?: any },
-    opts?: { timeoutMs?: number; pollIntervalMs?: number },
-  ): Promise<TaskResult> {
-    const { v7: uuidv7 } = await import('uuid');
-    const timeout = opts?.timeoutMs ?? 120_000;
-    const pollInterval = opts?.pollIntervalMs ?? 2_000;
-    const taskId = `t_${uuidv7()}`;
-    const startTime = Date.now();
-
-    // Step 1: open conversation
-    const openRes = await this.openConversation(targetDid);
-    if (!openRes.ok || !openRes.data) {
-      return { status: 'error', task_id: taskId, error: { code: 'E_OPEN_FAILED', message: 'Failed to open conversation' }, elapsed_ms: Date.now() - startTime };
-    }
-
-    let conversationId = openRes.data.conversation_id;
-
-    // Step 2: if not trusted, send contact_request and wait
-    if (!openRes.data.trusted) {
-      await this.sendContactRequest(conversationId, task.title);
-
-      // Poll for approval
-      const approvalDeadline = startTime + timeout;
-      while (Date.now() < approvalDeadline) {
-        await sleep(pollInterval);
-        const reopen = await this.openConversation(targetDid);
-        if (reopen.ok && reopen.data?.trusted) {
-          conversationId = reopen.data.conversation_id;
-          break;
-        }
-      }
-
-      if (Date.now() >= approvalDeadline) {
-        return { status: 'error', task_id: taskId, error: { code: 'E_NOT_APPROVED', message: 'Contact request not approved within timeout' }, elapsed_ms: Date.now() - startTime };
-      }
-    }
-
-    // Step 3: send task
-    const sendRes = await this.sendTask(conversationId, { task_id: taskId, ...task });
-    if (!sendRes.ok) {
-      return { status: 'error', task_id: taskId, error: { code: sendRes.error?.code ?? 'E_SEND_FAILED', message: sendRes.error?.message ?? 'Send failed' }, elapsed_ms: Date.now() - startTime };
-    }
-
-    const sinceSeq = sendRes.data?.seq ?? 0;
-
-    // Step 4: poll for result
-    const deadline = startTime + timeout;
-    while (Date.now() < deadline) {
-      await sleep(pollInterval);
-
-      const fetchRes = await this.fetchInbox(conversationId, { sinceSeq });
-      if (!fetchRes.ok || !fetchRes.data) continue;
-
-      for (const msg of fetchRes.data.messages) {
-        if (msg.schema === SCHEMA_RESULT && msg.payload?.task_id === taskId) {
-          return {
-            status: msg.payload.status === 'ok' ? 'ok' : 'error',
-            task_id: taskId,
-            result: msg.payload.output,
-            error: msg.payload.error,
-            elapsed_ms: Date.now() - startTime,
-          };
-        }
-
-        if (msg.schema === SCHEMA_RECEIPT && msg.payload?.for_task_id === taskId && msg.payload?.status === 'failed') {
-          return {
-            status: 'error',
-            task_id: taskId,
-            error: { code: msg.payload.reason ?? 'E_TASK_FAILED', message: msg.payload.reason ?? 'Task failed' },
-            elapsed_ms: Date.now() - startTime,
-          };
-        }
-      }
-    }
-
-    return { status: 'error', task_id: taskId, error: { code: 'E_TIMEOUT', message: `No result within ${timeout}ms` }, elapsed_ms: timeout };
-  }
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}