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

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

@@ -0,0 +1,74 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import {
+  deliveryProvidersListHandler,
+  DeliveryProvidersListSchema,
+} from './deliveryProvidersListHandler.js';
+import {
+  deliveryProvidersCountHandler,
+  DeliveryProvidersCountSchema,
+} from './deliveryProvidersCountHandler.js';
+import { DeliveryProviderByIdSchema, deliveryProviderHandler } from './deliveryProvider.js';
+import { deliveryInterfacesHandler, DeliveryInterfacesSchema } from './deliveryInterfacesHandler.js';
+import {
+  createDeliveryProviderHandler,
+  CreateDeliveryProviderSchema,
+} from './createDeliveryProviderHandler.js';
+import {
+  updateDeliveryProviderHandler,
+  UpdateDeliveryProviderSchema,
+} from './updateDeliveryProviderHandler.js';
+import {
+  removeDeliveryProviderHandler,
+  RemoveDeliveryProviderSchema,
+} from './removeDeliveryProviderHandler.js';
+
+export const registerDeliveryProviderTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'deliveryProviders_list',
+    'Get all delivery providers, optionally filtered by type.',
+    DeliveryProvidersListSchema,
+    async (params) => deliveryProvidersListHandler(context, params),
+  );
+
+  server.tool(
+    'deliveryProviders_count',
+    'Returns total number of delivery providers, optionally filtered by type.',
+    DeliveryProvidersCountSchema,
+    async (params) => deliveryProvidersCountHandler(context, params),
+  );
+
+  server.tool(
+    'deliveryProvider_get',
+    'Get a specific delivery provider by ID.',
+    DeliveryProviderByIdSchema,
+    async (params) => deliveryProviderHandler(context, params),
+  );
+  server.tool(
+    'deliveryInterfaces_list',
+    'Get all delivery interfaces filtered by type.',
+    DeliveryInterfacesSchema,
+    async (params) => deliveryInterfacesHandler(context, params),
+  );
+
+  server.tool(
+    'deliveryProvider_add',
+    'Adds new delivery provider.',
+    CreateDeliveryProviderSchema,
+    async (params) => createDeliveryProviderHandler(context, params),
+  );
+
+  server.tool(
+    'deliveryProvider_update',
+    'Updates the delivery provider specified.',
+    UpdateDeliveryProviderSchema,
+    async (params) => updateDeliveryProviderHandler(context, params),
+  );
+
+  server.tool(
+    'deliveryProvider_remove',
+    'Soft deletes a delivery provider by setting its deleted timestamp.',
+    RemoveDeliveryProviderSchema,
+    async (params) => removeDeliveryProviderHandler(context, params),
+  );
+};

package/src/mcp/tools/delivery/removeDeliveryProviderHandler.ts

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

