@unchainedshop/api 4.3.6 → 4.5.0

package/src/mcp/tools/users/schemas.ts

@@ -1,280 +0,0 @@
-import { z } from 'zod';
-import {
-  PaginationSchema,
-  SortingSchema,
-  SearchSchema,
-  DateRangeSchema,
-} from '../../utils/sharedSchemas.js';
-
-export const UserProfileSchema = z.object({
-  displayName: z.string().optional().describe("User's display name shown in the interface"),
-  birthday: z.string().optional().describe("User's birthday in ISO date format (YYYY-MM-DD)"),
-  phoneMobile: z.string().optional().describe("User's mobile phone number"),
-  address: z
-    .object({
-      firstName: z.string().optional().describe('First name for billing/shipping address'),
-      lastName: z.string().optional().describe('Last name for billing/shipping address'),
-      addressLine: z.string().optional().describe('Primary address line (street address)'),
-      addressLine2: z.string().optional().describe('Secondary address line (apartment, suite, etc.)'),
-      postalCode: z.string().optional().describe('Postal/ZIP code'),
-      city: z.string().optional().describe('City name'),
-      regionCode: z.string().optional().describe('Region/state code (e.g. "CA", "TX")'),
-      countryCode: z.string().optional().describe('ISO country code (e.g. "US", "DE", "CH")'),
-    })
-    .optional()
-    .describe("User's address information for billing and shipping"),
-});
-
-export const actionValidators = {
-  LIST: z.object({
-    ...PaginationSchema,
-    ...SortingSchema,
-    ...SearchSchema,
-    includeGuests: z.boolean().optional().describe('Include guest users in results'),
-    emailVerified: z.boolean().optional().describe('Filter by email verification status'),
-    lastLogin: z
-      .object({
-        start: z.string().optional(),
-        end: z.string().optional(),
-      })
-      .optional()
-      .describe('Filter by last login date range'),
-  }),
-
-  COUNT: z.object({
-    ...SearchSchema,
-    includeGuests: z.boolean().optional().describe('Include guest users in count'),
-    emailVerified: z.boolean().optional().describe('Filter by email verification status'),
-    lastLogin: z
-      .object({
-        start: z.string().optional(),
-        end: z.string().optional(),
-      })
-      .optional()
-      .describe('Filter by last login date range'),
-  }),
-
-  GET: z.object({
-    userId: z.string().describe('User ID to retrieve'),
-  }),
-
-  CREATE: z.object({
-    username: z.string().optional().describe('Username for the new user'),
-    email: z.string().optional().describe('Email address for the new user'),
-    password: z.string().optional().describe('Password for the new user'),
-    profile: UserProfileSchema.optional().describe('User profile information'),
-  }),
-
-  UPDATE: z.object({
-    userId: z.string().describe('User ID to update'),
-    profile: UserProfileSchema.optional().describe('Profile updates'),
-    meta: z.any().optional().describe('Additional metadata'),
-  }),
-
-  REMOVE: z.object({
-    userId: z.string().describe('User ID to remove'),
-    removeUserReviews: z.boolean().optional().default(false).describe('Also remove user reviews'),
-  }),
-
-  ENROLL: z.object({
-    email: z.string().describe('Email address for enrollment'),
-    profile: UserProfileSchema.describe('Profile information for new user'),
-    password: z
-      .string()
-      .optional()
-      .describe('Optional password (if not provided, enrollment email sent)'),
-  }),
-
-  SET_TAGS: z.object({
-    userId: z.string().describe('User ID to update'),
-    tags: z.array(z.string()).describe('Array of tags to assign'),
-  }),
-
-  SET_USERNAME: z.object({
-    userId: z.string().describe('User ID to update'),
-    username: z.string().describe('New username to set'),
-  }),
-
-  ADD_EMAIL: z.object({
-    userId: z.string().optional().describe('User ID (optional, defaults to current user)'),
-    email: z.string().describe('Email address to add'),
-  }),
-
-  REMOVE_EMAIL: z.object({
-    userId: z.string().optional().describe('User ID (optional, defaults to current user)'),
-    email: z.string().describe('Email address to remove'),
-  }),
-
-  SEND_ENROLLMENT_EMAIL: z.object({
-    email: z.string().describe('Email address to send enrollment to'),
-  }),
-
-  SEND_VERIFICATION_EMAIL: z.object({
-    email: z.string().optional().describe('Email address to verify (optional)'),
-  }),
-
-  REMOVE_PRODUCT_REVIEWS: z.object({
-    userId: z.string().describe('User ID whose reviews to remove'),
-  }),
-
-  GET_ORDERS: z.object({
-    userId: z.string().describe('User ID to get orders for'),
-    ...PaginationSchema,
-    ...SortingSchema,
-    ...SearchSchema,
-    includeCarts: z.boolean().optional().default(false).describe('Include cart orders'),
-    status: z.array(z.string()).optional().describe('Filter by order status'),
-  }),
-
-  GET_ENROLLMENTS: z.object({
-    userId: z.string().describe('User ID to get enrollments for'),
-    ...PaginationSchema,
-    ...SortingSchema,
-    ...SearchSchema,
-    status: z.array(z.string()).optional().describe('Filter by enrollment status'),
-  }),
-
-  GET_QUOTATIONS: z.object({
-    userId: z.string().describe('User ID to get quotations for'),
-    ...PaginationSchema,
-    ...SortingSchema,
-    ...SearchSchema,
-  }),
-
-  GET_BOOKMARKS: z.object({
-    userId: z.string().describe('User ID to get bookmarks for'),
-  }),
-  GET_CURRENT_USER: z.object({}),
-
-  GET_PAYMENT_CREDENTIALS: z.object({
-    userId: z.string().describe('User ID to get payment credentials for'),
-  }),
-
-  GET_AVATAR: z.object({
-    userId: z.string().describe('User ID to get avatar for'),
-  }),
-
-  GET_REVIEWS: z.object({
-    userId: z.string().describe('User ID to get reviews for'),
-    ...PaginationSchema,
-    ...SortingSchema,
-  }),
-
-  GET_REVIEWS_COUNT: z.object({
-    userId: z.string().describe('User ID to count reviews for'),
-  }),
-} as const;
-
-export const UsersManagementSchema = {
-  action: z
-    .enum([
-      'LIST',
-      'COUNT',
-      'GET',
-      'CREATE',
-      'UPDATE',
-      'REMOVE',
-      'ENROLL',
-      'SET_TAGS',
-      'SET_USERNAME',
-      'ADD_EMAIL',
-      'REMOVE_EMAIL',
-      'SEND_ENROLLMENT_EMAIL',
-      'SEND_VERIFICATION_EMAIL',
-      'REMOVE_PRODUCT_REVIEWS',
-      'GET_ORDERS',
-      'GET_ENROLLMENTS',
-      'GET_QUOTATIONS',
-      'GET_BOOKMARKS',
-      'GET_PAYMENT_CREDENTIALS',
-      'GET_AVATAR',
-      'GET_REVIEWS',
-      'GET_REVIEWS_COUNT',
-      'GET_CURRENT_USER',
-    ])
-    .describe(
-      'User management action to perform. LIST: list users with filters and pagination. COUNT: count users matching criteria. GET: retrieve single user by ID. CREATE: create new user account. UPDATE: update user profile/metadata. REMOVE: mark user as deleted. ENROLL: create user and send enrollment email. SET_TAGS: assign tags to user. SET_USERNAME: set user username. ADD_EMAIL/REMOVE_EMAIL: manage user email addresses. SEND_ENROLLMENT_EMAIL/SEND_VERIFICATION_EMAIL: trigger email workflows. REMOVE_PRODUCT_REVIEWS: delete all reviews by user. GET_ORDERS/GET_ENROLLMENTS/GET_QUOTATIONS/GET_BOOKMARKS/GET_PAYMENT_CREDENTIALS/GET_AVATAR/GET_REVIEWS/GET_REVIEWS_COUNT/GET_CURRENT_USER: retrieve user-related data with optional filtering and pagination.',
-    ),
-  userId: z
-    .string()
-    .optional()
-    .describe(
-      'Required for: GET, UPDATE, REMOVE, SET_TAGS, SET_USERNAME, GET_ORDERS, GET_ENROLLMENTS, GET_QUOTATIONS, GET_BOOKMARKS, GET_PAYMENT_CREDENTIALS, GET_AVATAR, GET_REVIEWS, GET_REVIEWS_COUNT, REMOVE_PRODUCT_REVIEWS. Optional for: ADD_EMAIL, REMOVE_EMAIL (defaults to current user if not provided)',
-    ),
-
-  username: z
-    .string()
-    .optional()
-    .describe(
-      'Used for: CREATE (optional username for new user), SET_USERNAME (new username to assign)',
-    ),
-  email: z
-    .string()
-    .optional()
-    .describe(
-      'Used for: CREATE (optional email for new user), ENROLL (required email for enrollment), ADD_EMAIL/REMOVE_EMAIL (email address to add/remove), SEND_ENROLLMENT_EMAIL/SEND_VERIFICATION_EMAIL (target email address)',
-    ),
-  password: z
-    .string()
-    .optional()
-    .describe(
-      'Used for: CREATE (optional password for new user), ENROLL (optional password - if not provided, enrollment email is sent)',
-    ),
-  profile: UserProfileSchema.optional().describe(
-    'Used for: CREATE (optional profile data for new user), UPDATE (profile updates to apply), ENROLL (required profile data for new user including displayName, birthday, phoneMobile, address)',
-  ),
-  // meta: z.any().optional().describe('Used for: UPDATE (additional metadata to store with user profile)'),
-  tags: z
-    .array(z.string())
-    .optional()
-    .describe('Used for: SET_TAGS (array of tag names to assign to user for categorization/filtering)'),
-  removeUserReviews: z
-    .boolean()
-    .optional()
-    .describe(
-      'Used for: REMOVE (if true, also delete all product reviews authored by the user when removing the user account)',
-    ),
-  ...PaginationSchema,
-  ...SortingSchema,
-  ...SearchSchema,
-  ...DateRangeSchema,
-  includeGuests: z
-    .boolean()
-    .optional()
-    .describe(
-      'Used for: LIST, COUNT (if true, include guest/anonymous users in results, default: false)',
-    ),
-  emailVerified: z
-    .boolean()
-    .optional()
-    .describe(
-      'Used for: LIST, COUNT (filter users by email verification status - true: only verified emails, false: only unverified emails, undefined: all users)',
-    ),
-  lastLogin: z
-    .object({
-      start: z.string().optional().describe('ISO date string for earliest last login date'),
-      end: z.string().optional().describe('ISO date string for latest last login date'),
-    })
-    .optional()
-    .describe('Used for: LIST, COUNT (filter users by their last login date range)'),
-
-  includeCarts: z
-    .boolean()
-    .optional()
-    .describe(
-      'Used for: GET_ORDERS (if true, include cart/open orders in results along with completed orders, default: false)',
-    ),
-  status: z
-    .array(z.string())
-    .optional()
-    .describe(
-      'Used for: GET_ORDERS (filter by order status like ["PENDING", "CONFIRMED"]), GET_ENROLLMENTS (filter by enrollment status like ["ACTIVE", "PAUSED"])',
-    ),
-};
-
-export const UsersManagementZodSchema = z.object(UsersManagementSchema);
-export type UsersManagementParams = z.infer<typeof UsersManagementZodSchema>;
-
-export type ActionName = keyof typeof actionValidators;
-export type Params<T extends ActionName> = z.infer<(typeof actionValidators)[T]>;
-export type Handler<T extends ActionName> = (usersModule: any, params: Params<T>) => Promise<unknown>;

