@unchainedshop/api 4.0.0-rc.2 → 4.0.0-rc.21

package/src/mcp/tools/filter/handlers/getFilter.ts

@@ -0,0 +1,14 @@
+import { Context } from '../../../../context.js';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function getFilter(context: Context, params: Params<'GET'>) {
+  const { filterId } = params;
+
+  const normalizedFilter = await getNormalizedFilterDetails(filterId, context);
+  if (!normalizedFilter) {
+    throw new FilterNotFoundError({ filterId });
+  }
+  return { filter: normalizedFilter };
+}

package/src/mcp/tools/filter/handlers/getFilterTexts.ts

@@ -0,0 +1,19 @@
+import { Context } from '../../../../context.js';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { Params } from '../schemas.js';
+
+export default async function getFilterTexts(context: Context, params: Params<'GET_TEXTS'>) {
+  const { modules } = context;
+  const { filterId, filterOptionValue } = params;
+
+  if (!(await modules.filters.filterExists({ filterId }))) {
+    throw new FilterNotFoundError({ filterId });
+  }
+
+  const texts = await modules.filters.texts.findTexts({
+    filterId,
+    filterOptionValue: filterOptionValue || null,
+  });
+
+  return { texts };
+}

package/src/mcp/tools/filter/handlers/index.ts

@@ -0,0 +1,23 @@
+import createFilter from './createFilter.js';
+import updateFilter from './updateFilter.js';
+import removeFilter from './removeFilter.js';
+import getFilter from './getFilter.js';
+import listFilters from './listFilters.js';
+import countFilters from './countFilters.js';
+import createFilterOption from './createFilterOption.js';
+import removeFilterOption from './removeFilterOption.js';
+import updateFilterTexts from './updateFilterTexts.js';
+import getFilterTexts from './getFilterTexts.js';
+
+export default {
+  CREATE: createFilter,
+  UPDATE: updateFilter,
+  REMOVE: removeFilter,
+  GET: getFilter,
+  LIST: listFilters,
+  COUNT: countFilters,
+  CREATE_OPTION: createFilterOption,
+  REMOVE_OPTION: removeFilterOption,
+  UPDATE_TEXTS: updateFilterTexts,
+  GET_TEXTS: getFilterTexts,
+};

package/src/mcp/tools/filter/handlers/listFilters.ts

@@ -0,0 +1,28 @@
+import { Context } from '../../../../context.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function listFilters(context: Context, params: Params<'LIST'>) {
+  const { modules } = context;
+  const { limit = 50, offset = 0, sort, includeInactive = false, queryString } = params;
+
+  const sortOptions = sort?.map((s) => ({ key: s.key, value: s.value as any })) || undefined;
+
+  const filters = await modules.filters.findFilters(
+    {
+      includeInactive,
+      queryString,
+    },
+    {
+      limit,
+      skip: offset,
+      sort: sortOptions as any,
+    },
+  );
+
+  return {
+    filters: await Promise.all(
+      filters?.map(async ({ _id }) => getNormalizedFilterDetails(_id, context)),
+    ),
+  };
+}

package/src/mcp/tools/filter/handlers/removeFilter.ts

@@ -0,0 +1,22 @@
+import { Context } from '../../../../context.js';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { Params } from '../schemas.js';
+
+export default async function removeFilter(context: Context, params: Params<'REMOVE'>) {
+  const { modules } = context;
+  const { filterId } = params;
+
+  if (!(await modules.filters.filterExists({ filterId }))) {
+    throw new FilterNotFoundError({ filterId });
+  }
+
+  const assortmentFilters = await modules.assortments.filters.findFilters({ filterId } as any);
+  await Promise.all(
+    assortmentFilters.map(async (assortmentFilter) => {
+      await modules.assortments.filters.delete(assortmentFilter._id);
+    }),
+  );
+
+  await modules.filters.delete(filterId);
+  return { success: true };
+}

package/src/mcp/tools/filter/handlers/removeFilterOption.ts

@@ -0,0 +1,26 @@
+import { Context } from '../../../../context.js';
+import { FilterDirector } from '@unchainedshop/core';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function removeFilterOption(context: Context, params: Params<'REMOVE_OPTION'>) {
+  const { modules } = context;
+  const { filterId, option } = params;
+
+  if (!(await modules.filters.filterExists({ filterId }))) {
+    throw new FilterNotFoundError({ filterId });
+  }
+
+  const removedFilterOption = await modules.filters.removeFilterOption({
+    filterId,
+    filterOptionValue: option,
+  });
+
+  if (!removedFilterOption) return { filter: null };
+
+  await FilterDirector.invalidateProductIdCache(removedFilterOption, context);
+
+  const normalizedFilter = await getNormalizedFilterDetails(filterId, context);
+  return { filter: normalizedFilter };
+}

