@frak-labs/core-sdk 0.1.1 → 0.2.0

package/src/types/rpc/merchantInformation.ts

@@ -0,0 +1,77 @@
+import type { Address } from "viem";
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+
+/**
+ * The type for the amount of tokens
+ */
+export type TokenAmountType = {
+    amount: number;
+    eurAmount: number;
+    usdAmount: number;
+    gbpAmount: number;
+};
+
+/**
+ * A tier definition for tiered rewards
+ */
+export type RewardTier = {
+    minValue: number;
+    maxValue?: number;
+    amount: TokenAmountType;
+};
+
+/**
+ * Estimated reward amount — discriminated union by payout type
+ *
+ * - `fixed`: A known token amount (with fiat equivalents)
+ * - `percentage`: A percent of a purchase field (e.g. 5% of purchase_amount), with optional min/max caps
+ * - `tiered`: Amount depends on a field value matching tier brackets
+ */
+export type EstimatedReward =
+    | {
+          payoutType: "fixed";
+          amount: TokenAmountType;
+      }
+    | {
+          payoutType: "percentage";
+          percent: number;
+          percentOf: string;
+          maxAmount?: TokenAmountType;
+          minAmount?: TokenAmountType;
+      }
+    | {
+          payoutType: "tiered";
+          tierField: string;
+          tiers: RewardTier[];
+      };
+
+/**
+ * Response of the `frak_getMerchantInformation` RPC method
+ * @group RPC Schema
+ */
+export type GetMerchantInformationReturnType = {
+    /**
+     * Current merchant id
+     */
+    id: string;
+    /**
+     * Some metadata
+     */
+    onChainMetadata: {
+        /**
+         * Name of the merchant on-chain
+         */
+        name: string;
+        /**
+         * Domain of the merchant on-chain
+         */
+        domain: string;
+    };
+    rewards: {
+        token?: Address;
+        campaignId: string;
+        interactionTypeKey: InteractionTypeKey;
+        referrer?: EstimatedReward;
+        referee?: EstimatedReward;
+    }[];
+};

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

@@ -4,10 +4,6 @@ export type {
 } from "./final";
 export type { ModalStepMetadata } from "./generic";
 export type { LoginModalStepType } from "./login";
