@sponson/adapters 0.4.0 → 0.5.0

package/recipes/unleash.yaml

@@ -0,0 +1,149 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Unleash Admin API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: unleash
+title: Unleash
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Admin API overview (authorization, base URL)
+    url: https://docs.getunleash.io/reference/api/unleash
+  - title: Add a strategy to a flag in an environment
+    url: https://docs.getunleash.io/reference/api/unleash/add-feature-strategy
+  - title: Get feature flag strategies
+    url: https://docs.getunleash.io/reference/api/unleash/get-feature-strategies
+  - title: Update a strategy (replace)
+    url: https://docs.getunleash.io/reference/api/unleash/update-feature-strategy
+  - title: Delete a strategy
+    url: https://docs.getunleash.io/reference/api/unleash/delete-feature-strategy
+  - title: API tokens and client keys
+    url: https://docs.getunleash.io/reference/api-tokens-and-client-keys
+# Every Unleash instance has its own URL (self-hosted, or https://<region>.app.unleash-hosted.com/<instance>):
+# everything before `/api`.
+base_url_example: https://unleash.example.com
+api:
+  base_url_env: UNLEASH_API_URL
+  auth: { header: Authorization, value_env: UNLEASH_AUTH_TOKEN }
+detect:
+  deps: [unleash-client, unleash-proxy-client, "@unleash/"]
+  env: ["UNLEASH_*"]
+  starter:
+    - op: flag_strategy
+      values: { title: "preview ${ctx.scope}", values: ["${ctx.scope}"] }
+  where:
+    base_url: "your Unleash instance's URL (`https://<instance>`)"
+assumptions:
+  - id: UN1
+    verified: true
+    text: "Every request carries the token as it is in `Authorization` (`Authorization: <token>`, no `Bearer`); a personal access token or service account token (admin tokens are deprecated) reaches the Admin API. The spec also lists a Bearer scheme, but the server does not strip a `Bearer ` prefix, so the bare form is used."
+    source: https://docs.getunleash.io/reference/api/unleash
+  - id: UN2
+    verified: true
+    text: "`POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies` with `name`, `title`, `disabled`, `constraints` and `parameters` adds a strategy and answers it bare, with its server-assigned `id` (a UUID)."
+    source: https://docs.getunleash.io/reference/api/unleash/add-feature-strategy
+  - id: UN3
+    verified: true
+    text: "`GET` on the same path answers a bare array of the environment's strategies (the source returns `FeatureStrategySchema[]`; the docs page's schema shows a single strategy, which is wrong)."
+    source: https://github.com/Unleash/unleash/blob/main/src/lib/features/feature-toggle/feature-toggle-controller.ts
+  - id: UN4
+    verified: true
+    text: "`PUT .../strategies/{strategyId}` replaces a strategy's configuration (so it sends `name`, `title` and every compared field); `DELETE` on the same path removes it."
+    source: https://docs.getunleash.io/reference/api/unleash/update-feature-strategy
+  - id: UN5
+    verified: true
+    text: "A constraint is `{ contextName, operator, values, caseInsensitive, inverted }` (`caseInsensitive` and `inverted` default to false, and are written explicitly so the comparison does not depend on defaults); `parameters` is a map of strings (`rollout: \"100\"`)."
+    source: https://docs.getunleash.io/reference/api/unleash/add-feature-strategy
+  - id: UN6
+    verified: false
+    text: "`title` is optional and not unique on the server: the strategy is identified by its title in the environment, and two strategies with that title are PARAM_INVALID rather than a guess."
+    source: https://docs.getunleash.io/reference/api/unleash/add-feature-strategy
+  - id: UN7
+    verified: false
+    text: "A strategy is read back with `constraints` and `parameters` exactly as written (no extra keys such as `value: \"\"`); otherwise every plan shows it as changed."
+  - id: UN8
+    verified: true
+    text: "Deleting a strategy that is gone already answers 200 (nothing to do). Deleting the last strategy of an environment turns the flag off in that environment (the service calls `disableEnvironmentIfNoStrategies`). Adding a strategy does not turn the environment on."
+    source: https://github.com/Unleash/unleash/blob/main/src/lib/features/feature-toggle/feature-toggle-service.ts
+  - id: UN9
+    verified: true
+    text: "With change requests enabled for the environment, these writes are refused unless the caller may bypass them; the refusal fails the apply."
+    source: https://github.com/Unleash/unleash/blob/main/src/lib/features/feature-toggle/feature-toggle-service.ts
+ops:
+  flag_strategy:
+    kind: resource
+    title: Flag strategy with constraints
+    summary: "A `flexibleRollout` strategy on a flag in one environment, constrained to the preview (such as `preview IN [pr-42]`). Located by its title in the environment's strategies; a console edit of its constraints, rollout parameters or `disabled` is drift. Destroy deletes it; if it was the environment's last strategy, Unleash turns the flag off there (UN8). The environment itself must be enabled for the flag to be served."
+    covers: [unleash-strategy]
+    params:
+      project:
+        type: string
+        default: default
+        description: The project id.
+      feature:
+        type: string
+        required: true
+        description: The flag's name; also the rollout's `groupId`.
+        example: new-checkout
+      environment:
+        type: string
+        required: true
+        description: The environment the strategy is added in.
+        example: development
+      title:
+        type: string
+        required: true
+        description: The strategy's title, unique among the environment's strategies; it identifies the strategy.
+        example: "preview ${ctx.scope}"
+      context_name:
+        type: string
+        required: true
+        description: The context field the constraint tests (a custom context field such as `preview`, or `environment`, `userId`, …).
+        example: preview
+      operator:
+        type: string
+        default: IN
+        enum: [IN, NOT_IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS]
+        description: The constraint's operator.
+      values:
+        type: list
+        required: true
+        description: The values the context field is compared with.
+        example: ["${ctx.scope}"]
+      rollout:
+        type: string
+        default: "100"
+        pattern: "^(100|[1-9]?[0-9])$"
+        description: The share of matching users the strategy enables, as a string (0–100).
+      stickiness:
+        type: string
+        default: default
+        description: The rollout's stickiness (`default`, `userId`, `sessionId`, `random`, or a context field).
+      disabled:
+        type: boolean
+        default: false
+        description: Keep the strategy but switch it off.
+    http:
+      find:
+        path: "/api/admin/projects/{project}/features/{feature}/environments/{environment}/strategies"
+        match: { title: { param: title } }
+      create:
+        path: "/api/admin/projects/{project}/features/{feature}/environments/{environment}/strategies"
+        body: { name: flexibleRollout }
+      update:
+        method: PUT
+        path: "/api/admin/projects/{project}/features/{feature}/environments/{environment}/strategies/{id}"
+        body: { name: flexibleRollout }
+      delete: { path: "/api/admin/projects/{project}/features/{feature}/environments/{environment}/strategies/{id}" }
+      fields:
+        disabled: { param: disabled }
+        constraints:
+          - contextName: { param: context_name }
+            operator: { param: operator }
+            values: { param: values }
+            caseInsensitive: false
+            inverted: false
+        parameters:
+          rollout: { param: rollout }
+          stickiness: { param: stickiness }
+          groupId: { param: feature }
+    live:
+      params: { project: SPONSON_LIVE_UNLEASH_PROJECT, feature: SPONSON_LIVE_UNLEASH_FEATURE, environment: SPONSON_LIVE_UNLEASH_ENVIRONMENT }

