@carlonicora/nextjs-jsonapi 6.10.2 → 6.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "6.10.2",
+  "version": "6.12.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -143,7 +143,8 @@
     "next-intl": ">=4.0.0",
     "react": ">=19.3.0",
     "react-dom": ">=19.3.0",
-    "react-hook-form": ">=7.0.0"
+    "react-hook-form": ">=7.0.0",
+    "yjs": "^13.6.33"
   },
   "peerDependenciesMeta": {
     "@stripe/react-stripe-js": {
@@ -163,6 +164,9 @@
     },
     "react-hook-form": {
       "optional": true
+    },
+    "yjs": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -264,7 +268,8 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.3",
+    "yjs": "^13.6.33"
   },
   "keywords": [
     "nextjs",

package/src/components/editors/BlockNoteEditor.tsx

@@ -42,6 +42,7 @@ import { BlockNoteDiffUtil, BlockNoteWordDiffRendererUtil, cn } from "../../util
 import { errorToast } from "../errors";
 import { BlockNoteAiGenerateAction, generateActionItems } from "./BlockNoteEditorAiActions";
 import { BlockNoteEditorFormattingToolbar } from "./BlockNoteEditorFormattingToolbar";
+import { type BlockNoteCollaboration, buildBlockNoteEditorOptions, resolveEditable } from "./blockNoteEditorOptions";
 import { BlockNoteEditorMentionHoverCard } from "./BlockNoteEditorMentionHoverCard";
 import {
   createMentionInlineContentSpec,
@@ -115,6 +116,19 @@ export type BlockNoteEditorProps = {
   // is on, so a control outside the editor can run a whole-document AI action.
   // Cleared on unmount and whenever AI is unavailable.
   aiHandleRef?: React.MutableRefObject<BlockNoteAiHandle | null>;
+  /**
+   * Live co-editing (Yjs). When set, the Yjs document is the content: used
+   * instead of `initialContent`/`onChange`. Changing `collaboration.fragment`
+   * rebuilds the editor.
+   */
+  collaboration?: BlockNoteCollaboration;
+  /** true: image uploads are off (no paste/drop upload, no upload tab). */
+  disableUploads?: boolean;
+  /**
+   * Overrides the default `onChange !== undefined` editability, e.g. for a
+   * collaborative editor, which has no `onChange`.
+   */
+  editable?: boolean;
 };
 
 function isBlockEmpty(block: any): boolean {
@@ -429,7 +443,11 @@ export default function BlockNoteEditor({
   stretch,
   aiEnabled = true,
   aiHandleRef,
+  collaboration,
+  disableUploads,
+  editable,
 }: BlockNoteEditorProps): React.JSX.Element {
+  const isEditable = resolveEditable({ editable, onChange });
   const t = useTranslations();
   const locale = useI18nLocale();
   const { resolvedTheme } = useTheme();
@@ -700,21 +718,30 @@ export default function BlockNoteEditor({
 
   const editor = useCreateBlockNote(
     useMemo(
-      () => ({
-        placeholders: {
-          emptyDocument: placeholder || t(`common.blocknote.placeholder`),
-        },
+      () =>
+        buildBlockNoteEditorOptions({
+          placeholder: placeholder || t(`common.blocknote.placeholder`),
+          schema,
+          initialContent: validatedInitialContent,
+          uploadFile: uploadImage,
+          disableUploads,
+          aiExtension,
+          coreDictionary,
+          aiDictionary,
+          collaboration,
+        }),
+      [
+        placeholder,
+        t,
         schema,
-        initialContent: validatedInitialContent,
-        uploadFile: uploadImage,
-        extensions: aiExtension ? [aiExtension] : undefined,
-        dictionary: aiExtension
-          ? { ...coreDictionary, ai: aiDictionary }
-          : coreDictionary === coreLocales.en
-            ? undefined
-            : coreDictionary,
-      }),
-      [placeholder, t, schema, validatedInitialContent, uploadImage, aiExtension, coreDictionary, aiDictionary],
+        validatedInitialContent,
+        uploadImage,
+        disableUploads,
+        aiExtension,
+        coreDictionary,
+        aiDictionary,
+        collaboration,
+      ],
     ),
     // useCreateBlockNote memoises on THIS list, not on the options' identity
     // (@blocknote/react: useMemo(() => BlockNoteEditor.create(options), deps),
@@ -723,7 +750,8 @@ export default function BlockNoteEditor({
     // rendered the AI UI over an editor with no AIExtension, and BlockNote's
     // useExtension threw "Extension not found". The other options keep their
     // first-render values, as before. `aiEnabled` is deliberately not here.
-    [aiExtension],
+    // A new Yjs fragment (another document) needs a new editor bound to it.
+    [aiExtension, collaboration?.fragment],
   );
 
   // Every AI surface keys off the editor actually rendered, never off the
@@ -878,6 +906,10 @@ export default function BlockNoteEditor({
   const previousContentHashRef = useRef<string | null>(null);
   useEffect(() => {
     if (!processedContent || !editor) return;
+    // A collaborative editor's content IS the shared Yjs document: it has no initialContent,
+    // so processedContent is [] and replaceBlocks would wipe the document it just loaded,
+    // and that wipe would be synced to every other writer and stored.
+    if (collaboration) return;
     const hash = JSON.stringify(processedContent);
     if (previousContentHashRef.current === hash) return; // no changes
     // Skip replaceBlocks when the new initialContent is just an echo of what
@@ -896,7 +928,7 @@ export default function BlockNoteEditor({
     }
     editor.replaceBlocks(editor.document, processedContent as PartialBlock[]);
     previousContentHashRef.current = hash;
-  }, [processedContent, editor]);
+  }, [processedContent, editor, collaboration]);
 
   useEffect(() => {
     if (!onWarmMentions || !initialContent || !Array.isArray(initialContent) || initialContent.length === 0) return;
@@ -956,7 +988,7 @@ export default function BlockNoteEditor({
         // Phone: an editable field types at 16px, or iPhone Safari zooms the
         // page in on focus. The two ranges never overlap, so neither depends on
         // CSS source order to win.
-        onChange
+        isEditable
           ? "md:[&_.bn-default-styles]:!text-sm max-md:[&_.bn-default-styles]:!text-base"
           : "[&_.bn-default-styles]:!text-sm",
         className,
@@ -965,7 +997,7 @@ export default function BlockNoteEditor({
       <BlockNoteView
         editor={editor}
         onChange={handleChange}
-        editable={onChange !== undefined}
+        editable={isEditable}
         formattingToolbar={false}
         slashMenu={!aiActive}
         // Follow the app theme: hardcoding "light" leaves dark (light-theme)
@@ -977,13 +1009,13 @@ export default function BlockNoteEditor({
         // element and produce a phantom scrollbar on the wrapper.
         className={cn(
           "BlockNoteView flex-1",
-          onChange && "[&.bn-container]:p-4",
+          isEditable && "[&.bn-container]:p-4",
           // In stretch mode the parent chain caps our height via flex; without
           // these two classes the `.bn-container` keeps `min-height: auto`
           // (its content's intrinsic height) and pushes the bordered wrapper
           // — and the surrounding EditorSheet form — to scroll instead of
           // scrolling internally.
-          onChange && stretch && "[&.bn-container]:min-h-0 [&.bn-container]:overflow-y-auto",
+          isEditable && stretch && "[&.bn-container]:min-h-0 [&.bn-container]:overflow-y-auto",
           // Phone — these reach the floating menus because BlockNote puts this
           // className on its portal root too. The formatting toolbar (~450px)
           // scrolls sideways instead of losing alignment and link off-screen;

package/src/components/editors/__tests__/blocknote-editor-options.spec.ts

@@ -0,0 +1,81 @@
+import * as coreLocales from "@blocknote/core/locales";
+import { describe, expect, it, vi } from "vitest";
+import * as Y from "yjs";
+import { buildBlockNoteEditorOptions, resolveEditable } from "../blockNoteEditorOptions";
+
+const content = [{ type: "paragraph", content: "hello" }] as any;
+const baseParams = () => ({
+  placeholder: "Write here",
+  schema: { schema: true } as any,
+  initialContent: content,
+  uploadFile: vi.fn(async () => "https://s3/image.png"),
+  aiExtension: undefined,
+  coreDictionary: coreLocales.en,
+  aiDictionary: {} as any,
+});
+
+describe("buildBlockNoteEditorOptions", () => {
+  it("without collaboration: passes the validated content and sets no collaboration", () => {
+    const options = buildBlockNoteEditorOptions(baseParams());
+    expect(options.initialContent).toBe(content);
+    expect("collaboration" in options).toBe(false);
+    expect(options.extensions).toBeUndefined();
+    expect(options.disableExtensions).toBeUndefined();
+    expect(options.placeholders).toEqual({ emptyDocument: "Write here" });
+    expect(options.dictionary).toBeUndefined();
+  });
+
+  it("with collaboration: the Yjs document is the content, never the validated content", () => {
+    const doc = new Y.Doc();
+    const collaboration = { fragment: doc.getXmlFragment("document-store"), user: { name: "Ann", color: "#f00" } };
+    const options = buildBlockNoteEditorOptions({ ...baseParams(), collaboration });
+    expect((options as any).collaboration).toBe(collaboration);
+    expect(options.initialContent).not.toBe(content);
+    // BlockNote's fixed single-block placeholder for collaborative documents.
+    expect(options.initialContent).toEqual([{ type: "paragraph", id: "initialBlockId" }]);
+    expect(options.extensions).toHaveLength(1);
+    expect(options.disableExtensions).toContain("history");
+  });
+
+  it("with collaboration and AI: keeps the AI extension next to the collaboration one", () => {
+    const doc = new Y.Doc();
+    const aiExtension = { ai: true } as any;
+    const collaboration = { fragment: doc.getXmlFragment("document-store"), user: { name: "Ann", color: "#f00" } };
+    const options = buildBlockNoteEditorOptions({ ...baseParams(), aiExtension, collaboration });
+    expect(options.extensions).toHaveLength(2);
+    expect(options.extensions![0]).toBe(aiExtension);
+  });
+
+  it("disableUploads: true leaves uploadFile undefined", () => {
+    const options = buildBlockNoteEditorOptions({ ...baseParams(), disableUploads: true });
+    expect(options.uploadFile).toBeUndefined();
+  });
+
+  it("uploads on by default: uploadFile is the upload function", () => {
+    const params = baseParams();
+    expect(buildBlockNoteEditorOptions(params).uploadFile).toBe(params.uploadFile);
+    expect(buildBlockNoteEditorOptions({ ...params, disableUploads: false }).uploadFile).toBe(params.uploadFile);
+  });
+
+  it("keeps today's dictionary rule: AI adds the AI dictionary, a non-English core dictionary is passed", () => {
+    const aiExtension = { ai: true } as any;
+    const aiDictionary = { ai: "dict" } as any;
+    const withAi = buildBlockNoteEditorOptions({ ...baseParams(), aiExtension, aiDictionary });
+    expect(withAi.extensions).toEqual([aiExtension]);
+    expect(withAi.dictionary).toEqual({ ...coreLocales.en, ai: aiDictionary });
+    const italian = buildBlockNoteEditorOptions({ ...baseParams(), coreDictionary: coreLocales.it });
+    expect(italian.dictionary).toBe(coreLocales.it);
+  });
+});
+
+describe("resolveEditable", () => {
+  it("editable wins when defined", () => {
+    expect(resolveEditable({ editable: true, onChange: undefined })).toBe(true);
+    expect(resolveEditable({ editable: false, onChange: () => {} })).toBe(false);
+  });
+
+  it("falls back to onChange !== undefined", () => {
+    expect(resolveEditable({ editable: undefined, onChange: () => {} })).toBe(true);
+    expect(resolveEditable({ editable: undefined, onChange: undefined })).toBe(false);
+  });
+});

package/src/components/editors/blockNoteEditorOptions.ts

@@ -0,0 +1,58 @@
+import type { BlockNoteEditorOptions, PartialBlock } from "@blocknote/core";
+import * as coreLocales from "@blocknote/core/locales";
+import { type CollaborationOptions, withCollaboration } from "@blocknote/core/yjs";
+
+/**
+ * Live co-editing options for the shared editor: `{ fragment, user: { name, color }, provider?, showCursorLabels? }`.
+ * BlockNote 0.55 no longer reads `collaboration` from the editor options; it is applied through
+ * `withCollaboration()` from `@blocknote/core/yjs`, which this module does.
+ */
+export type BlockNoteCollaboration = CollaborationOptions;
+
+export type BuildBlockNoteEditorOptionsParams = {
+  placeholder: string;
+  schema: any;
+  /** The validated initial content. Ignored when `collaboration` is set: the Yjs document is the content. */
+  initialContent: PartialBlock[] | undefined;
+  uploadFile: (file: File) => Promise<string>;
+  /** true: no image uploads (no `uploadFile`, so BlockNote offers no upload). */
+  disableUploads?: boolean;
+  aiExtension: any;
+  coreDictionary: typeof coreLocales.en;
+  aiDictionary: any;
+  collaboration?: BlockNoteCollaboration;
+};
+
+/**
+ * The options handed to `useCreateBlockNote`. Without `collaboration` they are exactly the options the
+ * editor has always built; with it, BlockNote's `withCollaboration` adds the collaboration extension,
+ * disables the local history (Yjs owns undo) and replaces `initialContent` with its fixed placeholder.
+ */
+export function buildBlockNoteEditorOptions(
+  params: BuildBlockNoteEditorOptionsParams,
+): Partial<BlockNoteEditorOptions<any, any, any>> {
+  const { aiExtension, coreDictionary, aiDictionary, collaboration } = params;
+
+  const options: Partial<BlockNoteEditorOptions<any, any, any>> = {
+    placeholders: {
+      emptyDocument: params.placeholder,
+    },
+    schema: params.schema,
+    uploadFile: params.disableUploads ? undefined : params.uploadFile,
+    extensions: aiExtension ? [aiExtension] : undefined,
+    dictionary: aiExtension
+      ? { ...coreDictionary, ai: aiDictionary }
+      : coreDictionary === coreLocales.en
+        ? undefined
+        : coreDictionary,
+  };
+
+  if (collaboration) return withCollaboration({ ...options, collaboration });
+
+  return { ...options, initialContent: params.initialContent };
+}
+
+/** An explicit `editable` wins; otherwise the editor is editable when it reports changes. */
+export function resolveEditable(params: { editable?: boolean; onChange?: unknown }): boolean {
+  return params.editable !== undefined ? params.editable : params.onChange !== undefined;
+}

package/src/core/index.ts

@@ -129,6 +129,8 @@ export * from "../features/rbac/rbac.module";
 export * from "../features/referral/data";
 export * from "../features/referral/referral.module";
 export * from "../features/referral/referral-stats.module";
+export * from "../features/referral/referral-admin.modules";
+export * from "../features/referral/interfaces/referral-admin.interface";
 // Administrative token-usage reporting modules. Exported from core (not only
 // from the client-marked ./tokenusage barrel) so a consuming app can register
 // them in its bootstrapper without pulling the feature's client bundle —

package/src/core/registry/ModuleRegistry.ts

@@ -62,6 +62,11 @@ export interface FoundationModuleDefinitions {
   // Referral modules
   Referral: ModuleWithPermissions;
   ReferralStats: ModuleWithPermissions;
+  // Referral link visits and the administrative referral report (opt-in: registered by apps that spread referralAdminModules)
+  ReferralVisit: ModuleWithPermissions;
+  ReferralAdminSummary: ModuleWithPermissions;
+  ReferralAdminReferrer: ModuleWithPermissions;
+  ReferralAdminReferral: ModuleWithPermissions;
   // Two-factor authentication modules
   TotpAuthenticator: ModuleWithPermissions;
   TotpSetup: ModuleWithPermissions;

package/src/features/referral/__tests__/referral-admin-models.spec.ts

@@ -0,0 +1,122 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import { ReferralAdminReferral } from "../data/ReferralAdminReferral";
+import { ReferralAdminReferrer } from "../data/ReferralAdminReferrer";
+import { ReferralAdminSummary } from "../data/ReferralAdminSummary";
+import { referralAdminModules } from "../referral-admin.modules";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+// ModuleRegistry is shared across test files in a worker, hence the
+// register-if-absent guard (same idiom as the analytics models spec).
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  for (const [key, module] of Object.entries(referralAdminModules(moduleFactory))) registerIfAbsent(key, module);
+});
+
+const hydrate = (id: string, attributes: Record<string, unknown>) =>
+  ({ jsonApi: { id, type: "t", attributes }, included: [] }) as any;
+
+describe("referral admin models — rehydrate", () => {
+  it("rehydrates every summary attribute", () => {
+    const m = new ReferralAdminSummary().rehydrate(
+      hydrate("current", {
+        window: "current",
+        visits: 12,
+        invitesSent: 8,
+        signups: 3,
+        paying: 2,
+        creditsGiven: 800,
+        sharingCompanies: 4,
+        eligibleCompanies: 40,
+      }),
+    );
+    expect(m.id).toBe("current");
+    expect(m.window).toBe("current");
+    expect(m.visits).toBe(12);
+    expect(m.invitesSent).toBe(8);
+    expect(m.signups).toBe(3);
+    expect(m.paying).toBe(2);
+    expect(m.creditsGiven).toBe(800);
+    expect(m.sharingCompanies).toBe(4);
+    expect(m.eligibleCompanies).toBe(40);
+  });
+
+  it("rehydrates every referrer attribute and parses lastInviteAt into a Date", () => {
+    const m = new ReferralAdminReferrer().rehydrate(
+      hydrate("c1", {
+        name: "Luca",
+        email: "luca@x.test",
+        visits: 5,
+        invitesSent: 4,
+        signupsLink: 2,
+        signupsDirect: 1,
+        paying: 1,
+        creditsEarned: 200,
+        lastInviteAt: "2026-10-27T10:00:00.000Z",
+      }),
+    );
+    expect(m.id).toBe("c1");
+    expect(m.name).toBe("Luca");
+    expect(m.email).toBe("luca@x.test");
+    expect(m.visits).toBe(5);
+    expect(m.invitesSent).toBe(4);
+    expect(m.signupsLink).toBe(2);
+    expect(m.signupsDirect).toBe(1);
+    expect(m.paying).toBe(1);
+    expect(m.creditsEarned).toBe(200);
+    expect(m.lastInviteAt).toBeInstanceOf(Date);
+    expect(m.lastInviteAt?.toISOString()).toBe("2026-10-27T10:00:00.000Z");
+  });
+
+  it("leaves a missing lastInviteAt undefined", () => {
+    const m = new ReferralAdminReferrer().rehydrate(hydrate("c2", { name: "Sara", email: "sara@x.test" }));
+    expect(m.lastInviteAt).toBeUndefined();
+  });
+
+  it("rehydrates every referral attribute and parses the datetimes into Dates", () => {
+    const m = new ReferralAdminReferral().rehydrate(
+      hydrate("r1", {
+        name: "Marta",
+        email: "marta@x.test",
+        referrerName: "Luca",
+        referrerEmail: "luca@x.test",
+        source: "link",
+        status: "completed",
+        referredAt: "2026-10-20T08:00:00.000Z",
+        completedAt: "2026-10-27T08:00:00.000Z",
+        tokensAwarded: 200,
+      }),
+    );
+    expect(m.id).toBe("r1");
+    expect(m.name).toBe("Marta");
+    expect(m.email).toBe("marta@x.test");
+    expect(m.referrerName).toBe("Luca");
+    expect(m.referrerEmail).toBe("luca@x.test");
+    expect(m.source).toBe("link");
+    expect(m.status).toBe("completed");
+    expect(m.referredAt).toBeInstanceOf(Date);
+    expect(m.referredAt.toISOString()).toBe("2026-10-20T08:00:00.000Z");
+    expect(m.completedAt).toBeInstanceOf(Date);
+    expect(m.completedAt?.toISOString()).toBe("2026-10-27T08:00:00.000Z");
+    expect(m.tokensAwarded).toBe(200);
+  });
+
+  it("leaves a missing completedAt and tokensAwarded undefined", () => {
+    const m = new ReferralAdminReferral().rehydrate(
+      hydrate("r2", { name: "Tom", status: "pending", source: "direct", referredAt: "2026-10-24T08:00:00.000Z" }),
+    );
+    expect(m.completedAt).toBeUndefined();
+    expect(m.tokensAwarded).toBeUndefined();
+  });
+});

package/src/features/referral/__tests__/referral-admin-service.spec.ts

@@ -0,0 +1,70 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { AbstractService } from "../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import { ReferralAdminService } from "../data/ReferralAdminService";
+import { referralAdminModules } from "../referral-admin.modules";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  for (const [key, module] of Object.entries(referralAdminModules(moduleFactory))) registerIfAbsent(key, module);
+});
+
+type CallApiParams = { type: ApiRequestDataTypeInterface; method: string; endpoint: string };
+
+// `callApi` is a protected static on AbstractService; spying on the base class
+// intercepts every call without touching the HTTP layer.
+const callApi = () => vi.spyOn(AbstractService as any, "callApi").mockResolvedValue([]);
+const firstCall = (spy: ReturnType<typeof callApi>): CallApiParams => spy.mock.calls[0][0] as CallApiParams;
+
+describe("ReferralAdminService", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("getSummary sends the period to the summary endpoint", async () => {
+    const spy = callApi();
+
+    await ReferralAdminService.getSummary({ period: "30d" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("ReferralAdminSummary" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toContain("referrals/administration/summary");
+    expect(call.endpoint).toContain("period=30d");
+  });
+
+  it("getReferrers sends the period and the sort", async () => {
+    const spy = callApi();
+
+    await ReferralAdminService.getReferrers({ period: "90d", sort: "invites" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("ReferralAdminReferrer" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toContain("referrals/administration/referrers");
+    expect(call.endpoint).toContain("period=90d");
+    expect(call.endpoint).toContain("sort=invites");
+  });
+
+  it("getReferrals sends the period", async () => {
+    const spy = callApi();
+
+    await ReferralAdminService.getReferrals({ period: "all" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("ReferralAdminReferral" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toContain("referrals/administration/referrals");
+    expect(call.endpoint).toContain("period=all");
+  });
+});

package/src/features/referral/__tests__/referral-code-capture.spec.tsx

@@ -0,0 +1,105 @@
+import { act, render } from "@testing-library/react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+
+const REF = "11111111-1111-4111-8111-111111111111";
+
+const mocks = vi.hoisted(() => ({
+  searchParams: new URLSearchParams(),
+  enabled: true,
+  existingCode: null as string | null,
+  setReferralCode: vi.fn(),
+  recordVisit: vi.fn(),
+}));
+
+vi.mock("next/navigation", () => ({ useSearchParams: () => mocks.searchParams }));
+vi.mock("../config", () => ({
+  isReferralEnabled: () => mocks.enabled,
+  getReferralConfig: () => ({ urlParamName: "ref" }),
+}));
+vi.mock("../utils/referral-cookie", () => ({
+  getReferralCode: () => mocks.existingCode,
+  setReferralCode: mocks.setReferralCode,
+}));
+vi.mock("../data/ReferralService", () => ({ ReferralService: { recordVisit: mocks.recordVisit } }));
+
+import { ReferralCodeCapture } from "../components/ReferralCodeCapture";
+import { ReferralVisit } from "../data/ReferralVisit";
+
+// ReferralVisit.createJsonApi() resolves Modules.ReferralVisit through the real ModuleRegistry.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("ReferralVisit", { name: "referrals/visits", model: ReferralVisit } as any);
+});
+
+describe("ReferralCodeCapture", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.searchParams = new URLSearchParams({ ref: REF });
+    mocks.enabled = true;
+    mocks.existingCode = null;
+    mocks.recordVisit.mockResolvedValue(undefined);
+  });
+
+  it("records a visit when it sets the cookie", () => {
+    render(<ReferralCodeCapture />);
+
+    expect(mocks.setReferralCode).toHaveBeenCalledTimes(1);
+    expect(mocks.setReferralCode).toHaveBeenCalledWith(REF);
+    expect(mocks.recordVisit).toHaveBeenCalledTimes(1);
+    expect(mocks.recordVisit).toHaveBeenCalledWith({ referralCode: REF });
+  });
+
+  it("does not record a visit when a cookie already exists", () => {
+    mocks.existingCode = "22222222-2222-4222-8222-222222222222";
+
+    render(<ReferralCodeCapture />);
+
+    expect(mocks.setReferralCode).not.toHaveBeenCalled();
+    expect(mocks.recordVisit).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when the feature is disabled", () => {
+    mocks.enabled = false;
+
+    render(<ReferralCodeCapture />);
+
+    expect(mocks.setReferralCode).not.toHaveBeenCalled();
+    expect(mocks.recordVisit).not.toHaveBeenCalled();
+  });
+
+  it("a failed visit call is swallowed", async () => {
+    const unhandled = vi.fn();
+    process.on("unhandledRejection", unhandled);
+    mocks.recordVisit.mockRejectedValue(new Error("network down"));
+
+    try {
+      render(<ReferralCodeCapture />);
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+
+      expect(mocks.setReferralCode).toHaveBeenCalledWith(REF);
+      expect(mocks.recordVisit).toHaveBeenCalledTimes(1);
+      expect(unhandled).not.toHaveBeenCalled();
+    } finally {
+      process.off("unhandledRejection", unhandled);
+    }
+  });
+});
+
+describe("ReferralVisit.createJsonApi()", () => {
+  it("builds the visit body with no id", () => {
+    expect(new ReferralVisit().createJsonApi({ referralCode: "x" })).toEqual({
+      data: { type: "referrals/visits", attributes: { referralCode: "x" } },
+    });
+  });
+});