@asstio-dev/storefront 0.21.0 → 0.24.0

package/README.md

@@ -282,11 +282,16 @@ differ from what the order later freezes. `productFacts()` reads them from any s
 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
+render(facts.primaryCategory?.pathNames.join(" > ")); // the one category to use for analytics, breadcrumbs and feeds
 ```
 
 `brand` is the selected or purchased variant's brand, and `null` can mean the variant deliberately has none — do not
-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.
+fall back to `productBrand`. **`categories` carry no primary meaning**: `categories[0]` may be a gender, a brand or a
+product-type node. `primaryCategory` is the one to use: the storefront picks it under the site's product-taxonomy root, one
+of `categories`, and it is `null` when the site has no root, the product has no category under it, or the line was frozen
+before it existed. Identify a root by `pathIds[0]`, never by its translated name. `pathIds` and `primaryCategory` need
+API v0.24.0 or later; on order lines and checkout lines frozen from a snapshot taken before v0.24.0, `pathIds` is `[]` and
+`primaryCategory` is `null`.
 
 `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
@@ -306,20 +311,28 @@ know nothing about consent or a data layer.
   25 % gives `price: 7.99`, `value: 23.97`). Pass `tax: "include"` to report gross on purpose.
 - For `add_to_cart` and `remove_from_cart`, pass `quantity`: the positive number of units added or removed, never the
   line's new total.
-- `item_category`…`item_category5` come from one category's `pathNames`: by default the longest, or the one your
-  `pickCategory` returns. A `pickCategory` that returns `undefined` means no category fields.
+- `item_category`…`item_category5` come from `primaryCategory`'s `pathNames` (the full path, root included). When
+  `primaryCategory` is `null` the item has **no** category fields: null can mean "this product has no category under the
+  taxonomy root", and a fallback would put a brand or series root into GA4. Since v0.24.0 this is the default; before it
+  was the longest path, which `pickCategory: longestCategory` still gives. A `pickCategory` gets the categories and the
+  line's facts, `(categories, facts) => CategoryRefDto | undefined`; returning `undefined` means no category fields.
+- Identify a root by id (`pathIds[0]`), never by its translated name.
 - No `discount`: `compareAt` is a recommended price, not a discount applied.
 - A source without a price throws `AnalyticsError`, as does a non-product order line; never `price: 0`.
 - For an order, `transaction_id` is `order.id` (stable from completion; `orderNumber` is null until export), `tax` the
   recorded VAT and `shipping` the shipping lines' net.
 
 ```ts
-const byProductType = (cs: readonly CategoryRefDto[]) => cs.find((c) => c.pathNames[0] === "Produkttyp");
-gtag("event", "view_item_list", { items: listing.items.map((card, index) => toGa4Item(card, { index, pickCategory: byProductType })) });
+// The primary category is the default; this drops a top-level taxonomy root from the emitted path.
+const belowRoot = (_: readonly CategoryRefDto[], f: ProductFacts) =>
+  f.primaryCategory ? { ...f.primaryCategory, pathNames: f.primaryCategory.pathNames.slice(1) } : undefined;
+gtag("event", "view_item_list", { items: listing.items.map((card, index) => toGa4Item(card, { index, pickCategory: belowRoot })) });
 gtag("event", "add_to_cart", { currency: cart.currency, items: [toGa4Item(line, { quantity: added })] });
-gtag("event", "purchase", toGa4Ecommerce(order, { pickCategory: byProductType }));
+gtag("event", "purchase", toGa4Ecommerce(order, { pickCategory: belowRoot }));
 ```
 
+`slice(1)` is right only when the site's taxonomy root is a top-level category.
+
 ### Search-as-you-type and search-in-facet
 
 `/v1/search/suggest` answers three short lists for what the shopper has typed so far: up to 5 product cards

package/dist/analytics/facts.js

