@ekomerc/storefront 0.1.0 → 0.1.2

package/README.md

@@ -42,9 +42,89 @@ interface StorefrontClientConfig {
   apiKey: string;             // API key (sfk_...)
   storage?: StorageAdapter;   // Cart token storage (default: auto-detect)
   cacheTTL?: number;          // Query cache TTL in ms (default: 5 minutes)
+  trackingAttributionTTL?: number; // Landing attribution TTL in ms (default: 30 days)
+  tracking?: StorefrontTrackingRuntimeConfig; // Unified tracking runtime config
 }
 ```
 
+### Tracking Runtime Configuration
+
+`tracking` wires up the unified tracking runtime — consent signaling, GTM adapter dispatch, and optional diagnostics.
+
+```typescript
+interface StorefrontTrackingRuntimeConfig {
+  // Controls whether browser adapters may dispatch when consent is "unknown".
+  // Defaults to true when not set.
+  dispatchOnUnknownConsent?: boolean;
+
+  // Called before every event to get the current consent state.
+  // Return "granted", "denied", or "unknown". Defaults to "unknown".
+  resolveConsentState?: () => AnalyticsConsentState | Promise<AnalyticsConsentState>;
+
+  // Browser adapters to forward events to (GTM-only supported path in v1).
+  adapters?: AnalyticsBrowserAdapter[];
+
+  // Optional diagnostic observer — called after every ingest/adapter/consent operation.
+  // Never throws; errors inside are swallowed.
+  onDiagnostic?: (diagnostic: AnalyticsDiagnostic) => void;
+}
+```
+
+**Consent states:** `"granted"` | `"denied"` | `"unknown"`
+
+- `dispatchOnUnknownConsent: false`: events forwarded only when consent is `"granted"`.
+- `dispatchOnUnknownConsent: true` (default): events forwarded unless consent is `"denied"`.
+
+Example with a consent management platform:
+
+```typescript
+const client = createStorefrontClient({
+  endpoint: "https://api.yourstore.com/graphql",
+  apiKey: "sfk_...",
+});
+
+await client.init({
+  analytics: {
+    dispatchOnUnknownConsent: true,
+    resolveConsentState: () => myCmp.getConsentState(), // "granted" | "denied" | "unknown"
+    adapters: [gtmAdapter].filter(Boolean),
+    onDiagnostic: (d) => console.debug("[tracking]", d),
+  },
+});
+```
+
+The SDK persists landing attribution (`utm_*`, `gclid`, `gbraid`, `wbraid`, `fbclid`, `ttclid`) in `localStorage` under `ekomerc_tracking_attribution` and expires it on read. Fresh URL params always overwrite the stored snapshot.
+
+Call `client.init()` once on storefront bootstrap. It loads the store analytics config from the storefront API, captures landing attribution, and removes known attribution params from the address bar by default after capture. If you need to keep them in the URL, pass:
+
+```typescript
+await client.init({
+  analytics: {
+    stripUrl: false,
+  },
+});
+```
+
+### GTM-First Browser Model (v1)
+
+- SDK remains the single browser event producer.
+- First-party ingest (`/analytics/ingest`) remains authoritative for Ekomerc analytics/audit.
+- Browser-side vendor routing is GTM-only in this phase.
+- Backend provider forwarding is env-gated and defaults to disabled (`TRACKING_PROVIDER_FORWARDING_ENABLED=false`).
+- Hosted/default storefront GTM support is deferred (follow-up TODO).
+
+Custom storefront setup in this phase:
+
+1. Install the GTM snippet in storefront code (merchant-owned, outside SDK).
+2. Import `packages/sdk/storefront/src/gtm-recipes/ekomerc-gtm-browser-recipe-v1.export-v2.json` into GTM.
+3. Fill provider IDs/settings in GTM and publish manually.
+
+Anti-duplication checklist (required):
+
+1. Disable GA4 Enhanced Measurement in the GA4 data stream used by this GTM setup.
+2. Disable Meta Automatic Event Setup in Meta Events Manager for the pixel used by this setup.
+3. Disable TikTok automatic event setup or equivalent automatic browser-event features for this setup.
+
 ### Custom Endpoint URLs
 
 `endpoint` is used exactly as provided. The SDK sends `POST` requests directly to that URL and does not rewrite hosts or paths.
@@ -123,15 +203,31 @@ const result = await client.products.list({
 });
 // Returns: { items: Product[], pageInfo: PageInfo }
 
-// Get single product by handle or ID
+// Get single product by handle or GID
 const result = await client.products.get("blue-shirt");
-const result = await client.products.get("UHJvZHVjdDoxMjM="); // Global ID
+const result = await client.products.get("UHJvZHVjdDoxMjM="); // GID (global ID)
 
 // Batch fetch by handles
 const result = await client.products.getByHandles(["shirt-1", "shirt-2"]);
 // Returns: (Product | null)[]
 ```
 
