@roku-sdk/ads 0.0.0-stage → 2.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roku, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# `@roku-sdk/ads`
 
-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.
+> ⚠️ **Development Notice:** This package's interface may still change between releases. Pin the version and re-read the types after an upgrade.
+
+Ad support for Roku SceneGraph TypeScript apps via the Roku Advertising Framework (RAF), across all three insertion modes:
+
+| Mode | Command sequence | Needs |
+| --- | --- | --- |
+| **CSAI** — client-side insertion | `getAds` → `showAds` per break | `adView` + `contentView` |
+| **SSAI** — server-stitched insertion | `getAds` → `stitchedAdsInit` | `contentView` |
+| **CSAS** — client-side stitching | `getAds` → `constructStitchedStream` → `renderStitchedStream` | `adView` + `contentMetadata`; renders no app-owned `Video` |
+
+`<Ads>` is a headless SceneGraph Task driven by writing props rather than by calling methods: wait for `onAdsState` to report `"ready"`, set the data fields, set `command` last, then read the result off the matching callback.
+
+Every string result is cleared to `"none"` before its real value, so from the second command onwards each handler is called with that sentinel first — treat it as "no result yet". Only the first command hides it, because the field already holds `"none"` and writing a field the value it already has notifies nobody. The same comparison is why re-issuing a command with the value it already has does nothing at all.
+
+Mid-roll needs no cue-point loop in the app — the task observes `contentView`'s position and calls RAF's `getAds` itself at each cue point, handing back the pods due now.
+
+Requires `bs_libs_required: "roku_ads_lib"` in the app's `manifestEntries`; without it RAF never reports ready and every command is written into a void.
+
+One worked example per mode lives in [`examples/ads`](../../examples/ads).

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@roku-sdk/ads",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.19.0",
+  "description": "Roku Advertising Framework (RAF) bridge for SceneGraph",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "engines": {
+    "npm": ">=8.5.0",
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@roku-sdk/components": "2.19.0",
+    "@roku-sdk/interfaces": "2.19.0",
+    "@roku-sdk/solid": "2.19.0",
+    "@roku-sdk/common": "2.19.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@roku-sdk/dev-tools": "2.19.0"
+  },
+  "author": "Roku Inc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/rokudev/rsg-sdk.git",
+    "directory": "packages/ads"
+  },
+  "homepage": "https://gitlab.com/rokudev/rsg-sdk/-/tree/main/packages/ads#readme",
+  "bugs": {
+    "url": "https://gitlab.com/rokudev/rsg-sdk/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "coverage": "jest --coverage --runInBand --passWithNoTests --testTimeout=60000 --forceExit",
+    "clean": "rm -rf dist",
+    "lint": "eslint --no-error-on-unmatched-pattern \"src/**/*.{ts,tsx,mjs,cjs,js}\""
+  }
 }