@linktr.ee/messaging-react 3.6.1 → 3.7.0-rc-1783304153

package/src/testing/createMockMessagingClient.ts

@@ -0,0 +1,231 @@
+import type {
+  Channel,
+  MessageResponse,
+  QueryChannelAPIResponse,
+  SendMessageAPIResponse,
+} from 'stream-chat'
+import { StreamChat } from 'stream-chat'
+
+/** A participant in the mock conversation. */
+export interface MockMessagingUser {
+  id: string
+  name?: string
+  image?: string
+}
+
+/**
+ * A seed message, authored from the viewer's perspective. `from: 'me'` is the
+ * connected user (the viewer); `from: 'them'` is the other participant.
+ */
+export interface MockMessage {
+  id?: string
+  text?: string
+  from: 'me' | 'them'
+  /** Stream attachment payloads, rendered by the toolkit's attachment gate. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  attachments?: any[]
+  /** e.g. `{ custom_type: 'MESSAGE_WELCOME' }`. */
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateMockMessagingClientOptions {
+  /** The connected/viewing user. */
+  currentUser: MockMessagingUser
+  /** The other party in the direct conversation (e.g. the creator/linker). */
+  participant: MockMessagingUser
+  /** Seed conversation, oldest-first. */
+  messages?: MockMessage[]
+  /** Channel id; defaults to `mock-dm`. */
+  channelId?: string
+  /**
+   * Optional canned reply. Called after the viewer sends a message; return the
+   * reply text (or a partial message) to have `participant` echo a response, or
+   * a falsy value for no reply. Drives the "send echo" in `dev:mock-messaging`.
+   */
+  onSend?: (
+    text: string
+  ) => string | { text?: string; attachments?: unknown[] } | null | undefined
+}
+
+export interface MockMessagingClient {
+  /** Pass to `<MessagingProvider client={...}>`. */
+  client: StreamChat
+  /** The seeded direct-conversation channel. */
+  channel: Channel
+  /** Pass to `<MessagingShell initialParticipantFilter={...}>`. */
+  participantFilterId: string
+}
+
+const REPLY_DELAY_MS = 600
+
+/**
+ * Builds an offline Stream client seeded with a single direct conversation, so
+ * consumers can render the **real** messaging UI (MessagingProvider →
+ * MessagingShell → ChannelView) without a Stream backend — for `dev:mock-*`
+ * surfaces and Storybook. It is a real `StreamChat` whose network calls
+ * (`connectUser`, `queryChannels`, `channel.watch`, `channel.sendMessage`) are
+ * replaced with in-memory behaviour driven by Stream's own channel-state
+ * machinery, so rendering fidelity matches production.
+ *
+ * Ships from `@linktr.ee/messaging-react/testing` and must never be imported by
+ * production code.
+ */
+export function createMockMessagingClient({
+  currentUser,
+  participant,
+  messages = [],
+  channelId = 'mock-dm',
+  onSend,
+}: CreateMockMessagingClientOptions): MockMessagingClient {
+  const client = new StreamChat('mock-api-key', {
+    allowServerSideConnect: true,
+  })
+
+  // Mark connected without opening a WebSocket. `MessagingProvider` renders
+  // `<Chat client={client}>` directly for an injected client, so it never
+  // calls connectUser itself.
+  client.connectUser = async () => ({ me: currentUser }) as never
+  client.disconnectUser = async () => undefined
+  client.userID = currentUser.id
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  client.user = currentUser as any
+
+  const cid = `messaging:${channelId}`
+
+  const toStreamMessage = (
+    message: MockMessage,
+    index: number
+  ): MessageResponse => {
+    const author = message.from === 'me' ? currentUser : participant
+    // Stagger timestamps oldest-first so the list orders naturally.
+    const createdAt = new Date(
+      Date.now() - (messages.length - index) * 60_000
+    ).toISOString()
+    return {
+      id: message.id ?? `mock-msg-${index}`,
+      text: message.text ?? '',
+      type: 'regular',
+      html: message.text ? `<p>${message.text}</p>` : '',
+      user: author,
+      attachments: message.attachments ?? [],
+      latest_reactions: [],
+      own_reactions: [],
+      reaction_counts: {},
+      reaction_scores: {},
+      reply_count: 0,
+      status: 'received',
+      cid,
+      created_at: createdAt,
+      updated_at: createdAt,
+      mentioned_users: [],
+      ...(message.metadata ? { metadata: message.metadata } : {}),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+  }
+
+  const seededMessages = messages.map(toStreamMessage)
+
+  const memberState = {
+    [currentUser.id]: {
+      user: { ...currentUser, is_account: false },
+      user_id: currentUser.id,
+      role: 'owner',
+      is_account: false,
+    },
+    [participant.id]: {
+      user: { ...participant, is_account: true },
+      user_id: participant.id,
+      role: 'member',
+      is_account: true,
+    },
+  }
+
+  const channel = client.channel('messaging', channelId, {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    members: [currentUser.id, participant.id] as any,
+  })
+
+  // Seed state locally instead of fetching. Mirrors the proven ChannelView
+  // story mock: override `watch` to populate `state` and return a canned
+  // QueryChannelAPIResponse.
+  channel.watch = async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    channel.state.messages = seededMessages as unknown as any[]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    channel.state.members = memberState as unknown as any
+    return {
+      channel: { members: [currentUser.id, participant.id] },
+      members: [],
+      messages: seededMessages,
+      watchers: [],
+      pinned_messages: [],
+      duration: '0ms',
+    } as unknown as QueryChannelAPIResponse
+  }
+
+  const appendMessage = (message: MessageResponse) => {
+    // addMessageSorted is Stream's own state mutation (dedupes by id), so the
+    // toolkit re-renders through the real channel-state path.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    channel.state.addMessageSorted(message as any)
+    client.dispatchEvent({
+      type: 'message.new',
+      cid,
+      message,
+      user: message.user ?? undefined,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any)
+  }
+
+  let sentCount = 0
+  channel.sendMessage = async (message) => {
+    const text =
+      typeof message === 'string'
+        ? message
+        : ((message as { text?: string })?.text ?? '')
+    const sent = {
+      ...toStreamMessage({ text, from: 'me', id: `mock-sent-${sentCount++}` }, seededMessages.length),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ...(typeof message === 'object' ? (message as any) : {}),
+      user: currentUser,
+      cid,
+    } as MessageResponse
+
+    // stream-chat-react adds the outgoing message optimistically; addMessageSorted
+    // dedupes by id, so confirming here is safe and idempotent.
+    appendMessage(sent)
+
+    const reply = onSend?.(text)
+    if (reply) {
+      const replyText = typeof reply === 'string' ? reply : reply.text
+      const replyAttachments =
+        typeof reply === 'string' ? undefined : reply.attachments
+      setTimeout(() => {
+        appendMessage(
+          toStreamMessage(
+            {
+              text: replyText,
+              from: 'them',
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              attachments: replyAttachments as any,
+              id: `mock-reply-${sentCount}`,
+            },
+            seededMessages.length
+          )
+        )
+      }, REPLY_DELAY_MS)
+    }
+
+    return { message: sent } as unknown as SendMessageAPIResponse
+  }
+
+  // MessagingShell finds the direct conversation via queryChannels; always
+  // return the one seeded channel regardless of the filter.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  client.queryChannels = async () => [channel] as any
+
+  // Initialise state up-front so first render already has the conversation.
+  void channel.watch()
+
+  return { client, channel, participantFilterId: participant.id }
+}

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+export {
+  createMockMessagingClient,
+  type CreateMockMessagingClientOptions,
+  type MockMessage,
+  type MockMessagingClient,
+  type MockMessagingUser,
+} from './createMockMessagingClient'

package/src/types.ts

@@ -10,6 +10,7 @@ import type {
   ChannelSort,
   LocalMessage,
   SendMessageAPIResponse,
+  StreamChat,
 } from 'stream-chat'
 import type {
   ChannelPreviewUIComponentProps,
@@ -448,8 +449,20 @@ export interface MessagingShellProps extends ChannelViewPassthroughProps {
 export interface MessagingProviderProps {
   children: React.ReactNode
   user: MessagingUser | null
-  serviceConfig: Omit<StreamChatServiceConfig, 'apiKey'>
-  apiKey: string
+  /**
+   * An already-constructed Stream client. When provided it takes precedence
+   * over `apiKey`: the provider renders `<Chat>` against this exact instance
+   * and does NOT create a StreamChatService or call `connectUser` — the caller
+   * owns the client's connection lifecycle. This is the seam for offline/dev
+   * (`createMockMessagingClient` from `@linktr.ee/messaging-react/testing`) and
+   * for tests, so consumers render the real UI instead of forking it.
+   * `apiKey`/`serviceConfig` are ignored while `client` is set.
+   */
+  client?: StreamChat
+  /** Required unless `client` is provided. */
+  serviceConfig?: Omit<StreamChatServiceConfig, 'apiKey'>
+  /** Required unless `client` is provided. */
+  apiKey?: string
   capabilities?: MessagingCapabilities
   debug?: boolean
 }