@sponson/adapters 0.0.0-stage → 0.5.0

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 }

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 }