@djangocfg/payments 2.1.457

package/src/context/PaymentProvider.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — PaymentProvider context (the injected transport seam)
+// ============================================================================
+// The host picks ONE adapter (mock or stripe) and injects it here. Package
+// hooks/components read it via usePaymentAdapter() — they never import a
+// concrete SDK or a generated client.
+
+import React, { createContext, useContext } from 'react';
+import type { PaymentProviderAdapter } from '../domain/types';
+
+const PaymentAdapterContext = createContext<PaymentProviderAdapter | null>(null);
+
+export interface PaymentProviderProps {
+  adapter: PaymentProviderAdapter;
+  children: React.ReactNode;
+}
+
+export function PaymentProvider({ adapter, children }: PaymentProviderProps) {
+  return (
+    <PaymentAdapterContext.Provider value={adapter}>
+      {children}
+    </PaymentAdapterContext.Provider>
+  );
+}
+
+/** Read the injected adapter. Throws if no <PaymentProvider> is mounted. */
+export function usePaymentAdapter(): PaymentProviderAdapter {
+  const adapter = useContext(PaymentAdapterContext);
+  if (!adapter) {
+    throw new Error(
+      'usePaymentAdapter must be used within a <PaymentProvider adapter={…}>. ' +
+        'Inject a mock or stripe adapter at the app root.',
+    );
+  }
+  return adapter;
+}

package/src/domain/index.ts

@@ -0,0 +1,23 @@
+// ============================================================================
+// @djangocfg/payments — domain barrel
+// ============================================================================
+
+export type {
+  Currency,
+  MinorUnits,
+  PaymentProviderId,
+  PaymentReference,
+  PaymentStatus,
+  PaymentIntent,
+  CreatePaymentInput,
+  ConfirmResult,
+  ConfirmArgs,
+  ConfirmType,
+  StartSubscriptionInput,
+  SubscriptionIntent,
+  PaymentRecord,
+  PaymentPage,
+  PaymentProviderAdapter,
+} from './types';
+
+export { toMinorUnits, toMajorUnits, formatAmount } from './money';

package/src/domain/money.ts

@@ -0,0 +1,48 @@
+// ============================================================================
+// @djangocfg/payments — money helpers (framework-free)
+// ============================================================================
+// Amounts cross the package boundary as MinorUnits (integer cents) to avoid
+// float drift. These helpers convert at the display boundary only.
+
+import type { Currency, MinorUnits } from './types';
+
+/** Currencies with no minor unit (amount == major unit). Extend as needed. */
+const ZERO_DECIMAL_CURRENCIES = new Set([
+  'bif', 'clp', 'djf', 'gnf', 'jpy', 'kmf', 'krw', 'mga',
+  'pyg', 'rwf', 'ugx', 'vnd', 'vuv', 'xaf', 'xof', 'xpf',
+]);
+
+function fractionDigits(currency: Currency): number {
+  return ZERO_DECIMAL_CURRENCIES.has(currency.toLowerCase()) ? 0 : 2;
+}
+
+/** Convert a decimal major-unit amount (e.g. 49.0 or "49.00") to minor units. */
+export function toMinorUnits(amount: number | string, currency: Currency): MinorUnits {
+  const value = typeof amount === 'string' ? Number.parseFloat(amount) : amount;
+  if (!Number.isFinite(value)) return 0;
+  const factor = 10 ** fractionDigits(currency);
+  return Math.round(value * factor);
+}
+
+/** Convert minor units back to a major-unit number. */
+export function toMajorUnits(minor: MinorUnits, currency: Currency): number {
+  const factor = 10 ** fractionDigits(currency);
+  return minor / factor;
+}
+
+/** Format minor units as a localized currency string (e.g. "$49.00"). */
+export function formatAmount(
+  minor: MinorUnits,
+  currency: Currency,
+  locale?: string,
+): string {
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: 'currency',
+      currency: currency.toUpperCase(),
+    }).format(toMajorUnits(minor, currency));
+  } catch {
+    // Unknown currency code → fall back to a plain number + code.
+    return `${toMajorUnits(minor, currency).toFixed(fractionDigits(currency))} ${currency.toUpperCase()}`;
+  }
+}

package/src/domain/types.ts

