@frak-labs/core-sdk 0.1.0-beta.8d103039 → 0.1.0-beta.d9302e66

package/src/types/index.ts

@@ -1,70 +1,71 @@
 // Rpc related
-export type { WalletStatusReturnType } from "./rpc/walletStatus";
-export type {
-    DisplayEmbeddedWalletParamsType,
-    DisplayEmbeddedWalletResultType,
-    LoggedOutEmbeddedView,
-    LoggedInEmbeddedView,
-    EmbeddedViewActionReferred,
-    EmbeddedViewActionSharing,
-} from "./rpc/embedded";
-export type {
-    SsoMetadata,
-    OpenSsoParamsType,
-    OpenSsoReturnType,
-    PrepareSsoParamsType,
-    PrepareSsoReturnType,
-} from "./rpc/sso";
-export type {
-    TokenAmountType,
-    GetProductInformationReturnType,
-} from "./rpc/productInformation";
-export type {
-    PreparedInteraction,
-    SendInteractionParamsType,
-    SendInteractionReturnType,
-} from "./rpc/interaction";
-export type { IFrameRpcSchema } from "./rpc";
+
 // Client related
 export type { FrakClient } from "./client";
-export type { IFrameTransport, FrakLifecycleEvent } from "./transport";
 export type {
-    IFrameLifecycleEvent,
-    ClientLifecycleEvent,
-} from "./lifecycle";
+    CompressedData,
+    HashProtectedData,
+    KeyProvider,
+} from "./compression";
 export type {
-    FrakWalletSdkConfig,
     Currency,
-    Language,
+    FrakWalletSdkConfig,
     I18nConfig,
+    Language,
     LocalizedI18nConfig,
 } from "./config";
+// Utils
+export type { FrakContext } from "./context";
 export type {
-    CompressedData,
-    HashProtectedData,
-    KeyProvider,
-} from "./compression";
+    ClientLifecycleEvent,
+    IFrameLifecycleEvent,
+} from "./lifecycle";
+export type { IFrameRpcSchema } from "./rpc";
 // Modal related
 export type {
-    ModalStepTypes,
-    ModalRpcStepsInput,
-    ModalRpcStepsResultType,
     DisplayModalParamsType,
     ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
 } from "./rpc/displayModal";
 export type {
-    ModalStepMetadata,
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    LoggedInEmbeddedView,
+    LoggedOutEmbeddedView,
+} from "./rpc/embedded";
+export type {
+    PreparedInteraction,
+    SendInteractionParamsType,
+    SendInteractionReturnType,
+} from "./rpc/interaction";
+export type {
+    FinalActionType,
+    FinalModalStepType,
     LoginModalStepType,
-    SiweAuthenticateModalStepType,
-    SiweAuthenticationParams,
-    SiweAuthenticateReturnType,
-    SendTransactionTxType,
+    ModalStepMetadata,
+    OpenInteractionSessionModalStepType,
+    OpenInteractionSessionReturnType,
     SendTransactionModalStepType,
     SendTransactionReturnType,
-    OpenInteractionSessionReturnType,
-    OpenInteractionSessionModalStepType,
-    FinalModalStepType,
-    FinalActionType,
+    SendTransactionTxType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
 } from "./rpc/modal";
-// Utils
-export type { FrakContext } from "./context";
+export type {
+    GetProductInformationReturnType,
+    TokenAmountType,
+} from "./rpc/productInformation";
+export type {
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+    SsoMetadata,
+} from "./rpc/sso";
+export type { WalletStatusReturnType } from "./rpc/walletStatus";
+export type { FrakLifecycleEvent, IFrameTransport } from "./transport";

package/src/types/lifecycle/index.ts

@@ -1,2 +1,2 @@
-export type { IFrameLifecycleEvent } from "./iframe";
 export type { ClientLifecycleEvent } from "./client";
+export type { IFrameLifecycleEvent } from "./iframe";

package/src/types/rpc/embedded/loggedIn.ts

