@voyantjs/plugin-payload-cms 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,15 @@
 # @voyantjs/plugin-payload-cms
 
-Payload CMS sync plugin for Voyant. Subscribes to module events and mirrors documents into a Payload collection keyed by a `voyantId` field.
+Payload CMS sync adapter bundle for Voyant.
+
+Architecturally, this package is primarily:
+
+- a Payload sync adapter
+- a subscriber bundle that mirrors Voyant module records into Payload
+- an optional plugin bundle for distribution
+
+It subscribes to module events and mirrors documents into a Payload collection
+keyed by a `voyantId` field.
 
 ## Install
 
@@ -14,19 +23,23 @@ pnpm add @voyantjs/plugin-payload-cms
 import { payloadCmsPlugin } from "@voyantjs/plugin-payload-cms"
 import { createApp } from "@voyantjs/hono"
 
+const payloadCmsSync = payloadCmsPlugin({
+  apiUrl: "https://cms.example.com/api",
+  apiKey: env.PAYLOAD_API_KEY,
+  collection: "products",
+  // optional: events, mapEvent, logger, apiKeyAuthScheme
+})
+
 const app = createApp({
-  plugins: [
-    payloadCmsPlugin({
-      apiUrl: "https://cms.example.com/api",
-      apiKey: env.PAYLOAD_API_KEY,
-      collection: "products",
-      // optional: events, mapEvent, logger, apiKeyAuthScheme
-    }),
-  ],
+  plugins: [payloadCmsSync],
 })
 ```
 
-By default the plugin wires up 3 subscribers (`product.created`, `product.updated`, `product.deleted`) that upsert/delete documents keyed by `voyantId`. All error handling is fire-and-forget per the EventBus contract.
+The exported value is an optional distribution bundle. At runtime, the package
+behaves primarily as a subscriber-driven Payload sync adapter. By default it
+wires up 3 subscribers (`product.created`, `product.updated`, `product.deleted`)
+that upsert/delete documents keyed by `voyantId`. All error handling is
+fire-and-forget per the EventBus contract.
 
 ## Exports
 

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export type { PayloadClient, PayloadClientOptions } from "./client.js";
 export { createPayloadClient } from "./client.js";
 export type { PayloadCmsPluginOptions, PayloadLogger, PayloadMapFn, PayloadSyncEventNames, } from "./plugin.js";
 export { payloadCmsPlugin } from "./plugin.js";
+export type { PayloadSyncRuntime, ResolvedPayloadSyncEventNames } from "./runtime.js";
+export { createPayloadSyncRuntime } from "./runtime.js";
 export type { PayloadDocBody, PayloadFetch, VoyantEntityEvent } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EACV,uBAAuB,EACvB,aAAa,EACb,YAAY,EACZ,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EACV,uBAAuB,EACvB,aAAa,EACb,YAAY,EACZ,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAA;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AACvD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createPayloadClient } from "./client.js";
 export { payloadCmsPlugin } from "./plugin.js";
+export { createPayloadSyncRuntime } from "./runtime.js";

package/dist/plugin.d.ts

@@ -1,59 +1,21 @@
 import type { Plugin } from "@voyantjs/core";
-import { type PayloadClientOptions } from "./client.js";
+import type { PayloadClientOptions } from "./client.js";
 import type { PayloadDocBody, VoyantEntityEvent } from "./types.js";
-/**
- * Event names the plugin subscribes to. Defaults match the `<resource>.<pastTenseAction>`
- * naming convention documented by the EventBus contract.
- */
 export interface PayloadSyncEventNames {
     created?: string;
     updated?: string;
     deleted?: string;
 }
-/**
- * Mapper from a Voyant event payload (assumed to carry at least `id: string`)
- * to a Payload document body. The `voyantId` field is injected automatically
- * by the client — do not set it here.
- */
 export type PayloadMapFn = (event: VoyantEntityEvent) => PayloadDocBody;
-/**
- * Logger shape used to surface plugin errors without coupling to any specific
- * runtime. Defaults to `console`.
- */
 export interface PayloadLogger {
     error: (message: string, meta?: unknown) => void;
     info?: (message: string, meta?: unknown) => void;
 }
 export interface PayloadCmsPluginOptions extends PayloadClientOptions {
-    /**
-     * Payload collection slug to sync Voyant records into (e.g. "products").
-     */
     collection: string;
-    /**
-     * Event names this plugin subscribes to. Defaults to
-     * `product.created` / `product.updated` / `product.deleted`.
-     */
     events?: PayloadSyncEventNames;
-    /**
-     * Map a Voyant event payload into a Payload document body. Defaults to
-     * passing through every property except `id` (which becomes `voyantId`).
-     */
     mapEvent?: PayloadMapFn;
-    /** Override logger. Defaults to `console`. */
     logger?: PayloadLogger;
 }
-/**
- * Build a Voyant {@link Plugin} that pushes event payloads to a Payload
- * collection as documents, keyed by `voyantId` for idempotent upserts.
- *
- * The plugin subscribes to three events (configurable via
- * {@link PayloadCmsPluginOptions.events}):
- * - `product.created` → upsert document
- * - `product.updated` → upsert document
- * - `product.deleted` → delete document by `voyantId`
- *
- * Errors are caught and logged — subscribers are fire-and-forget per the
- * EventBus contract, so a Payload outage never blocks the emitter.
- */
 export declare function payloadCmsPlugin(options: PayloadCmsPluginOptions): Plugin;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,gBAAgB,CAAA;AAExD,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,cAAc,CAAA;AAEvE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,aAAa,CAAA;CACvB;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CA+DzE"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,gBAAgB,CAAA;AAGxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGnE,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,cAAc,CAAA;AAEvE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,qBAAqB,CAAA;IAC9B,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,MAAM,CAAC,EAAE,aAAa,CAAA;CACvB;AASD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAyDzE"}

package/dist/plugin.js

@@ -1,8 +1,6 @@
-import { createPayloadClient } from "./client.js";
-function defaultMapEvent(event) {
-    const { id: _id, ...rest } = event;
-    return rest;
-}
+import { ZodError } from "zod";
+import { createPayloadSyncRuntime } from "./runtime.js";
+import { payloadCmsPluginOptionsSchema } from "./validation.js";
 function coerceEvent(data) {
     if (data == null || typeof data !== "object")
         return null;
@@ -11,37 +9,18 @@ function coerceEvent(data) {
         return null;
     return maybe;
 }
-/**
- * Build a Voyant {@link Plugin} that pushes event payloads to a Payload
- * collection as documents, keyed by `voyantId` for idempotent upserts.
- *
- * The plugin subscribes to three events (configurable via
- * {@link PayloadCmsPluginOptions.events}):
- * - `product.created` → upsert document
- * - `product.updated` → upsert document
- * - `product.deleted` → delete document by `voyantId`
- *
- * Errors are caught and logged — subscribers are fire-and-forget per the
- * EventBus contract, so a Payload outage never blocks the emitter.
- */
 export function payloadCmsPlugin(options) {
-    const client = createPayloadClient(options);
-    const mapEvent = options.mapEvent ?? defaultMapEvent;
-    const logger = options.logger ?? console;
-    const eventNames = {
-        created: options.events?.created ?? "product.created",
-        updated: options.events?.updated ?? "product.updated",
-        deleted: options.events?.deleted ?? "product.deleted",
-    };
+    const validatedOptions = parsePayloadCmsPluginOptions(options);
+    const { client, mapEvent, logger, eventNames } = createPayloadSyncRuntime(validatedOptions);
     const subscribers = [
         {
             event: eventNames.created,
-            handler: async (data) => {
-                const event = coerceEvent(data);
+            handler: async (envelope) => {
+                const event = coerceEvent(envelope.data);
                 if (!event)
                     return;
                 try {
-                    await client.upsertByVoyantId(options.collection, event.id, mapEvent(event));
+                    await client.upsertByVoyantId(validatedOptions.collection, event.id, mapEvent(event));
                 }
                 catch (err) {
                     logger.error(`[payload-cms] upsert on "${eventNames.created}" failed for ${event.id}`, err);
@@ -50,12 +29,12 @@ export function payloadCmsPlugin(options) {
         },
         {
             event: eventNames.updated,
-            handler: async (data) => {
-                const event = coerceEvent(data);
+            handler: async (envelope) => {
+                const event = coerceEvent(envelope.data);
                 if (!event)
                     return;
                 try {
-                    await client.upsertByVoyantId(options.collection, event.id, mapEvent(event));
+                    await client.upsertByVoyantId(validatedOptions.collection, event.id, mapEvent(event));
                 }
                 catch (err) {
                     logger.error(`[payload-cms] upsert on "${eventNames.updated}" failed for ${event.id}`, err);
@@ -64,12 +43,12 @@ export function payloadCmsPlugin(options) {
         },
         {
             event: eventNames.deleted,
-            handler: async (data) => {
-                const event = coerceEvent(data);
+            handler: async (envelope) => {
+                const event = coerceEvent(envelope.data);
                 if (!event)
                     return;
                 try {
-                    await client.deleteByVoyantId(options.collection, event.id);
+                    await client.deleteByVoyantId(validatedOptions.collection, event.id);
                 }
                 catch (err) {
                     logger.error(`[payload-cms] delete on "${eventNames.deleted}" failed for ${event.id}`, err);
@@ -83,3 +62,20 @@ export function payloadCmsPlugin(options) {
         subscribers,
     };
 }
+function parsePayloadCmsPluginOptions(options) {
+    try {
+        return payloadCmsPluginOptionsSchema.parse(options);
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            const detail = error.issues
+                .map((issue) => {
+                const path = issue.path.join(".") || "options";
+                return `${path}: ${issue.message}`;
+            })
+                .join("; ");
+            throw new Error(`Invalid Payload CMS plugin options: ${detail}`);
+        }
+        throw error;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,15 @@
+import { createPayloadClient } from "./client.js";
+import type { PayloadCmsPluginOptions, PayloadLogger, PayloadMapFn } from "./plugin.js";
+export interface ResolvedPayloadSyncEventNames {
+    created: string;
+    updated: string;
+    deleted: string;
+}
+export interface PayloadSyncRuntime {
+    client: ReturnType<typeof createPayloadClient>;
+    logger: PayloadLogger;
+    mapEvent: PayloadMapFn;
+    eventNames: ResolvedPayloadSyncEventNames;
+}
+export declare function createPayloadSyncRuntime(options: PayloadCmsPluginOptions): PayloadSyncRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAGvF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA;IAC9C,MAAM,EAAE,aAAa,CAAA;IACrB,QAAQ,EAAE,YAAY,CAAA;IACtB,UAAU,EAAE,6BAA6B,CAAA;CAC1C;AAOD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,kBAAkB,CAW7F"}

package/dist/runtime.js

@@ -0,0 +1,17 @@
+import { createPayloadClient } from "./client.js";
+function defaultMapEvent(event) {
+    const { id: _id, ...rest } = event;
+    return rest;
+}
+export function createPayloadSyncRuntime(options) {
+    return {
+        client: createPayloadClient(options),
+        logger: options.logger ?? console,
+        mapEvent: options.mapEvent ?? defaultMapEvent,
+        eventNames: {
+            created: options.events?.created ?? "product.created",
+            updated: options.events?.updated ?? "product.updated",
+            deleted: options.events?.deleted ?? "product.deleted",
+        },
+    };
+}

package/dist/validation.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { PayloadLogger, PayloadMapFn, PayloadSyncEventNames } from "./plugin.js";
+import type { PayloadFetch } from "./types.js";
+export declare const payloadCmsPluginOptionsSchema: z.ZodObject<{
+    apiUrl: z.ZodString;
+    apiKey: z.ZodString;
+    collection: z.ZodString;
+    voyantIdField: z.ZodOptional<z.ZodString>;
+    apiKeyAuthScheme: z.ZodOptional<z.ZodString>;
+    fetch: z.ZodOptional<z.ZodCustom<PayloadFetch | undefined, PayloadFetch | undefined>>;
+    events: z.ZodOptional<z.ZodCustom<PayloadSyncEventNames | undefined, PayloadSyncEventNames | undefined>>;
+    mapEvent: z.ZodOptional<z.ZodCustom<PayloadMapFn | undefined, PayloadMapFn | undefined>>;
+    logger: z.ZodOptional<z.ZodCustom<PayloadLogger | undefined, PayloadLogger | undefined>>;
+}, z.core.$strip>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAEV,aAAa,EACb,YAAY,EACZ,qBAAqB,EACtB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAkC9C,eAAO,MAAM,6BAA6B;;;;;;;;;;iBAUK,CAAA"}

package/dist/validation.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+const optionalString = z.string().trim().min(1).optional();
+const optionalFetch = z.custom((value) => value === undefined || typeof value === "function", "Expected a fetch implementation function");
+const optionalLogger = z.custom((value) => value === undefined ||
+    (typeof value === "object" &&
+        value !== null &&
+        typeof value.error === "function" &&
+        ((value.info ?? undefined) === undefined ||
+            typeof value.info === "function")), "Expected a logger with an error function");
+const optionalMapEvent = z.custom((value) => value === undefined || typeof value === "function", "Expected a mapEvent function");
+const optionalEvents = z.custom((value) => {
+    if (value === undefined)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const events = value;
+    return [events.created, events.updated, events.deleted].every((entry) => entry === undefined || (typeof entry === "string" && entry.trim().length > 0));
+}, "Expected event names to be non-empty strings");
+export const payloadCmsPluginOptionsSchema = z.object({
+    apiUrl: z.string().trim().url(),
+    apiKey: z.string().trim().min(1),
+    collection: z.string().trim().min(1),
+    voyantIdField: optionalString,
+    apiKeyAuthScheme: optionalString,
+    fetch: optionalFetch.optional(),
+    events: optionalEvents.optional(),
+    mapEvent: optionalMapEvent.optional(),
+    logger: optionalLogger.optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/plugin-payload-cms",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
   "exports": {
@@ -22,7 +22,8 @@
     }
   },
   "dependencies": {
-    "@voyantjs/core": "0.5.0"
+    "zod": "^4.3.6",
+    "@voyantjs/core": "0.6.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",