@comity/order 0.9.0

package/dist/cjs/index.js

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

package/dist/cjs/repositories/index.js

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

package/dist/cjs/repositories/memory.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryOrderRepository = void 0;
+const result_1 = require("@comity/primitives/result");
+/**
+ * In-memory implementation of `OrderRepository` for testing and development purposes.
+ *
+ * Note: This implementation is not suitable for production use as it does not persist
+ * sessions and is not shared across multiple instances of the application.
+ */
+class MemoryOrderRepository {
+    /** Internal storage keyed by tenant + order ID */
+    #orders = new Map();
+    #makeKey(tenant, id) {
+        return `${tenant.toString()}\u0000${id.toString()}`;
+    }
+    /**
+     * @inheritdoc
+     */
+    async getById(id, ctx) {
+        const order = this.#orders.get(this.#makeKey(ctx.tenant, id));
+        if (!order) {
+            return (0, result_1.success)(null);
+        }
+        return (0, result_1.success)(order);
+    }
+    /**
+     * @inheritdoc
+     */
+    async save(order, ctx) {
+        this.#orders.set(this.#makeKey(ctx.tenant, order.id), order);
+        return (0, result_1.success)(undefined);
+    }
+    /**
+     * @inheritdoc
+     */
+    async search(criteria, ctx) {
+        const tenantPrefix = `${ctx.tenant.toString()}\u0000`;
+        const all = [...this.#orders.entries()]
+            .filter(([key]) => key.startsWith(tenantPrefix))
+            .map(([, order]) => order);
+        let filtered = all;
+        if (criteria?.status !== undefined) {
+            filtered = filtered.filter((o) => o.status === criteria.status);
+        }
+        const limit = criteria?.limit ?? filtered.length;
+        const offset = criteria?.offset ?? 0;
+        const items = filtered.slice(offset, offset + limit).map((o) => ({
+            id: o.id,
+            status: o.status,
+            createdAt: o.createdAt,
+            updatedAt: o.updatedAt,
+            items: o.items,
+            price: o.price,
+            channelId: o.channelId,
+            ...(o.customer !== undefined ? { customer: o.customer } : {}),
+            ...(o.addresses !== undefined ? { addresses: o.addresses } : {}),
+            ...(o.payments !== undefined ? { payments: o.payments } : {}),
+            ...(o.meta !== undefined ? { meta: o.meta } : {}),
+        }));
+        const total = filtered.length;
+        return (0, result_1.success)({
+            items,
+            total,
+        });
+    }
+}
+exports.MemoryOrderRepository = MemoryOrderRepository;
+//# sourceMappingURL=memory.js.map

package/dist/cjs/value-objects/order-id.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderId = void 0;
+const result_1 = require("@comity/primitives/result");
+const errors_1 = require("@comity/primitives/errors");
+/**
+ * OrderId is a value object that represents the unique identifier of an order.
+ *
+ * @remarks
+ * OrderId is globally unique. The current implementation generates UUIDs.
+ * The repository uses a composite key of `TenantId + OrderId` as its physical
+ * storage namespace, but the OrderId itself is globally unique and not scoped
+ * to a tenant.
+ */
+class OrderId {
+    #value;
+    /**
+     * Creates an OrderId from an identifier string.
+     *
+     * The Value Object is always created in a valid state; an empty or
+     * whitespace-only value yields an `empty` failure instead of throwing.
+     *
+     * @param value - The value of the order ID.
+     *
+     * @returns The OrderId, or an `empty` error when the value is empty or
+     * whitespace-only.
+     */
+    static create(value) {
+        if (value.trim().length === 0) {
+            return (0, result_1.failure)(new errors_1.InvalidIdentifierError("empty", {
+                details: { kind: "OrderId" },
+            }));
+        }
+        return (0, result_1.success)(new OrderId(value));
+    }
+    /**
+     * @param value - The value of the order ID.
+     */
+    constructor(value) {
+        this.#value = value;
+    }
+    /**
+     * Returns the underlying string value of the order ID.
+     *
+     * @returns The underlying identifier.
+     */
+    get value() {
+        return this.#value;
+    }
+    /**
+     * Checks if this OrderId is equal to another OrderId.
+     *
+     * @param other - The other OrderId to compare with.
+     *
+     * @returns True if the OrderIds are equal, false otherwise.
+     */
+    equals(other) {
+        return this.#value === other.toString();
+    }
+    /**
+     * Returns a string representation of the order ID.
+     *
+     * @returns The string representation of the order ID.
+     */
+    toString() {
+        return this.#value;
+    }
+}
+exports.OrderId = OrderId;
+//# sourceMappingURL=order-id.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=address-snapshot.js.map

package/dist/esm/contracts/contact.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contact.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=customer-snapshot.js.map

package/dist/esm/contracts/item.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=item.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=order-repository.js.map

package/dist/esm/contracts/order.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=order.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=payment-snapshot.js.map

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

@@ -0,0 +1,48 @@
+import { failure, success } from "@comity/primitives/result";
+import { OrderError } from "../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.
+ */
+export 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.
+ */
+export function transitionOrderStatus(from, to) {
+    if (!canTransition(from, to)) {
+        return failure(new OrderError("invalid_status_transition", {
+            details: { from, to },
+        }));
+    }
+    return success(to);
+}
+//# sourceMappingURL=order-transitions.js.map

package/dist/esm/entities/order.js

@@ -0,0 +1,455 @@
+import { failure, success } from "@comity/primitives/result";
+import { Instant } from "@comity/primitives/time";
+import { transitionOrderStatus } from "../domain/order-transitions.js";
+import { OrderError } from "../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.
+ */
+export 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 ?? 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 = 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 = 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 failure(new 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 failure(new OrderError("ambiguous_shipping_destination", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                },
+            }));
+        }
+        if (isSameShippingDestination(current, destination)) {
+            return success(undefined);
+        }
+        this.#addresses = addresses.map((address) => address.role === "shipping" ? copyAddressSnapshot({ ...destination, role: "shipping" }) : address);
+        this.#updatedAt = Instant.now();
+        return 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 failure(new 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 = Instant.now();
+        return 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 failure(new OrderError("invalid_item", {
+                details: {
+                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    itemId,
+                },
+            }));
+        }
+        this.#items.splice(index, 1);
+        this.#updatedAt = Instant.now();
+        return 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 failure(new 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 failure(new 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 = Instant.now();
+        }
+        return 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: 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 = transitionOrderStatus(this.#status, to);
+        if (!result.success) {
+            return result;
+        }
+        this.#status = to;
+        this.#updatedAt = Instant.now();
+        return success(undefined);
+    }
+}
+//# sourceMappingURL=order.js.map

package/dist/esm/errors/index.js

@@ -0,0 +1,2 @@
+export { OrderError } from "./order.js";
+//# sourceMappingURL=index.js.map