@unchainedshop/api 3.1.15 → 4.0.0-rc.10

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}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductWrongTypeError } from '../../../errors.js';
+import { ProductTypes } from '@unchainedshop/core-products';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductSupplySchema = {
+  productId: z
+    .string()
+    .min(1)
+    .describe('Product ID of a SIMPLE_PRODUCT only to update supply details for'),
+  supply: z
+    .object({
+      weightInGram: z.number().int().positive().optional().describe('Weight of the product in grams'),
+      heightInMillimeters: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Height of the product in millimeters'),
+      lengthInMillimeters: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Length of the product in millimeters'),
+      widthInMillimeters: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Width of the product in millimeters'),
+    })
+    .describe('Supply (delivery) attributes of the product'),
+};
+
+export const UpdateProductSupplyZodSchema = z.object(UpdateProductSupplySchema);
+
+export type UpdateProductSupplyParams = z.infer<typeof UpdateProductSupplyZodSchema>;
+
+export async function updateProductSupplyHandler(context: Context, params: UpdateProductSupplyParams) {
+  const { productId, supply } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductSupplyHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (product?.type !== ProductTypes.SimpleProduct)
+      throw new ProductWrongTypeError({
+        productId,
+        received: product?.type,
+        required: ProductTypes.SimpleProduct,
+      });
+
+    await modules.products.update(productId, { supply });
+
+    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 supply: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductTextsSchema = {
+  productId: z.string().min(1).describe('ID of the product to update texts for'),
+  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 UpdateProductTextsZodSchema = z.object(UpdateProductTextsSchema);
+
+export type UpdateProductTextsParams = z.infer<typeof UpdateProductTextsZodSchema>;
+
+export async function updateProductTextsHandler(context: Context, params: UpdateProductTextsParams) {
+  const { productId, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductTextsHandler', { userId, params });
+    await modules.products.texts.updateTexts(productId, 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 updating product texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductTypes } from '@unchainedshop/core-products';
+import { ProductNotFoundError, ProductWrongStatusError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductTokenizationSchema = {
+  productId: z.string().min(1).describe('ID of the product of type TOKENIZED_PRODUCT to tokenize only'),
+  tokenization: z
+    .object({
+      contractAddress: z.string().min(1).describe('Blockchain contract address'),
+      contractStandard: z.string().describe('Standard of the smart contract (e.g., ERC-721)'),
+      tokenId: z.string().min(1).describe('Unique token identifier'),
+      supply: z.number().int().positive().describe('Total supply of the token'),
+      ercMetadataProperties: z.record(z.any()).optional().describe('Optional ERC metadata properties'),
+    })
+    .describe('Tokenization details'),
+};
+
+export const UpdateProductTokenizationZodSchema = z.object(UpdateProductTokenizationSchema);
+export type UpdateProductTokenizationParams = z.infer<typeof UpdateProductTokenizationZodSchema>;
+
+export async function updateProductTokenizationHandler(
+  context: Context,
+  params: UpdateProductTokenizationParams,
+) {
+  const { productId, tokenization } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductTokenizationHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product?.type !== ProductTypes.TokenizedProduct)
+      throw new ProductWrongStatusError({
+        received: product?.type,
+        required: ProductTypes.TokenizedProduct,
+      });
+
+    await modules.products.update(productId, { tokenization });
+
+    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 tokenization: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { ProductVariationNotFoundError } from '../../../errors.js';
+
+export const ProductVariationTextInputSchema = z.object({
+  locale: z.string().min(1).describe('Locale code (e.g., "en", "de")'),
+  title: z.string().optional().describe('Title of the variation in the given locale'),
+  subtitle: z.string().optional().describe('Subtitle of the variation in the given locale'),
+});
+
+export const UpdateProductVariationTextsSchema = {
+  productVariationId: z.string().min(1).describe('ID of the product variation to update'),
+  productVariationOptionValue: z
+    .string()
+    .optional()
+    .describe('Optional production option value to filter variations'),
+  texts: z
+    .array(ProductVariationTextInputSchema)
+    .min(1)
+    .describe('Localized texts to apply to the variation'),
+};
+
+export const UpdateProductVariationTextsZodSchema = z.object(UpdateProductVariationTextsSchema);
+
+export type UpdateProductVariationTextsParams = z.infer<typeof UpdateProductVariationTextsZodSchema>;
+
+export async function updateProductVariationTextsHandler(
+  context: Context,
+  params: UpdateProductVariationTextsParams,
+) {
+  const { productVariationId, productVariationOptionValue, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductVariationTextsHandler', { userId, params });
+    const productVariation = await modules.products.variations.findProductVariation({
+      productVariationId,
+    });
+    if (!productVariation) throw new ProductVariationNotFoundError({ productVariationId });
+
+    const updatedTexts = await modules.products.variations.texts.updateVariationTexts(
+      productVariationId,
+      texts as any,
+      productVariationOptionValue,
+    );
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts: updatedTexts, productId: productVariation.productId }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating product warehousing: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductWrongTypeError } from '../../../errors.js';
+import { ProductTypes } from '@unchainedshop/core-products';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const UpdateProductWarehousingSchema = {
+  productId: z.string().min(1).describe('ID of the SIMPLE_PRODUCT product type to update'),
+  warehousing: z
+    .object({
+      sku: z.string().min(1).optional().describe('Stock keeping unit'),
+      baseUnit: z.string().min(1).optional().describe('Base unit of the product (e.g., "piece", "kg")'),
+    })
+    .describe('Warehousing details to update'),
+};
+
+export const UpdateProductWarehousingZodSchema = z.object(UpdateProductWarehousingSchema);
+
+export type UpdateProductWarehousingParams = z.infer<typeof UpdateProductWarehousingZodSchema>;
+
+export async function updateProductWarehousingHandler(
+  context: Context,
+  params: UpdateProductWarehousingParams,
+) {
+  const { productId, warehousing } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateProductWarehousingHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (product?.type !== ProductTypes.SimpleProduct)
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: ProductTypes.SimpleProduct,
+      });
+
+    await modules.products.update(productId, { warehousing });
+    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 warehousing: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,61 @@
+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';
+
+const VariationProductsVectorSchema = z.object({
+  key: z.string().min(1),
+  value: z.string().min(1),
+});
+
+export const VariationProductsSchema = {
+  productId: z.string().min(1),
+  vectors: z.array(VariationProductsVectorSchema).min(1),
+  includeInactive: z.boolean().optional().default(true).describe('Whether to include inactive products'),
+};
+export const VariationProductsZodSchema = z.object(VariationProductsSchema);
+export type VariationProductsParams = z.infer<typeof VariationProductsZodSchema>;
+
+export const variationProductsHandler = async (context: Context, params: VariationProductsParams) => {
+  const { modules, userId } = context;
+  const { productId, vectors, includeInactive } = params;
+
+  try {
+    log('handler variationProductsHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    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 normalizedProducts = await Promise.all(
+      products.map(async ({ _id }) => getNormalizedProductDetails(_id, context)),
+    );
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ products: normalizedProducts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching variation products: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+};