@caldik/client 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,15 @@
 # Caldik SDK
+TThe official Caldik SDK for interacting with Caldik storefronts, products, carts, checkouts, and customer accounts.
 
-The official Caldik SDK for interacting with Caldik storefronts, products, carts, checkouts, and customer accounts.
+## Installation
 
-## Caldik-hosted Storefront
+```bash
+npm install @caldik/client
+```
+
+## Getting Started
+
+### Caldik-hosted Storefront
 
 No credentials or store configuration are required when running inside a Caldik-hosted storefront.
 
@@ -14,7 +21,7 @@ const caldik = new CaldikClient()
 const { products } = await caldik.products.list()
 ```
 
-## External Server
+### External Server
 
 External integrations must explicitly provide a store ID and a private `sk_` API key.
 
@@ -27,40 +34,196 @@ const caldik = new CaldikClient({
 })
 ```
 
+> **Security:** Private API keys must only be used in trusted server-side environments. Never expose `sk_` keys in client-side code.
+
+
+## Orders and Items
+
+### List Products
+
+Retrieve products associated with the current store.
+
+**Basic usage**
+
+```ts
+const { products } = await caldik.products.list()
+```
+
+**Limit results**
+
+Pass a number to limit the number of products returned.
+
+```ts
+const { products } = await caldik.products.list(20)
+```
+
+### Get Product
+
+Retrieve a specific product by its ID.
+
+**Basic usage**
+
+```ts
+const { product } = await caldik.products.get("product_123")
+```
+
+### Get Category
+
+Retrieve a specific category by its ID.
+
+**Basic usage**
+
+```ts
+const { category } = await caldik.categories.get("CAT_ID")
+```
+
+### List Categories
+
+Retrieve categories associated with the current store.
+
+**Basic usage**
+
+```ts
+const { categories } = await caldik.categories.list()
+```
+
+**Limit results**
+
+Pass a number to limit the number of categories returned.
+
+```ts
+const { categories } = await caldik.categories.list(20)
+```
+
+**Advanced usage**
+
+Use an options object to configure the limit and request additional fields.
+
+```ts
+const { categories } = await caldik.categories.list({
+  limit: 20,
+  include: ["productCount", "startingPrice"],
+})
+```
+
+**Optional fields**
+
+The following fields are omitted by default unless explicitly requested using `include`:
+
+| Field | Description |
+|---|---|
+| `productCount` | Number of products associated with the category. |
+| `startingPrice` | Lowest available product price in the category, in cents. |
+
+
 ## Cart and Discounts
 
 ### Cart Management
 
-Add products to the cart, update quantities, or remove items.
+**Get the cart**
+
+Refresh the current items and applied discount from the server.
 
 ```ts
-const cart = caldik.cart.add({
+const { items, discount } = await caldik.cart.get()
+```
+
+**Add an item**
+
+```ts
+const cart = await caldik.cart.add({
   productId: "PRODUCT_...",
   productVariantId: "PRODUCT_VARIANT_...",
   quantity: 1,
 })
+```
+
+**Update item quantity**
+
+Set an item's quantity. A quantity of zero removes it.
+
+```ts
+await caldik.cart.updateQuantity(cart.items[0].id, 3)
+```
+
+**Remove an item**
+
+```ts
+await caldik.cart.remove(cart.items[0].id)
+```
+
+**Clear the cart**
+
+Remove all items and the applied discount from the persisted cart.
+
+```ts
+await caldik.cart.clear()
+```
 
-// Update item quantity
-caldik.cart.updateQuantity(cart.items[0].id, 3)
+**Check a discount**
 
-// Remove an item
-caldik.cart.remove(cart.items[0].id)
+Get a price and discount quote for the current items without applying the code.
+
+```ts
+const quote = await caldik.cart.checkDiscount("SAVE10")
 ```
 
-### Apply Discounts
+**Apply a discount**
 
-Apply a discount code to the current cart.
+Validate the code and save it to the current cart.
 
 ```ts
-await caldik.cart.applyDiscount("SAVE10")
+const discountedCart = await caldik.cart.applyDiscount("SAVE10")
 ```
 
-### Checkout
+**Remove the discount**
 
-Create a checkout session using the current cart or explicitly provided items.
+Remove the applied code while keeping the cart's items.
+
+```ts
+await caldik.cart.removeDiscount()
+```
+
+**Checkout the cart**
+
+Create an order using the persisted cart. The API revalidates prices and discounts.
 
 ```ts
 const result = await caldik.cart.checkout({
+  paymentMethod: "stripe",
+  termsAccepted: acceptedTermsCheckbox,
+  successUrl: "https://shop.example/success",
+  cancelUrl: "https://shop.example/cart",
+})
+```
+
+### Server-rendered Storefronts
+
+Create a client for each incoming request so shopper sessions stay isolated.
+Pass the request and forward returned session cookies to the outgoing response:
+
+```ts
+const responseHeaders = new Headers()
+const caldik = new CaldikClient({
+  request,
+  onSetCookie: (cookie) => responseHeaders.append("Set-Cookie", cookie),
+  // External servers also supply storeId and their private apiKey.
+})
+const cart = await caldik.cart.get()
+// Include responseHeaders in your framework's HTTP response.
+```
+
+Browser and server calls must share the same cookie context (for example through
+a storefront API proxy). Cookies set only on a separate API hostname are not
+included in requests to the storefront server. A private store key does not
+replace a shopper's customer session.
+
+### Checkout with Explicit Items
+
+Use `caldik.checkout.create()` to create an order from explicitly provided items.
+
+```ts
+const result = await caldik.checkout.create({
   paymentMethod: "stripe",
   items: [
     {
@@ -96,11 +259,24 @@ Username authentication is available through the **Customer Usernames** plugin.
 
 Customers can log in using a six-digit verification code sent to their email address.
 
+**Send a verification code**
+
 ```ts
