@frak-labs/core-sdk 1.0.0 → 1.0.1

package/src/utils/{trackEvent.test.ts → analytics/trackEvent.test.ts}

@@ -10,8 +10,8 @@ import {
     expect,
     it,
     vi,
-} from "../../tests/vitest-fixtures";
-import type { FrakClient } from "../types";
+} from "../../../tests/vitest-fixtures";
+import type { FrakClient } from "../../types";
 import { trackEvent } from "./trackEvent";
 
 describe("trackEvent", () => {
@@ -42,16 +42,19 @@ describe("trackEvent", () => {
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "share_button_clicked",
-                {}
+                undefined
             );
         });
 
         it("should track event with props", () => {
-            const props = { userId: "123", page: "home" };
-            trackEvent(mockClient, "wallet_button_clicked", props);
+            const props = {
+                placement: "footer",
+                click_action: "share-modal",
+            } as const;
+            trackEvent(mockClient, "share_button_clicked", props);
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
-                "wallet_button_clicked",
+                "share_button_clicked",
                 props
             );
         });
@@ -71,25 +74,18 @@ describe("trackEvent", () => {
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "user_referred_started",
-                {}
+                undefined
             );
         });
 
         it("should track user_referred_completed event", () => {
-            trackEvent(mockClient, "user_referred_completed");
+            trackEvent(mockClient, "user_referred_completed", {
+                status: "success",
+            });
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "user_referred_completed",
-                {}
-            );
-        });
-
-        it("should track user_referred_error event", () => {
-            trackEvent(mockClient, "user_referred_error");
-
-            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
-                "user_referred_error",
-                {}
+                { status: "success" }
             );
         });
     });
