@adcp/sdk 6.13.2 → 6.15.0

package/skills/build-seller-agent/specialisms/sales-streaming-tv.md

@@ -0,0 +1,45 @@
+# Specialism: sales-streaming-tv
+
+Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-streaming-tv`.
+
+**Status: preview.** The storyboard is a placeholder (`phases: []` in `index.yaml`); claim the specialism to advertise CTV intent. Today only the protocol baseline is enforced — the deltas below are forward-looking guidance so adopters write CTV-shaped responses now and gate-pass when phases land.
+
+**Fork target**: [`examples/hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts) — CTV reservation inventory is guaranteed (impressions + audience). Inherit the IO-task envelope, three `create_media_buy` return shapes, and `targeting_overlay` echo pattern from [`sales-guaranteed.md`](sales-guaranteed.md). Apply the streaming deltas below. See [SHAPE-GOTCHAS.md](../../SHAPE-GOTCHAS.md) for response-shape pitfalls.
+
+## What's different from `sales-guaranteed`
+
+CTV sits between digital and broadcast. The buyer wants impressions and audience guarantees (digital), but the planning surface uses GRP-style reach/freq (broadcast). The differences from `sales-guaranteed` are mostly about which targeting / pricing axes you surface, not new protocol shapes.
+
+## Audience-vs-program targeting
+
+CTV inventory is sold two ways; the seller chooses per product:
+
+- **Audience-bought** — buyer specifies demos / segments via `targeting_overlay.audiences` and `targeting_overlay.signals`. Seller resolves to whichever programs match. Most CTV inventory ships this way.
+- **Program-bought** — buyer specifies titles / shows / genres via `targeting_overlay.contextual` (or a publisher-property list). Seller fulfills against that exact program slate.
+
+Declare which axis a product supports via its `format_ids` and `publisher_properties`. Don't accept program targeting on an audience-bought product — surface `INVALID_REQUEST` with a hint pointing at the supported overlay path. The `targeting_overlay` echo rule from [`sales-guaranteed.md`](sales-guaranteed.md) applies — persist verbatim, echo verbatim.
+
+## Forecast surface — `'reach_freq'` or `'availability'`
+
+CTV planning uses both:
+
+- **`reach_freq`** — unique reach + frequency on a target demo at planned weight. Each `Product.forecast.points[i].metrics` includes `reach_unique`, `frequency_avg`, `grps` (or `irps` for incremental reach), `spend`.
+- **`availability`** — for fully-spec'd reservations (single point, `metrics.impressions` + `metrics.audience_size`, `metrics.spend` is the quoted cost, no `budget`).
+
+Choose per product / per query. Drive from your real demo-projection upstream (Nielsen, VideoAmp, iSpot) — static `availability` blobs read as placeholder during the storyboard.
+
+## Day-of-week + daypart on streaming
+
+Live streaming inventory honors the broadcast `dayparts` enum (`early_morning`, `daytime`, `prime_access`, `prime`, `late_news`, `overnight`). VOD / library inventory typically ignores daypart — surface `INVALID_REQUEST` with a hint if the buyer sends `targeting_overlay.dayparts` against a VOD-only product.
+
+## Measurement windows — same shape as broadcast
+
+CTV billing typically settles on a digital window (`served`) or a panel-blended window (`c3` / `c7` for cross-screen reach). Use the broadcast `measurement_windows` shape from [`sales-broadcast-tv.md`](sales-broadcast-tv.md#measurement-windows--array-of-objects-not-enum-strings) — array of `MeasurementWindow` objects, not enum strings.
+
+## Frequency caps
+
+CTV buyers cap on user-day or user-campaign basis. Surface via `Product.frequency_capping_options` and accept on `packages[].frequency_caps`. Sellers that can't enforce a requested cap should reject with `INVALID_REQUEST` rather than silently dropping the cap.
+
+## Cross-screen attribution
+
+Cross-screen attribution (CTV → mobile / web) lands in AdCP 3.1 alongside the closed-loop attribution surface — out of scope for the 3.0 baseline. Sellers can attach `measurement_partners` to a product and let the buyer subscribe to the feed out-of-band.

package/skills/build-seller-agent/specialisms/signed-requests.md

@@ -23,15 +23,22 @@ The `WWW-Authenticate` header is the grading surface — return the right error
 
 **Use the SDK's server verifier.** Don't write signature parsing or canonicalization yourself — `@adcp/sdk/signing/server` ships the full pipeline. The canonical wiring lives in [§ Composing OAuth, signing, and idempotency](#composing-oauth-signing-and-idempotency) which feeds `verifyRequestSignature` through `serve({ preTransport })`; don't hand-roll an Express middleware chain alongside it. What you need that's specific to this specialism is the capability advertisement and the revocation-store pre-state:
 
-**Auto-wiring via `createAdcpServer`.** When you're already using `createAdcpServer`, pass `signedRequests: { jwks, replayStore, revocationStore }` and add `'signed-requests'` to `capabilities.specialisms` — the framework builds the verifier preTransport for you and `serve()` auto-mounts it. `createAdcpServer` throws at startup when `signedRequests` is set without the specialism claim (buyers wouldn't sign), and logs a loud error in the other direction (leaving the legacy manual `serve({ preTransport })` path working). Keep `request_signing` in capabilities separately — it's still how buyers discover your `required_for` policy.
+**Auto-wiring via `createAdcpServerFromPlatform`.** Pass `signedRequests: { jwks, replayStore, revocationStore }` alongside your platform and add `'signed-requests'` to `capabilities.specialisms` — the framework builds the verifier preTransport for you and `serve()` auto-mounts it. `createAdcpServerFromPlatform` throws at startup when `signedRequests` is set without the specialism claim (buyers wouldn't sign), and logs a loud error in the other direction. Keep `request_signing` in capabilities separately — it's still how buyers discover your `required_for` policy.
 
 ```typescript
-createAdcpServer({
-  // ...handlers...
+const platform = definePlatform({
   capabilities: {
+    specialisms: ['signed-requests', 'sales-non-guaranteed'] as const,
     request_signing: capability,
-    specialisms: ['signed-requests'],
+    pricingModels: ['cpm'] as const,
   },
+  accounts: { resolve: async (ref, ctx) => /* ... */ null },
+  sales: defineSalesCorePlatform({ /* handlers */ }),
+});
+
+createAdcpServerFromPlatform(platform, {
+  name: 'My Seller',
+  version: '1.0.0',
   signedRequests: {
     jwks,
     replayStore,

package/skills/build-signals-agent/SKILL.md

@@ -9,25 +9,14 @@ A signals agent serves audience and contextual targeting segments to buyer agent
 
 ## Pick your fork target
 
-| Specialism | Archetype | Fork this | Mock upstream | Storyboard |
-| --- | --- | --- | --- | --- |
-| `signal-marketplace` | Multi-provider data marketplace (Oracle Data Cloud, LiveRamp, third-party data) | [`hello_signals_adapter_marketplace.ts`](../../examples/hello_signals_adapter_marketplace.ts) | `npx adcp mock-server signal-marketplace` | `signal_marketplace` |
-| `signal-owned` | First-party / single-provider data (CDP, identity provider, contextual) | Fork the marketplace adapter; see [deletion list below](#what-to-delete-if-youre-single-specialism-signal-owned) | — | `signal_owned` |
+| Specialism           | Archetype                                                                       | Fork this                                                                                            | Mock upstream                             | Storyboard           |
+| -------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------- |
+| `signal-marketplace` | Multi-provider data marketplace (Oracle Data Cloud, LiveRamp, third-party data) | [`hello_signals_adapter_marketplace.ts`](../../examples/hello_signals_adapter_marketplace.ts)        | `npx adcp mock-server signal-marketplace` | `signal_marketplace` |
+| `signal-owned`       | First-party / single-provider data (CDP, identity provider, contextual)         | Same — fork the marketplace adapter and apply the [single-provider deltas below](#specialism-deltas) | Same                                      | `signal_owned`       |
 
-Both specialisms share the same tool surface (`get_signals`, `activate_signal`, `list_accounts`); the difference is whether you serve segments from multiple `data_provider_domain` values or one. A `signal-owned` adapter is the marketplace adapter with the multi-provider directory simplified to a single seed.
+Both specialisms share the same tool surface (`get_signals`, `activate_signal`, `list_accounts`); the difference is whether you serve segments from multiple `data_provider_domain` values or one.
 
-### What to delete if you're single-specialism `signal-owned`
-
-**Forking the marketplace adapter for a `signal-owned` agent? Delete or replace these seams** — leaning on stable symbol names rather than line numbers (the adapter evolves; greppable identifiers don't):
-
-- Replace the multi-provider seed (the `UpstreamCohort` array seeded with multiple `data_provider_domain` / `data_provider_id` / `data_provider_name` triples) with your single-provider catalog. Every cohort gets the same `data_provider_domain` (your domain) and `data_provider_name` (your brand).
-- Strip the marketplace-discovery code paths in `getSignals` that filter `signals[]` by `(data_provider_domain, data_provider_id)` pairs — single-provider adopters either return everything or filter on signal id alone.
-- Set `signal_type: 'owned'` (not `'marketplace'`) in the `toAdcpSignal` projection. See [SHAPE-GOTCHAS §7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom) for the `marketplace`/`owned`/`custom` decision table.
-- Drop the marketplace governance sub-scenario in your storyboard run if you don't model multi-provider consent flows — `signal_owned` storyboard is simpler.
-
-**Keep**: the `accounts` / `createTenantStore` block (single-tenant adapters pass one tenant entry), `agentRegistry`, the `signals` SignalsPlatform block (`getSignals`, `activateSignal`, `listAccounts`), platform vs agent activation polling logic, `forceDeploymentStatus` for compliance-test determinism.
-
-For exact response shapes, error codes, and optional fields, `docs/llms.txt` is the canonical reference. The fork target stays in sync with the spec because PR #1394's three-gate contract fails CI when it drifts.
+For exact response shapes, error codes, and optional fields, [`docs/llms.txt`](../../docs/llms.txt) is the canonical reference. The fork target stays in sync with the spec because PR #1394's three-gate contract fails CI when it drifts. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) — particularly [§1](../SHAPE-GOTCHAS.md#1-activationkey-oneof--keyvalue-are-top-level-not-nested) (flat `activation_key.key/value`), [§2](../SHAPE-GOTCHAS.md#2-signal_ids-is-signal_id-provenance-objects-not-string) (`signal_ids` is `SignalID[]`, not `string[]`), and [§7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom) (`marketplace` / `owned` / `custom` decision).
 
 ## When to use this skill
 
@@ -61,11 +50,23 @@ Platform activations (`type: 'platform'`) take minutes-to-hours to propagate to
 
 Buyers fetch `https://{domain}/adagents.json` out-of-band to verify the provider. Use real domains even in demos, not `example.com`. For marketplace adopters, seed ≥2 different `data_provider_domain` values so the multi-provider nature is visible to the storyboard.
 
-## Specialism deltas at a glance
+## Specialism deltas
+
+### `signal-marketplace` (the baseline fork target)
+
+Multi-provider directory: `signals[].data_provider_domain` varies across cohorts. Platform-activation polling pattern is fully exercised. The marketplace governance sub-scenario in the storyboard exercises consent flows across providers; if you can't model multi-provider consent yet, surface `INVALID_REQUEST` rather than silently fall through. Use `signal_type: 'marketplace'` only when `data_provider_domain` resolves to a real `adagents.json`.
+
+### `signal-owned` (single-provider)
+
+Forking the marketplace adapter for a `signal-owned` agent? Apply these deltas — leaning on stable symbol names rather than line numbers (the adapter evolves; greppable identifiers don't):
 
-**`signal-marketplace`** — multi-provider directory (`signals[].data_provider_domain` varies), platform-activation polling pattern, marketplace governance sub-scenario in the storyboard exercises consent flows.
+- **Replace the multi-provider seed.** The adapter ships an `UpstreamCohort` array seeded with multiple `data_provider_domain` / `data_provider_id` / `data_provider_name` triples. Replace with your single-provider catalog: every cohort gets the same `data_provider_domain` (your domain) and `data_provider_name` (your brand).
+- **Strip marketplace-discovery filters in `getSignals`** that filter `signals[]` by `(data_provider_domain, data_provider_id)` pairs — single-provider adopters either return everything or filter on signal id alone.
+- **Set `signal_type: 'owned'`** (not `'marketplace'`) in the `toAdcpSignal` projection. See [SHAPE-GOTCHAS §7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom) for the decision table — `owned` is the default for first-party data agents.
+- **Drop the marketplace governance sub-scenario** from your storyboard run if you don't model multi-provider consent flows. The `signal_owned` storyboard is simpler.
+- **`value_type` drives targeting semantics** for owned segments: `binary` (in/out), `categorical` (with `allowed_values: [...]`), `numeric` (with `min`, `max`, optional `units`).
 
-**`signal-owned`** — single `data_provider_domain` across all signals. `value_type` drives targeting semantics: `binary` (in/out), `categorical` (with `allowed_values: [...]`), `numeric` (with `min`, `max`, optional `units`). For the `signal_type` value (`marketplace`/`owned`/`custom`) decision, see [SHAPE-GOTCHAS §7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom).
+**Keep**: the `accounts` / `createTenantStore` block (single-tenant adapters pass one tenant entry), `agentRegistry`, the `signals` `SignalsPlatform` block (`getSignals`, `activateSignal`, `listAccounts`), platform-vs-agent activation polling logic, `forceDeploymentStatus` for compliance-test determinism.
 
 ## Validate locally