@unchainedshop/api 3.1.13 → 4.0.0-rc.3

package/src/loaders/productTextLoader.ts

@@ -0,0 +1,22 @@
+import { UnchainedCore } from '@unchainedshop/core';
+import DataLoader from 'dataloader';
+import { ProductText } from '@unchainedshop/core-products';
+import buildTextMap from './buildTextMap.js';
+import buildLocaleMap from './buildLocaleMap.js';
+
+export default (unchainedAPI: UnchainedCore) =>
+  new DataLoader<{ productId: string; locale: Intl.Locale }, ProductText>(async (queries) => {
+    const productIds = [...new Set(queries.map((q) => q.productId))].filter(Boolean);
+    const texts = await unchainedAPI.modules.products.texts.findTexts(
+      { productId: { $in: productIds } },
+      {
+        sort: {
+          productId: 1,
+        },
+      },
+    );
+    const localeMap = buildLocaleMap(queries, texts);
+    const textsMap = buildTextMap(localeMap, texts, (text) => text.productId);
+
+    return queries.map((q) => textsMap[q.locale + q.productId]);
+  });

package/src/loaders/userLoader.ts

@@ -0,0 +1,23 @@
+import { UnchainedCore } from '@unchainedshop/core';
+import { User } from '@unchainedshop/core-users';
+import DataLoader from 'dataloader';
+
+export default (unchainedAPI: UnchainedCore) =>
+  new DataLoader<{ userId: string }, User>(async (queries) => {
+    const userIds = [...new Set(queries.map((q) => q.userId).filter(Boolean))];
+
+    // It's important to also fetch deleted with the loader,
+    // because the loader fetches entities by id.
+    const users = await unchainedAPI.modules.users.findUsers({
+      includeGuests: true,
+      includeDeleted: true,
+      _id: { $in: userIds },
+    });
+
+    const userMap = {};
+    for (const user of users) {
+      userMap[user._id] = user;
+    }
+
+    return queries.map((q) => userMap[q.userId]);
+  });

package/src/loaders/utils.ts

@@ -0,0 +1,35 @@
+import { systemLocale } from '@unchainedshop/utils';
+
+export function getLocaleStrings(locale: Intl.Locale) {
+  try {
+    return [
+      ...new Set([locale.baseName, locale.language, systemLocale.baseName, systemLocale.language]),
+    ];
+  } catch {
+    return [...new Set([systemLocale.baseName, systemLocale.language])];
+  }
+}
+
+export function buildLocaleMap(
+  queries: readonly { locale: Intl.Locale }[],
+  texts: readonly { locale?: string }[],
+): Record<string, string[]> {
+  // key = texts.locale
+  // value = input query locale
+
+  const queryLocales = Object.values(
+    Object.fromEntries(queries.map((q) => [q.locale.baseName, q.locale])),
+  );
+
+  const textLocales: string[] = [...new Set(texts.map((t) => t.locale))];
+  const localeMap = {};
+  for (const queryLocale of queryLocales) {
+    const potentialMatches = getLocaleStrings(queryLocale);
+    const matches = potentialMatches.filter((l) => textLocales.includes(l));
+    for (const match of matches) {
+      if (!localeMap[match]) localeMap[match] = [];
+      localeMap[match].push(queryLocale);
+    }
+  }
+  return localeMap;
+}

package/src/locale-context.ts

@@ -12,15 +12,13 @@ import { createLogger } from '@unchainedshop/logger';
 const logger = createLogger('unchained:api');
 
 export interface UnchainedLocaleContext {
-  countryContext: string;
-  localeContext: Intl.Locale;
-  currencyContext: string;
+  countryCode: string;
+  locale: Intl.Locale;
+  currencyCode: string;
 }
-const { NODE_ENV } = process.env;
-
 export type GetHeaderFn = (key: string) => string | string[];
 
