@admoai/sdk-scenarios 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+Versioning: a scenario added or an `expect` tightened is a **minor** release; a scenario
+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.0.0 — 2026-10-20
+
+The 39 scenarios the three SDKs already carried, byte for byte (sha256 `a55f68eb…`):
+L1 L5 L6 L7 L8 · M1 M2 M3 M5 M6 M7 M8 · P1 P2 P3 P6 P8 · V1 V3 V4 V5 V6 V9 · Z1 Z2 · SP1–SP14.
+First release from adhub, the source of truth since admoai/adhub#4158; before it the file was
+mirrored into each SDK repo and held equal by a hash in each and a parity check in adhub.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @admoai/sdk-scenarios
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The scenarios every AdMoai mobile SDK (iOS, Android, Flutter) must pass against a real
+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.
+
+## For an SDK
+
+Vendor one version and pin it; your CI verifies the vendored bytes against the published
+tarball, and your tests read the vendored file (they never touch the network):
+
+```bash
+curl -sSfL "https://registry.npmjs.org/@admoai/sdk-scenarios/-/sdk-scenarios-$VERSION.tgz" \
+  | tar -xzO package/scenarios.json | cmp - path/to/vendored/scenarios.json
+```
+
+## 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
+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,6 +1,16 @@
 {
   "name": "@admoai/sdk-scenarios",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The cross-SDK decision & tracking scenarios every AdMoai SDK asserts against a real decision-engine. Data only.",
+  "license": "MIT",
+  "files": [
+    "scenarios.json",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "keywords": [
+    "admoai",
+    "sdk",
+    "contract-tests"
+  ]
+}

package/scenarios.json

@@ -0,0 +1,946 @@
+{
+  "schemaVersion": 1,
+  "description": "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.",
+  "scenarios": [
+    {
+      "id": "L1",
+      "title": "a normal native ad serves with complete, well-formed metadata",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "requireMetadata": true,
+          "journey": false,
+          "formatEquals": "native",
+          "priorityIn": [
+            "standard",
+            "sponsorship",
+            "house"
+          ]
+        }
+      }
+    },
+    {
+      "id": "L5",
+      "title": "a placement with no eligible ad returns a clean no-ad, not an error",
+      "request": {
+        "placements": [
+          {
+            "key": "postroll"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "noAd",
+        "decisions": 1
+      }
+    },
+    {
+      "id": "L6",
+      "title": "the advertiser block is complete (name, legalName, logoUrl)",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "requireAdvertiser": true
+        }
+      }
+    },
+    {
+      "id": "L7",
+      "title": "the template block carries a non-empty key",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "requireTemplate": true
+        }
+      }
+    },
+    {
+      "id": "L8",
+      "title": "a served native ad exposes an impression URL, a click URL and non-empty contents",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "impressions": "required",
+          "clicksAtLeast": 1,
+          "requireContents": true
+        }
+      }
+    },
+    {
+      "id": "M1",
+      "title": "count=2 returns at most two creatives, and they are distinct",
+      "request": {
+        "placements": [
+          {
+            "key": "promotions",
+            "count": 2
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creativesAtMost": 2,
+        "creativesDistinct": true
+      }
+    },
+    {
+      "id": "M2",
+      "title": "three placements in one request each get their own correctly-keyed decision",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          },
+          {
+            "key": "promotions"
+          },
+          {
+            "key": "search"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 3,
+        "decisionsMatchRequest": true
+      }
+    },
+    {
+      "id": "M3",
+      "title": "an advertiserId filter still serves that advertiser's ad",
+      "request": {
+        "placements": [
+          {
+            "key": "promotions",
+            "advertiserId": "advertiser_01JEPGMJXARVYSJA0CAM9FQ79Y"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "requireAdvertiser": true
+        }
+      }
+    },
+    {
+      "id": "M5",
+      "title": "format=native on a mixed placement returns a native ad",
+      "request": {
+        "placements": [
+          {
+            "key": "promotions",
+            "format": "native"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "formatEquals": "native"
+        }
+      }
+    },
+    {
+      "id": "M6",
+      "title": "format=video on the same mixed placement returns a video ad instead",
+      "request": {
+        "placements": [
+          {
+            "key": "promotions",
+            "format": "video"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "formatEquals": "video"
+        }
+      }
+    },
+    {
+      "id": "M7",
+      "title": "omitting format still serves \u2014 the engine chooses",
+      "request": {
+        "placements": [
+          {
+            "key": "promotions"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served"
+      }
+    },
+    {
+      "id": "M8",
+      "title": "a journey-owned placement and a normal placement resolve independently in ONE request",
+      "request": {
+        "placements": [
+          {
+            "key": "promotions"
+          },
+          {
+            "key": "home"
+          }
+        ],
+        "session": "auto",
+        "journeyOpt": "in"
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 2
+      }
+    },
+    {
+      "id": "P1",
+      "title": "a non-skippable JSON video exposes json delivery and five video events (no skip)",
+      "request": {
+        "placements": [
+          {
+            "key": "json_none"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "deliveryEquals": "json",
+          "formatEquals": "video",
+          "videoEventCount": 5,
+          "videoEventKeys": [
+            "start",
+            "first_quartile",
+            "midpoint",
+            "third_quartile",
+            "complete"
+          ]
+        }
+      }
+    },
+    {
+      "id": "P2",
+      "title": "a vast_tag ad exposes its tag URL and surfaces NO engine-side beacons (no double count)",
+      "request": {
+        "placements": [
+          {
+            "key": "vasttag_none"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "deliveryEquals": "vast_tag",
+          "requireVastTagUrl": true,
+          "videoEventCount": 0,
+          "impressions": "forbidden"
+        }
+      }
+    },
+    {
+      "id": "P3",
+      "title": "a vast_xml ad exposes base64 that decodes to a VAST document, and no beacons",
+      "request": {
+        "placements": [
+          {
+            "key": "vastxml_none"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "deliveryEquals": "vast_xml",
+          "requireVastXmlDecodes": true,
+          "videoEventCount": 0,
+          "impressions": "forbidden"
+        }
+      }
+    },
+    {
+      "id": "P6",
+      "title": "a skippable video resolves skippability from ENGINE METADATA, plus a sixth skip event",
+      "request": {
+        "placements": [
+          {
+            "key": "json_none_skippable"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "metadataIsSkippable": true,
+          "skipOffsetSecondsEquals": 5,
+          "helperIsSkippable": true,
+          "helperSkipOffsetEquals": "5",
+          "videoEventCount": 6
+        }
+      }
+    },
+    {
+      "id": "P8",
+      "title": "an end-card video reports its configured endCardMode",
+      "request": {
+        "placements": [
+          {
+            "key": "json_native_endcard"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "endCardModeEquals": "native_endcard"
+        }
+      }
+    },
+    {
+      "id": "V1",
+      "title": "an unknown placement key raises a typed validation error, not a silent no-fill",
+      "request": {
+        "placements": [
+          {
+            "key": "definitely_not_a_real_placement"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "error",
+        "error": {
+          "kind": "validation",
+          "status": 422,
+          "code": 10017
+        }
+      }
+    },
+    {
+      "id": "V3",
+      "title": "an unknown custom-targeting key is rejected by the engine",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ],
+        "custom": [
+          {
+            "key": "not_a_configured_preset",
+            "value": "x"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "error",
+        "error": {
+          "kind": "validation",
+          "status": 422,
+          "code": 10028
+        }
+      }
+    },
+    {
+      "id": "V4",
+      "title": "the SDK deduplicates a repeated custom key, so the engine never sees the duplicate that would fail the whole request",
+      "comment": "Sent raw over HTTP this same payload returns 422 code 10031, and the engine aborts validation for the ENTIRE request \u2014 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.",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          },
+          {
+            "key": "promotions"
+          }
+        ],
+        "custom": [
+          {
+            "key": "category",
+            "value": "sports"
+          },
+          {
+            "key": "category",
+            "value": "news"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 2,
+        "decisionsMatchRequest": true
+      }
+    },
+    {
+      "id": "V5",
+      "title": "a single valid custom target does not break serving",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ],
+        "custom": [
+          {
+            "key": "category",
+            "value": "sports"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served"
+      }
+    },
+    {
+      "id": "V6",
+      "title": "a count above the documented maximum is rejected",
+      "request": {
+        "placements": [
+          {
+            "key": "home",
+            "count": 99
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "error",
+        "error": {
+          "kind": "validation",
+          "status": 422,
+          "code": 10016
+        }
+      }
+    },
+    {
+      "id": "V9",
+      "title": "a request with no placements fails locally, before any network call",
+      "request": {
+        "placements": []
+      },
+      "expect": {
+        "outcome": "error",
+        "error": {
+          "kind": "local"
+        }
+      }
+    },
+    {
+      "id": "Z1",
+      "title": "API version 2025-01-01 still serves a native ad and never a journey block",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ],
+        "apiVersion": "2025-01-01"
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "journey": false,
+          "requireMetadata": true
+        }
+      }
+    },
+    {
+      "id": "Z2",
+      "title": "omitting the version header still serves (engine falls back to the oldest active version)",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ],
+        "apiVersion": "none"
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "journey": false
+        }
+      }
+    },
+    {
+      "id": "SP1",
+      "title": "a radius search returns the campaign's own shops, nearest first",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 2,
+          "matchedPointsNearestFirst": true,
+          "matchedPointsWellFormed": true
+        }
+      }
+    },
+    {
+      "id": "SP2",
+      "title": "a bounds search returns them too \u2014 the other shape a map can ask with",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "bounds": {
+            "north": -33.3,
+            "south": -33.55,
+            "east": -70.45,
+            "west": -70.65
+          }
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 2,
+          "matchedPointsWellFormed": true
+        }
+      }
+    },
+    {
+      "id": "SP3",
+      "title": "every returned shop carries its own view, tap and click beacons",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsHaveBeacons": true
+        }
+      }
+    },
+    {
+      "id": "SP4",
+      "title": "every returned shop carries a resolved destination, its own or the creative's",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsHaveClickUrl": true
+        }
+      }
+    },
+    {
+      "id": "SP5",
+      "title": "the request's limit narrows how many shops come back",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000,
+          "limit": 2
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsEquals": 2
+        }
+      }
+    },
+    {
+      "id": "SP6",
+      "title": "a tight radius excludes the shops outside it",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 1500
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsEquals": 1
+        }
+      }
+    },
+    {
+      "id": "SP7",
+      "title": "without a distance search a Sponsored Pin campaign does not serve at all",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "noAd"
+      }
+    },
+    {
+      "id": "SP8",
+      "title": "on the older API version the ad still serves, silently carrying no pins \u2014 the failure an integrator must recognise",
+      "request": {
+        "apiVersion": "none",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsNone": true
+        }
+      }
+    },
+    {
+      "id": "SP9",
+      "title": "a map's first render sends every shop's view beacon exactly once",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 1,
+          "matchedPointsHaveBeacons": true
+        }
+      },
+      "pinTracking": {
+        "steps": [
+          {
+            "views": "all"
+          }
+        ],
+        "expect": {
+          "viewsOncePerResponse": true,
+          "engineAcceptsEveryBeacon": true
+        }
+      }
+    },
+    {
+      "id": "SP10",
+      "title": "re-rendering the same response sends no view beacon again",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 1,
+          "matchedPointsHaveBeacons": true
+        }
+      },
+      "pinTracking": {
+        "steps": [
+          {
+            "views": "all"
+          },
+          {
+            "views": "all"
+          },
+          {
+            "views": "all"
+          }
+        ],
+        "expect": {
+          "viewsOncePerResponse": true,
+          "engineAcceptsEveryBeacon": true
+        }
+      }
+    },
+    {
+      "id": "SP11",
+      "title": "a render that brings new shops into view sends views only for the new ones",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 4,
+          "matchedPointsHaveBeacons": true
+        }
+      },
+      "pinTracking": {
+        "steps": [
+          {
+            "views": {
+              "from": 0,
+              "to": 2
+            }
+          },
+          {
+            "views": {
+              "from": 1,
+              "to": 4
+            }
+          },
+          {
+            "views": {
+              "from": 0,
+              "to": 4
+            }
+          }
+        ],
+        "expect": {
+          "viewsOncePerResponse": true,
+          "engineAcceptsEveryBeacon": true
+        }
+      }
+    },
+    {
+      "id": "SP12",
+      "title": "a new decision response reports the same shops again, once",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 1,
+          "matchedPointsHaveBeacons": true
+        }
+      },
+      "pinTracking": {
+        "steps": [
+          {
+            "views": "all"
+          },
+          {
+            "newResponse": true
+          },
+          {
+            "views": "all"
+          },
+          {
+            "views": "all"
+          }
+        ],
+        "expect": {
+          "viewsOncePerResponse": true,
+          "newResponseHasNewViewUrls": true,
+          "engineAcceptsEveryBeacon": true
+        }
+      }
+    },
+    {
+      "id": "SP13",
+      "title": "single-pin views follow the same once-per-response rule as the bulk call",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 1,
+          "matchedPointsHaveBeacons": true
+        }
+      },
+      "pinTracking": {
+        "steps": [
+          {
+            "view": 0
+          },
+          {
+            "view": 0
+          },
+          {
+            "views": "all"
+          },
+          {
+            "view": 0
+          }
+        ],
+        "expect": {
+          "viewsOncePerResponse": true,
+          "engineAcceptsEveryBeacon": true
+        }
+      }
+    },
+    {
+      "id": "SP14",
+      "title": "taps and clicks are sent on every call, never de-duplicated",
+      "request": {
+        "apiVersion": "2025-11-01",
+        "placements": [
+          {
+            "key": "poi"
+          }
+        ],
+        "distance": {
+          "latitude": -33.4175,
+          "longitude": -70.6065,
+          "radius": 20000
+        }
+      },
+      "expect": {
+        "outcome": "served",
+        "creative": {
+          "matchedPointsAtLeast": 1,
+          "matchedPointsHaveBeacons": true
+        }
+      },
+      "pinTracking": {
+        "steps": [
+          {
+            "views": "all"
+          },
+          {
+            "tap": 0
+          },
+          {
+            "tap": 0
+          },
+          {
+            "click": 0
+          },
+          {
+            "click": 0
+          },
+          {
+            "views": "all"
+          }
+        ],
+        "expect": {
+          "viewsOncePerResponse": true,
+          "interactionsEveryCall": true,
+          "engineAcceptsEveryBeacon": true
+        }
+      }
+    }
+  ]
+}