@unchainedshop/api 3.1.15 → 4.0.0-rc.10

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

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const PaymentProviderByIdSchema = {
+  paymentProviderId: z.string().min(1).describe('ID of the payment provider'),
+};
+
+export const PaymentProviderByIdZodSchema = z.object(PaymentProviderByIdSchema);
+export type PaymentProviderByIdParams = z.infer<typeof PaymentProviderByIdZodSchema>;
+
+export async function paymentProviderByIdHandler(context: Context, params: PaymentProviderByIdParams) {
+  const { modules, userId } = context;
+  const { paymentProviderId } = params;
+
+  try {
+    log('handler paymentProviderByIdHandler', { userId, paymentProviderId });
+
+    const provider = await modules.payment.paymentProviders.findProvider({
+      paymentProviderId,
+    });
+
+    if (!provider) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Payment provider not found for ID: ${paymentProviderId}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ paymentProvider: provider }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching payment provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
+
+export const PaymentProvidersCountSchema = {
+  type: PaymentProviderTypeEnum.optional().describe('Filter payment providers by type'),
+};
+
+export const PaymentProvidersCountZodSchema = z.object(PaymentProvidersCountSchema);
+export type PaymentProvidersCountParams = z.infer<typeof PaymentProvidersCountZodSchema>;
+
+export async function paymentProvidersCountHandler(
+  context: Context,
+  params: PaymentProvidersCountParams,
+) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler paymentProvidersCountHandler', { userId, params });
+
+    const count = await modules.payment.paymentProviders.count(params as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ count }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error counting payment providers: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+const PaymentProviderTypeEnum = z.enum(['CARD', 'INVOICE', 'GENERIC']);
+
+export const PaymentProvidersListSchema = {
+  type: PaymentProviderTypeEnum.optional().describe('Filter payment providers by type'),
+};
+
+export const PaymentProvidersListZodSchema = z.object(PaymentProvidersListSchema);
+export type PaymentProvidersListParams = z.infer<typeof PaymentProvidersListZodSchema>;
+
+export async function paymentProvidersListHandler(context: Context, params: PaymentProvidersListParams) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler paymentProvidersListHandler', { userId, params });
+
+    const providers = await modules.payment.paymentProviders.findProviders(params as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ paymentProviders: providers }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching payment providers: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { PaymentProviderNotFoundError } from '../../../errors.js';
+
+export const RemovePaymentProviderSchema = {
+  paymentProviderId: z.string().min(1).describe('ID of the payment provider to soft delete'),
+};
+
+export const RemovePaymentProviderZodSchema = z.object(RemovePaymentProviderSchema);
+export type RemovePaymentProviderParams = z.infer<typeof RemovePaymentProviderZodSchema>;
+
+export async function removePaymentProviderHandler(
+  context: Context,
+  params: RemovePaymentProviderParams,
+) {
+  const { modules, userId } = context;
+  const { paymentProviderId } = params;
+
+  try {
+    log('handler removePaymentProviderHandler', { userId, paymentProviderId });
+
+    if (
+      !(await modules.payment.paymentProviders.providerExists({
+        paymentProviderId,
+      }))
+    )
+      throw new PaymentProviderNotFoundError({ paymentProviderId });
+
+    const removed = await modules.payment.paymentProviders.delete(paymentProviderId);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ paymentProvider: removed }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error removing payment provider: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { PaymentProviderNotFoundError } from '../../../errors.js';
+
+export const UpdatePaymentProviderSchema = {
+  paymentProviderId: z.string().min(1).describe('ID of the payment provider to update'),
+  paymentProvider: z.object({
+    configuration: z.array(z.any()).optional().describe('Array of JSON configuration values'),
+  }),
+};
+
+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({ paymentProvider: 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}`,
+        },
+      ],
+    };
+  }
+}