babysea 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) BabySea, Inc.
+
+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,473 @@
+# BabySea
+
+Official TypeScript SDK for the [BabySea API](https://babysea.ai). BabySea offers one API for image and video generation across multiple AI inference providers, with automatic failover and a unified schema.
+
+[![npm version](./badges/version.svg)](https://www.npmjs.com/package/babysea) [![license](./badges/license.svg)](./LICENSE) [![npm type definitions](./badges/types.svg)](https://www.typescriptlang.org/) [![node](./badges/node.svg)](https://nodejs.org/en/about/previous-releases)
+
+- **Zero dependencies** - pure `fetch` and `crypto.subtle`, works everywhere
+- **Isomorphic** - Node 18+, Edge runtimes (Vercel, Cloudflare Workers), browsers
+- **ESM + CJS** dual build with full TypeScript types
+- **Auto-retry** with exponential backoff and `Retry-After` support
+- **Typed errors** - structured BSE error codes, retry flags, rate limit info
+
+---
+
+## Installation
+
+```bash
+npm install babysea
+# or
+pnpm add babysea
+# or
+yarn add babysea
+```
+
+---
+
+## Quick Start
+
+```ts
+import { BabySea } from 'babysea';
+
+const client = new BabySea({
+  apiKey: 'bye_...',
+  region: 'us', // 'us' | 'eu'
+});
+
+// Preview cost before generating
+const est = await client.estimate('{model_identifier}', 2);
+console.log(est.data.credit_balance_can_afford); // true
+console.log(est.data.cost_total_consumed);       // 0.102
+
+// Generate an image
+const result = await client.generate('{model_identifier}', {
+  generation_prompt: 'A cute baby seal on the beach at golden hour',
+  generation_ratio: '16:9',
+  generation_output_format: 'png',
+  generation_output_number: 1,
+});
+
+console.log(result.data.generation_id);
+// → "gen_01jh..."
+```
+
+> Generations are async - you get a `generation_id` immediately. Use **webhooks** to receive the completed output.
+
+---
+
+## Configuration
+
+```ts
+const client = new BabySea({
+  /** API key (required). Create one in your BabySea dashboard. */
+  apiKey: 'bye_...',
+
+  /**
+   * Region endpoint.
+   * - 'us' → https://api.us.babysea.ai  (default)
+   * - 'eu' → https://api.eu.babysea.ai
+   */
+  region: 'us',
+
+  /**
+   * Override the base URL entirely - for custom domains or self-hosted.
+   * Takes precedence over `region`.
+   */
+  baseUrl: 'https://acme.api.us.babysea.ai',
+
+  /** Request timeout in milliseconds. Default: 30 000 (30s). */
+  timeout: 30_000,
+
+  /** Max automatic retries on retryable errors (429, 5xx). Default: 2. */
+  maxRetries: 2,
+});
+```
+
+---
+
+## Methods
+
+### `generate(model, params)` - Create an image generation
+
+```ts
+const result = await client.generate('{model_identifier}', {
+  // Required
+  generation_prompt: 'A serene Japanese garden in spring',
+
+  // Optional
+  generation_ratio: '16:9',            // '1:1' | '16:9' | '9:16' | '4:3' | '3:4'
+  generation_output_format: 'png',    // 'png' | 'jpeg' | 'webp'
+  generation_output_number: 1,         // number of output images
+  generation_input_file: [             // input image URLs (for img2img models)
+    'https://example.com/reference.jpg',
+  ],
+  generation_provider_order: 'replicate, fal', // optional, model-dependent default
+});
+
+const { generation_id, generation_provider_order } = result.data;
+```
+
+---
+
+### `generateVideo(model, params)` - Create a video generation
+
+```ts
+// Duration-only video model
+const result = await client.generateVideo('{model_identifier}', {
+  // Required
+  generation_prompt: 'A baby seal swimming in the ocean',
+  generation_duration: 5, // seconds (range varies per model)
+
+  // Optional
+  generation_ratio: '16:9',
+  generation_output_format: 'mp4',
+  generation_input_file: [
+    'https://example.com/reference.jpg',
+  ],
+  generation_provider_order: 'replicate, fal',
+});
+
+// Duration + resolution video model
+const hd = await client.generateVideo('{model_identifier}', {
+  generation_prompt: 'Cinematic drone shot over a coral reef',
+  generation_duration: 8,
+  generation_resolution: '1080p', // required for resolution-priced models
+  generation_ratio: '16:9',
+});
+
+const { generation_id, generation_provider_order } = result.data;
+```
+
+---
+
+### `estimate(model, count?)` - Preview cost before generating
+
+```ts
+const est = await client.estimate('{model_identifier}', 5);
+
+est.data.cost_per_generation;       // 0.051 credits
+est.data.cost_total_consumed;       // 0.255 credits
+est.data.credit_balance;            // 10.000
+est.data.credit_balance_can_afford;  // true
+est.data.credit_balance_max_affordable; // 196
+```
+
+---
+
+### `getGeneration(id)` - Fetch a single generation
+
+```ts
+const gen = await client.getGeneration('gen_01jh...');
+
+gen.data.generation_status;       // 'processing' | 'succeeded' | 'failed' | 'canceled'
+gen.data.generation_output_file;  // string[] of output URLs (when succeeded)
+```
+
+---
+
+### `listGenerations(options?)` - List with pagination
+
+```ts
+const page = await client.listGenerations({ limit: 20, offset: 0 });
+
+page.total;            // total count across all pages
+page.data.generations; // Generation[]
+```
+
+---
+
+### `cancelGeneration(id)` - Cancel an in-progress generation
+
+```ts
+const cancel = await client.cancelGeneration('gen_01jh...');
+
+cancel.data.generation_status;    // 'canceled'
+cancel.data.credits_refunded;     // true
+cancel.data.provider_cancel_sent; // true (best-effort signal to provider)
+```
+
+> Only available while status is `pending` or `processing`. Sends a cancel signal to the upstream provider (best-effort) and refunds credits.
+
+---
+
+### `deleteGeneration(id)` - Delete a generation and its files
+
+```ts
+const del = await client.deleteGeneration('gen_01jh...');
+
+del.data.files_deleted; // number of storage files removed
+```
+
+---
+
+### `status()` - Verify API key and connectivity
+
+```ts
+const s = await client.status();
+
+s.data.account_id;
+s.data.apikey_prefix;       // 'bye_abc...'
+s.data.apikey_last_used_at;
+s.data.apikey_expires_at;
+```
+
+---
+
+### `account()` - Account details
+
+```ts
+const acct = await client.account();
+
+acct.data.account_name;
+acct.data.account_email;
+acct.data.account_is_personal;
+```
+
+---
+
+### `billing()` - Credit balance and subscription
+
+```ts
+const bill = await client.billing();
+
+bill.data.billing_credit_balance;    // 42.500
+  bill.data.billing_plan;              // 'Scale'
+bill.data.billing_period_ends_at;
+```
+
+---
+
+### `usage(days?)` - Usage analytics
+
+```ts
+const u = await client.usage(30); // last 30 days (1–90)
+
+u.data.usage_total_generations;
+u.data.usage_total_estimated_cost;
+u.data.usage_providers; // per-provider submission breakdown
+u.data.usage_endpoints; // per-endpoint request breakdown
+```
+
+---
+
+### `health.*` - Infrastructure health
+
+```ts
+// Provider circuit breaker state
+const prov = await client.health.providers();
+prov.data.providers;
+// [{ provider: 'replicate', status: 'healthy', failure_rate: 0.01, window: {...} }, ...]
+
+// Model availability across inference providers
+const healthModels = await client.health.models();
+healthModels.data.models.forEach((m) => {
+  console.log(m.model_identifier, m.model_pricing);
+});
+
+// Redis cache latency
+const cache = await client.health.cache();
+cache.data.latency_ms;
+
+// Supabase storage latency
+const storage = await client.health.storage();
+storage.data.latency_ms;
+```
+
+---
+
+### `library.*` - Model and provider catalog
+
+```ts
+// All available models (image + video) with pricing and input schemas
+const models = await client.library.models();
+models.data.models.forEach((m) => {
+  // Flat pricing (image + some video models)
+  // m.model_pricing → number
+
+  // Resolution-based pricing (some video models)
+  // m.model_pricing → { "480p": 0.030, "720p": 0.062, "1080p": 0.166 }
+
+  if (typeof m.model_pricing === 'number') {
+    console.log(m.model_identifier, m.model_pricing);
+  } else {
+    console.log(m.model_identifier, m.model_pricing); // per-resolution map
+  }
+});
+
+// All provider integration details
+const providers = await client.library.providers();
+```
+
+---
+
+## Error Handling
+
+```ts
+import { BabySea, BabySeaError, BabySeaTimeoutError, BabySeaRetryError } from 'babysea';
+
+try {
+  await client.generate('{model_identifier}', {
+    generation_prompt: 'A rainy city street',
+  });
+} catch (err) {
+  if (err instanceof BabySeaError) {
+    console.error(err.code);      // 'BSE1004' - structured error code
+    console.error(err.type);      // 'insufficient_credits'
+    console.error(err.message);   // human-readable
+    console.error(err.status);    // HTTP status (402, 429, 5xx...)
+    console.error(err.retryable); // boolean - safe to retry?
+    console.error(err.requestId); // unique ID for support
+
+    // Present on 429 responses
+    if (err.rateLimit) {
+      console.error(err.rateLimit.remaining);  // requests left in window
+      console.error(err.rateLimit.retryAfter); // seconds until reset
+    }
+  }
+
+  if (err instanceof BabySeaTimeoutError) {
+    // Request exceeded the configured `timeout`
+  }
+
+  if (err instanceof BabySeaRetryError) {
+    // All retry attempts exhausted
+    console.error(err.attempts);  // number of attempts made
+    console.error(err.lastError); // the final BabySeaError
+  }
+}
+```
+
+---
+
+## Webhooks
+
+Receive real-time generation events on your server. BabySea signs every delivery with HMAC-SHA256 (Stripe-style `t=<ts>,v1=<hex>`).
+
+```ts
+import { verifyWebhook } from 'babysea/webhooks';
+
+// Next.js App Router
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const signature = req.headers.get('X-BabySea-Signature') ?? '';
+
+  let payload;
+  try {
+    payload = await verifyWebhook(
+      rawBody,
+      signature,
+      process.env.BABYSEA_WEBHOOK_SECRET!,
+    );
+  } catch {
+    return new Response('Invalid signature', { status: 400 });
+  }
+
+  switch (payload.webhook_event) {
+    case 'generation.completed':
+      const urls = payload.webhook_data.generation_output_file;
+      // urls → string[] of output image URLs
+      await saveToDatabase(payload.webhook_data.generation_id, urls);
+      break;
+
+    case 'generation.failed':
+      console.error(payload.webhook_data.generation_error);
+      break;
+
+    case 'generation.canceled':
+      // credits were automatically refunded
+      break;
+  }
+
+  return new Response('OK');
+}
+```
+
+### Webhook Events
+
+| Event | When |
+|---|---|
+| `generation.started` | Generation accepted, provider called |
+| `generation.completed` | Provider succeeded, output files available |
+| `generation.failed` | All providers failed or infrastructure error |
+| `generation.canceled` | Canceled by user, credits refunded |
+| `webhook.test` | Test ping from the dashboard |
+
+---
+
+## API Key Scopes
+
+BabySea supports scoped API keys - issue a read-only key for your analytics dashboard, a generate-only key for your backend, and a full-access key for internal tools.
+
+| Scope | Routes |
+|---|---|
+| `generation:write` | POST `/v1/generate/image/:model`, POST `/v1/generate/video/:model` |
+| `generation:read` | GET `/v1/content/:generationId`, GET `/v1/content/list` |
+| `generation:delete` | DELETE `/v1/content/:generationId`, POST `/v1/content/generation/cancel/:generationId` |
+| `account:read` | GET `/v1/user/account`, `/v1/user/billing`, `/v1/usage`, `/v1/status` |
+| `health:read` | GET `/v1/health/*` |
+| `library:read` | GET `/v1/library/*`, `/v1/estimate/*` |
+
+**Preset bundles:**
+
+| Preset | Included scopes |
+|---|---|
+| `full_access` | All scopes |
+| `generate_only` | `generation:write`, `generation:read`, `library:read` |
+| `read_only` | `generation:read`, `account:read`, `health:read`, `library:read` |
+| `monitor_only` | `health:read`, `library:read` |
+
+---
+
+## Response Envelope
+
+All successful responses share this shape:
+
+```ts
+interface ApiResponse<T> {
+  status: 'success';
+  request_id: string; // unique ID - include this when contacting support
+  message: string;
+  timestamp: string;
+  data: T;
+}
+
+// Paginated responses add:
+interface PaginatedResponse<T> extends ApiResponse<T> {
+  total: number;
+  limit: number;
+  offset: number;
+}
+```
+
+---
+
+## Rate Limits
+
+| Plan | General (req/min) | Generation (req/min) |
+|---|---|---|
+| Free | 30 | 10 |
+| Starter ($9/mo) | 60 | 20 |
+| Pro ($29/mo) | 150 | 50 |
+| Scale ($99/mo) | 300 | 100 |
+| Enterprise ($199/mo) | 600 | 200 |
+
+All limits are per-account (shared across all API keys under the same account). The SDK automatically retries 429 responses using `Retry-After`, up to `maxRetries` (default: 2).
+
+---
+
+## Regions
+
+| Region | Endpoint |
+|---|---|
+| `us` | `https://api.us.babysea.ai` |
+| `eu` | `https://api.eu.babysea.ai` |
+
+Custom API domains (Scale and Enterprise plans) are supported via the `baseUrl` option.
+
+BabySea routes requests across all configured inference providers (Replicate, Fal, BytePlus) automatically with failover.
+
+---
+
+## License
+
+MIT

package/badges/license.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="78" height="20" role="img" aria-label="license: MIT"><title>license: MIT</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="78" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="47" height="20" fill="#555"/><rect x="47" width="31" height="20" fill="#4c1"/><rect width="78" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="245" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">license</text><text x="245" y="140" transform="scale(.1)" fill="#fff" textLength="370">license</text><text aria-hidden="true" x="615" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">MIT</text><text x="615" y="140" transform="scale(.1)" fill="#fff" textLength="210">MIT</text></g></svg>

package/badges/node.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="78" height="20" role="img" aria-label="node: &gt;=18"><title>node: &gt;=18</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="78" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="41" height="20" fill="#339933"/><rect width="78" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">node</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">node</text><text aria-hidden="true" x="565" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="310">&gt;=18</text><text x="565" y="140" transform="scale(.1)" fill="#fff" textLength="310">&gt;=18</text></g></svg>

package/badges/types.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="20" role="img" aria-label="npm type definitions: TypeScript"><title>npm type definitions: TypeScript</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="192" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="123" height="20" fill="#555"/><rect x="123" width="69" height="20" fill="#3178c6"/><rect width="192" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="625" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1130">npm type definitions</text><text x="625" y="140" transform="scale(.1)" fill="#fff" textLength="1130">npm type definitions</text><text aria-hidden="true" x="1565" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="590">TypeScript</text><text x="1565" y="140" transform="scale(.1)" fill="#fff" textLength="590">TypeScript</text></g></svg>

package/badges/version.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="80" height="20" role="img" aria-label="npm: v1.0.2"><title>npm: v1.0.2</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="80" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="35" height="20" fill="#555"/><rect x="35" width="45" height="20" fill="#cb3837"/><rect width="80" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="185" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="250">npm</text><text x="185" y="140" transform="scale(.1)" fill="#fff" textLength="250">npm</text><text aria-hidden="true" x="565" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="350">v1.0.2</text><text x="565" y="140" transform="scale(.1)" fill="#fff" textLength="350">v1.0.2</text></g></svg>