@azlib/cms 0.2.0 → 0.3.0

package/README.md

@@ -12,6 +12,7 @@ A framework-agnostic, modular Content Management System (CMS) runtime inspired b
 - 🗂️ **Hierarchical Taxonomies**: Nested category trees, flat tags, and custom taxonomy binding.
 - 🖼️ **Media & Asset Management**: MIME validation, file sanitization, metadata, and asset queries.
 - 🔒 **RBAC & Capability Matrix**: Built-in Administrator, Editor, Author, Contributor, and Subscriber roles with content ownership checks.
+- 🔌 **Extensible Plugin System**: Package and distribute reusable plugins (`definePlugin`) with schema extensions, custom API routes, lifecycle hooks, and filter pipelines.
 - 🌐 **Universal Web Standard Router**: `Request` -> `Response` HTTP router ready for Next.js App Router, Remix, Vite, Astro, Express, or Cloudflare Workers.
 - 🚀 **Type-Safe Headless Client SDK**: Query content in-process or over HTTP with zero boilerplate (`createCmsClient`).
 
@@ -109,6 +110,69 @@ export async function POST(request: Request) {
 
 ---
 
+## Plugin System
+
+Create modular, decoupled plugins that extend collections, inject custom fields, register custom Web Standard routes, and hook into lifecycle pipelines:
+
+```typescript
+import { definePlugin, fields } from "@azlib/cms";
+
+export const seoPlugin = definePlugin<{ defaultTitleSuffix?: string }>((options = {}) => ({
+  name: "seo-plugin",
+  version: "1.0.0",
+
+  // 1. Inject custom fields into existing collections
+  extendCollections: {
+    posts: [
+      fields.text({ name: "metaTitle", label: "Meta Title" }),
+      fields.text({ name: "metaDescription", label: "Meta Description" }),
+    ],
+  },
+
+  // 2. Programmatic setup for hooks and routes
+  setup({ hooks, registerRoute, engine }) {
+    // Intercept content before saving
+    hooks.addFilter("cms.before_create_input", (input: any) => {
+      if (input.title && options.defaultTitleSuffix && !input.data?.metaTitle) {
+        input.data = {
+          ...input.data,
+          metaTitle: `${input.title} | ${options.defaultTitleSuffix}`,
+        };
+      }
+      return input;
+    });
+
+    // Expose custom Web Standard API route
+    registerRoute("GET", "/api/seo/sitemap", async () => {
+      const posts = await engine.collection("posts").find({ status: "published" });
+      const urls = posts.items.map((p) => `https://example.com/posts/${p.slug}`);
+      return new Response(JSON.stringify({ urls }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+  },
+
+  // 3. Lifecycle callbacks
+  async onInit(engine) {
+    console.log("[SEO Plugin] Initialized");
+  },
+}));
+```
+
+Register plugins declaratively in `defineConfig` or dynamically via `cms.use()`:
+
+```typescript
+// Declarative registration
+export default defineConfig({
+  plugins: [seoPlugin({ defaultTitleSuffix: "Alex's Journal" })],
+});
+
+// Or dynamic registration
+cms.use(seoPlugin());
+```
+
+---
+
 ## License
 
 MIT © Google / azlib

package/dist/index.cjs

@@ -230,6 +230,7 @@ function normalizeConfig(config) {
 		},
 		collections,
 		taxonomies: config.taxonomies ?? [],
+		plugins: config.plugins ?? [],
 		admin: {
 			route: config.admin?.route ?? "/admin",
 			enableRegistration: config.admin?.enableRegistration ?? false,
@@ -1246,6 +1247,9 @@ var CMSEngine = class {
 	revisions;
 	lifecycle;
 	collections = /* @__PURE__ */ new Map();
+	plugins = /* @__PURE__ */ new Map();
+	customRoutes = /* @__PURE__ */ new Map();
+	pendingPluginSetups = [];
 	constructor(config = {}, storage, hooks) {
 		this.config = normalizeConfig(config);
 		this.hooks = hooks ?? new HooksManager();
@@ -1258,21 +1262,114 @@ var CMSEngine = class {
 		this.lifecycle = new ContentLifecycle(this.storage, this.hooks);
 		for (const coll of this.config.collections) this.collections.set(coll.slug, coll);
 		if (this.config.taxonomies) for (const tax of this.config.taxonomies) this.taxonomies.registerTaxonomy(tax);
+		if (this.config.plugins) for (const plugin of this.config.plugins) this.use(plugin);
+	}
+	/**
+	* Register a plugin with the CMS engine.
+	*/
+	use(plugin) {
+		if (this.plugins.has(plugin.name)) throw new Error(`[CMSEngine] Plugin '${plugin.name}' is already registered.`);
+		this.plugins.set(plugin.name, plugin);
+		if (plugin.collections) for (const coll of plugin.collections) this.registerCollection(coll);
+		if (plugin.taxonomies) for (const tax of plugin.taxonomies) this.taxonomies.registerTaxonomy(tax);
+		if (plugin.extendCollections) for (const [slug, fields] of Object.entries(plugin.extendCollections)) this.extendCollection(slug, fields);
+		if (plugin.setup) {
+			const context = {
+				engine: this,
+				hooks: this.hooks,
+				storage: this.storage,
+				options: this.options,
+				taxonomies: this.taxonomies,
+				media: this.media,
+				rbac: this.rbac,
+				revisions: this.revisions,
+				lifecycle: this.lifecycle,
+				registerCollection: (c) => this.registerCollection(c),
+				extendCollection: (s, f) => this.extendCollection(s, f),
+				registerTaxonomy: (t) => this.taxonomies.registerTaxonomy(t),
+				registerRoute: (m, p, h) => this.registerRoute(m, p, h)
+			};
+			const setupResult = plugin.setup(context);
+			if (setupResult instanceof Promise) this.pendingPluginSetups.push(setupResult);
+		}
+		return this;
+	}
+	/**
+	* Get all registered plugins.
+	*/
+	getPlugins() {
+		return Array.from(this.plugins.values());
+	}
+	/**
+	* Get a registered plugin by name.
+	*/
+	getPlugin(name) {
+		return this.plugins.get(name);
+	}
+	/**
+	* Check if a plugin is registered.
+	*/
+	hasPlugin(name) {
+		return this.plugins.has(name);
+	}
+	/**
+	* Register a collection dynamically.
+	*/
+	registerCollection(coll) {
+		this.collections.set(coll.slug, coll);
+	}
+	/**
+	* Inject additional field definitions into an existing collection.
+	*/
+	extendCollection(slug, newFields) {
+		const existing = this.collections.get(slug);
+		if (!existing) throw new Error(`[CMSEngine] Cannot extend non-existent collection '${slug}'.`);
+		const existingFieldNames = new Set(existing.fields.map((f) => f.name));
+		const addedFields = newFields.filter((f) => !existingFieldNames.has(f.name));
+		this.collections.set(slug, {
+			...existing,
+			fields: [...existing.fields, ...addedFields]
+		});
+	}
+	/**
+	* Register a custom Web Standard HTTP route on the engine.
+	*/
+	registerRoute(method, path, handler) {
+		const normalizedMethod = method.toUpperCase();
+		let methodMap = this.customRoutes.get(normalizedMethod);
+		if (!methodMap) {
+			methodMap = /* @__PURE__ */ new Map();
+			this.customRoutes.set(normalizedMethod, methodMap);
+		}
+		methodMap.set(path, handler);
+	}
+	/**
+	* Get all custom routes registered across all HTTP methods.
+	*/
+	getCustomRoutes() {
+		return this.customRoutes;
 	}
 	/**
 	* Initialize storage and trigger bootstrap hooks.
 	*/
 	async init() {
 		await this.storage.init();
+		if (this.pendingPluginSetups.length > 0) {
+			await Promise.all(this.pendingPluginSetups);
+			this.pendingPluginSetups = [];
+		}
 		if (this.config.site) {
 			if (!await this.options.has("site_name")) await this.options.set("site_name", this.config.site.name);
 		}
+		for (const plugin of this.plugins.values()) if (plugin.onInit) await plugin.onInit(this);
+		await this.hooks.doAction("cms.plugins_initialized", this);
 		await this.hooks.doAction("cms.init", this);
 	}
 	/**
-	* Close storage connections.
+	* Close storage connections and run plugin teardown hooks.
 	*/
 	async close() {
+		for (const plugin of this.plugins.values()) if (plugin.onClose) await plugin.onClose(this);
 		await this.storage.close();
 		await this.hooks.doAction("cms.close", this);
 	}
@@ -1298,38 +1395,39 @@ var CMSEngine = class {
 		return {
 			config: collConfig,
 			async create(input, authorId = null) {
-				const inputData = { ...input.data || {} };
-				if (input.title !== void 0) inputData.title = input.title;
-				if (input.slug !== void 0) inputData.slug = input.slug;
-				if (input.status !== void 0) inputData.status = input.status;
+				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;
 				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 = input.title ?? normalizedData.title ?? "";
-				const finalSlug = await resolveUniqueSlug(input.slug ? slugify(input.slug) : slugify(title) || "item", async (s) => {
+				const title = filteredInput.title ?? normalizedData.title ?? "";
+				const finalSlug = await resolveUniqueSlug(filteredInput.slug ? slugify(filteredInput.slug) : slugify(title) || "item", async (s) => {
 					return await self.storage.getContentBySlug(slug, s) !== null;
 				});
-				const status = input.status ?? (collConfig.draftable ? "draft" : "published");
+				const status = filteredInput.status ?? (collConfig.draftable ? "draft" : "published");
 				const nowIso = (/* @__PURE__ */ new Date()).toISOString();
 				const item = await self.storage.createContent({
 					collection: slug,
 					slug: finalSlug,
 					title,
 					status,
-					parentId: collConfig.hierarchical ? input.parentId ?? null : null,
+					parentId: collConfig.hierarchical ? filteredInput.parentId ?? null : null,
 					authorId,
 					publishedAt: status === "published" ? nowIso : null,
-					scheduledAt: status === "scheduled" ? input.scheduledAt ?? null : null,
+					scheduledAt: status === "scheduled" ? filteredInput.scheduledAt ?? null : null,
 					data: normalizedData,
-					terms: input.terms
+					terms: filteredInput.terms
 				});
-				if (input.terms) {
-					const allTermIds = Object.values(input.terms).flat();
+				if (filteredInput.terms) {
+					const allTermIds = Object.values(filteredInput.terms).flat();
 					if (allTermIds.length > 0) await self.taxonomies.assignTerms(item.id, allTermIds);
 				}
 				if (collConfig.revisions) await self.revisions.createRevision(item, authorId, "Initial creation");
 				await self.hooks.doAction("cms.content_created", item);
 				await self.hooks.doAction(`cms.${slug}_created`, item);
-				return item;
+				return self.hooks.applyFilters("cms.after_create_item", item, { collection: slug });
 			},
 			async findById(id) {
 				return self.storage.getContent(slug, id);
@@ -1338,51 +1436,58 @@ var CMSEngine = class {
 				return self.storage.getContentBySlug(slug, contentSlug);
 			},
 			async find(options = {}) {
-				return self.storage.findContent(slug, options);
+				const filteredOptions = await self.hooks.applyFilters("cms.find_options", options, { collection: slug });
+				return self.storage.findContent(slug, filteredOptions);
 			},
 			async update(id, input, authorId = null, revisionNote) {
 				const existing = await self.storage.getContent(slug, id);
 				if (!existing) return null;
+				const filteredInput = await self.hooks.applyFilters("cms.before_update_input", input, {
+					collection: slug,
+					id,
+					existing
+				});
 				const mergedData = {
 					...existing.data,
-					...input.data || {}
+					...filteredInput.data || {}
 				};
-				if (input.title !== void 0) mergedData.title = input.title;
+				if (filteredInput.title !== void 0) mergedData.title = filteredInput.title;
 				else if (existing.title !== void 0 && mergedData.title === void 0) mergedData.title = existing.title;
-				if (input.slug !== void 0) mergedData.slug = input.slug;
+				if (filteredInput.slug !== void 0) mergedData.slug = filteredInput.slug;
 				else if (existing.slug !== void 0 && mergedData.slug === void 0) mergedData.slug = existing.slug;
-				if (input.status !== void 0) mergedData.status = input.status;
+				if (filteredInput.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)}`);
 				let updatedSlug = existing.slug;
