@fluent.xyz/connect 0.4.0 → 0.4.1

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/README.md CHANGED
@@ -69,11 +69,29 @@ App's identity — sponsorship, auth and analytics speak it — and must be the
69
69
  value the Fluent Dashboard shows; the widget throws on any other shape. `privyClientId` is
70
70
  login configuration: the Privy app client carrying your allowed origins.
71
71
 
72
+ For Capacitor social login, use `authMode: "direct"` and pass
73
+ `customOAuthRedirectUrl: "https://app.example.com/auth/ios/callback"` in `config`.
74
+ This forwards an HTTPS Universal Link callback to Privy; the host must configure
75
+ the dashboard allowlists, iOS Associated Domains, and callback handling.
76
+ See [Capacitor OAuth setup](https://github.com/fluentlabs-xyz/fluent-connect-sdk/blob/devel/packages/connect/INTEGRATION.md#capacitor-oauth).
77
+
72
78
  > Upgrading from 0.2.x? `partnerId` was renamed to `appId` in 0.3.0 and the id value changed
73
79
  > from `partner_…` to `app_…`; passing `partnerId` throws with the same hint. Migrating from
74
80
  > `clientId`? That option is gone: the value it held is now `privyClientId`.
75
81
 
76
- `authMode: "direct"` requires your origin registered on the Privy app client behind your `privyClientId`. Default `authMode: "hosted"` uses the Fluent authorize popup and works on any origin.
82
+ ### Auth mode
83
+
84
+ > **Hosted mode is deprecated.** `authMode: "hosted"` is no longer supported and will be
85
+ > removed in 0.5.0 — use `authMode: "direct"`. The config default is still `"hosted"`, so
86
+ > leaving `authMode` out opts your app into the deprecated mode: set it explicitly, as the
87
+ > example above does.
88
+
89
+ `authMode: "direct"` renders Fluent's own sign-in dialog inside your page and requires your
90
+ origin registered on the Privy app client behind your `privyClientId`. `authMode: "hosted"`
91
+ (deprecated) opens the Fluent authorize popup and needs no origin allow-listing; a Fluent ID
92
+ signed in that way has its Privy session on the authorize page rather than in yours, so
93
+ `signMessage`, `signTypedData` and `linkX()` reject there with `hosted_not_supported`, and so
94
+ does `getAuthToken()` for a Fluent ID.
77
95
 
78
96
  ### Authenticating your backend
79
97
 
@@ -81,11 +99,16 @@ login configuration: the Privy app client carrying your allowed origins.
81
99
  Fluent Connect. Send it to your backend once and issue your own session; verify it with the keys
82
100
  at `<iss>/.well-known/jwks.json` — `iss` is the API host root, not `/api/v1` — and check `iss`,
83
101
  `aud` (your `appId`) and `exp`. `sub` is stable per user per app. `addresses` is present only
84
- when your app has the `addresses` scope. Direct auth only. External wallets: an EOA or a deployed
85
- contract wallet signs in; a counterfactual smart account cannot (no ERC-6492).
86
- The token renews itself silently for both account types — an external wallet signs once, when
87
- the session opens, not once per token; the session and what holding it costs are in
88
- `INTEGRATION.md` §8. See `apps/auth-demo` for a browser-side verifier.
102
+ when your app has the `addresses` scope. A Fluent ID needs `authMode: "direct"`: in hosted mode
103
+ it rejects with `FluentAuthError` code `hosted_not_supported`. An external wallet gets a token in
104
+ either mode — an EOA or a deployed contract wallet signs in; a counterfactual smart account
105
+ cannot (no ERC-6492).
106
+ The token renews itself silently for both account types — against a service that issues the
107
+ refresh credential this release expects, an external wallet signs once, when the session opens,
108
+ not once per token; against a deployment that answers without one there is nothing to renew from,
109
+ and every expired token costs another signature. The session and what holding it costs are in
110
+ [`INTEGRATION.md` §8](INTEGRATION.md#8-auth-modes). See `apps/auth-demo` for a browser-side
111
+ verifier.
89
112
 
90
113
  Brand images (logo, wallet icons) ship inside the package as bundled data URLs — you do not need a `/fluent-assets` folder.
91
114
 
@@ -97,7 +120,13 @@ By default the connect control floats top-right (`connectButton="fixed"`). To pl
97
120
  // Hide the default control and use your own CTA
98
121
  <FluentWidget
99
122
  connectButton={false}
100
- config={{ appId: "app_…", privyClientId: "client-…", network: "testnet", appName: "My App" }}
123
+ config={{
124
+ appId: "app_…",
125
+ privyClientId: "client-…",
126
+ network: "testnet",
127
+ appName: "My App",
128
+ authMode: "direct",
129
+ }}
101
130
  mode="page"
102
131
  renderPage={({ openConnect, openAccount, hasConnectedAccount }) => (
103
132
  <button type="button" onClick={hasConnectedAccount ? openAccount : openConnect}>
@@ -119,6 +148,95 @@ By default the connect control floats top-right (`connectButton="fixed"`). To pl
119
148
  />
120
149
  ```
121
150
 
151
+ ### Sending a transaction
152
+
153
+ Everything your app sends goes through one call: `widget.createBatchOp({...}).execute()`.
154
+ `widget` comes from the render context (`renderPage` / `renderHome`) or from
155
+ `useFluentWidget()` anywhere below `<FluentWidget>`; `useWidget()` returns it on its own. The
156
+ widget routes a Fluent ID (one UserOperation, all calls atomic) and an external wallet (one
157
+ transaction per call, each confirmed in the wallet) itself, so your app never branches on the
158
+ account type.
159
+
160
+ ```tsx
161
+ import { useFluentWidget } from "@fluent.xyz/connect";
162
+ import { erc20Abi, exchangeAbi } from "./abi";
163
+
164
+ function BuyButton({ token, exchange, price, orderId }) {
165
+ const { widget } = useFluentWidget();
166
+
167
+ async function onBuy() {
168
+ // Guard first: `execute()` rejects when the session cannot execute, and
169
+ // `widget.account.executionError` is the message to show when it is not ready.
170
+ if (!widget.account.executionReady) return;
171
+
172
+ const { hash, atomic } = await widget
173
+ .createBatchOp({
174
+ id: "buy-order",
175
+ reviewTitle: "Approve + buy",
176
+ calls: [
177
+ { to: token, abi: erc20Abi, method: "approve", args: [exchange, price] },
178
+ { to: exchange, abi: exchangeAbi, method: "buy", args: [orderId] },
179
+ ],
180
+ })
181
+ .execute();
182
+ // atomic === true → both calls landed in a single UserOperation (Fluent ID)
183
+ }
184
+
185
+ return (
186
+ <button type="button" onClick={onBuy} disabled={!widget.account.executionReady}>
187
+ Buy
188
+ </button>
189
+ );
190
+ }
191
+ ```
192
+
193
+ `calls` is the only required field: `reviewTitle` is the heading of the Fluent review modal
194
+ and `id` is a label for your own bookkeeping. Each call carries either `abi` + `method` +
195
+ `args` or raw `data`, and `to` can be any contract. `createBatchOp` itself throws straight
196
+ away on an empty `calls` array, or on a call that has neither `data` nor `abi` + `method`.
197
+
198
+ `execute()` resolves once the transaction is included, with `hash`, every hash in order as
199
+ `hashes`, `atomic`, `sponsored`, the `receipt` for `hash`, and `userOpHash` for a
200
+ smart-account operation. It rejects when the session cannot execute (the message is
201
+ `widget.account.executionError`), when the user dismisses the Fluent review
202
+ (`FluentReviewRejectedError`, message `User rejected Fluent transaction review`), when the
203
+ wallet rejects a call, and when a call reverts — a sequential external-wallet batch stops at
204
+ the call that reverted. Who pays the gas, how to force a gas token, and what each stage costs
205
+ in time: [`INTEGRATION.md` §7](INTEGRATION.md#7-sending-a-transaction).
206
+
207
+ ### Execution gas headroom
208
+
209
+ For smart-account batches whose execution cost can change between estimation and
210
+ inclusion, set `userOperationGas` on `execute()`:
211
+
212
+ ```ts
213
+ await widget.createBatchOp({ calls }).execute({
214
+ userOperationGas: {
215
+ callGasBuffer: { percentage: 50, fixed: 50_000n },
216
+ },
217
+ });
218
+ ```
219
+
220
+ This example sets `callGasLimit` to `ceil(estimate × 1.5) + 50,000`. The estimate
221
+ covers the complete UserOperation, including account deployment and any gas-token
222
+ approval prepended by the widget. The buffer is applied during normal gas
223
+ preparation, before final paymaster authorization and signing, without adding an
224
+ estimation request. Paymaster adapters that previously supplied data only once
225
+ are called again to authorize the final gas limit. The same policy
226
+ applies to sponsored, account-paid, and ERC-20 gas, including sponsorship fallback.
227
+
228
+ Alternatively, supply a known execution limit with
229
+ `userOperationGas: { callGasLimit: 600_000n }`. Use either `callGasLimit` or
230
+ `callGasBuffer`. Percentages must be nonnegative safe integers; fixed gas must be
231
+ a nonnegative bigint, and the final limit must fit a positive uint128. Defaults
232
+ keep the existing estimation behavior. These options apply only to smart-account
233
+ UserOperations; external EOA transactions keep their wallet's gas estimation.
234
+
235
+ Choose headroom for your application's execution paths and paymaster limits.
236
+ Headroom increases the maximum gas budget and does not guarantee execution if
237
+ state changes. An included outer transaction can still contain a failed
238
+ UserOperation; the widget continues to reject that failed execution.
239
+
122
240
  ## Styles
123
241
 
124
242
  Import the package CSS once in your app entry: