@twilio/conversations 2.0.0-rc.1 → 2.0.1-canary.1

package/dist/lib.d.ts

@@ -1,10 +1,11 @@
-import { EventEmitter } from "events";
 import { SyncClient } from "twilio-sync";
 import { Transport, TwilsockClient, InitRegistration } from "twilsock";
 import { ConnectionState as TwilsockConnectionState } from "twilsock";
+import { ReplayEventEmitter } from "@twilio/replay-event-emitter";
 import { ChannelType, Notifications } from "@twilio/notifications";
 import { Notifications as NotificationClient } from "@twilio/notifications";
 import { McsClient, MediaCategory, McsMedia } from "@twilio/mcs-client";
+import { MediaCategory as McsMediaCategory } from "@twilio/mcs-client";
 interface ConfigurationResponse {
     options: {
         consumption_report_interval: string;
@@ -104,42 +105,53 @@ declare class CommandExecutor {
     fetchResource<REQ = void, RESP = void>(url: string, requestBody?: REQ): Promise<RESP>;
     mutateResource<REQ = void, RESP = void>(method: "post" | "delete", url: string, requestBody?: REQ): Promise<RESP>;
 }
+type UserEvents = {
+    updated: (data: {
+        user: User;
+        updateReasons: UserUpdateReason[];
+    }) => void;
+    userSubscribed: (user: User) => void;
+    userUnsubscribed: (user: User) => void;
+};
 interface UserServices {
     syncClient: SyncClient;
     commandExecutor: CommandExecutor;
 }
-interface UserLinks {
-    self: string;
-}
 /**
  * The reason for the `updated` event being emitted by a user.
  */
 type UserUpdateReason = "friendlyName" | "attributes" | "reachabilityOnline" | "reachabilityNotifiable";
+interface UserUpdatedEventArgs {
+    user: User;
+    updateReasons: UserUpdateReason[];
+}
 /**
  * Extended user information.
  * Note that `isOnline` and `isNotifiable` properties are eligible
  * for use only if the reachability function is enabled.
  * You may check if it is enabled by reading the value of {@link Client.reachabilityEnabled}.
  */
-declare class User extends EventEmitter {
-    private readonly links;
-    private readonly configuration;
+declare class User extends ReplayEventEmitter<UserEvents> {
+    private links;
+    private configuration;
     private readonly services;
     private entity;
     private state;
     private promiseToFetch;
     private subscribed;
+    private _initializationPromise;
+    private _resolveInitializationPromise;
     /**
      * @internal
      */
-    constructor(identity: string, entityName: string, links: UserLinks, configuration: Configuration, services: UserServices);
+    constructor(identity: string, entityName: string, configuration: Configuration | null, services: UserServices);
     /**
      * Fired when the properties or the reachability status of the message has been updated.
      *
      * Parameters:
      * 1. object `data` - info object provided with the event. It has the following properties:
-     *     * {@link User} user - the user in question
-     *     * {@link UserUpdateReason}[] updateReasons - array of reasons for the update
+     *     * {@link User} `user` - the user in question
+     *     * {@link UserUpdateReason}[] `updateReasons` - array of reasons for the update
      * @event
      */
     readonly updated = "updated";
@@ -186,7 +198,7 @@ declare class User extends EventEmitter {
      */
     get isSubscribed(): boolean;
     // Handles service updates
-    _update(key: string, value: any): void;
+    _update(key: string, value: any): Promise<void>;
     // Fetch reachability info
     private _updateReachabilityInfo;
     // Fetch user
@@ -207,6 +219,7 @@ declare class User extends EventEmitter {
      * @return A promise of completion.
      */
     unsubscribe(): Promise<void>;
+    _resolveInitialization(configuration: Configuration, identity: string, entityName: string, emitUpdated: boolean): void;
 }
 declare class Network {
     private readonly configuration;
@@ -221,22 +234,29 @@ declare class Network {
     private executeWithRetry;
     get(url: string): Promise<any>;
 }
+type UsersEvents = {
+    userUpdated: (data: {
+        user: User;
+        updateReasons: UserUpdateReason[];
+    }) => void;
+    userSubscribed: (user: User) => void;
+    userUnsubscribed: (user: User) => void;
+};
 interface UsersServices {
     network: Network;
     syncClient: SyncClient;
     commandExecutor: CommandExecutor;
 }
 /**
- * @classdesc Container for known users
- * @fires Users#userUpdated
+ * Container for known users
  */
-declare class Users extends EventEmitter {
+declare class Users extends ReplayEventEmitter<UsersEvents> {
     private readonly configuration;
     private readonly services;
     private subscribedUsers;
     private fifoStack;
     readonly myself: User;
-    constructor(configuration: Configuration, services: UsersServices);
+    constructor(myself: User, configuration: Configuration, services: UsersServices);
     private handleUnsubscribeUser;
     private handleSubscribeUser;
     /**
@@ -254,6 +274,14 @@ declare class Users extends EventEmitter {
      */
     private getSyncUniqueName;
 }
+type ParticipantEvents = {
+    typingEnded: (participant: Participant) => void;
+    typingStarted: (participant: Participant) => void;
+    updated: (data: {
+        participant: Participant;
+        updateReasons: ParticipantUpdateReason[];
+    }) => void;
+};
 interface ParticipantDescriptor {
     attributes?: Object;
     dateCreated: any;
@@ -277,13 +305,17 @@ interface ParticipantLinks {
  */
 type ParticipantUpdateReason = "attributes" | "dateCreated" | "dateUpdated" | "roleSid" | "lastReadMessageIndex" | "lastReadTimestamp";
 /**
- * Push notification type of a participant.
+ * Type of a participant.
  */
 type ParticipantType = "chat" | "sms" | "whatsapp";
+interface ParticipantUpdatedEventArgs {
+    participant: Participant;
+    updateReasons: ParticipantUpdateReason[];
+}
 /**
  * A participant represents a remote client in a conversation.
  */
-declare class Participant extends EventEmitter {
+declare class Participant extends ReplayEventEmitter<ParticipantEvents> {
     private state;
     private readonly links;
     private readonly services;
@@ -390,9 +422,16 @@ declare class Participant extends EventEmitter {
      */
     updateAttributes(attributes: any): Promise<Participant>;
 }
+/**
+ * Category of media. Possible values are as follows:
+ * * `'media'`
+ * * `'body'`
+ * * `'history'`
+ */
+type MediaCategory$0 = McsMediaCategory;
 interface MediaState {
     sid: string;
-    category: MediaCategory;
+    category: MediaCategory$0;
     filename?: string;
     contentType: string;
     size: number;
@@ -428,9 +467,9 @@ declare class Media {
      */
     get size(): number;
     /**
-     * Media category, can be one of the {MediaCategory} values.
+     * Media category, can be one of the {@link MediaCategory} values.
      */
-    get category(): MediaCategory;
+    get category(): MediaCategory$0;
     /**
      * Returns the direct content URL for the media.
      *
@@ -593,6 +632,12 @@ declare class DetailedDeliveryReceipt {
      */
     constructor(descriptor: DetailedDeliveryReceiptDescriptor);
 }
+type MessageEvents = {
+    updated: (data: {
+        message: Message;
+        updateReasons: MessageUpdateReason[];
+    }) => void;
+};
 interface MessageServices {
     mcsClient: McsClient;
     network: Network;
@@ -608,13 +653,17 @@ interface MessageLinks {
  */
 type MessageUpdateReason = "body" | "lastUpdatedBy" | "dateCreated" | "dateUpdated" | "attributes" | "author" | "deliveryReceipt" | "subject";
 /**
- * Push notification type of a message.
+ * Type of a message.
  */
 type MessageType = "text" | "media";
+interface MessageUpdatedEventArgs {
+    message: Message;
+    updateReasons: MessageUpdateReason[];
+}
 /**
  * A message in a conversation.
  */
-declare class Message extends EventEmitter {
+declare class Message extends ReplayEventEmitter<MessageEvents> {
     /**
      * Conversation that the message is in.
      */
@@ -739,29 +788,30 @@ declare class Message extends EventEmitter {
     private _getDetailedDeliveryReceiptsPaginator;
 }
 /**
- * Pagination helper class.
- *
- * @interface
- * @property {Array} items Elements on current page
- * @property {boolean} hasNextPage Indicates the existence of next page
- * @property {boolean} hasPrevPage Indicates the existence of previous page
- * @function {Promise<Paginator>} nextPage() Request next page. Does not modify existing object
- * @function {Promise<Paginator>} prevPage() Request previous page. Does not modify existing object
+ * Pagination helper interface.
+ * @typeParam T The item type.
  */
 interface Paginator<T> {
+    /**
+     * Indicates the existence of the next page.
+     */
     hasNextPage: boolean;
+    /**
+     * Indicates the existence of the previous page.
+     */
     hasPrevPage: boolean;
-    items: Array<T>;
+    /**
+     * Array of elements of type T on the current page.
+     */
+    items: T[];
     /**
      * Request next page.
-     * Does not modify existing object.
-     * @return {Promise<Paginator<T>>}
+     * Does not modify the existing object.
      */
     nextPage(): Promise<Paginator<T>>;
     /**
      * Request previous page.
-     * Does not modify existing object.
-     * @return {Promise<Paginator<T>>}
+     * Does not modify the existing object.
      */
     prevPage(): Promise<Paginator<T>>;
 }
@@ -810,30 +860,94 @@ declare class TypingIndicator {
     send(conversationSid: string): Promise<void>;
     private _send;
 }
+/**
+ * An unsent message. Returned from {@link MessageBuilder.build}.
+ */
 declare class UnsentMessage {
     private messagesEntity;
     text?: string;
     attributes: any;
     mediaContent: [MediaCategory, FormData | SendMediaOptions][];
     emailOptions?: SendEmailOptions;
+    /**
+     * @internal
+     */
     constructor(messagesEntity: any);
     /**
      * Send the prepared message to the conversation.
-     * @returns {Promise<number>} new Message's index in the Conversation's messages list
+     * @returns Index of the new message in the conversation.
      */
     send(): Promise<number>;
 }
+/**
+ * Message builder. Allows the message to be built and sent via method chaining.
+ *
+ * Example:
+ *
+ * ```ts
+ * await testConversation.prepareMessage()
+ *   .setBody('Hello!')
+ *   .setAttributes({foo: 'bar'})
+ *   .addMedia(media1)
+ *   .addMedia(media2)
+ *   .build()
+ *   .send();
+ * ```
+ */
 declare class MessageBuilder {
     private readonly limits;
     private readonly message;
+    /**
+     * @internal
+     */
     constructor(limits: Limits, messagesEntity: any);
+    /**
+     * Sets the message body.
+     * @param text Contents of the body.
+     */
     setBody(text: string): MessageBuilder;
+    /**
+     * Sets the message subject.
+     * @param subject Contents of the subject.
+     */
     setSubject(subject: string): MessageBuilder;
+    /**
+     * Sets the message attributes.
+     * @param attributes Message attributes.
+     */
     setAttributes(attributes: any): MessageBuilder;
+    /**
+     * Adds media to the message.
+     * @param payload Media to add.
+     */
     addMedia(payload: FormData | SendMediaOptions): MessageBuilder;
+    /**
+     * Builds the message, making it ready to be sent.
+     */
     build(): UnsentMessage;
     private getPayloadContentType;
 }
+type ConversationEvents = {
+    participantJoined: (participant: Participant) => void;
+    participantLeft: (participant: Participant) => void;
+    participantUpdated: (data: {
+        participant: Participant;
+        updateReasons: ParticipantUpdateReason[];
+    }) => void;
+    messageAdded: (message: Message) => void;
+    messageRemoved: (message: Message) => void;
+    messageUpdated: (data: {
+        message: Message;
+        updateReasons: MessageUpdateReason[];
+    }) => void;
+    typingEnded: (participant: Participant) => void;
+    typingStarted: (participant: Participant) => void;
+    updated: (data: {
+        conversation: Conversation;
+        updateReasons: ConversationUpdateReason[];
+    }) => void;
+    removed: (conversation: Conversation) => void;
+};
 interface ConversationServices {
     users: Users;
     typingIndicator: TypingIndicator;
@@ -895,7 +1009,8 @@ interface ConversationUpdatedEventArgs {
 }
 /**
  * Configuration for attaching a media file to a message.
- * These options can be passed to {@link Conversation.sendMessage}.
+ * These options can be passed to {@link Conversation.sendMessage} and
+ * {@link MessageBuilder.addMedia}.
  */
 interface SendMediaOptions {
     /**
@@ -936,7 +1051,7 @@ interface LastMessage {
 /**
  * A conversation represents communication between multiple Conversations clients
  */
-declare class Conversation extends EventEmitter {
+declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
     /**
      * Unique system identifier of the conversation.
      */
@@ -1141,7 +1256,7 @@ declare class Conversation extends EventEmitter {
      * @param address User address of the participant.
      * @param attributes Attributes to be attached to the participant.
      */
-    addNonChatParticipant(proxyAddress: string, address: string, attributes?: Record<string, any>): Promise<void>;
+    addNonChatParticipant(proxyAddress: string, address: string, attributes?: any): Promise<void>;
     /**
      * Advance the conversation's last read message index to the current read horizon.
      * Rejects if the user is not a participant of the conversation.
@@ -1228,14 +1343,15 @@ declare class Conversation extends EventEmitter {
      */
     leave(): Promise<Conversation>;
     /**
-     * Remove a participant from the conversation. When a string is passed as the argument, it will assume that the string is an identity.
-     * @param participant Identity or the participant object to remove.
+     * Remove a participant from the conversation. When a string is passed as the
+     * argument, it will assume that the string is an identity or SID.
+     * @param participant Identity, SID or the participant object to remove.
      */
     removeParticipant(participant: string | Participant): Promise<void>;
     /**
      * Send a message to the conversation.
      * @param message Message body for the text message,
-     * `FormData` or {@link Conversation.MediaOptions) for media content. Sending FormData is supported only with the browser engine.
+     * `FormData` or {@link SendMediaOptions} for media content. Sending FormData is supported only with the browser engine.
      * @param messageAttributes Attributes for the message.
      * @param emailOptions Email options for the message.
      * @return Index of the new message.
@@ -1244,7 +1360,6 @@ declare class Conversation extends EventEmitter {
     /**
      * New interface to prepare for sending a message.
      * Use instead of `sendMessage`.
-     * @return {MessageBuilder} [description]
      */
     prepareMessage(): MessageBuilder;
     /**
@@ -1276,7 +1391,7 @@ declare class Conversation extends EventEmitter {
      * Update the friendly name of the conversation.
      * @param friendlyName New friendly name.
      */
-    updateFriendlyName(friendlyName: string | null): Promise<Conversation>;
+    updateFriendlyName(friendlyName: string): Promise<Conversation>;
     /**
      * Set the last read message index to the current read horizon.
      * @param index Message index to set as last read.
@@ -1317,7 +1432,7 @@ interface PushNotificationData {
      */
     messageIndex?: number;
     /**
-     * SID of the message in the conversation.s
+     * SID of the message in the conversation.
      */
     messageSid?: string;
 }
@@ -1342,7 +1457,7 @@ declare class PushNotification {
      */
     readonly badge: number;
     /**
-     * Notification action (`click_action` in FCM/GCM terms and `category` in APN terms).
+     * Notification action (`click_action` in FCM terms and `category` in APN terms).
      */
     readonly action: string;
     /**
@@ -1358,6 +1473,47 @@ declare class PushNotification {
      */
     constructor(data: PushNotificationDescriptor);
 }
+type ClientEvents = {
+    conversationAdded: (conversation: Conversation) => void;
+    conversationJoined: (conversation: Conversation) => void;
+    conversationLeft: (conversation: Conversation) => void;
+    conversationRemoved: (conversation: Conversation) => void;
+    conversationUpdated: (data: {
+        conversation: Conversation;
+        updateReasons: ConversationUpdateReason[];
+    }) => void;
+    participantJoined: (participant: Participant) => void;
+    participantLeft: (participant: Participant) => void;
+    participantUpdated: (data: {
+        participant: Participant;
+        updateReasons: ParticipantUpdateReason[];
+    }) => void;
+    messageAdded: (message: Message) => void;
+    messageRemoved: (message: Message) => void;
+    messageUpdated: (data: {
+        message: Message;
+        updateReasons: MessageUpdateReason[];
+    }) => void;
+    tokenAboutToExpire: (ttl: number) => void;
+    tokenExpired: () => void;
+    typingEnded: (participant: Participant) => void;
+    typingStarted: (participant: Participant) => void;
+    pushNotification: (pushNotification: PushNotification) => void;
+    userSubscribed: (user: User) => void;
+    userUnsubscribed: (user: User) => void;
+    userUpdated: (data: {
+        user: User;
+        updateReasons: UserUpdateReason[];
+    }) => void;
+    stateChanged: (state: State) => void;
+    connectionStateChanged: (state: TwilsockConnectionState) => void;
+    connectionError: (data: {
+        terminal: boolean;
+        message: string;
+        httpStatusCode?: number;
+        errorCode?: number;
+    }) => void;
+};
 /**
  * Connection state of the client. Possible values are as follows:
  * * `'connecting'` - client is offline and connection attempt is in process
@@ -1367,6 +1523,12 @@ declare class PushNotification {
  * * `'denied'` - client connection is denied because of invalid JWT access token. User must refresh token in order to proceed
  */
 type ConnectionState = TwilsockConnectionState;
+/**
+ * State of the client. Possible values are as follows:
+ * * `'failed'` - the client failed to initialize
+ * * `'initialized'` - the client successfully initialized
+ */
+type State = "failed" | "initialized";
 /**
  * Notifications channel type. Possible values are as follows:
  * * `'fcm'`
@@ -1423,7 +1585,7 @@ interface CreateConversationOptions {
 /**
  * A client is the starting point to the Twilio Conversations functionality.
  */
-declare class Client extends EventEmitter {
+declare class Client extends ReplayEventEmitter<ClientEvents> {
     /**
      * Client connection state.
      */
@@ -1437,6 +1599,7 @@ declare class Client extends EventEmitter {
     private conversations;
     private readonly options;
     private services;
+    private readonly _myself;
     /**
      * Current version of the Conversations client.
      */
@@ -1493,7 +1656,7 @@ declare class Client extends EventEmitter {
     static readonly conversationRemoved = "conversationRemoved";
     /**
      * Fired when the attributes or the metadata of a conversation have been updated.
-     * During conversation's {@link Client.create| creation and initialization}, this event might be fired multiple times
+     * During conversation's creation and initialization, this event might be fired multiple times
      * for same joined or created conversation as new data is arriving from different sources.
      *
      * Parameters:
@@ -1503,14 +1666,6 @@ declare class Client extends EventEmitter {
      * @event
      */
     static readonly conversationUpdated = "conversationUpdated";
-    /**
-     * Fired when the connection state of the client has been changed.
-     *
-     * Parameters:
-     * 1. {@link Conversation} `conversation` - the conversation in question
-     * @event
-     */
-    static readonly conversationStateChanged = "connectionStateChanged";
     /**
      * Fired when a participant has joined a conversation.
      *
@@ -1565,6 +1720,8 @@ declare class Client extends EventEmitter {
     static readonly messageUpdated = "messageUpdated";
     /**
      * Fired when the token is about to expire and needs to be updated.
+     * * Parameters:
+     * 1. number `message` - token's time to live
      * @event
      */
     static readonly tokenAboutToExpire = "tokenAboutToExpire";
@@ -1623,6 +1780,22 @@ declare class Client extends EventEmitter {
      * @event
      */
     static readonly userUpdated = "userUpdated";
+    /**
+     * Fired when the state of the client has been changed.
+     *
+     * Parameters:
+     * 1. {@link State} `state` - the new client state
+     * @event
+     */
+    static readonly stateChanged = "stateChanged";
+    /**
+     * Fired when the connection state of the client has been changed.
+     *
+     * Paremeters:
+     * 1. {@link ConnectionState} `state` - the new connection state
+     * @event
+     */
+    static readonly connectionStateChanged = "connectionStateChanged";
     /**
      * Fired when the connection is interrupted for an unexpected reason.
      *
@@ -1643,17 +1816,27 @@ declare class Client extends EventEmitter {
      * The factory method will automatically trigger connection.
      * Do not use it if you need finer-grained control.
      *
+     * Since this method returns an already-initialized client, some of the events
+     * will be lost because they happen *before* the initialization. It is
+     * recommended that `client.onWithReplay` is used as opposed to `client.on`
+     * for subscribing to client events. The `client.onWithReplay` will re-emit
+     * the most recent value for a given event if it emitted before the
+     * subscription.
+     *
      * @param token Access token.
      * @param options Options to customize the client.
      * @returns Returns a fully initialized client.
      */
     static create(token: string, options?: ClientOptions): Promise<Client>;
     /**
-     * Information of the logged-in user.
+     * Information of the logged-in user. Before client initialization, returns an
+     * uninitialized user. Will trigger a {@link Client.userUpdated} event after
+     * initialization.
      */
     get user(): User;
     /**
-     * Client reachability state.
+     * Client reachability state. Throws if accessed before the client
+     * initialization was completed.
      */
     get reachabilityEnabled(): boolean;
     get token(): string;
@@ -1766,4 +1949,12 @@ declare class RestPaginator<T> implements Paginator<T> {
      */
     prevPage(): Promise<RestPaginator<T>>;
 }
-export { Client as default, Client, Conversation, ConversationUpdateReason, ConversationStatus, NotificationLevel, ConversationState, ConversationUpdatedEventArgs, SendMediaOptions, SendEmailOptions, LastMessage, Participant, ParticipantUpdateReason, ParticipantType, Message, MessageUpdateReason, MessageType, Media, AggregatedDeliveryReceipt, DeliveryAmount, DetailedDeliveryReceipt, DeliveryStatus, RestPaginator, User, UserUpdateReason, PushNotification, PushNotificationType, PushNotificationDescriptor, ConnectionState, NotificationsChannelType, ClientOptions, CreateConversationOptions };
+declare class NotificationTypes {
+    static readonly TYPING_INDICATOR = "twilio.ipmsg.typing_indicator";
+    static readonly NEW_MESSAGE = "twilio.conversations.new_message";
+    static readonly ADDED_TO_CONVERSATION = "twilio.conversations.added_to_conversation";
+    // static readonly INVITED_TO_CHANNEL = 'twilio.channel.invited_to_channel';
+    static readonly REMOVED_FROM_CONVERSATION = "twilio.conversations.removed_from_conversation";
+    static readonly CONSUMPTION_UPDATE = "twilio.channel.consumption_update";
+}
+export { Conversation, ConversationUpdateReason, ConversationStatus, NotificationLevel, ConversationState, ConversationUpdatedEventArgs, SendMediaOptions, SendEmailOptions, LastMessage, Participant, ParticipantUpdateReason, ParticipantType, ParticipantUpdatedEventArgs, Message, MessageUpdateReason, MessageType, MessageUpdatedEventArgs, Media, MediaCategory$0 as MediaCategory, AggregatedDeliveryReceipt, DeliveryAmount, DetailedDeliveryReceipt, DeliveryStatus, RestPaginator, MessageBuilder, UnsentMessage, Paginator, User, UserUpdateReason, UserUpdatedEventArgs, PushNotification, PushNotificationType, PushNotificationDescriptor, PushNotificationData, NotificationTypes, Client, State, ConnectionState, NotificationsChannelType, ClientOptions, CreateConversationOptions };