package/src/mcp/tools/users/usersManagement.ts

@@ -1,34 +0,0 @@
-import { Context } from '../../../context.js';
-import { log } from '@unchainedshop/logger';
-import {
-  actionValidators,
-  UsersManagementSchema,
-  UsersManagementZodSchema,
-  UsersManagementParams,
-  ActionName,
-} from './schemas.js';
-import actionHandlers from './handlers/index.js';
-import { createMcpResponse, createMcpErrorResponse } from '../../utils/sharedSchemas.js';
-
-export { UsersManagementSchema, UsersManagementZodSchema, UsersManagementParams };
-
-export async function usersManagement(context: Context, params: UsersManagementParams) {
-  const { action, ...actionParams } = params;
-  log('MCP handler usersManagement ', { userId: context.userId, params });
-
-  try {
-    if (!(action in actionHandlers)) {
-      throw new Error(`Unknown action: ${action}`);
-    }
-
-    const parsedParams = actionValidators[action as ActionName].parse(actionParams);
-    const data = await actionHandlers[action as ActionName](context, parsedParams as never);
-
-    return createMcpResponse({
-      action,
-      data,
-    });
-  } catch (error) {
-    return createMcpErrorResponse(action, error);
-  }
-}

package/src/mcp/utils/getNormalizedAssortmentDetails.ts

