@reactionary/core 0.11.2 → 0.12.0

package/capabilities/analytics.capability.js

@@ -8,102 +8,283 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (kind && result) __defProp(target, key, result);
   return result;
 };
-import { BaseCapability } from "./base.capability.js";
+import { emitLegacyAnalyticsEvent } from "../analytics/legacy-adapter.js";
+import { Reactionary } from "../decorators/reactionary.decorator.js";
 import {
+  AnalyticsEventResultSchema,
   AnalyticsMutationSchema,
-  AnalyticsResultSchema
+  AnalyticsResultSchema,
+  AnalyticsMutationPageViewedSchema,
+  AnalyticsMutationSearchResultsViewedSchema,
+  AnalyticsMutationAutocompleteSuggestionSelectedSchema,
+  AnalyticsMutationCategoryViewedSchema,
+  AnalyticsMutationProductCarouselViewedSchema,
+  AnalyticsMutationProductClickedSchema,
+  AnalyticsMutationProductViewedSchema,
+  AnalyticsMutationPromotionViewedSchema,
+  AnalyticsMutationPromotionClickedSchema,
+  AnalyticsMutationCartItemAddedSchema,
+  AnalyticsMutationCartItemRemovedSchema,
+  AnalyticsMutationCartItemQuantityChangedSchema,
+  AnalyticsMutationCartViewedSchema,
+  AnalyticsMutationCouponAppliedSchema,
+  AnalyticsMutationCouponRejectedSchema,
+  AnalyticsMutationCheckoutStartedSchema,
+  AnalyticsMutationShippingInfoAddedSchema,
+  AnalyticsMutationPaymentInfoAddedSchema,
+  AnalyticsMutationOrderPlacedSchema,
+  AnalyticsMutationQuoteRequestedSchema,
+  AnalyticsMutationOrderReorderedSchema,
+  AnalyticsMutationCompanyRegisteredSchema,
+  AnalyticsMutationUserLoggedInSchema,
+  AnalyticsMutationUserLoggedOutSchema,
+  AnalyticsMutationUserRegisteredSchema,
+  AnalyticsMutationProfileUpdatedSchema,
+  AnalyticsMutationConsentChangedSchema,
+  AnalyticsMutationNewsletterSubscribedSchema,
+  AnalyticsMutationWishlistItemAddedSchema,
+  AnalyticsMutationWishlistItemRemovedSchema,
+  AnalyticsMutationBackInStockRequestedSchema,
+  AnalyticsMutationReviewSubmittedSchema,
+  AnalyticsMutationStoreSelectedSchema,
+  AnalyticsMutationProductSharedSchema,
+  AnalyticsMutationCustomSchema
 } from "../schemas/index.js";
