@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.1e44255d

package/src/clients/transports/iframeLifecycleManager.ts

@@ -0,0 +1,229 @@
+import { Deferred } from "@frak-labs/frame-connector";
+import type { FrakLifecycleEvent } from "../../types";
+import { getClientId } from "../../utils/clientId";
+import { BACKUP_KEY } from "../../utils/constants";
+import {
+    isFrakDeepLink,
+    triggerDeepLinkWithFallback,
+} from "../../utils/deepLinkWithFallback";
+import { changeIframeVisibility } from "../../utils/iframeHelper";
+
+/**
+ * Detect iOS in-app browsers (Instagram, Facebook) where server-side
+ * 302 redirects to custom URL schemes (x-safari-https://) are silently
+ * swallowed by WKWebView. Direct window.location.href assignment works.
+ */
+const isIOSInAppBrowser = (() => {
+    if (typeof navigator === "undefined") return false;
+    const ua = navigator.userAgent;
+    // Standard iOS or iPadOS 13+ (reports as Macintosh with touch)
+    const isIOS =
+        /iPhone|iPad|iPod/i.test(ua) ||
+        (/Macintosh/i.test(ua) && navigator.maxTouchPoints > 1);
+    if (!isIOS) return false;
+    const lower = ua.toLowerCase();
+    return (
+        lower.includes("instagram") ||
+        lower.includes("fban") ||
+        lower.includes("fbav") ||
+        lower.includes("facebook")
+    );
+})();
+
+/** @ignore */
+export type IframeLifecycleManager = {
+    isConnected: Promise<boolean>;
+    handleEvent: (messageEvent: FrakLifecycleEvent) => Promise<void>;
+};
+
+/**
+ * Handle backup storage
+ */
+function handleBackup(backup: string | undefined): void {
+    if (backup) {
+        localStorage.setItem(BACKUP_KEY, backup);
+    } else {
+        localStorage.removeItem(BACKUP_KEY);
+    }
+}
+
+/**
+ * Handle handshake with iframe — sends client metadata so the listener can resolve the correct merchant
+ * @param iframe - The iframe element to post the handshake response to
+ * @param token - The handshake token received from the iframe
+ * @param targetOrigin - The target origin for postMessage security
+ * @param configDomain - Optional override domain for merchant resolution in tunneled/proxied environments
+ */
+function handleHandshake(
+    iframe: HTMLIFrameElement,
+    token: string,
+    targetOrigin: string,
+    configDomain?: string
+): void {
+    const url = new URL(window.location.href);
+    const pendingMergeToken = url.searchParams.get("fmt") ?? undefined;
+
+    iframe.contentWindow?.postMessage(
+        {
+            clientLifecycle: "handshake-response",
+            data: {
+                token,
+                currentUrl: window.location.href,
+                pendingMergeToken,
+                configDomain,
+                clientId: getClientId(),
+            },
+        },
+        targetOrigin
+    );
+
+    if (pendingMergeToken) {
+        url.searchParams.delete("fmt");
+        window.history.replaceState({}, "", url.toString());
+    }
+}
+
+/**
+ * Compute final redirect URL with parameter substitution
+ */
+function computeRedirectUrl(
+    baseRedirectUrl: string,
+    mergeToken?: string
+): string {
+    try {
+        const redirectUrl = new URL(baseRedirectUrl);
+        if (!redirectUrl.searchParams.has("u")) {
+            return baseRedirectUrl;
+        }
+
+        redirectUrl.searchParams.delete("u");
+        redirectUrl.searchParams.append("u", window.location.href);
+
+        if (mergeToken) {
+            redirectUrl.searchParams.append("fmt", mergeToken);
+        }
+
+        return redirectUrl.toString();
+    } catch {
+        return baseRedirectUrl;
+    }
+}
+
+/**
+ * Redirect current page to Safari via x-safari-https:// scheme.
+ * Used on iOS in-app browsers where backend 302 → custom scheme fails.
+ */
+function redirectToSafari(mergeToken?: string) {
+    const url = new URL(window.location.href);
+    if (mergeToken) {
+        url.searchParams.set("fmt", mergeToken);
+    }
+    const scheme =
+        url.protocol === "http:" ? "x-safari-http" : "x-safari-https";
+    window.location.href = `${scheme}://${url.host}${url.pathname}${url.search}${url.hash}`;
+}
+
+/**
+ * Check if this is a social/in-app-browser escape redirect (contains /common/social)
+ */
+function isSocialRedirect(url: string): boolean {
+    return url.includes("/common/social");
+}
+
+/**
+ * Handle redirect with deep link fallback
+ */
+function handleRedirect(
+    iframe: HTMLIFrameElement,
+    baseRedirectUrl: string,
+    targetOrigin: string,
+    mergeToken?: string
+): void {
+    if (isFrakDeepLink(baseRedirectUrl)) {
+        const finalUrl = computeRedirectUrl(baseRedirectUrl, mergeToken);
+        triggerDeepLinkWithFallback(finalUrl, {
+            onFallback: () => {
+                iframe.contentWindow?.postMessage(
+                    {
+                        clientLifecycle: "deep-link-failed",
+                        data: { originalUrl: finalUrl },
+                    },
+                    targetOrigin
+                );
+            },
+        });
+    } else if (isIOSInAppBrowser && isSocialRedirect(baseRedirectUrl)) {
+        // iOS WKWebView silently swallows 302 redirects to custom URL
+        // schemes — bypass the server redirect entirely
+        redirectToSafari(mergeToken);
+    } else {
+        const finalUrl = computeRedirectUrl(baseRedirectUrl, mergeToken);
+        window.location.href = finalUrl;
+    }
+}
+
+/**
+ * Create a new iframe lifecycle handler
+ * @param args
+ * @param args.iframe - The iframe element used for wallet communication
+ * @param args.targetOrigin - The wallet URL origin for postMessage security
+ * @param args.configDomain - Optional domain override forwarded during handshake for tunneled/proxied environments
+ * @ignore
+ */
+export function createIFrameLifecycleManager({
+    iframe,
+    targetOrigin,
+    configDomain,
+}: {
+    iframe: HTMLIFrameElement;
+    targetOrigin: string;
+    configDomain?: string;
+}): IframeLifecycleManager {
+    // Create the isConnected listener
+    const isConnectedDeferred = new Deferred<boolean>();
+
+    // Build the handler itself
+    const handler = async (messageEvent: FrakLifecycleEvent) => {
+        if (!("iframeLifecycle" in messageEvent)) return;
+
+        const { iframeLifecycle: event, data } = messageEvent;
+
+        switch (event) {
+            // Resolve the isConnected promise
+            case "connected":
+                isConnectedDeferred.resolve(true);
+                break;
+            // Perform a frak backup
+            case "do-backup":
+                handleBackup(data.backup);
+                break;
+            // Remove frak backup
+            case "remove-backup":
+                localStorage.removeItem(BACKUP_KEY);
+                break;
+            // Change iframe visibility
+            case "show":
+            case "hide":
+                changeIframeVisibility({ iframe, isVisible: event === "show" });
+                break;
+            // Handshake handling
+            case "handshake":
+                handleHandshake(iframe, data.token, targetOrigin, configDomain);
+                break;
+            // Redirect handling
+            case "redirect":
+                handleRedirect(
+                    iframe,
+                    data.baseRedirectUrl,
+                    targetOrigin,
+                    data.mergeToken
+                );
+                break;
+        }
+    };
+
+    return {
+        handleEvent: handler,
+        isConnected: isConnectedDeferred.promise,
+    };
+}

