@farm.js/sanity 0.1.0-beta.104

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,158 @@
+# @farm.js/sanity
+
+Sanity CMS integration for Farm.js applications. It resolves the Sanity client configuration,
+validates it at startup, and receives Sanity webhooks so cached content is invalidated the moment
+an editor publishes.
+
+Farm.js is currently in beta.
+
+## Install
+
+```bash
+pnpm add @farm.js/sanity @sanity/client
+```
+
+`@sanity/client` is a peer dependency so the application and the integration share one client.
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { sanity } from "@farm.js/sanity";
+
+export default defineConfig({
+  integrations: {
+    cms: sanity(),
+  },
+});
+```
+
+With no options, values come from the environment:
+
+| Variable                | Purpose                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `SANITY_PROJECT_ID`     | Project id. `SANITY_STUDIO_PROJECT_ID` is also read.                           |
+| `SANITY_DATASET`        | Dataset. `SANITY_STUDIO_DATASET` is also read.                                 |
+| `SANITY_API_VERSION`    | Optional. `SANITY_STUDIO_API_VERSION` is also read. Defaults to a pinned date. |
+| `SANITY_API_READ_TOKEN` | Optional. A Viewer token, needed for private datasets and drafts.              |
+| `SANITY_WEBHOOK_SECRET` | Required once a webhook is configured.                                         |
+
+A missing project id or dataset fails at startup rather than at the first request.
+
+Note that a dataset which needs a token returns an empty result to an unauthenticated query,
+with no error. If content is missing, check the token before anything else.
+
+## Read content
+
+The application owns the client. Build it once, use it directly, and hand the same object to the
+integration so Farm does not construct a second one.
+
+```ts
+// src/lib/cms.server.ts
+import { createSanityClient, resolveSanityConfig } from "@farm.js/sanity";
+
+export const cms = createSanityClient(resolveSanityConfig({ useCdn: false }));
+```
+
+```ts
+// farm.config.ts
+integrations: {
+  cms: sanity({ instance: cms }),
+}
+```
+
+Wrap queries in `createServerQuery` so results are cached and can be invalidated by key.
+
+```ts
+import { createServerQuery } from "@farm.js/core";
+import { cms } from "./cms.server";
+
+export const postsQuery = createServerQuery({
+  key: () => ["sanity", "post", "list"],
+  staleTime: "5m",
+  handler: () =>
+    cms.fetch(`*[_type == "post"] | order(publishedAt desc) { title, "slug": slug.current }`),
+});
+```
+
+## Invalidate on publish
+
+Sanity can call your application when a document changes. The integration verifies the request
+came from Sanity, then asks the application which cache entries the change affects.
+
+```ts
+sanity({
+  instance: cms,
+  webhook: {
+    onChange(payload) {
+      if (payload._type !== "post") return;
+      const slug = payload.slug as string;
+      return {
+        keys: [
+          ["sanity", "post", "list"],
+          ["sanity", "post", slug],
+        ],
+        paths: ["/posts", `/posts/${slug}`],
+      };
+    },
+  },
+});
+```
+
+`keys` are server query keys. `paths` are route paths whose rendered output should be
+revalidated as well. Return nothing for changes that affect no cached content.
+
+In Sanity, create a webhook under **API > Webhooks**:
+
+- URL: `https://your-app.example/api/sanity/webhook`
+- Trigger on create, update and delete
+- Projection: `{ _id, _type, "slug": slug.current }`
+- Secret: the value of `SANITY_WEBHOOK_SECRET`
+
+The payload passed to `onChange` is whatever the projection returns, so include the fields the
+mapping needs. A document referenced by others can list them, for example
+`"slugs": *[_type == "post" && references(^._id)].slug.current`.
+
+Responses follow what Sanity does next: `401` for a bad signature and `400` for a malformed body
+are not retried, and a `500` from a failing `onChange` is retried.
+
+### Read through the API, not the CDN
+
+Set `useCdn: false` on the client when the webhook drives invalidation. The webhook fires before
+Sanity's CDN has updated, so a refetch through the CDN can return the previous content and cache
+it again for the full `staleTime`. Farm's cache is the cache in this setup; a second one in front
+of it only adds that race.
+
+Leave the CDN on for applications that rely on `staleTime` alone, or for browser side reads.
+
+### Multiple server instances
+
+Farm's data cache lives in memory per process unless a distributed adapter is configured. On a
+serverless platform the webhook reaches one instance and clears only that instance's memory. Use
+an adapter such as `@farm.js/cache-redis` so an invalidation reaches every instance.
+
+## Options
+
+| Option             | Default               | Notes                                                 |
+| ------------------ | --------------------- | ----------------------------------------------------- |
+| `projectId`        | env                   |                                                       |
+| `dataset`          | env                   |                                                       |
+| `apiVersion`       | pinned date           | Exported as `DEFAULT_SANITY_API_VERSION`.             |
+| `token`            | env                   | Server only. Never passed to the browser.             |
+| `useCdn`           | `true`                | Set `false` with webhook invalidation.                |
+| `instance`         |                       | Existing `SanityClient`. Skips credential validation. |
+| `webhook.secret`   | env                   |                                                       |
+| `webhook.path`     | `/api/sanity/webhook` |                                                       |
+| `webhook.onChange` |                       | Maps a payload to `{ keys?, paths? }`.                |
+| `log`              |                       | Integration lifecycle logger.                         |
+
+## Bring your own client
+
+Pass a configured client through `instance` for options the integration does not expose. The
+integration uses that object as is.
+
+```ts
+import { createClient } from "@sanity/client";
+
+sanity({ instance: createClient({ projectId, dataset, apiVersion, perspective: "published" }) });
+```

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedSanityConfig } from "./config.js";
+import { type SanityClient } from "@sanity/client";
+export declare function createSanityClient(config: ResolvedSanityConfig, instance?: SanityClient): SanityClient;
+/**
+ * Webhooks fire before Sanity's CDN updates, so a revalidation fetch through
+ * the CDN re-caches the content it was told to replace.
+ */
+export declare function createFreshSanityClient(client: SanityClient): SanityClient;
+//# 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,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEjE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,EAC5B,QAAQ,CAAC,EAAE,YAAY,GACtB,YAAY,CAYd;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE1E"}

