@reactionary/core 0.0.59 → 0.0.60

package/initialization.js

@@ -7,7 +7,7 @@ function createInitialRequestContext() {
         cache: { hit: false, key: "" },
         placeholder: false
       },
-      id: { userId: "anonymous" },
+      id: { userId: "anonymous-" + crypto.randomUUID().toString() },
       token: void 0,
       issued: /* @__PURE__ */ new Date(),
       expiry: new Date((/* @__PURE__ */ new Date()).getTime() + 3600 * 1e3),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/core",
-  "version": "0.0.59",
+  "version": "0.0.60",
   "main": "index.js",
   "types": "src/index.d.ts",
   "dependencies": {

package/providers/index.js

@@ -8,6 +8,6 @@ export * from "./inventory.provider.js";
 export * from "./price.provider.js";
 export * from "./product.provider.js";
 export * from "./profile.provider.js";
-export * from "./search.provider.js";
+export * from "./product-search.provider.js";
 export * from "./store.provider.js";
 export * from "./order.provider.js";

package/providers/price.provider.js

@@ -11,7 +11,7 @@ class PriceProvider extends BaseProvider {
   createEmptyPriceResult(sku, currency) {
     const base = this.newModel();
     base.identifier = {
-      sku: { key: sku }
+      variant: { sku }
     };
     base.unitPrice = {
       value: -1,

package/providers/{search.provider.js → product-search.provider.js}

@@ -1,9 +1,9 @@
 import { BaseProvider } from "./base.provider.js";
-class SearchProvider extends BaseProvider {
+class ProductSearchProvider extends BaseProvider {
   getResourceName() {
     return "product-search";
   }
 }
 export {
-  SearchProvider
+  ProductSearchProvider
 };

package/providers/product.provider.js

@@ -1,5 +1,13 @@
 import { BaseProvider } from "./base.provider.js";
 class ProductProvider extends BaseProvider {
+  /**
+   * Returns a set of Products for each variant. Is a paged response, to ensure we do not build in overfetching from the start.
+   *
+   * Usecase: You are rendering a variant-list on a b2b PDP page maybe, and it contains 500 variants. You do not want to fetch all 500 variants in one go.
+   * @param payload
+   * @param reqCtx
+   */
+  //  public abstract getVariantList(payload: ProductQueryVariants, reqCtx: RequestContext): Promise<typeof this.parsePaginatedResult>;
   createEmptyProduct(id) {
     const product = this.newModel();
     product.identifier = { key: id };

package/schemas/capabilities.schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 const CapabilitiesSchema = z.looseObject({
   product: z.boolean(),
-  search: z.boolean(),
+  productSearch: z.boolean(),
   analytics: z.boolean(),
   identity: z.boolean(),
   cart: z.boolean(),

package/schemas/models/base.model.js

@@ -12,13 +12,13 @@ const BaseModelSchema = z.looseObject({
 });
 const PaginationOptionsSchema = z.looseObject({
   pageNumber: z.number().default(1).describe("Current page number, starting from 1"),
-  pageSize: z.number().default(20).describe("Number of items per page")
+  pageSize: z.number().min(1).max(50).default(20).describe("Number of items per page")
 });
 function createPaginatedResponseSchema(itemSchema) {
   return z.object({
     meta: MetaSchema.default(() => MetaSchema.parse({})),
     pageNumber: z.number().min(1).describe("Current page number, starting from 1"),
-    pageSize: z.number().min(1).max(50).describe("Number of items per page"),
+    pageSize: z.number().min(1).describe("Number of items per page"),
     totalCount: z.number().min(0).describe("Total number of items available"),
     totalPages: z.number().min(0).describe("Total number of pages available"),
     items: z.array(itemSchema)

package/schemas/models/cart.model.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
-import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, ProductIdentifierSchema, SKUIdentifierSchema } from "../models/identifiers.model.js";
+import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, ProductIdentifierSchema, ProductVariantIdentifierSchema } from "../models/identifiers.model.js";
 import { CostBreakDownSchema, ItemCostBreakdownSchema } from "./cost.model.js";
 import { BaseModelSchema } from "./base.model.js";
 const CartItemSchema = z.looseObject({
   identifier: CartItemIdentifierSchema.default(() => CartItemIdentifierSchema.parse({})),
   product: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})),
-  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})),
   quantity: z.number().default(0),
   price: ItemCostBreakdownSchema.default(() => ItemCostBreakdownSchema.parse({}))
 });

package/schemas/models/checkout.model.js

@@ -1,13 +1,13 @@
 import { z } from "zod";
 import { BaseModelSchema } from "./base.model.js";
-import { CartIdentifierSchema, CheckoutIdentifierSchema, CheckoutItemIdentifierSchema, OrderIdentifierSchema, SKUIdentifierSchema } from "./identifiers.model.js";
+import { CartIdentifierSchema, CheckoutIdentifierSchema, CheckoutItemIdentifierSchema, OrderIdentifierSchema, ProductVariantIdentifierSchema } from "./identifiers.model.js";
 import { CostBreakDownSchema, ItemCostBreakdownSchema } from "./cost.model.js";
 import { AddressSchema } from "./profile.model.js";
 import { ShippingInstructionSchema } from "./shipping-method.model.js";
 import { PaymentInstructionSchema } from "./payment.model.js";
 const CheckoutItemSchema = z.looseObject({
   identifier: CheckoutItemIdentifierSchema.default(() => CheckoutItemIdentifierSchema.parse({})),
-  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})),
   quantity: z.number().default(0),
   price: ItemCostBreakdownSchema.default(() => ItemCostBreakdownSchema.parse({}))
 });

package/schemas/models/identifiers.model.js

@@ -1,22 +1,36 @@
 import { z } from "zod";
+import { PaginationOptionsSchema } from "./base.model.js";
 const FacetIdentifierSchema = z.looseObject({
   key: z.string().default("").nonoptional()
 });
-const FacetValueIdentifierSchema = z.looseObject({
+const FacetValueIdentifierSchema = z.object({
   facet: FacetIdentifierSchema.default(() => FacetIdentifierSchema.parse({})),
   key: z.string().default("")
 });
-const SKUIdentifierSchema = z.looseObject({
-  key: z.string().default("").nonoptional()
+const ProductVariantIdentifierSchema = z.looseObject({
+  sku: z.string().default("").nonoptional()
+});
+const ProductAttributeIdentifierSchema = z.looseObject({
+  key: z.string().default("").describe("The unique identifier for the product attribute.")
+});
+const ProductAttributeValueIdentifierSchema = z.looseObject({
+  key: z.string().default("").describe("The unique identifier for the product attribute value.")
+});
+const ProductOptionIdentifierSchema = z.looseObject({
+  key: z.string().default("").describe("The unique identifier for the product option.")
+});
+const ProductOptionValueIdentifierSchema = z.looseObject({
+  option: ProductOptionIdentifierSchema.default(() => ProductOptionIdentifierSchema.parse({})),
+  key: z.string().default("").describe('The value of the product option, e.g., "Red" or "Large".')
 });
 const ProductIdentifierSchema = z.looseObject({
   key: z.string().default("")
 });
-const SearchIdentifierSchema = z.looseObject({
+const ProductSearchIdentifierSchema = z.looseObject({
   term: z.string().default(""),
-  page: z.number().default(0),
-  pageSize: z.number().default(20),
-  facets: z.array(FacetValueIdentifierSchema.required()).default(() => [])
+  facets: z.array(FacetValueIdentifierSchema.required()).default(() => []),
+  filters: z.array(z.string()).default(() => []),
+  paginationOptions: PaginationOptionsSchema.default(() => PaginationOptionsSchema.parse({}))
 });
 const CartIdentifierSchema = z.looseObject({
   key: z.string().default("")
@@ -25,7 +39,7 @@ const CartItemIdentifierSchema = z.looseObject({
   key: z.string().default("")
 });
 const PriceIdentifierSchema = z.looseObject({
-  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({}))
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({}))
 });
 const CategoryIdentifierSchema = z.looseObject({
   key: z.string().default("").nonoptional()
@@ -52,7 +66,7 @@ const FulfillmentCenterIdentifierSchema = z.looseObject({
   key: z.string().default("").nonoptional()
 });
 const InventoryIdentifierSchema = z.looseObject({
-  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})),
   fulfillmentCenter: FulfillmentCenterIdentifierSchema.default(
     () => FulfillmentCenterIdentifierSchema.parse({})
   )
@@ -95,9 +109,13 @@ export {
   PaymentMethodIdentifierSchema,
   PickupPointIdentifierSchema,
   PriceIdentifierSchema,
+  ProductAttributeIdentifierSchema,
+  ProductAttributeValueIdentifierSchema,
   ProductIdentifierSchema,
-  SKUIdentifierSchema,
-  SearchIdentifierSchema,
+  ProductOptionIdentifierSchema,
+  ProductOptionValueIdentifierSchema,
+  ProductSearchIdentifierSchema,
+  ProductVariantIdentifierSchema,
   ShippingMethodIdentifierSchema,
   StoreIdentifierSchema,
   WebStoreIdentifierSchema

package/schemas/models/index.js

@@ -9,8 +9,8 @@ export * from "./inventory.model.js";
 export * from "./payment.model.js";
 export * from "./price.model.js";
 export * from "./product.model.js";
+export * from "./product-search.model.js";
 export * from "./profile.model.js";
-export * from "./search.model.js";
 export * from "./shipping-method.model.js";
 export * from "./store.model.js";
 export * from "./order.model.js";

package/schemas/models/order.model.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, SKUIdentifierSchema } from "../models/identifiers.model.js";
+import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, ProductVariantIdentifierSchema } from "../models/identifiers.model.js";
 import { BaseModelSchema } from "./base.model.js";
 import { AddressSchema } from "./profile.model.js";
 import { ShippingMethodSchema } from "./shipping-method.model.js";
@@ -9,7 +9,7 @@ const OrderStatusSchema = z.enum(["AwaitingPayment", "ReleasedToFulfillment", "S
 const OrderInventoryStatusSchema = z.enum(["NotAllocated", "Allocated", "Backordered", "Preordered"]).default("Allocated").describe("The inventory release status of the order.");
 const OrderItemSchema = z.looseObject({
   identifier: CartItemIdentifierSchema.default(() => CartItemIdentifierSchema.parse({})),
-  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})),
   quantity: z.number().default(0),
   price: ItemCostBreakdownSchema.default(() => ItemCostBreakdownSchema.parse({})),
   inventoryStatus: OrderInventoryStatusSchema.default("Allocated").describe("The inventory release status of the order item.")

package/schemas/models/product-search.model.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { ProductIdentifierSchema, FacetValueIdentifierSchema, FacetIdentifierSchema, ProductSearchIdentifierSchema, ProductVariantIdentifierSchema } from "./identifiers.model.js";
+import { BaseModelSchema, createPaginatedResponseSchema, ImageSchema } from "./base.model.js";
+import { ProductVariantOptionSchema } from "./product.model.js";
+const ProductSearchResultItemVariantSchema = z.looseObject({
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})).describe("The specific variant of the product"),
+  image: ImageSchema.default(() => ImageSchema.parse({})).describe("The image representing this variant in the search results"),
+  options: ProductVariantOptionSchema.optional().describe("The subset of options that can reasonably be applied on a PLP")
+});
+const ProductSearchResultItemSchema = BaseModelSchema.extend({
+  identifier: ProductIdentifierSchema.default(ProductIdentifierSchema.parse({})),
+  name: z.string().default(""),
+  slug: z.string().default(""),
+  variants: z.array(ProductSearchResultItemVariantSchema).default(() => []).describe("A list of variants associated with the product in the search results. If exactly one is present, you can use add-to-cart directly from PLP. If none are present, you must direct to PDP. If mulitple are present, and no options are set, you must direct to PDP. If multiple are present, and they have options, you can render swatches on PLP and allow customer to flip between variants.")
+});
+const ProductSearchResultFacetValueSchema = z.looseObject({
+  identifier: FacetValueIdentifierSchema.default(() => FacetValueIdentifierSchema.parse({})),
+  name: z.string().default(""),
+  count: z.number().default(0),
+  active: z.boolean().default(false)
+});
+const ProductSearchResultFacetSchema = z.looseObject({
+  identifier: FacetIdentifierSchema.default(() => FacetIdentifierSchema.parse({})),
+  name: z.string().default(""),
+  values: z.array(ProductSearchResultFacetValueSchema).default(() => [])
+});
+const ProductSearchResultSchema = createPaginatedResponseSchema(ProductSearchResultItemSchema).extend({
+  identifier: ProductSearchIdentifierSchema.default(() => ProductSearchIdentifierSchema.parse({})),
+  facets: z.array(ProductSearchResultFacetSchema).default(() => [])
+});
+export {
+  ProductSearchResultFacetSchema,
+  ProductSearchResultFacetValueSchema,
+  ProductSearchResultItemSchema,
+  ProductSearchResultItemVariantSchema,
+  ProductSearchResultSchema
+};

package/schemas/models/product.model.js

@@ -1,29 +1,61 @@
 import { z } from "zod";
-import { ProductIdentifierSchema, SKUIdentifierSchema } from "./identifiers.model.js";
-import { BaseModelSchema } from "./base.model.js";
-const SKUSchema = z.looseObject({
-  identifier: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({}))
-  /*    name: z.string().default(''),
-      slug: z.string().default(''),
-      image: ImageSchema.default(() => ImageSchema.parse({})), */
+import { CategoryIdentifierSchema, ProductAttributeIdentifierSchema, ProductAttributeValueIdentifierSchema, ProductIdentifierSchema, ProductOptionIdentifierSchema, ProductOptionValueIdentifierSchema, ProductVariantIdentifierSchema } from "./identifiers.model.js";
+import { BaseModelSchema, ImageSchema } from "./base.model.js";
+const ProductOptionValueSchema = z.looseObject({
+  identifier: ProductOptionValueIdentifierSchema.default(() => ProductOptionValueIdentifierSchema.parse({})).describe("The unique identifier for the product option value."),
+  label: z.string().describe("The human-friendly label for the product option value.")
+});
+const ProductOptionSchema = z.looseObject({
+  identifier: ProductOptionIdentifierSchema.default(() => ProductOptionIdentifierSchema.parse({})).describe("The unique identifier for the option."),
+  name: z.string().describe("The name of the option, e.g., Size or Color."),
+  values: z.array(ProductOptionValueSchema).default(() => []).describe("A list of possible values for the option.")
+});
+const ProductVariantOptionSchema = z.looseObject({
+  identifier: ProductOptionIdentifierSchema.default(() => ProductOptionIdentifierSchema.parse({})).describe("The unique identifier for the option."),
+  name: z.string().describe("The name of the option, e.g., Size or Color."),
+  value: ProductOptionValueSchema.default(() => ProductOptionValueSchema.parse({})).describe("The unique identifier for the option value.")
+});
+const ProductVariantSchema = z.looseObject({
+  identifier: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})).describe("The unique identifier for the variant. Often its SKU"),
+  name: z.string().default(""),
+  images: z.array(ImageSchema).default(() => []).describe("A list of images associated with the product variant"),
+  ean: z.string().default("").describe("The European Article Number identifier for the product variant"),
+  gtin: z.string().default("").describe("The Global Trade Item Number identifier for the product variant"),
+  upc: z.string().default("").describe("The Universal Product Code identifier for the product variant"),
+  barcode: z.string().default("").describe("The barcode identifier for the product variant"),
+  options: z.array(ProductVariantOptionSchema).default(() => []).describe("A list of option identifiers that define this variant")
+});
+const ProductAttributeValueSchema = z.looseObject({
+  identifier: ProductAttributeValueIdentifierSchema.default(() => ProductAttributeValueIdentifierSchema.parse({})).describe("The unique identifier for the attribute value."),
+  value: z.string().default("").describe("The value of the attribute. Typically a language independent string"),
+  label: z.string().default("").describe("The human friendly label for the attribute value. Typically a language dependent string")
 });
 const ProductAttributeSchema = z.looseObject({
-  id: z.string(),
-  name: z.string(),
-  value: z.string()
+  identifier: ProductAttributeIdentifierSchema.default(() => ProductAttributeIdentifierSchema.parse({})).describe("The unique identifier for the attribute, also typically used as the facet key if the attribute is filterable."),
+  group: z.string().default(""),
+  name: z.string().default(""),
+  values: z.array(ProductAttributeValueSchema).default(() => [])
 });
 const ProductSchema = BaseModelSchema.extend({
   identifier: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})),
-  name: z.string().default(""),
-  slug: z.string().default(""),
-  description: z.string().default(""),
-  image: z.string().url().default("https://placehold.co/400"),
-  images: z.string().url().array().default(() => []),
-  attributes: z.array(ProductAttributeSchema).default(() => []),
-  skus: z.array(SKUSchema).default(() => [])
-});
+  name: z.string().default("").describe("The name of the product"),
+  slug: z.string().default("").describe("The URL-friendly identifier for the product"),
+  description: z.string().default("").describe("A brief description of the product"),
+  longDescription: z.string().default("").describe("A detailed description of the product"),
+  brand: z.string().default("").describe("The brand associated with the product"),
+  manufacturer: z.string().default("").describe("The manufacturer of the product"),
+  parentCategories: z.array(CategoryIdentifierSchema).default(() => []).describe("A list of parent categories the product belongs to"),
+  published: z.boolean().default(false).describe("Indicates whether the product is published and visible to customers"),
+  sharedAttributes: z.array(ProductAttributeSchema).default(() => []).describe("A list of technical attributes associated with the product"),
+  options: z.array(ProductOptionSchema).default(() => []).describe("A list of options available for the product, such as size or color. Can be empty if product is single-sku"),
+  mainVariant: ProductVariantSchema.default(() => ProductVariantSchema.parse({})).describe("The primary SKU for the product")
+}).describe("A product is a wrapper around sellable items. It contains all the shared information for a set of SKUs. All products have at least one SKU, but can potentially have hundreds.");
 export {
   ProductAttributeSchema,
+  ProductAttributeValueSchema,
+  ProductOptionSchema,
+  ProductOptionValueSchema,
   ProductSchema,
-  SKUSchema
+  ProductVariantOptionSchema,
+  ProductVariantSchema
 };