package/recipes/upstash.yaml

@@ -0,0 +1,130 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Upstash Developer API recipes (Redis). QStash has its own API and credential: recipes/qstash.yaml.
+# Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: upstash
+title: Upstash Redis
+category: queues
+verified_on: "2026-10-11"
+docs:
+  - title: Developer API authentication
+    url: https://upstash.com/docs/devops/developer-api/authentication
+  - title: Developer API introduction (supported accounts)
+    url: https://upstash.com/docs/devops/developer-api/introduction
+  - title: Create a Redis database (global)
+    url: https://upstash.com/docs/devops/developer-api/redis/create_database_global
+  - title: List Redis databases
+    url: https://upstash.com/docs/devops/developer-api/redis/list_databases
+  - title: Get a Redis database
+    url: https://upstash.com/docs/devops/developer-api/redis/get_database
+  - title: Delete a Redis database
+    url: https://upstash.com/docs/devops/developer-api/redis/delete_database
+  - title: Upstash CLI (UPSTASH_EMAIL, UPSTASH_API_KEY)
+    url: https://upstash.com/docs/agent-resources/cli
+  - title: Terraform upstash_redis_database (exported credentials)
+    url: https://upstash.com/docs/devops/terraform/resources/upstash_redis_database
+api:
+  base_url: https://api.upstash.com/v2
+  base_url_env: UPSTASH_API_URL
+  auth: { basic: { user_env: UPSTASH_EMAIL, password_env: UPSTASH_API_KEY } }
+detect:
+  deps: ["@upstash/redis"]
+  env: ["UPSTASH_REDIS_*"]
+  starter:
+    - op: redis_database
+      values: { name: "app-${ctx.scope}" }
+assumptions:
+  - id: UR1
+    verified: true
+    text: "The Developer API authenticates with HTTP Basic, the account's email as user and an API key as password; the Upstash CLI reads them from `UPSTASH_EMAIL` and `UPSTASH_API_KEY`. Accounts created through Vercel or Fly cannot use it."
+    source: https://upstash.com/docs/devops/developer-api/authentication
+  - id: UR2
+    verified: true
+    text: "`POST /v2/redis/database` with `{ database_name, platform, primary_region, read_regions?, plan?, tls?, eviction? }` creates a global database and answers it bare, with `database_id`, `database_name`, `endpoint`, `port` and `state`."
+    source: https://upstash.com/docs/devops/developer-api/redis/create_database_global
+  - id: UR3
+    verified: true
+    text: "`GET /v2/redis/databases` answers every database of the account as a bare array (no paging)."
+    source: https://upstash.com/docs/devops/developer-api/redis/list_databases
+  - id: UR4
+    verified: false
+    text: "Database names are unique in the account, so `database_name` identifies one; a create whose answer was lost is found by it before another is created. (Not documented: a second database with the same name makes `find.match` ambiguous, which is refused with PARAM_INVALID rather than guessed.)"
+  - id: UR5
+    verified: true
+    text: "`GET /v2/redis/database/{id}` answers the database, with its credentials unless `?credentials=hide` is sent."
+    source: https://upstash.com/docs/devops/developer-api/redis/get_database
+  - id: UR6
+    verified: false
+    text: "The credentials are the fields `password` and `rest_token` (the documented schema omits them; the Terraform resource and the CLI expose them), so they are readable on every run, not only from the create: ordinary sensitive outputs, not once-only ones."
+    source: https://upstash.com/docs/devops/terraform/resources/upstash_redis_database
+  - id: UR7
+    verified: true
+    text: "`DELETE /v2/redis/database/{id}` deletes the database and answers 200 `\"OK\"`."
+    source: https://upstash.com/docs/devops/developer-api/redis/delete_database
+  - id: UR8
+    verified: false
+    text: "A database that is gone answers 404 on GET and DELETE (only 200 is documented)."
+  - id: UR9
+    verified: false
+    text: "The database is usable when the create answers (`state: active` in the documented example); nothing waits for it."
+    source: https://upstash.com/docs/devops/developer-api/redis/create_database_global
+  - id: UR10
+    verified: false
+    text: "`endpoint` is the database's host name (`<name>.upstash.io`); the documented example shows only its first label, so check the output before building a URL from it."
+    source: https://upstash.com/docs/devops/developer-api/redis/create_database_global
+ops:
+  redis_database:
+    kind: resource
+    title: Redis database
+    summary: "A global Redis database per scope, such as `app-pr-42`, with its endpoint, port, password and REST token as outputs (the last two sensitive). Located by name; only its existence is compared for drift (region, plan and TLS are set on create and not compared); destroy deletes it and its data."
+    covers: [upstash-redis-database]
+    params:
+      name:
+        type: string
+        required: true
+        description: The database's name.
+        example: "app-${ctx.scope}"
+      platform:
+        type: string
+        default: aws
+        enum: [aws, gcp]
+        description: The cloud it runs on.
+      primary_region:
+        type: string
+        required: true
+        description: The primary region, such as `us-east-1` or `eu-west-1`.
+        example: us-east-1
+      read_regions:
+        type: list
+        description: Read replica regions.
+      plan:
+        type: string
+        description: The plan (`free`, `payg`, `fixed_…`); the account's default when left out.
+      tls:
+        type: boolean
+        default: true
+        description: Whether TLS is enabled.
+      eviction:
+        type: boolean
+        description: Whether keys are evicted when the database is full.
+    http:
+      find:
+        path: /redis/databases
+        match: { database_name: { param: name } }
+      read: { path: "/redis/database/{id}" }
+      create:
+        path: /redis/database
+        body:
+          platform: { param: platform }
+          primary_region: { param: primary_region }
+          read_regions: { param: read_regions }
+          plan: { param: plan }
+          tls: { param: tls }
+          eviction: { param: eviction }
+      id_path: /database_id
+      outputs:
+        endpoint: /endpoint
+        port: /port
+        password: { path: /password, sensitive: true }
+        rest_token: { path: /rest_token, sensitive: true }
+    live:
+      params: { primary_region: SPONSON_LIVE_UPSTASH_REGION }