+Each `Product` includes a `detailSections: DetailSection[]` field containing structured sections for use in product detail pages. Each section has a `sectionType` (`"RICH_TEXT"` | `"BULLET_LIST"` | `"TABLE"`), `displayIntent` (`"ACCORDION"` | `"SPECIFICATIONS"` | `"BOTH"`), `title`, `position`, and type-specific `content`.
+
+```typescript
+if (result.isOk()) {
+  for (const section of result.value.detailSections) {
+    if (section.sectionType === "RICH_TEXT") {
+      console.log(section.content.html);
+    } else if (section.sectionType === "BULLET_LIST") {
+      console.log(section.content.items);
+    } else if (section.sectionType === "TABLE") {
+      console.log(section.content.rows); // [string, string][]
+    }
+  }
+}
+```
+
 ### Collections
 
 ```typescript
@@ -166,17 +262,17 @@ const result = await client.cart.create();
 // Returns: Cart
 
 // Add item to cart
-// variantId must be a Global ID (GID) — use variant.id from product queries
+// variantId must be a GID (global ID) — use variant.id from product queries
 const result = await client.cart.addItem(variantId, quantity);
 // Returns: Cart
 
 // Update item quantity
-// variantId must be a Global ID (GID) — use variant.id from product queries
+// variantId must be a GID (global ID) — use variant.id from product queries
 const result = await client.cart.updateItem(variantId, newQuantity);
 // Returns: Cart
 
 // Remove item from cart
-// variantId must be a Global ID (GID) — use variant.id from product queries
+// variantId must be a GID (global ID) — use variant.id from product queries
 const result = await client.cart.removeItem(variantId);
 // Returns: Cart
 
@@ -196,7 +292,7 @@ const result = await client.cart.removePromoCode();
 // Returns: Cart (with appliedPromoCode cleared)
 ```
 
-Note: `variantId` in `cart.addItem`, `cart.updateItem`, and `cart.removeItem` must be a GraphQL Global ID (GID), not a raw UUID. Use variant IDs returned by product queries.
+Note: `variantId` in `cart.addItem`, `cart.updateItem`, and `cart.removeItem` must be a GID (global ID), not a raw UUID. Use variant IDs returned by product queries.
 
 ### Pricing Display
 
@@ -276,6 +372,44 @@ const result = await client.checkout.abandon();
 // Returns: Cart
 ```
 
+### Analytics
+
+`client.analytics.track()` sends a first-party event to the storefront ingest endpoint and, when GTM adapter is configured, mirrors supported events to GTM `dataLayer`.
+
+```typescript
+// Page view
+await client.analytics.track("page_view");
+
+// Product view (productId can be a raw UUID, GID, or base64-encoded GID)
+await client.analytics.track("product_view", { productId: product.id, variantId: variant.id });
+
+// Collection view
+await client.analytics.track("collection_view", { collectionId: collection.id });
+
+// Search
+await client.analytics.track("search_performed", { query: "shirt", resultsCount: 42 });
+
+// Cart events
+await client.analytics.track("add_to_cart", { cartId: cart.id, quantity: 1, itemsCount: 3, cartValue: 29.99 });
+await client.analytics.track("remove_from_cart", { cartId: cart.id, quantity: 1, itemsCount: 2, cartValue: 19.99 });
+
+// Checkout funnel
+await client.analytics.track("checkout_started", { cartId: cart.id });
+await client.analytics.track("checkout_step_completed", { cartId: cart.id, step: "contact" }); // "contact" | "shipping" | "payment" | "review"
+await client.analytics.track("checkout_completed", { orderId: order.id, cartId: cart.id, orderTotal: 49.99 });
+
+// Custom event — sent as analytics.custom with eventName in properties
+await client.analytics.track("homepage.banner_clicked", { position: 0 });
+```
+
+All preset events also accept an optional `AnalyticsContext` as the last argument to override path, referrer, UTM params, consent state, or visitor/session IDs.
+
+Important purchase behavior:
+
+- `track("checkout_completed", ...)` is ingest-only.
+- Browser purchase event (`ekomerc.purchase`) is emitted only on successful `checkout.complete()` using server-confirmed `purchaseTracking`.
+- `checkout.complete()` API remains `Result<Order, StorefrontError>` (non-breaking).
+
 ### Cache
 
 ```typescript