package/schemas/mutations/analytics.mutation.js

@@ -1,14 +1,14 @@
 import { z } from "zod";
 import { BaseMutationSchema } from "./base.mutation.js";
-import { ProductIdentifierSchema, SearchIdentifierSchema } from "../models/identifiers.model.js";
+import { ProductIdentifierSchema, ProductSearchIdentifierSchema } from "../models/identifiers.model.js";
 const AnalyticsMutationSearchEventSchema = BaseMutationSchema.extend({
   mutation: z.literal("search"),
-  search: SearchIdentifierSchema.required(),
+  search: ProductSearchIdentifierSchema.required(),
   products: z.array(ProductIdentifierSchema)
 });
 const AnalyticsMutationSearchProductClickEventSchema = BaseMutationSchema.extend({
   mutation: z.literal("product-search-click"),
-  search: SearchIdentifierSchema.required(),
+  search: ProductSearchIdentifierSchema.required(),
   product: ProductIdentifierSchema.required(),
   position: z.number().min(0)
 });

package/schemas/mutations/cart.mutation.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
 import { BaseMutationSchema } from "./base.mutation.js";
-import { CartIdentifierSchema, CartItemIdentifierSchema, PaymentMethodIdentifierSchema, ShippingMethodIdentifierSchema, SKUIdentifierSchema } from "../models/identifiers.model.js";
+import { CartIdentifierSchema, CartItemIdentifierSchema, PaymentMethodIdentifierSchema, ShippingMethodIdentifierSchema, ProductVariantIdentifierSchema } from "../models/identifiers.model.js";
 import { AddressSchema } from "../models/profile.model.js";
 import { CurrencySchema } from "../models/currency.model.js";
 import { MonetaryAmountSchema } from "../models/price.model.js";
 const CartMutationItemAddSchema = BaseMutationSchema.extend({
   cart: CartIdentifierSchema.nonoptional(),
-  sku: SKUIdentifierSchema.nonoptional(),
+  variant: ProductVariantIdentifierSchema.nonoptional(),
   quantity: z.number()
 });
 const CartMutationItemRemoveSchema = BaseMutationSchema.extend({

package/schemas/queries/index.js

@@ -7,7 +7,7 @@ export * from "./inventory.query.js";
 export * from "./price.query.js";
 export * from "./product.query.js";
 export * from "./profile.query.js";
-export * from "./search.query.js";
+export * from "./product-search.query.js";
 export * from "./store.query.js";
 export * from "./order.query.js";
 export * from "./checkout.query.js";

package/schemas/queries/inventory.query.js

@@ -1,7 +1,7 @@
 import { BaseQuerySchema } from "./base.query.js";
-import { FulfillmentCenterIdentifierSchema, ProductIdentifierSchema } from "../models/identifiers.model.js";
+import { FulfillmentCenterIdentifierSchema, ProductIdentifierSchema, ProductVariantIdentifierSchema } from "../models/identifiers.model.js";
 const InventoryQueryBySKUSchema = BaseQuerySchema.extend({
-  sku: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})).nonoptional(),
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})).describe("The unique identifier for the product variant (SKU)."),
   fulfilmentCenter: FulfillmentCenterIdentifierSchema.default(() => FulfillmentCenterIdentifierSchema.parse({})).nonoptional()
 });
 export {

package/schemas/queries/price.query.js

@@ -1,7 +1,7 @@
 import { BaseQuerySchema } from "./base.query.js";
-import { SKUIdentifierSchema } from "../models/identifiers.model.js";
+import { ProductVariantIdentifierSchema } from "../models/identifiers.model.js";
 const PriceQueryBySkuSchema = BaseQuerySchema.extend({
-  sku: SKUIdentifierSchema.required()
+  variant: ProductVariantIdentifierSchema.required()
 });
 export {
   PriceQueryBySkuSchema

package/schemas/queries/product-search.query.js

@@ -0,0 +1,8 @@
+import { BaseQuerySchema } from "./base.query.js";
+import { ProductSearchIdentifierSchema } from "../models/identifiers.model.js";
+const ProductSearchQueryByTermSchema = BaseQuerySchema.extend({
+  search: ProductSearchIdentifierSchema.required()
+});
+export {
+  ProductSearchQueryByTermSchema
+};

package/schemas/queries/product.query.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { BaseQuerySchema } from "./base.query.js";
-import { SKUIdentifierSchema } from "../models/index.js";
+import { PaginationOptionsSchema, ProductIdentifierSchema, ProductVariantIdentifierSchema } from "../models/index.js";
 const ProductQueryBySlugSchema = BaseQuerySchema.extend({
   slug: z.string()
 });
@@ -8,10 +8,15 @@ const ProductQueryByIdSchema = BaseQuerySchema.extend({
   id: z.string()
 });
 const ProductQueryBySKUSchema = BaseQuerySchema.extend({
-  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({}))
+  variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({}))
+});
+const ProductQueryVariantsSchema = BaseQuerySchema.extend({
+  parentId: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})),
+  paginationOptions: PaginationOptionsSchema.default(() => PaginationOptionsSchema.parse({}))
 });
 export {
   ProductQueryByIdSchema,
   ProductQueryBySKUSchema,
-  ProductQueryBySlugSchema
+  ProductQueryBySlugSchema,
+  ProductQueryVariantsSchema
 };

