@frak-labs/core-sdk 0.1.0-beta.afa252b0 → 0.1.0-beta.b0bd1f8a

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,
+        };
+    },
+};

package/src/interactions/purchaseEncoder.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Tests for PurchaseInteractionEncoder
+ * Tests encoding of purchase-related user interactions
+ */
+
+import type { Hex } from "viem";
+import { encodeAbiParameters, pad, toHex } from "viem";
+import { describe, expect, test } from "../../tests/vitest-fixtures";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import { PurchaseInteractionEncoder } from "./purchaseEncoder";
+
+describe("PurchaseInteractionEncoder", () => {
+    describe("startPurchase", () => {
+        test("should encode start purchase interaction with correct structure", ({
+            mockPurchaseId,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+
+            // Should return PreparedInteraction structure
+            expect(interaction).toHaveProperty("handlerTypeDenominator");
+            expect(interaction).toHaveProperty("interactionData");
+        });
+
+        test("should use purchase product type in handlerTypeDenominator", ({
+            mockPurchaseId,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+
+            // Should use purchase product type (31)
+            const expectedDenominator = toHex(productTypes.purchase);
+            expect(interaction.handlerTypeDenominator).toBe(
+                expectedDenominator
+            );
+        });
+
+        test("should include started interaction type in data", ({
+            mockPurchaseId,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+
+            // Should start with started interaction type
+            expect(interaction.interactionData).toContain(
+                interactionTypes.purchase.started
+            );
+        });
+
+        test("should pad purchase ID to 32 bytes", ({ mockPurchaseId }) => {
+            const interaction = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+
+            // Purchase ID should be padded to 32 bytes
+            const paddedPurchaseId = pad(mockPurchaseId, { size: 32 });
+            expect(interaction.interactionData).toContain(
+                paddedPurchaseId.slice(2)
+            );
+        });
+
+        test("should produce consistent output for same purchase ID", ({
+            mockPurchaseId,
+        }) => {
+            const interaction1 = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+            const interaction2 = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+
+            // Same input should produce same output
+            expect(interaction1).toEqual(interaction2);
+        });
+    });
+
+    describe("completedPurchase", () => {
+        test("should encode completed purchase with proof", ({
+            mockPurchaseId,
+            mockProof,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.completedPurchase({
+                purchaseId: mockPurchaseId,
+                proof: mockProof,
+            });
+
+            // Should return PreparedInteraction structure
+            expect(interaction).toHaveProperty("handlerTypeDenominator");
+            expect(interaction).toHaveProperty("interactionData");
+        });
+
+        test("should use purchase product type in handlerTypeDenominator", ({
+            mockPurchaseId,
+            mockProof,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.completedPurchase({
+                purchaseId: mockPurchaseId,
+                proof: mockProof,
+            });
+
+            // Should use purchase product type (31)
+            const expectedDenominator = toHex(productTypes.purchase);
+            expect(interaction.handlerTypeDenominator).toBe(
+                expectedDenominator
+            );
+        });
+
+        test("should include completed interaction type in data", ({
+            mockPurchaseId,
+            mockProof,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.completedPurchase({
+                purchaseId: mockPurchaseId,
+                proof: mockProof,
+            });
+
+            // Should start with completed interaction type
+            expect(interaction.interactionData).toContain(
+                interactionTypes.purchase.completed
+            );
+        });
+
+        test("should use ABI encoding for inner data", ({
+            mockPurchaseId,
+            mockProof,
+        }) => {
+            const interaction = PurchaseInteractionEncoder.completedPurchase({
+                purchaseId: mockPurchaseId,
+                proof: mockProof,
+            });
+
+            // Inner data should be ABI encoded (uint256 + bytes32[])
+            const expectedInnerData = encodeAbiParameters(
+                [{ type: "uint256" }, { type: "bytes32[]" }],
+                [BigInt(mockPurchaseId), mockProof]
+            );
+            expect(interaction.interactionData).toContain(
+                expectedInnerData.slice(2)
+            );
+        });
+
+        test("should handle empty proof array", ({ mockPurchaseId }) => {
+            const interaction = PurchaseInteractionEncoder.completedPurchase({
+                purchaseId: mockPurchaseId,
+                proof: [],
+            });
+
+            // Should still encode properly with empty proof
+            expect(interaction.interactionData).toBeDefined();
+            expect(interaction.handlerTypeDenominator).toBe(
+                toHex(productTypes.purchase)
+            );
+        });
+
+        test("should handle multiple proof elements", ({ mockPurchaseId }) => {
+            const largeProof: Hex[] = [
+                "0x0000000000000000000000000000000000000000000000000000000000000001",
+                "0x0000000000000000000000000000000000000000000000000000000000000002",
+                "0x0000000000000000000000000000000000000000000000000000000000000003",
+                "0x0000000000000000000000000000000000000000000000000000000000000004",
+                "0x0000000000000000000000000000000000000000000000000000000000000005",
+            ];
+
+            const interaction = PurchaseInteractionEncoder.completedPurchase({
+                purchaseId: mockPurchaseId,
+                proof: largeProof,
+            });
+
+            // Should handle larger proof arrays
+            expect(interaction.interactionData).toBeDefined();
+            expect(interaction.handlerTypeDenominator).toBe(
+                toHex(productTypes.purchase)
+            );
+        });
+    });
+
+    describe("unsafeCompletedPurchase", () => {
+        test("should encode unsafe completed purchase", ({
+            mockPurchaseId,
+        }) => {
+            const interaction =
+                PurchaseInteractionEncoder.unsafeCompletedPurchase({
+                    purchaseId: mockPurchaseId,
+                });
+
+            // Should return PreparedInteraction structure
+            expect(interaction).toHaveProperty("handlerTypeDenominator");
+            expect(interaction).toHaveProperty("interactionData");
+        });
+
+        test("should use purchase product type in handlerTypeDenominator", ({
+            mockPurchaseId,
+        }) => {
+            const interaction =
+                PurchaseInteractionEncoder.unsafeCompletedPurchase({
+                    purchaseId: mockPurchaseId,
+                });
+
+            // Should use purchase product type (31)
+            const expectedDenominator = toHex(productTypes.purchase);
+            expect(interaction.handlerTypeDenominator).toBe(
+                expectedDenominator
+            );
+        });
+
+        test("should include unsafeCompleted interaction type in data", ({
+            mockPurchaseId,
+        }) => {
+            const interaction =
+                PurchaseInteractionEncoder.unsafeCompletedPurchase({
+                    purchaseId: mockPurchaseId,
+                });
+
+            // Should start with unsafeCompleted interaction type
+            expect(interaction.interactionData).toContain(
+                interactionTypes.purchase.unsafeCompleted
+            );
+        });
+
+        test("should pad purchase ID to 32 bytes", ({ mockPurchaseId }) => {
+            const interaction =
+                PurchaseInteractionEncoder.unsafeCompletedPurchase({
+                    purchaseId: mockPurchaseId,
+                });
+
+            // Purchase ID should be padded to 32 bytes
+            const paddedPurchaseId = pad(mockPurchaseId, { size: 32 });
+            expect(interaction.interactionData).toContain(
+                paddedPurchaseId.slice(2)
+            );
+        });
+
+        test("should differ from safe completed purchase", ({
+            mockPurchaseId,
+        }) => {
+            const safeInteraction =
+                PurchaseInteractionEncoder.completedPurchase({
+                    purchaseId: mockPurchaseId,
+                    proof: [],
+                });
+            const unsafeInteraction =
+                PurchaseInteractionEncoder.unsafeCompletedPurchase({
+                    purchaseId: mockPurchaseId,
+                });
+
+            // Unsafe and safe versions should be different
+            expect(unsafeInteraction.interactionData).not.toBe(
+                safeInteraction.interactionData
+            );
+        });
+    });
+
+    describe("interaction data format", () => {
+        test("should produce valid hex strings", ({ mockPurchaseId }) => {
+            const startInteraction = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: mockPurchaseId,
+            });
+            const unsafeInteraction =
+                PurchaseInteractionEncoder.unsafeCompletedPurchase({
+                    purchaseId: mockPurchaseId,
+                });
+
+            // Both should be valid hex strings starting with 0x
+            expect(startInteraction.interactionData).toMatch(/^0x[0-9a-f]+$/);
+            expect(unsafeInteraction.interactionData).toMatch(/^0x[0-9a-f]+$/);
+        });
+
+        test("should handle different purchase IDs correctly", () => {
+            const purchaseId1 =
+                "0x0000000000000000000000000000000000000000000000000000000000000001" as const;
+            const purchaseId2 =
+                "0x0000000000000000000000000000000000000000000000000000000000000002" as const;
+
+            const interaction1 = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: purchaseId1,
+            });
+            const interaction2 = PurchaseInteractionEncoder.startPurchase({
+                purchaseId: purchaseId2,
+            });
+
+            // Different purchase IDs should produce different interaction data
+            expect(interaction1.interactionData).not.toBe(
+                interaction2.interactionData
+            );
+        });
+    });
+});

package/src/interactions/purchaseEncoder.ts

@@ -0,0 +1,99 @@
+import { concatHex, encodeAbiParameters, type Hex, pad, toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Purchase interactions allow you to track user purchases on your platform.
+ * After setting up these interactions, you can create acquisition campaign based on the user purchase  (starting a new one, completed, or even purchase dropped).
+ *
+ * :::info
+ *   To properly handle purchase interactions, ensure that the "Purchase" product type is enabled in your Business dashboard, and that you have set up everything correctly in the `Purchasetracker` section.
+ * :::
+ *
+ * :::note
+ * The `purchaseId` is used on both interactions. It can be computed like this:
+ *
+ * ```ts
+ * const purchaseId = keccak256(concatHex([productId, toHex(externalPurchaseId)]));
+ * ```
+ *
+ * With:
+ * - `productId`: The id of your product, you can find it in the product dashboard.
+ * - `externalPurchaseId`: The id of the purchase in your system (e.g. the shopify `order_id`).
+ * :::
+ *
+ * @description Encode purchase related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.trackPurchaseStatus | `trackPurchaseStatus()`} Action that will automatically send the purchase upon completion
+ * @see [Purchase Webhooks](/wallet-sdk/references-api/webhook) Webhooks to be implemented on your side to confirm a purchase
+ * @see [Purchase Proof](/wallet-sdk/references-api/purchaseProof) Get a merklee proof for the purchase
+ */
+export const PurchaseInteractionEncoder = {
+    /**
+     * Encode a start purchase interaction
+     * @param args
+     * @param args.purchaseId - The id of the purchase that is being started.
+     */
+    startPurchase({ purchaseId }: { purchaseId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.purchase.started,
+            pad(purchaseId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.purchase),
+            interactionData,
+        };
+    },
+
+    /**
+     * Encode a complete purchase interaction
+     * @param args
+     * @param args.purchaseId - The id of the purchase that is being completed.
+     * @param args.proof - The merkle proof that the user has completed the purchase (see [Purchase Webhooks](/wallet-sdk/references-api/webhook) for more details).
+     */
+    completedPurchase({
+        purchaseId,
+        proof,
+    }: {
+        purchaseId: Hex;
+        proof: Hex[];
+    }): PreparedInteraction {
+        const innerData = encodeAbiParameters(
+            [{ type: "uint256" }, { type: "bytes32[]" }],
+            [BigInt(purchaseId), proof]
+        );
+        const interactionData = concatHex([
+            interactionTypes.purchase.completed,
+            innerData,
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.purchase),
+            interactionData,
+        };
+    },
+
+    /**
+     * Encode an unsafe complete purchase interaction (when we can't provide the proof)
+     * @param args
+     * @param args.purchaseId - The id of the purchase that is being completed.
+     */
+    unsafeCompletedPurchase({
+        purchaseId,
+    }: {
+        purchaseId: Hex;
+    }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.purchase.unsafeCompleted,
+            pad(purchaseId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.purchase),
+            interactionData,
+        };
+    },
+};