@unchainedshop/core-orders 5.0.0-alpha.4 → 5.0.0-alpha.7

package/README.md

@@ -13,126 +13,18 @@ npm install @unchainedshop/core-orders
 
 ## Usage
 
-```typescript
-import { configureOrdersModule, OrderStatus } from '@unchainedshop/core-orders';
-
-const ordersModule = await configureOrdersModule({ db });
-
-// Create an order
-const orderId = await ordersModule.create({
-  userId: 'user-123',
-  currency: 'CHF',
-  countryCode: 'CH',
-});
+The platform initializes this module as `platform.unchainedAPI.modules.orders`.
 
-// Add position to order
-await ordersModule.positions.create({
-  orderId,
-  productId: 'product-456',
-  quantity: 2,
-});
+```typescript
+const { orders } = platform.unchainedAPI.modules;
 
-// Checkout order
-await ordersModule.checkout(orderId, { paymentContext: {} });
+const order = await orders.findOrder({ orderId: 'order-123' });
+const userOrders = await orders.findOrders({ userId: 'user-123', limit: 20 });
 ```
 
-## API Overview
-
-### Module Configuration
-
-| Export | Description |
-|--------|-------------|
-| `configureOrdersModule` | Configure and return the orders module |
-
-### Queries
-
-| Method | Description |
-|--------|-------------|
-| `findOrder` | Find order by ID or number |
-| `findOrders` | Find orders with filtering and pagination |
-| `count` | Count orders matching query |
-| `orderExists` | Check if order exists |
-
-### Mutations
-
-| Method | Description |
-|--------|-------------|
-| `create` | Create a new order |
-| `update` | Update order data |
-| `delete` | Delete an order |
-| `checkout` | Process order checkout |
-| `confirm` | Confirm an order |
-| `reject` | Reject an order |
-| `setPaymentProvider` | Set payment provider |
-| `setDeliveryProvider` | Set delivery provider |
-
-### Submodules
-
-#### Positions (`orders.positions`)
-| Method | Description |
-|--------|-------------|
-| `findPositions` | Find order positions |
-| `create` | Add position to order |
-| `update` | Update position |
-| `delete` | Remove position |
-
-#### Payments (`orders.payments`)
-| Method | Description |
-|--------|-------------|
-| `findPayment` | Find order payment |
-| `create` | Create payment for order |
-| `markPaid` | Mark payment as paid |
-| `charge` | Charge the payment |
-
-#### Deliveries (`orders.deliveries`)
-| Method | Description |
-|--------|-------------|
-| `findDelivery` | Find order delivery |
-| `create` | Create delivery for order |
-| `markDelivered` | Mark as delivered |
-| `send` | Trigger delivery |
-
-#### Discounts (`orders.discounts`)
-| Method | Description |
-|--------|-------------|
-| `findDiscounts` | Find order discounts |
-| `create` | Add discount to order |
-| `delete` | Remove discount |
-
-### Constants
-
-| Export | Description |
-|--------|-------------|
-| `OrderStatus` | Order status values (OPEN, PENDING, CONFIRMED, FULFILLED, REJECTED) |
-
-### Settings
-
-| Export | Description |
-|--------|-------------|
-| `ordersSettings` | Access order module settings |
-
-### Types
-
-| Export | Description |
-|--------|-------------|
-| `Order` | Order document type |
-| `OrderPosition` | Position document type |
-| `OrderPayment` | Payment document type |
-| `OrderDelivery` | Delivery document type |
-| `OrderDiscount` | Discount document type |
-| `OrdersModule` | Module interface type |
-
-## Events
+Order positions, payments, deliveries, discounts, and statistics are exposed through the corresponding submodules. Use `unchainedAPI.services.orders` or the GraphQL API for cart operations and checkout so pricing, validation, payment, and delivery are coordinated.
 
-| Event | Description |
-|-------|-------------|
-| `ORDER_CREATE` | Order created |
-| `ORDER_UPDATE` | Order updated |
-| `ORDER_REMOVE` | Order deleted |
-| `ORDER_CHECKOUT` | Order checked out |
-| `ORDER_CONFIRMED` | Order confirmed |
-| `ORDER_REJECTED` | Order rejected |
-| `ORDER_FULFILLED` | Order fulfilled |
+See the [module guide](https://docs.unchained.shop/platform-configuration/modules/orders), [checkout guide](https://docs.unchained.shop/guides/checkout-implementation), [public exports](src/orders-index.ts), and [module implementation](src/module/configureOrdersModule.ts).
 
 ## License
 

package/lib/migrations/20260907120000-order-calculation-net.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationRepository } from '@unchainedshop/mongodb';
+import type { PricingCalculation } from '@unchainedshop/utils';
+export declare const convertOrderCalculationToNet: (calculation: PricingCalculation[]) => PricingCalculation[];
+export default function migrateOrderCalculationToNet(repository: MigrationRepository): void;

package/lib/migrations/20260907120000-order-calculation-net.js

@@ -0,0 +1,125 @@
+import { OrdersCollection } from "../db/OrdersCollection.js";
+const legacyCalculationSelector = {
+    'calculation.0': { $exists: true },
+    calculation: {
+        $not: { $elemMatch: { category: { $ne: 'TAXES' }, isNetPrice: true } },
+    },
+};
+export const convertOrderCalculationToNet = (calculation) => {
+    let previousBaseRow;
+    const attributed = calculation.map((row) => {
+        if (!row || !Number.isFinite(row.amount)) {
+            throw new Error('Calculation contains an invalid amount');
+        }
+        if (row.category !== 'TAXES') {
+            previousBaseRow = row;
+            return row;
+        }
+        const baseCategory = row.baseCategory || previousBaseRow?.category;
+        if (!baseCategory || baseCategory === 'TAXES') {
+            throw new Error('Cannot determine the base category of a tax row');
+        }
+        const discountId = row.discountId ??
+            (previousBaseRow?.category === baseCategory ? previousBaseRow.discountId : undefined);
+        return { ...row, baseCategory, discountId, isNetPrice: false };
+    });
+    const converted = attributed.flatMap((row) => {
+        if (row.category !== 'TAXES')
+            return [row];
+        return [
+            {
+                category: row.baseCategory,
+                amount: -row.amount,
+                discountId: row.discountId,
+                isNetPrice: true,
+                meta: row.meta,
+            },
+            row,
+        ];
+    });
+    const sum = (rows, category, discountId) => rows.reduce((total, row) => (category === undefined || row.category === category) &&
+        (discountId === undefined || row.discountId === discountId)
+        ? total + row.amount
+        : total, 0);
+    const taxes = attributed.filter((row) => row.category === 'TAXES');
+    const taxSum = (category, discountId) => sum(category === undefined ? taxes : taxes.filter((row) => row.baseCategory === category), undefined, discountId);
+    const categories = [
+        ...new Set(attributed.map((row) => (row.category === 'TAXES' ? row.baseCategory : row.category))),
+    ];
+    const discountIds = [...new Set(attributed.map((row) => row.discountId))].filter((discountId) => discountId !== undefined);
+    let roundingCategory = 'ROUNDING';
+    while (categories.includes(roundingCategory))
+        roundingCategory = `_${roundingCategory}`;
+    const scopes = [
+        ...categories.flatMap((category) => [
+            ...discountIds.map((discountId) => ({ category, discountId })),
+            { category, discountId: undefined },
+        ]),
+        ...discountIds.map((discountId) => ({ category: undefined, discountId })),
+        { category: undefined, discountId: undefined },
+    ];
+    const balances = scopes.map(({ category, discountId }) => ({
+        category,
+        discountId,
+        amount: sum(attributed, category, discountId) - taxSum(category, discountId),
+    }));
+    for (const { category, discountId, amount } of balances) {
+        const difference = amount - sum(converted, category, discountId);
+        if (!Number.isFinite(amount) || !Number.isFinite(difference)) {
+            throw new Error('Calculation contains an invalid balance');
+        }
+        if (difference) {
+            converted.push({
+                category: category ?? roundingCategory,
+                discountId,
+                amount: difference,
+                isNetPrice: true,
+                meta: { migration: 20260907120000, reason: 'Preserve historical floating-point balance' },
+            });
+        }
+    }
+    for (const { category, discountId, amount } of balances) {
+        if (sum(converted, category, discountId) !== amount) {
+            throw new Error(`Cannot preserve historical balance for ${category ?? 'order'} ${discountId ?? ''}`);
+        }
+    }
+    for (const discountId of discountIds) {
+        const before = sum(attributed, 'DISCOUNTS', discountId);
+        const after = sum(converted, 'DISCOUNTS', discountId) + taxSum('DISCOUNTS', discountId);
+        if (Math.round(before) !== Math.round(after) || Boolean(before) !== Boolean(after)) {
+            throw new Error(`Cannot preserve historical discount ${discountId}`);
+        }
+    }
+    return converted;
+};
+export default function migrateOrderCalculationToNet(repository) {
+    repository?.register({
+        id: 20260907120000,
+        name: 'Convert persisted order calculations from gross to net category balances',
+        up: async ({ logger }) => {
+            const Orders = await OrdersCollection(repository.db);
+            const projection = { _id: 1, calculation: 1 };
+            let migrated = 0;
+            for await (const order of Orders.find(legacyCalculationSelector, { projection })) {
+                let calculation;
+                try {
+                    calculation = convertOrderCalculationToNet(order.calculation);
+                }
+                catch (error) {
+                    throw new Error(`Cannot migrate order ${order._id}: ${error.message}`, { cause: error });
+                }
+                if (!calculation.some((row) => row.isNetPrice === true)) {
+                    calculation = calculation.map((row) => ({ ...row, isNetPrice: true }));
+                }
+                const result = await Orders.updateOne({ _id: order._id, calculation: order.calculation }, { $set: { calculation } });
+                if (result.matchedCount) {
+                    migrated += 1;
+                }
+                else if (await Orders.findOne({ _id: order._id, ...legacyCalculationSelector }, { projection })) {
+                    throw new Error(`Order ${order._id} changed during migration; retry after stopping old writers`);
+                }
+            }
+            logger?.info(`Converted ${migrated} order calculation(s) to net category balances`);
+        },
+    });
+}

package/lib/module/configureOrderDeliveriesModule.d.ts

@@ -8,6 +8,9 @@ export declare const configureOrderDeliveriesModule: ({ OrderDeliveries, }: {
     findDelivery: ({ orderDeliveryId }: {
         orderDeliveryId: string;
     }, options?: mongodb.FindOptions) => Promise<OrderDelivery | null>;
+    findDeliveries: ({ orderDeliveryIds }: {
+        orderDeliveryIds: string[];
+    }, options?: mongodb.FindOptions) => Promise<OrderDelivery[]>;
     findDeliveryByProvidersId: ({ deliveryProviderIds }: {
         deliveryProviderIds: string[];
     }, options?: mongodb.FindOptions) => Promise<OrderDelivery[]>;

package/lib/module/configureOrderDeliveriesModule.js

@@ -32,6 +32,11 @@ export const configureOrderDeliveriesModule = ({ OrderDeliveries, }) => {
         findDelivery: async ({ orderDeliveryId }, options) => {
             return OrderDeliveries.findOne(buildFindByIdSelector(orderDeliveryId), options);
         },
+        findDeliveries: async ({ orderDeliveryIds }, options) => {
+            if (!orderDeliveryIds?.length)
+                return [];
+            return OrderDeliveries.find({ _id: { $in: orderDeliveryIds } }, options).toArray();
+        },
         findDeliveryByProvidersId: async ({ deliveryProviderIds }, options) => {
             if (!deliveryProviderIds?.length)
                 return [];

package/lib/module/configureOrderDiscountsModule.d.ts

@@ -7,8 +7,10 @@ export declare const configureOrderDiscountsModule: ({ OrderDiscounts, }: {
     findOrderDiscount: ({ discountId }: {
         discountId: string;
     }, options?: mongodb.FindOptions) => Promise<OrderDiscount | null>;
-    findOrderDiscounts: ({ orderId }: {
+    findOrderDiscounts: (query: {
         orderId: string;
+    } | {
+        orderIds: string[];
     }) => Promise<OrderDiscount[]>;
     create: (doc: Omit<OrderDiscount, "_id" | "created" | "trigger"> & Pick<Partial<OrderDiscount>, "_id" | "created" | "trigger">) => Promise<OrderDiscount>;
     delete: (orderDiscountId: string) => Promise<mongodb.WithId<OrderDiscount> | null>;

package/lib/module/configureOrderDiscountsModule.js

@@ -13,7 +13,10 @@ export const configureOrderDiscountsModule = ({ OrderDiscounts, }) => {
         findOrderDiscount: async ({ discountId }, options) => {
             return OrderDiscounts.findOne(buildFindOrderDiscountByIdSelector(discountId), options);
         },
-        findOrderDiscounts: async ({ orderId }) => {
+        findOrderDiscounts: async (query) => {
+            if ('orderIds' in query && !query.orderIds.length)
+                return [];
+            const orderId = 'orderIds' in query ? { $in: query.orderIds } : query.orderId;
             const discounts = OrderDiscounts.find({ orderId }, { sort: { created: 1, _id: 1 } });
             return discounts.toArray();
         },

package/lib/module/configureOrderPaymentsModule.d.ts

@@ -8,6 +8,9 @@ export declare const configureOrderPaymentsModule: ({ OrderPayments, }: {
     findOrderPayment: ({ orderPaymentId, }: {
         orderPaymentId: string;
     }, options?: mongodb.FindOptions) => Promise<OrderPayment | null>;
+    findOrderPayments: ({ orderPaymentIds }: {
+        orderPaymentIds: string[];
+    }, options?: mongodb.FindOptions) => Promise<OrderPayment[]>;
     findOrderPaymentsByProviderIds: ({ paymentProviderIds, }: {
         paymentProviderIds: string[];
     }, options?: mongodb.FindOptions) => Promise<OrderPayment[]>;

package/lib/module/configureOrderPaymentsModule.js

@@ -35,6 +35,11 @@ export const configureOrderPaymentsModule = ({ OrderPayments, }) => {
         findOrderPayment: async ({ orderPaymentId, }, options) => {
             return OrderPayments.findOne(buildFindOrderPaymentByIdSelector(orderPaymentId), options);
         },
+        findOrderPayments: async ({ orderPaymentIds }, options) => {
+            if (!orderPaymentIds?.length)
+                return [];
+            return OrderPayments.find({ _id: { $in: orderPaymentIds } }, options).toArray();
+        },
         findOrderPaymentsByProviderIds: async ({ paymentProviderIds, }, options) => {
             if (!paymentProviderIds?.length)
                 return [];

package/lib/module/configureOrderPositionsModule.d.ts

@@ -23,8 +23,10 @@ export declare const configureOrderPositionsModule: ({ OrderPositions, }: {
     findOrderPosition: ({ itemId }: {
         itemId: string;
     }, options?: mongodb.FindOptions) => Promise<OrderPosition | null>;
-    findOrderPositions: ({ orderId }: {
+    findOrderPositions: (query: {
         orderId: string;
+    } | {
+        orderIds: string[];
     }) => Promise<OrderPosition[]>;
     delete: (orderPositionId: string) => Promise<mongodb.WithId<OrderPosition> | null>;
     removePositions: ({ orderId }: {

package/lib/module/configureOrderPositionsModule.js

@@ -13,7 +13,10 @@ export const configureOrderPositionsModule = ({ OrderPositions, }) => {
         findOrderPosition: async ({ itemId }, options) => {
             return OrderPositions.findOne(buildFindOrderPositionByIdSelector(itemId), options);
         },
-        findOrderPositions: async ({ orderId }) => {
+        findOrderPositions: async (query) => {
+            if ('orderIds' in query && !query.orderIds.length)
+                return [];
+            const orderId = 'orderIds' in query ? { $in: query.orderIds } : query.orderId;
             const positions = OrderPositions.find({ orderId, quantity: { $gt: 0 } }, { sort: { created: 1, _id: 1 } });
             return positions.toArray();
         },

package/lib/module/configureOrdersModule-queries.js

@@ -66,6 +66,7 @@ export const configureOrdersModuleQueries = ({ Orders }) => {
             const selector = buildFindSelector({ queryString, ...query });
             if (queryString) {
                 return Orders.find(selector, {
+                    ...findOptions,
                     ...options,
                     projection: { score: { $meta: 'textScore' } },
                     sort: { score: { $meta: 'textScore' } },
@@ -160,19 +161,26 @@ export const configureOrdersModuleQueries = ({ Orders }) => {
                             created: 1,
                             currencyCode: 1,
                             itemAmount: {
-                                $let: {
-                                    vars: {
-                                        item: {
-                                            $first: {
-                                                $filter: {
-                                                    input: '$calculation',
-                                                    as: 'c',
-                                                    cond: { $eq: ['$$c.category', 'ITEMS'] },
-                                                },
+                                $reduce: {
+                                    input: {
+                                        $filter: {
+                                            input: { $ifNull: ['$calculation', []] },
+                                            as: 'c',
+                                            cond: {
+                                                $or: [
+                                                    { $eq: ['$$c.category', 'ITEMS'] },
+                                                    {
+                                                        $and: [
+                                                            { $eq: ['$$c.category', 'TAXES'] },
+                                                            { $eq: ['$$c.baseCategory', 'ITEMS'] },
+                                                        ],
+                                                    },
+                                                ],
                                             },
                                         },
                                     },
-                                    in: '$$item.amount',
+                                    initialValue: 0,
+                                    in: { $add: ['$$value', { $ifNull: ['$$this.amount', 0] }] },
                                 },
                             },
                         },

package/lib/module/configureOrdersModule.d.ts

@@ -6,6 +6,9 @@ export declare const configureOrdersModule: ({ db, migrationRepository, options:
         findDelivery: ({ orderDeliveryId }: {
             orderDeliveryId: string;
         }, options?: mongodb.FindOptions) => Promise<import("../db/OrderDeliveriesCollection.ts").OrderDelivery | null>;
+        findDeliveries: ({ orderDeliveryIds }: {
+            orderDeliveryIds: string[];
+        }, options?: mongodb.FindOptions) => Promise<import("../db/OrderDeliveriesCollection.ts").OrderDelivery[]>;
         findDeliveryByProvidersId: ({ deliveryProviderIds }: {
             deliveryProviderIds: string[];
         }, options?: mongodb.FindOptions) => Promise<import("../db/OrderDeliveriesCollection.ts").OrderDelivery[]>;
@@ -25,8 +28,10 @@ export declare const configureOrdersModule: ({ db, migrationRepository, options:
         findOrderDiscount: ({ discountId }: {
             discountId: string;
         }, options?: mongodb.FindOptions) => Promise<import("../db/OrderDiscountsCollection.ts").OrderDiscount | null>;
-        findOrderDiscounts: ({ orderId }: {
+        findOrderDiscounts: (query: {
             orderId: string;
+        } | {
+            orderIds: string[];
         }) => Promise<import("../db/OrderDiscountsCollection.ts").OrderDiscount[]>;
         create: (doc: Omit<import("../db/OrderDiscountsCollection.ts").OrderDiscount, "_id" | "created" | "trigger"> & Pick<Partial<import("../db/OrderDiscountsCollection.ts").OrderDiscount>, "_id" | "created" | "trigger">) => Promise<import("../db/OrderDiscountsCollection.ts").OrderDiscount>;
         delete: (orderDiscountId: string) => Promise<mongodb.WithId<import("../db/OrderDiscountsCollection.ts").OrderDiscount> | null>;
@@ -44,8 +49,10 @@ export declare const configureOrdersModule: ({ db, migrationRepository, options:
         findOrderPosition: ({ itemId }: {
             itemId: string;
         }, options?: mongodb.FindOptions) => Promise<import("../db/OrderPositionsCollection.ts").OrderPosition | null>;
-        findOrderPositions: ({ orderId }: {
+        findOrderPositions: (query: {
             orderId: string;
+        } | {
+            orderIds: string[];
         }) => Promise<import("../db/OrderPositionsCollection.ts").OrderPosition[]>;
         delete: (orderPositionId: string) => Promise<mongodb.WithId<import("../db/OrderPositionsCollection.ts").OrderPosition> | null>;
         removePositions: ({ orderId }: {
@@ -84,6 +91,9 @@ export declare const configureOrdersModule: ({ db, migrationRepository, options:
         findOrderPayment: ({ orderPaymentId, }: {
             orderPaymentId: string;
         }, options?: mongodb.FindOptions) => Promise<import("../db/OrderPaymentsCollection.ts").OrderPayment | null>;
+        findOrderPayments: ({ orderPaymentIds }: {
+            orderPaymentIds: string[];
+        }, options?: mongodb.FindOptions) => Promise<import("../db/OrderPaymentsCollection.ts").OrderPayment[]>;
         findOrderPaymentsByProviderIds: ({ paymentProviderIds, }: {
             paymentProviderIds: string[];
         }, options?: mongodb.FindOptions) => Promise<import("../db/OrderPaymentsCollection.ts").OrderPayment[]>;

package/lib/module/configureOrdersModule.js

@@ -15,6 +15,7 @@ import { configureOrdersModuleQueries } from "./configureOrdersModule-queries.js
 import { emit, registerEvents } from '@unchainedshop/events';
 import renameCurrencyCode from "../migrations/20250502111800-currency-code.js";
 import normalizeOrderContactPhone from "../migrations/20260625120000-normalize-contact-phone.js";
+import migrateOrderCalculationToNet from "../migrations/20260907120000-order-calculation-net.js";
 const ORDER_EVENTS = [
     'ORDER_CHECKOUT',
     'ORDER_CONFIRMED',
@@ -24,6 +25,7 @@ const ORDER_EVENTS = [
 export const configureOrdersModule = async ({ db, migrationRepository, options: orderOptions = {}, }) => {
     renameCurrencyCode(migrationRepository);
     normalizeOrderContactPhone(migrationRepository);
+    migrateOrderCalculationToNet(migrationRepository);
     registerEvents(ORDER_EVENTS);
     ordersSettings.configureSettings(orderOptions);
     const Orders = await OrdersCollection(db);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unchainedshop/core-orders",
   "description": "Order management module for the Unchained Engine",
-  "version": "5.0.0-alpha.4",
+  "version": "5.0.0-alpha.7",
   "main": "lib/orders-index.js",
   "types": "lib/orders-index.d.ts",
   "type": "module",
@@ -35,9 +35,9 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/events": "^5.0.0-alpha.1",
-    "@unchainedshop/mongodb": "^5.0.0-alpha.1",
-    "@unchainedshop/utils": "^5.0.0-alpha.1"
+    "@unchainedshop/events": "^5.0.0-alpha.7",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.7",
+    "@unchainedshop/utils": "^5.0.0-alpha.7"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",