@twilio/conversations 3.0.0-canary.13 → 3.0.0-canary.2

package/builds/lib.d.ts

@@ -1,8 +1,9 @@
+/// <reference types="node" />
 import { SyncClient, SyncDocument, SyncList } from "twilio-sync";
 import { LogLevelDesc } from "loglevel";
-import { Transport, TwilsockClient, InitRegistration, ConnectionError, TransportResult } from "twilsock";
-import { ConnectionState as TwilsockConnectionState } from "twilsock";
+import { TwilsockClient, InitRegistration } from "twilsock";
 import { ReplayEventEmitter } from "@twilio/replay-event-emitter";
+import { JSONValue } from "@twilio/shared";
 import { ChannelType, Notifications } from "@twilio/notifications";
 import { Notifications as NotificationClient } from "@twilio/notifications";
 import { CancellablePromise, McsClient, MediaCategory, McsMedia } from "@twilio/mcs-client";
@@ -112,7 +113,7 @@ declare class Configuration {
     constructor(options: ClientOptions, configurationResponse: ConfigurationResponse, logger: Logger);
 }
 interface CommandExecutorServices {
-    transport: Transport;
+    transport: TwilsockClient;
 }
 declare class CommandExecutor {
     private _serviceUrl;
@@ -124,20 +125,6 @@ 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>;
 }
