@carlonicora/nextjs-jsonapi 6.10.1 → 6.11.0

package/src/features/referral/hooks/useReferralAdminReferralTableStructure.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { cellDate } from "../../../components/tables/cells/cell.date";
+import { registerTableGenerator, TableContent, UseTableStructureHook } from "../../../hooks";
+import { Badge } from "../../../shadcnui";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { ReferralAdminReferralInterface } from "../interfaces/referral-admin.interface";
+
+/**
+ * Columns of "Every referral". The values double as the TanStack column ids:
+ * ContentListTable builds its `columnVisibility` from the `fields` array.
+ */
+export enum ReferralAdminReferralFields {
+  account = "account",
+  referrer = "referrer",
+  source = "source",
+  date = "date",
+  status = "status",
+  credits = "credits",
+}
+
+type Row = { row: { original: TableContent<ReferralAdminReferralInterface> } };
+
+export const useReferralAdminReferralTableStructure: UseTableStructureHook<
+  ReferralAdminReferralInterface,
+  ReferralAdminReferralFields
+> = (params) => {
+  const t = useTranslations();
+  const { decimal } = useUsageFormatters();
+
+  const tableData = useMemo(() => {
+    return params.data.map((entry: ReferralAdminReferralInterface) => {
+      const row: TableContent<ReferralAdminReferralInterface> = { jsonApiData: entry };
+      // cellDate reads the value from the row by the column name.
+      row[ReferralAdminReferralFields.date] = entry.referredAt;
+      return row;
+    });
+  }, [params.data]);
+
+  const fieldColumnMap: Record<ReferralAdminReferralFields, () => any> = {
+    [ReferralAdminReferralFields.account]: () => ({
+      id: ReferralAdminReferralFields.account,
+      header: t("referral.admin.referrals.columns.account"),
+      cell: ({ row }: Row) => {
+        const entry = row.original.jsonApiData;
+        return (
+          <div className="flex flex-col">
+            <span className="text-sm">{entry.name}</span>
+            <span className="text-muted-foreground text-xs">{entry.email}</span>
+          </div>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferralFields.referrer]: () => ({
+      id: ReferralAdminReferralFields.referrer,
+      header: t("referral.admin.referrals.columns.referrer"),
+      cell: ({ row }: Row) => {
+        const entry = row.original.jsonApiData;
+        return (
+          <div className="flex flex-col">
+            <span className="text-sm">{entry.referrerName}</span>
+            <span className="text-muted-foreground text-xs">{entry.referrerEmail}</span>
+          </div>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferralFields.source]: () => ({
+      id: ReferralAdminReferralFields.source,
+      header: t("referral.admin.referrals.columns.source"),
+      cell: ({ row }: Row) => {
+        const source = row.original.jsonApiData.source;
+        if (source === "link") return <Badge variant="softBlue">{t("referral.admin.source.link")}</Badge>;
+        if (source === "direct") return <Badge variant="softGray">{t("referral.admin.source.direct")}</Badge>;
+        // A referral written before the source was recorded: unknown, not guessed.
+        return <span className="text-muted-foreground text-xs">—</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferralFields.date]: () =>
+      cellDate({ name: ReferralAdminReferralFields.date, title: t("referral.admin.referrals.columns.date") }),
+    [ReferralAdminReferralFields.status]: () => ({
+      id: ReferralAdminReferralFields.status,
+      header: t("referral.admin.referrals.columns.status"),
+      cell: ({ row }: Row) =>
+        row.original.jsonApiData.status === "completed" ? (
+          <Badge variant="softGreen">{t("referral.admin.status.completed")}</Badge>
+        ) : (
+          <Badge variant="softYellow">{t("referral.admin.status.pending")}</Badge>
+        ),
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferralFields.credits]: () => ({
+      id: ReferralAdminReferralFields.credits,
+      header: t("referral.admin.referrals.columns.credits"),
+      cell: ({ row }: Row) => {
+        const entry = row.original.jsonApiData;
+        // Both sides receive the same award: shown as "200 + 200", as in the approved mock.
+        if (entry.status !== "completed" || !entry.tokensAwarded)
+          return <span className="block text-muted-foreground text-xs text-end">—</span>;
+        const award = decimal(entry.tokensAwarded, 0);
+        return <span className="block text-xs tabular-nums text-end">{`${award} + ${award}`}</span>;
+      },
+      meta: { className: "text-end" },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<ReferralAdminReferralInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, decimal]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("referrals/administration/referrals", useReferralAdminReferralTableStructure);

package/src/features/referral/hooks/useReferralAdminReferrerTableStructure.tsx

@@ -0,0 +1,229 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { CopyIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { cellDate } from "../../../components/tables/cells/cell.date";
+import { registerTableGenerator, TableContent, UseTableStructureHook } from "../../../hooks";
+import { Button } from "../../../shadcnui";
+import { showError, showToast } from "../../../utils";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { ReferralAdminReferrerInterface, ReferralAdminSort } from "../interfaces/referral-admin.interface";
+
+/**
+ * Columns of the referrers ranking. The values double as the TanStack column
+ * ids: ContentListTable builds its `columnVisibility` from the `fields` array,
+ * so a column whose id differs from its field is invisible.
+ */
+export enum ReferralAdminReferrerFields {
+  rank = "rank",
+  referrer = "referrer",
+  visits = "visits",
+  invites = "invites",
+  signups = "signups",
+  paying = "paying",
+  conversion = "conversion",
+  credits = "credits",
+  lastInvite = "lastInvite",
+}
+
+/** What the container passes through ContentListTable's `context`: the active sort and its setter. */
+export type ReferralAdminReferrerTableContext = {
+  sort: ReferralAdminSort;
+  onSort: (sort: ReferralAdminSort) => void;
+};
+
+/**
+ * Copies text to the clipboard from inside a click handler, with the toast on
+ * success and the error toast on refusal (a denied permission or an insecure
+ * context). Shared by the per-row button and the container's "Copy all emails".
+ */
+export async function copyReferrerEmails(
+  text: string,
+  t: (key: string, values?: Record<string, string | number>) => string,
+): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text);
+    showToast(t("referral.admin.referrers.copied"));
+  } catch {
+    showError(t("referral.admin.referrers.copyFailed"));
+  }
+}
+
+const NUMERIC = { className: "text-end" };
+
+export const useReferralAdminReferrerTableStructure: UseTableStructureHook<
+  ReferralAdminReferrerInterface,
+  ReferralAdminReferrerFields
+> = (params) => {
+  const t = useTranslations();
+  const { decimal } = useUsageFormatters();
+  const context = params.context as ReferralAdminReferrerTableContext | undefined;
+
+  const tableData = useMemo(() => {
+    return params.data.map((entry: ReferralAdminReferrerInterface, index: number) => {
+      const row: TableContent<ReferralAdminReferrerInterface> = { jsonApiData: entry };
+      row[ReferralAdminReferrerFields.rank] = index + 1;
+      // cellDate reads the value from the row by the column name.
+      row[ReferralAdminReferrerFields.lastInvite] = entry.lastInviteAt;
+      return row;
+    });
+  }, [params.data]);
+
+  /** Header of a sortable column: a button that sets the sort the API reads (D8). */
+  const sortableHeader = (sort: ReferralAdminSort, label: string) => () => {
+    const active = context?.sort === sort;
+    return (
+      <Button
+        type="button"
+        variant="ghost"
+        size="xs"
+        className={active ? "text-primary" : "text-muted-foreground"}
+        title={t("referral.admin.referrers.sortBy")}
+        aria-sort={active ? "descending" : undefined}
+        data-testid={active ? "referrals-referrers-sort" : undefined}
+        onClick={() => context?.onSort(sort)}
+      >
+        {label}
+      </Button>
+    );
+  };
+
+  // Typography role 15 (numeric): tabular-nums, end-aligned.
+  const numericCell = (read: (entry: ReferralAdminReferrerInterface) => number) => {
+    return ({ row }: { row: { original: TableContent<ReferralAdminReferrerInterface> } }) => (
+      <span className="block text-xs tabular-nums text-end">{decimal(read(row.original.jsonApiData), 0)}</span>
+    );
+  };
+
+  const fieldColumnMap: Record<ReferralAdminReferrerFields, () => any> = {
+    [ReferralAdminReferrerFields.rank]: () => ({
+      id: ReferralAdminReferrerFields.rank,
+      header: "#",
+      cell: ({ row }: { row: { original: TableContent<ReferralAdminReferrerInterface> } }) => (
+        <span className="text-muted-foreground text-xs tabular-nums">
+          {row.original[ReferralAdminReferrerFields.rank]}
+        </span>
+      ),
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.referrer]: () => ({
+      id: ReferralAdminReferrerFields.referrer,
+      header: t("referral.admin.referrers.columns.referrer"),
+      cell: ({ row }: { row: { original: TableContent<ReferralAdminReferrerInterface> } }) => {
+        const entry = row.original.jsonApiData;
+        return (
+          <div className="flex items-center gap-2">
+            <div className="flex flex-col">
+              <span className="text-sm">{entry.name}</span>
+              <span className="text-muted-foreground text-xs">{entry.email}</span>
+            </div>
+            {entry.email && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-xs"
+                aria-label={t("referral.admin.referrers.copyEmail")}
+                title={t("referral.admin.referrers.copyEmail")}
+                data-testid={`referrals-copy-email-${entry.id}`}
+                onClick={() => copyReferrerEmails(entry.email, t)}
+              >
+                <CopyIcon />
+              </Button>
+            )}
+          </div>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.visits]: () => ({
+      id: ReferralAdminReferrerFields.visits,
+      header: t("referral.admin.referrers.columns.visits"),
+      cell: numericCell((entry) => entry.visits),
+      meta: NUMERIC,
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.invites]: () => ({
+      id: ReferralAdminReferrerFields.invites,
+      header: sortableHeader("invites", t("referral.admin.referrers.columns.invites")),
+      cell: numericCell((entry) => entry.invitesSent),
+      meta: NUMERIC,
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.signups]: () => ({
+      id: ReferralAdminReferrerFields.signups,
+      header: sortableHeader("signups", t("referral.admin.referrers.columns.signups")),
+      cell: ({ row }: { row: { original: TableContent<ReferralAdminReferrerInterface> } }) => {
+        const entry = row.original.jsonApiData;
+        return (
+          <div className="flex flex-col items-end">
+            <span className="text-xs tabular-nums">{decimal(entry.signupsLink + entry.signupsDirect, 0)}</span>
+            <span className="text-muted-foreground text-xs">
+              {t("referral.admin.referrers.split", { link: entry.signupsLink, direct: entry.signupsDirect })}
+            </span>
+          </div>
+        );
+      },
+      meta: NUMERIC,
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.paying]: () => ({
+      id: ReferralAdminReferrerFields.paying,
+      header: sortableHeader("paying", t("referral.admin.referrers.columns.paying")),
+      cell: numericCell((entry) => entry.paying),
+      meta: NUMERIC,
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.conversion]: () => ({
+      id: ReferralAdminReferrerFields.conversion,
+      header: sortableHeader("conversion", t("referral.admin.referrers.columns.conversion")),
+      cell: ({ row }: { row: { original: TableContent<ReferralAdminReferrerInterface> } }) => {
+        const entry = row.original.jsonApiData;
+        // Conversion = paying / emails sent; a referrer who sent none has no rate.
+        if (!entry.invitesSent) return <span className="block text-muted-foreground text-xs text-end">—</span>;
+        const rate = Math.round((entry.paying / entry.invitesSent) * 100);
+        return (
+          <span className="flex items-center justify-end gap-1.5">
+            <span className="bg-primary/15 relative h-1.5 w-12 overflow-hidden rounded-full">
+              <span className="bg-primary absolute inset-y-0 start-0" style={{ width: `${Math.min(rate, 100)}%` }} />
+            </span>
+            <span className="text-xs tabular-nums">{`${decimal(rate, 0)}%`}</span>
+          </span>
+        );
+      },
+      meta: NUMERIC,
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.credits]: () => ({
+      id: ReferralAdminReferrerFields.credits,
+      header: sortableHeader("credits", t("referral.admin.referrers.columns.credits")),
+      cell: numericCell((entry) => entry.creditsEarned),
+      meta: NUMERIC,
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [ReferralAdminReferrerFields.lastInvite]: () =>
+      cellDate({
+        name: ReferralAdminReferrerFields.lastInvite,
+        title: t("referral.admin.referrers.columns.lastInvite"),
+      }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<ReferralAdminReferrerInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, decimal, context?.sort]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("referrals/administration/referrers", useReferralAdminReferrerTableStructure);

package/src/features/referral/hooks/useReferralInvite.ts

@@ -23,6 +23,8 @@ export function useReferralInvite() {
       setSuccess(true);
     } catch (err) {
       setError(err as Error);
+      // Rethrown so the caller can tell a refused invite from a sent one.
+      throw err;
     } finally {
       setSending(false);
     }

package/src/features/referral/index.ts

@@ -19,3 +19,4 @@ export * from "./components";
 // Modules
 export * from "./referral.module";
 export * from "./referral-stats.module";
+export * from "./referral-admin.modules";

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

@@ -1 +1,2 @@
 export * from "./referral.interface";
+export * from "./referral-admin.interface";

package/src/features/referral/interfaces/referral-admin.interface.ts

@@ -0,0 +1,45 @@
+import { ApiDataInterface } from "../../../core";
+
+/** Report window of the administrative referral page. */
+export type ReferralAdminPeriod = "30d" | "90d" | "all";
+
+/** The referrers ranking order the API allowlists. */
+export type ReferralAdminSort = "paying" | "signups" | "invites" | "conversion" | "credits";
+
+/** One window (`current` or `previous`) of the headline tiles. */
+export interface ReferralAdminSummaryInterface extends ApiDataInterface {
+  get window(): string;
+  get visits(): number;
+  get invitesSent(): number;
+  get signups(): number;
+  get paying(): number;
+  get creditsGiven(): number;
+  get sharingCompanies(): number;
+  get eligibleCompanies(): number;
+}
+
+/** One referrer company in the ranking; the id is the company id. */
+export interface ReferralAdminReferrerInterface extends ApiDataInterface {
+  get name(): string;
+  get email(): string;
+  get visits(): number;
+  get invitesSent(): number;
+  get signupsLink(): number;
+  get signupsDirect(): number;
+  get paying(): number;
+  get creditsEarned(): number;
+  get lastInviteAt(): Date | undefined;
+}
+
+/** One referral (new account and who brought it); the id is the Referral id. */
+export interface ReferralAdminReferralInterface extends ApiDataInterface {
+  get name(): string;
+  get email(): string;
+  get referrerName(): string;
+  get referrerEmail(): string;
+  get source(): string;
+  get status(): string;
+  get referredAt(): Date;
+  get completedAt(): Date | undefined;
+  get tokensAwarded(): number | undefined;
+}

package/src/features/referral/referral-admin.modules.ts

@@ -0,0 +1,32 @@
+import { GiftIcon } from "lucide-react";
+import { ModuleFactory, ModuleWithPermissions } from "../../permissions";
+import { ReferralAdminReferral } from "./data/ReferralAdminReferral";
+import { ReferralAdminReferrer } from "./data/ReferralAdminReferrer";
+import { ReferralAdminSummary } from "./data/ReferralAdminSummary";
+import { ReferralVisit } from "./data/ReferralVisit";
+
+/**
+ * The referral visit and administrative report resources, as one object a
+ * consuming app spreads into its `allModules` (same rationale as
+ * `analyticsModules`). An app records link visits only once it spreads this.
+ * None has a pageUrl: these are not navigable resources.
+ */
+export const referralAdminModules = (factory: ModuleFactory) =>
+  ({
+    ReferralVisit: factory({ name: "referrals/visits", model: ReferralVisit }),
+    ReferralAdminSummary: factory({
+      name: "referrals/administration/summary",
+      model: ReferralAdminSummary,
+      icon: GiftIcon,
+    }),
+    ReferralAdminReferrer: factory({
+      name: "referrals/administration/referrers",
+      model: ReferralAdminReferrer,
+      icon: GiftIcon,
+    }),
+    ReferralAdminReferral: factory({
+      name: "referrals/administration/referrals",
+      model: ReferralAdminReferral,
+      icon: GiftIcon,
+    }),
+  }) satisfies Record<string, ModuleWithPermissions>;

package/dist/chunk-3TNGKMJU.mjs

@@ -1,115 +0,0 @@
-import {
-  getTokenUsageCurrency
-} from "./chunk-6HFRXEF5.mjs";
-import {
-  __name
-} from "./chunk-PAWJFY3S.mjs";
-
-// src/features/tokenusage/lib/formatters.ts
-import { useLocale } from "next-intl";
-import { useMemo } from "react";
-function createUsageFormatters(locale, currency) {
-  const symbol = new Intl.NumberFormat(locale, { style: "currency", currency, currencyDisplay: "narrowSymbol" }).formatToParts(0).find((part) => part.type === "currency")?.value ?? currency;
-  const decimal = /* @__PURE__ */ __name((value, decimals) => value.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals }), "decimal");
-  const dayFormat = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", timeZone: "UTC" });
-  const monthFormat = new Intl.DateTimeFormat(locale, { month: "short", year: "numeric", timeZone: "UTC" });
-  const compactFormat = new Intl.NumberFormat(locale, { notation: "compact", maximumSignificantDigits: 3 });
-  const collator = new Intl.Collator(locale);
-  return {
-    decimal,
-    metricValue(value, metric) {
-      if (metric === "cost") return `${symbol} ${decimal(value, 2)}`;
-      if (metric === "credits") return decimal(value, 1);
-      return decimal(value, 0);
-    },
-    currency(value, decimals) {
-      return `${symbol} ${decimal(value, decimals)}`;
-    },
-    percent(value, decimals = 1) {
-      return `${decimal(value, decimals)} %`;
-    },
-    compact(value) {
-      return compactFormat.format(value);
-    },
-    bucketDate(iso, granularity) {
-      const date = /* @__PURE__ */ new Date(`${iso}T00:00:00.000Z`);
-      return granularity === "month" ? monthFormat.format(date) : dayFormat.format(date);
-    },
-    compare(a, b) {
-      return collator.compare(a, b);
-    }
-  };
-}
-__name(createUsageFormatters, "createUsageFormatters");
-function useUsageFormatters() {
-  const locale = useLocale();
-  const currency = getTokenUsageCurrency();
-  return useMemo(() => createUsageFormatters(locale, currency), [locale, currency]);
-}
-__name(useUsageFormatters, "useUsageFormatters");
-
-// src/features/tokenusage/lib/palette.ts
-var CATEGORICAL_LIGHT = [
-  "#2a78d6",
-  "#eb6834",
-  "#1baf7a",
-  "#eda100",
-  "#e87ba4",
-  "#008300",
-  "#4a3aa7"
-];
-var CATEGORICAL_DARK = [
-  "#3987e5",
-  "#d95926",
-  "#199e70",
-  "#c98500",
-  "#d55181",
-  "#008300",
-  "#9085e9"
-];
-var CATEGORICAL_CEILING = CATEGORICAL_LIGHT.length;
-var OTHER_COLOR = "#898781";
-var SEQUENTIAL_RAMP_LIGHT = ["#104281", "#1c5cab", "#2a78d6", "#5598e7", "#86b6ef"];
-var SEQUENTIAL_RAMP = SEQUENTIAL_RAMP_LIGHT;
-var categoricalSet = /* @__PURE__ */ __name((mode) => mode === "dark" ? CATEGORICAL_DARK : CATEGORICAL_LIGHT, "categoricalSet");
-function seriesColor(index, mode = "light") {
-  if (index < 0 || index >= CATEGORICAL_CEILING) return OTHER_COLOR;
-  return categoricalSet(mode)[index];
-}
-__name(seriesColor, "seriesColor");
-function seriesTheme(index) {
-  return { light: seriesColor(index, "light"), dark: seriesColor(index, "dark") };
-}
-__name(seriesTheme, "seriesTheme");
-
-// src/features/tokenusage/lib/metrics.ts
-function metricValue(row, metric) {
-  if (metric === "cost") return row.cost;
-  if (metric === "credits") return row.credits;
-  return row.tokensIn + row.tokensOut;
-}
-__name(metricValue, "metricValue");
-function cacheHitPercentage(cached, tokensIn) {
-  if (!tokensIn) return 0;
-  return cached / tokensIn * 100;
-}
-__name(cacheHitPercentage, "cacheHitPercentage");
-function percentageDelta(current, previous) {
-  if (!previous) return void 0;
-  return Math.round((current - previous) / previous * 100);
-}
-__name(percentageDelta, "percentageDelta");
-
-export {
-  createUsageFormatters,
-  useUsageFormatters,
-  metricValue,
-  cacheHitPercentage,
-  percentageDelta,
-  CATEGORICAL_CEILING,
-  OTHER_COLOR,
-  SEQUENTIAL_RAMP,
-  seriesColor,
-  seriesTheme
-};
-//# sourceMappingURL=chunk-3TNGKMJU.mjs.map

package/dist/chunk-3TNGKMJU.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/features/tokenusage/lib/formatters.ts","../src/features/tokenusage/lib/palette.ts","../src/features/tokenusage/lib/metrics.ts"],"sourcesContent":["\"use client\";\n\nimport { useLocale } from \"next-intl\";\nimport { useMemo } from \"react\";\nimport type { Metric } from \"../data/tokenusage-admin.types\";\nimport { getTokenUsageCurrency } from \"./config\";\n\nexport type UsageFormatters = {\n  /** Locale-aware fixed-decimal number, e.g. 9.46 → \"9,46\" in it-IT. */\n  decimal(value: number, decimals: number): string;\n  /** Currency for cost, 2 decimals for credits, whole numbers for tokens. */\n  metricValue(value: number, metric: Metric): string;\n  /** Currency with an explicit decimal count — the per-call tile needs 4. */\n  currency(value: number, decimals: number): string;\n  /** Percentage with one decimal by default, e.g. 60 → \"60,0 %\" in it-IT. */\n  percent(value: number, decimals?: number): string;\n  /** Compact notation for axis ticks, e.g. 1500000 → \"1,5 Mln\" in it-IT. */\n  compact(value: number): string;\n  /** A \"YYYY-MM-DD\" bucket key rendered as an axis or tooltip label, in UTC. */\n  bucketDate(iso: string, granularity: \"day\" | \"week\" | \"month\"): string;\n  /** Locale collation for client-side table sorting. */\n  compare(a: string, b: string): number;\n};\n\n/**\n * Builds every formatter the token-usage surfaces need, for one locale and one\n * currency.\n *\n * A pure factory on purpose: it takes no React context, so the arithmetic and\n * the formatting are unit-testable without rendering, and a server component or\n * a test can construct a set for an arbitrary locale.\n *\n * The currency symbol is placed with a space rather than through\n * `style: \"currency\"`, which is what the previous hard-coded implementation\n * rendered (\"€ 9,46\"). Keeping that shape means a consuming app on EUR sees\n * byte-identical output after this refactor.\n *\n * `bucketDate` formats in UTC, always. The wire value is a `type: \"date\"` — a\n * calendar day — parsed to UTC midnight; reading it back with local getters\n * would shift the label a day early west of UTC.\n */\nexport function createUsageFormatters(locale: string, currency: string): UsageFormatters {\n  const symbol =\n    new Intl.NumberFormat(locale, { style: \"currency\", currency, currencyDisplay: \"narrowSymbol\" })\n      .formatToParts(0)\n      .find((part) => part.type === \"currency\")?.value ?? currency;\n\n  const decimal = (value: number, decimals: number): string =>\n    value.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });\n\n  const dayFormat = new Intl.DateTimeFormat(locale, { day: \"numeric\", month: \"short\", timeZone: \"UTC\" });\n  const monthFormat = new Intl.DateTimeFormat(locale, { month: \"short\", year: \"numeric\", timeZone: \"UTC\" });\n  // Axis ticks step by 1, 2, 2.5 or 5 times a power of ten, so a tick never needs\n  // more than three significant digits. A fixed one-decimal cap rounded a 0.05\n  // step into repeated labels (0.1, 0.1, 0.2, 0.2); significant digits keep every\n  // tick distinct at any scale (0.05, 0.15, 1.25K).\n  const compactFormat = new Intl.NumberFormat(locale, { notation: \"compact\", maximumSignificantDigits: 3 });\n  const collator = new Intl.Collator(locale);\n\n  return {\n    decimal,\n\n    metricValue(value, metric) {\n      if (metric === \"cost\") return `${symbol} ${decimal(value, 2)}`;\n      // Credits are stored to 4 decimals (round4(cost / creditCost)), but that\n      // precision is noise to a reader comparing rows: one decimal is enough to\n      // separate two values and keeps the columns narrow enough to scan.\n      if (metric === \"credits\") return decimal(value, 1);\n      return decimal(value, 0);\n    },\n\n    currency(value, decimals) {\n      return `${symbol} ${decimal(value, decimals)}`;\n    },\n\n    percent(value, decimals = 1) {\n      return `${decimal(value, decimals)} %`;\n    },\n\n    compact(value) {\n      return compactFormat.format(value);\n    },\n\n    bucketDate(iso, granularity) {\n      const date = new Date(`${iso}T00:00:00.000Z`);\n      return granularity === \"month\" ? monthFormat.format(date) : dayFormat.format(date);\n    },\n\n    compare(a, b) {\n      return collator.compare(a, b);\n    },\n  };\n}\n\n/**\n * The formatter set for the current request's locale and the app's configured\n * currency. Memoised on both, so the Intl objects are built once per locale\n * rather than on every render.\n */\nexport function useUsageFormatters(): UsageFormatters {\n  const locale = useLocale();\n  const currency = getTokenUsageCurrency();\n  return useMemo(() => createUsageFormatters(locale, currency), [locale, currency]);\n}\n","/**\n * Chart palette for the administrative token-usage dashboard.\n *\n * Every value here is a documented step of the dataviz skill's reference ramps —\n * nothing was eyeballed, nothing was hand-mixed. The palette was run through the\n * skill's validator against THIS application's real chart surfaces in both modes.\n * The verbatim output is below.\n *\n * The surface is `--card`, NOT `--background`. Every chart that uses this palette\n * is painted inside a `<Card>`, so the card is the surface the marks actually sit\n * on — and in dark mode it is the *lighter* of the two (`oklch(0.205 0 0)` vs the\n * background's `oklch(0.145 0 0)`), which is the harder case for contrast. Taken\n * from `apps/web/src/app/globals.css` (narr8 declares two `:root`/`.dark` pairs;\n * the LATER pair wins, and it is the one read here) — light `oklch(1 0 0)`, dark\n * `oklch(0.205 0 0)`. a360ai declares the same two values.\n *\n * oklch→hex conversion: the algebraic inverse of the Björn Ottosson OKLab\n * matrices — the same matrices the validator applies in the forward direction —\n * giving light `#ffffff` and dark `#171717`. Cross-checked by feeding it the\n * previously recorded background value, which it reproduces exactly:\n * `oklch(0.145 0 0)` → `#0a0a0a`. ✓\n *\n * Light and dark are two SELECTED sets of steps, chosen for their own surface —\n * never one set with its lightness flipped at runtime. Consumers pick a set from\n * the resolved theme (`seriesColor(i, mode)` / `sequentialColor(i, mode)`).\n *\n * ---------------------------------------------------------------------------\n * VALIDATOR OUTPUT — dataviz `scripts/validate_palette.js`, run 2026-08-15\n * ---------------------------------------------------------------------------\n *\n * $ node scripts/validate_palette.js \"#2a78d6,#eb6834,#1baf7a,#eda100,#e87ba4,#008300,#4a3aa7\" --mode light --surface \"#ffffff\"\n *\n * Palette (light, surface #ffffff, categorical): 7 slots\n *   [PASS] Lightness band         all 7 inside L 0.43–0.77\n *   [PASS] Chroma floor           all 7 >= 0.1\n *   [PASS] CVD separation         worst adjacent #eda100↔#1baf7a ΔE 9.1 (protan) · tritan 5.8\n *   [PASS] Normal-vision floor    worst adjacent #e87ba4↔#eda100 ΔE 19.6 (normal)\n *   [WARN] Contrast vs surface    below 3:1 — relief required (visible labels or table view): [[\"#1baf7a\",2.82],[\"#eda100\",2.17],[\"#e87ba4\",2.69]]\n *\n *   → ALL CHECKS PASS  (CVD in the 6–8 floor band is legal ONLY with secondary encoding: direct labels, gaps, or texture)\n *   scope: categorical palettes only. For a lone status/text color check WCAG text contrast; for a sequential ramp, lightness monotonicity.\n *\n * $ node scripts/validate_palette.js \"#3987e5,#d95926,#199e70,#c98500,#d55181,#008300,#9085e9\" --mode dark --surface \"#171717\"\n *\n * Palette (dark, surface #171717, categorical): 7 slots\n *   [PASS] Lightness band         all 7 inside L 0.48–0.67\n *   [PASS] Chroma floor           all 7 >= 0.1\n *   [PASS] CVD separation         worst adjacent #c98500↔#199e70 ΔE 8.4 (protan) · tritan 8.7\n *   [PASS] Normal-vision floor    worst adjacent #d55181↔#c98500 ΔE 19.3 (normal)\n *   [PASS] Contrast vs surface    all 7 >= 3:1\n *\n *   → ALL CHECKS PASS  (CVD in the 6–8 floor band is legal ONLY with secondary encoding: direct labels, gaps, or texture)\n *   scope: categorical palettes only. For a lone status/text color check WCAG text contrast; for a sequential ramp, lightness monotonicity.\n *\n * $ node scripts/validate_palette.js \"#104281,#1c5cab,#2a78d6,#5598e7,#86b6ef\" --mode light --surface \"#ffffff\" --ordinal\n *\n * Palette (light, surface #ffffff, ordinal ramp): 5 slots\n *   [PASS] Lightness monotone     steps read light→dark\n *   [PASS] Adjacent ΔL            all gaps >= 0.06\n *   [PASS] Light-end contrast     #86b6ef at 2.11:1 vs surface\n *   [PASS] Single hue             hue spread 3°\n *\n *   → ALL CHECKS PASS  (ordinal: one hue, monotone L, visible step gaps, light end clears surface)\n *\n * $ node scripts/validate_palette.js \"#9ec5f4,#6da7ec,#3987e5,#256abf,#184f95\" --mode dark --surface \"#171717\" --ordinal\n *\n * Palette (dark, surface #171717, ordinal ramp): 5 slots\n *   [PASS] Lightness monotone     steps read light→dark\n *   [PASS] Adjacent ΔL            all gaps >= 0.06\n *   [PASS] Light-end contrast     #184f95 at 2.21:1 vs surface\n *   [PASS] Single hue             hue spread 3°\n *\n *   → ALL CHECKS PASS  (ordinal: one hue, monotone L, visible step gaps, light end clears surface)\n *\n * OTHER_COLOR is achromatic, so the categorical checks (which gate hue identity)\n * do not apply to it; it was gated on contrast alone with the validator's own\n * `contrast()` export: 3.59:1 on `#ffffff`, 4.99:1 on `#171717` — both clear 3:1.\n *\n * ---------------------------------------------------------------------------\n * WHAT THE RESULTS OBLIGE US TO DO\n * ---------------------------------------------------------------------------\n *\n * - NO COLOUR VALUE CHANGED in the move from `--background` to `--card`. Every\n *   gate that passed on the background still passes on the card, so re-stepping\n *   a hue would have been churn, not a fix. Only the recorded surface, the\n *   recorded numbers and this prose changed.\n * - The dark set still clears 3:1 on the LIGHTER card surface: the worst slot is\n *   green `#008300` at 3.63:1, and the ordinal ramp's surface-nearest step lands\n *   at 2.21:1 (down from 2.44:1 on the background) — still above the 2:1 gate.\n *   That headroom is thin, so a future card-surface lightening MUST re-run these\n *   four commands rather than assume the set still holds.\n * - The light-mode contrast WARN is NOT dismissable. Three slots (aqua, yellow,\n *   magenta) sit below 3:1 on white, so every surface that paints with this\n *   palette MUST ship the relief channel: a visible legend, direct labels and a\n *   tooltip carrying the value in text. The timeline chart and the breakdown\n *   table both do. The light card is `#ffffff`, identical to the light\n *   background, so this WARN is unchanged rather than newly incurred.\n * - CVD separation is measured on ADJACENT pairs, which is the correct pairlist\n *   for stacked bars, grouped bars and lines — the only forms this palette paints.\n *   A scatter / bubble / small-multiples chart would need `--pairs all`, which\n *   caps the usable slot count at three; do not reuse this array there without\n *   re-running the validator with that flag.\n */\n\n/** Which surface the colours are being painted on. */\nexport type ChartMode = \"light\" | \"dark\";\n\n/**\n * The chart surfaces the palette was validated against (globals.css `--card`).\n *\n * `--card`, never `--background`: the charts are painted inside a `<Card>`.\n */\nexport const CHART_SURFACE: Readonly<Record<ChartMode, string>> = {\n  light: \"#ffffff\",\n  dark: \"#171717\",\n};\n\n/**\n * Categorical slots, in FIXED order. Slot n is series n — the order is the\n * CVD-safety mechanism, not decoration, so it is never re-ordered and never\n * cycled. The two-series default (customer / platform) takes slots 0 and 1.\n *\n * Hues, in order: blue, orange, aqua, yellow, magenta, green, violet.\n */\nconst CATEGORICAL_LIGHT: readonly string[] = [\n  \"#2a78d6\",\n  \"#eb6834\",\n  \"#1baf7a\",\n  \"#eda100\",\n  \"#e87ba4\",\n  \"#008300\",\n  \"#4a3aa7\",\n];\n\n/** The same seven hues, re-stepped for the dark surface. Not a lightness flip. */\nconst CATEGORICAL_DARK: readonly string[] = [\n  \"#3987e5\",\n  \"#d95926\",\n  \"#199e70\",\n  \"#c98500\",\n  \"#d55181\",\n  \"#008300\",\n  \"#9085e9\",\n];\n\n/**\n * The default (light-surface) categorical set.\n *\n * Prefer `seriesColor(index, mode)` — this array exists for consumers that only\n * need the documented default order.\n */\nexport const CATEGORICAL: readonly string[] = CATEGORICAL_LIGHT;\n\n/**\n * How many series may carry their own identity hue. An 8th series is NEVER a\n * generated hue: it folds into `other`.\n */\nexport const CATEGORICAL_CEILING = CATEGORICAL_LIGHT.length;\n\n/**\n * The \"other\" rollup colour: deliberately achromatic so it reads as \"not an\n * identity\" beside the seven hues. Same step in both modes — it clears 3:1 on\n * both card surfaces (3.59:1 on `#ffffff`, 4.99:1 on `#171717`).\n */\nexport const OTHER_COLOR = \"#898781\";\n\n/**\n * Sequential (single-hue, blue) ramp for MAGNITUDE, indexed by rank position:\n * index 0 is rank 1 — the largest value — so the strongest step leads.\n *\n * On the light surface \"strongest\" is the darkest step; on the dark surface it\n * is the lightest. The anchor flips with the surface, which is why there are two\n * selected sets rather than one array reversed at runtime.\n *\n * Five steps, not eight: with the adjacent-ΔL ≥ 0.06 gate and the ≥ 2:1\n * surface-contrast gate on the step nearest the surface, the blue ramp fits\n * exactly five distinguishable steps. Consumers clamp past the end.\n */\nconst SEQUENTIAL_RAMP_LIGHT: readonly string[] = [\"#104281\", \"#1c5cab\", \"#2a78d6\", \"#5598e7\", \"#86b6ef\"];\n\nconst SEQUENTIAL_RAMP_DARK: readonly string[] = [\"#9ec5f4\", \"#6da7ec\", \"#3987e5\", \"#256abf\", \"#184f95\"];\n\n/**\n * The default (light-surface) sequential ramp.\n *\n * Prefer `sequentialColor(index, mode)` — this array exists for consumers that\n * only need the documented default.\n */\nexport const SEQUENTIAL_RAMP: readonly string[] = SEQUENTIAL_RAMP_LIGHT;\n\nconst categoricalSet = (mode: ChartMode): readonly string[] => (mode === \"dark\" ? CATEGORICAL_DARK : CATEGORICAL_LIGHT);\n\nconst sequentialSet = (mode: ChartMode): readonly string[] =>\n  mode === \"dark\" ? SEQUENTIAL_RAMP_DARK : SEQUENTIAL_RAMP_LIGHT;\n\n/**\n * The identity colour for series `index`.\n *\n * Never generates a hue and never cycles: anything at or past the ceiling gets\n * `OTHER_COLOR`, because a series past the ceiling should already have been\n * folded into the \"other\" bucket by the caller.\n */\nexport function seriesColor(index: number, mode: ChartMode = \"light\"): string {\n  if (index < 0 || index >= CATEGORICAL_CEILING) return OTHER_COLOR;\n  return categoricalSet(mode)[index];\n}\n\n/**\n * Both mode steps for series `index`, shaped for a shadcn `ChartConfig` entry's\n * `theme` field.\n */\nexport function seriesTheme(index: number): { light: string; dark: string } {\n  return { light: seriesColor(index, \"light\"), dark: seriesColor(index, \"dark\") };\n}\n\n/**\n * The magnitude colour for rank position `index`, clamped to the last step so a\n * long list keeps its weakest step rather than falling off the ramp.\n */\nexport function sequentialColor(index: number, mode: ChartMode = \"light\"): string {\n  const ramp = sequentialSet(mode);\n  const clamped = Math.min(Math.max(index, 0), ramp.length - 1);\n  return ramp[clamped];\n}\n","import type { Metric } from \"../data/tokenusage-admin.types\";\n\n/**\n * Locale-free arithmetic for the token-usage surfaces.\n *\n * Everything that turns a number into a STRING lives in `./formatters` instead,\n * because it depends on the request's locale and the app's configured currency.\n * This file stays pure arithmetic so it needs neither.\n */\n\n/**\n * The metric field set every admin token-usage resource carries. Declared\n * structurally so it accepts the summary, timeline and breakdown interfaces\n * alike — all three expose exactly these getters.\n */\nexport type TokenUsageMetrics = {\n  cost: number;\n  credits: number;\n  tokensIn: number;\n  tokensOut: number;\n  cached: number;\n  calls: number;\n};\n\n/** Reads the single number a row contributes for the currently selected metric. */\nexport function metricValue(row: TokenUsageMetrics, metric: Metric): number {\n  if (metric === \"cost\") return row.cost;\n  if (metric === \"credits\") return row.credits;\n  return row.tokensIn + row.tokensOut;\n}\n\n/**\n * Share of cached input tokens. Returns 0 rather than NaN when the window holds\n * no input tokens at all, so the tile renders \"0,0 %\" instead of \"NaN %\".\n */\nexport function cacheHitPercentage(cached: number, tokensIn: number): number {\n  if (!tokensIn) return 0;\n  return (cached / tokensIn) * 100;\n}\n\n/**\n * Percentage change of `current` against `previous`, rounded to a whole number.\n *\n * Returns `undefined` when the previous window is zero — there is no meaningful\n * percentage change from nothing, and rendering Infinity would be worse than\n * rendering nothing. Callers show an em dash in that slot.\n */\nexport function percentageDelta(current: number, previous: number): number | undefined {\n  if (!previous) return undefined;\n  return Math.round(((current - previous) / previous) * 100);\n}\n"],"mappings":"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","names":[]}