-// Send a six-digit verification code
 await caldik.customer.login("customer@example.com")
+```
 
-// Verify the code
+Alternatively, use an options object to configure the session.
+
+```ts
+await caldik.customer.login({
+  email: "customer@example.com",
+  rememberMe: true, // Optional, defaults to false
+})
+```
+
+**Verify the code**
+
+```ts
 await caldik.customer.login.verify(code)
 ```
 
@@ -112,6 +288,7 @@ Email and password authentication requires password login to be enabled in the s
 await caldik.customer.login({
   email: "customer@example.com",
   password,
+  rememberMe: true, // Optional, defaults to false
 })
 ```
 
@@ -125,11 +302,58 @@ Once installed, customers can authenticate using their username instead of their
 await caldik.customer.login({
   username: "customer",
   password,
+  rememberMe: true, // Optional, defaults to false
 })
 ```
 
 > **Note:** Username authentication requires both the Customer Usernames plugin and password authentication to be enabled.
 
+### Session Duration
+
+All customer authentication methods support the optional `rememberMe` parameter.
+
+| `rememberMe` | Session Duration |
+|---|---|
+| `false` (default) | 24 hours |
+| `true` | 30 days |
+
+Omit `rememberMe` to use the default session duration.
+
+### Session Check
+
+Retrieve the current customer's authentication status, account details, and session expiration.
+
+```ts
+const {
+  authenticated,
+  customer,
+  expiresAt,
+} = await caldik.customer.session()
+```
+
+### Password Reset
+
+Customers can reset their passwords using a verification code sent to their email address.
+
+**Request a password reset**
+
+```ts
+const { challengeId } =
+  await caldik.customer.password.requestReset(email)
+```
+
+Password reset codes expire after **10 minutes**.
+
+**Reset the password**
+
+```ts
+await caldik.customer.password.reset({
+  challengeId,
+  code,
+  password: newPassword,
+})
+```
+
 ## Customer Registration
 
 Customers can register using their email address, with optional password and username support.
@@ -142,14 +366,18 @@ Password registration must be enabled in the store dashboard.
 
 Register a customer using their email address and password.
 
+**Register a customer**
+
 ```ts
-// Register a new customer
 await caldik.customer.register({
   email: "customer@example.com",
   password,
 })
+```
+
+**Verify the email address**
 
-// Verify the email using the six-digit code
+```ts
 await caldik.customer.register.verify(code)
 ```
 
@@ -159,15 +387,19 @@ To register customers with a username, install and enable the **Customer Usernam
 
 Once installed, the registration endpoint accepts an additional `username` field.
 
+**Register a customer with a username**
+
 ```ts
-// Register a new customer with a username
 await caldik.customer.register({
   email: "customer@example.com",
   password,
   username: "customer",
 })
+```
+
+**Verify the email address**
 
-// Verify the email using the six-digit code
+```ts
 await caldik.customer.register.verify(code)
 ```
 
@@ -179,28 +411,36 @@ Retrieve customer authentication settings, checkout configuration, and available
 
 ### Customer Settings
 
+Retrieve the store's customer authentication settings.
+
 ```ts
 const { settings: loginSettings } = await caldik.customer.settings.get()
 ```
 
 ### Checkout Settings
 
+Retrieve the store's checkout configuration.
+
 ```ts
 const { settings: checkoutSettings } = await caldik.checkout.settings.get()
 ```
 
 ### Available Payment Methods
 
+Retrieve the payment methods available for checkout.
+
 ```ts
 const { paymentMethods } = await caldik.checkout.paymentmethods.list()
 ```
 
 ### Combined Example
 
+Retrieve customer settings, checkout settings, and available payment methods together.
+
 ```ts
 const { settings: loginSettings } = await caldik.customer.settings.get()
 
 const { settings: checkoutSettings } = await caldik.checkout.settings.get()
 
 const { paymentMethods } = await caldik.checkout.paymentmethods.list()
-```
+```

package/dist/index.d.mts

