@putiikkipalvelu/storefront-sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,270 +1,2382 @@
 /**
- * Store configuration types for the Storefront API
+ * Store Configuration Types
+ *
+ * Types for the store config endpoint response.
  */
+/**
+ * Complete store configuration returned by the API.
+ * Includes business info, SEO settings, payments, campaigns, and feature flags.
+ */
+interface StoreConfig {
+    store: StoreInfo;
+    seo: StoreSeo;
+    payments: PaymentConfig;
+    campaigns: Campaign[];
+    features: FeatureFlags;
+}
 /**
  * Store business information
  */
 interface StoreInfo {
+    /** Unique store identifier */
     id: string;
+    /** Store display name */
     name: string;
+    /** Contact email */
     email: string;
+    /** Contact phone number */
     phone: string;
+    /** Street address */
     address: string;
+    /** City */
     city: string;
+    /** Postal/ZIP code */
     postalCode: string;
+    /** Country code (e.g., "FI") */
     country: string;
+    /** Currency code (e.g., "EUR") */
     currency: string;
+    /** Currency symbol (e.g., "€") */
     currencySymbol: string;
+    /** Default VAT rate as percentage (e.g., 25.5) */
     defaultVatRate: number;
+    /** Business/VAT ID */
     businessId: string;
+    /** Store logo URL */
     logoUrl: string | null;
 }
 /**
  * Store SEO and social media configuration
  */
 interface StoreSeo {
+    /** SEO meta title */
     seoTitle: string | null;
+    /** SEO meta description */
     seoDescription: string | null;
+    /** Store domain URL */
     domain: string | null;
+    /** Open Graph image URL */
     openGraphImageUrl: string | null;
+    /** Twitter card image URL */
     twitterImageUrl: string | null;
+    /** Instagram profile URL */
     instagramUrl: string | null;
+    /** Facebook page URL */
     facebookUrl: string | null;
+    /** Price range indicator (e.g., "€€") */
     priceRange: string | null;
+    /** Business type description */
     businessType: string | null;
 }
 /**
  * Payment configuration
  */
 interface PaymentConfig {
+    /** Available payment methods (e.g., ["stripe", "paytrail"]) */
     methods: string[];
+    /** Default VAT rate */
     defaultVatRate: number;
 }
 /**
  * Feature flags for the store
  */
 interface FeatureFlags {
+    /** Whether wishlist functionality is enabled */
     wishlistEnabled: boolean;
+    /** Whether guest checkout is allowed */
     guestCheckoutEnabled: boolean;
+    /** Whether newsletter signup is enabled */
     newsletterEnabled: boolean;
+    /** Whether product reviews are enabled */
     reviewsEnabled: boolean;
 }
+/** Campaign type */
+type CampaignType = "FREE_SHIPPING" | "BUY_X_PAY_Y";
 /**
- * Shipment method for free shipping campaigns
+ * Store campaign (promotion)
  */
