waterlight 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# Waterlight Node.js SDK
+
+OpenAI-compatible TypeScript/JavaScript client for the [Waterlight API](https://waterlight.ai). Zero dependencies — uses only the built-in `fetch` API.
+
+## Install
+
+```bash
+npm install waterlight
+```
+
+## Quick Start
+
+```typescript
+import { Waterlight } from 'waterlight';
+
+const client = new Waterlight({ apiKey: 'wl-...' });
+
+const response = await client.chat.completions.create({
+  model: 'mist-1-turbo',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+console.log(response.choices[0].message.content);
+```
+
+## Drop-in OpenAI Replacement
+
+```typescript
+// Before
+import OpenAI from 'openai';
+const client = new OpenAI({ apiKey: 'sk-...' });
+
+// After
+import { Waterlight } from 'waterlight';
+const client = new Waterlight({ apiKey: 'wl-...' });
+
+// Same API — no other code changes needed
+const response = await client.chat.completions.create({
+  model: 'mist-1-turbo',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+```
+
+## Streaming
+
+```typescript
+const stream = client.chat.completions.create({
+  model: 'mist-1-turbo',
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+}
+```
+
+## Tool Calling
+
+```typescript
+const response = await client.chat.completions.create({
+  model: 'mist-1-turbo',
+  messages: [{ role: 'user', content: "What's the weather in Austin?" }],
+  tools: [{
+    type: 'function',
+    function: {
+      name: 'get_weather',
+      description: 'Get current weather',
+      parameters: {
+        type: 'object',
+        properties: {
+          location: { type: 'string' },
+        },
+        required: ['location'],
+      },
+    },
+  }],
+});
+
+if (response.choices[0].message.tool_calls) {
+  for (const call of response.choices[0].message.tool_calls) {
+    console.log(call);
+  }
+}
+```
+
+## Embeddings
+
+```typescript
+const result = await client.embeddings.create({
+  input: 'Hello world',
+});
+console.log(result.data[0].embedding.length); // dimension count
+```
+
+## Models
+
+```typescript
+const models = await client.models.list();
+for (const model of models.data) {
+  console.log(model.id);
+}
+```
+
+## Billing
+
+```typescript
+import { Waterlight, BillingInfo } from 'waterlight';
+
+const billing: BillingInfo = await client.billing.get();
+console.log(billing); // plan, spent_usd, balance, limits
+```
+
+## Error Handling
+
+```typescript
+import {
+  Waterlight,
+  AuthenticationError,
+  RateLimitError,
+  InsufficientCreditsError,
+  APIError,
+} from 'waterlight';
+
+try {
+  const response = await client.chat.completions.create({
+    model: 'mist-1-turbo',
+    messages: [{ role: 'user', content: 'Hello' }],
+  });
+} catch (e) {
+  if (e instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (e instanceof RateLimitError) {
+    console.error('Rate limited');
+  } else if (e instanceof InsufficientCreditsError) {
+    console.error('Add credits at https://waterlight.ai');
+  } else if (e instanceof APIError) {
+    console.error(`API error ${e.statusCode}: ${e.message}`);
+  }
+}
+```
+
+## Configuration
+
+| Parameter | Env Var | Default |
+|-----------|---------|---------|
+| `apiKey` | `WATERLIGHT_API_KEY` | — (required) |
+| `baseUrl` | `WATERLIGHT_BASE_URL` | `https://api.waterlight.ai` |
+
+```typescript
+// Using env var
+process.env.WATERLIGHT_API_KEY = 'wl-...';
+const client = new Waterlight(); // picks up from env
+
+// Explicit
+const client = new Waterlight({
+  apiKey: 'wl-...',
+  baseUrl: 'https://custom.endpoint.com',
+});
+```
+
+## Requirements
+
+- Node.js 18+ (uses built-in `fetch`)
+- TypeScript 5+ (for type definitions)
+- Zero runtime dependencies
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,103 @@
+import type { ChatCompletionCreateParams, ChatCompletion, EmbeddingCreateParams, EmbeddingResponse, ModelList } from './types';
+import { Stream } from './streaming';
+/** Chat completions namespace. */
+declare class Completions {
+    private readonly client;
+    constructor(client: Waterlight);
+    /**
+     * Create a chat completion.
+     *
+     * @param params - Chat completion parameters
+     * @returns ChatCompletion if stream is false/undefined, Stream if stream is true
+     */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): Stream;
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletion> | Stream;
+}
+/** Chat namespace — mirrors openai.chat. */
+declare class Chat {
+    readonly completions: Completions;
+    constructor(client: Waterlight);
+}
+/** Embeddings namespace. */
+declare class Embeddings {
+    private readonly client;
+    constructor(client: Waterlight);
+    create(params: EmbeddingCreateParams): Promise<EmbeddingResponse>;
+}
+/** Models namespace. */
+declare class Models {
+    private readonly client;
+    constructor(client: Waterlight);
+    list(): Promise<ModelList>;
+}
+/** Billing info response. */
+export interface BillingInfo {
+    plan: string;
+    billing_mode: string;
+    spent_usd: number;
+    total_requests: number;
+    total_tokens: number;
+    rpm_limit: number;
+    tpm_limit: number;
+    balance_usd?: number;
+    min_deposit_usd?: number;
+    budget_usd?: number;
+    remaining_usd?: number;
+    monthly_usd?: number;
+    daily_limit?: number;
+    daily_used?: number;
+    allowed_models?: string[];
+}
+/** Billing namespace — Waterlight-specific (not in OpenAI SDK). */
+declare class Billing {
+    private readonly client;
+    constructor(client: Waterlight);
+    get(): Promise<BillingInfo>;
+}
+/**
+ * Waterlight API client — OpenAI-compatible interface.
+ *
+ * @example
+ * ```ts
+ * import { Waterlight } from 'waterlight';
+ *
+ * const client = new Waterlight({ apiKey: 'wl-...' });
+ *
+ * // Non-streaming
+ * const response = await client.chat.completions.create({
+ *   model: 'mist-1-turbo',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * console.log(response.choices[0].message.content);
+ *
+ * // Streaming
+ * const stream = client.chat.completions.create({
+ *   model: 'mist-1-turbo',
+ *   messages: [{ role: 'user', content: 'Tell me a story' }],
+ *   stream: true,
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * ```
+ */
+export declare class Waterlight {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly chat: Chat;
+    readonly embeddings: Embeddings;
+    readonly models: Models;
+    readonly billing: Billing;
+    constructor(opts?: {
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    private _post;
+    private _get;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 errObj = body?.error;
+    const msg = (typeof errObj === 'object' ? errObj?.message : errObj) ?? 'Request failed';
+    if (status === 401)
+        throw new errors_1.AuthenticationError(msg);
+    if (status === 429)
+        throw new errors_1.RateLimitError(msg);
+    if (status === 402)
+        throw new errors_1.InsufficientCreditsError(msg);
+    throw new errors_1.APIError(msg, status);
+}
+/** Chat completions namespace. */
+class Completions {
+    constructor(client) {
+        this.client = client;
+    }
+    create(params) {
+        if (params.stream) {
+            return new streaming_1.Stream(`${this.client.baseUrl}/v1/chat/completions`, this.client.apiKey, params);
+        }
+        return this.client['_post']('/v1/chat/completions', { ...params, stream: false });
+    }
+}
+/** Chat namespace — mirrors openai.chat. */
+class Chat {
+    constructor(client) {
+        this.completions = new Completions(client);
+    }
+}
+/** Embeddings namespace. */
+class Embeddings {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(params) {
+        return this.client['_post']('/v1/embeddings', params);
+    }
+}
+/** Models namespace. */
+class Models {
+    constructor(client) {
+        this.client = client;
+    }
+    async list() {
+        return this.client['_get']('/v1/models');
+    }
+}
+/** Billing namespace — Waterlight-specific (not in OpenAI SDK). */
+class Billing {
+    constructor(client) {
+        this.client = client;
+    }
+    async get() {
+        return this.client['_get']('/v1/billing');
+    }
+}
+/**
+ * Waterlight API client — OpenAI-compatible interface.
+ *
+ * @example
+ * ```ts
+ * import { Waterlight } from 'waterlight';
+ *
+ * const client = new Waterlight({ apiKey: 'wl-...' });
+ *
+ * // Non-streaming
+ * const response = await client.chat.completions.create({
+ *   model: 'mist-1-turbo',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * console.log(response.choices[0].message.content);
+ *
+ * // Streaming
+ * const stream = client.chat.completions.create({
+ *   model: 'mist-1-turbo',
+ *   messages: [{ role: 'user', content: 'Tell me a story' }],
+ *   stream: true,
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * ```
+ */
+class Waterlight {
+    constructor(opts = {}) {
+        const key = opts.apiKey ?? process.env.WATERLIGHT_API_KEY;
+        if (!key) {
+            throw new errors_1.WaterlightError('API key required. Pass apiKey or set WATERLIGHT_API_KEY env var. ' +
+                'Get your key at https://waterlight.ai');
+        }
+        this.apiKey = key;
+        this.baseUrl = (opts.baseUrl ?? process.env.WATERLIGHT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        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;
+    }
+    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;
+    }
+}
+exports.Waterlight = Waterlight;

package/dist/errors.d.ts

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

package/dist/errors.js

@@ -0,0 +1,39 @@
+"use strict";
+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) {
+        super(message);
+        this.name = 'WaterlightError';
+        this.status = status;
+    }
+}
+exports.WaterlightError = WaterlightError;
+class AuthenticationError extends WaterlightError {
+    constructor(message) {
+        super(message, 401);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class RateLimitError extends WaterlightError {
+    constructor(message) {
+        super(message, 429);
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;
+class InsufficientCreditsError extends WaterlightError {
+    constructor(message) {
+        super(message, 402);
+        this.name = 'InsufficientCreditsError';
+    }
+}
+exports.InsufficientCreditsError = InsufficientCreditsError;
+class APIError extends WaterlightError {
+    constructor(message, status) {
+        super(message, status);
+        this.name = 'APIError';
+    }
+}
+exports.APIError = APIError;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Waterlight } from './client';
+export type { BillingInfo } from './client';
+export * from './types';
+export * from './errors';
+export { Stream } from './streaming';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stream = exports.Waterlight = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Waterlight", { enumerable: true, get: function () { return client_1.Waterlight; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);
+var streaming_1 = require("./streaming");
+Object.defineProperty(exports, "Stream", { enumerable: true, get: function () { return streaming_1.Stream; } });

package/dist/streaming.d.ts

@@ -0,0 +1,17 @@
+import type { ChatCompletionChunk } from './types';
+/**
+ * SSE stream that implements AsyncIterable<ChatCompletionChunk>.
+ *
+ * Usage:
+ *   const stream = client.chat.completions.create({ ..., stream: true });
+ *   for await (const chunk of stream) {
+ *     process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ *   }
+ */
+export declare class Stream implements AsyncIterable<ChatCompletionChunk> {
+    private readonly url;
+    private readonly apiKey;
+    private readonly body;
+    constructor(url: string, apiKey: string, params: object);
+    [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk>;
+}

package/dist/streaming.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stream = void 0;
+const errors_1 = require("./errors");
+/**
+ * SSE stream that implements AsyncIterable<ChatCompletionChunk>.
+ *
+ * Usage:
+ *   const stream = client.chat.completions.create({ ..., stream: true });
+ *   for await (const chunk of stream) {
+ *     process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ *   }
+ */
+class Stream {
+    constructor(url, apiKey, params) {
+        this.url = url;
+        this.apiKey = apiKey;
+        this.body = JSON.stringify({ ...params, stream: true });
+    }
+    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,
+        });
+        if (!res.ok) {
+            let errMsg = '';
+            try {
+                errMsg = await res.text();
+            }
+            catch { }
+            throw new errors_1.WaterlightError(`Streaming error: ${res.status} ${errMsg}`, res.status);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete SSE events (double newline delimited)
+                let boundary;
+                while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+                    const rawEvent = buffer.slice(0, boundary);
+                    buffer = buffer.slice(boundary + 2);
+                    for (const line of rawEvent.split('\n')) {
+                        if (!line.startsWith('data:'))
+                            continue;
+                        const data = line.slice(5).trim();
+                        if (data === '[DONE]')
+                            return;
+                        try {
+                            yield JSON.parse(data);
+                        }
+                        catch {
+                            // skip malformed chunks
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+exports.Stream = Stream;

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+export interface Message {
+    role: Role;
+    content: string | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+export interface FunctionCall {
+    name: string;
+    arguments: string;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: FunctionCall;
+}
+export interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export type ToolChoice = 'none' | 'auto' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+export interface ChatCompletionCreateParams {
+    model: string;
+    messages: Message[];
+    stream?: boolean;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+}
+export interface Choice {
+    index: number;
+    message: Message;
+    finish_reason: string | null;
+}
+export interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface ChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: Choice[];
+    usage: Usage;
+}
+export interface Delta {
+    role?: Role;
+    content?: string | null;
+    tool_calls?: ToolCall[];
+}
+export interface StreamChoice {
+    index: number;
+    delta: Delta;
+    finish_reason: string | null;
+}
+export interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: StreamChoice[];
+}
+export interface EmbeddingCreateParams {
+    input: string | string[];
+    model?: string;
+    encoding_format?: string;
+}
+export interface Embedding {
+    object: 'embedding';
+    index: number;
+    embedding: number[];
+}
+export interface EmbeddingResponse {
+    object: 'list';
+    data: Embedding[];
+    model: string;
+    usage: Usage;
+}
+export interface Model {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+}
+export interface ModelList {
+    object: 'list';
+    data: Model[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "waterlight",
+  "version": "0.1.0",
+  "description": "OpenAI-compatible SDK for the Waterlight API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "openai",
+    "waterlight",
+    "ai",
+    "llm",
+    "sdk",
+    "typescript"
+  ],
+  "license": "MIT",
+  "homepage": "https://waterlight.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/waterlight-ai/waterlight-node"
+  }
+}