@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.0cd79998

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

@@ -121,6 +121,150 @@ describe("FrakContextManager", () => {
                 expect(result).toContain("baz=qux");
                 expect(result).toContain("fCtx=");
             });
+
+            describe("update with attribution", () => {
+                const url = "https://example.com/product";
+
+                it("should not add attribution params when attribution is omitted", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                    });
+
+                    expect(result).toBeDefined();
+                    expect(result).toContain("fCtx=");
+                    expect(result).not.toContain("utm_source");
+                    expect(result).not.toContain("utm_medium");
+                    expect(result).not.toContain("utm_campaign");
+                    expect(result).not.toContain("ref=");
+                    expect(result).not.toContain("via=");
+                });
+
+                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);
+                });
+            });
         });
     });
 

package/src/utils/FrakContext.ts

@@ -1,5 +1,10 @@
 import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
-import type { FrakContext, FrakContextV1, FrakContextV2 } from "../types";
+import type {
+    AttributionParams,
+    FrakContext,
+    FrakContextV1,
+    FrakContextV2,
+} from "../types";
 import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "./compression/b64";
 import { compressJsonToB64 } from "./compression/compress";
@@ -91,20 +96,80 @@ function parse({ url }: { url: string }): FrakContext | null | undefined {
     return decompress(frakContext);
 }
 
