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

package/dist/esm/postgres/sync.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @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 { type GeyserConfig } from "../events/geyser";
+import type { SapPostgres, SyncAllResult } from "./adapter";
+import type { SyncOptions } from "./types";
+/**
+ * @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 declare class SapSyncEngine {
+    private readonly pg;
+    private readonly client;
+    private readonly debug;
+    private intervalId;
+    private logSubId;
+    private geyserStream;
+    private running;
+    constructor(pg: SapPostgres, client: SapClient, debug?: boolean);
+    /**
+     * @name run
+     * @description Execute a single full sync cycle.
+     * @param options - Optional sync configuration.
+     * @returns Sync result summary.
+     * @since v0.1.0
+     */
+    run(options?: SyncOptions): Promise<SyncAllResult>;
+    /**
+     * @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?: number, options?: SyncOptions): void;
+    /**
+     * @name stop
+     * @description Stop all sync activity (periodic + event stream).
+     * @since v0.1.0
+     */
+    stop(): Promise<void>;
+    private stopInterval;
+    /**
+     * @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();
+     * ```
+     */
+    startEventStream(): Promise<void>;
+    /**
+     * @name stopEventStream
+     * @description Unsubscribe from the program log stream (WebSocket or Geyser).
+     * @since v0.1.0
+     */
+    stopEventStream(): Promise<void>;
+    /**
+     * @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!,
+     * });
+     * ```
+     */
+    startGeyserStream(geyserConfig: GeyserConfig): Promise<void>;
+    /**
+     * @name isRunning
+     * @description Check whether the periodic sync is active.
+     * @since v0.1.0
+     */
+    isRunning(): boolean;
+    /**
+     * @name isStreaming
+     * @description Check whether the event stream is active (WebSocket or Geyser).
+     * @since v0.1.0
+     */
+    isStreaming(): boolean;
+    private log;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/esm/postgres/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/postgres/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAEhC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,OAAO,CAAS;gBAEZ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,UAAQ;IAU7D;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAWxD;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAcvD;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,OAAO,CAAC,YAAY;IAWpB;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAyCvC;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0DlE;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAQtB,OAAO,CAAC,GAAG;CAKZ"}

package/dist/esm/postgres/sync.js

@@ -0,0 +1,285 @@
+/**
+ * @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 { EventParser } from "../events";
+import { GeyserEventStream } from "../events/geyser";
+// ═══════════════════════════════════════════════════════════════════
+//  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 {
+    pg;
+    client;
+    debug;
+    intervalId = null;
+    logSubId = null;
+    geyserStream = null;
+    running = false;
+    constructor(pg, client, 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) {
+        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) {
+        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() {
+        this.running = false;
+        this.stopInterval();
+        await this.stopEventStream();
+        this.log("Sync engine stopped");
+    }
+    stopInterval() {
+        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() {
+        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;
+                    const agentPda = data.agent ?? data.agentPda ?? undefined;
+                    const wallet = data.wallet ?? data.owner ?? 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() {
+        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) {
+        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, signature, slot) => {
+            try {
+                const events = eventParser.parseLogs(logs);
+                for (const event of events) {
+                    const data = event.data;
+                    const agentPda = data.agent ?? data.agentPda ?? undefined;
+                    const wallet = data.wallet ?? data.owner ?? 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) => {
+            this.log(`Geyser gRPC disconnected: ${reason}`);
+        });
+        stream.on("error", (err) => {
+            this.log(`Geyser error: ${err.message}`);
+        });
+        stream.on("reconnecting", (attempt) => {
+            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() {
+        return this.running;
+    }
+    /**
+     * @name isStreaming
+     * @description Check whether the event stream is active (WebSocket or Geyser).
+     * @since v0.1.0
+     */
+    isStreaming() {
+        return this.logSubId !== null || this.geyserStream?.connected === true;
+    }
+    // ═════════════════════════════════════════════
+    //  Internal
+    // ═════════════════════════════════════════════
+    log(msg) {
+        if (this.debug) {
+            console.log(`[SapSyncEngine] ${msg}`);
+        }
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/esm/postgres/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/postgres/sync.ts"],"names":[],"mappings":"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"}

package/dist/esm/postgres/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @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
+ */
+/**
+ * @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;
+}
+/**
+ * @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 declare const SAP_TABLE_MAP: Record<SapAccountType, string>;
+/** 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;
+}
+/**
+ * @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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/postgres/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/postgres/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/postgres/types.js

@@ -0,0 +1,41 @@
+/**
+ * @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
+ */
+/**
+ * @name SapTableName
+ * @description Mapping of account types to PostgreSQL table names.
+ * @category Postgres
+ * @since v0.1.0
+ */
+export const SAP_TABLE_MAP = {
+    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",
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/postgres/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/postgres/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAwEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAmC;IAC3D,eAAe,EAAE,qBAAqB;IACtC,MAAM,EAAE,YAAY;IACpB,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,eAAe;IAC1B,kBAAkB,EAAE,wBAAwB;IAC5C,gBAAgB,EAAE,sBAAsB;IACxC,YAAY,EAAE,kBAAkB;IAChC,cAAc,EAAE,oBAAoB;IACpC,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,mBAAmB;IAClC,QAAQ,EAAE,cAAc;IACxB,WAAW,EAAE,iBAAiB;IAC9B,eAAe,EAAE,qBAAqB;IACtC,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE,aAAa;IACtB,qBAAqB,EAAE,2BAA2B;IAClD,YAAY,EAAE,kBAAkB;IAChC,cAAc,EAAE,oBAAoB;IACpC,cAAc,EAAE,oBAAoB;IACpC,cAAc,EAAE,oBAAoB;IACpC,YAAY,EAAE,kBAAkB;CACjC,CAAC"}