@frak-labs/core-sdk 0.1.0-beta.6e0d8026 → 0.1.0-beta.8d103039

package/src/utils/iframeHelper.ts

@@ -0,0 +1,142 @@
+import type { FrakWalletSdkConfig } from "../types";
+
+/**
+ * Base props for the iframe
+ * @ignore
+ */
+export const baseIframeProps = {
+    id: "frak-wallet",
+    name: "frak-wallet",
+    title: "Frak Wallet",
+    allow: "publickey-credentials-get *; clipboard-write; web-share *",
+    style: {
+        width: "0",
+        height: "0",
+        border: "0",
+        position: "absolute",
+        zIndex: 2000001,
+        top: "-1000px",
+        left: "-1000px",
+        colorScheme: "auto",
+    },
+};
+
+/**
+ * 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`.
+ */
+export function createIframe({
+    walletBaseUrl,
+    config,
+}: { walletBaseUrl?: string; config?: FrakWalletSdkConfig }): Promise<
+    HTMLIFrameElement | undefined
+> {
+    // Check if the iframe is already created
+    const alreadyCreatedIFrame = document.querySelector("#frak-wallet");
+
+    // If the iframe is already created, remove it
+    if (alreadyCreatedIFrame) {
+        alreadyCreatedIFrame.remove();
+    }
+
+    const iframe = document.createElement("iframe");
+
+    // Set the base iframe props
+    iframe.id = baseIframeProps.id;
+    iframe.name = baseIframeProps.name;
+    iframe.allow = baseIframeProps.allow;
+    iframe.style.zIndex = baseIframeProps.style.zIndex.toString();
+
+    changeIframeVisibility({ iframe, isVisible: false });
+    document.body.appendChild(iframe);
+
+    return new Promise((resolve) => {
+        iframe?.addEventListener("load", () => resolve(iframe));
+        iframe.src = `${config?.walletUrl ?? walletBaseUrl ?? "https://wallet.frak.id"}/listener`;
+    });
+}
+/**
+ * Change the visibility of the given iframe
+ * @ignore
+ */
+export function changeIframeVisibility({
+    iframe,
+    isVisible,
+}: {
+    iframe: HTMLIFrameElement;
+    isVisible: boolean;
+}) {
+    if (!isVisible) {
+        iframe.style.width = "0";
+        iframe.style.height = "0";
+        iframe.style.border = "0";
+        iframe.style.position = "fixed";
+        iframe.style.top = "-1000px";
+        iframe.style.left = "-1000px";
+        return;
+    }
+
+    iframe.style.position = "fixed";
+    iframe.style.top = "0";
+    iframe.style.left = "0";
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    iframe.style.pointerEvents = "auto";
+}
+
+/**
+ * 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");
+ * ```
+ */
+export function findIframeInOpener(pathname = "/listener"): Window | null {
+    if (!window.opener) return null;
+
+    const frameCheck = (frame: Window) => {
+        try {
+            return (
+                frame.location.origin === window.location.origin &&
+                frame.location.pathname === pathname
+            );
+        } catch {
+            // Cross-origin frame, skip
+            return false;
+        }
+    };
+
+    // Check if the openner window is the right one
+    if (frameCheck(window.opener)) return window.opener;
+
+    // Search through frames in window.opener
+    try {
+        const frames = window.opener.frames;
+        for (let i = 0; i < frames.length; i++) {
+            if (frameCheck(frames[i])) {
+                return frames[i];
+            }
+        }
+        return null;
+    } catch (error) {
+        console.error(
+            `[findIframeInOpener] Error finding iframe with pathname ${pathname}:`,
+            error
+        );
+        return null;
+    }
+}

package/src/utils/index.ts

@@ -0,0 +1,21 @@
+export {
+    createIframe,
+    baseIframeProps,
+    findIframeInOpener,
+} from "./iframeHelper";
+export { compressJsonToB64 } from "./compression/compress";
+export { decompressJsonFromB64 } from "./compression/decompress";
+export { base64urlDecode, base64urlEncode } from "./compression/b64";
+export { FrakContextManager } from "./FrakContext";
+export { getSupportedCurrency } from "./getSupportedCurrency";
+export { getSupportedLocale } from "./getSupportedLocale";
+export { getCurrencyAmountKey } from "./getCurrencyAmountKey";
+export { formatAmount } from "./formatAmount";
+export { trackEvent } from "./trackEvent";
+export { Deferred } from "@frak-labs/frame-connector";
+export {
+    generateSsoUrl,
+    type CompressedSsoData,
+    type FullSsoParams,
+    type AppSpecificSsoMetadata,
+} from "./sso";

package/src/utils/sso.ts

