@stigmer/react 0.3.4 → 0.4.1

package/src/billing/BillingSection.tsx

@@ -0,0 +1,255 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import { BillingAccountStatus } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+import { useDeploymentMode } from "../deployment-mode";
+import { CloudFeatureNotice } from "../internal/CloudFeatureNotice";
+import { useOrg } from "../organization/OrgProvider";
+import { useBillingAccount } from "./useBillingAccount";
+import { useCreateCheckoutSession } from "./useCreateCheckoutSession";
+import { useCreateBillingPortalSession } from "./useCreateBillingPortalSession";
+import { CreditBalanceCard } from "./CreditBalanceCard";
+import { PaymentMethodCard } from "./PaymentMethodCard";
+import { AutoRechargeCard } from "./AutoRechargeCard";
+import { CreditPackGrid } from "./CreditPackGrid";
+import { CreditLedgerTable } from "./CreditLedgerTable";
+import { LowBalanceBanner } from "./LowBalanceBanner";
+
+/** Props for {@link BillingSection}. */
+export interface BillingSectionProps {
+  /**
+   * Whether a checkout just completed (e.g., `?checkout=success`).
+   *
+   * When `true`, an optimistic banner is shown indicating that
+   * credits will appear shortly. This prop is typically driven
+   * by the host application's URL query parameters.
+   */
+  readonly checkoutSuccess?: boolean;
+  /** Callback to dismiss the checkout success banner. */
+  readonly onDismissCheckoutSuccess?: () => void;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Top-level billing settings section.
+ *
+ * Composes the billing sub-components into a cohesive settings page:
+ * low-balance warning, checkout success banner, credit balance display,
+ * credit pack purchase grid, and transaction history. Handles the
+ * deployment mode gate (billing unavailable in local mode) and the
+ * org-not-selected state.
+ *
+ * @example
+ * ```tsx
+ * // In a settings page:
+ * <BillingSection checkoutSuccess={searchParams.checkout === "success"} />
+ * ```
+ */
+export function BillingSection({
+  checkoutSuccess,
+  onDismissCheckoutSuccess,
+  className,
+}: BillingSectionProps) {
+  const { activeOrg } = useOrg();
+  const mode = useDeploymentMode();
+  const orgId = activeOrg?.metadata?.id ?? "";
+
+  return (
+    <section aria-labelledby="billing-heading" className={className}>
+      <h2
+        id="billing-heading"
+        className="text-foreground mb-1 text-sm font-semibold"
+      >
+        Billing
+      </h2>
+      <p className="text-muted-foreground mb-4 text-xs">
+        Manage credits, purchase credit packs, and view transaction history.
+      </p>
+
+      {mode === "local" ? (
+        <CloudFeatureNotice>
+          Billing is available on Stigmer Cloud. Connect to a Cloud
+          organization to manage credits and purchase credit packs.
+        </CloudFeatureNotice>
+      ) : !orgId ? (
+        <p className="text-muted-foreground py-4 text-center text-xs">
+          Select an organization to view billing.
+        </p>
+      ) : (
+        <BillingContent
+          orgId={orgId}
+          checkoutSuccess={checkoutSuccess}
+          onDismissCheckoutSuccess={onDismissCheckoutSuccess}
+        />
+      )}
+    </section>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// BillingContent (internal)
+// ---------------------------------------------------------------------------
+
+function BillingContent({
+  orgId,
+  checkoutSuccess,
+  onDismissCheckoutSuccess,
+}: {
+  orgId: string;
+  checkoutSuccess?: boolean;
+  onDismissCheckoutSuccess?: () => void;
+}) {
+  const { account, isLoading, error, refetch } = useBillingAccount(orgId);
+  const { createSession, isSubmitting, error: checkoutError, clearError } = useCreateCheckoutSession();
+  const { openPortal, isLoading: isPortalLoading } = useCreateBillingPortalSession();
+  const [purchasingPackId, setPurchasingPackId] = useState<string | null>(null);
+
+  const handlePurchase = useCallback(
+    (packId: string) => {
+      setPurchasingPackId(packId);
+      clearError();
+
+      const baseUrl = typeof window !== "undefined" ? window.location.origin : "";
+      const billingPath = `${baseUrl}/settings/billing`;
+
+      createSession({
+        orgId,
+        packId,
+        successUrl: `${billingPath}?checkout=success`,
+        cancelUrl: billingPath,
+      }).catch(() => {
+        setPurchasingPackId(null);
+      });
+    },
+    [orgId, createSession, clearError],
+  );
+
+  if (isLoading) {
+    return (
+      <div className="space-y-4" aria-busy="true" aria-label="Loading billing">
+        <div className="h-24 animate-pulse rounded-lg bg-muted-subtle" />
+        <div className="grid grid-cols-3 gap-3">
+          {Array.from({ length: 3 }, (_, i) => (
+            <div
+              key={i}
+              className="h-36 animate-pulse rounded-lg bg-muted-subtle"
+            />
+          ))}
+        </div>
+        <div className="h-48 animate-pulse rounded-lg bg-muted-subtle" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <p className="text-destructive text-xs" role="alert">
+        {getUserMessage(error)}
+      </p>
+    );
+  }
+
+  if (!account) return null;
+
+  const balance = account.balance;
+  if (!balance) return null;
+
+  const isLowBalance =
+    balance.availableMicros < account.lowBalanceThresholdMicros;
+
+  return (
+    <div className="space-y-6">
+      {checkoutSuccess && (
+        <CheckoutSuccessBanner onDismiss={onDismissCheckoutSuccess} />
+      )}
+
+      <LowBalanceBanner
+        availableMicros={balance.availableMicros}
+        thresholdMicros={account.lowBalanceThresholdMicros}
+      />
+
+      <CreditBalanceCard balance={balance} isLowBalance={isLowBalance} />
+
+      <PaymentMethodCard
+        paymentMethod={account.defaultPaymentMethod}
+        accountStatus={account.status}
+        isPortalLoading={isPortalLoading}
+        onManage={() => openPortal(orgId)}
+      />
+
+      <AutoRechargeCard
+        orgId={orgId}
+        autoRecharge={account.autoRecharge}
+        hasPaymentMethod={
+          account.defaultPaymentMethod != null &&
+          account.defaultPaymentMethod.paymentMethodId !== ""
+        }
+        accountStatus={account.status}
+        onSaved={refetch}
+      />
+
+      <CreditPackGrid
+        accountStatus={account.status}
+        purchasingPackId={isSubmitting ? purchasingPackId : null}
+        onPurchase={handlePurchase}
+      />
+
+      {checkoutError && (
+        <p className="text-destructive text-xs" role="alert">
+          {getUserMessage(checkoutError)}
+        </p>
+      )}
+
+      <CreditLedgerTable orgId={orgId} />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// CheckoutSuccessBanner (internal)
+// ---------------------------------------------------------------------------
+
+function CheckoutSuccessBanner({
+  onDismiss,
+}: {
+  onDismiss?: () => void;
+}) {
+  return (
+    <div
+      role="status"
+      className="flex items-center justify-between gap-3 rounded-lg border border-emerald-500/30 bg-emerald-500/5 px-3.5 py-3 text-xs text-emerald-700 dark:text-emerald-300"
+    >
+      <p>
+        <span className="font-medium">Payment received</span>
+        {" \u2014 "}
+        credits will appear in your balance shortly.
+      </p>
+      {onDismiss && (
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="shrink-0 rounded p-0.5 transition-colors hover:bg-emerald-500/10"
+          aria-label="Dismiss"
+        >
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+}

package/src/billing/CreditBalanceCard.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { CreditBalance } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
+import { formatCreditBalance } from "./format";
+
+/** Props for {@link CreditBalanceCard}. */
+export interface CreditBalanceCardProps {
+  /** The credit balance breakdown from the billing account. */
+  readonly balance: CreditBalance;
+  /** Whether the balance is below the low-balance threshold. */
+  readonly isLowBalance?: boolean;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Prominent display of the organization's available credit balance.
+ *
+ * Shows the total available balance as the primary figure, with
+ * a secondary breakdown of promotional vs. purchased credits and
+ * any reserved amount. Uses semantic colors to indicate balance
+ * health: green for healthy, amber for low, red for zero/negative.
+ *
+ * @example
+ * ```tsx
+ * <CreditBalanceCard balance={account.balance} isLowBalance={isLow} />
+ * ```
+ */
+export function CreditBalanceCard({
+  balance,
+  isLowBalance,
+  className,
+}: CreditBalanceCardProps) {
+  const available = balance.availableMicros;
+  const zero = BigInt(0);
+  const isZeroOrNegative = available <= zero;
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border border-border bg-card px-4 py-4",
+        className,
+      )}
+    >
+      <div className="text-xs font-medium text-muted-foreground">
+        Available Credits
+      </div>
+      <div
+        className={cn(
+          "mt-1 text-2xl font-bold tabular-nums",
+          isZeroOrNegative
+            ? "text-destructive"
+            : isLowBalance
+              ? "text-warning-foreground"
+              : "text-foreground",
+        )}
+      >
+        {formatCreditBalance(available)}
+      </div>
+
+      <div className="mt-3 flex flex-wrap gap-x-4 gap-y-1 text-xs tabular-nums text-muted-foreground">
+        {balance.purchasedMicros > zero && (
+          <span>
+            Purchased: {formatCreditBalance(balance.purchasedMicros)}
+          </span>
+        )}
+        {balance.promotionalMicros > zero && (
+          <span>
+            Promotional: {formatCreditBalance(balance.promotionalMicros)}
+          </span>
+        )}
+        {balance.reservedMicros > zero && (
+          <span>
+            Reserved: {formatCreditBalance(balance.reservedMicros)}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}

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