@evershop/evershop 2.1.0 → 2.1.2

package/src/modules/oms/services/statusManager.ts

@@ -0,0 +1,159 @@
+import config from 'config';
+import { getConfig } from '../../../lib/util/getConfig.js';
+import { addProcessor } from '../../../lib/util/registry.js';
+import {
+  OrderStatus,
+  PaymentStatus,
+  ShipmentStatus
+} from '../../../types/order.js';
+
+/**
+ * Retrieves the list of order statuses defined in the system. The statuses are defined in the configuration under `oms.order.status`. Each status includes details such as its name, badge, whether it's the default status, and possible next statuses.
+ * @returns A record of order statuses, where the key is the status ID and the value is an object containing the status details.
+ */
+function getOrderStatusList(): Record<string, OrderStatus> {
+  const statuses = getConfig('oms.order.status', {}) as Record<
+    string,
+    OrderStatus
+  >;
+  return statuses;
+}
+
+/**
+ * Retrieves the list of shipment statuses defined in the system. The statuses are defined in the configuration under `oms.order.shipmentStatus`. Each status includes details such as its name, badge, whether it's the default status, and whether it's cancelable.
+ * @returns A record of shipment statuses, where the key is the status ID and the value is an object containing the status details.
+ */
+function getShipmentStatusList() {
+  const statuses = getConfig('oms.order.shipmentStatus', {}) as Record<
+    string,
+    {
+      name: string;
+      badge: string;
+      progress?: string;
+      isDefault?: boolean;
+      isCancelable?: boolean;
+    }
+  >;
+  return statuses;
+}
+
+/**
+ * Retrieves the list of payment statuses defined in the system. The statuses are defined in the configuration under `oms.order.paymentStatus`. Each status includes details such as its name, badge, whether it's the default status, and whether it's cancelable.
+ * @returns A record of payment statuses, where the key is the status ID and the value is an object containing the status details.
+ */
+function getPaymentStatusList() {
+  const statuses = getConfig('oms.order.paymentStatus', {}) as Record<
+    string,
+    {
+      name: string;
+      badge: string;
+      isDefault?: boolean;
+      isCancelable?: boolean;
+    }
+  >;
+  return statuses;
+}
+
+/**
+ * Registers a new payment status in the system. This function must be called during the application initialization phase (e.g., in a module's `bootstrap` function).
+ * @param id Unique identifier for the payment status (e.g., "paid", "pending")
+ * @param detail Object containing details about the payment status (name, badge, etc.)
+ * @param psoMapping Optional mapping of payment status to order status (e.g., { "paid": "processing" })
+ */
+function registerPaymentStatus(
+  id: string,
+  detail: PaymentStatus,
+  psoMapping?: Record<string, string>
+) {
+  // Make sure ID is not empty and does not contain spaces
+  if (!id || /\s/.test(id)) {
+    throw new Error(
+      'Payment status ID must be a non-empty string without spaces.'
+    );
+  }
+  const statusConfig = {
+    order: {
+      paymentStatus: {
+        [id]: detail
+      },
+      psoMapping: psoMapping
+    }
+  };
+  config.util.setModuleDefaults('oms', statusConfig);
+}
+
+/**
+ * Registers a new shipment status in the system. This function must be called during the application initialization phase (e.g., in a module's `bootstrap` function).
+ * @param id Unique identifier for the shipment status (e.g., "shipped", "delivered")
+ * @param detail Object containing details about the shipment status (name, badge, etc.)
+ * @param psoMapping Optional mapping of shipment status to order status (e.g., { "shipped": "processing" })
+ */
+function registerShipmentStatus(
+  id: string,
+  detail: ShipmentStatus,
+  psoMapping?: Record<string, string>
+) {
+  // Make sure ID is not empty and does not contain spaces
+  if (!id || /\s/.test(id)) {
+    throw new Error(
+      'Shipment status ID must be a non-empty string without spaces.'
+    );
+  }
+  const statusConfig = {
+    order: {
+      shipmentStatus: {
+        [id]: detail
+      },
+      psoMapping: psoMapping
+    }
+  };
+  config.util.setModuleDefaults('oms', statusConfig);
+}
+
+/**
+ * Registers a new order status in the system. This function must be called during the application initialization phase (e.g., in a module's `bootstrap` function).
+ * @param id Unique identifier for the order status (e.g., "processing", "completed")
+ * @param detail Object containing details about the order status (name, badge, next statuses, etc.)
+ */
+function registerOrderStatus(id: string, detail: OrderStatus) {
+  // Make sure ID is not empty and does not contain spaces
+  if (!id || /\s/.test(id)) {
+    throw new Error(
+      'Order status ID must be a non-empty string without spaces.'
+    );
+  }
+  const statusConfig = {
+    order: {
+      status: {
+        [id]: { ...detail }
+      }
+    }
+  };
+  config.util.setModuleDefaults('oms', statusConfig);
+}
+
+/** Registers a mapping of payment status and shipment status to order status. This function must be called during the application initialization phase (e.g., in a module's `bootstrap` function).
+ * @param paymentStatus Payment status ID or "*" to match any payment status
+ * @param shipmentStatus Shipment status ID or "*" to match any shipment status
+ * @param orderStatus Order status ID to map to when the payment status and shipment status match the provided values
+ */
+function registerPSOStatusMapping(
+  paymentStatus: string | '*',
+  shipmentStatus: string | '*',
+  orderStatus: string
+) {
+  addProcessor('psoMapping', async (mapping: Record<string, string>) => {
+    mapping[`${paymentStatus}:${shipmentStatus}`] = orderStatus;
+    return mapping;
+  });
+}
+
+export {
+  getOrderStatusList,
+  getShipmentStatusList,
+  getPaymentStatusList,
+  registerPaymentStatus,
+  registerShipmentStatus,
+  registerOrderStatus,
+  registerPSOStatusMapping
+};

