@scayle/storefront-core 8.12.3 → 8.14.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @scayle/storefront-core
 
+## 8.14.0
+
+### Minor Changes
+
+- Expose `PackageDeliveryStatus` type. This new type clearly defines the allowed values for a package's delivery status. This improves code clarity and helps prevent typos. It's used to replace the inline string literal types in the `ListOfPackages` type.
+- Refactor the `Order` and `OrderItem` interfaces to be generic, allowing them to accept custom `Product` and `Variant` types. This allows to strongly type the `product` and `variant` data within orders and order items, leading to better type checking and potentially fewer runtime errors. This allows for compile-time checks and autocompletion when working with product and variant properties of `OrderItem` and items property of `Order`.
+
+## 8.13.0
+
+### Minor Changes
+
+- Expose `OrderStatus` and `OrderItem` interfaces from `order` types.
+- Enhance the `OrderSummary` component by integrating the `OrderStatus` type
+  from the order `Order` interface. This update provides a more accurate and
+  detailed representation of the order status for users.
+- Enhance order `detailedStatus` code type for `billing`, `order` and `shipping` properties and
+  expose `OrderStatusCode`, `BillingStatusCode` and `ShippingStatusCode`.
+
+### Patch Changes
+
+- Added `fishery@>=2.2.3` as `peerDependencies`.
+
 ## 8.12.3
 
 ### Patch Changes

package/dist/api/customer.d.ts

@@ -113,7 +113,7 @@ export declare class CustomerAPIClient {
      *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/order/get-order
      */
-    getOrder(shopId: number, orderId: number): Promise<Order>;
+    getOrder(shopId: number, orderId: number): Promise<Order<Record<string, unknown>, Record<string, unknown>>>;
     /**
      * Update contact details of a customer.
      *

package/dist/helpers/orderHelpers.d.ts

@@ -6,71 +6,7 @@ import type { Order } from '../types';
  *
  * @returns An array of unique order items.
  */
-export declare const getUniqueItemsFromOrder: (order: Order) => {
-    id?: string;
-    availableQuantity?: number;
-    currency?: string;
-    customData?: {
-        [k: string]: unknown;
-    };
-    deliveryForecast?: import("../types").DeliveryForecastFromWarehouse;
-    isManuallyReturnedByCci?: boolean;
-    itemGroup?: null | {
-        id: string;
-        isMainItem: boolean;
-        isRequired: boolean;
-    };
-    key: string;
-    lowestPriorPrice?: null | {
-        relativeDifferenceToPrice: number;
-        withTax: import("@scayle/storefront-api/dist/shared/storefront-api.CrBb99Bp").C;
-    };
-    merchant?: {
-        id: number;
-        [k: string]: unknown;
-    };
-    packageId: import("../types").PackageReference;
-    price: {
-        appliedReductions?: {
-            amount: {
-                absoluteWithTax: import("@scayle/storefront-api/dist/shared/storefront-api.CrBb99Bp").C;
-                relative: number;
-            };
-            category: "sale" | "campaign" | "voucher";
-            code?: string;
-            type: "relative" | "absolute";
-        }[];
-        overrideWithoutTax?: number;
-        overrideWithTax?: number;
-        reference?: {
-            size?: string;
-            unit?: string;
-            withTax?: number;
-        };
-        tax: {
-            [k: string]: {
-                amount: number;
-                rate: number;
-            };
-        };
-        undiscountedWithOutTax?: number;
-        undiscountedWithTax?: number;
-        withoutTax: import("@scayle/storefront-api/dist/shared/storefront-api.CrBb99Bp").C;
-        withTax: import("@scayle/storefront-api/dist/shared/storefront-api.CrBb99Bp").C;
-    };
-    product: {
-        [k: string]: unknown;
-    };
-    reservationKey?: string;
-    status: "available" | "cancelled" | "delivered" | "returned" | "unavailable";
-    variant: {
-        [k: string]: unknown;
-    };
-    warehouseId?: null | number;
-    warehousePackageGroupId?: null | number;
-    createdAt: string;
-    updatedAt: string;
-}[] | undefined;
+export declare const getUniqueItemsFromOrder: (order: Order) => import("../types").OrderItem<Record<string, unknown>, Record<string, unknown>>[] | undefined;
 /**
  * Gets the quantity of a specific item in an order based on its variant ID.
  *

package/dist/rpc/methods/cbd.d.ts

@@ -12,4 +12,4 @@ import type { Order, RpcContext } from '../../types';
  */
 export declare const getOrderDataByCbd: ({ cbdToken }: {
     cbdToken: string;
-}, context: RpcContext) => Promise<ErrorResponse | Order>;
+}, context: RpcContext) => Promise<ErrorResponse | Order<Record<string, unknown>, Record<string, unknown>>>;

