@frak-labs/core-sdk 1.0.2 → 1.1.0-beta.53162c2d

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.
Files changed (96) hide show
  1. package/README.md +0 -1
  2. package/cdn/bundle.js +1 -14
  3. package/dist/actions-BVbAHcBk.cjs +1 -0
  4. package/dist/actions-dH5NFCj1.js +1 -0
  5. package/dist/actions.cjs +1 -1
  6. package/dist/actions.d.cts +2 -2
  7. package/dist/actions.d.ts +2 -2
  8. package/dist/actions.js +1 -1
  9. package/dist/bundle.cjs +1 -1
  10. package/dist/bundle.d.cts +4 -4
  11. package/dist/bundle.d.ts +4 -4
  12. package/dist/bundle.js +1 -1
  13. package/dist/frakContext-CTKalP6g.js +1 -0
  14. package/dist/frakContext-_b-_uwgd.cjs +1 -0
  15. package/dist/{index-DzVPSUQq.d.ts → index-5JycXTk0.d.cts} +248 -352
  16. package/dist/{index-quaxtKRh.d.ts → index-BD1gOEIo.d.ts} +1 -1
  17. package/dist/{index-BsBbSMxk.d.cts → index-C2xfJCUg.d.cts} +1 -1
  18. package/dist/{index-s1vE3jLz.d.cts → index-RNzVfwrP.d.ts} +248 -352
  19. package/dist/index.cjs +1 -1
  20. package/dist/index.d.cts +3 -3
  21. package/dist/index.d.ts +3 -3
  22. package/dist/index.js +1 -1
  23. package/dist/{openSso-DyUQew2K.d.ts → openSso-CtDyvXLM.d.ts} +19 -20
  24. package/dist/{openSso-rQhLhPbq.d.cts → openSso-DIBN_iiz.d.cts} +18 -19
  25. package/dist/src-CDfF2FOa.cjs +1 -0
  26. package/dist/src-DFiac-zk.js +1 -0
  27. package/package.json +4 -4
  28. package/src/actions/ensureIdentity.ts +3 -3
  29. package/src/actions/openSso.ts +13 -6
  30. package/src/actions/referral/processReferral.test.ts +38 -22
  31. package/src/actions/referral/processReferral.ts +6 -4
  32. package/src/actions/referral/referralInteraction.test.ts +7 -7
  33. package/src/actions/referral/referralInteraction.ts +1 -1
  34. package/src/actions/sendInteraction.ts +1 -1
  35. package/src/actions/trackPurchaseStatus.test.ts +4 -4
  36. package/src/actions/trackPurchaseStatus.ts +3 -3
  37. package/src/actions/wrapper/siweAuthenticate.test.ts +1 -5
  38. package/src/actions/wrapper/siweAuthenticate.ts +25 -1
  39. package/src/clients/createIFrameFrakClient.ts +5 -21
  40. package/src/clients/index.ts +0 -1
  41. package/src/clients/transports/iframeLifecycleManager.test.ts +10 -10
  42. package/src/clients/transports/iframeLifecycleManager.ts +3 -3
  43. package/src/config/index.ts +3 -0
  44. package/src/{utils → config}/sdkConfigStore.ts +1 -1
  45. package/src/{utils/constants.test.ts → constants.test.ts} +1 -6
  46. package/src/constants.ts +15 -0
  47. package/src/context/address.ts +76 -0
  48. package/src/{utils/FrakContext.test.ts → context/frakContext.test.ts} +4 -2
  49. package/src/{utils/FrakContext.ts → context/frakContext.ts} +4 -4
  50. package/src/{utils → context}/frakContextV2Codec.test.ts +1 -1
  51. package/src/{utils → context}/frakContextV2Codec.ts +6 -6
  52. package/src/context/index.ts +6 -0
  53. package/src/index.ts +17 -22
  54. package/src/stubs/rrweb.ts +8 -4
  55. package/src/types/client.ts +0 -3
  56. package/src/types/config.ts +11 -0
  57. package/src/types/index.ts +1 -0
  58. package/src/types/rpc/sso.ts +6 -2
  59. package/src/utils/{deepLinkWithFallback.ts → browser/deepLinkWithFallback.ts} +10 -5
  60. package/src/utils/{inAppBrowser.ts → browser/inAppBrowser.ts} +13 -0
  61. package/src/utils/browser/index.ts +13 -0
  62. package/src/utils/{formatAmount.test.ts → format/formatAmount.test.ts} +1 -1
  63. package/src/utils/{formatAmount.ts → format/formatAmount.ts} +1 -1
  64. package/src/utils/{getCurrencyAmountKey.test.ts → format/getCurrencyAmountKey.test.ts} +2 -2
  65. package/src/utils/{getCurrencyAmountKey.ts → format/getCurrencyAmountKey.ts} +1 -1
  66. package/src/utils/{getSupportedCurrency.test.ts → format/getSupportedCurrency.test.ts} +2 -2
  67. package/src/utils/{getSupportedCurrency.ts → format/getSupportedCurrency.ts} +2 -2
  68. package/src/utils/{getSupportedLocale.test.ts → format/getSupportedLocale.test.ts} +3 -3
  69. package/src/utils/{getSupportedLocale.ts → format/getSupportedLocale.ts} +2 -2
  70. package/src/utils/format/index.ts +4 -0
  71. package/src/utils/{iframeHelper.test.ts → iframe/iframeHelper.test.ts} +3 -3
  72. package/src/utils/{iframeHelper.ts → iframe/iframeHelper.ts} +3 -3
  73. package/src/utils/iframe/index.ts +6 -0
  74. package/src/utils/index.ts +31 -24
  75. package/src/utils/sso/index.ts +6 -0
  76. package/src/utils/{sso.ts → sso/sso.ts} +2 -2
  77. package/dist/actions-DihYM-OG.js +0 -1
  78. package/dist/actions-cYbmqewX.cjs +0 -1
  79. package/dist/sdkConfigStore-BXzz5PlK.js +0 -1
  80. package/dist/sdkConfigStore-DDL_fjYX.cjs +0 -1
  81. package/dist/src-CfxklqLh.cjs +0 -13
  82. package/dist/src-VDUSvqqt.js +0 -13
  83. package/src/clients/DebugInfo.test.ts +0 -418
  84. package/src/clients/DebugInfo.ts +0 -182
  85. package/src/utils/computeLegacyProductId.ts +0 -11
  86. package/src/utils/constants.ts +0 -9
  87. /package/src/{utils → clients}/ssoUrlListener.test.ts +0 -0
  88. /package/src/{utils → clients}/ssoUrlListener.ts +0 -0
  89. /package/src/{utils → config}/backendUrl.test.ts +0 -0
  90. /package/src/{utils → config}/backendUrl.ts +0 -0
  91. /package/src/{utils → config}/clientId.test.ts +0 -0
  92. /package/src/{utils → config}/clientId.ts +0 -0
  93. /package/src/{utils → config}/sdkConfigStore.test.ts +0 -0
  94. /package/src/{utils → context}/mergeAttribution.test.ts +0 -0
  95. /package/src/{utils → context}/mergeAttribution.ts +0 -0
  96. /package/src/utils/{deepLinkWithFallback.test.ts → browser/deepLinkWithFallback.test.ts} +0 -0
