@carlonicora/nextjs-jsonapi 6.10.2 → 6.12.0

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

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

@@ -0,0 +1,128 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { MicroLabel } from "../../../components/typography/MicroLabel";
+import { Card, CardContent } from "../../../shadcnui";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { percentageDelta } from "../../tokenusage/lib/metrics";
+import { ReferralAdminSummaryInterface } from "../interfaces/referral-admin.interface";
+
+type Props = {
+  /** The summary rows: `current`, plus `previous` unless the period is `all`. */
+  summary: ReferralAdminSummaryInterface[];
+};
+
+type Metric =
+  "visits" | "invitesSent" | "signups" | "paying" | "creditsGiven" | "sharingCompanies" | "eligibleCompanies";
+
+const ZERO: Record<Metric, number> = {
+  visits: 0,
+  invitesSent: 0,
+  signups: 0,
+  paying: 0,
+  creditsGiven: 0,
+  sharingCompanies: 0,
+  eligibleCompanies: 0,
+};
+
+/**
+ * The KPI row of the administrative referral page. Each tile reads the
+ * `current` window; the change line compares it with the `previous` one and is
+ * left out when there is no previous window (the `all` period).
+ */
+export function ReferralsAdminTiles({ summary }: Props) {
+  const t = useTranslations();
+  const { decimal } = useUsageFormatters();
+
+  const current = summary.find((row) => row.window === "current") ?? ZERO;
+  const previous = summary.find((row) => row.window === "previous");
+
+  const change = (metric: Metric): string | undefined => {
+    if (!previous) return undefined;
+    const delta = percentageDelta(current[metric], previous[metric]);
+    const formatted = delta === undefined ? "—" : `${delta > 0 ? "+" : ""}${decimal(delta, 0)}%`;
+    return t("referral.admin.tiles.change", { delta: formatted });
+  };
+
+  return (
+    <div className="grid gap-3 lg:grid-cols-[minmax(0,1fr)_minmax(0,4fr)]">
+      <LeadTile
+        id="sharing"
+        label={t("referral.admin.tiles.sharing")}
+        value={decimal(current.sharingCompanies, 0)}
+        detail={t("referral.admin.tiles.sharingOf", {
+          count: decimal(current.sharingCompanies, 0),
+          total: decimal(current.eligibleCompanies, 0),
+        })}
+      />
+      <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-5">
+        <SupportingTile
+          id="visits"
+          label={t("referral.admin.tiles.visits")}
+          value={decimal(current.visits, 0)}
+          change={change("visits")}
+        />
+        <SupportingTile
+          id="invites"
+          label={t("referral.admin.tiles.invites")}
+          value={decimal(current.invitesSent, 0)}
+          change={change("invitesSent")}
+        />
+        <SupportingTile
+          id="signups"
+          label={t("referral.admin.tiles.signups")}
+          value={decimal(current.signups, 0)}
+          change={change("signups")}
+        />
+        <SupportingTile
+          id="paying"
+          label={t("referral.admin.tiles.paying")}
+          value={decimal(current.paying, 0)}
+          change={change("paying")}
+        />
+        <SupportingTile
+          id="credits"
+          label={t("referral.admin.tiles.credits")}
+          value={decimal(current.creditsGiven, 0)}
+          change={change("creditsGiven")}
+        />
+      </div>
+    </div>
+  );
+}
+
+/** The lead tile: the same card and recipe as AnalyticsAdminTiles' LeadTile. */
+function LeadTile({ id, label, value, detail }: { id: string; label: string; value: string; detail: string }) {
+  return (
+    <Card data-testid={`referrals-tile-${id}`}>
+      <CardContent className="grid gap-1">
+        <MicroLabel>{label}</MicroLabel>
+        <span data-testid={`referrals-tile-${id}-value`} className="text-primary text-xl font-semibold tabular-nums">
+          {value}
+        </span>
+        <span className="text-muted-foreground text-xs">{detail}</span>
+      </CardContent>
+    </Card>
+  );
+}
+
+/** A supporting tile: the same card and recipe as AnalyticsAdminTiles' SupportingTile. */
+function SupportingTile({ id, label, value, change }: { id: string; label: string; value: string; change?: string }) {
+  return (
+    <Card data-testid={`referrals-tile-${id}`} size="sm">
+      <CardContent className="grid gap-1">
+        <MicroLabel>{label}</MicroLabel>
+        <span className="flex items-center gap-2">
+          <span data-testid={`referrals-tile-${id}-value`} className="text-sm font-medium tabular-nums">
+            {value}
+          </span>
+          {change && (
+            <span data-testid={`referrals-tile-${id}-change`} className="text-muted-foreground text-xs">
+              {change}
+            </span>
+          )}
+        </span>
+      </CardContent>
+    </Card>
+  );
+}

