@yetter/client 0.0.11 → 0.0.13

package/README.md

@@ -8,6 +8,16 @@ The Yetter JS Client provides a convenient way to interact with the Yetter API f
 npm install @yetter/client
 ```
 
+## Testing
+
+Run the local test suite:
+
+```bash
+npm test
+```
+
+Tests are automatically omitted from npm releases because `package.json` uses a `files` whitelist (`dist`, `README.md`).
+
 ## Authentication
 
 The client requires a Yetter API key for authentication. Ensure you have the `YTR_API_KEY` or `REACT_APP_YTR_API_KEY` environment variable set:
@@ -30,6 +40,44 @@ yetter.configure({
 
 If `yetter.configure()` is used, it will override any API key found in environment variables for subsequent API calls. If neither environment variables are set nor `yetter.configure()` is called with an API key, an error will be thrown when attempting to make an API call.
 
+## Instance Client (Recommended for Concurrent Apps)
+
+For server or multi-tenant workloads, prefer creating isolated client instances instead of sharing global static state.
+
+```typescript
+import { YetterClient } from "@yetter/client";
+
+const teamAClient = new YetterClient({ apiKey: process.env.TEAM_A_YTR_API_KEY! });
+const teamBClient = new YetterClient({ apiKey: process.env.TEAM_B_YTR_API_KEY! });
+
+const result = await teamAClient.subscribe("ytr-ai/qwen/image-edit/i2i", {
+  input: {
+    prompt: "Transform this image to watercolor painting style",
+    image_url: ["https://example.com/input.jpg"],
+    num_inference_steps: 28,
+  },
+});
+```
+
+## Running i2i Example Scripts
+
+For image-to-image models (such as `ytr-ai/qwen/image-edit/i2i`), provide both a prompt and an input image.
+
+```bash
+export YTR_API_KEY="your_api_key_here"
+export YTR_MODEL="ytr-ai/qwen/image-edit/i2i"
+export YTR_IMAGE_PATH="./bowow2.jpeg"
+export YTR_PROMPT="Transform this image to watercolor painting style"
+```
+
+Then run one of:
+
+```bash
+npm run test:submit
+npm run test:subscribe
+npm run test:stream
+```
+
 ## Core Functionalities
 
 The client is available via the `yetter` object imported from `yetter-js` (or the relevant path to `client.js`/`client.ts` if used directly).
@@ -44,10 +92,11 @@ 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.
+- Optional `pollIntervalMs` to control status polling interval (default: 2000ms).
 
 **Example (from `examples/subscribe.ts`):**
 
@@ -71,7 +120,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 +144,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 +176,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 +188,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);
@@ -197,11 +248,11 @@ async function main() {
         console.log("Request ID:", request_id);
 
         if (request_id) {
-            console.log(`\n--- Polling for status of Request ID: ${request_id} ---`);
+            console.log(`\n--- Polling for status of Request ID: ${request_id} (10-minute timeout) ---`);
             // Polling logic:
             let success = false;
             const startTime = Date.now();
-            const timeoutMilliseconds = 3 * 60 * 1000; // 3 minutes
+            const timeoutMilliseconds = 10 * 60 * 1000; // 10 minutes
             const pollIntervalMilliseconds = 10 * 1000; // Poll every 10 seconds
 
             while (Date.now() - startTime < timeoutMilliseconds) {
@@ -215,7 +266,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 +282,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",
+        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,11 +1,26 @@
-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;
     constructor(options: ClientOptions);
     getApiEndpoint(): string;
+    private getAuthHeaders;
+    private readErrorBody;
+    private requestJson;
     generate(body: GenerateRequest): Promise<GenerateResponse>;
     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

@@ -1,4 +1,29 @@
 import fetch from "cross-fetch";
+const DEFAULT_TIMEOUT_MS = 30000;
+const MAX_RETRY_DELAY_MS = 5000;
+const BASE_RETRY_DELAY_MS = 300;
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isAbortError(error) {
+    return (error === null || error === void 0 ? void 0 : error.name) === "AbortError";
+}
+function isLikelyNetworkError(error) {
+    if (!error) {
+        return false;
+    }
+    if (error instanceof TypeError) {
+        return true;
+    }
+    const message = String(error.message || "");
+    return /(ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|NetworkError|network request failed)/i.test(message);
+}
+function getRetryDelayMs(attempt) {
+    const backoff = Math.min(MAX_RETRY_DELAY_MS, BASE_RETRY_DELAY_MS * (2 ** attempt));
+    const jitter = Math.floor(Math.random() * 150);
+    return backoff + jitter;
+}
 export class YetterImageClient {
     constructor(options) {
         if (!options.apiKey) {
@@ -10,66 +35,131 @@ export class YetterImageClient {
     getApiEndpoint() {
         return this.endpoint;
     }
+    getAuthHeaders() {
+        return {
+            "Content-Type": "application/json",
+            Authorization: this.apiKey,
+        };
+    }
+    async readErrorBody(res) {
+        try {
+            const text = await res.text();
+            return text || res.statusText || "Unknown API error";
+        }
+        catch {
+            return res.statusText || "Unknown API error";
+        }
+    }
+    async requestJson(url, init, options = {}) {
+        var _a, _b, _c;
+        const maxRetries = (_a = options.maxRetries) !== null && _a !== void 0 ? _a : 0;
+        const timeoutMs = (_b = options.timeoutMs) !== null && _b !== void 0 ? _b : DEFAULT_TIMEOUT_MS;
+        const errorPrefix = (_c = options.errorPrefix) !== null && _c !== void 0 ? _c : "API error";
+        for (let attempt = 0;; attempt += 1) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetch(url, {
+                    ...init,
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    const errorText = await this.readErrorBody(res);
+                    const shouldRetry = attempt < maxRetries && RETRYABLE_STATUS_CODES.has(res.status);
+                    if (shouldRetry) {
+                        await sleep(getRetryDelayMs(attempt));
+                        continue;
+                    }
+                    throw new Error(`${errorPrefix} (${res.status}): ${errorText}`);
+                }
+                return (await res.json());
+            }
+            catch (error) {
+                const retryableNetworkError = isAbortError(error) || isLikelyNetworkError(error);
+                const shouldRetry = attempt < maxRetries && retryableNetworkError;
+                if (shouldRetry) {
+                    await sleep(getRetryDelayMs(attempt));
+                    continue;
+                }
+                if (isAbortError(error)) {
+                    throw new Error(`${errorPrefix}: request timed out after ${timeoutMs}ms`);
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+    }
     async generate(body) {
+        if (!body.model) {
+            throw new Error("`model` is required in generate request body");
+        }
         const url = `${this.endpoint}/${body.model}`;
-        const res = await fetch(url, {
+        return this.requestJson(url, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: this.apiKey,
-            },
+            headers: this.getAuthHeaders(),
             body: JSON.stringify(body),
+        }, {
+            maxRetries: 0,
         });
-        if (!res.ok) {
-            const errorText = await res.text();
-            throw new Error(`API error (${res.status}): ${errorText}`);
-        }
-        return (await res.json());
     }
     async getStatus(body) {
         const url = new URL(body.url);
         if (body.logs) {
             url.searchParams.append('logs', '1');
         }
-        const res = await fetch(url.toString(), {
+        return this.requestJson(url.toString(), {
             method: "GET",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: this.apiKey,
-            },
+            headers: this.getAuthHeaders(),
+        }, {
+            maxRetries: 4,
         });
-        if (!res.ok) {
-            const errorText = await res.text();
-            throw new Error(`API error (${res.status}): ${errorText}`);
-        }
-        return (await res.json());
     }
     async cancel(body) {
-        const res = await fetch(body.url, {
+        return this.requestJson(body.url, {
             method: "PUT",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: this.apiKey,
-            },
+            headers: this.getAuthHeaders(),
+        }, {
+            maxRetries: 3,
         });
-        if (!res.ok) {
-            const errorText = await res.text();
-            throw new Error(`API error (${res.status}): ${errorText}`);
-        }
-        return (await res.json());
     }
     async getResponse(body) {
-        const res = await fetch(body.url, {
+        return this.requestJson(body.url, {
             method: "GET",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: this.apiKey,
-            },
+            headers: this.getAuthHeaders(),
+        }, {
+            maxRetries: 4,
+        });
+    }
+    /**
+     * Request presigned URL(s) for file upload
+     * @param body Upload request parameters
+     * @returns Presigned URL response with mode (single/multipart)
+     */
+    async getUploadUrl(body) {
+        return this.requestJson(`${this.endpoint}/uploads`, {
+            method: "POST",
+            headers: this.getAuthHeaders(),
+            body: JSON.stringify(body),
+        }, {
+            maxRetries: 0,
+            errorPrefix: "Upload URL request failed",
+        });
+    }
+    /**
+     * Notify server that upload is complete
+     * @param body Completion request with S3 key
+     * @returns Uploaded file metadata with public URL
+     */
+    async uploadComplete(body) {
+        return this.requestJson(`${this.endpoint}/uploads/complete`, {
+            method: "POST",
+            headers: this.getAuthHeaders(),
+            body: JSON.stringify(body),
+        }, {
+            maxRetries: 0,
+            errorPrefix: "Upload completion failed",
         });
-        if (!res.ok) {
-            const errorText = await res.text();
-            throw new Error(`API error (${res.status}): ${errorText}`);
-        }
-        return (await res.json());
     }
 }

package/dist/client.d.ts

@@ -1,7 +1,32 @@
-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 YetterClient {
+    private apiKey;
+    private endpoint;
+    constructor(options?: Partial<ClientOptions>);
+    private setApiKey;
+    private assertApiKeyConfigured;
+    private createApiClient;
+    private getUploadTimeoutMs;
+    private putWithTimeout;
+    configure(options: ClientOptions): void;
+    subscribe(model: string, options: SubscribeOptions): Promise<GetResponseResponse>;
+    readonly queue: {
+        submit: (model: string, options: SubmitQueueOptions) => Promise<GenerateResponse>;
+        status: (model: string, options: StatusOptions) => Promise<StatusResponse>;
+        result: (model: string, options: GetResultOptions) => Promise<GetResultResponse>;
+    };
+    stream(model: string, options: StreamOptions): Promise<YetterStream>;
+    uploadFile(fileOrPath: string | File | Blob, options?: UploadOptions): Promise<UploadCompleteResponse>;
+    uploadBlob(file: File | Blob, options?: UploadOptions): Promise<UploadCompleteResponse>;
+    private _uploadFromPath;
+    private _uploadFromBlob;
+    private _uploadFileSingle;
+    private _uploadFileMultipart;
+    private _uploadBlobSingle;
+    private _uploadBlobMultipart;
+}
 export declare class yetter {
-    private static apiKey;
-    private static endpoint;
+    private static client;
     static configure(options: ClientOptions): void;
     static subscribe(model: string, options: SubscribeOptions): Promise<GetResponseResponse>;
     static queue: {
@@ -10,4 +35,6 @@ export declare class yetter {
         result: (model: string, options: GetResultOptions) => Promise<GetResultResponse>;
     };
     static stream(model: string, options: StreamOptions): Promise<YetterStream>;
+    static uploadFile(fileOrPath: string | File | Blob, options?: UploadOptions): Promise<UploadCompleteResponse>;
+    static uploadBlob(file: File | Blob, options?: UploadOptions): Promise<UploadCompleteResponse>;
 }