package/src/constants/interactionTypes.ts

@@ -0,0 +1,15 @@
+/**
+ * The supported interaction type keys
+ *
+ * - `referral` - User arrived via a referral link
+ * - `create_referral_link` - User created/shared a referral link
+ * - `purchase` - User completed a purchase
+ * - `custom.${string}` - Custom interaction type defined per campaign
+ *
+ * @inline
+ */
+export type InteractionTypeKey =
+    | "referral"
+    | "create_referral_link"
+    | "purchase"
+    | `custom.${string}`;

package/src/constants/locales.ts

@@ -0,0 +1,14 @@
+/**
+ * The keys for each locales
+ * @inline
+ */
+export type LocalesKey = keyof typeof locales;
+
+/**
+ * Map the currency to the locale
+ */
+export const locales = {
+    eur: "fr-FR",
+    usd: "en-US",
+    gbp: "en-GB",
+} as const;

package/src/index.ts

@@ -0,0 +1,109 @@
+// Clients
+
+export { ssoPopupFeatures, ssoPopupName } from "./actions/openSso";
+export {
+    createIFrameFrakClient,
+    DebugInfoGatherer,
+    setupClient,
+} from "./clients";
+
+export type { InteractionTypeKey } from "./constants/interactionTypes";
+export { type LocalesKey, locales } from "./constants/locales";
+
+// Types
+export type {
+    ClientLifecycleEvent,
+    CompressedData,
+    Currency,
+    // RPC Embedded wallet
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    DisplayModalParamsType,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    EstimatedReward,
+    FinalActionType,
+    FinalModalStepType,
+    // Client
+    FrakClient,
+    // Utils
+    FrakContext,
+    FrakLifecycleEvent,
+    // Config
+    FrakWalletSdkConfig,
+    GetMerchantInformationReturnType,
+    HashProtectedData,
+    I18nConfig,
+    IFrameLifecycleEvent,
+    IFrameRpcSchema,
+    // Transport
+    IFrameTransport,
+    // Compression
+    KeyProvider,
+    Language,
+    LocalizedI18nConfig,
+    LoggedInEmbeddedView,
+    LoggedOutEmbeddedView,
+    LoginModalStepType,
+    ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    // RPC Modal types
+    ModalStepMetadata,
+    // RPC Modal generics
+    ModalStepTypes,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+    RewardTier,
+    // RPC Interaction
+    SendInteractionParamsType,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    SendTransactionTxType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
+    SsoMetadata,
+    TokenAmountType,
+    // Tracking
+    TrackArrivalParams,
+    TrackArrivalResult,
+    UtmParams,
+    // Rpc
+    WalletStatusReturnType,
+} from "./types";
+// Utils
+export {
+    type AppSpecificSsoMetadata,
+    base64urlDecode,
+    base64urlEncode,
+    baseIframeProps,
+    type CompressedSsoData,
+    clearMerchantIdCache,
+    compressJsonToB64,
+    createIframe,
+    DEEP_LINK_SCHEME,
+    type DeepLinkFallbackOptions,
+    decompressJsonFromB64,
+    FrakContextManager,
+    type FrakEvent,
+    type FullSsoParams,
+    fetchMerchantId,
+    findIframeInOpener,
+    formatAmount,
+    generateSsoUrl,
+    getBackendUrl,
+    getClientId,
+    getCurrencyAmountKey,
+    getSupportedCurrency,
+    getSupportedLocale,
+    isChromiumAndroid,
+    isFrakDeepLink,
+    resolveMerchantId,
+    toAndroidIntentUrl,
+    trackEvent,
+    triggerDeepLinkWithFallback,
+} from "./utils";
+export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/types/client.ts

