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	9b25f9e	Commit Preview URL Branch Preview URL	Aug 13 2026, 06:48 PM

[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/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>

<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>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/services/previews/v1/cache.ts, line 48:

<comment>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.</comment>

<file context>
@@ -28,9 +41,13 @@ export async function cachedLookup<T>(
+      typeof ttlSeconds === "function" ? ttlSeconds(result.data) : ttlSeconds;
+    if (ttl >= KV_MIN_TTL_SECONDS) {
+      await kv.put(key, JSON.stringify(result.data), {
+        expirationTtl: ttl
+      });
+    }
</file context>

[cubic-dev-ai]

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.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/services/previews/v1/github/artifacts.ts, line 155:

<comment>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.</comment>

<file context>
@@ -61,67 +61,111 @@ function unavailable<T>(
-        };
-      }
+    if (!match) {
+      const all = await listArtifacts(githubToken, undefined);
+      match = matchArtifact(
+        all.filter((artifact) =>
</file context>

[cubic-dev-ai]

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 "".

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/services/previews/v1/routes/commit.ts, line 32:

<comment>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 "".</comment>

<file context>
@@ -17,6 +18,20 @@ const COMMIT_CACHE_TTL_SECONDS = 3600;
+  const remainingSeconds = Math.floor(
+    (new Date(artifact.expires_at).getTime() - Date.now()) / 1000
+  );
+  return Math.min(COMMIT_CACHE_TTL_SECONDS, remainingSeconds);
+}
+
</file context>

[cubic-dev-ai]

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.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/services/previews/v1/routes/commit.ts, line 32:

<comment>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.</comment>

<file context>
@@ -17,6 +18,20 @@ const COMMIT_CACHE_TTL_SECONDS = 3600;
+  const remainingSeconds = Math.floor(
+    (new Date(artifact.expires_at).getTime() - Date.now()) / 1000
+  );
+  return Math.min(COMMIT_CACHE_TTL_SECONDS, remainingSeconds);
+}
+
</file context>