@marianmeres/ecsuite 1.3.2 → 2.1.0

package/AGENTS.md

@@ -6,7 +6,7 @@ Machine-readable documentation for AI coding assistants.
 
 ```yaml
 name: "@marianmeres/ecsuite"
-version: "1.1.4"
+version: "1.3.2"
 type: "library"
 language: "typescript"
 runtime: "deno"
@@ -28,12 +28,13 @@ E-commerce frontend UI state management library providing:
 
 ```
 ECSuite (orchestrator)
-├── CartManager      [localStorage, optimistic updates]
-├── WishlistManager  [localStorage, optimistic updates]
-├── OrderManager     [server-only, read + create (returns model_id)]
+├── CartManager      [localStorage, optimistic updates, per-domain mutation queue]
+├── WishlistManager  [localStorage, optimistic updates, per-domain mutation queue]
+├── OrderManager     [server-only, read + create — list of {model_id, data}]
 ├── CustomerManager  [server-only, read + update + fetchBySession]
-├── PaymentManager   [server-only, read + initiate + capture]
-└── ProductManager   [in-memory cache with TTL]
+├── PaymentManager   [server-only, read + initiate + capture (throw NOT_IMPL)]
+└── ProductManager   [in-memory TTL cache; extends BaseDomainManager;
+                      in-flight dedup; emits domain:error]
 ```
 
 ## Directory Structure
@@ -57,15 +58,27 @@ src/
 │   ├── payment.ts            # PaymentManager
 │   └── product.ts            # ProductManager
 └── adapters/
-    ├── mod.ts                # Adapter exports
-    └── mock/                 # Mock adapters for testing
+    ├── mod.ts                # Adapter exports (re-exports mock/* and http/*)
+    ├── mock/                 # Mock adapters for testing
+    │   ├── mod.ts
+    │   ├── cart.ts
+    │   ├── wishlist.ts
+    │   ├── order.ts
+    │   ├── customer.ts
+    │   ├── payment.ts
+    │   └── product.ts
+    └── http/                 # Built-in HTTP adapters
         ├── mod.ts
-        ├── cart.ts
-        ├── wishlist.ts
-        ├── order.ts
-        ├── customer.ts
-        ├── payment.ts
-        └── product.ts
+        ├── _http.ts          # Shared fetch primitives (authHeaders, sessionHeader, requestJson)
+        ├── cart.ts           # createHttpCartAdapter
+        ├── wishlist.ts       # createHttpWishlistAdapter
+        ├── order.ts          # createHttpOrderAdapter
+        ├── customer.ts       # createHttpCustomerAdapter
+        ├── payment.ts        # createHttpPaymentAdapter (capture omitted)
+        └── product.ts        # createHttpProductAdapter
+example/
+├── index.html                # Vanilla-JS reference harness — every public verb
+└── src/app.ts                # imports ../../src/mod.ts
 tests/
 ├── cart.test.ts
 ├── wishlist.test.ts
@@ -73,6 +86,7 @@ tests/
 ├── customer.test.ts
 ├── payment.test.ts
 ├── product.test.ts
+├── http-adapters.test.ts     # Unit tests for the built-in HTTP adapters
 └── ecsuite.test.ts
 ```
 
@@ -142,8 +156,74 @@ export {
 	MockProductAdapterOptions,
 	MockWishlistAdapterOptions,
 } from "./adapters/mod.ts";