@@ -17,7 +17,7 @@ export type EmbeddedViewActionSharing = {
         popupTitle?: string;
         /**
          * The text that will be shared alongside the link.
-         * Can contain the variable {LINK} to specify where the link is placed, otherwise it will be added at the end
+         * Can contain the variable `{LINK}` to specify where the link is placed, otherwise it will be added at the end
          * @deprecated Use the top level `config.metadata.i18n` instead
          */
         text?: string;

package/src/types/rpc/embedded/loggedOut.ts

@@ -10,7 +10,7 @@ export type LoggedOutEmbeddedView = {
         /**
          * The main CTA for the logged out view
          *  - can include some variable, available ones are:
-         *      - {REWARD} -> The maximum reward a user can receive when interacting on your website
+         *      - `{REWARD}` -> The maximum reward a user can receive when interacting on your website
          *  - can be formatted in markdown
          *
          * If not set, it will default to a internationalized message

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

@@ -1,20 +1,20 @@
+export type {
+    FinalActionType,
+    FinalModalStepType,
+} from "./final";
+export type { ModalStepMetadata } from "./generic";
 export type { LoginModalStepType } from "./login";
+export type {
+    OpenInteractionSessionModalStepType,
+    OpenInteractionSessionReturnType,
+} from "./openSession";
 export type {
     SiweAuthenticateModalStepType,
-    SiweAuthenticationParams,
     SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
 } from "./siweAuthenticate";
 export type {
     SendTransactionModalStepType,
-    SendTransactionTxType,
     SendTransactionReturnType,
+    SendTransactionTxType,
 } from "./transaction";
-export type {
-    OpenInteractionSessionReturnType,
-    OpenInteractionSessionModalStepType,
-} from "./openSession";
-export type { ModalStepMetadata } from "./generic";
-export type {
-    FinalModalStepType,
-    FinalActionType,
-} from "./final";

package/src/utils/FrakContext.test.ts

@@ -0,0 +1,338 @@
+/**
+ * Tests for FrakContextManager utility
+ * Tests Frak context compression, URL parsing, and management
+ */
+
+import type { Address } from "viem";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
+import type { FrakContext } from "../types";
+import { FrakContextManager } from "./FrakContext";
+
+describe("FrakContextManager", () => {
+    let consoleErrorSpy: any;
+
+    beforeEach(() => {
+        consoleErrorSpy = vi
+            .spyOn(console, "error")
+            .mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleErrorSpy.mockRestore();
+    });
+
+    describe("compress", () => {
+        it("should compress context with referrer address", () => {
+            const context: Partial<FrakContext> = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.compress(context);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result?.length).toBeGreaterThan(0);
+            // Base64url should not contain +, /, or =
+            expect(result).not.toMatch(/[+/=]/);
+        });
+
+        it("should return undefined when context has no referrer", () => {
+            const context: Partial<FrakContext> = {};
+
+            const result = FrakContextManager.compress(context);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should return undefined when context is undefined", () => {
+            const result = FrakContextManager.compress(undefined);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should handle compression errors gracefully", () => {
+            const invalidContext = {
+                r: "invalid-address" as Address,
+            };
+
+            const result = FrakContextManager.compress(invalidContext);
+
+            expect(consoleErrorSpy).toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("decompress", () => {
+        it("should decompress valid base64url context", () => {
+            // First compress a context
+            const originalContext: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+            const compressed = FrakContextManager.compress(originalContext);
+
+            // Then decompress it
+            const result = FrakContextManager.decompress(compressed);
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return undefined for empty string", () => {
+            const result = FrakContextManager.decompress("");
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should return undefined for undefined input", () => {
+            const result = FrakContextManager.decompress(undefined);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should handle decompression errors gracefully", () => {
+            const result = FrakContextManager.decompress(
+                "invalid-base64url!@#"
+            );
+
+            expect(consoleErrorSpy).toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+
+        it("should round-trip compress and decompress", () => {
+            const original: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const compressed = FrakContextManager.compress(original);
+            const decompressed = FrakContextManager.decompress(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+    });
+
+    describe("parse", () => {
+        it("should parse URL with fCtx parameter", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0x1234567890123456789012345678901234567890"
+            );
+        });
+
+        it("should return null for URL without fCtx parameter", () => {
+            const url = "https://example.com?other=param";
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeNull();
+        });
+
+        it("should return null for empty URL", () => {
+            const result = FrakContextManager.parse({ url: "" });
+
+            expect(result).toBeNull();
+        });
+
+        it("should parse URL with multiple parameters", () => {
+            const context: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?foo=bar&fCtx=${compressed}&baz=qux`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return undefined for malformed fCtx parameter", () => {
+            // Use a string that will fail base64url decoding
+            const url = "https://example.com?fCtx=!!!invalid!!!";
+
+            const result = FrakContextManager.parse({ url });
+
+            // Should handle the error and return undefined
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("update", () => {
+        it("should add fCtx to URL without existing context", () => {
+            const url = "https://example.com";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toBeDefined();
+            expect(result).toContain("fCtx=");
+            expect(result).toContain("https://example.com");
+        });
+
+        it("should merge with existing context in URL", () => {
+            const existingContext: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(existingContext);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const newContext: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+
+            const result = FrakContextManager.update({
+                url,
+                context: newContext,
+            });
+
+            expect(result).toBeDefined();
+            expect(result).toContain("fCtx=");
+
+            // Parse the result and check it has the new referrer
+            const parsedResult = FrakContextManager.parse({ url: result! });
+            expect(parsedResult?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return null when URL is undefined", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({
+                url: undefined,
+                context,
+            });
+
+            expect(result).toBeNull();
+        });
+
+        it("should return null when context has no referrer", () => {
+            const url = "https://example.com";
+            const context: Partial<FrakContext> = {};
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toBeNull();
+        });
+
+        it("should preserve other URL parameters", () => {
+            const url = "https://example.com?foo=bar&baz=qux";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("foo=bar");
+            expect(result).toContain("baz=qux");
+            expect(result).toContain("fCtx=");
+        });
+
+        it("should preserve URL hash", () => {
+            const url = "https://example.com#section";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("#section");
+            expect(result).toContain("fCtx=");
+        });
+    });
+
+    describe("remove", () => {
+        it("should remove fCtx parameter from URL", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toBe("https://example.com/");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should preserve other parameters when removing fCtx", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?foo=bar&fCtx=${compressed}&baz=qux`;
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("foo=bar");
+            expect(result).toContain("baz=qux");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should handle URL without fCtx parameter", () => {
+            const url = "https://example.com?foo=bar";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("foo=bar");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should preserve URL hash", () => {
+            const url = "https://example.com?fCtx=test#section";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("#section");
+            expect(result).not.toContain("fCtx");
+        });
+    });
+
+    describe("replaceUrl", () => {
+        // Note: replaceUrl tests are skipped because window.location cannot be mocked
+        // in JSDOM environment. The function is primarily used for browser DOM manipulation
+        // and is tested through integration/E2E tests.
+
+        it.skip("should update window.location with context", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should use provided URL instead of window.location.href", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should remove fCtx when context is null", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should not call replaceState when context has no referrer", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should handle missing window gracefully", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+    });
+});

package/src/utils/FrakContext.ts

@@ -67,7 +67,10 @@ function parse({ url }: { url: string }) {
 function update({
     url,
     context,
-}: { url?: string; context: Partial<FrakContext> }) {
+}: {
+    url?: string;
+    context: Partial<FrakContext>;
+}) {
     if (!url) return null;
 
     // Parse the current context
@@ -111,7 +114,10 @@ function remove(url: string) {
 function replaceUrl({
     url: baseUrl,
     context,
-}: { url?: string; context: Partial<FrakContext> | null }) {
+}: {
+    url?: string;
+    context: Partial<FrakContext> | null;
+}) {
     // If no window here early exit
     if (!window.location?.href || typeof window === "undefined") {
         console.error("No window found, can't update context");