@render-lab/tasks-sanity

⚠️ Experimental: proof of concept. This package is part of the Render Tasks POC and is published for testing only. It is not fully tested or production ready. Task names, inputs, outputs, and behavior can change or break in any release. Pin exact versions and expect breaking changes.

Durable Sanity tasks for Render Workflows.

import {
  query,
  getDocument,
  getDocuments,
  createDocument,
  patchDocument,
  deleteDocument,
  deleteByQuery,
  mutate,
  uploadAsset,
  deleteAsset,
} from "@render-lab/tasks-sanity";

| Task | Input | Output | | ----------------------- | ----------------------------------------------------------- | ------------------- | | sanity.query | { query, params? } | { result } | | sanity.getDocument | { id } | SanityDocument \| null | | sanity.getDocuments | { ids } | { documents } | | sanity.createDocument | { document, mode? } | SanityDocument | | sanity.patchDocument | { id, set?, setIfMissing?, unset?, inc?, dec?, ifRevisionId? } | SanityDocument | | sanity.deleteDocument | { id } | { deletedIds } | | sanity.deleteByQuery | { query, params? } | { deletedIds } | | sanity.mutate | { mutations } | { transactionId, results } | | sanity.uploadAsset | { assetType, base64, contentType, filename? } | AssetDTO | | sanity.deleteAsset | { id } | { deletedIds } |

A SanityDocument is an open JSON object carrying at least _id and _type; other fields are your content model. AssetDTO is { _id, url, assetType, contentType, size, originalFilename }. Query and multi-get results are byte-bounded against the Render Workflows 4 MB task-result cap before they are returned.

query runs a GROQ query with named $params. getDocument/getDocuments read by id (multi-get preserves order, with null for absent ids). createDocument writes a document — mode is createOrReplace (default, idempotent), createIfNotExists (idempotent), or create (which requires a caller-supplied _id). patchDocument applies a targeted patch. deleteDocument/deleteByQuery remove documents. mutate submits a raw transaction of mutations atomically — the full-fidelity primitive the write tasks wrap. uploadAsset/deleteAsset manage image and file assets.

Idempotency & retries

Reads and idempotent writes (createOrReplace, createIfNotExists, set/setIfMissing/unset patches, deletes, hash-deduped asset uploads) run under SANITY_RETRY and converge on replay. A bare create requires a _id so the write stays identifiable, and inc/dec patches are not idempotent — pass ifRevisionId for optimistic locking where replay-safety matters. mutate inherits the retry-safety of whatever mutations you put in it.

Install

pnpm add @render-lab/tasks-sanity @renderinc/sdk

@renderinc/sdk is a peer dependency. @render-lab/triggers is an optional peer, needed only if you use the webhook adapter. The default port wraps @sanity/client with useCdn: false and maxRetries: 0 (the durable task retry owns retries, ADR-0005).

Environment contract

| Variable | Required | Purpose | | ---------------------- | -------- | ------------------------------------------------------------------------------ | | SANITY_PROJECT_ID | yes | Sanity project id. Read lazily on first API call, never at import. | | SANITY_DATASET | yes | Dataset name (e.g. production). Read lazily on first API call. | | SANITY_API_TOKEN | yes | Token with read+write access (writes and fresh/private reads). Read lazily. | | SANITY_API_VERSION | no | API version date (default v2025-02-19). | | SANITY_WEBHOOK_SECRET| no | Signing secret for the webhook adapter. Read lazily at verify time. |

A missing required var throws a clear error from the task that needs it (fail-close, ADR-0007). Any non-2xx response throws so the durable retry (SANITY_RETRY) is the single source of truth for retries (ADR-0005).

Webhooks

Sanity delivers GROQ-powered webhooks signed with HMAC-SHA256. The adapter lives at a registration-free subpath (ADR-0017) and never calls task() or constructs a client:

import { sanityAdapter } from "@render-lab/tasks-sanity/webhooks";

const adapter = sanityAdapter({
  // secret defaults to SANITY_WEBHOOK_SECRET
  onEvent: ({ payload }) =>
    payload._type === "post"
      ? { task: "content.enrich", args: [{ id: payload._id }] }
      : null,
});

verify checks the sanity-webhook-signature header (t=<ts>,v1=<base64url>, HMAC-SHA256 over `${t}.${rawBody}`) in constant time. map runs your onEvent routing over the projected payload — the body shape is whatever your webhook's GROQ projection emits.

Extending & testing

Every operation exports the wrapped task and its raw *Impl. The impls depend on a small SanityPort interface, so they unit-test without touching the network:

import { patchDocumentImpl, type SanityPort } from "@render-lab/tasks-sanity";

const sanity = { patch: async () => ({ _id: "post_1", _type: "post", title: "New" }) } as SanityPort;
await patchDocumentImpl({ id: "post_1", set: { title: "New" } }, { sanity });

Run the tests with pnpm -C packages/tasks-sanity test.