@shipengine/elements 2.18.0 → 2.20.0

package/esm/hooks/use-balance-services.js

@@ -0,0 +1,113 @@
+import { __awaiter } from 'tslib';
+import { getCurrencyFromString } from '../utilities/money.js';
+import { useState, useMemo, useCallback } from 'react';
+import { useFundingSourcesAddFunds, useAddFunds, useListCarriers, useListFundingSources, SE, CodedError } from '@shipengine/react-api';
+
+/**
+ * The `useBalanceServices` hook retrieves and manages balance information for a carrier or funding source. If a funding source cannot be found, the hook will default to using the carrier balance associated with the provided `carrierId` as the primary source of truth.
+ *
+ * @returns `UseBalanceServicesReturnType`
+ */
+const useBalanceServices = () => {
+  const {
+    mutateAsync: addFSFundsMutation,
+    error: addFSFundsErrors,
+    reset: resetFSAddFunds
+  } = useFundingSourcesAddFunds();
+  const {
+    error: addCarrierFundsErrors,
+    mutateAsync: addCarrierFundsMutation,
+    reset: resetCarrierAddfunds
+  } = useAddFunds();
+  const {
+    data: carriersData,
+    error: carriersErrors,
+    isInitialLoading: isInitialLoadingCarriers
+  } = useListCarriers();
+  const {
+    data: fundingSources,
+    error: fundingSourcesErrors,
+    isInitialLoading: isFundingSourceInitialLoading
+  } = useListFundingSources();
+  const [fundingOriginError, setFundingOriginError] = useState(null);
+  const useCarrierBalance = useMemo(() => (fundingSources === null || fundingSources === void 0 ? void 0 : fundingSources.length) === 0, [fundingSources]);
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  //@ts-ignore
+  const fundingOrigin = useMemo(() => {
+    if (useCarrierBalance && (carriersData === null || carriersData === void 0 ? void 0 : carriersData.length)) {
+      // find first availible carrier with a balance.
+      const walletedCarrier = carriersData.find(carrier => carrier.requiresFundedAmount);
+      if (walletedCarrier) {
+        return {
+          balance: walletedCarrier.balance,
+          currency: SE.Currency.USD,
+          id: walletedCarrier.carrierId
+        };
+      }
+    } else if (fundingSources === null || fundingSources === void 0 ? void 0 : fundingSources.length) {
+      const fundingSource = fundingSources[0];
+      if (fundingSource) {
+        return {
+          balance: fundingSource.balance,
+          currency: getCurrencyFromString(fundingSource.currencyCode),
+          id: fundingSource.fundingSourceId
+        };
+      }
+    }
+  }, [carriersData, fundingSources, useCarrierBalance]);
+  const addFundsMutation = useCallback(funds => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+      if (!fundingOrigin) throw new CodedError("No funding origin", {
+        errorCode: "invalid_status",
+        errorSource: "elements",
+        errorType: "business_rules"
+      });
+      if (useCarrierBalance) {
+        yield addCarrierFundsMutation({
+          carrierId: fundingOrigin.id,
+          funds
+        });
+      } else {
+        yield addFSFundsMutation({
+          fundingSourceId: fundingOrigin.id,
+          funds: funds
+        });
+      }
+    } catch (error) {
+      // If the error was already set, we do not want to set it again.
+      if (fundingOriginError === null && error instanceof CodedError) {
+        setFundingOriginError(error);
+      }
+    }
+  }), [addCarrierFundsMutation, addFSFundsMutation, fundingOrigin, fundingOriginError, useCarrierBalance]);
+  const resetAddFundsMutationState = useCallback(() => {
+    resetCarrierAddfunds();
+    resetFSAddFunds();
+    setFundingOriginError(null);
+  }, [resetCarrierAddfunds, resetFSAddFunds]);
+  const isLoadingBalance = useMemo(() => isInitialLoadingCarriers || isFundingSourceInitialLoading, [isInitialLoadingCarriers, isFundingSourceInitialLoading]);
+  const fetchBalanceErrors = useMemo(() => {
+    if (!fundingSourcesErrors && !carriersErrors) {
+      return undefined;
+    }
+    return [...(fundingSourcesErrors !== null && fundingSourcesErrors !== void 0 ? fundingSourcesErrors : []), ...(carriersErrors !== null && carriersErrors !== void 0 ? carriersErrors : [])];
+  }, [carriersErrors, fundingSourcesErrors]);
+  const addFundsErrors = useMemo(() => {
+    if (!addCarrierFundsErrors && !addFSFundsErrors && !fundingOriginError) {
+      return undefined;
+    }
+    return [...(addCarrierFundsErrors !== null && addCarrierFundsErrors !== void 0 ? addCarrierFundsErrors : []), ...(addFSFundsErrors !== null && addFSFundsErrors !== void 0 ? addFSFundsErrors : []), ...(fundingOriginError ? [fundingOriginError] : [])];
+  }, [addCarrierFundsErrors, addFSFundsErrors, fundingOriginError]);
+  return {
+    addFundsMutation,
+    errors: {
+      addFundsErrors,
+      fetchBalanceErrors
+    },
+    fundingOrigin,
+    isLoadingBalance,
+    resetAddFundsMutationState
+  };
+};
+
+export { useBalanceServices };