@@ -0,0 +1,153 @@
+// ============================================================================
+// @djangocfg/payments — domain types (framework-free: no React, no Stripe)
+// ============================================================================
+// This is the stable contract the host app compiles against. Package code
+// depends on these types and the PaymentProviderAdapter seam — never on a
+// concrete SDK or a generated API client.
+
+/** ISO 4217 currency, lowercase (e.g. 'usd'). */
+export type Currency = string;
+
+/** Amount in the smallest unit of the currency (e.g. cents for USD). */
+export type MinorUnits = number;
+
+/** Provider identifier. `(string & {})` keeps the union open for future providers. */
+export type PaymentProviderId = 'stripe' | 'mock' | (string & {});
+
+/** What an app entity a payment settles. */
+export interface PaymentReference {
+  kind: 'order' | 'subscription' | 'addon';
+  id: string;
+}
+
+/**
+ * The checkout state machine. Shared by `useCheckout` and the mock adapter so
+ * the whole UX can be exercised before any provider exists.
+ */
+export type PaymentStatus =
+  | 'idle'
+  | 'creating' // creating the PaymentIntent on the backend
+  | 'requires_payment' // client_secret ready, awaiting payment details
+  | 'processing' // confirming with the provider
+  | 'requires_action' // 3DS / redirect needed
+  | 'succeeded'
+  | 'failed'
+  | 'canceled';
+
+/** A payment in flight or settled. Mirrors a provider intent, normalized. */
+export interface PaymentIntent {
+  /** Provider intent id (e.g. `pi_…` for Stripe). */
+  id: string;
+  /** Provider client secret used to confirm on the frontend (Stripe Elements). */
+  clientSecret: string | null;
+  amount: MinorUnits;
+  currency: Currency;
+  status: PaymentStatus;
+  reference: PaymentReference;
+  provider: PaymentProviderId;
+  /** ISO timestamp. */
+  createdAt: string;
+}
+
+/** Input to create a payment intent. Amount is authoritative server-side. */
+export interface CreatePaymentInput {
+  amount: MinorUnits;
+  currency: Currency;
+  reference: PaymentReference;
+  /** Provider-specific extras (coupon, save card, return_url…). */
+  metadata?: Record<string, string>;
+}
+
+/** Result of confirming a payment on the frontend. */
+export interface ConfirmResult {
+  status: PaymentStatus;
+  intentId: string;
+  error?: string;
+  /** Set when the provider needs a redirect / 3DS step. */
+  nextActionUrl?: string;
+}
+
+/** A historical payment row for <PaymentHistory>. */
+export interface PaymentRecord {
+  id: string;
+  amount: MinorUnits;
+  currency: Currency;
+  status: PaymentStatus;
+  reference: PaymentReference;
+  provider: PaymentProviderId;
+  createdAt: string;
+}
+
+/** Page of payment records. */
+export interface PaymentPage {
+  items: PaymentRecord[];
+  nextCursor?: string;
+}
+
+/**
+ * Which client-side confirm to run (deferred subscription flow). For a one-time
+ * PaymentIntent this is always `'payment'` (the default). For a subscription it
+ * comes from the backend: `'payment'` when a first invoice is due
+ * (`stripe.confirmPayment`), `'setup'` for a $0/trial card-on-file
+ * (`stripe.confirmSetup`).
+ */
+export type ConfirmType = 'payment' | 'setup';
+
+/** Arguments for the adapter's confirm step. */
+export interface ConfirmArgs {
+  clientSecret: string;
+  /** Provider-native confirm payload, e.g. a Stripe Elements instance. */
+  elementsContext?: unknown;
+  returnUrl?: string;
+  /** Dispatch confirmPayment vs confirmSetup. Default `'payment'`. */
+  confirmType?: ConfirmType;
+}
+
+/** Input to start a subscription checkout (deferred flow). */
+export interface StartSubscriptionInput {
+  plan: string;
+  cycle: 'monthly' | 'annual' | (string & {});
+  /** Prefill for Stripe Link / receipt. */
+  email?: string;
+}
+
+/**
+ * The backend's deferred-subscription handle, normalized. The subscription is
+ * created `incomplete`; the client confirms `clientSecret` with the call named
+ * by `confirmType`. `clientSecret` is null only when there is nothing to
+ * confirm (a Free plan subscribed directly — the host handles that BEFORE
+ * calling the adapter, so in practice the adapter always gets a secret).
+ */
+export interface SubscriptionIntent {
+  stripeSubscriptionId: string;
+  status: string;
+  confirmType: ConfirmType;
+  clientSecret: string | null;
+  provider: PaymentProviderId;
+}
+
+/**
+ * Provider-agnostic seam. The HOST injects one implementation via
+ * <PaymentProvider adapter={…}>. Package code depends on THIS interface,
+ * never on a concrete SDK or a generated client.
+ */
+export interface PaymentProviderAdapter {
+  readonly id: PaymentProviderId;
+  /** Backend creates the intent; returns a client_secret to confirm with. */
+  createIntent(input: CreatePaymentInput): Promise<PaymentIntent>;
+  /**
+   * Confirm the intent on the frontend. Dispatches on `args.confirmType`:
+   * `'payment'` → `stripe.confirmPayment`, `'setup'` → `stripe.confirmSetup`.
+   */
+  confirm(args: ConfirmArgs): Promise<ConfirmResult>;
+  /**
+   * Optional (subscription providers): backend creates an `incomplete` Stripe
+   * subscription (deferred flow) and returns a `clientSecret` + `confirmType`.
+   * Absent on the mock/one-time-only adapters.
+   */
+  createSubscription?(input: StartSubscriptionInput): Promise<SubscriptionIntent>;
+  /** Optional: poll/retrieve status after a redirect. */
+  retrieve?(intentId: string): Promise<PaymentIntent>;
+  /** Optional: paginated history for <PaymentHistory>. */
+  listPayments?(params?: { limit?: number; cursor?: string }): Promise<PaymentPage>;
+}

