@xformmedia/sdk 0.5.3

package/README.md

@@ -0,0 +1,501 @@
+# @xformmedia/sdk
+
+Official SDK for the [xform.media](https://xform.media) service.
+
+## Installation
+
+```bash
+npm install @xformmedia/sdk
+```
+
+---
+
+## Overview
+
+The SDK ships two clients:
+
+| Client | Key type | Use for |
+|---|---|---|
+| `XformClient` | Source key | Video ingest, upload, and playback operations on a single source |
+| `XformAdminClient` | Organization key | Programmatic source management + all video operations (enterprise / server-to-server) |
+
+API keys are created in the xform admin:
+- **Source keys** — Source detail page → API Keys tab
+- **Organization keys** — Org settings → API Keys
+
+---
+
+## `XformClient` — Source-scoped client
+
+```ts
+import { XformClient } from '@xformmedia/sdk'
+
+const client = new XformClient({
+  sourceId: 'your-source-id',
+  organizationId: 'your-org-id',
+  apiKey: 'xfm_your_source_key',
+  baseUrl: 'https://admin.xform.media',
+})
+```
+
+### `client.ingest(options)`
+
+Trigger transcoding for a video already in your connected S3/R2 bucket. Call this after your own upload completes.
+
+```ts
+const result = await client.ingest({
+  key: 'recordings/standup.mp4',
+  callbackUrl: 'https://your-app.com/webhooks/xform', // optional
+})
+
+console.log(result.videoKey)        // "recordings-standup"
+console.log(result.transcodeStatus) // "pending"
+```
+
+### `client.createUploadUrl(options)`
+
+Get a presigned URL to upload a file directly to xform's storage, bypassing your own servers.
+
+```ts
+const { uploadUrl, key } = await client.createUploadUrl({
+  filename: 'recording.mp4',
+  contentType: 'video/mp4',
+})
+
+// Upload directly from browser or server
+await fetch(uploadUrl, {
+  method: 'PUT',
+  body: fileBlob,
+  headers: { 'Content-Type': 'video/mp4' },
+})
+
+// Then trigger transcoding
+const result = await client.ingest({ key })
+```
+
+### `client.events()`
+
+Open an SSE connection to receive real-time video status updates. Events are emitted as videos transition through: `pending` → `processing` → `ready` / `failed`.
+
+```ts
+const stream = client.events()
+
+stream.on('video.ready', (video) => {
+  console.log(`${video.videoKey} is ready (${video.duration}s)`)
+  console.log(`Stream:    https://${subdomain}.xform.media${video.streamUrl}`)
+  console.log(`Download:  https://${subdomain}.xform.media${video.downloadUrl}`)
+  console.log(`Thumbnail: https://${subdomain}.xform.media${video.thumbnailUrl}`)
+})
+
+stream.on('video.failed', (video) => {
+  console.error(`${video.videoKey} failed: ${video.errorMessage}`)
+})
+
+// Listen to all events
+stream.on('*', (video) => {
+  console.log(video.videoKey, video.transcodeStatus)
+})
+
+// Close when done
+stream.close()
+```
+
+This is an alternative to polling `client.videos.get()` or providing a `callbackUrl`. The stream uses Server-Sent Events over a persistent HTTP connection — no webhook endpoint needed.
+
+**Ingest + wait for ready:**
+
+```ts
+const stream = client.events()
+
+stream.on('video.ready', (video) => {
+  console.log(`Stream:   https://${subdomain}.xform.media${video.streamUrl}`)
+  console.log(`Download: https://${subdomain}.xform.media${video.downloadUrl}`)
+  stream.close()
+})
+
+stream.on('video.failed', (video) => {
+  console.error(video.errorMessage)
+  stream.close()
+})
+
+await client.ingest({ key: 'recordings/standup.mp4' })
+```
+
+### `client.videos.get(videoKey)`
+
+Get the current status and metadata of a video.
+
+```ts
+const video = await client.videos.get('recordings-standup')
+
+if (video.transcodeStatus === 'ready') {
+  const subdomain = 'acme' // your source subdomain
+  console.log(`Stream:   https://${subdomain}.xform.media/v/${video.videoKey}.m3u8`)
+  console.log(`Download: https://${subdomain}.xform.media/d/${video.videoKey}`)
+}
+```
+
+### `client.videos.delete(videoId)`
+
+Delete a video and all its renditions by database ID. This action is irreversible.
+
+```ts
+const result = await client.ingest({ key: 'recordings/standup.mp4' })
+
+// Later...
+await client.videos.delete(result.id)
+```
+
+### `client.videos.list(options?)`
+
+List all videos for this source, newest first.
+
+```ts
+const { data } = await client.videos.list({ limit: 20, skip: 0 })
+
+for (const video of data) {
+  console.log(video.videoKey, video.transcodeStatus, video.duration)
+}
+```
+
+### `client.usage()`
+
+Get storage and bandwidth usage for this source.
+
+```ts
+const usage = await client.usage()
+console.log(usage.totalVideos)
+console.log(usage.totalDurationSeconds)
+console.log(usage.totalFileSizeBytes)
+```
+
+### `client.updatePlan(input)`
+
+Change the source's plan, billing cycle, or add-ons. All fields are optional — omit any to leave it unchanged.
+
+```ts
+// Upgrade to Pro (prorated immediately)
+await client.updatePlan({ name: 'Pro', billingCycle: 'monthly' })
+
+// Switch to annual billing
+await client.updatePlan({ billingCycle: 'annual' })
+
+// Enable Video add-on on Starter plan
+await client.updatePlan({ addOns: { video: true } })
+
+// Downgrade to Starter with Smart Crop (no credit issued, takes effect next cycle)
+const billing = await client.updatePlan({
+  name: 'Starter',
+  billingCycle: 'monthly',
+  addOns: { smartCrop: true },
+})
+console.log(billing.status)            // "active"
+console.log(billing.plan.name)         // "Starter"
+console.log(billing.plan.billingCycle) // "monthly"
+```
+
+**Behaviour:**
+- Upgrades are prorated and charged immediately
+- Downgrades take effect at the next billing cycle — no credit is issued
+- Downgrading Pro → Starter automatically removes any attached custom domain
+- Upgrading Starter → Pro automatically removes the Smart Crop add-on (Pro includes it)
+
+---
+
+## `XformAdminClient` — Organization-scoped client
+
+For enterprise integrations that need to create and manage sources programmatically. Requires an organization-level API key.
+
+```ts
+import { createXformAdminClient } from '@xformmedia/sdk'
+
+const admin = createXformAdminClient({
+  organizationId: 'your-org-id',
+  apiKey: 'xfm_your_org_key',
+  baseUrl: 'https://admin.xform.media',
+})
+```
+
+### `admin.sources.checkSubdomain(subdomain)`
+
+Check if a subdomain is available before creating a source.
+
+```ts
+const { available } = await admin.sources.checkSubdomain('my-app')
+```
+
+### `admin.sources.create(input)`
+
+Create a new source. This provisions a subdomain, Cloudflare DNS record, and Stripe subscription item.
+
+```ts
+const source = await admin.sources.create({
+  name: 'My App Media',
+  subdomain: 'my-app',
+  provider: 'cloudflare-r2',
+  credentials: {
+    bucket: 'my-bucket',
+    endpoint: 'https://accountid.r2.cloudflarestorage.com',
+    accessKeyId: 'your-r2-key-id',
+    secretAccessKey: 'your-r2-secret',
+  },
+  plan: {
+    name: 'Starter',
+    billingCycle: 'monthly',
+  },
+})
+
+console.log(source.id)        // "64a1b2c3..."
+console.log(source.subdomain) // "my-app"
+// Media now served at: https://my-app.xform.media/
+```
+
+Supported providers: `'aws'`, `'cloudflare-r2'`, `'public-web'`
+
+### `admin.sources.list()`
+
+```ts
+const sources = await admin.sources.list()
+```
+
+### `admin.sources.get(sourceId)`
+
+```ts
+const source = await admin.sources.get('source-id')
+console.log(source.subdomain, source.status)
+```
+
+### `admin.sources.update(sourceId, input)`
+
+Update a source's name or credentials.
+
+```ts
+await admin.sources.update('source-id', {
+  name: 'New Name',
+  credentials: {
+    accessKeyId: 'rotated-key-id',
+    secretAccessKey: 'rotated-secret',
+  },
+})
+```
+
+### `admin.source(sourceId)` — per-source operations
+
+All video operations, event streaming, and plan management are available via `admin.source(id)`:
+
+```ts
+const src = admin.source(sourceId)
+
+// Real-time events
+const stream = src.events()
+stream.on('video.ready', (video) => console.log(video.videoKey, 'ready'))
+
+// Plan management
+await src.updatePlan({ name: 'Pro' })
+await src.updatePlan({ addOns: { video: true } })
+
+// Video ingest
+const { uploadUrl, key } = await src.createUploadUrl({ filename: 'clip.mp4', contentType: 'video/mp4' })
+await fetch(uploadUrl, { method: 'PUT', body: blob, headers: { 'Content-Type': 'video/mp4' } })
+const job = await src.ingest({ key })
+
+// Video status
+const video = await src.videos.get(job.videoKey)
+const { data } = await src.videos.list({ limit: 50 })
+
+// Delete a video by ID
+await src.videos.delete(job.id)
+
+// Usage
+const usage = await src.usage()
+```
+
+### `admin.source(sourceId).webhook` — Webhook configuration
+
+Configure a webhook to receive HTTP POST notifications when video events occur. All payloads are signed with HMAC-SHA256 for verification.
+
+```ts
+const src = admin.source(sourceId)
+
+// Set a webhook (subscribes to all events by default)
+await src.webhook.set({
+  url: 'https://your-app.com/webhooks/xform',
+  secret: 'whsec_your_signing_secret',
+})
+
+// Or subscribe to specific events only
+await src.webhook.set({
+  url: 'https://your-app.com/webhooks/xform',
+  secret: 'whsec_your_signing_secret',
+  events: ['video.ready', 'video.failed'],
+})
+
+// Get current config (secret is masked)
+const config = await src.webhook.get()
+// { url: "https://...", secret: "whse••••••••", events: [...] }
+
+// Remove webhook
+await src.webhook.delete()
+```
+
+**Webhook events:**
+
+| Event | Trigger | Payload `data` fields |
+|---|---|---|
+| `video.ready` | Transcode completed | `streamUrl`, `downloadUrl`, `duration`, `thumbnailUrl`, `width`, `height` |
+| `video.failed` | Transcode failed (after retries) | `errorMessage` |
+| `video.renamed` | Video display name changed | `displayName` |
+
+**Payload format:**
+
+```json
+{
+  "event": "video.ready",
+  "sourceId": "64a1b2c3...",
+  "videoKey": "recordings-standup",
+  "timestamp": "2026-03-06T12:00:00.000Z",
+  "data": {
+    "streamUrl": "/v/recordings-standup.m3u8",
+    "downloadUrl": "/d/recordings-standup",
+    "duration": 42.5,
+    "thumbnailUrl": "/v/recordings-standup/thumbnail.jpg",
+    "width": 1920,
+    "height": 1080
+  }
+}
+```
+
+**Verifying signatures:**
+
+```ts
+import { createHmac } from 'crypto'
+
+function verifyWebhook(body: string, signature: string, secret: string): boolean {
+  const expected = createHmac('sha256', secret).update(body).digest('hex')
+  return signature === expected
+}
+
+// In your webhook handler:
+app.post('/webhooks/xform', (req, res) => {
+  const signature = req.headers['x-webhook-signature']
+  const event = req.headers['x-webhook-event']
+
+  if (!verifyWebhook(JSON.stringify(req.body), signature, 'whsec_your_secret')) {
+    return res.status(401).send('Invalid signature')
+  }
+
+  // Process event...
+  res.sendStatus(200)
+})
+```
+
+Webhooks are retried up to 3 times with exponential backoff if your endpoint returns a non-2xx status.
+
+### Full end-to-end example
+
+```ts
+// 1. Create source
+const { available } = await admin.sources.checkSubdomain('pixelfilm-user-123')
+if (!available) throw new Error('Subdomain taken')
+
+const source = await admin.sources.create({
+  name: 'User 123',
+  subdomain: 'pixelfilm-user-123',
+  provider: 'cloudflare-r2',
+  credentials: { bucket, endpoint, accessKeyId, secretAccessKey },
+  plan: { name: 'Starter', billingCycle: 'monthly' },
+})
+
+// 2. Upload and ingest with real-time status
+const src = admin.source(source.id)
+const stream = src.events()
+
+stream.on('video.ready', (video) => {
+  console.log(`https://${source.subdomain}.xform.media/v/${video.videoKey}.m3u8`)
+  stream.close()
+})
+
+stream.on('video.failed', (video) => {
+  console.error(video.errorMessage)
+  stream.close()
+})
+
+const { uploadUrl, key } = await src.createUploadUrl({
+  filename: 'recording.mp4',
+  contentType: 'video/mp4',
+})
+await fetch(uploadUrl, { method: 'PUT', body: blob, headers: { 'Content-Type': 'video/mp4' } })
+await src.ingest({ key })
+```
+
+---
+
+## Error Handling
+
+All methods throw `XformError` on API failures.
+
+```ts
+import { XformError } from '@xformmedia/sdk'
+
+try {
+  await admin.sources.create({ ... })
+} catch (err) {
+  if (err instanceof XformError) {
+    console.error(err.statusCode, err.message)
+    console.error(err.body) // full response body
+  }
+}
+```
+
+| Status | Meaning |
+|---|---|
+| `400` | Invalid input — missing fields, bad subdomain format, etc. |
+| `401` | Invalid or expired API key |
+| `403` | Key scope mismatch — wrong source, or source key used on org endpoint |
+| `404` | Source or video not found |
+| `409` | Subdomain already taken |
+| `500` | Server error — retry with backoff |
+
+---
+
+## TypeScript
+
+All types are exported:
+
+```ts
+import type {
+  // Clients
+  XformClientOptions,
+  XformAdminClientOptions,
+  // Sources
+  Source,
+  SourceBilling,
+  SourcePlan,
+  SourceCredentials,
+  SourceProvider,
+  SourceStatus,
+  CreateSourceInput,
+  UpdateSourceInput,
+  UpdatePlanInput,
+  BillingCycle,
+  BillingStatus,
+  PlanName,
+  CheckSubdomainResult,
+  // Webhooks
+  WebhookEventType,
+  WebhookConfig,
+  SetWebhookInput,
+  // Videos
+  Video,
+  VideoEvent,
+  VideoEventType,
+  VideoEventStream,
+  VideoRendition,
+  VideoTranscodeStatus,
+  VideoRenditionQuality,
+  IngestResult,
+  UploadUrlResult,
+  ListVideosResult,
+  VideoUsageResult,
+} from '@xformmedia/sdk'
+```

package/dist/admin-client.d.ts

@@ -0,0 +1,115 @@
+import type { XformAdminClientOptions, Source, SourceBilling, VideoEventStream, CreateSourceInput, UpdateSourceInput, UpdatePlanInput, CheckSubdomainResult, Video, IngestResult, UploadUrlResult, ListVideosResult, VideoUsageResult, WebhookConfig, SetWebhookInput } from './types.js';
+export declare class XformAdminClient {
+    private readonly organizationId;
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: XformAdminClientOptions);
+    private get headers();
+    private request;
+    /** Source management operations (requires org-scoped API key) */
+    readonly sources: {
+        /**
+         * List all sources for this organization.
+         */
+        list: () => Promise<Source[]>;
+        /**
+         * Get a specific source by ID.
+         */
+        get: (sourceId: string) => Promise<Source>;
+        /**
+         * Create a new source. This provisions a subdomain, Cloudflare DNS record,
+         * and Stripe subscription item.
+         */
+        create: (input: CreateSourceInput) => Promise<Source>;
+        /**
+         * Update an existing source's settings.
+         */
+        update: (sourceId: string, input: UpdateSourceInput) => Promise<Source>;
+        /**
+         * Check if a subdomain is available before creating a source.
+         */
+        checkSubdomain: (subdomain: string) => Promise<CheckSubdomainResult>;
+    };
+    /**
+     * Returns a set of video operations scoped to a specific source.
+     * Use this after creating or looking up a source.
+     */
+    source(sourceId: string): {
+        /**
+         * Open an SSE connection to receive real-time video status updates for this source.
+         */
+        events(): VideoEventStream;
+        /**
+         * Ingest a video from the source's connected S3/R2 bucket.
+         * Call this after uploading the file to the bucket.
+         */
+        ingest(options: {
+            key: string;
+            callbackUrl?: string;
+        }): Promise<IngestResult>;
+        /**
+         * Create a presigned URL for uploading a file directly to xform's R2 storage.
+         * After uploading, call `ingest()` with the returned `key`.
+         */
+        createUploadUrl(options: {
+            filename: string;
+            contentType: string;
+        }): Promise<UploadUrlResult>;
+        /**
+         * Get storage and bandwidth usage for this source.
+         */
+        usage(): Promise<VideoUsageResult>;
+        /**
+         * Change the source's plan, billing cycle, or add-ons.
+         * Omit any field to leave it unchanged.
+         *
+         * Upgrades are prorated immediately.
+         * Downgrades take effect at the next billing cycle (no credit issued).
+         * Downgrading from Pro to Starter automatically removes any custom domain.
+         */
+        updatePlan(input: UpdatePlanInput): Promise<SourceBilling>;
+        /** Video operations for this source */
+        videos: {
+            /**
+             * List all videos for this source.
+             */
+            list(options?: {
+                limit?: number;
+                skip?: number;
+            }): Promise<ListVideosResult>;
+            /**
+             * Get the status and metadata of a specific video.
+             */
+            get(videoKey: string): Promise<Video>;
+        };
+        /** Webhook configuration for this source */
+        webhook: {
+            /**
+             * Get the current webhook configuration (secret is masked).
+             * Returns null if no webhook is configured.
+             */
+            get(): Promise<WebhookConfig | null>;
+            /**
+             * Set or update the webhook configuration.
+             * If `events` is omitted, all event types are subscribed.
+             */
+            set(input: SetWebhookInput): Promise<WebhookConfig>;
+            /**
+             * Remove the webhook configuration. No more webhooks will be sent.
+             */
+            delete(): Promise<void>;
+        };
+    };
+}
+/**
+ * Create an organization-scoped xform client.
+ * Use this for programmatic source management (enterprise / server-to-server).
+ * Requires an organization-level API key.
+ *
+ * @example
+ * const admin = createXformAdminClient({ organizationId, apiKey, baseUrl })
+ * const source = await admin.sources.create({ name: 'My Source', ... })
+ * const { uploadUrl, key } = await admin.source(source.id).createUploadUrl({ ... })
+ */
+export declare function createXformAdminClient(options: XformAdminClientOptions): XformAdminClient;
+//# sourceMappingURL=admin-client.d.ts.map

package/dist/admin-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-client.d.ts","sourceRoot":"","sources":["../src/admin-client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,MAAM,EACN,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,KAAK,EACL,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;gBAEpB,OAAO,EAAE,uBAAuB;IAM5C,OAAO,KAAK,OAAO,GAMlB;YAEa,OAAO;IAuBrB,iEAAiE;IACjE,QAAQ,CAAC,OAAO;QACd;;WAEG;oBACO,OAAO,CAAC,MAAM,EAAE,CAAC;QAI3B;;WAEG;wBACa,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;QAIxC;;;WAGG;wBACa,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC;QAInD;;WAEG;2BACgB,MAAM,SAAS,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC;QAIrE;;WAEG;oCACyB,MAAM,KAAG,OAAO,CAAC,oBAAoB,CAAC;MAInE;IAED;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM;QAOnB;;WAEG;kBACO,gBAAgB;QAQ1B;;;WAGG;wBACmB;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC,YAAY,CAAC;QASnF;;;WAGG;iCAC4B;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC,eAAe,CAAC;QASnG;;WAEG;iBACM,OAAO,CAAC,gBAAgB,CAAC;QAIlC;;;;;;;WAOG;0BACe,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;QAQ1D,uCAAuC;;YAErC;;eAEG;2BACW;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,GAAQ,OAAO,CAAC,gBAAgB,CAAC;YAQhF;;eAEG;0BACW,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;;QAQvC,4CAA4C;;YAE1C;;;eAGG;mBACI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAOpC;;;eAGG;uBACQ,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;YAQnD;;eAEG;sBACO,OAAO,CAAC,IAAI,CAAC;;;CAM9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAEzF"}