waterlight 0.1.0 → 0.2.0

package/README.md

@@ -145,6 +145,8 @@ try {
 |-----------|---------|---------|
 | `apiKey` | `WATERLIGHT_API_KEY` | — (required) |
 | `baseUrl` | `WATERLIGHT_BASE_URL` | `https://api.waterlight.ai` |
+| `timeout` | — | `120000` (ms) |
+| `maxRetries` | — | `2` |
 
 ```typescript
 // Using env var
@@ -155,6 +157,8 @@ const client = new Waterlight(); // picks up from env
 const client = new Waterlight({
   apiKey: 'wl-...',
   baseUrl: 'https://custom.endpoint.com',
+  timeout: 60_000,      // 60s timeout
+  maxRetries: 3,         // retry 429/5xx up to 3 times
 });
 ```
 

package/dist/client.d.ts

@@ -89,6 +89,8 @@ declare class Billing {
 export declare class Waterlight {
     readonly apiKey: string;
     readonly baseUrl: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
     readonly chat: Chat;
     readonly embeddings: Embeddings;
     readonly models: Models;
@@ -96,8 +98,11 @@ export declare class Waterlight {
     constructor(opts?: {
         apiKey?: string;
         baseUrl?: string;
+        timeout?: number;
+        maxRetries?: number;
     });
     private _post;
     private _get;
+    private _request;
 }
 export {};

package/dist/client.js

@@ -4,16 +4,26 @@ exports.Waterlight = void 0;
 const errors_1 = require("./errors");
 const streaming_1 = require("./streaming");
 const DEFAULT_BASE_URL = 'https://api.waterlight.ai';
-function handleError(status, body) {
+const DEFAULT_TIMEOUT = 120000;
+const DEFAULT_MAX_RETRIES = 2;
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function handleError(status, body, headers) {
     const errObj = body?.error;
     const msg = (typeof errObj === 'object' ? errObj?.message : errObj) ?? 'Request failed';
+    const requestId = headers?.get('x-request-id') ?? undefined;
     if (status === 401)
-        throw new errors_1.AuthenticationError(msg);
-    if (status === 429)
-        throw new errors_1.RateLimitError(msg);
+        throw new errors_1.AuthenticationError(msg, requestId);
+    if (status === 429) {
+        const ra = headers?.get('retry-after');
+        const retryAfter = ra ? parseFloat(ra) : undefined;
+        throw new errors_1.RateLimitError(msg, retryAfter, requestId);
+    }
     if (status === 402)
-        throw new errors_1.InsufficientCreditsError(msg);
-    throw new errors_1.APIError(msg, status);
+        throw new errors_1.InsufficientCreditsError(msg, requestId);
+    throw new errors_1.APIError(msg, status, requestId);
 }
 /** Chat completions namespace. */
 class Completions {
@@ -22,7 +32,7 @@ class Completions {
     }
     create(params) {
         if (params.stream) {
-            return new streaming_1.Stream(`${this.client.baseUrl}/v1/chat/completions`, this.client.apiKey, params);
+            return new streaming_1.Stream(`${this.client.baseUrl}/v1/chat/completions`, this.client.apiKey, params, this.client.timeout);
         }
         return this.client['_post']('/v1/chat/completions', { ...params, stream: false });
     }
@@ -96,37 +106,59 @@ class Waterlight {
         }
         this.apiKey = key;
         this.baseUrl = (opts.baseUrl ?? process.env.WATERLIGHT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
         this.chat = new Chat(this);
         this.embeddings = new Embeddings(this);
         this.models = new Models(this);
         this.billing = new Billing(this);
     }
     async _post(path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json',
-                'User-Agent': 'waterlight-node/0.1.0',
-            },
-            body: JSON.stringify(body),
-        });
-        const data = await res.json();
-        if (!res.ok)
-            handleError(res.status, data);
-        return data;
+        return this._request('POST', path, body);
     }
     async _get(path) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'User-Agent': 'waterlight-node/0.1.0',
-            },
-        });
-        const data = await res.json();
-        if (!res.ok)
-            handleError(res.status, data);
-        return data;
+        return this._request('GET', path);
+    }
+    async _request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        let attempt = 0;
+        while (true) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeout);
+            try {
+                const res = await fetch(url, {
+                    method,
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        ...(body ? { 'Content-Type': 'application/json' } : {}),
+                        'User-Agent': 'waterlight-node/0.2.0',
+                    },
+                    ...(body ? { body: JSON.stringify(body) } : {}),
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (!res.ok) {
+                    if (RETRYABLE_STATUS.has(res.status) && attempt < this.maxRetries) {
+                        const retryAfter = res.headers.get('retry-after');
+                        const delay = retryAfter ? parseFloat(retryAfter) * 1000 : 500 * 2 ** attempt;
+                        await sleep(delay);
+                        attempt++;
+                        continue;
+                    }
+                    const data = await res.json().catch(() => ({}));
+                    handleError(res.status, data, res.headers);
+                }
+                return await res.json();
+            }
+            catch (e) {
+                clearTimeout(timer);
+                if (e instanceof errors_1.WaterlightError)
+                    throw e;
+                if (e?.name === 'AbortError')
+                    throw new errors_1.APIError('Request timed out', 408);
+                throw new errors_1.APIError(`Network error: ${e?.message ?? e}`, 0);
+            }
+        }
     }
 }
 exports.Waterlight = Waterlight;