package/src/mcp/tools/filter/handlers/updateFilter.ts

@@ -0,0 +1,17 @@
+import { Context } from '../../../../context.js';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function updateFilter(context: Context, params: Params<'UPDATE'>) {
+  const { modules } = context;
+  const { filterId, updateData } = params;
+
+  if (!(await modules.filters.filterExists({ filterId }))) {
+    throw new FilterNotFoundError({ filterId });
+  }
+
+  await modules.filters.update(filterId, updateData as any);
+  const normalizedFilter = await getNormalizedFilterDetails(filterId, context);
+  return { filter: normalizedFilter };
+}

package/src/mcp/tools/filter/handlers/updateFilterTexts.ts

@@ -0,0 +1,22 @@
+import { FilterText } from '@unchainedshop/core-filters';
+import { Context } from '../../../../context.js';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function updateFilterTexts(context: Context, params: Params<'UPDATE_TEXTS'>) {
+  const { modules } = context;
+  const { filterId, textUpdates, filterOptionValue } = params;
+
+  if (!(await modules.filters.filterExists({ filterId }))) {
+    throw new FilterNotFoundError({ filterId });
+  }
+
+  const updatedTexts = await modules.filters.texts.updateTexts(
+    { filterId, filterOptionValue: filterOptionValue || null },
+    textUpdates as FilterText[],
+  );
+
+  const normalizedFilter = await getNormalizedFilterDetails(filterId, context);
+  return { texts: updatedTexts, filter: normalizedFilter };
+}

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

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import { filterManagement, FilterManagementSchema } from './filterManagement.js';
+
+export const registerFilterTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'filter_management',
+    'Comprehensive filter management system with unified CRUD operations. Supports: CREATE (new filters with localized texts), UPDATE (modify filter properties), REMOVE (delete with assortment cleanup), GET (retrieve single filter), LIST (paginated search with sorting), COUNT (total counts), CREATE_OPTION/REMOVE_OPTION (manage filter options), UPDATE_TEXTS/GET_TEXTS (localization management). Action-based routing with proper validation and error handling.',
+    FilterManagementSchema,
+    async (params) => filterManagement(context, params),
+  );
+};

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

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import {
+  PaginationSchema,
+  SortingSchema,
+  SearchSchema,
+  LocalizationTextSchema,
+} from '../../utils/sharedSchemas.js';
+
+export const FilterTextInputSchema = LocalizationTextSchema.describe('Filter localized text data');
+
+export const FilterOptionTextInputSchema = LocalizationTextSchema.extend({
+  title: z.string().optional().describe('Optional localized title for the filter option'),
+}).describe('Filter option localized text data');
+
+export const SortOptionInputSchema = z
+  .object({
+    key: z.string().min(1).describe('Field key to sort by (e.g., "key", "createdAt")'),
+    value: z.enum(['ASC', 'DESC']).describe('Sort direction: ASC for ascending, DESC for descending'),
+  })
+  .strict();
+
+export const CreateFilterInputSchema = z.object({
+  key: z.string().min(1).describe('Unique key for the filter'),
+  type: z.enum(['SWITCH', 'SINGLE_CHOICE', 'MULTI_CHOICE', 'RANGE']).describe('Type of the filter'),
+  options: z.array(z.string().min(1)).default([]).describe('Selectable options (if applicable)'),
+});
+
+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 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 actionValidators = {
+  CREATE: z.object({
+    filter: CreateFilterInputSchema.describe('Filter data'),
+    texts: z.array(FilterTextInputSchema).optional().describe('Localized text entries'),
+  }),
+
+  UPDATE: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+    updateData: UpdateFilterInputSchema.describe('Filter updates'),
+  }),
+
+  REMOVE: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+  }),
+
+  GET: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+  }),
+
+  LIST: z.object({
+    ...PaginationSchema,
+    ...SortingSchema,
+    ...SearchSchema,
+  }),
+
+  COUNT: z.object({
+    ...SearchSchema,
+  }),
+
+  CREATE_OPTION: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+    option: z.string().min(1).describe('Option value string - must be unique within the filter'),
+    optionTexts: z
+      .array(FilterOptionTextInputSchema)
+      .describe('Localized titles/subtitles - can be added later via UPDATE_TEXTS'),
+  }),
+
+  REMOVE_OPTION: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+    option: z.string().min(1).describe('Option value to remove'),
+  }),
+
+  UPDATE_TEXTS: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+    textUpdates: z
+      .array(FilterUpdateTextInputSchema)
+      .min(1)
+      .describe(
+        'Array of localized text updates - each entry contains locale, title, and optional subtitle',
+      ),
+    filterOptionValue: z
+      .string()
+      .optional()
+      .describe(
+        'Specific filter option value for text operations - omit to work with main filter texts',
+      ),
+  }),
+
+  GET_TEXTS: z.object({
+    filterId: z.string().min(1).describe('Unique filter identifier'),
+    filterOptionValue: z
+      .string()
+      .optional()
+      .describe('Specific filter option value - omit to get main filter texts'),
+  }),
+} as const;
+
+export const FilterManagementSchema = {
+  action: z
+    .enum([
+      'CREATE',
+      'UPDATE',
+      'REMOVE',
+      'GET',
+      'LIST',
+      'COUNT',
+      'CREATE_OPTION',
+      'REMOVE_OPTION',
+      'UPDATE_TEXTS',
+      'GET_TEXTS',
+    ])
+    .describe(
+      'Action to perform: CREATE (new filter), UPDATE (modify filter), REMOVE (delete filter), GET (retrieve filter), LIST (search filters), COUNT (count filters), CREATE_OPTION (add filter option), REMOVE_OPTION (delete filter option), UPDATE_TEXTS (modify localized texts), GET_TEXTS (retrieve localized texts)',
+    ),
+
+  filterId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Unique filter identifier. Required for: UPDATE, REMOVE, GET, CREATE_OPTION, REMOVE_OPTION, UPDATE_TEXTS, GET_TEXTS. Not needed for: CREATE, LIST, COUNT',
+    ),
+
+  filter: CreateFilterInputSchema.optional().describe('Filter data for CREATE action'),
+  texts: z.array(FilterTextInputSchema).optional().describe('Localized text entries for CREATE action'),
+
+  updateData: UpdateFilterInputSchema.optional().describe('Filter updates for UPDATE action'),
+
+  ...PaginationSchema,
+  ...SortingSchema,
+  ...SearchSchema,
+
+  option: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Option value string for CREATE_OPTION/REMOVE_OPTION actions. Must be unique within the filter',
+    ),
+  optionTexts: z
+    .array(FilterOptionTextInputSchema)
+    .optional()
+    .describe(
+      'Localized titles/subtitles for CREATE_OPTION action. Optional - can be added later via UPDATE_TEXTS',
+    ),
+
+  filterOptionValue: z
+    .string()
+    .optional()
+    .describe(
+      'Specific filter option value for text operations (UPDATE_TEXTS/GET_TEXTS). Omit to work with main filter texts',
+    ),
+  textUpdates: z
+    .array(FilterUpdateTextInputSchema)
+    .optional()
+    .describe(
+      'Array of localized text updates for UPDATE_TEXTS action. Each entry contains locale, title, and optional subtitle',
+    ),
+};
+
+export const FilterManagementZodSchema = z.object(FilterManagementSchema);
+export type FilterManagementParams = z.infer<typeof FilterManagementZodSchema>;
+
+export type ActionName = keyof typeof actionValidators;
+export type Params<T extends ActionName> = z.infer<(typeof actionValidators)[T]>;
+export type Handler<T extends ActionName> = (filterModule: any, params: Params<T>) => Promise<unknown>;

