@comity/order 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @comity/order
+
+Order domain contracts for Comity commerce modules.
+
+---
+
+## Purpose
+
+Defines order contracts and models consumed by commerce and storefront modules. Unifies cart and order into a single domain where a cart is an order in draft status. Provides repositories, item models, and structured errors without binding to a specific commerce backend.
+
+---
+
+## Scope
+
+This package:
+
+- ✅ defines the order entity with lifecycle and item mutations
+- ✅ defines order, item, and product contracts with status lifecycle
+- ✅ defines order repository contracts
+- ✅ exposes the `error` subpath for order-specific error types
+
+This package does NOT:
+
+- ❌ implement checkout orchestration or payment processing
+- ❌ manage inventory or pricing logic
+- ❌ validate coupons or apply promotion rules
+- ❌ render order UI
+
+---
+
+## Public API
+
+- `Order` — order entity with lifecycle and item mutations (`addItem`, `removeItem`, `updateItemQuantity`, `submit`, `confirm`, `fulfill`, `cancel`)
+- `OrderId` — order identifier value object
+- `OrderRepository` — persistence-boundary contract (`getById`, `search`, `save`)
+- `OrderState`, `OrderCreate`, `OrderUpdate`, `OrderSnapshot`, `OrderData`, `OrderStatus` — domain contracts
+- `OrderItem`, `OrderProductSnapshot` (with `OrderVariantSnapshot`, `OrderProductAttribute`, `OrderProductOption`) — embedded item value structures
+- Error types (`@comity/order/errors`)
+
+The product data in an order is an **owned, immutable snapshot**
+(`OrderProductSnapshot`): it is self-contained and never references the
+catalog after order creation. The application/checkout maps
+`ProductProjection` into the snapshot at creation time.
+
+Price composition is owned by `@comity/pricing`: orders store the immutable
+`Price` value (line item and order level) and do not store modifiers
+separately — modifiers are accessed only through `price.modifiers`.
+
+No exhaustive reference; see docs for constraints.
+
+---
+
+## Documentation
+
+- docs/overview.md
+- docs/conventions.md
+
+---
+
+## Related Packages
+
+- @comity/pricing — price and money models (`order → pricing`, registered in ADR-008)
+- @comity/catalog — source of `ProductProjection`, mapped by the application into owned `OrderProductSnapshot` (no direct dependency)
+- @comity/kernel — module lifecycle runtime
+
+---
+
+## Status
+
+Stable
+
+_Review Completed: 2026-08-01_
+_Compliance Score: N/A% (Green)_

package/dist/cjs/contracts/address-snapshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=address-snapshot.js.map

package/dist/cjs/contracts/contact.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=contact.js.map

package/dist/cjs/contracts/customer-snapshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=customer-snapshot.js.map

package/dist/cjs/contracts/item.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=item.js.map

package/dist/cjs/contracts/order-repository.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=order-repository.js.map

package/dist/cjs/contracts/order.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=order.js.map

package/dist/cjs/contracts/payment-snapshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=payment-snapshot.js.map

package/dist/cjs/domain/order-transitions.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canTransition = canTransition;
+exports.transitionOrderStatus = transitionOrderStatus;
+const result_1 = require("@comity/primitives/result");
+const order_js_1 = require("../errors/order.js");
+/**
+ * Legal transitions for each order status.
+ *
+ * - `draft` → `pending` (submit)
+ * - `pending` → `confirmed` (confirm)
+ * - `confirmed` → `fulfilled` (fulfill)
+ * - `draft | pending | confirmed` → `cancelled` (cancel)
+ *
+ * `fulfilled` and `cancelled` are terminal: no transition is legal from them.
+ */
+const TRANSITIONS = {
+    draft: ["pending", "cancelled"],
+    pending: ["confirmed", "cancelled"],
+    confirmed: ["fulfilled", "cancelled"],
+    fulfilled: [],
+    cancelled: [],
+};
+/**
+ * Checks whether a status transition is legal.
+ *
+ * @param from - Source status.
+ * @param to - Target status.
+ *
+ * @returns True if the transition is allowed, false otherwise.
+ */
+function canTransition(from, to) {
+    return TRANSITIONS[from].includes(to);
+}
+/**
+ * Applies a status transition.
+ *
+ * @param from - Source status.
+ * @param to - Target status.
+ *
+ * @returns The target status, or an `invalid_status_transition` error when the
+ * transition is not allowed.
+ */
+function transitionOrderStatus(from, to) {
+    if (!canTransition(from, to)) {
+        return (0, result_1.failure)(new order_js_1.OrderError("invalid_status_transition", {
+            details: { from, to },
+        }));
+    }
+    return (0, result_1.success)(to);
+}
+//# sourceMappingURL=order-transitions.js.map