@@ -0,0 +1,14 @@
+import type { OpenPanel } from "@openpanel/web";
+import type { FrakWalletSdkConfig } from "./config";
+import type { IFrameTransport } from "./transport";
+
+/**
+ * Representing a Frak client, used to interact with the Frak Wallet
+ */
+export type FrakClient = {
+    config: FrakWalletSdkConfig;
+    debugInfo: {
+        formatDebugInfo: (error: Error | unknown | string) => string;
+    };
+    openPanel?: OpenPanel;
+} & IFrameTransport;

package/src/types/compression.ts

@@ -0,0 +1,22 @@
+/**
+ * The received encoded data from a client
+ *  -> The encoded should contain a HashProtectedData once decoded
+ *  @ignore
+ */
+export type CompressedData = Uint8Array;
+
+/**
+ * The encoded data to send to a client / received by a client
+ *  @ignore
+ */
+export type HashProtectedData<DataType> = Readonly<
+    DataType & {
+        validationHash: string;
+    }
+>;
+
+/**
+ * Represent a key provider used for the hashed and secure compression
+ *  @ignore
+ */
+export type KeyProvider<DataType> = (value: DataType) => string[];

package/src/types/config.ts

@@ -0,0 +1,117 @@
+/**
+ * All the currencies available
+ * @category Config
+ */
+export type Currency = "eur" | "usd" | "gbp";
+
+/**
+ * All the languages available
+ * @category Config
+ */
+export type Language = "fr" | "en";
+
+/**
+ * Configuration for the Frak Wallet SDK
+ * @category Config
+ */
+export type FrakWalletSdkConfig = {
+    /**
+     * The Frak wallet url
+     * @defaultValue "https://wallet.frak.id"
+     */
+    walletUrl?: string;
+    /**
+     * Some metadata about your implementation of the Frak SDK
+     */
+    metadata: {
+        /**
+         * Your application name (will be displayed in a few modals and in SSO)
+         */
+        name: string;
+        /**
+         * Your merchant ID from the Frak dashboard (UUID format)
+         * Used for referral tracking and analytics
+         * If not provided, will be auto-fetched from the backend using your domain
+         */
+        merchantId?: string;
+        /**
+         * Language to display in the modal
+         * If undefined, will default to the browser language
+         */
+        lang?: Language;
+        /**
+         * The currency to display in the modal
+         * @defaultValue `"eur"`
+         */
+        currency?: Currency;
+        /**
+         * The logo URL that will be displayed in a few components
+         */
+        logoUrl?: string;
+        /**
+         * The homepage link that could be displayed in a few components
+         */
+        homepageLink?: string;
+    };
+    /**
+     * Some customization for the modal
+     */
+    customizations?: {
+        /**
+         * Custom CSS styles to apply to the modals and components
+         */
+        css?: `${string}.css`;
+        /**
+         * Custom i18n configuration for the modal
+         */
+        i18n?: I18nConfig;
+    };
+    /**
+     * The domain name of your application
+     * @defaultValue window.location.host
+     */
+    domain?: string;
+};
+
+/**
+ * Custom i18n configuration for the modal
+ *  See [i18next json format](https://www.i18next.com/misc/json-format#i18next-json-v4)
+ *
+ * Available variables
+ *  - `{{ productName }}` : The name of your website (`metadata.name`)
+ *  - `{{ productOrigin }}` : The origin url of your website
+ *  - `{{ estimatedReward }}` : The estimated reward for the user (based on the specific `targetInteraction` you can specify, or the max referrer reward if no target interaction is specified)
+ *
+ * Context of the translation [see i18n context](https://www.i18next.com/translation-function/context)
+ *  - For modal display, the key of the final action (`sharing`, `reward`, or undefined)
+ *  - For embedded wallet display, the key of the logged in action (`sharing` or undefined)
+ *
+ * @example
+ * ```ts
+ * // Multi language config
+ * const multiI18n = {
+ *  fr: {
+ *      "sdk.modal.title": "Titre de modal",
+ *      "sdk.modal.description": "Description de modal, avec {{ estimatedReward }} de gains possible",
+ *  },
+ *  en: "https://example.com/en.json"
+ * }
+ *
+ * // Single language config
+ * const singleI18n = {
+ *      "sdk.modal.title": "Modal title",
+ *      "sdk.modal.description": "Modal description, with {{ estimatedReward }} of gains possible",
+ * }
+ * ```
+ *
+ * @category Config
+ */
+export type I18nConfig =
+    | Record<Language, LocalizedI18nConfig>
+    | LocalizedI18nConfig;
+
+/**
+ * A localized i18n config
+ * @category Config
+ */
+export type LocalizedI18nConfig = `${string}.css` | { [key: string]: string };

