@carlonicora/nextjs-jsonapi 6.10.2 → 6.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "6.10.2",
+  "version": "6.11.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

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

package/src/features/referral/__tests__/referral-invite-errors.spec.tsx

@@ -0,0 +1,82 @@
+import { act, fireEvent, render, renderHook, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  sendReferralEmail: vi.fn(),
+  sendInvite: vi.fn(),
+  showError: vi.fn(),
+  showToast: vi.fn(),
+}));
+
+// Echoes the key, so an assertion names the message the user would read.
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key }));
+vi.mock("../../../utils", async () => ({
+  ...(await vi.importActual<object>("../../../utils")),
+  showError: mocks.showError,
+  showToast: mocks.showToast,
+}));
+vi.mock("../data/ReferralService", () => ({ ReferralService: { sendReferralEmail: mocks.sendReferralEmail } }));
+vi.mock("../hooks/useReferralStats", () => ({
+  useReferralStats: () => ({ stats: { referralCode: "abc", completedReferrals: 0 }, loading: false, error: null }),
+}));
+vi.mock("../hooks/useReferralInvite", async () => ({
+  ...(await vi.importActual<object>("../hooks/useReferralInvite")),
+  useReferralInvite: () => ({ sendInvite: mocks.sendInvite, sending: false }),
+}));
+
+import { ReferralWidget } from "../components/ReferralWidget";
+import { configureReferral } from "../config";
+
+/** The error callApi throws when suppressGlobalError is set: the JSON:API body rides on `body`. */
+const apiError = (code?: string) =>
+  Object.assign(new Error("400:English text from the API"), {
+    status: 400,
+    body: { errors: [{ status: "400", ...(code ? { code } : {}), detail: "English text from the API" }] },
+  });
+
+const sendTo = (email: string) => {
+  fireEvent.change(screen.getByPlaceholderText("referral.emailPlaceholder"), { target: { value: email } });
+  fireEvent.click(screen.getByRole("button", { name: "referral.send" }));
+};
+
+describe("referral invite errors", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    configureReferral({ enabled: true });
+  });
+
+  it.each([
+    ["REFERRAL_ALREADY_INVITED", "referral.alreadyInvited"],
+    ["REFERRAL_ALREADY_REGISTERED", "referral.alreadyRegistered"],
+    [undefined, "referral.inviteFailed"],
+  ])("code %s shows %s, never the API text", async (code, message) => {
+    mocks.sendInvite.mockRejectedValue(apiError(code));
+    render(<ReferralWidget isDialog />);
+
+    await act(async () => sendTo("gm@example.com"));
+
+    expect(mocks.showError).toHaveBeenCalledWith(message);
+    expect(mocks.showToast).not.toHaveBeenCalled();
+  });
+
+  it("a sent invite shows the translated confirmation", async () => {
+    mocks.sendInvite.mockResolvedValue(undefined);
+    render(<ReferralWidget isDialog />);
+
+    await act(async () => sendTo("gm@example.com"));
+
+    expect(mocks.showToast).toHaveBeenCalledWith("referral.inviteSent");
+    expect(mocks.showError).not.toHaveBeenCalled();
+  });
+
+  it("useReferralInvite rethrows a refused invite", async () => {
+    const { useReferralInvite } =
+      await vi.importActual<typeof import("../hooks/useReferralInvite")>("../hooks/useReferralInvite");
+    mocks.sendReferralEmail.mockRejectedValue(apiError("REFERRAL_ALREADY_INVITED"));
+    const { result } = renderHook(() => useReferralInvite());
+
+    await act(async () => {
+      await expect(result.current.sendInvite("gm@example.com")).rejects.toMatchObject({ status: 400 });
+    });
+  });
+});

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

@@ -0,0 +1,47 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { AbstractService } from "../../../core/abstracts/AbstractService";
+import { JsonApiDataFactory } from "../../../core/factories/JsonApiDataFactory";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { DataClassRegistry } from "../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import { ReferralService } from "../data/ReferralService";
+import { ReferralVisit } from "../data/ReferralVisit";
+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);
+  // bootstrap() does this in an app: the factory builds the body through the registered model.
+  DataClassRegistry.registerObjectClass(ModuleRegistry.get("ReferralVisit" as any), ReferralVisit);
+});
+
+type CallApiParams = { type: ApiRequestDataTypeInterface; method: string; input: unknown };
+
+describe("ReferralService.recordVisit", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  // JsonApiPost runs the model's createJsonApi() on `input` itself, so the body the
+  // API receives is JsonApiDataFactory.create(type, input), never `input` as is.
+  it("the body the API receives carries the referral code", async () => {
+    const spy = vi.spyOn(AbstractService as any, "callApi").mockResolvedValue(undefined);
+
+    await ReferralService.recordVisit({ referralCode: "code-1" });
+
+    const call = spy.mock.calls[0][0] as CallApiParams;
+    expect(call.method).toBe("POST");
+    expect(JsonApiDataFactory.create(call.type, call.input)).toEqual({
+      data: { type: "referrals/visits", attributes: { referralCode: "code-1" } },
+    });
+  });
+});