@signalwire/js 3.7.1-dev.202201131750.6d234cc.0 → 3.8.0

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',
+   *   message: 'Hello, world.'
+   * })
+   * ```
+   *
+   * @example Publishing a message as an object:
+   * ```js
+   * await chatClient.publish({
+   *   channel: 'my-channel',
+   *   message: {
+   *     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.test.ts

@@ -128,7 +128,7 @@ describe('ChatClient Object', () => {
     await chat.subscribe(['test'])
     await chat.publish({
       channel: 'test',
-      message: 'test',
+      content: 'test',
     })
 
     const connectMsg = JSON.parse(server.messages[0].toString())
@@ -147,7 +147,7 @@ describe('ChatClient Object', () => {
       chat.subscribe(['test']),
       chat.publish({
         channel: 'test',
-        message: 'test',
+        content: 'test',
       }),
     ])
 
@@ -390,7 +390,7 @@ describe('ChatClient Object', () => {
 
       const params = {
         channel: 'test',
-        message: 'test',
+        content: 'test',
       }
 
       await chat.publish(params)
@@ -476,7 +476,7 @@ describe('ChatClient Object', () => {
       // calling unsubscribe()
       await chat.publish({
         channel: 'test',
-        message: 'test',
+        content: 'test',
       })
 
       await expect(() => chat.unsubscribe(['test1_error'])).rejects.toBeTruthy()

package/src/chat/Client.ts

@@ -7,18 +7,54 @@ import type {
 } 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',
+ *   message: '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) {

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

@@ -46,6 +46,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 +102,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,7 @@ import type {
   VideoRoomSessionContract,
   OnlyFunctionProperties,
   AssertSameType,
+  MemberListUpdated,
 } from '@signalwire/core'
 import { INTERNAL_MEMBER_UPDATABLE_PROPS } from '@signalwire/core'
 import type { RoomSession } from '../RoomSession'
@@ -29,6 +29,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 +59,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

package/src/video/memberListUpdatedWorker.ts

@@ -0,0 +1,217 @@
+import {
+  sagaEffects,
+  SagaIterator,
+  SDKWorker,
+  toSyntheticEvent,
+  validateEventsToSubscribe,
+  toInternalEventName,
+  PubSubChannel,
+  InternalVideoMemberEntity,
+  InternalVideoMemberUpdatedEvent,
+  VideoMemberJoinedEvent,
+  VideoMemberLeftEvent,
+  VideoMemberUpdatedEvent,
+  InternalVideoRoomJoinedEvent,
+  MapToPubSubShape,
+} from '@signalwire/core'
+import type { RoomSession } from '../RoomSession'
+import type { VideoMemberListUpdatedParams } from '../utils/interfaces'
+
+const noop = () => {}
+
+const EXTERNAL_MEMBER_LIST_UPDATED_EVENT = 'video.memberList.updated'
+
+const INTERNAL_MEMBER_LIST_UPDATED_EVENT = toInternalEventName({
+  event: EXTERNAL_MEMBER_LIST_UPDATED_EVENT,
+})
+
+const SYNTHETIC_MEMBER_LIST_UPDATED_EVENT = toSyntheticEvent(
+  INTERNAL_MEMBER_LIST_UPDATED_EVENT
+)
+
+/**
+ * List of action types this worker cares about.
+ */
+type MemberListUpdatedTargetActions = MapToPubSubShape<
+  | InternalVideoRoomJoinedEvent
+  | InternalVideoMemberUpdatedEvent
+  | VideoMemberJoinedEvent
+  | VideoMemberLeftEvent
+  | VideoMemberUpdatedEvent
+>
+
+const MEMBER_LIST_EVENTS: Array<MemberListUpdatedTargetActions['type']> = [
+  /** Alias to `video.room.subscribed` */
+  'video.room.joined',
+  'video.member.joined',
+  'video.member.left',
+  'video.member.updated',
+]
+
+type MemberList = Map<string, InternalVideoMemberEntity>
+
+const isMemberListEvent = (
+  event: string
+): event is MemberListUpdatedTargetActions['type'] => {
+  // @ts-expect-error
+  return MEMBER_LIST_EVENTS.includes(event)
+}
+
+const getMemberListEventsToSubscribe = (subscriptions: MemberListUpdatedTargetActions['type'][]) => {
+  return validateEventsToSubscribe(MEMBER_LIST_EVENTS).filter((event) => {
+    return !subscriptions.includes(event)
+  })
+}
+
+const shouldHandleMemberList = (subscriptions: string[]) => {
+  return subscriptions.some((event) =>
+    event.includes(INTERNAL_MEMBER_LIST_UPDATED_EVENT)
+  )
+}
+
+const getMembersFromAction = (action: MemberListUpdatedTargetActions) => {
+  if (action.type === 'video.room.joined') {
+    return action.payload.room_session.members
+  }
+
+  return [action.payload.member]
+}
+
+export const getUpdatedMembers = ({
+  action,
+  memberList,
+}: {
+  action: MemberListUpdatedTargetActions
+  memberList: MemberList
+}) => {
+  const actionMembers = getMembersFromAction(action)
+
+  switch (action.type) {
+    case 'video.member.left':
+      actionMembers.forEach((member: InternalVideoMemberEntity) => {
+        memberList.delete(member.id)
+      })
+      break
+    default:
+      actionMembers.forEach((member: InternalVideoMemberEntity) => {
+        memberList.set(member.id, member)
+      })
+  }
+
+  return Array.from(memberList.values())
+}
+
+const initMemberListSubscriptions = (
+  room: RoomSession,
+  subscriptions: MemberListUpdatedTargetActions['type'][]
+) => {
+  const events = getMemberListEventsToSubscribe(subscriptions)
+
+  events.forEach((event) => {
+    /**
+     * Params to `subscribe` come from the event handlers
+     * the user has attached so to make sure we subscribe to
+     * all the appropiate events needed for
+     * `memberList.updated` to work, we must subscribe to
+     * the required events. We don't need to act upon the
+     * event (that's why we attach a `noop`), just to
+     * register it (`subscribe` gets its values from
+     * `BaseComponent.getSubscriptions`, which gets
+     * populated by each of the  event handlers the user
+     * attached).
+     */
+    room.once(event as any, noop)
+  })
+
+  /**
+   * This handler will act as a simple bridge between
+   * synthetic events and external events.
+   */
+  const eventBridgeHandler = ({ members }: VideoMemberListUpdatedParams) => {
+    // @ts-expect-error
+    room.emit(EXTERNAL_MEMBER_LIST_UPDATED_EVENT, { members })
+  }
+
+  // @ts-expect-error
+  room.on(SYNTHETIC_MEMBER_LIST_UPDATED_EVENT, eventBridgeHandler)
+
+  /**
+   * Any events attached by the saga should be specified
+   * here so it can be cleaned up when needed.
+   */
+  const cleanup = () => {
+    // @ts-expect-error
+    room.off(SYNTHETIC_MEMBER_LIST_UPDATED_EVENT, eventBridgeHandler)
+  }
+
+  return {
+    cleanup,
+  }
+}
+
+function* membersListUpdatedWatcher({
+  pubSubChannel,
+}: {
+  pubSubChannel: PubSubChannel
+}): SagaIterator {
+  const memberList: MemberList = new Map()
+
+  function* worker(pubSubAction: MemberListUpdatedTargetActions) {
+    const roomSessionId =
+      pubSubAction.type === 'video.room.joined'
+        ? pubSubAction.payload.room_session.id
+        : pubSubAction.payload.room_session_id
+
+    const members = getUpdatedMembers({ action: pubSubAction, memberList })
+    const memberListPayload = {
+      /**
+       * At this point it's needed to send the
+       * `room_session_id` so the pubSubSaga can properly
+       * infer the namespace for emitting the events to the
+       * appropiate room.
+       */
+      room_session_id: roomSessionId,
+      members,
+    }
+
+    // TODO: add typings
+    yield sagaEffects.put(pubSubChannel, {
+      type: SYNTHETIC_MEMBER_LIST_UPDATED_EVENT as any,
+      payload: memberListPayload as any,
+    })
+  }
+
+  while (true) {
+    const pubSubAction: MemberListUpdatedTargetActions = yield sagaEffects.take(
+      pubSubChannel,
+      ({ type }: any) => {
+        return isMemberListEvent(type)
+      }
+    )
+
+    yield sagaEffects.fork(worker, pubSubAction)
+  }
+}
+
+export const memberListUpdatedWorker: SDKWorker<RoomSession> =
+  function* membersChangedWorker({
+    channels: { pubSubChannel },
+    instance,
+  }): SagaIterator {
+    // @ts-expect-error
+    const subscriptions = instance.getSubscriptions()
+
+    if (!shouldHandleMemberList(subscriptions)) {
+      return
+    }
+
+    const { cleanup } = initMemberListSubscriptions(instance, subscriptions)
+
+    yield sagaEffects.fork(membersListUpdatedWatcher, {
+      pubSubChannel,
+    })
+
+    instance.once('destroy', () => {
+      cleanup()
+    })
+  }

package/src/video/workers.ts

@@ -0,0 +1 @@
+export * from "./memberListUpdatedWorker"