@breeztech/breez-sdk-spark 0.27.2 → 0.27.3-dev

package/web/storage/index.js

@@ -27,7 +27,7 @@ class MigrationManager {
     const transaction = event.target.transaction;
 
     this._log(
-      "info",
+      "INFO",
       `Upgrading IndexedDB from version ${oldVersion} to ${newVersion}`
     );
 
@@ -35,14 +35,14 @@ class MigrationManager {
       for (let i = oldVersion; i < newVersion; i++) {
         const migration = this.migrations[i];
         if (migration) {
-          this._log("debug", `Running migration ${i + 1}: ${migration.name}`);
+          this._log("DEBUG", `Running migration ${i + 1}: ${migration.name}`);
           migration.upgrade(db, transaction);
         }
       }
-      this._log("info", `Database migration completed successfully`);
+      this._log("INFO", `Database migration completed successfully`);
     } catch (error) {
       this._log(
-        "error",
+        "ERROR",
         `Migration failed at version ${oldVersion}: ${error.message}`
       );
       throw new this.StorageError(
@@ -53,14 +53,7 @@ class MigrationManager {
   }
 
   _log(level, message) {
-    if (this.logger && typeof this.logger.log === "function") {
-      this.logger.log({
-        line: message,
-        level: level,
-      });
-    } else if (level === "error") {
-      console.error(`[MigrationManager] ${message}`);
-    }
+    this.logger?.log({ line: message, level });
   }
 
   /**
@@ -149,7 +142,7 @@ class MigrationManager {
               }
             });
 
-            console.log(`Migrated ${updated} payment records to BigInt format`);
+            this._log("INFO", `Migrated ${updated} payment records to BigInt format`);
           };
         },
       },
@@ -653,6 +646,77 @@ class MigrationManager {
           }
         },
       },
+      {
+        // A withdrawal stored before the SDK kept its destination address and
+        // output index loses its details, which the SDK cannot rebuild here.
+        // With the sync offset at 0, the SDK re-fetches every transfer on its
+        // next sync and rewrites past withdrawals with both values.
+        name: "Clear legacy withdrawal details and reset sync offset",
+        upgrade: (db, transaction) => {
+          if (db.objectStoreNames.contains("payments")) {
+            const paymentStore = transaction.objectStore("payments");
+            // The cursor opens from a callback, so it reads the payments after
+            // the earlier steps of this upgrade have written theirs.
+            paymentStore.count().onsuccess = () => {
+              const cursorRequest = paymentStore.openCursor();
+              cursorRequest.onsuccess = (event) => {
+                const cursor = event.target.result;
+                if (!cursor) return;
+                const payment = cursor.value;
+                let details = null;
+                if (payment.details && typeof payment.details === "string") {
+                  try {
+                    details = JSON.parse(payment.details);
+                  } catch (e) {
+                    details = null;
+                  }
+                } else {
+                  details = payment.details;
+                }
+                if (
+                  details &&
+                  details.type === "withdraw" &&
+                  (details.vout == null || details.destinationAddress == null)
+                ) {
+                  payment.details = null;
+                  cursor.update(payment);
+                }
+                cursor.continue();
+              };
+            };
+          }
+          if (!db.objectStoreNames.contains("settings")) {
+            return;
+          }
+          const settingsStore = transaction.objectStore("settings");
+          const getRequest = settingsStore.get("sync_offset");
+          getRequest.onsuccess = () => {
+            const syncCache = getRequest.result;
+            if (!syncCache || !syncCache.value) {
+              return;
+            }
+            try {
+              const syncInfo = JSON.parse(syncCache.value);
+              syncInfo.offset = 0;
+              settingsStore.put({
+                key: "sync_offset",
+                value: toJson(syncInfo),
+              });
+            } catch (e) {
+              // If parsing fails, just continue
+            }
+          };
+        },
+      },
+      {
+        name: "Force lnurl_receive_metadata re-sync for the lightning address",
+        upgrade: (db, transaction) => {
+          if (db.objectStoreNames.contains("settings")) {
+            const settings = transaction.objectStore("settings");
+            settings.delete("lnurl_metadata_updated_after");
+          }
+        },
+      },
     ];
   }
 }
@@ -681,7 +745,7 @@ class IndexedDBStorage {
     // so existing databases depend on indices never shifting. Never insert,
     // reorder, or delete a migration — only append. dbVersion MUST equal the
     // number of migrations (enforced by the guard in initialize()).
-    this.dbVersion = 23; // Current schema version (= migration count)
+    this.dbVersion = 25; // Current schema version (= migration count)
   }
 
   /**
@@ -1071,13 +1135,15 @@ class IndexedDBStorage {
           shouldPersist = true;
           shouldEmit = true;
         } else if (stored === next) {
-          console.debug(
+          this._log(
+            "DEBUG",
             `Skipping redundant payment event: id=${payment.id} status=${next}`
           );
           shouldPersist = true;
           shouldEmit = false;
         } else if (this._isFinalPaymentStatus(stored)) {
-          console.warn(
+          this._log(
+            "WARN",
             `Skipping payment update (would replace terminal status): id=${payment.id} stored=${stored} new=${next}`
           );
           shouldPersist = false;
@@ -1293,7 +1359,7 @@ class IndexedDBStorage {
   /**
    * Gets payments that have any of the specified parent payment IDs.
    * @param {string[]} parentPaymentIds - Array of parent payment IDs
-   * @returns {Promise<Object>} Map of parentPaymentId -> array of RelatedPayment objects
+   * @returns {Promise<Object>} Map of parentPaymentId -> array of Payment objects
    */
   async getPaymentsByParentIds(parentPaymentIds) {
     if (!this.db) {
@@ -2007,6 +2073,7 @@ class IndexedDBStorage {
           nostrZapRequest: item.nostrZapRequest || null,
           nostrZapReceipt: item.nostrZapReceipt || null,
           senderComment: item.senderComment || null,
+          lightningAddress: item.lightningAddress || null,
         });
 
         request.onsuccess = () => {
@@ -2725,6 +2792,10 @@ class IndexedDBStorage {
     };
   }
 
+  _log(level, line) {
+    this.logger?.log({ line, level });
+  }
+
   _normalizePaymentStatus(status) {
     return typeof status === "string" ? status.toLowerCase() : status;
   }
@@ -3040,6 +3111,7 @@ class IndexedDBStorage {
             nostrZapRequest: lnurlReceiveMetadata.nostrZapRequest || null,
             nostrZapReceipt: lnurlReceiveMetadata.nostrZapReceipt || null,
             senderComment: lnurlReceiveMetadata.senderComment || null,
+            lightningAddress: lnurlReceiveMetadata.lightningAddress || null,
           };
         }
         resolve(payment);

package/itest/.gitignore

@@ -1,2 +0,0 @@
-node_modules/
-.env

package/itest/database-drivers.test.js

@@ -1,45 +0,0 @@
-'use strict'
-
-// This project installs neither `pg` nor `mysql2`. The package loads without
-// a warning about them, and tells an app that selects PostgreSQL or MySQL
-// storage which driver to install. No network.
-
-const assert = require('node:assert/strict')
-const test = require('node:test')
-
-// The package prints its warnings on the first require in a process.
-const warnings = []
-const consoleWarn = console.warn
-console.warn = (...args) => warnings.push(args.join(' '))
-const {
-  SdkBuilder,
-  defaultConfig,
-  defaultMysqlStorageConfig,
-  defaultPostgresStorageConfig,
-  mysqlStorage,
-  postgresStorage,
-} = require('@breeztech/breez-sdk-spark/nodejs')
-console.warn = consoleWarn
-
-function buildWith(storage) {
-  const mnemonic = require('bip39').generateMnemonic()
-  const builder = SdkBuilder.new(defaultConfig('regtest'), { type: 'mnemonic', mnemonic })
-  return builder.withStorageBackend(storage).build()
-}
-
-test('loading the package prints no database driver warning', () => {
-  assert.deepEqual(
-    warnings.filter((warning) => /PostgreSQL|MySQL/.test(warning)),
-    []
-  )
-})
-
-test('selecting PostgreSQL storage names the missing driver', async () => {
-  const config = defaultPostgresStorageConfig('postgres://user:password@localhost:5432/spark')
-  await assert.rejects(buildWith(postgresStorage(config)), /pg not found\. Please install it/)
-})
-
-test('selecting MySQL storage names the missing driver', async () => {
-  const config = defaultMysqlStorageConfig('mysql://user:password@localhost:3306/spark')
-  await assert.rejects(buildWith(mysqlStorage(config)), /mysql2 not found\. Please install it/)
-})

package/itest/helpers/assert.test.js

@@ -1,70 +0,0 @@
-'use strict'
-
-// Pure tests for the tolerant JSON evaluator; no network. Mirrors the unit
-// tests in crates/breez-sdk/cli/tests/harness/assert.rs.
-
-const assert = require('node:assert/strict')
-const test = require('node:test')
-
-const { checkMatcher, extractJsonDocs, interpolate, lookupPath } = require('./scenario')
-
-test('extracts pretty and inline docs and skips noise', () => {
-  const chunk = 'Breez SDK: noise\n{\n  "a": 1\n}\nError: nope\n{"b": 2}\nEvent: {"c": 3}\n'
-  assert.deepEqual(extractJsonDocs(chunk), [{ a: 1 }, { b: 2 }])
-})
-
-test('path matches across casings', () => {
-  const rust = { payment_request: { amount_msat: 5 } }
-  const wasm = { paymentRequest: { amountMsat: 5 } }
-  for (const doc of [rust, wasm]) {
-    assert.equal(lookupPath(doc, 'payment_request.amount_msat'), 5)
-  }
-})
-
-test('path bridges enum tags', () => {
-  const rust = { Bolt11Invoice: { amount_msat: 7 } }
-  const wasm = { type: 'bolt11Invoice', amountMsat: 7 }
-  for (const doc of [rust, wasm]) {
-    assert.equal(lookupPath(doc, 'bolt11_invoice.amount_msat'), 7)
-  }
-})
-
-test('empty path addresses the document', () => {
-  assert.deepEqual(lookupPath({}, ''), {})
-  checkMatcher({}, lookupPath({}, ''))
-})
-
-test('path indexes arrays', () => {
-  const doc = { payments: [{ id: 'x' }, { id: 'y' }] }
-  assert.equal(lookupPath(doc, 'payments.1.id'), 'y')
-  assert.equal(lookupPath(doc, 'payments.2.id'), undefined)
-})
-
-test('equality tolerates case and bigint strings', () => {
-  checkMatcher('completed', 'Completed')
-  checkMatcher('1000', 1000)
-  checkMatcher(1000, '1000')
-  assert.throws(() => checkMatcher('completed', 'failed'))
-  assert.throws(() => checkMatcher('completed', undefined))
-})
-
-test('gte accepts numbers and numeric strings', () => {
-  checkMatcher({ gte: 10 }, 11)
-  checkMatcher({ gte: 10 }, '10')
-  assert.throws(() => checkMatcher({ gte: 10 }, 9))
-  assert.throws(() => checkMatcher({ gte: 10 }, 'abc'))
-  assert.throws(() => checkMatcher({ gte: 10 }, undefined))
-})
-
-test('exists checks presence and null', () => {
-  checkMatcher({ exists: true }, 'x')
-  checkMatcher({ exists: false }, undefined)
-  checkMatcher({ exists: false }, null)
-  assert.throws(() => checkMatcher({ exists: true }, null))
-  assert.throws(() => checkMatcher({ exists: true }, undefined))
-})
-
-test('interpolation substitutes known vars and rejects unknown', () => {
-  assert.equal(interpolate('pay -r ${addr} -a 5', { addr: 'spark1x' }), 'pay -r spark1x -a 5')
-  assert.throws(() => interpolate('${missing}', {}))
-})

package/itest/helpers/faucet.js

@@ -1,68 +0,0 @@
-'use strict'
-
-// Minimal client for the Lightspark regtest faucet, mirroring the Rust
-// harness (crates/breez-sdk/cli/tests/harness/faucet.rs).
-
-const DEFAULT_URL = 'https://api.lightspark.com/graphql/spark/rc'
-const MAX_RETRIES = 3
-
-/**
- * Fund a regtest bitcoin address, returning the funding txid. Retries with
- * exponential backoff. Reads FAUCET_URL, FAUCET_USERNAME, and
- * FAUCET_PASSWORD from the environment.
- *
- * @param {string} address
- * @param {number} amountSats
- * @returns {Promise<string>}
- */
-async function fundAddress(address, amountSats) {
-  let lastError
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    if (attempt > 0) {
-      await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 1000))
-    }
-    try {
-      return await tryFundAddress(address, amountSats)
-    } catch (e) {
-      lastError = e
-    }
-  }
-  throw lastError
-}
-
-async function tryFundAddress(address, amountSats) {
-  const url = process.env.FAUCET_URL || DEFAULT_URL
-  const headers = { 'Content-Type': 'application/json' }
-  const { FAUCET_USERNAME, FAUCET_PASSWORD } = process.env
-  if (FAUCET_USERNAME && FAUCET_PASSWORD) {
-    const credentials = Buffer.from(`${FAUCET_USERNAME}:${FAUCET_PASSWORD}`).toString('base64')
-    headers.Authorization = `Basic ${credentials}`
-  }
-
-  const response = await fetch(url, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({
-      operationName: 'RequestRegtestFunds',
-      variables: { amount_sats: amountSats, address },
-      query:
-        'mutation RequestRegtestFunds($address: String!, $amount_sats: Long!) { ' +
-        'request_regtest_funds(input: {address: $address, amount_sats: $amount_sats}) ' +
-        '{ transaction_hash}}'
-    })
-  })
-  const body = await response.text()
-  if (!response.ok) {
-    throw new Error(`faucet request failed with status ${response.status}: ${body}`)
-  }
-  const parsed = JSON.parse(body)
-  if (parsed.errors && parsed.errors.length > 0) {
-    throw new Error(`faucet returned errors: ${parsed.errors.map((e) => e.message).join(', ')}`)
-  }
-  if (!parsed.data) {
-    throw new Error(`faucet response has no data: ${body}`)
-  }
-  return parsed.data.request_regtest_funds.transaction_hash
-}
-
-module.exports = { fundAddress }

