@frak-labs/core-sdk 0.1.1 → 0.2.0-beta.7898df5b

package/dist/computeLegacyProductId-CCAZvLa5.d.cts

@@ -0,0 +1,537 @@
+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 { RpcMessage, RpcResponse } from "@frak-labs/frame-connector";
+import { Address, Hex } from "viem";
+
+//#region src/types/compression.d.ts
+/**
+ * The received encoded data from a client
+ *  -> The encoded should contain a HashProtectedData once decoded
+ *  @ignore
+ */
+type CompressedData = Uint8Array;
+/**
+ * The encoded data to send to a client / received by a client
+ *  @ignore
+ */
+type HashProtectedData<DataType> = Readonly<DataType & {
+  validationHash: string;
+}>;
+/**
+ * Represent a key provider used for the hashed and secure compression
+ *  @ignore
+ */
+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).
+ * @param args.iframe - The iframe to use for the communication
+ * @returns The created Frak Client
+ *
+ * @example
+ * const frakConfig: FrakWalletSdkConfig = {
+ *     metadata: {
+ *         name: "My app title",
+ *     },
+ * }
+ * const iframe = await createIframe({ config: frakConfig });
+ * const client = createIFrameFrakClient({ config: frakConfig, iframe });
+ */
+declare function createIFrameFrakClient({
+  config,
+  iframe
+}: {
+  config: FrakWalletSdkConfig;
+  iframe: HTMLIFrameElement;
+}): FrakClient;
+//#endregion
+//#region src/clients/DebugInfo.d.ts
+/** @ignore */
+declare class DebugInfoGatherer {
+  private config?;
+  private iframe?;
+  private isSetupDone;
+  private lastResponse;
+  private lastRequest;
+  constructor(config?: FrakWalletSdkConfig, iframe?: HTMLIFrameElement);
+  setLastResponse(message: RpcMessage, response: RpcResponse): void;
+  setLastRequest(event: RpcMessage): void;
+  updateSetupStatus(status: boolean): void;
+  private base64Encode;
+  /**
+   * Extract information from the iframe status
+   */
+  private getIframeStatus;
+  private getNavigatorInfo;
+  private gatherDebugInfo;
+  static empty(): DebugInfoGatherer;
+  /**
+   * Format Frak debug information
+   */
+  formatDebugInfo(error: Error | unknown | string): string;
+}
+//#endregion
+//#region src/clients/setupClient.d.ts
+/**
+ * Directly setup the Frak client with an iframe
+ * Return when the FrakClient is ready (setup and communication estbalished with the wallet)
+ *
+ * @param config - The configuration to use for the Frak Wallet SDK
+ * @returns a Promise with the Frak Client
+ *
+ * @example
+ * const frakConfig: FrakWalletSdkConfig = {
+ *     metadata: {
+ *         name: "My app title",
+ *     },
+ * }
+ * const client = await setupClient({ config: frakConfig });
+ */
+declare function setupClient({
+  config
+}: {
+  config: FrakWalletSdkConfig;
+}): Promise<FrakClient | undefined>;
+//#endregion
+//#region src/constants/locales.d.ts
+/**
+ * The keys for each locales
+ * @inline
+ */
+type LocalesKey = keyof typeof locales;
+/**
+ * Map the currency to the locale
+ */
+declare const locales: {
+  readonly eur: "fr-FR";
+  readonly usd: "en-US";
+  readonly gbp: "en-GB";
+};
+//#endregion
+//#region src/utils/backendUrl.d.ts
+/**
+ * Get the backend URL for API calls
+ * Tries to derive from SDK config, falls back to production
+ *
+ * @param walletUrl - Optional wallet URL to derive from (overrides global config)
+ */
+declare function getBackendUrl(walletUrl?: string): string;
+//#endregion
+//#region src/utils/clientId.d.ts
+/**
+ * Client ID utilities for anonymous tracking
+ * Generates and persists a UUID fingerprint for referral attribution
+ */
+/**
+ * Get the client ID from localStorage, creating one if it doesn't exist
+ * @returns The client ID (UUID format)
+ */
+declare function getClientId(): string;
+//#endregion
+//#region src/utils/compression/b64.d.ts
+/**
+ * Encode a buffer to a base64url encoded string
+ * @param buffer The buffer to encode
+ * @returns The encoded string
+ */
+declare function base64urlEncode(buffer: Uint8Array): string;
+/**
+ * Decode a base64url encoded string
+ * @param value The value to decode
+ * @returns The decoded value
+ */
+declare function base64urlDecode(value: string): Uint8Array;
+//#endregion
+//#region src/utils/compression/compress.d.ts
+/**
+ * Compress json data
+ * @param data
+ * @ignore
+ */
+declare function compressJsonToB64(data: unknown): string;
+//#endregion
+//#region src/utils/compression/decompress.d.ts
+/**
+ * Decompress json data
+ * @param data
+ * @ignore
+ */
+declare function decompressJsonFromB64<T>(data: string): T | null;
+//#endregion
+//#region src/utils/constants.d.ts
+/**
+ * Deep link scheme for Frak Wallet mobile app
+ */
+declare const DEEP_LINK_SCHEME = "frakwallet://";
+//#endregion
+//#region src/utils/deepLinkWithFallback.d.ts
+/**
+ * Options for deep link with fallback
+ */
+type DeepLinkFallbackOptions = {
+  /** Timeout in ms before triggering fallback (default: 2500ms) */timeout?: number; /** Callback invoked when fallback is triggered (app not installed) */
+  onFallback?: () => void;
+};
+/**
+ * Check if running on a Chromium-based Android browser.
+ *
+ * On Chrome Android, custom scheme deep links (e.g. frakwallet://) trigger
+ * a confirmation bar ("Continue to Frak Wallet?"). Using intent:// URLs
+ * instead bypasses this for Chromium browsers while keeping custom scheme
+ * fallback for non-Chromium browsers (e.g. Firefox) where it works fine.
+ */
+declare function isChromiumAndroid(): boolean;
+/**
+ * Convert a frakwallet:// deep link to an Android intent:// URL.
+ *
+ * Intent URLs let Chromium browsers open the app directly without
+ * showing the "Continue to app?" confirmation bar.
+ *
+ * Note: We intentionally omit the `package` parameter. Including it
+ * causes Chrome to redirect to the Play Store when the app is not
+ * installed, which breaks the visibility-based fallback detection.
+ * Without `package`, Chrome simply does nothing when the app is
+ * missing, allowing the fallback mechanism to fire correctly.
+ *
+ * Format: intent://path#Intent;scheme=frakwallet;end
+ */
+declare function toAndroidIntentUrl(deepLink: string): string;
+/**
+ * Trigger a deep link with visibility-based fallback detection.
+ *
+ * Uses the Page Visibility API to detect if the app opened (page goes hidden).
+ * If the page remains visible after the timeout, assumes app is not installed
+ * and invokes the onFallback callback.
+ *
+ * On Chromium Android, converts custom scheme to intent:// URL to avoid
+ * the "Continue to app?" confirmation bar.
+ *
+ * @param deepLink - The deep link URL to trigger (e.g., "frakwallet://wallet")
+ * @param options - Optional configuration (timeout, onFallback callback)
+ */
+declare function triggerDeepLinkWithFallback(deepLink: string, options?: DeepLinkFallbackOptions): void;
+/**
+ * Check if a URL is a Frak deep link
+ */
+declare function isFrakDeepLink(url: string): boolean;
+//#endregion
+//#region src/utils/FrakContext.d.ts
+/**
+ * Compress a Frak context into a URL-safe string.
+ *
+ * - V2 contexts are serialized as compressed JSON (base64url).
+ * - V1 contexts encode the wallet address as raw bytes (base64url).
+ *
+ * @param context - The context to compress (V1 or V2)
+ * @returns A compressed base64url string, or undefined on failure
+ */
+declare function compress(context?: FrakContextV1 | FrakContextV2): string | undefined;
+/**
+ * Decompress a base64url string back into a Frak context.
+ *
+ * Attempts V2 JSON decompression first, then falls back to V1 raw bytes.
+ *
+ * @param context - The compressed context string
+ * @returns The decompressed FrakContext, or undefined on failure
+ */
+declare function decompress(context?: string): FrakContext | undefined;
+/**
+ * Parse a URL to extract the Frak referral context from the `fCtx` query parameter.
+ *
+ * @param args
+ * @param args.url - The URL to parse
+ * @returns The parsed FrakContext, or null if absent
+ */
+declare function parse({
+  url
+}: {
+  url: string;
+}): FrakContext | null | undefined;
+/**
+ * Add or replace the `fCtx` query parameter in a URL with the given context.
+ *
+ * @param args
+ * @param args.url - The URL to update
+ * @param args.context - The context to embed (V1 or V2)
+ * @returns The updated URL string, or null on failure
+ */
+declare function update({
+  url,
+  context
+}: {
+  url?: string;
+  context: FrakContextV1 | FrakContextV2;
+}): string | null;
+/**
+ * Remove the `fCtx` query parameter from a URL.
+ *
+ * @param url - The URL to strip the context from
+ * @returns The cleaned URL string
+ */
+declare function remove(url: string): string;
+/**
+ * Replace the current browser URL with an updated Frak context.
+ *
+ * - If `context` is non-null, embeds it via {@link update}.
+ * - If `context` is null, strips the context via {@link remove}.
+ *
+ * @param args
+ * @param args.url - Base URL (defaults to `window.location.href`)
+ * @param args.context - Context to set, or null to remove
+ */
+declare function replaceUrl({
+  url: baseUrl,
+  context
+}: {
+  url?: string;
+  context: FrakContextV1 | FrakContextV2 | null;
+}): void;
+/**
+ * Manager for Frak referral context in URLs.
+ *
+ * Handles compression, decompression, URL parsing, and browser history updates
+ * for both V1 (wallet address) and V2 (anonymous clientId) referral contexts.
+ */
+declare const FrakContextManager: {
+  compress: typeof compress;
+  decompress: typeof decompress;
+  parse: typeof parse;
+  update: typeof update;
+  remove: typeof remove;
+  replaceUrl: typeof replaceUrl;
+};
+//#endregion
+//#region src/utils/formatAmount.d.ts
+/**
+ * Format a numeric amount as a localized currency string
+ * @param amount - The raw numeric amount to format
+ * @param currency - Optional currency config; defaults to EUR/fr-FR when omitted
+ * @returns Localized currency string (e.g. "1 500 €", "$1,500")
+ */
+declare function formatAmount(amount: number, currency?: Currency): string;
+//#endregion
+//#region src/utils/getCurrencyAmountKey.d.ts
+/**
+ * Get the currency amount key for a given currency
+ * @param currency - The currency to use
+ * @returns The currency amount key
+ */
+declare function getCurrencyAmountKey(currency?: Currency): keyof TokenAmountType;
+//#endregion
+//#region src/utils/getSupportedCurrency.d.ts
+/**
+ * Get the supported currency for a given currency
+ * @param currency - The currency to use
+ * @returns The supported currency
+ */
+declare function getSupportedCurrency(currency?: Currency): Currency;
+//#endregion
+//#region src/utils/getSupportedLocale.d.ts
+/**
+ * Get the supported locale for a given currency
+ * @param currency - The currency to use
+ * @returns The supported locale
+ */
+declare function getSupportedLocale(currency?: Currency): (typeof locales)[LocalesKey];
+//#endregion
+//#region src/utils/iframeHelper.d.ts
+/**
+ * Base props for the iframe
+ * @ignore
+ */
+declare const baseIframeProps: {
+  id: string;
+  name: string;
+  title: string;
+  allow: string;
+  style: {
+    width: string;
+    height: string;
+    border: string;
+    position: string;
+    zIndex: number;
+    top: string;
+    left: string;
+    colorScheme: string;
+  };
+};
+/**
+ * Create the Frak iframe
+ * @param args
+ * @param args.walletBaseUrl - Use `config.walletUrl` instead. Will be removed in future versions.
+ * @param args.config - The configuration object containing iframe options, including the replacement for `walletBaseUrl`.
+ */
+declare function createIframe({
+  walletBaseUrl,
+  config
+}: {
+  walletBaseUrl?: string;
+  config?: FrakWalletSdkConfig;
+}): Promise<HTMLIFrameElement | undefined>;
+/**
+ * Find an iframe within window.opener by pathname
+ *
+ * When a popup is opened via window.open from an iframe, window.opener points to
+ * the parent window, not the iframe itself. This utility searches through all frames
+ * in window.opener to find an iframe matching the specified pathname.
+ *
+ * @param pathname - The pathname to search for (default: "/listener")
+ * @returns The matching iframe window, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Find the default /listener iframe
+ * const listenerIframe = findIframeInOpener();
+ *
+ * // Find a custom iframe
+ * const customIframe = findIframeInOpener("/my-custom-iframe");
+ * ```
+ */
+declare function findIframeInOpener(pathname?: string): Window | null;
+//#endregion
+//#region src/utils/merchantId.d.ts
+/**
+ * Merchant ID utilities for auto-fetching from backend
+ */
+/**
+ * Fetch merchantId from backend by domain
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const merchantId = await fetchMerchantId("shop.example.com");
+ * if (merchantId) {
+ *     // Use merchantId for tracking
+ * }
+ * ```
+ */
+declare function fetchMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
+/**
+ * Clear the cached merchantId
+ * Useful for testing or when switching domains
+ */
+declare function clearMerchantIdCache(): void;
+/**
+ * Get merchantId from config or auto-fetch from backend
+ *
+ * @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>;
+//#endregion
+//#region src/utils/sso.d.ts
+type AppSpecificSsoMetadata = SsoMetadata & {
+  name: string;
+  css?: string;
+};
+/**
+ * The full SSO params that will be used for compression
+ */
+type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
+  metadata: AppSpecificSsoMetadata;
+  merchantId: string;
+  clientId: string;
+};
+/**
+ * Generate SSO URL with compressed parameters
+ * This mirrors the wallet's getOpenSsoLink() function
+ *
+ * @param walletUrl - Base wallet URL (e.g., "https://wallet.frak.id")
+ * @param params - SSO parameters
+ * @param merchantId - Merchant identifier
+ * @param name - Application name
+ * @param clientId - Client identifier for identity tracking
+ * @param css - Optional custom CSS
+ * @returns Complete SSO URL ready to open in popup or redirect
+ *
+ * @example
+ * ```ts
+ * const ssoUrl = generateSsoUrl(
+ *   "https://wallet.frak.id",
+ *   { metadata: { logoUrl: "..." }, directExit: true },
+ *   "0x123...",
+ *   "My App"
+ * );
+ * // 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;
+/**
+ * Type of compressed the sso data
+ */
+type CompressedSsoData = {
+  id?: Hex;
+  cId: string;
+  r?: string;
+  d?: boolean;
+  l?: "en" | "fr";
+  m: string;
+  md: {
+    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
+ * @ignore
+ */
+declare function computeLegacyProductId({
+  domain
+}?: {
+  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 };