@buildonspark/spark-sdk 0.4.1 → 0.4.2

package/dist/types/index.d.cts

@@ -1,6 +1,6 @@
-export { B as BitcoinNetwork, O as ClaimStaticDeposit, C as ClaimStaticDepositOutput, Q as ClaimStaticDepositStatus, R as CompleteCoopExitInput, X as CompleteLeavesSwapInput, Y as CoopExitFeeEstimate, Z as CoopExitFeeEstimatesInput, _ as CoopExitFeeEstimatesOutput, F as CoopExitFeeQuote, a0 as CoopExitFeeQuoteInput, G as CoopExitRequest, a2 as CurrencyAmount, a3 as CurrencyUnit, E as ExitSpeed, a4 as GetChallengeOutput, a5 as Invoice, a6 as Leaf, L as LeavesSwapFeeEstimateOutput, a8 as LeavesSwapRequest, x as LightningReceiveRequest, aa as LightningReceiveRequestStatus, z as LightningSendFeeEstimateInput, ab as LightningSendFeeEstimateOutput, y as LightningSendRequest, ad as LightningSendRequestStatus, P as PageInfo, ae as RequestCoopExitInput, af as RequestLeavesSwapInput, ag as RequestLightningReceiveInput, ah as RequestLightningSendInput, ai as SparkCoopExitRequestStatus, aj as SparkLeavesSwapRequestStatus, ak as SparkTransferToLeavesConnection, al as StaticDepositQuoteInput, u as StaticDepositQuoteOutput, am as SwapLeaf, an as Transfer, ar as TransferDirection, ao as UserLeafInput, as as UserRequestType, ap as VerifyChallengeOutput, W as WalletLeaf, w as WalletTransfer, at as WalletTransferLeaf, N as getClaimStaticDepositQuery, $ as getCoopExitFeeQuoteQuery, a1 as getCoopExitRequestQuery, a7 as getLeavesSwapRequestQuery, a9 as getLightningReceiveRequestQuery, ac as getLightningSendRequestQuery, au as mapTransferLeafToWalletTransferLeaf, av as mapTransferToWalletTransfer, aq as mapTreeNodeToWalletLeaf } from '../client-BIqiUNy4.cjs';
+export { B as BitcoinNetwork, O as ClaimStaticDeposit, C as ClaimStaticDepositOutput, Q as ClaimStaticDepositStatus, R as CompleteCoopExitInput, X as CompleteLeavesSwapInput, Y as CoopExitFeeEstimate, Z as CoopExitFeeEstimatesInput, _ as CoopExitFeeEstimatesOutput, F as CoopExitFeeQuote, a0 as CoopExitFeeQuoteInput, G as CoopExitRequest, a2 as CurrencyAmount, a3 as CurrencyUnit, E as ExitSpeed, a4 as GetChallengeOutput, a5 as Invoice, a6 as Leaf, L as LeavesSwapFeeEstimateOutput, a8 as LeavesSwapRequest, x as LightningReceiveRequest, aa as LightningReceiveRequestStatus, z as LightningSendFeeEstimateInput, ab as LightningSendFeeEstimateOutput, y as LightningSendRequest, ad as LightningSendRequestStatus, P as PageInfo, ae as RequestCoopExitInput, af as RequestLeavesSwapInput, ag as RequestLightningReceiveInput, ah as RequestLightningSendInput, ai as SparkCoopExitRequestStatus, aj as SparkLeavesSwapRequestStatus, ak as SparkTransferToLeavesConnection, al as StaticDepositQuoteInput, u as StaticDepositQuoteOutput, am as SwapLeaf, an as Transfer, ar as TransferDirection, ao as UserLeafInput, as as UserRequestType, ap as VerifyChallengeOutput, W as WalletLeaf, w as WalletTransfer, at as WalletTransferLeaf, N as getClaimStaticDepositQuery, $ as getCoopExitFeeQuoteQuery, a1 as getCoopExitRequestQuery, a7 as getLeavesSwapRequestQuery, a9 as getLightningReceiveRequestQuery, ac as getLightningSendRequestQuery, au as mapTransferLeafToWalletTransferLeaf, av as mapTransferToWalletTransfer, aq as mapTreeNodeToWalletLeaf } from '../client-BZFWaZ1l.cjs';
 export { ClaimStaticDepositInput, ClaimStaticDepositRequestType, CompleteCoopExitOutput, CompleteLeavesSwapOutput, CompleteSeedReleaseInput, CompleteSeedReleaseOutput, Connection, CoopExitFeeQuoteOutput, Entity, GetChallengeInput, LeavesSwapFeeEstimateInput, NotifyReceiverTransferInput, Provider, RequestCoopExitOutput, RequestLeavesSwapOutput, RequestLightningReceiveOutput, RequestLightningSendOutput, SparkUserRequestStatus, SparkUserRequestType, SparkWalletUser, SparkWalletUserToUserRequestsConnection, StartSeedReleaseInput, UserRequest, VerifyChallengeInput, WalletUserIdentityPublicKeyInput, WalletUserIdentityPublicKeyOutput, getUserRequestQuery } from '../graphql/objects/index.cjs';
