@fonoster/common 0.27.0 → 0.30.0

package/dist/webhooks/Dispatcher.js

@@ -0,0 +1,225 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookDispatcher = exports.WebhookError = exports.MemoryWebhookStore = void 0;
+exports.deliveryId = deliveryId;
+/**
+ * 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.
+ */
+const crypto_1 = require("crypto");
+const url_1 = require("url");
+const net_1 = require("../net");
+const events_1 = require("./events");
+const signing_1 = require("./signing");
+class MemoryWebhookStore {
+    constructor() {
+        this.e = new Map();
+        this.d = new Map();
+    }
+    endpoints(workspaceRef) {
+        return [...this.e.values()].filter((x) => !workspaceRef || x.workspaceRef === workspaceRef);
+    }
+    putEndpoint(x) {
+        this.e.set(x.id, x);
+    }
+    deleteEndpoint(id) {
+        this.e.delete(id);
+    }
+    deliveries(endpointId) {
+        return [...this.d.values()].filter((x) => !endpointId || x.endpointId === endpointId);
+    }
+    putDelivery(x) {
+        this.d.set(x.id, x);
+    }
+}
+exports.MemoryWebhookStore = MemoryWebhookStore;
+class WebhookError extends Error {
+}
+exports.WebhookError = WebhookError;
+/**
+ * The id of an event's delivery to one endpoint. It depends only on the two, so the same event
+ * fanned out again (a bus message redelivered after a replica died, or published twice) finds
+ * the delivery it already made instead of making a second one (ST-2).
+ */
+function deliveryId(eventId, endpointId) {
+    const h = (0, crypto_1.createHash)("sha256")
+        .update(`${eventId}\0${endpointId}`)
+        .digest("hex");
+    return `whd_${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+class WebhookDispatcher {
+    constructor(options) {
+        this.options = options;
+    }
+    policy() {
+        return this.options.allowedDestinations
+            ? { allow: this.options.allowedDestinations }
+            : undefined;
+    }
+    now() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.options).now) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Date.now();
+    }
+    /** Registers an endpoint; the returned secret is the only time it is shown. */
+    createEndpoint(input) {
+        let url;
+        try {
+            url = new url_1.URL(input.url);
+        }
+        catch (_a) {
+            throw new WebhookError("invalid webhook URL");
+        }
+        if (url.protocol !== "https:" &&
+            !(this.options.allowInsecureUrls && url.protocol === "http:")) {
+            throw new WebhookError("webhook URLs must use HTTPS");
+        }
+        try {
+            (0, net_1.assertPublicUrlShape)(url, this.policy());
+        }
+        catch (e) {
+            throw new WebhookError(`webhook URL not allowed: ${e.message}`);
+        }
+        const unknown = input.events.filter((e) => !events_1.WEBHOOK_EVENT_TYPES.includes(e));
+        const retired = unknown.filter((e) => events_1.RETIRED_EVENT_TYPES[e]);
+        if (retired.length)
+            throw new WebhookError(`retired event types: ${retired
+                .map((e) => `${e} (use ${events_1.RETIRED_EVENT_TYPES[e].join(" or ")})`)
+                .join(", ")}; the conversation's transcript and recording are in the call record`);
+        if (unknown.length)
+            throw new WebhookError(`unknown event types: ${unknown.join(", ")}`);
+        const endpoint = {
+            id: `whe_${(0, crypto_1.randomUUID)()}`,
+            workspaceRef: input.workspaceRef,
+            url: input.url,
+            events: input.events,
+            secret: `whsec_${(0, crypto_1.randomBytes)(24).toString("base64url")}`
+        };
+        this.options.store.putEndpoint(endpoint);
+        return endpoint;
+    }
+    /** New secret; the old one keeps verifying for `windowMs`. Returns the new secret. */
+    rotateSecret(endpointId, windowMs = 24 * 3600 * 1000) {
+        const e = this.options.store.endpoints().find((x) => x.id === endpointId);
+        if (!e)
+            throw new WebhookError(`no endpoint ${endpointId}`);
+        const secret = `whsec_${(0, crypto_1.randomBytes)(24).toString("base64url")}`;
+        this.options.store.putEndpoint(Object.assign(Object.assign({}, e), { secret, previousSecret: e.secret, previousUntil: this.now() + windowMs }));
+        return secret;
+    }
+    /** The deliveries an event makes, one per subscribed endpoint of its workspace (not stored). */
+    plan(event) {
+        return this.options.store
+            .endpoints(event.workspaceRef)
+            .filter((e) => e.events.includes(event.type))
+            .map((e) => ({
+            id: deliveryId(event.id, e.id),
+            endpointId: e.id,
+            event,
+            status: "pending",
+            attempts: 0,
+            nextAttemptAt: this.now()
+        }));
+    }
+    /** Fans an event out to every endpoint of its workspace subscribed to its type. */
+    publish(event) {
+        const deliveries = this.plan(event);
+        deliveries.forEach((d) => this.options.store.putDelivery(d));
+        return deliveries;
+    }
+    /** Attempts every pending delivery that is due; returns how many were attempted. */
+    runDue() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const due = this.options.store
+                .deliveries()
+                .filter((d) => d.status === "pending" && d.nextAttemptAt <= this.now());
+            yield Promise.all(due.map((d) => this.attempt(d)));
+            return due.length;
+        });
+    }
+    /** Sends a delivery again now, with the original event id and a fresh signature. */
+    resend(deliveryId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const d = this.options.store.deliveries().find((x) => x.id === deliveryId);
+            if (!d)
+                throw new WebhookError(`no delivery ${deliveryId}`);
+            const again = Object.assign(Object.assign({}, d), { status: "pending", nextAttemptAt: this.now(), firstAttemptAt: this.now() });
+            this.options.store.putDelivery(again);
+            return this.attempt(again);
+        });
+    }
+    attempt(d) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f;
+            const endpoint = this.options.store
+                .endpoints()
+                .find((e) => e.id === d.endpointId);
+            if (!endpoint) {
+                const failed = Object.assign(Object.assign({}, d), { status: "failed" });
+                this.options.store.putDelivery(failed);
+                return failed;
+            }
+            const now = this.now();
+            const secrets = [endpoint.secret];
+            if (endpoint.previousSecret && ((_a = endpoint.previousUntil) !== null && _a !== void 0 ? _a : 0) > now)
+                secrets.push(endpoint.previousSecret);
+            const body = JSON.stringify(d.event);
+            let status = 0;
+            try {
+                // Checked again at delivery: DNS may have changed since the endpoint was created.
+                const res = yield (0, net_1.safeFetch)(endpoint.url, {
+                    method: "POST",
+                    headers: Object.assign({ "content-type": "application/json" }, (0, signing_1.webhookHeaders)(body, secrets, Math.floor(now / 1000))),
+                    body,
+                    timeoutMs: (_b = this.options.attemptTimeoutMs) !== null && _b !== void 0 ? _b : 10000,
+                    maxRedirects: 0,
+                    policy: this.policy()
+                });
+                status = res.status;
+                yield res.arrayBuffer().catch(() => undefined);
+            }
+            catch (_g) {
+                status = 0;
+            }
+            const attempts = d.attempts + 1;
+            const firstAttemptAt = (_c = d.firstAttemptAt) !== null && _c !== void 0 ? _c : now;
+            let next;
+            if (status >= 200 && status < 300) {
+                next = Object.assign(Object.assign({}, d), { status: "succeeded", attempts,
+                    firstAttemptAt, lastAttemptAt: now, lastStatus: status });
+            }
+            else {
+                const delay = Math.min(((_d = this.options.firstDelayMs) !== null && _d !== void 0 ? _d : 10000) * Math.pow(2, (attempts - 1)), (_e = this.options.maxDelayMs) !== null && _e !== void 0 ? _e : 3600000);
+                const giveUp = now + delay - firstAttemptAt >
+                    ((_f = this.options.retryPeriodMs) !== null && _f !== void 0 ? _f : 24 * 3600000);
+                next = Object.assign(Object.assign({}, d), { status: giveUp ? "failed" : "pending", attempts,
+                    firstAttemptAt, lastAttemptAt: now, lastStatus: status, nextAttemptAt: now + delay });
+            }
+            this.options.store.putDelivery(next);
+            return next;
+        });
+    }
+}
+exports.WebhookDispatcher = WebhookDispatcher;

