@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.61e6fb99

package/dist/{computeLegacyProductId-CCAZvLa5.d.cts → index-B_Uj-puh.d.ts}

@@ -1,6 +1,6 @@
-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";
+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-B6pD2oA6.js";
+import { Hex } from "viem";
 import { RpcMessage, RpcResponse } from "@frak-labs/frame-connector";
-import { Address, Hex } from "viem";
 
 //#region src/types/compression.d.ts
 /**
@@ -22,35 +22,12 @@ type HashProtectedData<DataType> = Readonly<DataType & {
  */
 type KeyProvider<DataType> = (value: DataType) => string[];
 //#endregion
-//#region src/types/tracking.d.ts
-type UtmParams = {
-  source?: string;
-  medium?: string;
-  campaign?: string;
-  term?: string;
-  content?: string;
-};
-type TrackArrivalParams = {
-  /** @deprecated V1 legacy — use referrerClientId for v2 contexts */referrerWallet?: Address;
-  referrerClientId?: string;
-  referrerMerchantId?: string; /** Epoch seconds timestamp from the referral link creation */
-  referralTimestamp?: number;
-  landingUrl?: string;
-  utmParams?: UtmParams;
-};
-type TrackArrivalResult = {
-  success: boolean;
-  identityGroupId?: string;
-  touchpointId?: string;
-  error?: string;
-};
-//#endregion
 //#region src/clients/createIFrameFrakClient.d.ts
 /**
  * Create a new iframe Frak client
  * @param args
  * @param args.config - The configuration to use for the Frak Wallet SDK.
- *   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).
+ *   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).
  * @param args.iframe - The iframe to use for the communication
  * @returns The created Frak Client
  *
@@ -134,6 +111,111 @@ declare const locales: {
   readonly gbp: "en-GB";
 };
 //#endregion
+//#region src/utils/analytics/events/component.d.ts
+type ButtonBaseProps = {
+  placement?: string;
+  target_interaction?: string;
+  has_reward?: boolean;
+};
+type BannerVariant = "referral" | "inapp";
+type BannerOutcome = "clicked" | "dismissed";
+type PostPurchaseVariant = "referrer" | "referee";
+type ShareClickAction = "share-modal" | "embedded-wallet" | "sharing-page";
+type SdkComponentEventMap = {
+  share_button_clicked: ButtonBaseProps & {
+    click_action: ShareClickAction;
+  };
+  share_modal_error: ButtonBaseProps & {
+    error?: string;
+  };
+  open_in_app_clicked: {
+    placement?: string;
+    path: string;
+  };
+  app_not_installed: {
+    placement?: string;
+    path: string;
+  };
+  banner_impression: {
+    placement?: string;
+    variant: BannerVariant;
+    has_reward?: boolean;
+  };
+  banner_resolved: {
+    placement?: string;
+    variant: BannerVariant;
+    outcome: BannerOutcome;
+  };
+  post_purchase_impression: {
+    placement?: string;
+    variant: PostPurchaseVariant;
+    has_reward?: boolean;
+  };
+  post_purchase_clicked: {
+    placement?: string;
+    variant: PostPurchaseVariant;
+  };
+};
+//#endregion
+//#region src/utils/analytics/events/lifecycle.d.ts
+type SdkHandshakeFailureReason = "timeout" | "origin" | "asset_push" | "unknown";
+type SdkLifecycleEventMap = {
+  sdk_initialized: {
+    sdkVersion?: string;
+  };
+  sdk_iframe_connected: {
+    handshake_duration_ms: number;
+  };
+  sdk_iframe_handshake_failed: {
+    reason: SdkHandshakeFailureReason;
+  };
+  /**
+   * Emitted by the CDN bootstrap when `initFrakSdk()` throws before a
+   * client is available. Uses a transient OpenPanel instance so broken
+   * partner integrations are still captured.
+   */
+  sdk_init_failed: {
+    reason: string;
+    config_missing?: boolean;
+  };
+};
+//#endregion
+//#region src/utils/analytics/events/referral.d.ts
+type SdkReferralEventMap = {
+  user_referred_started: {
+    referrer?: string;
+    referrerClientId?: string;
+    walletStatus?: string;
+  };
+  user_referred_completed: {
+    status: "success";
+  };
+};
+//#endregion
+//#region src/utils/analytics/events/index.d.ts
+/**
+ * Merged SDK event map. Consumed by the SDK's typed `trackEvent`.
+ * Stays isolated from wallet-shared because the SDK ships in partner
+ * bundles (different OpenPanel client id, no wallet-shared dependency
+ * allowed — see `packages/wallet-shared/AGENTS.md`).
+ */
+type SdkEventMap = SdkLifecycleEventMap & SdkComponentEventMap & SdkReferralEventMap;
+//#endregion
+//#region src/utils/analytics/trackEvent.d.ts
+/**
+ * Track an analytics event via the SDK's OpenPanel instance.
+ * Fire-and-forget — silently catches errors so analytics never break a
+ * partner integration.
+ *
+ * The client must be passed explicitly because the OpenPanel instance is
+ * scoped to each `FrakClient` (a partner site may hold multiple iframes).
+ *
+ * @param client - The Frak client instance (no-op if undefined)
+ * @param event - Typed event name from the SDK event map
+ * @param properties - Typed properties for the given event
+ */
+declare function trackEvent<K extends keyof SdkEventMap>(client: FrakClient | undefined, event: K, properties?: SdkEventMap[K]): void;
+//#endregion
 //#region src/utils/backendUrl.d.ts
 /**
  * Get the backend URL for API calls
@@ -143,6 +225,50 @@ declare const locales: {
  */
 declare function getBackendUrl(walletUrl?: string): string;
 //#endregion
