@unchainedshop/api 4.0.0-rc.3 → 4.0.0-rc.4

package/src/mcp/index.ts

@@ -69,6 +69,99 @@ import {
   productReviewsCountHandler,
   ProductReviewsSchema,
   productReviewsHandler,
+  TranslatedProductTextsSchema,
+  translatedProductTextsHandler,
+  TranslatedProductMediaTextsSchema,
+  translatedProductMediaTextsHandler,
+  TranslatedProductVariationTextsSchema,
+  translatedProductVariationTextsHandler,
+  shopInfoHandler,
+  CreateCountrySchema,
+  createCountryHandler,
+  UpdateCountrySchema,
+  updateCountryHandler,
+  RemoveCountrySchema,
+  removeCountryHandler,
+  CountriesCountSchema,
+  countriesCountHandler,
+  CreateCurrencySchema,
+  createCurrencyHandler,
+  UpdateCurrencySchema,
+  updateCurrencyHandler,
+  RemoveCurrencySchema,
+  removeCurrencyHandler,
+  CurrenciesCountSchema,
+  currenciesCountHandler,
+  LanguagesCountSchema,
+  languagesCountHandler,
+  CreateAssortmentSchema,
+  createAssortmentHandler,
+  AssortmentsSchema,
+  assortmentsHandler,
+  AssortmentsCountSchema,
+  assortmentsCountHandler,
+  AssortmentSchema,
+  assortmentHandler,
+  UpdateAssortmentSchema,
+  updateAssortmentHandler,
+  RemoveAssortmentSchema,
+  removeAssortmentHandler,
+  SetBaseAssortmentSchema,
+  setBaseAssortmentHandler,
+  AssortmentChildrenSchema,
+  assortmentChildrenHandler,
+  assortmentProductsHandler,
+  AssortmentProductsSchema,
+  searchAssortmentProductHandler,
+  SearchAssortmentProductSchema,
+  AssortmentLinksSchema,
+  assortmentLinksHandler,
+  AssortmentFiltersSchema,
+  assortmentFiltersHandler,
+  AddAssortmentProductSchema,
+  addAssortmentProductHandler,
+  RemoveAssortmentProductSchema,
+  removeAssortmentProductHandler,
+  ReorderAssortmentProductsSchema,
+  reorderAssortmentProductsHandler,
+  AddAssortmentLinkSchema,
+  addAssortmentLinkHandler,
+  RemoveAssortmentLinkSchema,
+  removeAssortmentLinkHandler,
+  ReorderAssortmentMediaSchema,
+  reorderAssortmentMediaHandler,
+  RemoveAssortmentMediaSchema,
+  removeAssortmentMediaHandler,
+  AddAssortmentMediaUploadSchema,
+  addAssortmentMediaUploadHandler,
+  CreateFilterSchema,
+  createFilterHandler,
+  UpdateFilterSchema,
+  updateFilterHandler,
+  RemoveFilterSchema,
+  removeFilterHandler,
+  CreateFilterOptionSchema,
+  createFilterOptionHandler,
+  UpdateFilterTextsSchema,
+  updateFilterTextsHandler,
+  RemoveFilterOptionSchema,
+  removeFilterOptionHandler,
+  GetFilterSchema,
+  getFilterHandler,
+  GetFiltersSchema,
+  getFiltersHandler,
+  TranslatedFilterTextsSchema,
+  translatedFilterTextsHandler,
+  TranslatedAssortmentMediaTextsSchema,
+  translatedAssortmentMediaTextsHandler,
+  TranslatedAssortmentTextsSchema,
+  translatedAssortmentTextsHandler,
+  AddAssortmentFilterSchema,
+  addAssortmentFilterHandler,
+  RemoveAssortmentFilterSchema,
+  removeAssortmentFilterHandler,
+  ReorderAssortmentFiltersSchema,
+  reorderAssortmentFiltersHandler,
 } from './tools/index.js';
 
 export default function createMcpServer(context: Context, roles) {
@@ -83,7 +176,7 @@ export default function createMcpServer(context: Context, roles) {
 
   server.tool(
     'list_products',
-    'Search and list products with comprehensive filtering and pagination support',
+    `Search and list products with comprehensive filtering, sorting, and pagination support.`,
     ListProductsSchema,
     async (params) => listProductsHandler(context, params),
   );
@@ -173,7 +266,7 @@ export default function createMcpServer(context: Context, roles) {
 
   server.tool(
     'list_currencies',
-    'List all available currencies in the system, when currency is required and not implicitly provided use this tool to get the list of available currencies also if non existing currency is provided to you by a user inform them it does not exist and to create it first before they can use it',
+    'List all available currencies in the system, if non existing currency is provided to you by a user inform them it does not exist and to create it first before they can use it',
     ListCurrenciesSchema,
     async (params) => currenciesHandler(context, params),
   );
@@ -187,7 +280,7 @@ export default function createMcpServer(context: Context, roles) {
 
   server.tool(
     'list_countries',
-    'List all available countries in the system, when country is required and not implicitly provided use this tool to get the list of available countries also if non existing country is provided to you by a user inform them it does not exist and to create it first before they can use it',
+    'List all available countries in the system, if non existing country is provided to you by a user inform them it does not exist and to create it first before they can use it',
     ListCountriesSchema,
     async (params) => countriesHandler(context, params),
   );
@@ -201,7 +294,7 @@ export default function createMcpServer(context: Context, roles) {
 
   server.tool(
     'list_languages',
-    'List all available languages in the system, when language is required and not implicitly provided use this tool to get the list of available languages also if non existing language is provided to you by a user inform them it does not exist and to create it first before they can use it',
+    'List all available languages in the system, if non existing language is provided to you by a user inform them it does not exist and to create it first before they can use it',
     ListLanguagesSchema,
     async (params) => languagesHandler(context, params),
   );
@@ -304,10 +397,322 @@ export default function createMcpServer(context: Context, roles) {
 
   server.tool(
     'product_reviews',
-    ' Get all product reviews, by default sorted by creation date (descending)',
+    'Get all product reviews, by default sorted by creation date (descending)',
     ProductReviewsSchema,
     async (params) => productReviewsHandler(context, params),
   );
+  server.tool(
+    'product_localized_texts',
+    'Returns Localization: Meta data for product',
+    TranslatedProductTextsSchema,
+    async (params) => translatedProductTextsHandler(context, params),
+  );
+
+  server.tool(
+    'product_media_localized_texts',
+    'Returns Localization: Meta data for product media',
+    TranslatedProductMediaTextsSchema,
+    async (params) => translatedProductMediaTextsHandler(context, params),
+  );
+
+  server.tool(
+    'product_variation_localized_texts',
+    'Returns Localization: Meta data for product variation',
+    TranslatedProductVariationTextsSchema,
+    async (params) => translatedProductVariationTextsHandler(context, params),
+  );
+  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),
+  );
+
+  server.tool(
+    'add_country',
+    'Adds new country information to the system',
+    CreateCountrySchema,
+    async (params) => createCountryHandler(context, params),
+  );
+
+  server.tool(
+    'update_country',
+    'Updates provided country information',
+    UpdateCountrySchema,
+    async (params) => updateCountryHandler(context, params),
+  );
+
+  server.tool('delete_country', 'Deletes the specified country', RemoveCountrySchema, async (params) =>
+    removeCountryHandler(context, params),
+  );
+
+  server.tool(
+    'countries_count',
+    'Returns total number of countries registered in the system',
+    CountriesCountSchema,
+    async (params) => countriesCountHandler(context, params),
+  );
+
+  server.tool(
+    'add_currency',
+    'Adds new currency information to the system',
+    CreateCurrencySchema,
+    async (params) => createCurrencyHandler(context, params),
+  );
+  server.tool(
+    'update_currency',
+    'Updates the specified currency in the system',
+    UpdateCurrencySchema,
+    async (params) => updateCurrencyHandler(context, params),
+  );
+
+  server.tool(
+    'delete_currency',
+    'Deletes the specified currency from the system',
+    RemoveCurrencySchema,
+    async (params) => removeCurrencyHandler(context, params),
+  );
+
+  server.tool(
+    'currencies_count',
+    'Returns total number of currencies registered in the system',
+    CurrenciesCountSchema,
+    async (params) => currenciesCountHandler(context, params),
+  );
+
+  server.tool(
+    'languages_count',
+    'Returns total number of languages registered in the system',
+    LanguagesCountSchema,
+    async (params) => languagesCountHandler(context, params),
+  );
+
+  server.tool('add_assortment', 'Creates new assortment', CreateAssortmentSchema, async (params) =>
+    createAssortmentHandler(context, params),
+  );
+
+  server.tool(
+    'update_assortment',
+    'Updates the details of an existing assortment such as tags, active state, root status, or sort order.',
+    UpdateAssortmentSchema,
+    async (params) => updateAssortmentHandler(context, params),
+  );
+
+  server.tool(
+    'delete_assortment',
+    'Removes assortment with the provided ID',
+    RemoveAssortmentSchema,
+    async (params) => removeAssortmentHandler(context, params),
+  );
+
+  server.tool(
+    'set_assortment_base',
+    'Makes the assortment provided as the base assortment and make any other existing base assortment regular assortments.',
+    SetBaseAssortmentSchema,
+    async (params) => setBaseAssortmentHandler(context, params),
+  );
+
+  server.tool(
+    'get_assortment',
+    'Get a specific assortment by ID or slug',
+    AssortmentSchema,
+    async (params) => assortmentHandler(context, params),
+  );
+
+  server.tool(
+    'list_assortments',
+    'Search and list assortments with comprehensive filtering, sorting, and pagination support.',
+    AssortmentsSchema,
+    async (params) => assortmentsHandler(context, params),
+  );
+
+  server.tool(
+    'assortments_count',
+    'Returns total number of assortments that match a given criteria or all if no criteria is given',
+    AssortmentsCountSchema,
+    async (params) => assortmentsCountHandler(context, params),
+  );
+
+  server.tool(
+    'assortment_children',
+    'Returns child assortments of the specified assortmentID',
+    AssortmentChildrenSchema,
+    async (params) => assortmentChildrenHandler(context, params),
+  );
+
+  server.tool(
+    'assortment_products',
+    'Returns products assigned to the specified assortmentID',
+    AssortmentProductsSchema,
+    async (params) => assortmentProductsHandler(context, params),
+  );
+
+  server.tool(
+    'search_assortment_products',
+    'searches products assigned to the specified assortment using various parameters',
+    SearchAssortmentProductSchema,
+    async (params) => searchAssortmentProductHandler(context, params),
+  );
+
+  server.tool(
+    'assortment_links',
+    'return all the linked assortment of the specified assortment ID including all hierarchy',
+    AssortmentLinksSchema,
+    async (params) => assortmentLinksHandler(context, params),
+  );
+
+  server.tool(
+    'assortment_filters',
+    'Returns filters assigned to the specified assortmentID',
+    AssortmentFiltersSchema,
+    async (params) => assortmentFiltersHandler(context, params),
+  );
+
+  server.tool(
+    'add_assortment_product',
+    'Add a new product to an assortment',
+    AddAssortmentProductSchema,
+    async (params) => addAssortmentProductHandler(context, params),
+  );
+
+  server.tool(
+    'remove_assortment_product',
+    'Remove a product from an assortment',
+    RemoveAssortmentProductSchema,
+    async (params) => removeAssortmentProductHandler(context, params),
+  );
+
+  server.tool(
+    'reorder_assortment_products',
+    'Reorder sort sequence of products in an assortment',
+    ReorderAssortmentProductsSchema,
+    async (params) => reorderAssortmentProductsHandler(context, params),
+  );
+
+  server.tool(
+    'add_assortment_link',
+    'Add a new child assortment to an assortment',
+    AddAssortmentLinkSchema,
+    async (params) => addAssortmentLinkHandler(context, params),
+  );
+
+  server.tool(
+    'remove_assortment_link',
+    `Removes a child/parent assortment link from it's parent`,
+    RemoveAssortmentLinkSchema,
+    async (params) => removeAssortmentLinkHandler(context, params),
+  );
+
+  server.tool(
+    'reorder_assortment_links',
+    ` Reorders the assortment links in parent assortment`,
+    RemoveAssortmentLinkSchema,
+    async (params) => removeAssortmentLinkHandler(context, params),
+  );
+
+  server.tool(
+    'reorder_assortment_medias',
+    `Reorders the assortment medias`,
+    ReorderAssortmentMediaSchema,
+    async (params) => reorderAssortmentMediaHandler(context, params),
+  );
+
+  server.tool(
+    'add_assortment_media',
+    `Add a media asset to a assortment`,
+    RemoveAssortmentMediaSchema,
+    async (params) => removeAssortmentMediaHandler(context, params),
+  );
+  server.tool(
+    'remove_assortment_media',
+    `Remove a media asset from a assortment`,
+    AddAssortmentMediaUploadSchema,
+    async (params) => addAssortmentMediaUploadHandler(context, params),
+  );
+
+  server.tool('add_filter', `Creates new Filter`, CreateFilterSchema, async (params) =>
+    createFilterHandler(context, params),
+  );
+  server.tool('update_filter', `Update filter information`, UpdateFilterSchema, async (params) =>
+    updateFilterHandler(context, params),
+  );
+
+  server.tool('remove_filter', ` Deletes the specified filter`, RemoveFilterSchema, async (params) =>
+    removeFilterHandler(context, params),
+  );
+  server.tool(
+    'add_filter_option',
+    `Adds new option to filters`,
+    CreateFilterOptionSchema,
+    async (params) => createFilterOptionHandler(context, params),
+  );
+
+  server.tool(
+    'update_filter_texts',
+    `Updates or created specified filter texts for filter with ID provided and locale and optionally filterOptionValue`,
+    UpdateFilterTextsSchema,
+    async (params) => updateFilterTextsHandler(context, params),
+  );
+
+  server.tool(
+    'remove_filter_option',
+    `Removes the filter option from the specified filter.`,
+    RemoveFilterOptionSchema,
+    async (params) => removeFilterOptionHandler(context, params),
+  );
+
+  server.tool('get_filter', `Get a specific filter by ID`, GetFilterSchema, async (params) =>
+    getFilterHandler(context, params),
+  );
+
+  server.tool(
+    'list_filters',
+    `Get all filters, by default sorted by creation date (ascending), optionally it can filter based on various parameters including querystring`,
+    GetFiltersSchema,
+    async (params) => getFiltersHandler(context, params),
+  );
+
+  server.tool(
+    'filter_localized_texts',
+    `Returns localized filter texts found in the system for the specified filterId`,
+    TranslatedFilterTextsSchema,
+    async (params) => translatedFilterTextsHandler(context, params),
+  );
+
+  server.tool(
+    'assortment_media_localized_texts',
+    'Returns localized assortment media texts found in the system for the specified assortmentId',
+    TranslatedAssortmentMediaTextsSchema,
+    async (params) => translatedAssortmentMediaTextsHandler(context, params),
+  );
+
+  server.tool(
+    'assortment_localized_texts',
+    'Returns localized assortment texts found in the system for the specified assortmentId',
+    TranslatedAssortmentTextsSchema,
+    async (params) => translatedAssortmentTextsHandler(context, params),
+  );
+
+  server.tool(
+    'add_assortment_filter',
+    'Add/attach/link a filter to an assortment',
+    AddAssortmentFilterSchema,
+    async (params) => addAssortmentFilterHandler(context, params),
+  );
+
+  server.tool(
+    'remove_assortment_filter',
+    'Removes/unlinks a filter from assortment',
+    RemoveAssortmentFilterSchema,
+    async (params) => removeAssortmentFilterHandler(context, params),
+  );
+
+  server.tool(
+    'reorder_assortment_filters',
+    'Reorders the assortment filters',
+    ReorderAssortmentFiltersSchema,
+    async (params) => reorderAssortmentFiltersHandler(context, params),
+  );
 
   return server;
 }

package/src/mcp/tools/assortment/addAssortmentFilterHandler.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { AssortmentNotFoundError, FilterNotFoundError } from '../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+import { getNormalizedFilterDetails } from '../../utils/getNormalizedFilterDetails.js';
+
+export const AddAssortmentFilterSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment'),
+  filterId: z.string().min(1).describe('ID of the filter to add'),
+  tags: z
+    .array(z.string().regex(/^[a-z0-9-_]+$/))
+    .optional()
+    .describe('Optional lowercase tags'),
+};
+
+export const AddAssortmentFilterZodSchema = z.object(AddAssortmentFilterSchema);
+
+export type AddAssortmentFilterParams = z.infer<typeof AddAssortmentFilterZodSchema>;
+
+export async function addAssortmentFilterHandler(context: Context, params: AddAssortmentFilterParams) {
+  const { assortmentId, filterId, tags = [] } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler addAssortmentFilter', { userId, assortmentId, filterId, tags });
+    const assortment = await getNormalizedAssortmentDetails({ assortmentId }, context);
+    if (!assortment) throw new AssortmentNotFoundError({ assortmentId });
+    const filter = await getNormalizedFilterDetails(filterId, context);
+    if (!filter) throw new FilterNotFoundError({ filterId });
+
+    const assortmentFilter = await modules.assortments.filters.create({
+      assortmentId,
+      filterId,
+      tags,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            assortmentFilter: {
+              ...assortmentFilter,
+              filter,
+              assortment,
+            },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error adding filter to assortment: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/addAssortmentLinkHandler.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+import { AssortmentNotFoundError } from '../../../errors.js';
+
+export const AddAssortmentLinkSchema = {
+  parentAssortmentId: z.string().min(1).describe('ID of the parent assortment'),
+  childAssortmentId: z.string().min(1).describe('ID of the child assortment'),
+  tags: z.array(z.string().min(1)).default([]).describe('Tags for the link'),
+};
+
+export const AddAssortmentLinkZodSchema = z.object(AddAssortmentLinkSchema);
+
+export type AddAssortmentLinkParams = z.infer<typeof AddAssortmentLinkZodSchema>;
+
+export async function addAssortmentLinkHandler(context: Context, params: AddAssortmentLinkParams) {
+  const { parentAssortmentId, childAssortmentId, tags } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler addAssortmentLink', {
+      userId,
+      parentAssortmentId,
+      childAssortmentId,
+      tags,
+    });
+    const parent = await getNormalizedAssortmentDetails({ assortmentId: parentAssortmentId }, context);
+    if (!parent)
+      throw new AssortmentNotFoundError({
+        assortmentId: parentAssortmentId,
+      });
+    const child = await getNormalizedAssortmentDetails({ assortmentId: childAssortmentId }, context);
+    if (!child)
+      throw new AssortmentNotFoundError({
+        assortmentId: childAssortmentId,
+      });
+
+    const result = await modules.assortments.links.create({
+      parentAssortmentId,
+      childAssortmentId,
+      tags,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ assortmentLink: { ...result, parent, child } }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error adding assortment link: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/addAssortmentMediaUploadHandler.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FileNotFoundError, FileUploadExpiredError } from '../../../errors.js';
+
+export const AddAssortmentMediaUploadSchema = {
+  mediaName: z
+    .string()
+    .min(1)
+    .describe('Name of the media file (e.g. "image.png") use random name if not provided'),
+  assortmentId: z.string().min(1).describe('ID of the assortment to link media to'),
+  url: z.string().describe('Anonymously fetchable URL of the source media, can be a data URL too'),
+};
+
+export const AddAssortmentMediaUploadZodSchema = z.object(AddAssortmentMediaUploadSchema);
+
+export type AddAssortmentMediaUploadParams = z.infer<typeof AddAssortmentMediaUploadZodSchema>;
+
+export async function addAssortmentMediaUploadHandler(
+  context: Context,
+  params: AddAssortmentMediaUploadParams,
+) {
+  const { mediaName, assortmentId, url } = params;
+  const { modules, services, userId } = context;
+
+  try {
+    log('handler addAssortmentMediaUploadHandler', { mediaName, assortmentId, userId, url });
+    const {
+      _id: fileId,
+      putURL,
+      type,
+      size,
+    } = await services.files.createSignedURL({
+      directoryName: 'assortment-media',
+      fileName: mediaName,
+      meta: { assortmentId },
+    });
+
+    const sourceResponse = await fetch(url);
+    const uploadUrl = new URL(putURL, process.env.ROOT_URL || 'http://localhost:4010');
+    const uploadResponse = await fetch(uploadUrl, {
+      method: 'PUT',
+      body: sourceResponse.body,
+      duplex: 'half',
+    } as RequestInit);
+
+    if (!uploadResponse.ok) {
+      throw new Error(`Upload failed: ${uploadResponse.status} ${uploadResponse.statusText}`);
+    }
+
+    const file = await modules.files.findFile({ fileId });
+    if (!file) throw new FileNotFoundError({ fileId });
+
+    if (file.expires && new Date(file.expires).getTime() < Date.now()) {
+      throw new FileUploadExpiredError({ fileId });
+    }
+    const linked = await services.files.linkFile({ fileId, size, type });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            file: linked,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error uploading Assortment media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}