@@ -1,6 +1,5 @@
1
- import { G as SsoMetadata, Q as MerchantConfigResponse, U as PrepareSsoParamsType, a as FrakContextV1, at as Language, ct as AttributionParams, i as FrakContext, l as FrakClient, nt as Currency, o as FrakContextV2, rt as FrakWalletSdkConfig, st as AttributionDefaults, tt as SdkResolvedConfig, v as TokenAmountType } from "./openSso-DyUQew2K.js";
1
+ import { $ as SdkResolvedConfig, U as SsoMetadata, V as PrepareSsoParamsType, X as MerchantConfigResponse, a as FrakContextV1, et as Currency, g as TokenAmountType, i as FrakContext, o as FrakContextV2, ot as AttributionDefaults, rt as Language, s as FrakClient, st as AttributionParams, tt as FrakWalletSdkConfig } from "./openSso-DIBN_iiz.cjs";
2
2
  import { Hex } from "viem";
3
- import { RpcMessage, RpcResponse } from "@frak-labs/frame-connector";
4
3
 
5
4
  //#region src/types/compression.d.ts
6
5
  /**
@@ -48,32 +47,6 @@ declare function createIFrameFrakClient({
48
47
  iframe: HTMLIFrameElement;
49
48
  }): FrakClient;
50
49
  //#endregion
51
- //#region src/clients/DebugInfo.d.ts
52
- /** @ignore */
53
- declare class DebugInfoGatherer {
54
- private config?;
55
- private iframe?;
56
- private isSetupDone;
57
- private lastResponse;
58
- private lastRequest;
59
- constructor(config?: FrakWalletSdkConfig, iframe?: HTMLIFrameElement);
60
- setLastResponse(message: RpcMessage, response: RpcResponse): void;
61
- setLastRequest(event: RpcMessage): void;
62
- updateSetupStatus(status: boolean): void;
63
- private base64Encode;
64
- /**
65
- * Extract information from the iframe status
66
- */
67
- private getIframeStatus;
68
- private getNavigatorInfo;
69
- private gatherDebugInfo;
70
- static empty(): DebugInfoGatherer;
71
- /**
72
- * Format Frak debug information
73
- */
74
- formatDebugInfo(error: Error | unknown | string): string;
75
- }
76
- //#endregion
77
50
  //#region src/clients/setupClient.d.ts
