@fluent.xyz/connect 0.5.3 → 0.6.0-rc.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/dist/index.d.ts CHANGED
@@ -1,312 +1,41 @@
1
- import * as viem from 'viem';
2
- import { Chain, PublicClient, Transport, Address, createPublicClient, Hex, Abi, Hash, TransactionReceipt, SignableMessage, TypedData, TypedDataDefinition, WalletClient } from 'viem';
3
- import * as React from 'react';
4
- import { ReactNode, RefObject, AnchorHTMLAttributes, SVGProps } from 'react';
1
+ import * as react from 'react';
2
+ import { ReactNode, RefObject } from 'react';
5
3
  import * as web from '@privy-io/react-auth';
6
- import { CallType } from '@zerodev/permissions/policies';
7
- export { CallType, ParamCondition } from '@zerodev/permissions/policies';
8
- import * as _zerodev_sdk from '@zerodev/sdk';
9
- import { createKernelAccount, createKernelAccountClient, ZeroDevPaymasterClient } from '@zerodev/sdk';
10
- import * as _zerodev_sdk_actions from '@zerodev/sdk/actions';
11
- import * as viem_account_abstraction from 'viem/account-abstraction';
12
- import { SmartAccount, GetPaymasterDataParameters } from 'viem/account-abstraction';
13
- import * as class_variance_authority_types from 'class-variance-authority/types';
14
- import { Button as Button$1 } from '@base-ui/react/button';
15
- import { VariantProps } from 'class-variance-authority';
16
- import { Switch as Switch$1 } from '@base-ui/react/switch';
17
- import { Dialog as Dialog$1 } from '@base-ui/react/dialog';
18
- import { Separator as Separator$1 } from '@base-ui/react/separator';
19
- import { z } from 'zod';
4
+ import * as viem from 'viem';
5
+ import { Chain, SignableMessage, Hex, TypedData, TypedDataDefinition, Address, Abi, Hash, TransactionReceipt, WalletClient } from 'viem';
20
6
 
21
7
  /**
22
- * Minimal FluentBridge view ABI for connectivity checks.
23
- * Full ABI will be synced from solidity-contracts in a later release.
8
+ * Privy runtime supplied by a host using a native SDK. Its Provider owns session
9
+ * restoration, login and wallet RPC; web hosts keep the normal React SDK.
10
+ * Keep one stable adapter per runtime. Changing its Provider remounts descendants
11
+ * so React hooks from different SDKs never share a component lifetime.
12
+ *
13
+ * @experimental May change or be removed in a minor release: the one provider seam of the
14
+ * widget, kept for hosts that run a native login SDK.
24
15
  */
25
- declare const fluentBridgeAbi: readonly [{
26
- readonly type: "function";
27
- readonly name: "otherSideChainId";
28
- readonly stateMutability: "view";
29
- readonly inputs: readonly [];
30
- readonly outputs: readonly [{
31
- readonly name: "";
32
- readonly type: "uint256";
33
- }];
34
- }];
16
+ type FluentPrivyAdapter = Pick<typeof web, "PrivyProvider" | "Captcha" | "usePrivy" | "useSignMessage" | "useSignTypedData" | "useWallets" | "useIdentityToken" | "useUser" | "useLinkAccount" | "useLoginWithSiwe" | "useModalStatus" | "useCreateWallet" | "useLoginWithEmail" | "useLoginWithOAuth" | "useLoginWithPasskey" | "useLinkWithPasskey">;
35
17
 