@@ -8,6 +8,7 @@ export function productFacts(source) {
             throw new AnalyticsError(`an order line of type "${line.type}" has no product facts`);
         return {
             brand: line.variant.brand, productBrand: line.product.brand, categories: line.product.categories,
+            primaryCategory: line.product.primaryCategory ?? null,
             attributes: line.product.attributes, shortDescription: null,
         };
     }
@@ -17,7 +18,7 @@ export function productFacts(source) {
         const { product, variant } = source;
         const short = product.shortDescription;
         return {
-            brand: variant.brand, productBrand: product.brand, categories: product.categories,
+            brand: variant.brand, productBrand: product.brand, categories: product.categories, primaryCategory: product.primaryCategory ?? null,
             attributes: product.attributes, shortDescription: short ?? null,
         };
     }
@@ -25,7 +26,7 @@ export function productFacts(source) {
     if (!Array.isArray(flat.categories) || !Array.isArray(flat.attributes))
         throw new AnalyticsError("not a product facts source");
     return {
-        brand: flat.brand, productBrand: flat.brand, categories: flat.categories, attributes: flat.attributes,
+        brand: flat.brand, productBrand: flat.brand, categories: flat.categories, primaryCategory: flat.primaryCategory ?? null, attributes: flat.attributes,
         shortDescription: flat.shortDescription ?? null,
     };
 }

package/dist/analytics/ga4.d.ts