package/esm/hooks/use-black-box-detection.js

@@ -0,0 +1,65 @@
+import { useEffect } from 'react';
+
+/*
+ * ****** WARNING *******
+ * This hook was designed with the intention of only being used within the onboarding flow during carrier registration and carrier recovery and as such is not intended to be used elsewhere.
+ * There is a chance that more than one script will be mounted if this hook is used elsewhere.
+ */
+/**
+ * @internal
+ *
+ * - Creates an encoded device fingerprint string - aka black box - containing information about the end-user's computing device such as OS, browser, etc.
+ * https://developer.bazaarvoice.com/conversations-api/deprecations/iovation-web#snare_js_only
+ */
+const useBlackboxDetection = ({
+  onSuccess,
+  onError
+}) => {
+  useEffect(() => {
+    // basic configurations must be on page before snare.js is loaded
+    window.io_install_stm = false; // do not install Active X
+    window.io_exclude_stm = 12; // do not run Active X
+    window.io_install_flash = false; // do not install Flash
+    window.io_enable_rip = true; // collect Real IP information
+    const pollBlackBox = () => {
+      try {
+        if (typeof ioGetBlackbox !== "function") {
+          return;
+        }
+        // eslint-disable-next-line
+        const blackboxInfo = ioGetBlackbox();
+        // Each call to ioGetBlackbox() returns a JavaScript object with information about the current state of the black box and eventually the black box string itself
+        if (blackboxInfo.finished) {
+          clearTimeout(intervalId);
+          onSuccess(blackboxInfo.blackbox);
+        }
+      } catch (_e) {
+        onError();
+      }
+    };
+    const intervalId = setInterval(pollBlackBox, 500);
+    // attach script to DOM
+    const script = document.createElement("script");
+    script.type = "text/javascript";
+    script.async = true;
+    script.src = "https://mpsnare.iesnare.com/snare.js";
+    script.addEventListener("error", _e => {
+      if (typeof ioGetBlackbox !== "function") {
+        onError();
+      }
+    });
+    document.head.appendChild(script);
+    return () => {
+      if (intervalId) {
+        clearTimeout(intervalId);
+      }
+      delete window.io_install_stm;
+      delete window.io_exclude_stm;
+      delete window.io_install_flash;
+      delete window.io_enable_rip;
+      document.head.removeChild(script);
+    };
+  }, [onSuccess, onError]);
+};
+
+export { useBlackboxDetection };

package/esm/hooks/use-configure-shipment.js

