@shipengine/elements 2.18.0 → 2.20.0

package/types/src/types/charset-warning.d.ts

@@ -0,0 +1,5 @@
+export type CharsetWarning = {
+    error: boolean;
+    message: string;
+    title?: string;
+};

package/types/src/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./canada-ddp";
+export * from "./carrier-metadata";
+export * from "./harmonized-tariff-code";
+export * from "./insurance-metadata";
+export * from "./preferred-rates";
+export * from "./ship-from-address";
+export * from "./shipping-preset";
+export * from "./charset-warning";
+export * from "./rates";
+export * from "./pudo";
+export * from "./preferred-rates";

package/types/src/types/pudo.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @internal
+ *
+ * PUDO type
+ */
+export declare enum PudoType {
+    PICKUP = "pick_up",
+    DROPOFF = "drop_off"
+}

package/types/src/types/rates.d.ts

@@ -0,0 +1,21 @@
+import { SE } from "@shipengine/react-api";
+import { PreferredRateAcknowledgementMessage } from "./preferred-rates";
+import { PudoType } from "./pudo";
+/**
+ * @internal
+ *
+ * Rate Option Type
+ */
+export type RateOption = Omit<SE.Rate, "warningMessages"> & {
+    balance?: number;
+    insuranceClaim?: SE.LinkedResource;
+    insuranceProvider?: SE.InsuranceProviderType;
+    insuredValue?: SE.Money;
+    messages: string[];
+    pudoType?: PudoType;
+    rateAcknowledgementMessage?: PreferredRateAcknowledgementMessage;
+    rateDetails?: SE.RateDetail[];
+    requiresAcknowledgement?: boolean;
+    requiresFundedAmount?: boolean;
+    servicePoints?: SE.ServicePoint[];
+};

package/types/src/utilities/checks.d.ts

@@ -0,0 +1,22 @@
+import { ShipFromAddress } from "@types";
+import { Carrier, Warehouse } from "@shipengine/js-api";
+export declare const isOnboarded: (warehouses?: Warehouse[], carriers?: Carrier[]) => boolean;
+export declare const getSellerIdFromToken: (token: string) => string | undefined;
+/**
+ * Validates a ship-from address against the shipFromAddressFormSchema.
+ *
+ * @param shipFromAddress The ship-from address to validate.
+ * @returns An object indicating validation status and any error messages.
+ *
+ * @example
+ * const result = validateShipFromAddress(myAddress);
+ * if (result.isValid) {
+ * console.log("Address is valid.");
+ * } else {
+ * console.error("Address is invalid:", result.errors);
+ * }
+ */
+export declare const validateShipFromAddress: (shipFromAddress: ShipFromAddress) => {
+    errors: unknown;
+    isValid: boolean;
+};

package/types/src/utilities/feature-flags/types.d.ts