@@ -1,4 +1,4 @@
-import { type CartDto, type CheckoutCartDto, type Ga4Ecommerce, type Ga4Item, type Ga4ItemOptions, type Ga4ItemSource, type Ga4Purchase, type Ga4SharedOptions, type OrderDto } from "./types.js";
+import { type CartDto, type CategoryRefDto, 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;
@@ -20,3 +20,5 @@ export declare function mapItem(source: Ga4ItemSource, opts?: Ga4ItemOptions): M
 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;
+/** The longest path, the first of equals — the default before `primaryCategory` existed. Never mutates the array. */
+export declare function longestCategory(categories: readonly CategoryRefDto[]): CategoryRefDto | undefined;

package/dist/analytics/ga4.js

@@ -20,7 +20,7 @@ export function mapItem(source, opts = {}) {
     const variant = itemVariant(line.options);
     if (variant !== undefined)
         item.item_variant = variant;
-    const picked = opts.pickCategory ? opts.pickCategory(facts.categories) : longest(facts.categories);
+    const picked = opts.pickCategory ? opts.pickCategory(facts.categories, facts) : facts.primaryCategory ?? undefined;
     if (picked) {
         const keys = ["item_category", "item_category2", "item_category3", "item_category4", "item_category5"];
         picked.pathNames.slice(0, keys.length).forEach((name, i) => { item[keys[i]] = name; });
@@ -106,8 +106,8 @@ function itemVariant(options) {
     const axes = Object.keys(options).sort();
     return axes.length === 0 ? undefined : axes.map(a => `${a}: ${options[a]}`).join(", ");
 }
-/** The default pick: the longest path, the first of equals. Never mutates the array. */
-function longest(categories) {
+/** The longest path, the first of equals — the default before `primaryCategory` existed. Never mutates the array. */
+export function longestCategory(categories) {
     let best;
     for (const c of categories)
         if (!best || c.pathNames.length > best.pathNames.length)

package/dist/analytics/types.d.ts

@@ -26,6 +26,10 @@ export type ProductFacts = {
     productBrand: BrandDto | null;
     /** Classification memberships with no primary meaning; `categories[0]` may be any root. */
     categories: CategoryRefDto[];
+    /** The one category to use for analytics, breadcrumbs and feeds: one of `categories`, chosen by the storefront under the
+     * site's product-taxonomy root. `null` when the site has none, the product has no category under it, or the line was frozen
+     * before it existed. */
+    primaryCategory: CategoryRefDto | null;
     /** As the source carries them: a `ProductDto` may include `html` attributes; cards, cart and order lines do not. */
     attributes: AttributeDto[];
     /** Null on order lines and checkout cart lines. */
@@ -61,9 +65,10 @@ export type Ga4SharedOptions = {
     affiliation?: string;
     itemListId?: string;
     itemListName?: string;
-    /** Which category feeds `item_category`…`item_category5`. Default: the longest path, ties in the order given. Returning
-     * `undefined` means no category fields — never a fallback to the default. Categories carry no primary meaning. */
-    pickCategory?: (categories: readonly CategoryRefDto[]) => CategoryRefDto | undefined;
+    /** Which category feeds `item_category`…`item_category5`. Default: `facts.primaryCategory`, and no category fields when it is
+     * null (never a fallback: null can mean "this product has no category under the taxonomy root"). Pass `longestCategory` for
+     * the longest path. Returning `undefined` means no category fields. The second argument is the line's own facts. */
+    pickCategory?: (categories: readonly CategoryRefDto[], facts: ProductFacts) => CategoryRefDto | undefined;
 };
 /** One item's options: `quantity` overrides the source's (for add/remove events: the positive number of units added or
  * removed), `itemId` its id (e.g. for family-level reporting), `index` its position in a list. */

package/dist/index.d.ts

@@ -57,7 +57,7 @@ export { gtinJsonLd } from "./gtin.js";
 export { productJsonLd } from "./seo/product.js";
 export { jsonLdScript } from "./seo/serialize.js";
 export { productFacts } from "./analytics/facts.js";
-export { toGa4Ecommerce, toGa4Item } from "./analytics/ga4.js";
+export { longestCategory, toGa4Ecommerce, toGa4Item } from "./analytics/ga4.js";
 export { trackSearchEvents, type SearchEvent, type SearchEventsResponse } from "./analytics/events.js";
 export { AnalyticsError, type Ga4Ecommerce, type Ga4Item, type Ga4ItemOptions, type Ga4ItemSource, type Ga4Purchase, type Ga4SharedOptions, type ProductFacts, type SelectedVariant, } from "./analytics/types.js";
 export { SeoError, type BreadcrumbLink, type CollectionHeadOptions, type HeadOptions, type JsonLd, type NextMetadataLike, type ProductJsonLdOptions, type SchemaProperty, type SeoContext, type SeoHead, type SeoMeta, type VariantAvailability, } from "./seo/types.js";

package/dist/index.js

@@ -46,7 +46,7 @@ export { gtinJsonLd } from "./gtin.js";
 export { productJsonLd } from "./seo/product.js";
 export { jsonLdScript } from "./seo/serialize.js";
 export { productFacts } from "./analytics/facts.js";
-export { toGa4Ecommerce, toGa4Item } from "./analytics/ga4.js";
+export { longestCategory, toGa4Ecommerce, toGa4Item } from "./analytics/ga4.js";
 export { trackSearchEvents } from "./analytics/events.js";
 export { AnalyticsError, } from "./analytics/types.js";
 export { SeoError, } from "./seo/types.js";

package/dist/schema.d.ts

@@ -536,6 +536,7 @@ export interface components {
             categories: components["schemas"]["CategoryRefDto"][];
             id: string;
             name: string;
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
             shortDescription: null | string;
             slug: string;
         };
@@ -556,6 +557,7 @@ export interface components {
         CategoryRefDto: {
             id: string;
             name: string;
+            pathIds: string[];
             pathNames: string[];
         };
         CheckoutCartDto: {
@@ -917,6 +919,7 @@ export interface components {
             attributes: components["schemas"]["AttributeDto"][];
             brand: null | components["schemas"]["BrandDto"];
             categories: components["schemas"]["CategoryRefDto"][];
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
         };
         OrderLineVariantDto: {
             brand: null | components["schemas"]["BrandDto"];
@@ -977,6 +980,7 @@ export interface components {
             name: string;
             price: null | components["schemas"]["PriceDto"];
             priceVaries: boolean;
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
             shortDescription: null | string;
             sku: string;
             slug: string;
@@ -1003,6 +1007,7 @@ export interface components {
             matchedVariantId: null | string;
             name: string;
             options: components["schemas"]["OptionDto"][];
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
             redirectTo: null | string;
             related: components["schemas"]["RelatedGroupDto"][];
             responsible: components["schemas"]["ResponsibleDto"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "test": "vitest run",
     "test:browser": "playwright test -c browser/playwright.config.ts",
     "check": "npm run generate && npm run typecheck-examples && npm test && git diff --exit-code -- src/schema.d.ts && test -z \"$(git status --porcelain -- src/schema.d.ts)\"",
-    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\", \\\"formatImage\\\", \\\"styleToCss\\\", \\\"startCheckout\\\", \\\"syncCheckout\\\", \\\"completeCheckout\\\", \\\"getCheckoutStatus\\\", \\\"liveShippingFor\\\", \\\"getOrder\\\", \\\"awaitCompletion\\\", \\\"mountCheckout\\\", \\\"productJsonLd\\\", \\\"gtinJsonLd\\\", \\\"breadcrumbJsonLd\\\", \\\"productHead\\\", \\\"collectionHead\\\", \\\"brandHead\\\", \\\"toNextMetadata\\\", \\\"jsonLdScript\\\", \\\"SeoError\\\", \\\"productFacts\\\", \\\"toGa4Item\\\", \\\"toGa4Ecommerce\\\", \\\"AnalyticsError\\\", \\\"trackSearchEvents\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
+    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\", \\\"formatImage\\\", \\\"styleToCss\\\", \\\"startCheckout\\\", \\\"syncCheckout\\\", \\\"completeCheckout\\\", \\\"getCheckoutStatus\\\", \\\"liveShippingFor\\\", \\\"getOrder\\\", \\\"awaitCompletion\\\", \\\"mountCheckout\\\", \\\"productJsonLd\\\", \\\"gtinJsonLd\\\", \\\"breadcrumbJsonLd\\\", \\\"productHead\\\", \\\"collectionHead\\\", \\\"brandHead\\\", \\\"toNextMetadata\\\", \\\"jsonLdScript\\\", \\\"SeoError\\\", \\\"productFacts\\\", \\\"toGa4Item\\\", \\\"toGa4Ecommerce\\\", \\\"longestCategory\\\", \\\"AnalyticsError\\\", \\\"trackSearchEvents\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
   },
   "dependencies": {
     "openapi-fetch": "0.17.0"

package/src/schema.d.ts

@@ -536,6 +536,7 @@ export interface components {
             categories: components["schemas"]["CategoryRefDto"][];
             id: string;
             name: string;
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
             shortDescription: null | string;
             slug: string;
         };
@@ -556,6 +557,7 @@ export interface components {
         CategoryRefDto: {
             id: string;
             name: string;
+            pathIds: string[];
             pathNames: string[];
         };
         CheckoutCartDto: {
@@ -917,6 +919,7 @@ export interface components {
             attributes: components["schemas"]["AttributeDto"][];
             brand: null | components["schemas"]["BrandDto"];
             categories: components["schemas"]["CategoryRefDto"][];
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
         };
         OrderLineVariantDto: {
             brand: null | components["schemas"]["BrandDto"];
@@ -977,6 +980,7 @@ export interface components {
             name: string;
             price: null | components["schemas"]["PriceDto"];
             priceVaries: boolean;
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
             shortDescription: null | string;
             sku: string;
             slug: string;
@@ -1003,6 +1007,7 @@ export interface components {
             matchedVariantId: null | string;
             name: string;
             options: components["schemas"]["OptionDto"][];
+            primaryCategory: null | components["schemas"]["CategoryRefDto"];
             redirectTo: null | string;
             related: components["schemas"]["RelatedGroupDto"][];
             responsible: components["schemas"]["ResponsibleDto"];