@marianmeres/ecsuite 1.3.2 → 2.1.0

package/dist/adapters/mock/order.js

@@ -5,17 +5,19 @@ import { HTTP_ERROR } from "@marianmeres/http-utils";
 /** Create a mock order adapter for testing */
 export function createMockOrderAdapter(options = {}) {
     const delay = options.delay ?? 50;
-    let orders = options.initialData
+    const orders = options.initialData
         ? options.initialData.map((o, i) => ({
-            ...structuredClone(o),
             model_id: `order-${i + 1}`,
+            data: structuredClone(o),
         }))
         : [];
     let orderIdCounter = orders.length;
     const wait = () => new Promise((r) => setTimeout(r, delay));
     const maybeThrow = (operation) => {
         if (options.forceError?.operation === operation) {
-            throw new HTTP_ERROR.BadRequest(options.forceError.message ?? `Mock error for ${operation}`);
+            const code = options.forceError.code ?? "BadRequest";
+            const Ctor = HTTP_ERROR[code] ?? HTTP_ERROR.BadRequest;
+            throw new Ctor(options.forceError.message ?? `Mock error for ${operation}`);
         }
     };
     return {
@@ -41,8 +43,8 @@ export function createMockOrderAdapter(options = {}) {
                 ...structuredClone(orderData),
                 status: "pending",
             };
-            orders.push({ ...data, model_id });
-            return { model_id, data: structuredClone(data) };
+            orders.push({ model_id, data: structuredClone(data) });
+            return { model_id, data };
         },
     };
 }

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

@@ -2,6 +2,7 @@
  * Mock payment adapter for testing.
  */
 import type { PaymentData, UUID } from "@marianmeres/collection-types";