@@ -0,0 +1,206 @@
+import { CountryCode } from "../../constants";
+export type EnabledExternalCarriers = ("apc" | "asendia" | "better_trucks" | "canpar" | "chronopost" | "couriers_please" | "courierpost" | "dpd" | "hermes_germany" | "intelliquick_delivery" | "lso" | "ontrac" | "seko" | "ups" | "yodel")[];
+export type EnabledShipEngineCarriers = ("aramex_au_walleted" | "canada_post_walleted" | "canpar_walleted" | "couriersplease_walleted" | "sendle_walleted" | "dhl_express_walleted" | "dhl_express_worldwide" | "dpd_germany_walleted" | "dpdwallet" | "globalpost" | "hermes" | "purolator_walleted" | "stamps_com" | "ups_walleted" | "ups" | "yodel_walleted")[];
+export type RateFormFeatures = {
+    /**
+     * Enables the `funding` section of the rate form.
+     */
+    enableFunding?: boolean;
+    /**
+     * Enables the Pick Up/Drop Off tabs UI in the Rate Form to separate rates with PUDO capability by type.
+     */
+    enablePudoUI?: boolean;
+    /**
+     * Enables the `label layout` section of the Purchase Label element.
+     */
+    labelLayout?: boolean;
+    /**
+     * Enables showing the `carrier nickname` when rates are fetched.
+     */
+    nicknameRate?: boolean;
+    /**
+     * Enables the `DHL terms acknowledgement` when rates are fetched.
+     */
+    requireDhlTermsAcknowledgement?: boolean;
+    /**
+     * Enables the `save rate` button in the rate form. This allows users to save a `rateId` for a shipment to be purchased later.
+     */
+    saveRate?: boolean;
+};
+export type ShipmentFormFeatures = {
+    /**
+     * Enables the `Add-Ons` section of the shipment form. This allows users to add additional services to their shipment such as
+     * delivery confirmation and insurance.
+     */
+    addOns?: boolean;
+    /**
+     * Enables the `browse rates` button in the shipment form. This allows users to browse rates for a shipment with
+     * varying shipment configurations. This is useful for rate shopping.
+     */
+    browseRates?: boolean;
+    /**
+     * Enables the `carrier insurance` feature, allowing users to select carrier insurance when insuring their shipment.
+     */
+    includeCarrierInsurance?: boolean;
+    /**
+     * Enables the `shipsurance insurance` feature, allowing users to select Shipsurance when insuring their shipment.
+     */
+    includeShipsuranceInsurance?: boolean;
+    /**
+     * Enables the `third party insurance` feature, allowing users to opt for third party insurance when insuring their shipment.
+     */
+    includeThirdPartyInsurance?: boolean;
+    /**
+     * Enables the `select service` feature, allowing users to select a service when rate shopping across multiple carrier providers.
+     */
+    selectService?: boolean;
+    /**
+     * Enables the `shipping presets` feature, allowing users to pass in a set of shipping presets they wish to use within the
+     * shipment form of the PurchaseLabel element.
+     */
+    shippingPresets?: boolean;
+    /**
+     * When disabled the Purchase Label element will not use the Seller's saved warehouses during Shipment creation or expose the warehouses in the ship from drop down.
+     */
+    useWarehouses?: boolean;
+};
+export type ShipmentSummaryFeatures = {
+    schedulePickup?: boolean;
+};
+export type PurchaseLabelFeatures = {
+    /**
+     * Feature still in beta. When enabled, the Windsor Framework will display forms, messaging, and error messages if a shipment requires specific Windsor Framework features.
+     */
+    betaEnableWindsorFramework?: boolean;
+    /**
+     * List of all supported `countries` available in ShipEngine Elements.
+     */
+    compatibleCountryCodes?: CountryCode[];
+    /**
+     * Rates for any service codes included here will not be available for purchase.
+     * The property should be of the form { "carrier_code": ["service_code1", "service_code2"] }
+     */
+    disabledShippingServices?: Record<string, string[]>;
+    /**
+     * When enabled will modify the default behavior of creating a new shipment for a salesorder to throwing an error
+     */
+    enableErrorWhenShipmentCancelled?: boolean;
+    /**
+     * @internal
+     *
+     * `partnerMessages` enables the partner consuming elements to specify override messages in specific cases.
+     */
+    partnerMessages?: {
+        incompleteLabelPurchaseRequirements?: string;
+    };
+    /**
+     * All scoped feature flags for the `rate form` section of the PurchaseLabel element.
+     */
+    rateForm?: RateFormFeatures;
+    /**
+     * All scoped feature flags for the `shipment form` section of the PurchaseLabel element.
+     */
+    shipmentForm?: ShipmentFormFeatures;
+};
+export type AccountSettingsFeatures = {
+    /**
+     * Whether or not to display the Add Funds settings within the ShipEngine Carriers section.
+     */
+    enableFunding?: boolean;
+    /**
+     * Whether or not to display the ShipEngine Carriers section on the Account Settings element.
+     */
+    showCarrierServices?: boolean;
+    /**
+     * Whether or not to display the External Carriers section on the Account Settings element.
+     */
+    showExternalCarriers?: boolean;
+    /**
+     * Whether or not to display the Shipping Label Layout section on the Account Settings element.
+     */
+    showLabelLayout?: boolean;
+    /**
+     * Whether or not to display the Ship From Locations section on the Account Settings element.
+     */
+    showManageWarehouses?: boolean;
+    /**
+     * Whether or not to display the Units of Measure section on the Account Settings element.
+     */
+    showUnitSettings?: boolean;
+    /**
+     * Whether or not to display the Taxes section on the Account Settings element.
+     */
+    showVatSettings?: boolean;
+};
+export type LabelColumnName = "shipmentId" | "labelId" | "externalOrderId" | "externalShipmentId" | "packages" | "recipient" | "shippingService" | "createdDate" | "shipDate" | "status" | "trackingStatus";
+export type BaseLabelColumnConfig = {
+    /**
+     * The name identifying the column
+     */
+    name: Exclude<LabelColumnName, "shipmentId" | "labelId">;
+    nickname?: string;
+};
+export type FilterableLabelColumnConfig = {
+    /**
+     * Allow filtering by this column
+     */
+    allowFilter?: boolean;
+    /**
+     * The name identifying the column
+     */
+    name: Extract<LabelColumnName, "shipmentId" | "labelId" | "trackingStatus">;
+    nickname?: string;
+};
+export type LabelColumnConfig = BaseLabelColumnConfig | FilterableLabelColumnConfig;
+export type LabelsGridFeatures = {
+    /**
+     * Configure label grid columns
+     */
+    columns?: LabelColumnConfig[];
+    /**
+     * Configure label grid columns
+     */
+    showActions?: boolean;
+};
+export type GlobalFeatures = {
+    /**
+     * Disable default usage of  Shadow DOM for all elements
+     */
+    disableShadowDOM?: boolean;
+    /**
+     * Availible "Bring your own carrier" carrier codes for carriers that may be added. If this is omitted, new carriers may not be added by this element.
+     */
+    enabledExternalCarriers?: EnabledExternalCarriers;
+    /**
+     * list of all walleted carriers that are enabled for use in Elements.
+     */
+    enabledShipEngineCarriers?: EnabledShipEngineCarriers;
+    /**
+     * Enable parcel guard related features for the different parts of UI
+     */
+    enableParcelGuard?: boolean;
+    /**
+     * Use Elements in Sandbox mode. Requires a sandbox partner.
+     */
+    isSandbox?: boolean;
+    /**
+     * Enables the `Powered by ShipEngine` logo in the footer various elements.
+     */
+    poweredByShipEngine?: boolean;
+    /**
+     * Enable the VAT settings to be shown
+     */
+    showVatSettings?: boolean;
+    /**
+     * The support email that will be referenced in error messages.
+     * Defaults to platform@shipengine.com if not specified.
+     */
+    supportEmailAddress?: string;
+};
+export type ElementsFeatureFlags = {
+    accountSettingsFeatures?: AccountSettingsFeatures;
+    globalFeatures?: GlobalFeatures;
+    labelsGridFeatures?: LabelsGridFeatures;
+    purchaseLabelFeatures?: PurchaseLabelFeatures;
+    shipmentSummaryFeatures?: ShipmentSummaryFeatures;
+};

