ADS-594 Ads: events resolve their breaks by time window; breaks have no eventId

[georgechoustoulakis]

Important

Do not merge before the OptiView Ads API change (ADS-391) is released to production. The live API still exposes eventId on breaks; these docs describe the post-release behaviour. Kept as a draft until then.

Jira: ADS-594 (docs) · ADS-391 (API change)

TODO before marking ready for review

• ADS-391 released to production
• Regenerate the API reference from the live spec: npm run refresh-ads-api-docs, then commit the result on this branch. The hand-patched api: blobs and rendered schemas below are expected to come out identical for the eventId fields; any extra diff is unrelated spec drift to be reviewed separately.
• Mark ready for review

Summary

The OptiView Ads API stops linking breaks to events by id. An event becomes a pure time window and resolves its breaks from that window; eventId disappears from break requests and responses (an eventId sent in a request is ignored), and a break is no longer validated against an event window. Deleting an event keeps its breaks.

Concept pages (ads/concepts/events.mdx, breaks.mdx, templates.mdx) now document the lookup rule for GET /channels/{channelId}/events/{eventId}/breaks:

• scheduled break → event whose [startDate, endDate) contains its start (wallclock: start; PTS: creation time)
• cued, not yet punched → the event in progress at request time
• event-triggered (pre-roll / pause / post-roll) → listed under every event

The "Deleting an event deletes its breaks" warning becomes "Deleting an event keeps its breaks"; the "Event boundaries are respected" scheduling constraint and the eventId break override are removed.

API reference (ads/api/reference/*.api.mdx): only the break-level eventId property is removed from the create-break request body and from the break response schema on the 7 break/event endpoints that return breaks. Each page carries the endpoint's OpenAPI operation as a compressed api: front-matter string (JSON → zlib → base64, emitted by the Docusaurus OpenAPI plugin); those were decoded, the eventId keys dropped, and re-encoded, and the same fields were removed from the rendered schema. Event path parameters, the template eventIds link and the break-manifest envelope eventId are unchanged. The reference was deliberately not regenerated from the live spec yet: production does not serve the new contract, and a full regeneration would also pull in unrelated drift — see the TODO above.

Validation: npm run lint, npm run check-format pass for the changed files; npm run typecheck only reports the pre-existing missing generated sidebars (gen-api-docs not run locally).

Link to Devin session: https://dolby.devinenterprise.com/sessions/fb0b1cb618a2429d847bb8ad43af0db7
Open in Devin Desktop: https://dolby.devinenterprise.com/desktop/session/fb0b1cb618a2429d847bb8ad43af0db7?variant=devin
Requested by: @georgechoustoulakis

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[theoplayer-bot]

Documentation preview
🚀 View preview at https://docs-preview.optiview.dolby.com/pr-894/
Deployed from commit 2feb316 at 2026-10-02 12:52 UTC.