@shipengine/elements 2.27.0 → 2.29.0

package/dist/cjs/hooks/financial-services/financial-service.cjs

@@ -0,0 +1,464 @@
+'use strict';
+
+var _tslib = require('../../_virtual/_tslib.cjs');
+var adyenWeb = require('@adyen/adyen-web');
+
+/**
+ * ShipstationFinancialService - This class provides a simple, unified interface for initializing and managing Adyen payment flows,
+ * including credit card payments, bank transfers, and handling 3D Secure redirects.
+ *
+ * @example
+ * ```typescript
+ * // 1. Create service instance with session data callback
+ * const financialService = new ShipstationFinancialService({
+ *   getAdyenSessionData: async () => {
+ *     // Fetch Adyen session data from Auctane Pay
+ *     const response = await fetch('/api/adyen/session', {
+ *       method: 'POST',
+ *       headers: { 'Authorization': `Bearer ${token}` },
+ *       body: JSON.stringify({ amount: 1000, currency: 'USD' })
+ *     });
+ *     return response.json();
+ *   }
+ * });
+ *
+ * // 2. Initialize the service
+ * await financialService.init();
+ *
+ * // 3. Create a credit card checkout component
+ * await financialService.createCheckout('credit_card', {
+ *   locale: 'en-US',
+ *   onPaymentCompleted: (result) => {
+ *     if (result.resultCode === 'Authorised') {
+ *       console.log('Payment successful!');
+ *     }
+ *   },
+ *   onError: (error) => {
+ *     console.error('Payment error:', error);
+ *   },
+ *   creditCardOptions: {
+ *     hasHolderName: true,
+ *     placeholders: {
+ *       cardNumber: '1234 5678 9012 3456',
+ *       expiryDate: 'MM/YY',
+ *       securityCodeThreeDigits: '123'
+ *     }
+ *   }
+ * });
+ *
+ * // 4. Mount the component to a DOM element
+ * financialService.mount('#payment-container');
+ *
+ * // 5. Submit payment when user clicks pay button
+ * document.getElementById('pay-button').addEventListener('click', () => {
+ *   financialService.submit();
+ * });
+ * ```
+ */
+class FinancialService {
+  /**
+   * A flag that indicates whether the current instance of the financial services class has been initialized.
+   *
+   * @example
+   * if (financialService.isReady()) {
+   *  financialService.mount("#service-container");
+   * }
+   */
+  isReady() {
+    return !!this.getCurrentSessionData();
+  }
+  constructor(config) {
+    this.paymentConfig = config;
+  }
+  /**
+   * Initializes the service by fetching Adyen session data.
+   * Must be called before creating any payment components.
+   *
+   * @throws Error If session data cannot be retrieved
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await new ShipstationFinancialService({ getAdyenSessionData }).init()
+   *   console.log('Service initialized successfully');
+   * } catch (error) {
+   *   console.error('Failed to initialize:', error);
+   * }
+   * ```
+   */
+  init() {
+    return _tslib.__awaiter(this, void 0, void 0, function* () {
+      const {
+        getAdyenSessionData
+      } = this.paymentConfig;
+      try {
+        this.adyenCheckoutData = yield getAdyenSessionData();
+        if (!this.adyenCheckoutData) {
+          throw new Error("Failed to retrieve Adyen session data");
+        }
+      } catch (error) {
+        throw new Error(`Failed to initialize: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    });
+  }
+  /**
+   * Creates a payment checkout component for the specified payment method.
+   *
+   * @returns The created Adyen component (Card or PayByBankUS)
+   * @throws {Error} If init() hasn't been called or if payment method is unsupported
+   *
+   * @example Credit card with custom styling
+   * ```typescript
+   * const cardComponent = await financialService.createCheckout('credit_card', {
+   *   locale: 'en-US',
+   *   creditCardOptions: {
+   *     hasHolderName: true,
+   *     holderNameRequired: true,
+   *     showBrandIcon: true,
+   *     placeholders: {
+   *       cardNumber: 'Card number',
+   *       expiryDate: 'MM/YY',
+   *       securityCodeThreeDigits: 'CVV'
+   *     }
+   *   },
+   *   onChange: (state) => {
+   *     // Update UI based on validation state
+   *     submitButton.disabled = !state.isValid;
+   *   }
+   * });
+   * ```
+   */
+  createCheckout(type_1) {
+    return _tslib.__awaiter(this, arguments, void 0, function* (type, options = {}) {
+      if (!this.isReady()) {
+        throw new Error("No session data. Please call init() first.");
+      }
+      const coreConfig = this.getCoreConfig(options);
+      try {
+        this.checkout = yield adyenWeb.AdyenCheckout(coreConfig);
+        // Create the specific component based on payment method type
+        if (type === "credit_card") {
+          this.activeComponent = this.createCreditCardComponent(options.creditCardOptions);
+        } else if (type === "pay_by_bank_us") {
+          this.activeComponent = this.createPayByBankComponent();
+        } else {
+          throw new Error(`Unsupported payment method type: ${type}`);
+        }
+        if (!this.activeComponent) {
+          throw new Error("Failed to create payment component");
+        }
+        return this.activeComponent;
+      } catch (error) {
+        throw new Error(`Failed to create checkout: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    });
+  }
+  /**
+   * Mounts the active payment component to a DOM element.
+   *
+   * @param element - DOM element or CSS selector where the component should be mounted
+   * @throws Error If no active component exists (createCheckout must be called first)
+   *
+   * @example
+   * ```typescript
+   * // Mount to element by ID
+   * financialService.mount('#payment-form');
+   *
+   * // Mount to DOM element
+   * const container = document.getElementById('payment-container');
+   * financialService.mount(container);
+   * ```
+   */
+  mount(element) {
+    if (!this.activeComponent) {
+      throw new Error("No active component. Please call createCheckout() first.");
+    }
+    this.activeComponent.mount(element);
+  }
+  /**
+   * Submits the payment using the active component.
+   * Triggers validation and payment processing.
+   *
+   * @throws Error If no active component exists
+   *
+   * @example
+   * ```typescript
+   * // In a form submit handler
+   * form.addEventListener('submit', (e) => {
+   *   e.preventDefault();
+   *   financialService.submit();
+   * });
+   * ```
+   */
+  submit() {
+    if (!this.activeComponent) {
+      throw new Error("No active component. Please call createCheckout() first.");
+    }
+    this.activeComponent.submit();
+  }
+  /**
+   * Submits the payment and returns a Promise that resolves with the payment result.
+   * This method should be used when you need to wait for payment completion.
+   *
+   * @returns Promise that resolves with PaymentResult
+   * @throws Error If no active component exists
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const result = await financialService.submitPayment();
+   *   if (result.success) {
+   *     console.log('Payment successful!', result.resultCode);
+   *   } else {
+   *     console.error('Payment failed:', result.error);
+   *   }
+   * } catch (error) {
+   *   console.error('Payment error:', error);
+   * }
+   * ```
+   */
+  submitPromise() {
+    return _tslib.__awaiter(this, void 0, void 0, function* () {
+      if (!this.activeComponent) {
+        throw new Error("No active component. Please call createCheckout() first.");
+      }
+      return new Promise((resolve, reject) => {
+        this.paymentPromise = {
+          resolve,
+          reject
+        };
+        this.activeComponent.submit();
+      });
+    });
+  }
+  /**
+   * Unmounts and cleans up the active payment component.
+   * Should be called when the component is no longer needed.
+   *
+   * @example
+   * ```typescript
+   * // Clean up on component unmount (React example)
+   * useEffect(() => {
+   *   return () => {
+   *     financialService.unmount();
+   *   };
+   * }, []);
+   * ```
+   */
+  unmount() {
+    if (this.activeComponent && "unmount" in this.activeComponent) {
+      this.activeComponent.unmount();
+    }
+    this.activeComponent = undefined;
+  }
+  /**
+   * Resets the payment component to ready state, allowing user to edit fields and retry.
+   * This is useful after a failed payment to unlock the form fields.
+   *
+   * @example
+   * ```typescript
+   * // After a failed payment
+   * const result = await financialService.submitPromise();
+   * if (!result.success) {
+   *   // Reset the component to allow retry
+   *   financialService.resetComponent();
+   *   // Show error message to user
+   * }
+   * ```
+   */
+  resetComponent() {
+    if (this.activeComponent && "setStatus" in this.activeComponent) {
+      this.activeComponent.setStatus("ready");
+    }
+  }
+  /**
+   * Returns the current Adyen session data if available.
+   * Useful for accessing session metadata or debugging.
+   *
+   * @returns The current session data or undefined if not initialized
+   *
+   * @example
+   * ```typescript
+   * const sessionData = financialService.getCurrentSessionData();
+   * if (sessionData) {
+   *   console.log('Session ID:', sessionData.metadata.adyenSessionId);
+   *   console.log('Expires:', sessionData.metadata.adyenExpiration);
+   * }
+   * ```
+   */
+  getCurrentSessionData() {
+    return this.adyenCheckoutData;
+  }
+  /**
+   * Handles the return flow from payment redirects (3D Secure, bank authentication, etc.).
+   * Should be called on your return URL page with the redirect parameters.
+   *
+   * @example
+   * ```typescript
+   * // On your return URL page
+   * const urlParams = new URLSearchParams(window.location.search);
+   *
+   * await financialService.handleRedirect({
+   *   sessionId: urlParams.get('sessionId'),
+   *   redirectResult: urlParams.get('redirectResult'),
+   *   onPaymentCompleted: (result) => {
+   *     switch (result.resultCode) {
+   *       case 'Authorised':
+   *         ...
+   *         break;
+   *       case 'Pending':
+   *         ...
+   *         break;
+   *       default:
+   *         ...
+   *     }
+   *   },
+   *   onError: (error) => {
+   *     console.error('Redirect handling failed:', error);
+   *     showErrorMessage('Payment verification failed');
+   *   }
+   * });
+   * ```
+   */
+  handleRedirect(options) {
+    return _tslib.__awaiter(this, void 0, void 0, function* () {
+      const {
+          sessionId,
+          redirectResult,
+          clientKey,
+          locale = "en-US",
+          countryCode = "US"
+        } = options,
+        rest = _tslib.__rest(options, ["sessionId", "redirectResult", "clientKey", "locale", "countryCode"]);
+      if (!sessionId || !redirectResult) {
+        throw new Error("Missing sessionId or redirectResult, unable to complete checkout");
+      }
+      // Determine client key - use provided one or try to get from existing session data
+      let finalClientKey = clientKey;
+      if (!finalClientKey && this.adyenCheckoutData) {
+        finalClientKey = this.adyenCheckoutData.metadata.adyenClientKey;
+      }
+      if (!finalClientKey) {
+        throw new Error("Client key not found, unable to complete checkout");
+      }
+      const environment = this.parseEnvironment(finalClientKey);
+      try {
+        // Create a new checkout instance specifically for handling the redirect
+        const redirectCheckout = yield adyenWeb.AdyenCheckout(Object.assign({
+          environment,
+          clientKey: finalClientKey,
+          session: {
+            id: sessionId
+          },
+          locale,
+          countryCode
+        }, rest));
+        // Submit the redirect details to complete the payment
+        redirectCheckout.submitDetails({
+          details: {
+            redirectResult
+          }
+        });
+      } catch (error) {
+        throw new Error(`Failed to handle redirect: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    });
+  }
+  getCoreConfig(options) {
+    if (!this.adyenCheckoutData) {
+      throw new Error("No session data available");
+    }
+    const {
+      metadata: {
+        adyenClientKey,
+        adyenSessionId,
+        adyenSessionData
+      }
+    } = this.adyenCheckoutData;
+    // Determine environment from client key
+    const environment = options.environment || this.parseEnvironment(adyenClientKey);
+    // Exclude creditCardOptions from the core config as it's component-specific
+    const coreOptions = _tslib.__rest(options, ["creditCardOptions"]);
+    const config = Object.assign(Object.assign({
+      environment,
+      clientKey: adyenClientKey,
+      session: {
+        id: adyenSessionId,
+        sessionData: adyenSessionData
+      },
+      locale: options.locale || "en-US",
+      countryCode: options.countryCode || "US"
+    }, coreOptions), {
+      // Override callbacks to handle Promise resolution while preserving original callbacks
+      onPaymentCompleted: result => {
+        // Call original callback if provided
+        var _a;
+        (_a = options.onPaymentCompleted) === null || _a === void 0 ? void 0 : _a.call(options, result);
+        // Resolve Promise if waiting
+        if (this.paymentPromise) {
+          const paymentResult = {
+            success: result.resultCode === "Authorised" || result.resultCode === "Received",
+            resultCode: result.resultCode,
+            data: result
+          };
+          this.paymentPromise.resolve(paymentResult);
+          this.paymentPromise = undefined;
+        }
+      },
+      onPaymentFailed: result => {
+        // Call original callback if provided
+        var _a;
+        (_a = options.onPaymentFailed) === null || _a === void 0 ? void 0 : _a.call(options, result);
+        // Reset component to unlock form fields for retry
+        this.resetComponent();
+        // Resolve Promise with failure if waiting
+        if (this.paymentPromise) {
+          const paymentResult = {
+            success: false,
+            resultCode: result === null || result === void 0 ? void 0 : result.resultCode,
+            error: (result === null || result === void 0 ? void 0 : result.resultCode) ? `Payment failed: ${result.resultCode}` : "Payment failed",
+            data: result
+          };
+          this.paymentPromise.resolve(paymentResult);
+          this.paymentPromise = undefined;
+        }
+      },
+      onError: error => {
+        // Call original callback if provided
+        var _a;
+        (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error);
+        // Reset component to unlock form fields for retry
+        this.resetComponent();
+        // Reject Promise if waiting
+        if (this.paymentPromise) {
+          this.paymentPromise.reject(new Error(error.message || "Payment processing error"));
+          this.paymentPromise = undefined;
+        }
+      }
+    });
+    if (options.beforeSubmit) {
+      config.beforeSubmit = options.beforeSubmit;
+    }
+    if (options.onChange) {
+      config.onChange = options.onChange;
+    }
+    return config;
+  }
+  createCreditCardComponent(creditCardOptions) {
+    if (!this.checkout) {
+      throw new Error("Checkout not initialized");
+    }
+    return new adyenWeb.Card(this.checkout, creditCardOptions);
+  }
+  createPayByBankComponent() {
+    if (!this.checkout) {
+      throw new Error("Checkout not initialized");
+    }
+    return new adyenWeb.PayByBankUS(this.checkout);
+  }
+  parseEnvironment(clientKey) {
+    return clientKey.startsWith("test_") ? "test" : "live";
+  }
+}
+
+exports.FinancialService = FinancialService;

package/dist/cjs/hooks/financial-services/index.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+var financialService = require('./financial-service.cjs');
+var useFinancialService = require('./use-financial-service.cjs');
+
+
+
+exports.FinancialService = financialService.FinancialService;
+exports.useFinancialService = useFinancialService.useFinancialService;

package/dist/cjs/hooks/financial-services/use-financial-service.cjs

@@ -0,0 +1,188 @@
+'use strict';
+
+var _tslib = require('../../_virtual/_tslib.cjs');
+var React = require('react');
+var financialService = require('./financial-service.cjs');
+var elementsContextProvider = require('../../elements-provider/elements-context-provider.cjs');
+
+/**
+ * React hook for managing Adyen payment components lifecycle
+ *
+ * @example
+ * ```tsx
+ * const { adyenRef, adyenSubmit, isLoading, error } = useFinancialService({
+ *   serviceParams: { getAdyenSessionData: fetchSession },
+ *   paymentMethod: "credit_card",
+ *   options: { locale: 'en-US' }
+ * });
+ *
+ * return (
+ *   <div>
+ *     {isLoading && <Spinner />}
+ *     {error && <ErrorMessage>{error.message}</ErrorMessage>}
+ *     <div ref={adyenRef} />
+ *     <button onClick={adyenSubmit}>Pay</button>
+ *   </div>
+ * );
+ * ```
+ */
+const useFinancialService = ({
+  getAdyenSessionData,
+  paymentMethod,
+  options
+}) => {
+  const {
+    emotionCacheShadowRootContainer
+  } = elementsContextProvider.useElements();
+  const [isLoading, setIsLoading] = React.useState(true);
+  const [error, setError] = React.useState(null);
+  const [isMounted, setIsMounted] = React.useState(false);
+  const adyenRef = React.useRef(null);
+  const currentPaymentMethodRef = React.useRef(null);
+  const service = React.useRef(new financialService.FinancialService({
+    getAdyenSessionData
+  })).current;
+  /**
+   * Indicates if the current page is a redirect return (i.e., Coming back from bank account authorization).
+   */
+  const isRedirectReturn = !!new URLSearchParams(window.location.search).get("redirectResult");
+  const handleRedirect = React.useCallback(options => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    const params = new URLSearchParams(window.location.search);
+    const sessionId = params.get("sessionId");
+    const redirectResult = params.get("redirectResult");
+    if (!redirectResult || !sessionId) {
+      console.error("No redirectResult or sessionId param found in redirect URL");
+      return;
+    }
+    setIsLoading(true);
+    try {
+      yield service.handleRedirect(Object.assign({
+        redirectResult,
+        sessionId
+      }, options));
+    } catch (err) {
+      console.warn("Redirect handling failed:", err);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }), [service]);
+  const submit = React.useCallback(() => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    if (!isMounted) {
+      throw new Error("Adyen component is not mounted. Cannot submit payment.");
+    }
+    return service.submitPromise();
+  }), [isMounted, service]);
+  const createCheckout = React.useCallback(() => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    if (service.isReady()) {
+      yield service.createCheckout(paymentMethod, options);
+    } else {
+      throw new Error("Financial Services is not ready");
+    }
+  }), [options, paymentMethod, service]);
+  const init = React.useCallback(() => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    if (!service.isReady()) {
+      yield service.init();
+    } else {
+      throw new Error("Financial Service already initialized");
+    }
+  }), [service]);
+  const mount = React.useCallback(() => {
+    if (!service.isReady()) {
+      throw new Error("Financial Services is not ready");
+    } else {
+      if (adyenRef.current) {
+        // Mount Adyen styles
+        const adyenStyles = document.createElement("link");
+        adyenStyles.rel = "stylesheet";
+        adyenStyles.href = "https://checkoutshopper-live.adyen.com/checkoutshopper/sdk/6.19.0/adyen.css";
+        adyenStyles.id = "adyen-styles";
+        emotionCacheShadowRootContainer === null || emotionCacheShadowRootContainer === void 0 ? void 0 : emotionCacheShadowRootContainer.appendChild(adyenStyles);
+        // Mount Adyen component
+        service.mount(adyenRef.current);
+        setIsMounted(true);
+      } else {
+        throw new Error("Failed to mount Adyen component");
+      }
+    }
+  }, [service, emotionCacheShadowRootContainer]);
+  React.useEffect(() => {
+    if (service.isReady()) {
+      setIsLoading(false);
+      return;
+    }
+    const initCheckout = () => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+      setIsLoading(true);
+      setError(null);
+      try {
+        yield init();
+        yield createCheckout();
+        mount();
+        // Set the initial payment method
+        currentPaymentMethodRef.current = paymentMethod;
+      } catch (e) {
+        if (e instanceof Error) {
+          console.error("Financial Services Lifecycle Error: failed to initialize.", e);
+          setError(e);
+        }
+      } finally {
+        setIsLoading(false);
+      }
+    });
+    void initCheckout();
+    return () => {
+      var _a;
+      service.unmount();
+      (_a = document.getElementById("adyen-styles")) === null || _a === void 0 ? void 0 : _a.remove();
+    };
+  }, []); // Only run once on mount
+  // Handle payment method changes - recreate component when payment method changes
+  React.useEffect(() => {
+    if (!service.isReady() || currentPaymentMethodRef.current === paymentMethod) {
+      return;
+    }
+    const recreateComponent = () => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+      setIsLoading(true);
+      setError(null);
+      setIsMounted(false);
+      try {
+        // Unmount the existing component
+        service.unmount();
+        if (service.isReady()) {
+          yield service.createCheckout(paymentMethod, options);
+        } else {
+          throw new Error("Financial Services is not ready");
+        }
+        // Mount the new component
+        if (adyenRef.current) {
+          service.mount(adyenRef.current);
+          setIsMounted(true);
+        } else {
+          throw new Error("Failed to mount Adyen component");
+        }
+        // Update the ref to track current payment method
+        currentPaymentMethodRef.current = paymentMethod;
+      } catch (e) {
+        if (e instanceof Error) {
+          console.error("Financial Services Error: failed to recreate component for payment method change.", e);
+          setError(e);
+        }
+      } finally {
+        setIsLoading(false);
+      }
+    });
+    void recreateComponent();
+  }, [paymentMethod, options, service]);
+  return {
+    adyenRef,
+    submit,
+    handleRedirect,
+    isRedirectReturn,
+    isLoading,
+    error,
+    isMounted,
+    getSessionData: () => service.getCurrentSessionData()
+  };
+};
+
+exports.useFinancialService = useFinancialService;

package/dist/cjs/hooks/use-configure-shipment.cjs

@@ -114,6 +114,14 @@ const useConfigureShipment = ({
     isSuccess: salesOrderShipmentCreated
   } = reactApi.useCreateSalesOrderShipment();
   const pendingSalesOrderShipment = shipment.getShipmentByStatus("pending", salesOrderShipments);
+  if (pendingSalesOrderShipment) {
+    // ensure state code is uppercase for form hydration.  SE API may return mixed case state codes.
+    pendingSalesOrderShipment.shipFrom.stateProvince = pendingSalesOrderShipment.shipFrom.stateProvince.toUpperCase();
+    pendingSalesOrderShipment.shipTo.stateProvince = pendingSalesOrderShipment.shipTo.stateProvince.toUpperCase();
+    if (pendingSalesOrderShipment.returnTo) {
+      pendingSalesOrderShipment.returnTo.stateProvince = pendingSalesOrderShipment.returnTo.stateProvince.toUpperCase();
+    }
+  }
   const labelPurchasedSalesOrderShipment = shipment.getShipmentByStatus("label_purchased", salesOrderShipments);
   const cancelledShipment = shipment.getShipmentByStatus("cancelled", salesOrderShipments);
   const defaultWarehouse = warehouses.getDefaultWarehouse(warehouses$1);