@@ -1,58 +0,0 @@
-import { Context } from '../../context.js';
-import normalizeMediaUrl from './normalizeMediaUrl.js';
-
-export async function getNormalizedAssortmentDetails(
-  { assortmentId, slug }: { assortmentId?: string; slug?: string },
-  context: Context,
-) {
-  const { modules, locale, loaders } = context;
-  const assortment = await modules.assortments.findAssortment({ assortmentId, slug });
-  const normalizedAssortmentId = assortmentId || assortment!._id;
-  if (!assortment) return null;
-
-  const texts = await loaders.assortmentTextLoader.load({
-    assortmentId: normalizedAssortmentId,
-    locale,
-  });
-
-  const filters = await modules.assortments.filters.findFilters(
-    { assortmentId: assortment._id },
-    { sort: { sortKey: 1 } },
-  );
-
-  const assortmentMedias = await modules.assortments.media.findAssortmentMedias({
-    assortmentId: normalizedAssortmentId,
-  });
-  const assortmentChildLinks = await loaders.assortmentLinksLoader.load({
-    parentAssortmentId: assortment._id,
-  });
-
-  const links =
-    (await loaders.assortmentLinksLoader.load({
-      assortmentId: assortment._id,
-    })) || [];
-
-  const products = await modules.assortments.products.findAssortmentProducts(
-    { assortmentId: assortment._id },
-    { sort: { sortKey: 1 } },
-  );
-
-  const assortmentIds = assortmentChildLinks.map(({ childAssortmentId }) => childAssortmentId);
-
-  const childrenCount = await modules.assortments.count({
-    assortmentIds,
-    includeInactive: true,
-    includeLeaves: true,
-  });
-  const media = await normalizeMediaUrl(assortmentMedias, context);
-
-  return {
-    ...assortment,
-    texts,
-    media,
-    childrenCount,
-    filters,
-    links,
-    products,
-  };
-}

