@ekomerc/storefront 0.1.0 → 0.1.3

package/dist/index.d.cts

@@ -0,0 +1,1493 @@
+import { Result } from 'neverthrow';
+
+interface QueryCache {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttl: number): void;
+    clear(): void;
+}
+declare function createQueryCache(): QueryCache;
+
+/**
+ * Base class for all Storefront SDK errors
+ */
+declare class StorefrontError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Network error - fetch failed, connection issues
+ */
+declare class NetworkError extends StorefrontError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Authentication error - invalid/revoked API key, 401/403 responses
+ */
+declare class AuthError extends StorefrontError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Validation error - userErrors from mutations
+ */
+declare class ValidationError extends StorefrontError {
+    readonly userErrors: Array<{
+        field: string | null;
+        message: string;
+    }>;
+    constructor(message: string, userErrors: Array<{
+        field: string | null;
+        message: string;
+    }>, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Not found error - resource doesn't exist
+ */
+declare class NotFoundError extends StorefrontError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * State error - invalid cart state transition
+ */
+declare class StateError extends StorefrontError {
+    readonly state: string;
+    constructor(message: string, state: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * GraphQL error - unexpected GraphQL errors
+ */
+declare class GraphQLError extends StorefrontError {
+    readonly graphqlErrors: Array<{
+        message: string;
+        path?: readonly (string | number)[];
+    }>;
+    constructor(message: string, graphqlErrors: Array<{
+        message: string;
+        path?: readonly (string | number)[];
+    }>, options?: {
+        cause?: Error;
+    });
+}
+
+declare const TRACKING_POLICY_EVENT_TYPES: readonly ["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"];
+type TrackingPolicyEventType = (typeof TRACKING_POLICY_EVENT_TYPES)[number];
+declare const TRACKING_PROVIDERS: readonly ["gtm", "meta", "tiktok"];
+type TrackingProvider = (typeof TRACKING_PROVIDERS)[number];
+declare const GTM_STANDARD_EVENTS: readonly ["page_view", "view_item", "view_item_list", "search", "add_to_cart", "remove_from_cart", "begin_checkout", "purchase"];
+type GtmStandardEventName = (typeof GTM_STANDARD_EVENTS)[number];
+
+/**
+ * Consent states emitted with browser-side analytics events.
+ */
+type AnalyticsConsentState = "granted" | "denied" | "unknown";
+/**
+ * Runtime policies controlling how consent gates browser event dispatch.
+ */
+type AnalyticsDispatchOnUnknownConsent = boolean;
+/**
+ * UTM parameters captured for a visitor session.
+ */
+interface AnalyticsUtm {
+    schemaVersion: 1;
+    source: string | null;
+    medium: string | null;
+    campaign: string | null;
+    term: string | null;
+    content: string | null;
+}
+/**
+ * Click identifiers captured from ad platforms and passed through analytics events.
+ */
+interface AnalyticsClickIds {
+    schemaVersion: 1;
+    capturedAt: string | null;
+    gclid: string | null;
+    gbraid: string | null;
+    wbraid: string | null;
+    ttclid: string | null;
+    fbclid: string | null;
+}
+/**
+ * Request context attached to each browser analytics event.
+ */
+interface AnalyticsEventContextPayload {
+    schemaVersion: 1;
+    path: string;
+}
+/**
+ * Primitive JSON values supported inside analytics properties.
+ */
+type AnalyticsJsonPrimitive = string | number | boolean | null;
+/**
+ * Recursive JSON value shape supported by analytics event properties.
+ */
+type AnalyticsJsonValue = AnalyticsJsonPrimitive | AnalyticsJsonValue[] | {
+    [key: string]: AnalyticsJsonValue;
+};
+/**
+ * Arbitrary analytics event properties sent to ingest and browser adapters.
+ */
+interface AnalyticsProperties {
+    [key: string]: AnalyticsJsonValue;
+}
+/**
+ * Best-effort browser device fingerprint attached to an analytics event.
+ */
+interface AnalyticsBrowserEventDevice {
+    deviceType: string;
+    deviceOs: string | null;
+    deviceBrowser: string | null;
+}
+/**
+ * Canonical browser analytics event shape used by the storefront SDK.
+ */
+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;
+}
+/**
+ * Consent state payload passed to browser adapters and diagnostics.
+ */
+interface AnalyticsConsentUpdate {
+    consentState: AnalyticsConsentState;
+    dispatchOnUnknownConsent: AnalyticsDispatchOnUnknownConsent;
+}
+/**
+ * Input provided to a browser adapter when dispatching an analytics event.
+ */
+interface AnalyticsAdapterDispatchInput {
+    event: AnalyticsBrowserEvent;
+    consent: AnalyticsConsentUpdate;
+}
+/**
+ * Reasons a browser adapter may skip dispatch instead of throwing.
+ */
+type AnalyticsAdapterSkipReason = "unsupported_event" | "consent_blocked" | "runtime_unavailable";
+/**
+ * Structured result returned when a browser adapter intentionally skips dispatch.
+ */
+interface AnalyticsAdapterOperationSkippedResult {
+    status: "skipped";
+    reason: "runtime_unavailable";
+}
+/**
+ * Result returned by browser adapter dispatch and consent-update hooks.
+ */
+type AnalyticsAdapterOperationResult = void | {
+    status: "success";
+} | AnalyticsAdapterOperationSkippedResult;
+/**
+ * Browser-side analytics adapter contract for GTM, Meta, TikTok, or custom integrations.
+ */
+interface AnalyticsBrowserAdapter {
+    provider: TrackingProvider;
+    dispatch(input: AnalyticsAdapterDispatchInput): AnalyticsAdapterOperationResult | Promise<AnalyticsAdapterOperationResult>;
+    updateConsent?(input: AnalyticsConsentUpdate): AnalyticsAdapterOperationResult | Promise<AnalyticsAdapterOperationResult>;
+}
+/**
+ * Diagnostic events emitted by the analytics runtime for ingest and adapter activity.
+ */
+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;
+};
+/**
+ * Optional browser analytics runtime hooks passed to `createStorefrontClient()`.
+ */
+interface StorefrontTrackingRuntimeConfig {
+    dispatchOnUnknownConsent?: AnalyticsDispatchOnUnknownConsent;
+    resolveConsentState?: () => AnalyticsConsentState | Promise<AnalyticsConsentState>;
+    adapters?: AnalyticsBrowserAdapter[];
+    onDiagnostic?: (diagnostic: AnalyticsDiagnostic) => void;
+}
+
+/**
+ * Re-export generated GraphQL types once codegen runs
+ * For now, define placeholder types that will be replaced
+ */
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+interface StorefrontClientConfig {
+    endpoint: string;
+    apiKey: string;
+    storage?: StorageAdapter;
+    cacheTTL?: number;
+    /**
+     * 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;
+}
+interface StorefrontAnalyticsInitConfig extends StorefrontTrackingRuntimeConfig {
+    stripUrl?: boolean;
+}
+interface StorefrontInitOptions {
+    analytics?: StorefrontAnalyticsInitConfig;
+}
+interface ResolvedStorefrontAnalyticsConfig {
+    enabled: boolean;
+    dispatchOnUnknownConsent: boolean;
+    gtm: {
+        enabled: boolean;
+        containerId: string | null;
+    };
+}
+interface ResolvedStorefrontInitConfig {
+    analytics: ResolvedStorefrontAnalyticsConfig;
+}
+interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor: string | null;
+    endCursor: string | null;
+}
+interface PaginatedResult<T> {
+    items: T[];
+    pageInfo: PageInfo;
+}
+type StorefrontResult<T> = Result<T, StorefrontError>;
+type WeightUnit = "g" | "kg" | "lb" | "oz";
+interface ProductOptionValue {
+    id: string;
+    value: string;
+    position: number;
+}
+interface ProductOption {
+    id: string;
+    name: string;
+    position: number;
+    values: ProductOptionValue[];
+}
+interface ProductImage {
+    id: string;
+    url: string;
+    altText: string | null;
+    position: number;
+}
+interface QuantityPricingTier {
+    minQuantity: number;
+    price: number;
+}
+interface ProductVariant {
+    id: string;
+    title: string;
+    sku: string | null;
+    price: number;
+    compareAtPrice: number | null;
+    weight: number | null;
+    weightUnit: WeightUnit;
+    requiresShipping: boolean;
+    availableForSale: boolean;
+    quantity: number;
+    selectedOptions: ProductOptionValue[];
+    image: ProductImage | null;
+    isOnSale: boolean;
+    quantityPricing: QuantityPricingTier[];
+}
+interface Category {
+    id: string;
+    name: string;
+    handle: string;
+    description: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    imageAsset: {
+        url: string;
+        altText: string | null;
+        width: number | null;
+        height: number | null;
+    } | null;
+    parent: Category | null;
+    children: Category[];
+    ancestors: Category[];
+    productCount: number;
+}
+interface FlatCategory {
+    id: string;
+    name: string;
+    handle: string;
+    description: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    imageUrl: string | null;
+    parentId: string | null;
+    depth: number;
+    hasChildren: boolean;
+    productCount: number;
+}
+interface Tag {
+    id: string;
+    name: string;
+}
+type SectionType = "RICH_TEXT" | "BULLET_LIST" | "TABLE";
+type DisplayIntent = "ACCORDION" | "SPECIFICATIONS" | "BOTH";
+interface DetailSectionBase {
+    id: string;
+    title: string;
+    displayIntent: DisplayIntent;
+    position: number;
+}
+interface RichTextDetailSection extends DetailSectionBase {
+    sectionType: "RICH_TEXT";
+    content: {
+        html: string;
+    };
+}
+interface BulletListDetailSection extends DetailSectionBase {
+    sectionType: "BULLET_LIST";
+    content: {
+        items: string[];
+    };
+}
+interface TableDetailSection extends DetailSectionBase {
+    sectionType: "TABLE";
+    content: {
+        rows: [string, string][];
+    };
+}
+type DetailSection = RichTextDetailSection | BulletListDetailSection | TableDetailSection;
+interface Product {
+    id: string;
+    handle: string;
+    title: string;
+    description: string | null;
+    vendor: string | null;
+    productType: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    publishedAt: string | null;
+    createdAt: string;
+    availableForSale: boolean;
+    media: ProductImage[];
+    options: ProductOption[];
+    variants: ProductVariant[];
+    categories: Category[];
+    primaryCategory: Category | null;
+    tags: Tag[];
+    detailSections: DetailSection[];
+}
+type ProductSortKey = "CREATED_AT" | "TITLE" | "PRICE_ASC" | "PRICE_DESC" | "BEST_SELLING";
+interface ProductFilter {
+    search?: string | null;
+    categoryHandle?: string | null;
+    categoryId?: string | null;
+    includeDescendants?: boolean | null;
+    collectionHandle?: string | null;
+    collectionId?: string | null;
+    tags?: string[] | null;
+    vendor?: string | null;
+    productType?: string | null;
+    minPrice?: number | null;
+    maxPrice?: number | null;
+    availableForSale?: boolean | null;
+}
+type CollectionType = "manual" | "intelligent";
+type CollectionSortOrder = "manual" | "best_selling" | "newest" | "price_asc" | "price_desc";
+interface Collection {
+    id: string;
+    handle: string;
+    title: string;
+    description: string | null;
+    type: CollectionType;
+    sortOrder: CollectionSortOrder;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    productCount: number;
+    imageAsset: {
+        url: string;
+        altText: string | null;
+        width: number | null;
+        height: number | null;
+    } | null;
+}
+interface CartItem {
+    id: string;
+    variantId: string;
+    quantity: number;
+    priceAtAdd: number;
+    effectiveUnitPrice: number;
+    lineTotal: number;
+    taxAmount: number;
+    variant: ProductVariant | null;
+}
+type CartStatus = "active" | "checkout" | "converted" | "expired";
+interface AppliedPromoCode {
+    code: string;
+    discountType: string;
+    discountAmount: number;
+    description: string;
+}
+interface AppliedDiscount {
+    promotionId: string;
+    discountClass: string;
+    discountType: string;
+    discountAmount: number;
+    description: string;
+    isAutomatic: boolean;
+}
+interface Cart {
+    id: string;
+    token: string;
+    status: CartStatus;
+    items: CartItem[];
+    totalItems: number;
+    totalPrice: number;
+    taxTotal: number;
+    shippingTotal: number;
+    total: number;
+    discountTotal: number;
+    appliedPromoCode: AppliedPromoCode | null;
+    appliedDiscounts: AppliedDiscount[];
+    customerEmail: string | null;
+    customerPhone: string | null;
+    shippingAddress: Address | null;
+    billingAddress: Address | null;
+    notes: string | null;
+    paymentMethod: string | null;
+    shippingRateId: string | null;
+    checkoutStartedAt?: string | null;
+    checkoutExpiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Address {
+    firstName: string | null;
+    lastName: string | null;
+    company: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    province: string | null;
+    provinceCode: string | null;
+    country: string;
+    countryCode: string;
+    zip: string;
+    phone: string | null;
+}
+interface CheckoutData {
+    email?: string;
+    phone?: string;
+    shippingAddress?: Address;
+    billingAddress?: Address;
+    notes?: string;
+    emailMarketingConsent?: boolean | null;
+    paymentMethod?: string;
+    shippingRateId?: string;
+}
+interface ShippingRate {
+    id: string;
+    name: string;
+    price: number;
+    minOrderAmount: number | null;
+    estimatedDaysMin: number | null;
+    estimatedDaysMax: number | null;
+    isFree: boolean;
+}
+interface AvailablePaymentMethod {
+    method: string;
+    displayName: string;
+    additionalFee: number;
+}
+interface SocialLinks {
+    instagram?: string;
+    facebook?: string;
+    tiktok?: string;
+    twitter?: string;
+}
+/**
+ * Public GTM settings returned by the storefront `store` query.
+ */
+interface GtmBrowserTrackingConfig {
+    enabled: boolean;
+    containerId: string | null;
+}
+/**
+ * Browser-side tracking configuration returned by the storefront `store` query.
+ */
+interface BrowserTrackingConfig {
+    gtm: GtmBrowserTrackingConfig;
+}
+interface StoreAnalyticsConfig {
+    enabled: boolean;
+    dispatchOnUnknownConsent: boolean;
+    gtm: GtmBrowserTrackingConfig;
+}
+interface Store {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    currency: string;
+    timezone: string;
+    logoUrl: string | null;
+    contactEmail: string | null;
+    contactPhone: string | null;
+    trackingDispatchOnUnknownConsent: boolean;
+    browserTrackingConfig: BrowserTrackingConfig;
+    analytics: StoreAnalyticsConfig;
+    socialLinks: SocialLinks;
+}
+interface PaymentInstructions {
+    bankAccount: string;
+    recipientName: string;
+    referenceNumber: string;
+    ipsQrCodeBase64: string;
+    expiresAt: string;
+}
+interface OrderItem {
+    id: string;
+    productTitle: string;
+    variantTitle: string | null;
+    sku: string | null;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+interface Order {
+    id: string;
+    orderNumber: string;
+    email: string | null;
+    phone: string | null;
+    status: string;
+    shippingAddress: Address | null;
+    subtotal: number;
+    total: number;
+    note: string | null;
+    items: OrderItem[];
+    paymentInstructions: PaymentInstructions | null;
+    createdAt: string;
+}
+interface Customer {
+    id: string;
+    name: string | null;
+    email: string;
+    emailVerified: boolean;
+}
+interface CustomerAddress {
+    id: string;
+    label: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    zip: string | null;
+    phone: string | null;
+    isDefault: boolean;
+    createdAt: string;
+}
+interface CustomerAddressInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    zip?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface CustomerAddressUpdateInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    zip?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface CustomerUpdateInput {
+    name?: string;
+    email?: string;
+    currentPassword?: string;
+    newPassword?: string;
+}
+interface CustomerOrderItem {
+    id: string;
+    productTitle: string;
+    variantTitle: string | null;
+    sku: string | null;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+interface CustomerOrder {
+    id: string;
+    orderNumber: string;
+    status: string;
+    email: string;
+    phone: string | null;
+    subtotal: number;
+    total: number;
+    note: string | null;
+    items: CustomerOrderItem[];
+    createdAt: string;
+}
+
+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>>;
+}
+
+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;
+        name?: string;
+    }): Promise<Result<{
+        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;
+    }): Promise<Result<{
+        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;
+}
+
+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>>;
+}
+
+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>>;
+}
+
+interface CollectionsListOptions {
+    first?: number;
+    after?: string;
+    search?: string;
+}
+type CollectionProductSort = "manual" | "best_selling" | "newest" | "price_asc" | "price_desc";
+interface CollectionProductsOptions {
+    first?: number;
+    after?: string;
+    sort?: CollectionProductSort;
+}
+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>>;
+}
+
+interface GraphQLRequest {
+    query: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}
+interface GraphQLResponse<T = unknown> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        path?: readonly (string | number)[];
+    }>;
+}
+interface GraphQLClient {
+    query<T>(request: GraphQLRequest, options?: {
+        cache?: boolean;
+    }): Promise<Result<T, StorefrontError>>;
+    mutate<T>(request: GraphQLRequest): Promise<Result<T, StorefrontError>>;
+}
+/**
+ * Extract userErrors from mutation result and convert to ValidationError if present
+ */
+declare function extractUserErrors<T extends {
+    userErrors?: Array<{
+        field: string | null;
+        message: string;
+    }>;
+}>(data: T, fieldName: keyof T): Result<Exclude<T[keyof T], undefined>, ValidationError>;
+
+interface PaymentsOperations {
+    /**
+     * Fetch payment methods currently available for checkout.
+     *
+     * @returns Available storefront payment methods.
+     */
+    getAvailableMethods(): Promise<Result<AvailablePaymentMethod[], StorefrontError>>;
+}
+
+interface ProductsListOptions {
+    first?: number;
+    after?: string;
+    filter?: ProductFilter;
+    sort?: ProductSortKey;
+}
+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>>;
+}
+
+interface AnalyticsInitOptions {
+    stripUrl?: boolean;
+}
+/**
+ * Checkout step identifiers for `checkout_step_completed` analytics events.
+ */
+type CheckoutStep = "contact" | "shipping" | "payment" | "review";
+/**
+ * Canonical analytics event type values accepted by the storefront ingest endpoint.
+ */
+type AnalyticsEventType = TrackingPolicyEventType;
+/**
+ * Supported preset event names accepted by `track()`.
+ */
+type AnalyticsPresetEventName = "page_view" | "product_view" | "collection_view" | "search_performed" | "add_to_cart" | "remove_from_cart" | "checkout_started" | "checkout_step_completed" | "checkout_completed";
+/**
+ * Event name accepted by `track()`.
+ * Preset names (e.g. `product_view`) are normalized to `analytics.*` types.
+ * Unknown names are sent as `analytics.custom` with `{ eventName: <name> }`.
+ */
+type AnalyticsTrackEventName = AnalyticsPresetEventName | AnalyticsEventType;
+type PresetEventProperties = {
+    page_view: Record<string, never>;
+    product_view: {
+        productId: string;
+        variantId?: string | null;
+    };
+    collection_view: {
+        collectionId: string;
+    };
+    search_performed: {
+        query: string;
+        resultsCount: number;
+    };
+    add_to_cart: {
+        cartId: string;
+        quantity: number;
+        itemsCount: number;
+        cartValue: number;
+    };
+    remove_from_cart: {
+        cartId: string;
+        quantity: number;
+        itemsCount: number;
+        cartValue: number;
+    };
+    checkout_started: {
+        cartId: string;
+    };
+    checkout_step_completed: {
+        cartId: string;
+        step: CheckoutStep;
+    };
+    checkout_completed: {
+        orderId: string;
+        cartId: string;
+        orderTotal: number;
+    };
+};
+type PresetPropertiesByName<T extends AnalyticsPresetEventName> = PresetEventProperties[T];
+/**
+ * Optional context overrides for a tracking call.
+ */
+interface AnalyticsContext {
+    path?: string;
+    referrer?: string | null;
+    occurredAt?: Date | string;
+    sessionId?: string;
+    visitorId?: string;
+    customerId?: string | null;
+    utmSource?: string | null;
+    utmMedium?: string | null;
+    utmCampaign?: string | null;
+    utmTerm?: string | null;
+    utmContent?: string | null;
+    consentState?: AnalyticsConsentState;
+    clickIds?: Partial<Omit<AnalyticsClickIds, "schemaVersion">>;
+    deviceType?: string;
+    deviceOs?: string | null;
+    deviceBrowser?: string | null;
+}
+/**
+ * Error detail for a single ingest payload item.
+ */
+interface AnalyticsErrorItem {
+    /**
+     * Index of the event in the request `events` array.
+     */
+    index: number;
+    /**
+     * Server-assigned identifier for the event, if available.
+     */
+    eventId: string | null;
+    /**
+     * Validation or processing error code.
+     */
+    code: string;
+    /**
+     * Human-readable description of the failure.
+     */
+    message: string;
+}
+/**
+ * Response summary from the analytics ingest endpoint.
+ */
+interface AnalyticsIngestResponse {
+    /**
+     * Number of events accepted and persisted.
+     */
+    acceptedCount: number;
+    /**
+     * Number of events recognized as duplicates.
+     */
+    duplicateCount: number;
+    /**
+     * Number of events rejected by validation or storage.
+     */
+    rejectedCount: number;
+    /**
+     * Per-item errors, aligned by event index.
+     */
+    errors: AnalyticsErrorItem[];
+}
+interface AnalyticsOperations {
+    /**
+     * Track an analytics event.
+     *
+     * Supports preset event names (`page_view`, `product_view`, `add_to_cart`, etc.),
+     * canonical names (`analytics.page_view`, ...), and custom events.
+     *
+     * Custom event names are sent as `analytics.custom` with `eventName` included in `properties`.
+     *
+     * @param eventName - Preset/event-name to track.
+     * @param context - Optional per-call context overrides.
+     * @returns Tracking result with ingest summary, or network/validation error.
+     */
+    track(eventName: "page_view", context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track a product page view.
+     */
+    track(eventName: "product_view", input: PresetPropertiesByName<"product_view">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track a collection page view.
+     */
+    track(eventName: "collection_view", input: PresetPropertiesByName<"collection_view">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track search execution.
+     */
+    track(eventName: "search_performed", input: PresetPropertiesByName<"search_performed">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track adding items to cart.
+     */
+    track(eventName: "add_to_cart", input: PresetPropertiesByName<"add_to_cart">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track removing items from cart.
+     */
+    track(eventName: "remove_from_cart", input: PresetPropertiesByName<"remove_from_cart">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track checkout start.
+     */
+    track(eventName: "checkout_started", input: PresetPropertiesByName<"checkout_started">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track checkout step completion.
+     */
+    track(eventName: "checkout_step_completed", input: PresetPropertiesByName<"checkout_step_completed">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track successful checkout completion.
+     */
+    track(eventName: "checkout_completed", input: PresetPropertiesByName<"checkout_completed">, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+    /**
+     * Track a custom analytics event.
+     *
+     * Example:
+     * `client.analytics.track("homepage.hero_clicked", { section: "hero", position: 1 })`
+     */
+    track(eventName: string, properties: AnalyticsProperties, context?: AnalyticsContext): Promise<Result<AnalyticsIngestResponse, StorefrontError>>;
+}
+
+interface ShippingOperations {
+    /**
+     * Fetch shipping rates currently available for checkout.
+     *
+     * @returns Available shipping rates.
+     */
+    getAvailableRates(): Promise<Result<ShippingRate[], StorefrontError>>;
+}
+
+/**
+ * Store-level read operations exposed by the storefront SDK.
+ */
+interface StoreOperations {
+    get(options?: {
+        cache?: boolean;
+    }): Promise<StorefrontResult<Store>>;
+}
+
+interface CacheHelpers {
+    /**
+     * Clear all cached query results for this client instance.
+     */
+    clear(): void;
+}
+interface StorefrontClient {
+    readonly config: StorefrontClientConfig;
+    readonly cache: CacheHelpers;
+    readonly products: ProductsOperations;
+    readonly store: StoreOperations;
+    readonly collections: CollectionsOperations;
+    readonly categories: CategoriesOperations;
+    readonly cart: CartOperations;
+    readonly checkout: CheckoutOperations;
+    readonly payments: PaymentsOperations;
+    readonly auth: AuthOperations;
+    readonly account: AccountOperations;
+    readonly shipping: ShippingOperations;
+    readonly analytics: AnalyticsOperations;
+    init(options?: StorefrontInitOptions): Promise<Result<ResolvedStorefrontInitConfig, StorefrontError>>;
+    /**
+     * Execute a GraphQL query with optional caching
+     */
+    query<T>(request: GraphQLRequest, options?: {
+        cache?: boolean;
+    }): Promise<Result<T, StorefrontError>>;
+    /**
+     * Execute a GraphQL mutation (never cached)
+     */
+    mutate<T>(request: GraphQLRequest): Promise<Result<T, StorefrontError>>;
+    /**
+     * Get the current cart token from storage
+     */
+    getCartToken(): string | null;
+    /**
+     * Set the cart token in storage
+     */
+    setCartToken(token: string): void;
+    /**
+     * Clear the cart token from storage
+     */
+    clearCartToken(): void;
+    /**
+     * Get the current customer JWT token from storage
+     */
+    getCustomerToken(): string | null;
+    /**
+     * Set the customer JWT token in storage
+     */
+    setCustomerToken(token: string): void;
+    /**
+     * Clear the customer JWT token from storage
+     */
+    clearCustomerToken(): void;
+}
+
+/**
+ * Create a new Storefront SDK client
+ *
+ * @param config - Client configuration including endpoint, API key, and optional storage adapter
+ * @returns A configured StorefrontClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createStorefrontClient } from "@ekomerc/storefront";
+ *
+ * const client = createStorefrontClient({
+ *   endpoint: "https://api.mystore.com/storefront",
+ *   apiKey: "sfk_abc123...",
+ * });
+ *
+ * // Query products
+ * const result = await client.query({
+ *   query: `query { products { edges { node { id title } } } }`,
+ * });
+ *
+ * if (result.isOk()) {
+ *   console.log(result.value);
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function createStorefrontClient(config: StorefrontClientConfig): StorefrontClient;
+
+interface CategoryProductsOptions {
+    first?: number;
+    after?: string;
+    includeDescendants?: boolean;
+}
+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>>;
+}
+
+/**
+ * Namespaced GTM event names emitted by the storefront adapter.
+ */
+type GtmNamespacedEventName = `ekomerc.${GtmStandardEventName}`;
+/**
+ * GTM ecommerce item payload derived from storefront analytics properties.
+ */
+interface GtmItem {
+    product_id: string;
+    variant_id?: string;
+    quantity: number;
+    unit_price: number;
+    line_total: number;
+    currency: string;
+}
+/**
+ * GTM attribution payload copied from captured UTM and click ID data.
+ */
+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;
+}
+/**
+ * GTM page context payload copied from the storefront analytics event.
+ */
+interface GtmContextPayload {
+    path: string;
+    referrer: string | null;
+}
+/**
+ * GTM `ekomerc` payload pushed alongside each `dataLayer` event.
+ */
+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[];
+}
+/**
+ * Full object pushed to the configured GTM data layer.
+ */
+interface GtmDataLayerEvent {
+    event: GtmNamespacedEventName;
+    ekomerc: GtmEcommercePayload;
+}
+/**
+ * GTM consent-mode update payload derived from storefront consent state.
+ */
+interface GtmConsentModeUpdate {
+    analytics_storage: "granted" | "denied";
+    ad_storage: "granted" | "denied";
+    ad_user_data: "granted" | "denied";
+    ad_personalization: "granted" | "denied";
+}
+/**
+ * Optional runtime overrides for the GTM browser adapter.
+ */
+interface GtmBrowserAdapterOptions {
+    dataLayerName?: string;
+    getWindow?: () => object | null;
+}
+/**
+ * Maps a storefront analytics event to a GTM `dataLayer.push()` payload.
+ */
+declare function buildGtmDataLayerEvent(input: AnalyticsAdapterDispatchInput): GtmDataLayerEvent | null;
+/**
+ * Converts storefront consent state into a GTM consent-mode update payload.
+ */
+declare function buildGtmConsentModeUpdate({ consentState }: AnalyticsConsentUpdate): GtmConsentModeUpdate;
+/**
+ * Creates a GTM browser adapter that pushes storefront analytics events into `window.dataLayer`.
+ */
+declare function createGtmBrowserAdapter(config: GtmBrowserTrackingConfig, options?: GtmBrowserAdapterOptions): AnalyticsBrowserAdapter | null;
+
+declare const CART_TOKEN_KEY = "ekomerc_cart_token";
+declare const CUSTOMER_TOKEN_KEY = "ekomerc_customer_token";
+/**
+ * localStorage adapter for browser environments
+ */
+declare function createLocalStorageAdapter(): StorageAdapter;
+/**
+ * In-memory adapter for SSR or testing
+ */
+declare function createMemoryAdapter(): StorageAdapter;
+/**
+ * Detect environment and create appropriate default adapter
+ */
+declare function createDefaultAdapter(): StorageAdapter;
+
+declare const TRACKING_ATTRIBUTION_QUERY_PARAM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "gclid", "gbraid", "wbraid", "ttclid", "fbclid"];
+interface TrackingUtmSnapshot {
+    schemaVersion: 1;
+    source: string | null;
+    medium: string | null;
+    campaign: string | null;
+    term: string | null;
+    content: string | null;
+}
+interface TrackingClickIdsSnapshot {
+    schemaVersion: 1;
+    capturedAt: string | null;
+    gclid: string | null;
+    gbraid: string | null;
+    wbraid: string | null;
+    ttclid: string | null;
+    fbclid: string | null;
+}
+interface TrackingAttributionSnapshot {
+    schemaVersion: 1;
+    capturedAt: string;
+    utm: TrackingUtmSnapshot;
+    clickIds: TrackingClickIdsSnapshot;
+}
+interface TrackingAttributionOptions {
+    ttlMs?: number;
+}
+
+export { AuthError, CART_TOKEN_KEY, CUSTOMER_TOKEN_KEY, GraphQLError, NetworkError, NotFoundError, StateError, StorefrontError, TRACKING_ATTRIBUTION_QUERY_PARAM_KEYS, ValidationError, buildGtmConsentModeUpdate, buildGtmDataLayerEvent, createDefaultAdapter, createGtmBrowserAdapter, createLocalStorageAdapter, createMemoryAdapter, createQueryCache, createStorefrontClient, extractUserErrors };
+export type { AccountOperations, Address, AnalyticsAdapterDispatchInput, AnalyticsAdapterOperationResult, AnalyticsAdapterOperationSkippedResult, AnalyticsAdapterSkipReason, AnalyticsBrowserAdapter, AnalyticsBrowserEvent, AnalyticsBrowserEventDevice, AnalyticsClickIds, AnalyticsConsentState, AnalyticsConsentUpdate, AnalyticsContext, AnalyticsDiagnostic, AnalyticsDispatchOnUnknownConsent, AnalyticsErrorItem, AnalyticsEventContextPayload, AnalyticsEventType, AnalyticsIngestResponse, AnalyticsInitOptions, AnalyticsJsonPrimitive, AnalyticsJsonValue, AnalyticsOperations, AnalyticsPresetEventName, AnalyticsProperties, AnalyticsTrackEventName, AnalyticsUtm, AppliedDiscount, AppliedPromoCode, AuthOperations, AvailablePaymentMethod, BrowserTrackingConfig, BulletListDetailSection, CacheHelpers, Cart, CartItem, CartOperations, CartStatus, CategoriesOperations, Category, CategoryProductsOptions, CheckoutData, CheckoutOperations, CheckoutStep, Collection, CollectionProductSort, CollectionProductsOptions, CollectionSortOrder, CollectionType, CollectionsListOptions, CollectionsOperations, Customer, CustomerAddress, CustomerAddressInput, CustomerAddressUpdateInput, CustomerOrder, CustomerOrderItem, CustomerUpdateInput, DetailSection, DisplayIntent, FlatCategory, GraphQLClient, GraphQLRequest, GraphQLResponse, GtmAttributionPayload, GtmBrowserAdapterOptions, GtmBrowserTrackingConfig, GtmConsentModeUpdate, GtmContextPayload, GtmDataLayerEvent, GtmEcommercePayload, GtmItem, GtmNamespacedEventName, Order, OrderItem, PageInfo, PaginatedResult, PaymentInstructions, PaymentsOperations, Product, ProductFilter, ProductImage, ProductOption, ProductOptionValue, ProductSortKey, ProductVariant, ProductsListOptions, ProductsOperations, QuantityPricingTier, QueryCache, ResolvedStorefrontAnalyticsConfig, ResolvedStorefrontInitConfig, RichTextDetailSection, SectionType, ShippingOperations, ShippingRate, SocialLinks, StorageAdapter, Store, StoreAnalyticsConfig, StoreOperations, StorefrontAnalyticsInitConfig, StorefrontClient, StorefrontClientConfig, StorefrontInitOptions, StorefrontResult, StorefrontTrackingRuntimeConfig, TableDetailSection, Tag, TrackingAttributionOptions, TrackingAttributionSnapshot, WeightUnit };