@ceralive/cerastream 2026.6.0-rc.1 → 2026.6.1

package/README.md

@@ -1,41 +1,30 @@
-# @ceralive/cerastream (TypeScript bindings)
+# @ceralive/cerastream
 
-Type-safe control-IPC **schema + client surface** for the cerastream Rust
-streaming engine. This package is the **public contract** (ADR-0002 Decision 13):
-a CI-published npm package — **not** a sibling `link:` dep — consumable by Bun with
-zero native dependencies.
+Type-safe control-IPC **schema + client** for the cerastream streaming engine.
+A zero-native-dependency package — the published contract for driving the
+engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 
 - JSON-RPC 2.0 envelope + `hello` handshake schemas
-- The eight v1 control methods (params + result Zod schemas + inferred types)
+- The eight v1 control methods (Zod params + result schemas + inferred types)
 - The seven server-push event payloads (discriminated union)
-- Two-tier error codes (Tier 1 RPC + Tier 2 runtime, 1:1 with CeraUI)
+- Two-tier error codes (RPC + runtime)
 - A unified engine config schema (= `start` params)
-- A `CerastreamClient` interface + `connect()` factory (Bun-native UDS transport)
+- A `CerastreamClient` interface + `connect()` factory (UDS transport)
 
-> **Schema + client.** The Zod schemas, types, and constants are the **frozen**
-> wire contract; `connect()` drives that contract over a Bun-native NDJSON/UDS
-> transport (no native deps). The schema shape is unchanged from the v0.1.0-stub
-> freeze — this release adds the runtime client behind it (plan Task 31).
+The Zod schemas, types, and constants are the frozen wire contract; `connect()`
+drives that contract over an NDJSON/UDS transport with no native dependencies.
 
-See [`API.md`](./API.md) for the full exported surface, ADR-0002
-([`../../docs/adr/ADR-0002-control-ipc.md`](../../docs/adr/ADR-0002-control-ipc.md))
-for the protocol decision, and `schema.md`
-([`../../docs/adr/schema.md`](../../docs/adr/schema.md)) for the v1 message
-inventory.
-
-## Install / develop
+## Install
 
 ```bash
-bun install
-bun run typecheck   # tsc --noEmit
-bun test            # schema round-trip + stub-honesty + count + skew guards
-bun run build       # emit dist/
+npm i @ceralive/cerastream
+# or
+bun add @ceralive/cerastream
 ```
 
-## Usage (schema today, client after Task 31)
+## Usage
 
-The schemas are usable now — validate any control message on either side of the
-wire:
+The schemas validate any control message on either side of the wire:
 
 ```ts
 import { startParamsSchema, eventParamsSchema } from "@ceralive/cerastream";
@@ -71,18 +60,21 @@ await client.switchInput({ input_id: "video0" });
 await client.stop();
 
 sub.close();
-await client.close(); // closes the connection; never respawns the engine (ADR-0005)
+await client.close(); // closes the connection; never spawns the engine
 ```
 
-`connect()` honors `socketPath` (default: the resolved `/run/cerastream/control.sock`),
-`requestTimeoutMs`, and `autoReconnect` (capped backoff + re-handshake + re-subscribe).
-The engine is a systemd-owned service — the client connects, it never spawns it.
+`connect()` honours `socketPath`, `requestTimeoutMs`, and `autoReconnect`
+(capped backoff + re-handshake + re-subscribe). The engine runs as a
+systemd-owned service — the client connects to it and never spawns it.
+
+## Versioning
+
+Two independent version axes. The **wire-schema version** (`PROTOCOL_VERSION` +
+`SCHEMA_VERSION`) is pinned cross-language with the engine and is additive-only
+within `cerastream-ipc/1`. The **npm package version** is CalVer
+(`YYYY.MINOR.PATCH`) with SemVer intent applied to the exported TypeScript
+surface; release candidates use `-rc.N` (npm `next` dist-tag).
 
-## Versioning — SemVer on top of CalVer
+## License
 
-Two version axes, kept separate: the **wire-schema version** (`PROTOCOL_VERSION` +
-`SCHEMA_VERSION`) is pinned cross-language with the Rust engine and is additive-only
-within `cerastream-ipc/1`; the **npm package version** (`package.json`) is CalVer
-(`YYYY.MINOR.PATCH`) for the library release line, with SemVer intent applied to the
-exported TypeScript surface. Release candidates use `-rc.N` (npm `next` dist-tag).
-Full policy + the tag-driven publish pipeline: [`CHANGELOG.md`](./CHANGELOG.md).
+GPL-3.0

package/dist/events.d.ts

@@ -42,6 +42,7 @@ export declare const deviceEventSchema: z.ZodObject<{
             width: z.ZodOptional<z.ZodNumber>;
             height: z.ZodOptional<z.ZodNumber>;
             framerate: z.ZodOptional<z.ZodString>;
+            media_type: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -127,6 +128,7 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             width: z.ZodOptional<z.ZodNumber>;
             height: z.ZodOptional<z.ZodNumber>;
             framerate: z.ZodOptional<z.ZodString>;
+            media_type: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -207,6 +209,7 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 width: z.ZodOptional<z.ZodNumber>;
                 height: z.ZodOptional<z.ZodNumber>;
                 framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
@@ -291,6 +294,7 @@ export declare const eventSchemas: {
                 width: z.ZodOptional<z.ZodNumber>;
                 height: z.ZodOptional<z.ZodNumber>;
                 framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
         }, z.core.$strip>;
     }, z.core.$strip>;

package/dist/messages.d.ts

@@ -121,6 +121,7 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             width: z.ZodOptional<z.ZodNumber>;
             height: z.ZodOptional<z.ZodNumber>;
             framerate: z.ZodOptional<z.ZodString>;