+
+// Built-in HTTP Adapters
+export {
+	createHttpCartAdapter,
+	createHttpCustomerAdapter,
+	createHttpOrderAdapter,
+	createHttpPaymentAdapter,
+	createHttpProductAdapter,
+	createHttpWishlistAdapter,
+	HttpAdapterOptions,
+	HttpCartAdapterOptions,
+	HttpCustomerAdapterOptions,
+	HttpOrderAdapterOptions,
+	HttpPaymentAdapterOptions,
+	HttpProductAdapterOptions,
+	HttpWishlistAdapterOptions,
+} from "./adapters/mod.ts";
 ```
 
+## Built-in HTTP Adapters
+
+Each factory returns an object conforming to the matching `*Adapter`
+interface in `src/types/adapter.ts`. They target a conventional commerce
+REST surface; see the `README.md` "Built-in HTTP Adapters" section for the
+endpoint table.
+
+Key rules:
+
+- Adapters are **thin** — they throw raw HTTP errors (`Error` with
+  `.status` and `.body` attached); the domain manager normalizes them to
+  `DomainError`. Don't normalize inside the adapter.
+- Authentication comes off `DomainContext`:
+  - `ctx.jwt`       → `Authorization: Bearer <jwt>`
+  - `ctx.sessionId` → `X-Session-ID`
+- `ctx.customerId` is required for the customer adapter's
+  owner-scoped route.
+- `_http.ts` holds the shared primitives (`authHeaders`, `sessionHeader`,
+  `requestJson`, `join`, `require*Id`); every adapter is ~50–70 lines.
+- `createHttpOrderAdapter.create()` is a **single-call** adapter
+  targeting `POST /checkout/start`. The addresses → delivery → payment →
+  complete checkout flow is not wrapped by the adapter in v2.x; callers
+  drive the remaining steps directly.
+- `createHttpPaymentAdapter.initiate()` posts `{ order_id, provider,
+  return_url, cancel_url }` to `POST {baseUrl}/initiate`. **No
+  `amount`/`currency` in the body** — the server derives them from the
+  order row (security: prevents client-side tampering), and the target
+  route strictly requires all four listed fields. The adapter throws a
+  client-side error if `return_url` or `cancel_url` is missing from the
+  `PaymentInitConfig`. The server additionally requires the order to have
+  passed checkout validation (addresses + delivery set) before initiating
+  payment — callers are responsible for the upstream steps.
+- `createHttpPaymentAdapter` intentionally omits `capture` — consumers
+  calling `suite.payment.capture()` will get `NOT_IMPLEMENTED` from the
+  manager. Capture is typically server-driven (webhooks + checkout
+  complete).
+- `createHttpCustomerAdapter` omits `fetchBySession` — there is no clean
+  session-scoped read endpoint on the target surface. Consumers should
+  hydrate customer state from the JWT subject claim or pass an explicit
+  `customerId` on context.
+
+## Reference Harness
+
+`example/` ships a vanilla-JS harness that exercises every public verb of
+every domain manager. It can swap between mock adapters (zero-setup
+default) and the built-in HTTP adapters (real server round-trip). Runs
+through `deno task example:build` / `example:watch` + any static file
+server.
+
 ## State Machine
 
 ```
@@ -166,7 +246,29 @@ const suite = createECSuite({
 	storage: { type: "local" },
 	productCacheTtl: 300000,
 	autoInitialize: true,
+	autoResetOnIdentityChange: true, // default: reset on customerId transition
 });
