Add createSignedUrl to YepCodeApi and YepCodeStorage

Wraps the new POST /storage/signed-urls endpoint that returns a short-lived
GCS V4 signed read URL for an existing file.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: marcos-muino-garcia

src/api/types.ts

@@ -463,6 +463,17 @@ export type CreateStorageObjectInput = {
   file: File | Blob | Readable;
 };
 
+export type CreateSignedUrlInput = {
+  path: string;
+  expiresInSeconds?: number;
+};
+
+export type SignedUrl = {
+  url: string;
+  path: string;
+  expiresAt: string;
+};
+
 /**
  * Auth
  */

src/api/yepcodeApi.ts

@@ -34,6 +34,8 @@ import {
   VersionedModuleAliasesPaginatedResult,
   StorageObject,
   CreateStorageObjectInput,
+  CreateSignedUrlInput,
+  SignedUrl,
   Token,
   Sandbox,
   CreateSandboxInput,
@@ -796,6 +798,10 @@ export class YepCodeApi {
     );
   }
 
+  async createSignedUrl(data: CreateSignedUrlInput): Promise<SignedUrl> {
+    return this.request("POST", "/storage/signed-urls", { data });
+  }
+
   // Auth endpoints
   async getToken(apiToken: string): Promise<Token> {
     return this.request("POST", "/auth/token", {

src/storage/yepcodeStorage.ts

@@ -1,5 +1,5 @@
 import { YepCodeApi } from "../api";
-import { StorageObject, YepCodeApiConfig } from "../api/types";
+import { SignedUrl, StorageObject, YepCodeApiConfig } from "../api/types";
 import { Readable } from "stream";
 
 export class YepCodeStorage {
@@ -27,4 +27,11 @@ export class YepCodeStorage {
   async delete(filename: string): Promise<void> {
     await this.api.deleteObject(filename);
   }
+
+  async createSignedUrl(
+    filename: string,
+    options: { expiresInSeconds?: number } = {}
+  ): Promise<SignedUrl> {
+    return this.api.createSignedUrl({ path: filename, ...options });
+  }
 }

tests/api/yepcodeApi.storage.test.ts

@@ -1,5 +1,5 @@
-import { YepCodeApi } from "../../src/api/yepcodeApi";
-import { StorageObject } from "../../src/api/types";
+import { YepCodeApi, YepCodeApiError } from "../../src/api/yepcodeApi";
+import { SignedUrl, StorageObject } from "../../src/api/types";
 import fs, { createWriteStream, readFileSync } from "fs";
 import path from "path";
 import { Readable } from "stream";
@@ -113,4 +113,68 @@ describe.skip("YepCodeApi", () => {
       await verifyDownloadedFile(result, downloadedFile, testFilePath);
     });
   });
+
+  describe("createSignedUrl", () => {
+    it("should return a signed url with the default expiry", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await api.createObject({ name: testName, file });
+
+      const result: SignedUrl = await api.createSignedUrl({ path: testName });
+
+      expect(typeof result.url).toBe("string");
+      expect(result.url.length).toBeGreaterThan(0);
+      expect(result.path).toBe(testName);
+
+      const expiresAt = new Date(result.expiresAt).getTime();
+      const expectedExpiry = Date.now() + 3600 * 1000;
+      expect(Math.abs(expiresAt - expectedExpiry)).toBeLessThan(60 * 1000);
+    });
+
+    it("should return a signed url with a custom expiry", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await api.createObject({ name: testName, file });
+
+      const result: SignedUrl = await api.createSignedUrl({
+        path: testName,
+        expiresInSeconds: 60,
+      });
+
+      const expiresAt = new Date(result.expiresAt).getTime();
+      const expectedExpiry = Date.now() + 60 * 1000;
+      expect(Math.abs(expiresAt - expectedExpiry)).toBeLessThan(30 * 1000);
+    });
+
+    it("should return content matching the original file when fetched", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await api.createObject({ name: testName, file });
+
+      const { url } = await api.createSignedUrl({ path: testName });
+
+      const response = await fetch(url);
+      expect(response.ok).toBe(true);
+      const body = await response.text();
+      expect(body).toBe(readFileSync(testFilePath, "utf8"));
+    });
+
+    it("should throw a 404 when the file does not exist", async () => {
+      await expect(
+        api.createSignedUrl({ path: "does-not-exist.txt" })
+      ).rejects.toMatchObject({
+        name: "YepCodeApiError",
+        status: 404,
+      } as Partial<YepCodeApiError>);
+    });
+
+    it("should throw a 400 when expiresInSeconds is out of range", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await api.createObject({ name: testName, file });
+
+      await expect(
+        api.createSignedUrl({ path: testName, expiresInSeconds: 999999 })
+      ).rejects.toMatchObject({
+        name: "YepCodeApiError",
+        status: 400,
+      } as Partial<YepCodeApiError>);
+    });
+  });
 });

tests/storage/yepcodeStorage.test.ts

@@ -1,5 +1,6 @@
 import { YepCodeStorage } from "../../src/storage";
-import { StorageObject } from "../../src/api/types";
+import { YepCodeApiError } from "../../src/api/yepcodeApi";
+import { SignedUrl, StorageObject } from "../../src/api/types";
 import fs, { createWriteStream, readFileSync } from "fs";
 import path from "path";
 import { Readable } from "stream";
@@ -117,4 +118,55 @@ describe.skip("YepCodeStorage", () => {
       await verifyDownloadedFile(result, downloadedFile, testFilePath);
     });
   });
+
+  describe("createSignedUrl", () => {
+    it("should return a signed url with the default expiry", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await storage.upload(testName, file);
+
+      const result: SignedUrl = await storage.createSignedUrl(testName);
+
+      expect(typeof result.url).toBe("string");
+      expect(result.url.length).toBeGreaterThan(0);
+      expect(result.path).toBe(testName);
+
+      const expiresAt = new Date(result.expiresAt).getTime();
+      const expectedExpiry = Date.now() + 3600 * 1000;
+      expect(Math.abs(expiresAt - expectedExpiry)).toBeLessThan(60 * 1000);
+    });
+
+    it("should return a signed url with a custom expiry", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await storage.upload(testName, file);
+
+      const result: SignedUrl = await storage.createSignedUrl(testName, {
+        expiresInSeconds: 60,
+      });
+
+      const expiresAt = new Date(result.expiresAt).getTime();
+      const expectedExpiry = Date.now() + 60 * 1000;
+      expect(Math.abs(expiresAt - expectedExpiry)).toBeLessThan(30 * 1000);
+    });
+
+    it("should throw a 404 when the file does not exist", async () => {
+      await expect(
+        storage.createSignedUrl("does-not-exist.txt")
+      ).rejects.toMatchObject({
+        name: "YepCodeApiError",
+        status: 404,
+      } as Partial<YepCodeApiError>);
+    });
+
+    it("should throw a 400 when expiresInSeconds is out of range", async () => {
+      const file: File = new File([readFileSync(testFilePath)], testName);
+      await storage.upload(testName, file);
+
+      await expect(
+        storage.createSignedUrl(testName, { expiresInSeconds: 999999 })
+      ).rejects.toMatchObject({
+        name: "YepCodeApiError",
+        status: 400,
+      } as Partial<YepCodeApiError>);
+    });
+  });
 });