@breeztech/breez-sdk-spark 0.13.11-dev1 → 0.13.12-dev1

package/nodejs/breez_sdk_spark_wasm_bg.wasm.d.ts

@@ -1,11 +1,19 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const __wbg_bitcoinchainservicehandle_free: (a: number, b: number) => void;
 export const __wbg_breezsdk_free: (a: number, b: number) => void;
 export const __wbg_defaultsigner_free: (a: number, b: number) => void;
+export const __wbg_mysqlconnectionpool_free: (a: number, b: number) => void;
 export const __wbg_passkey_free: (a: number, b: number) => void;
 export const __wbg_sdkbuilder_free: (a: number, b: number) => void;
+export const __wbg_sspconnectionmanager_free: (a: number, b: number) => void;
 export const __wbg_tokenissuer_free: (a: number, b: number) => void;
+export const bitcoinchainservicehandle_broadcastTransaction: (a: number, b: number, c: number) => any;
+export const bitcoinchainservicehandle_getAddressUtxos: (a: number, b: number, c: number) => any;
+export const bitcoinchainservicehandle_getTransactionHex: (a: number, b: number, c: number) => any;
+export const bitcoinchainservicehandle_getTransactionStatus: (a: number, b: number, c: number) => any;
+export const bitcoinchainservicehandle_recommendedFees: (a: number) => any;
 export const breezsdk_addContact: (a: number, b: any) => any;
 export const breezsdk_addEventListener: (a: number, b: any) => any;
 export const breezsdk_buyBitcoin: (a: number, b: any) => any;
@@ -52,6 +60,8 @@ export const breezsdk_updateContact: (a: number, b: any) => any;
 export const breezsdk_updateUserSettings: (a: number, b: any) => any;
 export const connect: (a: any) => any;
 export const connectWithSigner: (a: any, b: any, c: number, d: number) => any;
+export const createMysqlConnectionPool: (a: any) => [number, number, number];
+export const createPostgresConnectionPool: (a: any) => [number, number, number];
 export const defaultConfig: (a: any) => any;
 export const defaultExternalSigner: (a: number, b: number, c: number, d: number, e: any, f: number) => [number, number, number];
 export const defaultMysqlStorageConfig: (a: number, b: number) => any;
@@ -77,6 +87,8 @@ export const defaultsigner_staticDepositSigningKey: (a: number, b: number) => an
 export const defaultsigner_subtractSecrets: (a: number, b: any, c: any) => any;
 export const getSparkStatus: () => any;
 export const initLogging: (a: any, b: number, c: number) => any;
+export const newRestChainService: (a: number, b: number, c: any, d: any, e: number) => number;
+export const newSspConnectionManager: (a: number, b: number) => number;
 export const passkey_getWallet: (a: number, b: number, c: number) => any;
 export const passkey_isAvailable: (a: number) => any;
 export const passkey_listLabels: (a: number) => any;
@@ -90,10 +102,14 @@ export const sdkbuilder_withDefaultStorage: (a: number, b: number, c: number) =>
 export const sdkbuilder_withFiatService: (a: number, b: any) => number;
 export const sdkbuilder_withKeySet: (a: number, b: any) => number;
 export const sdkbuilder_withLnurlClient: (a: number, b: any) => number;
-export const sdkbuilder_withMysqlBackend: (a: number, b: any) => number;
+export const sdkbuilder_withMysqlBackend: (a: number, b: any) => [number, number, number];
+export const sdkbuilder_withMysqlConnectionPool: (a: number, b: number) => number;
 export const sdkbuilder_withPaymentObserver: (a: number, b: any) => number;
-export const sdkbuilder_withPostgresBackend: (a: number, b: any) => number;
+export const sdkbuilder_withPostgresBackend: (a: number, b: any) => [number, number, number];
+export const sdkbuilder_withPostgresConnectionPool: (a: number, b: number) => number;
 export const sdkbuilder_withRestChainService: (a: number, b: number, c: number, d: any, e: number) => number;
