@commercengine/storefront-sdk 0.13.3 → 0.14.0

package/dist/index.iife.js

@@ -1,6 +1,6 @@
 var CE_SDK = (function(exports) {
 
-Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region ../../node_modules/.pnpm/openapi-fetch@0.17.0/node_modules/openapi-fetch/dist/index.mjs
 	const PATH_PARAM_RE = /\{[^{}]+\}/g;
@@ -455,7 +455,6 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 	*/
 	var DebugLogger = class {
 		logger;
-		responseTextCache = /* @__PURE__ */ new Map();
 		constructor(logger) {
 			this.logger = logger || ((level, message, data) => {
 				console.log(`[${level.toUpperCase()}]`, message);
@@ -478,7 +477,6 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* Log debug information about API response
 		*/
 		async logResponse(response, responseBody) {
-			if (responseBody && typeof responseBody === "string") this.responseTextCache.set(response.url, responseBody);
 			this.logger("info", "API Response Debug Info", {
 				url: response.url,
 				status: response.status,
@@ -502,17 +500,17 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 			this.logger("error", message, error);
 		}
 		/**
-		* Get cached response text for a URL (if available)
+		* Compatibility shim retained for older internal callers.
+		* Response bodies are no longer cached by the debug logger.
 		*/
-		getCachedResponseText(url) {
-			return this.responseTextCache.get(url) || null;
+		getCachedResponseText(_url) {
+			return null;
 		}
 		/**
-		* Clear cached response texts
+		* Compatibility shim retained for older internal callers.
+		* Response bodies are no longer cached by the debug logger.
 		*/
-		clearCache() {
-			this.responseTextCache.clear();
-		}
+		clearCache() {}
 		info(message, data) {
 			this.logger("info", message, data);
 		}
@@ -598,14 +596,33 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 	* @returns Middleware object with onRequest handler
 	*/
 	function createTimeoutMiddleware(timeoutMs) {
-		return { onRequest: async ({ request }) => {
-			const controller = new AbortController();
-			const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-			if (request.signal) request.signal.addEventListener("abort", () => controller.abort());
-			const newRequest = new Request(request, { signal: controller.signal });
-			controller.signal.addEventListener("abort", () => clearTimeout(timeoutId));
-			return newRequest;
-		} };
+		const timeouts = /* @__PURE__ */ new WeakMap();
+		const clearRequestTimeout = (signal) => {
+			const timeoutId = timeouts.get(signal);
+			if (timeoutId) {
+				clearTimeout(timeoutId);
+				timeouts.delete(signal);
+			}
+		};
+		return {
+			onRequest: async ({ request }) => {
+				const controller = new AbortController();
+				const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+				if (request.signal) request.signal.addEventListener("abort", () => controller.abort(), { once: true });
+				const newRequest = new Request(request, { signal: controller.signal });
+				timeouts.set(newRequest.signal, timeoutId);
+				controller.signal.addEventListener("abort", () => clearRequestTimeout(newRequest.signal), { once: true });
+				return newRequest;
+			},
+			onResponse: async ({ request, response }) => {
+				clearRequestTimeout(request.signal);
+				return response;
+			},
+			onError: async ({ request, error }) => {
+				clearRequestTimeout(request.signal);
+				throw error;
+			}
+		};
 	}
 	/**
 	* Transform headers using a transformation mapping
@@ -671,8 +688,8 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 			};
 		} catch (err) {
 			const mockResponse = new Response(null, {
-				status: 0,
-				statusText: "Network Error"
+				status: 503,
+				statusText: "Service Unavailable"
 			});
 			return {
 				data: null,
@@ -792,619 +809,228 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 	}
 
 //#endregion
-//#region src/lib/jwt-utils.ts
+//#region src/lib/shared/url-utils.ts
 /**
-	* Decode a JWT token payload without signature verification.
-	* This is a lightweight replacement for jose's decodeJwt.
-	*
-	* @param token - The JWT token to decode
-	* @returns The decoded payload
-	* @throws Error if the token is malformed
+	* URL utility functions for the Storefront SDK
 	*/
-	function decodeJwt(token) {
-		if (typeof token !== "string") throw new Error("Invalid token: must be a string");
-		const parts = token.split(".");
-		if (parts.length !== 3) throw new Error("Invalid token: must have 3 parts");
-		const base64Url = parts[1];
-		if (!base64Url) throw new Error("Invalid token: missing payload");
-		let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
-		const padding = base64.length % 4;
-		if (padding) base64 += "=".repeat(4 - padding);
-		const binaryStr = atob(base64);
-		const bytes = new Uint8Array(binaryStr.length);
-		for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i);
-		const payload = JSON.parse(new TextDecoder().decode(bytes));
-		if (typeof payload !== "object" || payload === null) throw new Error("Invalid token: payload must be an object");
-		return payload;
-	}
 	/**
-	* Decode and extract user information from a JWT token
-	* 
-	* @param token - The JWT token to decode
-	* @returns User information or null if token is invalid
+	* Available API environments for Commerce Engine
 	*/
-	function extractUserInfoFromToken(token) {
-		try {
-			const payload = decodeJwt(token);
-			return {
-				id: payload.ulid,
-				email: payload.email,
-				phone: payload.phone,
-				username: payload.username,
-				firstName: payload.first_name,
-				lastName: payload.last_name,
-				storeId: payload.store_id,
-				isLoggedIn: payload.is_logged_in,
-				isAnonymous: payload.is_anonymous,
-				customerId: payload.customer_id,
-				customerGroupId: payload.customer_group_id,
-				anonymousId: payload.anonymous_id,
-				channel: payload.channel,
-				tokenExpiry: /* @__PURE__ */ new Date(payload.exp * 1e3),
-				tokenIssuedAt: /* @__PURE__ */ new Date(payload.iat * 1e3)
-			};
-		} catch (error) {
-			console.warn("Failed to decode JWT token:", error);
-			return null;
-		}
-	}
+	let Environment = /* @__PURE__ */ function(Environment) {
+		/**
+		* Staging environment
+		*/
+		Environment["Staging"] = "staging";
+		/**
+		* Production environment
+		*/
+		Environment["Production"] = "production";
+		return Environment;
+	}({});
 	/**
-	* Check if a JWT token is expired
-	* 
-	* @param token - The JWT token to check
-	* @param bufferSeconds - Buffer time in seconds (default: 30)
-	* @returns True if token is expired or will expire within buffer time
+	* Build base URL for Storefront API
 	*/
-	function isTokenExpired(token, bufferSeconds = 30) {
-		try {
-			const payload = decodeJwt(token);
-			if (!payload.exp) return true;
-			return Math.floor(Date.now() / 1e3) >= payload.exp - bufferSeconds;
-		} catch (error) {
-			console.warn("Failed to decode JWT token:", error);
-			return true;
+	function buildStorefrontURL(config) {
+		if (config.baseUrl) return config.baseUrl;
+		switch (config.environment || Environment.Production) {
+			case Environment.Staging: return `https://staging.api.commercengine.io/api/v1/${config.storeId}/storefront`;
+			case Environment.Production:
+			default: return `https://prod.api.commercengine.io/api/v1/${config.storeId}/storefront`;
 		}
 	}
-	/**
-	* Get the user ID from a JWT token
-	* 
-	* @param token - The JWT token
-	* @returns User ID (ulid) or null if token is invalid
-	*/
-	function getUserIdFromToken(token) {
-		return extractUserInfoFromToken(token)?.id || null;
-	}
-	/**
-	* Check if user is logged in based on JWT token
-	* 
-	* @param token - The JWT token
-	* @returns True if user is logged in, false otherwise
-	*/
-	function isUserLoggedIn(token) {
-		return extractUserInfoFromToken(token)?.isLoggedIn || false;
-	}
-	/**
-	* Check if user is anonymous based on JWT token
-	* 
-	* @param token - The JWT token
-	* @returns True if user is anonymous, false otherwise
-	*/
-	function isUserAnonymous(token) {
-		return extractUserInfoFromToken(token)?.isAnonymous ?? true;
-	}
-
-//#endregion
-//#region src/types/api-key-endpoints.ts
-	const API_KEY_ENDPOINTS = [
-		"/auth/anonymous",
-		"/store/check",
-		"/store/config"
-	];
 
 //#endregion
-//#region src/lib/auth-utils.ts
+//#region src/lib/shared/client.ts
 /**
-	* Check if a URL path is an auth endpoint that should use API key
-	*/
-	function isAnonymousAuthEndpoint(pathname) {
-		return pathname.endsWith("/auth/anonymous");
-	}
-	/**
-	* Check if a URL path requires API key authentication (auto-generated from OpenAPI spec)
-	*/
-	function isApiKeyRequiredEndpoint(pathname) {
-		return API_KEY_ENDPOINTS.some((endpoint) => pathname.endsWith(endpoint));
-	}
-	/**
-	* Check if a URL path is a login/register endpoint that returns tokens
+	* Shared base class for Storefront API clients.
+	*
+	* This centralizes Storefront-specific URL construction, default header
+	* transformations, and shared API key state while leaving auth middleware
+	* decisions to the public and session-specific subclasses.
 	*/
-	function isTokenReturningEndpoint(pathname) {
-		return [
-			"/auth/login/password",
-			"/auth/register/phone",
-			"/auth/register/email",
-			"/auth/verify-otp",
-			"/auth/refresh-token",
-			"/auth/logout"
-		].some((endpoint) => pathname.endsWith(endpoint));
-	}
+	var StorefrontAPIClientBase = class extends BaseAPIClient {
+		apiKey;
+		constructor(config) {
+			const baseUrl = buildStorefrontURL({
+				storeId: config.storeId,
+				environment: config.environment,
+				baseUrl: config.baseUrl
+			});
+			super({
+				baseUrl,
+				timeout: config.timeout,
+				defaultHeaders: config.defaultHeaders,
+				debug: config.debug,
+				logger: config.logger
+			}, baseUrl, {
+				customer_group_id: "x-customer-group-id",
+				debug_mode: "x-debug-mode"
+			});
+			this.apiKey = config.apiKey;
+		}
+		setApiKey(apiKey) {
+			this.apiKey = apiKey;
+		}
+		clearApiKey() {
+			this.apiKey = void 0;
+		}
+		useMiddleware(middleware) {
+			this.client.use(middleware);
+		}
+	};
 
 //#endregion
-//#region src/lib/middleware.ts
-/**
-	* Simple in-memory token storage implementation
+//#region src/lib/session/client.ts
+	function attachSessionAuth(client, sessionManager) {
+		client.useMiddleware(sessionManager.createAuthMiddleware());
+	}
+	/**
+	* Storefront API client that extends the generic BaseAPIClient
+	* Adds Commerce Engine specific authentication and token management
 	*/
-	var MemoryTokenStorage = class {
-		accessToken = null;
-		refreshToken = null;
-		async getAccessToken() {
-			return this.accessToken;
+	var SessionStorefrontAPIClient = class extends StorefrontAPIClientBase {
+		config;
+		/**
+		* Create a new SessionStorefrontAPIClient
+		*
+		* @param config - Configuration for the API client
+		*/
+		constructor(config) {
+			super(config);
+			this.config = { ...config };
+			this.setupStorefrontAuth();
 		}
-		async setAccessToken(token) {
-			this.accessToken = token;
+		/**
+		* Set up Storefront-specific authentication middleware
+		*/
+		setupStorefrontAuth() {
+			attachSessionAuth(this, this.config.sessionManager);
 		}
-		async getRefreshToken() {
-			return this.refreshToken;
+		/**
+		* Get the authorization header value
+		* without creating a new session.
+		*
+		* @returns The Authorization header value or empty string if no token is set
+		*/
+		async getAuthorizationHeader() {
+			return this.config.sessionManager.getAuthorizationHeader();
 		}
-		async setRefreshToken(token) {
-			this.refreshToken = token;
+		/**
+		* Set authentication tokens
+		*
+		* @param accessToken - The access token (required)
+		* @param refreshToken - The refresh token (optional)
+		*
+		* Behavior:
+		* - If tokenStorage is provided: Stores tokens for automatic management
+		* - If tokenStorage is not provided: Only stores access token for manual management
+		*/
+		async setTokens(accessToken, refreshToken) {
+			await this.config.sessionManager.setTokens(accessToken, refreshToken);
 		}
+		/**
+		* Clear all authentication tokens
+		*
+		* Behavior:
+		* - If tokenStorage is provided: Clears both access and refresh tokens from storage
+		* - If tokenStorage is not provided: Clears the manual access token
+		*/
 		async clearTokens() {
-			this.accessToken = null;
-			this.refreshToken = null;
+			await this.config.sessionManager.clearTokens();
 		}
-	};
-	/**
-	* Browser localStorage token storage implementation
-	*/
-	var BrowserTokenStorage = class {
-		accessTokenKey;
-		refreshTokenKey;
-		constructor(prefix = "storefront_") {
-			this.accessTokenKey = `${prefix}access_token`;
-			this.refreshTokenKey = `${prefix}refresh_token`;
+		/**
+		* Set the X-Api-Key header
+		*
+		* @param apiKey - The API key to set
+		*/
+		setApiKey(apiKey) {
+			super.setApiKey(apiKey);
+			this.config.apiKey = apiKey;
+			this.config.sessionManager.setApiKey(apiKey);
 		}
-		async getAccessToken() {
-			if (typeof localStorage === "undefined") return null;
-			return localStorage.getItem(this.accessTokenKey);
+		/**
+		* Clear the X-Api-Key header
+		*/
+		clearApiKey() {
+			super.clearApiKey();
+			this.config.apiKey = void 0;
+			this.config.sessionManager.clearApiKey();
 		}
-		async setAccessToken(token) {
-			if (typeof localStorage !== "undefined") localStorage.setItem(this.accessTokenKey, token);
+		/**
+		* Resolve the current user ID from explicit parameters or the active session.
+		*
+		* @param explicitUserId - Optional user ID supplied by the caller
+		* @returns The resolved user ID
+		* @throws When no user ID is available
+		*/
+		async resolveCurrentUserId(explicitUserId) {
+			if (explicitUserId) return explicitUserId;
+			return this.config.sessionManager.ensureUserId();
 		}
-		async getRefreshToken() {
-			if (typeof localStorage === "undefined") return null;
-			return localStorage.getItem(this.refreshTokenKey);
+		/**
+		* Resolve path parameters that require `user_id`.
+		*
+		* @param pathParams - Path parameters with an optional `user_id`
+		* @returns Path parameters with a guaranteed `user_id`
+		*/
+		async resolveUserPathParams(pathParams) {
+			return {
+				...pathParams,
+				user_id: await this.resolveCurrentUserId(pathParams.user_id)
+			};
 		}
-		async setRefreshToken(token) {
-			if (typeof localStorage !== "undefined") localStorage.setItem(this.refreshTokenKey, token);
+		/**
+		* Resolve query parameters that require `user_id`.
+		*
+		* @param queryParams - Query parameters with an optional `user_id`
+		* @returns Query parameters with a guaranteed `user_id`
+		*/
+		async resolveUserQueryParams(queryParams) {
+			return {
+				...queryParams,
+				user_id: await this.resolveCurrentUserId(queryParams.user_id)
+			};
 		}
-		async clearTokens() {
-			if (typeof localStorage !== "undefined") {
-				localStorage.removeItem(this.accessTokenKey);
-				localStorage.removeItem(this.refreshTokenKey);
-			}
-		}
-	};
-	/**
-	* Cookie-based token storage implementation
-	*/
-	var CookieTokenStorage = class {
-		accessTokenKey;
-		refreshTokenKey;
-		options;
-		constructor(options = {}) {
-			const prefix = options.prefix || "storefront_";
-			this.accessTokenKey = `${prefix}access_token`;
-			this.refreshTokenKey = `${prefix}refresh_token`;
-			this.options = {
-				maxAge: options.maxAge || 10080 * 60,
-				path: options.path || "/",
-				domain: options.domain,
-				secure: options.secure ?? (typeof window !== "undefined" && window.location?.protocol === "https:"),
-				sameSite: options.sameSite || "Lax",
-				httpOnly: false
-			};
-		}
-		async getAccessToken() {
-			return this.getCookie(this.accessTokenKey);
-		}
-		async setAccessToken(token) {
-			this.setCookie(this.accessTokenKey, token);
-		}
-		async getRefreshToken() {
-			return this.getCookie(this.refreshTokenKey);
-		}
-		async setRefreshToken(token) {
-			this.setCookie(this.refreshTokenKey, token);
-		}
-		async clearTokens() {
-			this.deleteCookie(this.accessTokenKey);
-			this.deleteCookie(this.refreshTokenKey);
-		}
-		getCookie(name) {
-			if (typeof document === "undefined") return null;
-			const parts = `; ${document.cookie}`.split(`; ${name}=`);
-			if (parts.length === 2) {
-				const cookieValue = parts.pop()?.split(";").shift();
-				return cookieValue ? decodeURIComponent(cookieValue) : null;
-			}
-			return null;
-		}
-		setCookie(name, value) {
-			if (typeof document === "undefined") return;
-			let cookieString = `${name}=${encodeURIComponent(value)}`;
-			if (this.options.maxAge) cookieString += `; Max-Age=${this.options.maxAge}`;
-			if (this.options.path) cookieString += `; Path=${this.options.path}`;
-			if (this.options.domain) cookieString += `; Domain=${this.options.domain}`;
-			if (this.options.secure) cookieString += `; Secure`;
-			if (this.options.sameSite) cookieString += `; SameSite=${this.options.sameSite}`;
-			document.cookie = cookieString;
-		}
-		deleteCookie(name) {
-			if (typeof document === "undefined") return;
-			let cookieString = `${name}=; Max-Age=0`;
-			if (this.options.path) cookieString += `; Path=${this.options.path}`;
-			if (this.options.domain) cookieString += `; Domain=${this.options.domain}`;
-			document.cookie = cookieString;
-		}
-	};
-	/**
-	* Create authentication middleware for openapi-fetch
-	*/
-	function createAuthMiddleware(config) {
-		let isRefreshing = false;
-		let refreshPromise = null;
-		let hasAssessedTokens = false;
-		const assessTokenStateOnce = async () => {
-			if (hasAssessedTokens) return;
-			hasAssessedTokens = true;
-			try {
-				const accessToken = await config.tokenStorage.getAccessToken();
-				const refreshToken = await config.tokenStorage.getRefreshToken();
-				if (!accessToken && refreshToken) {
-					await config.tokenStorage.clearTokens();
-					console.info("Cleaned up orphaned refresh token");
-				}
-			} catch (error) {
-				console.warn("Token state assessment failed:", error);
-			}
-		};
-		const refreshTokens = async () => {
-			if (isRefreshing && refreshPromise) return refreshPromise;
-			isRefreshing = true;
-			refreshPromise = (async () => {
-				try {
-					const refreshToken = await config.tokenStorage.getRefreshToken();
-					let newTokens;
-					if (refreshToken && !isTokenExpired(refreshToken)) if (config.refreshTokenFn) newTokens = await config.refreshTokenFn(refreshToken);
-					else {
-						const response = await fetch(`${config.baseUrl}/auth/refresh-token`, {
-							method: "POST",
-							headers: { "Content-Type": "application/json" },
-							body: JSON.stringify({ refresh_token: refreshToken })
-						});
-						if (!response.ok) throw new Error(`Token refresh failed: ${response.status}`);
-						newTokens = (await response.json()).content;
-					}
-					else {
-						const currentAccessToken = await config.tokenStorage.getAccessToken();
-						if (!currentAccessToken) throw new Error("No tokens available for refresh");
-						const reason = refreshToken ? "refresh token expired" : "no refresh token available";
-						const response = await fetch(`${config.baseUrl}/auth/anonymous`, {
-							method: "POST",
-							headers: {
-								"Content-Type": "application/json",
-								...config.apiKey && { "X-Api-Key": config.apiKey },
-								Authorization: `Bearer ${currentAccessToken}`
-							}
-						});
-						if (!response.ok) throw new Error(`Anonymous token fallback failed: ${response.status}`);
-						newTokens = (await response.json()).content;
-						console.info(`Token refreshed via anonymous fallback (${reason}) - user may need to re-authenticate for privileged operations`);
-					}
-					await config.tokenStorage.setAccessToken(newTokens.access_token);
-					await config.tokenStorage.setRefreshToken(newTokens.refresh_token);
-					config.onTokensUpdated?.(newTokens.access_token, newTokens.refresh_token);
-				} catch (error) {
-					console.error("Token refresh failed:", error);
-					await config.tokenStorage.clearTokens();
-					config.onTokensCleared?.();
-					throw error;
-				} finally {
-					isRefreshing = false;
-					refreshPromise = null;
-				}
-			})();
-			return refreshPromise;
-		};
-		return {
-			async onRequest({ request }) {
-				const pathname = getPathnameFromUrl(request.url);
-				await assessTokenStateOnce();
-				if (isAnonymousAuthEndpoint(pathname)) {
-					if (config.apiKey) request.headers.set("X-Api-Key", config.apiKey);
-					const existingToken = await config.tokenStorage.getAccessToken();
-					if (existingToken && !isTokenExpired(existingToken) && isUserLoggedIn(existingToken)) return new Response(JSON.stringify({
-						message: "Cannot create anonymous session while authenticated",
-						success: false,
-						code: "USER_ALREADY_AUTHENTICATED"
-					}), {
-						status: 400,
-						headers: { "Content-Type": "application/json" }
-					});
-					if (existingToken) request.headers.set("Authorization", `Bearer ${existingToken}`);
-					return request;
-				}
-				if (isApiKeyRequiredEndpoint(pathname)) {
-					if (config.apiKey) request.headers.set("X-Api-Key", config.apiKey);
-					return request;
-				}
-				let accessToken = await config.tokenStorage.getAccessToken();
-				if (!accessToken) try {
-					const response = await fetch(`${config.baseUrl}/auth/anonymous`, {
-						method: "POST",
-						headers: {
-							"Content-Type": "application/json",
-							...config.apiKey && { "X-Api-Key": config.apiKey }
-						}
-					});
-					if (response.ok) {
-						const tokens = (await response.json()).content;
-						if (tokens?.access_token && tokens?.refresh_token) {
-							await config.tokenStorage.setAccessToken(tokens.access_token);
-							await config.tokenStorage.setRefreshToken(tokens.refresh_token);
-							accessToken = tokens.access_token;
-							config.onTokensUpdated?.(tokens.access_token, tokens.refresh_token);
-							console.info("Automatically created anonymous session for first API request");
-						}
-					}
-				} catch (error) {
-					console.warn("Failed to automatically create anonymous tokens:", error);
-				}
-				if (accessToken && isTokenExpired(accessToken)) try {
-					await refreshTokens();
-					accessToken = await config.tokenStorage.getAccessToken();
-				} catch (error) {}
-				if (accessToken) request.headers.set("Authorization", `Bearer ${accessToken}`);
-				return request;
-			},
-			async onResponse({ request, response }) {
-				const pathname = getPathnameFromUrl(request.url);
-				if (response.ok) {
-					if (isTokenReturningEndpoint(pathname) || isAnonymousAuthEndpoint(pathname)) try {
-						const content = (await response.clone().json()).content;
-						if (content?.access_token && content?.refresh_token) {
-							await config.tokenStorage.setAccessToken(content.access_token);
-							await config.tokenStorage.setRefreshToken(content.refresh_token);
-							config.onTokensUpdated?.(content.access_token, content.refresh_token);
-						}
-					} catch (error) {
-						console.warn("Failed to extract tokens from response:", error);
-					}
-				}
-				if (response.status === 401 && !isAnonymousAuthEndpoint(pathname)) {
-					const currentToken = await config.tokenStorage.getAccessToken();
-					if (currentToken && isTokenExpired(currentToken, 0)) try {
-						await refreshTokens();
-						const newToken = await config.tokenStorage.getAccessToken();
-						if (newToken) {
-							const retryRequest = request.clone();
-							retryRequest.headers.set("Authorization", `Bearer ${newToken}`);
-							return fetch(retryRequest);
-						}
-					} catch (error) {
-						console.warn("Token refresh failed on 401 response:", error);
-					}
-				}
-				return response;
-			}
-		};
-	}
-	/**
-	* Helper function to create auth middleware with sensible defaults
-	*/
-	function createDefaultAuthMiddleware(options) {
-		return createAuthMiddleware({
-			tokenStorage: options.tokenStorage || (typeof localStorage !== "undefined" ? new BrowserTokenStorage() : new MemoryTokenStorage()),
-			apiKey: options.apiKey,
-			baseUrl: options.baseUrl,
-			onTokensUpdated: options.onTokensUpdated,
-			onTokensCleared: options.onTokensCleared
-		});
-	}
-
-//#endregion
-//#region src/lib/url-utils.ts
-/**
-	* URL utility functions for the Storefront SDK
-	*/
-	/**
-	* Available API environments for Commerce Engine
-	*/
-	let Environment = /* @__PURE__ */ function(Environment) {
-		/**
-		* Staging environment
-		*/
-		Environment["Staging"] = "staging";
 		/**
-		* Production environment
+		* Resolve path parameters that require `customer_id`.
+		*
+		* @param pathParams - Path parameters with an optional `customer_id`
+		* @returns Path parameters with a guaranteed `customer_id`
+		* @throws When the user is anonymous or no session can be established
 		*/
-		Environment["Production"] = "production";
-		return Environment;
-	}({});
-	/**
-	* Build base URL for Storefront API
-	*/
-	function buildStorefrontURL(config) {
-		if (config.baseUrl) return config.baseUrl;
-		switch (config.environment || Environment.Production) {
-			case Environment.Staging: return `https://staging.api.commercengine.io/api/v1/${config.storeId}/storefront`;
-			case Environment.Production:
-			default: return `https://prod.api.commercengine.io/api/v1/${config.storeId}/storefront`;
+		async resolveCustomerPathParams(pathParams) {
+			return {
+				...pathParams,
+				customer_id: pathParams.customer_id ?? await this.config.sessionManager.ensureCustomerId()
+			};
 		}
-	}
+	};
 
 //#endregion
-//#region src/lib/client.ts
+//#region src/lib/shared/catalog.ts
 /**
-	* Storefront API client that extends the generic BaseAPIClient
-	* Adds Commerce Engine specific authentication and token management
+	* Client for interacting with catalog endpoints
 	*/
-	var StorefrontAPIClient = class extends BaseAPIClient {
-		config;
-		initializationPromise = null;
-		/**
-		* Create a new StorefrontAPIClient
-		*
-		* @param config - Configuration for the API client
-		*/
-		constructor(config) {
-			const baseUrl = buildStorefrontURL({
-				storeId: config.storeId,
-				environment: config.environment,
-				baseUrl: config.baseUrl
-			});
-			super({
-				baseUrl,
-				timeout: config.timeout,
-				defaultHeaders: config.defaultHeaders,
-				debug: config.debug,
-				logger: config.logger
-			}, baseUrl, {
-				customer_group_id: "x-customer-group-id",
-				debug_mode: "x-debug-mode"
-			});
-			this.config = { ...config };
-			this.setupStorefrontAuth();
-		}
-		/**
-		* Set up Storefront-specific authentication middleware
-		*/
-		setupStorefrontAuth() {
-			const config = this.config;
-			if (config.tokenStorage) {
-				const authMiddleware = createDefaultAuthMiddleware({
-					apiKey: config.apiKey,
-					baseUrl: this.getBaseUrl(),
-					tokenStorage: config.tokenStorage,
-					onTokensUpdated: config.onTokensUpdated,
-					onTokensCleared: config.onTokensCleared
-				});
-				this.client.use(authMiddleware);
-				if (config.accessToken) {
-					this.initializationPromise = this.initializeTokens(config.accessToken, config.refreshToken);
-					config.accessToken = void 0;
-					config.refreshToken = void 0;
-				}
-			} else this.client.use({ onRequest: async ({ request }) => {
-				if (isAnonymousAuthEndpoint(getPathnameFromUrl(request.url))) {
-					if (config.apiKey) request.headers.set("X-Api-Key", config.apiKey);
-					if (config.accessToken) request.headers.set("Authorization", `Bearer ${config.accessToken}`);
-					return request;
-				}
-				if (config.accessToken) request.headers.set("Authorization", `Bearer ${config.accessToken}`);
-				return request;
-			} });
-		}
+	var BaseCatalogClient = class extends StorefrontAPIClientBase {
 		/**
-		* Get the authorization header value
-		* If using token storage, gets the current token from storage
-		* Otherwise returns the manual token
+		* List all products
 		*
-		* @returns The Authorization header value or empty string if no token is set
-		*/
-		async getAuthorizationHeader() {
-			if (this.config.tokenStorage && this.initializationPromise) await this.initializationPromise;
-			if (this.config.tokenStorage) {
-				const token = await this.config.tokenStorage.getAccessToken();
-				return token ? `Bearer ${token}` : "";
-			}
-			return this.config.accessToken ? `Bearer ${this.config.accessToken}` : "";
-		}
-		/**
-		* Set authentication tokens
+		* @param options - Optional query parameters
+		* @param headers - Optional header parameters (customer_group_id, etc.)
+		* @returns Promise with products and pagination info
 		*
-		* @param accessToken - The access token (required)
-		* @param refreshToken - The refresh token (optional)
+		* @example
+		* ```typescript
+		* // Basic product listing
+		* const { data, error } = await sdk.catalog.listProducts();
 		*
-		* Behavior:
-		* - If tokenStorage is provided: Stores tokens for automatic management
-		* - If tokenStorage is not provided: Only stores access token for manual management
-		*/
-		async setTokens(accessToken, refreshToken) {
-			if (this.config.tokenStorage) {
-				await this.config.tokenStorage.setAccessToken(accessToken);
-				if (refreshToken) await this.config.tokenStorage.setRefreshToken(refreshToken);
-			} else {
-				this.config.accessToken = accessToken;
-				if (refreshToken) console.warn("Refresh token provided but ignored in manual token management mode. Use tokenStorage for automatic management.");
-			}
-		}
-		/**
-		* Clear all authentication tokens
+		* if (error) {
+		*   console.error("Failed to list products:", error);
+		*   return;
+		* }
 		*
-		* Behavior:
-		* - If tokenStorage is provided: Clears both access and refresh tokens from storage
-		* - If tokenStorage is not provided: Clears the manual access token
-		*/
-		async clearTokens() {
-			if (this.config.tokenStorage) await this.config.tokenStorage.clearTokens();
-			else this.config.accessToken = void 0;
-		}
-		/**
-		* Set the X-Api-Key header
-		*
-		* @param apiKey - The API key to set
-		*/
-		setApiKey(apiKey) {
-			this.config.apiKey = apiKey;
-		}
-		/**
-		* Clear the X-Api-Key header
-		*/
-		clearApiKey() {
-			this.config.apiKey = void 0;
-		}
-		/**
-		* Initialize tokens in storage (private helper method)
-		*/
-		async initializeTokens(accessToken, refreshToken) {
-			try {
-				if (this.config.tokenStorage) {
-					await this.config.tokenStorage.setAccessToken(accessToken);
-					if (refreshToken) await this.config.tokenStorage.setRefreshToken(refreshToken);
-				}
-			} catch (error) {
-				console.warn("Failed to initialize tokens in storage:", error);
-			}
-		}
-	};
-
-//#endregion
-//#region src/lib/catalog.ts
-/**
-	* Client for interacting with catalog endpoints
-	*/
-	var CatalogClient = class extends StorefrontAPIClient {
-		/**
-		* List all products
-		*
-		* @param options - Optional query parameters
-		* @param headers - Optional header parameters (customer_group_id, etc.)
-		* @returns Promise with products and pagination info
-		*
-		* @example
-		* ```typescript
-		* // Basic product listing
-		* const { data, error } = await sdk.catalog.listProducts();
-		*
-		* if (error) {
-		*   console.error("Failed to list products:", error);
-		*   return;
-		* }
-		*
-		* console.log("Products found:", data.products?.length || 0);
-		* console.log("Pagination:", data.pagination);
+		* console.log("Products found:", data.products?.length || 0);
+		* console.log("Pagination:", data.pagination);
 		*
 		* // With filtering and pagination
 		* const { data: filteredData, error: filteredError } = await sdk.catalog.listProducts({
@@ -1501,7 +1127,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		/**
 		* Get details for a specific product
 		*
-		* @param pathParams - The path parameters (product ID or slug)
+		* @param pathParams - The path parameters. Accepts product ID or product slug.
 		* @param headers - Optional header parameters (customer_group_id, etc.)
 		* @returns Promise with product details
 		*
@@ -1509,7 +1135,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* ```typescript
 		* // Get product by ID
 		* const { data, error } = await sdk.catalog.getProductDetail(
-		*   { product_id_or_slug: "prod_123" }
+		*   { product_id: "prod_123" }
 		* );
 		*
 		* if (error) {
@@ -1521,14 +1147,15 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* console.log("Price:", data.product.pricing?.selling_price);
 		* console.log("Description:", data.product.short_description);
 		*
-		* // Get product by slug
+		* // Get product by slug (also accepted in place of product_id)
 		* const { data: slugData, error: slugError } = await sdk.catalog.getProductDetail({
-		*   product_id_or_slug: "detox-candy"
+		*   product_id: "detox-candy"
 		* });
 		*
 		* // Override customer group ID for this specific request
 		* const { data: overrideData, error: overrideError } = await sdk.catalog.getProductDetail(
-		*   { product_id_or_slug: "detox-candy" },
+		*   { product_id: "detox-candy" },
+		*   undefined,
 		*   {
 		*     "x-customer-group-id": "premium_customers" // Override default SDK config
 		*   }
@@ -1544,7 +1171,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		*/
 		async getProductDetail(pathParams, options, headers) {
 			const mergedHeaders = this.mergeHeaders(headers);
-			return this.executeRequest(() => this.client.GET("/catalog/products/{product_id_or_slug}", { params: {
+			return this.executeRequest(() => this.client.GET("/catalog/products/{product_id}", { params: {
 				path: pathParams,
 				query: options,
 				header: mergedHeaders
@@ -1553,12 +1180,13 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		/**
 		* List all variants for a specific product
 		*
-		* @param pathParams - The path parameters (product ID)
+		* @param pathParams - The path parameters. Accepts product ID or product slug.
 		* @param headers - Optional header parameters (customer_group_id, etc.)
 		* @returns Promise with product variants and pagination info
 		*
 		* @example
 		* ```typescript
+		* // By product ID
 		* const { data, error } = await sdk.catalog.listProductVariants(
 		*   { product_id: "prod_123" }
 		* );
@@ -1574,9 +1202,15 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		*   console.log(`Variant: ${variant.name} - SKU: ${variant.sku} - Price: ${variant.pricing?.selling_price}`);
 		* });
 		*
+		* // By product slug (also accepted in place of product_id)
+		* const { data: slugData, error: slugError } = await sdk.catalog.listProductVariants(
+		*   { product_id: "detox-candy" }
+		* );
+		*
 		* // Override customer group ID for this specific request
 		* const { data: overrideData, error: overrideError } = await sdk.catalog.listProductVariants(
 		*   { product_id: "prod_123" },
+		*   undefined,
 		*   {
 		*     "x-customer-group-id": "wholesale_customers" // Override default SDK config
 		*   }
@@ -1594,12 +1228,13 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		/**
 		* Get details for a specific product variant
 		*
-		* @param pathParams - The path parameters (product ID and variant ID)
+		* @param pathParams - The path parameters. Accepts product ID or slug for product_id, and variant ID or slug for variant_id.
 		* @param headers - Optional header parameters (customer_group_id, etc.)
 		* @returns Promise with variant details
 		*
 		* @example
 		* ```typescript
+		* // By product ID and variant ID
 		* const { data, error } = await sdk.catalog.getVariantDetail(
 		*   {
 		*     product_id: "prod_123",
@@ -1616,6 +1251,14 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* console.log("SKU:", data.variant.sku);
 		* console.log("Price:", data.variant.pricing?.selling_price);
 		* console.log("Stock available:", data.variant.stock_available);
+		*
+		* // By product slug and variant slug (also accepted in place of IDs)
+		* const { data: slugData, error: slugError } = await sdk.catalog.getVariantDetail(
+		*   {
+		*     product_id: "detox-candy",
+		*     variant_id: "detox-candy-100g"
+		*   }
+		* );
 		* ```
 		*/
 		async getVariantDetail(pathParams, options, headers) {
@@ -1700,49 +1343,6 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 			} }));
 		}
 		/**
-		* Create a product review
-		*
-		* @param pathParams - The path parameters (product ID)
-		* @param formData - The review data including rating, comment, and optional images
-		* @returns Promise with review creation response
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.catalog.createProductReview(
-		*   { product_id: "prod_123" },
-		*   {
-		*     user_id: "user_123",
-		*     order_number: "ORD-001",
-		*     rating: 5,
-		*     review_text: "Excellent product! Highly recommended.",
-		*     images: [
-		*       new File(["image data"], "review1.jpg", { type: "image/jpeg" }),
-		*       new File(["image data"], "review2.jpg", { type: "image/jpeg" })
-		*     ]
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to create review:", error);
-		*   return;
-		* }
-		*
-		* console.log("Review created successfully:", data.message);
-		* ```
-		*/
-		async createProductReview(pathParams, formData) {
-			return this.executeRequest(() => this.client.POST("/catalog/products/{product_id}/reviews", {
-				params: { path: pathParams },
-				body: formData,
-				bodySerializer: (body) => {
-					const fd = new FormData();
-					for (const [key, value] of Object.entries(body)) if (value !== void 0 && value !== null) if (value instanceof File || value instanceof Blob) fd.append(key, value);
-					else fd.append(key, String(value));
-					return fd;
-				}
-			}));
-		}
-		/**
 		* Search for products
 		*
 		* @param searchData - The search query, filters, sort, and pagination options
@@ -1982,12 +1582,74 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		}
 	};
 
+//#endregion
+//#region src/lib/public/catalog.ts
+/**
+	* Client for interacting with catalog endpoints
+	*/
+	var PublicCatalogClient = class extends BaseCatalogClient {};
+
+//#endregion
+//#region src/lib/catalog.ts
+/**
+	* Client for interacting with catalog endpoints
+	*/
+	var CatalogClient = class extends BaseCatalogClient {
+		constructor(config) {
+			super(config);
+			attachSessionAuth(this, config.sessionManager);
+		}
+		/**
+		* Create a product review
+		*
+		* @param pathParams - The path parameters (product ID)
+		* @param formData - The review data including rating, comment, and optional images
+		* @returns Promise with review creation response
+		*
+		* @example
+		* ```typescript
+		* const { data, error } = await sdk.catalog.createProductReview(
+		*   { product_id: "prod_123" },
+		*   {
+		*     user_id: "user_123",
+		*     order_number: "ORD-001",
+		*     rating: 5,
+		*     review_text: "Excellent product! Highly recommended.",
+		*     images: [
+		*       new File(["image data"], "review1.jpg", { type: "image/jpeg" }),
+		*       new File(["image data"], "review2.jpg", { type: "image/jpeg" })
+		*     ]
+		*   }
+		* );
+		*
+		* if (error) {
+		*   console.error("Failed to create review:", error);
+		*   return;
+		* }
+		*
+		* console.log("Review created successfully:", data.message);
+		* ```
+		*/
+		async createProductReview(pathParams, formData) {
+			return this.executeRequest(() => this.client.POST("/catalog/products/{product_id}/reviews", {
+				params: { path: pathParams },
+				body: formData,
+				bodySerializer: (body) => {
+					const fd = new FormData();
+					for (const [key, value] of Object.entries(body)) if (value !== void 0 && value !== null) if (value instanceof File || value instanceof Blob) fd.append(key, value);
+					else fd.append(key, String(value));
+					return fd;
+				}
+			}));
+		}
+	};
+
 //#endregion
 //#region src/lib/cart.ts
 /**
 	* Client for interacting with cart endpoints
 	*/
-	var CartClient = class extends StorefrontAPIClient {
+	var CartClient = class extends SessionStorefrontAPIClient {
 		/**
 		* Create a new cart
 		*
@@ -2109,49 +1771,14 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 				body
 			}));
 		}
-		/**
-		* Get cart details by user ID
-		*
-		* @param userId - The ID of the user
-		* @returns Promise with cart details
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.cart.getUserCart({
-		*   user_id: "01H9USER12345ABCDE"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get user cart:", error.message);
-		* } else {
-		*   console.log("User cart ID:", data.cart.id);
-		*   console.log("Cart value:", data.cart.subtotal);
-		* }
-		* ```
-		*/
-		async getUserCart(userId) {
-			return this.executeRequest(() => this.client.GET("/carts/users/{user_id}", { params: { path: userId } }));
+		async getUserCart(pathParams = {}) {
+			const resolvedPathParams = await this.resolveUserPathParams(pathParams);
+			return this.executeRequest(() => this.client.GET("/carts/users/{user_id}", { params: { path: resolvedPathParams } }));
 		}
-		/**
-		* Delete a cart by user ID
-		*
-		* @param userId - The ID of the user
-		* @returns Promise that resolves when the cart is deleted
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.cart.deleteUserCart({
-		*   user_id: "01H9USER12345ABCDE"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to delete user cart:", error.message);
-		* } else {
-		*   console.log("User cart cleared:", data.message);
-		* }
-		* ```
-		*/
-		async deleteUserCart(userId) {
+		async deleteUserCart(pathParams = {}) {
+			const resolvedPathParams = await this.resolveUserPathParams(pathParams);
 			return this.executeRequest(() => this.client.DELETE("/carts/users/{user_id}", {
-				params: { path: userId },
+				params: { path: resolvedPathParams },
 				body: void 0
 			}));
 		}
@@ -2644,92 +2271,31 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 				body: void 0
 			}));
 		}
-		/**
-		* Get wishlist items
-		*
-		* @param userId - The ID of the user
-		* @param options - Optional query parameters for filtering by seller_id (only for multi-seller marketplace stores)
-		* @returns Promise with wishlist items
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.cart.getWishlist({
-		*   user_id: "01H9USER12345ABCDE"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get wishlist:", error.message);
-		* } else {
-		*   const products = data.products;
-		*   console.log("Wishlist items:", products.length);
-		*   products.forEach(product => {
-		*     console.log("Product:", product.product_name, "Price:", product.pricing?.selling_price);
-		*   });
-		* }
-		* ```
-		*/
-		async getWishlist(userId, options) {
+		async getWishlist(pathParamsOrQuery, options) {
+			const hasPathParams = options !== void 0 || !!pathParamsOrQuery && typeof pathParamsOrQuery === "object" && "user_id" in pathParamsOrQuery;
+			const pathParams = hasPathParams ? pathParamsOrQuery : {};
+			const queryParams = hasPathParams ? options : pathParamsOrQuery;
+			const resolvedPathParams = await this.resolveUserPathParams(pathParams);
 			return this.executeRequest(() => this.client.GET("/wishlist/{user_id}", { params: {
-				path: userId,
-				query: options
+				path: resolvedPathParams,
+				query: queryParams
 			} }));
 		}
-		/**
-		* Add item to wishlist
-		*
-		* @param userId - The ID of the user
-		* @param itemId - The ID of the item
-		* @returns Promise with updated wishlist
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.cart.addToWishlist(
-		*   { user_id: "01H9USER12345ABCDE" },
-		*   {
-		*     product_id: "01F3Z7KG06J4ACWH1C4926KJEC",
-		*     variant_id: null
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to add to wishlist:", error.message);
-		* } else {
-		*   const products = data.products;
-		*   console.log("Item added to wishlist, total items:", products.length);
-		* }
-		* ```
-		*/
-		async addToWishlist(userId, itemId) {
+		async addToWishlist(pathParamsOrBody, maybeBody) {
+			const pathParams = maybeBody ? pathParamsOrBody : {};
+			const body = maybeBody ?? pathParamsOrBody;
+			const resolvedPathParams = await this.resolveUserPathParams(pathParams);
 			return this.executeRequest(() => this.client.POST("/wishlist/{user_id}", {
-				params: { path: userId },
-				body: itemId
+				params: { path: resolvedPathParams },
+				body
 			}));
 		}
-		/**
-		* Remove item from wishlist
-		*
-		* @param userId - The ID of the user
-		* @param body - The body containing product details to remove
-		* @returns Promise with updated wishlist
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.cart.removeFromWishlist(
-		*   { user_id: "01H9USER12345ABCDE" },
-		*   {
-		*     product_id: "01F3Z7KG06J4ACWH1C4926KJEC",
-		*     variant_id: null
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to remove from wishlist:", error.message);
-		* } else {
-		*   const products = data.products;
-		*   console.log("Item removed from wishlist, remaining items:", products.length);
-		* }
-		* ```
-		*/
-		async removeFromWishlist(userId, body) {
+		async removeFromWishlist(pathParamsOrBody, maybeBody) {
+			const pathParams = maybeBody ? pathParamsOrBody : {};
+			const body = maybeBody ?? pathParamsOrBody;
+			const resolvedPathParams = await this.resolveUserPathParams(pathParams);
 			return this.executeRequest(() => this.client.DELETE("/wishlist/{user_id}", {
-				params: { path: userId },
+				params: { path: resolvedPathParams },
 				body
 			}));
 		}
@@ -2740,7 +2306,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 /**
 	* Client for interacting with authentication endpoints
 	*/
-	var AuthClient = class extends StorefrontAPIClient {
+	var AuthClient = class extends SessionStorefrontAPIClient {
 		/**
 		* Get anonymous token for guest users
 		*
@@ -2873,13 +2439,14 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 			return this.executeRequest(() => this.client.POST("/auth/login/password", { body }));
 		}
 		/**
-		* Forgot password
+		* Start forgot-password OTP flow
 		*
-		* @param body - Request body containing email address
-		* @returns Promise with password reset information
+		* @param body - Request body containing email or phone details
+		* @param headers - Optional header parameters (for example `x-debug-mode`)
+		* @returns Promise with OTP token and action for the reset flow
 		* @example
 		* ```typescript
-		* // Send password reset email
+		* // Send password reset OTP
 		* const { data, error } = await sdk.auth.forgotPassword({
 		*   email: "customer@example.com"
 		* });
@@ -2887,13 +2454,17 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* if (error) {
 		*   console.error("Password reset failed:", error.message);
 		* } else {
-		*   console.log("Reset email sent successfully");
-		*   // Show confirmation message to user
+		*   console.log("OTP token:", data.otp_token);
+		*   console.log("Action:", data.otp_action);
 		* }
 		* ```
 		*/
-		async forgotPassword(body) {
-			return this.executeRequest(() => this.client.POST("/auth/forgot-password", { body }));
+		async forgotPassword(body, headers) {
+			const mergedHeaders = this.mergeHeaders(headers);
+			return this.executeRequest(() => this.client.POST("/auth/forgot-password", {
+				body,
+				params: { header: mergedHeaders }
+			}));
 		}
 		/**
 		* Reset password
@@ -2975,7 +2546,8 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* Register with phone
 		*
 		* @param body - Registration details including phone number and user information
-		* @returns Promise with user info and tokens
+		* @param headers - Optional header parameters (for example `x-debug-mode`)
+		* @returns Promise with OTP token and action for completing registration
 		* @example
 		* ```typescript
 		* // Register a new user with phone number
@@ -2990,20 +2562,24 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* if (error) {
 		*   console.error("Phone registration failed:", error.message);
 		* } else {
-		*   console.log("Registration successful:", data.user.first_name);
-		*   console.log("User ID:", data.user.id);
-		*   console.log("Access token:", data.access_token);
+		*   console.log("OTP token:", data.otp_token);
+		*   console.log("Action:", data.otp_action);
 		* }
 		* ```
 		*/
-		async registerWithPhone(body) {
-			return this.executeRequest(() => this.client.POST("/auth/register/phone", { body }));
+		async registerWithPhone(body, headers) {
+			const mergedHeaders = this.mergeHeaders(headers);
+			return this.executeRequest(() => this.client.POST("/auth/register/phone", {
+				body,
+				params: { header: mergedHeaders }
+			}));
 		}
 		/**
 		* Register with email
 		*
 		* @param body - Registration details including email and user information
-		* @returns Promise with user info and tokens
+		* @param headers - Optional header parameters (for example `x-debug-mode`)
+		* @returns Promise with OTP token and action for completing registration
 		* @example
 		* ```typescript
 		* // Register a new user with email address
@@ -3017,29 +2593,93 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* if (error) {
 		*   console.error("Email registration failed:", error.message);
 		* } else {
-		*   console.log("Registration successful:", data.user.email);
-		*   console.log("User ID:", data.user.id);
-		*   console.log("Access token:", data.access_token);
+		*   console.log("OTP token:", data.otp_token);
+		*   console.log("Action:", data.otp_action);
 		* }
 		* ```
 		*/
-		async registerWithEmail(body) {
-			return this.executeRequest(() => this.client.POST("/auth/register/email", { body }));
+		async registerWithEmail(body, headers) {
+			const mergedHeaders = this.mergeHeaders(headers);
+			return this.executeRequest(() => this.client.POST("/auth/register/email", {
+				body,
+				params: { header: mergedHeaders }
+			}));
 		}
 		/**
-		* Refresh the access token using a refresh token
-		* @param body - Request body containing the refresh token
-		* @returns Promise with the new access token and refresh token
+		* Register with WhatsApp
+		*
+		* @param body - Registration details including WhatsApp number and user information
+		* @param headers - Optional header parameters (for example `x-debug-mode`)
+		* @returns Promise with OTP token and action for completing registration
 		* @example
 		* ```typescript
-		* // Refresh access token when it expires
-		* const { data, error } = await sdk.auth.refreshToken({
-		*   refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+		* // Register a new user with WhatsApp number
+		* const { data, error } = await sdk.auth.registerWithWhatsapp({
+		*   phone: "9876543210",
+		*   country_code: "+91",
+		*   first_name: "John",
+		*   last_name: "Doe",
+		*   email: "john.doe@example.com"
 		* });
 		*
 		* if (error) {
-		*   console.error("Token refresh failed:", error.message);
-		*   // Redirect to login
+		*   console.error("WhatsApp registration failed:", error.message);
+		* } else {
+		*   console.log("OTP token:", data.otp_token);
+		*   console.log("Action:", data.otp_action);
+		* }
+		* ```
+		*/
+		async registerWithWhatsapp(body, headers) {
+			const mergedHeaders = this.mergeHeaders(headers);
+			return this.executeRequest(() => this.client.POST("/auth/register/whatsapp", {
+				body,
+				params: { header: mergedHeaders }
+			}));
+		}
+		/**
+		* Register with password
+		*
+		* @param body - Registration details including email or phone and password
+		* @param headers - Optional header parameters (for example `x-debug-mode`)
+		* @returns Promise with OTP token and action for completing registration
+		* @example
+		* ```typescript
+		* const { data, error } = await sdk.auth.registerWithPassword({
+		*   email: "jane.smith@example.com",
+		*   password: "securePassword123",
+		*   confirm_password: "securePassword123",
+		* });
+		*
+		* if (error) {
+		*   console.error("Password registration failed:", error.message);
+		* } else {
+		*   console.log("OTP token:", data.otp_token);
+		*   console.log("Action:", data.otp_action);
+		* }
+		* ```
+		*/
+		async registerWithPassword(body, headers) {
+			const mergedHeaders = this.mergeHeaders(headers);
+			return this.executeRequest(() => this.client.POST("/auth/register/password", {
+				body,
+				params: { header: mergedHeaders }
+			}));
+		}
+		/**
+		* Refresh the access token using a refresh token
+		* @param body - Request body containing the refresh token
+		* @returns Promise with the new access token and refresh token
+		* @example
+		* ```typescript
+		* // Refresh access token when it expires
+		* const { data, error } = await sdk.auth.refreshToken({
+		*   refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+		* });
+		*
+		* if (error) {
+		*   console.error("Token refresh failed:", error.message);
+		*   // Redirect to login
 		* } else {
 		*   console.log("Token refreshed successfully");
 		*   console.log("New access token:", data.access_token);
@@ -3293,90 +2933,6 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 			return this.executeRequest(() => this.client.PUT("/auth/user/{id}/deactivate", { params: { path: pathParams } }));
 		}
 		/**
-		* Get user notification preferences
-		*
-		* @param pathParams - Path parameters containing user ID
-		* @returns Promise with user's notification preferences
-		* @example
-		* ```typescript
-		* // Get user's notification preferences
-		* const { data, error } = await sdk.auth.getUserNotificationPreferences({
-		*   id: "01H9XYZ12345USERID"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get preferences:", error.message);
-		* } else {
-		*   console.log("Notification preferences:", data.notification_preferences);
-		* }
-		* ```
-		*/
-		async getUserNotificationPreferences(pathParams) {
-			return this.executeRequest(() => this.client.GET("/auth/user/{id}/notification-preferences", { params: { path: pathParams } }));
-		}
-		/**
-		* Update user notification preferences
-		*
-		* @param pathParams - Path parameters containing user ID
-		* @param body - Updated notification preferences
-		* @returns Promise with updated notification preferences
-		* @example
-		* ```typescript
-		* // Update user's notification preferences
-		* const { data, error } = await sdk.auth.updateUserNotificationPreferences(
-		*   { id: "01H9XYZ12345USERID" },
-		*   {
-		*     email_notifications: true,
-		*     sms_notifications: false,
-		*     push_notifications: true
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to update preferences:", error.message);
-		* } else {
-		*   console.log("Preferences updated successfully");
-		* }
-		* ```
-		*/
-		async updateUserNotificationPreferences(pathParams, body) {
-			return this.executeRequest(() => this.client.PUT("/auth/user/{id}/notification-preferences", {
-				params: { path: pathParams },
-				body
-			}));
-		}
-		/**
-		* Create user notification preference
-		*
-		* @param pathParams - Path parameters containing user ID
-		* @param body - Notification preferences to create
-		* @returns Promise with created notification preferences
-		* @example
-		* ```typescript
-		* // Create notification preferences for a user
-		* const { data, error } = await sdk.auth.createUserNotificationPreference(
-		*   { id: "01H9XYZ12345USERID" },
-		*   {
-		*     email_notifications: true,
-		*     sms_notifications: true,
-		*     push_notifications: false
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to create preferences:", error.message);
-		* } else {
-		*   console.log("Preferences created successfully");
-		* }
-		* ```
-		*/
-		async createUserNotificationPreference(pathParams, body) {
-			return this.executeRequest(() => this.client.POST("/auth/user/{id}/notification-preferences", {
-				params: { path: pathParams },
-				body
-			}));
-		}
-		/**
 		* Generate OTP
 		*
 		* @param body - OTP generation body (phone or email)
@@ -3436,7 +2992,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 /**
 	* Client for interacting with order endpoints
 	*/
-	var OrderClient = class extends StorefrontAPIClient {
+	var OrderClient = class extends SessionStorefrontAPIClient {
 		/**
 		* Get order details
 		*
@@ -3567,41 +3123,9 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		async createOrder(body) {
 			return this.executeRequest(() => this.client.POST("/orders", { body }));
 		}
-		/**
-		* List all orders
-		*
-		* @param queryParams - Query parameters for filtering and pagination
-		* @returns Promise with order list
-		* @example
-		* ```typescript
-		* // Basic usage - only required parameter
-		* const { data, error } = await sdk.order.listOrders({
-		*   user_id: "user_01H9XYZ12345ABCDE"
-		* });
-		*
-		* // Advanced usage with optional parameters
-		* const { data, error } = await sdk.order.listOrders({
-		*   user_id: "user_01H9XYZ12345ABCDE",
-		*   page: 1,
-		*   limit: 20,
-		*   sort_by: '{"created_at":"desc"}',
-		*   status: ["confirmed", "shipped", "delivered"]
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to list orders:", error.message);
-		* } else {
-		*   console.log("Orders found:", data.orders?.length || 0);
-		*   console.log("Pagination:", data.pagination);
-		*
-		*   data.orders?.forEach(order => {
-		*     console.log(`Order ${order.order_number}: ${order.status}`);
-		*   });
-		* }
-		* ```
-		*/
-		async listOrders(queryParams) {
-			return this.executeRequest(() => this.client.GET("/orders", { params: { query: queryParams } }));
+		async listOrders(queryParams = {}) {
+			const resolvedQueryParams = await this.resolveUserQueryParams(queryParams);
+			return this.executeRequest(() => this.client.GET("/orders", { params: { query: resolvedQueryParams } }));
 		}
 		/**
 		* Get payment status for an order
@@ -3832,7 +3356,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 /**
 	* Client for interacting with payment endpoints
 	*/
-	var PaymentsClient = class extends StorefrontAPIClient {
+	var PaymentsClient = class extends SessionStorefrontAPIClient {
 		/**
 		* List all available payment methods
 		*
@@ -3975,11 +3499,11 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 	};
 
 //#endregion
-//#region src/lib/helper.ts
+//#region src/lib/shared/helper.ts
 /**
 	* Client for interacting with helper endpoints
 	*/
-	var HelpersClient = class extends StorefrontAPIClient {
+	var BaseHelpersClient = class extends StorefrontAPIClientBase {
 		/**
 		* Get a list of countries
 		*
@@ -4002,446 +3526,1077 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* });
 		* ```
 		*/
-		async listCountries() {
-			return this.executeRequest(() => this.client.GET("/common/countries", {}));
+		async listCountries() {
+			return this.executeRequest(() => this.client.GET("/common/countries", {}));
+		}
+		/**
+		* Get a list of states for a country
+		*
+		* @param pathParams - Path parameters
+		* @returns Promise with states
+		*
+		* @example
+		* ```typescript
+		* const { data, error } = await sdk.helpers.listCountryStates({
+		*   country_iso_code: "IN"
+		* });
+		*
+		* if (error) {
+		*   console.error("Failed to get states:", error);
+		*   return;
+		* }
+		*
+		* console.log("States found:", data.states?.length || 0);
+		*
+		* data.states?.forEach(state => {
+		*   console.log(`State: ${state.name} (${state.iso_code})`);
+		* });
+		*
+		* // Get states for different country
+		* const { data: usStates, error: usError } = await sdk.helpers.listCountryStates({
+		*   country_iso_code: "US"
+		* });
+		*
+		* if (usError) {
+		*   console.error("Failed to get US states:", usError);
+		*   return;
+		* }
+		*
+		* console.log("US States:", usStates.states?.map(s => s.name).join(", "));
+		* ```
+		*/
+		async listCountryStates(pathParams) {
+			return this.executeRequest(() => this.client.GET("/common/countries/{country_iso_code}/states", { params: { path: pathParams } }));
+		}
+		/**
+		* Get pincodes for a country
+		*
+		* @param pathParams - Path parameters
+		* @returns Promise with pincodes
+		*
+		* @example
+		* ```typescript
+		* const { data, error } = await sdk.helpers.listCountryPincodes({
+		*   country_iso_code: "IN"
+		* });
+		*
+		* if (error) {
+		*   console.error("Failed to get pincodes:", error);
+		*   return;
+		* }
+		*
+		* console.log("Pincodes found:", data.pincodes?.length || 0);
+		*
+		* data.pincodes?.forEach(pincode => {
+		*   console.log(`Pincode: ${pincode.pincode} - ${pincode.city}, ${pincode.state_name}`);
+		* });
+		*
+		* // Get pincodes for different country
+		* const { data: usPincodes, error: usError } = await sdk.helpers.listCountryPincodes({
+		*   country_iso_code: "US"
+		* });
+		*
+		* if (usError) {
+		*   console.error("Failed to get US pincodes:", usError);
+		*   return;
+		* }
+		*
+		* console.log("US Pincodes:", usPincodes.pincodes?.map(p => p.pincode).join(", "));
+		* ```
+		*/
+		async listCountryPincodes(pathParams, queryParams) {
+			return this.executeRequest(() => this.client.GET("/common/countries/{country_iso_code}/pincodes", { params: {
+				path: pathParams,
+				query: queryParams
+			} }));
+		}
+	};
+
+//#endregion
+//#region src/lib/public/helper.ts
+/**
+	* Client for interacting with helper endpoints
+	*/
+	var PublicHelpersClient = class extends BaseHelpersClient {};
+
+//#endregion
+//#region src/lib/helper.ts
+/**
+	* Client for interacting with helper endpoints
+	*/
+	var HelpersClient = class extends BaseHelpersClient {
+		constructor(config) {
+			super(config);
+			attachSessionAuth(this, config.sessionManager);
+		}
+	};
+
+//#endregion
+//#region src/lib/customer.ts
+/**
+	* Client for interacting with customer endpoints
+	*/
+	var CustomerClient = class extends SessionStorefrontAPIClient {
+		async listAddresses(pathParamsOrQuery, queryParams) {
+			const hasPathParams = queryParams !== void 0 || !!pathParamsOrQuery && typeof pathParamsOrQuery === "object" && "customer_id" in pathParamsOrQuery;
+			const pathParams = hasPathParams ? pathParamsOrQuery : {};
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			const resolvedQueryParams = hasPathParams ? queryParams : pathParamsOrQuery;
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/addresses", { params: {
+				path: resolvedPathParams,
+				query: resolvedQueryParams
+			} }));
+		}
+		async createAddress(pathParamsOrBody, maybeBody) {
+			const pathParams = maybeBody ? pathParamsOrBody : {};
+			const body = maybeBody ?? pathParamsOrBody;
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.POST("/customers/{customer_id}/addresses", {
+				params: { path: resolvedPathParams },
+				body
+			}));
+		}
+		async getAddress(pathParams) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/addresses/{address_id}", { params: { path: resolvedPathParams } }));
+		}
+		async updateAddress(pathParams, body) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.PUT("/customers/{customer_id}/addresses/{address_id}", {
+				params: { path: resolvedPathParams },
+				body
+			}));
+		}
+		async deleteAddress(pathParams) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.DELETE("/customers/{customer_id}/addresses/{address_id}", { params: { path: resolvedPathParams } }));
+		}
+		async getLoyaltyDetails(pathParams = {}) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/loyalty", { params: { path: resolvedPathParams } }));
+		}
+		async listLoyaltyPointsActivity(pathParamsOrQuery, queryParams) {
+			const hasPathParams = queryParams !== void 0 || !!pathParamsOrQuery && typeof pathParamsOrQuery === "object" && "customer_id" in pathParamsOrQuery;
+			const pathParams = hasPathParams ? pathParamsOrQuery : {};
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			const resolvedQueryParams = hasPathParams ? queryParams : pathParamsOrQuery;
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/loyalty-points-activity", { params: {
+				path: resolvedPathParams,
+				query: resolvedQueryParams
+			} }));
+		}
+		async listCustomerReviews(pathParams = {}) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/reviews", { params: { path: resolvedPathParams } }));
+		}
+		async listSavedPaymentMethods(pathParams = {}, queryParams) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/payment-methods", { params: {
+				path: resolvedPathParams,
+				query: queryParams
+			} }));
+		}
+		async listCustomerCards(pathParams = {}) {
+			const resolvedPathParams = await this.resolveCustomerPathParams(pathParams);
+			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/cards", { params: { path: resolvedPathParams } }));
+		}
+	};
+
+//#endregion
+//#region src/lib/shared/store-config.ts
+/**
+	* Client for interacting with store config endpoints
+	*/
+	var BaseStoreConfigClient = class extends StorefrontAPIClientBase {
+		/**
+		* Check store existence
+		*
+		* @description Checks whether a store with the configured store ID exists.
+		* Returns `success: true` if the store exists, `false` otherwise.
+		*
+		* @returns Promise with store existence check result
+		* @example
+		* ```typescript
+		* const { data, error } = await sdk.store.checkStore();
+		*
+		* if (error) {
+		*   console.error("Failed to check store:", error.message);
+		* } else {
+		*   console.log("Store exists:", data.success);
+		* }
+		* ```
+		*/
+		async checkStore() {
+			return this.executeRequest(() => this.client.GET("/store/check"));
+		}
+		/**
+		* Get store config
+		*
+		* @returns Promise with store configuration data
+		*
+		* @example
+		* ```typescript
+		* const { data, error } = await sdk.store.getStoreConfig();
+		*
+		* if (error) {
+		*   console.error('Failed to get store config:', error.message);
+		*   return;
+		* }
+		*
+		* // Access store configuration data
+		* const storeConfig = data.store_config;
+		* console.log('Store brand:', storeConfig.brand.name);
+		* console.log('Currency:', storeConfig.currency.code);
+		* console.log('KYC enabled:', storeConfig.is_kyc_enabled);
+		* console.log('Customer groups enabled:', storeConfig.is_customer_group_enabled);
+		* ```
+		*/
+		async getStoreConfig() {
+			return this.executeRequest(() => this.client.GET("/store/config"));
+		}
+	};
+
+//#endregion
+//#region src/lib/public/store-config.ts
+/**
+	* Client for interacting with store config endpoints
+	*/
+	var PublicStoreConfigClient = class extends BaseStoreConfigClient {};
+
+//#endregion
+//#region src/lib/store-config.ts
+/**
+	* Client for interacting with store config endpoints
+	*/
+	var StoreConfigClient = class extends BaseStoreConfigClient {
+		constructor(config) {
+			super(config);
+			attachSessionAuth(this, config.sessionManager);
+		}
+	};
+
+//#endregion
+//#region src/lib/storage/token-storage.ts
+/**
+	* Simple in-memory token storage implementation
+	*/
+	var MemoryTokenStorage = class {
+		accessToken = null;
+		refreshToken = null;
+		async getAccessToken() {
+			return this.accessToken;
+		}
+		async setAccessToken(token) {
+			this.accessToken = token;
+		}
+		async getRefreshToken() {
+			return this.refreshToken;
+		}
+		async setRefreshToken(token) {
+			this.refreshToken = token;
+		}
+		async clearTokens() {
+			this.accessToken = null;
+			this.refreshToken = null;
+		}
+	};
+	/**
+	* Browser localStorage token storage implementation
+	*/
+	var BrowserTokenStorage = class {
+		accessTokenKey;
+		refreshTokenKey;
+		constructor(prefix = "storefront_") {
+			this.accessTokenKey = `${prefix}access_token`;
+			this.refreshTokenKey = `${prefix}refresh_token`;
+		}
+		async getAccessToken() {
+			if (typeof localStorage === "undefined") return null;
+			return localStorage.getItem(this.accessTokenKey);
+		}
+		async setAccessToken(token) {
+			if (typeof localStorage !== "undefined") localStorage.setItem(this.accessTokenKey, token);
+		}
+		async getRefreshToken() {
+			if (typeof localStorage === "undefined") return null;
+			return localStorage.getItem(this.refreshTokenKey);
+		}
+		async setRefreshToken(token) {
+			if (typeof localStorage !== "undefined") localStorage.setItem(this.refreshTokenKey, token);
+		}
+		async clearTokens() {
+			if (typeof localStorage !== "undefined") {
+				localStorage.removeItem(this.accessTokenKey);
+				localStorage.removeItem(this.refreshTokenKey);
+			}
+		}
+	};
+	/**
+	* Cookie-based token storage implementation
+	*/
+	var CookieTokenStorage = class {
+		accessTokenKey;
+		refreshTokenKey;
+		options;
+		constructor(options = {}) {
+			const prefix = options.prefix || "storefront_";
+			this.accessTokenKey = `${prefix}access_token`;
+			this.refreshTokenKey = `${prefix}refresh_token`;
+			this.options = {
+				maxAge: options.maxAge || 10080 * 60,
+				path: options.path || "/",
+				domain: options.domain,
+				secure: options.secure ?? (typeof window !== "undefined" && window.location?.protocol === "https:"),
+				sameSite: options.sameSite || "Lax",
+				httpOnly: false
+			};
+		}
+		async getAccessToken() {
+			return this.getCookie(this.accessTokenKey);
+		}
+		async setAccessToken(token) {
+			this.setCookie(this.accessTokenKey, token);
+		}
+		async getRefreshToken() {
+			return this.getCookie(this.refreshTokenKey);
+		}
+		async setRefreshToken(token) {
+			this.setCookie(this.refreshTokenKey, token);
+		}
+		async clearTokens() {
+			this.deleteCookie(this.accessTokenKey);
+			this.deleteCookie(this.refreshTokenKey);
+		}
+		getCookie(name) {
+			if (typeof document === "undefined") return null;
+			const parts = `; ${document.cookie}`.split(`; ${name}=`);
+			if (parts.length === 2) {
+				const cookieValue = parts.pop()?.split(";").shift();
+				return cookieValue ? decodeURIComponent(cookieValue) : null;
+			}
+			return null;
+		}
+		setCookie(name, value) {
+			if (typeof document === "undefined") return;
+			let cookieString = `${name}=${encodeURIComponent(value)}`;
+			if (this.options.maxAge) cookieString += `; Max-Age=${this.options.maxAge}`;
+			if (this.options.path) cookieString += `; Path=${this.options.path}`;
+			if (this.options.domain) cookieString += `; Domain=${this.options.domain}`;
+			if (this.options.secure) cookieString += `; Secure`;
+			if (this.options.sameSite) cookieString += `; SameSite=${this.options.sameSite}`;
+			document.cookie = cookieString;
+		}
+		deleteCookie(name) {
+			if (typeof document === "undefined") return;
+			let cookieString = `${name}=; Max-Age=0`;
+			if (this.options.path) cookieString += `; Path=${this.options.path}`;
+			if (this.options.domain) cookieString += `; Domain=${this.options.domain}`;
+			document.cookie = cookieString;
+		}
+	};
+
+//#endregion
+//#region src/lib/session/jwt-utils.ts
+/**
+	* Decode a JWT token payload without signature verification.
+	* This is a lightweight replacement for jose's decodeJwt.
+	*
+	* @param token - The JWT token to decode
+	* @returns The decoded payload
+	* @throws Error if the token is malformed
+	*/
+	function decodeJwt(token) {
+		if (typeof token !== "string") throw new Error("Invalid token: must be a string");
+		const parts = token.split(".");
+		if (parts.length !== 3) throw new Error("Invalid token: must have 3 parts");
+		const base64Url = parts[1];
+		if (!base64Url) throw new Error("Invalid token: missing payload");
+		let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+		const padding = base64.length % 4;
+		if (padding) base64 += "=".repeat(4 - padding);
+		const binaryStr = atob(base64);
+		const bytes = new Uint8Array(binaryStr.length);
+		for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i);
+		const payload = JSON.parse(new TextDecoder().decode(bytes));
+		if (typeof payload !== "object" || payload === null) throw new Error("Invalid token: payload must be an object");
+		return payload;
+	}
+	/**
+	* Decode and extract user information from a JWT token
+	* 
+	* @param token - The JWT token to decode
+	* @returns User information or null if token is invalid
+	*/
+	function extractUserInfoFromToken(token) {
+		try {
+			const payload = decodeJwt(token);
+			return {
+				id: payload.ulid,
+				email: payload.email,
+				phone: payload.phone,
+				username: payload.username,
+				firstName: payload.first_name,
+				lastName: payload.last_name,
+				storeId: payload.store_id,
+				isLoggedIn: payload.is_logged_in,
+				isAnonymous: payload.is_anonymous,
+				customerId: payload.customer_id,
+				customerGroupId: payload.customer_group_id,
+				anonymousId: payload.anonymous_id,
+				channel: payload.channel,
+				tokenExpiry: /* @__PURE__ */ new Date(payload.exp * 1e3),
+				tokenIssuedAt: /* @__PURE__ */ new Date(payload.iat * 1e3)
+			};
+		} catch (error) {
+			console.warn("Failed to decode JWT token:", error);
+			return null;
+		}
+	}
+	/**
+	* Check if a JWT token is expired
+	* 
+	* @param token - The JWT token to check
+	* @param bufferSeconds - Buffer time in seconds (default: 30)
+	* @returns True if token is expired or will expire within buffer time
+	*/
+	function isTokenExpired(token, bufferSeconds = 30) {
+		try {
+			const payload = decodeJwt(token);
+			if (!payload.exp) return true;
+			return Math.floor(Date.now() / 1e3) >= payload.exp - bufferSeconds;
+		} catch (error) {
+			console.warn("Failed to decode JWT token:", error);
+			return true;
+		}
+	}
+	/**
+	* Get the user ID from a JWT token
+	* 
+	* @param token - The JWT token
+	* @returns User ID (ulid) or null if token is invalid
+	*/
+	function getUserIdFromToken(token) {
+		return extractUserInfoFromToken(token)?.id || null;
+	}
+	/**
+	* Check if user is logged in based on JWT token
+	* 
+	* @param token - The JWT token
+	* @returns True if user is logged in, false otherwise
+	*/
+	function isUserLoggedIn(token) {
+		return extractUserInfoFromToken(token)?.isLoggedIn || false;
+	}
+	/**
+	* Check if user is anonymous based on JWT token
+	* 
+	* @param token - The JWT token
+	* @returns True if user is anonymous, false otherwise
+	*/
+	function isUserAnonymous(token) {
+		return extractUserInfoFromToken(token)?.isAnonymous ?? true;
+	}
+
+//#endregion
+//#region src/types/auth-operation-metadata.ts
+	const API_KEY_ONLY_OPERATIONS = [
+		{
+			method: "POST",
+			path: "/auth/anonymous"
+		},
+		{
+			method: "GET",
+			path: "/common/countries"
+		},
+		{
+			method: "GET",
+			path: "/common/countries/{country_iso_code}/pincodes"
+		},
+		{
+			method: "GET",
+			path: "/common/countries/{country_iso_code}/states"
+		},
+		{
+			method: "GET",
+			path: "/store/check"
+		},
+		{
+			method: "GET",
+			path: "/store/config"
+		},
+		{
+			method: "GET",
+			path: "/store/kyc-document"
+		},
+		{
+			method: "GET",
+			path: "/store/sellers/{id}"
+		},
+		{
+			method: "GET",
+			path: "/store/sellers/{id}/reviews"
+		}
+	];
+
+//#endregion
+//#region src/lib/session/auth-utils.ts
+	const TOKEN_RETURNING_OPERATIONS = [
+		{
+			method: "POST",
+			path: "/auth/change-password"
+		},
+		{
+			method: "POST",
+			path: "/auth/login/password"
+		},
+		{
+			method: "POST",
+			path: "/auth/reset-password"
+		},
+		{
+			method: "POST",
+			path: "/auth/verify-otp"
+		},
+		{
+			method: "POST",
+			path: "/auth/refresh-token"
+		},
+		{
+			method: "POST",
+			path: "/auth/logout"
+		}
+	];
+	const ANONYMOUS_AUTH_OPERATION = {
+		method: "POST",
+		path: "/auth/anonymous"
+	};
+	function normalizeMethod(method) {
+		return method.toUpperCase();
+	}
+	function normalizePathname(pathname) {
+		let normalizedPathname = pathname;
+		const storefrontMarkerIndex = normalizedPathname.indexOf("/storefront");
+		if (storefrontMarkerIndex !== -1) normalizedPathname = normalizedPathname.slice(storefrontMarkerIndex + 11) || "/";
+		if (normalizedPathname.length > 1 && normalizedPathname.endsWith("/")) return normalizedPathname.slice(0, -1);
+		return normalizedPathname;
+	}
+	function matchesPathTemplate(pathTemplate, pathname) {
+		const normalizedTemplate = normalizePathname(pathTemplate);
+		const normalizedPathname = normalizePathname(pathname);
+		const templateSegments = normalizedTemplate.split("/").filter(Boolean);
+		const pathSegments = normalizedPathname.split("/").filter(Boolean);
+		if (templateSegments.length !== pathSegments.length) return false;
+		return templateSegments.every((templateSegment, index) => {
+			if (templateSegment.startsWith("{") && templateSegment.endsWith("}")) return true;
+			return templateSegment === pathSegments[index];
+		});
+	}
+	function matchesOperation(method, pathname, operation) {
+		return normalizeMethod(method) === operation.method && matchesPathTemplate(operation.path, pathname);
+	}
+	function matchesOperationList(method, pathname, operations) {
+		return operations.some((operation) => matchesOperation(method, pathname, operation));
+	}
+	/**
+	* Check if a method+path pair is the anonymous auth operation.
+	*/
+	function isAnonymousAuthOperation(method, pathname) {
+		return matchesOperation(method, pathname, ANONYMOUS_AUTH_OPERATION);
+	}
+	/**
+	* Check if a method+path pair requires API key only authentication.
+	*/
+	function isApiKeyOnlyOperation(method, pathname) {
+		return matchesOperationList(method, pathname, API_KEY_ONLY_OPERATIONS);
+	}
+	/**
+	* Check if a method+path pair returns tokens in a successful response.
+	*/
+	function isTokenReturningOperation(method, pathname) {
+		return matchesOperationList(method, pathname, TOKEN_RETURNING_OPERATIONS);
+	}
+
+//#endregion
+//#region src/lib/session/manager.ts
+/**
+	* Internal per-SDK session controller.
+	*
+	* A single instance is shared by all API clients created from the same
+	* `SessionStorefrontSDK`. This keeps refresh locks, token assessment, and session
+	* bootstrap logic coordinated in one place while preserving optional manual
+	* token management when `tokenStorage` is not provided.
+	*/
+	var StorefrontSessionManager = class {
+		tokenStorage;
+		onTokensUpdated;
+		onTokensCleared;
+		baseUrl;
+		refreshTokenFn;
+		apiKey;
+		accessToken;
+		refreshToken;
+		initializationPromise = null;
+		refreshPromise = null;
+		bootstrapPromise = null;
+		hasAssessedTokens = false;
+		constructor(options) {
+			this.tokenStorage = options.tokenStorage;
+			this.baseUrl = options.baseUrl;
+			this.apiKey = options.apiKey;
+			this.onTokensUpdated = options.onTokensUpdated;
+			this.onTokensCleared = options.onTokensCleared;
+			this.accessToken = options.accessToken ?? null;
+			this.refreshToken = options.refreshToken ?? null;
+			this.refreshTokenFn = options.refreshTokenFn;
+			if (this.tokenStorage && this.accessToken) this.initializationPromise = this.initializeManagedTokens(this.accessToken, this.refreshToken);
+		}
+		/**
+		* Update the API key used by session bootstrap and refresh flows.
+		*/
+		setApiKey(apiKey) {
+			this.apiKey = apiKey;
 		}
 		/**
-		* Get a list of states for a country
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with states
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.helpers.listCountryStates({
-		*   country_iso_code: "IN"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get states:", error);
-		*   return;
-		* }
-		*
-		* console.log("States found:", data.states?.length || 0);
-		*
-		* data.states?.forEach(state => {
-		*   console.log(`State: ${state.name} (${state.iso_code})`);
-		* });
-		*
-		* // Get states for different country
-		* const { data: usStates, error: usError } = await sdk.helpers.listCountryStates({
-		*   country_iso_code: "US"
-		* });
-		*
-		* if (usError) {
-		*   console.error("Failed to get US states:", usError);
-		*   return;
-		* }
-		*
-		* console.log("US States:", usStates.states?.map(s => s.name).join(", "));
-		* ```
+		* Remove the API key used by session bootstrap and refresh flows.
 		*/
-		async listCountryStates(pathParams) {
-			return this.executeRequest(() => this.client.GET("/common/countries/{country_iso_code}/states", { params: { path: pathParams } }));
+		clearApiKey() {
+			this.apiKey = void 0;
 		}
 		/**
-		* Get pincodes for a country
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with pincodes
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.helpers.listCountryPincodes({
-		*   country_iso_code: "IN"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get pincodes:", error);
-		*   return;
-		* }
-		*
-		* console.log("Pincodes found:", data.pincodes?.length || 0);
-		*
-		* data.pincodes?.forEach(pincode => {
-		*   console.log(`Pincode: ${pincode.pincode} - ${pincode.city}, ${pincode.state_name}`);
-		* });
-		*
-		* // Get pincodes for different country
-		* const { data: usPincodes, error: usError } = await sdk.helpers.listCountryPincodes({
-		*   country_iso_code: "US"
-		* });
-		*
-		* if (usError) {
-		*   console.error("Failed to get US pincodes:", usError);
-		*   return;
-		* }
+		* Create the auth middleware used by each API client.
 		*
-		* console.log("US Pincodes:", usPincodes.pincodes?.map(p => p.pincode).join(", "));
-		* ```
+		* The returned middleware shares the same session state and refresh locking
+		* across all clients attached to a single `SessionStorefrontSDK` instance.
 		*/
-		async listCountryPincodes(pathParams, queryParams) {
-			return this.executeRequest(() => this.client.GET("/common/countries/{country_iso_code}/pincodes", { params: {
-				path: pathParams,
-				query: queryParams
-			} }));
+		createAuthMiddleware() {
+			return {
+				onRequest: async ({ request }) => this.handleRequest(request),
+				onResponse: async ({ request, response }) => this.handleResponse(request, response)
+			};
 		}
-	};
-
-//#endregion
-//#region src/lib/customer.ts
-/**
-	* Client for interacting with customer endpoints
-	*/
-	var CustomerClient = class extends StorefrontAPIClient {
 		/**
-		* Get all saved addresses for a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with addresses
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.listAddresses({
-		*   user_id: "user_456"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to list addresses:", error);
-		*   return;
-		* }
-		*
-		* console.log("Addresses:", data.addresses);
-		* console.log("Pagination:", data.pagination);
+		* Read the current authorization header without creating a new session.
 		*
-		* // With pagination
-		* const { data: page2, error: page2Error } = await sdk.customer.listAddresses({
-		*   user_id: "user_456",
-		*   page: 2,
-		*   limit: 10
-		* });
-		* ```
+		* @returns A `Bearer` header value, or an empty string when no token exists
 		*/
-		async listAddresses(pathParams, queryParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{user_id}/addresses", { params: {
-				path: pathParams,
-				query: queryParams
-			} }));
+		async getAuthorizationHeader() {
+			const token = await this.peekAccessToken();
+			return token ? `Bearer ${token}` : "";
 		}
 		/**
-		* Create a new address for a customer
-		*
-		* @param pathParams - Path parameters
-		* @param body - Address creation body
-		* @returns Promise with address details
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.createAddress(
-		*   { user_id: "user_456" },
-		*   {
-		*     address_line1: "123 Main Street",
-		*     address_line2: "Apt 4B",
-		*     city: "New York",
-		*     state: "NY",
-		*     country: "US",
-		*     pincode: "10001",
-		*     is_default_billing: true,
-		*     is_default_shipping: false
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to create address:", error);
-		*   return;
-		* }
+		* Persist new session tokens.
 		*
-		* console.log("Address created:", data.address);
-		* ```
+		* In managed mode, tokens are written to the configured token storage. In
+		* manual mode, they are stored in memory for header injection and session
+		* inspection.
 		*/
-		async createAddress(pathParams, body) {
-			return this.executeRequest(() => this.client.POST("/customers/{user_id}/addresses", {
-				params: { path: pathParams },
-				body
-			}));
+		async setTokens(accessToken, refreshToken) {
+			const previousTokens = await this.getCurrentTokenState();
+			if (this.tokenStorage) {
+				await this.awaitInitialization();
+				await this.storeManagedTokens(accessToken, refreshToken ?? null);
+			} else {
+				this.accessToken = accessToken;
+				if (refreshToken) {
+					this.refreshToken = refreshToken;
+					console.warn("Refresh token provided but automatic refresh is disabled because tokenStorage is not configured.");
+				}
+			}
+			const nextTokens = await this.getCurrentTokenState();
+			this.notifyTokensUpdatedIfChanged(previousTokens, nextTokens);
 		}
 		/**
-		* Get an address for a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with address details
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.getAddress({
-		*   user_id: "user_456",
-		*   address_id: "addr_789"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get address:", error);
-		*   return;
-		* }
-		*
-		* console.log("Address details:", data.address);
-		* ```
+		* Clear all session tokens managed by this controller.
 		*/
-		async getAddress(pathParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{user_id}/addresses/{address_id}", { params: { path: pathParams } }));
+		async clearTokens() {
+			if (this.tokenStorage) {
+				await this.awaitInitialization();
+				await this.tokenStorage.clearTokens();
+			} else {
+				this.accessToken = null;
+				this.refreshToken = null;
+			}
+			this.onTokensCleared?.();
+		}
+		/**
+		* Clear all session tokens through the public session interface.
+		*/
+		async clear() {
+			await this.clearTokens();
+		}
+		async peekAccessToken() {
+			await this.awaitInitialization();
+			if (this.tokenStorage) return this.tokenStorage.getAccessToken();
+			return this.accessToken;
+		}
+		async peekRefreshToken() {
+			await this.awaitInitialization();
+			if (this.tokenStorage) return this.tokenStorage.getRefreshToken();
+			return this.refreshToken;
+		}
+		async peekUserInfo() {
+			const token = await this.peekAccessToken();
+			if (!token) return null;
+			return extractUserInfoFromToken(token);
+		}
+		async peekUserId() {
+			const token = await this.peekAccessToken();
+			if (!token) return null;
+			return getUserIdFromToken(token);
+		}
+		async peekCustomerId() {
+			return (await this.peekUserInfo())?.customerId ?? null;
+		}
+		async peekCustomerGroupId() {
+			return (await this.peekUserInfo())?.customerGroupId ?? null;
+		}
+		async ensureAccessToken() {
+			const token = await this.getOrCreateAccessToken();
+			if (!token) throw new Error("No session available. Configure tokenStorage + apiKey for automatic session management, or call setTokens() to set tokens manually.");
+			return token;
+		}
+		async ensureUserInfo() {
+			const userInfo = extractUserInfoFromToken(await this.ensureAccessToken());
+			if (!userInfo) throw new Error("Failed to extract user information from access token.");
+			return userInfo;
+		}
+		async ensureUserId() {
+			const userId = getUserIdFromToken(await this.ensureAccessToken());
+			if (!userId) throw new Error("Failed to extract user ID from access token.");
+			return userId;
+		}
+		async ensureCustomerId() {
+			const userInfo = await this.ensureUserInfo();
+			if (!userInfo.customerId) throw new Error("No customer_id available. User must be logged in (not anonymous) for this operation. Pass customer_id explicitly or log in first.");
+			return userInfo.customerId;
+		}
+		async handleRequest(request) {
+			const method = request.method;
+			const pathname = getPathnameFromUrl(request.url);
+			if (this.tokenStorage) await this.assessTokenStateOnce();
+			if (isAnonymousAuthOperation(method, pathname)) return this.prepareAnonymousAuthRequest(request);
+			if (isApiKeyOnlyOperation(method, pathname)) {
+				this.applyApiKeyHeader(request);
+				return request;
+			}
+			const accessToken = await this.getOrCreateAccessToken();
+			if (accessToken) request.headers.set("Authorization", `Bearer ${accessToken}`);
+			return request;
+		}
+		async handleResponse(request, response) {
+			if (!this.tokenStorage) return response;
+			const method = request.method;
+			const pathname = getPathnameFromUrl(request.url);
+			if (response.ok) {
+				await this.captureTokensFromResponse(method, pathname, response);
+				return response;
+			}
+			if (response.status === 401 && !isAnonymousAuthOperation(method, pathname) && !isApiKeyOnlyOperation(method, pathname)) {
+				const currentToken = await this.peekAccessToken();
+				if (currentToken && isTokenExpired(currentToken, 0)) try {
+					await this.refreshTokens();
+					const refreshedToken = await this.peekAccessToken();
+					if (refreshedToken) {
+						const retryRequest = request.clone();
+						retryRequest.headers.set("Authorization", `Bearer ${refreshedToken}`);
+						return fetch(retryRequest);
+					}
+				} catch (error) {
+					console.warn("Token refresh failed on 401 response:", error);
+				}
+			}
+			return response;
+		}
+		async prepareAnonymousAuthRequest(request) {
+			this.applyApiKeyHeader(request);
+			const existingToken = await this.peekAccessToken();
+			if (this.tokenStorage && existingToken && !isTokenExpired(existingToken) && isUserLoggedIn(existingToken)) return new Response(JSON.stringify({
+				message: "Cannot create anonymous session while authenticated",
+				success: false,
+				code: "USER_ALREADY_AUTHENTICATED"
+			}), {
+				status: 400,
+				headers: { "Content-Type": "application/json" }
+			});
+			if (existingToken) request.headers.set("Authorization", `Bearer ${existingToken}`);
+			return request;
+		}
+		applyApiKeyHeader(request) {
+			if (this.apiKey) request.headers.set("X-Api-Key", this.apiKey);
+		}
+		/**
+		* Snapshot the effective token pair from storage (managed mode) or
+		* in-memory fields (manual mode). Used before and after `setTokens()` to
+		* detect whether the tokens actually changed.
+		*/
+		async getCurrentTokenState() {
+			await this.awaitInitialization();
+			if (this.tokenStorage) return {
+				accessToken: await this.tokenStorage.getAccessToken(),
+				refreshToken: await this.tokenStorage.getRefreshToken()
+			};
+			return {
+				accessToken: this.accessToken,
+				refreshToken: this.refreshToken
+			};
+		}
+		/**
+		* Fire `onTokensUpdated` only when the effective token pair differs from
+		* the previous snapshot. This prevents duplicate notifications when
+		* `setTokens()` is called with the same values already in storage.
+		*/
+		notifyTokensUpdatedIfChanged(previousTokens, nextTokens) {
+			if (!this.onTokensUpdated || !nextTokens.accessToken) return;
+			if (previousTokens.accessToken === nextTokens.accessToken && previousTokens.refreshToken === nextTokens.refreshToken) return;
+			this.onTokensUpdated(nextTokens.accessToken, nextTokens.refreshToken ?? "");
+		}
+		/**
+		* Internal token acquisition — returns null on failure instead of throwing.
+		* Used by middleware so requests degrade gracefully.
+		*/
+		async getOrCreateAccessToken() {
+			if (!this.tokenStorage) return this.peekAccessToken();
+			await this.awaitInitialization();
+			await this.assessTokenStateOnce();
+			let accessToken = await this.tokenStorage.getAccessToken();
+			if (!accessToken) accessToken = await this.bootstrapAnonymousSession();
+			if (accessToken && isTokenExpired(accessToken)) try {
+				await this.refreshTokens();
+				accessToken = await this.tokenStorage.getAccessToken();
+			} catch {
+				accessToken = await this.tokenStorage.getAccessToken();
+			}
+			return accessToken;
+		}
+		async initializeManagedTokens(accessToken, refreshToken) {
+			try {
+				await this.storeManagedTokens(accessToken, refreshToken);
+			} catch (error) {
+				console.warn("Failed to initialize tokens in storage:", error);
+			} finally {
+				this.accessToken = null;
+				this.refreshToken = null;
+			}
+		}
+		async awaitInitialization() {
+			if (this.initializationPromise) {
+				await this.initializationPromise;
+				this.initializationPromise = null;
+			}
+		}
+		async assessTokenStateOnce() {
+			if (!this.tokenStorage || this.hasAssessedTokens) return;
+			this.hasAssessedTokens = true;
+			try {
+				const accessToken = await this.tokenStorage.getAccessToken();
+				const refreshToken = await this.tokenStorage.getRefreshToken();
+				if (!accessToken && refreshToken) {
+					await this.tokenStorage.clearTokens();
+					console.info("Cleaned up orphaned refresh token");
+				}
+			} catch (error) {
+				console.warn("Token state assessment failed:", error);
+			}
+		}
+		async bootstrapAnonymousSession() {
+			if (!this.tokenStorage) return null;
+			if (this.bootstrapPromise) return this.bootstrapPromise;
+			this.bootstrapPromise = (async () => {
+				try {
+					const response = await fetch(`${this.baseUrl}/auth/anonymous`, {
+						method: "POST",
+						headers: {
+							"Content-Type": "application/json",
+							...this.apiKey && { "X-Api-Key": this.apiKey }
+						}
+					});
+					if (!response.ok) return null;
+					const tokens = (await response.json()).content;
+					if (tokens?.access_token && tokens?.refresh_token) {
+						await this.storeManagedTokens(tokens.access_token, tokens.refresh_token);
+						this.onTokensUpdated?.(tokens.access_token, tokens.refresh_token);
+						console.info("Automatically created anonymous session for first API request");
+						return tokens.access_token;
+					}
+					return null;
+				} catch (error) {
+					console.warn("Failed to automatically create anonymous tokens:", error);
+					return null;
+				} finally {
+					this.bootstrapPromise = null;
+				}
+			})();
+			return this.bootstrapPromise;
+		}
+		async refreshTokens() {
+			if (!this.tokenStorage) return;
+			const tokenStorage = this.tokenStorage;
+			if (this.refreshPromise) return this.refreshPromise;
+			this.refreshPromise = (async () => {
+				try {
+					const refreshToken = await tokenStorage.getRefreshToken();
+					let newTokens;
+					if (refreshToken && !isTokenExpired(refreshToken)) if (this.refreshTokenFn) newTokens = await this.refreshTokenFn(refreshToken);
+					else {
+						const response = await fetch(`${this.baseUrl}/auth/refresh-token`, {
+							method: "POST",
+							headers: { "Content-Type": "application/json" },
+							body: JSON.stringify({ refresh_token: refreshToken })
+						});
+						if (!response.ok) throw new Error(`Token refresh failed: ${response.status}`);
+						newTokens = (await response.json()).content;
+					}
+					else {
+						const currentAccessToken = await tokenStorage.getAccessToken();
+						if (!currentAccessToken) throw new Error("No tokens available for refresh");
+						const reason = refreshToken ? "refresh token expired" : "no refresh token available";
+						const response = await fetch(`${this.baseUrl}/auth/anonymous`, {
+							method: "POST",
+							headers: {
+								"Content-Type": "application/json",
+								...this.apiKey && { "X-Api-Key": this.apiKey },
+								Authorization: `Bearer ${currentAccessToken}`
+							}
+						});
+						if (!response.ok) throw new Error(`Anonymous token fallback failed: ${response.status}`);
+						newTokens = (await response.json()).content;
+						console.info(`Token refreshed via anonymous fallback (${reason}) - user may need to re-authenticate for privileged operations`);
+					}
+					await this.storeManagedTokens(newTokens.access_token, newTokens.refresh_token);
+					this.onTokensUpdated?.(newTokens.access_token, newTokens.refresh_token);
+				} catch (error) {
+					console.error("Token refresh failed:", error);
+					await this.clearTokens();
+					throw error;
+				} finally {
+					this.refreshPromise = null;
+				}
+			})();
+			return this.refreshPromise;
+		}
+		async captureTokensFromResponse(method, pathname, response) {
+			if (!this.tokenStorage || !(isTokenReturningOperation(method, pathname) || isAnonymousAuthOperation(method, pathname))) return;
+			try {
+				const content = (await response.clone().json()).content;
+				if (content?.access_token && content?.refresh_token) {
+					await this.storeManagedTokens(content.access_token, content.refresh_token);
+					this.onTokensUpdated?.(content.access_token, content.refresh_token);
+				}
+			} catch (error) {
+				console.warn("Failed to extract tokens from response:", error);
+			}
+		}
+		async storeManagedTokens(accessToken, refreshToken) {
+			if (!this.tokenStorage) return;
+			await this.tokenStorage.setAccessToken(accessToken);
+			if (refreshToken) await this.tokenStorage.setRefreshToken(refreshToken);
+		}
+	};
+
+//#endregion
+//#region src/lib/public/client.ts
+/**
+	* Storefront API client that always authenticates with `X-Api-Key`.
+	*
+	* This client is used by the public storefront surface where no session or
+	* token lifecycle should be involved.
+	*/
+	var PublicStorefrontAPIClient = class extends StorefrontAPIClientBase {
+		constructor(config) {
+			super(config);
+			this.setupPublicAuth();
 		}
-		/**
-		* Update an address for a customer
-		*
-		* @param pathParams - Path parameters
-		* @param body - Address update body
-		* @returns Promise with address details
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.updateAddress(
-		*   {
-		*     user_id: "user_456",
-		*     address_id: "addr_789"
-		*   },
-		*   {
-		*     address_line1: "456 Oak Avenue",
-		*     city: "Los Angeles",
-		*     state: "CA",
-		*     pincode: "90210"
-		*   }
-		* );
-		*
-		* if (error) {
-		*   console.error("Failed to update address:", error);
-		*   return;
-		* }
-		*
-		* console.log("Address updated:", data.address);
-		* ```
-		*/
-		async updateAddress(pathParams, body) {
-			return this.executeRequest(() => this.client.PUT("/customers/{user_id}/addresses/{address_id}", {
-				params: { path: pathParams },
-				body
-			}));
+		setupPublicAuth() {
+			this.client.use({ onRequest: async ({ request }) => {
+				if (this.apiKey) request.headers.set("X-Api-Key", this.apiKey);
+				return request;
+			} });
 		}
+	};
+
+//#endregion
+//#region src/index.ts
+/**
+	* Public SDK class for the Storefront API.
+	*
+	* This surface is intentionally limited to API-key-backed, public read
+	* operations so it can be used safely during build and prerender flows.
+	*/
+	var PublicStorefrontSDK = class {
 		/**
-		* Delete an address for a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with deletion response
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.deleteAddress({
-		*   user_id: "user_456",
-		*   address_id: "addr_789"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to delete address:", error);
-		*   return;
-		* }
-		*
-		* console.log("Address deleted:", data.message);
-		* ```
+		* Client for catalog-related read-only endpoints
 		*/
-		async deleteAddress(pathParams) {
-			return this.executeRequest(() => this.client.DELETE("/customers/{user_id}/addresses/{address_id}", { params: { path: pathParams } }));
-		}
+		catalog;
 		/**
-		* Get customer loyalty details
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with loyalty details
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.getLoyaltyDetails({
-		*   user_id: "user_456"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get loyalty details:", error);
-		*   return;
-		* }
-		*
-		* console.log("Loyalty info:", data.loyalty);
-		* console.log("Points balance:", data.loyalty_point_balance);
-		* ```
+		* Client for helper-related endpoints
 		*/
-		async getLoyaltyDetails(pathParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{user_id}/loyalty", { params: { path: pathParams } }));
-		}
+		helpers;
 		/**
-		* List all loyalty points activity for a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with loyalty points activity
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.listLoyaltyPointsActivity({
-		*   user_id: "user_456"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get loyalty activity:", error);
-		*   return;
-		* }
-		*
-		* console.log("Loyalty activity:", data.loyalty_points_activity);
-		*
-		* // With pagination and sorting
-		* const { data: sortedData, error: sortedError } = await sdk.customer.listLoyaltyPointsActivity({
-		*   user_id: "user_456",
-		*   page: 1,
-		*   limit: 20,
-		*   sort_by: JSON.stringify({ "created_at": "desc" })
-		* });
-		* ```
+		* Client for store config-related endpoints
 		*/
-		async listLoyaltyPointsActivity(pathParams, queryParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{user_id}/loyalty-points-activity", { params: {
-				path: pathParams,
-				query: queryParams
-			} }));
-		}
+		store;
 		/**
-		* List all reviews left by a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with reviews
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.listCustomerReviews({
-		*   user_id: "user_456"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to get customer reviews:", error);
-		*   return;
-		* }
-		*
-		* console.log("Customer reviews:", data.reviews);
-		* console.log("Ready for review:", data.ready_for_review);
-		* ```
+		* Centrally stored default headers for consistency
 		*/
-		async listCustomerReviews(pathParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{user_id}/reviews", { params: { path: pathParams } }));
+		defaultHeaders;
+		constructor(options) {
+			this.defaultHeaders = options.defaultHeaders;
+			const config = {
+				storeId: options.storeId,
+				environment: options.environment,
+				baseUrl: options.baseUrl,
+				apiKey: options.apiKey,
+				timeout: options.timeout,
+				defaultHeaders: options.defaultHeaders,
+				debug: options.debug,
+				logger: options.logger
+			};
+			this.catalog = new PublicCatalogClient(config);
+			this.helpers = new PublicHelpersClient(config);
+			this.store = new PublicStoreConfigClient(config);
 		}
 		/**
-		* List all saved payment methods for a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with payment methods
+		* Set the API key for all public clients
 		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.listSavedPaymentMethods({
-		*   customer_id: "customer_123"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to list saved payment methods:", error);
-		*   return;
-		* }
-		*
-		* console.log("Saved payment methods:", data.saved_payment_methods);
-		* ```
+		* @param apiKey - The API key to set
 		*/
-		async listSavedPaymentMethods(pathParams, queryParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/payment-methods", { params: {
-				path: pathParams,
-				query: queryParams
-			} }));
+		setApiKey(apiKey) {
+			this.catalog.setApiKey(apiKey);
+			this.helpers.setApiKey(apiKey);
+			this.store.setApiKey(apiKey);
 		}
 		/**
-		* List all saved cards for a customer
-		*
-		* @param pathParams - Path parameters
-		* @returns Promise with cards
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.customer.listCustomerCards({
-		*   customer_id: "customer_123"
-		* });
-		*
-		* if (error) {
-		*   console.error("Failed to list customer cards:", error);
-		*   return;
-		* }
-		*
-		* console.log("Customer cards:", data.cards);
-		* ```
+		* Clear the API key from all public clients
 		*/
-		async listCustomerCards(pathParams) {
-			return this.executeRequest(() => this.client.GET("/customers/{customer_id}/cards", { params: { path: pathParams } }));
+		clearApiKey() {
+			this.catalog.clearApiKey();
+			this.helpers.clearApiKey();
+			this.store.clearApiKey();
 		}
-	};
-
-//#endregion
-//#region src/lib/store-config.ts
-/**
-	* Client for interacting with store config endpoints
-	*/
-	var StoreConfigClient = class extends StorefrontAPIClient {
 		/**
-		* Check store existence
-		*
-		* @description Checks whether a store with the configured store ID exists.
-		* Returns `success: true` if the store exists, `false` otherwise.
-		*
-		* @returns Promise with store existence check result
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.storeConfig.checkStore();
+		* Set default headers for all public clients
 		*
-		* if (error) {
-		*   console.error("Failed to check store:", error.message);
-		* } else {
-		*   console.log("Store exists:", data.success);
-		* }
-		* ```
+		* @param headers - Default headers to set (only supported headers allowed)
 		*/
-		async checkStore() {
-			return this.executeRequest(() => this.client.GET("/store/check"));
+		setDefaultHeaders(headers) {
+			this.defaultHeaders = headers;
+			this.catalog.setDefaultHeaders(headers);
+			this.helpers.setDefaultHeaders(headers);
+			this.store.setDefaultHeaders(headers);
 		}
 		/**
-		* Get store config
-		*
-		* @returns Promise with store configuration data
-		*
-		* @example
-		* ```typescript
-		* const { data, error } = await sdk.storeConfig.getStoreConfig();
-		*
-		* if (error) {
-		*   console.error('Failed to get store config:', error.message);
-		*   return;
-		* }
+		* Get current default headers
 		*
-		* // Access store configuration data
-		* const storeConfig = data.store_config;
-		* console.log('Store brand:', storeConfig.brand.name);
-		* console.log('Currency:', storeConfig.currency.code);
-		* console.log('KYC enabled:', storeConfig.is_kyc_enabled);
-		* console.log('Customer groups enabled:', storeConfig.is_customer_group_enabled);
-		* ```
+		* @returns Current default headers from central storage (always consistent)
 		*/
-		async getStoreConfig() {
-			return this.executeRequest(() => this.client.GET("/store/config"));
+		getDefaultHeaders() {
+			return this.defaultHeaders;
 		}
 	};
-
-//#endregion
-//#region src/index.ts
-/**
-	* Main SDK class for the Storefront API
+	/**
+	* Main session-aware SDK class for the Storefront API
 	*/
-	var StorefrontSDK = class {
+	var SessionStorefrontSDK = class {
 		/**
 		* Client for catalog-related endpoints (products, categories, etc.)
 		*/
@@ -4479,12 +4634,33 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		*/
 		defaultHeaders;
 		/**
-		* Create a new StorefrontSDK instance
+		* Shared session helper and coordinator for all API clients in this SDK instance.
+		*/
+		session;
+		sessionManager;
+		/**
+		* Create a new SessionStorefrontSDK instance
 		*
 		* @param options - Configuration options for the SDK
 		*/
 		constructor(options) {
 			this.defaultHeaders = options.defaultHeaders;
+			const sessionManager = new StorefrontSessionManager({
+				accessToken: options.accessToken,
+				apiKey: options.apiKey,
+				baseUrl: buildStorefrontURL({
+					storeId: options.storeId,
+					environment: options.environment,
+					baseUrl: options.baseUrl
+				}),
+				onTokensCleared: options.onTokensCleared,
+				onTokensUpdated: options.onTokensUpdated,
+				refreshToken: options.refreshToken,
+				refreshTokenFn: options.refreshTokenFn,
+				tokenStorage: options.tokenStorage
+			});
+			this.sessionManager = sessionManager;
+			this.session = sessionManager;
 			const config = {
 				storeId: options.storeId,
 				environment: options.environment,
@@ -4498,7 +4674,8 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 				onTokensCleared: options.onTokensCleared,
 				defaultHeaders: options.defaultHeaders,
 				debug: options.debug,
-				logger: options.logger
+				logger: options.logger,
+				sessionManager
 			};
 			this.catalog = new CatalogClient(config);
 			this.cart = new CartClient(config);
@@ -4520,14 +4697,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* - If tokenStorage is not provided: Only stores access token for manual management
 		*/
 		async setTokens(accessToken, refreshToken) {
-			await this.catalog.setTokens(accessToken, refreshToken);
-			await this.cart.setTokens(accessToken, refreshToken);
-			await this.auth.setTokens(accessToken, refreshToken);
-			await this.customer.setTokens(accessToken, refreshToken);
-			await this.helpers.setTokens(accessToken, refreshToken);
-			await this.order.setTokens(accessToken, refreshToken);
-			await this.payments.setTokens(accessToken, refreshToken);
-			await this.store.setTokens(accessToken, refreshToken);
+			await this.sessionManager.setTokens(accessToken, refreshToken);
 		}
 		/**
 		* Clear all authentication tokens from all clients
@@ -4537,14 +4707,7 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* - If tokenStorage is not provided: Clears the manual access token
 		*/
 		async clearTokens() {
-			await this.catalog.clearTokens();
-			await this.cart.clearTokens();
-			await this.auth.clearTokens();
-			await this.customer.clearTokens();
-			await this.helpers.clearTokens();
-			await this.order.clearTokens();
-			await this.payments.clearTokens();
-			await this.store.clearTokens();
+			await this.sessionManager.clearTokens();
 		}
 		/**
 		* Set the API key for all clients
@@ -4552,57 +4715,58 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		* @param apiKey - The API key to set
 		*/
 		setApiKey(apiKey) {
-			this.catalog.setApiKey(apiKey);
-			this.cart.setApiKey(apiKey);
-			this.auth.setApiKey(apiKey);
-			this.customer.setApiKey(apiKey);
-			this.helpers.setApiKey(apiKey);
-			this.order.setApiKey(apiKey);
-			this.payments.setApiKey(apiKey);
-			this.store.setApiKey(apiKey);
+			this.sessionManager.setApiKey(apiKey);
 		}
 		/**
 		* Clear the API key from all clients
 		*/
 		clearApiKey() {
-			this.catalog.clearApiKey();
-			this.cart.clearApiKey();
-			this.auth.clearApiKey();
-			this.customer.clearApiKey();
-			this.helpers.clearApiKey();
-			this.order.clearApiKey();
-			this.payments.clearApiKey();
-			this.store.clearApiKey();
+			this.sessionManager.clearApiKey();
 		}
 		/**
 		* Get the current access token if using token storage
+		*
+		* This is a passive lookup. It will not create or refresh a session.
 		*/
 		async getAccessToken() {
-			return await this.auth.getAuthorizationHeader().then((header) => header.startsWith("Bearer ") ? header.substring(7) : null);
+			return this.session.peekAccessToken();
+		}
+		/**
+		* Ensure an access token is available for the current session.
+		*
+		* This may create or refresh a managed session when automatic token
+		* management is configured.
+		*
+		* @returns A usable access token
+		*/
+		async ensureAccessToken() {
+			return this.session.ensureAccessToken();
 		}
 		/**
 		* Get user information from the current access token
 		*
+		* This is a passive lookup. It will not create or refresh a session.
+		*
 		* @returns User information extracted from JWT token, or null if no token or invalid token
 		*/
 		async getUserInfo() {
-			const token = await this.getAccessToken();
-			if (!token) return null;
-			return extractUserInfoFromToken(token);
+			return this.session.peekUserInfo();
 		}
 		/**
 		* Get the current user ID from the access token
 		*
+		* This is a passive lookup. It will not create or refresh a session.
+		*
 		* @returns User ID (ulid) or null if no token or invalid token
 		*/
 		async getUserId() {
-			const token = await this.getAccessToken();
-			if (!token) return null;
-			return getUserIdFromToken(token);
+			return this.session.peekUserId();
 		}
 		/**
 		* Check if the current user is logged in (not anonymous)
 		*
+		* This is a passive lookup. It will not create or refresh a session.
+		*
 		* @returns True if user is logged in, false if anonymous or no token
 		*/
 		async isLoggedIn() {
@@ -4613,6 +4777,8 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		/**
 		* Check if the current user is anonymous
 		*
+		* This is a passive lookup. It will not create or refresh a session.
+		*
 		* @returns True if user is anonymous or no token, false if logged in
 		*/
 		async isAnonymous() {
@@ -4623,18 +4789,22 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 		/**
 		* Get the customer ID from the current access token
 		*
+		* This is a passive lookup. It will not create or refresh a session.
+		*
 		* @returns Customer ID or null if no token, invalid token, or user has no customer ID
 		*/
 		async getCustomerId() {
-			return (await this.getUserInfo())?.customerId || null;
+			return this.session.peekCustomerId();
 		}
 		/**
 		* Get the customer group ID from the current access token
 		*
+		* This is a passive lookup. It will not create or refresh a session.
+		*
 		* @returns Customer group ID or null if no token, invalid token, or user has no customer group
 		*/
 		async getCustomerGroupId() {
-			return (await this.getUserInfo())?.customerGroupId || null;
+			return this.session.peekCustomerGroupId();
 		}
 		/**
 		* Set default headers for all clients
@@ -4661,6 +4831,70 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
 			return this.defaultHeaders;
 		}
 	};
+	function buildPublicStorefrontOptions(options) {
+		return {
+			storeId: options.storeId,
+			environment: options.environment,
+			baseUrl: options.baseUrl,
+			apiKey: options.apiKey,
+			timeout: options.timeout,
+			defaultHeaders: options.defaultHeaders,
+			debug: options.debug,
+			logger: options.logger
+		};
+	}
+	function buildSessionStorefrontOptions(options, overrides) {
+		return {
+			...buildPublicStorefrontOptions(options),
+			...options.session,
+			...overrides
+		};
+	}
+	/**
+	* Create a configured storefront factory with explicit public and session
+	* access patterns.
+	*
+	* @example
+	* ```typescript
+	* import {
+	*   BrowserTokenStorage,
+	*   createStorefront,
+	*   Environment,
+	* } from "@commercengine/storefront-sdk";
+	*
+	* export const storefront = createStorefront({
+	*   storeId: "your-store-id",
+	*   apiKey: "your-api-key",
+	*   environment: Environment.Staging,
+	*   session: {
+	*     tokenStorage: new BrowserTokenStorage("myapp_"),
+	*   },
+	* });
+	*
+	* const { data: products } = await storefront.public().catalog.listProducts();
+	* const { data: cart } = await storefront.session().cart.getCart();
+	* ```
+	*
+	* @param options - Shared public config plus optional default session config
+	* @returns A storefront factory with explicit `public()` and `session()` accessors
+	*/
+	function createStorefront(options) {
+		const publicOptions = buildPublicStorefrontOptions(options);
+		let publicSDK = null;
+		let sessionSDK = null;
+		const session = (overrides) => {
+			if (overrides && Object.keys(overrides).length > 0) return new SessionStorefrontSDK(buildSessionStorefrontOptions(options, overrides));
+			if (!sessionSDK) sessionSDK = new SessionStorefrontSDK(buildSessionStorefrontOptions(options));
+			return sessionSDK;
+		};
+		return {
+			public: () => {
+				if (!publicSDK) publicSDK = new PublicStorefrontSDK(publicOptions);
+				return publicSDK;
+			},
+			session
+		};
+	}
 
 //#endregion
 exports.AuthClient = AuthClient;
@@ -4674,11 +4908,16 @@ exports.HelpersClient = HelpersClient;
 exports.MemoryTokenStorage = MemoryTokenStorage;
 exports.OrderClient = OrderClient;
 exports.PaymentsClient = PaymentsClient;
+exports.PublicCatalogClient = PublicCatalogClient;
+exports.PublicHelpersClient = PublicHelpersClient;
+exports.PublicStoreConfigClient = PublicStoreConfigClient;
+exports.PublicStorefrontAPIClient = PublicStorefrontAPIClient;
+exports.PublicStorefrontSDK = PublicStorefrontSDK;
 exports.ResponseUtils = ResponseUtils;
+exports.SessionStorefrontAPIClient = SessionStorefrontAPIClient;
+exports.SessionStorefrontSDK = SessionStorefrontSDK;
 exports.StoreConfigClient = StoreConfigClient;
-exports.StorefrontAPIClient = StorefrontAPIClient;
-exports.StorefrontSDK = StorefrontSDK;
-exports.default = StorefrontSDK;
+exports.createStorefront = createStorefront;
 return exports;
 })({});
 //# sourceMappingURL=index.iife.js.map