-export { n as CommonProto, s as SparkProto } from '../spark-DOpheE8_.cjs';
+export { n as CommonProto, s as SparkProto } from '../spark-BWkABx3N.cjs';
 import '@lightsparkdev/core';
 import '@scure/btc-signer';
 import '@scure/bip32';

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
-export { B as BitcoinNetwork, O as ClaimStaticDeposit, C as ClaimStaticDepositOutput, Q as ClaimStaticDepositStatus, R as CompleteCoopExitInput, X as CompleteLeavesSwapInput, Y as CoopExitFeeEstimate, Z as CoopExitFeeEstimatesInput, _ as CoopExitFeeEstimatesOutput, F as CoopExitFeeQuote, a0 as CoopExitFeeQuoteInput, G as CoopExitRequest, a2 as CurrencyAmount, a3 as CurrencyUnit, E as ExitSpeed, a4 as GetChallengeOutput, a5 as Invoice, a6 as Leaf, L as LeavesSwapFeeEstimateOutput, a8 as LeavesSwapRequest, x as LightningReceiveRequest, aa as LightningReceiveRequestStatus, z as LightningSendFeeEstimateInput, ab as LightningSendFeeEstimateOutput, y as LightningSendRequest, ad as LightningSendRequestStatus, P as PageInfo, ae as RequestCoopExitInput, af as RequestLeavesSwapInput, ag as RequestLightningReceiveInput, ah as RequestLightningSendInput, ai as SparkCoopExitRequestStatus, aj as SparkLeavesSwapRequestStatus, ak as SparkTransferToLeavesConnection, al as StaticDepositQuoteInput, u as StaticDepositQuoteOutput, am as SwapLeaf, an as Transfer, ar as TransferDirection, ao as UserLeafInput, as as UserRequestType, ap as VerifyChallengeOutput, W as WalletLeaf, w as WalletTransfer, at as WalletTransferLeaf, N as getClaimStaticDepositQuery, $ as getCoopExitFeeQuoteQuery, a1 as getCoopExitRequestQuery, a7 as getLeavesSwapRequestQuery, a9 as getLightningReceiveRequestQuery, ac as getLightningSendRequestQuery, au as mapTransferLeafToWalletTransferLeaf, av as mapTransferToWalletTransfer, aq as mapTreeNodeToWalletLeaf } from '../client-BaQf-5gD.js';
+export { B as BitcoinNetwork, O as ClaimStaticDeposit, C as ClaimStaticDepositOutput, Q as ClaimStaticDepositStatus, R as CompleteCoopExitInput, X as CompleteLeavesSwapInput, Y as CoopExitFeeEstimate, Z as CoopExitFeeEstimatesInput, _ as CoopExitFeeEstimatesOutput, F as CoopExitFeeQuote, a0 as CoopExitFeeQuoteInput, G as CoopExitRequest, a2 as CurrencyAmount, a3 as CurrencyUnit, E as ExitSpeed, a4 as GetChallengeOutput, a5 as Invoice, a6 as Leaf, L as LeavesSwapFeeEstimateOutput, a8 as LeavesSwapRequest, x as LightningReceiveRequest, aa as LightningReceiveRequestStatus, z as LightningSendFeeEstimateInput, ab as LightningSendFeeEstimateOutput, y as LightningSendRequest, ad as LightningSendRequestStatus, P as PageInfo, ae as RequestCoopExitInput, af as RequestLeavesSwapInput, ag as RequestLightningReceiveInput, ah as RequestLightningSendInput, ai as SparkCoopExitRequestStatus, aj as SparkLeavesSwapRequestStatus, ak as SparkTransferToLeavesConnection, al as StaticDepositQuoteInput, u as StaticDepositQuoteOutput, am as SwapLeaf, an as Transfer, ar as TransferDirection, ao as UserLeafInput, as as UserRequestType, ap as VerifyChallengeOutput, W as WalletLeaf, w as WalletTransfer, at as WalletTransferLeaf, N as getClaimStaticDepositQuery, $ as getCoopExitFeeQuoteQuery, a1 as getCoopExitRequestQuery, a7 as getLeavesSwapRequestQuery, a9 as getLightningReceiveRequestQuery, ac as getLightningSendRequestQuery, au as mapTransferLeafToWalletTransferLeaf, av as mapTransferToWalletTransfer, aq as mapTreeNodeToWalletLeaf } from '../client-3MdPdtnA.js';
 export { ClaimStaticDepositInput, ClaimStaticDepositRequestType, CompleteCoopExitOutput, CompleteLeavesSwapOutput, CompleteSeedReleaseInput, CompleteSeedReleaseOutput, Connection, CoopExitFeeQuoteOutput, Entity, GetChallengeInput, LeavesSwapFeeEstimateInput, NotifyReceiverTransferInput, Provider, RequestCoopExitOutput, RequestLeavesSwapOutput, RequestLightningReceiveOutput, RequestLightningSendOutput, SparkUserRequestStatus, SparkUserRequestType, SparkWalletUser, SparkWalletUserToUserRequestsConnection, StartSeedReleaseInput, UserRequest, VerifyChallengeInput, WalletUserIdentityPublicKeyInput, WalletUserIdentityPublicKeyOutput, getUserRequestQuery } from '../graphql/objects/index.js';
