@sponson/adapters 0.9.2 → 0.10.0

package/recipes/mailgun.yaml

@@ -0,0 +1,186 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Mailgun API recipes: an account webhook and an inbound route per preview. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: mailgun
+title: Mailgun
+category: email
+verified_on: "2026-10-12"
+docs:
+  - title: Mailgun API OpenAPI document (every operation and schema below)
+    url: https://documentation.mailgun.com/_bundle/docs/mailgun/api-reference/send/mailgun.yaml
+  - title: Authentication (HTTP Basic, user `api`)
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/
+  - title: Account Webhooks
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks
+  - title: Create an account-level webhook
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks/post-v1-webhooks
+  - title: Get account-level webhook by ID
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks/get-v1-webhooks--webhook-id-
+  - title: Update an account-level webhook
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks/put-v1-webhooks--webhook-id-
+  - title: Domain Webhooks (the v3 and v4 per-domain alternatives)
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-webhooks
+  - title: Routes
+    url: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes
+  - title: Route actions
+    url: https://documentation.mailgun.com/docs/mailgun/user-manual/receive-forward-store/route-actions
+api:
+  base_url: https://api.mailgun.net
+  base_url_env: MAILGUN_API_URL
+  auth: { basic: { user: api, password_env: MAILGUN_API_KEY } }
+  encoding: form
+  # Lists go as the key repeated (`action=…&action=…`, `event_types=…&event_types=…`): MG4.
+  form_arrays: repeat
+credential:
+  url: "https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/"
+  scope: "An account API key (Account Settings > API Keys): Domain Sending Keys 'only allow sending messages' and cannot manage webhooks or routes."
+  source: "https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/"
+  verify: "GET /v1/webhooks"
+detect:
+  deps: [mailgun.js, mailgun-js]
+  env: ["MAILGUN_*"]
+  starter:
+    - op: webhook
+      preview_url: url
+      values: { name: "sponson-${ctx.env}-${ctx.scope}" }
+      check: [path]
+assumptions:
+  - id: MG1
+    verified: true
+    text: "Requests authenticate with HTTP Basic, the user name `api` and an API key as the password; the US API is `https://api.mailgun.net`, the EU one `https://api.eu.mailgun.net` (an EU account sets `base_url` in the provider block)."
+    source: https://documentation.mailgun.com/_bundle/docs/mailgun/api-reference/send/mailgun.yaml
+  - id: MG2
+    verified: true
+    text: "`POST /v1/webhooks` creates an account-level webhook from `url` (required), `event_types` (required, one of accepted, clicked, opened, unsubscribed, delivered, permanent_fail, temporary_fail, complained; repeated for several) and `description`, and answers `{ webhook_id }` only; it receives the events of every domain of the account. At most three URLs per event type (a fourth answers 409 'unable to add more than 3 urls for event type …'), so at most three previews (fewer when the account has its own webhooks) can each have one at a time."
+    source: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks/post-v1-webhooks
+  - id: MG3
+    verified: true
+    text: "`GET /v1/webhooks` answers `{ webhooks: [...] }` and `GET /v1/webhooks/{webhook_id}` one webhook, each with `webhook_id`, `description`, `url`, `event_types` (a list) and `created_at`; `PUT /v1/webhooks/{webhook_id}` replaces url, description and event types whole (204), `DELETE` on the same path removes it (204), and an unknown id answers 404."
+    source: https://documentation.mailgun.com/_bundle/docs/mailgun/api-reference/send/mailgun.yaml
+  - id: MG4
+    verified: true
+    text: "Lists in request bodies are the key repeated: the OpenAPI document declares `action` with `style: form, explode: true` and says to use `event_types` 'multiple times to specify multiple event types', hence `form_arrays: repeat`."
+    source: https://documentation.mailgun.com/_bundle/docs/mailgun/api-reference/send/mailgun.yaml
+  - id: MG5
+    verified: false
+    text: "The account-webhook operations, documented as `multipart/form-data`, accept the same fields `application/x-www-form-urlencoded`, as Mailgun's v3 operations (documented so) do."
+  - id: MG6
+    verified: true
+    text: "Webhook changes 'can take up to 10 minutes to become effective due to caching': a new preview may miss its first events."
+    source: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks
+  - id: MG7
+    verified: true
+    text: "Routes are account-wide ('defined globally, per account, not per domain'). `POST /v3/routes` takes `priority` (default 0, lower first), `description`, `expression` (required) and `action` (repeated), and answers `{ message, route }`; `GET /v3/routes/{id}` answers `{ route }` (404 when unknown); `GET /v3/routes` answers `{ total_count, items }`, `limit` up to 1000; `PUT /v3/routes/{id}` updates only the fields sent and answers `{ message, route }`; `DELETE /v3/routes/{id}` removes it. A route object carries `id`, `priority`, `description`, `expression`, `actions` (a list) and `created_at`."
+    source: https://documentation.mailgun.com/_bundle/docs/mailgun/api-reference/send/mailgun.yaml
+  - id: MG8
+    verified: true
+    text: "`forward(\"https://…\")` posts a matching message to the URL; every route is evaluated unless a higher-priority one runs `stop()`; `match_recipient('regex')` filters on the recipient. The receiving domain needs its MX records pointing at Mailgun."
+    source: https://documentation.mailgun.com/docs/mailgun/user-manual/receive-forward-store/route-actions
+  - id: MG9
+    verified: false
+    text: "The API answers `description`, `url`, `event_types`, `expression` and `actions` as they were written, so an unchanged webhook or route hashes the same on every plan, and a route's description (not required to be unique by Mailgun) or a webhook's identifies what this recipe made: two equal ones make `find` refuse with PARAM_INVALID."
+  - id: MG10
+    verified: false
+    text: "A per-domain webhook (v3 `…/domains/{domain}/webhooks/{event}`, a list of up to three URLs per event; v4 `…/webhooks?url=`, answered as a map of event to URLs) is not an object of its own that a later run can read back by an id, so this recipe uses account webhooks; the preview's handler must ignore events of mail it did not send (every webhook gets every domain's events)."
+ops:
+  webhook:
+    kind: resource
+    title: Account webhook
+    summary: "An account-level webhook that posts the chosen email events to the preview's own URL, `url` + `path` (usually `{ from: web.preview_url }`). Identified by its description (`name`), so a new preview URL updates it in place. It receives every domain's events (MG10), and Mailgun takes at most three URLs per event type (MG2): at most three previews at a time. A console edit of its URL or events is drift."
+    covers: [mailgun-webhook-route]
+    params:
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_.:/ -]{1,200}$"
+        description: "The webhook's identity, kept as its description: unique per preview, such as `sponson-${ctx.env}-${ctx.scope}`."
+        example: "sponson-${ctx.env}-${ctx.scope}"
+      url:
+        type: string
+        required: true
+        pattern: "^https://\\S*[^/]$"
+        description: "The preview's base URL, without a trailing slash: usually `{ from: <deploy line>.preview_url }`."
+        example: https://pr-42.preview.example.com
+      path:
+        type: string
+        default: /api/webhooks/mailgun
+        pattern: "^/\\S*$"
+        description: "Where the app handles Mailgun's events, appended to `url`."
+      event_types:
+        type: list
+        default: [delivered, permanent_fail, complained]
+        description: "The events posted: accepted, clicked, opened, unsubscribed, delivered, permanent_fail, temporary_fail, complained (MG2)."
+    http:
+      find:
+        path: /v1/webhooks
+        list_path: /webhooks
+        match: { description: { param: name } }
+      read: { path: "/v1/webhooks/{id}" }
+      create: { path: /v1/webhooks, locate: true }
+      update: { method: PUT, path: "/v1/webhooks/{id}" }
+      id_path: /webhook_id
+      fields:
+        url: { join: [{ param: url }, { param: path }] }
+        event_types: { param: event_types }
+  route:
+    kind: resource
+    title: Inbound route
+    summary: "An inbound route per preview that forwards mail matching `expression` (such as `match_recipient('pr-42@inbound.example.com')`) to the preview's own URL, `url` + `path`. Identified by its description (`name`); a console edit of its priority, expression or action is drift. The receiving domain is long-lived and shared (MX records at Mailgun, MG8); each preview gets its own address on it."
+    covers: [mailgun-webhook-route]
+    params:
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_.:/ -]{1,200}$"
+        description: "The route's identity, kept as its description: unique per preview, such as `sponson-${ctx.env}-${ctx.scope}`."
+        example: "sponson-${ctx.env}-${ctx.scope}"
+      expression:
+        type: string
+        required: true
+        description: "The filter (MG8), such as `match_recipient('${ctx.scope}@inbound.example.com')`."
+        example: "match_recipient('${ctx.scope}@inbound.example.com')"
+      url:
+        type: string
+        required: true
+        pattern: "^https://\\S*[^/\"]$"
+        description: "The preview's base URL, without a trailing slash: usually `{ from: <deploy line>.preview_url }`."
+        example: https://pr-42.preview.example.com
+      path:
+        type: string
+        default: /api/inbound/mailgun
+        pattern: "^/[^\\s\"]*$"
+        description: "Where the app receives forwarded mail, appended to `url`."
+      priority:
+        type: integer
+        default: 0
+        description: "Lower runs first (MG7)."
+    http:
+      find:
+        path: "/v3/routes?limit=1000"
+        list_path: /items
+        match: { description: { param: name } }
+      read: { path: "/v3/routes/{id}" }
+      create:
+        path: /v3/routes
+        send_fields: false
+        body:
+          priority: { param: priority }
+          description: { param: name }
+          expression: { param: expression }
+          action: [{ join: ["forward(\"", { param: url }, { param: path }, "\")"] }]
+      update:
+        method: PUT
+        path: "/v3/routes/{id}"
+        send_fields: false
+        body:
+          priority: { param: priority }
+          description: { param: name }
+          expression: { param: expression }
+          action: [{ join: ["forward(\"", { param: url }, { param: path }, "\")"] }]
+      item_path: /route
+      fields:
+        priority: { param: priority }
+        expression: { param: expression }
+        actions: [{ join: ["forward(\"", { param: url }, { param: path }, "\")"] }]
+    sim:
+      write_fields: { action: actions }

