@stigmer/react 0.3.4 → 0.4.0

package/src/billing/AutoRechargeCard.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+import { useState, useCallback, useEffect } from "react";
+import { cn } from "@stigmer/theme";
+import type { AutoRechargeConfig } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
+import { BillingAccountStatus } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+import { getUserMessage } from "@stigmer/sdk";
+import { useSetAutoRechargeConfig } from "./useSetAutoRechargeConfig";
+
+/** Props for {@link AutoRechargeCard}. */
+export interface AutoRechargeCardProps {
+  /** Organization ID. */
+  readonly orgId: string;
+  /** Current auto-recharge configuration from the billing account. */
+  readonly autoRecharge?: AutoRechargeConfig;
+  /** Whether the account has a saved payment method. */
+  readonly hasPaymentMethod: boolean;
+  /** Account status — config disabled when suspended or closed. */
+  readonly accountStatus: BillingAccountStatus;
+  /** Called after a successful save so the parent can refresh account data. */
+  readonly onSaved?: () => void;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+const MICROS_PER_DOLLAR = BigInt(1_000_000);
+
+function microsToDollars(micros: bigint): string {
+  if (micros === BigInt(0)) return "";
+  const dollars = Number(micros) / 1_000_000;
+  return dollars.toString();
+}
+
+function dollarsToMicros(value: string): bigint {
+  const num = parseFloat(value);
+  if (isNaN(num) || num < 0) return BigInt(0);
+  return BigInt(Math.round(num * 1_000_000));
+}
+
+/**
+ * Auto-recharge configuration card for the billing settings page.
+ *
+ * Shows a toggle to enable/disable auto-recharge, with input fields
+ * for threshold, recharge amount, and monthly cap. Displays a
+ * disabled state with an explanatory message when no payment method
+ * is on file. Validates inputs client-side before submitting.
+ *
+ * @example
+ * ```tsx
+ * <AutoRechargeCard
+ *   orgId={orgId}
+ *   autoRecharge={account.autoRecharge}
+ *   hasPaymentMethod={!!account.defaultPaymentMethod?.paymentMethodId}
+ *   accountStatus={account.status}
+ *   onSaved={refetch}
+ * />
+ * ```
+ */
+export function AutoRechargeCard({
+  orgId,
+  autoRecharge,
+  hasPaymentMethod,
+  accountStatus,
+  onSaved,
+  className,
+}: AutoRechargeCardProps) {
+  const { setConfig, isSubmitting, error, clearError } =
+    useSetAutoRechargeConfig();
+
+  const [enabled, setEnabled] = useState(autoRecharge?.enabled ?? false);
+  const [threshold, setThreshold] = useState(
+    microsToDollars(autoRecharge?.thresholdMicros ?? BigInt(0)),
+  );
+  const [amount, setAmount] = useState(
+    microsToDollars(autoRecharge?.rechargeAmountMicros ?? BigInt(0)),
+  );
+  const [cap, setCap] = useState(
+    microsToDollars(autoRecharge?.monthlyCapMicros ?? BigInt(0)),
+  );
+  const [saved, setSaved] = useState(false);
+
+  useEffect(() => {
+    if (!autoRecharge) return;
+    setEnabled(autoRecharge.enabled);
+    setThreshold(microsToDollars(autoRecharge.thresholdMicros));
+    setAmount(microsToDollars(autoRecharge.rechargeAmountMicros));
+    setCap(microsToDollars(autoRecharge.monthlyCapMicros));
+  }, [autoRecharge]);
+
+  const isAccountActive =
+    accountStatus === BillingAccountStatus.billing_account_active;
+  const canConfigure = hasPaymentMethod && isAccountActive;
+
+  const hasChanges =
+    enabled !== (autoRecharge?.enabled ?? false) ||
+    dollarsToMicros(threshold) !==
+      (autoRecharge?.thresholdMicros ?? BigInt(0)) ||
+    dollarsToMicros(amount) !==
+      (autoRecharge?.rechargeAmountMicros ?? BigInt(0)) ||
+    dollarsToMicros(cap) !== (autoRecharge?.monthlyCapMicros ?? BigInt(0));
+
+  const handleSave = useCallback(async () => {
+    clearError();
+    setSaved(false);
+
+    try {
+      await setConfig({
+        orgId,
+        enabled,
+        thresholdMicros: dollarsToMicros(threshold),
+        rechargeAmountMicros: dollarsToMicros(amount),
+        monthlyCapMicros: dollarsToMicros(cap),
+      });
+      setSaved(true);
+      onSaved?.();
+      setTimeout(() => setSaved(false), 3000);
+    } catch {
+      // error state is managed by the hook
+    }
+  }, [orgId, enabled, threshold, amount, cap, setConfig, clearError, onSaved]);
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border border-border bg-card px-4 py-4",
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between">
+        <div>
+          <h3 className="text-xs font-semibold text-foreground">
+            Auto-Recharge
+          </h3>
+          <p className="mt-0.5 text-[0.7rem] text-muted-foreground">
+            Automatically add credits when your balance runs low.
+          </p>
+        </div>
+        <button
+          type="button"
+          role="switch"
+          aria-checked={enabled}
+          disabled={!canConfigure || isSubmitting}
+          onClick={() => setEnabled((prev) => !prev)}
+          className={cn(
+            "relative inline-flex h-5 w-9 shrink-0 rounded-full transition-colors",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+            enabled ? "bg-primary" : "bg-muted",
+          )}
+        >
+          <span
+            className={cn(
+              "pointer-events-none block size-4 rounded-full bg-background shadow-sm ring-0 transition-transform",
+              enabled ? "translate-x-4" : "translate-x-0.5",
+              "mt-0.5",
+            )}
+          />
+        </button>
+      </div>
+
+      {!hasPaymentMethod && (
+        <p className="mt-3 text-xs text-muted-foreground">
+          A saved payment method is required to enable auto-recharge.
+          Purchase a credit pack first to save a card.
+        </p>
+      )}
+
+      {canConfigure && (
+        <div className="mt-4 space-y-3">
+          <DollarInput
+            id="ar-threshold"
+            label="When balance drops below"
+            value={threshold}
+            onChange={setThreshold}
+            disabled={isSubmitting}
+            placeholder="e.g. 5"
+          />
+          <DollarInput
+            id="ar-amount"
+            label="Recharge amount"
+            value={amount}
+            onChange={setAmount}
+            disabled={isSubmitting}
+            placeholder="e.g. 50"
+          />
+          <DollarInput
+            id="ar-cap"
+            label="Monthly cap"
+            value={cap}
+            onChange={setCap}
+            disabled={isSubmitting}
+            placeholder="e.g. 200"
+          />
+
+          <div className="flex items-center gap-3 pt-1">
+            <button
+              type="button"
+              disabled={!hasChanges || isSubmitting}
+              onClick={handleSave}
+              className={cn(
+                "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={isSubmitting}
+            >
+              {isSubmitting ? "Saving\u2026" : "Save"}
+            </button>
+            {saved && (
+              <span className="text-xs text-emerald-600 dark:text-emerald-400">
+                Saved
+              </span>
+            )}
+          </div>
+
+          {error && (
+            <p className="text-xs text-destructive" role="alert">
+              {getUserMessage(error)}
+            </p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// DollarInput (internal)
+// ---------------------------------------------------------------------------
+
+function DollarInput({
+  id,
+  label,
+  value,
+  onChange,
+  disabled,
+  placeholder,
+}: {
+  id: string;
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+  disabled?: boolean;
+  placeholder?: string;
+}) {
+  return (
+    <div>
+      <label htmlFor={id} className="block text-xs text-muted-foreground">
+        {label}
+      </label>
+      <div className="relative mt-1">
+        <span className="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-xs text-muted-foreground">
+          $
+        </span>
+        <input
+          id={id}
+          type="number"
+          min="0"
+          step="any"
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          disabled={disabled}
+          placeholder={placeholder}
+          className={cn(
+            "w-full rounded-md border border-input bg-background py-1.5 pl-6 pr-3 text-xs tabular-nums",
+            "text-foreground placeholder:text-muted-foreground/60",
+            "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+          )}
+        />
+      </div>
+    </div>
+  );
+}

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