@reactionary/core 0.11.2 → 0.12.0

package/schemas/mutations/analytics/events/index.js

@@ -0,0 +1,85 @@
+import {
+  AnalyticsMutationPageViewedSchema,
+  AnalyticsMutationSearchResultsViewedSchema,
+  AnalyticsMutationAutocompleteSuggestionSelectedSchema,
+  AnalyticsMutationCategoryViewedSchema,
+  AnalyticsMutationProductCarouselViewedSchema,
+  AnalyticsMutationProductClickedSchema,
+  AnalyticsMutationProductViewedSchema,
+  AnalyticsMutationPromotionViewedSchema,
+  AnalyticsMutationPromotionClickedSchema
+} from "./browse.mutation.js";
+import {
+  AnalyticsMutationCartItemAddedSchema,
+  AnalyticsMutationCartItemRemovedSchema,
+  AnalyticsMutationCartItemQuantityChangedSchema,
+  AnalyticsMutationCartViewedSchema,
+  AnalyticsMutationCouponAppliedSchema,
+  AnalyticsMutationCouponRejectedSchema,
+  AnalyticsMutationCheckoutStartedSchema,
+  AnalyticsMutationShippingInfoAddedSchema,
+  AnalyticsMutationPaymentInfoAddedSchema,
+  AnalyticsMutationOrderPlacedSchema,
+  AnalyticsMutationQuoteRequestedSchema,
+  AnalyticsMutationOrderReorderedSchema,
+  AnalyticsMutationCompanyRegisteredSchema
+} from "./commerce.mutation.js";
+import {
+  AnalyticsMutationUserLoggedInSchema,
+  AnalyticsMutationUserLoggedOutSchema,
+  AnalyticsMutationUserRegisteredSchema,
+  AnalyticsMutationProfileUpdatedSchema,
+  AnalyticsMutationConsentChangedSchema,
+  AnalyticsMutationNewsletterSubscribedSchema,
+  AnalyticsMutationWishlistItemAddedSchema,
+  AnalyticsMutationWishlistItemRemovedSchema,
+  AnalyticsMutationBackInStockRequestedSchema,
+  AnalyticsMutationReviewSubmittedSchema,
+  AnalyticsMutationStoreSelectedSchema,
+  AnalyticsMutationProductSharedSchema,
+  AnalyticsMutationCustomSchema
+} from "./account.mutation.js";
+export * from "./base.mutation.js";
+export * from "./browse.mutation.js";
+export * from "./commerce.mutation.js";
+export * from "./account.mutation.js";
+const AnalyticsEventMutationSchemas = {
+  "page-viewed": AnalyticsMutationPageViewedSchema,
+  "search-results-viewed": AnalyticsMutationSearchResultsViewedSchema,
+  "autocomplete-suggestion-selected": AnalyticsMutationAutocompleteSuggestionSelectedSchema,
+  "category-viewed": AnalyticsMutationCategoryViewedSchema,
+  "product-carousel-viewed": AnalyticsMutationProductCarouselViewedSchema,
+  "product-clicked": AnalyticsMutationProductClickedSchema,
+  "product-viewed": AnalyticsMutationProductViewedSchema,
+  "promotion-viewed": AnalyticsMutationPromotionViewedSchema,
+  "promotion-clicked": AnalyticsMutationPromotionClickedSchema,
+  "cart-item-added": AnalyticsMutationCartItemAddedSchema,
+  "cart-item-removed": AnalyticsMutationCartItemRemovedSchema,
+  "cart-item-quantity-changed": AnalyticsMutationCartItemQuantityChangedSchema,
+  "cart-viewed": AnalyticsMutationCartViewedSchema,
+  "coupon-applied": AnalyticsMutationCouponAppliedSchema,
+  "coupon-rejected": AnalyticsMutationCouponRejectedSchema,
+  "checkout-started": AnalyticsMutationCheckoutStartedSchema,
+  "shipping-info-added": AnalyticsMutationShippingInfoAddedSchema,
+  "payment-info-added": AnalyticsMutationPaymentInfoAddedSchema,
+  "order-placed": AnalyticsMutationOrderPlacedSchema,
+  "quote-requested": AnalyticsMutationQuoteRequestedSchema,
+  "order-reordered": AnalyticsMutationOrderReorderedSchema,
+  "company-registered": AnalyticsMutationCompanyRegisteredSchema,
+  "user-logged-in": AnalyticsMutationUserLoggedInSchema,
+  "user-logged-out": AnalyticsMutationUserLoggedOutSchema,
+  "user-registered": AnalyticsMutationUserRegisteredSchema,
+  "profile-updated": AnalyticsMutationProfileUpdatedSchema,
+  "consent-changed": AnalyticsMutationConsentChangedSchema,
+  "newsletter-subscribed": AnalyticsMutationNewsletterSubscribedSchema,
+  "wishlist-item-added": AnalyticsMutationWishlistItemAddedSchema,
+  "wishlist-item-removed": AnalyticsMutationWishlistItemRemovedSchema,
+  "back-in-stock-requested": AnalyticsMutationBackInStockRequestedSchema,
+  "review-submitted": AnalyticsMutationReviewSubmittedSchema,
+  "store-selected": AnalyticsMutationStoreSelectedSchema,
+  "product-shared": AnalyticsMutationProductSharedSchema,
+  "custom": AnalyticsMutationCustomSchema
+};
+export {
+  AnalyticsEventMutationSchemas
+};