package/src/mcp/tools/localization/getLocalizationsConfig.ts

@@ -0,0 +1,45 @@
+import { Context } from 'vm';
+import { CountryNotFoundError, CurrencyNotFoundError, LanguageNotFoundError } from '../../../errors.js';
+import { LocalizationType, LocalizationModuleConfig } from './types.js';
+
+export const getLocalizationsConfig = (
+  context: Context,
+  localizationType: LocalizationType,
+): LocalizationModuleConfig => {
+  const { modules } = context;
+
+  switch (localizationType) {
+    case 'COUNTRY':
+      return {
+        module: modules.countries,
+        NotFoundError: CountryNotFoundError,
+        entityName: 'country',
+        idField: 'countryId',
+        existsMethod: modules.countries.countryExists,
+        findMethod: modules.countries.findCountry,
+        findMultipleMethod: modules.countries.findCountries,
+      };
+    case 'CURRENCY':
+      return {
+        module: modules.currencies,
+        NotFoundError: CurrencyNotFoundError,
+        entityName: 'currency',
+        idField: 'currencyId',
+        existsMethod: modules.currencies.currencyExists,
+        findMethod: modules.currencies.findCurrency,
+        findMultipleMethod: modules.currencies.findCurrencies,
+      };
+    case 'LANGUAGE':
+      return {
+        module: modules.languages,
+        NotFoundError: LanguageNotFoundError,
+        entityName: 'language',
+        idField: 'languageId',
+        existsMethod: modules.languages.languageExists,
+        findMethod: modules.languages.findLanguage,
+        findMultipleMethod: modules.languages.findLanguages,
+      };
+    default:
+      throw new Error(`Unknown localization type: ${localizationType}`);
+  }
+};

