@voyantjs/plugin-sanity-cms 0.5.0 → 0.6.2

package/README.md

@@ -1,6 +1,15 @@
 # @voyantjs/plugin-sanity-cms
 
-Sanity CMS sync plugin for Voyant. Subscribes to module events and mirrors documents into a Sanity dataset keyed by a `voyantId` field.
+Sanity CMS sync adapter bundle for Voyant.
+
+Architecturally, this package is primarily:
+
+- a Sanity sync adapter
+- a subscriber bundle that mirrors Voyant module records into Sanity
+- an optional packaged bundle when an app wants one installable entrypoint
+
+It subscribes to module events and mirrors documents into a Sanity dataset keyed
+by a `voyantId` field.
 
 ## Install
 
@@ -14,29 +23,33 @@ pnpm add @voyantjs/plugin-sanity-cms
 import { sanityCmsPlugin } from "@voyantjs/plugin-sanity-cms"
 import { createApp } from "@voyantjs/hono"
 
+const sanitySync = sanityCmsPlugin({
+  projectId: env.SANITY_PROJECT_ID,
+  dataset: "production",
+  token: env.SANITY_TOKEN,
+  documentType: "product",
+  // optional: apiVersion, voyantIdField, apiHost, events, mapEvent, logger
+})
+
 const app = createApp({
-  plugins: [
-    sanityCmsPlugin({
-      projectId: env.SANITY_PROJECT_ID,
-      dataset: "production",
-      token: env.SANITY_TOKEN,
-      documentType: "product",
-      // optional: apiVersion, voyantIdField, apiHost, events, mapEvent, logger
-    }),
-  ],
+  plugins: [sanitySync],
 })
 ```
 
-Uses GROQ for reads and Sanity Mutations API for writes. Default `apiVersion` is `"2024-01-01"`. By default the plugin wires up 3 subscribers (`product.created`, `product.updated`, `product.deleted`).
+Uses GROQ for reads and Sanity Mutations API for writes. `sanityCmsPlugin(...)`
+is the packaged distribution helper; at runtime the package is primarily a
+subscriber-driven Sanity sync adapter. Default `apiVersion` is `"2024-01-01"`.
+By default it wires up 3 subscribers
+(`product.created`, `product.updated`, `product.deleted`).
 
 ## Exports
 
 | Entry | Description |
 | --- | --- |
 | `.` | Barrel re-exports |
-| `./plugin` | `sanityCmsPlugin(options)` |
+| `./plugin` | `sanityCmsPlugin(options)` — packaged adapter/subscriber bundle |
 | `./client` | `createSanityClient` — `upsertByVoyantId`, `deleteByVoyantId`, `findByVoyantId` |
-| `./types` | Plugin option types |
+| `./types` | Adapter and bundle option types |
 
 ## License
 

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export type { SanityClient, SanityClientOptions } from "./client.js";
 export { createSanityClient } from "./client.js";
 export type { SanityCmsPluginOptions, SanityLogger, SanityMapFn, SanitySyncEventNames, } from "./plugin.js";
 export { sanityCmsPlugin } from "./plugin.js";
+export type { ResolvedSanitySyncEventNames, SanitySyncRuntime } from "./runtime.js";
+export { createSanitySyncRuntime } from "./runtime.js";
 export type { SanityDocBody, SanityFetch, 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,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,YAAY,EACV,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,YAAY,EACV,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createSanityClient } from "./client.js";
 export { sanityCmsPlugin } from "./plugin.js";
+export { createSanitySyncRuntime } from "./runtime.js";

package/dist/plugin.d.ts

@@ -1,61 +1,21 @@
 import type { Plugin } from "@voyantjs/core";
-import { type SanityClientOptions } from "./client.js";
+import type { SanityClientOptions } from "./client.js";
 import type { SanityDocBody, VoyantEntityEvent } from "./types.js";
-/**
- * Event names the plugin subscribes to. Defaults match the
- * `<resource>.<pastTenseAction>` naming convention documented by the
- * EventBus contract.
- */
 export interface SanitySyncEventNames {
     created?: string;
     updated?: string;
     deleted?: string;
 }
-/**
- * Mapper from a Voyant event payload (assumed to carry at least `id: string`)
- * to a Sanity document body. The `voyantId` field + `_type` are injected
- * automatically by the client — do not set either here.
- */
 export type SanityMapFn = (event: VoyantEntityEvent) => SanityDocBody;
-/**
- * Logger shape used to surface plugin errors without coupling to any specific
- * runtime. Defaults to `console`.
- */
 export interface SanityLogger {
     error: (message: string, meta?: unknown) => void;
     info?: (message: string, meta?: unknown) => void;
 }
 export interface SanityCmsPluginOptions extends SanityClientOptions {
-    /**
-     * Sanity document type to sync Voyant records into (e.g. `"product"`).
-     * Equivalent to a Payload collection / content model.
-     */
     documentType: string;
-    /**
-     * Event names this plugin subscribes to. Defaults to
-     * `product.created` / `product.updated` / `product.deleted`.
-     */
     events?: SanitySyncEventNames;
-    /**
-     * Map a Voyant event payload into a Sanity document body. Defaults to
-     * passing through every property except `id` (which becomes `voyantId`).
-     */
     mapEvent?: SanityMapFn;
-    /** Override logger. Defaults to `console`. */
     logger?: SanityLogger;
 }
-/**
- * Build a Voyant {@link Plugin} that pushes event payloads to a Sanity
- * document type, keyed by `voyantId` for idempotent upserts.
- *
- * The plugin subscribes to three events (configurable via
- * {@link SanityCmsPluginOptions.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 Sanity outage never blocks the emitter.
- */
 export declare function sanityCmsPlugin(options: SanityCmsPluginOptions): 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,EAAsB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,aAAa,CAAA;AAErE;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,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,sBAAuB,SAAQ,mBAAmB;IACjE;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAsDvE"}
+{"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,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGlE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,aAAa,CAAA;AAErE,MAAM,WAAW,YAAY;IAC3B,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,sBAAuB,SAAQ,mBAAmB;IACjE,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AASD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAgDvE"}

package/dist/plugin.js

@@ -1,8 +1,6 @@
-import { createSanityClient } from "./client.js";
-function defaultMapEvent(event) {
-    const { id: _id, ...rest } = event;
-    return rest;
-}
+import { ZodError } from "zod";
+import { createSanitySyncRuntime } from "./runtime.js";
+import { sanityCmsPluginOptionsSchema } 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 Sanity
- * document type, keyed by `voyantId` for idempotent upserts.
- *
- * The plugin subscribes to three events (configurable via
- * {@link SanityCmsPluginOptions.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 Sanity outage never blocks the emitter.
- */
 export function sanityCmsPlugin(options) {
-    const client = createSanityClient(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 = parseSanityCmsPluginOptions(options);
+    const { client, mapEvent, logger, eventNames } = createSanitySyncRuntime(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.documentType, event.id, mapEvent(event));
+                    await client.upsertByVoyantId(validatedOptions.documentType, event.id, mapEvent(event));
                 }
                 catch (err) {
                     logger.error(`[sanity-cms] upsert on "${eventNames.created}" failed for ${event.id}`, err);
@@ -50,12 +29,12 @@ export function sanityCmsPlugin(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.documentType, event.id, mapEvent(event));
+                    await client.upsertByVoyantId(validatedOptions.documentType, event.id, mapEvent(event));
                 }
                 catch (err) {
                     logger.error(`[sanity-cms] upsert on "${eventNames.updated}" failed for ${event.id}`, err);
@@ -64,12 +43,12 @@ export function sanityCmsPlugin(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.documentType, event.id);
+                    await client.deleteByVoyantId(validatedOptions.documentType, event.id);
                 }
                 catch (err) {
                     logger.error(`[sanity-cms] delete on "${eventNames.deleted}" failed for ${event.id}`, err);
@@ -83,3 +62,20 @@ export function sanityCmsPlugin(options) {
         subscribers,
     };
 }
+function parseSanityCmsPluginOptions(options) {
+    try {
+        return sanityCmsPluginOptionsSchema.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 Sanity CMS plugin options: ${detail}`);
+        }
+        throw error;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,15 @@
+import { createSanityClient } from "./client.js";
+import type { SanityCmsPluginOptions, SanityLogger, SanityMapFn } from "./plugin.js";
+export interface ResolvedSanitySyncEventNames {
+    created: string;
+    updated: string;
+    deleted: string;
+}
+export interface SanitySyncRuntime {
+    client: ReturnType<typeof createSanityClient>;
+    logger: SanityLogger;
+    mapEvent: SanityMapFn;
+    eventNames: ResolvedSanitySyncEventNames;
+}
+export declare function createSanitySyncRuntime(options: SanityCmsPluginOptions): SanitySyncRuntime;
+//# 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,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,sBAAsB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGpF,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA;IAC7C,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,WAAW,CAAA;IACrB,UAAU,EAAE,4BAA4B,CAAA;CACzC;AAOD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,iBAAiB,CAW1F"}

