@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/src/postgres/sync.ts

@@ -0,0 +1,254 @@
+/**
+ * @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 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 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.
+   * @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("Event stream stopped");
+    }
+  }
+
+  // ═════════════════════════════════════════════
+  //  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.
+   * @since v0.1.0
+   */
+  isStreaming(): boolean {
+    return this.logSubId !== null;
+  }
+
+  // ═════════════════════════════════════════════
+  //  Internal
+  // ═════════════════════════════════════════════
+
+  private log(msg: string): void {
+    if (this.debug) {
+      console.log(`[SapSyncEngine] ${msg}`);
+    }
+  }
+}

package/src/postgres/types.ts

@@ -0,0 +1,245 @@
+/**
+ * @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;
+}