@sponson/adapters 0.4.0 → 0.6.0

package/recipes/sentry.yaml

@@ -0,0 +1,158 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Sentry Web API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: sentry
+title: Sentry
+category: observability
+verified_on: "2026-10-11"
+docs:
+  - title: Create a New Release for an Organization
+    url: https://docs.sentry.io/api/releases/create-a-new-release-for-an-organization/
+  - title: Retrieve an Organization's Release
+    url: https://docs.sentry.io/api/releases/retrieve-an-organizations-release/
+  - title: Update an Organization's Release
+    url: https://docs.sentry.io/api/releases/update-an-organizations-release/
+  - title: Delete an Organization's Release
+    url: https://docs.sentry.io/api/releases/delete-an-organizations-release/
+  - title: Create a Deploy
+    url: https://docs.sentry.io/api/releases/create-a-deploy/
+  - title: List a Release's Deploys
+    url: https://docs.sentry.io/api/releases/list-a-releases-deploys/
+  - title: Release Management (sentry-cli)
+    url: https://docs.sentry.io/cli/releases/
+api:
+  base_url: https://sentry.io/api/0
+  base_url_env: SENTRY_API_URL
+  auth: { bearer_env: SENTRY_AUTH_TOKEN }
+detect:
+  deps: ["@sentry/"]
+  env: ["SENTRY_*"]
+  files: [sentry.client.config.ts, sentry.client.config.js, sentry.server.config.ts, sentry.server.config.js, sentry.properties, .sentryclirc]
+  starter:
+    - op: release
+      values: { version: "app@${ctx.git.sha}" }
+  where:
+    organization: "Sentry → Settings → Organization Settings → Organization Slug"
+    project: "Sentry → Settings → Projects: the project's slug"
+assumptions:
+  - id: SE1
+    verified: true
+    text: "`POST /api/0/organizations/{organization_id_or_slug}/releases/` creates a release from `version` and `projects` (both required), `ref`, `url`, `dateReleased` and commit data, with a bearer token holding `project:releases`, `project:write`, `project:admin` or `org:ci`; it answers 201 (or 208)."
+    source: https://docs.sentry.io/api/releases/create-a-new-release-for-an-organization/
+  - id: SE2
+    verified: true
+    text: "A version is one release across the organization's projects, and `GET /api/0/organizations/{org}/releases/{version}/` answers it (404 when there is none), so the version names the release."
+    source: https://docs.sentry.io/api/releases/retrieve-an-organizations-release/
+  - id: SE3
+    verified: true
+    text: "`PUT /api/0/organizations/{org}/releases/{version}/` updates `ref`, `url`, `dateReleased` and commit data (the documentation says an omitted `dateReleased` is the current time), and answers the release."
+    source: https://docs.sentry.io/api/releases/update-an-organizations-release/
+  - id: SE4
+    verified: true
+    text: "`DELETE /api/0/organizations/{org}/releases/{version}/` permanently removes a release and its files (`project:releases` or `project:admin`). The recipe keeps releases on destroy: one version is shared by every environment it is deployed to."
+    source: https://docs.sentry.io/api/releases/delete-an-organizations-release/
+  - id: SE5
+    verified: true
+    text: "`POST /api/0/organizations/{org}/releases/{version}/deploys/` records a deploy of the release from `environment` (required), `name`, `url`, `dateStarted`, `dateFinished` (default now) and `projects` (default: all of the release's)."
+    source: https://docs.sentry.io/api/releases/create-a-deploy/
+  - id: SE6
+    verified: true
+    text: "`GET /api/0/organizations/{org}/releases/{version}/deploys/` lists the release's deploys; deploys cannot be deleted, so the deploy op never deletes (`destroy: never`)."
+    source: https://docs.sentry.io/cli/releases/
+  - id: SE7
+    verified: true
+    text: "The release's `dateReleased` defaults to the current time on create, so a release this recipe creates is finalized at once."
+    source: https://docs.sentry.io/api/releases/create-a-new-release-for-an-organization/
+  - id: SE8
+    verified: false
+    text: "A create for a version that exists answers 208 with the existing release (not an error), so a release another tool made (sentry-cli in the build) is taken over without a second write; the recipe keeps it on destroy either way."
+  - id: SE9
+    verified: false
+    text: "The deploy list answers a bare array of `{ id, environment, name, url, dateStarted, dateFinished }` with string ids, all of a release's deploys on the first page; `environment` and `name` together identify the deploy this recipe recorded."
+  - id: SE10
+    verified: false
+    text: "Release `url` is answered as sent (null when unset); organizations hosted in another region (`de.sentry.io`) or self-hosted Sentry set `base_url` in the provider block."
+ops:
+  release:
+    kind: resource
+    title: Release
+    summary: "A release for the commit, such as `app@${ctx.git.sha}`, in the given projects, finalized when created (SE7). Named by its version; a console edit of its URL is drift. Kept on destroy (shared history: preview and production deploy the same version); `destroy: delete` on the line removes it."
+    covers: [sentry-release]
+    destroy: keep
+    params:
+      organization:
+        type: string
+        required: true
+        description: The organization's slug or id.
+        example: acme
+      version:
+        type: string
+        required: true
+        pattern: "^[^/\\s]+$"
+        description: The release's version (no slashes or whitespace), such as `app@<sha>`.
+        example: "app@${ctx.git.sha}"
+      project:
+        type: string
+        required: true
+        description: The slug of the project the release belongs to (a release of several projects is a hand-written `http` line).
+        example: web
+      url:
+        type: string
+        description: A link for the release (its commit or build).
+        example: "https://github.com/acme/app/commit/${ctx.git.sha}"
+      ref:
+        type: string
+        description: A commit reference, sent on create.
+    http:
+      read: { path: "/organizations/{organization}/releases/{version}/" }
+      create:
+        path: "/organizations/{organization}/releases/"
+        body: { version: { param: version }, projects: [{ param: project }], ref: { param: ref } }
+      update: { method: PUT }
+      id_path: /version
+      fields:
+        url: { param: url }
+    sim:
+      id_from: version
+    live:
+      params: { organization: SPONSON_LIVE_SENTRY_ORG, project: SPONSON_LIVE_SENTRY_PROJECT }
+  deploy:
+    kind: resource
+    title: Deploy of a release to an environment
+    summary: "The record that a release was deployed to an environment (`preview`, named for the scope), which Sentry shows on the release and uses for deploy notifications. Located by environment and name among the release's deploys. Sentry has no way to change or delete a deploy, so nothing is compared for drift and destroy leaves it (`destroy: never`)."
+    covers: [sentry-release]
+    destroy: never
+    params:
+      organization:
+        type: string
+        required: true
+        description: The organization's slug or id.
+        example: acme
+      version:
+        type: string
+        required: true
+        pattern: "^[^/\\s]+$"
+        description: "The deployed release's version; the release must exist (`{ from: <release line>.id }` orders the lines)."
+        example: "app@${ctx.git.sha}"
+      environment:
+        type: string
+        required: true
+        description: The environment deployed to.
+        example: "${ctx.env}"
+      name:
+        type: string
+        required: true
+        description: The deploy's name, which with the environment identifies it among the release's deploys.
+        example: "sponson-${ctx.scope}"
+      url:
+        type: string
+        description: A link to the deployment (the preview URL), sent on create.
+    http:
+      find:
+        path: "/organizations/{organization}/releases/{version}/deploys/"
+        match: { environment: { param: environment }, name: { param: name } }
+      create:
+        path: "/organizations/{organization}/releases/{version}/deploys/"
+        body: { url: { param: url } }
+      delete: { path: "/organizations/{organization}/releases/{version}/deploys/{id}/" }
+    live:
+      params: { organization: SPONSON_LIVE_SENTRY_ORG, version: SPONSON_LIVE_SENTRY_VERSION }

