@djangocfg/payments 2.1.560 → 2.1.562

package/src/index.ts

@@ -3,9 +3,14 @@
 // ============================================================================
 // The host injects ONE adapter (mock or stripe) via <PaymentProvider>.
 // Package code depends only on the domain types + the adapter seam — never on
-// a concrete SDK or a generated API client. @stripe/* is touched in exactly
-// two files (stripe-adapter.ts, StripePaymentElement.tsx); it ships as a
-// regular dep (stripe-js is just the CDN loader) and tree-shakes out of mock-only bundles.
+// a concrete SDK or a generated API client.
+//
+// @stripe/* is a RUNTIME dependency of two files (stripe-adapter.ts,
+// StripePaymentElement.tsx) and a type-only one of a third (appearance.ts).
+// It ships as a regular dep — stripe-js is just the CDN loader — and
+// tree-shakes out of mock-only bundles. Enforced by
+// scripts/check-stripe-imports.mjs, because this rule was stated in four
+// comments and checked by none until it had already drifted.
 
 // Domain (types + money helpers)
 export * from './domain';
@@ -36,15 +41,20 @@ export type {
   StripeAdapterConfig,
   BackendIntent,
   BackendSubscription,
+  BackendSetupIntent,
+  BackendSavedCard,
   Stripe,
 } from './transport';
 
 // Hooks
-export { useCheckout, usePaymentHistory } from './hooks';
+export { useCheckout, usePaymentHistory, useSavedCards, useCardSetup } from './hooks';
 export type {
   UseCheckoutResult,
   UsePaymentHistoryProps,
   UsePaymentHistoryResult,
+  UseSavedCardsProps,
+  UseSavedCardsResult,
+  UseCardSetupResult,
 } from './hooks';
 
 // Components
