@pandait.tech/payment-nuvei 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+# @pandait.tech/payment-nuvei
+
+Nuvei Ecuador payment gateway adapter for Next.js. Ships:
+
+- **SDK wrapper** for Nuvei's REST endpoints (debit, verify, refund, card list/delete).
+- **Route-handler factories** for `/api/payment/*` and `/api/webhooks/nuvei` — drop-in for Next.js App Router.
+- **Payment-link primitives** (token gen, expiry helpers, anonymous-auth helper).
+- **React UI components** (`CardVisual`, `SavedCards`, `NuveiPaymentForm`) with bank-color branding driven by the package's BIN/bank-colors database.
+
+Extracted from `pauhenriques-website` (production-validated).
+
+## Status
+
+V0 — Phase 1 of `panda-commerce-kit`. Published to public npm.
+
+## Install
+
+```bash
+pnpm add @pandait.tech/payment-nuvei
+```
+
+Peer deps the consumer must install:
+
+| Peer | When required |
+|---|---|
+| `next` >= 14 | Always (handlers + UI use `next/server` and `next/script`) |
+| `react` >= 18 | Only if importing `/ui` |
+| `react-icons` >= 5 | Only if importing `/ui` |
+| `zod` >= 3.22 | Always (used by 3ds-complete handler validation) |
+| `firebase-admin` >= 12 | Always (handlers need Firestore + Auth admin SDKs) |
+| `firebase` >= 10 | Only if importing `createAnonymousAuthHelper` |
+
+## Public API
+
+```ts
+// Pure SDK functions (server-side)
+import {
+  debitWithToken,
+  verifyThreeDS,
+  refundTransaction,
+  listCards,
+  deleteCard,
+  verifyCard,
+} from "@pandait.tech/payment-nuvei";
+
+// Route handler factories
+import {
+  createChargeHandler,
+  createWebhookHandler,
+  create3dsCallbackHandler,
+  create3dsCompleteHandler,
+  create3dsTimeoutHandler,
+  createRefundHandler,
+  createInitCheckoutHandler,
+  createCardsHandler,
+  createVerifyHandler,
+  createTestChargeHandler,
+} from "@pandait.tech/payment-nuvei/handlers";
+
+// Payment-link primitives
+import {
+  generatePaymentLinkToken,
+  defaultExpiry,
+  isExpired,
+  createAnonymousAuthHelper,
+  PAYMENT_LINK_PRICE_MIN,
+  PAYMENT_LINK_PRICE_MAX,
+} from "@pandait.tech/payment-nuvei/payment-links";
+
+// React UI components
+import {
+  CardVisual,
+  SavedCards,
+  NuveiPaymentForm,
+  // utilities
+  getBinDatabase,
+  lookupBin,
+  lookupBankPalette,
+} from "@pandait.tech/payment-nuvei/ui";
+```
+
+## Handler factories — usage
+
+```ts
+// app/api/payment/charge/route.ts
+import { createChargeHandler } from "@pandait.tech/payment-nuvei/handlers";
+import { dbAdmin, authAdmin } from "@/lib/firebase";
+import { sendPaymentConfirmation, sendPaymentFailed } from "@/lib/email";
+import { getPriceDisplay } from "@/lib/pricing";
+
+export const POST = createChargeHandler({
+  firebase: { db: dbAdmin, auth: authAdmin },
+  email: { sendPaymentConfirmation, sendPaymentFailed },
+  getPriceDisplay,
+  merchantName: "Acme Shop",
+  // Required for 3DS to work. Without it, browser-info is sent to Nuvei but
+  // 3DS challenges won't initiate — the handler logs a loud error if browserInfo
+  // is provided but cloudFunctionsBaseUrl is missing.
+  cloudFunctionsBaseUrl: process.env.CLOUD_FUNCTIONS_BASE_URL,
+  rateLimit: checkRateLimit,         // optional
+  turnstile: verifyTurnstile,        // optional
+  // Optional consumer-specific side effects after order transitions to paid
+  onPaymentSucceeded: async (order) => {
+    await ensureFulfillment(order.id);
+  },
+  // Optional retry URL for payment-failed emails
+  getRetryUrl: (order) => `https://shop.example.com/checkout?orderId=${order.id}`,
+});
+```
+
+Apply the same pattern to the remaining handlers — each one is documented inline with its own `XHandlerDeps` interface.
+
+## 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.
+
+### 1. Define CSS variables in your global stylesheet
+
+Add this to your `app/globals.css` (Next.js) or equivalent, in `:root`:
+
+```css
+:root {
+  /* Brand */
+  --color-primary: #a68a63;
+  --color-primary-hover: #b89a73;
+
+  /* Text */
+  --color-text-main: #c1c4a7;
+
+  /* Surfaces */
+  --color-background: #343d2a;
+  --color-surface-elevated: #475536;
+
+  /* Borders */
+  --color-border-default: rgba(193, 196, 167, 0.20);
+  --color-border-strong: rgba(193, 196, 167, 0.35);
+  --color-border-subtle: rgba(193, 196, 167, 0.12);
+
+  /* Status */
+  --color-error: #c75c4a;
+  --color-warning: #c9a84c;
+}
+
+/* Optional: dark mode palette */
+.dark {
+  --color-primary: #b89a73;
+  /* ...override as needed */
+}
+```
+
+### 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
+"use client";
+import { SavedCards, NuveiPaymentForm } from "@pandait.tech/payment-nuvei/ui";
+
+export function PaymentMethodPicker() {
+  const [token, setToken] = useState<string | null>(null);
+  return (
+    <div>
+      <SavedCards
+        selectedToken={token}
+        onSelectCard={(card, cvc) => { /* ... */ }}
+        onAddNewCard={() => { /* show NuveiPaymentForm */ }}
+      />
+      <NuveiPaymentForm
+        uid={user.uid}
+        email={user.email}
+        onTokenSuccess={(token, cardInfo, saveCard) => { /* call /api/payment/charge */ }}
+        onTokenError={(err) => { /* ... */ }}
+      />
+    </div>
+  );
+}
+```
+
+The `NuveiPaymentForm` reads `NEXT_PUBLIC_NUVEI_CLIENT_APP_CODE`, `NEXT_PUBLIC_NUVEI_CLIENT_APP_KEY`, and `NEXT_PUBLIC_NUVEI_ENV` from your env by default. You can override per-instance with the `nuveiAppCode` / `nuveiAppKey` / `nuveiEnv` props.
+
+### Endpoints the UI components expect
+
+The components POST/GET to fixed paths because the package's handler factories are designed to mount there:
+
+| Component / call | Endpoint | Handler factory |
+|---|---|---|
+| `SavedCards` GET on mount | `/api/nuvei/cards` | `createCardsHandler` GET |
+| `SavedCards` DELETE on remove | `/api/nuvei/cards` | `createCardsHandler` DELETE |
+| `SavedCards` POST on verify | `/api/nuvei/verify` | `createVerifyHandler` POST |
+| `NuveiPaymentForm` DELETE on duplicate | `/api/nuvei/cards` | `createCardsHandler` DELETE |
+| `CardVisual` BIN lookup | `/api/bins` (overridable) | Consumer-provided JSON of `BinDatabase` |
+
+The consumer must wire those routes — each `route.ts` is one or two lines re-exporting the factory result.
+
+## 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).