+//#region src/utils/cache/withCache.d.ts
+type WithCacheOptions = {
+  /** 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. */
+  cacheTime?: number;
+};
+/**
+ * Returns the result of a given promise, and caches the result for
+ * subsequent invocations against a provided cache key.
+ *
+ * Also deduplicates concurrent calls — if multiple callers request the same
+ * cache key while the promise is pending, they share the same promise.
+ *
+ * @example
+ * ```ts
+ * // First call fetches, subsequent calls return cached data for 30s
+ * const data = await withCache(
+ *     () => client.request({ method: "frak_getMerchantInformation" }),
+ *     { cacheKey: "merchantInfo", cacheTime: 30_000 }
+ * );
+ * ```
+ */
+declare function withCache<TData>(fn: () => Promise<TData>, {
+  cacheKey,
+  cacheTime
+}: WithCacheOptions): Promise<TData>;
+/**
+ * Get a cache handle for a specific key, useful for manual invalidation.
+ *
+ * @example
+ * ```ts
+ * // Invalidate merchant info cache after a mutation
+ * getCache("frak_getMerchantInformation").clear();
+ * ```
+ */
+declare function getCache(cacheKey: string): {
+  /** Clear both the pending promise and the cached response */clear: () => void; /** Check if a non-expired response exists */
+  has: (cacheTime?: number) => boolean;
+};
+/**
+ * Clear all cached data (both pending promises and resolved responses).
+ * Called automatically when the client is destroyed.
+ */
+declare function clearAllCache(): void;
+//#endregion
 //#region src/utils/clientId.d.ts
 /**
  * Client ID utilities for anonymous tracking
@@ -276,17 +402,25 @@ declare function parse({
 /**
  * Add or replace the `fCtx` query parameter in a URL with the given context.
  *
+ * Standard affiliation params (`utm_source`, `utm_medium`, `utm_campaign`,
+ * `ref`, `via`, ...) are always appended using gap-fill semantics: pre-existing
+ * params on the URL are preserved, defaults are derived from the context when
+ * applicable, and `attribution` overrides take precedence when provided.
+ *
  * @param args
  * @param args.url - The URL to update
  * @param args.context - The context to embed (V1 or V2)
+ * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
  * @returns The updated URL string, or null on failure
  */
 declare function update({
   url,
-  context
+  context,
+  attribution
 }: {
   url?: string;
   context: FrakContextV1 | FrakContextV2;
+  attribution?: AttributionParams;
 }): string | null;
 /**
  * Remove the `fCtx` query parameter from a URL.
@@ -415,47 +549,104 @@ declare function createIframe({
  */
 declare function findIframeInOpener(pathname?: string): Window | null;
 //#endregion
-//#region src/utils/merchantId.d.ts
+//#region src/utils/inAppBrowser.d.ts
+/**
+ * Whether the current device runs iOS (including iPadOS 13+).
+ */
+declare const isIOS: boolean;
 /**
- * Merchant ID utilities for auto-fetching from backend
+ * Whether the current browser is a social media in-app browser
+ * (Instagram, Facebook).
  */
+declare const isInAppBrowser: boolean;
 /**
- * Fetch merchantId from backend by domain
+ * Redirect to external browser from in-app WebView.
  *
- * @param domain - The domain to lookup (defaults to current hostname)
- * @param walletUrl - Optional wallet URL to derive backend URL
- * @returns The merchantId if found, undefined otherwise
+ * - **iOS**: Uses `x-safari-https://` scheme — server-side 302 redirects
+ *   to custom URL schemes are silently swallowed by WKWebView.
+ *   Direct `window.location.href` assignment works (confirmed iOS 17+).
  *
- * @example
- * ```ts
- * const merchantId = await fetchMerchantId("shop.example.com");
- * if (merchantId) {
- *     // Use merchantId for tracking
- * }
- * ```
+ * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
+ *   Content-Type response, forcing the WebView to hand off to the default browser.
+ *
+ * @param targetUrl - The URL to open in the external browser
  */
