@ottervoice/protocol

Documentation

---

Documentation / @ottervoice/protocol

@ottervoice/protocol

Versioned JSON wire protocol for transporting OtterVoice session events across processes and native boundaries.

Install

npm install @ottervoice/core @ottervoice/protocol

Usage

import { encodeMessage, parseMessage, serializeMessage } from '@ottervoice/protocol';

const encoded = serializeMessage(encodeMessage('asr_final', {
  text: 'Hello',
  confidence: 0.98,
}));
const message = parseMessage(encoded);

The package exports the protocol version, supported message types, envelope types, serializers, parsers, and runtime validation helpers.

Links

Documentation · GitHub

License

MIT

Classes

ProtocolError

Defined in: packages/protocol/src/index.ts:57

Thrown when JSON is malformed or fails protocol validation.

Extends

• Error

Constructors

Constructor

new ProtocolError(message): ProtocolError;

Defined in: packages/protocol/src/index.ts:61

Parameters

Parameter	Type	Description
message	string	Human-readable validation / parse failure.

Returns

ProtocolError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
cause?	public	unknown	The cause of the error.	Error.cause	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
message	public	string	-	Error.message	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077
name	public	string	-	Error.name	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076
stack?	public	string	-	Error.stack	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078
stackTraceLimit	static	number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	Error.stackTraceLimit	node_modules/.bun/@types+node@26.0.1/node_modules/@types/node/globals.d.ts:67

Methods

captureStackTrace()

Call Signature

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.bun/@types+node@26.0.1/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
targetObject	object
constructorOpt?	Function

Returns

void

Inherited from

Error.captureStackTrace

Call Signature

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.bun/bun-types@1.3.14/node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters

Parameter	Type
targetObject	object
constructorOpt?	Function

Returns

void

Inherited from

Error.captureStackTrace

isError()

static isError(value): value is Error;

Defined in: node_modules/.bun/bun-types@1.3.14/node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters

Parameter	Type	Description
value	unknown	The value to check

Returns

value is Error

True if the value is an instance of Error, false otherwise

Inherited from

Error.isError

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.bun/@types+node@26.0.1/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
err	Error
stackTraces	CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

Interfaces

ProtocolEnvelope

Defined in: packages/protocol/src/index.ts:40

Versioned JSON envelope for one session event on the wire.

Type Parameters

Type Parameter	Default type	Description
T extends ProtocolMessageType	ProtocolMessageType	Event name; narrows ProtocolEnvelope.payload.

Properties

Property	Type	Description	Defined in
payload	VoiceSessionEventMap[T]	Event payload matching the core session event map.	packages/protocol/src/index.ts:48
type	T	Event name (same keys as core VoiceSessionEventMap).	packages/protocol/src/index.ts:46
v	1	Protocol schema version; must equal PROTOCOL_VERSION.	packages/protocol/src/index.ts:44

Type Aliases

ProtocolMessageType

type ProtocolMessageType = keyof VoiceSessionEventMap;

Defined in: packages/protocol/src/index.ts:15

Event name carried in ProtocolEnvelope.type (mirrors core session events).

---

VoiceProtocolMessage

type VoiceProtocolMessage = { [T in ProtocolMessageType]: ProtocolEnvelope<T> }[ProtocolMessageType];

Defined in: packages/protocol/src/index.ts:52

Discriminated union of all protocol envelopes.

Variables

PROTOCOL_MESSAGE_TYPES

const PROTOCOL_MESSAGE_TYPES: readonly ProtocolMessageType[];

Defined in: packages/protocol/src/index.ts:18

Every event type that may appear on the wire, in a stable order.

---

PROTOCOL_VERSION

const PROTOCOL_VERSION: 1;

Defined in: packages/protocol/src/index.ts:12

Bumped when the envelope shape or payload contracts change incompatibly.

Functions

encodeMessage()

function encodeMessage<T>(type, payload): ProtocolEnvelope<T>;

Defined in: packages/protocol/src/index.ts:74

Build a typed envelope for an event.

Type Parameters

Type Parameter
T extends keyof VoiceSessionEventMap

Parameters

Parameter	Type	Description
type	T	Event name.
payload	VoiceSessionEventMap[T]	Payload for that event.

Returns

ProtocolEnvelope<T>

Envelope ready for serializeMessage.

---

isProtocolMessage()

function isProtocolMessage(value): value is VoiceProtocolMessage;

Defined in: packages/protocol/src/index.ts:99

Structurally validate a decoded value as a ProtocolEnvelope without trusting the version. Returns a boolean type-guard.

Parameters

Parameter	Type
value	unknown

Returns

value is VoiceProtocolMessage

---

parseMessage()

function parseMessage(raw): VoiceProtocolMessage;

Defined in: packages/protocol/src/index.ts:119

Parse a JSON string into a validated ProtocolEnvelope.

Throws ProtocolError on malformed JSON, an unknown/old version, an unknown message type, or a missing payload.

Parameters

Parameter	Type	Description
raw	string	JSON string from the wire.

Returns

VoiceProtocolMessage

A typed VoiceProtocolMessage.

---

serializeMessage()

function serializeMessage(message): string;

Defined in: packages/protocol/src/index.ts:87

Serialize an envelope (or any event via encodeMessage) to JSON.

Parameters

Parameter	Type	Description
message	VoiceProtocolMessage	Validated VoiceProtocolMessage.

Returns

string

JSON string for transport.