package/dist/webhooks/bus.d.ts

@@ -0,0 +1,49 @@
+import { Delivery } from "./Dispatcher";
+import { WebhookEvent } from "./events";
+export declare const WEBHOOK_EVENTS_SUBJECT = "webhooks.events";
+/** The slice of a NATS connection the bus uses (so `@fonoster/common` needs no NATS client). */
+export type BusConnection = {
+    publish(subject: string, data: Uint8Array): void;
+    subscribe(subject: string, opts: {
+        queue?: string;
+        callback: (err: Error | null, msg: {
+            data: Uint8Array;
+        }) => void;
+    }): {
+        unsubscribe(): void;
+    };
+};
+/** A producer that publishes events on the bus instead of delivering them itself. */
+export declare function busWebhookPublisher(nc: Pick<BusConnection, "publish">): (event: WebhookEvent) => void;
+/** Parses a bus message; undefined for anything that is not a v1 webhook event. */
+export declare function parseBusEvent(data: Uint8Array): WebhookEvent | undefined;
+/** Where media nodes report calls no gateway claimed (the last token is never a room ref). */
+export declare const NODE_CALL_FAILED_SUBJECT = "media.*.events.call-failed";
+/** The reasons a node may give: it only ever fails a call nobody claimed. */
+export declare const NODE_CALL_FAILED_REASONS: readonly ["node_error"];
+/**
+ * The call.failed event for a media node's report on `subject`
+ * (`media.<nodeId>.events.call-failed`); undefined for anything else. Only `call.failed` with a
+ * node reason is accepted, the report must name the node of its subject, and the workspace is left
+ * empty for the fan-out to resolve from the app: a node never chooses the workspace, the event type
+ * or extra data. The id depends on the node and the call, so a repeated report is delivered once.
+ */
+export declare function nodeCallFailedEvent(subject: string, data: Uint8Array, now?: Date): WebhookEvent | undefined;
+export type FanoutOptions = {
+    /** Usually `WebhookDispatcher.publish`: stores one pending delivery per subscribed endpoint. */
+    publish(event: WebhookEvent): Delivery[];
+    /**
+     * The workspace of an app, for events whose producer did not know it (empty or `default`
+     * workspaceRef with a `data.appRef`).
+     */
+    workspaceOfApp?(appRef: string): Promise<string | undefined>;
+    /** Called after an event was fanned out (e.g. to attempt the new deliveries at once). */
+    onPublished?(event: WebhookEvent, deliveries: Delivery[]): void;
+    onError?(e: Error): void;
+    /** Queue group: one replica handles each event. */
+    queue?: string;
+};
+/** Fills in a missing workspace from the app; undefined when it cannot be known. */
+export declare function resolveWorkspace(event: WebhookEvent, workspaceOfApp?: FanoutOptions["workspaceOfApp"]): Promise<WebhookEvent | undefined>;
+/** Subscribes to the bus and fans every event out; returns the unsubscribe function. */
+export declare function subscribeWebhookFanout(nc: Pick<BusConnection, "subscribe">, options: FanoutOptions): () => void;

