@bwalletx/connect 0.5.6 → 0.7.0

package/dist/{choice-DCh-tgpT.d.cts → choice-B97AjqF4.d.cts}

@@ -114,7 +114,15 @@ interface PayResult {
     /** For an identity-key payment: what the recipient needs to internalize the output (BRC-29). Deliver it to them. */
     remittance?: Brc29Remittance;
 }
-type PaymentErrorCode = 'BAD_REQUEST' | 'RESOLVE_FAILED' | 'RATE_FAILED' | 'WALLET_REJECTED' | 'WALLET_ERROR' | 'NOT_SUPPORTED';
+type PaymentErrorCode = 'BAD_REQUEST' | 'RESOLVE_FAILED' | 'RATE_FAILED' | 'WALLET_REJECTED' | 'WALLET_ERROR' | 'NOT_SUPPORTED' | 'INSUFFICIENT_FUNDS';
+/** (0.7.0) The plain message for a wallet with no coins for the network fee (PaymentError code INSUFFICIENT_FUNDS). */
+declare const NO_COINS_TEXT = "Your wallet doesn't have enough to cover this payment and its small network fee. Add a little and try again.";
+/**
+ * True when createAction failed because the wallet has no coins (or too few) to fund it: the SDK's
+ * WERR_INSUFFICIENT_FUNDS (code 7, also as it arrives from Metanet Desktop over the JSON API), or a wallet's own
+ * "insufficient funds" text. Nothing was sent in that case.
+ */
+declare function isInsufficientFunds(e: unknown): boolean;
 declare class PaymentError extends Error {
     readonly code: PaymentErrorCode;
     /** true when the wallet was asked to spend and the outcome is unknown. Check before trying again. */
@@ -294,6 +302,11 @@ declare function desktopOption(ms?: number): WalletOption;
  * `force` (picker off): the first detected wallet, else the first non-pairing option, else pairing.
  */
 declare function autoChoice(list: WalletOption[], force?: boolean): WalletOption | null | undefined;
+/**
+ * (0.7.0) A desktop wallet reached over localhost (json-api on 3321 = Metanet Desktop, Cicada on 3301): never picked
+ * by the button, the fast path or a remembered choice; only by its own tap ("Use Metanet Desktop…").
+ */
+declare function isLocalDesktop(w: Pick<WalletOption, 'id' | 'substrate'>): boolean;
 
 /** The wallet type every bWalletX (extension, in-app, app frame, phone) reports. */
 declare const BWALLETX_TYPE = "bwalletx";
@@ -317,7 +330,7 @@ declare function chooserOrder(list: readonly WalletOption[]): WalletOption[];
  * 'bwalletx-phone': picker off and no bWalletX here, so the phone; 'legacy': fastPath false (0.5.5 autoChoice);
  * 'chooser': show the chooser; 'none': nothing to offer.
  */
-type ChoiceReason = 'requested' | 'bwalletx' | 'bwalletx-phone' | 'legacy' | 'chooser' | 'none';
+type ChoiceReason = 'requested' | 'remembered' | 'bwalletx' | 'bwalletx-phone' | 'legacy' | 'chooser' | 'none';
 interface WalletChoice {
     option: WalletOption | null;
     reason: ChoiceReason;
@@ -331,6 +344,10 @@ interface DecideWalletOptions {
     picker?: boolean;
     /** The bWalletX-first rule. Default true; false restores the 0.5.5 behaviour (autoChoice). */
     fastPath?: boolean;
+    /** (0.6.0) The wallet the user picked on this origin before (rememberedWalletChoice()). Used when it is here. */
+    remembered?: RememberedWallet | null;
+    /** (0.6.0) "Switch" to bWalletX: ignore a remembered other wallet. */
+    preferBwalletX?: boolean;
 }
 /** The wallet to connect now, or the chooser ({ option: null, reason: 'chooser' }). */
 declare function decideWallet(list: readonly WalletOption[], o?: DecideWalletOptions): WalletChoice;
@@ -354,5 +371,72 @@ declare function outcomeOf(e: unknown): AttemptOutcome;
 declare function attemptFor(option: WalletOption | null | undefined, outcome: AttemptOutcome, startedAt: number, now?: number): ConnectAttempt;
 /** Call the hook with exactly the four fields; a throwing hook never breaks sign-in. */
 declare function reportAttempt(hook: AttemptHook | undefined, a: ConnectAttempt): void;
+/** localStorage key (per origin, like all localStorage) for the wallet type picked here. Never holds a key. */
+declare const WALLET_CHOICE_KEY = "bwx:wallet";
+/** What is remembered: the wallet type and how it reached the page. Nothing that identifies the user. */
+interface RememberedWallet {
+    type: string;
+    substrate: Substrate;
+}
+/**
+ * True when the same wallet can be found again next time: bWalletX, an announced wallet (by its rdns), a desktop
+ * wallet, an app adapter. A bare window.CWI cannot (whoever holds it next time may be another wallet), so it is
+ * never remembered.
+ */
+declare function isRememberable(o: WalletOption): boolean;
+/** Whether a successful connect counts as the user's explicit pick: bWalletX (they tapped its button), or chosen. */
+declare function isExplicitPick(o: WalletOption, reason: ChoiceReason): boolean;
+/** Remember the wallet type picked on this origin (or forget with null). Silently skips what can't be remembered. */
+declare function rememberWalletChoice(o: WalletOption | null): void;
+/** The wallet type picked on this origin before, or null. Anything malformed or key-like is ignored. */
+declare function rememberedWalletChoice(): RememberedWallet | null;
+/** Forget the remembered wallet (Disconnect does this). */
+declare function forgetWalletChoice(): void;
+/** True when this wallet type is not bWalletX: show "Some features need bWalletX · Switch". */
+declare function needsBwalletX(type: string | null | undefined): boolean;
+/**
+ * (0.7.0) True when the signed-out button's tap goes to this remembered wallet instead of bWalletX ("Continue with your
+ * wallet", the Switch note). Never for Metanet: the button never picks it (it has its own link and "Not you?").
+ */
+declare function tapGoesElsewhere(type: string | null | undefined): boolean;
+/** (0.7.0) A remembered desktop wallet on localhost (Metanet, 'desktop', json-api, cicada): never the button's pick. */
+declare function isLocalDesktopType(r: RememberedWallet): boolean;
+/**
+ * The option in `list` for a remembered wallet, or null when it isn't here. bWalletX counts only by its own marker
+ * (or the phone, when the phone was picked). A remembered desktop wallet on localhost (Metanet / 'desktop') gives null
+ * (0.7.0): the button never picks it; its own link does.
+ */
+declare function matchRemembered(list: readonly WalletOption[], r: RememberedWallet): WalletOption | null;
+/**
+ * What to do on page load for a returning visitor (0.6.0).
+ *   'attach'       signed in already (a server session) and the remembered wallet is in the page: pick it up by
+ *                  discovery alone (no wallet call, so no prompt) so pay/tip work without another tap;
+ *   'wait-for-tap' anything else a wallet would have to answer (a key, a signature, a localhost probe, a relay
+ *                  reconnect): nothing fires; the next tap goes straight to the remembered wallet;
+ *   'silent-metanet' (0.7.0) Metanet Desktop remembered, on a computer outside any frame: ONE silent attempt this page
+ *                  load (trySilentMetanet: 2 s, known identity keys only), else the normal choice;
+ *   'none'         nothing remembered, or auto-connect off (or Metanet remembered where it isn't offered).
+ */
+type AutoConnectAction = 'attach' | 'wait-for-tap' | 'silent-metanet' | 'none';
+interface AutoConnectPlan {
+    action: AutoConnectAction;
+    remembered: RememberedWallet | null;
+    /** The remembered wallet isn't bWalletX: show "Some features need bWalletX · Switch". */
+    needsBwalletX: boolean;
+}
+declare function planAutoConnect(o: {
+    remembered: RememberedWallet | null;
+    signedIn: boolean;
+    enabled?: boolean;
+    /** (0.7.0) Metanet is offered here (a computer, outside any frame). Default metanetOffered(). */
+    metanetHere?: boolean;
+}): AutoConnectPlan;
+/**
+ * Find the remembered wallet in the page by discovery alone: no wallet method is called, nothing touches localhost,
+ * no relay is opened. null when it isn't here (or it isn't something that can be attached silently).
+ */
+declare function attachRemembered(r: RememberedWallet, o?: {
+    ms?: number;
+}): Promise<WalletOption | null>;
 
-export { pay as $, type AttemptHook as A, type BuyTokenRequest as B, type ConnectedWallet as C, DESKTOP_OPTION_ID as D, type WalletChoice as E, type WalletKind as F, amountInSats as G, type HandCashAdapterOptions as H, attemptFor as I, buyToken as J, chooserOrder as K, type LegacyPayer as L, clearPairing as M, cwiIsAnnounced as N, decideWallet as O, type PayRequest as P, desktopOption as Q, hasBwalletX as R, type Substrate as S, type TokenQuote as T, isIdentityKeyHex as U, isPaymail as V, type WalletOption as W, isPresentBwalletX as X, otherDetected as Y, outcomeOf as Z, pairBwalletX as _, type PayResult as a, reportAttempt as a0, resolvePaymailP2P as a1, restorePairing as a2, substrateOf as a3, tip as a4, walletTypeOf as a5, type PayOptions as b, PaymentError as c, autoChoice as d, brc100Option as e, discoverWallets as f, type PairingOptions as g, handcashAdapter as h, type ChoiceReason as i, type AttemptOutcome as j, BRC29_PROTOCOL as k, BWALLETX_TYPE as l, type Brc29Remittance as m, type ConnectAttempt as n, type ConnectOptions as o, pairingOption as p, type DecideWalletOptions as q, type DiscoverWalletsOptions as r, type PairConnectionOptions as s, type PairStorage as t, type PairedWallet as u, type PayOutput as v, type PaySource as w, type PaymentErrorCode as x, type SocketFactory as y, type SocketLike as z };
+export { hasBwalletX as $, type AttemptHook as A, type BuyTokenRequest as B, type ConnectedWallet as C, DESKTOP_OPTION_ID as D, type SocketFactory as E, type SocketLike as F, WALLET_CHOICE_KEY as G, type HandCashAdapterOptions as H, type WalletChoice as I, type WalletKind as J, amountInSats as K, type LegacyPayer as L, attachRemembered as M, NO_COINS_TEXT as N, attemptFor as O, type PayRequest as P, buyToken as Q, type RememberedWallet as R, type Substrate as S, type TokenQuote as T, chooserOrder as U, clearPairing as V, type WalletOption as W, cwiIsAnnounced as X, decideWallet as Y, desktopOption as Z, forgetWalletChoice as _, type PayResult as a, isExplicitPick as a0, isIdentityKeyHex as a1, isInsufficientFunds as a2, isLocalDesktop as a3, isLocalDesktopType as a4, isPaymail as a5, isPresentBwalletX as a6, isRememberable as a7, matchRemembered as a8, needsBwalletX as a9, otherDetected as aa, outcomeOf as ab, pairBwalletX as ac, pay as ad, planAutoConnect as ae, rememberWalletChoice as af, rememberedWalletChoice as ag, reportAttempt as ah, resolvePaymailP2P as ai, restorePairing as aj, substrateOf as ak, tapGoesElsewhere as al, tip as am, walletTypeOf as an, type PayOptions as b, PaymentError as c, autoChoice as d, brc100Option as e, discoverWallets as f, type PairingOptions as g, handcashAdapter as h, type ChoiceReason as i, type AttemptOutcome as j, type AutoConnectAction as k, type AutoConnectPlan as l, BRC29_PROTOCOL as m, BWALLETX_TYPE as n, type Brc29Remittance as o, pairingOption as p, type ConnectAttempt as q, type ConnectOptions as r, type DecideWalletOptions as s, type DiscoverWalletsOptions as t, type PairConnectionOptions as u, type PairStorage as v, type PairedWallet as w, type PayOutput as x, type PaySource as y, type PaymentErrorCode as z };

package/dist/{choice-DCh-tgpT.d.ts → choice-B97AjqF4.d.ts}

@@ -114,7 +114,15 @@ interface PayResult {
     /** For an identity-key payment: what the recipient needs to internalize the output (BRC-29). Deliver it to them. */
     remittance?: Brc29Remittance;
 }
-type PaymentErrorCode = 'BAD_REQUEST' | 'RESOLVE_FAILED' | 'RATE_FAILED' | 'WALLET_REJECTED' | 'WALLET_ERROR' | 'NOT_SUPPORTED';
+type PaymentErrorCode = 'BAD_REQUEST' | 'RESOLVE_FAILED' | 'RATE_FAILED' | 'WALLET_REJECTED' | 'WALLET_ERROR' | 'NOT_SUPPORTED' | 'INSUFFICIENT_FUNDS';
+/** (0.7.0) The plain message for a wallet with no coins for the network fee (PaymentError code INSUFFICIENT_FUNDS). */
+declare const NO_COINS_TEXT = "Your wallet doesn't have enough to cover this payment and its small network fee. Add a little and try again.";
+/**
+ * True when createAction failed because the wallet has no coins (or too few) to fund it: the SDK's
+ * WERR_INSUFFICIENT_FUNDS (code 7, also as it arrives from Metanet Desktop over the JSON API), or a wallet's own
+ * "insufficient funds" text. Nothing was sent in that case.
+ */
+declare function isInsufficientFunds(e: unknown): boolean;
 declare class PaymentError extends Error {
     readonly code: PaymentErrorCode;
     /** true when the wallet was asked to spend and the outcome is unknown. Check before trying again. */
@@ -294,6 +302,11 @@ declare function desktopOption(ms?: number): WalletOption;
  * `force` (picker off): the first detected wallet, else the first non-pairing option, else pairing.
  */
 declare function autoChoice(list: WalletOption[], force?: boolean): WalletOption | null | undefined;
+/**
+ * (0.7.0) A desktop wallet reached over localhost (json-api on 3321 = Metanet Desktop, Cicada on 3301): never picked
+ * by the button, the fast path or a remembered choice; only by its own tap ("Use Metanet Desktop…").
+ */
+declare function isLocalDesktop(w: Pick<WalletOption, 'id' | 'substrate'>): boolean;
 
 /** The wallet type every bWalletX (extension, in-app, app frame, phone) reports. */
 declare const BWALLETX_TYPE = "bwalletx";
@@ -317,7 +330,7 @@ declare function chooserOrder(list: readonly WalletOption[]): WalletOption[];
  * 'bwalletx-phone': picker off and no bWalletX here, so the phone; 'legacy': fastPath false (0.5.5 autoChoice);
  * 'chooser': show the chooser; 'none': nothing to offer.
  */
-type ChoiceReason = 'requested' | 'bwalletx' | 'bwalletx-phone' | 'legacy' | 'chooser' | 'none';
+type ChoiceReason = 'requested' | 'remembered' | 'bwalletx' | 'bwalletx-phone' | 'legacy' | 'chooser' | 'none';
 interface WalletChoice {
     option: WalletOption | null;
     reason: ChoiceReason;
@@ -331,6 +344,10 @@ interface DecideWalletOptions {
     picker?: boolean;
     /** The bWalletX-first rule. Default true; false restores the 0.5.5 behaviour (autoChoice). */
     fastPath?: boolean;
+    /** (0.6.0) The wallet the user picked on this origin before (rememberedWalletChoice()). Used when it is here. */
+    remembered?: RememberedWallet | null;
+    /** (0.6.0) "Switch" to bWalletX: ignore a remembered other wallet. */
+    preferBwalletX?: boolean;
 }
 /** The wallet to connect now, or the chooser ({ option: null, reason: 'chooser' }). */
 declare function decideWallet(list: readonly WalletOption[], o?: DecideWalletOptions): WalletChoice;
@@ -354,5 +371,72 @@ declare function outcomeOf(e: unknown): AttemptOutcome;
 declare function attemptFor(option: WalletOption | null | undefined, outcome: AttemptOutcome, startedAt: number, now?: number): ConnectAttempt;
 /** Call the hook with exactly the four fields; a throwing hook never breaks sign-in. */
 declare function reportAttempt(hook: AttemptHook | undefined, a: ConnectAttempt): void;
+/** localStorage key (per origin, like all localStorage) for the wallet type picked here. Never holds a key. */
+declare const WALLET_CHOICE_KEY = "bwx:wallet";
+/** What is remembered: the wallet type and how it reached the page. Nothing that identifies the user. */
+interface RememberedWallet {
+    type: string;
+    substrate: Substrate;
+}
+/**
+ * True when the same wallet can be found again next time: bWalletX, an announced wallet (by its rdns), a desktop
+ * wallet, an app adapter. A bare window.CWI cannot (whoever holds it next time may be another wallet), so it is
+ * never remembered.
+ */
+declare function isRememberable(o: WalletOption): boolean;
+/** Whether a successful connect counts as the user's explicit pick: bWalletX (they tapped its button), or chosen. */
+declare function isExplicitPick(o: WalletOption, reason: ChoiceReason): boolean;
+/** Remember the wallet type picked on this origin (or forget with null). Silently skips what can't be remembered. */
+declare function rememberWalletChoice(o: WalletOption | null): void;
+/** The wallet type picked on this origin before, or null. Anything malformed or key-like is ignored. */
+declare function rememberedWalletChoice(): RememberedWallet | null;
+/** Forget the remembered wallet (Disconnect does this). */
+declare function forgetWalletChoice(): void;
+/** True when this wallet type is not bWalletX: show "Some features need bWalletX · Switch". */
+declare function needsBwalletX(type: string | null | undefined): boolean;
+/**
+ * (0.7.0) True when the signed-out button's tap goes to this remembered wallet instead of bWalletX ("Continue with your
+ * wallet", the Switch note). Never for Metanet: the button never picks it (it has its own link and "Not you?").
+ */
+declare function tapGoesElsewhere(type: string | null | undefined): boolean;
+/** (0.7.0) A remembered desktop wallet on localhost (Metanet, 'desktop', json-api, cicada): never the button's pick. */
+declare function isLocalDesktopType(r: RememberedWallet): boolean;
+/**
+ * The option in `list` for a remembered wallet, or null when it isn't here. bWalletX counts only by its own marker
+ * (or the phone, when the phone was picked). A remembered desktop wallet on localhost (Metanet / 'desktop') gives null
+ * (0.7.0): the button never picks it; its own link does.
+ */
+declare function matchRemembered(list: readonly WalletOption[], r: RememberedWallet): WalletOption | null;
+/**
+ * What to do on page load for a returning visitor (0.6.0).
+ *   'attach'       signed in already (a server session) and the remembered wallet is in the page: pick it up by
+ *                  discovery alone (no wallet call, so no prompt) so pay/tip work without another tap;
+ *   'wait-for-tap' anything else a wallet would have to answer (a key, a signature, a localhost probe, a relay
+ *                  reconnect): nothing fires; the next tap goes straight to the remembered wallet;
+ *   'silent-metanet' (0.7.0) Metanet Desktop remembered, on a computer outside any frame: ONE silent attempt this page
+ *                  load (trySilentMetanet: 2 s, known identity keys only), else the normal choice;
+ *   'none'         nothing remembered, or auto-connect off (or Metanet remembered where it isn't offered).
+ */
+type AutoConnectAction = 'attach' | 'wait-for-tap' | 'silent-metanet' | 'none';
+interface AutoConnectPlan {
+    action: AutoConnectAction;
+    remembered: RememberedWallet | null;
+    /** The remembered wallet isn't bWalletX: show "Some features need bWalletX · Switch". */
+    needsBwalletX: boolean;
+}
+declare function planAutoConnect(o: {
+    remembered: RememberedWallet | null;
+    signedIn: boolean;
+    enabled?: boolean;
+    /** (0.7.0) Metanet is offered here (a computer, outside any frame). Default metanetOffered(). */
+    metanetHere?: boolean;
+}): AutoConnectPlan;
+/**
+ * Find the remembered wallet in the page by discovery alone: no wallet method is called, nothing touches localhost,
+ * no relay is opened. null when it isn't here (or it isn't something that can be attached silently).
+ */
+declare function attachRemembered(r: RememberedWallet, o?: {
+    ms?: number;
+}): Promise<WalletOption | null>;
 
-export { pay as $, type AttemptHook as A, type BuyTokenRequest as B, type ConnectedWallet as C, DESKTOP_OPTION_ID as D, type WalletChoice as E, type WalletKind as F, amountInSats as G, type HandCashAdapterOptions as H, attemptFor as I, buyToken as J, chooserOrder as K, type LegacyPayer as L, clearPairing as M, cwiIsAnnounced as N, decideWallet as O, type PayRequest as P, desktopOption as Q, hasBwalletX as R, type Substrate as S, type TokenQuote as T, isIdentityKeyHex as U, isPaymail as V, type WalletOption as W, isPresentBwalletX as X, otherDetected as Y, outcomeOf as Z, pairBwalletX as _, type PayResult as a, reportAttempt as a0, resolvePaymailP2P as a1, restorePairing as a2, substrateOf as a3, tip as a4, walletTypeOf as a5, type PayOptions as b, PaymentError as c, autoChoice as d, brc100Option as e, discoverWallets as f, type PairingOptions as g, handcashAdapter as h, type ChoiceReason as i, type AttemptOutcome as j, BRC29_PROTOCOL as k, BWALLETX_TYPE as l, type Brc29Remittance as m, type ConnectAttempt as n, type ConnectOptions as o, pairingOption as p, type DecideWalletOptions as q, type DiscoverWalletsOptions as r, type PairConnectionOptions as s, type PairStorage as t, type PairedWallet as u, type PayOutput as v, type PaySource as w, type PaymentErrorCode as x, type SocketFactory as y, type SocketLike as z };
+export { hasBwalletX as $, type AttemptHook as A, type BuyTokenRequest as B, type ConnectedWallet as C, DESKTOP_OPTION_ID as D, type SocketFactory as E, type SocketLike as F, WALLET_CHOICE_KEY as G, type HandCashAdapterOptions as H, type WalletChoice as I, type WalletKind as J, amountInSats as K, type LegacyPayer as L, attachRemembered as M, NO_COINS_TEXT as N, attemptFor as O, type PayRequest as P, buyToken as Q, type RememberedWallet as R, type Substrate as S, type TokenQuote as T, chooserOrder as U, clearPairing as V, type WalletOption as W, cwiIsAnnounced as X, decideWallet as Y, desktopOption as Z, forgetWalletChoice as _, type PayResult as a, isExplicitPick as a0, isIdentityKeyHex as a1, isInsufficientFunds as a2, isLocalDesktop as a3, isLocalDesktopType as a4, isPaymail as a5, isPresentBwalletX as a6, isRememberable as a7, matchRemembered as a8, needsBwalletX as a9, otherDetected as aa, outcomeOf as ab, pairBwalletX as ac, pay as ad, planAutoConnect as ae, rememberWalletChoice as af, rememberedWalletChoice as ag, reportAttempt as ah, resolvePaymailP2P as ai, restorePairing as aj, substrateOf as ak, tapGoesElsewhere as al, tip as am, walletTypeOf as an, type PayOptions as b, PaymentError as c, autoChoice as d, brc100Option as e, discoverWallets as f, type PairingOptions as g, handcashAdapter as h, type ChoiceReason as i, type AttemptOutcome as j, type AutoConnectAction as k, type AutoConnectPlan as l, BRC29_PROTOCOL as m, BWALLETX_TYPE as n, type Brc29Remittance as o, pairingOption as p, type ConnectAttempt as q, type ConnectOptions as r, type DecideWalletOptions as s, type DiscoverWalletsOptions as t, type PairConnectionOptions as u, type PairStorage as v, type PairedWallet as w, type PayOutput as x, type PaySource as y, type PaymentErrorCode as z };