@putiikkipalvelu/storefront-sdk 0.1.1 → 0.2.1

package/dist/index.js

@@ -36,6 +36,14 @@ var ValidationError = class extends StorefrontError {
     this.name = "ValidationError";
   }
 };
+var VerificationRequiredError = class extends StorefrontError {
+  constructor(message, customerId) {
+    super(message, 403, "VERIFICATION_REQUIRED");
+    this.requiresVerification = true;
+    this.name = "VerificationRequiredError";
+    this.customerId = customerId;
+  }
+};
 
 // src/utils/fetch.ts
 var SDK_VERSION = "0.1.0";
@@ -96,15 +104,18 @@ function createFetcher(config) {
   return { request };
 }
 async function handleErrorResponse(response) {
-  let errorMessage = null;
+  let errorData = {};
   try {
     const json = await response.json();
-    if (json && typeof json === "object" && "error" in json) {
-      errorMessage = json.error;
+    if (json && typeof json === "object") {
+      errorData = json;
     }
   } catch {
   }
-  const message = errorMessage || response.statusText || "Request failed";
+  const message = errorData.error || response.statusText || "Request failed";
+  if (errorData.requiresVerification && errorData.customerId) {
+    throw new VerificationRequiredError(message, errorData.customerId);
+  }
   switch (response.status) {
     case 401:
       throw new AuthError(message);
@@ -165,6 +176,1135 @@ function createStoreResource(fetcher) {
   };
 }
 
+// src/resources/products.ts
+function createProductsResource(fetcher) {
+  return {
+    /**
+     * 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'] }
+     * });
+     * ```
+     */
+    async latest(take, options) {
+      return fetcher.request("/api/storefront/v1/latest-products", {
+        params: { take },
+        ...options
+      });
+    },
+    /**
+     * 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'] }
+     * });
+     * ```
+     */
+    async getBySlug(slug, options) {
+      return fetcher.request(
+        `/api/storefront/v1/product/${encodeURIComponent(slug)}`,
+        {
+          ...options
+        }
+      );
+    },
+    /**
+     * 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}`);
+     * ```
+     */
+    async count(slugs, options) {
+      const searchParams = new URLSearchParams();
+      if (slugs?.length) {
+        slugs.forEach((s) => searchParams.append("slugs", s));
+      }
+      const query = searchParams.toString();
+      const endpoint = `/api/storefront/v1/products-count${query ? `?${query}` : ""}`;
+      return fetcher.request(endpoint, {
+        ...options
+      });
+    },
+    /**
+     * 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' }
+     * );
+     * ```
+     */
+    async sorted(params = {}, options) {
+      const searchParams = new URLSearchParams();
+      if (params.page) searchParams.set("page", params.page.toString());
+      if (params.pageSize)
+        searchParams.set("pageSize", params.pageSize.toString());
+      if (params.sort) searchParams.set("sort", params.sort);
+      if (params.slugs?.length) {
+        params.slugs.forEach((s) => searchParams.append("slugs", s));
+      }
+      const query = searchParams.toString();
+      const endpoint = `/api/storefront/v1/sorted-products${query ? `?${query}` : ""}`;
+      return fetcher.request(endpoint, {
+        ...options
+      });
+    },
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async filtered(params = {}, options) {
+      const searchParams = new URLSearchParams();
+      if (params.page) searchParams.set("page", params.page.toString());
+      if (params.pageSize)
+        searchParams.set("pageSize", params.pageSize.toString());
+      if (params.sort) searchParams.set("sort", params.sort);
+      if (params.slugs?.length) {
+        params.slugs.forEach((s) => searchParams.append("slugs", s));
+      }
+      const query = searchParams.toString();
+      const endpoint = `/api/storefront/v1/filtered-products${query ? `?${query}` : ""}`;
+      return fetcher.request(
+        endpoint,
+        {
+          ...options
+        }
+      );
+    }
+  };
+}
+
+// src/resources/categories.ts
+function createCategoriesResource(fetcher) {
+  return {
+    /**
+     * 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'] }
+     * });
+     * ```
+     */
+    async list(options) {
+      return fetcher.request("/api/storefront/v1/categories", {
+        ...options
+      });
+    },
+    /**
+     * 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'] }
+     * });
+     * ```
+     */
+    async getBySlug(slug, options) {
+      return fetcher.request(
+        `/api/storefront/v1/categories/${encodeURIComponent(slug)}`,
+        {
+          ...options
+        }
+      );
+    }
+  };
+}
+
+// src/resources/cart.ts
+function buildCartHeaders(options) {
+  const headers = {};
+  if (options?.cartId) {
+    headers["x-cart-id"] = options.cartId;
+  }
+  if (options?.sessionId) {
+    headers["x-session-id"] = options.sessionId;
+  }
+  return headers;
+}
+function createCartResource(fetcher) {
+  return {
+    /**
+     * 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 });
+     * ```
+     */
+    async get(options, fetchOptions) {
+      return fetcher.request("/api/storefront/v1/cart", {
+        method: "GET",
+        headers: buildCartHeaders(options),
+        ...fetchOptions
+      });
+    },
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async addItem(params, fetchOptions) {
+      const { cartId, sessionId, ...body } = params;
+      return fetcher.request("/api/storefront/v1/cart", {
+        method: "POST",
+        headers: buildCartHeaders({ sessionId }),
+        body: {
+          cartId,
+          ...body
+        },
+        ...fetchOptions
+      });
+    },
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async updateQuantity(params, fetchOptions) {
+      const { cartId, sessionId, ...body } = params;
+      return fetcher.request("/api/storefront/v1/cart", {
+        method: "PATCH",
+        headers: buildCartHeaders({ sessionId }),
+        body: {
+          cartId,
+          ...body
+        },
+        ...fetchOptions
+      });
+    },
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    async removeItem(params, fetchOptions) {
+      const { cartId, sessionId, ...body } = params;
+      return fetcher.request("/api/storefront/v1/cart", {
+        method: "DELETE",
+        headers: buildCartHeaders({ sessionId }),
+        body: {
+          cartId,
+          ...body
+        },
+        ...fetchOptions
+      });
+    },
+    /**
+     * 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');
+     *   }
+     * }
+     * ```
+     */
+    async validate(options, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/cart/validate",
+        {
+          method: "GET",
+          headers: buildCartHeaders(options),
+          ...fetchOptions
+        }
+      );
+    }
+  };
+}
+
+// src/resources/shipping.ts
+function createShippingResource(fetcher) {
+  return {
+    /**
+     * 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}€`);
+     * });
+     * ```
+     */
+    async getMethods(options) {
+      return fetcher.request(
+        "/api/storefront/v1/shipment-methods",
+        {
+          method: "GET",
+          ...options
+        }
+      );
+    },
+    /**
+     * 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"
+     * );
+     * ```
+     */
+    async getWithLocations(postalCode, options) {
+      return fetcher.request(
+        `/api/storefront/v1/shipment-methods/${encodeURIComponent(postalCode)}`,
+        {
+          method: "GET",
+          ...options
+        }
+      );
+    }
+  };
+}
+
+// src/resources/customer.ts
+function buildSessionHeaders(sessionId) {
+  return { "x-session-id": sessionId };
+}
+function createCustomerResource(fetcher) {
+  return {
+    /**
+     * 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);
+     * ```
+     */
+    async register(data, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/(auth)/register",
+        {
+          method: "POST",
+          body: data,
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    async login(email, password, options, fetchOptions) {
+      const headers = {};
+      if (options?.cartId) {
+        headers["x-cart-id"] = options.cartId;
+      }
+      return fetcher.request(
+        "/api/storefront/v1/customer/(auth)/login",
+        {
+          method: "POST",
+          body: { email, password },
+          headers,
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async logout(sessionId, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/(auth)/logout",
+        {
+          method: "POST",
+          headers: buildSessionHeaders(sessionId),
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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}!`);
+     * }
+     * ```
+     */
+    async getUser(sessionId, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/(auth)/get-user",
+        {
+          method: "GET",
+          headers: buildSessionHeaders(sessionId),
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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."
+     * ```
+     */
+    async verifyEmail(token, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/(auth)/verify-email",
+        {
+          method: "GET",
+          params: { token },
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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);
+     * ```
+     */
+    async resendVerification(customerId, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/(auth)/resend-verification",
+        {
+          method: "POST",
+          body: { customerId },
+          ...fetchOptions
+        }
+      );
+    },
+    // =========================================================================
+    // Profile Management Methods
+    // =========================================================================
+    /**
+     * 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);
+     * ```
+     */
+    async updateProfile(sessionId, data, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/edit-user",
+        {
+          method: "PATCH",
+          headers: buildSessionHeaders(sessionId),
+          body: data,
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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('/');
+     * }
+     * ```
+     */
+    async deleteAccount(sessionId, fetchOptions) {
+      return fetcher.request(
+        "/api/storefront/v1/customer/delete-user",
+        {
+          method: "DELETE",
+          headers: buildSessionHeaders(sessionId),
+          ...fetchOptions
+        }
+      );
+    },
+    /**
+     * 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}`);
+     *   });
+     * });
+     * ```
+     */
+    async getOrders(sessionId, customerId, fetchOptions) {
+      return fetcher.request(
+        `/api/storefront/v1/customer/get-orders/${customerId}`,
+        {
+          method: "GET",
+          headers: buildSessionHeaders(sessionId),
+          ...fetchOptions
+        }
+      );
+    },
+    // =========================================================================
+    // Wishlist (Nested Resource)
+    // =========================================================================
+    /**
+     * 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}`);
+       *   }
+       * });
+       * ```
+       */
+      async get(sessionId, fetchOptions) {
+        return fetcher.request(
+          "/api/storefront/v1/customer/wishlist",
+          {
+            method: "GET",
+            headers: buildSessionHeaders(sessionId),
+            ...fetchOptions
+          }
+        );
+      },
+      /**
+       * 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');
+       * ```
+       */
+      async add(sessionId, productId, variationId, fetchOptions) {
+        return fetcher.request(
+          "/api/storefront/v1/customer/wishlist",
+          {
+            method: "POST",
+            headers: buildSessionHeaders(sessionId),
+            body: { productId, variationId },
+            ...fetchOptions
+          }
+        );
+      },
+      /**
+       * 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');
+       * ```
+       */
+      async remove(sessionId, productId, variationId, fetchOptions) {
+        return fetcher.request(
+          "/api/storefront/v1/customer/wishlist",
+          {
+            method: "DELETE",
+            headers: buildSessionHeaders(sessionId),
+            body: { productId, variationId },
+            ...fetchOptions
+          }
+        );
+      }
+    }
+  };
+}
+
+// src/resources/order.ts
+function createOrderResource(fetcher) {
+  return {
+    /**
+     * 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}`);
+     *   });
+     * }
+     * ```
+     */
+    async get(orderId, options) {
+      return fetcher.request(
+        `/api/storefront/v1/order/${encodeURIComponent(orderId)}`,
+        {
+          ...options
+        }
+      );
+    }
+  };
+}
+
+// src/resources/checkout.ts
+function createCheckoutResource(fetcher) {
+  function buildCheckoutHeaders(options) {
+    const headers = {};
+    if (options?.cartId) {
+      headers["x-cart-id"] = options.cartId;
+    }
+    if (options?.sessionId) {
+      headers["x-session-id"] = options.sessionId;
+    }
+    return headers;
+  }
+  function buildCheckoutBody(params) {
+    return {
+      orderId: params.orderId,
+      chosenShipmentMethod: params.shipmentMethod,
+      customerData: params.customerData,
+      successUrl: params.successUrl,
+      cancelUrl: params.cancelUrl
+    };
+  }
+  return {
+    /**
+     * 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;
+     * ```
+     */
+    async stripe(params, options) {
+      const headers = buildCheckoutHeaders(options);
+      const body = buildCheckoutBody(params);
+      return fetcher.request(
+        "/api/storefront/v1/payments/stripe/checkout",
+        {
+          method: "POST",
+          body,
+          headers: {
+            ...options?.headers,
+            ...headers
+          },
+          ...options
+        }
+      );
+    },
+    /**
+     * 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();
+     * ```
+     */
+    async paytrail(params, options) {
+      const headers = buildCheckoutHeaders(options);
+      const body = buildCheckoutBody(params);
+      return fetcher.request(
+        "/api/storefront/v1/payments/paytrail/checkout",
+        {
+          method: "POST",
+          body,
+          headers: {
+            ...options?.headers,
+            ...headers
+          },
+          ...options
+        }
+      );
+    }
+  };
+}
+
 // src/client.ts
 function createStorefrontClient(config) {
   if (!config.apiKey) {
@@ -174,16 +1314,190 @@ function createStorefrontClient(config) {
     throw new Error("baseUrl is required");
   }
   const baseUrl = config.baseUrl.replace(/\/$/, "");
-  const maskedApiKey = config.apiKey.length > 8 ? `${config.apiKey.slice(0, 8)}...` : config.apiKey;
   const fetcher = createFetcher({
     apiKey: config.apiKey,
     baseUrl,
     timeout: config.timeout
   });
   return {
-    apiKey: maskedApiKey,
     baseUrl,
-    store: createStoreResource(fetcher)
+    store: createStoreResource(fetcher),
+    products: createProductsResource(fetcher),
+    categories: createCategoriesResource(fetcher),
+    cart: createCartResource(fetcher),
+    shipping: createShippingResource(fetcher),
+    customer: createCustomerResource(fetcher),
+    order: createOrderResource(fetcher),
+    checkout: createCheckoutResource(fetcher)
+  };
+}
+
+// src/utils/pricing.ts
+function isSaleActive(startDate, endDate) {
+  if (!startDate && !endDate) {
+    return true;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const start = startDate ? new Date(startDate) : null;
+  const end = endDate ? new Date(endDate) : null;
+  if (start && !end) {
+    return now >= start;
+  }
+  if (!start && end) {
+    return now <= end;
+  }
+  if (start && end) {
+    return now >= start && now <= end;
+  }
+  return true;
+}
+function getPriceInfo(product, variation) {
+  if (variation) {
+    const isOnSale2 = isSaleActive(variation.saleStartDate, variation.saleEndDate) && variation.salePrice !== null;
+    const originalPrice2 = variation.price ?? product.price;
+    const effectivePrice2 = isOnSale2 ? variation.salePrice ?? originalPrice2 : originalPrice2;
+    return {
+      effectivePrice: effectivePrice2,
+      originalPrice: originalPrice2,
+      isOnSale: isOnSale2,
+      salePercent: isOnSale2 ? variation.salePercent ?? null : null
+    };
+  }
+  const isOnSale = isSaleActive(product.saleStartDate, product.saleEndDate) && product.salePrice !== null;
+  const originalPrice = product.price;
+  const effectivePrice = isOnSale ? product.salePrice ?? originalPrice : originalPrice;
+  return {
+    effectivePrice,
+    originalPrice,
+    isOnSale,
+    salePercent: isOnSale ? product.salePercent ?? null : null
+  };
+}
+
+// src/utils/cart-calculations.ts
+function calculateCartWithCampaigns(items, campaigns) {
+  const freeShippingCampaign = campaigns.find(
+    (c) => c.type === "FREE_SHIPPING" && c.isActive
+  );
+  const buyXPayYCampaign = campaigns.find(
+    (c) => c.type === "BUY_X_PAY_Y" && c.isActive
+  );
+  const originalTotal = items.reduce((total, { product, variation, cartQuantity }) => {
+    const priceInfo = getPriceInfo(product, variation);
+    return total + priceInfo.effectivePrice * cartQuantity;
+  }, 0);
+  if (!buyXPayYCampaign?.BuyXPayYCampaign) {
+    const calculatedItems2 = items.map((item) => ({
+      item,
+      paidQuantity: item.cartQuantity,
+      freeQuantity: 0,
+      totalQuantity: item.cartQuantity
+    }));
+    const freeShipping2 = calculateFreeShipping(
+      originalTotal,
+      freeShippingCampaign
+    );
+    return {
+      calculatedItems: calculatedItems2,
+      cartTotal: originalTotal,
+      originalTotal,
+      totalSavings: 0,
+      freeShipping: freeShipping2
+    };
+  }
+  const { buyQuantity, payQuantity, applicableCategories } = buyXPayYCampaign.BuyXPayYCampaign;
+  const applicableCategoryIds = new Set(
+    applicableCategories.map((c) => c.id)
+  );
+  const eligibleUnits = items.flatMap((item) => {
+    const { product, variation } = item;
+    const itemCategories = product.categories?.map((cat) => cat.id) || [];
+    const isEligible = itemCategories.some(
+      (id) => applicableCategoryIds.has(id)
+    );
+    if (isEligible) {
+      const priceInfo = getPriceInfo(product, variation);
+      return Array.from({ length: item.cartQuantity }, () => ({
+        price: priceInfo.effectivePrice,
+        productId: product.id,
+        variationId: variation?.id,
+        originalItem: item
+      }));
+    }
+    return [];
+  });
+  if (eligibleUnits.length < buyQuantity) {
+    const calculatedItems2 = items.map((item) => ({
+      item,
+      paidQuantity: item.cartQuantity,
+      freeQuantity: 0,
+      totalQuantity: item.cartQuantity
+    }));
+    const freeShipping2 = calculateFreeShipping(
+      originalTotal,
+      freeShippingCampaign
+    );
+    return {
+      calculatedItems: calculatedItems2,
+      cartTotal: originalTotal,
+      originalTotal,
+      totalSavings: 0,
+      freeShipping: freeShipping2
+    };
+  }
+  eligibleUnits.sort((a, b) => a.price - b.price);
+  const numToMakeFree = buyQuantity - payQuantity;
+  const itemsToMakeFree = eligibleUnits.slice(0, numToMakeFree);
+  const totalSavings = itemsToMakeFree.reduce(
+    (sum, item) => sum + item.price,
+    0
+  );
+  const freeCountMap = /* @__PURE__ */ new Map();
+  for (const freebie of itemsToMakeFree) {
+    const key = `${freebie.productId}${freebie.variationId ? `_${freebie.variationId}` : ""}`;
+    freeCountMap.set(key, (freeCountMap.get(key) || 0) + 1);
+  }
+  const calculatedItems = items.map((item) => {
+    const key = `${item.product.id}${item.variation?.id ? `_${item.variation.id}` : ""}`;
+    const freeQuantity = freeCountMap.get(key) || 0;
+    const paidQuantity = item.cartQuantity - freeQuantity;
+    return {
+      item,
+      paidQuantity: Math.max(0, paidQuantity),
+      freeQuantity,
+      totalQuantity: item.cartQuantity
+    };
+  });
+  const cartTotal = originalTotal - totalSavings;
+  const freeShipping = calculateFreeShipping(cartTotal, freeShippingCampaign);
+  return {
+    calculatedItems,
+    cartTotal,
+    originalTotal,
+    totalSavings,
+    freeShipping
+  };
+}
+function calculateFreeShipping(cartTotal, campaign) {
+  if (!campaign?.FreeShippingCampaign) {
+    return {
+      isEligible: false,
+      minimumSpend: 0,
+      remainingAmount: 0
+    };
+  }
+  const minimumSpend = campaign.FreeShippingCampaign.minimumSpend;
+  const isEligible = cartTotal >= minimumSpend;
+  const remainingAmount = isEligible ? 0 : minimumSpend - cartTotal;
+  const eligibleShipmentMethodIds = campaign.FreeShippingCampaign.shipmentMethods?.map(
+    (method) => method.id
+  );
+  return {
+    isEligible,
+    minimumSpend,
+    remainingAmount,
+    campaignName: campaign.name,
+    eligibleShipmentMethodIds
   };
 }
 export {
@@ -192,6 +1506,10 @@ export {
   RateLimitError,
   StorefrontError,
   ValidationError,
-  createStorefrontClient
+  VerificationRequiredError,
+  calculateCartWithCampaigns,
+  createStorefrontClient,
+  getPriceInfo,
+  isSaleActive
 };
 //# sourceMappingURL=index.js.map