ue-softphone-sdk 2.2.3 → 2.2.4

package/dist/platform/web/session-description-handler/session-description-handler.d.ts

@@ -0,0 +1,212 @@
+import { BodyAndContentType, SessionDescriptionHandler as SessionDescriptionHandlerDefinition, SessionDescriptionHandlerModifier } from "../../../api";
+import { Logger } from "../../../core";
+import { MediaStreamFactory } from "./media-stream-factory";
+import { SessionDescriptionHandlerConfiguration } from "./session-description-handler-configuration";
+import { SessionDescriptionHandlerOptions } from "./session-description-handler-options";
+import { PeerConnectionDelegate } from "./peer-connection-delegate";
+/**
+ * A base class implementing a WebRTC session description handler for sip.js.
+ * @remarks
+ * It is expected/intended to be extended by specific WebRTC based applications.
+ * @privateRemarks
+ * So do not put application specific implementation in here.
+ * @public
+ */
+export declare class SessionDescriptionHandler implements SessionDescriptionHandlerDefinition {
+    /** Logger. */
+    protected logger: Logger;
+    /** Media stream factory. */
+    protected mediaStreamFactory: MediaStreamFactory;
+    /** Configuration options. */
+    protected sessionDescriptionHandlerConfiguration?: SessionDescriptionHandlerConfiguration;
+    /** The local media stream. */
+    protected _localMediaStream: MediaStream;
+    /** The remote media stream. */
+    protected _remoteMediaStream: MediaStream;
+    /** The data channel. Undefined before created. */
+    protected _dataChannel: RTCDataChannel | undefined;
+    /** The peer connection. Undefined after SessionDescriptionHandler.close(). */
+    protected _peerConnection: RTCPeerConnection | undefined;
+    /** The peer connection delegate. */
+    protected _peerConnectionDelegate: PeerConnectionDelegate | undefined;
+    private iceGatheringCompletePromise;
+    private iceGatheringCompleteTimeoutId;
+    private iceGatheringCompleteResolve;
+    private iceGatheringCompleteReject;
+    private localMediaStreamConstraints;
+    private onDataChannel;
+    /**
+     * Constructor
+     * @param logger - A logger
+     * @param mediaStreamFactory - A factory to provide a MediaStream
+     * @param options - Options passed from the SessionDescriptionHandleFactory
+     */
+    constructor(logger: Logger, mediaStreamFactory: MediaStreamFactory, sessionDescriptionHandlerConfiguration?: SessionDescriptionHandlerConfiguration);
+    /**
+     * The local media stream currently being sent.
+     *
+     * @remarks
+     * The local media stream initially has no tracks, so the presence of tracks
+     * should not be assumed. Furthermore, tracks may be added or removed if the
+     * local media changes - for example, on upgrade from audio only to a video session.
+     * At any given time there will be at most one audio track and one video track
+     * (it's possible that this restriction may not apply to sub-classes).
+     * Use `MediaStream.onaddtrack` or add a listener for the `addtrack` event
+     * to detect when a new track becomes available:
+     * https://developer.mozilla.org/en-US/docs/Web/API/MediaStream/onaddtrack
+     */
+    get localMediaStream(): MediaStream;
+    /**
+     * The remote media stream currently being received.
+     *
+     * @remarks
+     * The remote media stream initially has no tracks, so the presence of tracks
+     * should not be assumed. Furthermore, tracks may be added or removed if the
+     * remote media changes - for example, on upgrade from audio only to a video session.
+     * At any given time there will be at most one audio track and one video track
+     * (it's possible that this restriction may not apply to sub-classes).
+     * Use `MediaStream.onaddtrack` or add a listener for the `addtrack` event
+     * to detect when a new track becomes available:
+     * https://developer.mozilla.org/en-US/docs/Web/API/MediaStream/onaddtrack
+     */
+    get remoteMediaStream(): MediaStream;
+    /**
+     * The data channel. Undefined before it is created.
+     */
+    get dataChannel(): RTCDataChannel | undefined;
+    /**
+     * The peer connection. Undefined if peer connection has closed.
+     *
+     * @remarks
+     * While access to the underlying `RTCPeerConnection` is provided, note that
+     * using methods with modify it may break the operation of this class.
+     * In particular, this class depends on exclusive access to the
+     * event handler properties. If you need access to the peer connection
+     * events, either register for events using `addEventListener()` on
+     * the `RTCPeerConnection` or set the `peerConnectionDelegate` on
+     * this `SessionDescriptionHandler`.
+     */
+    get peerConnection(): RTCPeerConnection | undefined;
+    /**
+     * A delegate which provides access to the peer connection event handlers.
+     *
+     * @remarks
+     * Setting the peer connection event handlers directly is not supported
+     * and may break this class. As this class depends on exclusive access
+     * to them, a delegate may be set which provides alternative access to
+     * the event handlers in a fashion which is supported.
+     */
+    get peerConnectionDelegate(): PeerConnectionDelegate | undefined;
+    set peerConnectionDelegate(delegate: PeerConnectionDelegate | undefined);
+    private static dispatchAddTrackEvent;
+    private static dispatchRemoveTrackEvent;
+    /**
+     * Stop tracks and close peer connection.
+     */
+    close(): void;
+    /**
+     * Creates an offer or answer.
+     * @param options - Options bucket.
+     * @param modifiers - Modifiers.
+     */
+    getDescription(options?: SessionDescriptionHandlerOptions, modifiers?: Array<SessionDescriptionHandlerModifier>): Promise<BodyAndContentType>;
+    /**
+     * Returns true if the SessionDescriptionHandler can handle the Content-Type described by a SIP message.
+     * @param contentType - The content type that is in the SIP Message.
+     */
+    hasDescription(contentType: string): boolean;
+    /**
+     * Send DTMF via RTP (RFC 4733).
+     * Returns true if DTMF send is successful, false otherwise.
+     * @param tones - A string containing DTMF digits.
+     * @param options - Options object to be used by sendDtmf.
+     */
+    sendDtmf(tones: string, options?: {
+        duration: number;
+        interToneGap: number;
+    }): boolean;
+    /**
+     * Sets an offer or answer.
+     * @param sdp - The session description.
+     * @param options - Options bucket.
+     * @param modifiers - Modifiers.
+     */
+    setDescription(sdp: string, options?: SessionDescriptionHandlerOptions, modifiers?: Array<SessionDescriptionHandlerModifier>): Promise<void>;
+    /**
+     * Applies modifiers to SDP prior to setting the local or remote description.
+     * @param sdp - SDP to modify.
+     * @param modifiers - Modifiers to apply.
+     */
+    protected applyModifiers(sdp: RTCSessionDescriptionInit, modifiers?: Array<SessionDescriptionHandlerModifier>): Promise<RTCSessionDescriptionInit>;
+    /**
+     * Create a data channel.
+     * @remarks
+     * Only creates a data channel if SessionDescriptionHandlerOptions.dataChannel is true.
+     * Only creates a data channel if creating a local offer.
+     * Only if one does not already exist.
+     * @param options - Session description handler options.
+     */
+    protected createDataChannel(options?: SessionDescriptionHandlerOptions): Promise<void>;
+    /**
+     * Depending on current signaling state, create a local offer or answer.
+     * @param options - Session description handler options.
+     */
+    protected createLocalOfferOrAnswer(options?: SessionDescriptionHandlerOptions): Promise<RTCSessionDescriptionInit>;
+    /**
+     * Get a media stream from the media stream factory and set the local media stream.
+     * @param options - Session description handler options.
+     */
+    protected getLocalMediaStream(options?: SessionDescriptionHandlerOptions): Promise<void>;
+    /**
+     * Sets the peer connection's sender tracks and local media stream tracks.
+     *
+     * @remarks
+     * Only the first audio and video tracks of the provided MediaStream are utilized.
+     * Adds tracks if audio and/or video tracks are not already present, otherwise replaces tracks.
+     *
+     * @param stream - Media stream containing tracks to be utilized.
+     */
+    protected setLocalMediaStream(stream: MediaStream): Promise<void>;
+    /**
+     * Gets the peer connection's local session description.
+     */
+    protected getLocalSessionDescription(): Promise<RTCSessionDescription>;
+    /**
+     * Sets the peer connection's local session description.
+     * @param sessionDescription - sessionDescription The session description.
+     */
+    protected setLocalSessionDescription(sessionDescription: RTCSessionDescriptionInit): Promise<void>;
+    /**
+     * Sets the peer connection's remote session description.
+     * @param sessionDescription - The session description.
+     */
+    protected setRemoteSessionDescription(sessionDescription: RTCSessionDescriptionInit): Promise<void>;
+    /**
+     * Sets a remote media stream track.
+     *
+     * @remarks
+     * Adds tracks if audio and/or video tracks are not already present, otherwise replaces tracks.
+     *
+     * @param track - Media stream track to be utilized.
+     */
+    protected setRemoteTrack(track: MediaStreamTrack): void;
+    /**
+     * Depending on the current signaling state and the session hold state, update transceiver direction.
+     * @param options - Session description handler options.
+     */
+    protected updateDirection(options?: SessionDescriptionHandlerOptions): Promise<void>;
+    /**
+     * Called when ICE gathering completes and resolves any waiting promise.
+     */
+    protected iceGatheringComplete(): void;
+    /**
+     * Wait for ICE gathering to complete.
+     * @param restart - If true, waits if current state is "complete" (waits for transition to "complete").
+     * @param timeout - Milliseconds after which waiting times out. No timeout if 0.
+     */
+    protected waitForIceGatheringComplete(restart?: boolean, timeout?: number): Promise<void>;
+    /**
+     * Initializes the peer connection event handlers
+     */
+    private initPeerConnectionEventHandlers;
+}

