graphile-realtime-subscriptions 0.3.0 → 0.4.0

package/esm/realtime-manager.js

@@ -0,0 +1,134 @@
+/**
+ * RealtimeManager — bridges CursorTracker (polling drain_changes) into
+ * PostGraphile's PgSubscriber so cursor-tracked events flow through the
+ * same subscription plans as NOTIFY events.
+ *
+ * Architecture:
+ *   PgSubscriber uses an internal EventEmitter. NOTIFY payloads arrive via
+ *   pg's `notification` event and are emitted as `eventEmitter.emit(channel, payload)`.
+ *   The `listen()` step in grafast subscribes to the same EventEmitter.
+ *
+ *   RealtimeManager converts ChangeLogEntry objects from drain_changes() into
+ *   the same NOTIFY payload format ("OP:rowId1,rowId2,...") and emits them on
+ *   the PgSubscriber's EventEmitter, so existing subscription plans handle
+ *   them identically to real NOTIFY events.
+ *
+ *   This provides at-least-once delivery: NOTIFY is instant but best-effort;
+ *   cursor polling catches up on anything missed (disconnects, restarts).
+ *   Duplicates are expected and acceptable — clients should be idempotent.
+ *
+ * Lifecycle:
+ *   1. start() → registers listener node, begins polling + heartbeat
+ *   2. drain_changes() results are converted and emitted on PgSubscriber
+ *   3. stop() → cleans up ephemeral subscriptions, removes listener node
+ */
+import { Logger } from '@pgpmjs/logger';
+import { CursorTracker } from './cursor-tracker';
+const log = new Logger('realtime-manager');
+/**
+ * Extract row IDs from a ChangeLogEntry.
+ *
+ * For INSERT/UPDATE the row ID lives in payload_after.id;
+ * for DELETE it lives in payload_before.id.
+ * Falls back to the change_log entry's own id if payloads are missing.
+ */
+function extractRowId(entry) {
+    if (entry.operation === 'DELETE') {
+        return entry.payload_before?.id ?? null;
+    }
+    return entry.payload_after?.id ?? null;
+}
+/**
+ * Convert a ChangeLogEntry into the NOTIFY payload format used by emit_change.
+ * Format: "OPERATION:rowId" (e.g. "INSERT:550e8400-...")
+ */
+function entryToNotifyPayload(entry) {
+    const rowId = extractRowId(entry);
+    if (!rowId) {
+        return entry.operation;
+    }
+    return `${entry.operation}:${rowId}`;
+}
+/**
+ * Build the NOTIFY channel name for a change_log entry.
+ * Matches the channel format used by emit_change: "realtime:{schema}.{table}"
+ */
+function entryToChannel(entry) {
+    return `realtime:${entry.source_schema}.${entry.source_table}`;
+}
+export class RealtimeManager {
+    cursorTracker;
+    subscriber;
+    started = false;
+    constructor(options) {
+        const { pgSubscriber, withPgClient, ...cursorOpts } = options;
+        this.subscriber = pgSubscriber;
+        this.cursorTracker = new CursorTracker({
+            nodeId: cursorOpts.nodeId,
+            schema: cursorOpts.schema,
+            pollIntervalMs: cursorOpts.pollIntervalMs,
+            heartbeatIntervalMs: cursorOpts.heartbeatIntervalMs,
+            batchLimit: cursorOpts.batchLimit,
+            withPgClient,
+            onChanges: (entries) => this.dispatchEntries(entries),
+            onError: cursorOpts.onError ?? ((err) => {
+                log.error(`RealtimeManager error: ${err.message}`);
+            }),
+        });
+    }
+    get nodeId() {
+        return this.cursorTracker.nodeId;
+    }
+    get isRunning() {
+        return this.started && this.cursorTracker.isRunning;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        log.info(`Starting RealtimeManager: node=${this.nodeId}`);
+        await this.cursorTracker.start();
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        log.info(`Stopping RealtimeManager: node=${this.nodeId}`);
+        await this.cursorTracker.stop();
+    }
+    /**
+     * Convert ChangeLogEntry objects to NOTIFY-format payloads and emit
+     * them on the PgSubscriber's internal EventEmitter.
+     */
+    dispatchEntries(entries) {
+        const emitter = this.getEventEmitter();
+        if (!emitter) {
+            log.warn('PgSubscriber has no eventEmitter; cursor events cannot be dispatched');
+            return;
+        }
+        for (const entry of entries) {
+            const channel = entryToChannel(entry);
+            const payload = entryToNotifyPayload(entry);
+            emitter.emit(channel, payload);
+        }
+        log.info(`Dispatched ${entries.length} cursor-tracked event(s) to PgSubscriber`);
+    }
+    /**
+     * Access PgSubscriber's internal EventEmitter.
+     *
+     * PgSubscriber from @dataplan/pg stores an EventEmitter3 instance as
+     * `this.eventEmitter`. It is private but stable across v1.x releases.
+     * This is the same emitter that NOTIFY events are dispatched through.
+     */
+    getEventEmitter() {
+        const sub = this.subscriber;
+        if (sub && typeof sub === 'object' && 'eventEmitter' in sub) {
+            const ee = sub.eventEmitter;
+            if (typeof ee?.emit === 'function') {
+                return ee;
+            }
+        }
+        return null;
+    }
+}
+export { extractRowId, entryToNotifyPayload, entryToChannel };

