@commercengine/storefront-sdk 0.13.3 → 0.14.0

package/dist/index.mjs

@@ -75,7 +75,6 @@ var ResponseUtils = class {
 */
 var DebugLogger = class {
 	logger;
-	responseTextCache = /* @__PURE__ */ new Map();
 	constructor(logger) {
 		this.logger = logger || ((level, message, data) => {
 			console.log(`[${level.toUpperCase()}]`, message);
@@ -98,7 +97,6 @@ var DebugLogger = class {
 	* 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,
@@ -122,17 +120,17 @@ var DebugLogger = class {
 		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);
 	}
@@ -218,14 +216,33 @@ function createDebugMiddleware(logger) {
 * @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
@@ -291,8 +308,8 @@ async function executeRequest(apiCall) {
 		};
 	} catch (err) {
 		const mockResponse = new Response(null, {
-			status: 0,
-			statusText: "Network Error"
+			status: 503,
+			statusText: "Service Unavailable"
 		});
 		return {
 			data: null,
@@ -412,619 +429,228 @@ function getPathnameFromUrl(url) {
 }
 
 //#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
-/**
-* Check if a URL path is an auth endpoint that should use API key
-*/
-function isAnonymousAuthEndpoint(pathname) {
-	return pathname.endsWith("/auth/anonymous");
-}
+//#region src/lib/shared/client.ts
 /**
-* 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
+//#region src/lib/session/client.ts
+function attachSessionAuth(client, sessionManager) {
+	client.useMiddleware(sessionManager.createAuthMiddleware());
+}
 /**
-* Simple in-memory token storage implementation
+* 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({
@@ -1121,7 +747,7 @@ var CatalogClient = class extends StorefrontAPIClient {
 	/**
 	* 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
 	*
@@ -1129,7 +755,7 @@ var CatalogClient = class extends StorefrontAPIClient {
 	* ```typescript
 	* // Get product by ID
 	* const { data, error } = await sdk.catalog.getProductDetail(
-	*   { product_id_or_slug: "prod_123" }
+	*   { product_id: "prod_123" }
 	* );
 	*
 	* if (error) {
@@ -1141,14 +767,15 @@ var CatalogClient = class extends StorefrontAPIClient {
 	* 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
 	*   }
@@ -1164,7 +791,7 @@ var CatalogClient = class extends StorefrontAPIClient {
 	*/
 	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
@@ -1173,12 +800,13 @@ var CatalogClient = class extends StorefrontAPIClient {
 	/**
 	* 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" }
 	* );
@@ -1194,9 +822,15 @@ var CatalogClient = class extends StorefrontAPIClient {
 	*   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
 	*   }
@@ -1214,12 +848,13 @@ var CatalogClient = class extends StorefrontAPIClient {
 	/**
 	* 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",
@@ -1236,6 +871,14 @@ var CatalogClient = class extends StorefrontAPIClient {
 	* 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) {
@@ -1320,49 +963,6 @@ var CatalogClient = class extends StorefrontAPIClient {
 		} }));
 	}
 	/**
-	* 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
@@ -1602,12 +1202,74 @@ var CatalogClient = class extends StorefrontAPIClient {
 	}
 };
 
+//#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
 	*
@@ -1729,49 +1391,14 @@ var CartClient = class extends StorefrontAPIClient {
 			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
 		}));
 	}
@@ -2264,92 +1891,31 @@ var CartClient = class extends StorefrontAPIClient {
 			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
 		}));
 	}
@@ -2360,7 +1926,7 @@ var CartClient = class extends StorefrontAPIClient {
 /**
 * Client for interacting with authentication endpoints
 */
-var AuthClient = class extends StorefrontAPIClient {
+var AuthClient = class extends SessionStorefrontAPIClient {
 	/**
 	* Get anonymous token for guest users
 	*
@@ -2493,13 +2059,14 @@ var AuthClient = class extends StorefrontAPIClient {
 		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"
 	* });
@@ -2507,13 +2074,17 @@ var AuthClient = class extends StorefrontAPIClient {
 	* 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
@@ -2595,7 +2166,8 @@ var AuthClient = class extends StorefrontAPIClient {
 	* 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
@@ -2610,20 +2182,24 @@ var AuthClient = class extends StorefrontAPIClient {
 	* 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
@@ -2637,32 +2213,96 @@ var AuthClient = class extends StorefrontAPIClient {
 	* 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("Token refreshed successfully");
-	*   console.log("New access token:", data.access_token);
+	*   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);
 	*   console.log("New refresh token:", data.refresh_token);
 	* }
 	* ```
@@ -2913,90 +2553,6 @@ var AuthClient = class extends StorefrontAPIClient {
 		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)
@@ -3056,7 +2612,7 @@ var AuthClient = class extends StorefrontAPIClient {
 /**
 * Client for interacting with order endpoints
 */
-var OrderClient = class extends StorefrontAPIClient {
+var OrderClient = class extends SessionStorefrontAPIClient {
 	/**
 	* Get order details
 	*
@@ -3187,41 +2743,9 @@ var OrderClient = class extends StorefrontAPIClient {
 	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
@@ -3452,7 +2976,7 @@ var OrderClient = class extends StorefrontAPIClient {
 /**
 * Client for interacting with payment endpoints
 */
-var PaymentsClient = class extends StorefrontAPIClient {
+var PaymentsClient = class extends SessionStorefrontAPIClient {
 	/**
 	* List all available payment methods
 	*
@@ -3595,11 +3119,11 @@ var PaymentsClient = class extends StorefrontAPIClient {
 };
 
 //#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
 	*
@@ -3622,446 +3146,1077 @@ var HelpersClient = class extends StorefrontAPIClient {
 	* });
 	* ```
 	*/
-	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);
+	* Create the auth middleware used by each API client.
 	*
-	* 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(", "));
-	* ```
+	* 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
+	* Read the current authorization header without creating a new session.
 	*
-	* @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);
-	*
-	* // 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
+	* Set the API key for all public clients
 	*
-	* @param pathParams - Path parameters
-	* @returns Promise with payment methods
-	*
-	* @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.)
 	*/
@@ -4099,12 +4254,33 @@ var StorefrontSDK = class {
 	*/
 	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,
@@ -4118,7 +4294,8 @@ var StorefrontSDK = class {
 			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);
@@ -4140,14 +4317,7 @@ var StorefrontSDK = class {
 	* - 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
@@ -4157,14 +4327,7 @@ var StorefrontSDK = class {
 	* - 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
@@ -4172,57 +4335,58 @@ var StorefrontSDK = class {
 	* @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() {
@@ -4233,6 +4397,8 @@ var StorefrontSDK = class {
 	/**
 	* 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() {
@@ -4243,18 +4409,22 @@ var StorefrontSDK = class {
 	/**
 	* 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
@@ -4281,7 +4451,71 @@ var StorefrontSDK = class {
 		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
-export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, ResponseUtils, StoreConfigClient, StorefrontAPIClient, StorefrontSDK, StorefrontSDK as default };
+export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient, createStorefront };
 //# sourceMappingURL=index.mjs.map