+/**
+ * Default UTM medium value when attribution is requested.
+ */
+const DEFAULT_UTM_MEDIUM = "referral";
+
+/**
+ * Default utm_source / via value when attribution is requested.
+ */
+const DEFAULT_ATTRIBUTION_SOURCE = "frak";
+
+/**
+ * Resolve attribution defaults from the provided context.
+ *
+ * V2 contexts expose the merchantId (`m`) and clientId (`c`), which feed
+ * `utm_campaign` and `ref` respectively. V1 contexts have no equivalent, so
+ * only the static defaults (`utm_source`, `utm_medium`, `via`) apply.
+ */
+function resolveAttributionValues(
+    context: FrakContextV1 | FrakContextV2,
+    overrides: AttributionParams
+): Record<string, string | undefined> {
+    const isV2 = isV2Context(context);
+    return {
+        utm_source: overrides.utmSource ?? DEFAULT_ATTRIBUTION_SOURCE,
+        utm_medium: overrides.utmMedium ?? DEFAULT_UTM_MEDIUM,
+        utm_campaign: overrides.utmCampaign ?? (isV2 ? context.m : undefined),
+        utm_content: overrides.utmContent,
+        utm_term: overrides.utmTerm,
+        via: overrides.via ?? DEFAULT_ATTRIBUTION_SOURCE,
+        ref: overrides.ref ?? (isV2 ? context.c : undefined),
+    };
+}
+
+/**
+ * Append attribution query params to a URL using gap-fill semantics.
+ *
+ * Existing params on the URL are preserved untouched (so merchant-provided
+ * UTMs take precedence). Only missing keys are populated.
+ */
+function applyAttributionParams(
+    urlObj: URL,
+    context: FrakContextV1 | FrakContextV2,
+    attribution?: AttributionParams
+): void {
+    const values = resolveAttributionValues(context, attribution ?? {});
+    for (const [key, value] of Object.entries(values)) {
+        if (value === undefined || value === "") continue;
+        if (urlObj.searchParams.has(key)) continue;
+        urlObj.searchParams.set(key, value);
+    }
+}
+
 /**
  * Add or replace the `fCtx` query parameter in a URL with the given context.
  *
+ * When `attribution` is provided (even as an empty object), standard affiliation
+ * params (`utm_source`, `utm_medium`, `utm_campaign`, `ref`, `via`, ...) are
+ * also appended using gap-fill semantics: pre-existing params on the URL are
+ * preserved, and defaults are derived from the context when applicable.
+ *
  * @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. Omit to skip UTM/ref params.
  * @returns The updated URL string, or null on failure
  */
 function update({
     url,
     context,
+    attribution,
 }: {
     url?: string;
     context: FrakContextV1 | FrakContextV2;
+    attribution?: AttributionParams;
 }): string | null {
     if (!url) return null;
 
@@ -113,6 +178,7 @@ function update({
 
     const urlObj = new URL(url);
     urlObj.searchParams.set(contextKey, compressedContext);
+    applyAttributionParams(urlObj, context, attribution);
     return urlObj.toString();
 }
 

package/src/utils/backendUrl.test.ts

@@ -15,13 +15,13 @@ describe("getBackendUrl", () => {
     describe("with explicit walletUrl", () => {
         test("should return localhost backend for localhost:3000", () => {
             expect(getBackendUrl("https://localhost:3000")).toBe(
-                "http://localhost:3030"
+                "https://localhost:3030"
             );
         });
 
         test("should return localhost backend for localhost:3010", () => {
             expect(getBackendUrl("https://localhost:3010")).toBe(
-                "http://localhost:3030"
+                "https://localhost:3030"
             );
         });
 

package/src/utils/backendUrl.ts

@@ -19,7 +19,7 @@ function isLocalDevelopment(walletUrl: string): boolean {
  */
 function deriveBackendUrl(walletUrl: string): string {
     if (isLocalDevelopment(walletUrl)) {
-        return "http://localhost:3030";
+        return "https://localhost:3030";
     }
     // Dev environment
     if (

package/src/utils/cache/index.ts

@@ -0,0 +1,7 @@
+export { LruMap } from "./lruMap";
+export {
+    clearAllCache,
+    DEFAULT_CACHE_TIME,
+    getCache,
+    withCache,
+} from "./withCache";

package/src/utils/cache/lruMap.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import { LruMap } from "./lruMap";
+
+describe("LruMap", () => {
+    it("should store and retrieve values", () => {
+        const map = new LruMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+
+        expect(map.get("a")).toBe(1);
+        expect(map.get("b")).toBe(2);
+    });
+
+    it("should evict least recently used when exceeding max size", () => {
+        const map = new LruMap<number>(2);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("c", 3); // Should evict "a"
+
+        expect(map.get("a")).toBeUndefined();
+        expect(map.get("b")).toBe(2);
+        expect(map.get("c")).toBe(3);
+    });
+
+    it("should promote accessed keys to most recently used", () => {
+        const map = new LruMap<number>(2);
+        map.set("a", 1);
+        map.set("b", 2);
+
+        // Access "a" to promote it
+        map.get("a");
+
+        // "b" is now least recently used, should be evicted
+        map.set("c", 3);
+
+        expect(map.get("a")).toBe(1);
+        expect(map.get("b")).toBeUndefined();
+        expect(map.get("c")).toBe(3);
+    });
+
+    it("should overwrite existing keys without increasing size", () => {
+        const map = new LruMap<number>(2);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("a", 10); // Overwrite, not a new entry
+
+        expect(map.size).toBe(2);
+        expect(map.get("a")).toBe(10);
+    });
+
+    it("should return undefined for missing keys", () => {
+        const map = new LruMap<number>(2);
+        expect(map.get("missing")).toBeUndefined();
+    });
+});

package/src/utils/cache/lruMap.ts

@@ -0,0 +1,38 @@
+/**
+ * Map with a LRU (Least Recently Used) eviction policy.
+ *
+ * When the map exceeds `maxSize`, the least recently accessed entry is removed.
+ * Accessing a key via `get()` promotes it to "most recently used".
+ *
+ * Adapted from viem's LruMap utility.
+ * @link https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU
+ */
+export class LruMap<TValue = unknown> extends Map<string, TValue> {
+    maxSize: number;
+
+    constructor(size: number) {
+        super();
+        this.maxSize = size;
+    }
+
+    override get(key: string) {
+        const value = super.get(key);
+        if (super.has(key)) {
+            // Move to end (most recently used)
+            super.delete(key);
+            super.set(key, value as TValue);
+        }
+        return value;
+    }
+
+    override set(key: string, value: TValue) {
+        if (super.has(key)) super.delete(key);
+        super.set(key, value);
+        // Evict least recently used if over capacity
+        if (this.maxSize && this.size > this.maxSize) {
+            const firstKey = super.keys().next().value;
+            if (firstKey !== undefined) super.delete(firstKey);
+        }
+        return this;
+    }
+}