@ceralive/cerastream 2026.8.1 → 2026.9.0

package/README.md

@@ -8,6 +8,7 @@ engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 - The eight v1 control methods (Zod params + result schemas + inferred types)
 - The nine server-push event payloads (discriminated union)
 - Two-tier error codes (RPC + runtime)
+- Typed capture-probe causes retained on runtime events and rejected-start exceptions
 - A unified engine config schema (= `start` params)
 - A `CerastreamClient` interface + `connect()` factory (UDS transport)
 - Additive `client.getCapabilities()` discovery for platform, source, encoder, and

package/dist/client.js

@@ -183,7 +183,7 @@ class ClientImpl {
         if (!parsed.success)
             return;
         const { id, error } = parsed.data;
-        const rpcErr = new CerastreamRpcError(error.code, error.message, error.data?.code, id);
+        const rpcErr = new CerastreamRpcError(error.code, error.message, error.data?.code, id, error.data);
         if (id == null)
             return; // parse error with null id — no request to settle.
         const pending = this.pending.get(id);

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ export declare const PROTOCOL_VERSION: 'cerastream-ipc/1';
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export declare const SCHEMA_VERSION: '0.11.0';
+export declare const SCHEMA_VERSION: '0.12.0';
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export declare const DEFAULT_IPC_DIR: '/run/cerastream';
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */

package/dist/constants.js

@@ -11,7 +11,7 @@ export const PROTOCOL_VERSION = 'cerastream-ipc/1';
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export const SCHEMA_VERSION = '0.11.0';
+export const SCHEMA_VERSION = '0.12.0';
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export const DEFAULT_IPC_DIR = '/run/cerastream';
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */

package/dist/errors.d.ts

@@ -20,7 +20,11 @@ export declare class CerastreamRpcError extends Error {
     readonly dataCode: string | undefined;
     /** The request id this error answered, when present. */
     readonly requestId: number | string | null;
-    constructor(code: number, message: string, dataCode: string | undefined, requestId: number | string | null);
+    /** Full JSON-RPC `error.data` object, retained for additive typed detail. */
+    readonly data?: unknown;
+    constructor(code: number, message: string, dataCode: string | undefined, requestId: number | string | null, data?: unknown);
+    /** Typed capture-probe failures carried by a rejected stream start. */
+    captureCauses(): readonly CaptureCauseEntry[];
 }
 /**
  * Machine-readable classification of a {@link CerastreamConnectionError}, stable
@@ -91,6 +95,21 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
     srtla_no_connections: "srtla_no_connections";
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
+export declare const captureCauseSchema: z.ZodEnum<{
+    device_busy: "device_busy";
+    negotiation_failed: "negotiation_failed";
+    no_signal: "no_signal";
+}>;
+export type CaptureCause = z.infer<typeof captureCauseSchema>;
+export declare const captureCauseEntrySchema: z.ZodObject<{
+    device: z.ZodString;
+    cause: z.ZodEnum<{
+        device_busy: "device_busy";
+        negotiation_failed: "negotiation_failed";
+        no_signal: "no_signal";
+    }>;
+}, z.core.$strip>;
+export type CaptureCauseEntry = z.infer<typeof captureCauseEntrySchema>;
 /**
  * Why a capture device became `capture_unrecoverable` — the `reason` field of the
  * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.

package/dist/errors.js

@@ -23,12 +23,21 @@ export class CerastreamRpcError extends Error {
     dataCode;
     /** The request id this error answered, when present. */
     requestId;
-    constructor(code, message, dataCode, requestId) {
+    /** Full JSON-RPC `error.data` object, retained for additive typed detail. */
+    data;
+    constructor(code, message, dataCode, requestId, data) {
         super(message);
         this.name = 'CerastreamRpcError';
         this.code = code;
         this.dataCode = dataCode;
         this.requestId = requestId;
+        if (data !== undefined)
+            this.data = data;
+    }
+    /** Typed capture-probe failures carried by a rejected stream start. */
+    captureCauses() {
+        const parsed = rpcCaptureDataSchema.safeParse(this.data);
+        return parsed.success ? parsed.data.capture_causes : [];
     }
 }
 /**
@@ -129,6 +138,16 @@ export const processErrorCodeSchema = z.enum([
     // would be lying. Always carries a captureUnrecoverableReasonSchema `reason`.
     'capture_unrecoverable',
 ]);
+export const captureCauseSchema = z.enum(['negotiation_failed', 'no_signal', 'device_busy']);
+export const captureCauseEntrySchema = z.object({
+    device: z.string(),
+    cause: captureCauseSchema,
+});
+const rpcCaptureDataSchema = z
+    .object({
+    capture_causes: z.array(captureCauseEntrySchema),
+})
+    .passthrough();
 /**
  * Why a capture device became `capture_unrecoverable` — the `reason` field of the
  * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.

package/dist/events.d.ts

@@ -239,6 +239,11 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
     }>;
     reason: z.ZodOptional<z.ZodString>;
     selected: z.ZodOptional<z.ZodBoolean>;
+    capture_cause: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        negotiation_failed: "negotiation_failed";
+        no_signal: "no_signal";
+    }>>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
 export type RuntimeErrorEvent = z.infer<typeof runtimeErrorEventSchema>;
@@ -457,6 +462,11 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     reason: z.ZodOptional<z.ZodString>;
     selected: z.ZodOptional<z.ZodBoolean>;
+    capture_cause: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        negotiation_failed: "negotiation_failed";
+        no_signal: "no_signal";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
     seq: z.ZodNumber;
@@ -649,6 +659,11 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         }>;
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
+        capture_cause: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            negotiation_failed: "negotiation_failed";
+            no_signal: "no_signal";
+        }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
         seq: z.ZodNumber;
@@ -850,6 +865,11 @@ export declare const eventSchemas: {
         }>;
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
+        capture_cause: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            negotiation_failed: "negotiation_failed";
+            no_signal: "no_signal";
+        }>>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{
         type: z.ZodLiteral<"preview">;

package/dist/events.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { processErrorCodeSchema, processErrorSourceSchema } from './errors.js';
+import { captureCauseSchema, processErrorCodeSchema, processErrorSourceSchema } from './errors.js';
 import { captureDeviceSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeFallbackSchema, previewEncodeModeSchema, streamStateSchema, } from './types.js';
 // Server → client `event` notifications, delivered after `subscribe-events`
 // (schema.md "Events"). Each event is the inner `params` of an rpcEventSchema:
@@ -119,6 +119,8 @@ export const runtimeErrorEventSchema = z.object({
     source: processErrorSourceSchema,
     reason: z.string().optional(), // structured replacement for the stderr <reason>
     selected: z.boolean().optional(), // additive (0.11.0): the degraded input is the operator's OWN selection, so the stream will not move itself and only they can pick another — a materially different operator response than a degraded non-selected input, and one to branch on rather than string-match. Absent ⇒ false
+    // The code stays capture_video_error because older consumers reject unknown code values.
+    capture_cause: captureCauseSchema.optional(),
 });
 /** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/cerastream",
-	"version": "2026.8.1",
+	"version": "2026.9.0",
 	"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",