@sponson/adapters 0.4.0 → 0.5.0

package/recipes/heroku.yaml

@@ -0,0 +1,98 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Heroku Platform API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: heroku
+title: Heroku
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Platform API reference (clients, Config Vars, Review App)
+    url: https://devcenter.heroku.com/articles/platform-api-reference
+  - title: Platform API JSON schema (config-var)
+    url: https://api.heroku.com/schema
+  - title: Configuration and config vars
+    url: https://devcenter.heroku.com/articles/config-vars
+  - title: CLI authentication (HEROKU_API_KEY)
+    url: https://devcenter.heroku.com/articles/authentication
+api:
+  base_url: https://api.heroku.com
+  base_url_env: HEROKU_API_URL
+  auth: { bearer_env: HEROKU_API_KEY }
+  media_type: "application/vnd.heroku+json; version=3"
+detect:
+  env: ["HEROKU_*"]
+  files: [heroku.yml]
+  starter:
+    - op: config_var
+  where:
+    app: "the review app's name (`heroku apps`; by default `<pipeline>-pr-<n>`)"
+assumptions:
+  - id: HK1
+    verified: true
+    text: "Requests authenticate as `Authorization: Bearer <token>`; the Heroku CLI reads the token from `HEROKU_API_KEY`."
+    source: https://devcenter.heroku.com/articles/authentication
+  - id: HK2
+    verified: true
+    text: "Every request must send `Accept: application/vnd.heroku+json; version=3`; without it the API refuses the request (documented as 406 `not_acceptable`; a request without it was answered 400 `missing_version` when checked)."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK3
+    verified: true
+    text: "`GET /apps/{app_id_or_name}/config-vars` answers the app's config vars as one flat map of name to string value."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK4
+    verified: true
+    text: "`PATCH /apps/{app_id_or_name}/config-vars` with a map sets the named vars and removes those set to `null`, leaving every other var as it is: one var is written without reading or rewriting the others, so concurrent writers of other vars cannot lose them (no lock needed)."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK5
+    verified: true
+    text: "Config var names match `^\\w+$` and values are strings (`null` only as a delete in a PATCH)."
+    source: https://api.heroku.com/schema
+  - id: HK6
+    verified: true
+    text: "Every change to config vars creates a new release and restarts the app, so a write takes effect without a separate deploy."
+    source: https://devcenter.heroku.com/articles/config-vars
+  - id: HK7
+    verified: true
+    text: "Review apps are created asynchronously (`POST /review-apps` answers `pending` with a nullable `app`), by Heroku itself when the pipeline has automatic review apps; this recipe does not create them, it writes vars on an app that exists (the review app's name or id)."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK9
+    verified: false
+    text: "A PATCH whose `Content-Type` is the same vendor media type (`media_type` sends it as both `Accept` and `Content-Type`) is accepted like `application/json`; the reference's examples send `application/json`."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK8
+    verified: false
+    text: "A missing app answers 404 `not_found` on GET and PATCH, which destroy treats as the var being gone."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+ops:
+  config_var:
+    kind: list_item
+    title: App config var
+    summary: "One config var on a Heroku app, such as a review app's `API_URL`. Written as a merge patch of that one var (`null` deletes it), so other vars, including other scopes', are never rewritten. A console edit of its value is drift; destroy removes only this var. Heroku restarts the app on every change (HK6)."
+    covers: [heroku-config-vars]
+    params:
+      app:
+        type: string
+        required: true
+        description: The app's name or id (a review app's, such as `myapp-pr-42`).
+        example: "myapp-${ctx.scope}"
+      key:
+        type: string
+        required: true
+        pattern: "^\\w+$"
+        description: The config var's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: "The value: a literal, `{ from }` or `{ secret }`."
+        example: "https://api-${ctx.scope}.example.com"
+    http:
+      parent: { path: "/apps/{app}/config-vars" }
+      list_path: ""
+      shape: map
+      item: { param: key }
+      value: { param: value }
+    sim:
+      objects:
+        "/apps/{app}/config-vars": { DATABASE_URL: "postgres://seeded", LOG_LEVEL: info }
+    live:
+      params: { app: SPONSON_LIVE_HEROKU_APP }

package/recipes/honeycomb.yaml

