@breeztech/breez-sdk-spark 0.15.1 → 0.16.1-dev1

package/nodejs/{postgres-session-manager → postgres-session-store}/index.cjs

@@ -1,7 +1,7 @@
 /**
- * CommonJS implementation for Node.js PostgreSQL Session Manager.
+ * CommonJS implementation for Node.js PostgreSQL Session Store.
  *
- * Implements the JS-side `SessionManager` interface consumed by the Breez
+ * Implements the JS-side `SessionStore` 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.
@@ -29,10 +29,10 @@ try {
   }
 }
 
-const { SessionManagerError } = require("./errors.cjs");
-const { SessionManagerMigrationManager } = require("./migrations.cjs");
+const { SessionStoreError } = require("./errors.cjs");
+const { SessionStoreMigrationManager } = require("./migrations.cjs");
 
-class PostgresSessionManager {
+class PostgresSessionStore {
   /**
    * @param {import('pg').Pool} pool
    * @param {Buffer|Uint8Array} identity - 33-byte secp256k1 compressed pubkey
@@ -41,7 +41,7 @@ class PostgresSessionManager {
    */
   constructor(pool, identity, logger = null, runMigration = true) {
     if (!identity || identity.length !== 33) {
-      throw new SessionManagerError(
+      throw new SessionStoreError(
         "tenant identity (33-byte secp256k1 pubkey) is required"
       );
     }
@@ -54,13 +54,13 @@ class PostgresSessionManager {
   async initialize() {
     try {
       if (this.runMigration) {
-        const migrationManager = new SessionManagerMigrationManager(this.logger);
+        const migrationManager = new SessionStoreMigrationManager(this.logger);
         await migrationManager.migrate(this.pool);
       }
       return this;
     } catch (error) {
-      throw new SessionManagerError(
-        `Failed to initialize PostgreSQL session manager: ${error.message}`,
+      throw new SessionStoreError(
+        `Failed to initialize PostgreSQL session store: ${error.message}`,
         error
       );
     }
@@ -76,7 +76,7 @@ class PostgresSessionManager {
   /**
    * 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`.
+   * `SessionStoreError::NotFound`.
    * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
    * @returns {Promise<{token: string, expiration: number} | null>}
    */
@@ -97,7 +97,7 @@ class PostgresSessionManager {
         expiration: Number(row.expiration),
       };
     } catch (error) {
-      throw new SessionManagerError(
+      throw new SessionStoreError(
         `Failed to read session: ${error.message}`,
         error
       );
@@ -120,7 +120,7 @@ class PostgresSessionManager {
         [this.identity, serviceKey, session.token, session.expiration]
       );
     } catch (error) {
-      throw new SessionManagerError(
+      throw new SessionStoreError(
         `Failed to write session: ${error.message}`,
         error
       );
@@ -130,7 +130,7 @@ class PostgresSessionManager {
 
 function _decodePubkey(hex) {
   if (typeof hex !== "string" || hex.length !== 66) {
-    throw new SessionManagerError(
+    throw new SessionStoreError(
       "service_identity_key must be a 66-character hex-encoded 33-byte pubkey"
     );
   }
@@ -139,13 +139,13 @@ function _decodePubkey(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
+ * initialized `PostgresSessionStore`. Most callers should use
+ * `createPostgresSessionStoreWithPool` instead so the pool can be shared
  * across stores.
  */
-async function createPostgresSessionManager(poolConfig, identity, logger = null) {
+async function createPostgresSessionStore(poolConfig, identity, logger = null) {
   const pool = new pg.Pool(poolConfig);
-  const manager = new PostgresSessionManager(
+  const manager = new PostgresSessionStore(
     pool,
     identity,
     logger,
@@ -159,13 +159,13 @@ async function createPostgresSessionManager(poolConfig, identity, logger = null)
  * Wraps an existing pool — useful when sharing the pool with the storage,
  * tree store, and token store implementations.
  */
-async function createPostgresSessionManagerWithPool(
+async function createPostgresSessionStoreWithPool(
   pool,
   identity,
   logger = null,
   runMigration = true
 ) {
-  const manager = new PostgresSessionManager(
+  const manager = new PostgresSessionStore(
     pool,
     identity,
     logger,
@@ -176,8 +176,8 @@ async function createPostgresSessionManagerWithPool(
 }
 
 module.exports = {
-  PostgresSessionManager,
-  createPostgresSessionManager,
-  createPostgresSessionManagerWithPool,
-  SessionManagerError,
+  PostgresSessionStore,
+  createPostgresSessionStore,
+  createPostgresSessionStoreWithPool,
+  SessionStoreError,
 };

package/nodejs/{postgres-session-manager → postgres-session-store}/migrations.cjs

@@ -1,22 +1,22 @@
 /**
- * Database Migration Manager for Breez SDK PostgreSQL Session Manager.
+ * Database Migration Manager for Breez SDK PostgreSQL Session Store.
  *
  * Uses a brz_session_schema_migrations table + pg_advisory_xact_lock to safely
  * run migrations from concurrent processes. Mirrors the schema produced by
- * the Rust `PostgresSessionManager`.
+ * the Rust `PostgresSessionStore`.
  */
 
-const { SessionManagerError } = require("./errors.cjs");
+const { SessionStoreError } = require("./errors.cjs");
 
 /**
- * Advisory lock ID for session-manager migrations.
+ * Advisory lock ID for session-store 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 {
+class SessionStoreMigrationManager {
   constructor(logger = null) {
     this.logger = logger;
   }
@@ -51,7 +51,7 @@ class SessionManagerMigrationManager {
       if (currentVersion >= migrations.length) {
         this._log(
           "info",
-          `Session manager database is up to date (version ${currentVersion})`
+          `Session store database is up to date (version ${currentVersion})`
         );
         await client.query("COMMIT");
         return;
@@ -59,7 +59,7 @@ class SessionManagerMigrationManager {
 
       this._log(
         "info",
-        `Migrating session manager database from version ${currentVersion} to ${migrations.length}`
+        `Migrating session store database from version ${currentVersion} to ${migrations.length}`
       );
 
       for (let i = currentVersion; i < migrations.length; i++) {
@@ -67,7 +67,7 @@ class SessionManagerMigrationManager {
         const version = i + 1;
         this._log(
           "debug",
-          `Running session manager migration ${version}: ${migration.name}`
+          `Running session store migration ${version}: ${migration.name}`
         );
 
         for (const sql of migration.sql) {
@@ -83,12 +83,12 @@ class SessionManagerMigrationManager {
       await client.query("COMMIT");
       this._log(
         "info",
-        "Session manager database migration completed successfully"
+        "Session store database migration completed successfully"
       );
     } catch (error) {
       await client.query("ROLLBACK").catch(() => {});
-      throw new SessionManagerError(
-        `Session manager migration failed: ${error.message}`,
+      throw new SessionStoreError(
+        `Session store migration failed: ${error.message}`,
         error
       );
     } finally {
@@ -137,12 +137,12 @@ class SessionManagerMigrationManager {
     if (this.logger && typeof this.logger.log === "function") {
       this.logger.log({ line: message, level });
     } else if (level === "error") {
-      console.error(`[SessionManagerMigrationManager] ${message}`);
+      console.error(`[SessionStoreMigrationManager] ${message}`);
     }
   }
 
   /**
-   * Migrations matching the Rust PostgresSessionManager schema exactly.
+   * Migrations matching the Rust PostgresSessionStore schema exactly.
    */
   _getMigrations() {
     return [
@@ -162,4 +162,4 @@ class SessionManagerMigrationManager {
   }
 }
 
-module.exports = { SessionManagerMigrationManager };
+module.exports = { SessionStoreMigrationManager };

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

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

package/nodejs/postgres-storage/index.cjs

@@ -2,6 +2,8 @@
  * CommonJS implementation for Node.js PostgreSQL Storage
  */
 
+const crypto = require("crypto");
+
 let pg;
 try {
   const mainModule = require.main;
@@ -38,7 +40,8 @@ const SELECT_PAYMENT_SQL = `
            p.timestamp,
            p.method,
            p.withdraw_tx_id,
-           p.deposit_tx_id,
+           pd.tx_id AS deposit_tx_id,
+           pd.vout AS deposit_vout,
            p.spark,
            l.invoice AS lightning_invoice,
            l.payment_hash AS lightning_payment_hash,
@@ -66,6 +69,7 @@ const SELECT_PAYMENT_SQL = `
       LEFT JOIN brz_payment_details_lightning l ON p.id = l.payment_id AND p.user_id = l.user_id
       LEFT JOIN brz_payment_details_token t ON p.id = t.payment_id AND p.user_id = t.user_id
       LEFT JOIN brz_payment_details_spark s ON p.id = s.payment_id AND p.user_id = s.user_id
+      LEFT JOIN brz_payment_details_deposit pd ON p.id = pd.payment_id AND p.user_id = pd.user_id
       LEFT JOIN brz_payment_metadata pm ON p.id = pm.payment_id AND p.user_id = pm.user_id
       LEFT JOIN brz_lnurl_receive_metadata lrm ON l.payment_hash = lrm.payment_hash AND l.user_id = lrm.user_id`;
 
@@ -353,130 +357,192 @@ class PostgresStorage {
     }
   }
 
-  async insertPayment(payment) {
-    try {
-      if (!payment) {
-        throw new StorageError("Payment cannot be null or undefined");
-      }
-
-      await this._withTransaction(async (client) => {
-        const withdrawTxId =
-          payment.details?.type === "withdraw" ? payment.details.txId : null;
-        const depositTxId =
-          payment.details?.type === "deposit" ? payment.details.txId : null;
-        const spark = payment.details?.type === "spark" ? true : null;
+  async applyPaymentUpdate(payment) {
+    if (!payment) {
+      throw new StorageError("Payment cannot be null or undefined");
+    }
 
+    try {
+      return await this._withTransaction(async (client) => {
+        const lockKey = this._paymentUpdateLockKey(payment.id);
         await client.query(
-          `INSERT INTO brz_payments (user_id, id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, deposit_tx_id, spark)
-           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
-           ON CONFLICT(user_id, id) DO UPDATE SET
-             payment_type=EXCLUDED.payment_type,
-             status=EXCLUDED.status,
-             amount=EXCLUDED.amount,
-             fees=EXCLUDED.fees,
-             timestamp=EXCLUDED.timestamp,
-             method=EXCLUDED.method,
-             withdraw_tx_id=EXCLUDED.withdraw_tx_id,
-             deposit_tx_id=EXCLUDED.deposit_tx_id,
-             spark=EXCLUDED.spark`,
-          [
-            this.identity,
-            payment.id,
-            payment.paymentType,
-            payment.status,
-            payment.amount.toString(),
-            payment.fees.toString(),
-            payment.timestamp,
-            payment.method ? JSON.stringify(payment.method) : null,
-            withdrawTxId,
-            depositTxId,
-            spark,
-          ]
+          "SELECT pg_advisory_xact_lock($1::bigint)",
+          [lockKey]
         );
 
-        if (
-          payment.details?.type === "spark" &&
-          (payment.details.invoiceDetails != null ||
-            payment.details.htlcDetails != null)
-        ) {
-          await client.query(
-            `INSERT INTO brz_payment_details_spark (user_id, payment_id, invoice_details, htlc_details)
-             VALUES ($1, $2, $3, $4)
-             ON CONFLICT(user_id, payment_id) DO UPDATE SET
-               invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_spark.invoice_details),
-               htlc_details=COALESCE(EXCLUDED.htlc_details, brz_payment_details_spark.htlc_details)`,
-            [
-              this.identity,
-              payment.id,
-              payment.details.invoiceDetails
-                ? JSON.stringify(payment.details.invoiceDetails)
-                : null,
-              payment.details.htlcDetails
-                ? JSON.stringify(payment.details.htlcDetails)
-                : null,
-            ]
-          );
-        }
-
-        if (payment.details?.type === "lightning") {
-          await client.query(
-            `INSERT INTO brz_payment_details_lightning
-              (user_id, payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
-              VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
-              ON CONFLICT(user_id, payment_id) DO UPDATE SET
-                invoice=EXCLUDED.invoice,
-                payment_hash=EXCLUDED.payment_hash,
-                destination_pubkey=EXCLUDED.destination_pubkey,
-                description=EXCLUDED.description,
-                preimage=COALESCE(EXCLUDED.preimage, brz_payment_details_lightning.preimage),
-                htlc_status=COALESCE(EXCLUDED.htlc_status, brz_payment_details_lightning.htlc_status),
-                htlc_expiry_time=COALESCE(EXCLUDED.htlc_expiry_time, brz_payment_details_lightning.htlc_expiry_time)`,
-            [
-              this.identity,
-              payment.id,
-              payment.details.invoice,
-              payment.details.htlcDetails.paymentHash,
-              payment.details.destinationPubkey,
-              payment.details.description,
-              payment.details.htlcDetails?.preimage,
-              payment.details.htlcDetails?.status ?? null,
-              payment.details.htlcDetails?.expiryTime ?? 0,
-            ]
+        const { rows } = await client.query(
+          "SELECT status FROM brz_payments WHERE user_id = $1 AND id = $2 FOR UPDATE",
+          [this.identity, payment.id]
+        );
+        const stored = rows.length > 0
+          ? this._normalizePaymentStatus(rows[0].status)
+          : null;
+        const next = this._normalizePaymentStatus(payment.status);
+
+        if (stored != null
+            && this._isFinalPaymentStatus(stored)
+            && stored !== next) {
+          console.warn(
+            `Skipping payment update (would replace terminal status): id=${payment.id} stored=${stored} new=${next}`
           );
+          return false;
         }
 
-        if (payment.details?.type === "token") {
-          await client.query(
-            `INSERT INTO brz_payment_details_token
-              (user_id, payment_id, metadata, tx_hash, tx_type, invoice_details)
-              VALUES ($1, $2, $3, $4, $5, $6)
-              ON CONFLICT(user_id, payment_id) DO UPDATE SET
-                metadata=EXCLUDED.metadata,
-                tx_hash=EXCLUDED.tx_hash,
-                tx_type=EXCLUDED.tx_type,
-                invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_token.invoice_details)`,
-            [
-              this.identity,
-              payment.id,
-              JSON.stringify(payment.details.metadata),
-              payment.details.txHash,
-              payment.details.txType,
-              payment.details.invoiceDetails
-                ? JSON.stringify(payment.details.invoiceDetails)
-                : null,
-            ]
+        const sameStatus = stored === next;
+        if (sameStatus) {
+          console.debug(
+            `Skipping redundant payment event: id=${payment.id} status=${next}`
           );
         }
+        await this._runPaymentUpsert(client, payment);
+        return !sameStatus;
       });
     } catch (error) {
       if (error instanceof StorageError) throw error;
       throw new StorageError(
-        `Failed to insert payment '${payment.id}': ${error.message}`,
+        `Failed to apply payment update '${payment.id}': ${error.message}`,
         error
       );
     }
   }
 
+  _paymentUpdateLockKey(paymentId) {
+    return crypto
+      .createHash("sha256")
+      .update("brz_payment_update")
+      .update(this.identity)
+      .update(Buffer.from(paymentId))
+      .digest()
+      .readBigInt64BE(0)
+      .toString();
+  }
+
+  async _runPaymentUpsert(client, payment) {
+    const withdrawTxId =
+      payment.details?.type === "withdraw" ? payment.details.txId : null;
+    const spark = payment.details?.type === "spark" ? true : null;
+
+    await client.query(
+      `INSERT INTO brz_payments (user_id, id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, spark)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       ON CONFLICT(user_id, id) DO UPDATE SET
+         payment_type=EXCLUDED.payment_type,
+         status=EXCLUDED.status,
+         amount=EXCLUDED.amount,
+         fees=EXCLUDED.fees,
+         timestamp=EXCLUDED.timestamp,
+         method=EXCLUDED.method,
+         withdraw_tx_id=EXCLUDED.withdraw_tx_id,
+         spark=EXCLUDED.spark`,
+      [
+        this.identity,
+        payment.id,
+        payment.paymentType,
+        payment.status,
+        payment.amount.toString(),
+        payment.fees.toString(),
+        payment.timestamp,
+        payment.method ? JSON.stringify(payment.method) : null,
+        withdrawTxId,
+        spark,
+      ]
+    );
+
+    if (payment.details?.type === "deposit") {
+      await client.query(
+        `INSERT INTO brz_payment_details_deposit (user_id, payment_id, tx_id, vout)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT(user_id, payment_id) DO UPDATE SET
+           tx_id=EXCLUDED.tx_id,
+           vout=EXCLUDED.vout`,
+        [this.identity, payment.id, payment.details.txId, payment.details.vout]
+      );
+    }
+
+    if (
+      payment.details?.type === "spark" &&
+      (payment.details.invoiceDetails != null ||
+        payment.details.htlcDetails != null)
+    ) {
+      await client.query(
+        `INSERT INTO brz_payment_details_spark (user_id, payment_id, invoice_details, htlc_details)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT(user_id, payment_id) DO UPDATE SET
+           invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_spark.invoice_details),
+           htlc_details=COALESCE(EXCLUDED.htlc_details, brz_payment_details_spark.htlc_details)`,
+        [
+          this.identity,
+          payment.id,
+          payment.details.invoiceDetails
+            ? JSON.stringify(payment.details.invoiceDetails)
+            : null,
+          payment.details.htlcDetails
+            ? JSON.stringify(payment.details.htlcDetails)
+            : null,
+        ]
+      );
+    }
+
+    if (payment.details?.type === "lightning") {
+      await client.query(
+        `INSERT INTO brz_payment_details_lightning
+          (user_id, payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
+          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+          ON CONFLICT(user_id, payment_id) DO UPDATE SET
+            invoice=EXCLUDED.invoice,
+            payment_hash=EXCLUDED.payment_hash,
+            destination_pubkey=EXCLUDED.destination_pubkey,
+            description=EXCLUDED.description,
+            preimage=COALESCE(EXCLUDED.preimage, brz_payment_details_lightning.preimage),
+            htlc_status=COALESCE(EXCLUDED.htlc_status, brz_payment_details_lightning.htlc_status),
+            htlc_expiry_time=COALESCE(EXCLUDED.htlc_expiry_time, brz_payment_details_lightning.htlc_expiry_time)`,
+        [
+          this.identity,
+          payment.id,
+          payment.details.invoice,
+          payment.details.htlcDetails.paymentHash,
+          payment.details.destinationPubkey,
+          payment.details.description,
+          payment.details.htlcDetails?.preimage,
+          payment.details.htlcDetails?.status ?? null,
+          payment.details.htlcDetails?.expiryTime ?? 0,
+        ]
+      );
+    }
+
+    if (payment.details?.type === "token") {
+      await client.query(
+        `INSERT INTO brz_payment_details_token
+          (user_id, payment_id, metadata, tx_hash, tx_type, invoice_details)
+          VALUES ($1, $2, $3, $4, $5, $6)
+          ON CONFLICT(user_id, payment_id) DO UPDATE SET
+            metadata=EXCLUDED.metadata,
+            tx_hash=EXCLUDED.tx_hash,
+            tx_type=EXCLUDED.tx_type,
+            invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_token.invoice_details)`,
+        [
+          this.identity,
+          payment.id,
+          JSON.stringify(payment.details.metadata),
+          payment.details.txHash,
+          payment.details.txType,
+          payment.details.invoiceDetails
+            ? JSON.stringify(payment.details.invoiceDetails)
+            : null,
+        ]
+      );
+    }
+  }
+
+  _normalizePaymentStatus(status) {
+    return typeof status === "string" ? status.toLowerCase() : status;
+  }
+
+  _isFinalPaymentStatus(status) {
+    const normalized = this._normalizePaymentStatus(status);
+    return normalized === "completed" || normalized === "failed";
+  }
+
   async getPaymentById(id) {
     try {
       if (!id) {
@@ -778,6 +844,7 @@ class PostgresStorage {
       details = {
         type: "deposit",
         txId: row.deposit_tx_id,
+        vout: Number(row.deposit_vout),
       };
     } else if (row.spark) {
       details = {

package/nodejs/postgres-storage/migrations.cjs

@@ -467,6 +467,30 @@ class PostgresMigrationManager {
              ON brz_sync_incoming(user_id, revision)`,
         ],
       },
+      {
+        // Move deposit details into their own table so vout can be NOT NULL and
+        // the schema matches brz_payment_details_lightning / _token / _spark. We
+        // can't safely backfill the new table from the dropped deposit_tx_id
+        // column: we never stored the original SSP output_index, and vout=0 is a
+        // valid output index — defaulting would silently mislabel. Drop the
+        // column and leave the brz_payments row in place. The read path sees an
+        // unjoined deposit row as `details: None` until the resync re-fetches the
+        // SSP user_request and the upsert inserts the new details row.
+        name: "Move deposit details into brz_payment_details_deposit table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS brz_payment_details_deposit (
+              user_id BYTEA NOT NULL,
+              payment_id TEXT NOT NULL,
+              tx_id TEXT NOT NULL,
+              vout BIGINT NOT NULL,
+              PRIMARY KEY (user_id, payment_id)
+          )`,
+          `ALTER TABLE brz_payments DROP COLUMN IF EXISTS deposit_tx_id`,
+          `UPDATE brz_settings
+           SET value = jsonb_set(value::jsonb, '{offset}', '0')::text
+           WHERE key = 'sync_offset' AND value IS NOT NULL`,
+        ],
+      },
     ];
   }
 }