@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.0cd79998

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 (82) hide show
  1. package/README.md +1 -2
  2. package/cdn/bundle.js +3 -3
  3. package/dist/actions-BMTVobuH.js +1 -0
  4. package/dist/actions-ukNCM0d7.cjs +1 -0
  5. package/dist/actions.cjs +1 -1
  6. package/dist/actions.d.cts +3 -3
  7. package/dist/actions.d.ts +3 -3
  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/{computeLegacyProductId-b5cUWdAm.d.ts → index-BCwGNRmk.d.cts} +144 -58
  14. package/dist/{computeLegacyProductId-CCAZvLa5.d.cts → index-BfmJnxzo.d.ts} +144 -58
  15. package/dist/{siweAuthenticate-CnCZ7mok.d.ts → index-CVnwk1E_.d.cts} +122 -8
  16. package/dist/{siweAuthenticate-CVigMOxz.d.cts → index-DZuYiI2M.d.ts} +122 -8
  17. package/dist/index.cjs +1 -1
  18. package/dist/index.d.cts +3 -3
  19. package/dist/index.d.ts +3 -3
  20. package/dist/index.js +1 -1
  21. package/dist/{openSso-B0g7-807.d.cts → openSso-BQ-q-_Y9.d.ts} +373 -46
  22. package/dist/{openSso-CMzwvaCa.d.ts → openSso-CMBCbhvP.d.cts} +372 -45
  23. package/dist/src-Cx0RZEA3.js +13 -0
  24. package/dist/src-DmYZ4ZLk.cjs +13 -0
  25. package/dist/trackEvent-B5xo_5K3.cjs +1 -0
  26. package/dist/trackEvent-DdykyX0U.js +1 -0
  27. package/package.json +12 -13
  28. package/src/actions/displayEmbeddedWallet.ts +6 -2
  29. package/src/actions/displayModal.ts +6 -2
  30. package/src/actions/displaySharingPage.ts +49 -0
  31. package/src/actions/ensureIdentity.ts +2 -2
  32. package/src/actions/getMerchantInformation.test.ts +13 -1
  33. package/src/actions/getMerchantInformation.ts +20 -5
  34. package/src/actions/getMergeToken.ts +33 -0
  35. package/src/actions/getUserReferralStatus.ts +42 -0
  36. package/src/actions/index.ts +8 -1
  37. package/src/actions/referral/setupReferral.test.ts +79 -0
  38. package/src/actions/referral/setupReferral.ts +32 -0
  39. package/src/actions/trackPurchaseStatus.test.ts +32 -20
  40. package/src/actions/trackPurchaseStatus.ts +3 -5
  41. package/src/actions/wrapper/modalBuilder.test.ts +4 -2
  42. package/src/actions/wrapper/modalBuilder.ts +6 -8
  43. package/src/clients/createIFrameFrakClient.ts +162 -27
  44. package/src/clients/transports/iframeLifecycleManager.test.ts +14 -94
  45. package/src/clients/transports/iframeLifecycleManager.ts +35 -53
  46. package/src/index.ts +21 -4
  47. package/src/stubs/rrweb.ts +9 -0
  48. package/src/types/config.ts +19 -3
  49. package/src/types/index.ts +15 -1
  50. package/src/types/lifecycle/client.ts +22 -27
  51. package/src/types/lifecycle/iframe.ts +7 -8
  52. package/src/types/resolvedConfig.ts +138 -0
  53. package/src/types/rpc/displaySharingPage.ts +100 -0
  54. package/src/types/rpc/embedded/index.ts +1 -1
  55. package/src/types/rpc/interaction.ts +4 -0
  56. package/src/types/rpc/userReferralStatus.ts +20 -0
  57. package/src/types/rpc.ts +54 -5
  58. package/src/types/tracking.ts +36 -0
  59. package/src/utils/FrakContext.test.ts +144 -0
  60. package/src/utils/FrakContext.ts +67 -1
  61. package/src/utils/backendUrl.test.ts +2 -2
  62. package/src/utils/backendUrl.ts +1 -1
  63. package/src/utils/cache/index.ts +7 -0
  64. package/src/utils/cache/lruMap.test.ts +55 -0
  65. package/src/utils/cache/lruMap.ts +38 -0
  66. package/src/utils/cache/withCache.test.ts +168 -0
  67. package/src/utils/cache/withCache.ts +124 -0
  68. package/src/utils/inAppBrowser.ts +60 -0
  69. package/src/utils/index.ts +10 -4
  70. package/src/utils/mergeAttribution.test.ts +153 -0
  71. package/src/utils/mergeAttribution.ts +75 -0
  72. package/src/utils/sdkConfigStore.test.ts +405 -0
  73. package/src/utils/sdkConfigStore.ts +263 -0
  74. package/src/utils/sso.ts +3 -7
  75. package/dist/setupClient-BduY6Sym.cjs +0 -13
  76. package/dist/setupClient-ftmdQ-I8.js +0 -13
  77. package/dist/siweAuthenticate-BWmI2_TN.cjs +0 -1
  78. package/dist/siweAuthenticate-zczqxm0a.js +0 -1
  79. package/dist/trackEvent-CeLFVzZn.js +0 -1
  80. package/dist/trackEvent-Ew5r5zfI.cjs +0 -1
  81. package/src/utils/merchantId.test.ts +0 -653
  82. package/src/utils/merchantId.ts +0 -143