package/src/hooks/index.ts

@@ -0,0 +1,9 @@
+// ============================================================================
+// @djangocfg/payments — hooks barrel
+// ============================================================================
+
+export { useCheckout } from './useCheckout';
+export type { UseCheckoutResult } from './useCheckout';
+
+export { usePaymentHistory } from './usePaymentHistory';
+export type { UsePaymentHistoryProps, UsePaymentHistoryResult } from './usePaymentHistory';

package/src/hooks/useCheckout.ts

@@ -0,0 +1,160 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — useCheckout (the checkout state machine)
+// ============================================================================
+// Owns the explicit state machine over the injected adapter:
+//   idle → creating → requires_payment → processing → succeeded | failed | requires_action
+// Reads the adapter via usePaymentAdapter(); never touches a concrete SDK.
+
+import { useCallback, useRef, useState } from 'react';
+import { usePaymentAdapter } from '../context/PaymentProvider';
+import type {
+  ConfirmArgs,
+  ConfirmType,
+  CreatePaymentInput,
+  PaymentIntent,
+  PaymentStatus,
+  StartSubscriptionInput,
+} from '../domain/types';
+
+export interface UseCheckoutResult {
+  status: PaymentStatus;
+  intent: PaymentIntent | null;
+  error: string | null;
+  /** Set when the provider needs a redirect / 3DS step. */
+  nextActionUrl: string | null;
+  /** Step 1 (one-time): create the PaymentIntent → client_secret ready. */
+  start: (input: CreatePaymentInput) => Promise<void>;
+  /**
+   * Step 1 (subscription, deferred flow): create an `incomplete` Stripe
+   * subscription on the backend → client_secret + confirmType ready. `confirm`
+   * then dispatches confirmPayment vs confirmSetup automatically.
+   */
+  startSubscription: (input: StartSubscriptionInput) => Promise<void>;
+  /** 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 useCheckout(): UseCheckoutResult {
+  const adapter = usePaymentAdapter();
+
+  const [status, setStatus] = useState<PaymentStatus>('idle');
+  const [intent, setIntent] = useState<PaymentIntent | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [nextActionUrl, setNextActionUrl] = useState<string | null>(null);
+
+  // Keep the latest intent for confirm() without stale closures.
+  const intentRef = useRef<PaymentIntent | null>(null);
+  // Which confirm call step 2 must run (subscription setup vs payment). One-time
+  // checkout leaves this at 'payment'.
+  const confirmTypeRef = useRef<ConfirmType>('payment');
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setIntent(null);
+    setError(null);
+    setNextActionUrl(null);
+    intentRef.current = null;
+    confirmTypeRef.current = 'payment';
+  }, []);
+
+  const start = useCallback(
+    async (input: CreatePaymentInput) => {
+      setError(null);
+      setNextActionUrl(null);
+      setStatus('creating');
+      confirmTypeRef.current = 'payment';
+      try {
+        const created = await adapter.createIntent(input);
+        intentRef.current = created;
+        setIntent(created);
+        setStatus(created.status === 'idle' ? 'requires_payment' : created.status);
+      } catch (e) {
+        setStatus('failed');
+        setError(e instanceof Error ? e.message : 'Failed to start payment.');
+      }
+    },
+    [adapter],
+  );
+
+  const startSubscription = useCallback(
+    async (input: StartSubscriptionInput) => {
+      setError(null);
+      setNextActionUrl(null);
+      setStatus('creating');
+      if (!adapter.createSubscription) {
+        setStatus('failed');
+        setError('This payment provider does not support subscriptions.');
+        return;
+      }
+      try {
+        const sub = await adapter.createSubscription(input);
+        confirmTypeRef.current = sub.confirmType;
+        // Normalize into the same PaymentIntent shape the confirm step reads —
+        // the subscription id stands in for `id`, the deferred client_secret
+        // drives Elements exactly like a one-time intent.
+        const asIntent: PaymentIntent = {
+          id: sub.stripeSubscriptionId,
+          clientSecret: sub.clientSecret,
+          amount: 0,
+          currency: 'usd',
+          status: 'requires_payment',
+          reference: { kind: 'subscription', id: sub.stripeSubscriptionId },
+          provider: sub.provider,
+          createdAt: new Date().toISOString(),
+        };
+        intentRef.current = asIntent;
+        setIntent(asIntent);
+        setStatus('requires_payment');
+      } catch (e) {
+        setStatus('failed');
+        setError(e instanceof Error ? e.message : 'Failed to start subscription.');
+      }
+    },
+    [adapter],
+  );
+
+  const confirm = useCallback(
+    async (elementsContext?: ConfirmArgs['elementsContext'], returnUrl?: string) => {
+      const current = intentRef.current;
+      if (!current?.clientSecret) {
+        setStatus('failed');
+        setError('Payment is not ready to confirm.');
+        return;
+      }
+
+      setError(null);
+      setStatus('processing');
+      try {
+        const result = await adapter.confirm({
+          clientSecret: current.clientSecret,
+          elementsContext,
+          returnUrl,
+          confirmType: confirmTypeRef.current,
+        });
+        setStatus(result.status);
+        if (result.error) setError(result.error);
+        if (result.nextActionUrl) setNextActionUrl(result.nextActionUrl);
+
+        const updated: PaymentIntent = { ...current, status: result.status };
+        intentRef.current = updated;
+        setIntent(updated);
+      } catch (e) {
+        setStatus('failed');
+        setError(e instanceof Error ? e.message : 'Payment failed.');
+      }
+    },
+    [adapter],
+  );
+
+  const isBusy = status === 'creating' || status === 'processing';
+
+  return { status, intent, error, nextActionUrl, start, startSubscription, confirm, reset, isBusy };
+}

package/src/hooks/usePaymentHistory.ts

@@ -0,0 +1,80 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — usePaymentHistory
+// ============================================================================
+// Loads paginated payment records via the injected adapter's optional
+// listPayments(). Returns an empty list (not an error) when the adapter
+// doesn't support history.
+
+import { useCallback, useEffect, useState } from 'react';
+import { usePaymentAdapter } from '../context/PaymentProvider';
+import type { PaymentRecord } from '../domain/types';
+
+export interface UsePaymentHistoryResult {
+  records: PaymentRecord[];
+  loading: boolean;
+  error: string | null;
+  nextCursor: string | null;
+  /** Reload from the start. */
+  refresh: () => Promise<void>;
+  /** Append the next page (if any). */
+  loadMore: () => Promise<void>;
+  /** Whether the adapter supports history at all. */
+  supported: boolean;
+}
+
+export interface UsePaymentHistoryProps {
+  limit?: number;
+  /** Load on mount. Default true. */
+  autoLoad?: boolean;
+}
+
+export function usePaymentHistory(
+  { limit, autoLoad = true }: UsePaymentHistoryProps = {},
+): UsePaymentHistoryResult {
+  const adapter = usePaymentAdapter();
+  const supported = typeof adapter.listPayments === 'function';
+
+  const [records, setRecords] = useState<PaymentRecord[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [nextCursor, setNextCursor] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!adapter.listPayments) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const page = await adapter.listPayments({ limit });
+      setRecords(page.items);
+      setNextCursor(page.nextCursor ?? null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Failed to load payments.');
+    } finally {
+      setLoading(false);
+    }
+  }, [adapter, limit]);
+
+  const loadMore = useCallback(async () => {
+    if (!adapter.listPayments || !nextCursor) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const page = await adapter.listPayments({ limit, cursor: nextCursor });
+      setRecords((prev) => [...prev, ...page.items]);
+      setNextCursor(page.nextCursor ?? null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Failed to load payments.');
+    } finally {
+      setLoading(false);
+    }
+  }, [adapter, limit, nextCursor]);
+
+  useEffect(() => {
+    if (autoLoad && supported) void refresh();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoLoad, supported]);
+
+  return { records, loading, error, nextCursor, refresh, loadMore, supported };
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+// ============================================================================
+// @djangocfg/payments - Provider-agnostic React payments module (Stripe-first)
+// ============================================================================
+// 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.
+
+// Domain (types + money helpers)
+export * from './domain';
+
+// Provider context (the injected transport seam)
+export { PaymentProvider, usePaymentAdapter } from './context/PaymentProvider';
+export type { PaymentProviderProps } from './context/PaymentProvider';
+
+// Checkout guard (dialog-owned in-flight lock — gates accidental close)
+export {
+  CheckoutGuardProvider,
+  useCheckoutGuard,
+  usePublishCheckoutStatus,
+  isCheckoutLocked,
+} from './context/CheckoutGuard';
+
+// Transport adapters (mock + stripe)
+export {
+  createMockPaymentAdapter,
+  createStripeAdapter,
+} from './transport';
+export type {
+  MockAdapterConfig,
+  MockOutcome,
+  StripeAdapterConfig,
+  BackendIntent,
+  BackendSubscription,
+} from './transport';
+
+// Hooks
+export { useCheckout, usePaymentHistory } from './hooks';
+export type {
+  UseCheckoutResult,
+  UsePaymentHistoryProps,
+  UsePaymentHistoryResult,
+} from './hooks';
+
+// Components
+export {
+  CheckoutDialog,
+  CheckoutForm,
+  StripePaymentElement,
+  DEFAULT_PAYMENT_ELEMENT_OPTIONS,
+  buildStripeAppearance,
+  PaymentHistory,
+  PaymentStatusBadge,
+} from './components';
+export type {
+  CheckoutDialogProps,
+  CheckoutFormProps,
+  StripePaymentElementProps,
+  StripeElementsContext,
+  AppearanceTokens,
+  PaymentHistoryProps,
+  PaymentStatusBadgeProps,
+} from './components';

package/src/styles.css

@@ -0,0 +1,14 @@
+/**
+ * Tailwind v4 Source Detection for the Payments Package
+ *
+ * This package is consumed from source and styled with Tailwind utility
+ * classes. Tailwind v4 only generates classes it can see — consumers MUST
+ * import this entry in their global CSS (after ui-core styles) so the
+ * package's sources get scanned:
+ *
+ *   @import "@djangocfg/payments/styles";
+ *
+ * Without it, status-tint classes (e.g. the PaymentStatusBadge chips) are
+ * silently missing from the build.
+ */
+@source "../**/*.{ts,tsx}";

package/src/transport/index.ts

@@ -0,0 +1,13 @@
+// ============================================================================
+// @djangocfg/payments — transport barrel
+// ============================================================================
+
+export { createMockPaymentAdapter } from './mock-adapter';
+export type { MockAdapterConfig, MockOutcome } from './mock-adapter';
+
+export { createStripeAdapter } from './stripe-adapter';
+export type {
+  StripeAdapterConfig,
+  BackendIntent,
+  BackendSubscription,
+} from './stripe-adapter';