@voyantjs/plugin-sanity-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,43 @@
+# @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.
+
+## Install
+
+```bash
+pnpm add @voyantjs/plugin-sanity-cms
+```
+
+## Usage
+
+```typescript
+import { sanityCmsPlugin } from "@voyantjs/plugin-sanity-cms"
+import { createApp } from "@voyantjs/hono"
+
+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
+    }),
+  ],
+})
+```
+
+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`).
+
+## Exports
+
+| Entry | Description |
+| --- | --- |
+| `.` | Barrel re-exports |
+| `./plugin` | `sanityCmsPlugin(options)` |
+| `./client` | `createSanityClient` — `upsertByVoyantId`, `deleteByVoyantId`, `findByVoyantId` |
+| `./types` | Plugin option types |
+
+## License
+
+FSL-1.1-Apache-2.0

package/dist/src/client.d.ts

@@ -0,0 +1,54 @@
+import type { SanityDocBody, SanityFetch } from "./types.js";
+/**
+ * Options for {@link createSanityClient}.
+ */
+export interface SanityClientOptions {
+    /** Sanity project ID (the short slug from sanity.io/manage). */
+    projectId: string;
+    /** Sanity dataset (e.g. `"production"`). */
+    dataset: string;
+    /**
+     * Sanity API token with write access. Sent as
+     * `Authorization: Bearer ${token}`.
+     */
+    token: string;
+    /**
+     * Sanity API version (date-based, e.g. `"2024-01-01"`). Defaults to
+     * `"2024-01-01"`.
+     */
+    apiVersion?: string;
+    /**
+     * Field on the Sanity document that stores the Voyant record's ID.
+     * Defaults to `"voyantId"`. A matching field (+unique index) must be
+     * declared in the Sanity schema.
+     */
+    voyantIdField?: string;
+    /**
+     * Sanity API host. Defaults to `"api.sanity.io"`. Override for regional
+     * hosts, proxies, or self-hosted deployments.
+     */
+    apiHost?: string;
+    /** Override `fetch` (e.g. in tests). Defaults to global `fetch`. */
+    fetch?: SanityFetch;
+}
+export interface SanityClient {
+    /**
+     * Create or replace a document whose {@link SanityClientOptions.voyantIdField}
+     * equals `voyantId`.
+     */
+    upsertByVoyantId(documentType: string, voyantId: string, body: SanityDocBody): Promise<{
+        _id: string;
+        created: boolean;
+    }>;
+    /**
+     * Delete a document whose `voyantId` field equals the given value.
+     * Returns `false` if no matching document was found.
+     */
+    deleteByVoyantId(documentType: string, voyantId: string): Promise<boolean>;
+    /** Find at most one document whose `voyantId` field equals the given value. */
+    findByVoyantId(documentType: string, voyantId: string): Promise<{
+        _id: string;
+    } | null>;
+}
+export declare function createSanityClient(options: SanityClientOptions): SanityClient;
+//# 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,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE5D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;IACjB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAWD,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,gBAAgB,CACd,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC7C;;;OAGG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1E,+EAA+E;IAC/E,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;CACxF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAiH7E"}

package/dist/src/client.js

@@ -0,0 +1,91 @@
+export function createSanityClient(options) {
+    const apiVersion = options.apiVersion ?? "2024-01-01";
+    const voyantIdField = options.voyantIdField ?? "voyantId";
+    const apiHost = options.apiHost ?? "api.sanity.io";
+    const baseUrl = `https://${options.projectId}.${apiHost}/v${apiVersion}/data`;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    function headers() {
+        return {
+            Authorization: `Bearer ${options.token}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async function request(method, path, body) {
+        if (!fetchImpl) {
+            throw new Error("Sanity client requires a fetch implementation");
+        }
+        const init = {
+            method,
+            headers: headers(),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const response = await fetchImpl(`${baseUrl}${path}`, init);
+        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(documentType, voyantId) {
+        // GROQ parameters are JSON-encoded values attached as $-prefixed query params.
+        const groq = `*[_type == $type && ${voyantIdField} == $vid][0]{_id}`;
+        const query = [
+            `query=${encodeURIComponent(groq)}`,
+            `$type=${encodeURIComponent(JSON.stringify(documentType))}`,
+            `$vid=${encodeURIComponent(JSON.stringify(voyantId))}`,
+        ].join("&");
+        const res = await request("GET", `/query/${options.dataset}?${query}`);
+        if (!res.ok) {
+            throw new Error(`Sanity findByVoyantId(${documentType}) failed (${res.status}): ${res.text}`);
+        }
+        const body = (res.json ?? {});
+        const first = body.result;
+        if (!first)
+            return null;
+        return { _id: first._id };
+    }
+    async function mutate(mutations) {
+        return request("POST", `/mutate/${options.dataset}?returnIds=true&visibility=sync`, {
+            mutations,
+        });
+    }
+    async function upsertByVoyantId(documentType, voyantId, body) {
+        const existing = await findByVoyantId(documentType, voyantId);
+        const docFields = { ...body, [voyantIdField]: voyantId };
+        if (existing) {
+            const res = await mutate([{ patch: { id: existing._id, set: docFields } }]);
+            if (!res.ok) {
+                throw new Error(`Sanity update(${documentType}/${existing._id}) failed (${res.status}): ${res.text}`);
+            }
+            return { _id: existing._id, created: false };
+        }
+        const createDoc = { _type: documentType, ...docFields };
+        const res = await mutate([{ create: createDoc }]);
+        if (!res.ok) {
+            throw new Error(`Sanity create(${documentType}) failed (${res.status}): ${res.text}`);
+        }
+        const json = (res.json ?? {});
+        const id = json.results?.[0]?.id;
+        if (!id) {
+            throw new Error(`Sanity create(${documentType}) response missing id`);
+        }
+        return { _id: id, created: true };
+    }
+    async function deleteByVoyantId(documentType, voyantId) {
+        const existing = await findByVoyantId(documentType, voyantId);
+        if (!existing)
+            return false;
+        const res = await mutate([{ delete: { id: existing._id } }]);
+        if (!res.ok) {
+            throw new Error(`Sanity delete(${documentType}/${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 { 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 { SanityDocBody, SanityFetch, 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,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"}

package/dist/src/index.js

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

package/dist/src/plugin.d.ts

@@ -0,0 +1,61 @@
+import type { Plugin } from "@voyantjs/core";
+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/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,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"}

package/dist/src/plugin.js

@@ -0,0 +1,85 @@
+import { createSanityClient } 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 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 subscribers = [
+        {
+            event: eventNames.created,
+            handler: async (data) => {
+                const event = coerceEvent(data);
+                if (!event)
+                    return;
+                try {
+                    await client.upsertByVoyantId(options.documentType, event.id, mapEvent(event));
+                }
+                catch (err) {
+                    logger.error(`[sanity-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.documentType, event.id, mapEvent(event));
+                }
+                catch (err) {
+                    logger.error(`[sanity-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.documentType, event.id);
+                }
+                catch (err) {
+                    logger.error(`[sanity-cms] delete on "${eventNames.deleted}" failed for ${event.id}`, err);
+                }
+            },
+        },
+    ];
+    return {
+        name: "sanity-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 `mapEvent` untouched.
+ */
+export interface VoyantEntityEvent {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * A Sanity document body, as a bag of properties. Sanity assigns `_id` +
+ * `_type` on creation; the plugin sets a `voyantId` field (configurable)
+ * for idempotent lookups.
+ */
+export type SanityDocBody = Record<string, unknown>;
+/**
+ * Minimal `fetch` shape the Sanity client depends on. Works with the global
+ * `fetch` in Node 18+ / Cloudflare Workers / browsers, and is trivially
+ * stubbable in tests.
+ */
+export type SanityFetch = (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,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEnD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,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,201 @@
+import { describe, expect, it, vi } from "vitest";
+import { createSanityClient } 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 = {
+    projectId: "abc123",
+    dataset: "production",
+    token: "test-token",
+};
+describe("createSanityClient.findByVoyantId", () => {
+    it("returns the first matching doc", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { result: { _id: "sn_1", name: "a" } }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.findByVoyantId("product", "prod_xyz");
+        expect(result).toEqual({ _id: "sn_1" });
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toContain("https://abc123.api.sanity.io/v2024-01-01/data/query/production?");
+        // GROQ query with voyantIdField and params
+        expect(url).toContain("query=");
+        expect(url).toContain("voyantId%20%3D%3D%20%24vid");
+        // JSON-encoded param values (`$` is not percent-encoded in param keys)
+        expect(url).toContain("$type=%22product%22");
+        expect(url).toContain("$vid=%22prod_xyz%22");
+        expect(init.method).toBe("GET");
+        expect(init.headers.Authorization).toBe("Bearer test-token");
+    });
+    it("returns null when no docs match", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { result: null }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.findByVoyantId("product", "missing")).toBeNull();
+    });
+    it("respects a custom voyantIdField", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { result: null }));
+        const client = createSanityClient({
+            ...baseOptions,
+            voyantIdField: "externalId",
+            fetch: fetchMock,
+        });
+        await client.findByVoyantId("product", "prod_1");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain("externalId%20%3D%3D%20%24vid");
+    });
+    it("respects a custom apiVersion", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { result: null }));
+        const client = createSanityClient({
+            ...baseOptions,
+            apiVersion: "2023-10-01",
+            fetch: fetchMock,
+        });
+        await client.findByVoyantId("product", "prod_1");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain("/v2023-10-01/data/query/production?");
+    });
+    it("respects a custom apiHost", async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { result: null }));
+        const client = createSanityClient({
+            ...baseOptions,
+            apiHost: "sanity.internal.example.com",
+            fetch: fetchMock,
+        });
+        await client.findByVoyantId("product", "prod_1");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain("https://abc123.sanity.internal.example.com/");
+    });
+    it("throws on non-2xx response", async () => {
+        const fetchMock = vi.fn(async () => textResponse(500, "boom"));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.findByVoyantId("product", "x")).rejects.toThrow(/Sanity findByVoyantId\(product\) failed \(500\)/);
+    });
+});
+describe("createSanityClient.upsertByVoyantId", () => {
+    it("creates a new doc when none exists", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_new", operation: "create" }] }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.upsertByVoyantId("product", "prod_1", { name: "X" });
+        expect(result).toEqual({ _id: "sn_new", created: true });
+        const createCall = fetchMock.mock.calls[1];
+        expect(createCall[0]).toContain("https://abc123.api.sanity.io/v2024-01-01/data/mutate/production");
+        expect(createCall[0]).toContain("returnIds=true");
+        expect(createCall[0]).toContain("visibility=sync");
+        expect(createCall[1].method).toBe("POST");
+        const body = JSON.parse(createCall[1].body ?? "{}");
+        expect(body).toEqual({
+            mutations: [
+                {
+                    create: { _type: "product", name: "X", voyantId: "prod_1" },
+                },
+            ],
+        });
+    });
+    it("updates an existing doc when found", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: { _id: "sn_existing" } }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_existing", operation: "update" }] }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        const result = await client.upsertByVoyantId("product", "prod_1", { name: "Y" });
+        expect(result).toEqual({ _id: "sn_existing", created: false });
+        const patchCall = fetchMock.mock.calls[1];
+        expect(patchCall[1].method).toBe("POST");
+        const body = JSON.parse(patchCall[1].body ?? "{}");
+        expect(body).toEqual({
+            mutations: [
+                {
+                    patch: {
+                        id: "sn_existing",
+                        set: { name: "Y", voyantId: "prod_1" },
+                    },
+                },
+            ],
+        });
+    });
+    it("throws if create response has no id", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [] }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.upsertByVoyantId("product", "p", {})).rejects.toThrow(/response missing id/);
+    });
+    it("throws on create error", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }))
+            .mockResolvedValueOnce(textResponse(400, "bad request"));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.upsertByVoyantId("product", "p", {})).rejects.toThrow(/Sanity create\(product\) failed \(400\)/);
+    });
+    it("throws on update error", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: { _id: "sn_1" } }))
+            .mockResolvedValueOnce(textResponse(409, "conflict"));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.upsertByVoyantId("product", "p", {})).rejects.toThrow(/Sanity update\(product\/sn_1\) failed \(409\)/);
+    });
+});
+describe("createSanityClient.deleteByVoyantId", () => {
+    it("deletes when doc exists", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: { _id: "sn_1" } }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_1", operation: "delete" }] }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.deleteByVoyantId("product", "p")).toBe(true);
+        const deleteCall = fetchMock.mock.calls[1];
+        expect(deleteCall[1].method).toBe("POST");
+        const body = JSON.parse(deleteCall[1].body ?? "{}");
+        expect(body).toEqual({ mutations: [{ delete: { id: "sn_1" } }] });
+    });
+    it("returns false when doc does not exist", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        expect(await client.deleteByVoyantId("product", "p")).toBe(false);
+        expect(fetchMock).toHaveBeenCalledOnce();
+    });
+    it("throws on non-2xx delete response", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: { _id: "sn_1" } }))
+            .mockResolvedValueOnce(textResponse(500, "boom"));
+        const client = createSanityClient({ ...baseOptions, fetch: fetchMock });
+        await expect(client.deleteByVoyantId("product", "p")).rejects.toThrow(/Sanity delete\(product\/sn_1\) failed \(500\)/);
+    });
+});
+describe("createSanityClient — 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 = createSanityClient({ ...baseOptions, fetch: undefined });
+            await expect(client.findByVoyantId("product", "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,183 @@
+import { createEventBus, registerPlugins } from "@voyantjs/core";
+import { describe, expect, it, vi } from "vitest";
+import { sanityCmsPlugin } 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 = {
+    projectId: "abc123",
+    dataset: "production",
+    token: "test-token",
+    documentType: "product",
+};
+describe("sanityCmsPlugin", () => {
+    it("exposes a stable identity", () => {
+        const plugin = sanityCmsPlugin({ ...baseOptions });
+        expect(plugin.name).toBe("sanity-cms");
+        expect(plugin.version).toBeDefined();
+        expect(plugin.subscribers).toHaveLength(3);
+    });
+    it("subscribes to default product.* events", () => {
+        const plugin = sanityCmsPlugin({ ...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 = sanityCmsPlugin({
+            ...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 Sanity as a create mutation", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_1", operation: "create" }] }));
+        const bus = createEventBus();
+        const plugin = sanityCmsPlugin({ ...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({
+            mutations: [{ create: { _type: "product", name: "Tour A", voyantId: "prod_1" } }],
+        });
+    });
+    it("pushes product.updated to Sanity as a patch mutation", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: { _id: "sn_99" } }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_99", operation: "update" }] }));
+        const bus = createEventBus();
+        const plugin = sanityCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.updated", { id: "prod_1", name: "Tour B" });
+        const [, init] = fetchMock.mock.calls[1];
+        expect(init.method).toBe("POST");
+        const body = JSON.parse(init.body ?? "{}");
+        expect(body).toEqual({
+            mutations: [{ patch: { id: "sn_99", set: { name: "Tour B", voyantId: "prod_1" } } }],
+        });
+    });
+    it("deletes from Sanity on product.deleted", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: { _id: "sn_50" } }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_50", operation: "delete" }] }));
+        const bus = createEventBus();
+        const plugin = sanityCmsPlugin({ ...baseOptions, fetch: fetchMock });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.deleted", { id: "prod_1" });
+        const [, init] = fetchMock.mock.calls[1];
+        expect(init.method).toBe("POST");
+        const body = JSON.parse(init.body ?? "{}");
+        expect(body).toEqual({ mutations: [{ delete: { id: "sn_50" } }] });
+    });
+    it("applies a custom mapEvent function", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_1", operation: "create" }] }));
+        const bus = createEventBus();
+        const plugin = sanityCmsPlugin({
+            ...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({
+            mutations: [
+                {
+                    create: {
+                        _type: "product",
+                        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 = sanityCmsPlugin({ ...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 Sanity 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 = sanityCmsPlugin({
+            ...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('[sanity-cms] upsert on "product.created" failed for prod_1');
+    });
+    it("uses a custom documentType for the Sanity document", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }))
+            .mockResolvedValueOnce(jsonResponse(200, { results: [{ id: "sn_1", operation: "create" }] }));
+        const bus = createEventBus();
+        const plugin = sanityCmsPlugin({
+            ...baseOptions,
+            documentType: "tour",
+            fetch: fetchMock,
+        });
+        registerPlugins([plugin], { eventBus: bus });
+        await bus.emit("product.created", { id: "prod_1", name: "X" });
+        // find query uses $type=tour
+        const [findUrl] = fetchMock.mock.calls[0];
+        expect(findUrl).toContain("$type=%22tour%22");
+        // create payload uses _type: "tour"
+        const [, createInit] = fetchMock.mock.calls[1];
+        const body = JSON.parse(createInit.body ?? "{}");
+        expect(body.mutations[0].create._type).toBe("tour");
+    });
+    it("does not mutate if the doc is missing on product.deleted", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse(200, { result: null }));
+        const bus = createEventBus();
+        const plugin = sanityCmsPlugin({ ...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-sanity-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"
+}