@easypayment/medusa-paypal 0.4.7 → 0.4.8

package/src/modules/paypal/service.ts

@@ -1,1247 +1,1247 @@
-import { MedusaService } from "@medusajs/framework/utils"
-import PayPalConnection from "./models/paypal_connection"
-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({
-  PayPalConnection,
-  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) : "EUR"
-      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,
-    }
-  }
-
-  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 live (production).
-   */
-  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) || "live"
-      return env === "sandbox" ? "sandbox" : "live"
-    } catch {
-      return "live"
-    }
-  }
-
-  private getEnvCreds(
-    row: any,
-    env: Environment
-  ): { clientId?: string; clientSecret?: 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,
-    }
-  }
-
-  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 (e: any) {
-      console.warn("[PayPal] Failed to parse response JSON — using empty object:", e?.message)
-    }
-
-    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 === "sandbox" ? "sandbox" : "live"
-    const row = await this.getCurrentRow()
-    const previousEnv = (row?.environment as Environment) || "live"
-
-    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 (e: any) {
-      console.warn("[PayPal] Failed to parse token response JSON:", e?.message)
-    }
-
-    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 (e: any) {
-      console.warn("[PayPal] Failed to parse token response JSON:", e?.message)
-    }
-
-    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 || "")
-    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 })
-
-  }
-
-
-  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" },
-          ],
-        }),
-      })
-
-      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) || "live")
-    }
-
-    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 sellerEmail: string | null = null
-
-    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> }
-  }
-
-  /**
-   * Deep-merge patch into current settings.
-   * Nested objects (additional_settings, api_details, etc.) are merged,
-   * not replaced.
-   */
-  private deepMerge(
-    target: Record<string, any>,
-    source: Record<string, any>
-  ): Record<string, any> {
-    const result = { ...target }
-    for (const key of Object.keys(source)) {
-      const sv = source[key]
-      const tv = target[key]
-      if (
-        sv !== null &&
-        typeof sv === "object" &&
-        !Array.isArray(sv) &&
-        tv !== null &&
-        typeof tv === "object" &&
-        !Array.isArray(tv)
-      ) {
-        result[key] = this.deepMerge(tv, sv)
-      } else {
-        result[key] = sv
-      }
-    }
-    return result
-  }
-
-  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 = this.deepMerge(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,
-    }
-  }
-
-  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 recordAuditEvent(_eventType: string, _metadata?: Record<string, unknown>) {
-    return null
-  }
-
-
-  async recordMetric(name: string, metadata?: Record<string, unknown>) {
-    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 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 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
+import { MedusaService } from "@medusajs/framework/utils"
+import PayPalConnection from "./models/paypal_connection"
+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({
+  PayPalConnection,
+  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) : "EUR"
+      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,
+    }
+  }
+
+  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 live (production).
+   */
+  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) || "live"
+      return env === "sandbox" ? "sandbox" : "live"
+    } catch {
+      return "live"
+    }
+  }
+
+  private getEnvCreds(
+    row: any,
+    env: Environment
+  ): { clientId?: string; clientSecret?: 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,
+    }
+  }
+
+  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 (e: any) {
+      console.warn("[PayPal] Failed to parse response JSON — using empty object:", e?.message)
+    }
+
+    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 === "sandbox" ? "sandbox" : "live"
+    const row = await this.getCurrentRow()
+    const previousEnv = (row?.environment as Environment) || "live"
+
+    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 (e: any) {
+      console.warn("[PayPal] Failed to parse token response JSON:", e?.message)
+    }
+
+    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 (e: any) {
+      console.warn("[PayPal] Failed to parse token response JSON:", e?.message)
+    }
+
+    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 || "")
+    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 })
+
+  }
+
+
+  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" },
+          ],
+        }),
+      })
+
+      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) || "live")
+    }
+
+    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 sellerEmail: string | null = null
+
+    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> }
+  }
+
+  /**
+   * Deep-merge patch into current settings.
+   * Nested objects (additional_settings, api_details, etc.) are merged,
+   * not replaced.
+   */
+  private deepMerge(
+    target: Record<string, any>,
+    source: Record<string, any>
+  ): Record<string, any> {
+    const result = { ...target }
+    for (const key of Object.keys(source)) {
+      const sv = source[key]
+      const tv = target[key]
+      if (
+        sv !== null &&
+        typeof sv === "object" &&
+        !Array.isArray(sv) &&
+        tv !== null &&
+        typeof tv === "object" &&
+        !Array.isArray(tv)
+      ) {
+        result[key] = this.deepMerge(tv, sv)
+      } else {
+        result[key] = sv
+      }
+    }
+    return result
+  }
+
+  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 = this.deepMerge(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,
+    }
+  }
+
+  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 recordAuditEvent(_eventType: string, _metadata?: Record<string, unknown>) {
+    return null
+  }
+
+
+  async recordMetric(name: string, metadata?: Record<string, unknown>) {
+    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 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 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