package/recipes/newrelic.yaml

@@ -0,0 +1,108 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# New Relic NerdGraph recipes: a change-tracking deployment marker per release. Format and checklist:
+# docs/adr/0020-recipes.md, docs/adr/0022-one-off-actions.md, CONTRIBUTING.md "Adding a recipe".
+provider: newrelic
+title: New Relic
+category: observability
+verified_on: "2026-10-12"
+docs:
+  - title: Track changes with NerdGraph (changeTrackingCreateDeployment, changeTrackingCreateEvent)
+    url: https://docs.newrelic.com/docs/change-tracking/change-tracking-graphql/
+  - title: Introduction to NerdGraph (endpoints, the API-Key header)
+    url: https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/
+  - title: New Relic's Go client, the mutation as its CLI and Terraform provider send it (ChangeTrackingDeploymentInput)
+    url: https://github.com/newrelic/newrelic-client-go/blob/main/pkg/changetracking/changetracking_api.go
+  - title: User keys
+    url: https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/
+api:
+  base_url: https://api.newrelic.com/graphql
+  base_url_env: NEW_RELIC_API_URL
+  auth: { header: API-Key, value_env: NEW_RELIC_API_KEY }
+credential:
+  url: "https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/"
+  scope: "A user key (`NRAK-…`, API keys > Create a key > User) of a user who can create change tracking events for the entity's account."
+  source: "https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/"
+detect:
+  deps: [newrelic, "@newrelic/"]
+  env: ["NEW_RELIC_*"]
+  starter:
+    - op: deployment
+      values: { version: "${ctx.git.sha}", description: "${ctx.env} ${ctx.scope}" }
+  where:
+    entity_guid: "the GUID of the APM (or browser) entity the environment reports as: the entity's metadata in New Relic, or `newrelic entity search`"
+assumptions:
+  - id: NR1
+    verified: true
+    text: "NerdGraph is one GraphQL endpoint, `https://api.newrelic.com/graphql` (EU accounts: `https://api.eu.newrelic.com/graphql`, set `base_url` in the provider block), taking a user key in the `API-Key` header and a JSON body `{ query, variables }`."
+    source: https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/
+  - id: NR2
+    verified: true
+    text: "`changeTrackingCreateDeployment(deployment: ChangeTrackingDeploymentInput!)` records a deployment marker on an entity from `version` and `entityGuid` (both required) and optionally `user`, `description`, `deploymentType` (`BASIC`, `BLUE_GREEN`, `CANARY`, `ROLLING`, `SHADOW`, `OTHER`), `deepLink`, `commit`, `changelog`, `groupId` and `timestamp` (within 24 hours of now), and answers `deploymentId` and `entityGuid`. New Relic recommends `changeTrackingCreateEvent` for new work but says this mutation 'isn't being retired and continues to work'."
+    source: https://docs.newrelic.com/docs/change-tracking/change-tracking-graphql/
+  - id: NR3
+    verified: true
+    text: "The input type's name is `ChangeTrackingDeploymentInput`, as New Relic's own Go client declares the mutation's variable."
+    source: https://github.com/newrelic/newrelic-client-go/blob/main/pkg/changetracking/changetracking_api.go
+  - id: NR4
+    verified: false
+    text: "NerdGraph has no mutation that deletes or edits a deployment marker (the REST v2 deployment endpoints, which could delete one, reach end of life on 2027-07-31), so destroy sends nothing and forgets the record: a marker is history."
+  - id: NR5
+    verified: false
+    text: "NerdGraph takes no idempotency key: a marker sent again after a crash before Sponson recorded it is a second marker for the same version (harmless, at least once)."
+  - id: NR6
+    verified: false
+    text: "A preview that reports to its own entity (an app name per environment, such as `web (preview)`) gets its markers there; a preview sharing production's entity would mark production's charts, so give previews their own entity or leave this line to production."
+ops:
+  deployment:
+    kind: action
+    title: Deployment marker
+    summary: "A change-tracking deployment marker on the environment's entity (`entity_guid`) for a release, sent once per entity and version (usually the commit). Nothing to undo: markers are history and NerdGraph deletes none (NR4)."
+    covers: [newrelic-deployment]
+    params:
+      entity_guid:
+        type: string
+        required: true
+        description: The GUID of the entity the environment reports as (NR6).
+        example: MXxBUE18QVBQTElDQVRJT058MTIzNDU2Nzg
+      version:
+        type: string
+        required: true
+        description: "The release's version, usually the commit: `\"${ctx.git.sha}\"`. A new one sends a new marker."
+        example: "${ctx.git.sha}"
+      description:
+        type: string
+        description: "Text shown with the marker, such as `preview pr-42`."
+        example: "${ctx.env} ${ctx.scope}"
+      user:
+        type: string
+        default: sponson
+        description: Who deployed.
+      commit:
+        type: string
+        description: The commit deployed.
+      deep_link:
+        type: string
+        pattern: "^https?://\\S+$"
+        description: A link to the deployment (the preview URL, or the CI run).
+      deployment_type:
+        type: string
+        default: BASIC
+        enum: [BASIC, BLUE_GREEN, CANARY, ROLLING, SHADOW, OTHER]
+        description: The kind of deployment (NR2).
+    http:
+      trigger: { entity_guid: { param: entity_guid }, version: { param: version } }
+      request:
+        graphql:
+          query: "mutation ($deployment: ChangeTrackingDeploymentInput!) { changeTrackingCreateDeployment(deployment: $deployment) { deploymentId entityGuid } }"
+          variables:
+            deployment:
+              entityGuid: { param: entity_guid }
+              version: { param: version }
+              description: { param: description }
+              user: { param: user }
+              commit: { param: commit }
+              deepLink: { param: deep_link }
+              deploymentType: { param: deployment_type }
+      outputs: { deployment_id: /changeTrackingCreateDeployment/deploymentId }
+    live:
+      params: { entity_guid: SPONSON_LIVE_NEW_RELIC_ENTITY_GUID }

