@sponson/adapters 0.4.0 → 0.5.0

package/recipes/qstash.yaml

@@ -0,0 +1,134 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Upstash QStash recipes (its own API and token; Upstash Redis is recipes/upstash.yaml).
+# Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: qstash
+title: Upstash QStash
+category: queues
+verified_on: "2026-10-11"
+docs:
+  - title: Authentication
+    url: https://upstash.com/docs/qstash/api/authentication
+  - title: Create a schedule
+    url: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - title: Get a schedule
+    url: https://upstash.com/docs/qstash/api-reference/schedules/get-a-schedule
+  - title: Delete a schedule
+    url: https://upstash.com/docs/qstash/api-reference/schedules/delete-a-schedule
+  - title: API examples (raw destination URL in the path)
+    url: https://upstash.com/docs/qstash/overall/apiexamples
+  - title: Multi-region (base URLs, tokens)
+    url: https://upstash.com/docs/qstash/howto/multi-region
+api:
+  base_url: https://qstash.upstash.io
+  base_url_env: QSTASH_API_URL
+  auth: { bearer_env: QSTASH_TOKEN }
+detect:
+  deps: ["@upstash/qstash"]
+  env: ["QSTASH_*"]
+  starter:
+    - op: schedule
+      values: { schedule_id: "cron-${ctx.scope}" }
+  where:
+    destination: "the preview's endpoint the schedule calls: its URL plus the path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: QS1
+    verified: true
+    text: "Requests authenticate with the QStash token as `Authorization: Bearer`; the SDKs read it from `QSTASH_TOKEN`."
+    source: https://upstash.com/docs/qstash/api/authentication
+  - id: QS2
+    verified: true
+    text: "Each region (`qstash.upstash.io` = EU, `qstash-us-east-1.upstash.io`) has its own token and its own schedules; the default here is the EU URL, and a US account overrides `base_url` in its block."
+    source: https://upstash.com/docs/qstash/howto/multi-region
+  - id: QS3
+    verified: true
+    text: "`POST /v2/schedules/{destination}` creates a schedule: the cron in `Upstash-Cron`, the method used to call the destination in `Upstash-Method` (default POST), the request body as the message delivered on every run. It answers `{ scheduleId }`."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - id: QS4
+    verified: true
+    text: "With `Upstash-Schedule-Id`, a schedule with that id is updated with the new settings if it exists (an upsert): the id is the client's, the read path names it, and the same request is both create and update."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - id: QS5
+    verified: true
+    text: "The official example writes the destination URL in the path as it is (`/v2/schedules/https://example.com`), hence the `{+destination}` placeholder."
+    source: https://upstash.com/docs/qstash/overall/apiexamples
+  - id: QS6
+    verified: false
+    text: "A destination URL with a query string arrives intact with its `?` escaped as `%3F` (a raw `?` would end the path); not documented."
+  - id: QS7
+    verified: true
+    text: "`GET /v2/schedules/{scheduleId}` answers the schedule bare with `scheduleId`, `cron`, `destination`, `method` and `body`, and 404 when there is none; `DELETE` on the same path removes it."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/get-a-schedule
+  - id: QS8
+    verified: false
+    text: "Deleting a schedule that is already gone answers 404 (only 200 is documented), which destroy treats as done."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/delete-a-schedule
+  - id: QS9
+    verified: true
+    text: "Schedule ids are alphanumerics, hyphens, periods and underscores (400 otherwise); a cron may carry a `CRON_TZ=<zone>` prefix and runs at most once a minute."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - id: QS10
+    verified: false
+    text: "`GET` returns `cron`, `destination` and `method` exactly as they were sent (the cron string unnormalised), so comparing them is not drift on every plan."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/get-a-schedule
+ops:
+  schedule:
+    kind: resource
+    title: Schedule
+    summary: "A cron schedule that calls a preview's URL, such as `/api/cron` of `pr-42`, under a schedule id per scope. Created and updated by the same upsert (QS4); a console edit of its cron, destination or method is drift; destroy deletes it. The message body is sent on create and update but not compared."
+    covers: [qstash-schedule]
+    params:
+      schedule_id:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9._-]+$"
+        description: The schedule's id, chosen by the plan (one per scope).
+        example: "cron-${ctx.scope}"
+      destination:
+        type: string
+        required: true
+        pattern: "^https?://"
+        description: The URL the schedule calls.
+        example: "https://${ctx.scope}.preview.example.com/api/cron"
+      cron:
+        type: string
+        required: true
+        description: "The cron expression, optionally prefixed `CRON_TZ=<zone> `."
+        example: "*/15 * * * *"
+      method:
+        type: string
+        default: POST
+        enum: [GET, POST, PUT, PATCH, DELETE]
+        description: The HTTP method used to call the destination.
+      body:
+        type: map
+        description: The JSON message delivered on every run (sent, not compared).
+    http:
+      read: { path: "/v2/schedules/{schedule_id}" }
+      create:
+        path: "/v2/schedules/{+destination}"
+        headers:
+          Upstash-Schedule-Id: { param: schedule_id }
+          Upstash-Cron: { param: cron }
+          Upstash-Method: { param: method }
+        send_fields: false
+        body: { param: body }
+      update:
+        method: POST
+        path: "/v2/schedules/{+destination}"
+        headers:
+          Upstash-Schedule-Id: { param: schedule_id }
+          Upstash-Cron: { param: cron }
+          Upstash-Method: { param: method }
+        send_fields: false
+        body: { param: body }
+      id_path: /scheduleId
+      fields:
+        cron: { param: cron }
+        destination: { param: destination }
+        method: { param: method }
+    sim:
+      collection: /v2/schedules
+      header_fields: { upstash-schedule-id: scheduleId, upstash-cron: cron, upstash-method: method }
+      suffix_field: destination
+    live:
+      params: { destination: SPONSON_LIVE_QSTASH_DESTINATION }

