@yetter/client 0.0.12 → 0.0.14

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).
@@ -48,6 +96,7 @@ This function submits an image generation request and long-polls for the result.
 - 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`):**
 
@@ -97,11 +146,18 @@ This function submits an image generation request and returns an async iterable
 **Features:**
 
 * Initiates a request and establishes an SSE connection.
+* Automatically falls back to status polling if SSE transport repeatedly fails.
 * 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.
 
+**Transport options (`StreamOptions`):**
+
+* `disableSse?: boolean` - skip SSE and use polling only.
+* `pollIntervalMs?: number` - polling interval for fallback/forced polling (default: `2000`).
+* `sseMaxConsecutiveErrors?: number` - number of transport errors tolerated before fallback (default: `3`).
+
 **Events (`StreamEvent`):**
 Each event pushed by the stream is an object typically including:
 
@@ -199,11 +255,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) {
@@ -259,7 +315,7 @@ const uploadResult = await yetter.uploadFile("./input-image.jpg", {
 const result = await yetter.subscribe("ytr-ai/model/i2i", {
     input: {
         prompt: "Transform to anime style",
-        input_image_url: uploadResult.url,
+        image_url: [uploadResult.url],
     },
 });
 ```

package/dist/api.d.ts

@@ -4,6 +4,9 @@ export declare class YetterImageClient {
     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>;

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,67 +35,102 @@ 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,
         });
-        if (!res.ok) {
-            const errorText = await res.text();
-            throw new Error(`API error (${res.status}): ${errorText}`);
-        }
-        return (await res.json());
     }
     /**
      * Request presigned URL(s) for file upload
@@ -78,19 +138,14 @@ export class YetterImageClient {
      * @returns Presigned URL response with mode (single/multipart)
      */
     async getUploadUrl(body) {
-        const res = await fetch(`${this.endpoint}/uploads`, {
+        return this.requestJson(`${this.endpoint}/uploads`, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: this.apiKey,
-            },
+            headers: this.getAuthHeaders(),
             body: JSON.stringify(body),
+        }, {
+            maxRetries: 0,
+            errorPrefix: "Upload URL request failed",
         });
-        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
@@ -98,18 +153,13 @@ export class YetterImageClient {
      * @returns Uploaded file metadata with public URL
      */
     async uploadComplete(body) {
-        const res = await fetch(`${this.endpoint}/uploads/complete`, {
+        return this.requestJson(`${this.endpoint}/uploads/complete`, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: this.apiKey,
-            },
+            headers: this.getAuthHeaders(),
             body: JSON.stringify(body),
+        }, {
+            maxRetries: 0,
+            errorPrefix: "Upload completion failed",
         });
-        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,7 +1,32 @@
 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,56 +35,6 @@ 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;
 }