-const memoizeCache = new ExpiryMap(NODE_ENV === 'production' ? 1000 * 60 : 100); // Cached values expire after 10 seconds
+const memoizeCache = new ExpiryMap(process.env.NODE_ENV === 'production' ? 1000 * 60 : 1); // Cached values expire after 10 seconds
 
 export const resolveDefaultContext = pMemoize(
   async ({ acceptLang, acceptCountry }, unchainedAPI) => {
@@ -36,31 +34,27 @@ export const resolveDefaultContext = pMemoize(
 
     const currencies = await unchainedAPI.modules.currencies.findCurrencies({ includeInactive: false });
 
-    const supportedLocaleStrings: Array<string> = languages.reduce((accumulator, language) => {
+    const defaultCurrencyCodes = Object.fromEntries(
+      countries.map((c) => [c.isoCode, c.defaultCurrencyCode]),
+    );
+
+    const supportedLocaleStrings: string[] = languages.reduce((accumulator, language) => {
       const added = countries.map((country) => {
         return `${language.isoCode}-${country.isoCode}`;
       });
       return accumulator.concat(added);
     }, []);
 
-    const localeContext = resolveBestSupported(
-      acceptLang,
-      supportedLocaleStrings,
-      systemLocale.baseName,
-    );
-    const countryContext = resolveBestCountry(localeContext.region, acceptCountry, countries);
-
-    const countryObject = countries.find((country) => country.isoCode === countryContext);
-    const currencyContext = resolveBestCurrency(countryObject.defaultCurrencyCode, currencies);
+    const locale = resolveBestSupported(acceptLang, supportedLocaleStrings, systemLocale.baseName);
+    const countryCode = resolveBestCountry(locale.region, acceptCountry, countries);
+    const currencyCode = resolveBestCurrency(defaultCurrencyCodes[countryCode], currencies);
 
-    logger.debug(
-      `Locale Context: Resolved ${localeContext.baseName} ${countryContext} ${currencyContext}`,
-    );
+    logger.debug(`Locale Context: Resolved ${locale.baseName} ${countryCode} ${currencyCode}`);
 
     const newContext: UnchainedLocaleContext = {
-      localeContext,
-      countryContext,
-      currencyContext,
+      locale,
+      countryCode,
+      currencyCode,
     };
 
     return newContext;

package/src/mcp/README.md

@@ -0,0 +1,25 @@
+# MCP Server
+
+This directory contains the Model Context Protocol (MCP) server implementation for Unchained Commerce.
+
+## Structure
+
+```
+mcp/
+├── index.ts              # Main MCP server setup
+├── types.ts              # Shared type definitions
+├── tools/                # Individual tool implementations
+│   ├── index.ts          # Re-exports for all tools
+│   └── listProducts.ts   # List products tool
+└── utils/                # Shared utilities
+    └── html.ts           # HTML generation utilities
+```
+
+## Adding New Tools
+
+To add a new tool:
+
+1. Create a new file in the `tools/` directory
+2. Export the schema and handler from the file
+3. Add the exports to `tools/index.ts`
+4. Register the tool in the main `index.ts` file

package/src/mcp/index.ts

@@ -0,0 +1,313 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../context.js';
+import {
+  listProductsHandler,
+  ListProductsSchema,
+  getProductHandler,
+  GetProductSchema,
+  createProductHandler,
+  CreateProductSchema,
+  RemoveProductSchema,
+  removeProductHandler,
+  PublishProductSchema,
+  publishProductHandler,
+  UnpublishProductSchema,
+  unpublishProductHandler,
+  UpdateProductSchema,
+  updateProductHandler,
+  UpdateProductTextsSchema,
+  updateProductTextsHandler,
+  UpdateProductCommerceSchema,
+  updateProductCommerceHandler,
+  ListCurrenciesSchema,
+  currenciesHandler,
+  CurrencySchema,
+  currencyHandler,
+  ListCountriesSchema,
+  countriesHandler,
+  CountrySchema,
+  countryHandler,
+  ListLanguagesSchema,
+  languagesHandler,
+  LanguageSchema,
+  languageHandler,
+  UpdateProductSupplySchema,
+  updateProductSupplyHandler,
+  UpdateProductPlanSchema,
+  updateProductPlanHandler,
+  UpdateProductTokenizationSchema,
+  updateProductTokenizationHandler,
+  ProductsCountSchema,
+  productsCountHandler,
+  CreateProductVariationSchema,
+  createProductVariationHandler,
+  RemoveProductVariationSchema,
+  removeProductVariationHandler,
+  AssignProductVariationSchema,
+  addProductAssignmentHandler,
+  CreateProductVariationOptionSchema,
+  createProductVariationOptionHandler,
+  removeProductAssignmentHandler,
+  RemoveProductVariationOptionSchema,
+  removeProductVariationOptionHandler,
+  RemoveProductAssignmentSchema,
+  CreateLanguageSchema,
+  createLanguageHandler,
+  UpdateLanguageSchema,
+  updateLanguageHandler,
+  RemoveLanguageSchema,
+  removeLanguageHandler,
+  AddProductMediaUploadSchema,
+  addProductMediaUploadHandler,
+  RemoveProductMediaSchema,
+  removeProductMediaHandler,
+  UpdateProductMediaTextsSchema,
+  updateProductMediaTextsHandler,
+  ReorderProductMediaSchema,
+  reorderProductMediaHandler,
+  ProductReviewsCountSchema,
+  productReviewsCountHandler,
+  ProductReviewsSchema,
+  productReviewsHandler,
+} from './tools/index.js';
+
+export default function createMcpServer(context: Context, roles) {
+  const server = new McpServer({
+    name: 'Unchained MCP Server',
+    version: '1.0.0',
+  });
+
+  if (!roles?.includes('admin')) {
+    return server;
+  }
+
+  server.tool(
+    'list_products',
+    'Search and list products with comprehensive filtering and pagination support',
+    ListProductsSchema,
+    async (params) => listProductsHandler(context, params),
+  );
+
+  server.tool(
+    'products_count',
+    'Search and returns total number of products registered in the system with comprehensive filtering if provided',
+    ProductsCountSchema,
+    async (params) => productsCountHandler(context, params),
+  );
+  server.tool('get_product', 'Get detailed product information', GetProductSchema, async (params) =>
+    getProductHandler(context, params),
+  );
+
+  server.tool(
+    'create_product',
+    'Adds or create new product the product will be in DRAFT/unpublish status',
+    CreateProductSchema,
+    async (params) => createProductHandler(context, params),
+  );
+  server.tool(
+    'remove_product',
+    'Removed or deletes a product by its id changing its status to DELETED and removing it from sale',
+    RemoveProductSchema,
+    async (params) => removeProductHandler(context, params),
+  );
+
+  server.tool(
+    'publish_product',
+    'Publish a product by its id changing it to active and available for sale',
+    PublishProductSchema,
+    async (params) => publishProductHandler(context, params),
+  );
+
+  server.tool(
+    'unpublish_product',
+    'Deactivates or Unpublishes product by its id changing it to DRAFT and not available for sale',
+    UnpublishProductSchema,
+    async (params) => unpublishProductHandler(context, params),
+  );
+  server.tool(
+    'update_product',
+    'Modify/Update generic infos of a product (tags for ex.)',
+    UpdateProductSchema,
+    async (params) => updateProductHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_texts',
+    'Modify/update localized texts of a product',
+    UpdateProductTextsSchema,
+    async (params) => updateProductTextsHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_commerce',
+    'Modify/update products commerce info like prices, taxes, etc. for all product types except CONFIGURABLE_PRODUCT. for currency value always use registered currency in the system and not a custom one, it should not be called for CONFIGURABLE_PRODUCT type products',
+    UpdateProductCommerceSchema,
+    async (params) => updateProductCommerceHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_warehousing',
+    'Modify/update products commerce info like prices, taxes, etc. for SIMPLE_PRODUCT product type only.  it is only available for SIMPLE_PRODUCT type products',
+    UpdateProductCommerceSchema,
+    async (params) => updateProductCommerceHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_supply',
+    'Modify/update products supply of SIMPLE_PRODUCT type info like prices, taxes, etc. it is only available for SIMPLE_PRODUCT type products',
+    UpdateProductSupplySchema,
+    async (params) => updateProductSupplyHandler(context, params),
+  );
+  server.tool(
+    'update_tokenized_product',
+    'Modify/update products supply of TOKENIZED_PRODUCT type info like contractAddress, contractStandard, tokenId, supply, ercMetadataProperties etc. it is only available for TOKENIZED_PRODUCT type products',
+    UpdateProductTokenizationSchema,
+    async (params) => updateProductTokenizationHandler(context, params),
+  );
+  server.tool(
+    'update_product_plan',
+    'Modify/update products subscription/plan information of PLAN_PRODUCT type info like billing period, trial period and usage calculation, etc. it is only available for PLAN_PRODUCT type products',
+    UpdateProductPlanSchema,
+    async (params) => updateProductPlanHandler(context, params),
+  );
+
+  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',
+    ListCurrenciesSchema,
+    async (params) => currenciesHandler(context, params),
+  );
+
+  server.tool(
+    'get_currency',
+    'Gets a single currency registered in the system',
+    CurrencySchema,
+    async (params) => currencyHandler(context, params),
+  );
+
+  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',
+    ListCountriesSchema,
+    async (params) => countriesHandler(context, params),
+  );
+
+  server.tool(
+    'get_country',
+    'Gets a single country registered in the system',
+    CountrySchema,
+    async (params) => countryHandler(context, params),
+  );
+
+  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',
+    ListLanguagesSchema,
+    async (params) => languagesHandler(context, params),
+  );
+
+  server.tool(
+    'get_language',
+    'Gets a single language registered in the system',
+    LanguageSchema,
+    async (params) => languageHandler(context, params),
+  );
+
+  server.tool(
+    'create_product_variation',
+    'Adds/create a variation of a product, it is only available for CONFIGURABLE_PRODUCT type products',
+    CreateProductVariationSchema,
+    async (params) => createProductVariationHandler(context, params),
+  );
+
+  server.tool(
+    'remove_product_variation',
+    'removes a variation of a product',
+    RemoveProductVariationSchema,
+    async (params) => removeProductVariationHandler(context, params),
+  );
+
+  server.tool(
+    'assign_product_variation',
+    'Link a product to a ConfigurableProduct variation option by providing a vector combination that uniquely identifies the variation option',
+    AssignProductVariationSchema,
+    async (params) => addProductAssignmentHandler(context, params),
+  );
+
+  server.tool(
+    'add_variation_options',
+    'Adds variation option to an existing product variations',
+    CreateProductVariationOptionSchema,
+    async (params) => createProductVariationOptionHandler(context, params),
+  );
+
+  server.tool(
+    'remove_variation_options',
+    'Removes product option value for product variation with the provided variation option value',
+    RemoveProductVariationOptionSchema,
+    async (params) => removeProductVariationOptionHandler(context, params),
+  );
+
+  server.tool(
+    'remove_product_variation_assignment',
+    'Unlinks a product from a ConfigurableProduct by providing a configuration combination that uniquely identifies a row in the assignment matrix',
+    RemoveProductAssignmentSchema,
+    async (params) => removeProductAssignmentHandler(context, params),
+  );
+
+  server.tool('add_language', 'Adds new language', CreateLanguageSchema, async (params) =>
+    createLanguageHandler(context, params),
+  );
+
+  server.tool('update_language', 'Updates language', UpdateLanguageSchema, async (params) =>
+    updateLanguageHandler(context, params),
+  );
+
+  server.tool('remove_language', 'Deletes a language', RemoveLanguageSchema, async (params) =>
+    removeLanguageHandler(context, params),
+  );
+
+  server.tool(
+    'add_product_media',
+    'Adds media to a product',
+    AddProductMediaUploadSchema,
+    async (params) => addProductMediaUploadHandler(context, params),
+  );
+
+  server.tool(
+    'remove_product_media',
+    "Remove a media asset from a product's visualization",
+    RemoveProductMediaSchema,
+    async (params) => removeProductMediaHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_media_texts',
+    "Modify localized texts part of a product's media asset",
+    UpdateProductMediaTextsSchema,
+    async (params) => updateProductMediaTextsHandler(context, params),
+  );
+
+  server.tool(
+    'reorder_product_media',
+    'Reorder a media asset (first is primary)',
+    ReorderProductMediaSchema,
+    async (params) => reorderProductMediaHandler(context, params),
+  );
+
+  server.tool(
+    'product_review_count',
+    'Returns total number of product reviews',
+    ProductReviewsCountSchema,
+    async (params) => productReviewsCountHandler(context, params),
+  );
+
+  server.tool(
+    'product_reviews',
+    ' Get all product reviews, by default sorted by creation date (descending)',
+    ProductReviewsSchema,
+    async (params) => productReviewsHandler(context, params),
+  );
+
+  return server;
+}

package/src/mcp/tools/addProductAssignmentHandler.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { getNormalizedProductDetails } from '../utils/getNormalizedProductDetails.js';
+import {
+  ProductNotFoundError,
+  ProductVariationVectorAlreadySet,
+  ProductVariationVectorInvalid,
+  ProductWrongTypeError,
+} from '../../errors.js';
+import { ProductConfiguration, ProductTypes } from '@unchainedshop/core-products';
+
+const extractVariationMatrix = (variations = []) => {
+  const cartesianProduct = (arrays) => {
+    return arrays.reduce(
+      (acc, array) => acc.flatMap((item) => array.map((value) => [...item, value])),
+      [[]],
+    );
+  };
+  const keys = variations.map((item) => item.key);
+  const options = variations.map((item) => item.options);
+  const combinations = cartesianProduct(options);
+  return combinations.map((combination) =>
+    combination.reduce((acc, value, index) => {
+      acc[keys[index]] = value;
+      return acc;
+    }, {}),
+  );
+};
+
+const combinationExists = (matrix, combination) => {
+  return matrix.some((variation) => {
+    return (
+      Object.keys(variation).length === Object.keys(combination).length && // Ensure both have the same number of keys
+      Object.entries(combination).every(([key, value]) => variation[key] === value)
+    );
+  });
+};
+
+// Zod schema for ProductAssignmentVectorInput
+const ProductAssignmentVectorSchema = z.object({
+  key: z.string().min(1).describe('Attribute key (e.g., "Color", "Size")'),
+  value: z.string().min(1).describe('Attribute value (e.g., "Red", "M")'),
+});
+
+export const AssignProductVariationSchema = {
+  proxyId: z.string().min(1).describe('should be ID of the CONFIGURABLE_PRODUCT (parent) only'),
+  productId: z
+    .string()
+    .min(1)
+    .describe('ID of the product being assigned. can not be a CONFIGURABLE_PRODUCT product'),
+  vectors: z
+    .array(ProductAssignmentVectorSchema)
+    .min(1)
+    .describe('Combination of attributes uniquely identifying the variant'),
+};
+// Full schema for the mutation
+export const AddProductAssignmentZodSchema = z.object(AssignProductVariationSchema);
+
+export type AddProductAssignmentParams = z.infer<typeof AddProductAssignmentZodSchema>;
+
+export async function addProductAssignmentHandler(context: Context, params: AddProductAssignmentParams) {
+  const { proxyId, productId, vectors } = params;
+  const { modules } = context;
+
+  try {
+    const proxyProduct = await modules.products.findProduct({
+      productId: proxyId,
+    });
+    if (!proxyProduct) throw new ProductNotFoundError({ proxyId });
+
+    if (proxyProduct.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        proxyId,
+        received: proxyProduct.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+    const variations = await modules.products.variations.findProductVariations({
+      productId: proxyId,
+    });
+    const variationMatrix = extractVariationMatrix(variations);
+    const normalizedVectors = vectors?.reduce((prev, { key, value }) => {
+      return {
+        ...prev,
+        [key]: value,
+      };
+    }, {});
+    if (!combinationExists(variationMatrix, normalizedVectors))
+      throw new ProductVariationVectorInvalid({ proxyId, vectors });
+
+    const added = await modules.products.assignments.addProxyAssignment({
+      productId,
+      proxyId,
+      vectors: vectors as ProductConfiguration[],
+    });
+
+    if (!added) throw new ProductVariationVectorAlreadySet({ proxyId, vectors });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(proxyId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error assigning product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/addProductMediaUploadHandler.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 AddProductMediaUploadSchema = {
+  mediaName: z
+    .string()
+    .min(1)
+    .describe('Name of the media file (e.g. "image.png") use random name if not provided'),
+  productId: z.string().min(1).describe('ID of the product to link media to'),
+  url: z.string().describe('Anonymously fetchable URL of the source media, can be a data URL too'),
+};
+
+export const AddProductMediaUploadZodSchema = z.object(AddProductMediaUploadSchema);
+
+export type AddProductMediaUploadParams = z.infer<typeof AddProductMediaUploadZodSchema>;
+
+export async function addProductMediaUploadHandler(
+  context: Context,
+  params: AddProductMediaUploadParams,
+) {
+  const { mediaName, productId, url } = params;
+  const { modules, services, userId } = context;
+
+  try {
+    log('addProductMediaUploadHandler', { mediaName, productId, userId, url });
+    const {
+      _id: fileId,
+      putURL,
+      type,
+      size,
+    } = await services.files.createSignedURL({
+      directoryName: 'product-media',
+      fileName: mediaName,
+      meta: { productId },
+    });
+
+    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 product media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}