package/dist/webhooks/bus.js

@@ -0,0 +1,170 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_CALL_FAILED_REASONS = exports.NODE_CALL_FAILED_SUBJECT = exports.WEBHOOK_EVENTS_SUBJECT = void 0;
+exports.busWebhookPublisher = busWebhookPublisher;
+exports.parseBusEvent = parseBusEvent;
+exports.nodeCallFailedEvent = nodeCallFailedEvent;
+exports.resolveWorkspace = resolveWorkspace;
+exports.subscribeWebhookFanout = subscribeWebhookFanout;
+/**
+ * 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.
+ */
+const crypto_1 = require("crypto");
+const util_1 = require("util");
+const events_1 = require("./events");
+// Event fan-out from the event bus (add-workspace-webhooks task 2.2, build log LO-B1). Producers
+// that have no database (media nodes, gateways in bus mode, other regions) publish events on
+// `webhooks.events`; one control-plane replica per event (queue group) fans each event out to the
+// workspace's subscribed endpoints. A producer that does not know the workspace leaves
+// `workspaceRef` empty and the fan-out resolves it from `data.appRef`.
+//
+// Media nodes may not publish `webhooks.events` (M6: a node could otherwise forge any event for
+// any workspace). A node reports a call no gateway claimed on its own subject,
+// `media.<nodeId>.events.call-failed`; the control plane builds the call.failed event from it
+// (nodeCallFailedEvent), with the workspace taken from the app and nothing else trusted.
+exports.WEBHOOK_EVENTS_SUBJECT = "webhooks.events";
+const encoder = new util_1.TextEncoder();
+const decoder = new util_1.TextDecoder();
+/** A producer that publishes events on the bus instead of delivering them itself. */
+function busWebhookPublisher(nc) {
+    return (event) => nc.publish(exports.WEBHOOK_EVENTS_SUBJECT, encoder.encode(JSON.stringify(event)));
+}
+/** Parses a bus message; undefined for anything that is not a v1 webhook event. */
+function parseBusEvent(data) {
+    let e;
+    try {
+        e = JSON.parse(decoder.decode(data));
+    }
+    catch (_a) {
+        return undefined;
+    }
+    if (!e ||
+        typeof e.id !== "string" ||
+        !/^evt_[\w-]+$/.test(e.id) ||
+        !events_1.WEBHOOK_EVENT_TYPES.includes(e.type) ||
+        typeof e.data !== "object" ||
+        e.data === null)
+        return undefined;
+    return e;
+}
+/** Where media nodes report calls no gateway claimed (the last token is never a room ref). */
+exports.NODE_CALL_FAILED_SUBJECT = "media.*.events.call-failed";
+/** The reasons a node may give: it only ever fails a call nobody claimed. */
+exports.NODE_CALL_FAILED_REASONS = ["node_error"];
+const MAX_FIELD = 256;
+const field = (v, required = false) => typeof v === "string" && v.length <= MAX_FIELD && (!required || v.length > 0)
+    ? v
+    : undefined;
+/**
+ * The call.failed event for a media node's report on `subject`
+ * (`media.<nodeId>.events.call-failed`); undefined for anything else. Only `call.failed` with a
+ * node reason is accepted, the report must name the node of its subject, and the workspace is left
+ * empty for the fan-out to resolve from the app: a node never chooses the workspace, the event type
+ * or extra data. The id depends on the node and the call, so a repeated report is delivered once.
+ */
+function nodeCallFailedEvent(subject, data, now = new Date()) {
+    var _a;
+    const tokens = subject.split(".");
+    if (tokens.length !== 4 ||
+        tokens[0] !== "media" ||
+        tokens[2] !== "events" ||
+        tokens[3] !== "call-failed")
+        return undefined;
+    let r;
+    try {
+        r = JSON.parse(decoder.decode(data));
+    }
+    catch (_b) {
+        return undefined;
+    }
+    if (!r || typeof r !== "object" || r.type !== "call.failed")
+        return undefined;
+    const nodeId = tokens[1];
+    const callRef = field(r.callRef, true);
+    const appRef = field(r.appRef, true);
+    const from = field(r.from);
+    const to = field(r.to);
+    const reason = field(r.reason);
+    const direction = (_a = r.direction) !== null && _a !== void 0 ? _a : "inbound";
+    if (r.nodeId !== nodeId ||
+        !callRef ||
+        !appRef ||
+        from === undefined ||
+        to === undefined ||
+        !exports.NODE_CALL_FAILED_REASONS.includes(reason !== null && reason !== void 0 ? reason : "") ||
+        (direction !== "inbound" && direction !== "outbound"))
+        return undefined;
+    const event = (0, events_1.callFailed)("", {
+        callRef,
+        appRef,
+        from,
+        to,
+        direction,
+        reason: reason
+    });
+    const digest = (0, crypto_1.createHash)("sha256")
+        .update(`${nodeId}\n${callRef}`)
+        .digest("hex")
+        .slice(0, 32);
+    return Object.assign(Object.assign({}, event), { id: `evt_node_${digest}`, createdAt: now.toISOString() });
+}
+/** Fills in a missing workspace from the app; undefined when it cannot be known. */
+function resolveWorkspace(event, workspaceOfApp) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (event.workspaceRef && event.workspaceRef !== "default")
+            return event;
+        const appRef = event.data.appRef;
+        if (typeof appRef !== "string" || !appRef || !workspaceOfApp)
+            return undefined;
+        const workspaceRef = yield workspaceOfApp(appRef);
+        return workspaceRef ? Object.assign(Object.assign({}, event), { workspaceRef }) : undefined;
+    });
+}
+/** Subscribes to the bus and fans every event out; returns the unsubscribe function. */
+function subscribeWebhookFanout(nc, options) {
+    var _a;
+    const sub = nc.subscribe(exports.WEBHOOK_EVENTS_SUBJECT, {
+        queue: (_a = options.queue) !== null && _a !== void 0 ? _a : "webhooks-fanout",
+        callback: (err, msg) => {
+            if (err)
+                return;
+            const event = parseBusEvent(msg.data);
+            if (!event)
+                return;
+            resolveWorkspace(event, options.workspaceOfApp)
+                .then((resolved) => {
+                var _a;
+                if (!resolved)
+                    return;
+                const deliveries = options.publish(resolved);
+                (_a = options.onPublished) === null || _a === void 0 ? void 0 : _a.call(options, resolved, deliveries);
+            })
+                .catch((e) => { var _a; return (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, e); });
+        }
+    });
+    return () => sub.unsubscribe();
+}