@@ -0,0 +1,89 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Honeycomb API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: honeycomb
+title: Honeycomb
+category: observability
+verified_on: "2026-10-11"
+docs:
+  - title: Create a Marker
+    url: https://docs.honeycomb.io/api/markers/create-a-marker
+  - title: List All Markers
+    url: https://docs.honeycomb.io/api/markers
+  - title: Update a Marker
+    url: https://docs.honeycomb.io/api/markers/update-a-marker
+  - title: Delete a Marker
+    url: https://docs.honeycomb.io/api/markers/delete-a-marker
+api:
+  base_url: https://api.honeycomb.io
+  base_url_env: HONEYCOMB_API_URL
+  auth: { header: X-Honeycomb-Team, value_env: HONEYCOMB_API_KEY }
+detect:
+  deps: ["@honeycombio/"]
+  env: ["HONEYCOMB_*"]
+  starter:
+    - op: marker
+      values: { dataset: __all__, message: "deploy ${ctx.scope} ${ctx.git.sha}" }
+assumptions:
+  - id: HC1
+    verified: true
+    text: "`POST /1/markers/{datasetSlug}` creates a marker from `start_time`, `end_time` (Unix seconds), `message`, `type` and `url` (all optional; `start_time` defaults to the request's arrival), answering 201 with the marker and its `id`; `__all__` as the dataset slug makes an environment-wide marker. Requests carry a Configuration Key with the Manage Markers permission in `X-Honeycomb-Team`."
+    source: https://docs.honeycomb.io/api/markers/create-a-marker
+  - id: HC2
+    verified: true
+    text: "`GET /1/markers/{datasetSlug}` answers a bare array of the dataset's markers (`id`, `message`, `type`, `url`, `start_time`, `end_time`, `created_at`, `updated_at`, `color`)."
+    source: https://docs.honeycomb.io/api/markers
+  - id: HC3
+    verified: true
+    text: "`PUT /1/markers/{datasetSlug}/{markerId}` replaces the marker: a field left out of the body is erased."
+    source: https://docs.honeycomb.io/api/markers/update-a-marker
+  - id: HC4
+    verified: true
+    text: "`DELETE /1/markers/{datasetSlug}/{markerId}` removes the marker and answers it (200)."
+    source: https://docs.honeycomb.io/api/markers/delete-a-marker
+  - id: HC5
+    verified: true
+    text: "The API is served from `api.honeycomb.io` (US) and `api.eu1.honeycomb.io` (EU); EU teams set `base_url` in the provider block."
+    source: https://docs.honeycomb.io/api/markers/create-a-marker
+  - id: HC6
+    verified: false
+    text: "Message and type identify the marker this recipe created among the dataset's markers (Honeycomb does not require them to be unique: two equal ones make `find` refuse with PARAM_INVALID), and the list holds every marker of the dataset in one answer."
+  - id: HC7
+    verified: false
+    text: "An update (a changed `url`) re-sends message, type and url but not `start_time`, which Honeycomb then sets to the time of the update (HC3), moving the marker; markers are rarely edited."
+  - id: HC8
+    verified: false
+    text: "A deleted marker answers 404 to DELETE, which destroy treats as already gone."
+ops:
+  marker:
+    kind: resource
+    title: Deploy marker
+    summary: "A marker on an environment's dataset (or on every dataset of the environment with `__all__`) for a deploy, such as `deploy pr-42 0123abc`. Located by its message and type; a console edit of its URL is drift. Destroying the scope removes it; write `destroy: keep` to keep the deploy history."
+    covers: [honeycomb-marker]
+    params:
+      dataset:
+        type: string
+        required: true
+        description: The dataset's slug, or `__all__` for an environment-wide marker.
+        example: __all__
+      message:
+        type: string
+        required: true
+        description: The marker's text; with its type, its identity (HC6).
+        example: "deploy ${ctx.scope} ${ctx.git.sha}"
+      type:
+        type: string
+        default: deploy
+        description: The marker's type, which groups markers (and their color).
+      url:
+        type: string
+        description: The link opened from the marker (the preview or the build).
+        example: "https://${ctx.scope}.preview.example.com"
+    http:
+      find:
+        path: "/1/markers/{dataset}"
+        match: { message: { param: message }, type: { param: type } }
+      create: { path: "/1/markers/{dataset}" }
+      update: { method: PUT, path: "/1/markers/{dataset}/{id}" }
+      delete: { path: "/1/markers/{dataset}/{id}" }
+      fields:
+        url: { param: url }

