@admoai/sdk-scenarios 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ Versioning: a scenario added or an `expect` tightened is a **minor** release; a
 removed, or a `request`/`expect` key renamed (every SDK's interpreter must change), is a
 **major** one. Each SDK vendors one version and its own CI checks the vendored bytes against it.
 
+## 1.1.0 — 2026-10-21
+
+Also ships `scenarios.feature`: the same 39 scenarios rendered as Gherkin for people to read
+(admoai/adhub#4348). It is generated from `scenarios.json` by `tools/sdkfeaturegen` in adhub and
+is never edited by hand; the SDK runners keep executing the JSON, which is byte-identical to
+1.0.0's.
+
 ## 1.0.0 — 2026-10-20
 
 The 39 scenarios the three SDKs already carried, byte for byte (sha256 `a55f68eb…`):

package/README.md

@@ -4,9 +4,11 @@ The scenarios every AdMoai mobile SDK (iOS, Android, Flutter) must pass against
 decision-engine: given a request, the outcome a publisher's app observes. One definition,
 executed by a thin interpreter in each SDK, so the three cannot make different claims.
 
-This package is **data only**: `scenarios.json` (the manifest, `schemaVersion` inside). It
-carries no URLs, hosts, credentials or tenant identifiers — `check.sh` refuses a release that
-does.
+This package is **data only**: `scenarios.json` (the manifest, `schemaVersion` inside) and
+`scenarios.feature`, the same scenarios rendered as Gherkin for a PM or an integrating
+publisher to read. The JSON is what the SDK runners execute; the feature is generated from it.
+Neither carries URLs, hosts, credentials or tenant identifiers — `check.sh` refuses a release
+whose manifest does.
 
 ## For an SDK
 
@@ -21,7 +23,8 @@ curl -sSfL "https://registry.npmjs.org/@admoai/sdk-scenarios/-/sdk-scenarios-$VE
 ## For adhub (the source)
 
 The source of truth is `sdk/scenarios/` in admoai/adhub. To change a scenario: edit
-`scenarios.json`, bump `version` in `package.json` (minor: added or tightened; major: removed
+`scenarios.json`, regenerate the Gherkin with `go run ./tools/sdkfeaturegen` from the
+repository root, bump `version` in `package.json` (minor: added or tightened; major: removed
 or a key renamed), add a `CHANGELOG.md` entry, and run `sdk/scenarios/check.sh`. Merging to
 `main` publishes the new version (`.github/workflows/sdk-scenarios-release.yml`); each SDK then
 moves to it in its own PR. See `docs/guides/sdk-ci.md`.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@admoai/sdk-scenarios",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The cross-SDK decision & tracking scenarios every AdMoai SDK asserts against a real decision-engine. Data only.",
   "license": "MIT",
   "files": [
     "scenarios.json",
+    "scenarios.feature",
     "CHANGELOG.md",
     "README.md"
   ],

package/scenarios.feature

@@ -0,0 +1,371 @@
+# GENERATED from scenarios.json — do not edit; regenerate with: go run ./tools/sdkfeaturegen
+#
+# scenarios.json is what the iOS, Android and Flutter manifest runners execute against a
+# real decision-engine. This is its readable rendering: what every AdMoai SDK promises a
+# publisher's app, in the same words for all three. CI regenerates it and fails on any
+# difference, so it cannot drift from what the runners execute.
+# How it is published and kept fresh: docs/guides/sdk-ci.md, Section 7.
+# Manifest schemaVersion: 1
+
+Feature: Cross-SDK decision & tracking contract
+  Shared cross-SDK E2E scenario manifest. ONE definition, executed by a thin interpreter in each
+  SDK, so the three suites cannot drift. Declarative only: given a request, expect an outcome.
+  Sponsored Pin tracking scenarios add `pinTracking`: the point-tracking calls an app makes on
+  the served pins, as data, and the beacons that must reach the engine. Procedural scenarios
+  (log capture, concurrency, retry, TTL waits) stay hand-written per SDK. Mirrored
+  byte-identically into all three repos; a checksum test fails the build if the copies diverge.
+  Every expected value here was verified against a live local decision-engine before being
+  written.
+
+  @L @native
+  Scenario: L1 — a normal native ad serves with complete, well-formed metadata
+    Given the app requests placement "home"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative carries complete metadata: ad, creative, placement and template ids
+    And the creative's priority is one of standard, sponsorship, house
+    And the creative is not a Journey Ad
+    And the creative's format is "native"
+
+  @L @native
+  Scenario: L5 — a placement with no eligible ad returns a clean no-ad, not an error
+    Given the app requests placement "postroll"
+    Then no ad is served, and the placement answers with a clean no-fill
+    And exactly 1 decision is returned
+
+  @L @native
+  Scenario: L6 — the advertiser block is complete (name, legalName, logoUrl)
+    Given the app requests placement "home"
+    Then an ad is served
+    And the creative names its advertiser: name, legal name and logo
+
+  @L @native
+  Scenario: L7 — the template block carries a non-empty key
+    Given the app requests placement "home"
+    Then an ad is served
+    And the creative names its template
+
+  @L @native
+  Scenario: L8 — a served native ad exposes an impression URL, a click URL and non-empty contents
+    Given the app requests placement "home"
+    Then an ad is served
+    And the creative carries its content fields
+    And the creative exposes an impression URL
+    And the creative exposes at least 1 click URL
+
+  @M
+  Scenario: M1 — count=2 returns at most two creatives, and they are distinct
+    Given the app requests placement "promotions"
+    And placement "promotions" asks for 2 creatives
+    Then an ad is served
+    And exactly 1 decision is returned
+    And at most 2 creatives are returned
+    And the returned creatives are all different
+
+  @M
+  Scenario: M2 — three placements in one request each get their own correctly-keyed decision
+    Given the app requests placement "home"
+    And the app requests placement "promotions"
+    And the app requests placement "search"
+    Then an ad is served
+    And exactly 3 decisions are returned
+    And every requested placement comes back with its own decision
+
+  @M
+  Scenario: M3 — an advertiserId filter still serves that advertiser's ad
+    Given the app requests placement "promotions"
+    And placement "promotions" is restricted to advertiser "advertiser_01JEPGMJXARVYSJA0CAM9FQ79Y"
+    Then an ad is served
+    And the creative names its advertiser: name, legal name and logo
+
+  @M
+  Scenario: M5 — format=native on a mixed placement returns a native ad
+    Given the app requests placement "promotions"
+    And placement "promotions" asks for format "native"
+    Then an ad is served
+    And the creative's format is "native"
+
+  @M
+  Scenario: M6 — format=video on the same mixed placement returns a video ad instead
+    Given the app requests placement "promotions"
+    And placement "promotions" asks for format "video"
+    Then an ad is served
+    And the creative's format is "video"
+
+  @M
+  Scenario: M7 — omitting format still serves — the engine chooses
+    Given the app requests placement "promotions"
+    Then an ad is served
+
+  @M
+  Scenario: M8 — a journey-owned placement and a normal placement resolve independently in ONE request
+    Given the app requests placement "promotions"
+    And the app requests placement "home"
+    And the request carries a fresh session id
+    And the user has opted in to Journey Ads
+    Then an ad is served
+    And exactly 2 decisions are returned
+
+  @P @video
+  Scenario: P1 — a non-skippable JSON video exposes json delivery and five video events (no skip)
+    Given the app requests placement "json_none"
+    Then an ad is served
+    And the creative's format is "video"
+    And the creative is delivered as "json"
+    And the creative exposes exactly 5 video event URLs
+    And the video events include start, first_quartile, midpoint, third_quartile, complete
+
+  @P @video
+  Scenario: P2 — a vast_tag ad exposes its tag URL and surfaces NO engine-side beacons (no double count)
+    Given the app requests placement "vasttag_none"
+    Then an ad is served
+    And the creative is delivered as "vast_tag"
+    And the creative exposes no engine impression URL, because the VAST owns the impression
+    And the creative exposes exactly 0 video event URLs
+    And the creative exposes a VAST tag URL
+
+  @P @video
+  Scenario: P3 — a vast_xml ad exposes base64 that decodes to a VAST document, and no beacons
+    Given the app requests placement "vastxml_none"
+    Then an ad is served
+    And the creative is delivered as "vast_xml"
+    And the creative exposes no engine impression URL, because the VAST owns the impression
+    And the creative exposes exactly 0 video event URLs
+    And the creative's inline VAST XML decodes to a VAST document
+
+  @P @video
+  Scenario: P6 — a skippable video resolves skippability from ENGINE METADATA, plus a sixth skip event
+    Given the app requests placement "json_none_skippable"
+    Then an ad is served
+    And the creative exposes exactly 6 video event URLs
+    And the metadata says the video is skippable
+    And the metadata's skip offset is 5 seconds
+    And the SDK's skippable helper says the video is skippable
+    And the SDK's skip-offset helper returns "5"
+
+  @P @video
+  Scenario: P8 — an end-card video reports its configured endCardMode
+    Given the app requests placement "json_native_endcard"
+    Then an ad is served
+    And the end-card mode is "native_endcard"
+
+  @V @validation
+  Scenario: V1 — an unknown placement key raises a typed validation error, not a silent no-fill
+    Given the app requests placement "definitely_not_a_real_placement"
+    Then the request fails
+    And the SDK surfaces a typed validation error with HTTP status 422
+    And the engine's error code is 10017
+
+  @V @validation
+  Scenario: V3 — an unknown custom-targeting key is rejected by the engine
+    Given the app requests placement "home"
+    And the custom target "not_a_configured_preset" is "x"
+    Then the request fails
+    And the SDK surfaces a typed validation error with HTTP status 422
+    And the engine's error code is 10028
+
+  @V @validation
+  Scenario: V4 — the SDK deduplicates a repeated custom key, so the engine never sees the duplicate that would fail the whole request
+    Sent raw over HTTP this same payload returns 422 code 10031, and the engine aborts
+    validation for the ENTIRE request — every placement, not just the offending target. All
+    three SDKs dedupe by key (last write wins), so a publisher cannot reach that state through
+    the public API. This scenario is the live proof of that guard: it must SERVE, and both
+    placements must come back.
+
+    Given the app requests placement "home"
+    And the app requests placement "promotions"
+    And the custom target "category" is "sports"
+    And the custom target "category" is "news"
+    Then an ad is served
+    And exactly 2 decisions are returned
+    And every requested placement comes back with its own decision
+
+  @V @validation
+  Scenario: V5 — a single valid custom target does not break serving
+    Given the app requests placement "home"
+    And the custom target "category" is "sports"
+    Then an ad is served
+
+  @V @validation
+  Scenario: V6 — a count above the documented maximum is rejected
+    Given the app requests placement "home"
+    And placement "home" asks for 99 creatives
+    Then the request fails
+    And the SDK surfaces a typed validation error with HTTP status 422
+    And the engine's error code is 10016
+
+  @V @validation
+  Scenario: V9 — a request with no placements fails locally, before any network call
+    Given the app requests no placements
+    Then the request fails
+    And the SDK rejects the request itself, before any network call
+
+  @Z @legacy-version
+  Scenario: Z1 — API version 2025-01-01 still serves a native ad and never a journey block
+    Given the app sends X-Decision-Version "2025-01-01"
+    And the app requests placement "home"
+    Then an ad is served
+    And the creative carries complete metadata: ad, creative, placement and template ids
+    And the creative is not a Journey Ad
+
+  @Z @legacy-version
+  Scenario: Z2 — omitting the version header still serves (engine falls back to the oldest active version)
+    Given the app sends no X-Decision-Version header
+    And the app requests placement "home"
+    Then an ad is served
+    And the creative is not a Journey Ad
+
+  @SP @sponsored-pin
+  Scenario: SP1 — a radius search returns the campaign's own shops, nearest first
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 2 pins
+    And the pins are ordered nearest first
+    And every pin is one of the advertiser's locations, with a name and a distance
+
+  @SP @sponsored-pin
+  Scenario: SP2 — a bounds search returns them too — the other shape a map can ask with
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins inside the map area north -33.3, south -33.55, east -70.45, west -70.65, around (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 2 pins
+    And every pin is one of the advertiser's locations, with a name and a distance
+
+  @SP @sponsored-pin
+  Scenario: SP3 — every returned shop carries its own view, tap and click beacons
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And every pin carries its own view, tap and click beacons
+
+  @SP @sponsored-pin
+  Scenario: SP4 — every returned shop carries a resolved destination, its own or the creative's
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And every pin carries a resolved destination URL
+
+  @SP @sponsored-pin
+  Scenario: SP5 — the request's limit narrows how many shops come back
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    And the search asks for at most 2 pins
+    Then an ad is served
+    And the ad carries exactly 2 pins
+
+  @SP @sponsored-pin
+  Scenario: SP6 — a tight radius excludes the shops outside it
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 1500 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries exactly 1 pin
+
+  @SP @sponsored-pin
+  Scenario: SP7 — without a distance search a Sponsored Pin campaign does not serve at all
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    Then no ad is served, and the placement answers with a clean no-fill
+
+  @SP @sponsored-pin
+  Scenario: SP8 — on the older API version the ad still serves, silently carrying no pins — the failure an integrator must recognise
+    Given the app sends no X-Decision-Version header
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries no pins
+
+  @SP @sponsored-pin
+  Scenario: SP9 — a map's first render sends every shop's view beacon exactly once
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 1 pin
+    And every pin carries its own view, tap and click beacons
+    When the app shows every pin
+    Then each shown pin's view beacon reaches the engine exactly once per response, and no pin the app never showed sends one
+    And the engine accepts every beacon
+
+  @SP @sponsored-pin
+  Scenario: SP10 — re-rendering the same response sends no view beacon again
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 1 pin
+    And every pin carries its own view, tap and click beacons
+    When the app shows every pin
+    And the app shows every pin
+    And the app shows every pin
+    Then each shown pin's view beacon reaches the engine exactly once per response, and no pin the app never showed sends one
+    And the engine accepts every beacon
+
+  @SP @sponsored-pin
+  Scenario: SP11 — a render that brings new shops into view sends views only for the new ones
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 4 pins
+    And every pin carries its own view, tap and click beacons
+    When the app shows the first 2 pins
+    And the app shows pins 2 to 4
+    And the app shows the first 4 pins
+    Then each shown pin's view beacon reaches the engine exactly once per response, and no pin the app never showed sends one
+    And the engine accepts every beacon
+
+  @SP @sponsored-pin
+  Scenario: SP12 — a new decision response reports the same shops again, once
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 1 pin
+    And every pin carries its own view, tap and click beacons
+    When the app shows every pin
+    And the app fetches a new decision response for the same search
+    And the app shows every pin
+    And the app shows every pin
+    Then each shown pin's view beacon reaches the engine exactly once per response, and no pin the app never showed sends one
+    And a new response carries new view beacons for the same pins
+    And the engine accepts every beacon
+
+  @SP @sponsored-pin
+  Scenario: SP13 — single-pin views follow the same once-per-response rule as the bulk call
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 1 pin
+    And every pin carries its own view, tap and click beacons
+    When the app shows pin 1 on its own
+    And the app shows pin 1 on its own
+    And the app shows every pin
+    And the app shows pin 1 on its own
+    Then each shown pin's view beacon reaches the engine exactly once per response, and no pin the app never showed sends one
+    And the engine accepts every beacon
+
+  @SP @sponsored-pin
+  Scenario: SP14 — taps and clicks are sent on every call, never de-duplicated
+    Given the app sends X-Decision-Version "2025-11-01"
+    And the app requests placement "poi"
+    And the app searches for pins within 20000 m of (-33.4175, -70.6065)
+    Then an ad is served
+    And the ad carries at least 1 pin
+    And every pin carries its own view, tap and click beacons
+    When the app shows every pin
+    And the user taps pin 1
+    And the user taps pin 1
+    And the user clicks pin 1
+    And the user clicks pin 1
+    And the app shows every pin
+    Then each shown pin's view beacon reaches the engine exactly once per response, and no pin the app never showed sends one
+    And every tap and every click sends its beacon, on every call
+    And the engine accepts every beacon