@azlib/cms 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -1397,9 +1397,9 @@ var CMSEngine = class {
 			async create(input, authorId = null) {
 				const filteredInput = await self.hooks.applyFilters("cms.before_create_input", input, { collection: slug });
 				const inputData = { ...filteredInput.data || {} };
-				if (filteredInput.title !== void 0) inputData.title = filteredInput.title;
-				if (filteredInput.slug !== void 0) inputData.slug = filteredInput.slug;
-				if (filteredInput.status !== void 0) inputData.status = filteredInput.status;
+				if (filteredInput.title !== void 0 && inputData.title === void 0) inputData.title = filteredInput.title;
+				if (filteredInput.slug !== void 0 && inputData.slug === void 0) inputData.slug = filteredInput.slug;
+				if (filteredInput.status !== void 0 && inputData.status === void 0) inputData.status = filteredInput.status;
 				const { data: normalizedData, errors } = validateAndNormalizeData(collConfig.fields, inputData);
 				if (Object.keys(errors).length > 0) throw new Error(`[CMSEngine] Validation failed for collection '${slug}': ${JSON.stringify(errors)}`);
 				const title = filteredInput.title ?? normalizedData.title ?? "";
@@ -1451,11 +1451,11 @@ var CMSEngine = class {
 					...existing.data,
 					...filteredInput.data || {}
 				};
-				if (filteredInput.title !== void 0) mergedData.title = filteredInput.title;
+				if (filteredInput.title !== void 0 && filteredInput.data?.title === void 0) mergedData.title = filteredInput.title;
 				else if (existing.title !== void 0 && mergedData.title === void 0) mergedData.title = existing.title;
-				if (filteredInput.slug !== void 0) mergedData.slug = filteredInput.slug;
+				if (filteredInput.slug !== void 0 && filteredInput.data?.slug === void 0) mergedData.slug = filteredInput.slug;
 				else if (existing.slug !== void 0 && mergedData.slug === void 0) mergedData.slug = existing.slug;
-				if (filteredInput.status !== void 0) mergedData.status = filteredInput.status;
+				if (filteredInput.status !== void 0 && filteredInput.data?.status === void 0) mergedData.status = filteredInput.status;
 				else if (existing.status !== void 0 && mergedData.status === void 0) mergedData.status = existing.status;
 				const { data: normalizedData, errors } = validateAndNormalizeData(collConfig.fields, mergedData);
 				if (Object.keys(errors).length > 0) throw new Error(`[CMSEngine] Validation failed updating '${slug}': ${JSON.stringify(errors)}`);
@@ -1842,6 +1842,12 @@ var CMSClient = class {
 			...options.headers || {}
 		};
 	}
+	/**
+	* Access underlying CMSEngine instance when in in-process mode.
+	*/
+	getEngine() {
+		return this.engine;
+	}
 	collection(slug) {
 		const self = this;
 		if (this.engine) {
@@ -1925,6 +1931,9 @@ var CMSClient = class {
 			return defaultValue;
 		}
 	} };
+	/**
+	* Perform an HTTP request against the CMS API (available in remote mode).
+	*/
 	async request(endpoint, init) {
 		if (!this.baseUrl) throw new Error(`[CMSClient] baseUrl must be provided when connecting to a remote CMS API.`);
 		const url = `${this.baseUrl}${endpoint}`;
@@ -1947,12 +1956,1293 @@ function createCmsClient(options) {
 	return new CMSClient(options);
 }
 //#endregion
+//#region src/plugins/ecommerce/schemas.ts
+/**
+* Creates the collection configuration for Products.
+*/
+function createProductCollection(options = {}) {
+	const slug = options.productCollectionSlug ?? "products";
+	const catSlug = options.categoriesTaxonomySlug ?? "product_categories";
+	const tagSlug = options.tagsTaxonomySlug ?? "product_tags";
+	const brandSlug = options.brandsTaxonomySlug ?? "product_brands";
+	const defaultCurrency = options.defaultCurrency ?? "USD";
+	return collection({
+		slug,
+		label: "Products",
+		singularLabel: "Product",
+		description: "Catalog products with pricing, inventory, images, and variants",
+		timestamps: true,
+		revisions: true,
+		draftable: true,
+		taxonomies: [
+			catSlug,
+			tagSlug,
+			brandSlug
+		],
+		defaultSort: {
+			field: "createdAt",
+			direction: "desc"
+		},
+		fields: [
+			fields.text({
+				name: "title",
+				label: "Product Title",
+				required: true
+			}),
+			fields.slug({
+				from: "title",
+				unique: true
+			}),
+			fields.text({
+				name: "sku",
+				label: "SKU",
+				description: "Stock Keeping Unit identifier"
+			}),
+			fields.number({
+				name: "price",
+				label: "Price",
+				required: true,
+				min: 0
+			}),
+			fields.number({
+				name: "compareAtPrice",
+				label: "Compare At Price",
+				description: "Original retail price for showing strike-through discounts",
+				min: 0
+			}),
+			fields.number({
+				name: "costPrice",
+				label: "Cost Price",
+				description: "Wholesale or production cost for margin tracking",
+				min: 0
+			}),
+			fields.text({
+				name: "currency",
+				label: "Currency",
+				defaultValue: defaultCurrency
+			}),
+			fields.number({
+				name: "stock",
+				label: "Inventory Quantity",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.boolean({
+				name: "trackInventory",
+				label: "Track Inventory",
+				defaultValue: options.inventoryManagement ?? true
+			}),
+			fields.select({
+				name: "status",
+				label: "Status",
+				options: [
+					"draft",
+					"published",
+					"out_of_stock",
+					"archived"
+				],
+				defaultValue: "draft"
+			}),
+			fields.richText({
+				name: "description",
+				label: "Full Description"
+			}),
+			fields.text({
+				name: "shortDescription",
+				label: "Short Description"
+			}),
+			fields.image({
+				name: "featuredImage",
+				label: "Featured Image"
+			}),
+			fields.json({
+				name: "gallery",
+				label: "Image Gallery",
+				defaultValue: []
+			}),
+			fields.json({
+				name: "variants",
+				label: "Product Variants",
+				defaultValue: []
+			}),
+			fields.json({
+				name: "attributes",
+				label: "Specifications / Attributes",
+				defaultValue: {}
+			}),
+			fields.number({
+				name: "weight",
+				label: "Weight",
+				min: 0
+			})
+		]
+	});
+}
+/**
+* Creates the collection configuration for Discounts / Coupons.
+*/
+function createDiscountCollection(options = {}) {
+	return collection({
+		slug: options.discountCollectionSlug ?? "discounts",
+		label: "Discounts",
+		singularLabel: "Discount",
+		description: "Promotional discount codes and coupons",
+		timestamps: true,
+		revisions: true,
+		draftable: false,
+		defaultSort: {
+			field: "createdAt",
+			direction: "desc"
+		},
+		fields: [
+			fields.text({
+				name: "title",
+				label: "Discount Name",
+				required: true
+			}),
+			fields.text({
+				name: "code",
+				label: "Coupon Code",
+				required: true,
+				unique: true
+			}),
+			fields.select({
+				name: "discountType",
+				label: "Discount Type",
+				options: [
+					"percentage",
+					"fixed_amount",
+					"free_shipping"
+				],
+				defaultValue: "percentage"
+			}),
+			fields.number({
+				name: "value",
+				label: "Discount Value",
+				required: true,
+				min: 0
+			}),
+			fields.number({
+				name: "minOrderAmount",
+				label: "Minimum Order Amount",
+				min: 0
+			}),
+			fields.number({
+				name: "maxDiscountAmount",
+				label: "Maximum Discount Cap",
+				min: 0
+			}),
+			fields.number({
+				name: "maxUses",
+				label: "Maximum Uses",
+				min: 1
+			}),
+			fields.number({
+				name: "usedCount",
+				label: "Times Used",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.date({
+				name: "startDate",
+				label: "Start Date"
+			}),
+			fields.date({
+				name: "endDate",
+				label: "Expiration Date"
+			}),
+			fields.select({
+				name: "status",
+				label: "Status",
+				options: [
+					"active",
+					"disabled",
+					"expired"
+				],
+				defaultValue: "active"
+			}),
+			fields.json({
+				name: "appliesToProductIds",
+				label: "Specific Product IDs",
+				defaultValue: []
+			}),
+			fields.json({
+				name: "appliesToCategoryIds",
+				label: "Specific Category Term IDs",
+				defaultValue: []
+			})
+		]
+	});
+}
+/**
+* Creates the collection configuration for Orders.
+*/
+function createOrderCollection(options = {}) {
+	const slug = options.orderCollectionSlug ?? "orders";
+	const defaultCurrency = options.defaultCurrency ?? "USD";
+	return collection({
+		slug,
+		label: "Orders",
+		singularLabel: "Order",
+		description: "Customer orders, status lifecycle, and line items",
+		timestamps: true,
+		revisions: true,
+		draftable: false,
+		defaultSort: {
+			field: "createdAt",
+			direction: "desc"
+		},
+		fields: [
+			fields.text({
+				name: "orderNumber",
+				label: "Order Number",
+				required: true,
+				unique: true
+			}),
+			fields.text({
+				name: "customerEmail",
+				label: "Customer Email",
+				required: true
+			}),
+			fields.text({
+				name: "customerName",
+				label: "Customer Name"
+			}),
+			fields.select({
+				name: "status",
+				label: "Status",
+				options: [
+					"pending",
+					"paid",
+					"processing",
+					"shipped",
+					"delivered",
+					"cancelled",
+					"refunded"
+				],
+				defaultValue: "pending"
+			}),
+			fields.text({
+				name: "currency",
+				label: "Currency",
+				defaultValue: defaultCurrency
+			}),
+			fields.json({
+				name: "items",
+				label: "Line Items",
+				defaultValue: []
+			}),
+			fields.number({
+				name: "subtotal",
+				label: "Subtotal",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.number({
+				name: "discountTotal",
+				label: "Discount Total",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.text({
+				name: "discountCode",
+				label: "Discount Code"
+			}),
+			fields.number({
+				name: "shippingTotal",
+				label: "Shipping Total",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.number({
+				name: "taxTotal",
+				label: "Tax Total",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.number({
+				name: "total",
+				label: "Grand Total",
+				defaultValue: 0,
+				min: 0
+			}),
+			fields.json({
+				name: "shippingAddress",
+				label: "Shipping Address"
+			}),
+			fields.json({
+				name: "billingAddress",
+				label: "Billing Address"
+			}),
+			fields.text({
+				name: "paymentMethod",
+				label: "Payment Method"
+			}),
+			fields.text({
+				name: "notes",
+				label: "Notes"
+			})
+		]
+	});
+}
+/**
+* Creates the standard e-commerce taxonomies: product categories, tags, and brands.
+*/
+function createEcommerceTaxonomies(options = {}) {
+	const productSlug = options.productCollectionSlug ?? "products";
+	const catSlug = options.categoriesTaxonomySlug ?? "product_categories";
+	const tagSlug = options.tagsTaxonomySlug ?? "product_tags";
+	const brandSlug = options.brandsTaxonomySlug ?? "product_brands";
+	return [
+		{
+			slug: catSlug,
+			label: "Product Categories",
+			singularLabel: "Product Category",
+			hierarchical: true,
+			postTypes: [productSlug],
+			description: "Hierarchical categories and catalog collections for organizing products"
+		},
+		{
+			slug: tagSlug,
+			label: "Product Tags",
+			singularLabel: "Product Tag",
+			hierarchical: false,
+			postTypes: [productSlug],
+			description: "Flat keyword tags for filtering products"
+		},
+		{
+			slug: brandSlug,
+			label: "Brands",
+			singularLabel: "Brand",
+			hierarchical: false,
+			postTypes: [productSlug],
+			description: "Product manufacturers or brand labels"
+		}
+	];
+}
+//#endregion
+//#region src/plugins/ecommerce/service.ts
+var EcommerceService = class {
+	engine;
+	options;
+	productSlug;
+	discountSlug;
+	orderSlug;
+	categoriesTaxonomy;
+	tagsTaxonomy;
+	brandsTaxonomy;
+	defaultCurrency;
+	inventoryManagement;
+	constructor(engine, options = {}) {
+		this.engine = engine;
+		this.options = options;
+		this.productSlug = options.productCollectionSlug ?? "products";
+		this.discountSlug = options.discountCollectionSlug ?? "discounts";
+		this.orderSlug = options.orderCollectionSlug ?? "orders";
+		this.categoriesTaxonomy = options.categoriesTaxonomySlug ?? "product_categories";
+		this.tagsTaxonomy = options.tagsTaxonomySlug ?? "product_tags";
+		this.brandsTaxonomy = options.brandsTaxonomySlug ?? "product_brands";
+		this.defaultCurrency = options.defaultCurrency ?? "USD";
+		this.inventoryManagement = options.inventoryManagement ?? true;
+	}
+	get productsCollection() {
+		return this.engine.collection(this.productSlug);
+	}
+	get discountsCollection() {
+		return this.engine.collection(this.discountSlug);
+	}
+	get ordersCollection() {
+		return this.engine.collection(this.orderSlug);
+	}
+	/**
+	* Create a new product in the catalog.
+	*/
+	async createProduct(input, authorId) {
+		const productData = {
+			price: input.price,
+			compareAtPrice: input.compareAtPrice,
+			costPrice: input.costPrice,
+			sku: input.sku,
+			currency: input.currency ?? this.defaultCurrency,
+			stock: input.stock ?? 0,
+			trackInventory: input.trackInventory ?? this.inventoryManagement,
+			status: input.status ?? "draft",
+			description: input.description,
+			shortDescription: input.shortDescription,
+			featuredImage: input.featuredImage,
+			gallery: input.gallery ?? [],
+			variants: input.variants ?? [],
+			attributes: input.attributes ?? {},
+			weight: input.weight
+		};
+		const product = await this.productsCollection.create({
+			title: input.title,
+			slug: input.slug,
+			status: input.status === "published" ? "published" : "draft",
+			data: productData
+		}, authorId);
+		if (input.categoryIds && input.categoryIds.length > 0) await this.engine.taxonomies.assignTerms(product.id, input.categoryIds);
+		if (input.tagIds && input.tagIds.length > 0) await this.engine.taxonomies.assignTerms(product.id, input.tagIds);
+		if (input.brandIds && input.brandIds.length > 0) await this.engine.taxonomies.assignTerms(product.id, input.brandIds);
+		await this.engine.hooks.doAction("ecommerce.product_created", product);
+		return product;
+	}
+	/**
+	* Update an existing product.
+	*/
+	async updateProduct(id, input, authorId) {
+		const existing = await this.getProduct(id);
+		if (!existing) return null;
+		const updatedData = {
+			...existing.data,
+			...input.price !== void 0 ? { price: input.price } : {},
+			...input.compareAtPrice !== void 0 ? { compareAtPrice: input.compareAtPrice } : {},
+			...input.costPrice !== void 0 ? { costPrice: input.costPrice } : {},
+			...input.sku !== void 0 ? { sku: input.sku } : {},
+			...input.currency !== void 0 ? { currency: input.currency } : {},
+			...input.stock !== void 0 ? { stock: input.stock } : {},
+			...input.trackInventory !== void 0 ? { trackInventory: input.trackInventory } : {},
+			...input.status !== void 0 ? { status: input.status } : {},
+			...input.description !== void 0 ? { description: input.description } : {},
+			...input.shortDescription !== void 0 ? { shortDescription: input.shortDescription } : {},
+			...input.featuredImage !== void 0 ? { featuredImage: input.featuredImage } : {},
+			...input.gallery !== void 0 ? { gallery: input.gallery } : {},
+			...input.variants !== void 0 ? { variants: input.variants } : {},
+			...input.attributes !== void 0 ? { attributes: input.attributes } : {},
+			...input.weight !== void 0 ? { weight: input.weight } : {}
+		};
+		const updated = await this.productsCollection.update(id, {
+			...input.title ? { title: input.title } : {},
+			...input.slug ? { slug: input.slug } : {},
+			...input.status === "published" ? { status: "published" } : input.status ? { status: "draft" } : {},
+			data: updatedData
+		}, authorId);
+		if (updated) {
+			if (input.categoryIds) await this.engine.taxonomies.assignTerms(id, input.categoryIds);
+			if (input.tagIds) await this.engine.taxonomies.assignTerms(id, input.tagIds);
+			if (input.brandIds) await this.engine.taxonomies.assignTerms(id, input.brandIds);
+			await this.engine.hooks.doAction("ecommerce.product_updated", updated);
+		}
+		return updated;
+	}
+	/**
+	* Get a product by ID.
+	*/
+	async getProduct(id) {
+		return this.productsCollection.findById(id);
+	}
+	/**
+	* Get a product by its URL slug.
+	*/
+	async getProductBySlug(slug) {
+		return this.productsCollection.findBySlug(slug);
+	}
+	/**
+	* Delete a product by ID.
+	*/
+	async deleteProduct(id) {
+		const deleted = await this.productsCollection.delete(id);
+		if (deleted) await this.engine.hooks.doAction("ecommerce.product_deleted", id);
+		return deleted;
+	}
+	/**
+	* List and filter catalog products.
+	*/
+	async listProducts(query = {}) {
+		let termIds;
+		if (query.categorySlug) {
+			const term = await this.engine.taxonomies.getTermBySlug(this.categoriesTaxonomy, query.categorySlug);
+			if (term) termIds = [term.id];
+			else return {
+				items: [],
+				total: 0,
+				limit: query.limit ?? 20,
+				offset: query.offset ?? 0,
+				hasMore: false
+			};
+		} else if (query.categoryId) termIds = [query.categoryId];
+		if (query.tagSlug) {
+			const term = await this.engine.taxonomies.getTermBySlug(this.tagsTaxonomy, query.tagSlug);
+			if (term) termIds = termIds ? [...termIds, term.id] : [term.id];
+		}
+		if (query.brandSlug) {
+			const term = await this.engine.taxonomies.getTermBySlug(this.brandsTaxonomy, query.brandSlug);
+			if (term) termIds = termIds ? [...termIds, term.id] : [term.id];
+		}
+		const contentStatus = query.status === "draft" ? "draft" : query.status === "published" ? "published" : void 0;
+		const result = await this.productsCollection.find({
+			search: query.search,
+			termIds,
+			status: contentStatus ?? "published",
+			limit: query.limit ?? 20,
+			offset: query.offset ?? 0,
+			orderBy: query.orderBy === "price" || query.orderBy === "stock" ? void 0 : query.orderBy,
+			orderDirection: query.orderDirection ?? "desc"
+		});
+		let items = result.items;
+		if (query.status) {
+			const statuses = Array.isArray(query.status) ? query.status : [query.status];
+			items = items.filter((p) => statuses.includes(p.data.status));
+		}
+		if (query.minPrice !== void 0) items = items.filter((p) => p.data.price >= query.minPrice);
+		if (query.maxPrice !== void 0) items = items.filter((p) => p.data.price <= query.maxPrice);
+		if (query.inStock) items = items.filter((p) => !p.data.trackInventory || p.data.stock > 0);
+		if (query.orderBy === "price") items.sort((a, b) => query.orderDirection === "asc" ? a.data.price - b.data.price : b.data.price - a.data.price);
+		else if (query.orderBy === "stock") items.sort((a, b) => query.orderDirection === "asc" ? a.data.stock - b.data.stock : b.data.stock - a.data.stock);
+		return {
+			items,
+			total: items.length,
+			limit: result.limit,
+			offset: result.offset,
+			hasMore: result.offset + items.length < result.total
+		};
+	}
+	/**
+	* Upload and link a product image to its gallery and featured slot.
+	*/
+	async uploadProductImage(productId, file, authorId) {
+		const product = await this.getProduct(productId);
+		if (!product) throw new Error(`[EcommerceService] Product '${productId}' not found.`);
+		const media = await this.engine.media.upload({
+			filename: file.filename,
+			mimeType: file.mimeType,
+			sizeBytes: file.sizeBytes,
+			url: file.url,
+			altText: file.altText ?? product.title,
+			caption: file.caption,
+			width: file.width,
+			height: file.height
+		}, authorId);
+		const gallery = [...product.data.gallery || []];
+		gallery.push({
+			id: media.id,
+			url: media.url,
+			altText: media.altText,
+			caption: media.caption,
+			width: media.width,
+			height: media.height
+		});
+		const isFeatured = file.isFeatured ?? !product.data.featuredImage;
+		const updated = await this.productsCollection.update(productId, { data: {
+			...product.data,
+			gallery,
+			...isFeatured ? { featuredImage: media.url } : {}
+		} });
+		await this.engine.hooks.doAction("ecommerce.product_image_added", {
+			product: updated ?? product,
+			media
+		});
+		return {
+			media,
+			product: updated ?? product
+		};
+	}
+	/**
+	* Adjust inventory stock for a product or variant.
+	*/
+	async adjustStock(productId, delta, variantId) {
+		const product = await this.getProduct(productId);
+		if (!product) return null;
+		if (!product.data.trackInventory) return product;
+		let newStock = product.data.stock;
+		const variants = [...product.data.variants || []];
+		if (variantId) {
+			const idx = variants.findIndex((v) => v.id === variantId);
+			if (idx !== -1) {
+				const currentVariantStock = variants[idx].stock ?? 0;
+				const updatedVariantStock = Math.max(0, currentVariantStock + delta);
+				variants[idx] = {
+					...variants[idx],
+					stock: updatedVariantStock
+				};
+			}
+		} else newStock = Math.max(0, product.data.stock + delta);
+		const newStatus = newStock === 0 && product.data.status === "published" ? "out_of_stock" : product.data.status === "out_of_stock" && newStock > 0 ? "published" : product.data.status;
+		const updated = await this.productsCollection.update(productId, { data: {
+			...product.data,
+			stock: newStock,
+			variants,
+			status: newStatus
+		} });
+		await this.engine.hooks.doAction("ecommerce.stock_changed", {
+			product: updated ?? product,
+			delta,
+			variantId,
+			oldStock: product.data.stock,
+			newStock
+		});
+		return updated;
+	}
+	/**
+	* Create a catalog category in the hierarchical category taxonomy.
+	*/
+	async createCategory(input) {
+		return this.engine.taxonomies.createTerm(this.categoriesTaxonomy, input);
+	}
+	/**
+	* Get all catalog categories.
+	*/
+	async getCategories(options) {
+		return this.engine.taxonomies.getTerms(this.categoriesTaxonomy, options);
+	}
+	/**
+	* Get full hierarchical catalog category tree.
+	*/
+	async getCategoryTree() {
+		return this.engine.taxonomies.getTermTree(this.categoriesTaxonomy);
+	}
+	/**
+	* Assign category IDs to a product.
+	*/
+	async assignProductCategory(productId, categoryIds) {
+		const ids = Array.isArray(categoryIds) ? categoryIds : [categoryIds];
+		await this.engine.taxonomies.assignTerms(productId, ids);
+	}
+	/**
+	* Get assigned categories for a product.
+	*/
+	async getProductCategories(productId) {
+		return this.engine.taxonomies.getContentTerms(productId, this.categoriesTaxonomy);
+	}
+	/**
+	* Create a promotional coupon / discount code.
+	*/
+	async createDiscount(input, authorId) {
+		const normalizedCode = input.code.trim().toUpperCase();
+		const discountData = {
+			code: normalizedCode,
+			discountType: input.discountType,
+			value: input.value,
+			minOrderAmount: input.minOrderAmount,
+			maxDiscountAmount: input.maxDiscountAmount,
+			maxUses: input.maxUses,
+			usedCount: 0,
+			startDate: input.startDate,
+			endDate: input.endDate,
+			status: input.status ?? "active",
+			appliesToProductIds: input.appliesToProductIds ?? [],
+			appliesToCategoryIds: input.appliesToCategoryIds ?? []
+		};
+		const discount = await this.discountsCollection.create({
+			title: input.title,
+			slug: normalizedCode.toLowerCase(),
+			status: "published",
+			data: discountData
+		}, authorId);
+		await this.engine.hooks.doAction("ecommerce.discount_created", discount);
+		return discount;
+	}
+	/**
+	* Find a discount code.
+	*/
+	async getDiscountByCode(code) {
+		const normalized = code.trim().toUpperCase();
+		return (await this.discountsCollection.find({ limit: 100 })).items.find((d) => d.data.code?.toUpperCase() === normalized) ?? null;
+	}
+	/**
+	* Validate a discount coupon against cart items and order subtotal.
+	*/
+	async validateDiscount(code, cartSubtotal, productIds = []) {
+		const normalized = code.trim().toUpperCase();
+		const discount = await this.getDiscountByCode(normalized);
+		if (!discount) return {
+			valid: false,
+			code: normalized,
+			discountAmount: 0,
+			message: `Discount code '${code}' not found.`
+		};
+		const { data } = discount;
+		if (data.status !== "active") return {
+			valid: false,
+			code: normalized,
+			discountAmount: 0,
+			message: "Discount code is currently inactive."
+		};
+		const now = Date.now();
+		if (data.startDate && new Date(data.startDate).getTime() > now) return {
+			valid: false,
+			code: normalized,
+			discountAmount: 0,
+			message: "Discount code is not yet active."
+		};
+		if (data.endDate && new Date(data.endDate).getTime() < now) return {
+			valid: false,
+			code: normalized,
+			discountAmount: 0,
+			message: "Discount code has expired."
+		};
+		if (data.maxUses !== void 0 && data.usedCount >= data.maxUses) return {
+			valid: false,
+			code: normalized,
+			discountAmount: 0,
+			message: "Discount code usage limit reached."
+		};
+		if (data.minOrderAmount !== void 0 && cartSubtotal < data.minOrderAmount) return {
+			valid: false,
+			code: normalized,
+			discountAmount: 0,
+			message: `Minimum order amount of ${data.minOrderAmount} required for this coupon.`
+		};
+		if (data.appliesToProductIds && data.appliesToProductIds.length > 0 && productIds.length > 0) {
+			if (!productIds.some((id) => data.appliesToProductIds?.includes(id))) return {
+				valid: false,
+				code: normalized,
+				discountAmount: 0,
+				message: "Coupon is not applicable to any products in your cart."
+			};
+		}
+		let discountAmount = 0;
+		if (data.discountType === "percentage") {
+			discountAmount = cartSubtotal * data.value / 100;
+			if (data.maxDiscountAmount) discountAmount = Math.min(discountAmount, data.maxDiscountAmount);
+		} else if (data.discountType === "fixed_amount") discountAmount = Math.min(data.value, cartSubtotal);
+		else if (data.discountType === "free_shipping") discountAmount = 0;
+		discountAmount = await this.engine.hooks.applyFilters("ecommerce.apply_discount", discountAmount, {
+			discount,
+			cartSubtotal
+		});
+		return {
+			valid: true,
+			code: normalized,
+			discountAmount: Math.round(discountAmount * 100) / 100,
+			discountType: data.discountType,
+			discount
+		};
+	}
+	/**
+	* Calculate cart subtotals, apply discounts, shipping, and taxes.
+	*/
+	async calculateCart(input) {
+		const lineItems = [];
+		let subtotal = 0;
+		const productIds = [];
+		for (const item of input.items) {
+			const product = await this.getProduct(item.productId);
+			if (!product) throw new Error(`[EcommerceService] Product '${item.productId}' not found.`);
+			productIds.push(product.id);
+			let price = product.data.price;
+			let sku = product.data.sku;
+			let title = product.title ?? "Product";
+			let availableStock = product.data.stock;
+			let image = product.data.featuredImage;
+			if (item.variantId && product.data.variants) {
+				const variant = product.data.variants.find((v) => v.id === item.variantId);
+				if (variant) {
+					price = variant.price ?? price;
+					sku = variant.sku ?? sku;
+					title = `${title} (${variant.title})`;
+					availableStock = variant.stock ?? availableStock;
+					image = variant.image ?? image;
+				}
+			}
+			if (this.inventoryManagement && product.data.trackInventory && availableStock < item.quantity) throw new Error(`[EcommerceService] Insufficient stock for '${title}'. Available: ${availableStock}, Requested: ${item.quantity}.`);
+			const itemSubtotal = Math.round(price * item.quantity * 100) / 100;
+			subtotal += itemSubtotal;
+			lineItems.push({
+				productId: product.id,
+				variantId: item.variantId,
+				title,
+				sku,
+				price,
+				quantity: item.quantity,
+				subtotal: itemSubtotal,
+				image
+			});
+		}
+		subtotal = Math.round(subtotal * 100) / 100;
+		let discountTotal = 0;
+		let discountType;
+		if (input.discountCode) {
+			const validation = await this.validateDiscount(input.discountCode, subtotal, productIds);
+			if (validation.valid) {
+				discountTotal = validation.discountAmount;
+				discountType = validation.discountType;
+			}
+		}
+		let shippingTotal = input.shippingCost ?? this.options.defaultShippingCost ?? 0;
+		if (discountType === "free_shipping") shippingTotal = 0;
+		const taxRate = input.taxRate ?? this.options.defaultTaxRate ?? 0;
+		const taxableAmount = Math.max(0, subtotal - discountTotal);
+		const taxTotal = Math.round(taxableAmount * taxRate * 100) / 100;
+		const total = Math.round((taxableAmount + shippingTotal + taxTotal) * 100) / 100;
+		const result = {
+			items: lineItems,
+			subtotal,
+			discountTotal,
+			discountCode: input.discountCode,
+			shippingTotal,
+			taxTotal,
+			total,
+			currency: this.defaultCurrency
+		};
+		return this.engine.hooks.applyFilters("ecommerce.calculate_totals", result, input);
+	}
+	/**
+	* Place a new order with cart validation, inventory deduction, and coupon counter updates.
+	*/
+	async createOrder(input, authorId) {
+		const calc = await this.calculateCart({
+			items: input.items,
+			discountCode: input.discountCode,
+			shippingCost: input.shippingCost,
+			taxRate: input.taxRate
+		});
+		const orderNumber = `ORD-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10).replace(/-/g, "")}-${Math.random().toString(36).substring(2, 6).toUpperCase()}`;
+		if (this.inventoryManagement) for (const item of input.items) await this.adjustStock(item.productId, -item.quantity, item.variantId);
+		if (input.discountCode) {
+			const discount = await this.getDiscountByCode(input.discountCode);
+			if (discount) await this.discountsCollection.update(discount.id, { data: {
+				...discount.data,
+				usedCount: (discount.data.usedCount || 0) + 1
+			} });
+		}
+		const orderData = {
+			orderNumber,
+			customerEmail: input.customerEmail,
+			customerName: input.customerName,
+			status: "pending",
+			currency: calc.currency,
+			items: calc.items,
+			subtotal: calc.subtotal,
+			discountTotal: calc.discountTotal,
+			discountCode: calc.discountCode,
+			shippingTotal: calc.shippingTotal,
+			taxTotal: calc.taxTotal,
+			total: calc.total,
+			shippingAddress: input.shippingAddress,
+			billingAddress: input.billingAddress,
+			paymentMethod: input.paymentMethod,
+			notes: input.notes
+		};
+		const order = await this.ordersCollection.create({
+			title: `Order #${orderNumber}`,
+			slug: orderNumber.toLowerCase(),
+			status: "published",
+			data: orderData
+		}, authorId);
+		await this.engine.hooks.doAction("ecommerce.order_created", order);
+		return order;
+	}
+	/**
+	* Get order by ID.
+	*/
+	async getOrder(id) {
+		return this.ordersCollection.findById(id);
+	}
+	/**
+	* Get order by order number.
+	*/
+	async getOrderByNumber(orderNumber) {
+		return (await this.ordersCollection.find({ limit: 100 })).items.find((o) => o.data.orderNumber?.toUpperCase() === orderNumber.toUpperCase()) ?? null;
+	}
+	/**
+	* Update the status of an order (e.g. pending -> paid -> shipped).
+	*/
+	async updateOrderStatus(id, status, note) {
+		const existing = await this.getOrder(id);
+		if (!existing) return null;
+		const oldStatus = existing.data.status;
+		const updated = await this.ordersCollection.update(id, { data: {
+			...existing.data,
+			status
+		} }, void 0, note);
+		if (updated) await this.engine.hooks.doAction("ecommerce.order_status_changed", {
+			order: updated,
+			oldStatus,
+			newStatus: status,
+			note
+		});
+		return updated;
+	}
+};
+//#endregion
+//#region src/plugins/ecommerce/routes.ts
+function json(data, status = 200) {
+	return new Response(JSON.stringify(data), {
+		status,
+		headers: {
+			"Content-Type": "application/json",
+			"Access-Control-Allow-Origin": "*"
+		}
+	});
+}
+function badRequest(message) {
+	return json({ error: message }, 400);
+}
+function notFound(message) {
+	return json({ error: message }, 404);
+}
+function registerEcommerceRoutes(ctx, service, options = {}) {
+	const prefix = (options.apiPrefix ?? "/api/ecommerce").replace(/\/+$/, "");
+	ctx.registerRoute("GET", `${prefix}/products`, async (_req, { url }) => {
+		try {
+			const categorySlug = url.searchParams.get("category") ?? void 0;
+			const categoryId = url.searchParams.get("categoryId") ?? void 0;
+			const tagSlug = url.searchParams.get("tag") ?? void 0;
+			const brandSlug = url.searchParams.get("brand") ?? void 0;
+			const search = url.searchParams.get("search") ?? void 0;
+			const statusParam = url.searchParams.get("status");
+			const inStock = url.searchParams.get("inStock") === "true";
+			const minPriceStr = url.searchParams.get("minPrice");
+			const maxPriceStr = url.searchParams.get("maxPrice");
+			const minPrice = minPriceStr ? parseFloat(minPriceStr) : void 0;
+			const maxPrice = maxPriceStr ? parseFloat(maxPriceStr) : void 0;
+			const orderBy = url.searchParams.get("orderBy");
+			const orderDirection = url.searchParams.get("orderDirection") ?? "desc";
+			const limitStr = url.searchParams.get("limit");
+			const offsetStr = url.searchParams.get("offset");
+			const limit = limitStr ? parseInt(limitStr, 10) : 20;
+			const offset = offsetStr ? parseInt(offsetStr, 10) : 0;
+			return json(await service.listProducts({
+				categorySlug,
+				categoryId,
+				tagSlug,
+				brandSlug,
+				search,
+				status: statusParam,
+				inStock,
+				minPrice,
+				maxPrice,
+				orderBy,
+				orderDirection,
+				limit,
+				offset
+			}));
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	ctx.registerRoute("GET", `${prefix}/products/:id`, async (_req, { params, url }) => {
+		const id = params.id;
+		const by = url.searchParams.get("by");
+		let product = null;
+		if (by === "slug") product = await service.getProductBySlug(id);
+		else {
+			product = await service.getProduct(id);
+			if (!product) product = await service.getProductBySlug(id);
+		}
+		if (!product) return notFound(`Product '${id}' not found`);
+		return json(product);
+	});
+	ctx.registerRoute("POST", `${prefix}/products`, async (req) => {
+		try {
+			const body = await req.json();
+			if (!body.title) return badRequest("Product 'title' is required.");
+			if (body.price === void 0 || body.price < 0) return badRequest("Valid product 'price' is required.");
+			return json(await service.createProduct(body), 201);
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	ctx.registerRoute("PUT", `${prefix}/products/:id`, async (req, { params }) => {
+		try {
+			const body = await req.json();
+			const updated = await service.updateProduct(params.id, body);
+			if (!updated) return notFound(`Product '${params.id}' not found.`);
+			return json(updated);
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	ctx.registerRoute("DELETE", `${prefix}/products/:id`, async (_req, { params }) => {
+		if (!await service.deleteProduct(params.id)) return notFound(`Product '${params.id}' not found.`);
+		return json({
+			success: true,
+			id: params.id
+		});
+	});
+	ctx.registerRoute("POST", `${prefix}/products/:id/images`, async (req, { params }) => {
+		try {
+			const body = await req.json();
+			if (!body.filename || !body.mimeType) return badRequest("'filename' and 'mimeType' are required.");
+			return json(await service.uploadProductImage(params.id, {
+				filename: body.filename,
+				mimeType: body.mimeType,
+				sizeBytes: body.sizeBytes ?? 0,
+				url: body.url,
+				altText: body.altText,
+				caption: body.caption,
+				width: body.width,
+				height: body.height,
+				isFeatured: body.isFeatured
+			}), 201);
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	ctx.registerRoute("GET", `${prefix}/categories`, async (_req, { url }) => {
+		try {
+			if (url.searchParams.get("tree") === "true") return json(await service.getCategoryTree());
+			const parentId = url.searchParams.get("parentId");
+			return json(await service.getCategories({ parentId: parentId === "null" ? null : parentId ?? void 0 }));
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	ctx.registerRoute("POST", `${prefix}/categories`, async (req) => {
+		try {
+			const body = await req.json();
+			if (!body.name) return badRequest("Category 'name' is required.");
+			return json(await service.createCategory(body), 201);
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	if (options.enableDiscounts !== false) {
+		ctx.registerRoute("POST", `${prefix}/discounts`, async (req) => {
+			try {
+				const body = await req.json();
+				if (!body.title || !body.code) return badRequest("'title' and 'code' are required.");
+				if (body.value === void 0 || body.value < 0) return badRequest("Valid discount 'value' is required.");
+				return json(await service.createDiscount(body), 201);
+			} catch (err) {
+				return badRequest(err instanceof Error ? err.message : String(err));
+			}
+		});
+		ctx.registerRoute("POST", `${prefix}/discounts/validate`, async (req) => {
+			try {
+				const body = await req.json();
+				if (!body.code) return badRequest("Discount 'code' is required.");
+				const subtotal = Number(body.subtotal ?? 0);
+				const productIds = Array.isArray(body.productIds) ? body.productIds : [];
+				return json(await service.validateDiscount(body.code, subtotal, productIds));
+			} catch (err) {
+				return badRequest(err instanceof Error ? err.message : String(err));
+			}
+		});
+	}
+	ctx.registerRoute("POST", `${prefix}/cart/calculate`, async (req) => {
+		try {
+			const body = await req.json();
+			if (!body.items || !Array.isArray(body.items) || body.items.length === 0) return badRequest("'items' array is required and must not be empty.");
+			return json(await service.calculateCart(body));
+		} catch (err) {
+			return badRequest(err instanceof Error ? err.message : String(err));
+		}
+	});
+	if (options.enableOrders !== false) {
+		ctx.registerRoute("POST", `${prefix}/orders`, async (req) => {
+			try {
+				const body = await req.json();
+				if (!body.customerEmail) return badRequest("'customerEmail' is required.");
+				if (!body.items || !Array.isArray(body.items) || body.items.length === 0) return badRequest("'items' array is required.");
+				return json(await service.createOrder(body), 201);
+			} catch (err) {
+				return badRequest(err instanceof Error ? err.message : String(err));
+			}
+		});
+		ctx.registerRoute("GET", `${prefix}/orders/:id`, async (_req, { params, url }) => {
+			const id = params.id;
+			const by = url.searchParams.get("by");
+			let order = null;
+			if (by === "number") order = await service.getOrderByNumber(id);
+			else {
+				order = await service.getOrder(id);
+				if (!order) order = await service.getOrderByNumber(id);
+			}
+			if (!order) return notFound(`Order '${id}' not found.`);
+			return json(order);
+		});
+		ctx.registerRoute("PATCH", `${prefix}/orders/:id/status`, async (req, { params }) => {
+			try {
+				const body = await req.json();
+				if (!body.status) return badRequest("New 'status' is required.");
+				const updated = await service.updateOrderStatus(params.id, body.status, body.note);
+				if (!updated) return notFound(`Order '${params.id}' not found.`);
+				return json(updated);
+			} catch (err) {
+				return badRequest(err instanceof Error ? err.message : String(err));
+			}
+		});
+	}
+}
+//#endregion
+//#region src/plugins/ecommerce/client.ts
+var EcommerceClient = class {
+	client;
+	options;
+	service;
+	prefix;
+	constructor(client, options = {}) {
+		this.client = client;
+		this.options = options;
+		this.prefix = (options.apiPrefix ?? "/api/ecommerce").replace(/\/+$/, "");
+		const engine = client.getEngine();
+		if (engine) this.service = new EcommerceService(engine, options);
+	}
+	products = {
+		find: async (query = {}) => {
+			if (this.service) return this.service.listProducts(query);
+			const params = new URLSearchParams();
+			if (query.categorySlug) params.set("category", query.categorySlug);
+			if (query.categoryId) params.set("categoryId", query.categoryId);
+			if (query.tagSlug) params.set("tag", query.tagSlug);
+			if (query.brandSlug) params.set("brand", query.brandSlug);
+			if (query.search) params.set("search", query.search);
+			if (query.inStock) params.set("inStock", "true");
+			if (query.minPrice !== void 0) params.set("minPrice", String(query.minPrice));
+			if (query.maxPrice !== void 0) params.set("maxPrice", String(query.maxPrice));
+			if (query.orderBy) params.set("orderBy", query.orderBy);
+			if (query.orderDirection) params.set("orderDirection", query.orderDirection);
+			if (query.limit !== void 0) params.set("limit", String(query.limit));
+			if (query.offset !== void 0) params.set("offset", String(query.offset));
+			const q = params.toString() ? `?${params.toString()}` : "";
+			return this.client.request(`${this.prefix}/products${q}`);
+		},
+		get: async (idOrSlug, by) => {
+			if (this.service) return by === "slug" ? this.service.getProductBySlug(idOrSlug) : this.service.getProduct(idOrSlug);
+			const query = by ? `?by=${by}` : "";
+			return this.client.request(`${this.prefix}/products/${encodeURIComponent(idOrSlug)}${query}`);
+		},
+		create: async (data) => {
+			if (this.service) return this.service.createProduct(data);
+			return this.client.request(`${this.prefix}/products`, {
+				method: "POST",
+				body: JSON.stringify(data)
+			});
+		},
+		update: async (id, data) => {
+			if (this.service) return this.service.updateProduct(id, data);
+			return this.client.request(`${this.prefix}/products/${encodeURIComponent(id)}`, {
+				method: "PUT",
+				body: JSON.stringify(data)
+			});
+		},
+		delete: async (id) => {
+			if (this.service) return this.service.deleteProduct(id);
+			const res = await this.client.request(`${this.prefix}/products/${encodeURIComponent(id)}`, { method: "DELETE" });
+			return Boolean(res?.success);
+		},
+		uploadImage: async (productId, file) => {
+			if (this.service) return this.service.uploadProductImage(productId, file);
+			return this.client.request(`${this.prefix}/products/${encodeURIComponent(productId)}/images`, {
+				method: "POST",
+				body: JSON.stringify(file)
+			});
+		}
+	};
+	categories = {
+		list: async (options) => {
+			if (this.service) return this.service.getCategories(options);
+			const q = options?.parentId !== void 0 ? `?parentId=${options.parentId}` : "";
+			return this.client.request(`${this.prefix}/categories${q}`);
+		},
+		tree: async () => {
+			if (this.service) return this.service.getCategoryTree();
+			return this.client.request(`${this.prefix}/categories?tree=true`);
+		},
+		create: async (input) => {
+			if (this.service) return this.service.createCategory(input);
+			return this.client.request(`${this.prefix}/categories`, {
+				method: "POST",
+				body: JSON.stringify(input)
+			});
+		}
+	};
+	discounts = {
+		validate: async (code, subtotal, productIds) => {
+			if (this.service) return this.service.validateDiscount(code, subtotal, productIds);
+			return this.client.request(`${this.prefix}/discounts/validate`, {
+				method: "POST",
+				body: JSON.stringify({
+					code,
+					subtotal,
+					productIds
+				})
+			});
+		},
+		create: async (input) => {
+			if (this.service) return this.service.createDiscount(input);
+			return this.client.request(`${this.prefix}/discounts`, {
+				method: "POST",
+				body: JSON.stringify(input)
+			});
+		}
+	};
+	cart = { calculate: async (input) => {
+		if (this.service) return this.service.calculateCart(input);
+		return this.client.request(`${this.prefix}/cart/calculate`, {
+			method: "POST",
+			body: JSON.stringify(input)
+		});
+	} };
+	orders = {
+		create: async (input) => {
+			if (this.service) return this.service.createOrder(input);
+			return this.client.request(`${this.prefix}/orders`, {
+				method: "POST",
+				body: JSON.stringify(input)
+			});
+		},
+		get: async (idOrNumber, by) => {
+			if (this.service) return by === "number" ? this.service.getOrderByNumber(idOrNumber) : this.service.getOrder(idOrNumber);
+			const q = by ? `?by=${by}` : "";
+			return this.client.request(`${this.prefix}/orders/${encodeURIComponent(idOrNumber)}${q}`);
+		},
+		updateStatus: async (id, status, note) => {
+			if (this.service) return this.service.updateOrderStatus(id, status, note);
+			return this.client.request(`${this.prefix}/orders/${encodeURIComponent(id)}/status`, {
+				method: "PATCH",
+				body: JSON.stringify({
+					status,
+					note
+				})
+			});
+		}
+	};
+};
+/**
+* Get or create an EcommerceClient adapter for a CMSClient.
+*/
+function getEcommerceClient(client, options) {
+	return new EcommerceClient(client, options);
+}
+//#endregion
+//#region src/plugins/ecommerce/index.ts
+/**
+* @azlib/cms - Built-in E-commerce Plugin
+*/
+/**
+* Built-in E-commerce plugin factory for @azlib/cms.
+* Equips the CMS engine with product catalogs, hierarchical categories,
+* image uploading, discount coupons, cart calculation, and order tracking.
+*/
+const ecommercePlugin = definePlugin((options) => {
+	const opts = options || {};
+	const collections = [createProductCollection(opts)];
+	if (opts.enableDiscounts !== false) collections.push(createDiscountCollection(opts));
+	if (opts.enableOrders !== false) collections.push(createOrderCollection(opts));
+	return {
+		name: "ecommerce",
+		version: "1.0.0",
+		description: "Built-in E-commerce shopping, products, catalogs, discounts, and orders plugin",
+		collections,
+		taxonomies: createEcommerceTaxonomies(opts),
+		setup(ctx) {
+			const service = new EcommerceService(ctx.engine, opts);
+			ctx.engine.__ecommerceService = service;
+			registerEcommerceRoutes(ctx, service, opts);
+		}
+	};
+});
+/**
+* Retrieve the active EcommerceService instance associated with a CMSEngine.
+*/
+function getEcommerceService(engine, options) {
+	if (engine.__ecommerceService) return engine.__ecommerceService;
+	const service = new EcommerceService(engine, options);
+	engine.__ecommerceService = service;
+	return service;
+}
+//#endregion
 exports.CMSClient = CMSClient;
 exports.CMSEngine = CMSEngine;
 exports.CMSRouter = CMSRouter;
 exports.ContentLifecycle = ContentLifecycle;
 exports.DEFAULT_COLLECTIONS = DEFAULT_COLLECTIONS;
 exports.DEFAULT_ROLE_CAPABILITIES = DEFAULT_ROLE_CAPABILITIES;
+exports.EcommerceClient = EcommerceClient;
+exports.EcommerceService = EcommerceService;
 exports.HooksManager = HooksManager;
 exports.MediaManager = MediaManager;
 exports.MemoryStorageAdapter = MemoryStorageAdapter;
@@ -1965,10 +3255,17 @@ exports.collection = collection;
 exports.createCMSEngine = createCMSEngine;
 exports.createCMSRouter = createCMSRouter;
 exports.createCmsClient = createCmsClient;
+exports.createDiscountCollection = createDiscountCollection;
+exports.createEcommerceTaxonomies = createEcommerceTaxonomies;
+exports.createOrderCollection = createOrderCollection;
+exports.createProductCollection = createProductCollection;
 exports.defaultHooks = defaultHooks;
 exports.defineConfig = defineConfig;
 exports.definePlugin = definePlugin;
+exports.ecommercePlugin = ecommercePlugin;
 exports.fields = fields;
+exports.getEcommerceClient = getEcommerceClient;
+exports.getEcommerceService = getEcommerceService;
 exports.normalizeConfig = normalizeConfig;
 exports.resolveUniqueSlug = resolveUniqueSlug;
 exports.slugify = slugify;