@@ -0,0 +1,233 @@
+import { __awaiter } from 'tslib';
+import { useQueryClient } from '@tanstack/react-query';
+import { getDefaultShipFromAddress } from '../utilities/shipengine/address.js';
+import { getIsCustomsRequiredForSalesOrder, getCustomsFromSalesOrder } from '../utilities/shipengine/sales-order.js';
+import { getShipmentByStatus, moveCustomsItemsToProducts } from '../utilities/shipengine/shipment.js';
+import { getDefaultWarehouse, getWarehouseById } from '../utilities/shipengine/warehouses.js';
+import { useMemo, useCallback, useEffect } from 'react';
+import { useListCarriers, useListWarehouses, useUpdateSalesOrderShipment, useCreateShipment, useGetShipmentByExternalId, useListSalesOrderShipments, useCreateSalesOrderShipment, CodedError } from '@shipengine/react-api';
+import { useImportSalesOrder } from './use-import-sales-order.js';
+
+const useConfigureShipment = ({
+  onShipmentUpdated,
+  onLoad,
+  errorWhenShipmentCancelled: _errorWhenShipmentCancelled = false,
+  externalOrderId,
+  externalOrderNumber,
+  externalShipmentId,
+  orderSourceCode,
+  salesOrderId,
+  shipFromAddresses,
+  shipmentId,
+  warehouseId,
+  useWarehouses: _useWarehouses = true
+}) => {
+  const queryClient = useQueryClient();
+  // Queue of incomplete requirement keys (i.e., Ship From addresses, Warehouses, Carriers)
+  const incompleteRequirementsKeys = useMemo(() => [], []);
+  const {
+    data: carriers,
+    isInitialLoading: isInitialLoadingCarriers,
+    isFetching: isFetchingCarriers
+  } = useListCarriers();
+  const {
+    data: warehouses,
+    error: listWarehouseErrors,
+    isInitialLoading: isInitialLoadingWarehouses,
+    isFetching: isFetchingWarehouses
+  } = useListWarehouses({
+    enabled: _useWarehouses
+  });
+  const {
+    salesOrder,
+    errors: importSalesOrderErrors,
+    isLoading: isSalesOrderLoading
+  } = useImportSalesOrder({
+    // Dont run Sales Order Import unless the Sales order info is present
+    enabled: !!externalOrderNumber || !!orderSourceCode || !!salesOrderId || !!externalOrderId,
+    externalOrderId,
+    externalOrderNumber,
+    orderSourceCode,
+    salesOrderId
+  });
+  const {
+    error: updateShipmentErrors,
+    mutate: updateShipment
+  } = useUpdateSalesOrderShipment();
+  const {
+    data: newV1Shipment,
+    mutateAsync: createV1Shipment,
+    isLoading: creatingV1Shipment,
+    isSuccess: v1shipmentCreated,
+    error: createV1ShipmentErrors
+  } = useCreateShipment();
+  const {
+    data: externalShipment,
+    error: getExternalShipmentErrors,
+    isInitialLoading: isExternalShipmentInitialLoading,
+    isFetching: isExternalShipmentFetching
+  } = useGetShipmentByExternalId({
+    enabled: !!externalShipmentId && !shipmentId,
+    queryFnParams: {
+      externalId: externalShipmentId !== null && externalShipmentId !== void 0 ? externalShipmentId : ""
+    }
+  });
+  const {
+    data: salesOrderShipments,
+    error: listSalesOrderShipmentsErrors,
+    refetch: refetchSalesOrderShipments,
+    isInitialLoading: listSalesOrderShipmentsInitiallyLoading,
+    isFetching: listSalesOrderShipmentsIsFetching
+  } = useListSalesOrderShipments({
+    externalOrderIds: externalOrderId ? [externalOrderId] : undefined,
+    salesOrderIds: salesOrderId ? [salesOrderId] : salesOrder ? [salesOrder.salesOrderId]
+    // TODO: current workaround - revert to being undefined rather than empty list
+    : [],
+    shipmentIds: shipmentId ? [shipmentId] : externalShipment ? [externalShipment.shipmentId] : newV1Shipment ? [newV1Shipment.shipments[0].shipmentId] : undefined
+  });
+  const {
+    error: createSalesOrderShipmentErrors,
+    mutateAsync: createSalesOrderShipment,
+    isLoading: creatingSalesOrderShipment,
+    isSuccess: salesOrderShipmentCreated
+  } = useCreateSalesOrderShipment();
+  const pendingSalesOrderShipment = getShipmentByStatus("pending", salesOrderShipments);
+  const labelPurchasedSalesOrderShipment = getShipmentByStatus("label_purchased", salesOrderShipments);
+  const cancelledShipment = getShipmentByStatus("cancelled", salesOrderShipments);
+  const defaultWarehouse = getDefaultWarehouse(warehouses);
+  const defaultShipFromAddress = getDefaultShipFromAddress(shipFromAddresses);
+  // Handles the creation of new shipments for the sales order flow and one-off flow
+  const handleShipmentCreation = useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c;
+    if (listSalesOrderShipmentsInitiallyLoading || listSalesOrderShipmentsIsFetching || isExternalShipmentFetching || isExternalShipmentInitialLoading || creatingSalesOrderShipment || salesOrderShipmentCreated || creatingV1Shipment || v1shipmentCreated || isInitialLoadingWarehouses || isFetchingWarehouses || !!pendingSalesOrderShipment || !!labelPurchasedSalesOrderShipment) {
+      return;
+    }
+    const isMissingShipFrom = !(shipFromAddresses === null || shipFromAddresses === void 0 ? void 0 : shipFromAddresses.length);
+    const isMissingWarehouse = !(warehouses === null || warehouses === void 0 ? void 0 : warehouses.length);
+    const isMissingWarehouseId = !warehouseId;
+    // Check if warehouses are disabled and if shipFrom addresses are available to create a shipment.
+    if (!_useWarehouses && isMissingShipFrom) {
+      incompleteRequirementsKeys.push("no_warehouses");
+      return;
+      // If warehouses are enabled then we need to check all of the availible address sources
+    } else if (isMissingShipFrom && isMissingWarehouse && isMissingWarehouseId) {
+      incompleteRequirementsKeys.push("no_warehouses");
+      return;
+    }
+    // Create a shipment using a Sales Order
+    if (salesOrder) {
+      const originAddress = (_c = (_a = defaultShipFromAddress === null || defaultShipFromAddress === void 0 ? void 0 : defaultShipFromAddress.originAddress) !== null && _a !== void 0 ? _a : (_b = getWarehouseById(warehouseId, warehouses)) === null || _b === void 0 ? void 0 : _b.originAddress) !== null && _c !== void 0 ? _c : defaultWarehouse === null || defaultWarehouse === void 0 ? void 0 : defaultWarehouse.originAddress;
+      const isCustomsRequired = getIsCustomsRequiredForSalesOrder(salesOrder, originAddress);
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const customsFromSalesOrder = getCustomsFromSalesOrder(salesOrder, originAddress);
+      const salesOrderShipment = yield createSalesOrderShipment(Object.assign(Object.assign(Object.assign({
+        salesOrderId: salesOrder.salesOrderId
+      }, (defaultShipFromAddress === null || defaultShipFromAddress === void 0 ? void 0 : defaultShipFromAddress.originAddress) ? {
+        shipFrom: defaultShipFromAddress.originAddress
+      } : {
+        warehouseId: warehouseId ? warehouseId : defaultWarehouse === null || defaultWarehouse === void 0 ? void 0 : defaultWarehouse.warehouseId
+      }), isCustomsRequired && {
+        customs: customsFromSalesOrder.customs
+      }), {
+        packages: [Object.assign(Object.assign({
+          packageCode: "package"
+        }, isCustomsRequired && {
+          products: customsFromSalesOrder.products
+        }), {
+          weight: {
+            unit: "pound",
+            value: 0
+          }
+        })]
+      }));
+      if (salesOrderShipment) {
+        yield refetchSalesOrderShipments();
+      }
+    }
+    // Create a Shipment for one-off flow
+    if (!salesOrderId && !externalOrderId && !externalOrderNumber && !orderSourceCode && !shipmentId && !externalShipmentId) {
+      const v1Shipment = yield createV1Shipment(Object.assign({}, (defaultShipFromAddress === null || defaultShipFromAddress === void 0 ? void 0 : defaultShipFromAddress.originAddress) ? {
+        shipFrom: defaultShipFromAddress.originAddress
+      } : {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        warehouseId: warehouseId ? warehouseId : defaultWarehouse.warehouseId
+      }));
+      if (v1Shipment) {
+        yield refetchSalesOrderShipments();
+      }
+    }
+  }), [createSalesOrderShipment, createV1Shipment, creatingSalesOrderShipment, creatingV1Shipment, defaultShipFromAddress, defaultWarehouse, externalOrderId, externalOrderNumber, externalShipmentId, incompleteRequirementsKeys, isExternalShipmentFetching, isExternalShipmentInitialLoading, isFetchingWarehouses, isInitialLoadingWarehouses, labelPurchasedSalesOrderShipment, listSalesOrderShipmentsInitiallyLoading, listSalesOrderShipmentsIsFetching, orderSourceCode, pendingSalesOrderShipment, refetchSalesOrderShipments, salesOrder, salesOrderId, salesOrderShipmentCreated, shipFromAddresses === null || shipFromAddresses === void 0 ? void 0 : shipFromAddresses.length, shipmentId, _useWarehouses, v1shipmentCreated, warehouseId, warehouses]);
+  /**
+   * Update a shipment with deprecated customs items. Move items to the products array on the Shipment's packages array
+   *
+   * Invalidate useGetShipment's cache
+   */
+  const formatCustoms = useCallback(shipment => {
+    const formattedShipment = moveCustomsItemsToProducts(shipment);
+    updateShipment(formattedShipment, {
+      onSuccess(data) {
+        void (onShipmentUpdated === null || onShipmentUpdated === void 0 ? void 0 : onShipmentUpdated(data));
+        void queryClient.invalidateQueries(["useListSalesOrderShipments", {
+          shipmentId: data.shipmentId
+        }], {
+          exact: false
+        } // Invalidate queries with similar keys
+        );
+      }
+    });
+  }, [onShipmentUpdated, queryClient, updateShipment]);
+  const refetchPendingSalesOrderShipments = useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
+    const {
+      data: shipments
+    } = yield refetchSalesOrderShipments();
+    return getShipmentByStatus("pending", shipments);
+  }), [refetchSalesOrderShipments]);
+  // useEffect to handle creating new shipments
+  useEffect(() => {
+    void (() => __awaiter(void 0, void 0, void 0, function* () {
+      yield handleShipmentCreation();
+    }))();
+  }, [shipmentId, externalShipmentId, salesOrderId, salesOrder, warehouses, warehouseId, handleShipmentCreation]);
+  // useEffect to handle formating customs
+  useEffect(() => {
+    var _a, _b;
+    if ((_b = (_a = pendingSalesOrderShipment === null || pendingSalesOrderShipment === void 0 ? void 0 : pendingSalesOrderShipment.customs) === null || _a === void 0 ? void 0 : _a.customsItems) === null || _b === void 0 ? void 0 : _b.length) {
+      formatCustoms(pendingSalesOrderShipment);
+    }
+  }, [formatCustoms, pendingSalesOrderShipment]);
+  // useEffect to check and run the onLoad prop
+  useEffect(() => {
+    if ((salesOrderShipments === null || salesOrderShipments === void 0 ? void 0 : salesOrderShipments.length) && salesOrderShipments.every(s => s.shipmentStatus === "label_purchased")) {
+      void (onLoad === null || onLoad === void 0 ? void 0 : onLoad(salesOrderShipments, salesOrder, pendingSalesOrderShipment));
+    }
+  }, [onLoad, pendingSalesOrderShipment, salesOrder, salesOrderShipments]);
+  // useEffect to validate the Seller has carriers accounts connected.
+  useEffect(() => {
+    if (isInitialLoadingCarriers || isFetchingCarriers) return;
+    if ((carriers === null || carriers === void 0 ? void 0 : carriers.length) === 0) incompleteRequirementsKeys.push("no_carriers");
+  }, [carriers, incompleteRequirementsKeys, isFetchingCarriers, isInitialLoadingCarriers]);
+  const errors = [...(listWarehouseErrors !== null && listWarehouseErrors !== void 0 ? listWarehouseErrors : []), ...(createSalesOrderShipmentErrors !== null && createSalesOrderShipmentErrors !== void 0 ? createSalesOrderShipmentErrors : []), ...(createV1ShipmentErrors !== null && createV1ShipmentErrors !== void 0 ? createV1ShipmentErrors : []), ...(listSalesOrderShipmentsErrors !== null && listSalesOrderShipmentsErrors !== void 0 ? listSalesOrderShipmentsErrors : []), ...(getExternalShipmentErrors !== null && getExternalShipmentErrors !== void 0 ? getExternalShipmentErrors : []), ...(importSalesOrderErrors !== null && importSalesOrderErrors !== void 0 ? importSalesOrderErrors : []), ...(updateShipmentErrors !== null && updateShipmentErrors !== void 0 ? updateShipmentErrors : []), ...(_errorWhenShipmentCancelled && cancelledShipment ? [new CodedError("shipment_cancelled", {
+    errorCode: "invalid_status",
+    errorSource: "elements",
+    errorType: "business_rules"
+  })] : []), ...(labelPurchasedSalesOrderShipment ? [new CodedError("label_purchased", {
+    errorCode: "invalid_status",
+    errorSource: "elements",
+    errorType: "business_rules"
+  })] : []), ...(incompleteRequirementsKeys.length > 0 ? [new CodedError(incompleteRequirementsKeys.length > 1 ? "no_carriers_and_warehouses" : incompleteRequirementsKeys[0], {
+    errorCode: "unknown",
+    errorSource: "elements",
+    errorType: "business_rules"
+  })] : [])];
+  return {
+    carriers,
+    errors: errors.length > 0 ? errors : undefined,
+    isLoading: (isSalesOrderLoading || !(salesOrderShipments === null || salesOrderShipments === void 0 ? void 0 : salesOrderShipments.length) || creatingSalesOrderShipment) && errors.length === 0,
+    refetchPendingSalesOrderShipments,
+    salesOrder,
+    shipment: pendingSalesOrderShipment !== null && pendingSalesOrderShipment !== void 0 ? pendingSalesOrderShipment : labelPurchasedSalesOrderShipment,
+    warehouses
+  };
+};
+
+export { useConfigureShipment };

