@adatechnology/conversations-ui 0.4.2 → 0.6.0

package/src/participant/participantFileValidation.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'bun:test'
+
+import { channelCapabilityFor } from '../channelCapability'
+import { maxBytesForChannel, reduceFilesSelection, validateParticipantFiles } from './participantFileValidation'
+
+function buildFile(name: string, type: string, sizeBytes: number): File {
+  return new File([new Uint8Array(sizeBytes)], name, { type })
+}
+
+describe('validateParticipantFiles', () => {
+  it('accepts files within the size limit and accepted types', () => {
+    const photo = buildFile('photo.jpg', 'image/jpeg', 10)
+    const result = validateParticipantFiles({ files: [photo], maxBytes: 100, acceptedTypes: ['image/*'] })
+
+    expect(result.accepted).toEqual([photo])
+    expect(result.rejection).toBeUndefined()
+  })
+
+  it('rejects a file above maxBytes with tooLarge and keeps the valid ones', () => {
+    const small = buildFile('a.jpg', 'image/jpeg', 10)
+    const big = buildFile('b.jpg', 'image/jpeg', 101)
+    const result = validateParticipantFiles({ files: [small, big], maxBytes: 100 })
+
+    expect(result.accepted).toEqual([small])
+    expect(result.rejection).toBe('tooLarge')
+  })
+
+  it('rejects a type outside acceptedTypes, by exact type or wildcard', () => {
+    const sheet = buildFile('a.xls', 'application/vnd.ms-excel', 1)
+    const pdf = buildFile('a.pdf', 'application/pdf', 1)
+    const result = validateParticipantFiles({ files: [sheet, pdf], maxBytes: 100, acceptedTypes: ['image/*', 'application/pdf'] })
+
+    expect(result.accepted).toEqual([pdf])
+    expect(result.rejection).toBe('typeNotAccepted')
+  })
+
+  it('accepts any type when acceptedTypes is absent', () => {
+    const any = buildFile('a.bin', '', 1)
+
+    expect(validateParticipantFiles({ files: [any], maxBytes: 100 }).accepted).toEqual([any])
+  })
+})
+
+describe('reduceFilesSelection', () => {
+  const ACCEPTED = ['image/*', 'application/pdf']
+
+  it('keeps already chosen files and appends the valid incoming ones', () => {
+    const current = [buildFile('a.jpg', 'image/jpeg', 10)]
+    const incoming = [buildFile('b.pdf', 'application/pdf', 10)]
+    const result = reduceFilesSelection({ current, incoming, maxBytes: 100, acceptedTypes: ACCEPTED })
+
+    expect(result.files).toEqual([...current, ...incoming])
+    expect(result.rejected).toEqual([])
+  })
+
+  it('a refusal never empties what was already chosen', () => {
+    const current = [buildFile('a.jpg', 'image/jpeg', 10)]
+    const big = buildFile('big.jpg', 'image/jpeg', 101)
+    const sheet = buildFile('s.xls', 'application/vnd.ms-excel', 1)
+    const result = reduceFilesSelection({ current, incoming: [big, sheet], maxBytes: 100, acceptedTypes: ACCEPTED })
+
+    expect(result.files).toEqual(current)
+    expect(result.rejected).toEqual([
+      { file: big, reason: 'tooLarge' },
+      { file: sheet, reason: 'typeNotAccepted' },
+    ])
+  })
+
+  it('keeps the valid files of a mixed selection', () => {
+    const good = buildFile('ok.jpg', 'image/jpeg', 10)
+    const big = buildFile('big.jpg', 'image/jpeg', 101)
+    const result = reduceFilesSelection({ current: [], incoming: [big, good], maxBytes: 100 })
+
+    expect(result.files).toEqual([good])
+    expect(result.rejected).toHaveLength(1)
+  })
+
+  it('takes the ceiling from the channel capability', () => {
+    const twentyFiveMegabytes = 25 * 1024 * 1024
+    expect(channelCapabilityFor('app').attachments.maxBytes).toBe(twentyFiveMegabytes)
+    expect(channelCapabilityFor('portal').attachments.maxBytes).toBeGreaterThan(0)
+    expect(maxBytesForChannel('app')).toBe(twentyFiveMegabytes)
+    expect(maxBytesForChannel(undefined)).toBe(twentyFiveMegabytes)
+    expect(maxBytesForChannel('portal')).toBe(channelCapabilityFor('portal').attachments.maxBytes)
+  })
+})

