feat(files): close the endpoint coverage gap - #175
Conversation
There was a problem hiding this comment.
Pull request overview
This PR closes the remaining supported-public endpoint gap identified in the private backend-to-SDK audit by adding first-class support for the XSPF playlist direct route (used for VLC handoff) to the canonical files domain surface, and it documents a public-safe endpoint-completeness evidence boundary/refresh contract.
Changes:
- Add
files.getXspfPlaylistUrl(...)(Effect + Promise clients), along withbuildFileXspfPlaylistUrl(...)and a typed options object with token override validation. - Extend the canonical operation tree + export surface assertions/snapshots to include the new operation.
- Add/extend coverage: domain/unit tests, packed consumer compat probe, route matrix, and a safe live test that fetches the XSPF playlist for an owned video; introduce
docs/API-COVERAGE.mdand align docs/README wording.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| test/live/domains/file-direct.ts | Adds live proof that the generated XSPF URL is fetchable and returns expected content type/body. |
| src/index.spec.ts | Extends root export surface test to include getXspfPlaylistUrl. |
| src/domains/files.ts | Introduces XSPF URL builder + Effect operation with schema validation and token resolution. |
| src/domains/files.spec.ts | Adds unit coverage for the builder and Effect operation output + validation failures. |
| src/core/client.ts | Wires the new operation into the shared operation tree. |
| src/core/client.spec.ts | Asserts the client exposes and resolves files.getXspfPlaylistUrl. |
| src/core/client.promise.spec.ts | Mocks and verifies the Promise adapter forwards the new operation. |
| src/snapshots/index.spec.ts.snap | Updates public surface snapshot to include the new exports. |
| scripts/test-compat-node.ts | Adds packed Node consumer check ensuring Promise token replacement reaches the XSPF URL helper. |
| README.md | Documents the new helper and adds a new “Endpoint Coverage” section pointing to API coverage docs. |
| docs/TESTING.md | Updates live target matrix to include XSPF under file-direct. |
| docs/ARCHITECTURE.md | Documents files.getXspfPlaylistUrl(...) as part of the direct-route helpers. |
| docs/api-route-matrix.json | Adds an explicit route-matrix decision entry for /v2/files/:fileId/xspf. |
| docs/API-COVERAGE.md | Adds public-safe endpoint completeness scope, audit outcome, evidence boundary, and refresh contract. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed
You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
## [11.2.0](v11.1.2...v11.2.0) (2026-08-11) ### Features * **files:** close the endpoint coverage gap ([#175](#175)) ([71858bf](71858bf))
|
🎉 This PR is included in version 11.2.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
Summary
A current private backend-to-SDK comparison found one unresolved supported public capability: the XSPF playlist route still used for first-party VLC handoff. This PR exposes it through the canonical SDK surface and records an accurate point-in-time endpoint-completeness contract without publishing the backend inventory.
Closes #172.
Changed
files.getXspfPlaylistUrl(...)to both Effect and Promise clients, plus the public URL builder and option type.docs/API-COVERAGE.mdwith the completeness scope, exclusions, evidence boundary, audit outcome, and refresh contract.Review aids
flowchart LR A["Private backend + consumer audit"] --> B{"Supported public gap?"} B -->|"XSPF"| C["files.getXspfPlaylistUrl"] B -->|"Alias, browser, or private"| H["Explicit coverage exclusions"] C --> D["Canonical operation tree"] D --> E["Effect client"] D --> F["Promise client"] C --> G["Unit + packed + live proof"]The public route matrix gains only the XSPF decision. The complete backend inventory and classifications remain private.
Risks
Verification
node_modules/.bin/vp run verify— passed; 24 files / 143 tests, 98.09% statements, 100% functions, 26 public route decisions with zero awaiting dispositionnode_modules/.bin/vp run lint:package— passed; Publint and ATTW ESM-only profilenode_modules/.bin/vp run test:compat— passed; packed strict Node consumer plus Chromium, Firefox, WebKit, and Bunsops exec-env --same-process <redacted-sdk-ciphertext> 'pnpm test:live:fresh -- test/live/file-direct.test.ts'— passed; 1 file / 7 tests including the real XSPF fetchautoreview review --mode branch --base origin/main --engine cursor --model cursor-grok-4.5-high-fast --output json --prompt-file -— clean; no findingsComplexity
Low to medium. The runtime addition follows the existing direct-route helper pattern; most of the change is contract proof and durable coverage documentation.
Summary by cubic
Exposes the XSPF playlist endpoint via
files.getXspfPlaylistUrl(...)and a public URL builder to support VLC handoff. This closes the last supported public endpoint gap and documents current API coverage (closes #172).files.getXspfPlaylistUrl(...)to Effect and Promise clients, plusbuildFileXspfPlaylistUrl(...).docs/api-route-matrix.json; add unit, compat (Node token replacement), and live tests for the XSPF route; align Promise adapter fixture with the XSPF URL.docs/API-COVERAGE.md, link from README, and clarify scope/exclusions/evidence; align architecture/testing docs; use query-stringoauth_tokenlike other direct URL helpers.Written for commit 8689c62. Summary will update on new commits.