@@ -56,6 +66,9 @@ export {
   buildStripeAppearance,
   PaymentHistory,
   PaymentStatusBadge,
+  SavedCardList,
+  CardSetupForm,
+  UpdateCardDialog,
 } from './components';
 export type {
   CheckoutDialogProps,
@@ -65,4 +78,8 @@ export type {
   AppearanceTokens,
   PaymentHistoryProps,
   PaymentStatusBadgeProps,
+  SavedCardListProps,
+  SavedCardListLabels,
+  CardSetupFormProps,
+  UpdateCardDialogProps,
 } from './components';

package/src/transport/index.ts

@@ -10,5 +10,7 @@ export type {
   StripeAdapterConfig,
   BackendIntent,
   BackendSubscription,
+  BackendSetupIntent,
+  BackendSavedCard,
   Stripe,
 } from './stripe-adapter';

package/src/transport/mock-adapter.ts

@@ -13,6 +13,9 @@ import type {
   PaymentPage,
   PaymentProviderAdapter,
   PaymentRecord,
+  SavedCard,
+  SaveCardInput,
+  SetupIntent,
   StartSubscriptionInput,
   SubscriptionIntent,
 } from '../domain/types';
@@ -29,6 +32,16 @@ export interface MockAdapterConfig {
   failureMessage?: string;
   /** Fixture history for listPayments(). */
   history?: PaymentRecord[];
+  /**
+   * Fixture cards for listPaymentMethods(). Defaults to two: a default Visa
+   * and an Amex inside the expiry warning window, so a story renders both the
+   * ordinary and the warning row without configuration.
+   *
+   * Pass `[]` for the loaded-and-empty state. Pass `null` to drop the four
+   * card methods entirely — that is the `unavailable` state a host sees when
+   * it never wired the endpoints, and it must look different from `[]`.
+   */
+  cards?: SavedCard[] | null;
   /**
    * Deterministic timestamp factory (tests). Defaults to `new Date()`.
    * Kept injectable so stories/tests stay stable.
@@ -40,6 +53,29 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/** A default Visa plus an Amex inside the warning window, relative to `now`. */
+function defaultMockCards(now: Date): SavedCard[] {
+  const soon = new Date(now.getFullYear(), now.getMonth() + 2, 1);
+  return [
+    {
+      id: 'pm_mock_visa',
+      brand: 'visa',
+      last4: '4242',
+      expMonth: now.getMonth() + 1,
+      expYear: now.getFullYear() + 3,
+      isDefault: true,
+    },
+    {
+      id: 'pm_mock_amex',
+      brand: 'amex',
+      last4: '0005',
+      expMonth: soon.getMonth() + 1,
+      expYear: soon.getFullYear(),
+      isDefault: false,
+    },
+  ];
+}
+
 let counter = 0;
 function nextId(prefix: string): string {
   counter += 1;
@@ -59,6 +95,11 @@ export function createMockPaymentAdapter(
 
   let lastIntent: PaymentIntent | null = null;
 
+  // `cards: null` means "this adapter has no card-on-file capability", which
+  // is expressed by leaving the four methods undefined — not by an empty list.
+  const supportsCards = config.cards !== null;
+  let cards: SavedCard[] = config.cards ?? defaultMockCards(now());
+
   return {
     id: 'mock',
 
@@ -141,6 +182,63 @@ export function createMockPaymentAdapter(
       };
     },
 
+    // Card on file. Defined only when the fixture says this adapter has the
+    // capability — `cards: null` leaves all four undefined, which is how a
+    // reader tells "unsupported" from "none on file".
+    createSetupIntent: supportsCards
+      ? async (_input?: SaveCardInput): Promise<SetupIntent> => {
+          await delay(latencyMs);
+          const id = nextId('seti');
+          // Route mock confirm() through the same lastIntent slot the checkout
+          // path uses, so `outcome` drives the setup branch identically.
+          lastIntent = {
+            id,
+            clientSecret: nextId('seti_secret'),
+            amount: 0,
+            currency: 'usd',
+            status: 'requires_payment',
+            reference: { kind: 'subscription', id },
+            provider: 'mock',
+            createdAt: now().toISOString(),
+          };
+          return { id, clientSecret: lastIntent.clientSecret!, provider: 'mock' };
+        }
+      : undefined,
+
+    listPaymentMethods: supportsCards
+      ? async (): Promise<SavedCard[]> => {
+          await delay(latencyMs / 2);
+          return cards;
+        }
+      : undefined,
+
+    setDefaultPaymentMethod: supportsCards
+      ? async (id: string): Promise<void> => {
+          await delay(latencyMs / 2);
+          if (!cards.some((card) => card.id === id)) {
+            throw new Error(`No such payment method: ${id}`);
+          }
+          cards = cards.map((card) => ({ ...card, isDefault: card.id === id }));
+        }
+      : undefined,
+
+    removePaymentMethod: supportsCards
+      ? async (id: string): Promise<void> => {
+          await delay(latencyMs / 2);
+          const target = cards.find((card) => card.id === id);
+          if (!target) throw new Error(`No such payment method: ${id}`);
+          // Mirrors the server rule: the last card on an active subscription
+          // cannot be detached, or the next renewal has nothing to charge.
+          if (cards.length === 1) {
+            throw new Error('Cannot remove the only card on an active subscription.');
+          }
+          cards = cards.filter((card) => card.id !== id);
+          if (target.isDefault && cards.length > 0) {
+            cards = cards.map((card, index) => ({ ...card, isDefault: index === 0 }));
+          }
+        }
+      : undefined,
+
     async listPayments(): Promise<PaymentPage> {
       await delay(latencyMs / 2);
       return { items: history };

package/src/transport/stripe-adapter.ts

@@ -1,9 +1,10 @@
 // ============================================================================
 // @djangocfg/payments — Stripe adapter (transport layer, Stripe-specific)
 // ============================================================================
-// One of TWO files allowed to import @stripe/* (the other is
-// StripePaymentElement.tsx). Keeping the SDK isolated here keeps the
-// mock-only path Stripe-free in the bundle and the domain/ layer SDK-free.
+// One of two files allowed a RUNTIME @stripe/* import (the other is
+// StripePaymentElement.tsx; appearance.ts may name its types). Keeping the SDK
+// isolated here keeps the mock-only path Stripe-free in the bundle and the
+// domain/ layer SDK-free. Enforced by scripts/check-stripe-imports.mjs.
 //
 // The publishable key and the create-intent HTTP call are HOST
 // responsibilities, passed in via StripeAdapterConfig — the package never
@@ -24,6 +25,9 @@ import type {
   PaymentPage,
   PaymentProviderAdapter,
   PaymentStatus,
+  SavedCard,
+  SaveCardInput,
+  SetupIntent,
   StartSubscriptionInput,
   SubscriptionIntent,
 } from '../domain/types';
@@ -46,6 +50,22 @@ export interface BackendSubscription {
   client_secret: string | null;
 }
 
+/** Raw shape the host's backend returns from its create-setup-intent endpoint. */
+export interface BackendSetupIntent {
+  id: string;
+  client_secret: string;
+}
+
+/** Raw saved-card row from the host's backend (snake_case, as Django serializes). */
+export interface BackendSavedCard {
+  id: string;
+  brand: string;
+  last4: string;
+  exp_month: number;
+  exp_year: number;
+  is_default: boolean;
+}
+
 export interface StripeAdapterConfig {
   /** Resolved by the host: memoized loadStripe(publishableKey). */
   getStripe: () => Promise<Stripe | null>;
@@ -59,10 +79,38 @@ export interface StripeAdapterConfig {
   createSubscriptionOnBackend?: (input: StartSubscriptionInput) => Promise<BackendSubscription>;
   /** Optional history fetch (host transport → GET /payments). */
   listPaymentsOnBackend?: PaymentProviderAdapter['listPayments'];
+  /**
+   * Card on file. Wire all four or none — a host that lists cards but cannot
+   * add one shows a dead end.
+   *
+   * SERVER-SIDE RULES this adapter cannot enforce:
+   *  - create the SetupIntent against the STORED customer, never an id from
+   *    the client;
+   *  - `usage: 'off_session'` — renewals are off-session, and the default
+   *    (`on_session`) stores a card Stripe declines at renewal time;
+   *  - setting a default writes `invoice_settings.default_payment_method` on
+   *    the customer AND `default_payment_method` on the subscription. Only the
+   *    second governs an existing subscription; writing one is a quiet no-op.
+   */
+  createSetupIntentOnBackend?: (input?: SaveCardInput) => Promise<BackendSetupIntent>;
+  listPaymentMethodsOnBackend?: () => Promise<BackendSavedCard[]>;
+  setDefaultPaymentMethodOnBackend?: (id: string) => Promise<void>;
+  removePaymentMethodOnBackend?: (id: string) => Promise<void>;
   /** Deterministic timestamp factory (tests). Defaults to `new Date()`. */
   now?: () => Date;
 }
 
+function mapSavedCard(raw: BackendSavedCard): SavedCard {
+  return {
+    id: raw.id,
+    brand: raw.brand,
+    last4: raw.last4,
+    expMonth: raw.exp_month,
+    expYear: raw.exp_year,
+    isDefault: raw.is_default,
+  };
+}
+
 /** Map a Stripe PaymentIntent status string to our normalized status. */
 function mapStripeStatus(status: string): PaymentStatus {
   switch (status) {
@@ -194,6 +242,32 @@ export function createStripeAdapter(
         }
       : undefined,
 
+    createSetupIntent: cfg.createSetupIntentOnBackend
+      ? async (input?: SaveCardInput): Promise<SetupIntent> => {
+          const raw = await cfg.createSetupIntentOnBackend!(input);
+          return {
+            id: raw.id,
+            clientSecret: raw.client_secret,
+            provider: 'stripe',
+          };
+        }
+      : undefined,
+
+    listPaymentMethods: cfg.listPaymentMethodsOnBackend
+      ? async (): Promise<SavedCard[]> => {
+          const raw = await cfg.listPaymentMethodsOnBackend!();
+          return raw.map(mapSavedCard);
+        }
+      : undefined,
+
+    setDefaultPaymentMethod: cfg.setDefaultPaymentMethodOnBackend
+      ? (id: string): Promise<void> => cfg.setDefaultPaymentMethodOnBackend!(id)
+      : undefined,
+
+    removePaymentMethod: cfg.removePaymentMethodOnBackend
+      ? (id: string): Promise<void> => cfg.removePaymentMethodOnBackend!(id)
+      : undefined,
+
     // No client-side `retrieve`: it needs the client secret, and the webhook
     // is the source of truth anyway. Callers reconcile against backend order
     // status instead. Intentionally omitted (the field is optional).