@@ -24,7 +24,10 @@ interface Category {
   name: string;
   slug: string;
   description: string;
-  price: string;
+  /** Present when startingPrice is included. Prefer startingPrice. */
+  price?: string;
+  productCount?: number;
+  startingPrice?: string | null;
   logo: string | null;
   banner: string | null;
   metadata: CategoryMetadata[];
@@ -33,6 +36,11 @@ interface CategoriesResponse {
   success: boolean;
   categories: Category[];
 }
+type CategoryInclude = "productCount" | "startingPrice" | "product count" | "starting price";
+interface CategoryListOptions {
+  limit?: number;
+  include?: readonly CategoryInclude[];
+}
 interface CategoryProduct {
   id: string;
   name: string;
@@ -245,10 +253,41 @@ interface CustomerPasswordResponse extends CustomerLoginVerifyResponse {
     extensions?: Record<string, Record<string, string | number | boolean>>;
   };
 }
-interface CustomerPasswordInput {
-  /** A username from an installed identity plugin, or the customer's email. */
+type CustomerPasswordInput = ({
   username: string;
+  email?: never;
+} | {
+  email: string;
+  username?: never;
+}) & {
   password: string;
+  rememberMe?: boolean;
+};
+interface CustomerEmailLoginInput {
+  email: string;
+  rememberMe?: boolean;
+}
+interface CustomerSessionResponse {
+  success: boolean;
+  authenticated: boolean;
+  customer: {
+    id: string;
+    email: string | null;
+  } | null;
+  expiresAt: number | null;
+}
+interface CustomerPasswordResetResponse extends CustomerLoginResponse {
+  expiresAt: number;
+  message: string;
+}
+interface CustomerPasswordResetInput {
+  challengeId?: string;
+  code: string;
+  password: string;
+}
+interface CustomerPasswordResetVerifyResponse {
+  success: boolean;
+  message: string;
 }
 interface CustomerRegistrationInput {
   email: string;
@@ -310,6 +349,8 @@ interface RequestOptions {
   edgeCache?: boolean;
   /** Internal authorization policy. Protected hosted calls are the default. */
   access?: "public" | "runtime";
+  /** Scoped credentials used by stateful storefront resources. */
+  headers?: Record<string, string>;
 }
 //#endregion
 //#region src/internal/client.d.ts
@@ -317,13 +358,22 @@ type HttpClientOptions = {
   apiKey?: string;
   apiUrl?: string;
   storeId?: string;
+  request?: Request;
+  onSetCookie?: (cookie: string) => void | Promise<void>;
 };
 declare class CaldikHttpClient {
   private readonly apiKey?;
   private readonly apiUrl;
   private readonly storeId?;
+  private readonly cookies;
+  private readonly onSetCookie?;
+  private readonly authenticationListeners;
   constructor(options?: HttpClientOptions);
   storeContextId(): string | null;
+  hasCartSession(): boolean;
+  onCustomerAuthentication(listener: () => Promise<unknown>): void;
+  customerAuthenticated(): Promise<void>;
+  private captureCookies;
   private baseUrl;
   private request;
   get<T>(path: string, params?: Record<string, string | number>, options?: RequestOptions): Promise<T>;
@@ -334,7 +384,7 @@ declare class CaldikHttpClient {
 declare class CategoriesApi {
   private client;
   constructor(client: CaldikHttpClient);
-  list(limit?: number): Promise<CategoriesResponse>;
+  list(options?: number | CategoryListOptions): Promise<CategoriesResponse>;
   get(categoryId: string): Promise<CategoryResponse>;
 }
 //#endregion
@@ -381,7 +431,10 @@ declare class CustomerApi {
     get: () => Promise<CustomerLoginSettingsResponse>;
   };
   readonly login: {
-    (email: string): Promise<CustomerLoginResponse>;
+    (email: string, options?: {
+      rememberMe?: boolean;
+    }): Promise<CustomerLoginResponse>;
+    (input: CustomerEmailLoginInput): Promise<CustomerLoginResponse>;
     (input: CustomerPasswordInput): Promise<CustomerPasswordResponse>;
   } & {
     /** Pass challengeId to resume a code request after reloading the page. */verify: (code: string, challengeId?: string | undefined) => Promise<CustomerLoginVerifyResponse>;
@@ -392,7 +445,13 @@ declare class CustomerApi {
   } & {
     /** Verify the email and atomically activate the account. Supports resuming after a reload. */verify: (code: string, challengeId?: string | undefined) => Promise<CustomerPasswordResponse>;
   };
+  readonly password: {
+    requestReset: (email: string) => Promise<CustomerPasswordResetResponse>;
+    reset: (input: CustomerPasswordResetInput) => Promise<CustomerPasswordResetVerifyResponse>;
+  };
   constructor(client: CaldikHttpClient);
+  /** Check a store-scoped session without raising an error for signed-out customers. */
+  session(): Promise<CustomerSessionResponse>;
   /** Read the signed-in customer and their balances. */
   me(): Promise<CustomerProfileResponse>;
 }
@@ -428,10 +487,8 @@ declare class DiscountsApi {
 }
 //#endregion
 //#region src/cart.d.ts
-interface CartItem {
+interface CartItem extends ProductCommerceItem {
   id: string;
-  productId: string;
-  productVariantId?: string;
   quantity: number;
 }
 interface CartDiscount {
@@ -446,24 +503,35 @@ interface CartSnapshot {
   items: CartItem[];
   discount: CartDiscount | null;
 }
-type CartCheckoutInput = Omit<CreateOrderInput, "items" | "discountCode">;
+type CartCheckoutInput = Omit<CreateOrderInput, "items" | "discountCode" | "customerId">;
+/** One persisted cart, automatically scoped to the current shopper session. */
 declare class CartApi {
   private client;
-  private memory;
+  private cache;
+  private queue;
+  private initialized;
   constructor(client: CaldikHttpClient);
-  private storageKey;
-  private read;
+  private storage;
+  private key;
+  private readCache;
+  private persistCache;
   private write;
-  get(): CartSnapshot;
-  add(item: ProductCommerceItem): CartSnapshot;
-  updateQuantity(itemId: string, nextQuantity: number): CartSnapshot;
-  remove(itemId: string): CartSnapshot;
-  clear(): CartSnapshot;
-  private commerceItems;
+  private enqueue;
+  private options;
+  private resolve;
+  private reset;
+  private mutate;
+  private save;
+  private quote;
+  get(): Promise<CartSnapshot>;
+  add(item: ProductCommerceItem): Promise<CartSnapshot>;
+  updateQuantity(itemId: string, nextQuantity: number): Promise<CartSnapshot>;
+  remove(itemId: string): Promise<CartSnapshot>;
+  clear(): Promise<CartSnapshot>;
   checkDiscount(code: string): Promise<DiscountQuoteResponse>;
   applyDiscount(code: string): Promise<CartSnapshot>;
-  removeDiscount(): CartSnapshot;
-  checkout(input: CartCheckoutInput): Promise<OrderResponse>;
+  removeDiscount(): Promise<CartSnapshot>;
+  checkout(input?: CartCheckoutInput): Promise<OrderResponse>;
 }
 //#endregion
 //#region src/index.d.ts
@@ -473,6 +541,10 @@ interface CaldikClientOptions {
   /** Private API key for external server integrations. Never use in browsers. */
   apiKey?: string;
   apiUrl?: string;
+  /** Incoming storefront request. Create one client per server request to isolate shoppers. */
+  request?: Request;
+  /** Forward session cookies to the outgoing storefront response in server code. */
+  onSetCookie?: (cookie: string) => void | Promise<void>;
 }
 declare class CaldikClient {
   readonly categories: CategoriesApi;
@@ -487,4 +559,4 @@ declare class CaldikClient {
   constructor(options?: CaldikClientOptions);
 }
 //#endregion
-export { AppliedDiscount, CaldikClient, CaldikClientOptions, CartApi, CartCheckoutInput, CartDiscount, CartItem, CartSnapshot, CategoriesResponse, Category, CategoryDetails, CategoryMetadata, CategoryProduct, CategoryResponse, CheckDiscountInput, CheckoutPayment, CheckoutPaymentMethod, CheckoutPaymentMethodsResponse, CheckoutPaymentProviderId, CheckoutSettings, CheckoutSettingsResponse, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerLoginResponse, CustomerLoginSettings, CustomerLoginSettingsResponse, CustomerLoginVerifyResponse, CustomerPasswordInput, CustomerPasswordResponse, CustomerProfileResponse, CustomerRegistrationInput, CustomerRegistrationResponse, DiscountQuoteResponse, DiscountsApi, ManualCommerceItem, OrderResponse, PaymentProviderId, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreWebhookEvent, StoreWebhookEventName, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };
+export { AppliedDiscount, CaldikClient, CaldikClientOptions, CartApi, CartCheckoutInput, CartDiscount, CartItem, CartSnapshot, CategoriesResponse, Category, CategoryDetails, CategoryInclude, CategoryListOptions, CategoryMetadata, CategoryProduct, CategoryResponse, CheckDiscountInput, CheckoutPayment, CheckoutPaymentMethod, CheckoutPaymentMethodsResponse, CheckoutPaymentProviderId, CheckoutSettings, CheckoutSettingsResponse, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerEmailLoginInput, CustomerLoginResponse, CustomerLoginSettings, CustomerLoginSettingsResponse, CustomerLoginVerifyResponse, CustomerPasswordInput, CustomerPasswordResetInput, CustomerPasswordResetResponse, CustomerPasswordResetVerifyResponse, CustomerPasswordResponse, CustomerProfileResponse, CustomerRegistrationInput, CustomerRegistrationResponse, CustomerSessionResponse, DiscountQuoteResponse, DiscountsApi, ManualCommerceItem, OrderResponse, PaymentProviderId, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreWebhookEvent, StoreWebhookEventName, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };

package/dist/index.mjs

@@ -26,6 +26,14 @@ function defaultApiUrl(browser) {
 //#region src/internal/client.ts
 const STORE_ID_PATTERN = /^STORE_[a-f0-9]{32}$/i;
 const STOREFRONT_STORE_ID_ATTRIBUTE = "data-caldik-store-id";
+var CaldikHttpError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "CaldikHttpError";
+	}
+};
 function isBrowserRuntime() {
 	return typeof window !== "undefined" && typeof document !== "undefined";
 }
@@ -48,9 +56,17 @@ var CaldikHttpClient = class {
 	apiKey;
 	apiUrl;
 	storeId;
+	cookies = /* @__PURE__ */ new Map();
+	onSetCookie;
+	authenticationListeners = /* @__PURE__ */ new Set();
 	constructor(options = {}) {
 		this.apiKey = options.apiKey?.trim() || void 0;
 		this.apiUrl = options.apiUrl || defaultApiUrl(isBrowserRuntime());
+		this.onSetCookie = options.onSetCookie;
+		if (!isBrowserRuntime()) for (const part of (options.request?.headers.get("Cookie") || "").split(";")) {
+			const separator = part.indexOf("=");
+			if (separator > 0) this.cookies.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+		}
 		const configuredStoreId = options.storeId?.trim() || void 0;
 		if (this.apiKey && !this.apiKey.startsWith("sk_")) throw new Error("Caldik external integrations require a private sk_ API key");
 		if (configuredStoreId && !STORE_ID_PATTERN.test(configuredStoreId)) throw new Error("Caldik storeId is invalid");
@@ -60,6 +76,31 @@ var CaldikHttpClient = class {
 	storeContextId() {
 		return this.storeId || boundRuntimeStoreId();
 	}
+	hasCartSession() {
+		return this.cookies.has(`caldik_cart_session_${this.storeContextId()}`);
+	}
+	onCustomerAuthentication(listener) {
+		this.authenticationListeners.add(listener);
+	}
+	async customerAuthenticated() {
+		await Promise.allSettled([...this.authenticationListeners].map((listener) => listener()));
+	}
+	async captureCookies(response) {
+		for (const cookie of response.headers.getSetCookie()) {
+			const [pair = "", ...attributes] = cookie.split(";");
+			const separator = pair.indexOf("=");
+			if (separator < 1) continue;
+			const name = pair.slice(0, separator).trim();
+			if (attributes.some((attribute) => {
+				const [key, ...value] = attribute.trim().split("=");
+				if (key?.toLowerCase() === "max-age") return Number(value.join("=")) <= 0;
+				if (key?.toLowerCase() === "expires") return Date.parse(value.join("=")) <= Date.now();
+				return false;
+			})) this.cookies.delete(name);
+			else this.cookies.set(name, pair.slice(separator + 1).trim());
+			await this.onSetCookie?.(cookie);
+		}
+	}
 	baseUrl() {
 		if (isBrowserRuntime()) {
 			const storeId = this.storeId;
@@ -76,8 +117,9 @@ var CaldikHttpClient = class {
 	async request(method, path, input, params, options) {
 		const url = new URL(`${this.baseUrl()}${path}`);
 		if (params) for (const [key, value] of Object.entries(params)) url.searchParams.set(key, String(value));
-		const headers = {};
+		const headers = { ...options?.headers };
 		if (!isBrowserRuntime()) headers["User-Agent"] = "CaldikClient/0.0.2";
+		if (!isBrowserRuntime() && options?.access === "public" && this.cookies.size) headers.Cookie = [...this.cookies].map(([name, value]) => `${name}=${value}`).join("; ");
 		if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
 		else if (options?.access === "public" && (!isBrowserRuntime() || isLocalBrowserRuntime())) headers["X-Caldik-Public-Request"] = "1";
 		if (input !== void 0) headers["Content-Type"] = "application/json";
@@ -89,10 +131,10 @@ var CaldikHttpClient = class {
 			cache: "default",
 			credentials: "include"
 		});
+		if (!isBrowserRuntime() && options?.access === "public") await this.captureCookies(response);
 		if (!response.ok) {
 			const error = await response.clone().json().catch(() => null);
-			const message = typeof error?.message === "string" && error.message ? error.message : `${response.status} ${response.statusText}`.trim();
-			throw new Error(message);
+			throw new CaldikHttpError(typeof error?.message === "string" && error.message ? error.message : `${response.status} ${response.statusText}`.trim(), response.status);
 		}
 		return response.json();
 	}
@@ -110,8 +152,12 @@ var CategoriesApi = class {
 	constructor(client) {
 		this.client = client;
 	}
-	list(limit) {
-		return this.client.get("/categories", limit ? { limit } : void 0, { access: "public" });
+	list(options) {
+		const { limit, include } = typeof options === "number" ? { limit: options } : options ?? {};
+		return this.client.get("/categories", {
+			...limit !== void 0 ? { limit } : {},
+			...include?.length ? { include: include.join(",") } : {}
+		}, { access: "public" });
 	}
 	get(categoryId) {
 		return this.client.get(`/categories/${categoryId}`, void 0, { access: "public" });
@@ -178,13 +224,40 @@ var CustomerApi = class {
 	settings;
 	login;
 	register;
+	password;
 	constructor(client) {
 		this.client = client;
 		this.settings = { get: () => this.client.get("/customers/settings", void 0, { access: "public" }) };
+		let pendingResetId;
+		this.password = {
+			requestReset: async (email) => {
+				const response = await client.post("/customers/password/reset", { email }, { access: "public" });
+				pendingResetId = response.challengeId;
+				return response;
+			},
+			reset: async (input) => {
+				const challengeId = input.challengeId ?? pendingResetId;
+				if (!challengeId) throw new Error("Request a password reset first or provide its challengeId");
+				if (!/^\d{6}$/.test(input.code)) throw new Error("A six-digit reset code is required");
+				const response = await client.post("/customers/password/reset/verify", {
+					...input,
+					challengeId
+				}, { access: "public" });
+				if (pendingResetId === challengeId) pendingResetId = void 0;
+				return response;
+			}
+		};
 		let pendingChallengeId;
-		async function login(input) {
-			if (typeof input !== "string") return client.post("/customers/login/password", input, { access: "public" });
-			const response = await client.post("/customers/login", { email: input }, { access: "public" });
+		async function login(input, options) {
+			if (typeof input !== "string" && "password" in input) {
+				const response = await client.post("/customers/login/password", input, { access: "public" });
+				await client.customerAuthenticated();
+				return response;
+			}
+			const response = await client.post("/customers/login", typeof input === "string" ? {
+				email: input,
+				...options
+			} : input, { access: "public" });
 			pendingChallengeId = response.challengeId;
 			return response;
 		}
@@ -198,6 +271,7 @@ verify: async (code, challengeId = pendingChallengeId) => {
 				challengeId
 			}, { access: "public" });
 			if (pendingChallengeId === challengeId) pendingChallengeId = void 0;
+			await client.customerAuthenticated();
 			return response;
 		} });
 		let pendingRegistrationId;
@@ -216,9 +290,14 @@ verify: async (code, challengeId = pendingRegistrationId) => {
 				challengeId
 			}, { access: "public" });
 			if (pendingRegistrationId === challengeId) pendingRegistrationId = void 0;
+			await client.customerAuthenticated();
 			return response;
 		} });
 	}
+	/** Check a store-scoped session without raising an error for signed-out customers. */
+	session() {
+		return this.client.get("/customers/session", void 0, { access: "public" });
+	}
 	/** Read the signed-in customer and their balances. */
 	me() {
 		return this.client.get("/customers/me", void 0, { access: "public" });
@@ -248,20 +327,18 @@ var DiscountsApi = class {
 };
 //#endregion
 //#region src/cart.ts
-const CART_VERSION = 1;
 const MAX_QUANTITY = 999999;
-function cartItemId(item) {
-	return item.productVariantId ? `${item.productId}:${item.productVariantId}` : item.productId;
-}
-function quantity(value, allowZero = false) {
-	const normalized = value ?? 1;
+function quantity(value = 1, allowZero = false) {
 	const minimum = allowZero ? 0 : 1;
-	if (!Number.isInteger(normalized) || normalized < minimum || normalized > MAX_QUANTITY) throw new Error(`Cart quantity must be an integer between ${minimum} and ${MAX_QUANTITY}`);
-	return normalized;
+	if (!Number.isInteger(value) || value < minimum || value > MAX_QUANTITY) throw new Error(`Cart quantity must be an integer between ${minimum} and ${MAX_QUANTITY}`);
+	return value;
 }
 function cloneSnapshot(state) {
 	return {
-		items: state.items.map((item) => ({ ...item })),
+		items: state.items.map((item) => ({
+			...item,
+			...item.customFields ? { customFields: { ...item.customFields } } : {}
+		})),
 		discount: state.discount ? { ...state.discount } : null
 	};
 }
@@ -272,140 +349,267 @@ function isCartItem(value) {
 }
 function isCartDiscount(value) {
 	if (!value || typeof value !== "object") return false;
-	const discount = value;
-	return typeof discount.code === "string" && typeof discount.percentage === "string" && typeof discount.subtotal === "string" && typeof discount.discountAmount === "string" && typeof discount.total === "string" && typeof discount.currency === "string";
+	return [
+		"code",
+		"percentage",
+		"subtotal",
+		"discountAmount",
+		"total",
+		"currency"
+	].every((key) => typeof value[key] === "string");
 }
+function isReference(value) {
+	if (!value || typeof value !== "object") return false;
+	const reference = value;
+	return typeof reference.id === "string" && /^CART_[a-f0-9]{32}$/.test(reference.id) && (reference.token == null || typeof reference.token === "string");
+}
+function commerceItems(items) {
+	return items.map(({ id: _id, ...item }) => item);
+}
+function discountFromQuote(quote) {
+	return {
+		...quote.discount,
+		subtotal: quote.subtotal,
+		discountAmount: quote.discountAmount,
+		total: quote.total,
+		currency: quote.currency
+	};
+}
+/** One persisted cart, automatically scoped to the current shopper session. */
 var CartApi = class {
 	client;
-	memory = {
-		version: CART_VERSION,
-		items: [],
-		discount: null
+	cache = {
+		version: 2,
+		reference: null,
+		snapshot: {
+			items: [],
+			discount: null
+		}
 	};
+	queue = Promise.resolve();
+	initialized = false;
 	constructor(client) {
 		this.client = client;
+		client.onCustomerAuthentication(() => {
+			this.readCache();
+			return this.initialized || this.cache.reference || this.cache.snapshot.items.length || client.hasCartSession() ? this.enqueue(async () => {
+				await this.resolve();
+			}) : Promise.resolve();
+		});
+	}
+	storage() {
+		try {
+			return typeof window !== "undefined" && typeof document !== "undefined" && typeof localStorage !== "undefined" ? localStorage : null;
+		} catch {
+			return null;
+		}
 	}
-	storageKey() {
-		const storeId = this.client.storeContextId();
-		return storeId ? `caldik:cart:${storeId}` : null;
-	}
-	read() {
-		const key = this.storageKey();
-		if (key && typeof localStorage !== "undefined") try {
-			const value = localStorage.getItem(key);
-			if (value) {
-				const parsed = JSON.parse(value);
-				if (parsed.version === CART_VERSION && Array.isArray(parsed.items) && parsed.items.every(isCartItem)) this.memory = {
-					version: CART_VERSION,
+	key() {
+		return `caldik:cart:${this.client.storeContextId()}`;
+	}
+	readCache() {
+		const storage = this.storage();
+		if (!storage) return;
+		try {
+			const parsed = JSON.parse(storage.getItem(this.key()) || "null");
+			if (parsed?.version === 2) {
+				const snapshot = parsed.snapshot;
+				if (snapshot && Array.isArray(snapshot.items) && snapshot.items.every(isCartItem) && (parsed.reference === null || isReference(parsed.reference))) this.cache = {
+					version: 2,
+					reference: parsed.reference,
+					snapshot: cloneSnapshot({
+						items: snapshot.items,
+						discount: isCartDiscount(snapshot.discount) ? snapshot.discount : null
+					})
+				};
+			} else if (parsed?.version === 1 && Array.isArray(parsed.items) && parsed.items.every(isCartItem)) this.cache = {
+				version: 2,
+				reference: null,
+				snapshot: cloneSnapshot({
 					items: parsed.items,
 					discount: isCartDiscount(parsed.discount) ? parsed.discount : null
-				};
+				})
+			};
+			if (!this.cache.reference) {
+				const legacy = JSON.parse(storage.getItem(`caldik:server-cart:${this.client.storeContextId()}`) || "null");
+				if (isReference(legacy)) this.cache.reference = legacy;
 			}
 		} catch {}
-		return this.memory;
 	}
-	write(state) {
-		this.memory = {
-			version: CART_VERSION,
-			...cloneSnapshot(state)
-		};
-		const key = this.storageKey();
-		if (key && typeof localStorage !== "undefined") try {
-			localStorage.setItem(key, JSON.stringify(this.memory));
+	persistCache() {
+		try {
+			const storage = this.storage();
+			storage?.setItem(this.key(), JSON.stringify(this.cache));
+			storage?.removeItem(`caldik:server-cart:${this.client.storeContextId()}`);
 		} catch {}
-		return this.get();
+	}
+	write(cart, token = this.cache.reference?.token, discount = null) {
+		this.cache = {
+			version: 2,
+			reference: {
+				id: cart.id,
+				token: cart.customerId ? null : token
+			},
+			snapshot: cloneSnapshot({
+				items: cart.items,
+				discount
+			})
+		};
+		this.persistCache();
+		return cloneSnapshot(this.cache.snapshot);
+	}
+	enqueue(operation) {
+		const run = () => {
+			const locks = this.storage() && typeof navigator !== "undefined" ? navigator.locks : void 0;
+			return locks ? locks.request(this.key(), operation) : operation();
+		};
+		const result = this.queue.then(run, run);
+		this.queue = result.catch(() => void 0);
+		return result;
+	}
+	options() {
+		return {
+			access: "public",
+			...this.cache.reference?.token ? { headers: { "X-Caldik-Cart-Token": this.cache.reference.token } } : {}
+		};
+	}
+	async resolve(checkout = false, seed = true) {
+		this.readCache();
+		const input = this.cache.reference ? { cartId: this.cache.reference.id } : seed && this.cache.snapshot.items.length ? {
+			items: commerceItems(this.cache.snapshot.items),
+			discountCode: this.cache.snapshot.discount?.code
+		} : {};
+		const response = await this.client.post("/carts/session", {
+			...input,
+			...checkout ? { checkout: true } : {}
+		}, this.options());
+		this.initialized = true;
+		this.write(response.cart, response.token ?? null);
+		if (!checkout && response.cart.status === "checked_out") {
+			this.reset();
+			return this.resolve(false, false);
+		}
+		return response.cart;
+	}
+	reset() {
+		this.cache = {
+			version: 2,
+			reference: null,
+			snapshot: {
+				items: [],
+				discount: null
+			}
+		};
+		this.persistCache();
+	}
+	async mutate(operation, seed = true) {
+		let cart = await this.resolve(false, seed);
+		let response;
+		try {
+			response = await operation(cart);
+		} catch (error) {
+			if (!(error instanceof CaldikHttpError) || error.status !== 409) throw error;
+			const refreshed = await this.resolve();
+			if (refreshed.id !== cart.id || refreshed.status !== "active") throw error;
+			cart = refreshed;
+			response = await operation(cart);
+		}
+		return this.write(response.cart);
+	}
+	save(cart, items, discountCode) {
+		return this.client.post(`/carts/${cart.id}`, {
+			items: commerceItems(items),
+			version: cart.version,
+			discountCode
+		}, this.options());
+	}
+	quote(cart, code) {
+		if (!cart.items.length) throw new Error("Cannot check a discount on an empty cart");
+		return this.client.post("/discounts/check", {
+			code,
+			items: commerceItems(cart.items)
+		}, { access: "public" });
 	}
 	get() {
-		return cloneSnapshot(this.read());
+		return this.enqueue(async () => {
+			let cart = await this.resolve();
+			let discount = null;
+			if (cart.discountCode) try {
+				discount = discountFromQuote(await this.quote(cart, cart.discountCode));
+			} catch (error) {
+				if (!(error instanceof CaldikHttpError) || ![
+					400,
+					404,
+					422
+				].includes(error.status)) throw error;
+				cart = (await this.save(cart, cart.items, null)).cart;
+			}
+			return this.write(cart, this.cache.reference?.token, discount);
+		});
 	}
 	add(item) {
-		const productId = item.productId.trim();
-		const productVariantId = item.productVariantId?.trim() || "";
-		if (!productId) throw new Error("Cart productId is required");
-		const state = this.get();
-		const id = cartItemId({
-			productId,
-			productVariantId
+		return this.enqueue(async () => {
+			if (!item.productId.trim()) throw new Error("Cart productId is required");
+			const normalized = {
+				...item,
+				productId: item.productId.trim(),
+				quantity: quantity(item.quantity)
+			};
+			return this.mutate((cart) => this.client.post(`/carts/${cart.id}/items`, {
+				item: normalized,
+				version: cart.version
+			}, this.options()));
 		});
-		const existing = state.items.find((entry) => entry.id === id);
-		const addedQuantity = quantity(item.quantity);
-		if (existing) existing.quantity = quantity(existing.quantity + addedQuantity);
-		else state.items.push({
-			id,
-			productId,
-			...productVariantId ? { productVariantId } : {},
-			quantity: addedQuantity
-		});
-		state.discount = null;
-		return this.write(state);
 	}
 	updateQuantity(itemId, nextQuantity) {
-		const state = this.get();
-		const normalized = quantity(nextQuantity, true);
-		const index = state.items.findIndex((item) => item.id === itemId);
-		if (index === -1) throw new Error("Cart item not found");
-		if (normalized === 0) state.items.splice(index, 1);
-		else state.items[index].quantity = normalized;
-		state.discount = null;
-		return this.write(state);
+		return this.enqueue(async () => {
+			const normalized = quantity(nextQuantity, true);
+			return this.mutate((cart) => {
+				if (!cart.items.some((item) => item.id === itemId)) throw new Error("Cart item not found");
+				const items = cart.items.map((item) => item.id === itemId ? {
+					...item,
+					quantity: normalized
+				} : item).filter((item) => item.quantity > 0);
+				return this.save(cart, items, null);
+			});
+		});
 	}
 	remove(itemId) {
-		const state = this.get();
-		const items = state.items.filter((item) => item.id !== itemId);
-		if (items.length === state.items.length) throw new Error("Cart item not found");
-		return this.write({
-			items,
-			discount: null
-		});
+		return this.updateQuantity(itemId, 0);
 	}
 	clear() {
-		return this.write({
-			items: [],
-			discount: null
+		return this.enqueue(() => this.mutate((cart) => this.save(cart, [], null), false));
+	}
+	checkDiscount(code) {
+		return this.enqueue(async () => this.quote(await this.resolve(), code));
+	}
+	applyDiscount(code) {
+		return this.enqueue(async () => {
+			let quote;
+			const snapshot = await this.mutate(async (cart) => {
+				quote = await this.quote(cart, code);
+				return this.save(cart, cart.items, quote.discount.code);
+			});
+			snapshot.discount = discountFromQuote(quote);
+			this.cache.snapshot = cloneSnapshot(snapshot);
+			this.persistCache();
+			return snapshot;
 		});
 	}
-	commerceItems() {
-		return this.get().items.map(({ productId, productVariantId, quantity }) => ({
-			productId,
-			...productVariantId ? { productVariantId } : {},
-			quantity
-		}));
-	}
-	async checkDiscount(code) {
-		const items = this.commerceItems();
-		if (items.length === 0) throw new Error("Cannot check a discount on an empty cart");
-		return this.client.post("/discounts/check", {
-			code,
-			items
-		}, { access: "public" });
-	}
-	async applyDiscount(code) {
-		const quote = await this.checkDiscount(code);
-		const state = this.get();
-		state.discount = {
-			...quote.discount,
-			subtotal: quote.subtotal,
-			discountAmount: quote.discountAmount,
-			total: quote.total,
-			currency: quote.currency
-		};
-		return this.write(state);
-	}
 	removeDiscount() {
-		const state = this.get();
-		state.discount = null;
-		return this.write(state);
-	}
-	async checkout(input) {
-		const state = this.get();
-		if (state.items.length === 0) throw new Error("Cannot checkout an empty cart");
-		const response = await this.client.post("/checkouts", {
-			...input,
-			items: this.commerceItems(),
-			...state.discount ? { discountCode: state.discount.code } : {}
-		}, { access: "public" });
-		this.clear();
-		return response;
+		return this.enqueue(() => this.mutate((cart) => this.save(cart, cart.items, null)));
+	}
+	checkout(input = {}) {
+		return this.enqueue(async () => {
+			const cart = await this.resolve(true);
+			if (!cart.items.length) throw new Error("Cannot checkout an empty cart");
+			const response = await this.client.post(`/carts/${cart.id}/checkout`, {
+				...input,
+				version: cart.version
+			}, this.options());
+			this.reset();
+			return response;
+		});
 	}
 };
 //#endregion
@@ -466,7 +670,9 @@ var CaldikClient = class {
 		const client = new CaldikHttpClient({
 			apiKey: options.apiKey,
 			apiUrl: options.apiUrl,
-			storeId: options.storeId
+			storeId: options.storeId,
+			request: options.request,
+			onSetCookie: options.onSetCookie
 		});
 		this.categories = new CategoriesApi(client);
 		this.products = new ProductsApi(client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caldik/client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",