ue-softphone-sdk 2.2.2 → 2.2.4

package/dist/api/inviter.d.ts

@@ -0,0 +1,236 @@
+import { Logger, NameAddrHeader, OutgoingInviteRequest, OutgoingRequestMessage, URI } from "../core";
+import { InviterCancelOptions } from "./inviter-cancel-options";
+import { InviterInviteOptions } from "./inviter-invite-options";
+import { InviterOptions } from "./inviter-options";
+import { Session } from "./session";
+import { BodyAndContentType } from "./session-description-handler";
+import { UserAgent } from "./user-agent";
+/**
+ * An inviter offers to establish a {@link Session} (outgoing INVITE).
+ * @public
+ */
+export declare class Inviter extends Session {
+    /**
+     * If this Inviter was created as a result of a REFER, the referred Session. Otherwise undefined.
+     * @internal
+     */
+    _referred: Session | undefined;
+    /**
+     * Logger.
+     */
+    protected logger: Logger;
+    /** @internal */
+    protected _id: string;
+    /** True if dispose() has been called. */
+    private disposed;
+    /** True if early media use is enabled. */
+    private earlyMedia;
+    /** The early media session. */
+    private earlyMediaDialog;
+    /** The early media session description handlers. */
+    private earlyMediaSessionDescriptionHandlers;
+    /** Our From tag. */
+    private fromTag;
+    /** True if cancel() was called. */
+    private isCanceled;
+    /** True if initial INVITE without SDP. */
+    private inviteWithoutSdp;
+    /** Initial INVITE request sent by core. Undefined until sent. */
+    private outgoingInviteRequest;
+    /** Initial INVITE message provided to core to send. */
+    private outgoingRequestMessage;
+    /**
+     * Constructs a new instance of the `Inviter` class.
+     * @param userAgent - User agent. See {@link UserAgent} for details.
+     * @param targetURI - Request URI identifying the target of the message.
+     * @param options - Options bucket. See {@link InviterOptions} for details.
+     */
+    constructor(userAgent: UserAgent, targetURI: URI, options?: InviterOptions);
+    /**
+     * Destructor.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Initial outgoing INVITE request message body.
+     */
+    get body(): BodyAndContentType | undefined;
+    /**
+     * The identity of the local user.
+     */
+    get localIdentity(): NameAddrHeader;
+    /**
+     * The identity of the remote user.
+     */
+    get remoteIdentity(): NameAddrHeader;
+    /**
+     * Initial outgoing INVITE request message.
+     */
+    get request(): OutgoingRequestMessage;
+    /**
+     * Cancels the INVITE request.
+     *
+     * @remarks
+     * Sends a CANCEL request.
+     * Resolves once the response sent, otherwise rejects.
+     *
+     * After sending a CANCEL request the expectation is that a 487 final response
+     * will be received for the INVITE. However a 200 final response to the INVITE
+     * may nonetheless arrive (it's a race between the CANCEL reaching the UAS before
+     * the UAS sends a 200) in which case an ACK & BYE will be sent. The net effect
+     * is that this method will terminate the session regardless of the race.
+     * @param options - Options bucket.
+     */
+    cancel(options?: InviterCancelOptions): Promise<void>;
+    /**
+     * Sends the INVITE request.
+     *
+     * @remarks
+     * TLDR...
+     *  1) Only one offer/answer exchange permitted during initial INVITE.
+     *  2) No "early media" if the initial offer is in an INVITE (default behavior).
+     *  3) If "early media" and the initial offer is in an INVITE, no INVITE forking.
+     *
+     * 1) Only one offer/answer exchange permitted during initial INVITE.
+     *
+     * Our implementation replaces the following bullet point...
+     *
+     * o  After having sent or received an answer to the first offer, the
+     *    UAC MAY generate subsequent offers in requests based on rules
+     *    specified for that method, but only if it has received answers
+     *    to any previous offers, and has not sent any offers to which it
+     *    hasn't gotten an answer.
+     * https://tools.ietf.org/html/rfc3261#section-13.2.1
+     *
+     * ...with...
+     *
+     * o  After having sent or received an answer to the first offer, the
+     *    UAC MUST NOT generate subsequent offers in requests based on rules
+     *    specified for that method.
+     *
+     * ...which in combination with this bullet point...
+     *
+     * o  Once the UAS has sent or received an answer to the initial
+     *    offer, it MUST NOT generate subsequent offers in any responses
+     *    to the initial INVITE.  This means that a UAS based on this
+     *    specification alone can never generate subsequent offers until
+     *    completion of the initial transaction.
+     * https://tools.ietf.org/html/rfc3261#section-13.2.1
+     *
+     * ...ensures that EXACTLY ONE offer/answer exchange will occur
+     * during an initial out of dialog INVITE request made by our UAC.
+     *
+     *
+     * 2) No "early media" if the initial offer is in an INVITE (default behavior).
+     *
+     * While our implementation adheres to the following bullet point...
+     *
+     * o  If the initial offer is in an INVITE, the answer MUST be in a
+     *    reliable non-failure message from UAS back to UAC which is
+     *    correlated to that INVITE.  For this specification, that is
+     *    only the final 2xx response to that INVITE.  That same exact
+     *    answer MAY also be placed in any provisional responses sent
+     *    prior to the answer.  The UAC MUST treat the first session
+     *    description it receives as the answer, and MUST ignore any
+     *    session descriptions in subsequent responses to the initial
+     *    INVITE.
+     * https://tools.ietf.org/html/rfc3261#section-13.2.1
+     *
+     * We have made the following implementation decision with regard to early media...
+     *
+     * o  If the initial offer is in the INVITE, the answer from the
+     *    UAS back to the UAC will establish a media session only
+     *    only after the final 2xx response to that INVITE is received.
+     *
+     * The reason for this decision is rooted in a restriction currently
+     * inherent in WebRTC. Specifically, while a SIP INVITE request with an
+     * initial offer may fork resulting in more than one provisional answer,
+     * there is currently no easy/good way to to "fork" an offer generated
+     * by a peer connection. In particular, a WebRTC offer currently may only
+     * be matched with one answer and we have no good way to know which
+     * "provisional answer" is going to be the "final answer". So we have
+     * decided to punt and not create any "early media" sessions in this case.
+     *
+     * The upshot is that if you want "early media", you must not put the
+     * initial offer in the INVITE. Instead, force the UAS to provide the
+     * initial offer by sending an INVITE without an offer. In the WebRTC
+     * case this allows us to create a unique peer connection with a unique
+     * answer for every provisional offer with "early media" on all of them.
+     *
+     *
+     * 3) If "early media" and the initial offer is in an INVITE, no INVITE forking.
+     *
+     * The default behavior may be altered and "early media" utilized if the
+     * initial offer is in the an INVITE by setting the `earlyMedia` options.
+     * However in that case the INVITE request MUST NOT fork. This allows for
+     * "early media" in environments where the forking behavior of the SIP
+     * servers being utilized is configured to disallow forking.
+     */
+    invite(options?: InviterInviteOptions): Promise<OutgoingInviteRequest>;
+    /**
+     * 13.2.1 Creating the Initial INVITE
+     *
+     * Since the initial INVITE represents a request outside of a dialog,
+     * its construction follows the procedures of Section 8.1.1.  Additional
+     * processing is required for the specific case of INVITE.
+     *
+     * An Allow header field (Section 20.5) SHOULD be present in the INVITE.
+     * It indicates what methods can be invoked within a dialog, on the UA
+     * sending the INVITE, for the duration of the dialog.  For example, a
+     * UA capable of receiving INFO requests within a dialog [34] SHOULD
+     * include an Allow header field listing the INFO method.
+     *
+     * A Supported header field (Section 20.37) SHOULD be present in the
+     * INVITE.  It enumerates all the extensions understood by the UAC.
+     *
+     * An Accept (Section 20.1) header field MAY be present in the INVITE.
+     * It indicates which Content-Types are acceptable to the UA, in both
+     * the response received by it, and in any subsequent requests sent to
+     * it within dialogs established by the INVITE.  The Accept header field
+     * is especially useful for indicating support of various session
+     * description formats.
+     *
+     * The UAC MAY add an Expires header field (Section 20.19) to limit the
+     * validity of the invitation.  If the time indicated in the Expires
+     * header field is reached and no final answer for the INVITE has been
+     * received, the UAC core SHOULD generate a CANCEL request for the
+     * INVITE, as per Section 9.
+     *
+     * A UAC MAY also find it useful to add, among others, Subject (Section
+     * 20.36), Organization (Section 20.25) and User-Agent (Section 20.41)
+     * header fields.  They all contain information related to the INVITE.
+     *
+     * The UAC MAY choose to add a message body to the INVITE.  Section
+     * 8.1.1.10 deals with how to construct the header fields -- Content-
+     * Type among others -- needed to describe the message body.
+     *
+     * https://tools.ietf.org/html/rfc3261#section-13.2.1
+     */
+    private sendInvite;
+    private disposeEarlyMedia;
+    private notifyReferer;
+    /**
+     * Handle final response to initial INVITE.
+     * @param inviteResponse - 2xx response.
+     */
+    private onAccept;
+    /**
+     * Handle provisional response to initial INVITE.
+     * @param inviteResponse - 1xx response.
+     */
+    private onProgress;
+    /**
+     * Handle final response to initial INVITE.
+     * @param inviteResponse - 3xx response.
+     */
+    private onRedirect;
+    /**
+     * Handle final response to initial INVITE.
+     * @param inviteResponse - 4xx, 5xx, or 6xx response.
+     */
+    private onReject;
+    /**
+     * Handle final response to initial INVITE.
+     * @param inviteResponse - 100 response.
+     */
+    private onTrying;
+}