@@ -0,0 +1,119 @@
+import type { Hex } from "viem";
+import type { PrepareSsoParamsType, SsoMetadata } from "../types";
+import { compressJsonToB64 } from "./compression/compress";
+
+export type AppSpecificSsoMetadata = SsoMetadata & {
+    name: string;
+    css?: string;
+};
+
+/**
+ * The full SSO params that will be used for compression
+ */
+export type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
+    metadata: AppSpecificSsoMetadata;
+    productId: Hex;
+};
+
+/**
+ * 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 productId - Product identifier
+ * @param name - Application name
+ * @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>
+ * ```
+ */
+export function generateSsoUrl(
+    walletUrl: string,
+    params: PrepareSsoParamsType,
+    productId: Hex,
+    name: string,
+    css?: string
+): string {
+    // Build full params with app-specific metadata
+    const fullParams: FullSsoParams = {
+        redirectUrl: params.redirectUrl,
+        directExit: params.directExit,
+        lang: params.lang,
+        productId,
+        metadata: {
+            name,
+            css,
+            logoUrl: params.metadata?.logoUrl,
+            homepageLink: params.metadata?.homepageLink,
+        },
+    };
+
+    // Compress params to minimal format
+    const compressedParam = ssoParamsToCompressed(fullParams);
+
+    // Encode to base64url
+    const compressedString = compressJsonToB64(compressedParam);
+
+    // Build URL matching wallet's expected format: /sso?p=<compressed>
+    const ssoUrl = new URL(walletUrl);
+    ssoUrl.pathname = "/sso";
+    ssoUrl.searchParams.set("p", compressedString);
+
+    return ssoUrl.toString();
+}
+
+/**
+ * Map full sso params to compressed sso params
+ * @param params
+ */
+function ssoParamsToCompressed(params: FullSsoParams) {
+    return {
+        r: params.redirectUrl,
+        d: params.directExit,
+        l: params.lang,
+        p: params.productId,
+        m: {
+            n: params.metadata?.name,
+            css: params.metadata?.css,
+            l: params.metadata?.logoUrl,
+            h: params.metadata?.homepageLink,
+        },
+    };
+}
+
+/**
+ * Type of compressed the sso data
+ */
+export type CompressedSsoData = {
+    // Potential id from backend
+    id?: Hex;
+    // redirect url
+    r?: string;
+    // direct exit
+    d?: boolean;
+    // language
+    l?: "en" | "fr";
+    // product id
+    p: Hex;
+    // metadata
+    m: {
+        // product name
+        n: string;
+        // custom css
+        css?: string;
+        // logo
+        l?: string;
+        // home page link
+        h?: string;
+    };
+};

package/src/utils/ssoUrlListener.ts

@@ -0,0 +1,60 @@
+import type { RpcClient } from "@frak-labs/frame-connector";
+import type { FrakLifecycleEvent } from "../types";
+import type { IFrameRpcSchema } from "../types/rpc";
+
+/**
+ * Listen for SSO redirect with compressed data in URL
+ * Forwards compressed data to iframe via lifecycle event
+ * Cleans URL immediately after detection
+ *
+ * Performance: One-shot URL check, no polling, no re-renders
+ *
+ * @param rpcClient - RPC client instance to send lifecycle events
+ * @param waitForConnection - Promise that resolves when iframe is connected
+ */
+export function setupSsoUrlListener(
+    rpcClient: RpcClient<IFrameRpcSchema, FrakLifecycleEvent>,
+    waitForConnection: Promise<boolean>
+): void {
+    if (typeof window === "undefined") {
+        return;
+    }
+
+    // One-shot URL check - no need for MutationObserver or polling
+    const url = new URL(window.location.href);
+    const compressedSso = url.searchParams.get("sso");
+
+    // Early return if no SSO parameter
+    if (!compressedSso) {
+        return;
+    }
+
+    // Forward compressed data directly to iframe (no decompression on SDK side)
+    // Iframe will decompress and process
+    waitForConnection
+        .then(() => {
+            // Send lifecycle event with compressed string
+            // This is a one-way notification, no response expected
+            rpcClient.sendLifecycle({
+                clientLifecycle: "sso-redirect-complete",
+                data: { compressed: compressedSso },
+            });
+
+            console.log(
+                "[SSO URL Listener] Forwarded compressed SSO data to iframe"
+            );
+        })
+        .catch((error) => {
+            console.error(
+                "[SSO URL Listener] Failed to forward SSO data:",
+                error
+            );
+        });
+
+    // Clean URL immediately to prevent exposure in browser history
+    // Use replaceState to avoid navigation/re-render
+    url.searchParams.delete("sso");
+    window.history.replaceState({}, "", url.toString());
+
+    console.log("[SSO URL Listener] SSO parameter detected and URL cleaned");
+}

package/src/utils/trackEvent.ts

@@ -0,0 +1,26 @@
+import type { FrakClient } from "../types";
+
+export type FrakEvent =
+    | "share_button_clicked"
+    | "wallet_button_clicked"
+    | "share_modal_error"
+    | "user_referred";
+
+type EventProps = Record<string, unknown>;
+
+export function trackEvent(
+    client: FrakClient | undefined,
+    event: FrakEvent,
+    props: EventProps = {}
+): void {
+    if (!client) {
+        console.debug("[Frak] No client provided, skipping event tracking");
+        return;
+    }
+
+    try {
+        client.openPanel?.track(event, props);
+    } catch (e) {
+        console.debug("[Frak] Failed to track event:", event, e);
+    }
+}