@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,126 @@
1
+ # Concepts
2
+
3
+ The widget gives your App one Widget account, and that account is one of two kinds. Most of what
4
+ the widget does depends on which kind is connected, so this page sets the two side by side. The
5
+ words in bold are the glossary's; the API reference ([api.md](api.md)) uses the same ones.
6
+
7
+ ## The two account kinds
8
+
9
+ **Fluent ID.** A person's account on Fluent, created at Direct login, which happens inside your
10
+ App's own page. It is the primary identity the widget gives a person, and the address the
11
+ widget's actions target.
12
+
13
+ **External wallet.** A third-party wallet the person connects themselves. It signs for itself and
14
+ holds its own balances, independently of any Fluent ID.
15
+
16
+ Read the kind from `widget.account.type` (`useFluentWidget().widget`, or `widget` in the render
17
+ context): `"smart"` for a Fluent ID once its account is ready, `"eoa"` for a connected External
18
+ wallet (even before its client is ready to sign), and absent otherwise. `FluentAccountType` may gain
19
+ values in a later release, so keep a `default` branch in any `switch` over it. To adapt your UI
20
+ without branching on the kind, read `widget.account.capabilities`
21
+ ([api.md](api.md#fluentaccountcapabilities)).
22
+
23
+ ## What differs by account kind
24
+
25
+ | Behaviour | Fluent ID | External wallet |
26
+ |---|---|---|
27
+ | Widget session (`session` in the render context) | Built at Direct login, and restored from storage on a later page load with its original `issuedAt`. `session.account.type` is `"smart"`. A session from an earlier visit stays in `session` until a disconnect through the widget or a new Direct login replaces it, even while `status` is `"disconnected"`: branch on `status`. | Not built for an External wallet: `session` is `null`, unless a Fluent ID's session from an earlier visit is still stored. Read the account from `widget.account`. |
28
+ | How a Batch operation lands | Atomically, in one transaction: `atomic` is `true` on the result. | One transaction per call, in order: `atomic` is `false`, and `hashes` holds one hash per call. When a call reverts, `execute()` rejects, sends none of the calls after it, and the calls before it stay included. |
29
+ | Review before a Batch operation | Shown in Prompt mode, skipped in Silent mode: see [Prompt mode and Silent mode](#prompt-mode-and-silent-mode). | No widget Review: the wallet shows its own prompt, and `confirmation` is ignored. A refusal there rejects with the wallet's own error. |
30
+ | Review before a signature (`signMessage`, `signTypedData`) | Shown in Prompt mode, skipped in Silent mode. | Always shown, then the wallet's own prompt. |
31
+ | Quick sign and Silent mode | Apply. | Do not apply. |
32
+ | Gas payment | Native ETH, or a Gas token (`gasPayment` on `execute()`, or the person's choice in the widget). | Always the wallet's own native ETH; `gasPayment` is ignored. |
33
+ | Sponsorship | Asked for on an operation paid in native ETH, unless `sponsorship` is `"never"`. When it is refused, the account pays its own gas. Once the service refuses the App outright, the widget stops asking until it is mounted again. | Never sponsored. |
34
+ | `sponsored` on `FluentExecuteResult` | `false` for a Gas token payment; `true` when the receipt names a sponsoring paymaster; `false` when the receipt names no paymaster and the operation made no sponsored submission, which is an operation the account paid for itself in ETH; `null` when the receipt names no paymaster after a sponsored submission. | Always `false`. |
35
+ | `paymaster` on `FluentExecuteResult` | The paymaster the receipt names, when it names one. Experimental: see [experimental.md](experimental.md#paymaster-and-timing). | Always absent. |
36
+ | `getAuthToken()` | Uses the Direct login: no signature is asked for. | Signs a Sign-in challenge when a Service session opens (a second time when the service refuses the first challenge and the call retries); renewals the service accepts ask the wallet for nothing. See [guides/backend-auth.md](guides/backend-auth.md#renewal). |
37
+
38
+ Every Sponsorship outcome, `FluentSponsorshipFallbackError`, and how to tell why an operation was
39
+ not sponsored are in [guides/sponsorship.md](guides/sponsorship.md).
40
+
41
+ The Auth token itself, and how a backend verifies it, are in
42
+ [guides/backend-auth.md](guides/backend-auth.md). Batch operations and their results are in
43
+ [guides/transactions.md](guides/transactions.md), signatures in
44
+ [guides/signing.md](guides/signing.md).
45
+
46
+ ## Prompt mode and Silent mode
47
+
48
+ These two modes decide whether the widget shows its Review before a Fluent ID signs a Batch
49
+ operation or a signature (`signMessage`, `signTypedData`). They apply to a Fluent ID only: an
50
+ External wallet's Batch operation never shows the widget's Review and goes through the wallet's
51
+ own prompt, and its signatures always show the Review, then the wallet's own prompt.
52
+
53
+ - **Prompt mode** (`"prompt"`): the widget shows its Review and signs once the person confirms
54
+ it. If the person dismisses it, `execute()` rejects with `FluentReviewRejectedError`, `code`
55
+ `"transaction_review_rejected"`, and a signature with `code` `"signature_review_rejected"`
56
+ ([errors.md](errors.md#fluentreviewrejectederror)).
57
+ - **Silent mode** (`"silent"`): the widget shows no Review and signs directly.
58
+
59
+ **Quick sign** is the person's choice of Silent mode: the "Quick sign" switch in the Settings of
60
+ the widget's account drawer; no option of the App sets it. It is kept in the person's User
61
+ settings, which the widget reads and saves with an Auth token. After every page load and every
62
+ connect, Quick sign is on until the widget has read the person's User settings, so until then a
63
+ Fluent ID signs in Silent mode, subject to the steps below. Without an Auth token the read and the
64
+ save fail: a person's choice to turn Quick sign off is not loaded, and lasts only until the next
65
+ page load or connect.
66
+
67
+ `widget.signingMode` is the current mode: `"silent"` while Quick sign is on, `"prompt"`
68
+ otherwise. Signatures follow it and take no option. Which mode a Batch operation gets is decided
69
+ once per `execute()` call:
70
+
71
+ 1. The `confirmation` option of `execute()`, when you pass it. Only the exact value `"silent"`
72
+ gives Silent mode; any other value gives Prompt mode, including `null` and the 0.5 values
73
+ `"always"` and `"session"`.
74
+ 2. When you leave `confirmation` out, `widget.signingMode`.
75
+ 3. Then the App's `quickSign.whitelistAddresses`, when it is set: an operation in Silent mode with
76
+ any call whose `to` is not on the list is switched to Prompt mode, so it shows the Review. This
77
+ applies to an explicit `confirmation: "silent"` as well as to Quick sign, so a per-call option
78
+ cannot lift the App's list. An empty list switches every operation to Prompt mode; leaving the
79
+ option out lets Silent mode cover every address. Addresses are compared case-insensitively.
80
+ The list does not apply to `signMessage` and `signTypedData`, which have no call target.
81
+
82
+ The option itself is in [configuration.md](configuration.md).
83
+
84
+ ## What the Swap page can do on mainnet
85
+
86
+ The drawer's Swap page deposits from Ethereum into the user's Fluent smart
87
+ account. On **mainnet** its Receive side also offers the other tokens Fluent
88
+ ships — so a user can deposit ETH and end up holding USDnr. That is a **two-step
89
+ deposit**: the bridge runs first and credits the smart account, then the smart
90
+ account swaps what landed, on Fluent, through FluxFlow. The user signs the bridge
91
+ alone; once the deposit lands, the swap is priced and sent without a second
92
+ press, from whichever drawer page the user is on.
93
+
94
+ Five consequences reach your integration:
95
+
96
+ - **The swap is an operation from the smart account**, like a Send: it uses the
97
+ user's gas token from Settings, it can be sponsored by your paymaster, and it
98
+ shows the Fluent transaction review. Its calls go to the FluxFlow router
99
+ (`0x23a8…3701`) and, for an ERC-20 input, to that token for an `approve` of
100
+ exactly the amount being swapped. If you set
101
+ `quickSign.whitelistAddresses` ([configuration.md](configuration.md)),
102
+ those targets have to be on the list for Quick
103
+ sign to cover it; otherwise the user sees the Review, which is the documented
104
+ behaviour of that option and not a bug. Because the swap starts on its own, a
105
+ user without Quick sign sees that Review open by itself when the deposit lands;
106
+ dismissing it, or a swap that fails, leaves a button on the Swap page to try
107
+ again, and the widget does not reopen it on its own.
108
+ - **It needs a Fluent ID.** A user whose widget account is an external wallet
109
+ sees the Receive side as it has always been — whatever the bridge delivers —
110
+ because the deposit is credited to the smart account and only that account can
111
+ swap it.
112
+ - **It keeps its place in `localStorage`.** From the moment the bridge is signed,
113
+ the deposit's progress is stored under
114
+ `fluent-connect:two-step-deposit:v1:<network>:<smart account>` in your page's
115
+ origin, so another drawer page or a reload comes back to the same step. The
116
+ entry is removed once the deposit is over. Where the browser refuses storage
117
+ the deposit is still followed, but only while the page stays open.
118
+ - **The swap sells what landed, never more than the deposit was to deliver.** A
119
+ smaller arrival is swapped as it is; a larger rise in the balance is other
120
+ money and is left alone. A swap whose confirmation never came back is not
121
+ offered again, because it may still land.
122
+ - **Testnet is unchanged.** FluxFlow runs on Fluent mainnet only, so on testnet
123
+ the Swap page offers the bridge alone.
124
+
125
+ Nothing here is configurable and no prop changed: a two-step deposit is the
126
+ user's choice on that page, made per deposit.
@@ -0,0 +1,276 @@
1
+ # Configuration
2
+
3
+ `<FluentWidget>` takes one `config`, a `FluentWidgetConfig`, and a handful of props. This page
4
+ says what each option and prop is for, what it defaults to, and what a bad value throws. The exact
5
+ types are in the API reference: [`FluentWidgetConfig`](api.md#fluentwidgetconfig) and
6
+ [`FluentWidgetProps`](api.md#fluentwidgetprops).
7
+
8
+ ## When the config is checked
9
+
10
+ The widget resolves `config` while `<FluentWidget>` renders, so a value it cannot use throws a
11
+ `FluentWidgetConfigError` from that render, where the nearest error boundary catches it. Its
12
+ message names the option to fix, and its `code` says what is wrong:
13
+
14
+ - `missing_option`: a required option is absent (for `appId` and `privyClientId`, also empty).
15
+ - `invalid_option`: an option holds a value the widget cannot use.
16
+ - `removed_option`: an option an earlier release removed is still passed.
17
+
18
+ The full table of codes is in [errors.md](errors.md#fluentwidgetconfigerror). The config is
19
+ resolved again on every render that passes a new `config` object, so such a render can throw too:
20
+ keep `config` stable, as a module constant or a memo.
21
+
22
+ ## A complete config
23
+
24
+ ```ts
25
+ import type { FluentWidgetConfig } from "@fluent.xyz/connect";
26
+
27
+ export const config: FluentWidgetConfig = {
28
+ // Who the App is, and where it runs.
29
+ appId: "app_0123456789abcdef0123456789abcdef",
30
+ privyClientId: "client-0123456789abcdef",
31
+ network: "testnet",
32
+ appName: "Marketplace",
33
+ // X is always offered; these stand beside it, in this order.
34
+ enabledAuthMethods: ["email", "passkey"],
35
+ gasPayment: { defaultToken: "ETH", sponsorship: "auto" },
36
+ quickSign: { whitelistAddresses: ["0x1111111111111111111111111111111111111111"] },
37
+ avatar: { defaultLogoUrl: "https://marketplace.example/logo.png" },
38
+ reputationEnabled: true,
39
+ source: "marketplace",
40
+ campaign: "launch",
41
+ };
42
+ ```
43
+
44
+ Only `appId`, `privyClientId` and `network` are required; every other option may be left out.
45
+
46
+ ## `FluentWidgetConfig`
47
+
48
+ ### Identity of the App
49
+
50
+ **`appId`** (required). The App's id, `app_` followed by 32 lowercase hex digits: the id the
51
+ Fluent Dashboard shows for the App, and the `aud` of every Auth token the widget mints for it.
52
+ Sponsorship, Auth tokens and analytics are all decided for this id.
53
+
54
+ - `missing_option` when it is absent or empty after trimming.
55
+ - `invalid_option` when it is not a string, when it holds a `client-…` value (the login client,
56
+ which belongs in `privyClientId`), or when it has any other shape.
57
+
58
+ **`privyClientId`** (required). The login client Fluent issues for the App, a `client-…` value.
59
+ The option is required, and it is also experimental: see
60
+ [experimental.md](experimental.md#privyclientid). Direct login works only on an origin Fluent has
61
+ allow-listed for the App beforehand, so ask Fluent to register each origin your App runs on.
62
+
63
+ - `missing_option` when it is absent or empty after trimming.
64
+ - `invalid_option` when it is not a string, when it holds an `app_…` id (the two were swapped),
65
+ or when it does not start with `client-`.
66
+
67
+ **`appName`**. The App's name, as the widget shows it: in the connect dialog's description and
68
+ on the Review of a Batch operation. Set it. Unset, the connect dialog says "this app" and the
69
+ Review shows the placeholder name `Fluent Connect Demo`.
70
+
71
+ ### Network
72
+
73
+ **`network`** (required). The Network the widget runs on: `"testnet"` or `"mainnet"`. It picks
74
+ the chain, its tokens and the service. There is no default, and the widget reads no environment
75
+ variable for it: if your App picks the Network from its own build settings, read them yourself and
76
+ pass the value.
77
+
78
+ - `missing_option` when it is absent (`undefined` or `null`).
79
+ - `invalid_option` for any other value than `"testnet"` and `"mainnet"`.
80
+
81
+ The two chains are exported as [`fluentTestnet`](api.md#fluenttestnet) and
82
+ [`fluentMainnet`](api.md#fluentmainnet).
83
+
84
+ ### Auth methods
85
+
86
+ **`enabledAuthMethods`**. The Auth methods the connect dialog offers beside X, in the order
87
+ given: any of `"google"`, `"email"` and `"passkey"`. X is always offered and is not a value here.
88
+ The default is `["google", "email", "passkey"]`; a shorter list drops the rest, and `[]` leaves X
89
+ alone. Unknown values and duplicates are dropped. An Auth method also has to be enabled for the
90
+ App by Fluent: listing it here only decides whether its button is drawn.
91
+
92
+ - `invalid_option` when it is not a list or another iterable. `null` counts as unset and gives
93
+ the default; a non-empty string is read character by character, so every value is dropped and
94
+ only X is offered.
95
+
96
+ ### Gas payment
97
+
98
+ These options apply to a Fluent ID. An External wallet always pays its own gas in native ETH
99
+ ([concepts.md](concepts.md)).
100
+
101
+ **`gasPayment.defaultToken`**. The Gas token the widget charges until the person chooses one:
102
+ `"ETH"` for native ETH (the default), or the symbol of a Gas token of the Network, compared
103
+ case-insensitively. A valid Gas token the person has saved in their User settings wins over it.
104
+
105
+ - `invalid_option` when it is not a string, or names no Gas token of the Network.
106
+
107
+ **`gasPayment.sponsorship`**. Whether the widget asks for Sponsorship on an operation paid in
108
+ native ETH. `"auto"` (the default) asks, and when the Sponsorship is refused the account pays its
109
+ own gas instead. `"never"` does not ask, so the account pays from the start. One operation can
110
+ override it with `gasPayment` on `execute()` ([guides/transactions.md](guides/transactions.md)).
111
+ An operation paid in a Gas token is never sponsored, whatever this option says.
112
+
113
+ **`gasPayment.ethValueByToken`** is experimental: see
114
+ [experimental.md](experimental.md#gaspaymentethvaluebytoken).
115
+
116
+ ### Quick sign
117
+
118
+ **`quickSign.whitelistAddresses`**. The call targets Quick sign may cover. Set, a Fluent ID's
119
+ Batch operation runs in Silent mode only when every call's `to` is on the list; an operation with
120
+ a call to any other address is switched to Prompt mode and shows the Review, even with Quick sign
121
+ on and even with `confirmation: "silent"`. An empty list switches every Batch operation to Prompt
122
+ mode. Unset (the default), Silent mode covers every address. Entries are trimmed and compared
123
+ case-insensitively. Signatures (`signMessage`, `signTypedData`) have no call target, so the list
124
+ does not scope them. How the modes are chosen:
125
+ [concepts.md](concepts.md#prompt-mode-and-silent-mode).
126
+
127
+ - `invalid_option` when it is not a list, or when an entry is not an address.
128
+
129
+ ### Account avatar and images
130
+
131
+ **`avatar.defaultLogoUrl`**. The image the Account avatar falls back to when the person has no
132
+ linked X picture, a URL or a data URI. Unset, the avatar is the Fluent mark. An empty string
133
+ counts as unset.
134
+
135
+ - `invalid_option` when it is not a string.
136
+
137
+ **`avatar.forceDefault`**. `true` shows `defaultLogoUrl` even for a person with a linked X
138
+ picture. Default `false`. It does not hide the render context's `userXDisplayName` and
139
+ `userGoogleName` ([Account name](getting-started.md#account-name)).
140
+
141
+ **`assets`**. Images for the widget, each a URL or a data URI
142
+ ([`FluentWidgetAssets`](api.md#fluentwidgetassets)). Today the widget reads only `fluentLogo`,
143
+ which it passes to the provider behind Direct login as its logo; the connect button, the account
144
+ drawer and the External wallet choices of the connect dialog keep their own images.
145
+
146
+ ### Account drawer
147
+
148
+ **`reputationEnabled`**. `false` drops the Reputation tab from the account drawer, and with it the
149
+ tab strip, since Home is then the only tab; the widget then makes no reputation request. Default
150
+ `true`.
151
+
152
+ **`swapper`** is experimental: see [experimental.md](experimental.md#swapper).
153
+
154
+ ### Auth tokens
155
+
156
+ **`authTokenRenewalOffsetSeconds`**. `getAuthToken()` reuses an Auth token until this many seconds
157
+ before its `exp`, then fetches a fresh one. Default `30`. `0` reuses a token until `exp` itself;
158
+ it does not mean fetching a new token on every call. How the token is used:
159
+ [guides/backend-auth.md](guides/backend-auth.md).
160
+
161
+ ### External wallets
162
+
163
+ **`reconnectOnMount`**. Which External wallets from an earlier visit the widget reconnects when
164
+ it mounts. Unset (the default), it reconnects only browser-extension wallets and WalletConnect;
165
+ `true` reconnects every kind of External wallet; `false` reconnects none. A Fluent ID's Widget
166
+ session is restored either way.
167
+
168
+ ### Analytics
169
+
170
+ **`disableAnalytics`**. `true` turns off the widget's analytics: it sends no event and stores
171
+ nothing for them. Default `false`.
172
+
173
+ **`source`** and **`campaign`**. Attribution tags the widget adds to every analytics event it
174
+ sends. `source` defaults to `"fluent_connect_widget"`; `campaign` has no default.
175
+
176
+ ### Experimental options
177
+
178
+ These options may change or be removed in a minor release. Each is named here only so you can
179
+ find it; what it does is in [experimental.md](experimental.md):
180
+
181
+ - `customOAuthRedirectUrl`: [experimental.md](experimental.md#customoauthredirecturl)
182
+ - `swapper`: [experimental.md](experimental.md#swapper)
183
+ - `gasPayment.ethValueByToken`: [experimental.md](experimental.md#gaspaymentethvaluebytoken)
184
+ - `execution`: [experimental.md](experimental.md#execution)
185
+ - `sponsorshipUrl`: [experimental.md](experimental.md#sponsorshipurl)
186
+ - `privyClientId`, which is required: [experimental.md](experimental.md#privyclientid)
187
+
188
+ ### Removed options
189
+
190
+ The type still lists `clientId` and `partnerId` as `never`, so that a config carrying one fails
191
+ the typecheck; past the type, `<FluentWidget>` throws `removed_option` for either. An `authMode`
192
+ key throws `removed_option` too, unless its value is `"direct"`, which only logs a warning. What
193
+ each was and what replaces it: [upgrading-0.5.md](upgrading-0.5.md).
194
+
195
+ ## Capacitor and other web views
196
+
197
+ Direct login happens inside your App's own page, so the origin a Capacitor web view serves the
198
+ App from has to be allow-listed by Fluent, like any other origin; ask Fluent for it with your
199
+ `appId`.
200
+
201
+ X is always offered, and a Direct login with X or Google goes through an OAuth round trip.
202
+ Leaving Google out of `enabledAuthMethods` removes one of the two; X cannot be removed. The option
203
+ that passes a return URL for that round trip to the provider is `customOAuthRedirectUrl`, which is
204
+ experimental: see [experimental.md](experimental.md#customoauthredirecturl).
205
+
206
+ ## `FluentWidgetProps`
207
+
208
+ The exact member list and types are in [api.md](api.md#fluentwidgetprops).
209
+
210
+ **`config`** (required). The `FluentWidgetConfig` above.
211
+
212
+ **`mode`**. Which of your two render props the widget renders: `"page"` renders `renderPage`, and
213
+ `"home"` (the default) renders `renderHome`. With `debugLogging` on, `"home"` also shows the
214
+ widget's debug panel.
215
+
216
+ **`renderHome`** and **`renderPage`**. Your App's content. Each receives the render context
217
+ ([`FluentWidgetRenderContext`](api.md#fluentwidgetrendercontext)): the Widget session, the Widget
218
+ API as `widget`, `status`, and the calls that open the widget's screens, disconnect, mint an Auth
219
+ token and link X. Any component rendered inside reads the same object from `useFluentWidget()`.
220
+
221
+ **`connectButton`**. Where the widget's own connect button goes: `"fixed"` (the default) floats it
222
+ at the top right of the page; `"inline"` renders it without fixed positioning, for your layout to
223
+ place; `false` hides it, and your App opens the connect dialog and the account drawer itself with
224
+ `openConnect` and `openAccount` from the render context.
225
+
226
+ **`renderConnectButton`**. Draws your own connect button in place of the widget's. It receives
227
+ [`FluentWidgetConnectButtonRenderContext`](api.md#fluentwidgetconnectbuttonrendercontext): whether
228
+ a Widget account is connected, whether a Fluent ID is still being prepared, the click handler, and
229
+ the widget's own button as `DefaultButton`. When it returns `null` or `undefined`, the
230
+ `connectButton` setting applies instead.
231
+
232
+ **`tokens`**. Integrator tokens the widget lists beside its Default tokens, each a
233
+ [`FluentTokenDefinition`](api.md#fluenttokendefinition). An Integrator token is listed only: it
234
+ never becomes a Gas token.
235
+
236
+ **`debugLogging`**. `true` prints the widget's diagnostics to the console, and shows the debug
237
+ panel in `mode="home"`. Off by default; turn it on only while debugging an integration.
238
+
239
+ **`onSessionChange`**. Called with the new Widget session when a Fluent ID connects by Direct
240
+ login, and with `null` on a disconnect through the widget. It is not called for a Widget session
241
+ restored from storage when the widget mounts, nor when an External wallet connects: read
242
+ `session` and `widget.account` from the render context for those. It is called on mount when a
243
+ restored login has no matching stored Widget session, because the widget then writes a new one.
244
+
245
+ **`wallet`** and **`privyAdapter`** are experimental: see
246
+ [experimental.md](experimental.md#wallet) and [experimental.md](experimental.md#privyadapter).
247
+
248
+ ```tsx
249
+ import { FluentWidget } from "@fluent.xyz/connect";
250
+ import type { FluentWidgetConfig, FluentWidgetSession } from "@fluent.xyz/connect";
251
+
252
+ const config: FluentWidgetConfig = {
253
+ appId: "app_0123456789abcdef0123456789abcdef",
254
+ privyClientId: "client-0123456789abcdef",
255
+ network: "testnet",
256
+ appName: "Marketplace",
257
+ };
258
+
259
+ function reportSession(session: FluentWidgetSession | null): void {
260
+ console.info(session ? `Connected as ${session.account.address}` : "Disconnected");
261
+ }
262
+
263
+ export function App() {
264
+ return (
265
+ <FluentWidget
266
+ config={config}
267
+ mode="page"
268
+ connectButton="inline"
269
+ onSessionChange={reportSession}
270
+ renderPage={({ status, widget }) => (
271
+ <main>{status === "connected" ? widget.account.address : "Connect to continue"}</main>
272
+ )}
273
+ />
274
+ );
275
+ }
276
+ ```
package/docs/errors.md ADDED
@@ -0,0 +1,213 @@
1
+ # Errors
2
+
3
+ Every error the widget hands an App on purpose is an instance of one of five classes, each with
4
+ a string `code`. This page lists every code of each class, the call that throws it today, what it
5
+ means and what to do. The [API reference](api.md#auth-and-errors) holds the declarations.
6
+
7
+ ## How to branch
8
+
9
+ Check the class with `instanceof`, then `switch` on `code`. Keep a `default` branch in every
10
+ `switch` over a code or status union: a later release may add a code, and a `switch` without a
11
+ `default` branch would then fall through in silence.
12
+
13
+ ```ts
14
+ import {
15
+ FluentAuthError,
16
+ FluentReviewRejectedError,
17
+ FluentSponsorshipFallbackError,
18
+ } from "@fluent.xyz/connect";
19
+
20
+ export function describeError(error: unknown): string {
21
+ if (error instanceof FluentReviewRejectedError) return "You dismissed the request.";
22
+ if (error instanceof FluentSponsorshipFallbackError) {
23
+ switch (error.code) {
24
+ case "unreachable":
25
+ return "The sponsorship service did not answer, and paying your own gas failed too.";
26
+ default:
27
+ return "The operation could not be sent.";
28
+ }
29
+ }
30
+ if (error instanceof FluentAuthError) {
31
+ switch (error.code) {
32
+ case "not_connected":
33
+ return "Connect first.";
34
+ case "rate_limited":
35
+ return "Too many requests; try again in a minute.";
36
+ default:
37
+ return `Sign-in failed (${error.code}).`;
38
+ }
39
+ }
40
+ return "Something went wrong.";
41
+ }
42
+ ```
43
+
44
+ An error a call does not list here (a wallet's own refusal, a reverted call, a network failure)
45
+ reaches the App as it was thrown: keep a fallback for it too. The exception is
46
+ [`FluentSponsorshipFallbackError`](#fluentsponsorshipfallbackerror), which wraps such errors.
47
+
48
+ The calls named in "Thrown by":
49
+
50
+ | Call | Where it is |
51
+ |---|---|
52
+ | `<FluentWidget>` | rendering the widget with its `config` |
53
+ | `execute()` | `widget.createBatchOp({ calls }).execute()` |
54
+ | `signMessage()`, `signTypedData()` | `widget.signMessage(…)`, `widget.signTypedData(…)` |
55
+ | `getAuthToken()`, `linkX()` | the render context, or `useFluentWidget()` |
56
+ | `useLinkX()` | its `linkX()`, which also keeps the error in `error` |
57
+
58
+ ## `FluentWidgetConfigError`
59
+
60
+ Thrown during the render of `<FluentWidget>` when its `config` cannot be used, so the nearest
61
+ error boundary catches it. The config is resolved again on every render that passes a new
62
+ `config` object: keep `config` stable (a module constant or a memo). The message names the
63
+ option to fix. See [configuration.md](configuration.md).
64
+
65
+ | `code` | Thrown by | What it means | What to do |
66
+ |---|---|---|---|
67
+ | `missing_option` | `<FluentWidget>` | A required option is absent: `config` itself `undefined` or `null`, `appId` or `privyClientId` absent or empty, or `network` `undefined` or `null` (an empty `network` is `invalid_option`). | Pass the option; `network` has no default. |
68
+ | `invalid_option` | `<FluentWidget>` | An option holds a value the widget cannot use: an `appId` or `privyClientId` of the wrong shape, a `network` other than `"testnet"` and `"mainnet"`, a `customOAuthRedirectUrl` that is not an absolute HTTPS URL, a `gasPayment.defaultToken` that names no Gas token of the Network, an `enabledAuthMethods` or `quickSign.whitelistAddresses` that is not a list, a `quickSign.whitelistAddresses` entry that is not an address, an `avatar.defaultLogoUrl` that is not a string. | Fix the value the message names. |
69
+ | `removed_option` | `<FluentWidget>` | An option an earlier release removed is still passed: `clientId`, `partnerId`, or an `authMode` other than `"direct"` (`"direct"` only logs a warning). | Remove the option. |
70
+ | `invalid_fee_source` | `<FluentWidget>` | The experimental `execution.feeSource` is neither `"chain"` nor `"bundler"`. | Fix it, or leave `execution` out. |
71
+ | `invalid_receipt_source` | `<FluentWidget>` | The experimental `execution.receiptSource` is neither `"chain"` nor `"bundler"`. | Fix it, or leave `execution` out. |
72
+ | `invalid_chain_check_before_sign` | `<FluentWidget>` | The experimental `execution.chainCheckBeforeSign` is not a boolean. | Fix it, or leave `execution` out. |
73
+
74
+ ## `FluentAuthError`
75
+
76
+ A refused Auth token, signature or X link. `code` is a `FluentAuthErrorCode`; `status` is the
77
+ service's HTTP status when the service refused. Where the service answers with a code of its
78
+ own, this package names it here. A service code this package does not name arrives as
79
+ `service_refused` from `getAuthToken()`, and as `link_failed` from `linkX()`. Not every rejection
80
+ of `getAuthToken()` is a `FluentAuthError`: a failure to read a Fluent ID's Direct-login
81
+ credential arrives as it was thrown.
82
+
83
+ | `code` | Thrown by | What it means | What to do |
84
+ |---|---|---|---|
85
+ | `not_connected` | `getAuthToken()`, `signMessage()`, `signTypedData()` | No Widget account is connected, or an External wallet is connected but its client is not ready yet (for `getAuthToken()`, only when the call has to sign the Sign-in challenge). | Wait for `widget.account.executionReady` to be `true`, then call again. |
86
+ | `root_signer_required` | `signMessage()`, `signTypedData()` | Neither of a Fluent ID's signing paths signs with its root Signer. A guard: no configuration of the widget reaches it today. | Report it to Fluent. |
87
+ | `login_credential_missing` | `getAuthToken()` | A Fluent ID's Direct login left no credential in the page. | Ask the person to connect again. |
88
+ | `origin_mismatch` | `getAuthToken()` | The Sign-in challenge names an origin other than the page's, so the External wallet was not asked to sign. | Report it to Fluent with the page's origin. |
89
+ | `request_failed` | `getAuthToken()` | The request did not reach the service, its answer carried no code or no token, or the External wallet refused to sign the Sign-in challenge. | Retry once the network is back; when the person refused to sign, retrying prompts the wallet again. |
90
+ | `service_refused` | `getAuthToken()` | The service refused with a code this package does not name; the message carries that code. | Log the message and report it. |
91
+ | `unknown_app` | `getAuthToken()` | The service does not know the App's `appId`. | Check `appId`. |
92
+ | `app_not_auth_enabled` | `getAuthToken()` | Auth tokens are not enabled for the App. | Ask Fluent to enable them. |
93
+ | `origin_not_allowed` | `getAuthToken()` | The page's origin is not registered on the App. | Ask Fluent to add the origin. |
94
+ | `origin_missing` | `getAuthToken()` | The request carried no origin. | Call from a page, not from a worker or a server. |
95
+ | `bad_request` | `getAuthToken()`, `linkX()`, `useLinkX()` | The service refused the request body. | Report it to Fluent: the request is this package's. |
96
+ | `challenge_unknown` | `getAuthToken()` | The service does not know the Sign-in challenge the External wallet signed. | Call again. |
97
+ | `challenge_used` | `getAuthToken()` | The Sign-in challenge was already used. The call retries once with a fresh one, which prompts the External wallet again, and rejects with whatever the retry fails with. | Call again. |
98
+ | `challenge_expired` | `getAuthToken()` | The Sign-in challenge expired before it was signed. Retried once, as above. | Call again. |
99
+ | `app_mismatch` | `getAuthToken()` | The credential or challenge belongs to another App. | Check `appId`. |
100
+ | `invalid_signature` | `getAuthToken()` | The External wallet's signature over the Sign-in challenge does not verify. | Call again; a smart-contract wallet must be deployed to sign the Sign-in challenge. |
101
+ | `signature_prefix_rejected` | `getAuthToken()` | The External wallet signed with a prefix the service refuses. Retried once, as above. | Call again. |
102
+ | `address_already_linked` | `getAuthToken()` | The External wallet is already bound to another person. | Tell the person to use the account it is bound to. |
103
+ | `invalid_login_credential` | `getAuthToken()` | The service did not accept a Fluent ID's Direct-login credential. | Ask the person to connect again. |
104
+ | `no_signer` | `getAuthToken()` | The service finds no Signer for the Fluent ID. | Ask the person to connect again; report it if it persists. |
105
+ | `invalid_refresh_token` | none | Not delivered: when the service refuses the stored refresh credential, `getAuthToken()` forgets it and opens a new Service session within the same call, which can prompt an External wallet. | Nothing. |
106
+ | `refresh_token_reused` | none | Not delivered, for the same reason as `invalid_refresh_token`. | Nothing. |
107
+ | `rate_limited` | `getAuthToken()` | Too many requests. | Retry later. |
108
+ | `internal` | `getAuthToken()` | The service failed. | Retry later. |
109
+ | `not_authenticated` | `linkX()`, `useLinkX()` | No Fluent ID or External wallet is connected, or the External wallet's client is not ready yet. | Connect first, or wait and call again. |
110
+ | `user_rejected` | `linkX()`, `useLinkX()` | The person said no at X, closed the flow, or declined a signature the link needed. | Nothing; offer the button again. |
111
+ | `linked_to_another_user` | `linkX()`, `useLinkX()` | That X account is already linked to another person. | Tell the person. |
112
+ | `link_failed` | `linkX()`, `useLinkX()` | Anything else under the link, including a refusal from the Auth token it mints (its message is kept) and a link record left in the tab for another account, which is discarded. | Call again. |
113
+
114
+ `getAuthToken()` throws the codes of its rows today, and `linkX()` throws its five. A code a later
115
+ release adds arrives in the `default` branch. Keep a fallback outside the `instanceof` check too:
116
+ not every rejection is a `FluentAuthError`.
117
+
118
+ ## `FluentReviewRejectedError`
119
+
120
+ The person dismissed a Review instead of confirming it. `review` is `"transaction"` or
121
+ `"signature"`, and `code` says the same as a `FluentReviewRejectedErrorCode`. When a Fluent ID
122
+ shows a Review is in [concepts.md](concepts.md#prompt-mode-and-silent-mode). A Review that a
123
+ newer one replaces, or that closes because the widget unmounts, rejects with a plain `Error`.
124
+
125
+ | `code` | Thrown by | What it means | What to do |
126
+ |---|---|---|---|
127
+ | `transaction_review_rejected` | `execute()` | The person dismissed the Review of a Batch operation. An External wallet shows its own prompt instead, and its refusal arrives as the wallet's error. | Nothing: the person said no. |
128
+ | `signature_review_rejected` | `signMessage()`, `signTypedData()` | The person dismissed the Review of a signature, which an External wallet always shows. | Nothing: the person said no. |
129
+
130
+ ## `FluentSponsorshipFallbackError`
131
+
132
+ A Fluent ID's sponsored submission failed, and the own-gas submission after it failed too
133
+ ([which failures become this error](guides/sponsorship.md#both-failed-fluentsponsorshipfallbackerror)).
134
+ `code` (equal to `sponsorshipReason`) says why the sponsored submission failed; `fallbackError`
135
+ is the own-gas submission's error, and `cause` the sponsored submission's.
136
+
137
+ `cause` and `fallbackError` are not the errors the submissions threw, and not `Error` instances.
138
+ Each is a plain object with these fields and no others:
139
+
140
+ - `name`, a `string`: the name of the error the submission threw, such as `HttpRequestError`;
141
+ `Error` when what it threw is not an `Error`.
142
+ - `message`, a `string`: the text of the innermost error along the thrown error's `cause`
143
+ chain that has any, usually the vendor's own sentence, such as `AA21 didn't pay prefund`. An
144
+ `AggregateError` with `errors` contributes the texts of its first four, joined by `; `. A viem
145
+ error's text is its `details`, or its short message when `details` is empty; when `details` is
146
+ a JSON object with a string `message`, that `message`.
147
+ - `status`, a `number`: the first integer `status` along the error's cause chain, such as the
148
+ sponsorship service's HTTP status. Absent when the chain has none.
149
+
150
+ The cause chain under the thrown error is not kept: its text is in `message` and its status in
151
+ `status`. When the thrown value cannot be read without an exception, for example a getter that
152
+ throws, the summary is `{ name: "Error", message: "[unreadable error]" }` and the App still
153
+ receives a `FluentSponsorshipFallbackError` with its `code`.
154
+
155
+ In `message`, here and in the error's own `message`, these forms are replaced by a placeholder:
156
+
157
+ | Form | Placeholder |
158
+ |---|---|
159
+ | A `{…}` or `[…]` span that balances, brackets inside double-quoted strings not counted (a request or response body). Each span is replaced on its own, so the text between two bodies is kept. | `[body]` |
160
+ | A URL with a scheme (`https://…`), up to the first character a URL cannot hold | `[url]` |
161
+ | `Bearer` followed by spaces, `%20` or `+` and a token, quoted or not | `[token]` |
162
+ | Three dot-separated base64url segments, the first at least 16 characters long and the second at least 2 (a JWT) | `[token]` |
163
+ | A `did:` id | `[id]` |
164
+ | An email address | `[email]` |
165
+ | A UUID | `[id]` |
166
+ | `0x` and 40 hex digits, or 64 | `[address]`, `[hash]` |
167
+ | `0x` and any other number of hex digits from 40 up (call data, a signature, revert data) | `[data 0x…]` with its first four bytes, the selector of a revert; for an `Error(string)` revert, `[data 0x08c379a0: <reason>]` with the decoded reason, redacted in the same way |
168
+
169
+ A Privy DID, an Auth token, an address, a user operation hash or an RPC key in one of these
170
+ forms does not reach a log of the whole error. Other forms are not looked for and are kept as
171
+ the vendor wrote them unless they happen to match a listed one, for example a URL without a
172
+ scheme, a URL-encoded `did:` id (`did%3Aprivy%3A…`), 40 hex digits without `0x`, a `Basic`
173
+ credential or an `x-api-key` header value.
174
+
175
+ | `code` | Thrown by | What it means | What to do |
176
+ |---|---|---|---|
177
+ | `denied` | `execute()` | Any failure of the sponsored submission the other codes do not name: the sponsorship service refused the operation, or the operation itself failed, for example a call that reverts. | Check the fallback's error in `fallbackError`: the account may lack the ETH to pay itself. |
178
+ | `unauthorized` | `execute()` | The sponsorship service refused the App (HTTP 403) or its Auth token (HTTP 401, also after one fresh token). | Ask Fluent whether Sponsorship is enabled for the App. |
179
+ | `unreachable` | `execute()` | The request to the sponsorship service failed with an HTTP status other than 401 and 403, or with none. | Retry later. |
180
+ | `no_token` | `execute()` | The service refused the Auth token, and minting a fresh one failed. | Retry; check that `getAuthToken()` works for this person. |
181
+ | `not_requested` | none | Never this error's code: it is the reason for an operation that did not ask for Sponsorship, which has no sponsored submission to fail. | Nothing. |
182
+
183
+ ### What the submissions threw
184
+
185
+ The errors that reach the widget before it builds `cause` and `fallbackError`, on each of the two
186
+ paths that end in this error, as measured against viem 2.52.0 and `@zerodev/sdk` 5.5.10. Each
187
+ chain runs from the error thrown to the innermost `cause`. "Identifiers" says what the raw error
188
+ carried in its fields or its `message`. Of each raw error only the name, the text chosen for
189
+ `message` (redacted as above) and the status reach the error the App receives.
190
+
191
+ | Path | Error | Raw error | Vendor | Identifiers |
192
+ |---|---|---|---|---|
193
+ | After a failed forced token refresh (`no_token`) | `cause` | `HttpRequestError` with `status` 401, the paymaster's refusal of the first Auth token. The refusal of the fresh token's exchange is not part of the error. | The sponsorship paymaster, through viem's HTTP transport | Yes: `url` is the paymaster URL with the App's `appId`; `body`, repeated in `message`, is the `zd_sponsorUserOperation` request with the user operation: the smart account's address as `sender`, its call data and its signature. `details` is the paymaster's error text, whatever it holds. The Auth token is not carried: viem keeps the response's headers, not the request's. |
194
+ | After a failed forced token refresh (`no_token`) | `fallbackError` | `UserOperationExecutionError`, then the bundler error viem maps the refusal to (for example `InsufficientPrefundError`), then `InvalidParamsRpcError`, then `RpcRequestError`, then the JSON-RPC error object `{ code, message }`. | The ZeroDev bundler, through viem's HTTP transport; viem wraps it | Yes: `UserOperationExecutionError`'s `message` lists the user operation (`sender`, call data, signature, paymaster fields); `RpcRequestError`'s `url` is the bundler URL with the ZeroDev project id, and its `message` repeats the URL and the `eth_sendUserOperation` request body. The bundler's text is in `details`. |
195
+ | After a failed sponsored submission (`denied`, `unauthorized`, `unreachable`) | `cause` | For `unauthorized` and `unreachable`: `HttpRequestError` with `status` 401 (the fresh Auth token refused too), 403 or another status, or without a status when the request did not reach the paymaster, with the same fields as above. For `denied`, when the paymaster refuses the operation: an `RpcError` such as `InvalidParamsRpcError`, then `RpcRequestError`, then `{ code, message }`. For `denied`, when the operation itself fails, such as a call that reverts during gas estimation, or when the bundler refuses the sponsored submission: a `UserOperationExecutionError` chain as for `fallbackError`. | The sponsorship paymaster, through viem's HTTP transport; the ZeroDev bundler for the estimation | Yes: the paymaster URL with the App's `appId`, and the request body with the smart account's address, call data and signature, in `url`, `body` and `message`; the paymaster's or bundler's text in `details`. |
196
+ | After a failed sponsored submission (`denied`, `unauthorized`, `unreachable`) | `fallbackError` | The same `UserOperationExecutionError` chain as on the first path. | The ZeroDev bundler, through viem's HTTP transport; viem wraps it | Yes, as on the first path. |
197
+ | Either path | `fallbackError` | When the Signer refuses to sign the own-gas submission, Privy's provider error, unwrapped: viem signs outside the part of the submission it wraps. Its `name` is `Error`, its `message` `The user rejected the request.`, with `type` `provider_error`, `code` 4001 and `details`, an entry of Privy's error table. The summary is `{ name: "Error", message: "The user rejected the request." }`. | Privy, the Signer | No: a fixed sentence, a code and a table entry. |
198
+
199
+ None of the raw errors measured carried a Privy DID or a user operation hash in a field of its own;
200
+ either can still reach one inside a vendor's text, which is why `message` is redacted. The
201
+ sponsored submission signs too, once the paymaster has answered, so a Signer's refusal there
202
+ reaches `cause` the same way, with the code `denied`; that case was read from viem's code, not
203
+ measured.
204
+
205
+ ## `FluentUserOperationGasError`
206
+
207
+ *Experimental*: may change or be removed in a minor release, with the `userOperationGas` option
208
+ it belongs to ([experimental.md](experimental.md#useroperationgas)).
209
+
210
+ | `code` | Thrown by | What it means | What to do |
211
+ |---|---|---|---|
212
+ | `invalid_policy` | `execute()` | A `skipEstimation` policy cannot be used: `skipEstimation` is not a boolean, is combined with `callGasBuffer`, comes with fixed gas limits that are missing or out of range, or, for a Gas token payment, gives only one of the two paymaster gas limits. A bad `callGasLimit` or `callGasBuffer` without `skipEstimation` throws a plain `Error` instead. | Fix the option, or leave it out to let the widget estimate. |
213
+ | `paymaster_gas_mismatch` | `execute()` | With estimation skipped, the paymaster's authorization of a Gas token payment does not match the fixed gas limits. | Leave `userOperationGas` out for Gas token payments. |