@jambonz/tap-types

Tap envelope schema, JWT claim types, and JSON Schema for jambonz callscope.

This package provides the protocol contracts shared between the tap-server and callscope SPA. Both packages depend on @jambonz/tap-types for type safety and schema validation.

Installation

npm install @jambonz/tap-types

Usage

TypeScript types

import type { TapEnvelope, TapJwtClaims } from '@jambonz/tap-types';

// Type-safe envelope handling
function handleEnvelope(envelope: TapEnvelope) {
  if (envelope.type === 'frame') {
    console.log(`${envelope.direction}: ${JSON.stringify(envelope.payload)}`);
  } else {
    console.log(`lifecycle event: ${envelope.event}`);
  }
}

// JWT claims for X-Jambonz-Tap header
const claims: TapJwtClaims = {
  tap_url: 'wss://tap.example.com/observer',
  session_id: '7b3f...',
  exp: Math.floor(Date.now() / 1000) + 60,
  iat: Math.floor(Date.now() / 1000),
};

JSON Schema validation (with ajv)

import Ajv from 'ajv';
import { TapEnvelopeSchema } from '@jambonz/tap-types';

const ajv = new Ajv();
const validate = ajv.compile(TapEnvelopeSchema);

const envelope = JSON.parse(message);
if (!validate(envelope)) {
  console.error('Invalid envelope:', validate.errors);
}

Envelope types

Frame (type: "frame")

Mirrored app-WS frames between jambonz and the customer's application:

• direction: "to_app" — frames the FS sends to the customer's app (e.g. session:new, verb:hook)
• direction: "from_app" — frames the customer's app sends back (e.g. verb commands, redirects)
• payload — the original frame content (opaque to the tap)

Lifecycle (type: "lifecycle")

Call leg events:

• leg_created — new leg spawned (B-leg via dial)
• leg_adulted — child leg promoted to independent session via LCC
• leg_ended — leg terminated

License

MIT