package/esm/hooks/use-get-funding-source-insurance-provider.js

@@ -0,0 +1,47 @@
+import { useMemo } from 'react';
+import { useGetInsuranceFundingSourceAcceptedTerms } from '@shipengine/react-api';
+import { useElements } from '../elements-provider/elements-context-provider.js';
+
+/**
+ * @internal
+ *
+ * # Get Funding Source Insurance Providers
+ *
+ * - description: This hook is used to get the enabled funding source insurance provider
+ *
+ * @example
+ */
+const useGetFundingSourceInsuranceProvider = () => {
+  const {
+    globalFeatures: {
+      enableParcelGuard
+    }
+  } = useElements();
+  const {
+    data,
+    refetch: refetchInsuranceAcceptedTerms
+  } = useGetInsuranceFundingSourceAcceptedTerms({
+    enabled: enableParcelGuard
+  });
+  const fundingSourceInsuranceProvider = useMemo(() => {
+    var _a;
+    let provider;
+    (_a = data === null || data === void 0 ? void 0 : data.acceptedTerms) === null || _a === void 0 ? void 0 : _a.forEach(term => {
+      if (enableParcelGuard && term.termType === "parcelguard_terms") {
+        provider = "parcelguard";
+      }
+      // TODO: once x_cover is enabled, confirm the term type and uncomment
+      // if (term.termType === "x_cover_terms") {
+      //   provider = "x_cover";
+      // }
+    });
+
+    return provider;
+  }, [data, enableParcelGuard]);
+  return {
+    fundingSourceInsuranceProvider,
+    refetchInsuranceAcceptedTerms
+  };
+};
+
+export { useGetFundingSourceInsuranceProvider };

