@signalwire/js 3.7.1-dev.202201311747.da5ddf5.0 → 3.9.0

package/src/BaseRoomSession.ts

@@ -41,6 +41,7 @@ import {
   RoomSessionDeviceConnection,
   RoomSessionDevice,
 } from './RoomSessionDevice'
+import * as workers from './video/workers'
 
 export interface BaseRoomSession<T>
   extends RoomMethods,
@@ -120,6 +121,20 @@ export class RoomSessionConnection
     ])
   }
 
+  /**
+   * This method will be called by `join()` right before the
+   * `connect()` happens and it's a way for us to control
+   * exactly when the workers are attached.
+   * @internal
+   */
+  protected attachPreConnectWorkers() {
+    this.setWorker('memberListUpdated', {
+      worker: workers.memberListUpdatedWorker,
+    })
+
+    this.attachWorkers()
+  }
+
   /** @deprecated Use {@link startScreenShare} instead. */
   async createScreenShareObject(opts: CreateScreenShareObjectOptions = {}) {
     return this.startScreenShare(opts)
@@ -129,7 +144,13 @@ export class RoomSessionConnection
    * Allow sharing the screen within the room.
    */
   async startScreenShare(opts: StartScreenShareOptions = {}) {
-    const { autoJoin = true, audio = false, video = true } = opts
+    const {
+      autoJoin = true,
+      audio = false,
+      video = true,
+      layout,
+      positions,
+    } = opts
     const displayStream: MediaStream = await getDisplayMedia({
       audio: audio === true ? SCREENSHARE_AUDIO_CONSTRAINTS : audio,
       video,
@@ -145,6 +166,8 @@ export class RoomSessionConnection
         memberCallId: this.__uuid,
         memberId: this.memberId,
       },
+      layout,
+      positions,
     }
 
     const screenShare = connect<
@@ -329,6 +352,8 @@ export const RoomSessionAPI = extendComponent<
   getMembers: Rooms.getMembers,
   getLayouts: Rooms.getLayouts,
   setLayout: Rooms.setLayout,
+  // setPositions: Rooms.setPositions,
+  // setMemberPosition: Rooms.setMemberPosition,
   hideVideoMuted: Rooms.hideVideoMuted,
   showVideoMuted: Rooms.showVideoMuted,
   getRecordings: Rooms.getRecordings,

package/src/RoomSession.docs.ts

@@ -1,14 +1,15 @@
-import type { Rooms } from '@signalwire/core'
+import type { AssertSameType, VideoPositions, Rooms } from '@signalwire/core'
 import { BaseRoomSession } from './BaseRoomSession'
 import { RoomSessionDevice } from './RoomSessionDevice'
 import { RoomSessionScreenShare } from './RoomSessionScreenShare'
+import { StartScreenShareOptions } from './utils/interfaces'
 
 export interface RoomSessionDocs<T>
   extends RoomMemberMethodsInterfaceDocs,
     RoomControlMethodsInterfaceDocs,
     RoomLayoutMethodsInterface,
     RoomSessionConstructorDocs<T>,
-    Pick<BaseRoomSession<T>, 'on' | 'off' | 'once'> {
+    Pick<BaseRoomSession<T>, 'on' | 'off' | 'once' | 'removeAllListeners'> {
   /** @internal */
   stopOutboundAudio(): void
   /** @internal */
@@ -116,17 +117,26 @@ export interface RoomSessionDocs<T>
    *
    * @example Sharing the screen together with the associated audio:
    * ```typescript
-   * await roomSession.startScreenShare({audio: true, video: true})
+   * await roomSession.startScreenShare({ audio: true, video: true })
    * ```
    */
-  startScreenShare(opts: {
-    /** Whether the screen share object should automatically join the room */
-    autoJoin?: boolean
-    /** Audio constraints to use when joining the room. Default: `true`. */
-    audio?: MediaStreamConstraints['audio']
-    /** Video constraints to use when joining the room. Default: `true`. */
-    video?: MediaStreamConstraints['video']
-  }): Promise<RoomSessionScreenShare>
+  startScreenShare(
+    opts: AssertSameType<
+      StartScreenShareOptions,
+      {
+        /** Whether the screen share object should automatically join the room. Default: `true`. */
+        autoJoin?: boolean
+        /** Audio constraints to use when joining the room. Default: `false`. */
+        audio?: MediaStreamConstraints['audio']
+        /** Video constraints to use when joining the room. Default: `true`. */
+        video?: MediaStreamConstraints['video']
+        /** Layout to use to use when joining the room. */
+        layout?: string
+        /** Automatically set positions when screen share joins the room. */
+        positions?: VideoPositions
+      }
+    >
+  ): Promise<RoomSessionScreenShare>
 
   /**
    * Adds a camera device to the room. Using this method, a user can stream
@@ -839,6 +849,10 @@ interface RoomControlMethodsInterfaceDocs {
   play(params: {
     url: string
     volume?: number
+    // positions?: Record<
+    //   string,
+    //   'self' | 'standard' | `standard-${number}` | 'off-canvas'
+    // >
   }): Promise<Rooms.RoomSessionPlayback>
 }
 
@@ -887,7 +901,32 @@ interface RoomLayoutMethodsInterface {
    * await room.setLayout({name: "6x6"})
    * ```
    */
-  setLayout(params: { name: string }): Rooms.SetLayout
+  setLayout(params: {
+    name: string
+    // positions?: Record<
+    //   string,
+    //   'self' | 'standard' | `standard-${number}` | 'off-canvas'
+    // >
+  }): Rooms.SetLayout
+
+  // setPositions(params: {
+  //   positions: Record<
+  //     string,
+  //     | 'self'
+  //     | 'standard'
+  //     | `standard-${number}`
+  //     | 'off-canvas'
+  //   >
+  // }): Promise<void>
+
+  // setMemberPosition(params: {
+  //   memberId?: string
+  //   position:
+  //     | 'self'
+  //     | 'standard'
+  //     | `standard-${number}`
+  //     | 'off-canvas'
+  // }): Promise<void>
 }
 
 /**
@@ -902,7 +941,7 @@ export interface RoomSessionEvents {
    *
    * ```typescript
    * type _ = {
-   *   room: {
+   *   room_session: {
    *     room_session_id: string,
    *     logos_visible: boolean,
    *     members: Array<{
@@ -1094,6 +1133,15 @@ export interface RoomSessionEvents {
    */
   'member.talking': undefined
 
+  /**
+   * The set of members or one or more properties of a member have changed. The
+   * event handler receives an object `e` with the updated, full list of members in
+   * the room as `e.members`.
+   *
+   * @event
+   */
+  'memberList.updated': undefined
+
   /**
    * The layout of the room has changed. This event is not limited to changes
    * associated to the grid layout of the room: it also includes for example

package/src/RoomSession.ts

@@ -1,4 +1,8 @@
-import { UserOptions, AssertSameType, getLogger } from '@signalwire/core'
+import {
+  UserOptions,
+  AssertSameType,
+  getLogger,
+} from '@signalwire/core'
 import { createClient } from './createClient'
 import type { MakeRoomOptions } from './Client'
 import { BaseRoomSession } from './BaseRoomSession'
@@ -27,6 +31,8 @@ export const UNSAFE_PROP_ACCESS = [
   'setInputSensitivity',
   'setInputVolume',
   'setLayout',
+  'setPositions',
+  'setMemberPosition',
   'setOutputVolume',
   'showVideoMuted',
   'startRecording',
@@ -123,6 +129,9 @@ export const RoomSession = function (roomOptions: RoomSessionOptions) {
   const join = () => {
     return new Promise(async (resolve, reject) => {
       try {
+        // @ts-expect-error
+        room.attachPreConnectWorkers()
+
         await client.connect()
 
         room.once('room.subscribed', () => {
@@ -137,10 +146,15 @@ export const RoomSession = function (roomOptions: RoomSessionOptions) {
     })
   }
 
+  const interceptors = {
+    join,
+  } as const
+
   return new Proxy<Omit<RoomSession, 'new'>>(room, {
-    get(target: RoomSession, prop: any, receiver: any) {
-      if (prop === 'join') {
-        return join
+    get(target: RoomSession, prop: keyof RoomSession, receiver: any) {
+      if (prop in interceptors) {
+        // @ts-expect-error
+        return interceptors[prop]
       }
 
       if (!target.active && UNSAFE_PROP_ACCESS.includes(prop)) {

package/src/chat/Client.docs.ts

@@ -0,0 +1,259 @@
+import type { ConsumerContract, Chat } from '@signalwire/core'
+
+import type { ClientApiEvents, ClientFullState } from './Client'
+
+export type PagingCursor =
+  | {
+      before: string
+      after?: never
+    }
+  | {
+      before?: never
+      after: string
+    }
+
+export interface ClientDocs
+  extends Omit<
+    ConsumerContract<ClientApiEvents, ClientFullState>,
+    'subscribe'
+  > {
+  /**
+   * Creates a new Chat client.
+   *
+   * @example
+   *
+   * ```js
+   * import { Chat } from '@signalwire/js'
+   *
+   * const chatClient = new Chat.Client({
+   *   token: '<your_chat_token>',
+   * })
+   * ```
+   */
+  new (chatOptions: {
+    /** SignalWire Chat token (you can get one with the REST APIs) */
+    token: string
+    /** @ignore */
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  }): this
+
+  /**
+   * Replaces the token used by the client with a new one. You can use this
+   * method to replace the token when for example it is expiring, in order to
+   * keep the session alive.
+   *
+   * The new token can contain different channels from the previous one. In that
+   * case, you will need to subscribe to the new channels if you want to receive
+   * messages for those. Channels that were in the previous token but are not in
+   * the new one will get unsubscribed automatically.
+   *
+   * @param token the new token.
+   *
+   * @example
+   * ```js
+   * const chatClient = new Chat.Client({
+   *   token: '<your chat token>'
+   * })
+   *
+   * chatClient.on('session.expiring', async () => {
+   *   const newToken = await fetchNewToken(..)
+   *
+   *   await chatClient.updateToken(newToken)
+   * })
+   * ```
+   */
+  updateToken(token: string): Promise<void>
+
+  /**
+   * List of channels for which you want to receive messages. You can only
+   * subscribe to those channels for which your token has read permission.
+   *
+   * Note that the `subscribe` function is idempotent, and calling it again with
+   * a different set of channels _will not_ unsubscribe you from the old ones.
+   * To unsubscribe, use {@link unsubscribe}.
+   *
+   * @param channels the channels to subscribe to, either in the form of a
+   * string (for one channel) or an array of strings.
+   *
+   * @example
+   * ```js
+   * const chatClient = new Chat.Client({
+   *   token: '<your chat token>'
+   * })
+   *
+   * chatClient.on('message', m => console.log(m))
+   *
+   * await chatClient.subscribe("my-channel")
+   * await chatClient.subscribe(["chan-2", "chan-3"])
+   * ```
+   */
+  subscribe(channels: string | string[]): Promise<any>
+
+  /**
+   * List of channels from which you want to unsubscribe.
+   *
+   * @param channels the channels to unsubscribe from, either in the form of a
+   * string (for one channel) or an array of strings.
+   *
+   * @example
+   * ```js
+   * await chatClient.unsubscribe("my-channel")
+   * await chatClient.unsubscribe(["chan-2", "chan-3"])
+   * ```
+   */
+  unsubscribe(channels: string | string[]): Promise<any>
+
+  /**
+   * Publish a message into the specified channel.
+   *
+   * @example Publishing a message as a string:
+   * ```js
+   * await chatClient.publish({
+   *   channel: 'my-channel',
+   *   content: 'Hello, world.'
+   * })
+   * ```
+   *
+   * @example Publishing a message as an object:
+   * ```js
+   * await chatClient.publish({
+   *   channel: 'my-channel',
+   *   content: {
+   *     field_one: 'value_one',
+   *     field_two: 'value_two',
+   *   }
+   * })
+   * ```
+   */
+  publish(params: {
+    /** The message to send. This can be any JSON-serializable object. */
+    content: any
+    /** Channel in which to send the message. */
+    channel: string
+    /**
+     * Metadata associated with the message. There are no requirements on the
+     * content of metadata.
+     */
+    meta?: Record<any, any>
+  }): Promise<any>
+
+  /**
+   * Returns the list of messages that were sent to the specified channel.
+   *
+   * @example
+   * ```js
+   * const m = await chatClient.getMessages({ channel: 'chan1' })
+   *
+   * m.messages.length;  // 23
+   * m.messages[0];  // the most recent message
+   * m.messages[0].member;  // the sender
+   * m.messages[0].content;  // the content
+   * m.messages[0].meta;  // the metadata (if any)
+   *
+   * m.cursor.next;  // if not null, there are more messages.
+   *
+   * // Get the next page using the cursor
+   * const next = await chatClient.getMessages({
+   *   channel: 'chan1',
+   *   cursor: {
+   *     after: m.cursor.after
+   *   }
+   * })
+   * ```
+   */
+  getMessages(params: {
+    /** Channel for which to retrieve the messages. */
+    channel: string
+    /** Cursor for pagination. */
+    cursor?: PagingCursor
+  }): Promise<any>
+
+  /**
+   * Returns the list of members in the given channel.
+   *
+   * @example
+   * ```js
+   * const m = await chatClient.getMembers({ channel: 'my-channel' })
+   *
+   * m.members.length;  // 7
+   * m.members[0];  // { id: ..., channel: ..., state: ... }
+   * ```
+   */
+  getMembers(params: {
+    /** The channel for which to get the list of members. */
+    channel: string
+  }): Promise<any>
+
+  /**
+   * Sets a state object for the current member, for the specified channels. The
+   * previous state object will be completely replaced.
+   *
+   * @example
+   * ```js
+   * await chatClient.setMemberState({
+   *   channels: ['chan1', 'chan2'],
+   *   state: {
+   *     online: true,
+   *     typing: false
+   *   }
+   * })
+   * ```
+   */
+  setMemberState(params: {
+    /** Channels for which to set the state. */
+    channels: string | string[]
+    /**
+     * The state to set. There are no requirements on the content of the state.
+     */
+    state: Record<any, any>
+  }): Promise<any>
+
+  /**
+   * Returns the states of a member in the specified channels.
+   *
+   * @example
+   * ```js
+   * const s = await chatClient.getMemberState({
+   *   channels: ['chan1', 'chan2'],
+   *   memberId: 'my-member-id'
+   * })
+   *
+   * s.channels.length;  // 2
+   * s.channels.chan1.state;  // the state object for chan1
+   * ```
+   */
+  getMemberState(params: {
+    /** Channels for which to get the state. */
+    channels: string | string[]
+    /** Id of the member for which to get the state. */
+    memberId: string
+  }): Promise<any>
+}
+
+export interface ClientApiEventsDocs {
+  /**
+   * The session is going to expire.
+   * Use the `updateToken` method to refresh your token.
+   */
+  'session.expiring': () => void
+
+  /**
+   * A new message has been received.
+   */
+  message: (message: Chat.ChatMessage) => void
+
+  /**
+   * A new member joined the chat.
+   */
+  'member.joined': (member: Chat.ChatMember) => void
+
+  /**
+   * A member updated its state.
+   */
+  'member.updated': (member: Chat.ChatMember) => void
+
+  /**
+   * A member left the chat.
+   */
+  'member.left': (member: Chat.ChatMember) => void
+}

package/src/chat/Client.ts

@@ -5,29 +5,56 @@ import type {
   UserOptions,
   Chat as ChatNamespace,
 } from '@signalwire/core'
-import { getLogger } from '@signalwire/core'
 import { createClient } from '../createClient'
+import { ClientApiEventsDocs, ClientDocs } from './Client.docs'
 
-export interface ClientApiEvents extends ChatNamespace.BaseChatApiEvents {}
+interface ClientApiEventsMain extends ChatNamespace.BaseChatApiEvents {}
+export interface ClientApiEvents
+  extends AssertSameType<ClientApiEventsMain, ClientApiEventsDocs> {}
 
+/** @ignore */
 export interface ClientFullState extends Client {}
 interface ClientMain
   extends ChatContract,
     Omit<ConsumerContract<ClientApiEvents, ClientFullState>, 'subscribe'> {}
 
-interface ClientDocs extends ClientMain {}
-
+/**
+ * You can use the Client object to build a messaging system into the browser.
+ *
+ * Example usage:
+ *
+ * ```js
+ * import { Chat } from '@signalwire/js'
+ *
+ * const chatClient = new Chat.Client({
+ *   token: '<your_chat_token>',  // get this from the REST APIs
+ * })
+ *
+ * await chatClient.subscribe([ 'mychannel1', 'mychannel2' ])
+ *
+ * chatClient.on('message', (message) => {
+ *   console.log("Received", message.content,
+ *               "on", message.channel,
+ *               "at", message.publishedAt)
+ * })
+ *
+ * await chatClient.publish({
+ *   channel: 'mychannel1',
+ *   content: 'hello world'
+ * })
+ * ```
+ *
+ * ## Events
+ *
+ * Please see {@link ClientApiEvents} for the list of events emitted by a chat
+ * Client object.
+ */
 export interface Client extends AssertSameType<ClientMain, ClientDocs> {}
 
+/** @ignore */
 export interface ClientOptions extends UserOptions {}
 
 export const Client = function (chatOptions: ClientOptions) {
-  if ('production' === process.env.NODE_ENV) {
-    getLogger().warn(
-      '`Chat` is still under development and may change in the future without prior notice.'
-    )
-  }
-
   const client = createClient<Client>(chatOptions)
   const subscribe: Client['subscribe'] = async (channels) => {
     await client.connect()

package/src/chat/index.ts

@@ -1 +1,11 @@
+import { Chat } from '@signalwire/core'
+import ChatMember = Chat.ChatMember
+import ChatMessage = Chat.ChatMessage
+
 export * from './Client'
+export { PagingCursor } from './Client.docs'
+
+export {
+  ChatMember,
+  ChatMessage,
+}

package/src/index.ts

@@ -2,18 +2,19 @@
  * Welcome to the technical documentation for the JavaScript SDK.
  *
  * At the outer level, when you import the SignalWire JS library you get access
- * to two different namespaces:
+ * to three different namespaces:
  *
  *  - {@link Video}
+ *  - {@link Chat}
  *  - {@link WebRTC}
  *
- * {@link Video} gives you access to the classes and methods that let you
- * interface with the backend Video APIs. {@link WebRTC} contains several
- * functions that are useful for interacting with the hardware of the user's
- * device.
+ * Video gives you access to the classes and methods that let you
+ * interface with the backend Video APIs. Chat gives you access to the classes and functions that you need to create a real-time chat application. WebRTC  
+ * contains several functions that are useful for interacting with the hardware of the user's device.
+ * 
  *
- * You don't know where to start? Create an instance of
- * {@link Video.RoomSession} to join a room, or take a look at [Getting Started
+ * Don't know where to start? Create an instance of
+ * {@link Video.RoomSession} to join a room, use the {@link Chat.Client} constructor to start a chat application, or take a look at [Getting Started
  * with the SignalWire Video
  * API](https://developer.signalwire.com/apis/docs/getting-started-with-the-signalwire-video-api-1).
  *
@@ -46,6 +47,12 @@ export type RoomScreenShare = VideoMemberEntity & { type: 'screen' }
 /** @ignore @deprecated */
 export type RoomDevice = VideoMemberEntity & { type: 'device' }
 
+/**
+ * The Chat namespace contains the classes and functions that you need to
+ * create a real-time chat application.
+ */
+export * as Chat from './chat'
+
 /**
  * The Video namespace contains the classes and functions that you need to
  * create a video conferencing application.
@@ -96,6 +103,3 @@ export type {
   RoomSessionObjectEventsHandlerMap as RoomObjectEventsHandlerMap,
   RoomSessionObjectEvents as RoomObjectEvents,
 } from './utils/interfaces'
-
-/** @internal */
-export * as __sw__Chat from './chat'

package/src/utils/interfaces.ts

@@ -5,7 +5,6 @@ import type {
   VideoLayoutEventNames,
   VideoRoomSessionEventNames,
   VideoRoomEventParams,
-  VideoMemberEntity,
   InternalVideoMemberEntity,
   VideoMemberEventNames,
   MemberUpdated,
@@ -22,6 +21,8 @@ import type {
   VideoRoomSessionContract,
   OnlyFunctionProperties,
   AssertSameType,
+  MemberListUpdated,
+  VideoPositions,
 } from '@signalwire/core'
 import { INTERNAL_MEMBER_UPDATABLE_PROPS } from '@signalwire/core'
 import type { RoomSession } from '../RoomSession'
@@ -29,6 +30,18 @@ import type { RoomSessionDevice } from '../RoomSessionDevice'
 import type { RoomSessionScreenShare } from '../RoomSessionScreenShare'
 import { RoomMemberSelfMethodsInterfaceDocs } from './interfaces.docs'
 
+/**
+ * @privateRemarks
+ * Every other package exposing a `VideoMemberEntity` is
+ * transforming the server payload into something else, with
+ * the most significant change being converting properties
+ * from snake to camel case. The `js` package, on the other
+ * hand, exposes the server payload pretty much as is (as as
+ * v3) so what we consider internal (sdk and server) in
+ * other packages is external (user facing) for `js`.
+ */
+type VideoMemberEntity = InternalVideoMemberEntity
+
 const INTERNAL_MEMBER_UPDATED_EVENTS = Object.keys(
   INTERNAL_MEMBER_UPDATABLE_PROPS
 ).map((key) => {
@@ -47,19 +60,27 @@ export type VideoMemberHandlerParams = { member: VideoMemberEntity }
 export type VideoMemberUpdatedHandlerParams = {
   member: VideoMemberEntityUpdated
 }
+export type VideoMemberListUpdatedParams = { members: VideoMemberEntity[] }
 
 export type RoomSessionObjectEventsHandlerMap = Record<
   VideoLayoutEventNames,
   (params: { layout: VideoLayout }) => void
 > &
   Record<
-    Exclude<VideoMemberEventNames, MemberUpdated | MemberUpdatedEventNames>,
+    Exclude<
+      VideoMemberEventNames,
+      MemberUpdated | MemberUpdatedEventNames | MemberListUpdated
+    >,
     (params: VideoMemberHandlerParams) => void
   > &
   Record<
     Extract<VideoMemberEventNames, MemberUpdated | MemberUpdatedEventNames>,
     (params: VideoMemberUpdatedHandlerParams) => void
   > &
+  Record<
+    Extract<VideoMemberEventNames, MemberListUpdated>,
+    (params: VideoMemberListUpdatedParams) => void
+  > &
   Record<
     DeprecatedMemberUpdatableProps,
     (params: DeprecatedVideoMemberHandlerParams) => void
@@ -82,6 +103,8 @@ export type StartScreenShareOptions = {
   autoJoin?: boolean
   audio?: MediaStreamConstraints['audio']
   video?: MediaStreamConstraints['video']
+  layout?: string
+  positions?: VideoPositions
 }
 
 /**