@commercengine/storefront-sdk 0.14.0 → 0.14.2

package/MIGRATION.md

@@ -40,6 +40,9 @@ const publicSdk = storefront.public();
 const sessionSdk = storefront.session();
 ```
 
+The factory owns one cached public SDK and one cached default session SDK, so
+most applications only need a single shared `storefront` export.
+
 ## Before / After
 
 ### Managed session SDK

package/README.md

@@ -5,6 +5,11 @@ A powerful, type-safe TypeScript SDK for the CommerceEngine Storefront API. Buil
 Breaking changes from the previous SDK surface are documented in
 [MIGRATION.md](./MIGRATION.md).
 
+If you are building an application on an official framework wrapper such as
+Next.js, prefer [`@commercengine/storefront`](../storefront/README.md). This
+package is the standalone isomorphic core SDK for SPA usage, advanced custom
+integrations, and framework bindings.
+
 **✨ Key Features:**
 - **100% Type Safe**: Every API endpoint is fully typed with TypeScript
 - **Automatic Token Management**: Built-in refresh token logic for seamless authentication
@@ -51,6 +56,11 @@ const { data: products } = await storefront.public().catalog.listProducts();
 const { data: wishlist } = await storefront.session().cart.getWishlist();
 ```
 
+`createStorefront()` returns one cached public SDK and one cached default
+session SDK for that factory instance. Use `storefront.session(overrides)` only
+for one-off, token-seeded/stateless cases that should not reuse the default
+session client.
+
 ## Configuration Options
 
 The SDK supports extensive configuration to fit your needs:
@@ -121,6 +131,18 @@ const sdk = new SessionStorefrontSDK({
 });
 ```
 
+If you need the raw public transport classes directly, the advanced exports are
+also available:
+
+```typescript
+import {
+  PublicStorefrontAPIClient,
+  PublicStorefrontSDK,
+  SessionStorefrontAPIClient,
+  SessionStorefrontSDK,
+} from "@commercengine/storefront-sdk";
+```
+
 ## Token Management
 
 The SDK supports three primary access patterns:
@@ -210,7 +232,7 @@ import { BrowserTokenStorage } from "@commercengine/storefront-sdk";
 const tokenStorage = new BrowserTokenStorage("myapp_"); // Optional prefix
 ```
 
-#### Cookies (for SSR or cross-tab sync)
+#### Browser cookies (for browser persistence or cross-tab sync)
 ```typescript
 import { CookieTokenStorage } from "@commercengine/storefront-sdk";
 
@@ -222,6 +244,12 @@ const tokenStorage = new CookieTokenStorage({
 });
 ```
 
+`CookieTokenStorage` uses `document.cookie` and is browser-only. It is useful
+for browser cookie persistence and cross-tab visibility, but it is **not**
+request-aware SSR storage. For framework server/client continuity, use an
+official wrapper from `@commercengine/storefront` or a request-aware storage
+adapter from `@commercengine/ssr-utils`.
+
 #### Memory (for server-side or temporary storage)
 ```typescript
 import { MemoryTokenStorage } from "@commercengine/storefront-sdk";
@@ -246,7 +274,14 @@ class CustomTokenStorage implements TokenStorage {
 
 ## Authentication
 
-If you use managed sessions (`tokenStorage`), you usually do not need to call anonymous auth manually. The SDK can bootstrap anonymous sessions automatically on token-required requests.
+If you use managed sessions (`tokenStorage`), you usually do not need to call
+anonymous auth manually. The SDK can bootstrap anonymous sessions
+automatically on token-required requests.
+
+That lazy bootstrap is a core SDK capability, not necessarily the primary app
+pattern for every framework. For official framework wrappers, the recommended
+pattern is still to bootstrap explicitly in app code when later server-side
+session reads depend on established cookie continuity.
 
 ### Anonymous Authentication
 ```typescript
@@ -467,10 +502,10 @@ The SDK works seamlessly across all JavaScript environments:
 - **Background jobs**: Reliable token management for long-running processes
 
 ### Hybrid Rendering (SSR/SSG)
-- **Next.js, Nuxt, SvelteKit, Remix**: Use request-aware cookie-backed storage
-- **CookieTokenStorage**: Useful for browser cookie persistence
-- **Cookie-based storage**: Maintains sessions across server/client boundaries
-- **Hydration-safe**: No client/server state mismatches
+- **Official framework wrappers**: Prefer `@commercengine/storefront`
+- **Custom SSR integrations**: Use request-aware storage from `@commercengine/ssr-utils`
+- **CookieTokenStorage**: Browser-only cookie persistence, not server request storage
+- **Hydration-safe setups**: depend on framework-aware request storage, not `document.cookie`
 
 ## Best Practices Built-In
 

package/dist/index.d.mts