package/recipes/railway.yaml

@@ -0,0 +1,130 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Railway public GraphQL API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: railway
+title: Railway
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Public API (endpoint, tokens, errors)
+    url: https://docs.railway.com/reference/public-api
+  - title: Manage Variables with the Public API
+    url: https://docs.railway.com/guides/manage-variables
+  - title: Environments (PR environments)
+    url: https://docs.railway.com/reference/environments
+  - title: CLI (RAILWAY_TOKEN and RAILWAY_API_TOKEN)
+    url: https://docs.railway.com/guides/cli
+  - title: railwayapp/cli GraphQL schema
+    url: https://github.com/railwayapp/cli/blob/master/src/gql/schema.json
+api:
+  base_url: https://backboard.railway.com/graphql/v2
+  base_url_env: RAILWAY_API_URL
+  auth: { bearer_env: RAILWAY_API_TOKEN }
+detect:
+  env: ["RAILWAY_*"]
+  files: [railway.json, railway.toml]
+  starter:
+    - op: variable
+  where:
+    project_id: "Railway → your project → Settings → Project ID, or `railway status --json`"
+    environment_id: "the pull request environment Railway created: its Settings, or `railway environment`"
+assumptions:
+  - id: RY1
+    verified: true
+    text: "The public API is one GraphQL endpoint, `https://backboard.railway.com/graphql/v2`; account, workspace and OAuth tokens are sent as `Authorization: Bearer <token>`, project tokens in `Project-Access-Token` instead (a project token therefore needs a hand-written block with `auth: { header: Project-Access-Token, value_env: RAILWAY_TOKEN }`)."
+    source: https://docs.railway.com/reference/public-api
+  - id: RY2
+    verified: true
+    text: "The Railway CLI reads an account or workspace token from `RAILWAY_API_TOKEN` and a project token from `RAILWAY_TOKEN`, so the bearer credential of this recipe is `RAILWAY_API_TOKEN`."
+    source: https://docs.railway.com/guides/cli
+  - id: RY3
+    verified: true
+    text: "Failures may be HTTP 200 with an `errors` array (a denied query among them); 400 is a parse or validation failure, 429 a rate limit with `Retry-After`. Queries are safe to retry; a mutation only when no answer arrived."
+    source: https://docs.railway.com/reference/public-api
+  - id: RY4
+    verified: true
+    text: "`variables(projectId, environmentId, serviceId?, unrendered?)` answers the variables of a service in an environment (without `serviceId`, the environment's shared variables) as a map of name to value; `unrendered: true` answers references such as `${{Postgres.DATABASE_URL}}` as written instead of resolved, so a value is compared as it was set."
+    source: https://docs.railway.com/guides/manage-variables
+  - id: RY5
+    verified: true
+    text: "`variableUpsert(input: { projectId, environmentId, serviceId?, name, value, skipDeploys? })` creates or replaces one variable (without `serviceId`, a shared variable); by default it triggers a redeploy of the service (`skipDeploys` defaults to false)."
+    source: https://docs.railway.com/guides/manage-variables
+  - id: RY6
+    verified: true
+    text: "`variableDelete(input: { projectId, environmentId, serviceId?, name })` deletes one variable."
+    source: https://docs.railway.com/guides/manage-variables
+  - id: RY7
+    verified: true
+    text: "Railway creates a PR environment when a pull request is opened (with PR environments enabled) and deletes it, with its variables, when the pull request is merged or closed. The recipe takes the environment's id as a param: the plan copies it from the dashboard, `railway status`, or a line that outputs it; the recipe does not look environments up by name (their naming is not documented)."
+    source: https://docs.railway.com/reference/environments
+  - id: RY8
+    verified: false
+    text: "Deleting a variable whose environment Railway already removed (the pull request closed) is an error saying the environment was not found, which the adapter reads as already gone; deleting a variable that does not exist answers `true`."
+  - id: RY9
+    verified: false
+    text: "Sponson does not wait for the redeploy a write triggers (RY5): a step that needs the running service to see the value waits on Railway's deployment status itself. A reference value written as `${{…}}` is not supported in a plan, where `${…}` is Sponson's own interpolation."
+ops:
+  variable:
+    kind: resource
+    title: Variable of a service in an environment
+    summary: "One variable of a service (or, without `service_id`, a shared variable) in a Railway environment, typically the PR environment Railway created. Upserted with `variableUpsert`, read unrendered from `variables`, removed with `variableDelete`. A console edit of the value is drift. Railway redeploys the service after each write unless `skip_deploys` is set; Sponson does not wait for that deploy (RY9)."
+    covers: [railway-variables]
+    params:
+      project_id:
+        type: string
+        required: true
+        description: The project's id.
+        example: prj-railway-demo
+      environment_id:
+        type: string
+        required: true
+        description: The environment's id (for a PR environment, the one Railway created for the pull request; RY7).
+        example: env-pr-42
+      service_id:
+        type: string
+        description: The service's id; without it, the variable is shared by the environment's services.
+        example: svc-web
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The variable's value (may be a `{ secret }` reference).
+        example: "https://api-${ctx.scope}.example.app"
+      skip_deploys:
+        type: boolean
+        description: Do not redeploy the service after a write (Railway's default is to redeploy).
+    http:
+      read:
+        graphql:
+          query: "query variables($projectId: String!, $environmentId: String!, $serviceId: String, $unrendered: Boolean) { variables(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId, unrendered: $unrendered) }"
+          variables: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, unrendered: true }
+          data_path: { join: ["/variables/", { param: name }] }
+      create:
+        graphql:
+          query: "mutation variableUpsert($input: VariableUpsertInput!) { variableUpsert(input: $input) }"
+          variables: { input: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, name: { param: name }, value: { param: value }, skipDeploys: { param: skip_deploys } } }
+          idempotent: true
+      update:
+        graphql:
+          query: "mutation variableUpsert($input: VariableUpsertInput!) { variableUpsert(input: $input) }"
+          variables: { input: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, name: { param: name }, value: { param: value }, skipDeploys: { param: skip_deploys } } }
+          idempotent: true
+      delete:
+        graphql:
+          query: "mutation variableDelete($input: VariableDeleteInput!) { variableDelete(input: $input) }"
+          variables: { input: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, name: { param: name } } }
+      fields:
+        value: { param: value }
+    sim:
+      provider: railway
+      seed: { environments: { env-pr-42: { projectId: prj-railway-demo, name: pr-42 } } }
+      present: /variables/env-pr-42~1svc-web/API_URL
+      drift:
+        changed: { vars.env-pr-42.svc-web.API_URL: "https://somewhere-else.example" }
+        missing: { vars.env-pr-42.svc-web.API_URL: delete }
+    live:
+      params: { project_id: SPONSON_LIVE_RAILWAY_PROJECT_ID, environment_id: SPONSON_LIVE_RAILWAY_ENVIRONMENT_ID, service_id: SPONSON_LIVE_RAILWAY_SERVICE_ID }