package/src/mcp/utils/getNormalizedFilterDetails.ts

@@ -1,23 +0,0 @@
-import { Context } from '../../context.js';
-
-export async function getNormalizedFilterDetails(filterId: string, context: Context) {
-  const { modules, locale, loaders } = context;
-  const filter = await modules.filters.findFilter({ filterId });
-
-  const texts = await loaders.filterTextLoader.load({
-    filterId,
-    filterOptionValue: null,
-    locale,
-  });
-
-  const options = await (filter!.options || []).map((filterOption) => ({
-    ...filter!,
-    filterOption,
-  }));
-
-  return {
-    ...filter!,
-    options,
-    texts,
-  };
-}

package/src/mcp/utils/getNormalizedOrderDetails.ts

@@ -1,77 +0,0 @@
-import { OrderPricingSheet } from '@unchainedshop/core';
-import { Context } from '../../context.js';
-import { getNormalizedProductDetails } from './getNormalizedProductDetails.js';
-import { removeConfidentialServiceHashes } from '@unchainedshop/core-users';
-
-export async function getNormalizedOrderDetails(
-  { orderId, orderNumber }: { orderId?: string; orderNumber?: string },
-  context: Context,
-) {
-  const { modules, loaders } = context;
-  const order = await modules.orders.findOrder({ orderId, orderNumber });
-  if (!order) return null;
-  const positions = await modules.orders.positions.findOrderPositions({
-    orderId: order._id,
-  });
-  const payment = await modules.orders.payments.findOrderPayment({
-    orderPaymentId: order?.paymentId as string,
-  });
-  const delivery = await modules.orders.deliveries.findDelivery({
-    orderDeliveryId: order?.deliveryId as string,
-  });
-  const [
-    items,
-    user,
-    enrollments,
-    currency,
-    country,
-    supportedPaymentProviders,
-    supportedDeliveryProviders,
-    discounts,
-  ] = await Promise.all([
-    Promise.all(
-      positions.map(async ({ productId, ...position }) => ({
-        ...(await getNormalizedProductDetails(productId, context)),
-        ...position,
-      })),
-    ),
-    loaders.userLoader.load({ userId: order.userId }),
-    modules.enrollments.findEnrollment({
-      orderId: order._id,
-    }),
-    loaders.currencyLoader.load({ isoCode: order.currencyCode }),
-    loaders.countryLoader.load({ isoCode: order.countryCode }),
-    context.services.orders.supportedPaymentProviders({
-      order,
-    }),
-    context.services.orders.supportedDeliveryProviders({
-      order,
-    }),
-    modules.orders.discounts.findOrderDiscounts({ orderId: order._id }),
-  ]);
-  let total: any = null;
-  const pricing = OrderPricingSheet({
-    calculation: order.calculation,
-    currencyCode: order.currencyCode,
-  });
-
-  if (pricing.isValid()) {
-    total = pricing.total();
-  }
-
-  return {
-    ...order,
-    total,
-    discounts,
-    enrollments,
-    currency,
-    supportedDeliveryProviders,
-    supportedPaymentProviders,
-    country,
-    user: removeConfidentialServiceHashes(user),
-    status: order?.status ?? 'OPEN',
-    items,
-    payment,
-    delivery,
-  };
-}