package/dist/cjs/entities/order.js

@@ -0,0 +1,459 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Order = void 0;
+const result_1 = require("@comity/primitives/result");
+const time_1 = require("@comity/primitives/time");
+const order_transitions_js_1 = require("../domain/order-transitions.js");
+const order_js_1 = require("../errors/order.js");
+/**
+ * Returns a defensive copy of a product snapshot so later mutations of the
+ * input cannot leak into the order.
+ *
+ * @param snapshot - The product snapshot to copy.
+ *
+ * @returns A defensive copy of the snapshot.
+ */
+function copyProductSnapshot(snapshot) {
+    /**
+     * Returns a defensive copy of a variant snapshot.
+     *
+     * @param variant - The variant snapshot to copy.
+     *
+     * @returns A defensive copy of the variant.
+     */
+    const copyVariant = (variant) => ({
+        ...variant,
+        ...(variant.attributes !== undefined
+            ? { attributes: variant.attributes.map((attribute) => ({ ...attribute })) }
+            : {}),
+        ...(variant.options !== undefined
+            ? { options: variant.options.map((option) => ({ ...option })) }
+            : {}),
+    });
+    return {
+        ...snapshot,
+        ...(snapshot.attributes !== undefined
+            ? { attributes: snapshot.attributes.map((attribute) => ({ ...attribute })) }
+            : {}),
+        ...(snapshot.options !== undefined
+            ? { options: snapshot.options.map((option) => ({ ...option })) }
+            : {}),
+        ...(snapshot.variant !== undefined ? { variant: copyVariant(snapshot.variant) } : {}),
+        ...(snapshot.metadata !== undefined ? { metadata: { ...snapshot.metadata } } : {}),
+    };
+}
+/**
+ * Returns a defensive copy of a contact so later mutations of the input cannot
+ * leak into the order.
+ *
+ * @param contact - The contact to copy.
+ *
+ * @returns A defensive copy of the contact.
+ */
+function copyContact(contact) {
+    return { ...contact };
+}
+/**
+ * Returns a defensive copy of the buyer fact so later mutations of the input
+ * cannot leak into the order.
+ *
+ * @param customer - The customer fact to copy.
+ *
+ * @returns A defensive copy of the customer fact.
+ */
+function copyCustomerSnapshot(customer) {
+    return {
+        ...customer,
+        ...(customer.contacts !== undefined
+            ? { contacts: customer.contacts.map((contact) => copyContact(contact)) }
+            : {}),
+    };
+}
+/**
+ * Returns a defensive copy of an address fact so later mutations of the input
+ * cannot leak into the order.
+ *
+ * @param address - The address fact to copy.
+ *
+ * @returns A defensive copy of the address fact.
+ */
+function copyAddressSnapshot(address) {
+    return {
+        ...address,
+        lines: [...address.lines],
+    };
+}
+/**
+ * Returns whether a stored address fact and a replacement destination are
+ * structurally identical.
+ *
+ * @param address - The address fact stored on the order.
+ * @param destination - The replacement destination to compare against.
+ *
+ * @returns `true` when every field matches, otherwise `false`.
+ */
+function isSameShippingDestination(address, destination) {
+    return (address.addressId === destination.addressId &&
+        address.lines.length === destination.lines.length &&
+        address.lines.every((line, index) => line === destination.lines[index]) &&
+        address.city === destination.city &&
+        address.administrativeArea === destination.administrativeArea &&
+        address.postalCode === destination.postalCode &&
+        address.countryCode === destination.countryCode &&
+        address.capturedAt.epochMilliseconds === destination.capturedAt.epochMilliseconds);
+}
+/**
+ * Represents an order entity in the system.
+ *
+ * @remark
+ * An order is a lifecycle aggregate: it owns its status transitions, its line
+ * items, the applied pricing result, and its historical facts (buyer,
+ * addresses, payment). It does not validate coupons, does not know promotion
+ * rules, and does not orchestrate external services — those concerns belong
+ * to `@comity/pricing`, other Core Modules, and application/domain services.
+ */
+class Order {
+    #id;
+    #status;
+    #items;
+    #price;
+    #channelId;
+    #customer;
+    #addresses;
+    #payments;
+    #meta;
+    #createdAt;
+    #updatedAt;
+    /**
+     * @param fields - The fields used to create or hydrate the order.
+     * @param id - The unique identifier of the order, if it has been assigned.
+     */
+    constructor(fields, id) {
+        this.#id = id;
+        this.#status = fields.status ?? "draft";
+        this.#items = [...fields.items];
+        this.#price = fields.price;
+        this.#channelId = fields.channelId;
+        this.#customer = fields.customer !== undefined ? copyCustomerSnapshot(fields.customer) : undefined;
+        this.#addresses =
+            fields.addresses !== undefined ? fields.addresses.map((address) => copyAddressSnapshot(address)) : undefined;
+        this.#payments =
+            fields.payments !== undefined
+                ? fields.payments.map((payment) => ({ ...payment }))
+                : undefined;
+        this.#meta = fields.meta ? { ...fields.meta } : undefined;
+        this.#createdAt = fields.createdAt ?? time_1.Instant.now();
+        this.#updatedAt = fields.updatedAt ?? this.#createdAt;
+    }
+    /**
+     * @returns The unique identifier of the order, if it has been assigned.
+     */
+    get id() {
+        return this.#id;
+    }
+    /**
+     * @returns The commercial channel through which the order was placed.
+     */
+    get channelId() {
+        return this.#channelId;
+    }
+    /**
+     * @returns The lifecycle status of the order.
+     */
+    get status() {
+        return this.#status;
+    }
+    /**
+     * @returns The order items.
+     */
+    get items() {
+        return [...this.#items];
+    }
+    /**
+     * @returns The order price.
+     */
+    get price() {
+        return this.#price;
+    }
+    /**
+     * @returns The historical buyer fact, if captured.
+     */
+    get customer() {
+        return this.#customer !== undefined
+            ? {
+                ...this.#customer,
+                ...(this.#customer.contacts !== undefined
+                    ? { contacts: this.#customer.contacts.map((contact) => ({ ...contact })) }
+                    : {}),
+            }
+            : undefined;
+    }
+    /**
+     * @returns The historical address facts, if captured.
+     */
+    get addresses() {
+        return this.#addresses !== undefined
+            ? this.#addresses.map((address) => ({ ...address, lines: [...address.lines] }))
+            : undefined;
+    }
+    /**
+     * @returns The historical payment facts, if attached.
+     */
+    get payments() {
+        return this.#payments?.map((payment) => ({ ...payment }));
+    }
+    /**
+     * @returns The custom metadata of the order, if any.
+     */
+    get meta() {
+        return this.#meta ? { ...this.#meta } : undefined;
+    }
+    /**
+     * @returns The timestamp when the order was created.
+     */
+    get createdAt() {
+        return this.#createdAt;
+    }
+    /**
+     * @returns The timestamp when the order was last updated.
+     */
+    get updatedAt() {
+        return this.#updatedAt;
+    }
+    /**
+     * Updates the applied pricing result and metadata.
+     *
+     * Status transitions are performed through the domain methods; items are
+     * mutated through `addItem`/`removeItem`/`updateItemQuantity`.
+     *
+     * @param changes - The changes to apply to the order.
+     */
+    update(changes) {
+        if (changes.price !== undefined) {
+            this.#price = changes.price;
+        }
+        if (changes.meta !== undefined) {
+            this.#meta = { ...changes.meta };
+        }
+        this.#updatedAt = time_1.Instant.now();
+    }
+    /**
+     * Appends a historical payment fact to the order.
+     *
+     * A payment may be processed after the order is created, so the outcome is
+     * recorded through a dedicated method rather than the generic update path.
+     * This records a historical fact only: it performs no payment logic, knows
+     * no payment module, and does not coordinate, authorize, or capture.
+     *
+     * @param snapshot - The payment fact to record.
+     */
+    attachPayment(snapshot) {
+        this.#payments = [
+            ...(this.#payments ?? []),
+            { ...snapshot },
+        ];
+        this.#updatedAt = time_1.Instant.now();
+    }
+    /**
+     * Replaces the shipping destination of the order.
+     *
+     * Allowed only while the order is `draft | pending`; in later statuses the
+     * shipping destination is immutable (ADR-018). The order must hold exactly
+     * one shipping address fact; a missing or ambiguous one is an error rather
+     * than a guess. A structurally identical destination is a successful no-op
+     * that leaves timestamps untouched. The operation never reaches the generic
+     * `update()` path, never touches billing, customer, item, price, or payment
+     * facts, and records no history: the aggregate retains only the current
+     * shipping destination.
+     *
+     * @param destination - The replacement shipping destination. The address
+     * role is owned by this operation and is always stored as `"shipping"`.
+     *
+     * @returns A result indicating the success or failure of the change.
+     */
+    changeShippingDestination(destination) {
+        if (this.#status !== "draft" && this.#status !== "pending") {
+            return (0, result_1.failure)(new order_js_1.OrderError("shipping_destination_immutable", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                },
+            }));
+        }
+        const addresses = this.#addresses;
+        const shipping = (addresses ?? []).filter((address) => address.role === "shipping");
+        const current = shipping.length === 1 ? shipping[0] : undefined;
+        if (current === undefined || addresses === undefined) {
+            return (0, result_1.failure)(new order_js_1.OrderError("ambiguous_shipping_destination", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                },
+            }));
+        }
+        if (isSameShippingDestination(current, destination)) {
+            return (0, result_1.success)(undefined);
+        }
+        this.#addresses = addresses.map((address) => address.role === "shipping" ? copyAddressSnapshot({ ...destination, role: "shipping" }) : address);
+        this.#updatedAt = time_1.Instant.now();
+        return (0, result_1.success)(undefined);
+    }
+    /**
+     * Adds an item to the order.
+     *
+     * @param input - The item data to add.
+     *
+     * @returns The created item, or an `invalid_quantity` error when the
+     * quantity is not a positive integer.
+     */
+    addItem(input) {
+        if (!Number.isInteger(input.quantity) || input.quantity < 1) {
+            return (0, result_1.failure)(new order_js_1.OrderError("invalid_quantity", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    field: "quantity",
+                },
+            }));
+        }
+        const item = {
+            id: crypto.randomUUID(),
+            product: copyProductSnapshot(input.product),
+            quantity: input.quantity,
+            price: input.price,
+        };
+        this.#items.push(item);
+        this.#updatedAt = time_1.Instant.now();
+        return (0, result_1.success)(item);
+    }
+    /**
+     * Removes an item from the order.
+     *
+     * @param itemId - The order item ID.
+     *
+     * @returns A result indicating the success or failure of the removal.
+     */
+    removeItem(itemId) {
+        const index = this.#items.findIndex((item) => item.id === itemId);
+        if (index === -1) {
+            return (0, result_1.failure)(new order_js_1.OrderError("invalid_item", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    itemId,
+                },
+            }));
+        }
+        this.#items.splice(index, 1);
+        this.#updatedAt = time_1.Instant.now();
+        return (0, result_1.success)(undefined);
+    }
+    /**
+     * Updates the quantity of an order item.
+     *
+     * @param itemId - The order item ID.
+     * @param quantity - The new quantity.
+     *
+     * @returns A result indicating the success or failure of the update.
+     */
+    updateItemQuantity(itemId, quantity) {
+        if (!Number.isInteger(quantity) || quantity < 1) {
+            return (0, result_1.failure)(new order_js_1.OrderError("invalid_quantity", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    itemId,
+                    field: "quantity",
+                },
+            }));
+        }
+        const index = this.#items.findIndex((candidate) => candidate.id === itemId);
+        if (index === -1) {
+            return (0, result_1.failure)(new order_js_1.OrderError("invalid_item", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    itemId,
+                },
+            }));
+        }
+        const current = this.#items[index];
+        if (current !== undefined) {
+            this.#items[index] = { ...current, quantity };
+            this.#updatedAt = time_1.Instant.now();
+        }
+        return (0, result_1.success)(undefined);
+    }
+    /**
+     * Submits the order: `draft` → `pending`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    submit() {
+        return this.#transition("pending");
+    }
+    /**
+     * Confirms the order: `pending` → `confirmed`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    confirm() {
+        return this.#transition("confirmed");
+    }
+    /**
+     * Fulfills the order: `confirmed` → `fulfilled`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    fulfill() {
+        return this.#transition("fulfilled");
+    }
+    /**
+     * Cancels the order: `draft | pending | confirmed` → `cancelled`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    cancel() {
+        return this.#transition("cancelled");
+    }
+    /**
+     * Creates a snapshot of the current state of the order.
+     * Requires the order to have an assigned identifier.
+     *
+     * @returns A snapshot representing the current state of the order.
+     */
+    snapshot() {
+        return {
+            id: this.#id,
+            status: this.#status,
+            items: [...this.#items],
+            price: this.#price,
+            channelId: this.#channelId,
+            ...(this.#customer !== undefined ? { customer: copyCustomerSnapshot(this.#customer) } : {}),
+            ...(this.#addresses !== undefined
+                ? { addresses: this.#addresses.map((address) => copyAddressSnapshot(address)) }
+                : {}),
+            ...(this.#payments !== undefined
+                ? {
+                    payments: this.#payments.map((payment) => ({ ...payment })),
+                }
+                : {}),
+            ...(this.#meta !== undefined ? { meta: { ...this.#meta } } : {}),
+            createdAt: this.#createdAt,
+            updatedAt: this.#updatedAt,
+            capturedAt: time_1.Instant.now(),
+        };
+    }
+    /**
+     * Applies a lifecycle transition through the centralized transition rules.
+     *
+     * @param to - The target status.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    #transition(to) {
+        const result = (0, order_transitions_js_1.transitionOrderStatus)(this.#status, to);
+        if (!result.success) {
+            return result;
+        }
+        this.#status = to;
+        this.#updatedAt = time_1.Instant.now();
+        return (0, result_1.success)(undefined);
+    }
+}
+exports.Order = Order;
+//# sourceMappingURL=order.js.map

package/dist/cjs/errors/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderError = void 0;
+var order_js_1 = require("./order.js");
+Object.defineProperty(exports, "OrderError", { enumerable: true, get: function () { return order_js_1.OrderError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/errors/order.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderError = void 0;
+const errors_1 = require("@comity/primitives/errors");
+const REASON_MESSAGES = {
+    invalid_quantity: "Invalid order item quantity",
+    invalid_item: "Order item not found",
+    invalid_status_transition: "Invalid order status transition",
+    shipping_destination_immutable: "Shipping destination cannot be changed in the current order status",
+    ambiguous_shipping_destination: "Order must contain exactly one shipping destination",
+};
+const REASON_HTTP_STATUS = {
+    invalid_quantity: 400,
+    invalid_item: 400,
+    invalid_status_transition: 409,
+    shipping_destination_immutable: 409,
+    ambiguous_shipping_destination: 409,
+};
+/**
+ * Order operation error with typed reasons.
+ */
+class OrderError extends errors_1.BaseError {
+    /** Error code. */
+    code;
+    /**
+     * @param reason - The reason for the order error.
+     * @param meta - Additional metadata for the error.
+     */
+    constructor(reason, meta) {
+        super(REASON_MESSAGES[reason], {
+            httpStatus: REASON_HTTP_STATUS[reason],
+            ...meta,
+            reason,
+        });
+        this.code = `order:${reason}`;
+    }
+}
+exports.OrderError = OrderError;
+//# sourceMappingURL=order.js.map