@frak-labs/core-sdk 0.0.19 → 0.1.0-beta.00226d62

package/src/constants/productTypes.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for productTypes constants
+ * Tests product type definitions and bitmask calculations
+ */
+
+import { describe, expect, it } from "vitest";
+import { productTypes, productTypesMask } from "./productTypes";
+
+describe("productTypes", () => {
+    describe("structure", () => {
+        it("should have all expected product types", () => {
+            expect(productTypes).toHaveProperty("dapp");
+            expect(productTypes).toHaveProperty("press");
+            expect(productTypes).toHaveProperty("webshop");
+            expect(productTypes).toHaveProperty("retail");
+            expect(productTypes).toHaveProperty("referral");
+            expect(productTypes).toHaveProperty("purchase");
+        });
+
+        it("should have correct numeric values", () => {
+            expect(productTypes.dapp).toBe(1);
+            expect(productTypes.press).toBe(2);
+            expect(productTypes.webshop).toBe(3);
+            expect(productTypes.retail).toBe(4);
+            expect(productTypes.referral).toBe(30);
+            expect(productTypes.purchase).toBe(31);
+        });
+    });
+
+    describe("productTypesMask", () => {
+        it("should have masks for all product types", () => {
+            expect(productTypesMask).toHaveProperty("dapp");
+            expect(productTypesMask).toHaveProperty("press");
+            expect(productTypesMask).toHaveProperty("webshop");
+            expect(productTypesMask).toHaveProperty("retail");
+            expect(productTypesMask).toHaveProperty("referral");
+            expect(productTypesMask).toHaveProperty("purchase");
+        });
+
+        it("should calculate correct bitmask for dapp (value 1)", () => {
+            expect(productTypesMask.dapp).toBe(BigInt(1) << BigInt(1));
+            expect(productTypesMask.dapp).toBe(BigInt(2));
+        });
+
+        it("should calculate correct bitmask for press (value 2)", () => {
+            expect(productTypesMask.press).toBe(BigInt(1) << BigInt(2));
+            expect(productTypesMask.press).toBe(BigInt(4));
+        });
+
+        it("should calculate correct bitmask for webshop (value 3)", () => {
+            expect(productTypesMask.webshop).toBe(BigInt(1) << BigInt(3));
+            expect(productTypesMask.webshop).toBe(BigInt(8));
+        });
+
+        it("should calculate correct bitmask for retail (value 4)", () => {
+            expect(productTypesMask.retail).toBe(BigInt(1) << BigInt(4));
+            expect(productTypesMask.retail).toBe(BigInt(16));
+        });
+
+        it("should calculate correct bitmask for referral (value 30)", () => {
+            expect(productTypesMask.referral).toBe(BigInt(1) << BigInt(30));
+            expect(productTypesMask.referral).toBe(BigInt(1073741824));
+        });
+
+        it("should calculate correct bitmask for purchase (value 31)", () => {
+            expect(productTypesMask.purchase).toBe(BigInt(1) << BigInt(31));
+            expect(productTypesMask.purchase).toBe(BigInt(2147483648));
+        });
+
+        it("should have all masks as BigInt values", () => {
+            Object.values(productTypesMask).forEach((mask) => {
+                expect(typeof mask).toBe("bigint");
+            });
+        });
+
+        it("should have unique mask values", () => {
+            const maskValues = Object.values(productTypesMask);
+            const uniqueValues = new Set(maskValues);
+            expect(maskValues.length).toBe(uniqueValues.size);
+        });
+    });
+
+    describe("bitmask calculation", () => {
+        it("should correctly calculate bitmask from product type value", () => {
+            // Verify the formula: 1 << value
+            expect(productTypesMask.dapp).toBe(
+                BigInt(1) << BigInt(productTypes.dapp)
+            );
+            expect(productTypesMask.press).toBe(
+                BigInt(1) << BigInt(productTypes.press)
+            );
+            expect(productTypesMask.webshop).toBe(
+                BigInt(1) << BigInt(productTypes.webshop)
+            );
+            expect(productTypesMask.retail).toBe(
+                BigInt(1) << BigInt(productTypes.retail)
+            );
+            expect(productTypesMask.referral).toBe(
+                BigInt(1) << BigInt(productTypes.referral)
+            );
+            expect(productTypesMask.purchase).toBe(
+                BigInt(1) << BigInt(productTypes.purchase)
+            );
+        });
+
+        it("should have masks that are powers of 2", () => {
+            Object.values(productTypesMask).forEach((mask) => {
+                // A power of 2 has exactly one bit set
+                // Check: mask & (mask - 1n) should be 0n
+                const isPowerOfTwo = mask > 0n && (mask & (mask - 1n)) === 0n;
+                expect(isPowerOfTwo).toBe(true);
+            });
+        });
+    });
+
+    describe("type safety", () => {
+        it("should have consistent structure", () => {
+            const productKeys = Object.keys(productTypes);
+            const maskKeys = Object.keys(productTypesMask);
+            expect(productKeys.sort()).toEqual(maskKeys.sort());
+        });
+
+        it("should have numeric values for product types", () => {
+            Object.values(productTypes).forEach((value) => {
+                expect(typeof value).toBe("number");
+                expect(Number.isInteger(value)).toBe(true);
+            });
+        });
+    });
+});