@@ -1,5 +1,5 @@
1
- import { J as Currency, V as SsoMetadata, Y as FrakWalletSdkConfig, _ as TokenAmountType, a as FrakContextV1, i as FrakContext, l as FrakClient, o as FrakContextV2, z as PrepareSsoParamsType } from "./openSso-CMzwvaCa.js";
2
- import { Address, Hex } from "viem";
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-CMBCbhvP.cjs";
2
+ import { Hex } from "viem";
3
3
  import { RpcMessage, RpcResponse } from "@frak-labs/frame-connector";
4
4
 
5
5
  //#region src/types/compression.d.ts
@@ -22,35 +22,12 @@ type HashProtectedData<DataType> = Readonly<DataType & {
22
22
  */
23
23
  type KeyProvider<DataType> = (value: DataType) => string[];
24
24
  //#endregion
25
- //#region src/types/tracking.d.ts
26
- type UtmParams = {
27
- source?: string;
28
- medium?: string;
29
- campaign?: string;
30
- term?: string;
31
- content?: string;
32
- };
33
- type TrackArrivalParams = {
34
- /** @deprecated V1 legacy — use referrerClientId for v2 contexts */referrerWallet?: Address;
35
- referrerClientId?: string;
36
- referrerMerchantId?: string; /** Epoch seconds timestamp from the referral link creation */
37
- referralTimestamp?: number;
38
- landingUrl?: string;
39
- utmParams?: UtmParams;
40
- };
41
- type TrackArrivalResult = {
42
- success: boolean;
43
- identityGroupId?: string;
44
- touchpointId?: string;
45
- error?: string;
46
- };
47
- //#endregion
48
25
  //#region src/clients/createIFrameFrakClient.d.ts
49
26
  /**
50
27
  * Create a new iframe Frak client
51
28
  * @param args
52
29
  * @param args.config - The configuration to use for the Frak Wallet SDK.
53
- * When `config.domain` is set, it is forwarded to the iframe handshake so the listener resolves the correct merchant in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
30
+ * When `config.domain` is set, it is used to resolve the correct merchant config in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
54
31
  * @param args.iframe - The iframe to use for the communication
55
32
  * @returns The created Frak Client
56
33
  *
@@ -143,6 +120,50 @@ declare const locales: {
143
120
  */
144
121
  declare function getBackendUrl(walletUrl?: string): string;
145
122
  //#endregion
123
+ //#region src/utils/cache/withCache.d.ts
124
+ type WithCacheOptions = {
125
+ /** The key to cache the data against */cacheKey: string; /** Time in ms that cached data will remain valid. Default: 30_000 (30s). Set to 0 to disable caching. */
126
+ cacheTime?: number;
127
+ };
128
+ /**
129
+ * Returns the result of a given promise, and caches the result for
130
+ * subsequent invocations against a provided cache key.
131
+ *
132
+ * Also deduplicates concurrent calls — if multiple callers request the same
133
+ * cache key while the promise is pending, they share the same promise.
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * // First call fetches, subsequent calls return cached data for 30s
138
+ * const data = await withCache(
139
+ * () => client.request({ method: "frak_getMerchantInformation" }),
140
+ * { cacheKey: "merchantInfo", cacheTime: 30_000 }
141
+ * );
142
+ * ```
143
+ */
144
+ declare function withCache<TData>(fn: () => Promise<TData>, {
145
+ cacheKey,
146
+ cacheTime
147
+ }: WithCacheOptions): Promise<TData>;
148
+ /**
149
+ * Get a cache handle for a specific key, useful for manual invalidation.
150
+ *
151
+ * @example
152
+ * ```ts
153
+ * // Invalidate merchant info cache after a mutation
154
+ * getCache("frak_getMerchantInformation").clear();
155
+ * ```
156
+ */
157
+ declare function getCache(cacheKey: string): {
158
+ /** Clear both the pending promise and the cached response */clear: () => void; /** Check if a non-expired response exists */
159
+ has: (cacheTime?: number) => boolean;
160
+ };
161
+ /**
162
+ * Clear all cached data (both pending promises and resolved responses).
163
+ * Called automatically when the client is destroyed.
164
+ */
165
+ declare function clearAllCache(): void;
166
+ //#endregion
146
167
  //#region src/utils/clientId.d.ts
147
168
  /**
148
169
  * Client ID utilities for anonymous tracking
@@ -276,17 +297,25 @@ declare function parse({
276
297
  /**
277
298
  * Add or replace the `fCtx` query parameter in a URL with the given context.
278
299
  *
300
+ * When `attribution` is provided (even as an empty object), standard affiliation
301
+ * params (`utm_source`, `utm_medium`, `utm_campaign`, `ref`, `via`, ...) are
302
+ * also appended using gap-fill semantics: pre-existing params on the URL are
303
+ * preserved, and defaults are derived from the context when applicable.
304
+ *
279
305
  * @param args
280
306
  * @param args.url - The URL to update
281
307
  * @param args.context - The context to embed (V1 or V2)
308
+ * @param args.attribution - Optional attribution overrides. Omit to skip UTM/ref params.
282
309
  * @returns The updated URL string, or null on failure
283
310
  */
284
311
  declare function update({
285
312
  url,
286
- context
313
+ context,
314
+ attribution
287
315
  }: {
288
316
  url?: string;
289
317
  context: FrakContextV1 | FrakContextV2;
318
+ attribution?: AttributionParams;
290
319
  }): string | null;
291
320
  /**
292
321
  * Remove the `fCtx` query parameter from a URL.
@@ -415,47 +444,104 @@ declare function createIframe({
415
444
  */
416
445
  declare function findIframeInOpener(pathname?: string): Window | null;
417
446
  //#endregion
418
- //#region src/utils/merchantId.d.ts
447
+ //#region src/utils/inAppBrowser.d.ts
448
+ /**
449
+ * Whether the current device runs iOS (including iPadOS 13+).
450
+ */
451
+ declare const isIOS: boolean;
419
452
  /**
420
- * Merchant ID utilities for auto-fetching from backend
453
+ * Whether the current browser is a social media in-app browser
454
+ * (Instagram, Facebook).
421
455
  */
456
+ declare const isInAppBrowser: boolean;
422
457
  /**
423
- * Fetch merchantId from backend by domain
458
+ * Redirect to external browser from in-app WebView.
424
459
  *
425
- * @param domain - The domain to lookup (defaults to current hostname)
426
- * @param walletUrl - Optional wallet URL to derive backend URL
427
- * @returns The merchantId if found, undefined otherwise
460
+ * - **iOS**: Uses `x-safari-https://` scheme server-side 302 redirects
461
+ * to custom URL schemes are silently swallowed by WKWebView.
462
+ * Direct `window.location.href` assignment works (confirmed iOS 17+).
428
463
  *
429
- * @example
430
- * ```ts
431
- * const merchantId = await fetchMerchantId("shop.example.com");
432
- * if (merchantId) {
433
- * // Use merchantId for tracking
434
- * }
435
- * ```
464
+ * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
465
+ * Content-Type response, forcing the WebView to hand off to the default browser.
466
+ *
467
+ * @param targetUrl - The URL to open in the external browser
436
468
  */
437
- declare function fetchMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
469
+ declare function redirectToExternalBrowser(targetUrl: string): void;
470
+ //#endregion
471
+ //#region src/utils/mergeAttribution.d.ts
438
472
  /**
439
- * Clear the cached merchantId
440
- * Useful for testing or when switching domains
473
+ * Inputs for {@link mergeAttribution}.
441
474
  */
442
- declare function clearMerchantIdCache(): void;
475
+ type MergeAttributionInput = {
476
+ /**
477
+ * Per-call attribution override passed to actions like `displaySharingPage`.
478
+ *
479
+ * - `null` explicitly disables attribution (no UTM/ref/via params are added).
480
+ * - `undefined` means "no per-call override" — defaults apply if present.
481
+ * - An object (including `{}`) merges field-by-field with defaults.
482
+ */
483
+ perCall: AttributionParams | null | undefined;
484
+ /**
485
+ * Pre-merged merchant-level defaults (backend config > SDK static config).
486
+ * `utm_content` is intentionally absent from this shape.
487
+ */
488
+ defaults?: AttributionDefaults;
489
+ /**
490
+ * Per-product `utm_content` override (from the currently selected
491
+ * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
492
+ */
493
+ productUtmContent?: string;
494
+ };
443
495
  /**
444
- * Get merchantId from config or auto-fetch from backend
496
+ * Merge the three attribution layers into a single {@link AttributionParams}
497
+ * value suitable for `FrakContextManager.update`.
445
498
  *
446
- * @param config - The SDK config that may contain merchantId
447
- * @param walletUrl - Optional wallet URL to derive backend URL
448
- * @returns The merchantId if available (from config or fetch), undefined otherwise
449
- */
450
- declare function resolveMerchantId(config: {
451
- metadata?: {
452
- merchantId?: string;
453
- };
454
- }, walletUrl?: string): Promise<string | undefined>;
499
+ * Priority per field:
500
+ * 1. `perCall` (wins)
501
+ * 2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
502
+ * 3. Hardcoded fallbacks resolved later by `FrakContextManager`
503
+ *
504
+ * Special rules:
505
+ * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
506
+ * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
507
+ * applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
508
+ * utm_campaign=<merchantId>, ref=<clientId>, via=frak).
509
+ * - `utm_content` never comes from `defaults`; only `productUtmContent` or
510
+ * `perCall.utmContent` can populate it.
511
+ */
512
+ declare function mergeAttribution({
513
+ perCall,
514
+ defaults,
515
+ productUtmContent
516
+ }: MergeAttributionInput): AttributionParams | undefined;
517
+ //#endregion
518
+ //#region src/utils/sdkConfigStore.d.ts
519
+ declare const GLOBAL_KEY = "__frakSdkConfig";
520
+ declare global {
521
+ interface Window {
522
+ [GLOBAL_KEY]?: SdkResolvedConfig;
523
+ }
524
+ interface WindowEventMap {
525
+ "frak:config": CustomEvent<SdkResolvedConfig>;
526
+ }
527
+ }
528
+ declare function getConfig(): SdkResolvedConfig;
529
+ declare const sdkConfigStore: {
530
+ getConfig: typeof getConfig;
531
+ readonly isResolved: boolean;
532
+ readonly isCacheFresh: boolean;
533
+ setCacheScope(domain: string, lang?: string): void;
534
+ setConfig(config: SdkResolvedConfig): void;
535
+ reset(): void;
536
+ clearCache(): void;
537
+ resolve(domain?: string, walletUrl?: string, lang?: Language): Promise<MerchantConfigResponse | undefined>;
538
+ getMerchantId(): string | undefined;
539
+ resolveMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
540
+ };
455
541
  //#endregion