package/esm/types.d.ts

@@ -12,3 +12,135 @@ export interface RealtimeSubscriptionsPluginOptions {
      */
     overflowThreshold?: number;
 }
+/**
+ * A minimal PostgreSQL client interface used by CursorTracker.
+ * Compatible with node-postgres (pg) Client or PoolClient.
+ */
+export interface PgClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Callback that provides a PgClient for executing queries.
+ * The client is released after the callback returns.
+ */
+export type WithPgClient = <T>(callback: (client: PgClient) => Promise<T>) => Promise<T>;
+/**
+ * A single entry from drain_changes(), representing a change_log row
+ * matched against subscriber tables.
+ */
+export interface ChangeLogEntry {
+    id: string;
+    occurred_at: string;
+    source_schema: string;
+    source_table: string;
+    operation: string;
+    payload_after: Record<string, unknown> | null;
+    payload_before: Record<string, unknown> | null;
+    payload_diff: Record<string, unknown> | null;
+    subscriber_ids: string[];
+}
+/**
+ * Configuration for the CursorTracker background poller.
+ */
+export interface CursorTrackerOptions {
+    /**
+     * Unique identifier for this listener node.
+     * Should be stable across restarts if you want cursor continuity.
+     * If not provided, a random ID is generated (ephemeral mode).
+     */
+    nodeId?: string;
+    /**
+     * The realtime_public schema name where drain_changes(),
+     * touch_listener(), and cleanup_ephemeral() live.
+     *
+     * Default: 'realtime_public'
+     */
+    schema?: string;
+    /**
+     * How often to poll drain_changes() for new events (milliseconds).
+     *
+     * Default: 5000 (5 seconds)
+     */
+    pollIntervalMs?: number;
+    /**
+     * How often to send a heartbeat via touch_listener() (milliseconds).
+     *
+     * Default: 30000 (30 seconds)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum number of change_log rows to fetch per drain_changes() call.
+     *
+     * Default: 500
+     */
+    batchLimit?: number;
+    /**
+     * Function to acquire a PgClient for executing queries.
+     * The cursor tracker calls this for every poll and heartbeat cycle.
+     */
+    withPgClient: WithPgClient;
+    /**
+     * Called when drain_changes() returns new change_log entries.
+     * The entries include subscriber_ids for fan-out routing.
+     */
+    onChanges?: (entries: ChangeLogEntry[]) => void;
+    /**
+     * Called when an error occurs during polling, heartbeat, or cleanup.
+     * If not provided, errors are logged to the console.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Configuration for the RealtimeManager, which bridges CursorTracker
+ * events into PostGraphile's PgSubscriber for at-least-once delivery.
+ */
+export interface RealtimeManagerOptions {
+    /**
+     * The PgSubscriber instance from PostGraphile's context.
+     * RealtimeManager emits cursor-tracked events on its internal EventEmitter
+     * so they flow through existing subscription plans.
+     */
+    pgSubscriber: unknown;
+    /**
+     * Function to acquire a PgClient for executing cursor tracking queries.
+     */
+    withPgClient: WithPgClient;
+    /**
+     * Unique identifier for this listener node.
+     * Should be stable across restarts if you want cursor continuity.
+     * If not provided, a random ID is generated (ephemeral mode).
+     */
+    nodeId?: string;
+    /**
+     * The realtime_public schema name where drain_changes(),
+     * touch_listener(), and cleanup_ephemeral() live.
+     *
+     * Default: 'realtime_public'
+     */
+    schema?: string;
+    /**
+     * How often to poll drain_changes() for new events (milliseconds).
+     *
+     * Default: 5000 (5 seconds)
+     */
+    pollIntervalMs?: number;
+    /**
+     * How often to send a heartbeat via touch_listener() (milliseconds).
+     *
+     * Default: 30000 (30 seconds)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum number of change_log rows to fetch per drain_changes() call.
+     *
+     * Default: 500
+     */
+    batchLimit?: number;
+    /**
+     * Called when an error occurs during polling, heartbeat, or cleanup.
+     * If not provided, errors are logged via @pgpmjs/logger.
+     */
+    onError?: (error: Error) => void;
+}

package/index.d.ts

@@ -18,4 +18,7 @@
  */
 export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
 export { RealtimeSubscriptionsPreset } from './preset';
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';
 export type { RealtimeSubscriptionsPluginOptions } from './types';
+export type { CursorTrackerOptions, ChangeLogEntry, PgClient, WithPgClient, RealtimeManagerOptions, } from './types';

package/index.js

@@ -18,9 +18,13 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RealtimeSubscriptionsPreset = exports.RealtimeSubscriptionsPlugin = exports.createRealtimeSubscriptionsPlugin = void 0;
+exports.RealtimeManager = exports.CursorTracker = exports.RealtimeSubscriptionsPreset = exports.RealtimeSubscriptionsPlugin = exports.createRealtimeSubscriptionsPlugin = void 0;
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "createRealtimeSubscriptionsPlugin", { enumerable: true, get: function () { return plugin_1.createRealtimeSubscriptionsPlugin; } });
 Object.defineProperty(exports, "RealtimeSubscriptionsPlugin", { enumerable: true, get: function () { return plugin_1.RealtimeSubscriptionsPlugin; } });
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "RealtimeSubscriptionsPreset", { enumerable: true, get: function () { return preset_1.RealtimeSubscriptionsPreset; } });
+var cursor_tracker_1 = require("./cursor-tracker");
+Object.defineProperty(exports, "CursorTracker", { enumerable: true, get: function () { return cursor_tracker_1.CursorTracker; } });
+var realtime_manager_1 = require("./realtime-manager");
+Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_manager_1.RealtimeManager; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-realtime-subscriptions",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Realtime subscription plugin for PostGraphile v5 — per-table GraphQL subscriptions via LISTEN/NOTIFY",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -40,7 +40,8 @@
     "url": "https://github.com/constructive-io/constructive/issues"
   },
   "dependencies": {
-    "@pgpmjs/logger": "^2.9.0"
+    "@pgpmjs/logger": "^2.9.0",
+    "@pgsql/quotes": "^17.1.0"
   },
   "peerDependencies": {
     "grafast": "1.0.0",
@@ -55,5 +56,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "4a575e3e29827e96979cb6aac2c88eb7a07f7fd0"
+  "gitHead": "b54aef52c81be35a53e771003939d447aa34ba35"
 }

