@ekomerc/storefront 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,16 +1,55 @@
+import { GtmStandardEventName } from '@ekomerc/tracking-policy';
 import { Result } from 'neverthrow';
+import { TrackingPolicyEventType } from '@ekomerc/tracking-policy';
+import { TrackingProvider } from '@ekomerc/tracking-policy';
 
 export declare interface AccountOperations {
+    /**
+     * Fetch paginated orders for the authenticated customer.
+     *
+     * @param args - Forward or backward pagination options.
+     * @returns Paginated customer orders.
+     */
     orders(args?: {
         first?: number;
         after?: string;
         last?: number;
         before?: string;
     }): Promise<Result<PaginatedResult<CustomerOrder>, StorefrontError>>;
+    /**
+     * Fetch saved addresses for the authenticated customer.
+     *
+     * @returns Customer addresses.
+     */
     addresses(): Promise<Result<CustomerAddress[], StorefrontError>>;
+    /**
+     * Create a saved customer address.
+     *
+     * @param input - Address fields to create.
+     * @returns The created address.
+     */
     createAddress(input: CustomerAddressInput): Promise<Result<CustomerAddress, StorefrontError>>;
+    /**
+     * Update a saved customer address.
+     *
+     * @param addressId - Address identifier to update.
+     * @param input - Address fields to change.
+     * @returns The updated address.
+     */
     updateAddress(addressId: string, input: CustomerAddressUpdateInput): Promise<Result<CustomerAddress, StorefrontError>>;
+    /**
+     * Delete a saved customer address.
+     *
+     * @param addressId - Address identifier to delete.
+     * @returns The deleted address identifier.
+     */
     deleteAddress(addressId: string): Promise<Result<string, StorefrontError>>;
+    /**
+     * Update the authenticated customer's profile fields.
+     *
+     * @param input - Customer fields to update.
+     * @returns The updated customer profile.
+     */
     update(input: CustomerUpdateInput): Promise<Result<Customer, StorefrontError>>;
 }
 