package/recipes/inngest.yaml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Inngest recipes. Format and checklist: docs/adr/0020-recipes.md, docs/adr/0022-one-off-actions.md, CONTRIBUTING.md
+# "Adding a recipe". No API block: the sync is a request to the app's own serve endpoint, which registers itself
+# with Inngest using its own signing key, so Sponson sends no Inngest credential at all.
+provider: inngest
+title: Inngest
+category: queues
+verified_on: "2026-10-11"
+docs:
+  - title: Syncing an Inngest app (curl -X PUT on the serve endpoint), Inngest's integration guide
+    url: https://www.inngest.com/llm-context.md
+  - title: Apps in Inngest Cloud (sync methods, when to sync)
+    url: https://www.inngest.com/docs/apps/cloud
+  - title: Environments and branch environments
+    url: https://www.inngest.com/docs/platform/environments
+  - title: The TypeScript SDK's serve handler (InngestCommHandler, PUT = register)
+    url: https://github.com/inngest/inngest-js/blob/main/packages/inngest/src/components/InngestCommHandler.ts
+  - title: REST API v2 OpenAPI document (V2_SyncApp)
+    url: https://api-docs.inngest.com/api-specs/v2.json
+detect:
+  deps: [inngest]
+  env: ["INNGEST_*"]
+  starter:
+    - op: sync
+      preview_url: url
+      values: { revision: "${ctx.git.sha}" }
+assumptions:
+  - id: IN1
+    verified: true
+    text: "A `PUT` to the app's serve endpoint (by convention `/api/inngest`, `curl -X PUT https://your-app.com/api/inngest --fail-with-body`) makes the app's SDK register its functions with Inngest; the SDK authenticates that registration with the app's own `INNGEST_SIGNING_KEY`, so the caller sends no credential."
+    source: https://www.inngest.com/llm-context.md
+  - id: IN2
+    verified: true
+    text: "The app registers into the environment its SDK is configured for: `INNGEST_ENV` (or the client's `env` option) names the branch environment and always wins; Vercel's `VERCEL_GIT_COMMIT_REF` is detected automatically, while Netlify, Cloudflare Pages, Railway and Render must pass their branch variable. Sponson does not choose the environment: the app must be configured so."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN3
+    verified: true
+    text: "A branch environment is created on demand the first time an app syncs with it (or events are sent to it), and every branch environment shares one signing key and one event key, so a preview needs no per-branch key."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN4
+    verified: true
+    text: "Without `x-inngest-sync-kind: in-band` (which this recipe never sends) the serve handler syncs out of band: it calls Inngest's register endpoint itself and answers with that call's status and a JSON body `{ message, modified }`; a failed registration answers 500 (`Failed to register`)."
+    source: https://github.com/inngest/inngest-js/blob/main/packages/inngest/src/components/InngestCommHandler.ts
+  - id: IN5
+    verified: true
+    text: "Sync only once the new version of the code is live: some hosts roll a deploy out over seconds or minutes and an early sync registers the old functions. The recipe's trigger is the deployment's URL (a deploy line's external output, so the line waits for the deploy) and a revision."
+    source: https://www.inngest.com/docs/apps/cloud
+  - id: IN6
+    verified: true
+    text: "Branch environments are archived automatically three days after their latest deployment (archiving stops functions from triggering and keeps the data), and archiving cannot be undone per app; there is no request to undo a sync, so destroy sends nothing and forgets the record."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN7
+    verified: true
+    text: "The REST API's `POST /v2/apps/{appId}/syncs` (marked beta, `x-beta: true`) takes `{ url }` and answers a sync with `status` pending, success, error or duplicate, but the operation declares no header or parameter that selects a branch environment; this recipe does not use it."
+    source: https://api-docs.inngest.com/api-specs/v2.json
+  - id: IN8
+    verified: false
+    text: "Syncing the same deployment again is harmless (the same functions registered again, `modified: false`), so the at-least-once delivery of an action (sent again after a crash before it was recorded) needs no idempotency key."
+  - id: IN9
+    verified: false
+    text: "A preview behind Vercel Deployment Protection answers the `PUT` with 401 unless it carries `x-vercel-protection-bypass` with the project's automation bypass secret; pass it with `headers`, as a `{ secret }`."
+ops:
+  sync:
+    kind: action
+    title: App sync into its branch environment
+    summary: Registers a preview deployment's Inngest functions by sending `PUT` to its serve endpoint, once per deployment URL and revision; the app's SDK picks the branch environment (`INNGEST_ENV`, IN2) and signs the registration with its own key (IN1), so no Inngest credential is needed.
+    covers: [inngest-sync]
+    params:
+      url:
+        type: string
+        description: "The deployment's base URL, without a trailing slash: usually `{ from: <deploy line>.preview_url }`, so the sync waits for the deploy (IN5)."
+        required: true
+        pattern: "^https?://\\S+[^/]$"
+        example: https://acme-git-feat-x-acme.vercel.app
+      path:
+        type: string
+        description: Where the app serves Inngest's `serve()` handler, appended to `url`.
+        default: /api/inngest
+        pattern: "^/\\S*$"
+      revision:
+        type: string
+        description: "What else makes it sync again when it changes, usually the commit: `\"${ctx.git.sha}\"`."
+        required: true
+        example: "${ctx.git.sha}"
+      headers:
+        type: map
+        description: "Extra request headers, such as `x-vercel-protection-bypass: { secret: env://VERCEL_AUTOMATION_BYPASS_SECRET }` for a protected preview (IN9)."
+    http:
+      trigger: { url: { param: url }, path: { param: path }, revision: { param: revision } }
+      request:
+        method: PUT
+        url: { join: [{ param: url }, { param: path }] }
+        headers: { param: headers }
+      outputs: { modified: /modified }
+    live:
+      # A deployed app with Inngest's serve handler and INNGEST_ENV set to a throwaway branch environment.
+      params: { url: SPONSON_LIVE_INNGEST_APP_URL }