+export const sdkbuilder_withSessionManager: (a: number, b: any) => number;
+export const sdkbuilder_withSspConnectionManager: (a: number, b: number) => number;
 export const sdkbuilder_withStorage: (a: number, b: any) => number;
 export const tokenissuer_burnIssuerToken: (a: number, b: any) => any;
 export const tokenissuer_createIssuerToken: (a: number, b: any) => any;
@@ -120,16 +136,18 @@ export const intounderlyingsink_close: (a: number) => any;
 export const intounderlyingsink_write: (a: number, b: any) => any;
 export const intounderlyingsource_cancel: (a: number) => void;
 export const intounderlyingsource_pull: (a: number, b: any) => any;
+export const __wbg_postgresconnectionpool_free: (a: number, b: number) => void;
 export const defaultPostgresStorageConfig: (a: number, b: number) => any;
-export const wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7_4: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7_5: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7_6: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_4: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_5: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_6: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_7: (a: number, b: number, c: any) => [number, number];
 export const wasm_bindgen__convert__closures_____invoke__h41057d61edf43a32: (a: number, b: number, c: any, d: any) => void;
 export const wasm_bindgen__convert__closures_____invoke__h4819aba3eed2db57: (a: number, b: number, c: any) => void;
 export const wasm_bindgen__convert__closures_____invoke__h4819aba3eed2db57_2: (a: number, b: number, c: any) => void;
 export const wasm_bindgen__convert__closures_____invoke__h4819aba3eed2db57_3: (a: number, b: number, c: any) => void;
-export const wasm_bindgen__convert__closures_____invoke__h484cd36e13f37bd7: (a: number, b: number) => void;
+export const wasm_bindgen__convert__closures_____invoke__h124479769cd429fd: (a: number, b: number) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;

package/nodejs/index.js

@@ -48,6 +48,17 @@ try {
     }
 }
 
+// Automatically import and set up the PostgreSQL session manager for Node.js
+try {
+    const { createPostgresSessionManager, createPostgresSessionManagerWithPool } = require('./postgres-session-manager/index.cjs');
+    global.createPostgresSessionManager = createPostgresSessionManager;
+    global.createPostgresSessionManagerWithPool = createPostgresSessionManagerWithPool;
+} catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') {
+        console.warn('Breez SDK: Failed to load PostgreSQL session manager:', error.message);
+    }
+}
+
 // Automatically import and set up the MySQL storage for Node.js
 try {
     const { createMysqlStorage, createMysqlPool, createMysqlStorageWithPool } = require('./mysql-storage/index.cjs');
@@ -82,5 +93,16 @@ try {
     }
 }
 
+// Automatically import and set up the MySQL session manager for Node.js
+try {
+    const { createMysqlSessionManager, createMysqlSessionManagerWithPool } = require('./mysql-session-manager/index.cjs');
+    global.createMysqlSessionManager = createMysqlSessionManager;
+    global.createMysqlSessionManagerWithPool = createMysqlSessionManagerWithPool;
+} catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') {
+        console.warn('Breez SDK: Failed to load MySQL session manager:', error.message);
+    }
+}
+
 // Export all WASM functions
 module.exports = wasmModule;

package/nodejs/index.mjs

@@ -6,20 +6,28 @@ import pkg from './index.js';
 export const {
   connect,
   connectWithSigner,
+  createMysqlConnectionPool,
+  createPostgresConnectionPool,
   defaultConfig,
   defaultExternalSigner,
   defaultMysqlStorageConfig,
   defaultPostgresStorageConfig,
   getSparkStatus,
   initLogging,
+  newRestChainService,
+  newSspConnectionManager,
   task_worker_entry_point,
+  BitcoinChainServiceHandle,
   BreezSdk,
   DefaultSigner,
   IntoUnderlyingByteSource,
   IntoUnderlyingSink,
   IntoUnderlyingSource,
+  MysqlConnectionPool,
   Passkey,
+  PostgresConnectionPool,
   SdkBuilder,
+  SspConnectionManager,
   TokenIssuer,
 } = pkg;
 

