@voyantjs/plugin-payload-cms 0.24.1 → 0.24.2

package/dist/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/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/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/index.d.ts

@@ -0,0 +1,8 @@
+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

@@ -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,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

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

package/dist/plugin.d.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from "@voyantjs/core";
+import type { PayloadClientOptions } from "./client.js";
+import type { PayloadDocBody, VoyantEntityEvent } from "./types.js";
+export interface PayloadSyncEventNames {
+    created?: string;
+    updated?: string;
+    deleted?: string;
+}
+export type PayloadMapFn = (event: VoyantEntityEvent) => PayloadDocBody;
+export interface PayloadLogger {
+    error: (message: string, meta?: unknown) => void;
+    info?: (message: string, meta?: unknown) => void;
+}
+export interface PayloadCmsPluginOptions extends PayloadClientOptions {
+    collection: string;
+    events?: PayloadSyncEventNames;
+    mapEvent?: PayloadMapFn;
+    logger?: PayloadLogger;
+}
+export declare function payloadCmsPlugin(options: PayloadCmsPluginOptions): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/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;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

@@ -0,0 +1,81 @@
+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;
+    const maybe = data;
+    if (typeof maybe.id !== "string")
+        return null;
+    return maybe;
+}
+export function payloadCmsPlugin(options) {
+    const validatedOptions = parsePayloadCmsPluginOptions(options);
+    const { client, mapEvent, logger, eventNames } = createPayloadSyncRuntime(validatedOptions);
+    const subscribers = [
+        {
+            event: eventNames.created,
+            handler: async (envelope) => {
+                const event = coerceEvent(envelope.data);
+                if (!event)
+                    return;
+                try {
+                    await client.upsertByVoyantId(validatedOptions.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 (envelope) => {
+                const event = coerceEvent(envelope.data);
+                if (!event)
+                    return;
+                try {
+                    await client.upsertByVoyantId(validatedOptions.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 (envelope) => {
+                const event = coerceEvent(envelope.data);
+                if (!event)
+                    return;
+                try {
+                    await client.deleteByVoyantId(validatedOptions.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,
+    };
+}
+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/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/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/types.js

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

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.24.1",
+  "version": "0.24.2",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.24.1"
+    "@voyantjs/core": "0.24.2"
   },
   "devDependencies": {
     "typescript": "^6.0.2",
@@ -50,7 +50,7 @@
     "lint": "biome check src/",
     "test": "vitest run",
     "build": "pnpm run clean && tsc -p tsconfig.json",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"