@unchainedshop/api 4.0.0-rc.10 → 4.0.0-rc.12

package/src/mcp/tools/order/getTopSellingProductsHandler.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { OrderStatus } from '@unchainedshop/core-orders';
+import { resolveDateRange } from '../../utils/orderFilters.js';
+
+export const TopSellingProductsSchema = {
+  from: z.string().datetime().optional().describe('Start date (ISO format)'),
+  to: z.string().datetime().optional().describe('End date (ISO format)'),
+  limit: z.number().int().min(1).max(100).optional().default(10),
+};
+
+export const TopSellingProductsZodSchema = z.object(TopSellingProductsSchema);
+export type TopSellingProductsParams = z.infer<typeof TopSellingProductsZodSchema>;
+
+export async function getTopSellingProductsHandler(context: Context, params: TopSellingProductsParams) {
+  const { modules, userId } = context;
+  const { from, to, limit } = params;
+
+  try {
+    log('handler getTopSellingProductsHandler', { userId, params });
+
+    const match: any = {};
+
+    const { startDate, endDate } = resolveDateRange(from, to);
+
+    const orders = await modules.orders.findOrders(
+      {
+        status: [OrderStatus.CONFIRMED, OrderStatus.FULLFILLED],
+        dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+      },
+      {
+        projection: {
+          _id: 1,
+        },
+      },
+    );
+    const orderIds = orders.map(({ _id }) => _id);
+
+    if (startDate) match.created = { ...(match.created || {}), $gte: startDate };
+    if (endDate) match.created = { ...(match.created || {}), $lte: endDate };
+    if (orderIds?.length) match.orderId = { $in: orderIds };
+
+    const topProducts = await modules.orders.positions.aggregatePositions({
+      match,
+      project: {
+        productId: 1,
+        quantity: 1,
+        itemAmount: {
+          $let: {
+            vars: {
+              item: {
+                $first: {
+                  $filter: {
+                    input: '$calculation',
+                    as: 'c',
+                    cond: { $eq: ['$$c.category', 'ITEM'] },
+                  },
+                },
+              },
+            },
+            in: '$$item.amount',
+          },
+        },
+      },
+      group: {
+        _id: '$productId',
+        totalSold: { $sum: '$quantity' },
+        totalRevenue: { $sum: '$itemAmount' },
+      },
+      sort: { totalSold: -1 },
+      limit,
+    });
+
+    const normalizedTopSellingProducts = await Promise.all(
+      topProducts.map(async (p) => {
+        const product = await getNormalizedProductDetails(p._id, context);
+        return {
+          productId: p._id?.toString?.() ?? null,
+          product,
+          totalSold: p.totalSold,
+          totalRevenue: p.totalRevenue,
+        };
+      }),
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            products: normalizedTopSellingProducts,
+            dateRange: {
+              start: from ? new Date(from).toISOString() : null,
+              end: to ? new Date(to).toISOString() : null,
+            },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching top-selling products: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/order/index.ts

@@ -0,0 +1,50 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import { ordersListHandler, OrdersListSchema } from './ordersListHandler.js';
+import { getSalesSummaryHandler, SalesSummarySchema } from './getSalesSummaryHandler.js';
+import {
+  getMonthlySalesBreakdownHandler,
+  MonthlySalesBreakdownSchema,
+} from './getMonthlySalesBreakdownHandler.js';
+import { getTopCustomersHandler, GetTopCustomersSchema } from './getTopCustomersHandler.js';
+import {
+  getTopSellingProductsHandler,
+  TopSellingProductsSchema,
+} from './getTopSellingProductsHandler.js';
+
+export const registerOrderTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'orders_list',
+    'Get all orders, filtered and sorted. Supports pagination, status filters, provider types, and date range.',
+    OrdersListSchema,
+    async (params) => ordersListHandler(context, params),
+  );
+
+  server.tool(
+    'ordersSales_summary',
+    'Get aggregate sales analytics including total revenue, order count, average order value, and daily breakdown over a time range.',
+    SalesSummarySchema,
+    async (params) => getSalesSummaryHandler(context, params),
+  );
+
+  server.tool(
+    'ordersSales_monthlyBreakdown',
+    'Break down total sales by month. Supports filtering by status and provider IDs, with optional custom date range.',
+    MonthlySalesBreakdownSchema,
+    async (params) => getMonthlySalesBreakdownHandler(context, params),
+  );
+
+  server.tool(
+    'orders_topCustomers',
+    'Get top customers by total amount spent, with optional date and status filters.',
+    GetTopCustomersSchema,
+    async (params) => getTopCustomersHandler(context, params),
+  );
+
+  server.tool(
+    'topSelling_products',
+    'Get top-selling products by quantity and revenue within an optional date range.',
+    TopSellingProductsSchema,
+    (params) => getTopSellingProductsHandler(context, params),
+  );
+};

package/src/mcp/tools/order/ordersListHandler.ts

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { PaymentProviderType } from '@unchainedshop/core-payment';
+import { DeliveryProviderType } from '@unchainedshop/core-delivery';
+import { resolveOrderFilters } from '../../utils/orderFilters.js';
+
+const OrderStatusEnum = z.enum(['PENDING', 'CONFIRMED', 'SHIPPED', 'DELIVERED', 'CANCELLED']);
+const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
+const DeliveryProviderTypeEnum = z.enum(['PICKUP', 'SHIPPING', 'LOCAL']);
+const SortDirectionEnum = z.enum(['ASC', 'DESC']);
+
+const SortOptionInput = z.object({
+  key: z.string().min(1).describe('Field to sort by'),
+  value: SortDirectionEnum.describe('Sort direction'),
+});
+
+const DateFilterInput = z.object({
+  from: z.string().datetime().optional().describe('Start date (ISO format)'),
+  to: z.string().datetime().optional().describe('End date (ISO format)'),
+});
+
+export const OrdersListSchema = {
+  limit: z.number().int().min(1).max(100).default(10),
+  offset: z.number().int().min(0).default(0),
+  includeCarts: z.boolean().default(false),
+  queryString: z.string().optional(),
+  status: z.array(OrderStatusEnum).optional(),
+  sort: z.array(SortOptionInput).optional(),
+  paymentProviderTypes: z.array(PaymentProviderTypeEnum).optional(),
+  deliveryProviderTypes: z.array(DeliveryProviderTypeEnum).optional(),
+  paymentProviderIds: z.array(z.string().min(1)).optional(),
+  deliveryProviderIds: z.array(z.string().min(1)).optional(),
+  dateRange: DateFilterInput.optional(),
+};
+
+export const OrdersListZodSchema = z.object(OrdersListSchema);
+export type OrdersListParams = z.infer<typeof OrdersListZodSchema>;
+
+export async function ordersListHandler(context: Context, params: OrdersListParams) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler ordersListHandler', { userId, params });
+
+    const {
+      paymentProviderTypes,
+      deliveryProviderTypes,
+      paymentProviderIds = [],
+      deliveryProviderIds = [],
+      ...restParams
+    } = params;
+
+    const resolvedPaymentProviderIds = new Set(paymentProviderIds);
+    const resolvedDeliveryProviderIds = new Set(deliveryProviderIds);
+
+    const lookups: Promise<void>[] = [];
+
+    if (paymentProviderTypes?.length) {
+      lookups.push(
+        modules.payment.paymentProviders
+          .findProviders({ type: { $in: paymentProviderTypes as PaymentProviderType[] } })
+          .then((providers) => {
+            providers.forEach((p) => resolvedPaymentProviderIds.add(p._id));
+          }),
+      );
+    }
+
+    if (deliveryProviderTypes?.length) {
+      lookups.push(
+        modules.delivery
+          .findProviders({ type: { $in: deliveryProviderTypes as DeliveryProviderType[] } })
+          .then((providers) => {
+            providers.forEach((p) => resolvedDeliveryProviderIds.add(p._id));
+          }),
+      );
+    }
+
+    await Promise.all(lookups);
+
+    const filters = await resolveOrderFilters(modules, {
+      paymentProviderIds: [...resolvedPaymentProviderIds],
+      deliveryProviderIds: [...resolvedDeliveryProviderIds],
+    });
+
+    if (!filters) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({ orders: [] }),
+          },
+        ],
+      };
+    }
+    const orders = await modules.orders.findOrders({
+      ...restParams,
+      ...filters,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ orders }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching orders: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/payment/createPaymentProviderHandler.ts

@@ -9,7 +9,12 @@ const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
 export const CreatePaymentProviderSchema = {
   paymentProvider: z.object({
     type: PaymentProviderTypeEnum.describe('Type of payment provider'),
-    adapterKey: z.string().min(1).describe('Adapter key for the payment provider'),
+    adapterKey: z
+      .string()
+      .min(1)
+      .describe(
+        'Adapter key for the payment provider, this value should be a valid adapter key found in payment provider interfaces',
+      ),
   }),
 };
 
@@ -38,7 +43,7 @@ export async function createPaymentProviderHandler(
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ paymentProvider: created }),
+          text: JSON.stringify({ provider: created }),
         },
       ],
     };

