@breeztech/breez-sdk-spark 0.14.0 → 0.15.1

package/web/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.
@@ -1736,9 +1810,10 @@ export interface InitOutput {
     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_postgresconnectionpool_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 __wbg_wasmsdkcontext_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;
@@ -1778,6 +1853,7 @@ export interface InitOutput {
     readonly breezsdk_receivePayment: (a: number, b: any) => any;
     readonly breezsdk_recommendedFees: (a: number) => any;
     readonly breezsdk_refundDeposit: (a: number, b: any) => any;
+    readonly breezsdk_refundPendingConversions: (a: number) => any;
     readonly breezsdk_registerLightningAddress: (a: number, b: any) => any;
     readonly breezsdk_registerWebhook: (a: number, b: any) => any;
     readonly breezsdk_removeEventListener: (a: number, b: number, c: number) => any;
@@ -1795,6 +1871,8 @@ export interface InitOutput {
     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;
+    readonly defaultPostgresStorageConfig: (a: number, b: number) => any;
+    readonly defaultServerConfig: (a: any) => any;
     readonly defaultsigner_aggregateFrost: (a: number, b: any) => any;
     readonly defaultsigner_decryptEcies: (a: number, b: number, c: number, d: number, e: number) => any;
     readonly defaultsigner_derivePublicKey: (a: number, b: number, c: number) => any;
@@ -1818,7 +1896,7 @@ export interface InitOutput {
     readonly getSparkStatus: () => any;
     readonly initLogging: (a: any, b: number, c: number) => any;
     readonly newRestChainService: (a: number, b: number, c: any, d: any, e: number) => any;
-    readonly newSspConnectionManager: (a: number, b: number) => number;
+    readonly newSharedSdkContext: (a: any) => any;
     readonly passkey_getWallet: (a: number, b: number, c: number) => any;
     readonly passkey_isAvailable: (a: number) => any;
     readonly passkey_listLabels: (a: number) => any;
@@ -1838,8 +1916,7 @@ export interface InitOutput {
     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_withSharedContext: (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;
@@ -1866,13 +1943,11 @@ 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__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__h013a98c02f3b4b21: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h013a98c02f3b4b21_4: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h013a98c02f3b4b21_5: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h013a98c02f3b4b21_6: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h013a98c02f3b4b21_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;