@fluent.xyz/connect 0.5.3 → 0.6.0-rc.2

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.
@@ -0,0 +1,247 @@
1
+ # Experimental API
2
+
3
+ > **Everything on this page is `@experimental`.** Each option, member and export below may
4
+ > change or be removed in a minor release. The rest of the API, every name [api.md](api.md)
5
+ > does not mark **experimental**, is kept after 0.6.0. Build on an experimental name only where
6
+ > you can follow its changes from release to release.
7
+
8
+ Each section says what the item does, its default, when to use it, and which account kind it
9
+ applies to: a Fluent ID, an External wallet, or both. The exact types are in [api.md](api.md).
10
+
11
+ | Name | Where it appears | Section |
12
+ |---|---|---|
13
+ | `privyAdapter`, `FluentPrivyAdapter` | `FluentWidgetProps` | [`privyAdapter`](#privyadapter) |
14
+ | `wallet`, `FluentExternalWalletState`, `FluentWalletChoice` | `FluentWidgetProps`, `FluentWidgetRenderContext` | [`wallet`](#wallet) |
15
+ | `execution`, `FluentWidgetExecution`, `FluentWidgetExecutionSource` | `FluentWidgetConfig` | [`execution`](#execution) |
16
+ | `userOperationGas`, `FluentUserOperationGas`, `FluentFixedAccountGas`, `FluentFixedPaymasterGas`, `FluentUserOperationGasError`, `FluentUserOperationGasErrorCode` | `FluentBatchOperationExecuteOptions` | [`userOperationGas`](#useroperationgas) |
17
+ | `paymaster`, `timing`, `FluentExecuteTiming`, `FluentExecuteTimingInstants` | `FluentExecuteResult` | [`paymaster` and `timing`](#paymaster-and-timing) |
18
+ | `gasPayment.ethValueByToken`, `FluentGasPaymentEthRates` | `FluentWidgetConfig` | [`gasPayment.ethValueByToken`](#gaspaymentethvaluebytoken) |
19
+ | `customOAuthRedirectUrl` | `FluentWidgetConfig` | [`customOAuthRedirectUrl`](#customoauthredirecturl) |
20
+ | `swapper` | `FluentWidgetConfig` | [`swapper`](#swapper) |
21
+ | `sponsorshipUrl` | `FluentWidgetConfig` | [`sponsorshipUrl`](#sponsorshipurl) |
22
+ | `privyClientId` | `FluentWidgetConfig` | [`privyClientId`](#privyclientid) |
23
+
24
+ ## `privyAdapter`
25
+
26
+ `FluentWidgetProps.privyAdapter` takes a `FluentPrivyAdapter`: the provider component and the
27
+ hooks of Privy's React SDK, taken from the host's own runtime
28
+ ([api.md](api.md#fluentprivyadapter)).
29
+
30
+ - **What it does**: the widget uses the adapter's provider and hooks in place of the web SDK it
31
+ bundles, so Direct login, its restore on a later page load and the Signer's signatures run
32
+ through the host's SDK.
33
+ - **Default**: none. Without it the widget uses its bundled web SDK, which is what a web App
34
+ needs.
35
+ - **When to use it**: only in a host that runs Privy's native SDK instead of the web one.
36
+ - **Applies to**: a Fluent ID, and an External wallet's `linkX()`. Connecting an External
37
+ wallet does not use it.
38
+ - **Keep it stable**: pass one adapter object for the life of the page. An adapter whose
39
+ provider component differs from the last one remounts everything the widget renders.
40
+
41
+ ## `wallet`
42
+
43
+ `FluentWidgetProps.wallet` takes a `FluentExternalWalletState`: an External wallet the host
44
+ connects itself ([api.md](api.md#fluentexternalwalletstate)).
45
+
46
+ - **What it does**: the widget uses the host's state as its External wallet instead of
47
+ connecting one itself. The state says whether a wallet is `configured` and `connected`, its
48
+ `address`, `chainId` and `walletClient`, and gives the widget `open`, `disconnect` and
49
+ `switchChain` to call. `reconnecting` is `true` while a wallet from an earlier visit is being
50
+ restored; leaving it out makes the widget report `"disconnected"` a little earlier on a
51
+ reload.
52
+ - **Inline choices**: `choices` lists `FluentWalletChoice` entries (`id`, `name`, an optional
53
+ `icon`, and `handoff` for a wallet that opens its own window or a QR code) that the connect
54
+ dialog shows inline; the widget calls `connectChoice(id)` with the one picked. Without them
55
+ the host's `open()` picker is used ([api.md](api.md#fluentwalletchoice)).
56
+ - **Default**: none. Omitted, or `null`, the widget connects External wallets itself.
57
+ - **When to use it**: when the App already manages its own wallet connection and the widget
58
+ has to act for that same wallet.
59
+ - **Applies to**: an External wallet. An External wallet's Batch operation is executed through
60
+ `walletClient`, so the state needs `connected` set to `true` and a `walletClient` for one to be
61
+ sent.
62
+
63
+ `FluentWidgetRenderContext.wallet` (also on `useFluentWidget()`) is the External wallet state the
64
+ widget is using: the host's when the prop is passed, the widget's own otherwise
65
+ ([api.md](api.md#fluentwidgetrendercontext)).
66
+
67
+ ## `execution`
68
+
69
+ `FluentWidgetConfig.execution` takes a `FluentWidgetExecution`, every field optional
70
+ ([api.md](api.md#fluentwidgetexecution)). Both sources are a `FluentWidgetExecutionSource`,
71
+ `"chain"` or `"bundler"` ([api.md](api.md#fluentwidgetexecutionsource)).
72
+
73
+ | Field | Default | What it sets |
74
+ |---|---|---|
75
+ | `feeSource` | `"chain"` | Where a Fluent ID's operation takes its fee quote from: the Fluent chain, or the bundler. |
76
+ | `receiptSource` | `"chain"` | Where the widget watches for the operation's inclusion: the Fluent chain, or the bundler. |
77
+ | `chainCheckBeforeSign` | `false` | `true` reads the Signer's chain before every signature, one extra round trip each. |
78
+
79
+ - **Default**: the values above, on both Networks. A `"chain"` source that fails falls back to
80
+ the bundler on its own, within the operation that needed it. The defaults are the recommended
81
+ setting.
82
+ - **When to use it**: leave it out. Set one field to `"bundler"` to take that one answer from
83
+ the bundler for every operation, for example while diagnosing slow operations with Fluent.
84
+ - **Applies to**: a Fluent ID. `chainCheckBeforeSign` covers both its Batch operations and its
85
+ `signMessage` and `signTypedData` signatures. An External wallet ignores `execution`.
86
+ - **Invalid values**: `<FluentWidget>` throws `FluentWidgetConfigError` from its render, with
87
+ `code` `invalid_fee_source`, `invalid_receipt_source` or `invalid_chain_check_before_sign`
88
+ ([errors.md](errors.md#fluentwidgetconfigerror)).
89
+
90
+ ## `userOperationGas`
91
+
92
+ `userOperationGas` is an option of `execute()`, on `FluentBatchOperationExecuteOptions`. It takes
93
+ a `FluentUserOperationGas`, one of three shapes ([api.md](api.md#fluentuseroperationgas)):
94
+
95
+ | Shape | What the widget does |
96
+ |---|---|
97
+ | `{ callGasLimit }` | Uses this execution gas limit for the whole Batch operation, any Gas token approval included, and estimates the rest. |
98
+ | `{ callGasBuffer: { percentage?, fixed? } }` | Estimates, then adds `percentage` percent (rounded up), then `fixed` gas. |
99
+ | `{ skipEstimation: true, ... }` | Estimates nothing: the App fixes the account's limits, and either fixes the paymaster's too or leaves them to the paymaster. |
100
+
101
+ With `skipEstimation: true`, the account's three limits are a `FluentFixedAccountGas`
102
+ (`callGasLimit`, `verificationGasLimit`, `preVerificationGas`, all required), and the
103
+ paymaster's two are a `FluentFixedPaymasterGas` (`paymasterVerificationGasLimit` and
104
+ `paymasterPostOpGasLimit`): pass both, or neither to use the limits the paymaster authorizes
105
+ ([api.md](api.md#fluentfixedaccountgas), [api.md](api.md#fluentfixedpaymastergas)).
106
+
107
+ - **Default**: omitted, the widget estimates every limit. Omitting it is the recommended
108
+ setting.
109
+ - **When to use it**: a buffer when an operation's estimate runs short; fixed limits when the
110
+ App knows them and wants no estimate.
111
+ - **Applies to**: the policy's shape is checked at the start of every `execute()`, before the
112
+ Review, whatever the account kind, so an invalid shape rejects for an External wallet too. It
113
+ shapes only a Fluent ID's operation: an External wallet's operation ignores a valid policy.
114
+ - **Errors**: `execute()` rejects with `FluentUserOperationGasError`, whose `code` is a
115
+ `FluentUserOperationGasErrorCode` ([errors.md](errors.md#fluentuseroperationgaserror),
116
+ [api.md](api.md#fluentuseroperationgaserror)). A `skipEstimation` policy of the wrong shape is
117
+ `invalid_policy`. Two more checks of a `skipEstimation` policy run at submission, and only
118
+ when a paymaster pays: only one of the two paymaster limits is `invalid_policy`, and a
119
+ paymaster authorization that does not match the fixed limits is `paymaster_gas_mismatch`.
120
+ For a Gas token payment they reject. Under Sponsorship they fail the sponsored submission
121
+ instead, and the operation falls back to the account's own gas
122
+ ([guides/sponsorship.md](guides/sponsorship.md)). An invalid `callGasLimit` or
123
+ `callGasBuffer` without `skipEstimation` rejects with a plain `Error`. Keep a `default` branch
124
+ in any `switch` over the code.
125
+
126
+ This component adds a fifth to the estimate and logs where the time went:
127
+
128
+ ```tsx
129
+ import { useFluentWidget } from "@fluent.xyz/connect";
130
+ import { parseEther, type Address } from "viem";
131
+
132
+ const RECIPIENT: Address = "0x0000000000000000000000000000000000000001";
133
+
134
+ export function TipWithHeadroom() {
135
+ const { widget, status } = useFluentWidget();
136
+ if (status !== "connected") return null;
137
+ const tip = async () => {
138
+ const result = await widget
139
+ .createBatchOp({ calls: [{ to: RECIPIENT, value: parseEther("0.001"), data: "0x" }] })
140
+ .execute({ userOperationGas: { callGasBuffer: { percentage: 20 } } });
141
+ console.log(result.timing?.totalMs, result.paymaster);
142
+ };
143
+ return <button onClick={() => void tip()}>Tip 0.001 ETH</button>;
144
+ }
145
+ ```
146
+
147
+ ## `paymaster` and `timing`
148
+
149
+ Two members of `FluentExecuteResult`, what `execute()` resolves with
150
+ ([api.md](api.md#fluentexecuteresult)).
151
+
152
+ `paymaster` is the address of the contract that paid the operation's gas, read off a Fluent ID's
153
+ receipt: the Sponsorship paymaster or a Gas token's paymaster.
154
+
155
+ - **Absent**: always for an External wallet, whose `sponsored` is always `false`. For a Fluent
156
+ ID, whenever the receipt names no paymaster, which includes an operation the account paid for
157
+ itself; `sponsored` is then `false`, or `null` after a sponsored submission.
158
+ - **When to use it**: to log or check which contract paid. To know whether Sponsorship paid,
159
+ read the kept `sponsored` member instead.
160
+
161
+ `timing` is a `FluentExecuteTiming`: where one operation's milliseconds went
162
+ ([api.md](api.md#fluentexecutetiming)).
163
+
164
+ - `prepareMs`, `signMs` and `broadcastMs` are measured on the page's clock, and each is absent
165
+ when the widget could not measure it. `retryMs` is the time spent on submissions that did not
166
+ settle, such as a refused Sponsorship before the fallback, and is `0` for an operation
167
+ submitted once.
168
+ - `inclusionMs` and `detectMs` are signed estimates across the page's clock and the chain's,
169
+ so either can be negative when it is small. Both are absent when the including block could
170
+ not be read.
171
+ - `totalMs` runs from the first submission to the receipt. It is measured, not summed, and does
172
+ not equal the sum of the parts.
173
+ - `instants`, a `FluentExecuteTimingInstants`, keeps the epoch-millisecond instants and the
174
+ number of `attempts` the estimates were computed from
175
+ ([api.md](api.md#fluentexecutetiminginstants)).
176
+ - **Absent**: always for an External wallet, whose wallet does its prompt, signing and
177
+ broadcast in one call; and for a Fluent ID when the page's clock could not be read.
178
+ - **When to use it**: for logs and latency dashboards. It is collected for every Fluent ID
179
+ operation, whatever `debugLogging` is set to.
180
+
181
+ ## `gasPayment.ethValueByToken`
182
+
183
+ `FluentWidgetConfig.gasPayment.ethValueByToken` takes a `FluentGasPaymentEthRates`: what one
184
+ unit of each Gas token is worth in ETH, as a decimal string, keyed by its `FluentGasTokenSymbol`
185
+ ([api.md](api.md#fluentgaspaymentethrates)).
186
+
187
+ - **What it does**: sets the rates behind the cost the widget shows beside each Gas token.
188
+ - **Default**: the widget works the rates out from the USD prices it reads for the Gas tokens,
189
+ where it has them, with ETH at `"1"`. A rate set here wins over the derived one for its
190
+ symbol; the others stay derived. The defaults are the recommended setting.
191
+ - **When to use it**: when the costs the widget shows for a Gas token are wrong for your App.
192
+ - **Applies to**: a Fluent ID, the only account kind that pays in a Gas token. An External
193
+ wallet pays its gas in ETH.
194
+
195
+ ## `customOAuthRedirectUrl`
196
+
197
+ `FluentWidgetConfig.customOAuthRedirectUrl` is passed to the provider behind Direct login as
198
+ its OAuth redirect URL ([api.md](api.md#fluentwidgetconfig)). The widget reads it nowhere else.
199
+
200
+ - **Default**: omitted, no redirect URL is passed.
201
+ - **When to use it**: in a Capacitor or other native app, where an OAuth return has to land on a
202
+ Universal Link that the host app handles.
203
+ - **Requirements**: an absolute HTTPS URL, with no credentials, query string or fragment.
204
+ Anything else makes `<FluentWidget>` throw `FluentWidgetConfigError` with `code`
205
+ `invalid_option` ([errors.md](errors.md#fluentwidgetconfigerror)); a blank string counts as
206
+ omitted. The exact URL must also be registered with Fluent among the allowed redirects of the
207
+ App's login client.
208
+ - **Applies to**: the OAuth flows of the provider behind Direct login. Which of them return to
209
+ this URL is the provider's to decide, not the widget's.
210
+
211
+ ## `swapper`
212
+
213
+ `FluentWidgetConfig.swapper` sets up the on-ramp that the account drawer's Get USDnr button
214
+ opens: `enabled`, `integratorId`, `dstChainId` and `dstTokenAddress`
215
+ ([api.md](api.md#fluentwidgetconfig)).
216
+
217
+ - **Default**: `enabled` is `true`, and the other three are Fluent's own: the on-ramp buys
218
+ USDnr on Fluent mainnet. The defaults are the recommended setting.
219
+ - **When to use it**: `enabled: false` turns the on-ramp off; Get USDnr is then disabled, with
220
+ "Not configured for this app" on hover.
221
+ - **Applies to**: a Fluent ID on mainnet. The on-ramp delivers to the Fluent ID's address, so
222
+ Get USDnr is disabled while no Fluent ID is connected. On testnet, Get USDnr mints testnet
223
+ USDnr instead and `swapper` is not read.
224
+
225
+ ## `sponsorshipUrl`
226
+
227
+ `FluentWidgetConfig.sponsorshipUrl` points the widget at a sponsorship service other than the
228
+ Network's own ([api.md](api.md#fluentwidgetconfig)).
229
+
230
+ - **Default**: the deployed sponsorship service of the configured Network.
231
+ - **When to use it**: local development of the sponsorship service only. Every real
232
+ integration uses the default.
233
+ - **Applies to**: Sponsorship of a Fluent ID's operations. An External wallet is never
234
+ sponsored.
235
+
236
+ ## `privyClientId`
237
+
238
+ `FluentWidgetConfig.privyClientId` is the login client Fluent issues for the App, a `client-…`
239
+ value ([api.md](api.md#fluentwidgetconfig)). It carries the origins allow-listed for Direct
240
+ login; `appId` is what names the App for Sponsorship, Auth tokens and analytics.
241
+
242
+ - **Default**: none. It is required today although it is marked experimental: it exists while
243
+ login runs on the current provider, and goes when Fluent's own login replaces it.
244
+ - **Errors**: `<FluentWidget>` throws `FluentWidgetConfigError` with `code` `missing_option`
245
+ when it is absent or empty, and `invalid_option` when it does not start with `client-`, an
246
+ `app_…` id included ([errors.md](errors.md#fluentwidgetconfigerror)).
247
+ - **Applies to**: every App, whatever account kind its users connect.
@@ -0,0 +1,336 @@
1
+ # Getting started
2
+
3
+ This guide takes a React App from nothing to a mounted widget that reads the Widget account. It
4
+ covers what to ask Fluent for, the install, the styles, the Network, mounting `<FluentWidget>`,
5
+ the connect button, reading the account, and debugging. The terms it uses (Fluent ID, External
6
+ wallet, Widget account, Widget session) are defined in [concepts.md](concepts.md); every option
7
+ of `config` is in [configuration.md](configuration.md).
8
+
9
+ ## What you need from Fluent
10
+
11
+ Ask Fluent for these before you write any code:
12
+
13
+ - **`appId`**: the App's id, `app_` followed by 32 lowercase hex characters, as the Fluent
14
+ Dashboard shows it.
15
+ - **`privyClientId`**: the login client Fluent issues for the App, a `client-…` value. It is
16
+ required today and is marked experimental, because it goes away when Fluent's own login
17
+ replaces it ([experimental.md](experimental.md#privyclientid)).
18
+ - **Your page origins allow-listed for Direct login**: Direct login happens in the App's own
19
+ page, so every origin the App is served from, a development origin included, has to be
20
+ allow-listed for the App's login client beforehand.
21
+ - **For `getAuthToken()`, Sponsorship, `linkX()` and User settings**: Auth tokens enabled for
22
+ the App, and each page origin that calls it registered on the App. Without them
23
+ `getAuthToken()` rejects with `FluentAuthError` and `code` `app_not_auth_enabled` or
24
+ `origin_not_allowed` ([errors.md](errors.md#fluentautherror)), a Fluent ID's operations are not
25
+ sponsored, `linkX()` cannot complete a link, and a person's User settings are neither loaded
26
+ nor saved. See [guides/backend-auth.md](guides/backend-auth.md).
27
+ - **For Sponsorship, the App enabled for Sponsorship**: without it a Fluent ID's operations are
28
+ not sponsored ([guides/sponsorship.md](guides/sponsorship.md)).
29
+
30
+ ## Install
31
+
32
+ Install the package and its peer dependencies:
33
+
34
+ ```bash
35
+ pnpm add @fluent.xyz/connect @tanstack/react-query react react-dom viem wagmi
36
+ ```
37
+
38
+ The peers are `@tanstack/react-query` 5, `react` and `react-dom` 18 or later, `viem` 2 and
39
+ `wagmi` 2. They are peers rather than dependencies so that your App and the widget resolve one
40
+ copy of each: the `viem` types the Widget API takes and returns (an `Address`, a `Hex`, an
41
+ `Abi`) are the ones your own code imports.
42
+
43
+ You do not need a `QueryClientProvider`. The widget mounts a TanStack Query client of its own.
44
+ When your App mounts its own `QueryClientProvider` around `<FluentWidget>`, the content your
45
+ `renderPage` or `renderHome` returns is rendered under your client again, so a query your App
46
+ prefetched or hydrated is read from your cache; the widget's own queries stay on its client.
47
+
48
+ You do not need a `Buffer` polyfill either. Importing `@fluent.xyz/connect` defines
49
+ `globalThis.Buffer` when the page has none, and leaves an existing one in place.
50
+
51
+ ## Styles
52
+
53
+ Import the widget's stylesheet once, in your App's entry module:
54
+
55
+ ```tsx
56
+ import "@fluent.xyz/connect/styles.css";
57
+ ```
58
+
59
+ ## Network
60
+
61
+ `config.network` names the Network the widget runs on: `"testnet"` or `"mainnet"`. It is
62
+ required and has no default, and the widget reads no environment variable for it. Rendering
63
+ `<FluentWidget>` with no `network` throws `FluentWidgetConfigError` with `code`
64
+ `missing_option`; a value other than the two throws it with `code` `invalid_option`
65
+ ([errors.md](errors.md#fluentwidgetconfigerror)). The error is thrown during the render, so the
66
+ nearest error boundary catches it.
67
+
68
+ The Network is chosen once per deployment of the App, and choosing it is your App's own code.
69
+ Pass the literal each deployment runs on: for example one config module per deployment, each
70
+ with its own literal, or a build-time constant of your own that your code checks is exactly
71
+ `"testnet"` or `"mainnet"` before it reaches `config`. Do not map an unknown value to one of the
72
+ two: a production build with a misspelled value would then run on the wrong Network.
73
+
74
+ ```ts
75
+ import type { FluentWidgetConfig } from "@fluent.xyz/connect";
76
+
77
+ // config.testnet.ts; the mainnet deployment's module passes network: "mainnet".
78
+ export const config: FluentWidgetConfig = {
79
+ appId: "app_0123456789abcdef0123456789abcdef",
80
+ privyClientId: "client-0123456789abcdef",
81
+ network: "testnet",
82
+ };
83
+ ```
84
+
85
+ Keep `config` stable: a module constant, as here, or a memo. The widget resolves `config` again
86
+ on every render that passes a new object, and such a render can throw too.
87
+
88
+ ## Mount the widget
89
+
90
+ `<FluentWidget>` renders the connect button, the connect dialog and the account drawer, and
91
+ hands your App's content the widget's render context. `mode` picks which of your two render
92
+ functions it calls:
93
+
94
+ - `mode="home"`, the default, calls `renderHome`.
95
+ - `mode="page"` calls `renderPage`.
96
+
97
+ Each receives the render context, a `FluentWidgetRenderContext`. Any component rendered inside
98
+ that content can read the same object with `useFluentWidget()`, so you do not have to pass it
99
+ down. `useFluentWidget()` throws an `Error` when it is called outside the content of
100
+ `<FluentWidget>`, the button `renderConnectButton` returns included: that button receives its
101
+ own context, described below.
102
+
103
+ ```tsx
104
+ import "@fluent.xyz/connect/styles.css";
105
+ import { FluentWidget, useFluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
106
+
107
+ const config: FluentWidgetConfig = {
108
+ appId: "app_0123456789abcdef0123456789abcdef",
109
+ privyClientId: "client-0123456789abcdef",
110
+ network: "testnet",
111
+ };
112
+
113
+ function Dashboard() {
114
+ const { status, widget } = useFluentWidget();
115
+ if (status !== "connected") return <p>Connect to continue.</p>;
116
+ return <p>Your account: {widget.account.address}</p>;
117
+ }
118
+
119
+ export function Root() {
120
+ return <FluentWidget config={config} mode="page" renderPage={() => <Dashboard />} />;
121
+ }
122
+ ```
123
+
124
+ ## The connect button
125
+
126
+ `connectButton` decides where the widget's own button goes:
127
+
128
+ - `"fixed"`, the default: a floating button at the top right of the page.
129
+ - `"inline"`: the same button without fixed positioning, for your own layout to place.
130
+ - `false`: no button; open the widget's screens yourself.
131
+
132
+ The button opens the connect dialog while no Widget account is connected, and toggles the
133
+ account drawer once one is.
134
+
135
+ To draw your own button in that place, pass `renderConnectButton`. It receives a
136
+ `FluentWidgetConnectButtonRenderContext`: `connected`, `pending` (true while a Fluent ID's
137
+ account is being prepared), `addressLabel` (once connected, the shortened
138
+ address, or `"Connected"`), `userAvatarUrl`, `userXDisplayName` and `userGoogleName` (the same
139
+ values as the render context's, see [Account name](#account-name)), `onClick` (what the default
140
+ button does on click),
141
+ `openConnect`, `openAccount`, and `DefaultButton`, which renders the widget's own button. When
142
+ `renderConnectButton` returns `null` or `undefined`, the widget falls back to the button
143
+ `connectButton` names.
144
+
145
+ ```tsx
146
+ import { FluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
147
+
148
+ const config: FluentWidgetConfig = {
149
+ appId: "app_0123456789abcdef0123456789abcdef",
150
+ privyClientId: "client-0123456789abcdef",
151
+ network: "testnet",
152
+ };
153
+
154
+ export function Root() {
155
+ return (
156
+ <FluentWidget
157
+ config={config}
158
+ renderConnectButton={({ connected, onClick, DefaultButton }) =>
159
+ connected ? (
160
+ <DefaultButton />
161
+ ) : (
162
+ <button type="button" onClick={onClick}>
163
+ Connect
164
+ </button>
165
+ )
166
+ }
167
+ renderHome={() => <main>Your App</main>}
168
+ />
169
+ );
170
+ }
171
+ ```
172
+
173
+ With `connectButton={false}`, open the screens from your own content with the render context's
174
+ `openConnect` (the connect dialog) and `openAccount` (the account drawer). `openConnect` ignores
175
+ a click event passed to it, so it can be handed straight to `onClick`. The example after the
176
+ next section shows both.
177
+
178
+ ## Reading the account
179
+
180
+ The render context, and `useFluentWidget()`, tell your App who is connected:
181
+
182
+ - **`status`**, a `FluentWidgetStatus`: `"restoring"` (a session from a previous visit may
183
+ exist and nothing is decided yet), `"connecting"` (a Fluent ID's login is done and its account
184
+ is being prepared, after a Direct login or on a restore), `"connected"` (a Widget account is
185
+ connected) or `"disconnected"`. Branch on `status`, not on `hasConnectedAccount` alone:
186
+ `hasConnectedAccount` is `false` both while a stored session is being restored and when
187
+ nobody is connected, and treating the two alike shows a Connect button to a person who is
188
+ already connected.
189
+ - **`hasConnectedAccount`**: whether a Widget account, a Fluent ID or an External wallet, is
190
+ connected now.
191
+ - **`widget.account`**, a `FluentWidgetAccount`: `address` (the Fluent ID's address, or the
192
+ External wallet's; `undefined` while there is none), `type` (`"smart"` for a Fluent ID whose
193
+ account is ready, `"eoa"` for a connected External wallet, `undefined` otherwise),
194
+ `executionReady` (whether the account can send now), `executionStatus` (`"ready"`, or why it
195
+ cannot send: `"disconnected"`, which is also what a Fluent ID still being prepared, or whose
196
+ account failed, reads; `"unavailable"` or `"error"` only for a connected External wallet whose
197
+ client is not ready), and `capabilities` (`atomicBatch` and `erc20Gas`, both `true` only for a
198
+ Fluent ID). While no External wallet is connected, `address` falls back to the address of the
199
+ stored Widget session, so it can be set while `status` is not `"connected"`: branch on
200
+ `status` before you use it.
201
+ - **`session`**, a `FluentWidgetSession` or `null`: the Widget session, which holds the Fluent ID's
202
+ `account` (`address` and `type`) and `issuedAt`. It is `null` until a Fluent ID connects, and
203
+ an External wallet never sets it: read an External wallet from `widget.account`. A session
204
+ stored on a previous visit is in `session` from the first render, without any callback, and
205
+ stays there until a disconnect through the widget or a new Direct login replaces it, even while
206
+ `status` is `"disconnected"` or only an External wallet is connected. The session is not a
207
+ credential; to prove who the person is to your backend, use an Auth token
208
+ ([guides/backend-auth.md](guides/backend-auth.md)).
209
+
210
+ ```tsx
211
+ import { useFluentWidget } from "@fluent.xyz/connect";
212
+
213
+ export function AccountBar() {
214
+ const { status, widget, openConnect, openAccount } = useFluentWidget();
215
+ switch (status) {
216
+ case "connected":
217
+ return (
218
+ <button type="button" onClick={openAccount}>
219
+ {widget.account.address ?? "Connected"}
220
+ </button>
221
+ );
222
+ case "disconnected":
223
+ return (
224
+ <button type="button" onClick={openConnect}>
225
+ Connect
226
+ </button>
227
+ );
228
+ default:
229
+ // "restoring", "connecting", and any status a later release adds.
230
+ return <span>Loading…</span>;
231
+ }
232
+ }
233
+ ```
234
+
235
+ Keep a `default` branch in any `switch` over `status` or another code or status union: a later
236
+ release may add a value.
237
+
238
+ A Fluent ID can sign without the widget's Review, under Quick sign: see
239
+ [concepts.md](concepts.md#prompt-mode-and-silent-mode).
240
+
241
+ `onSessionChange` is called each time the widget writes its Widget session: with the new
242
+ `FluentWidgetSession` when a Fluent ID connects by Direct login, and with `null` on a disconnect
243
+ through the widget. It is not called for a session restored from storage when the widget mounts,
244
+ nor when an External wallet connects; read `session` and `widget.account` from the render
245
+ context for those. One exception: when a restored login has no matching stored session, the
246
+ widget writes a new one after it mounts and calls `onSessionChange` with it.
247
+
248
+ ```tsx
249
+ import {
250
+ FluentWidget,
251
+ type FluentWidgetConfig,
252
+ type FluentWidgetSession,
253
+ } from "@fluent.xyz/connect";
254
+
255
+ const config: FluentWidgetConfig = {
256
+ appId: "app_0123456789abcdef0123456789abcdef",
257
+ privyClientId: "client-0123456789abcdef",
258
+ network: "testnet",
259
+ };
260
+
261
+ function handleSessionChange(session: FluentWidgetSession | null) {
262
+ console.info(session ? `Connected: ${session.account.address}` : "Disconnected");
263
+ }
264
+
265
+ export function Root() {
266
+ return (
267
+ <FluentWidget
268
+ config={config}
269
+ onSessionChange={handleSessionChange}
270
+ renderHome={({ status }) => <p>Status: {status}</p>}
271
+ />
272
+ );
273
+ }
274
+ ```
275
+
276
+ ### Account name
277
+
278
+ The render context, `useFluentWidget()` and the context `renderConnectButton` receives carry the
279
+ names the person is known by: `userXDisplayName`, the display name of their linked X account (the
280
+ name X shows above the handle, not the handle), and `userGoogleName`, the name on the Google
281
+ account linked to their Direct login. Each is `undefined` when no such account is linked or it
282
+ reports no name, and while an External wallet is connected without a Fluent ID.
283
+ `avatar.forceDefault` hides the Account avatar's picture only and leaves both names in place.
284
+ Neither is a fallback for the other: a person with Google linked and no X account has no X
285
+ display name, so pick your own order.
286
+
287
+ ```tsx
288
+ import { useFluentWidget } from "@fluent.xyz/connect";
289
+
290
+ export function Greeting() {
291
+ const { userXDisplayName, userGoogleName } = useFluentWidget();
292
+ const name = userXDisplayName ?? userGoogleName;
293
+ return <span>{name ? `Hi, ${name}` : "Hi"}</span>;
294
+ }
295
+ ```
296
+
297
+ ## Debugging
298
+
299
+ `debugLogging` prints the widget's connect, account and signing diagnostics to the browser
300
+ console, and in `mode="home"` also shows the widget's debug panel. It is off by default; turn it
301
+ on only while debugging an integration.
302
+
303
+ ```tsx
304
+ import { FluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
305
+
306
+ const config: FluentWidgetConfig = {
307
+ appId: "app_0123456789abcdef0123456789abcdef",
308
+ privyClientId: "client-0123456789abcdef",
309
+ network: "testnet",
310
+ };
311
+
312
+ export function Root() {
313
+ return <FluentWidget config={config} debugLogging renderHome={() => <main>Your App</main>} />;
314
+ }
315
+ ```
316
+
317
+ When the widget refuses its `config`, the error's message names the option and how to fix it,
318
+ and its `code` is listed in [errors.md](errors.md#fluentwidgetconfigerror).
319
+
320
+ ## Checklist
321
+
322
+ - `appId` and `privyClientId` from Fluent, and every page origin allow-listed for Direct login.
323
+ - For `getAuthToken()`, Sponsorship, `linkX()` and User settings: Auth tokens enabled for the
324
+ App and each calling origin registered.
325
+ - For Sponsorship: the App enabled for Sponsorship.
326
+ - `@fluent.xyz/connect` and all five peers installed.
327
+ - `@fluent.xyz/connect/styles.css` imported once.
328
+ - `network` passed as a literal per deployment, never defaulted.
329
+ - `config` kept stable: a module constant or a memo.
330
+ - `useFluentWidget()` called only inside the content `renderPage` or `renderHome` returns.
331
+ - UI branched on `status`, with a `default` branch.
332
+ - `debugLogging` off in production.
333
+
334
+ Next: send a Batch operation ([guides/transactions.md](guides/transactions.md)), request a
335
+ signature ([guides/signing.md](guides/signing.md)), or verify the person on your backend
336
+ ([guides/backend-auth.md](guides/backend-auth.md)).