@startsimpli/billing 0.4.24 → 0.4.26

package/src/hooks/usePlanChange.ts

@@ -0,0 +1,144 @@
+/**
+ * usePlanChange — choose a plan, confirming first when the click changes or
+ * ends a plan the viewer already has (crochet_patterns-anw61, -kigcj, -lr7mj).
+ *
+ * A new buyer choosing a paid plan goes straight on: the provider's checkout
+ * page is their confirmation. Anyone already paying, or choosing a free plan,
+ * is asked first, with what the backend says will happen (charged now and how
+ * much, or the date it changes, or that an unlisted plan ends for good).
+ *
+ * While a preview or the change itself is in flight `busy` is true, so
+ * callers disable their plan buttons — a second click used to start a second
+ * checkout (crochet_patterns-9e9o).
+ *
+ * `proceed(offer, preview)` does the change (checkout, subscribe-free, …).
+ * Return "navigating" when it has sent the browser away, so the buttons stay
+ * disabled until the page unloads. Throw to show the message.
+ */
+
+import { useCallback, useRef, useState } from "react";
+import type { PlanChangePreview, ProductOffer } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+export type PlanChangeProceed = (
+  offer: ProductOffer,
+  preview: PlanChangePreview | null,
+) => Promise<unknown> | unknown;
+
+export interface PlanChangeContext {
+  /** The viewer pays for a running plan (isPayingSubscription). */
+  paying: boolean;
+  /** The viewer's plan is not one of the offers for sale (a complimentary plan). */
+  leavingUnlisted?: boolean;
+  /** The viewer's plan, for the dialog copy when the preview can't be had. */
+  currentOffer?: ProductOffer | null;
+}
+
+export interface PlanChangeConfirmState {
+  offer: ProductOffer;
+  preview: PlanChangePreview | null;
+  currentName: string | null;
+  leavingUnlisted: boolean;
+}
+
+export interface UsePlanChangeResult {
+  choose: (offer: ProductOffer, context: PlanChangeContext) => Promise<void>;
+  confirm: () => Promise<void>;
+  cancel: () => void;
+  /** Open when the viewer must confirm. */
+  pending: PlanChangeConfirmState | null;
+  busy: boolean;
+  /** The confirm step itself is running. */
+  confirming: boolean;
+  error: string | null;
+  clearError: () => void;
+}
+
+export function usePlanChange(proceed: PlanChangeProceed): UsePlanChangeResult {
+  const { client } = useBillingContext();
+  const [pending, setPending] = useState<PlanChangeConfirmState | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inFlight = useRef(false);
+
+  const run = useCallback(
+    async (offer: ProductOffer, preview: PlanChangePreview | null) => {
+      try {
+        const outcome = await proceed(offer, preview);
+        if (outcome !== "navigating") {
+          inFlight.current = false;
+          setBusy(false);
+        }
+        return true;
+      } catch (e) {
+        inFlight.current = false;
+        setBusy(false);
+        setError(e instanceof Error ? e.message : "Something went wrong. Please try again.");
+        return false;
+      }
+    },
+    [proceed],
+  );
+
+  const choose = useCallback(
+    async (offer: ProductOffer, context: PlanChangeContext) => {
+      if (inFlight.current) return;
+      inFlight.current = true;
+      setBusy(true);
+      setError(null);
+
+      const leavingUnlisted = !!context.leavingUnlisted;
+      // Not paying yet (free, or an unbilled complimentary plan) and choosing a
+      // paid plan: that is a checkout, and its page is the confirmation.
+      if (!context.paying && !offer.isFree) {
+        await run(offer, null);
+        return;
+      }
+
+      let preview: PlanChangePreview | null = null;
+      try {
+        preview = await client.previewPlanChange(offer.id);
+      } catch {
+        preview = null; // still confirm, with the copy we can stand behind
+      }
+      if (preview?.mode === "current") {
+        inFlight.current = false;
+        setBusy(false);
+        return;
+      }
+      if (preview?.mode === "checkout") {
+        await run(offer, preview);
+        return;
+      }
+      setPending({
+        offer,
+        preview,
+        currentName: preview?.currentOffer?.name ?? context.currentOffer?.name ?? null,
+        leavingUnlisted: preview?.currentOffer ? !preview.currentOffer.isListed : leavingUnlisted,
+      });
+    },
+    [client, run],
+  );
+
+  const confirm = useCallback(async () => {
+    if (!pending || confirming) return;
+    setConfirming(true);
+    setError(null);
+    const ok = await run(pending.offer, pending.preview);
+    setConfirming(false);
+    if (ok) setPending(null);
+  }, [pending, confirming, run]);
+
+  const cancel = useCallback(() => {
+    if (confirming) return;
+    setPending(null);
+    setError(null);
+    inFlight.current = false;
+    setBusy(false);
+  }, [confirming]);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { choose, confirm, cancel, pending, busy, confirming, error, clearError };
+}