package/types/src/utilities/index.d.ts

@@ -0,0 +1,3 @@
+export { type ElementsFeatureFlags, getDefaultFeatures } from "./feature-flags";
+export { scopeTheme, createStyles } from "./styles";
+export { isOnboarded, getSellerIdFromToken, validateShipFromAddress } from "./checks";

package/types/src/utilities/shipengine/address.d.ts

@@ -0,0 +1,98 @@
+import { SE } from "@shipengine/react-api";
+import { ShipFromAddress } from "../../types";
+/**
+ * @internal
+ *
+ * # Address Utilities - isDomesticAddress
+ *
+ * @category Utilities
+ */
+export declare const isDomesticAddress: (address: Pick<SE.Address, "countryCode">) => boolean | undefined;
+/**
+ * @internal
+ *
+ * # Address Utilities - isMilitaryAddress
+ *
+ * @category Utilities
+ */
+export declare const isMilitaryAddress: (address: SE.Address) => boolean;
+/**
+ * @internal
+ *
+ * # Address Utilities - isUnitedStatesTerritory
+ *
+ * @category Utilities
+ */
+export declare const isUnitedStatesTerritory: (address: SE.Address) => boolean;
+/**
+ * @internal
+ *
+ * # Address Utilities - isUnsupportedByUps
+ *
+ * @category Utilities
+ */
+export declare const isUnsupportedByUps: (address: SE.Address) => boolean;
+/**
+ * @internal
+ *
+ * # Address Utilities - isPoBox
+ *
+ * @category Utilities
+ */
+export declare const isPoBox: (addressLine: string) => boolean;
+/**
+ * @internal
+ *
+ * # Address Utilities - isPoBoxAddress
+ *
+ * @category Utilities
+ */
+export declare const isPoBoxAddress: (address: SE.Address) => boolean;
+/**
+ * @internal
+ *
+ * # Address Utilities - isEmptyAddress
+ *
+ * @category Utilities
+ */
+export declare const isEmptyAddress: (address?: SE.Address) => boolean;
+/**
+ * @internal
+ *
+ * # Address Utilities - addEmailToValidation
+ *  Even though the documentation says otherwise, the email is dropped from the returned address validation object
+ *
+ * @category Utilities
+ */
+export declare const addEmailToValidation: (addressValidation: SE.AddressValidation, email?: string) => SE.AddressValidation;
+/**
+ * @internal
+ *
+ * # Address Utilities - getDefaultShipFromAddress
+ *  Gets the default ship from address from an array of ship from addresses
+ *
+ * @category Utilities
+ */
+export declare const getDefaultShipFromAddress: (addresses?: ShipFromAddress[]) => ShipFromAddress | undefined;
+/**
+ * @internal
+ *
+ * # Address Utilities - getSavedShipFromAddressId
+ *  Gets the address ID of the Ship From Address on the shipment if it is a saved address and not a warehouse
+ *
+ * @category Utilities
+ */
+export declare const getSavedShipFromAddressId: (shipment?: SE.SalesOrderShipment, shipFromAddresses?: (ShipFromAddress & {
+    addressId: string;
+})[]) => string | undefined;
+/**
+ * @internal
+ *
+ * # Address Utilities - getIsShipmentUsingSavedShipFromAddress
+ *  Returns true if the shipment is using a saved ship from address
+ *
+ * @category Utilities
+ */
+export declare const getIsShipmentUsingSavedShipFromAddress: (shipment?: SE.SalesOrderShipment, shipFromAddresses?: (ShipFromAddress & {
+    addressId: string;
+})[]) => boolean | undefined;

