@unchainedshop/core-products 4.8.29 → 5.0.0-alpha.10

package/README.md

@@ -13,121 +13,26 @@ npm install @unchainedshop/core-products
 
 ## Usage
 
-```typescript
-import { configureProductsModule, ProductType } from '@unchainedshop/core-products';
+The platform initializes this module as `platform.unchainedAPI.modules.products`.
 
-const productsModule = await configureProductsModule({ db });
+```typescript
+import { ProductType } from '@unchainedshop/core-products';
 
-// Create a product
-const productId = await productsModule.create({
-  type: ProductType.SimpleProduct,
-  slugs: ['my-product'],
+const { products } = platform.unchainedAPI.modules;
+const product = await products.create({
+  type: ProductType.SIMPLE_PRODUCT,
+  tags: ['featured'],
 });
-
-// Find products
-const products = await productsModule.findProducts({
+await products.publish(product);
+const publishedProducts = await products.findProducts({
   tags: ['featured'],
   includeDrafts: false,
 });
-
-// Publish a product
-await productsModule.publish(productId);
 ```
 
-## API Overview
-
-### Module Configuration
-
-| Export | Description |
-|--------|-------------|
-| `configureProductsModule` | Configure and return the products module |
-
-### Queries
-
-| Method | Description |
-|--------|-------------|
-| `findProduct` | Find product by ID or slug |
-| `findProducts` | Find products with filtering and pagination |
-| `count` | Count products matching query |
-| `productExists` | Check if product exists |
-
-### Mutations
-
-| Method | Description |
-|--------|-------------|
-| `create` | Create a new product |
-| `update` | Update product data |
-| `delete` | Soft delete a product |
-| `publish` | Publish a draft product |
-| `unpublish` | Unpublish a product |
-| `addAssignment` | Add product proxy assignment |
-| `removeAssignment` | Remove product assignment |
-
-### Submodules
-
-#### Media (`products.media`)
-| Method | Description |
-|--------|-------------|
-| `findProductMedia` | Find media for a product |
-| `createMedia` | Add media to product |
-| `updateMedia` | Update media metadata |
-| `deleteMedia` | Remove media from product |
-| `reorderMedia` | Reorder product media |
-
-#### Prices (`products.prices`)
-| Method | Description |
-|--------|-------------|
-| `findProductPrices` | Get product prices |
-| `createPrice` | Add a price |
-| `updatePrice` | Update a price |
-| `deletePrice` | Remove a price |
-
-#### Reviews (`products.reviews`)
-| Method | Description |
-|--------|-------------|
-| `findProductReviews` | Find reviews for product |
-| `createReview` | Add a review |
-| `updateReview` | Update a review |
-| `deleteReview` | Remove a review |
-
-#### Texts (`products.texts`)
-| Method | Description |
-|--------|-------------|
-| `findProductTexts` | Find localized texts |
-| `updateTexts` | Update product texts |
-
-#### Variations (`products.variations`)
-| Method | Description |
-|--------|-------------|
-| `findProductVariations` | Find product variations |
-| `createVariation` | Add a variation |
-| `updateVariation` | Update a variation |
-| `deleteVariation` | Remove a variation |
-
-### Constants
-
-| Export | Description |
-|--------|-------------|
-| `ProductType` | Product types (SimpleProduct, ConfigurableProduct, BundleProduct, PlanProduct, TokenizedProduct) |
-| `ProductStatus` | Product status values (ACTIVE, DRAFT) |
-
-### Types
-
-| Export | Description |
-|--------|-------------|
-| `Product` | Product document type |
-| `ProductQuery` | Query parameters type |
-| `ProductsModule` | Module interface type |
-
-## Events
+`create` returns the product document, and `publish` accepts that document. The module exposes `media`, `prices`, `reviews`, `texts`, `variations`, `assignments`, and `bundleItems` submodules. Catalog prices are written as `commerce.pricing` entries with `minQuantity` tiers; computed pricing is coordinated by the core pricing services and plugins.
 
-| Event | Description |
-|-------|-------------|
-| `PRODUCT_CREATE` | Product created |
-| `PRODUCT_UPDATE` | Product updated |
-| `PRODUCT_REMOVE` | Product deleted |
-| `PRODUCT_PUBLISH` | Product published |
-| `PRODUCT_UNPUBLISH` | Product unpublished |
+See the [module guide](https://docs.unchained.shop/platform-configuration/modules/products), [pricing guide](https://docs.unchained.shop/concepts/pricing-system), [public exports](src/products-index.ts), and [module implementation](src/module/configureProductsModule.ts).
 
 ## License
 

package/lib/db/ProductsCollection.d.ts

@@ -50,7 +50,7 @@ export interface ProductPrice extends Price {
     isTaxable?: boolean;
     isNetPrice?: boolean;
     countryCode: string;
-    maxQuantity?: number;
+    minQuantity?: number;
 }
 export interface ProductPriceRange {
     minPrice: ProductPrice;
@@ -63,9 +63,9 @@ export interface ProductCommerce {
     pricing: ProductPrice[];
 }
 export interface ProductTokenization {
-    contractAddress: string;
+    contractAddress?: string;
     contractStandard: ProductContractStandard;
-    tokenId: string;
+    tokenId?: string;
     supply: number;
     ercMetadataProperties?: Record<string, any>;
 }

package/lib/mock/product.d.ts

@@ -8,21 +8,14 @@ declare const _default: {
     slugs: string[];
     updated: Date;
     commerce: {
-        pricing: ({
+        pricing: {
             amount: number;
-            maxQuantity: null;
+            minQuantity: number;
             isTaxable: boolean;
             isNetPrice: boolean;
             currencyCode: string;
             countryCode: string;
-        } | {
-            amount: number;
-            maxQuantity: number;
-            isTaxable: boolean;
-            isNetPrice: boolean;
-            currencyCode: string;
-            countryCode: string;
-        })[];
+        }[];
     };
     published: Date;
 };

package/lib/mock/product.js

@@ -11,7 +11,7 @@ export default {
         pricing: [
             {
                 amount: 1000,
-                maxQuantity: null,
+                minQuantity: 3,
                 isTaxable: false,
                 isNetPrice: false,
                 currencyCode: 'CHF',
@@ -19,7 +19,7 @@ export default {
             },
             {
                 amount: 20000,
-                maxQuantity: 2,
+                minQuantity: 0,
                 isTaxable: true,
                 isNetPrice: true,
                 currencyCode: 'ETB',
@@ -27,7 +27,7 @@ export default {
             },
             {
                 amount: 1,
-                maxQuantity: 1,
+                minQuantity: 0,
                 isTaxable: false,
                 isNetPrice: false,
                 currencyCode: 'ETH',
@@ -35,7 +35,7 @@ export default {
             },
             {
                 amount: 750,
-                maxQuantity: 2,
+                minQuantity: 0,
                 isTaxable: false,
                 isNetPrice: false,
                 currencyCode: 'CHF',

package/lib/module/configureProductMediaModule.js

@@ -54,7 +54,7 @@ export const configureProductMediaModule = async ({ db }) => {
             const mediaList = ProductMedias.find(selector, {
                 skip: offset,
                 limit,
-                sort: { sortKey: 1 },
+                sort: { sortKey: 1, _id: 1 },
                 ...options,
             });
             return mediaList.toArray();
@@ -64,7 +64,7 @@ export const configureProductMediaModule = async ({ db }) => {
                 const lastProductMedia = (await ProductMedias.findOne({
                     productId: doc.productId,
                 }, {
-                    sort: { sortKey: -1 },
+                    sort: { sortKey: -1, _id: -1 },
                 })) || { sortKey: 0 };
                 sortKey = lastProductMedia.sortKey + 1;
             }
@@ -123,7 +123,7 @@ export const configureProductMediaModule = async ({ db }) => {
             }));
             const productMedias = await ProductMedias.find({
                 _id: { $in: changedProductMediaIds },
-            }, { sort: { sortKey: 1 } }).toArray();
+            }, { sort: { sortKey: 1, _id: 1 } }).toArray();
             await emit('PRODUCT_REORDER_MEDIA', { productMedias });
             return productMedias;
         },

package/lib/module/configureProductPrices.d.ts

@@ -36,7 +36,7 @@ export declare const configureProductPricesModule: ({ proxyProducts, db, }: {
         countryCode: string;
     }) => Promise<{
         minQuantity: number;
-        maxQuantity: number;
+        maxQuantity: number | null;
         price: ProductPrice;
     }[]>;
     rates: {

package/lib/module/configureProductPrices.js

@@ -18,6 +18,18 @@ export const normalizeRate = (baseCurrency, quoteCurrency, rateRecord) => {
     rate = fromDecimals !== targetDecimals ? rate / 10 ** (fromDecimals - targetDecimals) : rate;
     return rate;
 };
+const normalizeProductPrice = (priceLevel) => {
+    if (priceLevel.amount === null)
+        return null;
+    return {
+        amount: priceLevel.amount,
+        currencyCode: priceLevel.currencyCode,
+        countryCode: priceLevel.countryCode,
+        minQuantity: priceLevel.minQuantity ?? 0,
+        isTaxable: !!priceLevel.isTaxable,
+        isNetPrice: !!priceLevel.isNetPrice,
+    };
+};
 export const configureProductPricesModule = ({ proxyProducts, db, }) => {
     const catalogPrice = async (product, { countryCode, currencyCode, quantity = 1, }) => {
         const pricing = getPriceLevels({
@@ -25,24 +37,18 @@ export const configureProductPricesModule = ({ proxyProducts, db, }) => {
             currencyCode,
             countryCode,
         });
-        const foundPrice = pricing.find((level) => !level.maxQuantity || level.maxQuantity >= quantity);
+        const foundPrice = pricing.filter((level) => (level.minQuantity ?? 0) <= quantity).pop();
         if (!foundPrice)
             return null;
-        const normalizedPrice = {
-            isTaxable: false,
-            isNetPrice: false,
-            ...foundPrice,
-        };
-        if (normalizedPrice.amount !== null) {
-            return normalizedPrice;
-        }
-        return null;
+        return normalizeProductPrice(foundPrice);
     };
     return {
         price: catalogPrice,
         priceRange: getPriceRange,
         async catalogPrices(product) {
-            return (product.commerce && product.commerce.pricing) || [];
+            return ((product.commerce && product.commerce.pricing) || [])
+                .map(normalizeProductPrice)
+                .filter((priceLevel) => Boolean(priceLevel));
         },
         catalogPriceRange: async (product, { quantity = 0, vectors = [], includeInactive = false, countryCode, currencyCode, }) => {
             const products = await proxyProducts(product, vectors, {
@@ -65,28 +71,24 @@ export const configureProductPricesModule = ({ proxyProducts, db, }) => {
             };
         },
         catalogPricesLeveled: async (product, { currencyCode, countryCode }) => {
-            let previousMax;
-            const filteredAndSortedPriceLevels = getPriceLevels({
+            const sortedPriceLevels = getPriceLevels({
                 product,
                 currencyCode,
                 countryCode,
             });
-            return filteredAndSortedPriceLevels.map((priceLevel, i) => {
-                const max = priceLevel.maxQuantity || 0;
-                const min = previousMax ? previousMax + 1 : 0;
-                previousMax = priceLevel.maxQuantity;
+            return sortedPriceLevels.flatMap((priceLevel, i) => {
+                const nextLevel = sortedPriceLevels[i + 1];
+                const price = normalizeProductPrice({
+                    ...priceLevel,
+                    currencyCode,
+                    countryCode,
+                });
+                if (!price)
+                    return [];
                 return {
-                    minQuantity: min,
-                    maxQuantity: i === 0 && priceLevel.maxQuantity && priceLevel.maxQuantity > 0
-                        ? priceLevel.maxQuantity
-                        : max,
-                    price: {
-                        isTaxable: !!priceLevel.isTaxable,
-                        isNetPrice: !!priceLevel.isNetPrice,
-                        amount: priceLevel.amount,
-                        currencyCode,
-                        countryCode,
-                    },
+                    minQuantity: priceLevel.minQuantity ?? 0,
+                    maxQuantity: nextLevel?.minQuantity != null ? nextLevel.minQuantity - 1 : null,
+                    price,
                 };
             });
         },
@@ -106,7 +108,7 @@ export const configureProductPricesModule = ({ proxyProducts, db, }) => {
                     ],
                     timestamp: { $lte: referenceDate },
                     expiresAt: { $gte: referenceDate },
-                }, { sort: { timestamp: -1 } });
+                }, { sort: { timestamp: -1, _id: -1 } });
                 if (!mostRecentCurrencyRate)
                     return null;
                 const rate = normalizeRate(baseCurrency, quoteCurrency, mostRecentCurrencyRate);

package/lib/module/configureProductsModule.d.ts

@@ -1,6 +1,6 @@
 import { mongodb, type ModuleInput } from '@unchainedshop/mongodb';
 import { type SortOption, type Price } from '@unchainedshop/utils';
-import { type Product, type ProductAssignment, type ProductBundleItem, type ProductConfiguration, ProductStatus } from '../db/ProductsCollection.ts';
+import { type Product, type ProductAssignment, type ProductBundleItem, type ProductConfiguration, ProductStatus, ProductType } from '../db/ProductsCollection.ts';
 import { type ProductsSettingsOptions } from '../products-settings.ts';
 export interface ProductQuery {
     queryString?: string;
@@ -11,6 +11,7 @@ export interface ProductQuery {
     slugs?: string[];
     tags?: string[];
     skus?: string[];
+    type?: ProductType;
     bundleItemProductIds?: string[];
     proxyAssignmentProductIds?: string[];
 }
@@ -22,7 +23,7 @@ export interface ProductDiscount {
     discountKey: string;
     context?: any;
 }
-export declare const buildFindSelector: ({ slugs, tags, includeDrafts, includeDeleted, productIds, productSelector, queryString, skus, bundleItemProductIds, proxyAssignmentProductIds, }: ProductQuery) => mongodb.Filter<Product>;
+export declare const buildFindSelector: ({ slugs, tags, includeDrafts, includeDeleted, productIds, productSelector, queryString, skus, type, bundleItemProductIds, proxyAssignmentProductIds, }: ProductQuery) => mongodb.Filter<Product>;
 export declare const configureProductsModule: (moduleInput: ModuleInput<ProductsSettingsOptions>) => Promise<{
     findProduct: (params: {
         productId: string;
@@ -80,7 +81,7 @@ export declare const configureProductsModule: (moduleInput: ModuleInput<Products
             countryCode: string;
         }) => Promise<{
             minQuantity: number;
-            maxQuantity: number;
+            maxQuantity: number | null;
             price: import("../db/ProductsCollection.ts").ProductPrice;
         }[]>;
         rates: {
@@ -119,6 +120,21 @@ export declare const configureProductsModule: (moduleInput: ModuleInput<Products
     }) => Promise<number>;
     publish: (product: Product) => Promise<boolean>;
     unpublish: (product: Product) => Promise<boolean>;
+    bulkPublish: (productIds: string[]) => Promise<{
+        successIds: string[];
+        failedIds: string[];
+    }>;
+    bulkUnpublish: (productIds: string[]) => Promise<{
+        successIds: string[];
+        failedIds: string[];
+    }>;
+    bulkUpdateTags: (productIds: string[], { add, remove }: {
+        add?: string[];
+        remove?: string[];
+    }) => Promise<{
+        successIds: string[];
+        failedIds: string[];
+    }>;
     assignments: {
         addProxyAssignment: ({ productId, proxyId, vectors, }: {
             productId: string;

package/lib/module/configureProductsModule.js

@@ -1,6 +1,6 @@
 import { emit, registerEvents } from '@unchainedshop/events';
 import { findPreservingIds, generateDbFilterById, buildSortOptions, mongodb, generateDbObjectId, } from '@unchainedshop/mongodb';
-import { SortDirection } from '@unchainedshop/utils';
+import { executeBulkOperation, SortDirection } from '@unchainedshop/utils';
 import { ProductsCollection, ProductStatus, ProductType, } from "../db/ProductsCollection.js";
 import { configureProductMediaModule } from "./configureProductMediaModule.js";
 import { configureProductPricesModule } from "./configureProductPrices.js";
@@ -8,6 +8,7 @@ import { configureProductReviewsModule } from "./configureProductReviewsModule.j
 import { configureProductTextsModule } from "./configureProductTextsModule.js";
 import { configureProductVariationsModule } from "./configureProductVariationsModule.js";
 import { productsSettings } from "../products-settings.js";
+import migrateCommercePricingToMinQuantity from "../migrations/20260611120000-pricing-maxquantity-to-minquantity.js";
 const PRODUCT_EVENTS = [
     'PRODUCT_CREATE',
     'PRODUCT_REMOVE',
@@ -24,11 +25,14 @@ const InternalProductStatus = {
     DRAFT: null,
 };
 const isDraftStatus = (status) => status === ProductStatus.DRAFT || status === InternalProductStatus.DRAFT;
-export const buildFindSelector = ({ slugs, tags, includeDrafts = false, includeDeleted = false, productIds, productSelector, queryString, skus, bundleItemProductIds, proxyAssignmentProductIds, }) => {
+export const buildFindSelector = ({ slugs, tags, includeDrafts = false, includeDeleted = false, productIds, productSelector, queryString, skus, type, bundleItemProductIds, proxyAssignmentProductIds, }) => {
     const selector = productSelector ? { ...productSelector } : {};
     if (productIds && !selector._id) {
         selector._id = { $in: productIds };
     }
+    if (type && !selector.type) {
+        selector.type = type;
+    }
     if (slugs && !selector.slugs) {
         selector.slugs = { $in: slugs };
     }
@@ -70,10 +74,11 @@ export const buildFindSelector = ({ slugs, tags, includeDrafts = false, includeD
     return selector;
 };
 export const configureProductsModule = async (moduleInput) => {
-    const { db, options: productsOptions = {} } = moduleInput;
+    const { db, migrationRepository, options: productsOptions = {} } = moduleInput;
     registerEvents(PRODUCT_EVENTS);
     await productsSettings.configureSettings(productsOptions);
     const { Products, ProductTexts } = await ProductsCollection(db);
+    migrateCommercePricingToMinQuantity(migrationRepository);
     const productTexts = configureProductTextsModule({
         Products,
         ProductTexts,
@@ -124,6 +129,16 @@ export const configureProductsModule = async (moduleInput) => {
         }
         return false;
     };
+    const updateProduct = async (productId, doc) => {
+        const product = await Products.findOneAndUpdate(generateDbFilterById(productId), {
+            $set: {
+                updated: new Date(),
+                ...doc,
+            },
+        }, { returnDocument: 'after' });
+        await emit('PRODUCT_UPDATE', { productId, ...doc, product });
+        return productId;
+    };
     const proxyProducts = async (product, vectors = [], { includeInactive = false } = {}) => {
         const { proxy } = product;
         let filtered = [...(proxy?.assignments || [])];
@@ -147,7 +162,7 @@ export const configureProductsModule = async (moduleInput) => {
     return {
         findProduct: async (params) => {
             if ('sku' in params) {
-                return Products.findOne({ 'warehousing.sku': params.sku }, { sort: { sequence: 1 } });
+                return Products.findOne({ 'warehousing.sku': params.sku }, { sort: { sequence: 1, _id: 1 } });
             }
             if ('slug' in params && params.slug != null) {
                 return Products.findOne({ slugs: params.slug }, {});
@@ -258,17 +273,7 @@ export const configureProductsModule = async (moduleInput) => {
             await emit('PRODUCT_CREATE', { product });
             return product;
         },
-        update: async (productId, doc) => {
-            const updateDoc = doc;
-            const product = await Products.findOneAndUpdate(generateDbFilterById(productId), {
-                $set: {
-                    updated: new Date(),
-                    ...updateDoc,
-                },
-            }, { returnDocument: 'after' });
-            await emit('PRODUCT_UPDATE', { productId, ...updateDoc, product });
-            return productId;
-        },
+        update: updateProduct,
         firstActiveProductProxy: async (productId) => {
             return Products.findOne({ 'proxy.assignments.productId': productId });
         },
@@ -290,6 +295,31 @@ export const configureProductsModule = async (moduleInput) => {
         deleteProductPermanently,
         publish: publishProduct,
         unpublish: unpublishProduct,
+        bulkPublish: async (productIds) => executeBulkOperation(productIds, async (productId) => {
+            const product = await Products.findOne(generateDbFilterById(productId), {});
+            if (!product || !(await publishProduct(product)))
+                throw new Error('publish-failed');
+        }),
+        bulkUnpublish: async (productIds) => executeBulkOperation(productIds, async (productId) => {
+            const product = await Products.findOne(generateDbFilterById(productId), {});
+            if (!product || !(await unpublishProduct(product)))
+                throw new Error('unpublish-failed');
+        }),
+        bulkUpdateTags: async (productIds, { add = [], remove = [] }) => {
+            const tagsToRemove = new Set(remove);
+            return executeBulkOperation(productIds, async (productId) => {
+                const product = await Products.findOne(generateDbFilterById(productId), {});
+                if (!product || (product.status !== ProductStatus.ACTIVE && !isDraftStatus(product.status))) {
+                    throw new Error('not-found');
+                }
+                const tags = (product.tags || []).filter((tag) => !tagsToRemove.has(tag));
+                for (const tag of add) {
+                    if (!tags.includes(tag))
+                        tags.push(tag);
+                }
+                await updateProduct(productId, { tags });
+            });
+        },
         assignments: {
             addProxyAssignment: async ({ productId, proxyId, vectors, }) => {
                 const assignment = {

package/lib/module/utils/getPriceLevels.js

@@ -1,17 +1,10 @@
 export const getPriceLevels = (params) => {
-    return (params.product?.commerce?.pricing || [])
-        .toSorted(({ maxQuantity: leftMaxQuantity = 0 }, { maxQuantity: rightMaxQuantity = 0 }) => {
-        if (leftMaxQuantity === rightMaxQuantity || (!leftMaxQuantity && !rightMaxQuantity))
-            return 0;
-        if (!leftMaxQuantity)
-            return 1;
-        if (!rightMaxQuantity)
-            return -1;
-        return leftMaxQuantity - rightMaxQuantity;
-    })
+    return ((params.product?.commerce?.pricing || [])
+        .toSorted((left, right) => (left.minQuantity ?? 0) - (right.minQuantity ?? 0))
         .filter((priceLevel) => {
         if (!params.currencyCode)
             return priceLevel.countryCode === params.countryCode;
-        return (priceLevel.currencyCode === params.currencyCode && priceLevel.countryCode === params.countryCode);
-    });
+        return (priceLevel.currencyCode === params.currencyCode &&
+            priceLevel.countryCode === params.countryCode);
+    }));
 };

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@unchainedshop/core-products",
   "description": "Product catalog management module for the Unchained Engine",
-  "version": "4.8.29",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib"
+  ],
   "main": "lib/products-index.js",
   "types": "lib/products-index.d.ts",
   "type": "module",
@@ -35,12 +38,13 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/events": "^4.8.27",
-    "@unchainedshop/mongodb": "^4.8.27",
-    "@unchainedshop/utils": "^4.8.27"
+    "@unchainedshop/events": "^5.0.0-alpha.10",
+    "@unchainedshop/logger": "^5.0.0-alpha.10",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.10",
+    "@unchainedshop/utils": "^5.0.0-alpha.10"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   }
 }