@asstio-dev/storefront 0.17.0 → 0.18.0

package/README.md

@@ -251,10 +251,13 @@ Cards and cart lines carry the product facts the product page has: `brand`, `cat
 shape without `shortDescription` (`productFacts(orderLine).shortDescription` is `null`): its facts are the ones the
 charged checkout snapshot captured, never re-resolved — `url`, `facet` and attribute `facetKey`/`valueKeys` are `null`
 there, the blocks are empty on orders placed before they existed, and `null` on fee, shipping and adjustment lines.
-`productFacts()` reads them from any source:
+A checkout cart line (`checkout.cart.lines[]`) has the order-line shape too, but is resolved **live while the attempt is
+`open`**, like a cart line, with `url`, `facet` and attribute keys filled in. In every other status, and for a line the
+catalogue can no longer describe, it carries the snapshot's frozen facts (links `null`). What it shows may therefore
+differ from what the order later freezes. `productFacts()` reads them from any source:
 
 ```ts
-const facts = productFacts(line);           // card, product, { product, variant }, cart line or product order line
+const facts = productFacts(line);           // card, product, { product, variant }, cart line, checkout cart line or product order line
 render(facts.brand?.label);                 // the item's brand: the variant's own, never a fallback to the family's
 render(facts.productBrand?.label);          // the family brand
 ```
@@ -263,7 +266,8 @@ render(facts.productBrand?.label);          // the family brand
 fall back to `productBrand`. **Categories carry no primary meaning**: `categories[0]` may be a gender, a brand or a
 product-type node. Pick the one you want by its root.
 
-`toGa4Item()` and `toGa4Ecommerce()` map the same sources to GA4 ecommerce data. They are pure: they send nothing and
+`toGa4Item()` and `toGa4Ecommerce()` map the same sources to GA4 ecommerce data; `toGa4Ecommerce(checkout.cart)` is the
+`begin_checkout` payload. They are pure: they send nothing and
 know nothing about consent or a data layer.
 
 | Source | `item_id` | `item_brand` | `price` | `quantity` | `item_variant` |
@@ -271,6 +275,7 @@ know nothing about consent or a data layer.
 | card (impression) | the family `sku` | `brand.label` | from-price | 1 | — |
 | `{ product, variant }` | the variant `sku` | the variant's brand | the variant's price | 1 | selected options |
 | cart line | the line `sku` | the variant's brand | the line's unit price | the line's | selected options |
+| checkout cart line | the line `sku` | the variant's brand | the unit price | the line's | options |
 | order line (product) | the line `sku` | the variant's brand | the unit price | the line's | options |
 
 - A card is a family impression; later events carry the purchased sku. Pass `itemId` to report at family level.

package/dist/analytics/facts.d.ts

@@ -1,6 +1,6 @@
-import { type CartLineDto, type OrderLineDto, type ProductCardDto, type ProductDto, type ProductFacts, type SelectedVariant } from "./types.js";
+import { type CartLineDto, type CheckoutCartLineDto, type OrderLineDto, type ProductCardDto, type ProductDto, type ProductFacts, type SelectedVariant } from "./types.js";
 /**
- * The product facts of a card, a product page (with or without a selected variant), a cart line or an order line, so a
+ * The product facts of a card, a product page (with or without a selected variant), a cart line, a checkout cart line or an order line, so a
  * frontend never needs to know where a surface keeps them. Returns the DTO's own arrays and objects — never copies,
  * filters or mutates them. `brand` is the item's brand: a selected or purchased variant's own, with no fallback to the
  * family brand (null can mean an explicit "none"). An order line that is not a product line throws.
@@ -9,4 +9,5 @@ export declare function productFacts(source: ProductCardDto): ProductFacts;
 export declare function productFacts(source: ProductDto): ProductFacts;
 export declare function productFacts(source: SelectedVariant): ProductFacts;
 export declare function productFacts(source: CartLineDto): ProductFacts;
+export declare function productFacts(source: CheckoutCartLineDto): ProductFacts;
 export declare function productFacts(source: OrderLineDto): ProductFacts;

package/dist/analytics/facts.js

@@ -12,11 +12,13 @@ export function productFacts(source) {
         };
     }
     if (isObject(s.product) && isObject(s.variant)) {
-        // A cart line or a selected-variant wrapper: the same fact paths.
+        // A cart line, a checkout cart line or a selected-variant wrapper: the same fact paths. A checkout line's product has no
+        // `shortDescription` (it is the order-line shape), so it reads null there.
         const { product, variant } = source;
+        const short = product.shortDescription;
         return {
             brand: variant.brand, productBrand: product.brand, categories: product.categories,
-            attributes: product.attributes, shortDescription: product.shortDescription ?? null,
+            attributes: product.attributes, shortDescription: short ?? null,
         };
     }
     const flat = source;

package/dist/analytics/ga4.d.ts

@@ -1,4 +1,4 @@
-import { type CartDto, type Ga4Ecommerce, type Ga4Item, type Ga4ItemOptions, type Ga4ItemSource, type Ga4Purchase, type Ga4SharedOptions, type OrderDto } from "./types.js";
+import { type CartDto, type CheckoutCartDto, type Ga4Ecommerce, type Ga4Item, type Ga4ItemOptions, type Ga4ItemSource, type Ga4Purchase, type Ga4SharedOptions, type OrderDto } from "./types.js";
 /** An item and its unit price in cents, so a payload's `value` sums exact cents rather than re-reading floats. */
 export type MappedItem = {
     item: Ga4Item;
@@ -6,7 +6,7 @@ export type MappedItem = {
 };
 /**
  * One GA4 item from a card (an impression: the family sku and from-price), a product with its selected variant, a cart
- * line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
+ * line, a checkout cart line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
  * A source without a price throws — never `price: 0`.
  */
 export declare function toGa4Item(source: Ga4ItemSource, opts?: Ga4ItemOptions): Ga4Item;
@@ -18,4 +18,5 @@ export declare function mapItem(source: Ga4ItemSource, opts?: Ga4ItemOptions): M
  * recorded VAT and its `shipping` comes from its shipping lines, each netted at its own rate and rounded once.
  */
 export declare function toGa4Ecommerce(source: CartDto, opts?: Ga4SharedOptions): Ga4Ecommerce;
+export declare function toGa4Ecommerce(source: CheckoutCartDto, opts?: Ga4SharedOptions): Ga4Ecommerce;
 export declare function toGa4Ecommerce(source: OrderDto, opts?: Ga4SharedOptions): Ga4Purchase;

package/dist/analytics/ga4.js

@@ -3,7 +3,7 @@ import { productFacts } from "./facts.js";
 import { AnalyticsError, } from "./types.js";
 /**
  * One GA4 item from a card (an impression: the family sku and from-price), a product with its selected variant, a cart
- * line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
+ * line, a checkout cart line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
  * A source without a price throws — never `price: 0`.
  */
 export function toGa4Item(source, opts = {}) {
@@ -65,6 +65,11 @@ function lineOf(source) {
             throw new AnalyticsError(`an order line of type "${l.type}" is not an item`);
         return { id: l.sku, name: l.name, gross: parseDecimal(l.unitPriceInc), vatRate: parseDecimal(l.vatRate), quantity: sourceQuantity(l.quantity), options: l.options };
     }
+    if (typeof s.unitPriceInc === "string" && typeof s.productId === "string" && typeof s.type !== "string") {
+        // A checkout cart line: the snapshot's own amounts (`unitPriceInc`, `vatRate`), not a PriceDto, and the options on the line.
+        const l = source;
+        return { id: l.sku, name: l.name, gross: parseDecimal(l.unitPriceInc), vatRate: parseDecimal(l.vatRate), quantity: sourceQuantity(l.quantity), options: l.options };
+    }
     if (typeof s.variant === "object" && s.variant !== null && "selectedOptions" in s.variant) {
         if ("quantity" in s) {
             const l = source;

package/dist/analytics/types.d.ts

@@ -7,6 +7,8 @@ export type CartDto = Schemas["CartDto"];
 export type CartLineDto = Schemas["CartLineDto"];
 export type OrderDto = Schemas["OrderDto"];
 export type OrderLineDto = Schemas["OrderLineDto"];
+export type CheckoutCartDto = Schemas["CheckoutCartDto"];
+export type CheckoutCartLineDto = Schemas["CheckoutCartLineDto"];
 export type BrandDto = Schemas["BrandDto"];
 export type CategoryRefDto = Schemas["CategoryRefDto"];
 export type AttributeDto = Schemas["AttributeDto"];
@@ -26,7 +28,7 @@ export type ProductFacts = {
     categories: CategoryRefDto[];
     /** As the source carries them: a `ProductDto` may include `html` attributes; cards, cart and order lines do not. */
     attributes: AttributeDto[];
-    /** Null on order lines. */
+    /** Null on order lines and checkout cart lines. */
     shortDescription: string | null;
 };
 /** A source the analytics helpers cannot map: a non-product order line, an unpriced variant, an invalid quantity. */
@@ -70,7 +72,7 @@ export type Ga4ItemOptions = Ga4SharedOptions & {
     itemId?: string;
     index?: number;
 };
-export type Ga4ItemSource = ProductCardDto | SelectedVariant | CartLineDto | OrderLineDto;
+export type Ga4ItemSource = ProductCardDto | SelectedVariant | CartLineDto | CheckoutCartLineDto | OrderLineDto;
 /** `view_cart`, `begin_checkout` and the like. */
 export type Ga4Ecommerce = {
     currency: string;

package/dist/schema.d.ts

@@ -541,11 +541,13 @@ export interface components {
             options: {
                 [key: string]: string;
             };
+            product: components["schemas"]["OrderLineProductDto"];
             productId: string;
             /** Format: int32 */
             quantity: number | string;
             sku: string;
             unitPriceInc: string;
+            variant: components["schemas"]["OrderLineVariantDto"];
             variantId: string;
             vatRate: string;
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",

package/src/schema.d.ts

@@ -541,11 +541,13 @@ export interface components {
             options: {
                 [key: string]: string;
             };
+            product: components["schemas"]["OrderLineProductDto"];
             productId: string;
             /** Format: int32 */
             quantity: number | string;
             sku: string;
             unitPriceInc: string;
+            variant: components["schemas"]["OrderLineVariantDto"];
             variantId: string;
             vatRate: string;
         };