@yetter/client 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,220 @@
+# Yetter JS Client
+
+The Yetter JS Client provides a convenient way to interact with the Yetter API for image generation. It supports different modes of operation: subscribing to real-time updates, submitting jobs to a queue, and streaming events.
+
+## Installation
+
+```bash
+npm install @yetter/client
+```
+
+## Authentication
+
+The client requires a Yetter API key for authentication. Ensure you have the `YTR_API_KEY` environment variable set:
+
+```bash
+export YTR_API_KEY="your_api_key_here"
+```
+
+## 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).
+
+```typescript
+import { yetter } from "@yetter/client";
+```
+
+### 1. `yetter.subscribe()`
+
+This function submits an image generation request and long-polls for the result. It provides updates on the queue status and logs if requested.
+
+**Features:**
+- Submits a generation request.
+- Polls for status updates until the job is "COMPLETED" or "FAILED".
+- 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.
+
+**Example (from `examples/subscribe.ts`):**
+
+```typescript
+import { yetter } from "@yetter/client";
+
+async function main() {
+    const model = "ytr-ai/flux/dev"; // Replace with your desired model
+    try {
+        console.log("\n--- Starting Subscribe Test ---");
+        const result = await yetter.subscribe(model, {
+            input: {
+                prompt: "a vibrant coral reef, underwater photography",
+            },
+            logs: true,
+            onQueueUpdate: (update) => {
+                console.log(`[Queue Update] Status: ${update.status}, Position: ${update.queue_position}`);
+                if (update.status === "IN_PROGRESS" && update.logs) {
+                    console.log("Logs:");
+                    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") {
+                    console.error("Processing failed. Logs:", update.logs);
+                }
+            },
+        });
+
+        console.log("\n--- Subscribe Test Result ---");
+        console.log("Results:", result); // Contains image data, prompt, etc.
+
+    } catch (err: any) {
+        console.error("\n--- Subscribe Test Failed ---");
+        console.error("Error during subscribe:", err.message || err);
+        // ... error handling ...
+    }
+}
+
+main();
+```
+
+### 2. `yetter.stream()`
+
+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.
+
+**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.
+
+**Example (from `examples/stream.ts`):**
+
+```typescript
+import { yetter } from "@yetter/client"; // Adjust path as needed
+
+async function main() {
+    const model = "ytr-ai/flux/dev";
+    let streamRequestId = "";
+    try {
+        console.log("\n--- Starting Stream Test ---");
+        const streamInstance = await yetter.stream(model, {
+            input: {
+                prompt: "a bioluminescent forest at night, fantasy art",
+            },
+        });
+        streamRequestId = streamInstance.getRequestId();
+        console.log(`Stream initiated for Request ID: ${streamRequestId}`);
+
+        // Iterate over stream events
+        for await (const event of streamInstance) {
+            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}`));
+            }
+        }
+        console.log(`Stream for ${streamRequestId} finished iterating events.`);
+
+        // Wait for the final result from the done() method
+        const result = await streamInstance.done();
+        console.log("\n--- Stream Test Final Result ---");
+        console.log("Generated Images:", result.images);
+
+    } catch (err: any) {
+        console.error(`\n--- Stream Test Failed (Request ID: ${streamRequestId || 'UNKNOWN'}) ---`);
+        console.error("Error during stream test:", err.message || err);
+    }
+}
+
+main();
+```
+
+### 3. `yetter.queue`
+
+This namespace provides methods for managing jobs in a queue-based workflow. This is useful if you want to submit a job and check its status or retrieve its result later, without maintaining a persistent connection.
+
+#### `yetter.queue.submit(model, options)`
+Submits a job to the queue.
+
+-   **`model`**: The model ID (e.g., `"ytr-ai/flux/dev"`).
+-   **`options.input`**: An object containing the input parameters for the model (e.g., `{ prompt: "your prompt" }`).
+
+Returns a promise that resolves to an object containing `request_id`, `status`, and `queue_position`.
+
+#### `yetter.queue.status(model, options)`
+Checks the status of a previously submitted job.
+
+-   **`model`**: The model ID.
+-   **`options.requestId`**: The `request_id` obtained from `queue.submit()`.
+
+Returns a promise that resolves to an object containing the status data and `requestId`.
+
+#### `yetter.queue.result(model, options)`
+Retrieves the result of a completed job.
+
+-   **`model`**: The model ID.
+-   **`options.requestId`**: The `request_id` of the completed job.
+
+Returns a promise that resolves to an object containing the result data (e.g., images, prompt) and `requestId`.
+
+**Example (from `examples/submit.ts`):**
+
+```typescript
+import { yetter } from "@yetter/client";
+
+async function main() {
+    const model = "ytr-ai/flux/dev";
+    try {
+        console.log("\n--- Starting Queue Submit Test ---");
+        const { request_id } = await yetter.queue.submit(model, {
+            input: {
+                prompt: "a fluffy white kitten playing with a yarn ball",
+            },
+        });
+        console.log("Request ID:", request_id);
+
+        if (request_id) {
+            console.log(`\n--- Polling for status of Request ID: ${request_id} ---`);
+            // Polling logic:
+            let success = false;
+            const startTime = Date.now();
+            const timeoutMilliseconds = 3 * 60 * 1000; // 3 minutes
+            const pollIntervalMilliseconds = 10 * 1000; // Poll every 10 seconds
+
+            while (Date.now() - startTime < timeoutMilliseconds) {
+                const statusResult = await yetter.queue.status(model, { requestId: request_id });
+                const currentStatus = statusResult.data.status;
+                console.log(`[${new Date().toLocaleTimeString()}] Status: ${currentStatus}, QPos: ${statusResult.data.queue_position}`);
+
+                if (currentStatus === "COMPLETED") {
+                    const finalResult = await yetter.queue.result(model, { requestId: request_id });
+                    console.log("\n--- Get Result Test Succeeded ---");
+                    console.log("Image Data:", finalResult.data.images);
+                    success = true;
+                    break;
+                } else if (currentStatus === "FAILED") {
+                    console.error(`Request ${request_id} FAILED. Logs:`, statusResult.data.logs);
+                    break;
+                }
+                await new Promise(resolve => setTimeout(resolve, pollIntervalMilliseconds));
+            }
+            if (!success) console.error(`Polling Timed Out or Failed for ${request_id}`);
+        }
+    } catch (err: any) {
+        console.error("\n--- Queue Submit Test Failed ---", err.message);
+    }
+}
+
+main();
+```
+
+## 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.
+The `stream()` function's `done()` promise will reject on failure or premature closure, and iterating the stream might also throw if connection errors occur.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yetter/client",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "scripts": {
     "build": "tsc",