@wave-av/sdk 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to `@wave/sdk` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-04-01
+
+### Added
+
+- **CloudSwitcherAPI** — Cloud video switcher control (instances, inputs, outputs, transitions, program/preview bus)
+- **ReplayAPI** — Replay engine management (sessions, points of interest, clip export to social)
+- **CameraControlAPI** — Multi-manufacturer camera control (PTZ, focus, iris, presets, discovery)
+- **GraphicsAPI** — Lower-thirds, overlays, and animated graphics layer management
+- **SportsDataAPI** — Live sports data integration (scoreboards, clocks, stats, player cards)
+- **AutomationAPI** — Rule-based production automation (triggers, actions, schedules, rundowns)
+- **StorefrontAPI** — Creator commerce (products, purchases, entitlement checks, storefronts)
+
+### Changed
+
+- Client HTTP methods replaced `client.request()` with dedicated `client.get()`, `client.post()`, and `client.delete()` for clearer intent and improved TypeScript inference. Migration:
+
+  ```typescript
+  // Before (v1.x)
+  const stream = await client.request<Stream>('/v1/streams/abc', {
+    method: 'GET',
+  });
+
+  // After (v2.0)
+  const stream = await client.get<Stream>('/v1/streams/abc');
+  ```
+
+- `Wave` convenience class expanded from 12 to 34 API module properties
+- `PipelineAPI`, `StudioAPI`, `FleetAPI`, `GhostAPI`, `MeshAPI`, `EdgeAPI`, `PulseAPI`, and `ClipsAPI` promoted from beta to stable
+
+## [1.0.0] - 2025-10-15
+
+### Added
+
+- Initial public release
+- **PipelineAPI** — Live stream management (create, start, stop, recordings, viewer metrics, protocol switching)
+- **StudioAPI** — Multi-camera production (sources, scenes, transitions, graphics, audio mixing)
+- **FleetAPI** — Desktop Node fleet management (register, health, commands, metrics)
+- **GhostAPI** — AI automatic directing (autonomous/assisted modes, suggestions, overrides)
+- **MeshAPI** — Multi-region failover (regions, peers, policies, replication, topology)
+- **EdgeAPI** — CDN and edge workers (deploy, routing, cache purge, latency map)
+- **PulseAPI** — Analytics and BI (stream, viewer, quality, engagement, revenue metrics; dashboards; reports)
+- **ClipsAPI** — Clip creation from live or VOD sources (export, highlights, AI detection)
+- Base `WaveClient` with API key authentication, configurable retry logic (default 3 attempts), rate limit handling, and optional OpenTelemetry integration
+- `Wave` convenience class bundling all 12 API modules under a single import
+- TypeScript strict mode throughout; ESM and CJS dual output via `tsup`
+
+[Unreleased]: https://github.com/wave-av/wave-surfer-connect/compare/sdk-v2.0.0...HEAD
+[2.0.0]: https://github.com/wave-av/wave-surfer-connect/compare/sdk-v1.0.0...sdk-v2.0.0
+[1.0.0]: https://github.com/wave-av/wave-surfer-connect/releases/tag/sdk-v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WAVE 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,406 @@
+# WAVE SDK for TypeScript
+
+Official TypeScript SDK for the WAVE API by WAVE Inc.
+
+## Installation
+
+```bash
+pnpm add @wave/sdk
+# or
+npm install @wave/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({
+  apiKey: process.env.WAVE_API_KEY!,
+  organizationId: "org_123",
+});
+
+// Create and start a live stream
+const stream = await wave.pipeline.create({
+  title: "My Live Stream",
+  protocol: "webrtc",
+  recording_enabled: true,
+});
+await wave.pipeline.start(stream.id);
+
+// Create a virtual camera from NDI
+const device = await wave.prism.createDevice({
+  name: "PTZ Camera 1",
+  type: "camera",
+  source_protocol: "ndi",
+  source_endpoint: "NDI-CAM-1",
+  node_id: "node_abc",
+  ptz_enabled: true,
+});
+
+// Get analytics
+const viewers = await wave.pulse.getViewerAnalytics({ time_range: "24h" });
+console.log(`Peak concurrent: ${viewers.peak_concurrent}`);
+```
+
+## All 34 APIs
+
+### P1 - Core Streaming
+
+| API             | Access        | Description                                                          |
+| --------------- | ------------- | -------------------------------------------------------------------- |
+| `wave.pipeline` | `PipelineAPI` | Live stream lifecycle, protocols, recordings, viewer metrics         |
+| `wave.studio`   | `StudioAPI`   | Multi-camera production, scenes, transitions, graphics, audio mixing |
+
+### P2 - Enterprise
+
+| API          | Access     | Description                                                  |
+| ------------ | ---------- | ------------------------------------------------------------ |
+| `wave.fleet` | `FleetAPI` | Desktop Node fleet management, health, commands              |
+| `wave.ghost` | `GhostAPI` | AI auto-directing (Autopilot), suggestions, overrides        |
+| `wave.mesh`  | `MeshAPI`  | Multi-region failover, replication, topology                 |
+| `wave.edge`  | `EdgeAPI`  | CDN, edge workers, cache, routing rules                      |
+| `wave.pulse` | `PulseAPI` | Analytics, BI dashboards, revenue metrics                    |
+| `wave.prism` | `PrismAPI` | Virtual Device Bridge (NDI/ONVIF/VISCA/Dante to USB UVC/UAC) |
+| `wave.zoom`  | `ZoomAPI`  | Zoom meetings, rooms, recordings, RTMS                       |
+
+### P3 - Content & Commerce
+
+| API                 | Access            | Description                                 |
+| ------------------- | ----------------- | ------------------------------------------- |
+| `wave.clips`        | `ClipsAPI`        | Video clips, exports, AI highlights         |
+| `wave.editor`       | `EditorAPI`       | Video editing, tracks, transitions, effects |
+| `wave.voice`        | `VoiceAPI`        | Text-to-speech, voice cloning               |
+| `wave.phone`        | `PhoneAPI`        | Voice calling, conferences, numbers         |
+| `wave.collab`       | `CollabAPI`       | Real-time collaboration rooms               |
+| `wave.captions`     | `CaptionsAPI`     | Auto-captions, translation, burn-in         |
+| `wave.chapters`     | `ChaptersAPI`     | Video chapters and markers                  |
+| `wave.studioAI`     | `StudioAIAPI`     | AI production assistant, suggestions        |
+| `wave.transcribe`   | `TranscribeAPI`   | Transcription with speaker diarization      |
+| `wave.sentiment`    | `SentimentAPI`    | Sentiment and emotion analysis              |
+| `wave.search`       | `SearchAPI`       | Full-text, visual, and audio search         |
+| `wave.scene`        | `SceneAPI`        | AI scene detection and shot classification  |
+| `wave.vault`        | `VaultAPI`        | Recording storage, VOD, archive policies    |
+| `wave.marketplace`  | `MarketplaceAPI`  | Templates, plugins, graphics marketplace    |
+| `wave.connect`      | `ConnectAPI`      | Third-party integrations, webhooks          |
+| `wave.distribution` | `DistributionAPI` | Social simulcasting, scheduled posts        |
+| `wave.desktop`      | `DesktopAPI`      | Desktop Node app management                 |
+| `wave.signage`      | `SignageAPI`      | Digital signage displays, playlists         |
+| `wave.qr`           | `QrAPI`           | Dynamic QR codes, analytics                 |
+| `wave.audience`     | `AudienceAPI`     | Polls, Q&A, reactions, engagement           |
+| `wave.creator`      | `CreatorAPI`      | Monetization, subscriptions, tips, payouts  |
+
+### P4 - Specialized
+
+| API            | Access       | Description                         |
+| -------------- | ------------ | ----------------------------------- |
+| `wave.podcast` | `PodcastAPI` | Podcast episodes, RSS, distribution |
+| `wave.slides`  | `SlidesAPI`  | Presentation-to-video conversion    |
+| `wave.usb`     | `UsbAPI`     | USB device relay and management     |
+
+## Product Examples
+
+- [Streams (Pipeline)](#streams-pipeline)
+- [Clips](#clips)
+- [Captions](#captions)
+- [Chapters](#chapters)
+- [Voice](#voice)
+- [Transcription](#transcription)
+- [Editor](#editor)
+- [Phone](#phone)
+- [Podcast](#podcast)
+- [Collab](#collab)
+- [Analytics (Pulse)](#analytics-pulse)
+- [VOD (Vault)](#vod-vault)
+- [Studio AI](#studio-ai)
+
+---
+
+### Streams (Pipeline)
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const stream = await wave.pipeline.create({
+  title: "My Live Stream",
+  protocol: "webrtc",
+  recording_enabled: true,
+});
+await wave.pipeline.start(stream.id);
+const live = await wave.pipeline.waitForLive(stream.id);
+console.log(`Playback: ${live.playback_url}`);
+await wave.pipeline.stop(stream.id);
+```
+
+### Clips
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const clip = await wave.clips.create({
+  title: "Best Moment",
+  source: { type: "stream", id: "stream_123", start_time: 120, end_time: 150 },
+});
+const ready = await wave.clips.waitForReady(clip.id);
+console.log(`Clip URL: ${ready.playback_url}`);
+```
+
+### Captions
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const track = await wave.captions.generate({
+  media_id: "video_123",
+  media_type: "video",
+  language: "en",
+  speaker_diarization: true,
+});
+const ready = await wave.captions.waitForReady(track.id);
+await wave.captions.translate(ready.id, { target_language: "es" });
+```
+
+### Chapters
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const chapterSet = await wave.chapters.generate({
+  media_id: "video_123",
+  media_type: "video",
+  method: "combined",
+  generate_thumbnails: true,
+});
+const ready = await wave.chapters.waitForReady(chapterSet.id);
+console.log(`Found ${ready.chapter_count} chapters`);
+```
+
+### Voice
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const voices = await wave.voice.listVoices({ language: "en" });
+const result = await wave.voice.synthesize({
+  text: "Welcome to WAVE live streaming.",
+  voice_id: voices.data[0].id,
+  format: "mp3",
+});
+const audio = await wave.voice.waitForSynthesis(result.id);
+console.log(`Audio: ${audio.audio_url}`);
+```
+
+### Transcription
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const job = await wave.transcribe.create({
+  source_type: "recording",
+  source_id: "rec_456",
+  language: "en",
+  speaker_diarization: true,
+});
+const result = await wave.transcribe.waitForReady(job.id);
+const text = await wave.transcribe.getText(result.id, { include_speakers: true });
+console.log(text);
+```
+
+### Editor
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const project = await wave.editor.createProject({
+  name: "Highlight Reel",
+  width: 1920,
+  height: 1080,
+  frame_rate: 30,
+});
+const track = await wave.editor.addTrack(project.id, { name: "Main", type: "video" });
+await wave.editor.addElement(project.id, {
+  track_id: track.id,
+  type: "clip",
+  source_id: "clip_789",
+  start_time: 0,
+});
+const job = await wave.editor.render(project.id, { format: "mp4", quality: "high" });
+const rendered = await wave.editor.waitForRender(project.id, job.id);
+console.log(`Output: ${rendered.output_url}`);
+```
+
+### Phone
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const call = await wave.phone.makeCall({
+  from: "+15551234567",
+  to: "+15559876543",
+  timeout: 30,
+});
+console.log(`Call ${call.id} status: ${call.status}`);
+```
+
+### Podcast
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const show = await wave.podcast.create({
+  title: "The WAVE Podcast",
+  description: "Weekly streaming industry news",
+  category: "Technology",
+});
+const episode = await wave.podcast.createEpisode({
+  podcast_id: show.id,
+  title: "Episode 1: Getting Started",
+  description: "An introduction to live streaming.",
+});
+await wave.podcast.publishEpisode(episode.id);
+```
+
+### Collab
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const room = await wave.collab.createRoom({
+  name: "Project Review",
+  resource_type: "project",
+  resource_id: "proj_123",
+  settings: { voice_enabled: true, annotations_enabled: true },
+});
+console.log(`Room: ${room.id} (${room.participant_count} participants)`);
+```
+
+### Analytics (Pulse)
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const viewers = await wave.pulse.getViewerAnalytics({ time_range: "24h" });
+console.log(`Peak concurrent: ${viewers.peak_concurrent}`);
+console.log(`Unique viewers: ${viewers.unique_viewers}`);
+
+const stream = await wave.pulse.getStreamAnalytics("stream_123", { time_range: "7d" });
+console.log(`Quality score: ${stream.quality_score}`);
+```
+
+### VOD (Vault)
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const upload = await wave.vault.createUpload({
+  title: "Conference Keynote",
+  format: "mp4",
+  file_size_bytes: 524288000,
+});
+console.log(`Upload to: ${upload.upload_url}`);
+
+const usage = await wave.vault.getStorageUsage();
+console.log(`Storage: ${usage.usage_percent}% used`);
+```
+
+### Studio AI
+
+```typescript
+import { Wave } from "@wave/sdk";
+
+const wave = new Wave({ apiKey: process.env.WAVE_API_KEY! });
+
+const assistant = await wave.studioAI.startAssistant({
+  stream_id: "stream_123",
+  mode: "auto_director",
+  config: { automation_level: 75, auto_apply: false, confidence_threshold: 0.8, settings: {} },
+});
+const suggestions = await wave.studioAI.getSuggestion(assistant.id);
+console.log(`AI suggestion: ${suggestions.title} (${suggestions.confidence * 100}% confidence)`);
+```
+
+---
+
+## Configuration
+
+```typescript
+const wave = new Wave({
+  apiKey: "your-api-key", // Required
+  organizationId: "org_123", // Multi-tenant isolation
+  baseUrl: "https://api.wave.online", // Default
+  timeout: 30000, // Request timeout (ms)
+  maxRetries: 3, // Retry attempts
+  debug: false, // Debug logging
+});
+```
+
+## Individual API Imports
+
+```typescript
+import { WaveClient, PipelineAPI, PrismAPI } from "@wave/sdk";
+
+const client = new WaveClient({ apiKey: "key" });
+const pipeline = new PipelineAPI(client);
+const prism = new PrismAPI(client);
+```
+
+## Error Handling
+
+```typescript
+import { WaveError, RateLimitError } from "@wave/sdk";
+
+try {
+  await wave.pipeline.get("invalid-id");
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
+  } else if (error instanceof WaveError) {
+    console.log(`${error.code}: ${error.message} (${error.statusCode})`);
+  }
+}
+```
+
+## Events
+
+```typescript
+wave.client.on("request.start", (url, method) => {
+  console.log(`${method} ${url}`);
+});
+
+wave.client.on("rate_limit.hit", (retryAfter) => {
+  console.log(`Rate limited. Waiting ${retryAfter}ms`);
+});
+```
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.0+ (for TypeScript users)
+
+## License
+
+MIT - WAVE Inc.