package/dist/rpc/methods/checkout/checkout.mjs

@@ -36,7 +36,7 @@ export const getCheckoutToken = async function getCheckoutToken2(jwtPayload = {}
     carrier,
     basketId: context.basketKey,
     campaignKey
-  }).setIssuedAt(now).setNotBefore(now).setExpirationTime("1h").setIssuer(`${"@scayle/storefront-core"}@${"8.12.3"}`).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(secret);
+  }).setIssuedAt(now).setNotBefore(now).setExpirationTime("1h").setIssuer(`${"@scayle/storefront-core"}@${"8.14.0"}`).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(secret);
   return {
     accessToken: refreshedAccessToken,
     checkoutJwt

package/dist/rpc/methods/checkout/order.d.ts

@@ -14,4 +14,4 @@ import type { Order } from '../../../types';
  */
 export declare const getOrderById: ({ orderId }: {
     orderId: number;
-}, context: import("../../../types").RpcContext) => Promise<ErrorResponse | Order>;
+}, context: import("../../../types").RpcContext) => Promise<ErrorResponse | Order<Record<string, unknown>, Record<string, unknown>>>;

package/dist/types/sapi/order.d.ts

@@ -1,8 +1,10 @@
+import type { Gender } from '../user';
 import type { CentAmount } from './product';
 /**
  * Items are grouped by package, depending on the item's supplier configuration. The `packageId` references an entry in the packages list with delivery estimates and expected carrier.
  */
 export type PackageReference = number;
+export type PackageDeliveryStatus = 'open' | 'shipment_pending' | 'delegation_pending' | 'shipment_completed' | 'cancellation_completed';
 /**
  * The distribution of items across packages is calculated based on the supplierId. Once shipments are processed, the packages may be updated to reflect the actual shipments.
  */
@@ -19,7 +21,7 @@ export type ListOfPackages = {
         maximum: string;
         minimum: string;
     };
-    deliveryStatus: 'open' | 'shipment_pending' | 'delegation_pending' | 'shipment_completed' | 'cancellation_completed';
+    deliveryStatus: PackageDeliveryStatus;
     returnIdentCode?: null | string;
     shipmentKey?: string;
     tracking?: {
@@ -99,7 +101,124 @@ export interface OrderForwardAddress {
         type?: OrderAddressRecipientType;
     };
 }
