@sponson/adapters 0.4.0 → 0.6.0

package/recipes/stripe.yaml

@@ -0,0 +1,310 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Stripe API v1 recipes: a test-mode webhook endpoint per preview, and the catalog objects (products, prices,
+# coupons) a preview's code expects. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: stripe
+title: Stripe
+category: webhooks
+verified_on: "2026-10-11"
+docs:
+  - title: Authentication
+    url: https://docs.stripe.com/api/authentication
+  - title: API keys
+    url: https://docs.stripe.com/keys
+  - title: Idempotent requests
+    url: https://docs.stripe.com/api/idempotent_requests
+  - title: Create a webhook endpoint
+    url: https://docs.stripe.com/api/webhook_endpoints/create
+  - title: List all webhook endpoints
+    url: https://docs.stripe.com/api/webhook_endpoints/list
+  - title: Update a webhook endpoint
+    url: https://docs.stripe.com/api/webhook_endpoints/update
+  - title: Delete a webhook endpoint
+    url: https://docs.stripe.com/api/webhook_endpoints/delete
+  - title: Webhooks in the Dashboard (endpoint limit)
+    url: https://docs.stripe.com/development/dashboard/webhooks
+  - title: Create a product
+    url: https://docs.stripe.com/api/products/create
+  - title: Retrieve a product
+    url: https://docs.stripe.com/api/products/retrieve
+  - title: Delete a product
+    url: https://docs.stripe.com/api/products/delete
+  - title: Create a price
+    url: https://docs.stripe.com/api/prices/create
+  - title: List all prices
+    url: https://docs.stripe.com/api/prices/list
+  - title: Update a price
+    url: https://docs.stripe.com/api/prices/update
+  - title: Create a coupon
+    url: https://docs.stripe.com/api/coupons/create
+api:
+  base_url: https://api.stripe.com/v1
+  base_url_env: STRIPE_API_URL
+  auth: { bearer_env: STRIPE_SECRET_KEY }
+  encoding: form
+  # A preview must never create live-mode objects (ST2): live keys are refused unless this variable says otherwise.
+  refuse_credential: { prefixes: [sk_live_, rk_live_], unless_env: SPONSON_STRIPE_ALLOW_LIVE }
+detect:
+  deps: [stripe, "@stripe/"]
+  env: ["STRIPE_*"]
+  starter:
+    - op: webhook_endpoint
+      preview_url: url
+      values: { name: "preview-${ctx.scope}" }
+assumptions:
+  - id: ST1
+    verified: true
+    text: "The API takes a secret or restricted key as `Authorization: Bearer` (besides Basic), and request bodies form-encoded with bracketed nesting (`metadata[k]=v`, `enabled_events[0]=x`)."
+    source: https://docs.stripe.com/api/authentication
+  - id: ST2
+    verified: true
+    text: "Test-mode keys start with `sk_test_` / `rk_test_`, live-mode keys with `sk_live_` / `rk_live_`; objects of one mode are invisible to the other. The recipe refuses the live prefixes (`refuse_credential`) unless `SPONSON_STRIPE_ALLOW_LIVE=1`."
+    source: https://docs.stripe.com/keys
+  - id: ST3
+    verified: false
+    text: "Organization keys (`sk_org_…`) and platform-managed keys do not carry the mode in their prefix, so they are not refused: use a test-mode secret or restricted key for previews."
+  - id: ST4
+    verified: true
+    text: "Every v1 `POST` accepts an `Idempotency-Key` (up to 255 characters, kept at least 24 hours); a retry with the same key returns the saved answer, and different parameters under one key are an error."
+    source: https://docs.stripe.com/api/idempotent_requests
+  - id: ST5
+    verified: true
+    text: "`POST /v1/webhook_endpoints` takes `url`, `enabled_events` (`['*']` for all), `description`, `metadata` and `api_version`, and answers the endpoint with its signing `secret` populated."
+    source: https://docs.stripe.com/api/webhook_endpoints/create
+  - id: ST6
+    verified: true
+    text: "`GET /v1/webhook_endpoints` (`limit` 1–100) answers `{ data: [...], has_more }` whose endpoints carry `url`, `enabled_events`, `description` and `metadata` but no `secret`: the secret exists only in the create's answer, hence the `once` output."
+    source: https://docs.stripe.com/api/webhook_endpoints/list
+  - id: ST7
+    verified: true
+    text: "An account has at most 16 webhook endpoints, so one list page of 100 holds them all, and at most 16 previews (minus the account's own endpoints) can have one at a time."
+    source: https://docs.stripe.com/development/dashboard/webhooks
+  - id: ST8
+    verified: true
+    text: "`POST /v1/webhook_endpoints/{id}` updates `url`, `enabled_events`, `description`, `metadata` and `disabled` in place (the secret is not rotated); `DELETE` on the same path removes the endpoint."
+    source: https://docs.stripe.com/api/webhook_endpoints/update
+  - id: ST9
+    verified: false
+    text: "The API returns `url`, `enabled_events` and `description` as they were written, `enabled_events` in the order sent, so an unchanged endpoint hashes the same on every plan."
+  - id: ST10
+    verified: true
+    text: "`POST /v1/products` takes a client-chosen `id` (unique among the account's products), `name`, `description` and `active`; `GET /v1/products/{id}` retrieves it; `POST /v1/products/{id}` updates it."
+    source: https://docs.stripe.com/api/products/create
+  - id: ST11
+    verified: true
+    text: "A product can be deleted only while it has no prices, and prices are never deleted, so the recipe archives a product (`active: false`) instead of deleting it."
+    source: https://docs.stripe.com/api/products/delete
+  - id: ST12
+    verified: false
+    text: "An archived product is still returned by `GET /v1/products/{id}`, and its id stays taken: re-applying a destroyed scope finds it and reactivates it as an adopted object, which a later destroy leaves active."
+  - id: ST13
+    verified: true
+    text: "`POST /v1/prices` takes `product`, `currency`, `unit_amount`, `recurring[interval]`, `nickname`, `lookup_key` and `transfer_lookup_key` (which moves the lookup key from the price holding it to the new one)."
+    source: https://docs.stripe.com/api/prices/create
+  - id: ST14
+    verified: true
+    text: "`GET /v1/prices` lists active prices by default, filters by up to 10 `lookup_keys` and by `active`, and answers `{ data: [...] }`."
+    source: https://docs.stripe.com/api/prices/list
+  - id: ST15
+    verified: true
+    text: "A price's amount, currency and interval cannot change after creation; `POST /v1/prices/{id}` updates `active`, `nickname`, `lookup_key` and `metadata`. There is no delete: the recipe archives (`active: false`)."
+    source: https://docs.stripe.com/api/prices/update
+  - id: ST16
+    verified: true
+    text: "`POST /v1/coupons` takes a client-chosen `id`, `name`, `percent_off` or `amount_off` with `currency`, `duration` (`once`, `repeating`, `forever`) and `duration_in_months`."
+    source: https://docs.stripe.com/api/coupons/create
+  - id: ST17
+    verified: false
+    text: "`GET /v1/coupons/{id}` retrieves a coupon, `POST /v1/coupons/{id}` updates its `name` and `metadata` only (the discount is fixed), and `DELETE /v1/coupons/{id}` deletes it, after which its id may be used again."
+    source: https://docs.stripe.com/api/coupons/create
+  - id: ST18
+    verified: false
+    text: "Stripe must reach the endpoint's URL over public HTTPS: a preview behind deployment protection (Vercel Authentication) receives no events unless it lets Stripe's requests through."
+ops:
+  webhook_endpoint:
+    kind: resource
+    title: Webhook endpoint
+    summary: "A test-mode webhook endpoint that sends the preview's events to its own URL, `url` + `path` (usually `{ from: web.preview_url }`). Identified by `name` in its metadata, so a new preview URL updates the endpoint in place. Its signing `secret` exists only in the answer that creates the endpoint: it is a once-only output, passed in the same run to the line that writes it (`STRIPE_WEBHOOK_SECRET` in a `vercel.env` or `netlify.env` line); later runs keep what that line holds, and `apply --recreate <line>` rotates it. Writing the secret rebuilds the preview, and a preview URL output follows the newest deploy, so the next run moves the endpoint to the rebuilt deploy's URL (in place: the secret is kept); a URL that does not change per deploy (`https://deploy-preview-${ctx.pr.number}--<site>.netlify.app`, a custom preview domain) avoids that update. A console edit of its URL, events or description is drift."
+    covers: [stripe-webhook]
+    params:
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_.:/-]{1,200}$"
+        description: "The endpoint's identity, kept in its metadata (`sponson_endpoint`): unique per preview, such as `preview-${ctx.scope}`."
+        example: "preview-${ctx.scope}"
+      url:
+        type: string
+        required: true
+        pattern: "^https://\\S*[^/]$"
+        description: "The preview's base URL, without a trailing slash: usually `{ from: <vercel.env or netlify.env line>.preview_url }`."
+        example: https://pr-42.preview.example.com
+      path:
+        type: string
+        default: /api/webhooks/stripe
+        pattern: "^/\\S*$"
+        description: The path of the app's webhook handler, appended to `url`.
+      enabled_events:
+        type: list
+        default: ["*"]
+        description: "The event types sent to the endpoint (`['*']`: all that need no explicit selection)."
+        example: [checkout.session.completed, customer.subscription.updated]
+      description:
+        type: string
+        description: A note shown in the Dashboard.
+        example: Preview webhook managed by Sponson
+      api_version:
+        type: string
+        description: The Stripe API version events are rendered with (the account's default when left out); sent on create only.
+    http:
+      find:
+        path: /webhook_endpoints?limit=100
+        list_path: /data
+        match: { /metadata/sponson_endpoint: { param: name } }
+      create:
+        path: /webhook_endpoints
+        idempotency_key: true
+        body: { api_version: { param: api_version } }
+      update: { method: POST, path: "/webhook_endpoints/{id}" }
+      delete: { path: "/webhook_endpoints/{id}" }
+      fields:
+        url: { join: [{ param: url }, { param: path }] }
+        enabled_events: { param: enabled_events }
+        description: { param: description }
+      outputs:
+        secret: { path: /secret, sensitive: true, once: true }
+    live:
+      params: { url: SPONSON_LIVE_STRIPE_WEBHOOK_URL }
+  product:
+    kind: resource
+    title: Product
+    summary: "A test-mode product with an id of the plan's choosing, such as `pro-pr-42`, for the prices a preview sells. Destroy archives it (`active: false`): Stripe never deletes a product that has prices. A console edit of its name, description or active flag is drift."
+    covers: [stripe-test-objects]
+    params:
+      product_id:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_-]{1,100}$"
+        description: The product's id, unique in the account, such as `pro-${ctx.scope}`.
+        example: "pro-${ctx.scope}"
+      name:
+        type: string
+        required: true
+        description: The product's name, shown to customers.
+        example: Pro (preview)
+      description:
+        type: string
+        description: The product's description, shown to customers.
+    http:
+      read: { path: "/products/{product_id}" }
+      create: { path: /products, idempotency_key: true, body: { id: { param: product_id } } }
+      update: { method: POST }
+      delete: { method: POST, body: { active: false } }
+      fields:
+        name: { param: name }
+        description: { param: description }
+        active: true
+  price:
+    kind: resource
+    title: Price
+    summary: "A test-mode price found by its lookup key (`lookup`, such as `pro-monthly-pr-42`, which the preview's code looks the price up by), product, currency, amount and interval. Amount, currency and interval cannot change on a Stripe price, so changing them in the plan makes a new price that takes over the lookup key, and the old one stays until the scope is destroyed. Destroy archives it (`active: false`): Stripe never deletes a price. A console edit of its nickname is drift."
+    covers: [stripe-test-objects]
+    params:
+      lookup:
+        type: string
+        required: true
+        pattern: "^\\S{1,200}$"
+        description: "The price's `lookup_key`: what the preview's code looks it up by, unique among active prices. (Named `lookup` because a plan key ending in `_key` must hold a secret reference.)"
+        example: "pro-monthly-${ctx.scope}"
+      product:
+        type: string
+        required: true
+        description: "The product's id: usually `{ from: <stripe.product line>.id }`."
+        example: pro-pr-42
+      currency:
+        type: string
+        required: true
+        pattern: "^[a-z]{3}$"
+        description: Three-letter ISO currency code, lower-case.
+        example: usd
+      unit_amount:
+        type: integer
+        required: true
+        description: The amount in the currency's smallest unit (1500 is 15.00 USD).
+        example: 1500
+      interval:
+        type: string
+        enum: [day, week, month, year]
+        description: The billing interval of a recurring price; left out, the price is one-time.
+        example: month
+      nickname:
+        type: string
+        description: A note on the price, hidden from customers.
+        example: Pro monthly (preview)
+    http:
+      find:
+        path: "/prices?lookup_keys[]={lookup}&active=true&limit=10"
+        list_path: /data
+        match:
+          lookup_key: { param: lookup }
+          active: true
+          product: { param: product }
+          currency: { param: currency }
+          unit_amount: { param: unit_amount }
+          /recurring/interval: { param: interval }
+      create: { path: /prices, idempotency_key: true, body: { transfer_lookup_key: true } }
+      update: { method: POST, path: "/prices/{id}" }
+      delete: { method: POST, path: "/prices/{id}", body: { active: false } }
+      fields:
+        nickname: { param: nickname }
+    live:
+      params: { product: SPONSON_LIVE_STRIPE_PRODUCT }
+  coupon:
+    kind: resource
+    title: Coupon
+    summary: "A test-mode coupon with an id of the plan's choosing, such as `preview-pr-42`, for the discount codes a preview accepts. Its discount (percent or amount, duration) is set on create and fixed after; give the line a new `coupon_id` to change it. Destroy deletes it. A console edit of its name is drift."
+    covers: [stripe-test-objects]
+    params:
+      coupon_id:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_-]{1,100}$"
+        description: The coupon's id (the code applied to a customer), unique in the account.
+        example: "preview-${ctx.scope}"
+      percent_off:
+        type: number
+        description: The discount in percent (0–100); or set `amount_off` and `currency`.
+        example: 25
+      amount_off:
+        type: integer
+        description: The discount in the currency's smallest unit, with `currency`.
+      currency:
+        type: string
+        pattern: "^[a-z]{3}$"
+        description: The currency of `amount_off`.
+      duration:
+        type: string
+        enum: [once, repeating, forever]
+        default: once
+        description: How long the discount applies to a subscription.
+      duration_in_months:
+        type: integer
+        description: "For `duration: repeating`, the number of months."
+      name:
+        type: string
+        description: The name shown to customers (the id when left out).
+        example: Preview discount
+    http:
+      read: { path: "/coupons/{coupon_id}" }
+      create:
+        path: /coupons
+        idempotency_key: true
+        body:
+          id: { param: coupon_id }
+          percent_off: { param: percent_off }
+          amount_off: { param: amount_off }
+          currency: { param: currency }
+          duration: { param: duration }
+          duration_in_months: { param: duration_in_months }
+      update: { method: POST }
+      fields:
+        name: { param: name }