package/src/participant/participantFileValidation.ts

@@ -0,0 +1,72 @@
+import { channelCapabilityFor } from '../channelCapability'
+import type { ConversationChannel } from '../conversationChannel'
+
+export type ParticipantFileRejection = 'tooLarge' | 'typeNotAccepted'
+
+export type ValidateParticipantFilesParams = {
+  readonly files: readonly File[]
+  readonly maxBytes: number
+  /** MIME types or wildcards such as `image/*`. Absent means any type. */
+  readonly acceptedTypes?: readonly string[]
+}
+
+export type ValidateParticipantFilesResult = {
+  readonly accepted: readonly File[]
+  readonly rejection?: ParticipantFileRejection
+}
+
+function matchesAcceptedType(mimeType: string, acceptedTypes: readonly string[]): boolean {
+  return acceptedTypes.some((accepted) =>
+    accepted.endsWith('/*') ? mimeType.startsWith(accepted.slice(0, -1)) : mimeType === accepted,
+  )
+}
+
+function rejectionOf(file: File, params: Omit<ValidateParticipantFilesParams, 'files'>): ParticipantFileRejection | undefined {
+  if (params.acceptedTypes && !matchesAcceptedType(file.type, params.acceptedTypes)) return 'typeNotAccepted'
+  if (file.size > params.maxBytes) return 'tooLarge'
+  return undefined
+}
+
+export function validateParticipantFiles(params: ValidateParticipantFilesParams): ValidateParticipantFilesResult {
+  const accepted: File[] = []
+  let rejection: ParticipantFileRejection | undefined
+  for (const file of params.files) {
+    const reason = rejectionOf(file, params)
+    if (reason === undefined) accepted.push(file)
+    else rejection = rejection ?? reason
+  }
+  return rejection === undefined ? { accepted } : { accepted, rejection }
+}
+
+export type RejectedParticipantFile = {
+  readonly file: File
+  readonly reason: ParticipantFileRejection
+}
+
+export type ReduceFilesSelectionParams = {
+  readonly current: readonly File[]
+  readonly incoming: readonly File[]
+  readonly maxBytes: number
+  readonly acceptedTypes?: readonly string[]
+}
+
+export type ReduceFilesSelectionResult = {
+  readonly files: readonly File[]
+  readonly rejected: readonly RejectedParticipantFile[]
+}
+
+/** A refusal never drops what was already chosen: valid files are kept, refused ones are reported. */
+export function reduceFilesSelection(params: ReduceFilesSelectionParams): ReduceFilesSelectionResult {
+  const files = [...params.current]
+  const rejected: RejectedParticipantFile[] = []
+  for (const file of params.incoming) {
+    const reason = rejectionOf(file, params)
+    if (reason === undefined) files.push(file)
+    else rejected.push({ file, reason })
+  }
+  return { files, rejected }
+}
+
+export function maxBytesForChannel(channel: ConversationChannel = 'app'): number {
+  return channelCapabilityFor(channel).attachments.maxBytes
+}

package/src/participant/participantFixtures.test-helper.ts

