@yetter/client 0.0.11 → 0.0.12

package/README.md

@@ -44,7 +44,7 @@ This function submits an image generation request and long-polls for the result.
 
 **Features:**
 - Submits a generation request.
-- Polls for status updates until the job is "COMPLETED" or "FAILED".
+- Polls for status updates until the job is "COMPLETED" or "ERROR".
 - Timeout after 30 minutes, with an attempt to cancel the job.
 - Optional `onQueueUpdate` callback for real-time feedback on queue position and status.
 - Optional `logs` flag to include logs in status updates.
@@ -71,7 +71,7 @@ async function main() {
                     update.logs.map((log) => log.message).forEach(logMessage => console.log(`  - ${logMessage}`));
                 } else if (update.status === "COMPLETED") {
                     console.log("Processing completed!");
-                } else if (update.status === "FAILED") {
+                } else if (update.status === "ERROR") {
                     console.error("Processing failed. Logs:", update.logs);
                 }
             },
@@ -95,18 +95,18 @@ main();
 This function submits an image generation request and returns an async iterable stream of events using Server-Sent Events (SSE). This allows for real-time updates on the job's progress, status, and logs.
 
 **Features:**
--   Initiates a request and establishes an SSE connection.
--   Provides an `AsyncIterator` (`Symbol.asyncIterator`) to loop through status events (`StreamEvent`).
--   A `done()` method: Returns a Promise that resolves with the final `GetResponseResponse` when the job is "COMPLETED", or rejects if it "FAILED" or the stream is prematurely closed.
--   A `cancel()` method: Closes the stream and attempts to cancel the underlying image generation request.
--   A `getRequestId()` method: Returns the request ID for the stream.
+
+* Initiates a request and establishes an SSE connection.
+* Provides an `AsyncIterator` (`Symbol.asyncIterator`) to loop through status events (`StreamEvent`).
+* A `done()` method: Returns a Promise that resolves with the final `GetResponseResponse` **after the server emits `event: done`** (successful completion), or rejects if the server emits `event: error` or the final response cannot be fetched.
+* A `cancel()` method: Requests cancellation on the backend; the stream naturally ends when the server emits `data` (with `status: "CANCELLED"`) followed by `event: done`.
+* A `getRequestId()` method: Returns the request ID for the stream.
 
 **Events (`StreamEvent`):**
 Each event pushed by the stream is an object typically including:
--   `status`: Current status (e.g., "IN_QUEUE", "IN_PROGRESS", "COMPLETED", "FAILED").
--   `queue_position`: Current position in the queue.
--   `logs`: Array of log messages if any.
--   Other model-specific data.
+
+* `status`: Current status (e.g., `"IN_QUEUE"`, `"IN_PROGRESS"`, `"COMPLETED"`, `"CANCELLED"`, `"ERROR"`).
+* Other model-specific data.
 
 **Example (from `examples/stream.ts`):**
 