package/recipes/vercel.yaml

@@ -0,0 +1,116 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Vercel REST API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+# Environment variables and deployments have the first-class `vercel` adapter (vercel.env, vercel.deploy).
+provider: vercel
+title: Vercel
+category: dns
+verified_on: "2026-10-11"
+docs:
+  - title: Add a domain to a project
+    url: https://vercel.com/docs/rest-api/projects/add-a-domain-to-a-project
+  - title: Get a project domain
+    url: https://vercel.com/docs/rest-api/projects/get-a-project-domain
+  - title: Update a project domain
+    url: https://vercel.com/docs/rest-api/projects/update-a-project-domain
+  - title: Remove a domain from a project
+    url: https://vercel.com/docs/rest-api/projects/remove-a-domain-from-a-project
+  - title: Errors
+    url: https://vercel.com/docs/rest-api/errors
+  - title: CLI global options (VERCEL_TOKEN)
+    url: https://vercel.com/docs/cli/global-options
+  - title: Working with domains (verification)
+    url: https://vercel.com/docs/domains/working-with-domains
+api:
+  base_url: https://api.vercel.com
+  base_url_env: VERCEL_API_URL
+  auth: { bearer_env: VERCEL_TOKEN }
+assumptions:
+  - id: VD1
+    verified: true
+    text: "Requests authenticate as `Authorization: Bearer <token>`; the Vercel CLI reads the token from `VERCEL_TOKEN` (the built-in `vercel` adapter uses the same variable)."
+    source: https://vercel.com/docs/cli/global-options
+  - id: VD2
+    verified: true
+    text: "`POST /v10/projects/{idOrName}/domains?teamId=` with `{ name, gitBranch, redirect, redirectStatusCode }` adds the domain to the project and answers it bare: `{ name, apexName, projectId, verified, gitBranch, redirect, redirectStatusCode, verification[] }`."
+    source: https://vercel.com/docs/rest-api/projects/add-a-domain-to-a-project
+  - id: VD3
+    verified: true
+    text: "`GET /v9/projects/{idOrName}/domains/{domain}?teamId=` answers the same shape; the domain's name identifies it within the project, so the read path names it and a create whose answer was lost is found by it."
+    source: https://vercel.com/docs/rest-api/projects/get-a-project-domain
+  - id: VD4
+    verified: false
+    text: "A domain that is not on the project answers 404 on GET and DELETE (documented with no description)."
+    source: https://vercel.com/docs/rest-api/projects/get-a-project-domain
+  - id: VD5
+    verified: true
+    text: "`PATCH /v9/projects/{idOrName}/domains/{domain}` changes `gitBranch`, `redirect` and `redirectStatusCode`; `DELETE` on the same path removes the domain from the project (200, `{}`)."
+    source: https://vercel.com/docs/rest-api/projects/update-a-project-domain
+  - id: VD6
+    verified: true
+    text: "Adding a domain that is already on a project of the account answers 409 (and, for the same project, the description says 400): someone else's domain is never taken over by name, and the conflict surfaces as an error."
+    source: https://vercel.com/docs/rest-api/projects/add-a-domain-to-a-project
+  - id: VD7
+    verified: true
+    text: "`gitBranch` and `redirect` cannot be set together, and the production branch cannot be a `gitBranch` (400)."
+    source: https://vercel.com/docs/rest-api/projects/add-a-domain-to-a-project
+  - id: VD8
+    verified: true
+    text: "A domain the account does not own answers `verified: false` with a `verification` challenge (a TXT record) that must be completed before it serves traffic; a domain bought through Vercel needs none."
+    source: https://vercel.com/docs/domains/working-with-domains
+  - id: VD9
+    verified: false
+    text: "A free `<name>.vercel.app` domain that no other project uses is verified on the spot (`verified: true`)."
+  - id: VD10
+    verified: false
+    text: "Every account has a team id (personal accounts are Hobby teams), so `teamId` can always be sent; the recipe requires it."
+ops:
+  project_domain:
+    kind: resource
+    title: Branch-bound project domain
+    summary: "A domain on a Vercel project that serves one git branch's latest preview, such as `pr-42.preview.example.com` for `feat/x`: a stable preview hostname. Located by name; a console edit of its branch or redirect is drift; destroy removes it from the project. Its `verified` output says whether DNS verification is still needed (VD8)."
+    covers: [vercel-domain]
+    params:
+      project:
+        type: string
+        required: true
+        description: The project's id or name.
+        example: prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB
+      team_id:
+        type: string
+        required: true
+        pattern: "^team_[A-Za-z0-9]+$"
+        description: The team's id (`team_…`, under Settings → General).
+        example: team_1a2b3c4d5e6f7g8h9i0j1k2l
+      name:
+        type: string
+        required: true
+        pattern: "^[a-z0-9*.-]+$"
+        description: The domain, lower-case.
+        example: "${ctx.scope}.preview.example.com"
+      git_branch:
+        type: string
+        description: The git branch whose latest deployment the domain serves.
+        example: "${ctx.git.branch}"
+      redirect:
+        type: string
+        description: Redirect to this domain instead of serving a branch (not with `git_branch`).
+      redirect_status_code:
+        type: integer
+        enum: [301, 302, 307, 308]
+        description: The redirect's status code.
+    http:
+      read: { path: "/v9/projects/{project}/domains/{name}?teamId={team_id}" }
+      create:
+        path: "/v10/projects/{project}/domains?teamId={team_id}"
+        body: { name: { param: name } }
+      update: { method: PATCH }
+      id_path: /name
+      fields:
+        gitBranch: { param: git_branch }
+        redirect: { param: redirect }
+        redirectStatusCode: { param: redirect_status_code }
+      outputs: { verified: /verified, apex_name: /apexName }
+    sim:
+      id_from: name
+    live:
+      params: { project: SPONSON_LIVE_VERCEL_PROJECT, team_id: SPONSON_LIVE_VERCEL_TEAM_ID, name: SPONSON_LIVE_VERCEL_DOMAIN }