package/recipes/stytch.yaml

@@ -0,0 +1,113 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Stytch Programmatic Workspace Actions (management API v3) recipes. Format and checklist: docs/adr/0020-recipes.md,
+# CONTRIBUTING.md "Adding a recipe".
+provider: stytch
+title: Stytch
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Create redirect URL (PWA v3)
+    url: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/create-redirect-url
+  - title: Get all redirect URLs (PWA v3)
+    url: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/get-all-redirect-urls
+  - title: Get redirect URL (PWA v3)
+    url: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/get-redirect-url
+  - title: Update redirect URL (PWA v3)
+    url: https://stytch.com/docs/workspace-management/pwa/update-redirect-url
+  - title: Delete redirect URL (PWA v3)
+    url: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/delete-redirect-url
+  - title: Limits
+    url: https://stytch.com/docs/workspace-management/pwa/limits
+api:
+  base_url: https://management.stytch.com
+  base_url_env: STYTCH_MANAGEMENT_API_URL
+  auth: { basic: { user_env: STYTCH_WORKSPACE_KEY_ID, password_env: STYTCH_WORKSPACE_KEY_SECRET } }
+detect:
+  deps: [stytch, "@stytch/"]
+  env: ["STYTCH_*"]
+  starter:
+    - op: redirect_url
+  where:
+    project_slug: "Stytch Dashboard → Project settings: the project's slug"
+    url: "the exact redirect URL Stytch receives on a preview: its URL plus the path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: SY1
+    verified: true
+    text: "The management API authenticates with HTTP Basic: a workspace management key's id as the user and its secret as the password."
+    source: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/create-redirect-url
+  - id: SY2
+    verified: true
+    text: "`POST /pwa/v3/projects/{project_slug}/environments/{environment_slug}/redirect_urls` takes `url`, `valid_types` (`{ type, is_default }`, type one of LOGIN, INVITE, SIGNUP, RESET_PASSWORD, DISCOVERY) and `do_not_promote_defaults`, and answers `{ request_id, redirect_url: { url, valid_types }, status_code }`."
+    source: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/create-redirect-url
+  - id: SY3
+    verified: true
+    text: "`GET …/redirect_urls/all` answers `{ redirect_urls: [{ url, valid_types }], … }`: every redirect URL of the environment, unpaged."
+    source: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/get-all-redirect-urls
+  - id: SY4
+    verified: true
+    text: "A redirect URL has no id of its own: `GET`, `PUT` (to change `valid_types`) and `DELETE` on `…/redirect_urls?url=<url>` address it by its URL."
+    source: https://stytch.com/docs/api-reference/pwa/api/v3/redirect-urls/delete-redirect-url
+  - id: SY5
+    verified: true
+    text: "A project has at most 100 redirect URLs."
+    source: https://stytch.com/docs/workspace-management/pwa/limits
+  - id: SY6
+    verified: false
+    text: "`do_not_promote_defaults: true` on create and delete keeps a preview URL from becoming, or a deletion from changing, the environment's default for a type."
+  - id: SY7
+    verified: false
+    text: "A `PUT` body that also carries `url` (the adapter sends the identifying field back on PUT) is accepted, and `valid_types` read back in the order and form they were written, so an unchanged URL hashes the same on every plan."
+  - id: SY8
+    verified: false
+    text: "Each redirect URL is its own object (no shared list to rewrite), so concurrent previews need no lock."
+ops:
+  redirect_url:
+    kind: resource
+    title: Redirect URL
+    summary: "One redirect URL of a Stytch project environment, such as the preview's `/authenticate`, with the redirect types it is valid for (by default login and sign-up, never the default). Found by its URL; a console edit of its types is drift and is put back with a `PUT`. Destroy deletes it without promoting another URL to default."
+    covers: [stytch-redirect]
+    params:
+      project_slug:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_-]+$"
+        description: The project's slug.
+        example: my-app
+      environment_slug:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9_-]+$"
+        description: The environment's slug within the project (its test environment, or a custom one).
+        example: test
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The redirect URL, exactly as Stytch will receive it (`https://pr-42.preview.example.com/authenticate`)."
+        example: "https://${ctx.scope}.preview.example.com/authenticate"
+      valid_types:
+        type: list
+        default: [{ type: LOGIN, is_default: false }, { type: SIGNUP, is_default: false }]
+        description: "The redirect types the URL is valid for: `{ type, is_default }` with type LOGIN, INVITE, SIGNUP, RESET_PASSWORD or DISCOVERY."
+    http:
+      find:
+        path: "/pwa/v3/projects/{project_slug}/environments/{environment_slug}/redirect_urls/all"
+        list_path: /redirect_urls
+        match: { url: { param: url } }
+      create:
+        path: "/pwa/v3/projects/{project_slug}/environments/{environment_slug}/redirect_urls"
+        body: { do_not_promote_defaults: true }
+      update:
+        method: PUT
+        path: "/pwa/v3/projects/{project_slug}/environments/{environment_slug}/redirect_urls?url={id}"
+        body: { do_not_promote_defaults: true }
+      delete:
+        path: "/pwa/v3/projects/{project_slug}/environments/{environment_slug}/redirect_urls?url={id}&do_not_promote_defaults=true"
+      item_path: /redirect_url
+      id_path: /url
+      fields:
+        valid_types: { param: valid_types }
+    sim:
+      item_query: url
+    live:
+      params: { project_slug: SPONSON_LIVE_STYTCH_PROJECT_SLUG, environment_slug: SPONSON_LIVE_STYTCH_ENVIRONMENT_SLUG }

