@pandait.tech/payment-nuvei 0.3.0 → 0.4.0

package/README.md

@@ -254,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) {