package/src/modules/oms/services/updateOrderStatus.ts

@@ -15,7 +15,9 @@ import Topo from '@hapi/topo';
 import { error } from '../../../lib/log/logger.js';
 import { pool } from '../../../lib/postgres/connection.js';
 import { getConfig } from '../../../lib/util/getConfig.js';
-import { hookable } from '../../../lib/util/hookable.js';
+import { hookable, hookAfter, hookBefore } from '../../../lib/util/hookable.js';
+import { getValueSync } from '../../../lib/util/registry.js';
+import { OrderRow } from '../../../types/db/index.js';
 import { PaymentStatus, ShipmentStatus } from '../../../types/order.js';
 
 function getOrderStatusFlow() {
@@ -45,11 +47,11 @@ export function resolveOrderStatus(
   const shipmentStatusList = getConfig(
     'oms.order.shipmentStatus',
     {}
-  ) as ShipmentStatus[];
-  const paymentStatusList = getConfig(
-    'oms.order.paymentStatus',
-    {}
-  ) as PaymentStatus[];
+  ) as Record<string, ShipmentStatus>;
+  const paymentStatusList = getConfig('oms.order.paymentStatus', {}) as Record<
+    string,
+    PaymentStatus
+  >;
   const psoMapping = getConfig('oms.order.psoMapping', {});
   const shipmentStatusDefination = shipmentStatusList[shipmentStatus];
   const paymentStatusDefination = paymentStatusList[paymentStatus];
@@ -58,12 +60,13 @@ export function resolveOrderStatus(
       'Either shipment status or payment status is invalid. Can not update order status'
     );
   }
+  const finalPsoMapping = getValueSync('psoMapping', psoMapping, {});
   // Reverse the order status list to get the highest priority status first
   const nextStatus =
