@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.15.0

package/src/postgres/sync.ts

@@ -1,340 +0,0 @@
-/**
- * @module postgres/sync
- * @description Real-time and scheduled sync engine for the SAP PostgreSQL
- * adapter. Provides cron-like periodic sync and WebSocket-based
- * live event streaming.
- *
- * @category Postgres
- * @since v0.1.0
- *
- * @example
- * ```ts
- * import { SapSyncEngine } from "@synapse-sap/sdk/postgres";
- * import { SapPostgres }   from "@synapse-sap/sdk/postgres";
- * import { SapClient }     from "@synapse-sap/sdk";
- * import { Pool }          from "pg";
- *
- * const pool = new Pool({ connectionString: "postgresql://..." });
- * const sap  = SapClient.from(provider);
- * const pg   = new SapPostgres(pool, sap);
- * const sync = new SapSyncEngine(pg, sap);
- *
- * // One-shot full sync
- * await sync.run();
- *
- * // Periodic sync (every 60 seconds)
- * sync.start(60_000);
- *
- * // Live event streaming via WebSocket
- * await sync.startEventStream();
- *
- * // Graceful shutdown
- * await sync.stop();
- * ```
- */
-
-import type { SapClient } from "../core/client";
-import { EventParser } from "../events";
-import { GeyserEventStream, type GeyserConfig } from "../events/geyser";
-import type { SapPostgres, SyncAllResult } from "./adapter";
-import type { SyncOptions } from "./types";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Sync Engine
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name SapSyncEngine
- * @description Orchestrates periodic and real-time sync between
- * Solana on-chain state and the PostgreSQL mirror.
- *
- * Two operational modes:
- *
- * 1. **Periodic sync** — polls all account types at a configurable
- *    interval and upserts into PostgreSQL.
- *
- * 2. **Event streaming** — subscribes to SAP program logs via
- *    WebSocket and inserts events in real-time.
- *
- * Both modes can run simultaneously.
- *
- * @category Postgres
- * @since v0.1.0
- */
-export class SapSyncEngine {
-  private readonly pg: SapPostgres;
-  private readonly client: SapClient;
-  private readonly debug: boolean;
-
-  private intervalId: ReturnType<typeof setInterval> | null = null;
-  private logSubId: number | null = null;
-  private geyserStream: GeyserEventStream | null = null;
-  private running = false;
-
-  constructor(pg: SapPostgres, client: SapClient, debug = false) {
-    this.pg = pg;
-    this.client = client;
-    this.debug = debug;
-  }
-
-  // ═════════════════════════════════════════════
-  //  One-shot Sync
-  // ═════════════════════════════════════════════
-
-  /**
-   * @name run
-   * @description Execute a single full sync cycle.
-   * @param options - Optional sync configuration.
-   * @returns Sync result summary.
-   * @since v0.1.0
-   */
-  async run(options?: SyncOptions): Promise<SyncAllResult> {
-    this.log("Starting one-shot sync...");
-    const result = await this.pg.syncAll(options);
-    this.log(`One-shot sync complete: ${result.totalRecords} records`);
-    return result;
-  }
-
-  // ═════════════════════════════════════════════
-  //  Periodic Sync
-  // ═════════════════════════════════════════════
-
-  /**
-   * @name start
-   * @description Start periodic sync at the given interval.
-   * Safe to call when already running — resets the interval.
-   *
-   * @param intervalMs - Sync interval in milliseconds (default: 60_000).
-   * @param options - Optional sync configuration.
-   * @since v0.1.0
-   *
-   * @example
-   * ```ts
-   * // Sync every 30 seconds
-   * sync.start(30_000);
-   * ```
-   */
-  start(intervalMs = 60_000, options?: SyncOptions): void {
-    this.stopInterval();
-    this.running = true;
-    this.log(`Starting periodic sync every ${intervalMs}ms`);
-
-    // Run immediately, then repeat
-    this.pg.syncAll(options).catch((err) => this.log(`Sync error: ${err}`));
-
-    this.intervalId = setInterval(() => {
-      if (!this.running) return;
-      this.pg.syncAll(options).catch((err) => this.log(`Sync error: ${err}`));
-    }, intervalMs);
-  }
-
-  /**
-   * @name stop
-   * @description Stop all sync activity (periodic + event stream).
-   * @since v0.1.0
-   */
-  async stop(): Promise<void> {
-    this.running = false;
-    this.stopInterval();
-    await this.stopEventStream();
-    this.log("Sync engine stopped");
-  }
-
-  private stopInterval(): void {
-    if (this.intervalId) {
-      clearInterval(this.intervalId);
-      this.intervalId = null;
-    }
-  }
-
-  // ═════════════════════════════════════════════
-  //  Real-time Event Stream
-  // ═════════════════════════════════════════════
-
-  /**
-   * @name startEventStream
-   * @description Subscribe to SAP program logs via WebSocket and
-   * insert parsed events into the `sap_events` table in real-time.
-   *
-   * @since v0.1.0
-   *
-   * @example
-   * ```ts
-   * // Start streaming events
-   * await sync.startEventStream();
-   *
-   * // Later, stop the stream
-   * await sync.stopEventStream();
-   * ```
-   */
-  async startEventStream(): Promise<void> {
-    if (this.logSubId !== null) {
-      this.log("Event stream already running");
-      return;
-    }
-
-    const connection = this.client.program.provider.connection;
-    const programId = this.client.program.programId;
-    const eventParser = new EventParser(this.client.program);
-
-    this.logSubId = connection.onLogs(
-      programId,
-      async (logInfo) => {
-        try {
-          const events = eventParser.parseLogs(logInfo.logs);
-          for (const event of events) {
-            const data = event.data as Record<string, unknown>;
-            const agentPda =
-              (data.agent as string) ?? (data.agentPda as string) ?? undefined;
-            const wallet =
-              (data.wallet as string) ?? (data.owner as string) ?? undefined;
-
-            await this.pg.syncEvent(
-              event.name,
-              logInfo.signature,
-              0, // slot populated from getSlot if needed
-              data,
-              agentPda,
-              wallet,
-            );
-          }
-        } catch (err) {
-          this.log(`Event parse error: ${err}`);
-        }
-      },
-      "confirmed",
-    );
-
-    this.log("Event stream started");
-  }
-
-  /**
-   * @name stopEventStream
-   * @description Unsubscribe from the program log stream (WebSocket or Geyser).
-   * @since v0.1.0
-   */
-  async stopEventStream(): Promise<void> {
-    if (this.logSubId !== null) {
-      const connection = this.client.program.provider.connection;
-      await connection.removeOnLogsListener(this.logSubId);
-      this.logSubId = null;
-      this.log("WebSocket event stream stopped");
-    }
-    if (this.geyserStream) {
-      await this.geyserStream.disconnect();
-      this.geyserStream = null;
-      this.log("Geyser event stream stopped");
-    }
-  }
-
-  // ═════════════════════════════════════════════
-  //  Geyser gRPC Event Stream
-  // ═════════════════════════════════════════════
-
-  /**
-   * @name startGeyserStream
-   * @description Subscribe to SAP program transactions via Yellowstone gRPC
-   * and insert parsed events into the `sap_events` table in real-time.
-   *
-   * Drop-in replacement for {@link startEventStream} with lower latency,
-   * no missed events, and automatic reconnection.
-   *
-   * Requires `@triton-one/yellowstone-grpc` to be installed.
-   *
-   * @param geyserConfig - Yellowstone gRPC connection config.
-   * @since v0.6.3
-   *
-   * @example
-   * ```ts
-   * await sync.startGeyserStream({
-   *   endpoint: "https://grpc.triton.one",
-   *   token:    process.env.GEYSER_TOKEN!,
-   * });
-   * ```
-   */
-  async startGeyserStream(geyserConfig: GeyserConfig): Promise<void> {
-    if (this.geyserStream) {
-      this.log("Geyser stream already running");
-      return;
-    }
-
-    const eventParser = new EventParser(this.client.program);
-    const stream = new GeyserEventStream(geyserConfig);
-
-    stream.on("logs", async (logs: string[], signature: string, slot: number) => {
-      try {
-        const events = eventParser.parseLogs(logs);
-        for (const event of events) {
-          const data = event.data as Record<string, unknown>;
-          const agentPda =
-            (data.agent as string) ?? (data.agentPda as string) ?? undefined;
-          const wallet =
-            (data.wallet as string) ?? (data.owner as string) ?? undefined;
-
-          await this.pg.syncEvent(
-            event.name,
-            signature,
-            slot,
-            data,
-            agentPda,
-            wallet,
-          );
-        }
-      } catch (err) {
-        this.log(`Geyser event parse error: ${err}`);
-      }
-    });
-
-    stream.on("connected", () => {
-      this.log("Geyser gRPC connected");
-    });
-
-    stream.on("disconnected", (reason: string) => {
-      this.log(`Geyser gRPC disconnected: ${reason}`);
-    });
-
-    stream.on("error", (err: Error) => {
-      this.log(`Geyser error: ${err.message}`);
-    });
-
-    stream.on("reconnecting", (attempt: number) => {
-      this.log(`Geyser reconnecting (attempt ${attempt})...`);
-    });
-
-    await stream.connect();
-    this.geyserStream = stream;
-    this.log("Geyser event stream started");
-  }
-
-  // ═════════════════════════════════════════════
-  //  Status
-  // ═════════════════════════════════════════════
-
-  /**
-   * @name isRunning
-   * @description Check whether the periodic sync is active.
-   * @since v0.1.0
-   */
-  isRunning(): boolean {
-    return this.running;
-  }
-
-  /**
-   * @name isStreaming
-   * @description Check whether the event stream is active (WebSocket or Geyser).
-   * @since v0.1.0
-   */
-  isStreaming(): boolean {
-    return this.logSubId !== null || this.geyserStream?.connected === true;
-  }
-
-  // ═════════════════════════════════════════════
-  //  Internal
-  // ═════════════════════════════════════════════
-
-  private log(msg: string): void {
-    if (this.debug) {
-      console.log(`[SapSyncEngine] ${msg}`);
-    }
-  }
-}

