@carlonicora/nextjs-jsonapi 6.10.1 → 6.11.0

package/messages/it.json

@@ -1785,7 +1785,84 @@
   "referral": {
     "description": "Invita i tuoi amici e guadagna ricompense",
     "title": "Invita e guadagna",
-    "yourLink": "Il tuo link di invito"
+    "yourLink": "Il tuo link di invito",
+    "copy": "Copia link",
+    "linkCopied": "Link copiato",
+    "completedLabel": "Inviti andati a buon fine",
+    "inviteTitle": "Invita via email",
+    "inviteDescription": "Il tuo nome e la tua email vengono condivisi con la persona che inviti.",
+    "emailPlaceholder": "amico@esempio.com",
+    "send": "Invia invito",
+    "sending": "Invio…",
+    "inviteSent": "Invito inviato",
+    "inviteFailed": "Impossibile inviare l'invito",
+    "copyFailed": "Impossibile copiare il link",
+    "invalidEmail": "Inserisci un indirizzo email valido",
+    "loadFailed": "Impossibile caricare il tuo link di invito",
+    "alreadyInvited": "Hai già invitato questa email di recente",
+    "alreadyRegistered": "Questa email ha già un account",
+    "admin": {
+      "title": "Referral",
+      "description": "Inviti, iscrizioni e referral paganti",
+      "period": {
+        "30d": "30 giorni",
+        "90d": "90 giorni",
+        "all": "Sempre"
+      },
+      "tiles": {
+        "sharing": "Condividono",
+        "sharingOf": "{count} su {total} account abbonati",
+        "visits": "Visite al link",
+        "invites": "Email di invito inviate",
+        "signups": "Iscritti",
+        "paying": "Paganti",
+        "credits": "Crediti assegnati",
+        "change": "{delta} rispetto al periodo precedente"
+      },
+      "funnel": {
+        "title": "Dalla visita al pagamento"
+      },
+      "referrers": {
+        "title": "Chi invita di più",
+        "sortBy": "Ordina per",
+        "copyAll": "Copia tutte le email",
+        "copied": "Email copiate",
+        "copyEmail": "Copia email",
+        "copyFailed": "Impossibile copiare le email",
+        "empty": "Nessuna attività di referral in questo periodo",
+        "split": "{link} via link, {direct} dirette",
+        "columns": {
+          "referrer": "Referente",
+          "visits": "Visite",
+          "invites": "Email inviate",
+          "signups": "Iscritti",
+          "paying": "Paganti",
+          "conversion": "Conversione",
+          "credits": "Crediti guadagnati",
+          "lastInvite": "Ultimo invito"
+        }
+      },
+      "referrals": {
+        "title": "Tutti i referral",
+        "empty": "Nessun referral in questo periodo",
+        "columns": {
+          "account": "Nuovo account",
+          "referrer": "Portato da",
+          "source": "Come",
+          "date": "Data",
+          "status": "Stato",
+          "credits": "Crediti assegnati"
+        }
+      },
+      "source": {
+        "link": "Link di invito",
+        "direct": "Diretto"
+      },
+      "status": {
+        "pending": "In attesa",
+        "completed": "Pagante"
+      }
+    }
   },
   "role": {
     "fields": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "6.10.1",
+  "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/abstracts/AbstractApiData.ts

@@ -227,7 +227,7 @@ export abstract class AbstractApiData implements ApiDataInterface {
 
         // Merge per-item meta from relationships[type].data[].meta
         if (item.meta) {
-          Object.assign(entity, item.meta);
+          AbstractApiData._mergeMeta(entity, item.meta);
         }
 
         result.push(entity as T & M);
@@ -256,7 +256,7 @@ export abstract class AbstractApiData implements ApiDataInterface {
           // Merge relationship-level meta for single relationships
           const relationshipMeta = data.jsonApi.relationships[type].meta;
           if (relationshipMeta) {
-            Object.assign(entity, relationshipMeta);
+            AbstractApiData._mergeMeta(entity, relationshipMeta);
           }
           return entity as T & M;
         }
@@ -272,12 +272,23 @@ export abstract class AbstractApiData implements ApiDataInterface {
     // Merge relationship-level meta for single relationships
     const relationshipMeta = data.jsonApi.relationships[type].meta;
     if (relationshipMeta) {
-      Object.assign(entity, relationshipMeta);
+      AbstractApiData._mergeMeta(entity, relationshipMeta);
     }
 
     return entity as T & M;
   }
 
+  /**
+   * Copies relationship meta onto a rehydrated entity as own data properties. Object.assign throws
+   * when the model declares a getter-only accessor of the same name (an app's `Chunk` with
+   * `get relevance()`); an own property shadows that getter, so the model reads the meta value.
+   */
+  private static _mergeMeta(entity: object, meta: Record<string, any>): void {
+    for (const [key, value] of Object.entries(meta)) {
+      Object.defineProperty(entity, key, { value, writable: true, enumerable: true, configurable: true });
+    }
+  }
+
   dehydrate(): JsonApiHydratedDataInterface {
     return {
       jsonApi: this._jsonApi,

package/src/core/abstracts/__tests__/readIncludedWithMeta.spec.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AbstractApiData } from "../AbstractApiData";
+import { DataClassRegistry } from "../../registry/DataClassRegistry";
+import { ApiDataInterface } from "../../interfaces/ApiDataInterface";
+import { JsonApiHydratedDataInterface } from "../../interfaces/JsonApiHydratedDataInterface";
+import { ApiRequestDataTypeInterface } from "../../interfaces/ApiRequestDataTypeInterface";
+
+// Concrete test class to access the protected method
+class TestModel extends AbstractApiData {
+  public testReadIncludedWithMeta<T extends ApiDataInterface, M extends Record<string, any>>(
+    data: JsonApiHydratedDataInterface,
+    type: string,
+    dataType: ApiRequestDataTypeInterface,
+  ): (T & M) | (T & M)[] | undefined {
+    return this._readIncludedWithMeta<T, M>(data, type, dataType);
+  }
+}
+
+// Mirrors an app model that exposes the relationship meta through a getter only (a360ai's Chunk)
+class MockChunk extends AbstractApiData {
+  private _relevance?: number;
+
+  get relevance(): number {
+    return this._relevance ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    return this;
+  }
+}
+
+const chunkModule: ApiRequestDataTypeInterface = {
+  name: "chunks",
+  model: MockChunk,
+} as any;
+
+describe("_readIncludedWithMeta", () => {
+  beforeEach(() => {
+    DataClassRegistry.clear();
+    DataClassRegistry.registerObjectClass(chunkModule, MockChunk);
+  });
+
+  it("merges per-item meta onto a model whose property is a getter only", () => {
+    // GIVEN: an assistant message citing two chunks with relevance meta on the relationship
+    const data: JsonApiHydratedDataInterface = {
+      jsonApi: {
+        id: "message-1",
+        type: "assistant-messages",
+        attributes: {},
+        relationships: {
+          citations: {
+            data: [
+              { id: "chunk-1", type: "chunks", meta: { relevance: 0.9, reason: "names the deadline" } },
+              { id: "chunk-2", type: "chunks", meta: { relevance: 0.4 } },
+            ],
+          },
+        },
+      },
+      included: [
+        { id: "chunk-1", type: "chunks", attributes: { content: "a" } },
+        { id: "chunk-2", type: "chunks", attributes: { content: "b" } },
+      ],
+    };
+
+    // WHEN: the citations are read with their meta
+    const result = new TestModel().testReadIncludedWithMeta<MockChunk, { relevance: number; reason?: string }>(
+      data,
+      "citations",
+      chunkModule,
+    ) as (MockChunk & { reason?: string })[];
+
+    // THEN: no TypeError, and the getter-only property reads the meta value
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBeInstanceOf(MockChunk);
+    expect(result[0].relevance).toBe(0.9);
+    expect(result[0].reason).toBe("names the deadline");
+    expect(result[1].relevance).toBe(0.4);
+  });
+
+  it("merges relationship-level meta on a single relationship", () => {
+    const data: JsonApiHydratedDataInterface = {
+      jsonApi: {
+        id: "message-1",
+        type: "assistant-messages",
+        attributes: {},
+        relationships: {
+          topCitation: { data: { id: "chunk-1", type: "chunks" }, meta: { relevance: 0.7 } },
+        },
+      },
+      included: [{ id: "chunk-1", type: "chunks", attributes: { content: "a" } }],
+    };
+
+    const result = new TestModel().testReadIncludedWithMeta<MockChunk, { relevance: number }>(
+      data,
+      "topCitation",
+      chunkModule,
+    ) as MockChunk;
+
+    expect(result).toBeInstanceOf(MockChunk);
+    expect(result.relevance).toBe(0.7);
+  });
+});

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