@carlonicora/nextjs-jsonapi 1.141.3 → 1.143.0

package/src/features/company/data/company.ts

@@ -11,9 +11,9 @@ export class Company extends AbstractApiData implements CompanyInterface {
 
   private _isActiveSubscription: boolean = false;
 
-  private _monthlyTokens: number = 0;
-  private _availableMonthlyTokens: number = 0;
-  private _availableExtraTokens: number = 0;
+  private _monthlyCredits: number = 0;
+  private _availableMonthlyCredits: number = 0;
+  private _availableExtraCredits: number = 0;
 
   private _features?: FeatureInterface[];
   private _modules?: ModuleInterface[];
@@ -46,16 +46,16 @@ export class Company extends AbstractApiData implements CompanyInterface {
     return this._isActiveSubscription ?? false;
   }
 
-  get monthlyTokens(): number {
-    return this._monthlyTokens ?? 0;
+  get monthlyCredits(): number {
+    return this._monthlyCredits ?? 0;
   }
 
-  get availableMonthlyTokens(): number {
-    return this._availableMonthlyTokens ?? 0;
+  get availableMonthlyCredits(): number {
+    return this._availableMonthlyCredits ?? 0;
   }
 
-  get availableExtraTokens(): number {
-    return this._availableExtraTokens ?? 0;
+  get availableExtraCredits(): number {
+    return this._availableExtraCredits ?? 0;
   }
 
   get features(): FeatureInterface[] {
@@ -120,9 +120,9 @@ export class Company extends AbstractApiData implements CompanyInterface {
     this._logo = data.jsonApi.attributes.logo;
     this._logoUrl = data.jsonApi.attributes.logoUrl;
     this._isActiveSubscription = data.jsonApi.attributes.isActiveSubscription ?? false;
-    this._monthlyTokens = data.jsonApi.attributes.monthlyTokens ?? 0;
-    this._availableMonthlyTokens = data.jsonApi.attributes.availableMonthlyTokens ?? 0;
-    this._availableExtraTokens = data.jsonApi.attributes.availableExtraTokens ?? 0;
+    this._monthlyCredits = data.jsonApi.attributes.monthlyCredits ?? 0;
+    this._availableMonthlyCredits = data.jsonApi.attributes.availableMonthlyCredits ?? 0;
+    this._availableExtraCredits = data.jsonApi.attributes.availableExtraCredits ?? 0;
 
     this._legal_address = data.jsonApi.attributes.legal_address;
     this._street_number = data.jsonApi.attributes.street_number;
@@ -156,11 +156,11 @@ export class Company extends AbstractApiData implements CompanyInterface {
     if (data.name) response.data.attributes.name = data.name;
     if (data.configurations) response.data.attributes.configurations = JSON.stringify(data.configurations);
     if (data.logo) response.data.attributes.logo = data.logo;
-    if (data.monthlyTokens !== undefined) response.data.attributes.monthlyTokens = data.monthlyTokens;
-    if (data.availableMonthlyTokens !== undefined)
-      response.data.attributes.availableMonthlyTokens = data.availableMonthlyTokens;
-    if (data.availableExtraTokens !== undefined)
-      response.data.attributes.availableExtraTokens = data.availableExtraTokens;
+    if (data.monthlyCredits !== undefined) response.data.attributes.monthlyCredits = data.monthlyCredits;
+    if (data.availableMonthlyCredits !== undefined)
+      response.data.attributes.availableMonthlyCredits = data.availableMonthlyCredits;
+    if (data.availableExtraCredits !== undefined)
+      response.data.attributes.availableExtraCredits = data.availableExtraCredits;
 
     if (data.legal_address !== undefined) response.data.attributes.legal_address = data.legal_address;
     if (data.street_number !== undefined) response.data.attributes.street_number = data.street_number;

package/src/features/tokenusage/components/TokenUsageAdminContainer.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { cn } from "../../../lib/utils";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { RoundPageContainer } from "../../../components";
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../../../shadcnui";
+import { useTokenUsageAdmin } from "../contexts/TokenUsageAdminContext";
+import type { StackBy } from "../data/tokenusage-admin.types";
+import { TokenUsageAdminTiles } from "./TokenUsageAdminTiles";
+import { TokenUsageBreakdownTable } from "./TokenUsageBreakdownTable";
+import { TokenUsageRankedBar } from "./TokenUsageRankedBar";
+import { TokenUsageTimelineChart } from "./TokenUsageTimelineChart";
+
+const STACK_BY_VALUES: StackBy[] = ["scope", "type", "company"];
+
+/**
+ * Page body for the administrative token-usage dashboard.
+ *
+ * Stateless by design — every value it renders comes from
+ * `useTokenUsageAdmin()`. The filter bar is deliberately NOT here: it belongs to
+ * the page title bar, which `RoundPageContainer` fills from `SharedContext`, so
+ * the provider publishes it (see TokenUsageAdminContext).
+ */
+export function TokenUsageAdminContainer() {
+  const t = useTranslations();
+  const {
+    summary,
+    timeline,
+    byCompany,
+    byUser,
+    byOperation,
+    byCustomerOperation,
+    filters,
+    setFilters,
+    singleCustomerMode,
+    isLoading,
+    error,
+  } = useTokenUsageAdmin();
+
+  const stackByItems = useMemo(
+    () => ({
+      scope: t("token_usage.admin.stack.scope"),
+      type: t("token_usage.admin.stack.type"),
+      company: t("token_usage.admin.stack.company"),
+    }),
+    [t],
+  );
+
+  if (error) {
+    return (
+      <RoundPageContainer fullWidth forceHeader>
+        <div className="p-4">
+          <Card>
+            <CardContent>
+              <p className="text-destructive text-xs/relaxed">{error}</p>
+            </CardContent>
+          </Card>
+        </div>
+      </RoundPageContainer>
+    );
+  }
+
+  // Loading renders nothing in the body: the title bar (with the filter bar) is
+  // already mounted, so a spinner would only make the controls jump on arrival.
+  if (isLoading) return <RoundPageContainer fullWidth forceHeader />;
+
+  const emptyLabel = t("token_usage.admin.no_data");
+
+  return (
+    <RoundPageContainer fullWidth forceHeader>
+      <div className="flex w-full flex-col gap-4 p-4">
+        <TokenUsageAdminTiles summary={summary} metric={filters.metric} singleCustomerMode={singleCustomerMode} />
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("token_usage.admin.usage_over_time")}</CardTitle>
+            <CardAction>
+              <div className="flex items-center gap-2">
+                <span className="text-muted-foreground text-xs">{t("token_usage.admin.stack_by")}</span>
+                <Select
+                  items={stackByItems}
+                  value={filters.stackBy}
+                  onValueChange={(value) => {
+                    if (value) setFilters({ stackBy: value as StackBy });
+                  }}
+                >
+                  <SelectTrigger size="sm" className="w-36">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {STACK_BY_VALUES.map((value) => (
+                      <SelectItem key={value} value={value}>
+                        {stackByItems[value]}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            </CardAction>
+          </CardHeader>
+          <CardContent>
+            <TokenUsageTimelineChart rows={timeline} metric={filters.metric} stackBy={filters.stackBy} />
+          </CardContent>
+        </Card>
+
+        <div className="grid gap-4 md:grid-cols-2">
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.admin.by_company")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TokenUsageRankedBar rows={byCompany} metric={filters.metric} emptyLabel={emptyLabel} />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.admin.by_user")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TokenUsageRankedBar rows={byUser} metric={filters.metric} emptyLabel={emptyLabel} />
+            </CardContent>
+          </Card>
+        </div>
+
+        {/* The two cost centres, broken down the same way so they can be read
+            against each other. Operation types are vocabulary, not data — unlike
+            the company and user panels above, these labels get translated.
+
+            Platform spend has no owning company, so a company filter makes that
+            half meaningless: the provider skips the request and the card is
+            hidden rather than rendered empty, leaving the customer half full
+            width. */}
+        <div className={cn("grid gap-4", !singleCustomerMode && "md:grid-cols-2")}>
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.admin.customer_by_operation")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TokenUsageRankedBar
+                rows={byCustomerOperation}
+                metric={filters.metric}
+                emptyLabel={emptyLabel}
+                labelsAreOperationTypes
+              />
+            </CardContent>
+          </Card>
+
+          {!singleCustomerMode && (
+            <Card>
+              <CardHeader>
+                <CardTitle>{t("token_usage.admin.platform_by_operation")}</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <TokenUsageRankedBar
+                  rows={byOperation}
+                  metric={filters.metric}
+                  emptyLabel={emptyLabel}
+                  labelsAreOperationTypes
+                />
+              </CardContent>
+            </Card>
+          )}
+        </div>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("token_usage.admin.detail")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <TokenUsageBreakdownTable rows={byCompany} metric={filters.metric} />
+          </CardContent>
+        </Card>
+      </div>
+    </RoundPageContainer>
+  );
+}

package/src/features/tokenusage/components/TokenUsageAdminFilterBar.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { DateRangeSelector } from "../../../components/forms/DateRangeSelector";
+import { Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import type { Granularity, Metric } from "../data/tokenusage-admin.types";
+
+/** Sentinel for "no company filter" — Base UI Select cannot hold `undefined`. */
+const ALL_COMPANIES = "all";
+
+type FilterState = {
+  from: string;
+  to: string;
+  granularity: Granularity;
+  companyId?: string;
+  metric: Metric;
+};
+
+type Props = FilterState & {
+  companies: { id: string; label: string }[];
+  /** Receives ONLY the keys that changed. */
+  onChange: (next: Partial<FilterState>) => void;
+};
+
+/**
+ * The single control row above the KPI tiles.
+ *
+ * It is deliberately stateless: every control reports the one key it changed and
+ * the owning context re-fetches. Keeping the whole filter state in one place is
+ * what lets the page issue a single coordinated batch of requests instead of one
+ * per control.
+ */
+export function TokenUsageAdminFilterBar({ granularity, companyId, metric, companies, onChange }: Props) {
+  const t = useTranslations();
+
+  const companyItems: Record<string, string> = {
+    [ALL_COMPANIES]: t("token_usage.admin.all_companies"),
+    ...Object.fromEntries(companies.map((company) => [company.id, company.label])),
+  };
+
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <DateRangeSelector
+        onDateChange={(range) => {
+          if (!range?.from || !range?.to) return;
+          onChange({ from: range.from.toISOString(), to: range.to.toISOString() });
+        }}
+      />
+
+      <Segmented
+        ariaLabel={t("token_usage.admin.granularity.label")}
+        value={granularity}
+        options={[
+          { value: "day", label: t("token_usage.admin.granularity.day") },
+          { value: "week", label: t("token_usage.admin.granularity.week") },
+          { value: "month", label: t("token_usage.admin.granularity.month") },
+        ]}
+        onSelect={(value) => onChange({ granularity: value })}
+      />
+
+      <Segmented
+        ariaLabel={t("token_usage.admin.metric.label")}
+        value={metric}
+        options={[
+          { value: "cost", label: t("token_usage.admin.metric.cost") },
+          { value: "credits", label: t("token_usage.admin.metric.credits") },
+          { value: "tokens", label: t("token_usage.admin.metric.tokens") },
+        ]}
+        onSelect={(value) => onChange({ metric: value })}
+      />
+
+      <Select
+        items={companyItems}
+        value={companyId ?? ALL_COMPANIES}
+        onValueChange={(value) =>
+          onChange({ companyId: !value || value === ALL_COMPANIES ? undefined : (value as string) })
+        }
+      >
+        <SelectTrigger className="w-56">
+          <SelectValue placeholder={t("token_usage.admin.all_companies")} />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={ALL_COMPANIES}>{t("token_usage.admin.all_companies")}</SelectItem>
+          {companies.map((company) => (
+            <SelectItem key={company.id} value={company.id}>
+              {company.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}
+
+/**
+ * A segmented control built from plain Buttons.
+ *
+ * The design system has no ToggleGroup primitive, and Base UI triggers may never
+ * wrap a Button, so the segmented look is composed from Buttons directly — the
+ * selected segment takes the solid variant, the rest stay ghosts.
+ */
+function Segmented<T extends string>({
+  ariaLabel,
+  value,
+  options,
+  onSelect,
+}: {
+  ariaLabel: string;
+  value: T;
+  options: { value: T; label: string }[];
+  onSelect: (value: T) => void;
+}) {
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      className="border-border inline-flex items-center gap-0.5 rounded-md border p-0.5"
+    >
+      {options.map((option) => {
+        const selected = option.value === value;
+        return (
+          <Button
+            key={option.value}
+            type="button"
+            size="sm"
+            variant={selected ? "default" : "ghost"}
+            aria-pressed={selected}
+            className={cn(!selected && "text-muted-foreground")}
+            onClick={() => onSelect(option.value)}
+          >
+            {option.label}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

package/src/features/tokenusage/components/TokenUsageAdminTiles.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { Card, CardContent } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import type { TokenUsageAdminSummaryInterface } from "../data/tokenusage-admin-summary.interface";
+import type { Metric } from "../data/tokenusage-admin.types";
+import {
+  cacheHitPercentage,
+  formatDecimal,
+  formatMetricValue,
+  formatPercent,
+  metricValue,
+  percentageDelta,
+  type TokenUsageMetrics,
+} from "../lib/metrics";
+
+type Props = {
+  /** The six summary rows: {customer, platform, total} × {current, previous}. */
+  summary: TokenUsageAdminSummaryInterface[];
+  metric: Metric;
+  /** True when a company filter is applied — platform spend is then meaningless. */
+  singleCustomerMode: boolean;
+};
+
+const ZERO: TokenUsageMetrics = { cost: 0, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls: 0 };
+
+/**
+ * The KPI header of the administrative token-usage page.
+ *
+ * Two lead tiles carry the cost centres — customer spend and platform spend —
+ * each with its delta against the equal-length preceding window. Three
+ * supporting tiles below carry the totals that give those two numbers context.
+ *
+ * The backend always returns both windows, which is why no tile has to branch on
+ * a missing row: an absent scope is simply zero-filled here.
+ */
+export function TokenUsageAdminTiles({ summary, metric, singleCustomerMode }: Props) {
+  const t = useTranslations();
+
+  const rowFor = (scope: string, window: string): TokenUsageMetrics =>
+    summary.find((r) => r.scope === scope && r.window === window) ?? ZERO;
+
+  const customerCurrent = rowFor("customer", "current");
+  const customerPrevious = rowFor("customer", "previous");
+  const platformCurrent = rowFor("platform", "current");
+  const platformPrevious = rowFor("platform", "previous");
+  const totalCurrent = rowFor("total", "current");
+  const totalPrevious = rowFor("total", "previous");
+
+  const averagePerCall = totalCurrent.calls ? totalCurrent.cost / totalCurrent.calls : 0;
+  const cacheHit = cacheHitPercentage(totalCurrent.cached, totalCurrent.tokensIn);
+
+  return (
+    <div className="grid gap-3">
+      <div className={cn("grid gap-3", singleCustomerMode ? "sm:grid-cols-1" : "sm:grid-cols-2")}>
+        <LeadTile
+          testId="tile-customer"
+          label={t("token_usage.admin.customer_spend")}
+          value={formatMetricValue(metricValue(customerCurrent, metric), metric)}
+          delta={percentageDelta(metricValue(customerCurrent, metric), metricValue(customerPrevious, metric))}
+          previousLabel={t("token_usage.admin.vs_previous")}
+        />
+        {!singleCustomerMode && (
+          <LeadTile
+            testId="tile-platform"
+            label={t("token_usage.admin.platform_spend")}
+            value={formatMetricValue(metricValue(platformCurrent, metric), metric)}
+            delta={percentageDelta(metricValue(platformCurrent, metric), metricValue(platformPrevious, metric))}
+            previousLabel={t("token_usage.admin.vs_previous")}
+          />
+        )}
+      </div>
+
+      <div className="grid gap-3 sm:grid-cols-3">
+        <SupportingTile
+          testId="tile-total"
+          label={t("token_usage.admin.total_cost")}
+          value={formatMetricValue(metricValue(totalCurrent, metric), metric)}
+          delta={percentageDelta(metricValue(totalCurrent, metric), metricValue(totalPrevious, metric))}
+        />
+        <SupportingTile
+          testId="tile-avg-per-call"
+          label={t("token_usage.admin.avg_per_call")}
+          value={`€ ${formatDecimal(averagePerCall, 4)}`}
+        />
+        <SupportingTile
+          testId="tile-cache-hit"
+          label={t("token_usage.admin.cache_hit")}
+          value={formatPercent(cacheHit)}
+        />
+      </div>
+    </div>
+  );
+}
+
+function LeadTile({
+  testId,
+  label,
+  value,
+  delta,
+  previousLabel,
+}: {
+  testId: string;
+  label: string;
+  value: string;
+  delta: number | undefined;
+  previousLabel: string;
+}) {
+  return (
+    <Card data-testid={testId}>
+      <CardContent className="grid gap-1">
+        <span className="text-muted-foreground text-xs">{label}</span>
+        <span className="text-primary text-xl font-semibold tabular-nums">{value}</span>
+        <span className="flex items-center gap-1">
+          <Delta testId={`${testId}-delta`} delta={delta} />
+          <span className="text-muted-foreground text-xs">{previousLabel}</span>
+        </span>
+      </CardContent>
+    </Card>
+  );
+}
+
+function SupportingTile({
+  testId,
+  label,
+  value,
+  delta,
+}: {
+  testId: string;
+  label: string;
+  value: string;
+  delta?: number | undefined;
+}) {
+  return (
+    <Card data-testid={testId} size="sm">
+      <CardContent className="grid gap-1">
+        <span className="text-muted-foreground text-xs">{label}</span>
+        <span className="flex items-center gap-2">
+          <span className="text-sm font-medium tabular-nums">{value}</span>
+          {delta !== undefined && <Delta testId={`${testId}-delta`} delta={delta} />}
+        </span>
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * The delta slot. An undefined delta means the previous window was zero: an
+ * em dash says "not comparable" where a percentage would say "infinite growth".
+ */
+function Delta({ testId, delta }: { testId: string; delta: number | undefined }) {
+  if (delta === undefined) {
+    return (
+      <span data-testid={testId} className="text-muted-foreground text-xs">
+        —
+      </span>
+    );
+  }
+
+  const increased = delta >= 0;
+  const Icon = increased ? ArrowUpIcon : ArrowDownIcon;
+
+  return (
+    <span
+      data-testid={testId}
+      className={cn(
+        "inline-flex items-center gap-0.5 text-xs tabular-nums",
+        increased ? "text-success" : "text-destructive",
+      )}
+    >
+      <Icon aria-hidden className="size-3" />
+      {formatDecimal(Math.abs(delta), 0)} %
+    </span>
+  );
+}