package/itest/helpers/lnurl-fixture.js

@@ -1,229 +0,0 @@
-'use strict'
-
-// LNURL server fixture driven through the docker CLI, mirroring the Rust
-// harness (crates/breez-sdk/cli/tests/harness/lnurl.rs). Shares the
-// breez-lnurl-built image tag: whichever runner builds it first wins. To
-// force a rebuild: `docker image rm breez-lnurl-built:latest`.
-
-const net = require('net')
-const path = require('path')
-const { execFile, execFileSync } = require('child_process')
-const { promisify } = require('util')
-
-const execFileAsync = promisify(execFile)
-
-const IMAGE = 'breez-lnurl-built:latest'
-const POSTGRES_IMAGE = 'postgres:16-alpine'
-const HTTP_PORT = 8080
-const POSTGRES_PORT = 5432
-const START_TIMEOUT_MS = 120_000
-const WORKSPACE_ROOT = path.join(__dirname, '../../../..')
-
-/** @returns {boolean} whether the docker daemon is reachable */
-function dockerAvailable() {
-  try {
-    execFileSync('docker', ['version'], { stdio: 'ignore' })
-    return true
-  } catch {
-    return false
-  }
-}
-
-async function docker(args, opts = {}) {
-  const { stdout } = await execFileAsync('docker', args, { maxBuffer: 64 * 1024 * 1024, ...opts })
-  return stdout
-}
-
-async function buildImageIfMissing() {
-  try {
-    await docker(['image', 'inspect', IMAGE])
-    return
-  } catch {
-    // Image missing: build it.
-  }
-  console.error(`building ${IMAGE} (first run only, this can take several minutes)`)
-  await docker([
-    'build',
-    '-f',
-    path.join(WORKSPACE_ROOT, 'crates/breez-sdk/lnurl/Dockerfile'),
-    '-t',
-    IMAGE,
-    '--build-arg',
-    'CARGO_FEATURES=dev',
-    WORKSPACE_ROOT
-  ])
-}
-
-/** @returns {Promise<number>} host port the container port was published to */
-async function publishedPort(containerId, containerPort) {
-  const portOutput = await docker(['port', containerId, `${containerPort}/tcp`])
-  return Number(portOutput.split('\n')[0].trim().split(':').pop())
-}
-
-/**
- * Resolves once something answers HTTP on `port`. Any status answers the
- * question, so this only checks that a response came back. HTTP/1.0 so the
- * server closes the connection when it is done.
- */
-function httpResponds(port) {
-  return new Promise((resolve, reject) => {
-    const socket = net.connect(port, '127.0.0.1')
-    let response = ''
-    socket.setTimeout(5000)
-    socket.on('connect', () => socket.write('GET /health HTTP/1.0\r\nHost: localhost\r\n\r\n'))
-    socket.on('data', (chunk) => {
-      response += chunk
-    })
-    socket.on('end', () =>
-      response.startsWith('HTTP/') ? resolve() : reject(new Error('no HTTP response'))
-    )
-    socket.on('timeout', () => socket.destroy(new Error('timed out')))
-    socket.on('error', reject)
-  })
-}
-
-class LnurlFixture {
-  /** @param {string} containerId @param {string} httpUrl @param {string} postgresContainerId */
-  constructor(containerId, httpUrl, postgresContainerId) {
-    this.containerId = containerId
-    this.httpUrl = httpUrl
-    // Backing database. Postgres is the server's only supported backend.
-    this.postgresContainerId = postgresContainerId
-  }
-
-  static async start() {
-    await buildImageIfMissing()
-    const fixture = new LnurlFixture('', '', '')
-    try {
-      const postgresOutput = await docker([
-        'run',
-        '-d',
-        // All interfaces rather than 127.0.0.1: the lnurl server reaches this
-        // from inside its own container through the host gateway, which on
-        // Linux is the bridge address and not loopback.
-        '-p',
-        '0.0.0.0:0:5432',
-        '-e', 'POSTGRES_PASSWORD=postgres',
-        POSTGRES_IMAGE
-      ])
-      fixture.postgresContainerId = postgresOutput.trim()
-      await fixture.waitForPostgres()
-      const dbPort = await publishedPort(fixture.postgresContainerId, POSTGRES_PORT)
-
-      const runOutput = await docker([
-        'run',
-        '-d',
-        '-p',
-        '127.0.0.1:0:8080',
-        '--add-host',
-        'host.docker.internal:host-gateway',
-        '-e', 'BREEZ_LNURL_NETWORK=regtest',
-        '-e', 'BREEZ_LNURL_AUTO_MIGRATE=true',
-        '-e', `BREEZ_LNURL_DB_URL=postgres://postgres:postgres@host.docker.internal:${dbPort}/postgres`,
-        '-e', 'BREEZ_LNURL_LOG_LEVEL=lnurl=trace,info',
-        '-e', 'BREEZ_LNURL_DOMAINS=',
-        '-e', 'BREEZ_LNURL_SCHEME=http',
-        '-e', 'BREEZ_LNURL_NSEC=nsec1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqsmhltgl',
-        '-e', 'BREEZ_LNURL_MIN_SENDABLE=1000',
-        '-e', 'BREEZ_LNURL_MAX_SENDABLE=1000000000',
-        '-e', 'BREEZ_LNURL_DEV_DONT_USE_LNURL_INCLUDE_SPARK_ADDRESS=false',
-        IMAGE
-      ])
-      fixture.containerId = runOutput.trim()
-
-      const port = await publishedPort(fixture.containerId, HTTP_PORT)
-      await fixture.waitForHttp(port)
-      fixture.httpUrl = `http://127.0.0.1:${port}`
-      return fixture
-    } catch (e) {
-      fixture.stop()
-      throw e
-    }
-  }
-
-  /**
-   * Readiness cannot be taken from the logs: the server's startup line is
-   * printed before it migrates the database and binds, and it logs nothing
-   * afterwards. Nor is reaching the port enough, since docker's proxy accepts
-   * connections there from the moment the container starts and closes them
-   * again while nothing is listening inside.
-   */
-  async waitForHttp(port) {
-    const deadline = Date.now() + START_TIMEOUT_MS
-    for (;;) {
-      try {
-        await httpResponds(port)
-        return
-      } catch {
-        // Not serving yet.
-      }
-      await this.ensureRunning(this.containerId, 'lnurl server')
-      if (Date.now() >= deadline) {
-        const logs = await this.logs(this.containerId)
-        throw new Error(`lnurl server did not serve HTTP within ${START_TIMEOUT_MS}ms:\n${logs}`)
-      }
-      await new Promise((resolve) => setTimeout(resolve, 250))
-    }
-  }
-
-  async waitForPostgres() {
-    const deadline = Date.now() + START_TIMEOUT_MS
-    for (;;) {
-      try {
-        // Probe TCP explicitly: while initialising, the image's entrypoint
-        // runs a temporary socket-only server that the default `pg_isready`
-        // check would accept as ready.
-        await docker([
-          'exec', this.postgresContainerId,
-          'pg_isready', '-h', '127.0.0.1', '-U', 'postgres'
-        ])
-        return
-      } catch {
-        // Not accepting connections yet.
-      }
-      await this.ensureRunning(this.postgresContainerId, 'postgres')
-      if (Date.now() >= deadline) {
-        throw new Error(`postgres did not accept connections within ${START_TIMEOUT_MS}ms`)
-      }
-      await new Promise((resolve) => setTimeout(resolve, 250))
-    }
-  }
-
-  /**
-   * Fail with the container's logs once it has exited. A container that dies
-   * on startup otherwise surfaces only as a readiness timeout, or as an
-   * unrelated docker error, neither of which names the real cause.
-   */
-  async ensureRunning(containerId, name) {
-    const state = await docker(['inspect', '-f', '{{.State.Running}}', containerId])
-    if (state.trim() === 'true') {
-      return
-    }
-    throw new Error(`${name} container exited before it was ready:\n${await this.logs(containerId)}`)
-  }
-
-  async logs(containerId) {
-    try {
-      // docker logs writes to both stdout and stderr; check both.
-      const { stdout, stderr } = await execFileAsync('docker', ['logs', containerId])
-      return stdout + stderr
-    } catch (e) {
-      return `failed to read container logs: ${e.message}`
-    }
-  }
-
-  stop() {
-    for (const containerId of [this.containerId, this.postgresContainerId]) {
-      if (!containerId) {
-        continue
-      }
-      try {
-        execFileSync('docker', ['rm', '-f', containerId], { stdio: 'ignore' })
-      } catch {
-        // Container may already be gone.
-      }
-    }
-  }
-}
-
-module.exports = { LnurlFixture, dockerAvailable }