+            media_type: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -190,6 +191,60 @@ export declare const previewSessionResultSchema: z.ZodObject<{
     }, z.core.$strip>], "kind">;
 }, z.core.$strip>;
 export type PreviewSessionResult = z.infer<typeof previewSessionResultSchema>;
+export declare const videoSourceCapSchema: z.ZodObject<{
+    id: z.ZodString;
+    supports_audio: z.ZodBoolean;
+    supports_resolution_override: z.ZodBoolean;
+    supports_framerate_override: z.ZodBoolean;
+    default_resolution: z.ZodString;
+    default_framerate: z.ZodNumber;
+}, z.core.$strip>;
+export type VideoSourceCap = z.infer<typeof videoSourceCapSchema>;
+export declare const bitrateRangeCapsSchema: z.ZodObject<{
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+    unit: z.ZodString;
+}, z.core.$strip>;
+export type BitrateRangeCaps = z.infer<typeof bitrateRangeCapsSchema>;
+export declare const encoderCapsSchema: z.ZodObject<{
+    codecs: z.ZodArray<z.ZodString>;
+    bitrate_range: z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+        unit: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EncoderCaps = z.infer<typeof encoderCapsSchema>;
+export declare const platformCapsSchema: z.ZodObject<{
+    supports_h265: z.ZodBoolean;
+    hardware_accelerated: z.ZodBoolean;
+    max_resolution: z.ZodString;
+}, z.core.$strip>;
+export type PlatformCaps = z.infer<typeof platformCapsSchema>;
+export declare const getCapabilitiesResultSchema: z.ZodObject<{
+    platform: z.ZodObject<{
+        supports_h265: z.ZodBoolean;
+        hardware_accelerated: z.ZodBoolean;
+        max_resolution: z.ZodString;
+    }, z.core.$strip>;
+    encoder: z.ZodObject<{
+        codecs: z.ZodArray<z.ZodString>;
+        bitrate_range: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        supports_audio: z.ZodBoolean;
+        supports_resolution_override: z.ZodBoolean;
+        supports_framerate_override: z.ZodBoolean;
+        default_resolution: z.ZodString;
+        default_framerate: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GetCapabilitiesResult = z.infer<typeof getCapabilitiesResultSchema>;
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
 export declare const V1_METHODS: readonly ["start", "stop", "reload-config", "set-bitrate", "switch-input", "list-devices", "subscribe-events", "preview-session"];
 export type V1Method = (typeof V1_METHODS)[number];
@@ -332,6 +387,7 @@ export declare const requestSchemas: {
                     width: z.ZodOptional<z.ZodNumber>;
                     height: z.ZodOptional<z.ZodNumber>;
                     framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;

package/dist/messages.js

@@ -104,6 +104,36 @@ export const previewSessionResultSchema = z.object({
         z.object({ kind: z.literal("webrtc"), sdp: z.string().optional() }),
     ]),
 });
+// ---- 9. get-capabilities ----
+// Deliberately absent from V1_METHODS / requestSchemas: it is an additive
+// standalone schema, so the frozen eight-method contract-count stays eight.
+export const videoSourceCapSchema = z.object({
+    id: z.string(),
+    supports_audio: z.boolean(),
+    supports_resolution_override: z.boolean(),
+    supports_framerate_override: z.boolean(),
+    default_resolution: z.string(),
+    default_framerate: z.number().int(),
+});
+export const bitrateRangeCapsSchema = z.object({
+    min: z.number().int(),
+    max: z.number().int(),
+    unit: z.string(), // "bps" or "kbps"
+});
+export const encoderCapsSchema = z.object({
+    codecs: z.array(z.string()),
+    bitrate_range: bitrateRangeCapsSchema,
+});
+export const platformCapsSchema = z.object({
+    supports_h265: z.boolean(),
+    hardware_accelerated: z.boolean(),
+    max_resolution: z.string(),
+});
+export const getCapabilitiesResultSchema = z.object({
+    platform: platformCapsSchema,
+    encoder: encoderCapsSchema,
+    sources: z.array(videoSourceCapSchema),
+});
 // ---- method registry (count-assertion source of truth) ----
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
 export const V1_METHODS = [

package/dist/types.d.ts

@@ -85,6 +85,7 @@ export declare const captureCapSchema: z.ZodObject<{
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     framerate: z.ZodOptional<z.ZodString>;
+    media_type: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureCap = z.infer<typeof captureCapSchema>;
 export declare const captureDeviceSchema: z.ZodObject<{
@@ -99,6 +100,7 @@ export declare const captureDeviceSchema: z.ZodObject<{
         width: z.ZodOptional<z.ZodNumber>;
         height: z.ZodOptional<z.ZodNumber>;
         framerate: z.ZodOptional<z.ZodString>;
+        media_type: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type CaptureDevice = z.infer<typeof captureDeviceSchema>;

package/dist/types.js

@@ -53,6 +53,7 @@ export const captureCapSchema = z.object({
     width: z.number().int().optional(),
     height: z.number().int().optional(),
     framerate: z.string().optional(), // e.g. "30/1"
+    media_type: z.string().optional(), // e.g. "video/x-h265"; additive, absent on legacy producers
 });
 export const captureDeviceSchema = z.object({
     input_id: z.string(), // stable id used by switch-input

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ceralive/cerastream",
-  "version": "2026.6.0-rc.1",
-  "description": "Type-safe TypeScript bindings + IPC client for the cerastream Rust streaming engine (JSON-RPC 2.0 / NDJSON over UDS). See ADR-0002.",
+  "version": "2026.6.1",
+  "description": "Type-safe TypeScript schema + IPC client for the cerastream streaming engine (JSON-RPC 2.0 / NDJSON over a Unix domain socket).",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",