@stigmer/react 3.39.1-dev.20260928194002 → 3.40.1

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";

package/src/billing/plan-features.ts

@@ -0,0 +1,162 @@
+// What a plan offers, as the console shows it: which plans are offered and
+// in what order, what each includes, and the formatting of its terms and
+// periods.
+//
+// A plan's features render from its entitlements through the shared
+// vocabulary (../internal/features.ts), never from the plan's stored
+// description: a plan row is immutable once seeded, and the description is
+// free text that can promise a feature before it is built. The console
+// shows only what an organization can use today.
+
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import { PlanInstrument, type PlanTerms } from "@stigmer/protos/ai/stigmer/billing/plan/v1/spec_pb";
+import { PlanLifecycle } from "@stigmer/protos/ai/stigmer/billing/plan/v1/status_pb";
+import { Feature, type Entitlements } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import { FEATURE_COPY, isNamedFeature, type NamedFeature } from "../internal/features.js";
+import { formatCreditBalance } from "./format.js";
+
+// BigInt(0), not a literal: the docs site compiles this source for a
+// target below ES2020, which has no BigInt literal syntax.
+const ZERO = BigInt(0);
+
+/**
+ * Features a plan may list ahead of the gate that serves them, which
+ * Stigmer Cloud does not offer yet. The console leaves them out of every
+ * comparison. Bring-your-own provider keys leaves this set when the proxy
+ * uses an organization's own key.
+ */
+export const NOT_YET_OFFERED: ReadonlySet<Feature> = new Set([Feature.byo_provider_keys]);
+
+/** One feature a plan offers today, with its words. */
+export interface OfferedFeature {
+  readonly feature: NamedFeature;
+  readonly label: string;
+  readonly description: string;
+}
+
+/** The features `entitlements` grant that Cloud offers today, in contract order. */
+export function offeredFeatures(entitlements: Entitlements | undefined): readonly OfferedFeature[] {
+  const listed = entitlements?.features ?? [];
+  return [...new Set(listed)]
+    .filter((feature): feature is NamedFeature => isNamedFeature(feature) && !NOT_YET_OFFERED.has(feature))
+    .sort((a, b) => a - b)
+    .map((feature) => ({ feature, ...FEATURE_COPY[feature] }));
+}
+
+/**
+ * The plans an organization can subscribe to, cheapest monthly minimum
+ * first, so a comparison reads upward from Free; equal minimums keep the
+ * catalog's order. Retired rows and prepaid instruments are left out.
+ */
+export function buyablePlans(plans: readonly Plan[]): readonly Plan[] {
+  return plans
+    .filter(
+      (plan) =>
+        plan.spec?.instrument === PlanInstrument.subscription && plan.status?.lifecycle === PlanLifecycle.active,
+    )
+    .map((plan, index) => ({ plan, index }))
+    .sort((a, b) => compareMinimums(a.plan, b.plan) || a.index - b.index)
+    .map(({ plan }) => plan);
+}
+
+/** The cheapest plan that can be bought and includes `feature`, if any. */
+export function lowestPlanWith(plans: readonly Plan[], feature: Feature): Plan | undefined {
+  return buyablePlans(plans).find((plan) =>
+    offeredFeatures(plan.spec?.entitlements).some((offered) => offered.feature === feature),
+  );
+}
+
+/** What `from` offers that `to` does not: what a switch stops the organization creating. */
+export function featuresLost(from: Plan | undefined, to: Plan): readonly OfferedFeature[] {
+  const kept = new Set(offeredFeatures(to.spec?.entitlements).map((offered) => offered.feature));
+  return offeredFeatures(from?.spec?.entitlements).filter((offered) => !kept.has(offered.feature));
+}
+
+function compareMinimums(a: Plan, b: Plan): number {
+  const left = a.spec?.terms?.monthlyMinimumMicros ?? ZERO;
+  const right = b.spec?.terms?.monthlyMinimumMicros ?? ZERO;
+  return left === right ? 0 : left < right ? -1 : 1;
+}
+
+/** A plan's monthly minimum, e.g. "$99.00/month". */
+export function formatMonthlyMinimum(terms: PlanTerms | undefined): string {
+  return `${formatCreditBalance(terms?.monthlyMinimumMicros ?? ZERO)}/month`;
+}
+
+/**
+ * A plan's usage share as its terms state it, for operators who read terms,
+ * e.g. "or 10% of provider cost, whichever is greater; the commission
+ * already paid on tokens counts toward it". Empty when the plan has no
+ * usage share.
+ */
+export function formatUsageShare(terms: PlanTerms | undefined): string {
+  const percent = sharePercent(terms);
+  return percent === ""
+    ? ""
+    : `or ${percent} of provider cost, whichever is greater; the commission already paid on tokens counts toward it`;
+}
+
+/**
+ * The same share as a customer reads it: usage stays paid from credits,
+ * and the commission on it counts toward the minimum up to the spend at
+ * which the plan costs nothing extra, e.g. "Usage is still paid from
+ * credits. The 10% commission on it counts toward the minimum, so from
+ * $990.00 a month in provider costs the plan costs nothing extra." Empty
+ * when the plan has no usage share.
+ */
+export function explainUsageShare(terms: PlanTerms | undefined): string {
+  const percent = sharePercent(terms);
+  if (percent === "") {
+    return "";
+  }
+  const basisPoints = BigInt(terms?.usageShareBasisPoints ?? 0);
+  // The provider cost whose share equals the minimum: past it, the share is the plan's cost and the commission pays it.
+  const breakEven = ((terms?.monthlyMinimumMicros ?? ZERO) * BigInt(10_000)) / basisPoints;
+  return (
+    `Usage is still paid from credits. The ${percent} commission on it counts toward the minimum, ` +
+    `so from ${formatCreditBalance(breakEven)} a month in provider costs the plan costs nothing extra.`
+  );
+}
+
+/** The usage share as a percentage, e.g. "10%" or "12.50%"; empty when there is none. */
+export function sharePercent(terms: PlanTerms | undefined): string {
+  const basisPoints = terms?.usageShareBasisPoints ?? 0;
+  if (basisPoints === 0) {
+    return "";
+  }
+  return `${basisPoints % 100 === 0 ? `${basisPoints / 100}` : (basisPoints / 100).toFixed(2)}%`;
+}
+
+/** The managed organizations a plan includes and what each beyond costs, or empty. */
+export function formatManagedOrganizations(
+  entitlements: Entitlements | undefined,
+  terms: PlanTerms | undefined,
+): string {
+  if (!(entitlements?.features ?? []).includes(Feature.managed_organizations)) {
+    return "";
+  }
+  const included = entitlements?.limits?.includedManagedOrganizations;
+  const fee = terms?.perExtraOrganizationMicros ?? ZERO;
+  if (included === undefined) {
+    return "Unlimited managed organizations";
+  }
+  const beyond = fee > ZERO ? `, then ${formatCreditBalance(fee)}/month each` : "";
+  return `${included} managed organization${included === 1 ? "" : "s"} included${beyond}`;
+}
+
+const DAY = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" });
+
+/**
+ * A period boundary as a UTC calendar day, e.g. "Feb 28, 2027". Periods
+ * run anniversary to anniversary in UTC, the rule the invoice follows.
+ */
+export function formatPeriodDay(timestamp: Timestamp | undefined): string {
+  return timestamp === undefined ? "" : formatDay(timestampDate(timestamp));
+}
+
+/** An instant as its UTC calendar day, the way {@link formatPeriodDay} shows a period boundary. */
+export function formatDay(date: Date): string {
+  return DAY.format(date);
+}

