@linktr.ee/messaging-react 1.25.1 → 1.26.1-rc-1776055454

package/src/components/LockedAttachmentCard/index.tsx

@@ -0,0 +1,378 @@
+import {
+  DownloadSimpleIcon,
+  CircleNotchIcon,
+  CheckCircleIcon,
+  FileIcon,
+  FileCsvIcon,
+  FileDocIcon,
+  FileMdIcon,
+  FilePdfIcon,
+  FilePptIcon,
+  FileTextIcon,
+  FileXlsIcon,
+  FileZipIcon,
+  ImageIcon,
+  LockSimpleIcon,
+  LockSimpleOpenIcon,
+  PauseIcon,
+  PlayIcon,
+  SpeakerHighIcon,
+  VideoCameraIcon,
+} from '@phosphor-icons/react'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import ReactPlayer from 'react-player'
+
+import { getDocumentIconType, getSourceType } from './mimeType'
+import type { AttachmentSourceType } from './mimeType'
+
+export interface LockedAttachmentCardProps {
+  title: string
+  amountText?: string
+  thumbnail?: string
+  /**
+   * The unlocked media URL. When undefined the card is in locked state.
+   * Typically undefined while the source is being fetched post-purchase.
+   */
+  source?: string
+  /** MIME type of the attachment (e.g. 'video/mp4', 'audio/mpeg', 'image/jpeg', 'application/pdf'). Determines the icon and player behaviour. */
+  mimeType: string
+  detail?: string
+  /**
+   * Called when the visitor clicks Unlock.
+   * Omit to hide the Unlock button (e.g. creator-side views).
+   */
+  onUnlock?: () => void
+  /** Called when the visitor clicks Download on an unlocked card. */
+  onDownload?: () => void
+  /** Shows a loading spinner on the unlock button while the source is being fetched. */
+  loading?: boolean
+  /**
+   * Payment has been completed but the source URL hasn't been resolved yet.
+   * Shows a "Preparing…" state instead of the lock overlay.
+   */
+  isPurchased?: boolean
+}
+
+const MEDIA_TYPE_ICON: Record<AttachmentSourceType, React.ElementType> = {
+  video: VideoCameraIcon,
+  audio: SpeakerHighIcon,
+  image: ImageIcon,
+  document: FileIcon,
+}
+
+const DOCUMENT_ICON_COMPONENT = {
+  pdf: FilePdfIcon,
+  doc: FileDocIcon,
+  xls: FileXlsIcon,
+  csv: FileCsvIcon,
+  ppt: FilePptIcon,
+  zip: FileZipIcon,
+  text: FileTextIcon,
+  markdown: FileMdIcon,
+  generic: FileIcon,
+} as const
+
+function getTypeIcon(mimeType: string): React.ElementType {
+  const sourceType = getSourceType(mimeType)
+  if (sourceType !== 'document') return MEDIA_TYPE_ICON[sourceType]
+  return DOCUMENT_ICON_COMPONENT[getDocumentIconType(mimeType)]
+}
+
+const LockedAttachmentCard: React.FC<LockedAttachmentCardProps> = ({
+  title,
+  amountText,
+  thumbnail,
+  source,
+  mimeType,
+  detail,
+  onUnlock,
+  onDownload,
+  loading = false,
+  isPurchased = false,
+}) => {
+  const isLocked = source === undefined
+  const LockIcon = isPurchased ? LockSimpleOpenIcon : LockSimpleIcon
+  const sourceType = getSourceType(mimeType)
+  const TypeIcon = getTypeIcon(mimeType)
+  const [playing, setPlaying] = useState(false)
+  const [played, setPlayed] = useState(0)
+  const [seeking, setSeeking] = useState(false)
+  const [scrubberHovered, setScrubberHovered] = useState(false)
+  const [sourceReady, setSourceReady] = useState(false)
+  const [videoAspect, setVideoAspect] = useState<number | null>(null)
+  const [buffering, setBuffering] = useState(false)
+  const playerRef = useRef<HTMLVideoElement>(null)
+  const trackRef = useRef<HTMLDivElement>(null)
+  const rafRef = useRef<number | null>(null)
+
+  const tickProgress = useCallback(() => {
+    const el = playerRef.current
+    if (el && el.duration && !seeking) setPlayed(el.currentTime / el.duration)
+    rafRef.current = requestAnimationFrame(tickProgress)
+  }, [seeking])
+
+  useEffect(() => {
+    if (playing) {
+      rafRef.current = requestAnimationFrame(tickProgress)
+    } else {
+      if (rafRef.current !== null) cancelAnimationFrame(rafRef.current)
+    }
+    return () => { if (rafRef.current !== null) cancelAnimationFrame(rafRef.current) }
+  }, [playing, tickProgress])
+
+  // ReactPlayer v3 uses native HTML media elements and does not support a
+  // declarative `playing` prop — playback must be driven imperatively.
+  useEffect(() => {
+    const el = playerRef.current
+    if (!el) return
+    if (playing) {
+      el.play().catch(() => {})
+    } else {
+      el.pause()
+    }
+  }, [playing])
+
+  const getFraction = (e: MouseEvent | React.MouseEvent) => {
+    const track = trackRef.current
+    if (!track) return 0
+    const rect = track.getBoundingClientRect()
+    return Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
+  }
+
+  const seekTo = (fraction: number) => {
+    const el = playerRef.current
+    if (el && el.duration) el.currentTime = fraction * el.duration
+  }
+
+  const handleTrackMouseDown = (e: React.MouseEvent<HTMLDivElement>) => {
+    e.stopPropagation()
+    setSeeking(true)
+    const fraction = getFraction(e)
+    setPlayed(fraction)
+    seekTo(fraction)
+  }
+
+  useEffect(() => {
+    if (!seeking) return
+    const onMove = (e: MouseEvent) => setPlayed(getFraction(e))
+    const onUp = (e: MouseEvent) => {
+      setSeeking(false)
+      seekTo(getFraction(e))
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+    return () => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+  }, [seeking])
+
+  const mediaPlayer = (
+    <div
+      role="button"
+      tabIndex={0}
+      className={`relative cursor-pointer overflow-hidden ${sourceType === 'audio' && !thumbnail ? 'bg-black/5' : 'bg-black'}${!thumbnail ? ' aspect-video' : ''}`}
+      style={!thumbnail && videoAspect ? { aspectRatio: String(videoAspect) } : undefined}
+      onClick={() => setPlaying((p) => !p)}
+      onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') setPlaying((p) => !p) }}
+    >
+      {thumbnail && (
+        <img src={thumbnail} alt="" className="block w-full" />
+      )}
+      {!thumbnail && (
+        <div className="absolute inset-0 flex items-center justify-center">
+          <TypeIcon className="size-12 text-black/20" weight="regular" />
+        </div>
+      )}
+      <div className="absolute inset-0">
+        <ReactPlayer
+          ref={playerRef}
+          src={source}
+          poster={thumbnail}
+          width="100%"
+          height="100%"
+          onLoadStart={() => setBuffering(true)}
+          onCanPlay={() => setBuffering(false)}
+          onWaiting={() => setBuffering(true)}
+          onLoadedMetadata={() => {
+            const el = playerRef.current
+            if (el && el.videoWidth && el.videoHeight) {
+              setVideoAspect(el.videoWidth / el.videoHeight)
+            }
+          }}
+          onEnded={() => {
+            setPlaying(false)
+            setPlayed(0)
+          }}
+        />
+      </div>
+
+      {buffering && (
+        <div className="absolute inset-0 flex items-center justify-center">
+          <CircleNotchIcon className="size-8 animate-spin text-white/80" weight="bold" />
+        </div>
+      )}
+
+      {/* Custom controls */}
+      <div className="absolute inset-x-0 bottom-0 flex items-center gap-2 bg-gradient-to-t from-black/60 to-transparent px-3 pb-2.5 pt-6">
+          <button
+            type="button"
+            onClick={(e) => { e.stopPropagation(); setPlaying((p) => !p) }}
+            className="shrink-0 text-white"
+            aria-label={playing ? 'Pause' : 'Play'}
+          >
+            {playing
+              ? <PauseIcon className="size-5" weight="fill" />
+              : <PlayIcon className="size-5 translate-x-px" weight="fill" />
+            }
+          </button>
+
+          {/* Scrubber */}
+          <div
+            role="slider"
+            aria-label="Playback position"
+            aria-valuenow={Math.round(played * 100)}
+            aria-valuemin={0}
+            aria-valuemax={100}
+            tabIndex={0}
+            ref={trackRef}
+            className="relative flex h-4 w-full cursor-pointer items-center"
+            onMouseDown={handleTrackMouseDown}
+            onClick={(e) => e.stopPropagation()}
+            onMouseEnter={() => setScrubberHovered(true)}
+            onMouseLeave={() => setScrubberHovered(false)}
+            onKeyDown={(e) => {
+              if (e.key === 'ArrowRight') seekTo(Math.min(1, played + 0.05))
+              if (e.key === 'ArrowLeft') seekTo(Math.max(0, played - 0.05))
+            }}
+          >
+            <div className={`w-full overflow-hidden rounded-full bg-white/30 transition-all duration-200 ${scrubberHovered || seeking ? 'h-1.5' : 'h-1'}`}>
+              <div className="h-full rounded-full bg-white" style={{ width: `${played * 100}%` }} />
+            </div>
+            <div
+              className={`absolute size-3 -translate-x-1/2 rounded-full bg-white shadow transition-[opacity,transform] duration-200 ${scrubberHovered || seeking ? 'scale-100 opacity-100' : 'scale-0 opacity-0'}`}
+              style={{ left: `${played * 100}%` }}
+            />
+          </div>
+        </div>
+    </div>
+  )
+
+  return (
+    <div className="w-[280px] overflow-hidden rounded-3xl bg-white shadow-[0px_0px_0px_1px_rgba(0,0,0,0.04),0px_1px_2px_0px_rgba(0,0,0,0.04),0px_8px_32px_0px_rgba(0,0,0,0.1)]">
+
+        {/* Media area */}
+        {sourceType === 'image' || sourceType === 'document' ? (
+          <div className={`relative overflow-hidden bg-black/5${!thumbnail && (isLocked || sourceType === 'document') ? ' aspect-video' : ''}`}>
+            {thumbnail && (
+              <img
+                src={thumbnail}
+                alt=""
+                className="block w-full"
+              />
+            )}
+            {!thumbnail && !isLocked && (
+              <div className="absolute inset-0 flex items-center justify-center">
+                <TypeIcon className="size-12 text-black/20" weight="regular" />
+              </div>
+            )}
+            {!thumbnail && !isLocked && sourceType === 'image' && (
+              <img
+                src={source}
+                alt={title}
+                className="relative block w-full"
+              />
+            )}
+            {isLocked ? (
+              <div className="absolute inset-0 flex items-center justify-center bg-black/30">
+                <div className="flex size-12 items-center justify-center rounded-full bg-black/60">
+                  <LockIcon className="size-6 text-white" weight="regular" />
+                </div>
+              </div>
+            ) : thumbnail && sourceType === 'image' && (
+              <img
+                src={source}
+                alt={title}
+                className={`absolute inset-0 h-full w-full object-cover transition-opacity duration-300 ${sourceReady ? 'opacity-100' : 'opacity-0'}`}
+                onLoad={() => setSourceReady(true)}
+              />
+            )}
+          </div>
+        ) : isLocked ? (
+          <div className={`relative overflow-hidden bg-black/5${!thumbnail ? ' aspect-video' : ''}`}>
+            {thumbnail && (
+              <img src={thumbnail} alt="" className="block w-full" />
+            )}
+            <div className="absolute inset-0 flex items-center justify-center bg-black/30">
+              <div className="flex size-12 items-center justify-center rounded-full bg-black/60">
+                <LockIcon className="size-6 text-white" weight="regular" />
+              </div>
+            </div>
+          </div>
+        ) : (
+          mediaPlayer
+        )}
+
+        {/* Footer */}
+        <div className="px-4 pb-3 pt-3">
+          <p className="mb-1.5 truncate text-base font-medium text-black">{title}</p>
+
+          <div className="flex items-center gap-1">
+            <TypeIcon className="size-5 shrink-0 text-black/55" weight="regular" />
+            {detail && (
+              <span className="text-xs font-medium text-black/55">{detail}</span>
+            )}
+
+            {isPurchased || source ? (
+              <>
+                <span className="text-xs font-medium text-black/55">•</span>
+                <span className="text-xs font-medium text-[#008236]">Purchased</span>
+                <CheckCircleIcon className="size-4 text-[#008236]" weight="bold" />
+              </>
+            ) : amountText && (
+              <>
+                <span className="text-xs font-medium text-black/55">•</span>
+                <span className="text-xs font-medium text-black/55">{amountText}</span>
+              </>
+            )}
+
+          </div>
+
+          {isLocked ? (onUnlock || loading) && (
+            <button
+              type="button"
+              onClick={onUnlock}
+              disabled={loading}
+              className="mt-3 inline-flex h-10 w-full items-center justify-center gap-2 rounded-full bg-[#121110] px-4 text-sm font-medium leading-none text-white disabled:opacity-70"
+            >
+              {loading ? (
+                <span className="flex items-center gap-1">
+                  <span className="size-1 rounded-full bg-white animate-bounce [animation-delay:-0.3s]" />
+                  <span className="size-1 rounded-full bg-white animate-bounce [animation-delay:-0.15s]" />
+                  <span className="size-1 rounded-full bg-white animate-bounce" />
+                </span>
+              ) : (
+                <>
+                  <LockIcon className="size-4" weight="fill" />
+                  {isPurchased ? 'Open' : 'Unlock'}
+                </>
+              )}
+            </button>
+          ) : onDownload && source && (
+            <a
+              href={`${source}${source.includes('?') ? '&' : '?'}d=true`}
+              target="_blank"
+              rel="noopener noreferrer"
+              onClick={onDownload}
+              className="mt-3 inline-flex h-10 w-full items-center justify-center gap-2 rounded-full bg-[#121110] px-4 text-sm font-medium leading-none !text-white"
+            >
+              <DownloadSimpleIcon className="size-4" weight="bold" />
+              Download
+            </a>
+          )}
+        </div>
+      </div>
+  )
+}
+
+export default LockedAttachmentCard

package/src/components/LockedAttachmentCard/mimeType.test.ts

@@ -0,0 +1,97 @@
+import { getDocumentIconType, getSourceType } from './mimeType'
+
+describe('getSourceType', () => {
+  it('returns video for video/* types', () => {
+    expect(getSourceType('video/mp4')).toBe('video')
+    expect(getSourceType('video/webm')).toBe('video')
+    expect(getSourceType('video/quicktime')).toBe('video')
+  })
+
+  it('returns audio for audio/* types', () => {
+    expect(getSourceType('audio/mpeg')).toBe('audio')
+    expect(getSourceType('audio/mp4')).toBe('audio')
+    expect(getSourceType('audio/ogg')).toBe('audio')
+  })
+
+  it('returns image for image/* types', () => {
+    expect(getSourceType('image/jpeg')).toBe('image')
+    expect(getSourceType('image/png')).toBe('image')
+    expect(getSourceType('image/webp')).toBe('image')
+  })
+
+  it('returns document for application/* types', () => {
+    expect(getSourceType('application/pdf')).toBe('document')
+    expect(getSourceType('application/msword')).toBe('document')
+    expect(getSourceType('application/zip')).toBe('document')
+  })
+
+  it('returns document for text/* types', () => {
+    expect(getSourceType('text/plain')).toBe('document')
+    expect(getSourceType('text/csv')).toBe('document')
+    expect(getSourceType('text/markdown')).toBe('document')
+  })
+})
+
+describe('getDocumentIconType', () => {
+  it('returns pdf for application/pdf', () => {
+    expect(getDocumentIconType('application/pdf')).toBe('pdf')
+  })
+
+  it('returns doc for Word types', () => {
+    expect(getDocumentIconType('application/msword')).toBe('doc')
+    expect(getDocumentIconType('application/vnd.openxmlformats-officedocument.wordprocessingml.document')).toBe('doc')
+  })
+
+  it('returns xls for Excel types', () => {
+    expect(getDocumentIconType('application/vnd.ms-excel')).toBe('xls')
+    expect(getDocumentIconType('application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')).toBe('xls')
+  })
+
+  it('returns csv for text/csv', () => {
+    expect(getDocumentIconType('text/csv')).toBe('csv')
+  })
+
+  it('returns ppt for PowerPoint types', () => {
+    expect(getDocumentIconType('application/vnd.ms-powerpoint')).toBe('ppt')
+    expect(getDocumentIconType('application/vnd.openxmlformats-officedocument.presentationml.presentation')).toBe('ppt')
+  })
+
+  it('returns zip for archive types', () => {
+    expect(getDocumentIconType('application/zip')).toBe('zip')
+    expect(getDocumentIconType('application/x-zip-compressed')).toBe('zip')
+    expect(getDocumentIconType('application/gzip')).toBe('zip')
+    expect(getDocumentIconType('application/x-gzip')).toBe('zip')
+    expect(getDocumentIconType('application/x-rar-compressed')).toBe('zip')
+    expect(getDocumentIconType('application/x-7z-compressed')).toBe('zip')
+    expect(getDocumentIconType('application/x-tar')).toBe('zip')
+  })
+
+  it('returns text for plain text and rtf', () => {
+    expect(getDocumentIconType('text/plain')).toBe('text')
+    expect(getDocumentIconType('text/rtf')).toBe('text')
+    expect(getDocumentIconType('application/rtf')).toBe('text')
+    expect(getDocumentIconType('application/x-rtf')).toBe('text')
+  })
+
+  it('returns markdown for markdown types', () => {
+    expect(getDocumentIconType('text/markdown')).toBe('markdown')
+    expect(getDocumentIconType('text/x-markdown')).toBe('markdown')
+  })
+
+  it('returns xls for macro-enabled Excel', () => {
+    expect(getDocumentIconType('application/vnd.ms-excel.sheet.macroEnabled.12')).toBe('xls')
+  })
+
+  it('returns ppt for macro-enabled PowerPoint', () => {
+    expect(getDocumentIconType('application/vnd.ms-powerpoint.presentation.macroEnabled.12')).toBe('ppt')
+  })
+
+  it('returns generic for unknown types', () => {
+    expect(getDocumentIconType('application/octet-stream')).toBe('generic')
+    expect(getDocumentIconType('application/json')).toBe('generic')
+    expect(getDocumentIconType('text/html')).toBe('generic')
+    expect(getDocumentIconType('application/vnd.rar')).toBe('generic')
+    expect(getDocumentIconType('application/vnd.oasis.opendocument.text')).toBe('generic')
+    expect(getDocumentIconType('application/vnd.oasis.opendocument.spreadsheet')).toBe('generic')
+  })
+})

package/src/components/LockedAttachmentCard/mimeType.ts

@@ -0,0 +1,35 @@
+export type AttachmentSourceType = 'image' | 'audio' | 'video' | 'document'
+
+export type DocumentIconType =
+  | 'pdf'
+  | 'doc'
+  | 'xls'
+  | 'csv'
+  | 'ppt'
+  | 'zip'
+  | 'text'
+  | 'markdown'
+  | 'generic'
+
+const DOCUMENT_ICON_PATTERNS: Array<[RegExp, DocumentIconType]> = [
+  [/pdf/, 'pdf'],
+  [/wordprocessingml|msword|\.doc/, 'doc'],
+  [/spreadsheetml|ms-excel|\.xls/, 'xls'],
+  [/csv/, 'csv'],
+  [/presentationml|ms-powerpoint|\.ppt/, 'ppt'],
+  [/zip|x-rar|x-7z|x-tar|x-gzip/, 'zip'],
+  [/plain|rtf/, 'text'],
+  [/markdown/, 'markdown'],
+]
+
+export function getSourceType(mimeType: string): AttachmentSourceType {
+  if (mimeType.startsWith('video/')) return 'video'
+  if (mimeType.startsWith('audio/')) return 'audio'
+  if (mimeType.startsWith('image/')) return 'image'
+  return 'document'
+}
+
+export function getDocumentIconType(mimeType: string): DocumentIconType {
+  const match = DOCUMENT_ICON_PATTERNS.find(([pattern]) => pattern.test(mimeType))
+  return match ? match[1] : 'generic'
+}

package/src/components/MessagingShell/index.tsx

@@ -27,6 +27,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
   CustomChannelEmptyState,
   showChannelList = true,
   filters,
+  channelRenderFilterFn,
   channelListCustomEmptyStateIndicator,
   onDeleteConversationClick,
   onBlockParticipantClick,
@@ -455,6 +456,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
             onChannelSelect={handleChannelSelect}
             selectedChannel={selectedChannel || undefined}
             filters={channelFilters}
+            channelRenderFilterFn={channelRenderFilterFn}
             customEmptyStateIndicator={channelListCustomEmptyStateIndicator}
             renderMessagePreview={renderMessagePreview}
           />

package/src/index.ts

@@ -6,12 +6,14 @@ export { MessagingShell } from './components/MessagingShell'
 export { ChannelList } from './components/ChannelList'
 export { ChannelView } from './components/ChannelView'
 export { default as ActionButton } from './components/ActionButton'
+export { default as LockedAttachmentCard } from './components/LockedAttachmentCard'
 export { ParticipantPicker } from './components/ParticipantPicker'
 export { Avatar } from './components/Avatar'
 export { FaqList } from './components/FaqList'
 export { FaqListItem } from './components/FaqList/FaqListItem'
 export { ChannelEmptyState } from './components/MessagingShell/ChannelEmptyState'
 export { MessageVoteButtons } from './components/CustomMessage/MessageVoteButtons'
+export { isAttachmentMessage } from './components/CustomMessage/MessageTag'
 
 // Providers
 export { MessagingProvider } from './providers/MessagingProvider'
@@ -38,6 +40,8 @@ export type {
 export type { MessageMetadata } from './stream-custom-data'
 export type { AvatarProps } from './components/Avatar'
 export type { ActionButtonProps } from './components/ActionButton'
+export type { LockedAttachmentCardProps } from './components/LockedAttachmentCard'
+export type { AttachmentSourceType } from './components/LockedAttachmentCard/mimeType'
 export type { Faq, FaqListProps } from './components/FaqList'
 export type { FaqListItemProps } from './components/FaqList/FaqListItem'
 export type { VoteSelection } from './hooks/useMessageVote'

package/src/stream-custom-data.ts

@@ -24,6 +24,7 @@ export type MessageCustomType =
   | 'MESSAGE_TIP'
   | 'MESSAGE_PAID'
   | 'MESSAGE_CHATBOT'
+  | 'MESSAGE_ATTACHMENT'
   | AgeSafetySystemType
   | DmAgentSystemType
 
@@ -31,12 +32,18 @@ export type MessageCustomType =
  * Message metadata for paid messaging and chatbot flows.
  * Used to identify message types and payment status.
  */
+export type PaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded'
+
 export interface MessageMetadata {
   custom_type?: MessageCustomType
-  amount_text?: string
-  payment_status?: string
-  payment_intent_id?: string
   listing_id?: string
+  amount_text?: string
+  payment_status?: PaymentStatus
+  // MESSAGE_ATTACHMENT
+  attachment_title?: string
+  attachment_mime_type?: string
+  attachment_thumbnail?: string
+  attachment_detail?: string
 }
 
 declare module 'stream-chat' {

package/src/types.ts

@@ -91,6 +91,20 @@ export interface ChannelListProps {
    * channel belongs in the current list before inserting it.
    */
   onAddedToChannel?: StreamChannelListProps['onAddedToChannel']
+  /**
+   * Client-side filter applied before rendering the channel list.
+   * Websocket events can add channels to the list that bypass server-side
+   * query filters. Use this to enforce visibility rules that can't be
+   * automatically derived from the filters prop (e.g. $or conditions).
+   *
+   * @example
+   * // Hide channels where the visitor hasn't sent a message yet,
+   * // but keep legacy channels that predate the has_visitor_message field
+   * channelRenderFilterFn={(channels) =>
+   *   channels.filter(ch => ch.data?.has_visitor_message !== false)
+   * }
+   */
+  channelRenderFilterFn?: (channels: Channel[]) => Channel[]
   /**
    * Sort order for the channel list query.
    * Defaults to `{ last_message_at: -1 }` (most recent first).
@@ -217,6 +231,19 @@ export interface ChannelViewProps {
     messageNode: React.ReactElement,
     message: LocalMessage
   ) => React.ReactNode
+
+  /**
+   * Called when the visitor clicks Unlock on a locked attachment message.
+   * Receives the message and channel. Show checkout, confirm payment, fetch
+   * the unlocked URL. `attachment_source` must NOT be stored on the Stream message metadata.
+   * The card shows a loading state for the full duration of the promise.
+   */
+  onAttachmentUnlock?: (message: LocalMessage, channel: Channel) => Promise<string>
+
+  /**
+   * Called when the visitor clicks Download on an unlocked attachment message.
+   */
+  onAttachmentDownload?: (message: LocalMessage, channel: Channel) => void
 }
 
 /**
@@ -240,6 +267,8 @@ export type ChannelViewPassthroughProps = Pick<
   | 'customProfileContent'
   | 'customChannelActions'
   | 'renderMessage'
+  | 'onAttachmentUnlock'
+  | 'onAttachmentDownload'
 >
 
 /**
@@ -282,6 +311,18 @@ export interface MessagingShellProps extends ChannelViewPassthroughProps {
    */
   filters?: ChannelFilters
 
+  /**
+   * Client-side filter applied before rendering the channel list.
+   * Websocket events can add channels to the list that bypass server-side
+   * query filters. Use this to enforce visibility rules client-side.
+   *
+   * @example
+   * channelRenderFilterFn={(channels) =>
+   *   channels.filter(ch => ch.data?.has_visitor_message !== false)
+   * }
+   */
+  channelRenderFilterFn?: (channels: Channel[]) => Channel[]
+
   /**
    * Custom empty state indicator component to render when the channel list is empty.
    * Useful for showing a custom empty state indicator when the channel list is empty.