package/src/hooks/useSuccessSync.ts

@@ -16,7 +16,7 @@ import type { CachedSubscriptionState } from "../types";
 import { useBillingContext } from "./BillingProvider";
 
 interface UseSuccessSyncResult {
-  sync: () => Promise<CachedSubscriptionState | null>;
+  sync: (params?: { sessionId?: string | null; productSlug?: string | null }) => Promise<CachedSubscriptionState | null>;
   data: CachedSubscriptionState | null;
   loading: boolean;
   error: Error | null;
@@ -28,11 +28,11 @@ export function useSuccessSync(): UseSuccessSyncResult {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
-  const sync = useCallback(async () => {
+  const sync = useCallback(async (params?: { sessionId?: string | null; productSlug?: string | null }) => {
     setLoading(true);
     setError(null);
     try {
-      const result = await client.successSync();
+      const result = await client.successSync(params);
       setData(result);
       return result;
     } catch (e) {

package/src/index.ts

@@ -19,10 +19,11 @@ export {
   useSubscription,
   useSuccessSync,
   useUsage,
+  usePlanChange,
   notifyUsageChanged,
   USAGE_CHANGED_EVENT,
 } from "./hooks";
-export type { BillingProviderProps } from "./hooks";
+export type { BillingProviderProps, PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./hooks";
 
 // Types
 export type {
@@ -34,13 +35,14 @@ export type {
   CachedSubscriptionState,
   FreeSubscriptionResult,
   PaymentMethod,
+  PlanChangePreview,
   PortalResult,
   SubscriptionInfo,
   UsageMap,
 } from "./types";
 
 // Components
-export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge } from "./components";
+export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge, PlanChangeConfirm, planChangeCopy } from "./components";
 export type {
   PricingPageProps,
   PricingSectionProps,
@@ -51,14 +53,28 @@ export type {
   PlanGateProps,
   CurrentPlanCardProps,
   LimitNudgeProps,
+  PlanChangeConfirmProps,
 } from "./components";
 
 // API client (for advanced usage)
 export { BillingApiClient } from "./utils/api";
 
 // Pure helpers
-export { isPaidSubscription, getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow, resolveCurrentOfferId } from "./utils/plan";
-export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow, CurrentPlanState } from "./utils/plan";
+export {
+  isPaidSubscription,
+  isPayingSubscription,
+  isUnlistedOffer,
+  getFeatureLimit,
+  resolvePlanEntitlement,
+  resolveUsageWindow,
+  resolveCurrentOfferId,
+  resolveCurrentOffer,
+  planDirection,
+  planCtaLabel,
+  trialApplies,
+  TRIAL_NOTE_FEATURE_KEY,
+} from "./utils/plan";
+export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow, CurrentPlanState, PlanDirection } from "./utils/plan";
 export { formatPrice, formatFeatureLabel } from "./utils/format";
 export { groupOffersByTier, offersForInterval, hasIntervalChoice, annualSavings, tierOffer } from "./utils/tiers";
 export type { BillingInterval, OfferTier } from "./utils/tiers";

package/src/types/index.ts

@@ -52,14 +52,43 @@ export interface BillingProduct {
   offers: ProductOffer[];
 }
 
+/**
+ * What choosing an offer will do, from POST /billing/plan-change-preview/
+ * (crochet_patterns-anw61):
+ * - "current"       already on it
+ * - "immediate"     changes now; a paid offer is charged `amountDue` now
+ *                   (null when it could not be priced) and never trials;
+ *                   a free offer ends an unbilled plan now
+ * - "at_period_end" changes on `effectiveAt`; nothing is charged now
+ * - "checkout"      a new checkout, with `trialDays`
+ */
+export interface PlanChangePreview {
+  mode: "current" | "immediate" | "at_period_end" | "checkout";
+  offerId: string;
+  amountDue: string | null;
+  currency: string;
+  effectiveAt: string | null;
+  trialDays: number;
+  /** The plan being left; `isListed` false = not for sale, cannot be chosen again. */
+  currentOffer: { slug: string; name: string; isListed: boolean } | null;
+}
+
 export interface CheckoutResult {
   sessionId: string;
   url: string;
+  /** Set when the offer was a change to a plan already paid for (no checkout):
+   * "immediate", "at_period_end", "payment_required", "pending_change_cancelled".
+   * The backend sends it as `plan_change`. */
+  plan_change?: string;
+  planChange?: string;
 }
 
 export interface FreeSubscriptionResult {
   subscriptionId: string;
   status: string;
+  /** Leaving a paid plan: it ends at `effective_at` instead of now. */
+  scheduled_downgrade?: boolean;
+  effective_at?: string | null;
 }
 
 export interface PortalResult {

package/src/utils/api.ts

@@ -8,6 +8,7 @@ import type {
   CachedSubscriptionState,
   CheckoutResult,
   FreeSubscriptionResult,
+  PlanChangePreview,
   PortalResult,
   SubscriptionInfo,
   UsageMap,
@@ -104,11 +105,47 @@ export class BillingApiClient {
    * Eagerly sync subscription state after Stripe checkout redirect.
    * Call this from your success_url page to avoid waiting for the webhook.
    */
-  async successSync(): Promise<CachedSubscriptionState | null> {
+  /** What choosing an offer will do, without doing it (crochet_patterns-anw61). */
+  async previewPlanChange(offerId: string): Promise<PlanChangePreview> {
+    const url = `${this.config.apiBaseUrl}/billing/plan-change-preview/`;
+    const resp = await this.fetcher(url, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ offer_id: offerId }),
+    });
+    if (!resp.ok) {
+      const data = await resp.json().catch(() => ({}));
+      throw new Error(billingErrorMessage(data, `Plan preview failed: ${resp.status}`));
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const raw: any = await resp.json();
+    const cur = raw.current_offer ?? raw.currentOffer ?? null;
+    return {
+      mode: raw.mode,
+      offerId: raw.offer_id ?? raw.offerId ?? offerId,
+      amountDue: raw.amount_due ?? raw.amountDue ?? null,
+      currency: raw.currency ?? "usd",
+      effectiveAt: raw.effective_at ?? raw.effectiveAt ?? null,
+      trialDays: raw.trial_days ?? raw.trialDays ?? 0,
+      currentOffer: cur
+        ? { slug: cur.slug, name: cur.name, isListed: (cur.is_listed ?? cur.isListed) !== false }
+        : null,
+    };
+  }
+
+  /** `sessionId` is the checkout session from the success URL
+   * ({CHECKOUT_SESSION_ID}): it sends the sync straight to the checkout that
+   * was paid, not to whichever customer the team resolves to first
+   * (crochet_patterns-eq11). */
+  async successSync(params: { sessionId?: string | null; productSlug?: string | null } = {}): Promise<CachedSubscriptionState | null> {
     const url = `${this.config.apiBaseUrl}/billing/success-sync/`;
+    const body: Record<string, string> = {};
+    if (params.sessionId) body.session_id = params.sessionId;
+    if (params.productSlug) body.product_slug = params.productSlug;
     const resp = await this.fetcher(url, {
       method: "POST",
       headers: this.headers,
+      ...(Object.keys(body).length > 0 && { body: JSON.stringify(body) }),
     });
     if (resp.status === 404) {
       return null;

package/src/utils/plan.ts

@@ -213,6 +213,8 @@ export interface CurrentPlanState {
   loading?: boolean;
   /** The subscription fetch failed. */
   error?: unknown;
+  /** Fetch the subscription again (offered when it failed). */
+  retry?: () => void;
 }
 
 /**
@@ -239,3 +241,87 @@ export function resolveCurrentOfferId(
   }
   return offers.find((o) => o.isFree)?.id ?? null;
 }
+
+/**
+ * The plan to treat as the viewer's own on a picker: their subscription's
+ * offer while it counts (see resolveCurrentOfferId), else the free offer for a
+ * signed-in viewer. The offer may be one the picker does not list (a hidden
+ * complimentary plan); `isUnlistedOffer` says so. Null while unknown.
+ */
+export function resolveCurrentOffer(
+  offers: ProductOffer[],
+  state: CurrentPlanState | null | undefined,
+): ProductOffer | null {
+  const id = resolveCurrentOfferId(offers, state);
+  if (!id) return null;
+  const own = state?.subscription?.offer ?? null;
+  if (own && own.id === id) return own;
+  return offers.find((o) => o.id === id) ?? null;
+}
+
+/** True when `offer` is not one of the offers for sale (e.g. a complimentary plan). */
+export function isUnlistedOffer(offers: ProductOffer[], offer: ProductOffer | null | undefined): boolean {
+  return !!offer && !offers.some((o) => o.id === offer.id);
+}
+
+/**
+ * True while the viewer pays for a plan that is still running (active,
+ * trialing or past due). Choosing another paid plan then changes that
+ * subscription in place — an upgrade is charged now, prorated, and never
+ * starts a trial — so pickers must not sell it as one (crochet_patterns-anw61).
+ */
+export function isPayingSubscription(sub: SubscriptionInfo | null | undefined): boolean {
+  if (!sub?.offer || sub.offer.isFree) return false;
+  return PAID_STATUSES.includes(sub.status) || sub.status === "past_due";
+}
+
+/**
+ * A card's direction relative to the viewer's plan:
+ * - "current"   their exact offer
+ * - "switch"    the same plan on the other billing interval (Lite ↔ Lite Annual)
+ * - "upgrade"   paid over free, or a higher sortOrder
+ * - "downgrade" free under paid, or a lower sortOrder
+ * Unknown plan (null) → every card is an upgrade.
+ */
+export type PlanDirection = "current" | "upgrade" | "downgrade" | "switch";
+
+export function planDirection(
+  card: ProductOffer,
+  current: ProductOffer | null | undefined,
+  tierKeyOf: (offerId: string) => string | null = () => null,
+): PlanDirection {
+  if (!current) return "upgrade";
+  if (card.id === current.id) return "current";
+  const tierKey = tierKeyOf(card.id);
+  if (tierKey !== null && tierKey === tierKeyOf(current.id)) return "switch";
+  if (card.isFree && !current.isFree) return "downgrade";
+  if (!card.isFree && current.isFree) return "upgrade";
+  return card.sortOrder > current.sortOrder ? "upgrade" : "downgrade";
+}
+
+/**
+ * Whether the offer's free trial applies to this viewer: only an upgrade by
+ * someone not already paying goes through a checkout that starts one.
+ */
+export function trialApplies(card: ProductOffer, direction: PlanDirection, paying: boolean): boolean {
+  return direction === "upgrade" && !paying && (card.trialDays ?? 0) > 0;
+}
+
+/**
+ * The CTA for a card. `offer.ctaText` ("Start Free Trial") is the pitch to a
+ * new buyer; someone already paying is upgraded in place, so they get
+ * "Upgrade to X" (startsim-21f, crochet_patterns-anw61).
+ */
+export function planCtaLabel(card: ProductOffer, direction: PlanDirection, paying = false): string {
+  if (direction === "current") return "Current plan";
+  if (direction === "switch") return card.intervalUnit === "year" ? "Switch to annual" : "Switch to monthly";
+  if (direction === "downgrade") return `Downgrade to ${card.name}`;
+  if (paying) return `Upgrade to ${card.name}`;
+  return card.ctaText || `Upgrade to ${card.name}`;
+}
+
+/**
+ * A feature row that only describes the trial (key `trial_note`, e.g. "7-day
+ * free trial with AI designs included") is not true when the trial does not apply.
+ */
+export const TRIAL_NOTE_FEATURE_KEY = "trial_note";