package/dist/client.js

@@ -0,0 +1,21 @@
+import { createClient } from "@sanity/client";
+export function createSanityClient(config, instance) {
+    if (instance)
+        return instance;
+    // Mapped field by field. Spreading config would forward the webhook secret
+    // straight into the Sanity client.
+    return createClient({
+        projectId: config.projectId,
+        dataset: config.dataset,
+        apiVersion: config.apiVersion,
+        useCdn: config.useCdn,
+        ...(config.token ? { token: config.token } : {}),
+    });
+}
+/**
+ * Webhooks fire before Sanity's CDN updates, so a revalidation fetch through
+ * the CDN re-caches the content it was told to replace.
+ */
+export function createFreshSanityClient(client) {
+    return client.withConfig({ useCdn: false });
+}

package/dist/config.d.ts

@@ -0,0 +1,56 @@
+import type { FarmIntegrationLogger, RouteDataCacheKey } from "@farm.js/core";
+import type { SanityClient } from "@sanity/client";
+/** Pinned so query behaviour never changes without a version bump. */
+export declare const DEFAULT_SANITY_API_VERSION = "2026-03-01";
+export interface SanityWebhookChange {
+    /** Server query keys to invalidate, as passed to `createServerQuery`. */
+    keys?: readonly RouteDataCacheKey[];
+    /** Route paths whose rendered output should be revalidated. */
+    paths?: readonly string[];
+}
+export interface SanityWebhookOptions {
+    /** Defaults to `SANITY_WEBHOOK_SECRET`. */
+    secret?: string;
+    /** Defaults to `/api/sanity/webhook`. */
+    path?: string;
+    /**
+     * Maps a changed document to the cache entries it affects. The payload is
+     * whatever projection the webhook is configured with in Sanity.
+     */
+    onChange(payload: Record<string, unknown>): SanityWebhookChange | void | Promise<SanityWebhookChange | void>;
+}
+export interface SanityIntegrationInput {
+    projectId?: string;
+    dataset?: string;
+    apiVersion?: string;
+    token?: string;
+    /**
+     * Defaults to true. Set false when the webhook drives invalidation: the
+     * webhook fires before Sanity's CDN updates, so a CDN read after
+     * invalidation can re-cache the content it was told to replace.
+     */
+    useCdn?: boolean;
+    /** Existing Sanity client. When provided, Farm does not construct its own. */
+    instance?: SanityClient;
+    webhook?: SanityWebhookOptions;
+    log?: FarmIntegrationLogger;
+}
+export interface ResolvedSanityConfig {
+    projectId: string;
+    dataset: string;
+    apiVersion: string;
+    useCdn: boolean;
+    token?: string;
+    webhookSecret?: string;
+}
+/**
+ * Farm copies .env into process.env before evaluating the config file, so the
+ * integration factory can resolve everything it needs up front.
+ */
+export declare function resolveSanityConfig(input: SanityIntegrationInput): ResolvedSanityConfig;
+/**
+ * Validation for Farm. Values are already resolved, so this only reports what
+ * is missing and turns it into a startup error rather than a runtime one.
+ */
+export declare function sanityIntegrationConfig(resolved: ResolvedSanityConfig, input: SanityIntegrationInput): import("@farm.js/core").FarmIntegrationConfigDefinition<ResolvedSanityConfig, import("@farm.js/core").FarmSchema | undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,sEAAsE;AACtE,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,IAAI,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,GAAG,CAAC,EAAE,qBAAqB,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAWD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,sBAAsB,GAAG,oBAAoB,CAYvF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,sBAAsB,iIAY9B"}

