@vellumai/cli 0.7.0 → 0.7.2

package/src/lib/__tests__/local-runtime-client.test.ts

@@ -1,8 +1,10 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import type { AssistantEntry } from "../assistant-config.js";
 import {
   MigrationInProgressError,
   localRuntimeExportToGcs,
+  localRuntimeIdentity,
   localRuntimeImportFromGcs,
   localRuntimePollJobStatus,
 } from "../local-runtime-client.js";
@@ -10,6 +12,17 @@ import {
 const RUNTIME_URL = "http://127.0.0.1:8765";
 const TOKEN = "local-bearer-token";
 
+// All tests in this file exercise the local/docker code path (cloud="local"),
+// which builds `{runtimeUrl}/v1/migrations/<subpath>` URLs and uses
+// guardian-token bearer auth. The platform path (cloud="vellum") is covered
+// by `runtime-url.test.ts` (URL construction) and the teleport tests
+// (call-site wiring).
+const ENTRY: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId"> = {
+  cloud: "local",
+  runtimeUrl: RUNTIME_URL,
+  assistantId: "ast-test-1",
+};
+
 interface CapturedCall {
   url: string;
   method: string;
@@ -82,7 +95,7 @@ describe("localRuntimeExportToGcs", () => {
     });
     globalThis.fetch = fetchMock;
 
-    const result = await localRuntimeExportToGcs(RUNTIME_URL, TOKEN, {
+    const result = await localRuntimeExportToGcs(ENTRY, TOKEN, {
       uploadUrl: "https://storage.example/signed/abc",
       description: "teleport export",
     });
@@ -108,7 +121,7 @@ describe("localRuntimeExportToGcs", () => {
     });
     globalThis.fetch = fetchMock;
 
-    await localRuntimeExportToGcs(RUNTIME_URL, TOKEN, {
+    await localRuntimeExportToGcs(ENTRY, TOKEN, {
       uploadUrl: "https://storage.example/signed/abc",
     });
 
@@ -132,7 +145,7 @@ describe("localRuntimeExportToGcs", () => {
     globalThis.fetch = fetchMock;
 
     try {
-      await localRuntimeExportToGcs(RUNTIME_URL, TOKEN, {
+      await localRuntimeExportToGcs(ENTRY, TOKEN, {
         uploadUrl: "https://storage.example/signed/abc",
       });
       throw new Error("expected to throw");
@@ -156,7 +169,7 @@ describe("localRuntimeExportToGcs", () => {
     globalThis.fetch = fetchMock;
 
     try {
-      await localRuntimeExportToGcs(RUNTIME_URL, TOKEN, {
+      await localRuntimeExportToGcs(ENTRY, TOKEN, {
         uploadUrl: "https://storage.example/signed/abc",
       });
       throw new Error("expected to throw");
@@ -182,7 +195,7 @@ describe("localRuntimeExportToGcs", () => {
     globalThis.fetch = fetchMock;
 
     try {
-      await localRuntimeExportToGcs(RUNTIME_URL, TOKEN, {
+      await localRuntimeExportToGcs(ENTRY, TOKEN, {
         uploadUrl: "https://storage.example/signed/abc",
       });
       throw new Error("expected to throw");
@@ -201,7 +214,7 @@ describe("localRuntimeExportToGcs", () => {
     globalThis.fetch = fetchMock;
 
     await expect(
-      localRuntimeExportToGcs(RUNTIME_URL, TOKEN, {
+      localRuntimeExportToGcs(ENTRY, TOKEN, {
         uploadUrl: "https://storage.example/signed/abc",
       }),
     ).rejects.toThrow(/500/);
@@ -222,7 +235,7 @@ describe("localRuntimeImportFromGcs", () => {
     });
     globalThis.fetch = fetchMock;
 
-    const result = await localRuntimeImportFromGcs(RUNTIME_URL, TOKEN, {
+    const result = await localRuntimeImportFromGcs(ENTRY, TOKEN, {
       bundleUrl: "https://storage.example/signed/dl-xyz",
     });
 
@@ -250,7 +263,7 @@ describe("localRuntimeImportFromGcs", () => {
     globalThis.fetch = fetchMock;
 
     try {
-      await localRuntimeImportFromGcs(RUNTIME_URL, TOKEN, {
+      await localRuntimeImportFromGcs(ENTRY, TOKEN, {
         bundleUrl: "https://storage.example/signed/dl-xyz",
       });
       throw new Error("expected to throw");
@@ -275,7 +288,7 @@ describe("localRuntimeImportFromGcs", () => {
     globalThis.fetch = fetchMock;
 
     try {
-      await localRuntimeImportFromGcs(RUNTIME_URL, TOKEN, {
+      await localRuntimeImportFromGcs(ENTRY, TOKEN, {
         bundleUrl: "https://storage.example/signed/dl-xyz",
       });
       throw new Error("expected to throw");
@@ -302,11 +315,7 @@ describe("localRuntimePollJobStatus", () => {
     });
     globalThis.fetch = fetchMock;
 
-    const status = await localRuntimePollJobStatus(
-      RUNTIME_URL,
-      TOKEN,
-      "poll-1",
-    );
+    const status = await localRuntimePollJobStatus(ENTRY, TOKEN, "poll-1");
 
     expect(status).toEqual({
       jobId: "poll-1",
@@ -332,11 +341,7 @@ describe("localRuntimePollJobStatus", () => {
     });
     globalThis.fetch = fetchMock;
 
-    const status = await localRuntimePollJobStatus(
-      RUNTIME_URL,
-      TOKEN,
-      "poll-2",
-    );
+    const status = await localRuntimePollJobStatus(ENTRY, TOKEN, "poll-2");
 
     expect(status.status).toBe("complete");
     if (status.status === "complete") {
@@ -358,11 +363,7 @@ describe("localRuntimePollJobStatus", () => {
     });
     globalThis.fetch = fetchMock;
 
-    const status = await localRuntimePollJobStatus(
-      RUNTIME_URL,
-      TOKEN,
-      "poll-3",
-    );
+    const status = await localRuntimePollJobStatus(ENTRY, TOKEN, "poll-3");
 
     expect(status.status).toBe("failed");
     if (status.status === "failed") {
@@ -377,7 +378,289 @@ describe("localRuntimePollJobStatus", () => {
     globalThis.fetch = fetchMock;
 
     await expect(
-      localRuntimePollJobStatus(RUNTIME_URL, TOKEN, "missing"),
+      localRuntimePollJobStatus(ENTRY, TOKEN, "missing"),
     ).rejects.toThrow(/Migration job not found/);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Platform-managed assistants (cloud="vellum") route through the platform's
+// wildcard runtime proxy at `/v1/assistants/<id>/migrations/...` with
+// platform-token auth (NOT guardian-token bearer). This block asserts the
+// actual URL and headers built by the helpers — not mocked, not abstracted.
+// Regression guard for the routing bug fixed in this PR.
+// ---------------------------------------------------------------------------
+const VELLUM_ENTRY: Pick<
+  AssistantEntry,
+  "cloud" | "runtimeUrl" | "assistantId"
+> = {
+  cloud: "vellum",
+  runtimeUrl: "https://platform.vellum.ai",
+  assistantId: "11111111-2222-3333-4444-555555555555",
+};
+// `vak_` prefix bypasses `fetchOrganizationId` (org-scoped API keys); the
+// auth header collapses to a single `Authorization: Bearer vak_...` so this
+// test stays free of network mocks.
+const VAK_TOKEN = "vak_platform-token";
+
+describe("vellum-cloud routing through wildcard proxy", () => {
+  test("export-to-gcs URL has /v1/assistants/<id>/migrations/ prefix and uses platform-token bearer (no guardian)", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({ job_id: "wp-export-1", status: "pending" }),
+        { status: 202, headers: { "Content-Type": "application/json" } },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    const result = await localRuntimeExportToGcs(VELLUM_ENTRY, VAK_TOKEN, {
+      uploadUrl: "https://storage.example/signed/x",
+      description: "teleport export",
+    });
+
+    expect(result.jobId).toBe("wp-export-1");
+    expect(calls[0]!.url).toBe(
+      `https://platform.vellum.ai/v1/assistants/11111111-2222-3333-4444-555555555555/migrations/export-to-gcs`,
+    );
+    expect(calls[0]!.method).toBe("POST");
+    expect(calls[0]!.headers.Authorization).toBe(`Bearer ${VAK_TOKEN}`);
+    expect(calls[0]!.body).toEqual({
+      upload_url: "https://storage.example/signed/x",
+      description: "teleport export",
+    });
+  });
+
+  test("import-from-gcs URL has /v1/assistants/<id>/migrations/ prefix", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({ job_id: "wp-import-1", status: "pending" }),
+        { status: 202 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    await localRuntimeImportFromGcs(VELLUM_ENTRY, VAK_TOKEN, {
+      bundleUrl: "https://storage.example/download/y",
+    });
+
+    expect(calls[0]!.url).toBe(
+      `https://platform.vellum.ai/v1/assistants/11111111-2222-3333-4444-555555555555/migrations/import-from-gcs`,
+    );
+    expect(calls[0]!.headers.Authorization).toBe(`Bearer ${VAK_TOKEN}`);
+  });
+
+  test("jobs/<id> URL has /v1/assistants/<id>/migrations/ prefix (NOT the dedicated platform endpoint)", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          job_id: "wp-export-1",
+          status: "complete",
+          type: "export",
+          bundle_key: "exports/org-1/x.vbundle",
+        }),
+        { status: 200 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    const status = await localRuntimePollJobStatus(
+      VELLUM_ENTRY,
+      VAK_TOKEN,
+      "wp-export-1",
+    );
+
+    expect(calls[0]!.url).toBe(
+      `https://platform.vellum.ai/v1/assistants/11111111-2222-3333-4444-555555555555/migrations/jobs/wp-export-1`,
+    );
+    expect(calls[0]!.headers.Authorization).toBe(`Bearer ${VAK_TOKEN}`);
+    expect(status.status).toBe("complete");
+    if (status.status === "complete") {
+      expect(status.bundleKey).toBe("exports/org-1/x.vbundle");
+    }
+  });
+});
+
+describe("localRuntimeIdentity", () => {
+  test("local entry: GETs /v1/health with Bearer auth and returns the version", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          status: "healthy",
+          timestamp: "2025-01-01T00:00:00Z",
+          version: "0.6.5",
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    const result = await localRuntimeIdentity(ENTRY, TOKEN);
+
+    expect(result.version).toBe("0.6.5");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe(`${RUNTIME_URL}/v1/health`);
+    expect(calls[0]!.method).toBe("GET");
+    expect(calls[0]!.headers.Authorization).toBe(`Bearer ${TOKEN}`);
+  });
+
+  test("GETs /v1/health, not /v1/identity (works on pre-onboarding runtimes)", async () => {
+    // Regression guard: /v1/identity reads IDENTITY.md (written during
+    // onboarding, NOT hatch) and 404s on freshly-hatched targets. /v1/health
+    // returns the version field unconditionally, so it's the right source.
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(JSON.stringify({ version: "0.7.0" }), {
+        status: 200,
+      });
+    });
+    globalThis.fetch = fetchMock;
+
+    await localRuntimeIdentity(ENTRY, TOKEN);
+
+    expect(calls[0]!.url.endsWith("/v1/health")).toBe(true);
+    expect(calls[0]!.url).not.toContain("/v1/identity");
+  });
+
+  test("vellum entry: GETs /v1/assistants/<id>/health through the wildcard proxy", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(JSON.stringify({ version: "0.7.2" }), {
+        status: 200,
+      });
+    });
+    globalThis.fetch = fetchMock;
+
+    const result = await localRuntimeIdentity(VELLUM_ENTRY, VAK_TOKEN);
+
+    expect(result.version).toBe("0.7.2");
+    expect(calls[0]!.url).toBe(
+      `https://platform.vellum.ai/v1/assistants/11111111-2222-3333-4444-555555555555/health`,
+    );
+    expect(calls[0]!.headers.Authorization).toBe(`Bearer ${VAK_TOKEN}`);
+  });
+
+  test("non-2xx status throws with status + statusText", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response("nope", {
+        status: 503,
+        statusText: "Service Unavailable",
+      });
+    });
+    globalThis.fetch = fetchMock;
+
+    await expect(localRuntimeIdentity(ENTRY, TOKEN)).rejects.toThrow(
+      /Failed to fetch runtime identity: 503/,
+    );
+  });
+
+  test("missing version in body throws", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response(JSON.stringify({}), { status: 200 });
+    });
+    globalThis.fetch = fetchMock;
+
+    await expect(localRuntimeIdentity(ENTRY, TOKEN)).rejects.toThrow(
+      /Runtime identity response missing version/,
+    );
+  });
+
+  test("non-string version in body throws", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response(JSON.stringify({ version: 123 }), { status: 200 });
+    });
+    globalThis.fetch = fetchMock;
+
+    await expect(localRuntimeIdentity(ENTRY, TOKEN)).rejects.toThrow(
+      /Runtime identity response missing version/,
+    );
+  });
+
+  test("empty-string version in body throws", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response(JSON.stringify({ version: "" }), { status: 200 });
+    });
+    globalThis.fetch = fetchMock;
+
+    await expect(localRuntimeIdentity(ENTRY, TOKEN)).rejects.toThrow(
+      /Runtime identity response missing version/,
+    );
+  });
+
+  // ---------------------------------------------------------------------
+  // 401-retry parity with platformRequestSignedUrl (Codex P2 regression
+  // guard). localRuntimeIdentity is the first network call in the
+  // backup/teleport export flow for vellum-cloud assistants, so a stale
+  // Vellum-Organization-Id cache entry would surface as a hard abort
+  // before any other helper got a chance to clear the cache and retry.
+  // ---------------------------------------------------------------------
+
+  test("vellum entry: retries once after 401 with a fresh org-ID lookup", async () => {
+    // Use a non-vak session token so authHeaders fetches + caches an org ID.
+    const SESSION_TOKEN = "session-abcdef";
+    const PLATFORM_URL = "https://platform.vellum.ai";
+    const ASSISTANT_ID = "11111111-2222-3333-4444-555555555555";
+
+    let healthCalls = 0;
+    const orgIdFetchedAs: string[] = [];
+
+    const fetchMock = mock(async (url: string | URL | Request) => {
+      const urlStr = typeof url === "string" ? url : url.toString();
+      if (urlStr.endsWith("/v1/organizations/")) {
+        // Each org-ID fetch returns a different ID to prove that the
+        // second health request DID re-resolve the org rather than
+        // reuse a stale cache entry.
+        orgIdFetchedAs.push(`org-${orgIdFetchedAs.length + 1}`);
+        return new Response(
+          JSON.stringify({
+            results: [{ id: orgIdFetchedAs[orgIdFetchedAs.length - 1]! }],
+          }),
+          { status: 200 },
+        );
+      }
+      if (urlStr.endsWith(`/v1/assistants/${ASSISTANT_ID}/health`)) {
+        healthCalls += 1;
+        if (healthCalls === 1) {
+          return new Response("unauthorized", { status: 401 });
+        }
+        return new Response(JSON.stringify({ version: "0.7.4" }), {
+          status: 200,
+        });
+      }
+      return new Response("unexpected", { status: 500 });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const result = await localRuntimeIdentity(
+      {
+        cloud: "vellum",
+        runtimeUrl: PLATFORM_URL,
+        assistantId: ASSISTANT_ID,
+      },
+      SESSION_TOKEN,
+    );
+
+    expect(result.version).toBe("0.7.4");
+    expect(healthCalls).toBe(2);
+    // Two org-ID fetches: the first to satisfy the initial authHeaders
+    // call, the second after the 401-driven cache invalidation.
+    expect(orgIdFetchedAs).toEqual(["org-1", "org-2"]);
+  });
+
+  test("local entry: does NOT retry after 401 (guardian-token refresh is the caller's job via callRuntimeWithAuthRetry)", async () => {
+    let identityCalls = 0;
+    const fetchMock = mock(async () => {
+      identityCalls += 1;
+      return new Response("unauthorized", {
+        status: 401,
+        statusText: "Unauthorized",
+      });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    await expect(localRuntimeIdentity(ENTRY, TOKEN)).rejects.toThrow(
+      /Failed to fetch runtime identity: 401/,
+    );
+    expect(identityCalls).toBe(1);
+  });
+});

package/src/lib/__tests__/platform-client-signed-url.test.ts

@@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import {
   platformPollJobStatus,
   platformRequestSignedUrl,
+  VersionMismatchError,
   type UnifiedJobStatus,
 } from "../platform-client.js";
 
@@ -291,7 +292,241 @@ describe("platformRequestSignedUrl", () => {
     expect(signedUrlCalls[0]!.headers.Authorization).toBeUndefined();
   });
 
-  test("503 → throws so callers can fall back to legacy inline upload", async () => {
+  test("upload operation with min/max runtime versions → posts them in body", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          url: "https://storage.example/signed/v",
+          bundle_key: "bundles/v.tar.gz",
+          expires_at: "2026-04-22T05:00:00Z",
+        }),
+        { status: 201 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    await platformRequestSignedUrl(
+      {
+        operation: "upload",
+        minRuntimeVersion: "1.2.3",
+        maxRuntimeVersion: null,
+      },
+      VAK_TOKEN,
+      PLATFORM_URL,
+    );
+
+    expect(calls[0]!.body).toEqual({
+      operation: "upload",
+      min_runtime_version: "1.2.3",
+      max_runtime_version: null,
+    });
+  });
+
+  test("download operation with target_runtime_version → posts it in body", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          url: "https://storage.example/signed/dl-v",
+          bundle_key: "bundles/dl-v.tar.gz",
+          expires_at: "2026-04-22T06:00:00Z",
+        }),
+        { status: 201 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    await platformRequestSignedUrl(
+      {
+        operation: "download",
+        bundleKey: "bundles/dl-v.tar.gz",
+        targetRuntimeVersion: "2.0.0",
+      },
+      VAK_TOKEN,
+      PLATFORM_URL,
+    );
+
+    expect(calls[0]!.body).toEqual({
+      operation: "download",
+      bundle_key: "bundles/dl-v.tar.gz",
+      target_runtime_version: "2.0.0",
+    });
+  });
+
+  test("download 422 with version_mismatch body → throws VersionMismatchError", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          reason: "version_mismatch",
+          bundle_compat: {
+            min_runtime_version: "2.0.0",
+            max_runtime_version: "2.5.0",
+          },
+          target_runtime_version: "1.9.0",
+        }),
+        { status: 422 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    let caught: unknown;
+    try {
+      await platformRequestSignedUrl(
+        {
+          operation: "download",
+          bundleKey: "bundles/foo.tar.gz",
+          targetRuntimeVersion: "1.9.0",
+        },
+        VAK_TOKEN,
+        PLATFORM_URL,
+      );
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(VersionMismatchError);
+    expect(caught).toBeInstanceOf(Error);
+    const err = caught as VersionMismatchError;
+    expect(err.bundleCompat).toEqual({
+      min_runtime_version: "2.0.0",
+      max_runtime_version: "2.5.0",
+    });
+    expect(err.targetRuntimeVersion).toBe("1.9.0");
+    expect(err.message).toBe(
+      "Cannot import: bundle requires runtime 2.0.0–2.5.0, but this runtime is 1.9.0. Update your runtime before importing.",
+    );
+  });
+
+  test("download 422 with version_mismatch and null max_runtime_version → '+' suffix in message", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          reason: "version_mismatch",
+          bundle_compat: {
+            min_runtime_version: "3.0.0",
+            max_runtime_version: null,
+          },
+          target_runtime_version: "2.9.0",
+        }),
+        { status: 422 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    let caught: unknown;
+    try {
+      await platformRequestSignedUrl(
+        {
+          operation: "download",
+          bundleKey: "bundles/foo.tar.gz",
+          targetRuntimeVersion: "2.9.0",
+        },
+        VAK_TOKEN,
+        PLATFORM_URL,
+      );
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(VersionMismatchError);
+    const err = caught as VersionMismatchError;
+    expect(err.message).toBe(
+      "Cannot import: bundle requires runtime 3.0.0+, but this runtime is 2.9.0. Update your runtime before importing.",
+    );
+  });
+
+  test("download 422 with arbitrary body (no reason field) → falls through to generic Error", async () => {
+    const { fetchMock } = captureFetch(() => {
+      return new Response(JSON.stringify({ detail: "validation failed" }), {
+        status: 422,
+      });
+    });
+    globalThis.fetch = fetchMock;
+
+    let caught: unknown;
+    try {
+      await platformRequestSignedUrl(
+        { operation: "download", bundleKey: "bundles/foo.tar.gz" },
+        VAK_TOKEN,
+        PLATFORM_URL,
+      );
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(Error);
+    expect(caught).not.toBeInstanceOf(VersionMismatchError);
+    expect((caught as Error).message).toBe("validation failed");
+  });
+
+  test("422 is NOT retried after a 401", async () => {
+    let callCount = 0;
+    const { calls, fetchMock } = captureFetch(() => {
+      callCount += 1;
+      if (callCount === 1) {
+        return new Response(JSON.stringify({ detail: "unauthorized" }), {
+          status: 401,
+        });
+      }
+      return new Response(
+        JSON.stringify({
+          reason: "version_mismatch",
+          bundle_compat: {
+            min_runtime_version: "2.0.0",
+            max_runtime_version: "2.5.0",
+          },
+          target_runtime_version: "1.9.0",
+        }),
+        { status: 422 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    let caught: unknown;
+    try {
+      await platformRequestSignedUrl(
+        {
+          operation: "download",
+          bundleKey: "bundles/foo.tar.gz",
+          targetRuntimeVersion: "1.9.0",
+        },
+        VAK_TOKEN,
+        PLATFORM_URL,
+      );
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(calls).toHaveLength(2);
+    expect(caught).toBeInstanceOf(VersionMismatchError);
+  });
+
+  test("non-422 download path remains unchanged (regression pin on body shape)", async () => {
+    const { calls, fetchMock } = captureFetch(() => {
+      return new Response(
+        JSON.stringify({
+          url: "https://storage.example/signed/dl-xyz",
+          bundle_key: "bundles/xyz.tar.gz",
+          expires_at: "2026-04-22T02:00:00Z",
+        }),
+        { status: 201 },
+      );
+    });
+    globalThis.fetch = fetchMock;
+
+    const result = await platformRequestSignedUrl(
+      { operation: "download", bundleKey: "bundles/xyz.tar.gz" },
+      VAK_TOKEN,
+      PLATFORM_URL,
+    );
+
+    expect(result.url).toBe("https://storage.example/signed/dl-xyz");
+    expect(calls[0]!.body).toEqual({
+      operation: "download",
+      bundle_key: "bundles/xyz.tar.gz",
+    });
+  });
+
+  test("5xx error response → surfaces platform detail message", async () => {
     const { fetchMock } = captureFetch(() => {
       return new Response(JSON.stringify({ detail: "temporarily down" }), {
         status: 503,
@@ -305,7 +540,7 @@ describe("platformRequestSignedUrl", () => {
         VAK_TOKEN,
         PLATFORM_URL,
       ),
-    ).rejects.toThrow(/503/);
+    ).rejects.toThrow(/temporarily down/);
   });
 });