@comity/order 0.9.0

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

@@ -0,0 +1,168 @@
+import type { Price } from "@comity/pricing";
+import type { Result } from "@comity/primitives/result";
+import type { OrderAddressSnapshot } from "../contracts/address-snapshot.js";
+import type { OrderCustomerSnapshot } from "../contracts/customer-snapshot.js";
+import type { OrderItem } from "../contracts/item.js";
+import type { OrderCreate, OrderItemInput, OrderSnapshot, OrderStatus, OrderUpdate } from "../contracts/order.js";
+import type { OrderPaymentSnapshot } from "../contracts/payment-snapshot.js";
+import type { OrderId } from "../value-objects/order-id.js";
+import type { ChannelId } from "@comity/organization";
+import { Instant } from "@comity/primitives/time";
+import { OrderError } from "../errors/order.js";
+/**
+ * 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 declare class Order {
+    #private;
+    /**
+     * @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: OrderCreate, id?: OrderId);
+    /**
+     * @returns The unique identifier of the order, if it has been assigned.
+     */
+    get id(): OrderId | undefined;
+    /**
+     * @returns The commercial channel through which the order was placed.
+     */
+    get channelId(): ChannelId;
+    /**
+     * @returns The lifecycle status of the order.
+     */
+    get status(): OrderStatus;
+    /**
+     * @returns The order items.
+     */
+    get items(): ReadonlyArray<OrderItem>;
+    /**
+     * @returns The order price.
+     */
+    get price(): Price;
+    /**
+     * @returns The historical buyer fact, if captured.
+     */
+    get customer(): OrderCustomerSnapshot | undefined;
+    /**
+     * @returns The historical address facts, if captured.
+     */
+    get addresses(): ReadonlyArray<OrderAddressSnapshot> | undefined;
+    /**
+     * @returns The historical payment facts, if attached.
+     */
+    get payments(): ReadonlyArray<OrderPaymentSnapshot> | undefined;
+    /**
+     * @returns The custom metadata of the order, if any.
+     */
+    get meta(): Readonly<Record<string, unknown>> | undefined;
+    /**
+     * @returns The timestamp when the order was created.
+     */
+    get createdAt(): Instant;
+    /**
+     * @returns The timestamp when the order was last updated.
+     */
+    get updatedAt(): Instant;
+    /**
+     * 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: OrderUpdate): void;
+    /**
+     * 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: OrderPaymentSnapshot): void;
+    /**
+     * 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: Omit<OrderAddressSnapshot, "role">): Result<void, OrderError>;
+    /**
+     * 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: OrderItemInput): Result<OrderItem, OrderError>;
+    /**
+     * 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: string): Result<void, OrderError>;
+    /**
+     * 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: string, quantity: number): Result<void, OrderError>;
+    /**
+     * Submits the order: `draft` → `pending`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    submit(): Result<void, OrderError>;
+    /**
+     * Confirms the order: `pending` → `confirmed`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    confirm(): Result<void, OrderError>;
+    /**
+     * Fulfills the order: `confirmed` → `fulfilled`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    fulfill(): Result<void, OrderError>;
+    /**
+     * Cancels the order: `draft | pending | confirmed` → `cancelled`.
+     *
+     * @returns A result indicating the success or failure of the transition.
+     */
+    cancel(): Result<void, OrderError>;
+    /**
+     * 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(): OrderSnapshot;
+}

package/dist/types/errors/index.d.ts

@@ -0,0 +1,2 @@
+export type { OrderErrorReason } from "./order.js";
+export { OrderError } from "./order.js";

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

@@ -0,0 +1,44 @@
+import type { ErrorMeta } from "@comity/primitives/errors";
+import { BaseError } from "@comity/primitives/errors";
+/**
+ * Order error reason.
+ *
+ * Contains only domain conditions owned by the Order aggregate. Not-found is
+ * a `null` repository result, never an error; infrastructure and
+ * cross-module failures (`repository_error`, `insufficient_stock`,
+ * `product_not_available`, coupon validation) belong to other layers/modules.
+ */
+export type OrderErrorReason = "invalid_quantity" | "invalid_item" | "invalid_status_transition" | "shipping_destination_immutable" | "ambiguous_shipping_destination";
+/**
+ * Order error metadata.
+ */
+interface OrderErrorMeta extends ErrorMeta {
+    /** Error reason. */
+    readonly reason: OrderErrorReason;
+    /** Contextual details. */
+    readonly details?: Readonly<{
+        /** Affected order ID. */
+        orderId?: string;
+        /** Affected item ID. */
+        itemId?: string;
+        /** Invalid input field. */
+        field?: string;
+        /** Source status of an invalid transition. */
+        from?: string;
+        /** Target status of an invalid transition. */
+        to?: string;
+    }>;
+}
+/**
+ * Order operation error with typed reasons.
+ */
+export declare class OrderError extends BaseError<OrderErrorMeta> {
+    /** Error code. */
+    readonly code: `order:${OrderErrorReason}`;
+    /**
+     * @param reason - The reason for the order error.
+     * @param meta - Additional metadata for the error.
+     */
+    constructor(reason: OrderErrorReason, meta?: Omit<OrderErrorMeta, "reason">);
+}
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+export type { OrderAddressRole, OrderAddressSnapshot } from "./contracts/address-snapshot.js";
+export type { OrderContact } from "./contracts/contact.js";
+export type { OrderCustomerSnapshot } from "./contracts/customer-snapshot.js";
+export type { OrderItem, OrderProductAttribute, OrderProductOption, OrderProductSnapshot, OrderVariantSnapshot, } from "./contracts/item.js";
+export type { OrderRepository, OrderRepositoryContext, OrderSearchCriteria, OrderSearchResult } from "./contracts/order-repository.js";
+export type { OrderCreate, OrderData, OrderItemInput, OrderSnapshot, OrderState, OrderStatus, OrderUpdate, } from "./contracts/order.js";
+export type { OrderPaymentSnapshot, OrderPaymentStatus } from "./contracts/payment-snapshot.js";
+export { Order } from "./entities/order.js";
+export { OrderId } from "./value-objects/order-id.js";