package/dist/runtime.js

@@ -0,0 +1,17 @@
+import { createSanityClient } from "./client.js";
+function defaultMapEvent(event) {
+    const { id: _id, ...rest } = event;
+    return rest;
+}
+export function createSanitySyncRuntime(options) {
+    return {
+        client: createSanityClient(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,17 @@
+import { z } from "zod";
+import type { SanityLogger, SanityMapFn, SanitySyncEventNames } from "./plugin.js";
+import type { SanityFetch } from "./types.js";
+export declare const sanityCmsPluginOptionsSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    dataset: z.ZodString;
+    token: z.ZodString;
+    documentType: z.ZodString;
+    apiVersion: z.ZodOptional<z.ZodString>;
+    voyantIdField: z.ZodOptional<z.ZodString>;
+    apiHost: z.ZodOptional<z.ZodString>;
+    fetch: z.ZodOptional<z.ZodCustom<SanityFetch | undefined, SanityFetch | undefined>>;
+    events: z.ZodOptional<z.ZodCustom<SanitySyncEventNames | undefined, SanitySyncEventNames | undefined>>;
+    mapEvent: z.ZodOptional<z.ZodCustom<SanityMapFn | undefined, SanityMapFn | undefined>>;
+    logger: z.ZodOptional<z.ZodCustom<SanityLogger | undefined, SanityLogger | 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,YAAY,EACZ,WAAW,EACX,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAkC7C,eAAO,MAAM,4BAA4B;;;;;;;;;;;;iBAYK,CAAA"}

package/dist/validation.js

@@ -0,0 +1,31 @@
+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 sanityCmsPluginOptionsSchema = z.object({
+    projectId: z.string().trim().min(1),
+    dataset: z.string().trim().min(1),
+    token: z.string().trim().min(1),
+    documentType: z.string().trim().min(1),
+    apiVersion: optionalString,
+    voyantIdField: optionalString,
+    apiHost: optionalString,
+    fetch: optionalFetch.optional(),
+    events: optionalEvents.optional(),
+    mapEvent: optionalMapEvent.optional(),
+    logger: optionalLogger.optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/plugin-sanity-cms",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "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.2"
   },
   "devDependencies": {
     "typescript": "^6.0.2",