-import { Reactionary } from "../decorators/reactionary.decorator.js";
+import { BaseCapability } from "./base.capability.js";
 class AnalyticsCapability extends BaseCapability {
+  dispatcher;
+  constructor(cache, context, dispatcher) {
+    super(cache, context);
+    this.dispatcher = dispatcher;
+  }
   getResourceName() {
     return "analytics";
   }
+  /**
+   * Delivers everything queued so far and resolves once delivery is done. For scripts, tests and
+   * runtimes without `waitUntil`. Never rejects.
+   */
+  async flush() {
+    await this.dispatcher.flush();
+  }
   async track(event) {
-    switch (event.event) {
-      case "product-summary-view":
-        return this.processProductSummaryView(event);
-      case "product-summary-click":
-        return this.processProductSummaryClick(event);
-      case "product-details-view":
-        return this.processProductDetailsView(event);
-      case "product-cart-add":
-        return this.processProductAddToCart(event);
-      case "purchase":
-        return this.processPurchase(event);
-      default:
-        return this.ignored();
-    }
-  }
-  async processProductSummaryView(_event) {
-    return this.ignored();
-  }
-  async processProductSummaryClick(_event) {
-    return this.ignored();
-  }
-  async processProductDetailsView(_event) {
-    return this.ignored();
-  }
-  async processProductAddToCart(_event) {
-    return this.ignored();
-  }
-  async processPurchase(_event) {
-    return this.ignored();
-  }
-  accepted() {
-    return {
-      outcomes: [
-        {
-          provider: this.getResourceName(),
-          outcome: "accepted"
-        }
-      ]
-    };
-  }
-  ignored() {
-    return {
-      outcomes: [
-        {
-          provider: this.getResourceName(),
-          outcome: "ignored"
-        }
-      ]
-    };
-  }
-  rejected() {
-    return {
-      outcomes: [
-        {
-          provider: this.getResourceName(),
-          outcome: "rejected"
-        }
-      ]
-    };
+    const result = await emitLegacyAnalyticsEvent(event, this.dispatcher);
+    return { outcomes: [{ provider: this.getResourceName(), outcome: result.success ? "accepted" : "rejected" }] };
   }
-}
-class MulticastAnalyticsCapability extends AnalyticsCapability {
-  capabilities;
-  constructor(cache, requestContext, capabilities) {
-    super(cache, requestContext);
-    this.capabilities = capabilities;
+  async pageViewed(payload) {
+    return this.dispatcher.emit("page-viewed", payload);
   }
-  async track(event) {
-    const tracks = [];
-    for (const capability of this.capabilities) {
-      tracks.push(capability.track(event));
-    }
-    const results = await Promise.all(tracks);
-    return {
-      outcomes: results.flatMap((result) => result.outcomes)
-    };
+  async searchResultsViewed(payload) {
+    return this.dispatcher.emit("search-results-viewed", payload);
+  }
+  async autocompleteSuggestionSelected(payload) {
+    return this.dispatcher.emit("autocomplete-suggestion-selected", payload);
+  }
+  async categoryViewed(payload) {
+    return this.dispatcher.emit("category-viewed", payload);
+  }
+  async productCarouselViewed(payload) {
+    return this.dispatcher.emit("product-carousel-viewed", payload);
+  }
+  async productClicked(payload) {
+    return this.dispatcher.emit("product-clicked", payload);
+  }
+  async productViewed(payload) {
+    return this.dispatcher.emit("product-viewed", payload);
+  }
+  async promotionViewed(payload) {
+    return this.dispatcher.emit("promotion-viewed", payload);
+  }
+  async promotionClicked(payload) {
+    return this.dispatcher.emit("promotion-clicked", payload);
+  }
+  async cartItemAdded(payload) {
+    return this.dispatcher.emit("cart-item-added", payload);
+  }
+  async cartItemRemoved(payload) {
+    return this.dispatcher.emit("cart-item-removed", payload);
+  }
+  async cartItemQuantityChanged(payload) {
+    return this.dispatcher.emit("cart-item-quantity-changed", payload);
+  }
+  async cartViewed(payload) {
+    return this.dispatcher.emit("cart-viewed", payload);
+  }
+  async couponApplied(payload) {
+    return this.dispatcher.emit("coupon-applied", payload);
+  }
+  async couponRejected(payload) {
+    return this.dispatcher.emit("coupon-rejected", payload);
+  }
+  async checkoutStarted(payload) {
+    return this.dispatcher.emit("checkout-started", payload);
+  }
+  async shippingInfoAdded(payload) {
+    return this.dispatcher.emit("shipping-info-added", payload);
+  }
+  async paymentInfoAdded(payload) {
+    return this.dispatcher.emit("payment-info-added", payload);
+  }
+  async orderPlaced(payload) {
+    return this.dispatcher.emit("order-placed", payload);
+  }
+  async quoteRequested(payload) {
+    return this.dispatcher.emit("quote-requested", payload);
+  }
+  async orderReordered(payload) {
+    return this.dispatcher.emit("order-reordered", payload);
+  }
+  async companyRegistered(payload) {
+    return this.dispatcher.emit("company-registered", payload);
+  }
+  async userLoggedIn(payload) {
+    return this.dispatcher.emit("user-logged-in", payload);
+  }
+  async userLoggedOut(payload) {
+    return this.dispatcher.emit("user-logged-out", payload);
+  }
+  async userRegistered(payload) {
+    return this.dispatcher.emit("user-registered", payload);
+  }
+  async profileUpdated(payload) {
+    return this.dispatcher.emit("profile-updated", payload);
+  }
+  async consentChanged(payload) {
+    return this.dispatcher.emit("consent-changed", payload);
+  }
+  async newsletterSubscribed(payload) {
+    return this.dispatcher.emit("newsletter-subscribed", payload);
+  }
+  async wishlistItemAdded(payload) {
+    return this.dispatcher.emit("wishlist-item-added", payload);
+  }
+  async wishlistItemRemoved(payload) {
+    return this.dispatcher.emit("wishlist-item-removed", payload);
+  }
+  async backInStockRequested(payload) {
+    return this.dispatcher.emit("back-in-stock-requested", payload);
+  }
+  async reviewSubmitted(payload) {
+    return this.dispatcher.emit("review-submitted", payload);
+  }
+  async storeSelected(payload) {
+    return this.dispatcher.emit("store-selected", payload);
+  }
+  async productShared(payload) {
+    return this.dispatcher.emit("product-shared", payload);
+  }
+  async custom(payload) {
+    return this.dispatcher.emit("custom", payload);
   }
 }
 __decorateClass([
-  Reactionary({
-    inputSchema: AnalyticsMutationSchema,
-    outputSchema: AnalyticsResultSchema
-  })
-], MulticastAnalyticsCapability.prototype, "track", 1);
+  Reactionary({ inputSchema: AnalyticsMutationSchema, outputSchema: AnalyticsResultSchema })
+], AnalyticsCapability.prototype, "track", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationPageViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "pageViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationSearchResultsViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "searchResultsViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationAutocompleteSuggestionSelectedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "autocompleteSuggestionSelected", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCategoryViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "categoryViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationProductCarouselViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "productCarouselViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationProductClickedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "productClicked", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationProductViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "productViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationPromotionViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "promotionViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationPromotionClickedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "promotionClicked", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCartItemAddedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "cartItemAdded", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCartItemRemovedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "cartItemRemoved", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCartItemQuantityChangedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "cartItemQuantityChanged", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCartViewedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "cartViewed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCouponAppliedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "couponApplied", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCouponRejectedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "couponRejected", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCheckoutStartedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "checkoutStarted", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationShippingInfoAddedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "shippingInfoAdded", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationPaymentInfoAddedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "paymentInfoAdded", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationOrderPlacedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "orderPlaced", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationQuoteRequestedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "quoteRequested", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationOrderReorderedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "orderReordered", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCompanyRegisteredSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "companyRegistered", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationUserLoggedInSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "userLoggedIn", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationUserLoggedOutSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "userLoggedOut", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationUserRegisteredSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "userRegistered", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationProfileUpdatedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "profileUpdated", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationConsentChangedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "consentChanged", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationNewsletterSubscribedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "newsletterSubscribed", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationWishlistItemAddedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "wishlistItemAdded", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationWishlistItemRemovedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "wishlistItemRemoved", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationBackInStockRequestedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "backInStockRequested", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationReviewSubmittedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "reviewSubmitted", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationStoreSelectedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "storeSelected", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationProductSharedSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "productShared", 1);
+__decorateClass([
+  Reactionary({ inputSchema: AnalyticsMutationCustomSchema, outputSchema: AnalyticsEventResultSchema })
+], AnalyticsCapability.prototype, "custom", 1);
 export {
-  AnalyticsCapability,
-  MulticastAnalyticsCapability
+  AnalyticsCapability
 };

package/capabilities/analytics.provider.js

@@ -0,0 +1,13 @@
+import { BaseCapability } from "./base.capability.js";
+class AnalyticsProvider extends BaseCapability {
+  /** Unique within a client. Used in logs and tracing. Defaults to the resource name. */
+  get name() {
+    return this.getResourceName();
+  }
+  getResourceName() {
+    return "analytics";
+  }
+}
+export {
+  AnalyticsProvider
+};

package/capabilities/index.js

@@ -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/client/client-builder.js

@@ -1,5 +1,7 @@
 import { NoOpCache } from "../cache/noop-cache.js";
-import { MulticastAnalyticsCapability } from "../capabilities/analytics.capability.js";
+import { AnalyticsCapability } from "../capabilities/analytics.capability.js";
+import { createAnalyticsContext } from "../analytics/context.js";
+import { AnalyticsDispatcher } from "../analytics/dispatcher.js";
 import {
   RequestContextSchema
 } from "../schemas/session.schema.js";
@@ -9,33 +11,44 @@ class ClientBuilder {
   cache;
   context;
   collisionStrategy = "last-wins";
+  analyticsOptions = {};
+  analyticsSubscribers = [];
   constructor(context) {
     this.context = context;
   }
   withCapability(factory) {
-    const newBuilder = new ClientBuilder(this.context);
+    const newBuilder = this.clone();
     newBuilder.factories = [...this.factories, factory];
-    newBuilder.cache = this.cache;
-    newBuilder.context = this.context;
-    newBuilder.collisionStrategy = this.collisionStrategy;
     return newBuilder;
   }
   withCache(cache) {
-    const newBuilder = new ClientBuilder(this.context);
-    newBuilder.factories = [...this.factories];
+    const newBuilder = this.clone();
     newBuilder.cache = cache;
-    newBuilder.context = this.context;
-    newBuilder.collisionStrategy = this.collisionStrategy;
     return newBuilder;
   }
   withCollisionStrategy(strategy) {
-    const newBuilder = new ClientBuilder(this.context);
-    newBuilder.factories = [...this.factories];
-    newBuilder.cache = this.cache;
-    newBuilder.context = this.context;
+    const newBuilder = this.clone();
     newBuilder.collisionStrategy = strategy;
     return newBuilder;
   }
+  /**
+   * 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) {
+    const newBuilder = this.clone();
+    newBuilder.analyticsOptions = { ...this.analyticsOptions, ...options };
+    return newBuilder;
+  }
+  /**
+   * 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) {
+    const newBuilder = this.clone();
+    newBuilder.analyticsSubscribers = [...this.analyticsSubscribers, subscriber];
+    return newBuilder;
+  }
   build() {
     let client = {};
     const sharedCache = this.cache || new NoOpCache();
@@ -43,26 +56,42 @@ class ClientBuilder {
     if (!validatedContext.success) {
       throw new Error("Invalid context: " + validatedContext.error);
     }
-    const mergedAnalytics = [];
+    const analyticsProviders = [];
     const mergedProductRecommendations = [];
     for (const factory of this.factories) {
       const capability = this.resolveFactory(factory, sharedCache, this.context);
       client = this.mergeCapabilities(client, capability);
       if (capability.analytics) {
-        mergedAnalytics.push(capability.analytics);
+        analyticsProviders.push(capability.analytics);
       }
       if (capability.productRecommendations) {
         mergedProductRecommendations.push(capability.productRecommendations);
       }
     }
+    const dispatcher = new AnalyticsDispatcher({
+      requestContext: this.context,
+      subscribers: [...analyticsProviders, ...this.analyticsSubscribers],
+      // Lookups use the client's own capabilities (and so its cache); `client` is complete by the time anything is flushed.
+      createContext: () => createAnalyticsContext({ capabilities: client, requestContext: this.context }),
+      options: this.analyticsOptions
+    });
     const completeClient = {
       ...client,
-      analytics: new MulticastAnalyticsCapability(sharedCache, this.context, mergedAnalytics),
+      analytics: new AnalyticsCapability(sharedCache, this.context, dispatcher),
       productRecommendations: new MulticastProductRecommendationsCapability(sharedCache, this.context, mergedProductRecommendations),
       cache: sharedCache
     };
     return completeClient;
   }
+  clone() {
+    const newBuilder = new ClientBuilder(this.context);
+    newBuilder.factories = [...this.factories];
+    newBuilder.cache = this.cache;
+    newBuilder.collisionStrategy = this.collisionStrategy;
+    newBuilder.analyticsOptions = this.analyticsOptions;
+    newBuilder.analyticsSubscribers = [...this.analyticsSubscribers];
+    return newBuilder;
+  }
   resolveFactory(factory, cache, context) {
     if (factory.length <= 1) {
       return factory({ cache, context });

package/index.js

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/core",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",

package/schemas/models/analytics/consent.model.js

@@ -0,0 +1,10 @@
+import * as z from "zod";
+const AnalyticsPurposeSchema = z.enum(["necessary", "analytics", "marketing"]).meta({ description: 'The purpose an analytics subscriber processes events for. "necessary" is always allowed; the others require granted consent.' });
+const AnalyticsConsentSchema = z.looseObject({
+  analytics: z.boolean().meta({ description: "True if the visitor has granted consent to analytics processing." }),
+  marketing: z.boolean().meta({ description: "True if the visitor has granted consent to marketing processing." })
+});
+export {
+  AnalyticsConsentSchema,
+  AnalyticsPurposeSchema
+};

package/schemas/models/analytics/dispatch.model.js

@@ -0,0 +1,15 @@
+import * as z from "zod";
+import { AnalyticsConsentSchema, AnalyticsPurposeSchema } from "./consent.model.js";
+const AnalyticsSubscriberDescriptorSchema = z.looseObject({
+  name: z.string().min(1).meta({ description: 'Unique subscriber name, e.g. "unomi" or "algolia". Used in logs and tracing.' }),
+  types: z.array(z.string().min(1)).min(1).meta({ description: 'Event types handled: an exact type, a prefix wildcard such as "cart-*", or "*".' }),
+  purpose: AnalyticsPurposeSchema
+});
+const AnalyticsDispatchOptionsSchema = z.looseObject({
+  waitUntil: z.custom((value) => typeof value === "function", "waitUntil must be a function").optional().meta({ description: "Called with the delivery promise so the runtime keeps it alive after the response. Without it, delivery is fire-and-forget with errors logged." }),
+  defaultConsent: AnalyticsConsentSchema.optional().meta({ description: "Consent applied when the session carries none. Defaults to everything granted, which preserves behaviour from before consent existed." })
+});
+export {
+  AnalyticsDispatchOptionsSchema,
+  AnalyticsSubscriberDescriptorSchema
+};

package/schemas/models/analytics/envelope.model.js

@@ -0,0 +1,38 @@
+import * as z from "zod";
+import { PersonalizationProfileIdentifierSchema } from "../identifiers.model.js";
+import { IdentitySchema } from "../identity.model.js";
+import { CurrencySchema } from "../currency.model.js";
+import { AnalyticsConsentSchema } from "./consent.model.js";
+import { OriginSchema } from "./origin.model.js";
+const AnalyticsPageSchema = z.looseObject({
+  url: z.string().optional(),
+  title: z.string().optional(),
+  referrer: z.string().optional()
+});
+const EventContextSnapshotSchema = z.looseObject({
+  marketingIdentifier: PersonalizationProfileIdentifierSchema.meta({ description: "The marketing (CDP) identifier of the visitor at emit time." }),
+  identity: IdentitySchema.meta({ description: "The identity of the visitor at emit time. Anonymous when not logged in." }),
+  locale: z.string(),
+  currency: CurrencySchema,
+  consent: AnalyticsConsentSchema.optional().meta({ description: "Consent at emit time. Absent when the request carried none and no default applied." }),
+  page: AnalyticsPageSchema.optional(),
+  userAgent: z.string().optional().meta({ description: "The user agent of the visitor's request, if known. Delivery happens after the request, so subscribers cannot read it from the request context later." }),
+  clientIp: z.string().optional().meta({ description: "The IP address of the visitor's request, if known. Personal data: capturing it does not forward it, each subscriber decides what to send to its vendor." }),
+  isBot: z.boolean().optional().meta({ description: "True if the request was identified as a bot or crawler." })
+});
+const AnalyticsEventEnvelopeSchema = z.looseObject({
+  id: z.string().meta({ description: "Unique event id (UUID). Used for deduplication by vendors and for debugging." }),
+  occurredAt: z.iso.datetime().meta({ description: "ISO timestamp taken when the storefront emitted the event." }),
+  origin: OriginSchema.optional(),
+  properties: z.record(z.string(), z.unknown()).optional().meta({ description: "Storefront-only knowledge. Not a channel for product data; providers look that up." }),
+  context: EventContextSnapshotSchema
+});
+const AnalyticsEventResultSchema = z.looseObject({
+  eventId: z.string().meta({ description: "The id assigned to the enqueued event." })
+});
+export {
+  AnalyticsEventEnvelopeSchema,
+  AnalyticsEventResultSchema,
+  AnalyticsPageSchema,
+  EventContextSnapshotSchema
+};

package/schemas/models/analytics/event-parts.model.js

@@ -0,0 +1,47 @@
+import * as z from "zod";
+import { CategorySchema } from "../category.model.js";
+import {
+  CategoryIdentifierSchema,
+  ProductIdentifierSchema,
+  ProductRecommendationIdentifierSchema,
+  StoreIdentifierSchema
+} from "../identifiers.model.js";
+import { ProductSchema } from "../product.model.js";
+import { StoreSchema } from "../store.model.js";
+const PageTypeSchema = z.enum(["home", "category", "search", "pdp", "cart", "checkout", "content", "account", "other"]).meta({ description: "The kind of page that was viewed." });
+const AnalyticsPageViewSchema = z.looseObject({
+  type: PageTypeSchema,
+  url: z.string().optional(),
+  title: z.string().optional()
+});
+const AnalyticsPromotionSchema = z.looseObject({
+  id: z.string().meta({ description: "The promotion id." }),
+  name: z.string(),
+  slot: z.string().meta({ description: 'The placement of the promotion, e.g. "hero".' }),
+  creative: z.string().optional().meta({ description: "The creative shown, if the storefront distinguishes creatives." })
+});
+const AnalyticsCarouselSchema = z.looseObject({
+  recommendationId: ProductRecommendationIdentifierSchema.optional().meta({ description: "The recommendation the carousel was built from, if any." }),
+  carouselName: z.string().meta({ description: "Storefront name of the carousel." })
+});
+const AnalyticsAutocompleteSuggestionSchema = z.discriminatedUnion("type", [
+  z.looseObject({ type: z.literal("term"), term: z.string() }),
+  z.looseObject({ type: z.literal("product"), product: ProductIdentifierSchema })
+]);
+const AnalyticsProductRefSchema = z.union([ProductIdentifierSchema, ProductSchema]);
+const AnalyticsCategoryRefSchema = z.union([CategoryIdentifierSchema, CategorySchema]);
+const AnalyticsStoreRefSchema = z.union([StoreIdentifierSchema, StoreSchema]);
+const AnalyticsCouponRejectionReasonSchema = z.string().meta({ description: "Why the coupon was rejected, as reported by the backend or storefront." });
+const AnalyticsChannelSchema = z.string().meta({ description: 'A channel, e.g. "email" for newsletters or "facebook" for sharing.' });
+export {
+  AnalyticsAutocompleteSuggestionSchema,
+  AnalyticsCarouselSchema,
+  AnalyticsCategoryRefSchema,
+  AnalyticsChannelSchema,
+  AnalyticsCouponRejectionReasonSchema,
+  AnalyticsPageViewSchema,
+  AnalyticsProductRefSchema,
+  AnalyticsPromotionSchema,
+  AnalyticsStoreRefSchema,
+  PageTypeSchema
+};