@sponson/adapters 0.4.0 → 0.6.0

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" }

package/recipes/sendgrid.yaml

@@ -0,0 +1,165 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Twilio SendGrid v3 API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: sendgrid
+title: SendGrid
+category: email
+verified_on: "2026-10-11"
+docs:
+  - title: Create an Event Webhook
+    url: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/create-an-event-webhook
+  - title: Get all Event Webhooks
+    url: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/get-all-event-webhooks
+  - title: Get an Event Webhook
+    url: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/get-an-event-webhook
+  - title: Update an Event Webhook
+    url: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/update-an-event-webhook
+  - title: Delete an Event Webhook
+    url: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/delete-an-event-webhook
+  - title: Create a parse setting
+    url: https://www.twilio.com/docs/sendgrid/api-reference/settings-inbound-parse/create-a-parse-setting
+  - title: Retrieve a specific parse setting
+    url: https://www.twilio.com/docs/sendgrid/api-reference/settings-inbound-parse/retrieve-a-specific-parse-setting
+  - title: Update a parse setting
+    url: https://www.twilio.com/docs/sendgrid/api-reference/settings-inbound-parse/update-a-parse-setting
+  - title: Delete a parse setting
+    url: https://www.twilio.com/docs/sendgrid/api-reference/settings-inbound-parse/delete-a-parse-setting
+api:
+  base_url: https://api.sendgrid.com
+  base_url_env: SENDGRID_API_URL
+  auth: { bearer_env: SENDGRID_API_KEY }
+detect:
+  deps: ["@sendgrid/"]
+  env: ["SENDGRID_*"]
+  starter:
+    - op: event_webhook
+  where:
+    url: "the preview's event handler: its URL plus the handler's path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: SG1
+    verified: true
+    text: "`POST /v3/user/webhooks/event/settings` creates an Event Webhook from `url` (required), `enabled`, one boolean per event type (`processed`, `delivered`, `dropped`, `deferred`, `bounce`, `open`, `click`, `spam_report`, `unsubscribe`, `group_unsubscribe`, `group_resubscribe`) and `friendly_name`, answering 201 with the webhook and its string `id`; requests carry the API key as `Authorization: Bearer`. EU regional subusers use `https://api.eu.sendgrid.com`."
+    source: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/create-an-event-webhook
+  - id: SG2
+    verified: true
+    text: "Each URL can be used by only one Event Webhook (a second create answers 400 naming the existing id), so the URL identifies the webhook; the number of webhooks is limited by the plan (400 beyond it)."
+    source: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/create-an-event-webhook
+  - id: SG3
+    verified: true
+    text: "`GET /v3/user/webhooks/event/settings/all` answers `{ max_allowed, webhooks: [...] }` with every webhook's settings and `id`."
+    source: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/get-all-event-webhooks
+  - id: SG4
+    verified: true
+    text: "`PATCH /v3/user/webhooks/event/settings/{id}` requires `url` and updates the fields sent; `DELETE` on the same path answers 204, and 404 for an unknown id. Without an id these paths act on the oldest webhook, which the recipe never does (its paths always carry the id)."
+    source: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/update-an-event-webhook
+  - id: SG5
+    verified: true
+    text: "Signature verification and its public key are set through a separate endpoint and are not part of the webhook's create or update; this recipe does not manage them."
+    source: https://www.twilio.com/docs/sendgrid/api-reference/webhooks/create-an-event-webhook
+  - id: SG6
+    verified: true
+    text: "`POST /v3/user/webhooks/parse/settings` creates an Inbound Parse setting from `url`, `hostname`, `spam_check` and `send_raw`, answering 201 with those four fields bare; `GET`, `PATCH` and `DELETE` (204) `/v3/user/webhooks/parse/settings/{hostname}` read, update and remove it. The hostname must be on a domain authenticated in SendGrid, with an MX record pointing at SendGrid."
+    source: https://www.twilio.com/docs/sendgrid/api-reference/settings-inbound-parse/create-a-parse-setting
+  - id: SG7
+    verified: false
+    text: "A PATCH that leaves out an event flag keeps its current value (the documentation's examples send only `url`); the recipe sends every flag it compares anyway."
+  - id: SG8
+    verified: false
+    text: "A parse setting for a hostname that exists already is refused with an error status (not documented which); the next run then finds it by its hostname."
+ops:
+  event_webhook:
+    kind: resource
+    title: Event Webhook
+    summary: An Event Webhook delivering an environment's email events to its URL, such as the preview's `/api/sendgrid/events` handler. Located by its URL (unique in SendGrid); a console edit of its enabled flag, an event flag or its friendly name is drift.
+    covers: [sendgrid-webhook]
+    params:
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL events are posted to; its identity (SG2).
+        example: "https://${ctx.scope}.preview.example.com/api/sendgrid/events"
+      enabled:
+        type: boolean
+        default: true
+        description: Whether events are posted.
+      friendly_name:
+        type: string
+        description: A label for the webhook (not unique).
+        example: "sponson ${ctx.env} ${ctx.scope}"
+      processed: { type: boolean, default: false, description: Post `processed` events. }
+      delivered: { type: boolean, default: true, description: Post `delivered` events. }
+      dropped: { type: boolean, default: true, description: Post `dropped` events. }
+      deferred: { type: boolean, default: false, description: Post `deferred` events. }
+      bounce: { type: boolean, default: true, description: Post `bounce` events. }
+      open: { type: boolean, default: false, description: Post `open` events. }
+      click: { type: boolean, default: false, description: Post `click` events. }
+      spam_report: { type: boolean, default: true, description: Post `spam_report` events. }
+      unsubscribe: { type: boolean, default: false, description: Post `unsubscribe` events. }
+      group_unsubscribe: { type: boolean, default: false, description: Post `group_unsubscribe` events. }
+      group_resubscribe: { type: boolean, default: false, description: Post `group_resubscribe` events. }
+    http:
+      find:
+        path: /v3/user/webhooks/event/settings/all
+        list_path: /webhooks
+        match: { url: { param: url } }
+      create: { path: /v3/user/webhooks/event/settings }
+      update:
+        method: PATCH
+        path: "/v3/user/webhooks/event/settings/{id}"
+        body: { url: { param: url } }
+      delete: { path: "/v3/user/webhooks/event/settings/{id}" }
+      fields:
+        enabled: { param: enabled }
+        friendly_name: { param: friendly_name }
+        processed: { param: processed }
+        delivered: { param: delivered }
+        dropped: { param: dropped }
+        deferred: { param: deferred }
+        bounce: { param: bounce }
+        open: { param: open }
+        click: { param: click }
+        spam_report: { param: spam_report }
+        unsubscribe: { param: unsubscribe }
+        group_unsubscribe: { param: group_unsubscribe }
+        group_resubscribe: { param: group_resubscribe }
+  parse_setting:
+    kind: resource
+    title: Inbound Parse setting
+    summary: An Inbound Parse host per environment, such as `pr-42.parse.example.com`, posting the mail it receives to the environment's URL. Named by its hostname; a console edit of its URL, spam check or raw flag is drift. The hostname's domain must be authenticated in SendGrid and its MX record point at SendGrid (a wildcard record serves every environment).
+    covers: [sendgrid-webhook]
+    params:
+      hostname:
+        type: string
+        required: true
+        pattern: "^[a-z0-9.-]+$"
+        description: The host mail is received for, lower-case; its identity.
+        example: "${ctx.scope}.parse.example.com"
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL parsed mail is posted to.
+        example: "https://${ctx.scope}.preview.example.com/api/sendgrid/inbound"
+      spam_check:
+        type: boolean
+        default: false
+        description: Check mail for spam before posting it.
+      send_raw:
+        type: boolean
+        default: false
+        description: Post the original MIME message.
+    http:
+      read: { path: "/v3/user/webhooks/parse/settings/{hostname}" }
+      create:
+        path: /v3/user/webhooks/parse/settings
+        body: { hostname: { param: hostname } }
+      update: { method: PATCH }
+      id_path: /hostname
+      fields:
+        url: { param: url }
+        spam_check: { param: spam_check }
+        send_raw: { param: send_raw }
+    sim:
+      id_from: hostname
+    live:
+      params: { hostname: SPONSON_LIVE_SENDGRID_PARSE_HOSTNAME }