package/recipes/rollbar.yaml

@@ -0,0 +1,94 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Rollbar API recipes: a deploy per release in the environment. Format and checklist: docs/adr/0020-recipes.md,
+# docs/adr/0022-one-off-actions.md, CONTRIBUTING.md "Adding a recipe".
+provider: rollbar
+title: Rollbar
+category: observability
+verified_on: "2026-10-12"
+docs:
+  - title: Report a deploy
+    url: https://docs.rollbar.com/reference/post-deploy
+  - title: Deploy tracking
+    url: https://docs.rollbar.com/docs/deploy-tracking
+  - title: Project access tokens and their scopes
+    url: https://docs.rollbar.com/docs/access-tokens
+  - title: API reference index (deploy endpoints)
+    url: https://docs.rollbar.com/llms.txt
+api:
+  base_url: https://api.rollbar.com/api/1
+  base_url_env: ROLLBAR_API_URL
+  auth: { header: X-Rollbar-Access-Token, value_env: ROLLBAR_ACCESS_TOKEN }
+credential:
+  url: "https://docs.rollbar.com/docs/access-tokens"
+  scope: "A project access token with the `post_server_item` scope ('Can perform all POST requests to /deploy/ and /item/')."
+  source: "https://docs.rollbar.com/reference/post-deploy"
+detect:
+  deps: [rollbar, "@rollbar/"]
+  env: ["ROLLBAR_*"]
+  starter:
+    - op: deploy
+      values: { environment: "${ctx.env}", revision: "${ctx.git.sha}", comment: "${ctx.scope}" }
+assumptions:
+  - id: RB1
+    verified: true
+    text: "`POST https://api.rollbar.com/api/1/deploy` records a deploy from `environment` and `revision` (required), `rollbar_username`, `local_username`, `comment` and `status` (`started`, `succeeded` by default, `failed`, `timed_out`), authenticated by a project access token with the `post_server_item` scope in `X-Rollbar-Access-Token`, and answers 200 with `data.deploy_id`, an integer."
+    source: https://docs.rollbar.com/reference/post-deploy
+  - id: RB2
+    verified: false
+    text: "The token in the header is enough: the reference also lists `access_token` as a body field, which this recipe does not send (a credential in a body would be part of what the request logs show)."
+  - id: RB3
+    verified: true
+    text: "The API reference has report, get, update and list operations for deploys and none that deletes one, so destroy sends nothing and forgets the record: a deploy is history."
+    source: https://docs.rollbar.com/llms.txt
+  - id: RB4
+    verified: false
+    text: "Rollbar takes no idempotency key for deploys: one sent again after a crash before Sponson recorded it is a second deploy of the same revision (harmless, at least once)."
+  - id: RB5
+    verified: false
+    text: "A deploy is attributed to errors of the environment of the same name that the SDK reports (`environment` in its configuration), so a preview's deploys stay apart from production's when the preview's SDK reports its own environment, such as `preview`."
+ops:
+  deploy:
+    kind: action
+    title: Deploy
+    summary: "A deploy of the release's revision in the environment's Rollbar `environment` (such as `preview`), sent once per environment and revision, so errors are attributed to the deploy. Nothing to undo: Rollbar deletes no deploys (RB3)."
+    covers: [rollbar-deploy]
+    params:
+      environment:
+        type: string
+        required: true
+        description: "The Rollbar environment the deployment's SDK reports, such as `${ctx.env}` (RB5)."
+        example: "${ctx.env}"
+      revision:
+        type: string
+        required: true
+        description: "The revision deployed, usually the commit: `\"${ctx.git.sha}\"`. A new one sends a new deploy."
+        example: "${ctx.git.sha}"
+      comment:
+        type: string
+        description: "Text shown with the deploy, such as the scope."
+        example: "${ctx.scope}"
+      local_username:
+        type: string
+        default: sponson
+        description: Who deployed.
+      rollbar_username:
+        type: string
+        description: A Rollbar user to attribute the deploy to.
+      status:
+        type: string
+        default: succeeded
+        enum: [started, succeeded, failed, timed_out]
+        description: The deploy's status.
+    http:
+      trigger: { environment: { param: environment }, revision: { param: revision } }
+      request:
+        method: POST
+        path: /deploy
+        body:
+          environment: { param: environment }
+          revision: { param: revision }
+          comment: { param: comment }
+          local_username: { param: local_username }
+          rollbar_username: { param: rollbar_username }
+          status: { param: status }
+      outputs: { deploy_id: /data/deploy_id }