package/dist/api/message.d.ts

@@ -0,0 +1,16 @@
+import { IncomingMessageRequest, IncomingRequestMessage, ResponseOptions } from "../core";
+/**
+ * A received message (incoming MESSAGE).
+ * @public
+ */
+export declare class Message {
+    private incomingMessageRequest;
+    /** @internal */
+    constructor(incomingMessageRequest: IncomingMessageRequest);
+    /** Incoming MESSAGE request message. */
+    get request(): IncomingRequestMessage;
+    /** Accept the request. */
+    accept(options?: ResponseOptions): Promise<void>;
+    /** Reject the request. */
+    reject(options?: ResponseOptions): Promise<void>;
+}

package/dist/api/messager-message-options.d.ts

@@ -0,0 +1,11 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+/**
+ * Options for {@link Messager.message}.
+ * @public
+ */
+export interface MessagerMessageOptions {
+    /** See `core` API. */
+    requestDelegate?: OutgoingRequestDelegate;
+    /** See `core` API. */
+    requestOptions?: RequestOptions;
+}

package/dist/api/messager-options.d.ts

@@ -0,0 +1,17 @@
+import { URI } from "../core";
+/**
+ * Options for {@link Messager} constructor.
+ * @public
+ */
+export interface MessagerOptions {
+    /** Array of extra headers added to the MESSAGE. */
+    extraHeaders?: Array<string>;
+    /** @deprecated TODO: provide alternative. */
+    params?: {
+        fromDisplayName?: string;
+        fromTag?: string;
+        fromUri?: string | URI;
+        toDisplayName?: string;
+        toUri?: string | URI;
+    };
+}

