@unchainedshop/api 3.1.15 → 4.0.0-rc.11

package/src/mcp/tools/payment/updatePaymentProviderHandler.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { PaymentProviderNotFoundError } from '../../../errors.js';
+
+const ConfigurationEntry = z.object({
+  key: z.string().min(1).describe('Configuration key'),
+  value: z.any().describe('Configuration value'),
+});
+
+export const UpdatePaymentProviderSchema = {
+  paymentProviderId: z.string().min(1).describe('ID of the payment provider to update'),
+  paymentProvider: z
+    .object({
+      configuration: z
+        .array(ConfigurationEntry)
+        .optional()
+        .describe('List of key-value configuration entries'),
+    })
+    .refine(
+      (data) => {
+        const keys = data.configuration?.map((entry) => entry.key) || [];
+        return new Set(keys).size === keys.length;
+      },
+      {
+        message: 'Duplicate keys are not allowed in configuration.',
+        path: ['configuration'],
+      },
+    ),
+};
+
+export const UpdatePaymentProviderZodSchema = z.object(UpdatePaymentProviderSchema);
+export type UpdatePaymentProviderParams = z.infer<typeof UpdatePaymentProviderZodSchema>;
+
+export async function updatePaymentProviderHandler(
+  context: Context,
+  params: UpdatePaymentProviderParams,
+) {
+  const { modules, userId } = context;
+  const { paymentProviderId, paymentProvider } = params;
+
+  try {
+    log('handler updatePaymentProviderHandler', { userId, paymentProviderId, paymentProvider });
+
+    if (
+      !(await modules.payment.paymentProviders.providerExists({
+        paymentProviderId,
+      }))
+    )
+      throw new PaymentProviderNotFoundError({ paymentProviderId });
+
+    const updated = await modules.payment.paymentProviders.update(
+      paymentProviderId,
+      paymentProvider as any,
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ provider: updated }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating payment provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/addProductAssignmentHandler.ts

@@ -0,0 +1,121 @@
+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';
+import { log } from '@unchainedshop/logger';
+
+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)
+    );
+  });
+};
+
+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('ID of the CONFIGURABLE_PRODUCT (parent) only'),
+  productId: z
+    .string()
+    .min(1)
+    .describe('ID of the product being assigned. Cannot be a CONFIGURABLE_PRODUCT product'),
+  vectors: z
+    .array(ProductAssignmentVectorSchema)
+    .min(1)
+    .describe(
+      'Provide one option for **each** variation of the parent product (e.g., Color and Size). if it is not complete request the user to add all options or offer to create it. Do not call this tool unless all variation options have been selected. Otherwise, this will fail.',
+    ),
+};
+
+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, userId } = context;
+
+  try {
+    log('handler addProductAssignmentHandler', { userId, params });
+    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/product/addProductBundleItemHandler.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductNotFoundError, ProductWrongTypeError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { ProductTypes } from '@unchainedshop/core-products';
+
+const AddProductBundleItemInputSchema = z.object({
+  productId: z.string().min(1),
+  quantity: z.number().int().min(1),
+});
+
+export const AddProductBundleItemSchema = {
+  productId: z.string().min(1).describe('ID of the BUNDLE_PRODUCT to which the item will be added'),
+  item: AddProductBundleItemInputSchema,
+};
+
+export const AddProductBundleItemZodSchema = z.object(AddProductBundleItemSchema);
+
+export type AddProductBundleItemParams = z.infer<typeof AddProductBundleItemZodSchema>;
+export const addProductBundleItemHandler = async (
+  context: Context,
+  params: AddProductBundleItemParams,
+) => {
+  const { modules, userId } = context;
+  const { productId, item } = params;
+
+  log('handler addProductBundleItemHandler', { userId, params });
+
+  try {
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product.type !== ProductTypes.BundleProduct)
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: ProductTypes.BundleProduct,
+      });
+
+    if (!(await modules.products.productExists({ productId: item.productId })))
+      throw new ProductNotFoundError({ productId: item.productId });
+
+    await modules.products.bundleItems.addBundleItem(productId, item as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product: await getNormalizedProductDetails(productId, context) }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error adding bundle item: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+};