@@ -0,0 +1,41 @@
+import type { ParticipantConversationSummary, ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+export function buildConversation(
+  overrides: Partial<ParticipantConversationSummary> & { subjectId: string },
+): ParticipantConversationSummary {
+  return {
+    subjectType: 'invoice',
+    subjectLabel: 'Invoice 4521',
+    lastMessageAt: '2026-10-01T10:00:00.000Z',
+    unreadCount: 0,
+    awaitingParticipant: false,
+    status: 'open',
+    ...overrides,
+  }
+}
+
+export function buildMessage(overrides: Partial<ParticipantMessage> & { id: string }): ParticipantMessage {
+  return {
+    direction: 'outbound',
+    text: 'Hello',
+    attachments: [],
+    createdAt: '2026-10-01T10:00:00.000Z',
+    ...overrides,
+  }
+}
+
+const UTILITY_PREFIXES = /^(flex|grid|block|inline|hidden|p[xytblr]?-|m[xytblr]?-|text-|bg-|border|rounded|w-|h-|min-|max-|items-|justify-|gap-|space-|font-|shadow|dark:|hover:|sm:|md:)/
+
+/** Returns the class tokens in the markup that look like Tailwind utilities. */
+export function findUtilityClassTokens(markup: string): string[] {
+  const classAttributes = [...markup.matchAll(/class="([^"]*)"/g)].map((match) => match[1] ?? '')
+  const tokens = classAttributes.flatMap((value) => value.split(/\s+/).filter(Boolean))
+  return tokens.filter((token) => UTILITY_PREFIXES.test(token))
+}
+
+/** Returns class tokens that do not belong to the participant namespace or the reused leaf components. */
+export function findForeignClassTokens(markup: string): string[] {
+  const classAttributes = [...markup.matchAll(/class="([^"]*)"/g)].map((match) => match[1] ?? '')
+  const tokens = classAttributes.flatMap((value) => value.split(/\s+/).filter(Boolean))
+  return tokens.filter((token) => !/^(cv-p$|cv-p-|cv-status-ticks|cv-message-text|lucide)/.test(token))
+}

package/src/participant/participantGrouping.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import { groupParticipantConversations } from './participantGrouping'
+
+function build(
+  overrides: Partial<ParticipantConversationSummary> & { subjectId: string },
+): ParticipantConversationSummary {
+  return {
+    subjectType: 'invoice',
+    subjectLabel: 'Label',
+    lastMessageAt: '2026-10-01T10:00:00.000Z',
+    unreadCount: 0,
+    awaitingParticipant: false,
+    status: 'open',
+    ...overrides,
+  }
+}
+
+const GROUPS = [
+  { subjectType: 'zeta', label: 'Zeta' },
+  { subjectType: 'alpha', label: 'Alpha' },
+] as const
+
+function keysOf(view: ReturnType<typeof groupParticipantConversations>): string[] {
+  return view.sections.map((section) => section.key)
+}
+
+describe('groupParticipantConversations', () => {
+  it('applies precedence closed > awaiting > group > other', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [
+        build({ subjectId: '1', subjectType: 'zeta', status: 'closed', awaitingParticipant: true }),
+        build({ subjectId: '2', subjectType: 'zeta', awaitingParticipant: true }),
+        build({ subjectId: '3', subjectType: 'zeta' }),
+        build({ subjectId: '4', subjectType: 'unknown' }),
+      ],
+    })
+    expect(keysOf(view)).toEqual(['awaiting', 'zeta', 'other', 'closed'])
+    expect(view.sections.map((section) => section.conversations.map((c) => c.subjectId))).toEqual([
+      ['2'],
+      ['3'],
+      ['4'],
+      ['1'],
+    ])
+  })
+
+  it('orders group sections by the subjectGroups array, not alphabetically, skipping empty groups', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: [...GROUPS, { subjectType: 'empty', label: 'Empty' }],
+      conversations: [build({ subjectId: '1', subjectType: 'alpha' }), build({ subjectId: '2', subjectType: 'zeta' })],
+    })
+    expect(keysOf(view)).toEqual(['zeta', 'alpha'])
+  })
+
+  it('sorts by lastMessageAt descending, null last, ties by subjectLabel', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [
+        build({ subjectId: 'a', subjectType: 'zeta', lastMessageAt: null, subjectLabel: 'A' }),
+        build({ subjectId: 'b', subjectType: 'zeta', lastMessageAt: '2026-10-01T10:00:00.000Z', subjectLabel: 'Beta' }),
+        build({ subjectId: 'c', subjectType: 'zeta', lastMessageAt: '2026-10-02T10:00:00.000Z', subjectLabel: 'Z' }),
+        build({
+          subjectId: 'd',
+          subjectType: 'zeta',
+          lastMessageAt: '2026-10-01T10:00:00.000Z',
+          subjectLabel: 'Alpha',
+        }),
+      ],
+    })
+    expect(view.sections[0]?.conversations.map((c) => c.subjectId)).toEqual(['c', 'd', 'b', 'a'])
+  })
+
+  it('sums unread per section and per filter', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [
+        build({ subjectId: '1', subjectType: 'zeta', unreadCount: 2 }),
+        build({ subjectId: '2', subjectType: 'zeta', unreadCount: 3, awaitingParticipant: true }),
+        build({ subjectId: '3', subjectType: 'alpha', unreadCount: 4 }),
+      ],
+    })
+    expect(view.sections.map((section) => [section.key, section.unreadCount])).toEqual([
+      ['awaiting', 3],
+      ['zeta', 2],
+      ['alpha', 4],
+    ])
+    expect(view.filters.map((filter) => [filter.subjectType, filter.unreadCount])).toEqual([
+      ['all', 9],
+      ['zeta', 5],
+      ['alpha', 4],
+    ])
+  })
+
+  it('places every conversation in exactly one section', () => {
+    const conversations = [
+      build({ subjectId: '1', subjectType: 'zeta', status: 'closed' }),
+      build({ subjectId: '2', subjectType: 'alpha', awaitingParticipant: true }),
+      build({ subjectId: '3', subjectType: 'nope' }),
+      build({ subjectId: '4', subjectType: 'alpha' }),
+      build({ subjectId: '5', subjectType: 'zeta', lastMessageAt: null }),
+    ]
+    const view = groupParticipantConversations({ subjectGroups: GROUPS, conversations })
+    const total = view.sections.reduce((sum, section) => sum + section.conversations.length, 0)
+    expect(total).toBe(conversations.length)
+  })
+
+  it('sends unknown subjectType to other and never drops it', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [build({ subjectId: '1', subjectType: 'mystery' })],
+    })
+    expect(keysOf(view)).toEqual(['other'])
+  })
+
+  it('shows filters only with two or more groups that have conversations', () => {
+    const one = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [build({ subjectId: '1', subjectType: 'zeta' })],
+    })
+    expect(one.showFilters).toBe(false)
+    const two = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [build({ subjectId: '1', subjectType: 'zeta' }), build({ subjectId: '2', subjectType: 'alpha' })],
+    })
+    expect(two.showFilters).toBe(true)
+  })
+
+  it('restricts every section to the filtered subjectType, including awaiting', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      filter: 'alpha',
+      conversations: [
+        build({ subjectId: '1', subjectType: 'zeta', awaitingParticipant: true }),
+        build({ subjectId: '2', subjectType: 'alpha', awaitingParticipant: true }),
+        build({ subjectId: '3', subjectType: 'alpha' }),
+        build({ subjectId: '4', subjectType: 'zeta' }),
+      ],
+    })
+    expect(view.sections.map((section) => section.conversations.map((c) => c.subjectId))).toEqual([['2'], ['3']])
+    expect(
+      groupParticipantConversations({
+        subjectGroups: GROUPS,
+        filter: 'all',
+        conversations: [build({ subjectId: '1' })],
+      }).sections,
+    ).toHaveLength(1)
+  })
+})
+
+describe('groupParticipantConversations with a search query', () => {
+  const conversations = [
+    build({ subjectId: '1', subjectType: 'alpha', protocol: '261009-K7M2', unreadCount: 2 }),
+    build({ subjectId: '2', subjectType: 'zeta', protocol: '261008-AB23', unreadCount: 1 }),
+    build({ subjectId: '3', subjectType: 'zeta', protocol: '261007-CD45' }),
+  ]
+  const idsOf = (view: ReturnType<typeof groupParticipantConversations>) =>
+    view.sections.flatMap((section) => section.conversations.map((item) => item.subjectId))
+
+  it('keeps chips and counts computed on the whole list, not on the search result', () => {
+    const view = groupParticipantConversations({
+      conversations,
+      subjectGroups: GROUPS,
+      filter: 'all',
+      searchQuery: 'k7m2',
+    })
+    expect(idsOf(view)).toEqual(['1'])
+    expect(view.showFilters).toBe(true)
+    expect(view.filters.map((filter) => [filter.subjectType, filter.unreadCount])).toEqual([
+      ['all', 3],
+      ['zeta', 1],
+      ['alpha', 2],
+    ])
+  })
+
+  it('chip of another subject plus the protocol of a conversation outside it: chips stay and the view says so', () => {
+    const view = groupParticipantConversations({
+      conversations,
+      subjectGroups: GROUPS,
+      filter: 'zeta',
+      searchQuery: '261009',
+    })
+    expect(view.sections).toEqual([])
+    expect(view.showFilters).toBe(true)
+    expect(view.hasMatchesOutsideFilter).toBe(true)
+  })
+
+  it('a query that matches inside the active filter shows only those rows', () => {
+    const view = groupParticipantConversations({
+      conversations,
+      subjectGroups: GROUPS,
+      filter: 'zeta',
+      searchQuery: 'ab23',
+    })
+    expect(idsOf(view)).toEqual(['2'])
+    expect(view.hasMatchesOutsideFilter).toBe(false)
+  })
+
+  it('a query that matches nothing anywhere is not an outside-filter match', () => {
+    const view = groupParticipantConversations({
+      conversations,
+      subjectGroups: GROUPS,
+      filter: 'zeta',
+      searchQuery: 'zzz',
+    })
+    expect(view.hasMatchesOutsideFilter).toBe(false)
+    expect(view.showFilters).toBe(true)
+  })
+
+  it('without a query nothing is outside the filter', () => {
+    const view = groupParticipantConversations({ conversations, subjectGroups: GROUPS, filter: 'zeta' })
+    expect(view.hasMatchesOutsideFilter).toBe(false)
+  })
+
+  it('a filter pointing at a subject with no conversations behaves as all', () => {
+    const view = groupParticipantConversations({
+      conversations: [build({ subjectId: '1', subjectType: 'zeta' })],
+      subjectGroups: GROUPS,
+      filter: 'alpha',
+    })
+    expect(idsOf(view)).toEqual(['1'])
+    expect(view.activeFilter).toBe('all')
+    expect(view.hasMatchesOutsideFilter).toBe(false)
+  })
+
+  it('keeps a filter that still has conversations as active', () => {
+    const view = groupParticipantConversations({
+      conversations: [build({ subjectId: '1', subjectType: 'zeta' })],
+      subjectGroups: GROUPS,
+      filter: 'zeta',
+    })
+    expect(view.activeFilter).toBe('zeta')
+  })
+})