-declare function fetchMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
+declare function redirectToExternalBrowser(targetUrl: string): void;
+//#endregion
+//#region src/utils/mergeAttribution.d.ts
 /**
- * Clear the cached merchantId
- * Useful for testing or when switching domains
+ * Inputs for {@link mergeAttribution}.
  */
-declare function clearMerchantIdCache(): void;
+type MergeAttributionInput = {
+  /**
+   * Per-call attribution override passed to actions like `displaySharingPage`.
+   *
+   * - `null` explicitly disables attribution (no UTM/ref/via params are added).
+   * - `undefined` means "no per-call override" — defaults apply if present.
+   * - An object (including `{}`) merges field-by-field with defaults.
+   */
+  perCall: AttributionParams | null | undefined;
+  /**
+   * Pre-merged merchant-level defaults (backend config > SDK static config).
+   * `utm_content` is intentionally absent from this shape.
+   */
+  defaults?: AttributionDefaults;
+  /**
+   * Per-product `utm_content` override (from the currently selected
+   * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
+   */
+  productUtmContent?: string;
+};
 /**
- * Get merchantId from config or auto-fetch from backend
+ * Merge the three attribution layers into a single {@link AttributionParams}
+ * value suitable for `FrakContextManager.update`.
  *
- * @param config - The SDK config that may contain merchantId
- * @param walletUrl - Optional wallet URL to derive backend URL
- * @returns The merchantId if available (from config or fetch), undefined otherwise
- */
-declare function resolveMerchantId(config: {
-  metadata?: {
-    merchantId?: string;
-  };
-}, walletUrl?: string): Promise<string | undefined>;
+ * Priority per field:
+ *   1. `perCall` (wins)
+ *   2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
+ *   3. Hardcoded fallbacks resolved later by `FrakContextManager`
+ *
+ * Special rules:
+ * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
+ * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
+ *   applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
+ *   utm_campaign=<merchantId>, ref=<clientId>, via=frak).
+ * - `utm_content` never comes from `defaults`; only `productUtmContent` or
+ *   `perCall.utmContent` can populate it.
+ */
+declare function mergeAttribution({
+  perCall,
+  defaults,
+  productUtmContent
+}: MergeAttributionInput): AttributionParams | undefined;
+//#endregion
+//#region src/utils/sdkConfigStore.d.ts
+declare const GLOBAL_KEY = "__frakSdkConfig";
+declare global {
+  interface Window {
+    [GLOBAL_KEY]?: SdkResolvedConfig;
+  }
+  interface WindowEventMap {
+    "frak:config": CustomEvent<SdkResolvedConfig>;
+  }
+}
+declare function getConfig(): SdkResolvedConfig;
+declare const sdkConfigStore: {
+  getConfig: typeof getConfig;
+  readonly isResolved: boolean;
+  readonly isCacheFresh: boolean;
+  setCacheScope(domain: string, lang?: string): void;
+  setConfig(config: SdkResolvedConfig): void;
+  reset(): void;
+  clearCache(): void;
+  resolve(domain?: string, walletUrl?: string, lang?: Language): Promise<MerchantConfigResponse | undefined>;
+  getMerchantId(): string | undefined;
+  resolveMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
+};
 //#endregion
 //#region src/utils/sso.d.ts
 type AppSpecificSsoMetadata = SsoMetadata & {
-  name: string;
+  name?: string;
   css?: string;
 };
 /**
@@ -489,7 +680,7 @@ type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
  * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
  * ```
  */
-declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string, clientId: string, css?: string): string;
+declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string | undefined, clientId: string, css?: string): string;
 /**
  * Type of compressed the sso data
  */
@@ -501,28 +692,13 @@ type CompressedSsoData = {
   l?: "en" | "fr";
   m: string;
   md: {
-    n: string;
+    n?: string;
     css?: string;
     l?: string;
     h?: string;
   };
 };
 //#endregion
-//#region src/utils/trackEvent.d.ts
-/**
- * Analytics event names emitted by the SDK
- */
-type FrakEvent = "share_button_clicked" | "wallet_button_clicked" | "open_in_app_clicked" | "open_in_app_login_clicked" | "app_not_installed" | "share_modal_error" | "user_referred_started" | "user_referred_completed" | "user_referred_error";
-type EventProps = Record<string, unknown>;
-/**
- * Track an analytics event via OpenPanel.
- * Fire-and-forget: silently catches errors.
- * @param client - The Frak client instance (no-op if undefined)
- * @param event - The event name to track
- * @param props - Optional event properties
- */
-declare function trackEvent(client: FrakClient | undefined, event: FrakEvent, props?: EventProps): void;
-//#endregion
 //#region src/utils/computeLegacyProductId.d.ts
 /**
  * Compute the legacy product id from a domain
@@ -534,4 +710,4 @@ declare function computeLegacyProductId({
   domain?: string;
 }): `0x${string}`;
 //#endregion
-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 };
+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 };