@@ -296,6 +430,81 @@ client.setCartToken("cart-token-uuid");
 client.clearCartToken();
 ```
 
+### Store
+
+```typescript
+const result = await client.store.get();
+if (result.isOk()) {
+  const store = result.value;
+  // store.analytics — derived analytics availability and GTM config for this store
+  console.log(store.analytics);
+  // {
+  //   enabled: true,
+  //   dispatchOnUnknownConsent: true,
+  //   gtm: { enabled: true, containerId: "GTM-XXXXXX" },
+  // }
+}
+```
+
+Use `store.analytics` to decide whether GTM forwarding should be active at runtime:
+
+```typescript
+import {
+  createGtmBrowserAdapter,
+} from "@ekomerc/storefront";
+
+const storeResult = await client.store.get();
+if (storeResult.isOk()) {
+  const { analytics } = storeResult.value;
+  const adapters = [
+    createGtmBrowserAdapter(analytics.gtm),
+  ].filter(Boolean);
+
+  console.log(adapters, analytics.dispatchOnUnknownConsent);
+}
+```
+
+## Browser Adapters
+
+GTM is the supported first-party browser adapter in this phase. The adapter returns `null` when GTM is disabled or container ID is missing.
+
+### GTM (`createGtmBrowserAdapter`)
+
+Pushes namespaced Ekomerc events to `window.dataLayer` (`ekomerc.*`) and updates GTM Consent Mode via `gtag("consent", "update", ...)`.
+
+```typescript
+import { createGtmBrowserAdapter } from "@ekomerc/storefront";
+
+const gtmAdapter = createGtmBrowserAdapter(
+  store.browserTrackingConfig.gtm,  // { enabled, containerId }
+  { dataLayerName: "dataLayer" },   // optional — defaults to "dataLayer"
+);
+// Returns null if disabled or containerId is missing
+```
+
+GTM mapping example: `page_view` -> `ekomerc.page_view`, `product_view` -> `ekomerc.view_item`, `add_to_cart` -> `ekomerc.add_to_cart`, `checkout_started` -> `ekomerc.begin_checkout`, `search_performed` -> `ekomerc.search`.
+`checkout_step_completed` and `analytics.custom` remain ingest-only in this phase.
+
+### Custom Adapters
+
+Implement `AnalyticsBrowserAdapter` to add your own integration:
+
+```typescript
+import type { AnalyticsBrowserAdapter } from "@ekomerc/storefront";
+
+const myAdapter: AnalyticsBrowserAdapter = {
+  provider: "gtm", // reuse an existing provider key
+  dispatch({ event, consent }) {
+    if (event.eventType === "analytics.page_view") {
+      myAnalytics.page(event.context.path);
+    }
+  },
+  updateConsent(consent) {
+    myAnalytics.setConsent(consent.consentState === "granted");
+  },
+};
+```
+
 ## Error Handling
 
 The SDK uses Result types for error handling. Errors are typed and categorized:
@@ -348,15 +557,13 @@ Always use a full absolute URL like `https://api.example.com/storefront`. The SD
 
 ### Cart State Errors
 
-Cart operations are only allowed when the cart is in `active` state. Attempting to modify a cart in `checkout`, `converted`, `abandoned`, or `expired` state returns a `StateError`:
+Cart mutations (add/update/remove/clear) work on `active` carts. If the cart is in `checkout` state, the backend automatically reactivates it (releases reservations, reverts to `active`) before applying the mutation. This does not mark the cart as abandoned. Attempting to modify a `converted` or `expired` cart returns a `StateError`:
 
 ```typescript
-// Cart is in checkout state
 const result = await client.cart.addItem(variantId, 1);
 
 if (result.isErr() && result.error instanceof StateError) {
   console.log(`Cannot modify cart: ${result.error.message}`);
-  // "Cannot modify cart in 'checkout' state. Cart operations are only allowed when cart is in 'active' state."
 }
 ```
 
@@ -377,6 +584,11 @@ import type {
   ProductOption,
   ProductImage,
   QuantityPricingTier,
+  DetailSection,
+  RichTextDetailSection,
+  BulletListDetailSection,
+  TableDetailSection,
+  DisplayIntent,
 
   // Collections
   Collection,
@@ -398,8 +610,23 @@ import type {
   PaginatedResult,
 
   // Common
-  Money,
   Store,
+  BrowserTrackingConfig,
+  GtmBrowserTrackingConfig,
+
+  // Tracking runtime
+  StorefrontTrackingRuntimeConfig,
+  AnalyticsBrowserAdapter,
+  AnalyticsConsentState,
+  AnalyticsDispatchOnUnknownConsent,
+  AnalyticsDiagnostic,
+  AnalyticsContext,
+  AnalyticsIngestResponse,
+
+  // Browser adapter types
+  GtmBrowserAdapterOptions,
+  GtmDataLayerEvent,
+  GtmConsentModeUpdate,
 } from "@ekomerc/storefront";
 ```