@djangocfg/payments 2.1.561 → 2.1.563

package/src/components/UpdateCardDialog.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — UpdateCardDialog
+// ============================================================================
+// The whole add-a-card flow in one mountable surface: create the SetupIntent
+// on open → render the provider's field against its clientSecret → confirm →
+// report. ui-core + package internals only; the Stripe field arrives from the
+// host through `renderPaymentField`, so this file imports no SDK.
+//
+// THE INTENT IS CREATED ON OPEN, NOT ON SUBMIT. CheckoutForm can create its
+// intent lazily because it owns a mock-friendly text field. <Elements> cannot:
+// it needs the clientSecret BEFORE it mounts, and remounting it after a submit
+// would wipe whatever the customer typed. So opening the dialog starts the
+// intent, and closing it resets the machine — an abandoned SetupIntent costs
+// nothing and expires on its own.
+
+import React, { useCallback, useEffect } from 'react';
+import { Alert, AlertDescription, Button, Spinner } from '@djangocfg/ui-core';
+import { AlertTriangle } from 'lucide-react';
+import { CheckoutDialog } from './CheckoutDialog';
+import { CardSetupForm } from './CardSetupForm';
+import { useCardSetup } from '../hooks/useCardSetup';
+import type { SaveCardInput } from '../domain/types';
+
+export interface UpdateCardDialogProps {
+  open: boolean;
+  /** Called on any allowed close path. The machine resets itself. */
+  onClose: () => void;
+  /** Attach the saved card to this subscription's default. */
+  subscriptionId?: string;
+  /**
+   * Render the whole card step against the live clientSecret. The host mounts
+   * the provider's field (typically <StripePaymentElement>) and calls
+   * `renderForm` from inside its render prop, handing back the live elements
+   * context — which is what keeps this file free of @stripe/*.
+   *
+   * The two arrive TOGETHER on purpose: the elements context only exists
+   * inside <Elements>, so a callback that reported it upward would have to
+   * write state during the host's render. Passing the form INTO that scope
+   * needs no state at all.
+   */
+  renderCardStep?: (args: {
+    clientSecret: string;
+    /** Render the form with the live provider context and its field node. */
+    renderForm: (args: { elementsContext: unknown; field: React.ReactNode }) => React.ReactNode;
+  }) => React.ReactNode;
+  /** Mock path: renders the 4242 stub instead of a provider field. */
+  isMock?: boolean;
+  returnUrl?: string;
+  /** Fired after Stripe stored the card. NOT proof the subscription recovered. */
+  onSaved?: (setupIntentId: string) => void;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  submitLabel?: string;
+  consentText?: string;
+  className?: string;
+}
+
+export function UpdateCardDialog({
+  open,
+  onClose,
+  subscriptionId,
+  renderCardStep,
+  isMock = false,
+  returnUrl,
+  onSaved,
+  title = 'Add a card',
+  description = 'Save a card for future renewals.',
+  submitLabel,
+  consentText,
+  className,
+}: UpdateCardDialogProps) {
+  const setup = useCardSetup();
+  const { start, reset, status, error, intent, supported } = setup;
+
+  const input: SaveCardInput | undefined = subscriptionId ? { subscriptionId } : undefined;
+
+  useEffect(() => {
+    if (!open) {
+      reset();
+      return;
+    }
+    if (supported) void start(input);
+    // `input` is derived from subscriptionId; re-running on open is the intent.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, supported, subscriptionId]);
+
+  const handleSuccess = useCallback(
+    (setupIntentId: string) => {
+      onSaved?.(setupIntentId);
+    },
+    [onSaved],
+  );
+
+  let body: React.ReactNode;
+
+  if (!supported) {
+    body = (
+      <Alert variant="destructive">
+        <AlertTriangle className="h-4 w-4" />
+        <AlertDescription>
+          This account cannot save a card. Contact support to update your billing details.
+        </AlertDescription>
+      </Alert>
+    );
+  } else if (status === 'creating' || (!intent && status !== 'failed')) {
+    body = (
+      <div className="flex flex-col items-center gap-2 py-8">
+        <Spinner className="h-5 w-5" />
+        <p className="text-muted-foreground text-sm">Preparing the secure form…</p>
+      </div>
+    );
+  } else if (!intent) {
+    // Creation failed: the form would have no clientSecret to render against,
+    // so offer the retry here rather than an empty card field.
+    body = (
+      <div className="space-y-3 py-2">
+        <Alert variant="destructive">
+          <AlertTriangle className="h-4 w-4" />
+          <AlertDescription>{error ?? 'Could not open the card form.'}</AlertDescription>
+        </Alert>
+        <Button type="button" variant="outline" className="w-full" onClick={() => void start(input)}>
+          Retry
+        </Button>
+      </div>
+    );
+  } else {
+    const renderForm = ({
+      elementsContext,
+      field,
+    }: {
+      elementsContext: unknown;
+      field: React.ReactNode;
+    }) => (
+      <CardSetupForm
+        setup={setup}
+        isMock={isMock}
+        elementsContext={elementsContext}
+        paymentField={field}
+        returnUrl={returnUrl}
+        submitLabel={submitLabel}
+        consentText={consentText}
+        onSuccess={handleSuccess}
+        onCancel={onClose}
+      />
+    );
+
+    body = renderCardStep
+      ? renderCardStep({ clientSecret: intent.clientSecret, renderForm })
+      : renderForm({ elementsContext: undefined, field: undefined });
+  }
+
+  return (
+    <CheckoutDialog
+      open={open}
+      onClose={onClose}
+      title={title}
+      description={description}
+      className={className}
+    >
+      {body}
+    </CheckoutDialog>
+  );
+}

package/src/components/index.ts

@@ -19,3 +19,12 @@ export type { PaymentHistoryProps } from './PaymentHistory';
 
 export { PaymentStatusBadge } from './PaymentStatusBadge';
 export type { PaymentStatusBadgeProps } from './PaymentStatusBadge';
+
+export { SavedCardList } from './SavedCardList';
+export type { SavedCardListProps, SavedCardListLabels } from './SavedCardList';
+
+export { CardSetupForm } from './CardSetupForm';
+export type { CardSetupFormProps } from './CardSetupForm';
+
+export { UpdateCardDialog } from './UpdateCardDialog';
+export type { UpdateCardDialogProps } from './UpdateCardDialog';

package/src/domain/cards.ts

@@ -0,0 +1,63 @@
+// ============================================================================
+// @djangocfg/payments — card derivations (pure: no React, no Stripe)
+// ============================================================================
+// `SavedCard` stores only what the provider states. Everything below is
+// derived against a clock, so it lives here rather than in a component: two
+// readers computing "expiring soon" separately drift the first time one of
+// them forgets that a card is valid through the END of its expiry month.
+
+import type { SavedCard, SavedCardsPhase } from './types';
+
+/** The cards a phase carries. `error` keeps the last known list, so it renders. */
+export function cardsOf(phase: SavedCardsPhase): SavedCard[] {
+  if (phase.kind === 'ready') return phase.cards;
+  if (phase.kind === 'error') return phase.previous ?? [];
+  return [];
+}
+
+/** Days before expiry at which a card is worth flagging. */
+export const EXPIRY_WARNING_DAYS = 60;
+
+/**
+ * The instant a card stops working: midnight after the last day of its expiry
+ * month. A card marked 08/2026 is valid through 2026-08-31.
+ */
+export function cardExpiresAt(card: SavedCard): Date {
+  // Day 1 of the FOLLOWING month. `Date` normalizes month 12 into next
+  // January, so December needs no special case.
+  return new Date(card.expYear, card.expMonth, 1);
+}
+
+/** Whether the card can no longer be charged. */
+export function isCardExpired(card: SavedCard, now: Date = new Date()): boolean {
+  return cardExpiresAt(card).getTime() <= now.getTime();
+}
+
+/**
+ * Whether the card still works but is close enough to expiry to warn about.
+ * False for an already-expired card — that is a different, louder state.
+ */
+export function isCardExpiringSoon(
+  card: SavedCard,
+  now: Date = new Date(),
+  withinDays: number = EXPIRY_WARNING_DAYS,
+): boolean {
+  const expiresAt = cardExpiresAt(card).getTime();
+  if (expiresAt <= now.getTime()) return false;
+  return expiresAt - now.getTime() <= withinDays * 24 * 60 * 60 * 1000;
+}
+
+/** `expMonth`/`expYear` as `MM/YY`. Display only. */
+export function formatCardExpiry(card: SavedCard): string {
+  const month = String(card.expMonth).padStart(2, '0');
+  const year = String(card.expYear).slice(-2);
+  return `${month}/${year}`;
+}
+
+/** Default first, then soonest to expire — the order a chooser wants. */
+export function sortCards(cards: readonly SavedCard[]): SavedCard[] {
+  return cards.slice().sort((a, b) => {
+    if (a.isDefault !== b.isDefault) return a.isDefault ? -1 : 1;
+    return cardExpiresAt(a).getTime() - cardExpiresAt(b).getTime();
+  });
+}

package/src/domain/index.ts

@@ -18,6 +18,20 @@ export type {
   PaymentRecord,
   PaymentPage,
   PaymentProviderAdapter,
+  SetupIntent,
+  SaveCardInput,
+  SavedCard,
+  SavedCardsPhase,
 } from './types';
 
+export {
+  EXPIRY_WARNING_DAYS,
+  cardsOf,
+  cardExpiresAt,
+  isCardExpired,
+  isCardExpiringSoon,
+  formatCardExpiry,
+  sortCards,
+} from './cards';
+
 export { toMinorUnits, toMajorUnits, formatAmount } from './money';

package/src/domain/types.ts

@@ -126,6 +126,73 @@ export interface SubscriptionIntent {
   provider: PaymentProviderId;
 }
 
+// ---------------------------------------------------------------------------
+// Card on file
+// ---------------------------------------------------------------------------
+// A subscription outlives the card that pays for it. Stripe retries a failed
+// renewal for ~2 weeks against the SAME stored card, so a customer who cannot
+// replace it loses the subscription regardless of intent to pay.
+//
+// Saving a card here is the same Stripe operation as the $0/trial branch of
+// checkout — a SetupIntent confirmed with `confirmSetup`. Only the entry point
+// is new; `ConfirmArgs.confirmType = 'setup'` already dispatches it.
+
+/** A SetupIntent: authorization to store a card, charging nothing now. */
+export interface SetupIntent {
+  /** Provider intent id (e.g. `seti_…` for Stripe). */
+  id: string;
+  /** Confirmed on the frontend with `confirmType: 'setup'`. */
+  clientSecret: string;
+  provider: PaymentProviderId;
+}
+
+/** Input to create a SetupIntent. */
+export interface SaveCardInput {
+  /**
+   * Make the saved card this subscription's default on success. Omit to store
+   * it at account level only. The CUSTOMER is always resolved server-side from
+   * the session — never sent from here.
+   */
+  subscriptionId?: string;
+}
+
+/**
+ * A card already on file.
+ *
+ * Carries no `status` and no `isExpiring` on purpose: both are derivations
+ * from `expMonth`/`expYear` against today, and a stored copy goes stale on the
+ * first day of a month. Readers derive them.
+ */
+export interface SavedCard {
+  /** Provider payment-method id (e.g. `pm_…`). */
+  id: string;
+  /** Display only — never branch on it. */
+  brand: string;
+  last4: string;
+  /** 1-12. */
+  expMonth: number;
+  /** Four digits. */
+  expYear: number;
+  /** Whether renewals charge this card. */
+  isDefault: boolean;
+}
+
+/**
+ * Cards on file as a phase, not a boolean pair.
+ *
+ * `[]` answers three different questions identically: the host wired no card
+ * endpoints, the read has not run, and the customer genuinely has no card.
+ * They are three screens, so they are three states.
+ */
+export type SavedCardsPhase =
+  /** The adapter defines no card methods — no card-on-file capability here. */
+  | { kind: 'unavailable' }
+  /** Never loaded. A reserved-height skeleton, not nothing. */
+  | { kind: 'loading' }
+  | { kind: 'ready'; cards: SavedCard[]; refreshing: boolean }
+  /** `previous` keeps the last known list, so a failed refresh does not blank it. */
+  | { kind: 'error'; message: string; previous?: SavedCard[] };
+
 /**
  * Provider-agnostic seam. The HOST injects one implementation via
  * <PaymentProvider adapter={…}>. Package code depends on THIS interface,
@@ -150,4 +217,20 @@ export interface PaymentProviderAdapter {
   retrieve?(intentId: string): Promise<PaymentIntent>;
   /** Optional: paginated history for <PaymentHistory>. */
   listPayments?(params?: { limit?: number; cursor?: string }): Promise<PaymentPage>;
+
+  // --- Card on file (all four optional together) ---------------------------
+  // ABSENCE IS THE SIGNAL. A one-time-payment adapter has no card on file, and
+  // an undefined method — not a capability flag — is what says so. Readers
+  // MUST render an `unavailable` state rather than coercing to an empty list:
+  // "no cards on file" and "this host never wired the endpoint" look identical
+  // once both are `[]`, and they mean opposite things.
+
+  /** Backend creates a SetupIntent against the stored customer. */
+  createSetupIntent?(input?: SaveCardInput): Promise<SetupIntent>;
+  /** Cards on file, newest default first. */
+  listPaymentMethods?(): Promise<SavedCard[]>;
+  /** Make one saved card the default for renewals. */
+  setDefaultPaymentMethod?(id: string): Promise<void>;
+  /** Detach a saved card. Rejected server-side when it is the last one on an active subscription. */
+  removePaymentMethod?(id: string): Promise<void>;
 }

package/src/hooks/index.ts

@@ -7,3 +7,9 @@ export type { UseCheckoutResult } from './useCheckout';
 
 export { usePaymentHistory } from './usePaymentHistory';
 export type { UsePaymentHistoryProps, UsePaymentHistoryResult } from './usePaymentHistory';
+
+export { useSavedCards } from './useSavedCards';
+export type { UseSavedCardsProps, UseSavedCardsResult } from './useSavedCards';
+
+export { useCardSetup } from './useCardSetup';
+export type { UseCardSetupResult } from './useCardSetup';

package/src/hooks/useCardSetup.ts

@@ -0,0 +1,138 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — useCardSetup (save a card, charge nothing now)
+// ============================================================================
+// The state machine for putting a card on file:
+//   idle → creating → requires_payment → processing → succeeded | failed | requires_action
+//
+// Deliberately the SAME PaymentStatus vocabulary as useCheckout. One status
+// union across the package means <PaymentStatusBadge> and every host branch
+// read one set of names, not two that mean the same things.
+//
+// What it is NOT: proof that a subscription recovered. A succeeded SetupIntent
+// means Stripe stored the card. Whether the open invoice then gets paid is a
+// server decision reported by webhook — see the track's §6.
+
+import { useCallback, useRef, useState } from 'react';
+import { usePaymentAdapter } from '../context/PaymentProvider';
+import type {
+  ConfirmArgs,
+  PaymentStatus,
+  SaveCardInput,
+  SetupIntent,
+} from '../domain/types';
+
+export interface UseCardSetupResult {
+  status: PaymentStatus;
+  /** The SetupIntent once created; its clientSecret drives <StripePaymentElement>. */
+  intent: SetupIntent | null;
+  error: string | null;
+  /** Set when the provider needs a redirect / 3DS step. */
+  nextActionUrl: string | null;
+  /** Whether the adapter can save a card at all. */
+  supported: boolean;
+  /** Step 1: create the SetupIntent. Resolves with it, or undefined on failure. */
+  start: (input?: SaveCardInput) => Promise<SetupIntent | undefined>;
+  /** Step 2: confirm with the provider (Stripe Elements or mock). */
+  confirm: (
+    elementsContext?: ConfirmArgs['elementsContext'],
+    returnUrl?: string,
+  ) => Promise<void>;
+  reset: () => void;
+  /** True while a network step is in flight. */
+  isBusy: boolean;
+}
+
+export function useCardSetup(): UseCardSetupResult {
+  const adapter = usePaymentAdapter();
+  const supported = typeof adapter.createSetupIntent === 'function';
+
+  const [status, setStatus] = useState<PaymentStatus>('idle');
+  const [intent, setIntent] = useState<SetupIntent | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [nextActionUrl, setNextActionUrl] = useState<string | null>(null);
+
+  // Latest intent for confirm() without a stale closure — same device as
+  // useCheckout's intentRef.
+  const intentRef = useRef<SetupIntent | null>(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setIntent(null);
+    setError(null);
+    setNextActionUrl(null);
+    intentRef.current = null;
+  }, []);
+
+  const start = useCallback(
+    async (input?: SaveCardInput) => {
+      setError(null);
+      setNextActionUrl(null);
+      setStatus('creating');
+      if (!adapter.createSetupIntent) {
+        setStatus('failed');
+        setError('This payment provider cannot save a card.');
+        return undefined;
+      }
+      try {
+        const created = await adapter.createSetupIntent(input);
+        intentRef.current = created;
+        setIntent(created);
+        setStatus('requires_payment');
+        return created;
+      } catch (e) {
+        setStatus('failed');
+        setError(e instanceof Error ? e.message : 'Failed to start saving the card.');
+        return undefined;
+      }
+    },
+    [adapter],
+  );
+
+  const confirm = useCallback(
+    async (elementsContext?: ConfirmArgs['elementsContext'], returnUrl?: string) => {
+      const current = intentRef.current;
+      if (!current?.clientSecret) {
+        setStatus('failed');
+        setError('The card form is not ready to submit.');
+        return;
+      }
+
+      setError(null);
+      setStatus('processing');
+      try {
+        // `confirmType: 'setup'` is what dispatches stripe.confirmSetup. The
+        // adapter already sends mandate_data.customer_acceptance with it, which
+        // is what makes the stored card chargeable off-session at renewal.
+        const result = await adapter.confirm({
+          clientSecret: current.clientSecret,
+          elementsContext,
+          returnUrl,
+          confirmType: 'setup',
+        });
+        setStatus(result.status);
+        if (result.error) setError(result.error);
+        if (result.nextActionUrl) setNextActionUrl(result.nextActionUrl);
+      } catch (e) {
+        setStatus('failed');
+        setError(e instanceof Error ? e.message : 'Could not save your card.');
+      }
+    },
+    [adapter],
+  );
+
+  const isBusy = status === 'creating' || status === 'processing';
+
+  return {
+    status,
+    intent,
+    error,
+    nextActionUrl,
+    supported,
+    start,
+    confirm,
+    reset,
+    isBusy,
+  };
+}