package/esm/hooks/use-get-service-name.js

@@ -0,0 +1,20 @@
+import { useCallback } from 'react';
+import { useListCarriers } from '@shipengine/react-api';
+
+const useGetServiceName = () => {
+  const {
+    data: carrierList,
+    isLoading,
+    isError
+  } = useListCarriers();
+  const getServiceName = useCallback(itemSelected => {
+    const selectedCarrier = carrierList && carrierList.find(option => option.carrierId === itemSelected.carrierId);
+    const selectedService = selectedCarrier === null || selectedCarrier === void 0 ? void 0 : selectedCarrier.services.find(service => service.serviceCode === itemSelected.serviceCode);
+    return isLoading || isError ? itemSelected.serviceCode : selectedService === null || selectedService === void 0 ? void 0 : selectedService.name;
+  }, [carrierList, isLoading, isError]);
+  return {
+    getServiceName
+  };
+};
+
+export { useGetServiceName };

package/esm/hooks/use-helpers.js

@@ -0,0 +1,22 @@
+import { isOnboarded, validateShipFromAddress } from '../utilities/checks.js';
+import { useListCarriers, useListWarehouses } from '@shipengine/react-api';
+
+const useHelpers = () => {
+  const {
+    data: carriers,
+    isLoading: carriersLoading
+  } = useListCarriers();
+  const {
+    data: warehouses,
+    isLoading: warehousesLoading
+  } = useListWarehouses();
+  const helpersReady = !carriersLoading && !warehousesLoading;
+  const sellerOnboarded = isOnboarded(warehouses, carriers);
+  return {
+    helpersReady,
+    sellerOnboarded,
+    validateShipFromAddress
+  };
+};
+
+export { useHelpers };

