@stigmer/react 3.39.0 → 3.40.0

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

package/src/billing/useCreateCheckoutSession.ts

@@ -4,12 +4,13 @@ import { useCallback, useState } from "react";
 import type { CreateCreditCheckoutSessionResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
+import { leaveForStripe, type BillingRedirect } from "./redirect.js";
 
 /** 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"). */
+  /** Credit pack to purchase: its id, e.g. "starter", "growth" or "team" (the pack named Scale). */
   readonly packId: string;
   /** URL to redirect to after successful payment. */
   readonly successUrl: string;
@@ -22,9 +23,10 @@ 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.
+   * On success, leaves for the Stripe-hosted checkout page: through the
+   * hook's `redirect.openUrl` when given, else by navigating this window.
+   * The promise resolves with the response before the redirect occurs,
+   * allowing callers to perform cleanup if needed.
    */
   readonly createSession: (
     input: CreateCheckoutSessionInput,
@@ -60,8 +62,11 @@ export interface UseCreateCheckoutSessionReturn {
  * };
  * ```
  */
-export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
+export function useCreateCheckoutSession(
+  redirect?: BillingRedirect,
+): UseCreateCheckoutSessionReturn {
   const stigmer = useStigmer();
+  const openUrl = redirect?.openUrl;
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -83,7 +88,7 @@ export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
         });
 
         if (response.checkoutUrl) {
-          window.location.href = response.checkoutUrl;
+          await leaveForStripe(response.checkoutUrl, { openUrl });
         }
 
         return response;
@@ -94,7 +99,7 @@ export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
         setIsSubmitting(false);
       }
     },
-    [stigmer],
+    [stigmer, openUrl],
   );
 
   return { createSession, isSubmitting, error, clearError };

package/src/billing/useCreatePaymentMethodSetupSession.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { useCallback, useMemo, 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 useCreatePaymentMethodSetupSession}. */
+export interface UseCreatePaymentMethodSetupSessionReturn {
+  /**
+   * Leave for Stripe's hosted page to save a card, with no charge. Stripe
+   * returns to the billing page with `?setup=success` (and `&plan=<id>`
+   * when `planId` names the plan the person was subscribing to, so the
+   * page can reopen that choice), or without a query when they leave.
+   * The saved card becomes the organization's default for every invoice.
+   */
+  readonly addPaymentMethod: (orgId: string, planId?: string) => Promise<void>;
+  /** `true` while the setup 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;
+}
+
+/**
+ * Behaviour hook that saves a payment method through a Stripe-hosted setup
+ * page: the card door every subscription needs before its first period.
+ *
+ * The caller needs `can_manage_billing` on the organization. Pass the
+ * host's {@link BillingRedirect} where the window cannot host Stripe's
+ * page itself.
+ */
+export function useCreatePaymentMethodSetupSession(
+  redirect?: BillingRedirect,
+): UseCreatePaymentMethodSetupSessionReturn {
+  const stigmer = useStigmer();
+  const openUrl = redirect?.openUrl;
+  const returnUrl = redirect?.returnUrl;
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const addPaymentMethod = useCallback(
+    async (orgId: string, planId?: string): Promise<void> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        const billingPage = billingReturnUrl({ returnUrl });
+        const success = new URLSearchParams({ setup: "success" });
+        if (planId !== undefined && planId !== "") {
+          success.set("plan", planId);
+        }
+        const response = await stigmer.billing.createPaymentMethodSetupSession({
+          orgId,
+          successUrl: `${billingPage}?${success.toString()}`,
+          cancelUrl: billingPage,
+        });
+        if (response.setupUrl) {
+          await leaveForStripe(response.setupUrl, { openUrl });
+        }
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.billing, openUrl, returnUrl],
+  );
+  const clearError = useCallback(() => setError(null), []);
+
+  return useMemo(
+    () => ({ addPaymentMethod, isSubmitting, error, clearError }),
+    [addPaymentMethod, isSubmitting, error, clearError],
+  );
+}