package/src/types/context.ts

@@ -0,0 +1,13 @@
+import type { Address } from "viem";
+
+/**
+ * The current Frak Context
+ *
+ * For now, only contain a referrer address.
+ *
+ * @ignore
+ */
+export type FrakContext = {
+    // Referrer address
+    r: Address;
+};

package/src/types/index.ts

@@ -0,0 +1,74 @@
+// Rpc related
+
+// Client related
+export type { FrakClient } from "./client";
+export type {
+    CompressedData,
+    HashProtectedData,
+    KeyProvider,
+} from "./compression";
+export type {
+    Currency,
+    FrakWalletSdkConfig,
+    I18nConfig,
+    Language,
+    LocalizedI18nConfig,
+} from "./config";
+// Utils
+export type { FrakContext } from "./context";
+
+export type {
+    ClientLifecycleEvent,
+    IFrameLifecycleEvent,
+} from "./lifecycle";
+export type { IFrameRpcSchema } from "./rpc";
+// Modal related
+export type {
+    DisplayModalParamsType,
+    ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
+} from "./rpc/displayModal";
+export type {
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    LoggedInEmbeddedView,
+    LoggedOutEmbeddedView,
+} from "./rpc/embedded";
+export type { SendInteractionParamsType } from "./rpc/interaction";
+export type {
+    EstimatedReward,
+    GetMerchantInformationReturnType,
+    RewardTier,
+    TokenAmountType,
+} from "./rpc/merchantInformation";
+export type {
+    FinalActionType,
+    FinalModalStepType,
+    LoginModalStepType,
+    ModalStepMetadata,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    SendTransactionTxType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
+} from "./rpc/modal";
+export type {
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+    SsoMetadata,
+} from "./rpc/sso";
+export type { WalletStatusReturnType } from "./rpc/walletStatus";
+// Tracking
+export type {
+    TrackArrivalParams,
+    TrackArrivalResult,
+    UtmParams,
+} from "./tracking";
+export type { FrakLifecycleEvent, IFrameTransport } from "./transport";

