@unchainedshop/api 3.1.13 → 4.0.0-rc.10

package/src/locale-context.ts

@@ -1,9 +1,4 @@
-import {
-  resolveBestCountry,
-  resolveBestSupported,
-  resolveBestCurrency,
-  systemLocale,
-} from '@unchainedshop/utils';
+import { resolveBestSupported, resolveBestCurrency } from '@unchainedshop/utils';
 import { UnchainedCore } from '@unchainedshop/core';
 import pMemoize from 'p-memoize';
 import ExpiryMap from 'expiry-map';
@@ -12,15 +7,13 @@ import { createLogger } from '@unchainedshop/logger';
 const logger = createLogger('unchained:api');
 
 export interface UnchainedLocaleContext {
-  countryContext: string;
-  localeContext: Intl.Locale;
-  currencyContext: string;
+  countryCode: string;
+  locale: Intl.Locale;
+  currencyCode: string;
 }
-const { NODE_ENV } = process.env;
-
 export type GetHeaderFn = (key: string) => string | string[];
 
-const memoizeCache = new ExpiryMap(NODE_ENV === 'production' ? 1000 * 60 : 100); // Cached values expire after 10 seconds
+const memoizeCache = new ExpiryMap(process.env.NODE_ENV === 'production' ? 1000 * 60 : 1); // Cached values expire after 10 seconds
 
 export const resolveDefaultContext = pMemoize(
   async ({ acceptLang, acceptCountry }, unchainedAPI) => {
@@ -36,31 +29,20 @@ export const resolveDefaultContext = pMemoize(
 
     const currencies = await unchainedAPI.modules.currencies.findCurrencies({ includeInactive: false });
 
-    const supportedLocaleStrings: Array<string> = languages.reduce((accumulator, language) => {
-      const added = countries.map((country) => {
-        return `${language.isoCode}-${country.isoCode}`;
-      });
-      return accumulator.concat(added);
-    }, []);
+    const locale = resolveBestSupported(acceptLang, acceptCountry, { countries, languages });
 
-    const localeContext = resolveBestSupported(
-      acceptLang,
-      supportedLocaleStrings,
-      systemLocale.baseName,
-    );
-    const countryContext = resolveBestCountry(localeContext.region, acceptCountry, countries);
+    const defaultCurrencyCode = countries.find(
+      (country) => country.isoCode.toUpperCase() === locale?.region?.toUpperCase(),
+    )?.defaultCurrencyCode;
 
-    const countryObject = countries.find((country) => country.isoCode === countryContext);
-    const currencyContext = resolveBestCurrency(countryObject.defaultCurrencyCode, currencies);
+    const currencyCode = resolveBestCurrency(defaultCurrencyCode, currencies);
 
-    logger.debug(
-      `Locale Context: Resolved ${localeContext.baseName} ${countryContext} ${currencyContext}`,
-    );
+    logger.debug(`Locale Context: Resolved ${locale?.baseName} ${currencyCode}`);
 
     const newContext: UnchainedLocaleContext = {
-      localeContext,
-      countryContext,
-      currencyContext,
+      locale,
+      countryCode: locale?.region,
+      currencyCode,
     };
 
     return newContext;

package/src/mcp/README.md

@@ -0,0 +1,25 @@
+# MCP Server
+
+This directory contains the Model Context Protocol (MCP) server implementation for Unchained Commerce.
+
+## Structure
+
+```
+mcp/
+├── index.ts              # Main MCP server setup
+├── types.ts              # Shared type definitions
+├── tools/                # Individual tool implementations
+│   ├── index.ts          # Re-exports for all tools
+│   └── listProducts.ts   # List products tool
+└── utils/                # Shared utilities
+    └── html.ts           # HTML generation utilities
+```
+
+## Adding New Tools
+
+To add a new tool:
+
+1. Create a new file in the `tools/` directory
+2. Export the schema and handler from the file
+3. Add the exports to `tools/index.ts`
+4. Register the tool in the main `index.ts` file

package/src/mcp/index.ts

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../context.js';
+import { registerOtherTools } from './tools/index.js';
+import { registerFilterTools } from './tools/filter/index.js';
+import { registerProductTools } from './tools/product/index.js';
+import { registerAssortmentTools } from './tools/assortment/index.js';
+import { registerCurrencyTools } from './tools/currency/index.js';
+import { registerCountryTools } from './tools/country/index.js';
+import { registerLanguageTools } from './tools/language/index.js';
+import { registerPaymentProviderTools } from './tools/payment/index.js';
+
+export default function createMcpServer(context: Context, roles) {
+  const server = new McpServer({
+    name: 'Unchained MCP Server',
+    version: '1.0.0',
+  });
+
+  if (!roles?.includes('admin')) {
+    return server;
+  }
+  registerFilterTools(server, context);
+  registerProductTools(server, context);
+  registerAssortmentTools(server, context);
+  registerCurrencyTools(server, context);
+  registerCountryTools(server, context);
+  registerLanguageTools(server, context);
+  registerOtherTools(server, context);
+  registerPaymentProviderTools(server, context);
+
+  return server;
+}

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

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { AssortmentNotFoundError, FilterNotFoundError } from '../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+import { getNormalizedFilterDetails } from '../../utils/getNormalizedFilterDetails.js';
+
+export const AddAssortmentFilterSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to which the filter will be added.'),
+
+  filterId: z.string().min(1).describe('ID of the filter being added to the assortment.'),
+
+  tags: z
+    .array(z.string().regex(/^[a-z0-9-_]+$/))
+    .optional()
+    .describe(
+      'Optional array of lowercase tags (letters, numbers, hyphens, underscores). Used to label or categorize the filter connection.',
+    ),
+};
+
+export const AddAssortmentFilterZodSchema = z.object(AddAssortmentFilterSchema);
+
+export type AddAssortmentFilterParams = z.infer<typeof AddAssortmentFilterZodSchema>;
+
+export async function addAssortmentFilterHandler(context: Context, params: AddAssortmentFilterParams) {
+  const { assortmentId, filterId, tags = [] } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler addAssortmentFilterHandler', { userId, params });
+    const assortment = await getNormalizedAssortmentDetails({ assortmentId }, context);
+    if (!assortment) throw new AssortmentNotFoundError({ assortmentId });
+    const filter = await getNormalizedFilterDetails(filterId, context);
+    if (!filter) throw new FilterNotFoundError({ filterId });
+
+    const assortmentFilter = await modules.assortments.filters.create({
+      assortmentId,
+      filterId,
+      tags,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            assortmentFilter: {
+              ...assortmentFilter,
+              filter,
+              assortment,
+            },
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error adding filter to assortment: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,70 @@
+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 AddAssortmentLinkSchema = {
+  parentAssortmentId: z
+    .string()
+    .min(1)
+    .describe('ID of the parent assortment (the container or grouping assortment).'),
+  childAssortmentId: z
+    .string()
+    .min(1)
+    .describe('ID of the child assortment (the linked or nested assortment).'),
+  tags: z
+    .array(z.string().min(1))
+    .default([])
+    .describe('Optional tags to label or categorize this link.'),
+};
+
+export const AddAssortmentLinkZodSchema = z.object(AddAssortmentLinkSchema);
+
+export type AddAssortmentLinkParams = z.infer<typeof AddAssortmentLinkZodSchema>;
+
+export async function addAssortmentLinkHandler(context: Context, params: AddAssortmentLinkParams) {
+  const { parentAssortmentId, childAssortmentId, tags } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler addAssortmentLinkHandler', {
+      userId,
+      params,
+    });
+    const parent = await getNormalizedAssortmentDetails({ assortmentId: parentAssortmentId }, context);
+    if (!parent)
+      throw new AssortmentNotFoundError({
+        assortmentId: parentAssortmentId,
+      });
+    const child = await getNormalizedAssortmentDetails({ assortmentId: childAssortmentId }, context);
+    if (!child)
+      throw new AssortmentNotFoundError({
+        assortmentId: childAssortmentId,
+      });
+
+    const result = await modules.assortments.links.create({
+      parentAssortmentId,
+      childAssortmentId,
+      tags,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ assortmentLink: { ...result, parent, child } }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error adding assortment link: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FileNotFoundError, FileUploadExpiredError } from '../../../errors.js';
+import normalizeMediaUrl from '../../utils/normalizeMediaUrl.js';
+
+export const AddAssortmentMediaUploadSchema = {
+  mediaName: z
+    .string()
+    .min(1)
+    .describe('Name of the media file (e.g., "image.png"). A random name will be used if not provided.'),
+  assortmentId: z.string().min(1).describe('ID of the assortment to link the media to.'),
+  url: z.string().describe('Anonymously fetchable URL of the media file.'),
+};
+
+export const AddAssortmentMediaUploadZodSchema = z.object(AddAssortmentMediaUploadSchema);
+
+export type AddAssortmentMediaUploadParams = z.infer<typeof AddAssortmentMediaUploadZodSchema>;
+
+export async function addAssortmentMediaUploadHandler(
+  context: Context,
+  params: AddAssortmentMediaUploadParams,
+) {
+  const { mediaName, assortmentId, url } = params;
+  const { modules, services, userId } = context;
+
+  try {
+    log('handler addAssortmentMediaUploadHandler', { params, userId });
+    const {
+      _id: fileId,
+      putURL,
+      type,
+      size,
+    } = await services.files.createSignedURL({
+      directoryName: 'assortment-media',
+      fileName: mediaName,
+      meta: { assortmentId },
+    });
+
+    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: await normalizeMediaUrl([{ ...linked, mediaId: linked._id }], context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error uploading Assortment media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { AssortmentNotFoundError, ProductNotFoundError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+
+export const AddAssortmentProductSchema = {
+  assortmentId: z.string().min(1).describe('ID of the assortment to add the product to'),
+  productId: z.string().min(1).describe('ID of the product to add'),
+  tags: z
+    .array(z.string().min(1).toLowerCase())
+    .optional()
+    .describe('Optional tags to associate with this product inside the assortment'),
+};
+
+export const AddAssortmentProductZodSchema = z.object(AddAssortmentProductSchema);
+export type AddAssortmentProductParams = z.infer<typeof AddAssortmentProductZodSchema>;
+
+export async function addAssortmentProductHandler(context: Context, params: AddAssortmentProductParams) {
+  const { modules, userId } = context;
+  const { assortmentId, productId, tags } = params;
+  try {
+    log('mutation addAssortmentProductHandler', { userId, params });
+    const assortment = await getNormalizedAssortmentDetails({ assortmentId }, context);
+    if (!assortment)
+      throw new AssortmentNotFoundError({
+        assortmentId,
+      });
+    const product = await getNormalizedProductDetails(productId, context);
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    const assortmentProduct = await modules.assortments.products.create({
+      assortmentId,
+      productId,
+      tags,
+    } as any);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ assortmentProduct: { ...assortmentProduct, assortment, product } }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error adding product to assortment product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+
+export const AssortmentChildrenSchema = {
+  assortmentId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('ID of the assortment to fetch children for (optional: fetch root-level if omitted)'),
+  includeInactive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Whether to include inactive child assortments in the response'),
+};
+
+export const AssortmentChildrenZodSchema = z.object(AssortmentChildrenSchema);
+
+export type AssortmentChildrenParams = z.infer<typeof AssortmentChildrenZodSchema>;
+
+export async function assortmentChildrenHandler(context: Context, params: AssortmentChildrenParams) {
+  const { userId, modules } = context;
+  const { assortmentId, includeInactive } = params;
+
+  try {
+    log('handler assortmentChildrenHandler', { userId, params });
+    const assortmentChildren = await modules.assortments.children({
+      assortmentId,
+      includeInactive,
+    });
+
+    const normalizedAssortmentChildren = await Promise.all(
+      assortmentChildren.map(async ({ _id }) =>
+        getNormalizedAssortmentDetails({ assortmentId: _id }, context),
+      ),
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ assortments: normalizedAssortmentChildren }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting assortment children: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+
+export const AssortmentFiltersSchema = {
+  assortmentId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('ID of the assortment to fetch filters for (optional)'),
+};
+
+export const AssortmentFiltersZodSchema = z.object(AssortmentFiltersSchema);
+
+export type AssortmentFiltersParams = z.infer<typeof AssortmentFiltersZodSchema>;
+
+export async function assortmentFiltersHandler(context: Context, params: AssortmentFiltersParams) {
+  const { userId, modules } = context;
+  const { assortmentId } = params;
+
+  try {
+    log('handler assortmentFiltersHandler', { userId, params });
+    const assortmentFilters = await modules.assortments.filters.findFilters(
+      {
+        assortmentId,
+      },
+      {
+        sort: { sortKey: 1 },
+      },
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ filters: assortmentFilters }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting assortment filters: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+
+export const AssortmentSchema = {
+  assortmentId: z.string().min(1).optional().describe('ID of the assortment to fetch'),
+  slug: z.string().min(1).optional().describe('Slug of the assortment to fetch'),
+};
+
+export const AssortmentZodSchema = z
+  .object(AssortmentSchema)
+  .refine((data) => !!data.assortmentId || !!data.slug, {
+    message: 'Either assortmentId or slug must be provided.',
+  });
+
+export type AssortmentParams = z.infer<typeof AssortmentZodSchema>;
+
+export async function assortmentHandler(context: Context, params: AssortmentParams) {
+  const { userId } = context;
+  const { assortmentId, slug } = params;
+
+  try {
+    log('handler assortmentHandler', { userId, params });
+
+    const assortment = await getNormalizedAssortmentDetails(
+      {
+        assortmentId,
+        slug,
+      },
+      context,
+    );
+
+    if (!assortment) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Assortment not found  with ${assortmentId ? `ID: ${assortmentId}` : `slug: ${slug}`}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ assortment }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting assortment: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedAssortmentDetails } from '../../utils/getNormalizedAssortmentDetails.js';
+
+export const AssortmentLinksSchema = {
+  assortmentId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('ID of the assortment to fetch links for (optional).'),
+};
+
+export const AssortmentLinksZodSchema = z.object(AssortmentLinksSchema);
+
+export type AssortmentLinksParams = z.infer<typeof AssortmentLinksZodSchema>;
+
+export async function assortmentLinksHandler(context: Context, params: AssortmentLinksParams) {
+  const { userId, loaders } = context;
+  const { assortmentId } = params;
+
+  try {
+    log('handler assortmentLinksHandler', { userId, params });
+    const assortmentLinks = await loaders.assortmentLinksLoader.load({
+      assortmentId,
+    });
+
+    const normalizedAssortmentLinks = await Promise.all(
+      assortmentLinks.map(async ({ parentAssortmentId, childAssortmentId, ...rest }) => {
+        const parent =
+          parentAssortmentId === assortmentId
+            ? null
+            : await getNormalizedAssortmentDetails({ assortmentId: parentAssortmentId }, context);
+        const child =
+          childAssortmentId === assortmentId
+            ? null
+            : await getNormalizedAssortmentDetails({ assortmentId: childAssortmentId }, context);
+
+        return {
+          ...rest,
+          parent,
+          child,
+        };
+      }),
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ links: normalizedAssortmentLinks }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting assortment links: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}