-export { n as CommonProto, s as SparkProto } from '../spark-DOpheE8_.js';
+export { n as CommonProto, s as SparkProto } from '../spark-BWkABx3N.js';
 import '@lightsparkdev/core';
 import '@scure/btc-signer';
 import '@scure/bip32';

package/dist/types/index.js

@@ -3,11 +3,7 @@ import {
   mapTransferLeafToWalletTransferLeaf,
   mapTransferToWalletTransfer,
   mapTreeNodeToWalletLeaf
-} from "../chunk-4YFT7DAE.js";
-import {
-  common_exports,
-  spark_exports
-} from "../chunk-YEBEN7XD.js";
+} from "../chunk-Q537QTDY.js";
 import {
   BitcoinNetwork_default,
   ClaimStaticDepositRequestType_default,
@@ -29,6 +25,10 @@ import {
   getLightningSendRequestQuery,
   getUserRequestQuery
 } from "../chunk-CQY5ML2A.js";
+import {
+  common_exports,
+  spark_exports
+} from "../chunk-BHFVMNXO.js";
 import "../chunk-MVRQ5US7.js";
 export {
   BitcoinNetwork_default as BitcoinNetwork,

package/dist/{wallet-config-w9e62Plc.d.ts → wallet-config-CQW-mDqN.d.ts}

@@ -1,7 +1,7 @@
-import { B as BitcoinNetwork, H as HasSspClientOptions, S as SparkSigner, t as SspClientOptions, l as KeyDerivation, i as SigningCommitmentWithOptionalNonce, V as VerifiableSecretShare, D as DefaultSparkSigner, L as LeavesSwapFeeEstimateOutput, u as StaticDepositQuoteOutput, C as ClaimStaticDepositOutput, W as WalletLeaf, w as WalletTransfer, x as LightningReceiveRequest, y as LightningSendRequest, z as LightningSendFeeEstimateInput, E as ExitSpeed, F as CoopExitFeeQuote, G as CoopExitRequest, I as TransferWithUserRequest, M as MayHaveSspClientOptions } from './client-BaQf-5gD.js';
+import { B as BitcoinNetwork, H as HasSspClientOptions, S as SparkSigner, t as SspClientOptions, l as KeyDerivation, i as SigningCommitmentWithOptionalNonce, V as VerifiableSecretShare, D as DefaultSparkSigner, L as LeavesSwapFeeEstimateOutput, u as StaticDepositQuoteOutput, C as ClaimStaticDepositOutput, W as WalletLeaf, w as WalletTransfer, x as LightningReceiveRequest, y as LightningSendRequest, z as LightningSendFeeEstimateInput, E as ExitSpeed, F as CoopExitFeeQuote, G as CoopExitRequest, I as TransferWithUserRequest, M as MayHaveSspClientOptions } from './client-3MdPdtnA.js';
 import * as btc from '@scure/btc-signer';
 import { Transaction } from '@scure/btc-signer';
-import { N as Network$1, e as SparkInvoiceFields, b as SparkServiceDefinition, f as SparkServiceClient, d as SubscribeToEventsResponse, R as RequestedSigningCommitments, U as UserSignedTxSigningJob, c as TreeNode, T as Transfer, g as StartTransferRequest, L as LeafRefundTxSigningResult, h as NodeSignatures, F as FinalizeNodeSignaturesResponse, Q as QueryTransfersResponse, i as QuerySparkInvoicesResponse, O as OutputWithPreviousTransactionData } from './spark-DOpheE8_.js';
+import { N as Network$1, e as SparkInvoiceFields, b as SparkServiceDefinition, f as SparkServiceClient, d as SubscribeToEventsResponse, R as RequestedSigningCommitments, U as UserSignedTxSigningJob, c as TreeNode, T as Transfer, g as StartTransferRequest, L as LeafRefundTxSigningResult, h as NodeSignatures, F as FinalizeNodeSignaturesResponse, Q as QueryTransfersResponse, i as QuerySparkInvoicesResponse, O as OutputWithPreviousTransactionData } from './spark-BWkABx3N.js';
 import { SparkTokenServiceDefinition, SparkTokenServiceClient, QueryTokenTransactionsResponse, TokenMetadata } from './proto/spark_token.js';
 import * as _scure_base from '@scure/base';
 import { Channel } from 'nice-grpc';
@@ -69,8 +69,8 @@ interface DecodedSparkAddressData {
     };
     signature?: string;
 }
-declare function encodeSparkAddress(payload: SparkAddressData): LegacySparkAddressFormat;
-declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): LegacySparkAddressFormat;
+declare function encodeSparkAddress(payload: SparkAddressData): SparkAddressFormat;
+declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): SparkAddressFormat;
 declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
 declare function getNetworkFromSparkAddress(address: string): NetworkType;
 declare function isLegacySparkAddress(address: string): address is LegacySparkAddressFormat;