package/recipes/split.yaml

@@ -0,0 +1,121 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Split (Harness FME) Admin API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: split
+title: Split (Harness FME)
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Authentication
+    url: https://docs.split.io/reference/authentication
+  - title: Get feature flag definition in environment
+    url: https://docs.split.io/reference/get-feature-flag-definition-in-environment
+  - title: Full update feature flag definition in environment
+    url: https://docs.split.io/reference/full-update-feature-flag-definition-in-environment
+  - title: Feature flag definition, rule, condition, matcher
+    url: https://docs.split.io/reference/feature-flag-definition
+  - title: Matcher types
+    url: https://docs.split.io/reference/matcher-type
+  - title: API for Split admins after the move to Harness
+    url: https://developer.harness.io/docs/feature-management-experimentation/split-to-harness/api-for-split-admins/
+api:
+  base_url: https://api.split.io/internal/api/v2
+  base_url_env: SPLIT_API_URL
+  auth: { bearer_env: SPLIT_ADMIN_API_KEY }
+detect:
+  deps: ["@splitsoftware/"]
+  env: ["SPLIT_*"]
+  starter:
+    - op: targeting_rule
+      values: { match: "${ctx.scope}" }
+  where:
+    workspace_id: "Split → Admin settings → Projects: the project's id"
+assumptions:
+  - id: SP1
+    verified: true
+    text: "The Admin API is at `https://api.split.io/internal/api/v2`, authenticated as `Authorization: Bearer` with a Split Admin API key (or a Harness PAT/SAT, accepted as Bearer on the non-deprecated endpoints). Host and paths are unchanged by the move to Harness; the workspace id is still Split's `wsId`."
+    source: https://developer.harness.io/docs/feature-management-experimentation/split-to-harness/api-for-split-admins/
+  - id: SP2
+    verified: true
+    text: "`GET /splits/ws/{wsId}/{featureFlagName}/environments/{environmentIdOrName}` answers the flag's definition in the environment bare: `treatments`, `defaultTreatment`, `baselineTreatment`, `trafficAllocation`, `rules`, `defaultRule` and read-only fields (`name`, `environment`, `trafficType`, times)."
+    source: https://docs.split.io/reference/get-feature-flag-definition-in-environment
+  - id: SP3
+    verified: true
+    text: "`PUT` on the same path replaces the definition with `treatments`, `defaultTreatment`, `baselineTreatment`, `trafficAllocation`, `rules` and `defaultRule` (the first three of the required fields). Those are sent as read, with the rule list changed (`parent.send`); whether PUT takes the read-only fields back is not documented, so they are not sent."
+    source: https://docs.split.io/reference/full-update-feature-flag-definition-in-environment
+  - id: SP4
+    verified: true
+    text: "A rule is `{ condition: { combiner: AND, matchers: [...] }, buckets: [{ treatment, size }] }` (bucket sizes sum to 100); rules have no id and are evaluated in order. `IN_LIST_STRING` with `attribute` and `strings` matches an attribute in a list."
+    source: https://docs.split.io/reference/matcher-type
+  - id: SP5
+    verified: false
+    text: "A rule is read back with its matcher exactly as written (no added `negate: false` or null members); otherwise every plan shows the rule as changed."
+  - id: SP6
+    verified: false
+    text: "A full update leaves the flag's killed state alone (`killed` is not a documented PUT field)."
+  - id: SP7
+    verified: true
+    text: "In a project that requires a title and comment on changes, they are query parameters of the update; this recipe does not send them, so such a project refuses the write and the apply fails."
+    source: https://developer.harness.io/docs/feature-management-experimentation/api/feature-flags/
+ops:
+  targeting_rule:
+    kind: list_item
+    title: Feature flag targeting rule
+    summary: "A targeting rule on a feature flag's definition in one environment that serves a treatment to the preview, such as `if preview is in list [pr-42] serve on`. Added after the flag's other rules (evaluated in order: an earlier matching rule wins); the treatments, default rule and traffic allocation are written back as read. Identified by the matched value; a console edit of its matcher or treatment is drift. Destroy removes the rule."
+    covers: [split-rule]
+    params:
+      workspace_id:
+        type: string
+        required: true
+        description: The workspace (project) id, Split's `wsId`.
+        example: a3b6f5d0-0e8f-11ee-9b0f-0242ac120002
+      flag:
+        type: string
+        required: true
+        description: The feature flag's name.
+        example: new_checkout
+      environment:
+        type: string
+        required: true
+        description: The environment's id or name; the flag must have a definition there.
+        example: Staging
+      attribute:
+        type: string
+        required: true
+        description: The attribute the rule tests (passed with the evaluation).
+        example: preview
+      match:
+        type: string
+        required: true
+        description: The attribute value that is the preview; it identifies the rule.
+        example: "${ctx.scope}"
+      treatment:
+        type: string
+        required: true
+        description: The treatment served to the preview; one of the flag's treatments.
+        example: "on"
+    http:
+      parent:
+        path: "/splits/ws/{workspace_id}/{flag}/environments/{environment}"
+        method: PUT
+        send: [treatments, defaultTreatment, baselineTreatment, trafficAllocation, defaultRule]
+      list_path: /rules
+      key_field: /condition/matchers/0/strings/0
+      item:
+        condition:
+          combiner: AND
+          matchers:
+            - type: IN_LIST_STRING
+              attribute: { param: attribute }
+              strings: [{ param: match }]
+        buckets: [{ treatment: { param: treatment }, size: 100 }]
+    sim:
+      objects:
+        "/splits/ws/{workspace_id}/{flag}/environments/{environment}":
+          treatments: [{ name: "on" }, { name: "off" }]
+          defaultTreatment: "off"
+          baselineTreatment: "off"
+          trafficAllocation: 100
+          rules: []
+          defaultRule: [{ treatment: "off", size: 100 }]
+    live:
+      params: { workspace_id: SPONSON_LIVE_SPLIT_WORKSPACE_ID, flag: SPONSON_LIVE_SPLIT_FLAG, environment: SPONSON_LIVE_SPLIT_ENVIRONMENT }