-    psoMapping[`${paymentStatus}:${shipmentStatus}`] ||
-    psoMapping[`*:${shipmentStatus}`] ||
-    psoMapping[`${paymentStatus}:*`] ||
-    psoMapping['*:*'];
+    finalPsoMapping[`${paymentStatus}:${shipmentStatus}`] ||
+    finalPsoMapping[`*:${shipmentStatus}`] ||
+    finalPsoMapping[`${paymentStatus}:*`] ||
+    finalPsoMapping['*:*'];
   if (!nextStatus || !orderStatusList[nextStatus]) {
     throw new Error(
       'Can not found a valid order status from the current shipment and payment status'
@@ -72,6 +75,14 @@ export function resolveOrderStatus(
   return nextStatus;
 }
 
+/**
+ * This function means to be private and should not be called outside of this module. It will not perform any validation and directly update the order status.
+ * You should consider updating the payment status and shipment status only, and let the system to update the order status automatically.
+ *
+ * @param orderId
+ * @param status
+ * @param connection
+ */
 async function updateOrderStatus(
   orderId: number,
   status: string,
@@ -95,7 +106,7 @@ async function addOrderStatusChangeEvents(
     .given({
       name: 'order_status_updated',
       data: {
-        order_id: orderId,
+        orderId: orderId,
         before,
         after
       }
@@ -110,13 +121,17 @@ export async function changeOrderStatus(
 ) {
   const statusFlow = getOrderStatusFlow();
   const connection = conn || (await getConnection(pool));
-  const order = await select()
+  const order = (await select()
     .from('order')
     .where('order_id', '=', orderId)
-    .load(connection, false);
+    .load(connection, false)) as OrderRow | null;
   if (!order) {
     throw new Error('Order not found');
   }
+
+  if (order.status === status) {
+    return;
+  }
   // Do not allow to revert the status
   if (statusFlow.indexOf(order.status) > statusFlow.indexOf(status)) {
     throw new Error('Can not revert the status of the order');
@@ -135,7 +150,12 @@ export async function changeOrderStatus(
     await hookable(addOrderStatusChangeEvents, {
       order,
       status
-    })(order.order_id, order.status.toString(), status, connection);
+    })(
+      order.order_id,
+      order.status ? order.status.toString() : 'unknown',
+      status,
+      connection
+    );
 
     if (!conn) {
       await commit(connection);
@@ -148,3 +168,75 @@ export async function changeOrderStatus(
     throw err;
   }
 }
+
+export function hookBeforeUpdateOrderStatus(
+  callback: (
+    this: {
+      order: OrderRow;
+      status: string;
+    },
+    ...args: [
+      orderId: number,
+      status: string,
+      connection: PoolClient,
+      ...args: any[]
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('updateOrderStatus', callback, priority);
+}
+
+export function hookAfterUpdateOrderStatus(
+  callback: (
+    this: {
+      order: OrderRow;
+      status: string;
+    },
+    ...args: [
+      orderId: number,
+      status: string,
+      connection: PoolClient,
+      ...args: any[]
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('updateOrderStatus', callback, priority);
+}
+
+export function hookBeforeAddOrderStatusChangeEvents(
+  callback: (
+    this: {
+      order: OrderRow;
+      status: string;
+    },
+    ...args: [
+      orderId: number,
+      before: string,
+      after: string,
+      connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('addOrderStatusChangeEvents', callback, priority);
+}
+
+export function hookAfterAddOrderStatusChangeEvents(
+  callback: (
+    this: {
+      order: OrderRow;
+      status: string;
+    },
+    ...args: [
+      orderId: number,
+      before: string,
+      after: string,
+      connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('addOrderStatusChangeEvents', callback, priority);
+}

package/src/modules/oms/services/updatePaymentStatus.ts

@@ -9,14 +9,14 @@ import {
 import { error } from '../../../lib/log/logger.js';
 import { pool } from '../../../lib/postgres/connection.js';
 import { getConfig } from '../../../lib/util/getConfig.js';
-import { hookable } from '../../../lib/util/hookable.js';
+import { hookable, hookBefore, hookAfter } from '../../../lib/util/hookable.js';
 import { PaymentStatus } from '../../../types/order.js';
 
 function validatePaymentStatusBeforeUpdate(status: string): boolean {
-  const paymentStatusList = getConfig(
-    'oms.order.paymentStatus',
-    {}
-  ) as PaymentStatus[];
+  const paymentStatusList = getConfig('oms.order.paymentStatus', {}) as Record<
+    string,
+    PaymentStatus
+  >;
   if (!paymentStatusList[status]) {
     throw new Error('Invalid status');
   }
@@ -64,3 +64,55 @@ export const updatePaymentStatus = async (
     throw err;
   }
 };
+
+export function hookBeforeValidatePaymentStatusBeforeUpdate(
+  callback: (
+    this: { orderId: number },
+    ...args: [
+    status: string
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('validatePaymentStatusBeforeUpdate', callback, priority);
+}
+
+export function hookAfterValidatePaymentStatusBeforeUpdate(
+  callback: (
+    this: { orderId: number },
+    ...args: [
+    status: string
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('validatePaymentStatusBeforeUpdate', callback, priority);
+}
+
+export function hookBeforeChangePaymentStatus(
+  callback: (
+    this: { orderId: number; status: string },
+    ...args: [
+    orderId: number,
+    status: string,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('changePaymentStatus', callback, priority);
+}
+
+export function hookAfterChangePaymentStatus(
+  callback: (
+    this: { orderId: number; status: string },
+    ...args: [
+    orderId: number,
+    status: string,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('changePaymentStatus', callback, priority);
+}

package/src/modules/oms/services/updateShipmentStatus.ts

@@ -9,14 +9,14 @@ import {
 import { error } from '../../../lib/log/logger.js';
 import { pool } from '../../../lib/postgres/connection.js';
 import { getConfig } from '../../../lib/util/getConfig.js';
-import { hookable } from '../../../lib/util/hookable.js';
+import { hookable, hookBefore, hookAfter } from '../../../lib/util/hookable.js';
 import { ShipmentStatus } from '../../../types/order.js';
 
 function validateShipmentStatusBeforeUpdate(status: string): boolean {
   const shipmentStatusList = getConfig(
     'oms.order.shipmentStatus',
     {}
-  ) as ShipmentStatus;
+  ) as Record<string, ShipmentStatus>;
   if (!shipmentStatusList[status]) {
     throw new Error('Invalid status');
   }
@@ -63,3 +63,55 @@ export const updateShipmentStatus = async (
     throw err;
   }
 };
+
+export function hookBeforeValidateShipmentStatusBeforeUpdate(
+  callback: (
+    this: { orderId: number },
+    ...args: [
+    status: string
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('validateShipmentStatusBeforeUpdate', callback, priority);
+}
+
+export function hookAfterValidateShipmentStatusBeforeUpdate(
+  callback: (
+    this: { orderId: number },
+    ...args: [
+    status: string
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('validateShipmentStatusBeforeUpdate', callback, priority);
+}
+
+export function hookBeforeChangeShipmentStatus(
+  callback: (
+    this: { orderId: number; status: string },
+    ...args: [
+    orderId: number,
+    status: string,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('changeShipmentStatus', callback, priority);
+}
+
+export function hookAfterChangeShipmentStatus(
+  callback: (
+    this: { orderId: number; status: string },
+    ...args: [
+    orderId: number,
+    status: string,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('changeShipmentStatus', callback, priority);
+}