@sponson/adapters 0.0.0-stage → 0.5.0

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 }

package/recipes/okta.yaml

@@ -0,0 +1,177 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Okta Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: okta
+title: Okta
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Okta Management API (OpenAPI specification, management-minimal.yaml)
+    url: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - title: Applications API, replace an application
+    url: https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/#tag/Application/operation/replaceApplication
+  - title: Trusted Origins API
+    url: https://developer.okta.com/docs/api/openapi/okta-management/management/tag/TrustedOrigin/
+  - title: Okta Terraform provider, configuration (conventional variable names)
+    url: https://raw.githubusercontent.com/okta/terraform-provider-okta/master/docs/index.md
+api:
+  base_url_env: OKTA_API_URL
+  auth: { header: Authorization, value_env: OKTA_API_TOKEN, prefix: "SSWS " }
+base_url_example: https://acme.okta.com/api/v1
+detect:
+  deps: ["@okta/"]
+  env: ["OKTA_*"]
+  starter:
+    - op: redirect_uri
+    - op: trusted_origin
+      preview_url: origin
+      values: { name: "sponson-${ctx.scope}" }
+  where:
+    base_url: "`https://<org>.okta.com/api/v1`: your Okta org's domain"
+    app_id: "Okta Admin Console → Applications → your application: the `0oa…` id in its URL"
+    url: "the exact redirect URI the app sends on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: OK1
+    verified: true
+    text: "An API token is sent as `Authorization: SSWS <token>` (the `apiToken` security scheme; Okta recommends scoped OAuth tokens, which need `private_key_jwt` and are not supported here). Every path is under `https://<org>.okta.com/api/v1`."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK2
+    verified: true
+    text: "`PUT /api/v1/apps/{appId}` replaces an application: all required properties must be in the body (no partial update), and system-assigned properties (`id`, `name`, `status`, `created`, `lastUpdated`) in the body are ignored. So the recipe sends the whole application read with `GET /api/v1/apps/{appId}` back, with one URI added or removed (`parent.send: parent`)."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK3
+    verified: true
+    text: "An OIDC application keeps its redirect URIs in `settings.oauthClient.redirect_uris` and its sign-out redirect URIs in `settings.oauthClient.post_logout_redirect_uris`, both arrays of strings."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK4
+    verified: false
+    text: "The read-only members of the GET answer that the replace documentation does not list (`_links`, `_embedded`, `credentials.oauthClient.client_id`) are ignored when sent back, as the listed system-assigned ones are."
+  - id: OK5
+    verified: false
+    text: "The application replace has no precondition: the line locks the application (`lockOn`, shared by both URI ops) against other Sponson runs; a console edit made between the read and the write can still be lost (the next apply reports it as drift)."
+  - id: OK6
+    verified: true
+    text: "`POST /api/v1/trustedOrigins` creates a trusted origin from `name`, `origin` and `scopes` (`[{ type: CORS }, { type: REDIRECT }]`, or `IFRAME_EMBED`); `GET /api/v1/trustedOrigins` lists them as a bare array, `q` prefix-matching `name` and `origin`, `limit` up to 200; `PUT /api/v1/trustedOrigins/{id}` replaces one; `DELETE /api/v1/trustedOrigins/{id}` answers 204. `name` and `origin` are each unique."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK7
+    verified: false
+    text: "A trusted origin is found among the first 200 that `q=<origin>` matches (pagination follows a `Link` header, which the http adapter does not read); an org with more than 200 origins starting with the same text may not find it and would see the create refused as a duplicate."
+  - id: OK8
+    verified: false
+    text: "Scopes are read back as written (`[{ type: CORS }, { type: REDIRECT }]`, no added members), so they can be compared as drift."
+  - id: OK9
+    verified: true
+    text: "`OKTA_API_TOKEN` is the variable the Okta Terraform provider reads for an API token."
+    source: https://raw.githubusercontent.com/okta/terraform-provider-okta/master/docs/index.md
+ops:
+  redirect_uri:
+    kind: list_item
+    title: OIDC application sign-in redirect URI
+    summary: "One URI in an Okta OIDC application's sign-in redirect URIs (`settings.oauthClient.redirect_uris`), such as the preview's `/login/callback`. The application is read, and written back whole with the URI added (Okta replaces applications only as a whole), under a lock on the application; removed on destroy; every other URI and setting is sent back as read."
+    covers: [okta-redirect]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (`0oa…`).
+        example: 0oa1gjh63g214q0Hq0g4
+      url:
+        type: string
+        required: true
+        pattern: "^\\S+://\\S+$"
+        description: "The redirect URI, exactly as the application sends it as `redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app/login/callback"
+    http:
+      parent: { path: "/apps/{app_id}", method: PUT, send: parent }
+      list_path: /settings/oauthClient/redirect_uris
+      item: { param: url }
+    sim:
+      objects:
+        "/apps/{app_id}":
+          id: 0oa1gjh63g214q0Hq0g4
+          name: oidc_client
+          label: Web app
+          status: ACTIVE
+          signOnMode: OPENID_CONNECT
+          credentials: { oauthClient: { client_id: 0oa1gjh63g214q0Hq0g4, token_endpoint_auth_method: client_secret_basic } }
+          settings:
+            oauthClient:
+              application_type: web
+              grant_types: [authorization_code]
+              response_types: [code]
+              redirect_uris: [https://app.example.com/login/callback]
+              post_logout_redirect_uris: [https://app.example.com]
+    live:
+      params: { app_id: SPONSON_LIVE_OKTA_APP_ID }
+  post_logout_redirect_uri:
+    kind: list_item
+    title: OIDC application sign-out redirect URI
+    summary: "One URI in an Okta OIDC application's sign-out redirect URIs (`settings.oauthClient.post_logout_redirect_uris`), such as the preview's home page. Written back with the whole application, under the application's lock; removed on destroy; every other URI and setting is sent back as read."
+    covers: [okta-redirect]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (`0oa…`).
+        example: 0oa1gjh63g214q0Hq0g4
+      url:
+        type: string
+        required: true
+        pattern: "^\\S+://\\S+$"
+        description: "The URI the application passes as `post_logout_redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent: { path: "/apps/{app_id}", method: PUT, send: parent }
+      list_path: /settings/oauthClient/post_logout_redirect_uris
+      item: { param: url }
+    sim:
+      objects:
+        "/apps/{app_id}":
+          id: 0oa1gjh63g214q0Hq0g4
+          name: oidc_client
+          label: Web app
+          status: ACTIVE
+          signOnMode: OPENID_CONNECT
+          credentials: { oauthClient: { client_id: 0oa1gjh63g214q0Hq0g4, token_endpoint_auth_method: client_secret_basic } }
+          settings:
+            oauthClient:
+              application_type: web
+              grant_types: [authorization_code]
+              response_types: [code]
+              redirect_uris: [https://app.example.com/login/callback]
+              post_logout_redirect_uris: [https://app.example.com]
+    live:
+      params: { app_id: SPONSON_LIVE_OKTA_APP_ID }
+  trusted_origin:
+    kind: resource
+    title: Trusted origin (CORS and redirect)
+    summary: "A trusted origin for the preview, so the Okta Sign-In Widget and Auth JS may call Okta from it (CORS) and Okta may redirect to it after sign-in or sign-out (REDIRECT). Found by its origin; its name and scopes are compared as drift and replaced with `PUT`; deleted on destroy."
+    covers: [okta-redirect]
+    params:
+      name:
+        type: string
+        required: true
+        description: "The trusted origin's name, unique in the org."
+        example: "sponson-${ctx.scope}"
+      origin:
+        type: string
+        required: true
+        pattern: "^\\S+://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`); unique in the org."
+        example: "https://${ctx.scope}.preview.example.app"
+      scopes:
+        type: list
+        default: [{ type: CORS }, { type: REDIRECT }]
+        description: "What the origin is trusted for: `[{ type: CORS }]`, `[{ type: REDIRECT }]`, both (the default), or `IFRAME_EMBED`."
+    http:
+      find:
+        path: "/trustedOrigins?q={origin}&limit=200"
+        list_path: ""
+        match: { origin: { param: origin } }
+      create: { path: /trustedOrigins }
+      update: { method: PUT, path: "/trustedOrigins/{id}" }
+      delete: { path: "/trustedOrigins/{id}" }
+      item_path: ""
+      fields:
+        name: { param: name }
+        origin: { param: origin }
+        scopes: { param: scopes }

package/recipes/posthog.yaml

@@ -0,0 +1,127 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# PostHog private API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: posthog
+title: PostHog
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Private API (hosts, personal API keys)
+    url: https://posthog.com/docs/api
+  - title: Feature flags API
+    url: https://posthog.com/docs/api/feature-flags
+  - title: OpenAPI schema (FeatureFlag, PersonalAPIKeyAuth)
+    url: https://us.posthog.com/api/schema/?format=json
+  - title: Feature flag serializer (filters validation and merge)
+    url: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/feature_flag.py
+  - title: Feature flag filters schema (condition groups)
+    url: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/filters_schema.py
+api:
+  base_url: https://us.posthog.com
+  base_url_env: POSTHOG_API_URL
+  auth: { bearer_env: POSTHOG_PERSONAL_API_KEY }
+detect:
+  deps: [posthog-js, posthog-node, posthog-react-native]
+  env: ["POSTHOG_*"]
+  starter:
+    - op: release_condition
+      values: { property: $host }
+  where:
+    project_id: "PostHog → Settings → Project → Project ID"
+    flag_id: "PostHog → Feature flags → your flag: the number in its URL"
+    value: "the preview's host name (with `property: $host`)"
+assumptions:
+  - id: PH1
+    verified: true
+    text: "The private API is at `https://us.posthog.com` (US cloud) or `https://eu.posthog.com` (EU cloud; set `base_url`), authenticated with a personal API key as `Authorization: Bearer`, with the `feature_flag:read` and `feature_flag:write` scopes."
+    source: https://posthog.com/docs/api
+  - id: PH2
+    verified: true
+    text: "`GET /api/projects/{project_id}/feature_flags/{id}/` (trailing slash) answers the flag bare, with its release conditions in `filters.groups`; `PATCH` on the same path updates it and answers it bare."
+    source: https://us.posthog.com/api/schema/?format=json
+  - id: PH3
+    verified: true
+    text: "A condition group is `{ properties: [{ key, type, operator, value }], rollout_percentage, variant }`; `exact` takes a list of values. Groups have no id, so the group is identified by the first value of its first property (the preview host)."
+    source: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/filters_schema.py
+  - id: PH4
+    verified: true
+    text: "A PATCH of `filters` merges top-level keys into the stored filters (`{**stored_filters, **filters}`): sending `{ filters: { groups } }` replaces the groups and keeps `multivariate`, `payloads` and the rest. This is in the serializer's source, not the docs."
+    source: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/feature_flag.py
+  - id: PH5
+    verified: false
+    text: "Self-hosted or older PostHog versions merge `filters` the same way (the merge arrived with 2026's validation work). On a version that replaces `filters` whole, every write would drop the flag's variants and payloads: check before pointing the recipe at one."
+  - id: PH6
+    verified: false
+    text: "A group is read back as written (the serializer drops unknown keys and adds none to the declared ones), so the compared `properties`, `rollout_percentage` and `variant` do not show as changed on every plan."
+  - id: PH7
+    verified: true
+    text: "A flag under an approval policy answers a PATCH with 409 (`approval_required` or `change_request_pending`); the apply then fails with PROVIDER_CONFLICT rather than waiting for the approval."
+    source: https://github.com/PostHog/posthog/blob/master/products/approvals/backend/decorators.py
+ops:
+  release_condition:
+    kind: list_item
+    title: Flag release condition
+    summary: "A release condition (condition group) on an existing feature flag that matches the preview, such as `$host exact [pr-42.preview.example.com]` at 100%. Groups are OR'd; the flag's other groups, variants and payloads are left as they are. A console edit of its properties, rollout or variant is drift. Destroy removes the group (with the last group gone, the flag matches no one)."
+    covers: [posthog-release-condition]
+    params:
+      project_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The project's numeric id (Project settings).
+        example: "12345"
+      flag_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The flag's numeric id (in the flag's URL), not its key.
+        example: "678"
+      property:
+        type: string
+        required: true
+        description: The property the condition tests. It must be known when the flag is evaluated (a person property, or one passed with the evaluation).
+        example: $host
+      property_type:
+        type: string
+        default: person
+        enum: [person, group]
+        description: Whether `property` is a person or a group property.
+      operator:
+        type: string
+        default: exact
+        enum: [exact, is_not, icontains, regex]
+        description: How the property is compared with `value`.
+      value:
+        type: string
+        required: true
+        description: The value that matches the preview (such as its host); it identifies the condition on the flag.
+        example: "${ctx.scope}.preview.example.com"
+      rollout_percentage:
+        type: integer
+        default: 100
+        description: The share of matching users the flag is on for (0–100).
+      variant:
+        type: string
+        description: For a multivariate flag, the variant the condition serves.
+    http:
+      parent: { path: "/api/projects/{project_id}/feature_flags/{flag_id}/", method: PATCH }
+      list_path: /filters/groups
+      key_field: /properties/0/value/0
+      item:
+        properties:
+          - key: { param: property }
+            type: { param: property_type }
+            operator: { param: operator }
+            value: [{ param: value }]
+        rollout_percentage: { param: rollout_percentage }
+        variant: { param: variant }
+    sim:
+      objects:
+        "/api/projects/{project_id}/feature_flags/{flag_id}":
+          id: 678
+          key: new-checkout
+          filters:
+            groups: [{ properties: [], rollout_percentage: 0 }]
+            multivariate: null
+            payloads: {}
+    live:
+      params: { project_id: SPONSON_LIVE_POSTHOG_PROJECT_ID, flag_id: SPONSON_LIVE_POSTHOG_FLAG_ID }

package/recipes/postmark.yaml

@@ -0,0 +1,105 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Postmark Account API recipes (account token). The Server API, which takes a server's own token, is
+# postmark_server.yaml. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: postmark
+title: Postmark (Account API)
+category: email
+verified_on: "2026-10-11"
+docs:
+  - title: Servers API
+    url: https://postmarkapp.com/developer/api/servers-api
+  - title: API overview (authentication)
+    url: https://postmarkapp.com/developer/api/overview
+api:
+  base_url: https://api.postmarkapp.com
+  base_url_env: POSTMARK_API_URL
+  auth: { header: X-Postmark-Account-Token, value_env: POSTMARK_ACCOUNT_TOKEN }
+detect:
+  deps: [postmark]
+  env: ["POSTMARK_*"]
+  starter:
+    - op: server
+      values: { name: "sponson-${ctx.env}-${ctx.scope}" }
+assumptions:
+  - id: PM1
+    verified: true
+    text: "The Servers API authenticates with the account token in `X-Postmark-Account-Token` (account owner only) and takes and answers JSON."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM2
+    verified: true
+    text: "`POST /servers` creates a server from `Name` (required), `Color`, `DeliveryType` (`Live` or `Sandbox`, fixed after creation), `InboundHookUrl`, `TrackOpens`, `TrackLinks` and more, answering the server with its integer `ID`, its settings and `ApiTokens` (the server's tokens)."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM3
+    verified: true
+    text: "`GET /servers?count=&offset=&name=` answers `{ TotalCount, Servers: [...] }`; `name` is a substring search (`MyServer` also matches `MyServer Production`), so the recipe matches the exact `Name` among the results."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM4
+    verified: true
+    text: "`PUT /servers/{serverid}` changes the settings sent (everything but `DeliveryType`); `GET /servers/{serverid}` answers the server with its `ApiTokens`, so the server token stays readable."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM5
+    verified: true
+    text: "`DELETE /servers/{serverid}` removes a server, but is not enabled for every account: where Postmark support has not enabled it, destroy fails and the line needs `destroy: keep`."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM6
+    verified: false
+    text: "Server names are unique in the account (a second create with the same name is refused), and an account has fewer than 500 servers, so the first page of `count=500` holds the one `find` looks for."
+  - id: PM7
+    verified: false
+    text: "`Color`, `TrackOpens`, `TrackLinks` and `InboundHookUrl` are answered as sent (`InboundHookUrl` empty when unset), so they compare without drift."
+ops:
+  server:
+    kind: resource
+    title: Server
+    summary: "A Postmark server per environment, such as `sponson-preview-pr-42`, with its inbound webhook URL and tracking settings. Its token is a sensitive output for the app's environment (`{ from: <line>.server_token }`). Located by its name; a console edit of its color, tracking or inbound hook URL is drift. Its webhooks: `postmark_server.webhook` with `credential: { from: <this line>.server_token }`."
+    covers: [postmark-server-webhook]
+    params:
+      name:
+        type: string
+        required: true
+        description: The server's name, unique in the account (PM6); its identity.
+        example: "sponson-${ctx.env}-${ctx.scope}"
+      color:
+        type: string
+        default: Blue
+        enum: [Purple, Blue, Turquoise, Green, Red, Yellow, Grey, Orange]
+        description: The server's color in the Postmark dashboard.
+      delivery_type:
+        type: string
+        default: Sandbox
+        enum: [Live, Sandbox]
+        description: "`Sandbox` accepts mail without delivering it; fixed once the server exists (sent on create only)."
+      inbound_hook_url:
+        type: string
+        default: ""
+        description: The URL inbound mail is posted to (empty for none).
+        example: "https://${ctx.scope}.preview.example.com/api/postmark/inbound"
+      track_opens:
+        type: boolean
+        default: false
+        description: Track opens of outbound mail.
+      track_links:
+        type: string
+        default: None
+        enum: [None, HtmlAndText, HtmlOnly, TextOnly]
+        description: Track link clicks of outbound mail.
+    http:
+      find:
+        path: "/servers?count=500&offset=0&name={name}"
+        list_path: /Servers
+        match: { Name: { param: name } }
+      create:
+        path: /servers
+        body: { DeliveryType: { param: delivery_type } }
+      update: { method: PUT, path: "/servers/{id}" }
+      delete: { path: "/servers/{id}" }
+      id_path: /ID
+      fields:
+        Color: { param: color }
+        InboundHookUrl: { param: inbound_hook_url }
+        TrackOpens: { param: track_opens }
+        TrackLinks: { param: track_links }
+      outputs:
+        server_token: { path: /ApiTokens/0, sensitive: true }
+    sim:
+      numeric_ids: true