package/src/postgres/types.ts

@@ -1,245 +0,0 @@
-/**
- * @module postgres/types
- * @description PostgreSQL adapter type definitions for SAP v2.
- *
- * Defines configuration, row shapes, and query result types
- * for the PostgreSQL off-chain mirror.
- *
- * @category Postgres
- * @since v0.1.0
- */
-
-// ═══════════════════════════════════════════════════════════════════
-//  Configuration
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name SapPostgresConfig
- * @description Configuration for the SAP PostgreSQL adapter.
- * @category Postgres
- * @since v0.1.0
- */
-export interface SapPostgresConfig {
-  /**
-   * PostgreSQL connection string.
-   * @example "postgresql://user:pass@localhost:5432/sap"
-   */
-  readonly connectionString: string;
-
-  /**
-   * Whether to automatically run schema migrations on connect.
-   * @default false
-   */
-  readonly autoMigrate?: boolean;
-
-  /**
-   * Table name prefix (default: "sap_").
-   * @default "sap_"
-   */
-  readonly tablePrefix?: string;
-
-  /**
-   * Enable verbose query logging.
-   * @default false
-   */
-  readonly debug?: boolean;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Account Type Registry
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name SapAccountType
- * @description All syncable on-chain account types.
- * @category Postgres
- * @since v0.1.0
- */
-export type SapAccountType =
-  | "global_registry"
-  | "agents"
-  | "agent_stats"
-  | "feedbacks"
-  | "capability_indexes"
-  | "protocol_indexes"
-  | "plugin_slots"
-  | "memory_entries"
-  | "memory_chunks"
-  | "memory_vaults"
-  | "sessions"
-  | "epoch_pages"
-  | "vault_delegates"
-  | "tools"
-  | "checkpoints"
-  | "escrows"
-  | "tool_category_indexes"
-  | "attestations"
-  | "memory_buffers"
-  | "memory_digests"
-  | "memory_ledgers"
-  | "ledger_pages";
-
-/**
- * @name SapTableName
- * @description Mapping of account types to PostgreSQL table names.
- * @category Postgres
- * @since v0.1.0
- */
-export const SAP_TABLE_MAP: Record<SapAccountType, string> = {
-  global_registry: "sap_global_registry",
-  agents: "sap_agents",
-  agent_stats: "sap_agent_stats",
-  feedbacks: "sap_feedbacks",
-  capability_indexes: "sap_capability_indexes",
-  protocol_indexes: "sap_protocol_indexes",
-  plugin_slots: "sap_plugin_slots",
-  memory_entries: "sap_memory_entries",
-  memory_chunks: "sap_memory_chunks",
-  memory_vaults: "sap_memory_vaults",
-  sessions: "sap_sessions",
-  epoch_pages: "sap_epoch_pages",
-  vault_delegates: "sap_vault_delegates",
-  tools: "sap_tools",
-  checkpoints: "sap_checkpoints",
-  escrows: "sap_escrows",
-  tool_category_indexes: "sap_tool_category_indexes",
-  attestations: "sap_attestations",
-  memory_buffers: "sap_memory_buffers",
-  memory_digests: "sap_memory_digests",
-  memory_ledgers: "sap_memory_ledgers",
-  ledger_pages: "sap_ledger_pages",
-};
-
-// ═══════════════════════════════════════════════════════════════════
-//  Row Types (PostgreSQL ↔ TypeScript)
-// ═══════════════════════════════════════════════════════════════════
-
-/** Base fields present on every synced row. */
-export interface SyncMeta {
-  readonly pda: string;
-  readonly slot: number;
-  readonly synced_at: Date;
-  readonly raw_data: Record<string, unknown> | null;
-}
-
-/** sap_agents row. */
-export interface AgentRow extends SyncMeta {
-  readonly bump: number;
-  readonly version: number;
-  readonly wallet: string;
-  readonly name: string;
-  readonly description: string;
-  readonly agent_id: string | null;
-  readonly agent_uri: string | null;
-  readonly x402_endpoint: string | null;
-  readonly is_active: boolean;
-  readonly created_at: string;
-  readonly updated_at: string;
-  readonly reputation_score: number;
-  readonly total_feedbacks: number;
-  readonly reputation_sum: string;
-  readonly total_calls_served: string;
-  readonly avg_latency_ms: number;
-  readonly uptime_percent: number;
-  readonly capabilities: unknown[];
-  readonly pricing: unknown[];
-  readonly protocols: string[];
-  readonly active_plugins: unknown[];
-}
-
-/** sap_escrows row. */
-export interface EscrowRow extends SyncMeta {
-  readonly bump: number;
-  readonly agent: string;
-  readonly depositor: string;
-  readonly agent_wallet: string;
-  readonly balance: string;
-  readonly total_deposited: string;
-  readonly total_settled: string;
-  readonly total_calls_settled: string;
-  readonly price_per_call: string;
-  readonly max_calls: string;
-  readonly created_at: string;
-  readonly last_settled_at: string | null;
-  readonly expires_at: string | null;
-  readonly volume_curve: unknown[];
-  readonly token_mint: string | null;
-  readonly token_decimals: number;
-}
-
-/** sap_tools row. */
-export interface ToolRow extends SyncMeta {
-  readonly bump: number;
-  readonly agent: string;
-  readonly tool_name: string;
-  readonly version: number;
-  readonly http_method: string;
-  readonly category: string;
-  readonly params_count: number;
-  readonly required_params: number;
-  readonly is_compound: boolean;
-  readonly is_active: boolean;
-  readonly total_invocations: string;
-  readonly created_at: string;
-  readonly updated_at: string;
-}
-
-/** sap_memory_ledgers row. */
-export interface LedgerRow extends SyncMeta {
-  readonly bump: number;
-  readonly session: string;
-  readonly authority: string;
-  readonly num_entries: number;
-  readonly total_data_size: string;
-  readonly created_at: string;
-  readonly updated_at: string;
-  readonly num_pages: number;
-}
-
-/** sap_events row. */
-export interface EventRow {
-  readonly id: number;
-  readonly event_name: string;
-  readonly tx_signature: string;
-  readonly slot: number;
-  readonly block_time: number | null;
-  readonly data: Record<string, unknown>;
-  readonly agent_pda: string | null;
-  readonly wallet: string | null;
-  readonly synced_at: Date;
-}
-
-/** sap_sync_cursors row. */
-export interface SyncCursorRow {
-  readonly account_type: string;
-  readonly last_slot: number;
-  readonly last_signature: string | null;
-  readonly updated_at: Date;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Sync Options
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name SyncOptions
- * @description Options for the sync engine.
- * @category Postgres
- * @since v0.1.0
- */
-export interface SyncOptions {
-  /** Account types to sync. Default: all. */
-  readonly accountTypes?: SapAccountType[];
-
-  /** Sync events from TX logs. @default true */
-  readonly syncEvents?: boolean;
-
-  /** Batch size for account fetching. @default 100 */
-  readonly batchSize?: number;
-
-  /** Callback invoked after each batch. */
-  readonly onProgress?: (synced: number, total: number, type: string) => void;
-
-  /** Skip accounts that haven't changed since last sync. @default true */
-  readonly incremental?: boolean;
-}