@bwalletx/connect 0.5.4 → 0.7.0

package/dist/react.d.cts

@@ -1,8 +1,8 @@
 import { ReactNode, ReactElement, CSSProperties } from 'react';
 import { WalletInterface } from '@bsv/sdk';
-import { C as ConnectedWallet, W as WalletOption, P as PayRequest, a as PayResult, B as BuyTokenRequest, b as PayOptions } from './wallets-CbzMtxrf.cjs';
-export { H as HandCashAdapterOptions, c as PaymentError, d as brc100Option, e as discoverWallets, h as handcashAdapter, p as pairingOption } from './wallets-CbzMtxrf.cjs';
-import { SigninSize, SigninTheme, SigninLabel, SigninBrand } from './element.cjs';
+import { R as RememberedWallet, C as ConnectedWallet, W as WalletOption, P as PayRequest, a as PayResult, B as BuyTokenRequest, A as AttemptHook, b as PayOptions } from './choice-B97AjqF4.cjs';
+export { H as HandCashAdapterOptions, c as PaymentError, d as autoChoice, e as brc100Option, f as discoverWallets, h as handcashAdapter, p as pairingOption } from './choice-B97AjqF4.cjs';
+import { S as SigninSize, a as SigninTheme, b as SigninLabel, c as SigninBrand, d as SigninState } from './element-BXEoOdXY.cjs';
 
 /**
  * React wrapper for <bwalletx-signin>. React is an optional peer dependency; the button itself is
@@ -40,6 +40,25 @@ interface BwalletxSigninProps {
     redirectUri?: string;
     scope?: string;
     discoverMs?: number;
+    /** "Other wallets" link under the button: 'auto' (default: lg/md), 'on' or 'off'. */
+    otherWallets?: 'auto' | 'on' | 'off';
+    /**
+     * (0.7.0) "Use Metanet Desktop or another BRC-100 wallet" under the button: 'auto' (default: lg/md on a computer,
+     * outside any frame), 'on' or 'off'. Connects to localhost:3321 on its own tap only.
+     */
+    metanet?: 'auto' | 'on' | 'off';
+    /** Without a provider: GET → { identityKey, handle?, paymail? } restores the signed-in badge on load. */
+    sessionUrl?: string;
+    /** Without a provider: POST on Disconnect. */
+    logoutUrl?: string;
+    /** Paymail lookup for the badge; 'off' to skip. */
+    lookupUrl?: string;
+    /**
+     * Show the signed-in badge and the pending / error states (default true). Inside <BwalletXProvider> the button
+     * follows the provider: click → connect() (one wallet sheet), badge when signed in, Disconnect → disconnect()
+     * (logoutUrl). Set false for the pre-0.5.5 plain button.
+     */
+    stateful?: boolean;
     'aria-label'?: string;
     className?: string;
     style?: CSSProperties;
@@ -51,7 +70,11 @@ interface BwalletxSigninProps {
     onSignedIn?: (d: SignedInDetail) => void;
     onNotFound?: () => void;
     onError?: (error: unknown) => void;
+    /** After Disconnect in the badge menu. */
+    onSignedOut?: () => void;
 }
+/** The element state for the provider's state. */
+declare function signinStateFor(v: Pick<BwalletXState, 'status' | 'identityKey'>): SigninState;
 declare function BwalletxSignin(props: BwalletxSigninProps): ReactElement;
 
 type BwalletXStatus = 'idle' | 'restoring' | 'connecting' | 'connected' | 'error';