+import { HTTP_ERROR } from "@marianmeres/http-utils";
 import type { PaymentAdapter } from "../../types/adapter.js";
 /** Mock payment adapter options */
 export interface MockPaymentAdapterOptions {
@@ -12,7 +13,8 @@ export interface MockPaymentAdapterOptions {
     /** Force errors for testing */
     forceError?: {
         operation?: "fetchForOrder" | "fetchOne" | "initiate" | "capture";
-        code?: string;
+        /** HTTP error class name from `HTTP_ERROR` (default: "BadRequest") */
+        code?: keyof typeof HTTP_ERROR;
         message?: string;
     };
 }

package/dist/adapters/mock/payment.js

@@ -11,11 +11,19 @@ export function createMockPaymentAdapter(options = {}) {
     const wait = () => new Promise((r) => setTimeout(r, delay));
     const maybeThrow = (operation) => {
         if (options.forceError?.operation === operation) {
-            throw new HTTP_ERROR.BadRequest(options.forceError.message ??
-                `Mock error for ${operation}`);
+            const code = options.forceError.code ?? "BadRequest";
+            const Ctor = HTTP_ERROR[code] ?? HTTP_ERROR.BadRequest;
+            throw new Ctor(options.forceError.message ?? `Mock error for ${operation}`);
         }
     };
-    const getAllPayments = () => Object.values(payments).flat();
+    const findPaymentByRef = (ref) => {
+        for (const [orderId, list] of Object.entries(payments)) {
+            const payment = list.find((p) => p.provider_reference === ref);
+            if (payment)
+                return { payment, orderId: orderId };
+        }
+        return null;
+    };
     return {
         async fetchForOrder(orderId, _ctx) {
             await wait();
@@ -29,17 +37,26 @@ export function createMockPaymentAdapter(options = {}) {
         async fetchOne(paymentId, _ctx) {
             await wait();
             maybeThrow("fetchOne");
-            const allPayments = getAllPayments();
-            const payment = allPayments.find((p) => p.provider_reference === paymentId);
-            if (!payment) {
+            const found = findPaymentByRef(paymentId);
+            if (!found) {
                 throw new HTTP_ERROR.NotFound(`Payment ${paymentId} not found`);
             }
-            return structuredClone(payment);
+            return structuredClone(found.payment);
         },
         async initiate(orderId, config, _ctx) {
             await wait();
             maybeThrow("initiate");
             const id = `pi_${Math.random().toString(36).slice(2)}`;
+            // Persist the initiated (pending) payment so capture() can find it.
+            if (!payments[orderId])
+                payments[orderId] = [];
+            payments[orderId].push({
+                provider: config.provider,
+                status: "pending",
+                amount: config.amount,
+                currency: config.currency,
+                provider_reference: id,
+            });
             return {
                 id,
                 redirect_url: `https://mock-payment.test/pay/${id}`,
@@ -52,19 +69,16 @@ export function createMockPaymentAdapter(options = {}) {
         async capture(paymentId, _ctx) {
             await wait();
             maybeThrow("capture");
-            const payment = {
-                provider: "mock",
-                status: "completed",
-                amount: 0,
-                currency: "EUR",
-                provider_reference: paymentId,
-            };
-            // Store captured payment
-            const key = Object.keys(payments)[0] ?? "mock-order";
-            if (!payments[key])
-                payments[key] = [];
-            payments[key].push(payment);
-            return structuredClone(payment);
+            // Look up the (pending) payment by reference and complete it.
+            // Preserves the original amount/currency/provider that initiate()
+            // recorded — bypassing this would force the test to assert against
+            // hardcoded zeros.
+            const found = findPaymentByRef(paymentId);
+            if (!found) {
+                throw new HTTP_ERROR.NotFound(`Payment ${paymentId} not found`);
+            }
+            found.payment.status = "completed";
+            return structuredClone(found.payment);
         },
     };
 }

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

@@ -2,6 +2,7 @@
  * Mock product adapter for testing.
  */
 import type { ProductData, UUID } from "@marianmeres/collection-types";
+import { HTTP_ERROR } from "@marianmeres/http-utils";
 import type { ProductAdapter } from "../../types/adapter.js";
 /** Product with model_id for internal storage */
 interface StoredProduct extends ProductData {
@@ -16,7 +17,8 @@ export interface MockProductAdapterOptions {
     /** Force errors for testing */
     forceError?: {
         operation?: "fetchOne" | "fetchMany";
-        code?: string;
+        /** HTTP error class name from `HTTP_ERROR` (default: "BadRequest") */
+        code?: keyof typeof HTTP_ERROR;
         message?: string;
     };
 }

package/dist/adapters/mock/product.js

@@ -15,7 +15,9 @@ export function createMockProductAdapter(options = {}) {
     const wait = () => new Promise((r) => setTimeout(r, delay));
     const maybeThrow = (operation) => {
         if (options.forceError?.operation === operation) {
-            throw new HTTP_ERROR.BadRequest(options.forceError.message ?? `Mock error for ${operation}`);
+            const code = options.forceError.code ?? "BadRequest";
+            const Ctor = HTTP_ERROR[code] ?? HTTP_ERROR.BadRequest;
+            throw new Ctor(options.forceError.message ?? `Mock error for ${operation}`);
         }
     };
     return {

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

@@ -1,6 +1,7 @@
 /**
  * Mock wishlist adapter for testing.
  */
+import { HTTP_ERROR } from "@marianmeres/http-utils";
 import type { WishlistAdapter } from "../../types/adapter.js";
 import type { WishlistData } from "../../types/state.js";
 /** Mock wishlist adapter options */
@@ -11,8 +12,9 @@ export interface MockWishlistAdapterOptions {
     delay?: number;
     /** Force errors for testing */
     forceError?: {
-        operation?: "fetch" | "addItem" | "removeItem" | "clear" | "sync";
-        code?: string;
+        operation?: "fetch" | "addItem" | "removeItem" | "clear";
+        /** HTTP error class name from `HTTP_ERROR` (default: "BadRequest") */
+        code?: keyof typeof HTTP_ERROR;
         message?: string;
     };
 }

package/dist/adapters/mock/wishlist.js

@@ -11,7 +11,9 @@ export function createMockWishlistAdapter(options = {}) {
     const wait = () => new Promise((r) => setTimeout(r, delay));
     const maybeThrow = (operation) => {
         if (options.forceError?.operation === operation) {
-            throw new HTTP_ERROR.BadRequest(options.forceError.message ?? `Mock error for ${operation}`);
+            const code = options.forceError.code ?? "BadRequest";
+            const Ctor = HTTP_ERROR[code] ?? HTTP_ERROR.BadRequest;
+            throw new Ctor(options.forceError.message ?? `Mock error for ${operation}`);
         }
     };
     return {
@@ -44,11 +46,5 @@ export function createMockWishlistAdapter(options = {}) {
             wishlist = { items: [] };
             return structuredClone(wishlist);
         },
-        async sync(newWishlist, _ctx) {
-            await wait();
-            maybeThrow("sync");
-            wishlist = structuredClone(newWishlist);
-            return structuredClone(wishlist);
-        },
     };
 }

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/domains/base.d.ts

@@ -36,6 +36,7 @@ export interface BaseDomainOptions {
  * @typeParam TAdapter - The adapter interface type for server communication
  */
 export declare abstract class BaseDomainManager<TData, TAdapter> {
+    #private;
     protected readonly store: StoreLike<DomainStateWrapper<TData>>;
     protected readonly pubsub: PubSub;
     protected readonly domainName: DomainName;
@@ -68,12 +69,18 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     /**
      * Execute an async operation with optimistic update pattern.
      *
-     * 1. Captures current state for potential rollback
-     * 2. Applies optimistic update immediately
-     * 3. Sets state to "syncing"
-     * 4. Awaits server sync
-     * 5. On success: marks synced, calls success callback
-     * 6. On error: rolls back to previous state, sets error state
+     * 1. Waits for any prior in-flight mutation on this domain to settle
+     *    (per-domain serialization — see `#mutationQueue`)
+     * 2. Captures current state for potential rollback
+     * 3. Applies optimistic update immediately
+     * 4. Sets state to "syncing"
+     * 5. Awaits server sync
+     * 6. On success: marks synced, calls success callback
+     * 7. On error: rolls back to previous state, sets error state
+     *
+     * Concurrent callers see a deterministic order (FIFO) and a correct
+     * `previousData` snapshot per operation. Failures do not poison the
+     * queue — subsequent operations continue.
      */
     protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError) => void): Promise<void>;
     /** Initialize the domain (fetch from server) */

package/dist/domains/base.js

@@ -27,6 +27,13 @@ export class BaseDomainManager {
     clog;
     adapter = null;
     context = {};
+    /**
+     * Serializes per-domain mutations so concurrent callers don't race on the
+     * `previousData` snapshot used for rollback. Each `withOptimisticUpdate`
+     * waits for the prior one to settle. Reads (`get()`, `subscribe`) are
+     * never blocked by the queue.
+     */
+    #mutationQueue = Promise.resolve();
     constructor(domainName, options = {}) {
         this.domainName = domainName;
         this.clog = createClog(`ecsuite:${domainName}`, { color: "auto" });
@@ -141,15 +148,28 @@ export class BaseDomainManager {
     /**
      * Execute an async operation with optimistic update pattern.
      *
-     * 1. Captures current state for potential rollback
-     * 2. Applies optimistic update immediately
-     * 3. Sets state to "syncing"
-     * 4. Awaits server sync
-     * 5. On success: marks synced, calls success callback
-     * 6. On error: rolls back to previous state, sets error state
+     * 1. Waits for any prior in-flight mutation on this domain to settle
+     *    (per-domain serialization — see `#mutationQueue`)
+     * 2. Captures current state for potential rollback
+     * 3. Applies optimistic update immediately
+     * 4. Sets state to "syncing"
+     * 5. Awaits server sync
+     * 6. On success: marks synced, calls success callback
+     * 7. On error: rolls back to previous state, sets error state
+     *
+     * Concurrent callers see a deterministic order (FIFO) and a correct
+     * `previousData` snapshot per operation. Failures do not poison the
+     * queue — subsequent operations continue.
      */
-    async withOptimisticUpdate(operation, optimisticUpdate, serverSync, onSuccess, onError) {
-        // Capture current state for rollback
+    withOptimisticUpdate(operation, optimisticUpdate, serverSync, onSuccess, onError) {
+        const next = this.#mutationQueue.then(() => this.#runOptimistic(operation, optimisticUpdate, serverSync, onSuccess, onError));
+        // Swallow rejection on the chain so a failing op doesn't poison
+        // downstream awaiters. The original `next` still rejects to its caller.
+        this.#mutationQueue = next.catch(() => { });
+        return next;
+    }
+    async #runOptimistic(operation, optimisticUpdate, serverSync, onSuccess, onError) {
+        // Capture current state for rollback (after prior queued ops settled)
         const previousData = this.store.get().data;
         // Apply optimistic update immediately
         optimisticUpdate();
@@ -160,10 +180,9 @@ export class BaseDomainManager {
             onSuccess?.(result);
         }
         catch (e) {
-            // Rollback on error
-            if (previousData !== null) {
-                this.setData(previousData, false);
-            }
+            // Always rollback to previousData (including null) so we never
+            // leave optimistic mutations stranded in an "error" state.
+            this.store.update((s) => ({ ...s, data: previousData }));
             const error = {
                 code: "SYNC_FAILED",
                 message: e instanceof Error ? e.message : "Unknown error",

package/dist/domains/cart.js

@@ -5,6 +5,21 @@
  * Manages shopping cart state with automatic server synchronization.
  */
 import { BaseDomainManager } from "./base.js";
+/**
+ * Reject NaN, Infinity, and non-integer quantities at the entry point so
+ * malformed UI input never reaches the optimistic store or the server.
+ */
+function assertValidQuantity(quantity, op, { allowZero = false } = {}) {
+    if (typeof quantity !== "number" || !Number.isFinite(quantity)) {
+        throw new TypeError(`Cart.${op}: quantity must be a finite number, got ${quantity}`);
+    }
+    if (!Number.isInteger(quantity)) {
+        throw new TypeError(`Cart.${op}: quantity must be an integer, got ${quantity}`);
+    }
+    if (quantity < 0 || (!allowZero && quantity === 0)) {
+        throw new RangeError(`Cart.${op}: quantity must be ${allowZero ? "non-negative" : "positive"}, got ${quantity}`);
+    }
+}
 /**
  * Cart domain manager with optimistic updates and localStorage persistence.
  *
@@ -81,6 +96,7 @@ export class CartManager extends BaseDomainManager {
             productId: item.product_id,
             quantity: item.quantity,
         });
+        assertValidQuantity(item.quantity, "addItem");
         await this.withOptimisticUpdate("addItem", () => {
             // Optimistic: update local state immediately
             const current = this.store.get().data ?? { items: [] };
@@ -129,6 +145,7 @@ export class CartManager extends BaseDomainManager {
      */
     async updateItemQuantity(productId, quantity) {
         this.clog.debug("updateItemQuantity", { productId, quantity });
+        assertValidQuantity(quantity, "updateItemQuantity", { allowZero: true });
         if (quantity <= 0) {
             return this.removeItem(productId);
         }

package/dist/domains/customer.js

@@ -51,9 +51,13 @@ export class CustomerManager extends BaseDomainManager {
                 data = await this.adapter.fetchBySession(this.context);
             }
             else {
-                // No customerId and no fetchBySession — call fetch()
-                // for backward compatibility
-                data = await this.adapter.fetch(this.context);
+                // No customerId and no fetchBySession — there is nothing safe
+                // to fetch. Mark ready with no data and warn so config bugs
+                // don't manifest as adapter-rejection noise.
+                this.clog.warn("customer fetch skipped: no customerId in context and " +
+                    "adapter has no fetchBySession()");
+                this.setState("ready");
+                return false;
             }
             if (data) {
                 this.setData(data);
@@ -115,10 +119,20 @@ export class CustomerManager extends BaseDomainManager {
     async update(data) {
         this.clog.debug("update");
         if (!this.adapter) {
-            return;
+            const error = {
+                code: "NOT_IMPLEMENTED",
+                message: "CustomerAdapter is not configured",
+                operation: "update",
+            };
+            this.setError(error);
+            throw new Error(error.message);
         }
         const current = this.store.get().data;
         if (!current) {
+            // No data loaded yet — refuse to optimistically merge into nothing.
+            // Treat as a recoverable warning rather than a hard error so the
+            // caller can `await refresh()` first and retry.
+            this.clog.warn("update called before customer data was loaded — no-op");
             return;
         }
         await this.withOptimisticUpdate("update", () => {

package/dist/domains/order.d.ts

@@ -7,9 +7,13 @@
 import type { OrderData, UUID } from "@marianmeres/collection-types";
 import type { OrderAdapter, OrderCreatePayload, OrderCreateResult } from "../types/adapter.js";
 import { BaseDomainManager, type BaseDomainOptions } from "./base.js";
-/** Order list data (array of orders) */
+/**
+ * Order list data — array of `{ model_id, data }` envelopes so each order is
+ * uniquely identifiable by its server-assigned `model_id`. (Bare `OrderData`
+ * has no id field, only an open index signature.)
+ */
 export interface OrderListData {
-    orders: OrderData[];
+    orders: OrderCreateResult[];
 }
 export interface OrderManagerOptions extends BaseDomainOptions {
     /** Order adapter for server communication */
@@ -22,15 +26,15 @@ export interface OrderManagerOptions extends BaseDomainOptions {
  * - Server-side data source (no local persistence)
  * - Fetch all orders or individual orders
  * - Create new orders
- * - Order list management
+ * - Order list management keyed by `model_id`
  *
  * @example
  * ```typescript
  * const orders = new OrderManager({ adapter: myOrderAdapter });
  * await orders.initialize();
  *
- * const newOrder = await orders.create({ items: [...], total: 100 });
- * console.log(orders.getOrderCount());
+ * const result = await orders.create({ items: [...], total: 100 });
+ * console.log(result.model_id, result.data);
  * ```
  */
 export declare class OrderManager extends BaseDomainManager<OrderListData, OrderAdapter> {
@@ -46,18 +50,18 @@ export declare class OrderManager extends BaseDomainManager<OrderListData, Order
     fetchAll(): Promise<void>;
     /**
      * Fetch a single order by ID from the server.
-     * Updates or adds the order to the local list.
+     * Updates or adds the order to the local list, keyed by `model_id`.
      *
      * @param orderId - The order ID to fetch
-     * @returns The fetched order or null on error
+     * @returns The fetched order envelope or null on error
      */
-    fetchOne(orderId: UUID): Promise<OrderData | null>;
+    fetchOne(orderId: UUID): Promise<OrderCreateResult | null>;
     /**
      * Create a new order.
      * The order status is assigned by the server.
      *
      * @param orderData - The order data (without status)
-     * @returns The created order result (with model_id) or null on error
+     * @returns The created order envelope (with model_id) or null on error
      * @emits order:created - On successful creation
      */
     create(orderData: OrderCreatePayload): Promise<OrderCreateResult | null>;
@@ -68,16 +72,30 @@ export declare class OrderManager extends BaseDomainManager<OrderListData, Order
      */
     getOrderCount(): number;
     /**
-     * Get all orders.
+     * Get all order envelopes (`{ model_id, data }`).
+     *
+     * @returns Array of order envelopes
+     */
+    getOrders(): OrderCreateResult[];
+    /**
+     * Get an order envelope by its `model_id`.
+     *
+     * @param modelId - The order's server-assigned model id
+     * @returns The order envelope or undefined if not found
+     */
+    getOrderById(modelId: UUID): OrderCreateResult | undefined;
+    /**
+     * Get the bare `OrderData` for an order by its `model_id`.
      *
-     * @returns Array of orders
+     * @param modelId - The order's server-assigned model id
+     * @returns The order data or undefined if not found
      */
-    getOrders(): OrderData[];
+    getOrderDataById(modelId: UUID): OrderData | undefined;
     /**
-     * Get an order by its index in the list.
+     * Get an order envelope by its index in the list.
      *
      * @param index - The index in the orders array
-     * @returns The order or undefined if index is out of bounds
+     * @returns The order envelope or undefined if index is out of bounds
      */
-    getOrderByIndex(index: number): OrderData | undefined;
+    getOrderByIndex(index: number): OrderCreateResult | undefined;
 }

package/dist/domains/order.js

@@ -13,15 +13,15 @@ import { BaseDomainManager } from "./base.js";
  * - Server-side data source (no local persistence)
  * - Fetch all orders or individual orders
  * - Create new orders
- * - Order list management
+ * - Order list management keyed by `model_id`
  *
  * @example
  * ```typescript
  * const orders = new OrderManager({ adapter: myOrderAdapter });
  * await orders.initialize();
  *
- * const newOrder = await orders.create({ items: [...], total: 100 });
- * console.log(orders.getOrderCount());
+ * const result = await orders.create({ items: [...], total: 100 });
+ * console.log(result.model_id, result.data);
  * ```
  */
 export class OrderManager extends BaseDomainManager {
@@ -94,10 +94,10 @@ export class OrderManager extends BaseDomainManager {
     }
     /**
      * Fetch a single order by ID from the server.
-     * Updates or adds the order to the local list.
+     * Updates or adds the order to the local list, keyed by `model_id`.
      *
      * @param orderId - The order ID to fetch
-     * @returns The fetched order or null on error
+     * @returns The fetched order envelope or null on error
      */
     async fetchOne(orderId) {
         this.clog.debug("fetchOne", { orderId });
@@ -106,23 +106,20 @@ export class OrderManager extends BaseDomainManager {
         }
         this.setState("syncing");
         try {
-            const data = await this.adapter.fetchOne(orderId, this.context);
-            // Update the order in our local list
-            // TODO: fetchAll/fetchOne return OrderData which lacks model_id;
-            // matching by model_id relies on the index signature on OrderData
+            const result = await this.adapter.fetchOne(orderId, this.context);
             const current = this.store.get().data ?? { orders: [] };
-            const existingIndex = current.orders.findIndex((o) => o.model_id === orderId);
+            const existingIndex = current.orders.findIndex((o) => o.model_id === result.model_id);
             let orders;
             if (existingIndex >= 0) {
                 orders = [...current.orders];
-                orders[existingIndex] = data;
+                orders[existingIndex] = result;
             }
             else {
-                orders = [...current.orders, data];
+                orders = [...current.orders, result];
             }
             this.setData({ orders });
             this.markSynced();
-            return data;
+            return result;
         }
         catch (e) {
             const isNotFound = e instanceof HTTP_ERROR.NotFound;
@@ -140,7 +137,7 @@ export class OrderManager extends BaseDomainManager {
      * The order status is assigned by the server.
      *
      * @param orderData - The order data (without status)
-     * @returns The created order result (with model_id) or null on error
+     * @returns The created order envelope (with model_id) or null on error
      * @emits order:created - On successful creation
      */
     async create(orderData) {
@@ -151,10 +148,9 @@ export class OrderManager extends BaseDomainManager {
         this.setState("syncing");
         try {
             const result = await this.adapter.create(orderData, this.context);
-            // Add the new order to our local list
             const current = this.store.get().data ?? { orders: [] };
             this.setData({
-                orders: [...current.orders, result.data],
+                orders: [...current.orders, result],
             });
             this.markSynced();
             this.emit({
@@ -184,18 +180,36 @@ export class OrderManager extends BaseDomainManager {
         return this.store.get().data?.orders.length ?? 0;
     }
     /**
-     * Get all orders.
+     * Get all order envelopes (`{ model_id, data }`).
      *
-     * @returns Array of orders
+     * @returns Array of order envelopes
      */
     getOrders() {
         return this.store.get().data?.orders ?? [];
     }
     /**
-     * Get an order by its index in the list.
+     * Get an order envelope by its `model_id`.
+     *
+     * @param modelId - The order's server-assigned model id
+     * @returns The order envelope or undefined if not found
+     */
+    getOrderById(modelId) {
+        return this.store.get().data?.orders.find((o) => o.model_id === modelId);
+    }
+    /**
+     * Get the bare `OrderData` for an order by its `model_id`.
+     *
+     * @param modelId - The order's server-assigned model id
+     * @returns The order data or undefined if not found
+     */
+    getOrderDataById(modelId) {
+        return this.getOrderById(modelId)?.data;
+    }
+    /**
+     * Get an order envelope by its index in the list.
      *
      * @param index - The index in the orders array
-     * @returns The order or undefined if index is out of bounds
+     * @returns The order envelope or undefined if index is out of bounds
      */
     getOrderByIndex(index) {
         return this.store.get().data?.orders[index];