package/dist/platform/web/simple-user/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A simple SIP user implementation for web browsers.
+ * @packageDocumentation
+ */
+export * from "./simple-user";
+export * from "./simple-user-delegate";
+export * from "./simple-user-options";

package/dist/platform/web/simple-user/simple-user-delegate.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Delegate for {@link SimpleUser}.
+ * @public
+ */
+export interface SimpleUserDelegate {
+    /**
+     * Called when a call is answered.
+     * @remarks
+     * Callback for handling establishment of a new Session.
+     */
+    onCallAnswered?(): void;
+    /**
+     * Called when a call is created.
+     * @remarks
+     * Callback for handling the creation of a new Session.
+     */
+    onCallCreated?(): void;
+    /**
+     * Called when a call is received.
+     * @remarks
+     * Callback for handling incoming INVITE requests.
+     * The callback must either accept or reject the incoming call by calling `answer()` or `decline()` respectively.
+     */
+    onCallReceived?(): void;
+    /**
+     * Called when a call is hung up.
+     * @remarks
+     * Callback for handling termination of a Session.
+     */
+    onCallHangup?(): void;
+    /**
+     * Called when a call is put on hold or taken off hold.
+     * @remarks
+     * Callback for handling re-INVITE responses.
+     */
+    onCallHold?(held: boolean): void;
+    /**
+     * Called when a call receives an incoming DTMF tone.
+     * @remarks
+     * Callback for handling an incoming INFO request with content type application/dtmf-relay.
+     */
+    onCallDTMFReceived?(tone: string, duration: number): void;
+    /**
+     * Called upon receiving a message.
+     * @remarks
+     * Callback for handling incoming MESSAGE requests.
+     * @param message - The message received.
+     */
+    onMessageReceived?(message: string): void;
+    /**
+     * Called when user is registered to received calls.
+     */
+    onRegistered?(): void;
+    /**
+     * Called when user is no longer registered to received calls.
+     */
+    onUnregistered?(): void;
+    /**
+     * Called when user is connected to server.
+     * @remarks
+     * Callback for handling user becomes connected.
+     */
+    onServerConnect?(): void;
+    /**
+     * Called when user is no longer connected.
+     * @remarks
+     * Callback for handling user becomes disconnected.
+     *
+     * @param error - An Error if server caused the disconnect. Otherwise undefined.
+     */
+    onServerDisconnect?(error?: Error): void;
+}