package/src/participant/participantGrouping.ts

@@ -0,0 +1,90 @@
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import type {
+  GroupParticipantConversationsParams,
+  ParticipantInboxFilter,
+  ParticipantInboxSection,
+  ParticipantInboxView,
+} from './participant.types'
+import { filterConversationsBySearch } from './participantProtocol'
+
+const ALL_FILTER = 'all'
+const SECTION_AWAITING = 'awaiting'
+const SECTION_OTHER = 'other'
+const SECTION_CLOSED = 'closed'
+
+function compareConversations(left: ParticipantConversationSummary, right: ParticipantConversationSummary): number {
+  if (left.lastMessageAt !== right.lastMessageAt) {
+    if (left.lastMessageAt === null) return 1
+    if (right.lastMessageAt === null) return -1
+    return left.lastMessageAt < right.lastMessageAt ? 1 : -1
+  }
+  return left.subjectLabel.localeCompare(right.subjectLabel)
+}
+
+function sumUnread(conversations: readonly ParticipantConversationSummary[]): number {
+  return conversations.reduce((sum, conversation) => sum + conversation.unreadCount, 0)
+}
+
+function resolveSectionKey(conversation: ParticipantConversationSummary, knownTypes: ReadonlySet<string>): string {
+  if (conversation.status === 'closed') return SECTION_CLOSED
+  if (conversation.awaitingParticipant) return SECTION_AWAITING
+  return knownTypes.has(conversation.subjectType) ? conversation.subjectType : SECTION_OTHER
+}
+
+function buildSection(key: string, conversations: readonly ParticipantConversationSummary[]): ParticipantInboxSection {
+  const sorted = [...conversations].sort(compareConversations)
+  return { key, conversations: sorted, unreadCount: sumUnread(sorted) }
+}
+
+function buildFilters(
+  params: GroupParticipantConversationsParams,
+): Pick<ParticipantInboxView, 'filters' | 'showFilters'> {
+  const groupFilters: ParticipantInboxFilter[] = []
+  for (const group of params.subjectGroups) {
+    const own = params.conversations.filter((conversation) => conversation.subjectType === group.subjectType)
+    if (own.length === 0) continue
+    groupFilters.push({ subjectType: group.subjectType, label: group.label, unreadCount: sumUnread(own) })
+  }
+  const all: ParticipantInboxFilter = {
+    subjectType: ALL_FILTER,
+    label: 'All',
+    unreadCount: sumUnread(params.conversations),
+  }
+  return { filters: [all, ...groupFilters], showFilters: groupFilters.length >= 2 }
+}
+
+function resolveActiveFilter(params: GroupParticipantConversationsParams): string {
+  const { filter, conversations } = params
+  if (filter === undefined || filter === ALL_FILTER) return ALL_FILTER
+  return conversations.some((conversation) => conversation.subjectType === filter) ? filter : ALL_FILTER
+}
+
+export function groupParticipantConversations(params: GroupParticipantConversationsParams): ParticipantInboxView {
+  const { subjectGroups } = params
+  const filter = resolveActiveFilter(params)
+  const isFiltered = filter !== ALL_FILTER
+  const searched = filterConversationsBySearch(params.conversations, params.searchQuery ?? '')
+  const visible = isFiltered ? searched.filter((conversation) => conversation.subjectType === filter) : searched
+  const knownTypes = new Set(subjectGroups.map((group) => group.subjectType))
+
+  const buckets = new Map<string, ParticipantConversationSummary[]>()
+  for (const conversation of visible) {
+    const key = resolveSectionKey(conversation, knownTypes)
+    buckets.set(key, [...(buckets.get(key) ?? []), conversation])
+  }
+
+  const orderedKeys = [
+    SECTION_AWAITING,
+    ...subjectGroups.map((group) => group.subjectType),
+    SECTION_OTHER,
+    SECTION_CLOSED,
+  ]
+  const sections = orderedKeys.flatMap((key) => {
+    const bucket = buckets.get(key)
+    return bucket === undefined ? [] : [buildSection(key, bucket)]
+  })
+
+  const hasMatchesOutsideFilter = isFiltered && visible.length === 0 && searched.length > 0
+  return { sections, hasMatchesOutsideFilter, activeFilter: filter, ...buildFilters(params) }
+}

