@visgate_ai/client 0.2.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visgate AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# @visgate_ai/client
+
+JavaScript/TypeScript SDK for the [Visgate API](https://visgateai.com) — one client for image and video generation across Fal, Replicate, and Runway.
+
+Works in Node.js (18+), browsers, and with React, Vite, Next.js, and vanilla JS.
+
+## Install
+
+```bash
+npm install @visgate_ai/client
+```
+
+## Quick Start
+
+```javascript
+import { Client } from "@visgate_ai/client";
+
+const client = new Client(); // reads VISGATE_API_KEY from env (Node)
+
+const result = await client.generate("a sunset over Istanbul");
+console.log(result.imageUrl, result.cost, result.provider);
+
+client.close();
+```
+
+With explicit API key:
+
+```javascript
+const client = new Client({ apiKey: "vg-..." });
+const result = await client.generate("a sunset", { model: "fal-ai/flux/schnell" });
+console.log(result.imageUrl);
+```
+
+## Features
+
+- **One client, three providers.** Fal, Replicate, and Runway behind a single API.
+- **Managed and BYOK modes.** Use Visgate-managed keys or bring your own.
+- **Promise-based API.** All methods return Promises; use `async/await` or `.then()`.
+- **Automatic retries.** Transient errors (429, 5xx) are retried with exponential backoff.
+- **Typed exceptions.** Catch `AuthenticationError`, `RateLimitError`, `ProviderError`, etc.
+- **TypeScript.** Full type definitions included.
+- **Framework-agnostic.** Use in vanilla JS, React, Vite, Next.js.
+- **Async generation.** Video/image async mode with `client.requests.get()` for status polling; usage and billing resources.
+
+## Authentication
+
+**Node.js:** Set `VISGATE_API_KEY` in the environment or pass `apiKey` in options.
+
+```bash
+export VISGATE_API_KEY="vg-..."
+```
+
+**Browser / Vite:** Pass `apiKey` in options (or use `import.meta.env.VITE_VISGATE_API_KEY` in Vite and pass it to the client).
+
+```javascript
+const client = new Client({ apiKey: "vg-..." });
+```
+
+### Production / proxy (recommended for browser apps)
+
+Do not put your Visgate API key in the client. Use a server-side proxy that adds the key:
+
+```javascript
+const client = new Client({ proxyUrl: "/api/visgate" });
+// No apiKey needed — the proxy adds Authorization on the server
+```
+
+Set `VISGATE_API_KEY` on the server. This repo includes a ready-made proxy package: **`server-proxy/`** (published as `@visgate_ai/server-proxy` on npm). See [server-proxy/README.md](server-proxy/README.md) for setup; or implement your own forward that injects the key.
+
+## BYOK (Bring Your Own Key)
+
+```javascript
+const client = new Client({
+  apiKey: "vg-...",
+  falKey: "fal_...",
+  replicateKey: "r8_...",
+  runwayKey: "rw_...",
+});
+```
+
+## API Reference
+
+### Image Generation
+
+```javascript
+// Quick generation (unified POST /generate)
+const result = await client.generate("a cat in space", { model: "fal-ai/flux/schnell" });
+console.log(result.status, result.imageUrl, result.cost);
+
+// Full control (POST /images/generate) — matches API ImageGenerateRequest
+const result = await client.images.generate("fal-ai/flux/schnell", "a cat in space", {
+  width: 1024,
+  height: 1024,
+  numImages: 1,
+  negativePrompt: null,
+  seed: null,
+  imageUrl: null,           // optional: input image for img2img
+  preferCache: true,       // use cache (exact or semantic match)
+  maxLatencyMs: null,      // optional: max acceptable latency (ms)
+  webhookUrl: null,        // optional: callback URL when done
+  callbackId: null,        // optional: id in callback payload
+});
+// result: id, status, images, model, provider, cost, cacheHit, cacheSource?, latencyMs, savedAmount?, marginPercent?, createdAt
+```
+
+### Video Generation
+
+Video generation can take several minutes. To **avoid 502** when the request takes longer than proxy/Cloudflare timeout, use **async mode** (`preferAsync: true`): the API returns 202 immediately, then poll `client.requests.get(requestId)` until completed.
+
+Use `VIDEO_MODEL_PRESETS` for provider model IDs (Fal, Replicate, Runway), or pass a model string (e.g. `fal-ai/veo3`, `replicate/lucataco/cogvideox-5b`, `runway/gen4_turbo`). For **image-to-video**, set `imageUrl` or `imageFile` in options.
+
+```javascript
+import { Client, VIDEO_MODEL_PRESETS } from "@visgate_ai/client";
+
+const client = new Client({ proxyUrl: "/api/visgate", timeout: 300_000 });
+
+// Sync (wait for result; may hit proxy timeout on long videos)
+const syncResult = await client.videos.generate(VIDEO_MODEL_PRESETS.fal, "waves on a beach", {
+  durationSeconds: 6,
+  skipGcsUpload: true,
+});
+console.log(syncResult.videoUrl, syncResult.cacheHit, syncResult.cost);
+
+// Async (recommended): returns 202, poll client.requests.get(requestId)
+const result = await client.videos.generate("fal-ai/veo3", "waves on a beach", {
+  durationSeconds: 6,
+  skipGcsUpload: true,   // faster; return provider URL directly
+  preferAsync: true,     // avoids 502 — returns 202, poll client.requests.get(requestId)
+  imageUrl: null,        // optional: input image for img2vid (or use imageFile)
+  webhookUrl: null,      // optional: callback URL when done
+  callbackId: null,      // optional: id in callback payload
+  params: {},            // optional: extra provider params
+});
+if (result.status === "accepted") {
+  let status = await client.requests.get(result.requestId);
+  while (status.status === "pending" || status.status === "processing") {
+    await new Promise((r) => setTimeout(r, 3000));
+    status = await client.requests.get(result.requestId);
+  }
+  console.log(status.status, status.outputUrl);
+} else {
+  console.log(result.videoUrl, result.cacheHit, result.status);
+}
+```
+
+On the server, set the proxy route’s `maxDuration` (e.g. 300 seconds) so the request is not cut off — see [server-proxy/README.md](server-proxy/README.md).
+
+### Async request status (Requests)
+
+After starting an async generation (video or image with `preferAsync: true`), poll the request status until completion:
+
+```javascript
+const status = await client.requests.get(result.requestId);
+// status: requestId, status ("pending" | "processing" | "completed" | "failed"),
+//         mediaType, provider, model, outputUrl, errorMessage, createdAt, completedAt
+```
+
+### Model Discovery
+
+```javascript
+const resp = await client.models.list({ provider: "fal", mediaType: "image", limit: 20 });
+for (const m of resp.models) console.log(m.id, m.name);
+
+const model = await client.models.get("fal-ai/flux/schnell");
+```
+
+### Usage and Billing
+
+```javascript
+const usage = await client.usage.get("month");
+console.log(usage.totalRequests, usage.totalBilledCost, usage.cacheHitRate, usage.avgLatency, usage.history);
+
+const logs = await client.usage.logs({ limit: 50 });
+const dashboard = await client.usage.dashboard("week");
+
+// Track download event (POST /usage/downloads)
+await client.usage.trackDownload("request-id", "https://...", { mediaType: "image" });
+```
+
+### Billing
+
+```javascript
+const stats = await client.billing.getStats();       // public stats
+const info = await client.billing.getInfo();         // org billing info (tier, balance, etc.)
+const pricing = await client.billing.getPricing();  // model pricing list
+await client.billing.checkout(10, "https://...", { customerEmail: "..." });
+await client.billing.updateSubscription("starter");
+```
+
+### Provider Management
+
+```javascript
+const keys = await client.providers.listKeys();
+const balances = await client.providers.balances();
+```
+
+### Health Check
+
+```javascript
+const health = await client.health();
+console.log(health.status);
+```
+
+## Error Handling
+
+```javascript
+import { Client, AuthenticationError, RateLimitError, ProviderError, ValidationError, VisgateError } from "@visgate_ai/client";
+
+const client = new Client({ apiKey: "vg-..." });
+
+try {
+  const result = await client.generate("a sunset");
+} catch (err) {
+  if (err instanceof AuthenticationError) console.error("Invalid API key");
+  else if (err instanceof RateLimitError) console.error("Rate limit", err.retryAfter);
+  else if (err instanceof ProviderError) console.error("Provider error", err.provider);
+  else if (err instanceof ValidationError) console.error("Validation", err.field);
+  else if (err instanceof VisgateError) console.error(err.message, err.errorCode);
+}
+```
+
+## Configuration
+
+| Option       | Default                     | Description                    |
+| ------------ | --------------------------- | ------------------------------ |
+| `apiKey`     | `process.env.VISGATE_API_KEY` | Visgate API key (optional when using `proxyUrl`) |
+| `proxyUrl`   | —                           | Server proxy URL; when set, no key or BYOK is sent |
+| `baseUrl`    | `https://visgateai.com/api/v1` | API base URL                   |
+| `timeout`    | `120000` (ms)               | Request timeout                |
+| `maxRetries` | `2`                         | Retries for 429 and 5xx        |
+| `falKey`     | —                           | Fal BYOK key                   |
+| `replicateKey` | —                         | Replicate BYOK key             |
+| `runwayKey`  | —                           | Runway BYOK key                |
+
+## AsyncClient
+
+For API parity with the Python SDK, `AsyncClient` is also exported; it has the same interface as `Client` (all methods return Promises).
+
+```javascript
+import { AsyncClient } from "@visgate_ai/client";
+
+const client = new AsyncClient();
+const result = await client.generate("a sunset");
+```
+
+## Repository structure
+
+- **`src/`** — @visgate_ai/client (client library): `generate`, `images`, `videos`, `models`, `requests` (async status), `usage`, `providers`, `billing`
+- **`server-proxy/`** — `@visgate_ai/server-proxy`: server-side proxy for Next.js and other Node runtimes. Install with `npm install @visgate_ai/server-proxy` or use locally from this repo.
+- **`examples/`** — Next.js, vanilla, and Vite examples
+
+## License
+
+MIT — see [LICENSE](LICENSE).