package/dist/platform/web/simple-user/simple-user-options.d.ts

@@ -0,0 +1,90 @@
+import { UserAgentOptions } from "../../../api";
+import { SimpleUserDelegate } from "./simple-user-delegate";
+/**
+ * Media for {@link SimpleUserOptions}.
+ * @public
+ */
+export interface SimpleUserMedia {
+    /**
+     * Offer/Answer constraints determine if audio and/or video are utilized.
+     * If not specified, only audio is utilized (audio is true, video is false).
+     * @remarks
+     * Constraints are used when creating local media stream.
+     * If undefined, defaults to audio true and video false.
+     * If audio and video are false, media stream will have no tracks.
+     */
+    constraints?: SimpleUserMediaConstraints;
+    /** HTML elements for local media streams. */
+    local?: SimpleUserMediaLocal;
+    /** Local HTML media elements. */
+    remote?: SimpleUserMediaRemote;
+}
+/**
+ * Constraints for {@link SimpleUserMedia}.
+ * @public
+ */
+export interface SimpleUserMediaConstraints {
+    /** If true, offer and answer to send and receive audio. */
+    audio: boolean;
+    /** If true, offer and answer to send and receive video. */
+    video: boolean;
+}
+/**
+ * Local media elements for {@link SimpleUserMedia}.
+ * @public
+ */
+export interface SimpleUserMediaLocal {
+    /** The local video media stream is attached to this element. */
+    video?: HTMLVideoElement;
+}
+/**
+ * Remote media elements for {@link SimpleUserMedia}.
+ * @public
+ */
+export interface SimpleUserMediaRemote {
+    /** The remote audio media stream is attached to this element. */
+    audio?: HTMLAudioElement;
+    /** The remote video media stream is attached to this element. */
+    video?: HTMLVideoElement;
+}
+/**
+ * Options for {@link SimpleUser}.
+ * @public
+ */
+export interface SimpleUserOptions {
+    /**
+     * User's SIP Address of Record (AOR).
+     * @remarks
+     * The AOR is registered to receive incoming calls.
+     * If not specified, a random anonymous address is created for the user.
+     */
+    aor?: string;
+    /**
+     * Delegate for SimpleUser.
+     */
+    delegate?: SimpleUserDelegate;
+    /**
+     * Media options.
+     */
+    media?: SimpleUserMedia;
+    /**
+     * Maximum number of times to attempt to reconnection.
+     * @remarks
+     * When the transport connection is lost (WebSocket disconnects),
+     * reconnection will be attempted immediately. If that fails,
+     * reconnection will be attempted again when the browser indicates
+     * the application has come online. See:
+     * https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine
+     * @defaultValue 3
+     */
+    reconnectionAttempts?: number;
+    /**
+     * Seconds to wait between reconnection attempts.
+     * @defaultValue 4
+     */
+    reconnectionDelay?: number;
+    /**
+     * Options for UserAgent.
+     */
+    userAgentOptions?: UserAgentOptions;
+}

