@easypayment/medusa-paypal 0.6.3 → 0.6.4

package/src/modules/paypal/webhook-processor.ts

@@ -1,215 +1,377 @@
-import type { MedusaContainer } from "@medusajs/framework/types"
-import { Modules } from "@medusajs/framework/utils"
-import type PayPalModuleService from "./service"
-import { isPayPalProviderId } from "./utils/provider-ids"
-import { PAYPAL_MODULE } from "./index"
-
-export const EVENT_STATUS_MAP: Record<string, "authorized" | "captured" | "canceled" | "error"> = {
-  "CHECKOUT.ORDER.APPROVED": "authorized",
-  "CHECKOUT.ORDER.CANCELLED": "canceled",
-  "PAYMENT.CAPTURE.COMPLETED": "captured",
-  "PAYMENT.CAPTURE.DENIED": "error",
-  "PAYMENT.CAPTURE.REFUNDED": "canceled",
-  "PAYMENT.CAPTURE.REVERSED": "canceled",
-  "PAYMENT.AUTHORIZATION.CREATED": "authorized",
-  "PAYMENT.AUTHORIZATION.VOIDED": "canceled",
-  "PAYMENT.AUTHORIZATION.DENIED": "error",
-  "PAYMENT.REFUND.COMPLETED": "canceled",
-  "PAYMENT.REFUND.DENIED": "error",
-}
-
-export const REQUIRED_EVENT_PREFIXES = [
-  "PAYMENT.CAPTURE.",
-  "CHECKOUT.ORDER.",
-  "PAYMENT.AUTHORIZATION.",
-  "PAYMENT.REFUND.",
-]
-
-export function isAllowedEventType(eventType: string) {
-  return REQUIRED_EVENT_PREFIXES.some((prefix) => eventType.startsWith(prefix))
-}
-
-export function normalizeResource(payload: Record<string, any>) {
-  const resource = payload?.resource
-  if (!resource) {
-    return {}
-  }
-  if (typeof resource === "string") {
-    try {
-      return JSON.parse(resource)
-    } catch {
-      return {}
-    }
-  }
-  return resource
-}
-
-export function normalizeEventVersion(payload: Record<string, any>) {
-  const raw =
-    payload?.event_version ??
-    payload?.resource_version ??
-    payload?.resource?.resource_version ??
-    payload?.resource?.version ??
-    null
-
-  if (!raw) {
-    return null
-  }
-
-  return String(raw).trim().replace(/^v/i, "")
-}
-
-export function extractIdentifiers(resource: any) {
-  const relatedIds = resource?.supplementary_data?.related_ids || {}
-  const orderId =
-    relatedIds?.order_id ||
-    resource?.purchase_units?.[0]?.custom_id ||
-    resource?.custom_id ||
-    resource?.purchase_units?.[0]?.reference_id
-  const captureId =
-    relatedIds?.capture_id ||
-    resource?.id ||
-    resource?.purchase_units?.[0]?.payments?.captures?.[0]?.id
-  const refundId =
-    relatedIds?.refund_id ||
-    resource?.id ||
-    resource?.purchase_units?.[0]?.payments?.refunds?.[0]?.id
-  const cartId =
-    resource?.custom_id ||
-    resource?.purchase_units?.[0]?.custom_id ||
-    resource?.purchase_units?.[0]?.reference_id
-
-  return { orderId, captureId, refundId, cartId, resource }
-}
-
-function mergeRefunds(existing: any[], incoming: any[]) {
-  const seen = new Set<string>()
-  const merged: any[] = []
-
-  for (const refund of [...existing, ...incoming]) {
-    const id = refund?.id ? String(refund.id) : ""
-    if (id && seen.has(id)) {
-      continue
-    }
-    if (id) {
-      seen.add(id)
-    }
-    merged.push(refund)
-  }
-
-  return merged
-}
-
-async function updatePaymentSession(
-  container: MedusaContainer,
-  cartId: string,
-  status: string,
-  data: Record<string, unknown>
-) {
-  // FIX 4b: was container.resolve("payment_collection") as any
-  //         and container.resolve("payment_session") as any
-  // Modules.PAYMENT is the official typed constant that resolves the Medusa payment module.
-  // It gives access to both payment collections and payment sessions through one service.
-  const paymentModule = container.resolve(Modules.PAYMENT) as any
-
-  const pc = await paymentModule.retrievePaymentCollectionByCartId?.(cartId).catch(() => null)
-    ?? await paymentModule.listPaymentCollections({ cart_id: cartId })
-        .then((r: any[]) => r?.[0] ?? null)
-        .catch(() => null)
-
-  if (!pc?.id) {
-    return
-  }
-
-  const sessions = await paymentModule.listPaymentSessions({ payment_collection_id: pc.id })
-  const paypalSession = sessions?.find((s: any) => isPayPalProviderId(s.provider_id))
-  if (!paypalSession) {
-    return
-  }
-
-  const existingData = (paypalSession.data || {}) as Record<string, any>
-  const existingPaypal = (existingData.paypal || {}) as Record<string, any>
-  const existingRefunds = Array.isArray(existingPaypal.refunds) ? existingPaypal.refunds : []
-  const incomingRefunds = Array.isArray(data.refunds) ? data.refunds : null
-  const nextRefunds = incomingRefunds
-    ? mergeRefunds(existingRefunds, incomingRefunds)
-    : existingRefunds
-
-  await paymentModule.updatePaymentSession(paypalSession.id, {
-    status,
-    data: {
-      ...existingData,
-      paypal: {
-        ...existingPaypal,
-        ...data,
-        refunds: nextRefunds,
-      },
-    },
-  })
-}
-
-export function computeNextRetryAt(attemptCount: number) {
-  const scheduleMinutes = [5, 15, 30, 60, 120]
-  const delayMinutes = scheduleMinutes[Math.min(attemptCount - 1, scheduleMinutes.length - 1)]
-  if (!delayMinutes || attemptCount <= 0) {
-    return null
-  }
-  return new Date(Date.now() + delayMinutes * 60 * 1000)
-}
-
-export async function processPayPalWebhookEvent(
-  container: MedusaContainer,
-  input: {
-    eventType: string
-    payload: Record<string, any>
-  }
-) {
-  // FIX 4c: was container.resolve<PayPalModuleService>("paypal_onboarding")
-  // PAYPAL_MODULE is the exported constant from ./index.ts — value is "paypal_onboarding"
-  // Using the constant means if the key ever changes, this file updates automatically.
-  const paypal = container.resolve<PayPalModuleService>(PAYPAL_MODULE)
-  const resource = normalizeResource(input.payload)
-  const { orderId, captureId, refundId, cartId } = extractIdentifiers(resource)
-  const refundReason =
-    String(resource?.note_to_payer || resource?.reason || resource?.seller_note || "").trim() ||
-    undefined
-  const refundReasonCode =
-    String(resource?.reason_code || resource?.reasonCode || "").trim() || undefined
-
-  const status = EVENT_STATUS_MAP[input.eventType]
-  if (status && cartId) {
-    const refundEntry =
-      refundId || resource?.status
-        ? [
-            {
-              id: refundId,
-              status: resource?.status,
-              reason: refundReason,
-              reason_code: refundReasonCode,
-              amount: (resource as any)?.amount,
-              raw: resource,
-            },
-          ]
-        : null
-
-    await updatePaymentSession(container, cartId, status, {
-      order_id: orderId,
-      capture_id: captureId,
-      refund_id: refundId,
-      refund_status: resource?.status,
-      refund_reason: refundReason,
-      refund_reason_code: refundReasonCode,
-      refunds: refundEntry || undefined,
-      webhook_event_type: input.eventType,
-      webhook_resource: resource,
-    })
-  }
-
-  return {
-    orderId,
-    captureId,
-    refundId,
-    cartId,
-    resource,
-  }
-}
+import type { MedusaContainer } from "@medusajs/framework/types"
+import { Modules } from "@medusajs/framework/utils"
+import { isPayPalProviderId } from "./utils/provider-ids"
+
+// ─── Event → Medusa status mapping ───────────────────────────────────────────
+
+export const EVENT_STATUS_MAP: Record<
+  string,
+  "authorized" | "captured" | "canceled" | "error"
+> = {
+  "CHECKOUT.ORDER.APPROVED": "authorized",
+  "CHECKOUT.ORDER.CANCELLED": "canceled",
+  "PAYMENT.CAPTURE.COMPLETED": "captured",
+  "PAYMENT.CAPTURE.DENIED": "error",
+  "PAYMENT.CAPTURE.PENDING": "authorized",
+  "PAYMENT.CAPTURE.REFUNDED": "canceled",
+  "PAYMENT.CAPTURE.REVERSED": "canceled",
+  "PAYMENT.AUTHORIZATION.CREATED": "authorized",
+  "PAYMENT.AUTHORIZATION.VOIDED": "canceled",
+  "PAYMENT.AUTHORIZATION.DENIED": "error",
+  "PAYMENT.AUTHORIZATION.EXPIRED": "canceled",
+  "PAYMENT.REFUND.COMPLETED": "canceled",
+  "PAYMENT.REFUND.DENIED": "error",
+}
+
+// ─── Status transition guard ──────────────────────────────────────────────────
+// Only allow forward/meaningful moves.
+// Prevents a late-arriving webhook from downgrading an already-captured payment.
+
+const ALLOWED_TRANSITIONS: Record<string, Set<string>> = {
+  pending: new Set(["authorized", "captured", "canceled", "error"]),
+  authorized: new Set(["captured", "canceled", "error"]),
+  captured: new Set(["canceled"]),
+  canceled: new Set([]),
+  error: new Set(["authorized", "captured", "canceled"]),
+}
+
+export function isTransitionAllowed(from: string, to: string): boolean {
+  return ALLOWED_TRANSITIONS[from]?.has(to) ?? false
+}
+
+// ─── Event type helpers ───────────────────────────────────────────────────────
+
+export const SUPPORTED_EVENT_PREFIXES = [
+  "PAYMENT.CAPTURE.",
+  "CHECKOUT.ORDER.",
+  "PAYMENT.AUTHORIZATION.",
+  "PAYMENT.REFUND.",
+]
+
+export function isAllowedEventType(eventType: string): boolean {
+  return SUPPORTED_EVENT_PREFIXES.some((prefix) => eventType.startsWith(prefix))
+}
+
+// ─── Error classification ─────────────────────────────────────────────────────
+// Non-retryable: event is permanently unprocessable (wrong cart, missing session).
+// Retryable: transient failure (DB down, network error) — worth trying again.
+
+const NON_RETRYABLE_PATTERNS = [
+  "payment collection not found",
+  "no paypal session",
+  "session not found",
+  "cart not found",
+  "no payment collection",
+]
+
+export function isRetryableError(error: unknown): boolean {
+  const message = String(
+    error instanceof Error ? error.message : error ?? ""
+  ).toLowerCase()
+  return !NON_RETRYABLE_PATTERNS.some((p) => message.includes(p))
+}
+
+// ─── Retry schedule ───────────────────────────────────────────────────────────
+
+const RETRY_SCHEDULE_MINUTES = [2, 10, 30, 60, 120]
+export const MAX_WEBHOOK_ATTEMPTS = RETRY_SCHEDULE_MINUTES.length + 1
+
+export function computeNextRetryAt(attemptCount: number): Date | null {
+  const idx = attemptCount - 1
+  const delayMinutes = RETRY_SCHEDULE_MINUTES[idx]
+  if (delayMinutes === undefined || attemptCount <= 0) return null
+  return new Date(Date.now() + delayMinutes * 60 * 1000)
+}
+
+// ─── Payload normalisation ────────────────────────────────────────────────────
+
+export function normalizeResource(payload: Record<string, any>): Record<string, any> {
+  const resource = payload?.resource
+  if (!resource) return {}
+  if (typeof resource === "string") {
+    try {
+      return JSON.parse(resource)
+    } catch {
+      return {}
+    }
+  }
+  return resource as Record<string, any>
+}
+
+export function normalizeEventVersion(payload: Record<string, any>): string | null {
+  const raw =
+    payload?.event_version ??
+    payload?.resource_version ??
+    payload?.resource?.resource_version ??
+    payload?.resource?.version ??
+    null
+  if (!raw) return null
+  return String(raw).trim().replace(/^v/i, "")
+}
+
+// ─── Identifier extraction ────────────────────────────────────────────────────
+
+export interface ExtractedIdentifiers {
+  orderId: string | null
+  captureId: string | null
+  refundId: string | null
+  cartId: string | null
+}
+
+export function extractIdentifiers(
+  resource: Record<string, any>,
+  eventType: string
+): ExtractedIdentifiers {
+  const related = resource?.supplementary_data?.related_ids || {}
+  const isOrder = eventType.startsWith("CHECKOUT.ORDER.")
+  const isCapture = eventType.startsWith("PAYMENT.CAPTURE.")
+  const isAuthorization = eventType.startsWith("PAYMENT.AUTHORIZATION.")
+  const isRefund = eventType.startsWith("PAYMENT.REFUND.")
+
+  let orderId: string | null = null
+  let captureId: string | null = null
+  let refundId: string | null = null
+  let cartId: string | null = null
+
+  if (isOrder) {
+    orderId = String(resource?.id || "").trim() || null
+    cartId =
+      String(
+        resource?.purchase_units?.[0]?.custom_id || resource?.custom_id || ""
+      ).trim() || null
+    captureId =
+      String(
+        resource?.purchase_units?.[0]?.payments?.captures?.[0]?.id || ""
+      ).trim() || null
+  } else if (isCapture) {
+    captureId = String(resource?.id || "").trim() || null
+    orderId = String(related?.order_id || "").trim() || null
+    cartId = String(resource?.custom_id || "").trim() || null
+  } else if (isAuthorization) {
+    orderId = String(related?.order_id || "").trim() || null
+    cartId = String(resource?.custom_id || "").trim() || null
+  } else if (isRefund) {
+    refundId = String(resource?.id || "").trim() || null
+    orderId = String(related?.order_id || "").trim() || null
+    captureId = String(related?.capture_id || "").trim() || null
+    cartId = null
+  }
+
+  return { orderId, captureId, refundId, cartId }
+}
+
+// ─── Session lookup ───────────────────────────────────────────────────────────
+
+interface ResolvedSession {
+  sessionId: string
+  sessionData: Record<string, any>
+  sessionStatus: string
+  collectionId: string
+}
+
+async function findPayPalSession(
+  container: MedusaContainer,
+  cartId: string
+): Promise<ResolvedSession | null> {
+  const paymentModule = container.resolve(Modules.PAYMENT) as any
+
+  let collections: any[]
+  try {
+    collections = await paymentModule.listPaymentCollections(
+      { cart_id: [cartId] },
+      { take: 1 }
+    )
+  } catch (e: any) {
+    throw new Error(`payment collection not found for cart ${cartId}: ${e?.message}`)
+  }
+
+  const collection = collections?.[0]
+  if (!collection?.id) {
+    throw new Error(`payment collection not found for cart ${cartId}`)
+  }
+
+  const sessions = await paymentModule.listPaymentSessions({
+    payment_collection_id: collection.id,
+  })
+
+  const paypalSession = (sessions || [])
+    .filter((s: any) => isPayPalProviderId(s.provider_id))
+    .sort(
+      (a: any, b: any) =>
+        new Date(b.created_at || 0).getTime() -
+        new Date(a.created_at || 0).getTime()
+    )[0]
+
+  if (!paypalSession) {
+    throw new Error(
+      `no paypal session found in collection ${collection.id} for cart ${cartId}`
+    )
+  }
+
+  return {
+    sessionId: paypalSession.id,
+    sessionData: (paypalSession.data || {}) as Record<string, any>,
+    sessionStatus: String(paypalSession.status || "pending"),
+    collectionId: collection.id,
+  }
+}
+
+// ─── Session update ───────────────────────────────────────────────────────────
+
+function mergeRefunds(existing: any[], incoming: any[]): any[] {
+  const seen = new Set<string>()
+  const merged: any[] = []
+  for (const refund of [...existing, ...incoming]) {
+    const id = String(refund?.id || "")
+    if (id && seen.has(id)) continue
+    if (id) seen.add(id)
+    merged.push(refund)
+  }
+  return merged
+}
+
+async function applyStatusToSession(
+  container: MedusaContainer,
+  resolved: ResolvedSession,
+  status: string,
+  patch: Record<string, unknown>
+): Promise<void> {
+  const paymentModule = container.resolve(Modules.PAYMENT) as any
+
+  if (!isTransitionAllowed(resolved.sessionStatus, status)) {
+    console.info(
+      `[PayPal] webhook: skipping disallowed transition ${resolved.sessionStatus} → ${status} for session ${resolved.sessionId}`
+    )
+    return
+  }
+
+  const existingPaypal = (resolved.sessionData.paypal || {}) as Record<string, any>
+  const existingRefunds = Array.isArray(existingPaypal.refunds)
+    ? existingPaypal.refunds
+    : []
+  const incomingRefunds = Array.isArray(patch.refunds)
+    ? (patch.refunds as any[])
+    : null
+  const nextRefunds = incomingRefunds
+    ? mergeRefunds(existingRefunds, incomingRefunds)
+    : existingRefunds
+
+  await paymentModule.updatePaymentSession({
+    id: resolved.sessionId,
+    status,
+    data: {
+      ...resolved.sessionData,
+      paypal: {
+        ...existingPaypal,
+        ...patch,
+        refunds: nextRefunds,
+      },
+    },
+  })
+}
+
+// ─── Main event processor ─────────────────────────────────────────────────────
+
+export interface ProcessResult {
+  orderId: string | null
+  captureId: string | null
+  refundId: string | null
+  cartId: string | null
+  sessionUpdated: boolean
+}
+
+export async function processPayPalWebhookEvent(
+  container: MedusaContainer,
+  input: {
+    eventType: string
+    payload: Record<string, any>
+  }
+): Promise<ProcessResult> {
+  const resource = normalizeResource(input.payload)
+  const { orderId, captureId, refundId, cartId: rawCartId } = extractIdentifiers(
+    resource,
+    input.eventType
+  )
+
+  const refundReason =
+    String(
+      resource?.note_to_payer || resource?.reason || resource?.seller_note || ""
+    ).trim() || undefined
+  const refundReasonCode =
+    String(resource?.reason_code || resource?.reasonCode || "").trim() ||
+    undefined
+
+  const targetStatus = EVENT_STATUS_MAP[input.eventType]
+  if (!targetStatus) {
+    return { orderId, captureId, refundId, cartId: rawCartId, sessionUpdated: false }
+  }
+
+  let cartId = rawCartId
+
+  if (!cartId) {
+    try {
+      const paymentModule = container.resolve(Modules.PAYMENT) as any
+      const allSessions = await paymentModule.listPaymentSessions({
+        provider_id: ["pp_paypal_paypal", "pp_paypal_card_paypal_card"],
+      })
+      const matchedSession = (allSessions || []).find((s: any) => {
+        const pp = ((s.data || {}) as Record<string, any>).paypal || {}
+        if (orderId && pp.order_id === orderId) return true
+        if (captureId && pp.capture_id === captureId) return true
+        return false
+      })
+      if (matchedSession?.payment_collection_id) {
+        const colls = await paymentModule.listPaymentCollections(
+          { id: [matchedSession.payment_collection_id] },
+          { take: 1 }
+        )
+        cartId = String(colls?.[0]?.cart_id || "").trim() || null
+      }
+    } catch (e: any) {
+      console.warn(
+        `[PayPal] webhook: cartId fallback lookup failed for ${input.eventType}:`,
+        e?.message
+      )
+    }
+  }
+
+  let sessionUpdated = false
+
+  if (cartId) {
+    const resolved = await findPayPalSession(container, cartId)
+    if (resolved) {
+      const refundEntry = refundId
+        ? [
+            {
+              id: refundId,
+              status: resource?.status,
+              reason: refundReason,
+              reason_code: refundReasonCode,
+              amount: resource?.amount,
+              raw: resource,
+            },
+          ]
+        : null
+
+      await applyStatusToSession(container, resolved, targetStatus, {
+        order_id: orderId,
+        capture_id: captureId ?? resolved.sessionData.paypal?.capture_id ?? undefined,
+        refund_id: refundId,
+        refund_status: refundId ? resource?.status : undefined,
+        refund_reason: refundReason,
+        refund_reason_code: refundReasonCode,
+        ...(refundEntry ? { refunds: refundEntry } : {}),
+        webhook_event_type: input.eventType,
+        last_webhook_at: new Date().toISOString(),
+      })
+      sessionUpdated = true
+    }
+  } else {
+    console.warn(
+      `[PayPal] webhook: could not resolve cartId for event ${input.eventType}`,
+      { orderId, captureId, refundId }
+    )
+  }
+
+  return { orderId, captureId, refundId, cartId, sessionUpdated }
+}