+
+// Avoid the auto-init race: callers should await the suite's readiness
+// before issuing mutations.
+await suite.ready;
+```
+
+### Identity Switch
+
+```typescript
+// Atomic: merge context, reset all domains, re-initialize.
+await suite.switchIdentity({ customerId: "another" });
+
+// Or via setContext when autoResetOnIdentityChange is enabled.
+suite.setContext({ customerId: "another" });
+await suite.ready;
+```
+
+### Teardown
+
+```typescript
+suite.destroy(); // unsubscribes all internal pubsub listeners
 ```
 
 ### Selective Initialization
@@ -280,20 +382,32 @@ deno publish           # Publish to JSR
 
 ## Important Implementation Details
 
-1. **Optimistic Updates**: `_withOptimisticUpdate()` in BaseDomainManager captures previous state before mutation, rolls back on server error.
+1. **Optimistic Updates**: `withOptimisticUpdate()` in BaseDomainManager captures previous state before mutation, rolls back to it (including `null`) on server error. Mutations are **serialized per domain** through an internal mutation queue so concurrent callers can't race their rollback snapshots.
 
-2. **Persistence**: Cart and Wishlist use `@marianmeres/store` with `createStoragePersistor()` for localStorage/sessionStorage.
+2. **Persistence**: Cart and Wishlist use `@marianmeres/store` with `createStoragePersistor()` for localStorage/sessionStorage. (Cross-tab `storage` event sync is NOT yet implemented.)
 
-3. **ProductManager**: Does NOT extend BaseDomainManager. Uses simple Map cache with TTL instead of state machine.
+3. **ProductManager**: Extends BaseDomainManager with `data: null` (cache lives in a private Map). Exposes `subscribe`, emits `domain:error` (without changing state — a single failed product fetch shouldn't blanket the whole domain in error). Uses an in-flight Map to dedup concurrent `getById` callers (prevents stampede on TTL expiry).
 
 4. **Event System**: Shared PubSub instance passed through ECSuite constructor. Events typed with discriminated union.
 
 5. **Context**: DomainContext (customerId, sessionId, + arbitrary properties via index signature) passed to all adapter methods for server-side identification.
 
-6. **OrderCreateResult**: `OrderAdapter.create()` returns `{ model_id, data }` so consumers always get the server-assigned model ID.
+6. **OrderListData**: Stores `OrderCreateResult[]` (`{ model_id, data }`). `fetchAll`/`fetchOne`/`create` all return this envelope so orders are uniquely identifiable. Use `getOrderById(modelId)` / `getOrderDataById(modelId)`.
 
-7. **Payment Write Ops**: `PaymentAdapter.initiate?()` and `capture?()` are optional methods. `PaymentManager` null-checks before calling, returns null when unavailable.
+7. **Payment Write Ops**: `PaymentAdapter.initiate?()` and `capture?()` are optional adapter methods. `PaymentManager` **throws** `NOT_IMPLEMENTED` (and emits `domain:error`) when called without an implementation — callers must catch or feature-detect (`adapter.initiate !== undefined`).
 
-8. **Guest Checkout**: `CustomerAdapter.fetchBySession?()` is optional. `CustomerManager` uses it when `customerId` is absent in context, falls back to `fetch()` when unavailable.
+8. **Guest Checkout**: `CustomerAdapter.fetchBySession?()` is optional. When `customerId` is absent in context AND `fetchBySession` isn't implemented, `CustomerManager` warns and stays in `ready` with `data: null` — it does NOT silently call `fetch()` anymore (real adapters typically need a `customerId`).
 
 9. **Operation Hooks**: `ECSuite.onBeforeSync()` and `onAfterSync()` are convenience wrappers over the existing event system (no changes to BaseDomainManager).
+
+10. **Identity Switches**: `setContext({ customerId })` auto-resets all domains and re-initializes when the id transitions (default; opt out via `autoResetOnIdentityChange: false`). Awaitable via `suite.ready` or use `suite.switchIdentity()` directly.
+
+11. **Auto-init race**: Constructor with `autoInitialize: true` (default) starts initialize() but cannot await it; consumers should `await suite.ready` before issuing mutations.
+
+12. **Cart Quantity Validation**: `addItem` and `updateItemQuantity` throw `TypeError`/`RangeError` for `NaN`, `Infinity`, fractional, or negative values at the call site (never persisted optimistically).
+
+## Known limitations (not yet fixed)
+
+- **Payment grouping by orderId**: `PaymentManager.getPayments()` returns a flat list. There is no `getPaymentsForOrder(orderId)` helper because `PaymentData` does not carry the order id; consumers fetching for multiple orders must keep their own index.
+- **Pagination**: `OrderAdapter.fetchAll` and `PaymentAdapter.fetchForOrder` have no `limit/offset/cursor` params.
+- **Cross-tab sync**: localStorage edits in one tab don't propagate to other tabs' stores.

package/API.md

@@ -59,6 +59,14 @@ interface ECSuiteConfig {
 	productCacheTtl?: number;
 	/** Auto-initialize on creation (default: true) */
 	autoInitialize?: boolean;
+	/** Domains to initialize (default: all) */
+	initializeDomains?: InitializableDomainName[];
+	/**
+	 * Reset and re-initialize all domains automatically when `setContext()`
+	 * changes `customerId`. Default: true. Set false to manage identity
+	 * transitions yourself via `switchIdentity()`.
+	 */
+	autoResetOnIdentityChange?: boolean;
 }
 ```
 