package/dist/config.js

@@ -0,0 +1,44 @@
+import { integrationConfig } from "@farm.js/integration-utils";
+/** Pinned so query behaviour never changes without a version bump. */
+export const DEFAULT_SANITY_API_VERSION = "2026-03-01";
+/** First non-empty value among the given variables. */
+function readEnv(...names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Farm copies .env into process.env before evaluating the config file, so the
+ * integration factory can resolve everything it needs up front.
+ */
+export function resolveSanityConfig(input) {
+    return {
+        projectId: input.projectId ?? readEnv("SANITY_PROJECT_ID", "SANITY_STUDIO_PROJECT_ID") ?? "",
+        dataset: input.dataset ?? readEnv("SANITY_DATASET", "SANITY_STUDIO_DATASET") ?? "",
+        apiVersion: input.apiVersion ??
+            readEnv("SANITY_API_VERSION", "SANITY_STUDIO_API_VERSION") ??
+            DEFAULT_SANITY_API_VERSION,
+        useCdn: input.useCdn ?? true,
+        token: input.token ?? readEnv("SANITY_API_READ_TOKEN"),
+        webhookSecret: input.webhook?.secret ?? readEnv("SANITY_WEBHOOK_SECRET"),
+    };
+}
+/**
+ * Validation for Farm. Values are already resolved, so this only reports what
+ * is missing and turns it into a startup error rather than a runtime one.
+ */
+export function sanityIntegrationConfig(resolved, input) {
+    const required = input.instance
+        ? []
+        : ["projectId", "dataset"];
+    if (input.webhook)
+        required.push("webhookSecret");
+    return integrationConfig({
+        label: "Sanity integration",
+        input: resolved,
+        required,
+    });
+}

package/dist/content.d.ts

@@ -0,0 +1,46 @@
+import type { ContentRemoteSource } from "@farm.js/content";
+import type { SanityClient } from "@sanity/client";
+export interface SanityContentSourceOptions {
+    /** GROQ query resolving to an array of documents. */
+    query: string;
+    params?: Record<string, unknown>;
+    /** Existing Sanity client. When provided, Farm does not construct its own. */
+    client?: SanityClient;
+    projectId?: string;
+    dataset?: string;
+    apiVersion?: string;
+    token?: string;
+    /**
+     * Defaults to false here, unlike the integration: content is fetched while
+     * the configuration loads and bundled, so a build wants the freshest
+     * documents rather than the CDN's cached copy.
+     */
+    useCdn?: boolean;
+    /** Names the source in error messages. Defaults to "sanity". */
+    name?: string;
+    /**
+     * Entry identifier per document. Defaults to `slug.current` when present,
+     * falling back to `_id`.
+     */
+    id?: (document: Record<string, unknown>) => string;
+    /** Optional Markdown body per document, for `entry.body` and word counts. */
+    body?: (document: Record<string, unknown>) => string | undefined;
+    /** Development re-fetch cadence in milliseconds. */
+    refreshInterval?: number;
+    /**
+     * Enables `collections.<name>.create/update/delete`. Defaults to
+     * `SANITY_API_WRITE_TOKEN`; without it the source stays read-only.
+     * Keep write tokens server-side only.
+     */
+    writeToken?: string;
+    /** Sanity `_type` for documents made through `create`. Required to create. */
+    createType?: string;
+}
+/**
+ * A `@farm.js/content` source that loads documents from Sanity, so a CMS
+ * collection gets the same schema validation, transforms, and generated
+ * server types as local files. Content is a build-time snapshot; configure a
+ * Sanity webhook against a deploy hook to rebuild on publish.
+ */
+export declare function sanitySource(options: SanityContentSourceOptions): ContentRemoteSource;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD,MAAM,WAAW,0BAA0B;IACzC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IACnD,6EAA6E;IAC7E,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACjE,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CA+HrF"}

package/dist/content.js

@@ -0,0 +1,129 @@
+import { createSanityClient } from "./client.js";
+import { resolveSanityConfig } from "./config.js";
+/**
+ * A `@farm.js/content` source that loads documents from Sanity, so a CMS
+ * collection gets the same schema validation, transforms, and generated
+ * server types as local files. Content is a build-time snapshot; configure a
+ * Sanity webhook against a deploy hook to rebuild on publish.
+ */
+export function sanitySource(options) {
+    if (typeof options?.query !== "string" || !options.query.trim()) {
+        throw new TypeError("sanitySource() requires a GROQ `query` string");
+    }
+    const name = options.name ?? "sanity";
+    const resolveId = options.id ?? defaultDocumentId;
+    // Resolved lazily so importing farm.config.ts without the env set only
+    // fails when the collection actually loads, with an actionable message.
+    let client = options.client;
+    const resolveClient = () => {
+        if (client)
+            return client;
+        const config = resolveSanityConfig({
+            projectId: options.projectId,
+            dataset: options.dataset,
+            apiVersion: options.apiVersion,
+            token: options.token,
+            useCdn: options.useCdn ?? false,
+        });
+        if (!config.projectId || !config.dataset) {
+            throw new Error(`sanitySource(${JSON.stringify(name)}) requires a project id and dataset. Set ` +
+                "SANITY_PROJECT_ID and SANITY_DATASET, pass them to sanitySource(), or supply " +
+                "an existing client through `client`.");
+        }
+        client = createSanityClient(config);
+        return client;
+    };
+    const writeToken = options.writeToken ?? process.env.SANITY_API_WRITE_TOKEN;
+    let writeClient;
+    const resolveWriteClient = () => {
+        if (writeClient)
+            return writeClient;
+        const base = resolveClient();
+        // The write path never reads through the CDN and may need a stronger token.
+        writeClient = base.withConfig({ useCdn: false, ...(writeToken ? { token: writeToken } : {}) });
+        return writeClient;
+    };
+    // Entry ids are slugs by default, but Sanity mutations address `_id`.
+    // Remember the mapping from the last fetch and fall back to a lookup.
+    const documentIds = new Map();
+    const resolveDocumentId = async (id) => {
+        const known = documentIds.get(id);
+        if (known)
+            return known;
+        const bySlug = await resolveWriteClient().fetch("*[slug.current == $id][0]._id", { id });
+        return bySlug ?? id;
+    };
+    const toDocument = (record) => {
+        const id = resolveId(record) || record._id;
+        if (typeof record._id === "string")
+            documentIds.set(id, record._id);
+        const body = options.body?.(record);
+        return { id, data: record, ...(typeof body === "string" ? { body } : {}) };
+    };
+    const writes = writeToken
+        ? {
+            create: async (input) => {
+                if (!options.createType) {
+                    throw new Error(`sanitySource(${JSON.stringify(name)}) needs \`createType\` (the Sanity _type) to create documents`);
+                }
+                const created = await resolveWriteClient().create({
+                    _type: options.createType,
+                    ...input.data,
+                });
+                return toDocument(created);
+            },
+            update: async (id, patch) => {
+                const documentId = await resolveDocumentId(id);
+                const updated = await resolveWriteClient()
+                    .patch(documentId)
+                    .set(patch.data ?? {})
+                    .commit();
+                return toDocument(updated);
+            },
+            delete: async (id) => {
+                await resolveWriteClient().delete(await resolveDocumentId(id));
+            },
+        }
+        : {};
+    return {
+        kind: "remote",
+        name,
+        ...(options.refreshInterval !== undefined ? { refreshInterval: options.refreshInterval } : {}),
+        ...writes,
+        async fetch() {
+            const result = await resolveClient().fetch(options.query, options.params ?? {});
+            if (!Array.isArray(result)) {
+                throw new Error(`sanitySource(${JSON.stringify(name)}) query must resolve to an array of documents; ` +
+                    "wrap single documents in [] in the GROQ projection");
+            }
+            return result.map((document, index) => {
+                if (!document || typeof document !== "object" || Array.isArray(document)) {
+                    throw new Error(`sanitySource(${JSON.stringify(name)}) document at index ${index} is not an object`);
+                }
+                const record = document;
+                const id = resolveId(record);
+                if (typeof id !== "string" || !id) {
+                    throw new Error(`sanitySource(${JSON.stringify(name)}) could not derive an id for the document at ` +
+                        `index ${index}; give documents a slug or pass an \`id\` function`);
+                }
+                if (typeof record._id === "string")
+                    documentIds.set(id, record._id);
+                const body = options.body?.(record);
+                return {
+                    id,
+                    data: record,
+                    ...(typeof body === "string" ? { body } : {}),
+                };
+            });
+        },
+    };
+}
+function defaultDocumentId(document) {
+    const slug = document.slug;
+    if (slug &&
+        typeof slug === "object" &&
+        typeof slug.current === "string") {
+        return slug.current;
+    }
+    return typeof document._id === "string" ? document._id : "";
+}

package/dist/image.d.ts

@@ -0,0 +1,15 @@
+import type { FarmImageLoader } from "@farm.js/core/image";
+export interface SanityImageLoaderOptions {
+    projectId: string;
+    dataset: string;
+}
+/**
+ * A loader for `@farm.js/core/image` that resolves images on the Sanity CDN.
+ *
+ * `src` is either an asset id such as `image-abc-2000x3000-jpg` or a CDN URL
+ * that already carries crop and hotspot parameters. Crop and hotspot live on
+ * the image object and cannot pass through a string, so an app that needs them
+ * builds the base URL with `@sanity/image-url` and hands that in as `src`.
+ */
+export declare function createSanityImageLoader(options: SanityImageLoaderOptions): FarmImageLoader;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,eAAe,CA+B1F"}

package/dist/image.js

@@ -0,0 +1,37 @@
+import { createImageUrlBuilder } from "@sanity/image-url";
+/**
+ * A loader for `@farm.js/core/image` that resolves images on the Sanity CDN.
+ *
+ * `src` is either an asset id such as `image-abc-2000x3000-jpg` or a CDN URL
+ * that already carries crop and hotspot parameters. Crop and hotspot live on
+ * the image object and cannot pass through a string, so an app that needs them
+ * builds the base URL with `@sanity/image-url` and hands that in as `src`.
+ */
+export function createSanityImageLoader(options) {
+    const builder = createImageUrlBuilder(options);
+    return ({ src, width, quality }) => {
+        const w = String(Math.round(width));
+        const q = String(Math.round(quality));
+        // A prebuilt CDN URL already carries crop and hotspot. The builder only
+        // parses asset references, so append the responsive parameters directly.
+        if (/^https?:\/\//.test(src)) {
+            const url = new URL(src);
+            url.searchParams.set("w", w);
+            url.searchParams.set("q", q);
+            url.searchParams.set("auto", "format");
+            // An art-directed URL may already carry fit=crop; only default it.
+            if (!url.searchParams.has("fit"))
+                url.searchParams.set("fit", "max");
+            return url.toString();
+        }
+        return (builder
+            .image(src)
+            .width(Math.round(width))
+            .quality(Math.round(quality))
+            // Let the CDN negotiate WebP or AVIF from the Accept header.
+            .auto("format")
+            // Serve the original when it is smaller than requested instead of upscaling.
+            .fit("max")
+            .url());
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { type SanityIntegrationInput } from "./config.js";
+export declare function sanity(input?: SanityIntegrationInput): import("@farm.js/core").DefinedIntegration<{
+    category: "cms";
+    type: string;
+    instance: import("@sanity/client").SanityClient;
+    config: import("@farm.js/core").FarmIntegrationConfigDefinition<import("./config.js").ResolvedSanityConfig, import("@farm.js/core").FarmSchema | undefined>;
+    log: import("@farm.js/core").FarmIntegrationLogger | undefined;
+    routes: import("@farm.js/core").FarmIntegrationRoute<unknown, unknown, import("@farm.js/core").FarmSchema | undefined>[];
+}, import("@farm.js/core").FarmSchema | undefined>;
+export { createFreshSanityClient, createSanityClient } from "./client.js";
+export { DEFAULT_SANITY_API_VERSION, resolveSanityConfig } from "./config.js";
+export type { ResolvedSanityConfig, SanityIntegrationInput, SanityWebhookChange, SanityWebhookOptions, } from "./config.js";
+export { createSanityImageLoader, type SanityImageLoaderOptions } from "./image.js";
+export { createSanityWebhookRoute, DEFAULT_SANITY_WEBHOOK_PATH } from "./webhook.js";
+export { sanitySource } from "./content.js";
+export type { SanityContentSourceOptions } from "./content.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":"AAEA,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AAGrB,wBAAgB,MAAM,CAAC,KAAK,GAAE,sBAA2B;;;;;;;mDA2BxD;AAED,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+import { defineIntegration } from "@farm.js/core";
+import { createSanityClient } from "./client.js";
+import { resolveSanityConfig, sanityIntegrationConfig, } from "./config.js";
+import { createSanityWebhookRoute } from "./webhook.js";
+export function sanity(input = {}) {
+    const config = resolveSanityConfig(input);
+    // The factory runs while farm.config.ts is evaluated, before Farm validates
+    // integration config, and the client cannot be constructed without these.
+    if (!input.instance && (!config.projectId || !config.dataset)) {
+        throw new Error("Sanity integration requires a project id and dataset. Set SANITY_PROJECT_ID and " +
+            "SANITY_DATASET, pass them to sanity(), or supply an existing client through `instance`.");
+    }
+    // A configured webhook without a secret is reported by `config` at startup,
+    // so the route is only registered once both are present.
+    const routes = input.webhook && config.webhookSecret
+        ? [createSanityWebhookRoute({ ...input.webhook, secret: config.webhookSecret })]
+        : [];
+    return defineIntegration({
+        category: "cms",
+        type: "sanity",
+        instance: createSanityClient(config, input.instance),
+        config: sanityIntegrationConfig(config, input),
+        log: input.log,
+        routes,
+    });
+}
+export { createFreshSanityClient, createSanityClient } from "./client.js";
+export { DEFAULT_SANITY_API_VERSION, resolveSanityConfig } from "./config.js";
+export { createSanityImageLoader } from "./image.js";
+export { createSanityWebhookRoute, DEFAULT_SANITY_WEBHOOK_PATH } from "./webhook.js";
+export { sanitySource } from "./content.js";

package/dist/webhook.d.ts

@@ -0,0 +1,14 @@
+import { type FarmIntegrationRoute, type RouteDataCacheKey } from "@farm.js/core";
+import type { SanityWebhookChange, SanityWebhookOptions } from "./config.js";
+export declare const DEFAULT_SANITY_WEBHOOK_PATH = "/api/sanity/webhook";
+/** The cache operations the route performs. Injected so tests need no cache. */
+export interface SanityWebhookInvalidation {
+    invalidate(key: RouteDataCacheKey): void | Promise<void>;
+    revalidatePath(path: string): void | Promise<void>;
+}
+export interface SanityWebhookRouteOptions extends Omit<SanityWebhookOptions, "secret"> {
+    secret: string;
+}
+export declare function applySanityWebhookChange(change: SanityWebhookChange | void, invalidation?: SanityWebhookInvalidation): Promise<number>;
+export declare function createSanityWebhookRoute(options: SanityWebhookRouteOptions, invalidation?: SanityWebhookInvalidation): FarmIntegrationRoute;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE7E,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AAEjE,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAID,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC;IACrF,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,mBAAmB,GAAG,IAAI,EAClC,YAAY,GAAE,yBAA4C,GACzD,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,EAClC,YAAY,GAAE,yBAA4C,GACzD,oBAAoB,CAgCtB"}

package/dist/webhook.js

@@ -0,0 +1,55 @@
+import { integrationRoute, invalidate, revalidatePath, } from "@farm.js/core";
+import { isValidSignature, SIGNATURE_HEADER_NAME } from "@sanity/webhook";
+export const DEFAULT_SANITY_WEBHOOK_PATH = "/api/sanity/webhook";
+const farmInvalidation = { invalidate, revalidatePath };
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+export async function applySanityWebhookChange(change, invalidation = farmInvalidation) {
+    if (!change)
+        return 0;
+    // The cache reports nothing back, so the count is of distinct targets asked
+    // for, not entries removed. Deduplicate so a repeated key is only requested once.
+    const keys = [...new Map((change.keys ?? []).map((key) => [JSON.stringify(key), key])).values()];
+    const paths = [...new Set(change.paths ?? [])];
+    await Promise.all([
+        ...keys.map((key) => invalidation.invalidate(key)),
+        ...paths.map((path) => invalidation.revalidatePath(path)),
+    ]);
+    return keys.length + paths.length;
+}
+export function createSanityWebhookRoute(options, invalidation = farmInvalidation) {
+    return integrationRoute.post(options.path ?? DEFAULT_SANITY_WEBHOOK_PATH, {
+        // Sanity signs the exact bytes it sent. Parsing first and re-serialising
+        // changes them, so the body has to be read as text and verified before
+        // anything looks at it.
+        rawBody: true,
+        async handler(request) {
+            const rawBody = await request.text();
+            const signature = request.headers.get(SIGNATURE_HEADER_NAME);
+            if (!signature || !(await isValidSignature(rawBody, signature, options.secret))) {
+                return json(401, { error: "Invalid signature" });
+            }
+            let payload;
+            try {
+                payload = JSON.parse(rawBody);
+            }
+            catch {
+                return json(400, { error: "Body is not JSON" });
+            }
+            // Sanity retries on 5xx and gives up on 4xx. A failing mapping is the
+            // app's problem, not the payload's, so it should be retried.
+            try {
+                const change = await options.onChange(payload);
+                const invalidated = await applySanityWebhookChange(change, invalidation);
+                return json(200, { targets: invalidated });
+            }
+            catch {
+                return json(500, { error: "Failed to apply change" });
+            }
+        },
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@farm.js/sanity",
+  "version": "0.1.0-beta.104",
+  "description": "Sanity CMS integration for Farm.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-sanity"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sanity/image-url": "^2.1.1",
+    "@sanity/webhook": "^4.0.4",
+    "@farm.js/core": "0.1.0-beta.104",
+    "@farm.js/integration-utils": "0.1.0-beta.104"
+  },
+  "devDependencies": {
+    "@sanity/client": "^8.4.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7",
+    "@farm.js/content": "0.1.0-beta.0"
+  },
+  "peerDependencies": {
+    "@sanity/client": "^7.0.0 || ^8.0.0",
+    "@farm.js/content": "^0.1.0-beta.0"
+  },
+  "peerDependenciesMeta": {
+    "@farm.js/content": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}