package/src/mcp/utils/getNormalizedProductDetails.ts

@@ -1,85 +0,0 @@
-import { ProductTypes } from '@unchainedshop/core-products';
-import { Context } from '../../context.js';
-import normalizeMediaUrl from './normalizeMediaUrl.js';
-import { createLogger } from '@unchainedshop/logger';
-import normalizeProxyAssignments from './normalizeProxyAssignments.js';
-
-const logger = createLogger('unchained:api:mcp');
-export async function getNormalizedProductDetails(productId: string, context: Context) {
-  const { modules, locale, loaders } = context;
-  const product = await modules.products.findProduct({ productId });
-
-  if (!product) return null;
-
-  const texts = await loaders.productTextLoader.load({
-    productId,
-    locale,
-  });
-  let variations: any = [];
-  let bundleItems: any = [];
-  let assignments: any = [];
-  const reviews = await modules.products.reviews.findProductReviews({
-    productId,
-  });
-
-  if (product.type === ProductTypes.ConfigurableProduct) {
-    variations = await context.modules.products.variations.findProductVariations({
-      productId: product?._id,
-    });
-    assignments = await Promise.all(
-      (product?.proxy?.assignments || [])?.map(async (assignment) =>
-        normalizeProxyAssignments(assignment, context),
-      ),
-    );
-  }
-
-  if (product.type === ProductTypes.BundleProduct) {
-    bundleItems = await Promise.all(
-      (product.bundleItems || []).map(async (item) => {
-        const bundleItemProduct = await loaders.productLoader.load({
-          productId: item.productId,
-        });
-        const productMedias = await modules.products.media.findProductMedias({
-          productId: item.productId,
-        });
-        const media = await normalizeMediaUrl(productMedias, context);
-        const texts = await loaders.productTextLoader.load({
-          productId: item.productId,
-          locale,
-        });
-        return {
-          product: {
-            ...bundleItemProduct,
-            media,
-            texts,
-          },
-          ...item,
-        };
-      }),
-    );
-  }
-
-  // Get pricing information
-  let pricing: any = null;
-  try {
-    pricing = await context.modules.products.prices.price(product, {
-      countryCode: context.countryCode,
-    });
-  } catch {
-    // Pricing might not be available for all products
-    logger.warn('Pricing not available for product:', product._id);
-  }
-
-  const productMedias = await modules.products.media.findProductMedias({ productId });
-  const media = await normalizeMediaUrl(productMedias, context);
-  return {
-    ...product,
-    texts,
-    media,
-    assignments,
-    variations,
-    bundleItems,
-    pricing,
-    reviews,
-  };
-}

package/src/mcp/utils/getNormalizedQuotationDetails.ts

