@sponson/adapters 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sponson/adapters",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The built-in resource adapters and secret sources for Sponson.",
   "keywords": [
     "sponson",
@@ -12,7 +12,8 @@
     "neon",
     "clerk",
     "adapters",
-    "secrets"
+    "secrets",
+    "recipes"
   ],
   "license": "Apache-2.0",
   "repository": {
@@ -33,17 +34,23 @@
     }
   },
   "dependencies": {
-    "@sponson/core": "0.4.0"
+    "yaml": "^2.8.1",
+    "@sponson/core": "0.6.0"
   },
   "devDependencies": {
-    "@sponson/sim": "0.4.0"
+    "@sponson/sim": "0.6.0"
   },
   "files": [
     "dist",
     "!dist/.tsbuildinfo",
+    "recipes",
     "README.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "homepage": "https://sponson.mintlify.site",
   "bugs": {
     "url": "https://github.com/MishaBear94/Sponson/issues"

package/recipes/amplify.yaml

@@ -0,0 +1,147 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# AWS Amplify Hosting API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: amplify
+title: AWS Amplify Hosting
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: CreateBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateBranch.html
+  - title: GetBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_GetBranch.html
+  - title: UpdateBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateBranch.html
+  - title: DeleteBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_DeleteBranch.html
+  - title: Amplify endpoints and quotas
+    url: https://docs.aws.amazon.com/general/latest/gr/amplify.html
+  - title: Create a signed AWS API request (SigV4)
+    url: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+api:
+  base_url: https://amplify.us-east-1.amazonaws.com
+  base_url_env: AMPLIFY_API_URL
+  auth:
+    aws_sigv4: { region: us-east-1, service: amplify, access_key_id_env: AWS_ACCESS_KEY_ID, secret_access_key_env: AWS_SECRET_ACCESS_KEY }
+detect:
+  files: [amplify.yml]
+  starter:
+    - op: branch_variable
+      values: { branch_name: "${ctx.git.branch}" }
+  where:
+    app_id: "Amplify console → your app → App settings → General → App ID (`d…`), or `aws amplify list-apps --query 'apps[].appId'`"
+assumptions:
+  - id: AM1
+    verified: true
+    text: "The Amplify API is regional (`https://amplify.<region>.amazonaws.com`) and signed with SigV4 for the service `amplify`. The recipe defaults to `us-east-1`; an app in another region sets `base_url` and `auth` (with its `region`) in the provider block, and temporary credentials (a CI role) add `session_token_env: AWS_SESSION_TOKEN` there."
+    source: https://docs.aws.amazon.com/general/latest/gr/amplify.html
+  - id: AM2
+    verified: true
+    text: "`POST /apps/{appId}/branches` (CreateBranch) creates a branch from `branchName` (required) and optional `description`, `stage` (PRODUCTION, BETA, DEVELOPMENT, EXPERIMENTAL, PULL_REQUEST), `enableAutoBuild`, `environmentVariables`, …; it answers 200 with `{ branch }`."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateBranch.html
+  - id: AM3
+    verified: true
+    text: "`GET /apps/{appId}/branches/{branchName}` (GetBranch) answers `{ branch }` with `branchName`, `stage`, `description`, `enableAutoBuild` and `environmentVariables` (a map of string to string)."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_GetBranch.html
+  - id: AM4
+    verified: true
+    text: "`POST /apps/{appId}/branches/{branchName}` (UpdateBranch) takes the same optional fields and answers `{ branch }`; `environmentVariables` is the branch's whole map of variables."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateBranch.html
+  - id: AM5
+    verified: true
+    text: "`DELETE /apps/{appId}/branches/{branchName}` (DeleteBranch) deletes a branch; an unknown app or branch is 404 `NotFoundException`."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_DeleteBranch.html
+  - id: AM6
+    verified: false
+    text: "UpdateBranch leaves the fields it is not sent as they are (so the branch op's update does not reset the variables, and the variable op's write does not reset the branch's settings), while an `environmentVariables` it is sent replaces the whole map, as the sim models it (assumption A4 of packages/sim/src/routes/aws.ts)."
+  - id: AM7
+    verified: false
+    text: "A build that ran before a variable was written does not see it: Sponson does not start a new job (StartJob), so order the variable lines before the branch's first build (`enable_auto_build: false` and a CI-started job, or the branch line, then the variables, then the push). The branches Amplify's own pull request previews make are not modelled; this recipe manages a branch the plan names."
+ops:
+  branch:
+    kind: resource
+    title: Branch
+    summary: "An Amplify branch named by the plan (the git branch of the pull request, `${ctx.git.branch}`), created with CreateBranch and deleted on destroy. Its `stage`, `description` and auto-build setting are compared: a console edit is drift. Variables on it are `amplify.branch_variable` lines."
+    covers: [amplify-branch]
+    params:
+      app_id:
+        type: string
+        required: true
+        pattern: "^d[a-z0-9]+$"
+        description: The Amplify app's id.
+        example: d1demo
+      branch_name:
+        type: string
+        required: true
+        description: The branch's name, as the repository names it.
+        example: "${ctx.scope}"
+      stage:
+        type: string
+        enum: [PRODUCTION, BETA, DEVELOPMENT, EXPERIMENTAL, PULL_REQUEST]
+        description: The branch's stage.
+        example: PULL_REQUEST
+      description:
+        type: string
+        description: The branch's description.
+        example: "Preview of ${ctx.scope}"
+      enable_auto_build:
+        type: boolean
+        description: Build automatically on every push (false lets CI start the build after the variables are written; AM7).
+    http:
+      read: { path: "/apps/{app_id}/branches/{branch_name}" }
+      create:
+        path: "/apps/{app_id}/branches"
+        body: { branchName: { param: branch_name } }
+      update: { method: POST }
+      item_path: /branch
+      id_path: /branchName
+      fields:
+        stage: { param: stage }
+        description: { param: description }
+        enableAutoBuild: { param: enable_auto_build }
+    sim:
+      id_from: branchName
+    live:
+      params: { app_id: SPONSON_LIVE_AMPLIFY_APP_ID }
+  branch_variable:
+    kind: list_item
+    title: Branch environment variable
+    summary: "One entry of a branch's `environmentVariables`, by read-modify-write of the whole map (UpdateBranch replaces the map it is sent); other variables are left alone, and the branch is locked while Sponson writes it. A branch that is not there yet reads as having no variables, so a plan that also creates the branch shows a create. Builds started before the write do not see it (AM7)."
+    covers: [amplify-branch]
+    params:
+      app_id:
+        type: string
+        required: true
+        pattern: "^d[a-z0-9]+$"
+        description: The Amplify app's id.
+        example: d1demo
+      branch_name:
+        type: string
+        required: true
+        description: The branch's name (a `{ from }` of the `amplify.branch` line orders the two).
+        example: "${ctx.scope}"
+      name:
+        type: string
+        required: true
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The variable's value.
+        example: "https://api-${ctx.scope}.example.app"
+    http:
+      parent: { path: "/apps/{app_id}/branches/{branch_name}", method: POST, send: collection, item_path: /branch, if_missing: empty }
+      list_path: /environmentVariables
+      shape: map
+      item: { param: name }
+      value: { param: value }
+    sim:
+      provider: aws
+      base_path: /aws/amplify
+      seed: { amplify: { d1demo: { branches: { pr-42: { environmentVariables: { NODE_ENV: production } } } } } }
+      present: /amplify/d1demo/branches/pr-42/environmentVariables/API_URL
+      drift:
+        changed: { amplify.d1demo.pr-42.API_URL: "https://somewhere-else.example" }
+        missing: { amplify.d1demo.pr-42.API_URL: delete }
+    live:
+      params: { app_id: SPONSON_LIVE_AMPLIFY_APP_ID, branch_name: SPONSON_LIVE_AMPLIFY_BRANCH }

package/recipes/auth0.yaml

@@ -0,0 +1,178 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Auth0 Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: auth0
+title: Auth0
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Get Management API access tokens for production
+    url: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production
+  - title: Management API v2, get a client
+    url: https://auth0.com/docs/api/management/v2/clients/get-clients-by-id
+  - title: Management API v2, update a client
+    url: https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id
+  - title: Auth0 Terraform provider, configuration (conventional variable names)
+    url: https://raw.githubusercontent.com/auth0/terraform-provider-auth0/main/docs/index.md
+api:
+  base_url_env: AUTH0_API_URL
+  auth:
+    oauth2_client_credentials:
+      token_url: /oauth/token
+      token_url_env: AUTH0_TOKEN_URL
+      client_id_env: AUTH0_CLIENT_ID
+      client_secret_env: AUTH0_CLIENT_SECRET
+      audience: /api/v2/
+base_url_example: https://acme.eu.auth0.com/api/v2
+detect:
+  deps: [auth0, "@auth0/"]
+  env: ["AUTH0_*"]
+  starter:
+    - op: callback_url
+    - op: logout_url
+      preview_url: url
+  where:
+    base_url: "`https://<tenant>.<region>.auth0.com/api/v2`: Auth0 Dashboard → Settings → General → Domain (the canonical domain, not a custom one)"
+    client_id: "Auth0 Dashboard → Applications → your application → Settings → Client ID"
+    url: "the exact callback URL the app sends as `redirect_uri` on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: AU1
+    verified: true
+    text: "A machine-to-machine application gets a Management API token from `POST https://<tenant>/oauth/token` (form-encoded `grant_type=client_credentials`, `client_id`, `client_secret`, `audience`); the audience is the Management API's identifier `https://<tenant>/api/v2/`. The answer has `access_token`, `expires_in` (86400 in the example) and `token_type: Bearer`. The recipe writes both as paths, so a plan's `base_url: https://<tenant>/api/v2` names the tenant once."
+    source: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production
+  - id: AU2
+    verified: true
+    text: "`GET /api/v2/clients/{id}` answers the application with its `callbacks`, `allowed_logout_urls`, `web_origins` and `allowed_origins` arrays, which only a token with `read:clients` (or `read:client_keys`) receives. `fields` with `include_fields=true` limits the answer to the listed fields, so the recipe never reads the client secret."
+    source: https://auth0.com/docs/api/management/v2/clients/get-clients-by-id
+  - id: AU3
+    verified: true
+    text: "`PATCH /api/v2/clients/{id}` (scope `update:clients`) updates an application; `callbacks`, `allowed_logout_urls`, `web_origins` and `allowed_origins` are arrays of strings, and the body needs at least one property, so a write sends the one array alone."
+    source: https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id
+  - id: AU4
+    verified: false
+    text: "An array sent in a PATCH replaces the stored array whole (it is not merged), so the recipe sends the full list read just before with one URL added or removed. The reference does not say so for these fields."
+  - id: AU5
+    verified: false
+    text: "Updates have no precondition (no ETag or version): the line locks the application (`lockOn`, one lock per tenant and client id, shared by the four ops) against other Sponson runs, and a console edit made between the read and the write can still be lost (the next apply then reports it as drift)."
+  - id: AU6
+    verified: false
+    text: "URLs are stored and read back exactly as written (no trailing slash added or case changed), so a URL identifies its entry."
+  - id: AU7
+    verified: true
+    text: "`AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` are the variables the Auth0 Terraform provider reads for a machine-to-machine client."
+    source: https://raw.githubusercontent.com/auth0/terraform-provider-auth0/main/docs/index.md
+  - id: AU8
+    verified: false
+    text: "The audience stays the tenant's canonical domain when the tenant has a custom domain, so `base_url` names the canonical domain (`<tenant>.<region>.auth0.com`), not the custom one."
+ops:
+  callback_url:
+    kind: list_item
+    title: Application callback URL
+    summary: "One URL in an Auth0 application's Allowed Callback URLs (`callbacks`), such as the preview's `/callback`; usually `{ from: <deploy line>.preview_url }` joined with the path in the app. Added by read-modify-write of the list under a lock on the application, removed on destroy; every other URL is left as it is. A URL removed in the Dashboard is drift (`missing`) that the next apply puts back."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The callback URL, exactly as the application sends it as `redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app/callback"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /callbacks
+      item: { param: url }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  logout_url:
+    kind: list_item
+    title: Application allowed logout URL
+    summary: "One URL in an Auth0 application's Allowed Logout URLs (`allowed_logout_urls`), where `/v2/logout` may return the user, such as the preview's home page. Read-modify-write of the list under the application's lock; removed on destroy; every other URL is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The URL the application passes as `returnTo` on logout."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /allowed_logout_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  web_origin:
+    kind: list_item
+    title: Application allowed web origin
+    summary: "One origin in an Auth0 application's Allowed Web Origins (`web_origins`), which silent authentication and the SPA SDKs' token refresh need for the preview's origin. Read-modify-write of the list under the application's lock; removed on destroy; every other origin is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /web_origins
+      item: { param: origin }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  allowed_origin:
+    kind: list_item
+    title: Application allowed origin (CORS)
+    summary: "One origin in an Auth0 application's Allowed Origins (CORS, `allowed_origins`), for a preview that calls Auth0 from the browser across origins (embedded login, cross-origin authentication). Read-modify-write of the list under the application's lock; removed on destroy; every other origin is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /allowed_origins
+      item: { param: origin }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }

package/recipes/azure_swa.yaml

@@ -0,0 +1,116 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Azure Static Web Apps (Azure Resource Manager) recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: azure_swa
+title: Azure Static Web Apps
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Static Sites - Create Or Update Static Site Build App Settings
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/create-or-update-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - title: Static Sites - List Static Site Build App Settings
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/list-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - title: Static Sites - Get Static Site Builds
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/get-static-site-builds?view=rest-appservice-2024-04-01
+  - title: Preview environments in Azure Static Web Apps
+    url: https://learn.microsoft.com/en-us/azure/static-web-apps/preview-environments
+  - title: Configure application settings for Azure Static Web Apps
+    url: https://learn.microsoft.com/en-us/azure/static-web-apps/application-settings
+  - title: az account get-access-token
+    url: https://learn.microsoft.com/en-us/cli/azure/account#az-account-get-access-token
+api:
+  base_url: https://management.azure.com
+  base_url_env: AZURE_SWA_API_URL
+  auth: { command: [az, account, get-access-token, --query, accessToken, -o, tsv] }
+detect:
+  files: [staticwebapp.config.json]
+  env: ["AZURE_STATIC_WEB_APPS_*"]
+  starter:
+    - op: build_app_setting
+      values: { environment: "${ctx.pr.number}" }
+  where:
+    subscription_id: "`az account show --query id -o tsv`"
+    resource_group: "`az staticwebapp show --name <site> --query resourceGroup -o tsv`"
+    site: "`az staticwebapp list --query '[].name'`"
+assumptions:
+  - id: AZ1
+    verified: true
+    text: "`PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/staticSites/{name}/builds/{environmentName}/config/appsettings?api-version=2024-04-01` with `{ properties: { <name>: <value>, … } }` sets the app settings of one environment (build) and answers 200 with the same `properties`."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/create-or-update-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - id: AZ2
+    verified: true
+    text: "The settings are read with `POST …/builds/{environmentName}/listAppSettings?api-version=2024-04-01` (no body), which answers a StringDictionary `{ id, properties }`; there is no GET, so the recipe reads with `parent.read_method: POST`."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/list-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - id: AZ3
+    verified: true
+    text: "Each environment is a `builds/{environmentName}` resource: production is `default`, a pull request's preview environment is named by the pull request's number (`builds/12`)."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/get-static-site-builds?view=rest-appservice-2024-04-01
+  - id: AZ4
+    verified: true
+    text: "A preview environment exists from the pull request's first deployment and is deleted, with its settings, when the pull request is closed; app settings reach the app's managed API (Functions), not the front-end build."
+    source: https://learn.microsoft.com/en-us/azure/static-web-apps/preview-environments
+  - id: AZ5
+    verified: true
+    text: "`az account get-access-token --query accessToken -o tsv` prints an Azure Resource Manager access token for the signed-in account (the default resource is `https://management.azure.com/`), sent as a bearer token."
+    source: https://learn.microsoft.com/en-us/cli/azure/account#az-account-get-access-token
+  - id: AZ6
+    verified: false
+    text: "The PUT replaces the whole settings map (a setting it is not sent is removed), so the recipe sends the map as read with the one entry changed (`send: collection`); there is no ETag on this resource, so only Sponson's own writers are serialised (the parent lock), and a setting added in the portal between the read and the write is lost."
+  - id: AZ7
+    verified: false
+    text: "Listing the settings of an environment that does not exist (not deployed yet, or deleted with its pull request) answers 404, which the recipe reads as no settings (`if_missing: empty`): plan shows a create before the first deploy, and destroy after the pull request closed is a no-op. A write before the first deploy fails with that 404; order the line after the deploy."
+ops:
+  build_app_setting:
+    kind: list_item
+    title: App setting of a preview environment
+    summary: "One app setting of a Static Web App environment (a pull request's preview environment is named by its number), by read-modify-write of the environment's settings: read with `listAppSettings`, written whole with a PUT. Other settings are left alone and the environment is locked while Sponson writes it. Settings reach the app's managed API, not the front-end build (AZ4); the environment exists only after the PR's first deploy (AZ7)."
+    covers: [azure-swa-settings]
+    params:
+      subscription_id:
+        type: string
+        required: true
+        description: The Azure subscription id.
+        example: 00000000-0000-0000-0000-000000000000
+      resource_group:
+        type: string
+        required: true
+        description: The resource group of the static web app.
+        example: rg-web
+      site:
+        type: string
+        required: true
+        description: The static web app's name.
+        example: web
+      environment:
+        type: string
+        required: true
+        pattern: "^[a-zA-Z0-9]+$"
+        description: The environment's name (the pull request's number for its preview environment; `default` is production).
+        example: "42"
+      name:
+        type: string
+        required: true
+        description: The setting's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The setting's value.
+        example: "https://api-${ctx.scope}.example.app"
+    http:
+      parent:
+        path: "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/config/appsettings?api-version=2024-04-01"
+        read_path: "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/listAppSettings?api-version=2024-04-01"
+        read_method: POST
+        method: PUT
+        send: collection
+        if_missing: empty
+      list_path: /properties
+      shape: map
+      item: { param: name }
+      value: { param: value }
+    sim:
+      objects:
+        "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/config/appsettings":
+          properties: { SHARED_SETTING: from-the-portal }
+    live:
+      params: { subscription_id: SPONSON_LIVE_AZURE_SUBSCRIPTION_ID, resource_group: SPONSON_LIVE_AZURE_RESOURCE_GROUP, site: SPONSON_LIVE_AZURE_SWA_SITE, environment: SPONSON_LIVE_AZURE_SWA_ENVIRONMENT }

package/recipes/cloudflare.yaml

@@ -0,0 +1,108 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Cloudflare API v4 recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: cloudflare
+title: Cloudflare
+category: dns
+verified_on: "2026-10-11"
+docs:
+  - title: Create DNS record
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/
+  - title: List DNS records
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/list/
+  - title: DNS record details
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/get/
+  - title: Update DNS record (PATCH)
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/edit/
+  - title: Delete DNS record
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/delete/
+api:
+  base_url: https://api.cloudflare.com/client/v4
+  base_url_env: CLOUDFLARE_API_URL
+  auth: { bearer_env: CLOUDFLARE_API_TOKEN }
+assumptions:
+  - id: CF1
+    verified: true
+    text: "Records are created with `POST /zones/{zone_id}/dns_records` (`type`, `name`, `content`, `ttl`, `proxied`, `comment`), authenticated with an API token as `Authorization: Bearer` that has DNS Write on the zone."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/
+  - id: CF2
+    verified: true
+    text: "`GET /zones/{zone_id}/dns_records` answers `{ result: [...] }` and filters by `type` and `name.exact` (names compare case-insensitively)."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/list/
+  - id: CF3
+    verified: true
+    text: "Single-record answers (create, details, update) carry the record under `result`, with its `id`."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/get/
+  - id: CF4
+    verified: true
+    text: "`PATCH /zones/{zone_id}/dns_records/{id}` updates a record; `DELETE` on the same path removes it permanently."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/delete/
+  - id: CF5
+    verified: false
+    text: "A PATCH needs `name` and `type` alongside the changed fields (the edit schema does not mark them optional), so every update sends both."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/edit/
+  - id: CF6
+    verified: false
+    text: "The API returns `name` lower-cased as the full name and `content` as written, so `name` must be given lower-case and fully qualified, or every plan finds no record and tries to create one."
+  - id: CF7
+    verified: false
+    text: "A proxied record reports `ttl: 1` (automatic) whatever was sent, so `ttl` other than 1 with `proxied: true` shows as drift on every plan."
+  - id: CF8
+    verified: true
+    text: A CNAME cannot share its name with another record, so name and type identify it within the zone and a filtered list holds at most one, on its first page.
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/
+ops:
+  dns_cname:
+    kind: resource
+    title: DNS CNAME record
+    summary: A CNAME record in a zone, such as `pr-42.preview.example.com` pointing at the preview deployment's host. Located by name and type; a console edit of its target, proxying, TTL or comment is drift.
+    covers: [cloudflare-dns]
+    params:
+      zone_id:
+        type: string
+        required: true
+        pattern: "^[0-9a-f]{32}$"
+        description: The zone's id (32 hex characters, on the zone's Overview page).
+        example: 023e105f4ecef8ad9ca31a8372d0c353
+      name:
+        type: string
+        required: true
+        pattern: "^[a-z0-9*_.-]+$"
+        description: The record's full name, lower-case, zone included.
+        example: "${ctx.scope}.preview.example.com"
+      target:
+        type: string
+        required: true
+        description: The host the name points at (the record's `content`).
+        example: preview-host.example.net
+      proxied:
+        type: boolean
+        default: false
+        description: Whether Cloudflare proxies the traffic.
+      ttl:
+        type: integer
+        default: 1
+        description: TTL in seconds (60–86400), or 1 for automatic.
+      comment:
+        type: string
+        description: A note on the record; no effect on DNS.
+        example: Managed by Sponson
+    http:
+      find:
+        path: "/zones/{zone_id}/dns_records?type=CNAME&name.exact={name}"
+        list_path: /result
+        match: { type: CNAME, name: { param: name } }
+      create: { path: "/zones/{zone_id}/dns_records" }
+      update:
+        method: PATCH
+        path: "/zones/{zone_id}/dns_records/{id}"
+        body: { type: CNAME, name: { param: name } }
+      delete: { path: "/zones/{zone_id}/dns_records/{id}" }
+      item_path: /result
+      fields:
+        content: { param: target }
+        proxied: { param: proxied }
+        ttl: { param: ttl }
+        comment: { param: comment }
+      outputs: { hostname: /name }
+    live:
+      params: { zone_id: SPONSON_LIVE_CLOUDFLARE_ZONE_ID, name: SPONSON_LIVE_CLOUDFLARE_NAME }