package/nodejs/mysql-session-manager/errors.cjs

@@ -0,0 +1,13 @@
+// errors.cjs - Session manager error wrapper with cause chain support
+class SessionManagerError extends Error {
+    constructor(message, cause = null) {
+        super(message);
+        this.name = 'SessionManagerError';
+        this.cause = cause;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SessionManagerError);
+        }
+    }
+}
+
+module.exports = { SessionManagerError };

package/nodejs/mysql-session-manager/index.cjs

@@ -0,0 +1,144 @@
+/**
+ * CommonJS implementation for Node.js MySQL Session Manager.
+ *
+ * Mirrors `postgres-session-manager/index.cjs` for MySQL 8.0+.
+ */
+
+let mysql;
+try {
+  const mainModule = require.main;
+  if (mainModule) {
+    mysql = mainModule.require("mysql2/promise");
+  } else {
+    mysql = require("mysql2/promise");
+  }
+} catch (error) {
+  try {
+    mysql = require("mysql2/promise");
+  } catch (fallbackError) {
+    throw new Error(
+      `mysql2 not found. Please install it in your project: npm install mysql2@^3.11.0\n` +
+        `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
+    );
+  }
+}
+
+const { SessionManagerError } = require("./errors.cjs");
+const { MysqlSessionManagerMigrationManager } = require("./migrations.cjs");
+
+class MysqlSessionManager {
+  /**
+   * @param {import('mysql2/promise').Pool} pool
+   * @param {Buffer|Uint8Array} identity - 33-byte secp256k1 compressed pubkey
+   *   identifying the tenant. All reads and writes are scoped by this.
+   * @param {object} [logger]
+   */
+  constructor(pool, identity, logger = null) {
+    if (!identity || identity.length !== 33) {
+      throw new SessionManagerError(
+        "tenant identity (33-byte secp256k1 pubkey) is required"
+      );
+    }
+    this.pool = pool;
+    this.identity = Buffer.from(identity);
+    this.logger = logger;
+  }
+
+  async initialize() {
+    try {
+      const migrationManager = new MysqlSessionManagerMigrationManager(this.logger);
+      await migrationManager.migrate(this.pool);
+      return this;
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to initialize MySQL session manager: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async close() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+  }
+
+  /**
+   * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
+   * @returns {Promise<{token: string, expiration: number} | null>}
+   */
+  async getSession(serviceIdentityKey) {
+    const serviceKey = _decodePubkey(serviceIdentityKey);
+    try {
+      const [rows] = await this.pool.execute(
+        `SELECT token, expiration FROM sessions
+         WHERE user_id = ? AND service_identity_key = ?`,
+        [this.identity, serviceKey]
+      );
+      if (!rows || rows.length === 0) {
+        return null;
+      }
+      const row = rows[0];
+      return {
+        token: row.token,
+        expiration: Number(row.expiration),
+      };
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to read session: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  /**
+   * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
+   * @param {{token: string, expiration: number}} session
+   */
+  async setSession(serviceIdentityKey, session) {
+    const serviceKey = _decodePubkey(serviceIdentityKey);
+    try {
+      await this.pool.execute(
+        `INSERT INTO sessions (user_id, service_identity_key, token, expiration)
+         VALUES (?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE token = VALUES(token), expiration = VALUES(expiration)`,
+        [this.identity, serviceKey, session.token, session.expiration]
+      );
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to write session: ${error.message}`,
+        error
+      );
+    }
+  }
+}
+
+function _decodePubkey(hex) {
+  if (typeof hex !== "string" || hex.length !== 66) {
+    throw new SessionManagerError(
+      "service_identity_key must be a 66-character hex-encoded 33-byte pubkey"
+    );
+  }
+  return Buffer.from(hex, "hex");
+}
+
+async function createMysqlSessionManager(poolConfig, identity, logger = null) {
+  const pool = mysql.createPool(poolConfig);
+  const manager = new MysqlSessionManager(pool, identity, logger);
+  await manager.initialize();
+  return manager;
+}
+
+async function createMysqlSessionManagerWithPool(pool, identity, logger = null) {
+  const manager = new MysqlSessionManager(pool, identity, logger);
+  await manager.initialize();
+  return manager;
+}
+
+module.exports = {
+  MysqlSessionManager,
+  createMysqlSessionManager,
+  createMysqlSessionManagerWithPool,
+  SessionManagerError,
+};