@@ -18,8 +57,8 @@ export declare interface Address {
     firstName: string | null;
     lastName: string | null;
     company: string | null;
-    address1: string;
-    address2: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
     city: string;
     province: string | null;
     provinceCode: string | null;
@@ -29,7 +68,76 @@ export declare interface Address {
     phone: string | null;
 }
 
-declare interface AnalyticsClickIds {
+/**
+ * Input provided to a browser adapter when dispatching an analytics event.
+ */
+export declare interface AnalyticsAdapterDispatchInput {
+    event: AnalyticsBrowserEvent;
+    consent: AnalyticsConsentUpdate;
+}
+
+/**
+ * Result returned by browser adapter dispatch and consent-update hooks.
+ */
+export declare type AnalyticsAdapterOperationResult = void | {
+    status: "success";
+} | AnalyticsAdapterOperationSkippedResult;
+
+/**
+ * Structured result returned when a browser adapter intentionally skips dispatch.
+ */
+export declare interface AnalyticsAdapterOperationSkippedResult {
+    status: "skipped";
+    reason: "runtime_unavailable";
+}
+
+/**
+ * Reasons a browser adapter may skip dispatch instead of throwing.
+ */
+export declare type AnalyticsAdapterSkipReason = "unsupported_event" | "consent_blocked" | "runtime_unavailable";
+
+/**
+ * Browser-side analytics adapter contract for GTM, Meta, TikTok, or custom integrations.
+ */
+export declare interface AnalyticsBrowserAdapter {
+    provider: TrackingProvider;
+    dispatch(input: AnalyticsAdapterDispatchInput): AnalyticsAdapterOperationResult | Promise<AnalyticsAdapterOperationResult>;
+    updateConsent?(input: AnalyticsConsentUpdate): AnalyticsAdapterOperationResult | Promise<AnalyticsAdapterOperationResult>;
+}
+
+/**
+ * Canonical browser analytics event shape used by the storefront SDK.
+ */
+export declare interface AnalyticsBrowserEvent {
+    schemaVersion: 1;
+    eventId: string;
+    eventType: TrackingPolicyEventType;
+    occurredAt: string;
+    sessionId: string;
+    visitorId: string;
+    customerId: string | null;
+    consentState: AnalyticsConsentState;
+    context: AnalyticsEventContextPayload;
+    referrer: string | null;
+    utm: AnalyticsUtm;
+    clickIds: AnalyticsClickIds;
+    device: AnalyticsBrowserEventDevice;
+    properties: AnalyticsProperties;
+}
+
+/**
+ * Best-effort browser device fingerprint attached to an analytics event.
+ */
+export declare interface AnalyticsBrowserEventDevice {
+    deviceType: string;
+    deviceOs: string | null;
+    deviceBrowser: string | null;
+}
+
+/**
+ * Click identifiers captured from ad platforms and passed through analytics events.
+ */
+export declare interface AnalyticsClickIds {
     schemaVersion: 1;
     capturedAt: string | null;
     gclid: string | null;
@@ -39,13 +147,23 @@ declare interface AnalyticsClickIds {
     fbclid: string | null;
 }
 
-declare type AnalyticsConsentState = "granted" | "denied" | "unknown";
+/**
+ * Consent states emitted with browser-side analytics events.
+ */
+export declare type AnalyticsConsentState = "granted" | "denied" | "unknown";
+
+/**
+ * Consent state payload passed to browser adapters and diagnostics.
+ */
+export declare interface AnalyticsConsentUpdate {
+    consentState: AnalyticsConsentState;
+    dispatchOnUnknownConsent: AnalyticsDispatchOnUnknownConsent;
+}
 
 /**
  * Optional context overrides for a tracking call.
  */
 export declare interface AnalyticsContext {
-    storeSlug?: string;
     path?: string;
     referrer?: string | null;
     occurredAt?: Date | string;
@@ -64,6 +182,88 @@ export declare interface AnalyticsContext {
     deviceBrowser?: string | null;
 }
 
+/**
+ * Diagnostic events emitted by the analytics runtime for ingest and adapter activity.
+ */
+export declare type AnalyticsDiagnostic = {
+    target: "ingest";
+    status: "success";
+    event: AnalyticsBrowserEvent;
+    response: {
+        acceptedCount: number;
+        duplicateCount: number;
+        rejectedCount: number;
+    };
+} | {
+    target: "ingest";
+    status: "error";
+    event: AnalyticsBrowserEvent;
+    error: Error;
+} | {
+    target: "ingest";
+    status: "accepted_unknown";
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "queue";
+    status: "enqueued";
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "queue";
+    status: "flushed";
+    count: number;
+} | {
+    target: "queue";
+    status: "evicted_full";
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "queue";
+    status: "evicted_expired";
+    eventId: string;
+} | {
+    target: "adapter";
+    status: "success";
+    provider: TrackingProvider;
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "adapter";
+    status: "skipped";
+    provider: TrackingProvider;
+    event: AnalyticsBrowserEvent;
+    reason: AnalyticsAdapterSkipReason;
+} | {
+    target: "adapter";
+    status: "error";
+    provider: TrackingProvider;
+    event: AnalyticsBrowserEvent;
+    error: Error;
+} | {
+    target: "consent_bridge";
+    status: "success";
+    provider: TrackingProvider;
+    consent: AnalyticsConsentUpdate;
+} | {
+    target: "consent_bridge";
+    status: "skipped";
+    provider: TrackingProvider;
+    consent: AnalyticsConsentUpdate;
+    reason: "runtime_unavailable";
+} | {
+    target: "consent_bridge";
+    status: "error";
+    provider: TrackingProvider;
+    consent: AnalyticsConsentUpdate;
+    error: Error;
+} | {
+    target: "consent";
+    status: "error";
+    error: Error;
+};
+
+/**
+ * Runtime policies controlling how consent gates browser event dispatch.
+ */
+export declare type AnalyticsDispatchOnUnknownConsent = boolean;
+
 /**
  * Error detail for a single ingest payload item.
  */
@@ -86,10 +286,18 @@ export declare interface AnalyticsErrorItem {
     message: string;
 }
 
+/**
+ * Request context attached to each browser analytics event.
+ */
+export declare interface AnalyticsEventContextPayload {
+    schemaVersion: 1;
+    path: string;
+}
+
 /**
  * Canonical analytics event type values accepted by the storefront ingest endpoint.
  */
-export declare type AnalyticsEventType = "analytics.page_view" | "analytics.product_view" | "analytics.collection_view" | "analytics.search_performed" | "analytics.add_to_cart" | "analytics.remove_from_cart" | "analytics.checkout_started" | "analytics.checkout_step_completed" | "analytics.checkout_completed" | "analytics.custom";
+export declare type AnalyticsEventType = TrackingPolicyEventType;
 
 /**
  * Response summary from the analytics ingest endpoint.
@@ -113,13 +321,17 @@ export declare interface AnalyticsIngestResponse {
     errors: AnalyticsErrorItem[];
 }
 
+export declare interface AnalyticsInitOptions {
+    stripUrl?: boolean;
+}
+
 /**
- * Primitive value allowed in analytics custom event properties.
+ * Primitive JSON values supported inside analytics properties.
  */
 export declare type AnalyticsJsonPrimitive = string | number | boolean | null;
 
 /**
- * Recursive JSON value allowed in analytics custom event properties.
+ * Recursive JSON value shape supported by analytics event properties.
  */
 export declare type AnalyticsJsonValue = AnalyticsJsonPrimitive | AnalyticsJsonValue[] | {
     [key: string]: AnalyticsJsonValue;
@@ -186,7 +398,7 @@ export declare interface AnalyticsOperations {
 export declare type AnalyticsPresetEventName = "page_view" | "product_view" | "collection_view" | "search_performed" | "add_to_cart" | "remove_from_cart" | "checkout_started" | "checkout_step_completed" | "checkout_completed";
 
 /**
- * Generic analytics event property bag.
+ * Arbitrary analytics event properties sent to ingest and browser adapters.
  */
 export declare interface AnalyticsProperties {
     [key: string]: AnalyticsJsonValue;
@@ -197,7 +409,19 @@ export declare interface AnalyticsProperties {
  * Preset names (e.g. `product_view`) are normalized to `analytics.*` types.
  * Unknown names are sent as `analytics.custom` with `{ eventName: <name> }`.
  */
-export declare type AnalyticsTrackEventName = AnalyticsPresetEventName | AnalyticsEventType | string;
+export declare type AnalyticsTrackEventName = AnalyticsPresetEventName | AnalyticsEventType;
+
+/**
+ * UTM parameters captured for a visitor session.
+ */
+export declare interface AnalyticsUtm {
+    schemaVersion: 1;
+    source: string | null;
+    medium: string | null;
+    campaign: string | null;
+    term: string | null;
+    content: string | null;
+}
 
 export declare interface AppliedDiscount {
     promotionId: string;
@@ -225,6 +449,12 @@ export declare class AuthError extends StorefrontError {
 }
 
 export declare interface AuthOperations {
+    /**
+     * Register a customer account and store the returned auth token.
+     *
+     * @param input - Registration credentials and optional name.
+     * @returns The authenticated customer and token.
+     */
     register(input: {
         email: string;
         password: string;
@@ -233,6 +463,12 @@ export declare interface AuthOperations {
         customer: Customer;
         token: string;
     }, StorefrontError>>;
+    /**
+     * Log in an existing customer and store the returned auth token.
+     *
+     * @param input - Customer login credentials.
+     * @returns The authenticated customer and token.
+     */
     login(input: {
         email: string;
         password: string;
@@ -240,18 +476,49 @@ export declare interface AuthOperations {
         customer: Customer;
         token: string;
     }, StorefrontError>>;
+    /**
+     * Remove the stored customer auth token.
+     */
     logout(): void;
+    /**
+     * Request a password reset email for a customer account.
+     *
+     * @param email - Customer email address.
+     * @returns Reset request success state.
+     */
     requestPasswordReset(email: string): Promise<Result<{
         success: boolean;
     }, StorefrontError>>;
+    /**
+     * Reset a customer password with a reset token.
+     *
+     * @param input - Reset token and new password.
+     * @returns Reset success state.
+     */
     resetPassword(input: {
         token: string;
         newPassword: string;
     }): Promise<Result<{
         success: boolean;
     }, StorefrontError>>;
+    /**
+     * Verify a customer email address with a verification token.
+     *
+     * @param token - Verification token from email.
+     * @returns The verified customer.
+     */
     verifyEmail(token: string): Promise<Result<Customer, StorefrontError>>;
+    /**
+     * Fetch the currently authenticated customer.
+     *
+     * @returns The signed-in customer, or `null` when unauthenticated.
+     */
     me(): Promise<Result<Customer | null, StorefrontError>>;
+    /**
+     * Check whether a customer token is currently stored.
+     *
+     * @returns `true` when a customer session exists.
+     */
     isLoggedIn(): boolean;
 }
 
@@ -261,7 +528,34 @@ export declare interface AvailablePaymentMethod {
     additionalFee: number;
 }
 
+/**
+ * Browser-side tracking configuration returned by the storefront `store` query.
+ */
+export declare interface BrowserTrackingConfig {
+    gtm: GtmBrowserTrackingConfig;
+}
+
+/**
+ * Converts storefront consent state into a GTM consent-mode update payload.
+ */
+export declare function buildGtmConsentModeUpdate({ consentState }: AnalyticsConsentUpdate): GtmConsentModeUpdate;
+
+/**
+ * Maps a storefront analytics event to a GTM `dataLayer.push()` payload.
+ */
+export declare function buildGtmDataLayerEvent(input: AnalyticsAdapterDispatchInput): GtmDataLayerEvent | null;
+
+export declare interface BulletListDetailSection extends DetailSectionBase {
+    sectionType: "BULLET_LIST";
+    content: {
+        items: string[];
+    };
+}
+
 export declare interface CacheHelpers {
+    /**
+     * Clear all cached query results for this client instance.
+     */
     clear(): void;
 }
 
@@ -305,22 +599,91 @@ export declare interface CartItem {
 }
 
 export declare interface CartOperations {
+    /**
+     * Load the current cart from the stored cart token.
+     *
+     * @returns The current cart, or `null` when no cart exists.
+     */
     get(): Promise<Result<Cart | null, StorefrontError>>;
+    /**
+     * Create a new active cart and persist its token.
+     *
+     * @returns The newly created cart.
+     */
     create(): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Add a product variant to the active cart.
+     *
+     * @param variantId - Product variant GID (global ID).
+     * @param quantity - Quantity to add.
+     * @returns The updated cart.
+     */
     addItem(variantId: string, quantity: number): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Update the quantity of an existing cart item.
+     *
+     * @param variantId - Product variant GID (global ID).
+     * @param quantity - New quantity for the item.
+     * @returns The updated cart.
+     */
     updateItem(variantId: string, quantity: number): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Remove a product variant from the cart.
+     *
+     * @param variantId - Product variant GID (global ID).
+     * @returns The updated cart.
+     */
     removeItem(variantId: string): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Remove all items from the active cart.
+     *
+     * @returns The emptied cart.
+     */
     clear(): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Apply a promo code to the active cart.
+     *
+     * @param code - Promo code to validate and apply.
+     * @returns The updated cart with discount data.
+     */
     applyPromoCode(code: string): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Remove the currently applied promo code from the cart.
+     *
+     * @returns The updated cart.
+     */
     removePromoCode(): Promise<Result<Cart, StorefrontError>>;
 }
 
-export declare type CartStatus = "active" | "checkout" | "converted" | "abandoned" | "expired";
+export declare type CartStatus = "active" | "checkout" | "converted" | "expired";
 
 export declare interface CategoriesOperations {
+    /**
+     * Fetch the nested storefront category tree.
+     *
+     * @returns Categories with their child hierarchy.
+     */
     tree(): Promise<Result<Category[], StorefrontError>>;
+    /**
+     * Fetch categories flattened into a parent-aware list.
+     *
+     * @returns Flat categories with depth and parent metadata.
+     */
     flat(): Promise<Result<FlatCategory[], StorefrontError>>;
+    /**
+     * Fetch a single category by GID or handle.
+     *
+     * @param idOrHandle - Category GID or handle.
+     * @returns The matching category.
+     */
     get(idOrHandle: string): Promise<Result<Category, StorefrontError>>;
+    /**
+     * Fetch products assigned to a category.
+     *
+     * @param idOrHandle - Category GID or handle.
+     * @param options - Pagination and descendant-inclusion options.
+     * @returns Paginated products for the category.
+     */
     getProducts(idOrHandle: string, options?: CategoryProductsOptions): Promise<Result<PaginatedResult<Product>, StorefrontError>>;
 }
 
@@ -361,9 +724,30 @@ export declare interface CheckoutData {
 }
 
 export declare interface CheckoutOperations {
+    /**
+     * Start checkout for the current active cart.
+     *
+     * @returns The cart in checkout state.
+     */
     start(): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Update checkout customer, shipping, and payment details.
+     *
+     * @param data - Checkout fields to update.
+     * @returns The updated checkout cart.
+     */
     update(data: CheckoutData): Promise<Result<Cart, StorefrontError>>;
+    /**
+     * Complete checkout and convert the cart into an order.
+     *
+     * @returns The created order.
+     */
     complete(): Promise<Result<Order, StorefrontError>>;
+    /**
+     * Abandon checkout and return the cart to an active state.
+     *
+     * @returns The reactivated cart.
+     */
     abandon(): Promise<Result<Cart, StorefrontError>>;
 }
 
@@ -405,8 +789,27 @@ export declare interface CollectionsListOptions {
 }
 
 export declare interface CollectionsOperations {
+    /**
+     * List collections with cursor pagination and optional search.
+     *
+     * @param options - Pagination and search options.
+     * @returns Paginated storefront collections.
+     */
     list(options?: CollectionsListOptions): Promise<Result<PaginatedResult<Collection>, StorefrontError>>;
+    /**
+     * Fetch a single collection by GID or handle.
+     *
+     * @param idOrHandle - Collection GID or handle.
+     * @returns The matching collection.
+     */
     get(idOrHandle: string): Promise<Result<Collection, StorefrontError>>;
+    /**
+     * Fetch products that belong to a collection.
+     *
+     * @param idOrHandle - Collection GID or handle.
+     * @param options - Pagination and collection product options.
+     * @returns Paginated products for the collection.
+     */
     getProducts(idOrHandle: string, options?: CollectionProductsOptions): Promise<Result<PaginatedResult<Product>, StorefrontError>>;
 }
 
@@ -419,6 +822,11 @@ export declare type CollectionType = "manual" | "intelligent";
  */
 export declare function createDefaultAdapter(): StorageAdapter;
 
+/**
+ * Creates a GTM browser adapter that pushes storefront analytics events into `window.dataLayer`.
+ */
+export declare function createGtmBrowserAdapter(config: GtmBrowserTrackingConfig, options?: GtmBrowserAdapterOptions): AnalyticsBrowserAdapter | null;
+
 /**
  * localStorage adapter for browser environments
  */
@@ -477,7 +885,7 @@ export declare interface CustomerAddress {
     addressLine1: string;
     addressLine2: string | null;
     city: string;
-    postalCode: string | null;
+    zip: string | null;
     phone: string | null;
     isDefault: boolean;
     createdAt: string;
@@ -490,7 +898,7 @@ export declare interface CustomerAddressInput {
     addressLine1: string;
     addressLine2?: string;
     city: string;
-    postalCode?: string;
+    zip?: string;
     phone?: string;
     isDefault?: boolean;
 }
@@ -502,7 +910,7 @@ export declare interface CustomerAddressUpdateInput {
     addressLine1?: string;
     addressLine2?: string;
     city?: string;
-    postalCode?: string;
+    zip?: string;
     phone?: string;
     isDefault?: boolean;
 }
@@ -537,6 +945,17 @@ export declare interface CustomerUpdateInput {
     newPassword?: string;
 }
 
+export declare type DetailSection = RichTextDetailSection | BulletListDetailSection | TableDetailSection;
+
+declare interface DetailSectionBase {
+    id: string;
+    title: string;
+    displayIntent: DisplayIntent;
+    position: number;
+}
+
+export declare type DisplayIntent = "ACCORDION" | "SPECIFICATIONS" | "BOTH";
+
 /**
  * Extract userErrors from mutation result and convert to ValidationError if present
  */
@@ -598,6 +1017,101 @@ export declare interface GraphQLResponse<T = unknown> {
     }>;
 }
 
+/**
+ * GTM attribution payload copied from captured UTM and click ID data.
+ */
+export declare interface GtmAttributionPayload {
+    utm_source: string | null;
+    utm_medium: string | null;
+    utm_campaign: string | null;
+    utm_term: string | null;
+    utm_content: string | null;
+    gclid: string | null;
+    gbraid: string | null;
+    wbraid: string | null;
+    fbclid: string | null;
+    ttclid: string | null;
+}
+
+/**
+ * Optional runtime overrides for the GTM browser adapter.
+ */
+export declare interface GtmBrowserAdapterOptions {
+    dataLayerName?: string;
+    getWindow?: () => object | null;
+}
+
+/**
+ * Public GTM settings returned by the storefront `store` query.
+ */
+export declare interface GtmBrowserTrackingConfig {
+    enabled: boolean;
+    containerId: string | null;
+}
+
+/**
+ * GTM consent-mode update payload derived from storefront consent state.
+ */
+export declare interface GtmConsentModeUpdate {
+    analytics_storage: "granted" | "denied";
+    ad_storage: "granted" | "denied";
+    ad_user_data: "granted" | "denied";
+    ad_personalization: "granted" | "denied";
+}
+
+/**
+ * GTM page context payload copied from the storefront analytics event.
+ */
+export declare interface GtmContextPayload {
+    path: string;
+    referrer: string | null;
+}
+
+/**
+ * Full object pushed to the configured GTM data layer.
+ */
+export declare interface GtmDataLayerEvent {
+    event: GtmNamespacedEventName;
+    ekomerc: GtmEcommercePayload;
+}
+
+/**
+ * GTM `ekomerc` payload pushed alongside each `dataLayer` event.
+ */
+export declare interface GtmEcommercePayload {
+    event_name: GtmNamespacedEventName;
+    event_id: string;
+    consent_state: AnalyticsConsentState;
+    context: GtmContextPayload;
+    attribution: GtmAttributionPayload;
+    currency?: string;
+    value?: number;
+    order_id?: string;
+    cart_id?: string;
+    quantity?: number;
+    items_count?: number;
+    search_term?: string;
+    results_count?: number;
+    items?: GtmItem[];
+}
+
+/**
+ * GTM ecommerce item payload derived from storefront analytics properties.
+ */
+export declare interface GtmItem {
+    product_id: string;
+    variant_id?: string;
+    quantity: number;
+    unit_price: number;
+    line_total: number;
+    currency: string;
+}
+
+/**
+ * Namespaced GTM event names emitted by the storefront adapter.
+ */
+export declare type GtmNamespacedEventName = `ekomerc.${GtmStandardEventName}`;
+
 /**
  * Network error - fetch failed, connection issues
  */
@@ -662,11 +1176,16 @@ export declare interface PaymentInstructions {
 }
 
 export declare interface PaymentsOperations {
+    /**
+     * Fetch payment methods currently available for checkout.
+     *
+     * @returns Available storefront payment methods.
+     */
     getAvailableMethods(): Promise<Result<AvailablePaymentMethod[], StorefrontError>>;
 }
 
 declare type PresetEventProperties = {
-    page_view: {};
+    page_view: Record<string, never>;
     product_view: {
         productId: string;
         variantId?: string | null;
@@ -724,6 +1243,7 @@ export declare interface Product {
     categories: Category[];
     primaryCategory: Category | null;
     tags: Tag[];
+    detailSections: DetailSection[];
 }
 
 export declare interface ProductFilter {
@@ -769,8 +1289,26 @@ export declare interface ProductsListOptions {
 }
 
 export declare interface ProductsOperations {
+    /**
+     * List products with cursor pagination and optional filters.
+     *
+     * @param options - Pagination, search, and sort options.
+     * @returns Paginated storefront products.
+     */
     list(options?: ProductsListOptions): Promise<Result<PaginatedResult<Product>, StorefrontError>>;
+    /**
+     * Fetch a single product by GID or handle.
+     *
+     * @param idOrHandle - Product GID or handle.
+     * @returns The matching product.
+     */
     get(idOrHandle: string): Promise<Result<Product, StorefrontError>>;
+    /**
+     * Fetch multiple products by handle in request order.
+     *
+     * @param handles - Product handles to resolve.
+     * @returns Products for each requested handle, with `null` for missing entries.
+     */
     getByHandles(handles: string[]): Promise<Result<(Product | null)[], StorefrontError>>;
 }
 
@@ -804,7 +1342,34 @@ export declare interface QueryCache {
     clear(): void;
 }
 
+export declare interface ResolvedStorefrontAnalyticsConfig {
+    enabled: boolean;
+    dispatchOnUnknownConsent: boolean;
+    gtm: {
+        enabled: boolean;
+        containerId: string | null;
+    };
+}
+
+export declare interface ResolvedStorefrontInitConfig {
+    analytics: ResolvedStorefrontAnalyticsConfig;
+}
+
+export declare interface RichTextDetailSection extends DetailSectionBase {
+    sectionType: "RICH_TEXT";
+    content: {
+        html: string;
+    };
+}
+
+export declare type SectionType = "RICH_TEXT" | "BULLET_LIST" | "TABLE";
+
 export declare interface ShippingOperations {
+    /**
+     * Fetch shipping rates currently available for checkout.
+     *
+     * @returns Available shipping rates.
+     */
     getAvailableRates(): Promise<Result<ShippingRate[], StorefrontError>>;
 }
 
@@ -853,14 +1418,29 @@ export declare interface Store {
     currency: string;
     timezone: string;
     logoUrl: string | null;
+    contactEmail: string | null;
     contactPhone: string | null;
+    trackingDispatchOnUnknownConsent: boolean;
+    browserTrackingConfig: BrowserTrackingConfig;
+    analytics: StoreAnalyticsConfig;
     socialLinks: SocialLinks;
 }
 
+export declare interface StoreAnalyticsConfig {
+    enabled: boolean;
+    dispatchOnUnknownConsent: boolean;
+    gtm: GtmBrowserTrackingConfig;
+}
+
+export declare interface StorefrontAnalyticsInitConfig extends StorefrontTrackingRuntimeConfig {
+    stripUrl?: boolean;
+}
+
 export declare interface StorefrontClient {
     readonly config: StorefrontClientConfig;
     readonly cache: CacheHelpers;
     readonly products: ProductsOperations;
+    readonly store: StoreOperations;
     readonly collections: CollectionsOperations;
     readonly categories: CategoriesOperations;
     readonly cart: CartOperations;
@@ -870,6 +1450,7 @@ export declare interface StorefrontClient {
     readonly account: AccountOperations;
     readonly shipping: ShippingOperations;
     readonly analytics: AnalyticsOperations;
+    init(options?: StorefrontInitOptions): Promise<Result<ResolvedStorefrontInitConfig, StorefrontError>>;
     /**
      * Execute a GraphQL query with optional caching
      */
@@ -911,7 +1492,15 @@ export declare interface StorefrontClientConfig {
     apiKey: string;
     storage?: StorageAdapter;
     cacheTTL?: number;
-    storeSlug?: string;
+    /**
+     * How long stored landing attribution remains valid, in milliseconds.
+     * Defaults to 30 days.
+     */
+    trackingAttributionTTL?: number;
+    /**
+     * Deprecated. Pass runtime analytics hooks to `client.init({ analytics: ... })`.
+     */
+    tracking?: StorefrontTrackingRuntimeConfig;
 }
 
 /**
@@ -924,13 +1513,75 @@ export declare class StorefrontError extends Error {
     });
 }
 
+export declare interface StorefrontInitOptions {
+    analytics?: StorefrontAnalyticsInitConfig;
+}
+
 export declare type StorefrontResult<T> = Result<T, StorefrontError>;
 
+/**
+ * Optional browser analytics runtime hooks passed to `createStorefrontClient()`.
+ */
+export declare interface StorefrontTrackingRuntimeConfig {
+    dispatchOnUnknownConsent?: AnalyticsDispatchOnUnknownConsent;
+    resolveConsentState?: () => AnalyticsConsentState | Promise<AnalyticsConsentState>;
+    adapters?: AnalyticsBrowserAdapter[];
+    onDiagnostic?: (diagnostic: AnalyticsDiagnostic) => void;
+}
+
+/**
+ * Store-level read operations exposed by the storefront SDK.
+ */
+export declare interface StoreOperations {
+    get(options?: {
+        cache?: boolean;
+    }): Promise<StorefrontResult<Store>>;
+}
+
+export declare interface TableDetailSection extends DetailSectionBase {
+    sectionType: "TABLE";
+    content: {
+        rows: [string, string][];
+    };
+}
+
 export declare interface Tag {
     id: string;
     name: string;
 }
 
+export declare const TRACKING_ATTRIBUTION_QUERY_PARAM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "gclid", "gbraid", "wbraid", "ttclid", "fbclid"];
+
+export declare interface TrackingAttributionOptions {
+    ttlMs?: number;
+}
+
+export declare interface TrackingAttributionSnapshot {
+    schemaVersion: 1;
+    capturedAt: string;
+    utm: TrackingUtmSnapshot;
+    clickIds: TrackingClickIdsSnapshot;
+}
+
+declare interface TrackingClickIdsSnapshot {
+    schemaVersion: 1;
+    capturedAt: string | null;
+    gclid: string | null;
+    gbraid: string | null;
+    wbraid: string | null;
+    ttclid: string | null;
+    fbclid: string | null;
+}
+
+declare interface TrackingUtmSnapshot {
+    schemaVersion: 1;
+    source: string | null;
+    medium: string | null;
+    campaign: string | null;
+    term: string | null;
+    content: string | null;
+}
+
 /**
  * Validation error - userErrors from mutations
  */