package/src/mcp/tools/payment/index.ts

@@ -51,7 +51,7 @@ export const registerPaymentProviderTools = (server: McpServer, context: Context
     async (params) => paymentInterfacesHandler(context, params),
   );
   server.tool(
-    'paymentProvider_create',
+    'paymentProvider_add',
     'Adds new payment provider.',
     CreatePaymentProviderSchema,
     async (params) => createPaymentProviderHandler(context, params),

package/src/mcp/tools/payment/paymentInterfacesHandler.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-
 import { Context } from '../../../context.js';
 import { log } from '@unchainedshop/logger';
 import { PaymentDirector } from '@unchainedshop/core';
@@ -8,7 +7,7 @@ import { PaymentProviderType } from '@unchainedshop/core-payment';
 const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
 
 export const PaymentInterfacesSchema = {
-  type: PaymentProviderTypeEnum.describe('Filter payment interfaces by provider type'),
+  type: PaymentProviderTypeEnum.optional().describe('Optional filter by payment provider type'),
 };
 
 export const PaymentInterfacesZodSchema = z.object(PaymentInterfacesSchema);
@@ -21,19 +20,23 @@ export async function paymentInterfacesHandler(context: Context, params: Payment
   try {
     log('handler paymentInterfacesHandler', { userId, type });
 
-    const interfaces = await PaymentDirector.getAdapters()
-      .filter((Adapter) => Adapter.typeSupported(type as PaymentProviderType))
-      .map((Adapter) => ({
-        _id: Adapter.key,
-        label: Adapter.label,
-        version: Adapter.version,
-      }));
+    const allAdapters = await PaymentDirector.getAdapters();
+
+    const filteredAdapters = type
+      ? allAdapters.filter((Adapter) => Adapter.typeSupported(type as PaymentProviderType))
+      : allAdapters;
+
+    const interfaces = filteredAdapters.map((Adapter) => ({
+      _id: Adapter.key,
+      label: Adapter.label,
+      version: Adapter.version,
+    }));
 
     return {
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ paymentInterfaces: interfaces }),
+          text: JSON.stringify({ interfaces }),
         },
       ],
     };