package/dist/platform/web/simple-user/simple-user.d.ts

@@ -0,0 +1,226 @@
+import { InvitationAcceptOptions, InviterInviteOptions, InviterOptions, RegistererOptions, RegistererRegisterOptions, RegistererUnregisterOptions } from "../../../api";
+import { SimpleUserDelegate } from "./simple-user-delegate";
+import { SimpleUserOptions } from "./simple-user-options";
+/**
+ * A simple SIP user class.
+ * @remarks
+ * While this class is completely functional for simple use cases, it is not intended
+ * to provide an interface which is suitable for most (must less all) applications.
+ * While this class has many limitations (for example, it only handles a single concurrent session),
+ * it is, however, intended to serve as a simple example of using the SIP.js API.
+ * @public
+ */
+export declare class SimpleUser {
+    /** Delegate. */
+    delegate: SimpleUserDelegate | undefined;
+    private attemptingReconnection;
+    private connectRequested;
+    private logger;
+    private held;
+    private muted;
+    private options;
+    private registerer;
+    private registerRequested;
+    private session;
+    private userAgent;
+    /**
+     * Constructs a new instance of the `SimpleUser` class.
+     * @param server - SIP WebSocket Server URL.
+     * @param options - Options bucket. See {@link SimpleUserOptions} for details.
+     */
+    constructor(server: string, options?: SimpleUserOptions);
+    /**
+     * Instance identifier.
+     * @internal
+     */
+    get id(): string;
+    /** The local media stream. Undefined if call not answered. */
+    get localMediaStream(): MediaStream | undefined;
+    /** The remote media stream. Undefined if call not answered. */
+    get remoteMediaStream(): MediaStream | undefined;
+    /**
+     * The local audio track, if available.
+     * @deprecated Use localMediaStream and get track from the stream.
+     */
+    get localAudioTrack(): MediaStreamTrack | undefined;
+    /**
+     * The local video track, if available.
+     * @deprecated Use localMediaStream and get track from the stream.
+     */
+    get localVideoTrack(): MediaStreamTrack | undefined;
+    /**
+     * The remote audio track, if available.
+     * @deprecated Use remoteMediaStream and get track from the stream.
+     */
+    get remoteAudioTrack(): MediaStreamTrack | undefined;
+    /**
+     * The remote video track, if available.
+     * @deprecated Use remoteMediaStream and get track from the stream.
+     */
+    get remoteVideoTrack(): MediaStreamTrack | undefined;
+    /**
+     * Connect.
+     * @remarks
+     * Start the UserAgent's WebSocket Transport.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect.
+     * @remarks
+     * Stop the UserAgent's WebSocket Transport.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Return true if connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Start receiving incoming calls.
+     * @remarks
+     * Send a REGISTER request for the UserAgent's AOR.
+     * Resolves when the REGISTER request is sent, otherwise rejects.
+     */
+    register(registererOptions?: RegistererOptions, registererRegisterOptions?: RegistererRegisterOptions): Promise<void>;
+    /**
+     * Stop receiving incoming calls.
+     * @remarks
+     * Send an un-REGISTER request for the UserAgent's AOR.
+     * Resolves when the un-REGISTER request is sent, otherwise rejects.
+     */
+    unregister(registererUnregisterOptions?: RegistererUnregisterOptions): Promise<void>;
+    /**
+     * Make an outgoing call.
+     * @remarks
+     * Send an INVITE request to create a new Session.
+     * Resolves when the INVITE request is sent, otherwise rejects.
+     * Use `onCallAnswered` delegate method to determine if Session is established.
+     * @param destination - The target destination to call. A SIP address to send the INVITE to.
+     * @param inviterOptions - Optional options for Inviter constructor.
+     * @param inviterInviteOptions - Optional options for Inviter.invite().
+     */
+    call(destination: string, inviterOptions?: InviterOptions, inviterInviteOptions?: InviterInviteOptions): Promise<void>;
+    /**
+     * Hangup a call.
+     * @remarks
+     * Send a BYE request, CANCEL request or reject response to end the current Session.
+     * Resolves when the request/response is sent, otherwise rejects.
+     * Use `onCallTerminated` delegate method to determine if and when call is ended.
+     */
+    hangup(): Promise<void>;
+    /**
+     * Answer an incoming call.
+     * @remarks
+     * Accept an incoming INVITE request creating a new Session.
+     * Resolves with the response is sent, otherwise rejects.
+     * Use `onCallAnswered` delegate method to determine if and when call is established.
+     * @param invitationAcceptOptions - Optional options for Inviter.accept().
+     */
+    answer(invitationAcceptOptions?: InvitationAcceptOptions): Promise<void>;
+    /**
+     * Decline an incoming call.
+     * @remarks
+     * Reject an incoming INVITE request.
+     * Resolves with the response is sent, otherwise rejects.
+     * Use `onCallTerminated` delegate method to determine if and when call is ended.
+     */
+    decline(): Promise<void>;
+    /**
+     * Hold call
+     * @remarks
+     * Send a re-INVITE with new offer indicating "hold".
+     * Resolves when the re-INVITE request is sent, otherwise rejects.
+     * Use `onCallHold` delegate method to determine if request is accepted or rejected.
+     * See: https://tools.ietf.org/html/rfc6337
+     */
+    hold(): Promise<void>;
+    /**
+     * Unhold call.
+     * @remarks
+     * Send a re-INVITE with new offer indicating "unhold".
+     * Resolves when the re-INVITE request is sent, otherwise rejects.
+     * Use `onCallHold` delegate method to determine if request is accepted or rejected.
+     * See: https://tools.ietf.org/html/rfc6337
+     */
+    unhold(): Promise<void>;
+    /**
+     * Hold state.
+     * @remarks
+     * True if session media is on hold.
+     */
+    isHeld(): boolean;
+    /**
+     * Mute call.
+     * @remarks
+     * Disable sender's media tracks.
+     */
+    mute(): void;
+    /**
+     * Unmute call.
+     * @remarks
+     * Enable sender's media tracks.
+     */
+    unmute(): void;
+    /**
+     * Mute state.
+     * @remarks
+     * True if sender's media track is disabled.
+     */
+    isMuted(): boolean;
+    /**
+     * Send DTMF.
+     * @remarks
+     * Send an INFO request with content type application/dtmf-relay.
+     * @param tone - Tone to send.
+     */
+    sendDTMF(tone: string): Promise<void>;
+    /**
+     * Send a message.
+     * @remarks
+     * Send a MESSAGE request.
+     * @param destination - The target destination for the message. A SIP address to send the MESSAGE to.
+     */
+    message(destination: string, message: string): Promise<void>;
+    /** Media constraints. */
+    private get constraints();
+    /**
+     * Attempt reconnection up to `maxReconnectionAttempts` times.
+     * @param reconnectionAttempt - Current attempt number.
+     */
+    private attemptReconnection;
+    /** Helper function to remove media from html elements. */
+    private cleanupMedia;
+    /** Helper function to enable/disable media tracks. */
+    private enableReceiverTracks;
+    /** Helper function to enable/disable media tracks. */
+    private enableSenderTracks;
+    /**
+     * Setup session delegate and state change handler.
+     * @param session - Session to setup
+     * @param referralInviterOptions - Options for any Inviter created as result of a REFER.
+     */
+    private initSession;
+    /** Helper function to init send then send invite. */
+    private sendInvite;
+    /**
+     * Puts Session on hold.
+     * @param hold - Hold on if true, off if false.
+     */
+    private setHold;
+    /**
+     * Puts Session on mute.
+     * @param mute - Mute on if true, off if false.
+     */
+    private setMute;
+    /** Helper function to attach local media to html elements. */
+    private setupLocalMedia;
+    /** Helper function to attach remote media to html elements. */
+    private setupRemoteMedia;
+    /**
+     * End a session.
+     * @remarks
+     * Send a BYE request, CANCEL request or reject response to end the current Session.
+     * Resolves when the request/response is sent, otherwise rejects.
+     * Use `onCallTerminated` delegate method to determine if and when Session is terminated.
+     */
+    private terminate;
+}

package/dist/platform/web/transport/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A Transport implementation for web browsers.
+ * @packageDocumentation
+ */
+export * from "./transport";
+export * from "./transport-options";

package/dist/platform/web/transport/transport-options.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transport options.
+ * @public
+ */
+export interface TransportOptions {
+    /**
+     * URL of WebSocket server to connect with. For example, "wss://localhost:8080".
+     */
+    server: string;
+    /**
+     * Seconds to wait for WebSocket to connect before giving up.
+     * @defaultValue `5`
+     */
+    connectionTimeout?: number;
+    /**
+     * Keep alive - needs review.
+     * @internal
+     */
+    keepAliveInterval?: number;
+    /**
+     * Keep alive - needs review.
+     * @internal
+     */
+    keepAliveDebounce?: number;
+    /**
+     * If true, messages sent and received by the transport are logged.
+     * @defaultValue `true`
+     */
+    traceSip?: boolean;
+}