-export type {
-    OpenInteractionSessionModalStepType,
-    OpenInteractionSessionReturnType,
-} from "./openSession";
 export type {
     SiweAuthenticateModalStepType,
     SiweAuthenticateReturnType,

package/src/types/rpc/modal/login.ts

@@ -1,4 +1,4 @@
-import type { Address } from "viem";
+import type { Address, Hex } from "viem";
 import type { SsoMetadata } from "../sso";
 import type { GenericModalStepType } from "./generic";
 
@@ -28,5 +28,9 @@ export type LoginModalStepType = GenericModalStepType<
     LoginWithSso | LoginWithoutSso,
     {
         wallet: Address;
+        webauthnProof?: {
+            challenge: Hex;
+            authenticatorResponse: string;
+        };
     }
 >;

package/src/types/rpc/walletStatus.ts

@@ -14,13 +14,8 @@ export type WalletConnected = {
     key: "connected";
     // The user wallet address
     wallet: Address;
-    // The interaction token, used to push interactions to the delegator if needed
+    // The interaction token, used to push interactions to the backend
     interactionToken?: string;
-    // The current onchain interaction session of the user
-    interactionSession?: {
-        startTimestamp: number;
-        endTimestamp: number;
-    };
 };
 
 /**
@@ -31,5 +26,4 @@ export type WalletNotConnected = {
     key: "not-connected";
     wallet?: never;
     interactionToken?: never;
-    interactionSession?: never;
 };

package/src/types/rpc.ts

@@ -1,4 +1,3 @@
-import type { Hex } from "viem";
 import type { FrakWalletSdkConfig } from "./config";
 import type {
     ModalRpcMetadata,
@@ -9,11 +8,8 @@ import type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
 } from "./rpc/embedded";
-import type {
-    PreparedInteraction,
-    SendInteractionReturnType,
-} from "./rpc/interaction";
-import type { GetProductInformationReturnType } from "./rpc/productInformation";
+import type { SendInteractionParamsType } from "./rpc/interaction";
+import type { GetMerchantInformationReturnType } from "./rpc/merchantInformation";
 import type {
     OpenSsoParamsType,
     OpenSsoReturnType,
@@ -46,19 +42,14 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  * - Returns: {@link ModalRpcStepsResultType}
  * - Response Type: promise (one-shot)
  *
- * #### frak_sendInteraction
- *  - Params: [productId: Hex, interaction: {@link PreparedInteraction}, signature?: Hex]
- *  - Returns: {@link SendInteractionReturnType}
- *  - Response Type: promise (one-shot)
- *
  * #### frak_sso
  *  - Params: [params: {@link OpenSsoParamsType}, name: string, customCss?: string]
  *  - Returns: {@link OpenSsoReturnType}
  *  - Response Type: promise (one-shot)
  *
- * #### frak_getProductInformation
+ * #### frak_getMerchantInformation
  *  - Params: None
- *  - Returns: {@link GetProductInformationReturnType}
+ *  - Returns: {@link GetMerchantInformationReturnType}
  *  - Response Type: promise (one-shot)
  *
  * #### frak_displayEmbeddedWallet
@@ -89,19 +80,6 @@ export type IFrameRpcSchema = [
         ];
         ReturnType: ModalRpcStepsResultType;
     },
-    /**
-     * Method to transmit a user interaction
-     * This is a one-shot request
-     */
-    {
-        Method: "frak_sendInteraction";
-        Parameters: [
-            productId: Hex,
-            interaction: PreparedInteraction,
-            signature?: Hex,
-        ];
-        ReturnType: SendInteractionReturnType;
-    },
     /**
      * Method to prepare SSO (generate URL for popup)
      * Returns the SSO URL that should be opened in a popup
@@ -132,16 +110,16 @@ export type IFrameRpcSchema = [
         ReturnType: OpenSsoReturnType;
     },
     /**
-     * Method to get current product information's
-     *  - Is product minted?
+     * Method to get current merchant information
+     *  - Is merchant registered?
      *  - Does it have running campaign?
      *  - Estimated reward on actions
      * This is a one-shot request
      */
     {
-        Method: "frak_getProductInformation";
+        Method: "frak_getMerchantInformation";
         Parameters?: undefined;
-        ReturnType: GetProductInformationReturnType;
+        ReturnType: GetMerchantInformationReturnType;
     },
     /**
      * Method to show the embedded wallet, with potential customization
@@ -155,4 +133,18 @@ export type IFrameRpcSchema = [
         ];
         ReturnType: DisplayEmbeddedWalletResultType;
     },
+    /**
+     * 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
+     */
+    {
+        Method: "frak_sendInteraction";
+        Parameters: [
+            interaction: SendInteractionParamsType,
+            metadata?: { clientId?: string },
+        ];
+        ReturnType: undefined;
+    },
 ];

package/src/types/tracking.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for arrival tracking and referral attribution
+ * @category Tracking
+ */
+
+import type { Address } from "viem";
+
+/**
+ * UTM parameters for marketing attribution
+ * @category Tracking
+ */
+export type UtmParams = {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+};
+
+/**
+ * Parameters for tracking an arrival event
+ * @category Tracking
+ */
+export type TrackArrivalParams = {
+    /**
+     * The referrer wallet address (from fCtx URL param)
+     */
+    referrerWallet?: Address;
+    /**
+     * The landing page URL (defaults to current page)
+     */
+    landingUrl?: string;
+    /**
+     * UTM parameters for marketing attribution
+     */
+    utmParams?: UtmParams;
+};
+
+/**
+ * Result from tracking an arrival event
+ * @category Tracking
+ */
+export type TrackArrivalResult = {
+    success: boolean;
+    identityGroupId?: string;
+    touchpointId?: string;
+    error?: string;
+};
+
+/**
+ * Internal params passed to the trackArrival action
+ * Includes merchantId resolved from config or fetch
+ * @internal
+ */
+export type TrackArrivalInternalParams = TrackArrivalParams & {
+    /**
+     * The merchant ID (UUID from dashboard)
+     */
+    merchantId: string;
+};

