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

package/src/mcp/tools/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Re-export all MCP tools
+ */
+
+export * from './product/listProducts.js';
+export * from './product/getProduct.js';
+export * from './product/createProductHandler.js';
+export * from './product/removeProductHandler.js';
+export * from './product/publishProduct.js';
+export * from './product/unPublishProduct.js';
+export * from './product/updateProduct.js';
+export * from './product/updateProductTextsHandler.js';
+export * from './product/updateProductCommerceHandler.js';
+export * from './product/updateProductSupplyHandler.js';
+export * from './product/updateProductWarehousingHandler.js';
+export * from './language/languagesCountHandler.js';
+export * from './language/languagesHandler.js';
+export * from './language/languageHandler.js';
+export * from './language/createLanguageHandler.js';
+export * from './language/updateLanguageHandler.js';
+export * from './language/removeLanguageHandler.js';
+export * from './product/updateProductPlanHandler.js';
+export * from './product/updateProductTokenizationHandler.js';
+export * from './product/productsCountHandler.js';
+export * from './product/createProductVariationHandler.js';
+export * from './product/removeProductVariationHandler.js';
+export * from './product/addProductAssignmentHandler.js';
+export * from './product/createProductVariationOptionHandler.js';
+export * from './product/removeProductAssignmentHandler.js';
+export * from './product/removeProductVariationOptionHandler.js';
+export * from './product/addProductMediaUploadHandler.js';
+export * from './product/removeProductMediaHandler.js';
+export * from './product/updateProductMediaTextsHandler.js';
+export * from './product/reorderProductMediaHandler.js';
+export * from './product/productReviewsCountHandler.js';
+export * from './product/productReviewsHandler.js';
+export * from './product/translatedProductTextsHandler.js';
+export * from './product/translatedProductMediaTextsHandler.js';
+export * from './product/translatedProductVariationTextsHandler.js';
+export * from './shopInfoHandler.js';
+export * from './country/countriesHandler.js';
+export * from './country/countryHandler.js';
+export * from './country/createCountryHandler.js';
+export * from './country/updateCountryHandler.js';
+export * from './country/removeCountryHandler.js';
+export * from './country/countriesCountHandler.js';
+export * from './currency/createCurrencyHandler.js';
+export * from './currency/updateCurrencyHandler.js';
+export * from './currency/removeCurrencyHandler.js';
+export * from './currency/currenciesCountHandler.js';
+export * from './currency/currenciesHandler.js';
+export * from './currency/currencyHandler.js';
+
+export * from './assortment/assortmentHandler.js';
+export * from './assortment/assortmentsHandler.js';
+export * from './assortment/assortmentsCountHandler.js';
+export * from './assortment/createAssortmentHandler.js';
+export * from './assortment/updateAssortmentHandler.js';
+export * from './assortment/removeAssortmentHandler.js';
+export * from './assortment/setBaseAssortmentHandler.js';
+export * from './assortment/assortmentChildrenHandler.js';
+export * from './assortment/assortmentProductsHandler.js';
+export * from './assortment/searchAssortmentProductHandler.js';
+export * from './assortment/assortmentLinksHandler.js';
+export * from './assortment/assortmentFiltersHandler.js';
+export * from './assortment/addAssortmentProductHandler.js';
+export * from './assortment/removeAssortmentProductHandler.js';
+export * from './assortment/reorderAssortmentProductsHandler.js';
+export * from './assortment/addAssortmentLinkHandler.js';
+export * from './assortment/removeAssortmentLinkHandler.js';
+export * from './assortment/reorderAssortmentLinksHandler.js';
+export * from './assortment/reorderAssortmentMediaHandler.js';
+export * from './assortment/removeAssortmentMediaHandler.js';
+export * from './assortment/addAssortmentMediaUploadHandler.js';
+export * from './assortment/translatedAssortmentTextsHandler.js';
+export * from './assortment/translatedAssortmentMediaTextsHandler.js';
+export * from './assortment/addAssortmentFilterHandler.js';
+export * from './assortment/removeAssortmentFilterHandler.js';
+export * from './assortment/reorderAssortmentFiltersHandler.js';
+
+export * from './filter/createFilterHandler.js';
+export * from './filter/updateFilterHandler.js';
+export * from './filter/removeFilterHandler.js';
+export * from './filter/createFilterOptionHandler.js';
+export * from './filter/updateFilterTextsHandler.js';
+export * from './filter/removeFilterOptionHandler.js';
+export * from './filter/getFilterHandler.js';
+export * from './filter/getFiltersHandler.js';
+export * from './filter/translatedFilterTextsHandler.js';

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const LanguagesCountSchema = {
+  includeInactive: z.boolean().optional().default(false).describe('Include inactive languages in count'),
+  queryString: z.string().optional().describe('Optional search filter'),
+};
+
+export const LanguagesCountZodSchema = z.object(LanguagesCountSchema);
+
+export type LanguagesCountParams = z.infer<typeof LanguagesCountZodSchema>;
+
+export async function languagesCountHandler(context: Context, params: LanguagesCountParams) {
+  const { includeInactive = false, queryString } = params;
+  const { modules, userId } = context;
+
+  try {
+    log(`handler languagesCount (includeInactive: ${includeInactive}, query: ${queryString ?? ''})`, {
+      userId,
+    });
+
+    const count = await modules.languages.count(params);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify(count),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error counting languages: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/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}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/removeLanguageHandler.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { LanguageNotFoundError } from '../../../errors.js';
+
+export const RemoveLanguageSchema = {
+  languageId: z.string().min(1).describe('ID of the language to remove'),
+};
+
+export const RemoveLanguageZodSchema = z.object(RemoveLanguageSchema);
+export type RemoveLanguageParams = z.infer<typeof RemoveLanguageZodSchema>;
+
+export async function removeLanguageHandler(context: Context, params: RemoveLanguageParams) {
+  const { languageId } = params;
+  const { modules } = context;
+
+  try {
+    if (!(await modules.languages.languageExists({ languageId })))
+      throw new LanguageNotFoundError({ languageId });
+
+    await modules.languages.delete(languageId);
+
+    const removeLanguage = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: removeLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error removing language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/language/updateLanguageHandler.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { LanguageNotFoundError } from '../../../errors.js';
+
+const UpdateLanguageInputSchema = z.object({
+  isoCode: z.string().min(2).max(10).describe('Updated ISO code for the language'),
+  isActive: z.boolean().optional().describe('Whether the language is active'),
+});
+
+export const UpdateLanguageSchema = {
+  languageId: z.string().min(1).describe('ID of the language to update'),
+  language: UpdateLanguageInputSchema,
+};
+
+export const UpdateLanguageZodSchema = z.object(UpdateLanguageSchema);
+export type UpdateLanguageParams = z.infer<typeof UpdateLanguageZodSchema>;
+
+export async function updateLanguageHandler(context: Context, params: UpdateLanguageParams) {
+  const { languageId, language } = params;
+  const { modules } = context;
+
+  try {
+    if (!(await modules.languages.languageExists({ languageId })))
+      throw new LanguageNotFoundError({ languageId });
+
+    await modules.languages.update(languageId, language);
+
+    const updatedLanguage = await modules.languages.findLanguage({ languageId });
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: updatedLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import {
+  ProductNotFoundError,
+  ProductVariationVectorAlreadySet,
+  ProductVariationVectorInvalid,
+  ProductWrongTypeError,
+} from '../../../errors.js';
+import { ProductConfiguration, ProductTypes } from '@unchainedshop/core-products';
+
+const extractVariationMatrix = (variations = []) => {
+  const cartesianProduct = (arrays) => {
+    return arrays.reduce(
+      (acc, array) => acc.flatMap((item) => array.map((value) => [...item, value])),
+      [[]],
+    );
+  };
+  const keys = variations.map((item) => item.key);
+  const options = variations.map((item) => item.options);
+  const combinations = cartesianProduct(options);
+  return combinations.map((combination) =>
+    combination.reduce((acc, value, index) => {
+      acc[keys[index]] = value;
+      return acc;
+    }, {}),
+  );
+};
+
+const combinationExists = (matrix, combination) => {
+  return matrix.some((variation) => {
+    return (
+      Object.keys(variation).length === Object.keys(combination).length && // Ensure both have the same number of keys
+      Object.entries(combination).every(([key, value]) => variation[key] === value)
+    );
+  });
+};
+
+// Zod schema for ProductAssignmentVectorInput
+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 AssignProductVariationSchema = {
+  proxyId: z.string().min(1).describe('should be ID of the CONFIGURABLE_PRODUCT (parent) only'),
+  productId: z
+    .string()
+    .min(1)
+    .describe('ID of the product being assigned. can not be a CONFIGURABLE_PRODUCT product'),
+  vectors: z
+    .array(ProductAssignmentVectorSchema)
+    .min(1)
+    .describe('Combination of attributes uniquely identifying the variant'),
+};
+// Full schema for the mutation
+export const AddProductAssignmentZodSchema = z.object(AssignProductVariationSchema);
+
+export type AddProductAssignmentParams = z.infer<typeof AddProductAssignmentZodSchema>;
+
+export async function addProductAssignmentHandler(context: Context, params: AddProductAssignmentParams) {
+  const { proxyId, productId, vectors } = params;
+  const { modules } = context;
+
+  try {
+    const proxyProduct = await modules.products.findProduct({
+      productId: proxyId,
+    });
+    if (!proxyProduct) throw new ProductNotFoundError({ proxyId });
+
+    if (proxyProduct.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        proxyId,
+        received: proxyProduct.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+    const variations = await modules.products.variations.findProductVariations({
+      productId: proxyId,
+    });
+    const variationMatrix = extractVariationMatrix(variations);
+    const normalizedVectors = vectors?.reduce((prev, { key, value }) => {
+      return {
+        ...prev,
+        [key]: value,
+      };
+    }, {});
+    if (!combinationExists(variationMatrix, normalizedVectors))
+      throw new ProductVariationVectorInvalid({ proxyId, vectors });
+
+    const added = await modules.products.assignments.addProxyAssignment({
+      productId,
+      proxyId,
+      vectors: vectors as ProductConfiguration[],
+    });
+
+    if (!added) throw new ProductVariationVectorAlreadySet({ proxyId, vectors });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(proxyId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error assigning product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FileNotFoundError, FileUploadExpiredError } from '../../../errors.js';
+
+export const AddProductMediaUploadSchema = {
+  mediaName: z
+    .string()
+    .min(1)
+    .describe('Name of the media file (e.g. "image.png") use random name if not provided'),
+  productId: z.string().min(1).describe('ID of the product to link media to'),
+  url: z.string().describe('Anonymously fetchable URL of the source media, can be a data URL too'),
+};
+
+export const AddProductMediaUploadZodSchema = z.object(AddProductMediaUploadSchema);
+
+export type AddProductMediaUploadParams = z.infer<typeof AddProductMediaUploadZodSchema>;
+
+export async function addProductMediaUploadHandler(
+  context: Context,
+  params: AddProductMediaUploadParams,
+) {
+  const { mediaName, productId, url } = params;
+  const { modules, services, userId } = context;
+
+  try {
+    log('addProductMediaUploadHandler', { mediaName, productId, userId, url });
+    const {
+      _id: fileId,
+      putURL,
+      type,
+      size,
+    } = await services.files.createSignedURL({
+      directoryName: 'product-media',
+      fileName: mediaName,
+      meta: { productId },
+    });
+
+    const sourceResponse = await fetch(url);
+    const uploadUrl = new URL(putURL, process.env.ROOT_URL || 'http://localhost:4010');
+    const uploadResponse = await fetch(uploadUrl, {
+      method: 'PUT',
+      body: sourceResponse.body,
+      duplex: 'half',
+    } as RequestInit);
+
+    if (!uploadResponse.ok) {
+      throw new Error(`Upload failed: ${uploadResponse.status} ${uploadResponse.statusText}`);
+    }
+
+    const file = await modules.files.findFile({ fileId });
+    if (!file) throw new FileNotFoundError({ fileId });
+
+    if (file.expires && new Date(file.expires).getTime() < Date.now()) {
+      throw new FileUploadExpiredError({ fileId });
+    }
+    const linked = await services.files.linkFile({ fileId, size, type });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            file: linked,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error uploading product media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,74 @@
+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 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 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}`,
+        },
+      ],
+    };
+  }
+}