@stinkycomputing/sesame-api-client 1.4.1-alpha.9 → 1.4.1-beta.1

package/README.md

@@ -1,16 +1,10 @@
 # @stinkycomputing/sesame-api-client
 
-Official TypeScript/JavaScript client library for the Sesame video production server.
+TypeScript client library for the Sesame video production server. Provides type-safe protobuf definitions, a WebSocket RPC client with reconnection, and helpers for building command lists.
 
-## Features
+All websocket traffic uses protobuf wire framing — see [Wire Protocol](#wire-protocol).
 
-- 🎯 **Full Protobuf API** - Complete type-safe protobuf definitions for all Sesame APIs
-- 🔧 **Command List Helper** - Fluent API for building command lists
-- 🌐 **RPC Client** - WebSocket-based RPC client with automatic reconnection
-- 📦 **Modular Design** - New v1 API with domain-specific modules
-- 🔄 **Backward Compatible** - Supports both legacy and new API structures
-
-## Installation
+## Install
 
 ```bash
 npm install @stinkycomputing/sesame-api-client
@@ -18,196 +12,124 @@ npm install @stinkycomputing/sesame-api-client
 
 ## Quick Start
 
-### Node.js (Full Client with RPC)
-
-For Node.js applications that need the full RPC client:
-
 ```typescript
 import { SesameClient, CommandList } from '@stinkycomputing/sesame-api-client';
 
-// Create client
-const client = new SesameClient(8080);
+const client = new SesameClient(9000);
 
-// Build command list
 const cl = new CommandList();
-cl.sourceAdd('my-source', {
-  type: 'file',
-  path: '/path/to/video.mp4'
-});
+cl.sourceAdd('my-source', { type: 'file', path: '/path/to/video.mp4' });
 cl.compositorAdd('main', 1920, 1080, false);
 
-// Execute commands
 await client.execute(cl);
-
-// Listen to events
-client.on('status', (status) => {
-  console.log('Status update:', status);
-});
 ```
 
-### Browser (Protobuf Types Only)
+Works in the browser too — the browser entry point bundles `events` and other Node built-ins so `SesameClient`, `RPCClient`, and `WireProtocol` all work without polyfills.
 
-For browser applications that only need protobuf types (e.g., for decoding messages from WebSocket):
+## Protobuf Modules
 
-```typescript
-import { Sesame } from '@stinkycomputing/sesame-api-client/browser';
+Types are generated from `.proto` files under `sesame.v1.*`:
 
-// Decode a status message received from WebSocket
-const statusBytes = new Uint8Array(data);
-const status = Sesame.PB.StatusMessage.decode(statusBytes);
-const statusObj = Sesame.PB.StatusMessage.toObject(status, { longs: Number });
-console.log('Status:', statusObj);
+```typescript
+import { sesame } from '@stinkycomputing/sesame-api-client';
 ```
 
-**Browser entry point (`/browser`) includes:**
-- ✅ Protobuf types (`Sesame`, `sesame`, `Message`)
-- ✅ `CommandList` helper
-- ✅ `SesameBinaryProtocol` utilities
-- ✅ Logger abstraction
-- ❌ No Node.js dependencies (`events`, `ws`)
-- ❌ No `RPCClient` or `SesameConnection` classes
+| Module | Contents |
+|--------|----------|
+| `sesame.v1.wire` | Wire framing (FrameHeader, FrameType, MediaCodecData) |
+| `sesame.v1.common` | Shared types (Empty, Vec4, PropValue, EventTopic) |
+| `sesame.v1.sources` | Source config and transport |
+| `sesame.v1.outputs` | Output config and encoder settings |
+| `sesame.v1.compositor` | Scene graph, nodes, properties, animations |
+| `sesame.v1.audio` | Audio mixer and channels |
+| `sesame.v1.recorder` | Recorder, clips, playlists |
+| `sesame.v1.jobs` | Background export/import jobs |
+| `sesame.v1.status` | Status polling and event subscriptions |
+| `sesame.v1.commands` | Command list items |
+| `sesame.v1.rpc` | RPC message envelope (Request/Response/Event) |
 
-## API Structure
+## Wire Protocol
 
-### Legacy API (Sesame.PB)
+Every websocket message is framed as:
 
-The legacy API uses the `Sesame.PB` namespace:
-
-```typescript
-import { Sesame } from '@stinkycomputing/sesame-api-client';
-
-const msg: Sesame.PB.AddSourceMessage = {
-  id: 'source1',
-  type: Sesame.PB.SourceType.ST_FILE,
-  // ...
-};
+```
+[4-byte LE header_size][FrameHeader protobuf][payload bytes]
 ```
 
-### New Modular API (sesame.v1.*)
-
-The new API is organized into domain-specific modules:
+`WireProtocol.serialize` / `WireProtocol.parse` handle this:
 
 ```typescript
-import { sesame } from '@stinkycomputing/sesame-api-client';
+import { WireProtocol, sesame } from '@stinkycomputing/sesame-api-client';
 
-const msg: sesame.v1.sources.SourceAddRequest = {
-  id: 'source1',
-  type: sesame.v1.sources.SourceType.SOURCE_TYPE_FILE,
-  // ...
-};
-```
+// serialize
+const frame = WireProtocol.serialize(
+  { type: sesame.v1.wire.FrameType.FRAME_TYPE_RPC },
+  rpcPayload,
+);
 
-#### Available Modules
+// parse
+const parsed = WireProtocol.parse(incoming);
+if (parsed.valid) {
+  // parsed.header.type, parsed.payload
+}
+```
 
-- `sesame.v1.common` - Common types (Empty, Vec4, PropValue, etc.)
-- `sesame.v1.sources` - Source management
-- `sesame.v1.outputs` - Output management
-- `sesame.v1.compositor` - Compositor and scene graph
-- `sesame.v1.audio` - Audio mixer
-- `sesame.v1.recorder` - Recorder and clips
-- `sesame.v1.jobs` - Background jobs (export/import)
-- `sesame.v1.status` - Status and events
-- `sesame.v1.commands` - Command list system
-- `sesame.v1.rpc` - RPC protocol
+Frame types: `FRAME_TYPE_RPC`, `FRAME_TYPE_VIDEO`, `FRAME_TYPE_AUDIO`, `FRAME_TYPE_MUXED`, `FRAME_TYPE_DECODER_DATA`.
 
-## Command List Helper
+## Command List
 
-The `CommandList` class provides a fluent API for building command sequences:
+`CommandList` builds a batch of operations to send in one `execute` call:
 
 ```typescript
 const cl = new CommandList();
 
-// Add source
-cl.sourceAdd('cam1', {
-  type: 'decklink',
-  deviceIndex: 0
-});
-
-// Add compositor
+cl.sourceAdd('cam1', { type: 'decklink', deviceIndex: 0 });
 cl.compositorAdd('main', 1920, 1080, false);
+cl.nodeAdd('main', 'cam1-node', 'source', { sourceId: 'cam1' });
 
-// Add node to compositor
-cl.nodeAdd('main', 'cam1-node', 'source', {
-  sourceId: 'cam1'
-});
-
-// Set properties
 cl.propertySet(
   { compositor: 'main', node: 'cam1-node' },
-  'transform',
-  'position',
-  { vecValue: { r: 100, g: 100 } }
+  'transform', 'position',
+  { vecValue: { r: 100, g: 100 } },
 );
 
-// Transport control
 cl.transportCommand('cam1', { type: 'play' });
 
-// Execute all commands
 await client.execute(cl);
 ```
 
 ### Animations
 
-Use the `keyframe()` helper to build type-safe animation keyframes. The easing parameters are constrained to the `EaseKind` enum, so invalid values are caught at compile time:
-
 ```typescript
 import { CommandList, keyframe, EaseKind, sesame } from '@stinkycomputing/sesame-api-client';
 
 const cl = new CommandList();
-
 cl.propertyAnimate(
-  { compositor: 'main', node: 'cam1-node' },  // property domain
-  'cam1-node',                                  // address
-  'opacity',                                    // property name
-  sesame.v1.compositor.AnimationChannelEvaluationMode.HOLD,  // before
-  sesame.v1.compositor.AnimationChannelEvaluationMode.HOLD,  // after
+  { compositor: 'main', node: 'cam1-node' },
+  'cam1-node', 'opacity',
+  sesame.v1.compositor.AnimationChannelEvaluationMode.HOLD,
+  sesame.v1.compositor.AnimationChannelEvaluationMode.HOLD,
   [
     keyframe(0,       { floatValue: 0.0 }),
     keyframe(500000,  { floatValue: 1.0 }, EaseKind.QUADRATIC_INOUT),
     keyframe(1000000, { floatValue: 0.5 }, EaseKind.CUBIC_IN, EaseKind.CUBIC_OUT),
-  ]
+  ],
 );
 ```
 
-The `keyframe(timeUs, value, easingIn?, easingOut?)` parameters:
-- **timeUs** — time in microseconds
-- **value** — a `PropValue` (`floatValue`, `intValue`, `vec4Value`, `stringValue`, or `boolValue`)
-- **easingIn** *(optional)* — easing curve entering this keyframe (`EaseKind`)
-- **easingOut** *(optional)* — easing curve leaving this keyframe (`EaseKind`)
+`keyframe(timeUs, value, easingIn?, easingOut?)` — time in microseconds, value is a `PropValue`, easing uses `EaseKind`.
 
-## Deployment Notes
+## Bundling
 
-When using this package in a bundled application (e.g., with esbuild):
-
-- **Bundle the package**: Include `@stinkycomputing/sesame-api-client` in your bundle for zero-dependency deployment
-- **External native deps**: Only mark native binary modules as external (`ws`, `bufferutil`, `utf-8-validate`)
-- **Production install**: Only `npm install` the native dependencies in production
-
-This approach gives you:
-- ✅ Single bundle file with all code
-- ✅ Minimal production dependencies (3 packages)
-- ✅ Fast deployment
-- ✅ No version conflicts
+All dependencies (`events`, `long`, `protobufjs`) are pure JS — no native modules. The package bundles cleanly with esbuild or similar without any special `external` config.
 
 ## Publishing
 
-The package is published manually to npm from a local machine.
-
-### Prerequisites (one-time setup)
-
-1. Create the `@stinkycomputing` organization on [npmjs.com](https://www.npmjs.com/org/create)
-2. Log in to npm: `npm login`
-
-### Release process
-
-1. Update the version in `package.json`
-2. Build: `npm run build`
-3. Publish:
-   - **Stable release:** `npm publish --access public`
-   - **Prerelease:** `npm publish --access public --tag alpha` (or `beta`, etc.)
-4. Commit and tag: `git tag api-client-vX.Y.Z && git push origin api-client-vX.Y.Z`
+1. Bump version in `package.json`
+2. `npm run build`
+3. `npm publish --access public` (or `--tag alpha` for prereleases)
+4. `git tag api-client-vX.Y.Z && git push origin api-client-vX.Y.Z`
 
 ## License
 
 MIT
-