package/nodejs/mysql-session-manager/migrations.cjs

@@ -0,0 +1,102 @@
+/**
+ * Session manager migrations for MySQL 8.0+. Mirrors the Rust
+ * `MysqlSessionManager` schema exactly.
+ */
+
+const { SessionManagerError } = require("./errors.cjs");
+
+const SESSION_MIGRATIONS_TABLE = "session_schema_migrations";
+const MIGRATION_LOCK_NAME = "breez_mysql_session_manager_migration_lock";
+const MIGRATION_LOCK_TIMEOUT = 60;
+
+class MysqlSessionManagerMigrationManager {
+  constructor(logger = null) {
+    this.logger = logger;
+  }
+
+  /**
+   * @param {import('mysql2/promise').Pool} pool
+   */
+  async migrate(pool) {
+    const conn = await pool.getConnection();
+    try {
+      const [lockRows] = await conn.query(
+        "SELECT GET_LOCK(?, ?) AS acquired",
+        [MIGRATION_LOCK_NAME, MIGRATION_LOCK_TIMEOUT]
+      );
+      if (!lockRows || lockRows[0].acquired !== 1) {
+        throw new SessionManagerError(
+          `Failed to acquire session manager migration lock within ${MIGRATION_LOCK_TIMEOUT}s`
+        );
+      }
+
+      try {
+        await conn.query("START TRANSACTION");
+
+        await conn.query(`
+          CREATE TABLE IF NOT EXISTS \`${SESSION_MIGRATIONS_TABLE}\` (
+            version INT PRIMARY KEY,
+            applied_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
+          )
+        `);
+
+        const [versionRows] = await conn.query(
+          `SELECT COALESCE(MAX(version), 0) AS version FROM \`${SESSION_MIGRATIONS_TABLE}\``
+        );
+        const currentVersion = versionRows[0].version;
+
+        const migrations = this._getMigrations();
+
+        if (currentVersion >= migrations.length) {
+          await conn.query("COMMIT");
+          return;
+        }
+
+        for (let i = currentVersion; i < migrations.length; i++) {
+          const migration = migrations[i];
+          const version = i + 1;
+          for (const sql of migration.sql) {
+            await conn.query(sql);
+          }
+          await conn.query(
+            `INSERT INTO \`${SESSION_MIGRATIONS_TABLE}\` (version) VALUES (?)`,
+            [version]
+          );
+        }
+
+        await conn.query("COMMIT");
+      } catch (error) {
+        await conn.query("ROLLBACK").catch(() => {});
+        throw new SessionManagerError(
+          `Session manager migration failed: ${error.message}`,
+          error
+        );
+      } finally {
+        await conn
+          .query("SELECT RELEASE_LOCK(?)", [MIGRATION_LOCK_NAME])
+          .catch(() => {});
+      }
+    } finally {
+      conn.release();
+    }
+  }
+
+  _getMigrations() {
+    return [
+      {
+        name: "Create sessions table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS sessions (
+            user_id VARBINARY(33) NOT NULL,
+            service_identity_key VARBINARY(33) NOT NULL,
+            token TEXT NOT NULL,
+            expiration BIGINT NOT NULL,
+            PRIMARY KEY (user_id, service_identity_key)
+          )`,
+        ],
+      },
+    ];
+  }
+}
+
+module.exports = { MysqlSessionManagerMigrationManager };

package/nodejs/mysql-session-manager/package.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "mysql2": "^3.11.0"
+  },
+  "description": "Node.js MySQL session manager implementation for Breez SDK WASM (CommonJS)",
+  "main": "index.cjs",
+  "name": "@breez-sdk/mysql-session-manager",
+  "version": "1.0.0"
+}

package/nodejs/mysql-storage/index.cjs

@@ -147,6 +147,7 @@ class MysqlStorage {
   async _withTransaction(fn) {
     const conn = await this.pool.getConnection();
     try {
+      await conn.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
       await conn.beginTransaction();
       const result = await fn(conn);
       await conn.commit();

package/nodejs/mysql-token-store/index.cjs

@@ -128,6 +128,7 @@ class MysqlTokenStore {
       }
       lockAcquired = true;
 
+      await conn.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
       await conn.beginTransaction();
       const result = await fn(conn);
       await conn.commit();
@@ -157,6 +158,7 @@ class MysqlTokenStore {
   async _withTransaction(fn) {
     const conn = await this.pool.getConnection();
     try {
+      await conn.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
       await conn.beginTransaction();
       const result = await fn(conn);
       await conn.commit();
@@ -518,10 +520,7 @@ class MysqlTokenStore {
 
   async insertTokenOutputs(tokenOutputs) {
     try {
-      const conn = await this.pool.getConnection();
-      try {
-        await conn.beginTransaction();
-
+      await this._withTransaction(async (conn) => {
         await this._upsertMetadata(conn, tokenOutputs.metadata);
 
         const outputIds = tokenOutputs.outputs.map((o) => o.output.id);
@@ -540,14 +539,7 @@ class MysqlTokenStore {
             output
           );
         }
-
-        await conn.commit();
-      } catch (error) {
-        await conn.rollback().catch(() => {});
-        throw error;
-      } finally {
-        conn.release();
-      }
+      });
     } catch (error) {
       if (error instanceof TokenStoreError) throw error;
       throw new TokenStoreError(

package/nodejs/mysql-tree-store/index.cjs

@@ -135,6 +135,7 @@ class MysqlTreeStore {
       }
       lockAcquired = true;
 
+      await conn.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
       await conn.beginTransaction();
       const result = await fn(conn);
       await conn.commit();
@@ -164,6 +165,7 @@ class MysqlTreeStore {
   async _withTransaction(fn) {
     const conn = await this.pool.getConnection();
     try {
+      await conn.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
       await conn.beginTransaction();
       const result = await fn(conn);
       await conn.commit();

package/nodejs/package.json

@@ -7,9 +7,11 @@
     "postgres-storage/",
     "postgres-tree-store/",
     "postgres-token-store/",
+    "postgres-session-manager/",
     "mysql-storage/",
     "mysql-tree-store/",
     "mysql-token-store/",
+    "mysql-session-manager/",
     "index.js",
     "index.mjs"
   ],

package/nodejs/postgres-session-manager/errors.cjs

@@ -0,0 +1,13 @@
+// errors.cjs - Session manager error wrapper with cause chain support
+class SessionManagerError extends Error {
+    constructor(message, cause = null) {
+        super(message);
+        this.name = 'SessionManagerError';
+        this.cause = cause;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SessionManagerError);
+        }
+    }
+}
+
+module.exports = { SessionManagerError };

package/nodejs/postgres-session-manager/index.cjs

@@ -0,0 +1,165 @@
+/**
+ * CommonJS implementation for Node.js PostgreSQL Session Manager.
+ *
+ * Implements the JS-side `SessionManager` interface consumed by the Breez
+ * SDK WASM bindings: `getSession(serviceIdentityKey)` returns the cached
+ * session for the (tenant, service) pair or `null` when not found, and
+ * `setSession(serviceIdentityKey, session)` upserts a session.
+ *
+ * Tenant identity is bound at construction so multiple tenants can share
+ * a single Postgres database without leaking sessions across tenants.
+ */
+
+let pg;
+try {
+  const mainModule = require.main;
+  if (mainModule) {
+    pg = mainModule.require("pg");
+  } else {
+    pg = require("pg");
+  }
+} catch (error) {
+  try {
+    pg = require("pg");
+  } catch (fallbackError) {
+    throw new Error(
+      `pg not found. Please install it in your project: npm install pg@^8.18.0\n` +
+        `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
+    );
+  }
+}
+
+const { SessionManagerError } = require("./errors.cjs");
+const { SessionManagerMigrationManager } = require("./migrations.cjs");
+
+class PostgresSessionManager {
+  /**
+   * @param {import('pg').Pool} pool
+   * @param {Buffer|Uint8Array} identity - 33-byte secp256k1 compressed pubkey
+   *   identifying the tenant. All reads and writes are scoped by this.
+   * @param {object} [logger]
+   */
+  constructor(pool, identity, logger = null) {
+    if (!identity || identity.length !== 33) {
+      throw new SessionManagerError(
+        "tenant identity (33-byte secp256k1 pubkey) is required"
+      );
+    }
+    this.pool = pool;
+    this.identity = Buffer.from(identity);
+    this.logger = logger;
+  }
+
+  async initialize() {
+    try {
+      const migrationManager = new SessionManagerMigrationManager(this.logger);
+      await migrationManager.migrate(this.pool);
+      return this;
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to initialize PostgreSQL session manager: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async close() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+  }
+
+  /**
+   * Returns the cached session for the given service identity key, or `null`
+   * if no session is cached. The Rust adapter maps `null` to
+   * `SessionManagerError::NotFound`.
+   * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
+   * @returns {Promise<{token: string, expiration: number} | null>}
+   */
+  async getSession(serviceIdentityKey) {
+    const serviceKey = _decodePubkey(serviceIdentityKey);
+    try {
+      const { rows } = await this.pool.query(
+        `SELECT token, expiration FROM sessions
+         WHERE user_id = $1 AND service_identity_key = $2`,
+        [this.identity, serviceKey]
+      );
+      if (rows.length === 0) {
+        return null;
+      }
+      const row = rows[0];
+      return {
+        token: row.token,
+        expiration: Number(row.expiration),
+      };
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to read session: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Upserts a session for the given service identity key.
+   * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
+   * @param {{token: string, expiration: number}} session
+   */
+  async setSession(serviceIdentityKey, session) {
+    const serviceKey = _decodePubkey(serviceIdentityKey);
+    try {
+      await this.pool.query(
+        `INSERT INTO sessions (user_id, service_identity_key, token, expiration)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (user_id, service_identity_key)
+         DO UPDATE SET token = EXCLUDED.token, expiration = EXCLUDED.expiration`,
+        [this.identity, serviceKey, session.token, session.expiration]
+      );
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to write session: ${error.message}`,
+        error
+      );
+    }
+  }
+}
+
+function _decodePubkey(hex) {
+  if (typeof hex !== "string" || hex.length !== 66) {
+    throw new SessionManagerError(
+      "service_identity_key must be a 66-character hex-encoded 33-byte pubkey"
+    );
+  }
+  return Buffer.from(hex, "hex");
+}
+
+/**
+ * Convenience factory: creates a pool from a Pool config and returns an
+ * initialized `PostgresSessionManager`. Most callers should use
+ * `createPostgresSessionManagerWithPool` instead so the pool can be shared
+ * across stores.
+ */
+async function createPostgresSessionManager(poolConfig, identity, logger = null) {
+  const pool = new pg.Pool(poolConfig);
+  const manager = new PostgresSessionManager(pool, identity, logger);
+  await manager.initialize();
+  return manager;
+}
+
+/**
+ * Wraps an existing pool — useful when sharing the pool with the storage,
+ * tree store, and token store implementations.
+ */
+async function createPostgresSessionManagerWithPool(pool, identity, logger = null) {
+  const manager = new PostgresSessionManager(pool, identity, logger);
+  await manager.initialize();
+  return manager;
+}
+
+module.exports = {
+  PostgresSessionManager,
+  createPostgresSessionManager,
+  createPostgresSessionManagerWithPool,
+  SessionManagerError,
+};