package/src/constants/productTypes.ts

@@ -0,0 +1,33 @@
+/**
+ * The keys for each product types
+ * @inline
+ */
+export type ProductTypesKey = keyof typeof productTypes;
+
+/**
+ * List of the product types per denominator
+ */
+export const productTypes = {
+    // content type
+    dapp: 1,
+    press: 2,
+    webshop: 3,
+    retail: 4,
+
+    // feature type
+    referral: 30,
+    purchase: 31,
+};
+
+/**
+ * Bitmask for each product types
+ */
+export const productTypesMask: Record<ProductTypesKey, bigint> = Object.entries(
+    productTypes
+).reduce(
+    (acc, [key, value]) => {
+        acc[key as ProductTypesKey] = BigInt(1) << BigInt(value);
+        return acc;
+    },
+    {} as Record<ProductTypesKey, bigint>
+);

package/src/index.ts

@@ -0,0 +1,101 @@
+// Clients
+
+export { ssoPopupFeatures, ssoPopupName } from "./actions/openSso";
+export {
+    createIFrameFrakClient,
+    DebugInfoGatherer,
+    setupClient,
+} from "./clients";
+export {
+    type FullInteractionTypesKey,
+    type InteractionTypesKey,
+    interactionTypes,
+} from "./constants/interactionTypes";
+export { type LocalesKey, locales } from "./constants/locales";
+// Constants
+export {
+    type ProductTypesKey,
+    productTypes,
+    productTypesMask,
+} from "./constants/productTypes";
+// Types
+export type {
+    ClientLifecycleEvent,
+    CompressedData,
+    Currency,
+    // RPC Embedded wallet
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    DisplayModalParamsType,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    FinalActionType,
+    FinalModalStepType,
+    // Client
+    FrakClient,
+    // Utils
+    FrakContext,
+    FrakLifecycleEvent,
+    // Config
+    FrakWalletSdkConfig,
+    GetProductInformationReturnType,
+    HashProtectedData,
+    I18nConfig,
+    IFrameLifecycleEvent,
+    IFrameRpcSchema,
+    // Transport
+    IFrameTransport,
+    // Compression
+    KeyProvider,
+    Language,
+    LocalizedI18nConfig,
+    LoggedInEmbeddedView,
+    LoggedOutEmbeddedView,
+    LoginModalStepType,
+    ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    // RPC Modal types
+    ModalStepMetadata,
+    // RPC Modal generics
+    ModalStepTypes,
+    OpenInteractionSessionModalStepType,
+    OpenInteractionSessionReturnType,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PreparedInteraction,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+    SendInteractionParamsType,
+    SendInteractionReturnType,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    SendTransactionTxType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
+    SsoMetadata,
+    TokenAmountType,
+    // Rpc
+    WalletStatusReturnType,
+} from "./types";
+// Utils
+export {
+    type AppSpecificSsoMetadata,
+    base64urlDecode,
+    base64urlEncode,
+    baseIframeProps,
+    type CompressedSsoData,
+    compressJsonToB64,
+    createIframe,
+    decompressJsonFromB64,
+    FrakContextManager,
+    type FullSsoParams,
+    findIframeInOpener,
+    formatAmount,
+    generateSsoUrl,
+    getCurrencyAmountKey,
+    getSupportedCurrency,
+    getSupportedLocale,
+    trackEvent,
+} from "./utils";

