@stigmer/react 0.3.4 → 0.4.1

package/src/billing/CreditPackGrid.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { BillingAccountStatus } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+import {
+  CREDIT_PACKS,
+  formatPackPrice,
+  formatCreditCount,
+  type CreditPackInfo,
+} from "./credit-packs";
+
+/** Props for {@link CreditPackGrid}. */
+export interface CreditPackGridProps {
+  /** Account status — purchases disabled when suspended or closed. */
+  readonly accountStatus: BillingAccountStatus;
+  /** ID of the pack currently being purchased (shows loading state). */
+  readonly purchasingPackId?: string | null;
+  /** Called when the user clicks a pack's buy button. */
+  readonly onPurchase: (packId: string) => void;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Grid of credit pack cards with purchase buttons.
+ *
+ * Displays the 3 self-serve credit packs (Starter, Growth, Team)
+ * in a responsive grid. Each card shows the pack name, price,
+ * credit count, and a buy button. Buttons are disabled when the
+ * account is suspended/closed or a purchase is in progress.
+ *
+ * @example
+ * ```tsx
+ * <CreditPackGrid
+ *   accountStatus={account.status}
+ *   purchasingPackId={isSubmitting ? activePackId : null}
+ *   onPurchase={(packId) => createSession({ orgId, packId, ... })}
+ * />
+ * ```
+ */
+export function CreditPackGrid({
+  accountStatus,
+  purchasingPackId,
+  onPurchase,
+  className,
+}: CreditPackGridProps) {
+  const isAccountActive =
+    accountStatus === BillingAccountStatus.billing_account_active;
+
+  return (
+    <div>
+      <h3 className="mb-2 text-xs font-semibold text-foreground">
+        Purchase Credits
+      </h3>
+      <div
+        className={cn("grid gap-3 sm:grid-cols-3", className)}
+        role="group"
+        aria-label="Credit packs"
+      >
+        {CREDIT_PACKS.map((pack) => (
+          <PackCard
+            key={pack.packId}
+            pack={pack}
+            isPurchasing={purchasingPackId === pack.packId}
+            isDisabled={!isAccountActive || purchasingPackId != null}
+            onPurchase={onPurchase}
+          />
+        ))}
+      </div>
+      {!isAccountActive && (
+        <p className="mt-2 text-xs text-muted-foreground">
+          Credit purchases are unavailable while your billing account is{" "}
+          {accountStatus === BillingAccountStatus.billing_account_suspended
+            ? "suspended"
+            : "closed"}
+          .
+        </p>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// PackCard (internal)
+// ---------------------------------------------------------------------------
+
+function PackCard({
+  pack,
+  isPurchasing,
+  isDisabled,
+  onPurchase,
+}: {
+  pack: CreditPackInfo;
+  isPurchasing: boolean;
+  isDisabled: boolean;
+  onPurchase: (packId: string) => void;
+}) {
+  return (
+    <div className="flex flex-col rounded-lg border border-border bg-card px-4 py-4">
+      <div className="text-sm font-semibold text-foreground">
+        {pack.displayName}
+      </div>
+      <div className="mt-0.5 text-xs text-muted-foreground">
+        {pack.description}
+      </div>
+
+      <div className="mt-3 flex items-baseline gap-1">
+        <span className="text-xl font-bold tabular-nums text-foreground">
+          {formatPackPrice(pack.priceCents)}
+        </span>
+      </div>
+      <div className="mt-0.5 text-xs tabular-nums text-muted-foreground">
+        {formatCreditCount(pack.credits)} credits
+      </div>
+
+      <button
+        type="button"
+        disabled={isDisabled}
+        onClick={() => onPurchase(pack.packId)}
+        className={cn(
+          "mt-4 w-full rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
+          "bg-primary text-primary-foreground",
+          "hover:bg-primary/90",
+          "disabled:pointer-events-none disabled:opacity-50",
+        )}
+        aria-busy={isPurchasing}
+      >
+        {isPurchasing ? "Redirecting\u2026" : "Buy"}
+      </button>
+    </div>
+  );
+}

package/src/billing/LowBalanceBanner.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { AlertTriangle } from "lucide-react";
+import { formatCreditBalance } from "./format";
+
+/** Props for {@link LowBalanceBanner}. */
+export interface LowBalanceBannerProps {
+  /** Available balance in micro-USD. */
+  readonly availableMicros: bigint;
+  /** Threshold in micro-USD below which the warning is shown. */
+  readonly thresholdMicros: bigint;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Conditional banner that warns when the available credit balance
+ * is below the configured threshold.
+ *
+ * Renders nothing when the balance is healthy. Not dismissible —
+ * it reflects a real account state that the user should address.
+ *
+ * @example
+ * ```tsx
+ * <LowBalanceBanner
+ *   availableMicros={account.balance.availableMicros}
+ *   thresholdMicros={account.lowBalanceThresholdMicros}
+ * />
+ * ```
+ */
+export function LowBalanceBanner({
+  availableMicros,
+  thresholdMicros,
+  className,
+}: LowBalanceBannerProps) {
+  if (availableMicros >= thresholdMicros) return null;
+
+  const isZeroOrNegative = availableMicros <= BigInt(0);
+
+  return (
+    <div
+      role="alert"
+      className={cn(
+        "flex items-start gap-2.5 rounded-lg border px-3.5 py-3 text-xs",
+        isZeroOrNegative
+          ? "border-destructive/30 bg-destructive/5 text-destructive"
+          : "border-warning/30 bg-warning/5 text-warning-foreground",
+        className,
+      )}
+    >
+      <AlertTriangle className="mt-0.5 size-3.5 shrink-0" aria-hidden="true" />
+      <div>
+        <p className="font-medium">
+          {isZeroOrNegative
+            ? "Credit balance exhausted"
+            : "Low credit balance"}
+        </p>
+        <p className="mt-0.5 opacity-80">
+          {isZeroOrNegative
+            ? "Your credit balance is zero. Purchase credits to continue running agent executions."
+            : `Your balance (${formatCreditBalance(availableMicros)}) is below the warning threshold. Consider purchasing additional credits.`}
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/billing/PaymentMethodCard.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { PaymentMethodSummary } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
+import { BillingAccountStatus } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+
+/** Props for {@link PaymentMethodCard}. */
+export interface PaymentMethodCardProps {
+  /** The saved payment method, or undefined if none is on file. */
+  readonly paymentMethod?: PaymentMethodSummary;
+  /** Account status — portal button disabled when suspended or closed. */
+  readonly accountStatus: BillingAccountStatus;
+  /** `true` while the portal session is being created. */
+  readonly isPortalLoading?: boolean;
+  /** Called when the user clicks "Manage payment methods". */
+  readonly onManage: () => void;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+const BRAND_DISPLAY: Record<string, string> = {
+  visa: "Visa",
+  mastercard: "Mastercard",
+  amex: "American Express",
+  discover: "Discover",
+  diners: "Diners Club",
+  jcb: "JCB",
+  unionpay: "UnionPay",
+};
+
+function formatBrand(brand: string): string {
+  return BRAND_DISPLAY[brand.toLowerCase()] ?? brand;
+}
+
+function formatExpiry(month: number, year: number): string {
+  const m = String(month).padStart(2, "0");
+  const y = String(year).slice(-2);
+  return `${m}/${y}`;
+}
+
+/**
+ * Displays the saved payment method with a button to open the
+ * Stripe Customer Portal for management.
+ *
+ * Shows card brand, last 4 digits, and expiry when a payment method
+ * is on file. Shows an empty state prompt when none exists. The
+ * "Manage" button opens the Stripe Customer Portal where users can
+ * add, update, or remove payment methods.
+ *
+ * @example
+ * ```tsx
+ * <PaymentMethodCard
+ *   paymentMethod={account.defaultPaymentMethod}
+ *   accountStatus={account.status}
+ *   onManage={() => openPortal(orgId)}
+ * />
+ * ```
+ */
+export function PaymentMethodCard({
+  paymentMethod,
+  accountStatus,
+  isPortalLoading,
+  onManage,
+  className,
+}: PaymentMethodCardProps) {
+  const isAccountActive =
+    accountStatus === BillingAccountStatus.billing_account_active;
+  const hasPm =
+    paymentMethod != null && paymentMethod.paymentMethodId !== "";
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border border-border bg-card px-4 py-4",
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between">
+        <h3 className="text-xs font-semibold text-foreground">
+          Payment Method
+        </h3>
+        {hasPm && (
+          <button
+            type="button"
+            disabled={!isAccountActive || isPortalLoading}
+            onClick={onManage}
+            className={cn(
+              "rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+              "text-muted-foreground hover:bg-accent hover:text-foreground",
+              "disabled:pointer-events-none disabled:opacity-50",
+            )}
+            aria-busy={isPortalLoading}
+          >
+            {isPortalLoading ? "Opening\u2026" : "Manage"}
+          </button>
+        )}
+      </div>
+
+      {hasPm ? (
+        <div className="mt-2 flex items-center gap-3">
+          <CardBrandIcon brand={paymentMethod.brand} />
+          <div>
+            <div className="text-sm font-medium text-foreground">
+              {formatBrand(paymentMethod.brand)} ····{" "}
+              {paymentMethod.last4}
+            </div>
+            <div className="text-xs text-muted-foreground">
+              Expires{" "}
+              {formatExpiry(paymentMethod.expMonth, paymentMethod.expYear)}
+            </div>
+          </div>
+        </div>
+      ) : (
+        <div className="mt-2">
+          <p className="text-xs text-muted-foreground">
+            No payment method on file. A card will be saved automatically
+            when you purchase your first credit pack.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function CardBrandIcon({ brand }: { brand: string }) {
+  return (
+    <div className="flex size-9 items-center justify-center rounded-md border border-border bg-background">
+      <span className="text-[0.6rem] font-bold uppercase text-muted-foreground">
+        {brand.slice(0, 4)}
+      </span>
+    </div>
+  );
+}

package/src/billing/credit-packs.ts

@@ -0,0 +1,54 @@
+/** Metadata for a self-serve credit pack. */
+export interface CreditPackInfo {
+  /** Stable identifier matching the backend catalog (e.g., "starter"). */
+  readonly packId: string;
+  /** Display name shown in the UI. */
+  readonly displayName: string;
+  /** Brief description of the pack's positioning. */
+  readonly description: string;
+  /** Price in USD cents (e.g., 1000 = $10.00). */
+  readonly priceCents: number;
+  /** Number of credits granted (1 credit = $0.01 USD). */
+  readonly credits: number;
+}
+
+/**
+ * Static credit pack catalog matching the backend `CreditPackCatalog`.
+ *
+ * Packs are static product entries, not database-backed resources.
+ * At launch, credits equal the dollar value (no volume bonus).
+ */
+export const CREDIT_PACKS: readonly CreditPackInfo[] = [
+  {
+    packId: "starter",
+    displayName: "Starter",
+    description: "For trying things out",
+    priceCents: 1_000,
+    credits: 1_000,
+  },
+  {
+    packId: "growth",
+    displayName: "Growth",
+    description: "For growing teams",
+    priceCents: 5_000,
+    credits: 5_000,
+  },
+  {
+    packId: "team",
+    displayName: "Team",
+    description: "For production workloads",
+    priceCents: 20_000,
+    credits: 20_000,
+  },
+];
+
+/** Format a cent amount as a dollar string (e.g., 1000 -> "$10"). */
+export function formatPackPrice(cents: number): string {
+  const dollars = cents / 100;
+  return dollars % 1 === 0 ? `$${dollars}` : `$${dollars.toFixed(2)}`;
+}
+
+/** Format a credit count with commas (e.g., 5000 -> "5,000"). */
+export function formatCreditCount(credits: number): string {
+  return credits.toLocaleString("en-US");
+}

package/src/billing/format.ts

@@ -0,0 +1,97 @@
+import { LedgerEntryType } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+
+/**
+ * Convert micro-USD (bigint) to a display string like "$12.50".
+ *
+ * Micro-USD uses 6 decimal places (1 USD = 1,000,000 micros).
+ * The output always shows exactly 2 decimal places.
+ */
+export function formatCreditBalance(micros: bigint | undefined): string {
+  if (micros === undefined) return "$0.00";
+  const cents = Number(micros) / 10_000;
+  const dollars = cents / 100;
+  return `$${dollars.toFixed(2)}`;
+}
+
+/**
+ * Convert micro-USD (bigint) to a signed display string.
+ *
+ * Positive amounts show "+$5.00", negative show "-$0.23",
+ * zero shows "$0.00" (no sign).
+ */
+export function formatLedgerAmount(micros: bigint): string {
+  const zero = BigInt(0);
+  const absMicros = micros < zero ? -micros : micros;
+  const dollars = Number(absMicros) / 1_000_000;
+  const formatted = `$${dollars.toFixed(2)}`;
+  if (micros > zero) return `+${formatted}`;
+  if (micros < zero) return `-${formatted}`;
+  return formatted;
+}
+
+const ENTRY_LABELS: Record<number, string> = {
+  [LedgerEntryType.purchase_credit]: "Credit Purchase",
+  [LedgerEntryType.promotional_credit]: "Promotional Credit",
+  [LedgerEntryType.usage_debit]: "Usage",
+  [LedgerEntryType.reservation_hold]: "Reservation Hold",
+  [LedgerEntryType.reservation_release]: "Reservation Release",
+  [LedgerEntryType.adjustment_credit]: "Admin Credit",
+  [LedgerEntryType.adjustment_debit]: "Admin Debit",
+  [LedgerEntryType.refund_reversal]: "Refund",
+  [LedgerEntryType.dispute_hold]: "Dispute Hold",
+  [LedgerEntryType.dispute_release]: "Dispute Release",
+  [LedgerEntryType.expiry_debit]: "Credit Expiry",
+  [LedgerEntryType.auto_recharge_credit]: "Auto-Recharge",
+};
+
+/** Human-readable label for a ledger entry type. */
+export function ledgerEntryLabel(type: LedgerEntryType): string {
+  return ENTRY_LABELS[type] ?? "Unknown";
+}
+
+/**
+ * Whether a ledger entry type represents a credit (positive amount).
+ *
+ * Used by UI components to choose semantic colors: green for credits,
+ * red for debits, gray for holds/releases.
+ */
+export function isCredit(type: LedgerEntryType): boolean {
+  return (
+    type === LedgerEntryType.purchase_credit ||
+    type === LedgerEntryType.promotional_credit ||
+    type === LedgerEntryType.adjustment_credit ||
+    type === LedgerEntryType.reservation_release ||
+    type === LedgerEntryType.dispute_release ||
+    type === LedgerEntryType.auto_recharge_credit
+  );
+}
+
+/**
+ * Whether a ledger entry type represents a hold operation.
+ *
+ * Holds are neither credits nor debits in the user's mental model —
+ * they represent temporary balance changes (reservations, disputes).
+ */
+export function isHold(type: LedgerEntryType): boolean {
+  return (
+    type === LedgerEntryType.reservation_hold ||
+    type === LedgerEntryType.dispute_hold
+  );
+}
+
+/**
+ * Format a protobuf Timestamp for ledger display.
+ *
+ * Returns a locale-appropriate date and time string
+ * (e.g., "May 3, 2026, 4:30 PM").
+ */
+export function formatLedgerDate(seconds: bigint): string {
+  const date = new Date(Number(seconds) * 1000);
+  return new Intl.DateTimeFormat("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  }).format(date);
+}

package/src/billing/index.ts

@@ -0,0 +1,51 @@
+// Data hooks
+export { useBillingAccount } from "./useBillingAccount";
+export type { UseBillingAccountReturn } from "./useBillingAccount";
+export { useCreditLedger } from "./useCreditLedger";
+export type { UseCreditLedgerReturn, UseCreditLedgerOptions } from "./useCreditLedger";
+export { useBillingUsageReport } from "./useBillingUsageReport";
+export type { UseBillingUsageReportReturn } from "./useBillingUsageReport";
+export { useCustomerModelPricing } from "./useCustomerModelPricing";
+export type { UseCustomerModelPricingReturn } from "./useCustomerModelPricing";
+
+// Behavior hooks
+export { useCreateCheckoutSession } from "./useCreateCheckoutSession";
+export type {
+  CreateCheckoutSessionInput,
+  UseCreateCheckoutSessionReturn,
+} from "./useCreateCheckoutSession";
+export { useCreateBillingPortalSession } from "./useCreateBillingPortalSession";
+export type { UseCreateBillingPortalSessionReturn } from "./useCreateBillingPortalSession";
+export { useSetAutoRechargeConfig } from "./useSetAutoRechargeConfig";
+export type {
+  SetAutoRechargeConfigInput,
+  UseSetAutoRechargeConfigReturn,
+} from "./useSetAutoRechargeConfig";
+
+// Styled components
+export { BillingSection } from "./BillingSection";
+export type { BillingSectionProps } from "./BillingSection";
+export { CreditBalanceCard } from "./CreditBalanceCard";
+export type { CreditBalanceCardProps } from "./CreditBalanceCard";
+export { PaymentMethodCard } from "./PaymentMethodCard";
+export type { PaymentMethodCardProps } from "./PaymentMethodCard";
+export { AutoRechargeCard } from "./AutoRechargeCard";
+export type { AutoRechargeCardProps } from "./AutoRechargeCard";
+export { CreditPackGrid } from "./CreditPackGrid";
+export type { CreditPackGridProps } from "./CreditPackGrid";
+export { CreditLedgerTable } from "./CreditLedgerTable";
+export type { CreditLedgerTableProps } from "./CreditLedgerTable";
+export { LowBalanceBanner } from "./LowBalanceBanner";
+export type { LowBalanceBannerProps } from "./LowBalanceBanner";
+
+// Credit pack catalog and formatting utilities
+export { CREDIT_PACKS, formatPackPrice, formatCreditCount } from "./credit-packs";
+export type { CreditPackInfo } from "./credit-packs";
+export {
+  formatCreditBalance,
+  formatLedgerAmount,
+  ledgerEntryLabel,
+  isCredit,
+  isHold,
+  formatLedgerDate,
+} from "./format";

package/src/billing/useBillingAccount.ts

@@ -0,0 +1,64 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import {
+  GetOrCreateBillingAccountInputSchema,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import type { BillingAccount } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useBillingAccount}. */
+export interface UseBillingAccountReturn {
+  /** The billing account, or `null` before the first successful fetch. */
+  readonly account: BillingAccount | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the billing account for an organization.
+ *
+ * Calls `billing.getOrCreateBillingAccount` which is idempotent —
+ * creates the account on first call, returns the existing account
+ * on subsequent calls. The returned `BillingAccount` includes
+ * the embedded `CreditBalance` with available, reserved,
+ * promotional, and purchased breakdowns.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ *
+ * @param orgId - Organization ID, or `null` to skip.
+ *
+ * @example
+ * ```tsx
+ * const { account, isLoading, error } = useBillingAccount(orgId);
+ *
+ * if (isLoading) return <Skeleton />;
+ * if (error) return <ErrorMessage error={error} />;
+ * if (!account) return null;
+ *
+ * return <div>Balance: {formatCreditBalance(account.balance?.availableMicros)}</div>;
+ * ```
+ */
+export function useBillingAccount(
+  orgId: string | null,
+): UseBillingAccountReturn {
+  const stigmer = useStigmer();
+
+  const { data: account, isLoading, isRefetching, error, refetch } = useFetch(
+    orgId
+      ? () =>
+          stigmer.billing.getOrCreateBillingAccount(orgId)
+      : null,
+    [orgId, stigmer],
+    null as BillingAccount | null,
+  );
+
+  return { account, isLoading, isRefetching, error, refetch };
+}

package/src/billing/useBillingUsageReport.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import type {
+  BillingUsageReportResponse,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useBillingUsageReport}. */
+export interface UseBillingUsageReportReturn {
+  /** The usage report, or `null` before the first successful fetch. */
+  readonly report: BillingUsageReportResponse | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches an aggregated billing usage report for a date range.
+ *
+ * Returns total provider cost, total billable amount, execution and LLM
+ * call counts, and a per-model breakdown with cost tier attribution.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ *
+ * @param orgId - Organization ID, or `null` to skip.
+ * @param startTime - Start of the reporting period.
+ * @param endTime - End of the reporting period.
+ *
+ * @example
+ * ```tsx
+ * const { report, isLoading } = useBillingUsageReport(
+ *   orgId,
+ *   new Date("2026-05-01"),
+ *   new Date("2026-05-31"),
+ * );
+ *
+ * if (isLoading) return <Skeleton />;
+ * if (!report) return null;
+ *
+ * return <div>Total: {formatCreditBalance(report.totalBillableAmountMicros)}</div>;
+ * ```
+ */
+export function useBillingUsageReport(
+  orgId: string | null,
+  startTime: Date,
+  endTime: Date,
+): UseBillingUsageReportReturn {
+  const stigmer = useStigmer();
+
+  const startKey = startTime.toISOString();
+  const endKey = endTime.toISOString();
+
+  const { data: report, isLoading, isRefetching, error, refetch } = useFetch(
+    orgId
+      ? () =>
+          stigmer.billing.getBillingUsageReport({
+            orgId,
+            startTime,
+            endTime,
+          })
+      : null,
+    [orgId, startKey, endKey, stigmer],
+    null as BillingUsageReportResponse | null,
+  );
+
+  return { report, isLoading, isRefetching, error, refetch };
+}