feat: add support for urls in .generate function (#132)

Author: davidhu2000

src/resources/v1/files/resource-client.test.ts

@@ -69,6 +69,71 @@ describe("FilesClient.uploadFile", () => {
     mockFs.readFileSync.mockReturnValue(Buffer.from("mock file content"));
   });
 
+  describe("URL and already-uploaded path handling", () => {
+    test("should return HTTP URL as-is without uploading", async () => {
+      const url = "http://example.com/image.jpg";
+      const createSpy = jest.spyOn(client.v1.files.uploadUrls, "create");
+
+      const result = await client.v1.files.uploadFile(url);
+
+      expect(result).toBe(url);
+      expect(createSpy).not.toHaveBeenCalled();
+      expect(mockFs.existsSync).not.toHaveBeenCalled();
+
+      createSpy.mockRestore();
+    });
+
+    test("should return HTTPS URL as-is without uploading", async () => {
+      const url = "https://example.com/path/to/video.mp4";
+      const createSpy = jest.spyOn(client.v1.files.uploadUrls, "create");
+
+      const result = await client.v1.files.uploadFile(url);
+
+      expect(result).toBe(url);
+      expect(createSpy).not.toHaveBeenCalled();
+      expect(mockFs.existsSync).not.toHaveBeenCalled();
+
+      createSpy.mockRestore();
+    });
+
+    test("should return already-uploaded api-assets path as-is without uploading", async () => {
+      const apiAssetsPath = "api-assets/12345/image.jpg";
+      const createSpy = jest.spyOn(client.v1.files.uploadUrls, "create");
+
+      const result = await client.v1.files.uploadFile(apiAssetsPath);
+
+      expect(result).toBe(apiAssetsPath);
+      expect(createSpy).not.toHaveBeenCalled();
+      expect(mockFs.existsSync).not.toHaveBeenCalled();
+
+      createSpy.mockRestore();
+    });
+
+    test("should handle URLs with query parameters", async () => {
+      const url = "https://example.com/image.jpg?token=abc123&expires=12345";
+      const createSpy = jest.spyOn(client.v1.files.uploadUrls, "create");
+
+      const result = await client.v1.files.uploadFile(url);
+
+      expect(result).toBe(url);
+      expect(createSpy).not.toHaveBeenCalled();
+
+      createSpy.mockRestore();
+    });
+
+    test("should upload local file paths that look similar to URLs but are not", async () => {
+      const filePath = "/http/example.com/image.jpg";
+      const createSpy = jest.spyOn(client.v1.files.uploadUrls, "create");
+
+      const result = await client.v1.files.uploadFile(filePath);
+
+      expect(result).toBe("api-assets/12345/image.jpg");
+      expect(createSpy).toHaveBeenCalled();
+
+      createSpy.mockRestore();
+    });
+  });
+
   describe("File type detection", () => {
     // MSW handles the uploadUrls.create call automatically
 

src/resources/v1/files/resource-client.ts

@@ -8,6 +8,7 @@ import {
 import * as path from "path";
 import { Readable } from "stream";
 
+import { getLogger } from "magic-hour/logger";
 import { UploadUrlsClient } from "magic-hour/resources/v1/files/upload-urls";
 
 export type FileInput =
@@ -17,6 +18,25 @@ export type FileInput =
   | File
   | NodeJS.ReadableStream;
 
+/**
+ * Check if the given string is a valid HTTP/HTTPS URL.
+ */
+function isUrl(str: string): boolean {
+  try {
+    const url = new URL(str);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the given string is an already-uploaded path (api-assets/).
+ */
+function isAlreadyUploaded(str: string): boolean {
+  return str.startsWith("api-assets/");
+}
+
 /**
  * Determine file type and extension from file path or name.
  */
@@ -128,14 +148,20 @@ export class FilesClient extends CoreResourceClient {
    * a file path that can be used as input for other Magic Hour API endpoints.
    * The file type is automatically detected from the file extension.
    *
+   * If a URL (http:// or https://) or an already-uploaded path (api-assets/...)
+   * is provided, it will be returned as-is without uploading.
+   *
    * @param file - The file to upload. Can be:
-   *   - **string**: Path to a local file (e.g., "/path/to/image.jpg")
+   *   - **string**: Path to a local file (e.g., "/path/to/image.jpg"),
+   *     a URL (e.g., "https://example.com/image.jpg"), or
+   *     an already-uploaded path (e.g., "api-assets/id/1234.png")
    *   - **Buffer**: File content as buffer (requires extension detection via other means)
    *   - **Readable**: Node.js readable stream (must have a 'path' property)
    *   - **File**: File object (browser environment)
    *
-   * @returns The uploaded file's path in Magic Hour's storage system.
-   *   This path can be used as input for other API endpoints.
+   * @returns The file path that can be used as input for other API endpoints.
+   *   For local files, this will be the uploaded path in Magic Hour's storage.
+   *   For URLs and already-uploaded paths, this will be the input string as-is.
    *
    * @throws {Error} If the specified local file doesn't exist.
    * @throws {Error} If the file type is not supported.
@@ -151,6 +177,10 @@ export class FilesClient extends CoreResourceClient {
    * const filePath = await client.v1.files.uploadFile("/path/to/your/image.jpg");
    * console.log(`Uploaded file: ${filePath}`);
    *
+   * // URLs are returned as-is (no upload needed)
+   * const urlPath = await client.v1.files.uploadFile("https://example.com/image.jpg");
+   * console.log(urlPath); // "https://example.com/image.jpg"
+   *
    * // Use the uploaded file in other API calls
    * const result = await client.v1.aiImageUpscaler.create({
    *   assets: { imageFilePath: filePath },
@@ -159,7 +189,29 @@ export class FilesClient extends CoreResourceClient {
    * ```
    */
   async uploadFile(file: FileInput): Promise<string> {
+    const logger = getLogger();
+
+    // If the input is a URL or already-uploaded path, return it as-is
+    if (typeof file === "string") {
+      if (isUrl(file)) {
+        logger.debug(`Skipping upload for ${file} since it is a valid URL`);
+        return file;
+      } else if (isAlreadyUploaded(file)) {
+        logger.debug(
+          `Skipping upload for ${file} since it is a valid already-uploaded path`,
+        );
+        return file;
+      } else {
+        logger.debug(
+          `Processing file input for upload ${file} as a local file`,
+        );
+      }
+    }
+
     const { filePath, fileData, fileType, extension } = processFileInput(file);
+    logger.debug(
+      `File processed: type=${fileType}, extension=${extension}, source=${filePath ? "path" : "data"}`,
+    );
 
     // Create upload URL
     const response = await this.uploadUrls.create({
@@ -179,25 +231,32 @@ export class FilesClient extends CoreResourceClient {
     if (!uploadInfo) {
       throw new Error("Upload info is missing from server response");
     }
+    logger.debug(`Received upload URL, target path: ${uploadInfo.filePath}`);
 
     // Prepare file content
     let content: Buffer;
     if (filePath) {
       content = fs.readFileSync(filePath);
+      logger.debug(`Read ${content.length} bytes from local file: ${filePath}`);
     } else if (fileData) {
       if (Buffer.isBuffer(fileData)) {
         content = fileData;
+        logger.debug(`Using buffer data: ${content.length} bytes`);
       } else if (fileData instanceof Readable) {
         // For streams, read all data into buffer
         const chunks: Buffer[] = [];
         for await (const chunk of fileData) {
           chunks.push(chunk);
         }
         content = Buffer.concat(chunks);
+        logger.debug(`Read ${content.length} bytes from stream`);
       } else if (typeof File !== "undefined" && fileData instanceof File) {
         // File object - convert to buffer
         const arrayBuffer = await fileData.arrayBuffer();
         content = Buffer.from(arrayBuffer);
+        logger.debug(
+          `Read ${content.length} bytes from File object: ${fileData.name}`,
+        );
       } else {
         throw new Error("Unsupported file data type");
       }
@@ -222,6 +281,7 @@ export class FilesClient extends CoreResourceClient {
       );
     }
 
+    logger.debug(`Upload complete: ${uploadInfo.filePath}`);
     return uploadInfo.filePath;
   }
 }