36
- declare const fluentChainSchema: z.ZodObject<{
37
- id: z.ZodString;
38
- name: z.ZodString;
39
- chainId: z.ZodNumber;
40
- testnet: z.ZodBoolean;
41
- nativeCurrency: z.ZodObject<{
42
- name: z.ZodString;
43
- symbol: z.ZodString;
44
- decimals: z.ZodNumber;
45
- }, "strip", z.ZodTypeAny, {
46
- symbol: string;
47
- name: string;
48
- decimals: number;
49
- }, {
50
- symbol: string;
51
- name: string;
52
- decimals: number;
53
- }>;
54
- rpcUrls: z.ZodObject<{
55
- default: z.ZodObject<{
56
- http: z.ZodArray<z.ZodString, "many">;
57
- webSocket: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
58
- }, "strip", z.ZodTypeAny, {
59
- http: string[];
60
- webSocket?: string[] | undefined;
61
- }, {
62
- http: string[];
63
- webSocket?: string[] | undefined;
64
- }>;
65
- }, "strip", z.ZodTypeAny, {
66
- default: {
67
- http: string[];
68
- webSocket?: string[] | undefined;
69
- };
70
- }, {
71
- default: {
72
- http: string[];
73
- webSocket?: string[] | undefined;
74
- };
75
- }>;
76
- blockExplorers: z.ZodObject<{
77
- default: z.ZodObject<{
78
- name: z.ZodString;
79
- url: z.ZodString;
80
- }, "strip", z.ZodTypeAny, {
81
- name: string;
82
- url: string;
83
- }, {
84
- name: string;
85
- url: string;
86
- }>;
87
- }, "strip", z.ZodTypeAny, {
88
- default: {
89
- name: string;
90
- url: string;
91
- };
92
- }, {
93
- default: {
94
- name: string;
95
- url: string;
96
- };
97
- }>;
98
- infoURL: z.ZodString;
99
- faucets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
100
- parent: z.ZodOptional<z.ZodObject<{
101
- type: z.ZodLiteral<"L2">;
102
- chainId: z.ZodNumber;
103
- bridgeUrl: z.ZodString;
104
- }, "strip", z.ZodTypeAny, {
105
- type: "L2";
106
- chainId: number;
107
- bridgeUrl: string;
108
- }, {
109
- type: "L2";
110
- chainId: number;
111
- bridgeUrl: string;
112
- }>>;
113
- contracts: z.ZodOptional<z.ZodObject<{
114
- fluentBridge: z.ZodOptional<z.ZodObject<{
115
- address: z.ZodString;
116
- implementation: z.ZodOptional<z.ZodString>;
117
- }, "strip", z.ZodTypeAny, {
118
- address: string;
119
- implementation?: string | undefined;
120
- }, {
121
- address: string;
122
- implementation?: string | undefined;
123
- }>>;
124
- nativeGateway: z.ZodOptional<z.ZodObject<{
125
- address: z.ZodString;
126
- implementation: z.ZodOptional<z.ZodString>;
127
- }, "strip", z.ZodTypeAny, {
128
- address: string;
129
- implementation?: string | undefined;
130
- }, {
131
- address: string;
132
- implementation?: string | undefined;
133
- }>>;
134
- erc20Gateway: z.ZodOptional<z.ZodObject<{
135
- address: z.ZodString;
136
- implementation: z.ZodOptional<z.ZodString>;
137
- }, "strip", z.ZodTypeAny, {
138
- address: string;
139
- implementation?: string | undefined;
140
- }, {
141
- address: string;
142
- implementation?: string | undefined;
143
- }>>;
144
- wethGateway: z.ZodOptional<z.ZodObject<{
145
- address: z.ZodString;
146
- implementation: z.ZodOptional<z.ZodString>;
147
- }, "strip", z.ZodTypeAny, {
148
- address: string;
149
- implementation?: string | undefined;
150
- }, {
151
- address: string;
152
- implementation?: string | undefined;
153
- }>>;
154
- universalTokenFactory: z.ZodOptional<z.ZodObject<{
155
- address: z.ZodString;
156
- implementation: z.ZodOptional<z.ZodString>;
157
- }, "strip", z.ZodTypeAny, {
158
- address: string;
159
- implementation?: string | undefined;
160
- }, {
161
- address: string;
162
- implementation?: string | undefined;
163
- }>>;
164
- paymentGateway: z.ZodOptional<z.ZodObject<{
165
- address: z.ZodString;
166
- implementation: z.ZodOptional<z.ZodString>;
167
- }, "strip", z.ZodTypeAny, {
168
- address: string;
169
- implementation?: string | undefined;
170
- }, {
171
- address: string;
172
- implementation?: string | undefined;
173
- }>>;
174
- peggedTokenPrecompile: z.ZodOptional<z.ZodObject<{
175
- address: z.ZodString;
176
- }, "strip", z.ZodTypeAny, {
177
- address: string;
178
- }, {
179
- address: string;
180
- }>>;
181
- }, "strip", z.ZodTypeAny, {
182
- fluentBridge?: {
183
- address: string;
184
- implementation?: string | undefined;
185
- } | undefined;
186
- nativeGateway?: {
187
- address: string;
188
- implementation?: string | undefined;
189
- } | undefined;
190
- erc20Gateway?: {
191
- address: string;
192
- implementation?: string | undefined;
193
- } | undefined;
194
- wethGateway?: {
195
- address: string;
196
- implementation?: string | undefined;
197
- } | undefined;
198
- universalTokenFactory?: {
199
- address: string;
200
- implementation?: string | undefined;
201
- } | undefined;
202
- paymentGateway?: {
203
- address: string;
204
- implementation?: string | undefined;
205
- } | undefined;
206
- peggedTokenPrecompile?: {
207
- address: string;
208
- } | undefined;
209
- }, {
210
- fluentBridge?: {
211
- address: string;
212
- implementation?: string | undefined;
213
- } | undefined;
214
- nativeGateway?: {
215
- address: string;
216
- implementation?: string | undefined;
217
- } | undefined;
218
- erc20Gateway?: {
219
- address: string;
220
- implementation?: string | undefined;
221
- } | undefined;
222
- wethGateway?: {
223
- address: string;
224
- implementation?: string | undefined;
225
- } | undefined;
226
- universalTokenFactory?: {
227
- address: string;
228
- implementation?: string | undefined;
229
- } | undefined;
230
- paymentGateway?: {
231
- address: string;
232
- implementation?: string | undefined;
233
- } | undefined;
234
- peggedTokenPrecompile?: {
235
- address: string;
236
- } | undefined;
237
- }>>;
238
- }, "strip", z.ZodTypeAny, {
18
+ /**
19
+ * One Fluent chain as the registry describes it: its ids, native currency, RPC and explorer
20
+ * endpoints, its L1 parent and its contracts. Declared rather than inferred from
21
+ * `fluentChainSchema`, so its shape is what this file says; `chainDefinitionMatchesSchema`
22
+ * below fails the build if the two drift apart.
23
+ */
24
+ type FluentChainDefinition = {
25
+ /** The registry's own id: `"fluent-testnet"`, `"fluent-mainnet"`. */
239
26
  id: string;
240
27
  name: string;
241
28
  chainId: number;
242
29
  testnet: boolean;
243
30
  nativeCurrency: {
244
- symbol: string;
245
31
  name: string;
246
- decimals: number;
247
- };
248
- rpcUrls: {
249
- default: {
250
- http: string[];
251
- webSocket?: string[] | undefined;
252
- };
253
- };
254
- blockExplorers: {
255
- default: {
256
- name: string;
257
- url: string;
258
- };
259
- };
260
- infoURL: string;
261
- faucets?: string[] | undefined;
262
- parent?: {
263
- type: "L2";
264
- chainId: number;
265
- bridgeUrl: string;
266
- } | undefined;
267
- contracts?: {
268
- fluentBridge?: {
269
- address: string;
270
- implementation?: string | undefined;
271
- } | undefined;
272
- nativeGateway?: {
273
- address: string;
274
- implementation?: string | undefined;
275
- } | undefined;
276
- erc20Gateway?: {
277
- address: string;
278
- implementation?: string | undefined;
279
- } | undefined;
280
- wethGateway?: {
281
- address: string;
282
- implementation?: string | undefined;
283
- } | undefined;
284
- universalTokenFactory?: {
285
- address: string;
286
- implementation?: string | undefined;
287
- } | undefined;
288
- paymentGateway?: {
289
- address: string;
290
- implementation?: string | undefined;
291
- } | undefined;
292
- peggedTokenPrecompile?: {
293
- address: string;
294
- } | undefined;
295
- } | undefined;
296
- }, {
297
- id: string;
298
- name: string;
299
- chainId: number;
300
- testnet: boolean;
301
- nativeCurrency: {
302
32
  symbol: string;
303
- name: string;
304
33
  decimals: number;
305
34
  };
306
35
  rpcUrls: {
307
36
  default: {
308
37
  http: string[];
309
- webSocket?: string[] | undefined;
38
+ webSocket?: string[];
310
39
  };
311
40
  };
312
41
  blockExplorers: {
@@ -316,927 +45,80 @@ declare const fluentChainSchema: z.ZodObject<{
316
45
  };
317
46
  };
318
47
  infoURL: string;
319
- faucets?: string[] | undefined;
48
+ faucets?: string[];
49
+ /** The L1 the chain settles to, and where its bridge is. */
320
50
  parent?: {
321
51
  type: "L2";
322
52
  chainId: number;
323
53
  bridgeUrl: string;
324
- } | undefined;
54
+ };
55
+ /** Addresses of the chain's system contracts, each with its implementation when proxied. */
325
56
  contracts?: {
326
57
  fluentBridge?: {
327
58
  address: string;
328
- implementation?: string | undefined;
329
- } | undefined;
59
+ implementation?: string;
60
+ };
330
61
  nativeGateway?: {
331
62
  address: string;
332
- implementation?: string | undefined;
333
- } | undefined;
63
+ implementation?: string;
64
+ };
334
65
  erc20Gateway?: {
335
66
  address: string;
336
- implementation?: string | undefined;
337
- } | undefined;
67
+ implementation?: string;
68
+ };
338
69
  wethGateway?: {
339
70
  address: string;
340
- implementation?: string | undefined;
341
- } | undefined;
71
+ implementation?: string;
72
+ };
342
73
  universalTokenFactory?: {
343
74
  address: string;
344
- implementation?: string | undefined;
345
- } | undefined;
346
- paymentGateway?: {
347
- address: string;
348
- implementation?: string | undefined;
349
- } | undefined;
350
- peggedTokenPrecompile?: {
351
- address: string;
352
- } | undefined;
353
- } | undefined;
354
- }>;
355
- declare const l1ChainSchema: z.ZodObject<{
356
- id: z.ZodString;
357
- name: z.ZodString;
358
- chainId: z.ZodNumber;
359
- testnet: z.ZodBoolean;
360
- nativeCurrency: z.ZodObject<{
361
- name: z.ZodString;
362
- symbol: z.ZodString;
363
- decimals: z.ZodNumber;
364
- }, "strip", z.ZodTypeAny, {
365
- symbol: string;
366
- name: string;
367
- decimals: number;
368
- }, {
369
- symbol: string;
370
- name: string;
371
- decimals: number;
372
- }>;
373
- rpcUrls: z.ZodObject<{
374
- default: z.ZodObject<{
375
- http: z.ZodArray<z.ZodString, "many">;
376
- }, "strip", z.ZodTypeAny, {
377
- http: string[];
378
- }, {
379
- http: string[];
380
- }>;
381
- }, "strip", z.ZodTypeAny, {
382
- default: {
383
- http: string[];
384
- };
385
- }, {
386
- default: {
387
- http: string[];
388
- };
389
- }>;
390
- blockExplorers: z.ZodObject<{
391
- default: z.ZodObject<{
392
- name: z.ZodString;
393
- url: z.ZodString;
394
- }, "strip", z.ZodTypeAny, {
395
- name: string;
396
- url: string;
397
- }, {
398
- name: string;
399
- url: string;
400
- }>;
401
- }, "strip", z.ZodTypeAny, {
402
- default: {
403
- name: string;
404
- url: string;
405
- };
406
- }, {
407
- default: {
408
- name: string;
409
- url: string;
410
- };
411
- }>;
412
- pairedL2: z.ZodOptional<z.ZodString>;
413
- contracts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
414
- address: z.ZodString;
415
- implementation: z.ZodOptional<z.ZodString>;
416
- }, "strip", z.ZodTypeAny, {
417
- address: string;
418
- implementation?: string | undefined;
419
- }, {
420
- address: string;
421
- implementation?: string | undefined;
422
- }>>>;
423
- }, "strip", z.ZodTypeAny, {
424
- id: string;
425
- name: string;
426
- chainId: number;
427
- testnet: boolean;
428
- nativeCurrency: {
429
- symbol: string;
430
- name: string;
431
- decimals: number;
432
- };
433
- rpcUrls: {
434
- default: {
435
- http: string[];
436
- };
437
- };
438
- blockExplorers: {
439
- default: {
440
- name: string;
441
- url: string;
442
- };
443
- };
444
- contracts?: Record<string, {
445
- address: string;
446
- implementation?: string | undefined;
447
- }> | undefined;
448
- pairedL2?: string | undefined;
449
- }, {
450
- id: string;
451
- name: string;
452
- chainId: number;
453
- testnet: boolean;
454
- nativeCurrency: {
455
- symbol: string;
456
- name: string;
457
- decimals: number;
458
- };
459
- rpcUrls: {
460
- default: {
461
- http: string[];
462
- };
463
- };
464
- blockExplorers: {
465
- default: {
466
- name: string;
467
- url: string;
468
- };
469
- };
470
- contracts?: Record<string, {
471
- address: string;
472
- implementation?: string | undefined;
473
- }> | undefined;
474
- pairedL2?: string | undefined;
475
- }>;
476
- declare const appSchema: z.ZodObject<{
477
- id: z.ZodString;
478
- name: z.ZodString;
479
- category: z.ZodString;
480
- description: z.ZodOptional<z.ZodString>;
481
- docs: z.ZodOptional<z.ZodString>;
482
- deployments: z.ZodRecord<z.ZodString, z.ZodObject<{
483
- contract: z.ZodString;
484
- address: z.ZodString;
485
- }, "strip", z.ZodTypeAny, {
486
- address: string;
487
- contract: string;
488
- }, {
489
- address: string;
490
- contract: string;
491
- }>>;
492
- }, "strip", z.ZodTypeAny, {
493
- id: string;
494
- name: string;
495
- category: string;
496
- deployments: Record<string, {
497
- address: string;
498
- contract: string;
499
- }>;
500
- description?: string | undefined;
501
- docs?: string | undefined;
502
- }, {
503
- id: string;
504
- name: string;
505
- category: string;
506
- deployments: Record<string, {
507
- address: string;
508
- contract: string;
509
- }>;
510
- description?: string | undefined;
511
- docs?: string | undefined;
512
- }>;
513
- type FluentChainDefinition = z.infer<typeof fluentChainSchema>;
514
- type L1ChainDefinition = z.infer<typeof l1ChainSchema>;
515
- type AppDefinition = z.infer<typeof appSchema>;
516
- declare const zerodevIntegrationSchema: z.ZodObject<{
517
- id: z.ZodLiteral<"zerodev">;
518
- name: z.ZodString;
519
- description: z.ZodString;
520
- docs: z.ZodString;
521
- dashboard: z.ZodString;
522
- rpcUrlTemplate: z.ZodString;
523
- supportedFluentChains: z.ZodArray<z.ZodObject<{
524
- fluentChainId: z.ZodString;
525
- chainId: z.ZodNumber;
526
- }, "strip", z.ZodTypeAny, {
527
- chainId: number;
528
- fluentChainId: string;
529
- }, {
530
- chainId: number;
531
- fluentChainId: string;
532
- }>, "many">;
533
- privy: z.ZodObject<{
534
- docs: z.ZodString;
535
- embeddedWalletCreateOnLogin: z.ZodString;
536
- }, "strip", z.ZodTypeAny, {
537
- docs: string;
538
- embeddedWalletCreateOnLogin: string;
539
- }, {
540
- docs: string;
541
- embeddedWalletCreateOnLogin: string;
542
- }>;
543
- }, "strip", z.ZodTypeAny, {
544
- id: "zerodev";
545
- name: string;
546
- description: string;
547
- docs: string;
548
- dashboard: string;
549
- rpcUrlTemplate: string;
550
- supportedFluentChains: {
551
- chainId: number;
552
- fluentChainId: string;
553
- }[];
554
- privy: {
555
- docs: string;
556
- embeddedWalletCreateOnLogin: string;
557
- };
558
- }, {
559
- id: "zerodev";
560
- name: string;
561
- description: string;
562
- docs: string;
563
- dashboard: string;
564
- rpcUrlTemplate: string;
565
- supportedFluentChains: {
566
- chainId: number;
567
- fluentChainId: string;
568
- }[];
569
- privy: {
570
- docs: string;
571
- embeddedWalletCreateOnLogin: string;
572
- };
573
- }>;
574
- type ZerodevIntegration = z.infer<typeof zerodevIntegrationSchema>;
575
-
576
- declare const fluentChains: {
577
- readonly testnet: {
578
- id: string;
579
- name: string;
580
- chainId: number;
581
- testnet: boolean;
582
- nativeCurrency: {
583
- symbol: string;
584
- name: string;
585
- decimals: number;
586
- };
587
- rpcUrls: {
588
- default: {
589
- http: string[];
590
- webSocket?: string[] | undefined;
591
- };
592
- };
593
- blockExplorers: {
594
- default: {
595
- name: string;
596
- url: string;
597
- };
598
- };
599
- infoURL: string;
600
- faucets?: string[] | undefined;
601
- parent?: {
602
- type: "L2";
603
- chainId: number;
604
- bridgeUrl: string;
605
- } | undefined;
606
- contracts?: {
607
- fluentBridge?: {
608
- address: string;
609
- implementation?: string | undefined;
610
- } | undefined;
611
- nativeGateway?: {
612
- address: string;
613
- implementation?: string | undefined;
614
- } | undefined;
615
- erc20Gateway?: {
616
- address: string;
617
- implementation?: string | undefined;
618
- } | undefined;
619
- wethGateway?: {
620
- address: string;
621
- implementation?: string | undefined;
622
- } | undefined;
623
- universalTokenFactory?: {
624
- address: string;
625
- implementation?: string | undefined;
626
- } | undefined;
627
- paymentGateway?: {
628
- address: string;
629
- implementation?: string | undefined;
630
- } | undefined;
631
- peggedTokenPrecompile?: {
632
- address: string;
633
- } | undefined;
634
- } | undefined;
635
- };
636
- readonly mainnet: {
637
- id: string;
638
- name: string;
639
- chainId: number;
640
- testnet: boolean;
641
- nativeCurrency: {
642
- symbol: string;
643
- name: string;
644
- decimals: number;
645
- };
646
- rpcUrls: {
647
- default: {
648
- http: string[];
649
- webSocket?: string[] | undefined;
650
- };
651
- };
652
- blockExplorers: {
653
- default: {
654
- name: string;
655
- url: string;
656
- };
75
+ implementation?: string;
657
76
  };
658
- infoURL: string;
659
- faucets?: string[] | undefined;
660
- parent?: {
661
- type: "L2";
662
- chainId: number;
663
- bridgeUrl: string;
664
- } | undefined;
665
- contracts?: {
666
- fluentBridge?: {
667
- address: string;
668
- implementation?: string | undefined;
669
- } | undefined;
670
- nativeGateway?: {
671
- address: string;
672
- implementation?: string | undefined;
673
- } | undefined;
674
- erc20Gateway?: {
675
- address: string;
676
- implementation?: string | undefined;
677
- } | undefined;
678
- wethGateway?: {
679
- address: string;
680
- implementation?: string | undefined;
681
- } | undefined;
682
- universalTokenFactory?: {
683
- address: string;
684
- implementation?: string | undefined;
685
- } | undefined;
686
- paymentGateway?: {
687
- address: string;
688
- implementation?: string | undefined;
689
- } | undefined;
690
- peggedTokenPrecompile?: {
691
- address: string;
692
- } | undefined;
693
- } | undefined;
694
- };
695
- };
696
- declare const l1Chains: {
697
- readonly ethereum: {
698
- id: string;
699
- name: string;
700
- chainId: number;
701
- testnet: boolean;
702
- nativeCurrency: {
703
- symbol: string;
704
- name: string;
705
- decimals: number;
706
- };
707
- rpcUrls: {
708
- default: {
709
- http: string[];
710
- };
711
- };
712
- blockExplorers: {
713
- default: {
714
- name: string;
715
- url: string;
716
- };
717
- };
718
- contracts?: Record<string, {
77
+ paymentGateway?: {
719
78
  address: string;
720
- implementation?: string | undefined;
721
- }> | undefined;
722
- pairedL2?: string | undefined;
723
- };
724
- readonly sepolia: {
725
- id: string;
726
- name: string;
727
- chainId: number;
728
- testnet: boolean;
729
- nativeCurrency: {
730
- symbol: string;
731
- name: string;
732
- decimals: number;
733
- };
734
- rpcUrls: {
735
- default: {
736
- http: string[];
737
- };
79
+ implementation?: string;
738
80
  };
739
- blockExplorers: {
740
- default: {
741
- name: string;
742
- url: string;
743
- };
744
- };
745
- contracts?: Record<string, {
746
- address: string;
747
- implementation?: string | undefined;
748
- }> | undefined;
749
- pairedL2?: string | undefined;
750
- };
751
- };
752
- declare const apps: {
753
- readonly fluentBridge: {
754
- id: string;
755
- name: string;
756
- category: string;
757
- deployments: Record<string, {
81
+ peggedTokenPrecompile?: {
758
82
  address: string;
759
- contract: string;
760
- }>;
761
- description?: string | undefined;
762
- docs?: string | undefined;
763
- };
764
- };
765
- declare const integrations: {
766
- readonly zerodev: {
767
- id: "zerodev";
768
- name: string;
769
- description: string;
770
- docs: string;
771
- dashboard: string;
772
- rpcUrlTemplate: string;
773
- supportedFluentChains: {
774
- chainId: number;
775
- fluentChainId: string;
776
- }[];
777
- privy: {
778
- docs: string;
779
- embeddedWalletCreateOnLogin: string;
780
83
  };
781
84
  };
782
85
  };
783
- declare const registryVersion: "0.1.0";
784
- /** Fluent chain IDs with ZeroDev bundler/paymaster support */
785
- declare const fluentZeroDevChainIds: readonly number[];
786
- declare function getFluentChain(id: keyof typeof fluentChains): FluentChainDefinition;
787
- declare function getFluentChainByChainId(chainId: number): FluentChainDefinition | undefined;
788
- declare function getL1Chain(id: keyof typeof l1Chains): L1ChainDefinition;
789
- declare function getL1ForFluentChain(fluent: FluentChainDefinition): L1ChainDefinition | undefined;
790
- declare function getApp(id: keyof typeof apps): AppDefinition;
791
- declare function getZerodevIntegration(): ZerodevIntegration;
792
- declare function getZeroDevRpcUrl(params: {
793
- projectId: string;
794
- chainId: number;
795
- }): string;
796
- declare function isFluentZeroDevChain(chainId: number): boolean;
797
-
798
- type BridgeAddresses = {
799
- l2?: {
800
- proxy: `0x${string}`;
801
- implementation?: `0x${string}`;
802
- };
803
- l1?: {
804
- proxy: `0x${string}`;
805
- implementation?: `0x${string}`;
806
- };
807
- };
808
- declare function resolveBridgeAddresses(definition: FluentChainDefinition): BridgeAddresses;
809
- declare function getContractAddressFromChain(chain: Chain, name: "fluentBridge" | "paymentGateway" | "universalTokenFactory"): `0x${string}` | undefined;
810
- declare function resolveL1Definition(definition: FluentChainDefinition): L1ChainDefinition | undefined;
811
86
 
812
- type FluentClientConfig = {
813
- /** Fluent network to target. Defaults to `"testnet"`. */
814
- network?: "testnet" | "mainnet";
815
- /** Custom RPC URL. Defaults to the selected chain's built-in RPC. */
816
- rpcUrl?: string;
817
- /** Advanced override: pass a viem chain directly (takes precedence over `network`). */
818
- chain?: Chain;
819
- /** Advanced override: pass a viem transport directly (takes precedence over `rpcUrl`). */
820
- transport?: Transport;
821
- };
822
- type FluentClient = {
823
- chain: Chain;
824
- definition: FluentChainDefinition;
825
- public: PublicClient;
826
- addresses: {
827
- bridge: BridgeAddresses;
828
- peggedTokenPrecompile?: `0x${string}`;
829
- paymentGateway?: `0x${string}`;
830
- universalTokenFactory?: `0x${string}`;
831
- };
832
- l1: L1ChainDefinition | undefined;
833
- /** Read L2 bridge `otherSideChainId` when deployed */
834
- readOtherSideChainId: () => Promise<bigint | undefined>;
835
- };
836
- declare function createFluentClient(config?: FluentClientConfig): FluentClient;
837
-
838
- type FluentPermissionStatus = "pending" | "active" | "expired" | "revoked";
839
- type FluentCallPermission = {
840
- chainId: number;
841
- to: `0x${string}`;
842
- function?: string;
843
- selector?: `0x${string}`;
844
- };
845
- type FluentSpendPeriod = "transaction" | "hour" | "day" | "session";
846
- type FluentSpendPermission = {
847
- chainId: number;
848
- token: `0x${string}` | "native";
849
- symbol?: string;
850
- limit: string;
851
- period: FluentSpendPeriod;
852
- recipients?: `0x${string}`[];
853
- };
854
- type FluentPermissionPolicy$1 = {
855
- calls: FluentCallPermission[];
856
- spend: FluentSpendPermission[];
857
- };
858
- type FluentPermissionGrantRequest = {
859
- appId: string;
860
- expiry: number;
861
- permissions: FluentPermissionPolicy$1;
862
- };
863
- type FluentPermissionGrant = {
864
- id: string;
865
- appId: string;
866
- clientId: string;
867
- userId: string;
868
- walletAddress?: `0x${string}`;
869
- origin: string;
870
- status: FluentPermissionStatus;
871
- expiry: number;
872
- permissions: FluentPermissionPolicy$1;
873
- createdAt: number;
874
- lastUsedAt?: number;
875
- revokedAt?: number;
876
- };
877
- type FluentPermissionPreview = {
878
- request: FluentPermissionGrantRequest;
879
- effectivePolicy: FluentPermissionPolicy$1;
880
- warnings: string[];
881
- };
882
- type FluentPermissionClientConfig = {
883
- baseUrl: string;
884
- clientId: string;
885
- getSessionToken: () => string | Promise<string>;
886
- fetch?: typeof globalThis.fetch;
887
- };
888
- type FluentPermissionClient = {
889
- preview: (request: FluentPermissionGrantRequest) => Promise<FluentPermissionPreview>;
890
- grant: (request: FluentPermissionGrantRequest) => Promise<FluentPermissionGrant>;
891
- list: () => Promise<FluentPermissionGrant[]>;
892
- revoke: (grantId: string) => Promise<FluentPermissionGrant>;
893
- };
894
- declare function createFluentPermissionClient(config: FluentPermissionClientConfig): FluentPermissionClient;
895
-
896
- type FluentNetworkName = "testnet" | "mainnet";
897
- type FluentTokenDefinition = {
898
- chainId: number;
899
- address?: Address;
900
- name: string;
901
- symbol: string;
902
- decimals: number;
903
- logoURI?: string;
904
- native?: true;
905
- gasPriority?: number;
906
- };
907
- declare function isFluentNativeToken(token: Pick<FluentTokenDefinition, "native">): boolean;
908
- declare function fluentTokenIdentity(token: Pick<FluentTokenDefinition, "chainId" | "address" | "native">): string;
909
- type FluentTokenBalance = FluentTokenDefinition & {
910
- raw: bigint | null;
911
- formatted: string | null;
912
- status: "ready" | "not-configured" | "error";
913
- error?: string;
914
- };
915
- declare const fluentTestnetTokenDefaults: {
916
- readonly ETH: {
917
- readonly chainId: 20994;
918
- readonly symbol: "ETH";
919
- readonly name: "Ether";
920
- readonly decimals: 18;
921
- readonly native: true;
922
- readonly gasPriority: 3;
923
- };
924
- readonly USDnr: {
925
- readonly chainId: 20994;
926
- readonly symbol: "USDnr";
927
- readonly name: "USDnr";
928
- readonly decimals: 6;
929
- readonly address: "0x279a6DC6354374473f6f3CFB3999e6C2e146f8a1";
930
- readonly gasPriority: 2;
931
- };
932
- readonly BLEND: {
933
- readonly chainId: 20994;
934
- readonly symbol: "BLEND";
935
- readonly name: "Mock Blend";
936
- readonly decimals: 18;
937
- readonly address: "0x83Fed707A8dDDC2535aE591CF19fB6C91D542D8E";
938
- readonly gasPriority: 1;
939
- };
940
- };
941
- declare const fluentMainnetTokenDefaults: {
942
- readonly ETH: {
943
- readonly chainId: 25363;
944
- readonly symbol: "ETH";
945
- readonly name: "Ether";
946
- readonly decimals: 18;
947
- readonly native: true;
948
- readonly gasPriority: 3;
949
- };
950
- readonly USDnr: {
951
- readonly chainId: 25363;
952
- readonly symbol: "USDnr";
953
- readonly name: "USDnr";
954
- readonly decimals: 6;
955
- readonly address: "0xD48e565561416dE59DA1050ED70b8d75e8eF28f9";
956
- readonly gasPriority: 2;
957
- };
958
- readonly BLEND: {
959
- readonly chainId: 25363;
960
- readonly symbol: "BLEND";
961
- readonly name: "Fluent";
962
- readonly decimals: 18;
963
- readonly address: "0x1385b8f55a84f2bda13eed4099d29eae03d553b2";
964
- readonly gasPriority: 1;
965
- };
966
- };
967
- declare function getFluentTokenDefaultsForNetwork(network: FluentNetworkName): {
968
- readonly ETH: {
969
- readonly chainId: 20994;
970
- readonly symbol: "ETH";
971
- readonly name: "Ether";
972
- readonly decimals: 18;
973
- readonly native: true;
974
- readonly gasPriority: 3;
975
- };
976
- readonly USDnr: {
977
- readonly chainId: 20994;
978
- readonly symbol: "USDnr";
979
- readonly name: "USDnr";
980
- readonly decimals: 6;
981
- readonly address: "0x279a6DC6354374473f6f3CFB3999e6C2e146f8a1";
982
- readonly gasPriority: 2;
983
- };
984
- readonly BLEND: {
985
- readonly chainId: 20994;
986
- readonly symbol: "BLEND";
987
- readonly name: "Mock Blend";
988
- readonly decimals: 18;
989
- readonly address: "0x83Fed707A8dDDC2535aE591CF19fB6C91D542D8E";
990
- readonly gasPriority: 1;
991
- };
992
- } | {
993
- readonly ETH: {
994
- readonly chainId: 25363;
995
- readonly symbol: "ETH";
996
- readonly name: "Ether";
997
- readonly decimals: 18;
998
- readonly native: true;
999
- readonly gasPriority: 3;
1000
- };
1001
- readonly USDnr: {
1002
- readonly chainId: 25363;
1003
- readonly symbol: "USDnr";
1004
- readonly name: "USDnr";
1005
- readonly decimals: 6;
1006
- readonly address: "0xD48e565561416dE59DA1050ED70b8d75e8eF28f9";
1007
- readonly gasPriority: 2;
1008
- };
1009
- readonly BLEND: {
1010
- readonly chainId: 25363;
1011
- readonly symbol: "BLEND";
1012
- readonly name: "Fluent";
1013
- readonly decimals: 18;
1014
- readonly address: "0x1385b8f55a84f2bda13eed4099d29eae03d553b2";
1015
- readonly gasPriority: 1;
1016
- };
1017
- };
1018
- declare function isFluentDefaultToken(token: Pick<FluentTokenDefinition, "chainId" | "address" | "native">): boolean;
1019
87
  /**
1020
- * The tokens in `tokens` that declare a `gasPriority`, cheapest priority first.
1021
- * The single spelling of "gas tokens, in order" — do not re-implement the
1022
- * filter and comparator elsewhere.
1023
- */
1024
- declare function sortFluentGasTokens<T extends FluentTokenDefinition>(tokens: readonly T[]): readonly T[];
1025
- declare function getFluentDefaultWidgetDisplayTokens(network: FluentNetworkName): readonly FluentTokenDefinition[];
1026
- declare function getFluentDefaultWidgetGasTokens(network: FluentNetworkName): readonly FluentTokenDefinition[];
1027
- declare function readFluentTokenBalances<TTransport extends Transport = Transport, TChain extends Chain = Chain>(params: {
1028
- client: PublicClient<TTransport, TChain>;
1029
- account: Address;
1030
- tokens: readonly FluentTokenDefinition[];
1031
- }): Promise<FluentTokenBalance[]>;
1032
-
1033
- type FluentTokenMetadataResult = {
1034
- status: "ok";
1035
- token: FluentTokenDefinition;
1036
- } | {
1037
- status: "invalid-address";
1038
- } | {
1039
- status: "unreadable";
1040
- reason: string;
1041
- };
1042
- /**
1043
- * Read a token's own account of itself from its contract.
88
+ * Looks up a Fluent chain by its EVM chain id, among the chains the registry knows: Fluent
89
+ * testnet (`20994`) and Fluent mainnet (`25363`).
1044
90
  *
1045
- * Never trust user-typed metadata: the address is the only input, everything
1046
- * else comes from the chain. `decimals` is mandatory — without it every balance
1047
- * we render would be off by an unknown power of ten — so a contract that fails
1048
- * to answer it is rejected rather than defaulted to 18.
91
+ * @param chainId The EVM chain id, as a wallet or `eth_chainId` reports it.
92
+ * @returns The chain's `FluentChainDefinition`, or `undefined` for any other chain id,
93
+ * an L1's included.
1049
94
  *
1050
- * Reads are issued individually rather than batched: the Fluent chains have no
1051
- * Multicall3 deployment configured, so `client.multicall` would throw.
1052
- */
1053
- declare function readFluentTokenMetadata<TTransport extends Transport = Transport, TChain extends Chain = Chain>(params: {
1054
- client: PublicClient<TTransport, TChain>;
1055
- address: string;
1056
- chainId: number;
1057
- }): Promise<FluentTokenMetadataResult>;
1058
-
1059
- /**
1060
- * Where a display token came from, ordered by how much we trust it. See
1061
- * docs/adr/0002-user-tokens-are-stored-locally-behind-an-interface.md.
1062
- */
1063
- type FluentTokenSource = "default" | "integrator" | "user";
1064
- type FluentDisplayToken = FluentTokenDefinition & {
1065
- source: FluentTokenSource;
1066
- /** `fluentTokenIdentity` for this token, computed once here. */
1067
- identity: string;
1068
- };
1069
- /**
1070
- * Combine the three token sources into the list the widget renders.
95
+ * @example
96
+ * ```ts
97
+ * import { getFluentChainByChainId } from "@fluent.xyz/connect";
1071
98
  *
1072
- * Duplicates are resolved by identity, never by symbol, and the more trusted
1073
- * source wins: a token a user added by hand is superseded once we ship it as
1074
- * one of ours, taking our name and logo with it. The user's stored record is only
1075
- * shadowed here — callers must not delete it, so that dropping a token from the
1076
- * default set brings their entry back rather than destroying it.
1077
- */
1078
- declare function mergeFluentDisplayTokens(params: {
1079
- defaults: readonly FluentTokenDefinition[];
1080
- integrator?: readonly FluentTokenDefinition[];
1081
- user?: readonly FluentTokenDefinition[];
1082
- }): FluentDisplayToken[];
1083
- /**
1084
- * Symbols in `tokens` that more than one token claims. The widget shows the
1085
- * address on every row regardless, but a collision is worth calling out loudly:
1086
- * it is the cheap way to pass a worthless token off as a valuable one.
99
+ * export const explorer = getFluentChainByChainId(20994)?.blockExplorers.default.url;
100
+ * ```
1087
101
  */
1088
- declare function findFluentSymbolCollisions(tokens: readonly FluentTokenDefinition[]): Set<string>;
1089
-
1090
- type FluentFamilyTier = "A" | "B" | "C" | "D";
1091
- type FluentFamilyType = "identity" | "tester" | "builder" | "influential" | "predictor";
1092
- type FluentFamily = {
1093
- tier: FluentFamilyTier;
1094
- metadata?: Record<string, string>;
1095
- lastUpdate?: string;
1096
- };
1097
- type FluentFamilies = {
1098
- xHandle?: string;
1099
- families: Record<FluentFamilyType, FluentFamily>;
1100
- };
1101
- type FluentFamiliesClientConfig = {
1102
- baseUrl: string;
1103
- fetch?: typeof globalThis.fetch;
1104
- };
1105
- type FluentFamiliesClient = {
1106
- getFamilies: (privyId: string) => Promise<FluentFamilies>;
1107
- };
1108
- declare function createFluentFamiliesClient(config: FluentFamiliesClientConfig): FluentFamiliesClient;
1109
-
1110
- declare function fluentDefinitionToViemChain(definition: FluentChainDefinition): Chain;
1111
- declare function l1DefinitionToViemChain(definition: L1ChainDefinition): Chain;
102
+ declare function getFluentChainByChainId(chainId: number): FluentChainDefinition | undefined;
1112
103
 
1113
104
  /** Fluent public testnet (chain id 20994) */
1114
105
  declare const fluentTestnet: viem.Chain;
1115
106
  /** Fluent mainnet (chain id 25363) */
1116
107
  declare const fluentMainnet: viem.Chain;
1117
- declare const fluent$1: {
1118
- readonly testnet: viem.Chain;
1119
- readonly mainnet: viem.Chain;
1120
- };
1121
-
1122
- type FluentNetwork = "testnet" | "mainnet";
1123
- type FluentInitializeConfig = {
1124
- network: FluentNetwork;
1125
- /**
1126
- * Advanced override for registered production apps.
1127
- * Default integrations should omit this and let Fluent derive app identity from origin.
1128
- */
1129
- clientId?: string;
1130
- /**
1131
- * Optional display hint for anonymous/basic mode.
1132
- * The Fluent Dashboard remains the source of truth for registered app metadata.
1133
- */
1134
- appName?: string;
1135
- scopes?: string[];
1136
- source?: string;
1137
- campaign?: string;
1138
- storage?: StorageLike;
1139
- origin?: string;
1140
- };
1141
- type FluentAppIdentity = {
1142
- mode: "origin" | "registered";
1143
- origin: string;
1144
- installationId: string;
1145
- clientId?: string;
1146
- appName?: string;
1147
- };
1148
- type FluentSession = {
1149
- app: FluentAppIdentity;
1150
- user: {
1151
- id: string;
1152
- email?: string;
1153
- };
1154
- wallet: {
1155
- smartAccountAddress?: `0x${string}`;
1156
- };
1157
- scopes: string[];
1158
- issuedAt: number;
1159
- idToken?: string;
1160
- };
1161
- type FluentConnectionStatus = {
1162
- status: "connected" | "disconnected";
1163
- network: FluentNetwork;
1164
- app: FluentAppIdentity;
1165
- session?: FluentSession;
1166
- };
1167
- type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
1168
- declare class FluentConnectSDK {
1169
- private config;
1170
- private app;
1171
- private session;
1172
- constructor(config: FluentInitializeConfig);
1173
- status(): FluentConnectionStatus;
1174
- setSession(session: Omit<FluentSession, "app"> & {
1175
- app?: FluentAppIdentity;
1176
- }): FluentSession;
1177
- disconnect(): FluentConnectionStatus;
1178
- private readStoredSession;
1179
- }
1180
- declare function initialize(config: FluentInitializeConfig): FluentConnectSDK;
1181
- declare const fluent: {
1182
- initialize: typeof initialize;
1183
- };
1184
108
 
109
+ /** Which of Fluent's two deployments the widget runs on. */
1185
110
  type FluentWidgetNetwork = "testnet" | "mainnet";
1186
- declare function isFaucetNetwork(network: FluentWidgetNetwork): network is "testnet";
111
+ /**
112
+ * The viem chain of a Network, for a host's own chain config.
113
+ *
114
+ * @example
115
+ * ```ts
116
+ * import { getFluentChainForNetwork } from "@fluent.xyz/connect";
117
+ *
118
+ * export const chain = getFluentChainForNetwork("mainnet"); // chain.id === 25363
119
+ * ```
120
+ */
1187
121
  declare function getFluentChainForNetwork(network: FluentWidgetNetwork): Chain;
1188
- declare function getFluentTokenDefaults(network: FluentWidgetNetwork): {
1189
- readonly ETH: {
1190
- readonly chainId: 20994;
1191
- readonly symbol: "ETH";
1192
- readonly name: "Ether";
1193
- readonly decimals: 18;
1194
- readonly native: true;
1195
- readonly gasPriority: 3;
1196
- };
1197
- readonly USDnr: {
1198
- readonly chainId: 20994;
1199
- readonly symbol: "USDnr";
1200
- readonly name: "USDnr";
1201
- readonly decimals: 6;
1202
- readonly address: "0x279a6DC6354374473f6f3CFB3999e6C2e146f8a1";
1203
- readonly gasPriority: 2;
1204
- };
1205
- readonly BLEND: {
1206
- readonly chainId: 20994;
1207
- readonly symbol: "BLEND";
1208
- readonly name: "Mock Blend";
1209
- readonly decimals: 18;
1210
- readonly address: "0x83Fed707A8dDDC2535aE591CF19fB6C91D542D8E";
1211
- readonly gasPriority: 1;
1212
- };
1213
- } | {
1214
- readonly ETH: {
1215
- readonly chainId: 25363;
1216
- readonly symbol: "ETH";
1217
- readonly name: "Ether";
1218
- readonly decimals: 18;
1219
- readonly native: true;
1220
- readonly gasPriority: 3;
1221
- };
1222
- readonly USDnr: {
1223
- readonly chainId: 25363;
1224
- readonly symbol: "USDnr";
1225
- readonly name: "USDnr";
1226
- readonly decimals: 6;
1227
- readonly address: "0xD48e565561416dE59DA1050ED70b8d75e8eF28f9";
1228
- readonly gasPriority: 2;
1229
- };
1230
- readonly BLEND: {
1231
- readonly chainId: 25363;
1232
- readonly symbol: "BLEND";
1233
- readonly name: "Fluent";
1234
- readonly decimals: 18;
1235
- readonly address: "0x1385b8f55a84f2bda13eed4099d29eae03d553b2";
1236
- readonly gasPriority: 1;
1237
- };
1238
- };
1239
- declare function getFluentExplorerBaseUrl(network: FluentWidgetNetwork): string | undefined;
1240
122
 
1241
123
  /**
1242
124
  * A symbol that can pay for gas. Deliberately `string`: which tokens are
@@ -1244,685 +126,255 @@ declare function getFluentExplorerBaseUrl(network: FluentWidgetNetwork): string
1244
126
  */
1245
127
  type FluentGasTokenSymbol = string;
1246
128
  /**
1247
- * What the widget charges gas to until the person chooses otherwise, and what
1248
- * a stored choice falls back to when it names no Gas token on this network.
1249
- */
1250
- declare const FLUENT_WIDGET_DEFAULT_GAS_TOKEN: FluentGasTokenSymbol;
1251
- declare function resolveDefaultGasToken(network: FluentWidgetNetwork, symbol?: string): FluentGasTokenSymbol;
1252
- /**
1253
- * Resolve a gas token symbol to its ERC-20 paymaster address on `network`.
1254
- * Returns `undefined` for the native currency, which pays gas directly, and for
1255
- * any symbol that is not a gas token on this network.
129
+ * What one unit of each Gas token is worth in ETH, as a decimal string, keyed by its
130
+ * `FluentGasTokenSymbol`.
1256
131
  *
1257
- * Matching is case-insensitive to agree with
1258
- * `resolveFluentZeroDevErc20PaymasterToken`, which uppercases its keys — the two
1259
- * feed the same approval call and must not disagree on `"usdnr"`.
132
+ * @experimental May change or be removed in a minor release while the defaults are measured;
133
+ * the defaults are the recommended setting.
1260
134
  */
1261
- declare function getFluentGasTokenAddress(symbol: FluentGasTokenSymbol, network: FluentWidgetNetwork): Address | undefined;
1262
- type FluentGasPaymentValueTier = "green" | "yellow" | "red" | "neutral" | "unknown";
1263
135
  type FluentGasPaymentEthRates = Partial<Record<FluentGasTokenSymbol, string>>;
1264
- declare const FLUENT_GAS_PAYMENT_DEFAULT_ETH_RATES: {
1265
- readonly ETH: "1";
1266
- };
1267
- type FluentGasPaymentSelection = {
1268
- status: "ready";
1269
- symbol: FluentGasTokenSymbol;
1270
- balance: FluentTokenBalance;
1271
- } | {
1272
- status: "bridge-required";
1273
- symbol: null;
1274
- balance: null;
1275
- } | {
1276
- status: "loading";
1277
- symbol: null;
1278
- balance: null;
1279
- };
1280
- declare function selectFluentGasPaymentToken(params: {
1281
- balances: readonly FluentTokenBalance[];
1282
- loading?: boolean;
1283
- }): FluentGasPaymentSelection;
136
+
1284
137
  /**
1285
- * Narrow a token list down to the gas tokens in it, in paymaster priority
1286
- * order. Only gas selection may use this — running the whole display list
1287
- * through it is what previously made the token list inextensible.
1288
- *
1289
- * `mergeFluentDisplayTokens` already strips `gasPriority` off untrusted
1290
- * sources, so the `isFluentDefaultToken` filter here is the safety net for a
1291
- * caller handed a raw list — an integrator prop, say — that never went through
1292
- * the merge. It stays because this list decides what the paymaster is asked to
1293
- * charge.
138
+ * Why an operation was not sponsored, and the `code` of a `FluentSponsorshipFallbackError`.
139
+ * `not_requested` is the only one that is not a failure: the caller asked to pay its own gas,
140
+ * so the sponsorship paymaster was never contacted. For the same reason it is never the error's
141
+ * code, which is thrown only after a sponsored attempt failed: the error carries one of the
142
+ * other four.
1294
143
  */
1295
- declare function getFluentGasPaymentTokens<T extends FluentTokenDefinition>(tokens: readonly T[]): readonly T[];
1296
- declare function getFluentGasPaymentEthValue(params: {
1297
- balance: FluentTokenBalance | undefined;
1298
- ethValueByToken?: FluentGasPaymentEthRates;
1299
- }): {
1300
- ethValueWei: null;
1301
- formatted: null;
1302
- tier: "unknown";
1303
- } | {
1304
- ethValueWei: bigint;
1305
- formatted: string;
1306
- tier: FluentGasPaymentValueTier;
1307
- };
144
+ type FluentSponsorshipReason = "no_token" | "denied" | "unauthorized" | "unreachable" | "not_requested";
1308
145
  /**
1309
- * ETH-value rates for `getFluentGasPaymentEthValue`, derived from the USD prices
1310
- * the widget already holds rather than from configuration.
146
+ * Both the sponsored submission and the fallback, the account paying its own gas, failed.
147
+ * `code` (equal to `sponsorshipReason`) says why Sponsorship was refused: `no_token`, `denied`,
148
+ * `unauthorized` or `unreachable`, never `not_requested`. `fallbackError` is what the own-gas
149
+ * submission failed with, and `cause` the sponsored submission's error.
150
+ *
151
+ * Neither is the error that was thrown. Each is a plain object `{ name, message, status? }`:
152
+ * `name` is the thrown error's name (`"Error"` for a thrown value that is not an `Error`),
153
+ * `message` the text of the innermost error along its `cause` chain that has any (an
154
+ * `AggregateError` gives the texts of its first four `errors`), and `status` the first integer
155
+ * `status` along that chain, such as an HTTP status, present only when there is one; the chain
156
+ * itself is not kept. A thrown value that cannot be read without an exception is summarized as
157
+ * `{ name: "Error", message: "[unreadable error]" }`.
1311
158
  *
1312
- * `gasPayment.ethValueByToken` is the App's to set and almost no App sets it,
1313
- * which left every "is this balance too small to pay a fee" question
1314
- * unanswerable for anything but ETH. The prices are per Token identity and the
1315
- * rates are per symbol, because that is what the two sides are keyed by.
1316
- * Anything the App did configure still wins: it is a deliberate override of
1317
- * exactly this guess.
159
+ * In `message`, here and in each of the two, a balanced `{…}` or `[…]` span becomes `[body]`, a
160
+ * `scheme://` URL `[url]`, a `Bearer` token or a JWT `[token]`, a `did:` id or a UUID `[id]`, an
161
+ * email address `[email]`, and `0x` with 40 or 64 hex digits `[address]` or `[hash]`. Any other
162
+ * `0x` run of 40 or more hex digits becomes `[data 0x…]` with its first four bytes, and the
163
+ * reason of an `Error(string)` revert is decoded and redacted in the same way.
1318
164
  */
1319
- declare function deriveFluentGasEthRates(params: {
1320
- tokens: readonly (FluentTokenDefinition & {
1321
- identity: string;
1322
- })[];
1323
- usdPrices: Readonly<Record<string, number>>;
1324
- configured?: FluentGasPaymentEthRates;
1325
- }): FluentGasPaymentEthRates;
1326
- declare function getFluentGasPaymentValueTier(ethValueWei: bigint): FluentGasPaymentValueTier;
165
+ declare class FluentSponsorshipFallbackError extends Error {
166
+ readonly code: FluentSponsorshipReason;
167
+ readonly sponsorshipReason: FluentSponsorshipReason;
168
+ readonly fallbackError: unknown;
169
+ constructor(params: {
170
+ sponsorshipReason: FluentSponsorshipReason;
171
+ /** The sponsored submission's error, retained as `cause` once summarized. */
172
+ sponsorshipError: unknown;
173
+ /** The own-gas submission's error, retained as `fallbackError` once summarized. */
174
+ fallbackError: unknown;
175
+ });
176
+ }
1327
177
 
1328
- declare const FLUENT_WIDGET_SESSION_STORAGE_KEY = "fluent:widget:session:v1";
1329
178
  /**
1330
- * Tokens the user added by hand, in the states where no Fluent token can exist:
1331
- * the not-connected state. Everywhere
1332
- * `getAuthToken()` resolves, the service holds the list per person and this key
1333
- * is not read (ADR 0004).
1334
- *
1335
- * Keyed per chain inside the payload, not per account: one person holds both a
1336
- * Fluent ID and possibly an external wallet and switches between them, and
1337
- * their list should not appear to vanish when they disconnect one.
179
+ * The signatures of the Widget API, for the Widget account. A Fluent ID shows the Review in
180
+ * Prompt mode and none in Silent mode; an External wallet always shows the Review, then its own
181
+ * prompt.
1338
182
  */
1339
- declare const FLUENT_WIDGET_USER_TOKENS_STORAGE_KEY = "fluent:widget:tokens:v1";
183
+ type FluentSignApi = {
184
+ /**
185
+ * EIP-191 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an
186
+ * External wallet.
187
+ *
188
+ * @throws `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person
189
+ * dismisses the Review: always shown for an External wallet, and for a Fluent ID unless Quick
190
+ * sign is on. An External wallet's refusal in its own prompt rejects with the wallet's error.
191
+ * @throws `FluentAuthError` with `code` `not_connected` when no Widget account is connected or
192
+ * the External wallet has no client, and `root_signer_required` when neither of the Fluent
193
+ * ID's signing paths signs with its root Signer, a guard no configuration reaches today.
194
+ *
195
+ * @example
196
+ * ```ts
197
+ * import { useFluentWidget } from "@fluent.xyz/connect";
198
+ *
199
+ * export function useSignGreeting() {
200
+ * const { widget } = useFluentWidget();
201
+ * return () => widget.signMessage({ message: "Sign in to Marketplace" });
202
+ * }
203
+ * ```
204
+ */
205
+ signMessage: (params: {
206
+ message: SignableMessage;
207
+ }) => Promise<Hex>;
208
+ /**
209
+ * EIP-712 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an
210
+ * External wallet.
211
+ *
212
+ * @throws `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person
213
+ * dismisses the Review, as for `signMessage`.
214
+ * @throws `FluentAuthError` with `code` `not_connected` or `root_signer_required`, as for
215
+ * `signMessage`.
216
+ *
217
+ * @example
218
+ * ```ts
219
+ * import { useFluentWidget } from "@fluent.xyz/connect";
220
+ *
221
+ * const verifyingContract = "0x0000000000000000000000000000000000000001";
222
+ * const order = { maker: "0x0000000000000000000000000000000000000002", price: 100n } as const;
223
+ *
224
+ * export function useSignOrder() {
225
+ * const { widget } = useFluentWidget();
226
+ * return () =>
227
+ * widget.signTypedData({
228
+ * domain: { name: "Marketplace", version: "1", chainId: 20994, verifyingContract },
229
+ * types: {
230
+ * Order: [
231
+ * { name: "maker", type: "address" },
232
+ * { name: "price", type: "uint256" },
233
+ * ],
234
+ * },
235
+ * primaryType: "Order",
236
+ * message: order,
237
+ * });
238
+ * }
239
+ * ```
240
+ */
241
+ signTypedData: <const typedData extends TypedData | Record<string, unknown>, primaryType extends keyof typedData | "EIP712Domain" = keyof typedData>(typedData: TypedDataDefinition<typedData, primaryType>) => Promise<Hex>;
242
+ };
243
+
1340
244
  /**
1341
- * Set while the one-time import of the local token list is in flight, and
1342
- * removed with the list itself once every entry is on the service. It is what
1343
- * tells a resumed import from a person who simply already had a list there.
245
+ * The account's own gas limits, all three fixed, for a `FluentUserOperationGas` that skips
246
+ * estimation.
1344
247
  *
1345
- * Its value is the subject whose import stopped halfway, not a flag: this key is
1346
- * per browser, and the next person to sign in here must not have another's
1347
- * leftovers pushed into their list (ADR 0004).
248
+ * @experimental May change or be removed in a minor release while the gas policy is measured;
249
+ * omitting it, which lets the widget estimate, is the recommended setting.
1348
250
  */
1349
- declare const FLUENT_WIDGET_USER_TOKENS_IMPORT_MARKER_KEY = "fluent:widget:tokens-import:v1";
1350
-
1351
- declare const FLUENT_CONNECT_DEFAULT_ASSETS: {
1352
- readonly fluentLogo: string;
1353
- readonly walletConnectIcon: string;
1354
- readonly metamaskIcon: string;
1355
- readonly coinbaseIcon: string;
1356
- };
1357
-
1358
- type FluentWidgetSession = FluentSession & {
1359
- appId?: string;
1360
- idToken: string;
1361
- wallet: Omit<FluentSession["wallet"], "smartAccountAddress"> & {
1362
- smartAccountAddress: `0x${string}`;
1363
- signerAddress?: `0x${string}`;
1364
- authorizationSession?: {
1365
- expiresAt: number;
1366
- serializedPermissionAccount: string;
1367
- sessionPrivateKey: `0x${string}`;
1368
- signerAddress: `0x${string}`;
1369
- };
1370
- };
1371
- expiresAt?: number;
1372
- metadata?: Record<string, string>;
251
+ type FluentFixedAccountGas = {
252
+ /** Whole-batch execution budget, including any Gas token approval. Positive uint128. */
253
+ callGasLimit: bigint;
254
+ /** Account validation and deployment budget. Positive uint128. */
255
+ verificationGasLimit: bigint;
256
+ /** Calldata overhead, or its ceiling with provider-owned paymaster gas. Positive uint256. */
257
+ preVerificationGas: bigint;
1373
258
  };
1374
259
  /**
1375
- * A sign-in method the sign-in dialog can offer beside X. X is not on this list:
1376
- * it is always offered and cannot be switched off.
260
+ * The paymaster's gas limits for a `FluentUserOperationGas` that skips estimation: both, or
261
+ * neither to use the limits the paymaster authorizes.
262
+ *
263
+ * @experimental May change or be removed in a minor release while the gas policy is measured;
264
+ * omitting it, which lets the widget estimate, is the recommended setting.
1377
265
  */
1378
- type FluentWidgetAuthMethod = "google" | "email" | "passkey";
266
+ type FluentFixedPaymasterGas = {
267
+ /** Fixed validation budget, a positive uint128. Omit both paymaster limits to use its answer. */
268
+ paymasterVerificationGasLimit?: bigint;
269
+ /** Fixed post-operation budget, a nonnegative uint128. Supplied together with validation. */
270
+ paymasterPostOpGasLimit?: bigint;
271
+ };
1379
272
  /**
1380
- * Which value in `FluentWidgetConfig` was refused, for a host that branches rather than reads
1381
- * the message.
273
+ * Gas policy for a Fluent ID batch. Estimation is enabled unless `skipEstimation` is true.
274
+ * Skipping requires account limits. Omit both paymaster limits to use provider-authorized
275
+ * paymaster gas and calldata overhead within `preVerificationGas`; supply both to fix all gas.
276
+ * The fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`.
277
+ *
278
+ * @experimental May change or be removed in a minor release while the gas policy is measured;
279
+ * omitting it, which lets the widget estimate, is the recommended setting.
1382
280
  */
1383
- type FluentWidgetConfigErrorCode = "invalid_fee_source" | "invalid_receipt_source" | "invalid_chain_check_before_sign";
281
+ type FluentUserOperationGas = (FluentFixedAccountGas & FluentFixedPaymasterGas & {
282
+ /** Skip the account gas hook and bundler gas estimation. Defaults to false. */
283
+ skipEstimation: true;
284
+ callGasBuffer?: never;
285
+ }) | {
286
+ skipEstimation?: false;
287
+ callGasLimit: bigint;
288
+ callGasBuffer?: never;
289
+ } | {
290
+ skipEstimation?: false;
291
+ callGasLimit?: never;
292
+ callGasBuffer: {
293
+ /** Extra percent of the bundler estimate, rounded up. Must be a nonnegative safe integer. */
294
+ percentage?: number;
295
+ /** Extra gas added after the percentage buffer. Must be nonnegative. */
296
+ fixed?: bigint;
297
+ };
298
+ };
1384
299
  /**
1385
- * A value in `FluentWidgetConfig` the widget refuses to start with.
300
+ * Reasons explicit gas preparation can fail before signing.
1386
301
  *
1387
- * Thrown by `resolveFluentWidgetConfig`, which every `<FluentWidget>` runs on its first
1388
- * render, so it surfaces at startup where the integrator is looking rather than at the first
1389
- * send. The message names the field and the values it accepts; `code` is what to branch on.
302
+ * @experimental May change or be removed in a minor release while the gas policy is measured;
303
+ * omitting it, which lets the widget estimate, is the recommended setting.
304
+ */
305
+ type FluentUserOperationGasErrorCode = "invalid_policy" | "paymaster_gas_mismatch";
306
+ /**
307
+ * An invalid skip-estimation policy or paymaster authorization for different gas limits.
308
+ * `code`, a `FluentUserOperationGasErrorCode`, identifies the failure; `message` names the
309
+ * option or gas field to correct.
1390
310
  *
1391
- * @example
1392
- * ```ts
1393
- * try {
1394
- * resolveFluentWidgetConfig(config);
1395
- * } catch (error) {
1396
- * if (error instanceof FluentWidgetConfigError && error.code === "invalid_fee_source") {
1397
- * // fix execution.feeSource
1398
- * }
1399
- * }
1400
- * ```
311
+ * @experimental May change or be removed in a minor release while the gas policy is measured;
312
+ * omitting it, which lets the widget estimate, is the recommended setting.
1401
313
  */
1402
- declare class FluentWidgetConfigError extends Error {
1403
- readonly code: FluentWidgetConfigErrorCode;
1404
- constructor(code: FluentWidgetConfigErrorCode, message: string);
314
+ declare class FluentUserOperationGasError extends Error {
315
+ readonly code: FluentUserOperationGasErrorCode;
316
+ constructor(code: FluentUserOperationGasErrorCode, message: string);
1405
317
  }
318
+
1406
319
  /**
1407
- * Where a smart-account send reads a value it could ask either side for: the widget chain's
1408
- * own RPC, or the ZeroDev bundler.
1409
- *
1410
- * @experimental May change or be removed in a minor release while the defaults are measured;
1411
- * the defaults are the recommended setting.
320
+ * One contract call of a Batch operation: either raw `data`, or an `abi` with the `method` to
321
+ * encode and its `args`.
1412
322
  */
1413
- type FluentWidgetExecutionSource = "chain" | "bundler";
323
+ type FluentBatchCallInput = {
324
+ id?: string;
325
+ label?: string;
326
+ to: Address;
327
+ /** Native ETH sent with the call, in wei. Defaults to `0n`. */
328
+ value?: bigint;
329
+ data?: Hex;
330
+ abi?: Abi;
331
+ /** The ABI function to encode, with `abi` and `args`, when `data` is not given. */
332
+ method?: string;
333
+ args?: readonly unknown[];
334
+ };
335
+ /** A Batch operation's call as it is sent: `data` encoded, `value` defaulted to `0n`. */
336
+ type FluentEncodedBatchCall = {
337
+ id?: string;
338
+ label?: string;
339
+ to: Address;
340
+ value: bigint;
341
+ data: Hex;
342
+ };
1414
343
  /**
1415
- * `FluentWidgetConfig.execution`, every field optional.
1416
- *
1417
- * @experimental May change or be removed in a minor release while the defaults are measured;
1418
- * the defaults are the recommended setting.
344
+ * Whether the Widget account can send now: `ready`, `disconnected`, `unavailable` (connected
345
+ * but not ready yet) or `error` (see `FluentWidgetAccount.executionError`).
1419
346
  */
1420
- type FluentWidgetExecution = {
1421
- /**
1422
- * Where the fees of a user operation come from. `chain` reads the widget chain's
1423
- * `eth_gasPrice` and caps `maxFeePerGas` 10 % above it; `bundler` takes ZeroDev's
1424
- * `zd_getUserOperationGasPrice` quote unchanged. Defaults to `chain`.
1425
- *
1426
- * @experimental May change or be removed in a minor release while the defaults are
1427
- * measured; the defaults are the recommended setting.
1428
- */
1429
- feeSource?: FluentWidgetExecutionSource;
1430
- /**
1431
- * Where inclusion is read from. `chain` polls the EntryPoint's `UserOperationEvent` with
1432
- * `eth_getLogs`; `bundler` polls `eth_getUserOperationReceipt`. Defaults to `chain`.
1433
- *
1434
- * @experimental May change or be removed in a minor release while the defaults are
1435
- * measured; the defaults are the recommended setting.
1436
- */
1437
- receiptSource?: FluentWidgetExecutionSource;
347
+ type FluentWidgetExecutionStatus = "disconnected" | "ready" | "unavailable" | "error";
348
+ /** How the connected account executes transactions. */
349
+ type FluentAccountType = "smart" | "eoa";
350
+ /** What the Widget account can do, so a host adapts its UI without branching on its type. */
351
+ type FluentAccountCapabilities = {
352
+ /** Multiple calls land in a single atomic transaction (smart account only). */
353
+ atomicBatch: boolean;
1438
354
  /**
1439
- * Whether the Signer's chain is read before every signature. The widget gives Privy its own
1440
- * chain as the only one, and the kernel checks the chain once when it is created, so the
1441
- * repeat costs a provider round trip per signature and switches nothing. Defaults to `false`.
1442
- *
1443
- * @experimental May change or be removed in a minor release while the defaults are
1444
- * measured; the defaults are the recommended setting.
355
+ * Gas can be paid in an ERC-20 (BLEND / USDnr) via the paymaster instead of
356
+ * native ETH — smart account only. This is NOT free/sponsored gas: the user
357
+ * still pays, just in a token.
1445
358
  */
1446
- chainCheckBeforeSign?: boolean;
359
+ erc20Gas: boolean;
1447
360
  };
1448
361
  /**
1449
- * `FluentWidgetExecution` with its defaults applied.
1450
- *
1451
- * @experimental May change or be removed in a minor release while the defaults are measured;
1452
- * the defaults are the recommended setting.
362
+ * The Widget account as the Widget API reports it: its address and type, whether it is
363
+ * connected and can send now, and what it can do.
1453
364
  */
1454
- type ResolvedFluentWidgetExecution = {
1455
- feeSource: FluentWidgetExecutionSource;
1456
- receiptSource: FluentWidgetExecutionSource;
1457
- chainCheckBeforeSign: boolean;
1458
- };
1459
- type FluentWidgetConfig = {
1460
- /** The App's id (`app_<32 hex>`) — the same string the Fluent Dashboard shows and the token's `aud` carries. */
1461
- appId: string;
1462
- /**
1463
- * The Privy app client issued by Fluent for this App. Login configuration, not
1464
- * identity: it carries the allowed origins for Privy login, while `appId` is what
1465
- * sponsorship, auth and analytics speak.
1466
- */
1467
- privyClientId: string;
1468
- /** Removed in 0.2.0 — the type exists only so the error names the fix. */
1469
- clientId?: never;
1470
- /** Renamed to `appId` in 0.3.0 — the type exists only so the error names the fix. */
1471
- partnerId?: never;
1472
- network?: FluentWidgetNetwork;
1473
- appName?: string;
1474
- /**
1475
- * HTTPS callback for the widget's Privy OAuth flows. Capacitor apps must use a
1476
- * Universal Link registered in Privy and handle its return in the host app.
1477
- * Omit to keep Privy's current-page redirect.
1478
- */
1479
- customOAuthRedirectUrl?: string;
1480
- /**
1481
- * Sign-in methods the sign-in dialog offers beside X, in the order given.
1482
- * Defaults to `["google", "email", "passkey"]` — all of them; name a shorter
1483
- * set to drop the rest, or `[]` to leave X as the only Fluent method.
1484
- * Sign-in with X is always offered and is not a value here.
1485
- *
1486
- * A method still has to be enabled on the shared Privy app — listing it here only
1487
- * decides whether its button is drawn.
1488
- */
1489
- enabledAuthMethods?: FluentWidgetAuthMethod[];
1490
- swapper?: {
1491
- enabled?: boolean;
1492
- integratorId?: string;
1493
- dstChainId?: string;
1494
- dstTokenAddress?: string;
1495
- };
1496
- gasPayment?: {
1497
- /** Initial/fallback token. Defaults to ETH; a valid saved user choice wins. */
1498
- defaultToken?: FluentGasTokenSymbol;
1499
- /** Native-gas sponsorship policy. Defaults to `auto`; `never` skips the paymaster. */
1500
- sponsorship?: "auto" | "never";
1501
- ethValueByToken?: FluentGasPaymentEthRates;
1502
- };
1503
- /**
1504
- * How a smart-account send is executed. Every field defaults to the fast path, which falls
1505
- * back to ZeroDev on its own: set a field to switch that one answer back to ZeroDev for good.
1506
- *
1507
- * @experimental May change or be removed in a minor release while the defaults are
1508
- * measured; the defaults are the recommended setting.
1509
- */
1510
- execution?: FluentWidgetExecution;
1511
- quickSign?: {
1512
- /**
1513
- * Call targets Quick sign may execute without the review. With a list set, a batch
1514
- * operation runs silently only when every call's `to` is on it; a single call to any
1515
- * other address shows the review and the signer prompt, even with Quick sign on. An
1516
- * empty list is honoured and stops Quick sign from silencing anything; omit the
1517
- * option to keep it covering every address. Compared case-insensitively.
1518
- * `signMessage` / `signTypedData` have no call target and are not scoped by this.
1519
- */
1520
- whitelistAddresses?: readonly string[];
1521
- };
1522
- /**
1523
- * `false` drops the Reputation tab from the account drawer — and with it the
1524
- * whole tab strip, since Home is then the only tab. The families request is
1525
- * never made. Default `true`.
1526
- */
1527
- reputationEnabled?: boolean;
1528
- scopes?: string[];
1529
- source?: string;
1530
- campaign?: string;
1531
- /** Turns off all analytics: PostHog is never initialised, nothing is sent or stored. */
1532
- disableAnalytics?: boolean;
1533
- /** Restore injected wallets and WalletConnect by default; true restores all, false restores none. */
1534
- reconnectOnMount?: boolean;
1535
- /**
1536
- * Point the widget at a sponsorship service other than the network default. Local
1537
- * development only: the deployed URL is the one every real integration should use.
1538
- */
1539
- sponsorshipUrl?: string;
1540
- /**
1541
- * `getAuthToken()` reuses a token until this many seconds before its `exp`, then fetches a
1542
- * fresh one (the renewal-offset pattern: MSAL's `tokenRenewalOffsetSeconds`, Go oauth2's
1543
- * `expiryDelta`). Default 30. Set 0 to drop the margin entirely: a token is then reused
1544
- * until `exp` itself, which is not the same as always fetching — it is the case the margin
1545
- * exists for, a token handed out a moment before it expires and rejected by the backend it
1546
- * is sent to.
1547
- */
1548
- authTokenRenewalOffsetSeconds?: number;
1549
- assets?: Partial<typeof FLUENT_CONNECT_DEFAULT_ASSETS>;
1550
- /** The account avatar shown on the connect button and in the account drawer. */
1551
- avatar?: {
1552
- /**
1553
- * Image used when there is no X avatar to show — a URL or a data URI.
1554
- * Defaults to the Fluent mark.
1555
- */
1556
- defaultLogoUrl?: string;
1557
- /**
1558
- * Always show `defaultLogoUrl`, even for users who signed in with X.
1559
- * Default `false` (the X avatar wins when Privy has one).
1560
- */
1561
- forceDefault?: boolean;
1562
- };
1563
- };
1564
- type ResolvedFluentWidgetConfig = {
1565
- appId: string;
1566
- privyClientId: string;
1567
- network: FluentWidgetNetwork;
1568
- appName: string;
1569
- customOAuthRedirectUrl: string | undefined;
1570
- /** What the dialog shows beside X, defaults applied. */
1571
- authMethods: FluentWidgetAuthMethod[];
1572
- faucetEndpoint: string;
1573
- eventsEndpoint: string;
1574
- analyticsHost: string;
1575
- sponsorshipUrl: string;
1576
- authTokenRenewalOffsetSeconds: number;
1577
- disableAnalytics: boolean;
1578
- reconnectOnMount: boolean | undefined;
1579
- publicApiUrl: string;
1580
- reputationSignupUrl: string;
1581
- bridgeUrl: string;
1582
- swapper: {
1583
- enabled: boolean;
1584
- integratorId: string;
1585
- dstChainId: string;
1586
- dstTokenAddress: string;
1587
- };
1588
- gasPayment: {
1589
- defaultToken: FluentGasTokenSymbol;
1590
- sponsorship: "auto" | "never";
1591
- ethValueByToken: FluentGasPaymentEthRates | undefined;
1592
- };
1593
- execution: ResolvedFluentWidgetExecution;
1594
- quickSign: {
1595
- /** Lowercased and deduplicated; `undefined` leaves Quick sign covering every address. */
1596
- whitelistAddresses: readonly Address[] | undefined;
1597
- };
1598
- reputationEnabled: boolean;
1599
- scopes: string[];
1600
- source: string;
1601
- campaign: string | undefined;
1602
- assets: typeof FLUENT_CONNECT_DEFAULT_ASSETS & Partial<typeof FLUENT_CONNECT_DEFAULT_ASSETS>;
1603
- avatar: {
1604
- defaultLogoUrl: string | undefined;
1605
- forceDefault: boolean;
1606
- };
1607
- };
1608
-
1609
- declare function normalizeFluentWidgetNetwork(value: string | undefined): FluentWidgetNetwork | undefined;
1610
- /** Reads `VITE_FLUENT_WIDGET_NETWORK` / `FLUENT_NETWORK` (`testnet`, `mainnet`, `dev`, `prod`, …). */
1611
- declare function resolveFluentWidgetNetworkFromEnv(): FluentWidgetNetwork | undefined;
1612
-
1613
- type FluentWidgetNetworkContextValue = {
1614
- network: FluentWidgetNetwork;
1615
- chain: Chain;
1616
- };
1617
- declare function FluentWidgetNetworkProvider({ network, children, }: {
1618
- network: FluentWidgetNetwork;
1619
- children: ReactNode;
1620
- }): React.JSX.Element;
1621
- declare function useFluentWidgetNetwork(): FluentWidgetNetworkContextValue;
1622
-
1623
- /** Why an operation was not sponsored, when sponsorship was configured for it. */
1624
- /**
1625
- * Why an operation was not sponsored. `not_requested` is the only one that is not a failure:
1626
- * the caller asked to pay its own gas, so the sponsorship paymaster was never contacted.
1627
- */
1628
- type FluentSponsorshipReason = "no_token" | "denied" | "unauthorized" | "unreachable" | "not_requested";
1629
- /** Both sponsored submission and the account-paid fallback failed. */
1630
- declare class FluentSponsorshipFallbackError extends Error {
1631
- readonly sponsorshipReason: FluentSponsorshipReason;
1632
- readonly fallbackError: unknown;
1633
- constructor(params: {
1634
- sponsorshipReason: FluentSponsorshipReason;
1635
- /** The original sponsored submission error, retained as `cause`. */
1636
- sponsorshipError: unknown;
1637
- fallbackError: unknown;
1638
- });
1639
- }
1640
-
1641
- /** How a sponsored operation asks for its Fluent token. `fresh` discards a rejected one first. */
1642
- type SponsorshipTokenRequest = (options?: {
1643
- fresh?: boolean;
1644
- }) => Promise<string>;
1645
-
1646
- type KernelAccount = Awaited<ReturnType<typeof createKernelAccount>>;
1647
- type KernelClient = ReturnType<typeof createKernelAccountClient>;
1648
- /**
1649
- * Where a sponsored operation gets its bearer: the Fluent token for the connected account, and
1650
- * which kind of account that is. Read at send time through a function rather than taken as a
1651
- * value, because `useFluentZeroDevAccount` is constructed before the widget has derived the
1652
- * account or built its `getAuthToken()`, and reordering the widget would change when the kernel
1653
- * initializes.
1654
- */
1655
- type FluentZeroDevSponsorshipTokenSource = {
1656
- accountType: FluentAccountType | undefined;
1657
- getAuthToken: SponsorshipTokenRequest;
1658
- };
1659
- type FluentZeroDevSignerMode = "prompt" | "silent";
1660
- type FluentZeroDevCall = {
1661
- to: Address;
1662
- data?: Hex;
1663
- value?: bigint;
1664
- };
1665
- type FluentZeroDevKernel = {
1666
- account: KernelAccount;
1667
- client: KernelClient;
1668
- publicClient: ReturnType<typeof createPublicClient>;
1669
- smartAccountAddress: Address;
1670
- zeroDevRpcUrl: string;
1671
- chain: Chain;
1672
- signerMode: FluentZeroDevSignerMode;
1673
- signerSource: "privy" | "session";
1674
- };
1675
- type FluentZeroDevPermissionSession = {
1676
- serializedPermissionAccount: string;
1677
- sessionSignerAddress: Address;
1678
- smartAccountAddress: Address;
1679
- };
1680
- type FluentZeroDevPermissionCall = {
1681
- target: Address;
1682
- selector?: Hex;
1683
- abi?: Abi;
1684
- functionName?: string;
1685
- args?: readonly unknown[];
1686
- valueLimit?: bigint;
1687
- callType?: CallType;
1688
- };
1689
- declare function useFluentZeroDevAccount(hookOptions?: {
1690
- /** App id in the sponsorship path. Sponsorship is off unless both this and the URL are set. */
1691
- appId?: string;
1692
- sponsorshipUrl?: string;
1693
- /** The Fluent token a sponsored operation authenticates with. Without it nothing is sponsored. */
1694
- sponsorshipTokenSource?: () => FluentZeroDevSponsorshipTokenSource | null;
1695
- authorizationSession?: {
1696
- expiresAt: number;
1697
- serializedPermissionAccount: string;
1698
- sessionPrivateKey: Hex;
1699
- };
1700
- sessionSignerAddress?: Address;
1701
- sessionSmartAccountAddress?: Address;
1702
- /**
1703
- * Where a send reads its fees and its receipt, and whether the Signer's chain is read before
1704
- * every signature. Omitted, the defaults of `FLUENT_CONNECT_DEFAULT_EXECUTION` apply.
1705
- */
1706
- execution?: ResolvedFluentWidgetExecution;
1707
- /** Prefer over Privy's login when the host needs to remount Privy first. */
1708
- login?: () => void;
1709
- }): {
1710
- smartAccountEnabled: boolean;
1711
- smartAccountReady: boolean;
1712
- smartAccountAddress: `0x${string}` | undefined;
1713
- signerAddress: `0x${string}` | undefined;
1714
- privyReady: boolean;
1715
- privyAuthenticated: boolean;
1716
- embeddedWalletCount: number;
1717
- authenticate: (options?: web.LoginModalOptions | React.MouseEvent<any, any>) => void;
1718
- kernel: FluentZeroDevKernel | null;
1719
- signerModesReady: FluentZeroDevSignerMode[];
1720
- error: Error | null;
1721
- ensureExecutionReady: (options?: {
1722
- confirmation?: "always" | "session";
1723
- }) => Promise<FluentZeroDevKernel>;
1724
- sendTransaction: (request: {
1725
- to: Address;
1726
- data?: Hex;
1727
- value?: bigint;
1728
- }) => Promise<Hash>;
1729
- sendCalls: (calls: FluentZeroDevCall[], options?: FluentBatchOperationExecuteOptions, readyAccount?: unknown) => Promise<{
1730
- hash: Hash;
1731
- receipt: TransactionReceipt;
1732
- userOpHash: Hash;
1733
- sponsored: boolean;
1734
- sponsorshipReason?: FluentSponsorshipReason;
1735
- paymaster?: Address;
1736
- /** Where this send's milliseconds went. Absent only when the measurement itself failed. */
1737
- timing?: FluentExecuteTiming;
1738
- }>;
1739
- refresh: () => Promise<FluentZeroDevKernel | null>;
1740
- };
1741
- declare function createFluentZeroDevPermissionSession(params: {
1742
- kernel: FluentZeroDevKernel;
1743
- sessionPrivateKey: Hex;
1744
- calls: readonly FluentZeroDevPermissionCall[];
1745
- expiresAt?: number;
1746
- }): Promise<FluentZeroDevPermissionSession>;
1747
-
1748
- type FluentPermissionArgConstraint = {
1749
- equals: unknown;
1750
- } | {
1751
- max: unknown;
1752
- } | {
1753
- min: unknown;
1754
- };
1755
- type FluentPermissionArgs = readonly (FluentPermissionArgConstraint | null | undefined)[] | Record<string, FluentPermissionArgConstraint | null | undefined>;
1756
- type FluentPermissionCallInput = {
1757
- id?: string;
1758
- to: Address;
1759
- abi: Abi;
1760
- method?: string;
1761
- functionName?: string;
1762
- args?: FluentPermissionArgs;
1763
- valueLimit?: bigint;
1764
- };
1765
- type FluentPermissionCallPolicy = {
1766
- kind: "call";
1767
- id?: string;
1768
- call: FluentPermissionCallInput;
1769
- };
1770
- type FluentPermissionBatchPolicy = {
1771
- kind: "batch";
1772
- id?: string;
1773
- calls: readonly FluentPermissionCallInput[];
1774
- };
1775
- type FluentPermissionBatchPolicyInput = {
1776
- id?: string;
1777
- calls: readonly FluentPermissionCallInput[];
1778
- };
1779
- type FluentPermissionPolicy = FluentPermissionCallPolicy | FluentPermissionBatchPolicy;
1780
- type FluentPermissionSessionInput = {
1781
- label?: string;
1782
- delegate?: Address;
1783
- expiresAt?: Date | number;
1784
- sessionPrivateKey?: Hex;
1785
- policies: readonly FluentPermissionPolicy[];
1786
- };
1787
- type FluentPermissionSession = FluentZeroDevPermissionSession & {
1788
- label?: string;
1789
- delegate?: Address;
1790
- expiresAt?: number;
1791
- policies: readonly FluentPermissionPolicy[];
1792
- };
1793
- type FluentPermissionPolicyBuilders = {
1794
- call: (input: FluentPermissionCallInput) => FluentPermissionCallPolicy;
1795
- batch: (input: FluentPermissionBatchPolicyInput) => FluentPermissionBatchPolicy;
1796
- };
1797
- type FluentPermissionApi = {
1798
- createPermissionSession: (input: FluentPermissionSessionInput) => Promise<FluentPermissionSession>;
1799
- policies: FluentPermissionPolicyBuilders;
1800
- };
1801
- type FluentPermissionSessionExecutor = {
1802
- kernel: FluentZeroDevKernel | null;
1803
- smartAccountReady?: boolean;
1804
- };
1805
- declare function createFluentPermissionApi(executor?: FluentPermissionSessionExecutor | null): FluentPermissionApi;
1806
- declare function createFluentPermissionPolicyBuilders(): FluentPermissionPolicyBuilders;
1807
- declare function createFluentPermissionSession(input: FluentPermissionSessionInput, executor?: FluentPermissionSessionExecutor | null): Promise<FluentPermissionSession>;
1808
-
1809
- /**
1810
- * A typed-data request with its generics erased: what the review shows and what the
1811
- * signer receives. `signTypedData` on the public API keeps viem's generic signature so
1812
- * hosts get their `types` checked; the erasure happens once, at the API boundary.
1813
- */
1814
- type FluentTypedDataRequest = TypedDataDefinition<TypedData | Record<string, unknown>, string>;
1815
- /**
1816
- * What the user reviews before a signature is produced. `origin` is the page asking,
1817
- * which is the one fact a signature request cannot be trusted to state about itself;
1818
- * `address` is the account the signature will be for.
1819
- */
1820
- type FluentSignatureReview = {
1821
- origin: string;
1822
- account: FluentWidgetAccount;
1823
- address: Address;
1824
- } & ({
1825
- kind: "message";
1826
- message: SignableMessage;
1827
- } | {
1828
- kind: "typedData";
1829
- typedData: FluentTypedDataRequest;
1830
- });
1831
- type FluentSignApi = {
1832
- /** EIP-191 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an External wallet. */
1833
- signMessage: (params: {
1834
- message: SignableMessage;
1835
- }) => Promise<Hex>;
1836
- /** EIP-712 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an External wallet. */
1837
- signTypedData: <const typedData extends TypedData | Record<string, unknown>, primaryType extends keyof typedData | "EIP712Domain" = keyof typedData>(typedData: TypedDataDefinition<typedData, primaryType>) => Promise<Hex>;
1838
- };
1839
-
1840
- type FixedAccountGas = {
1841
- /** Whole-batch execution budget, including any Gas token approval. Positive uint128. */
1842
- callGasLimit: bigint;
1843
- /** Account validation and deployment budget. Positive uint128. */
1844
- verificationGasLimit: bigint;
1845
- /** Calldata overhead, or its ceiling with provider-owned paymaster gas. Positive uint256. */
1846
- preVerificationGas: bigint;
1847
- };
1848
- type FixedPaymasterGas = {
1849
- /** Fixed validation budget, a positive uint128. Omit both paymaster limits to use its answer. */
1850
- paymasterVerificationGasLimit?: bigint;
1851
- /** Fixed post-operation budget, a nonnegative uint128. Supplied together with validation. */
1852
- paymasterPostOpGasLimit?: bigint;
1853
- };
1854
- /**
1855
- * Gas policy for a Fluent ID batch. Estimation is enabled unless `skipEstimation` is true.
1856
- * Skipping requires account limits. Omit both paymaster limits to use provider-authorized
1857
- * paymaster gas and calldata overhead within `preVerificationGas`; supply both to fix all gas.
1858
- */
1859
- type FluentUserOperationGas = (FixedAccountGas & FixedPaymasterGas & {
1860
- /** Skip the account gas hook and bundler gas estimation. Defaults to false. */
1861
- skipEstimation: true;
1862
- callGasBuffer?: never;
1863
- }) | {
1864
- skipEstimation?: false;
1865
- callGasLimit: bigint;
1866
- callGasBuffer?: never;
1867
- } | {
1868
- skipEstimation?: false;
1869
- callGasLimit?: never;
1870
- callGasBuffer: {
1871
- /** Extra percent of the bundler estimate, rounded up. Must be a nonnegative safe integer. */
1872
- percentage?: number;
1873
- /** Extra gas added after the percentage buffer. Must be nonnegative. */
1874
- fixed?: bigint;
1875
- };
1876
- };
1877
- /** Reasons explicit gas preparation can fail before signing. */
1878
- type FluentUserOperationGasErrorCode = "invalid_policy" | "paymaster_gas_mismatch";
1879
- /**
1880
- * An invalid skip-estimation policy or paymaster authorization for different gas limits.
1881
- * `code` identifies the failure; `message` names the option or gas field to correct.
1882
- */
1883
- declare class FluentUserOperationGasError extends Error {
1884
- readonly code: FluentUserOperationGasErrorCode;
1885
- constructor(code: FluentUserOperationGasErrorCode, message: string);
1886
- }
1887
-
1888
- type FluentBatchCallInput = {
1889
- id?: string;
1890
- label?: string;
1891
- to: Address;
1892
- value?: bigint;
1893
- data?: Hex;
1894
- abi?: Abi;
1895
- method?: string;
1896
- functionName?: string;
1897
- args?: readonly unknown[];
1898
- };
1899
- type FluentEncodedBatchCall = {
1900
- id?: string;
1901
- label?: string;
1902
- to: Address;
1903
- value: bigint;
1904
- data: Hex;
1905
- };
1906
- type FluentWidgetExecutionStatus = "disconnected" | "ready" | "unavailable" | "error";
1907
- /** How the connected account executes transactions. */
1908
- type FluentAccountType = "smart" | "eoa";
1909
- type FluentAccountCapabilities = {
1910
- /** Multiple calls land in a single atomic transaction (smart account only). */
1911
- atomicBatch: boolean;
1912
- /**
1913
- * Gas can be paid in an ERC-20 (BLEND / USDnr) via the paymaster instead of
1914
- * native ETH — smart account only. This is NOT free/sponsored gas: the user
1915
- * still pays, just in a token. Without an ERC-20 selection the smart account
1916
- * pays gas in native ETH from its own balance.
1917
- */
1918
- erc20Gas: boolean;
1919
- };
1920
365
  type FluentWidgetAccount = {
366
+ /** The Widget account's address: the Fluent ID's, or the External wallet's. */
1921
367
  address?: Address;
1922
- signerAddress?: Address;
368
+ /** Whether a Widget account, a Fluent ID or an External wallet, is connected. */
1923
369
  connected: boolean;
370
+ /** Whether the Widget account can send now; `executionStatus` says why it cannot. */
1924
371
  executionReady: boolean;
372
+ /** Where sending stands, a `FluentWidgetExecutionStatus`. */
1925
373
  executionStatus: FluentWidgetExecutionStatus;
374
+ /**
375
+ * The message of the last failure to prepare the Fluent ID's account, if any: the reason an
376
+ * `executionStatus` of `"error"` gives.
377
+ */
1926
378
  executionError?: string;
1927
379
  /** Active account kind, or undefined when nothing is connected. */
1928
380
  type?: FluentAccountType;
@@ -1933,6 +385,8 @@ type FluentWidgetAccount = {
1933
385
  * Absolute instants behind `FluentExecuteTiming`, kept so its signed estimates can be
1934
386
  * re-checked rather than believed. Epoch milliseconds (`Date.now()`), because the only other
1935
387
  * clock in the arithmetic — the including block's `timestamp` — is a wall clock too.
388
+ *
389
+ * @experimental May change or be removed in a minor release while the numbers are measured.
1936
390
  */
1937
391
  type FluentExecuteTimingInstants = {
1938
392
  /** When the first submission attempt of this send began. */
@@ -1961,13 +415,15 @@ type FluentExecuteTimingInstants = {
1961
415
  * so the subtraction can be redone by whoever doubts it.
1962
416
  *
1963
417
  * `totalMs` is measured, not summed: it runs from the start of the first submission to the
1964
- * instant the receipt was in hand, and excludes both the kernel and authentication setup before
1965
- * the send and the block read after it. It does not equal the sum of the stages and must not be
1966
- * displayed as if it did.
418
+ * instant the receipt was in hand, and excludes both the smart-account and authentication setup
419
+ * before the send and the block read after it. It does not equal the sum of the stages and must
420
+ * not be displayed as if it did.
1967
421
  *
1968
422
  * Collected for every send, whatever `debugLogging` is set to — the numbers are the answer to
1969
423
  * "where did the four seconds go", which is a question a host asks in production. A failure
1970
424
  * inside the measuring code costs the stages it could not establish, never the send.
425
+ *
426
+ * @experimental May change or be removed in a minor release while the numbers are measured.
1971
427
  */
1972
428
  type FluentExecuteTiming = {
1973
429
  /**
@@ -2015,74 +471,62 @@ type FluentExecuteResult = {
2015
471
  /** True when all calls landed atomically (smart account), false for sequential EOA txs. */
2016
472
  atomic: boolean;
2017
473
  /**
2018
- * True when an App's sponsorship paid the gas for this operation. Read back off the
2019
- * settled UserOperation (which contract the EntryPoint charged), not from which client
2020
- * we chose to send with: a refusal in the sponsorship proxy is a flat 403 and the
2021
- * account silently pays its own gas, so an optimistic flag would report the failure
2022
- * mode as a success. Always false for the EOA path, which has no paymaster.
474
+ * Whether the App's Sponsorship paid the gas for this operation, read back off the settled
475
+ * operation (which contract the EntryPoint charged) first: a refused Sponsorship falls back
476
+ * to the account paying its own gas, so a flag set from asking for Sponsorship would report
477
+ * the fallback as a success. `false` for a Gas token payment and always for an External
478
+ * wallet, which has no paymaster. When a Fluent ID's receipt names no paymaster, the way the
479
+ * operation was sent decides: `false` when it made no sponsored submission (the fallback,
480
+ * `sponsorship: "never"`, Sponsorship unavailable or not configured), and `null` after a
481
+ * sponsored submission, where nothing says who paid.
2023
482
  */
2024
- sponsored: boolean;
483
+ sponsored: boolean | null;
2025
484
  /**
2026
- * The paymaster that actually paid, zero address when the account paid itself.
2027
- * Undefined when the bundler's receipt carried no paymaster field and no
2028
- * `UserOperationEvent` could be decoded — i.e. `sponsored` is a guess, say so.
485
+ * The paymaster a Fluent ID's receipt names: the Sponsorship paymaster or a Gas token's
486
+ * paymaster, when one paid. Undefined when the receipt carried no paymaster — `sponsored` is
487
+ * then `false`, or `null` after a sponsored submission — and always for an External wallet,
488
+ * which has no paymaster.
489
+ *
490
+ * @experimental May change or be removed in a minor release while the numbers are measured.
2029
491
  */
2030
492
  paymaster?: Address;
2031
493
  /**
2032
- * Where this send's milliseconds went. Smart-account path only: an external wallet performs
2033
- * its prompt, its signing and its broadcast behind one `sendTransaction` await, so EIP-1193
2034
- * exposes no truthful instant to put a boundary on.
494
+ * Where this send's milliseconds went, as a `FluentExecuteTiming` whose raw instants are a
495
+ * `FluentExecuteTimingInstants`. Fluent ID only: an External wallet performs its prompt, its
496
+ * signing and its broadcast behind one `sendTransaction` await, so EIP-1193 exposes no
497
+ * truthful instant to put a boundary on.
498
+ *
499
+ * @experimental May change or be removed in a minor release while the numbers are measured.
2035
500
  */
2036
501
  timing?: FluentExecuteTiming;
2037
502
  };
503
+ /** The Gas payment chosen in the widget: the Gas token's symbol, its address and decimals. */
2038
504
  type FluentWidgetGasPayment = {
2039
505
  symbol: FluentGasTokenSymbol;
2040
506
  token?: Address;
2041
507
  decimals: number;
2042
508
  };
509
+ /** What `widget.createBatchOp` takes: the calls of one Batch operation, and its Review title. */
2043
510
  type FluentBatchOperationInput = {
2044
511
  id?: string;
2045
- /** Heading shown in the Fluent transaction-review modal (smart account, confirmation "always"). Defaults to "Confirm transaction". */
512
+ /**
513
+ * Heading of this Batch operation's Review (Fluent ID, Prompt mode). Defaults to the
514
+ * widget's own copy, "Confirm transaction".
515
+ */
2046
516
  reviewTitle?: string;
2047
517
  calls: readonly FluentBatchCallInput[];
2048
518
  };
2049
- type FluentBatchOperationExecutor = {
2050
- smartAccountReady?: boolean;
2051
- account?: FluentWidgetAccount;
2052
- ensureReady?: (options: FluentBatchOperationExecuteOptions) => Promise<unknown>;
2053
- defaultConfirmation?: FluentBatchConfirmationMode;
2054
- /**
2055
- * Gas token selected in the widget UI. Used as the default when `execute` is
2056
- * called without an explicit `gasPayment`, so the in-widget selector actually
2057
- * drives which token pays for gas. Native-gas selections (no `token`) fall
2058
- * back to native gas (no ERC20 paymaster).
2059
- */
2060
- defaultGasPayment?: FluentWidgetGasPayment;
2061
- /** Native-gas policy inherited from widget config; each execution may override it. */
2062
- defaultSponsorship?: "auto" | "never";
2063
- /**
2064
- * Call targets Quick sign may skip the review for, compared case-insensitively.
2065
- * Set, it caps every `"session"` confirmation — the widget default and an explicit
2066
- * per-execute option alike, because it is the host's guardrail and a per-call option
2067
- * must not be able to lift it: an operation with any call outside the list reviews
2068
- * and signs as `"always"`. Undefined leaves Quick sign covering every address.
2069
- */
2070
- quickSignWhitelist?: readonly Address[];
2071
- confirm?: (operation: FluentBatchOperationReview) => Promise<void>;
2072
- /**
2073
- * `readyAccount` is whatever `ensureReady` resolved with for this execution, and is
2074
- * `undefined` when the executor was already ready and `ensureReady` never ran.
2075
- *
2076
- * It is passed because an executor assembled inside a React render — which is every
2077
- * executor the widget builds — closes over the readiness state of that render, and
2078
- * `ensureReady` resolving does not re-render it: in the tick after the account becomes
2079
- * ready, `sendCalls` still sees "not ready" and has no way to reach the account that
2080
- * now exists. This argument is that way. An executor whose readiness is not captured in
2081
- * a closure can ignore it.
2082
- */
2083
- sendCalls: (calls: FluentEncodedBatchCall[], options: FluentBatchOperationExecuteOptions, readyAccount?: unknown) => Promise<FluentExecuteResult>;
2084
- };
2085
- type FluentBatchConfirmationMode = "always" | "session";
519
+ /**
520
+ * How a Fluent ID signs: `"prompt"` shows the widget's Review first (Prompt mode), `"silent"`
521
+ * signs with none (Silent mode), except that where the App set `quickSign.whitelistAddresses`, a
522
+ * Batch operation with a call outside it is signed as `"prompt"`. An External wallet always
523
+ * shows its own prompt.
524
+ */
525
+ type FluentSigningMode = "prompt" | "silent";
526
+ /**
527
+ * How one operation's gas is paid: a Gas token by symbol, or native ETH, and whether
528
+ * Sponsorship is asked for.
529
+ */
2086
530
  type FluentGasPayment = {
2087
531
  /**
2088
532
  * Gas token symbol. The widget resolves the ERC-20 address for the active
@@ -2093,15 +537,12 @@ type FluentGasPayment = {
2093
537
  /**
2094
538
  * Whether to ask the App's sponsorship paymaster to pay for this operation.
2095
539
  *
2096
- * Defaults to `"auto"`, which is what every caller got before this option existed: try
2097
- * sponsorship, and if the paymaster refuses, resend with the account paying its own gas.
2098
- * `"never"` skips the paymaster outright, so the account pays from the first attempt and
2099
- * the result reports `sponsorshipReason: "not_requested"`.
540
+ * `"auto"` tries Sponsorship, and if the paymaster refuses, resends with the account paying
541
+ * its own gas. `"never"` skips the paymaster outright, so the account pays from the first
542
+ * attempt and the result reports `sponsored: false`. What an omitted value means:
543
+ * [guides/sponsorship.md](guides/sponsorship.md#not-asking-sponsorship-never-and-gas-tokens).
2100
544
  *
2101
- * The distinction is not cosmetic: under `"auto"` the two outcomes are indistinguishable
2102
- * before the send and only the settled receipt separates them, so a caller that wants to
2103
- * *demonstrate* unsponsored execution — or to keep an App's budget untouched — has no
2104
- * way to say so. Ignored when `symbol` names an ERC-20: that token's own paymaster pays,
545
+ * Ignored when `symbol` names an ERC-20: that token's own paymaster pays,
2105
546
  * and sponsorship is not in the picture.
2106
547
  */
2107
548
  sponsorship?: "auto" | "never";
@@ -2112,1141 +553,839 @@ type FluentGasPayment = {
2112
553
  includeApproval?: false;
2113
554
  approveAmount?: never;
2114
555
  });
556
+ /** The options of `FluentBatchOperation.execute`, every one optional. */
2115
557
  type FluentBatchOperationExecuteOptions = {
2116
- confirmation?: FluentBatchConfirmationMode;
558
+ /**
559
+ * The `FluentSigningMode` of this operation. Defaults to the widget's `signingMode`, which
560
+ * follows the person's Quick sign. A `"silent"` operation with a call outside
561
+ * `quickSign.whitelistAddresses` is signed as `"prompt"`. Any value but `"silent"`, 0.5's
562
+ * `"always"` and `"session"` included, is `"prompt"`. Ignored for an External wallet.
563
+ */
564
+ confirmation?: FluentSigningMode;
565
+ /** How the gas of this operation is paid. Defaults to the Gas payment chosen in the widget. */
2117
566
  gasPayment?: FluentGasPayment;
2118
- /** Fluent ID gas limits, estimation opt-out or headroom. Ignored for External wallet sends. */
567
+ /**
568
+ * Fluent ID gas limits, estimation opt-out or headroom: a `FluentUserOperationGas`, whose
569
+ * fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`. Ignored for
570
+ * External wallet sends.
571
+ *
572
+ * @experimental May change or be removed in a minor release while the gas policy is measured;
573
+ * omitting it, which lets the widget estimate, is the recommended setting.
574
+ */
2119
575
  userOperationGas?: FluentUserOperationGas;
2120
576
  };
2121
- type FluentBatchOperationReview = {
2122
- id?: string;
2123
- reviewTitle?: string;
2124
- calls: readonly FluentBatchCallInput[];
2125
- encodedCalls: FluentEncodedBatchCall[];
2126
- account?: FluentWidgetAccount;
2127
- };
577
+ /**
578
+ * A Batch operation `widget.createBatchOp` built: its calls, encoded, and `execute`, which sends
579
+ * them for the Widget account.
580
+ */
2128
581
  type FluentBatchOperation = {
582
+ /** `FluentBatchOperationInput.id`, copied. */
2129
583
  id?: string;
584
+ /** `FluentBatchOperationInput.reviewTitle`, copied. */
2130
585
  reviewTitle?: string;
586
+ /** The calls as the host passed them. */
2131
587
  calls: readonly FluentBatchCallInput[];
588
+ /** The same calls encoded, in order: what `execute()` sends. */
2132
589
  encodedCalls: FluentEncodedBatchCall[];
590
+ /**
591
+ * Whether the widget could send the operation when it was built: the Widget account ready, or
592
+ * able to prepare itself when `execute()` is called. Not updated afterwards; read
593
+ * `widget.account.executionReady` for the live value.
594
+ */
2133
595
  canExecute: boolean;
2134
- execute: (optionsOrExecutor?: FluentBatchOperationExecuteOptions | FluentBatchOperationExecutor, executor?: FluentBatchOperationExecutor) => Promise<FluentExecuteResult>;
596
+ /**
597
+ * Executes the operation for the Widget account and resolves once it is included.
598
+ *
599
+ * @throws `FluentReviewRejectedError` with `code` `transaction_review_rejected` when the
600
+ * person dismisses the Review, which a Fluent ID shows in Prompt mode; an External wallet's
601
+ * refusal in its own prompt rejects with the wallet's error.
602
+ * @throws `FluentSponsorshipFallbackError` when a Fluent ID asked for Sponsorship, a sponsored
603
+ * submission failed, and the submission in which the account pays its own gas failed too;
604
+ * its `code` says why Sponsorship failed: `denied`, `unauthorized`, `unreachable` or
605
+ * `no_token`. A failure while waiting for an operation's inclusion is not wrapped: it rejects
606
+ * with its own error, and an operation whose wait failed was submitted. What else is not
607
+ * wrapped: [guides/sponsorship.md](guides/sponsorship.md#both-failed-fluentsponsorshipfallbackerror).
608
+ * @throws `FluentUserOperationGasError` (experimental) with `code` `invalid_policy` for a
609
+ * `skipEstimation` policy that cannot be used (other invalid `userOperationGas` values throw a
610
+ * plain `Error`), and `paymaster_gas_mismatch` when, with estimation skipped,
611
+ * the paymaster's authorization of a Gas token payment does not match the fixed gas limits.
612
+ * Under Sponsorship, a failed check of the paymaster's gas fails the sponsored submission
613
+ * instead, and the account pays its own gas.
614
+ */
615
+ execute: (options?: FluentBatchOperationExecuteOptions) => Promise<FluentExecuteResult>;
2135
616
  };
2136
- type FluentBatchApi = FluentPermissionApi & FluentSignApi & {
617
+ /**
618
+ * The Widget API: what the widget gives an App's code to act for the Widget account. Reached as
619
+ * `widget` in the render context or from `useFluentWidget()`.
620
+ */
621
+ type FluentBatchApi = FluentSignApi & {
622
+ /** The Widget account: its address, type, readiness and capabilities. */
2137
623
  account: FluentWidgetAccount;
2138
- confirmationMode: FluentBatchConfirmationMode;
624
+ /** How the widget signs by default: `"silent"` while the person's Quick sign is on. */
625
+ signingMode: FluentSigningMode;
626
+ /** The Gas payment chosen in the widget, which `execute()` uses when given no `gasPayment`. */
2139
627
  gasPayment: FluentWidgetGasPayment;
628
+ /**
629
+ * Builds a Batch operation, encoding its calls now; `execute()` sends it.
630
+ *
631
+ * @throws `Error` when `calls` is empty, or when a call has neither `data` nor `abi` with
632
+ * `method`: a call that still names its function in 0.5's `functionName` is one.
633
+ */
2140
634
  createBatchOp: (input: FluentBatchOperationInput) => FluentBatchOperation;
2141
635
  };
2142
- declare function createFluentBatchOp(input: FluentBatchOperationInput, executor?: FluentBatchOperationExecutor | null): FluentBatchOperation;
2143
636
 
2144
637
  /**
2145
- * Privy runtime supplied by a host using a native SDK. Its Provider owns session
2146
- * restoration, login and wallet RPC; web hosts keep the normal React SDK.
2147
- * Keep one stable adapter per runtime. Changing its Provider remounts descendants
2148
- * so React hooks from different SDKs never share a component lifetime.
638
+ * Images for the widget, each a URL or a data URI. Today the widget reads only `fluentLogo`,
639
+ * which it passes to the provider behind Direct login as its logo; see `assets` in
640
+ * [configuration.md](configuration.md).
2149
641
  */
2150
- type FluentPrivyAdapter = Pick<typeof web, "PrivyProvider" | "Captcha" | "usePrivy" | "useSignMessage" | "useSignTypedData" | "useWallets" | "useIdentityToken" | "useUser" | "useLinkAccount" | "useLoginWithSiwe" | "useModalStatus" | "useCreateWallet" | "useLoginWithEmail" | "useLoginWithOAuth" | "useLoginWithPasskey" | "useLinkWithPasskey">;
2151
-
2152
- type FluentWalletChoice = {
2153
- id: string;
2154
- name: string;
2155
- icon?: string;
2156
- /** This connector opens an external wallet/QR surface. */
2157
- handoff?: boolean;
642
+ type FluentWidgetAssets = {
643
+ /** The Fluent mark. */
644
+ fluentLogo: string;
645
+ /** The WalletConnect icon. */
646
+ walletConnectIcon: string;
647
+ /** The MetaMask icon. */
648
+ metamaskIcon: string;
649
+ /** The Coinbase Wallet icon. */
650
+ coinbaseIcon: string;
2158
651
  };
2159
- type FluentExternalWalletState = {
2160
- configured: boolean;
2161
- connected: boolean;
2162
- address?: string;
2163
- chainId?: number;
2164
- walletClient?: WalletClient;
652
+ /**
653
+ * What the widget tells an App about who is signed in: the Widget account's address and type,
654
+ * and when the widget built that snapshot. Not a credential: an App proves who the person is
655
+ * with an Auth token from `getAuthToken()`.
656
+ *
657
+ * Only a Fluent ID's Direct login writes a session. Connecting an External wallet neither writes nor
658
+ * clears it; read the connected account from `widget.account`.
659
+ */
660
+ type FluentWidgetSession = {
661
+ account: {
662
+ /** The Fluent ID's smart account address. */
663
+ address: Address;
664
+ /**
665
+ * `"smart"`: today a session is only ever a Fluent ID's. `FluentAccountType` may gain
666
+ * values, so a `switch` over it keeps a `default` branch.
667
+ */
668
+ type: FluentAccountType;
669
+ };
2165
670
  /**
2166
- * True while the wallet is being restored from a previous visit and neither
2167
- * `connected` nor "no wallet" is known yet. Optional so hosts supplying their
2168
- * own wallet state keep working; omitting it just means the widget reports
2169
- * `"disconnected"` slightly earlier during a reload.
671
+ * The local time the widget built the snapshot, in Unix seconds from the browser's clock; not
672
+ * a time the service attests. A session restored on a later page load keeps that time.
2170
673
  */
2171
- reconnecting?: boolean;
2172
- /** Optional inline choices; hosts without them keep their existing open() picker. */
2173
- choices?: readonly FluentWalletChoice[];
2174
- connectChoice?: (id: string) => Promise<void>;
2175
- open: () => void;
2176
- disconnect: () => void;
2177
- switchChain: (chainId: number) => Promise<void>;
674
+ issuedAt: number;
2178
675
  };
2179
676
  /**
2180
- * Top-level connection state of the widget, safe to read on any render.
677
+ * A sign-in method the sign-in dialog can offer beside X. X is not on this list:
678
+ * it is always offered and cannot be switched off.
679
+ */
680
+ type FluentWidgetAuthMethod = "google" | "email" | "passkey";
681
+ /**
682
+ * Which value in `FluentWidgetConfig` was refused, for a host that branches rather than reads
683
+ * the message.
684
+ */
685
+ type FluentWidgetConfigErrorCode = "invalid_fee_source" | "invalid_receipt_source" | "invalid_chain_check_before_sign"
686
+ /** A required option is absent or empty. */
687
+ | "missing_option"
688
+ /** An option holds a value the widget cannot use. */
689
+ | "invalid_option"
690
+ /** An option an earlier release removed or renamed is still passed. */
691
+ | "removed_option";
692
+ /**
693
+ * A value in `FluentWidgetConfig` the widget refuses to start with.
2181
694
  *
2182
- * The distinction that matters is `"restoring"` vs `"disconnected"`: a session
2183
- * restored from a previous visit is not known synchronously, so a host that
2184
- * treats "not connected yet" as "no account" will render a Connect button at
2185
- * users who do have a live session. Wait out `"restoring"` instead.
695
+ * Thrown when `<FluentWidget>` renders with a config it has not resolved yet: on its first
696
+ * render, and again on any render that passes a new `config` object. So it surfaces at startup
697
+ * where the integrator is looking rather than at the first send. The message names the option and
698
+ * how to fix it; `code`, a `FluentWidgetConfigErrorCode`, is what to branch on.
2186
699
  *
2187
- * - `"restoring"` — a previous session may exist; nothing is decided yet.
2188
- * - `"connecting"` — a sign-in the user started is in flight.
2189
- * - `"connected"` — an account is available. Whether it can send transactions
2190
- * *right now* is a separate question — see `widget.account.executionStatus`.
2191
- * - `"disconnected"` — no account, and none is being restored or negotiated.
700
+ * @example
701
+ * ```tsx
702
+ * import { FluentWidgetConfigError } from "@fluent.xyz/connect";
703
+ *
704
+ * export function WidgetBoundaryFallback({ error }: { error: unknown }) {
705
+ * // More than one option is required, and the message names the one that is missing.
706
+ * if (error instanceof FluentWidgetConfigError && error.code === "missing_option") {
707
+ * return <p>The widget config is missing a required option: {error.message}</p>;
708
+ * }
709
+ * throw error;
710
+ * }
711
+ * ```
2192
712
  */
2193
- type FluentWidgetStatus = "restoring" | "connecting" | "connected" | "disconnected";
2194
-
2195
- type FluentAuthErrorCode = "unknown_app" | "app_not_auth_enabled" | "origin_not_allowed" | "origin_missing" | "bad_request" | "nonce_unknown" | "nonce_used" | "nonce_expired" | "app_mismatch" | "invalid_signature" | "signature_prefix_rejected" | "address_already_linked" | "invalid_privy_token" | "no_embedded_wallet" | "invalid_refresh_token" | "refresh_token_reused" | "rate_limited" | "internal" | "not_connected" | "root_signer_required" | "privy_token_missing" | "origin_mismatch" | "request_failed" | "not_authenticated" | "user_rejected" | "linked_to_another_user" | "link_failed";
2196
- declare class FluentAuthError extends Error {
2197
- readonly code: FluentAuthErrorCode;
2198
- readonly status?: number | undefined;
2199
- constructor(code: FluentAuthErrorCode, message: string, status?: number | undefined);
713
+ declare class FluentWidgetConfigError extends Error {
714
+ readonly code: FluentWidgetConfigErrorCode;
715
+ constructor(code: FluentWidgetConfigErrorCode, message: string);
2200
716
  }
2201
-
2202
- /** One X account as the Fluent auth service reports it. */
2203
- type FluentXAccount = {
2204
- id: string;
2205
- handle: string;
2206
- avatarUrl: string;
2207
- };
2208
717
  /**
2209
- * The wire body of `GET /api/v1/me/profile` and of `POST /api/v1/me/identity/privy`.
718
+ * Where a Fluent ID's send reads a value it could ask either side for: the widget chain's own
719
+ * RPC, or the bundler.
2210
720
  *
2211
- * `x` is required and nullable: the route always says something about the X account, and `null`
2212
- * is that answer — this user has none linked. A body without the key at all is not this route's.
721
+ * @experimental May change or be removed in a minor release while the defaults are measured;
722
+ * the defaults are the recommended setting.
2213
723
  */
2214
- type FluentProfile = {
2215
- subject: string;
2216
- appId: string;
2217
- x: FluentXAccount | null;
2218
- };
2219
- type FluentLinkXResult = {
2220
- status: "linked";
2221
- x: FluentXAccount;
2222
- }
2223
- /** The page is leaving for X. Call linkX() again after the return; useLinkX() does it on mount. */
2224
- | {
2225
- status: "redirecting";
2226
- };
2227
-
2228
- type FluentWidgetRenderContext = {
2229
- session: FluentWidgetSession | null;
2230
- connectedAddress?: string;
2231
- /** Privy's X avatar used by the account tile; absent for an External wallet or `forceDefault`. */
2232
- userAvatarUrl?: string;
2233
- wallet: FluentExternalWalletState | null;
2234
- widget: FluentBatchApi;
2235
- openConnect: () => void;
2236
- openAccount: () => void;
724
+ type FluentWidgetExecutionSource = "chain" | "bundler";
725
+ /**
726
+ * `FluentWidgetConfig.execution`, every field optional.
727
+ *
728
+ * @experimental May change or be removed in a minor release while the defaults are measured;
729
+ * the defaults are the recommended setting.
730
+ */
731
+ type FluentWidgetExecution = {
2237
732
  /**
2238
- * Tear down the current session without going through the widget's account
2239
- * menu — the same teardown that menu's "Disconnect" runs. The session, the
2240
- * stored identity token and any external wallet connection are cleared before
2241
- * this resolves, so a host can await it before resetting its own state.
733
+ * Where the fees of a user operation come from, a `FluentWidgetExecutionSource`. `chain` reads
734
+ * the widget chain's `eth_gasPrice` and caps `maxFeePerGas` 10 % above it; `bundler` takes the
735
+ * bundler's own gas price quote unchanged. Defaults to `chain`.
2242
736
  *
2243
- * It also covers ending the Fluent session at the service — revoking the refresh
2244
- * family so the 30 days stop here — including for a `getAuthToken()` that was still
2245
- * out when the user disconnected: a wallet signature answered late opens a session
2246
- * of its own, and this promise does not resolve while one of those could still be
2247
- * live. It can therefore take as long as that request does. It never rejects, and
2248
- * the widget's own teardown does not wait for it.
737
+ * @experimental May change or be removed in a minor release while the defaults are
738
+ * measured; the defaults are the recommended setting.
2249
739
  */
2250
- disconnect: () => Promise<void>;
2251
- hasConnectedAccount: boolean;
740
+ feeSource?: FluentWidgetExecutionSource;
2252
741
  /**
2253
- * Connection state as a single value that is meaningful on every render —
2254
- * including the first, before a stored session has been reconciled. Branch on
2255
- * this rather than on `hasConnectedAccount` alone: `"restoring"` and
2256
- * `"disconnected"` both have `hasConnectedAccount === false`, and treating
2257
- * them alike shows a Connect button to users who are already signed in.
742
+ * Where inclusion is read from, a `FluentWidgetExecutionSource`. `chain` polls the
743
+ * EntryPoint's `UserOperationEvent` with `eth_getLogs`; `bundler` polls
744
+ * `eth_getUserOperationReceipt`. Defaults to `chain`.
745
+ *
746
+ * @experimental May change or be removed in a minor release while the defaults are
747
+ * measured; the defaults are the recommended setting.
2258
748
  */
2259
- status: FluentWidgetStatus;
749
+ receiptSource?: FluentWidgetExecutionSource;
2260
750
  /**
2261
- * True while a direct-auth smart account is being prepared after sign-in.
2262
- * Equivalent to `status === "connecting"`; prefer `status`, which also covers
2263
- * the restore-in-progress case this flag cannot express.
751
+ * Whether the Signer's chain is read before every signature. The widget gives the Signer's
752
+ * provider its own chain as the only one, and the smart account checks the chain once when it
753
+ * is created, so the repeat costs a provider round trip per signature and switches nothing.
754
+ * Defaults to `false`.
755
+ *
756
+ * @experimental May change or be removed in a minor release while the defaults are
757
+ * measured; the defaults are the recommended setting.
2264
758
  */
2265
- connecting: boolean;
759
+ chainCheckBeforeSign?: boolean;
760
+ };
761
+ /** The configuration of one `<FluentWidget>`, fixed for the App's deployment. */
762
+ type FluentWidgetConfig = {
763
+ /** The App's id (`app_<32 hex>`) — the same string the Fluent Dashboard shows and the token's `aud` carries. */
764
+ appId: string;
2266
765
  /**
2267
- * Refetch the widget's on-chain balances. Transactions run through
2268
- * `widget.createBatchOp` refresh automatically; call this after a tx sent via
2269
- * an external wallet client (outside the widget's execution path).
766
+ * The Privy app client issued by Fluent for this App. Login configuration, not
767
+ * identity: it carries the allowed origins for Privy login, while `appId` is what
768
+ * sponsorship, auth and analytics speak. Required while login runs on Privy.
769
+ *
770
+ * @experimental May change or be removed in a minor release: it exists while login runs on
771
+ * Privy, and goes when Fluent's own login replaces it.
2270
772
  */
2271
- refreshBalances: () => void;
773
+ privyClientId: string;
774
+ /** Removed in 0.2.0 — the type exists only so the error names the fix. */
775
+ clientId?: never;
776
+ /** Renamed to `appId` in 0.3.0 — the type exists only so the error names the fix. */
777
+ partnerId?: never;
2272
778
  /**
2273
- * A short-lived (5 min) Fluent-signed JWT for the connected user. Verify it on your backend
2274
- * against `<iss>/.well-known/jwks.json` (ES256), checking `iss`, `aud` (= your appId) and
2275
- * `exp`; `sub` is stable per user per app. Reused until `authTokenRenewalOffsetSeconds`
2276
- * before `exp`, and renewed silently after that — for a Fluent ID and for an external wallet
2277
- * alike. The wallet signs once, when the session opens; the renewals that follow ask it for
2278
- * nothing. A new signature is needed only when the session's 30-day refresh family expires,
2279
- * when the service rejects the refresh credential, or when it was never stored (the user
2280
- * disconnected, cleared site data, or opened another browser).
2281
- * External wallets: EOAs and deployed smart-contract wallets sign in; a not-yet-deployed
2282
- * smart account cannot (no ERC-6492).
779
+ * The Network the widget runs on. It picks the chain, the funds, the login app, the account
780
+ * project and the service, so the App names it: the widget reads no environment variable for
781
+ * it and has no default.
2283
782
  */
2284
- getAuthToken: () => Promise<string>;
783
+ network: FluentWidgetNetwork;
784
+ appName?: string;
2285
785
  /**
2286
- * Link an X account to the connected Fluent ID, headless: no widget screen, no settings page,
2287
- * one call. Idempotent and re-enterable, because linking X needs an OAuth round trip that
2288
- * leaves the page and Privy offers no other primitive for it.
2289
- *
2290
- * A user who already has X resolves `{ status: "linked", x }` with no dialog and without
2291
- * leaving: the SDK sends the one `POST /api/v1/me/identity/privy` the service needs and
2292
- * returns the account from its answer. A user who has none resolves `{ status: "redirecting" }`
2293
- * once the navigation to X has been started: the code after the `await` does run, briefly —
2294
- * enough to show a "taking you to X" state — but the page is unloading, so nothing on it may
2295
- * wait for the link to finish. When the browser comes back, call `linkX()` again — `useLinkX()`
2296
- * does it for you on mount — and it resolves `linked`, having waited for Privy to restore the
2297
- * user and seen the X account on it. Calling it again when the user already has X costs one
2298
- * request and changes nothing, which is what makes it safe to call on every mount.
786
+ * An HTTPS URL passed to the provider behind Direct login as its OAuth redirect URL. When to
787
+ * use it: [experimental.md](experimental.md#customoauthredirecturl).
2299
788
  *
2300
- * A link somebody else started in this tab, or a stale record of one, is discarded rather
2301
- * than resumed: the call does no work and rejects with `link_failed`; call again to start one
2302
- * for the signed-in user.
2303
- *
2304
- * An external wallet is first signed in to Privy with SIWE — one signature prompt, never a
2305
- * transaction — and then takes the same path; a repeat call with that session live signs
2306
- * nothing again. The connected account, its kind and the wallet's Fluent token are unchanged
2307
- * by it.
2308
- *
2309
- * Rejects with `FluentAuthError`: `user_rejected` (the user said no at X, or declined the
2310
- * SIWE signature), `linked_to_another_user` (that X account belongs to another Fluent user),
2311
- * `not_authenticated` (no Fluent ID or external wallet connected), `bad_request` and
2312
- * `link_failed` (everything else). No other code reaches the caller: a refusal from under
2313
- * the call keeps its message under `link_failed`.
2314
- */
2315
- linkX: () => Promise<FluentLinkXResult>;
2316
- };
2317
- type FluentWidgetConnectButtonRenderContext = {
2318
- connected: boolean;
2319
- /** True while a direct-auth smart account is being prepared after sign-in. */
2320
- pending: boolean;
2321
- addressLabel?: string;
2322
- /** Privy's X avatar used by the account tile; absent for an External wallet or `forceDefault`. */
2323
- userAvatarUrl?: string;
2324
- onClick: () => void;
2325
- openConnect: () => void;
2326
- openAccount: () => void;
2327
- DefaultButton: () => ReactNode;
2328
- };
2329
- type FluentWidgetProps = {
2330
- wallet?: FluentExternalWalletState | null;
2331
- config: FluentWidgetConfig;
2332
- /** Optional native Privy SDK bridge; requires direct auth. */
2333
- privyAdapter?: FluentPrivyAdapter;
2334
- mode?: "home" | "page";
2335
- /**
2336
- * Show the default connect/account control.
2337
- * - `"fixed"` (default) — top-right floating button
2338
- * - `"inline"` — same button, no fixed positioning (host places via CSS / wrapper)
2339
- * - `false` — hide; use `renderConnectButton`, `openConnect`, or `openAccount`
789
+ * @experimental May change or be removed in a minor release: it configures the redirect of
790
+ * the login provider the widget runs on today.
2340
791
  */
2341
- connectButton?: "fixed" | "inline" | false;
2342
- /** Replace the default connect button UI / placement entirely. */
2343
- renderConnectButton?: (context: FluentWidgetConnectButtonRenderContext) => ReactNode;
2344
- renderHome?: (context: FluentWidgetRenderContext) => ReactNode;
2345
- renderPage?: (context: FluentWidgetRenderContext) => ReactNode;
2346
- tokens?: readonly FluentTokenDefinition[];
2347
- showDebugPayload?: boolean;
792
+ customOAuthRedirectUrl?: string;
2348
793
  /**
2349
- * Print the widget's internal connect / smart-account / signing diagnostics to
2350
- * the console. Off by default; turn on only while debugging an integration.
794
+ * Sign-in methods the sign-in dialog offers beside X, in the order given.
795
+ * Defaults to `["google", "email", "passkey"]` — all of them; name a shorter
796
+ * set to drop the rest, or `[]` to leave X as the only Fluent method.
797
+ * Sign-in with X is always offered and is not a value here.
798
+ *
799
+ * A method still has to be enabled for the App by Fluent — listing it here only decides
800
+ * whether its button is drawn.
2351
801
  */
2352
- debugLogging?: boolean;
2353
- onSessionChange?: (session: FluentWidgetSession | null) => void;
2354
- };
2355
- declare function FluentWidget(props: FluentWidgetProps): React.JSX.Element;
2356
-
2357
- /**
2358
- * Access the Fluent widget render context from any component rendered inside
2359
- * `<FluentWidget>` (e.g. within `renderHome` / `renderPage`). Returns the same
2360
- * object the render props receive — `session`, `widget`, `openConnect`, etc. —
2361
- * so host apps no longer need to prop-drill it.
2362
- *
2363
- * Throws if used outside `<FluentWidget>`.
2364
- */
2365
- declare function useFluentWidget(): FluentWidgetRenderContext;
2366
- /** Convenience hook returning just the widget API (`createBatchOp`, permissions, account…). */
2367
- declare function useWidget(): FluentBatchApi;
2368
-
2369
- /** Per chain. A ceiling, not a product limit — it stops storage being abused. */
2370
- declare const FLUENT_USER_TOKEN_LIMIT = 50;
2371
- type FluentUserTokenAddResult = {
2372
- status: "added";
2373
- } | {
2374
- status: "already-present";
2375
- } | {
2376
- status: "at-capacity";
2377
- limit: number;
2378
- } | {
2379
- status: "invalid";
2380
- }
2381
- /**
2382
- * The store could not reach the truth: no network, no Fluent token, or the
2383
- * service answered something other than a refusal it can name. Distinct from
2384
- * `invalid`, which says the token itself is wrong and retrying cannot help.
2385
- */
2386
- | {
2387
- status: "failed";
2388
- message: string;
2389
- };
2390
- /**
2391
- * Persistence for tokens the end user added by hand.
2392
- *
2393
- * Asynchronous because the truth may live on the service: while the widget
2394
- * holds a Fluent token the backing store is `createFluentBackendUserTokenStore`
2395
- * and the list follows the person between Apps and browsers; where no Fluent
2396
- * token can exist (the not-connected state)
2397
- * it is `createFluentUserTokenStore` over this browser's localStorage. See
2398
- * `docs/adr/0004-user-settings-live-on-the-service.md`.
2399
- */
2400
- type UserTokenStore = {
2401
- list(chainId: number): Promise<FluentTokenDefinition[]>;
2402
- add(token: FluentTokenDefinition): Promise<FluentUserTokenAddResult>;
2403
- remove(token: Pick<FluentTokenDefinition, "chainId" | "address">): Promise<void>;
2404
- };
2405
- /**
2406
- * The browser-backed store, used where no Fluent token can exist. Falls back to
2407
- * an in-memory list when storage is unavailable, so the UI keeps working for
2408
- * the current view instead of throwing. Its promises are already settled: the
2409
- * async signatures exist for the backend store, not for this one.
2410
- */
2411
- declare function createFluentUserTokenStore(options?: {
2412
- storage?: StorageLike;
2413
- key?: string;
2414
- }): UserTokenStore;
2415
-
2416
- /**
2417
- * The tokens this person added by hand, on the current chain, plus the two
2418
- * writes. Every call is asynchronous now: the store may be the service's
2419
- * (`createFluentBackendUserTokenStore`) rather than this browser's.
2420
- *
2421
- * A failed load is not an empty list — the last one settled stays on screen and
2422
- * the failure goes to `debugWarn`. A failed `add` comes back as a result the
2423
- * form can show; nothing rejects out of here.
2424
- */
2425
- declare function useFluentUserTokens(options?: {
2426
- store?: UserTokenStore;
2427
- }): {
2428
- tokens: FluentTokenDefinition[];
2429
- add: (token: FluentTokenDefinition) => Promise<FluentUserTokenAddResult>;
2430
- remove: (token: Pick<FluentTokenDefinition, "chainId" | "address">) => Promise<void>;
2431
- };
2432
-
2433
- /**
2434
- * Codes fluent-connect-service returns on the `/me` routes (FLU-1481), plus the
2435
- * one the client mints when the failure never reached the service.
2436
- */
2437
- type FluentSettingsErrorCode = "invalid_request" | "invalid_token" | "at_capacity" | "internal" | "request_failed";
2438
- declare class FluentSettingsError extends Error {
2439
- readonly code: FluentSettingsErrorCode;
2440
- readonly status?: number | undefined;
2441
- constructor(code: FluentSettingsErrorCode, message: string, status?: number | undefined);
2442
- }
2443
- /** The three values the service keeps per person. */
2444
- type FluentUserSettings = {
2445
- quickSign: boolean;
2446
- /** `null` means "no choice stored"; the widget's own default applies. */
2447
- gasTokenSymbol: string | null;
2448
- /** Every chain the person has tokens on; callers filter by chain themselves. */
2449
- tokens: FluentTokenDefinition[];
2450
- };
2451
- type FluentUserSettingsPatch = {
2452
- quickSign?: boolean;
2453
- gasTokenSymbol?: string | null;
2454
- };
2455
- type FluentSettingsClient = {
2456
- read(): Promise<FluentUserSettings>;
2457
- /** At least one field; the service refuses an empty or unknown-field body. */
2458
- patch(patch: FluentUserSettingsPatch): Promise<FluentUserSettings>;
2459
- putToken(token: FluentTokenDefinition): Promise<void>;
2460
- deleteToken(token: Pick<FluentTokenDefinition, "chainId" | "address">): Promise<void>;
2461
- };
2462
- /**
2463
- * The widget's own client for `GET/PATCH /me/settings` and
2464
- * `PUT/DELETE /me/tokens/{chain_id}/{address}`.
2465
- *
2466
- * Every request carries the Fluent token from `getAuthToken()` and nothing
2467
- * else: the token names the person, so no route here carries a Privy DID, a
2468
- * subject or a uuid.
2469
- */
2470
- declare function createFluentSettingsClient(params: {
2471
- /** Already ends in `/api/v1`. */
2472
- publicApiUrl: string;
2473
- getAuthToken: () => Promise<string>;
2474
- fetch?: typeof globalThis.fetch;
2475
- }): FluentSettingsClient;
2476
-
2477
- type BackendUserTokenStore = UserTokenStore & {
802
+ enabledAuthMethods?: FluentWidgetAuthMethod[];
2478
803
  /**
2479
- * Adopt the list from a `GET /me/settings` the caller already made, so the
2480
- * settings read and the token list share one round trip at sign-in.
804
+ * The swap entry in the account drawer.
805
+ *
806
+ * @experimental May change or be removed in a minor release while the defaults are measured;
807
+ * the defaults are the recommended setting.
2481
808
  */
2482
- prime(tokens: readonly FluentTokenDefinition[]): void;
2483
- /** Forget the list; the next `list()` loads again. */
2484
- reset(): void;
2485
- };
2486
- /**
2487
- * `UserTokenStore` over the service's `/me/tokens` routes, used wherever
2488
- * `getAuthToken()` can resolve. The list is cached in memory and kept in step
2489
- * with every write, so browsing the token list costs no request after sign-in.
2490
- *
2491
- * `add` and `remove` never throw: the token list is a corner of a wallet menu,
2492
- * and a failed write there must not reach the host App as a rejection. `list`
2493
- * may reject — its caller (`createUserTokenListLoader`) keeps the last settled
2494
- * list on screen instead.
2495
- */
2496
- declare function createFluentBackendUserTokenStore(params: {
2497
- client: FluentSettingsClient;
809
+ swapper?: {
810
+ enabled?: boolean;
811
+ integratorId?: string;
812
+ dstChainId?: string;
813
+ dstTokenAddress?: string;
814
+ };
815
+ gasPayment?: {
816
+ /** Initial/fallback token. Defaults to ETH; a valid saved user choice wins. */
817
+ defaultToken?: FluentGasTokenSymbol;
818
+ /** Native-gas sponsorship policy. Defaults to `auto`; `never` skips the paymaster. */
819
+ sponsorship?: "auto" | "never";
820
+ /**
821
+ * What one unit of each Gas token is worth in ETH, a `FluentGasPaymentEthRates` keyed by
822
+ * `FluentGasTokenSymbol`, for the cost the widget shows beside each Gas token.
823
+ *
824
+ * @experimental May change or be removed in a minor release while the defaults are
825
+ * measured; the defaults are the recommended setting.
826
+ */
827
+ ethValueByToken?: FluentGasPaymentEthRates;
828
+ };
2498
829
  /**
2499
- * The shared settings read. Called only when the store has no list yet, so a
2500
- * controller that primes it after its own `GET` causes no second request.
830
+ * How a Fluent ID's send is executed: a `FluentWidgetExecution`, each of whose sources is a
831
+ * `FluentWidgetExecutionSource`. Every field defaults to the fast path, which falls back to
832
+ * the bundler on its own: set a field to switch that one answer to the bundler for good.
833
+ *
834
+ * @experimental May change or be removed in a minor release while the defaults are
835
+ * measured; the defaults are the recommended setting.
2501
836
  */
2502
- load: () => Promise<readonly FluentTokenDefinition[]>;
2503
- /** Shown next to the token list when a `DELETE` fails. */
2504
- onRemoveError?: (message: string) => void;
2505
- }): BackendUserTokenStore;
2506
-
2507
- type UseLinkXStatus = "idle" | "pending" | "redirecting" | "linked" | "error";
2508
- /**
2509
- * Linking X as a component sees it: the call, and what the last one did.
2510
- *
2511
- * `redirecting` is the status a page is unlikely to render for long — it is set just before the
2512
- * browser leaves for X — and `linked` after a return is what the mount-time re-entry produces
2513
- * without the component asking for anything.
2514
- */
2515
- declare function useLinkX(): {
2516
- linkX: () => Promise<FluentLinkXResult>;
2517
- status: UseLinkXStatus;
2518
- x: FluentXAccount | null;
2519
- error: FluentAuthError | null;
2520
- };
2521
-
2522
- type FluentTokenTransferRequest = {
2523
- token: FluentDisplayToken;
2524
- to: Address;
2525
- /** In the token's base units, already checked against the balance. */
2526
- amount: bigint;
837
+ execution?: FluentWidgetExecution;
838
+ quickSign?: {
839
+ /**
840
+ * Call targets Quick sign may execute without the Review. With a list set, a Batch
841
+ * operation runs in Silent mode only when every call's `to` is on it; a single call to any
842
+ * other address shows the Review, even with Quick sign on. An
843
+ * empty list is honoured and stops Quick sign from silencing anything; omit the
844
+ * option to keep it covering every address. Compared case-insensitively.
845
+ * `signMessage` / `signTypedData` have no call target and are not scoped by this.
846
+ */
847
+ whitelistAddresses?: readonly string[];
848
+ };
2527
849
  /**
2528
- * What the fee is charged in, for this one transfer. Overrides the gas token
2529
- * stored in User settings without changing it: a withdrawal is exactly the
2530
- * moment the usual choice may be the wrong one.
850
+ * `false` drops the Reputation tab from the account drawer — and with it the
851
+ * whole tab strip, since Home is then the only tab. The families request is
852
+ * never made. Default `true`.
2531
853
  */
2532
- gasSymbol: FluentGasTokenSymbol;
2533
- };
2534
- type FluentTokenTransferOutcome = {
2535
- status: "sent";
2536
- hash: Hash;
2537
- }
2538
- /** The user dismissed the review. Not a failure, and nothing to report. */
2539
- | {
2540
- status: "rejected";
2541
- } | {
2542
- status: "failed";
2543
- message: string;
2544
- };
2545
- /**
2546
- * A transfer the widget has sent and is still waiting on. It has no hash yet —
2547
- * `execute` resolves with one only after the receipt — so it cannot be a
2548
- * `FluentTransactionHistoryEntry`, every one of which describes something
2549
- * already mined. Activity lists these above the mined rows until the real one
2550
- * takes over.
2551
- */
2552
- type FluentPendingTransfer = {
2553
- id: string;
2554
- /** `fluentTokenIdentity` of the token, so the row it fills in prices and filters like any other. */
2555
- tokenIdentity: string;
2556
- symbol: string;
2557
- /** Decimal, unsigned: a pending transfer is always outgoing. */
2558
- amount: string;
2559
- to: Address;
2560
- /** Unix milliseconds, so it sorts into the list beside the mined rows. */
2561
- startedAt: number;
854
+ reputationEnabled?: boolean;
855
+ source?: string;
856
+ campaign?: string;
857
+ /** Turns off all analytics: PostHog is never initialised, nothing is sent or stored. */
858
+ disableAnalytics?: boolean;
859
+ /** Restore injected wallets and WalletConnect by default; true restores all, false restores none. */
860
+ reconnectOnMount?: boolean;
2562
861
  /**
2563
- * Set once the transfer settles. The row stays until the history has caught
2564
- * up and lists this hash: FluentScan indexes a little behind the receipt, so
2565
- * dropping the row the moment `execute` resolves makes the transfer vanish
2566
- * from the list for as long as the next refetch takes.
862
+ * Point the widget at a sponsorship service other than the network default. Local
863
+ * development only: the deployed URL is the one every real integration should use.
864
+ *
865
+ * @experimental May change or be removed in a minor release while the defaults are measured;
866
+ * the defaults are the recommended setting.
2567
867
  */
2568
- hash?: Hash;
868
+ sponsorshipUrl?: string;
2569
869
  /**
2570
- * The stand-in row has given up waiting for the history to list this hash.
2571
- * The details stay: the history may yet list the operation before the
2572
- * transfer it carried, and they are what fills that row in.
870
+ * `getAuthToken()` reuses a token until this many seconds before its `exp`, then fetches a
871
+ * fresh one (the renewal-offset pattern: MSAL's `tokenRenewalOffsetSeconds`, Go oauth2's
872
+ * `expiryDelta`). Default 30. Set 0 to drop the margin entirely: a token is then reused
873
+ * until `exp` itself, which is not the same as always fetching — it is the case the margin
874
+ * exists for, a token handed out a moment before it expires and rejected by the backend it
875
+ * is sent to.
2573
876
  */
2574
- expired?: boolean;
2575
- };
2576
- /** What the wallet menu hands a form to actually move the money. */
2577
- type FluentTokenTransferSender = (request: FluentTokenTransferRequest) => Promise<FluentTokenTransferOutcome>;
2578
- declare const fluentTransferAbi: readonly [{
2579
- readonly name: "transfer";
2580
- readonly type: "function";
2581
- readonly stateMutability: "nonpayable";
2582
- readonly inputs: readonly [{
2583
- readonly type: "address";
2584
- readonly name: "to";
2585
- }, {
2586
- readonly type: "uint256";
2587
- readonly name: "amount";
2588
- }];
2589
- readonly outputs: readonly [{
2590
- readonly type: "bool";
2591
- }];
2592
- }];
2593
- type FluentTransferRecipient = {
2594
- status: "ok";
2595
- address: Address;
2596
- } | {
2597
- status: "empty";
2598
- } | {
2599
- status: "rejected";
2600
- message: string;
2601
- };
2602
- /**
2603
- * The address a transfer would pay. Rejected rather than merely unparsed for
2604
- * the two destinations that look valid and still lose the money: the sending
2605
- * account itself, and a token's own contract.
2606
- */
2607
- declare function parseFluentTransferRecipient(params: {
2608
- input: string;
2609
- /** The account the funds leave, which can never be where they arrive. */
2610
- self?: string;
2611
- /** Contract addresses of the listed tokens, lowercased. */
2612
- contracts?: ReadonlySet<string>;
2613
- }): FluentTransferRecipient;
2614
- type FluentTransferAmount = {
2615
- status: "ok";
2616
- raw: bigint;
2617
- } | {
2618
- status: "empty";
2619
- } | {
2620
- status: "rejected";
2621
- message: string;
877
+ authTokenRenewalOffsetSeconds?: number;
878
+ /** Images for the widget; see `FluentWidgetAssets`. */
879
+ assets?: Partial<FluentWidgetAssets>;
880
+ /** The account avatar shown on the connect button and in the account drawer. */
881
+ avatar?: {
882
+ /**
883
+ * Image used when there is no X avatar to show — a URL or a data URI.
884
+ * Defaults to the Fluent mark.
885
+ */
886
+ defaultLogoUrl?: string;
887
+ /**
888
+ * Always show `defaultLogoUrl`, even for users who signed in with X.
889
+ * Default `false` (the linked X picture wins when the person has one).
890
+ */
891
+ forceDefault?: boolean;
892
+ };
2622
893
  };
894
+
2623
895
  /**
2624
- * The amount a transfer would move, in the token's own base units.
896
+ * One wallet the connect dialog offers inline, as a host's `FluentExternalWalletState` lists it.
2625
897
  *
2626
- * `balance` is required and not nullable on purpose: every answer here is
2627
- * checked against it, so a caller whose balance has not arrived yet has nothing
2628
- * to validate against and must wait rather than pass a stand-in.
898
+ * @experimental May change or be removed in a minor release: a host that brings its own wallet
899
+ * connection is not a 0.6.0 commitment.
2629
900
  */
2630
- declare function parseFluentTransferAmount(params: {
2631
- input: string;
2632
- symbol: string;
2633
- decimals: number;
2634
- balance: bigint;
2635
- }): FluentTransferAmount;
2636
- type FluentTransferFee = {
2637
- status: "ok";
2638
- }
2639
- /** Worth saying, but the send may still succeed. */
2640
- | {
2641
- status: "warning";
2642
- message: string;
2643
- }
2644
- /** This send cannot pay its fee. Nothing to do but change something first. */
2645
- | {
2646
- status: "blocked";
2647
- message: string;
901
+ type FluentWalletChoice = {
902
+ id: string;
903
+ name: string;
904
+ icon?: string;
905
+ /** This connector opens an external wallet/QR surface. */
906
+ handoff?: boolean;
2648
907
  };
2649
908
  /**
2650
- * Whether the account can pay for this transfer's fee.
2651
- *
2652
- * Not a gas estimate — nothing here knows what the operation will cost. It
2653
- * answers the one question that needs no estimate to answer: whether there is
2654
- * any of the fee token at all. A send that empties the fee token's own balance
2655
- * is left to the review and the chain, as any other operation is.
909
+ * An External wallet as the widget sees it: whether one is connected, its address, chain and
910
+ * client, and how to open, connect, switch and disconnect it. Its inline choices are
911
+ * `FluentWalletChoice`s.
2656
912
  *
2657
- * "Blocked" and "warning" are the same facts under different gas paths.
2658
- * Sponsorship covers native gas only — an ERC-20 fee is charged by that token's
2659
- * own paymaster, which the App's paymaster never stands in for — so an empty
2660
- * balance is certain failure there and merely likely failure on the native
2661
- * path of a sponsoring App.
913
+ * @experimental May change or be removed in a minor release: a host that brings its own wallet
914
+ * connection is not a 0.6.0 commitment.
2662
915
  */
2663
- declare function checkFluentTransferFee(params: {
2664
- /** The token the fee will be charged in, already resolved for this account. */
2665
- feeToken: FluentDisplayToken;
2666
- /** Its balance, or null while it is unread. */
2667
- feeBalance: bigint | null;
916
+ type FluentExternalWalletState = {
917
+ configured: boolean;
918
+ connected: boolean;
919
+ address?: string;
920
+ chainId?: number;
921
+ walletClient?: WalletClient;
2668
922
  /**
2669
- * Roughly what that balance is worth in wei, where the App configured
2670
- * `gasPayment.ethValueByToken`. Without rates there is no way to call a
2671
- * non-zero balance too small, and this stays undefined.
923
+ * True while the wallet is being restored from a previous visit and neither
924
+ * `connected` nor "no wallet" is known yet. Optional so hosts supplying their
925
+ * own wallet state keep working; omitting it just means the widget reports
926
+ * `"disconnected"` slightly earlier during a reload.
2672
927
  */
2673
- feeBalanceEthValue?: bigint | null;
2674
- /** True where the App's paymaster may cover a native-gas operation. */
2675
- sponsorshipAvailable: boolean;
2676
- }): FluentTransferFee;
2677
- /**
2678
- * The one call that moves `amount` of `token` to `to`: a plain value send for
2679
- * the chain's own currency, an ERC-20 `transfer` for everything else.
2680
- */
2681
- declare function buildFluentTransferCall(params: {
2682
- token: Pick<FluentTokenDefinition, "address" | "symbol" | "native">;
2683
- to: Address;
2684
- amount: bigint;
2685
- }): FluentBatchCallInput;
2686
-
2687
- /** One JSON-RPC request as the embedded page sends it: method plus positional params. */
2688
- type FluentIframeRpcRequest = {
2689
- method: string;
2690
- params?: unknown[];
2691
- };
2692
- /**
2693
- * The widget surface answering an embedded page's wallet calls needs. Every field is
2694
- * injected so the handler is pure: it never reads the DOM or React state on its own.
2695
- */
2696
- type FluentIframeRpcExecutor = {
2697
- /** Read at call time: the account changes while the bridge lives. */
2698
- account: () => FluentWidgetAccount;
2699
- chainId: number;
2700
- sign: FluentSignApi;
2701
- sendCalls: (calls: FluentEncodedBatchCall[]) => Promise<FluentExecuteResult>;
2702
- /** Read-only chain access for the methods the wallet does not answer itself. */
2703
- rpc: (method: string, params?: unknown[]) => Promise<unknown>;
2704
- };
2705
- type FluentIframeRpcHandler = (request: FluentIframeRpcRequest) => Promise<unknown>;
2706
- /**
2707
- * An error the embedded page understands: EIP-1193 provider codes (4001 user rejected,
2708
- * 4100 unauthorized, 4200 unsupported method) and EIP-1474 JSON-RPC codes (-32602
2709
- * invalid params, -32603 internal error).
2710
- */
2711
- declare class FluentIframeRpcError extends Error {
2712
- readonly code: number;
2713
- constructor(code: number, message: string);
2714
- }
2715
- declare function createFluentIframeRpcHandler(executor: FluentIframeRpcExecutor): FluentIframeRpcHandler;
2716
- /** The part of a `message` event the bridge reads; named so tests can build one without a DOM. */
2717
- type FluentIframeMessageEvent = {
2718
- origin: string;
2719
- source: unknown;
2720
- data: unknown;
2721
- };
2722
- type MessageListener = (event: FluentIframeMessageEvent) => void;
2723
- /** Where the bridge listens for the iframe's messages; `window` outside tests. */
2724
- type FluentIframeListenTarget = {
2725
- addEventListener: (type: "message", listener: MessageListener) => void;
2726
- removeEventListener: (type: "message", listener: MessageListener) => void;
928
+ reconnecting?: boolean;
929
+ /** Optional inline choices; hosts without them keep their existing open() picker. */
930
+ choices?: readonly FluentWalletChoice[];
931
+ connectChoice?: (id: string) => Promise<void>;
932
+ open: () => void;
933
+ disconnect: () => void;
934
+ switchChain: (chainId: number) => Promise<void>;
2727
935
  };
2728
936
  /**
2729
- * The iframe element, reduced to the window the bridge replies to. Read on every
2730
- * message, so an element swapped in later is picked up without rebuilding the bridge.
937
+ * Top-level connection state of the widget, safe to read on any render.
938
+ *
939
+ * The distinction that matters is `"restoring"` vs `"disconnected"`: a session
940
+ * restored from a previous visit is not known synchronously, so a host that
941
+ * treats "not connected yet" as "no account" will render a Connect button at
942
+ * users who do have a live session. Wait out `"restoring"` instead.
943
+ *
944
+ * - `"restoring"` — a previous session may exist; nothing is decided yet.
945
+ * - `"connecting"` — a sign-in the user started is in flight.
946
+ * - `"connected"` — an account is available. Whether it can send transactions
947
+ * *right now* is a separate question — see `widget.account.executionStatus`.
948
+ * - `"disconnected"` — no account, and none is being restored or negotiated.
2731
949
  */
2732
- type FluentIframeElement = {
2733
- contentWindow: {
2734
- postMessage: (message: unknown, targetOrigin: string) => void;
2735
- } | null;
2736
- };
2737
- type FluentIframeBridgeOptions = {
2738
- /**
2739
- * The exact origin the marketplace is served from. Messages from any other origin are
2740
- * dropped without a reply: `@ledgerhq/iframe-provider` posts with `targetOrigin "*"`
2741
- * and checks nothing itself, so this is the only origin check in the exchange.
2742
- */
2743
- allowedOrigin: string;
2744
- executor: FluentIframeRpcExecutor;
2745
- listenOn?: FluentIframeListenTarget;
2746
- };
2747
- type FluentIframeBridge = {
2748
- /** Tell the iframe who is signed in now: `[]` on sign-out. */
2749
- notifyAccountsChanged: (accounts: readonly Address[]) => void;
2750
- notifyChainChanged: (chainId: number) => void;
2751
- /**
2752
- * Stop listening and stop notifying. A request accepted before this is still answered,
2753
- * so a review confirmed after the host unmounts does not leave the iframe waiting.
2754
- */
2755
- dispose: () => void;
2756
- };
950
+ type FluentWidgetStatus = "restoring" | "connecting" | "connected" | "disconnected";
951
+
2757
952
  /**
2758
- * Answers an embedded page's EIP-1193 calls with the widget, over the JSON-RPC 2.0
2759
- * `postMessage` protocol `@ledgerhq/iframe-provider` speaks, which marketplace
2760
- * white-label frontends embed: a request is `{jsonrpc, id, method, params}` posted to `window.parent`, the reply
2761
- * carries the same `id` with `result` or `error`, and events are `{jsonrpc, method, params}`
2762
- * without an `id`.
953
+ * Why `getAuthToken()`, `linkX()`, or `widget.signMessage()` / `widget.signTypedData()` was
954
+ * refused (the signatures throw `not_connected` and `root_signer_required`). The codes are the
955
+ * SDK's own, named for the product rather than for a vendor or a mechanism: where the service
956
+ * answers with a code of its own, the SDK maps it here before it reaches the App, and a service
957
+ * code the SDK does not name reaches `getAuthToken()` as `service_refused` and `linkX()` as
958
+ * `link_failed`. Keep a `default` branch in a
959
+ * `switch` over them: a later release may add a code.
2763
960
  */
2764
- declare function createFluentIframeBridge(iframe: FluentIframeElement, options: FluentIframeBridgeOptions): FluentIframeBridge;
2765
-
961
+ 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";
2766
962
  /**
2767
- * The user dismissed a review (transaction or signature) instead of confirming it.
2768
- * A class, not a message, so callers that translate errors for another party — the
2769
- * iframe bridge maps it to EIP-1193 `4001` — can recognise it without parsing prose.
963
+ * A refused Auth token or X link. `code` is a `FluentAuthErrorCode`; `status` is the service's
964
+ * HTTP status when the service refused it.
2770
965
  */
2771
- declare class FluentReviewRejectedError extends Error {
2772
- readonly review: "transaction" | "signature";
2773
- constructor(review: "transaction" | "signature");
966
+ declare class FluentAuthError extends Error {
967
+ readonly code: FluentAuthErrorCode;
968
+ readonly status?: number | undefined;
969
+ constructor(code: FluentAuthErrorCode, message: string, status?: number | undefined);
2774
970
  }
2775
971
 
2776
- type UseFluentIframeBridgeOptions = {
2777
- /** The exact origin the embedded page is served from; see `createFluentIframeBridge`. */
2778
- allowedOrigin: string;
972
+ /** One X account as the Fluent auth service reports it. */
973
+ type FluentXAccount = {
974
+ id: string;
975
+ handle: string;
976
+ avatarUrl: string;
2779
977
  };
2780
978
  /**
2781
- * Lets a page embedded in `iframeRef` use the account signed in here, over the
2782
- * JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The bridge lives
2783
- * while the component is mounted; the bridge states the chain and account before its
2784
- * first reply, and sign-in and sign-out reach the iframe as `accountsChanged`.
979
+ * What a `linkX()` resolves: `linked` with the Linked X account, or `redirecting` while the page
980
+ * leaves for X.
2785
981
  */
2786
- declare function useFluentIframeBridge(iframeRef: RefObject<FluentIframeElement | null>, { allowedOrigin }: UseFluentIframeBridgeOptions): void;
2787
-
2788
- type FluentWidgetConnectButtonProps = {
2789
- connected: boolean;
2790
- /** Preparing the account after sign-in — disables the button and shows a spinner. */
2791
- pending?: boolean;
2792
- addressLabel?: string;
2793
- onClick: () => void;
2794
- className?: string;
2795
- userLogoUrl?: string | null;
2796
- /** Shown instead of the Fluent mark when there is no `userLogoUrl` — a URL or a data URI. */
2797
- defaultLogoUrl?: string | null;
982
+ type FluentLinkXResult = {
983
+ status: "linked";
984
+ x: FluentXAccount;
985
+ }
986
+ /** The page is leaving for X. Call linkX() again after the return; useLinkX() does it on mount. */
987
+ | {
988
+ status: "redirecting";
2798
989
  };
2799
- /** Default Fluent Connect / account button — place it anywhere in your layout. */
2800
- declare function FluentWidgetConnectButton({ connected, pending, addressLabel, onClick, className, userLogoUrl, defaultLogoUrl, }: FluentWidgetConnectButtonProps): React.JSX.Element;
2801
990
 
2802
- declare const FLUENT_ZERODEV_ERC20_PAYMASTER_QUERY = "selfFunded=true";
2803
- declare const FLUENT_ZERODEV_PAYMASTER_DEMO_RECIPIENT: "0x000000000000000000000000000000000000dEaD";
2804
- type FluentZeroDevErc20PaymasterTokenInfo = {
2805
- address: Address;
2806
- decimals: number;
2807
- symbol: string;
2808
- };
2809
- declare function getFluentZeroDevErc20PaymasterTokens(network?: FluentWidgetNetwork): Record<string, FluentZeroDevErc20PaymasterTokenInfo>;
2810
- /**
2811
- * Either a paymaster token symbol (see `getFluentZeroDevErc20PaymasterTokens`),
2812
- * a bare token address, or an explicit token. Symbols are not a closed union:
2813
- * which tokens are payable is data on the token definitions.
2814
- */
2815
- type FluentZeroDevErc20PaymasterToken = string | {
2816
- address: Address;
2817
- symbol?: string;
2818
- };
2819
- type FluentZeroDevPaymasterKernel = {
2820
- account: SmartAccount;
2821
- publicClient: Parameters<typeof createKernelAccountClient>[0]["client"];
2822
- smartAccountAddress: Address;
2823
- zeroDevRpcUrl: string;
2824
- };
2825
- type FluentZeroDevPaymasterDemoResult = {
2826
- approvalIncluded: boolean;
2827
- gasToken: Address;
2828
- gasTokenSymbol?: string;
2829
- paymasterRpcUrl: string;
2830
- transactionHash: Hash;
2831
- userOpHash: Hash;
2832
- };
2833
- /**
2834
- * The ZeroDev bundler URL for one chain. `chainId` defaults to Fluent Testnet, and `projectId`
2835
- * to the Fluent ZeroDev project of the network that chain id belongs to — the testnet project
2836
- * for 20994, the production one for 25363 — so a host that passes a chain id gets that
2837
- * network's project without naming it. Pass `projectId` to use your own ZeroDev project, and
2838
- * `selfFunded` for the ERC-20 paymaster form.
2839
- *
2840
- * @example
2841
- * const rpcUrl = createFluentZeroDevRpcUrl({ chainId: 25363 });
2842
- */
2843
- declare function createFluentZeroDevRpcUrl(params?: {
2844
- chainId?: number;
2845
- projectId?: string;
2846
- selfFunded?: boolean;
2847
- }): string;
2848
- declare function createFluentZeroDevErc20PaymasterRpcUrl(params?: {
2849
- chainId?: number;
2850
- projectId?: string;
2851
- }): string;
2852
- /** The App travels in the path, the user's Fluent token in the `Authorization` header. */
2853
- declare function createFluentSponsorshipRpcUrl(params: {
2854
- sponsorshipUrl: string;
2855
- appId: string;
2856
- }): string;
2857
991
  /**
2858
- * The sponsorship paymaster for one user. `bearerToken` is the Fluent token that
2859
- * `getAuthToken()` mints: the service binds its `aud` to the App and the UserOp `sender` to an
2860
- * address this user proved, and a Privy access token carries neither binding.
992
+ * A token a host adds to the list the widget shows: an Integrator token. It describes the token
993
+ * and grants nothing — whether a token can pay for gas is a property only Default tokens have
994
+ * (ADR 0001), so the widget would strip any such field from a host's token anyway.
2861
995
  */
2862
- declare function createFluentZeroDevSponsoredPaymaster(params: {
2863
- chain: Chain;
2864
- rpcUrl: string;
2865
- bearerToken: string;
2866
- }): {
2867
- getPaymasterData: (userOperation: GetPaymasterDataParameters) => Promise<_zerodev_sdk.SponsorUserOperationReturnType>;
2868
- };
2869
- declare function resolveFluentZeroDevErc20PaymasterToken(token?: FluentZeroDevErc20PaymasterToken, network?: FluentWidgetNetwork): {
2870
- address: Address;
2871
- symbol?: string;
2872
- };
2873
- declare function createFluentZeroDevErc20PaymasterClient(params?: {
2874
- chain?: Chain;
2875
- paymasterRpcUrl?: string;
2876
- }): {
2877
- account: SmartAccount | undefined;
2878
- batch?: {
2879
- multicall?: boolean | viem.Prettify<viem.MulticallBatchOptions> | undefined;
2880
- } | undefined;
2881
- cacheTime: number;
2882
- ccipRead?: false | {
2883
- request?: (parameters: viem.CcipRequestParameters) => Promise<`0x${string}`>;
2884
- } | undefined;
2885
- chain: Chain | undefined;
2886
- dataSuffix?: viem.DataSuffix | undefined;
2887
- experimental_blockTag?: viem.BlockTag | undefined;
2888
- key: string;
996
+ type FluentTokenDefinition = {
997
+ /** The chain the token lives on. The widget does not filter by it: pass the Network's tokens. */
998
+ chainId: number;
999
+ /** The token's contract address; absent for the chain's native token. */
1000
+ address?: Address;
2889
1001
  name: string;
2890
- pollingInterval: number;
2891
- request: viem.EIP1193RequestFn<_zerodev_sdk.ZeroDevPaymasterRpcSchema<"0.7">>;
2892
- transport: viem.TransportConfig<string, viem.EIP1193RequestFn> & Record<string, any>;
2893
- type: string;
2894
- uid: string;
2895
- getPaymasterData: (parameters: GetPaymasterDataParameters) => Promise<viem_account_abstraction.GetPaymasterDataReturnType>;
2896
- getPaymasterStubData: (parameters: viem_account_abstraction.GetPaymasterStubDataParameters) => Promise<viem_account_abstraction.GetPaymasterStubDataReturnType>;
2897
- sponsorUserOperation: (args: _zerodev_sdk.SponsorUserOperationParameters) => Promise<_zerodev_sdk.SponsorUserOperationReturnType>;
2898
- estimateGasInERC20: (args: _zerodev_sdk_actions.EstimateGasInERC20Parameters) => Promise<_zerodev_sdk_actions.EstimateGasInERC20ReturnType>;
2899
- extend: <const client extends {
2900
- [x: string]: unknown;
2901
- account?: undefined;
2902
- batch?: undefined;
2903
- cacheTime?: undefined;
2904
- ccipRead?: undefined;
2905
- chain?: undefined;
2906
- dataSuffix?: undefined;
2907
- experimental_blockTag?: undefined;
2908
- key?: undefined;
2909
- name?: undefined;
2910
- pollingInterval?: undefined;
2911
- request?: undefined;
2912
- transport?: undefined;
2913
- type?: undefined;
2914
- uid?: undefined;
2915
- } & viem.ExactPartial<Pick<viem.PublicActions<viem.Transport, Chain | undefined, SmartAccount | undefined>, "prepareTransactionRequest" | "call" | "createContractEventFilter" | "createEventFilter" | "estimateContractGas" | "estimateGas" | "getBlock" | "getBlockNumber" | "getChainId" | "getContractEvents" | "getEnsText" | "getFilterChanges" | "getGasPrice" | "getLogs" | "getTransaction" | "getTransactionCount" | "getTransactionReceipt" | "readContract" | "sendRawTransaction" | "simulateContract" | "uninstallFilter" | "watchBlockNumber" | "watchContractEvent"> & Pick<viem.WalletActions<Chain | undefined, SmartAccount | undefined>, "sendTransaction" | "writeContract">>>(fn: (client: viem.Client<viem.Transport, Chain | undefined, SmartAccount | undefined, _zerodev_sdk.ZeroDevPaymasterRpcSchema<"0.7">, viem_account_abstraction.PaymasterActions & _zerodev_sdk.ZeroDevPaymasterClientActions>) => client) => viem.Client<viem.Transport, Chain | undefined, SmartAccount | undefined, _zerodev_sdk.ZeroDevPaymasterRpcSchema<"0.7">, { [K in keyof client]: client[K]; } & viem_account_abstraction.PaymasterActions & _zerodev_sdk.ZeroDevPaymasterClientActions>;
2916
- };
2917
- declare function createFluentZeroDevErc20Paymaster(params: {
2918
- chain?: Chain;
2919
- gasToken?: FluentZeroDevErc20PaymasterToken;
2920
- network?: FluentWidgetNetwork;
2921
- paymasterClient?: ZeroDevPaymasterClient;
2922
- paymasterRpcUrl?: string;
2923
- }): {
2924
- getPaymasterData: (userOperation: GetPaymasterDataParameters) => Promise<_zerodev_sdk.SponsorUserOperationReturnType>;
2925
- };
2926
- declare function createFluentZeroDevErc20PaymasterApprovalCall(params: {
2927
- approveAmount: bigint;
2928
- chain?: Chain;
2929
- gasToken?: FluentZeroDevErc20PaymasterToken;
2930
- network?: FluentWidgetNetwork;
2931
- paymasterClient?: ZeroDevPaymasterClient;
2932
- paymasterRpcUrl?: string;
2933
- }): Promise<{
2934
- to: Address;
2935
- value: bigint;
2936
- data: Hex;
2937
- }>;
2938
- type FluentZeroDevPaymasterDemoApproval = {
2939
- includeApproval: true;
2940
- approveAmount: bigint;
2941
- } | {
2942
- includeApproval?: false;
2943
- approveAmount?: never;
1002
+ symbol: string;
1003
+ decimals: number;
1004
+ /** An image for the token, a URL or a data URI. */
1005
+ logoURI?: string;
2944
1006
  };
2945
- declare function sendFluentZeroDevErc20PaymasterDemo(params: {
2946
- chain?: Chain;
2947
- gasToken?: FluentZeroDevErc20PaymasterToken;
2948
- kernel: FluentZeroDevPaymasterKernel;
2949
- network?: FluentWidgetNetwork;
2950
- paymasterRpcUrl?: string;
2951
- testRecipient?: Address;
2952
- } & FluentZeroDevPaymasterDemoApproval): Promise<{
2953
- approvalIncluded: boolean;
2954
- gasToken: `0x${string}`;
2955
- gasTokenSymbol: string | undefined;
2956
- paymasterRpcUrl: string;
2957
- transactionHash: `0x${string}`;
2958
- userOpHash: `0x${string}`;
2959
- }>;
2960
1007
 
2961
1008
  /**
2962
- * Privy promotes the last-used login method to the top of its modal via
2963
- * localStorage. Fluent Connect always wants X first (email in overflow), so
2964
- * clear these keys before mounting/opening Privy login.
1009
+ * What the widget hands an App's own content: the Widget session, the Widget API, the External
1010
+ * wallet, and the calls that open the widget's screens, disconnect, mint an Auth token and link
1011
+ * X. `renderHome` and `renderPage` receive it, and `useFluentWidget()` returns it.
2965
1012
  */
2966
- declare function clearPrivyRecentLoginMethod(appId: string): void;
2967
-
2968
- interface FluentAccountDrawerProps {
2969
- accountOpen: boolean;
2970
- setAccountOpen: (open: boolean | ((current: boolean) => boolean)) => void;
2971
- hasConnectedAccount: boolean;
2972
- isMobile: boolean;
2973
- connectButton: ReactNode;
2974
- accountMenuAddress?: string;
2975
- onAccountMenuAction: (value: string | null) => void;
1013
+ type FluentWidgetRenderContext = {
2976
1014
  /**
2977
- * Title of the sub-page currently replacing the wallet menu (Settings,
2978
- * Deposit, …). Set it and the header becomes a back
2979
- * button plus this title.
1015
+ * Who is signed in, or `null`: a `FluentWidgetSession`. Once `onSessionChange` has fired on
1016
+ * this page, equal to (not the same object as) the last value it received; a session restored
1017
+ * from storage is here before any callback. Connecting an External wallet neither writes nor
1018
+ * clears it; read the connected account from `widget.account`.
2980
1019
  */
2981
- subPageTitle?: string | null;
2982
- onCloseSubPage?: () => void;
1020
+ session: FluentWidgetSession | null;
1021
+ /** The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. */
1022
+ userAvatarUrl?: string;
2983
1023
  /**
2984
- * How the sub-page is left: `back` is a chevron on the left that walks up the
2985
- * stack; `close` is an X on the right, for a page that stands alone, such as
2986
- * a review the user is answering.
1024
+ * The display name of the person's linked X account, the name X shows above the handle, not
1025
+ * the handle. Absent when no X account is linked or X reports no name for it, and while an
1026
+ * External wallet is connected without a Fluent ID. `avatar.forceDefault` does not hide it.
2987
1027
  */
2988
- subPageDismiss?: "back" | "close";
2989
- /** @deprecated Pass `subPageTitle="Settings"` and `onCloseSubPage` instead. */
2990
- settingsOpen?: boolean;
2991
- /** @deprecated Renamed to `onCloseSubPage`. */
2992
- onCloseSettings?: () => void;
2993
- /** Preview harnesses relax these to keep the drawer pinned open; the widget keeps the modal defaults. */
2994
- modal?: boolean | "trap-focus";
2995
- disablePointerDismissal?: boolean;
2996
- children: ReactNode;
2997
- userLogoUrl?: string | null;
2998
- /** Shown instead of the Fluent mark when there is no `userLogoUrl` — a URL or a data URI. */
2999
- defaultLogoUrl?: string | null;
3000
- }
3001
- /**
3002
- * The connected-account drawer shell: the connect-button trigger, the account
3003
- * header/actions menu (explorer / copy / settings /
3004
- * disconnect), and a slot (`children`) for the wallet menu card. Rendered
3005
- * whenever the widget has a connected account.
3006
- */
3007
- declare function FluentAccountDrawer({ accountOpen, setAccountOpen, hasConnectedAccount, isMobile, connectButton, accountMenuAddress, onAccountMenuAction, subPageTitle, onCloseSubPage, subPageDismiss, settingsOpen, onCloseSettings, modal, disablePointerDismissal, children, userLogoUrl, defaultLogoUrl, }: FluentAccountDrawerProps): React.JSX.Element;
3008
-
3009
- /** Colour scheme and design tokens for the widget's own UI — never around host content. */
3010
- declare const WIDGET_STYLE_SCOPE = "fluent-root dark contents text-foreground";
3011
- /**
3012
- * Provides the element widget overlays portal into, so they inherit the widget's
3013
- * scope instead of landing on a bare `<body>` outside every token definition.
3014
- *
3015
- * The element is attached to `document.body` rather than rendered into the React
3016
- * tree on purpose: overlays position themselves with `position: fixed`, and a
3017
- * host mounting `<FluentWidget>` inside an element with `transform`, `filter` or
3018
- * `contain` would turn that ancestor into their containing block and misplace
3019
- * every one of them.
3020
- *
3021
- * Alongside it lives `dialog[data-fluent-top-layer]`, the host for the widget's
3022
- * modal overlays. A host app that opens its own dialog with `showModal()` puts
3023
- * it in the browser's top layer and makes the rest of the document inert — any
3024
- * overlay we keep in the normal document is then covered and unclickable. Modal
3025
- * overlays therefore portal into this `<dialog>`, and the first one to open
3026
- * calls `showModal()` on it: it becomes the topmost modal, painted above the
3027
- * host's dialog and exempt from its inertness. Elements in the top layer are
3028
- * laid out against the viewport regardless of ancestors, so the `body`
3029
- * constraint above is preserved for free.
3030
- */
3031
- declare function FluentPortalContainerProvider({ children }: {
3032
- children: ReactNode;
3033
- }): React.JSX.Element;
3034
-
3035
- type FluentAnalyticsSendOptions = {
3036
- /** The page is going away — this event has to leave before the tab does. */
3037
- unload?: boolean;
3038
- };
3039
- type FluentAnalyticsTrack = {
3040
- (eventName: string, properties?: Record<string, unknown>, options?: FluentAnalyticsSendOptions): void;
3041
- /** False when analytics is off for this config, so every call is a no-op. */
3042
- live?: boolean;
3043
- };
3044
-
3045
- type FluentUsdnrMintOutcome = {
3046
- status: "minted";
3047
- hash: Hash;
3048
- }
3049
- /** The person dismissed the review. Not a failure, and nothing to report. */
3050
- | {
3051
- status: "rejected";
3052
- } | {
3053
- status: "failed";
3054
- message: string;
3055
- }
3056
- /**
3057
- * The press built nothing, because a mint was already in flight. Its own
3058
- * status rather than a silent `undefined`: a caller counting operations — the
3059
- * double-press this guards against — needs to see that one was refused.
3060
- */
3061
- | {
3062
- status: "skipped";
3063
- };
3064
- /**
3065
- * What the wallet menu's Get USDnr button runs on testnet. The widget hands one
3066
- * in; the card holds no execution of its own.
3067
- */
3068
- type FluentUsdnrMinter = (recipient: Address) => Promise<FluentUsdnrMintOutcome>;
3069
-
3070
- interface WalletMenuActionCardProps {
3071
- track: FluentAnalyticsTrack;
3072
- session: FluentWidgetSession | null;
3073
- smartAccountAddress?: string;
3074
- faucetBusy: boolean;
3075
- onFaucet: () => void;
3076
- config: FluentWidgetConfig;
3077
- tokens?: readonly FluentTokenDefinition[];
3078
- gasPaymentToken: FluentGasTokenSymbol;
3079
- onGasPaymentTokenChange: (token: FluentGasTokenSymbol) => void;
3080
- silentSigningEnabled: boolean;
3081
- onSilentSigningChange: (enabled: boolean) => void;
3082
- onDisconnect: () => void;
3083
- onConnectWithX: () => void;
3084
- tab: string;
3085
- onTabChange: (tab: string) => void;
1028
+ userXDisplayName?: string;
1029
+ /**
1030
+ * The name on the Google account linked to the person's Direct login. Absent when none is
1031
+ * linked or Google reports no name for it, and while an External wallet is connected without a
1032
+ * Fluent ID. `avatar.forceDefault` does not hide it.
1033
+ */
1034
+ userGoogleName?: string;
1035
+ /**
1036
+ * The External wallet as the widget sees it, a `FluentExternalWalletState` whose inline
1037
+ * choices are `FluentWalletChoice`s, or `null`.
1038
+ *
1039
+ * @experimental May change or be removed in a minor release: a host that brings its own wallet
1040
+ * connection is not a 0.6.0 commitment.
1041
+ */
1042
+ wallet: FluentExternalWalletState | null;
1043
+ /** The Widget API: the account, Batch operations, signatures and the current Gas payment. */
1044
+ widget: FluentBatchApi;
3086
1045
  /**
3087
- * Which Home panel is showing, "tokens" or "activity". Optional, and only
3088
- * because the preview harnesses render this card outside a drawer; the widget
3089
- * must pass it, or a panel opened for a settled transfer dies with the card
3090
- * the review modal unmounted.
1046
+ * Opens the sign-in dialog, the same one the connect button opens. A click event passed to it
1047
+ * is ignored, so it can be handed straight to `onClick`.
3091
1048
  */
3092
- panel?: string;
3093
- onPanelChange?: (panel: string) => void;
3094
- /** The connected account address shown in the header (external EOA or Fluent smart account). */
3095
- connectedAddress?: string;
1049
+ openConnect: () => void;
1050
+ /** Opens the account drawer, as the connect button does once a Widget account is connected. */
1051
+ openAccount: () => void;
3096
1052
  /**
3097
- * Which account this menu is for. An External wallet (`"eoa"`) confirms every
3098
- * call in the wallet itself and pays the chain's own gas, so it has neither
3099
- * Quick sign nor a Gas token to choose and no Fluent smart account to claim a
3100
- * faucet for; Settings shows both preferences disabled, hides Faucet and
3101
- * sends Explorer to the EOA's own address.
1053
+ * Tear down the current session without going through the widget's account
1054
+ * menu — the same teardown that menu's "Disconnect" runs. The session and the
1055
+ * stored identity token are cleared before this resolves, so a host can await
1056
+ * it before resetting its own state.
3102
1057
  *
3103
- * Optional, and absent reads as a Fluent ID: this card is exported
3104
- * (`src/index.ts`), and the preview harnesses mount it with no account at all.
1058
+ * It also asks the service to revoke the Service session, and any Service session that a
1059
+ * `getAuthToken()` still out at the disconnect opens later, and resolves once those requests
1060
+ * have been answered or have failed, so it can take as long as that `getAuthToken()` does. A
1061
+ * failed revocation is not retried: the promise resolving does not prove the service ended
1062
+ * the Service session.
3105
1063
  */
3106
- accountKind?: FluentAccountType;
3107
- /** The External wallet that signs bridge deposits, while one is connected. */
3108
- externalWalletAddress?: string;
3109
- /** Bumped after a confirmed widget transaction so balances refetch. */
3110
- balanceRevisionCounter?: number;
1064
+ disconnect: () => Promise<void>;
3111
1065
  /**
3112
- * Where this person's hand-added tokens live. The service's store while the
3113
- * widget holds a Fluent token, this browser's otherwise.
1066
+ * Whether a Widget account, a Fluent ID or an External wallet, is connected now. `false`
1067
+ * while a stored session is still being restored: branch on `status` to tell that apart.
3114
1068
  */
3115
- userTokenStore?: UserTokenStore;
1069
+ hasConnectedAccount: boolean;
3116
1070
  /**
3117
- * True while the stored settings are still on their way. The preferences and
3118
- * the token actions stay disabled so the answer cannot overwrite a choice
3119
- * made while it was in flight.
1071
+ * Connection state as a single value that is meaningful on every render —
1072
+ * including the first, before a stored session has been reconciled. Branch on
1073
+ * this rather than on `hasConnectedAccount` alone: `"restoring"` and
1074
+ * `"disconnected"` both have `hasConnectedAccount === false`, and treating
1075
+ * them alike shows a Connect button to users who are already signed in. The
1076
+ * account's address is `widget.account.address`.
3120
1077
  */
3121
- settingsPending?: boolean;
3122
- /** A preference the service refused to store. */
3123
- settingsError?: string | null;
3124
- /** A token write the service refused. */
3125
- tokenListError?: string | null;
1078
+ status: FluentWidgetStatus;
3126
1079
  /**
3127
- * Moves a token out of this account. Absent where nothing can execute — the
3128
- * preview harnesses render the card outside the widget — and the Send button
3129
- * is then disabled rather than hidden.
1080
+ * Refetch the widget's on-chain balances. Transactions run through
1081
+ * `widget.createBatchOp` refresh automatically; call this after a tx sent via
1082
+ * an External wallet client (outside the widget's execution path).
3130
1083
  */
3131
- onSendToken?: FluentTokenTransferSender;
3132
- /** Transfers sent from here that have not settled yet, listed in Activity. */
3133
- pendingTransfers?: readonly FluentPendingTransfer[];
1084
+ refreshBalances: () => void;
3134
1085
  /**
3135
- * Mints testnet USDnr into this account. On a faucet network Get USDnr runs
3136
- * this instead of opening the Swapper Finance on-ramp, which has nothing to
3137
- * sell on a testnet, and the USDnr contract there mints to whoever asks.
1086
+ * A short-lived (5 min) Auth token, a Fluent-signed JWT for the connected person. Verify it on
1087
+ * your backend against `<iss>/.well-known/jwks.json` (ES256), checking `iss`, `aud` (= your
1088
+ * appId) and `exp`; `sub` is stable per person per App. Reused until
1089
+ * `authTokenRenewalOffsetSeconds` before `exp`, then renewed; a renewal the service accepts
1090
+ * asks the wallet for nothing. When the wallet is asked to sign:
1091
+ * [guides/backend-auth.md](guides/backend-auth.md#renewal). External wallets: EOAs and deployed
1092
+ * smart-contract wallets sign in; a not-yet-deployed smart account cannot (no ERC-6492).
3138
1093
  *
3139
- * Absent where nothing can execute — the preview harnesses render this card
3140
- * outside the widget — and Get USDnr then opens the on-ramp on both networks,
3141
- * under the on-ramp's own rule.
1094
+ * @throws `FluentAuthError`, its `code` one of:
1095
+ * - `not_connected`: no Widget account is connected, or an External wallet has no client
1096
+ * when the call has to sign the Sign-in challenge;
1097
+ * - `login_credential_missing`: a Fluent ID's login left no credential in the page;
1098
+ * - `origin_mismatch`: the Sign-in challenge names an origin other than the page's;
1099
+ * - `request_failed`: the request did not reach the service, its answer carried no code or no
1100
+ * token, or the External wallet refused to sign the Sign-in challenge;
1101
+ * - `service_refused`: the service refused with a code this SDK does not name;
1102
+ * - a code the service answered with: `unknown_app`, `app_not_auth_enabled`,
1103
+ * `origin_not_allowed`, `origin_missing`, `bad_request`, `challenge_unknown`,
1104
+ * `challenge_used`, `challenge_expired`, `app_mismatch`, `invalid_signature`,
1105
+ * `signature_prefix_rejected`, `address_already_linked`, `invalid_login_credential`,
1106
+ * `no_signer`, `rate_limited` or `internal`.
1107
+ *
1108
+ * A refused refresh credential is not among them: the call forgets it and signs in again
1109
+ * within the same call, which can prompt the External wallet. Keep a `default` branch.
3142
1110
  */
3143
- onMintUsdnr?: FluentUsdnrMinter;
1111
+ getAuthToken: () => Promise<string>;
3144
1112
  /**
3145
- * True while a mint is in flight, and the one thing that disables Get USDnr
3146
- * on the mint path. An address that has not arrived yet does not: a press
3147
- * reports it in the status line, the way Send does, which says more than a
3148
- * button nothing explains. Held by the widget rather than here, because the
3149
- * review modal closes the drawer and unmounts this card mid-mint.
1113
+ * Link an X account to the connected person, headless: no widget screen, no settings page,
1114
+ * one call. Idempotent and re-enterable, because linking X needs an OAuth round trip that
1115
+ * leaves the page.
1116
+ *
1117
+ * A person who already has X resolves `{ status: "linked", x }` without leaving the page. A
1118
+ * person who has none resolves `{ status: "redirecting" }` once the navigation to X has
1119
+ * started: the page is unloading, so nothing on it may wait for the link to finish. When the
1120
+ * browser comes back, `useLinkX()` calls `linkX()` again on mount, and it resolves `linked`;
1121
+ * nothing public tells a page that calls `linkX()` itself that it is a return from X.
1122
+ *
1123
+ * A link somebody else started in this tab, or a stale record of one, is discarded rather
1124
+ * than resumed: the call does no work and rejects with `link_failed`; call again to start one
1125
+ * for the signed-in person.
1126
+ *
1127
+ * An External wallet can be asked to sign before either result:
1128
+ * [guides/link-x.md](guides/link-x.md) says when.
1129
+ *
1130
+ * @throws `FluentAuthError`, whose codes today are `user_rejected`,
1131
+ * `linked_to_another_user`, `not_authenticated`, `bad_request` and `link_failed`; keep a
1132
+ * `default` branch for any code a later release adds.
3150
1133
  */
3151
- mintUsdnrBusy?: boolean;
1134
+ linkX: () => Promise<FluentLinkXResult>;
1135
+ };
1136
+ /** What `renderConnectButton` receives to draw its own connect button. */
1137
+ type FluentWidgetConnectButtonRenderContext = {
1138
+ connected: boolean;
1139
+ /** True while a Fluent ID's smart account is being prepared after sign-in. */
1140
+ pending: boolean;
1141
+ addressLabel?: string;
1142
+ /** The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. */
1143
+ userAvatarUrl?: string;
1144
+ /** The person's X display name, the render context's `userXDisplayName`. */
1145
+ userXDisplayName?: string;
1146
+ /** The person's Google name, the render context's `userGoogleName`. */
1147
+ userGoogleName?: string;
1148
+ onClick: () => void;
1149
+ openConnect: () => void;
1150
+ openAccount: () => void;
1151
+ DefaultButton: () => ReactNode;
1152
+ };
1153
+ /** The props of `<FluentWidget>`. */
1154
+ type FluentWidgetProps = {
3152
1155
  /**
3153
- * Brings the account drawer back up. A transaction review closes it on its
3154
- * way in, so without this a transfer that settles has nowhere to report
3155
- * itself. Absent in the preview harnesses, which render the card with no
3156
- * drawer around it.
1156
+ * An External wallet the host connects itself, a `FluentExternalWalletState` whose inline
1157
+ * choices are `FluentWalletChoice`s; omit it to let the widget connect one.
1158
+ *
1159
+ * @experimental May change or be removed in a minor release: a host that brings its own wallet
1160
+ * connection is not a 0.6.0 commitment.
3157
1161
  */
3158
- onRevealAccount?: () => void;
1162
+ wallet?: FluentExternalWalletState | null;
1163
+ config: FluentWidgetConfig;
3159
1164
  /**
3160
- * What pays a transfer's fee, for the Send page's fee selector and warnings.
3161
- * Defaults describe the Fluent smart account with no sponsorship, which is
3162
- * the conservative reading: it warns where a sponsoring App would not need to.
1165
+ * Optional native Privy SDK bridge, a `FluentPrivyAdapter`, for a host that runs Privy's
1166
+ * native SDK; requires Direct login.
1167
+ *
1168
+ * @experimental May change or be removed in a minor release: the one provider seam of the
1169
+ * widget, kept for hosts that run a native login SDK.
3163
1170
  */
3164
- gasContext?: {
3165
- /** False for an external wallet, which has no paymaster to charge a token. */
3166
- erc20Gas: boolean;
3167
- /** True where the App's paymaster may cover a native-gas operation. */
3168
- sponsorshipAvailable: boolean;
3169
- };
1171
+ privyAdapter?: FluentPrivyAdapter;
1172
+ mode?: "home" | "page";
3170
1173
  /**
3171
- * Registers a passkey on the signed-in Fluent ID, so the next sign-in is the
3172
- * dialog's "Continue with passkey" instead of the X round trip. Absent where
3173
- * there is no Privy session on this page to register it on — hosted mode, an
3174
- * External wallet, the preview harnesses — and Settings then has no Security
3175
- * section at all: an action that can only fail is not offered.
1174
+ * Show the default connect/account control.
1175
+ * - `"fixed"` (default) — top-right floating button
1176
+ * - `"inline"` — same button, no fixed positioning (host places via CSS / wrapper)
1177
+ * - `false` — hide; use `renderConnectButton`, `openConnect`, or `openAccount`
3176
1178
  */
3177
- onAddPasskey?: () => Promise<void>;
1179
+ connectButton?: "fixed" | "inline" | false;
1180
+ /** Replace the default connect button UI / placement entirely. */
1181
+ renderConnectButton?: (context: FluentWidgetConnectButtonRenderContext) => ReactNode;
1182
+ renderHome?: (context: FluentWidgetRenderContext) => ReactNode;
1183
+ renderPage?: (context: FluentWidgetRenderContext) => ReactNode;
1184
+ /** Integrator tokens the widget lists beside its Default tokens; see `FluentTokenDefinition`. */
1185
+ tokens?: readonly FluentTokenDefinition[];
3178
1186
  /**
3179
- * The passkeys the signed-in user already has, listed above the Add row so the
3180
- * state reads before the action. What Privy's record says, not the browser's:
3181
- * a credential deleted from a password manager stays listed until it is
3182
- * removed here — WebAuthn gives the server no word of a local deletion.
1187
+ * Print the widget's internal connect / smart-account / signing diagnostics to
1188
+ * the console, and show the debug panel in `mode="home"`. Off by default; turn
1189
+ * on only while debugging an integration.
3183
1190
  */
3184
- passkeys?: readonly FluentSettingsPasskey[];
1191
+ debugLogging?: boolean;
3185
1192
  /**
3186
- * Removes one passkey from the account by its credential id — Privy's record
3187
- * of it; the key in the person's password manager is theirs to delete. Absent
3188
- * hides the per-row remove button, nothing else.
1193
+ * Called each time the widget writes its stored session: with the new `FluentWidgetSession`
1194
+ * when a Fluent ID signs in by Direct login, and with `null` on a disconnect through the
1195
+ * widget. It is not called for a session restored from storage on mount, nor when an External
1196
+ * wallet connects; read the render context's `session` and `widget.account` for those.
3189
1197
  */
3190
- onRemovePasskey?: (credentialId: string) => Promise<void>;
3191
- }
3192
- /** One passkey of the signed-in user, as the Security section lists it. */
3193
- type FluentSettingsPasskey = {
3194
- /** Privy's credential id — the handle `onRemovePasskey` takes. */
3195
- credentialId: string;
3196
- /** Where it lives, as Privy recorded it: "iCloud Keychain", "Chrome on Mac OS X", … */
3197
- label: string;
3198
- /** The day it was added, already formatted for display; absent when Privy has none. */
3199
- addedOn?: string;
1198
+ onSessionChange?: (session: FluentWidgetSession | null) => void;
3200
1199
  };
3201
- declare function WalletMenuActionCard({ track, session, smartAccountAddress, faucetBusy, onFaucet, config, tokens, gasPaymentToken, onGasPaymentTokenChange, silentSigningEnabled, onSilentSigningChange, onDisconnect, onConnectWithX, tab, onTabChange, panel, onPanelChange, connectedAddress, accountKind, externalWalletAddress, balanceRevisionCounter, userTokenStore, settingsPending, settingsError, tokenListError, onSendToken, pendingTransfers, onMintUsdnr, mintUsdnrBusy, onRevealAccount, gasContext, onAddPasskey, passkeys, onRemovePasskey, }: WalletMenuActionCardProps): React.JSX.Element | null;
3202
-
3203
- declare const buttonVariants: (props?: ({
3204
- variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
3205
- size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
3206
- } & class_variance_authority_types.ClassProp) | undefined) => string;
3207
- type ButtonProps = Button$1.Props & VariantProps<typeof buttonVariants> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "target" | "rel">;
3208
- declare const Button: React.ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
1200
+ /**
1201
+ * The Fluent Connect widget: the connect button, the sign-in dialog, the account drawer and the
1202
+ * Widget API, provided to the App's own content rendered through `renderHome` or `renderPage`.
1203
+ *
1204
+ * @throws `FluentWidgetConfigError` from a render when `config` cannot be used, its `code`
1205
+ * `missing_option`, `invalid_option` or `removed_option` with the option named in its message,
1206
+ * or, for the experimental `execution`, `invalid_fee_source`, `invalid_receipt_source` or
1207
+ * `invalid_chain_check_before_sign`. The config is resolved again on every render that passes
1208
+ * a new `config` object, so such a render can throw too; keep `config` stable (a module
1209
+ * constant or a memo) to resolve it once.
1210
+ *
1211
+ * @example
1212
+ * ```tsx
1213
+ * import { FluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
1214
+ *
1215
+ * // The App's id, its login client and the Network: see the configuration guide.
1216
+ * declare const config: FluentWidgetConfig;
1217
+ *
1218
+ * export function App() {
1219
+ * return <FluentWidget config={config} mode="page" renderPage={() => <main>Your App</main>} />;
1220
+ * }
1221
+ * ```
1222
+ */
1223
+ declare function FluentWidget(props: FluentWidgetProps): react.JSX.Element;
3209
1224
 
3210
- declare function Label({ className, ...props }: React.ComponentProps<"label">): React.JSX.Element;
1225
+ /**
1226
+ * Access the Fluent widget render context from any component rendered inside
1227
+ * `<FluentWidget>` (e.g. within `renderHome` / `renderPage`). Returns the same
1228
+ * object the render props receive — `session`, `widget`, `openConnect`, etc. —
1229
+ * so host apps no longer need to prop-drill it. The Widget API is
1230
+ * `useFluentWidget().widget`.
1231
+ *
1232
+ * Throws if used outside `<FluentWidget>`.
1233
+ *
1234
+ * @example
1235
+ * ```tsx
1236
+ * import { useFluentWidget } from "@fluent.xyz/connect";
1237
+ *
1238
+ * const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
1239
+ *
1240
+ * export function Send() {
1241
+ * const { widget, status } = useFluentWidget();
1242
+ * if (status !== "connected") return null;
1243
+ * return <button onClick={() => widget.createBatchOp({ calls }).execute()}>Send</button>;
1244
+ * }
1245
+ * ```
1246
+ */
1247
+ declare function useFluentWidget(): FluentWidgetRenderContext;
3211
1248
 
3212
- declare function Switch({ className, size, ...props }: Switch$1.Root.Props & {
3213
- size?: "sm" | "default";
3214
- }): React.JSX.Element;
1249
+ /** Which Review the person dismissed: a Batch operation's or a signature's. */
1250
+ type FluentReviewRejectedErrorCode = "transaction_review_rejected" | "signature_review_rejected";
1251
+ /**
1252
+ * The person dismissed a Review (transaction or signature) instead of confirming it.
1253
+ *
1254
+ * A class with a `code`, not a message, so a host branches on `code` and callers that translate
1255
+ * errors for another party — the iframe bridge maps it to EIP-1193 `4001` — recognise it
1256
+ * without parsing prose.
1257
+ *
1258
+ * @example
1259
+ * ```ts
1260
+ * import { FluentReviewRejectedError, type FluentBatchApi } from "@fluent.xyz/connect";
1261
+ *
1262
+ * const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
1263
+ *
1264
+ * export async function send(widget: FluentBatchApi) {
1265
+ * try {
1266
+ * await widget.createBatchOp({ calls }).execute();
1267
+ * } catch (error) {
1268
+ * if (error instanceof FluentReviewRejectedError) return; // the person said no
1269
+ * throw error;
1270
+ * }
1271
+ * }
1272
+ * ```
1273
+ */
1274
+ declare class FluentReviewRejectedError extends Error {
1275
+ readonly review: "transaction" | "signature";
1276
+ readonly code: FluentReviewRejectedErrorCode;
1277
+ constructor(review: "transaction" | "signature");
1278
+ }
3215
1279
 
3216
- declare function Dialog({ ...props }: Dialog$1.Root.Props): React.JSX.Element;
3217
- declare function DialogTrigger({ ...props }: Dialog$1.Trigger.Props): React.JSX.Element;
3218
- declare function DialogPortal({ container, children, ...props }: Dialog$1.Portal.Props): React.JSX.Element;
3219
- declare function DialogClose({ ...props }: Dialog$1.Close.Props): React.JSX.Element;
3220
- declare function DialogOverlay({ className, ...props }: Dialog$1.Backdrop.Props): React.JSX.Element;
3221
- declare function DialogContent({ className, children, showCloseButton, ...props }: Dialog$1.Popup.Props & {
3222
- showCloseButton?: boolean;
3223
- }): React.JSX.Element;
3224
- declare function DialogHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
3225
- declare function DialogFooter({ className, showCloseButton, children, ...props }: React.ComponentProps<"div"> & {
3226
- showCloseButton?: boolean;
3227
- }): React.JSX.Element;
3228
- declare function DialogTitle({ className, ...props }: Dialog$1.Title.Props): React.JSX.Element;
3229
- declare function DialogDescription({ className, ...props }: Dialog$1.Description.Props): React.JSX.Element;
1280
+ /**
1281
+ * Where `useLinkX()`'s last link stands: `idle` before any, `pending` while one runs,
1282
+ * `redirecting` just before the browser leaves for X, `linked` once the Linked X account is
1283
+ * there, `error` when the last one was refused.
1284
+ */
1285
+ type FluentLinkXStatus = "idle" | "pending" | "redirecting" | "linked" | "error";
1286
+ /**
1287
+ * Linking X as a component sees it: the call, and what the last one did.
1288
+ *
1289
+ * `redirecting` is the status a page is unlikely to render for long — it is set just before the
1290
+ * browser leaves for X — and `linked` after a return is what the mount-time re-entry produces
1291
+ * without the component asking for anything.
1292
+ *
1293
+ * @throws From `linkX`, as the render context's `linkX()` does: a `FluentAuthError` whose `code`
1294
+ * is today `not_authenticated`, `user_rejected`, `linked_to_another_user`, `bad_request` or
1295
+ * `link_failed` (keep a `default` branch); the same error is kept in `error`.
1296
+ *
1297
+ * @example
1298
+ * ```tsx
1299
+ * import { useLinkX } from "@fluent.xyz/connect";
1300
+ *
1301
+ * export function LinkXButton() {
1302
+ * const { linkX, status, x, error } = useLinkX();
1303
+ * if (x) return <span>Linked as @{x.handle}</span>;
1304
+ * return (
1305
+ * <button onClick={() => void linkX().catch(() => undefined)} disabled={status === "pending"}>
1306
+ * {error ? `Retry (${error.code})` : "Link X"}
1307
+ * </button>
1308
+ * );
1309
+ * }
1310
+ * ```
1311
+ */
1312
+ declare function useLinkX(): {
1313
+ linkX: () => Promise<FluentLinkXResult>;
1314
+ status: FluentLinkXStatus;
1315
+ x: FluentXAccount | null;
1316
+ error: FluentAuthError | null;
1317
+ };
3230
1318
 
3231
- declare function Separator({ className, orientation, ...props }: Separator$1.Props): React.JSX.Element;
1319
+ /**
1320
+ * The iframe element, reduced to the window the bridge replies to. Read on every
1321
+ * message, so an element swapped in later is picked up without rebuilding the bridge.
1322
+ */
1323
+ type FluentIframeElement = {
1324
+ contentWindow: {
1325
+ postMessage: (message: unknown, targetOrigin: string) => void;
1326
+ } | null;
1327
+ };
3232
1328
 
3233
- type IconName = "coinbase" | "walletConnect" | "metaMask" | "rabby" | "keplr" | "okx" | "fluent" | "fluentLogomark" | "fluentLogotype" | "x" | "google" | "arrow-right-s-line" | "arrow-left-right-line" | "arrow-up-line" | "arrow-up-s-fill" | "arrow-down-s-fill" | "plus" | "eth" | "usdnr" | "usdc" | "blend";
3234
- declare function Icon({ name, className, ...props }: {
3235
- name: IconName;
3236
- } & SVGProps<SVGSVGElement>): React.JSX.Element;
1329
+ /** The options of `useFluentIframeBridge`. */
1330
+ type UseFluentIframeBridgeOptions = {
1331
+ /**
1332
+ * The exact origin the embedded page is served from. Messages from any other origin are
1333
+ * dropped without a reply: this is the only origin check in the exchange.
1334
+ */
1335
+ allowedOrigin: string;
1336
+ };
1337
+ /**
1338
+ * Lets a page embedded in `iframeRef` use the account signed in here, over the
1339
+ * JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The bridge lives
1340
+ * while the component is mounted; the bridge states the chain and account before its
1341
+ * first reply, and sign-in and sign-out reach the iframe as `accountsChanged`.
1342
+ *
1343
+ * @param iframeRef The `<iframe>` the embedded page runs in; read on every message, so an
1344
+ * element swapped in after mount is still answered.
1345
+ * @param options `allowedOrigin`, the one origin whose messages are answered.
1346
+ * @throws `Error`, from the effect that builds the bridge (so to the nearest error boundary),
1347
+ * when `allowedOrigin` is not an `http:` or `https:` origin: `"*"` and a bare host are
1348
+ * refused.
1349
+ *
1350
+ * @example
1351
+ * ```tsx
1352
+ * import { useFluentIframeBridge } from "@fluent.xyz/connect";
1353
+ * import { useRef } from "react";
1354
+ *
1355
+ * export function Marketplace() {
1356
+ * const iframeRef = useRef<HTMLIFrameElement>(null);
1357
+ * useFluentIframeBridge(iframeRef, { allowedOrigin: "https://market.example" });
1358
+ * return <iframe ref={iframeRef} src="https://market.example/collection/cards" />;
1359
+ * }
1360
+ * ```
1361
+ */
1362
+ declare function useFluentIframeBridge(iframeRef: RefObject<FluentIframeElement | null>, { allowedOrigin }: UseFluentIframeBridgeOptions): void;
3237
1363
 
1364
+ /** The props of `AccountAvatar`. */
3238
1365
  type AccountAvatarProps = {
3239
- /** The signed-in user's X avatar, when Privy has one. Wins over `defaultLogoUrl`. */
3240
- userLogoUrl?: string | null;
1366
+ /**
1367
+ * The person's linked X picture, the render context's `userAvatarUrl`. Wins over
1368
+ * `defaultLogoUrl`.
1369
+ */
1370
+ userAvatarUrl?: string | null;
3241
1371
  /** Host-supplied stand-in for the Fluent mark — a URL or a data URI. */
3242
1372
  defaultLogoUrl?: string | null;
3243
1373
  className?: string;
3244
1374
  };
3245
1375
  /**
3246
- * The 32px account tile's contents: X avatar, else the host's default logo, else
3247
- * the Fluent mark. A logo that fails to load falls through to the next option
3248
- * rather than leaving a broken image in the button.
1376
+ * The Account avatar: the person's linked X picture, else the host's default logo, else the
1377
+ * Fluent mark.
1378
+ *
1379
+ * @example
1380
+ * ```tsx
1381
+ * import { AccountAvatar, useFluentWidget } from "@fluent.xyz/connect";
1382
+ *
1383
+ * export function Avatar() {
1384
+ * const { userAvatarUrl } = useFluentWidget();
1385
+ * return <AccountAvatar userAvatarUrl={userAvatarUrl} />;
1386
+ * }
1387
+ * ```
3249
1388
  */
3250
- declare function AccountAvatar({ userLogoUrl, defaultLogoUrl, className }: AccountAvatarProps): React.JSX.Element;
1389
+ declare function AccountAvatar({ userAvatarUrl, defaultLogoUrl, className }: AccountAvatarProps): react.JSX.Element;
3251
1390
 
3252
- export { AccountAvatar, type AccountAvatarProps, type AppDefinition, type BackendUserTokenStore, type BridgeAddresses, Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, FLUENT_CONNECT_DEFAULT_ASSETS, FLUENT_GAS_PAYMENT_DEFAULT_ETH_RATES, FLUENT_USER_TOKEN_LIMIT, FLUENT_WIDGET_DEFAULT_GAS_TOKEN, FLUENT_WIDGET_SESSION_STORAGE_KEY, FLUENT_WIDGET_USER_TOKENS_IMPORT_MARKER_KEY, FLUENT_WIDGET_USER_TOKENS_STORAGE_KEY, FLUENT_ZERODEV_ERC20_PAYMASTER_QUERY, FLUENT_ZERODEV_PAYMASTER_DEMO_RECIPIENT, type FluentAccountCapabilities, FluentAccountDrawer, type FluentAccountType, FluentAuthError, type FluentAuthErrorCode, type FluentBatchApi, type FluentBatchCallInput, type FluentBatchConfirmationMode, type FluentBatchOperation, type FluentBatchOperationExecuteOptions, type FluentBatchOperationExecutor, type FluentBatchOperationInput, type FluentBatchOperationReview, type FluentCallPermission, type FluentChainDefinition, type FluentClient, type FluentClientConfig, type FluentEncodedBatchCall, type FluentExecuteResult, type FluentExecuteTiming, type FluentExecuteTimingInstants, type FluentExternalWalletState, type FluentFamilies, type FluentFamiliesClient, type FluentFamiliesClientConfig, type FluentFamily, type FluentFamilyTier, type FluentFamilyType, type FluentGasPayment, type FluentGasPaymentEthRates, type FluentGasPaymentSelection, type FluentGasPaymentValueTier, type FluentGasTokenSymbol, type FluentIframeBridge, type FluentIframeBridgeOptions, type FluentIframeElement, FluentIframeRpcError, type FluentIframeRpcExecutor, type FluentIframeRpcHandler, type FluentIframeRpcRequest, type FluentLinkXResult, type FluentPermissionApi, type FluentPermissionArgConstraint, type FluentPermissionArgs, type FluentPermissionBatchPolicy, type FluentPermissionBatchPolicyInput, type FluentPermissionCallInput, type FluentPermissionCallPolicy, type FluentPermissionClient, type FluentPermissionClientConfig, type FluentPermissionGrant, type FluentPermissionGrantRequest, type FluentPermissionPolicy, type FluentPermissionPolicyBuilders, type FluentPermissionPreview, type FluentPermissionSession, type FluentPermissionSessionExecutor, type FluentPermissionSessionInput, type FluentPermissionStatus, FluentPortalContainerProvider, type FluentPrivyAdapter, type FluentProfile, FluentReviewRejectedError, type FluentSession, type FluentSettingsClient, FluentSettingsError, type FluentSettingsErrorCode, type FluentSignApi, type FluentSignatureReview, type FluentSpendPeriod, type FluentSpendPermission, FluentSponsorshipFallbackError, type FluentSponsorshipReason, type FluentTokenBalance, type FluentTokenDefinition, type FluentTokenTransferOutcome, type FluentTokenTransferRequest, type FluentTokenTransferSender, type FluentTransferAmount, type FluentTransferFee, type FluentTransferRecipient, type FluentTypedDataRequest, type FluentUserOperationGas, FluentUserOperationGasError, type FluentUserOperationGasErrorCode, type FluentUserSettings, type FluentUserSettingsPatch, type FluentUserTokenAddResult, type FluentWalletChoice, FluentWidget, type FluentWidgetAccount, type FluentWidgetAuthMethod, type FluentWidgetConfig, FluentWidgetConfigError, type FluentWidgetConfigErrorCode, FluentWidgetConnectButton, type FluentWidgetConnectButtonProps, type FluentWidgetConnectButtonRenderContext, type FluentWidgetExecution, type FluentWidgetExecutionSource, type FluentWidgetExecutionStatus, type FluentWidgetGasPayment, type FluentWidgetNetwork, FluentWidgetNetworkProvider, type FluentWidgetProps, type FluentWidgetRenderContext, type FluentWidgetSession, type FluentWidgetStatus, type FluentXAccount, type FluentZeroDevErc20PaymasterToken, type FluentZeroDevErc20PaymasterTokenInfo, type FluentZeroDevKernel, type FluentZeroDevPaymasterDemoResult, type FluentZeroDevPaymasterKernel, type FluentZeroDevPermissionCall, type FluentZeroDevPermissionSession, type FluentZeroDevSignerMode, type FluentZeroDevSponsorshipTokenSource, Icon, type IconName, type L1ChainDefinition, Label, type ResolvedFluentWidgetConfig, type ResolvedFluentWidgetExecution, Separator, Switch, type UseFluentIframeBridgeOptions, type UserTokenStore, WIDGET_STYLE_SCOPE, WalletMenuActionCard, type ZerodevIntegration, buildFluentTransferCall, buttonVariants, checkFluentTransferFee, clearPrivyRecentLoginMethod, createFluentBackendUserTokenStore, createFluentBatchOp, createFluentClient, createFluentFamiliesClient, createFluentIframeBridge, createFluentIframeRpcHandler, createFluentPermissionApi, createFluentPermissionClient, createFluentPermissionPolicyBuilders, createFluentPermissionSession, createFluentSettingsClient, createFluentSponsorshipRpcUrl, createFluentUserTokenStore, createFluentZeroDevErc20Paymaster, createFluentZeroDevErc20PaymasterApprovalCall, createFluentZeroDevErc20PaymasterClient, createFluentZeroDevErc20PaymasterRpcUrl, createFluentZeroDevPermissionSession, createFluentZeroDevRpcUrl, createFluentZeroDevSponsoredPaymaster, deriveFluentGasEthRates, findFluentSymbolCollisions, fluent, apps as fluentApps, fluentBridgeAbi, fluent$1 as fluentChain, fluentChains, fluentDefinitionToViemChain, integrations as fluentIntegrations, l1Chains as fluentL1Chains, fluentMainnet, fluentMainnetTokenDefaults, fluentTestnet, fluentTestnetTokenDefaults, fluentTokenIdentity, fluentTransferAbi, fluentZeroDevChainIds, getApp, getContractAddressFromChain, getFluentChain, getFluentChainByChainId, getFluentChainForNetwork, getFluentDefaultWidgetDisplayTokens, getFluentDefaultWidgetGasTokens, getFluentExplorerBaseUrl, getFluentGasPaymentEthValue, getFluentGasPaymentTokens, getFluentGasPaymentValueTier, getFluentGasTokenAddress, getFluentTokenDefaults, getFluentTokenDefaultsForNetwork, getFluentZeroDevErc20PaymasterTokens, getL1Chain, getL1ForFluentChain, getZeroDevRpcUrl, getZerodevIntegration, isFaucetNetwork, isFluentDefaultToken, isFluentNativeToken, isFluentZeroDevChain, l1DefinitionToViemChain, mergeFluentDisplayTokens, normalizeFluentWidgetNetwork, parseFluentTransferAmount, parseFluentTransferRecipient, readFluentTokenBalances, readFluentTokenMetadata, registryVersion, resolveBridgeAddresses, resolveDefaultGasToken, resolveFluentWidgetNetworkFromEnv, resolveFluentZeroDevErc20PaymasterToken, resolveL1Definition, selectFluentGasPaymentToken, sendFluentZeroDevErc20PaymasterDemo, sortFluentGasTokens, useFluentIframeBridge, useFluentUserTokens, useFluentWidget, useFluentWidgetNetwork, useFluentZeroDevAccount, useLinkX, useWidget };
1391
+ export { AccountAvatar, type AccountAvatarProps, type FluentAccountCapabilities, type FluentAccountType, FluentAuthError, type FluentAuthErrorCode, type FluentBatchApi, type FluentBatchCallInput, type FluentBatchOperation, type FluentBatchOperationExecuteOptions, type FluentBatchOperationInput, type FluentChainDefinition, type FluentEncodedBatchCall, type FluentExecuteResult, type FluentExecuteTiming, type FluentExecuteTimingInstants, type FluentExternalWalletState, type FluentFixedAccountGas, type FluentFixedPaymasterGas, type FluentGasPayment, type FluentGasPaymentEthRates, type FluentGasTokenSymbol, type FluentIframeElement, type FluentLinkXResult, type FluentLinkXStatus, type FluentPrivyAdapter, FluentReviewRejectedError, type FluentReviewRejectedErrorCode, type FluentSignApi, type FluentSigningMode, FluentSponsorshipFallbackError, type FluentSponsorshipReason, type FluentTokenDefinition, type FluentUserOperationGas, FluentUserOperationGasError, type FluentUserOperationGasErrorCode, type FluentWalletChoice, FluentWidget, type FluentWidgetAccount, type FluentWidgetAssets, type FluentWidgetAuthMethod, type FluentWidgetConfig, FluentWidgetConfigError, type FluentWidgetConfigErrorCode, type FluentWidgetConnectButtonRenderContext, type FluentWidgetExecution, type FluentWidgetExecutionSource, type FluentWidgetExecutionStatus, type FluentWidgetGasPayment, type FluentWidgetNetwork, type FluentWidgetProps, type FluentWidgetRenderContext, type FluentWidgetSession, type FluentWidgetStatus, type FluentXAccount, type UseFluentIframeBridgeOptions, fluentMainnet, fluentTestnet, getFluentChainByChainId, getFluentChainForNetwork, useFluentIframeBridge, useFluentWidget, useLinkX };