package/src/types/lifecycle/client.ts

@@ -0,0 +1,69 @@
+import type { I18nConfig } from "../config";
+
+/**
+ * Event related to the iframe lifecycle
+ * @ignore
+ */
+export type ClientLifecycleEvent =
+    | CustomCssEvent
+    | CustomI18nEvent
+    | RestoreBackupEvent
+    | HearbeatEvent
+    | HandshakeResponse
+    | SsoRedirectCompleteEvent
+    | DeepLinkFailedEvent;
+
+type CustomCssEvent = {
+    clientLifecycle: "modal-css";
+    data: { cssLink: string };
+};
+
+type CustomI18nEvent = {
+    clientLifecycle: "modal-i18n";
+    data: { i18n: I18nConfig };
+};
+
+type RestoreBackupEvent = {
+    clientLifecycle: "restore-backup";
+    data: { backup: string };
+};
+
+type HearbeatEvent = {
+    clientLifecycle: "heartbeat";
+    data?: never;
+};
+
+type HandshakeResponse = {
+    clientLifecycle: "handshake-response";
+    data: {
+        token: string;
+        currentUrl: string;
+        /**
+         * Pending merge token extracted from URL (?fmt= parameter)
+         * When present, listener should execute identity merge in background
+         * URL is cleaned after handshake response is sent
+         */
+        pendingMergeToken?: string;
+        /**
+         * Client ID for identity tracking (belt & suspenders fallback)
+         * Primary delivery is via iframe URL query param; handshake is backup for SSR
+         */
+        clientId?: string;
+        /**
+         * Explicit domain from SDK config (FrakWalletSdkConfig.domain)
+         * When present, listener should prefer this over URL-derived domain
+         * for merchant resolution (handles proxied/tunneled environments)
+         */
+        configDomain?: string;
+    };
+};
+
+type SsoRedirectCompleteEvent = {
+    clientLifecycle: "sso-redirect-complete";
+    data: { compressed: string };
+};
+
+type DeepLinkFailedEvent = {
+    clientLifecycle: "deep-link-failed";
+    data: { originalUrl: string };
+};