@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.10dada3f

package/src/types/lifecycle/iframe.ts

@@ -8,7 +8,6 @@ export type IFrameLifecycleEvent =
           data?: never;
       }
     | DoBackupEvent
-    | HandshakeRequestEvent
     | RedirectRequestEvent;
 
 type DoBackupEvent = {
@@ -16,13 +15,6 @@ type DoBackupEvent = {
     data: { backup?: string };
 };
 
-type HandshakeRequestEvent = {
-    iframeLifecycle: "handshake";
-    data: {
-        token: string;
-    };
-};
-
 type RedirectRequestEvent = {
     iframeLifecycle: "redirect";
     data: {
@@ -37,5 +29,12 @@ type RedirectRequestEvent = {
          * Used when redirecting out of social browsers to preserve identity across contexts
          */
         mergeToken?: string;
+        /**
+         * When true, open the URL in a new tab via window.open(_blank)
+         * instead of navigating the current page.
+         * Requires the postMessage to include user activation delegation
+         * (includeUserActivation: true) so Safari allows the popup.
+         */
+        openInNewTab?: boolean;
     };
 };

package/src/types/resolvedConfig.ts

@@ -0,0 +1,138 @@
+import type { Currency, Language } from "./config";
+import type { AttributionDefaults } from "./tracking";
+
+/**
+ * Response from the merchant resolve endpoint
+ * @category Config
+ */
+export type MerchantConfigResponse = {
+    merchantId: string;
+    name: string;
+    domain: string;
+    allowedDomains: string[];
+    sdkConfig?: ResolvedSdkConfig;
+};
+
+/**
+ * Resolved placement config from backend
+ * Translations already flattened: default + lang-specific merged into one record
+ * @category Config
+ */
+export type ResolvedPlacement = {
+    /** Per-component configuration within this placement */
+    components?: {
+        buttonShare?: {
+            text?: string;
+            noRewardText?: string;
+            clickAction?: "embedded-wallet" | "share-modal" | "sharing-page";
+            useReward?: boolean;
+            css?: string;
+        };
+        buttonWallet?: {
+            position?: "right" | "left";
+            css?: string;
+        };
+        openInApp?: {
+            text?: string;
+            css?: string;
+        };
+        postPurchase?: {
+            badgeText?: string;
+            refereeText?: string;
+            refereeNoRewardText?: string;
+            referrerText?: string;
+            referrerNoRewardText?: string;
+            ctaText?: string;
+            ctaNoRewardText?: string;
+            css?: string;
+        };
+        banner?: {
+            referralTitle?: string;
+            referralDescription?: string;
+            referralCta?: string;
+            inappTitle?: string;
+            inappDescription?: string;
+            inappCta?: string;
+            css?: string;
+        };
+    };
+    targetInteraction?: string;
+    /** Already flattened: default + lang-specific merged into one record */
+    translations?: Record<string, string>;
+    /** Global placement CSS (applied to modals/listener) */
+    css?: string;
+};
+
+/**
+ * Resolved SDK config from backend `/resolve` endpoint
+ * Language resolution and translation merging already applied
+ * @category Config
+ */
+export type ResolvedSdkConfig = {
+    name?: string;
+    logoUrl?: string;
+    homepageLink?: string;
+    currency?: Currency;
+    lang?: Language;
+    /** When true, all SDK components should be hidden */
+    hidden?: boolean;
+    css?: string;
+    translations?: Record<string, string>;
+    placements?: Record<string, ResolvedPlacement>;
+    /** Global component defaults (used when no placement override exists) */
+    components?: ResolvedPlacement["components"];
+    /**
+     * Default attribution params applied when building outbound sharing URLs.
+     * Per-call overrides win over these backend defaults; `utm_content` is
+     * intentionally excluded (per-content/per-product, never a merchant default).
+     */
+    attribution?: AttributionDefaults;
+};
+
+/**
+ * Internal SDK config store state
+ * Merged config: backend > SDK static > defaults
+ * Components subscribe to this reactively
+ * @category Config
+ */
+export type SdkResolvedConfig = {
+    /** Whether the backend config has been resolved */
+    isResolved: boolean;
+
+    /** Merchant ID from resolution */
+    merchantId: string;
+
+    /** Domain returned by the resolve endpoint */
+    domain?: string;
+
+    /** Domains allowed for this merchant (used by iframe trust check) */
+    allowedDomains?: string[];
+
+    /** Whether the resolve returned a backend sdkConfig object */
+    hasRawSdkConfig?: boolean;
+
+    /** Merged metadata fields */
+    name?: string;
+    logoUrl?: string;
+    homepageLink?: string;
+    lang?: Language;
+    currency?: Currency;
+
+    /** When true, all SDK components should be hidden */
+    hidden?: boolean;
+
+    /** Global CSS from backend config (passed to iframe) */
+    css?: string;
+
+    /** Global translations (for reference / component fallback) */
+    translations?: Record<string, string>;
+
+    /** Named placements (keyed by placement ID) */
+    placements?: Record<string, ResolvedPlacement>;
+
+    /** Global component defaults (fallback for placement-level overrides) */
+    components?: ResolvedPlacement["components"];
+
+    /** Merged attribution defaults: backend > SDK static config */
+    attribution?: AttributionDefaults;
+};

package/src/types/rpc/displaySharingPage.ts

@@ -0,0 +1,100 @@
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+import type { I18nConfig } from "../config";
+import type { AttributionParams } from "../tracking";
+
+/**
+ * Product information to display on the sharing page
+ * @group Sharing Page
+ */
+export type SharingPageProduct = {
+    /**
+     * The product title / name
+     */
+    title: string;
+    /**
+     * Optional product image URL
+     */
+    imageUrl?: string;
+    /**
+     * Optional product-specific sharing link
+     * When provided and the product is selected, this link is used instead of the default sharing link
+     */
+    link?: string;
+    /**
+     * Optional `utm_content` value to apply when this product is selected.
+     * Falls back to the page-level `attribution.utmContent` when omitted.
+     */
+    utmContent?: string;
+};
+
+/**
+ * Parameters to display the sharing page
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+export type DisplaySharingPageParamsType = {
+    /**
+     * Products to showcase on the sharing page
+     * If provided, they will be displayed in a product card section
+     */
+    products?: SharingPageProduct[];
+    /**
+     * Optional link override for sharing
+     * If not provided, the sharing link will be generated from the current page URL + merchant context
+     */
+    link?: string;
+    /**
+     * Optional attribution overrides for the outbound sharing URL.
+     *
+     * When provided (even as an empty object), Frak adds standard affiliation
+     * params (`utm_source=frak`, `utm_medium=referral`, `utm_campaign=<merchantId>`,
+     * `ref=<clientId>`, `via=frak`) alongside `fCtx`. Existing UTMs on the base
+     * URL are preserved (gap-fill). Set this to `null` to disable attribution
+     * params entirely (only `fCtx` is added).
+     *
+     * @default {} — defaults applied
+     */
+    attribution?: AttributionParams | null;
+    /**
+     * Optional metadata overrides for the sharing page
+     */
+    metadata?: {
+        /**
+         * Logo override for the sharing page header
+         */
+        logo?: string;
+        /**
+         * Link to the homepage of the calling website
+         */
+        homepageLink?: string;
+        /**
+         * The target interaction behind this sharing page
+         */
+        targetInteraction?: InteractionTypeKey;
+        /**
+         * i18n overrides for the sharing page
+         */
+        i18n?: I18nConfig;
+    };
+};
+
+/**
+ * Result of the sharing page display
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+export type DisplaySharingPageResultType = {
+    /**
+     * The action the user took
+     * - "shared": User used the native share dialog
+     * - "copied": User copied the link to clipboard
+     * - "dismissed": User dismissed the sharing page without acting
+     */
+    action: "shared" | "copied" | "dismissed";
+    /**
+     * The install URL for the Frak app
+     * Can be used as a fallback to redirect the user to the install page
+     * from the merchant's top-level page (e.g. via `window.location.href`)
+     */
+    installUrl?: string;
+};