package/recipes/render.yaml

@@ -0,0 +1,103 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Render API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: render
+title: Render
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Authentication
+    url: https://api-docs.render.com/reference/authentication
+  - title: Retrieve environment variable
+    url: https://api-docs.render.com/reference/retrieve-env-var
+  - title: Add or update environment variable
+    url: https://api-docs.render.com/reference/update-env-var
+  - title: Delete environment variable
+    url: https://api-docs.render.com/reference/delete-env-var
+  - title: Update environment variables (replace all; deploy behaviour)
+    url: https://api-docs.render.com/reference/update-env-vars-for-service
+  - title: Service previews
+    url: https://render.com/docs/service-previews
+  - title: Render CLI (RENDER_API_KEY)
+    url: https://render.com/docs/cli
+api:
+  base_url: https://api.render.com/v1
+  base_url_env: RENDER_API_URL
+  auth: { bearer_env: RENDER_API_KEY }
+detect:
+  env: ["RENDER_*"]
+  files: [render.yaml]
+  starter:
+    - op: env_var
+  where:
+    service_id: "Render Dashboard → the preview service: the `srv-…` id in its URL"
+assumptions:
+  - id: RE1
+    verified: true
+    text: "Requests authenticate with an API key as `Authorization: Bearer`; the Render CLI reads it from `RENDER_API_KEY`."
+    source: https://api-docs.render.com/reference/authentication
+  - id: RE2
+    verified: true
+    text: "`GET /services/{serviceId}/env-vars/{envVarKey}` answers the variable bare, `{ key, value }`, and 404 when it does not exist."
+    source: https://api-docs.render.com/reference/retrieve-env-var
+  - id: RE3
+    verified: true
+    text: "`PUT /services/{serviceId}/env-vars/{envVarKey}` with `{ value }` adds the variable or replaces its value (200, `{ key, value }`): a create whose answer was lost is the same request again, and the variable's name is its identity."
+    source: https://api-docs.render.com/reference/update-env-var
+  - id: RE4
+    verified: true
+    text: "`DELETE /services/{serviceId}/env-vars/{envVarKey}` removes the variable (204)."
+    source: https://api-docs.render.com/reference/delete-env-var
+  - id: RE5
+    verified: false
+    text: "Deleting a variable that is already gone answers 404 (documented only as \"Unable to find the requested resource\"), which destroy treats as done."
+    source: https://api-docs.render.com/reference/delete-env-var
+  - id: RE6
+    verified: true
+    text: "Changing environment variables through the API does not deploy the service, whatever its autoDeploy setting (stated for the replace-all endpoint); a running preview sees a new value only after its next deploy."
+    source: https://api-docs.render.com/reference/update-env-vars-for-service
+  - id: RE7
+    verified: false
+    text: "The single-variable PUT does not deploy either (its page is silent; assumed like the replace-all endpoint)."
+  - id: RE8
+    verified: true
+    text: "Render creates service previews and preview environments itself (per pull request, from the service's Previews setting or `render.yaml`); a preview copies the base service's variables once, when it is created. No API looks up the preview of pull request N, so the line takes the service's id."
+    source: https://render.com/docs/service-previews
+  - id: RE9
+    verified: false
+    text: "`GET` returns the value in plain text for every variable, including ones generated with `generateValue`, so the value can be compared for drift."
+    source: https://api-docs.render.com/reference/retrieve-env-var
+ops:
+  env_var:
+    kind: resource
+    title: Service environment variable
+    summary: "One environment variable on a Render service, such as a preview service's `API_URL`, written by name (`PUT` adds or replaces it). A console edit of its value is drift; destroy deletes it. The service's id is a param: Render creates preview services itself, and writing a variable does not deploy (RE6)."
+    covers: [render-env]
+    params:
+      service_id:
+        type: string
+        required: true
+        pattern: "^[a-z]{3}-[a-z0-9]+$"
+        description: The service's id (`srv-…`, in the service's dashboard URL and settings).
+        example: srv-d0a1b2c3d4e5f6g7h8i9
+      key:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: "The variable's value: a literal, `{ from }` or `{ secret }`."
+        example: "https://api-${ctx.scope}.example.com"
+    http:
+      read: { path: "/services/{service_id}/env-vars/{key}" }
+      create: { method: PUT, path: "/services/{service_id}/env-vars/{key}" }
+      update: { method: PUT }
+      id_path: /key
+      fields:
+        value: { param: value }
+    sim:
+      collection: "/services/{service_id}/env-vars"
+    live:
+      params: { service_id: SPONSON_LIVE_RENDER_SERVICE_ID }