package/recipes/kinde.yaml

@@ -0,0 +1,120 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Kinde Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: kinde
+title: Kinde
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Kinde Management API (OpenAPI specification)
+    url: https://api-spec.kinde.com/kinde-management-api-spec.yaml
+  - title: Access the Kinde Management API
+    url: https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/
+  - title: Kinde Management API JS SDK (conventional variable names)
+    url: https://github.com/kinde-oss/management-api-js
+api:
+  base_url_env: KINDE_API_URL
+  auth:
+    oauth2_client_credentials:
+      token_url: /oauth2/token
+      token_url_env: KINDE_TOKEN_URL
+      client_id_env: KINDE_MANAGEMENT_CLIENT_ID
+      client_secret_env: KINDE_MANAGEMENT_CLIENT_SECRET
+      audience: /api
+base_url_example: https://acme.kinde.com/api/v1
+detect:
+  deps: ["@kinde-oss/"]
+  env: ["KINDE_*"]
+  starter:
+    - op: callback_url
+    - op: logout_url
+      preview_url: url
+  where:
+    base_url: "`https://<business>.kinde.com/api/v1`: Kinde → Settings → Details → Domain"
+    app_id: "Kinde → Settings → Applications → your application → Details → Client ID"
+    url: "the exact callback URL the SDK sends on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: KI1
+    verified: true
+    text: "A machine-to-machine application authorized for the Management API gets a token from `POST https://<business>.kinde.com/oauth2/token` (form-encoded `grant_type=client_credentials`, `client_id`, `client_secret`, `audience=https://<business>.kinde.com/api`); API calls go to `https://<business>.kinde.com/api/v1/…`. The recipe writes the token URL and audience as paths, so a plan's `base_url: https://<business>.kinde.com/api/v1` names the business once."
+    source: https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/
+  - id: KI2
+    verified: true
+    text: "`GET /api/v1/applications/{app_id}/auth_redirect_urls` (scope `read:applications_redirect_uris`) answers `{ redirect_urls: [...] }`; `PUT` on the same path (scope `update:applications_redirect_uris`) replaces all of an application's callback URLs with the body's `urls` array. (`POST` adds and `DELETE ?urls=` removes; the recipe replaces the list it read, under a lock, so that one apply is one idempotent write.)"
+    source: https://api-spec.kinde.com/kinde-management-api-spec.yaml
+  - id: KI3
+    verified: true
+    text: "`GET /api/v1/applications/{app_id}/auth_logout_urls` answers `{ logout_urls: [...] }` and `PUT` replaces them with the body's `urls` array, as for callback URLs."
+    source: https://api-spec.kinde.com/kinde-management-api-spec.yaml
+  - id: KI4
+    verified: true
+    text: "The audience is always the business's kinde.com subdomain (`https://<business>.kinde.com/api`), even when a custom domain serves sign-in, so `base_url` names the kinde.com subdomain."
+    source: https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/
+  - id: KI5
+    verified: true
+    text: "`KINDE_MANAGEMENT_CLIENT_ID` and `KINDE_MANAGEMENT_CLIENT_SECRET` are the variables Kinde's Management API SDK reads for the machine-to-machine client."
+    source: https://github.com/kinde-oss/management-api-js
+  - id: KI6
+    verified: false
+    text: "A `PUT` with an empty `urls` list is accepted and leaves the application with no URLs of that kind (destroying the last preview URL of an application that has no others)."
+  - id: KI7
+    verified: false
+    text: "URLs are read back exactly as written (no normalisation), and the replace has no precondition: the line locks the list (`lockOn`) against other Sponson runs; a console edit made between the read and the write can still be lost."
+ops:
+  callback_url:
+    kind: list_item
+    title: Application callback URL
+    summary: "One URL in a Kinde application's Allowed callback URLs, such as the preview's `/api/auth/kinde_callback`. Read-modify-write: the list is read (`redirect_urls`) and replaced (`urls`) with the URL added, under a lock on the list; removed on destroy; every other URL is left as it is."
+    covers: [kinde-callbacks]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (its Client ID in the Kinde dashboard).
+        example: 3b0b5c6c8fcc464fab397f4969b5f482
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The callback URL, exactly as the SDK sends it (`KINDE_REDIRECT_URL` / `KINDE_SITE_URL` + the callback path)."
+        example: "https://${ctx.scope}.preview.example.app/api/auth/kinde_callback"
+    http:
+      parent:
+        path: "/applications/{app_id}/auth_redirect_urls"
+        method: PUT
+        write_list_path: /urls
+      list_path: /redirect_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/applications/{app_id}/auth_redirect_urls": { redirect_urls: [https://app.example.com/api/auth/kinde_callback] }
+    live:
+      params: { app_id: SPONSON_LIVE_KINDE_APP_ID }
+  logout_url:
+    kind: list_item
+    title: Application allowed logout redirect URL
+    summary: "One URL in a Kinde application's Allowed logout redirect URLs, such as the preview's home page. Read (`logout_urls`) and replaced (`urls`) with the URL added, under a lock on the list; removed on destroy; every other URL is left as it is."
+    covers: [kinde-callbacks]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (its Client ID in the Kinde dashboard).
+        example: 3b0b5c6c8fcc464fab397f4969b5f482
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The URL the SDK redirects to after logout (`KINDE_POST_LOGOUT_REDIRECT_URL`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/applications/{app_id}/auth_logout_urls"
+        method: PUT
+        write_list_path: /urls
+      list_path: /logout_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/applications/{app_id}/auth_logout_urls": { logout_urls: [https://app.example.com] }
+    live:
+      params: { app_id: SPONSON_LIVE_KINDE_APP_ID }

package/recipes/mongodb_atlas.yaml

@@ -0,0 +1,119 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# MongoDB Atlas Administration API v2 recipes (programmatic API keys, HTTP Digest). Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: mongodb_atlas
+title: MongoDB Atlas
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Atlas Administration API v2 (OpenAPI document)
+    url: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - title: Create One Database User in One Project
+    url: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupdatabaseuser
+  - title: Configure Atlas API access (API keys use HTTP Digest)
+    url: https://www.mongodb.com/docs/atlas/configure-api-access/
+  - title: Atlas CLI environment variables
+    url: https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-env-variables/
+api:
+  base_url: https://cloud.mongodb.com/api/atlas/v2
+  base_url_env: MONGODB_ATLAS_API_URL
+  media_type: application/vnd.atlas.2023-01-01+json
+  auth: { digest: { user_env: MONGODB_ATLAS_PUBLIC_API_KEY, password_env: MONGODB_ATLAS_PRIVATE_API_KEY } }
+detect:
+  env: ["MONGODB_ATLAS_*"]
+  db_hosts: [.mongodb.net]
+  starter:
+    - op: database_user
+      values: { username: "app-${ctx.scope}", roles: [{ databaseName: "app_${ctx.scope}", roleName: readWrite }] }
+  where:
+    group_id: "Atlas → Project Settings → Project ID, or `atlas projects list`"
+    password: "a reference, never a value: `{ secret: \"env://PREVIEW_DB_PASSWORD\" }`"
+assumptions:
+  - id: MA1
+    verified: true
+    text: "Programmatic API keys authenticate with HTTP Digest (the public key as the user name, the private key as the password); service accounts take an OAuth2 client-credentials token instead (`https://cloud.mongodb.com/api/oauth/token`)."
+    source: https://www.mongodb.com/docs/atlas/configure-api-access/
+  - id: MA2
+    verified: true
+    text: "The Atlas CLI keeps the key pair in `MONGODB_ATLAS_PUBLIC_API_KEY` and `MONGODB_ATLAS_PRIVATE_API_KEY`."
+    source: https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-env-variables/
+  - id: MA3
+    verified: true
+    text: "Requests and answers use the versioned media type `application/vnd.atlas.2023-01-01+json` (in `Accept` and `Content-Type`); the database-user operations are published under that version."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - id: MA4
+    verified: true
+    text: "`POST /groups/{groupId}/databaseUsers` creates a user from `databaseName`, `groupId`, `roles` and `username` (required), with `password` for SCRAM users (write-only, never answered), optional `scopes` (absent: every cluster of the project) and `deleteAfterDate` (Atlas deletes the user then; within one week of the request). It answers 201 with the user."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - id: MA5
+    verified: true
+    text: "`GET`, `PATCH` and `DELETE /groups/{groupId}/databaseUsers/{databaseName}/{username}` read, update and delete one user; SCRAM users authenticate against `databaseName` `admin`."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - id: MA6
+    verified: true
+    text: "A project supports 100 database users by default (900 at most)."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupdatabaseuser
+  - id: MA7
+    verified: false
+    text: "A GET of a user that does not exist answers 404; a second create of the same user answers 409."
+  - id: MA8
+    verified: false
+    text: "`roles` (each `{ databaseName, roleName, collectionName? }`) and `scopes` (each `{ name, type }`) are answered in the order they were sent, so they compare without drift."
+  - id: MA9
+    verified: false
+    text: "`PATCH` takes the user's identifying fields (`databaseName`, `groupId`, `username`) with the changed ones and keeps the password when none is sent."
+ops:
+  database_user:
+    kind: resource
+    title: Database user
+    summary: "A SCRAM database user per scope on a shared Atlas cluster, such as `app-pr-42` with `readWrite` on the database `app_pr_42`, instead of a cluster per preview. The password is an input: a `{ secret: … }` reference (a value per environment in a secret manager) or a sensitive output of another line, sent on create only and never compared. Located by its user name; a console edit of its roles or scopes is drift; destroy deletes the user (not the database's data)."
+    covers: [mongodb-atlas-user]
+    params:
+      group_id:
+        type: string
+        required: true
+        pattern: "^[0-9a-f]{24}$"
+        description: The project (group) id, 24 hexadecimal digits.
+        example: 32b6e34b3d91647abb20e7b8
+      username:
+        type: string
+        required: true
+        description: The user name, unique in the project; its identity.
+        example: "app-${ctx.scope}"
+      password:
+        type: string
+        required: true
+        description: "The user's password, as a reference (`{ secret: env://… }`, or `{ from: <line>.<output> }` of a sensitive output); sent on create only (MA4)."
+        example: { secret: "env://PREVIEW_DB_PASSWORD" }
+      roles:
+        type: list
+        required: true
+        description: "The roles, each `{ databaseName, roleName }` (`readWrite`, `read`, `dbAdmin`, …)."
+        example: [{ databaseName: "app_${ctx.scope}", roleName: readWrite }]
+      scopes:
+        type: list
+        description: "The clusters it may reach, each `{ name, type: CLUSTER }`; absent: every cluster of the project (not compared then)."
+      delete_after:
+        type: string
+        description: "An ISO 8601 time, within a week, at which Atlas deletes the user by itself (sent on create only)."
+    http:
+      read: { path: "/groups/{group_id}/databaseUsers/admin/{username}" }
+      create:
+        path: "/groups/{group_id}/databaseUsers"
+        body:
+          databaseName: admin
+          groupId: { param: group_id }
+          username: { param: username }
+          password: { param: password }
+          deleteAfterDate: { param: delete_after }
+      update:
+        method: PATCH
+        body: { databaseName: admin, groupId: { param: group_id }, username: { param: username } }
+      id_path: /username
+      fields:
+        roles: { param: roles }
+        scopes: { param: scopes }
+    sim:
+      id_from: username
+    live:
+      params: { group_id: SPONSON_LIVE_ATLAS_GROUP_ID }