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

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

@@ -0,0 +1,126 @@
+/**
+ * Database Migration Manager for Breez SDK PostgreSQL Session Manager.
+ *
+ * Uses a session_schema_migrations table + pg_advisory_xact_lock to safely
+ * run migrations from concurrent processes. Mirrors the schema produced by
+ * the Rust `PostgresSessionManager`.
+ */
+
+const { SessionManagerError } = require("./errors.cjs");
+
+/**
+ * Advisory lock ID for session-manager migrations.
+ * Uses a different lock ID from the storage / tree store / token store
+ * migrations to avoid contention. Derived from ASCII bytes of "SESN"
+ * (0x5345534E).
+ */
+const MIGRATION_LOCK_ID = "1397245774"; // 0x5345534E as decimal string
+
+class SessionManagerMigrationManager {
+  constructor(logger = null) {
+    this.logger = logger;
+  }
+
+  /**
+   * Run all pending migrations inside a single transaction with an advisory
+   * lock.
+   * @param {import('pg').Pool} pool
+   */
+  async migrate(pool) {
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(`SELECT pg_advisory_xact_lock(${MIGRATION_LOCK_ID})`);
+
+      await client.query(`
+        CREATE TABLE IF NOT EXISTS session_schema_migrations (
+          version INTEGER PRIMARY KEY,
+          applied_at TIMESTAMPTZ DEFAULT NOW()
+        )
+      `);
+
+      const versionResult = await client.query(
+        "SELECT COALESCE(MAX(version), 0) AS version FROM session_schema_migrations"
+      );
+      const currentVersion = versionResult.rows[0].version;
+
+      const migrations = this._getMigrations();
+
+      if (currentVersion >= migrations.length) {
+        this._log(
+          "info",
+          `Session manager database is up to date (version ${currentVersion})`
+        );
+        await client.query("COMMIT");
+        return;
+      }
+
+      this._log(
+        "info",
+        `Migrating session manager database from version ${currentVersion} to ${migrations.length}`
+      );
+
+      for (let i = currentVersion; i < migrations.length; i++) {
+        const migration = migrations[i];
+        const version = i + 1;
+        this._log(
+          "debug",
+          `Running session manager migration ${version}: ${migration.name}`
+        );
+
+        for (const sql of migration.sql) {
+          await client.query(sql);
+        }
+
+        await client.query(
+          "INSERT INTO session_schema_migrations (version) VALUES ($1)",
+          [version]
+        );
+      }
+
+      await client.query("COMMIT");
+      this._log(
+        "info",
+        "Session manager database migration completed successfully"
+      );
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {});
+      throw new SessionManagerError(
+        `Session manager migration failed: ${error.message}`,
+        error
+      );
+    } finally {
+      client.release();
+    }
+  }
+
+  _log(level, message) {
+    if (this.logger && typeof this.logger.log === "function") {
+      this.logger.log({ line: message, level });
+    } else if (level === "error") {
+      console.error(`[SessionManagerMigrationManager] ${message}`);
+    }
+  }
+
+  /**
+   * Migrations matching the Rust PostgresSessionManager schema exactly.
+   */
+  _getMigrations() {
+    return [
+      {
+        name: "Create sessions table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS sessions (
+            user_id BYTEA NOT NULL,
+            service_identity_key BYTEA NOT NULL,
+            token TEXT NOT NULL,
+            expiration BIGINT NOT NULL,
+            PRIMARY KEY (user_id, service_identity_key)
+          )`,
+        ],
+      },
+    ];
+  }
+}
+
+module.exports = { SessionManagerMigrationManager };

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

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

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

@@ -532,13 +532,9 @@ class PostgresTokenStore {
    */
   async insertTokenOutputs(tokenOutputs) {
     try {
-      const client = await this.pool.connect();
-      try {
-        await client.query("BEGIN");
-
+      await this._withTransaction(async (client) => {
         await this._upsertMetadata(client, tokenOutputs.metadata);
 
-        // Remove inserted output IDs from spent markers (output returned to us)
         const outputIds = tokenOutputs.outputs.map((o) => o.output.id);
         if (outputIds.length > 0) {
           await client.query(
@@ -554,14 +550,7 @@ class PostgresTokenStore {
             output
           );
         }
-
-        await client.query("COMMIT");
-      } catch (error) {
-        await client.query("ROLLBACK").catch(() => {});
-        throw error;
-      } finally {
-        client.release();
-      }
+      });
     } catch (error) {
       if (error instanceof TokenStoreError) throw error;
       throw new TokenStoreError(

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@breeztech/breez-sdk-spark",
-    "version": "0.13.11-dev1",
+    "version": "0.13.12-dev1",
     "description": "Breez Spark SDK",
     "repository": "https://github.com/breez/spark-sdk",
     "author": "Breez <contact@breez.technology> (https://github.com/breez)",

package/ssr/index.js

@@ -33,6 +33,16 @@ export function connectWithSigner(...args) {
   return _module.connectWithSigner(...args);
 }
 
+export function createMysqlConnectionPool(...args) {
+  if (!_module) _notInitialized('createMysqlConnectionPool');
+  return _module.createMysqlConnectionPool(...args);
+}
+
+export function createPostgresConnectionPool(...args) {
+  if (!_module) _notInitialized('createPostgresConnectionPool');
+  return _module.createPostgresConnectionPool(...args);
+}
+
 export function defaultConfig(...args) {
   if (!_module) _notInitialized('defaultConfig');
   return _module.defaultConfig(...args);
@@ -63,6 +73,16 @@ export function initLogging(...args) {
   return _module.initLogging(...args);
 }
 
+export function newRestChainService(...args) {
+  if (!_module) _notInitialized('newRestChainService');
+  return _module.newRestChainService(...args);
+}
+
+export function newSspConnectionManager(...args) {
+  if (!_module) _notInitialized('newSspConnectionManager');
+  return _module.newSspConnectionManager(...args);
+}
+
 export function task_worker_entry_point(...args) {
   if (!_module) _notInitialized('task_worker_entry_point');
   return _module.task_worker_entry_point(...args);
@@ -73,6 +93,13 @@ export function initSync(...args) {
   return _module.initSync(...args);
 }
 
+export class BitcoinChainServiceHandle {
+  constructor(...args) {
+    if (!_module) _notInitialized('new BitcoinChainServiceHandle');
+    return new _module.BitcoinChainServiceHandle(...args);
+  }
+}
+
 export class BreezSdk {
   constructor(...args) {
     if (!_module) _notInitialized('new BreezSdk');
@@ -108,6 +135,13 @@ export class IntoUnderlyingSource {
   }
 }
 
+export class MysqlConnectionPool {
+  constructor(...args) {
+    if (!_module) _notInitialized('new MysqlConnectionPool');
+    return new _module.MysqlConnectionPool(...args);
+  }
+}
+
 export class Passkey {
   constructor(...args) {
     if (!_module) _notInitialized('new Passkey');
@@ -115,6 +149,13 @@ export class Passkey {
   }
 }
 
+export class PostgresConnectionPool {
+  constructor(...args) {
+    if (!_module) _notInitialized('new PostgresConnectionPool');
+    return new _module.PostgresConnectionPool(...args);
+  }
+}
+
 export class SdkBuilder {
   constructor(...args) {
     if (!_module) _notInitialized('new SdkBuilder');
@@ -122,6 +163,13 @@ export class SdkBuilder {
   }
 }
 
+export class SspConnectionManager {
+  constructor(...args) {
+    if (!_module) _notInitialized('new SspConnectionManager');
+    return new _module.SspConnectionManager(...args);
+  }
+}
+
 export class TokenIssuer {
   constructor(...args) {
     if (!_module) _notInitialized('new TokenIssuer');

package/web/breez_sdk_spark_wasm.d.ts

@@ -1068,6 +1068,16 @@ export interface SendPaymentResponse {
     payment: Payment;
 }
 
+export interface Session {
+    token: string;
+    expiration: number;
+}
+
+export interface SessionManager {
+    getSession: (serviceIdentityKey: string) => Promise<Session>;
+    setSession: (serviceIdentityKey: string, session: Session) => Promise<void>;
+}
+
 export interface SetLnurlMetadataItem {
     paymentHash: string;
     senderComment?: string;
@@ -1361,6 +1371,8 @@ export type SendPaymentOptions = { type: "bitcoinAddress"; confirmationSpeed: On
 
 export type ServiceStatus = "operational" | "degraded" | "partial" | "unknown" | "major";
 
+export type SessionManagerError = { type: "notFound" } | ({ type: "generic" } & string);
+
 export type SparkHtlcStatus = "waitingForPreimage" | "preimageShared" | "returned";
 
 export type StableBalanceActiveLabel = { type: "set"; label: string } | { type: "unset" };
@@ -1378,6 +1390,25 @@ export type UpdateDepositPayload = { type: "claimError"; error: DepositClaimErro
 export type WebhookEventType = { type: "lightningReceiveFinished" } | { type: "lightningSendFinished" } | { type: "coopExitFinished" } | { type: "staticDepositFinished" } | ({ type: "unknown" } & string);
 
 
+/**
+ * Rust-built implementation of the JS `BitcoinChainService` interface.
+ *
+ * Returned by factories like [`new_rest_chain_service`]; users see it as a
+ * `BitcoinChainService` and pass it to `withChainService`. Pass the same
+ * instance to multiple `SdkBuilder`s to share a single underlying HTTP
+ * client (and its connection pool) across SDK instances.
+ */
+export class BitcoinChainServiceHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    broadcastTransaction(tx: string): Promise<void>;
+    getAddressUtxos(address: string): Promise<any>;
+    getTransactionHex(txid: string): Promise<any>;
+    getTransactionStatus(txid: string): Promise<any>;
+    recommendedFees(): Promise<any>;
+}
+
 export class BreezSdk {
     private constructor();
     free(): void;
@@ -1486,6 +1517,16 @@ export class IntoUnderlyingSource {
     pull(controller: ReadableStreamDefaultController): Promise<any>;
 }
 
+/**
+ * A shareable MySQL connection pool. See [`PostgresConnectionPool`](super::postgres_pool::PostgresConnectionPool)
+ * for sharing semantics and lifecycle.
+ */
+export class MysqlConnectionPool {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
 /**
  * Passkey-based wallet operations using WebAuthn PRF extension.
  *
@@ -1529,6 +1570,22 @@ export class Passkey {
     storeLabel(label: string): Promise<void>;
 }
 
+/**
+ * A shareable Postgres connection pool.
+ *
+ * Construct via [`create_postgres_connection_pool`] and pass the same handle to multiple
+ * `SdkBuilder`s via `withPostgresConnectionPool` to share connections across SDKs.
+ * Per-tenant scoping is derived from each SDK's seed.
+ *
+ * The pool's lifecycle is controlled by the integrator: it stays alive as
+ * long as any reference is held. `disconnect()` does **not** close the pool.
+ */
+export class PostgresConnectionPool {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
 export class SdkBuilder {
     private constructor();
     free(): void;
@@ -1541,13 +1598,57 @@ export class SdkBuilder {
     withFiatService(fiat_service: FiatService): SdkBuilder;
     withKeySet(config: KeySetConfig): SdkBuilder;
     withLnurlClient(lnurl_client: RestClient): SdkBuilder;
+    /**
+     * **Deprecated.** Call `withMysqlConnectionPool(config)` and `withMysqlConnectionPool(pool)` instead.
+     */
     withMysqlBackend(config: MysqlStorageConfig): SdkBuilder;
+    /**
+     * Sets a shared `MySQL` connection pool as the backend for all stores.
+     * Construct via `createMysqlConnectionPool` and pass the same handle to multiple
+     * `SdkBuilder`s to share connections across SDKs.
+     */
+    withMysqlConnectionPool(pool: MysqlConnectionPool): SdkBuilder;
     withPaymentObserver(payment_observer: PaymentObserver): SdkBuilder;
+    /**
+     * **Deprecated.** Call `withPostgresConnectionPool(config)` and `withPostgresConnectionPool(pool)` instead.
+     */
     withPostgresBackend(config: PostgresStorageConfig): SdkBuilder;
+    /**
+     * Sets a shared `PostgreSQL` connection pool as the backend for all
+     * stores. Construct via `createPostgresConnectionPool` and pass the same handle
+     * to multiple `SdkBuilder`s to share connections across SDKs.
+     */
+    withPostgresConnectionPool(pool: PostgresConnectionPool): SdkBuilder;
     withRestChainService(url: string, api_type: ChainApiType, credentials?: Credentials | null): SdkBuilder;
+    /**
+     * Sets a custom session manager used to persist authentication sessions.
+     *
+     * Provide a shared, persistent implementation (e.g. backed by `PostgreSQL`
+     * or Redis) to let multiple SDK instances share authentication state and
+     * bootstrap quickly. If not set, an in-memory session manager is used.
+     */
+    withSessionManager(session_manager: SessionManager): SdkBuilder;
+    /**
+     * Reuses a shared SSP connection across SDK instances. Pass the same
+     * manager to every `SdkBuilder` whose SSP traffic should share an
+     * underlying HTTP client.
+     */
+    withSspConnectionManager(manager: SspConnectionManager): SdkBuilder;
     withStorage(storage: Storage): SdkBuilder;
 }
 
+/**
+ * Shared transport for SSP GraphQL traffic across SDK instances.
+ *
+ * All SDK instances built with the same `SspConnectionManager` share a single
+ * underlying HTTP client (and its h2 connection pool) for SSP requests.
+ */
+export class SspConnectionManager {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
 export class TokenIssuer {
     private constructor();
     free(): void;
@@ -1565,6 +1666,16 @@ export function connect(request: ConnectRequest): Promise<BreezSdk>;
 
 export function connectWithSigner(config: Config, signer: ExternalSigner, storage_dir: string): Promise<BreezSdk>;
 
+/**
+ * Creates a shareable MySQL connection pool from the given config.
+ */
+export function createMysqlConnectionPool(config: MysqlStorageConfig): MysqlConnectionPool;
+
+/**
+ * Creates a shareable Postgres connection pool from the given config.
+ */
+export function createPostgresConnectionPool(config: PostgresStorageConfig): PostgresConnectionPool;
+
 export function defaultConfig(network: Network): Config;
 
 export function defaultExternalSigner(mnemonic: string, passphrase: string | null | undefined, network: Network, key_set_config?: KeySetConfig | null): DefaultSigner;
@@ -1598,6 +1709,19 @@ export function getSparkStatus(): Promise<SparkStatus>;
 
 export function initLogging(logger: Logger, filter?: string | null): Promise<void>;
 
+/**
+ * Constructs a shareable REST-based Bitcoin chain service.
+ *
+ * Pass the returned chain service to multiple `SdkBuilder`s via
+ * `withChainService` to reuse one HTTP client across SDK instances. All
+ * SDKs sharing the chain service must use the same `network`.
+ *
+ * For one-off, non-shared use, prefer `withRestChainService`.
+ */
+export function newRestChainService(url: string, network: Network, api_type: ChainApiType, credentials?: Credentials | null): BitcoinChainService;
+
+export function newSspConnectionManager(user_agent?: string | null): SspConnectionManager;
+
 /**
  * Entry point invoked by JavaScript in a worker.
  */
@@ -1607,11 +1731,19 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_bitcoinchainservicehandle_free: (a: number, b: number) => void;
     readonly __wbg_breezsdk_free: (a: number, b: number) => void;
     readonly __wbg_defaultsigner_free: (a: number, b: number) => void;
+    readonly __wbg_mysqlconnectionpool_free: (a: number, b: number) => void;
     readonly __wbg_passkey_free: (a: number, b: number) => void;
     readonly __wbg_sdkbuilder_free: (a: number, b: number) => void;
+    readonly __wbg_sspconnectionmanager_free: (a: number, b: number) => void;
     readonly __wbg_tokenissuer_free: (a: number, b: number) => void;
+    readonly bitcoinchainservicehandle_broadcastTransaction: (a: number, b: number, c: number) => any;
+    readonly bitcoinchainservicehandle_getAddressUtxos: (a: number, b: number, c: number) => any;
+    readonly bitcoinchainservicehandle_getTransactionHex: (a: number, b: number, c: number) => any;
+    readonly bitcoinchainservicehandle_getTransactionStatus: (a: number, b: number, c: number) => any;
+    readonly bitcoinchainservicehandle_recommendedFees: (a: number) => any;
     readonly breezsdk_addContact: (a: number, b: any) => any;
     readonly breezsdk_addEventListener: (a: number, b: any) => any;
     readonly breezsdk_buyBitcoin: (a: number, b: any) => any;
@@ -1658,6 +1790,8 @@ export interface InitOutput {
     readonly breezsdk_updateUserSettings: (a: number, b: any) => any;
     readonly connect: (a: any) => any;
     readonly connectWithSigner: (a: any, b: any, c: number, d: number) => any;
+    readonly createMysqlConnectionPool: (a: any) => [number, number, number];
+    readonly createPostgresConnectionPool: (a: any) => [number, number, number];
     readonly defaultConfig: (a: any) => any;
     readonly defaultExternalSigner: (a: number, b: number, c: number, d: number, e: any, f: number) => [number, number, number];
     readonly defaultMysqlStorageConfig: (a: number, b: number) => any;
@@ -1683,6 +1817,8 @@ export interface InitOutput {
     readonly defaultsigner_subtractSecrets: (a: number, b: any, c: any) => any;
     readonly getSparkStatus: () => any;
     readonly initLogging: (a: any, b: number, c: number) => any;
+    readonly newRestChainService: (a: number, b: number, c: any, d: any, e: number) => number;
+    readonly newSspConnectionManager: (a: number, b: number) => number;
     readonly passkey_getWallet: (a: number, b: number, c: number) => any;
     readonly passkey_isAvailable: (a: number) => any;
     readonly passkey_listLabels: (a: number) => any;
@@ -1696,10 +1832,14 @@ export interface InitOutput {
     readonly sdkbuilder_withFiatService: (a: number, b: any) => number;
     readonly sdkbuilder_withKeySet: (a: number, b: any) => number;
     readonly sdkbuilder_withLnurlClient: (a: number, b: any) => number;
-    readonly sdkbuilder_withMysqlBackend: (a: number, b: any) => number;
+    readonly sdkbuilder_withMysqlBackend: (a: number, b: any) => [number, number, number];
+    readonly sdkbuilder_withMysqlConnectionPool: (a: number, b: number) => number;
     readonly sdkbuilder_withPaymentObserver: (a: number, b: any) => number;
-    readonly sdkbuilder_withPostgresBackend: (a: number, b: any) => number;
+    readonly sdkbuilder_withPostgresBackend: (a: number, b: any) => [number, number, number];
+    readonly sdkbuilder_withPostgresConnectionPool: (a: number, b: number) => number;
     readonly sdkbuilder_withRestChainService: (a: number, b: number, c: number, d: any, e: number) => number;
+    readonly sdkbuilder_withSessionManager: (a: number, b: any) => number;
+    readonly sdkbuilder_withSspConnectionManager: (a: number, b: number) => number;
     readonly sdkbuilder_withStorage: (a: number, b: any) => number;
     readonly tokenissuer_burnIssuerToken: (a: number, b: any) => any;
     readonly tokenissuer_createIssuerToken: (a: number, b: any) => any;
@@ -1726,16 +1866,18 @@ export interface InitOutput {
     readonly intounderlyingsink_write: (a: number, b: any) => any;
     readonly intounderlyingsource_cancel: (a: number) => void;
     readonly intounderlyingsource_pull: (a: number, b: any) => any;
+    readonly __wbg_postgresconnectionpool_free: (a: number, b: number) => void;
     readonly defaultPostgresStorageConfig: (a: number, b: number) => any;
-    readonly wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7_4: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7_5: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h27d08ee20b1285c7_6: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_4: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_5: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_6: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h459c42c6ffe5f52c_7: (a: number, b: number, c: any) => [number, number];
     readonly wasm_bindgen__convert__closures_____invoke__h41057d61edf43a32: (a: number, b: number, c: any, d: any) => void;
     readonly wasm_bindgen__convert__closures_____invoke__h4819aba3eed2db57: (a: number, b: number, c: any) => void;
     readonly wasm_bindgen__convert__closures_____invoke__h4819aba3eed2db57_2: (a: number, b: number, c: any) => void;
     readonly wasm_bindgen__convert__closures_____invoke__h4819aba3eed2db57_3: (a: number, b: number, c: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h484cd36e13f37bd7: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h124479769cd429fd: (a: number, b: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;