-export interface Order {
+export type OrderStatus = 'order_open' | 'payment_pending' | 'payment_reserved' | 'invoice_completed' | 'cancellation_pending' | 'cancellation_completed' | 'invoice_partially_completed';
+export type OrderStatusCode = 'order_created' | 'order_open' | 'order_pended' | 'order_confirmed' | 'order_delegated' | 'order_shipped' | 'order_invoiced' | 'order_aborted' | 'order_cancelled' | 'order_imported' | 'order_invoice_error';
+export type BillingStatusCode = 'billing_open' | 'billing_pending' | 'billing_payment_pending' | 'billing_completed' | 'billing_payment_cancelled' | 'billing_partially_refunded' | 'billing_refunded';
+export type ShippingStatusCode = 'shipping_open' | 'shipping_not_deliveable' | 'shipping_ordered' | 'shipping_delivered' | 'shipping_cancelled' | 'shipping_undeliverable' | 'shipping_returned' | 'shipping_partially_returned' | 'shipping_partially_undeliverable';
+export interface OrderItem<Product = Record<string, unknown>, Variant = Record<string, unknown>> {
+    id?: string;
+    /**
+     * The number of deliverable items available in the warehouse for immediate shipping.
+     */
+    availableQuantity?: number;
+    /**
+     * The three character [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code that identifies the currency. The currency is defined on the configuration of the shop, and can be modified in the cloud panel.
+     */
+    currency?: string;
+    /**
+     * customData allows the tenant to attach data to an item. The data will remain attached to the item from the basket through the process of order creation and delegation and may be displayed to the customer during the order lifecycle.
+     */
+    customData?: Record<string, unknown>;
+    deliveryForecast?: DeliveryForecastFromWarehouse;
+    /**
+     * Whether the return shipment got triggered manually. Is missing in case there is no return shipment.
+     */
+    isManuallyReturnedByCci?: boolean;
+    itemGroup?: null | {
+        /**
+         * Item group ID
+         */
+        id: string;
+        /**
+         * Specifies the main item in the group (true for only one item in a group)
+         */
+        isMainItem: boolean;
+        /**
+         * Specifies if the item is mandatory or optional
+         */
+        isRequired: boolean;
+    };
+    key: string;
+    lowestPriorPrice?: null | {
+        /**
+         * Difference to the current price
+         */
+        relativeDifferenceToPrice: number;
+        /**
+         * Lowest price including taxes
+         */
+        withTax: CentAmount;
+    };
+    /**
+     * the merchant id to which the item belongs.
+     */
+    merchant?: {
+        id: number;
+        [k: string]: unknown;
+    };
+    packageId: PackageReference;
+    /**
+     * The price is provided in a currency's lowest denomination (e.g. cent for EUR). In a multi-supplier environment, the price displayed on an item is dictated by the supplier order of preference, which is configured in the cloud panel.
+     */
+    price: {
+        /**
+         * The discounts detail the reductions included in the final `price.withTax` and `price.withoutTax` calculation.
+         */
+        appliedReductions?: {
+            amount: {
+                absoluteWithTax: CentAmount;
+                /**
+                 * The `rate` is calculated on the basis of the reduction in relation to the `preDiscountPrice` price.
+                 */
+                relative: number;
+            };
+            category: 'sale' | 'campaign' | 'voucher';
+            code?: string;
+            type: 'relative' | 'absolute';
+        }[];
+        overrideWithoutTax?: number;
+        overrideWithTax?: number;
+        reference?: {
+            size?: string;
+            unit?: string;
+            withTax?: number;
+        };
+        /**
+         * List of all taxes applied in calculating the `price.withTax`
+         */
+        tax: {
+            [k: string]: {
+                amount: number;
+                rate: number;
+            };
+        };
+        undiscountedWithOutTax?: number;
+        undiscountedWithTax?: number;
+        /**
+         * This price excludes taxes, but also includes all applicable reductions.
+         */
+        withoutTax: CentAmount;
+        /**
+         * The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request).
+         */
+        withTax: CentAmount;
+    };
+    product: Product;
+    /**
+     * Reference set in the checkout when an item was reserved successfully.
+     */
+    reservationKey?: string;
+    status: 'available' | 'cancelled' | 'delivered' | 'undeliverable' | 'returned' | 'unavailable';
+    variant: Variant;
+    /**
+     * The warehouse id where the item are being picking from.
+     */
+    warehouseId?: null | number;
+    warehousePackageGroupId?: null | number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Order<Product = Record<string, unknown>, Variant = Record<string, unknown>> {
     /**
      * The `id` can be applied as a parameter on the url to retrieve an individual order in the [Fetch Order by ID](#fetch-order-by-id) endpoint.
      */
@@ -194,9 +313,7 @@ export interface Order {
     };
     currencyCode: string;
     customData?: {
-        score?: {
-            [k: string]: unknown;
-        } | string | number | unknown[] | boolean;
+        score?: Record<string, unknown> | string | number | unknown[] | boolean;
         [k: string]: unknown;
     };
     customer?: {
@@ -213,14 +330,12 @@ export interface Order {
          * Additional data attached by the client to enhance the customer
          */
         customData?: {
-            score?: {
-                [k: string]: unknown;
-            } | string | number | unknown[] | boolean;
+            score?: Record<string, unknown> | string | number | unknown[] | boolean;
             [k: string]: unknown;
         };
         email?: string;
         firstName?: string;
-        gender?: 'm' | 'f' | 'd';
+        gender?: Gender;
         groups?: string[];
         ipAddress?: string;
         lastName: string;
@@ -245,143 +360,25 @@ export interface Order {
         updatedAt: string;
     };
     detailedStatus: {
-        billing: {
-            code: string;
+        order: {
+            code: OrderStatusCode;
             name: string;
             [k: string]: unknown;
         };
-        order: {
-            code: string;
+        billing: {
+            code: BillingStatusCode;
             name: string;
             [k: string]: unknown;
         };
         shipping: {
-            code: string;
+            code: ShippingStatusCode;
             name: string;
             [k: string]: unknown;
         };
         [k: string]: unknown;
     };
     invoicedAt?: string;
-    items?: {
-        id?: string;
-        /**
-         * The number of deliverable items available in the warehouse for immediate shipping.
-         */
-        availableQuantity?: number;
-        /**
-         * The three character [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code that identifies the currency. The currency is defined on the configuration of the shop, and can be modified in the cloud panel.
-         */
-        currency?: string;
-        /**
-         * customData allows the tenant to attach data to an item. The data will remain attached to the item from the basket through the process of order creation and delegation and may be displayed to the customer during the order lifecycle.
-         */
-        customData?: {
-            [k: string]: unknown;
-        };
-        deliveryForecast?: DeliveryForecastFromWarehouse;
-        /**
-         * Whether the return shipment got triggered manually. Is missing in case there is no return shipment.
-         */
-        isManuallyReturnedByCci?: boolean;
-        itemGroup?: null | {
-            /**
-             * Item group ID
-             */
-            id: string;
-            /**
-             * Specifies the main item in the group (true for only one item in a group)
-             */
-            isMainItem: boolean;
-            /**
-             * Specifies if the item is mandatory or optional
-             */
-            isRequired: boolean;
-        };
-        key: string;
-        lowestPriorPrice?: null | {
-            /**
-             * Difference to the current price
-             */
-            relativeDifferenceToPrice: number;
-            /**
-             * Lowest price including taxes
-             */
-            withTax: CentAmount;
-        };
-        /**
-         * the merchant id to which the item belongs.
-         */
-        merchant?: {
-            id: number;
-            [k: string]: unknown;
-        };
-        packageId: PackageReference;
-        /**
-         * The price is provided in a currency's lowest denomination (e.g. cent for EUR). In a multi-supplier environment, the price displayed on an item is dictated by the supplier order of preference, which is configured in the cloud panel.
-         */
-        price: {
-            /**
-             * The discounts detail the reductions included in the final `price.withTax` and `price.withoutTax` calculation.
-             */
-            appliedReductions?: {
-                amount: {
-                    absoluteWithTax: CentAmount;
-                    /**
-                     * The `rate` is calculated on the basis of the reduction in relation to the `preDiscountPrice` price.
-                     */
-                    relative: number;
-                };
-                category: 'sale' | 'campaign' | 'voucher';
-                code?: string;
-                type: 'relative' | 'absolute';
-            }[];
-            overrideWithoutTax?: number;
-            overrideWithTax?: number;
-            reference?: {
-                size?: string;
-                unit?: string;
-                withTax?: number;
-            };
-            /**
-             * List of all taxes applied in calculating the `price.withTax`
-             */
-            tax: {
-                [k: string]: {
-                    amount: number;
-                    rate: number;
-                };
-            };
-            undiscountedWithOutTax?: number;
-            undiscountedWithTax?: number;
-            /**
-             * This price excludes taxes, but also includes all applicable reductions.
-             */
-            withoutTax: CentAmount;
-            /**
-             * The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request).
-             */
-            withTax: CentAmount;
-        };
-        product: {
-            [k: string]: unknown;
-        };
-        /**
-         * Reference set in the checkout when an item was reserved successfully.
-         */
-        reservationKey?: string;
-        status: 'available' | 'cancelled' | 'delivered' | 'returned' | 'unavailable';
-        variant: {
-            [k: string]: unknown;
-        };
-        /**
-         * The warehouse id where the item are being picking from.
-         */
-        warehouseId?: null | number;
-        warehousePackageGroupId?: null | number;
-        createdAt: string;
-        updatedAt: string;
-    }[];
+    items?: OrderItem<Product, Variant>[];
     loyaltyCard?: {
         cardNumber?: string;
         points: number;
@@ -393,9 +390,7 @@ export interface Order {
         /**
          * The `data` attribute will contain the data pushed to the Checkout by the Payment Provider in use (or internally generated, should the payment not be provided by an external PSP). This object's structure depends on the PSP itself, however, it will contain the minimum dataset necessary for further processing of the Order.
          */
-        data?: {
-            [k: string]: unknown;
-        };
+        data?: Record<string, unknown>;
         /**
          * Details about installments, included as a listing of the values involved in the Installments transaction.
          */
@@ -436,7 +431,7 @@ export interface Order {
          */
         language: string;
     };
-    status: 'order_open' | 'payment_pending' | 'payment_reserved' | 'invoice_completed' | 'cancellation_pending' | 'cancellation_completed' | 'invoice_partially_completed';
+    status: OrderStatus;
     vouchers?: {
         id: number;
         applicableItems?: {

package/dist/types/user.d.ts

@@ -1,4 +1,5 @@
 import type { UseBasketParams } from './sapi/basket';
+import type { OrderStatus } from './sapi/order';
 import type { UseWishlistParams } from './sapi/wishlist';
 /**
  * Represents the gender of a user.
@@ -64,7 +65,7 @@ export interface OrderSummary {
     /** The ID of the shop associated with the order. */
     shopId: number;
     /** The current status of the order. */
-    status?: string;
+    status?: OrderStatus;
 }
 /**
  * Represents the status of a shop user.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/storefront-core",
-  "version": "8.12.3",
+  "version": "8.14.0",
   "description": "Collection of essential utilities to work with the Storefront API",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -8,6 +8,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "repository": {
+    "url": "git+https://github.com/scayle/storefront-core.git"
+  },
   "website": "https://scayle.dev/en/storefront-guide/developer-guide/getting-started/about-storefront",
   "sideEffects": false,
   "exports": {
@@ -55,6 +58,9 @@
     "test": "vitest --run --passWithNoTests",
     "test:ci": "vitest --run --passWithNoTests --coverage --reporter=default --reporter=junit --outputFile=./coverage/junit.xml"
   },
+  "peerDependencies": {
+    "fishery": "^2.2.3"
+  },
   "dependencies": {
     "@scayle/storefront-api": "18.1.0",
     "@scayle/unstorage-scayle-kv-driver": "0.1.1",
@@ -69,12 +75,13 @@
   "devDependencies": {
     "@scayle/eslint-config-storefront": "4.4.1",
     "@types/crypto-js": "4.2.2",
-    "@types/node": "22.13.9",
+    "@types/node": "22.13.10",
     "@types/webpack-env": "1.18.8",
     "@vitest/coverage-v8": "2.1.9",
     "dprint": "0.49.0",
-    "eslint": "9.21.0",
+    "eslint": "9.22.0",
     "eslint-formatter-gitlab": "5.1.0",
+    "fishery": "2.2.3",
     "publint": "0.2.12",
     "rimraf": "6.0.1",
     "typescript": "5.8.2",