@easypayment/medusa-paypal-ui 1.2.8 → 1.3.0

package/dist/order.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/order.ts","../src/constants.ts"],"sourcesContent":["/**\n * Server-safe helpers for displaying PayPal payments on order / confirmation\n * pages.\n *\n * This module is intentionally free of React and any client-only code, so it\n * can be imported from Next.js **server components** (e.g. the order\n * confirmation page) without pulling in the checkout UI.\n *\n * @example\n * import { getPaymentLabel, fetchPayPalConfig } from \"@easypayment/medusa-paypal-ui/order\"\n *\n * // In the (async) server component that renders the payment method:\n * const titles = await fetchPayPalConfig({\n *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,\n *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,\n * })\n *\n * <Text>\n *   {getPaymentLabel(\n *     payment.provider_id,\n *     paymentInfoMap[payment.provider_id]?.title,\n *     titles\n *   )}\n * </Text>\n */\n\nimport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  isPayPalProviderId,\n} from \"./constants\"\n\nexport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  isPayPalProviderId,\n}\n\nexport type PayPalPaymentInfo = { title: string }\n\n/** Built-in fallback titles, used only when admin titles aren't supplied. */\nexport const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo> = {\n  [PAYPAL_WALLET_PROVIDER_ID]: { title: \"PayPal\" },\n  [PAYPAL_CARD_PROVIDER_ID]: { title: \"Credit or Debit Card\" },\n}\n\n/** Admin-configured titles, as returned by `GET /store/paypal/config`. */\nexport type PayPalConfigTitles = {\n  paypal_title?: string | null\n  card_title?: string | null\n}\n\n/**\n * Null-safe payment label resolver for order / confirmation pages.\n *\n * Precedence for the PayPal providers: **admin-configured title** (`titles`,\n * from {@link fetchPayPalConfig}) → built-in default. For any other provider:\n * `fallback` → raw id. Never throws on an unknown / missing provider, which is\n * what causes the common `Cannot read properties of undefined (reading 'title')`\n * crash on the order confirmation page.\n *\n * @param titles Admin titles so the order page shows the same labels configured\n *   in Medusa Admin → Settings → PayPal (e.g. a custom \"Credit or Debit Card\").\n */\nexport function getPaymentLabel(\n  providerId: string | undefined | null,\n  fallback?: string,\n  titles?: PayPalConfigTitles\n): string {\n  if (!providerId) {\n    return fallback ?? \"\"\n  }\n  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {\n    return (\n      titles?.paypal_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title\n    )\n  }\n  if (providerId === PAYPAL_CARD_PROVIDER_ID) {\n    return (\n      titles?.card_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title\n    )\n  }\n  return fallback ?? providerId\n}\n\n/**\n * Fetch the admin-configured PayPal titles from the storefront API\n * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).\n *\n * Returns `{}` on any error/network failure so callers can fall back to the\n * built-in defaults without their own try/catch.\n */\nexport async function fetchPayPalConfig(opts: {\n  baseUrl: string\n  publishableApiKey?: string\n  signal?: AbortSignal\n}): Promise<PayPalConfigTitles> {\n  const { baseUrl, publishableApiKey, signal } = opts\n  if (!baseUrl) {\n    return {}\n  }\n  try {\n    const timeoutMs = 30_000\n    let effectiveSignal = signal\n    let timeoutId: ReturnType<typeof setTimeout> | undefined\n    if (!signal) {\n      const controller = new AbortController()\n      timeoutId = setTimeout(() => controller.abort(), timeoutMs)\n      effectiveSignal = controller.signal\n    }\n    let res: Response\n    try {\n      res = await fetch(`${baseUrl.replace(/\\/$/, \"\")}/store/paypal/config`, {\n        headers: {\n          accept: \"application/json\",\n          ...(publishableApiKey\n            ? { \"x-publishable-api-key\": publishableApiKey }\n            : {}),\n        },\n        signal: effectiveSignal,\n      })\n    } finally {\n      if (timeoutId !== undefined) clearTimeout(timeoutId)\n    }\n    if (!res.ok) {\n      return {}\n    }\n    const cfg = (await res.json()) as Record<string, unknown>\n    return {\n      paypal_title:\n        typeof cfg.paypal_title === \"string\" ? cfg.paypal_title : undefined,\n      card_title:\n        typeof cfg.card_title === \"string\" ? cfg.card_title : undefined,\n    }\n  } catch {\n    return {}\n  }\n}\n","/**\n * Provider ids registered by `@easypayment/medusa-payment-paypal`.\n *\n * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,\n * and the server-safe `order` entrypoint all re-export from here so the ids\n * can never drift between entrypoints.\n */\nexport const PAYPAL_WALLET_PROVIDER_ID = \"pp_paypal_paypal\" as const\nexport const PAYPAL_CARD_PROVIDER_ID = \"pp_paypal_card_paypal_card\" as const\n\nexport const PAYPAL_PROVIDER_IDS = [\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n] as const\n\nexport type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number]\n\n/** True when the provider id belongs to this PayPal plugin. */\nexport function isPayPalProviderId(\n  providerId?: string | null\n): providerId is PayPalProviderId {\n  if (!providerId) return false\n  return PAYPAL_PROVIDER_IDS.includes(providerId as PayPalProviderId)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOO,IAAM,4BAA4B;AAClC,IAAM,0BAA0B;AAEhC,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AACF;AAKO,SAAS,mBACd,YACgC;AAChC,MAAI,CAAC,WAAY,QAAO;AACxB,SAAO,oBAAoB,SAAS,UAA8B;AACpE;;;ADkBO,IAAM,uBAA0D;AAAA,EACrE,CAAC,yBAAyB,GAAG,EAAE,OAAO,SAAS;AAAA,EAC/C,CAAC,uBAAuB,GAAG,EAAE,OAAO,uBAAuB;AAC7D;AAoBO,SAAS,gBACd,YACA,UACA,QACQ;AACR,MAAI,CAAC,YAAY;AACf,WAAO,YAAY;AAAA,EACrB;AACA,MAAI,eAAe,2BAA2B;AAC5C,WACE,QAAQ,cAAc,KAAK,KAC3B,qBAAqB,yBAAyB,EAAE;AAAA,EAEpD;AACA,MAAI,eAAe,yBAAyB;AAC1C,WACE,QAAQ,YAAY,KAAK,KACzB,qBAAqB,uBAAuB,EAAE;AAAA,EAElD;AACA,SAAO,YAAY;AACrB;AASA,eAAsB,kBAAkB,MAIR;AAC9B,QAAM,EAAE,SAAS,mBAAmB,OAAO,IAAI;AAC/C,MAAI,CAAC,SAAS;AACZ,WAAO,CAAC;AAAA,EACV;AACA,MAAI;AACF,UAAM,YAAY;AAClB,QAAI,kBAAkB;AACtB,QAAI;AACJ,QAAI,CAAC,QAAQ;AACX,YAAM,aAAa,IAAI,gBAAgB;AACvC,kBAAY,WAAW,MAAM,WAAW,MAAM,GAAG,SAAS;AAC1D,wBAAkB,WAAW;AAAA,IAC/B;AACA,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,GAAG,QAAQ,QAAQ,OAAO,EAAE,CAAC,wBAAwB;AAAA,QACrE,SAAS;AAAA,UACP,QAAQ;AAAA,UACR,GAAI,oBACA,EAAE,yBAAyB,kBAAkB,IAC7C,CAAC;AAAA,QACP;AAAA,QACA,QAAQ;AAAA,MACV,CAAC;AAAA,IACH,UAAE;AACA,UAAI,cAAc,OAAW,cAAa,SAAS;AAAA,IACrD;AACA,QAAI,CAAC,IAAI,IAAI;AACX,aAAO,CAAC;AAAA,IACV;AACA,UAAM,MAAO,MAAM,IAAI,KAAK;AAC5B,WAAO;AAAA,MACL,cACE,OAAO,IAAI,iBAAiB,WAAW,IAAI,eAAe;AAAA,MAC5D,YACE,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,IAC1D;AAAA,EACF,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}
+{"version":3,"sources":["../src/order.ts","../src/constants.ts"],"sourcesContent":["/**\n * Server-safe helpers for displaying PayPal payments on order / confirmation\n * pages.\n *\n * This module is intentionally free of React and any client-only code, so it\n * can be imported from Next.js **server components** (e.g. the order\n * confirmation page) without pulling in the checkout UI.\n *\n * @example\n * import { getPaymentLabel, fetchPayPalConfig } from \"@easypayment/medusa-paypal-ui/order\"\n *\n * // In the (async) server component that renders the payment method:\n * const titles = await fetchPayPalConfig({\n *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,\n *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,\n * })\n *\n * <Text>\n *   {getPaymentLabel(\n *     payment.provider_id,\n *     paymentInfoMap[payment.provider_id]?.title,\n *     titles\n *   )}\n * </Text>\n */\n\nimport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  PAYPAL_PROVIDER_IDS,\n  isPayPalProviderId,\n} from \"./constants\"\nimport type { PayPalProviderId } from \"./constants\"\n\nexport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  PAYPAL_PROVIDER_IDS,\n  isPayPalProviderId,\n}\nexport type { PayPalProviderId }\n\nexport type PayPalPaymentInfo = { title: string }\n\n/** Built-in fallback titles, used only when admin titles aren't supplied. */\nexport const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo> = {\n  [PAYPAL_WALLET_PROVIDER_ID]: { title: \"PayPal\" },\n  [PAYPAL_CARD_PROVIDER_ID]: { title: \"Credit or Debit Card\" },\n}\n\n/** Admin-configured titles, as returned by `GET /store/paypal/config`. */\nexport type PayPalConfigTitles = {\n  paypal_title?: string | null\n  card_title?: string | null\n}\n\n/**\n * Null-safe payment label resolver for order / confirmation pages.\n *\n * Precedence for the PayPal providers: **admin-configured title** (`titles`,\n * from {@link fetchPayPalConfig}) → built-in default. For any other provider:\n * `fallback` → raw id. Never throws on an unknown / missing provider, which is\n * what causes the common `Cannot read properties of undefined (reading 'title')`\n * crash on the order confirmation page.\n *\n * @param titles Admin titles so the order page shows the same labels configured\n *   in Medusa Admin → Settings → PayPal (e.g. a custom \"Credit or Debit Card\").\n */\nexport function getPaymentLabel(\n  providerId: string | undefined | null,\n  fallback?: string,\n  titles?: PayPalConfigTitles\n): string {\n  if (!providerId) {\n    return fallback ?? \"\"\n  }\n  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {\n    return (\n      titles?.paypal_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title\n    )\n  }\n  if (providerId === PAYPAL_CARD_PROVIDER_ID) {\n    return (\n      titles?.card_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title\n    )\n  }\n  return fallback ?? providerId\n}\n\n/**\n * Fetch the admin-configured PayPal titles from the storefront API\n * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).\n *\n * Returns `{}` on any error/network failure so callers can fall back to the\n * built-in defaults without their own try/catch.\n */\nexport async function fetchPayPalConfig(opts: {\n  baseUrl: string\n  publishableApiKey?: string\n  signal?: AbortSignal\n}): Promise<PayPalConfigTitles> {\n  const { baseUrl, publishableApiKey, signal } = opts\n  if (!baseUrl) {\n    return {}\n  }\n  try {\n    // Always arm the timeout — a caller-supplied signal composes with it\n    // rather than replacing it (matching the client-side HTTP client), so a\n    // signal that never fires can't leave the request hanging forever.\n    const timeoutMs = 30_000\n    const controller = new AbortController()\n    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)\n    const onCallerAbort = () => controller.abort()\n    if (signal) {\n      if (signal.aborted) controller.abort()\n      else signal.addEventListener(\"abort\", onCallerAbort)\n    }\n    let res: Response\n    try {\n      res = await fetch(`${baseUrl.replace(/\\/$/, \"\")}/store/paypal/config`, {\n        headers: {\n          accept: \"application/json\",\n          ...(publishableApiKey\n            ? { \"x-publishable-api-key\": publishableApiKey }\n            : {}),\n        },\n        signal: controller.signal,\n      })\n    } finally {\n      clearTimeout(timeoutId)\n      if (signal) signal.removeEventListener(\"abort\", onCallerAbort)\n    }\n    if (!res.ok) {\n      return {}\n    }\n    const cfg = (await res.json()) as Record<string, unknown>\n    return {\n      paypal_title:\n        typeof cfg.paypal_title === \"string\" ? cfg.paypal_title : undefined,\n      card_title:\n        typeof cfg.card_title === \"string\" ? cfg.card_title : undefined,\n    }\n  } catch {\n    return {}\n  }\n}\n","/**\n * Provider ids registered by `@easypayment/medusa-payment-paypal`.\n *\n * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,\n * and the server-safe `order` entrypoint all re-export from here so the ids\n * can never drift between entrypoints.\n */\nexport const PAYPAL_WALLET_PROVIDER_ID = \"pp_paypal_paypal\" as const\nexport const PAYPAL_CARD_PROVIDER_ID = \"pp_paypal_card_paypal_card\" as const\n\nexport const PAYPAL_PROVIDER_IDS = [\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n] as const\n\nexport type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number]\n\n/** True when the provider id belongs to this PayPal plugin. */\nexport function isPayPalProviderId(\n  providerId?: string | null\n): providerId is PayPalProviderId {\n  if (!providerId) return false\n  return PAYPAL_PROVIDER_IDS.includes(providerId as PayPalProviderId)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOO,IAAM,4BAA4B;AAClC,IAAM,0BAA0B;AAEhC,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AACF;AAKO,SAAS,mBACd,YACgC;AAChC,MAAI,CAAC,WAAY,QAAO;AACxB,SAAO,oBAAoB,SAAS,UAA8B;AACpE;;;ADsBO,IAAM,uBAA0D;AAAA,EACrE,CAAC,yBAAyB,GAAG,EAAE,OAAO,SAAS;AAAA,EAC/C,CAAC,uBAAuB,GAAG,EAAE,OAAO,uBAAuB;AAC7D;AAoBO,SAAS,gBACd,YACA,UACA,QACQ;AACR,MAAI,CAAC,YAAY;AACf,WAAO,YAAY;AAAA,EACrB;AACA,MAAI,eAAe,2BAA2B;AAC5C,WACE,QAAQ,cAAc,KAAK,KAC3B,qBAAqB,yBAAyB,EAAE;AAAA,EAEpD;AACA,MAAI,eAAe,yBAAyB;AAC1C,WACE,QAAQ,YAAY,KAAK,KACzB,qBAAqB,uBAAuB,EAAE;AAAA,EAElD;AACA,SAAO,YAAY;AACrB;AASA,eAAsB,kBAAkB,MAIR;AAC9B,QAAM,EAAE,SAAS,mBAAmB,OAAO,IAAI;AAC/C,MAAI,CAAC,SAAS;AACZ,WAAO,CAAC;AAAA,EACV;AACA,MAAI;AAIF,UAAM,YAAY;AAClB,UAAM,aAAa,IAAI,gBAAgB;AACvC,UAAM,YAAY,WAAW,MAAM,WAAW,MAAM,GAAG,SAAS;AAChE,UAAM,gBAAgB,MAAM,WAAW,MAAM;AAC7C,QAAI,QAAQ;AACV,UAAI,OAAO,QAAS,YAAW,MAAM;AAAA,UAChC,QAAO,iBAAiB,SAAS,aAAa;AAAA,IACrD;AACA,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,GAAG,QAAQ,QAAQ,OAAO,EAAE,CAAC,wBAAwB;AAAA,QACrE,SAAS;AAAA,UACP,QAAQ;AAAA,UACR,GAAI,oBACA,EAAE,yBAAyB,kBAAkB,IAC7C,CAAC;AAAA,QACP;AAAA,QACA,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH,UAAE;AACA,mBAAa,SAAS;AACtB,UAAI,OAAQ,QAAO,oBAAoB,SAAS,aAAa;AAAA,IAC/D;AACA,QAAI,CAAC,IAAI,IAAI;AACX,aAAO,CAAC;AAAA,IACV;AACA,UAAM,MAAO,MAAM,IAAI,KAAK;AAC5B,WAAO;AAAA,MACL,cACE,OAAO,IAAI,iBAAiB,WAAW,IAAI,eAAe;AAAA,MAC5D,YACE,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,IAC1D;AAAA,EACF,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}

package/dist/order.d.cts

@@ -74,4 +74,4 @@ declare function fetchPayPalConfig(opts: {
     signal?: AbortSignal;
 }): Promise<PayPalConfigTitles>;
 
-export { PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, type PayPalConfigTitles, type PayPalPaymentInfo, fetchPayPalConfig, getPaymentLabel, isPayPalProviderId, paypalPaymentInfoMap };
+export { PAYPAL_CARD_PROVIDER_ID, PAYPAL_PROVIDER_IDS, PAYPAL_WALLET_PROVIDER_ID, type PayPalConfigTitles, type PayPalPaymentInfo, type PayPalProviderId, fetchPayPalConfig, getPaymentLabel, isPayPalProviderId, paypalPaymentInfoMap };

package/dist/order.d.ts

@@ -74,4 +74,4 @@ declare function fetchPayPalConfig(opts: {
     signal?: AbortSignal;
 }): Promise<PayPalConfigTitles>;
 
-export { PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, type PayPalConfigTitles, type PayPalPaymentInfo, fetchPayPalConfig, getPaymentLabel, isPayPalProviderId, paypalPaymentInfoMap };
+export { PAYPAL_CARD_PROVIDER_ID, PAYPAL_PROVIDER_IDS, PAYPAL_WALLET_PROVIDER_ID, type PayPalConfigTitles, type PayPalPaymentInfo, type PayPalProviderId, fetchPayPalConfig, getPaymentLabel, isPayPalProviderId, paypalPaymentInfoMap };

package/dist/order.mjs

@@ -34,12 +34,12 @@ async function fetchPayPalConfig(opts) {
   }
   try {
     const timeoutMs = 3e4;
-    let effectiveSignal = signal;
-    let timeoutId;
-    if (!signal) {
-      const controller = new AbortController();
-      timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-      effectiveSignal = controller.signal;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const onCallerAbort = () => controller.abort();
+    if (signal) {
+      if (signal.aborted) controller.abort();
+      else signal.addEventListener("abort", onCallerAbort);
     }
     let res;
     try {
@@ -48,10 +48,11 @@ async function fetchPayPalConfig(opts) {
           accept: "application/json",
           ...publishableApiKey ? { "x-publishable-api-key": publishableApiKey } : {}
         },
-        signal: effectiveSignal
+        signal: controller.signal
       });
     } finally {
-      if (timeoutId !== void 0) clearTimeout(timeoutId);
+      clearTimeout(timeoutId);
+      if (signal) signal.removeEventListener("abort", onCallerAbort);
     }
     if (!res.ok) {
       return {};
@@ -67,6 +68,7 @@ async function fetchPayPalConfig(opts) {
 }
 export {
   PAYPAL_CARD_PROVIDER_ID,
+  PAYPAL_PROVIDER_IDS,
   PAYPAL_WALLET_PROVIDER_ID,
   fetchPayPalConfig,
   getPaymentLabel,

package/dist/order.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts","../src/order.ts"],"sourcesContent":["/**\n * Provider ids registered by `@easypayment/medusa-payment-paypal`.\n *\n * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,\n * and the server-safe `order` entrypoint all re-export from here so the ids\n * can never drift between entrypoints.\n */\nexport const PAYPAL_WALLET_PROVIDER_ID = \"pp_paypal_paypal\" as const\nexport const PAYPAL_CARD_PROVIDER_ID = \"pp_paypal_card_paypal_card\" as const\n\nexport const PAYPAL_PROVIDER_IDS = [\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n] as const\n\nexport type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number]\n\n/** True when the provider id belongs to this PayPal plugin. */\nexport function isPayPalProviderId(\n  providerId?: string | null\n): providerId is PayPalProviderId {\n  if (!providerId) return false\n  return PAYPAL_PROVIDER_IDS.includes(providerId as PayPalProviderId)\n}\n","/**\n * Server-safe helpers for displaying PayPal payments on order / confirmation\n * pages.\n *\n * This module is intentionally free of React and any client-only code, so it\n * can be imported from Next.js **server components** (e.g. the order\n * confirmation page) without pulling in the checkout UI.\n *\n * @example\n * import { getPaymentLabel, fetchPayPalConfig } from \"@easypayment/medusa-paypal-ui/order\"\n *\n * // In the (async) server component that renders the payment method:\n * const titles = await fetchPayPalConfig({\n *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,\n *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,\n * })\n *\n * <Text>\n *   {getPaymentLabel(\n *     payment.provider_id,\n *     paymentInfoMap[payment.provider_id]?.title,\n *     titles\n *   )}\n * </Text>\n */\n\nimport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  isPayPalProviderId,\n} from \"./constants\"\n\nexport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  isPayPalProviderId,\n}\n\nexport type PayPalPaymentInfo = { title: string }\n\n/** Built-in fallback titles, used only when admin titles aren't supplied. */\nexport const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo> = {\n  [PAYPAL_WALLET_PROVIDER_ID]: { title: \"PayPal\" },\n  [PAYPAL_CARD_PROVIDER_ID]: { title: \"Credit or Debit Card\" },\n}\n\n/** Admin-configured titles, as returned by `GET /store/paypal/config`. */\nexport type PayPalConfigTitles = {\n  paypal_title?: string | null\n  card_title?: string | null\n}\n\n/**\n * Null-safe payment label resolver for order / confirmation pages.\n *\n * Precedence for the PayPal providers: **admin-configured title** (`titles`,\n * from {@link fetchPayPalConfig}) → built-in default. For any other provider:\n * `fallback` → raw id. Never throws on an unknown / missing provider, which is\n * what causes the common `Cannot read properties of undefined (reading 'title')`\n * crash on the order confirmation page.\n *\n * @param titles Admin titles so the order page shows the same labels configured\n *   in Medusa Admin → Settings → PayPal (e.g. a custom \"Credit or Debit Card\").\n */\nexport function getPaymentLabel(\n  providerId: string | undefined | null,\n  fallback?: string,\n  titles?: PayPalConfigTitles\n): string {\n  if (!providerId) {\n    return fallback ?? \"\"\n  }\n  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {\n    return (\n      titles?.paypal_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title\n    )\n  }\n  if (providerId === PAYPAL_CARD_PROVIDER_ID) {\n    return (\n      titles?.card_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title\n    )\n  }\n  return fallback ?? providerId\n}\n\n/**\n * Fetch the admin-configured PayPal titles from the storefront API\n * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).\n *\n * Returns `{}` on any error/network failure so callers can fall back to the\n * built-in defaults without their own try/catch.\n */\nexport async function fetchPayPalConfig(opts: {\n  baseUrl: string\n  publishableApiKey?: string\n  signal?: AbortSignal\n}): Promise<PayPalConfigTitles> {\n  const { baseUrl, publishableApiKey, signal } = opts\n  if (!baseUrl) {\n    return {}\n  }\n  try {\n    const timeoutMs = 30_000\n    let effectiveSignal = signal\n    let timeoutId: ReturnType<typeof setTimeout> | undefined\n    if (!signal) {\n      const controller = new AbortController()\n      timeoutId = setTimeout(() => controller.abort(), timeoutMs)\n      effectiveSignal = controller.signal\n    }\n    let res: Response\n    try {\n      res = await fetch(`${baseUrl.replace(/\\/$/, \"\")}/store/paypal/config`, {\n        headers: {\n          accept: \"application/json\",\n          ...(publishableApiKey\n            ? { \"x-publishable-api-key\": publishableApiKey }\n            : {}),\n        },\n        signal: effectiveSignal,\n      })\n    } finally {\n      if (timeoutId !== undefined) clearTimeout(timeoutId)\n    }\n    if (!res.ok) {\n      return {}\n    }\n    const cfg = (await res.json()) as Record<string, unknown>\n    return {\n      paypal_title:\n        typeof cfg.paypal_title === \"string\" ? cfg.paypal_title : undefined,\n      card_title:\n        typeof cfg.card_title === \"string\" ? cfg.card_title : undefined,\n    }\n  } catch {\n    return {}\n  }\n}\n"],"mappings":";AAOO,IAAM,4BAA4B;AAClC,IAAM,0BAA0B;AAEhC,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AACF;AAKO,SAAS,mBACd,YACgC;AAChC,MAAI,CAAC,WAAY,QAAO;AACxB,SAAO,oBAAoB,SAAS,UAA8B;AACpE;;;ACkBO,IAAM,uBAA0D;AAAA,EACrE,CAAC,yBAAyB,GAAG,EAAE,OAAO,SAAS;AAAA,EAC/C,CAAC,uBAAuB,GAAG,EAAE,OAAO,uBAAuB;AAC7D;AAoBO,SAAS,gBACd,YACA,UACA,QACQ;AACR,MAAI,CAAC,YAAY;AACf,WAAO,YAAY;AAAA,EACrB;AACA,MAAI,eAAe,2BAA2B;AAC5C,WACE,QAAQ,cAAc,KAAK,KAC3B,qBAAqB,yBAAyB,EAAE;AAAA,EAEpD;AACA,MAAI,eAAe,yBAAyB;AAC1C,WACE,QAAQ,YAAY,KAAK,KACzB,qBAAqB,uBAAuB,EAAE;AAAA,EAElD;AACA,SAAO,YAAY;AACrB;AASA,eAAsB,kBAAkB,MAIR;AAC9B,QAAM,EAAE,SAAS,mBAAmB,OAAO,IAAI;AAC/C,MAAI,CAAC,SAAS;AACZ,WAAO,CAAC;AAAA,EACV;AACA,MAAI;AACF,UAAM,YAAY;AAClB,QAAI,kBAAkB;AACtB,QAAI;AACJ,QAAI,CAAC,QAAQ;AACX,YAAM,aAAa,IAAI,gBAAgB;AACvC,kBAAY,WAAW,MAAM,WAAW,MAAM,GAAG,SAAS;AAC1D,wBAAkB,WAAW;AAAA,IAC/B;AACA,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,GAAG,QAAQ,QAAQ,OAAO,EAAE,CAAC,wBAAwB;AAAA,QACrE,SAAS;AAAA,UACP,QAAQ;AAAA,UACR,GAAI,oBACA,EAAE,yBAAyB,kBAAkB,IAC7C,CAAC;AAAA,QACP;AAAA,QACA,QAAQ;AAAA,MACV,CAAC;AAAA,IACH,UAAE;AACA,UAAI,cAAc,OAAW,cAAa,SAAS;AAAA,IACrD;AACA,QAAI,CAAC,IAAI,IAAI;AACX,aAAO,CAAC;AAAA,IACV;AACA,UAAM,MAAO,MAAM,IAAI,KAAK;AAC5B,WAAO;AAAA,MACL,cACE,OAAO,IAAI,iBAAiB,WAAW,IAAI,eAAe;AAAA,MAC5D,YACE,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,IAC1D;AAAA,EACF,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}
+{"version":3,"sources":["../src/constants.ts","../src/order.ts"],"sourcesContent":["/**\n * Provider ids registered by `@easypayment/medusa-payment-paypal`.\n *\n * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,\n * and the server-safe `order` entrypoint all re-export from here so the ids\n * can never drift between entrypoints.\n */\nexport const PAYPAL_WALLET_PROVIDER_ID = \"pp_paypal_paypal\" as const\nexport const PAYPAL_CARD_PROVIDER_ID = \"pp_paypal_card_paypal_card\" as const\n\nexport const PAYPAL_PROVIDER_IDS = [\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n] as const\n\nexport type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number]\n\n/** True when the provider id belongs to this PayPal plugin. */\nexport function isPayPalProviderId(\n  providerId?: string | null\n): providerId is PayPalProviderId {\n  if (!providerId) return false\n  return PAYPAL_PROVIDER_IDS.includes(providerId as PayPalProviderId)\n}\n","/**\n * Server-safe helpers for displaying PayPal payments on order / confirmation\n * pages.\n *\n * This module is intentionally free of React and any client-only code, so it\n * can be imported from Next.js **server components** (e.g. the order\n * confirmation page) without pulling in the checkout UI.\n *\n * @example\n * import { getPaymentLabel, fetchPayPalConfig } from \"@easypayment/medusa-paypal-ui/order\"\n *\n * // In the (async) server component that renders the payment method:\n * const titles = await fetchPayPalConfig({\n *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,\n *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,\n * })\n *\n * <Text>\n *   {getPaymentLabel(\n *     payment.provider_id,\n *     paymentInfoMap[payment.provider_id]?.title,\n *     titles\n *   )}\n * </Text>\n */\n\nimport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  PAYPAL_PROVIDER_IDS,\n  isPayPalProviderId,\n} from \"./constants\"\nimport type { PayPalProviderId } from \"./constants\"\n\nexport {\n  PAYPAL_WALLET_PROVIDER_ID,\n  PAYPAL_CARD_PROVIDER_ID,\n  PAYPAL_PROVIDER_IDS,\n  isPayPalProviderId,\n}\nexport type { PayPalProviderId }\n\nexport type PayPalPaymentInfo = { title: string }\n\n/** Built-in fallback titles, used only when admin titles aren't supplied. */\nexport const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo> = {\n  [PAYPAL_WALLET_PROVIDER_ID]: { title: \"PayPal\" },\n  [PAYPAL_CARD_PROVIDER_ID]: { title: \"Credit or Debit Card\" },\n}\n\n/** Admin-configured titles, as returned by `GET /store/paypal/config`. */\nexport type PayPalConfigTitles = {\n  paypal_title?: string | null\n  card_title?: string | null\n}\n\n/**\n * Null-safe payment label resolver for order / confirmation pages.\n *\n * Precedence for the PayPal providers: **admin-configured title** (`titles`,\n * from {@link fetchPayPalConfig}) → built-in default. For any other provider:\n * `fallback` → raw id. Never throws on an unknown / missing provider, which is\n * what causes the common `Cannot read properties of undefined (reading 'title')`\n * crash on the order confirmation page.\n *\n * @param titles Admin titles so the order page shows the same labels configured\n *   in Medusa Admin → Settings → PayPal (e.g. a custom \"Credit or Debit Card\").\n */\nexport function getPaymentLabel(\n  providerId: string | undefined | null,\n  fallback?: string,\n  titles?: PayPalConfigTitles\n): string {\n  if (!providerId) {\n    return fallback ?? \"\"\n  }\n  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {\n    return (\n      titles?.paypal_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title\n    )\n  }\n  if (providerId === PAYPAL_CARD_PROVIDER_ID) {\n    return (\n      titles?.card_title?.trim() ||\n      paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title\n    )\n  }\n  return fallback ?? providerId\n}\n\n/**\n * Fetch the admin-configured PayPal titles from the storefront API\n * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).\n *\n * Returns `{}` on any error/network failure so callers can fall back to the\n * built-in defaults without their own try/catch.\n */\nexport async function fetchPayPalConfig(opts: {\n  baseUrl: string\n  publishableApiKey?: string\n  signal?: AbortSignal\n}): Promise<PayPalConfigTitles> {\n  const { baseUrl, publishableApiKey, signal } = opts\n  if (!baseUrl) {\n    return {}\n  }\n  try {\n    // Always arm the timeout — a caller-supplied signal composes with it\n    // rather than replacing it (matching the client-side HTTP client), so a\n    // signal that never fires can't leave the request hanging forever.\n    const timeoutMs = 30_000\n    const controller = new AbortController()\n    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)\n    const onCallerAbort = () => controller.abort()\n    if (signal) {\n      if (signal.aborted) controller.abort()\n      else signal.addEventListener(\"abort\", onCallerAbort)\n    }\n    let res: Response\n    try {\n      res = await fetch(`${baseUrl.replace(/\\/$/, \"\")}/store/paypal/config`, {\n        headers: {\n          accept: \"application/json\",\n          ...(publishableApiKey\n            ? { \"x-publishable-api-key\": publishableApiKey }\n            : {}),\n        },\n        signal: controller.signal,\n      })\n    } finally {\n      clearTimeout(timeoutId)\n      if (signal) signal.removeEventListener(\"abort\", onCallerAbort)\n    }\n    if (!res.ok) {\n      return {}\n    }\n    const cfg = (await res.json()) as Record<string, unknown>\n    return {\n      paypal_title:\n        typeof cfg.paypal_title === \"string\" ? cfg.paypal_title : undefined,\n      card_title:\n        typeof cfg.card_title === \"string\" ? cfg.card_title : undefined,\n    }\n  } catch {\n    return {}\n  }\n}\n"],"mappings":";AAOO,IAAM,4BAA4B;AAClC,IAAM,0BAA0B;AAEhC,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AACF;AAKO,SAAS,mBACd,YACgC;AAChC,MAAI,CAAC,WAAY,QAAO;AACxB,SAAO,oBAAoB,SAAS,UAA8B;AACpE;;;ACsBO,IAAM,uBAA0D;AAAA,EACrE,CAAC,yBAAyB,GAAG,EAAE,OAAO,SAAS;AAAA,EAC/C,CAAC,uBAAuB,GAAG,EAAE,OAAO,uBAAuB;AAC7D;AAoBO,SAAS,gBACd,YACA,UACA,QACQ;AACR,MAAI,CAAC,YAAY;AACf,WAAO,YAAY;AAAA,EACrB;AACA,MAAI,eAAe,2BAA2B;AAC5C,WACE,QAAQ,cAAc,KAAK,KAC3B,qBAAqB,yBAAyB,EAAE;AAAA,EAEpD;AACA,MAAI,eAAe,yBAAyB;AAC1C,WACE,QAAQ,YAAY,KAAK,KACzB,qBAAqB,uBAAuB,EAAE;AAAA,EAElD;AACA,SAAO,YAAY;AACrB;AASA,eAAsB,kBAAkB,MAIR;AAC9B,QAAM,EAAE,SAAS,mBAAmB,OAAO,IAAI;AAC/C,MAAI,CAAC,SAAS;AACZ,WAAO,CAAC;AAAA,EACV;AACA,MAAI;AAIF,UAAM,YAAY;AAClB,UAAM,aAAa,IAAI,gBAAgB;AACvC,UAAM,YAAY,WAAW,MAAM,WAAW,MAAM,GAAG,SAAS;AAChE,UAAM,gBAAgB,MAAM,WAAW,MAAM;AAC7C,QAAI,QAAQ;AACV,UAAI,OAAO,QAAS,YAAW,MAAM;AAAA,UAChC,QAAO,iBAAiB,SAAS,aAAa;AAAA,IACrD;AACA,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,GAAG,QAAQ,QAAQ,OAAO,EAAE,CAAC,wBAAwB;AAAA,QACrE,SAAS;AAAA,UACP,QAAQ;AAAA,UACR,GAAI,oBACA,EAAE,yBAAyB,kBAAkB,IAC7C,CAAC;AAAA,QACP;AAAA,QACA,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH,UAAE;AACA,mBAAa,SAAS;AACtB,UAAI,OAAQ,QAAO,oBAAoB,SAAS,aAAa;AAAA,IAC/D;AACA,QAAI,CAAC,IAAI,IAAI;AACX,aAAO,CAAC;AAAA,IACV;AACA,UAAM,MAAO,MAAM,IAAI,KAAK;AAC5B,WAAO;AAAA,MACL,cACE,OAAO,IAAI,iBAAiB,WAAW,IAAI,eAAe;AAAA,MAC5D,YACE,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,IAC1D;AAAA,EACF,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@easypayment/medusa-paypal-ui",
-  "version": "1.2.8",
-  "description": "Enterprise Gold PayPal UI module for Medusa v2 storefront (Next.js)",
+  "version": "1.3.0",
+  "description": "PayPal checkout UI for Medusa v2 storefronts — PayPal Buttons, hosted card fields, and server-safe order helpers for Next.js and React. Companion to @easypayment/medusa-payment-paypal.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -52,13 +52,21 @@
     "@paypal/react-paypal-js": "^9.2.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@testing-library/jest-dom": "^6.5.0",
     "@testing-library/react": "^16.0.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.5",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^24.0.0",
+    "prettier": "^3.6.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
+    "typescript-eslint": "^8.71.1",
     "vitest": "^2.0.5"
   },
   "scripts": {
@@ -67,10 +75,41 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint src test"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/easypaymentplugins/medusa-paypal-ui"
-  }
+  },
+  "homepage": "https://github.com/easypaymentplugins/medusa-paypal-ui#readme",
+  "bugs": {
+    "url": "https://github.com/easypaymentplugins/medusa-paypal-ui/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "medusa",
+    "medusajs",
+    "medusa-v2",
+    "medusa-plugin",
+    "medusa-storefront",
+    "paypal",
+    "paypal-checkout",
+    "paypal-buttons",
+    "card-fields",
+    "payment",
+    "payments",
+    "checkout",
+    "ecommerce",
+    "nextjs",
+    "react",
+    "credit-card"
+  ]
 }

package/src/adapters/MedusaNextPayPalAdapter.tsx

@@ -10,14 +10,12 @@ import {
   PAYPAL_CARD_PROVIDER_ID as DEFAULT_PAYPAL_CARD_PROVIDER_ID,
 } from "../constants"
 import { usePayPalConfig } from "../hooks/usePayPalConfig"
-
-const SPIN_STYLE = `@keyframes _pp_spin { to { transform: rotate(360deg) } }`
+import { AnimationStyles } from "../components/internal/ui"
 
 function PayPalLoadingCard() {
   return (
     <div
       role="status"
-      aria-label="Connecting to PayPal"
       style={{
         display: "flex",
         alignItems: "center",
@@ -28,15 +26,16 @@ function PayPalLoadingCard() {
         borderRadius: 10,
       }}
     >
-      <style>{SPIN_STYLE}</style>
+      <AnimationStyles />
       <div
+        className="_pp-spin-sm"
+        aria-hidden="true"
         style={{
           width: 22,
           height: 22,
           borderRadius: "50%",
           border: "2.5px solid #e5e7eb",
           borderTopColor: "#0070ba",
-          animation: "_pp_spin .7s linear infinite",
           flexShrink: 0,
         }}
       />
@@ -52,7 +51,13 @@ function PayPalLoadingCard() {
   )
 }
 
-function PayPalErrorCard({ message }: { message: string }) {
+function PayPalErrorCard({
+  message,
+  onRetry,
+}: {
+  message: string
+  onRetry?: () => void
+}) {
   return (
     <div
       role="alert"
@@ -66,6 +71,26 @@ function PayPalErrorCard({ message }: { message: string }) {
       }}
     >
       {message}
+      {onRetry && (
+        <button
+          type="button"
+          onClick={onRetry}
+          style={{
+            display: "block",
+            marginTop: 8,
+            padding: "6px 14px",
+            background: "#ffffff",
+            color: "#b91c1c",
+            border: "1px solid #fecaca",
+            borderRadius: 6,
+            fontSize: 13,
+            fontWeight: 500,
+            cursor: "pointer",
+          }}
+        >
+          Try again
+        </button>
+      )}
     </div>
   )
 }
@@ -99,13 +124,20 @@ export type MedusaNextPayPalAdapterProps = {
   selectedProviderId: string | null | undefined
   baseUrl: string
   publishableApiKey?: string
+  /** Forwarded to every API call — see `HttpOptions.credentials`. */
+  credentials?: RequestCredentials
+  /**
+   * The cart's currency code (e.g. "usd"). Recommended: busts the config
+   * cache when the buyer switches region/currency on the same cart.
+   */
+  currencyCode?: string
   providerIds?: {
     paypal?: string
     paypalCard?: string
   }
-  onSuccess?: (cartId: string) => void
+  onSuccess?: (cartId: string) => void | Promise<void>
   onError?: (message: string) => void
-  onPaid?: (result: unknown) => void
+  onPaid?: (result: unknown) => void | Promise<void>
 }
 
 export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
@@ -114,6 +146,8 @@ export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
     selectedProviderId,
     baseUrl,
     publishableApiKey,
+    credentials,
+    currencyCode,
     providerIds,
     onSuccess,
     onError,
@@ -128,10 +162,12 @@ export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
     selectedProviderId === paypalProviderId ||
     selectedProviderId === paypalCardProviderId
 
-  const { config, loading, error } = usePayPalConfig({
+  const { config, loading, error, retry } = usePayPalConfig({
     baseUrl,
     publishableApiKey,
+    credentials,
     cartId,
+    currencyCode,
     enabled: shouldRender,
   })
 
@@ -147,7 +183,7 @@ export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
 
   if (loading) return <PayPalLoadingCard />
 
-  if (error) return <PayPalErrorCard message={error} />
+  if (error) return <PayPalErrorCard message={error} onRetry={retry} />
 
   if (!config) return null
 
@@ -175,6 +211,7 @@ export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
           <PayPalAdvancedCard
             baseUrl={baseUrl}
             publishableApiKey={publishableApiKey}
+            credentials={credentials}
             cartId={cartId}
             config={config}
             onPaid={handlePaid}
@@ -184,6 +221,7 @@ export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
           <PayPalSmartButtons
             baseUrl={baseUrl}
             publishableApiKey={publishableApiKey}
+            credentials={credentials}
             cartId={cartId}
             config={config}
             onPaid={handlePaid}

package/src/client/config-cache.ts

@@ -0,0 +1,96 @@
+import type { PayPalConfig } from "./types"
+
+/**
+ * Shared module-level cache for `/store/paypal/config` responses.
+ *
+ * Both `usePayPalConfig` and `usePayPalPaymentMethods` read the same endpoint;
+ * sharing one cache (and one in-flight promise per key) means a checkout page
+ * that mounts both hooks issues a single network request instead of two.
+ *
+ * The key includes the publishable API key and an optional currency code so a
+ * region/currency switch on the same cart busts the cache instead of serving
+ * a stale config for up to the TTL.
+ */
+
+type Entry = { config: PayPalConfig; at: number }
+
+const MAX_CACHE_ENTRIES = 50
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+/** Separator that cannot appear in URLs, API keys, cart ids, or currencies. */
+const SEP = "\u0001"
+
+const cache = new Map<string, Entry>()
+const inflight = new Map<string, Promise<PayPalConfig>>()
+
+export function configCacheKey(args: {
+  baseUrl: string
+  publishableApiKey?: string
+  cartId?: string
+  currencyCode?: string
+}): string {
+  return [
+    args.baseUrl,
+    args.publishableApiKey ?? "",
+    args.cartId ?? "",
+    (args.currencyCode ?? "").toLowerCase(),
+  ].join(SEP)
+}
+
+export function getCachedPayPalConfig(key: string): PayPalConfig | null {
+  const hit = cache.get(key)
+  if (!hit) return null
+  if (Date.now() - hit.at >= CACHE_TTL_MS) {
+    cache.delete(key)
+    return null
+  }
+  return hit.config
+}
+
+/**
+ * Drop cached configs — all of them, or only the entries for one cart.
+ * Call after anything that changes what the config endpoint would return
+ * (region/currency switch, plugin settings change).
+ */
+export function invalidatePayPalConfigCache(cartId?: string): void {
+  if (cartId === undefined) {
+    cache.clear()
+    return
+  }
+  for (const key of [...cache.keys()]) {
+    if (key.split(SEP)[2] === cartId) cache.delete(key)
+  }
+}
+
+/**
+ * Fetch a config, deduplicating concurrent requests for the same key.
+ *
+ * The fetcher deliberately receives no caller AbortSignal: the resulting
+ * promise may be shared by several mounted hooks, so one unmounting must not
+ * cancel the others. Callers discard the result after unmount instead; the
+ * HTTP client's own timeout bounds the request.
+ */
+export function fetchPayPalConfigShared(
+  key: string,
+  fetcher: () => Promise<PayPalConfig>
+): Promise<PayPalConfig> {
+  const existing = inflight.get(key)
+  if (existing) return existing
+
+  const p = (async () => {
+    try {
+      const config = await fetcher()
+      if (cache.size >= MAX_CACHE_ENTRIES && !cache.has(key)) {
+        const oldest = cache.keys().next().value
+        if (oldest !== undefined) cache.delete(oldest)
+      }
+      cache.set(key, { config, at: Date.now() })
+      return config
+    } finally {
+      inflight.delete(key)
+    }
+  })()
+
+  inflight.set(key, p)
+  return p
+}

package/src/client/http.ts

@@ -9,6 +9,12 @@ export type HttpOptions = {
    * credentialed requests against a wildcard CORS origin outright.
    */
   credentials?: RequestCredentials
+  /**
+   * Per-request timeout in milliseconds. Covers the full request including
+   * reading the body. Defaults to 30 000. A caller-supplied AbortSignal
+   * composes with (never replaces) this timeout.
+   */
+  timeoutMs?: number
 }
 
 export type RequestOptions = {
@@ -21,7 +27,13 @@ export type RequestOptions = {
   retries?: number
 }
 
-class HttpError extends Error {
+/**
+ * Error thrown for HTTP-level failures (non-2xx responses and malformed
+ * response bodies). `status` carries the HTTP status code so callers can
+ * branch on it (e.g. 403 → "PayPal is disabled") instead of matching
+ * localized/backend-authored message text.
+ */
+export class HttpError extends Error {
   status: number
   constructor(message: string, status: number) {
     super(message)
@@ -96,7 +108,7 @@ export function createHttpClient(opts: HttpOptions) {
     // connection. The timer also covers reading the body: a server that sends
     // headers then stalls the response stream would otherwise hang the
     // request indefinitely with the old header-only timeout.
-    const timeoutMs = 30_000
+    const timeoutMs = opts.timeoutMs ?? 30_000
     const controller = new AbortController()
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
     const callerSignal = init?.signal ?? null
@@ -166,17 +178,24 @@ export function createHttpClient(opts: HttpOptions) {
       )
     }
 
+    // Malformed success responses are HttpError (carrying the 2xx status) so
+    // the retry logic treats them as non-transient — a server answering 200
+    // with HTML will answer the same way on a retry.
     const contentType = res.headers.get("content-type") || ""
     if (!contentType.includes("application/json")) {
-      throw new Error(
-        `[PayPal] Unexpected non-JSON response (${contentType}) from ${path}`
+      throw new HttpError(
+        `[PayPal] Unexpected non-JSON response (${contentType}) from ${path}`,
+        res.status
       )
     }
 
     try {
       return JSON.parse(text) as T
     } catch {
-      throw new Error(`[PayPal] Failed to parse JSON response from ${path}`)
+      throw new HttpError(
+        `[PayPal] Failed to parse JSON response from ${path}`,
+        res.status
+      )
     }
   }
 

package/src/client/paypal.ts

@@ -21,12 +21,29 @@ export function generateIdempotencyKey(): string {
   return `pp-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`
 }
 
+export type MarkPaymentCompleteOptions = {
+  publishableApiKey?: string
+  credentials?: RequestCredentials
+  timeoutMs?: number
+  signal?: AbortSignal
+}
+
 export async function markPaymentComplete(
   baseUrl: string,
   cartId: string,
-  publishableApiKey?: string
+  /** Publishable API key string (legacy signature) or an options object. */
+  options?: string | MarkPaymentCompleteOptions
 ): Promise<Record<string, unknown>> {
-  const http = createHttpClient({ baseUrl, publishableApiKey })
+  const opts: MarkPaymentCompleteOptions =
+    typeof options === "string"
+      ? { publishableApiKey: options }
+      : (options ?? {})
+  const http = createHttpClient({
+    baseUrl,
+    publishableApiKey: opts.publishableApiKey,
+    credentials: opts.credentials,
+    timeoutMs: opts.timeoutMs,
+  })
   // Retry transient failures: /store/paypal-complete is idempotent (it returns
   // already_completed for a finished cart), so a network blip right after
   // capture — the classic "captured but cart not completed" gap — is retried
@@ -37,6 +54,7 @@ export async function markPaymentComplete(
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ cart_id: cartId }),
+      signal: opts.signal,
     },
     { retries: 3 }
   )
@@ -51,11 +69,13 @@ export function createPayPalStoreApi(opts: HttpOptions) {
       return http.request<PayPalConfig>(`/store/paypal/config${q}`, { signal })
     },
 
-    getSettings() {
-      return http.request<PayPalSettingsResponse>(`/store/paypal/settings`)
+    getSettings(signal?: AbortSignal) {
+      return http.request<PayPalSettingsResponse>(`/store/paypal/settings`, {
+        signal,
+      })
     },
 
-    createOrder(cartId: string, isCardPayment = false) {
+    createOrder(cartId: string, isCardPayment = false, signal?: AbortSignal) {
       return http.request<{ id: string }>(`/store/paypal/create-order`, {
         method: "POST",
         headers: {
@@ -69,10 +89,11 @@ export function createPayPalStoreApi(opts: HttpOptions) {
           cart_id: cartId,
           is_card_payment: isCardPayment,
         }),
+        signal,
       })
     },
 
-    captureOrder(cartId: string, orderId: string) {
+    captureOrder(cartId: string, orderId: string, signal?: AbortSignal) {
       // Retry transient failures: capture-order is idempotent server-side (it
       // short-circuits on an existing capture and PayPal dedupes by request id),
       // so a network blip during capture doesn't leave the buyer's funds
@@ -83,6 +104,7 @@ export function createPayPalStoreApi(opts: HttpOptions) {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ cart_id: cartId, order_id: orderId }),
+          signal,
         },
         { retries: 2 }
       )