@unchainedshop/api 3.1.15 → 4.0.0-rc.11

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),
+  );
+};

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { PaymentDirector } from '@unchainedshop/core';
+import { ProviderConfigurationInvalid } from '../../../errors.js';
+
+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, this value should be a valid adapter key found in payment provider interfaces',
+      ),
+  }),
+};
+
+export const CreatePaymentProviderZodSchema = z.object(CreatePaymentProviderSchema);
+export type CreatePaymentProviderParams = z.infer<typeof CreatePaymentProviderZodSchema>;
+
+export async function createPaymentProviderHandler(
+  context: Context,
+  params: CreatePaymentProviderParams,
+) {
+  const { modules, userId } = context;
+  const { paymentProvider } = params;
+
+  try {
+    log('handler createPaymentProviderHandler', { userId, paymentProvider });
+
+    const Adapter = PaymentDirector.getAdapter(paymentProvider.adapterKey);
+    if (!Adapter) throw new ProviderConfigurationInvalid(paymentProvider);
+
+    const created = await modules.payment.paymentProviders.create({
+      configuration: Adapter.initialConfiguration,
+      ...paymentProvider,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ provider: created }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating payment provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,73 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import {
+  paymentProvidersListHandler,
+  PaymentProvidersListSchema,
+} from './paymentProvidersListHandler.js';
+import {
+  paymentProvidersCountHandler,
+  PaymentProvidersCountSchema,
+} from './paymentProvidersCountHandler.js';
+import { paymentProviderByIdHandler, PaymentProviderByIdSchema } from './paymentProviderByIdHandler.js';
+import { paymentInterfacesHandler, PaymentInterfacesSchema } from './paymentInterfacesHandler.js';
+import {
+  createPaymentProviderHandler,
+  CreatePaymentProviderSchema,
+} from './createPaymentProviderHandler.js';
+import {
+  updatePaymentProviderHandler,
+  UpdatePaymentProviderSchema,
+} from './updatePaymentProviderHandler.js';
+import {
+  removePaymentProviderHandler,
+  RemovePaymentProviderSchema,
+} from './removePaymentProviderHandler.js';
+
+export const registerPaymentProviderTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'paymentProviders_list',
+    'Get all payment providers, optionally filtered by type.',
+    PaymentProvidersListSchema,
+    async (params) => paymentProvidersListHandler(context, params),
+  );
+  server.tool(
+    'paymentProviders_count',
+    'Returns total number of payment providers, optionally filtered by type.',
+    PaymentProvidersCountSchema,
+    async (params) => paymentProvidersCountHandler(context, params),
+  );
+
+  server.tool(
+    'paymentProvider_get',
+    'Get a specific payment provider by ID.',
+    PaymentProviderByIdSchema,
+    async (params) => paymentProviderByIdHandler(context, params),
+  );
+
+  server.tool(
+    'paymentInterfaces_list',
+    'Get all payment interfaces filtered by type.',
+    PaymentInterfacesSchema,
+    async (params) => paymentInterfacesHandler(context, params),
+  );
+  server.tool(
+    'paymentProvider_add',
+    'Adds new payment provider.',
+    CreatePaymentProviderSchema,
+    async (params) => createPaymentProviderHandler(context, params),
+  );
+
+  server.tool(
+    'paymentProvider_update',
+    'Updates payment provider information with the provided ID.',
+    UpdatePaymentProviderSchema,
+    async (params) => updatePaymentProviderHandler(context, params),
+  );
+
+  server.tool(
+    'paymentProvider_remove',
+    'Soft deletes a payment provider by setting its deleted timestamp.',
+    RemovePaymentProviderSchema,
+    async (params) => removePaymentProviderHandler(context, params),
+  );
+};

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { PaymentDirector } from '@unchainedshop/core';
+import { PaymentProviderType } from '@unchainedshop/core-payment';
+
+const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
+
+export const PaymentInterfacesSchema = {
+  type: PaymentProviderTypeEnum.optional().describe('Optional filter by payment provider type'),
+};
+
+export const PaymentInterfacesZodSchema = z.object(PaymentInterfacesSchema);
+export type PaymentInterfacesParams = z.infer<typeof PaymentInterfacesZodSchema>;
+
+export async function paymentInterfacesHandler(context: Context, params: PaymentInterfacesParams) {
+  const { userId } = context;
+  const { type } = params;
+
+  try {
+    log('handler paymentInterfacesHandler', { userId, type });
+
+    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({ interfaces }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching payment interfaces: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const PaymentProviderByIdSchema = {
+  paymentProviderId: z.string().min(1).describe('ID of the payment provider'),
+};
+
+export const PaymentProviderByIdZodSchema = z.object(PaymentProviderByIdSchema);
+export type PaymentProviderByIdParams = z.infer<typeof PaymentProviderByIdZodSchema>;
+
+export async function paymentProviderByIdHandler(context: Context, params: PaymentProviderByIdParams) {
+  const { modules, userId } = context;
+  const { paymentProviderId } = params;
+
+  try {
+    log('handler paymentProviderByIdHandler', { userId, paymentProviderId });
+
+    const provider = await modules.payment.paymentProviders.findProvider({
+      paymentProviderId,
+    });
+
+    if (!provider) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Payment provider not found for ID: ${paymentProviderId}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ provider }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching payment provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
+
+export const PaymentProvidersCountSchema = {
+  type: PaymentProviderTypeEnum.optional().describe('Filter payment providers by type'),
+};
+
+export const PaymentProvidersCountZodSchema = z.object(PaymentProvidersCountSchema);
+export type PaymentProvidersCountParams = z.infer<typeof PaymentProvidersCountZodSchema>;
+
+export async function paymentProvidersCountHandler(
+  context: Context,
+  params: PaymentProvidersCountParams,
+) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler paymentProvidersCountHandler', { userId, params });
+
+    const count = await modules.payment.paymentProviders.count(params as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ count }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error counting payment providers: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
+
+export const PaymentProvidersListSchema = {
+  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 { 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({ providers }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching payment providers: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

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