@@ -102,7 +98,7 @@ describe("trackEvent", () => {
         });
 
         it("should log debug message when client is undefined", () => {
-            trackEvent(undefined, "wallet_button_clicked");
+            trackEvent(undefined, "share_button_clicked");
 
             expect(consoleDebugSpy).toHaveBeenCalledWith(
                 "[Frak] No client provided, skipping event tracking"
@@ -143,30 +139,26 @@ describe("trackEvent", () => {
             const clientWithoutPanel = {} as FrakClient;
 
             expect(() => {
-                trackEvent(clientWithoutPanel, "wallet_button_clicked");
+                trackEvent(clientWithoutPanel, "share_button_clicked");
             }).not.toThrow();
         });
     });
 
     describe("edge cases", () => {
-        it("should handle empty props object", () => {
-            trackEvent(mockClient, "share_button_clicked", {});
+        it("should handle typed props object", () => {
+            trackEvent(mockClient, "share_button_clicked", {
+                click_action: "share-modal",
+            });
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "share_button_clicked",
-                {}
+                { click_action: "share-modal" }
             );
         });
 
         it("should handle complex props object", () => {
             const complexProps = {
-                userId: "123",
-                metadata: {
-                    page: "home",
-                    section: "header",
-                },
-                tags: ["tag1", "tag2"],
-                timestamp: Date.now(),
+                status: "success" as const,
             };
 
             trackEvent(mockClient, "user_referred_completed", complexProps);

package/src/utils/analytics/trackEvent.ts

@@ -0,0 +1,34 @@
+import type { FrakClient } from "../../types";
+import type { SdkEventMap } from "./events";
+
+/**
+ * Track an analytics event via the SDK's OpenPanel instance.
+ * Fire-and-forget — silently catches errors so analytics never break a
+ * partner integration.
+ *
+ * The client must be passed explicitly because the OpenPanel instance is
+ * scoped to each `FrakClient` (a partner site may hold multiple iframes).
+ *
+ * @param client - The Frak client instance (no-op if undefined)
+ * @param event - Typed event name from the SDK event map
+ * @param properties - Typed properties for the given event
+ */
+export function trackEvent<K extends keyof SdkEventMap>(
+    client: FrakClient | undefined,
+    event: K,
+    properties?: SdkEventMap[K]
+): void {
+    if (!client) {
+        console.debug("[Frak] No client provided, skipping event tracking");
+        return;
+    }
+
+    try {
+        client.openPanel?.track(
+            event as string,
+            properties as Record<string, unknown> | undefined
+        );
+    } catch (e) {
+        console.debug("[Frak] Failed to track event:", event, e);
+    }
+}

package/src/utils/frakContextV2Codec.test.ts

@@ -0,0 +1,241 @@
+import type { Address } from "viem";
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import type { FrakContextV2 } from "../types";
+import { base64urlEncode } from "./compression/b64";
+import {
+    decodeFrakContextV2,
+    encodeFrakContextV2,
+    isV2BinaryLength,
+} from "./frakContextV2Codec";
+
+const MERCHANT = "550e8400-e29b-41d4-a716-446655440000";
+const CLIENT = "550e8400-e29b-41d4-a716-446655440001";
+const WALLET = "0x1234567890123456789012345678901234567890" as Address;
+
+describe("frakContextV2Codec", () => {
+    describe("encodeFrakContextV2 / decodeFrakContextV2 round-trip", () => {
+        it("round-trips a context with clientId only (37 bytes)", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                c: CLIENT,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            expect(encoded).toBeInstanceOf(Uint8Array);
+            expect(encoded?.length).toBe(37);
+            expect(decodeFrakContextV2(encoded as Uint8Array)).toEqual(ctx);
+        });
+
+        it("round-trips a context with wallet only (41 bytes)", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                w: WALLET,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            expect(encoded?.length).toBe(41);
+            expect(decodeFrakContextV2(encoded as Uint8Array)).toEqual(ctx);
+        });
+
+        it("round-trips a context with clientId + wallet (57 bytes)", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                c: CLIENT,
+                w: WALLET,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            expect(encoded?.length).toBe(57);
+            expect(decodeFrakContextV2(encoded as Uint8Array)).toEqual(ctx);
+        });
+
+        it("produces a base64url string shorter than the legacy JSON format", () => {
+            // Legacy reference: a typical anonymous context is ~115 JSON bytes
+            // \u2192 ~154 base64url chars. Wallet variant is ~165 \u2192 ~220 chars.
+            const ctxBoth: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                c: CLIENT,
+                w: WALLET,
+            };
+            const encoded = base64urlEncode(
+                encodeFrakContextV2(ctxBoth) as Uint8Array
+            );
+            // 57 bytes encodes to 76 chars (no padding).
+            expect(encoded.length).toBe(76);
+            // Sanity: far below the legacy ~220-char payload.
+            expect(encoded.length).toBeLessThan(100);
+        });
+
+        it("preserves UUID case insensitivity on decode", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT.toUpperCase(),
+                t: 1,
+                c: CLIENT,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            const decoded = decodeFrakContextV2(encoded as Uint8Array);
+            // Decoded UUIDs are lower-case canonical.
+            expect(decoded?.m).toBe(MERCHANT);
+        });
+
+        it("preserves timestamp at the uint32 boundary", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 0xff_ff_ff_ff,
+                c: CLIENT,
+            };
+            const decoded = decodeFrakContextV2(
+                encodeFrakContextV2(ctx) as Uint8Array
+            );
+            expect(decoded?.t).toBe(0xff_ff_ff_ff);
+        });
+    });
+
+    describe("encodeFrakContextV2 validation", () => {
+        it("rejects non-UUID merchant id", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: "not-a-uuid",
+                    t: 1,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+        });
+
+        it("rejects non-UUID client id", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1,
+                    c: "not-a-uuid",
+                })
+            ).toBeNull();
+        });
+
+        it("rejects malformed wallet address", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1,
+                    w: "0xnot-a-wallet" as Address,
+                })
+            ).toBeNull();
+        });
+
+        it("rejects contexts missing both c and w", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1,
+                } as FrakContextV2)
+            ).toBeNull();
+        });
+
+        it("rejects timestamps outside uint32 range", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: -1,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 0x1_00_00_00_00,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1.5,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+        });
+    });
+
+    describe("decodeFrakContextV2 validation", () => {
+        it("returns null on wrong version nibble", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            const tampered = new Uint8Array(encoded);
+            tampered[0] = (tampered[0] & 0xf0) | 0x03; // flip version to 3
+            expect(decodeFrakContextV2(tampered)).toBeNull();
+        });
+
+        it("returns null when reserved header bits are set", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            const tampered = new Uint8Array(encoded);
+            tampered[0] |= 0x80;
+            expect(decodeFrakContextV2(tampered)).toBeNull();
+        });
+
+        it("returns null when neither flag is set", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            const tampered = new Uint8Array(encoded);
+            tampered[0] &= 0x0f; // clear flags, keep version
+            expect(decodeFrakContextV2(tampered)).toBeNull();
+        });
+
+        it("returns null when byte length disagrees with flags", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            // Drop the trailing byte to break the expected length.
+            const truncated = encoded.subarray(0, encoded.length - 1);
+            expect(decodeFrakContextV2(truncated)).toBeNull();
+        });
+
+        it("returns null on an empty buffer", () => {
+            expect(decodeFrakContextV2(new Uint8Array(0))).toBeNull();
+        });
+    });
+
+    describe("isV2BinaryLength", () => {
+        it("matches exactly the three valid V2 sizes", () => {
+            expect(isV2BinaryLength(37)).toBe(true);
+            expect(isV2BinaryLength(41)).toBe(true);
+            expect(isV2BinaryLength(57)).toBe(true);
+        });
+
+        it("rejects V1 size and everything else", () => {
+            expect(isV2BinaryLength(20)).toBe(false);
+            expect(isV2BinaryLength(0)).toBe(false);
+            expect(isV2BinaryLength(36)).toBe(false);
+            expect(isV2BinaryLength(58)).toBe(false);
+        });
+    });
+});