package/dist/api/messager.d.ts

@@ -0,0 +1,26 @@
+import { URI } from "../core";
+import { MessagerMessageOptions } from "./messager-message-options";
+import { MessagerOptions } from "./messager-options";
+import { UserAgent } from "./user-agent";
+/**
+ * A messager sends a {@link Message} (outgoing MESSAGE).
+ * @public
+ */
+export declare class Messager {
+    private logger;
+    private request;
+    private userAgent;
+    /**
+     * Constructs a new instance of the `Messager` class.
+     * @param userAgent - User agent. See {@link UserAgent} for details.
+     * @param targetURI - Request URI identifying the target of the message.
+     * @param content - Content for the body of the message.
+     * @param contentType - Content type of the body of the message.
+     * @param options - Options bucket. See {@link MessagerOptions} for details.
+     */
+    constructor(userAgent: UserAgent, targetURI: URI, content: string, contentType?: string, options?: MessagerOptions);
+    /**
+     * Send the message.
+     */
+    message(options?: MessagerMessageOptions): Promise<void>;
+}

package/dist/api/notification.d.ts

@@ -0,0 +1,16 @@
+import { IncomingNotifyRequest, IncomingRequestMessage, ResponseOptions } from "../core";
+/**
+ * A notification of an event (incoming NOTIFY).
+ * @public
+ */
+export declare class Notification {
+    private incomingNotifyRequest;
+    /** @internal */
+    constructor(incomingNotifyRequest: IncomingNotifyRequest);
+    /** Incoming NOTIFY request message. */
+    get request(): IncomingRequestMessage;
+    /** Accept the request. */
+    accept(options?: ResponseOptions): Promise<void>;
+    /** Reject the request. */
+    reject(options?: ResponseOptions): Promise<void>;
+}

package/dist/api/notifier.d.ts

@@ -0,0 +1,8 @@
+/**
+ * TODO: This is currently just a placeholder.
+ * Notifier is the peer of a Subscriber.
+ * That is, a Notifier sends NOTIFY requests.
+ * @internal
+ */
+export declare class Notifier {
+}