package/esm/hooks/use-helpers.stories.js

@@ -0,0 +1,75 @@
+import { jsxs, jsx } from '@emotion/react/jsx-runtime';
+import { Tag, TagColor, Spinner, SpinnerSize } from '@shipengine/giger';
+import { useHelpers } from './use-helpers.js';
+
+var useHelpers_stories = {
+  parameters: {
+    controls: {
+      expanded: false
+    },
+    previewTabs: {
+      "storybook/docs/panel": {
+        hidden: true
+      }
+    },
+    viewMode: "story"
+  },
+  title: "Hooks/Helpers"
+};
+const DisplayBoolean = ({
+  loading,
+  name,
+  value
+}) => jsxs("div", Object.assign({
+  style: {
+    alignItems: "center",
+    display: "flex",
+    flexDirection: "row",
+    gap: "5px"
+  }
+}, {
+  children: [jsx("div", Object.assign({
+    style: {
+      width: "130px"
+    }
+  }, {
+    children: jsxs("b", {
+      children: [name, ":"]
+    })
+  })), jsx("div", {
+    children: value ? jsx(Tag, Object.assign({
+      color: TagColor.PRIMARY
+    }, {
+      children: "true"
+    })) : jsx(Tag, Object.assign({
+      color: TagColor.ERROR
+    }, {
+      children: "false"
+    }))
+  }), loading && jsx(Spinner, {
+    size: SpinnerSize.SIZE_SMALL
+  })]
+}));
+const Template = () => {
+  const {
+    helpersReady,
+    sellerOnboarded
+  } = useHelpers();
+  return jsxs("ul", {
+    children: [jsx("li", {
+      children: jsx(DisplayBoolean, {
+        loading: !helpersReady,
+        name: "helpersReady",
+        value: helpersReady
+      })
+    }), jsx("li", {
+      children: jsx(DisplayBoolean, {
+        name: "sellerOnboarded",
+        value: sellerOnboarded
+      })
+    })]
+  });
+};
+const Default = Template.bind({});
+
+export { Default, useHelpers_stories as default };