package/types/src/utilities/styles.d.ts

@@ -0,0 +1,47 @@
+import { FunctionInterpolation, Interpolation, Theme } from "@emotion/react";
+import { THEME_ID } from "@shipengine/giger";
+/**
+ * The verbose typing is necessary to get around TypeScript's limitations on contextual inference
+ * with generics. https://stackoverflow.com/questions/75999792/ide-autocompletion-broken-with-typescript-mapped-type-conditionals
+ */
+export type ScopedGigerTheme = Theme | {
+    [THEME_ID]: Theme;
+};
+type GetterKey = `get${Capitalize<string>}`;
+type GetterFunction = (...args: any[]) => FunctionInterpolation<ScopedGigerTheme> | FunctionInterpolation<ScopedGigerTheme>;
+type LowerLetters = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+type Letters = LowerLetters | Uppercase<LowerLetters>;
+type NotG = Exclude<Letters, "g">;
+type NotGE = `g${Exclude<Letters, "e">}`;
+type NotGET = `ge${Exclude<Letters, "t">}`;
+type NotGETUP = `get${Uncapitalize<string>}`;
+type NotGetterKey = NotG | NotGE | NotGET | NotGETUP;
+type StylesConstraint = Record<GetterKey, GetterFunction> & Record<`${NotGetterKey}${string}`, Interpolation<ScopedGigerTheme>>;
+/**
+ * @internal
+ *
+ * Creates a Record of Emotion styles; eliminating the need to explicitly type styles
+ * while remaining fully typesafe w/ autocomplete.
+ *
+ * Keys prefixed with `get` are assumed to be getters and support arbitrary props.
+ *
+ * Values may be any variant of `Interpolation` that the `css` prop can accept:
+ * a `CSSObject`, `SerializedStyles`, a `FunctionInterpolation` with theme, etc.
+ *
+ * @example
+ * ```
+ * const styles = createStyles({
+ *   basicObject: { color: "red" },
+ *   withTheme: (theme) => ({ backgroundColor: theme.palette.primary.main }),
+ *
+ *   getWithArbitraryPropsAndTheme: (disabled?: boolean) => (theme) => ({
+ *     color: theme.palette[disabled ? 'primary' : 'gray'].main,
+ *   }),
+ * });
+ * ```
+ *
+ * @category Utilities
+ */
+export declare const createStyles: <T extends StylesConstraint>(styles: T) => T;
+export declare const scopeTheme: (theme: ScopedGigerTheme) => Theme;
+export {};