package/src/mcp/tools/payment/paymentProviderByIdHandler.ts

@@ -35,7 +35,7 @@ export async function paymentProviderByIdHandler(context: Context, params: Payme
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ paymentProvider: provider }),
+          text: JSON.stringify({ provider }),
         },
       ],
     };

package/src/mcp/tools/payment/paymentProvidersListHandler.ts

@@ -5,25 +5,35 @@ import { log } from '@unchainedshop/logger';
 const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
 
 export const PaymentProvidersListSchema = {
-  type: PaymentProviderTypeEnum.optional().describe('Filter payment providers by type'),
+  type: PaymentProviderTypeEnum.optional().describe('Optional filter by payment provider type'),
+  queryString: z.string().min(1).optional().describe('Optional full-text search string'),
 };
 
 export const PaymentProvidersListZodSchema = z.object(PaymentProvidersListSchema);
 export type PaymentProvidersListParams = z.infer<typeof PaymentProvidersListZodSchema>;
-
 export async function paymentProvidersListHandler(context: Context, params: PaymentProvidersListParams) {
   const { modules, userId } = context;
 
   try {
     log('handler paymentProvidersListHandler', { userId, params });
 
-    const providers = await modules.payment.paymentProviders.findProviders(params as any);
+    const { type, queryString } = params;
+
+    const selector: Record<string, any> = {};
+    if (type) selector.type = type;
+
+    if (queryString) {
+      const regex = new RegExp(queryString, 'i');
+      selector.$or = [{ _id: regex }, { adapterKey: regex }];
+    }
+
+    const providers = await modules.payment.paymentProviders.findProviders(selector);
 
     return {
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ paymentProviders: providers }),
+          text: JSON.stringify({ providers }),
         },
       ],
     };

