@sponson/adapters 0.4.0 → 0.5.0

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

package/recipes/postmark_server.yaml

@@ -0,0 +1,93 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Postmark Server API recipes (one server's token). The Account API is postmark.yaml. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: postmark_server
+title: Postmark (Server API)
+category: email
+verified_on: "2026-10-11"
+docs:
+  - title: Webhooks API
+    url: https://postmarkapp.com/developer/api/webhooks-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-Server-Token, value_env: POSTMARK_SERVER_TOKEN }
+assumptions:
+  - id: PS1
+    verified: true
+    text: "The Webhooks API authenticates with a server's token in `X-Postmark-Server-Token`, so it manages the webhooks of that one server."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS2
+    verified: true
+    text: "`POST /webhooks` creates a webhook from `Url` (required), `MessageStream` (default `outbound`), `HttpAuth`, `HttpHeaders` and `Triggers` (`Open { Enabled, PostFirstOpenOnly }`, `Click`, `Delivery`, `Bounce { Enabled, IncludeContent }`, `SpamComplaint { Enabled, IncludeContent }`, `SubscriptionChange`, each with `Enabled`), answering the webhook with its integer `ID`."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS3
+    verified: true
+    text: "`GET /webhooks` (optionally `?MessageStream=`) answers `{ Webhooks: [...] }` with each webhook's `ID`, `Url`, `MessageStream` and `Triggers`."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS4
+    verified: true
+    text: "`PUT /webhooks/{Id}` changes `Url`, `HttpAuth`, `HttpHeaders` and `Triggers` (not `MessageStream`), re-verifying the endpoint when the URL or the triggers change; `DELETE /webhooks/{Id}` removes it."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS5
+    verified: true
+    text: "Postmark tests the endpoint when a webhook is created; `Verify: false` saves it without the test (a preview that is not deployed yet would fail it)."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS6
+    verified: false
+    text: "A URL identifies one webhook of the server (two webhooks with the same URL, on different streams, make `find` refuse with PARAM_INVALID), and every trigger's `Enabled` is answered as a boolean even when it was not sent."
+  - id: PS7
+    verified: false
+    text: "`PostFirstOpenOnly` and `IncludeContent` are left at Postmark's defaults; only which events are delivered is compared."
+  - id: PS8
+    verified: false
+    text: "A server's webhooks belong to it: deleting the server (`DELETE /servers/{id}`, Account API) removes them, so a webhook line authenticated with the server's own token can leave its destroy to the server's line."
+ops:
+  webhook:
+    kind: resource
+    title: Webhook of a server
+    summary: "A webhook of one Postmark server delivering to an environment's URL, such as the preview's `/api/postmark` handler, with the events it enables. Located by its URL; a console edit of an event's `Enabled` is drift. The server is the one whose token is in `POSTMARK_SERVER_TOKEN` (a shared staging server), or, for a server the same plan creates per environment (`postmark.server`), the line says `credential: { from: <server line>.server_token }` and `destroy: keep`: deleting the server removes its webhooks (PS8)."
+    covers: [postmark-server-webhook]
+    params:
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL events are posted to; its identity (PS6).
+        example: "https://${ctx.scope}.preview.example.com/api/postmark"
+      message_stream:
+        type: string
+        default: outbound
+        description: The message stream whose events are delivered (sent on create only).
+      verify:
+        type: boolean
+        default: false
+        description: Have Postmark test the URL when the webhook is created (PS5).
+      delivery: { type: boolean, default: true, description: Deliver `Delivery` events. }
+      bounce: { type: boolean, default: true, description: Deliver `Bounce` events. }
+      spam_complaint: { type: boolean, default: true, description: Deliver `SpamComplaint` events. }
+      open: { type: boolean, default: false, description: Deliver `Open` events. }
+      click: { type: boolean, default: false, description: Deliver `Click` events. }
+      subscription_change: { type: boolean, default: false, description: Deliver `SubscriptionChange` events. }
+    http:
+      find:
+        path: /webhooks
+        list_path: /Webhooks
+        match: { Url: { param: url } }
+      create:
+        path: /webhooks
+        body: { MessageStream: { param: message_stream }, Verify: { param: verify } }
+      update: { method: PUT, path: "/webhooks/{id}" }
+      delete: { path: "/webhooks/{id}" }
+      id_path: /ID
+      fields:
+        /Triggers/Delivery/Enabled: { param: delivery }
+        /Triggers/Bounce/Enabled: { param: bounce }
+        /Triggers/SpamComplaint/Enabled: { param: spam_complaint }
+        /Triggers/Open/Enabled: { param: open }
+        /Triggers/Click/Enabled: { param: click }
+        /Triggers/SubscriptionChange/Enabled: { param: subscription_change }
+    sim:
+      numeric_ids: true

package/recipes/prisma.yaml

@@ -0,0 +1,150 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Prisma Postgres Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: prisma
+title: Prisma Postgres
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Management API OpenAPI document
+    url: https://api.prisma.io/v1/doc
+  - title: Management API guide (base URL, service tokens)
+    url: https://www.prisma.io/docs/guides/management-api-basic
+  - title: Connecting to your database (connection strings)
+    url: https://www.prisma.io/docs/postgres/database/connecting-to-your-database
+api:
+  base_url: https://api.prisma.io/v1
+  base_url_env: PRISMA_API_URL
+  auth: { bearer_env: PRISMA_SERVICE_TOKEN }
+detect:
+  deps: ["@prisma/ppg"]
+  db_hosts: [.prisma.io, .prisma-data.net]
+  starter:
+    - op: database
+      values: { name: "app-${ctx.scope}" }
+  where:
+    project_id: "Prisma Console → your project → Settings → Project ID"
+assumptions:
+  - id: PP1
+    verified: true
+    text: "The Management API at `https://api.prisma.io/v1` authenticates with a workspace service token as `Authorization: Bearer`; Prisma's guide keeps it in `PRISMA_SERVICE_TOKEN`."
+    source: https://www.prisma.io/docs/guides/management-api-basic
+  - id: PP2
+    verified: true
+    text: "Answers are enveloped: one object as `{ data: {…} }`, a list as `{ data: [...], pagination: { nextCursor, hasMore } }`, paged with `?cursor=`."
+    source: https://api.prisma.io/v1/doc
+  - id: PP3
+    verified: true
+    text: "`POST /v1/projects/{projectId}/databases` with `{ name, region, source? }` creates a database (201); `source: { type: database, databaseId }` copies an existing one. It answers the database with `id`, `name`, `status` (`provisioning` or `ready`) and `connections[]`."
+    source: https://api.prisma.io/v1/doc
+  - id: PP4
+    verified: true
+    text: "`GET /v1/projects/{projectId}/databases` lists the project's databases with `id` and `name`; it has no name filter, so the list is searched page by page."
+    source: https://api.prisma.io/v1/doc
+  - id: PP5
+    verified: false
+    text: "Database names are not unique (the project-scoped create documents no 409), so two databases with one name make `find.match` ambiguous, which is refused with PARAM_INVALID rather than guessed. Sponson never creates a second one: it looks the name up before every create."
+    source: https://api.prisma.io/v1/doc
+  - id: PP6
+    verified: true
+    text: "`GET /v1/databases/{databaseId}` answers the database (404 when it does not exist); `DELETE` on the same path deletes it (204; 404 when gone; 403 for a project's default database)."
+    source: https://api.prisma.io/v1/doc
+  - id: PP7
+    verified: false
+    text: "The connection strings (`connections[0].endpoints.direct.connectionString`, and `.pooled` when there is a pooled endpoint) are in the create answer only: list and get answer the endpoints' host and port without them. So they are once-only outputs (ADR 0018), and a create whose answer was lost leaves dependents to be refused until the database is recreated. Inferred from the schemas; not stated in the docs."
+    source: https://api.prisma.io/v1/doc
+  - id: PP8
+    verified: false
+    text: "`connections[0]` is the database's default connection, present in every create answer."
+    source: https://api.prisma.io/v1/doc
+  - id: PP9
+    verified: false
+    text: "A database answered with `status: provisioning` accepts connections within seconds; nothing waits for `ready` (the API has no readiness the http adapter can poll), so a dependent deployment that starts at once may see connection errors for that long."
+    source: https://api.prisma.io/v1/doc
+  - id: PP10
+    verified: true
+    text: "Connection strings have the form `postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require` (direct) and `postgres://USER:PASSWORD@pooled.db.prisma.io:5432/?sslmode=require` (pooled)."
+    source: https://www.prisma.io/docs/postgres/database/connecting-to-your-database
+ops:
+  database:
+    kind: resource
+    title: Database
+    summary: "An empty Postgres database per scope in a Prisma Postgres project, such as `app-pr-42`. Its connection strings exist only in the create answer, so they are once-only outputs: reference them from the line that needs them (an env var) in the same plan. Located by name; only its existence is compared for drift; destroy deletes it and its data."
+    covers: [prisma-postgres-database]
+    params:
+      project_id:
+        type: string
+        required: true
+        description: The project's id.
+        example: proj_cm1a2b3c4d5e6f7g8h9
+      name:
+        type: string
+        required: true
+        description: The database's name.
+        example: "app-${ctx.scope}"
+      region:
+        type: string
+        default: us-east-1
+        enum: [us-east-1, us-west-1, eu-west-3, eu-central-1, ap-northeast-1, ap-southeast-1]
+        description: Where it runs.
+    http:
+      find:
+        path: "/projects/{project_id}/databases"
+        list_path: /data
+        next: /pagination/nextCursor
+        match: { name: { param: name } }
+      read: { path: "/databases/{id}" }
+      create:
+        path: "/projects/{project_id}/databases"
+        body: { region: { param: region } }
+      item_path: /data
+      outputs:
+        status: /status
+        direct_url: { path: /connections/0/endpoints/direct/connectionString, sensitive: true, once: true }
+        pooled_url: { path: /connections/0/endpoints/pooled/connectionString, sensitive: true, once: true }
+    live:
+      params: { project_id: SPONSON_LIVE_PRISMA_PROJECT_ID }
+  database_copy:
+    kind: resource
+    title: Database copied from another
+    summary: "A Postgres database per scope copied from an existing one (`source: { type: database }`), such as `app-pr-42` with the data of `app`. Otherwise like `prisma.database`: once-only connection strings, existence-only drift, destroy deletes the copy (never the source)."
+    covers: [prisma-postgres-database]
+    params:
+      project_id:
+        type: string
+        required: true
+        description: The project's id.
+        example: proj_cm1a2b3c4d5e6f7g8h9
+      name:
+        type: string
+        required: true
+        description: The new database's name.
+        example: "app-${ctx.scope}"
+      source_database_id:
+        type: string
+        required: true
+        description: The id of the database to copy.
+        example: db_cm9z8y7x6w5v4u3t2s1
+      region:
+        type: string
+        default: us-east-1
+        enum: [us-east-1, us-west-1, eu-west-3, eu-central-1, ap-northeast-1, ap-southeast-1]
+        description: Where it runs.
+    http:
+      find:
+        path: "/projects/{project_id}/databases"
+        list_path: /data
+        next: /pagination/nextCursor
+        match: { name: { param: name } }
+      read: { path: "/databases/{id}" }
+      create:
+        path: "/projects/{project_id}/databases"
+        body:
+          region: { param: region }
+          source: { type: database, databaseId: { param: source_database_id } }
+      item_path: /data
+      outputs:
+        status: /status
+        direct_url: { path: /connections/0/endpoints/direct/connectionString, sensitive: true, once: true }
+        pooled_url: { path: /connections/0/endpoints/pooled/connectionString, sensitive: true, once: true }
+    live:
+      params: { project_id: SPONSON_LIVE_PRISMA_PROJECT_ID, source_database_id: SPONSON_LIVE_PRISMA_DATABASE_ID }