@coventia/softphone 0.1.0

package/dist/engine-D9nbeY08.d.cts

@@ -0,0 +1,115 @@
+import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, o as SoftphoneState, k as SoftphoneError } from './call-BTYlT2SU.cjs';
+
+/**
+ * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.
+ *
+ * This is the boundary `Softphone` and `Call` delegate to. It is DISTINCT from `SipProvider`
+ * (transports/providers/provider.ts), and the distinction is the whole reason S2 works:
+ *
+ *   - `SipProvider` provisions CREDENTIALS (provision / registrationMode / quirks). It is a
+ *     sub-component of the real SIP engine — Zadarma vs. our own infrastructure.
+ *   - `CallEngine` places and drives CALLS. The SIP engine (S3) implements it *using* a SipProvider;
+ *     the mock (S2) implements it directly, replacing the SIP layer wholesale.
+ *
+ * Softphone/Call therefore know nothing about JsSIP, SIP, or credentials — only about this engine.
+ * A mock that scripts a call lifecycle and the real JsSIP engine both satisfy it, and the contract
+ * suite (SPEC §9) runs against both so the playground can never drift from production.
+ *
+ * The engine speaks in RAW SIGNALS (`EngineCallEvent`), not call states. Translating those into the
+ * public state machine (SPEC §5.3) is `Call`'s job, and lives in exactly one place.
+ */
+/** What the engine tells `Call` happened. Raw; not yet a state. */
+type EngineCallEvent = 
+/** Outbound: a provisional response. `early` may carry ringback media. */
+{
+    readonly type: 'progress';
+    readonly response: 'ringing' | 'early';
+}
+/** Media is up (200 OK + ACK, or inbound answer confirmed). */
+ | {
+    readonly type: 'accepted';
+}
+/**
+ * Terminal. Fires exactly once.
+ *
+ * `cause` is the transport's own raw reason (for SIP, the JsSIP cause — `'Unavailable'`,
+ * `'Not Found'`…) and is present only when one ended the call. `reason` is the coarse outcome the
+ * UI acts on; several causes map onto each, and the specific one is what makes a `call/failed`
+ * diagnosable after the fact. Never show it to a user: it is untranslated protocol vocabulary.
+ */
+ | {
+    readonly type: 'ended';
+    readonly reason: HangupReason;
+    readonly cause?: string | undefined;
+} | {
+    readonly type: 'held';
+    readonly originator: HoldOriginator;
+} | {
+    readonly type: 'unheld';
+    readonly originator: HoldOriginator;
+} | {
+    readonly type: 'reconnecting';
+} | {
+    readonly type: 'reconnected';
+}
+/** Media stream to route to the call audio element. */
+ | {
+    readonly type: 'stream';
+    readonly stream: MediaStream;
+};
+/**
+ * The engine's handle to one live call: the command surface plus its raw event source.
+ *
+ * Commands are effects only — they never mutate call state directly. State moves only in response to
+ * an `EngineCallEvent`, so the real (async, provider-confirmed) transitions and the mock's scripted
+ * ones travel the exact same path through `Call`.
+ */
+interface EngineCall {
+    readonly id: string;
+    readonly direction: CallDirection;
+    readonly remoteNumber: string;
+    answer(): Promise<void>;
+    reject(): Promise<void>;
+    hangup(): Promise<void>;
+    mute(muted: boolean): void;
+    hold(): Promise<void>;
+    unhold(): Promise<void>;
+    sendDigits(digits: string): void;
+    transfer(target: string): Promise<void>;
+    /** Attended transfer: dial the consult target. Returns the consult leg as its own EngineCall. */
+    startConsult(target: string): Promise<EngineCall>;
+    completeTransfer(consult: EngineCall): Promise<void>;
+    onEvent(listener: (event: EngineCallEvent) => void): () => void;
+}
+interface CallEngine {
+    /** Bring the engine to a reachable state (presence up / able to register). */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    placeCall(destination: string, options?: CallOptions): Promise<EngineCall>;
+    /** Fires when an inbound INVITE lands — NOT on a mere presence signal (SPEC §3.3). */
+    onIncoming(listener: (call: EngineCall) => void): () => void;
+    onStateChange(listener: (state: SoftphoneState) => void): () => void;
+    readonly state: SoftphoneState;
+    /**
+     * Report a failure the engine cannot recover from silently. Returns an unsubscribe function.
+     *
+     * **Optional**, so an engine that never fails interestingly — `MockProvider`, or one written before
+     * this existed — still satisfies the interface. `SoftphoneImpl` subscribes only when it is present.
+     *
+     * Without this the engine had the diagnosis and no way to pass it on: a failed registration knew
+     * the cause, the status code and the registrar domain, and could do nothing but `console.warn`
+     * while the widget went on claiming the phone was fine.
+     */
+    onError?(listener: (error: SoftphoneError) => void): () => void;
+    /**
+     * Switch the microphone (SPEC §7 Phase 2, device management): stored for every future call's own
+     * capture, and — if a call is live right now — swapped onto it immediately.
+     *
+     * **Optional**, same reasoning as `onError`: `MockProvider` scripts calls with no real media at
+     * all, so there is nothing for it to swap, and it satisfies the interface by simply not having this
+     * method. `AudioDevices.setInput` only calls it when present.
+     */
+    setInputDevice?(deviceId: string | null): Promise<void>;
+}
+
+export type { CallEngine as C, EngineCall as E };