package/plugin.d.ts

@@ -6,7 +6,7 @@
  * for real-time event delivery.
  *
  * Subscription modes:
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ *   - Specific rows: onXxxChanged(ids: [UUID!]) — subscribe to changes on specific rows
  *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
  *
  * NOTIFY payload format (from emit_change trigger):
@@ -20,13 +20,30 @@
  *   4. The plugin parses the payload and fetches the specific changed row(s)
  *   5. The client receives { event, row, rowId, overflow }
  *
+ * Cursor tracking (at-least-once delivery):
+ *   The CursorTracker class provides a complementary polling-based delivery
+ *   path via drain_changes(). It manages the listener_node lifecycle:
+ *   - start() registers the node via touch_listener()
+ *   - Periodic polling via drain_changes() fetches change_log entries
+ *   - Periodic heartbeat via touch_listener() keeps the node alive
+ *   - stop() calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *   This enables at-least-once semantics by tracking cursor position.
+ *
  * Overflow protection:
  *   - Database-side: statements affecting > 50 rows send INVALIDATE
  *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
  *     drops individual events and sends a single INVALIDATE when exceeded
  *
- * RLS enforcement is automatic — resource.get() queries through the
- * authenticated user's connection with their JWT role applied.
+ * Security / RLS enforcement:
+ *   - Row data is always fetched via resource.get() which runs through the
+ *     authenticated user's connection with their JWT role and pgSettings applied.
+ *   - For INSERT/UPDATE events, if RLS denies access (resource.get returns null),
+ *     the rowId is masked (set to null) to prevent metadata leaks.
+ *   - For DELETE events, row is naturally null (the row no longer exists).
+ *   - For INVALIDATE (overflow), the client should refetch via a normal query
+ *     which is also RLS-gated.
+ *   - When ids are provided, only events for those specific rows are delivered,
+ *     preventing cross-tenant event leaks.
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { RealtimeSubscriptionsPluginOptions } from './types';
@@ -61,4 +78,7 @@ declare class EventThrottle {
 }
 export declare function createRealtimeSubscriptionsPlugin(options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Plugin;
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';
+export type { CursorTrackerOptions, ChangeLogEntry, WithPgClient, PgClient, RealtimeManagerOptions } from './types';
 export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/plugin.js

@@ -7,7 +7,7 @@
  * for real-time event delivery.
  *
  * Subscription modes:
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ *   - Specific rows: onXxxChanged(ids: [UUID!]) — subscribe to changes on specific rows
  *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
  *
  * NOTIFY payload format (from emit_change trigger):
@@ -21,16 +21,33 @@
  *   4. The plugin parses the payload and fetches the specific changed row(s)
  *   5. The client receives { event, row, rowId, overflow }
  *
+ * Cursor tracking (at-least-once delivery):
+ *   The CursorTracker class provides a complementary polling-based delivery
+ *   path via drain_changes(). It manages the listener_node lifecycle:
+ *   - start() registers the node via touch_listener()
+ *   - Periodic polling via drain_changes() fetches change_log entries
+ *   - Periodic heartbeat via touch_listener() keeps the node alive
+ *   - stop() calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *   This enables at-least-once semantics by tracking cursor position.
+ *
  * Overflow protection:
  *   - Database-side: statements affecting > 50 rows send INVALIDATE
  *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
  *     drops individual events and sends a single INVALIDATE when exceeded
  *
- * RLS enforcement is automatic — resource.get() queries through the
- * authenticated user's connection with their JWT role applied.
+ * Security / RLS enforcement:
+ *   - Row data is always fetched via resource.get() which runs through the
+ *     authenticated user's connection with their JWT role and pgSettings applied.
+ *   - For INSERT/UPDATE events, if RLS denies access (resource.get returns null),
+ *     the rowId is masked (set to null) to prevent metadata leaks.
+ *   - For DELETE events, row is naturally null (the row no longer exists).
+ *   - For INVALIDATE (overflow), the client should refetch via a normal query
+ *     which is also RLS-gated.
+ *   - When ids are provided, only events for those specific rows are delivered,
+ *     preventing cross-tenant event leaks.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OVERFLOW_THRESHOLD = exports.EventThrottle = void 0;
+exports.DEFAULT_OVERFLOW_THRESHOLD = exports.EventThrottle = exports.RealtimeManager = exports.CursorTracker = void 0;
 exports.createRealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
 exports.RealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
 exports.parseNotifyPayload = parseNotifyPayload;
@@ -129,7 +146,7 @@ function discoverRealtimeTables(build) {
 }
 function buildTypeDefs(tables) {
     const subscriptionFields = tables
-        .map(({ fieldName, payloadTypeName }) => `  """Subscribe to changes on this table. Pass an id to watch a specific record."""\n  ${fieldName}(id: UUID): ${payloadTypeName}`)
+        .map(({ fieldName, payloadTypeName }) => `  """Subscribe to changes on this table. Pass ids to watch specific rows, or no args for the full collection."""\n  ${fieldName}(ids: [UUID!]): ${payloadTypeName}`)
         .join('\n');
     const payloadTypes = tables
         .map(({ payloadTypeName, typeName, rowFieldName }) => `"""Payload delivered when a ${typeName} row changes."""\n` +
@@ -138,7 +155,7 @@ function buildTypeDefs(tables) {
         `  event: String!\n` +
         `  """The current state of the row (null for DELETE, INVALIDATE, or if RLS denies access)."""\n` +
         `  ${rowFieldName}: ${typeName}\n` +
-        `  """The ID of the changed row (null for INVALIDATE)."""\n` +
+        `  """The ID of the changed row (null for INVALIDATE, or masked when RLS denies access)."""\n` +
         `  rowId: UUID\n` +
         `  """True when too many changes occurred and the client should refetch."""\n` +
         `  overflow: Boolean!\n` +
@@ -155,9 +172,10 @@ function buildPlans(tables, overflowThreshold) {
             subscribePlan(_$root, args) {
                 const $pgSubscriber = (0, grafast_1.context)().get('pgSubscriber');
                 const $topic = (0, grafast_1.constant)(notifyChannel);
-                const $id = args.get('id');
+                const $ids = args.get('ids');
                 return (0, grafast_1.listen)($pgSubscriber, $topic, ($payload) => {
-                    const $parsed = (0, grafast_1.lambda)($payload, (raw) => {
+                    const $parsed = (0, grafast_1.lambda)([$payload, $ids], (pair) => {
+                        const [raw, subscribedIds] = pair;
                         const parsed = parseNotifyPayload(String(raw));
                         const action = parsed.overflow ? 'deliver' : throttle.check();
                         if (action === 'drop') {
@@ -170,11 +188,17 @@ function buildPlans(tables, overflowThreshold) {
                                 overflow: true,
                             };
                         }
+                        // Sparse set filtering: only deliver events for subscribed row IDs
+                        if (subscribedIds && subscribedIds.length > 0) {
+                            const hasMatch = parsed.rowIds.some((rid) => subscribedIds.includes(rid));
+                            if (!hasMatch)
+                                return null;
+                        }
                         return parsed;
                     });
                     return (0, grafast_1.object)({
                         parsed: $parsed,
-                        subscribedId: $id,
+                        subscribedIds: $ids,
                     });
                 });
             },
@@ -189,11 +213,16 @@ function buildPlans(tables, overflowThreshold) {
             },
             rowId($parent) {
                 const $parsed = $parent.get('parsed');
-                return (0, grafast_1.lambda)($parsed, (p) => {
-                    const parsed = p;
-                    if (!parsed || parsed.overflow || parsed.rowIds.length === 0)
+                const $subscribedIds = $parent.get('subscribedIds');
+                return (0, grafast_1.lambda)([$parsed, $subscribedIds], (pair) => {
+                    const [p, subscribedIds] = pair;
+                    if (!p || p.overflow || p.rowIds.length === 0)
                         return null;
-                    return parsed.rowIds[0];
+                    // When ids are provided, return the first matching row ID
+                    if (subscribedIds && subscribedIds.length > 0) {
+                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
+                    }
+                    return p.rowIds[0];
                 });
             },
             overflow($parent) {
@@ -202,13 +231,16 @@ function buildPlans(tables, overflowThreshold) {
             },
             [rowFieldName]($parent) {
                 const $parsed = $parent.get('parsed');
-                const $subscribedId = $parent.get('subscribedId');
-                const $rowId = (0, grafast_1.lambda)([$parsed, $subscribedId], (pair) => {
-                    const [p, subscribedId] = pair;
-                    if (subscribedId)
-                        return subscribedId;
+                const $subscribedIds = $parent.get('subscribedIds');
+                const $rowId = (0, grafast_1.lambda)([$parsed, $subscribedIds], (tuple) => {
+                    const [p, subscribedIds] = tuple;
                     if (!p || p.overflow || p.rowIds.length === 0)
                         return null;
+                    // When ids are provided, return first matching row ID
+                    if (subscribedIds && subscribedIds.length > 0) {
+                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
+                    }
+                    // Full collection mode: return first row ID
                     return p.rowIds[0];
                 });
                 return resource.get({ id: $rowId });
@@ -233,3 +265,8 @@ function createRealtimeSubscriptionsPlugin(options = {}) {
         return { typeDefs, plans };
     }, 'RealtimeSubscriptionsPlugin');
 }
+// Re-export CursorTracker and RealtimeManager for convenience
+var cursor_tracker_1 = require("./cursor-tracker");
+Object.defineProperty(exports, "CursorTracker", { enumerable: true, get: function () { return cursor_tracker_1.CursorTracker; } });
+var realtime_manager_1 = require("./realtime-manager");
+Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_manager_1.RealtimeManager; } });

package/realtime-manager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * RealtimeManager — bridges CursorTracker (polling drain_changes) into
+ * PostGraphile's PgSubscriber so cursor-tracked events flow through the
+ * same subscription plans as NOTIFY events.
+ *
+ * Architecture:
+ *   PgSubscriber uses an internal EventEmitter. NOTIFY payloads arrive via
+ *   pg's `notification` event and are emitted as `eventEmitter.emit(channel, payload)`.
+ *   The `listen()` step in grafast subscribes to the same EventEmitter.
+ *
+ *   RealtimeManager converts ChangeLogEntry objects from drain_changes() into
+ *   the same NOTIFY payload format ("OP:rowId1,rowId2,...") and emits them on
+ *   the PgSubscriber's EventEmitter, so existing subscription plans handle
+ *   them identically to real NOTIFY events.
+ *
+ *   This provides at-least-once delivery: NOTIFY is instant but best-effort;
+ *   cursor polling catches up on anything missed (disconnects, restarts).
+ *   Duplicates are expected and acceptable — clients should be idempotent.
+ *
+ * Lifecycle:
+ *   1. start() → registers listener node, begins polling + heartbeat
+ *   2. drain_changes() results are converted and emitted on PgSubscriber
+ *   3. stop() → cleans up ephemeral subscriptions, removes listener node
+ */
+import type { ChangeLogEntry, RealtimeManagerOptions } from './types';
+/**
+ * Extract row IDs from a ChangeLogEntry.
+ *
+ * For INSERT/UPDATE the row ID lives in payload_after.id;
+ * for DELETE it lives in payload_before.id.
+ * Falls back to the change_log entry's own id if payloads are missing.
+ */
+declare function extractRowId(entry: ChangeLogEntry): string | null;
+/**
+ * Convert a ChangeLogEntry into the NOTIFY payload format used by emit_change.
+ * Format: "OPERATION:rowId" (e.g. "INSERT:550e8400-...")
+ */
+declare function entryToNotifyPayload(entry: ChangeLogEntry): string;
+/**
+ * Build the NOTIFY channel name for a change_log entry.
+ * Matches the channel format used by emit_change: "realtime:{schema}.{table}"
+ */
+declare function entryToChannel(entry: ChangeLogEntry): string;
+export declare class RealtimeManager {
+    private readonly cursorTracker;
+    private readonly subscriber;
+    private started;
+    constructor(options: RealtimeManagerOptions);
+    get nodeId(): string;
+    get isRunning(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Convert ChangeLogEntry objects to NOTIFY-format payloads and emit
+     * them on the PgSubscriber's internal EventEmitter.
+     */
+    private dispatchEntries;
+    /**
+     * Access PgSubscriber's internal EventEmitter.
+     *
+     * PgSubscriber from @dataplan/pg stores an EventEmitter3 instance as
+     * `this.eventEmitter`. It is private but stable across v1.x releases.
+     * This is the same emitter that NOTIFY events are dispatched through.
+     */
+    private getEventEmitter;
+}
+export { extractRowId, entryToNotifyPayload, entryToChannel };