package/src/participant/participantInboxState.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import { INITIAL_PARTICIPANT_INBOX_STATE, participantInboxReducer } from './participantInboxState'
+
+function conversation(subjectId: string, unreadCount = 0, subjectType = 'trip'): ParticipantConversationSummary {
+  return { subjectType, subjectId, subjectLabel: subjectId, lastMessageAt: null, unreadCount, awaitingParticipant: false, status: 'open' }
+}
+
+describe('participantInboxReducer', () => {
+  it('starts idle and goes to loading on started', () => {
+    expect(INITIAL_PARTICIPANT_INBOX_STATE.status).toBe('idle')
+    expect(participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'started' }).status).toBe('loading')
+  })
+
+  it('keeps ready status while revalidating', () => {
+    const ready = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')] })
+    expect(participantInboxReducer(ready, { type: 'started' }).status).toBe('ready')
+  })
+
+  it('loaded stores the list and the cursor', () => {
+    const state = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')], nextCursor: 'c1' })
+    expect(state).toMatchObject({ status: 'ready', nextCursor: 'c1' })
+    const replaced = participantInboxReducer(state, { type: 'loaded', conversations: [conversation('a')] })
+    expect(replaced.conversations.map((item) => item.subjectId)).toEqual(['a'])
+    expect(replaced.nextCursor).toBeUndefined()
+  })
+
+  it('loaded (revalidation) keeps the appended pages and lets the newest version of a subject win', () => {
+    const first = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a'), conversation('b')], nextCursor: 'c1' })
+    const paged = participantInboxReducer(first, { type: 'appended', conversations: [conversation('c'), conversation('d')], nextCursor: 'c2' })
+    const revalidated = participantInboxReducer(paged, { type: 'loaded', conversations: [conversation('b', 7), conversation('a')], nextCursor: 'c1' })
+
+    expect(revalidated.conversations.map((item) => item.subjectId)).toEqual(['b', 'a', 'c', 'd'])
+    expect(revalidated.conversations[0]?.unreadCount).toBe(7)
+    expect(revalidated.nextCursor).toBe('c2')
+  })
+
+  it('loaded takes the new cursor when no extra pages were appended', () => {
+    const first = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')], nextCursor: 'c1' })
+    const revalidated = participantInboxReducer(first, { type: 'loaded', conversations: [conversation('a')], nextCursor: 'c9' })
+    expect(revalidated.nextCursor).toBe('c9')
+  })
+
+  it('appended adds the next page without duplicating a subject', () => {
+    const first = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a'), conversation('b')], nextCursor: 'c1' })
+    const next = participantInboxReducer(first, { type: 'appended', conversations: [conversation('b', 3), conversation('c')] })
+    expect(next.conversations.map((item) => item.subjectId)).toEqual(['a', 'b', 'c'])
+    expect(next.conversations[1]?.unreadCount).toBe(3)
+    expect(next.nextCursor).toBeUndefined()
+  })
+
+  it('markedRead zeroes only that subject', () => {
+    const loaded = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, {
+      type: 'loaded',
+      conversations: [conversation('a', 2), conversation('b', 4), conversation('a', 5, 'invoice')],
+    })
+    const next = participantInboxReducer(loaded, { type: 'markedRead', subject: { subjectType: 'trip', subjectId: 'a' } })
+    expect(next.conversations.map((item) => item.unreadCount)).toEqual([0, 4, 5])
+  })
+
+  it('failed records the error and keeps the conversations', () => {
+    const loaded = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')] })
+    const failed = participantInboxReducer(loaded, { type: 'failed', error: 'boom' })
+    expect(failed).toMatchObject({ status: 'error', error: 'boom' })
+    expect(failed.conversations).toHaveLength(1)
+  })
+})