package/dist/engine-Doa6Brkm.d.ts

@@ -0,0 +1,115 @@
+import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, o as SoftphoneState, k as SoftphoneError } from './call-BTYlT2SU.js';
+
+/**
+ * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.
+ *
+ * This is the boundary `Softphone` and `Call` delegate to. It is DISTINCT from `SipProvider`
+ * (transports/providers/provider.ts), and the distinction is the whole reason S2 works:
+ *
+ *   - `SipProvider` provisions CREDENTIALS (provision / registrationMode / quirks). It is a
+ *     sub-component of the real SIP engine — Zadarma vs. our own infrastructure.
+ *   - `CallEngine` places and drives CALLS. The SIP engine (S3) implements it *using* a SipProvider;
+ *     the mock (S2) implements it directly, replacing the SIP layer wholesale.
+ *
+ * Softphone/Call therefore know nothing about JsSIP, SIP, or credentials — only about this engine.
+ * A mock that scripts a call lifecycle and the real JsSIP engine both satisfy it, and the contract
+ * suite (SPEC §9) runs against both so the playground can never drift from production.
+ *
+ * The engine speaks in RAW SIGNALS (`EngineCallEvent`), not call states. Translating those into the
+ * public state machine (SPEC §5.3) is `Call`'s job, and lives in exactly one place.
+ */
+/** What the engine tells `Call` happened. Raw; not yet a state. */
+type EngineCallEvent = 
+/** Outbound: a provisional response. `early` may carry ringback media. */
+{
+    readonly type: 'progress';
+    readonly response: 'ringing' | 'early';
+}
+/** Media is up (200 OK + ACK, or inbound answer confirmed). */
+ | {
+    readonly type: 'accepted';
+}
+/**
+ * Terminal. Fires exactly once.
+ *
+ * `cause` is the transport's own raw reason (for SIP, the JsSIP cause — `'Unavailable'`,
+ * `'Not Found'`…) and is present only when one ended the call. `reason` is the coarse outcome the
+ * UI acts on; several causes map onto each, and the specific one is what makes a `call/failed`
+ * diagnosable after the fact. Never show it to a user: it is untranslated protocol vocabulary.
+ */
+ | {
+    readonly type: 'ended';
+    readonly reason: HangupReason;
+    readonly cause?: string | undefined;
+} | {
+    readonly type: 'held';
+    readonly originator: HoldOriginator;
+} | {
+    readonly type: 'unheld';
+    readonly originator: HoldOriginator;
+} | {
+    readonly type: 'reconnecting';
+} | {
+    readonly type: 'reconnected';
+}
+/** Media stream to route to the call audio element. */
+ | {
+    readonly type: 'stream';
+    readonly stream: MediaStream;
+};
+/**
+ * The engine's handle to one live call: the command surface plus its raw event source.
+ *
+ * Commands are effects only — they never mutate call state directly. State moves only in response to
+ * an `EngineCallEvent`, so the real (async, provider-confirmed) transitions and the mock's scripted
+ * ones travel the exact same path through `Call`.
+ */
+interface EngineCall {
+    readonly id: string;
+    readonly direction: CallDirection;
+    readonly remoteNumber: string;
+    answer(): Promise<void>;
+    reject(): Promise<void>;
+    hangup(): Promise<void>;
+    mute(muted: boolean): void;
+    hold(): Promise<void>;
+    unhold(): Promise<void>;
+    sendDigits(digits: string): void;
+    transfer(target: string): Promise<void>;
+    /** Attended transfer: dial the consult target. Returns the consult leg as its own EngineCall. */
+    startConsult(target: string): Promise<EngineCall>;
+    completeTransfer(consult: EngineCall): Promise<void>;
+    onEvent(listener: (event: EngineCallEvent) => void): () => void;
+}
+interface CallEngine {
+    /** Bring the engine to a reachable state (presence up / able to register). */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    placeCall(destination: string, options?: CallOptions): Promise<EngineCall>;
+    /** Fires when an inbound INVITE lands — NOT on a mere presence signal (SPEC §3.3). */
+    onIncoming(listener: (call: EngineCall) => void): () => void;
+    onStateChange(listener: (state: SoftphoneState) => void): () => void;
+    readonly state: SoftphoneState;
+    /**
+     * Report a failure the engine cannot recover from silently. Returns an unsubscribe function.
+     *
+     * **Optional**, so an engine that never fails interestingly — `MockProvider`, or one written before
+     * this existed — still satisfies the interface. `SoftphoneImpl` subscribes only when it is present.
+     *
+     * Without this the engine had the diagnosis and no way to pass it on: a failed registration knew
+     * the cause, the status code and the registrar domain, and could do nothing but `console.warn`
+     * while the widget went on claiming the phone was fine.
+     */
+    onError?(listener: (error: SoftphoneError) => void): () => void;
+    /**
+     * Switch the microphone (SPEC §7 Phase 2, device management): stored for every future call's own
+     * capture, and — if a call is live right now — swapped onto it immediately.
+     *
+     * **Optional**, same reasoning as `onError`: `MockProvider` scripts calls with no real media at
+     * all, so there is nothing for it to swap, and it satisfies the interface by simply not having this
+     * method. `AudioDevices.setInput` only calls it when present.
+     */
+    setInputDevice?(deviceId: string | null): Promise<void>;
+}
+
+export type { CallEngine as C, EngineCall as E };