@voyantjs/plugin-payload-cms 0.1.0

package/LICENSE

@@ -0,0 +1,109 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 PixelMakers Studio SRL
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly
+display and redistribute the Software for any Permitted Purpose identified
+below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing
+Use means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe
+our patents, the license grant above includes a license under our patents.
+If you make a claim against any party that the Software infringes or
+contributes to the infringement of any patent, then your patent license to
+the Software ends immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives
+of the Software.
+
+If you redistribute any copies, modifications or derivatives of the
+Software, you must include a copy of or a link to these Terms and Conditions
+and not remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A
+PARTICULAR PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO
+THE SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+DAMAGES, EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin
+of the Software, you have no right under these Terms and Conditions to use
+our trademarks, trade names, service marks or product names.
+
+---
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software
+under the Apache License, Version 2.0 that is effective on the second
+anniversary of the date we make the Software available. On or after that
+date, you may use the Software under the Apache License, Version 2.0, in
+which case the following will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.

package/README.md

@@ -0,0 +1,42 @@
+# @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.
+
+## Install
+
+```bash
+pnpm add @voyantjs/plugin-payload-cms
+```
+
+## Usage
+
+```typescript
+import { payloadCmsPlugin } from "@voyantjs/plugin-payload-cms"
+import { createApp } from "@voyantjs/hono"
+
+const app = createApp({
+  plugins: [
+    payloadCmsPlugin({
+      apiUrl: "https://cms.example.com/api",
+      apiKey: env.PAYLOAD_API_KEY,
+      collection: "products",
+      // optional: events, mapEvent, logger, apiKeyAuthScheme
+    }),
+  ],
+})
+```
+
+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.
+
+## Exports
+
+| Entry | Description |
+| --- | --- |
+| `.` | Barrel re-exports |
+| `./plugin` | `payloadCmsPlugin(options)` |
+| `./client` | `createPayloadClient` — `upsertByVoyantId`, `deleteByVoyantId`, `findByVoyantId` |
+| `./types` | Plugin option types |
+
+## License
+
+FSL-1.1-Apache-2.0

package/dist/src/client.d.ts

@@ -0,0 +1,48 @@
+import type { PayloadDocBody, PayloadFetch } from "./types.js";
+/**
+ * Options for {@link createPayloadClient}.
+ */
+export interface PayloadClientOptions {
+    /**
+     * Base URL of the Payload REST API including `/api` suffix.
+     * Example: `"https://cms.example.com/api"`.
+     */
+    apiUrl: string;
+    /** Payload API key. Sent as `Authorization: ${apiKeyHeader} API-Key ${apiKey}`. */
+    apiKey: string;
+    /**
+     * Field on the Payload collection that stores the Voyant record's ID.
+     * Defaults to `"voyantId"`. The Payload collection must declare this
+     * field (unique recommended).
+     */
+    voyantIdField?: string;
+    /**
+     * Header used to carry the API key. Defaults to `"users API-Key"` which
+     * matches Payload's default `users` auth collection. Override if your
+     * Payload deployment uses a different auth collection.
+     */
+    apiKeyAuthScheme?: string;
+    /** Override `fetch` (e.g. in tests). Defaults to global `fetch`. */
+    fetch?: PayloadFetch;
+}
+export interface PayloadClient {
+    /**
+     * Create or update a document whose {@link PayloadClientOptions.voyantIdField}
+     * equals `voyantId`.
+     */
+    upsertByVoyantId(collection: string, voyantId: string, body: PayloadDocBody): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /**
+     * Delete a document whose `voyantId` field equals the given value. Returns
+     * `false` if no matching document was found.
+     */
+    deleteByVoyantId(collection: string, voyantId: string): Promise<boolean>;
+    /** Find at most one document whose `voyantId` field equals the given value. */
+    findByVoyantId(collection: string, voyantId: string): Promise<{
+        id: string;
+    } | null>;
+}
+export declare function createPayloadClient(options: PayloadClientOptions): PayloadClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,YAAY,CAAA;CACrB;AAUD,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,gBAAgB,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC5C;;;OAGG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACxE,+EAA+E;IAC/E,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;CACrF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA+FhF"}

package/dist/src/client.js