package/dist/api/publisher-options.d.ts

@@ -0,0 +1,33 @@
+import { URI } from "../core";
+/**
+ * Options for {@link Publisher} constructor.
+ * @public
+ */
+export interface PublisherOptions {
+    /** @deprecated TODO: provide alternative. */
+    body?: string;
+    /** @deprecated TODO: provide alternative. */
+    contentType?: string;
+    /**
+     * Expire value for the published event.
+     * @defaultValue 3600
+     */
+    expires?: number;
+    /**
+     * Array of extra headers added to the PUBLISH request message.
+     */
+    extraHeaders?: Array<string>;
+    /** @deprecated TODO: provide alternative. */
+    params?: {
+        fromDisplayName?: string;
+        fromTag?: string;
+        fromUri?: URI;
+        toDisplayName?: string;
+        toUri?: URI;
+    };
+    /**
+     * If set true, UA will gracefully unpublish for the event on UA close.
+     * @defaultValue true
+     */
+    unpublishOnClose?: boolean;
+}

package/dist/api/publisher-publish-options.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Options for {@link Publisher.publish}.
+ * @public
+ */
+export interface PublisherPublishOptions {
+}

package/dist/api/publisher-state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * {@link Publisher} state.
+ * @remarks
+ * The {@link Publisher} behaves in a deterministic manner according to the following
+ * Finite State Machine (FSM).
+ * ```txt
+ *                  __________________________________________
+ *                 |  __________________________              |
+ * Publisher       | |                          v             v
+ * Constructed -> Initial -> Published -> Unpublished -> Terminated
+ *                              |   ^____________|             ^
+ *                              |______________________________|
+ * ```
+ * @public
+ */
+export declare enum PublisherState {
+    Initial = "Initial",
+    Published = "Published",
+    Unpublished = "Unpublished",
+    Terminated = "Terminated"
+}

package/dist/api/publisher-unpublish-options.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Options for {@link Publisher.unpublish}.
+ * @public
+ */
+export interface PublisherUnpublishOptions {
+}

package/dist/api/publisher.d.ts

@@ -0,0 +1,65 @@
+import { IncomingResponseMessage, OutgoingPublishRequest, URI } from "../core";
+import { Emitter } from "./emitter";
+import { PublisherOptions } from "./publisher-options";
+import { PublisherPublishOptions } from "./publisher-publish-options";
+import { PublisherState } from "./publisher-state";
+import { PublisherUnpublishOptions } from "./publisher-unpublish-options";
+import { UserAgent } from "./user-agent";
+/**
+ * A publisher publishes a publication (outgoing PUBLISH).
+ * @public
+ */
+export declare class Publisher {
+    private event;
+    private options;
+    private target;
+    private pubRequestBody;
+    private pubRequestExpires;
+    private pubRequestEtag;
+    private publishRefreshTimer;
+    private disposed;
+    private id;
+    private logger;
+    private request;
+    private userAgent;
+    /** The publication state. */
+    private _state;
+    /** Emits when the registration state changes. */
+    private _stateEventEmitter;
+    /**
+     * Constructs a new instance of the `Publisher` class.
+     *
+     * @param userAgent - User agent. See {@link UserAgent} for details.
+     * @param targetURI - Request URI identifying the target of the message.
+     * @param eventType - The event type identifying the published document.
+     * @param options - Options bucket. See {@link PublisherOptions} for details.
+     */
+    constructor(userAgent: UserAgent, targetURI: URI, eventType: string, options?: PublisherOptions);
+    /**
+     * Destructor.
+     */
+    dispose(): Promise<void>;
+    /** The publication state. */
+    get state(): PublisherState;
+    /** Emits when the publisher state changes. */
+    get stateChange(): Emitter<PublisherState>;
+    /**
+     * Publish.
+     * @param content - Body to publish
+     */
+    publish(content: string, options?: PublisherPublishOptions): Promise<void>;
+    /**
+     * Unpublish.
+     */
+    unpublish(options?: PublisherUnpublishOptions): Promise<void>;
+    /** @internal */
+    protected receiveResponse(response: IncomingResponseMessage): void;
+    /** @internal */
+    protected send(): OutgoingPublishRequest;
+    private refreshRequest;
+    private sendPublishRequest;
+    /**
+     * Transition publication state.
+     */
+    private stateTransition;
+}

package/dist/api/referral.d.ts

