@ekomerc/storefront 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,952 @@
+import { Result } from 'neverthrow';
+
+export declare interface AccountOperations {
+    orders(args?: {
+        first?: number;
+        after?: string;
+        last?: number;
+        before?: string;
+    }): Promise<Result<PaginatedResult<CustomerOrder>, StorefrontError>>;
+    addresses(): Promise<Result<CustomerAddress[], StorefrontError>>;
+    createAddress(input: CustomerAddressInput): Promise<Result<CustomerAddress, StorefrontError>>;
+    updateAddress(addressId: string, input: CustomerAddressUpdateInput): Promise<Result<CustomerAddress, StorefrontError>>;
+    deleteAddress(addressId: string): Promise<Result<string, StorefrontError>>;
+    update(input: CustomerUpdateInput): Promise<Result<Customer, StorefrontError>>;
+}
+
+export declare interface Address {
+    firstName: string | null;
+    lastName: string | null;
+    company: string | null;
+    address1: string;
+    address2: string | null;
+    city: string;
+    province: string | null;
+    provinceCode: string | null;
+    country: string;
+    countryCode: string;
+    zip: string;
+    phone: string | null;
+}
+
+declare interface AnalyticsClickIds {
+    schemaVersion: 1;
+    capturedAt: string | null;
+    gclid: string | null;
+    gbraid: string | null;
+    wbraid: string | null;
+    ttclid: string | null;
+    fbclid: string | null;
+}
+
+declare type AnalyticsConsentState = "granted" | "denied" | "unknown";
+
+/**
+ * Optional context overrides for a tracking call.
+ */
+export declare interface AnalyticsContext {
+    storeSlug?: string;
+    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.
+ */
+export declare 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;
+}
+
+/**
+ * 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";
+
+/**
+ * Response summary from the analytics ingest endpoint.
+ */
+export declare 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[];
+}
+
+/**
+ * Primitive value allowed in analytics custom event properties.
+ */
+export declare type AnalyticsJsonPrimitive = string | number | boolean | null;
+
+/**
+ * Recursive JSON value allowed in analytics custom event properties.
+ */
+export declare type AnalyticsJsonValue = AnalyticsJsonPrimitive | AnalyticsJsonValue[] | {
+    [key: string]: AnalyticsJsonValue;
+};
+
+export declare 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>>;
+}
+
+/**
+ * Supported preset event names accepted by `track()`.
+ */
+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.
+ */
+export declare interface AnalyticsProperties {
+    [key: string]: AnalyticsJsonValue;
+}
+
+/**
+ * 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> }`.
+ */
+export declare type AnalyticsTrackEventName = AnalyticsPresetEventName | AnalyticsEventType | string;
+
+export declare interface AppliedDiscount {
+    promotionId: string;
+    discountClass: string;
+    discountType: string;
+    discountAmount: number;
+    description: string;
+    isAutomatic: boolean;
+}
+
+export declare interface AppliedPromoCode {
+    code: string;
+    discountType: string;
+    discountAmount: number;
+    description: string;
+}
+
+/**
+ * Authentication error - invalid/revoked API key, 401/403 responses
+ */
+export declare class AuthError extends StorefrontError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+
+export declare interface AuthOperations {
+    register(input: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<Result<{
+        customer: Customer;
+        token: string;
+    }, StorefrontError>>;
+    login(input: {
+        email: string;
+        password: string;
+    }): Promise<Result<{
+        customer: Customer;
+        token: string;
+    }, StorefrontError>>;
+    logout(): void;
+    requestPasswordReset(email: string): Promise<Result<{
+        success: boolean;
+    }, StorefrontError>>;
+    resetPassword(input: {
+        token: string;
+        newPassword: string;
+    }): Promise<Result<{
+        success: boolean;
+    }, StorefrontError>>;
+    verifyEmail(token: string): Promise<Result<Customer, StorefrontError>>;
+    me(): Promise<Result<Customer | null, StorefrontError>>;
+    isLoggedIn(): boolean;
+}
+
+export declare interface AvailablePaymentMethod {
+    method: string;
+    displayName: string;
+    additionalFee: number;
+}
+
+export declare interface CacheHelpers {
+    clear(): void;
+}
+
+export declare 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;
+}
+
+export declare const CART_TOKEN_KEY = "ekomerc_cart_token";
+
+export declare interface CartItem {
+    id: string;
+    variantId: string;
+    quantity: number;
+    priceAtAdd: number;
+    effectiveUnitPrice: number;
+    lineTotal: number;
+    taxAmount: number;
+    variant: ProductVariant | null;
+}
+
+export declare interface CartOperations {
+    get(): Promise<Result<Cart | null, StorefrontError>>;
+    create(): Promise<Result<Cart, StorefrontError>>;
+    addItem(variantId: string, quantity: number): Promise<Result<Cart, StorefrontError>>;
+    updateItem(variantId: string, quantity: number): Promise<Result<Cart, StorefrontError>>;
+    removeItem(variantId: string): Promise<Result<Cart, StorefrontError>>;
+    clear(): Promise<Result<Cart, StorefrontError>>;
+    applyPromoCode(code: string): Promise<Result<Cart, StorefrontError>>;
+    removePromoCode(): Promise<Result<Cart, StorefrontError>>;
+}
+
+export declare type CartStatus = "active" | "checkout" | "converted" | "abandoned" | "expired";
+
+export declare interface CategoriesOperations {
+    tree(): Promise<Result<Category[], StorefrontError>>;
+    flat(): Promise<Result<FlatCategory[], StorefrontError>>;
+    get(idOrHandle: string): Promise<Result<Category, StorefrontError>>;
+    getProducts(idOrHandle: string, options?: CategoryProductsOptions): Promise<Result<PaginatedResult<Product>, StorefrontError>>;
+}
+
+export declare 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;
+}
+
+export declare interface CategoryProductsOptions {
+    first?: number;
+    after?: string;
+    includeDescendants?: boolean;
+}
+
+export declare interface CheckoutData {
+    email?: string;
+    phone?: string;
+    shippingAddress?: Address;
+    billingAddress?: Address;
+    notes?: string;
+    emailMarketingConsent?: boolean | null;
+    paymentMethod?: string;
+    shippingRateId?: string;
+}
+
+export declare interface CheckoutOperations {
+    start(): Promise<Result<Cart, StorefrontError>>;
+    update(data: CheckoutData): Promise<Result<Cart, StorefrontError>>;
+    complete(): Promise<Result<Order, StorefrontError>>;
+    abandon(): Promise<Result<Cart, StorefrontError>>;
+}
+
+/**
+ * Checkout step identifiers for `checkout_step_completed` analytics events.
+ */
+export declare type CheckoutStep = "contact" | "shipping" | "payment" | "review";
+
+export declare 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;
+}
+
+export declare interface CollectionProductsOptions {
+    first?: number;
+    after?: string;
+    sort?: CollectionProductSort;
+}
+
+export declare type CollectionProductSort = "manual" | "best_selling" | "newest" | "price_asc" | "price_desc";
+
+export declare interface CollectionsListOptions {
+    first?: number;
+    after?: string;
+    search?: string;
+}
+
+export declare interface CollectionsOperations {
+    list(options?: CollectionsListOptions): Promise<Result<PaginatedResult<Collection>, StorefrontError>>;
+    get(idOrHandle: string): Promise<Result<Collection, StorefrontError>>;
+    getProducts(idOrHandle: string, options?: CollectionProductsOptions): Promise<Result<PaginatedResult<Product>, StorefrontError>>;
+}
+
+export declare type CollectionSortOrder = "manual" | "best_selling" | "newest" | "price_asc" | "price_desc";
+
+export declare type CollectionType = "manual" | "intelligent";
+
+/**
+ * Detect environment and create appropriate default adapter
+ */
+export declare function createDefaultAdapter(): StorageAdapter;
+
+/**
+ * localStorage adapter for browser environments
+ */
+export declare function createLocalStorageAdapter(): StorageAdapter;
+
+/**
+ * In-memory adapter for SSR or testing
+ */
+export declare function createMemoryAdapter(): StorageAdapter;
+
+export declare function createQueryCache(): QueryCache;
+
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function createStorefrontClient(config: StorefrontClientConfig): StorefrontClient;
+
+export declare interface Customer {
+    id: string;
+    name: string | null;
+    email: string;
+    emailVerified: boolean;
+}
+
+export declare const CUSTOMER_TOKEN_KEY = "ekomerc_customer_token";
+
+export declare interface CustomerAddress {
+    id: string;
+    label: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    postalCode: string | null;
+    phone: string | null;
+    isDefault: boolean;
+    createdAt: string;
+}
+
+export declare interface CustomerAddressInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    postalCode?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+
+export declare interface CustomerAddressUpdateInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    postalCode?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+
+export declare interface CustomerOrder {
+    id: string;
+    orderNumber: string;
+    status: string;
+    email: string;
+    phone: string | null;
+    subtotal: number;
+    total: number;
+    note: string | null;
+    items: CustomerOrderItem[];
+    createdAt: string;
+}
+
+export declare interface CustomerOrderItem {
+    id: string;
+    productTitle: string;
+    variantTitle: string | null;
+    sku: string | null;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+
+export declare interface CustomerUpdateInput {
+    name?: string;
+    email?: string;
+    currentPassword?: string;
+    newPassword?: string;
+}
+
+/**
+ * Extract userErrors from mutation result and convert to ValidationError if present
+ */
+export declare function extractUserErrors<T extends {
+    userErrors?: Array<{
+        field: string | null;
+        message: string;
+    }>;
+}>(data: T, fieldName: keyof T): Result<Exclude<T[keyof T], undefined>, ValidationError>;
+
+export declare 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;
+}
+
+export declare interface GraphQLClient {
+    query<T>(request: GraphQLRequest, options?: {
+        cache?: boolean;
+    }): Promise<Result<T, StorefrontError>>;
+    mutate<T>(request: GraphQLRequest): Promise<Result<T, StorefrontError>>;
+}
+
+/**
+ * GraphQL error - unexpected GraphQL errors
+ */
+export 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;
+    });
+}
+
+export declare interface GraphQLRequest {
+    query: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}
+
+export declare interface GraphQLResponse<T = unknown> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        path?: readonly (string | number)[];
+    }>;
+}
+
+/**
+ * Network error - fetch failed, connection issues
+ */
+export declare class NetworkError extends StorefrontError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+
+/**
+ * Not found error - resource doesn't exist
+ */
+export declare class NotFoundError extends StorefrontError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+
+export declare 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;
+}
+
+export declare interface OrderItem {
+    id: string;
+    productTitle: string;
+    variantTitle: string | null;
+    sku: string | null;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+
+export declare interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor: string | null;
+    endCursor: string | null;
+}
+
+export declare interface PaginatedResult<T> {
+    items: T[];
+    pageInfo: PageInfo;
+}
+
+export declare interface PaymentInstructions {
+    bankAccount: string;
+    recipientName: string;
+    referenceNumber: string;
+    ipsQrCodeBase64: string;
+    expiresAt: string;
+}
+
+export declare interface PaymentsOperations {
+    getAvailableMethods(): Promise<Result<AvailablePaymentMethod[], StorefrontError>>;
+}
+
+declare type PresetEventProperties = {
+    page_view: {};
+    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;
+    };
+};
+
+declare type PresetPropertiesByName<T extends AnalyticsPresetEventName> = PresetEventProperties[T];
+
+export declare 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[];
+}
+
+export declare 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;
+}
+
+export declare interface ProductImage {
+    id: string;
+    url: string;
+    altText: string | null;
+    position: number;
+}
+
+export declare interface ProductOption {
+    id: string;
+    name: string;
+    position: number;
+    values: ProductOptionValue[];
+}
+
+export declare interface ProductOptionValue {
+    id: string;
+    value: string;
+    position: number;
+}
+
+export declare interface ProductsListOptions {
+    first?: number;
+    after?: string;
+    filter?: ProductFilter;
+    sort?: ProductSortKey;
+}
+
+export declare interface ProductsOperations {
+    list(options?: ProductsListOptions): Promise<Result<PaginatedResult<Product>, StorefrontError>>;
+    get(idOrHandle: string): Promise<Result<Product, StorefrontError>>;
+    getByHandles(handles: string[]): Promise<Result<(Product | null)[], StorefrontError>>;
+}
+
+export declare type ProductSortKey = "CREATED_AT" | "TITLE" | "PRICE_ASC" | "PRICE_DESC" | "BEST_SELLING";
+
+export declare 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[];
+}
+
+export declare interface QuantityPricingTier {
+    minQuantity: number;
+    price: number;
+}
+
+export declare interface QueryCache {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttl: number): void;
+    clear(): void;
+}
+
+export declare interface ShippingOperations {
+    getAvailableRates(): Promise<Result<ShippingRate[], StorefrontError>>;
+}
+
+export declare interface ShippingRate {
+    id: string;
+    name: string;
+    price: number;
+    minOrderAmount: number | null;
+    estimatedDaysMin: number | null;
+    estimatedDaysMax: number | null;
+    isFree: boolean;
+}
+
+export declare interface SocialLinks {
+    instagram?: string;
+    facebook?: string;
+    tiktok?: string;
+    twitter?: string;
+}
+
+/**
+ * State error - invalid cart state transition
+ */
+export declare class StateError extends StorefrontError {
+    readonly state: string;
+    constructor(message: string, state: string, options?: {
+        cause?: Error;
+    });
+}
+
+/**
+ * Re-export generated GraphQL types once codegen runs
+ * For now, define placeholder types that will be replaced
+ */
+export declare interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+
+export declare interface Store {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    currency: string;
+    timezone: string;
+    logoUrl: string | null;
+    contactPhone: string | null;
+    socialLinks: SocialLinks;
+}
+
+export declare interface StorefrontClient {
+    readonly config: StorefrontClientConfig;
+    readonly cache: CacheHelpers;
+    readonly products: ProductsOperations;
+    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;
+    /**
+     * 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;
+}
+
+export declare interface StorefrontClientConfig {
+    endpoint: string;
+    apiKey: string;
+    storage?: StorageAdapter;
+    cacheTTL?: number;
+    storeSlug?: string;
+}
+
+/**
+ * Base class for all Storefront SDK errors
+ */
+export declare class StorefrontError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: {
+        cause?: Error;
+    });
+}
+
+export declare type StorefrontResult<T> = Result<T, StorefrontError>;
+
+export declare interface Tag {
+    id: string;
+    name: string;
+}
+
+/**
+ * Validation error - userErrors from mutations
+ */
+export 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;
+    });
+}
+
+export declare type WeightUnit = "g" | "kg" | "lb" | "oz";
+
+export { }