@memberjunction/ai-bridge-twilio 0.0.1 → 5.42.0

package/dist/twilio-call-sdk.js

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview The **Twilio** binding of the telephony call SDK seam — `TwilioCallSdk` +
+ * `TwilioCallSdkFactory`.
+ *
+ * {@link TwilioCallSdk} implements the platform-agnostic {@link ITelephonyCallSdk} (from
+ * `@memberjunction/ai-bridge-base`) over **Twilio Programmable Voice + Media Streams**, so
+ * {@link import('./twilio-bridge.js').TwilioBridge} drives a real phone call without ever importing the
+ * Twilio SDK directly. As shipped, every operation throws an explicit **"bind the real Twilio client"**
+ * error — the real Twilio binding is a documented deployment seam (below). Production supplies the bound
+ * client via {@link TwilioCallSdk}'s constructor / the factory; tests inject a `FakeTwilioCallSdk`.
+ *
+ * ## How the Twilio operations map (production binding — deployment TODO)
+ * Twilio has two halves: a **REST API** (place/modify/hang-up calls) and a **Media Streams** websocket
+ * (bidirectional realtime audio + DTMF events). This SDK adapter sits over both:
+ *
+ * | {@link ITelephonyCallSdk} op | Twilio binding |
+ * |---|---|
+ * | {@link TwilioCallSdk.dial} (outbound) | REST `client.calls.create({ to, from, twiml })` where the TwiML opens a bidirectional `<Connect><Stream>` to the Media-Streams websocket. Returns the Call SID. |
+ * | {@link TwilioCallSdk.answer} (inbound) | The inbound webhook (a call to the agent's DID) returns TwiML with `<Connect><Stream>`; "answering" = accepting that Media-Streams websocket for the delivered Call SID. |
+ * | {@link TwilioCallSdk.hangup} | REST `client.calls(callSid).update({ status: 'completed' })`. |
+ * | {@link TwilioCallSdk.sendAudioFrame} | A Media-Streams **outbound `media`** message (base64 μ-law/PCM payload) on the call's websocket — the agent's voice. |
+ * | {@link TwilioCallSdk.onAudioFrame} | Inbound Media-Streams **`media`** events on the websocket — what the agent hears (single remote party). |
+ * | {@link TwilioCallSdk.sendDtmf} | REST `client.calls(callSid).update({ twiml: '<Play digits="...">' })` (or a `<Dial>` `sendDigits`). |
+ * | {@link TwilioCallSdk.onDtmf} | `<Gather input="dtmf">` results delivered to the voice webhook, OR Media-Streams DTMF `dtmf` events. |
+ * | {@link TwilioCallSdk.transfer} | REST `client.calls(callSid).update({ twiml: '<Dial>+1...</Dial>' })` redirecting the live call. |
+ * | {@link TwilioCallSdk.onCallEnded} | The `status-callback` webhook for `completed` / `failed` / `canceled`, OR the Media-Streams `stop` event. |
+ *
+ * Binding the real Twilio client is a thin adapter that supplies an {@link ITwilioClientBindings}
+ * implementation (REST + websocket) to {@link TwilioCallSdk}; the driver and its tests do not change.
+ * **None of the `twilio` SDK's types leak into this package.**
+ *
+ * Credentials (Account SID, Auth Token, the Media-Streams websocket URL) resolve through MJ's credential
+ * system referenced by the provider `Configuration` — never inline secrets.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ * @see {@link ITelephonyCallSdk} — the platform-agnostic seam this binds.
+ * @see `/plans/realtime/realtime-bridges-architecture.md` §8 (Twilio capability row) and §9 Phase 6.
+ */
+/** The default bindings used when none are supplied — every operation throws the bind-me error. */
+const UNBOUND_BINDINGS = {
+    createCall: () => throwUnbound('createCall (outbound dial)'),
+    acceptInbound: () => throwUnbound('acceptInbound (inbound answer)'),
+    completeCall: () => throwUnbound('completeCall (hangup)'),
+    pushStreamAudio: () => throwUnboundVoid('pushStreamAudio (outbound media)'),
+    onStreamAudio: () => throwUnboundVoid('onStreamAudio (inbound media)'),
+    playDigits: () => throwUnbound('playDigits (send DTMF)'),
+    onDigits: () => throwUnboundVoid('onDigits (receive DTMF)'),
+    redirectCall: () => throwUnbound('redirectCall (transfer)'),
+    onCallStatus: () => throwUnboundVoid('onCallStatus (call ended)'),
+};
+function throwUnbound(op) {
+    throw new Error(`TwilioCallSdk has no real Twilio client bound (operation '${op}'). Construct it with an ` +
+        'ITwilioClientBindings over the real twilio SDK (REST + Media Streams), or inject a fake in tests.');
+}
+function throwUnboundVoid(op) {
+    throwUnbound(op);
+}
+/**
+ * Twilio's implementation of the {@link ITelephonyCallSdk} telephony seam over **Twilio Programmable
+ * Voice + Media Streams**. {@link import('./twilio-bridge.js').TwilioBridge} drives this; production
+ * constructs it with real {@link ITwilioClientBindings}, tests inject a `FakeTwilioCallSdk` directly
+ * (no need for this adapter at all in tests).
+ *
+ * The adapter tracks the active Call SID so the per-call websocket / REST operations can be addressed.
+ * It never imports the `twilio` SDK — all Twilio specifics live behind {@link ITwilioClientBindings}.
+ */
+export class TwilioCallSdk {
+    /**
+     * @param bindings The real Twilio client bindings (REST + Media Streams). Defaults to an unbound
+     *   implementation whose every method throws the explicit "bind the real Twilio client" error.
+     */
+    constructor(bindings = UNBOUND_BINDINGS) {
+        this.bindings = bindings;
+        /** The active call's SID once dialled/answered, so per-call operations can address it. */
+        this.activeCallSid = null;
+    }
+    /** @inheritdoc */
+    async dial(toNumber, fromNumber, args) {
+        const sid = await this.bindings.createCall(toNumber, fromNumber, args);
+        this.bindCall(sid);
+        return sid;
+    }
+    /** @inheritdoc */
+    async answer(callId) {
+        await this.bindings.acceptInbound(callId);
+        this.bindCall(callId);
+    }
+    /** @inheritdoc */
+    async hangup(callId) {
+        await this.bindings.completeCall(callId);
+        this.activeCallSid = null;
+    }
+    /** @inheritdoc */
+    sendAudioFrame(pcm) {
+        if (this.activeCallSid) {
+            this.bindings.pushStreamAudio(this.activeCallSid, pcm);
+        }
+    }
+    /** @inheritdoc */
+    onAudioFrame(cb) {
+        this.audioCb = cb;
+        if (this.activeCallSid) {
+            this.bindings.onStreamAudio(this.activeCallSid, cb);
+        }
+    }
+    /** @inheritdoc */
+    async sendDtmf(digits) {
+        if (this.activeCallSid) {
+            await this.bindings.playDigits(this.activeCallSid, digits);
+        }
+    }
+    /** @inheritdoc */
+    onDtmf(cb) {
+        this.dtmfCb = cb;
+        if (this.activeCallSid) {
+            this.bindings.onDigits(this.activeCallSid, cb);
+        }
+    }
+    /** @inheritdoc */
+    async transfer(callId, toNumber) {
+        await this.bindings.redirectCall(callId, toNumber);
+    }
+    /** @inheritdoc */
+    onCallEnded(cb) {
+        this.endedCb = cb;
+        if (this.activeCallSid) {
+            this.bindings.onCallStatus(this.activeCallSid, cb);
+        }
+    }
+    /** Binds the active Call SID and (re-)registers any handlers the driver set before the call existed. */
+    bindCall(callSid) {
+        this.activeCallSid = callSid;
+        if (this.audioCb) {
+            this.bindings.onStreamAudio(callSid, this.audioCb);
+        }
+        if (this.dtmfCb) {
+            this.bindings.onDigits(callSid, this.dtmfCb);
+        }
+        if (this.endedCb) {
+            this.bindings.onCallStatus(callSid, this.endedCb);
+        }
+    }
+}
+/**
+ * Builds a {@link TwilioCallSdk} for a session — the Twilio creation seam. Production supplies a factory
+ * that constructs the SDK with real {@link ITwilioClientBindings} (built from the resolved provider
+ * `Configuration` — Account SID, Auth Token, Media-Streams URL, all resolved upstream). Out of the box
+ * this returns an **unbound** `TwilioCallSdk` whose operations throw until the real client is bound.
+ *
+ * @param _config The resolved provider/session configuration (credential refs already resolved upstream).
+ * @returns An (unbound) {@link TwilioCallSdk}. Override in deployment / inject a fake in tests.
+ */
+export const TwilioCallSdkFactory = (_config) => {
+    return new TwilioCallSdk();
+};
+//# sourceMappingURL=twilio-call-sdk.js.map

package/dist/twilio-call-sdk.js.map

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

package/dist/twilio-native-call-sdk.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview `TwilioNativeCallSdk` — a **real, two-way** {@link ITelephonyCallSdk} binding over the
+ * native **Twilio Programmable Voice + Media Streams** path. Unlike the shipped, unbound
+ * {@link import('./twilio-call-sdk.js').TwilioCallSdk} (every operation throws "bind the real Twilio
+ * client"), this adapter actually carries the call: {@link TwilioNativeCallSdk.sendAudioFrame} forwards
+ * the agent's synthesized PCM onto the call's Media-Streams websocket (the agent's **voice** on the
+ * call), inbound Media-Streams audio maps to the seam's audio-frame callback (what the agent **hears**),
+ * and DTMF / transfer / hangup actually reach the native client.
+ *
+ * ## Why a native binding
+ * A phone call is a single-leg, bidirectional audio source. The native Twilio path has two halves — a
+ * **REST API** (place / hang-up / transfer / send-DTMF) and a **Media Streams** websocket (bidirectional
+ * realtime audio + inbound DTMF events). This adapter sits over both so a single binding gives the agent
+ * full-duplex audio plus the call controls the telephony seam declares.
+ *
+ * ## The native module seam (no SDK types leak)
+ * The `twilio` SDK is NOT imported here. Deployments wrap the REST + Media-Streams plumbing behind the
+ * small structural {@link NativeCallModule} surface declared below, and this adapter depends ONLY on that
+ * surface — none of `twilio`'s real types leak into `@memberjunction/ai-bridge-twilio`. The module is
+ * loaded **lazily** behind an injectable {@link NativeModuleLoader} so the package builds and unit-tests
+ * with **no `twilio` install and no network**. Tests inject a fake module; production points
+ * {@link TwilioNativeSdkConfig.NativeModuleSpecifier} at the real adapter package/path.
+ *
+ * ## Auth (deployment responsibility)
+ * The native client authenticates with the Twilio **Account SID + Auth Token** (or API key/secret) and a
+ * resolved Media-Streams websocket URL. These resolve **upstream** (MJ credential system / provider
+ * `Configuration`) and are **never inlined** at a call site — {@link readNativeConfig} reads already-
+ * resolved values out of the loose `Configuration` map the engine passes at connect.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ * @author MemberJunction.com
+ * @see {@link ITelephonyCallSdk} — the platform-agnostic telephony seam this binds.
+ */
+import { ITelephonyCallSdk } from '@memberjunction/ai-bridge-base';
+/** One inbound Media-Streams audio frame the native adapter surfaces (what the agent hears). */
+export interface NativeCallAudioFrame {
+    /** Raw PCM/μ-law bytes for this frame (`Uint8Array` view or standalone `ArrayBuffer`). */
+    data: Uint8Array | ArrayBuffer;
+    /** Optional epoch-ms capture timestamp (informational; the seam carries only the bytes). */
+    timestampMs?: number;
+}
+/** Options the native adapter's `createCall` (outbound dial) accepts. Mirrors the seam's `dial` args. */
+export interface NativeDialArgs {
+    /** Destination number to dial (E.164 recommended). */
+    toNumber: string;
+    /** The agent's caller-id / DID the call originates FROM. */
+    fromNumber: string;
+    /** Provider-specific dial options (status-callback URL, stream URL, recording flags, …). */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The live native-call client the adapter hands back. The surface mirrors {@link ITelephonyCallSdk} but in
+ * the native adapter's own (lower-cased) vocabulary; this adapter maps between the two. VERIFY against the
+ * native Twilio adapter.
+ */
+export interface NativeCallClient {
+    /** Places the outbound call (REST `calls.create` with a `<Connect><Stream>` TwiML). Resolves the Call SID. */
+    dial(args: NativeDialArgs): Promise<string>;
+    /** Accepts the Media-Streams websocket for an already-delivered inbound Call SID. */
+    answer(callId: string): Promise<void>;
+    /** Ends the call (REST `calls(sid).update({ status: 'completed' })`). */
+    hangup(callId: string): Promise<void>;
+    /** Pushes one outbound PCM frame onto the call's Media-Streams websocket — the agent's voice. */
+    sendAudioFrame(pcm: ArrayBuffer): void;
+    /** Registers the inbound Media-Streams audio callback. "Latest handler wins." */
+    onAudioFrame(cb: (frame: NativeCallAudioFrame) => void): void;
+    /** Sends DTMF digits on the call (REST `<Play digits>` / `<Dial sendDigits>`). */
+    sendDtmf(digits: string): Promise<void>;
+    /** Registers the inbound DTMF callback (`<Gather>` results or Media-Streams `dtmf` events). */
+    onDtmf(cb: (digits: string) => void): void;
+    /** Transfers the live call (REST `calls(sid).update({ twiml: '<Dial>...' })`). */
+    transfer(callId: string, toNumber: string): Promise<void>;
+    /** Registers the call-ended callback (status-callback `completed`/`failed` or stream `stop`). */
+    onCallEnded(cb: () => void): void;
+}
+/** Options passed to {@link NativeCallModule.createClient}. Credentials are resolved upstream. */
+export interface NativeClientOptions {
+    /** The Twilio Account SID (resolved upstream). */
+    AccountSid?: string;
+    /** The Twilio Auth Token (resolved upstream). */
+    AuthToken?: string;
+    /** The Twilio API Key SID (resolved upstream; alternative to Account SID + Auth Token). */
+    ApiKeySid?: string;
+    /** The Twilio API Key Secret (resolved upstream). */
+    ApiKeySecret?: string;
+    /** The Media-Streams websocket URL the call's `<Connect><Stream>` connects to (resolved upstream). */
+    StreamUrl?: string;
+}
+/** The native adapter module surface — a factory that constructs a {@link NativeCallClient}. */
+export interface NativeCallModule {
+    /**
+     * Constructs a native call client from resolved options (Twilio credentials already resolved upstream).
+     * VERIFY against the native Twilio adapter (`createClient` vs a `Client` constructor).
+     */
+    createClient(options: NativeClientOptions): NativeCallClient;
+}
+/**
+ * Resolved configuration for {@link TwilioNativeCallSdk}. Credentials resolve **upstream** (MJ credential
+ * system / provider `Configuration`) — this object carries already-resolved values; **never inline
+ * secrets** at a call site.
+ */
+export interface TwilioNativeSdkConfig {
+    /** The Twilio Account SID (resolved upstream). */
+    AccountSid?: string;
+    /** The Twilio Auth Token (resolved upstream). */
+    AuthToken?: string;
+    /** The Twilio API Key SID (resolved upstream; alternative to Account SID + Auth Token). */
+    ApiKeySid?: string;
+    /** The Twilio API Key Secret (resolved upstream). */
+    ApiKeySecret?: string;
+    /** The Media-Streams websocket URL the call's `<Connect><Stream>` connects to (resolved upstream). */
+    StreamUrl?: string;
+    /**
+     * The module specifier of the native Twilio adapter to load (an internal adapter package name or an
+     * absolute path to a sidecar entry). Required in production; tests inject a loader.
+     */
+    NativeModuleSpecifier?: string;
+}
+/**
+ * Copies arbitrary PCM bytes into a standalone `ArrayBuffer`, never aliasing the caller's buffer window.
+ * A `Uint8Array` view may be a slice of a larger backing buffer (offset/length), so a naive `.buffer`
+ * grab would leak neighbouring audio; this copies exactly the view's bytes. Defined locally because the
+ * Twilio package has no shared coercion helper to reuse (unlike the Zoom package's RTMS binding).
+ */
+export declare function toArrayBuffer(data: Uint8Array | ArrayBuffer): ArrayBuffer;
+/**
+ * **Pure mapping** of one native inbound audio frame onto the raw PCM `ArrayBuffer` the telephony seam's
+ * audio callback delivers. Copies the bytes (see {@link toArrayBuffer}). Isolated from I/O for direct
+ * unit testing. (The telephony seam carries no per-speaker label — a 1:1 call has one remote party.)
+ */
+export declare function mapNativeAudioFrame(frame: NativeCallAudioFrame): ArrayBuffer;
+/**
+ * The injectable loader for the native Twilio adapter — overridable so unit tests supply a fake module
+ * with no `twilio` install and no network. Production leaves it as {@link defaultNativeLoader}, which
+ * lazily imports the configured {@link TwilioNativeSdkConfig.NativeModuleSpecifier}.
+ */
+export type NativeModuleLoader = (specifier: string) => Promise<NativeCallModule>;
+/**
+ * Lazily loads the native Twilio adapter at the given specifier (category: runtime plugin discovery from
+ * config — the adapter path is deployment-supplied and not known at build time, so a static import is
+ * impossible). Throws a precise, actionable error when it can't be loaded so a misconfigured deployment
+ * fails loudly, not silently.
+ *
+ * VERIFY against the native Twilio adapter: the module's default/namespace interop + that it exposes
+ * `createClient`.
+ */
+export declare const defaultNativeLoader: NativeModuleLoader;
+/**
+ * A **real, two-way** {@link ITelephonyCallSdk} over the native Twilio Programmable Voice + Media Streams
+ * path.
+ *
+ * Gives the agent both **hearing** (inbound Media-Streams audio → the seam's audio callback) and a
+ * **voice** ({@link sendAudioFrame} → the native Media-Streams send path), plus working DTMF, transfer,
+ * and hangup. Construct via {@link BindTwilioNativeCall} (the factory the bridge's `SetSdkFactory` wants),
+ * not directly, so config resolution + the lazy loader wire consistently.
+ *
+ * The adapter tracks the active Call SID so per-call REST/websocket operations can be addressed, and
+ * re-registers any handlers the bridge set before the call existed once a call comes online.
+ */
+export declare class TwilioNativeCallSdk implements ITelephonyCallSdk {
+    /** Resolved config (credentials + stream URL + the native module specifier). */
+    private readonly config;
+    /** The native-adapter module loader (overridable for tests). */
+    private readonly loadModule;
+    /** The live native client once {@link dial}/{@link answer} brings a call online. */
+    private client;
+    /** The active call's SID, so per-call operations can address it. */
+    private activeCallId;
+    /** The inbound audio handler the bridge registered (may predate the call). */
+    private audioHandler?;
+    /** The inbound DTMF handler the bridge registered (may predate the call). */
+    private dtmfHandler?;
+    /** The call-ended handler the bridge registered (may predate the call). */
+    private endedHandler?;
+    /**
+     * @param config Resolved credentials + stream URL + the native module specifier.
+     * @param loadModule The native-adapter loader (defaults to the lazy specifier loader).
+     */
+    constructor(config: TwilioNativeSdkConfig, loadModule?: NativeModuleLoader);
+    /**
+     * Loads the native adapter, constructs a client, wires its callbacks, and places the **outbound** call.
+     * Brings BOTH hearing and the agent's voice online. Resolves the platform-native Call SID.
+     *
+     * @param toNumber The destination phone number to dial.
+     * @param fromNumber The agent's caller-id / DID the call originates from.
+     * @param args Provider-specific dial parameters.
+     * @returns The Twilio Call SID for the placed call.
+     * @throws When the native module specifier is missing or the adapter can't be loaded.
+     */
+    dial(toNumber: string, fromNumber: string, args?: Record<string, unknown>): Promise<string>;
+    /**
+     * Loads the native adapter, constructs a client, wires its callbacks, and **answers** an inbound call
+     * already delivered to the agent's number. Brings BOTH hearing and the agent's voice online.
+     *
+     * @param callId The platform-native identifier of the inbound call to answer.
+     * @throws When the native module specifier is missing or the adapter can't be loaded.
+     */
+    answer(callId: string): Promise<void>;
+    /**
+     * Hangs up the call via the native client and clears the active call. Tolerant of teardown errors.
+     *
+     * @param callId The platform-native identifier of the call to end.
+     */
+    hangup(callId: string): Promise<void>;
+    /**
+     * Sends one raw PCM frame as the agent's outbound voice into the call — **the agent's real voice on
+     * the call**, via the native Media-Streams send path. No-ops (without throwing) before a call exists
+     * so an early model frame never crashes the session.
+     *
+     * @param pcm The PCM audio bytes to speak into the call.
+     */
+    sendAudioFrame(pcm: ArrayBuffer): void;
+    /**
+     * Registers the inbound audio handler (the agent's hearing path). Wires it to the live client when a
+     * call already exists; otherwise it is (re-)registered at {@link bindCall} when the call comes online.
+     *
+     * @param cb Invoked with each inbound PCM audio frame.
+     */
+    onAudioFrame(cb: (pcm: ArrayBuffer) => void): void;
+    /**
+     * Sends DTMF touch-tones on the call via the native client. No-ops (without throwing) before a call
+     * exists.
+     *
+     * @param digits The DTMF digit string to send.
+     */
+    sendDtmf(digits: string): Promise<void>;
+    /**
+     * Registers the inbound DTMF handler. Wires it to the live client when a call already exists; otherwise
+     * it is (re-)registered at {@link bindCall} when the call comes online.
+     *
+     * @param cb Invoked with each received DTMF digit string.
+     */
+    onDtmf(cb: (digits: string) => void): void;
+    /**
+     * Transfers the live call to another party via the native client. No-ops (without throwing) before a
+     * call exists.
+     *
+     * @param callId The platform-native identifier of the call to transfer.
+     * @param toNumber The transfer destination.
+     */
+    transfer(callId: string, toNumber: string): Promise<void>;
+    /**
+     * Registers the call-ended handler. Wires it to the live client when a call already exists; otherwise
+     * it is (re-)registered at {@link bindCall} when the call comes online.
+     *
+     * @param cb Invoked when the call ends.
+     */
+    onCallEnded(cb: () => void): void;
+    /**
+     * Lazily loads the native adapter and constructs the client (once), throwing an actionable error when
+     * the required {@link TwilioNativeSdkConfig.NativeModuleSpecifier} is absent.
+     */
+    private ensureClient;
+    /** Binds the active Call SID and (re-)registers any handlers the bridge set before the call existed. */
+    private bindCall;
+}
+/**
+ * Builds the {@link import('@memberjunction/ai-bridge-base').TelephonyCallSdkFactory}-shaped factory that
+ * constructs a {@link TwilioNativeCallSdk} from the bridge's per-session `Configuration`. Pass the result
+ * to `TwilioBridge.SetSdkFactory(...)` so a deployment activates **two-way native Twilio audio** without
+ * code changes to the driver.
+ *
+ * Reads Twilio credentials + stream URL + the native module specifier out of the config map the engine
+ * passes at connect (credentials resolved upstream — **never inline secrets**).
+ *
+ * @example
+ * // Where bridge drivers are configured (creds already resolved from the MJ credential system):
+ * bridge.SetSdkFactory(BindTwilioNativeCall());
+ *
+ * @param loadModule Optional native-adapter loader override (tests inject a fake; production omits it).
+ * @returns A factory `(config) => TwilioNativeCallSdk`.
+ */
+export declare function BindTwilioNativeCall(loadModule?: NativeModuleLoader): (config?: Record<string, unknown>) => TwilioNativeCallSdk;
+/**
+ * Extracts a {@link TwilioNativeSdkConfig} from the engine's loosely-typed `Configuration` map without
+ * ever widening to `any`. Each field is read + type-checked individually so a malformed config yields a
+ * clean, partially-resolved object (and {@link TwilioNativeCallSdk} then throws a precise error if the
+ * required specifier is absent) rather than a half-typed blob.
+ */
+export declare function readNativeConfig(config?: Record<string, unknown>): TwilioNativeSdkConfig;
+//# sourceMappingURL=twilio-native-call-sdk.d.ts.map

package/dist/twilio-native-call-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio-native-call-sdk.d.ts","sourceRoot":"","sources":["../src/twilio-native-call-sdk.ts"],"names":[],"mappings":"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"}