@marianmeres/ecsuite 2.0.0 → 2.2.1

package/AGENTS.md

@@ -58,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
@@ -74,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
 ```
 
@@ -143,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
 
 ```

package/README.md

@@ -144,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/mod`, `GET {baseUrl}/col/order/mod/:id`, `POST {baseUrl}/checkout/start`   |
+| customer | `GET/PUT {baseUrl}/me/col/customer/mod/:customerId`                                                 |
+| payment  | `GET {baseUrl}/by-order/:orderId`, `GET {baseUrl}/col/payment/mod/: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/mod/: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:

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;

package/dist/adapters/http/_http.js

@@ -0,0 +1,75 @@
+/**
+ * @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.
+ */
+export function resolveFetch(opts) {
+    return opts?.fetch ?? globalThis.fetch.bind(globalThis);
+}
+/** Trailing-slash-safe path joining. */
+export function join(base, path) {
+    if (!base)
+        return path;
+    if (base.endsWith("/"))
+        return `${base.slice(0, -1)}${path}`;
+    return `${base}${path}`;
+}
+export function authHeaders(ctx) {
+    return ctx.jwt ? { Authorization: `Bearer ${ctx.jwt}` } : {};
+}
+export function sessionHeader(ctx) {
+    return ctx.sessionId ? { "X-Session-ID": String(ctx.sessionId) } : {};
+}
+/**
+ * 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 async function requestJson(doFetch, url, init, ctx) {
+    const hasBody = init.body !== undefined && init.body !== null;
+    const res = await doFetch(url, {
+        ...init,
+        headers: {
+            ...(hasBody ? { "Content-Type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+            ...authHeaders(ctx),
+            ...sessionHeader(ctx),
+        },
+        signal: ctx.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw Object.assign(new Error(text || res.statusText), {
+            status: res.status,
+            body: text,
+        });
+    }
+    if (res.status === 204)
+        return undefined;
+    return (await res.json());
+}
+/** Require `ctx.sessionId`; throw a client-side Error if missing. */
+export function requireSessionId(ctx, operation) {
+    if (!ctx.sessionId) {
+        throw Object.assign(new Error(`sessionId required for ${operation}`), { status: 400, body: `sessionId required for ${operation}` });
+    }
+    return String(ctx.sessionId);
+}
+/** Require `ctx.jwt`; throw a client-side Error if missing. */
+export function requireJwt(ctx, operation) {
+    if (!ctx.jwt) {
+        throw Object.assign(new Error(`jwt required for ${operation}`), { status: 401, body: `jwt required for ${operation}` });
+    }
+    return ctx.jwt;
+}
+/** Require `ctx.customerId`; throw a client-side Error if missing. */
+export function requireCustomerId(ctx, operation) {
+    if (!ctx.customerId) {
+        throw Object.assign(new Error(`customerId required for ${operation}`), { status: 400, body: `customerId required for ${operation}` });
+    }
+    return String(ctx.customerId);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @module adapters/http/cart
+ *
+ * Built-in {@link CartAdapter} targeting a REST surface of the shape:
+ *
+ *   GET    {baseUrl}/cart                 → { data: CartData }
+ *   POST   {baseUrl}/cart                 → { data: CartData }   body: CartItem
+ *   PUT    {baseUrl}/cart                 → { data: CartData }   body: { product_id, quantity }
+ *   DELETE {baseUrl}/cart?product_id=...  → { data: CartData }   (remove single item)
+ *   DELETE {baseUrl}/cart                 → { data: CartData }   (clear)
+ *
+ * All mutations require `X-Session-ID` on the request. The adapter reads
+ * `ctx.sessionId` and throws a client-side error if missing so failures
+ * surface before the network round-trip.
+ */
+import type { CartAdapter } from "../../types/adapter.js";
+import { type HttpAdapterOptions } from "./_http.js";
+/** Options for {@link createHttpCartAdapter}. */
+export type HttpCartAdapterOptions = HttpAdapterOptions;
+/** Build a cart adapter against the conventional `/cart` REST surface. */
+export declare function createHttpCartAdapter(opts?: HttpCartAdapterOptions): CartAdapter;

package/dist/adapters/http/cart.js

@@ -0,0 +1,52 @@
+/**
+ * @module adapters/http/cart
+ *
+ * Built-in {@link CartAdapter} targeting a REST surface of the shape:
+ *
+ *   GET    {baseUrl}/cart                 → { data: CartData }
+ *   POST   {baseUrl}/cart                 → { data: CartData }   body: CartItem
+ *   PUT    {baseUrl}/cart                 → { data: CartData }   body: { product_id, quantity }
+ *   DELETE {baseUrl}/cart?product_id=...  → { data: CartData }   (remove single item)
+ *   DELETE {baseUrl}/cart                 → { data: CartData }   (clear)
+ *
+ * All mutations require `X-Session-ID` on the request. The adapter reads
+ * `ctx.sessionId` and throws a client-side error if missing so failures
+ * surface before the network round-trip.
+ */
+import { join, requestJson, requireSessionId, resolveFetch, } from "./_http.js";
+/** Build a cart adapter against the conventional `/cart` REST surface. */
+export function createHttpCartAdapter(opts = {}) {
+    const base = opts.baseUrl ?? "/api/session";
+    const doFetch = resolveFetch(opts);
+    const url = () => join(base, "/cart");
+    return {
+        async fetch(ctx) {
+            const r = await requestJson(doFetch, url(), { method: "GET" }, ctx);
+            return r.data;
+        },
+        async addItem(item, ctx) {
+            requireSessionId(ctx, "cart.addItem");
+            const r = await requestJson(doFetch, url(), { method: "POST", body: JSON.stringify(item) }, ctx);
+            return r.data;
+        },
+        async updateItem(productId, quantity, ctx) {
+            requireSessionId(ctx, "cart.updateItem");
+            const r = await requestJson(doFetch, url(), {
+                method: "PUT",
+                body: JSON.stringify({ product_id: productId, quantity }),
+            }, ctx);
+            return r.data;
+        },
+        async removeItem(productId, ctx) {
+            requireSessionId(ctx, "cart.removeItem");
+            const qs = new URLSearchParams({ product_id: String(productId) });
+            const r = await requestJson(doFetch, `${url()}?${qs}`, { method: "DELETE" }, ctx);
+            return r.data;
+        },
+        async clear(ctx) {
+            requireSessionId(ctx, "cart.clear");
+            const r = await requestJson(doFetch, url(), { method: "DELETE" }, ctx);
+            return r.data;
+        },
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @module adapters/http/customer
+ *
+ * Built-in {@link CustomerAdapter} targeting the owner-scoped customer
+ * REST surface:
+ *
+ *   GET {baseUrl}/me/col/customer/mod/:customerId  → { model_id, data: CustomerData }
+ *   PUT {baseUrl}/me/col/customer/mod/:customerId  → { model_id, data: CustomerData }
+ *
+ * Both calls require `Authorization: Bearer <jwt>` + a `customerId` on the
+ * context (typically resolved from the login subject claim).
+ *
+ * `fetchBySession` is intentionally not implemented — there is no clean
+ * session-scoped read endpoint on the target REST surface; consumers who
+ * need session-based bootstrapping should hydrate from the JWT instead.
+ */
+import type { CustomerAdapter } from "../../types/adapter.js";
+import { type HttpAdapterOptions } from "./_http.js";
+/** Options for {@link createHttpCustomerAdapter}. */
+export type HttpCustomerAdapterOptions = HttpAdapterOptions;
+/** Build a customer adapter against the conventional owner-scoped REST surface. */
+export declare function createHttpCustomerAdapter(opts?: HttpCustomerAdapterOptions): CustomerAdapter;

package/dist/adapters/http/customer.js

@@ -0,0 +1,35 @@
+/**
+ * @module adapters/http/customer
+ *
+ * Built-in {@link CustomerAdapter} targeting the owner-scoped customer
+ * REST surface:
+ *
+ *   GET {baseUrl}/me/col/customer/mod/:customerId  → { model_id, data: CustomerData }
+ *   PUT {baseUrl}/me/col/customer/mod/:customerId  → { model_id, data: CustomerData }
+ *
+ * Both calls require `Authorization: Bearer <jwt>` + a `customerId` on the
+ * context (typically resolved from the login subject claim).
+ *
+ * `fetchBySession` is intentionally not implemented — there is no clean
+ * session-scoped read endpoint on the target REST surface; consumers who
+ * need session-based bootstrapping should hydrate from the JWT instead.
+ */
+import { join, requestJson, requireCustomerId, resolveFetch, } from "./_http.js";
+/** Build a customer adapter against the conventional owner-scoped REST surface. */
+export function createHttpCustomerAdapter(opts = {}) {
+    const base = opts.baseUrl ?? "/api/customer";
+    const doFetch = resolveFetch(opts);
+    const url = (customerId) => join(base, `/me/col/customer/mod/${encodeURIComponent(customerId)}`);
+    return {
+        async fetch(ctx) {
+            const customerId = requireCustomerId(ctx, "customer.fetch");
+            const r = await requestJson(doFetch, url(customerId), { method: "GET" }, ctx);
+            return r.data;
+        },
+        async update(data, ctx) {
+            const customerId = requireCustomerId(ctx, "customer.update");
+            const r = await requestJson(doFetch, url(customerId), { method: "PUT", body: JSON.stringify(data) }, ctx);
+            return r.data;
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @module adapters/http
+ *
+ * Built-in HTTP adapters targeting a conventional REST surface.
+ *
+ * Each factory takes `{ baseUrl?, fetch? }` and returns an adapter that
+ * conforms to the matching interface from `../../types/adapter.ts`.
+ * Adapters throw raw HTTP errors (`Error` with `.status` + `.body`);
+ * domain managers normalize them to `DomainError`.
+ *
+ * Authentication is carried on the context passed to each call:
+ *   - `ctx.sessionId` → emitted as `X-Session-ID`
+ *   - `ctx.jwt`       → emitted as `Authorization: Bearer <jwt>`
+ */
+export { type HttpAdapterOptions, } from "./_http.js";
+export { createHttpCartAdapter, type HttpCartAdapterOptions } from "./cart.js";
+export { createHttpWishlistAdapter, type HttpWishlistAdapterOptions, } from "./wishlist.js";
+export { createHttpOrderAdapter, type HttpOrderAdapterOptions } from "./order.js";
+export { createHttpCustomerAdapter, type HttpCustomerAdapterOptions, } from "./customer.js";
+export { createHttpPaymentAdapter, type HttpPaymentAdapterOptions, } from "./payment.js";
+export { createHttpProductAdapter, type HttpProductAdapterOptions, } from "./product.js";

package/dist/adapters/http/mod.js

@@ -0,0 +1,20 @@
+/**
+ * @module adapters/http
+ *
+ * Built-in HTTP adapters targeting a conventional REST surface.
+ *
+ * Each factory takes `{ baseUrl?, fetch? }` and returns an adapter that
+ * conforms to the matching interface from `../../types/adapter.ts`.
+ * Adapters throw raw HTTP errors (`Error` with `.status` + `.body`);
+ * domain managers normalize them to `DomainError`.
+ *
+ * Authentication is carried on the context passed to each call:
+ *   - `ctx.sessionId` → emitted as `X-Session-ID`
+ *   - `ctx.jwt`       → emitted as `Authorization: Bearer <jwt>`
+ */
+export { createHttpCartAdapter } from "./cart.js";
+export { createHttpWishlistAdapter, } from "./wishlist.js";
+export { createHttpOrderAdapter } from "./order.js";
+export { createHttpCustomerAdapter, } from "./customer.js";
+export { createHttpPaymentAdapter, } from "./payment.js";
+export { createHttpProductAdapter, } from "./product.js";

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

@@ -0,0 +1,24 @@
+/**
+ * @module adapters/http/order
+ *
+ * Built-in {@link OrderAdapter} targeting a REST surface of the shape:
+ *
+ *   GET  {baseUrl}/col/order/mod         → { data: [{ model_id, data }, ...] }
+ *   GET  {baseUrl}/col/order/mod/:id     → { model_id, data: OrderData }
+ *   POST {baseUrl}/checkout/start    → { order_id, order: OrderData, ... }
+ *
+ * `create()` only starts checkout — it calls `POST /checkout/start` and
+ * returns the freshly-created pending order. The multi-step completion
+ * flow (addresses → delivery → payment → complete) is not wrapped by this
+ * adapter; callers drive it via their own HTTP calls until ecsuite grows
+ * dedicated verbs.
+ *
+ * Read endpoints require `Authorization: Bearer <jwt>`; checkout/start
+ * additionally requires `X-Session-ID`.
+ */
+import type { OrderAdapter } from "../../types/adapter.js";
+import { type HttpAdapterOptions } from "./_http.js";
+/** Options for {@link createHttpOrderAdapter}. */
+export type HttpOrderAdapterOptions = HttpAdapterOptions;
+/** Build an order adapter against the conventional `/api/order` REST surface. */
+export declare function createHttpOrderAdapter(opts?: HttpOrderAdapterOptions): OrderAdapter;

package/dist/adapters/http/order.js

@@ -0,0 +1,43 @@
+/**
+ * @module adapters/http/order
+ *
+ * Built-in {@link OrderAdapter} targeting a REST surface of the shape:
+ *
+ *   GET  {baseUrl}/col/order/mod         → { data: [{ model_id, data }, ...] }
+ *   GET  {baseUrl}/col/order/mod/:id     → { model_id, data: OrderData }
+ *   POST {baseUrl}/checkout/start    → { order_id, order: OrderData, ... }
+ *
+ * `create()` only starts checkout — it calls `POST /checkout/start` and
+ * returns the freshly-created pending order. The multi-step completion
+ * flow (addresses → delivery → payment → complete) is not wrapped by this
+ * adapter; callers drive it via their own HTTP calls until ecsuite grows
+ * dedicated verbs.
+ *
+ * Read endpoints require `Authorization: Bearer <jwt>`; checkout/start
+ * additionally requires `X-Session-ID`.
+ */
+import { join, requestJson, requireSessionId, resolveFetch, } from "./_http.js";
+/** Build an order adapter against the conventional `/api/order` REST surface. */
+export function createHttpOrderAdapter(opts = {}) {
+    const base = opts.baseUrl ?? "/api/order";
+    const doFetch = resolveFetch(opts);
+    return {
+        async fetchAll(ctx) {
+            const r = await requestJson(doFetch, join(base, "/col/order/mod"), { method: "GET" }, ctx);
+            return r.data ?? [];
+        },
+        async fetchOne(orderId, ctx) {
+            return await requestJson(doFetch, join(base, `/col/order/mod/${encodeURIComponent(String(orderId))}`), { method: "GET" }, ctx);
+        },
+        async create(order, ctx) {
+            requireSessionId(ctx, "order.create");
+            const body = {
+                email: order.customer_email,
+            };
+            if (ctx.customerId)
+                body.customer_id = ctx.customerId;
+            const r = await requestJson(doFetch, join(base, "/checkout/start"), { method: "POST", body: JSON.stringify(body) }, ctx);
+            return { model_id: r.order_id, data: r.order };
+        },
+    };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @module adapters/http/payment
+ *
+ * Built-in {@link PaymentAdapter} targeting a REST surface of the shape:
+ *
+ *   GET  {baseUrl}/by-order/:orderId    → { data: [{ model_id, data: PaymentData }, ...] }
+ *   GET  {baseUrl}/col/payment/mod/:id  → { model_id, data: PaymentData }
+ *   POST {baseUrl}/initiate             → { payment_id, redirect_url }
+ *
+ * All calls require `X-Session-ID`; read endpoints additionally take a JWT
+ * if present.
+ *
+ * `initiate` targets a domain-scoped entry point that shares a service seam
+ * with the order-checkout payment step. The server derives `amount` and
+ * `currency` from the order record (not from the client) and only accepts
+ * an initiation once the order has passed checkout validation (addresses +
+ * delivery set). Callers must supply `provider`, `return_url`, and
+ * `cancel_url` through `PaymentInitConfig` — `return_url` is typed on the
+ * canonical config; `cancel_url` is read off the open index signature.
+ *
+ * `capture()` is intentionally not wired — the target REST surface does not
+ * expose a client-facing capture endpoint (capture is driven server-side by
+ * provider webhooks + the checkout/complete flow). The returned adapter
+ * omits `capture`, so `PaymentManager.capture()` surfaces a NOT_IMPLEMENTED
+ * error as designed.
+ */
+import type { PaymentAdapter } from "../../types/adapter.js";
+import { type HttpAdapterOptions } from "./_http.js";
+/** Options for {@link createHttpPaymentAdapter}. */
+export type HttpPaymentAdapterOptions = HttpAdapterOptions;
+/** Build a payment adapter against the conventional `/api/payment` REST surface. */
+export declare function createHttpPaymentAdapter(opts?: HttpPaymentAdapterOptions): PaymentAdapter;

package/dist/adapters/http/payment.js

@@ -0,0 +1,77 @@
+/**
+ * @module adapters/http/payment
+ *
+ * Built-in {@link PaymentAdapter} targeting a REST surface of the shape:
+ *
+ *   GET  {baseUrl}/by-order/:orderId    → { data: [{ model_id, data: PaymentData }, ...] }
+ *   GET  {baseUrl}/col/payment/mod/:id  → { model_id, data: PaymentData }
+ *   POST {baseUrl}/initiate             → { payment_id, redirect_url }
+ *
+ * All calls require `X-Session-ID`; read endpoints additionally take a JWT
+ * if present.
+ *
+ * `initiate` targets a domain-scoped entry point that shares a service seam
+ * with the order-checkout payment step. The server derives `amount` and
+ * `currency` from the order record (not from the client) and only accepts
+ * an initiation once the order has passed checkout validation (addresses +
+ * delivery set). Callers must supply `provider`, `return_url`, and
+ * `cancel_url` through `PaymentInitConfig` — `return_url` is typed on the
+ * canonical config; `cancel_url` is read off the open index signature.
+ *
+ * `capture()` is intentionally not wired — the target REST surface does not
+ * expose a client-facing capture endpoint (capture is driven server-side by
+ * provider webhooks + the checkout/complete flow). The returned adapter
+ * omits `capture`, so `PaymentManager.capture()` surfaces a NOT_IMPLEMENTED
+ * error as designed.
+ */
+import { join, requestJson, requireSessionId, resolveFetch, } from "./_http.js";
+function unwrapPayment(envelope) {
+    const e = envelope;
+    if (e && typeof e === "object" && e.data && "provider" in e.data) {
+        return e.data;
+    }
+    return envelope;
+}
+/** Build a payment adapter against the conventional `/api/payment` REST surface. */
+export function createHttpPaymentAdapter(opts = {}) {
+    const base = opts.baseUrl ?? "/api/payment";
+    const doFetch = resolveFetch(opts);
+    return {
+        async fetchForOrder(orderId, ctx) {
+            requireSessionId(ctx, "payment.fetchForOrder");
+            const r = await requestJson(doFetch, join(base, `/by-order/${encodeURIComponent(String(orderId))}`), { method: "GET" }, ctx);
+            return (r.data ?? []).map(unwrapPayment);
+        },
+        async fetchOne(paymentId, ctx) {
+            const r = await requestJson(doFetch, join(base, `/col/payment/mod/${encodeURIComponent(String(paymentId))}`), { method: "GET" }, ctx);
+            return unwrapPayment(r);
+        },
+        async initiate(orderId, config, ctx) {
+            requireSessionId(ctx, "payment.initiate");
+            const returnUrl = config.return_url;
+            const cancelUrl = config.cancel_url;
+            if (typeof returnUrl !== "string" || !returnUrl) {
+                throw Object.assign(new Error("return_url required for payment.initiate"), {
+                    status: 400,
+                    body: "return_url required for payment.initiate",
+                });
+            }
+            if (typeof cancelUrl !== "string" || !cancelUrl) {
+                throw Object.assign(new Error("cancel_url required for payment.initiate"), {
+                    status: 400,
+                    body: "cancel_url required for payment.initiate",
+                });
+            }
+            const r = await requestJson(doFetch, join(base, "/initiate"), {
+                method: "POST",
+                body: JSON.stringify({
+                    order_id: orderId,
+                    provider: config.provider,
+                    return_url: returnUrl,
+                    cancel_url: cancelUrl,
+                }),
+            }, ctx);
+            return { id: r.payment_id, redirect_url: r.redirect_url };
+        },
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @module adapters/http/product
+ *
+ * Built-in {@link ProductAdapter} targeting a generic collection REST surface:
+ *
+ *   GET {baseUrl}/col/product/mod/:id → { model_id, data: ProductData, ... }
+ *
+ * The `{ model_id, data }` model envelope is unwrapped; the adapter returns
+ * bare `ProductData` / `ProductData[]` to conform to the interface.
+ *
+ * There is no batch endpoint — `fetchMany` issues parallel GETs.
+ */
+import type { ProductAdapter } from "../../types/adapter.js";
+import { type HttpAdapterOptions } from "./_http.js";
+/** Options for {@link createHttpProductAdapter}. */
+export type HttpProductAdapterOptions = HttpAdapterOptions;
+/** Build a product adapter against the conventional `/col/product/mod` REST surface. */
+export declare function createHttpProductAdapter(opts?: HttpProductAdapterOptions): ProductAdapter;

package/dist/adapters/http/product.js

@@ -0,0 +1,30 @@
+/**
+ * @module adapters/http/product
+ *
+ * Built-in {@link ProductAdapter} targeting a generic collection REST surface:
+ *
+ *   GET {baseUrl}/col/product/mod/:id → { model_id, data: ProductData, ... }
+ *
+ * The `{ model_id, data }` model envelope is unwrapped; the adapter returns
+ * bare `ProductData` / `ProductData[]` to conform to the interface.
+ *
+ * There is no batch endpoint — `fetchMany` issues parallel GETs.
+ */
+import { join, requestJson, resolveFetch, } from "./_http.js";
+/** Build a product adapter against the conventional `/col/product/mod` REST surface. */
+export function createHttpProductAdapter(opts = {}) {
+    const base = opts.baseUrl ?? "/api/product";
+    const doFetch = resolveFetch(opts);
+    async function fetchOne(productId, ctx) {
+        const r = await requestJson(doFetch, join(base, `/col/product/mod/${encodeURIComponent(String(productId))}`), { method: "GET" }, ctx);
+        return r.data;
+    }
+    return {
+        fetchOne,
+        async fetchMany(productIds, ctx) {
+            if (productIds.length === 0)
+                return [];
+            return Promise.all(productIds.map((id) => fetchOne(id, ctx)));
+        },
+    };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * @module adapters/http/wishlist
+ *
+ * Built-in {@link WishlistAdapter} targeting a REST surface of the shape:
+ *
+ *   GET    {baseUrl}/wishlist                 → { data: WishlistData }
+ *   POST   {baseUrl}/wishlist                 → { data: WishlistData, added?: boolean }
+ *   DELETE {baseUrl}/wishlist?product_id=...  → { data: WishlistData }
+ *   DELETE {baseUrl}/wishlist                 → { data: WishlistData } (clear)
+ *
+ * Mutations require `X-Session-ID`. Add/toggle is idempotent on the server
+ * side — adding a product already present is a no-op for the wishlist state.
+ */
+import type { WishlistAdapter } from "../../types/adapter.js";
+import { type HttpAdapterOptions } from "./_http.js";
+/** Options for {@link createHttpWishlistAdapter}. */
+export type HttpWishlistAdapterOptions = HttpAdapterOptions;
+/** Build a wishlist adapter against the conventional `/wishlist` REST surface. */
+export declare function createHttpWishlistAdapter(opts?: HttpWishlistAdapterOptions): WishlistAdapter;

package/dist/adapters/http/wishlist.js

@@ -0,0 +1,42 @@
+/**
+ * @module adapters/http/wishlist
+ *
+ * Built-in {@link WishlistAdapter} targeting a REST surface of the shape:
+ *
+ *   GET    {baseUrl}/wishlist                 → { data: WishlistData }
+ *   POST   {baseUrl}/wishlist                 → { data: WishlistData, added?: boolean }
+ *   DELETE {baseUrl}/wishlist?product_id=...  → { data: WishlistData }
+ *   DELETE {baseUrl}/wishlist                 → { data: WishlistData } (clear)
+ *
+ * Mutations require `X-Session-ID`. Add/toggle is idempotent on the server
+ * side — adding a product already present is a no-op for the wishlist state.
+ */
+import { join, requestJson, requireSessionId, resolveFetch, } from "./_http.js";
+/** Build a wishlist adapter against the conventional `/wishlist` REST surface. */
+export function createHttpWishlistAdapter(opts = {}) {
+    const base = opts.baseUrl ?? "/api/session";
+    const doFetch = resolveFetch(opts);
+    const url = () => join(base, "/wishlist");
+    return {
+        async fetch(ctx) {
+            const r = await requestJson(doFetch, url(), { method: "GET" }, ctx);
+            return r.data;
+        },
+        async addItem(productId, ctx) {
+            requireSessionId(ctx, "wishlist.addItem");
+            const r = await requestJson(doFetch, url(), { method: "POST", body: JSON.stringify({ product_id: productId }) }, ctx);
+            return r.data;
+        },
+        async removeItem(productId, ctx) {
+            requireSessionId(ctx, "wishlist.removeItem");
+            const qs = new URLSearchParams({ product_id: String(productId) });
+            const r = await requestJson(doFetch, `${url()}?${qs}`, { method: "DELETE" }, ctx);
+            return r.data;
+        },
+        async clear(ctx) {
+            requireSessionId(ctx, "wishlist.clear");
+            const r = await requestJson(doFetch, url(), { method: "DELETE" }, ctx);
+            return r.data;
+        },
+    };
+}

package/dist/adapters/mod.d.ts

@@ -1,6 +1,9 @@
 /**
  * @module adapters
  *
- * Adapter exports including mock adapters for testing.
+ * Adapter exports. Includes:
+ *   - Mock adapters for testing (see `./mock/`)
+ *   - Built-in HTTP adapters for the conventional REST surface (see `./http/`)
  */
 export * from "./mock/mod.js";
+export * from "./http/mod.js";

package/dist/adapters/mod.js

@@ -1,6 +1,9 @@
 /**
  * @module adapters
  *
- * Adapter exports including mock adapters for testing.
+ * Adapter exports. Includes:
+ *   - Mock adapters for testing (see `./mock/`)
+ *   - Built-in HTTP adapters for the conventional REST surface (see `./http/`)
  */
 export * from "./mock/mod.js";
+export * from "./http/mod.js";

package/dist/types/state.d.ts

@@ -35,6 +35,8 @@ export interface DomainContext {
     customerId?: UUID;
     /** Optional session ID */
     sessionId?: UUID;
+    /** Optional JWT forwarded to HTTP adapters as `Authorization: Bearer <jwt>`. */
+    jwt?: string;
     /** Additional context properties for adapter-specific needs */
     [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ecsuite",
-	"version": "2.0.0",
+	"version": "2.2.1",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",