78
51
  /**
79
52
  * Directly setup the Frak client with an iframe
@@ -96,21 +69,204 @@ declare function setupClient({
96
69
  config: FrakWalletSdkConfig;
97
70
  }): Promise<FrakClient | undefined>;
98
71
  //#endregion
99
- //#region src/constants/locales.d.ts
72
+ //#region src/config/backendUrl.d.ts
100
73
  /**
101
- * The keys for each locales
102
- * @inline
74
+ * Get the backend URL for API calls
75
+ * Tries to derive from SDK config, falls back to production
76
+ *
77
+ * @param walletUrl - Optional wallet URL to derive from (overrides global config)
103
78
  */
104
- type LocalesKey = keyof typeof locales;
79
+ declare function getBackendUrl(walletUrl?: string): string;
80
+ //#endregion
81
+ //#region src/config/clientId.d.ts
105
82
  /**
106
- * Map the currency to the locale
83
+ * Client ID utilities for anonymous tracking
84
+ * Generates and persists a UUID fingerprint for referral attribution
107
85
  */
108
- declare const locales: {
109
- readonly eur: "fr-FR";
110
- readonly usd: "en-US";
111
- readonly gbp: "en-GB";
86
+ /**
87
+ * Get the client ID from localStorage, creating one if it doesn't exist
88
+ * @returns The client ID (UUID format)
89
+ */
90
+ declare function getClientId(): string;
91
+ //#endregion
92
+ //#region src/config/sdkConfigStore.d.ts
93
+ declare const GLOBAL_KEY = "__frakSdkConfig";
94
+ declare global {
95
+ interface Window {
96
+ [GLOBAL_KEY]?: SdkResolvedConfig;
97
+ }
98
+ interface WindowEventMap {
99
+ "frak:config": CustomEvent<SdkResolvedConfig>;
100
+ }
101
+ }
102
+ declare function getConfig(): SdkResolvedConfig;
103
+ declare const sdkConfigStore: {
104
+ getConfig: typeof getConfig;
105
+ readonly isResolved: boolean;
106
+ readonly isCacheFresh: boolean;
107
+ setCacheScope(domain: string, lang?: string): void;
108
+ setConfig(config: SdkResolvedConfig): void;
109
+ reset(): void;
110
+ clearCache(): void;
111
+ resolve(domain?: string, walletUrl?: string, lang?: Language): Promise<MerchantConfigResponse | undefined>;
112
+ getMerchantId(): string | undefined;
113
+ resolveMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
112
114
  };
113
115
  //#endregion
116
+ //#region src/constants.d.ts
117
+ /**
118
+ * Deep link scheme for Frak Wallet mobile app.
119
+ *
120
+ * Replaced at build time via tsdown/Vite `define`. Defaults to the prod scheme;
121
+ * in-monorepo dev builds (listener at wallet-dev.frak.id) override this with
122
+ * `frakwallet-dev://` so deep links open the dev wallet variant (id.frak.wallet.dev).
123
+ * External integrators consuming the published NPM/CDN bundle always see the prod scheme.
124
+ */
125
+ declare const DEEP_LINK_SCHEME: string;
126
+ //#endregion
127
+ //#region src/context/frakContext.d.ts
128
+ /**
129
+ * Compress a Frak context into a URL-safe string.
130
+ *
131
+ * - V2 contexts are encoded using a compact binary layout (see
132
+ * {@link encodeFrakContextV2}) then base64url-encoded.
133
+ * - V1 contexts encode the wallet address as raw bytes (base64url).
134
+ *
135
+ * @param context - The context to compress (V1 or V2)
136
+ * @returns A compressed base64url string, or undefined on failure
137
+ */
138
+ declare function compress(context?: FrakContextV1 | FrakContextV2): string | undefined;
139
+ /**
140
+ * Decompress a base64url string back into a Frak context.
141
+ *
142
+ * V1 (exactly 20 bytes) and V2 (37, 41, or 57 bytes) are distinguished by
143
+ * their decoded byte length, so there is no ambiguity.
144
+ *
145
+ * @param context - The compressed context string
146
+ * @returns The decompressed FrakContext, or undefined on failure
147
+ */
148
+ declare function decompress(context?: string): FrakContext | undefined;
149
+ /**
150
+ * Parse a URL to extract the Frak referral context from the `fCtx` query parameter.
151
+ *
152
+ * @param args
153
+ * @param args.url - The URL to parse
154
+ * @returns The parsed FrakContext, or null if absent
155
+ */
156
+ declare function parse({
157
+ url
158
+ }: {
159
+ url: string;
160
+ }): FrakContext | null | undefined;
161
+ /**
162
+ * Add or replace the `fCtx` query parameter in a URL with the given context.
163
+ *
164
+ * Standard affiliation params (`utm_source`, `utm_medium`, `utm_campaign`,
165
+ * `ref`, `via`, ...) are always appended using gap-fill semantics: pre-existing
166
+ * params on the URL are preserved, defaults are derived from the context when
167
+ * applicable, and `attribution` overrides take precedence when provided.
168
+ *
169
+ * @param args
170
+ * @param args.url - The URL to update
171
+ * @param args.context - The context to embed (V1 or V2)
172
+ * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
173
+ * @returns The updated URL string, or null on failure
174
+ */
175
+ declare function update({
176
+ url,
177
+ context,
178
+ attribution
179
+ }: {
180
+ url?: string;
181
+ context: FrakContextV1 | FrakContextV2;
182
+ attribution?: AttributionParams;
183
+ }): string | null;
184
+ /**
185
+ * Remove the `fCtx` query parameter from a URL.
186
+ *
187
+ * @param url - The URL to strip the context from
188
+ * @returns The cleaned URL string
189
+ */
190
+ declare function remove(url: string): string;
191
+ /**
192
+ * Replace the current browser URL with an updated Frak context.
193
+ *
194
+ * - If `context` is non-null, embeds it via {@link update}.
195
+ * - If `context` is null, strips the context via {@link remove}.
196
+ *
197
+ * @param args
198
+ * @param args.url - Base URL (defaults to `window.location.href`)
199
+ * @param args.context - Context to set, or null to remove
200
+ */
201
+ declare function replaceUrl({
202
+ url: baseUrl,
203
+ context
204
+ }: {
205
+ url?: string;
206
+ context: FrakContextV1 | FrakContextV2 | null;
207
+ }): void;
208
+ /**
209
+ * Manager for Frak referral context in URLs.
210
+ *
211
+ * Handles compression, decompression, URL parsing, and browser history updates
212
+ * for both V1 (wallet address) and V2 (anonymous clientId) referral contexts.
213
+ */
214
+ declare const FrakContextManager: {
215
+ compress: typeof compress;
216
+ decompress: typeof decompress;
217
+ parse: typeof parse;
218
+ update: typeof update;
219
+ remove: typeof remove;
220
+ replaceUrl: typeof replaceUrl;
221
+ };
222
+ //#endregion
223
+ //#region src/context/mergeAttribution.d.ts
224
+ /**
225
+ * Inputs for {@link mergeAttribution}.
226
+ */
227
+ type MergeAttributionInput = {
228
+ /**
229
+ * Per-call attribution override passed to actions like `displaySharingPage`.
230
+ *
231
+ * - `null` explicitly disables attribution (no UTM/ref/via params are added).
232
+ * - `undefined` means "no per-call override" — defaults apply if present.
233
+ * - An object (including `{}`) merges field-by-field with defaults.
234
+ */
235
+ perCall: AttributionParams | null | undefined;
236
+ /**
237
+ * Pre-merged merchant-level defaults (backend config > SDK static config).
238
+ * `utm_content` is intentionally absent from this shape.
239
+ */
240
+ defaults?: AttributionDefaults;
241
+ /**
242
+ * Per-product `utm_content` override (from the currently selected
243
+ * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
244
+ */
245
+ productUtmContent?: string;
246
+ };
247
+ /**
248
+ * Merge the three attribution layers into a single {@link AttributionParams}
249
+ * value suitable for `FrakContextManager.update`.
250
+ *
251
+ * Priority per field:
252
+ * 1. `perCall` (wins)
253
+ * 2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
254
+ * 3. Hardcoded fallbacks resolved later by `FrakContextManager`
255
+ *
256
+ * Special rules:
257
+ * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
258
+ * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
259
+ * applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
260
+ * utm_campaign=<merchantId>, ref=<clientId>, via=frak).
261
+ * - `utm_content` never comes from `defaults`; only `productUtmContent` or
262
+ * `perCall.utmContent` can populate it.
263
+ */
264
+ declare function mergeAttribution({
265
+ perCall,
266
+ defaults,
267
+ productUtmContent
268
+ }: MergeAttributionInput): AttributionParams | undefined;
269
+ //#endregion
114
270
  //#region src/utils/analytics/events/component.d.ts
115
271
  type ButtonBaseProps = {
116
272
  placement?: string;
@@ -217,14 +373,58 @@ type SdkEventMap = SdkLifecycleEventMap & SdkComponentEventMap & SdkReferralEven
217
373
  */
218
374
  declare function trackEvent<K extends keyof SdkEventMap>(client: FrakClient | undefined, event: K, properties?: SdkEventMap[K]): void;
219
375
  //#endregion
220
- //#region src/utils/backendUrl.d.ts
376
+ //#region src/utils/browser/deepLinkWithFallback.d.ts
221
377
  /**
222
- * Get the backend URL for API calls
223
- * Tries to derive from SDK config, falls back to production
378
+ * Options for deep link with fallback
379
+ */
380
+ type DeepLinkFallbackOptions = {
381
+ /** Timeout in ms before triggering fallback (default: 2500ms) */timeout?: number; /** Callback invoked when fallback is triggered (app not installed) */
382
+ onFallback?: () => void;
383
+ };
384
+ /**
385
+ * Trigger a deep link with visibility-based fallback detection.
224
386
  *
225
- * @param walletUrl - Optional wallet URL to derive from (overrides global config)
387
+ * Uses the Page Visibility API to detect if the app opened (page goes hidden).
388
+ * If the page remains visible after the timeout, assumes app is not installed
389
+ * and invokes the onFallback callback.
390
+ *
391
+ * On Chromium Android, converts custom scheme to intent:// URL to avoid
392
+ * the "Continue to app?" confirmation bar.
393
+ *
394
+ * @param deepLink - The deep link URL to trigger (e.g., "frakwallet://wallet")
395
+ * @param options - Optional configuration (timeout, onFallback callback)
226
396
  */
227
- declare function getBackendUrl(walletUrl?: string): string;
397
+ declare function triggerDeepLinkWithFallback(deepLink: string, options?: DeepLinkFallbackOptions): void;
398
+ //#endregion
399
+ //#region src/utils/browser/inAppBrowser.d.ts
400
+ /**
401
+ * Whether the current device runs iOS (including iPadOS 13+).
402
+ */
403
+ declare const isIOS: boolean;
404
+ /**
405
+ * Check if the current device is a mobile device (iOS, iPadOS, Android,
406
+ * webOS, BlackBerry, IEMobile, Opera Mini). Reuses {@link isIOS} so the
407
+ * iPadOS-13+ Macintosh heuristic stays in one place.
408
+ */
409
+ declare function isMobile(): boolean;
410
+ /**
411
+ * Whether the current browser is a social media in-app browser
412
+ * (Instagram, Facebook).
413
+ */
414
+ declare const isInAppBrowser: boolean;
415
+ /**
416
+ * Redirect to external browser from in-app WebView.
417
+ *
418
+ * - **iOS**: Uses `x-safari-https://` scheme — server-side 302 redirects
419
+ * to custom URL schemes are silently swallowed by WKWebView.
420
+ * Direct `window.location.href` assignment works (confirmed iOS 17+).
421
+ *
422
+ * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
423
+ * Content-Type response, forcing the WebView to hand off to the default browser.
424
+ *
425
+ * @param targetUrl - The URL to open in the external browser
426
+ */
427
+ declare function redirectToExternalBrowser(targetUrl: string): void;
228
428
  //#endregion
229
429
  //#region src/utils/cache/withCache.d.ts
230
430
  type WithCacheOptions = {
@@ -251,36 +451,12 @@ declare function withCache<TData>(fn: () => Promise<TData>, {
251
451
  cacheKey,
252
452
  cacheTime
253
453
  }: WithCacheOptions): Promise<TData>;
254
- /**
255
- * Get a cache handle for a specific key, useful for manual invalidation.
256
- *
257
- * @example
258
- * ```ts
259
- * // Invalidate merchant info cache after a mutation
260
- * getCache("frak_getMerchantInformation").clear();
261
- * ```
262
- */
263
- declare function getCache(cacheKey: string): {
264
- /** Clear both the pending promise and the cached response */clear: () => void; /** Check if a non-expired response exists */
265
- has: (cacheTime?: number) => boolean;
266
- };
267
454
  /**
268
455
  * Clear all cached data (both pending promises and resolved responses).
269
456
  * Called automatically when the client is destroyed.
270
457
  */
271
458
  declare function clearAllCache(): void;
272
459
  //#endregion
273
- //#region src/utils/clientId.d.ts
274
- /**
275
- * Client ID utilities for anonymous tracking
276
- * Generates and persists a UUID fingerprint for referral attribution
277
- */
278
- /**
279
- * Get the client ID from localStorage, creating one if it doesn't exist
280
- * @returns The client ID (UUID format)
281
- */
282
- declare function getClientId(): string;
283
- //#endregion
284
460
  //#region src/utils/compression/b64.d.ts
285
461
  /**
286
462
  * Encode a buffer to a base64url encoded string
@@ -311,160 +487,7 @@ declare function compressJsonToB64(data: unknown): string;
311
487
  */
312
488
  declare function decompressJsonFromB64<T>(data: string): T | null;
313
489
  //#endregion
314
- //#region src/utils/constants.d.ts
315
- /**
316
- * Deep link scheme for Frak Wallet mobile app
317
- */
318
- declare const DEEP_LINK_SCHEME = "frakwallet://";
319
- //#endregion
320
- //#region src/utils/deepLinkWithFallback.d.ts
321
- /**
322
- * Options for deep link with fallback
323
- */
324
- type DeepLinkFallbackOptions = {
325
- /** Timeout in ms before triggering fallback (default: 2500ms) */timeout?: number; /** Callback invoked when fallback is triggered (app not installed) */
326
- onFallback?: () => void;
327
- };
328
- /**
329
- * Check if running on a Chromium-based Android browser.
330
- *
331
- * On Chrome Android, custom scheme deep links (e.g. frakwallet://) trigger
332
- * a confirmation bar ("Continue to Frak Wallet?"). Using intent:// URLs
333
- * instead bypasses this for Chromium browsers while keeping custom scheme
334
- * fallback for non-Chromium browsers (e.g. Firefox) where it works fine.
335
- */
336
- declare function isChromiumAndroid(): boolean;
337
- /**
338
- * Convert a frakwallet:// deep link to an Android intent:// URL.
339
- *
340
- * Intent URLs let Chromium browsers open the app directly without
341
- * showing the "Continue to app?" confirmation bar.
342
- *
343
- * Note: We intentionally omit the `package` parameter. Including it
344
- * causes Chrome to redirect to the Play Store when the app is not
345
- * installed, which breaks the visibility-based fallback detection.
346
- * Without `package`, Chrome simply does nothing when the app is
347
- * missing, allowing the fallback mechanism to fire correctly.
348
- *
349
- * Format: intent://path#Intent;scheme=frakwallet;end
350
- */
351
- declare function toAndroidIntentUrl(deepLink: string): string;
352
- /**
353
- * Trigger a deep link with visibility-based fallback detection.
354
- *
355
- * Uses the Page Visibility API to detect if the app opened (page goes hidden).
356
- * If the page remains visible after the timeout, assumes app is not installed
357
- * and invokes the onFallback callback.
358
- *
359
- * On Chromium Android, converts custom scheme to intent:// URL to avoid
360
- * the "Continue to app?" confirmation bar.
361
- *
362
- * @param deepLink - The deep link URL to trigger (e.g., "frakwallet://wallet")
363
- * @param options - Optional configuration (timeout, onFallback callback)
364
- */
365
- declare function triggerDeepLinkWithFallback(deepLink: string, options?: DeepLinkFallbackOptions): void;
366
- /**
367
- * Check if a URL is a Frak deep link
368
- */
369
- declare function isFrakDeepLink(url: string): boolean;
370
- //#endregion
371
- //#region src/utils/FrakContext.d.ts
372
- /**
373
- * Compress a Frak context into a URL-safe string.
374
- *
375
- * - V2 contexts are encoded using a compact binary layout (see
376
- * {@link encodeFrakContextV2}) then base64url-encoded.
377
- * - V1 contexts encode the wallet address as raw bytes (base64url).
378
- *
379
- * @param context - The context to compress (V1 or V2)
380
- * @returns A compressed base64url string, or undefined on failure
381
- */
382
- declare function compress(context?: FrakContextV1 | FrakContextV2): string | undefined;
383
- /**
384
- * Decompress a base64url string back into a Frak context.
385
- *
386
- * V1 (exactly 20 bytes) and V2 (37, 41, or 57 bytes) are distinguished by
387
- * their decoded byte length, so there is no ambiguity.
388
- *
389
- * @param context - The compressed context string
390
- * @returns The decompressed FrakContext, or undefined on failure
391
- */
392
- declare function decompress(context?: string): FrakContext | undefined;
393
- /**
394
- * Parse a URL to extract the Frak referral context from the `fCtx` query parameter.
395
- *
396
- * @param args
397
- * @param args.url - The URL to parse
398
- * @returns The parsed FrakContext, or null if absent
399
- */
400
- declare function parse({
401
- url
402
- }: {
403
- url: string;
404
- }): FrakContext | null | undefined;
405
- /**
406
- * Add or replace the `fCtx` query parameter in a URL with the given context.
407
- *
408
- * Standard affiliation params (`utm_source`, `utm_medium`, `utm_campaign`,
409
- * `ref`, `via`, ...) are always appended using gap-fill semantics: pre-existing
410
- * params on the URL are preserved, defaults are derived from the context when
411
- * applicable, and `attribution` overrides take precedence when provided.
412
- *
413
- * @param args
414
- * @param args.url - The URL to update
415
- * @param args.context - The context to embed (V1 or V2)
416
- * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
417
- * @returns The updated URL string, or null on failure
418
- */
419
- declare function update({
420
- url,
421
- context,
422
- attribution
423
- }: {
424
- url?: string;
425
- context: FrakContextV1 | FrakContextV2;
426
- attribution?: AttributionParams;
427
- }): string | null;
428
- /**
429
- * Remove the `fCtx` query parameter from a URL.
430
- *
431
- * @param url - The URL to strip the context from
432
- * @returns The cleaned URL string
433
- */
434
- declare function remove(url: string): string;
435
- /**
436
- * Replace the current browser URL with an updated Frak context.
437
- *
438
- * - If `context` is non-null, embeds it via {@link update}.
439
- * - If `context` is null, strips the context via {@link remove}.
440
- *
441
- * @param args
442
- * @param args.url - Base URL (defaults to `window.location.href`)
443
- * @param args.context - Context to set, or null to remove
444
- */
445
- declare function replaceUrl({
446
- url: baseUrl,
447
- context
448
- }: {
449
- url?: string;
450
- context: FrakContextV1 | FrakContextV2 | null;
451
- }): void;
452
- /**
453
- * Manager for Frak referral context in URLs.
454
- *
455
- * Handles compression, decompression, URL parsing, and browser history updates
456
- * for both V1 (wallet address) and V2 (anonymous clientId) referral contexts.
457
- */
458
- declare const FrakContextManager: {
459
- compress: typeof compress;
460
- decompress: typeof decompress;
461
- parse: typeof parse;
462
- update: typeof update;
463
- remove: typeof remove;
464
- replaceUrl: typeof replaceUrl;
465
- };
466
- //#endregion
467
- //#region src/utils/formatAmount.d.ts
490
+ //#region src/utils/format/formatAmount.d.ts
468
491
  /**
469
492
  * Format a numeric amount as a localized currency string
470
493
  * @param amount - The raw numeric amount to format
@@ -473,7 +496,7 @@ declare const FrakContextManager: {
473
496
  */
474
497
  declare function formatAmount(amount: number, currency?: Currency): string;
475
498
  //#endregion
476
- //#region src/utils/getCurrencyAmountKey.d.ts
499
+ //#region src/utils/format/getCurrencyAmountKey.d.ts
477
500
  /**
478
501
  * Get the currency amount key for a given currency
479
502
  * @param currency - The currency to use
@@ -481,7 +504,7 @@ declare function formatAmount(amount: number, currency?: Currency): string;
481
504
  */
482
505
  declare function getCurrencyAmountKey(currency?: Currency): keyof TokenAmountType;
483
506
  //#endregion
484
- //#region src/utils/getSupportedCurrency.d.ts
507
+ //#region src/utils/format/getSupportedCurrency.d.ts
485
508
  /**
486
509
  * Get the supported currency for a given currency
487
510
  * @param currency - The currency to use
@@ -489,15 +512,7 @@ declare function getCurrencyAmountKey(currency?: Currency): keyof TokenAmountTyp
489
512
  */
490
513
  declare function getSupportedCurrency(currency?: Currency): Currency;
491
514
  //#endregion
492
- //#region src/utils/getSupportedLocale.d.ts
493
- /**
494
- * Get the supported locale for a given currency
495
- * @param currency - The currency to use
496
- * @returns The supported locale
497
- */
498
- declare function getSupportedLocale(currency?: Currency): (typeof locales)[LocalesKey];
499
- //#endregion
500
- //#region src/utils/iframeHelper.d.ts
515
+ //#region src/utils/iframe/iframeHelper.d.ts
501
516
  /**
502
517
  * Base props for the iframe
503
518
  * @ignore
@@ -518,19 +533,6 @@ declare const baseIframeProps: {
518
533
  colorScheme: string;
519
534
  };
520
535
  };
521
- /**
522
- * Create the Frak iframe
523
- * @param args
524
- * @param args.walletBaseUrl - Use `config.walletUrl` instead. Will be removed in future versions.
525
- * @param args.config - The configuration object containing iframe options, including the replacement for `walletBaseUrl`.
526
- */
527
- declare function createIframe({
528
- walletBaseUrl,
529
- config
530
- }: {
531
- walletBaseUrl?: string;
532
- config?: FrakWalletSdkConfig;
533
- }): Promise<HTMLIFrameElement | undefined>;
534
536
  /**
535
537
  * Find an iframe within window.opener by pathname
536
538
  *
@@ -552,102 +554,7 @@ declare function createIframe({
552
554
  */
553
555
  declare function findIframeInOpener(pathname?: string): Window | null;
554
556
  //#endregion
555
- //#region src/utils/inAppBrowser.d.ts
556
- /**
557
- * Whether the current device runs iOS (including iPadOS 13+).
558
- */
559
- declare const isIOS: boolean;
560
- /**
561
- * Whether the current browser is a social media in-app browser
562
- * (Instagram, Facebook).
563
- */
564
- declare const isInAppBrowser: boolean;
565
- /**
566
- * Redirect to external browser from in-app WebView.
567
- *
568
- * - **iOS**: Uses `x-safari-https://` scheme — server-side 302 redirects
569
- * to custom URL schemes are silently swallowed by WKWebView.
570
- * Direct `window.location.href` assignment works (confirmed iOS 17+).
571
- *
572
- * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
573
- * Content-Type response, forcing the WebView to hand off to the default browser.
574
- *
575
- * @param targetUrl - The URL to open in the external browser
576
- */
577
- declare function redirectToExternalBrowser(targetUrl: string): void;
578
- //#endregion
579
- //#region src/utils/mergeAttribution.d.ts
580
- /**
581
- * Inputs for {@link mergeAttribution}.
582
- */
583
- type MergeAttributionInput = {
584
- /**
585
- * Per-call attribution override passed to actions like `displaySharingPage`.
586
- *
587
- * - `null` explicitly disables attribution (no UTM/ref/via params are added).
588
- * - `undefined` means "no per-call override" — defaults apply if present.
589
- * - An object (including `{}`) merges field-by-field with defaults.
590
- */
591
- perCall: AttributionParams | null | undefined;
592
- /**
593
- * Pre-merged merchant-level defaults (backend config > SDK static config).
594
- * `utm_content` is intentionally absent from this shape.
595
- */
596
- defaults?: AttributionDefaults;
597
- /**
598
- * Per-product `utm_content` override (from the currently selected
599
- * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
600
- */
601
- productUtmContent?: string;
602
- };
603
- /**
604
- * Merge the three attribution layers into a single {@link AttributionParams}
605
- * value suitable for `FrakContextManager.update`.
606
- *
607
- * Priority per field:
608
- * 1. `perCall` (wins)
609
- * 2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
610
- * 3. Hardcoded fallbacks resolved later by `FrakContextManager`
611
- *
612
- * Special rules:
613
- * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
614
- * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
615
- * applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
616
- * utm_campaign=<merchantId>, ref=<clientId>, via=frak).
617
- * - `utm_content` never comes from `defaults`; only `productUtmContent` or
618
- * `perCall.utmContent` can populate it.
619
- */
620
- declare function mergeAttribution({
621
- perCall,
622
- defaults,
623
- productUtmContent
624
- }: MergeAttributionInput): AttributionParams | undefined;
625
- //#endregion
626
- //#region src/utils/sdkConfigStore.d.ts
627
- declare const GLOBAL_KEY = "__frakSdkConfig";
628
- declare global {
629
- interface Window {
630
- [GLOBAL_KEY]?: SdkResolvedConfig;
631
- }
632
- interface WindowEventMap {
633
- "frak:config": CustomEvent<SdkResolvedConfig>;
634
- }
635
- }
636
- declare function getConfig(): SdkResolvedConfig;
637
- declare const sdkConfigStore: {
638
- getConfig: typeof getConfig;
639
- readonly isResolved: boolean;
640
- readonly isCacheFresh: boolean;
641
- setCacheScope(domain: string, lang?: string): void;
642
- setConfig(config: SdkResolvedConfig): void;
643
- reset(): void;
644
- clearCache(): void;
645
- resolve(domain?: string, walletUrl?: string, lang?: Language): Promise<MerchantConfigResponse | undefined>;
646
- getMerchantId(): string | undefined;
647
- resolveMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
648
- };
649
- //#endregion
650
- //#region src/utils/sso.d.ts
557
+ //#region src/utils/sso/sso.d.ts
651
558
  type AppSpecificSsoMetadata = SsoMetadata & {
652
559
  name?: string;
653
560
  css?: string;
@@ -702,15 +609,4 @@ type CompressedSsoData = {
702
609
  };
703
610
  };
704
611
  //#endregion
705
- //#region src/utils/computeLegacyProductId.d.ts
706
- /**
707
- * Compute the legacy product id from a domain
708
- * @ignore
709
- */
710
- declare function computeLegacyProductId({
711
- domain
712
- }?: {
713
- domain?: string;
714
- }): `0x${string}`;
715
- //#endregion
716
- export { getClientId as A, setupClient as B, toAndroidIntentUrl as C, compressJsonToB64 as D, decompressJsonFromB64 as E, trackEvent as F, KeyProvider as G, createIFrameFrakClient as H, SdkEventMap as I, SdkHandshakeFailureReason as L, getCache as M, withCache as N, base64urlDecode as O, getBackendUrl as P, LocalesKey as R, isFrakDeepLink as S, DEEP_LINK_SCHEME as T, CompressedData as U, DebugInfoGatherer as V, HashProtectedData as W, getCurrencyAmountKey as _, generateSsoUrl as a, DeepLinkFallbackOptions as b, mergeAttribution as c, redirectToExternalBrowser as d, baseIframeProps as f, getSupportedCurrency as g, getSupportedLocale as h, FullSsoParams as i, clearAllCache as j, base64urlEncode as k, isIOS as l, findIframeInOpener as m, AppSpecificSsoMetadata as n, sdkConfigStore as o, createIframe as p, CompressedSsoData as r, MergeAttributionInput as s, computeLegacyProductId as t, isInAppBrowser as u, formatAmount as v, triggerDeepLinkWithFallback as w, isChromiumAndroid as x, FrakContextManager as y, locales as z };
612
+ export { getClientId as A, SdkEventMap as C, FrakContextManager as D, mergeAttribution as E, HashProtectedData as F, KeyProvider as I, setupClient as M, createIFrameFrakClient as N, DEEP_LINK_SCHEME as O, CompressedData as P, trackEvent as S, MergeAttributionInput as T, isInAppBrowser as _, baseIframeProps as a, DeepLinkFallbackOptions as b, getCurrencyAmountKey as c, compressJsonToB64 as d, base64urlDecode as f, isIOS as g, withCache as h, generateSsoUrl as i, getBackendUrl as j, sdkConfigStore as k, formatAmount as l, clearAllCache as m, CompressedSsoData as n, findIframeInOpener as o, base64urlEncode as p, FullSsoParams as r, getSupportedCurrency as s, AppSpecificSsoMetadata as t, decompressJsonFromB64 as u, isMobile as v, SdkHandshakeFailureReason as w, triggerDeepLinkWithFallback as x, redirectToExternalBrowser as y };