package/.medusa/server/src/api/admin/paypal/rotate-credentials/route.d.ts

@@ -1,3 +0,0 @@
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
-export declare function POST(req: MedusaRequest, res: MedusaResponse): Promise<MedusaResponse>;
-//# sourceMappingURL=route.d.ts.map

package/.medusa/server/src/api/admin/paypal/rotate-credentials/route.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../../src/api/admin/paypal/rotate-credentials/route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG7E,wBAAsB,IAAI,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,2BAIjE"}

package/.medusa/server/src/api/admin/paypal/rotate-credentials/route.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.POST = POST;
-async function POST(req, res) {
-    const paypal = req.scope.resolve("paypal_onboarding");
-    const result = await paypal.rotateCredentialEncryptionKey();
-    return res.json(result);
-}
-//# sourceMappingURL=route.js.map

package/.medusa/server/src/api/admin/paypal/rotate-credentials/route.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../../../../src/api/admin/paypal/rotate-credentials/route.ts"],"names":[],"mappings":";;AAGA,oBAIC;AAJM,KAAK,UAAU,IAAI,CAAC,GAAkB,EAAE,GAAmB;IAChE,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAsB,mBAAmB,CAAC,CAAA;IAC1E,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,6BAA6B,EAAE,CAAA;IAC3D,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AACzB,CAAC"}

package/.medusa/server/src/jobs/paypal-reconcile.d.ts

@@ -1,7 +0,0 @@
-import type { MedusaContainer } from "@medusajs/framework/types";
-export default function paypalReconcile(container: MedusaContainer): Promise<void>;
-export declare const config: {
-    name: string;
-    schedule: string;
-};
-//# sourceMappingURL=paypal-reconcile.d.ts.map

package/.medusa/server/src/jobs/paypal-reconcile.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"paypal-reconcile.d.ts","sourceRoot":"","sources":["../../../../src/jobs/paypal-reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAchE,wBAA8B,eAAe,CAAC,SAAS,EAAE,eAAe,iBA6FvE;AAED,eAAO,MAAM,MAAM;;;CAGlB,CAAA"}