@commercengine/storefront-sdk 0.14.1 → 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

@@ -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;
@@ -13976,8 +13980,9 @@ declare class BaseCatalogClient extends StorefrontAPIClientBase {
 /**
  * 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.
+ * 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);

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;
@@ -1587,8 +1591,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 /**
 	* 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.
+	* 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) {