@evershop/evershop 2.1.1 → 2.1.2

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

@@ -0,0 +1,26 @@
+import { insert, Pool, PoolClient } from '../../../lib/postgres/query.js';
+import { PaymentTransactionRow } from '../../../types/db/index.js';
+
+export async function addPaymentTransaction(
+  connection: Pool | PoolClient,
+  orderId: number,
+  amount: number,
+  transactionId: string | number,
+  transactionType: string,
+  paymentAction: string,
+  additionalInformation?: string,
+  parentTransactionId?: string | number
+): Promise<PaymentTransactionRow> {
+  const transaction = await insert('payment_transaction')
+    .given({
+      payment_transaction_order_id: orderId,
+      amount,
+      transaction_id: transactionId,
+      transaction_type: transactionType,
+      payment_action: paymentAction,
+      additional_information: additionalInformation,
+      parent_transaction_id: parentTransactionId
+    })
+    .execute(connection);
+  return transaction;
+}

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

@@ -10,7 +10,7 @@ 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, ShipmentStatus } from '../../../types/order.js';
 import addOrderActivityLog from './addOrderActivityLog.js';
 import { updatePaymentStatus } from './updatePaymentStatus.js';
@@ -120,3 +120,133 @@ async function cancelOrder(uuid: string, reason: string | undefined) {
 export default async (uuid: string, reason: string | undefined) => {
   await hookable(cancelOrder, { uuid })(uuid, reason);
 };
+
+export function hookBeforeValidateStatus(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    paymentStatus: string,
+    shipmentStatus: string
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('validateStatus', callback, priority);
+}
+
+export function hookAfterValidateStatus(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    paymentStatus: string,
+    shipmentStatus: string
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('validateStatus', callback, priority);
+}
+
+export function hookBeforeUpdatePaymentStatusToCancel(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    orderID: number,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('updatePaymentStatusToCancel', callback, priority);
+}
+
+export function hookAfterUpdatePaymentStatusToCancel(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    orderID: number,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('updatePaymentStatusToCancel', callback, priority);
+}
+
+export function hookBeforeUpdateShipmentStatusToCancel(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    orderID: number,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('updateShipmentStatusToCancel', callback, priority);
+}
+
+export function hookAfterUpdateShipmentStatusToCancel(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    orderID: number,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('updateShipmentStatusToCancel', callback, priority);
+}
+
+export function hookBeforeReStockAfterCancel(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    orderID: number,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('reStockAfterCancel', callback, priority);
+}
+
+export function hookAfterReStockAfterCancel(
+  callback: (
+    this: { order: Record<string, any> },
+    ...args: [
+    orderID: number,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('reStockAfterCancel', callback, priority);
+}
+
+export function hookBeforeCancelOrder(
+  callback: (
+    this: { uuid: string },
+    ...args: [
+    uuid: string,
+    reason: string | undefined
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('cancelOrder', callback, priority);
+}
+
+export function hookAfterCancelOrder(
+  callback: (
+    this: { uuid: string },
+    ...args: [
+    uuid: string,
+    reason: string | undefined
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('cancelOrder', callback, priority);
+}

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

@@ -7,7 +7,7 @@ import {
 } from '@evershop/postgres-query-builder';
 import { PoolClient } from 'pg';
 import { getConnection } from '../../../lib/postgres/connection.js';
-import { hookable } from '../../../lib/util/hookable.js';
+import { hookable, hookBefore, hookAfter } from '../../../lib/util/hookable.js';
 import addOrderActivityLog from './addOrderActivityLog.js';
 import { updateShipmentStatus } from './updateShipmentStatus.js';
 
@@ -89,3 +89,33 @@ export default async (
     throw e;
   }
 };
+
+export function hookBeforeCreateShipment(
+  callback: (
+    this: { order: Record<string, any>; carrier: string | null; trackingNumber: string | null },
+    ...args: [
+    orderId: number,
+    carrier: string | null,
+    trackingNumber: string | null,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookBefore('createShipment', callback, priority);
+}
+
+export function hookAfterCreateShipment(
+  callback: (
+    this: { order: Record<string, any>; carrier: string | null; trackingNumber: string | null },
+    ...args: [
+    orderId: number,
+    carrier: string | null,
+    trackingNumber: string | null,
+    connection: PoolClient
+    ]
+  ) => void | Promise<void>,
+  priority: number = 10
+): void {
+  hookAfter('createShipment', callback, priority);
+}

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

@@ -3,4 +3,8 @@ import cancelOrder from './cancelOrder.js';
 import createShipment from './createShipment.js';
 export * from './updatePaymentStatus.js';
 export * from './updateShipmentStatus.js';
+export * from './orderLoader.js';
+export * from './addPaymentTransaction.js';
+export * from './statusManager.js';
+export * from './updateOrderStatus.js';
 export { cancelOrder, addOrderActivityLog, createShipment };

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

@@ -0,0 +1,73 @@
+import { pool } from '../../../lib/postgres/connection.js';
+import { select } from '../../../lib/postgres/query.js';
+import {
+  OrderAddressRow,
+  OrderItemRow,
+  OrderRow
+} from '../../../types/db/index.js';
+
+export type OrderDetails = OrderRow & {
+  items: OrderItemRow[];
+  shippingAddress: OrderAddressRow | null;
+  billingAddress: OrderAddressRow | null;
+};
+
+export async function loadOrderById(
+  orderId: number
+): Promise<OrderDetails | null> {
+  const order = (await select()
+    .from('order')
+    .where('order_id', '=', orderId)
+    .load(pool)) as OrderRow | null;
+  if (!order) {
+    return null;
+  }
+  const items = (await select()
+    .from('order_item')
+    .where('order_item_order_id', '=', orderId)
+    .execute(pool)) as OrderItemRow[];
+  const shippingAddress = (await select()
+    .from('order_address')
+    .where('order_address_id', '=', order.shipping_address_id)
+    .load(pool)) as OrderAddressRow | null;
+  const billingAddress = (await select()
+    .from('order_address')
+    .where('order_address_id', '=', order.billing_address_id)
+    .load(pool)) as OrderAddressRow | null;
+  return {
+    ...order,
+    items,
+    shippingAddress,
+    billingAddress
+  };
+}
+
+export async function loadOrderByUUID(
+  orderUUID: string
+): Promise<OrderDetails | null> {
+  const order = (await select()
+    .from('order')
+    .where('uuid', '=', orderUUID)
+    .load(pool)) as OrderRow | null;
+  if (!order) {
+    return null;
+  }
+  const items = (await select()
+    .from('order_item')
+    .where('order_item_order_id', '=', order.order_id)
+    .execute(pool)) as OrderItemRow[];
+  const shippingAddress = (await select()
+    .from('order_address')
+    .where('order_address_id', '=', order.shipping_address_id)
+    .load(pool)) as OrderAddressRow | null;
+  const billingAddress = (await select()
+    .from('order_address')
+    .where('order_address_id', '=', order.billing_address_id)
+    .load(pool)) as OrderAddressRow | null;
+  return {
+    ...order,
+    items,
+    shippingAddress,
+    billingAddress
+  };
+}

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() {
@@ -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,7 +9,7 @@ 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 {
@@ -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);
+}