@twilio/conversations 2.1.0 → 3.0.0-rc.1

package/builds/lib.d.ts

@@ -5,7 +5,7 @@ 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 { CancellablePromise, McsClient, MediaCategory, McsMedia } from "@twilio/mcs-client";
 import { MediaCategory as McsMediaCategory } from "@twilio/mcs-client";
 interface ConfigurationResponse {
     options: {
@@ -72,13 +72,13 @@ interface ConversationLimits {
      */
     mediaAttachmentsTotalSizeLimitInMb: number;
     /**
-     * Allowed mime types for E-Mail histories.
+     * Allowed content types for E-Mail histories.
      */
-    emailHistoriesAllowedMimeTypes: string[];
+    emailHistoriesAllowedContentTypes: string[];
     /**
-     * Allowed mime types for E-Mail bodies.
+     * Allowed content types for E-Mail bodies.
      */
-    emailBodiesAllowedMimeTypes: string[];
+    emailBodiesAllowedContentTypes: string[];
 }
 interface BackoffConfiguration {
     min: number;
@@ -568,17 +568,7 @@ declare class Media {
      * If the URL becomes expired, you need to request a new one.
      * Each call to this function produces a new temporary URL.
      */
-    getContentTemporaryUrl(): Promise<string | null>;
-    /**
-     * Returns cached direct content URL for the media.
-     *
-     * This URL will expire in several minutes. This function does not refresh the URL and can be used to query it several times
-     * without causing network traffic.
-     * If the URL becomes expired, you need to request a new one using getContentTemporaryUrl().
-     *
-     * @returns {Promise<String>}
-     */
-    getCachedTemporaryUrl(): Promise<string | null>;
+    getContentTemporaryUrl(): CancellablePromise<string | null>;
     private _fetchMcsMedia;
 }
 /**
@@ -862,16 +852,16 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      * @param categories Array of categories to match.
      * @returns Array of media descriptors matching given categories.
      */
-    getMediaByCategory(categories: Array<MediaCategory>): Array<Media> | null;
+    getMediaByCategories(categories: MediaCategory[]): Media[] | null;
     /**
      * Get a media descriptor for an email body attachment of a provided type.
-     * Allowed body types are returned in the Conversation.limits().emailBodiesAllowedMimeTypes array.
+     * Allowed body types are returned in the Conversation.limits().emailBodiesAllowedContentTypes array.
      * @param type Type of email body to request, defaults to `text/plain`.
      */
     getEmailBody(type?: string): Media | null;
     /**
      * Get a media descriptor for an email history attachment of a provided type.
-     * Allowed body types are returned in the Conversation.limits().emailHistoriesAllowedMimeTypes array.
+     * Allowed body types are returned in the Conversation.limits().emailHistoriesAllowedContentTypes array.
      * @param type Type of email history to request, defaults to `text/plain`.
      */
     getEmailHistory(type?: string): Media | null;
@@ -899,10 +889,19 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      */
     updateAttributes(attributes: JSONValue): Promise<Message>;
     /**
-     * Get content URLs for all media attachments in the given set using single operation.
-     * @param contentSet Set of media attachments to query for content URL.
+     * Get content URLs for all media attachments in the given set using a single operation.
+     * @param contentSet Set of media attachments to query content URLs.
+     */
+    getTemporaryContentUrlsForMedia(contentSet: Media[] | null): CancellablePromise<Map<string, string>>;
+    /**
+     * Get content URLs for all media attachments in the given set of media sids using a single operation.
+     * @param mediaSids Set of media sids to query for the content URL.
      */
-    attachTemporaryUrlsFor(contentSet: Media[] | null): Promise<Media[]>;
+    getTemporaryContentUrlsForMediaSids(mediaSids: string[]): CancellablePromise<Map<string, string>>;
+    /**
+     * Get content URLs for all media attached to the message.
+     */
+    getTemporaryContentUrlsForAttachedMedia(): CancellablePromise<Map<string, string>>;
     private _getDetailedDeliveryReceiptsPaginator;
 }
 /**
@@ -978,25 +977,6 @@ 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: JSONValue;
-    mediaContent: [MediaCategory, FormData | SendMediaOptions][];
-    emailOptions: SendEmailOptions;
-    /**
-     * @internal
-     */
-    constructor(messagesEntity: any);
-    /**
-     * Send the prepared message to the conversation.
-     * @returns Index of the new message in the conversation.
-     */
-    send(): Promise<number | null>;
-}
 /**
  * Pagination helper class.
  */
@@ -1103,11 +1083,10 @@ declare class Messages extends ReplayEventEmitter<MessagesEvents> {
     subscribe(name: string): Promise<SyncList>;
     unsubscribe(): Promise<void>;
     /**
-     * Send Message to the conversation, message could include both text and multiple media attachments.
+     * Send a message to the conversation. The message could include text and multiple media attachments.
      * @param message Message to post
-     * @returns Returns a promise which can fail
      */
-    sendV2(message: UnsentMessage): Promise<MessageResponse>;
+    sendV2(message: UnsentMessage): CancellablePromise<MessageResponse>;
     /**
      * Send Message to the conversation
      * @param message Message to post
@@ -1144,6 +1123,25 @@ declare class Messages extends ReplayEventEmitter<MessagesEvents> {
      */
     private _getMessages;
 }
+/**
+ * An unsent message. Returned from {@link MessageBuilder.build}.
+ */
+declare class UnsentMessage {
+    private messagesEntity;
+    text?: string;
+    attributes: JSONValue;
+    mediaContent: [MediaCategory, FormData | SendMediaOptions][];
+    emailOptions: SendEmailOptions;
+    /**
+     * @internal
+     */
+    constructor(messagesEntity: Messages);
+    /**
+     * Send the prepared message to the conversation.
+     * @returns Index of the new message in the conversation.
+     */
+    send(): CancellablePromise<number | null>;
+}
 /**
  * Message builder. Allows the message to be built and sent via method chaining.
  *
@@ -1184,17 +1182,17 @@ declare class MessageBuilder {
      */
     setAttributes(attributes: JSONValue): MessageBuilder;
     /**
-     * Set email body with given MIME-type.
-     * @param mimeType Format of the body to set (text/plain or text/html).
-     * @param body Body payload in selected format.
+     * Set the email body with a given content type.
+     * @param contentType Format of the body to set (text/plain or text/html).
+     * @param body Body payload in the selected format.
      */
-    setEmailBody(mimeType: string, body: FormData | SendMediaOptions): MessageBuilder;
+    setEmailBody(contentType: string, body: FormData | SendMediaOptions): MessageBuilder;
     /**
-     * Set email history with given MIME-type.
-     * @param mimeType Format of the history to set (text/plain or text/html).
-     * @param history History payload in selected format.
+     * Set the email history with a given content type.
+     * @param contentType Format of the history to set (text/plain or text/html).
+     * @param history History payload in the selected format.
      */
-    setEmailHistory(mimeType: string, history: FormData | SendMediaOptions): MessageBuilder;
+    setEmailHistory(contentType: string, history: FormData | SendMediaOptions): MessageBuilder;
     /**
      * Adds media to the message.
      * @param payload Media to add.
@@ -1204,6 +1202,10 @@ declare class MessageBuilder {
      * Builds the message, making it ready to be sent.
      */
     build(): UnsentMessage;
+    /**
+     * Prepares a message and sends it to the conversation.
+     */
+    buildAndSend(): CancellablePromise<number | null>;
     private getPayloadContentType;
 }
 type ConversationEvents = {
@@ -1778,6 +1780,9 @@ declare class PushNotification {
      */
     constructor(data: PushNotificationDescriptor);
 }
+/**
+ * Client events.
+ */
 type ClientEvents = {
     conversationAdded: (conversation: Conversation) => void;
     conversationJoined: (conversation: Conversation) => void;
@@ -1810,7 +1815,10 @@ type ClientEvents = {
         user: User;
         updateReasons: UserUpdateReason[];
     }) => void;
-    stateChanged: (state: State) => void;
+    stateChanged: ({ state, error }: {
+        state: State;
+        error?: Error;
+    }) => void;
     connectionStateChanged: (state: TwilsockConnectionState) => void;
     connectionError: (data: {
         terminal: boolean;
@@ -1824,8 +1832,10 @@ type ClientEvents = {
  * * `'connecting'` - client is offline and connection attempt is in process
  * * `'connected'` - client is online and ready
  * * `'disconnecting'` - client is going offline as disconnection is in process
- * * `'disconnected'` - client is offline and no connection attempt is in process
- * * `'denied'` - client connection is denied because of invalid JWT access token. User must refresh token in order to proceed
+ * * `'disconnected'` - client is offline and no connection attempt is in
+ * process
+ * * `'denied'` - client connection is denied because of invalid JWT access
+ * token. User must refresh token in order to proceed
  */
 type ConnectionState = TwilsockConnectionState;
 /**
@@ -1840,6 +1850,9 @@ type State = "failed" | "initialized";
  * * `'apn'`
  */
 type NotificationsChannelType = ChannelType;
+/**
+ * Level of logging.
+ */
 type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "silent";
 /**
  * Conversations client options.
@@ -1894,43 +1907,9 @@ interface CreateConversationOptions {
  */
 declare class Client extends ReplayEventEmitter<ClientEvents> {
     /**
-     * Client connection state.
-     */
-    connectionState: ConnectionState;
-    private conversationsPromise;
-    private _ensureReady;
-    private _resolveEnsureReady;
-    private _rejectEnsureReady;
-    private fpaToken;
-    private configuration;
-    private conversations;
-    private readonly options;
-    private services;
-    private readonly _myself;
-    /**
-     * Current version of the Conversations client.
-     */
-    static readonly version: string;
-    /**
-     * Current version of the Conversations client.
-     */
-    readonly version: string;
-    private static readonly supportedPushChannels;
-    private static readonly supportedPushDataFields;
-    /**
-     * Returned Conversations instance is not yet fully initialized. Calling any operations will block until it is.
-     * Use connection events to monitor when client becomes fully available (connectionStateChanged with state
-     * 'connected') or not available (connectionStateChange with state 'denied', event tokenExpired, event connectionError).
-     *
-     * @param fpaToken Access token
-     * @param options Options to customize the Client
-     * @returns A not yet fully-initialized client.
-     */
-    constructor(fpaToken: string, options?: ClientOptions | null);
-    static populateInitRegistrations(reg: InitRegistration): void;
-    /**
-     * Fired when a conversation becomes visible to the client. The event is also triggered when the client creates a new conversation.
-     * Fired for all conversations client has joined.
+     * Fired when a conversation becomes visible to the client. The event is also
+     * triggered when the client creates a new conversation.
+     * Fired for all conversations that the client has joined.
      *
      * Parameters:
      * 1. {@link Conversation} `conversation` - the conversation in question
@@ -1962,14 +1941,17 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      */
     static readonly conversationRemoved = "conversationRemoved";
     /**
-     * Fired when the attributes or the metadata of a conversation have been updated.
-     * 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.
+     * Fired when the attributes or the metadata of a conversation have been
+     * updated. 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:
-     * 1. object `data` - info object provided with the event. It has the following properties:
+     * 1. object `data` - info object provided with the event. It has the
+     * following properties:
      *     * {@link Conversation} `conversation` - the conversation in question
-     *     * {@link ConversationUpdateReason}[] `updateReasons` - array of reasons for the update
+     *     * {@link ConversationUpdateReason}[] `updateReasons` - array of reasons
+     *     for the update
      * @event
      */
     static readonly conversationUpdated = "conversationUpdated";
@@ -1993,9 +1975,11 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * Fired when a participant's fields have been updated.
      *
      * Parameters:
-     * 1. object `data` - info object provided with the event. It has the following properties:
+     * 1. object `data` - info object provided with the event. It has the
+     * following properties:
      *     * {@link Participant} `participant` - the participant in question
-     *     * {@link ParticipantUpdateReason}[] `updateReasons` - array of reasons for the update
+     *     * {@link ParticipantUpdateReason}[] `updateReasons` - array of reasons
+     *     for the update
      * @event
      */
     static readonly participantUpdated = "participantUpdated";
@@ -2019,9 +2003,11 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * Fired when the fields of an existing message are updated with new values.
      *
      * Parameters:
-     * 1. object `data` - info object provided with the event. It has the following properties:
+     * 1. object `data` - info object provided with the event. It has the
+     * following properties:
      *     * {@link Message} `message` - the message in question
-     *     * {@link MessageUpdateReason}[] `updateReasons` - array of reasons for the update
+     *     * {@link MessageUpdateReason}[] `updateReasons` - array of reasons for
+     *     the update
      * @event
      */
     static readonly messageUpdated = "messageUpdated";
@@ -2054,10 +2040,12 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      */
     static readonly typingStarted = "typingStarted";
     /**
-     * Fired when the client has received (and parsed) a push notification via one of the push channels (apn or fcm).
+     * Fired when the client has received (and parsed) a push notification via one
+     * of the push channels (apn or fcm).
      *
      * Parameters:
-     * 1. {@link PushNotification} `pushNotification` - the push notification in question
+     * 1. {@link PushNotification} `pushNotification` - the push notification in
+     * question
      * @event
      */
     static readonly pushNotification = "pushNotification";
@@ -2078,12 +2066,15 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      */
     static readonly userUnsubscribed = "userUnsubscribed";
     /**
-     * Fired when the properties or the reachability status of a user have been updated.
+     * Fired when the properties or the reachability status of a user have been
+     * updated.
      *
      * Parameters:
-     * 1. object `data` - info object provided with the event. It has the following properties:
+     * 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 UserUpdateReason}[] `updateReasons` - array of reasons for the
+     *     update
      * @event
      */
     static readonly userUpdated = "userUpdated";
@@ -2091,14 +2082,17 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * Fired when the state of the client has been changed.
      *
      * Parameters:
-     * 1. {@link State} `state` - the new client state
+     * 1. object `data` - info object provided with the event. It has the
+     * following properties:
+     *     * {@link State} `state` - the new client state
+     *     * Error? `error` - the initialization error if present
      * @event
      */
     static readonly stateChanged = "stateChanged";
     /**
      * Fired when the connection state of the client has been changed.
      *
-     * Paremeters:
+     * Parameters:
      * 1. {@link ConnectionState} `state` - the new connection state
      * @event
      */
@@ -2107,7 +2101,8 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * Fired when the connection is interrupted for an unexpected reason.
      *
      * Parameters:
-     * 1. object `data` - info object provided with the event. It has the following properties:
+     * 1. object `data` - info object provided with the event. It has the
+     * following properties:
      *     * boolean `terminal` - Twilsock will stop connection attempts if true
      *     * string `message` - the error message of the root cause
      *     * number? `httpStatusCode` - http status code if available
@@ -2115,6 +2110,93 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * @event
      */
     static readonly connectionError = "connectionError";
+    /**
+     * Current version of the Conversations client.
+     */
+    static readonly version: string;
+    /**
+     * Logger instance.
+     */
+    private static readonly _logger;
+    /**
+     * Supported push notification channels.
+     */
+    private static readonly _supportedPushChannels;
+    /**
+     * Supported push data fields.
+     */
+    private static readonly _supportedPushDataFields;
+    /**
+     * Current version of the Conversations client.
+     */
+    readonly version: string;
+    /**
+     * Client connection state.
+     */
+    connectionState: ConnectionState;
+    /**
+     * Promise that resolves on successful initialization.
+     */
+    private readonly _ensureReady;
+    /**
+     * Options passed to the client.
+     */
+    private readonly _options;
+    /**
+     * Client service objects.
+     */
+    private readonly _services;
+    /**
+     * The user of the client.
+     */
+    private readonly _myself;
+    /**
+     * Resolves the {@link Client._ensureReady} promise.
+     */
+    private _resolveEnsureReady;
+    /**
+     * Rejects the {@link Client._ensureReady} promise.
+     */
+    private _rejectEnsureReady;
+    /**
+     * The current token of the client.
+     */
+    private _fpaToken;
+    /**
+     * The constructed configuration object.
+     */
+    private _configuration;
+    /**
+     * The Conversations entity.
+     */
+    private _conversations;
+    /**
+     * Promise that resolves when initial conversations are fetched.
+     */
+    private _conversationsPromise;
+    /**
+     * Returned Conversations instance is not yet fully initialized. Calling any
+     * operations will block until it is. Use connection events to monitor when
+     * client becomes fully available (connectionStateChanged with state
+     * 'connected') or not available (connectionStateChange with state 'denied',
+     * event tokenExpired, event connectionError).
+     *
+     * @param fpaToken Access token
+     * @param options Options to customize the Client
+     * @returns A not yet fully-initialized client.
+     */
+    constructor(fpaToken: string, options?: ClientOptions | null);
+    /**
+     * 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. Throws an error if accessed before the client
+     * initialization was completed.
+     */
+    get reachabilityEnabled(): boolean;
     /**
      * @deprecated Call constructor directly.
      *
@@ -2136,20 +2218,21 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      */
     static create(token: string, options?: ClientOptions | null): Promise<Client>;
     /**
-     * Information of the logged-in user. Before client initialization, returns an
-     * uninitialized user. Will trigger a {@link Client.userUpdated} event after
-     * initialization.
+     * Static method for push notification payload parsing. Returns parsed push as
+     * a {@link PushNotification} object.
+     * @param notificationPayload Push notification payload.
      */
-    get user(): User;
+    static parsePushNotification(notificationPayload: any): PushNotification;
     /**
-     * Client reachability state. Throws if accessed before the client
-     * initialization was completed.
+     * Static method for parsing push notification chat data.
+     * @param data Data to parse
      */
-    get reachabilityEnabled(): boolean;
-    get token(): string;
-    private _subscribeToPushNotifications;
-    private _unsubscribeFromPushNotifications;
-    private _initialize;
+    private static _parsePushNotificationChatData;
+    /**
+     * Populate the client with init registrations.
+     * @param reg The init registration to populate.
+     */
+    static populateInitRegistrations(reg: InitRegistration): void;
     /**
      * Gracefully shut down the client.
      */
@@ -2164,6 +2247,12 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * @param conversationSid Conversation sid
      */
     getConversationBySid(conversationSid: string): Promise<Conversation>;
+    /**
+     * Peek a conversation by its SID.
+     * @param conversationSid Conversation sid
+     * @internal
+     */
+    peekConversationBySid(conversationSid: string): Promise<Conversation>;
     /**
      * Get a known conversation by its unique identifier name.
      * @param uniqueName The unique identifier name of the conversation.
@@ -2182,7 +2271,8 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
     /**
      * Register for push notifications.
      * @param channelType Channel type.
-     * @param registrationId Push notification ID provided by the FCM/APNS service on the platform.
+     * @param registrationId Push notification ID provided by the FCM/APNS service
+     * on the platform.
      */
     setPushRegistrationId(channelType: NotificationsChannelType, registrationId: string): Promise<void>;
     /**
@@ -2195,27 +2285,29 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * Clear existing registrations directly using provided device token.
      * This is useful to ensure stopped subscriptions without resubscribing.
      *
-     * This function goes completely beside the state machine and removes all registrations.
-     * Use with caution: if it races with current state machine operations, madness will ensue.
+     * This function goes completely beside the state machine and removes all
+     * registrations.
+     * Use with caution: if it races with current state machine operations,
+     * madness will ensue.
      *
      * @param channelType Channel type.
-     * @param registrationId Push notification ID provided by the FCM/APNS service on the platform.
+     * @param registrationId Push notification ID provided by the FCM/APNS service
+     * on the platform.
      */
     removePushRegistrations(channelType: ChannelType, registrationId: string): Promise<void>;
-    private static parsePushNotificationChatData;
     /**
-     * Static method for push notification payload parsing. Returns parsed push as a {@link PushNotification} object.
-     * @param notificationPayload Push notification payload.
+     * Current version of the Conversations client.
      */
-    static parsePushNotification(notificationPayload: any): PushNotification;
     parsePushNotification: typeof Client.parsePushNotification;
     /**
-     * Handle push notification payload parsing and emit the {@link Client.pushNotification} event on this {@link Client} instance.
+     * Handle push notification payload parsing and emit the
+     * {@link Client.pushNotification} event on this {@link Client} instance.
      * @param notificationPayload Push notification payload
      */
     handlePushNotification(notificationPayload: any): Promise<void>;
     /**
-     * Gets a user with the given identity. If it's in the subscribed list, then return the user object from it;
+     * Gets a user with the given identity. If it's in the subscribed list, then
+     * return the user object from it;
      * if not, then subscribe and add user to the subscribed list.
      * @param identity Identity of the user.
      * @returns A fully initialized user.
@@ -2225,6 +2317,32 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * Get a list of subscribed user objects.
      */
     getSubscribedUsers(): Promise<Array<User>>;
+    /**
+     * Get content URLs for all media attachments in the given set of media sids
+     * using a single operation.
+     * @param mediaSids Set of media sids to query for the content URL.
+     */
+    getTemporaryContentUrlsForMediaSids(mediaSids: string[]): CancellablePromise<Map<string, string>>;
+    /**
+     * Get content URLs for all media attachments in the given set using a single
+     * operation.
+     * @param contentSet Set of media attachments to query content URLs.
+     */
+    getTemporaryContentUrlsForMedia(contentSet: Media[]): CancellablePromise<Map<string, string>>;
+    /**
+     * Initialize the client.
+     */
+    private _initialize;
+    /**
+     * Subscribe to push notifications.
+     * @param channelType The channel type to subscribe to.
+     */
+    private _subscribeToPushNotifications;
+    /**
+     * Unsubscribe from push notifications.
+     * @param channelType The channel type to unsubscribe from.
+     */
+    private _unsubscribeFromPushNotifications;
 }
 declare class NotificationTypes {
     static readonly TYPING_INDICATOR = "twilio.ipmsg.typing_indicator";