package/recipes/resend.yaml

@@ -0,0 +1,130 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Resend API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: resend
+title: Resend
+category: email
+verified_on: "2026-10-11"
+docs:
+  - title: Create API key
+    url: https://resend.com/docs/api-reference/api-keys/create-api-key
+  - title: List API keys
+    url: https://resend.com/docs/api-reference/api-keys/list-api-keys
+  - title: Delete API key
+    url: https://resend.com/docs/api-reference/api-keys/delete-api-key
+  - title: Create webhook
+    url: https://resend.com/docs/api-reference/webhooks/create-webhook
+  - title: Retrieve webhook
+    url: https://resend.com/docs/api-reference/webhooks/get-webhook
+  - title: List webhooks
+    url: https://resend.com/docs/api-reference/webhooks/list-webhooks
+  - title: Update webhook
+    url: https://resend.com/docs/api-reference/webhooks/update-webhook
+  - title: Delete webhook
+    url: https://resend.com/docs/api-reference/webhooks/delete-webhook
+api:
+  base_url: https://api.resend.com
+  base_url_env: RESEND_API_URL
+  auth: { bearer_env: RESEND_API_KEY }
+detect:
+  deps: [resend]
+  env: ["RESEND_*"]
+  starter:
+    - op: api_key
+      values: { name: "sponson-${ctx.env}-${ctx.scope}" }
+assumptions:
+  - id: RS1
+    verified: true
+    text: "`POST /api-keys` creates an API key from `name` (at most 50 characters), `permission` (`full_access` or `sending_access`) and `domain_id` (with `sending_access` only), answering `{ id, token }`; requests carry `Authorization: Bearer <key>`."
+    source: https://resend.com/docs/api-reference/api-keys/create-api-key
+  - id: RS2
+    verified: true
+    text: "`GET /api-keys` answers `{ object: list, has_more, data: [{ id, name, created_at, last_used_at }] }`, every key when no `limit` is sent, and never the token: the token is shown only in the create answer, so it is a once-only output."
+    source: https://resend.com/docs/api-reference/api-keys/list-api-keys
+  - id: RS3
+    verified: true
+    text: "`DELETE /api-keys/{api_key_id}` removes a key; there is no endpoint to read or change one key, so its permission and domain are sent on create and never compared."
+    source: https://resend.com/docs/api-reference/api-keys/delete-api-key
+  - id: RS4
+    verified: true
+    text: "`POST /webhooks` creates a webhook from `endpoint` and `events` (both required), answering `{ object, id, signing_secret }`."
+    source: https://resend.com/docs/api-reference/webhooks/create-webhook
+  - id: RS5
+    verified: true
+    text: "`GET /webhooks/{webhook_id}` answers the webhook with `status` (`enabled`/`disabled`), `endpoint`, `events` and `signing_secret`: the secret stays readable, so it is an ordinary sensitive output."
+    source: https://resend.com/docs/api-reference/webhooks/get-webhook
+  - id: RS6
+    verified: true
+    text: "`GET /webhooks` answers `{ object: list, has_more, data: [{ id, created_at, status, endpoint, events }] }`, every webhook when no `limit` is sent."
+    source: https://resend.com/docs/api-reference/webhooks/list-webhooks
+  - id: RS7
+    verified: true
+    text: "`PATCH /webhooks/{webhook_id}` changes `endpoint`, `events` and `status`; `DELETE` on the same path removes the webhook."
+    source: https://resend.com/docs/api-reference/webhooks/update-webhook
+  - id: RS8
+    verified: false
+    text: "Key names and webhook endpoints are not unique in Resend: the recipe takes the name (keys) and the endpoint URL (webhooks) as the identity, and refuses (PARAM_INVALID) when two match, so give each environment its own name and URL."
+  - id: RS9
+    verified: false
+    text: "Creating a key or a webhook needs a `full_access` key; a deleted object answers 404."
+ops:
+  api_key:
+    kind: resource
+    title: API key
+    summary: "A restricted API key per environment, such as `sponson-preview-pr-42` allowed only to send from one domain. Its token is a once-only output: pass it to the app's environment line in the same run (`{ from: <line>.token }`); later runs keep what that line holds, and `apply --recreate <line>` issues a new one. Only its existence is compared for drift: Resend shows no permission or domain for a key."
+    covers: [resend-key-webhook]
+    params:
+      name:
+        type: string
+        required: true
+        pattern: "^.{1,50}$"
+        description: The key's name, unique among the account's keys (RS8); its identity.
+        example: "sponson-${ctx.env}-${ctx.scope}"
+      permission:
+        type: string
+        default: sending_access
+        enum: [full_access, sending_access]
+        description: What the key may do.
+      domain_id:
+        type: string
+        description: With `sending_access`, the only domain the key may send from.
+    http:
+      find:
+        path: /api-keys
+        list_path: /data
+        match: { name: { param: name } }
+      create:
+        path: /api-keys
+        body: { permission: { param: permission }, domain_id: { param: domain_id } }
+      delete: { path: "/api-keys/{id}" }
+      outputs:
+        token: { path: /token, sensitive: true, once: true }
+  webhook:
+    kind: resource
+    title: Webhook
+    summary: "A webhook delivering an environment's email events to its URL, such as the preview's `/api/resend` handler. Located by its endpoint URL; a console edit of its events is drift (its enabled/disabled status is left to the console: the create request takes none). Its signing secret is a sensitive output, readable on every run."
+    covers: [resend-key-webhook]
+    params:
+      endpoint:
+        type: string
+        required: true
+        pattern: "^https://\\S+$"
+        description: The URL events are delivered to; its identity (RS8).
+        example: "https://${ctx.scope}.preview.example.com/api/resend"
+      events:
+        type: list
+        required: true
+        description: The event types to deliver, such as `email.delivered` and `email.bounced`.
+        example: [email.delivered, email.bounced]
+    http:
+      find:
+        path: /webhooks
+        list_path: /data
+        match: { endpoint: { param: endpoint } }
+      read: { path: "/webhooks/{id}" }
+      create: { path: /webhooks }
+      update: { method: PATCH, path: "/webhooks/{id}" }
+      delete: { path: "/webhooks/{id}" }
+      fields:
+        events: { param: events }
+      outputs:
+        signing_secret: { path: /signing_secret, sensitive: true }

