@carlonicora/nextjs-jsonapi 1.44.1 → 1.45.0

package/src/features/auth/data/auth.interface.ts

@@ -13,6 +13,7 @@ export type AuthInput = {
   marketingConsent?: boolean;
   marketingConsentAt?: string | null;
   inviteCode?: string;
+  referralCode?: string;
 };
 
 export type AuthQuery = {

package/src/features/auth/data/auth.ts

@@ -50,6 +50,7 @@ export class Auth extends AbstractApiData implements AuthInterface {
     if (data.marketingConsent !== undefined) response.data.attributes.marketingConsent = data.marketingConsent;
     if (data.marketingConsentAt !== undefined) response.data.attributes.marketingConsentAt = data.marketingConsentAt;
     if (data.inviteCode !== undefined) response.data.attributes.inviteCode = data.inviteCode;
+    if (data.referralCode !== undefined) response.data.attributes.referralCode = data.referralCode;
 
     return response;
   }

package/src/features/auth/utils/__tests__/clearClientStorage.spec.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { clearClientStorage } from "../clearClientStorage";
+
+describe("clearClientStorage", () => {
+  const originalWindow = global.window;
+
+  beforeEach(() => {
+    // Mock localStorage
+    const localStorageMock = {
+      removeItem: vi.fn(),
+      getItem: vi.fn(),
+      setItem: vi.fn(),
+      clear: vi.fn(),
+      length: 0,
+      key: vi.fn(),
+    };
+    Object.defineProperty(global, "window", {
+      value: { localStorage: localStorageMock },
+      writable: true,
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(global, "window", {
+      value: originalWindow,
+      writable: true,
+    });
+    vi.restoreAllMocks();
+  });
+
+  describe("Scenario: Clears specified storage keys", () => {
+    it("should remove each specified key from localStorage", () => {
+      const keys = ["user", "person", "recentPages"];
+
+      clearClientStorage(keys);
+
+      expect(window.localStorage.removeItem).toHaveBeenCalledTimes(3);
+      expect(window.localStorage.removeItem).toHaveBeenCalledWith("user");
+      expect(window.localStorage.removeItem).toHaveBeenCalledWith("person");
+      expect(window.localStorage.removeItem).toHaveBeenCalledWith("recentPages");
+    });
+  });
+
+  describe("Scenario: Handles empty key array gracefully", () => {
+    it("should not call removeItem when given empty array", () => {
+      clearClientStorage([]);
+
+      expect(window.localStorage.removeItem).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("Scenario: SSR-safe execution", () => {
+    it("should return early without error when window is undefined", () => {
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        writable: true,
+      });
+
+      expect(() => clearClientStorage(["user", "person"])).not.toThrow();
+    });
+  });
+
+  describe("Scenario: Handles keys with special characters", () => {
+    it("should properly remove keys containing colons", () => {
+      const keys = [
+        "react-resizable-panels:page-content-container-desktop:left-panel:right-panel",
+        "react-resizable-panels:page-content-container-mobile:left-panel:right-panel",
+      ];
+
+      clearClientStorage(keys);
+
+      expect(window.localStorage.removeItem).toHaveBeenCalledTimes(2);
+      expect(window.localStorage.removeItem).toHaveBeenCalledWith(
+        "react-resizable-panels:page-content-container-desktop:left-panel:right-panel",
+      );
+      expect(window.localStorage.removeItem).toHaveBeenCalledWith(
+        "react-resizable-panels:page-content-container-mobile:left-panel:right-panel",
+      );
+    });
+  });
+});

package/src/features/auth/utils/clearClientStorage.ts

@@ -0,0 +1,11 @@
+/**
+ * Clears specified keys from localStorage during logout.
+ * Called before redirect to ensure cleanup happens.
+ */
+export function clearClientStorage(keys: string[]): void {
+  if (typeof window === "undefined") return;
+
+  keys.forEach((key) => {
+    window.localStorage.removeItem(key);
+  });
+}

package/src/features/auth/utils/index.ts

@@ -1 +1,2 @@
 export * from "./AuthCookies";
+export * from "./clearClientStorage";

package/src/features/index.ts

@@ -20,3 +20,4 @@ export * from "./search";
 export * from "./user";
 export * from "./oauth";
 export * from "./waitlist";
+export * from "./referral";

package/src/features/referral/__tests__/config.spec.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { configureReferral, getReferralConfig, isReferralEnabled, DEFAULT_REFERRAL_CONFIG } from "../config";
+
+describe("Referral Configuration", () => {
+  beforeEach(() => {
+    // Reset to defaults before each test
+    configureReferral({});
+  });
+
+  describe("configureReferral()", () => {
+    it("should set config values correctly", () => {
+      configureReferral({
+        enabled: true,
+        cookieName: "my_referral",
+        cookieDays: 60,
+        urlParamName: "invite",
+        referralUrlBase: "https://example.com",
+        referralPath: "/signup",
+      });
+
+      const config = getReferralConfig();
+      expect(config.enabled).toBe(true);
+      expect(config.cookieName).toBe("my_referral");
+      expect(config.cookieDays).toBe(60);
+      expect(config.urlParamName).toBe("invite");
+      expect(config.referralUrlBase).toBe("https://example.com");
+      expect(config.referralPath).toBe("/signup");
+    });
+
+    it("should merge custom values with defaults", () => {
+      configureReferral({ enabled: true, cookieDays: 60 });
+
+      const config = getReferralConfig();
+      expect(config.enabled).toBe(true);
+      expect(config.cookieDays).toBe(60);
+      // Default values should be preserved
+      expect(config.cookieName).toBe(DEFAULT_REFERRAL_CONFIG.cookieName);
+      expect(config.urlParamName).toBe(DEFAULT_REFERRAL_CONFIG.urlParamName);
+      expect(config.referralPath).toBe(DEFAULT_REFERRAL_CONFIG.referralPath);
+    });
+
+    it("should overwrite previous configuration (singleton behavior)", () => {
+      configureReferral({ enabled: true, cookieDays: 60 });
+      configureReferral({ enabled: false, cookieName: "new_cookie" });
+
+      const config = getReferralConfig();
+      expect(config.enabled).toBe(false);
+      expect(config.cookieName).toBe("new_cookie");
+      // cookieDays should be reset to default
+      expect(config.cookieDays).toBe(DEFAULT_REFERRAL_CONFIG.cookieDays);
+    });
+  });
+
+  describe("isReferralEnabled()", () => {
+    it("should return false by default", () => {
+      expect(isReferralEnabled()).toBe(false);
+    });
+
+    it("should return true when enabled", () => {
+      configureReferral({ enabled: true });
+      expect(isReferralEnabled()).toBe(true);
+    });
+
+    it("should return false when explicitly disabled", () => {
+      configureReferral({ enabled: false });
+      expect(isReferralEnabled()).toBe(false);
+    });
+  });
+
+  describe("getReferralConfig()", () => {
+    it("should return default values before configure", () => {
+      const config = getReferralConfig();
+      expect(config.enabled).toBe(DEFAULT_REFERRAL_CONFIG.enabled);
+      expect(config.cookieName).toBe(DEFAULT_REFERRAL_CONFIG.cookieName);
+      expect(config.cookieDays).toBe(DEFAULT_REFERRAL_CONFIG.cookieDays);
+      expect(config.urlParamName).toBe(DEFAULT_REFERRAL_CONFIG.urlParamName);
+      expect(config.referralUrlBase).toBe(DEFAULT_REFERRAL_CONFIG.referralUrlBase);
+      expect(config.referralPath).toBe(DEFAULT_REFERRAL_CONFIG.referralPath);
+    });
+
+    it("should return custom values after configure", () => {
+      configureReferral({
+        enabled: true,
+        cookieName: "custom_cookie",
+        cookieDays: 45,
+      });
+
+      const config = getReferralConfig();
+      expect(config.enabled).toBe(true);
+      expect(config.cookieName).toBe("custom_cookie");
+      expect(config.cookieDays).toBe(45);
+    });
+  });
+
+  describe("DEFAULT_REFERRAL_CONFIG", () => {
+    it("should have expected default values", () => {
+      expect(DEFAULT_REFERRAL_CONFIG.enabled).toBe(false);
+      expect(DEFAULT_REFERRAL_CONFIG.cookieName).toBe("referral_code");
+      expect(DEFAULT_REFERRAL_CONFIG.cookieDays).toBe(30);
+      expect(DEFAULT_REFERRAL_CONFIG.urlParamName).toBe("ref");
+      expect(DEFAULT_REFERRAL_CONFIG.referralUrlBase).toBe("");
+      expect(DEFAULT_REFERRAL_CONFIG.referralPath).toBe("/");
+    });
+  });
+});

package/src/features/referral/__tests__/referral-cookie.spec.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { configureReferral, DEFAULT_REFERRAL_CONFIG } from "../config";
+import { setReferralCode, getReferralCode, clearReferralCode } from "../utils/referral-cookie";
+
+describe("Referral Cookie Utilities", () => {
+  let cookieStore: Record<string, string> = {};
+  let documentCookieDescriptor: PropertyDescriptor | undefined;
+
+  beforeEach(() => {
+    // Reset configuration to defaults
+    configureReferral({});
+    cookieStore = {};
+
+    // Save original cookie descriptor
+    documentCookieDescriptor = Object.getOwnPropertyDescriptor(Document.prototype, "cookie");
+
+    // Mock document.cookie
+    Object.defineProperty(document, "cookie", {
+      get: () => {
+        return Object.entries(cookieStore)
+          .map(([name, value]) => `${name}=${value}`)
+          .join("; ");
+      },
+      set: (cookieString: string) => {
+        // Parse the cookie string
+        const parts = cookieString.split(";");
+        const [nameValue] = parts;
+        const [name, value] = nameValue.split("=");
+
+        // Check for max-age=0 (deletion)
+        const maxAgeMatch = cookieString.match(/max-age=(\d+)/i);
+        if (maxAgeMatch && maxAgeMatch[1] === "0") {
+          delete cookieStore[name.trim()];
+        } else if (value !== undefined) {
+          cookieStore[name.trim()] = value;
+        }
+      },
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    // Restore original cookie descriptor
+    if (documentCookieDescriptor) {
+      Object.defineProperty(Document.prototype, "cookie", documentCookieDescriptor);
+    }
+    vi.restoreAllMocks();
+  });
+
+  describe("setReferralCode()", () => {
+    it("should set cookie with configured name", () => {
+      setReferralCode("test-code-123");
+      expect(cookieStore["referral_code"]).toBe("test-code-123");
+    });
+
+    it("should use custom cookie name when configured", () => {
+      configureReferral({ cookieName: "my_ref_code" });
+      setReferralCode("custom-code");
+      expect(cookieStore["my_ref_code"]).toBe("custom-code");
+    });
+
+    it("should URL encode the referral code", () => {
+      setReferralCode("code with spaces & special=chars");
+      expect(cookieStore["referral_code"]).toBe("code%20with%20spaces%20%26%20special%3Dchars");
+    });
+
+    it("should set cookie with configured duration in max-age", () => {
+      const setCookieSpy = vi.spyOn(document, "cookie", "set");
+      configureReferral({ cookieDays: 60 });
+
+      setReferralCode("test-code");
+
+      const expectedMaxAge = 60 * 24 * 60 * 60; // 60 days in seconds
+      expect(setCookieSpy).toHaveBeenCalledWith(expect.stringContaining(`max-age=${expectedMaxAge}`));
+    });
+
+    it("should use default 30 day duration", () => {
+      const setCookieSpy = vi.spyOn(document, "cookie", "set");
+      setReferralCode("test-code");
+
+      const expectedMaxAge = 30 * 24 * 60 * 60; // 30 days in seconds
+      expect(setCookieSpy).toHaveBeenCalledWith(expect.stringContaining(`max-age=${expectedMaxAge}`));
+    });
+
+    it("should set path to root and SameSite=Lax", () => {
+      const setCookieSpy = vi.spyOn(document, "cookie", "set");
+      setReferralCode("test-code");
+
+      expect(setCookieSpy).toHaveBeenCalledWith(expect.stringContaining("path=/"));
+      expect(setCookieSpy).toHaveBeenCalledWith(expect.stringContaining("SameSite=Lax"));
+    });
+  });
+
+  describe("getReferralCode()", () => {
+    it("should return stored value", () => {
+      cookieStore["referral_code"] = "stored-code";
+      expect(getReferralCode()).toBe("stored-code");
+    });
+
+    it("should return null when no cookie exists", () => {
+      expect(getReferralCode()).toBeNull();
+    });
+
+    it("should use custom cookie name when configured", () => {
+      configureReferral({ cookieName: "my_ref_code" });
+      cookieStore["my_ref_code"] = "custom-stored-code";
+      expect(getReferralCode()).toBe("custom-stored-code");
+    });
+
+    it("should not return value from wrong cookie name", () => {
+      configureReferral({ cookieName: "my_ref_code" });
+      cookieStore["referral_code"] = "wrong-cookie";
+      expect(getReferralCode()).toBeNull();
+    });
+
+    it("should URL decode the referral code", () => {
+      cookieStore["referral_code"] = "code%20with%20spaces%20%26%20special%3Dchars";
+      expect(getReferralCode()).toBe("code with spaces & special=chars");
+    });
+
+    it("should return null when cookie value is empty", () => {
+      cookieStore["referral_code"] = "";
+      expect(getReferralCode()).toBeNull();
+    });
+  });
+
+  describe("clearReferralCode()", () => {
+    it("should remove the cookie", () => {
+      cookieStore["referral_code"] = "existing-code";
+      clearReferralCode();
+      expect(cookieStore["referral_code"]).toBeUndefined();
+    });
+
+    it("should use configured cookie name for clearing", () => {
+      configureReferral({ cookieName: "my_ref_code" });
+      cookieStore["my_ref_code"] = "existing-code";
+      clearReferralCode();
+      expect(cookieStore["my_ref_code"]).toBeUndefined();
+    });
+
+    it("should set max-age to 0 for deletion", () => {
+      const setCookieSpy = vi.spyOn(document, "cookie", "set");
+      clearReferralCode();
+      expect(setCookieSpy).toHaveBeenCalledWith(expect.stringContaining("max-age=0"));
+    });
+
+    it("should handle clearing non-existent cookie gracefully", () => {
+      // Should not throw
+      expect(() => clearReferralCode()).not.toThrow();
+    });
+  });
+
+  describe("Integration scenarios", () => {
+    it("should set and get referral code correctly", () => {
+      setReferralCode("integration-test-code");
+      expect(getReferralCode()).toBe("integration-test-code");
+    });
+
+    it("should set, get, and clear referral code correctly", () => {
+      setReferralCode("to-be-cleared");
+      expect(getReferralCode()).toBe("to-be-cleared");
+
+      clearReferralCode();
+      expect(getReferralCode()).toBeNull();
+    });
+
+    it("should overwrite existing referral code", () => {
+      setReferralCode("first-code");
+      expect(getReferralCode()).toBe("first-code");
+
+      setReferralCode("second-code");
+      expect(getReferralCode()).toBe("second-code");
+    });
+
+    it("should work with different configurations", () => {
+      configureReferral({
+        cookieName: "custom_ref",
+        cookieDays: 7,
+      });
+
+      setReferralCode("custom-config-code");
+      expect(getReferralCode()).toBe("custom-config-code");
+
+      clearReferralCode();
+      expect(getReferralCode()).toBeNull();
+    });
+  });
+});

package/src/features/referral/components/ReferralCodeCapture.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { useSearchParams } from "next/navigation";
+import { useEffect } from "react";
+
+import { getReferralConfig, isReferralEnabled } from "../config";
+import { getReferralCode, setReferralCode } from "../utils/referral-cookie";
+
+/**
+ * ReferralCodeCapture captures referral codes from URL parameters.
+ *
+ * Behavior:
+ * - Checks if referral feature is enabled before processing
+ * - Reads the configured query param (default "ref") from the URL
+ * - Checks if a referral cookie already exists
+ * - If ref param is present AND no existing cookie, sets the cookie (first referrer wins)
+ * - Renders nothing (null) - component only captures the code
+ */
+export function ReferralCodeCapture(): null {
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    console.log("[REFERRAL] ReferralCodeCapture mounted");
+    console.log("[REFERRAL] isReferralEnabled():", isReferralEnabled());
+
+    // Skip if feature is disabled
+    if (!isReferralEnabled()) {
+      console.log("[REFERRAL] Feature DISABLED - not capturing");
+      return;
+    }
+
+    const config = getReferralConfig();
+    const refCode = searchParams.get(config.urlParamName);
+    console.log("[REFERRAL] URL param '" + config.urlParamName + "':", refCode);
+
+    if (refCode) {
+      const existingCode = getReferralCode();
+      console.log("[REFERRAL] Existing cookie:", existingCode);
+
+      // First referrer wins - only set if no existing cookie
+      if (!existingCode) {
+        setReferralCode(refCode);
+        console.log("[REFERRAL] Cookie SET to:", refCode);
+      } else {
+        console.log("[REFERRAL] Cookie already exists, not overwriting");
+      }
+    }
+  }, [searchParams]);
+
+  return null;
+}

package/src/features/referral/components/ReferralDialog.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from "../../../shadcnui";
+import { isReferralEnabled } from "../config";
+import { ReferralWidget, ReferralWidgetProps, ReferralWidgetTranslations } from "./ReferralWidget";
+
+/**
+ * Translation strings for the ReferralDialog component.
+ * Extends ReferralWidgetTranslations with dialog-specific strings.
+ */
+export interface ReferralDialogTranslations extends ReferralWidgetTranslations {
+  /** Dialog title */
+  dialogTitle?: string;
+  /** Dialog description */
+  dialogDescription?: string;
+}
+
+/**
+ * Default translations for ReferralDialog.
+ */
+const DEFAULT_DIALOG_TRANSLATIONS: Required<Pick<ReferralDialogTranslations, "dialogTitle" | "dialogDescription">> = {
+  dialogTitle: "Invite Friends",
+  dialogDescription: "Share your referral link and earn rewards when your friends subscribe.",
+};
+
+/**
+ * Props for the ReferralDialog component.
+ */
+export interface ReferralDialogProps extends Omit<ReferralWidgetProps, "isDialog" | "translations"> {
+  /** Whether the dialog is open */
+  open: boolean;
+  /** Callback when the dialog open state changes */
+  onOpenChange: (open: boolean) => void;
+  /** Custom translations to override defaults */
+  translations?: ReferralDialogTranslations;
+  /** Additional CSS class name for the dialog content */
+  dialogClassName?: string;
+}
+
+/**
+ * ReferralDialog displays the ReferralWidget in a modal dialog.
+ *
+ * Features:
+ * - Feature flag awareness (renders null when disabled)
+ * - Uses shadcn Dialog components
+ * - Passes through all ReferralWidget props
+ * - Customizable translations including dialog-specific text
+ *
+ * @example
+ * ```tsx
+ * import { ReferralDialog } from "@carlonicora/nextjs-jsonapi/components";
+ *
+ * // Basic usage
+ * const [open, setOpen] = useState(false);
+ * <ReferralDialog open={open} onOpenChange={setOpen} />
+ *
+ * // With custom translations
+ * <ReferralDialog
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   translations={{
+ *     dialogTitle: t("referral.title"),
+ *     dialogDescription: t("referral.description"),
+ *     yourLink: t("referral.yourLink"),
+ *   }}
+ * />
+ * ```
+ */
+export function ReferralDialog({
+  open,
+  onOpenChange,
+  translations,
+  dialogClassName,
+  ...widgetProps
+}: ReferralDialogProps) {
+  // Render nothing when disabled
+  if (!isReferralEnabled()) {
+    return null;
+  }
+
+  const t = { ...DEFAULT_DIALOG_TRANSLATIONS, ...translations };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className={dialogClassName ?? "max-w-md"}>
+        <DialogHeader>
+          <DialogTitle>{t.dialogTitle}</DialogTitle>
+          <DialogDescription>{t.dialogDescription}</DialogDescription>
+        </DialogHeader>
+        <ReferralWidget {...widgetProps} translations={translations} isDialog />
+      </DialogContent>
+    </Dialog>
+  );
+}