package/src/utils/backendUrl.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { getBackendUrl } from "./backendUrl";
+
+describe("getBackendUrl", () => {
+    const originalWindow = globalThis.window;
+
+    beforeEach(() => {
+        vi.stubGlobal("window", { ...originalWindow });
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    describe("with explicit walletUrl", () => {
+        test("should return localhost backend for localhost:3000", () => {
+            expect(getBackendUrl("https://localhost:3000")).toBe(
+                "http://localhost:3030"
+            );
+        });
+
+        test("should return localhost backend for localhost:3010", () => {
+            expect(getBackendUrl("https://localhost:3010")).toBe(
+                "http://localhost:3030"
+            );
+        });
+
+        test("should return dev backend for wallet-dev.frak.id", () => {
+            expect(getBackendUrl("https://wallet-dev.frak.id")).toBe(
+                "https://backend.gcp-dev.frak.id"
+            );
+        });
+
+        test("should return dev backend for wallet.gcp-dev.frak.id", () => {
+            expect(getBackendUrl("https://wallet.gcp-dev.frak.id")).toBe(
+                "https://backend.gcp-dev.frak.id"
+            );
+        });
+
+        test("should return production backend for wallet.frak.id", () => {
+            expect(getBackendUrl("https://wallet.frak.id")).toBe(
+                "https://backend.frak.id"
+            );
+        });
+
+        test("should return production backend for unknown URLs", () => {
+            expect(getBackendUrl("https://some-other-url.com")).toBe(
+                "https://backend.frak.id"
+            );
+        });
+    });
+
+    describe("with FrakSetup global config", () => {
+        test("should derive from window.FrakSetup.client.config.walletUrl", () => {
+            vi.stubGlobal("window", {
+                FrakSetup: {
+                    client: {
+                        config: {
+                            walletUrl: "https://wallet-dev.frak.id",
+                        },
+                    },
+                },
+            });
+
+            expect(getBackendUrl()).toBe("https://backend.gcp-dev.frak.id");
+        });
+
+        test("should fall back to production when FrakSetup has no walletUrl", () => {
+            vi.stubGlobal("window", {
+                FrakSetup: { client: { config: {} } },
+            });
+
+            expect(getBackendUrl()).toBe("https://backend.frak.id");
+        });
+    });
+
+    describe("fallback", () => {
+        test("should return production URL when no walletUrl and no FrakSetup", () => {
+            vi.stubGlobal("window", {});
+            expect(getBackendUrl()).toBe("https://backend.frak.id");
+        });
+    });
+});

package/src/utils/backendUrl.ts

@@ -0,0 +1,62 @@
+/**
+ * Default production backend URL
+ */
+const DEFAULT_BACKEND_URL = "https://backend.frak.id";
+
+/**
+ * Check if wallet URL is local development (port 3000 or 3010)
+ */
+function isLocalDevelopment(walletUrl: string): boolean {
+    return (
+        walletUrl.includes("localhost:3000") ||
+        walletUrl.includes("localhost:3010")
+    );
+}
+
+/**
+ * Derive backend URL from wallet URL
+ * Maps wallet URLs to their corresponding backend URLs
+ */
+function deriveBackendUrl(walletUrl: string): string {
+    if (isLocalDevelopment(walletUrl)) {
+        return "http://localhost:3030";
+    }
+    // Dev environment
+    if (
+        walletUrl.includes("wallet-dev.frak.id") ||
+        walletUrl.includes("wallet.gcp-dev.frak.id")
+    ) {
+        return "https://backend.gcp-dev.frak.id";
+    }
+    // Production
+    return DEFAULT_BACKEND_URL;
+}
+
+/**
+ * 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)
+ */
+export function getBackendUrl(walletUrl?: string): string {
+    // If explicit walletUrl provided, derive from it
+    if (walletUrl) {
+        return deriveBackendUrl(walletUrl);
+    }
+
+    // Try to get from global FrakSetup config
+    if (typeof window !== "undefined") {
+        const configWalletUrl = (
+            window as {
+                FrakSetup?: { client?: { config?: { walletUrl?: string } } };
+            }
+        ).FrakSetup?.client?.config?.walletUrl;
+
+        if (configWalletUrl) {
+            return deriveBackendUrl(configWalletUrl);
+        }
+    }
+
+    // Fallback to production
+    return DEFAULT_BACKEND_URL;
+}

package/src/utils/clientId.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getClientId } from "./clientId";
+
+describe("clientId", () => {
+    beforeEach(() => {
+        // Clear localStorage before each test
+        localStorage.clear();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("getClientId", () => {
+        it("should generate and store a new client ID when none exists", () => {
+            const clientId = getClientId();
+
+            expect(clientId).toBeDefined();
+            expect(clientId).toMatch(
+                /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+            );
+            expect(localStorage.getItem("frak-client-id")).toBe(clientId);
+        });
+
+        it("should return existing client ID from localStorage", () => {
+            const existingId = "existing-uuid-1234";
+            localStorage.setItem("frak-client-id", existingId);
+
+            const clientId = getClientId();
+
+            expect(clientId).toBe(existingId);
+        });
+
+        it("should generate consistent UUIDs", () => {
+            const id1 = getClientId();
+            const id2 = getClientId();
+
+            expect(id1).toBe(id2);
+        });
+    });
+});

package/src/utils/clientId.ts

@@ -0,0 +1,43 @@
+/**
+ * Client ID utilities for anonymous tracking
+ * Generates and persists a UUID fingerprint for referral attribution
+ */
+
+const CLIENT_ID_KEY = "frak-client-id";
+
+/**
+ * Generate a UUID v4
+ * Uses crypto.randomUUID if available, otherwise falls back to a manual implementation
+ */
+function generateUUID(): string {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for older browsers
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+
+/**
+ * Get the client ID from localStorage, creating one if it doesn't exist
+ * @returns The client ID (UUID format)
+ */
+export function getClientId(): string {
+    if (typeof window === "undefined" || !window.localStorage) {
+        // SSR or no localStorage - generate ephemeral ID
+        console.warn(
+            "[Frak SDK] No Window / localStorage available to save the clientId"
+        );
+        return generateUUID();
+    }
+
+    let clientId = localStorage.getItem(CLIENT_ID_KEY);
+    if (!clientId) {
+        clientId = generateUUID();
+        localStorage.setItem(CLIENT_ID_KEY, clientId);
+    }
+    return clientId;
+}

package/src/utils/compression/compress.test.ts

@@ -7,7 +7,7 @@ import { vi } from "vitest";
 
 // Mock the frame-connector module - must be before imports
 vi.mock("@frak-labs/frame-connector", () => ({
-    compressJson: vi.fn((data: unknown) => {
+    jsonEncode: vi.fn((data: unknown) => {
         // Simple mock: convert JSON to Uint8Array
         const jsonString = JSON.stringify(data);
         return new TextEncoder().encode(jsonString);

package/src/utils/compression/compress.ts

@@ -1,4 +1,4 @@
-import { compressJson } from "@frak-labs/frame-connector";
+import { jsonEncode } from "@frak-labs/frame-connector";
 import { base64urlEncode } from "./b64";
 
 /**
@@ -7,5 +7,5 @@ import { base64urlEncode } from "./b64";
  * @ignore
  */
 export function compressJsonToB64(data: unknown): string {
-    return base64urlEncode(compressJson(data));
+    return base64urlEncode(jsonEncode(data));
 }

package/src/utils/compression/decompress.test.ts

@@ -7,15 +7,19 @@ import { vi } from "vitest";
 
 // Mock the frame-connector module - must be before imports
 vi.mock("@frak-labs/frame-connector", () => ({
-    compressJson: vi.fn((data: unknown) => {
+    jsonEncode: vi.fn((data: unknown) => {
         // Simple mock: convert JSON to Uint8Array
         const jsonString = JSON.stringify(data);
         return new TextEncoder().encode(jsonString);
     }),
-    decompressJson: vi.fn((data: Uint8Array) => {
+    jsonDecode: vi.fn((data: Uint8Array) => {
         // Simple mock: convert Uint8Array back to JSON
-        const jsonString = new TextDecoder().decode(data);
-        return JSON.parse(jsonString);
+        try {
+            const jsonString = new TextDecoder().decode(data);
+            return JSON.parse(jsonString);
+        } catch {
+            return null;
+        }
     }),
 }));
 

package/src/utils/compression/decompress.ts

@@ -1,4 +1,4 @@
-import { decompressJson } from "@frak-labs/frame-connector";
+import { jsonDecode } from "@frak-labs/frame-connector";
 import { base64urlDecode } from "./b64";
 
 /**
@@ -7,5 +7,5 @@ import { base64urlDecode } from "./b64";
  * @ignore
  */
 export function decompressJsonFromB64<T>(data: string): T | null {
-    return decompressJson(base64urlDecode(data));
+    return jsonDecode<T>(base64urlDecode(data));
 }

package/src/utils/{computeProductId.ts → computeLegacyProductId.ts}

@@ -1,10 +1,10 @@
 import { keccak256, toHex } from "viem";
 
 /**
- * Compute the product id from a domain
+ * Compute the legacy product id from a domain
  * @ignore
  */
-export function computeProductId({ domain }: { domain?: string } = {}) {
+export function computeLegacyProductId({ domain }: { domain?: string } = {}) {
     const effectiveDomain = domain ?? window.location.host;
     const normalizedDomain = effectiveDomain.replace("www.", "");
     return keccak256(toHex(normalizedDomain));

package/src/utils/constants.ts

@@ -2,3 +2,8 @@
  * The backup key for client side backup if needed
  */
 export const BACKUP_KEY = "nexus-wallet-backup";
+
+/**
+ * Deep link scheme for Frak Wallet mobile app
+ */
+export const DEEP_LINK_SCHEME = "frakwallet://";