@vonage/client-sdk
Version:
The Client SDK is intended to provide a ready solution for developers to build Programmable Conversation applications across multiple Channels including: Messages, Voice, SIP, websockets, and App.
555 lines (554 loc) • 19.4 kB
TypeScript
import vonage from '../utils/vonage';
import { Conversation, ConversationsPage, EventsPage, MembersPage, ClientInitConfigObject, ClientConfigObject, Json, CustomData, Location, Template, Whatsapp, CreateConversationParameters, GetConversationsParameters, GetConversationEventsParameters, GetConversationMembersParameters, GetCallLegsParameters, UpdateConversationParameters, LegsPage, HangupReason, CallDisconnectReason, CancelReason, LegStatus, VoiceChannelType, SessionErrorReason, VonageError } from '../utils';
import { Nullable } from '../kotlin/clientsdk-clientcore_js';
import { ConversationEvent } from '../kotlin/JsUnions';
/**
* The Vonage Client SDK for JS/TS provides a simple interface
* For the Vonage Voice and Messaging APIs.
*
* @remarks
* Built on top of the Kotlin Multiplatform SDK, it provides a
* more JS-like API, and platform specific implementations for
* the underlying network and media layers.
*
* @packageDocumentation
*/
export * from '../utils';
type VonageEventOverride = Omit<vonage.CombinedEvents, 'conversationEvent' | 'callHangup' | 'callMediaDisconnect' | 'legStatusUpdate' | 'rtcStatsUpdate' | 'callInvite' | 'callInviteCancel' | 'sessionError' | 'callMediaError'> & {
conversationEvent: (event: ConversationEvent) => void;
callHangup: (callId: string, callQuality: RTCQuality, reason: HangupReason) => void;
callMediaDisconnect: (callId: string, reason: CallDisconnectReason) => void;
legStatusUpdate: (callId: string, legId: string, legStatus: LegStatus) => void;
rtcStatsUpdate: (stats: RtcStats, callId: string) => void;
callInviteCancel: (callId: string, reason: CancelReason) => void;
callInvite: (callId: string, from: string, channelType: VoiceChannelType) => void;
sessionError: (reason: SessionErrorReason) => void;
callMediaError: (callId: string, error: VonageError) => void;
};
/**
* Vonage Event Names
* The events that can be listened to via the `on` method
*
* @remarks
* Thsese names map to the VonageEventProps type to provide
* type safety when registering callbacks.
* @group VonageEvents
*/
type VonageEventNames = keyof VonageEventOverride;
/**
* Vonage Event Props
*/
type VonageEventProps<T> = T extends VonageEventNames ? VonageEventOverride[T] : never;
/**
* Vonage Events that can be listened to via the `on` method
* @interface
*/
export type VonageEvent = {
[key in VonageEventNames]: VonageEventProps<key>;
};
/**
* Information about the quality of a Voice Call
*
* @property mos_score
* @property quality_percentage
* @property jitter_min_var
* @property jitter_max_var
* @property jitter_loss_rate
* @property jitter_burst_rate
* @property flaw_total
* @property packet_cnt
* @property packet_loss_perc
* @interface
* @group Voice
*/
export type RTCQuality = vonage.RTCQualityJS;
/**
* Represents the Leg of a Voice Call
*
* @property id The Leg id
* @property type The type of Leg
* @property direction The direction of the Leg (inbound or outbound)
* @property conversationId The id of the Conversation the Leg belongs to
* @property status The status of the Leg
* @property startTime The timestamp when the Leg started
* @property endTime The timestamp when the Leg ended
* @property from The from {@link LegChannel}
* @property to The to {@link LegChannel}
* @interface
* @group Voice
*/
export type Leg = vonage.LegJS;
/**
* Represents a Leg Channel
*
* @property type The type of Channel
* @property user The user id of the Channel
* @property number The number id of the Channel
* @interface
* @group Voice
*/
export type LegChannel = vonage.LegChannelJS;
/**
* Parameters for {@link VonageClient.say}
*
* @property text
* @property level
* @property loop
* @property queue
* @property voiceName
* @property ssml
* @interface
* @group Voice
*/
export type CallSayParams = Partial<vonage.CallSayParams> & {
text: string;
};
/**
* WebRTC Stats of a Voice Call
*
* @property audioRecvPackets
* @property audioRecvPacketsLost
* @property audioRecvBytes
* @property audioRecvJitter
* @property audioSentPackets
* @property audioSentPacketsLost
* @property audioSentBytes
* @property audioSentJitter
* @property audioRtt
* @interface
* @group Voice
*/
export type RtcStats = vonage.RTCStatsJS;
/**
* VonageClient is the main entry point for the Vonage Client SDK.
*
* @privateRemarks
* This class is a wrapper around the KMP `CombinedClientJS` class.
* It provides a more JS-like API, and also provides a proxy object
* to allow for registering callbacks via `on()`.
*
* Minimal Interface built on top of KMP export
* DO NOT ADD CODE HERE UNLESS REALLY NEEDEED!!111!
*/
export declare class VonageClient extends vonage.CombinedClientJS {
constructor(config?: ClientInitConfigObject);
/**
* Set a configuration for the client SDK
*
* @example
* [[include: snippet_SetClientConfig.txt]]
*
* @param config - A configuration object
* @returns void
*/
setConfig(config: ClientConfigObject): void;
/**
* Register a callback for an event.
*
* @example
* [[include: snippet_OnConversationEventListener.txt]]
*
* @param event - the event to register for (e.g. 'legStatusUpdate')
* @param callback - the callback to register for the event
* @returns a symbol that can be used to unregister the callback
* @remarks
* Be sure to store the symbol returned by this method so you can unregister the callback later.
* We recommend unregistering callbacks when you no longer need them. See {@link off}.
*/
on<T extends VonageEventNames, P extends VonageEvent[T]>(event: T, callback: P): symbol;
/**
* Unregister a callback for an event.
*
* @example
* [[include: snippet_UnregisterListener.txt]]
*
* @param event - the event to register for (e.g. 'legStatusUpdate')
* @param callbackSymbol - the callback symbol to unregister
* @returns true if the callback was unregistered, false otherwise
* @remarks
* We recommend deregistering callbacks when you no longer need them.
*/
off<T extends keyof VonageEvent>(event: T, callbackSymbol: symbol): boolean;
/**
* Clear all callbacks for an event.
*
* @example
* [[include: snippet_ClearCallbacks.txt]]
*
* @param event - the event to unregister from (e.g. 'legStatusUpdate')
* @returns void
*
* @remarks
* This is useful for cleaning up callbacks when you no longer need them.
*
*/
clearCallbacks<T extends keyof VonageEvent>(event: T): void;
/**
* Create a session with a token and optional sessionId
* If no sessionId is provided, a new one will be generated
* and returned. If a sessionId is provided, it will be used
* to resume an existing session.
*
* @example
* [[include: snippet_SessionCreate.txt]]
*
* @param token
* @param sessionId - optional sessionId to use
* @returns the `sessionId` of the session
*/
createSession(token: string, sessionId?: string | null): Promise<string>;
/**
* Get the Peer Connection for a call
*
* @experimental
* @group Voice
* @param id - The Call Id
*/
getPeerConnection(id: string): RTCPeerConnection;
/**
* Get the HTML Audio Element for the SDK.
* It can be used to route output to other devices.
*
* @experimental
* @group Voice
*/
getAudioOutputElement(): HTMLAudioElement | undefined;
/**
* Get the Leg for a call
*
* @group Voice
* @param legId - The Leg Id
*/
getLeg(legId: string): Promise<Leg>;
/**
* Get a Call's Legs
*
* @example
* [[include: snippet_GetCallLegs.txt]]
*
* @group Voice
* @param id - the Call's id
* @param parameters - A {@link GetCallLegsParameters} object containing the parameters for the request.
* @returns a `LegsPage` containing the legs
*/
getCallLegs(callId: string, parameters?: Nullable<GetCallLegsParameters>): Promise<LegsPage>;
/**
* Make a server call to the Vonage API.
* This is used to initiate a call using the Voice API and NCCO.
*
* @example
* [[include: snippet_OutboundCall.txt]]
*
* @group Voice
* @param context - the context to send to the server passed as Custom data to the voice answer webhook
* @returns the `callId` of the call
*/
serverCall(context?: Json): Promise<string>;
/**
* Hangup a call.
*
* @example
* [[include: snippet_CallHangup.txt]]
*
* @group Voice
* @param callId - the `callId` of the call to hangup
* @param reasonText - optional reason text to send to the other party
* @param reasonCode - optional reason code to send to the other party
* @returns void
*/
hangup(callId: string, reasonText?: string, reasonCode?: string): Promise<void>;
/**
* Sends a TTS message to the Call
*
* @group Voice
* @param callId - the `callId` of the call to send the message to
* @param text - the text to send
* @returns void
*/
say(callId: string, text: string): Promise<void>;
/**
* Sends a TTS message to the Call
*
* @example
* [[include: snippet_Say.txt]]
*
* @group Voice
* @param callId - the `callId` of the call to send the message to
* @param params - the `CallSayParams` to send
* @returns void
*/
say(callId: string, params: CallSayParams): Promise<void>;
/**
* Get a list of Conversations for the user.
*
* @example
* [[include: snippet_GetConversations.txt]]
*
* @group Chat
* @param parameters - A {@link GetConversationsParameters} object containing the parameters for the request.
* @returns a `ConversationsPage` containing the conversations
*/
getConversations(parameters?: Nullable<GetConversationsParameters>): Promise<ConversationsPage>;
/**
* Get a Conversation's Events
*
* @example
* [[include: snippet_GetConversationEvents.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param parameters - A {@link GetConversationEventsParameters} object containing the parameters for the request.
* @returns a {@link EventsPage} containing the events
*/
getConversationEvents(id: string, parameters?: Nullable<GetConversationEventsParameters>): Promise<EventsPage>;
/**
* Get a Conversation's Members
*
* @example
* [[include: snippet_GetConversationMembers.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param parameters - A {@link GetConversationMembersParameters} object containing the parameters for the request.
* @returns a `MembersPage` containing the members
*/
getConversationMembers(id: string, parameters?: Nullable<GetConversationMembersParameters>): Promise<MembersPage>;
/**
* Create a conversation
*
* @example
* [[include: snippet_CreateConversation.txt]]
*
* @group Chat
* @param parameters - A {@link CreateConversationParameters} object containing the parameters for the creation request.
* @returns the `cid` of the conversation
*/
createConversation(parameters?: Nullable<CreateConversationParameters>): Promise<string>;
/**
* Get a Conversation
*
* @example
* [[include: snippet_GetConversation.txt]]
*
* @param conversationIdOrName - the Conversation's id or conversation name
* @returns the `Conversation`
*/
getConversation(conversationIdOrName: string): Promise<Conversation>;
/**
* Updates a conversation object identified by its unique conversation ID.
*
* This method overrides the conversation properties to the provided parameters and rest remains as it is.
*
* @example
* [[include: snippet_UpdateConversation.txt]]
*
* @param conversationId - the Conversation's id.
* @param parameters - The properties of the conversation. These will replace existing values to the provided ones, rest will remain as they are.
* @returns `conversation`, this object will contain the updated conversation properties if the update is successful.
*/
updateConversation(conversationId: string, parameters: UpdateConversationParameters): Promise<Conversation>;
/**
* Leave a Conversation
*
* @example
* [[include: snippet_LeaveConversation.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @returns void
*/
leaveConversation(id: string): Promise<void>;
/**
* Join a Conversation
*
* @example
* [[include: snippet_JoinConversation.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @returns the `memberId` of the member
*/
joinConversation(id: string): Promise<string>;
/**
* Delete a Conversation
*
* @example
* [[include: snippet_DeleteConversation.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @returns void
*/
deleteConversation(id: string): Promise<void>;
/**
* Invite a user to a Conversation by user's `name`
*
* @example
* [[include: snippet_InviteToConversation.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param name - the name of the user to invite
* @returns the `memberId` of the member
*/
inviteToConversation(id: string, name: string): Promise<string>;
/**
* Send a text message to a Conversation
*
* @example
* [[include: snippet_SendTextMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param text - the Body of the message
* @returns the `timestamp` of the message
*/
sendMessageTextEvent(id: string, text: string): Promise<string>;
/**
* Send a custom message to a Conversation
*
* @example
* [[include: snippet_SendCustomMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param customData - the body of the message
* @returns the `timestamp` of the message
*/
sendMessageCustomEvent(id: string, customData: CustomData): Promise<string>;
/**
* Send a Image message to a Conversation.
*
* @example
* [[include: snippet_SendImageMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param imageUrl - the url of the image resource.
* @returns the `timestamp` of the message
*/
sendMessageImageEvent(id: string, imageUrl: URL): Promise<string>;
/**
* Send a Vidoe message to a Conversation.
*
* @example
* [[include: snippet_SendVideoMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param videoUrl - the url of the video resource.
* @returns the `timestamp` of the message
*/
sendMessageVideoEvent(id: string, videoUrl: URL): Promise<string>;
/**
* Send a file message to a Conversation.
*
* @example
* [[include: snippet_SendFileMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param fileUrl - the url of the file resource.
* @returns the `timestamp` of the message
*/
sendMessageFileEvent(id: string, fileUrl: URL): Promise<string>;
/**
* Send a audio message to a Conversation.
*
* @example
* [[include: snippet_SendAudioMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param audioUrl - the url of the audio resource.
* @returns the `timestamp` of the message
*/
sendMessageAudioEvent(id: string, audioUrl: URL): Promise<string>;
/**
* Send a vcard message to a Conversation.
*
* @example
* [[include: snippet_SendVcardMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param vCardUrl - the url of the vCardUrl resource.
* @returns the `timestamp` of the message
*/
sendMessageVCardEvent(id: string, vCardUrl: URL): Promise<string>;
/**
* Send a Location message to a Conversation.
*
* @example
* [[include: snippet_SendLocationMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param location - the description of the location.
* @returns the `timestamp` of the message
*/
sendMessageLocationEvent(id: string, location: Location): Promise<string>;
/**
* Send a template message to a Conversation.
*
* @example
* [[include: snippet_SendTemplateMessage.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param whatsappObject - the description(locale and policies of business account) of the location.
* @param templateObject - the description(name and paramters) of the template.
* @returns the `timestamp` of the message
*/
sendMessageTemplateEvent(id: string, templateObject: Template, whatsappObject: Whatsapp): Promise<string>;
/**
* Send an ephemeral event to a Conversation
*
* @example
* [[include: snippet_SendEphemeralEvent.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param customData - the body of the event
* @returns the `timestamp` of the message
*/
sendEphemeralEvent(id: string, customData: CustomData): Promise<string>;
/**
* Send a Custom event to a Conversation
*
* @example
* [[include: snippet_SendCustomEvent.txt]]
*
* @group Chat
* @param id - the Conversation's id
* @param evenType - the type of the custom event. Type must start with `custom:<...>`
* @param customData - the body of the event
* @returns the `timestamp` of the message
*/
sendCustomEvent(id: string, eventType: string, customData: CustomData): Promise<string>;
/**
* Delete an Event in a Conversation
*
* @example
* [[include:snippet_DeleteEvent.txt]]
*
* @group Chat
* @param id - the id for the Event to be deleted
* @param conversationId - the id for the conversation, the event belongs to.
* @returns void
*/
deleteEvent(id: number, conversationId: string): Promise<void>;
/**
* Send a message seen event to a Conversation
*
* @example
* [[include: snippet_SendMessageSeenEvent.txt]]
*
* @group Chat
* @param id - the event id
* @param conversationId - the conversation id
* @returns the `timestamp` of the message
*/
sendMessageSeenEvent(id: number, conversationId: string): Promise<string>;
}
export default VonageClient;