@unchainedshop/api 3.1.13 → 4.0.0-rc.3

package/src/mcp/tools/countriesHandler.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { SortDirection } from '@unchainedshop/utils';
+
+const sortDirectionKeys = Object.keys(SortDirection) as [
+  keyof typeof SortDirection,
+  ...(keyof typeof SortDirection)[],
+];
+
+export const ListCountriesSchema = {
+  limit: z.number().int().min(1).max(100).default(50),
+  offset: z.number().int().min(0).default(0),
+  includeInactive: z.boolean().default(false),
+  queryString: z.string().min(1).optional(),
+  sort: z
+    .array(
+      z.object({
+        key: z.string().min(1),
+        value: z.enum(sortDirectionKeys).describe("Sort direction, e.g., 'ASC' or 'DESC'"),
+      }),
+    )
+    .optional(),
+};
+
+export const ListCountriesZodSchema = z.object(ListCountriesSchema);
+
+export type ListCountriesParams = z.infer<typeof ListCountriesZodSchema>;
+
+export async function countriesHandler(context: Context, params: ListCountriesParams) {
+  const { limit, offset, includeInactive, queryString, sort } = params;
+  const { modules } = context;
+
+  try {
+    const countries = await modules.countries.findCountries({
+      limit,
+      offset,
+      includeInactive,
+      queryString,
+      sort: sort as any[],
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ countries }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving countries: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/countryHandler.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { CountryNotFoundError } from '../../errors.js';
+
+export const CountrySchema = {
+  countryId: z.string().min(1).describe('The ID of the country to fetch'),
+};
+
+export const CountryZodSchema = z.object(CountrySchema);
+
+export type CountryParams = z.infer<typeof CountryZodSchema>;
+
+export async function countryHandler(context: Context, params: CountryParams) {
+  const { countryId } = params;
+  const { modules } = context;
+
+  try {
+    const country = await modules.countries.findCountry({ countryId });
+
+    if (!country) throw new CountryNotFoundError({ countryId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ country }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving country: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/createLanguageHandler.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+
+const CreateLanguageInputSchema = z.object({
+  isoCode: z
+    .string()
+    .min(2)
+    .max(10)
+    .describe('Language ISO code, e.g. "en" or "de-CH, accept only valid ISO code"'),
+});
+
+export const CreateLanguageSchema = {
+  language: CreateLanguageInputSchema,
+};
+
+export const CreateLanguageZodSchema = z.object(CreateLanguageSchema);
+export type CreateLanguageParams = z.infer<typeof CreateLanguageZodSchema>;
+
+export async function createLanguageHandler(context: Context, params: CreateLanguageParams) {
+  const { language } = params;
+  const { modules } = context;
+
+  try {
+    const languageId = await modules.languages.create(language as any);
+
+    const newLanguage = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: newLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/createProduct.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { Product, ProductText, ProductTypes } from '@unchainedshop/core-products';
+const productTypeKeys = Object.keys(ProductTypes) as [
+  keyof typeof ProductTypes,
+  ...(keyof typeof ProductTypes)[],
+];
+
+export const CreateProductSchema = {
+  product: z.object({
+    type: z.enum(productTypeKeys).describe('Product type (e.g., "SIMPLE_PRODUCT")'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags (lowercased strings)'),
+  }),
+  texts: z
+    .array(
+      z.object({
+        locale: z
+          .string()
+          .min(2)
+          .describe(
+            'Locale code like "en", "de" always use locales registered in the system languages, if language 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 CreateProductZodSchema = z.object(CreateProductSchema);
+
+export type CreateProductParams = z.infer<typeof CreateProductZodSchema>;
+
+export async function createProductHandler(context: Context, params: CreateProductParams) {
+  const { product, texts } = params;
+
+  try {
+    const newProduct = await context.modules.products.create(product as Product);
+    let productTexts: any[] = texts;
+    if (texts) {
+      productTexts = await context.modules.products.texts.updateTexts(
+        newProduct._id,
+        texts as unknown as ProductText[],
+      );
+    }
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: {
+              ...newProduct,
+              texts: productTexts,
+            },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/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 code like "en", "de" always use locales registered in the system languages, if language 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/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 code like "en", "de" always use locales registered in the system languages, if language 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/currenciesHandler.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { SortDirection } from '@unchainedshop/utils';
+
+const sortDirectionKeys = Object.keys(SortDirection) as [
+  keyof typeof SortDirection,
+  ...(keyof typeof SortDirection)[],
+];
+
+export const ListCurrenciesSchema = {
+  limit: z.number().int().min(1).max(100).default(50),
+  offset: z.number().int().min(0).default(0),
+  includeInactive: z.boolean().default(false),
+  queryString: z.string().min(1).optional(),
+  sort: z
+    .array(
+      z.object({
+        key: z.string().min(1),
+        value: z.enum(sortDirectionKeys).describe("Sort direction, e.g., 'ASC' or 'DESC'"),
+      }),
+    )
+    .optional(),
+};
+
+export const ListCurrenciesZodSchema = z.object(ListCurrenciesSchema);
+
+export type ListCurrenciesParams = z.infer<typeof ListCurrenciesZodSchema>;
+
+export async function currenciesHandler(context: Context, params: ListCurrenciesParams) {
+  const { limit, offset, includeInactive, queryString, sort } = params;
+
+  const { modules } = context;
+
+  try {
+    const currencies = await modules.currencies.findCurrencies({
+      limit,
+      offset,
+      includeInactive,
+      queryString,
+      sort: sort as any[],
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            currencies,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving currencies: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/currencyHandler.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { CurrencyNotFoundError } from '../../errors.js';
+
+export const CurrencySchema = {
+  currencyId: z.string().min(1).describe('The ID of the currency to fetch'),
+};
+
+export const CurrencyZodSchema = z.object(CurrencySchema);
+
+export type CurrencyParams = z.infer<typeof CurrencyZodSchema>;
+
+export async function currencyHandler(context: Context, params: CurrencyParams) {
+  const { currencyId } = params;
+  const { modules } = context;
+
+  try {
+    const currency = await modules.currencies.findCurrency({ currencyId });
+
+    if (!currency) throw new CurrencyNotFoundError({ currencyId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ currency }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving currency: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/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/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Re-export all MCP tools
+ */
+
+export * from './listProducts.js';
+export * from './getProduct.js';
+export * from './createProduct.js';
+export * from './removeProductHandler.js';
+export * from './publishProduct.js';
+export * from './unPublishProduct.js';
+export * from './updateProduct.js';
+export * from './updateProductTextsHandler.js';
+export * from './updateProductCommerceHandler.js';
+export * from './updateProductSupplyHandler.js';
+export * from './updateProductWarehousingHandler.js';
+export * from './currenciesHandler.js';
+export * from './currencyHandler.js';
+export * from './countriesHandler.js';
+export * from './countryHandler.js';
+export * from './languagesHandler.js';
+export * from './languageHandler.js';
+export * from './updateProductPlanHandler.js';
+export * from './updateProductTokenizationHandler.js';
+export * from './productsCountHandler.js';
+export * from './createProductVariationHandler.js';
+export * from './removeProductVariationHandler.js';
+export * from './addProductAssignmentHandler.js';
+export * from './createProductVariationOptionHandler.js';
+export * from './removeProductAssignmentHandler.js';
+export * from './removeProductVariationOptionHandler.js';
+export * from './createLanguageHandler.js';
+export * from './updateLanguageHandler.js';
+export * from './removeLanguageHandler.js';
+export * from './addProductMediaUploadHandler.js';
+export * from './removeProductMediaHandler.js';
+export * from './updateProductMediaTextsHandler.js';
+export * from './reorderProductMediaHandler.js';
+export * from './productReviewsCountHandler.js';
+export * from './productReviewsHandler.js';

package/src/mcp/tools/languageHandler.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+
+export const LanguageSchema = {
+  languageId: z.string().min(1).describe('The ID of the language to fetch'),
+};
+
+export const LanguageZodSchema = z.object(LanguageSchema);
+
+export type LanguageParams = z.infer<typeof LanguageZodSchema>;
+
+export async function languageHandler(context: Context, params: LanguageParams) {
+  const { languageId } = params;
+  const { modules } = context;
+
+  try {
+    const language = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/languagesHandler.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { SortDirection } from '@unchainedshop/utils';
+
+const sortDirectionKeys = Object.keys(SortDirection) as [
+  keyof typeof SortDirection,
+  ...(keyof typeof SortDirection)[],
+];
+
+export const ListLanguagesSchema = {
+  limit: z.number().int().min(1).max(100).default(50),
+  offset: z.number().int().min(0).default(0),
+  includeInactive: z.boolean().default(false),
+  queryString: z.string().min(1).optional(),
+  sort: z
+    .array(
+      z.object({
+        key: z.string().min(1),
+        value: z.enum(sortDirectionKeys).describe("Sort direction, e.g., 'ASC' or 'DESC'"),
+      }),
+    )
+    .optional(),
+};
+
+export const ListLanguagesZodSchema = z.object(ListLanguagesSchema);
+
+export type ListLanguagesParams = z.infer<typeof ListLanguagesZodSchema>;
+
+export async function languagesHandler(context: Context, params: ListLanguagesParams) {
+  const { sort, ...restParams } = params;
+  const { modules } = context;
+
+  try {
+    const languages = await modules.languages.findLanguages({ ...restParams, sort: sort as any[] });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ languages }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving languages: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}