@breeztech/breez-sdk-spark 0.14.0 → 0.15.0

package/bundler/breez_sdk_spark_wasm.d.ts

@@ -115,7 +115,7 @@ export interface TokenStore {
     listTokensOutputs: () => Promise<WasmTokenOutputsPerStatus[]>;
     getTokenBalances: () => Promise<WasmTokenBalance[]>;
     getTokenOutputs: (filter: WasmGetTokenOutputsFilter) => Promise<WasmTokenOutputsPerStatus>;
-    insertTokenOutputs: (tokenOutputs: WasmTokenOutputs) => Promise<void>;
+    updateTokenOutputs: (outputsToRemove: [string, number][], outputsToAdd: WasmTokenOutputs | null) => Promise<void>;
     reserveTokenOutputs: (
     tokenIdentifier: string,
     target: WasmReservationTarget,
@@ -162,6 +162,20 @@ export interface MysqlStorageConfig {
      * Timeout in seconds before recycling an idle connection.
      */
     recycleTimeoutSecs: number;
+    /**
+     * Whether the SDK should run schema migrations on startup. Set to
+     * `false` when the embedding service owns and migrates the database
+     * schema. Defaults to `true`.
+     */
+    runMigration?: boolean;
+    /**
+     * Whether migrations should create database-enforced foreign keys.
+     *
+     * Use `Disabled` for environments that manage relationships in
+     * application code and require schema changes without foreign-key
+     * constraints.
+     */
+    foreignKeyMode?: MysqlForeignKeyMode;
 }
 
 /**
@@ -184,8 +198,19 @@ export interface PostgresStorageConfig {
      * Timeout in seconds before recycling an idle connection.
      */
     recycleTimeoutSecs: number;
+    /**
+     * Whether the SDK should run schema migrations on startup. Set to
+     * `false` when the embedding service owns and migrates the database
+     * schema. Defaults to `true`.
+     */
+    runMigration?: boolean;
 }
 
+/**
+ * Controls whether MySQL migrations create database-enforced foreign keys.
+ */
+export type MysqlForeignKeyMode = "Enforced" | "Disabled";
+
 /**
  * Interface for passkey PRF (Pseudo-Random Function) operations.
  *
@@ -255,6 +280,40 @@ export interface NostrRelayConfig {
     timeoutSecs?: number;
 }
 
+/**
+ * Settings for `newSharedSdkContext`. `network` is required; all other
+ * fields are optional.
+ */
+export interface WasmSdkContextConfig {
+    /**
+     * Network the shared resources target. Used to gate the partner JWT
+     * header provider — only constructed on Mainnet.
+     */
+    network: Network;
+    /**
+     * Breez API key. When set together with `network == Mainnet`, the
+     * context constructs a shared partner JWT header provider that all
+     * SDKs built from this context will attach to their SO requests.
+     */
+    apiKey?: string;
+    /**
+     * Number of gRPC connections per Spark operator. `None` (or `Some(1)`)
+     * keeps a single connection per operator (right for most deployments);
+     * `Some(n)` opens `n` channels per operator and balances requests.
+     */
+    connectionsPerOperator?: number;
+    /**
+     * PostgreSQL backend configuration. When set, SDKs constructed with
+     * this context store their data in PostgreSQL via the shared pool.
+     */
+    postgresConfig?: PostgresStorageConfig;
+    /**
+     * MySQL backend configuration. When set, SDKs constructed with this
+     * context store their data in MySQL via the shared pool.
+     */
+    mysqlConfig?: MysqlStorageConfig;
+}
+
 export interface AddContactRequest {
     name: string;
     paymentIdentifier: string;
@@ -417,7 +476,8 @@ export interface Config {
     useDefaultExternalInputParsers: boolean;
     realTimeSyncServerUrl?: string;
     privateEnabledDefault: boolean;
-    optimizationConfig: OptimizationConfig;
+    leafOptimizationConfig: LeafOptimizationConfig;
+    tokenOptimizationConfig: TokenOptimizationConfig;
     stableBalanceConfig?: StableBalanceConfig;
     /**
      * Maximum number of concurrent transfer claims.
@@ -428,6 +488,7 @@ export interface Config {
      */
     maxConcurrentClaims: number;
     sparkConfig?: SparkConfig;
+    backgroundTasksEnabled: boolean;
 }
 
 export interface ConnectRequest {
@@ -705,6 +766,11 @@ export interface KeySetConfig {
     accountNumber?: number;
 }
 
+export interface LeafOptimizationConfig {
+    autoEnabled: boolean;
+    multiplicity: number;
+}
+
 export interface LightningAddressDetails {
     address: string;
     payRequest: LnurlPayRequestDetails;
@@ -861,11 +927,6 @@ export interface MintIssuerTokenRequest {
     amount: bigint;
 }
 
-export interface OptimizationConfig {
-    autoEnabled: boolean;
-    multiplicity: number;
-}
-
 export interface OptimizationProgress {
     isRunning: boolean;
     currentRound: number;
@@ -1243,6 +1304,12 @@ export interface TokenMetadata {
     isFreezable: boolean;
 }
 
+export interface TokenOptimizationConfig {
+    autoEnabled: boolean;
+    targetOutputCount: number;
+    minOutputsThreshold: number;
+}
+
 export interface TxStatus {
     confirmed: boolean;
     blockHeight?: number;
@@ -1447,6 +1514,7 @@ export class BreezSdk {
     receivePayment(request: ReceivePaymentRequest): Promise<ReceivePaymentResponse>;
     recommendedFees(): Promise<RecommendedFees>;
     refundDeposit(request: RefundDepositRequest): Promise<RefundDepositResponse>;
+    refundPendingConversions(): Promise<void>;
     registerLightningAddress(request: RegisterLightningAddressRequest): Promise<LightningAddressInfo>;
     registerWebhook(request: RegisterWebhookRequest): Promise<RegisterWebhookResponse>;
     removeEventListener(id: string): Promise<boolean>;
@@ -1518,7 +1586,8 @@ export class IntoUnderlyingSource {
 }
 
 /**
- * A shareable MySQL connection pool. See [`PostgresConnectionPool`](super::postgres_pool::PostgresConnectionPool)
+ * A shareable `MySQL` connection pool. See
+ * [`PostgresConnectionPool`](super::postgres_pool::PostgresConnectionPool)
  * for sharing semantics and lifecycle.
  */
 export class MysqlConnectionPool {
@@ -1599,56 +1668,42 @@ export class SdkBuilder {
     withKeySet(config: KeySetConfig): SdkBuilder;
     withLnurlClient(lnurl_client: RestClient): SdkBuilder;
     /**
-     * **Deprecated.** Call `withMysqlConnectionPool(config)` and `withMysqlConnectionPool(pool)` instead.
+     * **Deprecated.** Call `createMysqlConnectionPool(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.
+     *
+     * If the same builder also receives a `WasmSdkContext` carrying a MySQL
+     * pool, `build()` returns an error — pick one source.
      */
     withMysqlConnectionPool(pool: MysqlConnectionPool): SdkBuilder;
     withPaymentObserver(payment_observer: PaymentObserver): SdkBuilder;
     /**
-     * **Deprecated.** Call `withPostgresConnectionPool(config)` and `withPostgresConnectionPool(pool)` instead.
+     * **Deprecated.** Call `createPostgresConnectionPool(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.
+     * Sets a shared Postgres connection pool as the backend for all stores.
+     *
+     * If the same builder also receives a `WasmSdkContext` carrying a
+     * Postgres pool, `build()` returns an error — pick one source.
      */
     withPostgresConnectionPool(pool: PostgresConnectionPool): SdkBuilder;
     withRestChainService(url: string, api_type: ChainApiType, credentials?: Credentials | null): SdkBuilder;
     /**
-     * Sets a custom session manager used to persist authentication sessions.
+     * Threads a shared [`WasmSdkContext`] into the builder.
      *
-     * 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.
+     * Construct the context once via `newSharedSdkContext` and pass the same
+     * handle to every `SdkBuilder` whose SDKs should share its resources
+     * (operator gRPC channels, SSP HTTP client, database pool).
      */
-    withSspConnectionManager(manager: SspConnectionManager): SdkBuilder;
+    withSharedContext(context: WasmSdkContext): 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;
@@ -1662,12 +1717,25 @@ export class TokenIssuer {
     unfreezeIssuerToken(request: UnfreezeIssuerTokenRequest): Promise<UnfreezeIssuerTokenResponse>;
 }
 
+/**
+ * Process-shared resources backing one or more `BreezSdk` instances on WASM.
+ *
+ * Construct once via `newSharedSdkContext` and pass the handle to every
+ * `SdkBuilder` whose SDKs should share its operator gRPC channels, SSP HTTP
+ * client, and (optionally) database connection pool.
+ */
+export class WasmSdkContext {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
 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.
+ * Creates a shareable `MySQL` connection pool from the given config.
  */
 export function createMysqlConnectionPool(config: MysqlStorageConfig): MysqlConnectionPool;
 
@@ -1687,6 +1755,7 @@ export function defaultExternalSigner(mnemonic: string, passphrase: string | nul
  * - `maxPoolSize`: 10
  * - `createTimeoutSecs`: 0 (no timeout)
  * - `recycleTimeoutSecs`: 10
+ * - `foreignKeyMode`: `Enforced`
  */
 export function defaultMysqlStorageConfig(connection_string: string): MysqlStorageConfig;
 
@@ -1700,6 +1769,8 @@ export function defaultMysqlStorageConfig(connection_string: string): MysqlStora
  */
 export function defaultPostgresStorageConfig(connection_string: string): PostgresStorageConfig;
 
+export function defaultServerConfig(network: Network): Config;
+
 /**
  * Creates a default external signer from a mnemonic phrase.
  *
@@ -1720,7 +1791,10 @@ export function initLogging(logger: Logger, filter?: string | null): Promise<voi
  */
 export function newRestChainService(url: string, network: Network, api_type: ChainApiType, credentials?: Credentials | null): Promise<BitcoinChainService>;
 
-export function newSspConnectionManager(user_agent?: string | null): SspConnectionManager;
+/**
+ * Constructs a [`WasmSdkContext`] from a `WasmSdkContextConfig`.
+ */
+export function newSharedSdkContext(config: WasmSdkContextConfig): Promise<WasmSdkContext>;
 
 /**
  * Entry point invoked by JavaScript in a worker.

package/bundler/breez_sdk_spark_wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./breez_sdk_spark_wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    BitcoinChainServiceHandle, BreezSdk, DefaultSigner, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, MysqlConnectionPool, Passkey, PostgresConnectionPool, SdkBuilder, SspConnectionManager, TokenIssuer, 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, TokenIssuer, WasmSdkContext, connect, connectWithSigner, createMysqlConnectionPool, createPostgresConnectionPool, defaultConfig, defaultExternalSigner, defaultMysqlStorageConfig, defaultPostgresStorageConfig, defaultServerConfig, getSparkStatus, initLogging, newRestChainService, newSharedSdkContext, task_worker_entry_point
 } from "./breez_sdk_spark_wasm_bg.js";