@@ -0,0 +1,79 @@
+export function createPayloadClient(options) {
+    const voyantIdField = options.voyantIdField ?? "voyantId";
+    const authScheme = options.apiKeyAuthScheme ?? "users API-Key";
+    const apiUrl = options.apiUrl.replace(/\/$/, "");
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    function headers() {
+        return {
+            Authorization: `${authScheme} ${options.apiKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async function request(method, path, body) {
+        if (!fetchImpl) {
+            throw new Error("Payload client requires a fetch implementation");
+        }
+        const init = {
+            method,
+            headers: headers(),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const response = await fetchImpl(`${apiUrl}${path}`, init);
+        // Payload sends JSON for all 2xx/4xx; pull both eagerly.
+        let text = "";
+        let json = null;
+        try {
+            text = await response.text();
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // leave json as null, surface text
+        }
+        return { ok: response.ok, status: response.status, json, text };
+    }
+    async function findByVoyantId(collection, voyantId) {
+        const query = `where[${encodeURIComponent(voyantIdField)}][equals]=${encodeURIComponent(voyantId)}&limit=1&depth=0`;
+        const res = await request("GET", `/${collection}?${query}`);
+        if (!res.ok) {
+            throw new Error(`Payload findByVoyantId(${collection}) failed (${res.status}): ${res.text}`);
+        }
+        const body = (res.json ?? {});
+        const first = body.docs?.[0];
+        if (!first)
+            return null;
+        return { id: first.id };
+    }
+    async function upsertByVoyantId(collection, voyantId, body) {
+        const existing = await findByVoyantId(collection, voyantId);
+        const fullBody = { ...body, [voyantIdField]: voyantId };
+        if (existing) {
+            const res = await request("PATCH", `/${collection}/${existing.id}`, fullBody);
+            if (!res.ok) {
+                throw new Error(`Payload update(${collection}/${existing.id}) failed (${res.status}): ${res.text}`);
+            }
+            return { id: existing.id, created: false };
+        }
+        const res = await request("POST", `/${collection}`, fullBody);
+        if (!res.ok) {
+            throw new Error(`Payload create(${collection}) failed (${res.status}): ${res.text}`);
+        }
+        const json = (res.json ?? {});
+        const id = json.doc?.id ?? json.id;
+        if (!id) {
+            throw new Error(`Payload create(${collection}) response missing id`);
+        }
+        return { id, created: true };
+    }
+    async function deleteByVoyantId(collection, voyantId) {
+        const existing = await findByVoyantId(collection, voyantId);
+        if (!existing)
+            return false;
+        const res = await request("DELETE", `/${collection}/${existing.id}`);
+        if (!res.ok && res.status !== 404) {
+            throw new Error(`Payload delete(${collection}/${existing.id}) failed (${res.status}): ${res.text}`);
+        }
+        return true;
+    }
+    return { upsertByVoyantId, deleteByVoyantId, findByVoyantId };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+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 { PayloadDocBody, PayloadFetch, VoyantEntityEvent } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +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"}

package/dist/src/index.js

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

package/dist/src/plugin.d.ts

@@ -0,0 +1,59 @@
+import type { Plugin } from "@voyantjs/core";
+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/src/plugin.d.ts.map

@@ -0,0 +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"}

package/dist/src/plugin.js

@@ -0,0 +1,85 @@
+import { createPayloadClient } from "./client.js";
+function defaultMapEvent(event) {
+    const { id: _id, ...rest } = event;
+    return rest;
+}
+function coerceEvent(data) {
+    if (data == null || typeof data !== "object")
+        return null;
+    const maybe = data;
+    if (typeof maybe.id !== "string")
+        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 subscribers = [
+        {
+            event: eventNames.created,
+            handler: async (data) => {
+                const event = coerceEvent(data);
+                if (!event)
+                    return;
+                try {
+                    await client.upsertByVoyantId(options.collection, event.id, mapEvent(event));
+                }
+                catch (err) {
+                    logger.error(`[payload-cms] upsert on "${eventNames.created}" failed for ${event.id}`, err);
+                }
+            },
+        },
+        {
+            event: eventNames.updated,
+            handler: async (data) => {
+                const event = coerceEvent(data);
+                if (!event)
+                    return;
+                try {
+                    await client.upsertByVoyantId(options.collection, event.id, mapEvent(event));
+                }
+                catch (err) {
+                    logger.error(`[payload-cms] upsert on "${eventNames.updated}" failed for ${event.id}`, err);
+                }
+            },
+        },
+        {
+            event: eventNames.deleted,
+            handler: async (data) => {
+                const event = coerceEvent(data);
+                if (!event)
+                    return;
+                try {
+                    await client.deleteByVoyantId(options.collection, event.id);
+                }
+                catch (err) {
+                    logger.error(`[payload-cms] delete on "${eventNames.deleted}" failed for ${event.id}`, err);
+                }
+            },
+        },
+    ];
+    return {
+        name: "payload-cms",
+        version: "0.1.0",
+        subscribers,
+    };
+}

package/dist/src/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal shape Voyant events expose when carrying a record identifier.
+ * The plugin accepts anything with `id: string`; everything else is passed
+ * through to `mapProduct` untouched.
+ */
+export interface VoyantEntityEvent {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * A Payload document, as a bag of properties. Payload always assigns its own
+ * `id`; the plugin additionally sets a `voyantId` (configurable) for
+ * idempotent lookups.
+ */
+export type PayloadDocBody = Record<string, unknown>;
+/**
+ * Minimal `fetch` shape the Payload client depends on. Works with the global
+ * `fetch` in Node 18+ / Cloudflare Workers / browsers, and is trivially
+ * stubbable in tests.
+ */
+export type PayloadFetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEpD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAC,CAAA"}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tests/unit/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/tests/unit/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../../tests/unit/client.test.ts"],"names":[],"mappings":""}

package/dist/tests/unit/client.test.js

@@ -0,0 +1,192 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPayloadClient } from "../../src/client.js";
+function jsonResponse(status, body) {
+    const text = JSON.stringify(body);
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => JSON.parse(text),
+        text: async () => text,
+    };
+}
+function textResponse(status, text) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => {
+            throw new Error("not json");
+        },
+        text: async () => text,
+    };
+}
+const baseOptions = {
+    apiUrl: "https://cms.example.com/api",
+    apiKey: "test-key",
+};
+describe("createPayloadClient.findByVoyantId", () => {
+    it("returns the first matching doc", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { docs: [{ id: "pl_1", name: "a" }], totalDocs: 1 }));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.findByVoyantId("products", "prod_xyz");
+        expect(result).toEqual({ id: "pl_1" });
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toContain("https://cms.example.com/api/products?");
+        expect(url).toContain("where[voyantId][equals]=prod_xyz");
+        expect(url).toContain("limit=1");
+        expect(init.method).toBe("GET");
+        expect(init.headers.Authorization).toBe("users API-Key test-key");
+    });
+    it("returns null when no docs match", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { docs: [], totalDocs: 0 }));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.findByVoyantId("products", "missing")).toBeNull();
+    });
+    it("respects a custom voyantIdField", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { docs: [] }));
+        const client = createPayloadClient({
+            ...baseOptions,
+            voyantIdField: "externalId",
+            fetch: fetchMock,
+        });
+        await client.findByVoyantId("products", "prod_1");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain("where[externalId][equals]=prod_1");
+    });
+    it("respects a custom apiKeyAuthScheme", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { docs: [] }));
+        const client = createPayloadClient({
+            ...baseOptions,
+            apiKeyAuthScheme: "admins API-Key",
+            fetch: fetchMock,
+        });
+        await client.findByVoyantId("products", "prod_1");
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init.headers.Authorization).toBe("admins API-Key test-key");
+    });
+    it("strips trailing slash from apiUrl", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { docs: [] }));
+        const client = createPayloadClient({
+            ...baseOptions,
+            apiUrl: "https://cms.example.com/api/",
+            fetch: fetchMock,
+        });
+        await client.findByVoyantId("products", "x");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url.startsWith("https://cms.example.com/api/products?")).toBe(true);
+    });
+    it("throws on non-2xx response", async () => {
+        const fetchMock = vi.fn(async () => textResponse(500, "boom"));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.findByVoyantId("products", "x")).rejects.toThrow(/Payload findByVoyantId\(products\) failed \(500\)/);
+    });
+});
+describe("createPayloadClient.upsertByVoyantId", () => {
+    it("creates a new doc when none exists", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(jsonResponse(201, { doc: { id: "pl_new", name: "X" } }));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.upsertByVoyantId("products", "prod_1", { name: "X" });
+        expect(result).toEqual({ id: "pl_new", created: true });
+        const createCall = fetchMock.mock.calls[1];
+        expect(createCall[0]).toBe("https://cms.example.com/api/products");
+        expect(createCall[1].method).toBe("POST");
+        const body = JSON.parse(createCall[1].body ?? "{}");
+        expect(body).toEqual({ name: "X", voyantId: "prod_1" });
+    });
+    it("updates an existing doc when found", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_existing" }] }))
+            .mockResolvedValueOnce(jsonResponse(200, { doc: { id: "pl_existing", name: "Y" } }));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.upsertByVoyantId("products", "prod_1", { name: "Y" });
+        expect(result).toEqual({ id: "pl_existing", created: false });
+        const patchCall = fetchMock.mock.calls[1];
+        expect(patchCall[0]).toBe("https://cms.example.com/api/products/pl_existing");
+        expect(patchCall[1].method).toBe("PATCH");
+    });
+    it("accepts a top-level id in create response", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(jsonResponse(201, { id: "pl_top" }));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.upsertByVoyantId("products", "prod_1", {});
+        expect(result.id).toBe("pl_top");
+    });
+    it("throws if create response has no id", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(jsonResponse(201, {}));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.upsertByVoyantId("products", "p", {})).rejects.toThrow(/response missing id/);
+    });
+    it("throws on create error", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(textResponse(400, "bad request"));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.upsertByVoyantId("products", "p", {})).rejects.toThrow(/Payload create\(products\) failed \(400\)/);
+    });
+    it("throws on update error", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_1" }] }))
+            .mockResolvedValueOnce(textResponse(409, "conflict"));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.upsertByVoyantId("products", "p", {})).rejects.toThrow(/Payload update\(products\/pl_1\) failed \(409\)/);
+    });
+});
+describe("createPayloadClient.deleteByVoyantId", () => {
+    it("deletes when doc exists", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_1" }] }))
+            .mockResolvedValueOnce(jsonResponse(200, {}));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.deleteByVoyantId("products", "p")).toBe(true);
+        const deleteCall = fetchMock.mock.calls[1];
+        expect(deleteCall[0]).toBe("https://cms.example.com/api/products/pl_1");
+        expect(deleteCall[1].method).toBe("DELETE");
+    });
+    it("returns false when doc does not exist", async () => {
+        const fetchMock = vi.fn().mockResolvedValueOnce(jsonResponse(200, { docs: [] }));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.deleteByVoyantId("products", "p")).toBe(false);
+        expect(fetchMock).toHaveBeenCalledOnce();
+    });
+    it("treats 404 on delete as success", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_1" }] }))
+            .mockResolvedValueOnce(textResponse(404, "gone"));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.deleteByVoyantId("products", "p")).toBe(true);
+    });
+    it("throws on non-2xx, non-404 delete response", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_1" }] }))
+            .mockResolvedValueOnce(textResponse(500, "boom"));
+        const client = createPayloadClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.deleteByVoyantId("products", "p")).rejects.toThrow(/Payload delete\(products\/pl_1\) failed \(500\)/);
+    });
+});
+describe("createPayloadClient — fetch handling", () => {
+    it("throws when no fetch implementation is available", async () => {
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = undefined;
+        try {
+            // biome-ignore lint/suspicious/noExplicitAny: simulating missing fetch
+            const client = createPayloadClient({ ...baseOptions, fetch: undefined });
+            await expect(client.findByVoyantId("products", "x")).rejects.toThrow(/requires a fetch implementation/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});

package/dist/tests/unit/plugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin.test.d.ts.map

package/dist/tests/unit/plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.d.ts","sourceRoot":"","sources":["../../../tests/unit/plugin.test.ts"],"names":[],"mappings":""}

package/dist/tests/unit/plugin.test.js

@@ -0,0 +1,164 @@
+import { createEventBus, registerPlugins } from "@voyantjs/core";
+import { describe, expect, it, vi } from "vitest";
+import { payloadCmsPlugin } from "../../src/plugin.js";
+function jsonResponse(status, body) {
+    const text = JSON.stringify(body);
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => JSON.parse(text),
+        text: async () => text,
+    };
+}
+const baseOptions = {
+    apiUrl: "https://cms.example.com/api",
+    apiKey: "test-key",
+    collection: "products",
+};
+describe("payloadCmsPlugin", () => {
+    it("exposes a stable identity", () => {
+        const plugin = payloadCmsPlugin({ ...baseOptions });
+        expect(plugin.name).toBe("payload-cms");
+        expect(plugin.version).toBeDefined();
+        expect(plugin.subscribers).toHaveLength(3);
+    });
+    it("subscribes to default product.* events", () => {
+        const plugin = payloadCmsPlugin({ ...baseOptions });
+        const names = plugin.subscribers?.map((s) => s.event);
+        expect(names).toEqual(["product.created", "product.updated", "product.deleted"]);
+    });
+    it("honors custom event names", () => {
+        const plugin = payloadCmsPlugin({
+            ...baseOptions,
+            events: {
+                created: "departure.created",
+                updated: "departure.updated",
+                deleted: "departure.deleted",
+            },
+        });
+        const names = plugin.subscribers?.map((s) => s.event);
+        expect(names).toEqual(["departure.created", "departure.updated", "departure.deleted"]);
+    });
+    it("pushes product.created to Payload as an upsert", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(jsonResponse(201, { doc: { id: "pl_1" } }));
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.created", { id: "prod_1", name: "Tour A" });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        const [, createInit] = fetchMock.mock.calls[1];
+        expect(createInit.method).toBe("POST");
+        const body = JSON.parse(createInit.body ?? "{}");
+        expect(body).toEqual({ name: "Tour A", voyantId: "prod_1" });
+    });
+    it("pushes product.updated to Payload as an upsert", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_99" }] }))
+            .mockResolvedValueOnce(jsonResponse(200, { doc: { id: "pl_99" } }));
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.updated", { id: "prod_1", name: "Tour B" });
+        const [url, init] = fetchMock.mock.calls[1];
+        expect(url).toBe("https://cms.example.com/api/products/pl_99");
+        expect(init.method).toBe("PATCH");
+    });
+    it("deletes from Payload on product.deleted", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [{ id: "pl_50" }] }))
+            .mockResolvedValueOnce(jsonResponse(200, {}));
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.deleted", { id: "prod_1" });
+        const [url, init] = fetchMock.mock.calls[1];
+        expect(url).toBe("https://cms.example.com/api/products/pl_50");
+        expect(init.method).toBe("DELETE");
+    });
+    it("applies a custom mapEvent function", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(jsonResponse(201, { doc: { id: "pl_1" } }));
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({
+            ...baseOptions,
+            fetch: fetchMock,
+            mapEvent: (event) => ({
+                title: String(event.name ?? ""),
+                _syncedAt: "2024-01-01",
+            }),
+        });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.created", { id: "prod_x", name: "Cool Tour" });
+        const [, init] = fetchMock.mock.calls[1];
+        const body = JSON.parse(init.body ?? "{}");
+        expect(body).toEqual({
+            title: "Cool Tour",
+            _syncedAt: "2024-01-01",
+            voyantId: "prod_x",
+        });
+    });
+    it("ignores events with no string id", async () => {
+        const fetchMock = vi.fn();
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.created", { name: "no id here" });
+        await bus.emit("product.created", null);
+        await bus.emit("product.created", { id: 42 });
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it("logs and swallows Payload errors (fire-and-forget)", async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 500,
+            json: async () => ({}),
+            text: async () => "server down",
+        });
+        const errorFn = vi.fn();
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({
+            ...baseOptions,
+            fetch: fetchMock,
+            logger: { error: errorFn },
+        });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.created", { id: "prod_1", name: "X" });
+        expect(errorFn).toHaveBeenCalledOnce();
+        const [msg] = errorFn.mock.calls[0];
+        expect(msg).toContain('[payload-cms] upsert on "product.created" failed for prod_1');
+    });
+    it("uses a custom collection name for the Payload path", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { docs: [] }))
+            .mockResolvedValueOnce(jsonResponse(201, { doc: { id: "pl_1" } }));
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({
+            ...baseOptions,
+            collection: "tours",
+            fetch: fetchMock,
+        });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.created", { id: "prod_1", name: "X" });
+        const [findUrl] = fetchMock.mock.calls[0];
+        expect(findUrl).toContain("https://cms.example.com/api/tours?");
+        const [createUrl] = fetchMock.mock.calls[1];
+        expect(createUrl).toBe("https://cms.example.com/api/tours");
+    });
+    it("does not delete if the doc is missing on product.deleted", async () => {
+        const fetchMock = vi.fn().mockResolvedValueOnce(jsonResponse(200, { docs: [] }));
+        const bus = createEventBus();
+        const plugin = payloadCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.deleted", { id: "prod_missing" });
+        // Only the find call should have been made.
+        expect(fetchMock).toHaveBeenCalledOnce();
+    });
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@voyantjs/plugin-payload-cms",
+  "version": "0.1.0",
+  "license": "FSL-1.1-Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "dependencies": {
+    "@voyantjs/core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "@voyantjs/voyant-typescript-config": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}