@stigmer/react 0.3.3 → 0.4.0

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

package/src/billing/useCreateBillingPortalSession.ts

@@ -0,0 +1,76 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useCreateBillingPortalSession}. */
+export interface UseCreateBillingPortalSessionReturn {
+  /**
+   * Open the Stripe Customer Portal for payment method management.
+   *
+   * On success, redirects the user to the Stripe-hosted portal page.
+   * The promise resolves before the redirect occurs.
+   */
+  readonly openPortal: (orgId: string) => Promise<void>;
+  /** `true` while the portal session is being created. */
+  readonly isLoading: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that opens the Stripe Customer Portal for payment
+ * method management.
+ *
+ * Wraps `billing.createBillingPortalSession` with loading and error
+ * state management. On success, redirects the user to the Stripe-hosted
+ * portal. Payment method changes are synced back via webhooks.
+ *
+ * @example
+ * ```tsx
+ * const { openPortal, isLoading } = useCreateBillingPortalSession();
+ *
+ * <button onClick={() => openPortal(orgId)} disabled={isLoading}>
+ *   Manage payment methods
+ * </button>
+ * ```
+ */
+export function useCreateBillingPortalSession(): UseCreateBillingPortalSessionReturn {
+  const stigmer = useStigmer();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const openPortal = useCallback(
+    async (orgId: string): Promise<void> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const returnUrl =
+          typeof window !== "undefined" ? window.location.href : "";
+
+        const response = await stigmer.billing.createBillingPortalSession({
+          orgId,
+          returnUrl,
+        });
+
+        if (response.portalUrl) {
+          window.location.href = response.portalUrl;
+        }
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { openPortal, isLoading, error, clearError };
+}

package/src/billing/useCreateCheckoutSession.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { CreateCreditCheckoutSessionResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Parameters for {@link useCreateCheckoutSession}'s `createSession` callback. */
+export interface CreateCheckoutSessionInput {
+  /** Organization purchasing credits. */
+  readonly orgId: string;
+  /** Credit pack to purchase (e.g., "starter", "growth", "team"). */
+  readonly packId: string;
+  /** URL to redirect to after successful payment. */
+  readonly successUrl: string;
+  /** URL to redirect to if the user cancels checkout. */
+  readonly cancelUrl: string;
+}
+
+/** Return value of {@link useCreateCheckoutSession}. */
+export interface UseCreateCheckoutSessionReturn {
+  /**
+   * Create a Stripe Checkout Session and redirect the user.
+   *
+   * On success, sets `window.location.href` to the Stripe-hosted
+   * checkout page URL. The promise resolves with the response before
+   * the redirect occurs, allowing callers to perform cleanup if needed.
+   */
+  readonly createSession: (
+    input: CreateCheckoutSessionInput,
+  ) => Promise<CreateCreditCheckoutSessionResponse>;
+  /** `true` while the checkout session is being created. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that creates a Stripe Checkout Session for credit
+ * pack purchases.
+ *
+ * Wraps `billing.createCreditCheckoutSession` with loading and error
+ * state management. On success, redirects the user to the Stripe-hosted
+ * checkout page. Credits are provisioned asynchronously via webhook
+ * after payment succeeds.
+ *
+ * @example
+ * ```tsx
+ * const { createSession, isSubmitting, error } = useCreateCheckoutSession();
+ *
+ * const handleBuy = () => {
+ *   createSession({
+ *     orgId,
+ *     packId: "growth",
+ *     successUrl: `${window.location.origin}/settings/billing?checkout=success`,
+ *     cancelUrl: `${window.location.origin}/settings/billing`,
+ *   });
+ * };
+ * ```
+ */
+export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const createSession = useCallback(
+    async (
+      input: CreateCheckoutSessionInput,
+    ): Promise<CreateCreditCheckoutSessionResponse> => {
+      setIsSubmitting(true);
+      setError(null);
+
+      try {
+        const response = await stigmer.billing.createCreditCheckoutSession({
+          orgId: input.orgId,
+          packId: input.packId,
+          successUrl: input.successUrl,
+          cancelUrl: input.cancelUrl,
+        });
+
+        if (response.checkoutUrl) {
+          window.location.href = response.checkoutUrl;
+        }
+
+        return response;
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { createSession, isSubmitting, error, clearError };
+}

package/src/billing/useCreditLedger.ts

@@ -0,0 +1,79 @@
+"use client";
+
+import type {
+  CreditLedgerResponse,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import type { LedgerEntryType } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useCreditLedger}. */
+export interface UseCreditLedgerReturn {
+  /** The ledger response, or `null` before the first successful fetch. */
+  readonly ledger: CreditLedgerResponse | 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;
+}
+
+/** Options for {@link useCreditLedger}. */
+export interface UseCreditLedgerOptions {
+  /** 1-based page number. Defaults to 1. */
+  readonly pageNum?: number;
+  /** Page size. Defaults to 20. */
+  readonly pageSize?: number;
+  /** Filter to specific ledger entry types. Empty means all types. */
+  readonly typeFilter?: LedgerEntryType[];
+}
+
+/**
+ * Data hook that fetches paginated credit ledger entries for an organization.
+ *
+ * Calls `billing.getCreditLedger` with optional pagination and type
+ * filtering. Returns the entries and total page count for building
+ * pagination controls.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ *
+ * @param orgId - Organization ID, or `null` to skip.
+ * @param options - Pagination and filter options.
+ *
+ * @example
+ * ```tsx
+ * const { ledger, isLoading } = useCreditLedger(orgId, { pageNum: 1 });
+ *
+ * if (isLoading) return <Skeleton />;
+ * if (!ledger) return null;
+ *
+ * return ledger.entries.map(entry => <LedgerRow key={entry.entryId} entry={entry} />);
+ * ```
+ */
+export function useCreditLedger(
+  orgId: string | null,
+  options: UseCreditLedgerOptions = {},
+): UseCreditLedgerReturn {
+  const stigmer = useStigmer();
+  const { pageNum = 1, pageSize = 20, typeFilter } = options;
+
+  const typeFilterKey = typeFilter?.join(",") ?? "";
+
+  const { data: ledger, isLoading, isRefetching, error, refetch } = useFetch(
+    orgId
+      ? () =>
+          stigmer.billing.getCreditLedger({
+            orgId,
+            page: { num: pageNum, size: pageSize },
+            typeFilter,
+          })
+      : null,
+    [orgId, pageNum, pageSize, typeFilterKey, stigmer],
+    null as CreditLedgerResponse | null,
+  );
+
+  return { ledger, isLoading, isRefetching, error, refetch };
+}

package/src/billing/useCustomerModelPricing.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import type {
+  CustomerModelPricingResponse,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useCustomerModelPricing}. */
+export interface UseCustomerModelPricingReturn {
+  /** The pricing response, or `null` before the first successful fetch. */
+  readonly pricing: CustomerModelPricingResponse | 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 customer-facing model price list.
+ *
+ * Returns per-million-token prices for all billable models with
+ * billing policy markup already applied, organized by harness
+ * and cost tier.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ * Pass `undefined` to fetch default pricing (no org override).
+ *
+ * @param orgId - Organization ID for org-specific overrides,
+ *   `undefined` for default pricing, or `null` to skip.
+ *
+ * @example
+ * ```tsx
+ * const { pricing, isLoading } = useCustomerModelPricing(orgId);
+ *
+ * if (isLoading) return <Skeleton />;
+ * if (!pricing) return null;
+ *
+ * return pricing.entries.map(entry => (
+ *   <PricingRow key={entry.modelId} entry={entry} />
+ * ));
+ * ```
+ */
+export function useCustomerModelPricing(
+  orgId: string | undefined | null,
+): UseCustomerModelPricingReturn {
+  const stigmer = useStigmer();
+
+  const skip = orgId === null;
+
+  const { data: pricing, isLoading, isRefetching, error, refetch } = useFetch(
+    skip
+      ? null
+      : () =>
+          stigmer.billing.getCustomerModelPricing(
+            orgId ? { orgId } : undefined,
+          ),
+    [orgId, stigmer],
+    null as CustomerModelPricingResponse | null,
+  );
+
+  return { pricing, isLoading, isRefetching, error, refetch };
+}