package/recipes/workos.yaml

@@ -0,0 +1,70 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# WorkOS API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: workos
+title: WorkOS
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: AuthKit API reference, Redirect URI
+    url: https://workos.com/docs/reference/authkit/redirect-uri
+  - title: AuthKit, redirect URIs in the Dashboard
+    url: https://workos.com/docs/user-management/integrating-with-authkit
+api:
+  base_url: https://api.workos.com
+  base_url_env: WORKOS_API_URL
+  auth: { bearer_env: WORKOS_API_KEY }
+detect:
+  deps: ["@workos-inc/"]
+  env: ["WORKOS_*"]
+  starter:
+    - op: redirect_uri
+  where:
+    uri: "the exact redirect URI AuthKit receives on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: WO1
+    verified: true
+    text: "`POST /user_management/redirect_uris` with `{ uri }` creates a redirect URI for the environment the API key (`Authorization: Bearer sk_…`) belongs to, and answers the `redirect_uri` object (`id`, `uri`, `default`)."
+    source: https://workos.com/docs/reference/authkit/redirect-uri
+  - id: WO2
+    verified: true
+    text: "`GET /user_management/redirect_uris` (`limit` 1–100, cursors `before`/`after`) answers `{ data: [...], list_metadata: { before, after } }`."
+    source: https://workos.com/docs/reference/authkit/redirect-uri
+  - id: WO3
+    verified: true
+    text: "`DELETE /user_management/redirect_uris/{id}` removes one and answers an empty body. There is no GET or update by id: a URI is found in the list, and nothing about it is changed in place."
+    source: https://workos.com/docs/reference/authkit/redirect-uri
+  - id: WO4
+    verified: true
+    text: "Redirect URIs may contain wildcards, except the default one."
+    source: https://workos.com/docs/user-management/integrating-with-authkit
+  - id: WO5
+    verified: false
+    text: "Each URI is its own object (no shared list to rewrite), so concurrent previews need no lock; a URI is returned exactly as it was created, so `uri` identifies it."
+  - id: WO6
+    verified: false
+    text: "Creating a URI that already exists is refused as a conflict (409) rather than duplicated; the line then finds the existing one."
+  - id: WO7
+    verified: false
+    text: "The first redirect URI of an environment becomes its default; a preview's URI is never the first in an environment that has a production URI."
+ops:
+  redirect_uri:
+    kind: resource
+    title: AuthKit redirect URI
+    summary: "One redirect URI on the WorkOS environment the API key belongs to, such as the preview's `/callback`: usually `{ from: <vercel.env line>.preview_url }` joined in the app. Found by its URI in the list (following `list_metadata.after`); removed by id on destroy. A URI has nothing else to edit, so the only drift is a URI deleted in the Dashboard, which the next apply creates again."
+    covers: [workos-redirect]
+    params:
+      uri:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The redirect URI, exactly as AuthKit will receive it (`https://pr-42.preview.example.com/callback`)."
+        example: "https://${ctx.scope}.preview.example.com/callback"
+    http:
+      find:
+        path: /user_management/redirect_uris?limit=100
+        list_path: /data
+        match: { uri: { param: uri } }
+        next: /list_metadata/after
+        cursor_param: after
+      create: { path: /user_management/redirect_uris }
+      delete: { path: "/user_management/redirect_uris/{id}" }