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

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

@@ -0,0 +1,53 @@
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { z } from 'zod';
+import normalizeMediaUrl from '../../utils/normalizeMediaUrl.js';
+
+export const ProductMediaSchema = {
+  productId: z.string().min(1).describe('ID of the product to retrieve media for'),
+  limit: z.number().int().min(1).max(100).default(10).describe('Number of media items to return'),
+  offset: z.number().int().min(0).default(0).describe('Pagination offset'),
+  tags: z.array(z.string().min(1)).optional().describe('Filter media by lowercase tags'),
+};
+
+export const ProductMediaZodSchema = z
+  .object(ProductMediaSchema)
+  .describe(
+    'Retrieve media assets associated with a product, optionally filtered by tags and paginated.',
+  );
+
+export type ProductMediaParams = z.infer<typeof ProductMediaZodSchema>;
+
+export async function productMediaHandler(context: Context, params: ProductMediaParams) {
+  const { productId, limit, offset, tags } = params;
+  const { modules, loaders, userId } = context;
+
+  try {
+    log('handler productMediaHandler', { userId, params });
+    let media = [];
+    if (offset || tags) {
+      media = await modules.products.media.findProductMedias({
+        productId,
+        ...params,
+      });
+    }
+    media = (await loaders.productMediasLoader.load({ productId })).slice(offset, offset + limit);
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ media: await normalizeMediaUrl(media, context) }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving product media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
 
 export const ProductReviewsCountSchema = {
   queryString: z.string().optional().describe('Optional query string to filter reviews'),
@@ -10,9 +11,10 @@ export const ProductReviewsCountZodSchema = z.object(ProductReviewsCountSchema);
 export type ProductReviewsCountParams = z.infer<typeof ProductReviewsCountZodSchema>;
 
 export async function productReviewsCountHandler(context: Context, params: ProductReviewsCountParams) {
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler productReviewsCountHandler', { userId, params });
     const count = await modules.products.reviews.count(params);
 
     return {

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

@@ -30,6 +30,7 @@ export async function productReviewsHandler(context: Context, params: ProductRev
   try {
     log(`query productReviews: ${limit} ${offset} ${queryString || ''}`, {
       userId,
+      params,
     });
 
     const reviews = await modules.products.reviews.findProductReviews(params as any);

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

@@ -0,0 +1,82 @@
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+import { z } from 'zod';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+export const ProductSiblingsSchema = {
+  productId: z.string().describe('Product ID to get siblings of'),
+  assortmentId: z.string().optional().describe('Assortment ID to filter siblings (optional)'),
+  limit: z.number().int().min(1).max(100).default(10).describe('Number of siblings to return'),
+  offset: z.number().int().min(0).default(0).describe('Pagination offset'),
+  includeInactive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Whether to include inactive sibling products'),
+};
+
+export const ProductSiblingsZodSchema = z
+  .object(ProductSiblingsSchema)
+  .describe(
+    'Retrieve sibling products of a given product, optionally filtered by assortment ID, with support for pagination and inclusion of inactive products.',
+  );
+
+export type ProductSiblingsParams = z.infer<typeof ProductSiblingsZodSchema>;
+
+export async function productSiblingsHandler(context: Context, params: ProductSiblingsParams) {
+  const { modules, userId } = context;
+  const { productId, assortmentId, limit, offset, includeInactive } = params;
+
+  try {
+    log('handler productSiblingsHandler', { userId, params });
+
+    const assortmentIds = assortmentId
+      ? [assortmentId]
+      : await modules.assortments.products.findAssortmentIds({ productId });
+
+    if (!assortmentIds.length)
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({ products: [] }),
+          },
+        ],
+      };
+
+    const productIds = await modules.assortments.products.findSiblings({
+      productId,
+      assortmentIds,
+    });
+
+    const products = await modules.products.findProducts({
+      productIds,
+      includeDrafts: includeInactive,
+      limit,
+      offset,
+    });
+
+    const normalizedProducts = (
+      await Promise.allSettled(products.map(({ _id }) => getNormalizedProductDetails(_id, context)))
+    ).flatMap((r) => (r.status === 'fulfilled' ? [r.value] : []));
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ products: normalizedProducts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving product siblings: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,53 @@
+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';
+
+export const ProductVariationsSchema = {
+  productId: z.string().min(1).describe('ID of the CONFIGURABLE_PRODUCT to retrieve variations from'),
+};
+
+export const ProductVariationsZodSchema = z.object(ProductVariationsSchema);
+export type ProductVariationsParams = z.infer<typeof ProductVariationsZodSchema>;
+
+export const productVariationsHandler = async (context: Context, params: ProductVariationsParams) => {
+  const { productId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler productVariationsHandler', { userId, productId });
+
+    const product = await getNormalizedProductDetails(productId, context);
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product.type !== 'CONFIGURABLE_PRODUCT') {
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: 'CONFIGURABLE_PRODUCT',
+      });
+    }
+    const variations = await modules.products.variations.findProductVariations({
+      productId,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product, variations }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching variations: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+};

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

@@ -1,20 +1,22 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
 
 export const ProductsCountSchema = {
-  tags: z.array(z.string().min(1)).optional(),
-  slugs: z.array(z.string().min(1)).optional(),
-  includeDrafts: z.boolean().default(false),
-  queryString: z.string().min(1).optional(),
+  tags: z.array(z.string().min(1)).optional().describe('Filter products by tags'),
+  slugs: z.array(z.string().min(1)).optional().describe('Filter products by slugs'),
+  includeDrafts: z.boolean().default(false).describe('Include draft (unpublished) products'),
+  queryString: z.string().min(1).optional().describe('Text query to filter products'),
 };
 
 export const ProductsCountZodSchema = z.object(ProductsCountSchema);
 export type ProductsCountParams = z.infer<typeof ProductsCountZodSchema>;
 
 export async function productsCountHandler(context: Context, params: ProductsCountParams) {
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler productsCountHandler', { userId, params });
     const count = await modules.products.count(params);
 
     return {

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

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { ProductNotFoundError, ProductWrongStatusError } from '../../../errors.js';
 import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
 
 export const PublishProductSchema = {
   productId: z.string().min(1).describe('ID of the product to publish'),
@@ -13,8 +14,10 @@ export type PublishProductParams = z.infer<typeof PublishProductZodSchema>;
 
 export async function publishProductHandler(context: Context, params: PublishProductParams) {
   const { productId } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
+
   try {
+    log('handler publishProductHandler', { userId, params });
     const product = await modules.products.findProduct({ productId });
     if (!product) throw new ProductNotFoundError({ productId });
 

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

@@ -3,6 +3,7 @@ import { Context } from '../../../context.js';
 import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
 import { ProductWrongTypeError } from '../../../errors.js';
 import { ProductTypes } from '@unchainedshop/core-products';
+import { log } from '@unchainedshop/logger';
 
 const ProductAssignmentVectorSchema = z.object({
   key: z.string().min(1).describe('Attribute key (e.g., "Color", "Size")'),
@@ -24,9 +25,10 @@ export async function removeProductAssignmentHandler(
   params: RemoveProductAssignmentParams,
 ) {
   const { proxyId, vectors } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler removeProductAssignmentHandler', { userId, params });
     const product = await modules.products.findProduct({ productId: proxyId });
 
     if (product.type !== ProductTypes.ConfigurableProduct)

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

@@ -0,0 +1,55 @@
+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';
+
+export const RemoveProductBundleItemSchema = {
+  productId: z.string().min(1).describe('ID of the BUNDLE_PRODUCT from which the item will be removed'),
+  index: z.number().int().min(0).describe('0-based index of the bundle item to remove'),
+};
+
+export const RemoveProductBundleItemZodSchema = z.object(RemoveProductBundleItemSchema);
+
+export type RemoveProductBundleItemParams = z.infer<typeof RemoveProductBundleItemZodSchema>;
+
+export const removeProductBundleItemHandler = async (
+  context: Context,
+  params: RemoveProductBundleItemParams,
+) => {
+  const { modules, userId } = context;
+  const { productId, index } = params;
+
+  log('handler removeProductBundleItemHandler', { 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,
+      });
+
+    await modules.products.bundleItems.removeBundleItem(productId, index);
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product: await getNormalizedProductDetails(productId, context) }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error removing bundle item: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+};

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
 
 export const RemoveProductSchema = {
   productId: z.string().min(1).describe('ID of the product to remove'),
@@ -12,9 +13,10 @@ export type RemoveProductParams = z.infer<typeof RemoveProductZodSchema>;
 
 export async function removeProductHandler(context: Context, params: RemoveProductParams) {
   const { productId } = params;
-  const { services } = context;
+  const { services, userId } = context;
 
   try {
+    log('handler removeProductHandler', { userId, params });
     await services.products.removeProduct({ productId });
 
     return {

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

@@ -16,7 +16,7 @@ export async function removeProductMediaHandler(context: Context, params: Remove
   const { modules, userId } = context;
 
   try {
-    log('removeProductMediaHandler', { userId, productMediaId });
+    log('handler removeProductMediaHandler', { userId, params });
 
     const productMedia = await modules.products.media.findProductMedia({
       productMediaId,
@@ -31,7 +31,7 @@ export async function removeProductMediaHandler(context: Context, params: Remove
         {
           type: 'text' as const,
           text: JSON.stringify({
-            media: productMedia,
+            success: true,
           }),
         },
       ],

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

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { ProductVariationNotFoundError } from '../../../errors.js';
 import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
 
 export const RemoveProductVariationSchema = {
   productVariationId: z
@@ -18,9 +19,10 @@ export async function removeProductVariationHandler(
   params: RemoveProductVariationParams,
 ) {
   const { productVariationId } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler removeProductVariationHandler', { userId, params });
     const productVariation = await modules.products.variations.findProductVariation({
       productVariationId,
     });

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

@@ -2,6 +2,7 @@ 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';
 
 export const RemoveProductVariationOptionSchema = {
   productVariationId: z
@@ -22,9 +23,10 @@ export async function removeProductVariationOptionHandler(
   params: RemoveProductVariationOptionParams,
 ) {
   const { productVariationId, productVariationOptionValue } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler removeProductVariationOptionHandler', { userId, params });
     const productVariation = await modules.products.variations.findProductVariation({
       productVariationId,
     });

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

@@ -23,15 +23,15 @@ export async function reorderProductMediaHandler(context: Context, params: Reord
   const { modules, userId } = context;
 
   try {
-    log('handler reorderProductMedia', { userId });
+    log('handler reorderProductMediaHandler', { userId, params });
 
-    const reorderedMedia = await modules.products.media.updateManualOrder({ sortKeys: sortKeys as any });
+    const media = await modules.products.media.updateManualOrder({ sortKeys: sortKeys as any });
 
     return {
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ reorderedMedia }, null, 2),
+          text: JSON.stringify({ media }, null, 2),
         },
       ],
     };

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

@@ -0,0 +1,82 @@
+import { Context } from '../../../context.js';
+import { ProductNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+import { z } from 'zod';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+export const ProductConfigurationParameterInputSchema = z.object({
+  key: z.string().min(1).describe('Configuration attribute key'),
+  value: z.string().min(1).describe('Configuration attribute value'),
+});
+
+export const SimulatedPriceSchema = {
+  productId: z.string().min(1).describe('ID of the product for which to simulate pricing'),
+  quantity: z
+    .number()
+    .int()
+    .positive()
+    .default(1)
+    .describe('Quantity to simulate price for (default is 1)'),
+  currencyCode: z.string().optional().describe('Currency code for price simulation (e.g., "USD")'),
+  useNetPrice: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('If true, returns net price; otherwise, returns gross price'),
+  configuration: z
+    .array(ProductConfigurationParameterInputSchema)
+    .optional()
+    .describe('Complete configuration vector (e.g., Color: Red, Size: M)'),
+};
+
+export const SimulatedPriceZodSchema = z.object(SimulatedPriceSchema);
+
+export type SimulatedPriceParams = z.infer<typeof SimulatedPriceZodSchema>;
+
+export async function simulatedPriceHandler(context: Context, params: SimulatedPriceParams) {
+  const { userId, countryCode, user, services } = context;
+  const { productId, quantity, configuration, currencyCode: forcedCurrencyCode, useNetPrice } = params;
+
+  try {
+    log('handler simulatedPriceHandler', { userId, params });
+
+    const product = await getNormalizedProductDetails(productId, context);
+    if (!product) throw new ProductNotFoundError({ productId });
+    const currencyCode = forcedCurrencyCode || context.currencyCode;
+    const pricingContext = {
+      product,
+      user,
+      countryCode,
+      currencyCode,
+      quantity,
+      configuration,
+    };
+    const pricing = await services.products.simulateProductPricing(pricingContext as any);
+    const unitPrice = pricing.unitPrice({ useNetPrice });
+
+    const price = {
+      ...unitPrice,
+      isNetPrice: useNetPrice,
+      isTaxable: pricing.taxSum() > 0,
+      currencyCode: pricing.currencyCode,
+    };
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product, price }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error simulating price: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,126 @@
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { z } from 'zod';
+import { ProductWrongTypeError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+export const ProductAssignmentVectorInputSchema = z.object({
+  key: z.string().min(1).describe('Variation attribute key (e.g., "Color")'),
+  value: z.string().min(1).describe('Variation attribute value (e.g., "Red")'),
+});
+
+export const SimulatedPriceRangeSchema = {
+  productId: z.string().min(1).describe('ID of the CONFIGURABLE_PRODUCT to simulate price range for'),
+  quantity: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Desired quantity for price simulation (default is 1)'),
+  vectors: z
+    .array(ProductAssignmentVectorInputSchema)
+    .optional()
+    .describe('Optional variation key-value pairs (e.g., Color: Red) to simulate specific variant'),
+  includeInactive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Whether to include inactive variants'),
+  currencyCode: z
+    .string()
+    .optional()
+    .describe('Currency code to simulate pricing with (e.g., "USD", "EUR")'),
+  useNetPrice: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Return net price if true, otherwise gross price'),
+};
+
+export const SimulatedPriceRangeZodSchema = z.object(SimulatedPriceRangeSchema);
+
+export type SimulatedPriceRangeParams = z.infer<typeof SimulatedPriceRangeZodSchema>;
+
+export async function simulatedPriceRangeHandler(context: Context, params: SimulatedPriceRangeParams) {
+  const {
+    productId,
+    quantity,
+    vectors,
+    includeInactive,
+    currencyCode: forcedCurrencyCode,
+    useNetPrice,
+  } = params;
+  const { modules, userId, countryCode, services } = context;
+
+  try {
+    log('handler simulatedPriceRangeHandler', { userId, params });
+
+    const currencyCode = forcedCurrencyCode || context.currencyCode;
+    const product = await getNormalizedProductDetails(productId, context);
+
+    if (product.type !== 'CONFIGURABLE_PRODUCT') {
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: 'CONFIGURABLE_PRODUCT',
+      });
+    }
+    const products = await modules.products.proxyProducts(product, vectors as any, {
+      includeInactive,
+    });
+
+    const filteredPrices = (
+      await Promise.all(
+        products.map(async (proxyProduct) => {
+          const pricingContext = {
+            product: proxyProduct,
+            user: context.user,
+            countryCode,
+            currencyCode,
+            quantity,
+          };
+
+          const pricing = await services.products.simulateProductPricing(pricingContext);
+          if (!pricing) return null;
+          const unitPrice = pricing.unitPrice({ useNetPrice });
+
+          return {
+            ...unitPrice,
+            isNetPrice: useNetPrice,
+            isTaxable: pricing.taxSum() > 0,
+            currencyCode: pricing.currencyCode,
+          };
+        }),
+      )
+    ).filter(Boolean);
+
+    if (!filteredPrices.length) return null;
+
+    const { minPrice, maxPrice } = modules.products.prices.priceRange({
+      productId: product._id as string,
+      prices: filteredPrices,
+    });
+
+    const priceRange = {
+      minPrice,
+      maxPrice,
+    };
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product, priceRange }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error simulating price range: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}