package/src/interactions/index.ts

@@ -0,0 +1,5 @@
+export { PressInteractionEncoder } from "./pressEncoder";
+export { PurchaseInteractionEncoder } from "./purchaseEncoder";
+export { ReferralInteractionEncoder } from "./referralEncoder";
+export { RetailInteractionEncoder } from "./retailEncoder";
+export { WebShopInteractionEncoder } from "./webshopEncoder";

package/src/interactions/pressEncoder.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Tests for PressInteractionEncoder
+ * Tests encoding of press-related user interactions
+ */
+
+import { pad, toHex } from "viem";
+import { describe, expect, it, test } from "../../tests/vitest-fixtures";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import { PressInteractionEncoder } from "./pressEncoder";
+
+describe("PressInteractionEncoder", () => {
+    describe("openArticle", () => {
+        test("should encode open article interaction with correct structure", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should return PreparedInteraction structure
+            expect(interaction).toHaveProperty("handlerTypeDenominator");
+            expect(interaction).toHaveProperty("interactionData");
+        });
+
+        test("should use press product type in handlerTypeDenominator", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should use press product type (2)
+            const expectedDenominator = toHex(productTypes.press);
+            expect(interaction.handlerTypeDenominator).toBe(
+                expectedDenominator
+            );
+        });
+
+        test("should include openArticle interaction type in data", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should start with openArticle interaction type
+            expect(interaction.interactionData).toContain(
+                interactionTypes.press.openArticle
+            );
+        });
+
+        test("should pad article ID to 32 bytes", ({ mockArticleId }) => {
+            const interaction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+
+            // Article ID should be padded to 32 bytes (64 hex chars + 0x prefix = 66 chars)
+            const paddedArticleId = pad(mockArticleId, { size: 32 });
+            expect(interaction.interactionData).toContain(
+                paddedArticleId.slice(2)
+            );
+        });
+
+        it("should handle short article IDs by padding", () => {
+            const shortArticleId = "0x01" as const;
+            const interaction = PressInteractionEncoder.openArticle({
+                articleId: shortArticleId,
+            });
+
+            // Should pad short IDs to 32 bytes
+            expect(interaction.interactionData).toBeDefined();
+            // Total length: openArticle (10 chars) + padded ID (64 chars) + 0x (2 chars) = 76 chars
+            expect(interaction.interactionData.length).toBeGreaterThan(64);
+        });
+
+        test("should produce consistent output for same article ID", ({
+            mockArticleId,
+        }) => {
+            const interaction1 = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+            const interaction2 = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+
+            // Same input should produce same output
+            expect(interaction1).toEqual(interaction2);
+        });
+    });
+
+    describe("readArticle", () => {
+        test("should encode read article interaction with correct structure", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.readArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should return PreparedInteraction structure
+            expect(interaction).toHaveProperty("handlerTypeDenominator");
+            expect(interaction).toHaveProperty("interactionData");
+        });
+
+        test("should use press product type in handlerTypeDenominator", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.readArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should use press product type (2)
+            const expectedDenominator = toHex(productTypes.press);
+            expect(interaction.handlerTypeDenominator).toBe(
+                expectedDenominator
+            );
+        });
+
+        test("should include readArticle interaction type in data", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.readArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should start with readArticle interaction type
+            expect(interaction.interactionData).toContain(
+                interactionTypes.press.readArticle
+            );
+        });
+
+        test("should pad article ID to 32 bytes", ({ mockArticleId }) => {
+            const interaction = PressInteractionEncoder.readArticle({
+                articleId: mockArticleId,
+            });
+
+            // Article ID should be padded to 32 bytes
+            const paddedArticleId = pad(mockArticleId, { size: 32 });
+            expect(interaction.interactionData).toContain(
+                paddedArticleId.slice(2)
+            );
+        });
+
+        test("should produce different output than openArticle for same ID", ({
+            mockArticleId,
+        }) => {
+            const openInteraction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+            const readInteraction = PressInteractionEncoder.readArticle({
+                articleId: mockArticleId,
+            });
+
+            // Different interaction types should produce different data
+            expect(openInteraction.interactionData).not.toBe(
+                readInteraction.interactionData
+            );
+
+            // But should have same handlerTypeDenominator (both press)
+            expect(openInteraction.handlerTypeDenominator).toBe(
+                readInteraction.handlerTypeDenominator
+            );
+        });
+    });
+
+    describe("interaction data format", () => {
+        test("should concatenate interaction type and padded article ID", ({
+            mockArticleId,
+        }) => {
+            const interaction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+
+            // Should start with interaction type (10 chars including 0x)
+            expect(interaction.interactionData.slice(0, 10)).toBe(
+                interactionTypes.press.openArticle
+            );
+
+            // Should be followed by padded article ID (64 hex chars)
+            expect(interaction.interactionData.length).toBe(74); // 0x + 8 (type) + 64 (padded ID)
+        });
+
+        test("should produce valid hex strings", ({ mockArticleId }) => {
+            const openInteraction = PressInteractionEncoder.openArticle({
+                articleId: mockArticleId,
+            });
+            const readInteraction = PressInteractionEncoder.readArticle({
+                articleId: mockArticleId,
+            });
+
+            // Both should be valid hex strings starting with 0x
+            expect(openInteraction.interactionData).toMatch(/^0x[0-9a-f]+$/);
+            expect(readInteraction.interactionData).toMatch(/^0x[0-9a-f]+$/);
+        });
+
+        it("should handle different article IDs correctly", () => {
+            const articleId1 =
+                "0x0000000000000000000000000000000000000000000000000000000000000001" as const;
+            const articleId2 =
+                "0x0000000000000000000000000000000000000000000000000000000000000002" as const;
+
+            const interaction1 = PressInteractionEncoder.openArticle({
+                articleId: articleId1,
+            });
+            const interaction2 = PressInteractionEncoder.openArticle({
+                articleId: articleId2,
+            });
+
+            // Different article IDs should produce different interaction data
+            expect(interaction1.interactionData).not.toBe(
+                interaction2.interactionData
+            );
+        });
+    });
+});

package/src/interactions/pressEncoder.ts

@@ -0,0 +1,53 @@
+import { concatHex, type Hex, pad, toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Press interactions allow you to track user engagement with articles or other press content on your platform.
+ * After setting up these interactions, you can create acquisition campaign based on the user engagement with your press content.
+ *
+ * :::info
+ *   To properly handle press interactions, ensure that the "Press" product type is enabled in your Business dashboard.
+ * :::
+ *
+ * @description Encode press related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ */
+export const PressInteractionEncoder = {
+    /**
+     * Encode an open article interaction
+     * @param args
+     * @param args.articleId - The id of the article the user opened (32 bytes), could be a `keccak256` hash of the article slug, or your internal id
+     */
+    openArticle({ articleId }: { articleId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.press.openArticle,
+            pad(articleId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.press),
+            interactionData,
+        };
+    },
+
+    /**
+     * Encode a read article interaction
+     * @param args
+     * @param args.articleId - The id of the article the user opened (32 bytes), could be a `keccak256` hash of the article slug, or your internal id
+     */
+    readArticle({ articleId }: { articleId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.press.readArticle,
+            pad(articleId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.press),
+            interactionData,
+        };
+    },
+};