@easypayment/medusa-paypal-ui 1.2.8 → 1.3.0

package/dist/index.d.cts

@@ -53,6 +53,34 @@ 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;
+};
+type RequestOptions = {
+    /**
+     * Number of extra attempts on transient failures (network error, timeout,
+     * HTTP 429/5xx). Only use for idempotent calls — the PayPal capture/complete
+     * endpoints are idempotent server-side, so a retried request after a network
+     * blip re-uses the existing result instead of duplicating work. Default 0.
+     */
+    retries?: number;
+};
+/**
+ * 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.
+ */
+declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+declare function createHttpClient(opts: HttpOptions): {
+    request: <T>(path: string, init?: RequestInit, reqOpts?: RequestOptions) => Promise<T>;
 };
 
 /**
@@ -66,26 +94,64 @@ type HttpOptions = {
  * stored-order staleness check, not by this key.
  */
 declare function generateIdempotencyKey(): string;
-declare function markPaymentComplete(baseUrl: string, cartId: string, publishableApiKey?: string): Promise<Record<string, unknown>>;
+type MarkPaymentCompleteOptions = {
+    publishableApiKey?: string;
+    credentials?: RequestCredentials;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+declare function markPaymentComplete(baseUrl: string, cartId: string, 
+/** Publishable API key string (legacy signature) or an options object. */
+options?: string | MarkPaymentCompleteOptions): Promise<Record<string, unknown>>;
 declare function createPayPalStoreApi(opts: HttpOptions): {
     getConfig(cartId?: string, signal?: AbortSignal): Promise<PayPalConfig>;
-    getSettings(): Promise<PayPalSettingsResponse>;
-    createOrder(cartId: string, isCardPayment?: boolean): Promise<{
+    getSettings(signal?: AbortSignal): Promise<PayPalSettingsResponse>;
+    createOrder(cartId: string, isCardPayment?: boolean, signal?: AbortSignal): Promise<{
         id: string;
     }>;
-    captureOrder(cartId: string, orderId: string): Promise<Record<string, unknown>>;
+    captureOrder(cartId: string, orderId: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
 };
 
+/**
+ * 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).
+ */
+declare function invalidatePayPalConfigCache(cartId?: string): void;
+
+/**
+ * Provider ids registered by `@easypayment/medusa-payment-paypal`.
+ *
+ * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,
+ * and the server-safe `order` entrypoint all re-export from here so the ids
+ * can never drift between entrypoints.
+ */
+declare const PAYPAL_WALLET_PROVIDER_ID: "pp_paypal_paypal";
+declare const PAYPAL_CARD_PROVIDER_ID: "pp_paypal_card_paypal_card";
+declare const PAYPAL_PROVIDER_IDS: readonly ["pp_paypal_paypal", "pp_paypal_card_paypal_card"];
+type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number];
+/** True when the provider id belongs to this PayPal plugin. */
+declare function isPayPalProviderId(providerId?: string | null): providerId is PayPalProviderId;
+
 type Args$1 = {
     baseUrl: string;
     publishableApiKey?: string;
     cartId?: string;
+    /**
+     * The cart's current currency code (e.g. "usd"). Optional, but recommended:
+     * when provided it becomes part of the cache key, so a region/currency
+     * switch on the same cart refetches the config instead of serving a stale
+     * one for up to 5 minutes.
+     */
+    currencyCode?: string;
+    credentials?: RequestCredentials;
     enabled?: boolean;
 };
-declare function usePayPalConfig({ baseUrl, publishableApiKey, cartId, enabled, }: Args$1): {
+declare function usePayPalConfig({ baseUrl, publishableApiKey, cartId, currencyCode, credentials, enabled, }: Args$1): {
     config: PayPalConfig | null;
     loading: boolean;
     error: string | null;
+    retry: () => void;
 };
 
 declare function PayPalProvider(props: {
@@ -102,18 +168,22 @@ declare function PayPalCurrencyNotice({ config }: {
 declare function PayPalSmartButtons(props: {
     baseUrl: string;
     publishableApiKey?: string;
+    /** Forwarded to every API call — see `HttpOptions.credentials`. */
+    credentials?: RequestCredentials;
     cartId: string;
     config: PayPalConfig;
-    onPaid?: (result: Record<string, unknown>) => void;
+    onPaid?: (result: Record<string, unknown>) => void | Promise<void>;
     onError?: (message: string) => void;
 }): React.JSX.Element | null;
 
 declare function PayPalAdvancedCard(props: {
     baseUrl: string;
     publishableApiKey?: string;
+    /** Forwarded to every API call — see `HttpOptions.credentials`. */
+    credentials?: RequestCredentials;
     cartId: string;
     config: PayPalConfig;
-    onPaid?: (result: Record<string, unknown>) => void;
+    onPaid?: (result: Record<string, unknown>) => void | Promise<void>;
     onError?: (message: string) => void;
 }): React.JSX.Element | null;
 
@@ -122,39 +192,39 @@ 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>;
 };
 declare function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps): React.JSX.Element | null;
 
-/**
- * Provider ids registered by `@easypayment/medusa-payment-paypal`.
- *
- * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,
- * and the server-safe `order` entrypoint all re-export from here so the ids
- * can never drift between entrypoints.
- */
-declare const PAYPAL_WALLET_PROVIDER_ID: "pp_paypal_paypal";
-declare const PAYPAL_CARD_PROVIDER_ID: "pp_paypal_card_paypal_card";
-declare const PAYPAL_PROVIDER_IDS: readonly ["pp_paypal_paypal", "pp_paypal_card_paypal_card"];
-type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number];
-/** True when the provider id belongs to this PayPal plugin. */
-declare function isPayPalProviderId(providerId?: string | null): providerId is PayPalProviderId;
-
 type PayPalPaymentSectionProps = {
     cartId: string;
     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;
     sessionLoading?: boolean;
-    onSuccess?: (cartId: string) => void;
+    onSuccess?: (cartId: string) => void | Promise<void>;
     onError?: (message: string) => void;
-    onPaid?: (result: unknown) => void;
+    onPaid?: (result: unknown) => void | Promise<void>;
 };
 /**
  * Drop-in PayPal payment section for a Medusa checkout.
@@ -164,12 +234,15 @@ type PayPalPaymentSectionProps = {
  * component pins the default provider ids and adds the `sessionLoading` gate
  * shown while the storefront is still creating the payment session.
  */
-declare function PayPalPaymentSection({ cartId, selectedProviderId, baseUrl, publishableApiKey, sessionLoading, onSuccess, onError, onPaid, }: PayPalPaymentSectionProps): React.JSX.Element | null;
+declare function PayPalPaymentSection({ cartId, selectedProviderId, baseUrl, publishableApiKey, credentials, currencyCode, sessionLoading, onSuccess, onError, onPaid, }: PayPalPaymentSectionProps): React.JSX.Element | null;
 
 type Args = {
     baseUrl: string;
     publishableApiKey?: string;
     cartId?: string;
+    /** See `usePayPalConfig` — include to bust the cache on currency switches. */
+    currencyCode?: string;
+    credentials?: RequestCredentials;
     enabled?: boolean;
 };
 type Result = {
@@ -186,7 +259,7 @@ type Result = {
      */
     error: string | null;
 };
-declare function usePayPalPaymentMethods({ baseUrl, publishableApiKey, cartId, enabled, }: Args): Result;
+declare function usePayPalPaymentMethods({ baseUrl, publishableApiKey, cartId, currencyCode, credentials, enabled, }: Args): Result;
 
 declare function showProcessingOverlay(): void;
 declare function hideProcessingOverlay(): void;
@@ -210,4 +283,4 @@ declare function markCartCaptured(cartId: string): void;
 declare function wasCartCaptured(cartId: string): boolean;
 declare function clearCartCaptured(cartId: string): void;
 
-export { MedusaNextPayPalAdapter, type MedusaNextPayPalAdapterProps, PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, PayPalAdvancedCard, type PayPalConfig, PayPalCurrencyNotice, PayPalPaymentSection, type PayPalPaymentSectionProps, PayPalProvider, type PayPalSettingsResponse, PayPalSmartButtons, clearCartCaptured, createPayPalStoreApi, generateIdempotencyKey, hideProcessingOverlay, isPayPalProviderId, markCartCaptured, markPaymentComplete, showProcessingOverlay, usePayPalConfig, usePayPalPaymentMethods, wasCartCaptured };
+export { HttpError, type HttpOptions, type MarkPaymentCompleteOptions, MedusaNextPayPalAdapter, type MedusaNextPayPalAdapterProps, PAYPAL_CARD_PROVIDER_ID, PAYPAL_PROVIDER_IDS, PAYPAL_WALLET_PROVIDER_ID, PayPalAdvancedCard, type PayPalConfig, PayPalCurrencyNotice, PayPalPaymentSection, type PayPalPaymentSectionProps, PayPalProvider, type PayPalProviderId, type PayPalSettingsResponse, PayPalSmartButtons, type RequestOptions, clearCartCaptured, createHttpClient, createPayPalStoreApi, generateIdempotencyKey, hideProcessingOverlay, invalidatePayPalConfigCache, isPayPalProviderId, markCartCaptured, markPaymentComplete, showProcessingOverlay, usePayPalConfig, usePayPalPaymentMethods, wasCartCaptured };

package/dist/index.d.ts

@@ -53,6 +53,34 @@ 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;
+};
+type RequestOptions = {
+    /**
+     * Number of extra attempts on transient failures (network error, timeout,
+     * HTTP 429/5xx). Only use for idempotent calls — the PayPal capture/complete
+     * endpoints are idempotent server-side, so a retried request after a network
+     * blip re-uses the existing result instead of duplicating work. Default 0.
+     */
+    retries?: number;
+};
+/**
+ * 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.
+ */
+declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+declare function createHttpClient(opts: HttpOptions): {
+    request: <T>(path: string, init?: RequestInit, reqOpts?: RequestOptions) => Promise<T>;
 };
 
 /**
@@ -66,26 +94,64 @@ type HttpOptions = {
  * stored-order staleness check, not by this key.
  */
 declare function generateIdempotencyKey(): string;
-declare function markPaymentComplete(baseUrl: string, cartId: string, publishableApiKey?: string): Promise<Record<string, unknown>>;
+type MarkPaymentCompleteOptions = {
+    publishableApiKey?: string;
+    credentials?: RequestCredentials;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+declare function markPaymentComplete(baseUrl: string, cartId: string, 
+/** Publishable API key string (legacy signature) or an options object. */
+options?: string | MarkPaymentCompleteOptions): Promise<Record<string, unknown>>;
 declare function createPayPalStoreApi(opts: HttpOptions): {
     getConfig(cartId?: string, signal?: AbortSignal): Promise<PayPalConfig>;
-    getSettings(): Promise<PayPalSettingsResponse>;
-    createOrder(cartId: string, isCardPayment?: boolean): Promise<{
+    getSettings(signal?: AbortSignal): Promise<PayPalSettingsResponse>;
+    createOrder(cartId: string, isCardPayment?: boolean, signal?: AbortSignal): Promise<{
         id: string;
     }>;
-    captureOrder(cartId: string, orderId: string): Promise<Record<string, unknown>>;
+    captureOrder(cartId: string, orderId: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
 };
 
+/**
+ * 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).
+ */
+declare function invalidatePayPalConfigCache(cartId?: string): void;
+
+/**
+ * Provider ids registered by `@easypayment/medusa-payment-paypal`.
+ *
+ * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,
+ * and the server-safe `order` entrypoint all re-export from here so the ids
+ * can never drift between entrypoints.
+ */
+declare const PAYPAL_WALLET_PROVIDER_ID: "pp_paypal_paypal";
+declare const PAYPAL_CARD_PROVIDER_ID: "pp_paypal_card_paypal_card";
+declare const PAYPAL_PROVIDER_IDS: readonly ["pp_paypal_paypal", "pp_paypal_card_paypal_card"];
+type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number];
+/** True when the provider id belongs to this PayPal plugin. */
+declare function isPayPalProviderId(providerId?: string | null): providerId is PayPalProviderId;
+
 type Args$1 = {
     baseUrl: string;
     publishableApiKey?: string;
     cartId?: string;
+    /**
+     * The cart's current currency code (e.g. "usd"). Optional, but recommended:
+     * when provided it becomes part of the cache key, so a region/currency
+     * switch on the same cart refetches the config instead of serving a stale
+     * one for up to 5 minutes.
+     */
+    currencyCode?: string;
+    credentials?: RequestCredentials;
     enabled?: boolean;
 };
-declare function usePayPalConfig({ baseUrl, publishableApiKey, cartId, enabled, }: Args$1): {
+declare function usePayPalConfig({ baseUrl, publishableApiKey, cartId, currencyCode, credentials, enabled, }: Args$1): {
     config: PayPalConfig | null;
     loading: boolean;
     error: string | null;
+    retry: () => void;
 };
 
 declare function PayPalProvider(props: {
@@ -102,18 +168,22 @@ declare function PayPalCurrencyNotice({ config }: {
 declare function PayPalSmartButtons(props: {
     baseUrl: string;
     publishableApiKey?: string;
+    /** Forwarded to every API call — see `HttpOptions.credentials`. */
+    credentials?: RequestCredentials;
     cartId: string;
     config: PayPalConfig;
-    onPaid?: (result: Record<string, unknown>) => void;
+    onPaid?: (result: Record<string, unknown>) => void | Promise<void>;
     onError?: (message: string) => void;
 }): React.JSX.Element | null;
 
 declare function PayPalAdvancedCard(props: {
     baseUrl: string;
     publishableApiKey?: string;
+    /** Forwarded to every API call — see `HttpOptions.credentials`. */
+    credentials?: RequestCredentials;
     cartId: string;
     config: PayPalConfig;
-    onPaid?: (result: Record<string, unknown>) => void;
+    onPaid?: (result: Record<string, unknown>) => void | Promise<void>;
     onError?: (message: string) => void;
 }): React.JSX.Element | null;
 
@@ -122,39 +192,39 @@ 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>;
 };
 declare function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps): React.JSX.Element | null;
 
-/**
- * Provider ids registered by `@easypayment/medusa-payment-paypal`.
- *
- * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,
- * and the server-safe `order` entrypoint all re-export from here so the ids
- * can never drift between entrypoints.
- */
-declare const PAYPAL_WALLET_PROVIDER_ID: "pp_paypal_paypal";
-declare const PAYPAL_CARD_PROVIDER_ID: "pp_paypal_card_paypal_card";
-declare const PAYPAL_PROVIDER_IDS: readonly ["pp_paypal_paypal", "pp_paypal_card_paypal_card"];
-type PayPalProviderId = (typeof PAYPAL_PROVIDER_IDS)[number];
-/** True when the provider id belongs to this PayPal plugin. */
-declare function isPayPalProviderId(providerId?: string | null): providerId is PayPalProviderId;
-
 type PayPalPaymentSectionProps = {
     cartId: string;
     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;
     sessionLoading?: boolean;
-    onSuccess?: (cartId: string) => void;
+    onSuccess?: (cartId: string) => void | Promise<void>;
     onError?: (message: string) => void;
-    onPaid?: (result: unknown) => void;
+    onPaid?: (result: unknown) => void | Promise<void>;
 };
 /**
  * Drop-in PayPal payment section for a Medusa checkout.
@@ -164,12 +234,15 @@ type PayPalPaymentSectionProps = {
  * component pins the default provider ids and adds the `sessionLoading` gate
  * shown while the storefront is still creating the payment session.
  */
-declare function PayPalPaymentSection({ cartId, selectedProviderId, baseUrl, publishableApiKey, sessionLoading, onSuccess, onError, onPaid, }: PayPalPaymentSectionProps): React.JSX.Element | null;
+declare function PayPalPaymentSection({ cartId, selectedProviderId, baseUrl, publishableApiKey, credentials, currencyCode, sessionLoading, onSuccess, onError, onPaid, }: PayPalPaymentSectionProps): React.JSX.Element | null;
 
 type Args = {
     baseUrl: string;
     publishableApiKey?: string;
     cartId?: string;
+    /** See `usePayPalConfig` — include to bust the cache on currency switches. */
+    currencyCode?: string;
+    credentials?: RequestCredentials;
     enabled?: boolean;
 };
 type Result = {
@@ -186,7 +259,7 @@ type Result = {
      */
     error: string | null;
 };
-declare function usePayPalPaymentMethods({ baseUrl, publishableApiKey, cartId, enabled, }: Args): Result;
+declare function usePayPalPaymentMethods({ baseUrl, publishableApiKey, cartId, currencyCode, credentials, enabled, }: Args): Result;
 
 declare function showProcessingOverlay(): void;
 declare function hideProcessingOverlay(): void;
@@ -210,4 +283,4 @@ declare function markCartCaptured(cartId: string): void;
 declare function wasCartCaptured(cartId: string): boolean;
 declare function clearCartCaptured(cartId: string): void;
 
-export { MedusaNextPayPalAdapter, type MedusaNextPayPalAdapterProps, PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, PayPalAdvancedCard, type PayPalConfig, PayPalCurrencyNotice, PayPalPaymentSection, type PayPalPaymentSectionProps, PayPalProvider, type PayPalSettingsResponse, PayPalSmartButtons, clearCartCaptured, createPayPalStoreApi, generateIdempotencyKey, hideProcessingOverlay, isPayPalProviderId, markCartCaptured, markPaymentComplete, showProcessingOverlay, usePayPalConfig, usePayPalPaymentMethods, wasCartCaptured };
+export { HttpError, type HttpOptions, type MarkPaymentCompleteOptions, MedusaNextPayPalAdapter, type MedusaNextPayPalAdapterProps, PAYPAL_CARD_PROVIDER_ID, PAYPAL_PROVIDER_IDS, PAYPAL_WALLET_PROVIDER_ID, PayPalAdvancedCard, type PayPalConfig, PayPalCurrencyNotice, PayPalPaymentSection, type PayPalPaymentSectionProps, PayPalProvider, type PayPalProviderId, type PayPalSettingsResponse, PayPalSmartButtons, type RequestOptions, clearCartCaptured, createHttpClient, createPayPalStoreApi, generateIdempotencyKey, hideProcessingOverlay, invalidatePayPalConfigCache, isPayPalProviderId, markCartCaptured, markPaymentComplete, showProcessingOverlay, usePayPalConfig, usePayPalPaymentMethods, wasCartCaptured };