package/src/types/rpc/embedded/index.ts

@@ -9,10 +9,10 @@ import type {
 import type { LoggedOutEmbeddedView } from "./loggedOut";
 
 export type {
+    EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
-    EmbeddedViewActionReferred,
 };
 
 /**

package/src/types/rpc/interaction.ts

@@ -26,6 +26,10 @@ export type SendInteractionParamsType =
       }
     | {
           type: "sharing";
+          /** Epoch seconds timestamp matching the V2 context `t` field embedded in the referral link URL, used for backend correlation */
+          sharingTimestamp?: number;
+          /** Merchant order ID linking this sharing event to a purchase (stays server-side, never in URL) */
+          purchaseId?: string;
       }
     | {
           type: "custom";

package/src/types/rpc/userReferralStatus.ts

@@ -0,0 +1,20 @@
+/**
+ * User referral status returned by `frak_getUserReferralStatus`.
+ *
+ * Generic referral context for the current user on a merchant.
+ * Used by components like `<frak-post-purchase>` and `<frak-referred-banner>`
+ * to adapt their display based on the user's referral relationship.
+ *
+ * Returns `null` when the user's identity cannot be resolved
+ * (e.g. no clientId and no wallet session).
+ *
+ * @group RPC Schema
+ */
+export type UserReferralStatusType = {
+    /**
+     * Whether the user was referred to this merchant by someone else.
+     *
+     * `true` means a referral link exists where this user is the referee.
+     */
+    isReferred: boolean;
+};

package/src/types/rpc.ts

@@ -4,6 +4,10 @@ import type {
     ModalRpcStepsInput,
     ModalRpcStepsResultType,
 } from "./rpc/displayModal";
+import type {
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
+} from "./rpc/displaySharingPage";
 import type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
@@ -16,6 +20,7 @@ import type {
     PrepareSsoParamsType,
     PrepareSsoReturnType,
 } from "./rpc/sso";
+import type { UserReferralStatusType } from "./rpc/userReferralStatus";
 import type { WalletStatusReturnType } from "./rpc/walletStatus";
 
 /**
@@ -38,7 +43,7 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  *  - Response Type: stream (emits updates when wallet status changes)
  *
  * #### frak_displayModal
- * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
  * - Returns: {@link ModalRpcStepsResultType}
  * - Response Type: promise (one-shot)
  *
@@ -53,9 +58,14 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  *  - Response Type: promise (one-shot)
  *
  * #### frak_displayEmbeddedWallet
- * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
  * - Returns: {@link DisplayEmbeddedWalletResultType}
  * - Response Type: promise (one-shot)
+ *
+ * #### frak_displaySharingPage
+ * - Params: [request: {@link DisplaySharingPageParamsType}, configMetadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
+ * - Returns: {@link DisplaySharingPageResultType}
+ * - Response Type: promise (one-shot)
  */
 export type IFrameRpcSchema = [
     /**
@@ -77,6 +87,7 @@ export type IFrameRpcSchema = [
             requests: ModalRpcStepsInput,
             metadata: ModalRpcMetadata | undefined,
             configMetadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: ModalRpcStepsResultType;
     },
@@ -89,7 +100,7 @@ export type IFrameRpcSchema = [
         Method: "frak_prepareSso";
         Parameters: [
             params: PrepareSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: PrepareSsoReturnType;
@@ -104,7 +115,7 @@ export type IFrameRpcSchema = [
         Method: "frak_openSso";
         Parameters: [
             params: OpenSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: OpenSsoReturnType;
@@ -130,6 +141,7 @@ export type IFrameRpcSchema = [
         Parameters: [
             request: DisplayEmbeddedWalletParamsType,
             metadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: DisplayEmbeddedWalletResultType;
     },
@@ -137,7 +149,7 @@ export type IFrameRpcSchema = [
      * Method to send interactions (arrival, sharing, custom events)
      * Fire-and-forget method - no return value expected
      * merchantId is resolved from context
-     * clientId is passed via metadata as safeguard against handshake race condition
+     * clientId is passed via metadata as safeguard against race conditions
      */
     {
         Method: "frak_sendInteraction";
@@ -147,4 +159,41 @@ export type IFrameRpcSchema = [
         ];
         ReturnType: undefined;
     },
+    /**
+     * Method to get the current user's referral status on this merchant.
+     * Returns whether the user was referred (has a referral link as referee).
+     * Returns null when the user's identity cannot be resolved.
+     * This is a one-shot request.
+     */
+    {
+        Method: "frak_getUserReferralStatus";
+        Parameters?: undefined;
+        ReturnType: UserReferralStatusType | null;
+    },
+    /**
+     * Method to display a sharing page with product info and sharing buttons
+     * Resolves on first user action (share/copy) but the page stays visible
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_displaySharingPage";
+        Parameters: [
+            request: DisplaySharingPageParamsType,
+            configMetadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
+        ];
+        ReturnType: DisplaySharingPageResultType;
+    },
+    /**
+     * Method to get a merge token for the current anonymous identity.
+     * Used by in-app browser redirect flows to preserve identity
+     * when switching from a WebView to the system browser.
+     * Returns the merge token string, or null if unavailable.
+     * This is a one-shot request.
+     */
+    {
+        Method: "frak_getMergeToken";
+        Parameters?: undefined;
+        ReturnType: string | null;
+    },
 ];

package/src/types/tracking.ts

@@ -8,6 +8,42 @@ export type UtmParams = {
     content?: string;
 };
 
+/**
+ * Attribution parameters appended to outbound sharing URLs.
+ *
+ * Defaults are derived from the V2 Frak context when available:
+ * - `utmSource`: `"frak"`
+ * - `utmMedium`: `"referral"`
+ * - `utmCampaign`: merchantId (`context.m`)
+ * - `via`: `"frak"`
+ * - `ref`: clientId (`context.c`)
+ *
+ * Fields explicitly set here override the defaults. Existing params on the
+ * base URL are preserved (gap-fill policy) to respect merchant-provided UTMs.
+ */
+export type AttributionParams = {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmContent?: string;
+    utmTerm?: string;
+    via?: string;
+    ref?: string;
+};
+
+/**
+ * Merchant-level attribution defaults.
+ *
+ * Same shape as {@link AttributionParams} minus `utmContent`, because
+ * `utm_content` describes the specific content/creative being shared and is
+ * inherently per-call or per-product (never a merchant-wide default).
+ *
+ * Used as the shape for both:
+ * - `FrakWalletSdkConfig.attribution` (SDK-side compile-time defaults)
+ * - Backend merchant-config attribution (dashboard-driven defaults)
+ */
+export type AttributionDefaults = Omit<AttributionParams, "utmContent">;
+
 export type TrackArrivalParams = {
     /** @deprecated V1 legacy — use referrerClientId for v2 contexts */
     referrerWallet?: Address;

package/src/utils/FrakContext.test.ts

@@ -42,7 +42,7 @@ describe("FrakContextManager", () => {
                 expect(result).not.toMatch(/[+/=]/);
             });
 
-            it("should return undefined when v2 context is missing clientId", () => {
+            it("should return undefined when v2 context has neither clientId nor wallet", () => {
                 const partial = { v: 2 as const, m: "m", t: 123 };
                 const result = FrakContextManager.compress(
                     partial as FrakContextV2
@@ -50,6 +50,33 @@ describe("FrakContextManager", () => {
                 expect(result).toBeUndefined();
             });
 
+            it("should compress v2 context with wallet only (no clientId)", () => {
+                const v2WithWalletOnly: FrakContextV2 = {
+                    v: 2,
+                    m: "merchant-uuid-1234",
+                    t: 1709654400,
+                    w: "0x1234567890123456789012345678901234567890" as Address,
+                };
+                const result = FrakContextManager.compress(v2WithWalletOnly);
+                expect(result).toBeDefined();
+                const decompressed = FrakContextManager.decompress(result);
+                expect(decompressed).toEqual(v2WithWalletOnly);
+            });
+
+            it("should compress v2 context with both clientId and wallet", () => {
+                const v2Hybrid: FrakContextV2 = {
+                    v: 2,
+                    c: "test-client-id-uuid",
+                    m: "merchant-uuid-1234",
+                    t: 1709654400,
+                    w: "0x1234567890123456789012345678901234567890" as Address,
+                };
+                const result = FrakContextManager.compress(v2Hybrid);
+                expect(result).toBeDefined();
+                const decompressed = FrakContextManager.decompress(result);
+                expect(decompressed).toEqual(v2Hybrid);
+            });
+
             it("should return undefined when v2 context is missing merchantId", () => {
                 const partial = { v: 2 as const, c: "c", t: 123 };
                 const result = FrakContextManager.compress(
@@ -121,6 +148,157 @@ describe("FrakContextManager", () => {
                 expect(result).toContain("baz=qux");
                 expect(result).toContain("fCtx=");
             });
+
+            describe("update with attribution", () => {
+                const url = "https://example.com/product";
+
+                it("should apply default attribution params when attribution is omitted", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                    });
+
+                    expect(result).toBeDefined();
+                    expect(result).toContain("fCtx=");
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        v2Context.m
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                });
+
+                it("should apply default attribution params when attribution is an empty object", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: {},
+                    });
+
+                    expect(result).toBeDefined();
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        v2Context.m
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                    expect(
+                        parsedUrl.searchParams.get("utm_content")
+                    ).toBeNull();
+                    expect(parsedUrl.searchParams.get("utm_term")).toBeNull();
+                });
+
+                it("should honor overrides over defaults", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: {
+                            utmSource: "newsletter",
+                            utmMedium: "email",
+                            utmCampaign: "spring-sale",
+                            utmContent: "hero-banner",
+                            utmTerm: "wallet",
+                            via: "partner",
+                            ref: "alice",
+                        },
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "newsletter"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "email"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        "spring-sale"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_content")).toBe(
+                        "hero-banner"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_term")).toBe(
+                        "wallet"
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("partner");
+                    expect(parsedUrl.searchParams.get("ref")).toBe("alice");
+                });
+
+                it("should preserve merchant-provided UTMs on the base URL (gap-fill)", () => {
+                    const baseUrl =
+                        "https://example.com/product?utm_source=google&utm_campaign=merchant-spring";
+                    const result = FrakContextManager.update({
+                        url: baseUrl,
+                        context: v2Context,
+                        attribution: {},
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    // Merchant-provided values preserved
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "google"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        "merchant-spring"
+                    );
+                    // Missing ones filled by Frak defaults
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                });
+
+                it("should skip fields with empty-string overrides", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: { utmContent: "", utmTerm: "" },
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.has("utm_content")).toBe(
+                        false
+                    );
+                    expect(parsedUrl.searchParams.has("utm_term")).toBe(false);
+                });
+
+                it("should skip context-derived defaults for V1 (no merchantId/clientId)", () => {
+                    const v1Context: FrakContextV1 = {
+                        r: "0x1234567890123456789012345678901234567890" as Address,
+                    };
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v1Context,
+                        attribution: {},
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    // Static defaults still applied
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    // No derivable values from V1
+                    expect(parsedUrl.searchParams.has("utm_campaign")).toBe(
+                        false
+                    );
+                    expect(parsedUrl.searchParams.has("ref")).toBe(false);
+                });
+            });
         });
     });