@@ -0,0 +1,38 @@
+import { IncomingReferRequest, IncomingRequestMessage, NameAddrHeader, ResponseOptions } from "../core";
+import { Inviter } from "./inviter";
+import { InviterOptions } from "./inviter-options";
+import { Session } from "./session";
+/**
+ * A request to establish a {@link Session} elsewhere (incoming REFER).
+ * @public
+ */
+export declare class Referral {
+    private incomingReferRequest;
+    private session;
+    private inviter;
+    /** @internal */
+    constructor(incomingReferRequest: IncomingReferRequest, session: Session);
+    get referTo(): NameAddrHeader;
+    get referredBy(): string | undefined;
+    get replaces(): string | undefined;
+    /** Incoming REFER request message. */
+    get request(): IncomingRequestMessage;
+    /** Accept the request. */
+    accept(options?: ResponseOptions): Promise<void>;
+    /** Reject the request. */
+    reject(options?: ResponseOptions): Promise<void>;
+    /**
+     * Creates an inviter which may be used to send an out of dialog INVITE request.
+     *
+     * @remarks
+     * This a helper method to create an Inviter which will execute the referral
+     * of the `Session` which was referred. The appropriate headers are set and
+     * the referred `Session` is linked to the new `Session`. Note that only a
+     * single instance of the `Inviter` will be created and returned (if called
+     * more than once a reference to the same `Inviter` will be returned every time).
+     *
+     * @param options - Options bucket.
+     * @param modifiers - Session description handler modifiers.
+     */
+    makeInviter(options?: InviterOptions): Inviter;
+}

package/dist/api/registerer-options.d.ts

@@ -0,0 +1,46 @@
+import { URI } from "../core";
+/**
+ * Options for {@link Registerer} constructor.
+ * @public
+ */
+export interface RegistererOptions {
+    /** Registration expiration time in seconds. */
+    expires?: number;
+    /** Array of extra Contact header parameters. */
+    extraContactHeaderParams?: Array<string>;
+    /** Array of extra headers added to the REGISTER. */
+    extraHeaders?: Array<string>;
+    /**
+     * UUID to provide with "+sip.instance" Contact parameter.
+     * @defaultValue a randomly generated uuid
+     */
+    instanceId?: string;
+    /**
+     * If true, constructor logs the registerer configuration.
+     * @defaultValue `true`
+     */
+    logConfiguration?: boolean;
+    /** @deprecated TODO: provide alternative. */
+    params?: {
+        fromDisplayName?: string;
+        fromTag?: string;
+        fromUri?: URI;
+        toDisplayName?: string;
+        toUri?: URI;
+    };
+    /**
+     * Value to provide with "reg-id" Contact parameter.
+     * @defaultValue 1
+     */
+    regId?: number;
+    /**
+     * The URI of the registrar to send the REGISTER requests.
+     * @defaultValue domain portion of the user agent's uri
+     */
+    registrar?: URI;
+    /**
+     * Determines when a re-REGISTER request is sent. The value should be specified as a percentage of the expiration time (between 50 and 99).
+     * @defaultValue 99
+     */
+    refreshFrequency?: number;
+}

package/dist/api/registerer-register-options.d.ts

@@ -0,0 +1,11 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+/**
+ * Options for {@link Registerer.register}.
+ * @public
+ */
+export interface RegistererRegisterOptions {
+    /** See `core` API. */
+    requestDelegate?: OutgoingRequestDelegate;
+    /** See `core` API. */
+    requestOptions?: RequestOptions;
+}

package/dist/api/registerer-state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * {@link Registerer} state.
+ * @remarks
+ * The {@link Registerer} behaves in a deterministic manner according to the following
+ * Finite State Machine (FSM).
+ * ```txt
+ *                   __________________________________________
+ *                  |  __________________________              |
+ * Registerer       | |                          v             v
+ * Constructed -> Initial -> Registered -> Unregistered -> Terminated
+ *                              |   ^____________|             ^
+ *                              |______________________________|
+ * ```
+ * @public
+ */
+export declare enum RegistererState {
+    Initial = "Initial",
+    Registered = "Registered",
+    Unregistered = "Unregistered",
+    Terminated = "Terminated"
+}

package/dist/api/registerer-unregister-options.d.ts

@@ -0,0 +1,16 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+/**
+ * Options for {@link Registerer.unregister}.
+ * @public
+ */
+export interface RegistererUnregisterOptions {
+    /**
+     * If true, unregister all contacts.
+     * @defaultValue false
+     */
+    all?: boolean;
+    /** See `core` API. */
+    requestDelegate?: OutgoingRequestDelegate;
+    /** See `core` API. */
+    requestOptions?: RequestOptions;
+}