package/dist/webhooks/events.d.ts

@@ -0,0 +1,66 @@
+export declare const WEBHOOK_EVENT_TYPES: readonly ["call.started", "call.ended", "call.failed", "call_record.sealed", "provider.deprecated"];
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+/**
+ * Event names of the retired Autopilot assistant webhook (`eventsHook`) and what replaces them
+ * (add-call-record 7.3). The record of a conversation (transcript, turns, recording) is in the call
+ * record that `call_record.sealed` links to.
+ */
+export declare const RETIRED_EVENT_TYPES: Record<string, WebhookEventType[]>;
+export type WebhookEvent<D = Record<string, unknown>> = {
+    id: string;
+    type: WebhookEventType;
+    createdAt: string;
+    workspaceRef: string;
+    data: D;
+};
+type CallParties = {
+    callRef: string;
+    appRef: string;
+    from: string;
+    to: string;
+    direction: "inbound" | "outbound";
+};
+export declare const callStarted: (workspaceRef: string, call: CallParties) => WebhookEvent<CallParties>;
+export declare const callEnded: (workspaceRef: string, call: CallParties & {
+    durationSeconds: number;
+    endReason: string;
+}) => WebhookEvent<CallParties & {
+    durationSeconds: number;
+    endReason: string;
+}>;
+/** A call that never reached an app (busy, no answer, failed, app unreachable). */
+export declare const callFailed: (workspaceRef: string, call: {
+    callRef: string;
+    appRef?: string;
+    from: string;
+    to: string;
+    direction: "inbound" | "outbound";
+    reason: string;
+}) => WebhookEvent<{
+    callRef: string;
+    appRef?: string;
+    from: string;
+    to: string;
+    direction: "inbound" | "outbound";
+    reason: string;
+}>;
+/** Points to the record; never carries the transcript, recording or SIP trace. */
+export declare const callRecordSealed: (workspaceRef: string, sealed: {
+    callRef: string;
+    version: number;
+    recordUrl: string;
+}) => WebhookEvent<{
+    callRef: string;
+    version: number;
+    recordUrl: string;
+}>;
+export declare const providerDeprecated: (workspaceRef: string, d: {
+    id: string;
+    replacement: string;
+    retireOn: string;
+}) => WebhookEvent<{
+    id: string;
+    replacement: string;
+    retireOn: string;
+}>;
+export {};

