@djangocfg/payments 2.1.457

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# @djangocfg/payments
+
+Provider-agnostic React payments module. **Stripe-first**, but the package
+never depends on a concrete SDK — the host injects an adapter. Battle-tested
+in production (one-time PaymentIntent checkout + recurring subscriptions with
+Stripe Link) before extraction into `@djangocfg/*`.
+
+## The seam
+
+The host picks **one** adapter and injects it via `<PaymentProvider>`. Package
+hooks/components read it through `usePaymentAdapter()` and never import Stripe or
+a generated API client directly.
+
+```tsx
+import { PaymentProvider, createMockPaymentAdapter } from '@djangocfg/payments';
+
+// Mock-first: build & verify the whole checkout UX before any backend exists.
+<PaymentProvider adapter={createMockPaymentAdapter()}>
+  {children}
+</PaymentProvider>
+```
+
+Swapping to real Stripe is a one-line host change:
+
+```tsx
+import { loadStripe } from '@stripe/stripe-js';
+import { PaymentProvider, createStripeAdapter } from '@djangocfg/payments';
+
+const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PK!); // once, module scope
+const adapter = createStripeAdapter({
+  getStripe: () => stripePromise,
+  createIntentOnBackend: (input) => api.payments.createIntent(input), // host transport
+});
+
+<PaymentProvider adapter={adapter}>{children}</PaymentProvider>;
+```
+
+## Layering
+
+```
+domain/      pure types + money helpers   (no React, no Stripe)
+context/     <PaymentProvider> + usePaymentAdapter()  (the injected seam)
+transport/   mock-adapter | stripe-adapter  (only stripe-adapter touches @stripe/*)
+hooks/       useCheckout, usePaymentHistory  (state machine over the adapter)
+components/  CheckoutForm, StripePaymentElement, PaymentHistory, PaymentStatusBadge
+```
+
+`@stripe/*` is touched in **exactly two files** (`transport/stripe-adapter.ts`,
+`components/StripePaymentElement.tsx`) and ships as a regular dependency —
+`@stripe/stripe-js` is only the tiny CDN loader (the real SDK loads from
+js.stripe.com at runtime), and tree-shaking drops the Stripe components from
+mock-only bundles.
+
+## Styles (Tailwind v4) — required wiring
+
+This package is consumed **from source** and styled with Tailwind utility
+classes. Tailwind v4 only generates classes it can see, so the consumer's
+global CSS must import the package's styles entry (it carries the `@source`
+directive that points Tailwind at this package's sources):
+
+```css
+/* your app's globals.css */
+@import "@djangocfg/ui-core/styles/full";
+@import "@djangocfg/ui-tools/styles";
+@import "@djangocfg/payments/styles";   /* ← add this */
+```
+
+Symptom when missing: components render unstyled in spots — e.g.
+`PaymentStatusBadge` chips lose their background tint and show as plain text.
+Next.js hosts also add the package to `transpilePackages`.
+
+## Public API
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `PaymentProvider` / `usePaymentAdapter` | context | inject / read the adapter |
+| `createMockPaymentAdapter` | adapter | full fake state machine (success / declined / 3DS) |
+| `createStripeAdapter` | adapter | real Stripe (host supplies key + create-intent call) |
+| `useCheckout` | hook | `idle → creating → requires_payment → processing → succeeded\|failed\|requires_action` |
+| `usePaymentHistory` | hook | paginated history via `adapter.listPayments` |
+| `CheckoutDialog` | component | close-locked dialog shell (CheckoutGuard + ui-core Dialog); wrap your checkout body in it |
+| `CheckoutForm` | component | provider-agnostic form shell (ui-core only); inject the provider field via `paymentField` |
+| `StripePaymentElement` | component | `<Elements>` + `<PaymentElement>`; render-props the live Elements to the host |
+| `PaymentHistory` | component | DataTable of `PaymentRecord` |
+| `PaymentStatusBadge` | component | status pill on ui-core semantic tokens (success/warning/info/destructive) |
+| `toMinorUnits` / `toMajorUnits` / `formatAmount` | util | money at the boundary (amounts cross as integer minor units) |
+
+## Conventions
+
+- Source-consumed (no bundler); `main`/`types`/`exports` → `./src/index.ts`.
+- ui-core flat import; ui-tools subpath-only (`@djangocfg/ui-tools/data-table`).
+- Does **not** mount its own `<UiProviders>` — the host provides it once.
+- Locale-free: user-facing labels are props/slots (host supplies i18n).
+- Verify with `pnpm -F @djangocfg/payments check` (tsc).
+
+---
+
+## Configuration & keys
+
+Payments need **three Stripe keys**, split by where they're safe to live. Stripe
+ships them in two flavours — **test** (`sk_test_…`, `pk_test_…`) and **live**
+(`sk_live_…`, `pk_live_…`) — with the **same variable names**; only the values
+differ. Bring up **test first**, verify end-to-end, then switch to live.
+
+| Key | Prefix | Lives in | Exposed to browser? |
+|---|---|---|---|
+| Secret key | `sk_test_…` / `sk_live_…` | **Backend only** (`STRIPE__SECRET_KEY`) | ❌ never |
+| Webhook signing secret | `whsec_…` | **Backend only** (`STRIPE__WEBHOOK_SECRET`) | ❌ never |
+| Publishable key | `pk_test_…` / `pk_live_…` | Backend + Frontend | ✅ safe (it's public by design) |
+
+> The publishable key is typically returned to the browser by the backend's
+> create-checkout response (`publishable_key`) and/or read from
+> `NEXT_PUBLIC_STRIPE_PK`. The secret and webhook keys **never** leave the server.
+
+### Backend (Django) — `STRIPE__*`
+
+This package is frontend-only; it pairs with any Django backend that creates
+PaymentIntents (a built-in `django_cfg.apps.payments` module is planned — see
+`@plans/plan-payments-v1`). Paths below are the reference host's; adjust env
+names to your backend. Set the keys server-side (git-ignored secrets file):
+
+```dotenv
+# --- Stripe (test) ---
+STRIPE__SECRET_KEY=sk_test_xxx
+STRIPE__PUBLISHABLE_KEY=pk_test_xxx
+STRIPE__WEBHOOK_SECRET=whsec_xxx          # comma-separate to rotate: whsec_new,whsec_old
+
+# --- Stripe (live) — same names, live values ---
+# STRIPE__SECRET_KEY=sk_live_xxx
+# STRIPE__PUBLISHABLE_KEY=pk_live_xxx
+# STRIPE__WEBHOOK_SECRET=whsec_live_xxx
+```
+
+### Frontend — `NEXT_PUBLIC_STRIPE_PK`
+
+```dotenv
+# your Next.js app .env  (test → pk_test_…, live → pk_live_…)
+NEXT_PUBLIC_STRIPE_PK=pk_test_xxx
+```
+
+With **no** `NEXT_PUBLIC_STRIPE_PK` set, the host falls back to the **mock
+adapter** — the whole checkout UX still renders (no real charge), which is the
+mock-first dev path.
+
+> ⚠️ **Security:** the secret (`sk_`) and webhook (`whsec_`) keys must live in a
+> **git-ignored** file or a secret manager — never commit them. If the project's
+> `.env*` files are tracked by git, add the secrets file to `.gitignore` and
+> `git rm --cached` it first. Only `pk_…` (publishable) is safe in tracked config.
+
+## Stripe setup (test mode)
+
+1. **Get test keys** — Stripe Dashboard → Developers → API keys (toggle "test
+   mode"): copy `pk_test_…` and `sk_test_…`.
+2. **Webhook** — for local dev, use the Stripe CLI (it prints a `whsec_…` signing
+   secret for the forwarded endpoint):
+   ```bash
+   stripe login
+   stripe listen --forward-to localhost:8000/<your-webhook-path>/
+   # → copy the "whsec_…" it prints into STRIPE__WEBHOOK_SECRET
+   ```
+   For a deployed env, create the endpoint in Dashboard → Developers → Webhooks
+   pointing at your backend's webhook URL and subscribe to:
+   `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`.
+3. **Test a payment** — open an order, hit **Pay**, use a Stripe **test card**
+   (`4242 4242 4242 4242`, any future expiry/CVC). Trigger events directly with:
+   ```bash
+   stripe trigger payment_intent.succeeded
+   stripe events resend <evt_id>   # test idempotency / replay
+   ```
+
+## Going live
+
+1. Switch all three `STRIPE__*` values to their `…_live_…` counterparts and
+   `NEXT_PUBLIC_STRIPE_PK` to `pk_live_…`.
+2. Create a **live** webhook endpoint in the Dashboard (live mode has its own
+   signing secret — set it in `STRIPE__WEBHOOK_SECRET`).
+3. Register your domain for Apple Pay / Google Pay if you enable wallets.
+4. Do a small real charge to confirm end-to-end.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@djangocfg/payments",
+  "version": "2.1.457",
+  "description": "Provider-agnostic React payments module (Stripe-first): checkout state machine, Payment Element wrapper, close-guard context, mock adapter for keyless development",
+  "keywords": [
+    "payments",
+    "stripe",
+    "checkout",
+    "subscriptions",
+    "payment-element",
+    "react",
+    "django",
+    "typescript",
+    "hooks"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "packages/payments"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    },
+    "./styles": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@stripe/react-stripe-js": "^6.7.0",
+    "@stripe/stripe-js": "^9.9.0"
+  },
+  "peerDependencies": {
+    "@djangocfg/ui-core": "^2.1.457",
+    "@djangocfg/ui-tools": "^2.1.457",
+    "lucide-react": "^0.545.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "peerDependenciesMeta": {
+    "@djangocfg/ui-tools": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.457",
+    "@djangocfg/ui-core": "^2.1.457",
+    "@djangocfg/ui-tools": "^2.1.457",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "lucide-react": "0.545.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/CheckoutDialog.tsx

@@ -0,0 +1,122 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — CheckoutDialog
+// ============================================================================
+// The host-agnostic dialog shell around a checkout body. Every consumer used
+// to re-write this glue (see cmdop's PaymentCheckoutShell): a Dialog whose
+// close paths (Esc / overlay-click / ×) are gated while a charge is in flight,
+// wired to the CheckoutGuard context that the inner CheckoutForm publishes
+// into via usePublishCheckoutStatus.
+//
+// Layout invariant: the body is height-capped and scrolls INSIDE the dialog
+// (header stays pinned), so the Stripe Payment Element never clips on small
+// viewports.
+//
+// The children are the host's checkout body — typically the intent-creation
+// state machine ending in <CheckoutForm> (with <StripePaymentElement> on the
+// real path). This shell owns open/close + the in-flight lock, nothing else.
+
+import { type ReactNode } from 'react';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@djangocfg/ui-core';
+
+import { CheckoutGuardProvider, useCheckoutGuard } from '../context/CheckoutGuard';
+
+export interface CheckoutDialogProps {
+  open: boolean;
+  /** Called on any allowed close path (Esc / overlay / ×). */
+  onClose: () => void;
+  /** Dialog heading. Host supplies translated text. */
+  title?: ReactNode;
+  /**
+   * Accessible description (rendered sr-only). Screen readers announce it;
+   * sighted users see the checkout body itself.
+   */
+  description?: ReactNode;
+  /** Extra classes for the DialogContent (e.g. a wider max-w). */
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * Checkout dialog shell: `CheckoutGuardProvider` + close-locked `Dialog`.
+ * While the inner form reports `processing` / `requires_action`, every close
+ * path is disabled and the × button is hidden — tearing down the form
+ * mid-confirm would orphan the payment intent.
+ */
+export function CheckoutDialog({
+  open,
+  onClose,
+  title = 'Checkout',
+  description = 'Complete your payment.',
+  className,
+  children,
+}: CheckoutDialogProps) {
+  return (
+    <CheckoutGuardProvider>
+      <CheckoutDialogShell
+        open={open}
+        onClose={onClose}
+        title={title}
+        description={description}
+        className={className}
+      >
+        {children}
+      </CheckoutDialogShell>
+    </CheckoutGuardProvider>
+  );
+}
+
+/** Inner shell — must live under the provider to read the guard. */
+function CheckoutDialogShell({
+  open,
+  onClose,
+  title,
+  description,
+  className,
+  children,
+}: CheckoutDialogProps) {
+  const { canClose } = useCheckoutGuard();
+
+  const handleOpenChange = (next: boolean) => {
+    if (!next && canClose) onClose();
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent
+        className={[
+          'flex max-h-[88vh] flex-col gap-0 sm:max-w-md',
+          className,
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        closeButton={canClose ? undefined : false}
+        onEscapeKeyDown={(e) => {
+          if (!canClose) e.preventDefault();
+        }}
+        onInteractOutside={(e) => {
+          if (!canClose) e.preventDefault();
+        }}
+      >
+        <DialogHeader className="pb-4">
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription className="sr-only">{description}</DialogDescription>
+        </DialogHeader>
+
+        {/* Scroll container: negative margin + padding keeps the scrollbar
+            out of the content gutter. */}
+        <div className="-mr-2 min-h-0 flex-1 overflow-y-auto overscroll-contain pr-2">
+          {children}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/components/CheckoutForm.tsx

@@ -0,0 +1,213 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — CheckoutForm (provider-agnostic form shell)
+// ============================================================================
+// ui-core only — no Stripe import. The provider's payment field (Stripe
+// PaymentElement, or a mock input) is injected via the `paymentField` slot.
+// Drives the checkout via useCheckout(); the host supplies labels (i18n).
+//
+// Stripe-like composition: order summary on top → divider → payment field →
+// one prominent CTA → secure footer. Clean hierarchy, lots of air.
+
+import React, { useCallback } from 'react';
+import { Alert, AlertDescription, Button, Separator, Spinner } from '@djangocfg/ui-core';
+import { Lock, ShieldCheck, AlertTriangle } from 'lucide-react';
+import { useCheckout, type UseCheckoutResult } from '../hooks/useCheckout';
+import { usePublishCheckoutStatus, isCheckoutLocked } from '../context/CheckoutGuard';
+import { formatAmount } from '../domain/money';
+import type { Currency, MinorUnits, PaymentReference } from '../domain/types';
+
+export interface CheckoutFormProps {
+  amount: MinorUnits;
+  currency: Currency;
+  reference: PaymentReference;
+  /** Summary line-item title (e.g. the order description). Renders the top block. */
+  summaryTitle?: string;
+  /** Secondary summary line (e.g. "Billed monthly"). */
+  summaryNote?: string;
+  /** Slot for the provider's payment field (Stripe PaymentElement / mock input). */
+  paymentField?: React.ReactNode;
+  /**
+   * Mock mode (no real Stripe key). Renders a friendly `4242…` placeholder when
+   * no `paymentField` is supplied. On the real Stripe path this MUST be false so
+   * an absent slot never falls through to the mock stub (that was the duplicate
+   * card block under the real PaymentElement).
+   */
+  isMock?: boolean;
+  /**
+   * Confirm payload passed straight to the adapter (e.g. a Stripe Elements
+   * instance). For the mock adapter this can be undefined.
+   */
+  elementsContext?: unknown;
+  /** Where the provider returns after a redirect (3DS / hosted). */
+  returnUrl?: string;
+  onSuccess?: (intentId: string) => void;
+  onFailure?: (error: string) => void;
+  onCancel?: () => void;
+  /** Default: `Pay {amount}`. */
+  submitLabel?: string;
+  cancelLabel?: string;
+  /** Field label above the payment input. Default "Card". */
+  fieldLabel?: string;
+  /** Locale for amount formatting. */
+  locale?: string;
+  className?: string;
+  /**
+   * Share the PARENT's checkout state machine instead of creating a private one.
+   * Pass this when the parent already created the intent/subscription (via
+   * `start` / `startSubscription`) so the form confirms THAT intent rather than
+   * spinning up a second `useCheckout` (which would create a duplicate
+   * intent/subscription on submit). When omitted, the form is self-driving and
+   * lazily creates a one-time intent on submit (legacy one-time path).
+   */
+  checkout?: UseCheckoutResult;
+}
+
+export function CheckoutForm({
+  amount,
+  currency,
+  reference: _reference,
+  summaryTitle,
+  summaryNote,
+  paymentField,
+  isMock = false,
+  elementsContext,
+  returnUrl,
+  onSuccess,
+  onFailure,
+  onCancel,
+  submitLabel,
+  cancelLabel = 'Cancel',
+  fieldLabel = 'Card',
+  locale,
+  className,
+  checkout,
+}: CheckoutFormProps) {
+  // Use the parent's shared machine when provided; else self-drive (one-time).
+  // Hooks run unconditionally (Rules of Hooks); we just pick which result wins.
+  const ownCheckout = useCheckout();
+  const { status, error, isBusy, start, confirm, intent } = checkout ?? ownCheckout;
+  const isShared = Boolean(checkout);
+
+  // Publish status into the dialog's CheckoutGuard so the shell can block
+  // Esc / overlay-click / × while a charge is in flight (no-op if there's no
+  // guard, e.g. a standalone form).
+  usePublishCheckoutStatus(status);
+  const locked = isCheckoutLocked(status);
+
+  const formatted = formatAmount(amount, currency, locale);
+  const isDone = status === 'succeeded';
+  const needsAction = status === 'requires_action';
+
+  const handlePay = useCallback(
+    async (e: React.FormEvent) => {
+      e.preventDefault();
+      // Self-driving mode only: lazily create the one-time intent on first
+      // submit. In shared mode the parent already created the intent/subscription
+      // (start / startSubscription) — creating another here would duplicate it,
+      // so we go straight to confirm.
+      if (!isShared && !intent) {
+        await start({ amount, currency, reference: _reference });
+      }
+      await confirm(elementsContext, returnUrl);
+    },
+    [isShared, intent, start, amount, currency, _reference, confirm, elementsContext, returnUrl],
+  );
+
+  // Fire host callbacks on terminal states.
+  React.useEffect(() => {
+    if (status === 'succeeded' && intent) onSuccess?.(intent.id);
+    if (status === 'failed' && error) onFailure?.(error);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [status]);
+
+  return (
+    <form onSubmit={handlePay} className={className}>
+      <div className="space-y-5">
+        {/* Summary block — what you're paying for + the amount. */}
+        {summaryTitle ? (
+          <div className="space-y-1">
+            <p className="text-foreground text-sm font-medium leading-snug">{summaryTitle}</p>
+            <p className="text-muted-foreground text-sm">
+              <span className="text-foreground font-semibold">{formatted}</span>
+              {summaryNote ? <span> · {summaryNote}</span> : null}
+            </p>
+          </div>
+        ) : null}
+
+        {summaryTitle ? <Separator /> : null}
+
+        {/* Payment field. No mini "CARD" label — the accordion self-labels its
+            rows, so the extra uppercase caption was redundant chrome (plan7). */}
+        <div>
+          {paymentField ? (
+            <div className="min-h-[40px]">{paymentField}</div>
+          ) : isMock ? (
+            <div className="space-y-2">
+              <p className="text-muted-foreground text-xs font-medium uppercase tracking-wide">
+                {fieldLabel}
+              </p>
+              <div className="border-border bg-muted/30 text-muted-foreground flex h-10 items-center rounded-md border px-3 text-sm">
+                4242 4242 4242 4242
+              </div>
+            </div>
+          ) : null}
+        </div>
+
+        {error ? (
+          <Alert variant="destructive">
+            <AlertDescription>{error}</AlertDescription>
+          </Alert>
+        ) : null}
+
+        {needsAction ? (
+          <Alert>
+            <AlertTriangle className="h-4 w-4" />
+            <AlertDescription>
+              Additional authentication is required to complete this payment.
+            </AlertDescription>
+          </Alert>
+        ) : null}
+
+        {/* Primary CTA. */}
+        <Button type="submit" size="lg" className="w-full" disabled={isBusy || isDone}>
+          {isBusy ? (
+            <>
+              <Spinner className="mr-1.5 h-4 w-4" />
+              Processing…
+            </>
+          ) : isDone ? (
+            <>
+              <ShieldCheck className="mr-1.5 h-4 w-4" />
+              Paid
+            </>
+          ) : (
+            (submitLabel ?? `Pay ${formatted}`)
+          )}
+        </Button>
+
+        {/* Hide the dismiss control entirely while a charge is in flight — no
+            competing action, and closing now would orphan the intent. */}
+        {onCancel && !locked ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground w-full"
+            onClick={onCancel}
+            disabled={isBusy}
+          >
+            {cancelLabel}
+          </Button>
+        ) : null}
+
+        {/* Secure footer. */}
+        <p className="text-muted-foreground flex items-center justify-center gap-1.5 text-xs">
+          <Lock className="h-3 w-3" />
+          Secure payment · Powered by Stripe
+        </p>
+      </div>
+    </form>
+  );
+}