@easypayment/medusa-paypal 0.1.0

package/src/modules/paypal/service.ts

@@ -0,0 +1,1422 @@
+import { MedusaService } from "@medusajs/framework/utils"
+import PayPalConnection from "./models/paypal_connection"
+import PayPalDispute from "./models/paypal_dispute"
+import PayPalAuditLog from "./models/paypal_audit_log"
+import PayPalMetric from "./models/paypal_metric"
+import PayPalSettings from "./models/paypal_settings"
+import PayPalWebhookEvent from "./models/paypal_webhook_event"
+import { getPayPalConfig } from "./types/config"
+import { decryptSecret, encryptSecret, isEncryptedSecret } from "./utils/crypto"
+import { normalizeCurrencyCode } from "./utils/currencies"
+
+type Environment = "sandbox" | "live"
+
+type Status =
+  | "disconnected"
+  | "pending"
+  | "pending_credentials"
+  | "connected"
+  | "revoked"
+
+class PayPalModuleService extends MedusaService({
+  PayPalAuditLog,
+  PayPalConnection,
+  PayPalDispute,
+  PayPalMetric,
+  PayPalSettings,
+  PayPalWebhookEvent,
+}) {
+  protected cfg = getPayPalConfig()
+
+  private async getSettingsData() {
+    const settings = await this.getSettings()
+    return (settings?.data || {}) as Record<string, any>
+  }
+
+  private async ensureSettingsDefaults() {
+    const data = await this.getSettingsData()
+    const onboarding = { ...(data.onboarding_config || {}) } as Record<string, any>
+    const apiDetails = { ...(data.api_details || {}) } as Record<string, any>
+    let changed = false
+
+    if (!onboarding.partner_service_url) {
+      onboarding.partner_service_url = this.cfg.partnerServiceUrl
+      changed = true
+    }
+    if (!onboarding.partner_js_url) {
+      onboarding.partner_js_url = this.cfg.partnerJsUrl
+      changed = true
+    }
+    if (!onboarding.backend_url) {
+      onboarding.backend_url = this.cfg.backendUrl
+      changed = true
+    }
+    if (!onboarding.seller_nonce) {
+      onboarding.seller_nonce = this.cfg.sellerNonce
+      changed = true
+    }
+    if (!onboarding.bn_code && this.cfg.bnCode) {
+      onboarding.bn_code = this.cfg.bnCode
+      changed = true
+    }
+    if (!onboarding.partner_merchant_id_sandbox) {
+      onboarding.partner_merchant_id_sandbox = this.cfg.partnerMerchantIdSandbox
+      changed = true
+    }
+    if (!onboarding.partner_merchant_id_live) {
+      onboarding.partner_merchant_id_live = this.cfg.partnerMerchantIdLive
+      changed = true
+    }
+
+    if (!apiDetails.currency_code) {
+      const raw = (process.env.PAYPAL_CURRENCY || "").trim()
+      apiDetails.currency_code = raw ? normalizeCurrencyCode(raw) : "USD"
+      changed = true
+    }
+    if (!apiDetails.storefront_url) {
+      const storeUrl = process.env.STOREFRONT_URL || process.env.STORE_URL
+      if (storeUrl) {
+        apiDetails.storefront_url = storeUrl
+        changed = true
+      }
+    }
+
+    if (changed) {
+      await this.saveSettings({
+        onboarding_config: onboarding,
+        api_details: apiDetails,
+      })
+    }
+
+    return { onboarding, apiDetails }
+  }
+
+  async getApiDetails() {
+    const { onboarding, apiDetails } = await this.ensureSettingsDefaults()
+    return {
+      onboarding,
+      apiDetails,
+    }
+  }
+
+  async getLoggingPreference() {
+    const data = await this.getSettingsData()
+    const additional = (data.additional_settings || {}) as Record<string, any>
+    if (typeof additional.enableLogging === "boolean") {
+      return additional.enableLogging
+    }
+    return true
+  }
+
+  private getAlertWebhookUrls() {
+    return (this.cfg.alertWebhookUrls || []).map((url) => url.trim()).filter(Boolean)
+  }
+
+  private getEncryptionKey() {
+    return (this.cfg.credentialsEncryptionKey || "").trim()
+  }
+
+  private getDecryptionKeys() {
+    const current = this.getEncryptionKey()
+    const previous = this.cfg.credentialsEncryptionKeyPrevious || []
+    const keys = [current, ...previous].map((key) => (key || "").trim()).filter(Boolean)
+    return Array.from(new Set(keys))
+  }
+
+  private decryptSecretWithKeys(secret: string, keys: string[]) {
+    let lastError: unknown
+    for (const key of keys) {
+      try {
+        return decryptSecret(secret, key)
+      } catch (err) {
+        lastError = err
+      }
+    }
+    if (lastError) {
+      throw lastError
+    }
+    return secret
+  }
+
+  private maybeEncryptSecret(secret: string) {
+    const key = this.getEncryptionKey()
+    if (!key) {
+      return secret
+    }
+    return encryptSecret(secret, key)
+  }
+
+  private maybeDecryptSecret(secret?: string | null) {
+    if (!secret) {
+      return ""
+    }
+    const keys = this.getDecryptionKeys()
+    if (keys.length === 0) {
+      if (isEncryptedSecret(secret)) {
+        throw new Error(
+          "PayPal client secret is encrypted. Set PAYPAL_CREDENTIALS_ENCRYPTION_KEY to decrypt."
+        )
+      }
+      return secret
+    }
+    if (!isEncryptedSecret(secret)) {
+      return secret
+    }
+    return this.decryptSecretWithKeys(secret, keys)
+  }
+
+  private async getPartnerMerchantId(env: Environment) {
+    const { onboarding } = await this.ensureSettingsDefaults()
+    return env === "live" ? onboarding.partner_merchant_id_live : onboarding.partner_merchant_id_sandbox
+  }
+
+  /**
+   * We keep a single row in DB and store the currently selected environment there.
+   * If no row exists yet, default to sandbox.
+   */
+  private async getCurrentRow(): Promise<any | null> {
+    const rows = await this.listPayPalConnections({})
+    return rows?.[0] ?? null
+  }
+
+  private async getCurrentEnvironment(): Promise<Environment> {
+    try {
+      const row = await this.getCurrentRow()
+      const env = (row?.environment as Environment) || "sandbox"
+      return env === "live" ? "live" : "sandbox"
+    } catch {
+      return "sandbox"
+    }
+  }
+
+  private getEnvCreds(
+    row: any,
+    env: Environment
+  ): { clientId?: string; clientSecret?: string; merchantId?: string } {
+    const meta = (row?.metadata || {}) as any
+    const creds = meta?.credentials?.[env] || {}
+    return {
+      clientId: creds.client_id || creds.clientId || undefined,
+      clientSecret: creds.client_secret || creds.clientSecret || undefined,
+      merchantId: creds.merchant_id || creds.merchantId || undefined,
+    }
+  }
+
+  private getMerchantId(row: any, env: Environment) {
+    const meta = (row?.metadata || {}) as any
+    const creds = this.getEnvCreds(row, env)
+    return creds.merchantId || meta?.merchant_id || meta?.merchantId || undefined
+  }
+
+  private async fetchMerchantIntegrationDetails(env: Environment, merchantId: string) {
+    const partnerMerchantId = await this.getPartnerMerchantId(env)
+    if (!partnerMerchantId) {
+      throw new Error("Missing PayPal partner merchant id configuration.")
+    }
+
+    const { onboarding } = await this.ensureSettingsDefaults()
+    const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
+    const accessToken = await this.getAppAccessToken()
+
+    const resp = await fetch(
+      `${baseUrl}/v1/customer/partners/${encodeURIComponent(
+        partnerMerchantId
+      )}/merchant-integrations/${encodeURIComponent(merchantId)}`,
+      {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${accessToken}`,
+          ...(onboarding.bn_code ? { "PayPal-Partner-Attribution-Id": onboarding.bn_code } : {}),
+        },
+      }
+    )
+
+    const text = await resp.text().catch(() => "")
+    let json: any = {}
+    try {
+      json = text ? JSON.parse(text) : {}
+    } catch {}
+
+    if (!resp.ok) {
+      throw new Error(
+        `PayPal merchant integration lookup failed (${resp.status}): ${text || JSON.stringify(json)}`
+      )
+    }
+
+    return json
+  }
+
+  private async syncRowFieldsFromMetadata(row: any, env: Environment) {
+    const c = this.getEnvCreds(row, env)
+    await this.updatePayPalConnections({
+      id: row.id,
+      status: c.clientId && c.clientSecret ? "connected" : "disconnected",
+      seller_client_id: c.clientId || null,
+      seller_client_secret: c.clientSecret || null,
+      metadata: {
+        ...(row.metadata || {}),
+        active_environment: env,
+      },
+    })
+  }
+
+  /**
+   * Set environment based on admin UI selection (WooCommerce-style).
+   * Switching environment clears stored credentials and requires re-onboarding.
+   */
+
+  async setEnvironment(env: Environment) {
+    const nextEnv: Environment = env === "live" ? "live" : "sandbox"
+    const row = await this.getCurrentRow()
+    const previousEnv = (row?.environment as Environment) || "sandbox"
+
+    if (!row) {
+      // Create a row with no credentials yet for either environment
+      const created = await this.createPayPalConnections({
+        environment: nextEnv,
+        status: "disconnected",
+        shared_id: null,
+        auth_code: null,
+        seller_client_id: null,
+        seller_client_secret: null,
+        app_access_token: null,
+        app_access_token_expires_at: null,
+        metadata: { credentials: {}, active_environment: nextEnv },
+      })
+      await this.recordAuditEvent("environment_switched", {
+        previous_environment: previousEnv,
+        environment: nextEnv,
+      })
+      return created
+    }
+
+    // Just switch the active environment (do NOT wipe other env credentials)
+    await this.updatePayPalConnections({
+      id: row.id,
+      environment: nextEnv,
+      app_access_token: null,
+      app_access_token_expires_at: null,
+      metadata: {
+        ...(row.metadata || {}),
+        active_environment: nextEnv,
+      },
+    })
+
+    // Sync top-level fields/status for the active env so existing code keeps working
+    const updated = await this.getCurrentRow()
+    if (updated) {
+      await this.syncRowFieldsFromMetadata(updated, nextEnv)
+    }
+
+    await this.recordAuditEvent("environment_switched", {
+      previous_environment: previousEnv,
+      environment: nextEnv,
+    })
+    return await this.getCurrentRow()
+  }
+
+  /**
+   * ✅ WooCommerce-style signup link generation (your service returns PayPal partner-referrals JSON)
+   *
+   * - POST to your PHP service (WPG_ONBOARDING_URL)
+   * - Content-Type: application/x-www-form-urlencoded
+   * - fields: email, sandbox, return_url, return_url_description, products[], partner_merchant_id
+   *
+   * Response formats supported:
+   * 1) PayPal partner-referrals JSON: { links: [ { rel: "action_url", href: "..." }, ... ] }
+   * 2) Custom JSON: { onboarding_url: "..." }
+   * 3) Plain URL string
+   */
+  async createOnboardingLink(input?: { email?: string; products?: string[] }) {
+    const { onboarding } = await this.ensureSettingsDefaults()
+    const return_url = `${String(onboarding.backend_url || "").replace(/\/$/, "")}/admin/paypal/onboard-complete`
+    const env = await this.getCurrentEnvironment()
+    const partner_merchant_id = await this.getPartnerMerchantId(env)
+
+    // Match WooCommerce behavior: prefer the current admin user email when available.
+    // If it's missing, continue without it (some services can infer or ignore the field).
+    const email = (input?.email || "").trim()
+
+    if (!partner_merchant_id) {
+      throw new Error("Missing PAYPAL_PARTNER_MERCHANT_ID_* env for current environment")
+    }
+
+    // NOTE:
+    // We intentionally avoid DB access here because Medusa v2 has a known issue where
+    // MedusaService-generated DB methods can throw 'fork' errors when called outside a transaction context.
+    // We store onboarding state later when the JS callback returns authCode/sharedId.
+    const form = new URLSearchParams()
+    if (email) {
+      form.set("email", email)
+    }
+    form.set("sandbox", env === "live" ? "no" : "yes")
+    form.set("return_url", return_url)
+    form.set("return_url_description", "Return to your shop.")
+    form.set("partner_merchant_id", partner_merchant_id)
+
+    const products = input?.products?.length ? input.products : ["PPCP"]
+
+    // WooCommerce/wp_remote_request encodes PHP arrays like products[0]=PPCP.
+    // To maximize compatibility with your existing PHP bridge, we send BOTH:
+    // - products[0], products[1], ...
+    // - products[] (common PHP convention)
+    products.forEach((p, i) => {
+      form.append(`products[${i}]`, p)
+      form.append("products[]", p)
+    })
+
+    const res = await fetch(onboarding.partner_service_url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: form.toString(),
+    })
+
+    const text = await res.text().catch(() => "")
+    if (!res.ok) {
+      throw new Error(`Onboarding service failed (${res.status}): ${text}`)
+    }
+
+    const trimmed = text.trim()
+
+    // plain URL
+    if (trimmed.startsWith("http")) {
+      return { onboarding_url: trimmed, return_url }
+    }
+
+    let json: any
+    try {
+      json = JSON.parse(trimmed)
+    } catch {
+      throw new Error(`Invalid onboarding link response (not JSON / URL): ${trimmed.slice(0, 200)}`)
+    }
+
+    /**
+     * ✅ WooCommerce-style wrapper support
+     *
+     * Your PHP service (same as WooCommerce) often returns a wrapper like:
+     * { result, http_code, headers, body }
+     * where `body` is the actual PayPal partner-referrals JSON string.
+     */
+    if (json?.body) {
+      const inner = typeof json.body === "string" ? json.body.trim() : json.body
+
+      // body is a plain URL
+      if (typeof inner === "string" && inner.startsWith("http")) {
+        return { onboarding_url: inner, return_url }
+      }
+
+      // body is JSON string/object
+      try {
+        json = typeof inner === "string" ? JSON.parse(inner) : inner
+      } catch {
+        throw new Error(
+          `Onboarding wrapper JSON 'body' is not valid JSON / URL: ${
+            typeof inner === "string" ? inner.slice(0, 200) : "[object]"
+          }`
+        )
+      }
+    }
+
+    // ✅ If PayPal returned an error object, surface it clearly.
+    // Typical error shape: { name, message, debug_id, details: [...], links: [...] }
+    if (json?.name && json?.message && (json?.debug_id || json?.details || json?.links)) {
+      const debug = json.debug_id ? ` debug_id=${json.debug_id}` : ""
+      const details = Array.isArray(json.details)
+        ? json.details
+            .slice(0, 3)
+            .map((d: any) => {
+              const issue = d?.issue ? String(d.issue) : ""
+              const desc = d?.description ? String(d.description) : ""
+              const field = d?.field ? String(d.field) : ""
+              return [issue, desc, field].filter(Boolean).join(" | ")
+            })
+            .filter(Boolean)
+            .join("; ")
+        : ""
+
+      throw new Error(`PayPal onboarding error: ${json.name}: ${json.message}.${debug}${details ? ` Details: ${details}` : ""}`)
+    }
+
+    // custom json
+    if (json?.onboarding_url && String(json.onboarding_url).startsWith("http")) {
+      return { onboarding_url: String(json.onboarding_url), return_url }
+    }
+
+    // PayPal partner-referrals format: links[] rel=action_url
+    const links = Array.isArray(json?.links) ? json.links : null
+    if (links) {
+      const action = links.find(
+        (l: any) => l?.rel === "action_url" || l?.rel === "actionUrl" || l?.rel === "action-url"
+      )
+      const href = action?.href ? String(action.href) : null
+      if (href && href.startsWith("http")) {
+        return { onboarding_url: href, return_url }
+      }
+    }
+
+    throw new Error(
+      `Onboarding JSON missing action_url link. Keys: ${Object.keys(json || {}).join(", ")}`
+    )
+  }
+
+  async startOnboarding() {
+    const row = await this.getCurrentRow()
+    const env = await this.getCurrentEnvironment()
+
+    if (row) {
+      // MedusaService-generated update methods expect an object that includes the entity id
+      await this.updatePayPalConnections({ id: row.id, status: "pending" })
+      return
+    }
+
+    await this.createPayPalConnections({
+      environment: env,
+      status: "pending",
+      metadata: {},
+    })
+  }
+
+  async saveOnboardCallback(input: { authCode: string; sharedId: string }) {
+    const row = await this.getCurrentRow()
+    const env = await this.getCurrentEnvironment()
+
+    if (!row) {
+      return await this.createPayPalConnections({
+        environment: env,
+        status: "pending_credentials",
+        auth_code: input.authCode,
+        shared_id: input.sharedId,
+        metadata: {},
+      })
+    }
+
+    return await this.updatePayPalConnections({
+      id: row.id,
+      status: "pending_credentials",
+      auth_code: input.authCode,
+      shared_id: input.sharedId,
+    })
+  }
+
+  /**
+   * Exchange authCode/sharedId for seller API credentials (server-side) and save in DB.
+   *
+   * This calls an optional exchange service you control:
+   *   PAYPAL_EXCHANGE_SERVICE_URL or PAYPAL_PARTNER_EXCHANGE_URL
+   *
+   * Expected JSON response:
+   *   { clientId: string, clientSecret: string, merchantId?: string }
+   */
+  async exchangeAndSaveSellerCredentials(input: {
+    authCode: string
+    sharedId: string
+    env?: "sandbox" | "live"
+  }) {
+    // 1) Persist callback (sharedId/authCode) first
+    await this.saveOnboardCallback({ authCode: input.authCode, sharedId: input.sharedId })
+
+    // 2) Exchange authCode + sharedId (+ seller nonce) to get SELLER access token
+    const env = (input.env || (await this.getCurrentEnvironment())) as Environment
+    const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
+
+    // IMPORTANT: code_verifier MUST match the seller_nonce used when creating the onboarding link.
+    // In WooCommerce you use a fixed nonce() and it works, so we do the same here (no DB storage).
+    const { onboarding } = await this.ensureSettingsDefaults()
+    const sellerNonce = (onboarding.seller_nonce || "").trim()
+    if (!sellerNonce) {
+      throw new Error("PayPal seller nonce is not configured. Set PAYPAL_SELLER_NONCE.")
+    }
+
+    const tokenBody = new URLSearchParams()
+    tokenBody.set("grant_type", "authorization_code")
+    tokenBody.set("code", input.authCode)
+    tokenBody.set("code_verifier", sellerNonce)
+
+    const basic = Buffer.from(`${input.sharedId}:`).toString("base64")
+
+    const tokenRes = await fetch(`${baseUrl}/v1/oauth2/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${basic}`,
+      },
+      body: tokenBody,
+    })
+
+    const tokenText = await tokenRes.text().catch(() => "")
+    let tokenJson: any = {}
+    try {
+      tokenJson = tokenText ? JSON.parse(tokenText) : {}
+    } catch {}
+
+    if (!tokenRes.ok) {
+      throw new Error(
+        `PayPal authorization_code token exchange failed (${tokenRes.status}): ${tokenText || JSON.stringify(tokenJson)}`
+      )
+    }
+
+    const sellerAccessToken = String(tokenJson.access_token || "")
+    if (!sellerAccessToken) {
+      throw new Error("PayPal token exchange succeeded but access_token is missing.")
+    }
+
+    // 3) Use SELLER access token to fetch seller REST API credentials
+    const partnerMerchantId = await this.getPartnerMerchantId(env)
+    if (!partnerMerchantId) {
+      throw new Error("Missing PayPal partner merchant id configuration.")
+    }
+
+    const credRes = await fetch(
+      `${baseUrl}/v1/customer/partners/${encodeURIComponent(partnerMerchantId)}/merchant-integrations/credentials/`,
+      {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${sellerAccessToken}`,
+          ...(onboarding.bn_code ? { "PayPal-Partner-Attribution-Id": onboarding.bn_code } : {}),
+        },
+      }
+    )
+
+    const credText = await credRes.text().catch(() => "")
+    let credJson: any = {}
+    try {
+      credJson = credText ? JSON.parse(credText) : {}
+    } catch {}
+
+    if (!credRes.ok) {
+      throw new Error(
+        `PayPal credentials fetch failed (${credRes.status}): ${credText || JSON.stringify(credJson)}`
+      )
+    }
+
+    const clientId = String(credJson.client_id || "")
+    const clientSecret = String(credJson.client_secret || "")
+    const payerId = String(credJson.payer_id || "")
+
+    if (!clientId || !clientSecret) {
+      throw new Error(
+        `PayPal credentials response missing client_id/client_secret. Keys: ${Object.keys(credJson || {}).join(", ")}`
+      )
+    }
+
+    // 4) Save seller credentials (marks status = connected)
+    await this.saveSellerCredentials({ clientId, clientSecret })
+
+    // 5) Store payer_id as merchant_id in metadata (optional)
+    if (payerId) {
+      const row = await this.getCurrentRow()
+      if (row) {
+        const meta = (row.metadata || {}) as any
+        const creds = { ...(meta.credentials || {}) }
+        creds[env] = { ...(creds[env] || {}), merchant_id: payerId }
+        await this.updatePayPalConnections({
+          id: row.id,
+          metadata: { ...meta, credentials: creds, merchant_id: payerId },
+        })
+      }
+    }
+  }
+
+
+  async saveSellerCredentials(input: { clientId: string; clientSecret: string }) {
+    const row = await this.getCurrentRow()
+    const env = await this.getCurrentEnvironment()
+
+    const encryptedSecret = this.maybeEncryptSecret(input.clientSecret)
+    const nextCreds = {
+      client_id: input.clientId,
+      client_secret: encryptedSecret,
+    }
+
+    if (!row) {
+      const created = await this.createPayPalConnections({
+        environment: env,
+        status: "connected",
+        seller_client_id: input.clientId,
+        seller_client_secret: encryptedSecret,
+        app_access_token: null,
+        app_access_token_expires_at: null,
+        metadata: {
+          credentials: {
+            [env]: nextCreds,
+          },
+          active_environment: env,
+        },
+      })
+      await this.recordAuditEvent("credentials_saved", {
+        environment: env,
+        client_id: input.clientId,
+      })
+      await this.ensureWebhookRegistration()
+      return created
+    }
+
+    const meta = (row.metadata || {}) as any
+    const creds = { ...(meta.credentials || {}) }
+    creds[env] = {
+      ...(creds[env] || {}),
+      ...nextCreds,
+    }
+
+    const updated = await this.updatePayPalConnections({
+      id: row.id,
+      status: "connected",
+      seller_client_id: input.clientId,
+      seller_client_secret: encryptedSecret,
+      app_access_token: null,
+      app_access_token_expires_at: null,
+      metadata: {
+        ...(row.metadata || {}),
+        credentials: creds,
+        active_environment: env,
+      },
+    })
+    await this.recordAuditEvent("credentials_saved", {
+      environment: env,
+      client_id: input.clientId,
+    })
+    await this.ensureWebhookRegistration()
+    return updated
+  }
+
+  private async resolveWebhookUrl() {
+    const { onboarding } = await this.ensureSettingsDefaults()
+    const base = String(onboarding.backend_url || "").replace(/\/$/, "")
+    if (!base) {
+      throw new Error("PayPal backend URL is not configured.")
+    }
+    return `${base}/store/paypal/webhook`
+  }
+
+  private isLocalWebhookUrl(url: string) {
+    try {
+      const parsed = new URL(url)
+      return ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname)
+    } catch {
+      return false
+    }
+  }
+
+  private async ensureWebhookRegistration() {
+    const env = await this.getCurrentEnvironment()
+    const { apiDetails } = await this.ensureSettingsDefaults()
+    const webhookIds = { ...(apiDetails.webhook_ids || {}) } as Record<string, string>
+
+    if (webhookIds[env]) {
+      return webhookIds[env]
+    }
+
+    const accessToken = await this.getAppAccessToken()
+    const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
+    const webhookUrl = await this.resolveWebhookUrl()
+
+    if (this.isLocalWebhookUrl(webhookUrl)) {
+      await this.recordAuditEvent("webhook_skipped_localhost", {
+        environment: env,
+        webhook_url: webhookUrl,
+      })
+      return webhookIds[env] || ""
+    }
+
+    const listResp = await fetch(`${baseUrl}/v1/notifications/webhooks`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+    })
+
+    const listJson = await listResp.json().catch(() => ({}))
+    if (!listResp.ok) {
+      throw new Error(`PayPal webhook list failed (${listResp.status}): ${JSON.stringify(listJson)}`)
+    }
+
+    const existing = Array.isArray(listJson?.webhooks)
+      ? listJson.webhooks.find((hook: any) => hook?.url === webhookUrl)
+      : null
+
+    let webhookId = existing?.id ? String(existing.id) : ""
+
+    if (!webhookId) {
+      const createResp = await fetch(`${baseUrl}/v1/notifications/webhooks`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          url: webhookUrl,
+          event_types: [
+            { name: "CHECKOUT.ORDER.APPROVED" },
+            { name: "CHECKOUT.ORDER.CANCELLED" },
+            { name: "PAYMENT.CAPTURE.COMPLETED" },
+            { name: "PAYMENT.CAPTURE.DENIED" },
+            { name: "PAYMENT.CAPTURE.REFUNDED" },
+            { name: "PAYMENT.CAPTURE.REVERSED" },
+            { name: "PAYMENT.AUTHORIZATION.CREATED" },
+            { name: "PAYMENT.AUTHORIZATION.VOIDED" },
+            { name: "PAYMENT.AUTHORIZATION.DENIED" },
+            { name: "PAYMENT.REFUND.COMPLETED" },
+            { name: "PAYMENT.REFUND.DENIED" },
+            { name: "CUSTOMER.DISPUTE.CREATED" },
+            { name: "CUSTOMER.DISPUTE.UPDATED" },
+            { name: "CUSTOMER.DISPUTE.RESOLVED" },
+          ],
+        }),
+      })
+
+      const createJson = await createResp.json().catch(() => ({}))
+      if (!createResp.ok) {
+        throw new Error(
+          `PayPal webhook create failed (${createResp.status}): ${JSON.stringify(createJson)}`
+        )
+      }
+
+      webhookId = String(createJson?.id || "")
+    }
+
+    if (!webhookId) {
+      throw new Error("PayPal webhook registration did not return an id")
+    }
+
+    const nextWebhookIds = { ...webhookIds, [env]: webhookId }
+    await this.saveSettings({
+      api_details: {
+        ...apiDetails,
+        webhook_ids: nextWebhookIds,
+      },
+    })
+
+    await this.recordAuditEvent("webhook_registered", {
+      environment: env,
+      webhook_id: webhookId,
+      webhook_url: webhookUrl,
+    })
+
+    return webhookId
+  }
+
+  private maskValue(value?: string | null, visibleChars = 4) {
+    if (!value) return null
+    const trimmed = String(value)
+    if (trimmed.length <= visibleChars) {
+      return "•".repeat(trimmed.length)
+    }
+    return `${"•".repeat(Math.max(0, trimmed.length - visibleChars))}${trimmed.slice(
+      -visibleChars
+    )}`
+  }
+
+  async rotateCredentialEncryptionKey() {
+    const currentKey = this.getEncryptionKey()
+    if (!currentKey) {
+      throw new Error("PAYPAL_CREDENTIALS_ENCRYPTION_KEY must be set to rotate credentials.")
+    }
+
+    const row = await this.getCurrentRow()
+    if (!row) {
+      return { rotated: 0 }
+    }
+
+    const meta = (row.metadata || {}) as any
+    const credentials = { ...(meta.credentials || {}) }
+    let rotated = 0
+
+    for (const [env, envCreds] of Object.entries(credentials)) {
+      if (!envCreds || typeof envCreds !== "object") continue
+      const clientSecret = (envCreds as any).client_secret
+      if (!clientSecret) continue
+
+      const decrypted = this.maybeDecryptSecret(clientSecret)
+      const reEncrypted = this.maybeEncryptSecret(decrypted)
+      if (reEncrypted !== clientSecret) {
+        credentials[env] = {
+          ...(envCreds as any),
+          client_secret: reEncrypted,
+        }
+        rotated += 1
+      }
+    }
+
+    if (rotated === 0) {
+      return { rotated: 0 }
+    }
+
+    await this.updatePayPalConnections({
+      id: row.id,
+      metadata: {
+        ...(row.metadata || {}),
+        credentials,
+      },
+      seller_client_secret: credentials?.[row.environment as Environment]?.client_secret || null,
+    })
+
+    const updated = await this.getCurrentRow()
+    if (updated) {
+      await this.syncRowFieldsFromMetadata(updated, (updated.environment as Environment) || "sandbox")
+    }
+
+    await this.recordAuditEvent("credentials_rotated", {
+      environments: Object.keys(credentials),
+    })
+
+    return { rotated }
+  }
+
+  async getStatus(envOverride?: Environment) {
+    const row = await this.getCurrentRow()
+    const env = envOverride ?? (await this.getCurrentEnvironment())
+
+    if (!row) {
+      return { environment: env, status: "disconnected" as Status, seller_client_id_present: false }
+    }
+
+    const c = this.getEnvCreds(row, env)
+    const hasCreds = !!(c.clientId && c.clientSecret)
+    const merchantId = this.getMerchantId(row, env)
+    let sellerEmail: string | null = null
+
+    if (hasCreds && merchantId) {
+      try {
+        const merchantInfo = await this.fetchMerchantIntegrationDetails(env, merchantId)
+        sellerEmail = String(
+          merchantInfo?.primary_email ||
+            merchantInfo?.merchant_email ||
+            merchantInfo?.email ||
+            merchantInfo?.primaryEmail ||
+            ""
+        )
+        if (!sellerEmail) {
+          sellerEmail = null
+        }
+      } catch (error) {
+        console.warn("[paypal_onboarding] failed to fetch merchant integration details", error)
+      }
+    }
+
+    return {
+      environment: env,
+      status: (hasCreds ? "connected" : "disconnected") as Status,
+      shared_id: row.shared_id ?? null,
+      auth_code: row.auth_code ? "***stored***" : null,
+      seller_client_id_present: hasCreds,
+      seller_client_id_masked: this.maskValue(c.clientId),
+      seller_client_secret_masked: c.clientSecret ? "••••••••" : null,
+      seller_email: sellerEmail,
+      updated_at: (row.updated_at as any)?.toISOString?.() ?? null,
+    }
+  }
+
+  async disconnect() {
+    const row = await this.getCurrentRow()
+    if (!row) return
+    const env = await this.getCurrentEnvironment()
+
+    const meta = (row.metadata || {}) as any
+    const creds = { ...(meta.credentials || {}) }
+    // Remove only the active environment credentials
+    delete creds[env]
+
+    const hasAnyCreds = Object.values(creds).some((v: any) => {
+      return v && typeof v === "object" && (v as any).client_id && (v as any).client_secret
+    })
+
+    await this.updatePayPalConnections({
+      id: row.id,
+      status: hasAnyCreds ? "connected" : "disconnected",
+      shared_id: null,
+      auth_code: null,
+      seller_client_id: null,
+      seller_client_secret: null,
+      app_access_token: null,
+      app_access_token_expires_at: null,
+      metadata: {
+        ...(row.metadata || {}),
+        credentials: creds,
+        active_environment: env,
+      },
+    })
+    const updated = await this.getCurrentRow()
+    if (updated) {
+      await this.syncRowFieldsFromMetadata(updated, env)
+    }
+    await this.recordAuditEvent("disconnected", { environment: env })
+  }
+
+  async getAppAccessToken(): Promise<string> {
+    const row = await this.getCurrentRow()
+    const env = await this.getCurrentEnvironment()
+    const creds = await this.getActiveCredentials()
+
+    if (!row) {
+      throw new Error("PayPal connection row not found. Please complete onboarding.")
+    }
+
+    const expiresAt = row.app_access_token_expires_at ? new Date(row.app_access_token_expires_at as any) : null
+    if (row.app_access_token && expiresAt) {
+      const msLeft = expiresAt.getTime() - Date.now()
+      if (msLeft > 2 * 60 * 1000) return row.app_access_token
+    }
+
+    const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
+    const basic = Buffer.from(`${creds.client_id}:${creds.client_secret}`).toString("base64")
+
+    const body = new URLSearchParams()
+    body.set("grant_type", "client_credentials")
+
+    const res = await fetch(`${baseUrl}/v1/oauth2/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Authorization: `Basic ${basic}` },
+      body,
+    })
+
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok) throw new Error(`PayPal client_credentials failed (${res.status}): ${JSON.stringify(json)}`)
+
+    const accessToken = String(json.access_token)
+    const expiresIn = Number(json.expires_in || 3600)
+    const newExpiresAt = new Date(Date.now() + expiresIn * 1000)
+
+    await this.updatePayPalConnections({
+      id: row.id,
+      app_access_token: accessToken,
+      app_access_token_expires_at: newExpiresAt as any,
+    })
+
+    return accessToken
+  }
+
+  /**
+   * Generate a client token for PayPal JS SDK (required for CardFields/PaymentFields).
+   * This token is short-lived and safe to send to the browser.
+   *
+   * PayPal endpoint: POST /v1/identity/generate-token
+   */
+  async generateClientToken(opts?: { locale?: string }): Promise<string> {
+    const env = await this.getCurrentEnvironment()
+    const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
+
+    const accessToken = await this.getAppAccessToken()
+
+    const res = await fetch(`${baseUrl}/v1/identity/generate-token`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...(opts?.locale ? { "Accept-Language": opts.locale } : {}),
+        ...(this.cfg.bnCode ? { "PayPal-Partner-Attribution-Id": this.cfg.bnCode } : {}),
+      },
+    })
+
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok) {
+      throw new Error(`PayPal generate-token failed (${res.status}): ${JSON.stringify(json)}`)
+    }
+
+    const token = String((json as any)?.client_token || "")
+    if (!token) {
+      throw new Error("PayPal client_token is missing in generate-token response")
+    }
+
+    return token
+  }
+
+  /**
+   * GLOBAL PayPal settings (single row)
+   */
+  async getSettings() {
+    const rows = await this.listPayPalSettings({})
+    const row = rows?.[0]
+    return { data: (row?.data || {}) as Record<string, any> }
+  }
+
+  async saveSettings(patch: Record<string, any>) {
+    const rows = await this.listPayPalSettings({})
+    const row = rows?.[0]
+    const current = (row?.data || {}) as Record<string, any>
+
+    const next = { ...current, ...patch }
+
+    if (!row) {
+      const created = await this.createPayPalSettings({ data: next })
+      return { data: (created.data || {}) as Record<string, any> }
+    }
+
+    await this.updatePayPalSettings({ id: row.id, data: next })
+    return { data: next }
+  }
+
+  /**
+   * Active credentials based on selected environment in the single connection row.
+   */
+  async getActiveCredentials() {
+    const row = await this.getCurrentRow()
+    const env = await this.getCurrentEnvironment()
+
+    if (!row) {
+      throw new Error("PayPal connection row not found. Please complete onboarding.")
+    }
+
+    const c = this.getEnvCreds(row, env)
+    const clientSecret = this.maybeDecryptSecret(c.clientSecret)
+
+    if (!c.clientId || !clientSecret) {
+      throw new Error(
+        `PayPal credentials missing for environment "${env}". Please save credentials.`
+      )
+    }
+
+    return {
+      environment: env,
+      client_id: c.clientId,
+      client_secret: clientSecret,
+      merchant_id: c.merchantId,
+    }
+  }
+
+  async getOrderDetails(orderId: string) {
+    if (!orderId) {
+      throw new Error("PayPal orderId is required")
+    }
+
+    const creds = await this.getActiveCredentials()
+    const base =
+      creds.environment === "live"
+        ? "https://api-m.paypal.com"
+        : "https://api-m.sandbox.paypal.com"
+    const auth = Buffer.from(`${creds.client_id}:${creds.client_secret}`).toString("base64")
+
+    const tokenResp = await fetch(`${base}/v1/oauth2/token`, {
+      method: "POST",
+      headers: {
+        Authorization: `Basic ${auth}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: "grant_type=client_credentials",
+    })
+
+    const tokenText = await tokenResp.text()
+    if (!tokenResp.ok) {
+      throw new Error(`PayPal token error (${tokenResp.status}): ${tokenText}`)
+    }
+
+    const tokenJson = JSON.parse(tokenText)
+    const accessToken = String(tokenJson.access_token)
+
+    const resp = await fetch(`${base}/v2/checkout/orders/${orderId}`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+    })
+
+    const text = await resp.text()
+    if (!resp.ok) {
+      throw new Error(`PayPal get order error (${resp.status}): ${text}`)
+    }
+
+    return JSON.parse(text)
+  }
+
+  async createWebhookEventRecord(input: {
+    event_id: string
+    event_type: string
+    resource_id?: string | null
+    payload?: Record<string, unknown>
+    event_version?: string | null
+    transmission_id?: string | null
+    transmission_time?: Date | null
+    status?: string
+    attempt_count?: number
+  }) {
+    try {
+      const created = await this.createPayPalWebhookEvents({
+        event_id: input.event_id,
+        event_type: input.event_type,
+        resource_id: input.resource_id ?? null,
+        payload: input.payload ?? {},
+        event_version: input.event_version ?? null,
+        transmission_id: input.transmission_id ?? null,
+        transmission_time: input.transmission_time ?? null,
+        status: input.status ?? "pending",
+        attempt_count: input.attempt_count ?? 0,
+        next_retry_at: null,
+        processed_at: null,
+        last_error: null,
+      })
+      return { created: true, event: created }
+    } catch (error: any) {
+      const message = String(error?.message || "")
+      if (message.includes("paypal_webhook_event_event_id_unique") || message.includes("unique")) {
+        const existing = await this.listPayPalWebhookEvents({ event_id: input.event_id })
+        return { created: false, event: existing?.[0] ?? null }
+      }
+      throw error
+    }
+  }
+
+  async updateWebhookEventRecord(input: {
+    id: string
+    status?: string
+    attempt_count?: number
+    next_retry_at?: Date | null
+    processed_at?: Date | null
+    last_error?: string | null
+    resource_id?: string | null
+  }) {
+    return await this.updatePayPalWebhookEvents({
+      id: input.id,
+      status: input.status,
+      attempt_count: input.attempt_count,
+      next_retry_at: input.next_retry_at ?? null,
+      processed_at: input.processed_at ?? null,
+      last_error: input.last_error ?? null,
+      resource_id: input.resource_id ?? null,
+    })
+  }
+
+  async upsertDispute(input: {
+    dispute_id: string
+    status?: string | null
+    reason?: string | null
+    stage?: string | null
+    amount?: string | null
+    currency_code?: string | null
+    transaction_id?: string | null
+    seller_transaction_id?: string | null
+    order_id?: string | null
+    cart_id?: string | null
+    payload?: Record<string, unknown>
+  }) {
+    if (!input.dispute_id) {
+      throw new Error("dispute_id is required")
+    }
+    const existing = await this.listPayPalDisputes({ dispute_id: input.dispute_id })
+    const row = existing?.[0]
+
+    if (!row) {
+      return await this.createPayPalDisputes({
+        dispute_id: input.dispute_id,
+        status: input.status ?? null,
+        reason: input.reason ?? null,
+        stage: input.stage ?? null,
+        amount: input.amount ?? null,
+        currency_code: input.currency_code ?? null,
+        transaction_id: input.transaction_id ?? null,
+        seller_transaction_id: input.seller_transaction_id ?? null,
+        order_id: input.order_id ?? null,
+        cart_id: input.cart_id ?? null,
+        payload: input.payload ?? {},
+      })
+    }
+
+    return await this.updatePayPalDisputes({
+      id: row.id,
+      status: input.status ?? row.status ?? null,
+      reason: input.reason ?? row.reason ?? null,
+      stage: input.stage ?? row.stage ?? null,
+      amount: input.amount ?? row.amount ?? null,
+      currency_code: input.currency_code ?? row.currency_code ?? null,
+      transaction_id: input.transaction_id ?? row.transaction_id ?? null,
+      seller_transaction_id: input.seller_transaction_id ?? row.seller_transaction_id ?? null,
+      order_id: input.order_id ?? row.order_id ?? null,
+      cart_id: input.cart_id ?? row.cart_id ?? null,
+      payload: {
+        ...(row.payload || {}),
+        ...(input.payload || {}),
+      },
+    })
+  }
+
+  async recordAuditEvent(eventType: string, metadata?: Record<string, unknown>) {
+    const loggingEnabled = await this.getLoggingPreference().catch(() => true)
+    if (!loggingEnabled) {
+      return null
+    }
+    try {
+      return await this.createPayPalAuditLogs({
+        event_type: eventType,
+        metadata: metadata ?? {},
+      })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      if (message.includes("paypal_audit_log") && message.includes("does not exist")) {
+        console.warn("[paypal_onboarding] audit log table missing; skipping audit event")
+        return null
+      }
+      throw error
+    }
+  }
+
+  async getAuditLogs(limit = 50) {
+    const entries = await this.listPayPalAuditLogs({})
+    const sorted = [...(entries || [])].sort((a: any, b: any) => {
+      const aTime = a?.created_at ? new Date(a.created_at).getTime() : 0
+      const bTime = b?.created_at ? new Date(b.created_at).getTime() : 0
+      return bTime - aTime
+    })
+    return sorted.slice(0, limit).map((entry: any) => ({
+      id: entry.id,
+      event_type: entry.event_type,
+      metadata: this.sanitizeAuditMetadata(entry.metadata || {}),
+      created_at: entry.created_at || null,
+    }))
+  }
+
+  private sanitizeAuditMetadata(metadata: Record<string, unknown>) {
+    const next: Record<string, unknown> = { ...metadata }
+    if (typeof next.client_id === "string") {
+      next.client_id = this.maskValue(next.client_id)
+    }
+    if (typeof next.client_secret === "string") {
+      next.client_secret = "••••••••"
+    }
+    return next
+  }
+
+  async recordMetric(name: string, metadata?: Record<string, unknown>) {
+    const loggingEnabled = await this.getLoggingPreference().catch(() => true)
+    if (!loggingEnabled) {
+      return null
+    }
+    const existing = await this.listPayPalMetrics({ name })
+    const row = existing?.[0]
+    const current = (row?.data || {}) as Record<string, any>
+    const next = {
+      ...current,
+      ...(metadata || {}),
+      count: Number(current.count || 0) + 1,
+      last_recorded_at: new Date().toISOString(),
+    }
+
+    if (!row) {
+      return await this.createPayPalMetrics({
+        name,
+        data: next,
+      })
+    }
+
+    return await this.updatePayPalMetrics({
+      id: row.id,
+      name,
+      data: next,
+    })
+  }
+
+  async recordPaymentLog(eventType: string, metadata?: Record<string, unknown>) {
+    const loggingEnabled = await this.getLoggingPreference().catch(() => true)
+    if (!loggingEnabled) {
+      return null
+    }
+    const payload = {
+      event_type: eventType,
+      metadata: metadata ?? {},
+      created_at: new Date().toISOString(),
+    }
+    console.info("[PayPal] payment_event", payload)
+    return await this.recordAuditEvent(`payment_${eventType}`, metadata)
+  }
+
+  async updateReconciliationStatus(input: {
+    status: "success" | "failed"
+    sessions_checked?: number
+    sessions_updated?: number
+    drift_count?: number
+    error_message?: string | null
+    last_drift_at?: string | null
+    last_drift_order_id?: string | null
+  }) {
+    const existing = await this.listPayPalMetrics({ name: "reconcile_status" })
+    const row = existing?.[0]
+    const current = (row?.data || {}) as Record<string, any>
+    const now = new Date().toISOString()
+    const next = {
+      ...current,
+      runs: Number(current.runs || 0) + 1,
+      last_run_at: now,
+      last_run_status: input.status,
+      last_success_at: input.status === "success" ? now : current.last_success_at,
+      last_failure_at: input.status === "failed" ? now : current.last_failure_at,
+      sessions_checked: Number(input.sessions_checked ?? current.sessions_checked ?? 0),
+      sessions_updated: Number(input.sessions_updated ?? current.sessions_updated ?? 0),
+      drift_count: Number(input.drift_count ?? current.drift_count ?? 0),
+      last_drift_at: input.last_drift_at ?? current.last_drift_at ?? null,
+      last_drift_order_id: input.last_drift_order_id ?? current.last_drift_order_id ?? null,
+      last_error: input.error_message ?? current.last_error ?? null,
+    }
+
+    if (!row) {
+      return await this.createPayPalMetrics({
+        name: "reconcile_status",
+        data: next,
+      })
+    }
+
+    return await this.updatePayPalMetrics({
+      id: row.id,
+      name: "reconcile_status",
+      data: next,
+    })
+  }
+
+  async getReconciliationStatus() {
+    const rows = await this.listPayPalMetrics({ name: "reconcile_status" })
+    const row = rows?.[0]
+    return {
+      status: (row?.data as Record<string, any>) || {},
+    }
+  }
+
+  async sendAlert(input: {
+    type: string
+    message: string
+    metadata?: Record<string, unknown>
+  }) {
+    const urls = this.getAlertWebhookUrls()
+    if (urls.length === 0) {
+      return
+    }
+
+    const payload = {
+      type: input.type,
+      message: input.message,
+      metadata: input.metadata ?? {},
+      source: "paypal",
+      timestamp: new Date().toISOString(),
+    }
+
+    await Promise.all(
+      urls.map(async (url) => {
+        try {
+          const resp = await fetch(url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+          })
+          if (!resp.ok) {
+            const text = await resp.text().catch(() => "")
+            await this.recordAuditEvent("alert_failed", {
+              url,
+              status: resp.status,
+              response: text,
+            })
+          } else {
+            await this.recordAuditEvent("alert_sent", { url, type: input.type })
+          }
+        } catch (error: any) {
+          await this.recordAuditEvent("alert_failed", {
+            url,
+            message: error?.message,
+          })
+        }
+      })
+    )
+  }
+}
+
+export default PayPalModuleService