@twilio/conversations 3.0.1-rc.1 → 3.0.1-rc.103

package/builds/lib.d.ts

@@ -1,13 +1,13 @@
 /// <reference types="node" />
 import { SyncClient, SyncDocument, SyncList } from "twilio-sync";
 import { LogLevelDesc } from "loglevel";
-import { TwilsockClient } from "twilsock";
+import { Transport, TwilsockClient, InitRegistration, TransportResult } from "twilsock";
+import { ConnectionState as TwilsockConnectionState } from "twilsock";
 import { ReplayEventEmitter } from "@twilio/replay-event-emitter";
-import { JSONValue, CancellationError } from "@twilio/shared";
-import { CancellablePromise as CancellablePromise$0 } 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";
+import { MediaCategory as McsMediaCategory } from "@twilio/mcs-client";
 interface ConfigurationResponse {
     options: {
         consumption_report_interval: string;
@@ -111,10 +111,11 @@ declare class Configuration {
     readonly userInfo: string;
     readonly myConversations: string;
     readonly channelMetadataCacheCapacity: number;
+    readonly messageRecipientsCacheCapacity: number;
     constructor(options: ClientOptions, configurationResponse: ConfigurationResponse, logger: Logger);
 }
 interface CommandExecutorServices {
-    transport: TwilsockClient;
+    transport: Transport;
 }
 declare class CommandExecutor {
     private _serviceUrl;
@@ -126,6 +127,20 @@ declare class CommandExecutor {
     fetchResource<Request = void, Response = void>(url: string, requestBody?: Request): Promise<Response>;
     mutateResource<Request = void, Response = void>(method: "post" | "delete", url: string, requestBody?: Request): Promise<Response>;
 }
+/**
+ * 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;
@@ -252,16 +267,12 @@ 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 static responsePostProcess;
     private executeWithRetry;
-    get(url: string): Promise<any>;
-    disconnect(): Promise<void>;
+    get<T>(url: string): Promise<TransportResult<T>>;
 }
 type UsersEvents = {
     userUpdated: (data: {
@@ -421,7 +432,7 @@ declare class Participant extends ReplayEventEmitter<ParticipantEvents> {
      * using the type dynamically `participant.bindings[participant.type]`
      * just be aware that the binding information has different structure for
      * each participant type.
-     * See also {@link ParticipantEmailBinding}, the only available currently binding descriptor.
+     * See also {ParticipantEmailBinding}, the only available currently binding descriptor.
      */
     get bindings(): ParticipantBindings;
     /**
@@ -483,15 +494,39 @@ declare class Participant extends ReplayEventEmitter<ParticipantEvents> {
      */
     updateAttributes(attributes: JSONValue): Promise<Participant>;
 }
-/**
- * Participant binding options
- */
+interface ParticipantResponse {
+    account_sid: string;
+    chat_service_sid: string;
+    conversation_sid: string;
+    role_sid: string;
+    sid: string;
+    attributes: string;
+    date_created: string;
+    date_updated: string;
+    identity: string;
+    messaging_binding: {
+        type: "chat" | "sms" | "whatsapp" | "email";
+        address: string;
+        proxy_address: string;
+    } | null;
+    url: string;
+    links: {
+        conversation: string;
+    };
+}
 interface ParticipantBindingOptions {
     email?: ParticipantEmailBinding;
 }
+/**
+ * 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 | null;
     contentType: string;
     size: number;
@@ -529,7 +564,7 @@ declare class Media {
     /**
      * 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.
      *
@@ -1115,7 +1150,7 @@ declare class ContentTemplateVariable {
 /**
  * A rich content template.
  *
- * Use {@link Client.getContentTemplates} to request all the templates available
+ * Use {@Link Client.getContentTemplates} to request all the templates available
  * for the current account.
  */
 declare class ContentTemplate {
@@ -1175,6 +1210,115 @@ declare class ChannelMetadataClient {
     constructor(services: ChannelMetadataClientServices, configuration: Configuration);
     getChannelMetadata(conversationSid: string, messageSid: string): Promise<ChannelMetadata | null>;
 }
+type MessageRecipient = {
+    message_sid: string;
+    type: "email"; // discriminant for future expansion
+    level: "to" | "from" | "cc";
+    name: string;
+    address: string;
+};
+/**
+ * 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;
+    /**
+     * Array of elements of type T on the current page.
+     */
+    items: T[];
+    /**
+     * Request next page.
+     * Does not modify the existing object.
+     */
+    nextPage(): Promise<Paginator<T>>;
+    /**
+     * Request previous page.
+     * Does not modify the existing object.
+     */
+    prevPage(): Promise<Paginator<T>>;
+}
+type MessageRecipientsClientServices = {
+    commandExecutor: CommandExecutor;
+};
+/**
+ * Message recipient descriptor.
+ */
+type RecipientDescriptor = EmailRecipientDescriptor | UnknownRecipientDescriptor;
+/**
+ * Email recipient level.
+ */
+type EmailRecipientLevel = "to" | "from" | "cc";
+/**
+ * Email recipient descriptor.
+ */
+declare class EmailRecipientDescriptor {
+    /**
+     * Type of recipient.
+     */
+    readonly type = "email";
+    /**
+     * Sid of the message that this recipient belongs to.
+     */
+    readonly messageSid: string;
+    /**
+     * Email recipient level.
+     */
+    readonly level: EmailRecipientLevel;
+    /**
+     * Name of the recipient.
+     */
+    readonly name: string;
+    /**
+     * Address of the recipient.
+     */
+    readonly address: string;
+    /**
+     * @internal
+     */
+    constructor(recipient: MessageRecipient);
+}
+/**
+ * Unknown recipient descriptor. Used to be able to handle recipient types that
+ * are not supported by the current version of the SDK.
+ */
+declare class UnknownRecipientDescriptor {
+    /**
+     * Type of recipient.
+     */
+    readonly type: string;
+    /**
+     * Sid of the message that this recipient belongs to.
+     */
+    readonly messageSid: string;
+    /**
+     * Recipient data as a JSON string.
+     */
+    readonly rawData: string;
+    /**
+     * @internal
+     */
+    constructor(recipient: MessageRecipient);
+}
+declare class MessageRecipientsClient {
+    private readonly _services;
+    private readonly _configuration;
+    private readonly _cache;
+    constructor(services: MessageRecipientsClientServices, configuration: Configuration);
+    getRecipientsFromMessage(conversationSid: string, messageSid: string): Promise<RecipientDescriptor[]>;
+    getRecipientsFromConversation(conversationSid: string, paginatorOptions?: {
+        pageToken?: string;
+        pageSize?: string;
+    }): Promise<Paginator<RecipientDescriptor>>;
+    private _wrapResponse;
+}
 type MessageEvents = {
     updated: (data: {
         message: Message;
@@ -1186,6 +1330,7 @@ interface MessageServices {
     network: Network;
     commandExecutor: CommandExecutor;
     channelMetadataClient: ChannelMetadataClient;
+    messageRecipientsClient: MessageRecipientsClient;
 }
 interface MessageLinks {
     self: string;
@@ -1215,8 +1360,8 @@ interface MessageData {
     attributes?: JSONValue;
     dateUpdated: string;
     timestamp?: string;
-    medias: MediaState[] | null;
-    media: MediaState | null;
+    medias?: Media[];
+    media?: Media;
     memberSid?: string;
     delivery?: AggregatedDeliveryDescriptor;
     channelMetadata?: boolean;
@@ -1299,6 +1444,11 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      * Type of the message.
      */
     get type(): MessageType;
+    /**
+     * One of the attached media (if present).
+     * @deprecated Use attachedMedia instead. Note that the latter is now an array.
+     */
+    get media(): Media | null;
     /**
      * Return all media attachments, except email body/history attachments, without temporary urls.
      */
@@ -1311,6 +1461,14 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      * Aggregated information about the message delivery statuses across all participants of a conversation..
      */
     get aggregatedDeliveryReceipt(): AggregatedDeliveryReceipt | null;
+    /**
+     * @deprecated
+     * Return a (possibly empty) array of media matching a specific set of categories.
+     * Allowed category is so far only 'media'.
+     * @param categories Array of categories to match.
+     * @returns Array of media descriptors matching given categories.
+     */
+    getMediaByCategory(categories: Array<MediaCategory>): Array<Media> | null;
     /**
      * Return a (possibly empty) array of media matching a specific set of categories.
      * Allowed category is so far only 'media'.
@@ -1353,6 +1511,12 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      * @param attributes New attributes.
      */
     updateAttributes(attributes: JSONValue): Promise<Message>;
+    /**
+     * @deprecated
+     * 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.
+     */
+    attachTemporaryUrlsFor(contentSet: Media[] | null): Promise<Media[]>;
     /**
      * 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.
@@ -1378,34 +1542,10 @@ declare class Message extends ReplayEventEmitter<MessageEvents> {
      * the message doesn't have any channel metadata.
      */
     getChannelMetadata(): Promise<ChannelMetadata | null>;
-}
-/**
- * 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.
+     * Get recipients of the message.
      */
-    hasPrevPage: boolean;
-    /**
-     * Array of elements of type T on the current page.
-     */
-    items: T[];
-    /**
-     * Request next page.
-     * Does not modify the existing object.
-     */
-    nextPage(): Promise<Paginator<T>>;
-    /**
-     * Request previous page.
-     * Does not modify the existing object.
-     */
-    prevPage(): Promise<Paginator<T>>;
+    getMessageRecipients(): Promise<RecipientDescriptor[]>;
 }
 interface TypingIndicatorServices {
     twilsockClient: TwilsockClient;
@@ -1513,14 +1653,12 @@ interface MessageResponse {
     participant_sid: string;
     body: string;
     subject: string;
-    content_sid: string;
     date_created: string;
     date_updated: string;
     url: string;
     media: {
         sid: string;
         size: string;
-        category: string;
         content_type: string;
         filename: string;
     }[] | null;
@@ -1543,6 +1681,7 @@ interface MessagesServices {
     syncClient: SyncClient;
     commandExecutor: CommandExecutor;
     channelMetadataClient: ChannelMetadataClient;
+    messageRecipientsClient: MessageRecipientsClient;
 }
 /**
  * Represents the collection of messages in a conversation
@@ -1591,7 +1730,7 @@ declare class Messages extends ReplayEventEmitter<MessagesEvents> {
      */
     getMessages(pageSize: number | undefined, anchor: number | "end" | undefined, direction?: "forward" | "backwards"): Promise<SyncPaginator<Message>>;
     private _wrapPaginator;
-    _upsertMessage(index: number, value: MessageData): Message;
+    private _upsertMessage;
     /**
      * Returns last messages from conversation
      * @param {Number} [pageSize] Number of messages to return in single chunk. By default it's 30.
@@ -1838,6 +1977,7 @@ interface ConversationServices {
     syncClient: SyncClient;
     commandExecutor: CommandExecutor;
     channelMetadataClient: ChannelMetadataClient;
+    messageRecipientsClient: MessageRecipientsClient;
 }
 /**
  * Conversation descriptor.
@@ -2108,7 +2248,7 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * @param attributes Attributes to be attached to the participant.
      * @returns The added participant.
      */
-    add(identity: string, attributes?: JSONValue): Promise<Participant>;
+    add(identity: string, attributes?: JSONValue): Promise<ParticipantResponse>;
     /**
      * Add a non-chat participant to the conversation.
      * @param proxyAddress Proxy (Twilio) address of the participant.
@@ -2118,7 +2258,7 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * CC/To level.
      * @returns The added participant.
      */
-    addNonChatParticipant(proxyAddress: string, address: string, attributes?: JSONValue, bindingOptions?: ParticipantBindingOptions): Promise<Participant>;
+    addNonChatParticipant(proxyAddress: string, address: string, attributes?: JSONValue, bindingOptions?: ParticipantBindingOptions): Promise<ParticipantResponse>;
     /**
      * Advance the conversation's last read message index to the current read
      * horizon. Rejects if the user is not a participant of the conversation. Last
@@ -2233,7 +2373,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<Message>;
+    sendMessage(message: null | string | FormData | SendMediaOptions, messageAttributes?: JSONValue, emailOptions?: SendEmailOptions): Promise<number>;
     /**
      * New interface to prepare for sending a message.
      * Use this instead of {@link Conversation.sendMessage}.
@@ -2286,6 +2426,10 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
      * to null removes it.
      */
     updateUniqueName(uniqueName: string | null): Promise<Conversation>;
+    /**
+     * Get recipients of all messages in the conversation.
+     */
+    getMessageRecipients(): Promise<Paginator<RecipientDescriptor>>;
     /**
      * Load and subscribe to this conversation and do not subscribe to its
      * participants and messages. This or _subscribeStreams will need to be called
@@ -2340,9 +2484,6 @@ declare class Conversation extends ReplayEventEmitter<ConversationEvents> {
     private _setLastReadMessageIndex;
 }
 type ConversationsDataSource = "sync" | "rest";
-/**
- * Type of a push notification.
- */
 type PushNotificationType = "twilio.conversations.new_message" | "twilio.conversations.added_to_conversation" | "twilio.conversations.removed_from_conversation";
 interface PushNotificationDescriptor {
     title: string | null;
@@ -2454,11 +2595,12 @@ type ClientEvents = {
         user: User;
         updateReasons: UserUpdateReason[];
     }) => void;
+    stateChanged: (state: State) => void;
     initialized: () => void;
     initFailed: ({ error }: {
         error?: ConnectionError;
     }) => void;
-    connectionStateChanged: (state: ConnectionState) => void;
+    connectionStateChanged: (state: TwilsockConnectionState) => void;
     connectionError: (data: ConnectionError) => void;
 };
 /**
@@ -2471,7 +2613,7 @@ type ClientEvents = {
  * * `'denied'` - client connection is denied because of invalid JWT access
  * token. User must refresh token in order to proceed
  */
-type ConnectionState = "disconnected" | "connecting" | "connected";
+type ConnectionState = TwilsockConnectionState;
 /**
  * State of the client. Possible values are as follows:
  * * `'failed'` - the client failed to initialize
@@ -2500,10 +2642,14 @@ interface ClientOptions {
      * The cache capacity for channel metadata.
      */
     channelMetadataCacheCapacity?: number;
+    /**
+     * The cache capacity for message recipients.
+     */
+    messageRecipientsCacheCapacity?: number;
     region?: string;
     productId?: string;
     twilsockClient?: TwilsockClient;
-    transport?: TwilsockClient;
+    transport?: Transport;
     notificationsClient?: NotificationClient;
     syncClient?: SyncClient;
     typingIndicatorTimeoutOverride?: number;
@@ -2518,6 +2664,7 @@ interface ClientOptions {
     Notification?: Record<string, unknown>;
     Twilsock?: Record<string, unknown>;
     clientMetadata?: Record<string, unknown>;
+    initRegistrations?: InitRegistration[];
     disableDeepClone?: boolean;
     typingUri?: string;
     apiUri?: string;
@@ -2717,6 +2864,15 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * @event
      */
     static readonly userUpdated = "userUpdated";
+    /**
+     * @deprecated Use initialized or initFailed events instead
+     * 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 client has completed initialization successfully.
      * @event
@@ -2776,7 +2932,7 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
     /**
      * Client connection state.
      */
-    connectionState: ConnectionState | "unknown";
+    connectionState: ConnectionState;
     /**
      * Promise that resolves on successful initialization.
      */
@@ -2840,6 +2996,32 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * initialization was completed.
      */
     get reachabilityEnabled(): boolean;
+    /**
+     * @deprecated
+     * Current token.
+     * @internal
+     */
+    get token(): string;
+    /**
+     * @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.
@@ -2851,6 +3033,11 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * @param data Data to parse
      */
     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.
      */
@@ -2893,6 +3080,12 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * on the platform.
      */
     setPushRegistrationId(channelType: NotificationsChannelType, registrationId: string): Promise<void>;
+    /**
+     * Unregister from push notifications.
+     * @param channelType Channel type.
+     * @deprecated Use removePushRegistrations() instead.
+     */
+    unsetPushRegistrationId(channelType: NotificationsChannelType): Promise<void>;
     /**
      * Clear existing registrations directly using provided device token.
      * This is useful to ensure stopped subscriptions without resubscribing.
@@ -2955,6 +3148,11 @@ declare class Client extends ReplayEventEmitter<ClientEvents> {
      * @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";
@@ -2964,7 +3162,4 @@ 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, 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$0 as CancellablePromise, CancellationError, ContentDataActionUrl, ContentDataActionPhone, ContentDataActionReply, ContentDataActionOther, ContentDataAction, ContentDataText, ContentDataMedia, ContentDataLocation, ContentDataReply, ContentDataQuickReply, ContentDataCallToAction, ContentDataListPicker, ContentDataListItem, ContentDataCard, ContentDataOther, ContentData, ContentTemplate, ContentTemplateVariable, ChannelMetadata, LogLevel };
-export { JSONValue, JSONObject, JSONArray } from "@twilio/shared";
-export { MediaCategory } from "@twilio/mcs-client";
-export { ChannelType } from "@twilio/notifications";
+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, ContentDataActionUrl, ContentDataActionPhone, ContentDataActionReply, ContentDataActionOther, ContentDataAction, ContentDataText, ContentDataMedia, ContentDataLocation, ContentDataReply, ContentDataQuickReply, ContentDataCallToAction, ContentDataListPicker, ContentDataListItem, ContentDataCard, ContentDataOther, ContentData, ContentTemplate, ContentTemplateVariable, ChannelMetadata, RecipientDescriptor, EmailRecipientDescriptor, UnknownRecipientDescriptor, EmailRecipientLevel };