@unchainedshop/api 4.0.0-rc.3 → 4.0.0-rc.5

package/src/mcp/tools/assortment/reorderAssortmentProductsHandler.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const ReorderAssortmentProductInputSchema = z.object({
+  assortmentProductId: z.string().min(1).describe('ID of the assortment product to reorder'),
+  sortKey: z.number().describe('New sorting key for the product'),
+});
+
+export const ReorderAssortmentProductsSchema = {
+  sortKeys: z
+    .array(ReorderAssortmentProductInputSchema)
+    .min(1)
+    .describe('Array of assortmentProductId with their new sort keys'),
+};
+
+export const ReorderAssortmentProductsZodSchema = z.object(ReorderAssortmentProductsSchema);
+
+export type ReorderAssortmentProductsParams = z.infer<typeof ReorderAssortmentProductsZodSchema>;
+
+export async function reorderAssortmentProductsHandler(
+  context: Context,
+  params: ReorderAssortmentProductsParams,
+) {
+  const { sortKeys } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler reorderAssortmentProductsHandler', { userId, params });
+
+    await modules.assortments.products.updateManualOrder({
+      sortKeys,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ success: true }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error reordering assortment products: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/searchAssortmentProductHandler.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const SearchAssortmentProductSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to search in'),
+  queryString: z.string().optional().describe('Search query string'),
+  filterQuery: z
+    .array(
+      z.object({
+        key: z.string().describe('Filter key'),
+        value: z.string().optional().describe('Optional filter value'),
+      }),
+    )
+    .optional()
+    .describe('Filter conditions'),
+  includeInactive: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe('Whether to include inactive products in search results'),
+  ignoreChildAssortments: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Whether to ignore child assortments during search'),
+  limit: z.number().int().min(1).max(100).default(20).describe('Pagination limit'),
+  offset: z.number().int().min(0).default(0).describe('Pagination offset'),
+};
+
+export const SearchAssortmentProductZodSchema = z.object(SearchAssortmentProductSchema);
+
+export type SearchAssortmentProductParams = z.infer<typeof SearchAssortmentProductZodSchema>;
+
+export async function searchAssortmentProductHandler(
+  context: Context,
+  params: SearchAssortmentProductParams,
+) {
+  const { userId, modules, services, locale } = context;
+  const { assortmentId, limit, offset, ...query } = params;
+
+  try {
+    log('handler searchAssortmentProductHandler', { userId, params });
+
+    const productIds = await modules.assortments.findProductIds({
+      assortmentId,
+      ignoreChildAssortments: query.ignoreChildAssortments,
+    });
+
+    const filterIds = await modules.assortments.filters.findFilterIds({
+      assortmentId,
+    });
+    const result = await services.filters.searchProducts({ ...query, productIds, filterIds } as any, {
+      locale: locale,
+    });
+    const productsCount = await modules.products.search.countFilteredProducts({
+      productSelector: result.searchConfiguration.productSelector,
+      productIds: result.aggregatedTotalProductIds,
+    });
+    const products = await modules.products.search.findFilteredProducts({
+      limit,
+      offset,
+      productIds: result.aggregatedFilteredProductIds,
+      productSelector: result.searchConfiguration.productSelector,
+      sort: result.searchConfiguration.sortStage,
+    });
+
+    const relevantProductIds = await modules.products.findProductIds({
+      productSelector: result.searchConfiguration.productSelector,
+      productIds: result.totalProductIds,
+      includeDrafts: result.searchConfiguration.searchQuery.includeInactive,
+    });
+    const filters = await services.filters.loadFilters(result.searchConfiguration.searchQuery, {
+      productIds: relevantProductIds,
+      forceLiveCollection: result.searchConfiguration.forceLiveCollection,
+    });
+    const filteredProductsCount = await modules.products.search.countFilteredProducts({
+      productSelector: result.searchConfiguration.productSelector,
+      productIds: result.aggregatedFilteredProductIds,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ productsCount, products, filters, filteredProductsCount }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error searching products: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/setBaseAssortmentHandler.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+import { AssortmentNotFoundError } from '../../../errors.js';
+
+export const SetBaseAssortmentSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to set as base'),
+};
+
+export const SetBaseAssortmentZodSchema = z.object(SetBaseAssortmentSchema);
+export type SetBaseAssortmentParams = z.infer<typeof SetBaseAssortmentZodSchema>;
+
+export async function setBaseAssortmentHandler(context: Context, params: SetBaseAssortmentParams) {
+  const { modules, userId } = context;
+  const { assortmentId } = params;
+
+  try {
+    log('handler setBaseAssortmentHandler', { userId, params });
+
+    if (!(await modules.assortments.assortmentExists({ assortmentId })))
+      throw new AssortmentNotFoundError({ assortmentId });
+
+    await modules.assortments.setBase(assortmentId);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            assortment: await getNormalizedAssortmentDetails({ assortmentId }, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error setting base assortment: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/translatedAssortmentMediaTextsHandler.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const TranslatedAssortmentMediaTextsSchema = {
+  assortmentMediaId: z.string().min(1).describe('ID of the assortment media to retrieve texts for'),
+};
+
+export const TranslatedAssortmentMediaTextsZodSchema = z.object(TranslatedAssortmentMediaTextsSchema);
+
+export type TranslatedAssortmentMediaTextsParams = z.infer<
+  typeof TranslatedAssortmentMediaTextsZodSchema
+>;
+
+export async function translatedAssortmentMediaTextsHandler(
+  context: Context,
+  params: TranslatedAssortmentMediaTextsParams,
+) {
+  const { assortmentMediaId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler translatedAssortmentMediaTextsHandler', { userId, params });
+
+    const texts = await modules.assortments.media.texts.findMediaTexts({
+      assortmentMediaId,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving assortment media texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/translatedAssortmentTextsHandler.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const TranslatedAssortmentTextsSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to retrieve texts for'),
+};
+
+export const TranslatedAssortmentTextsZodSchema = z.object(TranslatedAssortmentTextsSchema);
+
+export type TranslatedAssortmentTextsParams = z.infer<typeof TranslatedAssortmentTextsZodSchema>;
+
+export async function translatedAssortmentTextsHandler(
+  context: Context,
+  params: TranslatedAssortmentTextsParams,
+) {
+  const { assortmentId } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler translatedAssortmentTextsHandler', { userId, params });
+
+    const texts = await modules.assortments.texts.findTexts({ assortmentId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving assortment texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/updateAssortmentHandler.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { AssortmentNotFoundError } from '../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+
+export const UpdateAssortmentInputSchema = z.object({
+  isRoot: z
+    .boolean()
+    .optional()
+    .describe('If true, sets this assortment as a root assortment (top-level).'),
+  isActive: z.boolean().optional().describe('Whether this assortment is active'),
+  sequence: z
+    .number()
+    .int()
+    .optional()
+    .describe('Order of the assortment in a sorted list (lower number = higher priority).'),
+  tags: z
+    .array(z.string().min(1).toLowerCase())
+    .optional()
+    .describe('Tags (lowercase) used to categorize or filter the assortment.'),
+});
+
+export const UpdateAssortmentSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to update'),
+  assortment: UpdateAssortmentInputSchema.describe('Partial object with fields to update.'),
+};
+
+export const UpdateAssortmentZodSchema = z.object(UpdateAssortmentSchema);
+export type UpdateAssortmentParams = z.infer<typeof UpdateAssortmentZodSchema>;
+
+export async function updateAssortmentHandler(context: Context, params: UpdateAssortmentParams) {
+  const { modules, userId } = context;
+  const { assortmentId, assortment } = params;
+
+  try {
+    log('handler updateAssortmentHandler', { userId, params });
+
+    if (!(await modules.assortments.assortmentExists({ assortmentId })))
+      throw new AssortmentNotFoundError({ assortmentId });
+
+    await modules.assortments.update(assortmentId, assortment as any);
+    const updatedAssortment = await getNormalizedAssortmentDetails({ assortmentId }, context);
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            assortment: updatedAssortment,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating assortment: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/updateAssortmentMediaTextsHandler.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { AssortmentMediaNotFoundError } from '../../../errors.js';
+
+export const AssortmentMediaTextInputSchema = 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'),
+});
+
+export const UpdateAssortmentMediaTextsSchema = {
+  assortmentMediaId: z.string().min(1).describe('ID of the assortment media to update'),
+  texts: z.array(AssortmentMediaTextInputSchema).min(1).describe('Localized text values to update'),
+};
+
+export const UpdateAssortmentMediaTextsZodSchema = z.object(UpdateAssortmentMediaTextsSchema);
+
+export type UpdateAssortmentMediaTextsParams = z.infer<typeof UpdateAssortmentMediaTextsZodSchema>;
+
+export async function updateAssortmentMediaTextsHandler(
+  context: Context,
+  params: UpdateAssortmentMediaTextsParams,
+) {
+  const { assortmentMediaId, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateAssortmentMediaTextsHandler', { userId, params });
+
+    const assortmentMedia = await modules.assortments.media.findAssortmentMedia({
+      assortmentMediaId,
+    });
+
+    if (!assortmentMedia) throw new AssortmentMediaNotFoundError({ assortmentMediaId });
+
+    const assortmentMediaTexts = await modules.assortments.media.texts.updateMediaTexts(
+      assortmentMediaId,
+      texts,
+    );
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ assortmentMediaTexts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating assortment media texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/assortment/updateAssortmentTextsHandler.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { AssortmentNotFoundError } from '../../../errors.js';
+
+export const AssortmentAssortmentTextInputSchema = z.object({
+  locale: z
+    .string()
+    .min(2)
+    .describe(
+      `Locale ISO code for the language of the text (e.g., "en-US", "de-CH").
+If not provided, fallback to the shop's defaultLanguageIsoCode.
+If provided, it must be a valid language configured in the shop.`,
+    ),
+  slug: z
+    .string()
+    .optional()
+    .describe('Optional URL-safe identifier for the assortment (e.g., "summer-sale").'),
+  title: z.string().optional().describe('Optional title for the assortment in this locale.'),
+  subtitle: z.string().optional().describe('Optional subtitle providing extra context.'),
+  description: z.string().optional().describe('Optional long-form description of the assortment.'),
+});
+
+export const UpdateAssortmentTextsSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to update'),
+  texts: z.array(AssortmentAssortmentTextInputSchema).min(1).describe('Localized metadata to update'),
+};
+
+export const UpdateAssortmentTextsZodSchema = z.object(UpdateAssortmentTextsSchema);
+
+export type UpdateAssortmentTextsParams = z.infer<typeof UpdateAssortmentTextsZodSchema>;
+
+export async function updateAssortmentTextsHandler(
+  context: Context,
+  params: UpdateAssortmentTextsParams,
+) {
+  const { assortmentId, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler updateAssortmentTextsHandler', { userId, params });
+
+    if (!(await modules.assortments.assortmentExists({ assortmentId })))
+      throw new AssortmentNotFoundError({ assortmentId });
+
+    const assortmentTexts = await modules.assortments.texts.updateTexts(assortmentId, texts as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ texts: assortmentTexts }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error updating assortment texts: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/country/countriesCountHandler.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const CountriesCountSchema = {
+  includeInactive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('If true, include inactive countries in the count. Defaults to false.'),
+  queryString: z
+    .string()
+    .optional()
+    .describe('Optional search string to filter countries by name or code'),
+};
+
+export const CountriesCountZodSchema = z.object(CountriesCountSchema);
+
+export type CountriesCountParams = z.infer<typeof CountriesCountZodSchema>;
+
+export async function countriesCountHandler(context: Context, params: CountriesCountParams) {
+  const { modules, userId } = context;
+
+  try {
+    log(`handler countriesCountHandler`, {
+      userId,
+      params,
+    });
+
+    const count = await modules.countries.count(params);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify(count),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error counting countries: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/{countriesHandler.ts → country/countriesHandler.ts}

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { Context } from '../../context.js';
+import { Context } from '../../../context.js';
 import { SortDirection } from '@unchainedshop/utils';
+import { log } from '@unchainedshop/logger';
 
 const sortDirectionKeys = Object.keys(SortDirection) as [
   keyof typeof SortDirection,
@@ -8,18 +9,37 @@ const sortDirectionKeys = Object.keys(SortDirection) as [
 ];
 
 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(),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(50)
+    .describe('Maximum number of countries to return (pagination limit)'),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe('Number of countries to skip before starting to collect the result set'),
+  includeInactive: z
+    .boolean()
+    .default(false)
+    .describe('Whether to include inactive (disabled) countries in the results'),
+  queryString: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Optional case-insensitive text filter to search country name or code'),
   sort: z
     .array(
       z.object({
-        key: z.string().min(1),
-        value: z.enum(sortDirectionKeys).describe("Sort direction, e.g., 'ASC' or 'DESC'"),
+        key: z.string().min(1).describe('Field name to sort by (e.g., "name", "isoCode")'),
+        value: z.enum(sortDirectionKeys).describe('Sorting direction, either "ASC" or "DESC"'),
       }),
     )
-    .optional(),
+    .optional()
+    .describe('List of fields and their corresponding sort directions'),
 };
 
 export const ListCountriesZodSchema = z.object(ListCountriesSchema);
@@ -28,9 +48,13 @@ 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;
+  const { modules, userId } = context;
 
   try {
+    log(`handler countriesHandler`, {
+      userId,
+      params,
+    });
     const countries = await modules.countries.findCountries({
       limit,
       offset,

package/src/mcp/tools/{countryHandler.ts → country/countryHandler.ts}

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { Context } from '../../context.js';
-import { CountryNotFoundError } from '../../errors.js';
+import { Context } from '../../../context.js';
+import { CountryNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
 
 export const CountrySchema = {
-  countryId: z.string().min(1).describe('The ID of the country to fetch'),
+  countryId: z.string().min(1).describe('ID of the country to retrieve'),
 };
 
 export const CountryZodSchema = z.object(CountrySchema);
@@ -12,9 +13,13 @@ export type CountryParams = z.infer<typeof CountryZodSchema>;
 
 export async function countryHandler(context: Context, params: CountryParams) {
   const { countryId } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log(`handler countryHandler`, {
+      userId,
+      params,
+    });
     const country = await modules.countries.findCountry({ countryId });
 
     if (!country) throw new CountryNotFoundError({ countryId });

package/src/mcp/tools/country/createCountryHandler.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const CreateCountrySchema = {
+  country: z.object({
+    isoCode: z
+      .string()
+      .min(2)
+      .max(2)
+      .toUpperCase()
+      .describe('2-letter ISO 3166-1 alpha-2 country code (e.g., "CH", "US")'),
+  }),
+};
+
+export const CreateCountryZodSchema = z.object(CreateCountrySchema);
+export type CreateCountryParams = z.infer<typeof CreateCountryZodSchema>;
+
+export async function createCountryHandler(context: Context, params: CreateCountryParams) {
+  const { country } = params;
+  const { modules, userId } = context;
+  try {
+    log(`handler createCountryHandler`, { userId, params });
+
+    const countryId = await modules.countries.create(country as any);
+
+    const newCountry = await modules.countries.findCountry({ countryId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ country: newCountry }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating country: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}