@@ -462,14 +462,14 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {Object} params - Parameters for the sats payment
      * @param {number} params.amount - The amount of sats to receive
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the sats payment
      */
-    createSatsInvoice({ amount, memo, senderPublicKey, expiryTime, }: {
+    createSatsInvoice({ amount, memo, senderSparkAddress, expiryTime, }: {
         amount?: number;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -479,15 +479,15 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {bigint} [params.amount] - The amount of tokens to receive
      * @param {Bech32mTokenIdentifier} [params.tokenIdentifier] - The token identifier
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the tokens payment
      */
-    createTokensInvoice({ amount, tokenIdentifier, memo, senderPublicKey, expiryTime, }: {
+    createTokensInvoice({ amount, tokenIdentifier, memo, senderSparkAddress, expiryTime, }: {
         tokenIdentifier?: Bech32mTokenIdentifier;
         amount?: bigint;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -786,6 +786,31 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @returns {Promise<LightningSendRequest>} The Lightning payment request details
      */
     payLightningInvoice({ invoice, maxFeeSats, preferSpark, amountSatsToSend, }: PayLightningInvoiceParams): Promise<LightningSendRequest | WalletTransfer>;
+    /**
+     * Fulfills one or more Spark invoices.
+     *
+     * Processes each provided invoice and attempts to pay it according to the wallet’s
+     * funding/selection strategy.
+     *
+     * @param sparkInvoices - Invoices to fulfill.
+     * @param sparkInvoices[].invoice - The parsed Spark address/invoice to pay.
+     *   Must be a valid Spark address or invoice.
+     *   Must use spark1... prefixed invoices.
+     *   Deprecated sp1... prefixed invoices are not supported.
+     * @param sparkInvoices[].amount - Used to define an amount for invoices without an amount encoded.
+     *   For sats invoices, this is the amount in sats. For token invoices, this is the amount in tokens.
+     *   Amount encoded in the invoice takes precedence if both are provided.
+     *
+     * @returns Promise<string> A payment or transaction identifier (implementation‑specific).
+     *
+     * @throws {ValidationError} If validation fails (malformed invoice, zero/negative amount, unsupported network),
+     *
+     * @example
+     * await wallet.fulfillSparkInvoice([
+     *   { invoice: invoiceWithNilAmount, amount: 1000n },
+     *   { invoice: invoiceWithEncodedAmount }, // uses amount encoded in the invoice
+     * ]);
+     */
     fulfillSparkInvoice(sparkInvoices: {
         invoice: SparkAddressFormat;
         amount?: bigint;
@@ -1043,28 +1068,27 @@ type FulfillSparkInvoiceResponse = {
     }[];
     tokenTransactionSuccess: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         txid: string;
     }[];
     satsTransactionErrors: {
-        invoice: string;
+        invoice: SparkAddressFormat;
         error: Error;
     }[];
     tokenTransactionErrors: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         error: Error;
     }[];
-    invalidInvoices: {
-        invoice: string;
-        error: Error;
-    }[];
+    invalidInvoices: InvalidInvoice[];
 };
 type TokenInvoice = {
-    invoice: string;
+    invoice: SparkAddressFormat;
     identifierHex: string;
     amount: bigint;
 };
 type InvalidInvoice = {
-    invoice: string;
+    invoice: SparkAddressFormat;
     error: Error;
 };
 type GroupSparkInvoicesResult = {

package/dist/{wallet-config-DVEoQg3w.d.cts → wallet-config-JYsN3izc.d.cts}

@@ -1,7 +1,7 @@
-import { B as BitcoinNetwork, H as HasSspClientOptions, S as SparkSigner, t as SspClientOptions, l as KeyDerivation, i as SigningCommitmentWithOptionalNonce, V as VerifiableSecretShare, D as DefaultSparkSigner, L as LeavesSwapFeeEstimateOutput, u as StaticDepositQuoteOutput, C as ClaimStaticDepositOutput, W as WalletLeaf, w as WalletTransfer, x as LightningReceiveRequest, y as LightningSendRequest, z as LightningSendFeeEstimateInput, E as ExitSpeed, F as CoopExitFeeQuote, G as CoopExitRequest, I as TransferWithUserRequest, M as MayHaveSspClientOptions } from './client-BIqiUNy4.cjs';
+import { B as BitcoinNetwork, H as HasSspClientOptions, S as SparkSigner, t as SspClientOptions, l as KeyDerivation, i as SigningCommitmentWithOptionalNonce, V as VerifiableSecretShare, D as DefaultSparkSigner, L as LeavesSwapFeeEstimateOutput, u as StaticDepositQuoteOutput, C as ClaimStaticDepositOutput, W as WalletLeaf, w as WalletTransfer, x as LightningReceiveRequest, y as LightningSendRequest, z as LightningSendFeeEstimateInput, E as ExitSpeed, F as CoopExitFeeQuote, G as CoopExitRequest, I as TransferWithUserRequest, M as MayHaveSspClientOptions } from './client-BZFWaZ1l.cjs';
 import * as btc from '@scure/btc-signer';
 import { Transaction } from '@scure/btc-signer';
-import { N as Network$1, e as SparkInvoiceFields, b as SparkServiceDefinition, f as SparkServiceClient, d as SubscribeToEventsResponse, R as RequestedSigningCommitments, U as UserSignedTxSigningJob, c as TreeNode, T as Transfer, g as StartTransferRequest, L as LeafRefundTxSigningResult, h as NodeSignatures, F as FinalizeNodeSignaturesResponse, Q as QueryTransfersResponse, i as QuerySparkInvoicesResponse, O as OutputWithPreviousTransactionData } from './spark-DOpheE8_.cjs';
+import { N as Network$1, e as SparkInvoiceFields, b as SparkServiceDefinition, f as SparkServiceClient, d as SubscribeToEventsResponse, R as RequestedSigningCommitments, U as UserSignedTxSigningJob, c as TreeNode, T as Transfer, g as StartTransferRequest, L as LeafRefundTxSigningResult, h as NodeSignatures, F as FinalizeNodeSignaturesResponse, Q as QueryTransfersResponse, i as QuerySparkInvoicesResponse, O as OutputWithPreviousTransactionData } from './spark-BWkABx3N.cjs';
 import { SparkTokenServiceDefinition, SparkTokenServiceClient, QueryTokenTransactionsResponse, TokenMetadata } from './proto/spark_token.cjs';
 import * as _scure_base from '@scure/base';
 import { Channel } from 'nice-grpc';
@@ -69,8 +69,8 @@ interface DecodedSparkAddressData {
     };
     signature?: string;
 }
-declare function encodeSparkAddress(payload: SparkAddressData): LegacySparkAddressFormat;
-declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): LegacySparkAddressFormat;
+declare function encodeSparkAddress(payload: SparkAddressData): SparkAddressFormat;
+declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): SparkAddressFormat;
 declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
 declare function getNetworkFromSparkAddress(address: string): NetworkType;
 declare function isLegacySparkAddress(address: string): address is LegacySparkAddressFormat;
@@ -462,14 +462,14 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {Object} params - Parameters for the sats payment
      * @param {number} params.amount - The amount of sats to receive
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the sats payment
      */
-    createSatsInvoice({ amount, memo, senderPublicKey, expiryTime, }: {
+    createSatsInvoice({ amount, memo, senderSparkAddress, expiryTime, }: {
         amount?: number;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -479,15 +479,15 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {bigint} [params.amount] - The amount of tokens to receive
      * @param {Bech32mTokenIdentifier} [params.tokenIdentifier] - The token identifier
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the tokens payment
      */
-    createTokensInvoice({ amount, tokenIdentifier, memo, senderPublicKey, expiryTime, }: {
+    createTokensInvoice({ amount, tokenIdentifier, memo, senderSparkAddress, expiryTime, }: {
         tokenIdentifier?: Bech32mTokenIdentifier;
         amount?: bigint;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -786,6 +786,31 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @returns {Promise<LightningSendRequest>} The Lightning payment request details
      */
     payLightningInvoice({ invoice, maxFeeSats, preferSpark, amountSatsToSend, }: PayLightningInvoiceParams): Promise<LightningSendRequest | WalletTransfer>;
+    /**
+     * Fulfills one or more Spark invoices.
+     *
+     * Processes each provided invoice and attempts to pay it according to the wallet’s
+     * funding/selection strategy.
+     *
+     * @param sparkInvoices - Invoices to fulfill.
+     * @param sparkInvoices[].invoice - The parsed Spark address/invoice to pay.
+     *   Must be a valid Spark address or invoice.
+     *   Must use spark1... prefixed invoices.
+     *   Deprecated sp1... prefixed invoices are not supported.
+     * @param sparkInvoices[].amount - Used to define an amount for invoices without an amount encoded.
+     *   For sats invoices, this is the amount in sats. For token invoices, this is the amount in tokens.
+     *   Amount encoded in the invoice takes precedence if both are provided.
+     *
+     * @returns Promise<string> A payment or transaction identifier (implementation‑specific).
+     *
+     * @throws {ValidationError} If validation fails (malformed invoice, zero/negative amount, unsupported network),
+     *
+     * @example
+     * await wallet.fulfillSparkInvoice([
+     *   { invoice: invoiceWithNilAmount, amount: 1000n },
+     *   { invoice: invoiceWithEncodedAmount }, // uses amount encoded in the invoice
+     * ]);
+     */
     fulfillSparkInvoice(sparkInvoices: {
         invoice: SparkAddressFormat;
         amount?: bigint;
@@ -1043,28 +1068,27 @@ type FulfillSparkInvoiceResponse = {
     }[];
     tokenTransactionSuccess: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         txid: string;
     }[];
     satsTransactionErrors: {
-        invoice: string;
+        invoice: SparkAddressFormat;
         error: Error;
     }[];
     tokenTransactionErrors: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         error: Error;
     }[];
-    invalidInvoices: {
-        invoice: string;
-        error: Error;
-    }[];
+    invalidInvoices: InvalidInvoice[];
 };
 type TokenInvoice = {
-    invoice: string;
+    invoice: SparkAddressFormat;
     identifierHex: string;
     amount: bigint;
 };
 type InvalidInvoice = {
-    invoice: string;
+    invoice: SparkAddressFormat;
     error: Error;
 };
 type GroupSparkInvoicesResult = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildonspark/spark-sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "author": "",
   "license": "Apache-2.0",
   "main": "./dist/index.js",