@memberjunction/server 5.43.0 → 5.45.0

package/src/rest/MediaStreamHandler.ts

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview Authenticated HTTP-Range media streaming route (`GET /media/:fileId`).
+ *
+ * Streams an `MJ: Files` object's bytes (optionally a byte range) to the browser so
+ * `<audio>`/`<video>` elements get native progressive playback + seek-before-download
+ * for large media — instead of the whole file being base64'd over GraphQL.
+ *
+ * Auth model: the request carries a short-lived signed token (`?token=`) minted by
+ * `CreateMediaAccessToken` AFTER a per-user permission check. The token IS the
+ * capability: this route re-verifies its signature/expiry/`typ` and that it matches
+ * the `:fileId`, then loads the file under a SYSTEM context (it only needs
+ * `ProviderKey`/`ProviderID` to locate the bytes — no row-level re-check, since
+ * access was already authorized at mint).
+ *
+ * Mount unauthenticated, BEFORE the unified auth middleware:
+ *   `app.use('/media', cors<cors.CorsRequest>(), createMediaStreamRouter())`
+ *
+ * @module @memberjunction/server/rest/MediaStreamHandler
+ */
+
+import express, { type Router, type Request, type Response } from 'express';
+import { LogError, Metadata, UserInfo } from '@memberjunction/core';
+import { MJFileEntity } from '@memberjunction/core-entities';
+import { FileStorageEngine } from '@memberjunction/storage';
+import type { FileStorageBase, ByteRange } from '@memberjunction/storage';
+import { getSystemUser } from '../auth/index.js';
+import { MediaAccessKeyManager } from './MediaAccessKeys.js';
+import { parseRange, parseRangeHeaderLoose } from './mediaRange.js';
+
+/** A located bytes source for a file: the driver + the provider key to read. */
+interface FileBytesSource {
+  driver: FileStorageBase;
+  providerKey: string;
+  contentType: string;
+}
+
+
+/**
+ * Builds the Express router exposing `GET /media/:fileId`. Stateless — verification
+ * and byte-source resolution happen per request.
+ */
+export function createMediaStreamRouter(): Router {
+  const router = express.Router();
+  router.get('/:fileId', async (req: Request, res: Response) => {
+    await handleMediaRequest(req, res);
+  });
+  return router;
+}
+
+/** Top-level request handler: verify token → resolve bytes → stream/buffer with Range support. */
+async function handleMediaRequest(req: Request, res: Response): Promise<void> {
+  // Express type defs allow req.params values to be string | string[]; normalize to string
+  // so downstream consumers with moduleResolution:"node" type-check cleanly (see SignatureWebhookHandler).
+  const rawFileId = req.params.fileId;
+  const fileId: string = Array.isArray(rawFileId) ? rawFileId[0] : rawFileId;
+  const token = typeof req.query.token === 'string' ? req.query.token : '';
+
+  const claims = verifyMediaToken(token, fileId);
+  if (!claims) {
+    // No body leak — a bad/expired/mismatched token is indistinguishable from "forbidden".
+    res.status(403).end();
+    return;
+  }
+
+  // Never let CDNs or shared caches retain authorized media bytes.
+  res.setHeader('Cache-Control', 'private, no-store');
+
+  try {
+    const source = await resolveFileBytesSource(fileId);
+    if (!source) {
+      res.status(404).end();
+      return;
+    }
+    await streamOrBuffer(req, res, source);
+  } catch (error) {
+    LogError(`[MediaStream] Failed to serve file ${fileId}: ${error instanceof Error ? error.message : String(error)}`);
+    if (!res.headersSent) {
+      res.status(500).end();
+    } else {
+      res.destroy();
+    }
+  }
+}
+
+/**
+ * Verifies the token and that it grants access to THIS file. Returns null on any failure
+ * (signature, expiry, `typ`, or fileId mismatch) so the caller can 403 uniformly.
+ */
+function verifyMediaToken(token: string, fileId: string): { fileId: string; userId: string } | null {
+  if (!token) {
+    return null;
+  }
+  const result = MediaAccessKeyManager.Instance.Verify(token);
+  if (!result.Valid) {
+    return null;
+  }
+  // The token's fileId must match the path — a token minted for file A cannot stream file B.
+  if (result.Claims.fileId !== fileId) {
+    return null;
+  }
+  return { fileId: result.Claims.fileId, userId: result.Claims.userId };
+}
+
+/**
+ * Loads the file under a SYSTEM context and resolves its storage driver + provider key.
+ * Returns null when the file row, its account, or its provider key can't be resolved
+ * (→ 404). Mirrors `readRealtimeRecordingFile`'s account-resolution (engine config with
+ * force-refresh fallback for newly-provisioned accounts).
+ */
+async function resolveFileBytesSource(fileId: string): Promise<FileBytesSource | null> {
+  const systemUser: UserInfo = await getSystemUser();
+
+  // The /media route runs pre-auth on the server's own provider; access was already authorized
+  // at token-mint time, so this load only locates the bytes.
+  const md = new Metadata(); // global-provider-ok: pre-auth system-context route, no per-request provider
+  const file = await md.GetEntityObject<MJFileEntity>('MJ: Files', systemUser);
+  if (!await file.Load(fileId) || !file.ProviderKey) {
+    return null;
+  }
+
+  // Resolve the storage account for the file's provider; force-refresh once if a
+  // newly-provisioned account isn't in the cache yet.
+  await FileStorageEngine.Instance.Config(false, systemUser);
+  let accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+  if (accounts.length === 0) {
+    await FileStorageEngine.Instance.Config(true, systemUser);
+    accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+  }
+  const account = accounts[0];
+  if (!account) {
+    return null;
+  }
+
+  const driver = await FileStorageEngine.Instance.GetDriver(account.ID, systemUser);
+  return {
+    driver,
+    providerKey: file.ProviderKey,
+    contentType: file.ContentType ?? 'application/octet-stream',
+  };
+}
+
+/**
+ * Streams the object honoring an HTTP `Range` request. Prefers true streaming
+ * (`GetObjectStream`) for streaming-capable drivers; gracefully falls back to a
+ * full buffered `GetObject` (slicing for Range) for drivers that don't.
+ */
+async function streamOrBuffer(req: Request, res: Response, source: FileBytesSource): Promise<void> {
+  const rangeHeader = typeof req.headers.range === 'string' ? req.headers.range : undefined;
+
+  if (source.driver.SupportsStreaming) {
+    await serveViaStream(res, source, rangeHeader);
+  } else {
+    await serveViaBuffer(res, source, rangeHeader);
+  }
+}
+
+/** True-streaming path: `GetObjectStream` + pipe, with 206 when a Range was honored. */
+async function serveViaStream(res: Response, source: FileBytesSource, rangeHeader: string | undefined): Promise<void> {
+  const range = rangeHeader ? parseRangeHeaderLoose(rangeHeader) : undefined;
+  // Omit End for an open-ended range so the driver streams to EOF (per ByteRange semantics).
+  const streamRange: ByteRange | undefined = range
+    ? (range.end == null ? { Start: range.start } : { Start: range.start, End: range.end })
+    : undefined;
+
+  const result = await source.driver.GetObjectStream({ fullPath: source.providerKey, Range: streamRange });
+
+  res.setHeader('Accept-Ranges', 'bytes');
+  res.setHeader('Content-Type', result.ContentType ?? source.contentType);
+  if (result.ContentLength != null) {
+    res.setHeader('Content-Length', String(result.ContentLength));
+  }
+  if (result.ContentRange) {
+    const { Start, End, Total } = result.ContentRange;
+    res.setHeader('Content-Range', `bytes ${Start}-${End}/${Total}`);
+    res.status(206);
+  } else {
+    res.status(200);
+  }
+
+  // Tear down the source stream if the client aborts (closed tab, seek, etc.).
+  res.on('close', () => result.Stream.destroy());
+  result.Stream.on('error', (err) => {
+    LogError(`[MediaStream] Source stream error: ${err instanceof Error ? err.message : String(err)}`);
+    if (!res.headersSent) {
+      res.status(500).end();
+    } else {
+      res.destroy();
+    }
+  });
+
+  result.Stream.pipe(res);
+}
+
+/** Fallback path: full buffered `GetObject`, slicing the buffer for Range (206) or sending whole (200). */
+async function serveViaBuffer(res: Response, source: FileBytesSource, rangeHeader: string | undefined): Promise<void> {
+  const buffer = await source.driver.GetObject({ fullPath: source.providerKey });
+  const total = buffer.length;
+
+  res.setHeader('Accept-Ranges', 'bytes');
+  res.setHeader('Content-Type', source.contentType);
+
+  if (!rangeHeader) {
+    res.status(200);
+    res.setHeader('Content-Length', String(total));
+    res.end(buffer);
+    return;
+  }
+
+  const range = parseRange(rangeHeader, total);
+  if (!range) {
+    // Unsatisfiable range — per RFC 7233, 416 + Content-Range with the total size.
+    res.setHeader('Content-Range', `bytes */${total}`);
+    res.status(416).end();
+    return;
+  }
+
+  const slice = buffer.subarray(range.start, range.end + 1);
+  res.status(206);
+  res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${total}`);
+  res.setHeader('Content-Length', String(slice.length));
+  res.end(slice);
+}
+

package/src/rest/mediaRange.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Pure HTTP `Range` header parsing for the `/media/:fileId` stream route.
+ *
+ * Split out of {@link module:@memberjunction/server/rest/MediaStreamHandler} (which pulls in
+ * auth/config/storage at module load) so this load-bearing parsing logic is unit-testable in
+ * isolation — same pattern as `peaksSidecar.ts`. These functions decide whether a request gets
+ * a 206 partial body (and over which byte window) vs. a full 200 / a 416.
+ *
+ * Both helpers are deliberately strict single-range parsers: anything malformed, multi-range,
+ * or suffix-only (`bytes=-N`) yields `undefined`, letting the caller fall back to a full read
+ * (streaming path) or a 416 (buffer path).
+ *
+ * @module @memberjunction/server/rest/mediaRange
+ */
+
+/** A parsed, validated `Range` request against a known total size. */
+export interface ParsedRange {
+  start: number;
+  end: number;
+}
+
+/**
+ * A parsed `Range` request WITHOUT a known total (streaming path). `end` is undefined
+ * for an open-ended `bytes=start-` request, matching `ByteRange`'s "omit End = EOF".
+ */
+export interface ParsedOpenRange {
+  start: number;
+  end?: number;
+}
+
+/**
+ * Parses a single-range `bytes=start-end` header WITHOUT a known total (streaming path).
+ * Returns the inclusive offsets, or undefined when the header is malformed/multi-range/
+ * suffix-only (those we leave to the driver as a full read). `end` is left undefined when
+ * open-ended (`bytes=start-`) so the driver streams to EOF.
+ */
+export function parseRangeHeaderLoose(rangeHeader: string): ParsedOpenRange | undefined {
+  const match = /^bytes=(\d+)-(\d*)$/.exec(rangeHeader.trim());
+  if (!match) {
+    return undefined;
+  }
+  const start = Number(match[1]);
+  if (!Number.isFinite(start)) {
+    return undefined;
+  }
+  if (match[2] === '') {
+    return { start };
+  }
+  const end = Number(match[2]);
+  if (!Number.isFinite(end) || end < start) {
+    return undefined;
+  }
+  return { start, end };
+}
+
+/**
+ * Parses a single-range `bytes=start-end` header against a known total (buffer path),
+ * clamping `end` to the last byte. Returns undefined when unsatisfiable (→ 416) or
+ * malformed/multi-range.
+ */
+export function parseRange(rangeHeader: string, total: number): ParsedRange | undefined {
+  const match = /^bytes=(\d+)-(\d*)$/.exec(rangeHeader.trim());
+  if (!match) {
+    return undefined;
+  }
+  const start = Number(match[1]);
+  if (!Number.isFinite(start) || start >= total) {
+    return undefined; // start past EOF → unsatisfiable
+  }
+  const requestedEnd = match[2] === '' ? total - 1 : Number(match[2]);
+  const end = Math.min(requestedEnd, total - 1);
+  if (end < start) {
+    return undefined;
+  }
+  return { start, end };
+}

package/src/telephony/RingCentralTelephonyService.ts

@@ -0,0 +1,342 @@
+/**
+ * @fileoverview Orchestrates RingCentral telephony bridge sessions (inbound + outbound) for MJAPI over the
+ * **SIP softphone** transport.
+ *
+ * RingCentral's only product that carries bidirectional call audio is a registered SIP softphone (the
+ * `ringcentral-softphone` SDK over SIP/TLS + RTP/SRTP) — its WebSocket "Call Streaming" product is
+ * receive-only and cannot inject the agent's voice. So unlike the Twilio/Vonage ingresses (public webhook
+ * + media WSS), this service owns a **long-lived SIP registration**: one
+ * {@link RingCentralSoftphoneHandle} created + registered at boot, shared across all calls. Inbound calls
+ * arrive as SIP INVITEs on that registration (no HTTP webhook); outbound calls place SIP calls through it.
+ *
+ * It does NOT re-implement bridge logic: it resolves the RingCentral provider + the agent identity, opens a
+ * server-side realtime session via the agent layer's `CreateBridgeRealtimeSession` factory, binds a
+ * {@link RingCentralSoftphoneCallSdk} (drawing its session from the shared handle) onto the driver, and
+ * hands everything to `AIBridgeEngine.StartBridgeSession` — the same seam the Twilio/Vonage services use.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { RunView, UserInfo, IMetadataProvider, Metadata, LogError, LogStatus } from '@memberjunction/core';
+import type { MJAIBridgeAgentIdentityEntity, MJAIBridgeProviderEntity } from '@memberjunction/core-entities';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import {
+    BaseTelephonyBridge,
+    type BridgeNativeSdkBinding,
+    CARRIER_SAMPLE_RATE_CONFIG_KEY,
+    DIRECTION_CONFIG_KEY,
+    FROM_NUMBER_CONFIG_KEY,
+    INBOUND_CALL_ID_CONFIG_KEY,
+} from '@memberjunction/ai-bridge-base';
+import {
+    createRingCentralSoftphone,
+    RingCentralSoftphoneCallSdk,
+    type RingCentralSoftphoneConfig,
+    type RingCentralSoftphoneHandle,
+    type InboundInviteInfo,
+} from '@memberjunction/ai-bridge-ringcentral';
+import type { RingCentralTelephonyConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+
+const RINGCENTRAL_PROVIDER_DRIVER = 'RingCentralBridge';
+const AGENT_IDENTITY_ENTITY = 'MJ: AI Bridge Agent Identities';
+const PHONE_IDENTITY_TYPE = 'PhoneNumber';
+
+/** PCM16 carrier rate (Hz) per softphone codec — the rate the bridge resamples to/from the model rate. */
+const CODEC_CARRIER_RATE: Record<NonNullable<RingCentralSoftphoneConfig['codec']>, number> = {
+    'OPUS/16000': 16000,
+    'OPUS/48000/2': 48000,
+    'PCMU/8000': 8000,
+};
+
+/** A resolved inbound call's identifying fields (mapped from a RingCentral SIP INVITE). */
+export interface InboundCallInput {
+    /** The SIP `Call-ID` (the per-call id the handle parked the INVITE under + the bridge's inbound id). */
+    sessionId: string;
+    /** The caller's number (the INVITE's `From`). */
+    from: string;
+    /** The dialed DID (the INVITE's `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 RingCentralTelephonyServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+    /** Test seam: a factory that builds the softphone handle (inject a fake to avoid the real SIP SDK). */
+    createHandle?: typeof createRingCentralSoftphone;
+}
+
+/**
+ * Starts RingCentral bridge sessions over a shared SIP-softphone registration. One instance per server,
+ * constructed at boot and held by the runtime holder so the outbound `PlaceRingCentralCall` resolver and the
+ * inbound INVITE coordinator share the same registration.
+ */
+export class RingCentralTelephonyService {
+    private readonly engine: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    private readonly sessionFactory: typeof CreateBridgeRealtimeSession;
+    private readonly sessionManager: Pick<SessionManager, 'CreateSession'>;
+    private readonly createHandle: typeof createRingCentralSoftphone;
+
+    /** The shared SIP registration — created + registered by {@link start}; null until then. */
+    private handle: RingCentralSoftphoneHandle | null = null;
+
+    /** The carrier PCM16 rate for the negotiated codec (set in {@link start}). */
+    private carrierSampleRate: number = CODEC_CARRIER_RATE['OPUS/16000'];
+
+    constructor(
+        private readonly config: RingCentralTelephonyConfig,
+        deps: RingCentralTelephonyServiceDeps = {},
+    ) {
+        this.engine = deps.engine ?? AIBridgeEngine.Instance;
+        this.sessionFactory = deps.sessionFactory ?? CreateBridgeRealtimeSession;
+        this.sessionManager = deps.sessionManager ?? new SessionManager();
+        this.createHandle = deps.createHandle ?? createRingCentralSoftphone;
+    }
+
+    /**
+     * Creates + registers the shared SIP softphone and wires inbound INVITE handling. Called once at boot
+     * (fire-and-forget so SIP registration never blocks server startup); logs success/failure. Inbound calls
+     * only flow once this resolves.
+     */
+    public async start(): Promise<void> {
+        try {
+            this.carrierSampleRate = CODEC_CARRIER_RATE[this.config.codec ?? 'OPUS/16000'];
+            this.handle = await this.createHandle(this.toSoftphoneConfig());
+            this.handle.onInvite((info) => void this.onInboundInvite(info));
+            await this.handle.register();
+            LogStatus('[Telephony][RingCentral] softphone telephony started (inbound + outbound ready).');
+        } catch (e) {
+            this.handle = null;
+            LogError(`[Telephony][RingCentral] softphone start failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+
+    /** Best-effort teardown of the SIP registration (server shutdown). */
+    public dispose(): void {
+        this.handle?.dispose();
+        this.handle = null;
+    }
+
+    /**
+     * Resolves the dialed DID to a pinned agent and starts an INBOUND bridge session. The bound
+     * {@link RingCentralSoftphoneCallSdk} answers the parked INVITE for `sessionId`. Returns
+     * `{ accepted:false }` (never throws) when no agent identity matches the DID, so the coordinator can
+     * decline the INVITE cleanly.
+     */
+    public async HandleInboundCall(input: InboundCallInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<InboundCallResult> {
+        try {
+            const identity = await this.resolveAgentIdentityByPhone(input.to, contextUser);
+            if (!identity) {
+                return { accepted: false, reason: `No active agent identity for dialed number '${input.to}'.` };
+            }
+            await this.startBridge({
+                agentID: identity.AgentID,
+                direction: 'Inbound',
+                address: input.from,
+                inboundCallId: input.sessionId,
+                contextUser,
+                provider,
+            });
+            return { accepted: true };
+        } catch (e) {
+            LogError(`[Telephony][RingCentral] inbound call ${input.sessionId} failed: ${e instanceof Error ? e.message : String(e)}`);
+            return { accepted: false, reason: 'Internal error starting the agent.' };
+        }
+    }
+
+    /**
+     * Places an OUTBOUND call from a given agent identity to a destination number. The bound
+     * {@link RingCentralSoftphoneCallSdk} places the SIP call through the shared registration; the returned
+     * SIP `Call-ID` is the bridge's external connection id.
+     *
+     * @returns The placed call's SIP `Call-ID`.
+     */
+    public async PlaceOutboundCall(agentIdentityId: string, toNumber: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<string> {
+        const identity = await this.loadAgentIdentity(agentIdentityId, contextUser, provider);
+        if (!identity) {
+            throw new Error(`Agent identity '${agentIdentityId}' not found or inactive.`);
+        }
+        const session = await this.startBridge({
+            agentID: identity.AgentID,
+            direction: 'Outbound',
+            address: toNumber,
+            fromNumber: identity.IdentityValue,
+            contextUser,
+            provider,
+        });
+        return session.RoomKey ?? '';
+    }
+
+    // ── internals ────────────────────────────────────────────────────────────────
+
+    /** Inbound INVITE coordinator: resolve the server principal, start a bridge, decline if no agent matched. */
+    private async onInboundInvite(info: InboundInviteInfo): Promise<void> {
+        const context = this.resolveServerContext();
+        if (!context) {
+            LogError('[Telephony][RingCentral] no server context user available; declining inbound call.');
+            await this.handle?.declineCall(info.callId);
+            return;
+        }
+        const result = await this.HandleInboundCall({ sessionId: info.callId, from: info.from, to: info.to }, context.user, context.provider);
+        if (!result.accepted) {
+            LogStatus(`[Telephony][RingCentral] inbound ${info.callId} not accepted: ${result.reason ?? 'unknown'}; declining.`);
+            await this.handle?.declineCall(info.callId);
+        }
+    }
+
+    /** Shared inbound/outbound bridge-start: resolve provider, open the realtime session, bind the SDK, start. */
+    private async startBridge(args: {
+        agentID: string;
+        direction: 'Inbound' | 'Outbound';
+        address: string;
+        inboundCallId?: string;
+        fromNumber?: string;
+        contextUser: UserInfo;
+        provider: IMetadataProvider;
+    }): Promise<{ RoomKey?: string }> {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const ringCentralProvider = 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.address,
+        });
+
+        const active = await this.engine.StartBridgeSession({
+            AgentSessionID: agentSession.ID,
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            Provider: ringCentralProvider,
+            RealtimeSession: realtimeSession,
+            Address: args.address,
+            Direction: args.direction,
+            Configuration: this.buildSessionConfiguration(args.direction, args.fromNumber, args.inboundCallId),
+            BindSdk: this.buildBindSdk(),
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+        });
+        return { RoomKey: active.RoomKey };
+    }
+
+    /** Resolves the seeded RingCentral provider row (by driver class, falling back to display name). */
+    private resolveProvider(): MJAIBridgeProviderEntity {
+        const provider = this.engine.ProviderByDriverClass(RINGCENTRAL_PROVIDER_DRIVER) ?? this.engine.ProviderByName('RingCentral');
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row for the RingCentral bridge (DriverClass '${RINGCENTRAL_PROVIDER_DRIVER}').`);
+        }
+        return provider;
+    }
+
+    /**
+     * Builds the per-session SDK binding that wires a {@link RingCentralSoftphoneCallSdk} (drawing its
+     * session from the shared SIP registration handle) onto the telephony driver — overriding the package's
+     * default unbound SDK. Reads the handle lazily at call time so a call placed during the brief boot window
+     * before registration fails loudly rather than binding a null handle.
+     */
+    public buildBindSdk(): BridgeNativeSdkBinding {
+        return (driver) => {
+            const telephony = driver as BaseTelephonyBridge;
+            telephony.SetSdkFactory(() => new RingCentralSoftphoneCallSdk(this.requireHandle()));
+        };
+    }
+
+    /** Returns the live registration handle, or throws if the softphone hasn't registered yet. */
+    private requireHandle(): RingCentralSoftphoneHandle {
+        if (!this.handle) {
+            throw new Error('[Telephony][RingCentral] softphone not registered yet (start() pending or failed).');
+        }
+        return this.handle;
+    }
+
+    /** Assembles the per-session bridge configuration (direction / from-number / inbound-call-id / carrier rate). */
+    private buildSessionConfiguration(direction: 'Inbound' | 'Outbound', fromNumber?: string, inboundCallId?: string): Record<string, unknown> {
+        // The engine does NOT forward the top-level Direction into the driver's Configuration; set it here so
+        // an inbound call answers instead of wrongly taking the outbound-dial path. The carrier rate tells the
+        // base bridge the SIP leg is wideband (16 kHz for OPUS/16000), not the 8 kHz G.711 default.
+        const config: Record<string, unknown> = {
+            [DIRECTION_CONFIG_KEY]: direction,
+            [CARRIER_SAMPLE_RATE_CONFIG_KEY]: this.carrierSampleRate,
+        };
+        if (fromNumber) {
+            config[FROM_NUMBER_CONFIG_KEY] = fromNumber;
+        }
+        if (inboundCallId) {
+            config[INBOUND_CALL_ID_CONFIG_KEY] = inboundCallId;
+        }
+        return config;
+    }
+
+    /** Maps the server config block to the softphone SDK's SIP-device config (credentials resolved upstream). */
+    private toSoftphoneConfig(): RingCentralSoftphoneConfig {
+        return {
+            domain: this.config.sipDomain,
+            outboundProxy: this.config.sipOutboundProxy,
+            username: this.config.sipUsername,
+            password: this.config.sipPassword,
+            authorizationId: this.config.sipAuthorizationId,
+            codec: this.config.codec,
+            ignoreTlsCertErrors: this.config.ignoreTlsCertErrors,
+        };
+    }
+
+    /** Resolves the server-side principal + provider for an inbound call (no MJ JWT on a SIP INVITE). */
+    private resolveServerContext(): { user: UserInfo; provider: IMetadataProvider } | null {
+        const user = UserCache.Instance.GetSystemUser() ?? UserCache.Users.find((u) => u.IsActive && u.Type?.trim().toLowerCase() === 'owner') ?? null;
+        const provider = Metadata.Provider as unknown as IMetadataProvider | undefined; // global-provider-ok: inbound SIP INVITE has no MJ JWT / per-request provider; the server's single default provider is correct
+        if (!user || !provider) {
+            return null;
+        }
+        return { user, provider };
+    }
+
+    /** Finds the active agent identity whose phone number matches the dialed DID. */
+    private async resolveAgentIdentityByPhone(dialedNumber: string, contextUser: UserInfo): Promise<MJAIBridgeAgentIdentityEntity | null> {
+        const normalized = (dialedNumber ?? '').trim();
+        if (!normalized) {
+            return null;
+        }
+        const rv = new RunView();
+        const result = await rv.RunView<MJAIBridgeAgentIdentityEntity>(
+            {
+                EntityName: AGENT_IDENTITY_ENTITY,
+                ExtraFilter: `IdentityType='${PHONE_IDENTITY_TYPE}' AND IdentityValue='${normalized.replace(/'/g, "''")}' AND IsActive=1`,
+                MaxRows: 1,
+                ResultType: 'entity_object',
+            },
+            contextUser,
+        );
+        if (!result.Success) {
+            LogError(`[Telephony][RingCentral] agent-identity lookup failed: ${result.ErrorMessage}`);
+            return null;
+        }
+        return result.Results?.[0] ?? null;
+    }
+
+    /** Loads a specific agent identity by id (used by outbound PlaceCall), requiring it be active. */
+    private async loadAgentIdentity(agentIdentityId: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<MJAIBridgeAgentIdentityEntity | null> {
+        // Use the request-scoped provider (multi-provider safe), not the global Metadata.
+        const entity = await provider.GetEntityObject<MJAIBridgeAgentIdentityEntity>(AGENT_IDENTITY_ENTITY, contextUser);
+        const loaded = await entity.Load(agentIdentityId);
+        if (!loaded || !entity.IsActive) {
+            return null;
+        }
+        return entity;
+    }
+}