@unchainedshop/api 3.1.15 → 4.0.0-rc.11

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

@@ -0,0 +1,47 @@
+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'),
+};
+
+export const TranslatedProductMediaTextsZodSchema = z.object(TranslatedProductMediaTextsSchema);
+
+export type TranslatedProductMediaTextsParams = z.infer<typeof TranslatedProductMediaTextsZodSchema>;
+
+export async function translatedProductMediaTextsHandler(
+  context: Context,
+  params: TranslatedProductMediaTextsParams,
+) {
+  const { productMediaId } = params;
+  const { modules, userId } = context;
+
+  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, productId: productMedia.productId }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting translated product media texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const TranslatedProductTextsSchema = {
+  productId: z.string().min(1).describe('ID of the product to fetch translated texts for'),
+};
+
+export const TranslatedProductTextsZodSchema = z.object(TranslatedProductTextsSchema);
+
+export type TranslatedProductTextsParams = z.infer<typeof TranslatedProductTextsZodSchema>;
+
+export async function translatedProductTextsHandler(
+  context: Context,
+  params: TranslatedProductTextsParams,
+) {
+  const { productId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler translatedProductTexts`, { userId, params });
+
+    const texts = await modules.products.texts.findTexts({ productId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting translated product texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,60 @@
+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'),
+  productVariationOptionValue: z
+    .string()
+    .optional()
+    .describe('Optional specific variation option value'),
+};
+
+export const TranslatedProductVariationTextsZodSchema = z.object(TranslatedProductVariationTextsSchema);
+
+export type TranslatedProductVariationTextsParams = z.infer<
+  typeof TranslatedProductVariationTextsZodSchema
+>;
+
+export async function translatedProductVariationTextsHandler(
+  context: Context,
+  params: TranslatedProductVariationTextsParams,
+) {
+  const { productVariationId, productVariationOptionValue } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler translatedProductVariationTexts`, {
+      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,
+      productVariationOptionValue,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts, productId: productVariation.productId }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting translated product variation texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,47 @@
+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 UnpublishProductSchema = {
+  productId: z.string().min(1).describe('ID of the product to unpublish'),
+};
+
+export const UnpublishProductZodSchema = z.object(UnpublishProductSchema);
+
+export type UnpublishProductParams = z.infer<typeof UnpublishProductZodSchema>;
+
+export async function unpublishProductHandler(context: Context, params: UnpublishProductParams) {
+  const { productId } = params;
+  const { modules, userId } = context;
+  log('handler unpublishProductHandler', { userId, params });
+  try {
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (!(await modules.products.unpublish(product))) {
+      throw new ProductWrongStatusError({ status: product.status });
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error unPublishing product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductCommerceSchema = {
+  productId: z
+    .string()
+    .min(1)
+    .describe('ID of the product of all type except for CONFIGURABLE_PRODUCT to update commerce info'),
+  commerce: z
+    .object({
+      pricing: z
+        .array(
+          z.object({
+            amount: z.number().int().describe('Price amount in smallest currency unit (e.g., cents)'),
+            maxQuantity: z
+              .number()
+              .int()
+              .optional()
+              .describe('Optional maximum quantity for this price tier'),
+            isTaxable: z.boolean().optional().describe('Whether tax applies to this price'),
+            isNetPrice: z.boolean().optional().describe('Whether this is a net price (without tax)'),
+            currencyCode: z
+              .string()
+              .min(3)
+              .max(3)
+              .describe(
+                'ISO currency code (e.g., USD, EUR) always use values registered in the system and if explicitly provided check if it exists',
+              ),
+            countryCode: z
+              .string()
+              .min(2)
+              .max(2)
+              .describe(
+                'ISO country code (e.g., US, DE) always use values registered in the system and if explicitly provided check if it exists',
+              ),
+          }),
+        )
+        .nonempty()
+        .describe('List of price configurations'),
+    })
+    .describe('Commerce info to update'),
+};
+
+export const UpdateProductCommerceZodSchema = z.object(UpdateProductCommerceSchema);
+
+export type UpdateProductCommerceParams = z.infer<typeof UpdateProductCommerceZodSchema>;
+
+export async function updateProductCommerceHandler(
+  context: Context,
+  params: UpdateProductCommerceParams,
+) {
+  const { productId, commerce } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductCommerceHandler', { userId, params });
+    await modules.products.update(productId, { commerce });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating product commerce info: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductNotFoundError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductSchema = {
+  productId: z.string().min(1).describe('ID of the product to update'),
+  product: z
+    .object({
+      tags: z.array(z.string().min(1).toLowerCase()).optional().describe('List of lowercase tags'),
+      sequence: z.number().int().optional().describe('Sorting sequence'),
+      meta: z.record(z.unknown()).optional().describe('Custom metadata as key-value pairs'),
+    })
+    .describe('Fields to update on the product'),
+};
+
+export const UpdateProductZodSchema = z.object(UpdateProductSchema);
+
+export type UpdateProductParams = z.infer<typeof UpdateProductZodSchema>;
+
+export async function updateProductHandler(context: Context, params: UpdateProductParams) {
+  const { productId, product } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductHandler', { userId, params });
+    if (!(await modules.products.productExists({ productId })))
+      throw new ProductNotFoundError({ productId });
+
+    await modules.products.update(productId, product);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductMediaNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductMediaTextsSchema = {
+  productMediaId: z.string().min(1).describe('ID of the media asset to update'),
+  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().optional().describe('Title in the given locale'),
+        subtitle: z.string().optional().describe('Subtitle in the given locale'),
+      }),
+    )
+    .min(1)
+    .describe('List of localized texts to update'),
+};
+
+export const UpdateProductMediaTextsZodSchema = z.object(UpdateProductMediaTextsSchema);
+
+export type UpdateProductMediaTextsParams = z.infer<typeof UpdateProductMediaTextsZodSchema>;
+
+export async function updateProductMediaTextsHandler(
+  context: Context,
+  params: UpdateProductMediaTextsParams,
+) {
+  const { productMediaId, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductMediaTextsHandler', { userId, params });
+    const productMedia = await modules.products.media.findProductMedia({
+      productMediaId,
+    });
+    if (!productMedia) throw new ProductMediaNotFoundError({ productMediaId });
+
+    const updatedTexts = await modules.products.media.texts.updateMediaTexts(productMediaId, texts);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts: updatedTexts, productId: productMedia.productId }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating product media texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductNotFoundError, ProductWrongStatusError } from '../../../errors.js';
+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: UpdateProductPlanInputSchema.describe('Configuration settings for the product plan.'),
+};
+
+export const UpdateProductPlanZodSchema = z.object(UpdateProductPlanSchema);
+
+export type UpdateProductPlanParams = z.infer<typeof UpdateProductPlanZodSchema>;
+
+export async function updateProductPlanHandler(context: Context, params: UpdateProductPlanParams) {
+  const { productId, plan } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductPlanHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product?.type !== ProductTypes.PlanProduct)
+      throw new ProductWrongStatusError({
+        received: product?.type,
+        required: ProductTypes.PlanProduct,
+      });
+
+    await modules.products.update(productId, { plan });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating product plan: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}