package/src/utils/frakContextV2Codec.ts

@@ -0,0 +1,197 @@
+/**
+ * Binary codec for {@link FrakContextV2}.
+ *
+ * Produces a compact, URL-safe byte layout (~65% smaller than the previous
+ * JSON+base64url format). See the layout below.
+ *
+ * ## Wire layout
+ *
+ * ```text
+ * byte 0:          header
+ *                    bits 0-3  version         (= 2)
+ *                    bit  4    has_c flag
+ *                    bit  5    has_w flag
+ *                    bits 6-7  reserved (must be 0)
+ * bytes 1..16:     merchant UUID   (16 bytes, mandatory)
+ * bytes 17..20:    timestamp       (uint32 big-endian, Unix seconds)
+ * bytes 21..36:    client UUID     (16 bytes, only when has_c is set)
+ * bytes 37..56:    wallet address  (20 bytes, only when has_w is set)
+ * ```
+ *
+ * Size variants (before base64url):
+ * - has_c only:     37 bytes
+ * - has_w only:     41 bytes
+ * - has_c + has_w:  57 bytes
+ *
+ * V1 payloads are exactly 20 bytes (raw wallet address); the byte lengths never
+ * overlap, so the outer decoder can disambiguate purely on length.
+ *
+ * @ignore
+ */
+import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
+import type { FrakContextV2 } from "../types";
+
+const VERSION_V2 = 0x02;
+const VERSION_MASK = 0x0f;
+const FLAG_HAS_C = 1 << 4;
+const FLAG_HAS_W = 1 << 5;
+const RESERVED_MASK = 0xc0;
+
+const UUID_BYTES = 16;
+const TIMESTAMP_BYTES = 4;
+const ADDRESS_BYTES = 20;
+const HEADER_BYTES = 1;
+
+const UUID_RE =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Strict lower-case UUID validation (RFC 4122 shape, any version/variant). */
+function isUuid(value: unknown): value is string {
+    return typeof value === "string" && UUID_RE.test(value);
+}
+
+/** Parse a canonical UUID string into 16 raw bytes. */
+function uuidToBytes(uuid: string): Uint8Array {
+    const hex = uuid.replace(/-/g, "");
+    const out = new Uint8Array(UUID_BYTES);
+    for (let i = 0; i < UUID_BYTES; i++) {
+        out[i] = Number.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+
+/** Format 16 raw bytes as a canonical 8-4-4-4-12 UUID string. */
+function bytesToUuid(bytes: Uint8Array): string {
+    let hex = "";
+    for (let i = 0; i < UUID_BYTES; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/**
+ * Encode a {@link FrakContextV2} into its binary wire format.
+ *
+ * Returns `null` when the context fails runtime validation (missing fields,
+ * malformed UUIDs, timestamp outside uint32 range, invalid wallet).
+ */
+export function encodeFrakContextV2(ctx: FrakContextV2): Uint8Array | null {
+    if (!isUuid(ctx.m)) return null;
+    if (!Number.isInteger(ctx.t) || ctx.t < 0 || ctx.t > 0xff_ff_ff_ff)
+        return null;
+
+    const hasC = typeof ctx.c === "string" && ctx.c.length > 0;
+    const hasW = typeof ctx.w === "string" && isAddress(ctx.w);
+    if (!hasC && !hasW) return null;
+    if (hasC && !isUuid(ctx.c)) return null;
+
+    const size =
+        HEADER_BYTES +
+        UUID_BYTES +
+        TIMESTAMP_BYTES +
+        (hasC ? UUID_BYTES : 0) +
+        (hasW ? ADDRESS_BYTES : 0);
+
+    const buf = new Uint8Array(size);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    let offset = 0;
+
+    buf[offset++] =
+        VERSION_V2 | (hasC ? FLAG_HAS_C : 0) | (hasW ? FLAG_HAS_W : 0);
+
+    buf.set(uuidToBytes(ctx.m), offset);
+    offset += UUID_BYTES;
+
+    view.setUint32(offset, ctx.t, false);
+    offset += TIMESTAMP_BYTES;
+
+    if (hasC) {
+        buf.set(uuidToBytes(ctx.c as string), offset);
+        offset += UUID_BYTES;
+    }
+
+    if (hasW) {
+        buf.set(hexToBytes(ctx.w as Address), offset);
+        offset += ADDRESS_BYTES;
+    }
+
+    return buf;
+}
+
+/**
+ * Decode a binary {@link FrakContextV2} payload.
+ *
+ * Returns `null` when:
+ * - the header version nibble is not V2
+ * - reserved header bits are set (guards against future-version payloads)
+ * - neither flag is set (invalid: V2 must carry `c` and/or `w`)
+ * - the byte length does not match the length implied by the header flags
+ * - the decoded wallet does not pass `isAddress` (defense-in-depth against
+ *   crafted payloads that round-trip by length but carry junk)
+ */
+export function decodeFrakContextV2(buf: Uint8Array): FrakContextV2 | null {
+    if (buf.length < HEADER_BYTES + UUID_BYTES + TIMESTAMP_BYTES) return null;
+
+    const header = buf[0];
+    if ((header & VERSION_MASK) !== VERSION_V2) return null;
+    if ((header & RESERVED_MASK) !== 0) return null;
+
+    const hasC = (header & FLAG_HAS_C) !== 0;
+    const hasW = (header & FLAG_HAS_W) !== 0;
+    if (!hasC && !hasW) return null;
+
+    const expected =
+        HEADER_BYTES +
+        UUID_BYTES +
+        TIMESTAMP_BYTES +
+        (hasC ? UUID_BYTES : 0) +
+        (hasW ? ADDRESS_BYTES : 0);
+    if (buf.length !== expected) return null;
+
+    let offset = HEADER_BYTES;
+
+    const m = bytesToUuid(buf.subarray(offset, offset + UUID_BYTES));
+    offset += UUID_BYTES;
+
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const t = view.getUint32(offset, false);
+    offset += TIMESTAMP_BYTES;
+
+    const out: FrakContextV2 = { v: 2, m, t };
+
+    if (hasC) {
+        out.c = bytesToUuid(buf.subarray(offset, offset + UUID_BYTES));
+        offset += UUID_BYTES;
+    }
+
+    if (hasW) {
+        const walletHex = bytesToHex(
+            buf.subarray(offset, offset + ADDRESS_BYTES),
+            { size: ADDRESS_BYTES }
+        ) as Address;
+        if (!isAddress(walletHex)) return null;
+        out.w = walletHex;
+        offset += ADDRESS_BYTES;
+    }
+
+    return out;
+}
+
+/**
+ * Quick length-based probe to tell V1 (20-byte wallet address) apart from a V2
+ * binary payload. Exposed so the outer decoder can branch without re-parsing.
+ */
+export function isV2BinaryLength(byteLength: number): boolean {
+    return (
+        byteLength ===
+            HEADER_BYTES + UUID_BYTES + TIMESTAMP_BYTES + UUID_BYTES ||
+        byteLength ===
+            HEADER_BYTES + UUID_BYTES + TIMESTAMP_BYTES + ADDRESS_BYTES ||
+        byteLength ===
+            HEADER_BYTES +
+                UUID_BYTES +
+                TIMESTAMP_BYTES +
+                UUID_BYTES +
+                ADDRESS_BYTES
+    );
+}

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { Deferred } from "@frak-labs/frame-connector";
+export { trackEvent } from "./analytics";
 export { getBackendUrl } from "./backendUrl";
 export { clearAllCache, getCache, withCache } from "./cache";
 export { getClientId } from "./clientId";
@@ -28,6 +29,10 @@ export {
     isIOS,
     redirectToExternalBrowser,
 } from "./inAppBrowser";
+export {
+    type MergeAttributionInput,
+    mergeAttribution,
+} from "./mergeAttribution";
 export { sdkConfigStore } from "./sdkConfigStore";
 export {
     type AppSpecificSsoMetadata,
@@ -35,4 +40,3 @@ export {
     type FullSsoParams,
     generateSsoUrl,
 } from "./sso";
-export { type FrakEvent, trackEvent } from "./trackEvent";