@pandait.tech/payment-nuvei 0.2.1 → 0.4.0

package/README.md

@@ -141,9 +141,44 @@ A production-validated implementation of both (`threeDSCallback` + `nuveiProxy`,
 
 ## UI components — usage
 
-All `/ui` exports are client components (`"use client"`) and expect a Tailwind setup. The components consume CSS variables for theming so the same components work for every white-label client with their own branding.
+All `/ui` exports are client components (`"use client"`). They consume CSS variables for theming so the same components work for every white-label client with their own branding.
 
-### 1. Define CSS variables in your global stylesheet
+### 1. Load the styles
+
+You have two options. **Option A is recommended** — it works without Tailwind, on any Tailwind version, and doesn't require configuring your build to scan this package.
+
+**Option A — import the prebuilt stylesheet (recommended, standalone):**
+
+```ts
+// once, e.g. in app/layout.tsx or your global entry
+import "@pandait.tech/payment-nuvei/ui/styles.css";
+```
+
+This ships the exact utility classes the components use (no Tailwind Preflight/reset — it won't touch your page's base styles). You still define the brand tokens (step 2) for theming.
+
+**Option B — let your own Tailwind build the classes (Tailwind v4 users):**
+
+Skip the CSS import and instead point Tailwind at the package so it generates the classes itself. Tailwind **v4** (`@source` in your CSS):
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@pandait.tech/payment-nuvei/dist/**/*.{js,cjs}";
+```
+
+Tailwind **v3** (`content` in `tailwind.config`):
+
+```js
+export default {
+  content: [
+    "./app/**/*.{ts,tsx}",
+    "./node_modules/@pandait.tech/payment-nuvei/dist/**/*.{js,cjs}",
+  ],
+};
+```
+
+> If components render unstyled, you forgot Option A's import or Option B's `@source`/`content` entry. Option A removes that failure mode entirely.
+
+### 2. Define CSS variables in your global stylesheet
 
 Add this to your `app/globals.css` (Next.js) or equivalent, in `:root`:
 
@@ -177,22 +212,6 @@ Add this to your `app/globals.css` (Next.js) or equivalent, in `:root`:
 }
 ```
 
-### 2. Add the package to Tailwind's content config
-
-Tailwind needs to detect the arbitrary-value utility classes (e.g. `bg-[var(--color-primary)]`) inside the package's compiled output:
-
-```js
-// tailwind.config.ts
-export default {
-  content: [
-    "./app/**/*.{ts,tsx}",
-    "./src/**/*.{ts,tsx}",
-    "./node_modules/@pandait.tech/payment-nuvei/dist/**/*.{js,cjs}",
-  ],
-  // ...
-};
-```
-
 ### 3. Use the components
 
 ```tsx
@@ -235,6 +254,39 @@ The components POST/GET to fixed paths because the package's handler factories a
 
 The consumer must wire those routes — each `route.ts` is one or two lines re-exporting the factory result.
 
+`CardVisual` **degrades gracefully** if no BIN endpoint is served: it just renders without bank-specific colors. The endpoint is optional and overridable via the `binDatabaseEndpoint` prop (default `/api/bins`).
+
+## Firestore data contract
+
+The handlers read/write a single `orders` collection (plus `promotions` for coupon usage). Your Firestore schema must match these names, statuses, and fields:
+
+**`orders/{orderId}`** — the document the charge/webhook/3DS/refund handlers operate on. `dev_reference` sent to Nuvei **is** the `orderId`.
+
+| Field | Written by | Notes |
+|---|---|---|
+| `status` | all | lifecycle: `pending` → `3ds-pending` → `paid` \| `cancelled` \| `refunded`. Final statuses (`paid`/`delivered`/`shipped`) are never downgraded by the webhook. |
+| `userId` | consumer (at create) | must match the `__session` cookie uid; handlers authorize against it. |
+| `userEmail` | consumer | used for confirmation emails. |
+| `items`, `subtotal`, `vat`, `total`, `discount` | consumer | echoed into emails. |
+| `promotionId`, `couponCode` | consumer | if set, webhook/charge increment `promotions/{id}.currentUses` and write a `promotions/{id}/usages/{auto}` doc atomically. |
+| `paymentTransactionId`, `authorizationCode`, `nuveiTransactionId` | charge/webhook | Nuvei refs; `paymentTransactionId` is required for refunds. |
+| `threeDSCres`, `threeDSTransStatus` | 3DS callback / webhook | set during the challenge; cleared on completion. |
+| `verifyCalledAt` | webhook | guards the BY_CRES verify path (single-fire). |
+| `emailPending`, `missingAuthCodeFlagged` | charge/webhook | pending-email reconciliation when auth_code arrives late. |
+| `deleteCardAfterPayment`, `paymentToken` | charge | "don't save card" opt-out, honored on 3DS/webhook completion. |
+| `shippingAddress.fullName` | consumer | used as the email customer name. |
+| `refundedAt` | refund | set on successful refund. |
+
+**`promotions/{promotionId}`**: `currentUses` (incremented). **`promotions/{promotionId}/usages/{auto}`**: `{ userId, orderId, discountApplied, usedAt }`.
+
+> Business-specific side effects (course enrollment, fulfillment, paymentLink usage) live in your `onPaymentSucceeded` callback — the package never assumes those collections. **`onPaymentSucceeded` fires once, on the transition into `paid`** (idempotent across Nuvei webhook retries), but you should still make it internally idempotent as defense-in-depth.
+
+## API surface & stability
+
+Public, supported entry points: the package root (SDK), `./handlers`, `./adapters`, `./payment-links`, `./ui`, and `./ui/styles.css`. Everything else (e.g. internal `http.ts`) is private and may change without notice.
+
+Pre-1.0 the package follows semver with the caveat that **minor versions may make small breaking changes to handler `*HandlerDeps` interfaces** as the design settles. From **1.0.0** onward the public API is frozen under semver. See `CHANGELOG.md`.
+
 ## Migration from `pauhenriques-website`
 
 See per-file `Source: pauhenriques-website/...` headers throughout the package. The refactor preserves behavior with three intentional fixes vs. the original (documented in commit `4b0cb06` — coupon-reuse in webhook BY_CRES + card-delete on 3DS flows).

package/dist/handlers/index.cjs

@@ -900,7 +900,8 @@ function createWebhookHandler(deps) {
       logger.log(
         `Webhook: Order ${orderId} \u2192 ${newStatus} (status_detail: ${transaction.status_detail})`
       );
-      if (newStatus === "paid" && deps.onPaymentSucceeded) {
+      const transitionedToPaid = newStatus === "paid" && !finalStatuses.includes(currentStatus);
+      if (transitionedToPaid && deps.onPaymentSucceeded) {
         try {
           await deps.onPaymentSucceeded({ ...orderData, id: orderId });
         } catch (err) {