@comity/order 0.9.0

package/dist/esm/errors/order.js

@@ -0,0 +1,35 @@
+import { BaseError } from "@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.
+ */
+export class OrderError extends 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}`;
+    }
+}
+//# sourceMappingURL=order.js.map

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { Order } from "./entities/order.js";
+export { OrderId } from "./value-objects/order-id.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/repositories/index.js

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

package/dist/esm/repositories/memory.js

@@ -0,0 +1,65 @@
+import { success } from "@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.
+ */
+export 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 success(null);
+        }
+        return success(order);
+    }
+    /**
+     * @inheritdoc
+     */
+    async save(order, ctx) {
+        this.#orders.set(this.#makeKey(ctx.tenant, order.id), order);
+        return 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 success({
+            items,
+            total,
+        });
+    }
+}
+//# sourceMappingURL=memory.js.map

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

@@ -0,0 +1,66 @@
+import { failure, success } from "@comity/primitives/result";
+import { InvalidIdentifierError } from "@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.
+ */
+export 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 failure(new InvalidIdentifierError("empty", {
+                details: { kind: "OrderId" },
+            }));
+        }
+        return 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;
+    }
+}
+//# sourceMappingURL=order-id.js.map

package/dist/types/contracts/address-snapshot.d.ts

@@ -0,0 +1,35 @@
+import type { Instant } from "@comity/primitives/time";
+/**
+ * Role an address plays within a purchase.
+ */
+export type OrderAddressRole = "shipping" | "billing";
+/**
+ * Immutable historical fact about an address used by an order.
+ *
+ * A plain, owned representation of an address as it was at purchase time. It
+ * is NOT `Address` from `@comity/address` and it is not a reference to the
+ * address module: once the order is created it MUST NOT depend on the address
+ * module for its content.
+ *
+ * A single generic type describes every address; the {@link role} discriminates
+ * between shipping and billing. Identical addresses are represented once per
+ * role rather than as a dedicated `ShippingAddress`/`BillingAddress` shape.
+ */
+export interface OrderAddressSnapshot {
+    /** Reference to the address identifier, if still known. */
+    readonly addressId?: string;
+    /** The role of the address within the purchase. */
+    readonly role: OrderAddressRole;
+    /** Free-form address lines, e.g. street address. */
+    readonly lines: ReadonlyArray<string>;
+    /** The city of the address. */
+    readonly city: string;
+    /** The administrative area (e.g. state or province), if any. */
+    readonly administrativeArea?: string;
+    /** The postal code of the address. */
+    readonly postalCode: string;
+    /** The country code of the address. */
+    readonly countryCode: string;
+    /** The timestamp when the address fact was captured. */
+    readonly capturedAt: Instant;
+}

package/dist/types/contracts/contact.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Historical contact method associated with an order purchaser.
+ *
+ * A plain, owned representation of a customer contact at purchase time. It
+ * mirrors the shape of the customer module's contact concept without
+ * importing any customer type: `@comity/order` stays independent of
+ * `@comity/customer`.
+ */
+export interface OrderContact {
+    /** The type of contact, e.g. "email" or "phone". */
+    readonly type: string;
+    /** The contact value. */
+    readonly value: string;
+}

package/dist/types/contracts/customer-snapshot.d.ts

@@ -0,0 +1,24 @@
+import type { Instant } from "@comity/primitives/time";
+import type { OrderContact } from "./contact.js";
+/**
+ * Immutable historical fact about the buyer of an order.
+ *
+ * A plain, owned representation of the customer as it was at purchase time.
+ * It is NOT `Customer` from `@comity/customer` and it is not a reference to
+ * the customer module: once the order is created it MUST NOT depend on the
+ * customer for its content. Historical order rendering, customer support, and
+ * invoice generation rely exclusively on this record.
+ *
+ * Only identity and display facts are preserved. Operational customer state
+ * (preferences, lifecycle metadata) is not copied.
+ */
+export interface OrderCustomerSnapshot {
+    /** Reference to the customer identifier, if still known. */
+    readonly customerId?: string;
+    /** Display name of the buyer. */
+    readonly displayName: string;
+    /** Buyer contact channels, e.g. email or phone. */
+    readonly contacts?: ReadonlyArray<OrderContact>;
+    /** The timestamp when the customer fact was captured. */
+    readonly capturedAt: Instant;
+}

package/dist/types/contracts/item.d.ts

@@ -0,0 +1,100 @@
+import type { Price } from "@comity/pricing";
+/**
+ * Product attribute snapshot associated with an order item.
+ *
+ * A frozen copy of a product attribute at purchase time. It mirrors
+ * `ProductAttribute` from `@comity/catalog` without importing catalog types:
+ * the order stays independent of the catalog read model.
+ */
+export interface OrderProductAttribute {
+    /** Attribute code. */
+    readonly code: string;
+    /** Display name of the attribute. */
+    readonly label?: string;
+    /** Attribute value. */
+    readonly value: string | number | boolean;
+}
+/**
+ * Selected option snapshot for an order item (e.g. size = "M", color = "blue").
+ *
+ * A frozen copy of a chosen product option at purchase time. It mirrors
+ * `ProductOptionSelection` from `@comity/catalog` without importing catalog
+ * types; the `label` is preserved so the selection stays renderable without
+ * the catalog.
+ */
+export interface OrderProductOption {
+    /** Option code. */
+    readonly code: string;
+    /** Display name of the option. */
+    readonly label?: string;
+    /** Selected option value. */
+    readonly value: string;
+}
+/**
+ * Product variant snapshot associated with an order item.
+ *
+ * A frozen copy of the purchased product variant at purchase time. It mirrors
+ * `ProductVariant` from `@comity/catalog` without importing catalog types and
+ * carries no pricing or inventory — those belong to their owning modules.
+ */
+export interface OrderVariantSnapshot {
+    /** Variant identifier. */
+    readonly id: string;
+    /** Stock Keeping Unit of the variant. */
+    readonly sku?: string;
+    /** Display name of the variant. */
+    readonly name?: string;
+    /** Variant attribute snapshots. */
+    readonly attributes?: ReadonlyArray<OrderProductAttribute>;
+    /** Selected option snapshots of the variant. */
+    readonly options?: ReadonlyArray<OrderProductOption>;
+}
+/**
+ * Immutable product snapshot associated with an order item.
+ *
+ * A self-contained representation of the product as it was at purchase time.
+ * It is NOT `ProductProjection` from `@comity/catalog` and it is NOT a
+ * reference to the catalog: once the order is created it MUST NOT depend on
+ * the catalog for its content. Historical order rendering, customer support,
+ * invoice generation, and returns workflows rely exclusively on this record.
+ */
+export interface OrderProductSnapshot {
+    /** Reference to the catalog product identifier, if still known. */
+    readonly productId?: string;
+    /** Stock Keeping Unit. */
+    readonly sku: string;
+    /** Product name. */
+    readonly name: string;
+    /** The purchased variant, if the product is variant-based. */
+    readonly variant?: OrderVariantSnapshot;
+    /** Product attribute snapshots. */
+    readonly attributes?: ReadonlyArray<OrderProductAttribute>;
+    /** Selected option snapshots. */
+    readonly options?: ReadonlyArray<OrderProductOption>;
+    /** Free-form metadata (e.g. image URL, page URL). */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Order line item.
+ *
+ * Embedded value structure of the Order aggregate: it has no independent
+ * identity, lifecycle, or repository.
+ */
+export interface OrderItem {
+    /** Unique item identifier within the order. */
+    readonly id: string;
+    /** Associated product snapshot. */
+    readonly product: OrderProductSnapshot;
+    /** Requested quantity. */
+    readonly quantity: number;
+    /**
+     * Full line price (subtotal, applied modifiers, total).
+     *
+     * `@comity/pricing` is the single owner of price composition data: price
+     * modifiers are accessed exclusively through `price.modifiers`. The order
+     * stores the immutable `Price` value and never duplicates modifier storage.
+     */
+    readonly price: Price;
+    /** Custom metadata. */
+    readonly meta?: Record<string, unknown>;
+}

package/dist/types/contracts/order-repository.d.ts

@@ -0,0 +1,82 @@
+import type { RepositoryError } from "@comity/primitives/errors";
+import type { Result } from "@comity/primitives/result";
+import type { TenantId } from "@comity/organization";
+import type { Order } from "../entities/order.js";
+import type { OrderId } from "../value-objects/order-id.js";
+import type { OrderState, OrderStatus } from "./order.js";
+/**
+ * Minimal search/filter criteria for orders.
+ */
+export interface OrderSearchCriteria {
+    /** Filter orders by lifecycle status. */
+    readonly status?: OrderStatus | undefined;
+    /** The maximum number of results to return. */
+    readonly limit?: number | undefined;
+    /** The offset for paginated results. */
+    readonly offset?: number | undefined;
+}
+/**
+ * Result of listing or searching orders.
+ */
+export interface OrderSearchResult {
+    /** The matching orders. */
+    readonly items: ReadonlyArray<OrderState>;
+    /** Total number of matching orders. */
+    readonly total: number;
+}
+/**
+ * Context for order repository operations.
+ *
+ * The tenant provides the isolation boundary for the operation.
+ * It is not stored on the order itself — tenant is an operational
+ * context, not a business fact of the order.
+ */
+export interface OrderRepositoryContext {
+    /** The tenant identifier for isolation. */
+    readonly tenant: TenantId;
+}
+/**
+ * Order repository contract.
+ *
+ * @remarks
+ * This contract is the persistence boundary only. Domain behavior (status
+ * transitions, item mutations) lives on the `Order` entity; orchestration
+ * belongs to application/domain services.
+ *
+ * @remarks
+ * Not found is `null`, never an error. Orders are not physically deleted: the
+ * terminal lifecycle states are `cancelled` and `fulfilled`, so no `remove`
+ * operation is exposed.
+ */
+export interface OrderRepository {
+    /**
+     * Retrieve an order by identifier.
+     *
+     * @param id - Order ID.
+     * @param ctx - Repository context containing tenant for isolation.
+     *
+     * @returns Order entity or null if not found.
+     */
+    getById(id: OrderId, ctx: OrderRepositoryContext): Promise<Result<Order | null, RepositoryError>>;
+    /**
+     * Persist an order.
+     *
+     * @param order - Order to persist.
+     * @param ctx - Repository context containing tenant for isolation.
+     *
+     * @remarks
+     * Implementations MUST treat this as upsert: if the order id already
+     * exists the stored order is overwritten, otherwise a new order is
+     * created.
+     */
+    save(order: Order, ctx: OrderRepositoryContext): Promise<Result<void, RepositoryError>>;
+    /**
+     * Search orders matching the given criteria.
+     *
+     * @param criteria - Search criteria.
+     * @param ctx - Repository context containing tenant for isolation.
+     *
+     * @returns Matching orders with a total count.
+     */
+    search(criteria: OrderSearchCriteria | undefined, ctx: OrderRepositoryContext): Promise<Result<OrderSearchResult, RepositoryError>>;
+}

package/dist/types/contracts/order.d.ts

@@ -0,0 +1,108 @@
+import type { Price } from "@comity/pricing";
+import type { Instant } from "@comity/primitives/time";
+import type { OrderId } from "../value-objects/order-id.js";
+import type { ChannelId } from "@comity/organization";
+import type { OrderAddressSnapshot } from "./address-snapshot.js";
+import type { OrderCustomerSnapshot } from "./customer-snapshot.js";
+import type { OrderItem, OrderProductSnapshot } from "./item.js";
+import type { OrderPaymentSnapshot } from "./payment-snapshot.js";
+/**
+ * Order status.
+ *
+ * An order starts in {@link OrderStatus."draft"} and progresses through a linear lifecycle.
+ * Each transition is explicit; the status cannot move backwards.
+ *
+ * Transitions:
+ * - `draft` → `pending` (submit)
+ * - `pending` → `confirmed` (confirm)
+ * - `confirmed` → `fulfilled` (fulfill)
+ * - `draft | pending | confirmed` → `cancelled` (cancel)
+ *
+ * `fulfilled` and `cancelled` are terminal.
+ */
+export type OrderStatus = "draft" | "pending" | "confirmed" | "fulfilled" | "cancelled";
+/**
+ * Business data of an order, independent of identity and lifecycle metadata.
+ */
+export interface OrderData {
+    /** Order items. */
+    readonly items: ReadonlyArray<OrderItem>;
+    /** Order price. `@comity/pricing` owns price composition: modifiers are accessed through `price.modifiers`. */
+    readonly price: Price;
+    /** The commercial channel through which the order was placed. */
+    readonly channelId: ChannelId;
+    /** Historical buyer fact, captured at purchase time. */
+    readonly customer?: OrderCustomerSnapshot;
+    /** Historical address facts (shipping/billing), captured at purchase time. */
+    readonly addresses?: ReadonlyArray<OrderAddressSnapshot>;
+    /** Historical payment facts, attached after processing. */
+    readonly payments?: ReadonlyArray<OrderPaymentSnapshot>;
+    /** Custom metadata. */
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * The persistent state of an existing order.
+ */
+export interface OrderState extends OrderData {
+    /** Unique order identifier. */
+    readonly id: OrderId;
+    /** Order lifecycle status. */
+    readonly status: OrderStatus;
+    /** Creation timestamp. */
+    readonly createdAt: Instant;
+    /** Last update timestamp. */
+    readonly updatedAt: Instant;
+}
+/**
+ * Immutable point-in-time snapshot of an existing order.
+ */
+export type OrderSnapshot = Readonly<OrderState & {
+    /** The timestamp when the snapshot was captured. */
+    readonly capturedAt: Instant;
+}>;
+/**
+ * Data required to create a new order.
+ *
+ * The identifier and the initial status are managed by the entity: an order
+ * without a supplied status starts as {@link OrderStatus."draft"}. Lifecycle
+ * timestamps are optional so the same contract supports both creation and
+ * hydration from persisted state (ADR-001).
+ */
+export type OrderCreate = OrderData & {
+    /** Order lifecycle status, used to restore persisted state during hydration. */
+    readonly status?: OrderStatus;
+    /** The timestamp when the order was created. */
+    readonly createdAt?: Instant;
+    /** The timestamp when the order was last updated. */
+    readonly updatedAt?: Instant;
+};
+/**
+ * Partial mutation data for an order.
+ *
+ * Status transitions are not part of the update contract: they must pass
+ * through the entity's domain methods (`submit`, `confirm`, `fulfill`,
+ * `cancel`). Items are mutated through `addItem`/`removeItem`/
+ * `updateItemQuantity`, which protect the order's invariants.
+ */
+export interface OrderUpdate {
+    /** Order price. Modifiers are updated through `price`; see `@comity/pricing`. */
+    readonly price?: Price;
+    /** Custom metadata. */
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Input for adding an item to the order.
+ *
+ * The item price is supplied by the caller as a complete `Price` value:
+ * price computation belongs to `@comity/pricing` orchestration, not to the
+ * Order aggregate. The product data is an owned snapshot mapped by the caller
+ * from `ProductProjection`: the Order never depends on `@comity/catalog`.
+ */
+export interface OrderItemInput {
+    /** Product snapshot to add to the order. */
+    readonly product: OrderProductSnapshot;
+    /** Quantity to add. */
+    readonly quantity: number;
+    /** Full line price (subtotal, applied modifiers, total). */
+    readonly price: Price;
+}

package/dist/types/contracts/payment-snapshot.d.ts

@@ -0,0 +1,36 @@
+import type { Instant } from "@comity/primitives/time";
+import type { Money } from "@comity/pricing";
+/**
+ * Outcome of a payment at the time the snapshot was captured.
+ *
+ * Mirrors the confirmed `@comity/payment` lifecycle without importing any
+ * payment type: the order records the factual outcome only.
+ */
+export type OrderPaymentStatus = "authorized" | "captured" | "failed" | "cancelled";
+/**
+ * Immutable historical fact about the payment of an order.
+ *
+ * A plain, owned representation of the payment outcome. It is NOT a payment
+ * entity and it is not a reference to `@comity/payment`: once the snapshot is
+ * attached the order MUST NOT depend on the payment module for its content.
+ *
+ * Only reconciling facts are preserved. The order never coordinates or
+ * recollects a payment; it only records the outcome the Application Layer
+ * attaches after processing.
+ */
+export interface OrderPaymentSnapshot {
+    /** Reference to the payment identifier managed by the payment module. */
+    readonly paymentId?: string;
+    /** The charged amount. */
+    readonly amount: Money;
+    /** The payment outcome at capture time. */
+    readonly status: OrderPaymentStatus;
+    /** The payment provider identifier, if known. */
+    readonly provider?: string;
+    /** The provider-side reference (e.g. transaction/authorization token). */
+    readonly reference?: string;
+    /** The timestamp when the payment was authorized, if known. */
+    readonly authorizedAt?: Instant;
+    /** The timestamp when the payment was captured, if known. */
+    readonly capturedAt?: Instant;
+}

package/dist/types/domain/order-transitions.d.ts

@@ -0,0 +1,22 @@
+import type { Result } from "@comity/primitives/result";
+import type { OrderStatus } from "../contracts/order.js";
+import { OrderError } from "../errors/order.js";
+/**
+ * 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 declare function canTransition(from: OrderStatus, to: OrderStatus): boolean;
+/**
+ * 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 declare function transitionOrderStatus(from: OrderStatus, to: OrderStatus): Result<OrderStatus, OrderError>;