@fonoster/common 0.27.0 → 0.31.0

package/dist/sessions/index.js

@@ -0,0 +1,197 @@
+"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());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionLeases = exports.sessionKey = exports.SESSIONS_REFRESH_MS = exports.SESSIONS_TTL_MS = exports.SESSIONS_BUCKET = void 0;
+exports.openSessions = openSessions;
+exports.watchSessions = watchSessions;
+exports.getSession = getSession;
+/**
+ * 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.
+ */
+exports.SESSIONS_BUCKET = "fonoster_sessions";
+exports.SESSIONS_TTL_MS = 15000;
+exports.SESSIONS_REFRESH_MS = 5000;
+/** `<kind>.<id>` with characters KV keys do not allow replaced by `_`. */
+const sessionKey = (kind, id) => `${kind}.${id.replace(/[^-_=/.a-zA-Z0-9]/g, "_")}`;
+exports.sessionKey = sessionKey;
+/** Opens the bucket, creating it when it does not exist yet. */
+function openSessions(nc_1) {
+    return __awaiter(this, arguments, void 0, function* (nc, options = {}) {
+        var _a;
+        const bucket = (_a = options.bucket) !== null && _a !== void 0 ? _a : exports.SESSIONS_BUCKET;
+        const open = () => {
+            var _a;
+            return nc.jetstream().views.kv(bucket, {
+                history: 1,
+                ttl: (_a = options.ttlMs) !== null && _a !== void 0 ? _a : exports.SESSIONS_TTL_MS,
+                description: "Fonoster session registry: nodes, rooms, calls, appbridges (leases)"
+            });
+        };
+        try {
+            return yield open();
+        }
+        catch (e) {
+            // Another service created it at the same moment with a slightly different config: bind.
+            if (/already in use/i.test(e.message))
+                return nc.jetstream().views.kv(bucket, { bindOnly: true });
+            throw e;
+        }
+    });
+}
+/**
+ * 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.
+ */
+class SessionLeases {
+    constructor(kv, options = {}) {
+        var _a, _b, _c;
+        this.kv = kv;
+        this.options = options;
+        this.entries = new Map();
+        this.chain = Promise.resolve();
+        this.closed = false;
+        this.timer = setInterval(() => this.refresh(), (_a = options.refreshMs) !== null && _a !== void 0 ? _a : exports.SESSIONS_REFRESH_MS);
+        (_c = (_b = this.timer).unref) === null || _c === void 0 ? void 0 : _c.call(_b);
+    }
+    write(key, value) {
+        // One write at a time, in order (a delete never overtakes the put before it).
+        this.chain = this.chain.then(() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                if (value)
+                    yield this.kv.put(key, JSON.stringify(Object.assign(Object.assign({}, value), { at: new Date().toISOString() })));
+                else
+                    yield this.kv.delete(key);
+            }
+            catch (e) {
+                (_a = this.options.logger) === null || _a === void 0 ? void 0 : _a.warn(`session registry write ${key} failed: ${e.message}`);
+            }
+        }));
+        return this.chain;
+    }
+    /** Writes the entry now and keeps it alive. */
+    set(kind, id, value) {
+        if (this.closed)
+            return Promise.resolve();
+        const key = (0, exports.sessionKey)(kind, id);
+        this.entries.set(key, value);
+        return this.write(key, value);
+    }
+    /** Removes the entry. */
+    delete(kind, id) {
+        if (this.closed)
+            return Promise.resolve();
+        const key = (0, exports.sessionKey)(kind, id);
+        this.entries.delete(key);
+        return this.write(key);
+    }
+    /** Reads any owner's entry from the bucket (undefined when absent or expired). */
+    get(kind, id) {
+        return getSession(this.kv, kind, id);
+    }
+    /** Rewrites every live entry (called on a timer). */
+    refresh() {
+        for (const [key, value] of this.entries)
+            void this.write(key, value);
+        return this.chain;
+    }
+    /** Stops refreshing; with `remove`, deletes every entry first (clean shutdown). */
+    close() {
+        return __awaiter(this, arguments, void 0, function* (remove = true) {
+            if (this.closed)
+                return;
+            clearInterval(this.timer);
+            if (remove)
+                for (const key of this.entries.keys())
+                    void this.write(key);
+            this.closed = true;
+            this.entries.clear();
+            yield this.chain;
+        });
+    }
+}
+exports.SessionLeases = SessionLeases;
+/**
+ * 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.
+ */
+function watchSessions(kv, kind, onEntry) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const iter = yield kv.watch({ key: `${kind}.>` });
+        void (() => __awaiter(this, void 0, void 0, function* () {
+            var _a, e_1, _b, _c;
+            try {
+                for (var _d = true, _e = __asyncValues(iter), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const e = _c;
+                    const id = e.key.slice(kind.length + 1);
+                    let value;
+                    if (e.operation === "PUT") {
+                        try {
+                            value = JSON.parse(e.string());
+                        }
+                        catch (_g) {
+                            continue;
+                        }
+                    }
+                    onEntry({ kind, id, value, writtenAt: e.created });
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }))();
+        return () => iter.stop();
+    });
+}
+/** Reads one entry (undefined when absent or expired). */
+function getSession(kv, kind, id) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const e = yield kv.get((0, exports.sessionKey)(kind, id));
+        if (!e || e.operation !== "PUT")
+            return undefined;
+        try {
+            return JSON.parse(e.string());
+        }
+        catch (_a) {
+            return undefined;
+        }
+    });
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+/**
+ * OpenTelemetry bootstrap shared by the TypeScript services (add-platform, observability).
+ *
+ * Driven by the standard OTEL_* variables and a complete no-op when no OTLP endpoint is set:
+ * nothing is loaded, nothing is sent, and the service only writes its normal logs. Signals go
+ * over OTLP/HTTP with JSON bodies (collector port 4318) using only `@opentelemetry/api`,
+ * `sdk-trace-base`, `sdk-trace-node` and `resources`, so no exporter package is needed.
+ *
+ * Every call-scoped span, log record and metric carries `fonoster.call_ref`.
+ */
+export declare const CALL_REF_ATTR = "fonoster.call_ref";
+type Attrs = Record<string, string | number | boolean>;
+export interface CallSpan {
+    /** Adds a timeline event to the call's span. */
+    event(name: string, attrs?: Attrs): void;
+    /** Ends the span; `error` marks it failed. */
+    end(attrs?: Attrs, error?: string): void;
+}
+/** A span not tied to a call (a gRPC request, a registry command), optionally continuing a trace. */
+export interface Span extends CallSpan {
+    /** The W3C `traceparent` of this span, to send with outgoing messages ("" when disabled). */
+    traceparent: string;
+}
+/** NATS/gRPC header carrying the W3C trace context between services. */
+export declare const TRACEPARENT_HEADER = "traceparent";
+export interface Telemetry {
+    enabled: boolean;
+    /**
+     * Starts the span of one call; the returned handle is a no-op when disabled. `parent` (a W3C
+     * traceparent from another service, e.g. the Roomr node) makes it a child in that trace.
+     */
+    startCall(callRef: string, name: string, attrs?: Attrs, parent?: string): CallSpan;
+    /**
+     * Starts a span; with `parent` (a W3C traceparent received from another service) it joins that
+     * trace. A no-op handle when disabled.
+     */
+    startSpan(name: string, attrs?: Attrs, parent?: string): Span;
+    /** The W3C traceparent of a call's span (to propagate over NATS), when one is active. */
+    traceparent(callRef: string): string | undefined;
+    /** An OTLP log record correlated by call ref (and the active trace, when any). */
+    log(level: "debug" | "info" | "warn" | "error", message: string, attrs?: Attrs & {
+        callRef?: string;
+    }): void;
+    /** Adds to a monotonic counter. */
+    count(name: string, value?: number, attrs?: Attrs): void;
+    /** Reads `fn` at every export and reports it as a gauge. */
+    gauge(name: string, fn: () => number, attrs?: Attrs): void;
+    /** Flushes and stops the exporters. */
+    shutdown(): Promise<void>;
+}
+/** True when any OTLP endpoint is configured and the SDK is not disabled. */
+export declare function telemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Starts telemetry for one service. Safe to call once at startup; returns a no-op handle when no
+ * OTLP endpoint is configured or the OpenTelemetry packages are not installed.
+ */
+export declare function initTelemetry(service: string, instanceId?: string, env?: Record<string, string | undefined>): Telemetry;
+export {};