@@ -127,9 +127,11 @@ async function main() {
         streamRequestId = streamInstance.getRequestId();
         console.log(`Stream initiated for Request ID: ${streamRequestId}`);
 
-        // Iterate over stream events
+        // Iterate over stream events (informational; termination is driven by server 'done'/'error' events)
         for await (const event of streamInstance) {
-            console.log(`[STREAM EVENT - ${streamRequestId}] Status: ${event.status}, QPos: ${event.queue_position}`);
+            console.log(
+              `[STREAM EVENT - ${streamRequestId}] Status: ${event.status}, QPos: ${event.queue_position}`
+            );
             if (event.logs && event.logs.length > 0) {
                 console.log(`  Logs for ${streamRequestId}:`);
                 event.logs.forEach(log => console.log(`    - ${log.message}`));
@@ -137,7 +139,7 @@ async function main() {
         }
         console.log(`Stream for ${streamRequestId} finished iterating events.`);
 
-        // Wait for the final result from the done() method
+        // Final result becomes available after server emits `event: done`
         const result = await streamInstance.done();
         console.log("\n--- Stream Test Final Result ---");
         console.log("Generated Images:", result.images);
@@ -215,7 +217,7 @@ async function main() {
                     console.log("Image Data:", finalResult.data.images);
                     success = true;
                     break;
-                } else if (currentStatus === "FAILED") {
+                } else if (currentStatus === "ERROR") {
                     console.error(`Request ${request_id} FAILED. Logs:`, statusResult.data.logs);
                     break;
                 }
@@ -231,6 +233,59 @@ async function main() {
 main();
 ```
 
+### 4. Uploading Input Images
+
+For models that require an input image (e.g., image-to-image, style transfer), you can upload your image using `yetter.uploadFile()` (Node.js) or `yetter.uploadBlob()` (browser).
+
+**Features:**
+- Support for both Node.js filesystem paths and browser File/Blob objects
+- Automatic single-part or multipart upload based on file size
+- Progress tracking with optional callback
+- Returns a public URL to use in generation requests
+
+#### Node.js Example
+
+```typescript
+import { yetter } from "@yetter/client";
+
+yetter.configure({ apiKey: process.env.YTR_API_KEY });
+
+// Upload image
+const uploadResult = await yetter.uploadFile("./input-image.jpg", {
+    onProgress: (percent) => console.log(`Upload: ${percent}%`),
+});
+
+// Use in generation
+const result = await yetter.subscribe("ytr-ai/model/i2i", {
+    input: {
+        prompt: "Transform to anime style",
+        input_image_url: uploadResult.url,
+    },
+});
+```
+
+#### Browser Example
+
+```typescript
+// HTML: <input type="file" id="imageInput" accept="image/*">
+
+const fileInput = document.getElementById('imageInput') as HTMLInputElement;
+fileInput.addEventListener('change', async () => {
+    const file = fileInput.files![0];
+
+    const uploadResult = await yetter.uploadBlob(file, {
+        onProgress: (pct) => updateProgressBar(pct),
+    });
+
+    console.log("Uploaded:", uploadResult.url);
+});
+```
+
+**Upload Options:**
+- `onProgress?: (progress: number) => void` - Progress callback (0-100)
+- `timeout?: number` - Timeout in milliseconds (default: 5 minutes)
+- `filename?: string` - Custom filename (browser uploads)
+
 ## Error Handling
 
 The client functions generally throw errors for API issues, network problems, or failed generation requests. Ensure you wrap API calls in `try...catch` blocks to handle potential errors gracefully. Specific error messages or details (like logs for failed jobs) are often included in the thrown error object or the final status response.

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import { ClientOptions, GenerateRequest, GenerateResponse, GetStatusRequest, GetStatusResponse, CancelRequest, CancelResponse, GetResponseRequest, GetResponseResponse } from "./types";
+import { ClientOptions, GenerateRequest, GenerateResponse, GetStatusRequest, GetStatusResponse, CancelRequest, CancelResponse, GetResponseRequest, GetResponseResponse, GetUploadUrlRequest, GetUploadUrlResponse, UploadCompleteRequest, UploadCompleteResponse } from "./types";
 export declare class YetterImageClient {
     private apiKey;
     private endpoint;
@@ -8,4 +8,16 @@ export declare class YetterImageClient {
     getStatus(body: GetStatusRequest): Promise<GetStatusResponse>;
     cancel(body: CancelRequest): Promise<CancelResponse>;
     getResponse(body: GetResponseRequest): Promise<GetResponseResponse>;
+    /**
+     * Request presigned URL(s) for file upload
+     * @param body Upload request parameters
+     * @returns Presigned URL response with mode (single/multipart)
+     */
+    getUploadUrl(body: GetUploadUrlRequest): Promise<GetUploadUrlResponse>;
+    /**
+     * Notify server that upload is complete
+     * @param body Completion request with S3 key
+     * @returns Uploaded file metadata with public URL
+     */
+    uploadComplete(body: UploadCompleteRequest): Promise<UploadCompleteResponse>;
 }

package/dist/api.js

@@ -72,4 +72,44 @@ export class YetterImageClient {
         }
         return (await res.json());
     }
+    /**
+     * Request presigned URL(s) for file upload
+     * @param body Upload request parameters
+     * @returns Presigned URL response with mode (single/multipart)
+     */
+    async getUploadUrl(body) {
+        const res = await fetch(`${this.endpoint}/uploads`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: this.apiKey,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const errorText = await res.text();
+            throw new Error(`Upload URL request failed (${res.status}): ${errorText}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Notify server that upload is complete
+     * @param body Completion request with S3 key
+     * @returns Uploaded file metadata with public URL
+     */
+    async uploadComplete(body) {
+        const res = await fetch(`${this.endpoint}/uploads/complete`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: this.apiKey,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const errorText = await res.text();
+            throw new Error(`Upload completion failed (${res.status}): ${errorText}`);
+        }
+        return (await res.json());
+    }
 }

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { ClientOptions, GetResponseResponse, SubscribeOptions, GenerateResponse, SubmitQueueOptions, GetResultOptions, GetResultResponse, StatusOptions, StatusResponse, StreamOptions, YetterStream } from "./types.js";
+import { ClientOptions, GetResponseResponse, SubscribeOptions, GenerateResponse, SubmitQueueOptions, GetResultOptions, GetResultResponse, StatusOptions, StatusResponse, StreamOptions, YetterStream, UploadOptions, UploadCompleteResponse } from "./types.js";
 export declare class yetter {
     private static apiKey;
     private static endpoint;
@@ -10,4 +10,56 @@ export declare class yetter {
         result: (model: string, options: GetResultOptions) => Promise<GetResultResponse>;
     };
     static stream(model: string, options: StreamOptions): Promise<YetterStream>;
+    /**
+     * Upload a file from the filesystem (Node.js) or File/Blob object (browser)
+     *
+     * @param fileOrPath File path (Node.js) or File/Blob object (browser)
+     * @param options Upload configuration options
+     * @returns Promise resolving to upload result with public URL
+     *
+     * @example
+     * ```typescript
+     * // Node.js
+     * const result = await yetter.uploadFile("/path/to/image.jpg", {
+     *   onProgress: (pct) => console.log(`Upload: ${pct}%`)
+     * });
+     *
+     * // Browser
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     * const result = await yetter.uploadFile(file, {
+     *   onProgress: (pct) => updateProgressBar(pct)
+     * });
+     * ```
+     */
+    static uploadFile(fileOrPath: string | File | Blob, options?: UploadOptions): Promise<UploadCompleteResponse>;
+    /**
+     * Upload a file from browser (File or Blob object)
+     * This is an alias for uploadFile for better clarity in browser contexts
+     */
+    static uploadBlob(file: File | Blob, options?: UploadOptions): Promise<UploadCompleteResponse>;
+    /**
+     * Upload file from filesystem path (Node.js only)
+     */
+    private static _uploadFromPath;
+    /**
+     * Upload file from Blob/File object (browser)
+     */
+    private static _uploadFromBlob;
+    /**
+     * Upload file using single PUT request (Node.js, private helper)
+     */
+    private static _uploadFileSingle;
+    /**
+     * Upload file using multipart upload (Node.js, private helper)
+     */
+    private static _uploadFileMultipart;
+    /**
+     * Upload blob using single PUT request (browser, private helper)
+     */
+    private static _uploadBlobSingle;
+    /**
+     * Upload blob using multipart upload (browser, private helper)
+     */
+    private static _uploadBlobMultipart;
 }