package/src/features/referral/components/containers/ReferralsAdminContainer.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import { CopyIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ContentListTable, RoundPageContainer } from "../../../../components";
+import { SharedProvider } from "../../../../contexts/SharedContext";
+import { Modules } from "../../../../core";
+import { DataListRetriever, useDataListRetriever } from "../../../../hooks";
+import { BreadcrumbItemData } from "../../../../interfaces";
+import { Button } from "../../../../shadcnui";
+import { ReferralAdminService } from "../../data/ReferralAdminService";
+// Importing the field enums (runtime values) also runs the hook modules, which
+// is what registers the table generators ContentListTable looks up.
+import { ReferralAdminReferralFields } from "../../hooks/useReferralAdminReferralTableStructure";
+import {
+  copyReferrerEmails,
+  ReferralAdminReferrerFields,
+  ReferralAdminReferrerTableContext,
+} from "../../hooks/useReferralAdminReferrerTableStructure";
+import {
+  ReferralAdminPeriod,
+  ReferralAdminReferralInterface,
+  ReferralAdminReferrerInterface,
+  ReferralAdminSort,
+  ReferralAdminSummaryInterface,
+} from "../../interfaces/referral-admin.interface";
+import { ReferralsAdminFunnel } from "../ReferralsAdminFunnel";
+import { ReferralsAdminTiles } from "../ReferralsAdminTiles";
+
+const PERIODS: ReferralAdminPeriod[] = ["30d", "90d", "all"];
+
+const REFERRER_FIELDS = [
+  ReferralAdminReferrerFields.rank,
+  ReferralAdminReferrerFields.referrer,
+  ReferralAdminReferrerFields.visits,
+  ReferralAdminReferrerFields.invites,
+  ReferralAdminReferrerFields.signups,
+  ReferralAdminReferrerFields.paying,
+  ReferralAdminReferrerFields.conversion,
+  ReferralAdminReferrerFields.credits,
+  ReferralAdminReferrerFields.lastInvite,
+];
+
+const REFERRAL_FIELDS = [
+  ReferralAdminReferralFields.account,
+  ReferralAdminReferralFields.referrer,
+  ReferralAdminReferralFields.source,
+  ReferralAdminReferralFields.date,
+  ReferralAdminReferralFields.status,
+  ReferralAdminReferralFields.credits,
+];
+
+/**
+ * Pushes a changed parameter into a list retriever. The retriever reads its
+ * `retrieverParams` only on the first load; a later change goes through
+ * `addAdditionalParameter`, which re-fetches and keeps the old rows on screen
+ * until the new ones arrive. The first render is skipped: the initial load
+ * already carries the value.
+ */
+function useRefetchOnChange(retriever: DataListRetriever<unknown>, key: string, value: string) {
+  const previous = useRef(value);
+  useEffect(() => {
+    if (previous.current === value) return;
+    previous.current = value;
+    retriever.addAdditionalParameter(key, value);
+  }, [retriever, key, value]);
+}
+
+/**
+ * Administrative referral report: period buttons in the title bar, the KPI
+ * tiles, the visit-to-paying funnel, the referrers ranking and every referral.
+ * Client component by necessity: `module={Modules.ReferralAdminSummary}` is a
+ * registry entry carrying an icon component, which a Server Component cannot
+ * pass across the boundary.
+ */
+export function ReferralsAdminContainer() {
+  const t = useTranslations();
+  const [period, setPeriod] = useState<ReferralAdminPeriod>("30d");
+  const [sort, setSort] = useState<ReferralAdminSort>("paying");
+  const [summary, setSummary] = useState<ReferralAdminSummaryInterface[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    ReferralAdminService.getSummary({ period })
+      .then((rows) => {
+        if (!cancelled) setSummary(rows ?? []);
+      })
+      .catch(() => {
+        if (!cancelled) setSummary([]);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [period]);
+
+  const referrers: DataListRetriever<ReferralAdminReferrerInterface> = useDataListRetriever({
+    module: Modules.ReferralAdminReferrer,
+    retriever: (params: { period: ReferralAdminPeriod; sort: ReferralAdminSort }) =>
+      ReferralAdminService.getReferrers({ period: params.period, sort: params.sort }),
+    retrieverParams: { period, sort },
+  });
+
+  const referrals: DataListRetriever<ReferralAdminReferralInterface> = useDataListRetriever({
+    module: Modules.ReferralAdminReferral,
+    retriever: (params: { period: ReferralAdminPeriod }) =>
+      ReferralAdminService.getReferrals({ period: params.period }),
+    retrieverParams: { period },
+  });
+
+  useRefetchOnChange(referrers as DataListRetriever<unknown>, "period", period);
+  useRefetchOnChange(referrers as DataListRetriever<unknown>, "sort", sort);
+  useRefetchOnChange(referrals as DataListRetriever<unknown>, "period", period);
+
+  const referrerContext = useMemo<ReferralAdminReferrerTableContext>(() => ({ sort, onSort: setSort }), [sort]);
+
+  const periodLabels: Record<ReferralAdminPeriod, string> = {
+    "30d": t("referral.admin.period.30d"),
+    "90d": t("referral.admin.period.90d"),
+    all: t("referral.admin.period.all"),
+  };
+
+  const periodButtons = (
+    <div
+      key="referralsAdminPeriod"
+      role="group"
+      className="border-border inline-flex items-center gap-0.5 rounded-md border p-0.5"
+    >
+      {PERIODS.map((value) => {
+        const selected = value === period;
+        return (
+          <Button
+            key={value}
+            type="button"
+            size="sm"
+            variant={selected ? "default" : "ghost"}
+            aria-pressed={selected}
+            data-testid={`referrals-period-${value}`}
+            onClick={() => setPeriod(value)}
+          >
+            {periodLabels[value]}
+          </Button>
+        );
+      })}
+    </div>
+  );
+
+  const shownEmails = (referrers.data ?? []).map((entry) => entry.email).filter((email) => !!email);
+
+  const copyAll = (
+    <Button
+      type="button"
+      variant="outline"
+      size="sm"
+      data-testid="referrals-copy-all-emails"
+      disabled={shownEmails.length === 0}
+      onClick={() => copyReferrerEmails(shownEmails.join(", "), t)}
+    >
+      <CopyIcon />
+      {t("referral.admin.referrers.copyAll")}
+    </Button>
+  );
+
+  const breadcrumbs: BreadcrumbItemData[] = [{ name: t("referral.admin.title") }];
+
+  return (
+    <SharedProvider value={{ breadcrumbs, title: { type: t("referral.admin.title"), functions: periodButtons } }}>
+      <RoundPageContainer module={Modules.ReferralAdminSummary} fullWidth forceHeader testId="page-admin-referrals">
+        <div className="flex w-full flex-col gap-6 p-4">
+          <p className="text-muted-foreground text-xs">{t("referral.admin.description")}</p>
+
+          <ReferralsAdminTiles summary={summary} />
+
+          <ReferralsAdminFunnel summary={summary} />
+
+          <section data-testid="referrals-referrers">
+            <ContentListTable
+              data={referrers}
+              fields={REFERRER_FIELDS}
+              tableGeneratorType={Modules.ReferralAdminReferrer}
+              context={referrerContext}
+              title={t("referral.admin.referrers.title")}
+              titleActions={copyAll}
+              hidePagination
+              allowSearch={false}
+              emptyState={t("referral.admin.referrers.empty")}
+            />
+          </section>
+
+          <section data-testid="referrals-referrals">
+            <ContentListTable
+              data={referrals}
+              fields={REFERRAL_FIELDS}
+              tableGeneratorType={Modules.ReferralAdminReferral}
+              title={t("referral.admin.referrals.title")}
+              hidePagination
+              allowSearch={false}
+              emptyState={t("referral.admin.referrals.empty")}
+            />
+          </section>
+        </div>
+      </RoundPageContainer>
+    </SharedProvider>
+  );
+}

package/src/features/referral/components/index.ts

@@ -1,3 +1,6 @@
 export { ReferralCodeCapture } from "./ReferralCodeCapture";
 export { ReferralDialog, type ReferralDialogProps, type ReferralDialogTranslations } from "./ReferralDialog";
 export { ReferralWidget, type ReferralWidgetProps, type ReferralWidgetTranslations } from "./ReferralWidget";
+export { ReferralsAdminContainer } from "./containers/ReferralsAdminContainer";
+export { ReferralsAdminTiles } from "./ReferralsAdminTiles";
+export { ReferralsAdminFunnel } from "./ReferralsAdminFunnel";

package/src/features/referral/data/ReferralAdminReferral.ts

@@ -0,0 +1,65 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { ReferralAdminReferralInterface } from "../interfaces/referral-admin.interface";
+
+/** One referral in the administrative list: the new account and who brought it. Read-only. */
+export class ReferralAdminReferral extends AbstractApiData implements ReferralAdminReferralInterface {
+  private _name?: string;
+  private _email?: string;
+  private _referrerName?: string;
+  private _referrerEmail?: string;
+  private _source?: string;
+  private _status?: string;
+  private _referredAt?: Date;
+  private _completedAt?: Date;
+  private _tokensAwarded?: number;
+
+  get name(): string {
+    return this._name ?? "";
+  }
+  get email(): string {
+    return this._email ?? "";
+  }
+  get referrerName(): string {
+    return this._referrerName ?? "";
+  }
+  get referrerEmail(): string {
+    return this._referrerEmail ?? "";
+  }
+  get source(): string {
+    return this._source ?? "";
+  }
+  get status(): string {
+    return this._status ?? "";
+  }
+  get referredAt(): Date {
+    return this._referredAt ?? new Date(0);
+  }
+  get completedAt(): Date | undefined {
+    return this._completedAt;
+  }
+  get tokensAwarded(): number | undefined {
+    return this._tokensAwarded;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._name = attrs.name;
+    this._email = attrs.email;
+    this._referrerName = attrs.referrerName;
+    this._referrerEmail = attrs.referrerEmail;
+    this._source = attrs.source;
+    this._status = attrs.status;
+    this._referredAt = attrs.referredAt ? new Date(attrs.referredAt) : undefined;
+    this._completedAt = attrs.completedAt ? new Date(attrs.completedAt) : undefined;
+    this._tokensAwarded = attrs.tokensAwarded ?? undefined;
+
+    return this;
+  }
+
+  /** The resource is read-only: there are no attributes to send. */
+  createJsonApi(data: { id: string }) {
+    return { data: { type: Modules.ReferralAdminReferral.name, id: data.id, attributes: {} } };
+  }
+}

package/src/features/referral/data/ReferralAdminReferrer.ts

@@ -0,0 +1,65 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { ReferralAdminReferrerInterface } from "../interfaces/referral-admin.interface";
+
+/** One referrer company in the referral ranking. Read-only. */
+export class ReferralAdminReferrer extends AbstractApiData implements ReferralAdminReferrerInterface {
+  private _name?: string;
+  private _email?: string;
+  private _visits?: number;
+  private _invitesSent?: number;
+  private _signupsLink?: number;
+  private _signupsDirect?: number;
+  private _paying?: number;
+  private _creditsEarned?: number;
+  private _lastInviteAt?: Date;
+
+  get name(): string {
+    return this._name ?? "";
+  }
+  get email(): string {
+    return this._email ?? "";
+  }
+  get visits(): number {
+    return this._visits ?? 0;
+  }
+  get invitesSent(): number {
+    return this._invitesSent ?? 0;
+  }
+  get signupsLink(): number {
+    return this._signupsLink ?? 0;
+  }
+  get signupsDirect(): number {
+    return this._signupsDirect ?? 0;
+  }
+  get paying(): number {
+    return this._paying ?? 0;
+  }
+  get creditsEarned(): number {
+    return this._creditsEarned ?? 0;
+  }
+  get lastInviteAt(): Date | undefined {
+    return this._lastInviteAt;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._name = attrs.name;
+    this._email = attrs.email;
+    this._visits = attrs.visits;
+    this._invitesSent = attrs.invitesSent;
+    this._signupsLink = attrs.signupsLink;
+    this._signupsDirect = attrs.signupsDirect;
+    this._paying = attrs.paying;
+    this._creditsEarned = attrs.creditsEarned;
+    this._lastInviteAt = attrs.lastInviteAt ? new Date(attrs.lastInviteAt) : undefined;
+
+    return this;
+  }
+
+  /** The resource is read-only: there are no attributes to send. */
+  createJsonApi(data: { id: string }) {
+    return { data: { type: Modules.ReferralAdminReferrer.name, id: data.id, attributes: {} } };
+  }
+}

package/src/features/referral/data/ReferralAdminService.ts

@@ -0,0 +1,51 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import {
+  ReferralAdminPeriod,
+  ReferralAdminReferralInterface,
+  ReferralAdminReferrerInterface,
+  ReferralAdminSort,
+  ReferralAdminSummaryInterface,
+} from "../interfaces/referral-admin.interface";
+
+/** Reads of the administrative referral report. Every route is administrator-only. */
+export class ReferralAdminService extends AbstractService {
+  /** Headline tiles: one row per window (`current`, plus `previous` unless the period is `all`). */
+  static async getSummary(params: { period: ReferralAdminPeriod }): Promise<ReferralAdminSummaryInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.ReferralAdminSummary });
+    endpoint.addAdditionalParam("period", params.period);
+
+    return this.callApi<ReferralAdminSummaryInterface[]>({
+      type: Modules.ReferralAdminSummary,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /** The referrers ranking, ordered by the allowlisted sort. */
+  static async getReferrers(params: {
+    period: ReferralAdminPeriod;
+    sort: ReferralAdminSort;
+  }): Promise<ReferralAdminReferrerInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.ReferralAdminReferrer });
+    endpoint.addAdditionalParam("period", params.period);
+    endpoint.addAdditionalParam("sort", params.sort);
+
+    return this.callApi<ReferralAdminReferrerInterface[]>({
+      type: Modules.ReferralAdminReferrer,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /** Every referral in the period, newest first. */
+  static async getReferrals(params: { period: ReferralAdminPeriod }): Promise<ReferralAdminReferralInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.ReferralAdminReferral });
+    endpoint.addAdditionalParam("period", params.period);
+
+    return this.callApi<ReferralAdminReferralInterface[]>({
+      type: Modules.ReferralAdminReferral,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+}

package/src/features/referral/data/ReferralAdminSummary.ts

@@ -0,0 +1,60 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { ReferralAdminSummaryInterface } from "../interfaces/referral-admin.interface";
+
+/** One window of the referral report tiles: `current` or `previous`. Read-only. */
+export class ReferralAdminSummary extends AbstractApiData implements ReferralAdminSummaryInterface {
+  private _window?: string;
+  private _visits?: number;
+  private _invitesSent?: number;
+  private _signups?: number;
+  private _paying?: number;
+  private _creditsGiven?: number;
+  private _sharingCompanies?: number;
+  private _eligibleCompanies?: number;
+
+  get window(): string {
+    return this._window ?? "";
+  }
+  get visits(): number {
+    return this._visits ?? 0;
+  }
+  get invitesSent(): number {
+    return this._invitesSent ?? 0;
+  }
+  get signups(): number {
+    return this._signups ?? 0;
+  }
+  get paying(): number {
+    return this._paying ?? 0;
+  }
+  get creditsGiven(): number {
+    return this._creditsGiven ?? 0;
+  }
+  get sharingCompanies(): number {
+    return this._sharingCompanies ?? 0;
+  }
+  get eligibleCompanies(): number {
+    return this._eligibleCompanies ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._window = attrs.window;
+    this._visits = attrs.visits;
+    this._invitesSent = attrs.invitesSent;
+    this._signups = attrs.signups;
+    this._paying = attrs.paying;
+    this._creditsGiven = attrs.creditsGiven;
+    this._sharingCompanies = attrs.sharingCompanies;
+    this._eligibleCompanies = attrs.eligibleCompanies;
+
+    return this;
+  }
+
+  /** The resource is read-only: there are no attributes to send. */
+  createJsonApi(data: { id: string }) {
+    return { data: { type: Modules.ReferralAdminSummary.name, id: data.id, attributes: {} } };
+  }
+}

package/src/features/referral/data/ReferralService.ts

@@ -33,6 +33,26 @@ export class ReferralService extends AbstractService {
       endpoint: endpoint.generate(),
       input: { email },
       overridesJsonApiCreation: true,
+      // The widget turns the error code into a translated message; the global
+      // handler would show the API's English text and swallow the failure.
+      suppressGlobalError: true,
+    });
+  }
+
+  /**
+   * Count one visit to a referral link. Answers 204 whatever the code.
+   */
+  static async recordVisit(params: { referralCode: string }): Promise<void> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.ReferralVisit });
+
+    await this.callApi<void>({
+      type: Modules.ReferralVisit,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      // The request layer builds the body through ReferralVisit.createJsonApi().
+      input: { referralCode: params.referralCode },
+      // A failed beacon must never show an error to a visitor.
+      suppressGlobalError: true,
     });
   }
 }