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

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

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductTypes, ProductVariationType } from '@unchainedshop/core-products';
+import { ProductNotFoundError, ProductWrongTypeError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+const productVariationTypeKeys = Object.keys(ProductVariationType) as [
+  keyof typeof ProductVariationType,
+  ...(keyof typeof ProductVariationType)[],
+];
+
+export const CreateProductVariationSchema = {
+  productId: z
+    .string()
+    .min(1)
+    .describe(
+      'Product ID for which to create the variation. it should only be CONFIGURABLE_PRODUCT type product id',
+    ),
+  variation: z.object({
+    key: z
+      .string()
+      .min(1)
+      .describe('unique value that is not already used as key for the products variations vector'),
+    type: z.enum(productVariationTypeKeys).describe('Product variation types'),
+  }),
+  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().describe('variation title'),
+        subtitle: z.string().optional().describe('variation additional description'),
+      }),
+    )
+    .optional(),
+};
+
+export const CreateProductVariationZodSchema = z.object(CreateProductVariationSchema);
+export type CreateProductVariationParams = z.infer<typeof CreateProductVariationZodSchema>;
+
+export async function createProductVariationHandler(
+  context: Context,
+  params: CreateProductVariationParams,
+) {
+  const { productId, variation, texts } = params;
+  const { modules } = context;
+
+  try {
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+
+    const newVariation = await modules.products.variations.create({
+      options: [],
+      productId,
+      ...variation,
+    });
+
+    if (texts) {
+      await modules.products.variations.texts.updateVariationTexts(newVariation._id, 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 creating product variation: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { ProductVariationNotFoundError } from '../../../errors.js';
+
+const ProductVariationTextInputSchema = 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().describe('variation option title in the specified locale'),
+  subtitle: z.string().optional().describe('variation option subtitle in the specified locale'),
+});
+
+export const CreateProductVariationOptionSchema = {
+  productVariationId: z
+    .string()
+    .min(1)
+    .describe('ID of the product variation, it should only be a CONFIGURABLE_PRODUCT type ID'),
+  option: z.string().min(1).describe('Name of the new option (e.g., "Red")'),
+  texts: z.array(ProductVariationTextInputSchema),
+};
+export const CreateProductVariationOptionZodSchema = z.object(CreateProductVariationOptionSchema);
+export type CreateProductVariationOptionParams = z.infer<typeof CreateProductVariationOptionZodSchema>;
+
+export async function createProductVariationOptionHandler(
+  context: Context,
+  params: CreateProductVariationOptionParams,
+) {
+  const { productVariationId, option, texts } = params;
+  const { modules } = context;
+  try {
+    const variation = await modules.products.variations.findProductVariation({
+      productVariationId,
+    });
+    if (!variation) throw new ProductVariationNotFoundError({ productVariationId });
+
+    const newOption = await modules.products.variations.addVariationOption(productVariationId, {
+      value: option,
+    });
+
+    if (texts) {
+      await modules.products.variations.texts.updateVariationTexts(
+        productVariationId,
+        texts as any,
+        option,
+      );
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            variation: newOption,
+            product: await getNormalizedProductDetails(newOption?.productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating variation option: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+/**
+ * Zod schema for the get_product tool (as raw object for MCP)
+ */
+export const GetProductSchema = {
+  productId: z.string().optional().describe('Product ID for lookup'),
+  slug: z.string().optional().describe('Product slug for lookup'),
+  sku: z.string().optional().describe('Product SKU for lookup'),
+};
+
+/**
+ * Zod object schema for type inference and validation
+ */
+export const GetProductZodSchema = z
+  .object(GetProductSchema)
+  .refine(
+    (data) => data.productId || data.slug || data.sku,
+    'At least one of productId, slug, or sku must be provided',
+  );
+
+/**
+ * Interface for the get_product tool parameters
+ */
+export type GetProductParams = z.infer<typeof GetProductZodSchema>;
+
+/**
+ * Implementation of the get_product tool
+ */
+export async function getProductHandler(context: Context, params: GetProductParams) {
+  const { productId, slug, sku } = params;
+
+  try {
+    // Find the product
+    const product = await context.modules.products.findProduct({
+      productId,
+      slug,
+      sku,
+    });
+
+    if (!product) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Product not found with ${productId ? `ID: ${productId}` : slug ? `slug: ${slug}` : `SKU: ${sku}`}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { SortDirection } from '@unchainedshop/utils';
+import { Context } from '../../../context.js';
+import { ProductText } from '@unchainedshop/core-products';
+import normalizeMediaUrl from '../../utils/normalizeMediaUrl.js';
+
+/**
+ * Zod schema for the list_products tool (as raw object for MCP)
+ */
+export const ListProductsSchema = {
+  // Search & Filter
+  queryString: z.string().optional().describe('Text search across product fields'),
+  tags: z.array(z.string()).optional().describe('Filter by product tags'),
+  productIds: z.array(z.string()).optional().describe('Filter by specific product IDs'),
+  filterQuery: z
+    .array(
+      z.object({
+        key: z.string().describe('Filter key'),
+        value: z.string().optional().describe('Filter value'),
+      }),
+    )
+    .optional()
+    .describe('Key-value filter pairs'),
+  assortmentId: z.string().optional().describe('Filter by assortment'),
+  includeInactive: z.boolean().default(false).describe('Include inactive products'),
+
+  // Pagination
+  limit: z.number().min(1).max(100).default(20).describe('Results per page'),
+  offset: z.number().min(0).default(0).describe('Skip results for pagination'),
+
+  // Sorting
+  sort: z
+    .array(
+      z.object({
+        key: z.string().describe('Sort field'),
+        value: z.enum(['ASC', 'DESC']).describe('Sort direction'),
+      }),
+    )
+    .optional()
+    .describe('Sort options'),
+};
+
+/**
+ * Zod object schema for type inference
+ */
+export const ListProductsZodSchema = z.object(ListProductsSchema);
+
+/**
+ * Interface for the list_products tool parameters
+ */
+export type ListProductsParams = z.infer<typeof ListProductsZodSchema>;
+
+/**
+ * Implementation of the list_products tool
+ */
+export async function listProductsHandler(context: Context, params: ListProductsParams) {
+  const {
+    queryString,
+    tags,
+    productIds,
+    filterQuery,
+    assortmentId,
+    includeInactive = false,
+    limit = 20,
+    offset = 0,
+    sort,
+  } = params;
+
+  try {
+    let filteredProductIds = productIds;
+
+    // If assortmentId is provided, get product IDs from assortment
+    if (assortmentId) {
+      const assortmentProductIds = await context.modules.assortments.products.findProductIds({
+        assortmentId,
+      });
+
+      if (filteredProductIds) {
+        // Intersection of both sets
+        filteredProductIds = filteredProductIds.filter((id) => assortmentProductIds.includes(id));
+      } else {
+        filteredProductIds = assortmentProductIds;
+      }
+    }
+
+    let searchResult: any = {};
+    if (queryString)
+      searchResult = await context.services.filters.searchProducts(
+        {
+          queryString,
+          productIds: filteredProductIds,
+          includeInactive,
+          filterQuery: filterQuery?.filter((f) => f.key) as { key: string; value?: string }[],
+        },
+        {
+          locale: context.locale,
+        },
+      );
+    const products = await context.modules.products.findProducts({
+      productIds: searchResult?.aggregatedFilteredProductIds,
+      tags,
+      limit,
+      offset,
+      includeDrafts: includeInactive,
+      sort: sort?.filter((s) => s.key) as { key: string; value: SortDirection }[],
+    });
+
+    const productTexts = await context.loaders.productTextLoader.loadMany(
+      products.map(({ _id }) => ({
+        productId: _id,
+        locale: context.locale,
+      })),
+    );
+
+    // iterate all products and add texts
+    const normalizedProducts = await Promise.all(
+      products.map(async (product) => {
+        const texts = productTexts.filter((text) => (text as ProductText)?.productId === product._id);
+        const productMedias = await context.modules.products.media.findProductMedias({
+          productId: product._id,
+        });
+        const media = await normalizeMediaUrl(productMedias, context);
+        return {
+          ...product,
+          texts,
+          media,
+        };
+      }),
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            products: normalizedProducts,
+            total: searchResult?.aggregatedTotalProductIds?.length,
+            filtered: searchResult?.aggregatedFilteredProductIds?.length || products?.length,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [{ type: 'text' as const, text: `Error listing products: ${(error as Error).message}` }],
+    };
+  }
+}

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

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+
+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 } = context;
+
+  try {
+    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,54 @@
+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,
+    });
+
+    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/productsCountHandler.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+
+export const ProductsCountSchema = {
+  tags: z.array(z.string().min(1)).optional(),
+  slugs: z.array(z.string().min(1)).optional(),
+  includeDrafts: z.boolean().default(false),
+  queryString: z.string().min(1).optional(),
+};
+
+export const ProductsCountZodSchema = z.object(ProductsCountSchema);
+export type ProductsCountParams = z.infer<typeof ProductsCountZodSchema>;
+
+export async function productsCountHandler(context: Context, params: ProductsCountParams) {
+  const { modules } = context;
+
+  try {
+    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,45 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductNotFoundError, ProductWrongStatusError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+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 } = context;
+  try {
+    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,61 @@
+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';
+
+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 } = context;
+
+  try {
+    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/removeProductHandler.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+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 } = context;
+
+  try {
+    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}`,
+        },
+      ],
+    };
+  }
+}