@admoai/sdk-scenarios 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.2.0 — 2026-11-05
+
+Adds `fixtureScenarios` F1–F15 and moves `schemaVersion` to 2 (admoai/adhub#4733): offline
+scenarios for the six standard native formats, so every SDK proves it decodes them before the
+engine serves them. Each decodes one golden decision-wire file, shipped in this package under
+`fixtures/golden-wire/` (byte-identical to adhub's `ui/platform/lib/ad-formats/golden-wire/`,
+copied at publish), optionally edited (`edits`: remove or add a field at one level), and asserts
+what the app reads: the standard format, version and template source (null = absent), content
+keys present and absent, slides in server order with their ids, positions and own trackers,
+click, custom and video-event keys, and matched points. F14 is the gate-off wire (the three
+standard fields removed); F15 adds unknown fields at every level. The 39 live scenarios are
+unchanged. A runner that does not execute `fixtureScenarios` must refuse schemaVersion 2, so an
+SDK cannot adopt this version and skip them silently.
+
+## 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
 
@@ -18,10 +20,20 @@ curl -sSfL "https://registry.npmjs.org/@admoai/sdk-scenarios/-/sdk-scenarios-$VE
   | tar -xzO package/scenarios.json | cmp - path/to/vendored/scenarios.json
 ```
 
+From `schemaVersion` 2 the manifest also holds `fixtureScenarios`: offline scenarios that decode
+a golden decision-wire file, so vendor `fixtures/golden-wire/` (the whole directory) beside the
+manifest and verify those bytes the same way, file by file, against the tarball's
+`package/fixtures/golden-wire/<file>`. A runner that cannot execute `fixtureScenarios` must
+refuse a schemaVersion 2 manifest.
+
 ## 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
+`main` publishes the new version (`.github/workflows/sdk-scenarios-release.yml`, which first runs
+`sdk/scenarios/stage-fixtures.sh` to copy adhub's `ui/platform/lib/ad-formats/golden-wire/*.json`
+into the package's `fixtures/golden-wire/`; that directory is never committed, and a change to a
+golden file needs a version bump too); each SDK then
 moves to it in its own PR. See `docs/guides/sdk-ci.md`.

package/fixtures/golden-wire/branded_assets.full.json

@@ -0,0 +1,74 @@
+{
+  "success": true,
+  "data": [
+    {
+      "placement": "map_vehicles",
+      "creatives": [
+        {
+          "contents": [
+            {
+              "key": "branded_image",
+              "type": "image",
+              "value": "https://cdn.admoai.com/media/volta-car.png"
+            },
+            {
+              "key": "accessible_label",
+              "type": "text",
+              "value": "Volta Coffee car"
+            },
+            {
+              "key": "destination_url",
+              "type": "url",
+              "value": "https://volta.example/menu"
+            }
+          ],
+          "advertiser": {
+            "name": "Volta Coffee",
+            "legalName": "Volta Coffee SpA",
+            "logoUrl": "https://cdn.admoai.com/media/volta-logo.png"
+          },
+          "template": {
+            "key": "branded_assets",
+            "style": "branded_asset"
+          },
+          "tracking": {
+            "impressions": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.branded_assets.full.impression"
+              }
+            ],
+            "clicks": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.branded_assets.full.click"
+              }
+            ],
+            "custom": [
+              {
+                "key": "asset_tap",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.branded_assets.full.asset_tap"
+              }
+            ]
+          },
+          "metadata": {
+            "adId": "ad_01JDBPXZN4D94EPQC5MVQB9MR6",
+            "creativeId": "creative_01JD1Z5CNM4GMHEJJFHCYWGKJ4",
+            "advertiserId": "advertiser_01JDH315KXW0FP82VY8WMV97YE",
+            "placementId": "placement_01JDGX7Z9JHJR8PN9HZJPDNFWA",
+            "templateId": "template_01JDKPBTZ611WAFQXYSNYMNXQ1",
+            "priority": "standard",
+            "language": "en",
+            "format": "native",
+            "effectiveStandardFormatKey": "branded_assets",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": "vehicle_marker"
+          }
+        }
+      ]
+    }
+  ],
+  "errors": null,
+  "warnings": null
+}

package/fixtures/golden-wire/branded_assets.minimal.json

@@ -0,0 +1,59 @@
+{
+  "success": true,
+  "data": [
+    {
+      "placement": "map_vehicles",
+      "creatives": [
+        {
+          "contents": [
+            {
+              "key": "branded_image",
+              "type": "image",
+              "value": "https://cdn.admoai.com/media/volta-car.png"
+            }
+          ],
+          "advertiser": {
+            "name": "Volta Coffee",
+            "legalName": "Volta Coffee SpA",
+            "logoUrl": "https://cdn.admoai.com/media/volta-logo.png"
+          },
+          "template": {
+            "key": "branded_assets",
+            "style": "branded_asset"
+          },
+          "tracking": {
+            "impressions": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.branded_assets.minimal.impression"
+              }
+            ],
+            "clicks": [],
+            "custom": [
+              {
+                "key": "asset_tap",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.branded_assets.minimal.asset_tap"
+              }
+            ]
+          },
+          "metadata": {
+            "adId": "ad_01JD5G0KWPJS27NVHD88PECDV3",
+            "creativeId": "creative_01JDNVFDYH4MJS4NEPTAW7BTG8",
+            "advertiserId": "advertiser_01JDH315KXW0FP82VY8WMV97YE",
+            "placementId": "placement_01JDGX7Z9JHJR8PN9HZJPDNFWA",
+            "templateId": "template_01JDZZDBFPJPN49AB9VF53KXKX",
+            "priority": "standard",
+            "language": "en",
+            "format": "native",
+            "effectiveStandardFormatKey": "branded_assets",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": "vehicle_marker"
+          }
+        }
+      ]
+    }
+  ],
+  "errors": null,
+  "warnings": null
+}

package/fixtures/golden-wire/card.derived.json

@@ -0,0 +1,78 @@
+{
+  "success": true,
+  "data": [
+    {
+      "placement": "home_feed",
+      "creatives": [
+        {
+          "contents": [
+            {
+              "key": "image",
+              "type": "image",
+              "value": "https://cdn.admoai.com/media/volta-latte.jpg"
+            },
+            {
+              "key": "headline",
+              "type": "text",
+              "value": "Two lattes, one price"
+            },
+            {
+              "key": "destination_url",
+              "type": "url",
+              "value": "https://volta.example/menu"
+            },
+            {
+              "key": "promo_code",
+              "type": "text",
+              "value": "VOLTA2X1"
+            }
+          ],
+          "advertiser": {
+            "name": "Volta Coffee",
+            "legalName": "Volta Coffee SpA",
+            "logoUrl": "https://cdn.admoai.com/media/volta-logo.png"
+          },
+          "template": {
+            "key": "city_promo_display",
+            "style": "compact"
+          },
+          "tracking": {
+            "impressions": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.derived.impression"
+              }
+            ],
+            "clicks": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.derived.click"
+              }
+            ],
+            "custom": [
+              {
+                "key": "save_offer",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.derived.save_offer"
+              }
+            ]
+          },
+          "metadata": {
+            "adId": "ad_01JDQA9PJQC1M206VCD5CCX4ZM",
+            "creativeId": "creative_01JDF9Z54P5KNER7PRNWGZB98F",
+            "advertiserId": "advertiser_01JDH315KXW0FP82VY8WMV97YE",
+            "placementId": "placement_01JDGX7Z9JHJR8PN9HZJPDNFWA",
+            "templateId": "template_01JD7MGVP04YN16MAY9WW89EVB",
+            "priority": "standard",
+            "language": "en",
+            "format": "native",
+            "effectiveStandardFormatKey": "card",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "based_on_standard"
+          }
+        }
+      ]
+    }
+  ],
+  "errors": null,
+  "warnings": null
+}

package/fixtures/golden-wire/card.full.json

@@ -0,0 +1,83 @@
+{
+  "success": true,
+  "data": [
+    {
+      "placement": "home_feed",
+      "creatives": [
+        {
+          "contents": [
+            {
+              "key": "image",
+              "type": "image",
+              "value": "https://cdn.admoai.com/media/volta-latte.jpg"
+            },
+            {
+              "key": "brand_logo",
+              "type": "image",
+              "value": "https://cdn.admoai.com/media/volta-logo.png"
+            },
+            {
+              "key": "headline",
+              "type": "text",
+              "value": "Two lattes, one price"
+            },
+            {
+              "key": "supporting_text",
+              "type": "text",
+              "value": "This week at every Volta in Santiago."
+            },
+            {
+              "key": "cta_text",
+              "type": "text",
+              "value": "See the menu"
+            },
+            {
+              "key": "destination_url",
+              "type": "url",
+              "value": "https://volta.example/menu"
+            }
+          ],
+          "advertiser": {
+            "name": "Volta Coffee",
+            "legalName": "Volta Coffee SpA",
+            "logoUrl": "https://cdn.admoai.com/media/volta-logo.png"
+          },
+          "template": {
+            "key": "card",
+            "style": "tall"
+          },
+          "tracking": {
+            "impressions": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.full.impression"
+              }
+            ],
+            "clicks": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.full.click"
+              }
+            ],
+            "custom": []
+          },
+          "metadata": {
+            "adId": "ad_01JDC69A0M6C0QGBF17PHDJ81B",
+            "creativeId": "creative_01JDJFV4GFKCR82452R7XXHX23",
+            "advertiserId": "advertiser_01JDH315KXW0FP82VY8WMV97YE",
+            "placementId": "placement_01JDGX7Z9JHJR8PN9HZJPDNFWA",
+            "templateId": "template_01JD19FWQSE5QZCVMVD705VQ89",
+            "priority": "standard",
+            "language": "en",
+            "format": "native",
+            "effectiveStandardFormatKey": "card",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard"
+          }
+        }
+      ]
+    }
+  ],
+  "errors": null,
+  "warnings": null
+}

package/fixtures/golden-wire/card.minimal.json

@@ -0,0 +1,63 @@
+{
+  "success": true,
+  "data": [
+    {
+      "placement": "home_feed",
+      "creatives": [
+        {
+          "contents": [
+            {
+              "key": "image",
+              "type": "image",
+              "value": "https://cdn.admoai.com/media/volta-latte.jpg"
+            },
+            {
+              "key": "destination_url",
+              "type": "url",
+              "value": "https://volta.example/menu"
+            }
+          ],
+          "advertiser": {
+            "name": "Volta Coffee",
+            "legalName": "Volta Coffee SpA",
+            "logoUrl": "https://cdn.admoai.com/media/volta-logo.png"
+          },
+          "template": {
+            "key": "card",
+            "style": "default"
+          },
+          "tracking": {
+            "impressions": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.minimal.impression"
+              }
+            ],
+            "clicks": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.card.minimal.click"
+              }
+            ],
+            "custom": []
+          },
+          "metadata": {
+            "adId": "ad_01JD0R43Z2P97HWMHKNQKAY7EN",
+            "creativeId": "creative_01JD5WRV1EZCS0CB082W50BVNR",
+            "advertiserId": "advertiser_01JDH315KXW0FP82VY8WMV97YE",
+            "placementId": "placement_01JDGX7Z9JHJR8PN9HZJPDNFWA",
+            "templateId": "template_01JD1V81MZ1C8PC6HYXYPBQA8R",
+            "priority": "standard",
+            "language": "en",
+            "format": "native",
+            "effectiveStandardFormatKey": "card",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard"
+          }
+        }
+      ]
+    }
+  ],
+  "errors": null,
+  "warnings": null
+}

package/fixtures/golden-wire/carousel.derived.json

@@ -0,0 +1,119 @@
+{
+  "success": true,
+  "data": [
+    {
+      "placement": "home_feed",
+      "creatives": [
+        {
+          "contents": [
+            {
+              "key": "slides",
+              "type": "group",
+              "value": [
+                {
+                  "slideId": "slide_01JDS1H8VEM0ABE2PQ0JY6S38W",
+                  "position": 1,
+                  "contents": [
+                    {
+                      "key": "image",
+                      "type": "image",
+                      "value": "https://cdn.admoai.com/media/slide-a.jpg"
+                    },
+                    {
+                      "key": "destination_url",
+                      "type": "url",
+                      "value": "https://volta.example/a"
+                    }
+                  ],
+                  "tracking": {
+                    "views": [
+                      {
+                        "key": "slide_view",
+                        "url": "https://api.admoai.com/v1/tracking?e=tok.carousel.derived.slide1.slide_view"
+                      }
+                    ],
+                    "clicks": [
+                      {
+                        "key": "default",
+                        "url": "https://api.admoai.com/v1/tracking?e=tok.carousel.derived.slide1.click"
+                      }
+                    ]
+                  }
+                },
+                {
+                  "slideId": "slide_01JDDGXJE0JDBY21Y9KEJDD54A",
+                  "position": 2,
+                  "contents": [
+                    {
+                      "key": "image",
+                      "type": "image",
+                      "value": "https://cdn.admoai.com/media/slide-b.jpg"
+                    },
+                    {
+                      "key": "destination_url",
+                      "type": "url",
+                      "value": "https://volta.example/b"
+                    }
+                  ],
+                  "tracking": {
+                    "views": [
+                      {
+                        "key": "slide_view",
+                        "url": "https://api.admoai.com/v1/tracking?e=tok.carousel.derived.slide2.slide_view"
+                      }
+                    ],
+                    "clicks": [
+                      {
+                        "key": "default",
+                        "url": "https://api.admoai.com/v1/tracking?e=tok.carousel.derived.slide2.click"
+                      }
+                    ]
+                  }
+                }
+              ]
+            },
+            {
+              "key": "promo_code",
+              "type": "text",
+              "value": "VOLTA2X1"
+            }
+          ],
+          "advertiser": {
+            "name": "Volta Coffee",
+            "legalName": "Volta Coffee SpA",
+            "logoUrl": "https://cdn.admoai.com/media/volta-logo.png"
+          },
+          "template": {
+            "key": "city_carousel",
+            "style": "carousel"
+          },
+          "tracking": {
+            "impressions": [
+              {
+                "key": "default",
+                "url": "https://api.admoai.com/v1/tracking?e=tok.carousel.derived.impression"
+              }
+            ],
+            "clicks": [],
+            "custom": []
+          },
+          "metadata": {
+            "adId": "ad_01JD849HTYNJ7SX6H5JRBKZ069",
+            "creativeId": "creative_01JDS1H8VEM0ABE2PQ0JY6S38W",
+            "advertiserId": "advertiser_01JDH315KXW0FP82VY8WMV97YE",
+            "placementId": "placement_01JDGX7Z9JHJR8PN9HZJPDNFWA",
+            "templateId": "template_01JDDGXJE0JDBY21Y9KEJDD54A",
+            "priority": "standard",
+            "language": "en",
+            "format": "native",
+            "effectiveStandardFormatKey": "carousel",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "based_on_standard"
+          }
+        }
+      ]
+    }
+  ],
+  "errors": null,
+  "warnings": null
+}