@stigmer/react 3.2.3 → 3.3.0

package/src/billing/__tests__/useModelGovernanceView.test.tsx

@@ -0,0 +1,308 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  ModelPricingBaselineSchema,
+  ModelPricingBaselineStatus,
+  PricingBlockSchema,
+} from "@stigmer/protos/ai/stigmer/billing/v1/model_pricing_baseline_pb";
+import {
+  ModelPricingGovernanceEntrySchema,
+  type ModelPricingGovernanceEntry,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import {
+  ModelPricingOverrideSchema,
+  type ModelPricingOverride,
+} from "@stigmer/protos/ai/stigmer/billing/v1/pricing_override_pb";
+import type { ModelPricingBaseline } from "@stigmer/protos/ai/stigmer/billing/v1/model_pricing_baseline_pb";
+import { useModelGovernanceView } from "../useModelGovernanceView";
+
+// The view hook is pure composition over the two data hooks — drive it
+// through mocks; the RPC wiring is covered by the console tests.
+const baselinesReturn = vi.fn();
+const governanceReturn = vi.fn();
+vi.mock("../useModelPricingBaselines", () => ({
+  useModelPricingBaselines: (options: unknown) => {
+    lastBaselinesOptions = options;
+    return baselinesReturn();
+  },
+}));
+vi.mock("../usePricingGovernance", () => ({
+  usePricingGovernance: () => governanceReturn(),
+}));
+
+let lastBaselinesOptions: unknown = null;
+
+function baseline(overrides: Record<string, unknown> = {}): ModelPricingBaseline {
+  return create(ModelPricingBaselineSchema, {
+    baselineId: "bl-sonnet",
+    modelId: "claude-sonnet-4-6",
+    provider: "anthropic",
+    harness: "native",
+    displayName: "Claude Sonnet",
+    status: ModelPricingBaselineStatus.pricing_baseline_active,
+    pricing: create(PricingBlockSchema, {
+      inputPriceMicrosPerMillion: 3_000_000n,
+      outputPriceMicrosPerMillion: 15_000_000n,
+    }),
+    ...overrides,
+  });
+}
+
+function entry(overrides: Record<string, unknown> = {}): ModelPricingGovernanceEntry {
+  return create(ModelPricingGovernanceEntrySchema, {
+    modelId: "claude-sonnet-4-6",
+    provider: "anthropic",
+    harness: "native",
+    variant: "",
+    baselineInputMicrosPerMillion: 3_000_000n,
+    effectiveInputMicrosPerMillion: 3_100_000n,
+    ledgerReconcilable: true,
+    ...overrides,
+  });
+}
+
+function override(overrides: Record<string, unknown> = {}): ModelPricingOverride {
+  return create(ModelPricingOverrideSchema, {
+    overrideId: "ovr-1",
+    modelId: "claude-sonnet-4-6",
+    variant: "",
+    ...overrides,
+  });
+}
+
+function setData({
+  baselines = [] as readonly ModelPricingBaseline[],
+  entries = [] as readonly ModelPricingGovernanceEntry[],
+  pendingOverrides = [] as readonly ModelPricingOverride[],
+} = {}) {
+  baselinesReturn.mockReturnValue({
+    baselines,
+    isLoading: false,
+    isRefetching: false,
+    error: null,
+    refetch: vi.fn(),
+  });
+  governanceReturn.mockReturnValue({
+    governance: { entries, pendingOverrides },
+    isLoading: false,
+    isRefetching: false,
+    error: null,
+    refetch: vi.fn(),
+  });
+}
+
+/** Renders the hook and exposes the parts under test via data attributes. */
+function Probe() {
+  const view = useModelGovernanceView();
+  return (
+    <div>
+      <div
+        data-testid="models"
+        data-keys={view.models.map((m) => m.key).join(";")}
+        data-governance={view.models
+          .map((m) => (m.governance ? "joined" : "none"))
+          .join(";")}
+        data-variants={view.models
+          .map((m) => m.variantGovernance.map((v) => v.variant).join(","))
+          .join(";")}
+        data-history={view.models.map((m) => m.history.length).join(";")}
+      />
+      <div
+        data-testid="signoffs"
+        data-count={view.pendingCount}
+        data-ids={view.pendingOverrides.map((o) => o.overrideId).join(";")}
+      />
+      <div
+        data-testid="flow"
+        data-phase={view.flow.phase}
+        data-mode={view.flow.phase === "detail" ? view.flow.mode : ""}
+        data-selected={view.selected?.key ?? "none"}
+      />
+      <input
+        aria-label="model query"
+        value={view.modelQuery}
+        onChange={(e) => view.setModelQuery(e.target.value)}
+      />
+      <input
+        aria-label="signoff query"
+        value={view.signOffQuery}
+        onChange={(e) => view.setSignOffQuery(e.target.value)}
+      />
+      <button onClick={() => view.openDetail("claude-sonnet-4-6|anthropic|native")}>detail</button>
+      <button onClick={() => view.openEdit()}>edit</button>
+      <button onClick={() => view.openRetire()}>retire</button>
+      <button onClick={() => view.backToDetail()}>back-detail</button>
+      <button onClick={() => view.backToList()}>back-list</button>
+      <button onClick={() => view.openCreate()}>create</button>
+    </div>
+  );
+}
+
+beforeEach(() => {
+  setData();
+});
+
+afterEach(() => {
+  cleanup();
+  baselinesReturn.mockReset();
+  governanceReturn.mockReset();
+});
+
+describe("useModelGovernanceView — join", () => {
+  it("joins governance entries onto baselines by (modelId, provider, harness)", () => {
+    setData({
+      baselines: [baseline()],
+      entries: [entry()],
+    });
+    render(<Probe />);
+
+    const models = screen.getByTestId("models");
+    expect(models.getAttribute("data-keys")).toBe("claude-sonnet-4-6|anthropic|native");
+    expect(models.getAttribute("data-governance")).toBe("joined");
+  });
+
+  it("keeps baseline-only models with no governance state", () => {
+    setData({
+      baselines: [baseline()],
+      entries: [entry({ harness: "cursor" })], // different key — must not join
+    });
+    render(<Probe />);
+
+    expect(screen.getByTestId("models").getAttribute("data-governance")).toBe("none");
+  });
+
+  it("folds variant entries into their model instead of top-level rows", () => {
+    setData({
+      baselines: [baseline()],
+      entries: [entry(), entry({ variant: "fast" })],
+    });
+    render(<Probe />);
+
+    const models = screen.getByTestId("models");
+    expect(models.getAttribute("data-keys")).toBe("claude-sonnet-4-6|anthropic|native");
+    expect(models.getAttribute("data-variants")).toBe("fast");
+  });
+
+  it("separates ACTIVE rows from their revision history", () => {
+    setData({
+      baselines: [
+        baseline(),
+        baseline({
+          baselineId: "bl-old",
+          status: ModelPricingBaselineStatus.pricing_baseline_superseded,
+        }),
+      ],
+    });
+    render(<Probe />);
+
+    const models = screen.getByTestId("models");
+    expect(models.getAttribute("data-keys")).toBe("claude-sonnet-4-6|anthropic|native");
+    expect(models.getAttribute("data-history")).toBe("1");
+  });
+
+  it("always fetches with history so the detail view needs no second round-trip", () => {
+    render(<Probe />);
+    expect(lastBaselinesOptions).toEqual({ includeHistory: true });
+  });
+
+  it("sorts models by display name", () => {
+    setData({
+      baselines: [
+        baseline({ baselineId: "bl-z", modelId: "z-model", displayName: "Zed" }),
+        baseline({ baselineId: "bl-a", modelId: "a-model", displayName: "Alpha" }),
+      ],
+    });
+    render(<Probe />);
+
+    expect(screen.getByTestId("models").getAttribute("data-keys")).toBe(
+      "a-model|anthropic|native;z-model|anthropic|native",
+    );
+  });
+});
+
+describe("useModelGovernanceView — search", () => {
+  it("filters models by id, display name, or provider (case-insensitive)", () => {
+    setData({
+      baselines: [
+        baseline(),
+        baseline({ baselineId: "bl-gpt", modelId: "gpt-5.6", provider: "openai", displayName: "GPT" }),
+      ],
+    });
+    render(<Probe />);
+
+    fireEvent.change(screen.getByLabelText("model query"), { target: { value: "OPENAI" } });
+    expect(screen.getByTestId("models").getAttribute("data-keys")).toBe(
+      "gpt-5.6|openai|native",
+    );
+  });
+
+  it("filters sign-offs by query but keeps the unfiltered badge count", () => {
+    setData({
+      pendingOverrides: [
+        override(),
+        override({ overrideId: "ovr-2", modelId: "gpt-5.6" }),
+      ],
+    });
+    render(<Probe />);
+
+    fireEvent.change(screen.getByLabelText("signoff query"), { target: { value: "gpt" } });
+    const signoffs = screen.getByTestId("signoffs");
+    expect(signoffs.getAttribute("data-ids")).toBe("ovr-2");
+    expect(signoffs.getAttribute("data-count")).toBe("2");
+  });
+});
+
+describe("useModelGovernanceView — flow", () => {
+  it("walks list → detail (view → edit → view → retire) → list", () => {
+    setData({ baselines: [baseline()] });
+    render(<Probe />);
+    const flow = screen.getByTestId("flow");
+
+    expect(flow.getAttribute("data-phase")).toBe("list");
+
+    fireEvent.click(screen.getByText("detail"));
+    expect(flow.getAttribute("data-phase")).toBe("detail");
+    expect(flow.getAttribute("data-mode")).toBe("view");
+    expect(flow.getAttribute("data-selected")).toBe("claude-sonnet-4-6|anthropic|native");
+
+    fireEvent.click(screen.getByText("edit"));
+    expect(flow.getAttribute("data-mode")).toBe("edit");
+
+    fireEvent.click(screen.getByText("back-detail"));
+    expect(flow.getAttribute("data-mode")).toBe("view");
+
+    fireEvent.click(screen.getByText("retire"));
+    expect(flow.getAttribute("data-mode")).toBe("retire");
+
+    fireEvent.click(screen.getByText("back-list"));
+    expect(flow.getAttribute("data-phase")).toBe("list");
+  });
+
+  it("ignores edit/retire transitions outside the detail phase", () => {
+    setData({ baselines: [baseline()] });
+    render(<Probe />);
+    const flow = screen.getByTestId("flow");
+
+    fireEvent.click(screen.getByText("edit"));
+    expect(flow.getAttribute("data-phase")).toBe("list");
+
+    fireEvent.click(screen.getByText("create"));
+    fireEvent.click(screen.getByText("retire"));
+    expect(flow.getAttribute("data-phase")).toBe("create");
+  });
+
+  it("resolves selected to null when the focused model disappears (e.g. retired)", () => {
+    setData({ baselines: [baseline()] });
+    const { rerender } = render(<Probe />);
+
+    fireEvent.click(screen.getByText("detail"));
+    expect(screen.getByTestId("flow").getAttribute("data-selected")).toBe(
+      "claude-sonnet-4-6|anthropic|native",
+    );
+
+    setData({ baselines: [] });
+    rerender(<Probe />);
+    expect(screen.getByTestId("flow").getAttribute("data-selected")).toBe("none");
+  });
+});

package/src/billing/form-primitives.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+// ---------------------------------------------------------------------------
+// Shared form primitives for the operator pricing surfaces (BaselineEditor,
+// RetireConfirm, the console's search inputs). Internal — not exported
+// from the billing barrel.
+// ---------------------------------------------------------------------------
+
+/** Standard text-input styling for the pricing surfaces. */
+export const INPUT_CLASSES = cn(
+  "w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground",
+  "placeholder:text-muted-foreground",
+  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+  "disabled:pointer-events-none disabled:opacity-50",
+);
+
+/** Labelled form field wrapper. */
+export function Field({
+  label,
+  required,
+  className,
+  children,
+}: {
+  readonly label: string;
+  readonly required?: boolean;
+  readonly className?: string;
+  readonly children: React.ReactNode;
+}) {
+  return (
+    <label className={cn("block space-y-1", className)}>
+      <span className="text-[11px] font-medium text-muted-foreground">
+        {label}
+        {required ? " *" : ""}
+      </span>
+      {children}
+    </label>
+  );
+}
+
+/** Dollar-rate input field (decimal keypad, "$ per million tokens"). */
+export function RateField({
+  label,
+  value,
+  placeholder,
+  disabled,
+  onChange,
+}: {
+  readonly label: string;
+  readonly value: string;
+  readonly placeholder?: string;
+  readonly disabled: boolean;
+  readonly onChange: (value: string) => void;
+}) {
+  return (
+    <Field label={label}>
+      <input
+        className={INPUT_CLASSES}
+        inputMode="decimal"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder ?? "0.00"}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}

package/src/billing/governance-primitives.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { ModelPricingOverride } from "@stigmer/protos/ai/stigmer/billing/v1/pricing_override_pb";
+import { Button } from "../button/index.js";
+import { RATE_FIELD_LABELS, formatDeltaBp, formatRate } from "./pricing-format.js";
+
+// ---------------------------------------------------------------------------
+// Shared display primitives for the operator pricing surfaces. Internal —
+// not exported from the billing barrel.
+// ---------------------------------------------------------------------------
+
+/**
+ * One PENDING_SIGNOFF pricing override with approve/reject actions and
+ * its ledger provenance (what was observed, against what, over which
+ * window) so the operator decides from evidence, not a bare number.
+ */
+export function PendingOverrideCard({
+  override,
+  isSubmitting,
+  onDecide,
+}: {
+  readonly override: ModelPricingOverride;
+  readonly isSubmitting: boolean;
+  readonly onDecide: (overrideId: string, approve: boolean) => void;
+}) {
+  const provenance = override.provenance;
+  return (
+    <div className="rounded-lg border border-border bg-card px-3 py-2">
+      <div className="flex items-center justify-between gap-2">
+        <div className="min-w-0">
+          <p className="truncate text-xs font-medium text-foreground">
+            {override.modelId}
+            {override.variant ? ` (${override.variant})` : ""}
+            {" · "}
+            {RATE_FIELD_LABELS[override.rateField] ?? "Rate"}
+          </p>
+          <p className="text-[11px] text-muted-foreground">
+            {provenance ? (
+              <>
+                Ledger observed {formatRate(provenance.observedRateMicrosPerMillion)} vs
+                effective {formatRate(provenance.effectiveRateAtDerivationMicrosPerMillion)}
+                {" "}({formatDeltaBp(provenance.deltaBasisPoints)}) over{" "}
+                {provenance.windowFrom}..{provenance.windowTo}
+              </>
+            ) : (
+              <>Proposed rate {formatRate(override.rateMicrosPerMillion)}</>
+            )}
+          </p>
+        </div>
+        <div className="flex shrink-0 gap-2">
+          <Button
+            size="sm"
+            disabled={isSubmitting}
+            onClick={() => onDecide(override.overrideId, true)}
+          >
+            Approve
+          </Button>
+          <Button
+            size="sm"
+            variant="outline"
+            disabled={isSubmitting}
+            onClick={() => onDecide(override.overrideId, false)}
+          >
+            Reject
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Effective rate; when an override moved it, the baseline shows
+ * struck-through. Pass `role="cell"` when rendered inside an ARIA
+ * table row; leave unset inside interactive list rows (a `<button>`
+ * row cannot contain table cells).
+ */
+export function RateCell({
+  baseline,
+  effective,
+  role,
+}: {
+  readonly baseline: bigint;
+  readonly effective: bigint;
+  readonly role?: "cell";
+}) {
+  const overridden = baseline !== effective;
+  return (
+    <span role={role} className="text-right text-foreground">
+      {overridden && (
+        <span className="mr-1 text-[10px] text-muted-foreground line-through">
+          {formatRate(baseline)}
+        </span>
+      )}
+      {formatRate(effective)}
+    </span>
+  );
+}
+
+/**
+ * Governance state chip: how this entry's rates are governed —
+ * ledger-verified (reconcilable, no overrides), ledger-corrected
+ * (reconcilable with active overrides), or manually governed (no
+ * external ledger can verify it).
+ */
+export function GovernanceBadge({
+  ledgerReconcilable,
+  hasOverrides,
+}: {
+  readonly ledgerReconcilable: boolean;
+  readonly hasOverrides: boolean;
+}) {
+  if (!ledgerReconcilable) {
+    return (
+      <span className="rounded bg-muted-subtle px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
+        Manually governed
+      </span>
+    );
+  }
+  return (
+    <span
+      className={cn(
+        "rounded px-1.5 py-0.5 text-[10px] font-medium",
+        hasOverrides
+          ? "bg-accent text-primary"
+          : "bg-muted-subtle text-muted-foreground",
+      )}
+    >
+      {hasOverrides ? "Ledger-corrected" : "Ledger-verified"}
+    </span>
+  );
+}

package/src/billing/index.ts

@@ -7,6 +7,19 @@ export { useBillingUsageReport } from "./useBillingUsageReport.js";
 export type { UseBillingUsageReportReturn } from "./useBillingUsageReport.js";
 export { useCustomerModelPricing } from "./useCustomerModelPricing.js";
 export type { UseCustomerModelPricingReturn } from "./useCustomerModelPricing.js";
+export { usePricingGovernance } from "./usePricingGovernance.js";
+export type { UsePricingGovernanceReturn } from "./usePricingGovernance.js";
+export { useModelPricingBaselines } from "./useModelPricingBaselines.js";
+export type {
+  UseModelPricingBaselinesOptions,
+  UseModelPricingBaselinesReturn,
+} from "./useModelPricingBaselines.js";
+export { useModelGovernanceView } from "./useModelGovernanceView.js";
+export type {
+  GovernanceFlow,
+  ModelGovernanceRow,
+  UseModelGovernanceViewReturn,
+} from "./useModelGovernanceView.js";
 
 // Behavior hooks
 export { useCreateCheckoutSession } from "./useCreateCheckoutSession.js";
@@ -21,6 +34,21 @@ export type {
   SetAutoRechargeConfigInput,
   UseSetAutoRechargeConfigReturn,
 } from "./useSetAutoRechargeConfig.js";
+export { useDecidePricingOverride } from "./useDecidePricingOverride.js";
+export type {
+  DecidePricingOverrideInput,
+  UseDecidePricingOverrideReturn,
+} from "./useDecidePricingOverride.js";
+export { useUpsertModelPricingBaseline } from "./useUpsertModelPricingBaseline.js";
+export type {
+  UpsertModelPricingBaselineInput,
+  UseUpsertModelPricingBaselineReturn,
+} from "./useUpsertModelPricingBaseline.js";
+export { useRetireModelPricingBaseline } from "./useRetireModelPricingBaseline.js";
+export type {
+  RetireModelPricingBaselineInput,
+  UseRetireModelPricingBaselineReturn,
+} from "./useRetireModelPricingBaseline.js";
 
 // Styled components
 export { BillingSection } from "./BillingSection.js";
@@ -37,6 +65,15 @@ export { CreditLedgerTable } from "./CreditLedgerTable.js";
 export type { CreditLedgerTableProps } from "./CreditLedgerTable.js";
 export { LowBalanceBanner } from "./LowBalanceBanner.js";
 export type { LowBalanceBannerProps } from "./LowBalanceBanner.js";
+export { PricingGovernancePanel } from "./PricingGovernancePanel.js";
+export type { PricingGovernancePanelProps } from "./PricingGovernancePanel.js";
+export { ModelCatalogPanel } from "./ModelCatalogPanel.js";
+export type { ModelCatalogPanelProps } from "./ModelCatalogPanel.js";
+export { PricingGovernanceConsole } from "./PricingGovernanceConsole.js";
+export type {
+  PricingGovernanceConsoleProps,
+  PricingGovernanceTab,
+} from "./PricingGovernanceConsole.js";
 
 // Credit pack catalog and formatting utilities
 export { CREDIT_PACKS, formatPackPrice, formatCreditCount } from "./credit-packs.js";

package/src/billing/pricing-format.ts

@@ -0,0 +1,53 @@
+import { PricingRateField } from "@stigmer/protos/ai/stigmer/billing/v1/pricing_override_pb";
+
+// ---------------------------------------------------------------------------
+// Shared money/label helpers for the platform-operator pricing surfaces
+// (PricingGovernanceConsole and the panels it grew out of). Internal —
+// not exported from the billing barrel.
+//
+// The UI works in dollars-per-million tokens; the protos store integer
+// micro-USD. Registry prices carry at most 4 decimal places, so the
+// round-trip through Math.round is exact.
+// ---------------------------------------------------------------------------
+
+// BigInt literals (0n) require an ES2020 target, which not every consuming
+// app's tsconfig guarantees — the constructor form is target-agnostic.
+export const ZERO = BigInt(0);
+
+/** Human labels for {@link PricingRateField} values. */
+export const RATE_FIELD_LABELS: Record<number, string> = {
+  [PricingRateField.input]: "Input",
+  [PricingRateField.output]: "Output",
+  [PricingRateField.cache_write]: "Cache write",
+  [PricingRateField.cache_read]: "Cache read",
+  [PricingRateField.cursor_token_rate]: "Cursor token rate",
+};
+
+/** Micro-USD per million tokens → "$X.XX/M" (raw provider rate). */
+export function formatRate(microsPerMillion: bigint): string {
+  const dollars = Number(microsPerMillion) / 1_000_000;
+  return `$${dollars.toFixed(dollars < 1 ? 4 : 2)}/M`;
+}
+
+/** Basis points → signed percentage, e.g. 530n → "+5.30%". */
+export function formatDeltaBp(deltaBp: bigint): string {
+  const pct = Number(deltaBp) / 100;
+  return `${pct > 0 ? "+" : ""}${pct.toFixed(2)}%`;
+}
+
+/** Micro-USD → editable dollar string, trailing zeros trimmed ("0.075"). */
+export function microsToDollarString(micros: bigint): string {
+  if (micros === ZERO) return "0";
+  const dollars = Number(micros) / 1_000_000;
+  // Trim trailing zeros without losing sub-cent precision (e.g. 0.075).
+  return String(parseFloat(dollars.toFixed(6)));
+}
+
+/** Parse a dollar input; returns null for anything that is not a finite, non-negative number. */
+export function dollarsToMicros(value: string): bigint | null {
+  const trimmed = value.trim();
+  if (trimmed === "") return null;
+  const parsed = Number(trimmed);
+  if (!Number.isFinite(parsed) || parsed < 0) return null;
+  return BigInt(Math.round(parsed * 1_000_000));
+}