@unchainedshop/api 4.0.0-rc.5 → 4.0.0-rc.7

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

@@ -0,0 +1,50 @@
+import { Context } from '../../../context.js';
+import { ProductNotFoundError, ProductWrongTypeError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { ProductTypes } from '@unchainedshop/core-products';
+import { log } from '@unchainedshop/logger';
+import { z } from 'zod';
+
+export const ProductBundleItemsSchema = {
+  productId: z.string().min(1).describe('ID of the product of type BUNDLE to retrieve its bundle items'),
+};
+
+export const ProductBundleItemsZodSchema = z.object(ProductBundleItemsSchema);
+export type ProductBundleItemsParams = z.infer<typeof ProductBundleItemsZodSchema>;
+
+export const productBundleItemsHandler = async (context: Context, params: ProductBundleItemsParams) => {
+  const { modules, userId } = context;
+  const { productId } = params;
+
+  log('handler productBundleItemsHandler', { 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,
+      });
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product: await getNormalizedProductDetails(productId, context) }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching bundle items: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+};

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/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/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/removeProductMediaHandler.ts

@@ -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/reorderProductMediaHandler.ts

@@ -25,13 +25,13 @@ export async function reorderProductMediaHandler(context: Context, params: Reord
   try {
     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}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { log } from '@unchainedshop/logger';
+import { ProductMediaNotFoundError } from '../../../errors.js';
 
 export const TranslatedProductMediaTextsSchema = {
   productMediaId: z.string().min(1).describe('ID of the product media to fetch translated texts for'),
@@ -19,14 +20,17 @@ export async function translatedProductMediaTextsHandler(
 
   try {
     log(`handler translatedProductMediaTexts`, { userId, params });
-
+    const productMedia = await modules.products.media.findProductMedia({
+      productMediaId,
+    });
+    if (!productMedia) throw new ProductMediaNotFoundError({ productMediaId });
     const texts = await modules.products.media.texts.findMediaTexts({ productMediaId });
 
     return {
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ texts }),
+          text: JSON.stringify({ texts, productId: productMedia.productId }),
         },
       ],
     };

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { log } from '@unchainedshop/logger';
+import { ProductVariationNotFoundError } from '../../../errors.js';
 
 export const TranslatedProductVariationTextsSchema = {
   productVariationId: z.string().min(1).describe('ID of the product variation'),
@@ -28,6 +29,10 @@ export async function translatedProductVariationTextsHandler(
       userId,
       params,
     });
+    const productVariation = await modules.products.variations.findProductVariation({
+      productVariationId,
+    });
+    if (!productVariation) throw new ProductVariationNotFoundError({ productVariationId });
 
     const texts = await modules.products.variations.texts.findVariationTexts({
       productVariationId,
@@ -38,7 +43,7 @@ export async function translatedProductVariationTextsHandler(
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ texts }),
+          text: JSON.stringify({ texts, productId: productVariation.productId }),
         },
       ],
     };

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

@@ -46,7 +46,7 @@ export async function updateProductMediaTextsHandler(
       content: [
         {
           type: 'text' as const,
-          text: JSON.stringify({ texts: updatedTexts }),
+          text: JSON.stringify({ texts: updatedTexts, productId: productMedia.productId }),
         },
       ],
     };

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

@@ -5,15 +5,45 @@ import { ProductTypes } from '@unchainedshop/core-products';
 import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
 import { log } from '@unchainedshop/logger';
 
+export const ProductPlanUsageCalculationTypeEnum = z.enum(['LICENSED', 'METERED'], {
+  description:
+    'Determines how usage is calculated for the product plan. LICENSED means a fixed license count, METERED means usage is tracked dynamically.',
+});
+
+export const ProductPlanConfigurationIntervalEnum = z.enum(
+  ['HOURS', 'DAYS', 'WEEKS', 'MONTHS', 'YEARS'],
+  {
+    description:
+      'Defines the time unit for billing intervals and trial periods (e.g., MONTHS means billing every month).',
+  },
+);
+
+export const UpdateProductPlanInputSchema = z.object({
+  usageCalculationType: ProductPlanUsageCalculationTypeEnum.describe(
+    'The billing usage calculation method for the product plan.',
+  ),
+  billingInterval: ProductPlanConfigurationIntervalEnum.describe(
+    'The interval unit used for billing cycles.',
+  ),
+  billingIntervalCount: z
+    .number()
+    .int()
+    .positive()
+    .describe('The number of billing intervals per billing cycle (e.g., 3 for every 3 months).'),
+  trialInterval: ProductPlanConfigurationIntervalEnum.optional().describe(
+    'Optional trial period interval unit before billing starts.',
+  ),
+  trialIntervalCount: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Number of trial intervals before the billing cycle starts.'),
+});
+
 export const UpdateProductPlanSchema = {
   productId: z.string().min(1).describe('ID of the product of type PLAN_PRODUCT to update only'),
-  plan: z.object({
-    usageCalculationType: z.string().describe('Type of usage calculation'),
-    billingInterval: z.string().describe('Billing interval, e.g., "month", "year"'),
-    billingIntervalCount: z.number().int().positive().optional().describe('Count of billing intervals'),
-    trialInterval: z.string().optional().describe('Trial period interval'),
-    trialIntervalCount: z.number().int().positive().optional().describe('Count of trial intervals'),
-  }),
+  plan: UpdateProductPlanInputSchema.describe('Configuration settings for the product plan.'),
 };
 
 export const UpdateProductPlanZodSchema = z.object(UpdateProductPlanSchema);