-interface ShipmentMethod {
+interface Campaign {
+    /** Unique campaign identifier */
     id: string;
+    /** Store ID this campaign belongs to */
     storeId: string;
+    /** Campaign display name */
     name: string;
+    /** Campaign description */
     description: string | null;
-    price: number;
-    active: boolean;
-    min_estimate_delivery_days: number | null;
-    max_estimate_delivery_days: number | null;
+    /** Type of campaign */
+    type: CampaignType;
+    /** Campaign start date (ISO 8601) */
+    startDate: string;
+    /** Campaign end date (ISO 8601), null = no end */
+    endDate: string | null;
+    /** Whether campaign is currently active */
+    isActive: boolean;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last update timestamp (ISO 8601) */
+    updatedAt: string;
+    /** Free shipping campaign details (if type is FREE_SHIPPING) */
+    FreeShippingCampaign: FreeShippingCampaign | null;
+    /** Buy X Pay Y campaign details (if type is BUY_X_PAY_Y) */
+    BuyXPayYCampaign: BuyXPayYCampaign | null;
 }
 /**
  * Free shipping campaign details
  */
 interface FreeShippingCampaign {
+    /** Unique identifier */
     id: string;
+    /** Parent campaign ID */
     campaignId: string;
+    /** Minimum spend in cents to qualify for free shipping */
     minimumSpend: number;
+    /** Shipping methods eligible for free shipping */
     shipmentMethods: ShipmentMethod[];
 }
 /**
- * Category reference for Buy X Pay Y campaigns
- */
-interface CategoryReference {
-    id: string;
-    name?: string;
-    slug?: string;
-}
-/**
- * Buy X Pay Y campaign details
+ * Buy X Pay Y campaign details (e.g., "Buy 3, Pay 2")
  */
 interface BuyXPayYCampaign {
+    /** Unique identifier */
     id: string;
+    /** Parent campaign ID */
     campaignId: string;
+    /** Number of items customer must buy */
     buyQuantity: number;
+    /** Number of items customer pays for */
     payQuantity: number;
+    /** Categories this campaign applies to */
     applicableCategories: CategoryReference[];
 }
 /**
- * Campaign type enum
+ * Shipit shipping method details
+ * Represents a shipping service synced from the Shipit API
  */
-type CampaignType = "FREE_SHIPPING" | "BUY_X_PAY_Y";
+interface ShipitShippingMethod {
+    /** Unique ID */
+    id: string;
+    /** Shipit service identifier */
+    serviceId: string;
+    /** Service name */
+    name: string;
+    /** Carrier name (e.g., "Posti", "Matkahuolto") */
+    carrier: string;
+    /** Carrier logo URL */
+    logo: string;
+    /** Whether pickup is included */
+    pickUpIncluded: boolean;
+    /** Whether home delivery is available */
+    homeDelivery: boolean;
+    /** Whether worldwide delivery is available */
+    worldwideDelivery: boolean;
+    /** Whether fragile handling is available */
+    fragile: boolean;
+    /** Whether domestic deliveries are available */
+    domesticDeliveries: boolean;
+    /** Additional information */
+    information: string | null;
+    /** Service description */
+    description: string;
+    /** Package height in cm */
+    height: number;
+    /** Package length in cm */
+    length: number;
+    /** Package width in cm */
+    width: number;
+    /** Package weight in kg */
+    weight: number;
+    /** Service type */
+    type: string;
+    /** Shipit price in cents */
+    price: number;
+    /** Whether pickup point selection is available */
+    pickupPoint: boolean;
+    /** Whether only parcel locker delivery is available */
+    onlyParchelLocker: boolean;
+    /** Reference to parent shipment method */
+    shipmentMethodId: string;
+    /** Created timestamp */
+    createdAt: string;
+    /** Updated timestamp */
+    updatedAt: string;
+}
 /**
- * Store campaign
- * Note: Date fields can be Date objects (from Prisma) or strings (after JSON serialization)
+ * Shipping method
  */
-interface Campaign {
+interface ShipmentMethod {
+    /** Unique identifier */
     id: string;
-    storeId: string;
+    /** Shipping method name (e.g., "Posti - Paketti") */
     name: string;
+    /** Description */
     description: string | null;
-    type: CampaignType;
-    startDate: Date | string;
-    endDate: Date | string | null;
-    isActive: boolean;
-    createdAt: Date | string;
-    updatedAt: Date | string;
-    FreeShippingCampaign?: FreeShippingCampaign | null;
-    BuyXPayYCampaign?: BuyXPayYCampaign | null;
+    /** Price in cents */
+    price: number;
+    /** Whether this method is active */
+    active: boolean;
+    /** Minimum estimated delivery days */
+    min_estimate_delivery_days: number | null;
+    /** Maximum estimated delivery days */
+    max_estimate_delivery_days: number | null;
+    /** Associated Shipit method (if using Shipit integration) */
+    shipitMethod?: ShipitShippingMethod | null;
 }
 /**
- * Complete store configuration returned by store.getConfig()
+ * Category reference (lightweight, used in relationships)
  */
-interface StoreConfig {
-    store: StoreInfo;
-    seo: StoreSeo;
-    payments: PaymentConfig;
-    campaigns: Campaign[];
-    features: FeatureFlags;
+interface CategoryReference {
+    /** Unique identifier */
+    id: string;
+    /** Category name */
+    name: string;
+    /** URL-friendly slug */
+    slug: string;
+    /** Parent category ID (null if root category) */
+    parentId: string | null;
 }
 
 /**
- * SDK Configuration options
+ * Product Types
+ *
+ * Types for product-related API endpoints.
  */
-interface StorefrontClientConfig {
-    /**
-     * Your store's API key (required)
-     */
-    apiKey: string;
-    /**
-     * Base URL for the Storefront API
-     */
-    baseUrl: string;
-    /**
-     * Request timeout in milliseconds
-     * @default 30000
-     */
-    timeout?: number;
+
+/**
+ * Product variation option (e.g., Size: Large)
+ */
+interface VariationOption {
+    /** Option value (e.g., "Large", "Red") */
+    value: string;
+    /** Option type information */
+    optionType: {
+        /** Option type name (e.g., "Size", "Color") */
+        name: string;
+    };
 }
 /**
- * Base options that can be passed to any API method.
- * Framework-agnostic - works with Next.js, Nuxt, or plain fetch.
+ * Product variation for listings (minimal fields)
  */
-interface FetchOptions {
-    /**
-     * AbortSignal for cancelling requests
-     */
-    signal?: AbortSignal;
-    /**
-     * Additional headers to send with the request
-     */
-    headers?: Record<string, string>;
-    /**
-     * Standard fetch cache mode
-     */
-    cache?: RequestCache;
-    /**
-     * Framework-specific options passthrough.
-     * These are spread directly to the underlying fetch call.
-     *
-     * @example Next.js caching
-     * ```typescript
-     * await client.store.getConfig({
-     *   next: { revalidate: 60, tags: ['store-config'] }
-     * });
-     * ```
-     *
-     * @example Standard fetch
-     * ```typescript
-     * await client.store.getConfig({
-     *   cache: 'force-cache'
-     * });
-     * ```
-     */
-    [key: string]: unknown;
+interface ProductVariationListing {
+    /** Unique variation identifier */
+    id: string;
+    /** Variation price in cents */
+    price: number;
+    /** Sale price in cents (null if not on sale) */
+    salePrice: number | null;
+    /** Sale discount percentage as string (null if not on sale) */
+    salePercent: string | null;
+    /** Sale start date (ISO 8601), null = immediate */
+    saleStartDate: string | null;
+    /** Sale end date (ISO 8601), null = no end */
+    saleEndDate: string | null;
+}
+/**
+ * Full product variation (for product detail page)
+ */
+interface ProductVariation extends ProductVariationListing {
+    /** Available quantity (null = unlimited) */
+    quantity: number | null;
+    /** Stock keeping unit */
+    sku: string | null;
+    /** Variation-specific images */
+    images: string[];
+    /** Variation-specific description */
+    description: string | null;
+    /** Whether variation is visible on store */
+    showOnStore: boolean;
+    /** Variation options (size, color, etc.) */
+    options: VariationOption[];
+}
+/**
+ * Product for listing (cards, grids)
+ * Used by: /latest-products, /sorted-products, /filtered-products
+ */
+interface Product {
+    /** Unique product identifier */
+    id: string;
+    /** Product display name */
+    name: string;
+    /** URL-friendly slug */
+    slug: string;
+    /** Product description */
+    description: string;
+    /** Base price in cents */
+    price: number;
+    /** Product images (URLs) */
+    images: string[];
+    /** Available quantity (null = unlimited) */
+    quantity: number | null;
+    /** Sale price in cents (null if not on sale) */
+    salePrice: number | null;
+    /** Sale discount percentage as string (null if not on sale) */
+    salePercent: string | null;
+    /** Sale start date (ISO 8601), null = immediate */
+    saleStartDate: string | null;
+    /** Sale end date (ISO 8601), null = no end */
+    saleEndDate: string | null;
+    /** Product variations (minimal fields for listing) */
+    variations: ProductVariationListing[];
+}
+/**
+ * Full product detail (single product page)
+ * Used by: /product/{slug}
+ */
+interface ProductDetail extends Omit<Product, "variations"> {
+    /** Stock keeping unit */
+    sku: string | null;
+    /** SEO meta title */
+    metaTitle: string | null;
+    /** SEO meta description */
+    metaDescription: string | null;
+    /** Product categories */
+    categories: CategoryReference[];
+    /** Full product variations */
+    variations: ProductVariation[];
+}
+/**
+ * Response from /sorted-products and /filtered-products
+ */
+interface ProductListResponse {
+    /** Category/collection name */
+    name: string;
+    /** Products in the list */
+    products: Product[];
+    /** Total count for pagination (only in sorted-products) */
+    totalCount?: number;
+}
+/**
+ * Response from /products-count
+ */
+interface ProductCountResponse {
+    /** Number of products */
+    count: number;
+}
+/**
+ * Sort options for product listing
+ */
+type ProductSortOption = "newest" | "price_asc" | "price_desc" | "popularity";
+/**
+ * Parameters for sorted/filtered products
+ */
+interface ProductListParams {
+    /** Category slugs to filter by (omit for all products) */
+    slugs?: string[];
+    /** Page number (1-based, default: 1) */
+    page?: number;
+    /** Products per page (default: 12, max: 100) */
+    pageSize?: number;
+    /** Sort order */
+    sort?: ProductSortOption;
 }
 
-interface FetcherConfig {
-    apiKey: string;
-    baseUrl: string;
-    timeout?: number;
+/**
+ * Category Types
+ *
+ * Types for category-related API endpoints.
+ */
+/**
+ * Category with nested children.
+ * Used by: /categories, /categories/{slug}
+ */
+interface Category {
+    /** Unique category identifier */
+    id: string;
+    /** Category display name */
+    name: string;
+    /** URL-friendly slug */
+    slug: string;
+    /** Store ID this category belongs to */
+    storeId: string;
+    /** Parent category ID (null if root category) */
+    parentId: string | null;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Child categories (recursive) */
+    children: Category[];
 }
-interface RequestOptions extends FetchOptions {
-    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-    body?: unknown;
-    params?: Record<string, string | number | boolean | undefined>;
+/**
+ * Response from /categories/{slug}
+ */
+interface CategoryResponse {
+    /** The category data */
+    category: Category;
 }
+
 /**
- * Fetcher instance type returned by createFetcher
+ * Cart Types
+ *
+ * Types for cart-related API endpoints.
  */
-type Fetcher = ReturnType<typeof createFetcher>;
+
 /**
- * Create a configured fetcher instance for making API requests
+ * A single item in the shopping cart
  */
-declare function createFetcher(config: FetcherConfig): {
-    request: <T>(endpoint: string, options?: RequestOptions) => Promise<T>;
-};
+interface CartItem {
+    /** Full product details */
+    product: ProductDetail;
+    /** Quantity of this item in the cart */
+    cartQuantity: number;
+    /** Selected variation (if product has variations) */
+    variation?: ProductVariation;
+}
+/**
+ * Response from GET /cart, POST /cart, PATCH /cart, DELETE /cart
+ */
+interface CartResponse {
+    /** Items currently in the cart */
+    items: CartItem[];
+    /** Cart ID for guest users (undefined for logged-in users) */
+    cartId?: string;
+}
+/**
+ * Changes detected during cart validation
+ */
+interface CartValidationChanges {
+    /** Number of items removed (product deleted or out of stock) */
+    removedItems: number;
+    /** Number of items with adjusted quantity (insufficient stock) */
+    quantityAdjusted: number;
+    /** Number of items with changed price */
+    priceChanged: number;
+}
+/**
+ * Response from GET /cart/validate
+ */
+interface CartValidationResponse {
+    /** Validated cart items (with auto-fixed quantities/prices) */
+    items: CartItem[];
+    /** Whether any changes were made during validation */
+    hasChanges: boolean;
+    /** Details about what changed */
+    changes: CartValidationChanges;
+}
+/**
+ * Options for cart operations that require session context
+ */
+interface CartSessionOptions {
+    /** Cart ID for guest users (from cookie or local storage) */
+    cartId?: string;
+    /** Session ID for logged-in users (from auth cookie) */
+    sessionId?: string;
+}
+/**
+ * Parameters for adding an item to cart
+ */
+interface AddToCartParams extends CartSessionOptions {
+    /** Product ID to add */
+    productId: string;
+    /** Variation ID (required if product has variations) */
+    variationId?: string;
+    /** Quantity to add (default: 1) */
+    quantity?: number;
+}
+/**
+ * Parameters for updating cart item quantity
+ */
+interface UpdateCartQuantityParams extends CartSessionOptions {
+    /** Product ID to update */
+    productId: string;
+    /** Variation ID (if applicable) */
+    variationId?: string;
+    /** Quantity change: positive to add, negative to subtract */
+    delta: number;
+}
+/**
+ * Parameters for removing an item from cart
+ */
+interface RemoveFromCartParams extends CartSessionOptions {
+    /** Product ID to remove */
+    productId: string;
+    /** Variation ID (if applicable) */
+    variationId?: string;
+}
+/**
+ * Price information for a product or variation
+ */
+interface PriceInfo {
+    /** Current effective price in cents (sale price if on sale, otherwise regular) */
+    effectivePrice: number;
+    /** Original/regular price in cents */
+    originalPrice: number;
+    /** Whether the item is currently on sale */
+    isOnSale: boolean;
+    /** Sale percentage (e.g., "-20%") if applicable */
+    salePercent: string | null;
+}
+/**
+ * A cart item with calculated paid and free quantities (for Buy X Pay Y campaigns)
+ */
+interface CalculatedCartItem {
+    /** Original cart item */
+    item: CartItem;
+    /** Number of units the customer pays for */
+    paidQuantity: number;
+    /** Number of units that are free (from campaign) */
+    freeQuantity: number;
+    /** Total quantity in cart */
+    totalQuantity: number;
+}
+/**
+ * Free shipping eligibility status
+ */
+interface FreeShippingStatus {
+    /** Whether the cart qualifies for free shipping */
+    isEligible: boolean;
+    /** Minimum spend required for free shipping (in cents) */
+    minimumSpend: number;
+    /** Amount remaining to qualify for free shipping (in cents) */
+    remainingAmount: number;
+    /** Name of the free shipping campaign */
+    campaignName?: string;
+    /** IDs of shipment methods eligible for free shipping (when isEligible is true) */
+    eligibleShipmentMethodIds?: string[];
+}
+/**
+ * Result of cart calculation with campaigns applied
+ */
+interface CartCalculationResult {
+    /** Cart items with paid/free quantities calculated */
+    calculatedItems: CalculatedCartItem[];
+    /** Final cart total after discounts (in cents) */
+    cartTotal: number;
+    /** Original cart total before discounts (in cents) */
+    originalTotal: number;
+    /** Total savings from campaigns (in cents) */
+    totalSavings: number;
+    /** Free shipping eligibility status */
+    freeShipping: FreeShippingStatus;
+}
 
 /**
- * Store resource for fetching store configuration
+ * Shipping Types
+ *
+ * Types for shipment methods and pickup locations.
+ * ShipmentMethod and ShipitShippingMethod are re-exported from storeconfig.
  */
-declare function createStoreResource(fetcher: Fetcher): {
-    /**
-     * Get the complete store configuration including settings, SEO, payments, campaigns, and features.
-     *
-     * @example Basic usage
-     * ```typescript
-     * const config = await client.store.getConfig();
-     * console.log(config.store.name);
-     * console.log(config.seo.seoTitle);
-     * console.log(config.campaigns);
-     * ```
-     *
-     * @example Next.js - with caching
-     * ```typescript
-     * const config = await client.store.getConfig({
-     *   next: { revalidate: 300, tags: ['store-config'] }
-     * });
-     * ```
-     *
-     * @example Nuxt - wrap with useAsyncData
-     * ```typescript
-     * const { data: config } = await useAsyncData(
-     *   'store-config',
-     *   () => client.store.getConfig()
-     * );
-     * ```
-     *
-     * @example Standard fetch caching
-     * ```typescript
-     * const config = await client.store.getConfig({
-     *   cache: 'force-cache'
-     * });
-     * ```
-     */
-    getConfig(options?: FetchOptions): Promise<StoreConfig>;
-};
+
 /**
- * Type for the store resource
+ * Opening hours for a pickup location
  */
-type StoreResource = ReturnType<typeof createStoreResource>;
+interface PickupLocationOpeningHours {
+    monday: string[];
+    tuesday: string[];
+    wednesday: string[];
+    thursday: string[];
+    friday: string[];
+    saturday: string[];
+    sunday: string[];
+    exceptions: string[];
+}
+/**
+ * A pickup location (parcel locker, pickup point, etc.)
+ * Returned from Shipit API with merchant pricing added
+ */
+interface PickupLocation {
+    /** Unique location ID */
+    id: string;
+    /** Location name */
+    name: string;
+    /** Street address */
+    address1: string;
+    /** Postal code */
+    zipcode: string;
+    /** City */
+    city: string;
+    /** Country code (e.g., "FI") */
+    countryCode: string;
+    /** Shipit service ID */
+    serviceId: string;
+    /** Carrier name */
+    carrier: string;
+    /** Shipit price in cents (may be null) */
+    price: number | null;
+    /** Merchant's price in cents (from store settings) */
+    merchantPrice: number | null;
+    /** Carrier logo URL */
+    carrierLogo: string;
+    /** Structured opening hours */
+    openingHours: PickupLocationOpeningHours | null;
+    /** Raw opening hours string */
+    openingHoursRaw: string | null;
+    /** GPS latitude */
+    latitude: number;
+    /** GPS longitude */
+    longitude: number;
+    /** Distance from postal code in meters */
+    distanceInMeters: number;
+    /** Distance from postal code in kilometers */
+    distanceInKilometers: number;
+    /** Additional metadata */
+    metadata: unknown | null;
+}
+/**
+ * Response from GET /shipment-methods
+ */
+interface ShipmentMethodsResponse {
+    /** Available shipment methods */
+    shipmentMethods: ShipmentMethod[];
+}
+/**
+ * Response from GET /shipment-methods/[postalCode]
+ * Includes pickup locations near the postal code
+ */
+interface ShipmentMethodsWithLocationsResponse {
+    /** Available shipment methods */
+    shipmentMethods: ShipmentMethod[];
+    /** Pickup locations near the postal code with merchant pricing */
+    pricedLocations: PickupLocation[];
+}
 
 /**
- * The Storefront API client
+ * Customer Types
+ *
+ * Types for customer authentication and account management API endpoints.
  */
-interface StorefrontClient {
-    /**
-     * The configured API key (masked for security)
-     */
-    readonly apiKey: string;
-    /**
-     * The base URL for API requests
-     */
-    readonly baseUrl: string;
-    /**
-     * Store configuration resource
-     */
-    readonly store: StoreResource;
+/**
+ * Basic customer information returned from most customer endpoints
+ */
+interface Customer {
+    /** Unique customer ID */
+    id: string;
+    /** Customer's first name */
+    firstName: string;
+    /** Customer's last name */
+    lastName: string;
+    /** Customer's email address */
+    email: string;
 }
 /**
- * Create a new Storefront API client
+ * Extended customer information returned after registration
+ */
+interface CustomerWithVerification extends Customer {
+    /** Account creation timestamp */
+    createdAt: string;
+    /** Email verification token (for sending verification emails) */
+    emailVerificationToken: string;
+    /** Token expiration timestamp */
+    emailVerificationExpiresAt: string;
+}
+/**
+ * Customer information returned after login
+ */
+interface CustomerWithEmailStatus extends Customer {
+    /** Email verification timestamp (null if not verified) */
+    emailVerified: string | null;
+    /** Account creation timestamp */
+    createdAt: string;
+}
+/**
+ * Data required to register a new customer account
+ */
+interface RegisterData {
+    /** Customer's first name */
+    firstName: string;
+    /** Customer's last name */
+    lastName: string;
+    /** Customer's email address */
+    email: string;
+    /** Password (minimum 8 characters) */
+    password: string;
+}
+/**
+ * Options for the login method
+ */
+interface LoginOptions {
+    /** Guest cart ID to merge into user's cart after login */
+    cartId?: string;
+}
+/**
+ * Response from successful registration
+ */
+interface RegisterResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Created customer with verification token */
+    customer: CustomerWithVerification;
+    /** Success message */
+    message: string;
+}
+/**
+ * Response from successful login
+ */
+interface LoginResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Authenticated customer data */
+    customer: CustomerWithEmailStatus;
+    /** Success message */
+    message: string;
+    /** Session token for authenticated requests */
+    sessionId: string;
+    /** Session expiration timestamp (ISO 8601) */
+    expiresAt: string;
+}
+/**
+ * Response when login fails due to unverified email
+ */
+interface LoginVerificationRequiredResponse {
+    /** Error message */
+    error: string;
+    /** Indicates email verification is required */
+    requiresVerification: true;
+    /** Customer ID for resending verification email */
+    customerId: string;
+}
+/**
+ * Response from successful logout
+ */
+interface LogoutResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Success message */
+    message: string;
+    /** New guest cart ID (if user had items in cart) */
+    cartId?: string;
+}
+/**
+ * Response from get user endpoint
+ */
+interface GetUserResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Current authenticated customer */
+    customer: Customer;
+}
+/**
+ * Response from successful email verification
+ */
+interface VerifyEmailResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Success message */
+    message: string;
+}
+/**
+ * Response from resend verification email
+ */
+interface ResendVerificationResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Updated customer with new verification token */
+    customer: CustomerWithVerification;
+    /** Success message */
+    message: string;
+}
+/**
+ * Data for updating customer profile
+ */
+interface UpdateProfileData {
+    /** Updated first name */
+    firstName?: string;
+    /** Updated last name */
+    lastName?: string;
+    /** Updated email address */
+    email?: string;
+}
+/**
+ * Extended customer info returned after profile update
+ */
+interface CustomerWithCreatedAt extends Customer {
+    /** Account creation timestamp */
+    createdAt: string;
+}
+/**
+ * Response from updating profile
+ */
+interface UpdateProfileResponse {
+    /** Success message */
+    message: string;
+    /** Updated customer data */
+    customer: CustomerWithCreatedAt;
+}
+/**
+ * Response from deleting account
+ */
+interface DeleteAccountResponse {
+    /** Success message */
+    message: string;
+}
+/**
+ * Product information attached to order line item
+ */
+interface OrderProductInfo {
+    /** Product or variation ID */
+    id: string;
+    /** Product name */
+    name: string;
+    /** Product images */
+    images: string[];
+    /** Product slug (null for shipping items) */
+    slug: string | null;
+    /** Variation ID if this is a variation */
+    variationId?: string;
+    /** Variation option name (e.g., "Size") */
+    optionName?: string;
+    /** Variation option value (e.g., "Large") */
+    optionValue?: string;
+    /** True if this is a shipping item */
+    isShipping?: boolean;
+    /** True if product is no longer available */
+    unavailable?: boolean;
+}
+/**
+ * A single line item in an order
+ */
+interface OrderLineItem {
+    /** Line item ID */
+    id: string;
+    /** Item type: PRODUCT, VARIATION, or SHIPPING */
+    itemType: "PRODUCT" | "VARIATION" | "SHIPPING";
+    /** Quantity ordered */
+    quantity: number;
+    /** Price per unit in cents */
+    price: number;
+    /** Total amount in cents */
+    totalAmount: number;
+    /** Product or variation code (ID) */
+    productCode: string;
+    /** Item name */
+    name: string;
+    /** VAT rate percentage */
+    vatRate: number;
+    /** Product information */
+    product: OrderProductInfo;
+}
+/**
+ * Shipment method info attached to order
+ */
+interface OrderShipmentMethod {
+    /** Shipment method name */
+    name: string;
+    /** Shipping price in cents */
+    price: number;
+    /** VAT rate percentage */
+    vatRate: number;
+    /** Carrier logo URL */
+    logo: string | null;
+}
+/**
+ * Order status values
+ */
+type OrderStatus = "PENDING" | "PROCESSING" | "SHIPPED" | "DELIVERED" | "CANCELLED" | "REFUNDED";
+/**
+ * A customer order
+ */
+interface CustomerOrder {
+    /** Order ID */
+    id: string;
+    /** Human-readable order number */
+    orderNumber: string;
+    /** Total order amount in cents */
+    totalAmount: number;
+    /** Order status */
+    status: OrderStatus;
+    /** Order creation timestamp */
+    createdAt: string;
+    /** Order line items with product info */
+    OrderLineItems: OrderLineItem[];
+    /** Shipment method details */
+    orderShipmentMethod: OrderShipmentMethod | null;
+}
+/**
+ * Response from getting customer orders
+ */
+interface GetOrdersResponse {
+    /** Whether the operation was successful */
+    success: true;
+    /** Customer's orders */
+    orders: CustomerOrder[];
+}
+/**
+ * Variation option in wishlist item
+ */
+interface WishlistVariationOption {
+    /** Option ID */
+    id: string;
+    /** Option value (e.g., "Large", "Red") */
+    value: string;
+    /** Option type details */
+    optionType: {
+        /** Option type ID */
+        id: string;
+        /** Option type name (e.g., "Size", "Color") */
+        name: string;
+    };
+}
+/**
+ * Variation details in wishlist item
+ */
+interface WishlistVariation {
+    /** Variation ID */
+    id: string;
+    /** Variation SKU */
+    sku: string | null;
+    /** Variation price in cents */
+    price: number;
+    /** Sale price in cents */
+    salePrice: number | null;
+    /** Quantity in stock */
+    quantity: number;
+    /** Variation images */
+    images: string[];
+    /** Variation options (size, color, etc.) */
+    options: WishlistVariationOption[];
+}
+/**
+ * Product details in wishlist item
+ */
+interface WishlistProduct {
+    /** Product ID */
+    id: string;
+    /** Product name */
+    name: string;
+    /** Product slug */
+    slug: string;
+    /** Product description */
+    description: string | null;
+    /** Product images */
+    images: string[];
+    /** Product price in cents */
+    price: number;
+    /** Sale price in cents */
+    salePrice: number | null;
+    /** Sale percentage (e.g., "-20%") */
+    salePercent: string | null;
+    /** Sale start date */
+    saleStartDate: string | null;
+    /** Sale end date */
+    saleEndDate: string | null;
+    /** Quantity in stock */
+    quantity: number;
+    /** Product SKU */
+    sku: string | null;
+    /** Product status */
+    status: string;
+}
+/**
+ * A wishlist item with product and optional variation details
+ */
+interface WishlistItem {
+    /** Wishlist item ID */
+    id: string;
+    /** Customer ID */
+    customerId: string;
+    /** Product ID */
+    productId: string;
+    /** Variation ID (if applicable) */
+    variationId: string | null;
+    /** When the item was added to wishlist */
+    createdAt: string;
+    /** Product details */
+    product: WishlistProduct;
+    /** Variation details (if applicable) */
+    variation: WishlistVariation | null;
+}
+/**
+ * Response from getting wishlist
+ */
+interface WishlistResponse {
+    /** Wishlist items */
+    items: WishlistItem[];
+}
+/**
+ * Response from adding item to wishlist
+ */
+interface AddToWishlistResponse {
+    /** Success message */
+    message: string;
+}
+/**
+ * Response from removing item from wishlist
+ */
+interface RemoveFromWishlistResponse {
+    /** Success message */
+    message: string;
+}
+
+/**
+ * Order Types
+ *
+ * Types for fetching order details from the Storefront API.
+ * These types represent the raw order data returned by GET /order/{id}.
+ *
+ * Note: These differ from CustomerOrder types in customer.ts which are
+ * transformed for customer order history display.
+ */
+/**
+ * Item type for order line items
+ */
+type ConfirmationItemType = "PRODUCT" | "VARIATION" | "SHIPPING";
+/**
+ * A single line item in an order confirmation
+ * Represents raw data as stored in the database
+ */
+interface ConfirmationOrderLineItem {
+    /** Unique line item ID */
+    id: string;
+    /** Parent order ID */
+    orderId: string;
+    /** Type of item: PRODUCT, VARIATION, or SHIPPING */
+    itemType: ConfirmationItemType;
+    /** Quantity ordered */
+    quantity: number;
+    /** Price per unit in cents */
+    price: number;
+    /** Total amount in cents (price * quantity) */
+    totalAmount: number;
+    /** Product or variation code (ID reference) */
+    productCode: string;
+    /** Display name of the item */
+    name: string;
+    /** VAT rate percentage */
+    vatRate: number;
+    /** Product images array */
+    images: string[];
+}
+/**
+ * Customer delivery information attached to an order
+ */
+interface ConfirmationOrderCustomerData {
+    /** Customer data record ID */
+    id: string;
+    /** Customer's first name */
+    firstName: string;
+    /** Customer's last name */
+    lastName: string;
+    /** Customer's email address */
+    email: string;
+    /** Customer's phone number */
+    phone: string | null;
+    /** Delivery street address */
+    address: string;
+    /** Delivery city */
+    city: string;
+    /** Delivery postal code */
+    postalCode: string;
+}
+/**
+ * Shipment method information attached to an order
+ * Includes tracking information when available
+ */
+interface ConfirmationOrderShipmentMethod {
+    /** Shipment method record ID */
+    id: string;
+    /** Carrier service ID (for Shipit integration) */
+    serviceId: string | null;
+    /** Shipment method display name */
+    name: string;
+    /** Description of the shipment method */
+    description: string | null;
+    /** Carrier logo URL */
+    logo: string | null;
+    /** Shipping price in cents */
+    price: number;
+    /** Parent order ID */
+    orderId: string;
+    /** VAT rate percentage */
+    vatRate: number | null;
+    /** Tracking number (when shipped) */
+    trackingNumber: string | null;
+    /** Array of tracking URLs */
+    trackingUrls: string[];
+    /** Shipit shipment number */
+    shipmentNumber: string | null;
+    /** Freight document URLs */
+    freightDoc: string[];
+}
+/**
+ * Order status values
+ */
+type ConfirmationOrderStatus = "PENDING" | "PAID" | "SHIPPED" | "DELIVERED" | "CANCELLED" | "REFUNDED";
+/**
+ * Complete order information returned by GET /order/{id}
+ * Used for order confirmation pages and order detail views
+ */
+interface Order {
+    /** Unique order ID */
+    id: string;
+    /** Store ID this order belongs to */
+    storeId: string;
+    /** Order creation timestamp */
+    createdAt: string;
+    /** Total order amount in cents */
+    totalAmount: number;
+    /** Current order status */
+    status: ConfirmationOrderStatus;
+    /** Human-readable order number */
+    orderNumber: number;
+    /** Order line items (products, variations, shipping) */
+    OrderLineItems: ConfirmationOrderLineItem[];
+    /** Customer delivery information */
+    orderCustomerData: ConfirmationOrderCustomerData | null;
+    /** Shipment method with tracking info */
+    orderShipmentMethod: ConfirmationOrderShipmentMethod | null;
+}
+
+/**
+ * Checkout Types
+ *
+ * Types for payment checkout operations (Stripe and Paytrail)
+ */
+/**
+ * Customer data required for checkout
+ */
+interface CheckoutCustomerData {
+    /** Customer's first name */
+    first_name: string;
+    /** Customer's last name */
+    last_name: string;
+    /** Customer's email address */
+    email: string;
+    /** Street address */
+    address: string;
+    /** Postal code (5 digits for Finland) */
+    postal_code: string;
+    /** City name */
+    city: string;
+    /** Phone number */
+    phone: string;
+}
+/**
+ * Shipment method selection for checkout
+ */
+interface CheckoutShipmentMethod {
+    /** ID of the selected shipment method */
+    shipmentMethodId: string;
+    /** ID of pickup point (for pickup delivery methods) */
+    pickupId: string | null;
+}
+/**
+ * Parameters for creating a checkout session
+ */
+interface CheckoutParams {
+    /** Customer information */
+    customerData: CheckoutCustomerData;
+    /** Selected shipment method */
+    shipmentMethod: CheckoutShipmentMethod | null;
+    /** Unique order ID (generated by caller) */
+    orderId: string;
+    /** URL to redirect on successful payment */
+    successUrl: string;
+    /** URL to redirect on cancelled payment */
+    cancelUrl: string;
+}
+/**
+ * Response from Stripe checkout
+ */
+interface StripeCheckoutResponse {
+    /** URL to redirect user to Stripe checkout page */
+    url: string;
+}
+/**
+ * Payment provider from Paytrail
+ */
+interface PaytrailProvider {
+    /** Form submission URL for this provider */
+    url: string;
+    /** Provider icon URL */
+    icon: string;
+    /** Provider SVG icon */
+    svg: string;
+    /** Provider name (e.g., "Nordea", "OP") */
+    name: string;
+    /** Provider group (e.g., "bank", "mobile", "creditcard") */
+    group: string;
+    /** Provider ID */
+    id: string;
+    /** Form parameters to submit to provider */
+    parameters: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Payment method group from Paytrail
+ */
+interface PaytrailGroup {
+    /** Group ID (e.g., "bank", "mobile", "creditcard") */
+    id: string;
+    /** Group name */
+    name: string;
+    /** Group icon URL */
+    icon: string;
+    /** Group SVG icon */
+    svg: string;
+}
+/**
+ * Response from Paytrail checkout
+ */
+interface PaytrailCheckoutResponse {
+    /** Paytrail transaction ID */
+    transactionId: string;
+    /** Direct payment URL */
+    href: string;
+    /** Payment reference */
+    reference: string;
+    /** Terms and conditions URL */
+    terms: string;
+    /** Payment method groups */
+    groups: PaytrailGroup[];
+    /** Available payment providers */
+    providers: PaytrailProvider[];
+    /** Custom providers (if configured) */
+    customProviders: Record<string, unknown>;
+}
+/**
+ * Checkout error codes
+ */
+type CheckoutErrorCode = "EMPTY_CART" | "PRODUCT_NOT_FOUND" | "VARIATION_NOT_FOUND" | "INSUFFICIENT_INVENTORY" | "STORE_SETTINGS_NOT_FOUND" | "PAYMENT_FAILED";
+/**
+ * Error details for checkout failures
+ */
+interface CheckoutErrorDetails {
+    /** ID of the problematic product */
+    productId?: string;
+    /** ID of the problematic variation */
+    variationId?: string;
+    /** Available quantity (for inventory errors) */
+    availableQuantity?: number;
+    /** Requested quantity (for inventory errors) */
+    requestedQuantity?: number;
+    /** Additional error details */
+    [key: string]: unknown;
+}
+
+/**
+ * Putiikkipalvelu Storefront SDK Types
+ *
+ * These types define the shape of data returned by the Storefront API.
+ * Keep in sync with API implementation when making changes.
+ */
+
+/**
+ * SDK client configuration options
+ */
+interface StorefrontClientConfig {
+    /**
+     * Your store's API key (required)
+     * Get this from Dashboard > Settings > API Keys
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Storefront API
+     * @example "https://putiikkipalvelu.fi/api/storefront/v1"
+     */
+    baseUrl: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Options that can be passed to any API method.
+ * Framework-agnostic - works with Next.js, Nuxt, or plain fetch.
+ */
+interface FetchOptions {
+    /**
+     * AbortSignal for cancelling requests
+     */
+    signal?: AbortSignal;
+    /**
+     * Additional headers to send with the request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Standard fetch cache mode
+     */
+    cache?: RequestCache;
+    /**
+     * Framework-specific options passthrough.
+     * These are spread directly to the underlying fetch call.
+     *
+     * @example Next.js caching
+     * ```typescript
+     * await client.store.getConfig({
+     *   next: { revalidate: 60, tags: ['store-config'] }
+     * });
+     * ```
+     */
+    [key: string]: unknown;
+}
+
+interface FetcherConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout?: number;
+}
+interface RequestOptions extends FetchOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * Fetcher instance type returned by createFetcher
+ */
+type Fetcher = ReturnType<typeof createFetcher>;
+/**
+ * Create a configured fetcher instance for making API requests
+ */
+declare function createFetcher(config: FetcherConfig): {
+    request: <T>(endpoint: string, options?: RequestOptions) => Promise<T>;
+};
+
+/**
+ * Store resource for fetching store configuration
+ */
+declare function createStoreResource(fetcher: Fetcher): {
+    /**
+     * Get the complete store configuration including settings, SEO, payments, campaigns, and features.
+     *
+     * @example Basic usage
+     * ```typescript
+     * const config = await client.store.getConfig();
+     * console.log(config.store.name);
+     * console.log(config.seo.seoTitle);
+     * console.log(config.campaigns);
+     * ```
+     *
+     * @example Next.js - with caching
+     * ```typescript
+     * const config = await client.store.getConfig({
+     *   next: { revalidate: 300, tags: ['store-config'] }
+     * });
+     * ```
+     *
+     * @example Nuxt - wrap with useAsyncData
+     * ```typescript
+     * const { data: config } = await useAsyncData(
+     *   'store-config',
+     *   () => client.store.getConfig()
+     * );
+     * ```
+     *
+     * @example Standard fetch caching
+     * ```typescript
+     * const config = await client.store.getConfig({
+     *   cache: 'force-cache'
+     * });
+     * ```
+     */
+    getConfig(options?: FetchOptions): Promise<StoreConfig>;
+};
+/**
+ * Type for the store resource
+ */
+type StoreResource = ReturnType<typeof createStoreResource>;
+
+/**
+ * Products resource for fetching product data
+ */
+declare function createProductsResource(fetcher: Fetcher): {
+    /**
+     * Get latest products ordered by creation date (newest first).
+     *
+     * @param take - Number of products to return (required, must be >= 1)
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Array of products
+     *
+     * @example Basic usage
+     * ```typescript
+     * const products = await client.products.latest(6);
+     * ```
+     *
+     * @example Next.js - with caching
+     * ```typescript
+     * const products = await client.products.latest(6, {
+     *   next: { revalidate: 3600, tags: ['products'] }
+     * });
+     * ```
+     */
+    latest(take: number, options?: FetchOptions): Promise<Product[]>;
+    /**
+     * Get a single product by its URL slug.
+     *
+     * @param slug - Product URL slug
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Full product details including categories and variations
+     * @throws NotFoundError if product doesn't exist or is not visible
+     *
+     * @example Basic usage
+     * ```typescript
+     * const product = await client.products.getBySlug('my-product');
+     * console.log(product.name, product.categories);
+     * ```
+     *
+     * @example Next.js - with caching
+     * ```typescript
+     * const product = await client.products.getBySlug('my-product', {
+     *   next: { revalidate: 3600, tags: ['product', 'my-product'] }
+     * });
+     * ```
+     */
+    getBySlug(slug: string, options?: FetchOptions): Promise<ProductDetail>;
+    /**
+     * Get total product count, optionally filtered by category.
+     *
+     * @param slugs - Optional category slugs to filter by
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Object with count property
+     *
+     * @example Get total count
+     * ```typescript
+     * const { count } = await client.products.count();
+     * console.log(`Total products: ${count}`);
+     * ```
+     *
+     * @example Get count for specific category
+     * ```typescript
+     * const { count } = await client.products.count(['shoes']);
+     * console.log(`Products in shoes: ${count}`);
+     * ```
+     */
+    count(slugs?: string[], options?: FetchOptions): Promise<ProductCountResponse>;
+    /**
+     * Get sorted products with pagination.
+     * Uses optimized sorting with pre-computed effective prices.
+     *
+     * @param params - Query parameters (slugs, page, pageSize, sort)
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Products list with totalCount for pagination
+     *
+     * @example Basic usage
+     * ```typescript
+     * const { products, totalCount } = await client.products.sorted({
+     *   page: 1,
+     *   pageSize: 12,
+     *   sort: 'newest'
+     * });
+     * ```
+     *
+     * @example Filter by category
+     * ```typescript
+     * const { products, totalCount } = await client.products.sorted({
+     *   slugs: ['shoes', 'clothing'],
+     *   page: 1,
+     *   pageSize: 24,
+     *   sort: 'price_asc'
+     * });
+     * ```
+     *
+     * @example Real-time data (no cache)
+     * ```typescript
+     * const data = await client.products.sorted(
+     *   { page: 1, pageSize: 12 },
+     *   { cache: 'no-store' }
+     * );
+     * ```
+     */
+    sorted(params?: ProductListParams, options?: FetchOptions): Promise<ProductListResponse>;
+    /**
+     * Get filtered products with pagination.
+     * Similar to sorted() but without totalCount in response.
+     * Useful for sitemaps and bulk fetches.
+     *
+     * @param params - Query parameters (slugs, page, pageSize, sort)
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Products list with category name
+     *
+     * @example Fetch all products for sitemap
+     * ```typescript
+     * const { products } = await client.products.filtered({
+     *   slugs: ['all-products'],
+     *   page: 1,
+     *   pageSize: 1000
+     * });
+     * ```
+     */
+    filtered(params?: ProductListParams, options?: FetchOptions): Promise<Omit<ProductListResponse, "totalCount">>;
+};
+/**
+ * Type for the products resource
+ */
+type ProductsResource = ReturnType<typeof createProductsResource>;
+
+/**
+ * Categories resource for fetching category data
+ */
+declare function createCategoriesResource(fetcher: Fetcher): {
+    /**
+     * Get all top-level categories with nested children.
+     * Returns a hierarchical tree of categories (up to 5 levels deep).
+     *
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Array of top-level categories with nested children
+     *
+     * @example Basic usage
+     * ```typescript
+     * const categories = await client.categories.list();
+     * categories.forEach(cat => {
+     *   console.log(cat.name, cat.children.length);
+     * });
+     * ```
+     *
+     * @example Next.js - with caching
+     * ```typescript
+     * const categories = await client.categories.list({
+     *   next: { revalidate: 3600, tags: ['categories'] }
+     * });
+     * ```
+     */
+    list(options?: FetchOptions): Promise<Category[]>;
+    /**
+     * Get a single category by its URL slug.
+     *
+     * @param slug - Category URL slug
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Category data
+     * @throws NotFoundError if category doesn't exist
+     *
+     * @example Basic usage
+     * ```typescript
+     * const { category } = await client.categories.getBySlug('shoes');
+     * console.log(category.name);
+     * ```
+     *
+     * @example Next.js - with caching
+     * ```typescript
+     * const { category } = await client.categories.getBySlug('shoes', {
+     *   next: { revalidate: 86400, tags: ['category', 'shoes'] }
+     * });
+     * ```
+     */
+    getBySlug(slug: string, options?: FetchOptions): Promise<CategoryResponse>;
+};
+/**
+ * Type for the categories resource
+ */
+type CategoriesResource = ReturnType<typeof createCategoriesResource>;
+
+/**
+ * Cart Resource
+ *
+ * Methods for managing the shopping cart stored in Redis.
+ * Supports both guest carts (via cartId) and authenticated user carts (via sessionId).
+ */
+
+/**
+ * Cart resource for managing shopping cart
+ */
+declare function createCartResource(fetcher: Fetcher): {
+    /**
+     * Fetch the current cart contents.
+     *
+     * @param options - Cart session options (cartId for guests, sessionId for logged-in users)
+     * @param fetchOptions - Fetch options (caching, headers, etc.)
+     * @returns Cart items and cartId (for guests)
+     *
+     * @example Guest user
+     * ```typescript
+     * const cartId = localStorage.getItem('cart-id');
+     * const { items, cartId: newCartId } = await client.cart.get({ cartId });
+     * ```
+     *
+     * @example Logged-in user
+     * ```typescript
+     * const { items } = await client.cart.get({ sessionId });
+     * ```
+     */
+    get(options?: CartSessionOptions, fetchOptions?: FetchOptions): Promise<CartResponse>;
+    /**
+     * Add an item to the cart.
+     * If the item already exists, quantity is incremented.
+     *
+     * @param params - Add to cart parameters
+     * @param fetchOptions - Fetch options
+     * @returns Updated cart with new cartId for guests
+     * @throws ValidationError if quantity exceeds available stock
+     *
+     * @example Add product
+     * ```typescript
+     * const { items, cartId } = await client.cart.addItem({
+     *   cartId: existingCartId,
+     *   productId: 'prod_123',
+     *   quantity: 2
+     * });
+     * // Save cartId for future requests
+     * localStorage.setItem('cart-id', cartId);
+     * ```
+     *
+     * @example Add product with variation
+     * ```typescript
+     * const { items, cartId } = await client.cart.addItem({
+     *   cartId,
+     *   productId: 'prod_123',
+     *   variationId: 'var_456',
+     *   quantity: 1
+     * });
+     * ```
+     */
+    addItem(params: AddToCartParams, fetchOptions?: FetchOptions): Promise<CartResponse>;
+    /**
+     * Update item quantity by delta (atomic operation).
+     * Use positive delta to increase, negative to decrease.
+     * Minimum quantity is 1 (use removeItem to delete).
+     *
+     * @param params - Update quantity parameters
+     * @param fetchOptions - Fetch options
+     * @returns Updated cart
+     * @throws NotFoundError if item not in cart or quantity would go below 1
+     *
+     * @example Increment quantity
+     * ```typescript
+     * const { items } = await client.cart.updateQuantity({
+     *   cartId,
+     *   productId: 'prod_123',
+     *   delta: 1
+     * });
+     * ```
+     *
+     * @example Decrement quantity
+     * ```typescript
+     * const { items } = await client.cart.updateQuantity({
+     *   cartId,
+     *   productId: 'prod_123',
+     *   variationId: 'var_456',
+     *   delta: -1
+     * });
+     * ```
+     */
+    updateQuantity(params: UpdateCartQuantityParams, fetchOptions?: FetchOptions): Promise<CartResponse>;
+    /**
+     * Remove an item from the cart.
+     *
+     * @param params - Remove from cart parameters
+     * @param fetchOptions - Fetch options
+     * @returns Updated cart
+     *
+     * @example Remove product
+     * ```typescript
+     * const { items } = await client.cart.removeItem({
+     *   cartId,
+     *   productId: 'prod_123'
+     * });
+     * ```
+     *
+     * @example Remove variation
+     * ```typescript
+     * const { items } = await client.cart.removeItem({
+     *   cartId,
+     *   productId: 'prod_123',
+     *   variationId: 'var_456'
+     * });
+     * ```
+     */
+    removeItem(params: RemoveFromCartParams, fetchOptions?: FetchOptions): Promise<CartResponse>;
+    /**
+     * Validate cart before checkout.
+     * Checks product availability, stock levels, and prices.
+     * Auto-fixes issues (removes unavailable items, adjusts quantities).
+     *
+     * @param options - Cart session options
+     * @param fetchOptions - Fetch options
+     * @returns Validated cart with change metadata
+     *
+     * @example Validate before checkout
+     * ```typescript
+     * const { items, hasChanges, changes } = await client.cart.validate({ cartId });
+     *
+     * if (hasChanges) {
+     *   if (changes.removedItems > 0) {
+     *     notify('Some items were removed (out of stock)');
+     *   }
+     *   if (changes.quantityAdjusted > 0) {
+     *     notify('Some quantities were adjusted');
+     *   }
+     *   if (changes.priceChanged > 0) {
+     *     notify('Some prices have changed');
+     *   }
+     * }
+     * ```
+     */
+    validate(options?: CartSessionOptions, fetchOptions?: FetchOptions): Promise<CartValidationResponse>;
+};
+/**
+ * Type for the cart resource
+ */
+type CartResource = ReturnType<typeof createCartResource>;
+
+/**
+ * Shipping Resource
+ *
+ * Methods for fetching shipment methods and pickup locations.
+ */
+
+/**
+ * Shipping resource for fetching shipment methods and pickup locations
+ */
+declare function createShippingResource(fetcher: Fetcher): {
+    /**
+     * Get all available shipment methods for the store.
+     * Returns methods without pickup locations - use `getWithLocations` for postal code specific data.
+     *
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Available shipment methods
+     *
+     * @example
+     * ```typescript
+     * const { shipmentMethods } = await client.shipping.getMethods();
+     *
+     * shipmentMethods.forEach(method => {
+     *   console.log(`${method.name}: ${method.price / 100}€`);
+     * });
+     * ```
+     */
+    getMethods(options?: FetchOptions): Promise<ShipmentMethodsResponse>;
+    /**
+     * Get shipment methods with pickup locations for a specific postal code.
+     * Calls the Shipit API to fetch nearby pickup points (parcel lockers, etc.)
+     *
+     * @param postalCode - Customer's postal code (e.g., "00100")
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Shipment methods and nearby pickup locations with pricing
+     *
+     * @example
+     * ```typescript
+     * const { shipmentMethods, pricedLocations } = await client.shipping.getWithLocations("00100");
+     *
+     * // Show pickup locations
+     * pricedLocations.forEach(location => {
+     *   console.log(`${location.name} - ${location.carrier}`);
+     *   console.log(`  ${location.address1}, ${location.city}`);
+     *   console.log(`  ${location.distanceInKilometers.toFixed(1)} km away`);
+     *   console.log(`  Price: ${(location.merchantPrice ?? 0) / 100}€`);
+     * });
+     * ```
+     *
+     * @example Filter by carrier
+     * ```typescript
+     * const { pricedLocations } = await client.shipping.getWithLocations("00100");
+     *
+     * const postiLocations = pricedLocations.filter(
+     *   loc => loc.carrier === "Posti"
+     * );
+     * ```
+     */
+    getWithLocations(postalCode: string, options?: FetchOptions): Promise<ShipmentMethodsWithLocationsResponse>;
+};
+/**
+ * Type for the shipping resource
+ */
+type ShippingResource = ReturnType<typeof createShippingResource>;
+
+/**
+ * Customer Resource
+ *
+ * Methods for customer authentication and account management.
+ * Supports session-based authentication with the x-session-id header.
+ */
+
+/**
+ * Customer resource for authentication and account management
+ */
+declare function createCustomerResource(fetcher: Fetcher): {
+    /**
+     * Register a new customer account.
+     * After registration, the customer must verify their email before logging in.
+     *
+     * @param data - Registration data (firstName, lastName, email, password)
+     * @param fetchOptions - Fetch options
+     * @returns Created customer with verification token
+     *
+     * @example
+     * ```typescript
+     * const { customer, message } = await client.customer.register({
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   email: 'john@example.com',
+     *   password: 'securePassword123'
+     * });
+     *
+     * // Send verification email using customer.emailVerificationToken
+     * console.log('Account created:', message);
+     * ```
+     */
+    register(data: RegisterData, fetchOptions?: FetchOptions): Promise<RegisterResponse>;
+    /**
+     * Log in an existing customer.
+     * Returns a session ID that must be stored and passed to authenticated endpoints.
+     *
+     * @param email - Customer's email address
+     * @param password - Customer's password
+     * @param options - Login options (optional cartId for cart merging)
+     * @param fetchOptions - Fetch options
+     * @returns Session ID and customer data
+     * @throws ValidationError if email is not verified (check error for requiresVerification)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const { sessionId, customer, expiresAt } = await client.customer.login(
+     *     'john@example.com',
+     *     'securePassword123',
+     *     { cartId: guestCartId } // Optional: merge guest cart
+     *   );
+     *
+     *   // Store sessionId in a cookie
+     *   cookies().set('session-id', sessionId, {
+     *     httpOnly: true,
+     *     expires: new Date(expiresAt)
+     *   });
+     * } catch (error) {
+     *   if (error.requiresVerification) {
+     *     // Prompt user to verify email
+     *     await client.customer.resendVerification(error.customerId);
+     *   }
+     * }
+     * ```
+     */
+    login(email: string, password: string, options?: LoginOptions, fetchOptions?: FetchOptions): Promise<LoginResponse>;
+    /**
+     * Log out the current customer and invalidate their session.
+     * If the customer had items in their cart, they are migrated to a new guest cart.
+     *
+     * @param sessionId - The customer's session ID
+     * @param fetchOptions - Fetch options
+     * @returns Logout confirmation with optional new guest cart ID
+     *
+     * @example
+     * ```typescript
+     * const { cartId } = await client.customer.logout(sessionId);
+     *
+     * // Clear session cookie
+     * cookies().delete('session-id');
+     *
+     * // If cart was migrated, store the new guest cart ID
+     * if (cartId) {
+     *   cookies().set('cart-id', cartId);
+     * }
+     * ```
+     */
+    logout(sessionId: string, fetchOptions?: FetchOptions): Promise<LogoutResponse>;
+    /**
+     * Get the currently authenticated customer's profile.
+     *
+     * @param sessionId - The customer's session ID
+     * @param fetchOptions - Fetch options
+     * @returns Current customer data
+     * @throws AuthError if session is invalid or expired
+     *
+     * @example
+     * ```typescript
+     * const sessionId = cookies().get('session-id')?.value;
+     * if (sessionId) {
+     *   const { customer } = await client.customer.getUser(sessionId);
+     *   console.log(`Welcome back, ${customer.firstName}!`);
+     * }
+     * ```
+     */
+    getUser(sessionId: string, fetchOptions?: FetchOptions): Promise<GetUserResponse>;
+    /**
+     * Verify a customer's email address using the token sent during registration.
+     *
+     * @param token - Email verification token
+     * @param fetchOptions - Fetch options
+     * @returns Verification confirmation
+     * @throws ValidationError if token is invalid or expired
+     *
+     * @example
+     * ```typescript
+     * // Token comes from the verification email link
+     * const token = searchParams.get('token');
+     *
+     * const { message } = await client.customer.verifyEmail(token);
+     * console.log(message); // "Email verified successfully. You can now log in."
+     * ```
+     */
+    verifyEmail(token: string, fetchOptions?: FetchOptions): Promise<VerifyEmailResponse>;
+    /**
+     * Resend the email verification token for an unverified customer.
+     * Generates a new token valid for 24 hours.
+     *
+     * @param customerId - The customer's ID (from failed login response)
+     * @param fetchOptions - Fetch options
+     * @returns Updated customer with new verification token
+     * @throws ValidationError if customer is already verified or not found
+     *
+     * @example
+     * ```typescript
+     * // After login fails with requiresVerification
+     * const { customer } = await client.customer.resendVerification(customerId);
+     *
+     * // Send new verification email using customer.emailVerificationToken
+     * await sendVerificationEmail(customer.email, customer.emailVerificationToken);
+     * ```
+     */
+    resendVerification(customerId: string, fetchOptions?: FetchOptions): Promise<ResendVerificationResponse>;
+    /**
+     * Update the authenticated customer's profile.
+     *
+     * @param sessionId - The customer's session ID
+     * @param data - Profile data to update (firstName, lastName, email)
+     * @param fetchOptions - Fetch options
+     * @returns Updated customer data
+     * @throws AuthError if session is invalid
+     * @throws ValidationError if email is already taken by another customer
+     *
+     * @example
+     * ```typescript
+     * const { customer } = await client.customer.updateProfile(sessionId, {
+     *   firstName: 'Jane',
+     *   lastName: 'Smith',
+     *   email: 'jane.smith@example.com'
+     * });
+     *
+     * console.log('Profile updated:', customer.email);
+     * ```
+     */
+    updateProfile(sessionId: string, data: UpdateProfileData, fetchOptions?: FetchOptions): Promise<UpdateProfileResponse>;
+    /**
+     * Delete the authenticated customer's account.
+     * This action is permanent and cannot be undone.
+     * All associated data (sessions, wishlist, etc.) will be deleted.
+     *
+     * @param sessionId - The customer's session ID
+     * @param fetchOptions - Fetch options
+     * @returns Deletion confirmation
+     * @throws AuthError if session is invalid
+     *
+     * @example
+     * ```typescript
+     * // Confirm with user before calling
+     * if (confirm('Are you sure you want to delete your account?')) {
+     *   await client.customer.deleteAccount(sessionId);
+     *
+     *   // Clear session cookie
+     *   cookies().delete('session-id');
+     *
+     *   // Redirect to home page
+     *   redirect('/');
+     * }
+     * ```
+     */
+    deleteAccount(sessionId: string, fetchOptions?: FetchOptions): Promise<DeleteAccountResponse>;
+    /**
+     * Get the customer's order history.
+     * Returns all orders with line items and product details.
+     *
+     * @param sessionId - The customer's session ID
+     * @param customerId - The customer's ID
+     * @param fetchOptions - Fetch options
+     * @returns List of customer orders
+     *
+     * @example
+     * ```typescript
+     * const { orders } = await client.customer.getOrders(sessionId, customerId);
+     *
+     * orders.forEach(order => {
+     *   console.log(`Order #${order.orderNumber}: ${order.status}`);
+     *   order.OrderLineItems.forEach(item => {
+     *     console.log(`  - ${item.name} x${item.quantity}`);
+     *   });
+     * });
+     * ```
+     */
+    getOrders(sessionId: string, customerId: string, fetchOptions?: FetchOptions): Promise<GetOrdersResponse>;
+    /**
+     * Wishlist management methods.
+     * Access via `client.customer.wishlist.get()`, `.add()`, `.remove()`.
+     */
+    wishlist: {
+        /**
+         * Get the customer's wishlist.
+         * Returns all wishlist items with product and variation details.
+         *
+         * @param sessionId - The customer's session ID
+         * @param fetchOptions - Fetch options
+         * @returns Wishlist items with product details
+         * @throws AuthError if session is invalid
+         *
+         * @example
+         * ```typescript
+         * const { items } = await client.customer.wishlist.get(sessionId);
+         *
+         * items.forEach(item => {
+         *   console.log(`${item.product.name} - $${item.product.price / 100}`);
+         *   if (item.variation) {
+         *     const options = item.variation.options
+         *       .map(o => `${o.optionType.name}: ${o.value}`)
+         *       .join(', ');
+         *     console.log(`  Variant: ${options}`);
+         *   }
+         * });
+         * ```
+         */
+        get(sessionId: string, fetchOptions?: FetchOptions): Promise<WishlistResponse>;
+        /**
+         * Add a product to the customer's wishlist.
+         *
+         * @param sessionId - The customer's session ID
+         * @param productId - The product ID to add
+         * @param variationId - Optional variation ID (for products with variations)
+         * @param fetchOptions - Fetch options
+         * @returns Success message
+         * @throws AuthError if session is invalid
+         * @throws ValidationError if product already in wishlist
+         *
+         * @example
+         * ```typescript
+         * // Add a simple product
+         * await client.customer.wishlist.add(sessionId, 'prod_123');
+         *
+         * // Add a product with a specific variation
+         * await client.customer.wishlist.add(sessionId, 'prod_123', 'var_456');
+         * ```
+         */
+        add(sessionId: string, productId: string, variationId?: string, fetchOptions?: FetchOptions): Promise<AddToWishlistResponse>;
+        /**
+         * Remove a product from the customer's wishlist.
+         *
+         * @param sessionId - The customer's session ID
+         * @param productId - The product ID to remove
+         * @param variationId - Optional variation ID (must match if item was added with variation)
+         * @param fetchOptions - Fetch options
+         * @returns Success message
+         * @throws AuthError if session is invalid
+         * @throws NotFoundError if item not in wishlist
+         *
+         * @example
+         * ```typescript
+         * // Remove a simple product
+         * await client.customer.wishlist.remove(sessionId, 'prod_123');
+         *
+         * // Remove a specific variation
+         * await client.customer.wishlist.remove(sessionId, 'prod_123', 'var_456');
+         * ```
+         */
+        remove(sessionId: string, productId: string, variationId?: string, fetchOptions?: FetchOptions): Promise<RemoveFromWishlistResponse>;
+    };
+};
+/**
+ * Type for the customer resource
+ */
+type CustomerResource = ReturnType<typeof createCustomerResource>;
+
+/**
+ * Order resource for fetching order details
+ *
+ * Used for order confirmation pages and viewing order details.
+ * For customer order history, use the customer.getOrders() method instead.
+ */
+declare function createOrderResource(fetcher: Fetcher): {
+    /**
+     * Get order details by ID.
+     *
+     * Retrieves complete order information including line items,
+     * customer data, and shipment method with tracking info.
+     *
+     * @param orderId - The order ID to fetch
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Complete order details
+     * @throws NotFoundError if order doesn't exist or belongs to different store
+     *
+     * @example Basic usage (order confirmation page)
+     * ```typescript
+     * const order = await client.order.get(orderId);
+     * console.log(`Order #${order.orderNumber} - ${order.status}`);
+     * console.log(`Total: ${order.totalAmount / 100} EUR`);
+     * ```
+     *
+     * @example Next.js - with caching
+     * ```typescript
+     * const order = await client.order.get(orderId, {
+     *   next: { revalidate: 60, tags: ['order', orderId] }
+     * });
+     * ```
+     *
+     * @example Display line items
+     * ```typescript
+     * const order = await client.order.get(orderId);
+     * order.OrderLineItems.forEach(item => {
+     *   if (item.itemType !== 'SHIPPING') {
+     *     console.log(`${item.name} x${item.quantity} = ${item.totalAmount / 100} EUR`);
+     *   }
+     * });
+     * ```
+     *
+     * @example Show tracking info
+     * ```typescript
+     * const order = await client.order.get(orderId);
+     * if (order.orderShipmentMethod?.trackingNumber) {
+     *   console.log(`Tracking: ${order.orderShipmentMethod.trackingNumber}`);
+     *   order.orderShipmentMethod.trackingUrls?.forEach(url => {
+     *     console.log(`Track at: ${url}`);
+     *   });
+     * }
+     * ```
+     */
+    get(orderId: string, options?: FetchOptions): Promise<Order>;
+};
+/**
+ * Type for the order resource
+ */
+type OrderResource = ReturnType<typeof createOrderResource>;
+
+/**
+ * Extended options for checkout requests
+ *
+ * Checkout requires cart and session context via headers.
+ */
+interface CheckoutOptions extends FetchOptions {
+    /**
+     * Cart ID for guest checkout.
+     * Pass this when the user is not logged in.
+     */
+    cartId?: string;
+    /**
+     * Session ID for authenticated checkout.
+     * Pass this when the user is logged in.
+     */
+    sessionId?: string;
+}
+/**
+ * Checkout resource for payment processing
+ *
+ * Handles both Stripe and Paytrail payment providers.
+ */
+declare function createCheckoutResource(fetcher: Fetcher): {
+    /**
+     * Create a Stripe checkout session.
+     *
+     * Redirects the user to Stripe's hosted checkout page.
+     * Cart items are validated and stock is reserved on the server.
+     *
+     * @param params - Checkout parameters (customer data, shipping, URLs)
+     * @param options - Checkout options including cart/session context
+     * @returns URL to redirect user to Stripe checkout
+     * @throws ValidationError for invalid data or empty cart
+     * @throws StorefrontError for inventory issues
+     *
+     * @example Basic usage with redirect
+     * ```typescript
+     * const { url } = await client.checkout.stripe({
+     *   customerData: {
+     *     first_name: "John",
+     *     last_name: "Doe",
+     *     email: "john@example.com",
+     *     address: "123 Main St",
+     *     postal_code: "00100",
+     *     city: "Helsinki",
+     *     phone: "+358401234567"
+     *   },
+     *   shipmentMethod: {
+     *     shipmentMethodId: "ship_123",
+     *     pickupId: null
+     *   },
+     *   orderId: "order_abc123",
+     *   successUrl: "https://mystore.com/success",
+     *   cancelUrl: "https://mystore.com/cancel"
+     * }, {
+     *   cartId: "cart_xyz",  // For guest users
+     *   sessionId: "sess_123" // For logged-in users
+     * });
+     *
+     * // Redirect to Stripe
+     * window.location.href = url;
+     * ```
+     */
+    stripe(params: CheckoutParams, options?: CheckoutOptions): Promise<StripeCheckoutResponse>;
+    /**
+     * Create a Paytrail checkout session.
+     *
+     * Returns payment providers for Finnish payment methods.
+     * Cart items are validated and stock is reserved on the server.
+     *
+     * @param params - Checkout parameters (customer data, shipping, URLs)
+     * @param options - Checkout options including cart/session context
+     * @returns Paytrail response with available payment providers
+     * @throws ValidationError for invalid data or empty cart
+     * @throws StorefrontError for inventory issues
+     *
+     * @example Display payment providers
+     * ```typescript
+     * const response = await client.checkout.paytrail({
+     *   customerData: {
+     *     first_name: "Matti",
+     *     last_name: "Meikäläinen",
+     *     email: "matti@example.fi",
+     *     address: "Mannerheimintie 1",
+     *     postal_code: "00100",
+     *     city: "Helsinki",
+     *     phone: "+358401234567"
+     *   },
+     *   shipmentMethod: {
+     *     shipmentMethodId: "ship_123",
+     *     pickupId: "pickup_456" // For pickup points
+     *   },
+     *   orderId: "order_abc123",
+     *   successUrl: "https://mystore.com/success",
+     *   cancelUrl: "https://mystore.com/cancel"
+     * }, {
+     *   cartId: "cart_xyz"
+     * });
+     *
+     * // Group providers by type
+     * const banks = response.providers.filter(p => p.group === "bank");
+     * const mobile = response.providers.filter(p => p.group === "mobile");
+     * const cards = response.providers.filter(p => p.group === "creditcard");
+     * ```
+     *
+     * @example Submit payment form
+     * ```typescript
+     * const provider = response.providers.find(p => p.id === "nordea");
+     *
+     * // Create and submit a form
+     * const form = document.createElement("form");
+     * form.method = "POST";
+     * form.action = provider.url;
+     *
+     * provider.parameters.forEach(({ name, value }) => {
+     *   const input = document.createElement("input");
+     *   input.type = "hidden";
+     *   input.name = name;
+     *   input.value = value;
+     *   form.appendChild(input);
+     * });
+     *
+     * document.body.appendChild(form);
+     * form.submit();
+     * ```
+     */
+    paytrail(params: CheckoutParams, options?: CheckoutOptions): Promise<PaytrailCheckoutResponse>;
+};
+/**
+ * Type for the checkout resource
+ */
+type CheckoutResource = ReturnType<typeof createCheckoutResource>;
+
+/**
+ * The Storefront API client
+ */
+interface StorefrontClient {
+    /**
+     * The configured API key (masked for security)
+     */
+    readonly apiKey: string;
+    /**
+     * The base URL for API requests
+     */
+    readonly baseUrl: string;
+    /**
+     * Store configuration resource
+     */
+    readonly store: StoreResource;
+    /**
+     * Products resource
+     */
+    readonly products: ProductsResource;
+    /**
+     * Categories resource
+     */
+    readonly categories: CategoriesResource;
+    /**
+     * Cart resource
+     */
+    readonly cart: CartResource;
+    /**
+     * Shipping resource
+     */
+    readonly shipping: ShippingResource;
+    /**
+     * Customer authentication and account management resource
+     */
+    readonly customer: CustomerResource;
+    /**
+     * Order resource for fetching order details
+     */
+    readonly order: OrderResource;
+    /**
+     * Checkout resource for payment processing
+     */
+    readonly checkout: CheckoutResource;
+}
+/**
+ * Create a new Storefront API client
  */
 declare function createStorefrontClient(config: StorefrontClientConfig): StorefrontClient;
 
+/**
+ * Pricing Utilities
+ *
+ * Helper functions for calculating prices with sale logic.
+ */
+
+/**
+ * Check if a sale is currently active based on start and end dates.
+ *
+ * @param startDate - Sale start date (ISO string, Date, null, or undefined)
+ * @param endDate - Sale end date (ISO string, Date, null, or undefined)
+ * @returns true if the sale is currently active
+ *
+ * @example
+ * ```typescript
+ * // No dates = always active
+ * isSaleActive(null, null); // true
+ *
+ * // Only start date = active if past start
+ * isSaleActive("2024-01-01", null); // true if today >= Jan 1
+ *
+ * // Both dates = active if within range
+ * isSaleActive("2024-01-01", "2024-12-31"); // true if within range
+ * ```
+ */
+declare function isSaleActive(startDate: Date | string | null | undefined, endDate: Date | string | null | undefined): boolean;
+/**
+ * Get price information for a product or variation.
+ * Returns the effective price (sale or regular) and sale status.
+ * All prices are in cents.
+ *
+ * @param product - The product to get price info for
+ * @param variation - Optional variation (takes precedence over product price)
+ * @returns Price information with effective price, original price, and sale status
+ *
+ * @example
+ * ```typescript
+ * // Product without variation
+ * const priceInfo = getPriceInfo(product);
+ * console.log(priceInfo.effectivePrice); // 1990 (cents)
+ * console.log(priceInfo.isOnSale); // true
+ *
+ * // Product with selected variation
+ * const priceInfo = getPriceInfo(product, selectedVariation);
+ * ```
+ */
+declare function getPriceInfo(product: ProductDetail, variation?: ProductVariation): PriceInfo;
+
+/**
+ * Cart Calculation Utilities
+ *
+ * Functions for calculating cart totals with campaign discounts.
+ */
+
+/**
+ * Calculate cart totals with campaign discounts applied.
+ *
+ * Supports two campaign types:
+ * - **FREE_SHIPPING**: Free shipping when cart total exceeds minimum spend
+ * - **BUY_X_PAY_Y**: Buy X items, pay for Y (e.g., Buy 3 Pay 2 = 1 free item)
+ *
+ * @param items - Cart items to calculate
+ * @param campaigns - Active campaigns to apply
+ * @returns Calculation result with totals, savings, and free shipping status
+ *
+ * @example
+ * ```typescript
+ * const result = calculateCartWithCampaigns(cartItems, activeCampaigns);
+ *
+ * console.log(result.cartTotal);     // 4990 (cents)
+ * console.log(result.totalSavings);  // 1990 (cents)
+ * console.log(result.freeShipping.isEligible); // true
+ *
+ * // Render calculated items
+ * result.calculatedItems.forEach(({ item, paidQuantity, freeQuantity }) => {
+ *   console.log(`${item.product.name}: ${paidQuantity} paid, ${freeQuantity} free`);
+ * });
+ * ```
+ */
+declare function calculateCartWithCampaigns(items: CartItem[], campaigns: Campaign[]): CartCalculationResult;
+
 /**
  * Base error class for all Storefront API errors
  */
@@ -299,4 +2411,4 @@ declare class ValidationError extends StorefrontError {
     constructor(message?: string);
 }
 
-export { AuthError, type BuyXPayYCampaign, type Campaign, type CampaignType, type CategoryReference, type FeatureFlags, type FetchOptions, type FreeShippingCampaign, NotFoundError, type PaymentConfig, RateLimitError, type ShipmentMethod, type StoreConfig, type StoreInfo, type StoreSeo, type StorefrontClient, type StorefrontClientConfig, StorefrontError, ValidationError, createStorefrontClient };
+export { type AddToCartParams, type AddToWishlistResponse, AuthError, type BuyXPayYCampaign, type CalculatedCartItem, type Campaign, type CampaignType, type CartCalculationResult, type CartItem, type CartResponse, type CartSessionOptions, type CartValidationChanges, type CartValidationResponse, type Category, type CategoryReference, type CategoryResponse, type CheckoutCustomerData, type CheckoutErrorCode, type CheckoutErrorDetails, type CheckoutOptions, type CheckoutParams, type CheckoutShipmentMethod, type ConfirmationItemType, type ConfirmationOrderCustomerData, type ConfirmationOrderLineItem, type ConfirmationOrderShipmentMethod, type ConfirmationOrderStatus, type Customer, type CustomerOrder, type CustomerWithCreatedAt, type CustomerWithEmailStatus, type CustomerWithVerification, type DeleteAccountResponse, type FeatureFlags, type FetchOptions, type FreeShippingCampaign, type FreeShippingStatus, type GetOrdersResponse, type GetUserResponse, type LoginOptions, type LoginResponse, type LoginVerificationRequiredResponse, type LogoutResponse, NotFoundError, type Order, type OrderLineItem, type OrderProductInfo, type OrderShipmentMethod, type OrderStatus, type PaymentConfig, type PaytrailCheckoutResponse, type PaytrailGroup, type PaytrailProvider, type PickupLocation, type PickupLocationOpeningHours, type PriceInfo, type Product, type ProductCountResponse, type ProductDetail, type ProductListParams, type ProductListResponse, type ProductSortOption, type ProductVariation, type ProductVariationListing, RateLimitError, type RegisterData, type RegisterResponse, type RemoveFromCartParams, type RemoveFromWishlistResponse, type ResendVerificationResponse, type ShipitShippingMethod, type ShipmentMethod, type ShipmentMethodsResponse, type ShipmentMethodsWithLocationsResponse, type StoreConfig, type StoreInfo, type StoreSeo, type StorefrontClient, type StorefrontClientConfig, StorefrontError, type StripeCheckoutResponse, type UpdateCartQuantityParams, type UpdateProfileData, type UpdateProfileResponse, ValidationError, type VariationOption, type VerifyEmailResponse, type WishlistItem, type WishlistProduct, type WishlistResponse, type WishlistVariation, type WishlistVariationOption, calculateCartWithCampaigns, createStorefrontClient, getPriceInfo, isSaleActive };