@yetter/client 0.0.11 → 0.0.12

package/src/client.ts

@@ -14,6 +14,8 @@ import {
     StreamOptions,
     StreamEvent,
     YetterStream,
+    UploadOptions,
+    UploadCompleteResponse,
 } from "./types.js";
 
 export class yetter {
@@ -56,7 +58,7 @@ export class yetter {
         const startTime = Date.now();
         const timeoutMilliseconds = 30 * 60 * 1000; // 30 minutes
 
-        while (status !== "COMPLETED" && status !== "FAILED") {
+        while (status !== "COMPLETED" && status !== "ERROR" && status !== "CANCELLED") {
             if (Date.now() - startTime > timeoutMilliseconds) {
                 console.warn(`Subscription timed out after 30 minutes for request ID: ${generateResponse.request_id}. Attempting to cancel.`);
                 try {
@@ -84,9 +86,11 @@ export class yetter {
             }
         }
 
-        if (status === "FAILED") {
+        if (status === "ERROR") {
             const errorMessage = lastStatusResponse?.logs?.map(log => log.message).join("\n") || "Image generation failed.";
             throw new Error(errorMessage);
+        } else if (status === "CANCELLED") {
+            throw new Error("Image generation was cancelled by user.");
         }
 
         const finalResponse = await client.getResponse({
@@ -188,7 +192,6 @@ export class yetter {
         const sseStreamUrl = `${client.getApiEndpoint()}/${model}/requests/${requestId}/status/stream`;
 
         let eventSource: EventSource;
-        let streamEnded = false;
 
         // Setup the promise for the done() method
         let resolveDonePromise: (value: GetResponseResponse) => void;
@@ -204,6 +207,18 @@ export class yetter {
             events: [] as StreamEvent[],
             resolvers: [] as Array<(value: IteratorResult<StreamEvent, any>) => void>,
             isClosed: false,
+            isSettled: false,
+            currentStatus: "" as "COMPLETED" | "ERROR" | "CANCELLED" | "IN_PROGRESS" | "IN_QUEUE",
+            callResolver(value: GetResponseResponse) {
+                if (this.isSettled) return;
+                this.isSettled = true;
+                resolveDonePromise(value);
+            },
+            callRejecter(reason?: any) {
+                if (this.isSettled) return;
+                this.isSettled = true;
+                rejectDonePromise(reason);
+            },
             push(event: StreamEvent) {
                 if (this.isClosed) return;
                 if (this.resolvers.length > 0) {
@@ -212,51 +227,39 @@ export class yetter {
                     this.events.push(event);
                 }
                 // Check for terminal events to resolve/reject the donePromise
-                if (event.status === "COMPLETED") {
-                    streamEnded = true;
-                    client.getResponse({ url: responseUrl })
-                        .then(resolveDonePromise)
-                        .catch(rejectDonePromise)
-                        .finally(() => this.close());
-                } else if (event.status === "FAILED") {
-                    streamEnded = true;
-                    rejectDonePromise(new Error(event.logs?.map(l => l.message).join('\n') || `Stream reported FAILED for ${requestId}`));
-                    this.close();
-                }
+                this.currentStatus = event.status as "COMPLETED" | "ERROR" | "CANCELLED" | "IN_PROGRESS" | "IN_QUEUE";
             },
             error(err: any) {
                 if (this.isClosed) return;
-
-                // If streamEnded is true, it means a terminal event (COMPLETED/FAILED)
-                // has already been processed and is handling the donePromise.
-                // This error is likely a secondary effect of the connection closing.
-                if (!streamEnded) {
-                    rejectDonePromise(err); // Only reject if no terminal event was processed
-                } else {
-                    console.warn("SSE 'onerror' event after stream was considered ended (COMPLETED/FAILED). This error will not alter the done() promise.", err);
+                if (this.resolvers.length > 0) {
+                    this.resolvers.shift()!({ value: undefined, done: true });
                 }
-
-                streamEnded = true; // Ensure it's marked as ended
+                this._close();
+                const errorToReport = err instanceof Error ? err : new Error("Stream closed prematurely or unexpectedly.");
+                this.callRejecter(errorToReport);
+            },
+            done(value: GetResponseResponse) {
+                if (this.isClosed) return;
+                if (this.resolvers.length > 0) {
+                    this.resolvers.shift()!({ value: undefined, done: true });
+                }
+                this._close();
+                this.callResolver(value);
+            },
+            cancel() {
+                if (this.isClosed) return;
                 if (this.resolvers.length > 0) {
-                    this.resolvers.shift()!({ value: undefined, done: true }); // Signal error to iterator consumer
+                    this.resolvers.shift()!({ value: undefined, done: true });
                 }
-                this.close(); // Proceed to close EventSource etc.
+                this._close();
+                this.callRejecter(new Error("Stream was cancelled by user."));
             },
-            close() {
+            _close() {
                 if (this.isClosed) return;
                 this.isClosed = true;
                 this.resolvers.forEach(resolve => resolve({ value: undefined, done: true }));
                 this.resolvers = [];
                 eventSource?.close();
-                 // If donePromise is still pending, reject it as stream closed prematurely
-                // Use a timeout to allow any final event processing for COMPLETED/FAILED to settle it first
-                setTimeout(() => {
-                    donePromise.catch(() => {}).finally(() => { // check if it's already settled
-                        if (!streamEnded) { // If not explicitly completed or failed
-                           rejectDonePromise(new Error("Stream closed prematurely or unexpectedly."));
-                        }
-                    });
-                }, 100);
             },
             next(): Promise<IteratorResult<StreamEvent, any>> {
                 if (this.events.length > 0) {
@@ -287,10 +290,31 @@ export class yetter {
                 controller.error(new Error(`Error parsing SSE 'data' event: ${e.message}`));
             }
         });
-
-        eventSource.addEventListener('done', (event: MessageEvent) => {
+        // when 'done' event is received, currentStatus can only be COMPLETED or CANCELLED
+        // TODO: remove currentStatus and branch two cases(COMPLETED and CANCELLED) by response status by responseUrl
+        // TODO: Determine whether raise error or not when response status is CANCELLED
+        //  => current code raise error when response status is CANCELLED because resolveDonePromise only get completed response
+        // => this mean that user expect only completed response from .done() method
+        eventSource.addEventListener('done', async (event: MessageEvent) => {
+            // console.log("SSE 'done' event received, raw data:", event.data);
+            try {
+                if (controller.currentStatus === "COMPLETED") {
+                    // Close SSE immediately to avoid any late 'error' events during await
+                    try { eventSource?.close(); } catch {}
+                    const response = await client.getResponse({ url: responseUrl });
+                    controller.done(response);
+                } else if (controller.currentStatus === "CANCELLED") {
+                    controller.cancel();
+                }
+            } catch (e: any) {
+                console.error("Error parsing SSE 'done' event:", e, "Raw data:", event.data);
+                controller.error(new Error(`Error parsing SSE 'done' event: ${e.message}`));
+            }
+        });
+        eventSource.addEventListener('error', (event: MessageEvent) => {
             // console.log("SSE 'done' event received, raw data:", event.data);
-            controller.close();
+            console.log("SSE 'error' event received, raw data:", event.data);
+            controller.error(new Error("Stream reported ERROR for ${requestId}"));
         });
 
         eventSource.onerror = (err: Event | MessageEvent) => { 
@@ -306,7 +330,7 @@ export class yetter {
         // Handle if API immediately returns a terminal status in initialApiResponse (e.g. already completed/failed)
         if (initialApiResponse.status === "COMPLETED"){
             controller.push(initialApiResponse as any as StreamEvent);
-        } else if (initialApiResponse.status === "FAILED"){
+        } else if (initialApiResponse.status === "ERROR"){
             controller.push(initialApiResponse as any as StreamEvent);
         }
 
@@ -320,19 +344,354 @@ export class yetter {
             },
             done: () => donePromise,
             cancel: async () => {
-                controller.close();
                 try {
                     await client.cancel({ url: cancelUrl });
                     console.log(`Stream for ${requestId} - underlying request cancelled.`);
                 } catch (e: any) {
                     console.error(`Error cancelling underlying request for stream ${requestId}:`, e.message);
                 }
-                // Ensure donePromise is settled if not already
-                if (!streamEnded) {
-                   rejectDonePromise(new Error("Stream was cancelled by user."));
-                }
             },
             getRequestId: () => requestId,
         };
     }
+
+    /**
+     * 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)
+     * });
+     * ```
+     */
+    public static async uploadFile(
+        fileOrPath: string | File | Blob,
+        options: UploadOptions = {}
+    ): Promise<UploadCompleteResponse> {
+        if (!yetter.apiKey) {
+            throw new Error("API key is not configured. Call yetter.configure()");
+        }
+
+        if (typeof fileOrPath === 'string') {
+            // Node.js path
+            return yetter._uploadFromPath(fileOrPath, options);
+        } else {
+            // Browser File/Blob
+            return yetter._uploadFromBlob(fileOrPath, options);
+        }
+    }
+
+    /**
+     * Upload a file from browser (File or Blob object)
+     * This is an alias for uploadFile for better clarity in browser contexts
+     */
+    public static async uploadBlob(
+        file: File | Blob,
+        options: UploadOptions = {}
+    ): Promise<UploadCompleteResponse> {
+        return yetter.uploadFile(file, options);
+    }
+
+    /**
+     * Upload file from filesystem path (Node.js only)
+     */
+    private static async _uploadFromPath(
+        filePath: string,
+        options: UploadOptions
+    ): Promise<UploadCompleteResponse> {
+        // Dynamic import for Node.js modules
+        const fs = await import('fs');
+        const mime = await import('mime-types');
+
+        // Validate file exists
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+
+        const stats = fs.statSync(filePath);
+        const fileSize = stats.size;
+        const fileName = filePath.split(/[\\/]/).pop() || "upload";
+        const mimeType = mime.default.lookup(filePath) || "application/octet-stream";
+
+        const client = new YetterImageClient({
+            apiKey: yetter.apiKey,
+            endpoint: yetter.endpoint,
+        });
+
+        // Step 1: Request presigned URL(s)
+        const uploadUrlResponse = await client.getUploadUrl({
+            file_name: fileName,
+            content_type: mimeType,
+            size: fileSize,
+        });
+
+        // Step 2: Upload file content
+        if (uploadUrlResponse.mode === "single") {
+            await yetter._uploadFileSingle(
+                filePath,
+                uploadUrlResponse.put_url!,
+                mimeType,
+                fileSize,
+                options,
+                fs
+            );
+        } else {
+            await yetter._uploadFileMultipart(
+                filePath,
+                uploadUrlResponse.part_urls!,
+                uploadUrlResponse.part_size!,
+                fileSize,
+                options,
+                fs
+            );
+        }
+
+        // Step 3: Notify completion
+        const result = await client.uploadComplete({
+            key: uploadUrlResponse.key,
+        });
+
+        if (options.onProgress) {
+            options.onProgress(100);
+        }
+
+        return result;
+    }
+
+    /**
+     * Upload file from Blob/File object (browser)
+     */
+    private static async _uploadFromBlob(
+        file: File | Blob,
+        options: UploadOptions
+    ): Promise<UploadCompleteResponse> {
+        const fileSize = file.size;
+        const fileName = options.filename ||
+                        (file instanceof File ? file.name : "blob-upload");
+        const mimeType = file.type || "application/octet-stream";
+
+        const client = new YetterImageClient({
+            apiKey: yetter.apiKey,
+            endpoint: yetter.endpoint,
+        });
+
+        // Step 1: Request presigned URL(s)
+        const uploadUrlResponse = await client.getUploadUrl({
+            file_name: fileName,
+            content_type: mimeType,
+            size: fileSize,
+        });
+
+        // Step 2: Upload file content
+        if (uploadUrlResponse.mode === "single") {
+            await yetter._uploadBlobSingle(
+                file,
+                uploadUrlResponse.put_url!,
+                mimeType,
+                fileSize,
+                options
+            );
+        } else {
+            await yetter._uploadBlobMultipart(
+                file,
+                uploadUrlResponse.part_urls!,
+                uploadUrlResponse.part_size!,
+                fileSize,
+                options
+            );
+        }
+
+        // Step 3: Notify completion
+        const result = await client.uploadComplete({
+            key: uploadUrlResponse.key,
+        });
+
+        if (options.onProgress) {
+            options.onProgress(100);
+        }
+
+        return result;
+    }
+
+    /**
+     * Upload file using single PUT request (Node.js, private helper)
+     */
+    private static async _uploadFileSingle(
+        filePath: string,
+        presignedUrl: string,
+        contentType: string,
+        totalSize: number,
+        options: UploadOptions,
+        fs: any
+    ): Promise<void> {
+        const fileBuffer = fs.readFileSync(filePath);
+
+        const response = await fetch(presignedUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": contentType,
+                "Content-Length": String(totalSize),
+            },
+            body: fileBuffer,
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(
+                `Single-part upload failed (${response.status}): ${errorText}`
+            );
+        }
+
+        if (options.onProgress) {
+            options.onProgress(90);
+        }
+    }
+
+    /**
+     * Upload file using multipart upload (Node.js, private helper)
+     */
+    private static async _uploadFileMultipart(
+        filePath: string,
+        partUrls: Array<{ part_number: number; url: string }>,
+        partSize: number,
+        totalSize: number,
+        options: UploadOptions,
+        fs: any
+    ): Promise<void> {
+        const sortedParts = [...partUrls].sort((a, b) => a.part_number - b.part_number);
+
+        const fileHandle = fs.openSync(filePath, "r");
+        try {
+            for (let i = 0; i < sortedParts.length; i++) {
+                const part = sortedParts[i];
+                const buffer = Buffer.alloc(partSize);
+                const offset = (part.part_number - 1) * partSize;
+
+                const bytesRead = fs.readSync(fileHandle, buffer, 0, partSize, offset);
+                const chunk = buffer.slice(0, bytesRead);
+
+                if (chunk.length === 0) {
+                    break;
+                }
+
+                const response = await fetch(part.url, {
+                    method: "PUT",
+                    headers: {
+                        "Content-Length": String(chunk.length),
+                    },
+                    body: chunk,
+                });
+
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    throw new Error(
+                        `Multipart upload failed at part ${part.part_number} ` +
+                        `(${response.status}): ${errorText}`
+                    );
+                }
+
+                if (options.onProgress) {
+                    const progress = Math.min(
+                        90,
+                        Math.floor(((i + 1) / sortedParts.length) * 90)
+                    );
+                    options.onProgress(progress);
+                }
+            }
+        } finally {
+            fs.closeSync(fileHandle);
+        }
+    }
+
+    /**
+     * Upload blob using single PUT request (browser, private helper)
+     */
+    private static async _uploadBlobSingle(
+        blob: Blob,
+        presignedUrl: string,
+        contentType: string,
+        totalSize: number,
+        options: UploadOptions
+    ): Promise<void> {
+        const response = await fetch(presignedUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": contentType,
+                "Content-Length": String(totalSize),
+            },
+            body: blob,
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(
+                `Single-part upload failed (${response.status}): ${errorText}`
+            );
+        }
+
+        if (options.onProgress) {
+            options.onProgress(90);
+        }
+    }
+
+    /**
+     * Upload blob using multipart upload (browser, private helper)
+     */
+    private static async _uploadBlobMultipart(
+        blob: Blob,
+        partUrls: Array<{ part_number: number; url: string }>,
+        partSize: number,
+        totalSize: number,
+        options: UploadOptions
+    ): Promise<void> {
+        const sortedParts = [...partUrls].sort((a, b) => a.part_number - b.part_number);
+
+        for (let i = 0; i < sortedParts.length; i++) {
+            const part = sortedParts[i];
+            const start = (part.part_number - 1) * partSize;
+            const end = Math.min(start + partSize, totalSize);
+            const chunk = blob.slice(start, end);
+
+            if (chunk.size === 0) {
+                break;
+            }
+
+            const response = await fetch(part.url, {
+                method: "PUT",
+                headers: {
+                    "Content-Length": String(chunk.size),
+                },
+                body: chunk,
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(
+                    `Multipart upload failed at part ${part.part_number} ` +
+                    `(${response.status}): ${errorText}`
+                );
+            }
+
+            if (options.onProgress) {
+                const progress = Math.min(
+                    90,
+                    Math.floor(((i + 1) / sortedParts.length) * 90)
+                );
+                options.onProgress(progress);
+            }
+        }
+    }
 }

package/src/index.ts

@@ -1,3 +1,12 @@
 export { YetterImageClient } from "./api.js";
 export * from "./types.js";
-export { yetter } from "./client.js";
+export { yetter } from "./client.js";
+
+// Explicitly export upload-related types for better discoverability
+export type {
+    UploadOptions,
+    GetUploadUrlRequest,
+    GetUploadUrlResponse,
+    UploadCompleteRequest,
+    UploadCompleteResponse,
+} from "./types.js";

package/src/types.ts

@@ -114,3 +114,79 @@ export interface YetterStream extends AsyncIterable<StreamEvent> {
     cancel(): Promise<void>; // Cancels the stream and attempts to cancel the underlying API request
     getRequestId(): string; // Helper to get the request ID associated with the stream
 }
+
+// ============= Upload-Related Types =============
+
+/**
+ * Options for yetter.uploadFile() and yetter.uploadBlob()
+ */
+export interface UploadOptions {
+    /** Optional callback for upload progress (0-100) */
+    onProgress?: (progress: number) => void;
+
+    /** Optional custom filename (browser File uploads) */
+    filename?: string;
+}
+
+/**
+ * Request to get presigned upload URL(s)
+ */
+export interface GetUploadUrlRequest {
+    /** Original filename with extension */
+    file_name: string;
+
+    /** MIME type (e.g., "image/jpeg") */
+    content_type: string;
+
+    /** File size in bytes */
+    size: number;
+}
+
+/**
+ * Response containing presigned URL(s) for upload
+ */
+export interface GetUploadUrlResponse {
+    /** Upload mode: "single" for small files, "multipart" for large files */
+    mode: "single" | "multipart";
+
+    /** S3 object key for tracking */
+    key: string;
+
+    /** Presigned PUT URL (single mode only) */
+    put_url?: string;
+
+    /** Size of each part in bytes (multipart mode only) */
+    part_size?: number;
+
+    /** Array of part URLs with part numbers (multipart mode only) */
+    part_urls?: Array<{
+        part_number: number;
+        url: string;
+    }>;
+}
+
+/**
+ * Request to notify upload completion
+ */
+export interface UploadCompleteRequest {
+    /** S3 object key from GetUploadUrlResponse */
+    key: string;
+}
+
+/**
+ * Response after successful upload completion
+ */
+export interface UploadCompleteResponse {
+    /** Public URL to access the uploaded file */
+    url: string;
+
+    /** S3 object key */
+    key: string;
+
+    /** Optional metadata */
+    metadata?: {
+        size: number;
+        content_type: string;
+        uploaded_at?: string;
+    };
+}