package/dist/webhooks/events.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.providerDeprecated = exports.callRecordSealed = exports.callFailed = exports.callEnded = exports.callStarted = exports.RETIRED_EVENT_TYPES = exports.WEBHOOK_EVENT_TYPES = void 0;
+/**
+ * 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.
+ */
+const crypto_1 = require("crypto");
+// Workspace webhook events, v1 (add-workspace-webhooks W2, W3). Every payload uses the envelope
+// id, type, createdAt, workspaceRef, data; ids stay the same across retries.
+exports.WEBHOOK_EVENT_TYPES = [
+    "call.started",
+    "call.ended",
+    "call.failed",
+    "call_record.sealed",
+    "provider.deprecated"
+];
+/**
+ * Event names of the retired Autopilot assistant webhook (`eventsHook`) and what replaces them
+ * (add-call-record 7.3). The record of a conversation (transcript, turns, recording) is in the call
+ * record that `call_record.sealed` links to.
+ */
+exports.RETIRED_EVENT_TYPES = {
+    "conversation.started": ["call.started"],
+    "conversation.ended": ["call.ended", "call_record.sealed"],
+    all: ["call.started", "call.ended", "call_record.sealed"]
+};
+function envelope(type, workspaceRef, data, now = new Date()) {
+    return {
+        id: `evt_${(0, crypto_1.randomUUID)()}`,
+        type,
+        createdAt: now.toISOString(),
+        workspaceRef,
+        data
+    };
+}
+const callStarted = (workspaceRef, call) => envelope("call.started", workspaceRef, call);
+exports.callStarted = callStarted;
+const callEnded = (workspaceRef, call) => envelope("call.ended", workspaceRef, call);
+exports.callEnded = callEnded;
+/** A call that never reached an app (busy, no answer, failed, app unreachable). */
+const callFailed = (workspaceRef, call) => envelope("call.failed", workspaceRef, call);
+exports.callFailed = callFailed;
+/** Points to the record; never carries the transcript, recording or SIP trace. */
+const callRecordSealed = (workspaceRef, sealed) => envelope("call_record.sealed", workspaceRef, sealed);
+exports.callRecordSealed = callRecordSealed;
+const providerDeprecated = (workspaceRef, d) => envelope("provider.deprecated", workspaceRef, d);
+exports.providerDeprecated = providerDeprecated;

package/dist/webhooks/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+export * from "./Dispatcher";
+export * from "./events";
+export * from "./signing";
+export * from "./prisma";
+export * from "./bus";

package/dist/webhooks/index.js

@@ -0,0 +1,39 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.
+ */
+__exportStar(require("./Dispatcher"), exports);
+__exportStar(require("./events"), exports);
+__exportStar(require("./signing"), exports);
+__exportStar(require("./prisma"), exports);
+__exportStar(require("./bus"), exports);