-				if (input.slug && input.slug !== existing.slug) updatedSlug = await resolveUniqueSlug(input.slug, async (s) => {
+				if (filteredInput.slug && filteredInput.slug !== existing.slug) updatedSlug = await resolveUniqueSlug(filteredInput.slug, async (s) => {
 					const check = await self.storage.getContentBySlug(slug, s);
 					return check !== null && check.id !== id;
 				}, id);
-				const nextStatus = input.status ?? existing.status;
+				const nextStatus = filteredInput.status ?? existing.status;
 				const nowIso = (/* @__PURE__ */ new Date()).toISOString();
 				let publishedAt = existing.publishedAt;
 				if (nextStatus === "published" && !publishedAt) publishedAt = nowIso;
 				const updated = await self.storage.updateContent(slug, id, {
-					title: input.title !== void 0 ? input.title : existing.title,
+					title: filteredInput.title !== void 0 ? filteredInput.title : existing.title,
 					slug: updatedSlug,
 					status: nextStatus,
-					parentId: collConfig.hierarchical ? input.parentId !== void 0 ? input.parentId : existing.parentId : null,
-					scheduledAt: input.scheduledAt !== void 0 ? input.scheduledAt : existing.scheduledAt,
+					parentId: collConfig.hierarchical ? filteredInput.parentId !== void 0 ? filteredInput.parentId : existing.parentId : null,
+					scheduledAt: filteredInput.scheduledAt !== void 0 ? filteredInput.scheduledAt : existing.scheduledAt,
 					publishedAt,
 					authorId: authorId ?? existing.authorId,
 					data: normalizedData,
-					terms: input.terms !== void 0 ? input.terms : existing.terms
+					terms: filteredInput.terms !== void 0 ? filteredInput.terms : existing.terms
 				});
 				if (updated) {
-					if (input.terms) {
-						const allTermIds = Object.values(input.terms).flat();
+					if (filteredInput.terms) {
+						const allTermIds = Object.values(filteredInput.terms).flat();
 						await self.taxonomies.assignTerms(updated.id, allTermIds);
 					}
 					if (collConfig.revisions) await self.revisions.createRevision(updated, authorId, revisionNote ?? `Updated version ${updated.version}`);
 					await self.hooks.doAction("cms.content_updated", updated);
 					await self.hooks.doAction(`cms.${slug}_updated`, updated);
+					return self.hooks.applyFilters("cms.after_update_item", updated, { collection: slug });
 				}
 				return updated;
 			},
@@ -1439,7 +1544,33 @@ function createCMSEngine(config, storage, hooks) {
 	return new CMSEngine(config, storage, hooks);
 }
 //#endregion
+//#region src/core/plugin.ts
+/**
+* Type-safe helper for authoring reusable CMS plugins and plugin factories.
+*/
+function definePlugin(factory) {
+	return factory;
+}
+//#endregion
 //#region src/api/router.ts
+function compilePath(path) {
+	const keys = [];
+	const pattern = path.replace(/:([a-zA-Z0-9_]+)/g, (_, key) => {
+		keys.push(key);
+		return "([^/]+)";
+	});
+	return {
+		regex: new RegExp(`^${pattern}$`),
+		keys
+	};
+}
+function matchRoute(entry, pathname) {
+	const match = pathname.match(entry.regex);
+	if (!match) return null;
+	const params = {};
+	for (let i = 0; i < entry.keys.length; i++) params[entry.keys[i]] = decodeURIComponent(match[i + 1]);
+	return params;
+}
 function jsonResponse(data, status = 200, headers = {}) {
 	return new Response(JSON.stringify(data), {
 		status,
@@ -1454,10 +1585,25 @@ function jsonResponse(data, status = 200, headers = {}) {
 }
 var CMSRouter = class {
 	engine;
+	localRoutes = [];
 	constructor(engine) {
 		this.engine = engine;
 	}
 	/**
+	* Register a custom Web Standard route on the router.
+	*/
+	registerRoute(method, path, handler) {
+		const { regex, keys } = compilePath(path);
+		this.localRoutes.push({
+			method: method.toUpperCase(),
+			path,
+			regex,
+			keys,
+			handler
+		});
+		return this;
+	}
+	/**
 	* Universal Web Standards request handler.
 	*/
 	async handle(request) {
@@ -1485,6 +1631,8 @@ var CMSRouter = class {
 			if (pathname.startsWith("/api/taxonomies")) return this.handleTaxonomies(pathname, method, url, request);
 			if (pathname.startsWith("/api/media")) return this.handleMedia(pathname, method, url, request);
 			if (pathname.startsWith("/api/content")) return this.handleContent(pathname, method, url, request);
+			const customResponse = await this.handleCustomRoute(pathname, method, url, request);
+			if (customResponse) return customResponse;
 			return jsonResponse({
 				error: "Endpoint not found",
 				path: pathname
@@ -1493,6 +1641,29 @@ var CMSRouter = class {
 			return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 500);
 		}
 	}
+	async handleCustomRoute(pathname, method, url, request) {
+		for (const route of this.localRoutes) if (route.method === method) {
+			const params = matchRoute(route, pathname);
+			if (params !== null) {
+				const context = {
+					params,
+					url,
+					engine: this.engine
+				};
+				return await route.handler(request, context);
+			}
+		}
+		const engineRoutes = this.engine.getCustomRoutes().get(method);
+		if (engineRoutes) for (const [pathPattern, handler] of engineRoutes) {
+			const params = matchRoute(compilePath(pathPattern), pathname);
+			if (params !== null) return await handler(request, {
+				params,
+				url,
+				engine: this.engine
+			});
+		}
+		return null;
+	}
 	async handleContent(pathname, method, url, request) {
 		const parts = pathname.replace(/^\/api\/content\/?/, "").split("/").filter(Boolean);
 		const collectionSlug = parts[0];
@@ -1796,6 +1967,7 @@ exports.createCMSRouter = createCMSRouter;
 exports.createCmsClient = createCmsClient;
 exports.defaultHooks = defaultHooks;
 exports.defineConfig = defineConfig;
+exports.definePlugin = definePlugin;
 exports.fields = fields;
 exports.normalizeConfig = normalizeConfig;
 exports.resolveUniqueSlug = resolveUniqueSlug;