@pandait.tech/payment-nuvei 0.5.0 → 1.0.1

package/README.md

@@ -110,11 +110,17 @@ export const POST = createChargeHandler({
 
 Apply the same pattern to the remaining handlers — each one is documented inline with its own `XHandlerDeps` interface.
 
-### Securing the webhook (important)
+### The webhook is OPTIONAL — and if you expose it, secure it
 
-Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must be protected with a shared secret — otherwise anyone who knows an `orderId` could POST a fake "paid" notification.
+First, set expectations correctly:
 
-1. Set a secret and pass it to the handler (or via `NUVEI_WEBHOOK_SECRET`):
+- **Payments are confirmed by the synchronous `/debit` response** (`createChargeHandler` reads `transaction.status === "success" && status_detail === 3`), plus the 3DS `term_url` callback + `verify` polling for challenged transactions. **That path fully confirms a payment without any webhook.**
+- Paymentez's transaction-notification **callback** (`developers.paymentez.com/api/#webhook`) is an **optional, redundant async channel** — Paymentez POSTs transaction status to a URL you register *with Paymentez during integration* (there is no documented self-serve dashboard; for many accounts it is simply never wired up). In a real production consumer we observed Paymentez never calling it at all.
+- So `createWebhookHandler` is a reconciliation backstop you can mount **if** your Paymentez account is configured to notify it. It is **not required** to take payments.
+
+Because the endpoint is nonetheless a **public POST** route, if you mount it you must authenticate it — otherwise anyone who knows an `orderId` could POST a fake "paid" notification (`status_detail: 3`) and mark an order paid. Paymentez callbacks are **not signed**, so use a shared secret:
+
+1. Pass a secret to the handler (or via `NUVEI_WEBHOOK_SECRET`):
 
    ```ts
    export const POST = createWebhookHandler({
@@ -125,7 +131,7 @@ Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must
    });
    ```
 
-2. In the **Nuvei dashboard**, configure your DMN/callback URL with the secret as a query param:
+2. If/when you register the notification URL with Paymentez, append the secret as a query param:
 
    ```
    https://your-shop.com/api/webhooks/nuvei?key=YOUR_SECRET
@@ -133,9 +139,9 @@ Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must
 
    (The secret is also accepted as the `x-webhook-key` header.)
 
-Requests without a matching key get `401` and are not processed (constant-time compared). If `webhookSecret` is **unset**, the handler still processes but logs a loud warning — treat that as not-production-ready.
+Requests without a matching key get `401` and are not processed (constant-time compared). If `webhookSecret` is **unset**, the handler still processes but logs a loud warning. If you never register the URL with Paymentez, setting the secret simply seals the endpoint (everything → 401), which is a safe default.
 
-> `onPaymentSucceeded` fires once, on the transition into `paid` (idempotent across Nuvei's webhook retries).
+> `onPaymentSucceeded` fires once, on the transition into `paid` (idempotent across retries).
 
 ## Hosting & deployment (3DS callback + Nuvei egress)
 
@@ -312,7 +318,22 @@ The handlers read/write a single `orders` collection (plus `promotions` for coup
 
 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`.
+**As of `1.0.0` the public API is frozen under semver** — breaking changes to the
+exported factories, their `*HandlerDeps` interfaces, the SDK functions, or the UI
+component props require a major version bump. See `CHANGELOG.md`.
+
+Design notes consumers should know:
+
+- **Order shape is generic.** `MinimalOrder` extends `Record<string, unknown>` and
+  declares only fields the package itself reads/writes. Your business-specific
+  order fields are yours to read off the order inside your callbacks
+  (`onPaymentSucceeded`, `validateCustomOrder`, `getRetryUrl`) — narrow them there.
+- **Payment links are primitives only.** The package ships token/expiry/price-bound
+  helpers; the payment-link *document shape* (what it points to) is yours to define.
+- **The webhook secret is optional but strongly recommended.** It's left optional so
+  the package never forces a specific webhook-URL scheme, but an unconfigured
+  webhook is forgeable — always set `webhookSecret` in production (see "Securing the
+  webhook" above).
 
 ## Migration from `pauhenriques-website`
 

package/dist/handlers/index.d.cts

@@ -23,10 +23,9 @@ interface MinimalOrder extends FirestoreData {
     shippingAddress?: {
         fullName?: string;
     } & FirestoreData;
+    /** Optional note shown to the customer post-purchase; echoed into the
+     *  confirmation email when present. */
     postPurchaseNote?: string;
-    paymentLinkId?: string;
-    tallerId?: string;
-    courseId?: string;
     /** Set by charge.ts when the user opted out of saving the card AND the order
      *  enters an intermediate status (3ds-pending / otp-pending). The downstream
      *  handler that finalizes the payment (3ds-complete, webhook BY_CRES) reads

package/dist/handlers/index.d.ts

@@ -23,10 +23,9 @@ interface MinimalOrder extends FirestoreData {
     shippingAddress?: {
         fullName?: string;
     } & FirestoreData;
+    /** Optional note shown to the customer post-purchase; echoed into the
+     *  confirmation email when present. */
     postPurchaseNote?: string;
-    paymentLinkId?: string;
-    tallerId?: string;
-    courseId?: string;
     /** Set by charge.ts when the user opted out of saving the card AND the order
      *  enters an intermediate status (3ds-pending / otp-pending). The downstream
      *  handler that finalizes the payment (3ds-complete, webhook BY_CRES) reads

package/dist/payment-links/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/payment-links/paymentLink.ts","../../src/payment-links/anonymousAuth.ts"],"names":["randomBytes"],"mappings":";;;;;AAkCO,IAAM,sBAAA,GAAyB;AAC/B,IAAM,sBAAA,GAAyB;AAC/B,IAAM,oCAAA,GAAuC;AAC7C,IAAM,gCAAA,GAAmC;AAEzC,SAAS,wBAAA,GAAmC;AAGjD,EAAA,OAAOA,mBAAY,EAAE,CAAA,CAClB,QAAA,CAAS,QAAQ,EACjB,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,QAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,OAAA,CAAQ,QAAQ,EAAE,CAAA;AACvB;AAEO,SAAS,aAAA,GAAsB;AACpC,EAAA,MAAM,CAAA,uBAAQ,IAAA,EAAK;AACnB,EAAA,CAAA,CAAE,OAAA,CAAQ,CAAA,CAAE,OAAA,EAAQ,GAAI,gCAAgC,CAAA;AACxD,EAAA,OAAO,CAAA;AACT;AAEO,SAAS,UAAU,SAAA,EAAmC;AAC3D,EAAA,MAAM,MAAM,OAAO,SAAA,KAAc,QAAA,GAAW,SAAA,GAAY,UAAU,WAAA,EAAY;AAC9E,EAAA,OAAO,IAAI,IAAA,CAAK,GAAG,EAAE,OAAA,EAAQ,GAAI,KAAK,GAAA,EAAI;AAC5C;;;ACrBO,SAAS,0BAA0B,IAAA,EAA+B;AACvE,EAAA,MAAM,eAAA,GAAkB,KAAK,eAAA,IAAmB,mBAAA;AAEhD,EAAA,OAAO,eAAe,uBACpB,YAAA,EACe;AACf,IAAA,IAAI,IAAA,GAAO,YAAA,IAAgB,IAAA,CAAK,IAAA,CAAK,WAAA;AAErC,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,MAAM,EAAE,iBAAA,EAAkB,GAAI,MAAM,OAAO,eAAe,CAAA;AAC1D,MAAA,MAAM,IAAA,GAAO,MAAM,iBAAA,CAAkB,IAAA,CAAK,IAAI,CAAA;AAC9C,MAAA,IAAA,GAAO,IAAA,CAAK,IAAA;AAAA,IACd;AAEA,IAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,UAAA;AAAA;AAAA,MAA8B;AAAA,KAAI;AAC7D,IAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,eAAA,EAAiB;AAAA,MACvC,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA,EAAmB;AAAA,MAC9C,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,SAAS;AAAA,KACjC,CAAA;AAED,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,oCAAA,EAAoC,GAAA,CAAI,MAAM,CAAA,CAAA,CAAG,CAAA;AAAA,IACnE;AAEA,IAAA,OAAO,IAAA;AAAA,EACT,CAAA;AACF","file":"index.cjs","sourcesContent":["import { randomBytes } from \"crypto\";\n\nexport interface PaymentLinkInput {\n  price: number;\n  label?: string;\n  publicLabel?: string;\n  expiresAt: Date;\n  tallerId: string;\n  notes?: string;\n}\n\nexport interface PaymentLink {\n  id: string;\n  token: string;\n  tallerId: string;\n  price: number;\n  // Nombre interno (solo admin) — referencia para identificar el link en la\n  // tabla y en el dashboard. NUNCA se muestra al cliente.\n  label: string | null;\n  // Etiqueta promocional visible al cliente en /pago/t/[token] junto al\n  // emoji 🔥 (ej. \"Promo amigas\", \"Última semana\"). Opcional.\n  publicLabel: string | null;\n  notes: string | null;\n  active: boolean;\n  expiresAt: string;\n  createdByUid: string;\n  createdByEmail: string | null;\n  createdByName: string | null;\n  timesPaid: number;\n  lastPaidAt: string | null;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport const PAYMENT_LINK_PRICE_MIN = 1;\nexport const PAYMENT_LINK_PRICE_MAX = 2000;\nexport const PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD = 200;\nexport const PAYMENT_LINK_DEFAULT_EXPIRY_DAYS = 30;\n\nexport function generatePaymentLinkToken(): string {\n  // 12 bytes → 16 chars base64url, suficientemente largo para evitar adivinanza\n  // (2^96 combinaciones) y lo bastante corto para un URL amigable.\n  return randomBytes(12)\n    .toString(\"base64\")\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/g, \"\");\n}\n\nexport function defaultExpiry(): Date {\n  const d = new Date();\n  d.setDate(d.getDate() + PAYMENT_LINK_DEFAULT_EXPIRY_DAYS);\n  return d;\n}\n\nexport function isExpired(expiresAt: Date | string): boolean {\n  const iso = typeof expiresAt === \"string\" ? expiresAt : expiresAt.toISOString();\n  return new Date(iso).getTime() < Date.now();\n}\n","// Source: pauhenriques-website/src/lib/pago-link/anonymousAuth.ts\n// Phase 1.4: refactored to factory pattern.\n//\n// Client-only helper used by guest checkout flows (e.g. payment links) that\n// need a Firebase __session cookie to call the package's POST handlers\n// (charge, 3ds-complete, refund, etc.) — those handlers verify a session\n// cookie, so guests must first sign in anonymously.\n//\n// The two consumer touchpoints (Firebase client Auth instance and session\n// endpoint path) are injected as deps rather than imported from a fixed\n// module path, so the helper works in any Next.js app regardless of how\n// the consumer initializes Firebase.\n\nimport type { Auth, User } from \"firebase/auth\";\n\n/** Dependencies for the anonymous-auth helper factory. */\nexport interface AnonymousAuthHelperDeps {\n  /** Firebase client Auth instance. Must be the same instance used by the consumer's app for sign-in state to stay consistent across calls. */\n  auth: Auth;\n  /** URL where the helper POSTs `{ idToken }` to exchange the Firebase ID token for a server-side session cookie. The endpoint must respond 2xx on success. Default: \"/api/auth/session\". */\n  sessionEndpoint?: string;\n}\n\n/**\n * Creates an `ensureAnonymousSession(existingUser)` function that signs in\n * anonymously (if not already signed in) and establishes a server-side\n * session cookie. Idempotent: if a user is already signed in, refreshes\n * the cookie with the current user.\n *\n * Usage:\n *\n *   const ensureAnonymousSession = createAnonymousAuthHelper({\n *     auth: clientAuth,\n *     sessionEndpoint: \"/api/auth/session\",\n *   });\n *   const user = await ensureAnonymousSession(currentUser);\n */\nexport function createAnonymousAuthHelper(deps: AnonymousAuthHelperDeps) {\n  const sessionEndpoint = deps.sessionEndpoint ?? \"/api/auth/session\";\n\n  return async function ensureAnonymousSession(\n    existingUser: User | null,\n  ): Promise<User> {\n    let user = existingUser ?? deps.auth.currentUser;\n\n    if (!user) {\n      const { signInAnonymously } = await import(\"firebase/auth\");\n      const cred = await signInAnonymously(deps.auth);\n      user = cred.user;\n    }\n\n    const idToken = await user.getIdToken(/* forceRefresh */ true);\n    const res = await fetch(sessionEndpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ idToken }),\n    });\n\n    if (!res.ok) {\n      throw new Error(`No se pudo establecer la sesión (${res.status})`);\n    }\n\n    return user;\n  };\n}\n"]}
+{"version":3,"sources":["../../src/payment-links/paymentLink.ts","../../src/payment-links/anonymousAuth.ts"],"names":["randomBytes"],"mappings":";;;;;AAQO,IAAM,sBAAA,GAAyB;AAC/B,IAAM,sBAAA,GAAyB;AAC/B,IAAM,oCAAA,GAAuC;AAC7C,IAAM,gCAAA,GAAmC;AAEzC,SAAS,wBAAA,GAAmC;AAGjD,EAAA,OAAOA,mBAAY,EAAE,CAAA,CAClB,QAAA,CAAS,QAAQ,EACjB,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,QAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,OAAA,CAAQ,QAAQ,EAAE,CAAA;AACvB;AAEO,SAAS,aAAA,GAAsB;AACpC,EAAA,MAAM,CAAA,uBAAQ,IAAA,EAAK;AACnB,EAAA,CAAA,CAAE,OAAA,CAAQ,CAAA,CAAE,OAAA,EAAQ,GAAI,gCAAgC,CAAA;AACxD,EAAA,OAAO,CAAA;AACT;AAEO,SAAS,UAAU,SAAA,EAAmC;AAC3D,EAAA,MAAM,MAAM,OAAO,SAAA,KAAc,QAAA,GAAW,SAAA,GAAY,UAAU,WAAA,EAAY;AAC9E,EAAA,OAAO,IAAI,IAAA,CAAK,GAAG,EAAE,OAAA,EAAQ,GAAI,KAAK,GAAA,EAAI;AAC5C;;;ACKO,SAAS,0BAA0B,IAAA,EAA+B;AACvE,EAAA,MAAM,eAAA,GAAkB,KAAK,eAAA,IAAmB,mBAAA;AAEhD,EAAA,OAAO,eAAe,uBACpB,YAAA,EACe;AACf,IAAA,IAAI,IAAA,GAAO,YAAA,IAAgB,IAAA,CAAK,IAAA,CAAK,WAAA;AAErC,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,MAAM,EAAE,iBAAA,EAAkB,GAAI,MAAM,OAAO,eAAe,CAAA;AAC1D,MAAA,MAAM,IAAA,GAAO,MAAM,iBAAA,CAAkB,IAAA,CAAK,IAAI,CAAA;AAC9C,MAAA,IAAA,GAAO,IAAA,CAAK,IAAA;AAAA,IACd;AAEA,IAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,UAAA;AAAA;AAAA,MAA8B;AAAA,KAAI;AAC7D,IAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,eAAA,EAAiB;AAAA,MACvC,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA,EAAmB;AAAA,MAC9C,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,SAAS;AAAA,KACjC,CAAA;AAED,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,oCAAA,EAAoC,GAAA,CAAI,MAAM,CAAA,CAAA,CAAG,CAAA;AAAA,IACnE;AAEA,IAAA,OAAO,IAAA;AAAA,EACT,CAAA;AACF","file":"index.cjs","sourcesContent":["import { randomBytes } from \"crypto\";\n\n// NOTE: this module intentionally exposes only generic payment-link PRIMITIVES\n// (token generation, expiry helpers, price bounds). The shape of a payment link\n// document — what it points to (a workshop, a course, a session…), its labels,\n// usage counters, etc. — is consumer-specific, so consumers define their own\n// PaymentLink type and build their own resolver on top of these primitives.\n\nexport const PAYMENT_LINK_PRICE_MIN = 1;\nexport const PAYMENT_LINK_PRICE_MAX = 2000;\nexport const PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD = 200;\nexport const PAYMENT_LINK_DEFAULT_EXPIRY_DAYS = 30;\n\nexport function generatePaymentLinkToken(): string {\n  // 12 bytes → 16 chars base64url, suficientemente largo para evitar adivinanza\n  // (2^96 combinaciones) y lo bastante corto para un URL amigable.\n  return randomBytes(12)\n    .toString(\"base64\")\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/g, \"\");\n}\n\nexport function defaultExpiry(): Date {\n  const d = new Date();\n  d.setDate(d.getDate() + PAYMENT_LINK_DEFAULT_EXPIRY_DAYS);\n  return d;\n}\n\nexport function isExpired(expiresAt: Date | string): boolean {\n  const iso = typeof expiresAt === \"string\" ? expiresAt : expiresAt.toISOString();\n  return new Date(iso).getTime() < Date.now();\n}\n","// Source: pauhenriques-website/src/lib/pago-link/anonymousAuth.ts\n// Phase 1.4: refactored to factory pattern.\n//\n// Client-only helper used by guest checkout flows (e.g. payment links) that\n// need a Firebase __session cookie to call the package's POST handlers\n// (charge, 3ds-complete, refund, etc.) — those handlers verify a session\n// cookie, so guests must first sign in anonymously.\n//\n// The two consumer touchpoints (Firebase client Auth instance and session\n// endpoint path) are injected as deps rather than imported from a fixed\n// module path, so the helper works in any Next.js app regardless of how\n// the consumer initializes Firebase.\n\nimport type { Auth, User } from \"firebase/auth\";\n\n/** Dependencies for the anonymous-auth helper factory. */\nexport interface AnonymousAuthHelperDeps {\n  /** Firebase client Auth instance. Must be the same instance used by the consumer's app for sign-in state to stay consistent across calls. */\n  auth: Auth;\n  /** URL where the helper POSTs `{ idToken }` to exchange the Firebase ID token for a server-side session cookie. The endpoint must respond 2xx on success. Default: \"/api/auth/session\". */\n  sessionEndpoint?: string;\n}\n\n/**\n * Creates an `ensureAnonymousSession(existingUser)` function that signs in\n * anonymously (if not already signed in) and establishes a server-side\n * session cookie. Idempotent: if a user is already signed in, refreshes\n * the cookie with the current user.\n *\n * Usage:\n *\n *   const ensureAnonymousSession = createAnonymousAuthHelper({\n *     auth: clientAuth,\n *     sessionEndpoint: \"/api/auth/session\",\n *   });\n *   const user = await ensureAnonymousSession(currentUser);\n */\nexport function createAnonymousAuthHelper(deps: AnonymousAuthHelperDeps) {\n  const sessionEndpoint = deps.sessionEndpoint ?? \"/api/auth/session\";\n\n  return async function ensureAnonymousSession(\n    existingUser: User | null,\n  ): Promise<User> {\n    let user = existingUser ?? deps.auth.currentUser;\n\n    if (!user) {\n      const { signInAnonymously } = await import(\"firebase/auth\");\n      const cred = await signInAnonymously(deps.auth);\n      user = cred.user;\n    }\n\n    const idToken = await user.getIdToken(/* forceRefresh */ true);\n    const res = await fetch(sessionEndpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ idToken }),\n    });\n\n    if (!res.ok) {\n      throw new Error(`No se pudo establecer la sesión (${res.status})`);\n    }\n\n    return user;\n  };\n}\n"]}

package/dist/payment-links/index.d.cts

@@ -1,31 +1,5 @@
 import { Auth, User } from 'firebase/auth';
 
-interface PaymentLinkInput {
-    price: number;
-    label?: string;
-    publicLabel?: string;
-    expiresAt: Date;
-    tallerId: string;
-    notes?: string;
-}
-interface PaymentLink {
-    id: string;
-    token: string;
-    tallerId: string;
-    price: number;
-    label: string | null;
-    publicLabel: string | null;
-    notes: string | null;
-    active: boolean;
-    expiresAt: string;
-    createdByUid: string;
-    createdByEmail: string | null;
-    createdByName: string | null;
-    timesPaid: number;
-    lastPaidAt: string | null;
-    createdAt: string;
-    updatedAt: string;
-}
 declare const PAYMENT_LINK_PRICE_MIN = 1;
 declare const PAYMENT_LINK_PRICE_MAX = 2000;
 declare const PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD = 200;
@@ -57,4 +31,4 @@ interface AnonymousAuthHelperDeps {
  */
 declare function createAnonymousAuthHelper(deps: AnonymousAuthHelperDeps): (existingUser: User | null) => Promise<User>;
 
-export { type AnonymousAuthHelperDeps, PAYMENT_LINK_DEFAULT_EXPIRY_DAYS, PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD, PAYMENT_LINK_PRICE_MAX, PAYMENT_LINK_PRICE_MIN, type PaymentLink, type PaymentLinkInput, createAnonymousAuthHelper, defaultExpiry, generatePaymentLinkToken, isExpired };
+export { type AnonymousAuthHelperDeps, PAYMENT_LINK_DEFAULT_EXPIRY_DAYS, PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD, PAYMENT_LINK_PRICE_MAX, PAYMENT_LINK_PRICE_MIN, createAnonymousAuthHelper, defaultExpiry, generatePaymentLinkToken, isExpired };

package/dist/payment-links/index.d.ts

@@ -1,31 +1,5 @@
 import { Auth, User } from 'firebase/auth';
 
-interface PaymentLinkInput {
-    price: number;
-    label?: string;
-    publicLabel?: string;
-    expiresAt: Date;
-    tallerId: string;
-    notes?: string;
-}
-interface PaymentLink {
-    id: string;
-    token: string;
-    tallerId: string;
-    price: number;
-    label: string | null;
-    publicLabel: string | null;
-    notes: string | null;
-    active: boolean;
-    expiresAt: string;
-    createdByUid: string;
-    createdByEmail: string | null;
-    createdByName: string | null;
-    timesPaid: number;
-    lastPaidAt: string | null;
-    createdAt: string;
-    updatedAt: string;
-}
 declare const PAYMENT_LINK_PRICE_MIN = 1;
 declare const PAYMENT_LINK_PRICE_MAX = 2000;
 declare const PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD = 200;
@@ -57,4 +31,4 @@ interface AnonymousAuthHelperDeps {
  */
 declare function createAnonymousAuthHelper(deps: AnonymousAuthHelperDeps): (existingUser: User | null) => Promise<User>;
 
-export { type AnonymousAuthHelperDeps, PAYMENT_LINK_DEFAULT_EXPIRY_DAYS, PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD, PAYMENT_LINK_PRICE_MAX, PAYMENT_LINK_PRICE_MIN, type PaymentLink, type PaymentLinkInput, createAnonymousAuthHelper, defaultExpiry, generatePaymentLinkToken, isExpired };
+export { type AnonymousAuthHelperDeps, PAYMENT_LINK_DEFAULT_EXPIRY_DAYS, PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD, PAYMENT_LINK_PRICE_MAX, PAYMENT_LINK_PRICE_MIN, createAnonymousAuthHelper, defaultExpiry, generatePaymentLinkToken, isExpired };

package/dist/payment-links/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/payment-links/paymentLink.ts","../../src/payment-links/anonymousAuth.ts"],"names":[],"mappings":";;;AAkCO,IAAM,sBAAA,GAAyB;AAC/B,IAAM,sBAAA,GAAyB;AAC/B,IAAM,oCAAA,GAAuC;AAC7C,IAAM,gCAAA,GAAmC;AAEzC,SAAS,wBAAA,GAAmC;AAGjD,EAAA,OAAO,YAAY,EAAE,CAAA,CAClB,QAAA,CAAS,QAAQ,EACjB,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,QAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,OAAA,CAAQ,QAAQ,EAAE,CAAA;AACvB;AAEO,SAAS,aAAA,GAAsB;AACpC,EAAA,MAAM,CAAA,uBAAQ,IAAA,EAAK;AACnB,EAAA,CAAA,CAAE,OAAA,CAAQ,CAAA,CAAE,OAAA,EAAQ,GAAI,gCAAgC,CAAA;AACxD,EAAA,OAAO,CAAA;AACT;AAEO,SAAS,UAAU,SAAA,EAAmC;AAC3D,EAAA,MAAM,MAAM,OAAO,SAAA,KAAc,QAAA,GAAW,SAAA,GAAY,UAAU,WAAA,EAAY;AAC9E,EAAA,OAAO,IAAI,IAAA,CAAK,GAAG,EAAE,OAAA,EAAQ,GAAI,KAAK,GAAA,EAAI;AAC5C;;;ACrBO,SAAS,0BAA0B,IAAA,EAA+B;AACvE,EAAA,MAAM,eAAA,GAAkB,KAAK,eAAA,IAAmB,mBAAA;AAEhD,EAAA,OAAO,eAAe,uBACpB,YAAA,EACe;AACf,IAAA,IAAI,IAAA,GAAO,YAAA,IAAgB,IAAA,CAAK,IAAA,CAAK,WAAA;AAErC,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,MAAM,EAAE,iBAAA,EAAkB,GAAI,MAAM,OAAO,eAAe,CAAA;AAC1D,MAAA,MAAM,IAAA,GAAO,MAAM,iBAAA,CAAkB,IAAA,CAAK,IAAI,CAAA;AAC9C,MAAA,IAAA,GAAO,IAAA,CAAK,IAAA;AAAA,IACd;AAEA,IAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,UAAA;AAAA;AAAA,MAA8B;AAAA,KAAI;AAC7D,IAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,eAAA,EAAiB;AAAA,MACvC,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA,EAAmB;AAAA,MAC9C,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,SAAS;AAAA,KACjC,CAAA;AAED,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,oCAAA,EAAoC,GAAA,CAAI,MAAM,CAAA,CAAA,CAAG,CAAA;AAAA,IACnE;AAEA,IAAA,OAAO,IAAA;AAAA,EACT,CAAA;AACF","file":"index.js","sourcesContent":["import { randomBytes } from \"crypto\";\n\nexport interface PaymentLinkInput {\n  price: number;\n  label?: string;\n  publicLabel?: string;\n  expiresAt: Date;\n  tallerId: string;\n  notes?: string;\n}\n\nexport interface PaymentLink {\n  id: string;\n  token: string;\n  tallerId: string;\n  price: number;\n  // Nombre interno (solo admin) — referencia para identificar el link en la\n  // tabla y en el dashboard. NUNCA se muestra al cliente.\n  label: string | null;\n  // Etiqueta promocional visible al cliente en /pago/t/[token] junto al\n  // emoji 🔥 (ej. \"Promo amigas\", \"Última semana\"). Opcional.\n  publicLabel: string | null;\n  notes: string | null;\n  active: boolean;\n  expiresAt: string;\n  createdByUid: string;\n  createdByEmail: string | null;\n  createdByName: string | null;\n  timesPaid: number;\n  lastPaidAt: string | null;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport const PAYMENT_LINK_PRICE_MIN = 1;\nexport const PAYMENT_LINK_PRICE_MAX = 2000;\nexport const PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD = 200;\nexport const PAYMENT_LINK_DEFAULT_EXPIRY_DAYS = 30;\n\nexport function generatePaymentLinkToken(): string {\n  // 12 bytes → 16 chars base64url, suficientemente largo para evitar adivinanza\n  // (2^96 combinaciones) y lo bastante corto para un URL amigable.\n  return randomBytes(12)\n    .toString(\"base64\")\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/g, \"\");\n}\n\nexport function defaultExpiry(): Date {\n  const d = new Date();\n  d.setDate(d.getDate() + PAYMENT_LINK_DEFAULT_EXPIRY_DAYS);\n  return d;\n}\n\nexport function isExpired(expiresAt: Date | string): boolean {\n  const iso = typeof expiresAt === \"string\" ? expiresAt : expiresAt.toISOString();\n  return new Date(iso).getTime() < Date.now();\n}\n","// Source: pauhenriques-website/src/lib/pago-link/anonymousAuth.ts\n// Phase 1.4: refactored to factory pattern.\n//\n// Client-only helper used by guest checkout flows (e.g. payment links) that\n// need a Firebase __session cookie to call the package's POST handlers\n// (charge, 3ds-complete, refund, etc.) — those handlers verify a session\n// cookie, so guests must first sign in anonymously.\n//\n// The two consumer touchpoints (Firebase client Auth instance and session\n// endpoint path) are injected as deps rather than imported from a fixed\n// module path, so the helper works in any Next.js app regardless of how\n// the consumer initializes Firebase.\n\nimport type { Auth, User } from \"firebase/auth\";\n\n/** Dependencies for the anonymous-auth helper factory. */\nexport interface AnonymousAuthHelperDeps {\n  /** Firebase client Auth instance. Must be the same instance used by the consumer's app for sign-in state to stay consistent across calls. */\n  auth: Auth;\n  /** URL where the helper POSTs `{ idToken }` to exchange the Firebase ID token for a server-side session cookie. The endpoint must respond 2xx on success. Default: \"/api/auth/session\". */\n  sessionEndpoint?: string;\n}\n\n/**\n * Creates an `ensureAnonymousSession(existingUser)` function that signs in\n * anonymously (if not already signed in) and establishes a server-side\n * session cookie. Idempotent: if a user is already signed in, refreshes\n * the cookie with the current user.\n *\n * Usage:\n *\n *   const ensureAnonymousSession = createAnonymousAuthHelper({\n *     auth: clientAuth,\n *     sessionEndpoint: \"/api/auth/session\",\n *   });\n *   const user = await ensureAnonymousSession(currentUser);\n */\nexport function createAnonymousAuthHelper(deps: AnonymousAuthHelperDeps) {\n  const sessionEndpoint = deps.sessionEndpoint ?? \"/api/auth/session\";\n\n  return async function ensureAnonymousSession(\n    existingUser: User | null,\n  ): Promise<User> {\n    let user = existingUser ?? deps.auth.currentUser;\n\n    if (!user) {\n      const { signInAnonymously } = await import(\"firebase/auth\");\n      const cred = await signInAnonymously(deps.auth);\n      user = cred.user;\n    }\n\n    const idToken = await user.getIdToken(/* forceRefresh */ true);\n    const res = await fetch(sessionEndpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ idToken }),\n    });\n\n    if (!res.ok) {\n      throw new Error(`No se pudo establecer la sesión (${res.status})`);\n    }\n\n    return user;\n  };\n}\n"]}
+{"version":3,"sources":["../../src/payment-links/paymentLink.ts","../../src/payment-links/anonymousAuth.ts"],"names":[],"mappings":";;;AAQO,IAAM,sBAAA,GAAyB;AAC/B,IAAM,sBAAA,GAAyB;AAC/B,IAAM,oCAAA,GAAuC;AAC7C,IAAM,gCAAA,GAAmC;AAEzC,SAAS,wBAAA,GAAmC;AAGjD,EAAA,OAAO,YAAY,EAAE,CAAA,CAClB,QAAA,CAAS,QAAQ,EACjB,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,QAAQ,KAAA,EAAO,GAAG,CAAA,CAClB,OAAA,CAAQ,QAAQ,EAAE,CAAA;AACvB;AAEO,SAAS,aAAA,GAAsB;AACpC,EAAA,MAAM,CAAA,uBAAQ,IAAA,EAAK;AACnB,EAAA,CAAA,CAAE,OAAA,CAAQ,CAAA,CAAE,OAAA,EAAQ,GAAI,gCAAgC,CAAA;AACxD,EAAA,OAAO,CAAA;AACT;AAEO,SAAS,UAAU,SAAA,EAAmC;AAC3D,EAAA,MAAM,MAAM,OAAO,SAAA,KAAc,QAAA,GAAW,SAAA,GAAY,UAAU,WAAA,EAAY;AAC9E,EAAA,OAAO,IAAI,IAAA,CAAK,GAAG,EAAE,OAAA,EAAQ,GAAI,KAAK,GAAA,EAAI;AAC5C;;;ACKO,SAAS,0BAA0B,IAAA,EAA+B;AACvE,EAAA,MAAM,eAAA,GAAkB,KAAK,eAAA,IAAmB,mBAAA;AAEhD,EAAA,OAAO,eAAe,uBACpB,YAAA,EACe;AACf,IAAA,IAAI,IAAA,GAAO,YAAA,IAAgB,IAAA,CAAK,IAAA,CAAK,WAAA;AAErC,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,MAAM,EAAE,iBAAA,EAAkB,GAAI,MAAM,OAAO,eAAe,CAAA;AAC1D,MAAA,MAAM,IAAA,GAAO,MAAM,iBAAA,CAAkB,IAAA,CAAK,IAAI,CAAA;AAC9C,MAAA,IAAA,GAAO,IAAA,CAAK,IAAA;AAAA,IACd;AAEA,IAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,UAAA;AAAA;AAAA,MAA8B;AAAA,KAAI;AAC7D,IAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,eAAA,EAAiB;AAAA,MACvC,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA,EAAmB;AAAA,MAC9C,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,SAAS;AAAA,KACjC,CAAA;AAED,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,oCAAA,EAAoC,GAAA,CAAI,MAAM,CAAA,CAAA,CAAG,CAAA;AAAA,IACnE;AAEA,IAAA,OAAO,IAAA;AAAA,EACT,CAAA;AACF","file":"index.js","sourcesContent":["import { randomBytes } from \"crypto\";\n\n// NOTE: this module intentionally exposes only generic payment-link PRIMITIVES\n// (token generation, expiry helpers, price bounds). The shape of a payment link\n// document — what it points to (a workshop, a course, a session…), its labels,\n// usage counters, etc. — is consumer-specific, so consumers define their own\n// PaymentLink type and build their own resolver on top of these primitives.\n\nexport const PAYMENT_LINK_PRICE_MIN = 1;\nexport const PAYMENT_LINK_PRICE_MAX = 2000;\nexport const PAYMENT_LINK_PRICE_CONFIRM_THRESHOLD = 200;\nexport const PAYMENT_LINK_DEFAULT_EXPIRY_DAYS = 30;\n\nexport function generatePaymentLinkToken(): string {\n  // 12 bytes → 16 chars base64url, suficientemente largo para evitar adivinanza\n  // (2^96 combinaciones) y lo bastante corto para un URL amigable.\n  return randomBytes(12)\n    .toString(\"base64\")\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/g, \"\");\n}\n\nexport function defaultExpiry(): Date {\n  const d = new Date();\n  d.setDate(d.getDate() + PAYMENT_LINK_DEFAULT_EXPIRY_DAYS);\n  return d;\n}\n\nexport function isExpired(expiresAt: Date | string): boolean {\n  const iso = typeof expiresAt === \"string\" ? expiresAt : expiresAt.toISOString();\n  return new Date(iso).getTime() < Date.now();\n}\n","// Source: pauhenriques-website/src/lib/pago-link/anonymousAuth.ts\n// Phase 1.4: refactored to factory pattern.\n//\n// Client-only helper used by guest checkout flows (e.g. payment links) that\n// need a Firebase __session cookie to call the package's POST handlers\n// (charge, 3ds-complete, refund, etc.) — those handlers verify a session\n// cookie, so guests must first sign in anonymously.\n//\n// The two consumer touchpoints (Firebase client Auth instance and session\n// endpoint path) are injected as deps rather than imported from a fixed\n// module path, so the helper works in any Next.js app regardless of how\n// the consumer initializes Firebase.\n\nimport type { Auth, User } from \"firebase/auth\";\n\n/** Dependencies for the anonymous-auth helper factory. */\nexport interface AnonymousAuthHelperDeps {\n  /** Firebase client Auth instance. Must be the same instance used by the consumer's app for sign-in state to stay consistent across calls. */\n  auth: Auth;\n  /** URL where the helper POSTs `{ idToken }` to exchange the Firebase ID token for a server-side session cookie. The endpoint must respond 2xx on success. Default: \"/api/auth/session\". */\n  sessionEndpoint?: string;\n}\n\n/**\n * Creates an `ensureAnonymousSession(existingUser)` function that signs in\n * anonymously (if not already signed in) and establishes a server-side\n * session cookie. Idempotent: if a user is already signed in, refreshes\n * the cookie with the current user.\n *\n * Usage:\n *\n *   const ensureAnonymousSession = createAnonymousAuthHelper({\n *     auth: clientAuth,\n *     sessionEndpoint: \"/api/auth/session\",\n *   });\n *   const user = await ensureAnonymousSession(currentUser);\n */\nexport function createAnonymousAuthHelper(deps: AnonymousAuthHelperDeps) {\n  const sessionEndpoint = deps.sessionEndpoint ?? \"/api/auth/session\";\n\n  return async function ensureAnonymousSession(\n    existingUser: User | null,\n  ): Promise<User> {\n    let user = existingUser ?? deps.auth.currentUser;\n\n    if (!user) {\n      const { signInAnonymously } = await import(\"firebase/auth\");\n      const cred = await signInAnonymously(deps.auth);\n      user = cred.user;\n    }\n\n    const idToken = await user.getIdToken(/* forceRefresh */ true);\n    const res = await fetch(sessionEndpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ idToken }),\n    });\n\n    if (!res.ok) {\n      throw new Error(`No se pudo establecer la sesión (${res.status})`);\n    }\n\n    return user;\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pandait.tech/payment-nuvei",
-  "version": "0.5.0",
+  "version": "1.0.1",
   "description": "Nuvei Ecuador payment gateway adapter for Next.js: charge handler, webhook, 3DS flow, refunds, tokenized cards, and payment links. Part of panda-commerce-kit.",
   "license": "MIT",
   "private": false,
@@ -91,6 +91,7 @@
     "@tailwindcss/cli": "^4",
     "@types/node": "^22.7.5",
     "@types/react": "^18.3.12",
+    "@vitest/coverage-v8": "^4.1.7",
     "firebase": "^11.0.0",
     "firebase-admin": "^12.7.0",
     "next": "^14.2.15",
@@ -107,7 +108,7 @@
     "build:css": "tailwindcss -i src/ui/styles.css -o dist/ui/styles.css --minify",
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint src",
     "clean": "rm -rf dist .turbo"