package/recipes/svix.yaml

@@ -0,0 +1,109 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Svix API recipes (Svix as the webhook sender). Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md
+# "Adding a recipe".
+provider: svix
+title: Svix
+category: webhooks
+verified_on: "2026-10-11"
+docs:
+  - title: Svix API reference (OpenAPI document)
+    url: https://api.svix.com/api/v1/openapi.json
+  - title: Svix API reference
+    url: https://api.svix.com/docs
+  - title: Entities overview (ids and uids)
+    url: https://docs.svix.com/overview
+api:
+  base_url: https://api.us.svix.com
+  base_url_env: SVIX_API_URL
+  auth: { bearer_env: SVIX_AUTH_TOKEN }
+detect:
+  deps: [svix]
+  env: ["SVIX_*"]
+  starter:
+    - op: endpoint
+      values: { uid: "sponson-${ctx.env}-${ctx.scope}" }
+  where:
+    app_id: "Svix dashboard → Applications: the application (customer) the previews receive as"
+    url: "the preview's webhook handler: its URL plus the handler's path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: SV1
+    verified: true
+    text: "`POST /api/v1/app/{app_id}/endpoint` creates an endpoint from `url` (required), `uid`, `description`, `eventTypes`, `channels`, `disabled`, `metadata` and an optional `secret`, answering 201 with the endpoint (`id` `ep_…`, `uid`, `url`, …); requests carry `Authorization: Bearer <token>`."
+    source: https://api.svix.com/api/v1/openapi.json
+  - id: SV2
+    verified: true
+    text: "`GET`, `PATCH` (partial update) and `DELETE` (204) `/api/v1/app/{app_id}/endpoint/{endpoint_id}` take the endpoint's id or its uid, and `{app_id}` takes the application's id or uid."
+    source: https://api.svix.com/api/v1/openapi.json
+  - id: SV3
+    verified: true
+    text: "A uid is 1–256 characters of letters, digits, `-`, `_` and `.`, unique among the application's endpoints, so it names the endpoint for every later request and a create whose answer was lost is found by it."
+    source: https://api.svix.com/api/v1/openapi.json
+  - id: SV4
+    verified: true
+    text: "The endpoint's signing secret is generated when `secret` is null (recommended) and is readable at any time with `GET …/endpoint/{endpoint_id}/secret` (`{ key }`): it is not a once-only value, and this recipe does not output it (an endpoint answer does not carry it)."
+    source: https://api.svix.com/api/v1/openapi.json
+  - id: SV5
+    verified: true
+    text: "The API is served per region (`api.us.svix.com`, `api.eu.svix.com`, `api.ca.svix.com`, `api.au.svix.com`), and POST requests accept an `idempotency-key` header."
+    source: https://api.svix.com/api/v1/openapi.json
+  - id: SV6
+    verified: false
+    text: "A create with a uid that exists already answers 409 (the specification lists 409 for every operation without saying when), after which the endpoint is found by its uid and claimed only if an earlier intent of the same scope named it."
+  - id: SV7
+    verified: false
+    text: "`description` is answered as sent (default empty), `disabled` as a boolean and `eventTypes` as the list sent, so they compare without drift on every plan; accounts outside the US region set `base_url` in the provider block."
+ops:
+  endpoint:
+    kind: resource
+    title: Application endpoint
+    summary: An endpoint of a Svix application delivering to an environment's URL, named by a uid such as `preview-pr-42`. Its URL, description, event type filter and disabled flag are compared for drift; its signing secret stays readable in Svix (SV4).
+    covers: [svix-endpoint]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (`app_…`) or uid.
+        example: acme-customer
+      uid:
+        type: string
+        required: true
+        pattern: "^[a-zA-Z0-9\\-_.]{1,256}$"
+        description: The endpoint's uid, unique in the application; its identity.
+        example: "sponson-${ctx.env}-${ctx.scope}"
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL messages are delivered to.
+        example: "https://${ctx.scope}.preview.example.com/api/webhooks"
+      description:
+        type: string
+        default: ""
+        description: A note shown in the Svix dashboard and the application portal.
+      event_types:
+        type: list
+        description: Event type names to deliver (all when left out); at least one when set.
+      disabled:
+        type: boolean
+        default: false
+        description: Whether deliveries are paused.
+      secret:
+        type: string
+        description: "A signing secret to use instead of a generated one (`whsec_…`); sent on create only. Use `{ secret: … }`."
+    http:
+      read: { path: "/api/v1/app/{app_id}/endpoint/{uid}" }
+      create:
+        path: "/api/v1/app/{app_id}/endpoint"
+        body: { uid: { param: uid }, secret: { param: secret } }
+        idempotency_key: true
+      update: { method: PATCH, path: "/api/v1/app/{app_id}/endpoint/{id}" }
+      delete: { path: "/api/v1/app/{app_id}/endpoint/{id}" }
+      fields:
+        url: { param: url }
+        description: { param: description }
+        disabled: { param: disabled }
+        eventTypes: { param: event_types }
+    sim:
+      id_from: uid
+    live:
+      params: { app_id: SPONSON_LIVE_SVIX_APP_ID }