package/dist/errors.d.ts

@@ -1,16 +1,18 @@
 export declare class WaterlightError extends Error {
     readonly status?: number;
-    constructor(message: string, status?: number);
+    readonly requestId?: string;
+    constructor(message: string, status?: number, requestId?: string);
 }
 export declare class AuthenticationError extends WaterlightError {
-    constructor(message: string);
+    constructor(message: string, requestId?: string);
 }
 export declare class RateLimitError extends WaterlightError {
-    constructor(message: string);
+    readonly retryAfter?: number;
+    constructor(message: string, retryAfter?: number, requestId?: string);
 }
 export declare class InsufficientCreditsError extends WaterlightError {
-    constructor(message: string);
+    constructor(message: string, requestId?: string);
 }
 export declare class APIError extends WaterlightError {
-    constructor(message: string, status?: number);
+    constructor(message: string, status?: number, requestId?: string);
 }

package/dist/errors.js

@@ -2,37 +2,39 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APIError = exports.InsufficientCreditsError = exports.RateLimitError = exports.AuthenticationError = exports.WaterlightError = void 0;
 class WaterlightError extends Error {
-    constructor(message, status) {
+    constructor(message, status, requestId) {
         super(message);
         this.name = 'WaterlightError';
         this.status = status;
+        this.requestId = requestId;
     }
 }
 exports.WaterlightError = WaterlightError;
 class AuthenticationError extends WaterlightError {
-    constructor(message) {
-        super(message, 401);
+    constructor(message, requestId) {
+        super(message, 401, requestId);
         this.name = 'AuthenticationError';
     }
 }
 exports.AuthenticationError = AuthenticationError;
 class RateLimitError extends WaterlightError {
-    constructor(message) {
-        super(message, 429);
+    constructor(message, retryAfter, requestId) {
+        super(message, 429, requestId);
         this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
     }
 }
 exports.RateLimitError = RateLimitError;
 class InsufficientCreditsError extends WaterlightError {
-    constructor(message) {
-        super(message, 402);
+    constructor(message, requestId) {
+        super(message, 402, requestId);
         this.name = 'InsufficientCreditsError';
     }
 }
 exports.InsufficientCreditsError = InsufficientCreditsError;
 class APIError extends WaterlightError {
-    constructor(message, status) {
-        super(message, status);
+    constructor(message, status, requestId) {
+        super(message, status, requestId);
         this.name = 'APIError';
     }
 }

package/dist/streaming.d.ts

@@ -12,6 +12,7 @@ export declare class Stream implements AsyncIterable<ChatCompletionChunk> {
     private readonly url;
     private readonly apiKey;
     private readonly body;
-    constructor(url: string, apiKey: string, params: object);
+    private readonly timeout;
+    constructor(url: string, apiKey: string, params: object, timeout?: number);
     [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk>;
 }

package/dist/streaming.js

@@ -12,21 +12,35 @@ const errors_1 = require("./errors");
  *   }
  */
 class Stream {
-    constructor(url, apiKey, params) {
+    constructor(url, apiKey, params, timeout = 120000) {
         this.url = url;
         this.apiKey = apiKey;
         this.body = JSON.stringify({ ...params, stream: true });
+        this.timeout = timeout;
     }
     async *[Symbol.asyncIterator]() {
-        const res = await fetch(this.url, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json',
-                'Accept': 'text/event-stream',
-            },
-            body: this.body,
-        });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        let res;
+        try {
+            res = await fetch(this.url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'Accept': 'text/event-stream',
+                    'User-Agent': 'waterlight-node/0.2.0',
+                },
+                body: this.body,
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            clearTimeout(timer);
+            if (e?.name === 'AbortError')
+                throw new errors_1.APIError('Stream request timed out', 408);
+            throw new errors_1.APIError(`Network error: ${e?.message ?? e}`, 0);
+        }
         if (!res.ok) {
             let errMsg = '';
             try {
@@ -66,6 +80,7 @@ class Stream {
             }
         }
         finally {
+            clearTimeout(timer);
             reader.releaseLock();
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waterlight",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenAI-compatible SDK for the Waterlight API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",