package/esm/hooks/use-import-sales-order.js

@@ -0,0 +1,69 @@
+import { __awaiter } from 'tslib';
+import { useQueryClient } from '@tanstack/react-query';
+import { useState, useMemo, useEffect } from 'react';
+import { useGetSalesOrderByExternalOrderId, useGetSalesOrder, useListOrderSources, useRefreshOrderSource } from '@shipengine/react-api';
+
+const useImportSalesOrder = ({
+  enabled,
+  externalOrderId,
+  orderSourceCode,
+  salesOrderId
+}) => {
+  var _a, _b, _c;
+  const queryClient = useQueryClient();
+  const [refreshAttempted, setRefreshAttempted] = useState(false);
+  // attempt to get sales order through external id means
+  const orderByExternalIdQuery = useGetSalesOrderByExternalOrderId(externalOrderId, {
+    enabled: enabled && !!externalOrderId && !salesOrderId
+  });
+  // if an order was found through external search disable this query
+  const orderByIdQuery = useGetSalesOrder(salesOrderId, {
+    enabled: enabled && !!salesOrderId
+  });
+  const salesOrder = useMemo(() => salesOrderId ? orderByIdQuery.data : orderByExternalIdQuery.data, [salesOrderId, orderByIdQuery.data, orderByExternalIdQuery.data]);
+  // Determine if the initial fetch attempts (if applicable) have settled without finding data
+  const initialFetchSettled = (salesOrderId ? !orderByIdQuery.isInitialLoading && !orderByIdQuery.isFetching : true) && (externalOrderId && !salesOrderId ? !orderByExternalIdQuery.isLoading && !orderByExternalIdQuery.isFetching : true);
+  const shouldAttemptRefresh = enabled && initialFetchSettled && !salesOrder && !refreshAttempted;
+  const listOrderSourcesQuery = useListOrderSources({
+    enabled: shouldAttemptRefresh
+  });
+  const {
+    error: refreshOrderSourceErrors,
+    isLoading: isRefreshingOrderSource,
+    mutateAsync: refreshOrderSource
+  } = useRefreshOrderSource();
+  useEffect(() => {
+    if (listOrderSourcesQuery.isSuccess && listOrderSourcesQuery.data && shouldAttemptRefresh && !isRefreshingOrderSource) {
+      const orderSourcesToRefresh = orderSourceCode ? listOrderSourcesQuery.data.filter(o => o.orderSourceCode.includes(orderSourceCode) && o.active) : listOrderSourcesQuery.data.filter(o => o.active);
+      if (orderSourcesToRefresh && orderSourcesToRefresh.length > 0) {
+        setRefreshAttempted(true);
+        void (() => __awaiter(void 0, void 0, void 0, function* () {
+          yield Promise.all(orderSourcesToRefresh.map(o => refreshOrderSource(o.orderSourceId, {
+            // Invalidate relevant queries on successful refresh
+            onSuccess: () => {
+              if (salesOrderId) {
+                void queryClient.invalidateQueries({
+                  queryKey: ["useGetSalesOrder", salesOrderId]
+                });
+              }
+              if (externalOrderId && !salesOrderId) {
+                void queryClient.invalidateQueries({
+                  queryKey: ["useGetSalesOrderByExternalOrderId", externalOrderId]
+                });
+              }
+            }
+          })));
+        }))();
+      }
+    }
+  }, [externalOrderId, isRefreshingOrderSource, listOrderSourcesQuery.data, listOrderSourcesQuery.isSuccess, orderSourceCode, queryClient, refreshOrderSource, salesOrderId, shouldAttemptRefresh]);
+  const isLoading = orderByIdQuery.isInitialLoading || orderByExternalIdQuery.isInitialLoading || listOrderSourcesQuery.isInitialLoading || isRefreshingOrderSource;
+  const errors = [...((_a = orderByIdQuery.error) !== null && _a !== void 0 ? _a : []), ...((_b = orderByExternalIdQuery.error) !== null && _b !== void 0 ? _b : []), ...((_c = listOrderSourcesQuery.error) !== null && _c !== void 0 ? _c : []), ...(refreshOrderSourceErrors !== null && refreshOrderSourceErrors !== void 0 ? refreshOrderSourceErrors : [])];
+  return {
+    errors: errors.length > 0 ? errors : undefined,
+    isLoading,
+    salesOrder
+  };
+};
+
+export { useImportSalesOrder };