@fluent.xyz/connect 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -3,25 +3,24 @@ import { ReactNode, RefObject } from 'react';
3
3
  import * as web from '@privy-io/react-auth';
4
4
  import * as viem from 'viem';
5
5
  import { Address, WalletClient } from 'viem';
6
- import { a as FluentWidgetNetwork, b as FluentGasTokenSymbol, c as FluentGasPaymentEthRates, d as FluentAccountType, e as FluentBatchApi } from './batchOperation-CIcgSRv5.js';
7
- export { f as FluentAccountCapabilities, F as FluentBatchCallInput, h as FluentBatchOperation, j as FluentBatchOperationExecuteOptions, k as FluentBatchOperationInput, l as FluentEncodedBatchCall, m as FluentExecuteResult, o as FluentExecuteTiming, p as FluentExecuteTimingInstants, q as FluentFixedAccountGas, r as FluentFixedPaymasterGas, s as FluentGasPayment, t as FluentSignApi, u as FluentSigningMode, v as FluentUserOperationGas, w as FluentUserOperationGasError, x as FluentUserOperationGasErrorCode, y as FluentWidgetAccount, z as FluentWidgetExecutionStatus, A as FluentWidgetGasPayment, B as getFluentChainForNetwork } from './batchOperation-CIcgSRv5.js';
6
+ import { a as FluentWidgetNetwork, b as FluentGasTokenSymbol, c as FluentGasPaymentEthRates, d as FluentAccountType, e as FluentBatchApi } from './batchOperation-B5Fd0-QX.js';
7
+ export { f as FluentAccountCapabilities, F as FluentBatchCallInput, h as FluentBatchOperation, j as FluentBatchOperationExecuteOptions, k as FluentBatchOperationInput, l as FluentEncodedBatchCall, m as FluentExecuteResult, o as FluentExecuteTiming, p as FluentExecuteTimingInstants, q as FluentFixedAccountGas, r as FluentFixedPaymasterGas, s as FluentGasPayment, t as FluentSignApi, u as FluentSigningMode, v as FluentUserOperationGas, w as FluentUserOperationGasError, x as FluentUserOperationGasErrorCode, y as FluentWidgetAccount, z as FluentWidgetExecutionStatus, A as FluentWidgetGasPayment, B as getFluentChainForNetwork } from './batchOperation-B5Fd0-QX.js';
8
8
 
9
9
  /**
10
- * Privy runtime supplied by a host using a native SDK. Its Provider owns session
11
- * restoration, login and wallet RPC; web hosts keep the normal React SDK.
12
- * Keep one stable adapter per runtime. Changing its Provider remounts descendants
13
- * so React hooks from different SDKs never share a component lifetime.
10
+ * The Privy runtime an App that runs a native Privy SDK passes as `privyAdapter`, in place of
11
+ * `@privy-io/react-auth`. Its `PrivyProvider` owns session restoration, login and wallet RPC; an
12
+ * App on the web passes none. Keep one stable adapter per runtime: a change of its
13
+ * `PrivyProvider` remounts everything below it, so hooks of two SDKs never share a component
14
+ * lifetime.
14
15
  *
15
16
  * @experimental May change or be removed in a minor release: the one provider seam of the
16
- * widget, kept for hosts that run a native login SDK.
17
+ * widget, kept for Apps that run a native login SDK.
17
18
  */
18
19
  type FluentPrivyAdapter = Pick<typeof web, "PrivyProvider" | "Captcha" | "usePrivy" | "useSignMessage" | "useSignTypedData" | "useWallets" | "useIdentityToken" | "useUser" | "useLinkAccount" | "useLoginWithSiwe" | "useModalStatus" | "useCreateWallet" | "useLoginWithEmail" | "useLoginWithOAuth" | "useLoginWithPasskey" | "useLinkWithPasskey">;
19
20
 
20
21
  /**
21
22
  * One Fluent chain as the registry describes it: its ids, native currency, RPC and explorer
22
- * endpoints, its L1 parent and its contracts. Declared rather than inferred from
23
- * `fluentChainSchema`, so its shape is what this file says; `chainDefinitionMatchesSchema`
24
- * below fails the build if the two drift apart.
23
+ * endpoints, its L1 parent and its contracts.
25
24
  */
