@unchainedshop/api 3.1.15 → 4.0.0-rc.10

package/src/mcp/tools/filter/updateFilterHandler.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FilterNotFoundError } from '../../../errors.js';
+import { FilterDirector } from '@unchainedshop/core';
+import { getNormalizedFilterDetails } from '../../utils/getNormalizedFilterDetails.js';
+
+export const UpdateFilterInputSchema = z.object({
+  isActive: z.boolean().optional().describe('Whether the filter should be active or not'),
+  key: z.string().min(1).optional().describe('New unique key for the filter (if updating)'),
+});
+
+export const UpdateFilterSchema = {
+  filterId: z.string().min(1).describe('ID of the filter to update'),
+  filter: UpdateFilterInputSchema.describe('Filter fields to update'),
+};
+
+export const UpdateFilterZodSchema = z.object(UpdateFilterSchema);
+
+export type UpdateFilterParams = z.infer<typeof UpdateFilterZodSchema>;
+
+export async function updateFilterHandler(context: Context, params: UpdateFilterParams) {
+  const { filterId, filter } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateFilterHandler', { userId, params });
+    if (!(await modules.filters.filterExists({ filterId }))) throw new FilterNotFoundError({ filterId });
+
+    const updatedFilter = await modules.filters.update(filterId, filter as any);
+    await FilterDirector.invalidateProductIdCache(updatedFilter, context);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ filter: await getNormalizedFilterDetails(filterId, context) }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating filter: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/filter/updateFilterTextsHandler.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FilterNotFoundError } from '../../../errors.js';
+import { getNormalizedFilterDetails } from '../../utils/getNormalizedFilterDetails.js';
+
+export const FilterUpdateTextInputSchema = z.object({
+  locale: z.string().min(1).describe('Locale ISO code (e.g., "en-US", "de-CH")'),
+  title: z.string().optional().describe('Title for the filter or filter option in the specified locale'),
+  subtitle: z
+    .string()
+    .optional()
+    .describe('Subtitle for the filter or filter option in the specified locale'),
+});
+
+export const UpdateFilterTextsSchema = {
+  filterId: z.string().min(1).describe('ID of the filter to update localized texts for'),
+  filterOptionValue: z
+    .string()
+    .optional()
+    .describe('Optional value of the filter option to localize (if applicable)'),
+  texts: z
+    .array(FilterUpdateTextInputSchema)
+    .min(1)
+    .describe('Array of localized texts to set or update'),
+};
+
+export const UpdateFilterTextsZodSchema = z.object(UpdateFilterTextsSchema);
+
+export type UpdateFilterTextsParams = z.infer<typeof UpdateFilterTextsZodSchema>;
+
+// Handler
+export async function updateFilterTextsHandler(context: Context, params: UpdateFilterTextsParams) {
+  const { filterId, filterOptionValue, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateFilterTexts', { userId, filterId, filterOptionValue, texts });
+
+    const filter = await getNormalizedFilterDetails(filterId, context);
+    if (!filter) throw new FilterNotFoundError({ filterId });
+
+    const updatedTexts = await modules.filters.texts.updateTexts({ filterId, filterOptionValue }, texts);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ filterTexts: updatedTexts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating filter texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../context.js';
+import { shopInfoHandler } from './shopInfoHandler.js';
+
+export const registerOtherTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'shop_info',
+    'Get the default configuration of the shop including country, language, currency, and locale. If the user does not provide values such as language, locale, country, or currency in their request or it cannot be derived from context, the tool MUST use the following fallback values : - language or locale: use defaultLanguageIsoCode  - country: use country_isoCode - currency: use country_defaultCurrency Always assume these values as the authoritative defaults when user input is missing or ambiguous.',
+    {},
+    async () => shopInfoHandler(context),
+  );
+};

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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+const CreateLanguageInputSchema = z.object({
+  isoCode: z
+    .string()
+    .min(2)
+    .max(10)
+    .describe(
+      'Language ISO code (e.g., "en" or "de-CH"). Must follow ISO 639-1 and ISO 3166-1 formats.',
+    ),
+});
+
+export const CreateLanguageSchema = {
+  language: CreateLanguageInputSchema,
+};
+
+export const CreateLanguageZodSchema = z.object(CreateLanguageSchema);
+export type CreateLanguageParams = z.infer<typeof CreateLanguageZodSchema>;
+
+export async function createLanguageHandler(context: Context, params: CreateLanguageParams) {
+  const { language } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler createLanguageHandler`, { userId, params });
+    const languageId = await modules.languages.create(language as any);
+
+    const newLanguage = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: newLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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/payment/createPaymentProviderHandler.ts

@@ -0,0 +1,55 @@
+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'),
+  }),
+};
+
+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({ paymentProvider: 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_create',
+    '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,50 @@
+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.describe('Filter payment interfaces by 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 interfaces = await PaymentDirector.getAdapters()
+      .filter((Adapter) => Adapter.typeSupported(type as PaymentProviderType))
+      .map((Adapter) => ({
+        _id: Adapter.key,
+        label: Adapter.label,
+        version: Adapter.version,
+      }));
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ paymentInterfaces: interfaces }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching payment interfaces: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}