-/**
- * Represents a JSON value.
- */
-type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
-/**
- * Represents a JSON object.
- */
-type JSONObject = {
-    [x: string]: JSONValue;
-};
-/**
- * Represents a JSON array.
- */
-type JSONArray = JSONValue[];
 type UserEvents = {
     updated: (data: {
         user: User;
@@ -264,12 +251,16 @@ declare class Network {
     private cacheLifetime;
     private readonly cache;
     private timer;
+    private pendingRequests;
+    private isShutdownInitiated;
     constructor(configuration: any, services: any);
     private isExpired;
     private cleanupCache;
     pokeTimer(): void;
+    private responsePostProcess;
     private executeWithRetry;
-    get<T>(url: string): Promise<TransportResult<T>>;
+    get(url: string): Promise<any>;
+    disconnect(): Promise<void>;
 }
 type UsersEvents = {
     userUpdated: (data: {
@@ -567,7 +558,7 @@ interface AggregatedDeliveryDescriptor {
  * Contains aggregated information about delivery statuses of a message across all participants
  * of a conversation.
  *
- * At any moment during the message delivery to a participant, the message can have zero or more of following
+ * At any moment during the message delivery to a participant, the message can have zero or more of the following
  * delivery statuses:
  * * Message is considered as **sent** to a participant if the nearest upstream carrier accepted the message.
  * * Message is considered as **delivered** to a participant if Twilio has received confirmation of message
@@ -731,8 +722,8 @@ interface MessageData {
     attributes?: JSONValue;
     dateUpdated: string;
     timestamp?: string;
-    medias?: Media[];
-    media?: Media;
+    medias: MediaState[] | null;
+    media: MediaState | null;
     memberSid?: string;
     delivery?: AggregatedDeliveryDescriptor;
 }
@@ -782,14 +773,15 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      */
     get dateUpdated(): Date | null;
     /**
-     * Index of the message in the conversation's messages list.
-     * By design of the Conversations system, the message indices may have arbitrary gaps between them,
+     * Index of this message in the conversation's list of messages.
+     *
+     * By design, the message indices may have arbitrary gaps between them,
      * that does not necessarily mean they were deleted or otherwise modified - just that
      * messages may have some non-contiguous indices even if they are being sent immediately one after another.
      *
      * Trying to use indices for some calculations is going to be unreliable.
      *
-     * To calculate the number of unread messages it is better to use the read horizon API.
+     * To calculate the number of unread messages, it is better to use the Read Horizon API.
      * See {@link Conversation.getUnreadMessagesCount} for details.
      */
     get index(): number;
@@ -1024,6 +1016,7 @@ interface MessageResponse {
     media: {
         sid: string;
         size: string;
+        category: string;
         content_type: string;
         filename: string;
     }[] | null;
@@ -1058,9 +1051,10 @@ declare class Messages extends ReplayEventEmitter<MessagesEvents> {
     constructor(conversation: Conversation, configuration: Configuration, services: MessagesServices);
     /**
      * Subscribe to the Messages Event Stream
-     * @param name - The name of Sync object for the Messages resource.
+     * @param arg - Name of the Sync object, or the SyncList itself, that
+     * represents the Messages resource.
      */
-    subscribe(name: string): Promise<SyncList>;
+    subscribe(arg: string | SyncList): Promise<SyncList>;
     unsubscribe(): Promise<void>;
     /**
      * Send a message to the conversation. The message could include text and multiple media attachments.
@@ -1092,7 +1086,7 @@ declare class Messages extends ReplayEventEmitter<MessagesEvents> {
      */
     getMessages(pageSize: number | undefined, anchor: number | "end" | undefined, direction?: "forward" | "backwards"): Promise<SyncPaginator<Message>>;
     private _wrapPaginator;
-    private _upsertMessage;
+    _upsertMessage(index: number, value: MessageData): Message;
     /**
      * Returns last messages from conversation
      * @param {Number} [pageSize] Number of messages to return in single chunk. By default it's 30.
@@ -1489,10 +1483,18 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * Messages entity.
      */
     private readonly _messagesEntity;
+    /**
+     * Sync list containing messages.
+     */
+    private _messagesList?;
     /**
      * Participants entity.
      */
     private readonly _participantsEntity;
+    /**
+     * Sync map containing participants.
+     */
+    private _participantsMap?;
     /**
      * Source of the most recent update.
      */
@@ -1663,7 +1665,7 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      */
     getMessagesCount(): Promise<number>;
     /**
-     * Get unread messages count for the user if they are a participant of this
+     * Get count of unread messages for the user if they are a participant of this
      * conversation. Rejects if the user is not a participant of the conversation.
      *
      * Use this method to obtain the number of unread messages together with
@@ -1671,12 +1673,19 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * message indices which may have gaps. See {@link Message.index} for details.
      *
      * This method is semi-realtime. This means that this data will be eventually
-     * correct, but will also be possibly incorrect for a few seconds. The
+     * correct, but it will also be possibly incorrect for a few seconds. The
      * Conversations system does not provide real time events for counter values
      * changes.
      *
      * This is useful for any UI badges, but it is not recommended to build any
      * core application logic based on these counters being accurate in real time.
+     *
+     * If the read horizon is not set, this function will return null. This could mean
+     * that all messages in the conversation are unread, or that the read horizon system
+     * is not being used. How to interpret this `null` value is up to the customer application.
+     *
+     * @return Number of unread messages based on the current read horizon set for
+     * the user or `null` if the read horizon is not set.
      */
     getUnreadMessagesCount(): Promise<number | null>;
     /**
@@ -1702,7 +1711,7 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * @param emailOptions Email options for the message.
      * @return Index of the new message.
      */
-    sendMessage(message: null | string | FormData | SendMediaOptions, messageAttributes?: JSONValue, emailOptions?: SendEmailOptions): Promise<number>;
+    sendMessage(message: null | string | FormData | SendMediaOptions, messageAttributes?: JSONValue, emailOptions?: SendEmailOptions): Promise<Message>;
     /**
      * New interface to prepare for sending a message.
      * Use this instead of {@link Message.sendMessage}.
@@ -1717,7 +1726,7 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
     setAllMessagesRead(): Promise<number>;
     /**
      * Set all messages in the conversation unread.
-     * @return Resulting unread messages count in the conversation.
+     * @returns New count of unread messages after this update.
      */
     setAllMessagesUnread(): Promise<number>;
     /**
@@ -1746,7 +1755,7 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * Set the last read message index to the current read horizon.
      * @param index Message index to set as last read. If null is provided, then
      * the behavior is identical to {@link Conversation.setAllMessagesUnread}.
-     * @returns Resulting unread messages count in the conversation.
+     * @returns New count of unread messages after this update.
      */
     updateLastReadMessageIndex(index: number | null): Promise<number>;
     /**
@@ -1762,6 +1771,16 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * @internal
      */
     _subscribe(): Promise<SyncDocument>;
+    /**
+     * Fetch participants and messages of the conversation. This method needs to
+     * be called during conversation initialization to catch broken conversations
+     * (broken conversations are conversations that have essential Sync entities
+     * missing, i.e. the conversation document, the messages list or the
+     * participant map). In case of this conversation being broken, the method
+     * will throw an exception that will be caught and handled gracefully.
+     * @internal
+     */
+    _fetchStreams(): Promise<void>;
     /**
      * Load the attributes of this conversation and instantiate its participants
      * and messages. This or _subscribe will need to be called before any events
@@ -1910,11 +1929,11 @@ type ClientEvents = {
         user: User;
         updateReasons: UserUpdateReason[];
     }) => void;
-    stateChanged: ({ state, error }: {
-        state: State;
+    initialized: () => void;
+    initFailed: ({ error }: {
         error?: ConnectionError;
     }) => void;
-    connectionStateChanged: (state: TwilsockConnectionState) => void;
+    connectionStateChanged: (state: ConnectionState) => void;
     connectionError: (data: ConnectionError) => void;
 };
 /**
@@ -1927,7 +1946,7 @@ type ClientEvents = {
  * * `'denied'` - client connection is denied because of invalid JWT access
  * token. User must refresh token in order to proceed
  */
-type ConnectionState = TwilsockConnectionState;
+type ConnectionState = "disconnected" | "connecting" | "connected";
 /**
  * State of the client. Possible values are as follows:
  * * `'failed'` - the client failed to initialize
@@ -1955,7 +1974,7 @@ interface ClientOptions {
     region?: string;
     productId?: string;
     twilsockClient?: TwilsockClient;
-    transport?: Transport;
+    transport?: TwilsockClient;
     notificationsClient?: NotificationClient;
     syncClient?: SyncClient;
     typingIndicatorTimeoutOverride?: number;
@@ -1975,6 +1994,10 @@ interface ClientOptions {
     typingUri?: string;
     apiUri?: string;
 }
+type ConnectionError = {
+    terminal: boolean;
+    message: string;
+};
 /**
  * Options for {@link Client.createConversation}.
  */
@@ -2167,16 +2190,20 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      */
     static readonly userUpdated = "userUpdated";
     /**
-     * Fired when the state of the client has been changed.
+     * Fired when the client has completed initialization successfully.
+     * @event
+     */
+    static readonly initialized = "initialized";
+    /**
+     * Fired when the client initialization failed.
      *
      * Parameters:
      * 1. object `data` - info object provided with the event. It has the
-     * following properties:
-     *     * {@link State} `state` - the new client state
+     * following property:
      *     * Error? `error` - the initialization error if present
      * @event
      */
-    static readonly stateChanged = "stateChanged";
+    static readonly initFailed = "initFailed";
     /**
      * Fired when the connection state of the client has been changed.
      *
@@ -2221,7 +2248,7 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
     /**
      * Client connection state.
      */
-    connectionState: ConnectionState;
+    connectionState: ConnectionState | "unknown";
     /**
      * Promise that resolves on successful initialization.
      */
@@ -2285,26 +2312,6 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * initialization was completed.
      */
     get reachabilityEnabled(): boolean;
-    /**
-     * @deprecated Call constructor directly.
-     *
-     * Factory method to create a Conversations client instance.
-     *
-     * 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 | null): Promise<Client>;
     /**
      * Static method for push notification payload parsing. Returns parsed push as
      * a {@link PushNotification} object.
@@ -2340,7 +2347,7 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * @param conversationSid Conversation sid
      * @internal
      */
-    peekConversationBySid(conversationSid: string): Promise<Conversation>;
+    private peekConversationBySid;
     /**
      * Get a known conversation by its unique identifier name.
      * @param uniqueName The unique identifier name of the conversation.
@@ -2440,4 +2447,5 @@ declare class NotificationTypes {
     static readonly REMOVED_FROM_CONVERSATION = "twilio.conversations.removed_from_conversation";
     static readonly CONSUMPTION_UPDATE = "twilio.channel.consumption_update";
 }
-export { Conversation, ConversationBindings, ConversationEmailBinding, ConversationUpdateReason, ConversationStatus, NotificationLevel, ConversationState, ConversationUpdatedEventArgs, SendMediaOptions, SendEmailOptions, LastMessage, Participant, ParticipantUpdateReason, ParticipantType, ParticipantUpdatedEventArgs, ParticipantBindings, ParticipantEmailBinding, ParticipantEmailLevel, Message, MessageUpdateReason, MessageType, MessageUpdatedEventArgs, Media, MediaCategory$0 as MediaCategory, AggregatedDeliveryReceipt, DeliveryAmount, DetailedDeliveryReceipt, DeliveryStatus, RestPaginator, MessageBuilder, UnsentMessage, Paginator, ParticipantBindingOptions, User, UserUpdateReason, UserUpdatedEventArgs, PushNotification, PushNotificationType, PushNotificationDescriptor, PushNotificationData, NotificationTypes, Client, State, ConnectionState, NotificationsChannelType, ClientOptions, CreateConversationOptions, ConversationLimits, JSONValue, JSONObject, JSONArray, CancellablePromise };
+export { Conversation, ConversationBindings, ConversationEmailBinding, ConversationUpdateReason, ConversationStatus, NotificationLevel, ConversationState, ConversationUpdatedEventArgs, SendMediaOptions, SendEmailOptions, LastMessage, Participant, ParticipantUpdateReason, ParticipantType, ParticipantUpdatedEventArgs, ParticipantBindings, ParticipantEmailBinding, ParticipantEmailLevel, Message, MessageUpdateReason, MessageType, MessageUpdatedEventArgs, Media, MediaCategory$0 as MediaCategory, AggregatedDeliveryReceipt, DeliveryAmount, DetailedDeliveryReceipt, DeliveryStatus, RestPaginator, MessageBuilder, UnsentMessage, Paginator, ParticipantBindingOptions, User, UserUpdateReason, UserUpdatedEventArgs, PushNotification, PushNotificationType, PushNotificationDescriptor, PushNotificationData, NotificationTypes, Client, State, ConnectionState, NotificationsChannelType, ClientOptions, CreateConversationOptions, ConversationLimits, CancellablePromise };
+export { JSONValue, JSONObject, JSONArray } from "@twilio/shared";