@@ -1,38 +0,0 @@
-import { removeConfidentialServiceHashes } from '@unchainedshop/core-users';
-import { Context } from '../../context.js';
-import normalizeMediaUrl from './normalizeMediaUrl.js';
-
-export async function getNormalizedQuotationDetails(quotationId: string, context: Context) {
-  const { modules, loaders, locale } = context;
-
-  const quotation = await modules.quotations.findQuotation({ quotationId });
-
-  if (!quotation) return null;
-  const [user, product, productText, country, currency] = await Promise.all([
-    loaders.userLoader.load({ userId: quotation.userId }),
-    loaders.productLoader.load({ productId: quotation.productId }),
-    loaders.productTextLoader.load({
-      productId: quotation.productId,
-      locale,
-    }),
-    quotation.countryCode ? loaders.countryLoader.load({ isoCode: quotation.countryCode }) : null,
-    quotation.currencyCode ? loaders.currencyLoader.load({ isoCode: quotation.currencyCode }) : null,
-  ]);
-
-  return {
-    ...quotation,
-    status: modules.quotations.normalizedStatus(quotation),
-    user: {
-      ...removeConfidentialServiceHashes(user),
-      avatar: user?.avatarId ? await normalizeMediaUrl([{ mediaId: user?.avatarId }], context) : null,
-    },
-    product: product
-      ? {
-          ...product,
-          texts: productText,
-        }
-      : null,
-    country,
-    currency,
-  };
-}

package/src/mcp/utils/getNormalizedUserDetails.ts

@@ -1,86 +0,0 @@
-import { removeConfidentialServiceHashes, User } from '@unchainedshop/core-users';
-import { Context } from '../../context.js';
-import normalizeMediaUrl from './normalizeMediaUrl.js';
-
-const getPrimaryEmail = (user: User) => {
-  return (user.emails || []).toSorted(
-    (left, right) => Number(right.verified) - Number(left.verified),
-  )?.[0];
-};
-
-export async function getNormalizedUserDetails(userId: string, context: Context) {
-  const { modules, loaders } = context;
-  const user = await modules.users.findUserById(userId);
-  if (!user) return null;
-
-  const avatar = await loaders.fileLoader.load({
-    fileId: user.avatarId!,
-  });
-  const normalizedAvatar = await normalizeMediaUrl([{ mediaId: avatar?._id } as any], context);
-
-  const primaryEmail = getPrimaryEmail(user);
-  const { profile } = user;
-  let name = primaryEmail?.address || user._id;
-  if (profile && profile.displayName && profile.displayName !== '') name = profile.displayName;
-
-  const walletAddresses =
-    user.services?.web3?.flatMap((service) => {
-      return service.verified ? [service.address] : [];
-    }) || [];
-
-  const tokens = await context.modules.warehousing.findTokensForUser({
-    userId: user._id,
-    walletAddresses,
-  });
-
-  const userLocale = await modules.users.userLocale(user);
-
-  const country = await loaders.countryLoader.load({
-    isoCode: userLocale.region!,
-  });
-
-  const enrollments = await modules.enrollments.findEnrollments({
-    userId: user._id,
-  });
-
-  const language = await loaders.languageLoader.load({ isoCode: userLocale.language });
-  const orders = await modules.orders.findOrders({
-    userId: user._id,
-  });
-
-  const paymentCredentials = await modules.payment.paymentCredentials.findPaymentCredentials(
-    { userId: user._id },
-    {
-      sort: {
-        created: -1,
-      },
-    },
-  );
-
-  const quotations = await modules.quotations.findQuotations({
-    userId: user._id,
-  });
-
-  const reviews = await modules.products.reviews.findProductReviews({
-    authorId: user._id,
-  });
-  const safeUser = removeConfidentialServiceHashes(user);
-
-  return {
-    ...safeUser,
-    avatar: normalizedAvatar,
-    primaryEmail,
-    name,
-    isGuest: !!safeUser?.guest,
-    tokens,
-    country,
-    enrollments,
-    language,
-    orders,
-    paymentCredentials,
-    quotations,
-    webAuthnCredentials: user?.services?.webAuthn || [],
-    web3Addresses: user?.services?.web3 || [],
-    reviews,
-  };
-}