@@ -66,33 +74,48 @@ interface ECSuiteConfig {
 
 #### Properties
 
-| Property   | Type              | Description             |
-| ---------- | ----------------- | ----------------------- |
-| `cart`     | `CartManager`     | Cart domain manager     |
-| `wishlist` | `WishlistManager` | Wishlist domain manager |
-| `order`    | `OrderManager`    | Order domain manager    |
-| `customer` | `CustomerManager` | Customer domain manager |
-| `payment`  | `PaymentManager`  | Payment domain manager  |
-| `product`  | `ProductManager`  | Product domain manager  |
+| Property   | Type              | Description                                                          |
+| ---------- | ----------------- | -------------------------------------------------------------------- |
+| `cart`     | `CartManager`     | Cart domain manager                                                  |
+| `wishlist` | `WishlistManager` | Wishlist domain manager                                              |
+| `order`    | `OrderManager`    | Order domain manager                                                 |
+| `customer` | `CustomerManager` | Customer domain manager                                              |
+| `payment`  | `PaymentManager`  | Payment domain manager                                               |
+| `product`  | `ProductManager`  | Product domain manager                                               |
+| `ready`    | `Promise<void>`   | Resolves when the most recent (auto or manual) `initialize()` settles |
 
 #### Methods
 
-##### initialize()
+##### initialize(domains?)
 
-Initialize all domains. Called automatically if `autoInitialize` is true.
+Initialize the chosen domains (or all by default). Called automatically if
+`autoInitialize` is true. The most recently initialized set is remembered
+and re-used for identity-switch re-initialization.
 
 ```typescript
-async initialize(): Promise<void>
+async initialize(domains?: InitializableDomainName[]): Promise<void>
 ```
 
 ##### setContext(context)
 
-Update context across all domains.
+Update context across all domains. If `customerId` transitions and
+`autoResetOnIdentityChange` is enabled (default), this also resets all
+domains and re-initializes them — `suite.ready` is updated to the new
+in-flight promise.
 
 ```typescript
 setContext(context: DomainContext): void
 ```
 
+##### switchIdentity(context)
+
+Atomic identity switch: merge context, reset all domains, re-initialize.
+Returns a promise that settles when the re-init completes.
+
+```typescript
+async switchIdentity(context: DomainContext): Promise<void>
+```
+
 ##### getContext()
 
 Get the current context.
@@ -133,6 +156,16 @@ Reset all domains to initial state.
 reset(): void
 ```
 
+##### destroy()
+
+Tear down the suite: unsubscribe all listeners on the internal pubsub and
+clear the product cache. Persisted storage is intentionally NOT cleared;
+call `reset()` first if you also want to wipe in-memory state.
+
+```typescript
+destroy(): void
+```
+
 ---
 
 ## Domain Managers
@@ -381,10 +414,11 @@ async fetchAll(): Promise<void>
 
 ##### fetchOne(orderId)
 
-Fetch single order by ID.
+Fetch single order by ID. Updates an existing entry in the local list (matched
+by `model_id`) or appends a new one.
 
 ```typescript
-async fetchOne(orderId: UUID): Promise<OrderData | null>
+async fetchOne(orderId: UUID): Promise<OrderCreateResult | null>
 ```
 
 ##### create(orderData)
@@ -392,7 +426,7 @@ async fetchOne(orderId: UUID): Promise<OrderData | null>
 Create a new order.
 
 ```typescript
-async create(orderData: OrderCreatePayload): Promise<OrderData | null>
+async create(orderData: OrderCreatePayload): Promise<OrderCreateResult | null>
 ```
 
 **Emits:** `order:created`
@@ -407,18 +441,34 @@ getOrderCount(): number
 
 ##### getOrders()
 
-Get all orders.
+Get all order envelopes.
+
+```typescript
+getOrders(): OrderCreateResult[]
+```
+
+##### getOrderById(modelId)
+
+Look up an order envelope by its server-assigned `model_id`.
 
 ```typescript
-getOrders(): OrderData[]
+getOrderById(modelId: UUID): OrderCreateResult | undefined
+```
+
+##### getOrderDataById(modelId)
+
+Same as `getOrderById` but returns the bare `OrderData` payload.
+
+```typescript
+getOrderDataById(modelId: UUID): OrderData | undefined
 ```
 
 ##### getOrderByIndex(index)
 
-Get order by index.
+Get order envelope by index.
 
 ```typescript
-getOrderByIndex(index: number): OrderData | undefined
+getOrderByIndex(index: number): OrderCreateResult | undefined
 ```
 
 ---
@@ -521,12 +571,38 @@ async fetchForOrder(orderId: UUID): Promise<PaymentData[]>
 
 ##### fetchOne(paymentId)
 
-Fetch single payment by ID.
+Fetch single payment by ID. Updates the existing entry (matched by
+`provider_reference`) or appends a new one.
 
 ```typescript
 async fetchOne(paymentId: UUID): Promise<PaymentData | null>
 ```
 
+##### initiate(orderId, config)
+
+Initiate a payment for an order. **Throws** if `adapter.initiate` is not
+implemented (also emits `domain:error` with `code: "NOT_IMPLEMENTED"`).
+
+```typescript
+async initiate(
+	orderId: UUID,
+	config: PaymentInitConfig,
+): Promise<PaymentIntent | null>
+```
+
+**Emits:** `payment:initiated`
+
+##### capture(paymentId)
+
+Capture a previously initiated payment. **Throws** if `adapter.capture` is
+not implemented (also emits `domain:error` with `code: "NOT_IMPLEMENTED"`).
+
+```typescript
+async capture(paymentId: UUID): Promise<PaymentData | null>
+```
+
+**Emits:** `payment:captured`
+
 ##### getPaymentCount()
 
 Get number of fetched payments.
@@ -563,7 +639,12 @@ clearCache(): void
 
 ### ProductManager
 
-Manages product data with in-memory caching. Unlike other managers, uses a simple cache layer instead of state machine.
+Manages product data with in-memory TTL caching. Extends `BaseDomainManager`
+for unified observability (`subscribe`, `domain:error`, `domain:state:changed`)
+but skips per-product state-machine transitions — fetching a single product
+never blankets the whole domain in `"syncing"` or `"error"`. Concurrent
+`getById()` callers for the same id share a single in-flight request
+(stampede dedup).
 
 #### Constructor Options
 
@@ -645,7 +726,6 @@ interface CartAdapter {
 	updateItem(productId: UUID, quantity: number, ctx: DomainContext): Promise<CartData>;
 	removeItem(productId: UUID, ctx: DomainContext): Promise<CartData>;
 	clear(ctx: DomainContext): Promise<CartData>;
-	sync(cart: CartData, ctx: DomainContext): Promise<CartData>;
 }
 ```
 
@@ -657,16 +737,19 @@ interface WishlistAdapter {
 	addItem(productId: UUID, ctx: DomainContext): Promise<WishlistData>;
 	removeItem(productId: UUID, ctx: DomainContext): Promise<WishlistData>;
 	clear(ctx: DomainContext): Promise<WishlistData>;
-	sync(wishlist: WishlistData, ctx: DomainContext): Promise<WishlistData>;
 }
 ```
 
 ### OrderAdapter
 
+> Returns `OrderCreateResult` envelopes (`{ model_id, data }`) so the
+> manager can identify orders by `model_id` (bare `OrderData` has only an
+> open index signature).
+
 ```typescript
 interface OrderAdapter {
-	fetchAll(ctx: DomainContext): Promise<OrderData[]>;
-	fetchOne(orderId: UUID, ctx: DomainContext): Promise<OrderData>;
+	fetchAll(ctx: DomainContext): Promise<OrderCreateResult[]>;
+	fetchOne(orderId: UUID, ctx: DomainContext): Promise<OrderCreateResult>;
 	create(order: OrderCreatePayload, ctx: DomainContext): Promise<OrderData>;
 }
 ```

package/README.md

@@ -41,6 +41,10 @@ const suite = createECSuite({
 	},
 });
 
+// `autoInitialize` is true by default; await `suite.ready` so consumer
+// mutations don't race the in-flight initial fetches.
+await suite.ready;
+
 // Subscribe to cart state (Svelte-compatible)
 suite.cart.subscribe((state) => {
 	console.log(state.state, state.data);
@@ -57,6 +61,23 @@ suite.on("domain:error", (event) => {
 await suite.cart.addItem({ product_id: "prod-1", quantity: 2 });
 ```
 
+### Identity switches (login / logout)
+
+When the user signs in or out, use `switchIdentity()` (or just call
+`setContext()` with a different `customerId` — auto-reset is on by default):
+
+```typescript
+await suite.switchIdentity({ customerId: "another-user" });
+// All domains reset, re-initialized for the new identity, and `suite.ready`
+// resolves once the new fetches settle.
+```
+
+### Teardown
+
+```typescript
+suite.destroy(); // unsubscribes every internal event listener
+```
+
 ## Domains
 
 | Domain   | Persistence  | Operations                          |
@@ -123,6 +144,63 @@ const suite = createECSuite({
 });
 ```
 
+## Built-in HTTP Adapters
+
+For consumers whose backend exposes the conventional commerce REST surface,
+ecsuite ships ready-to-use HTTP adapters for every domain. Each factory
+takes `{ baseUrl?, fetch? }`; authentication is carried on the context
+passed into each call (`ctx.sessionId` → `X-Session-ID`; `ctx.jwt` →
+`Authorization: Bearer <jwt>`).
+
+```typescript
+import {
+	createECSuite,
+	createHttpCartAdapter,
+	createHttpCustomerAdapter,
+	createHttpOrderAdapter,
+	createHttpPaymentAdapter,
+	createHttpProductAdapter,
+	createHttpWishlistAdapter,
+} from "@marianmeres/ecsuite";
+
+const suite = createECSuite({
+	context: { sessionId: mySessionId, jwt: myJwt, customerId: myCustomerId },
+	adapters: {
+		cart: createHttpCartAdapter({ baseUrl: "/api/session" }),
+		wishlist: createHttpWishlistAdapter({ baseUrl: "/api/session" }),
+		order: createHttpOrderAdapter({ baseUrl: "/api/order" }),
+		customer: createHttpCustomerAdapter({ baseUrl: "/api/customer" }),
+		payment: createHttpPaymentAdapter({ baseUrl: "/api/payment" }),
+		product: createHttpProductAdapter({ baseUrl: "/api/product" }),
+	},
+});
+```
+
+Expected endpoints per adapter (all mutations require `X-Session-ID`, all
+owner-scoped reads require a JWT):
+
+| Adapter  | Endpoints                                                                                           |
+| -------- | --------------------------------------------------------------------------------------------------- |
+| cart     | `GET/POST/PUT/DELETE {baseUrl}/cart` (DELETE with optional `?product_id=` for single-item remove)   |
+| wishlist | `GET/POST/DELETE {baseUrl}/wishlist` (DELETE with optional `?product_id=` for single-item remove)   |
+| order    | `GET {baseUrl}/col/order`, `GET {baseUrl}/col/order/:id`, `POST {baseUrl}/checkout/start`           |
+| customer | `GET/PUT {baseUrl}/me/col/customer/:customerId`                                                     |
+| payment  | `GET {baseUrl}/by-order/:orderId`, `GET {baseUrl}/col/payment/:id`, `POST {baseUrl}/initiate` (body: `{ order_id, provider, return_url, cancel_url }` — server derives amount/currency from the order record) |
+| product  | `GET {baseUrl}/col/product/:id` (`fetchMany` = parallel single fetches — no batch endpoint assumed) |
+
+Adapters throw raw HTTP errors (`Error` with `.status` and `.body`
+attached); the domain manager normalizes them to `DomainError`. Responses
+may use `{ model_id, data }` model envelopes — adapters unwrap them
+transparently.
+
+`PaymentAdapter.capture` is intentionally omitted from
+`createHttpPaymentAdapter`; capture is typically driven server-side by
+provider webhooks + checkout completion. Calls to `suite.payment.capture()`
+will surface as `NOT_IMPLEMENTED`.
+
+See [`example/`](./example/) for a vanilla-JS reference harness exercising
+every public verb against either the HTTP adapters or the mock adapters.
+
 ## Events
 
 Subscribe to domain events:
@@ -145,6 +223,55 @@ suite.once("order:created", (event) => {
 
 For complete API documentation, see [API.md](API.md).
 
+## Migration to next major
+
+This release tightens correctness in several places. Breaking changes:
+
+- **`OrderAdapter` returns `OrderCreateResult`** for both `fetchAll` and
+  `fetchOne` (`{ model_id, data }`) so orders are uniquely identifiable.
+  `OrderListData.orders` is now `OrderCreateResult[]`. Use the new
+  `orders.getOrderById(modelId)` / `getOrderDataById(modelId)` helpers, or
+  read `result.data.<field>` on returned envelopes.
+- **`CartAdapter.sync()` and `WishlistAdapter.sync()` removed** — they were
+  never called by the manager.
+- **`PaymentManager.initiate()` / `capture()` throw `NOT_IMPLEMENTED`** when
+  the adapter doesn't implement the optional method (previously returned
+  `null` silently). `domain:error` is also emitted.
+- **`CustomerManager.update()` throws `NOT_IMPLEMENTED`** when no adapter is
+  configured (previously silent no-op).
+- **`CustomerManager` no longer falls through to `fetch()`** when both
+  `customerId` is missing AND `adapter.fetchBySession` is undefined; it
+  now warns and stays in `ready` with `data: null`. Pass `customerId` in
+  context, or implement `fetchBySession`.
+- **`CartManager.addItem` / `updateItemQuantity`** validate the quantity
+  (must be a finite, non-negative integer); invalid values throw at the
+  call site instead of being persisted optimistically.
+- **`ProductManager` now extends `BaseDomainManager`** — exposes `subscribe`,
+  emits `domain:error`, and gains an `initialize()` no-op. `setAdapter` /
+  `getAdapter` / `setContext` / `getContext` keep the same signatures.
+- **`InitializableDomainName`** now includes `"product"` for parity with
+  the other domains.
+
+New additions:
+
+- `suite.ready: Promise<void>` — resolves when the most recent (auto or
+  manual) `initialize()` settles.
+- `suite.switchIdentity(context)` — atomic identity switch (merge context,
+  reset domains, re-initialize). Returns a promise.
+- `suite.destroy()` — unsubscribes all internal pubsub listeners.
+- `ECSuiteConfig.autoResetOnIdentityChange` (default `true`) — opt out of
+  the auto-reset path on `setContext()` if you manage identity transitions
+  yourself.
+- `OrderManager.getOrderById(modelId)` / `getOrderDataById(modelId)` lookup
+  helpers.
+- Per-domain mutation queue (`withOptimisticUpdate` is serialized per
+  manager) — concurrent `cart.addItem(...)` calls no longer race their
+  rollback snapshots.
+- Cache stampede dedup in `ProductManager.getById` — concurrent callers
+  for the same id share a single in-flight request.
+- Mock adapters now dispatch `forceError.code` (any name from `HTTP_ERROR`)
+  so tests can simulate `NotFound`, `Conflict`, etc., not just `BadRequest`.
+
 ## License
 
 MIT

package/dist/adapters/http/_http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module adapters/http/_http
+ *
+ * Shared primitives for the built-in HTTP adapters.
+ *
+ * Adapters throw raw HTTP errors (`Error` with `.status` and `.body`
+ * attached). `BaseDomainManager` catches and normalizes them to
+ * `DomainError` at the call site — adapters don't normalize themselves.
+ */
+import type { DomainContext } from "../../types/state.js";
+/** Options shared by every built-in HTTP adapter factory. */
+export interface HttpAdapterOptions {
+    /** Base URL of the mounted REST app. Each adapter has its own default. */
+    baseUrl?: string;
+    /** Override the `fetch` implementation (useful for tests / SSR). */
+    fetch?: typeof fetch;
+}
+export declare function resolveFetch(opts?: HttpAdapterOptions): typeof fetch;
+/** Trailing-slash-safe path joining. */
+export declare function join(base: string, path: string): string;
+export declare function authHeaders(ctx: DomainContext): HeadersInit;
+export declare function sessionHeader(ctx: DomainContext): HeadersInit;
+/**
+ * Wrap `fetch`, merge auth + session + content-type headers, and throw a raw
+ * HTTP error (with `.status` and `.body`) on non-OK. Returns `undefined` on
+ * 204 No Content, otherwise the parsed JSON body.
+ */
+export declare function requestJson<T>(doFetch: typeof fetch, url: string, init: RequestInit, ctx: DomainContext): Promise<T>;
+/** Require `ctx.sessionId`; throw a client-side Error if missing. */
+export declare function requireSessionId(ctx: DomainContext, operation: string): string;
+/** Require `ctx.jwt`; throw a client-side Error if missing. */
+export declare function requireJwt(ctx: DomainContext, operation: string): string;
+/** Require `ctx.customerId`; throw a client-side Error if missing. */
+export declare function requireCustomerId(ctx: DomainContext, operation: string): string;