@vonage/client-sdk 1.1.0-alpha.1 → 1.1.0-alpha.12

package/README.md

@@ -1,52 +1,75 @@
-# Vonage Voice SDK
+# Vonage Client SDK
 
 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.
 
+> **⚠️ Warning:** Chat Functionality (Beta)
+>
+> The chat functionality in our SDK is currently in beta. Methods related to chat may undergo changes as we refine and improve this feature. Please be aware of potential updates as we work towards its stability. Your feedback is valuable in shaping its development.
+
 ## Installation
 
 The SDK can be installed using the npm install command
 
-```
+```bash
 npm i @vonage/client-sdk
 ```
 
 ## SDK setup
 
-### With budler (webpack or vite)
+### With bundler (Webpack, Vite, etc.) and React
 
 ```js
-import './App.css';
-import { VoiceClient, ClientConfig, ConfigRegion } from '@vonage/client-sdk';
-import VoiceClient, { ClientConfig, ConfigRegion } from '@vonage/client-sdk/voice'; // NextJS/Webpack users see note below
-
-const client = new VoiceClient();
-
-// Config is optional but recomended, default region is US
-const config = new ClientConfig(ConfigRegion.US);
-client.setConfig(config);
+import { VonageClient, ClientConfig, ConfigRegion } from '@vonage/client-sdk';
+import { useState, useEffect } from 'react';
 
 function App() {
-  const createSession = async () => {
-    const token = 'my-token';
-    await client.createSession(token);
-  };
-
-  return <button onClick={createSession}> create session </button>;
+  // Config is optional but recomended, default region is US
+  const [config] = useState(() => new ClientConfig(ConfigRegion.US));
+  const [client] = useState(() => {
+    const client = new VonageClient();
+    client.setConfig(config);
+    return client;
+  });
+  const [session, setSession] = useState();
+  const [user, setUser] = useState();
+  const [error, setError] = useState();
+
+  // Create Session as soon as client is available
+  useEffect(() => {
+    if (!client) return;
+    client
+      .createSession('my-token')
+      .then((session) => setSession(session))
+      .catch((error) => setError(error));
+  }, [client]);
+
+  // Get User as soon as a session is available
+  useEffect(() => {
+    if (!client || !session) return;
+    client
+      .getUser('me')
+      .then((user) => setUser(user))
+      .catch((error) => setError(error));
+  }, [client, session]);
+
+  if (error) return <pre>{JSON.stringify(error)}</pre>;
+
+  if (!session || !user) return <div>Loading...</div>;
+
+  return <div>User {user.displayName || user.name} logged in</div>;
 }
 
 export default App;
 ```
 
-- **Node**: We have a known issue with NextJS / Webpack that means the main import from `@vonage/client-sdk` doesn't work, however if you import from `@vonage/client-sdk/voice` the voice client successfully imports. we are working on a fix.
-
 ### With script tag (UMD)
 
 ```html
 <!-- <script src="./node_modules/@vonage/client-sdk/dist/vonageClientSDK.js"></script> -->
-<!-- <script src="https://cdn.jsdelivr.net/npm/@vonage/client-sdk@0.1.4/dist/vonageClientSDK.min.js"></script> -->
+<!-- <script src="https://cdn.jsdelivr.net/npm/@vonage/client-sdk@1.0.0/dist/vonageClientSDK.min.js"></script> -->
 <script src="./node_modules/@vonage/client-sdk/dist/vonageClientSDK.min.js"></script>
 <script>
