@unchainedshop/api 3.1.13 → 4.0.0-rc.10

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

@@ -0,0 +1,86 @@
+import { Context } from '../../../context.js';
+import { ProductNotFoundError, ProductWrongTypeError } from '../../../errors.js';
+import { ProductTypes } from '@unchainedshop/core-products';
+import { log } from '@unchainedshop/logger';
+import { z } from 'zod';
+import normalizeMediaUrl from '../../utils/normalizeMediaUrl.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+export const ProductAssignmentsSchema = {
+  productId: z
+    .string()
+    .min(1)
+    .describe('ID of the CONFIGURABLE_PRODUCT whose assignments should be fetched'),
+  includeInactive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Whether to include inactive assigned products'),
+};
+
+export const ProductAssignmentsZodSchema = z.object(ProductAssignmentsSchema);
+export type ProductAssignmentsParams = z.infer<typeof ProductAssignmentsZodSchema>;
+
+export const productAssignmentsHandler = async (context: Context, params: ProductAssignmentsParams) => {
+  const { modules, userId, loaders, locale } = context;
+  const { productId, includeInactive } = params;
+
+  log('handler productAssignmentsHandler', { userId, params });
+  try {
+    const product = await getNormalizedProductDetails(productId, context);
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product.type !== ProductTypes.ConfigurableProduct) {
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+    }
+
+    const assignments = await modules.products.proxyAssignments(product, { includeInactive });
+    const normalizedAssignments = await Promise.all(
+      assignments.map(async ({ assignment, ...rest }) => {
+        const product = await loaders.productLoader.load({
+          productId: assignment.productId,
+        });
+        const productMedias = await modules.products.media.findProductMedias({
+          productId: assignment.productId,
+        });
+        const media = await normalizeMediaUrl(productMedias, context);
+        const texts = await loaders.productTextLoader.load({
+          productId: assignment.productId,
+          locale,
+        });
+        return {
+          assignment: {
+            ...assignment,
+            product: {
+              ...product,
+              media,
+              texts,
+            },
+          },
+          ...rest,
+        };
+      }),
+    );
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ product, assignments: normalizedAssignments }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching assignments: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+};

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

@@ -0,0 +1,38 @@
+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'),
+};
+
+export const ProductReviewsCountZodSchema = z.object(ProductReviewsCountSchema);
+
+export type ProductReviewsCountParams = z.infer<typeof ProductReviewsCountZodSchema>;
+
+export async function productReviewsCountHandler(context: Context, params: ProductReviewsCountParams) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler productReviewsCountHandler', { userId, params });
+    const count = await modules.products.reviews.count(params);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: count.toString(),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching review count: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+const SortDirectionEnum = z.enum(['ASC', 'DESC']);
+
+export const ProductReviewsSchema = {
+  limit: z.number().int().min(1).max(100).default(10).describe('Number of reviews to return'),
+  offset: z.number().int().min(0).default(0).describe('Number of reviews to skip'),
+  sort: z
+    .array(
+      z.object({
+        key: z.string().min(1).describe('Field to sort by'),
+        value: SortDirectionEnum.describe('Sort direction: asc or desc'),
+      }),
+    )
+    .optional()
+    .describe('Sort options'),
+  queryString: z.string().optional().describe('Optional filter query'),
+};
+
+export const ProductReviewsZodSchema = z.object(ProductReviewsSchema);
+
+export type ProductReviewsParams = z.infer<typeof ProductReviewsZodSchema>;
+
+export async function productReviewsHandler(context: Context, params: ProductReviewsParams) {
+  const { limit, offset, queryString } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`query productReviews: ${limit} ${offset} ${queryString || ''}`, {
+      userId,
+      params,
+    });
+
+    const reviews = await modules.products.reviews.findProductReviews(params as any);
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ reviews }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching product reviews: ${(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/productsCountHandler.ts

@@ -0,0 +1,40 @@
+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().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, userId } = context;
+
+  try {
+    log('handler productsCountHandler', { userId, params });
+    const count = await modules.products.count(params);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: count.toString(),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error counting products: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,48 @@
+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'),
+};
+
+export const PublishProductZodSchema = z.object(PublishProductSchema);
+
+export type PublishProductParams = z.infer<typeof PublishProductZodSchema>;
+
+export async function publishProductHandler(context: Context, params: PublishProductParams) {
+  const { productId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler publishProductHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (!(await modules.products.publish(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 publishing product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+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")'),
+  value: z.string().min(1).describe('Attribute value (e.g., "Red", "M")'),
+});
+
+export const RemoveProductAssignmentSchema = {
+  proxyId: z.string().min(1).describe('ID of the configurable_product'),
+  vectors: z
+    .array(ProductAssignmentVectorSchema)
+    .min(1)
+    .describe('Combination of attributes uniquely identifying the variant'),
+};
+export const RemoveProductAssignmentZodSchema = z.object(RemoveProductAssignmentSchema);
+export type RemoveProductAssignmentParams = z.infer<typeof RemoveProductAssignmentZodSchema>;
+
+export async function removeProductAssignmentHandler(
+  context: Context,
+  params: RemoveProductAssignmentParams,
+) {
+  const { proxyId, vectors } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler removeProductAssignmentHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId: proxyId });
+
+    if (product.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        productId: proxyId,
+        received: product.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+
+    await modules.products.assignments.removeAssignment(proxyId, { vectors: vectors as any });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(proxyId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error removing product assignment: ${(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/removeProductHandler.ts

@@ -0,0 +1,42 @@
+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'),
+};
+
+export const RemoveProductZodSchema = z.object(RemoveProductSchema);
+
+export type RemoveProductParams = z.infer<typeof RemoveProductZodSchema>;
+
+export async function removeProductHandler(context: Context, params: RemoveProductParams) {
+  const { productId } = params;
+  const { services, userId } = context;
+
+  try {
+    log('handler removeProductHandler', { userId, params });
+    await services.products.removeProduct({ productId });
+
+    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 product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}