@stigmer/react 0.3.3 → 0.4.0

package/src/billing/CreditLedgerTable.tsx

@@ -0,0 +1,281 @@
+"use client";
+
+import { useState } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import type { CreditLedgerEntry } from "@stigmer/protos/ai/stigmer/billing/v1/credit_pb";
+import {
+  formatLedgerAmount,
+  formatCreditBalance,
+  formatLedgerDate,
+  ledgerEntryLabel,
+  isCredit,
+  isHold,
+} from "./format";
+import { useCreditLedger, type UseCreditLedgerOptions } from "./useCreditLedger";
+
+/** Props for {@link CreditLedgerTable}. */
+export interface CreditLedgerTableProps {
+  /** Organization ID to fetch ledger entries for. */
+  readonly orgId: string;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Paginated transaction history table showing credit ledger entries.
+ *
+ * Displays entries with type badges, signed amounts, and running
+ * balance. Supports pagination with simple prev/next controls.
+ * Uses semantic colors: green for credits, red for debits, gray
+ * for holds and releases.
+ *
+ * @example
+ * ```tsx
+ * <CreditLedgerTable orgId={activeOrg.metadata.id} />
+ * ```
+ */
+export function CreditLedgerTable({
+  orgId,
+  className,
+}: CreditLedgerTableProps) {
+  const [pageNum, setPageNum] = useState(1);
+  const options: UseCreditLedgerOptions = { pageNum, pageSize: 10 };
+  const { ledger, isLoading, error } = useCreditLedger(orgId, options);
+
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-2", className)} aria-busy="true">
+        <div className="h-4 w-32 animate-pulse rounded bg-muted-subtle" />
+        {Array.from({ length: 5 }, (_, i) => (
+          <div
+            key={i}
+            className="h-10 animate-pulse rounded-lg bg-muted-subtle"
+          />
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <p className={cn("text-destructive text-xs", className)} role="alert">
+        {getUserMessage(error)}
+      </p>
+    );
+  }
+
+  const entries = ledger?.entries ?? [];
+  const totalPages = ledger?.totalPages ?? 0;
+
+  return (
+    <div className={className}>
+      <h3 className="mb-2 text-xs font-semibold text-foreground">
+        Transaction History
+      </h3>
+
+      {entries.length === 0 ? (
+        <EmptyLedger />
+      ) : (
+        <>
+          <div
+            className="rounded-lg border border-border bg-card"
+            role="table"
+            aria-label="Credit ledger"
+          >
+            <LedgerHeader />
+            {entries.map((entry) => (
+              <LedgerRow key={entry.entryId} entry={entry} />
+            ))}
+          </div>
+
+          {totalPages > 1 && (
+            <Pagination
+              pageNum={pageNum}
+              totalPages={totalPages}
+              onPageChange={setPageNum}
+            />
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// LedgerHeader (internal)
+// ---------------------------------------------------------------------------
+
+function LedgerHeader() {
+  return (
+    <div
+      role="row"
+      className="grid grid-cols-[1fr_auto_auto] gap-x-4 border-b border-border px-3.5 py-2 text-[0.65rem] font-medium uppercase tracking-wider text-muted-foreground sm:grid-cols-[auto_1fr_auto_auto]"
+    >
+      <span role="columnheader" className="hidden sm:block">
+        Date
+      </span>
+      <span role="columnheader">Type</span>
+      <span role="columnheader" className="text-right">
+        Amount
+      </span>
+      <span role="columnheader" className="text-right">
+        Balance
+      </span>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// LedgerRow (internal)
+// ---------------------------------------------------------------------------
+
+function LedgerRow({ entry }: { entry: CreditLedgerEntry }) {
+  const entryType = entry.type;
+  const credit = isCredit(entryType);
+  const hold = isHold(entryType);
+
+  return (
+    <div
+      role="row"
+      className="grid grid-cols-[1fr_auto_auto] items-center gap-x-4 border-b border-border-muted px-3.5 py-2.5 last:border-b-0 sm:grid-cols-[auto_1fr_auto_auto]"
+    >
+      <span
+        role="cell"
+        className="hidden text-xs tabular-nums text-muted-foreground sm:block sm:w-36"
+      >
+        {entry.createdAt
+          ? formatLedgerDate(entry.createdAt.seconds)
+          : "\u2014"}
+      </span>
+
+      <div role="cell" className="min-w-0">
+        <span
+          className={cn(
+            "inline-block rounded-full px-2 py-0.5 text-[0.65rem] font-medium",
+            credit
+              ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+              : hold
+                ? "bg-muted text-muted-foreground"
+                : "bg-destructive/10 text-destructive",
+          )}
+        >
+          {ledgerEntryLabel(entryType)}
+        </span>
+        {entry.source?.description && (
+          <span className="ml-2 text-xs text-muted-foreground">
+            {entry.source.description}
+          </span>
+        )}
+        {entry.createdAt && (
+          <span className="mt-0.5 block text-[0.6rem] tabular-nums text-muted-foreground sm:hidden">
+            {formatLedgerDate(entry.createdAt.seconds)}
+          </span>
+        )}
+      </div>
+
+      <span
+        role="cell"
+        className={cn(
+          "text-right text-xs font-medium tabular-nums",
+          credit
+            ? "text-emerald-600 dark:text-emerald-400"
+            : hold
+              ? "text-muted-foreground"
+              : "text-destructive",
+        )}
+      >
+        {formatLedgerAmount(entry.amountMicros)}
+      </span>
+
+      <span
+        role="cell"
+        className="text-right text-xs tabular-nums text-muted-foreground"
+      >
+        {formatCreditBalance(entry.balanceAfterMicros)}
+      </span>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Pagination (internal)
+// ---------------------------------------------------------------------------
+
+function Pagination({
+  pageNum,
+  totalPages,
+  onPageChange,
+}: {
+  pageNum: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+}) {
+  return (
+    <div
+      className="mt-3 flex items-center justify-between"
+      role="navigation"
+      aria-label="Ledger pagination"
+    >
+      <button
+        type="button"
+        disabled={pageNum <= 1}
+        onClick={() => onPageChange(pageNum - 1)}
+        className="rounded-md px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
+      >
+        Previous
+      </button>
+      <span className="text-xs tabular-nums text-muted-foreground">
+        Page {pageNum} of {totalPages}
+      </span>
+      <button
+        type="button"
+        disabled={pageNum >= totalPages}
+        onClick={() => onPageChange(pageNum + 1)}
+        className="rounded-md px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
+      >
+        Next
+      </button>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// EmptyLedger (internal)
+// ---------------------------------------------------------------------------
+
+function EmptyLedger() {
+  return (
+    <div className="flex flex-col items-center justify-center rounded-lg border border-border bg-card py-10 text-center">
+      <ReceiptIcon className="text-muted-foreground mb-3 size-8" />
+      <p className="text-sm font-medium text-foreground">
+        No transactions yet
+      </p>
+      <p className="mt-1 max-w-xs text-xs text-muted-foreground">
+        Credit purchases and usage charges will appear here as your
+        organization runs agent executions.
+      </p>
+    </div>
+  );
+}
+
+function ReceiptIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M4 2v20l2-1 2 1 2-1 2 1 2-1 2 1 2-1 2 1V2l-2 1-2-1-2 1-2-1-2 1-2-1-2 1Z" />
+      <path d="M16 8h-6a2 2 0 1 0 0 4h4a2 2 0 1 1 0 4H8" />
+      <path d="M12 17.5v.5M12 6v.5" />
+    </svg>
+  );
+}

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