package/src/mcp/tools/localization/handlers/countLocalizations.ts

@@ -0,0 +1,15 @@
+import { Context } from '../../../../context.js';
+import { getLocalizationsConfig } from '../getLocalizationsConfig.js';
+import { Params } from '../schemas.js';
+
+export default async function countLocalizations(context: Context, params: Params<'COUNT'>) {
+  const { localizationType, includeInactive = false, queryString } = params;
+  const config = getLocalizationsConfig(context, localizationType);
+
+  const count = await config.module.count({
+    includeInactive,
+    queryString,
+  });
+
+  return { count, localizationType };
+}

package/src/mcp/tools/localization/handlers/createLocalization.ts

@@ -0,0 +1,21 @@
+import { Context } from '../../../../context.js';
+import sanitizeEntityData from '../../../utils/sanitizeLocalizationEntityData.js';
+import validateIsoCode from '../../../utils/validateIsoCode.js';
+import { getLocalizationsConfig } from '../getLocalizationsConfig.js';
+
+import { Params } from '../schemas.js';
+
+export default async function createLocalization(context: Context, params: Params<'CREATE'>) {
+  const { localizationType, entity } = params;
+  const config = getLocalizationsConfig(context, localizationType);
+
+  const sanitizedEntity = sanitizeEntityData(localizationType, entity);
+  if (sanitizedEntity.isoCode) {
+    sanitizedEntity.isoCode = validateIsoCode(localizationType, sanitizedEntity.isoCode);
+  }
+
+  const entityId = await config.module.create(sanitizedEntity as any);
+  const newEntity = await config.findMethod({ [config.idField]: entityId });
+
+  return { [config.entityName]: newEntity };
+}

package/src/mcp/tools/localization/handlers/getLocalization.ts

@@ -0,0 +1,15 @@
+import { Context } from '../../../../context.js';
+import { getLocalizationsConfig } from '../getLocalizationsConfig.js';
+import { Params } from '../schemas.js';
+
+export default async function getLocalization(context: Context, params: Params<'GET'>) {
+  const { localizationType, entityId } = params;
+  const config = getLocalizationsConfig(context, localizationType);
+  const entity = await config.findMethod({ [config.idField]: entityId });
+
+  if (!entity) {
+    return { [config.entityName]: null, message: `${localizationType} not found for ID: ${entityId}` };
+  }
+
+  return { [config.entityName]: entity, localizationType };
+}

package/src/mcp/tools/localization/handlers/index.ts

@@ -0,0 +1,15 @@
+import createLocalization from './createLocalization.js';
+import updateLocalization from './updateLocalization.js';
+import removeLocalization from './removeLocalization.js';
+import getLocalization from './getLocalization.js';
+import listLocalizations from './listLocalizations.js';
+import countLocalizations from './countLocalizations.js';
+
+export default {
+  CREATE: createLocalization,
+  UPDATE: updateLocalization,
+  REMOVE: removeLocalization,
+  GET: getLocalization,
+  LIST: listLocalizations,
+  COUNT: countLocalizations,
+};

package/src/mcp/tools/localization/handlers/listLocalizations.ts