package/src/mcp/tools/payment/removePaymentProviderHandler.ts

@@ -20,20 +20,18 @@ export async function removePaymentProviderHandler(
   try {
     log('handler removePaymentProviderHandler', { userId, paymentProviderId });
 
-    if (
-      !(await modules.payment.paymentProviders.providerExists({
-        paymentProviderId,
-      }))
-    )
-      throw new PaymentProviderNotFoundError({ paymentProviderId });
+    const provider = await modules.payment.paymentProviders.findProvider({
+      paymentProviderId,
+    });
+    if (!provider) throw new PaymentProviderNotFoundError({ paymentProviderId });
 
-    const removed = await modules.payment.paymentProviders.delete(paymentProviderId);
+    await modules.payment.paymentProviders.delete(paymentProviderId);
 
     return {
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ paymentProvider: removed }),
+          text: JSON.stringify({ provider }),
         },
       ],
     };

package/src/mcp/tools/payment/updatePaymentProviderHandler.ts

@@ -3,11 +3,30 @@ import { Context } from '../../../context.js';
 import { log } from '@unchainedshop/logger';
 import { PaymentProviderNotFoundError } from '../../../errors.js';
 
+const ConfigurationEntry = z.object({
+  key: z.string().min(1).describe('Configuration key'),
+  value: z.any().describe('Configuration value'),
+});
+
 export const UpdatePaymentProviderSchema = {
   paymentProviderId: z.string().min(1).describe('ID of the payment provider to update'),
-  paymentProvider: z.object({
-    configuration: z.array(z.any()).optional().describe('Array of JSON configuration values'),
-  }),
+  paymentProvider: z
+    .object({
+      configuration: z
+        .array(ConfigurationEntry)
+        .optional()
+        .describe('List of key-value configuration entries'),
+    })
+    .refine(
+      (data) => {
+        const keys = data.configuration?.map((entry) => entry.key) || [];
+        return new Set(keys).size === keys.length;
+      },
+      {
+        message: 'Duplicate keys are not allowed in configuration.',
+        path: ['configuration'],
+      },
+    ),
 };
 
 export const UpdatePaymentProviderZodSchema = z.object(UpdatePaymentProviderSchema);
@@ -39,7 +58,7 @@ export async function updatePaymentProviderHandler(
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ paymentProvider: updated }),
+          text: JSON.stringify({ provider: updated }),
         },
       ],
     };

