@unchainedshop/api 3.1.15 → 4.0.0-rc.11

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

@@ -0,0 +1,42 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import { CreateLanguageSchema, createLanguageHandler } from './createLanguageHandler.js';
+import { LanguageSchema, languageHandler } from './languageHandler.js';
+import { ListLanguagesSchema, languagesHandler } from './languagesHandler.js';
+import { RemoveLanguageSchema, removeLanguageHandler } from './removeLanguageHandler.js';
+import { UpdateLanguageSchema, updateLanguageHandler } from './updateLanguageHandler.js';
+import { LanguagesCountSchema, languagesCountHandler } from './languagesCountHandler.js';
+
+export const registerLanguageTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'languages_list',
+    'List languages with optional filters, pagination, and sorting',
+    ListLanguagesSchema,
+    async (params) => languagesHandler(context, params),
+  );
+
+  server.tool('language_get', 'Fetch a specific language by ID.', LanguageSchema, async (params) =>
+    languageHandler(context, params),
+  );
+
+  server.tool(
+    'language_create',
+    'Create a new language using an ISO code like "en" or "de-CH".',
+    CreateLanguageSchema,
+    async (params) => createLanguageHandler(context, params),
+  );
+
+  server.tool('update_language', 'Update language details', UpdateLanguageSchema, async (params) =>
+    updateLanguageHandler(context, params),
+  );
+
+  server.tool('language_remove', 'Remove a language by its ID', RemoveLanguageSchema, async (params) =>
+    removeLanguageHandler(context, params),
+  );
+  server.tool(
+    'language_count',
+    'Return the count of languages, optionally including inactive and filtering by search text.',
+    LanguagesCountSchema,
+    async (params) => languagesCountHandler(context, params),
+  );
+};

package/src/mcp/tools/language/languageHandler.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const LanguageSchema = {
+  languageId: z.string().min(1).describe('The ID of the language to fetch'),
+};
+
+export const LanguageZodSchema = z.object(LanguageSchema);
+
+export type LanguageParams = z.infer<typeof LanguageZodSchema>;
+
+export async function languageHandler(context: Context, params: LanguageParams) {
+  const { languageId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler languageHandler`, { userId, params });
+    const language = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/languagesCountHandler.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const LanguagesCountSchema = {
+  includeInactive: z.boolean().optional().default(false).describe('Include inactive languages in count'),
+  queryString: z.string().optional().describe('Optional search filter'),
+};
+
+export const LanguagesCountZodSchema = z.object(LanguagesCountSchema);
+
+export type LanguagesCountParams = z.infer<typeof LanguagesCountZodSchema>;
+
+export async function languagesCountHandler(context: Context, params: LanguagesCountParams) {
+  const { modules, userId } = context;
+
+  try {
+    log(`handler languagesCountHandler `, {
+      userId,
+      params,
+    });
+
+    const count = await modules.languages.count(params);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify(count),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error counting languages: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/languagesHandler.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { SortDirection } from '@unchainedshop/utils';
+import { log } from '@unchainedshop/logger';
+
+const sortDirectionKeys = Object.keys(SortDirection) as [
+  keyof typeof SortDirection,
+  ...(keyof typeof SortDirection)[],
+];
+
+export const ListLanguagesSchema = {
+  limit: z.number().int().min(1).max(100).default(50).describe('Maximum number of languages to return'),
+  offset: z.number().int().min(0).default(0).describe('Number of languages to skip for pagination'),
+  includeInactive: z.boolean().default(false).describe('Whether to include inactive languages'),
+  query_string: z.string().min(1).optional().describe('Optional text search filter'),
+  sort: z
+    .array(
+      z.object({
+        key: z.string().min(1).describe('Field to sort by'),
+        value: z.enum(sortDirectionKeys).describe("Sort direction, 'ASC' or 'DESC'"),
+      }),
+    )
+    .optional()
+    .describe('Sort configuration'),
+};
+
+export const ListLanguagesZodSchema = z.object(ListLanguagesSchema);
+
+export type ListLanguagesParams = z.infer<typeof ListLanguagesZodSchema>;
+
+export async function languagesHandler(context: Context, params: ListLanguagesParams) {
+  const { modules, userId } = context;
+
+  try {
+    log(`handler languagesHandler `, {
+      userId,
+      params,
+    });
+    const languages = await modules.languages.findLanguages(params as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ languages }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving languages: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/removeLanguageHandler.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { LanguageNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+
+export const RemoveLanguageSchema = {
+  languageId: z.string().min(1).describe('ID of the language to remove'),
+};
+
+export const RemoveLanguageZodSchema = z.object(RemoveLanguageSchema);
+export type RemoveLanguageParams = z.infer<typeof RemoveLanguageZodSchema>;
+
+export async function removeLanguageHandler(context: Context, params: RemoveLanguageParams) {
+  const { languageId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler languagesHandler `, {
+      userId,
+      params,
+    });
+    if (!(await modules.languages.languageExists({ languageId })))
+      throw new LanguageNotFoundError({ languageId });
+
+    await modules.languages.delete(languageId);
+
+    const removeLanguage = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: removeLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error removing language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/updateLanguageHandler.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { LanguageNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+
+const UpdateLanguageInputSchema = z.object({
+  isoCode: z.string().min(2).max(10).describe('Updated ISO code for the language'),
+  isActive: z.boolean().optional().describe('Whether the language is active'),
+});
+
+export const UpdateLanguageSchema = {
+  languageId: z.string().min(1).describe('ID of the language to update'),
+  language: UpdateLanguageInputSchema,
+};
+
+export const UpdateLanguageZodSchema = z.object(UpdateLanguageSchema);
+export type UpdateLanguageParams = z.infer<typeof UpdateLanguageZodSchema>;
+
+export async function updateLanguageHandler(context: Context, params: UpdateLanguageParams) {
+  const { languageId, language } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler updateLanguageHandler `, {
+      userId,
+      params,
+    });
+    if (!(await modules.languages.languageExists({ languageId })))
+      throw new LanguageNotFoundError({ languageId });
+
+    await modules.languages.update(languageId, language);
+
+    const updatedLanguage = await modules.languages.findLanguage({ languageId });
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: updatedLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating language: ${(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}`,
+        },
+      ],
+    };
+  }
+}