@@ -0,0 +1,36 @@
+import { Context } from '../../../../context.js';
+import { getLocalizationsConfig } from '../getLocalizationsConfig.js';
+import { Params } from '../schemas.js';
+
+export default async function listLocalizations(context: Context, params: Params<'LIST'>) {
+  const {
+    localizationType,
+    limit = 50,
+    offset = 0,
+    includeInactive = false,
+    queryString,
+    sort,
+  } = params;
+  const config = getLocalizationsConfig(context, localizationType);
+
+  const sortOptions =
+    sort?.filter((s): s is { key: string; value: 'ASC' | 'DESC' } => Boolean(s.key && s.value)) ||
+    undefined;
+
+  const entities = await config.findMultipleMethod({
+    limit,
+    offset,
+    includeInactive,
+    queryString,
+    sort: sortOptions,
+  });
+
+  const mapper = {
+    COUNTRY: 'countries',
+    CURRENCY: 'currencies',
+    LANGUAGE: 'languages',
+  };
+  const pluralEntityName = mapper[localizationType] || `${config.entityName}s`;
+
+  return { [pluralEntityName]: entities, localizationType };
+}

package/src/mcp/tools/localization/handlers/removeLocalization.ts

@@ -0,0 +1,15 @@
+import { Context } from '../../../../context.js';
+import { getLocalizationsConfig } from '../getLocalizationsConfig.js';
+import { Params } from '../schemas.js';
+
+export default async function removeLocalization(context: Context, params: Params<'REMOVE'>) {
+  const { localizationType, entityId } = params;
+  const config = getLocalizationsConfig(context, localizationType);
+  const findParam = { [config.idField]: entityId };
+  const existing = await config.findMethod(findParam);
+
+  if (!existing) throw new config.NotFoundError(findParam);
+
+  await config.module.delete(entityId);
+  return { success: true };
+}

package/src/mcp/tools/localization/handlers/updateLocalization.ts

@@ -0,0 +1,21 @@
+import { Context } from '../../../../context.js';
+import sanitizeEntityData from '../../../utils/sanitizeLocalizationEntityData.js';
+import { getLocalizationsConfig } from '../getLocalizationsConfig.js';
+
+import { Params } from '../schemas.js';
+
+export default async function updateLocalization(context: Context, params: Params<'UPDATE'>) {
+  const { localizationType, entityId, entity } = params;
+  const config = getLocalizationsConfig(context, localizationType);
+  const existsParam = { [config.idField]: entityId };
+
+  if (!(await config.existsMethod(existsParam))) {
+    throw new config.NotFoundError(existsParam);
+  }
+
+  const updateData = sanitizeEntityData(localizationType, entity);
+  await config.module.update(entityId, updateData);
+  const updatedEntity = await config.findMethod(existsParam);
+
+  return { [config.entityName]: updatedEntity };
+}

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

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import { localizationManagement, LocalizationManagementSchema } from './localizationManagement.js';
+
+export const registerLocalizationTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'localization_management',
+    'Unified localization management tool for localization operations across geographic, monetary, and language entities. Countries use 2-letter codes (US, DE, FR), currencies use 3-letter codes (USD, EUR, CHF) with optional blockchain support, languages use locale codes (en, de-CH).. Actions: CREATE (add new), UPDATE (modify existing), REMOVE (delete).',
+    LocalizationManagementSchema,
+    async (params) => localizationManagement(context, params),
+  );
+};

package/src/mcp/tools/localization/localizationManagement.ts

@@ -0,0 +1,35 @@
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import {
+  actionValidators,
+  LocalizationManagementSchema,
+  LocalizationManagementZodSchema,
+  LocalizationManagementParams,
+  ActionName,
+} from './schemas.js';
+import actionHandlers from './handlers/index.js';
+import { createMcpErrorResponse, createMcpResponse } from '../../utils/sharedSchemas.js';
+
+export { LocalizationManagementSchema, LocalizationManagementZodSchema, LocalizationManagementParams };
+
+export async function localizationManagement(context: Context, params: LocalizationManagementParams) {
+  const { action, ...actionParams } = params;
+  log('MCP localizationManagement', { userId: context.userId, params });
+
+  try {
+    if (!(action in actionHandlers)) {
+      throw new Error(`Unknown action: ${action}`);
+    }
+
+    const parsedParams = actionValidators[action as ActionName].parse(actionParams);
+    const data = await actionHandlers[action as ActionName](context, parsedParams as never);
+
+    return createMcpResponse({
+      action,
+      data,
+      localizationType: actionParams.localizationType,
+    });
+  } catch (error) {
+    return createMcpErrorResponse(action, error);
+  }
+}