package/dist/telemetry.js

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * 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.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-require-imports */
+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());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACEPARENT_HEADER = exports.CALL_REF_ATTR = void 0;
+exports.telemetryEnabled = telemetryEnabled;
+exports.initTelemetry = initTelemetry;
+/**
+ * OpenTelemetry bootstrap shared by the TypeScript services (add-platform, observability).
+ *
+ * Driven by the standard OTEL_* variables and a complete no-op when no OTLP endpoint is set:
+ * nothing is loaded, nothing is sent, and the service only writes its normal logs. Signals go
+ * over OTLP/HTTP with JSON bodies (collector port 4318) using only `@opentelemetry/api`,
+ * `sdk-trace-base`, `sdk-trace-node` and `resources`, so no exporter package is needed.
+ *
+ * Every call-scoped span, log record and metric carries `fonoster.call_ref`.
+ */
+exports.CALL_REF_ATTR = "fonoster.call_ref";
+/** NATS/gRPC header carrying the W3C trace context between services. */
+exports.TRACEPARENT_HEADER = "traceparent";
+const NOOP_SPAN = {
+    event: () => undefined,
+    end: () => undefined,
+    traceparent: ""
+};
+const NOOP = {
+    enabled: false,
+    startCall: () => NOOP_SPAN,
+    startSpan: () => NOOP_SPAN,
+    traceparent: () => undefined,
+    log: () => undefined,
+    count: () => undefined,
+    gauge: () => undefined,
+    shutdown: () => __awaiter(void 0, void 0, void 0, function* () { return undefined; })
+};
+/** True when any OTLP endpoint is configured and the SDK is not disabled. */
+function telemetryEnabled(env = process.env) {
+    if (env.OTEL_SDK_DISABLED === "true")
+        return false;
+    return [
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"
+    ].some((k) => !!env[k]);
+}
+function toValue(v) {
+    if (typeof v === "number")
+        return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+    if (typeof v === "boolean")
+        return { boolValue: v };
+    return { stringValue: String(v) };
+}
+function toAttrs(a = {}) {
+    return Object.entries(a)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([key, value]) => ({ key, value: toValue(value) }));
+}
+const hrToNano = (t) => (BigInt(t[0]) * BigInt(1000000000) + BigInt(t[1])).toString();
+function signalUrl(env, signal) {
+    const specific = env[`OTEL_EXPORTER_OTLP_${signal.toUpperCase()}_ENDPOINT`];
+    if (specific)
+        return specific;
+    const base = env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    return base ? `${base.replace(/\/$/, "")}/v1/${signal}` : undefined;
+}
+function headers(env) {
+    var _a;
+    const h = { "content-type": "application/json" };
+    for (const pair of ((_a = env.OTEL_EXPORTER_OTLP_HEADERS) !== null && _a !== void 0 ? _a : "")
+        .split(",")
+        .filter(Boolean)) {
+        const i = pair.indexOf("=");
+        if (i > 0)
+            h[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
+    }
+    return h;
+}
+/**
+ * Starts telemetry for one service. Safe to call once at startup; returns a no-op handle when no
+ * OTLP endpoint is configured or the OpenTelemetry packages are not installed.
+ */
+function initTelemetry(service, instanceId, env) {
+    var _a, _b, _c;
+    if (instanceId === void 0) { instanceId = (_a = process.env.HOSTNAME) !== null && _a !== void 0 ? _a : String(process.pid); }
+    if (env === void 0) { env = process.env; }
+    if (!telemetryEnabled(env))
+        return NOOP;
+    let api, base, nodeSdk, resources;
+    try {
+        api = require("@opentelemetry/api");
+        base = require("@opentelemetry/sdk-trace-base");
+        nodeSdk = require("@opentelemetry/sdk-trace-node");
+        resources = require("@opentelemetry/resources");
+    }
+    catch (_d) {
+        return NOOP;
+    }
+    const resourceAttrs = {
+        "service.name": (_b = env.OTEL_SERVICE_NAME) !== null && _b !== void 0 ? _b : service,
+        "service.instance.id": instanceId
+    };
+    const resource = { attributes: toAttrs(resourceAttrs) };
+    const hdrs = headers(env);
+    const post = (url, body) => {
+        if (!url)
+            return Promise.resolve();
+        return fetch(url, {
+            method: "POST",
+            headers: hdrs,
+            body: JSON.stringify(body)
+        })
+            .then(() => undefined)
+            .catch(() => undefined);
+    };
+    // Traces
+    const tracesUrl = signalUrl(env, "traces");
+    const exporter = {
+        export(spans, done) {
+            const body = {
+                resourceSpans: [
+                    {
+                        resource,
+                        scopeSpans: [
+                            {
+                                scope: { name: "fonoster" },
+                                spans: spans.map((s) => {
+                                    var _a, _b;
+                                    return ({
+                                        traceId: s.spanContext().traceId,
+                                        spanId: s.spanContext().spanId,
+                                        parentSpanId: ((_a = s.parentSpanContext) === null || _a === void 0 ? void 0 : _a.spanId) || undefined,
+                                        name: s.name,
+                                        kind: 1 + ((_b = s.kind) !== null && _b !== void 0 ? _b : 0),
+                                        startTimeUnixNano: hrToNano(s.startTime),
+                                        endTimeUnixNano: hrToNano(s.endTime),
+                                        attributes: toAttrs(s.attributes),
+                                        events: s.events.map((e) => ({
+                                            name: e.name,
+                                            timeUnixNano: hrToNano(e.time),
+                                            attributes: toAttrs(e.attributes)
+                                        })),
+                                        status: s.status.code === 2
+                                            ? { code: 2, message: s.status.message }
+                                            : { code: s.status.code }
+                                    });
+                                })
+                            }
+                        ]
+                    }
+                ]
+            };
+            void post(tracesUrl, body).then(() => done({ code: 0 }));
+        },
+        shutdown: () => __awaiter(this, void 0, void 0, function* () { return undefined; })
+    };
+    const provider = new nodeSdk.NodeTracerProvider({
+        resource: resources.resourceFromAttributes(resourceAttrs),
+        spanProcessors: [new base.BatchSpanProcessor(exporter)]
+    });
+    provider.register();
+    // The provider's own tracer: the global one stays the first registered (tests init twice).
+    const tracer = provider.getTracer("fonoster");
+    // Logs
+    const logsUrl = signalUrl(env, "logs");
+    const logQueue = [];
+    const severity = { debug: 5, info: 9, warn: 13, error: 17 };
+    const flushLogs = () => {
+        if (!logQueue.length)
+            return Promise.resolve();
+        const records = logQueue.splice(0);
+        return post(logsUrl, {
+            resourceLogs: [
+                {
+                    resource,
+                    scopeLogs: [{ scope: { name: "fonoster" }, logRecords: records }]
+                }
+            ]
+        });
+    };
+    // Metrics
+    const metricsUrl = signalUrl(env, "metrics");
+    const startNs = (BigInt(Date.now()) * BigInt(1000000)).toString();
+    const counters = new Map();
+    const gauges = [];
+    const flushMetrics = () => {
+        const now = (BigInt(Date.now()) * BigInt(1000000)).toString();
+        const metrics = [];
+        for (const [name, series] of counters) {
+            metrics.push({
+                name,
+                sum: {
+                    aggregationTemporality: 2,
+                    isMonotonic: true,
+                    dataPoints: series.map((s) => ({
+                        asInt: String(s.value),
+                        startTimeUnixNano: startNs,
+                        timeUnixNano: now,
+                        attributes: toAttrs(s.attrs)
+                    }))
+                }
+            });
+        }
+        for (const g of gauges) {
+            let v = 0;
+            try {
+                v = g.fn();
+            }
+            catch (_a) {
+                continue;
+            }
+            metrics.push({
+                name: g.name,
+                gauge: {
+                    dataPoints: [
+                        { asDouble: v, timeUnixNano: now, attributes: toAttrs(g.attrs) }
+                    ]
+                }
+            });
+        }
+        if (!metrics.length)
+            return Promise.resolve();
+        return post(metricsUrl, {
+            resourceMetrics: [
+                {
+                    resource,
+                    scopeMetrics: [{ scope: { name: "fonoster" }, metrics }]
+                }
+            ]
+        });
+    };
+    const timer = setInterval(() => {
+        void flushLogs();
+        void flushMetrics();
+    }, Number((_c = env.OTEL_METRIC_EXPORT_INTERVAL) !== null && _c !== void 0 ? _c : 15000));
+    timer.unref();
+    const spanOf = new Map();
+    const contextOf = (parent) => parent
+        ? api.propagation.extract(api.context.active(), {
+            [exports.TRACEPARENT_HEADER]: parent
+        })
+        : api.context.active();
+    const traceparentOf = (span) => {
+        var _a;
+        const carrier = {};
+        api.propagation.inject(api.trace.setSpan(api.context.active(), span), carrier);
+        return (_a = carrier[exports.TRACEPARENT_HEADER]) !== null && _a !== void 0 ? _a : "";
+    };
+    return {
+        enabled: true,
+        startSpan(name, attrs, parent) {
+            const span = tracer.startSpan(name, { attributes: attrs }, contextOf(parent));
+            return {
+                traceparent: traceparentOf(span),
+                event: (n, a) => span.addEvent(n, a),
+                end: (a, error) => {
+                    if (a)
+                        span.setAttributes(a);
+                    if (error)
+                        span.setStatus({ code: 2, message: error });
+                    span.end();
+                }
+            };
+        },
+        traceparent(callRef) {
+            const span = spanOf.get(callRef);
+            return span ? traceparentOf(span) : undefined;
+        },
+        startCall(callRef, name, attrs, parent) {
+            const span = tracer.startSpan(name, { attributes: Object.assign({ [exports.CALL_REF_ATTR]: callRef }, attrs) }, contextOf(parent));
+            spanOf.set(callRef, span);
+            return {
+                event: (n, a) => span.addEvent(n, Object.assign({ [exports.CALL_REF_ATTR]: callRef }, a)),
+                end: (a, error) => {
+                    if (a)
+                        span.setAttributes(a);
+                    if (error)
+                        span.setStatus({ code: 2, message: error });
+                    span.end();
+                    spanOf.delete(callRef);
+                }
+            };
+        },
+        log(level, message, attrs = {}) {
+            var _a, _b, _c;
+            const { callRef } = attrs, rest = __rest(attrs, ["callRef"]);
+            const span = callRef ? spanOf.get(callRef) : undefined;
+            const ctx = (_b = (_a = span === null || span === void 0 ? void 0 : span.spanContext) === null || _a === void 0 ? void 0 : _a.call(span)) !== null && _b !== void 0 ? _b : (_c = api.trace.getActiveSpan()) === null || _c === void 0 ? void 0 : _c.spanContext();
+            logQueue.push({
+                timeUnixNano: (BigInt(Date.now()) * BigInt(1000000)).toString(),
+                severityNumber: severity[level],
+                severityText: level.toUpperCase(),
+                body: { stringValue: message },
+                attributes: toAttrs(callRef ? Object.assign({ [exports.CALL_REF_ATTR]: callRef }, rest) : rest),
+                traceId: ctx === null || ctx === void 0 ? void 0 : ctx.traceId,
+                spanId: ctx === null || ctx === void 0 ? void 0 : ctx.spanId
+            });
+            if (logQueue.length >= 100)
+                void flushLogs();
+        },
+        count(name, value = 1, attrs = {}) {
+            var _a;
+            const series = (_a = counters.get(name)) !== null && _a !== void 0 ? _a : [];
+            const key = JSON.stringify(attrs);
+            const hit = series.find((s) => JSON.stringify(s.attrs) === key);
+            if (hit)
+                hit.value += value;
+            else
+                series.push({ attrs, value });
+            counters.set(name, series);
+        },
+        gauge(name, fn, attrs) {
+            gauges.push({ name, fn, attrs });
+        },
+        shutdown() {
+            return __awaiter(this, void 0, void 0, function* () {
+                clearInterval(timer);
+                yield provider.shutdown().catch(() => undefined);
+                yield Promise.all([flushLogs(), flushMetrics()]);
+            });
+        }
+    };
+}

package/dist/types.d.ts

@@ -19,9 +19,7 @@
 type NumberPreconditionsCheck = (request: {
     appRef?: string;
     agentAor?: string;
+    /** The caller's workspace: an appRef must belong to it (RV-B4). */
+    accessKeyId?: string;
 }) => Promise<void>;
-type IntegrationConfig = {
-    productRef: string;
-    credentials: Record<string, unknown>;
-};
-export { NumberPreconditionsCheck, IntegrationConfig };
+export { NumberPreconditionsCheck };

package/dist/{voice/Gather.d.ts → usage/CallUsage.d.ts}

@@ -16,22 +16,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { VerbRequest, VerbResponse } from "./Verb";
-declare enum GatherSource {
-    SPEECH = "speech",
-    DTMF = "dtmf",
-    SPEECH_AND_DTMF = "speech,dtmf"
-}
-type GatherOptions = {
-    finishOnKey?: string;
-    maxDigits?: number;
-    timeout?: number;
-    source?: GatherSource;
-};
-type GatherRequest = VerbRequest & GatherOptions;
-type GatherResponse = VerbResponse & {
-    speech?: string;
-    digits?: string;
-    responseTime: number;
+import { MeterName } from "./meters";
+import { KeySource, UsageLine } from "./types";
+type Key = {
+    meter: MeterName;
+    provider?: string;
+    model?: string;
+    keySource?: KeySource;
 };
-export { GatherOptions, GatherRequest, GatherResponse, GatherSource };
+/**
+ * A call's usage, accumulated in memory while it runs (design D1). One entry per meter, provider,
+ * model and key source; seconds are kept exact and rounded up only when lines are taken.
+ */
+export declare class CallUsage {
+    private readonly entries;
+    add(line: UsageLine): void;
+    /** Adds seconds of a meter measured as a duration in milliseconds. */
+    addMillis(key: Key, ms: number): void;
+    lines(): UsageLine[];
+}
+export {};