package/src/client/client.d.ts

@@ -1,6 +1,6 @@
 import type { AnalyticsProvider } from "../providers/analytics.provider.js";
 import type { ProductProvider } from "../providers/product.provider.js";
-import type { SearchProvider } from "../providers/search.provider.js";
+import type { ProductSearchProvider } from "../providers/product-search.provider.js";
 import type { IdentityProvider } from '../providers/identity.provider.js';
 import type { CartProvider } from "../providers/cart.provider.js";
 import type { PriceProvider } from "../providers/price.provider.js";
@@ -10,7 +10,7 @@ import type { CategoryProvider } from "../providers/category.provider.js";
 import type { CheckoutProvider } from "../providers/index.js";
 export interface Client {
     product: ProductProvider;
-    search: SearchProvider;
+    productSearch: ProductSearchProvider;
     identity: IdentityProvider;
     cache: Cache;
     cart: CartProvider;

package/src/providers/index.d.ts

@@ -8,6 +8,6 @@ export * from './inventory.provider.js';
 export * from './price.provider.js';
 export * from './product.provider.js';
 export * from './profile.provider.js';
-export * from './search.provider.js';
+export * from './product-search.provider.js';
 export * from './store.provider.js';
 export * from './order.provider.js';

package/src/providers/product-search.provider.d.ts

@@ -0,0 +1,35 @@
+import type { FacetIdentifier, FacetValueIdentifier } from '../index.js';
+import type { ProductSearchResult, ProductSearchResultFacet, ProductSearchResultFacetValue, ProductSearchResultItem, ProductSearchResultItemVariant } from '../schemas/models/product-search.model.js';
+import type { ProductSearchQueryByTerm } from '../schemas/queries/product-search.query.js';
+import type { RequestContext } from '../schemas/session.schema.js';
+import { BaseProvider } from './base.provider.js';
+export declare abstract class ProductSearchProvider<T extends ProductSearchResultItem = ProductSearchResultItem> extends BaseProvider<T> {
+    abstract queryByTerm(payload: ProductSearchQueryByTerm, reqCtx: RequestContext): Promise<ProductSearchResult>;
+    protected getResourceName(): string;
+    /**
+     * Parses a facet value from the search response.
+     * @param facetValueIdentifier The identifier for the facet value.
+     * @param label The label for the facet value.
+     * @param count The count for the facet value.
+     * @param reqCtx The request context.
+     */
+    protected abstract parseFacetValue(facetValueIdentifier: FacetValueIdentifier, label: string, count: number, reqCtx: RequestContext): ProductSearchResultFacetValue;
+    /**
+     * Parses a facet from the search response.
+     * @param facetIdentifier The identifier for the facet.
+     * @param facetValue The value for the facet.
+     * @param reqCtx The request context.
+     *
+     * Usecase: Override this to customize the parsing of facets.
+     */
+    protected abstract parseFacet(facetIdentifier: FacetIdentifier, facetValue: unknown, reqCtx: RequestContext): ProductSearchResultFacet;
+    /**
+     * Parses a product variant from the search response.
+     * @param variant The variant data from the search response.
+     * @param product The product data from the search response.
+     * @param reqCtx The request context.
+     *
+     * Usecase: Override this to customize the parsing of product variants.
+     */
+    protected abstract parseVariant(variant: unknown, product: unknown, reqCtx: RequestContext): ProductSearchResultItemVariant;
+}

package/src/providers/product.provider.d.ts

@@ -3,9 +3,42 @@ import { BaseProvider } from './base.provider.js';
 import type { RequestContext } from '../schemas/session.schema.js';
 import type { ProductQueryById, ProductQueryBySKU, ProductQueryBySlug } from '../schemas/queries/product.query.js';
 export declare abstract class ProductProvider<T extends Product = Product> extends BaseProvider<T> {
+    /**
+     * Get a product by its ID.
+     * @param payload The query payload containing the product ID.
+     * @param reqCtx The request context.
+     *
+     * Usecase: Not clear. Maybe if you get a reference from marketing? But that would most likely be a partnumber.
+     * But what if the marketing system recommends products instead of variants? A product does not have a partnumber, or gtin.
+     * Marketing will TYPICALLY recommend products, and in some cases maybe HeroVariants of a product.
+     * In that case, you would need to resolve the product to its hero variant first, and then get the SKU from there.
+     */
     abstract getById(payload: ProductQueryById, reqCtx: RequestContext): Promise<T>;
+    /**
+     * Get a product by its slug.
+     * @param payload The query payload containing the product slug.
+     * @param reqCtx The request context.
+     *
+     * Usecase: You are rendering a product detail page, and you need to fetch the product by its slug.
+     */
     abstract getBySlug(payload: ProductQueryBySlug, reqCtx: RequestContext): Promise<T | null>;
-    abstract getBySKU(payload: ProductQueryBySKU | ProductQueryBySKU[], reqCtx: RequestContext): Promise<T>;
+    /**
+     * Get a product by its SKU
+     * @param payload
+     * @param reqCtx
+     *
+     * Usecase: you want to look up product details for a cart item. Or you have a SKU from an external system (e.g. ERP, PIM, Marketing, OMS/Order History),
+     * and you need to fetch the product details for that SKU. You will get the a Product back, with the variant matching the SKU set as heroSku.
+     * It might also be used on a quick-order page, or product recommendations from external system.
+     */
+    abstract getBySKU(payload: ProductQueryBySKU, reqCtx: RequestContext): Promise<T>;
+    /**
+     * Returns a set of Products for each variant. Is a paged response, to ensure we do not build in overfetching from the start.
+     *
+     * Usecase: You are rendering a variant-list on a b2b PDP page maybe, and it contains 500 variants. You do not want to fetch all 500 variants in one go.
+     * @param payload
+     * @param reqCtx
+     */
     protected createEmptyProduct(id: string): T;
     /**
      * The resource name, used for caching and logging.

package/src/schemas/capabilities.schema.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export declare const CapabilitiesSchema: z.ZodObject<{
     product: z.ZodBoolean;
-    search: z.ZodBoolean;
+    productSearch: z.ZodBoolean;
     analytics: z.ZodBoolean;
     identity: z.ZodBoolean;
     cart: z.ZodBoolean;

package/src/schemas/models/cart.model.d.ts

@@ -6,8 +6,8 @@ export declare const CartItemSchema: z.ZodObject<{
     product: z.ZodDefault<z.ZodObject<{
         key: z.ZodDefault<z.ZodString>;
     }, z.core.$loose>>;
-    sku: z.ZodDefault<z.ZodObject<{
-        key: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
+    variant: z.ZodDefault<z.ZodObject<{
+        sku: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
     }, z.core.$loose>>;
     quantity: z.ZodDefault<z.ZodNumber>;
     price: z.ZodDefault<z.ZodObject<{
@@ -778,8 +778,8 @@ export declare const CartSchema: z.ZodObject<{
         product: z.ZodDefault<z.ZodObject<{
             key: z.ZodDefault<z.ZodString>;
         }, z.core.$loose>>;
-        sku: z.ZodDefault<z.ZodObject<{
-            key: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
+        variant: z.ZodDefault<z.ZodObject<{
+            sku: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
         }, z.core.$loose>>;
         quantity: z.ZodDefault<z.ZodNumber>;
         price: z.ZodDefault<z.ZodObject<{

package/src/schemas/models/checkout.model.d.ts

@@ -3,8 +3,8 @@ export declare const CheckoutItemSchema: z.ZodObject<{
     identifier: z.ZodDefault<z.ZodObject<{
         key: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
     }, z.core.$loose>>;
-    sku: z.ZodDefault<z.ZodObject<{
-        key: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
+    variant: z.ZodDefault<z.ZodObject<{
+        sku: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
     }, z.core.$loose>>;
     quantity: z.ZodDefault<z.ZodNumber>;
     price: z.ZodDefault<z.ZodObject<{
@@ -782,8 +782,8 @@ export declare const CheckoutSchema: z.ZodObject<{
         identifier: z.ZodDefault<z.ZodObject<{
             key: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
         }, z.core.$loose>>;
-        sku: z.ZodDefault<z.ZodObject<{
-            key: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
+        variant: z.ZodDefault<z.ZodObject<{
+            sku: z.ZodNonOptional<z.ZodDefault<z.ZodString>>;
         }, z.core.$loose>>;
         quantity: z.ZodDefault<z.ZodNumber>;
         price: z.ZodDefault<z.ZodObject<{