@fonoster/common 0.27.0 → 0.31.0

package/dist/session/schema.js

@@ -0,0 +1,448 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_COMMAND_SCHEMAS = exports.APPBRIDGE_MESSAGE_SCHEMAS = exports.recordNoteSchema = exports.usageReportSchema = exports.handoffSchema = exports.resumeSchema = exports.holdSchema = exports.transferCompleteSchema = exports.transferSchema = exports.TRANSFER_MODES = exports.dtmfSendSchema = exports.hangupSchema = exports.clearSchema = exports.markCommandSchema = exports.subscribeSchema = exports.SUBSCRIBABLE_EVENTS = exports.listenUpdateSchema = exports.playSchema = exports.speakSchema = exports.amdResultSchema = exports.transferAnsweredSchema = exports.dtmfEventSchema = exports.markEventSchema = exports.outputInterruptedSchema = exports.outputDoneSchema = exports.outputStartedSchema = exports.transcriptPartialSchema = exports.turnEstimateSchema = exports.turnBackchannelSchema = exports.turnResumedSchema = exports.turnEndedSchema = exports.turnLikelyEndedSchema = exports.turnUserStartedSchema = exports.errorSchema = exports.ERROR_CODES = exports.sessionEndSchema = exports.SESSION_END_REASONS = exports.sessionStartSchema = exports.SESSION_PROTOCOL = void 0;
+exports.sessionProtocolDocument = sessionProtocolDocument;
+// The fonoster.session.v1 messages (fonoster protocol), as JSON Schema. These schemas are the source
+// of truth: TypeScript types are derived from them below, and schema/session.v1.json is exported
+// from them for other languages (see scripts/export-session-schema.ts).
+//
+// Every schema allows extra fields: both sides ignore unknown fields (voice-session, "Message
+// envelope and versioning"), so the protocol only grows.
+exports.SESSION_PROTOCOL = "fonoster.session.v1";
+const id = { type: "string", minLength: 1, maxLength: 128 };
+const catalogId = { type: "string", minLength: 1 };
+// ---- appbridge → app ---------------------------------------------------------------------
+exports.sessionStartSchema = {
+    type: "object",
+    required: [
+        "type",
+        "protocol",
+        "sessionRef",
+        "callRef",
+        "appRef",
+        "direction",
+        "from",
+        "to",
+        "metadata",
+        "handoff",
+        "audio",
+        "tracks",
+        "speech"
+    ],
+    properties: {
+        type: { const: "session.start" },
+        protocol: { const: exports.SESSION_PROTOCOL },
+        sessionRef: { type: "string" },
+        callRef: { type: "string" },
+        appRef: { type: "string" },
+        direction: { enum: ["inbound", "outbound"] },
+        from: { type: "string" },
+        to: { type: "string" },
+        metadata: { type: "object" },
+        handoff: { oneOf: [{ type: "null" }, { type: "object" }] },
+        // W3C traceparent of the call's span, so the app's spans join the call's trace (optional).
+        traceparent: { type: "string" },
+        audio: {
+            type: "object",
+            required: ["codec", "rate"],
+            properties: {
+                // The native format menu (voice-session OQ8, AO-B4); Opus is not offered over WebSocket.
+                codec: { enum: ["pcm16", "pcmu"] },
+                rate: { enum: [8000, 16000, 24000] }
+            }
+        },
+        tracks: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "side", "kind", "codec"],
+                properties: {
+                    id: { type: "integer", minimum: 0, maximum: 255 },
+                    side: { enum: ["inbound", "outbound"] },
+                    kind: { enum: ["audio"] },
+                    codec: { type: "string" }
+                }
+            }
+        },
+        speech: {
+            type: "object",
+            required: ["voice", "language"],
+            properties: { voice: { type: "string" }, language: { type: "string" } }
+        }
+    }
+};
+exports.SESSION_END_REASONS = [
+    "caller_hangup",
+    "app_hangup",
+    "transfer",
+    "handoff",
+    "error",
+    "timeout"
+];
+exports.sessionEndSchema = {
+    type: "object",
+    required: ["type", "reason"],
+    properties: {
+        type: { const: "session.end" },
+        reason: { enum: exports.SESSION_END_REASONS }
+    }
+};
+exports.ERROR_CODES = [
+    "bad_message",
+    "unknown_command",
+    "read_only",
+    "not_supported_by_protocol",
+    "provider_unavailable",
+    "provider_timeout",
+    "invalid_catalog_id",
+    "feature_not_supported",
+    "transfer_failed",
+    "transfer_not_answered",
+    "on_hold",
+    "queue_full",
+    "play_fetch_failed",
+    "key_unavailable",
+    "internal"
+];
+exports.errorSchema = {
+    type: "object",
+    required: ["type", "code", "message", "fatal"],
+    properties: {
+        type: { const: "error" },
+        code: { type: "string" },
+        message: { type: "string" },
+        fatal: { type: "boolean" },
+        relatesTo: id
+    }
+};
+exports.turnUserStartedSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "turn.user_started" } }
+};
+exports.turnLikelyEndedSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: { type: { const: "turn.likely_ended" }, text: { type: "string" } }
+};
+exports.turnEndedSchema = {
+    type: "object",
+    required: ["type", "text", "language", "confidence", "durationMs"],
+    properties: {
+        type: { const: "turn.ended" },
+        text: { type: "string" },
+        language: { type: "string" },
+        confidence: { type: "number", minimum: 0, maximum: 1 },
+        durationMs: { type: "number", minimum: 0 },
+        /** No speech followed turn.user_started for 10 s (noise, a dropped line). */
+        abandoned: { type: "boolean" }
+    }
+};
+exports.turnResumedSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "turn.resumed" } }
+};
+exports.turnBackchannelSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: { type: { const: "turn.backchannel" }, text: { type: "string" } }
+};
+exports.turnEstimateSchema = {
+    type: "object",
+    required: ["type", "eot", "speaking", "kind"],
+    properties: {
+        type: { const: "turn.estimate" },
+        eot: { type: "number", minimum: 0, maximum: 1 },
+        speaking: { type: "boolean" },
+        kind: { enum: ["speech", "backchannel", "interruption", "none"] }
+    }
+};
+exports.transcriptPartialSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: {
+        type: { const: "transcript.partial" },
+        text: { type: "string" },
+        language: { type: "string" }
+    }
+};
+exports.outputStartedSchema = {
+    type: "object",
+    required: ["type", "id"],
+    properties: { type: { const: "output.started" }, id }
+};
+exports.outputDoneSchema = {
+    type: "object",
+    required: ["type", "id"],
+    properties: {
+        type: { const: "output.done" },
+        id,
+        heardMs: { type: "number", minimum: 0 }
+    }
+};
+exports.outputInterruptedSchema = {
+    type: "object",
+    required: ["type", "id", "heardText", "heardMs"],
+    properties: {
+        type: { const: "output.interrupted" },
+        id,
+        heardText: { type: "string" },
+        heardMs: { type: "number", minimum: 0 }
+    }
+};
+exports.markEventSchema = {
+    type: "object",
+    required: ["type", "name", "cleared"],
+    properties: {
+        type: { const: "mark" },
+        name: { type: "string" },
+        cleared: { type: "boolean" }
+    }
+};
+exports.dtmfEventSchema = {
+    type: "object",
+    required: ["type", "digit"],
+    properties: {
+        type: { const: "dtmf" },
+        digit: { type: "string", pattern: "^[0-9A-D*#]$" }
+    }
+};
+/** A warm transfer's new party answered; the app may now send transfer.complete. */
+exports.transferAnsweredSchema = {
+    type: "object",
+    required: ["type", "relatesTo"],
+    properties: {
+        type: { const: "transfer.answered" },
+        relatesTo: id
+    }
+};
+/** Answering-machine detection, once per call, for apps with `amd` (add-roomr 4.3). */
+exports.amdResultSchema = {
+    type: "object",
+    required: ["type", "status", "confidence", "detector", "audioMs"],
+    properties: {
+        type: { const: "amd.result" },
+        status: { enum: ["human", "voicemail", "ivr", "machine", "unknown"] },
+        confidence: { type: "number", minimum: 0, maximum: 1 },
+        detector: { type: "string" },
+        /** How much caller audio the verdict is based on, from when the caller started speaking. */
+        audioMs: { type: "number", minimum: 0 },
+        /** Caller audio received before speech began (unset when the caller never spoke). */
+        speechOnsetMs: { type: "number", minimum: 0 },
+        /** Why detection could not run (status unknown): no_audio, no_speech, no_classifier, call_ended, … */
+        reason: { type: "string" }
+    }
+};
+// ---- app → appbridge ---------------------------------------------------------------------
+exports.speakSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: {
+        type: { const: "speak" },
+        id,
+        text: { type: "string" },
+        last: { type: "boolean" },
+        voice: catalogId,
+        language: catalogId,
+        interruptible: { type: "boolean" },
+        preempt: { type: "boolean" }
+    }
+};
+exports.playSchema = {
+    type: "object",
+    required: ["type", "url"],
+    properties: {
+        type: { const: "play" },
+        id,
+        url: { type: "string", pattern: "^https?://" },
+        loop: { type: "boolean" },
+        interruptible: { type: "boolean" },
+        preempt: { type: "boolean" }
+    }
+};
+exports.listenUpdateSchema = {
+    type: "object",
+    required: ["type"],
+    properties: {
+        type: { const: "listen.update" },
+        id,
+        language: catalogId,
+        hints: { type: "array", items: { type: "string" } },
+        /** How long the Turn Detector waits before turn.ended. */
+        patience: { enum: ["low", "normal", "high"] }
+    }
+};
+exports.SUBSCRIBABLE_EVENTS = [
+    "turn.estimate",
+    "transcript.partial"
+];
+exports.subscribeSchema = {
+    type: "object",
+    required: ["type", "events"],
+    properties: {
+        type: { const: "subscribe" },
+        id,
+        events: { type: "array", items: { type: "string" } }
+    }
+};
+exports.markCommandSchema = {
+    type: "object",
+    required: ["type", "name"],
+    properties: {
+        type: { const: "mark" },
+        name: { type: "string", minLength: 1 }
+    }
+};
+exports.clearSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "clear" }, id }
+};
+exports.hangupSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "hangup" }, id }
+};
+exports.dtmfSendSchema = {
+    type: "object",
+    required: ["type", "digits"],
+    properties: {
+        type: { const: "dtmf.send" },
+        id,
+        digits: { type: "string", pattern: "^[0-9A-D*#w]+$" }
+    }
+};
+exports.TRANSFER_MODES = ["cold", "warm", "refer"];
+exports.transferSchema = {
+    type: "object",
+    required: ["type", "to"],
+    properties: {
+        type: { const: "transfer" },
+        id,
+        to: { type: "string", minLength: 1 },
+        headers: { type: "object", additionalProperties: { type: "string" } },
+        mode: { enum: exports.TRANSFER_MODES },
+        /** Warm transfers: what the caller hears while waiting. */
+        music: { type: "string" }
+    }
+};
+exports.transferCompleteSchema = {
+    type: "object",
+    required: ["type", "id"],
+    properties: { type: { const: "transfer.complete" }, id }
+};
+exports.holdSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "hold" }, id, music: { type: "string" } }
+};
+exports.resumeSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "resume" }, id }
+};
+exports.handoffSchema = {
+    type: "object",
+    required: ["type", "app"],
+    properties: {
+        type: { const: "handoff" },
+        id,
+        app: { type: "string", minLength: 1 },
+        payload: { type: "object" }
+    }
+};
+/**
+ * Model token usage from Fonoster's own Autopilot (add-usage-metering D4). Reserved like
+ * record.note: accepted only from Autopilot agents and left out of the public docs.
+ */
+exports.usageReportSchema = {
+    type: "object",
+    required: ["type", "lines"],
+    properties: {
+        type: { const: "usage.report" },
+        id,
+        lines: {
+            type: "array",
+            minItems: 1,
+            maxItems: 64,
+            items: {
+                type: "object",
+                required: ["meter", "quantity", "provider", "keySource"],
+                additionalProperties: false,
+                properties: {
+                    meter: {
+                        enum: [
+                            "llm.tokens.in",
+                            "llm.tokens.out",
+                            "llm.tokens.cached",
+                            "embedding.tokens"
+                        ]
+                    },
+                    quantity: { type: "integer", minimum: 0 },
+                    provider: { type: "string", minLength: 1 },
+                    model: { type: "string", minLength: 1 },
+                    keySource: { enum: ["platform", "workspace"] }
+                }
+            }
+        }
+    }
+};
+exports.recordNoteSchema = {
+    type: "object",
+    required: ["type", "data"],
+    properties: {
+        type: { const: "record.note" },
+        id,
+        data: { type: "object" }
+    }
+};
+/** Schemas by message type, per direction. "mark" exists in both directions. */
+exports.APPBRIDGE_MESSAGE_SCHEMAS = {
+    "session.start": exports.sessionStartSchema,
+    "session.end": exports.sessionEndSchema,
+    error: exports.errorSchema,
+    "turn.user_started": exports.turnUserStartedSchema,
+    "turn.likely_ended": exports.turnLikelyEndedSchema,
+    "turn.ended": exports.turnEndedSchema,
+    "turn.resumed": exports.turnResumedSchema,
+    "turn.backchannel": exports.turnBackchannelSchema,
+    "turn.estimate": exports.turnEstimateSchema,
+    "transcript.partial": exports.transcriptPartialSchema,
+    "output.started": exports.outputStartedSchema,
+    "output.done": exports.outputDoneSchema,
+    "output.interrupted": exports.outputInterruptedSchema,
+    mark: exports.markEventSchema,
+    dtmf: exports.dtmfEventSchema,
+    "transfer.answered": exports.transferAnsweredSchema,
+    "amd.result": exports.amdResultSchema
+};
+exports.APP_COMMAND_SCHEMAS = {
+    speak: exports.speakSchema,
+    play: exports.playSchema,
+    "listen.update": exports.listenUpdateSchema,
+    subscribe: exports.subscribeSchema,
+    mark: exports.markCommandSchema,
+    clear: exports.clearSchema,
+    hangup: exports.hangupSchema,
+    "dtmf.send": exports.dtmfSendSchema,
+    transfer: exports.transferSchema,
+    "transfer.complete": exports.transferCompleteSchema,
+    hold: exports.holdSchema,
+    resume: exports.resumeSchema,
+    handoff: exports.handoffSchema,
+    "record.note": exports.recordNoteSchema,
+    "usage.report": exports.usageReportSchema
+};
+/** The whole protocol as one JSON Schema document, as exported to schema/session.v1.json. */
+function sessionProtocolDocument() {
+    return {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        $id: "https://fonoster.com/schemas/session/v1.json",
+        title: exports.SESSION_PROTOCOL,
+        description: "Messages of the Fonoster session protocol (a stream with protocol fonoster). Unknown types and fields must be ignored.",
+        protocol: exports.SESSION_PROTOCOL,
+        appBridgeToApp: exports.APPBRIDGE_MESSAGE_SCHEMAS,
+        appToAppBridge: exports.APP_COMMAND_SCHEMAS
+    };
+}