package/recipes/sanity.yaml

@@ -0,0 +1,163 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Sanity (Content Lake) Projects API recipes, authenticated by a robot token. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: sanity
+title: Sanity
+category: cms
+verified_on: "2026-10-12"
+docs:
+  - title: Projects API reference (datasets, CORS origins)
+    url: https://www.sanity.io/docs/http-reference/projects-api
+  - title: Datasets (naming rules, plan limits, environments)
+    url: https://www.sanity.io/docs/content-lake/datasets
+  - title: CORS origins (preview deployments)
+    url: https://www.sanity.io/docs/content-lake/cors
+  - title: HTTP API authentication (robot tokens)
+    url: https://www.sanity.io/docs/content-lake/http-auth
+  - title: Cloud Clone (dataset copy)
+    url: https://www.sanity.io/docs/content-lake/how-to-use-cloud-clone-for-datasets
+  - title: CLI configuration (SANITY_AUTH_TOKEN)
+    url: https://www.sanity.io/docs/cli-reference/cli-config
+  - title: Pricing (datasets per plan)
+    url: https://www.sanity.io/pricing
+api:
+  base_url: https://api.sanity.io/v2021-06-07
+  base_url_env: SANITY_API_URL
+  auth: { bearer_env: SANITY_AUTH_TOKEN }
+credential:
+  url: "https://www.sanity.io/manage"
+  scope: "A robot token of the project (API → Tokens) with the Administrator role, or Developer on Growth and Enterprise: editors cannot create datasets, and CORS origins are project settings."
+  source: "https://www.sanity.io/docs/http-reference/projects-api"
+detect:
+  deps: [sanity, "@sanity/client", next-sanity]
+  files: [sanity.config.ts, sanity.config.js, sanity.cli.ts, sanity.cli.js]
+  env: ["SANITY_*"]
+  starter:
+    - op: cors_origin
+      preview_url: origin
+    - op: dataset
+      values: { name: "preview-${ctx.scope}" }
+  where:
+    project_id: "`projectId` in sanity.config.ts or sanity.cli.ts (`SANITY_STUDIO_PROJECT_ID`), or sanity.io/manage"
+assumptions:
+  - id: SN1
+    verified: true
+    text: "The Projects API is served at `https://api.sanity.io/<version>` (default `v2021-06-07`) and authenticates with a robot token as `Authorization: Bearer`; the Sanity CLI reads a token for unattended use from `SANITY_AUTH_TOKEN`."
+    source: https://www.sanity.io/docs/http-reference/projects-api
+  - id: SN2
+    verified: true
+    text: "Managing a project's datasets and settings needs the Administrator or Developer role (Developer only on Growth and Enterprise); editors can modify existing datasets but cannot create new ones."
+    source: https://www.sanity.io/docs/user-guides/roles
+  - id: SN3
+    verified: true
+    text: "`PUT /projects/{projectId}/datasets/{name}` with an optional `{ aclMode }` (`public`, the default, or `private`, a paid feature) creates an empty dataset and answers 200 with `{ datasetName, aclMode }`, not the dataset itself, so the recipe finds it by name afterwards (`create.locate`)."
+    source: https://www.sanity.io/docs/http-reference/projects-api
+  - id: SN4
+    verified: true
+    text: "`GET /projects/{projectId}/datasets` answers a bare list of `{ name, aclMode, … }`; dataset names are unique in a project."
+    source: https://www.sanity.io/docs/http-reference/projects-api
+  - id: SN5
+    verified: true
+    text: "`DELETE /projects/{projectId}/datasets/{name}` deletes the dataset and its documents and answers `{ deleted: true }`."
+    source: https://www.sanity.io/docs/http-reference/projects-api
+  - id: SN6
+    verified: true
+    text: "A dataset name is 1 to 64 characters of lowercase letters, digits, `-` and `_`, beginning and ending with a letter or digit."
+    source: https://www.sanity.io/docs/content-lake/datasets
+  - id: SN7
+    verified: true
+    text: "Free and Growth plans include 2 datasets (more on Growth cost $999 per dataset per month), and copying a dataset (Cloud Clone, an asynchronous job) is an Enterprise feature; so a dataset per preview is practical on Enterprise, or with one preview dataset at a time below it. This recipe makes an empty dataset; its content is the app's import or seed (application data, not Sponson's), and Cloud Clone copies are not covered."
+    source: https://www.sanity.io/pricing
+  - id: SN8
+    verified: true
+    text: "A browser querying the Content Lake (or a Studio, or the Presentation tool) from an origin must find that origin in the project's CORS origins; preview deployments get a new URL per branch, so the origin cannot be added ahead of time, and unused preview origins should be removed. `https://*.vercel.app` with credentials is unsafe."
+    source: https://www.sanity.io/docs/content-lake/cors
+  - id: SN9
+    verified: true
+    text: "`GET /projects/{projectId}/cors` answers a bare list of `{ id, origin, allowCredentials, createdAt }` with integer ids; `POST /projects/{projectId}/cors` with `{ origin, allowCredentials? }` creates one (201); `DELETE /projects/{projectId}/cors/{id}` deletes it."
+    source: https://www.sanity.io/docs/http-reference/projects-api
+  - id: SN10
+    verified: false
+    text: "No update of a CORS origin or of a dataset's `aclMode` is documented, so neither is compared for drift: `allowCredentials` and `aclMode` are sent when the line creates the object, and only its existence is checked after."
+  - id: SN11
+    verified: false
+    text: "A dataset being deleted (or a `PUT` of a name that exists) answers within the request; nothing waits, and a dataset is usable as soon as the `PUT` returns."
+ops:
+  dataset:
+    kind: resource
+    title: Dataset per preview
+    summary: "An empty Sanity dataset per scope in a project, such as `preview-pr-42`, for the preview to import or seed its content into (SN7: copying production into it is Enterprise's Cloud Clone and is not covered). Located by name; only its existence is compared for drift; destroy deletes the dataset and its documents."
+    covers: [sanity-dataset]
+    params:
+      project_id:
+        type: string
+        required: true
+        pattern: "^[a-z0-9]+$"
+        description: The project id (`projectId` in sanity.config.ts).
+        example: abc123de
+      name:
+        type: string
+        required: true
+        pattern: "^(?!.*[-_]$)[a-z0-9][-_a-z0-9]{0,63}$"
+        description: The dataset's name; its identity in the project (SN6).
+        example: "preview-${ctx.scope}"
+      acl_mode:
+        type: string
+        default: public
+        enum: [public, private]
+        description: "Who may read it without a token: `public` (Sanity's default) or `private` (Growth and up). Sent on create only (SN10)."
+    http:
+      find:
+        path: "/projects/{project_id}/datasets"
+        match: { name: { param: name } }
+      create:
+        method: PUT
+        path: "/projects/{project_id}/datasets/{name}"
+        body: { aclMode: { param: acl_mode } }
+        send_fields: false
+        locate: true
+      delete: { path: "/projects/{project_id}/datasets/{id}" }
+      id_path: /name
+      outputs:
+        name: /name
+    sim:
+      collection: "/projects/{project_id}/datasets"
+    live:
+      params: { project_id: SPONSON_LIVE_SANITY_PROJECT_ID }
+  cors_origin:
+    kind: resource
+    title: CORS origin
+    summary: "The preview deployment's origin in the project's CORS origins (API → CORS origins), so the preview's browser code, an embedded Studio or the Presentation tool can query the Content Lake (SN8). Located by origin; removed on destroy; every other origin is left alone."
+    covers: [sanity-cors]
+    params:
+      project_id:
+        type: string
+        required: true
+        pattern: "^[a-z0-9]+$"
+        description: The project id (`projectId` in sanity.config.ts).
+        example: abc123de
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path or trailing slash: usually `{ from: <deploy line>.preview_url }`."
+        example: "https://${ctx.scope}.preview.example.app"
+      allow_credentials:
+        type: boolean
+        default: false
+        description: "Allow requests with credentials (a token or a login), which a Studio needs; never for a wildcard origin (SN8). Sent on create only (SN10)."
+    http:
+      find:
+        path: "/projects/{project_id}/cors"
+        match: { origin: { param: origin } }
+      create:
+        path: "/projects/{project_id}/cors"
+        body: { allowCredentials: { param: allow_credentials } }
+      delete: { path: "/projects/{project_id}/cors/{id}" }
+    sim:
+      numeric_ids: true
+    console_url:
+      template: "https://www.sanity.io/manage/project/{project_id}/api"
+      source: https://github.com/sanity-io/client/blob/main/src/http/errors.ts
+    live:
+      params: { project_id: SPONSON_LIVE_SANITY_PROJECT_ID }