456
542
  //#region src/utils/sso.d.ts
457
543
  type AppSpecificSsoMetadata = SsoMetadata & {
458
- name: string;
544
+ name?: string;
459
545
  css?: string;
460
546
  };
461
547
  /**
@@ -489,7 +575,7 @@ type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
489
575
  * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
490
576
  * ```
491
577
  */
492
- declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string, clientId: string, css?: string): string;
578
+ declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string | undefined, clientId: string, css?: string): string;
493
579
  /**
494
580
  * Type of compressed the sso data
495
581
  */
@@ -501,7 +587,7 @@ type CompressedSsoData = {
501
587
  l?: "en" | "fr";
502
588
  m: string;
503
589
  md: {
504
- n: string;
590
+ n?: string;
505
591
  css?: string;
506
592
  l?: string;
507
593
  h?: string;
@@ -534,4 +620,4 @@ declare function computeLegacyProductId({
534
620
  domain?: string;
535
621
  }): `0x${string}`;
536
622
  //#endregion
537
- export { getBackendUrl as A, HashProtectedData as B, triggerDeepLinkWithFallback as C, base64urlDecode as D, compressJsonToB64 as E, createIFrameFrakClient as F, TrackArrivalParams as I, TrackArrivalResult as L, locales as M, setupClient as N, base64urlEncode as O, DebugInfoGatherer as P, UtmParams as R, toAndroidIntentUrl as S, decompressJsonFromB64 as T, KeyProvider as V, formatAmount as _, CompressedSsoData as a, isChromiumAndroid as b, clearMerchantIdCache as c, baseIframeProps as d, createIframe as f, getCurrencyAmountKey as g, getSupportedCurrency as h, AppSpecificSsoMetadata as i, LocalesKey as j, getClientId as k, fetchMerchantId as l, getSupportedLocale as m, FrakEvent as n, FullSsoParams as o, findIframeInOpener as p, trackEvent as r, generateSsoUrl as s, computeLegacyProductId as t, resolveMerchantId as u, FrakContextManager as v, DEEP_LINK_SCHEME as w, isFrakDeepLink as x, DeepLinkFallbackOptions as y, CompressedData as z };
623
+ export { base64urlDecode as A, DebugInfoGatherer as B, isChromiumAndroid as C, DEEP_LINK_SCHEME as D, triggerDeepLinkWithFallback as E, withCache as F, CompressedData as H, getBackendUrl as I, LocalesKey as L, getClientId as M, clearAllCache as N, decompressJsonFromB64 as O, getCache as P, locales as R, DeepLinkFallbackOptions as S, toAndroidIntentUrl as T, HashProtectedData as U, createIFrameFrakClient as V, KeyProvider as W, getSupportedLocale as _, CompressedSsoData as a, formatAmount as b, sdkConfigStore as c, isIOS as d, isInAppBrowser as f, findIframeInOpener as g, createIframe as h, AppSpecificSsoMetadata as i, base64urlEncode as j, compressJsonToB64 as k, MergeAttributionInput as l, baseIframeProps as m, FrakEvent as n, FullSsoParams as o, redirectToExternalBrowser as p, trackEvent as r, generateSsoUrl as s, computeLegacyProductId as t, mergeAttribution as u, getSupportedCurrency as v, isFrakDeepLink as w, FrakContextManager as x, getCurrencyAmountKey as y, setupClient as z };
@@ -1,6 +1,6 @@
1
- import { J as Currency, V as SsoMetadata, Y as FrakWalletSdkConfig, _ as TokenAmountType, a as FrakContextV1, i as FrakContext, l as FrakClient, o as FrakContextV2, z as PrepareSsoParamsType } from "./openSso-B0g7-807.cjs";
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-BQ-q-_Y9.js";
2
+ import { Hex } from "viem";
2
3
  import { RpcMessage, RpcResponse } from "@frak-labs/frame-connector";
3
- import { Address, Hex } from "viem";
4
4
 
5
5
  //#region src/types/compression.d.ts
6
6
  /**
@@ -22,35 +22,12 @@ type HashProtectedData<DataType> = Readonly<DataType & {
22
22
  */
23
23
  type KeyProvider<DataType> = (value: DataType) => string[];
24
24
  //#endregion
25
- //#region src/types/tracking.d.ts
26
- type UtmParams = {
27
- source?: string;
28
- medium?: string;
29
- campaign?: string;
30
- term?: string;
31
- content?: string;
32
- };
33
- type TrackArrivalParams = {
34
- /** @deprecated V1 legacy — use referrerClientId for v2 contexts */referrerWallet?: Address;
35
- referrerClientId?: string;
36
- referrerMerchantId?: string; /** Epoch seconds timestamp from the referral link creation */
37
- referralTimestamp?: number;
38
- landingUrl?: string;
39
- utmParams?: UtmParams;
40
- };
41
- type TrackArrivalResult = {
42
- success: boolean;
43
- identityGroupId?: string;
44
- touchpointId?: string;
45
- error?: string;
46
- };
47
- //#endregion
48
25
  //#region src/clients/createIFrameFrakClient.d.ts
49
26
  /**
50
27
  * Create a new iframe Frak client
51
28
  * @param args
52
29
  * @param args.config - The configuration to use for the Frak Wallet SDK.
53
- * When `config.domain` is set, it is forwarded to the iframe handshake so the listener resolves the correct merchant in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
30
+ * When `config.domain` is set, it is used to resolve the correct merchant config in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
54
31
  * @param args.iframe - The iframe to use for the communication
55
32
  * @returns The created Frak Client
56
33
  *
@@ -143,6 +120,50 @@ declare const locales: {
143
120
  */
144
121
  declare function getBackendUrl(walletUrl?: string): string;
145
122
  //#endregion
123
+ //#region src/utils/cache/withCache.d.ts
124
+ type WithCacheOptions = {
125
+ /** The key to cache the data against */cacheKey: string; /** Time in ms that cached data will remain valid. Default: 30_000 (30s). Set to 0 to disable caching. */
126
+ cacheTime?: number;
127
+ };
128
+ /**
129
+ * Returns the result of a given promise, and caches the result for
130
+ * subsequent invocations against a provided cache key.
131
+ *
132
+ * Also deduplicates concurrent calls — if multiple callers request the same
133
+ * cache key while the promise is pending, they share the same promise.
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * // First call fetches, subsequent calls return cached data for 30s
138
+ * const data = await withCache(
139
+ * () => client.request({ method: "frak_getMerchantInformation" }),
140
+ * { cacheKey: "merchantInfo", cacheTime: 30_000 }
141
+ * );
142
+ * ```
143
+ */
144
+ declare function withCache<TData>(fn: () => Promise<TData>, {
145
+ cacheKey,
146
+ cacheTime
147
+ }: WithCacheOptions): Promise<TData>;
148
+ /**
149
+ * Get a cache handle for a specific key, useful for manual invalidation.
150
+ *
151
+ * @example
152
+ * ```ts
153
+ * // Invalidate merchant info cache after a mutation
154
+ * getCache("frak_getMerchantInformation").clear();
155
+ * ```
156
+ */
157
+ declare function getCache(cacheKey: string): {
158
+ /** Clear both the pending promise and the cached response */clear: () => void; /** Check if a non-expired response exists */
159
+ has: (cacheTime?: number) => boolean;
160
+ };
161
+ /**
162
+ * Clear all cached data (both pending promises and resolved responses).
163
+ * Called automatically when the client is destroyed.
164
+ */
165
+ declare function clearAllCache(): void;
166
+ //#endregion
146
167
  //#region src/utils/clientId.d.ts
147
168
  /**
148
169
  * Client ID utilities for anonymous tracking
@@ -276,17 +297,25 @@ declare function parse({
276
297
  /**
277
298
  * Add or replace the `fCtx` query parameter in a URL with the given context.
278
299
  *
300
+ * When `attribution` is provided (even as an empty object), standard affiliation
301
+ * params (`utm_source`, `utm_medium`, `utm_campaign`, `ref`, `via`, ...) are
302
+ * also appended using gap-fill semantics: pre-existing params on the URL are
303
+ * preserved, and defaults are derived from the context when applicable.
304
+ *
279
305
  * @param args
280
306
  * @param args.url - The URL to update
281
307
  * @param args.context - The context to embed (V1 or V2)
308
+ * @param args.attribution - Optional attribution overrides. Omit to skip UTM/ref params.
282
309
  * @returns The updated URL string, or null on failure
283
310
  */
284
311
  declare function update({
285
312
  url,
286
- context
313
+ context,
314
+ attribution
287
315
  }: {
288
316
  url?: string;
289
317
  context: FrakContextV1 | FrakContextV2;
318
+ attribution?: AttributionParams;
290
319
  }): string | null;
291
320
  /**
292
321
  * Remove the `fCtx` query parameter from a URL.
@@ -415,47 +444,104 @@ declare function createIframe({
415
444
  */
416
445
  declare function findIframeInOpener(pathname?: string): Window | null;
417
446
  //#endregion
418
- //#region src/utils/merchantId.d.ts
447
+ //#region src/utils/inAppBrowser.d.ts
448
+ /**
449
+ * Whether the current device runs iOS (including iPadOS 13+).
450
+ */
451
+ declare const isIOS: boolean;
419
452
  /**
420
- * Merchant ID utilities for auto-fetching from backend
453
+ * Whether the current browser is a social media in-app browser
454
+ * (Instagram, Facebook).
421
455
  */
456
+ declare const isInAppBrowser: boolean;
422
457
  /**
423
- * Fetch merchantId from backend by domain
458
+ * Redirect to external browser from in-app WebView.
424
459
  *
425
- * @param domain - The domain to lookup (defaults to current hostname)
426
- * @param walletUrl - Optional wallet URL to derive backend URL
427
- * @returns The merchantId if found, undefined otherwise
460
+ * - **iOS**: Uses `x-safari-https://` scheme server-side 302 redirects
461
+ * to custom URL schemes are silently swallowed by WKWebView.
462
+ * Direct `window.location.href` assignment works (confirmed iOS 17+).
428
463
  *
429
- * @example
430
- * ```ts
431
- * const merchantId = await fetchMerchantId("shop.example.com");
432
- * if (merchantId) {
433
- * // Use merchantId for tracking
434
- * }
435
- * ```
464
+ * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
465
+ * Content-Type response, forcing the WebView to hand off to the default browser.
466
+ *
467
+ * @param targetUrl - The URL to open in the external browser
436
468
  */
437
- declare function fetchMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
469
+ declare function redirectToExternalBrowser(targetUrl: string): void;
470
+ //#endregion
471
+ //#region src/utils/mergeAttribution.d.ts
438
472
  /**
439
- * Clear the cached merchantId
440
- * Useful for testing or when switching domains
473
+ * Inputs for {@link mergeAttribution}.
441
474
  */
442
- declare function clearMerchantIdCache(): void;
475
+ type MergeAttributionInput = {
476
+ /**
477
+ * Per-call attribution override passed to actions like `displaySharingPage`.
478
+ *
479
+ * - `null` explicitly disables attribution (no UTM/ref/via params are added).
480
+ * - `undefined` means "no per-call override" — defaults apply if present.
481
+ * - An object (including `{}`) merges field-by-field with defaults.
482
+ */
483
+ perCall: AttributionParams | null | undefined;
484
+ /**
485
+ * Pre-merged merchant-level defaults (backend config > SDK static config).
486
+ * `utm_content` is intentionally absent from this shape.
487
+ */
488
+ defaults?: AttributionDefaults;
489
+ /**
490
+ * Per-product `utm_content` override (from the currently selected
491
+ * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
492
+ */
493
+ productUtmContent?: string;
494
+ };
443
495
  /**
444
- * Get merchantId from config or auto-fetch from backend
496
+ * Merge the three attribution layers into a single {@link AttributionParams}
497
+ * value suitable for `FrakContextManager.update`.
445
498
  *
446
- * @param config - The SDK config that may contain merchantId
447
- * @param walletUrl - Optional wallet URL to derive backend URL
448
- * @returns The merchantId if available (from config or fetch), undefined otherwise
449
- */
450
- declare function resolveMerchantId(config: {
451
- metadata?: {
452
- merchantId?: string;
453
- };
454
- }, walletUrl?: string): Promise<string | undefined>;
499
+ * Priority per field:
500
+ * 1. `perCall` (wins)
501
+ * 2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
502
+ * 3. Hardcoded fallbacks resolved later by `FrakContextManager`
503
+ *
504
+ * Special rules:
505
+ * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
506
+ * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
507
+ * applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
508
+ * utm_campaign=<merchantId>, ref=<clientId>, via=frak).
509
+ * - `utm_content` never comes from `defaults`; only `productUtmContent` or
510
+ * `perCall.utmContent` can populate it.
511
+ */
512
+ declare function mergeAttribution({
513
+ perCall,
514
+ defaults,
515
+ productUtmContent
516
+ }: MergeAttributionInput): AttributionParams | undefined;
517
+ //#endregion
518
+ //#region src/utils/sdkConfigStore.d.ts
519
+ declare const GLOBAL_KEY = "__frakSdkConfig";
520
+ declare global {
521
+ interface Window {
522
+ [GLOBAL_KEY]?: SdkResolvedConfig;
523
+ }
524
+ interface WindowEventMap {
525
+ "frak:config": CustomEvent<SdkResolvedConfig>;
526
+ }
527
+ }
528
+ declare function getConfig(): SdkResolvedConfig;
529
+ declare const sdkConfigStore: {
530
+ getConfig: typeof getConfig;
531
+ readonly isResolved: boolean;
532
+ readonly isCacheFresh: boolean;
533
+ setCacheScope(domain: string, lang?: string): void;
534
+ setConfig(config: SdkResolvedConfig): void;
535
+ reset(): void;
536
+ clearCache(): void;
537
+ resolve(domain?: string, walletUrl?: string, lang?: Language): Promise<MerchantConfigResponse | undefined>;
538
+ getMerchantId(): string | undefined;
539
+ resolveMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
540
+ };
455
541
  //#endregion
456
542
  //#region src/utils/sso.d.ts
457
543
  type AppSpecificSsoMetadata = SsoMetadata & {
458
- name: string;
544
+ name?: string;
459
545
  css?: string;
460
546
  };
461
547
  /**
@@ -489,7 +575,7 @@ type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
489
575
  * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
490
576
  * ```
491
577
  */
492
- declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string, clientId: string, css?: string): string;
578
+ declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string | undefined, clientId: string, css?: string): string;
493
579
  /**
494
580
  * Type of compressed the sso data
495
581
  */
