@easypayment/medusa-paypal-ui 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -22,6 +22,16 @@ type PayPalConfig = {
     disable_buttons?: string[];
 };
 type PayPalSettingsResponse = {
+    /**
+     * What `GET /store/paypal/settings` actually returns: the configured
+     * payment action and whether advanced card fields are enabled.
+     */
+    paymentAction?: "capture" | "authorize";
+    advancedCardEnabled?: boolean;
+    /**
+     * @deprecated The settings endpoint has never returned a `data` envelope —
+     * kept only so existing (already-null-safe) consumer code keeps compiling.
+     */
     data?: {
         api_details?: {
             currency_code?: string;
@@ -35,8 +45,27 @@ type PayPalSettingsResponse = {
 type HttpOptions = {
     baseUrl: string;
     publishableApiKey?: string;
+    /**
+     * `credentials` mode for every request. Defaults to "include" (the
+     * historical behavior, required when the backend sits behind cookie-based
+     * gateways like Cloudflare Access). Set to "omit" or "same-origin" when the
+     * backend answers with `Access-Control-Allow-Origin: *` — browsers reject
+     * credentialed requests against a wildcard CORS origin outright.
+     */
+    credentials?: RequestCredentials;
 };
 
+/**
+ * Fresh idempotency key per create-order ATTEMPT (i.e. per buyer click).
+ *
+ * The backend derives the PayPal-Request-Id from this header. It must be
+ * unique per attempt: PayPal replays the cached response for a reused request
+ * id, so a key stable across cart changes would hand back the ORIGINAL order —
+ * at the original total — after the buyer edits the cart, charging a stale
+ * amount. Reuse/dedup of an unchanged order is handled server-side by the
+ * 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>>;
 declare function createPayPalStoreApi(opts: HttpOptions): {
     getConfig(cartId?: string, signal?: AbortSignal): Promise<PayPalConfig>;
@@ -103,9 +132,18 @@ type MedusaNextPayPalAdapterProps = {
 };
 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 function isPayPalProviderId(id?: string | null): boolean;
+/** True when the provider id belongs to this PayPal plugin. */
+declare function isPayPalProviderId(providerId?: string | null): boolean;
+
 type PayPalPaymentSectionProps = {
     cartId: string;
     selectedProviderId: string | null | undefined;
@@ -116,6 +154,14 @@ type PayPalPaymentSectionProps = {
     onError?: (message: string) => void;
     onPaid?: (result: unknown) => void;
 };
+/**
+ * Drop-in PayPal payment section for a Medusa checkout.
+ *
+ * A thin wrapper over {@link MedusaNextPayPalAdapter} (they previously carried
+ * two ~90%-identical render paths that had to be edited in lockstep): this
+ * 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;
 
 type Args = {
@@ -130,10 +176,36 @@ type Result = {
     cardEnabled: boolean;
     cardTitle: string;
     loading: boolean;
+    /**
+     * Non-null when the config fetch failed and the returned flags are the
+     * optimistic defaults rather than the merchant's real settings. Storefronts
+     * can use this to hide or annotate the PayPal options instead of advertising
+     * methods that will fail once selected.
+     */
+    error: string | null;
 };
 declare function usePayPalPaymentMethods({ baseUrl, publishableApiKey, cartId, enabled, }: Args): Result;
 
 declare function showProcessingOverlay(): void;
 declare function hideProcessingOverlay(): void;
 
-export { MedusaNextPayPalAdapter, type MedusaNextPayPalAdapterProps, PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, PayPalAdvancedCard, type PayPalConfig, PayPalCurrencyNotice, PayPalPaymentSection, type PayPalPaymentSectionProps, PayPalProvider, type PayPalSettingsResponse, PayPalSmartButtons, createPayPalStoreApi, hideProcessingOverlay, isPayPalProviderId, markPaymentComplete, showProcessingOverlay, usePayPalConfig, usePayPalPaymentMethods };
+/**
+ * Per-cart "money was captured" flag, persisted in sessionStorage.
+ *
+ * The in-memory `capturedRef` protects a buyer within one page lifetime, but a
+ * reload/crash between the capture and the order finalization loses it — the
+ * buyer would then see fresh payment buttons for a cart whose money is already
+ * taken. Persisting the flag lets the components restore the finalize-only
+ * Retry path after a reload instead of offering a second payment.
+ *
+ * sessionStorage is deliberately chosen over localStorage: it is scoped to the
+ * tab/session, so an abandoned flag can't leak into a future visit after the
+ * cart id is reused, and it needs no expiry logic. Every access is guarded —
+ * private browsing modes and storage-blocking settings throw on access, and a
+ * storage failure must never break the payment flow.
+ */
+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 };