@@ -64,6 +87,14 @@ interface BwalletXState {
     wallet: WalletInterface | null;
     /** Which option connected (e.g. 'com.bwalletx.extension', 'bwalletx-pairing', 'handcash'). */
     walletId: string | null;
+    /** 'bwalletx' for any bWalletX, else the wallet's rdns / option id (0.5.6). null until connect(). */
+    walletType: string | null;
+    /** (0.6.0) The wallet type picked on this origin before (no keys), or null. Read after mount. */
+    rememberedWallet: RememberedWallet | null;
+    /** (0.6.0) The connected (or remembered) wallet isn't bWalletX: show "Some features need bWalletX · Switch". */
+    needsBwalletX: boolean;
+    /** (0.7.0) "Use Metanet Desktop or another BRC-100 wallet" is offered here (a computer, outside any frame). */
+    metanetOffered: boolean;
     /** True while the transitional HandCash adapter is in use. */
     transitional: boolean;
     /** The server session (verifyUrl/sessionUrl) is in place. */
@@ -71,10 +102,29 @@ interface BwalletXState {
     error: Error | null;
 }
 interface BwalletXContextValue extends BwalletXState {
-    /** Find wallets, show the picker if there is a choice, connect, and sign in if verifyUrl is set. */
+    /**
+     * Find wallets, connect, and sign in if verifyUrl is set. bWalletX in this browser is used straight away (0.5.6);
+     * without it the chooser opens with "Get bWalletX" first. `chooser: true` is the "Other wallets" link: the chooser
+     * even when bWalletX is here.
+     */
     connect(opts?: {
         walletId?: string;
+        chooser?: boolean;
+        bwalletx?: boolean;
+        metanet?: boolean;
     }): Promise<ConnectedWallet | null>;
+    /** (0.6.0) "Switch": sign in with bWalletX (straight to it when here, else the chooser with Get bWalletX first). */
+    switchToBwalletX(): Promise<ConnectedWallet | null>;
+    /**
+     * (0.7.0) "Use Metanet Desktop or another BRC-100 wallet": connect to localhost:3321 (pinned json-api) and sign in.
+     * Call it from the user's tap only.
+     */
+    connectMetanet(): Promise<ConnectedWallet | null>;
+    /**
+     * (0.7.0) "Not you? Use another wallet": forget the wallet remembered on this origin and drop a silent Metanet
+     * sign-in in flight (a session its verify already set is ended through logoutUrl).
+     */
+    forgetWallet(): void;
     disconnect(): Promise<void>;
     /** The wallets found on the last connect() (or listWallets()). */
     wallets: WalletOption[];
@@ -85,22 +135,57 @@ interface BwalletXContextValue extends BwalletXState {
 }
 interface BwalletXProviderProps {
     children?: ReactNode;
-    /** POST { identityKey } → challenge. With verifyUrl, connect() also signs in. */
+    /** POST {} (or { identityKey }) → challenge. With verifyUrl, connect() also signs in, in ONE wallet sheet. */
     challengeUrl?: string;
     /** POST { identityKey, nonce, signature } → { identityKey, handle?, paymail? } and sets the cookie. */
     verifyUrl?: string;
-    /** POST to clear the cookie on disconnect(). */
+    /**
+     * POST to clear the cookie on disconnect(). REQUIRED whenever verifyUrl is set (0.7.0): "Not you? Use another wallet"
+     * and disconnect() end a session the verify route created through it. Missing → a console.warn in development.
+     */
     logoutUrl?: string;
     /** GET → { identityKey, handle?, paymail? } to restore a session on load. */
     sessionUrl?: string;
     /** Offer phone pairing with the built-in QR modal. Default true. */
     pairing?: boolean;
-    /** Show the built-in picker when more than one wallet is available. Default true. */
+    /**
+     * Show the built-in picker when there is a real choice. Default true. One wallet found in this browser (and no
+     * app-supplied option such as HandCash) is used straight away, with no picker; phone pairing is then not offered.
+     */
     picker?: boolean;
+    /**
+     * Your challenge route is older than 0.5.5 and needs the identity key first (two wallet sheets). Normally not
+     * needed: such a server is detected and retried. Upgrade the server to @bwalletx/connect 0.5.5 for one sheet.
+     */
+    challengeNeedsIdentityKey?: boolean;
+    /** Paymail lookup by identity key for the signed-in badge (best effort). Default pay.bwallet.space; 'off' to skip. */
+    lookupUrl?: string;
     /** Extra options, e.g. [handcashAdapter({ login })]. */
     extraWallets?: WalletOption[];
-    /** Probe desktop wallets on localhost. Default false. */
+    /**
+     * Probe desktop wallets on localhost while listing. Default false, and best left off (Chrome's Local Network Access
+     * prompt): the chooser offers "Desktop wallet", which probes only when tapped.
+     */
     probeLocal?: boolean;
+    /**
+     * bWalletX first (0.5.6, default true): with bWalletX in this browser connect() goes straight to its sheet, no
+     * chooser; without it the chooser opens, "Get bWalletX" first, and another wallet is connected only when picked.
+     * false: the 0.5.5 picker rule (one detected wallet of any brand was used without asking).
+     */
+    fastPath?: boolean;
+    /** Called once per connect attempt with { walletType, substrate, outcome, ms }. No keys, addresses or identity data. */
+    onAttempt?: AttemptHook;
+    /**
+     * (0.6.0) Remember the wallet TYPE the user explicitly picked on this origin (localStorage `bwx:wallet`; never a key)
+     * and go straight to it on the next tap, with no chooser. Disconnect forgets it. Default true.
+     */
+    rememberChoice?: boolean;
+    /**
+     * (0.6.0) On load, for a returning visitor with a server session, pick up the remembered wallet by discovery alone
+     * (no wallet call, so no prompt; never a localhost probe) so pay/tip work without another tap. Without a session
+     * nothing fires on load: a connect would ask the wallet, so it waits for the tap. Default true.
+     */
+    autoConnect?: boolean;
     /**
      * A theme the wallet already bundles (e.g. 'npgx') for bWalletX to wear while this site is connected and is the
      * active tab. Declared only while connecting or connected; withdrawn on disconnect. See declareWalletTheme.
@@ -114,8 +199,29 @@ interface BwalletXProviderProps {
 declare function BwalletXProvider(p: BwalletXProviderProps): ReactElement;
 /** The wallet + session state. Must be inside <BwalletXProvider>. */
 declare function useBwalletX(): BwalletXContextValue;
+type BwalletXAccountStatus = 'restoring' | 'signed-out' | 'pending' | 'signed-in' | 'error';
+interface BwalletXAccount {
+    status: BwalletXAccountStatus;
+    identityKey: string | null;
+    paymail: string | null;
+    handle: string | null;
+    /** $alice, a site handle, the paymail, or a short key: what the badge shows. */
+    label: string | null;
+    /** The bAvatar picture for the identity key (gold by default), or null when signed out. */
+    avatarUrl: string | null;
+    /** One plain line for the last error ("Sign-in cancelled" for a no in the wallet), or null. */
+    error: string | null;
+    /** Sign in (the provider's connect(): one wallet sheet). Never throws; failures show in `status`/`error`. */
+    login(): Promise<void>;
+    /** Sign out: the provider's disconnect() (posts logoutUrl). */
+    logout(): Promise<void>;
+}
+/** The account view of a provider state (what useBwalletXAccount returns). */
+declare function accountFor(v: BwalletXContextValue): BwalletXAccount;
+/** The signed-in account for your own UI: { status, identityKey, paymail, handle, avatarUrl, logout, … }. Inside <BwalletXProvider>. */
+declare function useBwalletXAccount(): BwalletXAccount;
 
 /** Alias with the casing used by <BwalletxSignin>. */
 declare const BwalletxProvider: typeof BwalletXProvider;
 
-export { BuyTokenRequest, type BwalletXContextValue, BwalletXProvider, type BwalletXProviderProps, type BwalletXState, type BwalletXStatus, BwalletxProvider, BwalletxSignin, type BwalletxSigninProps, ConnectedWallet, PayOptions, PayRequest, PayResult, type SignedInDetail, WalletOption, BwalletxSignin as default, useBwalletX };
+export { BuyTokenRequest, type BwalletXAccount, type BwalletXAccountStatus, type BwalletXContextValue, BwalletXProvider, type BwalletXProviderProps, type BwalletXState, type BwalletXStatus, BwalletxProvider, BwalletxSignin, type BwalletxSigninProps, ConnectedWallet, PayOptions, PayRequest, PayResult, type SignedInDetail, WalletOption, accountFor, BwalletxSignin as default, signinStateFor, useBwalletX, useBwalletXAccount };

package/dist/react.d.ts

@@ -1,8 +1,8 @@
 import { ReactNode, ReactElement, CSSProperties } from 'react';
 import { WalletInterface } from '@bsv/sdk';
-import { C as ConnectedWallet, W as WalletOption, P as PayRequest, a as PayResult, B as BuyTokenRequest, b as PayOptions } from './wallets-CbzMtxrf.js';
-export { H as HandCashAdapterOptions, c as PaymentError, d as brc100Option, e as discoverWallets, h as handcashAdapter, p as pairingOption } from './wallets-CbzMtxrf.js';
-import { SigninSize, SigninTheme, SigninLabel, SigninBrand } from './element.js';
+import { R as RememberedWallet, C as ConnectedWallet, W as WalletOption, P as PayRequest, a as PayResult, B as BuyTokenRequest, A as AttemptHook, b as PayOptions } from './choice-B97AjqF4.js';
+export { H as HandCashAdapterOptions, c as PaymentError, d as autoChoice, e as brc100Option, f as discoverWallets, h as handcashAdapter, p as pairingOption } from './choice-B97AjqF4.js';
+import { S as SigninSize, a as SigninTheme, b as SigninLabel, c as SigninBrand, d as SigninState } from './element-BXEoOdXY.js';
 
 /**
  * React wrapper for <bwalletx-signin>. React is an optional peer dependency; the button itself is
@@ -40,6 +40,25 @@ interface BwalletxSigninProps {
     redirectUri?: string;
     scope?: string;
     discoverMs?: number;
+    /** "Other wallets" link under the button: 'auto' (default: lg/md), 'on' or 'off'. */
+    otherWallets?: 'auto' | 'on' | 'off';
+    /**
+     * (0.7.0) "Use Metanet Desktop or another BRC-100 wallet" under the button: 'auto' (default: lg/md on a computer,
+     * outside any frame), 'on' or 'off'. Connects to localhost:3321 on its own tap only.
+     */
+    metanet?: 'auto' | 'on' | 'off';
+    /** Without a provider: GET → { identityKey, handle?, paymail? } restores the signed-in badge on load. */
+    sessionUrl?: string;
+    /** Without a provider: POST on Disconnect. */
+    logoutUrl?: string;
+    /** Paymail lookup for the badge; 'off' to skip. */
+    lookupUrl?: string;
+    /**
+     * Show the signed-in badge and the pending / error states (default true). Inside <BwalletXProvider> the button
+     * follows the provider: click → connect() (one wallet sheet), badge when signed in, Disconnect → disconnect()
+     * (logoutUrl). Set false for the pre-0.5.5 plain button.
+     */
+    stateful?: boolean;
     'aria-label'?: string;
     className?: string;
     style?: CSSProperties;
@@ -51,7 +70,11 @@ interface BwalletxSigninProps {
     onSignedIn?: (d: SignedInDetail) => void;
     onNotFound?: () => void;
     onError?: (error: unknown) => void;
+    /** After Disconnect in the badge menu. */
+    onSignedOut?: () => void;
 }
+/** The element state for the provider's state. */
+declare function signinStateFor(v: Pick<BwalletXState, 'status' | 'identityKey'>): SigninState;
 declare function BwalletxSignin(props: BwalletxSigninProps): ReactElement;
 
 type BwalletXStatus = 'idle' | 'restoring' | 'connecting' | 'connected' | 'error';
@@ -64,6 +87,14 @@ interface BwalletXState {
     wallet: WalletInterface | null;
     /** Which option connected (e.g. 'com.bwalletx.extension', 'bwalletx-pairing', 'handcash'). */
     walletId: string | null;
+    /** 'bwalletx' for any bWalletX, else the wallet's rdns / option id (0.5.6). null until connect(). */
+    walletType: string | null;
+    /** (0.6.0) The wallet type picked on this origin before (no keys), or null. Read after mount. */
+    rememberedWallet: RememberedWallet | null;
+    /** (0.6.0) The connected (or remembered) wallet isn't bWalletX: show "Some features need bWalletX · Switch". */
+    needsBwalletX: boolean;
+    /** (0.7.0) "Use Metanet Desktop or another BRC-100 wallet" is offered here (a computer, outside any frame). */
+    metanetOffered: boolean;
     /** True while the transitional HandCash adapter is in use. */
     transitional: boolean;
     /** The server session (verifyUrl/sessionUrl) is in place. */
@@ -71,10 +102,29 @@ interface BwalletXState {
     error: Error | null;
 }
 interface BwalletXContextValue extends BwalletXState {
-    /** Find wallets, show the picker if there is a choice, connect, and sign in if verifyUrl is set. */
+    /**
+     * Find wallets, connect, and sign in if verifyUrl is set. bWalletX in this browser is used straight away (0.5.6);
+     * without it the chooser opens with "Get bWalletX" first. `chooser: true` is the "Other wallets" link: the chooser
+     * even when bWalletX is here.
+     */
     connect(opts?: {
         walletId?: string;
+        chooser?: boolean;
+        bwalletx?: boolean;
+        metanet?: boolean;
     }): Promise<ConnectedWallet | null>;
+    /** (0.6.0) "Switch": sign in with bWalletX (straight to it when here, else the chooser with Get bWalletX first). */
+    switchToBwalletX(): Promise<ConnectedWallet | null>;
+    /**
+     * (0.7.0) "Use Metanet Desktop or another BRC-100 wallet": connect to localhost:3321 (pinned json-api) and sign in.
+     * Call it from the user's tap only.
+     */
+    connectMetanet(): Promise<ConnectedWallet | null>;
+    /**
+     * (0.7.0) "Not you? Use another wallet": forget the wallet remembered on this origin and drop a silent Metanet
+     * sign-in in flight (a session its verify already set is ended through logoutUrl).
+     */
+    forgetWallet(): void;
     disconnect(): Promise<void>;
     /** The wallets found on the last connect() (or listWallets()). */
     wallets: WalletOption[];
@@ -85,22 +135,57 @@ interface BwalletXContextValue extends BwalletXState {
 }
 interface BwalletXProviderProps {
     children?: ReactNode;
-    /** POST { identityKey } → challenge. With verifyUrl, connect() also signs in. */
+    /** POST {} (or { identityKey }) → challenge. With verifyUrl, connect() also signs in, in ONE wallet sheet. */
     challengeUrl?: string;
     /** POST { identityKey, nonce, signature } → { identityKey, handle?, paymail? } and sets the cookie. */
     verifyUrl?: string;
-    /** POST to clear the cookie on disconnect(). */
+    /**
+     * POST to clear the cookie on disconnect(). REQUIRED whenever verifyUrl is set (0.7.0): "Not you? Use another wallet"
+     * and disconnect() end a session the verify route created through it. Missing → a console.warn in development.
+     */
     logoutUrl?: string;
     /** GET → { identityKey, handle?, paymail? } to restore a session on load. */
     sessionUrl?: string;
     /** Offer phone pairing with the built-in QR modal. Default true. */
     pairing?: boolean;
-    /** Show the built-in picker when more than one wallet is available. Default true. */
+    /**
+     * Show the built-in picker when there is a real choice. Default true. One wallet found in this browser (and no
+     * app-supplied option such as HandCash) is used straight away, with no picker; phone pairing is then not offered.
+     */
     picker?: boolean;
+    /**
+     * Your challenge route is older than 0.5.5 and needs the identity key first (two wallet sheets). Normally not
+     * needed: such a server is detected and retried. Upgrade the server to @bwalletx/connect 0.5.5 for one sheet.
+     */
+    challengeNeedsIdentityKey?: boolean;
+    /** Paymail lookup by identity key for the signed-in badge (best effort). Default pay.bwallet.space; 'off' to skip. */
+    lookupUrl?: string;
     /** Extra options, e.g. [handcashAdapter({ login })]. */
     extraWallets?: WalletOption[];
-    /** Probe desktop wallets on localhost. Default false. */
+    /**
+     * Probe desktop wallets on localhost while listing. Default false, and best left off (Chrome's Local Network Access
+     * prompt): the chooser offers "Desktop wallet", which probes only when tapped.
+     */
     probeLocal?: boolean;
+    /**
+     * bWalletX first (0.5.6, default true): with bWalletX in this browser connect() goes straight to its sheet, no
+     * chooser; without it the chooser opens, "Get bWalletX" first, and another wallet is connected only when picked.
+     * false: the 0.5.5 picker rule (one detected wallet of any brand was used without asking).
+     */
+    fastPath?: boolean;
+    /** Called once per connect attempt with { walletType, substrate, outcome, ms }. No keys, addresses or identity data. */
+    onAttempt?: AttemptHook;
+    /**
+     * (0.6.0) Remember the wallet TYPE the user explicitly picked on this origin (localStorage `bwx:wallet`; never a key)
+     * and go straight to it on the next tap, with no chooser. Disconnect forgets it. Default true.
+     */
+    rememberChoice?: boolean;
+    /**
+     * (0.6.0) On load, for a returning visitor with a server session, pick up the remembered wallet by discovery alone
+     * (no wallet call, so no prompt; never a localhost probe) so pay/tip work without another tap. Without a session
+     * nothing fires on load: a connect would ask the wallet, so it waits for the tap. Default true.
+     */
+    autoConnect?: boolean;
     /**
      * A theme the wallet already bundles (e.g. 'npgx') for bWalletX to wear while this site is connected and is the
      * active tab. Declared only while connecting or connected; withdrawn on disconnect. See declareWalletTheme.
@@ -114,8 +199,29 @@ interface BwalletXProviderProps {
 declare function BwalletXProvider(p: BwalletXProviderProps): ReactElement;
 /** The wallet + session state. Must be inside <BwalletXProvider>. */
 declare function useBwalletX(): BwalletXContextValue;
+type BwalletXAccountStatus = 'restoring' | 'signed-out' | 'pending' | 'signed-in' | 'error';
+interface BwalletXAccount {
+    status: BwalletXAccountStatus;
+    identityKey: string | null;
+    paymail: string | null;
+    handle: string | null;
+    /** $alice, a site handle, the paymail, or a short key: what the badge shows. */
+    label: string | null;
+    /** The bAvatar picture for the identity key (gold by default), or null when signed out. */
+    avatarUrl: string | null;
+    /** One plain line for the last error ("Sign-in cancelled" for a no in the wallet), or null. */
+    error: string | null;
+    /** Sign in (the provider's connect(): one wallet sheet). Never throws; failures show in `status`/`error`. */
+    login(): Promise<void>;
+    /** Sign out: the provider's disconnect() (posts logoutUrl). */
+    logout(): Promise<void>;
+}
+/** The account view of a provider state (what useBwalletXAccount returns). */
+declare function accountFor(v: BwalletXContextValue): BwalletXAccount;
+/** The signed-in account for your own UI: { status, identityKey, paymail, handle, avatarUrl, logout, … }. Inside <BwalletXProvider>. */
+declare function useBwalletXAccount(): BwalletXAccount;
 
 /** Alias with the casing used by <BwalletxSignin>. */
 declare const BwalletxProvider: typeof BwalletXProvider;
 
-export { BuyTokenRequest, type BwalletXContextValue, BwalletXProvider, type BwalletXProviderProps, type BwalletXState, type BwalletXStatus, BwalletxProvider, BwalletxSignin, type BwalletxSigninProps, ConnectedWallet, PayOptions, PayRequest, PayResult, type SignedInDetail, WalletOption, BwalletxSignin as default, useBwalletX };
+export { BuyTokenRequest, type BwalletXAccount, type BwalletXAccountStatus, type BwalletXContextValue, BwalletXProvider, type BwalletXProviderProps, type BwalletXState, type BwalletXStatus, BwalletxProvider, BwalletxSignin, type BwalletxSigninProps, ConnectedWallet, PayOptions, PayRequest, PayResult, type SignedInDetail, WalletOption, accountFor, BwalletxSignin as default, signinStateFor, useBwalletX, useBwalletXAccount };