@@ -501,7 +587,7 @@ type CompressedSsoData = {
501
587
  l?: "en" | "fr";
502
588
  m: string;
503
589
  md: {
504
- n: string;
590
+ n?: string;
505
591
  css?: string;
506
592
  l?: string;
507
593
  h?: string;
@@ -534,4 +620,4 @@ declare function computeLegacyProductId({
534
620
  domain?: string;
535
621
  }): `0x${string}`;
536
622
  //#endregion
537
- export { getBackendUrl as A, HashProtectedData as B, triggerDeepLinkWithFallback as C, base64urlDecode as D, compressJsonToB64 as E, createIFrameFrakClient as F, TrackArrivalParams as I, TrackArrivalResult as L, locales as M, setupClient as N, base64urlEncode as O, DebugInfoGatherer as P, UtmParams as R, toAndroidIntentUrl as S, decompressJsonFromB64 as T, KeyProvider as V, formatAmount as _, CompressedSsoData as a, isChromiumAndroid as b, clearMerchantIdCache as c, baseIframeProps as d, createIframe as f, getCurrencyAmountKey as g, getSupportedCurrency as h, AppSpecificSsoMetadata as i, LocalesKey as j, getClientId as k, fetchMerchantId as l, getSupportedLocale as m, FrakEvent as n, FullSsoParams as o, findIframeInOpener as p, trackEvent as r, generateSsoUrl as s, computeLegacyProductId as t, resolveMerchantId as u, FrakContextManager as v, DEEP_LINK_SCHEME as w, isFrakDeepLink as x, DeepLinkFallbackOptions as y, CompressedData as z };
623
+ export { base64urlDecode as A, DebugInfoGatherer as B, isChromiumAndroid as C, DEEP_LINK_SCHEME as D, triggerDeepLinkWithFallback as E, withCache as F, CompressedData as H, getBackendUrl as I, LocalesKey as L, getClientId as M, clearAllCache as N, decompressJsonFromB64 as O, getCache as P, locales as R, DeepLinkFallbackOptions as S, toAndroidIntentUrl as T, HashProtectedData as U, createIFrameFrakClient as V, KeyProvider as W, getSupportedLocale as _, CompressedSsoData as a, formatAmount as b, sdkConfigStore as c, isIOS as d, isInAppBrowser as f, findIframeInOpener as g, createIframe as h, AppSpecificSsoMetadata as i, base64urlEncode as j, compressJsonToB64 as k, MergeAttributionInput as l, baseIframeProps as m, FrakEvent as n, FullSsoParams as o, redirectToExternalBrowser as p, trackEvent as r, generateSsoUrl as s, computeLegacyProductId as t, mergeAttribution as u, getSupportedCurrency as v, isFrakDeepLink as w, FrakContextManager as x, getCurrencyAmountKey as y, setupClient as z };