@rendobar/sdk 0.1.0

package/README.md

@@ -0,0 +1,229 @@
+# @rendobar/sdk
+
+TypeScript client for the Rendobar media processing API.
+
+## Install
+
+```bash
+npm install @rendobar/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from "@rendobar/sdk";
+
+const client = createClient({ apiKey: "rb_..." });
+
+// Submit a job
+const job = await client.jobs.create({
+  type: "watermark.apply",
+  inputs: { source: "https://example.com/video.mp4" },
+  params: { text: "PREVIEW", position: "center", opacity: 0.3 },
+});
+
+// Wait for completion
+const result = await client.jobs.wait(job.id);
+console.log(result.outputUrl);
+```
+
+## Authentication
+
+```typescript
+// API key (external users, CLI, scripts)
+const client = createClient({ apiKey: "rb_..." });
+
+// Session cookie (internal dashboard)
+const client = createClient({
+  baseUrl: "https://api.rendobar.com",
+  credentials: "include",
+});
+```
+
+## Configuration
+
+```typescript
+const client = createClient({
+  apiKey: "rb_...",
+  baseUrl: "https://api.rendobar.com", // default
+  timeout: 30_000,                      // default: 30s
+  maxRetries: 2,                        // default: 2 (retries 429, 5xx)
+  orgId: "org_abc",                     // X-Org-Id header
+  debug: false,                         // log request metadata
+  fetch: customFetch,                   // custom fetch for testing
+});
+```
+
+## Jobs
+
+```typescript
+// Create
+const job = await client.jobs.create({
+  type: "watermark.apply",
+  inputs: { source: "https://example.com/video.mp4" },
+  params: { text: "PREVIEW", position: "center" },
+  idempotencyKey: "unique-key-123",
+});
+
+// Get
+const job = await client.jobs.get("job_abc");
+
+// List (paginated — works with React Query)
+const page = await client.jobs.list({ status: "complete", limit: 20 });
+// page.data: Job[], page.meta: { total, page, limit }
+
+// Auto-paginate all pages
+for await (const job of client.jobs.listAll({ status: "complete" })) {
+  console.log(job.id);
+}
+
+// Wait for completion (polls until terminal status)
+const result = await client.jobs.wait("job_abc", {
+  timeout: 300_000,
+  interval: 2_000,
+  onProgress: (job) => console.log(job.status),
+  signal: abortController.signal,
+});
+
+// Cancel
+await client.jobs.cancel("job_abc");
+
+// Download output (returns raw Response)
+const response = await client.jobs.download("job_abc");
+const blob = await response.blob();
+
+// Execution logs
+const logs = await client.jobs.logs("job_abc");
+
+// Available job types
+const types = await client.jobs.types();
+```
+
+## Billing
+
+```typescript
+const state = await client.billing.state();
+const usage = await client.billing.usage({ start: "2026-01-01", end: "2026-03-29" });
+const txns = await client.billing.transactions({ page: 1, limit: 50 });
+```
+
+## Uploads
+
+```typescript
+// Upload a file, get a URL to use as job input
+const { downloadUrl } = await client.uploads.upload(file, { filename: "input.mp4" });
+
+const job = await client.jobs.create({
+  type: "watermark.apply",
+  inputs: { source: downloadUrl },
+  params: { text: "PREVIEW" },
+});
+```
+
+## Batches
+
+```typescript
+const batch = await client.batches.create({
+  jobs: [
+    { type: "watermark.apply", inputs: { source: url1 }, params: { text: "1" } },
+    { type: "watermark.apply", inputs: { source: url2 }, params: { text: "2" } },
+  ],
+});
+```
+
+## Webhooks
+
+```typescript
+// Create endpoint
+const endpoint = await client.webhooks.create({
+  name: "My Webhook",
+  url: "https://example.com/webhook",
+  subscribedEvents: ["job.completed", "job.failed"],
+});
+
+// Verify signature in your webhook handler
+import { verifyWebhookSignature } from "@rendobar/sdk/webhooks";
+
+const isValid = await verifyWebhookSignature(
+  requestBody,
+  request.headers.get("X-Rendobar-Signature"),
+  signingSecret,
+);
+```
+
+## Realtime Events (WebSocket)
+
+```typescript
+// Org-wide event stream
+const connection = client.realtime.connect({
+  onEvent: (event) => console.log(event.type, event),
+  onLive: () => console.log("Replay complete, now live"),
+  onResync: () => console.log("Buffer overflow — refresh data"),
+});
+
+// Per-job subscription
+const sub = client.realtime.subscribeJob("job_abc", {
+  onProgress: (e) => console.log(`${e.progress}%`),
+  onStep: (e) => console.log(`Step: ${e.stepName}`),
+  onComplete: (e) => console.log("Done!", e.status),
+});
+
+// Cleanup
+connection.disconnect();
+sub.unsubscribe();
+```
+
+> **Note:** Realtime requires session cookie auth. API key users should use `jobs.wait()` for polling.
+
+## Error Handling
+
+```typescript
+import { createClient, ApiError, isApiError } from "@rendobar/sdk";
+
+try {
+  await client.jobs.create({ type: "watermark.apply", ... });
+} catch (err) {
+  if (isApiError(err)) {
+    console.log(err.code);       // "INSUFFICIENT_CREDITS"
+    console.log(err.statusCode); // 402
+    console.log(err.message);    // "Not enough credits"
+    console.log(err.retryAfter); // seconds (for 429s)
+  }
+}
+```
+
+Error codes: `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`, `INSUFFICIENT_CREDITS`, `RATE_LIMITED`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_ERROR`.
+
+## Retries
+
+The SDK automatically retries:
+- **429** (rate limited) — respects `Retry-After` header
+- **500, 502, 503, 504** — server errors
+
+Retries use exponential backoff (500ms, 1s). Max 2 retries by default. Non-retryable errors (400, 401, 403, 404) throw immediately.
+
+## AbortSignal
+
+Every method accepts an optional `signal` for cancellation:
+
+```typescript
+const controller = new AbortController();
+const job = await client.jobs.get("job_abc", { signal: controller.signal });
+
+// Cancel the request
+controller.abort();
+```
+
+## Types
+
+All response types are exported:
+
+```typescript
+import type {
+  Job, JobStep, JobType, JobCreatedResponse,
+  BillingState, Transaction, UsageSummary,
+  WebhookEndpoint, WebhookDelivery,
+  Organization, ApiKey, PaginationMeta,
+  BillingInvoice, PaymentMethod, LogEntryData,
+} from "@rendobar/sdk";
+```