package/recipes/turso.yaml

@@ -0,0 +1,98 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Turso Platform API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: turso
+title: Turso
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Create database
+    url: https://docs.turso.tech/api-reference/databases/create
+  - title: Retrieve database
+    url: https://docs.turso.tech/api-reference/databases/retrieve
+  - title: Delete database
+    url: https://docs.turso.tech/api-reference/databases/delete
+  - title: Branching
+    url: https://docs.turso.tech/features/branching
+api:
+  base_url: https://api.turso.tech/v1
+  base_url_env: TURSO_API_URL
+  auth: { bearer_env: TURSO_API_TOKEN }
+detect:
+  deps: ["@libsql/client", "@tursodatabase/"]
+  env: ["TURSO_*"]
+  db_hosts: [.turso.io]
+  starter:
+    - op: database_branch
+      values: { name: "app-${ctx.scope}" }
+  where:
+    organization: "`turso org list`"
+    parent: "the database to branch from: `turso db list`"
+assumptions:
+  - id: TU1
+    verified: true
+    text: "`POST /v1/organizations/{organizationSlug}/databases` with `name`, `group` and `seed: { type: database, name: <parent> }` creates a database copied from the parent, authenticated with a Platform API token as `Authorization: Bearer`."
+    source: https://docs.turso.tech/api-reference/databases/create
+  - id: TU2
+    verified: true
+    text: "The create answers `{ database: { DbId, Hostname, Name } }` (capitalised), and 409 when a database with that name exists already."
+    source: https://docs.turso.tech/api-reference/databases/create
+  - id: TU3
+    verified: true
+    text: "`GET /v1/organizations/{organizationSlug}/databases/{databaseName}` answers `{ database: { Name, DbId, Hostname, group, … } }`, and 404 when there is none."
+    source: https://docs.turso.tech/api-reference/databases/retrieve
+  - id: TU4
+    verified: true
+    text: "`DELETE` on the same path removes the database; 404 when it is gone."
+    source: https://docs.turso.tech/api-reference/databases/delete
+  - id: TU5
+    verified: true
+    text: Database names are lower-case letters, numbers and dashes, at most 64 characters, unique in the organization; the group must exist already.
+    source: https://docs.turso.tech/api-reference/databases/create
+  - id: TU6
+    verified: false
+    text: The database is usable as soon as the create answers (no readiness to poll for a branch of a database in the same group).
+ops:
+  database_branch:
+    kind: resource
+    title: Database branch
+    summary: "A database copied from a parent database (a branch), named for the scope, such as `app-pr-42` from `app`. Its hostname is an output for the app's connection URL. Only its existence is compared for drift: changing `group` or `parent` later does not move or re-copy a database that exists."
+    covers: [turso-database]
+    params:
+      organization:
+        type: string
+        required: true
+        description: The organization (or user account) slug.
+        example: acme
+      name:
+        type: string
+        required: true
+        pattern: "^[a-z0-9-]{1,64}$"
+        description: The new database's name.
+        example: "app-${ctx.scope}"
+      parent:
+        type: string
+        required: true
+        description: The parent database to copy.
+        example: app
+      group:
+        type: string
+        default: default
+        description: The group the database is placed in; it must exist.
+      timestamp:
+        type: string
+        description: Copy the parent as it was at this ISO 8601 time (point-in-time recovery window only).
+    http:
+      read: { path: "/organizations/{organization}/databases/{name}" }
+      create:
+        path: "/organizations/{organization}/databases"
+        body:
+          name: { param: name }
+          group: { param: group }
+          seed: { type: database, name: { param: parent }, timestamp: { param: timestamp } }
+      item_path: /database
+      id_path: /Name
+      outputs: { hostname: /Hostname, db_id: /DbId }
+    sim:
+      id_from: name
+    live:
+      params: { organization: SPONSON_LIVE_TURSO_ORGANIZATION, parent: SPONSON_LIVE_TURSO_DATABASE }