package/dist/sessions/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { KV, NatsConnection } from "nats";
+/**
+ * The session registry (add-platform 2.3, add-roomr 3.2, decision D3): one NATS JetStream KV
+ * bucket shared by every service. Keys are `<kind>.<id>`:
+ *
+ *   calls.<callRef>       appbridge:    { callRef, bridgeRef, nodeId, roomRef, direction, at }
+ *                                     + once answered: { appRef, workspaceRef, from, to, startedAt }
+ *   appbridges.<bridgeRef> retired: AppBridge no longer writes it (redesign-roomr 15.3)
+ *   placements.<callRef>  apiserver:  { callRef, nodeRef, controlAddr, roomRef?, at }
+ *                                     while an outbound call is being placed (CreateCall)
+ *
+ * Roomr nodes write nothing here (core NATS only: heartbeat and events); the control plane learns
+ * nodes from their heartbeats.
+ *
+ * The control plane reads `calls` (billing counts active calls from them). A call that loses its
+ * AppBridge mid-call is reported by its node's `call.ended` with cause `app_gone` (redesign-roomr
+ * 15.4), not by expired `appbridges` entries.
+ *
+ * Entries are leases: the bucket keeps a value for SESSIONS_TTL_MS after its last write, owners
+ * rewrite theirs every SESSIONS_REFRESH_MS, and a crashed owner's entries expire on their own.
+ */
+export declare const SESSIONS_BUCKET = "fonoster_sessions";
+export declare const SESSIONS_TTL_MS = 15000;
+export declare const SESSIONS_REFRESH_MS = 5000;
+export type SessionKind = "nodes" | "rooms" | "calls" | "appbridges" | "placements";
+/** `<kind>.<id>` with characters KV keys do not allow replaced by `_`. */
+export declare const sessionKey: (kind: SessionKind, id: string) => string;
+/** Opens the bucket, creating it when it does not exist yet. */
+export declare function openSessions(nc: NatsConnection, options?: {
+    bucket?: string;
+    ttlMs?: number;
+}): Promise<KV>;
+type Logger = {
+    warn(message: string): void;
+};
+/**
+ * An owner's entries, kept alive until deleted (AppBridge's calls and its own appbridge entry).
+ * Writes never throw: the registry is best effort and entries are rewritten on the next refresh.
+ */
+export declare class SessionLeases {
+    private readonly kv;
+    private readonly options;
+    private readonly entries;
+    private readonly timer;
+    private chain;
+    private closed;
+    constructor(kv: KV, options?: {
+        refreshMs?: number;
+        logger?: Logger;
+    });
+    private write;
+    /** Writes the entry now and keeps it alive. */
+    set(kind: SessionKind, id: string, value: Record<string, unknown>): Promise<unknown>;
+    /** Removes the entry. */
+    delete(kind: SessionKind, id: string): Promise<unknown>;
+    /** Reads any owner's entry from the bucket (undefined when absent or expired). */
+    get(kind: SessionKind, id: string): Promise<Record<string, unknown>>;
+    /** Rewrites every live entry (called on a timer). */
+    refresh(): Promise<unknown>;
+    /** Stops refreshing; with `remove`, deletes every entry first (clean shutdown). */
+    close(remove?: boolean): Promise<void>;
+}
+export type SessionEntry = {
+    kind: SessionKind;
+    id: string;
+    /** Undefined when the entry was deleted or purged. */
+    value?: Record<string, unknown>;
+    /** When the entry was last written (the server's timestamp). */
+    writtenAt: Date;
+};
+/**
+ * Follows one kind of entries: the current ones first (so a restarted replica knows the registry
+ * at once), then every change. Returns a stop function.
+ */
+export declare function watchSessions(kv: KV, kind: SessionKind, onEntry: (entry: SessionEntry) => void): Promise<() => void>;
+/** Reads one entry (undefined when absent or expired). */
+export declare function getSession(kv: KV, kind: SessionKind, id: string): Promise<Record<string, unknown> | undefined>;
+export {};