-  const token = 'some-token';
+  const token = 'my-token';
   const client = new vonageClientSDK.VoiceClient();
   const config = new vonageClientSDK.ClientConfig(
     vonageClientSDK.ConfigRegion.EU
@@ -61,31 +84,160 @@ export default App;
 
 ```js
 import {
-  VoiceClient,
+  VonageClient,
   ClientConfig,
   ConfigRegion
-} from 'https://cdn.jsdelivr.net/npm/@vonage/client-sdk@0.1.4/dist/vonageClientSDK.esm.min.js';
+} from 'https://cdn.jsdelivr.net/npm/@vonage/client-sdk@1.0.0/dist/vonageClientSDK.esm.min.js';
 
-const client = new VoiceClient();
+const client = new VonageClient();
 
 // Config is optional but recomended, default region is US
 const config = new ClientConfig(ConfigRegion.US);
 client.setConfig(config);
 
-const token = 'my-token';
-client
-  .createSession(token)
-  .then((sessionId) => console.log(sessionId))
-  .catch((err) => console.log(err));
+(async () => {
+  const token = 'my-token';
+  try {
+    // Create Session
+    const sessionId = await client.createSession(token);
+    // Get User
+    const user = await client.getUser('me');
+    console.log(
+      `User ${
+        user.displayName || user.name
+      } logged in with session ID: ${sessionId}`
+    );
+  } catch (error) {
+    // Log errors for either createSession or getUser
+    console.error(error);
+  }
+})();
+```
+
+## Example Usage
+
+Below are several typical scenarios where the SDK is commonly utilized.
+
+### Make an Outbound Call
+
+```ts
+const call = await client.serverCall({
+  customData: {
+    callee: 'bob',
+    type: 'app'
+  }
+});
+console.log(call);
+```
+
+### Answer/Reject an Inbound Call
+
+```ts
+// Answer Call
+client.on(
+  'callInvite',
+  async (callId: string, from: string, channelType: string) => {
+    client.answerCall(callId);
+    console.log(callId, from, channelType);
+  }
+);
+
+// ----
+
+// Reject Call
+client.on(
+  'callInvite',
+  async (callId: string, from: string, channelType: string) => {
+    client.rejectCall(callId);
+    console.log(callId, from, channelType);
+  }
+);
+```  
+
+### Hang-up and Collect Stats
+
+```ts
+// await client.hangup(call);
+await client.hangup(call, 'reason-text', 'reason-code');
+
+client.on('callHangup', async (callId: string, callQuality: RTCQuality) => {
+  if (callId == call) {
+    console.log(`Call ${callId} has hanged up, callQuality:${callQuality}`);
+  }
+});
+```
+
+### Get Conversations
+
+```ts
+try {
+  let cursor: string | undefined | null = undefined;
+  const pageSize = 10;
+  const conversations: Conversation[] = [];
+  do {
+    const response: ConversationsPage = await client.getConversations(
+      PresentingOrder.ASC,
+      pageSize,
+      cursor
+    );
+    conversations.push(...response.conversations);
+    cursor = response.nextCursor;
+  } while (cursor !== null);
+  console.log(`Conversations successfully fetched: ${conversations}`);
+} catch (e) {
+  console.log(`Error in fetching Conversations: ${e}`);
+}
+```
+
+### Send Text Messages
+
+```ts
+try {
+  const timestamp = await client.sendTextMessage(
+    'conversationId',
+    'Hello there'
+  );
+  console.log(`Message successfully sent with timestamp ${timestamp}`);
+} catch (e) {
+  console.log(`Error in sending Message: ${e}`);
+}
+```
+
+### Listen for Conversation Events
+
+```ts
+client.on('conversationEvent', async (event) => {
+  if (event instanceof MemberInvitedEvent) {
+    console.log(
+      `User ${event.body.invitee.name} invited by ${event.body.inviter?.name} to Conversation ${event.conversationId}`
+    );
+  } else if (event instanceof MemberJoinedEvent) {
+    console.log(
+      `User ${event.body.user.name} joined Conversation ${event.conversationId}`
+    );
+  } else if (event instanceof MemberLeftEvent) {
+    console.log(
+      `User ${event.body.user.name} left Conversation ${event.conversationId}`
+    );
+  } else if (event instanceof TextMessageEvent) {
+    console.log(
+      `User ${event.body.sender.name} sent Text Message '${event.body.text}' in Conversation ${event.conversationId}`
+    );
+  } else if (event instanceof CustomMessageEvent) {
+    console.log(
+      `User ${event.body.sender} sent Custom Message '${event.body.customData}' in Conversation ${event.conversationId}`
+    );
+  }
+});
 ```
 
 ## Documentation and examples
 
-Visit [vonage website] (<https://developer.vonage.com/tools>)
+Visit [Vonage website](https://developer.vonage.com/tools)
 
 ## License
 
-Copyright (c) 2023 Vonage, Inc. All rights reserved. Licensed only under the Vonage Client SDK License Agreement (the "License") located at [LICENCE](https://github.com/nexmoinc/conversation-js-sdk/blob/master/LICENSE).
+Copyright (c) 2023 Vonage, Inc. All rights reserved. Licensed only under the Vonage Client SDK License Agreement (the "License") located at [LICENSE](https://github.com/nexmoinc/conversation-js-sdk/blob/master/LICENSE).
 
 By downloading or otherwise using our software or services, you acknowledge that you have read, understand and agree to be bound by the Vonage Client SDK License Agreement and Privacy Policy.
 

package/dist/client/VonageClient.d.ts

@@ -1,9 +1,16 @@
 import vonage from '../utils/vonage';
-export * from '../utils';
 /**
- * Minimal Interface built on top of KMP export
- * DO NOT ADD CODE HERE UNLESS REALLY NEEDEED!!111!
+ * 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';
 export type VonageEvent = vonage.CombinedEvents;
 export type RTCQuality = vonage.RTCQualityJS;
 export type CancelReason = vonage.CancelReasonJS;
@@ -12,13 +19,300 @@ export type HangupReason = vonage.HangupReasonJS;
 export declare const HangupReason: typeof vonage.HangupReasonJS;
 export type SessionErrorReason = vonage.SessionErrorReasonJS;
 export declare const SessionErrorReason: typeof vonage.SessionErrorReasonJS;
+export type Leg = vonage.LegJS;
 export type LegStatus = vonage.LegStatusJS;
 export declare const LegStatus: typeof vonage.LegStatusJS;
+export type CallSayParams = Partial<vonage.CallSayParams> & {
+    text: string;
+};
+type JSONValue = string | number | boolean | {
+    [x: string]: JSONValue;
+} | JSONValue[];
+import { Conversation, ConversationsPage, EventsPage, Member, MembersPage, PresentingOrder } from '../utils';
 export declare const setVonageClientLoggingLevel: typeof vonage.setDefaultLoggingLevel;
+/**
+ * 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 {
-    private callbacks;
     constructor();
-    on<T extends keyof VonageEvent, Fn extends VonageEvent[T]>(event: T, callback: Fn): void;
-    hangup(callId: string, reasonText?: string, reasonCode?: string): Promise<any>;
+    /**
+     * Register a callback for an event.
+     *
+     * @example
+     * [[include:register_listener.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
+     * Besure to store the symbol returned by this method so you can unregister the callback later.
+     * We recommend deregistering callbacks when you no longer need them. See {@link off}.
+     */
+    on<T extends keyof VonageEvent, Fn extends VonageEvent[T]>(event: T, callback: Fn): symbol;
+    /**
+     * Unregister a callback for an event.
+     *
+     * @example
+     * [[include:unregister_listener.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: clear_callbacks.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:create_session.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 Leg for a call
+     *
+     * @group Voice
+     * @param legId - The Leg Id
+     */
+    getLeg(legId: string): Promise<Leg>;
+    /**
+     * Make a server call to the Vonage API.
+     * This is used to initiate a call using the Voice API and NCCO.
+     *
+     * @example
+     * [[include:outbound_call.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:call_hangup.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:call_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:get_conversations.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param order - the order to return the conversations in (default: 'asc')
+     * @param pageSize - the number of conversations to return per page (default: 100)
+     * @param cursor - the cursor to use for pagination (default: null)
+     * @returns a `ConversationsPage` containing the conversations
+     */
+    getConversations(order?: PresentingOrder, pageSize?: number, cursor?: string | null): Promise<ConversationsPage>;
+    /**
+     * Get a Conversation's Events
+     *
+     * @example
+     * [[include:get_conversation_events.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @param order - the order to return the events in (default: 'asc')
+     * @param pageSize - the number of events to return per page (default: 100)
+     * @param cursor - the cursor to use for pagination (default: null)
+     * @returns a `EventsPage` containing the events
+     */
+    getConversationEvents(id: string, order?: PresentingOrder, pageSize?: number, cursor?: string | null): Promise<EventsPage>;
+    /**
+     * Get a Conversation's Members
+     *
+     * @example
+     * [[include:get_conversation_members.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @param order - the order to return the members in (default: 'asc')
+     * @param pageSize - the number of members to return per page (default: 100)
+     * @param cursor - the cursor to use for pagination (default: null)
+     * @returns a `MembersPage` containing the members
+     */
+    getConversationMembers(id: string, order?: PresentingOrder, pageSize?: number, cursor?: string | null): Promise<MembersPage>;
+    /**
+     * Create a conversation
+     *
+     * @example
+     * [[include:create_conversation.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param name - the name of the conversation
+     * @param displayName - the display name of the conversation
+     * @returns the `cid` of the conversation
+     */
+    createConversation(name?: string, displayName?: string): Promise<string>;
+    /**
+     * Get a Conversation
+     *
+     * @example
+     * [[include:get_conversation.txt]]
+     *
+     * @param id - the Conversation's id
+     * @returns the `Conversation`
+     */
+    getConversation(cid: string): Promise<Conversation>;
+    /**
+     * Leave a Conversation
+     *
+     * @example
+     * [[include:leave_conversation.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @returns void
+     */
+    leaveConversation(id: string): Promise<void>;
+    /**
+     * Join a Conversation
+     *
+     * @example
+     * [[include:join_conversation.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @returns the `memberId` of the member
+     */
+    joinConversation(id: string): Promise<string>;
+    /**
+     * Delete a Conversation
+     *
+     * @example
+     * [[include:delete_conversation.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @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:invite_to_conversation.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @param name - the namne 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:send_text_message.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @param text - the Body of the message
+     * @returns the `timestamp` of the message
+     */
+    sendTextMessage(id: string, text: string): Promise<string>;
+    /**
+     * Send a custom message to a Conversation
+     *
+     * @example
+     * [[include:send_custom_message.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param id - the Conversation's id
+     * @param customData - the body of the message
+     * @returns the `timestamp` of the message
+     */
+    sendCustomMessage(id: string, customData: JSONValue): Promise<string>;
+    /**
+     * Get a Member of a Conversation
+     *
+     * @example
+     * [[include:get_conversation_member.txt]]
+     *
+     * @group Chat
+     * @beta
+     * @param cid - the Conversation's id
+     * @param mid - the Member's id
+     * @returns the `Member`
+     */
+    getConversationMember(cid: string, mid: string): Promise<Member>;
 }
 export default VonageClient;