package/src/mcp/tools/product/addProductMediaUploadHandler.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FileNotFoundError, FileUploadExpiredError } from '../../../errors.js';
+import normalizeMediaUrl from '../../utils/normalizeMediaUrl.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'),
+};
+
+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('handler addProductMediaUploadHandler', { userId, params });
+    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: await normalizeMediaUrl([{ ...linked, mediaId: linked._id }], context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error uploading product media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/catalogPriceHandler.ts

@@ -0,0 +1,61 @@
+import { Context } from '../../../context.js';
+import { ProductNotFoundError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+import { z } from 'zod';
+
+export const CatalogPriceSchema = {
+  productId: z.string().min(1).describe('ID of the product to retrieve catalog price for'),
+  quantity: z
+    .number()
+    .int()
+    .positive()
+    .default(1)
+    .describe('Quantity to calculate catalog price for (default is 1)'),
+  currencyCode: z
+    .string()
+    .optional()
+    .describe('Optional currency code (e.g., "USD") for price calculation'),
+};
+
+export const CatalogPriceZodSchema = z.object(CatalogPriceSchema);
+export type CatalogPriceParams = z.infer<typeof CatalogPriceZodSchema>;
+
+export async function catalogPriceHandler(context: Context, params: CatalogPriceParams) {
+  const { productId, quantity, currencyCode: forcedCurrencyCode } = params;
+  const { modules, countryCode, currencyCode: defaultCurrencyCode, userId } = context;
+
+  try {
+    log('handler catalogPriceHandler', { userId, params });
+    const product = await getNormalizedProductDetails(productId, context);
+    if (!product) throw new ProductNotFoundError({ productId });
+    const currencyCode = forcedCurrencyCode || defaultCurrencyCode;
+    const catalogPrice = await modules.products.prices.price(product, {
+      countryCode,
+      currencyCode,
+      quantity,
+    });
+    const leveledCatalogPrice = await modules.products.prices.catalogPricesLeveled(product, {
+      currencyCode,
+      countryCode,
+    });
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product, price: catalogPrice, leveledCatalogPrice }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+
+          text: `Error retrieving catalog price: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/createProductHandler.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { Product, ProductText, ProductTypes } from '@unchainedshop/core-products';
+import { log } from '@unchainedshop/logger';
+const productTypeKeys = Object.keys(ProductTypes) as [
+  keyof typeof ProductTypes,
+  ...(keyof typeof ProductTypes)[],
+];
+
+export const CreateProductSchema = {
+  product: z.object({
+    type: z.enum(productTypeKeys).describe('Product type (e.g., "SIMPLE_PRODUCT")'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags (lowercased strings)'),
+  }),
+  texts: z
+    .array(
+      z.object({
+        locale: z
+          .string()
+          .min(2)
+          .describe(
+            'locale iso code like "en-US", "de-CH" use default defaultLanguageIsoCode in shop info if not explicitly provided. if language is explicitly provided check if it exists',
+          ),
+        slug: z.string().optional().describe('URL slug'),
+        title: z.string().optional().describe('Product title'),
+        subtitle: z.string().optional().describe('Product subtitle'),
+        description: z.string().optional().describe('Markdown description'),
+        vendor: z.string().optional().describe('Vendor name'),
+        brand: z.string().optional().describe('Brand name'),
+        labels: z.array(z.string()).optional().describe('Labels or tags'),
+      }),
+    )
+    .nonempty()
+    .describe('Localized product text entries'),
+};
+
+export const CreateProductZodSchema = z.object(CreateProductSchema);
+
+export type CreateProductParams = z.infer<typeof CreateProductZodSchema>;
+
+export async function createProductHandler(context: Context, params: CreateProductParams) {
+  const { product, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler createProductHandler', { userId, params });
+    const newProduct = await modules.products.create(product as Product);
+    let productTexts: any[] = texts;
+    if (texts) {
+      productTexts = await modules.products.texts.updateTexts(
+        newProduct._id,
+        texts as unknown as ProductText[],
+      );
+    }
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: {
+              ...newProduct,
+              texts: productTexts,
+            },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/createProductVariationHandler.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductTypes, ProductVariationType } from '@unchainedshop/core-products';
+import { ProductNotFoundError, ProductWrongTypeError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+const productVariationTypeKeys = Object.keys(ProductVariationType) as [
+  keyof typeof ProductVariationType,
+  ...(keyof typeof ProductVariationType)[],
+];
+
+export const CreateProductVariationSchema = {
+  productId: z
+    .string()
+    .min(1)
+    .describe(
+      'Product ID for which to create the variation. it should only be CONFIGURABLE_PRODUCT type product id',
+    ),
+  variation: z.object({
+    key: z
+      .string()
+      .min(1)
+      .describe('unique value that is not already used as key for the products variations vector'),
+    type: z.enum(productVariationTypeKeys).describe('Product variation types'),
+  }),
+  texts: z
+    .array(
+      z.object({
+        locale: z
+          .string()
+          .min(2)
+          .describe(
+            'locale iso code like "en-US", "de-CH" use default defaultLanguageIsoCode in shop info if not explicitly provided. if language is explicitly provided check if it exists',
+          ),
+        title: z.string().describe('variation title'),
+        subtitle: z.string().optional().describe('variation additional description'),
+      }),
+    )
+    .optional(),
+};
+
+export const CreateProductVariationZodSchema = z.object(CreateProductVariationSchema);
+export type CreateProductVariationParams = z.infer<typeof CreateProductVariationZodSchema>;
+
+export async function createProductVariationHandler(
+  context: Context,
+  params: CreateProductVariationParams,
+) {
+  const { productId, variation, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler createProductVariationHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+
+    const newVariation = await modules.products.variations.create({
+      options: [],
+      productId,
+      ...variation,
+    });
+
+    if (texts) {
+      await modules.products.variations.texts.updateVariationTexts(newVariation._id, texts as any);
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating product variation: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/createProductVariationOptionHandler.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { ProductVariationNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+
+const ProductVariationTextInputSchema = z.object({
+  locale: z
+    .string()
+    .min(2)
+    .describe(
+      'locale iso code like "en-US", "de-CH" use default defaultLanguageIsoCode in shop info if not explicitly provided. if language is explicitly provided check if it exists',
+    ),
+  title: z.string().describe('variation option title in the specified locale'),
+  subtitle: z.string().optional().describe('variation option subtitle in the specified locale'),
+});
+
+export const CreateProductVariationOptionSchema = {
+  productVariationId: z
+    .string()
+    .min(1)
+    .describe('ID of the product variation, it should only be a CONFIGURABLE_PRODUCT type ID'),
+  option: z.string().min(1).describe('Name of the new option (e.g., "Red")'),
+  texts: z.array(ProductVariationTextInputSchema),
+};
+export const CreateProductVariationOptionZodSchema = z.object(CreateProductVariationOptionSchema);
+export type CreateProductVariationOptionParams = z.infer<typeof CreateProductVariationOptionZodSchema>;
+
+export async function createProductVariationOptionHandler(
+  context: Context,
+  params: CreateProductVariationOptionParams,
+) {
+  const { productVariationId, option, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler createProductVariationOptionHandler', { userId, params });
+    const variation = await modules.products.variations.findProductVariation({
+      productVariationId,
+    });
+    if (!variation) throw new ProductVariationNotFoundError({ productVariationId });
+
+    const newOption = await modules.products.variations.addVariationOption(productVariationId, {
+      value: option,
+    });
+
+    if (texts) {
+      await modules.products.variations.texts.updateVariationTexts(
+        productVariationId,
+        texts as any,
+        option,
+      );
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            variation: newOption,
+            product: await getNormalizedProductDetails(newOption?.productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating variation option: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}