@djangocfg/payments 2.1.457

package/src/transport/mock-adapter.ts

@@ -0,0 +1,149 @@
+// ============================================================================
+// @djangocfg/payments — mock adapter (mock-first development)
+// ============================================================================
+// Fakes the full payment state machine with delays so apps/my can build and
+// verify the entire checkout UX before any backend endpoint or Stripe key
+// exists. Swapping to the real Stripe adapter is a one-line host change.
+
+import type {
+  ConfirmArgs,
+  ConfirmResult,
+  CreatePaymentInput,
+  PaymentIntent,
+  PaymentPage,
+  PaymentProviderAdapter,
+  PaymentRecord,
+  StartSubscriptionInput,
+  SubscriptionIntent,
+} from '../domain/types';
+
+/** Outcome the mock should simulate on confirm. */
+export type MockOutcome = 'succeeded' | 'failed' | 'requires_action';
+
+export interface MockAdapterConfig {
+  /** Latency per step, ms. Default 600. */
+  latencyMs?: number;
+  /** What confirm() resolves to. Default 'succeeded'. */
+  outcome?: MockOutcome;
+  /** Error message when outcome === 'failed'. */
+  failureMessage?: string;
+  /** Fixture history for listPayments(). */
+  history?: PaymentRecord[];
+  /**
+   * Deterministic timestamp factory (tests). Defaults to `new Date()`.
+   * Kept injectable so stories/tests stay stable.
+   */
+  now?: () => Date;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+let counter = 0;
+function nextId(prefix: string): string {
+  counter += 1;
+  return `${prefix}_mock_${counter}`;
+}
+
+export function createMockPaymentAdapter(
+  config: MockAdapterConfig = {},
+): PaymentProviderAdapter {
+  const {
+    latencyMs = 600,
+    outcome = 'succeeded',
+    failureMessage = 'Your card was declined.',
+    history = [],
+    now = () => new Date(),
+  } = config;
+
+  let lastIntent: PaymentIntent | null = null;
+
+  return {
+    id: 'mock',
+
+    async createIntent(input: CreatePaymentInput): Promise<PaymentIntent> {
+      await delay(latencyMs);
+      const intent: PaymentIntent = {
+        id: nextId('pi'),
+        clientSecret: nextId('secret'),
+        amount: input.amount,
+        currency: input.currency,
+        status: 'requires_payment',
+        reference: input.reference,
+        provider: 'mock',
+        createdAt: now().toISOString(),
+      };
+      lastIntent = intent;
+      return intent;
+    },
+
+    async confirm(_args: ConfirmArgs): Promise<ConfirmResult> {
+      await delay(latencyMs);
+      const intentId = lastIntent?.id ?? nextId('pi');
+
+      if (outcome === 'failed') {
+        if (lastIntent) lastIntent = { ...lastIntent, status: 'failed' };
+        return { status: 'failed', intentId, error: failureMessage };
+      }
+
+      if (outcome === 'requires_action') {
+        if (lastIntent) lastIntent = { ...lastIntent, status: 'requires_action' };
+        return {
+          status: 'requires_action',
+          intentId,
+          nextActionUrl: 'https://mock.test/3ds-challenge',
+        };
+      }
+
+      if (lastIntent) lastIntent = { ...lastIntent, status: 'succeeded' };
+      return { status: 'succeeded', intentId };
+    },
+
+    async createSubscription(input: StartSubscriptionInput): Promise<SubscriptionIntent> {
+      await delay(latencyMs);
+      const subId = nextId('sub');
+      // Mock the deferred flow: a paid first invoice → confirmPayment path, with
+      // a fake client_secret the mock confirm() accepts. (Trial/$0 setup path
+      // isn't exercised here — Free plans never reach the adapter.)
+      const intent: PaymentIntent = {
+        id: subId,
+        clientSecret: nextId('seti_or_pi_secret'),
+        amount: 0,
+        currency: 'usd',
+        status: 'requires_payment',
+        reference: { kind: 'subscription', id: subId },
+        provider: 'mock',
+        createdAt: now().toISOString(),
+      };
+      lastIntent = intent;
+      return {
+        stripeSubscriptionId: subId,
+        status: 'incomplete',
+        confirmType: 'payment',
+        clientSecret: intent.clientSecret,
+        provider: 'mock',
+      };
+    },
+
+    async retrieve(intentId: string): Promise<PaymentIntent> {
+      await delay(latencyMs / 2);
+      if (lastIntent && lastIntent.id === intentId) return lastIntent;
+      return {
+        id: intentId,
+        clientSecret: null,
+        amount: 0,
+        currency: 'usd',
+        status: 'succeeded',
+        reference: { kind: 'order', id: 'unknown' },
+        provider: 'mock',
+        createdAt: now().toISOString(),
+      };
+    },
+
+    async listPayments(): Promise<PaymentPage> {
+      await delay(latencyMs / 2);
+      return { items: history };
+    },
+  };
+}

package/src/transport/stripe-adapter.ts

@@ -0,0 +1,199 @@
+// ============================================================================
+// @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.
+//
+// The publishable key and the create-intent HTTP call are HOST
+// responsibilities, passed in via StripeAdapterConfig — the package never
+// reads env vars or imports the generated API client.
+
+import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type {
+  ConfirmArgs,
+  ConfirmResult,
+  CreatePaymentInput,
+  PaymentIntent,
+  PaymentPage,
+  PaymentProviderAdapter,
+  PaymentStatus,
+  StartSubscriptionInput,
+  SubscriptionIntent,
+} from '../domain/types';
+
+/** Raw shape the host's backend returns from its create-intent endpoint. */
+export interface BackendIntent {
+  id: string;
+  client_secret: string;
+  status: string;
+}
+
+/**
+ * Raw shape the host's backend returns from `subscribe-checkout` (paid branch).
+ * Mirrors the Django `SubscribeCheckoutResult` (snake_case).
+ */
+export interface BackendSubscription {
+  stripe_subscription_id: string;
+  status: string;
+  confirm_type: 'payment' | 'setup';
+  client_secret: string | null;
+}
+
+export interface StripeAdapterConfig {
+  /** Resolved by the host: memoized loadStripe(publishableKey). */
+  getStripe: () => Promise<Stripe | null>;
+  /** Host transport call → POST /payments/intents → { id, client_secret, status }. */
+  createIntentOnBackend: (input: CreatePaymentInput) => Promise<BackendIntent>;
+  /**
+   * Host transport call → POST /billing/subscribe-checkout/ (paid branch only) →
+   * the raw `SubscribeCheckoutResult`. Injected by the host so the package never
+   * touches the generated client. Omit on adapters that don't do subscriptions.
+   */
+  createSubscriptionOnBackend?: (input: StartSubscriptionInput) => Promise<BackendSubscription>;
+  /** Optional history fetch (host transport → GET /payments). */
+  listPaymentsOnBackend?: PaymentProviderAdapter['listPayments'];
+  /** Deterministic timestamp factory (tests). Defaults to `new Date()`. */
+  now?: () => Date;
+}
+
+/** Map a Stripe PaymentIntent status string to our normalized status. */
+function mapStripeStatus(status: string): PaymentStatus {
+  switch (status) {
+    case 'requires_payment_method':
+    case 'requires_confirmation':
+      return 'requires_payment';
+    case 'requires_action':
+    case 'requires_capture':
+      return 'requires_action';
+    case 'processing':
+      return 'processing';
+    case 'succeeded':
+      return 'succeeded';
+    case 'canceled':
+      return 'canceled';
+    default:
+      return 'failed';
+  }
+}
+
+export function createStripeAdapter(
+  cfg: StripeAdapterConfig,
+): PaymentProviderAdapter {
+  const now = cfg.now ?? (() => new Date());
+
+  return {
+    id: 'stripe',
+
+    async createIntent(input: CreatePaymentInput): Promise<PaymentIntent> {
+      const raw = await cfg.createIntentOnBackend(input);
+      return {
+        id: raw.id,
+        clientSecret: raw.client_secret,
+        amount: input.amount,
+        currency: input.currency,
+        status: mapStripeStatus(raw.status),
+        reference: input.reference,
+        provider: 'stripe',
+        createdAt: now().toISOString(),
+      };
+    },
+
+    async confirm(args: ConfirmArgs): Promise<ConfirmResult> {
+      const stripe = await cfg.getStripe();
+      if (!stripe) {
+        return {
+          status: 'failed',
+          intentId: '',
+          error: 'Stripe failed to initialize.',
+        };
+      }
+
+      const elements = args.elementsContext as StripeElements | undefined;
+      if (!elements) {
+        return {
+          status: 'failed',
+          intentId: '',
+          error: 'Missing Stripe Elements context.',
+        };
+      }
+
+      // `mandate_data` is REQUIRED for recurring alt-methods (Cash App Pay,
+      // Amazon Pay, SEPA…) or they silently fail to confirm on a subscription.
+      // Harmless for card. `infer_from_client` lets Stripe derive the mandate
+      // text from the on-screen agreement (research §2).
+      const confirmParams = {
+        ...(args.returnUrl ? { return_url: args.returnUrl } : {}),
+        mandate_data: {
+          customer_acceptance: {
+            type: 'online' as const,
+            online: { infer_from_client: true },
+          },
+        },
+      };
+
+      // Deferred subscription with nothing to charge now ($0 / trial): confirm a
+      // SetupIntent to save the card for future renewals. Otherwise confirm the
+      // (first-invoice) PaymentIntent. Same <Elements clientSecret> either way —
+      // only the confirm call differs (research §1 branch).
+      if (args.confirmType === 'setup') {
+        const { error, setupIntent } = await stripe.confirmSetup({
+          elements,
+          confirmParams,
+          redirect: 'if_required',
+        });
+        if (error) {
+          return {
+            status: 'failed',
+            intentId: error.setup_intent?.id ?? '',
+            error: error.message ?? 'Could not save your card.',
+          };
+        }
+        return {
+          status: mapStripeStatus(setupIntent?.status ?? 'failed'),
+          intentId: setupIntent?.id ?? '',
+        };
+      }
+
+      const { error, paymentIntent } = await stripe.confirmPayment({
+        elements,
+        confirmParams,
+        redirect: 'if_required',
+      });
+
+      if (error) {
+        return {
+          status: 'failed',
+          intentId: error.payment_intent?.id ?? '',
+          error: error.message ?? 'Payment failed.',
+        };
+      }
+
+      return {
+        status: mapStripeStatus(paymentIntent?.status ?? 'failed'),
+        intentId: paymentIntent?.id ?? '',
+      };
+    },
+
+    createSubscription: cfg.createSubscriptionOnBackend
+      ? async (input: StartSubscriptionInput): Promise<SubscriptionIntent> => {
+          const raw = await cfg.createSubscriptionOnBackend!(input);
+          return {
+            stripeSubscriptionId: raw.stripe_subscription_id,
+            status: raw.status,
+            confirmType: raw.confirm_type,
+            clientSecret: raw.client_secret,
+            provider: 'stripe',
+          };
+        }
+      : 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).
+
+    listPayments: cfg.listPaymentsOnBackend
+      ? (params): Promise<PaymentPage> => cfg.listPaymentsOnBackend!(params)
+      : undefined,
+  };
+}