package/src/mcp/tools/delivery/updateDeliveryProviderHandler.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { DeliverProviderNotFoundError } from '../../../errors.js';
+
+const ConfigurationEntry = z.object({
+  key: z.string().min(1).describe('Configuration key'),
+  value: z.any().describe('Configuration value'),
+});
+
+export const UpdateDeliveryProviderSchema = {
+  deliveryProviderId: z.string().min(1).describe('ID of the delivery provider to update'),
+  deliveryProvider: 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 UpdateDeliveryProviderZodSchema = z.object(UpdateDeliveryProviderSchema);
+export type UpdateDeliveryProviderParams = z.infer<typeof UpdateDeliveryProviderZodSchema>;
+
+export async function updateDeliveryProviderHandler(
+  context: Context,
+  params: UpdateDeliveryProviderParams,
+) {
+  const { modules, userId } = context;
+  const { deliveryProviderId, deliveryProvider } = params;
+
+  try {
+    log('handler updateDeliveryProviderHandler', { userId, deliveryProviderId, deliveryProvider });
+
+    if (!(await modules.delivery.providerExists({ deliveryProviderId })))
+      throw new DeliverProviderNotFoundError({ deliveryProviderId });
+
+    const updated = await modules.delivery.update(deliveryProviderId, deliveryProvider as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ provider: updated }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating delivery provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { DateRangeSchema, OrderFilterSchema } from '../../utils/sharedSchemas.js';
+import { formatSummaryMap, resolveDateRange, resolveOrderFilters } from '../../utils/orderFilters.js';
+
+export const MonthlySalesBreakdownSchema = {
+  ...DateRangeSchema,
+  ...OrderFilterSchema,
+};
+
+export const MonthlySalesBreakdownZodSchema = z.object(MonthlySalesBreakdownSchema);
+export type MonthlySalesBreakdownParams = z.infer<typeof MonthlySalesBreakdownZodSchema>;
+
+export async function getMonthlySalesBreakdownHandler(
+  context: Context,
+  params: MonthlySalesBreakdownParams,
+) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler getMonthlySalesBreakdownHandler', { userId, params });
+
+    const { from, to, paymentProviderIds, deliveryProviderIds, status } = params;
+
+    const { startDate, endDate } = resolveDateRange(from, to);
+    const filters = await resolveOrderFilters(modules, { paymentProviderIds, deliveryProviderIds });
+    if (!filters) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({
+              totalSalesAmount: 0,
+              orderCount: 0,
+              averageOrderValue: 0,
+              currencyCode: null,
+              summary: [],
+              dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+            }),
+          },
+        ],
+      };
+    }
+
+    const orders = await modules.orders.findOrders({
+      dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+      status,
+      ...filters,
+    } as any);
+
+    let totalSalesAmount = 0;
+    let orderCount = 0;
+
+    const monthlyMap = new Map<string, { sales: number; orders: number }>();
+
+    for (let i = 0; i < 12; i++) {
+      const date = new Date(endDate.getFullYear(), endDate.getMonth() - i, 1);
+      const label = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+      monthlyMap.set(label, { sales: 0, orders: 0 });
+    }
+
+    for (const order of orders) {
+      const orderDate = new Date(order.created);
+      if (orderDate < startDate || orderDate > endDate) continue;
+
+      orderCount++;
+      const itemsAmount = order.calculation?.find((c) => c.category === 'ITEMS')?.amount || 0;
+      totalSalesAmount += itemsAmount;
+
+      const label = `${orderDate.getFullYear()}-${String(orderDate.getMonth() + 1).padStart(2, '0')}`;
+      const entry = monthlyMap.get(label);
+      if (entry) {
+        entry.sales += itemsAmount;
+        entry.orders += 1;
+      }
+    }
+
+    const averageOrderValue = orderCount > 0 ? totalSalesAmount / orderCount : 0;
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            totalSalesAmount,
+            orderCount,
+            averageOrderValue,
+            currencyCode: orders[0]?.currencyCode ?? null,
+            summary: formatSummaryMap(monthlyMap),
+            dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching monthly sales breakdown: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { DateRangeSchema, OrderFilterSchema } from '../../utils/sharedSchemas.js';
+import { formatSummaryMap, resolveDateRange, resolveOrderFilters } from '../../utils/orderFilters.js';
+
+export const SalesSummarySchema = {
+  ...DateRangeSchema,
+  ...OrderFilterSchema,
+  days: z.number().int().min(1).max(365).optional(),
+};
+
+export const SalesSummaryZodSchema = z.object(SalesSummarySchema);
+export type SalesSummaryParams = z.infer<typeof SalesSummaryZodSchema>;
+
+export async function getSalesSummaryHandler(context: Context, params: SalesSummaryParams) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler getSalesSummaryHandler', { userId, params });
+
+    const { from, to, days = 30, paymentProviderIds, deliveryProviderIds, status } = params;
+    const { startDate, endDate } = resolveDateRange(from, to, days);
+
+    const filters = await resolveOrderFilters(modules, { paymentProviderIds, deliveryProviderIds });
+    if (!filters) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({
+              totalSalesAmount: 0,
+              orderCount: 0,
+              averageOrderValue: 0,
+              currencyCode: null,
+              summary: [],
+              dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+            }),
+          },
+        ],
+      };
+    }
+
+    const orders = await modules.orders.findOrders({
+      dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+      ...filters,
+      status,
+    } as any);
+
+    let totalSalesAmount = 0;
+    let orderCount = 0;
+
+    const dateMap = new Map<string, { sales: number; orders: number }>();
+    for (let i = 0; i < days; i++) {
+      const date = new Date(endDate.getTime() - i * 86400000);
+      const label = date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+      dateMap.set(label, { sales: 0, orders: 0 });
+    }
+
+    for (const order of orders) {
+      const orderDate = new Date(order.created);
+      if (orderDate < startDate || orderDate > endDate) continue;
+
+      orderCount++;
+      const itemsAmount = order.calculation?.find((c) => c.category === 'ITEMS')?.amount || 0;
+      totalSalesAmount += itemsAmount;
+
+      const label = orderDate.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+      const entry = dateMap.get(label);
+      if (entry) {
+        entry.sales += itemsAmount;
+        entry.orders += 1;
+      }
+    }
+
+    const averageOrderValue = orderCount > 0 ? totalSalesAmount / orderCount : 0;
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            totalSalesAmount,
+            orderCount,
+            averageOrderValue,
+            currencyCode: orders[0]?.currencyCode ?? null,
+            summary: formatSummaryMap(dateMap),
+            dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching sales summary: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { resolveDateRange } from '../../utils/orderFilters.js';
+import { OrderStatus } from '@unchainedshop/core-orders';
+
+export const GetTopCustomersSchema = {
+  limit: z.number().int().min(1).max(100).optional().describe('Max number of customers to return'),
+  status: z.string().optional().describe('Order status to filter by (e.g., CONFIRMED, DELIVERED)'),
+  dateRange: z
+    .object({
+      start: z.string().datetime().optional(),
+      end: z.string().datetime().optional(),
+    })
+    .optional()
+    .describe('Optional date range to filter orders'),
+};
+
+export const GetTopCustomersZodSchema = z.object(GetTopCustomersSchema);
+export type GetTopCustomersParams = z.infer<typeof GetTopCustomersZodSchema>;
+
+export async function getTopCustomersHandler(context: Context, params: GetTopCustomersParams) {
+  const { modules, userId, loaders } = context;
+  const { status, dateRange, limit = 10 } = params;
+
+  try {
+    log('handler getTopCustomersHandler', { userId, params });
+
+    const match: any = { status };
+    const { startDate, endDate } = resolveDateRange(dateRange.start, dateRange.end);
+
+    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.toISOString() };
+    if (endDate) match.created = { ...(match.created || {}), $lte: endDate.toISOString() };
+    if (orderIds?.length) match._id = { $in: orderIds };
+
+    const topCustomers = await modules.orders.aggregateOrders({
+      match,
+      project: {
+        userId: 1,
+        created: 1,
+        itemAmount: {
+          $let: {
+            vars: {
+              item: {
+                $first: {
+                  $filter: {
+                    input: '$calculation',
+                    as: 'c',
+                    cond: { $eq: ['$$c.category', 'ITEMS'] },
+                  },
+                },
+              },
+            },
+            in: '$$item.amount',
+          },
+        },
+      },
+      group: {
+        _id: '$userId',
+        totalSpent: { $sum: '$itemAmount' },
+        orderCount: { $sum: 1 },
+        lastOrderDate: { $max: '$created' },
+      },
+      addFields: {
+        averageOrderValue: {
+          $cond: [{ $eq: ['$orderCount', 0] }, 0, { $divide: ['$totalSpent', '$orderCount'] }],
+        },
+      },
+      sort: { totalSpent: -1 },
+      limit,
+    });
+
+    const normalizedCustomers = await Promise.all(
+      topCustomers.map(async (c) => {
+        const user = await modules.users.findUserById(c._id);
+        const avatar = await loaders.fileLoader.load({
+          fileId: user?.avatarId,
+        });
+        return {
+          userId: c._id?.toString?.() ?? null,
+          user: {
+            avatar,
+          },
+          totalSpent: c.totalSpent,
+          orderCount: c.orderCount,
+          lastOrderDate: c.lastOrderDate,
+          averageOrderValue: Math.round(c.averageOrderValue),
+        };
+      }),
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ customers: normalizedCustomers }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching top customers: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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.toISOString() };
+    if (endDate) match.created = { ...(match.created || {}), $lte: endDate.toISOString() };
+    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),
+  );
+};