Add previews/v1 service for preview build lookup

[admdly]

What

Adds previews/v1 — a read-only lookup service for FOSSBilling preview builds (current main, a PR's current head, or one exact commit), plus a small unrelated typecheck fix found along the way.

GET /previews/v1/main               GET /previews/v1/main/download
GET /previews/v1/pr/{number}        GET /previews/v1/pr/{number}/download
GET /previews/v1/commit/{sha}       GET /previews/v1/commit/{sha}/download

OpenAPI docs at /previews/v1/openapi.json and /previews/v1/docs.

Design

• GitHub Actions is the source of truth for pr/commit — FOSSBilling/FOSSBilling's ci.yml (see FOSSBilling/FOSSBilling#4157) uploads one artifact per commit, named FOSSBilling-preview-{short_sha}.zip (archive: false, so the zip itself is the artifact). This service resolves by querying that exact name rather than listing every preview artifact and filtering.
• main is R2-backed for download_url/digest — sourced from digest/commit-sha custom object metadata the same CI job sets on the R2 upload. Kept separate from the GitHub-artifact path because the R2 zip and the GitHub artifact zip for a given commit are two independently-built files, so whichever one is reported as the digest has to match the bytes actually served. main additionally cross-references that commit's GitHub Actions artifact to populate run_id/artifact_id/created_at/expires_at, purely as best-effort enrichment — never a dependency; a GitHub hiccup never fails /main, those fields just come back null.
• No publish/write endpoint — nothing pushes data into this service, it only resolves and redirects.
• Pointers vs fixed points — main and pr/{number} always resolve to whatever's current; commit/{sha} is permanently addressable to one exact build. pr/{number} resolves the PR to its head SHA and delegates to the same resolver commit/{sha} uses.
• GitHub API call budget — /download routes share the same cached lookup the metadata routes use (only the final signed-redirect resolution is ever live, since it expires in ~60s and can't be cached — Cloudflare KV enforces a hard 60s minimum TTL, leaving no safe margin). commit/{sha} caches for 3600s rather than the 60s default, since a commit's build never changes once it exists.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	api	c4434b4	Commit Preview URL Branch Preview URL	Aug 15 2026, 07:47 AM

[cubic-dev-ai]

All reported issues were addressed across 22 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

4 issues found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/services/previews/v1/github/artifacts.ts">

<violation number="1" location="src/services/previews/v1/github/artifacts.ts:155">
P2: The new fork-PR fallback only scans a single page of the artifacts API (`per_page: 100`, no pagination), so it never looks past the 100 most recent artifacts in the repo. For an active repo whose retention window holds more than 100 preview artifacts, valid fork-PR builds older than the newest ~100 produce a false NOT_FOUND — exactly the case this fallback was added to fix. Paginate through the artifact list (following the link header or “next” pages) until a match is found or pages are exhausted, and stop as soon as `matchArtifact` returns a result.</violation>
</file>

<file name="src/services/previews/v1/routes/commit.ts">

<violation number="1" location="src/services/previews/v1/routes/commit.ts:32">
P3: When an artifact expires within the next hour, this callback returns less than 3600 seconds, and the final minute is uncached. Update the caching documentation to describe this retention cap and final-minute behavior.</violation>

<violation number="2" location="src/services/previews/v1/routes/commit.ts:32">
P2: When `artifact.expires_at` is an empty string or otherwise unparseable, `new Date(expires_at).getTime()` returns `NaN`, so `remainingSeconds` and `Math.min(...)` are `NaN`. `NaN >= KV_MIN_TTL_SECONDS` is `false`, so in cache.ts the commit result is never cached and the lookup silently performs 2 GitHub API calls on every request instead of the intended 3600s caching. This is reachable in practice because `toPreviewArtifact` (github/artifacts.ts) fills `expiresAt` from `artifact.expires_at ?? ""`, so a null GitHub `expires_at` lands here as "".</violation>
</file>

<file name="src/services/previews/v1/cache.ts">

<violation number="1" location="src/services/previews/v1/cache.ts:48">
P2: When an artifact has only 60.x seconds of retention left, this writes a full 60-second KV TTL calculated before the write completes. Recompute against an absolute expiration or skip near-floor TTLs with a write-time safety margin so `/commit/{sha}` cannot remain cached after the artifact expires.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Requires human review: Adds a new public API service with R2 bucket binding, cache TTL tradeoffs, and GitHub API usage; a human should sign off on the operational and infrastructure decisions.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Requires human review: New public previews/v1 service adds production endpoints, an R2 bucket binding, and reliance on GitHub Actions artifact naming — a product/architectural and operational change that needs human sign-off.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 5 files (changes from recent commits).

<sub>Requires human review: Adds a public API with R2 config and a contract; core resolution logic is truncated and fallback paging cannot be verified, so a human must sign off on the new contract, caching/R2 bindings, and the unverified logic.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: New public-facing service adds endpoints, an R2 bucket binding, and operational/caching tradeoffs (TTLs, GitHub API budget) that need human review.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: New service adds public API endpoints and integrates GitHub Actions, R2, and KV with nontrivial caching/expiry tradeoffs; operational and architectural decisions need human sign-off.

Re-trigger cubic</sub>