@ekomerc/storefront 0.1.0 → 0.1.3

package/dist/README.md

@@ -0,0 +1,679 @@
+# @ekomerc/storefront
+
+TypeScript SDK for building headless storefronts with ekomerc. Provides typed helpers for products, collections, cart, and checkout operations.
+
+## Installation
+
+```bash
+pnpm add @ekomerc/storefront
+# or
+npm install @ekomerc/storefront
+```
+
+## Quick Start
+
+```typescript
+import { createStorefrontClient } from "@ekomerc/storefront";
+
+const client = createStorefrontClient({
+  endpoint: "https://api.yourstore.com/graphql",
+  apiKey: "sfk_your_api_key",
+});
+
+// Fetch products
+const result = await client.products.list({ first: 10, filter: { search: "shirt" } });
+if (result.isOk()) {
+  console.log(result.value.items);
+}
+
+// Add to cart (variantId is the GID from product queries, e.g. variant.id)
+await client.cart.create();
+const addResult = await client.cart.addItem(variant.id, 1);
+if (addResult.isOk()) {
+  console.log("Added to cart:", addResult.value);
+}
+```
+
+## Configuration
+
+```typescript
+interface StorefrontClientConfig {
+  endpoint: string;           // Full Storefront GraphQL URL (absolute)
+  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.
+
+```typescript
+const client = createStorefrontClient({
+  endpoint: "https://edge.example.com/custom/storefront/v1/graphql",
+  apiKey: "sfk_test_placeholder",
+});
+```
+
+Supported examples:
+- `https://api.example.com/graphql`
+- `https://edge.example.com/custom/storefront/v1/graphql`
+- `https://staging.example.net/gql/storefront`
+
+### Auth And Request Headers
+
+For each request the SDK sends:
+- `content-type: application/json`
+- `x-storefront-key: <apiKey>` (always)
+- `x-cart-token: <cartToken>` (when cart token exists)
+- `authorization: Bearer <customerToken>` (when customer token exists)
+
+### Storage Adapters
+
+The SDK stores the cart token to persist the cart across page loads.
+
+```typescript
+import {
+  createStorefrontClient,
+  createLocalStorageAdapter,  // Browser localStorage
+  createMemoryAdapter,        // In-memory (SSR/testing)
+  createDefaultAdapter,       // Auto-detects environment
+} from "@ekomerc/storefront";
+
+// Browser (default)
+const client = createStorefrontClient({
+  endpoint: "https://api.yourstore.com/graphql",
+  apiKey: "sfk_...",
+  // Uses localStorage by default in browser
+});
+
+// SSR / Server-side
+const client = createStorefrontClient({
+  endpoint: "https://api.yourstore.com/graphql",
+  apiKey: "sfk_...",
+  storage: createMemoryAdapter(),
+});
+
+// Custom storage
+const client = createStorefrontClient({
+  endpoint: "https://api.yourstore.com/graphql",
+  apiKey: "sfk_...",
+  storage: {
+    get: (key) => sessionStorage.getItem(key),
+    set: (key, value) => sessionStorage.setItem(key, value),
+    remove: (key) => sessionStorage.removeItem(key),
+  },
+});
+```
+
+## API Reference
+
+All methods return `Promise<Result<T, StorefrontError>>` from [neverthrow](https://github.com/supermacro/neverthrow).
+
+### Products
+
+```typescript
+// List products with pagination
+const result = await client.products.list({
+  first: 10,      // Number of products (default: 20)
+  after: cursor,  // Pagination cursor
+  filter: { search: "shirt" }, // Search query
+  sort: "BEST_SELLING"
+});
+// Returns: { items: Product[], pageInfo: PageInfo }
+
+// Get single product by handle or GID
+const result = await client.products.get("blue-shirt");
+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
+// List collections
+const result = await client.collections.list({
+  first: 10,
+  after: cursor,
+  search: "summer"
+});
+// Returns: { items: Collection[], pageInfo: PageInfo }
+
+// Get single collection
+const result = await client.collections.get("summer-collection");
+
+// Get products in a collection
+const result = await client.collections.getProducts("summer-collection", {
+  first: 20,
+  after: cursor,
+});
+// Returns: { items: Product[], pageInfo: PageInfo }
+```
+
+### Cart
+
+```typescript
+// Get current cart (from stored token)
+const result = await client.cart.get();
+// Returns: Cart | null
+
+// Create new cart
+const result = await client.cart.create();
+// Returns: Cart
+
+// Add item to cart
+// 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 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 GID (global ID) — use variant.id from product queries
+const result = await client.cart.removeItem(variantId);
+// Returns: Cart
+
+// Clear all items
+const result = await client.cart.clear();
+// Returns: Cart
+
+// Apply a promo code
+const result = await client.cart.applyPromoCode("SAVE10");
+if (result.isErr()) {
+  // ValidationError with reason (e.g. "Invalid or expired code")
+}
+// Returns: Cart (with appliedPromoCode populated)
+
+// Remove applied promo code
+const result = await client.cart.removePromoCode();
+// Returns: Cart (with appliedPromoCode cleared)
+```
+
+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
+
+Product variants include sale and quantity pricing information:
+
+```typescript
+const result = await client.products.get("my-product");
+if (result.isOk()) {
+  const variant = result.value.variants[0];
+
+  // Sale price detection
+  if (variant.isOnSale) {
+    console.log(`Was: ${variant.compareAtPrice}, Now: ${variant.price}`);
+  }
+
+  // Quantity tier pricing
+  for (const tier of variant.quantityPricing) {
+    console.log(`Buy ${tier.minQuantity}+ at ${tier.price}/unit`);
+  }
+}
+```
+
+Cart items expose the resolved effective unit price (considering sale + quantity tier):
+
+```typescript
+const cart = (await client.cart.get()).unwrapOr(null);
+if (cart) {
+  for (const item of cart.items) {
+    console.log(`Base price: ${item.price.amount}`);
+    console.log(`Effective price: ${item.effectiveUnitPrice.amount}`);
+    console.log(`Line total: ${item.totalPrice.amount}`);
+  }
+
+  // Discount information
+  console.log(`Discount: ${cart.discountTotal.amount}`);
+  if (cart.appliedPromoCode) {
+    console.log(`Promo: ${cart.appliedPromoCode.code} (-${cart.appliedPromoCode.discountAmount})`);
+  }
+  for (const discount of cart.appliedDiscounts) {
+    console.log(`${discount.description}: -${discount.discountAmount}`);
+  }
+}
+```
+
+### Checkout
+
+```typescript
+// Start checkout (transitions cart to checkout state)
+const result = await client.checkout.start();
+// Returns: Cart (with status: "checkout")
+
+// Update checkout info
+const result = await client.checkout.update({
+  email: "customer@example.com",
+  phone: "+381...",
+  shippingAddress: {
+    firstName: "John",
+    lastName: "Doe",
+    address1: "123 Main St",
+    city: "Belgrade",
+    country: "Serbia",
+    countryCode: "RS",
+    zip: "11000",
+  },
+  billingAddress: { ... },
+  notes: "Leave at door",
+  emailMarketingConsent: true,
+});
+// Returns: Cart
+
+// Complete checkout (creates order)
+const result = await client.checkout.complete();
+// Returns: Order
+
+// Abandon checkout (returns cart to active state)
+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
+// Clear the query cache
+client.cache.clear();
+```
+
+### Cart Token Management
+
+```typescript
+// Get current cart token
+const token = client.getCartToken();
+
+// Set cart token manually
+client.setCartToken("cart-token-uuid");
+
+// Clear cart token
+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:
+
+```typescript
+import {
+  StorefrontError,  // Base error class
+  NetworkError,     // Network/fetch failures
+  AuthError,        // Invalid/revoked API key
+  ValidationError,  // Validation errors from mutations
+  NotFoundError,    // Resource not found
+  StateError,       // Invalid cart state transition
+  GraphQLError,     // Unexpected GraphQL errors
+} from "@ekomerc/storefront";
+
+const result = await client.products.get("nonexistent");
+
+if (result.isErr()) {
+  const error = result.error;
+
+  if (error instanceof NotFoundError) {
+    console.log("Product not found");
+  } else if (error instanceof AuthError) {
+    console.log("Invalid API key");
+  } else if (error instanceof StateError) {
+    console.log(`Cart state error: ${error.state}`);
+  } else if (error instanceof ValidationError) {
+    console.log("Validation errors:", error.userErrors);
+  }
+}
+
+// Or use pattern matching
+result.match(
+  (product) => console.log("Found:", product.title),
+  (error) => console.error("Error:", error.message)
+);
+```
+
+### Troubleshooting Endpoint/Auth Issues
+
+1. `AuthError` (`401`/`403`)
+`x-storefront-key` is missing, invalid, revoked, or scoped for a different store. Rotate/regenerate the key and verify the exact value loaded in your runtime env.
+
+2. Browser CORS failure
+If browser console shows CORS errors, your API origin must allow your storefront origin and headers:
+`content-type, x-storefront-key, x-cart-token, authorization`.
+
+3. Malformed endpoint URL
+Always use a full absolute URL like `https://api.example.com/storefront`. The SDK does not validate the URL at initialization — requests will fail at runtime if the endpoint is malformed.
+
+### Cart State Errors
+
+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
+const result = await client.cart.addItem(variantId, 1);
+
+if (result.isErr() && result.error instanceof StateError) {
+  console.log(`Cannot modify cart: ${result.error.message}`);
+}
+```
+
+## Types
+
+All types are exported for TypeScript users:
+
+```typescript
+import type {
+  // Client
+  StorefrontClient,
+  StorefrontClientConfig,
+  StorageAdapter,
+
+  // Products
+  Product,
+  ProductVariant,
+  ProductOption,
+  ProductImage,
+  QuantityPricingTier,
+  DetailSection,
+  RichTextDetailSection,
+  BulletListDetailSection,
+  TableDetailSection,
+  DisplayIntent,
+
+  // Collections
+  Collection,
+
+  // Cart
+  Cart,
+  CartItem,
+  CartStatus,
+  AppliedPromoCode,
+  AppliedDiscount,
+
+  // Checkout
+  CheckoutData,
+  Address,
+  Order,
+
+  // Pagination
+  PageInfo,
+  PaginatedResult,
+
+  // Common
+  Store,
+  BrowserTrackingConfig,
+  GtmBrowserTrackingConfig,
+
+  // Tracking runtime
+  StorefrontTrackingRuntimeConfig,
+  AnalyticsBrowserAdapter,
+  AnalyticsConsentState,
+  AnalyticsDispatchOnUnknownConsent,
+  AnalyticsDiagnostic,
+  AnalyticsContext,
+  AnalyticsIngestResponse,
+
+  // Browser adapter types
+  GtmBrowserAdapterOptions,
+  GtmDataLayerEvent,
+  GtmConsentModeUpdate,
+} from "@ekomerc/storefront";
+```
+
+## SSR / Server-Side Rendering
+
+For SSR frameworks (Next.js, Remix, etc.), use the memory adapter on the server:
+
+```typescript
+import {
+  createStorefrontClient,
+  createMemoryAdapter,
+  createLocalStorageAdapter,
+} from "@ekomerc/storefront";
+
+const client = createStorefrontClient({
+  endpoint: process.env.STOREFRONT_API_URL,
+  apiKey: process.env.STOREFRONT_API_KEY,
+  storage: typeof window === "undefined"
+    ? createMemoryAdapter()
+    : createLocalStorageAdapter(),
+});
+```
+
+## React Integration
+
+For React applications, use the `@ekomerc/storefront-react` package which provides hooks and context:
+
+```typescript
+import { StorefrontProvider, useProducts, useCart } from "@ekomerc/storefront-react";
+
+function App() {
+  return (
+    <StorefrontProvider client={client}>
+      <Shop />
+    </StorefrontProvider>
+  );
+}
+
+function Shop() {
+  const { products, loading, error } = useProducts();
+  const { cart, addItem } = useCart();
+  // ...
+}
+```
+
+See the `@ekomerc/storefront-react` package for full documentation.
+
+## License
+
+MIT