package/src/mcp/tools/warehousing/createWarehousingProviderHandler.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { WarehousingDirector } from '@unchainedshop/core';
+import { ProviderConfigurationInvalid } from '../../../errors.js';
+
+const WarehousingProviderTypeEnum = z.enum(['PHYSICAL', 'VIRTUAL']);
+
+export const CreateWarehousingProviderSchema = {
+  warehousingProvider: z.object({
+    type: WarehousingProviderTypeEnum.describe('Type of the warehousing provider'),
+    adapterKey: z
+      .string()
+      .min(1)
+      .describe(
+        'Adapter key for the warehousing provider, it should be a valid interface key found in warehousing interfaces',
+      ),
+  }),
+};
+
+export const CreateWarehousingProviderZodSchema = z.object(CreateWarehousingProviderSchema);
+export type CreateWarehousingProviderParams = z.infer<typeof CreateWarehousingProviderZodSchema>;
+
+export async function createWarehousingProviderHandler(
+  context: Context,
+  params: CreateWarehousingProviderParams,
+) {
+  const { modules, userId } = context;
+  const { warehousingProvider } = params;
+
+  try {
+    log('handler createWarehousingProviderHandler', { userId, warehousingProvider });
+
+    const Adapter = WarehousingDirector.getAdapter(warehousingProvider.adapterKey);
+
+    const provider = await modules.warehousing.create({
+      configuration: Adapter.initialConfiguration,
+      ...warehousingProvider,
+    } as any);
+
+    if (!provider) throw new ProviderConfigurationInvalid(warehousingProvider);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ provider }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating warehousing provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/warehousing/index.ts

@@ -0,0 +1,81 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import {
+  warehousingProvidersListHandler,
+  WarehousingProvidersListSchema,
+} from './warehousingProvidersListHandler.js';
+import {
+  warehousingProvidersCountHandler,
+  WarehousingProvidersCountSchema,
+} from './warehousingProvidersCountHandler.js';
+import {
+  WarehousingProviderByIdSchema,
+  warehousingProviderHandler,
+} from './warehousingProviderHandler.js';
+import {
+  warehousingInterfacesHandler,
+  WarehousingInterfacesSchema,
+} from './warehousingInterfacesHandler.js';
+import {
+  createWarehousingProviderHandler,
+  CreateWarehousingProviderSchema,
+} from './createWarehousingProviderHandler.js';
+import {
+  updateWarehousingProviderHandler,
+  UpdateWarehousingProviderSchema,
+} from './updateWarehousingProviderHandler.js';
+import {
+  removeWarehousingProviderHandler,
+  RemoveWarehousingProviderSchema,
+} from './removeWarehousingProviderHandler.js';
+
+export const registerWarehousingProviderTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'warehousingProviders_list',
+    'Get all warehousing providers, optionally filtered by type.',
+    WarehousingProvidersListSchema,
+    async (params) => warehousingProvidersListHandler(context, params),
+  );
+
+  server.tool(
+    'warehousingProviders_count',
+    'Returns total number of warehousing providers, optionally filtered by type.',
+    WarehousingProvidersCountSchema,
+    async (params) => warehousingProvidersCountHandler(context, params),
+  );
+
+  server.tool(
+    'warehousingProvider_get',
+    'Get a specific warehousing provider by ID.',
+    WarehousingProviderByIdSchema,
+    async (params) => warehousingProviderHandler(context, params),
+  );
+
+  server.tool(
+    'warehousingInterfaces_list',
+    'Get all warehousing interfaces filtered by type.',
+    WarehousingInterfacesSchema,
+    async (params) => warehousingInterfacesHandler(context, params),
+  );
+
+  server.tool(
+    'warehousingProvider_add',
+    'Creates new warehousing provider.',
+    CreateWarehousingProviderSchema,
+    async (params) => createWarehousingProviderHandler(context, params),
+  );
+
+  server.tool(
+    'warehousingProvider_update',
+    'Updates warehousing provider information with the provided ID.',
+    UpdateWarehousingProviderSchema,
+    async (params) => updateWarehousingProviderHandler(context, params),
+  );
+
+  server.tool(
+    'warehousingProvider_remove',
+    'Soft deletes a warehousing provider by setting its deleted timestamp.',
+    RemoveWarehousingProviderSchema,
+    async (params) => removeWarehousingProviderHandler(context, params),
+  );
+};

package/src/mcp/tools/warehousing/removeWarehousingProviderHandler.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { WarehousingProviderNotFoundError } from '../../../errors.js';
+
+export const RemoveWarehousingProviderSchema = {
+  warehousingProviderId: z.string().min(1).describe('ID of the warehousing provider to soft delete'),
+};
+
+export const RemoveWarehousingProviderZodSchema = z.object(RemoveWarehousingProviderSchema);
+export type RemoveWarehousingProviderParams = z.infer<typeof RemoveWarehousingProviderZodSchema>;
+export async function removeWarehousingProviderHandler(
+  context: Context,
+  params: RemoveWarehousingProviderParams,
+) {
+  const { modules, userId } = context;
+  const { warehousingProviderId } = params;
+
+  try {
+    log('handler removeWarehousingProviderHandler', { userId, warehousingProviderId });
+    const provider = await modules.warehousing.findProvider({
+      warehousingProviderId,
+    });
+    if (!provider) throw new WarehousingProviderNotFoundError({ warehousingProviderId });
+
+    await modules.warehousing.delete(warehousingProviderId);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ provider }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error removing warehousing provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}