package/src/participant/participantInboxState.ts

@@ -0,0 +1,74 @@
+import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+export type ParticipantInboxState = {
+  readonly status: 'idle' | 'loading' | 'ready' | 'error'
+  readonly conversations: readonly ParticipantConversationSummary[]
+  readonly nextCursor?: string
+  readonly error?: string
+}
+
+export type ParticipantInboxAction =
+  | { readonly type: 'started' }
+  | { readonly type: 'loaded'; readonly conversations: readonly ParticipantConversationSummary[]; readonly nextCursor?: string }
+  | { readonly type: 'appended'; readonly conversations: readonly ParticipantConversationSummary[]; readonly nextCursor?: string }
+  | { readonly type: 'markedRead'; readonly subject: ParticipantSubjectRef }
+  | { readonly type: 'failed'; readonly error: string }
+
+export const INITIAL_PARTICIPANT_INBOX_STATE: ParticipantInboxState = { status: 'idle', conversations: [] }
+
+function subjectKey(subject: ParticipantSubjectRef): string {
+  return `${subject.subjectType}:${subject.subjectId}`
+}
+
+function withCursor(
+  state: ParticipantInboxState,
+  conversations: readonly ParticipantConversationSummary[],
+  nextCursor: string | undefined,
+): ParticipantInboxState {
+  const { error: _error, nextCursor: _nextCursor, ...rest } = state
+  return { ...rest, status: 'ready', conversations, ...(nextCursor === undefined ? {} : { nextCursor }) }
+}
+
+/** Revalidation brings the first page again: it must not drop the pages appended after it. */
+function mergeFirstPage(
+  state: ParticipantInboxState,
+  incoming: readonly ParticipantConversationSummary[],
+  nextCursor: string | undefined,
+): ParticipantInboxState {
+  const incomingKeys = new Set(incoming.map(subjectKey))
+  const retained = state.conversations.filter((conversation) => !incomingKeys.has(subjectKey(conversation)))
+  const cursor = retained.length > 0 ? state.nextCursor : nextCursor
+  return withCursor(state, [...incoming, ...retained], cursor)
+}
+
+function appendUnique(
+  current: readonly ParticipantConversationSummary[],
+  incoming: readonly ParticipantConversationSummary[],
+): readonly ParticipantConversationSummary[] {
+  const incomingByKey = new Map(incoming.map((conversation) => [subjectKey(conversation), conversation]))
+  const updated = current.map((conversation) => incomingByKey.get(subjectKey(conversation)) ?? conversation)
+  const knownKeys = new Set(current.map(subjectKey))
+  return [...updated, ...incoming.filter((conversation) => !knownKeys.has(subjectKey(conversation)))]
+}
+
+export function participantInboxReducer(state: ParticipantInboxState, action: ParticipantInboxAction): ParticipantInboxState {
+  switch (action.type) {
+    case 'started':
+      return state.status === 'ready' ? state : { ...state, status: 'loading' }
+    case 'loaded':
+      return mergeFirstPage(state, action.conversations, action.nextCursor)
+    case 'appended':
+      return withCursor(state, appendUnique(state.conversations, action.conversations), action.nextCursor)
+    case 'markedRead': {
+      const target = subjectKey(action.subject)
+      return {
+        ...state,
+        conversations: state.conversations.map((conversation) =>
+          subjectKey(conversation) === target ? { ...conversation, unreadCount: 0 } : conversation,
+        ),
+      }
+    }
+    case 'failed':
+      return { ...state, status: 'error', error: action.error }
+  }
+}