package/schemas/mutations/analytics/index.js

@@ -17,6 +17,7 @@ export * from "./product-summary-click.mutation.js";
 export * from "./product-summary-view.mutation.js";
 export * from "./purchase.mutation.js";
 export * from "./base-event.mutation.js";
+export * from "./events/index.js";
 export {
   AnalyticsMutationSchema
 };

package/schemas/session.schema.js

@@ -3,6 +3,7 @@ import { WebStoreIdentifierSchema } from "./models/identifiers.model.js";
 import { CurrencySchema } from "./models/currency.model.js";
 import { IdentitySchema } from "./models/identity.model.js";
 import { PersonalizationProfileSchema } from "./models/personalization-profile.model.js";
+import { AnalyticsConsentSchema } from "./models/analytics/consent.model.js";
 const LanguageContextSchema = z.looseObject({
   locale: z.string().default("en-US").meta({ description: "The locale for the current request, in IETF BCP 47 format (e.g. en-US, fr-FR). This can be used for localization and internationalization purposes." }),
   // TODO: Replace this hardcoded fallback with a configured project/store currency.
@@ -14,7 +15,8 @@ const IdentityContextSchema = z.looseObject({
 });
 const SessionSchema = z.looseObject({
   identityContext: IdentityContextSchema,
-  marketingContext: PersonalizationProfileSchema.default(() => PersonalizationProfileSchema.parse({}))
+  marketingContext: PersonalizationProfileSchema.default(() => PersonalizationProfileSchema.parse({})),
+  consent: AnalyticsConsentSchema.optional().meta({ description: "The visitor's consent for analytics and marketing processing, if known. When absent, the analytics dispatcher applies its configured default." })
 });
 const TaxJurisdictionSchema = z.object({
   countryCode: z.string().default("US"),

package/src/analytics/context.d.ts

@@ -0,0 +1,85 @@
+import type { CartCapability } from '../capabilities/cart.capability.js';
+import type { CategoryCapability } from '../capabilities/category.capability.js';
+import type { CompanyCapability } from '../capabilities/company.capability.js';
+import type { IdentityCapability } from '../capabilities/identity.capability.js';
+import type { InventoryCapability } from '../capabilities/inventory.capability.js';
+import type { OrderCapability } from '../capabilities/order.capability.js';
+import type { PersonalizationProfileCapability } from '../capabilities/personalization-profile.capability.js';
+import type { PriceCapability } from '../capabilities/price.capability.js';
+import type { ProductCapability } from '../capabilities/product.capability.js';
+import type { ProfileCapability } from '../capabilities/profile.capability.js';
+import type { StoreCapability } from '../capabilities/store.capability.js';
+import type { Cart, Category, CategoryIdentifier, Company, Identity, Inventory, NotFoundError, OrderIdentifier, PersonalizationProfile, Price, Product, ProductIdentifier, ProductVariantIdentifier, Profile, RequestContext, Result, Store, StoreIdentifier, Order } from '../schemas/index.js';
+/**
+ * The capabilities lookups are bound to. Structural, so the client's own capabilities satisfy it and tests can pass stubs.
+ * Anything left out answers lookups with an error Result.
+ */
+export interface AnalyticsLookupCapabilities {
+    product?: Pick<ProductCapability, 'getById' | 'getBySKU'>;
+    category?: Pick<CategoryCapability, 'getById' | 'getBreadcrumbPathToCategory'>;
+    price?: Pick<PriceCapability, 'getCustomerPrice' | 'getListPrice'>;
+    inventory?: Pick<InventoryCapability, 'getBySKU'>;
+    cart?: Pick<CartCapability, 'getActiveCartId' | 'getById'>;
+    order?: Pick<OrderCapability, 'getById'>;
+    store?: Pick<StoreCapability, 'getById'>;
+    identity?: Pick<IdentityCapability, 'getSelf'>;
+    profile?: Pick<ProfileCapability, 'getById'>;
+    personalizationProfile?: Pick<PersonalizationProfileCapability, 'getPersonalizationProfile'>;
+    company?: Pick<CompanyCapability, 'getById'>;
+}
+export interface AnalyticsPrices {
+    customer?: Price;
+    list?: Price;
+}
+/**
+ * Read-only lookups handed to analytics subscribers so they can enrich events lazily.
+ *
+ * Every lookup goes through the client's own decorated capabilities (so caching applies), is memoized for the lifetime of
+ * this context (one flush) and returns a Result. Subscribers should degrade by sending fewer fields, not by dropping the event.
+ * There is no mutation access, and the self.* lookups only ever resolve the current session.
+ */
+export interface AnalyticsContext {
+    readonly products: {
+        byId(id: ProductIdentifier): Promise<Result<Product>>;
+        bySku(variant: ProductVariantIdentifier): Promise<Result<Product>>;
+        /** Index-aligned with the input. Concurrency-limited. */
+        many(ids: ProductIdentifier[]): Promise<Array<Result<Product>>>;
+    };
+    readonly categories: {
+        byId(id: CategoryIdentifier): Promise<Result<Category, NotFoundError>>;
+        path(id: CategoryIdentifier): Promise<Result<Category[]>>;
+    };
+    readonly prices: {
+        forSku(variant: ProductVariantIdentifier): Promise<Result<AnalyticsPrices>>;
+    };
+    readonly inventory: {
+        /** Looks up the fulfilment center of the request's store first. */
+        forSku(variant: ProductVariantIdentifier): Promise<Result<Inventory>>;
+    };
+    readonly cart: {
+        active(): Promise<Result<Cart>>;
+    };
+    readonly orders: {
+        byId(id: OrderIdentifier): Promise<Result<Order, NotFoundError>>;
+    };
+    readonly stores: {
+        byId(id: StoreIdentifier): Promise<Result<Store, NotFoundError>>;
+    };
+    readonly self: {
+        identity(): Promise<Result<Identity>>;
+        profile(): Promise<Result<Profile>>;
+        personalization(): Promise<Result<PersonalizationProfile>>;
+        /** Best effort: the company of the active cart, as core has no current company on the request context. */
+        company(): Promise<Result<Company>>;
+    };
+}
+export interface AnalyticsContextDependencies {
+    capabilities: AnalyticsLookupCapabilities;
+    requestContext: RequestContext;
+    /** Maximum parallel product lookups in `products.many`. Defaults to 5. */
+    concurrency?: number;
+}
+/**
+ * Creates a context with fresh memoization. The dispatcher creates one per flush.
+ */
+export declare function createAnalyticsContext(dependencies: AnalyticsContextDependencies): AnalyticsContext;

package/src/analytics/dispatcher.d.ts

@@ -0,0 +1,71 @@
+import { AnalyticsEventMutationSchemas } from '../schemas/index.js';
+import type { AnalyticsConsent, AnalyticsDispatchOptions, AnalyticsEvent, AnalyticsEventResult, AnalyticsEventType, AnalyticsOutcome, AnalyticsPurpose, EventContextSnapshot, RequestContext, Result } from '../schemas/index.js';
+import type { InferType } from '../zod-utils.js';
+import type { AnalyticsContext } from './context.js';
+/**
+ * Receives analytics events from the dispatcher. Providers (Unomi, Algolia, ...) and custom subscribers implement this.
+ * Subscriptions are fixed when the client is built.
+ */
+export interface AnalyticsSubscriber<K extends AnalyticsEventType = AnalyticsEventType> {
+    readonly name: string;
+    /** Exact event types, prefix wildcards such as `cart-*`, or `*`. */
+    readonly types: ReadonlyArray<K | `${string}*`>;
+    readonly purpose: AnalyticsPurpose;
+    handle(event: AnalyticsEvent<K>, ctx: AnalyticsContext): Promise<AnalyticsOutcome | void>;
+}
+/** The input of the helper for event type `K`: its required arguments plus `origin` and `properties`. */
+export type AnalyticsEventInput<K extends AnalyticsEventType> = InferType<(typeof AnalyticsEventMutationSchemas)[K]>;
+export interface AnalyticsDispatcherDependencies {
+    requestContext: RequestContext;
+    subscribers: ReadonlyArray<AnalyticsSubscriber>;
+    /** Called once per flush, so lookups are memoized for that flush only. */
+    createContext: () => AnalyticsContext;
+    options?: AnalyticsDispatchOptions;
+}
+/**
+ * Per-emit overrides, for internal callers such as the deprecated `track` adapter. The storefront-facing helpers take none:
+ * the visitor's identity is `session.marketingContext`.
+ */
+export interface AnalyticsEmitOptions {
+    /** Identifies the visitor for this event instead of `session.marketingContext.identifier`. */
+    marketingIdentifier?: EventContextSnapshot['marketingIdentifier'];
+}
+export declare function eventTypeMatches(pattern: string, type: string): boolean;
+export declare function isPurposeAllowed(purpose: AnalyticsPurpose, consent: AnalyticsConsent): boolean;
+/**
+ * Per-request dispatcher internal to analytics: one per built client, never shared between requests.
+ *
+ * `emit` validates, snapshots request state, enqueues and schedules a flush, and never throws. Delivery is isolated per
+ * subscriber: ordered within a subscriber, parallel across subscribers, and one failing subscriber does not affect another.
+ * It is not a general purpose event bus.
+ */
+export declare class AnalyticsDispatcher {
+    private readonly requestContext;
+    private readonly subscribers;
+    private readonly createContext;
+    private readonly options;
+    private readonly defaultConsent;
+    private queue;
+    private flushScheduled;
+    private readonly tails;
+    private readonly inflight;
+    constructor(dependencies: AnalyticsDispatcherDependencies);
+    /**
+     * Validates the input, captures request state, enqueues the event and schedules delivery.
+     * Never throws: invalid input and emits made from inside a subscriber are logged and dropped.
+     */
+    emit<K extends AnalyticsEventType>(type: K, input: AnalyticsEventInput<K>, options?: AnalyticsEmitOptions): Result<AnalyticsEventResult>;
+    /**
+     * Delivers everything queued so far and resolves once all deliveries, including ones already in flight, are done.
+     * For scripts, tests and runtimes without `waitUntil`. Never rejects.
+     */
+    flush(): Promise<void>;
+    /**
+     * A fresh lookup context, for analytics code that has to resolve something before it can emit (the legacy adapter).
+     */
+    lookups(): AnalyticsContext;
+    private snapshot;
+    private scheduleFlush;
+    private deliverQueued;
+    private runSubscriber;
+}

package/src/analytics/index.d.ts

@@ -0,0 +1,6 @@
+export * from './context.js';
+export * from './dispatcher.js';
+export * from './legacy-adapter.js';
+export * from './origins.js';
+export * from './recording-subscriber.js';
+export * from './refs.js';

package/src/analytics/legacy-adapter.d.ts

@@ -0,0 +1,10 @@
+import type { AnalyticsEventResult, AnalyticsMutation, Result } from '../schemas/index.js';
+import type { AnalyticsDispatcher } from './dispatcher.js';
+/**
+ * Converts a legacy `track` event into the equivalent new event and enqueues it on the dispatcher, exactly like the
+ * new helpers do. Nothing is dispatched or awaited here beyond the cart and product lookups `product-cart-add` needs.
+ *
+ * A legacy event can carry the visitor's `personalizationProfile`. It identifies the visitor for that event only, as it did
+ * before; the new helpers take no profile and use `session.marketingContext`.
+ */
+export declare function emitLegacyAnalyticsEvent(event: AnalyticsMutation, dispatcher: AnalyticsDispatcher): Promise<Result<AnalyticsEventResult>>;

package/src/analytics/origins.d.ts

@@ -0,0 +1,25 @@
+import type { AssociationKind, CartOriginKind, CategoryIdentifier, FacetValueIdentifier, Origin, OriginAssociations, OriginAutocomplete, OriginCart, OriginCategory, OriginContent, OriginDirect, OriginList, OriginOrder, OriginPdp, OriginProductList, OriginPromotion, OriginQuickOrder, OriginSearch, OrderIdentifier, ProductIdentifier, ProductListIdentifier, ProductRecommendationIdentifier, PromotionIdentifier, QuickOrderKind, SearchIdentifier } from '../schemas/index.js';
+/**
+ * Constructors for {@link Origin}. `position` is always the absolute 0-based index across pages.
+ */
+export declare function fromSearch(identifier: SearchIdentifier, position: number): OriginSearch;
+export declare function fromAutocomplete(term: string, position: number): OriginAutocomplete;
+export declare function fromCategory(categoryId: CategoryIdentifier, filters: FacetValueIdentifier[], position: number): OriginCategory;
+export declare function fromList(recommendationId: ProductRecommendationIdentifier | undefined, carouselName: string, position: number): OriginList;
+export declare function fromAssociations(productId: ProductIdentifier, kind: AssociationKind, position: number): OriginAssociations;
+export declare function fromProductList(listId: ProductListIdentifier, position: number): OriginProductList;
+export declare function fromPromotion(promotionId: PromotionIdentifier, slot: string): OriginPromotion;
+export declare function fromContent(contentId: string, slot?: string): OriginContent;
+export declare function fromCart(kind?: CartOriginKind): OriginCart;
+export declare function fromOrder(orderId: OrderIdentifier): OriginOrder;
+export declare function fromQuickOrder(kind?: QuickOrderKind): OriginQuickOrder;
+/**
+ * Nests the origin of the PDP visit so conversions on the PDP stay attributed to the search or list that led there,
+ * e.g. `fromPDP(fromSearch(id, 4))`. The storefront decides how to carry it between pages.
+ */
+export declare function fromPDP(upstream?: Origin): OriginPdp;
+export declare function fromDirect(): OriginDirect;
+/**
+ * The search an origin leads back to, looking through `fromPDP(upstream)`.
+ */
+export declare function searchOriginOf(origin: Origin | undefined): OriginSearch | undefined;

package/src/analytics/recording-subscriber.d.ts

@@ -0,0 +1,18 @@
+import type { AnalyticsEvent, AnalyticsEventType, AnalyticsPurpose } from '../schemas/index.js';
+import type { AnalyticsContext } from './context.js';
+import type { AnalyticsSubscriber } from './dispatcher.js';
+/**
+ * Subscriber that records what it receives, for tests:
+ * `await client.analytics.flush(); expect(recorder.events).toContainEqual(...)`.
+ */
+export declare class RecordingAnalyticsSubscriber implements AnalyticsSubscriber {
+    readonly name: string;
+    readonly types: ReadonlyArray<AnalyticsEventType | `${string}*`>;
+    readonly purpose: AnalyticsPurpose;
+    readonly events: AnalyticsEvent[];
+    /** Lookup contexts the subscriber was handed, one per flush. */
+    readonly contexts: AnalyticsContext[];
+    constructor(name?: string, types?: ReadonlyArray<AnalyticsEventType | `${string}*`>, purpose?: AnalyticsPurpose);
+    handle(event: AnalyticsEvent, ctx: AnalyticsContext): Promise<'accepted'>;
+    eventsOfType<K extends AnalyticsEventType>(type: K): AnalyticsEvent<K>[];
+}

package/src/analytics/refs.d.ts

@@ -0,0 +1,8 @@
+import type { AnalyticsCategoryRef, AnalyticsProductRef, AnalyticsStoreRef } from '../schemas/index.js';
+/**
+ * Events accept a model or just its identifier. These return the key either way, so providers do not
+ * need to know which one the storefront passed.
+ */
+export declare function productKey(ref: AnalyticsProductRef): string;
+export declare function categoryKey(ref: AnalyticsCategoryRef): string;
+export declare function storeKey(ref: AnalyticsStoreRef): string;

package/src/capabilities/analytics.capability.d.ts

@@ -1,21 +1,68 @@
-import type { RequestContext } from '../schemas/session.schema.js';
-import { BaseCapability } from './base.capability.js';
+import type { AnalyticsDispatcher } from '../analytics/dispatcher.js';
 import type { Cache } from '../cache/cache.interface.js';
-import { type AnalyticsMutation, type AnalyticsMutationProductAddToCartEvent, type AnalyticsMutationProductDetailsViewEvent, type AnalyticsMutationProductSummaryClickEvent, type AnalyticsMutationProductSummaryViewEvent, type AnalyticsMutationPurchaseEvent, type AnalyticsResult } from '../schemas/index.js';
-export declare abstract class AnalyticsCapability extends BaseCapability {
+import { type AnalyticsMutation, type AnalyticsResult, type AnalyticsEventResult, type AnalyticsMutationPageViewed, type AnalyticsMutationSearchResultsViewed, type AnalyticsMutationAutocompleteSuggestionSelected, type AnalyticsMutationCategoryViewed, type AnalyticsMutationProductCarouselViewed, type AnalyticsMutationProductClicked, type AnalyticsMutationProductViewed, type AnalyticsMutationPromotionViewed, type AnalyticsMutationPromotionClicked, type AnalyticsMutationCartItemAdded, type AnalyticsMutationCartItemRemoved, type AnalyticsMutationCartItemQuantityChanged, type AnalyticsMutationCartViewed, type AnalyticsMutationCouponApplied, type AnalyticsMutationCouponRejected, type AnalyticsMutationCheckoutStarted, type AnalyticsMutationShippingInfoAdded, type AnalyticsMutationPaymentInfoAdded, type AnalyticsMutationOrderPlaced, type AnalyticsMutationQuoteRequested, type AnalyticsMutationOrderReordered, type AnalyticsMutationCompanyRegistered, type AnalyticsMutationUserLoggedIn, type AnalyticsMutationUserLoggedOut, type AnalyticsMutationUserRegistered, type AnalyticsMutationProfileUpdated, type AnalyticsMutationConsentChanged, type AnalyticsMutationNewsletterSubscribed, type AnalyticsMutationWishlistItemAdded, type AnalyticsMutationWishlistItemRemoved, type AnalyticsMutationBackInStockRequested, type AnalyticsMutationReviewSubmitted, type AnalyticsMutationStoreSelected, type AnalyticsMutationProductShared, type AnalyticsMutationCustom, type RequestContext, type Result } from '../schemas/index.js';
+import { BaseCapability } from './base.capability.js';
+/**
+ * What storefronts use: `client.analytics.cartItemAdded({ ... })`. Storefronts never know which vendors receive events.
+ *
+ * Every event comes from an explicit call here; other capabilities never emit analytics events on their own. Each helper
+ * validates its payload, enqueues the event on the client's per-request dispatcher and returns its id without waiting for
+ * any vendor. Delivery happens after the response via the dispatcher's `waitUntil`, or call {@link flush}.
+ */
+export declare class AnalyticsCapability extends BaseCapability {
+    protected readonly dispatcher: AnalyticsDispatcher;
+    constructor(cache: Cache, context: RequestContext, dispatcher: AnalyticsDispatcher);
     protected getResourceName(): string;
+    /**
+     * Delivers everything queued so far and resolves once delivery is done. For scripts, tests and
+     * runtimes without `waitUntil`. Never rejects.
+     */
+    flush(): Promise<void>;
+    /**
+     * @deprecated Use the event helpers, e.g. `productViewed`, `cartItemAdded`, `orderPlaced`.
+     *
+     * Compatibility is at the API level only: the event is converted to its new equivalent and enqueued exactly like the helpers
+     * do, with no immediate dispatch and no waiting on providers. The returned `AnalyticsResult` keeps its shape so callers
+     * keep compiling, but its outcomes no longer reflect what providers did: it holds one `accepted` outcome for the analytics
+     * capability when the event was enqueued, or `rejected` when it could not be (invalid input, or for `product-cart-add`
+     * when the active cart or the product could not be looked up). A `personalizationProfile` on the legacy
+     * event identifies the visitor for that event only. Prefer setting `session.marketingContext` to the resolved profile
+     * and emitting through the helpers, which take no profile.
+     */
     track(event: AnalyticsMutation): Promise<AnalyticsResult>;
-    protected processProductSummaryView(_event: AnalyticsMutationProductSummaryViewEvent): Promise<AnalyticsResult>;
-    protected processProductSummaryClick(_event: AnalyticsMutationProductSummaryClickEvent): Promise<AnalyticsResult>;
-    protected processProductDetailsView(_event: AnalyticsMutationProductDetailsViewEvent): Promise<AnalyticsResult>;
-    protected processProductAddToCart(_event: AnalyticsMutationProductAddToCartEvent): Promise<AnalyticsResult>;
-    protected processPurchase(_event: AnalyticsMutationPurchaseEvent): Promise<AnalyticsResult>;
-    protected accepted(): AnalyticsResult;
-    protected ignored(): AnalyticsResult;
-    protected rejected(): AnalyticsResult;
-}
-export declare class MulticastAnalyticsCapability extends AnalyticsCapability {
-    protected capabilities: Array<AnalyticsCapability>;
-    constructor(cache: Cache, requestContext: RequestContext, capabilities: Array<AnalyticsCapability>);
-    track(event: AnalyticsMutation): Promise<AnalyticsResult>;
+    pageViewed(payload: AnalyticsMutationPageViewed): Promise<Result<AnalyticsEventResult>>;
+    searchResultsViewed(payload: AnalyticsMutationSearchResultsViewed): Promise<Result<AnalyticsEventResult>>;
+    autocompleteSuggestionSelected(payload: AnalyticsMutationAutocompleteSuggestionSelected): Promise<Result<AnalyticsEventResult>>;
+    categoryViewed(payload: AnalyticsMutationCategoryViewed): Promise<Result<AnalyticsEventResult>>;
+    productCarouselViewed(payload: AnalyticsMutationProductCarouselViewed): Promise<Result<AnalyticsEventResult>>;
+    productClicked(payload: AnalyticsMutationProductClicked): Promise<Result<AnalyticsEventResult>>;
+    productViewed(payload: AnalyticsMutationProductViewed): Promise<Result<AnalyticsEventResult>>;
+    promotionViewed(payload: AnalyticsMutationPromotionViewed): Promise<Result<AnalyticsEventResult>>;
+    promotionClicked(payload: AnalyticsMutationPromotionClicked): Promise<Result<AnalyticsEventResult>>;
+    cartItemAdded(payload: AnalyticsMutationCartItemAdded): Promise<Result<AnalyticsEventResult>>;
+    cartItemRemoved(payload: AnalyticsMutationCartItemRemoved): Promise<Result<AnalyticsEventResult>>;
+    cartItemQuantityChanged(payload: AnalyticsMutationCartItemQuantityChanged): Promise<Result<AnalyticsEventResult>>;
+    cartViewed(payload: AnalyticsMutationCartViewed): Promise<Result<AnalyticsEventResult>>;
+    couponApplied(payload: AnalyticsMutationCouponApplied): Promise<Result<AnalyticsEventResult>>;
+    couponRejected(payload: AnalyticsMutationCouponRejected): Promise<Result<AnalyticsEventResult>>;
+    checkoutStarted(payload: AnalyticsMutationCheckoutStarted): Promise<Result<AnalyticsEventResult>>;
+    shippingInfoAdded(payload: AnalyticsMutationShippingInfoAdded): Promise<Result<AnalyticsEventResult>>;
+    paymentInfoAdded(payload: AnalyticsMutationPaymentInfoAdded): Promise<Result<AnalyticsEventResult>>;
+    orderPlaced(payload: AnalyticsMutationOrderPlaced): Promise<Result<AnalyticsEventResult>>;
+    quoteRequested(payload: AnalyticsMutationQuoteRequested): Promise<Result<AnalyticsEventResult>>;
+    orderReordered(payload: AnalyticsMutationOrderReordered): Promise<Result<AnalyticsEventResult>>;
+    companyRegistered(payload: AnalyticsMutationCompanyRegistered): Promise<Result<AnalyticsEventResult>>;
+    userLoggedIn(payload: AnalyticsMutationUserLoggedIn): Promise<Result<AnalyticsEventResult>>;
+    userLoggedOut(payload: AnalyticsMutationUserLoggedOut): Promise<Result<AnalyticsEventResult>>;
+    userRegistered(payload: AnalyticsMutationUserRegistered): Promise<Result<AnalyticsEventResult>>;
+    profileUpdated(payload: AnalyticsMutationProfileUpdated): Promise<Result<AnalyticsEventResult>>;
+    consentChanged(payload: AnalyticsMutationConsentChanged): Promise<Result<AnalyticsEventResult>>;
+    newsletterSubscribed(payload: AnalyticsMutationNewsletterSubscribed): Promise<Result<AnalyticsEventResult>>;
+    wishlistItemAdded(payload: AnalyticsMutationWishlistItemAdded): Promise<Result<AnalyticsEventResult>>;
+    wishlistItemRemoved(payload: AnalyticsMutationWishlistItemRemoved): Promise<Result<AnalyticsEventResult>>;
+    backInStockRequested(payload: AnalyticsMutationBackInStockRequested): Promise<Result<AnalyticsEventResult>>;
+    reviewSubmitted(payload: AnalyticsMutationReviewSubmitted): Promise<Result<AnalyticsEventResult>>;
+    storeSelected(payload: AnalyticsMutationStoreSelected): Promise<Result<AnalyticsEventResult>>;
+    productShared(payload: AnalyticsMutationProductShared): Promise<Result<AnalyticsEventResult>>;
+    custom(payload: AnalyticsMutationCustom): Promise<Result<AnalyticsEventResult>>;
 }

package/src/capabilities/analytics.provider.d.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsContext } from '../analytics/context.js';
+import type { AnalyticsSubscriber } from '../analytics/dispatcher.js';
+import type { AnalyticsEvent, AnalyticsEventType, AnalyticsOutcome, AnalyticsPurpose } from '../schemas/index.js';
+import { BaseCapability } from './base.capability.js';
+/**
+ * Base class for vendor analytics integrations (Unomi, Algolia, Google Analytics, ...).
+ *
+ * Providers are not called by the storefront. The `ClientBuilder` registers them as subscribers of the client's
+ * per-request dispatcher, which hands them events together with a read-only {@link AnalyticsContext} to enrich from.
+ */
+export declare abstract class AnalyticsProvider extends BaseCapability implements AnalyticsSubscriber {
+    /** Unique within a client. Used in logs and tracing. Defaults to the resource name. */
+    get name(): string;
+    /** Event types handled: exact types, prefix wildcards such as `cart-*`, or `*`. */
+    abstract readonly types: ReadonlyArray<AnalyticsEventType | `${string}*`>;
+    /** What the provider uses events for. The dispatcher skips providers whose purpose lacks consent. */
+    abstract readonly purpose: AnalyticsPurpose;
+    /**
+     * Handles one event. Throwing is safe: the dispatcher isolates failures per provider.
+     * Degrade by sending fewer fields when a lookup on `ctx` fails; do not drop the event for that.
+     */
+    abstract handle(event: AnalyticsEvent, ctx: AnalyticsContext): Promise<AnalyticsOutcome | void>;
+    protected getResourceName(): string;
+}

package/src/capabilities/index.d.ts

@@ -1,4 +1,5 @@
 export * from './analytics.capability.js';
+export * from './analytics.provider.js';
 export * from './base.capability.js';
 export * from './cart.capability.js';
 export * from './category.capability.js';

package/src/client/client-builder.d.ts

@@ -1,25 +1,48 @@
 import type { Cache } from '../cache/cache.interface.js';
 import type { Client } from './client.js';
+import type { AnalyticsProvider } from '../capabilities/analytics.provider.js';
+import { type AnalyticsSubscriber } from '../analytics/dispatcher.js';
+import type { AnalyticsDispatchOptions } from '../schemas/models/analytics/dispatch.model.js';
 import { type RequestContext } from '../schemas/session.schema.js';
 export interface ClientBuilderFactoryArgs {
     cache: Cache;
     context: RequestContext;
 }
+/**
+ * What capability factories return: the client's capabilities, except `analytics`, which is a vendor
+ * {@link AnalyticsProvider} the builder registers as a subscriber. `client.analytics` itself is always built by the builder.
+ */
+export type ClientCapabilities = Omit<Partial<Client>, 'analytics'> & {
+    analytics?: AnalyticsProvider;
+};
 export type CapabilityFactory<T> = ((cache: Cache, context: RequestContext) => T) | ((args: ClientBuilderFactoryArgs) => T);
-type MergeCapabilities<Acc, New> = Omit<Acc, keyof New> & New;
+type MergeCapabilities<Acc, New> = Omit<Acc, keyof New | 'analytics'> & Omit<New, 'analytics'> & Pick<Acc, Extract<'analytics', keyof Acc>>;
 export type CapabilityCollisionStrategy = 'last-wins' | 'first-wins' | 'throw';
 export declare class ClientBuilder<TClient = Client> {
     private factories;
     private cache;
     private context;
     private collisionStrategy;
+    private analyticsOptions;
+    private analyticsSubscribers;
     constructor(context: RequestContext);
-    withCapability<TNew extends Partial<Client>>(factory: CapabilityFactory<TNew>): ClientBuilder<MergeCapabilities<TClient, TNew>>;
+    withCapability<TNew extends ClientCapabilities>(factory: CapabilityFactory<TNew>): ClientBuilder<MergeCapabilities<TClient, TNew>>;
     withCache(cache: Cache): ClientBuilder<TClient>;
     withCollisionStrategy(strategy: CapabilityCollisionStrategy): ClientBuilder<TClient>;
+    /**
+     * Configures how analytics events are delivered, e.g. `{ waitUntil: after }` in Next.js so vendor calls finish after the
+     * response, or a `defaultConsent` for requests whose session carries no consent. Optional.
+     */
+    withAnalyticsDispatch(options: AnalyticsDispatchOptions): ClientBuilder<TClient>;
+    /**
+     * Adds a custom analytics subscriber next to the providers registered by capability factories. Subscriptions are
+     * fixed at build time; there is no way to subscribe at runtime.
+     */
+    withAnalyticsSubscriber(subscriber: AnalyticsSubscriber): ClientBuilder<TClient>;
     build(): TClient & {
         cache: Cache;
     };
+    private clone;
     private resolveFactory;
     private mergeCapabilities;
 }

package/src/index.d.ts

@@ -3,6 +3,7 @@ export * from './client/index.js';
 export * from './decorators/index.js';
 export * from './factories/index.js';
 export * from './capabilities/index.js';
+export * from './analytics/index.js';
 export * from './schemas/index.js';
 export * from './initialization.js';
 export * from './metrics/protocol.js';

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

@@ -1,6 +1,7 @@
 import * as z from 'zod';
 import type { InferType } from '../zod-utils.js';
 import type { Client } from '../client/client.js';
+import type { AnalyticsProvider } from '../capabilities/analytics.provider.js';
 export declare const CapabilitiesSchema: z.ZodObject<{
     product: z.ZodBoolean;
     productSearch: z.ZodBoolean;
@@ -24,6 +25,12 @@ export declare const CapabilitiesSchema: z.ZodObject<{
     company: z.ZodBoolean;
 }, z.core.$loose>;
 export type Capabilities = InferType<typeof CapabilitiesSchema>;
+/**
+ * What a factory provides for a capability key. For `analytics` that is a vendor provider; `client.analytics`
+ * itself is the storefront-facing capability the builder creates.
+ */
+type ProvidedCapability<K extends keyof Client> = K extends 'analytics' ? AnalyticsProvider : Client[K];
 export type ClientFromCapabilities<C extends Partial<Capabilities>> = {
-    [K in keyof C & keyof Client as C[K] extends true ? K : never]: Client[K];
+    [K in keyof C & keyof Client as C[K] extends true ? K : never]: ProvidedCapability<K>;
 };
+export {};

package/src/schemas/models/analytics/consent.model.d.ts

@@ -0,0 +1,13 @@
+import * as z from 'zod';
+import type { InferType } from '../../../zod-utils.js';
+export declare const AnalyticsPurposeSchema: z.ZodEnum<{
+    necessary: "necessary";
+    analytics: "analytics";
+    marketing: "marketing";
+}>;
+export declare const AnalyticsConsentSchema: z.ZodObject<{
+    analytics: z.ZodBoolean;
+    marketing: z.ZodBoolean;
+}, z.core.$loose>;
+export type AnalyticsPurpose = InferType<typeof AnalyticsPurposeSchema>;
+export type AnalyticsConsent = InferType<typeof AnalyticsConsentSchema>;

package/src/schemas/models/analytics/dispatch.model.d.ts

@@ -0,0 +1,29 @@
+import * as z from 'zod';
+import type { InferType } from '../../../zod-utils.js';
+/**
+ * Keeps work alive after the response has been sent, e.g. Next's `after`.
+ */
+export type AnalyticsWaitUntil = (promise: Promise<unknown>) => void;
+/**
+ * The declarative part of an analytics subscriber. `handle` is a member of the subscriber itself.
+ */
+export declare const AnalyticsSubscriberDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    types: z.ZodArray<z.ZodString>;
+    purpose: z.ZodEnum<{
+        necessary: "necessary";
+        analytics: "analytics";
+        marketing: "marketing";
+    }>;
+}, z.core.$loose>;
+export declare const AnalyticsDispatchOptionsSchema: z.ZodObject<{
+    waitUntil: z.ZodOptional<z.ZodCustom<AnalyticsWaitUntil, AnalyticsWaitUntil>>;
+    defaultConsent: z.ZodOptional<z.ZodObject<{
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type AnalyticsSubscriberDescriptor = InferType<typeof AnalyticsSubscriberDescriptorSchema>;
+export type AnalyticsDispatchOptions = Omit<InferType<typeof AnalyticsDispatchOptionsSchema>, 'waitUntil'> & {
+    waitUntil?: AnalyticsWaitUntil;
+};