package/src/hooks/useSavedCards.ts

@@ -0,0 +1,139 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — useSavedCards
+// ============================================================================
+// Owns the cards-on-file list via the adapter's optional listPaymentMethods().
+//
+// WHY A PHASE AND NOT A BOOLEAN PAIR. `[]` answers three different questions
+// identically: the host never wired the endpoint, the request has not run yet,
+// and the customer genuinely has no card. The first renders a dead "Add card"
+// button, the second flashes an empty table before data lands, the third is a
+// real empty state. They are different screens, so they are different states.
+
+import { useCallback, useEffect, useState } from 'react';
+import { usePaymentAdapter } from '../context/PaymentProvider';
+import type { SavedCard, SavedCardsPhase } from '../domain/types';
+import { cardsOf, sortCards } from '../domain/cards';
+
+export interface UseSavedCardsResult {
+  phase: SavedCardsPhase;
+  /** Cards known right now, including during a refresh or after a failed one. */
+  cards: SavedCard[];
+  /** Whether the adapter can add a card. Gates the primary action. */
+  canAddCard: boolean;
+  /** Whether the adapter can change the default and detach a card. */
+  canManageCards: boolean;
+  refresh: () => Promise<void>;
+  /** Make one card the default for renewals, then re-read. */
+  setDefault: (id: string) => Promise<void>;
+  /** Detach a card, then re-read. Rejects on the last card of an active subscription. */
+  remove: (id: string) => Promise<void>;
+  /** True while any of the three calls is in flight. */
+  isBusy: boolean;
+}
+
+export interface UseSavedCardsProps {
+  /** Load on mount. Default true. */
+  autoLoad?: boolean;
+}
+
+export function useSavedCards(
+  { autoLoad = true }: UseSavedCardsProps = {},
+): UseSavedCardsResult {
+  const adapter = usePaymentAdapter();
+  const canList = typeof adapter.listPaymentMethods === 'function';
+  const canAddCard = typeof adapter.createSetupIntent === 'function';
+  const canManageCards =
+    typeof adapter.setDefaultPaymentMethod === 'function' &&
+    typeof adapter.removePaymentMethod === 'function';
+
+  const [phase, setPhase] = useState<SavedCardsPhase>(
+    canList ? { kind: 'loading' } : { kind: 'unavailable' },
+  );
+  const [isBusy, setIsBusy] = useState(false);
+
+  const refresh = useCallback(async () => {
+    if (!adapter.listPaymentMethods) {
+      setPhase({ kind: 'unavailable' });
+      return;
+    }
+    setPhase((prev) =>
+      prev.kind === 'ready'
+        ? { ...prev, refreshing: true }
+        : prev.kind === 'error'
+          ? { kind: 'loading' }
+          : prev,
+    );
+    try {
+      const list = await adapter.listPaymentMethods();
+      setPhase({ kind: 'ready', cards: sortCards(list), refreshing: false });
+    } catch (e) {
+      setPhase((prev) => ({
+        kind: 'error',
+        message: e instanceof Error ? e.message : 'Failed to load cards.',
+        previous: cardsOf(prev),
+      }));
+    }
+  }, [adapter]);
+
+  // A write is only believed once the re-read confirms it: the server may
+  // refuse (detaching the last card) or adjust (promoting a new default), and
+  // an optimistic list would state the opposite of what renewals will charge.
+  const mutate = useCallback(
+    async (run: () => Promise<void>, fallback: string) => {
+      setIsBusy(true);
+      try {
+        await run();
+        await refresh();
+      } catch (e) {
+        setPhase((prev) => ({
+          kind: 'error',
+          message: e instanceof Error ? e.message : fallback,
+          previous: cardsOf(prev),
+        }));
+      } finally {
+        setIsBusy(false);
+      }
+    },
+    [refresh],
+  );
+
+  const setDefault = useCallback(
+    (id: string) =>
+      mutate(async () => {
+        if (!adapter.setDefaultPaymentMethod) {
+          throw new Error('This payment provider cannot change the default card.');
+        }
+        await adapter.setDefaultPaymentMethod(id);
+      }, 'Failed to change the default card.'),
+    [adapter, mutate],
+  );
+
+  const remove = useCallback(
+    (id: string) =>
+      mutate(async () => {
+        if (!adapter.removePaymentMethod) {
+          throw new Error('This payment provider cannot remove a card.');
+        }
+        await adapter.removePaymentMethod(id);
+      }, 'Failed to remove the card.'),
+    [adapter, mutate],
+  );
+
+  useEffect(() => {
+    if (autoLoad && canList) void refresh();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoLoad, canList]);
+
+  return {
+    phase,
+    cards: cardsOf(phase),
+    canAddCard,
+    canManageCards,
+    refresh,
+    setDefault,
+    remove,
+    isBusy,
+  };
+}