@comity/order 0.9.0 → 0.9.2

package/dist/cjs/entities/order.js

@@ -1,459 +0,0 @@
-"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

@@ -1,6 +0,0 @@
-"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

@@ -1,39 +0,0 @@
-"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

package/dist/cjs/index.js

@@ -1,8 +0,0 @@
-"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

@@ -1,6 +0,0 @@
-"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

@@ -1,69 +0,0 @@
-"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

@@ -1,70 +0,0 @@
-"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