@pingagent/sdk 0.1.7 → 0.1.9

package/src/ws-subscription.ts

@@ -1,428 +0,0 @@
-/**
- * WebSocket subscription for real-time inbox messages.
- * Connects to Gateway /v1/ws per conversation and receives ws_message pushes.
- */
-
-import WebSocket from 'ws';
-import type { ConversationEntry } from './client.js';
-
-export interface WsControlPayload {
-  action: string;
-  target?: string;
-}
-
-export interface WsSubscriptionOptions {
-  serverUrl: string;
-  getAccessToken: () => string | Promise<string>;
-  myDid: string;
-  listConversations: () => Promise<ConversationEntry[]>;
-  onMessage: (envelope: any, conversationId: string) => void;
-  onControl?: (control: WsControlPayload, conversationId: string) => void;
-  onError?: (err: Error) => void;
-  /** Optional debug hook for observability (non-fatal events). */
-  onDebug?: (info: { event: string; conversationId?: string; detail?: Record<string, unknown> }) => void;
-  /** Called when a WebSocket opens or reopens; e.g. Skill can run catchUp to fill gaps. */
-  onOpen?: (conversationId: string) => void;
-  /**
-   * When true (default), drop ws_message envelopes sent by myself (sender_did === myDid).
-   * Set to false when you intentionally run multiple devices/processes under the same DID and want cross-device delivery.
-   */
-  ignoreSelfMessages?: boolean;
-
-  /**
-   * Keepalive heartbeat for idle connections to reduce "WS silently dropped" periods.
-   * This is client-side only (WS ping/pong control frames) and does not add inbox HTTP fetch cost.
-   */
-  heartbeat?: {
-    enable?: boolean;
-    /** If idle time >= this value, start pinging. */
-    idleThresholdMs?: number;
-    /** Minimum interval between pings while connection is idle. */
-    pingIntervalMs?: number;
-    /** How long to wait for pong after sending ping. If timeout, close the socket. */
-    pongTimeoutMs?: number;
-    /** Max consecutive missed pongs before closing. */
-    maxMissedPongs?: number;
-    /** Heartbeat scheduler tick frequency. */
-    tickMs?: number;
-    /** Jitter for ping interval to avoid synchronized bursts across many connections. */
-    jitter?: number;
-  };
-}
-
-const RECONNECT_BASE_MS = 1000;
-const RECONNECT_MAX_MS = 30_000;
-const RECONNECT_JITTER = 0.2;
-const LIST_CONVERSATIONS_INTERVAL_MS = 60_000;
-
-const DEFAULT_HEARTBEAT = {
-  enable: true,
-  idleThresholdMs: 10_000,
-  pingIntervalMs: 15_000,
-  pongTimeoutMs: 10_000,
-  maxMissedPongs: 2,
-  tickMs: 5_000,
-  jitter: 0.2,
-};
-
-export class WsSubscription {
-  private opts: WsSubscriptionOptions;
-  private connections = new Map<string, WebSocket>();
-  private reconnectTimers = new Map<string, ReturnType<typeof setTimeout>>();
-  private reconnectAttempts = new Map<string, number>();
-  private listInterval: ReturnType<typeof setInterval> | null = null;
-  private stopped = false;
-  /** Conversation IDs that were explicitly stopped (e.g. revoke); do not reconnect. */
-  private stoppedConversations = new Set<string>();
-  private lastParseErrorAtByConv = new Map<string, number>();
-  private lastFrameAtByConv = new Map<string, number>();
-
-  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
-  private heartbeatStates = new Map<
-    string,
-    {
-      lastRxAt: number;
-      lastPingAt: number;
-      nextPingAt: number;
-      missedPongs: number;
-      pongTimeout: ReturnType<typeof setTimeout> | null;
-    }
-  >();
-
-  constructor(opts: WsSubscriptionOptions) {
-    this.opts = opts;
-  }
-
-  start(): void {
-    this.stopped = false;
-    this.connectAll();
-    this.listInterval = setInterval(() => this.syncConnections(), LIST_CONVERSATIONS_INTERVAL_MS);
-
-    // Start heartbeat scheduler (idle-triggered) once per process.
-    const hb = this.opts.heartbeat ?? {};
-    if (hb.enable ?? DEFAULT_HEARTBEAT.enable) {
-      this.heartbeatTimer = setInterval(() => this.heartbeatTick(), hb.tickMs ?? DEFAULT_HEARTBEAT.tickMs);
-    }
-  }
-
-  stop(): void {
-    this.stopped = true;
-    if (this.listInterval) {
-      clearInterval(this.listInterval);
-      this.listInterval = null;
-    }
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-    }
-    for (const timer of this.reconnectTimers.values()) {
-      clearTimeout(timer);
-    }
-    this.reconnectTimers.clear();
-    for (const [convId, ws] of this.connections) {
-      ws.removeAllListeners();
-      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
-        ws.close();
-      }
-      this.connections.delete(convId);
-    }
-    this.reconnectAttempts.clear();
-    this.stoppedConversations.clear();
-    this.lastParseErrorAtByConv.clear();
-    this.lastFrameAtByConv.clear();
-
-    for (const state of this.heartbeatStates.values()) {
-      if (state.pongTimeout) clearTimeout(state.pongTimeout);
-    }
-    this.heartbeatStates.clear();
-  }
-
-  /**
-   * Stop a single conversation's WebSocket and do not reconnect.
-   * Used when the conversation is revoked or the client no longer wants to subscribe.
-   */
-  stopConversation(conversationId: string): void {
-    this.stoppedConversations.add(conversationId);
-    const timer = this.reconnectTimers.get(conversationId);
-    if (timer) {
-      clearTimeout(timer);
-      this.reconnectTimers.delete(conversationId);
-    }
-
-    const hbState = this.heartbeatStates.get(conversationId);
-    if (hbState?.pongTimeout) clearTimeout(hbState.pongTimeout);
-    this.heartbeatStates.delete(conversationId);
-
-    const ws = this.connections.get(conversationId);
-    if (ws) {
-      ws.removeAllListeners();
-      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
-        ws.close();
-      }
-      this.connections.delete(conversationId);
-    }
-    this.lastParseErrorAtByConv.delete(conversationId);
-    this.lastFrameAtByConv.delete(conversationId);
-  }
-
-  private wsUrl(conversationId: string): string {
-    const base = this.opts.serverUrl.replace(/^http/, 'ws').replace(/\/$/, '');
-    return `${base}/v1/ws?conversation_id=${encodeURIComponent(conversationId)}`;
-  }
-
-  private async connectAsync(conversationId: string): Promise<void> {
-    if (this.stopped || this.stoppedConversations.has(conversationId) || this.connections.has(conversationId)) return;
-
-    const token = await Promise.resolve(this.opts.getAccessToken());
-    const url = this.wsUrl(conversationId);
-    const ws = new WebSocket(url, {
-      headers: { Authorization: `Bearer ${token}` },
-    });
-
-    this.connections.set(conversationId, ws);
-
-    const hb = this.opts.heartbeat ?? {};
-    const hbEnabled = hb.enable ?? DEFAULT_HEARTBEAT.enable;
-    if (hbEnabled) {
-      const now = Date.now();
-      this.heartbeatStates.set(conversationId, {
-        lastRxAt: now,
-        lastPingAt: 0,
-        nextPingAt: now + (hb.idleThresholdMs ?? DEFAULT_HEARTBEAT.idleThresholdMs),
-        missedPongs: 0,
-        pongTimeout: null,
-      });
-    }
-
-    ws.on('open', () => {
-      this.reconnectAttempts.set(conversationId, 0);
-      this.opts.onOpen?.(conversationId);
-      // ws_connected will arrive as first message
-    });
-
-    ws.on('message', (data: any) => {
-      try {
-        // Any server frame counts as activity; keep connection stable and avoid unnecessary pings.
-        const state = this.heartbeatStates.get(conversationId);
-        if (state) {
-          state.lastRxAt = Date.now();
-          state.missedPongs = 0;
-          if (state.pongTimeout) {
-            clearTimeout(state.pongTimeout);
-            state.pongTimeout = null;
-          }
-        }
-
-        const rawText =
-          typeof data === 'string'
-            ? data
-            : Buffer.isBuffer(data)
-              ? data.toString()
-              : Array.isArray(data)
-                ? Buffer.concat(data).toString()
-                : data instanceof ArrayBuffer
-                  ? Buffer.from(new Uint8Array(data)).toString()
-                  : // Fallback: try best-effort stringification
-                    String(data);
-
-        this.lastFrameAtByConv.set(conversationId, Date.now());
-
-        const msg = JSON.parse(rawText);
-
-        if (msg.type === 'ws_connected') {
-          this.opts.onDebug?.({
-            event: 'ws_connected',
-            conversationId,
-            detail: {
-              your_did: msg.your_did,
-              server_ts_ms: msg.server_ts_ms,
-              conversation_id: msg.conversation_id,
-            },
-          });
-        } else if (msg.type === 'ws_message' && msg.envelope) {
-          const env = msg.envelope;
-          const ignoreSelf = this.opts.ignoreSelfMessages ?? true;
-          if (!ignoreSelf || env.sender_did !== this.opts.myDid) {
-            this.opts.onMessage(env, conversationId);
-          } else {
-            this.opts.onDebug?.({
-              event: 'ws_message_ignored_self',
-              conversationId,
-              detail: { sender_did: env.sender_did, message_id: env.message_id, seq: env.seq },
-            });
-          }
-        } else if (msg.type === 'ws_control' && msg.control) {
-          this.opts.onControl?.(msg.control, conversationId);
-          this.opts.onDebug?.({ event: 'ws_control', conversationId, detail: msg.control });
-        } else if (msg.type === 'ws_receipt' && msg.receipt) {
-          this.opts.onDebug?.({ event: 'ws_receipt', conversationId, detail: msg.receipt });
-        } else if (msg?.type) {
-          this.opts.onDebug?.({ event: 'ws_unknown_type', conversationId, detail: { type: msg.type } });
-        }
-      } catch (e: any) {
-        // Observability: parse failures are otherwise silent and look like "server never pushes".
-        const now = Date.now();
-        const last = this.lastParseErrorAtByConv.get(conversationId) ?? 0;
-        if (now - last > 30_000) {
-          this.lastParseErrorAtByConv.set(conversationId, now);
-          this.opts.onDebug?.({
-            event: 'ws_parse_error',
-            conversationId,
-            detail: {
-              message: e?.message ?? String(e),
-              last_frame_at_ms: this.lastFrameAtByConv.get(conversationId) ?? null,
-            },
-          });
-        }
-      }
-    });
-
-    ws.on('pong', () => {
-      const state = this.heartbeatStates.get(conversationId);
-      if (!state) return;
-      state.lastRxAt = Date.now();
-      state.missedPongs = 0;
-      if (state.pongTimeout) {
-        clearTimeout(state.pongTimeout);
-        state.pongTimeout = null;
-      }
-    });
-
-    ws.on('close', () => {
-      this.connections.delete(conversationId);
-      const state = this.heartbeatStates.get(conversationId);
-      if (state?.pongTimeout) clearTimeout(state.pongTimeout);
-      this.heartbeatStates.delete(conversationId);
-      if (!this.stopped && !this.stoppedConversations.has(conversationId)) {
-        this.scheduleReconnect(conversationId);
-      }
-    });
-
-    ws.on('error', (err) => {
-      this.opts.onError?.(err);
-    });
-  }
-
-  private heartbeatTick(): void {
-    const hb = this.opts.heartbeat ?? {};
-    const hbEnabled = hb.enable ?? DEFAULT_HEARTBEAT.enable;
-    if (!hbEnabled) return;
-
-    const idleThresholdMs = hb.idleThresholdMs ?? DEFAULT_HEARTBEAT.idleThresholdMs;
-    const pingIntervalMs = hb.pingIntervalMs ?? DEFAULT_HEARTBEAT.pingIntervalMs;
-    const pongTimeoutMs = hb.pongTimeoutMs ?? DEFAULT_HEARTBEAT.pongTimeoutMs;
-    const maxMissedPongs = hb.maxMissedPongs ?? DEFAULT_HEARTBEAT.maxMissedPongs;
-    const jitter = hb.jitter ?? DEFAULT_HEARTBEAT.jitter;
-
-    const now = Date.now();
-
-    for (const [conversationId, ws] of this.connections) {
-      if (ws.readyState !== WebSocket.OPEN) continue;
-      const state = this.heartbeatStates.get(conversationId);
-      if (!state) continue;
-
-      // If we are waiting for a pong, do not send another ping.
-      if (state.pongTimeout) continue;
-
-      const idleFor = now - state.lastRxAt;
-      if (idleFor < idleThresholdMs) continue;
-
-      if (now < state.nextPingAt) continue;
-      if (state.lastPingAt !== 0 && now - state.lastPingAt < pingIntervalMs * 0.5) {
-        // Extra guard against edge cases (should be rare).
-        continue;
-      }
-
-      // Application-level keepalive for CDN/NAT idle timeouts (more reliable than ping/pong alone).
-      // Receiver can ignore this message.
-      try {
-        ws.send(JSON.stringify({ type: 'hb' }));
-      } catch {
-        // ignore; ping/pong + reconnect will handle dead sockets
-      }
-
-      ws.ping();
-      state.lastPingAt = now;
-      const jitterFactor = 1 + (Math.random() - 0.5) * 2 * jitter;
-      state.nextPingAt = now + Math.max(1000, pingIntervalMs * jitterFactor);
-
-      state.pongTimeout = setTimeout(() => {
-        state.missedPongs += 1;
-        state.pongTimeout = null;
-
-        if (state.missedPongs >= maxMissedPongs) {
-          try {
-            // Trigger close handler -> scheduleReconnect
-            ws.close(1001, 'pong timeout');
-          } catch {
-            // ignore
-          }
-        }
-      }, pongTimeoutMs);
-    }
-  }
-
-  private scheduleReconnect(conversationId: string): void {
-    if (this.reconnectTimers.has(conversationId)) return;
-
-    const attempt = this.reconnectAttempts.get(conversationId) ?? 0;
-    this.reconnectAttempts.set(conversationId, attempt + 1);
-
-    const tryConnect = () => {
-      this.reconnectTimers.delete(conversationId);
-      if (this.stopped) return;
-      void this.connectAsync(conversationId);
-    };
-
-    const delay = Math.min(
-      RECONNECT_BASE_MS * Math.pow(2, attempt) + (Math.random() - 0.5) * RECONNECT_JITTER * RECONNECT_BASE_MS,
-      RECONNECT_MAX_MS,
-    );
-    const timer = setTimeout(tryConnect, delay);
-    this.reconnectTimers.set(conversationId, timer);
-  }
-
-  private isSubscribableConversationType(type: string): boolean {
-    // Server may return pending_dm alongside dm listings. WS upgrade is supported for any conversation_id.
-    return type === 'dm' || type === 'pending_dm' || type === 'channel' || type === 'group';
-  }
-
-  private async connectAll(): Promise<void> {
-    try {
-      const convos = await this.opts.listConversations();
-      const subscribable = convos.filter((c) => this.isSubscribableConversationType(c.type));
-      for (const c of subscribable) {
-        void this.connectAsync(c.conversation_id);
-      }
-    } catch (err) {
-      this.opts.onError?.(err instanceof Error ? err : new Error(String(err)));
-    }
-  }
-
-  private async syncConnections(): Promise<void> {
-    if (this.stopped) return;
-    try {
-      const convos = await this.opts.listConversations();
-      const subscribableIds = new Set(
-        convos.filter((c) => this.isSubscribableConversationType(c.type)).map((c) => c.conversation_id),
-      );
-      for (const convId of subscribableIds) {
-        if (!this.stoppedConversations.has(convId) && !this.connections.has(convId)) {
-          void this.connectAsync(convId);
-        }
-      }
-      for (const convId of this.connections.keys()) {
-        if (!subscribableIds.has(convId) || this.stoppedConversations.has(convId)) {
-          const ws = this.connections.get(convId);
-          if (ws) {
-            ws.removeAllListeners();
-            ws.close();
-            this.connections.delete(convId);
-          }
-        }
-      }
-    } catch {
-      // ignore
-    }
-  }
-}

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"]
-}