@stigmer/react 3.39.1-dev.20260928194002 → 3.40.0

package/src/billing/PlanPicker.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import { Button } from "../button/index.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
+import {
+  formatManagedOrganizations,
+  formatMonthlyMinimum,
+  explainUsageShare,
+  offeredFeatures,
+} from "./plan-features.js";
+import { planMove, type PlanMove, type PlanStanding } from "./plan-state.js";
+
+/** Where Enterprise enquiries go by default. */
+export const ENTERPRISE_CONTACT_URL = "https://stigmer.ai/contact-sales";
+
+/** Props for {@link PlanPicker}. */
+export interface PlanPickerProps {
+  /** The plans that can be bought, cheapest first, as `buyablePlans` orders them. */
+  readonly plans: readonly Plan[];
+  /** Where the organization stands. */
+  readonly standing: PlanStanding;
+  /** The live period's end, which a cancel runs to. */
+  readonly periodEnd?: Date;
+  /**
+   * Whether the viewer may change the plan (`can_manage_billing`). Without
+   * it the comparison is read-only.
+   */
+  readonly canManage: boolean;
+  /** Called with the move a choice makes; the host confirms it. */
+  readonly onChoose: (move: PlanMove) => void;
+  /** Disables every choice, e.g. while a change is in flight. */
+  readonly disabled?: boolean;
+  /** Where "Talk to us" for Enterprise links. Defaults to {@link ENTERPRISE_CONTACT_URL}. */
+  readonly enterpriseHref?: string;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * The plan comparison: Free, each plan that can be bought, and
+ * Enterprise, each with its price and what it offers today. A choice
+ * reports the move it makes (subscribe, switch, resume or cancel) for the
+ * host to confirm; the plan in force reads "Current plan".
+ */
+export function PlanPicker({
+  plans,
+  standing,
+  periodEnd,
+  canManage,
+  onChoose,
+  disabled,
+  enterpriseHref = ENTERPRISE_CONTACT_URL,
+  className,
+}: PlanPickerProps) {
+  const freeMove = planMove(standing, "free", periodEnd);
+  return (
+    <ul className={cn(UNSTYLED_LIST, "stg:grid stg:gap-3 stg:sm:grid-cols-2", className)} aria-label="Plans">
+      <PlanOption
+        name="Free"
+        price="$0/month"
+        detail="Usage is paid from credits."
+        features={["Channels", "Sharing", "Unlimited members"]}
+        current={standing.kind === "free"}
+        action={canManage && freeMove !== null ? { label: "Move to Free", move: freeMove } : undefined}
+        disabled={disabled}
+        onChoose={onChoose}
+      />
+      {plans.map((plan) => {
+        const move = planMove(standing, plan, periodEnd);
+        const managed = formatManagedOrganizations(plan.spec?.entitlements, plan.spec?.terms);
+        return (
+          <PlanOption
+            key={plan.metadata?.id ?? plan.metadata?.slug}
+            name={plan.metadata?.name ?? ""}
+            price={formatMonthlyMinimum(plan.spec?.terms)}
+            detail={explainUsageShare(plan.spec?.terms)}
+            features={[
+              ...offeredFeatures(plan.spec?.entitlements).map((feature) => feature.label),
+              ...(managed === "" ? [] : [managed]),
+            ]}
+            current={move === null && standing.kind !== "free"}
+            action={canManage && move !== null ? { label: actionLabel(move), move } : undefined}
+            disabled={disabled}
+            onChoose={onChoose}
+          />
+        );
+      })}
+      <li className="stg:flex stg:flex-col stg:rounded-lg stg:border stg:border-border stg:bg-card stg:p-4">
+        <p className="stg:text-sm stg:font-medium stg:text-foreground">Enterprise</p>
+        <p className="stg:mt-1 stg:text-xs stg:text-muted-foreground">
+          A dedicated deployment, SSO enforcement, an SLA and annual invoicing, quoted for your organization.
+        </p>
+        <a
+          href={enterpriseHref}
+          target="_blank"
+          rel="noreferrer"
+          className="stg:mt-3 stg:self-start stg:text-xs stg:font-medium stg:text-primary stg:hover:underline"
+        >
+          Talk to us
+        </a>
+      </li>
+    </ul>
+  );
+}
+
+function PlanOption({
+  name,
+  price,
+  detail,
+  features,
+  current,
+  action,
+  disabled,
+  onChoose,
+}: {
+  readonly name: string;
+  readonly price: string;
+  readonly detail: string;
+  readonly features: readonly string[];
+  readonly current: boolean;
+  readonly action?: { readonly label: string; readonly move: PlanMove };
+  readonly disabled?: boolean;
+  readonly onChoose: (move: PlanMove) => void;
+}) {
+  return (
+    <li
+      className={cn(
+        "stg:flex stg:flex-col stg:rounded-lg stg:border stg:bg-card stg:p-4",
+        current ? "stg:border-primary" : "stg:border-border",
+      )}
+      aria-current={current ? "true" : undefined}
+    >
+      <div className="stg:flex stg:items-baseline stg:justify-between stg:gap-2">
+        <p className="stg:text-sm stg:font-medium stg:text-foreground">{name}</p>
+        <p className="stg:text-xs stg:tabular-nums stg:text-foreground">{price}</p>
+      </div>
+      {detail !== "" && <p className="stg:mt-1 stg:text-xs stg:text-muted-foreground">{detail}</p>}
+      <ul className={cn(UNSTYLED_LIST, "stg:mt-2 stg:space-y-0.5 stg:text-xs stg:text-muted-foreground")}>
+        {features.map((feature) => (
+          <li key={feature}>{feature}</li>
+        ))}
+      </ul>
+      <div className="stg:mt-auto stg:pt-3">
+        {current ? (
+          <span className="stg:text-xs stg:font-medium stg:text-primary">Current plan</span>
+        ) : action ? (
+          <Button
+            variant={action.move.kind === "cancel" ? "outline" : "primary"}
+            size="xs"
+            disabled={disabled}
+            onClick={() => onChoose(action.move)}
+          >
+            {action.label}
+          </Button>
+        ) : null}
+      </div>
+    </li>
+  );
+}
+
+function actionLabel(move: PlanMove): string {
+  switch (move.kind) {
+    case "subscribe":
+      return "Subscribe";
+    case "switch":
+      return `Switch to ${move.to.metadata?.name ?? "this plan"}`;
+    case "resume":
+      return `Keep ${move.to.metadata?.name ?? "this plan"}`;
+    case "cancel":
+      return "Move to Free";
+    default: {
+      const exhaustive: never = move;
+      return String(exhaustive);
+    }
+  }
+}

package/src/billing/PlanSection.tsx

@@ -0,0 +1,234 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import { ApiResourceKind, useResourceAvailable } from "../deployment-mode.js";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import { ChangePlanDialog } from "./ChangePlanDialog.js";
+import { PlanCard } from "./PlanCard.js";
+import { PlanPicker } from "./PlanPicker.js";
+import { buyablePlans, featuresLost } from "./plan-features.js";
+import { planMove, planStanding, standingPlanId, type PlanMove } from "./plan-state.js";
+import type { BillingRedirect } from "./redirect.js";
+import { useCancelSubscription, useChangePlan } from "./useChangePlan.js";
+import { useCreatePaymentMethodSetupSession } from "./useCreatePaymentMethodSetupSession.js";
+import { usePeriodEstimate } from "./usePeriodEstimate.js";
+import { usePlans } from "./usePlans.js";
+import { useSubscription } from "./useSubscription.js";
+
+/** How often, and how long, the section waits for a just-saved card to reach the account. */
+const CARD_POLL_MS = 2_000;
+const CARD_WAIT_MS = 30_000;
+
+/** Props for {@link PlanSection}. */
+export interface PlanSectionProps {
+  /** The organization whose plan is shown. */
+  readonly orgId: string;
+  /**
+   * The organization is platform-managed: it runs on its integrator's
+   * plan, and the section says so instead of offering plans.
+   */
+  readonly managed?: boolean;
+  /** Whether the organization's billing account holds a saved card. */
+  readonly hasPaymentMethod: boolean;
+  /** Re-read the billing account, so a card saved on Stripe's page shows. */
+  readonly onRefreshAccount?: () => void;
+  /** The host's seam for Stripe-hosted pages (see {@link BillingRedirect}). */
+  readonly redirect?: BillingRedirect;
+  /**
+   * The plan the person was choosing when they left to save a card (the
+   * `plan` query Stripe returns with). The section reopens that choice for
+   * an explicit confirm; it never subscribes on its own.
+   */
+  readonly resumePlanId?: string;
+  /** Called once the resumed choice has been taken up, so the host can clear its query. */
+  readonly onResumeHandled?: () => void;
+  /** The clock the standing reads. Defaults to each render's time. */
+  readonly now?: Date;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * An organization's plan on Stigmer Cloud: the current plan with its
+ * standing and the period's estimated invoice, the plan comparison, and
+ * the confirm step for a subscribe, switch, resume or cancel.
+ *
+ * Everyone who can view the organization's billing reads it; only those
+ * who can manage billing (its admins) see the choices. Renders nothing on
+ * an edition that serves no subscriptions.
+ *
+ * @example
+ * ```tsx
+ * <PlanSection orgId={orgId} hasPaymentMethod={hasCard} />
+ * ```
+ */
+export function PlanSection({
+  orgId,
+  managed = false,
+  hasPaymentMethod,
+  onRefreshAccount,
+  redirect,
+  resumePlanId,
+  onResumeHandled,
+  now,
+  className,
+}: PlanSectionProps) {
+  const available = useResourceAvailable(ApiResourceKind.subscription);
+  const renderNow = now ?? new Date();
+  const catalog = usePlans({ includeRetired: true, enabled: available });
+  const current = useSubscription(available ? orgId : null);
+  const standing = planStanding(current.subscription, renderNow);
+  const livePlanId = standingPlanId(standing);
+  const estimate = usePeriodEstimate(orgId, { enabled: available && !managed && livePlanId !== "" });
+  const manage = useCheckPermission(available && orgId ? { kind: "organization", id: orgId } : null, "can_manage_billing");
+  const canManage = !managed && !manage.isLoading && manage.allowed;
+
+  const changer = useChangePlan();
+  const canceler = useCancelSubscription();
+  const setup = useCreatePaymentMethodSetupSession(redirect);
+  const [move, setMove] = useState<PlanMove | null>(null);
+  const [awaitingCard, setAwaitingCard] = useState(false);
+
+  const buyable = useMemo(() => buyablePlans(catalog.plans ?? []), [catalog.plans]);
+  const planById = useCallback(
+    (planId: string) => catalog.plans?.find((plan) => plan.metadata?.id === planId),
+    [catalog.plans],
+  );
+  const planName = useCallback((planId: string) => planById(planId)?.metadata?.name ?? "your plan", [planById]);
+  const periodEndStamp = current.subscription?.status?.currentPeriodEnd;
+  const periodEnd = periodEndStamp === undefined ? undefined : timestampDate(periodEndStamp);
+
+  // Back from Stripe's card page: reopen the choice the person was making.
+  // Keyed by the plan resumed, and cleared once the host drops the query,
+  // because a desktop host stays mounted across returns and may resume again.
+  const resumedFor = useRef<string | null>(null);
+  useEffect(() => {
+    if (resumePlanId === undefined || resumePlanId === "") {
+      resumedFor.current = null;
+      return;
+    }
+    if (resumedFor.current === resumePlanId || catalog.plans === null || current.isLoading) {
+      return;
+    }
+    resumedFor.current = resumePlanId;
+    const target = buyable.find((plan) => plan.metadata?.id === resumePlanId);
+    const resumedMove = target === undefined ? null : planMove(standing, target, periodEnd);
+    if (resumedMove !== null) {
+      setMove(resumedMove);
+      setAwaitingCard(!hasPaymentMethod);
+    }
+    onResumeHandled?.();
+  }, [resumePlanId, catalog.plans, current.isLoading, buyable, standing, periodEnd, hasPaymentMethod, onResumeHandled]);
+
+  // The card lands on the account by webhook a few seconds after Stripe's
+  // page returns; poll the account until it does, bounded.
+  useEffect(() => {
+    if (!awaitingCard) return;
+    if (hasPaymentMethod) {
+      setAwaitingCard(false);
+      return;
+    }
+    const started = Date.now();
+    const timer = setInterval(() => {
+      if (Date.now() - started > CARD_WAIT_MS) {
+        setAwaitingCard(false);
+        clearInterval(timer);
+        return;
+      }
+      onRefreshAccount?.();
+    }, CARD_POLL_MS);
+    return () => clearInterval(timer);
+  }, [awaitingCard, hasPaymentMethod, onRefreshAccount]);
+
+  const close = useCallback(() => {
+    setMove(null);
+    setAwaitingCard(false);
+    changer.clearError();
+    canceler.clearError();
+    setup.clearError();
+  }, [changer.clearError, canceler.clearError, setup.clearError]);
+
+  const refreshAll = useCallback(() => {
+    current.refetch();
+    estimate.refetch();
+  }, [current.refetch, estimate.refetch]);
+
+  const confirm = useCallback(() => {
+    if (move === null) return;
+    const done = move.kind === "cancel" ? canceler.cancel(orgId) : changer.changePlan(orgId, move.to.metadata?.id ?? "");
+    done.then(
+      () => {
+        setMove(null);
+        refreshAll();
+      },
+      () => undefined,
+    );
+  }, [move, orgId, canceler.cancel, changer.changePlan, refreshAll]);
+
+  const addPaymentMethod = useCallback(() => {
+    const planId = move !== null && move.kind !== "cancel" ? move.to.metadata?.id : undefined;
+    setup.addPaymentMethod(orgId, planId).catch(() => undefined);
+  }, [move, orgId, setup.addPaymentMethod]);
+
+  if (!available) {
+    return null;
+  }
+
+  if (current.isLoading || catalog.isLoading) {
+    return (
+      <div className={cn("stg:space-y-3", className)} aria-busy="true" aria-label="Loading plan">
+        <div className="stg:h-24 stg:animate-pulse stg:rounded-lg stg:bg-muted-subtle" />
+      </div>
+    );
+  }
+
+  const readError = current.error ?? catalog.error;
+  if (readError) {
+    return (
+      <p className={cn("stg:text-xs stg:text-destructive", className)} role="alert">
+        {getUserMessage(readError)}
+      </p>
+    );
+  }
+
+  const nameInForce = livePlanId === "" ? "Free" : planName(livePlanId);
+  const moveError = move?.kind === "cancel" ? canceler.error : (changer.error ?? setup.error);
+  const losing = move?.kind === "switch" ? featuresLost(planById(move.fromPlanId), move.to) : [];
+
+  return (
+    <section className={cn("stg:space-y-3", className)} aria-label="Plan">
+      <PlanCard
+        planName={nameInForce}
+        standing={standing}
+        estimate={estimate.estimate}
+        estimateError={estimate.error}
+        managed={managed}
+      />
+      {!managed && (
+        <PlanPicker
+          plans={buyable}
+          standing={standing}
+          periodEnd={periodEnd}
+          canManage={canManage}
+          onChoose={setMove}
+          disabled={changer.isSubmitting || canceler.isSubmitting}
+        />
+      )}
+      <ChangePlanDialog
+        move={move}
+        planName={planName}
+        losing={losing}
+        hasPaymentMethod={hasPaymentMethod}
+        awaitingPaymentMethod={awaitingCard}
+        isSubmitting={changer.isSubmitting || canceler.isSubmitting || setup.isSubmitting}
+        error={moveError}
+        onConfirm={confirm}
+        onAddPaymentMethod={addPaymentMethod}
+        onClose={close}
+      />
+    </section>
+  );
+}

package/src/billing/UpgradeNotice.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { getErrorReason, getUserMessage } from "@stigmer/sdk";
+import { Feature } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import { FEATURE_COPY, isNamedFeature } from "../internal/features.js";
+
+/**
+ * The reason Stigmer Cloud refuses an act the organization's plan does not
+ * include (iam/team/v1 and tenancy/organization/v1 command.proto).
+ */
+export const PLAN_UPGRADE_REQUIRED = "PLAN_UPGRADE_REQUIRED";
+
+/** The billing page the notice links to by default: the settings route every client serves. */
+export const DEFAULT_BILLING_HREF = "/settings/billing";
+
+/** The wire names the refusal's `feature` metadata carries. */
+const FEATURE_BY_WIRE_NAME: Readonly<Record<string, Feature>> = {
+  teams: Feature.teams,
+  managed_organizations: Feature.managed_organizations,
+};
+
+/**
+ * The feature a refusal says the organization's plan lacks, when `error`
+ * is Stigmer Cloud's `PLAN_UPGRADE_REQUIRED`; `null` for any other error.
+ */
+export function planUpgradeFeature(error: unknown): Feature | null {
+  const reason = getErrorReason(error);
+  if (reason?.reason !== PLAN_UPGRADE_REQUIRED) {
+    return null;
+  }
+  return FEATURE_BY_WIRE_NAME[reason.metadata.feature ?? ""] ?? null;
+}
+
+/** Props for {@link UpgradeNotice}. */
+export interface UpgradeNoticeProps {
+  /** The feature the organization's plan lacks. */
+  readonly feature: Feature;
+  /**
+   * The refusal, when there was one: its message is the server's own
+   * copy, which names the plan that unlocks the act. Absent, the notice is
+   * shown ahead of an attempt.
+   */
+  readonly error?: Error | null;
+  /**
+   * The plan that unlocks the feature, named ahead of an attempt, e.g. the
+   * cheapest one that includes it (`lowestPlanWith`). With a refusal,
+   * the server's copy names it instead.
+   */
+  readonly unlockingPlanName?: string;
+  /** Where the plans are, in the host's routing. Defaults to {@link DEFAULT_BILLING_HREF}. */
+  readonly billingHref?: string;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Says an act needs a plan that includes it, and where to change the plan,
+ * in place of a bare refusal. Everything the organization already has keeps
+ * working; only creating more is refused.
+ *
+ * @example
+ * ```tsx
+ * const feature = planUpgradeFeature(error);
+ * if (feature !== null) return <UpgradeNotice feature={feature} error={error} />;
+ * ```
+ */
+export function UpgradeNotice({
+  feature,
+  error,
+  unlockingPlanName,
+  billingHref = DEFAULT_BILLING_HREF,
+  className,
+}: UpgradeNoticeProps) {
+  const label = isNamedFeature(feature) ? FEATURE_COPY[feature].label : "This feature";
+  const ahead =
+    unlockingPlanName === undefined || unlockingPlanName === ""
+      ? `${label} are not included in this organization's plan.`
+      : `${label} need the ${unlockingPlanName} plan or above.`;
+  const message = error ? getUserMessage(error) : ahead;
+  return (
+    <div
+      className={cn(
+        "stg:rounded-md stg:border stg:border-border stg:bg-muted-subtle stg:px-3 stg:py-2 stg:text-xs",
+        className,
+      )}
+      role="status"
+    >
+      <p className="stg:text-foreground">{message}</p>
+      <a href={billingHref} className="stg:mt-1 stg:inline-block stg:font-medium stg:text-primary stg:hover:underline">
+        View plans
+      </a>
+    </div>
+  );
+}

package/src/billing/credit-packs.ts

@@ -34,8 +34,11 @@ export const CREDIT_PACKS: readonly CreditPackInfo[] = [
     credits: 5_000,
   },
   {
+    // Named "Scale", not "Team", so it never reads as the Team plan on the
+    // page that sells both; its id stays "team", the wire value every
+    // purchase row and checkout call carries.
     packId: "team",
-    displayName: "Team",
+    displayName: "Scale",
     description: "For production workloads",
     priceCents: 20_000,
     credits: 20_000,

package/src/billing/index.ts

@@ -5,13 +5,21 @@
 
 // Data hooks
 export { useBillingAccount } from "./useBillingAccount.js";
-export type { UseBillingAccountReturn } from "./useBillingAccount.js";
+export type { UseBillingAccountOptions, UseBillingAccountReturn } from "./useBillingAccount.js";
 export { useCreditLedger } from "./useCreditLedger.js";
 export type { UseCreditLedgerReturn, UseCreditLedgerOptions } from "./useCreditLedger.js";
 export { useBillingUsageReport } from "./useBillingUsageReport.js";
 export type { UseBillingUsageReportReturn } from "./useBillingUsageReport.js";
 export { useCustomerModelPricing } from "./useCustomerModelPricing.js";
 export type { UseCustomerModelPricingReturn } from "./useCustomerModelPricing.js";
+export { usePlans } from "./usePlans.js";
+export type { UsePlansOptions, UsePlansReturn } from "./usePlans.js";
+export { useSubscription } from "./useSubscription.js";
+export type { UseSubscriptionReturn } from "./useSubscription.js";
+export { useEntitlements } from "./useEntitlements.js";
+export type { UseEntitlementsOptions, UseEntitlementsReturn } from "./useEntitlements.js";
+export { usePeriodEstimate } from "./usePeriodEstimate.js";
+export type { UsePeriodEstimateOptions, UsePeriodEstimateReturn } from "./usePeriodEstimate.js";
 
 // Behavior hooks
 export { useCreateCheckoutSession } from "./useCreateCheckoutSession.js";
@@ -21,6 +29,13 @@ export type {
 } from "./useCreateCheckoutSession.js";
 export { useCreateBillingPortalSession } from "./useCreateBillingPortalSession.js";
 export type { UseCreateBillingPortalSessionReturn } from "./useCreateBillingPortalSession.js";
+export { useChangePlan, useCancelSubscription } from "./useChangePlan.js";
+export type { UseChangePlanReturn, UseCancelSubscriptionReturn } from "./useChangePlan.js";
+export { useCreatePaymentMethodSetupSession } from "./useCreatePaymentMethodSetupSession.js";
+export type { UseCreatePaymentMethodSetupSessionReturn } from "./useCreatePaymentMethodSetupSession.js";
+export type { BillingRedirect } from "./redirect.js";
+export { planStanding, planMove } from "./plan-state.js";
+export type { PlanStanding, PlanMove } from "./plan-state.js";
 export { useSetAutoRechargeConfig } from "./useSetAutoRechargeConfig.js";
 export type {
   SetAutoRechargeConfigInput,
@@ -42,6 +57,16 @@ export { CreditLedgerTable } from "./CreditLedgerTable.js";
 export type { CreditLedgerTableProps } from "./CreditLedgerTable.js";
 export { LowBalanceBanner } from "./LowBalanceBanner.js";
 export type { LowBalanceBannerProps } from "./LowBalanceBanner.js";
+export { PlanSection } from "./PlanSection.js";
+export type { PlanSectionProps } from "./PlanSection.js";
+export { PlanCard } from "./PlanCard.js";
+export type { PlanCardProps } from "./PlanCard.js";
+export { PlanPicker, ENTERPRISE_CONTACT_URL } from "./PlanPicker.js";
+export type { PlanPickerProps } from "./PlanPicker.js";
+export { ChangePlanDialog, PAYMENT_METHOD_REQUIRED } from "./ChangePlanDialog.js";
+export type { ChangePlanDialogProps } from "./ChangePlanDialog.js";
+export { UpgradeNotice, planUpgradeFeature, PLAN_UPGRADE_REQUIRED, DEFAULT_BILLING_HREF } from "./UpgradeNotice.js";
+export type { UpgradeNoticeProps } from "./UpgradeNotice.js";
 
 // Credit pack catalog and formatting utilities
 export { CREDIT_PACKS, formatPackPrice, formatCreditCount } from "./credit-packs.js";