@@ -12582,7 +12582,7 @@ type StorefrontClientBaseConfig = BaseSDKOptions<SupportedDefaultHeaders> & {
  * decisions to the public and session-specific subclasses.
  */
 declare class StorefrontAPIClientBase extends BaseAPIClient<paths, SupportedDefaultHeaders> {
-  protected apiKey?: string;
+  apiKey?: string;
   constructor(config: StorefrontClientBaseConfig);
   setApiKey(apiKey: string): void;
   clearApiKey(): void;
@@ -12595,7 +12595,11 @@ type SessionStorefrontClientConfig = StorefrontClientBaseConfig & SessionStorefr
 };
 /**
  * Storefront API client that extends the generic BaseAPIClient
- * Adds Commerce Engine specific authentication and token management
+ * Adds Commerce Engine specific authentication and token management.
+ *
+ * Session-only domain clients can extend this directly. Shared public/session
+ * read clients may instead extend a shared base class and call
+ * `attachSessionAuth()` explicitly in their concrete session wrapper.
  */
 declare class SessionStorefrontAPIClient extends StorefrontAPIClientBase {
   protected config: SessionStorefrontClientConfig;
@@ -13972,11 +13976,25 @@ declare class BaseCatalogClient extends StorefrontAPIClientBase {
   listSimilarProducts(options?: ListSimilarProductsQuery, headers?: ListSimilarProductsHeaderParams): Promise<ApiResult<ListSimilarProductsContent>>;
 }
 //#endregion
+//#region src/lib/public/client.d.ts
+/**
+ * Storefront API client that always authenticates with `X-Api-Key`.
+ *
+ * This class is kept as the advanced public transport client. Concrete public
+ * domain clients can either extend this directly or extend a shared base class
+ * and attach the same auth behavior via `attachPublicAuth()`.
+ */
+declare class PublicStorefrontAPIClient extends StorefrontAPIClientBase {
+  constructor(config: StorefrontClientBaseConfig);
+}
+//#endregion
 //#region src/lib/public/catalog.d.ts
 /**
  * Client for interacting with catalog endpoints
  */
-declare class PublicCatalogClient extends BaseCatalogClient {}
+declare class PublicCatalogClient extends BaseCatalogClient {
+  constructor(config: ConstructorParameters<typeof PublicStorefrontAPIClient>[0]);
+}
 //#endregion
 //#region src/lib/catalog.d.ts
 /**
@@ -15916,7 +15934,9 @@ declare class BaseHelpersClient extends StorefrontAPIClientBase {
 /**
  * Client for interacting with helper endpoints
  */
-declare class PublicHelpersClient extends BaseHelpersClient {}
+declare class PublicHelpersClient extends BaseHelpersClient {
+  constructor(config: ConstructorParameters<typeof PublicStorefrontAPIClient>[0]);
+}
 //#endregion
 //#region src/lib/helper.d.ts
 /**
@@ -16276,7 +16296,9 @@ declare class BaseStoreConfigClient extends StorefrontAPIClientBase {
 /**
  * Client for interacting with store config endpoints
  */
-declare class PublicStoreConfigClient extends BaseStoreConfigClient {}
+declare class PublicStoreConfigClient extends BaseStoreConfigClient {
+  constructor(config: ConstructorParameters<typeof PublicStorefrontAPIClient>[0]);
+}
 //#endregion
 //#region src/lib/store-config.d.ts
 /**
@@ -16286,18 +16308,6 @@ declare class StoreConfigClient extends BaseStoreConfigClient {
   constructor(config: ConstructorParameters<typeof SessionStorefrontAPIClient>[0]);
 }
 //#endregion
-//#region src/lib/public/client.d.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.
- */
-declare class PublicStorefrontAPIClient extends StorefrontAPIClientBase {
-  constructor(config: StorefrontClientBaseConfig);
-  private setupPublicAuth;
-}
-//#endregion
 //#region src/index.d.ts
 /**
  * Public SDK class for the Storefront API.

package/dist/index.iife.js

@@ -886,7 +886,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	}
 	/**
 	* Storefront API client that extends the generic BaseAPIClient
-	* Adds Commerce Engine specific authentication and token management
+	* Adds Commerce Engine specific authentication and token management.
+	*
+	* Session-only domain clients can extend this directly. Shared public/session
+	* read clients may instead extend a shared base class and call
+	* `attachSessionAuth()` explicitly in their concrete session wrapper.
 	*/
 	var SessionStorefrontAPIClient = class extends StorefrontAPIClientBase {
 		config;
@@ -1582,12 +1586,39 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 	};
 
+//#endregion
+//#region src/lib/public/client.ts
+/**
+	* Storefront API client that always authenticates with `X-Api-Key`.
+	*
+	* This class is kept as the advanced public transport client. Concrete public
+	* domain clients can either extend this directly or extend a shared base class
+	* and attach the same auth behavior via `attachPublicAuth()`.
+	*/
+	var PublicStorefrontAPIClient = class extends StorefrontAPIClientBase {
+		constructor(config) {
+			super(config);
+			attachPublicAuth(this);
+		}
+	};
+	function attachPublicAuth(client) {
+		client.useMiddleware({ onRequest: async ({ request }) => {
+			if (client.apiKey) request.headers.set("X-Api-Key", client.apiKey);
+			return request;
+		} });
+	}
+
 //#endregion
 //#region src/lib/public/catalog.ts
 /**
 	* Client for interacting with catalog endpoints
 	*/
-	var PublicCatalogClient = class extends BaseCatalogClient {};
+	var PublicCatalogClient = class extends BaseCatalogClient {
+		constructor(config) {
+			super(config);
+			attachPublicAuth(this);
+		}
+	};
 
 //#endregion
 //#region src/lib/catalog.ts
@@ -3617,7 +3648,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 /**
 	* Client for interacting with helper endpoints
 	*/
-	var PublicHelpersClient = class extends BaseHelpersClient {};
+	var PublicHelpersClient = class extends BaseHelpersClient {
+		constructor(config) {
+			super(config);
+			attachPublicAuth(this);
+		}
+	};
 
 //#endregion
 //#region src/lib/helper.ts
@@ -3761,7 +3797,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 /**
 	* Client for interacting with store config endpoints
 	*/
-	var PublicStoreConfigClient = class extends BaseStoreConfigClient {};
+	var PublicStoreConfigClient = class extends BaseStoreConfigClient {
+		constructor(config) {
+			super(config);
+			attachPublicAuth(this);
+		}
+	};
 
 //#endregion
 //#region src/lib/store-config.ts
@@ -4493,27 +4534,6 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 	};
 
-//#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();
-		}
-		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
 /**