package/dist/types/repositories/index.d.ts

@@ -0,0 +1 @@
+export { MemoryOrderRepository } from "./memory.js";

package/dist/types/repositories/memory.d.ts

@@ -0,0 +1,26 @@
+import type { RepositoryError } from "@comity/primitives/errors";
+import type { Result } from "@comity/primitives/result";
+import type { OrderRepository, OrderRepositoryContext, OrderSearchCriteria, OrderSearchResult } from "../contracts/order-repository.js";
+import type { Order } from "../entities/order.js";
+import type { OrderId } from "../value-objects/order-id.js";
+/**
+ * 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 declare class MemoryOrderRepository implements OrderRepository {
+    #private;
+    /**
+     * @inheritdoc
+     */
+    getById(id: OrderId, ctx: OrderRepositoryContext): Promise<Result<Order | null, RepositoryError>>;
+    /**
+     * @inheritdoc
+     */
+    save(order: Order, ctx: OrderRepositoryContext): Promise<Result<void, RepositoryError>>;
+    /**
+     * @inheritdoc
+     */
+    search(criteria: OrderSearchCriteria | undefined, ctx: OrderRepositoryContext): Promise<Result<OrderSearchResult, RepositoryError>>;
+}

package/dist/types/value-objects/order-id.d.ts

@@ -0,0 +1,50 @@
+import type { Result } 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 declare class OrderId {
+    #private;
+    /**
+     * 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: string): Result<OrderId, InvalidIdentifierError>;
+    /**
+     * @param value - The value of the order ID.
+     */
+    private constructor();
+    /**
+     * Returns the underlying string value of the order ID.
+     *
+     * @returns The underlying identifier.
+     */
+    get value(): string;
+    /**
+     * 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: OrderId): boolean;
+    /**
+     * Returns a string representation of the order ID.
+     *
+     * @returns The string representation of the order ID.
+     */
+    toString(): string;
+}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@comity/order",
+  "version": "0.9.0",
+  "description": "Order domain contracts for Comity commerce modules.",
+  "type": "module",
+  "private": false,
+  "author": "Filippo Bovo <hello@filippobovo.com>",
+  "license": "MIT",
+  "comity": {
+    "layer": "core"
+  },
+  "homepage": "https://github.com/comityjs/framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comityjs/framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/comityjs/framework/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "comity",
+    "comityjs",
+    "cart",
+    "ecommerce",
+    "order",
+    "typescript"
+  ],
+  "files": [
+    "./dist",
+    "!./dist/**/*.map"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/types/errors/index.d.ts",
+        "default": "./dist/esm/errors/index.js"
+      },
+      "require": {
+        "types": "./dist/types/errors/index.d.ts",
+        "default": "./dist/cjs/errors/index.js"
+      }
+    },
+    "./repositories": {
+      "import": {
+        "types": "./dist/types/repositories/index.d.ts",
+        "default": "./dist/esm/repositories/index.js"
+      },
+      "require": {
+        "types": "./dist/types/repositories/index.d.ts",
+        "default": "./dist/cjs/repositories/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "errors": [
+        "./dist/types/errors/index.d.ts"
+      ],
+      "repositories": [
+        "./dist/types/repositories/index.d.ts"
+      ]
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@comity/pricing": "0.9.0",
+    "@comity/organization": "0.9.0",
+    "@comity/primitives": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "node ../../scripts/build.mjs --watch",
+    "test": "vitest run --coverage",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .ts src"
+  }
+}