package/src/billing/plan-state.ts

@@ -0,0 +1,92 @@
+// Where an organization stands on its plan, and what choosing a plan
+// would do, decided the way the server decides it (the subscription
+// engine's moves), so the confirm step states the move the server makes.
+//
+//   subscribe  no live plan: a monthly period opens now on the plan
+//   switch     a live plan, another chosen: this period closes early,
+//              billed for the time it ran, and a new one opens now
+//   resume     the plan being canceled, chosen again: the cancel is
+//              withdrawn and the period runs on
+//   cancel     Free chosen on a live plan: the plan runs to its period's
+//              end, then the organization is on Free
+//
+// Choosing the plan already in force, or Free while on Free or already
+// canceling, is no move at all.
+
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import type { Subscription } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/api_pb";
+import { SubscriptionState } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/status_pb";
+
+/** An organization's standing on its plan. */
+export type PlanStanding =
+  | { readonly kind: "free" }
+  | { readonly kind: "active"; readonly planId: string }
+  | { readonly kind: "past-due"; readonly planId: string }
+  | { readonly kind: "ending"; readonly planId: string; readonly endsAt: Date };
+
+/** What choosing a plan (or Free) would do. */
+export type PlanMove =
+  | { readonly kind: "subscribe"; readonly to: Plan }
+  | { readonly kind: "switch"; readonly fromPlanId: string; readonly to: Plan }
+  | { readonly kind: "resume"; readonly to: Plan }
+  | { readonly kind: "cancel"; readonly fromPlanId: string; readonly endsAt: Date };
+
+/**
+ * The standing a stored subscription gives at `now`: the engine's live
+ * rule (active, past due, or canceled but not yet at its period's end),
+ * else Free. `null` (never subscribed) is Free.
+ */
+export function planStanding(subscription: Subscription | null, now: Date): PlanStanding {
+  const status = subscription?.status;
+  const planId = subscription?.spec?.planId ?? "";
+  switch (status?.state) {
+    case SubscriptionState.active:
+      return { kind: "active", planId };
+    case SubscriptionState.past_due:
+      return { kind: "past-due", planId };
+    case SubscriptionState.canceled: {
+      const end = status.currentPeriodEnd === undefined ? undefined : timestampDate(status.currentPeriodEnd);
+      return end !== undefined && now.getTime() < end.getTime()
+        ? { kind: "ending", planId, endsAt: end }
+        : { kind: "free" };
+    }
+    default:
+      return { kind: "free" };
+  }
+}
+
+/** The move choosing `target` (a plan, or `"free"`) makes from `standing`, or `null` for none. */
+export function planMove(
+  standing: PlanStanding,
+  target: Plan | "free",
+  periodEnd: Date | undefined,
+): PlanMove | null {
+  if (target === "free") {
+    if (standing.kind === "active" || standing.kind === "past-due") {
+      return periodEnd === undefined ? null : { kind: "cancel", fromPlanId: standing.planId, endsAt: periodEnd };
+    }
+    return null;
+  }
+  const targetId = target.metadata?.id ?? "";
+  switch (standing.kind) {
+    case "free":
+      return { kind: "subscribe", to: target };
+    case "ending":
+      return targetId === standing.planId
+        ? { kind: "resume", to: target }
+        : { kind: "switch", fromPlanId: standing.planId, to: target };
+    case "active":
+    case "past-due":
+      return targetId === standing.planId ? null : { kind: "switch", fromPlanId: standing.planId, to: target };
+    default: {
+      const exhaustive: never = standing;
+      throw new Error(`unknown plan standing ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+/** The plan id in force for `standing`, or empty on Free. */
+export function standingPlanId(standing: PlanStanding): string {
+  return standing.kind === "free" ? "" : standing.planId;
+}

package/src/billing/redirect.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a billing flow leaves the app for a Stripe-hosted page, and where
+ * Stripe sends the person back.
+ *
+ * By default the console navigates its own window to Stripe and Stripe
+ * returns to the host's billing page on the same origin: right for a web
+ * console. A host whose window cannot host a third-party page, such as a
+ * desktop webview whose origin is not a web address Stripe can return to,
+ * passes a {@link BillingRedirect}: `openUrl` opens the page elsewhere
+ * (the system browser), and `returnUrl` names a real web page for Stripe
+ * to return to. The person finishes there; the host's reads refresh when
+ * its window regains focus, because the state lives on the server.
+ */
+
+/** The host's seam for leaving the app to a Stripe-hosted page. */
+export interface BillingRedirect {
+  /**
+   * Opens a Stripe-hosted page. Absent, the current window navigates to
+   * it. Desktop hosts open the system browser.
+   */
+  readonly openUrl?: (url: string) => void | Promise<void>;
+  /**
+   * The absolute URL of the billing page Stripe returns to, without a
+   * query. Absent, the current origin's `/settings/billing`.
+   */
+  readonly returnUrl?: string;
+}
+
+/** The billing page Stripe returns to, per the redirect or the current origin. */
+export function billingReturnUrl(redirect: BillingRedirect | undefined): string {
+  if (redirect?.returnUrl !== undefined) {
+    return redirect.returnUrl;
+  }
+  const origin = typeof window === "undefined" ? "" : window.location.origin;
+  return `${origin}/settings/billing`;
+}
+
+/** Leaves for a Stripe-hosted page through the redirect, or by navigating this window. */
+export async function leaveForStripe(url: string, redirect: BillingRedirect | undefined): Promise<void> {
+  if (redirect?.openUrl !== undefined) {
+    await redirect.openUrl(url);
+    return;
+  }
+  window.location.href = url;
+}

package/src/billing/useBillingAccount.ts

@@ -8,6 +8,16 @@ import type { BillingAccount } from "@stigmer/protos/ai/stigmer/billing/v1/billi
 import { useStigmer } from "../hooks.js";
 import { useFetch } from "../internal/useFetch.js";
 
+/** Options for {@link useBillingAccount}. */
+export interface UseBillingAccountOptions {
+  /**
+   * Re-read the account when the window regains focus: for a host that
+   * sends Stripe's pages to another window (the system browser), so a card
+   * saved there shows on return. Default `false`.
+   */
+  readonly refetchOnWindowFocus?: boolean;
+}
+
 /** Return value of {@link useBillingAccount}. */
 export interface UseBillingAccountReturn {
   /** The billing account, or `null` before the first successful fetch. */
@@ -48,6 +58,7 @@ export interface UseBillingAccountReturn {
  */
 export function useBillingAccount(
   orgId: string | null,
+  options?: UseBillingAccountOptions,
 ): UseBillingAccountReturn {
   const stigmer = useStigmer();
 
@@ -58,6 +69,7 @@ export function useBillingAccount(
       : null,
     [orgId, stigmer],
     null as BillingAccount | null,
+    { refetchOnWindowFocus: options?.refetchOnWindowFocus ?? false },
   );
 
   return { account, isLoading, isRefetching, error, refetch };

package/src/billing/useChangePlan.ts

@@ -0,0 +1,115 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Subscription } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/api_pb";
+import {
+  CancelSubscriptionInputSchema,
+  ChangePlanInputSchema,
+} from "@stigmer/protos/ai/stigmer/billing/subscription/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useChangePlan}. */
+export interface UseChangePlanReturn {
+  /**
+   * Move the organization onto a plan: subscribe (from Free), switch, or
+   * resume a canceled plan by choosing it again. A switch takes effect
+   * now: the current period closes early, billed for the time it ran, and
+   * a new monthly period opens on the new plan. Nothing is charged at the
+   * moment of the change; every period is collected when it closes.
+   *
+   * Refused with the `PAYMENT_METHOD_REQUIRED` reason when the
+   * organization has no saved card (see
+   * {@link useCreatePaymentMethodSetupSession}). Resolves with the
+   * subscription as it stands after the change.
+   */
+  readonly changePlan: (orgId: string, planId: string) => Promise<Subscription>;
+  /** `true` while a change is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behaviour hook that moves an organization onto a plan.
+ *
+ * The caller needs `can_manage_billing` on the organization (its admins).
+ * Refetch the subscription, entitlements and estimate after a change.
+ */
+export function useChangePlan(): UseChangePlanReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const changePlan = useCallback(
+    async (orgId: string, planId: string): Promise<Subscription> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        return await stigmer.subscription.changePlan(create(ChangePlanInputSchema, { orgId, planId }));
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.subscription],
+  );
+  const clearError = useCallback(() => setError(null), []);
+
+  return useMemo(
+    () => ({ changePlan, isSubmitting, error, clearError }),
+    [changePlan, isSubmitting, error, clearError],
+  );
+}
+
+/** Return value of {@link useCancelSubscription}. */
+export interface UseCancelSubscriptionReturn {
+  /**
+   * Cancel the organization's subscription. It keeps its plan to the end
+   * of the current period and is on Free after it; nothing it built is
+   * deleted. Choosing the same plan again before then resumes it.
+   */
+  readonly cancel: (orgId: string) => Promise<Subscription>;
+  /** `true` while a cancel is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behaviour hook that cancels an organization's subscription at the end
+ * of its period. The caller needs `can_manage_billing` on the organization.
+ */
+export function useCancelSubscription(): UseCancelSubscriptionReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const cancel = useCallback(
+    async (orgId: string): Promise<Subscription> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        return await stigmer.subscription.cancel(create(CancelSubscriptionInputSchema, { orgId }));
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.subscription],
+  );
+  const clearError = useCallback(() => setError(null), []);
+
+  return useMemo(() => ({ cancel, isSubmitting, error, clearError }), [cancel, isSubmitting, error, clearError]);
+}

package/src/billing/useCreateBillingPortalSession.ts

@@ -3,14 +3,17 @@
 import { useCallback, useState } from "react";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
+import { billingReturnUrl, leaveForStripe, type BillingRedirect } from "./redirect.js";
 
 /** 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.
+   * On success, leaves for the Stripe-hosted portal page: through
+   * `redirect.openUrl` when given, else by navigating this window. The
+   * portal returns to `redirect.returnUrl` when given, else to the page
+   * the person is on.
    */
   readonly openPortal: (orgId: string) => Promise<void>;
   /** `true` while the portal session is being created. */
@@ -38,8 +41,12 @@ export interface UseCreateBillingPortalSessionReturn {
  * </button>
  * ```
  */
-export function useCreateBillingPortalSession(): UseCreateBillingPortalSessionReturn {
+export function useCreateBillingPortalSession(
+  redirect?: BillingRedirect,
+): UseCreateBillingPortalSessionReturn {
   const stigmer = useStigmer();
+  const openUrl = redirect?.openUrl;
+  const pinnedReturnUrl = redirect?.returnUrl;
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -52,7 +59,11 @@ export function useCreateBillingPortalSession(): UseCreateBillingPortalSessionRe
 
       try {
         const returnUrl =
-          typeof window !== "undefined" ? window.location.href : "";
+          pinnedReturnUrl !== undefined
+            ? billingReturnUrl({ returnUrl: pinnedReturnUrl })
+            : typeof window !== "undefined"
+              ? window.location.href
+              : "";
 
         const response = await stigmer.billing.createBillingPortalSession({
           orgId,
@@ -60,7 +71,7 @@ export function useCreateBillingPortalSession(): UseCreateBillingPortalSessionRe
         });
 
         if (response.portalUrl) {
-          window.location.href = response.portalUrl;
+          await leaveForStripe(response.portalUrl, { openUrl });
         }
       } catch (err) {
         setError(toError(err));
@@ -69,7 +80,7 @@ export function useCreateBillingPortalSession(): UseCreateBillingPortalSessionRe
         setIsLoading(false);
       }
     },
-    [stigmer],
+    [stigmer, openUrl, pinnedReturnUrl],
   );
 
   return { openPortal, isLoading, error, clearError };