@carlonicora/nextjs-jsonapi 6.10.2 → 6.11.0

package/src/features/referral/__tests__/referrals-admin-container.spec.tsx

@@ -0,0 +1,230 @@
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+
+const mocks = vi.hoisted(() => ({
+  getSummary: vi.fn(),
+  getReferrers: vi.fn(),
+  getReferrals: vi.fn(),
+  showToast: vi.fn(),
+  showError: vi.fn(),
+}));
+
+// Echoes the key, so an assertion names the message the user would read.
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+  useLocale: () => "en",
+}));
+
+vi.mock("../data/ReferralAdminService", () => ({
+  ReferralAdminService: {
+    getSummary: mocks.getSummary,
+    getReferrers: mocks.getReferrers,
+    getReferrals: mocks.getReferrals,
+  },
+}));
+
+vi.mock("../../../utils", async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  showToast: mocks.showToast,
+  showError: mocks.showError,
+}));
+
+// The real page chrome needs the whole app shell; the stand-in renders the
+// title bar functions (the period buttons) and the body. The table stand-in
+// runs the registered table generator so the cells under test render, without
+// the TanStack and responsive machinery of the real ContentListTable.
+vi.mock("../../../components", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../components")>();
+  const { useSharedContext } = await import("../../../contexts/SharedContext");
+  const { useTableGenerator } = await import("../../../hooks");
+
+  const RoundPageContainer = ({ children, testId }: { children?: ReactNode; testId?: string }) => {
+    const { title } = useSharedContext();
+    return (
+      <div data-testid={testId}>
+        <div>{title.functions}</div>
+        {children}
+      </div>
+    );
+  };
+
+  const ContentListTable = (props: any) => {
+    const { data, columns } = useTableGenerator(props.tableGeneratorType, {
+      data: props.data.data ?? [],
+      fields: props.fields,
+      context: props.context,
+      dataRetriever: props.data,
+    });
+    const render = (def: unknown, ctx: unknown) => (typeof def === "function" ? def(ctx) : def);
+    return (
+      <div>
+        <div>
+          {props.titleActions}
+          {props.title}
+        </div>
+        <table>
+          <thead>
+            <tr>
+              {columns.map((column: any) => (
+                <th key={column.id}>{render(column.header, {})}</th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {data.map((row: any, index: number) => (
+              <tr key={index}>
+                {columns.map((column: any) => (
+                  <td key={column.id}>
+                    {render(column.cell, { row: { original: row, getValue: (key: string) => row[key] } })}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    );
+  };
+
+  return { ...actual, RoundPageContainer, ContentListTable };
+});
+
+import { ReferralsAdminContainer } from "../components/containers/ReferralsAdminContainer";
+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);
+});
+
+const summaryRow = (window: string, values: Record<string, number>) => ({
+  id: window,
+  window,
+  visits: 0,
+  invitesSent: 0,
+  signups: 0,
+  paying: 0,
+  creditsGiven: 0,
+  sharingCompanies: 0,
+  eligibleCompanies: 0,
+  ...values,
+});
+
+const referrer = (id: string, email: string) => ({
+  id,
+  name: `Name ${id}`,
+  email,
+  visits: 1,
+  invitesSent: 2,
+  signupsLink: 1,
+  signupsDirect: 1,
+  paying: 1,
+  creditsEarned: 200,
+  lastInviteAt: new Date("2026-10-27T10:00:00.000Z"),
+});
+
+const writeText = vi.fn();
+
+describe("ReferralsAdminContainer", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubGlobal("navigator", { ...navigator, clipboard: { writeText } });
+    writeText.mockResolvedValue(undefined);
+    mocks.getSummary.mockImplementation(({ period }: { period: string }) =>
+      Promise.resolve(
+        period === "all"
+          ? [summaryRow("current", { visits: 40 })]
+          : [summaryRow("current", { visits: 12 }), summaryRow("previous", { visits: 6 })],
+      ),
+    );
+    mocks.getReferrers.mockResolvedValue([referrer("c1", "a@x.test"), referrer("c2", "b@x.test")]);
+    mocks.getReferrals.mockResolvedValue([]);
+  });
+
+  it("renders the tiles from the current window", async () => {
+    render(<ReferralsAdminContainer />);
+
+    await waitFor(() => expect(screen.getByTestId("referrals-tile-visits-value")).toHaveTextContent("12"));
+    expect(mocks.getSummary).toHaveBeenCalledWith({ period: "30d" });
+    expect(screen.getByTestId("referrals-tile-visits-change")).toBeInTheDocument();
+  });
+
+  it("switching period refetches", async () => {
+    render(<ReferralsAdminContainer />);
+    await waitFor(() => expect(screen.getByTestId("referrals-tile-visits-value")).toHaveTextContent("12"));
+
+    await act(async () => fireEvent.click(screen.getByTestId("referrals-period-all")));
+
+    await waitFor(() => expect(screen.getByTestId("referrals-tile-visits-value")).toHaveTextContent("40"));
+    expect(mocks.getSummary).toHaveBeenCalledWith({ period: "all" });
+    expect(screen.getByTestId("referrals-period-all")).toHaveAttribute("aria-pressed", "true");
+    expect(screen.queryByTestId("referrals-tile-visits-change")).not.toBeInTheDocument();
+  });
+
+  it("copy all emails copies the shown referrers", async () => {
+    render(<ReferralsAdminContainer />);
+    await waitFor(() => expect(screen.getByTestId("referrals-copy-email-c2")).toBeInTheDocument());
+
+    await act(async () => fireEvent.click(screen.getByTestId("referrals-copy-all-emails")));
+
+    expect(writeText).toHaveBeenCalledWith("a@x.test, b@x.test");
+    expect(mocks.showToast).toHaveBeenCalledWith("referral.admin.referrers.copied");
+  });
+
+  it("per-row copy copies one email", async () => {
+    render(<ReferralsAdminContainer />);
+    await waitFor(() => expect(screen.getByTestId("referrals-copy-email-c2")).toBeInTheDocument());
+
+    await act(async () => fireEvent.click(screen.getByTestId("referrals-copy-email-c2")));
+
+    expect(writeText).toHaveBeenCalledWith("b@x.test");
+    expect(mocks.showToast).toHaveBeenCalledWith("referral.admin.referrers.copied");
+  });
+
+  it("a referral with no recorded source shows no source pill", async () => {
+    mocks.getReferrals.mockResolvedValue([
+      {
+        id: "r1",
+        name: "Old account",
+        email: "old@x.test",
+        referrerName: "Name c1",
+        referrerEmail: "a@x.test",
+        source: "",
+        status: "pending",
+        referredAt: new Date("2026-10-20T10:00:00.000Z"),
+        completedAt: undefined,
+        tokensAwarded: undefined,
+      },
+    ]);
+    render(<ReferralsAdminContainer />);
+    await waitFor(() => expect(screen.getByText("Old account")).toBeInTheDocument());
+
+    expect(screen.queryByText("referral.admin.source.direct")).not.toBeInTheDocument();
+    expect(screen.queryByText("referral.admin.source.link")).not.toBeInTheDocument();
+  });
+
+  it("a refused clipboard write shows an error", async () => {
+    writeText.mockRejectedValue(new Error("denied"));
+    render(<ReferralsAdminContainer />);
+    await waitFor(() => expect(screen.getByTestId("referrals-copy-email-c1")).toBeInTheDocument());
+
+    await act(async () => fireEvent.click(screen.getByTestId("referrals-copy-email-c1")));
+
+    expect(mocks.showError).toHaveBeenCalled();
+    expect(mocks.showToast).not.toHaveBeenCalled();
+  });
+});

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

@@ -4,6 +4,7 @@ import { useSearchParams } from "next/navigation";
 import { useEffect } from "react";
 
 import { getReferralConfig, isReferralEnabled } from "../config";
+import { ReferralService } from "../data/ReferralService";
 import { getReferralCode, setReferralCode } from "../utils/referral-cookie";
 
 /**
@@ -34,6 +35,8 @@ export function ReferralCodeCapture(): null {
       // First referrer wins - only set if no existing cookie
       if (!existingCode) {
         setReferralCode(refCode);
+        // Counted once per browser; a failed call never reaches the visitor.
+        ReferralService.recordVisit({ referralCode: refCode }).catch(() => {});
       }
     }
   }, [searchParams]);

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

@@ -1,5 +1,7 @@
 "use client";
 
+import { useTranslations } from "next-intl";
+
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from "../../../shadcnui";
 import { isReferralEnabled } from "../config";
 import { ReferralWidget, ReferralWidgetProps, ReferralWidgetTranslations } from "./ReferralWidget";
@@ -9,20 +11,12 @@ import { ReferralWidget, ReferralWidgetProps, ReferralWidgetTranslations } from
  * Extends ReferralWidgetTranslations with dialog-specific strings.
  */
 export interface ReferralDialogTranslations extends ReferralWidgetTranslations {
-  /** Dialog title */
+  /** Dialog title (default: `referral.title`) */
   dialogTitle?: string;
-  /** Dialog description */
+  /** Dialog description (default: `referral.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.
  */
@@ -73,19 +67,21 @@ export function ReferralDialog({
   dialogClassName,
   ...widgetProps
 }: ReferralDialogProps) {
+  const t = useTranslations();
+
   // Render nothing when disabled
   if (!isReferralEnabled()) {
     return null;
   }
 
-  const t = { ...DEFAULT_DIALOG_TRANSLATIONS, ...translations };
+  const text = { dialogTitle: t("referral.title"), dialogDescription: t("referral.description"), ...translations };
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className={dialogClassName ?? "max-w-md"}>
         <DialogHeader>
-          <DialogTitle>{t.dialogTitle}</DialogTitle>
-          <DialogDescription>{t.dialogDescription}</DialogDescription>
+          <DialogTitle>{text.dialogTitle}</DialogTitle>
+          <DialogDescription>{text.dialogDescription}</DialogDescription>
         </DialogHeader>
         <ReferralWidget {...widgetProps} translations={translations} isDialog />
       </DialogContent>

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

@@ -1,6 +1,7 @@
 "use client";
 
 import { Copy, Loader2, Mail, Users } from "lucide-react";
+import { useTranslations } from "next-intl";
 import { useCallback, useRef, useState } from "react";
 
 import { Button, Card, Input, Label } from "../../../shadcnui";
@@ -10,33 +11,10 @@ import { getReferralConfig, isReferralEnabled } from "../config";
 import { useReferralInvite } from "../hooks/useReferralInvite";
 import { useReferralStats } from "../hooks/useReferralStats";
 
-/**
- * Default translations for ReferralWidget.
- * These can be overridden via the translations prop.
- */
-const DEFAULT_TRANSLATIONS: Required<ReferralWidgetTranslations> = {
-  title: "Invite Friends",
-  description: "Share your referral link and earn rewards when your friends subscribe.",
-  yourLink: "Your referral link",
-  copyButton: "Copy",
-  copiedMessage: "Link copied to clipboard!",
-  statsLabel: "Your referral stats",
-  completedLabel: "Successful referrals",
-  tokensLabel: "Tokens earned",
-  inviteTitle: "Invite by email",
-  inviteDescription: "Send an invitation directly to a friend's email.",
-  emailPlaceholder: "friend@example.com",
-  sendButton: "Send",
-  sendingButton: "Sending...",
-  inviteSent: "Invitation sent successfully!",
-  inviteError: "Failed to send invitation",
-  copyError: "Failed to copy link",
-  invalidEmail: "Please enter a valid email address",
-};
-
 /**
  * Translation strings for the ReferralWidget component.
- * All strings are optional and have defaults.
+ * All strings are optional: each defaults to its `referral.*` key in the
+ * library's messages, which the app can also override in its own messages file.
  */
 export interface ReferralWidgetTranslations {
   /** Widget title */
@@ -73,6 +51,19 @@ export interface ReferralWidgetTranslations {
   copyError?: string;
   /** Error message for invalid email */
   invalidEmail?: string;
+  /** Error message when the referral link and stats cannot be loaded */
+  loadError?: string;
+  /** Error message when the email was already invited recently (API code REFERRAL_ALREADY_INVITED) */
+  alreadyInvited?: string;
+  /** Error message when the email already has an account (API code REFERRAL_ALREADY_REGISTERED) */
+  alreadyRegistered?: string;
+}
+
+/**
+ * The `code` the API puts on a refused invite's JSON:API error.
+ */
+function inviteErrorCode(err: unknown): string | undefined {
+  return (err as { body?: { errors?: { code?: string }[] } })?.body?.errors?.[0]?.code;
 }
 
 /**
@@ -162,7 +153,28 @@ export function ReferralWidget({
   onInviteSent,
   onInviteError,
 }: ReferralWidgetProps) {
-  const t = { ...DEFAULT_TRANSLATIONS, ...translations };
+  const t = useTranslations();
+  const text = {
+    title: t("referral.title"),
+    description: t("referral.description"),
+    yourLink: t("referral.yourLink"),
+    copyButton: t("referral.copy"),
+    copiedMessage: t("referral.linkCopied"),
+    completedLabel: t("referral.completedLabel"),
+    inviteTitle: t("referral.inviteTitle"),
+    inviteDescription: t("referral.inviteDescription"),
+    emailPlaceholder: t("referral.emailPlaceholder"),
+    sendButton: t("referral.send"),
+    sendingButton: t("referral.sending"),
+    inviteSent: t("referral.inviteSent"),
+    inviteError: t("referral.inviteFailed"),
+    copyError: t("referral.copyFailed"),
+    invalidEmail: t("referral.invalidEmail"),
+    loadError: t("referral.loadFailed"),
+    alreadyInvited: t("referral.alreadyInvited"),
+    alreadyRegistered: t("referral.alreadyRegistered"),
+    ...translations,
+  };
 
   // Call ALL hooks unconditionally at the top (React Rules of Hooks)
   const { stats, loading, error } = useReferralStats();
@@ -189,31 +201,49 @@ export function ReferralWidget({
     const success = await copyToClipboard(referralUrl);
     if (success) {
       setCopied(true);
-      showToast(t.copiedMessage);
+      showToast(text.copiedMessage);
       onLinkCopied?.();
       setTimeout(() => setCopied(false), 2000);
     } else {
-      showError(t.copyError);
+      showError(text.copyError);
     }
-  }, [referralUrl, t.copiedMessage, t.copyError, onLinkCopied]);
+  }, [referralUrl, text.copiedMessage, text.copyError, onLinkCopied]);
 
   const handleSendInvite = useCallback(async () => {
     if (!email || !email.includes("@")) {
-      showError(t.invalidEmail);
+      showError(text.invalidEmail);
       return;
     }
 
     try {
       await sendInvite(email);
-      showToast(t.inviteSent);
+      showToast(text.inviteSent);
       onInviteSent?.(email);
       setEmail("");
     } catch (err) {
-      const error = err instanceof Error ? err : new Error(t.inviteError);
-      showError(error.message);
-      onInviteError?.(error);
+      // The API's English text never reaches the user: a known refusal has its own
+      // translated message, anything else the generic one.
+      const code = inviteErrorCode(err);
+      showError(
+        code === "REFERRAL_ALREADY_INVITED"
+          ? text.alreadyInvited
+          : code === "REFERRAL_ALREADY_REGISTERED"
+            ? text.alreadyRegistered
+            : text.inviteError,
+      );
+      onInviteError?.(err instanceof Error ? err : new Error(text.inviteError));
     }
-  }, [email, sendInvite, t.inviteSent, t.inviteError, t.invalidEmail, onInviteSent, onInviteError]);
+  }, [
+    email,
+    sendInvite,
+    text.inviteSent,
+    text.inviteError,
+    text.invalidEmail,
+    text.alreadyInvited,
+    text.alreadyRegistered,
+    onInviteSent,
+    onInviteError,
+  ]);
 
   const handleEmailKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLInputElement>) => {
@@ -245,7 +275,7 @@ export function ReferralWidget({
 
   // Error state
   if (error) {
-    const errorMessage = error instanceof Error ? error.message : "Failed to load referral data";
+    const errorMessage = text.loadError;
     if (isDialog) {
       return <div className="text-destructive text-center text-sm">{errorMessage}</div>;
     }
@@ -266,15 +296,15 @@ export function ReferralWidget({
             <Users className="text-primary h-5 w-5" />
           </div>
           <div className="flex flex-col gap-1">
-            <SectionHeader>{t.title}</SectionHeader>
-            <p className="text-muted-foreground text-sm">{t.description}</p>
+            <SectionHeader>{text.title}</SectionHeader>
+            <p className="text-muted-foreground text-sm">{text.description}</p>
           </div>
         </div>
       )}
 
       {/* Referral Link */}
       <div className="flex flex-col gap-2">
-        <Label>{t.yourLink}</Label>
+        <Label>{text.yourLink}</Label>
         <div className="flex gap-2">
           <Input ref={linkInputRef} value={referralUrl} readOnly className="tabular-nums text-sm" />
           <Button
@@ -283,7 +313,7 @@ export function ReferralWidget({
             size="icon"
             onClick={handleCopyLink}
             disabled={!referralUrl}
-            aria-label={t.copyButton}
+            aria-label={text.copyButton}
           >
             <Copy className={`h-4 w-4 ${copied ? "text-success" : ""}`} />
           </Button>
@@ -292,15 +322,15 @@ export function ReferralWidget({
 
       {/* Email Invite */}
       <div className="flex flex-col gap-2">
-        <Label>{t.inviteTitle}</Label>
-        <p className="text-muted-foreground text-xs/relaxed">{t.inviteDescription}</p>
+        <Label>{text.inviteTitle}</Label>
+        <p className="text-muted-foreground text-xs/relaxed">{text.inviteDescription}</p>
         <div className="flex gap-2">
           <Input
             type="email"
             value={email}
             onChange={(e) => setEmail(e.target.value)}
             onKeyDown={handleEmailKeyDown}
-            placeholder={t.emailPlaceholder}
+            placeholder={text.emailPlaceholder}
             disabled={sending}
           />
           <Button
@@ -309,7 +339,7 @@ export function ReferralWidget({
             size="icon"
             onClick={handleSendInvite}
             disabled={sending || !email}
-            aria-label={sending ? t.sendingButton : t.sendButton}
+            aria-label={sending ? text.sendingButton : text.sendButton}
           >
             {sending ? <Loader2 className="h-4 w-4 animate-spin" /> : <Mail className="h-4 w-4" />}
           </Button>
@@ -320,7 +350,7 @@ export function ReferralWidget({
       {stats && stats.completedReferrals > 0 && (
         <div className="border-border border-t pt-3">
           <p className="text-muted-foreground text-sm">
-            {t.completedLabel}: {stats.completedReferrals}
+            {text.completedLabel}: {stats.completedReferrals}
           </p>
         </div>
       )}

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

@@ -0,0 +1,74 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { SEQUENTIAL_RAMP } from "../../tokenusage/lib/palette";
+import { ReferralAdminSummaryInterface } from "../interfaces/referral-admin.interface";
+
+type Props = {
+  summary: ReferralAdminSummaryInterface[];
+};
+
+/**
+ * "From visit to paying": visits → invites → sign-ups → paying of the current
+ * window as plain proportional bars, each with its share of the previous step.
+ * Bars are scaled to the largest step, since invites can outnumber visits.
+ * The rows copy TokenUsageRankedBar: same track, ramp, sizes and columns.
+ */
+export function ReferralsAdminFunnel({ summary }: Props) {
+  const t = useTranslations();
+  const { decimal } = useUsageFormatters();
+
+  const current = summary.find((row) => row.window === "current");
+
+  const steps = [
+    { label: t("referral.admin.tiles.visits"), value: current?.visits ?? 0 },
+    { label: t("referral.admin.tiles.invites"), value: current?.invitesSent ?? 0 },
+    { label: t("referral.admin.tiles.signups"), value: current?.signups ?? 0 },
+    { label: t("referral.admin.tiles.paying"), value: current?.paying ?? 0 },
+  ];
+
+  const max = Math.max(...steps.map((step) => step.value), 0);
+
+  return (
+    <section data-testid="referrals-funnel" className="grid gap-2">
+      <h2 className="text-muted-foreground flex items-center gap-x-2 text-sm font-light whitespace-nowrap">
+        {t("referral.admin.funnel.title")}
+      </h2>
+      <div className="grid gap-0.5">
+        {steps.map((step, index) => {
+          const width = max > 0 ? (step.value / max) * 100 : 0;
+          const before = index > 0 ? steps[index - 1].value : undefined;
+          const share =
+            before === undefined ? "" : before ? `${decimal(Math.round((step.value / before) * 100), 0)}%` : "—";
+          return (
+            <div
+              key={step.label}
+              className="grid grid-cols-[minmax(0,1fr)_auto_auto] items-center gap-x-3 gap-y-0.5 py-0.5"
+            >
+              <div className="grid min-w-0 gap-0.5">
+                <span className="text-muted-foreground truncate text-xs">{step.label}</span>
+                {/* The bar is a magnitude drawn on an axis, not prose: it always grows
+                    rightward and only its trailing corner is rounded, so the track and its fill
+                    stay an LTR island. The label, value and share around it mirror normally.
+                    rtl-ok: deliberate LTR island (chart) */}
+                <div className="bg-muted h-2 w-full overflow-hidden rounded-r-[4px]" dir="ltr">
+                  <div
+                    /* rtl-ok: inside the LTR island above */
+                    className="h-full rounded-r-[4px]"
+                    style={{
+                      width: `${width}%`,
+                      backgroundColor: SEQUENTIAL_RAMP[Math.min(index, SEQUENTIAL_RAMP.length - 1)],
+                    }}
+                  />
+                </div>
+              </div>
+              <span className="text-end text-xs tabular-nums">{decimal(step.value, 0)}</span>
+              <span className="text-muted-foreground w-16 text-end text-xs tabular-nums">{share}</span>
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  );
+}