package/recipes/statsig.yaml

@@ -0,0 +1,124 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Statsig Console API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: statsig
+title: Statsig
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Console API introduction (base URL, STATSIG-API-KEY, STATSIG-API-VERSION)
+    url: https://docs.statsig.com/console-api/introduction
+  - title: Add gate rule
+    url: https://docs.statsig.com/api-reference/gates/add-gate-rule
+  - title: Read gate rules
+    url: https://docs.statsig.com/api-reference/gates/read-gate-rules
+  - title: Update gate rules (one rule)
+    url: https://docs.statsig.com/api-reference/gates/update-gate-rules
+  - title: Delete gate rule
+    url: https://docs.statsig.com/api-reference/gates/delete-gate-rule
+  - title: Console API OpenAPI spec (20240601)
+    url: https://api.statsig.com/openapi/20240601.json
+api:
+  base_url: https://statsigapi.net/console/v1
+  base_url_env: STATSIG_API_URL
+  auth: { header: STATSIG-API-KEY, value_env: STATSIG_CONSOLE_API_KEY }
+  headers: { STATSIG-API-VERSION: "20240601" }
+detect:
+  deps: [statsig-js, statsig-node, statsig-react, "@statsig/"]
+  env: ["STATSIG_*"]
+  starter:
+    - op: gate_rule
+      values: { name: "preview ${ctx.scope}", values: ["${ctx.scope}"] }
+  where:
+    gate_id: "Statsig console → Feature Gates → your gate: its name in the URL"
+assumptions:
+  - id: SG1
+    verified: true
+    text: "The Console API is at `https://statsigapi.net/console/v1`, authenticated with a Console API key in the `STATSIG-API-KEY` header; `STATSIG-API-VERSION: 20240601` (the only version) is optional today and announced as required later, so it is always sent."
+    source: https://docs.statsig.com/console-api/introduction
+  - id: SG2
+    verified: true
+    text: "`POST /gates/{id}/rule` (singular) adds one rule (`name`, `passPercentage`, `conditions`, `environments`) and answers `{ message, data: <the whole gate> }`, not the rule: the new rule is located by name afterwards (`create.locate`)."
+    source: https://docs.statsig.com/api-reference/gates/add-gate-rule
+  - id: SG3
+    verified: false
+    text: "`GET /gates/{id}/rules` answers the rules under `data.rules` (the documented example); the spec's schema says `data` is a list of `{ rules }` objects instead. If the API follows the schema, every read fails with PROVIDER_RESPONSE naming `find.list_path` (it does not create duplicates). The rules of one gate fit on the first page."
+    source: https://docs.statsig.com/api-reference/gates/read-gate-rules
+  - id: SG4
+    verified: true
+    text: "`PATCH /gates/{id}/rules/{ruleID}` updates the given fields of one rule; `DELETE` on the same path removes it. Rules carry a server-assigned `id`."
+    source: https://docs.statsig.com/api-reference/gates/update-gate-rules
+  - id: SG5
+    verified: false
+    text: "Rule names are unique within a gate (not documented): the rule is identified by its name, and two rules with that name are PARAM_INVALID rather than a guess."
+  - id: SG6
+    verified: false
+    text: "A rule is read back with `conditions` exactly as written (`type`, `operator`, `targetValue`, and `field` when sent). If Statsig adds keys such as `field: null` to a condition, every plan shows the rule as changed."
+  - id: SG7
+    verified: false
+    text: "DELETE of a rule that is already gone answers 404 (the spec lists only 200); any other answer fails the destroy rather than passing silently."
+  - id: SG8
+    verified: false
+    text: "On a gate that requires reviews, what a Console API rule write does (apply, fail, or open a pending review) is not documented; a write that does not take effect is seen on the next read as missing or changed, never as done."
+    source: https://docs.statsig.com/guides/setting-up-reviews
+ops:
+  gate_rule:
+    kind: resource
+    title: Feature gate rule
+    summary: "A rule on an existing feature gate that passes the preview, such as `custom_field preview any [pr-42]`. Located by its name in the gate's rules; a console edit of its pass percentage, conditions or environments is drift. Destroy deletes the rule."
+    covers: [statsig-gate-rule]
+    params:
+      gate_id:
+        type: string
+        required: true
+        description: The gate's id (its name in the console URL).
+        example: new_checkout
+      name:
+        type: string
+        required: true
+        description: The rule's name, unique within the gate; it identifies the rule.
+        example: "preview ${ctx.scope}"
+      condition_type:
+        type: string
+        default: custom_field
+        enum: [custom_field, url, environment_tier, user_id, email]
+        description: "The condition's type: `custom_field` (with `field`), `url`, `environment_tier`, `user_id` or `email`."
+      field:
+        type: string
+        description: The custom field's name, for `condition_type` `custom_field`.
+        example: preview
+      operator:
+        type: string
+        default: any
+        description: "The condition's operator: `any`, `none`, `str_contains_any`, … (see the Statsig rule docs)."
+      values:
+        type: list
+        required: true
+        description: The values the condition matches (its `targetValue`).
+        example: ["${ctx.scope}"]
+      pass_percentage:
+        type: number
+        default: 100
+        description: The share of matching users that pass (0–100).
+      environment_names:
+        type: list
+        description: The environments the rule applies in (for example `[development, staging]`); all when left out.
+    http:
+      find:
+        path: "/gates/{gate_id}/rules"
+        list_path: /data/rules
+        match: { name: { param: name } }
+      create: { path: "/gates/{gate_id}/rule", locate: true }
+      update: { method: PATCH, path: "/gates/{gate_id}/rules/{id}" }
+      delete: { path: "/gates/{gate_id}/rules/{id}" }
+      fields:
+        passPercentage: { param: pass_percentage }
+        conditions:
+          - type: { param: condition_type }
+            field: { param: field }
+            operator: { param: operator }
+            targetValue: { param: values }
+        environments: { param: environment_names }
+    sim:
+      collection: "/gates/{gate_id}/rules"
+    live:
+      params: { gate_id: SPONSON_LIVE_STATSIG_GATE_ID }