26
25
  type FluentChainDefinition = {
27
26
  /** The registry's own id: `"fluent-testnet"`, `"fluent-mainnet"`. */
@@ -103,24 +102,28 @@ type FluentChainDefinition = {
103
102
  */
104
103
  declare function getFluentChainByChainId(chainId: number): FluentChainDefinition | undefined;
105
104
 
106
- /** Fluent public testnet (chain id 20994) */
105
+ /** The viem chain of Fluent testnet, chain id `20994`. */
107
106
  declare const fluentTestnet: viem.Chain;
108
- /** Fluent mainnet (chain id 25363) */
107
+ /** The viem chain of Fluent mainnet, chain id `25363`. */
109
108
  declare const fluentMainnet: viem.Chain;
110
109
 
111
110
  /**
112
111
  * Why an operation was not sponsored, and the `code` of a `FluentSponsorshipFallbackError`.
112
+ * `no_token`: no Auth token could be had for the operation. `unauthorized`: the sponsorship
113
+ * service answered HTTP 401 or 403. `unreachable`: the request failed with another HTTP status
114
+ * or none. `denied`: any other failure of the sponsored submission, a policy denial included.
113
115
  * `not_requested` is the only one that is not a failure: the caller asked to pay its own gas,
114
116
  * so the sponsorship paymaster was never contacted. For the same reason it is never the error's
115
117
  * code, which is thrown only after a sponsored attempt failed: the error carries one of the
116
- * other four.
118
+ * other four. See `docs/errors.md` for each code's conditions.
117
119
  */
118
120
  type FluentSponsorshipReason = "no_token" | "denied" | "unauthorized" | "unreachable" | "not_requested";
119
121
  /**
120
- * Both the sponsored submission and the fallback, the account paying its own gas, failed.
121
- * `code` (equal to `sponsorshipReason`) says why Sponsorship was refused: `no_token`, `denied`,
122
- * `unauthorized` or `unreachable`, never `not_requested`. `fallbackError` is what the own-gas
123
- * submission failed with, and `cause` the sponsored submission's error.
122
+ * A Fluent ID's operation whose sponsored submission failed, and whose fallback, the account
123
+ * paying its own gas, failed too. `code` (equal to `sponsorshipReason`) says why Sponsorship was
124
+ * refused: `no_token`, `denied`, `unauthorized` or `unreachable`, never `not_requested`.
125
+ * `fallbackError` is what the own-gas submission failed with, and `cause` the sponsored
126
+ * submission's error.
124
127
  *
125
128
  * Neither is the error that was thrown. Each is a plain object `{ name, message, status? }`:
126
129
  * `name` is the thrown error's name (`"Error"` for a thrown value that is not an `Error`),
@@ -175,8 +178,8 @@ declare class FluentGasPaymentError extends Error {
175
178
  }
176
179
 
177
180
  /**
178
- * Images for the widget, each a URL or a data URI. Today the widget reads only `fluentLogo`,
179
- * which it passes to the provider behind Direct login as its logo; see `assets` in
181
+ * Images for the widget, each a URL or a data URI. Of an App's `assets` the widget reads only
182
+ * `fluentLogo`, which it passes to the provider behind Direct login as its logo; see `assets` in
180
183
  * [configuration.md](configuration.md).
181
184
  */
182
185
  type FluentWidgetAssets = {
@@ -194,15 +197,15 @@ type FluentWidgetAssets = {
194
197
  * and when the widget built that snapshot. Not a credential: an App proves who the person is
195
198
  * with an Auth token from `getAuthToken()`.
196
199
  *
197
- * Only a Fluent ID's Direct login writes a session. Connecting an External wallet neither writes nor
198
- * clears it; read the connected account from `widget.account`.
200
+ * Only a Fluent ID's Direct login writes a session. Connecting an External wallet neither writes
201
+ * nor clears it; read the connected account from `widget.account`.
199
202
  */
200
203
  type FluentWidgetSession = {
201
204
  account: {
202
205
  /** The Fluent ID's smart account address. */
203
206
  address: Address;
204
207
  /**
205
- * `"smart"`: today a session is only ever a Fluent ID's. `FluentAccountType` may gain
208
+ * `"smart"`: only a Fluent ID's Direct login writes a session. `FluentAccountType` may gain
206
209
  * values, so a `switch` over it keeps a `default` branch.
207
210
  */
208
211
  type: FluentAccountType;
@@ -214,15 +217,21 @@ type FluentWidgetSession = {
214
217
  issuedAt: number;
215
218
  };
216
219
  /**
217
- * A sign-in method the sign-in dialog can offer beside X. X is not on this list:
218
- * it is always offered and cannot be switched off.
220
+ * An Auth method the connect dialog can offer beside X. X is not on this list: it is always
221
+ * offered and cannot be switched off.
219
222
  */
220
223
  type FluentWidgetAuthMethod = "google" | "email" | "passkey";
221
224
  /**
222
- * Which value in `FluentWidgetConfig` was refused, for a host that branches rather than reads
225
+ * Which value in `FluentWidgetConfig` was refused, for an App that branches rather than reads
223
226
  * the message.
224
227
  */
225
- type FluentWidgetConfigErrorCode = "invalid_fee_source" | "invalid_receipt_source" | "invalid_chain_check_before_sign"
228
+ type FluentWidgetConfigErrorCode =
229
+ /** `execution.feeSource` is neither `"chain"` nor `"bundler"`. */
230
+ "invalid_fee_source"
231
+ /** `execution.receiptSource` is neither `"chain"` nor `"bundler"`. */
232
+ | "invalid_receipt_source"
233
+ /** `execution.chainCheckBeforeSign` is not a boolean. */
234
+ | "invalid_chain_check_before_sign"
226
235
  /** A required option is absent or empty. */
227
236
  | "missing_option"
228
237
  /** An option holds a value the widget cannot use. */
@@ -233,8 +242,8 @@ type FluentWidgetConfigErrorCode = "invalid_fee_source" | "invalid_receipt_sourc
233
242
  * A value in `FluentWidgetConfig` the widget refuses to start with.
234
243
  *
235
244
  * Thrown when `<FluentWidget>` renders with a config it has not resolved yet: on its first
236
- * render, and again on any render that passes a new `config` object. So it surfaces at startup
237
- * where the integrator is looking rather than at the first send. The message names the option and
245
+ * render, and again on any render that passes a new `config` object, so it surfaces at startup
246
+ * rather than at the first send. The message names the option and
238
247
  * how to fix it; `code`, a `FluentWidgetConfigErrorCode`, is what to branch on.
239
248
  *
240
249
  * @example
@@ -300,7 +309,10 @@ type FluentWidgetExecution = {
300
309
  };
301
310
  /** The configuration of one `<FluentWidget>`, fixed for the App's deployment. */
302
311
  type FluentWidgetConfig = {
303
- /** The App's id (`app_<32 hex>`) — the same string the Fluent Dashboard shows and the token's `aud` carries. */
312
+ /**
313
+ * The App's id (`app_<32 hex>`): the string the Fluent Dashboard shows and an Auth token's
314
+ * `aud` carries.
315
+ */
304
316
  appId: string;
305
317
  /**
306
318
  * The Privy app client issued by Fluent for this App. Login configuration, not
@@ -311,9 +323,9 @@ type FluentWidgetConfig = {
311
323
  * Privy, and goes when Fluent's own login replaces it.
312
324
  */
313
325
  privyClientId: string;
314
- /** Removed in 0.2.0 — the type exists only so the error names the fix. */
326
+ /** Not an option: typed so that a config passing it is refused with a message naming `appId`. */
315
327
  clientId?: never;
316
- /** Renamed to `appId` in 0.3.0 — the type exists only so the error names the fix. */
328
+ /** Not an option: typed so that a config passing it is refused with a message naming `appId`. */
317
329
  partnerId?: never;
318
330
  /**
319
331
  * The Network the widget runs on. It picks the chain, the funds, the login app, the account
@@ -321,41 +333,55 @@ type FluentWidgetConfig = {
321
333
  * it and has no default.
322
334
  */
323
335
  network: FluentWidgetNetwork;
336
+ /** The App's name, shown in the connect dialog and on the Review. */
324
337
  appName?: string;
325
338
  /**
326
339
  * An HTTPS URL passed to the provider behind Direct login as its OAuth redirect URL. When to
327
340
  * use it: [experimental.md](experimental.md#customoauthredirecturl).
328
341
  *
329
342
  * @experimental May change or be removed in a minor release: it configures the redirect of
330
- * the login provider the widget runs on today.
343
+ * the login provider the widget runs on.
331
344
  */
332
345
  customOAuthRedirectUrl?: string;
333
346
  /**
334
- * Sign-in methods the sign-in dialog offers beside X, in the order given.
335
- * Defaults to `["google", "email", "passkey"]` — all of them; name a shorter
336
- * set to drop the rest, or `[]` to leave X as the only Fluent method.
337
- * Sign-in with X is always offered and is not a value here.
347
+ * The Auth methods the connect dialog offers beside X, in the order given: any of `"google"`,
348
+ * `"email"` and `"passkey"`. Defaults to `["google", "email"]`; name `"passkey"` to offer it, a
349
+ * shorter set to drop the rest, or `[]` to leave X as the only one. X is always offered and is
350
+ * not a value here.
338
351
  *
339
- * A method still has to be enabled for the App by Fluent — listing it here only decides
340
- * whether its button is drawn.
352
+ * A method still has to be enabled for the App by Fluent: listing it here only decides whether
353
+ * its button is drawn.
341
354
  */
342
355
  enabledAuthMethods?: FluentWidgetAuthMethod[];
343
356
  /**
344
- * The swap entry in the account drawer.
357
+ * The USDnr on-ramp, run by Swapper Finance, that the account drawer offers. It is offered
358
+ * only when `enabled` is `true` and the other three fields are non-empty.
345
359
  *
346
360
  * @experimental May change or be removed in a minor release while the defaults are measured;
347
361
  * the defaults are the recommended setting.
348
362
  */
349
363
  swapper?: {
364
+ /** Whether the on-ramp is offered. Defaults to `true`. */
350
365
  enabled?: boolean;
366
+ /** The Swapper Finance integrator id. Defaults to Fluent's own. */
351
367
  integratorId?: string;
368
+ /** The chain the on-ramp delivers to, a decimal chain id. Defaults to `"25363"`, mainnet. */
352
369
  dstChainId?: string;
370
+ /** The token the on-ramp delivers. Defaults to USDnr on mainnet. */
353
371
  dstTokenAddress?: string;
354
372
  };
373
+ /** How the widget pays gas: its default Gas token, Sponsorship and the rates it shows. */
355
374
  gasPayment?: {
356
- /** Initial/fallback token. Defaults to ETH; a valid saved user choice wins. */
375
+ /**
376
+ * The Gas token the widget charges until the person chooses one. Defaults to ETH; the
377
+ * person's own choice wins when it names a Gas token of the Network.
378
+ */
357
379
  defaultToken?: FluentGasTokenSymbol;
358
- /** Native-gas sponsorship policy. Defaults to `auto`; `never` skips the paymaster. */
380
+ /**
381
+ * Whether a Gas payment in native ETH asks for Sponsorship: `"auto"` asks, `"never"` does not
382
+ * and the account pays its own gas. Defaults to `"auto"`; a Batch operation's own
383
+ * `gasPayment.sponsorship` wins over it.
384
+ */
359
385
  sponsorship?: "auto" | "never";
360
386
  /**
361
387
  * What one unit of each Gas token is worth in ETH, a `FluentGasPaymentEthRates` keyed by
@@ -375,36 +401,55 @@ type FluentWidgetConfig = {
375
401
  * measured; the defaults are the recommended setting.
376
402
  */
377
403
  execution?: FluentWidgetExecution;
404
+ /** How far Quick sign reaches for this App. */
378
405
  quickSign?: {
379
406
  /**
380
- * Call targets Quick sign may execute without the Review. With a list set, a Batch
381
- * operation runs in Silent mode only when every call's `to` is on it; a single call to any
382
- * other address shows the Review, even with Quick sign on. An
383
- * empty list is honoured and stops Quick sign from silencing anything; omit the
384
- * option to keep it covering every address. Compared case-insensitively.
385
- * `signMessage` / `signTypedData` have no call target and are not scoped by this.
407
+ * Call targets Quick sign may execute without the Review. With a list set, a Batch operation
408
+ * runs in Silent mode only when every call's `to` is on it; a single call to any other
409
+ * address shows the Review, even with Quick sign on. An empty list is honoured and stops
410
+ * Quick sign from skipping any Review; omit the option to keep it covering every address.
411
+ * Compared case-insensitively. `signMessage` and `signTypedData` have no call target and are
412
+ * not scoped by this.
386
413
  */
387
414
  whitelistAddresses?: readonly string[];
388
415
  };
389
416
  /**
390
- * `false` drops the Reputation tab that follows Tokens and Activity in the
391
- * account drawer. The families request is never made. Default `true`.
417
+ * Whether the account drawer has its Reputation tab, after Tokens and Activity. `false` drops
418
+ * the tab, and the widget requests no families. Defaults to `true`.
392
419
  */
393
420
  reputationEnabled?: boolean;
421
+ /** The `source` every analytics event carries. Defaults to `"fluent_connect_widget"`. */
394
422
  source?: string;
423
+ /** The `campaign` every analytics event carries; unset, the events carry none. */
395
424
  campaign?: string;
396
- /** Turns off all analytics: PostHog is never initialised, nothing is sent or stored. */
425
+ /**
426
+ * Turns off analytics: PostHog is not initialised and nothing is sent or stored, and the
427
+ * External wallet connector's own analytics is off. Defaults to `false`.
428
+ */
397
429
  disableAnalytics?: boolean;
398
- /** Restore injected wallets and WalletConnect by default; true restores all, false restores none. */
430
+ /**
431
+ * Which External wallets reconnect on page load. Unset, injected wallets and WalletConnect do;
432
+ * `true` reconnects every connector, `false` none.
433
+ */
399
434
  reconnectOnMount?: boolean;
400
435
  /**
401
- * Point the widget at a sponsorship service other than the network default. Local
402
- * development only: the deployed URL is the one every real integration should use.
436
+ * A sponsorship service other than the Network's own, for local development: the deployed
437
+ * service is the one every App uses.
403
438
  *
404
439
  * @experimental May change or be removed in a minor release while the defaults are measured;
405
440
  * the defaults are the recommended setting.
406
441
  */
407
442
  sponsorshipUrl?: string;
443
+ /**
444
+ * An Order deposit service other than the Network's own, for local development: the base URL
445
+ * its quote and order requests go to. An empty string turns Order deposits off, and USDC
446
+ * then crosses through the swap facility and the bridge. The deployed service is the one
447
+ * every App uses.
448
+ *
449
+ * @experimental May change or be removed in a minor release while the defaults are measured;
450
+ * the defaults are the recommended setting.
451
+ */
452
+ orderDepositUrl?: string;
408
453
  /**
409
454
  * `getAuthToken()` reuses a token until this many seconds before its `exp`, then fetches a
410
455
  * fresh one (the renewal-offset pattern: MSAL's `tokenRenewalOffsetSeconds`, Go oauth2's
@@ -416,16 +461,16 @@ type FluentWidgetConfig = {
416
461
  authTokenRenewalOffsetSeconds?: number;
417
462
  /** Images for the widget; see `FluentWidgetAssets`. */
418
463
  assets?: Partial<FluentWidgetAssets>;
419
- /** The account avatar shown on the connect button and in the account drawer. */
464
+ /** The Account avatar, shown on the connect button and in the account drawer. */
420
465
  avatar?: {
421
466
  /**
422
- * Image used when there is no X avatar to show — a URL or a data URI.
423
- * Defaults to the Fluent mark.
467
+ * The image the Account avatar shows when there is no linked X picture to show, a URL or a
468
+ * data URI. Defaults to the Fluent mark.
424
469
  */
425
470
  defaultLogoUrl?: string;
426
471
  /**
427
- * Always show `defaultLogoUrl`, even for users who signed in with X.
428
- * Default `false` (the linked X picture wins when the person has one).
472
+ * Whether the Account avatar always shows the default image, even for a person with a
473
+ * Linked X account. Defaults to `false`: the linked X picture wins when there is one.
429
474
  */
430
475
  forceDefault?: boolean;
431
476
  };
@@ -438,10 +483,16 @@ type FluentWidgetConfig = {
438
483
  * connection is not a 0.6.0 commitment.
439
484
  */
440
485
  type FluentWalletChoice = {
486
+ /** What `connectChoice` is called with when the user picks this wallet. */
441
487
  id: string;
488
+ /** The wallet's name, shown on its button. */
442
489
  name: string;
490
+ /** The URL of the wallet's icon; without it the button shows a generic wallet icon. */
443
491
  icon?: string;
444
- /** This connector opens an external wallet/QR surface. */
492
+ /**
493
+ * Whether this wallet opens a surface of its own, such as a WalletConnect QR code: the connect
494
+ * dialog then closes before connecting it instead of showing its wait screen.
495
+ */
445
496
  handoff?: boolean;
446
497
  };
447
498
  /**
@@ -453,54 +504,68 @@ type FluentWalletChoice = {
453
504
  * connection is not a 0.6.0 commitment.
454
505
  */
455
506
  type FluentExternalWalletState = {
507
+ /**
508
+ * Whether an External wallet can be connected at all; `false` disables its row in the connect
509
+ * dialog.
510
+ */
456
511
  configured: boolean;
512
+ /** Whether an External wallet is connected. */
457
513
  connected: boolean;
514
+ /** The connected wallet's address. */
458
515
  address?: string;
516
+ /** The chain the connected wallet reports. */
459
517
  chainId?: number;
518
+ /**
519
+ * The client the widget signs and sends through, once the client's account is `address`.
520
+ */
460
521
  walletClient?: WalletClient;
461
522
  /**
462
- * True while the wallet is being restored from a previous visit and neither
463
- * `connected` nor "no wallet" is known yet. Optional so hosts supplying their
464
- * own wallet state keep working; omitting it just means the widget reports
465
- * `"disconnected"` slightly earlier during a reload.
523
+ * True while the wallet is being restored from a previous visit and neither `connected` nor
524
+ * "no wallet" is known yet. Without it the widget can report `"disconnected"` during a reload
525
+ * before the wallet is back.
466
526
  */
467
527
  reconnecting?: boolean;
468
- /** Optional inline choices; hosts without them keep their existing open() picker. */
528
+ /**
529
+ * The wallets the connect dialog offers inline. Without them, or without `connectChoice`, the
530
+ * dialog calls `open` instead.
531
+ */
469
532
  choices?: readonly FluentWalletChoice[];
533
+ /** Connects the wallet of the `FluentWalletChoice` with this `id`. */
470
534
  connectChoice?: (id: string) => Promise<void>;
535
+ /** Opens the host's own wallet picker. */
471
536
  open: () => void;
537
+ /** Disconnects the External wallet. */
472
538
  disconnect: () => void;
539
+ /** Asks the wallet to switch to `chainId`; the widget calls it before using the wallet. */
473
540
  switchChain: (chainId: number) => Promise<void>;
474
541
  };
475
542
  /**
476
- * Top-level connection state of the widget, safe to read on any render.
477
- *
478
- * The distinction that matters is `"restoring"` vs `"disconnected"`: a session
479
- * restored from a previous visit is not known synchronously, so a host that
480
- * treats "not connected yet" as "no account" will render a Connect button at
481
- * users who do have a live session. Wait out `"restoring"` instead.
482
- *
483
- * - `"restoring"` — a previous session may exist; nothing is decided yet.
484
- * - `"connecting"` — a sign-in the user started is in flight.
485
- * - `"connected"` — an account is available. Whether it can send transactions
486
- * *right now* is a separate question — see `widget.account.executionStatus`.
487
- * - `"disconnected"` — no account, and none is being restored or negotiated.
543
+ * The widget's connection state, safe to read on any render.
544
+ *
545
+ * The distinction that matters is `"restoring"` against `"disconnected"`: a sign-in kept from a
546
+ * previous visit is not known synchronously, so an App that treats "not connected yet" as "no
547
+ * account" shows a Connect button to people who are still signed in. Wait out `"restoring"`.
548
+ *
549
+ * - `"restoring"`: a previous sign-in may exist; nothing is decided yet.
550
+ * - `"connecting"`: a Connect the user started is in flight.
551
+ * - `"connected"`: a Widget account is available. Whether it can send right now is
552
+ * `widget.account.executionStatus`.
553
+ * - `"disconnected"`: no Widget account, and none is being restored or connected.
488
554
  */
489
555
  type FluentWidgetStatus = "restoring" | "connecting" | "connected" | "disconnected";
490
556
 
491
557
  /**
492
- * Why `getAuthToken()`, `linkX()`, or `widget.signMessage()` / `widget.signTypedData()` was
493
- * refused (the signatures throw `not_connected` and `root_signer_required`). The codes are the
494
- * SDK's own, named for the product rather than for a vendor or a mechanism: where the service
495
- * answers with a code of its own, the SDK maps it here before it reaches the App, and a service
496
- * code the SDK does not name reaches `getAuthToken()` as `service_refused` and `linkX()` as
497
- * `link_failed`. Keep a `default` branch in a
498
- * `switch` over them: a later release may add a code.
558
+ * The reason `getAuthToken()`, `linkX()`, `widget.signMessage()` or `widget.signTypedData()`
559
+ * was refused; the two signing calls throw only `not_connected` and `root_signer_required`.
560
+ * The codes are the SDK's own, named for the product rather than for a vendor or a mechanism:
561
+ * the SDK maps a service's code to one of them before it reaches the App, and a service code
562
+ * the SDK does not name reaches `getAuthToken()` as `service_refused` and `linkX()` as
563
+ * `link_failed`. Keep a `default` branch in a `switch` over them: a later release may add one.
499
564
  */
500
565
  type FluentAuthErrorCode = "unknown_app" | "app_not_auth_enabled" | "origin_not_allowed" | "origin_missing" | "bad_request" | "challenge_unknown" | "challenge_used" | "challenge_expired" | "app_mismatch" | "invalid_signature" | "signature_prefix_rejected" | "address_already_linked" | "invalid_login_credential" | "no_signer" | "invalid_refresh_token" | "refresh_token_reused" | "rate_limited" | "internal" | "not_connected" | "root_signer_required" | "login_credential_missing" | "origin_mismatch" | "request_failed" | "service_refused" | "not_authenticated" | "user_rejected" | "linked_to_another_user" | "link_failed";
501
566
  /**
502
- * A refused Auth token or X link. `code` is a `FluentAuthErrorCode`; `status` is the service's
503
- * HTTP status when the service refused it.
567
+ * A refused Auth token request, X link or signature. `code` is a `FluentAuthErrorCode`;
568
+ * `status` is the service's HTTP status when the service refused it.
504
569
  */
505
570
  declare class FluentAuthError extends Error {
506
571
  readonly code: FluentAuthErrorCode;
@@ -508,10 +573,13 @@ declare class FluentAuthError extends Error {
508
573
  constructor(code: FluentAuthErrorCode, message: string, status?: number | undefined);
509
574
  }
510
575
 
511
- /** One X account as the Fluent auth service reports it. */
576
+ /** One X account as the Fluent service reports it. */
512
577
  type FluentXAccount = {
578
+ /** The X account's id. */
513
579
  id: string;
580
+ /** The X account's handle. */
514
581
  handle: string;
582
+ /** The URL of the X account's picture, which the Account avatar shows. */
515
583
  avatarUrl: string;
516
584
  };
517
585
  /**
@@ -522,7 +590,7 @@ type FluentLinkXResult = {
522
590
  status: "linked";
523
591
  x: FluentXAccount;
524
592
  }
525
- /** The page is leaving for X. Call linkX() again after the return; useLinkX() does it on mount. */
593
+ /** The page is leaving for X. Call `linkX()` again after the return; `useLinkX()` does. */
526
594
  | {
527
595
  status: "redirecting";
528
596
  };
@@ -575,7 +643,7 @@ type FluentWidgetRenderContext = {
575
643
  * The External wallet as the widget sees it, a `FluentExternalWalletState` whose inline
576
644
  * choices are `FluentWalletChoice`s, or `null`.
577
645
  *
578
- * @experimental May change or be removed in a minor release: a host that brings its own wallet
646
+ * @experimental May change or be removed in a minor release: an App that brings its own wallet
579
647
  * connection is not a 0.6.0 commitment.
580
648
  */
581
649
  wallet: FluentExternalWalletState | null;
@@ -589,10 +657,9 @@ type FluentWidgetRenderContext = {
589
657
  /** Opens the account drawer, as the connect button does once a Widget account is connected. */
590
658
  openAccount: () => void;
591
659
  /**
592
- * Tear down the current session without going through the widget's account
593
- * menu — the same teardown that menu's "Disconnect" runs. The session and the
594
- * stored identity token are cleared before this resolves, so a host can await
595
- * it before resetting its own state.
660
+ * Disconnects the Widget account, the same teardown the account menu's "Disconnect" runs. The
661
+ * Widget session and the stored identity token are cleared before it resolves, so an App can
662
+ * await it before resetting its own state.
596
663
  *
597
664
  * It also asks the service to revoke the Service session, and any Service session that a
598
665
  * `getAuthToken()` still out at the disconnect opens later, and resolves once those requests
@@ -607,26 +674,24 @@ type FluentWidgetRenderContext = {
607
674
  */
608
675
  hasConnectedAccount: boolean;
609
676
  /**
610
- * Connection state as a single value that is meaningful on every render —
611
- * including the first, before a stored session has been reconciled. Branch on
612
- * this rather than on `hasConnectedAccount` alone: `"restoring"` and
613
- * `"disconnected"` both have `hasConnectedAccount === false`, and treating
614
- * them alike shows a Connect button to users who are already signed in. The
615
- * account's address is `widget.account.address`.
677
+ * The connection state as one value, meaningful on every render including the first, before a
678
+ * stored session has been restored. Branch on it rather than on `hasConnectedAccount` alone:
679
+ * `"restoring"` and `"disconnected"` both have `hasConnectedAccount === false`, and treating
680
+ * them alike shows a Connect button to a person who is signed in. The account's address is
681
+ * `widget.account.address`.
616
682
  */
617
683
  status: FluentWidgetStatus;
618
684
  /**
619
- * Refetch the widget's on-chain balances. Transactions run through
620
- * `widget.createBatchOp` refresh automatically, and the wallet menu reads them
621
- * itself when it opens and every 10 seconds while it stays open; call this to
622
- * show a tx sent via an External wallet client (outside the widget's execution
623
- * path) before the next scheduled read.
685
+ * Refetches the widget's on-chain balances. A Batch operation run through
686
+ * `widget.createBatchOp` refreshes them itself, and the account drawer reads them when it opens
687
+ * and every 10 seconds while it stays open; call this to show a transaction sent through an
688
+ * External wallet's own client, outside the widget, before the next read.
624
689
  */
625
690
  refreshBalances: () => void;
626
691
  /**
627
- * A short-lived (5 min) Auth token, a Fluent-signed JWT for the connected person. Verify it on
628
- * your backend against `<iss>/.well-known/jwks.json` (ES256), checking `iss`, `aud` (= your
629
- * appId) and `exp`; `sub` is stable per person per App. Reused until
692
+ * Returns a short-lived (5 min) Auth token, a Fluent-signed JWT for the connected person.
693
+ * Verify it on your backend against `<iss>/.well-known/jwks.json` (ES256), checking `iss`,
694
+ * `aud` (= your appId) and `exp`; `sub` is stable per person per App. Reused until
630
695
  * `authTokenRenewalOffsetSeconds` before `exp`, then renewed; a renewal the service accepts
631
696
  * asks the wallet for nothing. When the wallet is asked to sign:
632
697
  * [guides/backend-auth.md](guides/backend-auth.md#renewal). External wallets: EOAs and deployed
@@ -651,7 +716,7 @@ type FluentWidgetRenderContext = {
651
716
  */
652
717
  getAuthToken: () => Promise<string>;
653
718
  /**
654
- * Link an X account to the connected person, headless: no widget screen, no settings page,
719
+ * Links an X account to the connected person, headless: no widget screen, no settings page,
655
720
  * one call. Idempotent and re-enterable, because linking X needs an OAuth round trip that
656
721
  * leaves the page.
657
722
  *
@@ -676,9 +741,14 @@ type FluentWidgetRenderContext = {
676
741
  };
677
742
  /** What `renderConnectButton` receives to draw its own connect button. */
678
743
  type FluentWidgetConnectButtonRenderContext = {
744
+ /** Whether a Widget account is connected, the render context's `hasConnectedAccount`. */
679
745
  connected: boolean;
680
- /** True while a Fluent ID's smart account is being prepared after sign-in. */
746
+ /** `true` while a Fluent ID is signed in and its smart account is still being prepared. */
681
747
  pending: boolean;
748
+ /**
749
+ * The connected account's shortened address, or `"Connected"` while the address is not known;
750
+ * absent while no Widget account is connected.
751
+ */
682
752
  addressLabel?: string;
683
753
  /** The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. */
684
754
  userAvatarUrl?: string;
@@ -686,48 +756,62 @@ type FluentWidgetConnectButtonRenderContext = {
686
756
  userXDisplayName?: string;
687
757
  /** The person's Google name, the render context's `userGoogleName`. */
688
758
  userGoogleName?: string;
759
+ /** What the widget's own button does on a click: toggles the drawer or opens sign-in. */
689
760
  onClick: () => void;
761
+ /** The render context's `openConnect`. */
690
762
  openConnect: () => void;
763
+ /** The render context's `openAccount`. */
691
764
  openAccount: () => void;
765
+ /** The widget's own connect button, to render inside a custom one or beside it. */
692
766
  DefaultButton: () => ReactNode;
693
767
  };
694
768
  /** The props of `<FluentWidget>`. */
695
769
  type FluentWidgetProps = {
696
770
  /**
697
- * An External wallet the host connects itself, a `FluentExternalWalletState` whose inline
771
+ * An External wallet the App connects itself, a `FluentExternalWalletState` whose inline
698
772
  * choices are `FluentWalletChoice`s; omit it to let the widget connect one.
699
773
  *
700
- * @experimental May change or be removed in a minor release: a host that brings its own wallet
774
+ * @experimental May change or be removed in a minor release: an App that brings its own wallet
701
775
  * connection is not a 0.6.0 commitment.
702
776
  */
703
777
  wallet?: FluentExternalWalletState | null;
778
+ /** The widget's configuration; keep the object stable, since a new one is resolved again. */
704
779
  config: FluentWidgetConfig;
705
780
  /**
706
- * Optional native Privy SDK bridge, a `FluentPrivyAdapter`, for a host that runs Privy's
781
+ * Optional native Privy SDK bridge, a `FluentPrivyAdapter`, for an App that runs Privy's
707
782
  * native SDK; requires Direct login.
708
783
  *
709
784
  * @experimental May change or be removed in a minor release: the one provider seam of the
710
- * widget, kept for hosts that run a native login SDK.
785
+ * widget, kept for Apps that run a native login SDK.
711
786
  */
712
787
  privyAdapter?: FluentPrivyAdapter;
788
+ /**
789
+ * Which render prop the widget renders: `"home"` (the default) renders `renderHome`, `"page"`
790
+ * renders `renderPage`. With `debugLogging` on, `"home"` also shows the debug panel.
791
+ */
713
792
  mode?: "home" | "page";
714
793
  /**
715
- * Show the default connect/account control.
716
- * - `"fixed"` (default) — top-right floating button
717
- * - `"inline"` — same button, no fixed positioning (host places via CSS / wrapper)
718
- * - `false` — hide; use `renderConnectButton`, `openConnect`, or `openAccount`
794
+ * Where the widget's own connect button goes.
795
+ * - `"fixed"` (default): floating at the top right of the page.
796
+ * - `"inline"`: the same button without fixed positioning, for the App's layout to place.
797
+ * - `false`: hidden; use `renderConnectButton`, `openConnect` or `openAccount`.
719
798
  */
720
799
  connectButton?: "fixed" | "inline" | false;
721
- /** Replace the default connect button UI / placement entirely. */
800
+ /**
801
+ * A function that draws the App's own connect button in place of the widget's; when it returns
802
+ * `null` or `undefined`, `connectButton` applies instead.
803
+ */
722
804
  renderConnectButton?: (context: FluentWidgetConnectButtonRenderContext) => ReactNode;
805
+ /** The App's content in `mode="home"`, given the render context. */
723
806
  renderHome?: (context: FluentWidgetRenderContext) => ReactNode;
807
+ /** The App's content in `mode="page"`, given the render context. */
724
808
  renderPage?: (context: FluentWidgetRenderContext) => ReactNode;
725
809
  /** Integrator tokens the widget lists beside its Default tokens; see `FluentTokenDefinition`. */
726
810
  tokens?: readonly FluentTokenDefinition[];
727
811
  /**
728
- * Print the widget's internal connect / smart-account / signing diagnostics to
729
- * the console, and show the debug panel in `mode="home"`. Off by default; turn
730
- * on only while debugging an integration.
812
+ * Whether the widget prints its connect, smart-account and signing diagnostics to the console
813
+ * and shows the debug panel in `mode="home"`. Off by default; turn it on only while debugging
814
+ * an integration.
731
815
  */
732
816
  debugLogging?: boolean;
733
817
  /**
@@ -742,6 +826,10 @@ type FluentWidgetProps = {
742
826
  * The Fluent Connect widget: the connect button, the sign-in dialog, the account drawer and the
743
827
  * Widget API, provided to the App's own content rendered through `renderHome` or `renderPage`.
744
828
  *
829
+ * Renders on a server: the render context there is the `restoring` status with no session and
830
+ * no wallet, and the real state arrives after hydration — see the getting-started guide's
831
+ * server-side rendering section.
832
+ *
745
833
  * @throws `FluentWidgetConfigError` from a render when `config` cannot be used, its `code`
746
834
  * `missing_option`, `invalid_option` or `removed_option` with the option named in its message,
747
835
  * or, for the experimental `execution`, `invalid_fee_source`, `invalid_receipt_source` or
@@ -764,19 +852,18 @@ type FluentWidgetProps = {
764
852
  declare function FluentWidget(props: FluentWidgetProps): react.JSX.Element;
765
853
 
766
854
  /**
767
- * Access the Fluent widget render context from any component rendered inside
768
- * `<FluentWidget>` (e.g. within `renderHome` / `renderPage`). Returns the same
769
- * object the render props receive — `session`, `widget`, `openConnect`, etc. —
770
- * so host apps no longer need to prop-drill it. The Widget API is
771
- * `useFluentWidget().widget`.
855
+ * Returns the render context of the enclosing `<FluentWidget>`: the object `renderHome` and
856
+ * `renderPage` receive, with the Widget API as its `widget`.
772
857
  *
773
- * Throws if used outside `<FluentWidget>`.
858
+ * Throws an `Error` when called outside `<FluentWidget>`.
774
859
  *
775
860
  * @example
776
861
  * ```tsx
777
862
  * import { useFluentWidget } from "@fluent.xyz/connect";
778
863
  *
779
- * const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
864
+ * const calls = [
865
+ * { to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" },
866
+ * ] as const;
780
867
  *
781
868
  * export function Send() {
782
869
  * const { widget, status } = useFluentWidget();
@@ -790,17 +877,19 @@ declare function useFluentWidget(): FluentWidgetRenderContext;
790
877
  /** Which Review the person dismissed: a Batch operation's or a signature's. */
791
878
  type FluentReviewRejectedErrorCode = "transaction_review_rejected" | "signature_review_rejected";
792
879
  /**
793
- * The person dismissed a Review (transaction or signature) instead of confirming it.
880
+ * A Review the person dismissed instead of confirming it: a Batch operation's or a signature's.
794
881
  *
795
- * A class with a `code`, not a message, so a host branches on `code` and callers that translate
796
- * errors for another party — the iframe bridge maps it to EIP-1193 `4001` — recognise it
797
- * without parsing prose.
882
+ * A class with a `code`, not a message, so an App branches on `code` and callers that translate
883
+ * errors for another party (the Iframe bridge maps it to EIP-1193 `4001`) recognise it without
884
+ * parsing prose.
798
885
  *
799
886
  * @example
800
887
  * ```ts
801
888
  * import { FluentReviewRejectedError, type FluentBatchApi } from "@fluent.xyz/connect";
802
889
  *
803
- * const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
890
+ * const calls = [
891
+ * { to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" },
892
+ * ] as const;
804
893
  *
805
894
  * export async function send(widget: FluentBatchApi) {
806
895
  * try {
@@ -825,15 +914,20 @@ declare class FluentReviewRejectedError extends Error {
825
914
  */
826
915
  type FluentLinkXStatus = "idle" | "pending" | "redirecting" | "linked" | "error";
827
916
  /**
828
- * Linking X as a component sees it: the call, and what the last one did.
917
+ * Returns `linkX()` for a component that links X, with what its last call did: `status`, the
918
+ * Linked X account as `x`, and `error`.
829
919
  *
830
- * `redirecting` is the status a page is unlikely to render for long — it is set just before the
831
- * browser leaves for X — and `linked` after a return is what the mount-time re-entry produces
832
- * without the component asking for anything.
920
+ * `redirecting` is set just before the browser leaves for X, so a page rarely renders it for
921
+ * long. On the return from X the hook calls `linkX()` again on mount, without the component
922
+ * asking, and that call sets `linked`.
833
923
  *
834
- * @throws From `linkX`, as the render context's `linkX()` does: a `FluentAuthError` whose `code`
835
- * is today `not_authenticated`, `user_rejected`, `linked_to_another_user`, `bad_request` or
836
- * `link_failed` (keep a `default` branch); the same error is kept in `error`.
924
+ * @throws `FluentAuthError` from the `linkX` it returns, as the render context's `linkX()` does,
925
+ * with `code` `not_authenticated` when no Fluent ID or External wallet is connected or the
926
+ * wallet's client is not ready, `user_rejected` when the person declines at X or a signature the
927
+ * link needs, `linked_to_another_user` when that X account belongs to another person,
928
+ * `bad_request` when the service refuses the request body, and `link_failed` for anything
929
+ * else. The same error is kept in `error`; keep a `default` branch for a code a later release
930
+ * adds.
837
931
  *
838
932
  * @example
839
933
  * ```tsx
@@ -876,17 +970,17 @@ type UseFluentIframeBridgeOptions = {
876
970
  allowedOrigin: string;
877
971
  };
878
972
  /**
879
- * Lets a page embedded in `iframeRef` use the account signed in here, over the
880
- * JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The bridge lives
881
- * while the component is mounted; the bridge states the chain and account before its
882
- * first reply, and sign-in and sign-out reach the iframe as `accountsChanged`.
973
+ * Opens the Iframe bridge: the page embedded in `iframeRef` uses the Widget account as its
974
+ * wallet, over the JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The
975
+ * bridge lives while the component is mounted, states the chain and account before its first
976
+ * reply, and sends each connect and disconnect to the iframe as `accountsChanged`.
977
+ *
978
+ * Throws an `Error`, from the effect that builds the bridge and so to the nearest error
979
+ * boundary, when `allowedOrigin` is not an `http:` or `https:` origin: `"*"` and a bare host
980
+ * are refused.
883
981
  *
884
982
  * @param iframeRef The `<iframe>` the embedded page runs in; read on every message, so an
885
983
  * element swapped in after mount is still answered.
886
- * @param options `allowedOrigin`, the one origin whose messages are answered.
887
- * @throws `Error`, from the effect that builds the bridge (so to the nearest error boundary),
888
- * when `allowedOrigin` is not an `http:` or `https:` origin: `"*"` and a bare host are
889
- * refused.
890
984
  *
891
985
  * @example
892
986
  * ```tsx
@@ -909,13 +1003,14 @@ type AccountAvatarProps = {
909
1003
  * `defaultLogoUrl`.
910
1004
  */
911
1005
  userAvatarUrl?: string | null;
912
- /** Host-supplied stand-in for the Fluent mark — a URL or a data URI. */
1006
+ /** The App's stand-in for the Fluent mark: a URL or a data URI. */
913
1007
  defaultLogoUrl?: string | null;
1008
+ /** Classes added to the Fluent mark when it is drawn; the image does not take them. */
914
1009
  className?: string;
915
1010
  };
916
1011
  /**
917
- * The Account avatar: the person's linked X picture, else the host's default logo, else the
918
- * Fluent mark.
1012
+ * The Account avatar: the person's linked X picture, else the App's default logo, else the
1013
+ * Fluent mark. An image that fails to load falls back to the Fluent mark until the URL changes.
919
1014
  *
920
1015
  * @example
921
1016
  * ```tsx