package/recipes/s3.yaml

@@ -0,0 +1,108 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# S3 API recipes (Amazon S3, and Cloudflare R2 through its S3-compatible endpoint): XML documents, every request
+# signed with AWS Signature Version 4. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: s3
+title: Amazon S3 / Cloudflare R2 (S3 API)
+category: cors
+verified_on: "2026-10-11"
+docs:
+  - title: PutBucketCors
+    url: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html
+  - title: GetBucketCors
+    url: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html
+  - title: DeleteBucketCors
+    url: https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html
+  - title: R2 S3 API compatibility
+    url: https://developers.cloudflare.com/r2/api/s3/api/
+base_url_example: https://assets.s3.us-east-1.amazonaws.com
+api:
+  base_url_env: S3_API_URL
+  encoding: xml
+  auth:
+    aws_sigv4: { region: us-east-1, service: s3, access_key_id_env: AWS_ACCESS_KEY_ID, secret_access_key_env: AWS_SECRET_ACCESS_KEY }
+detect:
+  deps: ["@aws-sdk/client-s3"]
+  starter:
+    - op: bucket_cors
+      preview_url: origin
+      values: { rule_id: "sponson-${ctx.scope}" }
+  where:
+    base_url: "the bucket's endpoint: `https://<bucket>.s3.<region>.amazonaws.com`, or R2's `https://<account id>.r2.cloudflarestorage.com/<bucket>`"
+assumptions:
+  - id: SS1
+    verified: true
+    text: "`PUT /?cors` on the bucket's endpoint replaces its whole CORS configuration with a `CORSConfiguration` document of up to 100 `CORSRule`s (each `ID`, `AllowedOrigin`s, `AllowedMethod`s, `AllowedHeader`s, `ExposeHeader`s, `MaxAgeSeconds`) and requires `Content-MD5`, which the SigV4 signer adds for `s3`."
+    source: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html
+  - id: SS2
+    verified: true
+    text: "`GET /?cors` answers the configuration as XML."
+    source: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html
+  - id: SS3
+    verified: true
+    text: "`DELETE /?cors` removes the configuration (the way to leave a bucket with no rule)."
+    source: https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html
+  - id: SS4
+    verified: true
+    text: "R2 implements PutBucketCors, GetBucketCors and DeleteBucketCors at `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`; its SigV4 region is `auto`, and `us-east-1` is accepted as an alias, so the recipe's region works for R2 unchanged."
+    source: https://developers.cloudflare.com/r2/api/s3/api/
+  - id: SS5
+    verified: false
+    text: "A bucket without a CORS configuration answers 404 `NoSuchCORSConfiguration` (read as an empty list, `parent.if_missing: empty`), and an empty configuration is refused as `MalformedXML` (so the last rule is removed with DELETE, `parent.when_empty: delete`)."
+  - id: SS6
+    verified: false
+    text: "R2 accepts path-style requests (`https://<ACCOUNT_ID>.r2.cloudflarestorage.com/<bucket>/?cors`), so its base URL names the bucket in the path."
+  - id: SS7
+    verified: false
+    text: "S3 answers a rule's elements as they were written; a rule's `ID` identifies it among the bucket's rules (IDs are not required to be unique by S3, so other writers must not reuse the recipe's)."
+ops:
+  bucket_cors:
+    kind: list_item
+    title: CORS rule of a bucket
+    summary: "A CORS rule of an S3 or R2 bucket allowing the preview's origin, identified by its `ID` (such as `sponson-pr-42`); every other rule is left as it is. The base URL names the bucket: `https://<bucket>.s3.<region>.amazonaws.com` (set `auth.aws_sigv4.region` to the bucket's region), or `https://<account>.r2.cloudflarestorage.com/<bucket>` for R2. A console edit of the rule is drift; destroy removes only this rule (the whole configuration when it was the last one)."
+    covers: [s3-r2-cors]
+    params:
+      rule_id:
+        type: string
+        required: true
+        pattern: "^.{1,255}$"
+        description: The rule's `ID`, at most 255 characters; its identity (SS7).
+        example: "sponson-${ctx.scope}"
+      origin:
+        type: string
+        required: true
+        pattern: "^(https?://\\S+|\\*)$"
+        description: The origin allowed (the preview's URL, without a path).
+        example: "https://${ctx.scope}.preview.example.app"
+      methods:
+        type: list
+        default: [GET]
+        description: "The methods allowed: `GET`, `PUT`, `POST`, `DELETE`, `HEAD`."
+      allowed_headers:
+        type: list
+        description: "Request headers a preflight may ask for (`*` for any); absent: none."
+      expose_headers:
+        type: list
+        description: Response headers the browser may read; absent, none.
+      max_age_seconds:
+        type: string
+        default: "3000"
+        pattern: "^[0-9]+$"
+        description: How long a preflight answer may be cached, in seconds (a string, as XML carries it).
+    http:
+      parent: { path: "/?cors", method: PUT, if_missing: empty, when_empty: delete }
+      list_path: /CORSConfiguration/CORSRule
+      key_field: ID
+      item:
+        AllowedHeader: { param: allowed_headers }
+        AllowedMethod: { param: methods }
+        AllowedOrigin: { param: origin }
+        ExposeHeader: { param: expose_headers }
+        ID: { param: rule_id }
+        MaxAgeSeconds: { param: max_age_seconds }
+    sim:
+      provider: aws
+      base_path: /aws/s3/assets
+      seed: { buckets: { assets: { cors: null } } }
+      present: /buckets/assets/cors/0
+      drift:
+        missing: { s3.assets.cors: "remove:sponson-pr-42" }