@memberjunction/server 5.43.0 → 5.45.0

package/dist/telephony/TeamsMeetingsService.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Orchestrates Teams meeting bridge sessions (join-by-URL) for MJAPI.
+ *
+ * This is the composition layer between the Teams meetings ingress (the public Graph change-notification
+ * webhook + the server-owned ACS media plane) and the ONE unified realtime-agent pathway. It does NOT
+ * re-implement any bridge logic: it resolves the Teams provider + the agent identity, opens a server-side
+ * realtime session via the agent layer's `CreateBridgeRealtimeSession` factory, binds the REAL Teams binding
+ * (`RealTeamsBindings` over the Graph control plane + the per-call ACS media registry) onto the driver, and
+ * hands everything to `AIBridgeEngine.StartBridgeSession` — exactly the seam the Twilio telephony service +
+ * the LiveKit room coordinator use.
+ *
+ * Collaborators are injected (engine, session factory, session manager) so the resolution/branching logic is
+ * unit-testable with fakes; the actual Graph call placement + ACS media flow are live-only (real Teams/Azure
+ * credentials + a publicly reachable Graph webhook URL — see meeting-vendor-bindings-teams-slack.md M1).
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { LogError } from '@memberjunction/core';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import { RealTeamsBindings, RealGraphCallsClient, PumpBackedAcsMedia } from '@memberjunction/ai-bridge-teams';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+const TEAMS_PROVIDER_DRIVER = 'TeamsBridge';
+const AGENT_IDENTITY_ENTITY = 'MJ: AI Bridge Agent Identities';
+/**
+ * Starts Teams meeting bridge sessions. One instance per server, constructed alongside the meetings router and
+ * sharing the {@link TeamsAcsMediaRegistry} with the server's ACS media adapter.
+ */
+export class TeamsMeetingsService {
+    constructor(config, registry, deps = {}) {
+        this.config = config;
+        this.registry = registry;
+        /** Live Graph clients keyed by call id, so the webhook ingress can drive their roster/ended handlers. */
+        this.graphClientsByCall = new Map();
+        this.engine = deps.engine ?? AIBridgeEngine.Instance;
+        this.sessionFactory = deps.sessionFactory ?? CreateBridgeRealtimeSession;
+        this.sessionManager = deps.sessionManager ?? new SessionManager();
+        this.graphClientFactory =
+            deps.graphClientFactory ?? ((accessToken, tenantId) => new RealGraphCallsClient({ AccessToken: accessToken, TenantId: tenantId }));
+    }
+    /**
+     * Joins a Teams meeting by URL for a given agent identity and starts the bridge session. The bound
+     * `RealTeamsBindings` issues the Graph `POST /communications/calls` and accepts the ACS media transport
+     * (attached by the server's media adapter) for the joined call. Returns `{ accepted:false }` (never
+     * throws) when the agent identity is missing/inactive, so the caller can answer cleanly.
+     *
+     * @param agentIdentityId The agent identity to join as (its Teams account/email is the bot's identity).
+     * @param joinUrl The Teams meeting join URL.
+     * @param contextUser The request-scoped principal.
+     * @param provider The request-scoped metadata provider (multi-provider safe — never the global Metadata).
+     */
+    async JoinMeetingByUrl(agentIdentityId, joinUrl, contextUser, provider) {
+        try {
+            const identity = await this.loadAgentIdentity(agentIdentityId, contextUser, provider);
+            if (!identity) {
+                return { accepted: false, reason: `Agent identity '${agentIdentityId}' not found or inactive.` };
+            }
+            const session = await this.startBridge({ agentID: identity.AgentID, joinUrl, contextUser, provider });
+            return { accepted: true, callId: session.CallId };
+        }
+        catch (e) {
+            LogError(`[Meetings][Teams] join meeting failed: ${e instanceof Error ? e.message : String(e)}`);
+            return { accepted: false, reason: e instanceof Error ? e.message : 'Internal error starting the agent.' };
+        }
+    }
+    /**
+     * Drives the retained Graph roster handler for a call from a Graph change notification (called by the
+     * webhook ingress — Graph delivers roster changes over the webhook, not a client subscription).
+     */
+    DriveParticipantsUpdated(callId, participants) {
+        this.graphClientsByCall.get(callId)?.DriveParticipantsUpdated(callId, participants);
+    }
+    /** Drives the call-ended handler for a call from a Graph change notification, then tears the call down. */
+    DriveCallEnded(callId) {
+        this.graphClientsByCall.get(callId)?.DriveCallEnded(callId);
+        this.graphClientsByCall.delete(callId);
+        this.registry.EndCall(callId);
+    }
+    /**
+     * Builds the {@link StartBridgeSessionParams} for a SCHEDULED Teams join — a bridge the
+     * {@link ScheduledBridgeRunner} owns (it created the `MJ: AI Agent Sessions` row and owns the
+     * `StartBridgeSession` call). Reuses the same provider resolution, realtime-session factory, Graph
+     * client, and bind-sdk as an on-demand join, so a scheduled Teams join is identical to a live one
+     * for audio (the ACS media registry is wired via {@link buildBindSdk}).
+     *
+     * NOTE: an on-demand join also registers the live Graph client by call id for webhook-driven
+     * roster/ended routing; the runner abstracts the post-start call id away, so for a SCHEDULED join
+     * that notification routing is a documented follow-on. Audio is fully wired here.
+     */
+    async BuildScheduledStartParams(args) {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const teamsProvider = this.resolveProvider();
+        const realtimeSession = await this.sessionFactory({
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+            AgentSessionID: args.agentSessionID,
+            RoomName: args.joinUrl,
+        });
+        const graphClient = this.graphClientFactory(this.config.botAccessToken ?? '', this.config.tenantId);
+        return {
+            AgentSessionID: args.agentSessionID,
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            Provider: teamsProvider,
+            RealtimeSession: realtimeSession,
+            Address: args.joinUrl,
+            Direction: 'Outbound',
+            Configuration: this.buildSessionConfiguration(),
+            BindSdk: this.buildBindSdk(graphClient),
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+        };
+    }
+    // ── internals ────────────────────────────────────────────────────────────────
+    /** Resolves provider, opens the realtime session, binds the real Teams SDK, and starts the bridge. */
+    async startBridge(args) {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const teamsProvider = this.resolveProvider();
+        const agentSession = await this.sessionManager.CreateSession({ agentID: args.agentID, userID: args.contextUser.ID }, args.contextUser, args.provider);
+        const realtimeSession = await this.sessionFactory({
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+            AgentSessionID: agentSession.ID,
+            RoomName: args.joinUrl,
+        });
+        // The Graph client is created per session; its retained webhook handlers are driven by the ingress.
+        const graphClient = this.graphClientFactory(this.config.botAccessToken ?? '', this.config.tenantId);
+        const active = await this.engine.StartBridgeSession({
+            AgentSessionID: agentSession.ID,
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            Provider: teamsProvider,
+            RealtimeSession: realtimeSession,
+            Address: args.joinUrl,
+            Direction: 'Outbound',
+            Configuration: this.buildSessionConfiguration(),
+            BindSdk: this.buildBindSdk(graphClient),
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+        });
+        const callId = active.RoomKey;
+        if (callId) {
+            this.registry.RegisterCall(callId);
+            this.graphClientsByCall.set(callId, graphClient);
+        }
+        return { CallId: callId };
+    }
+    /** Resolves the seeded Teams provider row (by driver class, falling back to display name). */
+    resolveProvider() {
+        const provider = this.engine.ProviderByDriverClass(TEAMS_PROVIDER_DRIVER) ?? this.engine.ProviderByName('Microsoft Teams');
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row for the Teams bridge (DriverClass '${TEAMS_PROVIDER_DRIVER}').`);
+        }
+        return provider;
+    }
+    /**
+     * Builds the per-session SDK binding that wires the REAL Teams binding (`RealTeamsBindings` over the Graph
+     * control plane + the per-call ACS media registry) onto the Teams driver — overriding the package's default
+     * native loader. This is where the offline-complete seams meet the live Graph + ACS plumbing.
+     */
+    buildBindSdk(graphClient) {
+        return (driver) => {
+            const teams = driver;
+            // RealTeamsBindings threads the Graph call id through every media call, so PumpBackedAcsMedia
+            // routes onto the shared registry keyed by that id — no call id needed at construction.
+            teams.SetSdkFactory(() => new RealTeamsBindings({
+                Graph: graphClient,
+                Media: new PumpBackedAcsMedia(this.registry),
+                ModelSampleRate: this.config.modelSampleRate,
+            }));
+        };
+    }
+    /** Assembles the per-session bridge configuration (carries the resolved tenant for diagnostics). */
+    buildSessionConfiguration() {
+        const config = {};
+        if (this.config.tenantId) {
+            config.TenantId = this.config.tenantId;
+        }
+        return config;
+    }
+    /** Loads a specific agent identity by id (used by join-by-URL), requiring it be active. */
+    async loadAgentIdentity(agentIdentityId, contextUser, provider) {
+        // Use the request-scoped provider (multi-provider safe), not the global Metadata.
+        const entity = await provider.GetEntityObject(AGENT_IDENTITY_ENTITY, contextUser);
+        const loaded = await entity.Load(agentIdentityId);
+        if (!loaded || !entity.IsActive) {
+            return null;
+        }
+        return entity;
+    }
+}
+//# sourceMappingURL=TeamsMeetingsService.js.map

package/dist/telephony/TeamsMeetingsService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TeamsMeetingsService.js","sourceRoot":"","sources":["../../src/telephony/TeamsMeetingsService.ts"],"names":[],"mappings":"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"}

package/dist/telephony/TwilioTelephonyRouter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Express + WSS wiring for the Twilio telephony ingress.
+ *
+ * Two public surfaces (carriers cannot present an MJ JWT — the X-Twilio-Signature HMAC is the gate):
+ *   - `POST /telephony/twilio/voice`  — inbound voice webhook. Verifies the signature, resolves the
+ *     dialed DID to a pinned agent, starts an inbound bridge session, and answers with the
+ *     `<Connect><Stream>` TwiML that opens the Media-Streams socket.
+ *   - `WSS /telephony/twilio/media`   — the bidirectional Media-Streams socket. Frames are routed to the
+ *     active call's `RealTwilioBindings` via the shared {@link TwilioCallMediaRegistry}.
+ *
+ * Mirrors the magic-link / widget public-router pattern: mount the router BEFORE the unified auth
+ * middleware and attach the WSS to the shared HTTP server at startup. The signature-verification gate +
+ * inbound resolution use the offline-complete, unit-tested helpers from the Twilio provider package; this
+ * module is thin HTTP/WS plumbing over them and the {@link TwilioTelephonyService}.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { Router } from 'express';
+import type { TwilioTelephonyConfig } from '../config.js';
+import { TwilioCallMediaRegistry } from './twilioMediaRegistry.js';
+import { TwilioTelephonyService } from './TwilioTelephonyService.js';
+/** The mount path for the Twilio telephony public router. */
+export declare const TWILIO_TELEPHONY_MOUNT_PATH = "/telephony/twilio";
+/** The Media-Streams websocket path Twilio's `<Connect><Stream>` connects to. */
+export declare const TWILIO_MEDIA_WSS_PATH = "/telephony/twilio/media";
+/**
+ * Builds the Twilio telephony handler: the public webhook router + a function to attach the
+ * Media-Streams WSS to the shared HTTP server. Returns the registry + service for observability/tests.
+ */
+export declare function createTwilioTelephonyHandler(publicUrl: string, config: TwilioTelephonyConfig): {
+    publicRouter: Router;
+    attachMediaStreamServer: () => void;
+    registry: TwilioCallMediaRegistry;
+    service: TwilioTelephonyService;
+};
+//# sourceMappingURL=TwilioTelephonyRouter.d.ts.map

package/dist/telephony/TwilioTelephonyRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TwilioTelephonyRouter.d.ts","sourceRoot":"","sources":["../../src/telephony/TwilioTelephonyRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAA2C,MAAM,SAAS,CAAC;AAW1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,6DAA6D;AAC7D,eAAO,MAAM,2BAA2B,sBAAsB,CAAC;AAE/D,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAY/D;;;GAGG;AACH,wBAAgB,4BAA4B,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,qBAAqB,GAC9B;IACC,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,MAAM,IAAI,CAAC;IACpC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,OAAO,EAAE,sBAAsB,CAAC;CACnC,CAgBA"}

package/dist/telephony/TwilioTelephonyRouter.js

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Express + WSS wiring for the Twilio telephony ingress.
+ *
+ * Two public surfaces (carriers cannot present an MJ JWT — the X-Twilio-Signature HMAC is the gate):
+ *   - `POST /telephony/twilio/voice`  — inbound voice webhook. Verifies the signature, resolves the
+ *     dialed DID to a pinned agent, starts an inbound bridge session, and answers with the
+ *     `<Connect><Stream>` TwiML that opens the Media-Streams socket.
+ *   - `WSS /telephony/twilio/media`   — the bidirectional Media-Streams socket. Frames are routed to the
+ *     active call's `RealTwilioBindings` via the shared {@link TwilioCallMediaRegistry}.
+ *
+ * Mirrors the magic-link / widget public-router pattern: mount the router BEFORE the unified auth
+ * middleware and attach the WSS to the shared HTTP server at startup. The signature-verification gate +
+ * inbound resolution use the offline-complete, unit-tested helpers from the Twilio provider package; this
+ * module is thin HTTP/WS plumbing over them and the {@link TwilioTelephonyService}.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { Router, urlencoded } from 'express';
+import { WebSocketServer } from 'ws';
+import { RegisterMediaUpgradeRoute } from './media-upgrade-router.js';
+import { LogError, LogStatus, Metadata } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { verifyTwilioSignature, resolveInboundCall, buildInboundVoiceTwiML, } from '@memberjunction/ai-bridge-twilio';
+import { TwilioCallMediaRegistry } from './twilioMediaRegistry.js';
+import { TwilioTelephonyService } from './TwilioTelephonyService.js';
+/** The mount path for the Twilio telephony public router. */
+export const TWILIO_TELEPHONY_MOUNT_PATH = '/telephony/twilio';
+/** The Media-Streams websocket path Twilio's `<Connect><Stream>` connects to. */
+export const TWILIO_MEDIA_WSS_PATH = '/telephony/twilio/media';
+/** A polite TwiML response played when no agent is available for the dialed number. */
+const NO_AGENT_TWIML = '<?xml version="1.0" encoding="UTF-8"?><Response><Say>Sorry, no agent is available to take this call.</Say><Hangup/></Response>';
+/**
+ * Builds the Twilio telephony handler: the public webhook router + a function to attach the
+ * Media-Streams WSS to the shared HTTP server. Returns the registry + service for observability/tests.
+ */
+export function createTwilioTelephonyHandler(publicUrl, config) {
+    const registry = new TwilioCallMediaRegistry();
+    const service = new TwilioTelephonyService(config, registry);
+    const publicRouter = Router();
+    // Twilio signs the form-urlencoded webhook body; parse it so we can both verify + resolve.
+    publicRouter.post('/voice', urlencoded({ extended: false }), async (req, res) => {
+        await handleInboundVoice(service, config, publicUrl, req, res);
+    });
+    return {
+        publicRouter,
+        attachMediaStreamServer: () => attachMediaStreamServer(registry),
+        registry,
+        service,
+    };
+}
+/** Handles the inbound voice webhook: verify signature → resolve → start bridge → answer with stream TwiML. */
+async function handleInboundVoice(service, config, publicUrl, req, res) {
+    const params = coerceParams(req.body);
+    const fullUrl = `${publicUrl.replace(/\/+$/, '')}${req.originalUrl}`;
+    if (!config.authToken || !verifyTwilioSignature(config.authToken, req.get('X-Twilio-Signature'), fullUrl, params)) {
+        res.status(403).type('text/plain').send('Invalid Twilio signature.');
+        return;
+    }
+    const { callSid, from, to } = resolveInboundCall(params);
+    const context = resolveServerContext();
+    if (!context) {
+        LogError('[Telephony][Twilio] no server context user available; cannot start inbound call.');
+        res.status(200).type('text/xml').send(NO_AGENT_TWIML);
+        return;
+    }
+    const result = await service.HandleInboundCall({ callSid, from, to }, context.user, context.provider);
+    if (!result.accepted) {
+        LogStatus(`[Telephony][Twilio] inbound ${callSid} not accepted: ${result.reason ?? 'unknown'}`);
+        res.status(200).type('text/xml').send(NO_AGENT_TWIML);
+        return;
+    }
+    res.status(200).type('text/xml').send(buildInboundVoiceTwiML(config.streamPublicUrl));
+}
+/**
+ * Attaches the Media-Streams WSS to the shared HTTP server on {@link TWILIO_MEDIA_WSS_PATH}. Each socket
+ * is mapped to its Call SID on the first `start` frame, then inbound frames are dispatched to the call's
+ * bindings via the registry; the socket is also the registry's outbound pump for that call.
+ */
+function attachMediaStreamServer(registry) {
+    // noServer: the shared path-routing upgrade dispatcher (media-upgrade-router) owns the HTTP
+    // 'upgrade' event — a second {server}-bound WS server would fight GraphQL's socket and 400 the
+    // handshake (Twilio error 31920). We register our path and the dispatcher routes to it.
+    const wss = new WebSocketServer({ noServer: true });
+    wss.on('connection', (socket) => wireMediaSocket(socket, registry));
+    RegisterMediaUpgradeRoute(TWILIO_MEDIA_WSS_PATH, wss);
+    LogStatus(`[Telephony][Twilio] Media-Streams WSS route registered at ${TWILIO_MEDIA_WSS_PATH}`);
+}
+/** Wires one Media-Streams socket: bind on `start`, dispatch inbound frames, tear down on close. */
+function wireMediaSocket(socket, registry) {
+    let callSid = null;
+    const adapter = { send: (data) => socket.send(data), close: () => socket.close() };
+    socket.on('message', (raw) => {
+        const message = parseWsMessage(raw);
+        if (!message) {
+            return;
+        }
+        if (message.event === 'start' && message.start?.callSid) {
+            callSid = message.start.callSid;
+            registry.AttachSocket(callSid, adapter, message.start.streamSid ?? '');
+            return;
+        }
+        if (callSid) {
+            registry.DispatchInbound(callSid, message);
+        }
+    });
+    socket.on('close', () => {
+        if (callSid) {
+            registry.EndCall(callSid);
+        }
+    });
+}
+/** Parses a raw WS payload (Buffer/string) into a Twilio message, or null when unparseable. */
+function parseWsMessage(raw) {
+    try {
+        const text = typeof raw === 'string' ? raw : raw instanceof Buffer ? raw.toString('utf8') : String(raw);
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Coerces an Express urlencoded body to the `Record<string,string>` the signature verifier expects. */
+function coerceParams(body) {
+    const out = {};
+    if (body && typeof body === 'object') {
+        for (const [key, value] of Object.entries(body)) {
+            if (typeof value === 'string') {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
+}
+/** Resolves the server-side principal + provider for the public webhook (no MJ JWT on a carrier request). */
+function resolveServerContext() {
+    const user = UserCache.Instance.GetSystemUser() ?? UserCache.Users.find((u) => u.IsActive && u.Type?.trim().toLowerCase() === 'owner') ?? null;
+    const provider = Metadata.Provider; // global-provider-ok: public carrier webhook has no MJ JWT / per-request provider; the server's single default provider is correct
+    if (!user || !provider) {
+        return null;
+    }
+    return { user, provider };
+}
+//# sourceMappingURL=TwilioTelephonyRouter.js.map

package/dist/telephony/TwilioTelephonyRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TwilioTelephonyRouter.js","sourceRoot":"","sources":["../../src/telephony/TwilioTelephonyRouter.ts"],"names":[],"mappings":"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"}

package/dist/telephony/TwilioTelephonyService.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Orchestrates Twilio telephony bridge sessions (inbound + outbound) for MJAPI.
+ *
+ * This is the composition layer between the carrier ingress (the public webhook + the Media-Streams
+ * WSS) and the ONE unified realtime-agent pathway. It does NOT re-implement any bridge logic: it
+ * resolves the Twilio provider + the agent identity, opens a server-side realtime session via the
+ * agent layer's `CreateBridgeRealtimeSession` factory, binds `RealTwilioBindings` (real REST client +
+ * the per-call media registry) onto the driver, and hands everything to
+ * `AIBridgeEngine.StartBridgeSession` — exactly the seam the LiveKit room coordinator uses.
+ *
+ * Collaborators are injected (engine, session factory, session manager) so the resolution/branching
+ * logic is unit-testable with fakes; the actual call placement + media flow are live-only (real Twilio
+ * credentials + a publicly reachable stream URL — see telephony-vendor-bindings.md T1).
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import { type BridgeNativeSdkBinding } from '@memberjunction/ai-bridge-base';
+import type { TwilioTelephonyConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+import { TwilioCallMediaRegistry } from './twilioMediaRegistry.js';
+/** A resolved inbound call's identifying fields (parsed from the Twilio webhook). */
+export interface InboundCallInput {
+    /** The Twilio Call SID. */
+    callSid: string;
+    /** The caller's number (Twilio `From`). */
+    from: string;
+    /** The dialed DID (Twilio `To`) — resolved to an agent identity. */
+    to: string;
+}
+/** Result of starting an inbound bridge session. */
+export interface InboundCallResult {
+    /** Whether a pinned agent was resolved + a bridge session started. */
+    accepted: boolean;
+    /** Why it was rejected (no agent identity for the DID, provider missing, etc.). */
+    reason?: string;
+}
+/** Injectable collaborators (production defaults wired in the constructor; fakes in tests). */
+export interface TwilioTelephonyServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+}
+/**
+ * Starts Twilio bridge sessions. One instance per server, constructed alongside the telephony router and
+ * sharing the {@link TwilioCallMediaRegistry} with the Media-Streams WSS server.
+ */
+export declare class TwilioTelephonyService {
+    private readonly config;
+    private readonly registry;
+    private readonly rest;
+    private readonly engine;
+    private readonly sessionFactory;
+    private readonly sessionManager;
+    constructor(config: TwilioTelephonyConfig, registry: TwilioCallMediaRegistry, deps?: TwilioTelephonyServiceDeps);
+    /**
+     * Resolves the dialed DID to a pinned agent and starts an INBOUND bridge session. The bound
+     * `RealTwilioBindings` will accept the Media-Streams socket (opened by the webhook's TwiML) for the
+     * Call SID. Returns `{ accepted:false }` (never throws) when no agent identity matches the DID, so
+     * the webhook can answer with a polite "no agent" message instead of a 500.
+     */
+    HandleInboundCall(input: InboundCallInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<InboundCallResult>;
+    /**
+     * Places an OUTBOUND call from a given agent identity to a destination number. The bound
+     * `RealTwilioBindings.createCall` issues the Twilio REST `POST /Calls` with the `<Connect><Stream>`
+     * TwiML; the returned Call SID is the bridge's external connection id.
+     *
+     * @returns The placed Call SID.
+     */
+    PlaceOutboundCall(agentIdentityId: string, toNumber: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<string>;
+    /** Shared inbound/outbound bridge-start: resolve provider, open the realtime session, bind the SDK, start. */
+    private startBridge;
+    /** Resolves the seeded Twilio provider row (by driver class, falling back to display name). */
+    private resolveProvider;
+    /**
+     * Builds the per-session SDK binding that wires the REAL Twilio bindings (REST client + the per-call
+     * media registry) onto the telephony driver — overriding the package's default unbound SDK. This is
+     * where the offline-complete seams meet the live REST + websocket plumbing.
+     */
+    buildBindSdk(): BridgeNativeSdkBinding;
+    /**
+     * Assembles the per-session bridge Configuration the telephony driver reads. The engine does NOT
+     * forward the top-level `Direction` into the driver's Configuration (it only stamps the DB row), and
+     * the bridge defaults to `'Outbound'` when the key is absent — so Direction MUST be set here, or an
+     * inbound call wrongly takes the outbound-dial path and fails with "No 'From' number is specified".
+     */
+    private buildSessionConfiguration;
+    /** Finds the active agent identity whose phone number matches the dialed DID. */
+    private resolveAgentIdentityByPhone;
+    /** Loads a specific agent identity by id (used by outbound PlaceCall), requiring it be active. */
+    private loadAgentIdentity;
+}
+//# sourceMappingURL=TwilioTelephonyService.d.ts.map

package/dist/telephony/TwilioTelephonyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TwilioTelephonyService.d.ts","sourceRoot":"","sources":["../../src/telephony/TwilioTelephonyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAW,QAAQ,EAAE,iBAAiB,EAAY,MAAM,sBAAsB,CAAC;AAEtF,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAEH,KAAK,sBAAsB,EAI9B,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAMnE,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC7B,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAC9B,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;IAClB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,+FAA+F;AAC/F,MAAM,WAAW,0BAA0B;IACvC,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,uBAAuB,GAAG,oBAAoB,GAAG,QAAQ,CAAC,CAAC;IAC5G,cAAc,CAAC,EAAE,OAAO,2BAA2B,CAAC;IACpD,cAAc,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;CAC1D;AAED;;;GAGG;AACH,qBAAa,sBAAsB;IAO3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAP7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqG;IAC5H,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqC;IACpE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;gBAGlD,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,EAAE,uBAAuB,EAClD,IAAI,GAAE,0BAA+B;IAazC;;;;;OAKG;IACU,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsBvI;;;;;;OAMG;IACU,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB9I,8GAA8G;YAChG,WAAW;IAsCzB,+FAA+F;IAC/F,OAAO,CAAC,eAAe;IAQvB;;;;OAIG;IACI,YAAY,IAAI,sBAAsB;IAgB7C;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAWjC,iFAAiF;YACnE,2BAA2B;IAsBzC,kGAAkG;YACpF,iBAAiB;CASlC"}