@blogmcp/community 0.2.0 → 0.3.0

package/src/core/follow.ts

@@ -0,0 +1,139 @@
+/**
+ * The follow button's brain (m3-contracts.md §3.3, §4.3, §5.3; D-M3-4, B16): one target — a topic or an article
+ * discussion by its conversation id, or a category — and whether the member follows it.
+ *
+ *   - `me/follows/set { following: true }` needs a target the member may read now: anything else is the one `notFound`,
+ *     and the button says „not available" (`follow.unavailable`) and offers nothing more; `followLimit` above
+ *     COMMUNITY_FOLLOWS_MAX; a visitor's session is `signIn`.
+ *   - `me/follows/set { following: false }` never fails on its target (an unknown one answers `{ following: false }`): an
+ *     unfollow has no error path of its own — only the transport's (the request did not go), which leaves the state
+ *     as it was and says so like any write.
+ *   - The state the button starts from: what the page already knows (a topic's or a category's `following`, the host's
+ *     `following` attribute), else the member's follows (`me/follows/list`, read until the target is found or the list
+ *     ends — at most COMMUNITY_FOLLOWS_MAX rows, a few pages).
+ */
+import { reactive } from 'vue'
+import {
+  COMMUNITY_FOLLOWS_MAX,
+  followKeyOf,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type FollowTarget,
+} from '@blogmcp/sdk/community'
+import type { Lang, TextRef } from './i18n'
+import { failureText } from './outcomes'
+
+export type FollowPhase = 'idle' | 'loading' | 'ready' | 'signIn' | 'unavailable' | 'failed'
+
+export interface FollowUi {
+  phase: FollowPhase
+  following: boolean
+  busy: boolean
+  /** The last refusal of a click (the state stays as it was), or null. */
+  failure: CommunityFailure | null
+  announcement: TextRef | null
+  announceId: number
+}
+
+export interface FollowController {
+  readonly state: FollowUi
+  /** The state from what the page knows (`known`), else the member's follows. */
+  load(known?: boolean | null): Promise<void>
+  /** A newer `following` the page learnt (a topic re-read): taken unless a click is on its way. */
+  sync(following: boolean): void
+  toggle(): Promise<void>
+  dispose(): void
+}
+
+/** Pages of `me/follows/list` read for the state at most (COMMUNITY_FOLLOWS_MAX rows, whatever kb-api's page size). */
+const LIST_PAGES_MAX = 25
+
+export function createFollow(o: { client: CommunityClient; target: FollowTarget; lang: Lang }): FollowController {
+  const { client, target, lang } = o
+  const key = followKeyOf(target)
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  const state = reactive<FollowUi>({ phase: 'idle', following: false, busy: false, failure: null, announcement: null, announceId: 0 }) as FollowUi
+
+  const announce = (text: TextRef): void => {
+    state.announcement = text
+    state.announceId += 1
+  }
+
+  /** Whether the member follows the target, from their follows; null when that could not be read. */
+  async function readFollowing(): Promise<boolean | CommunityFailure> {
+    let cursor: string | null = null
+    let rows = 0
+    for (let page = 0; page < LIST_PAGES_MAX; page++) {
+      const r = await client.me.follows.list(cursor === null ? {} : { cursor }, call)
+      if (!r.ok) return r
+      for (const f of r.value.follows) if (followKeyOf(f) === key) return true
+      rows += r.value.follows.length
+      cursor = r.value.nextCursor
+      if (cursor === null || rows >= COMMUNITY_FOLLOWS_MAX) return false
+    }
+    return false
+  }
+
+  return {
+    state,
+    async load(known) {
+      state.failure = null
+      if (key === null) {
+        state.phase = 'unavailable'
+        return
+      }
+      if (typeof known === 'boolean') {
+        state.following = known
+        state.phase = 'ready'
+        return
+      }
+      state.phase = 'loading'
+      const r = await readFollowing()
+      if (disposed) return
+      if (typeof r === 'boolean') {
+        state.following = r
+        state.phase = 'ready'
+        return
+      }
+      state.phase = r.code === 'signIn' ? 'signIn' : 'failed'
+      state.failure = r
+    },
+    sync(following) {
+      if (!state.busy && state.phase === 'ready') state.following = following
+    },
+    async toggle() {
+      if (state.busy || state.phase !== 'ready' || key === null) return
+      const next = !state.following
+      state.busy = true
+      state.failure = null
+      const r = await client.me.follows.set({ target, following: next }, call)
+      state.busy = false
+      if (disposed) return
+      if (r.ok) {
+        state.following = r.value.following
+        announce({ key: r.value.following ? 'follow.followed' : 'follow.unfollowed' })
+        return
+      }
+      if (next && r.code === 'notFound') {
+        // Following needs a target the member may read now (B16): not available — the button offers nothing more.
+        state.phase = 'unavailable'
+        announce({ key: 'follow.unavailable' })
+        return
+      }
+      if (r.code === 'signIn') {
+        state.phase = 'signIn'
+        return
+      }
+      // An unfollow is never refused on its target; what is left is the transport or a quota: the state stays.
+      state.failure = r
+      announce(failureText(r, lang))
+    },
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}

package/src/core/forum-category.ts

@@ -0,0 +1,323 @@
+/**
+ * `<blogmcp-forum-category slug>`'s brain (m3-contracts.md §3.2, §3.3, §5.3): one category — its row of
+ * `forum/categories/list` (its description, who opens topics there, its mode, whether the member follows it) and its
+ * topics (`forum/topics/list` by the slug, the activity or the newest order, the forum's keyset cursor) — and the
+ * new-topic composer where the category takes topics from members (`forum/topics/create`: the title and the opening
+ * post as one text; the Russmedia confirmation, the cooldowns, the onboarding with the art. 9 consent a forum write
+ * needs, a pre-moderated topic waiting for review). In „Články" (kind `article_discussions`) the rows are the article
+ * discussions, and nothing is created there.
+ */
+import { reactive, shallowRef, type ShallowRef } from 'vue'
+import {
+  COMMUNITY_MESSAGE_MAX,
+  COMMUNITY_TOPICS_PAGE_SIZE,
+  forumTopicTitleOf,
+  knownTopicItemsOf,
+  newClientMsgId,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type ForumCategory,
+  type ForumSort,
+  type KnownTopicItem,
+  type MyState,
+} from '@blogmcp/sdk/community'
+import type { Draft } from './discussion'
+import { forumNoticesOf, isForumMember } from './forum-state'
+import type { Lang, TextRef } from './i18n'
+import { createOnboarding, type OnboardingModel } from './onboarding'
+import { failureEffect, failureText, waitUntilOf } from './outcomes'
+import { codePointLength, normalizeBody } from './text'
+
+export type CategoryPhase = 'loading' | 'ready' | 'failed' | 'hidden' | 'membersOnly' | 'notFound'
+
+/** The new topic's draft: the composer's, with its title. */
+export interface TopicDraft extends Draft {
+  title: string
+}
+
+export interface CategoryUi {
+  phase: CategoryPhase
+  failure: CommunityFailure | null
+  me: MyState | null
+  /** The category's row of the list (null when the list did not name it: the page header stays). */
+  category: ForumCategory | null
+  /** The page's own header of the category (its id, slug, name, kind). */
+  header: { id: string; slug: string; name: string; kind: string } | null
+  items: KnownTopicItem[]
+  nextCursor: string | null
+  sort: ForumSort
+  loadingMore: boolean
+  /** The list is read again (another order). */
+  sorting: boolean
+  composer: TopicDraft
+  /** The topic the member just opened (its link), and whether it waits for review. */
+  created: { conversationId: string; held: boolean } | null
+  /** kb-api said the category takes no topic from the member (TOPIC_CREATION_CLOSED). */
+  creationClosed: boolean
+  /**
+   * A write was refused BRAKED — by the forum's own brake (`surface: 'forum'`) or the module's (none named): the composer
+   * gives way to the pause until the category is read again.
+   */
+  brakedBy: 'forum' | 'module' | null
+  clock: number
+  announcement: TextRef | null
+  announceId: number
+}
+
+export interface CategoryController {
+  readonly state: CategoryUi
+  readonly onboarding: ShallowRef<OnboardingModel | null>
+  load(): Promise<void>
+  loadMore(): Promise<void>
+  setSort(sort: ForumSort): Promise<void>
+  /** The member may open a topic here now (the composer shows). */
+  canCreate(): boolean
+  /** Why the composer does not show where it would: the team's category, a pause, read_only — or null. */
+  notCreating(): 'team' | 'paused' | 'readOnly' | null
+  create(): Promise<void>
+  setConfirmed(code: string, checked: boolean): void
+  sendConfirmed(): Promise<void>
+  beginOnboarding(options?: { forceArt9?: boolean }): void
+  cancelOnboarding(): void
+  waitLeft(): number
+  dispose(): void
+}
+
+const emptyTopicDraft = (): TopicDraft => ({ title: '', body: '', sending: false, failure: null, confirm: null, waitUntil: null, clientMsgId: null })
+
+export function createCategory(o: {
+  client: CommunityClient
+  slug: string
+  lang: Lang
+  now?: () => number
+  onCreated?(topic: { conversationId: string; held: boolean }): void
+}): CategoryController {
+  const { client, lang } = o
+  const slug = o.slug.trim().toLowerCase()
+  const now = o.now ?? Date.now
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  let ticket = 0
+  let ticker: ReturnType<typeof setInterval> | null = null
+  const onboarding = shallowRef<OnboardingModel | null>(null)
+
+  const state = reactive<CategoryUi>({
+    phase: 'loading',
+    failure: null,
+    me: null,
+    category: null,
+    header: null,
+    items: [],
+    nextCursor: null,
+    sort: 'activity',
+    loadingMore: false,
+    sorting: false,
+    composer: emptyTopicDraft(),
+    created: null,
+    creationClosed: false,
+    brakedBy: null,
+    clock: now(),
+    announcement: null,
+    announceId: 0,
+  }) as CategoryUi
+
+  const announce = (text: TextRef): void => {
+    state.announcement = text
+    state.announceId += 1
+  }
+
+  function listFailed(f: CommunityFailure): void {
+    state.failure = f
+    if (f.code === 'surfaceOff') state.phase = 'hidden'
+    else if (f.code === 'membersOnly') state.phase = 'membersOnly'
+    else if (f.code === 'notFound') state.phase = 'notFound'
+    else if (state.phase !== 'ready') state.phase = 'failed'
+    else announce(failureText(f, lang))
+  }
+
+  /** The first page of the category's topics in the current order. */
+  async function firstPage(mine: number): Promise<boolean> {
+    const r = await client.forum.topics.list({ categorySlug: slug, sort: state.sort, limit: COMMUNITY_TOPICS_PAGE_SIZE }, call)
+    if (disposed || mine !== ticket) return false
+    if (!r.ok) {
+      listFailed(r)
+      return false
+    }
+    state.header = { ...r.value.category }
+    state.items = knownTopicItemsOf(r.value.items)
+    state.nextCursor = r.value.nextCursor
+    return true
+  }
+
+  async function load(): Promise<void> {
+    const mine = ++ticket
+    state.phase = 'loading'
+    state.failure = null
+    const [me, list, page] = await Promise.all([client.me.get(call), client.forum.categories.list(call), firstPage(mine)])
+    if (disposed || mine !== ticket) return
+    if (me.ok) state.me = me.value
+    if (list.ok) state.category = list.value.categories.find((c) => c.slug === slug) ?? null
+    state.brakedBy = null
+    if (page) state.phase = 'ready'
+  }
+
+  function startClock(): void {
+    state.clock = now()
+    if (ticker) return
+    ticker = setInterval(() => {
+      state.clock = now()
+      const d = state.composer
+      if (d.waitUntil !== null && d.waitUntil <= state.clock) {
+        d.waitUntil = null
+        if (d.failure && (d.failure.code === 'fast' || d.failure.code === 'quota')) d.failure = null
+      }
+      if (d.waitUntil === null && ticker) {
+        clearInterval(ticker)
+        ticker = null
+      }
+    }, 1000)
+  }
+
+  const waitLeft = (): number => {
+    const d = state.composer
+    return d.waitUntil === null ? 0 : Math.max(0, Math.ceil((d.waitUntil - Math.max(state.clock, now())) / 1000))
+  }
+
+  const isTopics = (): boolean => (state.category?.kind ?? state.header?.kind) === 'topics'
+
+  function notCreating(): 'team' | 'paused' | 'readOnly' | null {
+    if (!isTopics() || !isForumMember(state.me)) return null
+    if (state.category?.topicCreation !== 'members' || state.creationClosed) return 'team'
+    const notices = forumNoticesOf(state.me, now())
+    if (state.brakedBy !== null || notices.paused !== null) return 'paused'
+    if (notices.readOnly) return 'readOnly'
+    return null
+  }
+
+  const canCreate = (): boolean => state.phase === 'ready' && isTopics() && isForumMember(state.me) && state.category?.topicCreation === 'members' && notCreating() === null
+
+  function beginOnboarding(options: { forceArt9?: boolean } = {}): void {
+    if (onboarding.value || disposed) return
+    const model = createOnboarding({
+      client,
+      lang,
+      signal: abort.signal,
+      // A forum write needs the art. 9 consent whatever the tenant asks elsewhere (U14).
+      forceArt9: options.forceArt9 !== false,
+      onDone: (me) => {
+        state.me = me
+        onboarding.value = null
+        announce({ key: model.state.art9RefusedSent ? 'onboarding.art9RefusedDone' : 'onboarding.done' })
+      },
+      onSignIn: () => {
+        onboarding.value = null
+        void load()
+      },
+    })
+    onboarding.value = model
+    void model.load()
+  }
+
+  async function send(confirmations?: string[]): Promise<void> {
+    const d = state.composer
+    if (d.sending || waitLeft() > 0 || disposed || !state.category) return
+    const title = forumTopicTitleOf(d.title)
+    const body = normalizeBody(d.body)
+    if (title === null || body === '' || codePointLength(body) > COMMUNITY_MESSAGE_MAX) return
+    d.sending = true
+    d.failure = null
+    const clientMsgId = (d.clientMsgId ??= newClientMsgId())
+    const r = await client.forum.topics.create(
+      { categoryId: state.category.id, title, body, clientMsgId, languageCode: lang, ...(confirmations ? { confirmations } : {}) },
+      call,
+    )
+    if (disposed) return
+    d.sending = false
+    if (r.ok) {
+      const held = r.value.message.state === 'held'
+      state.composer = emptyTopicDraft()
+      state.created = { conversationId: r.value.topic.conversationId, held }
+      announce({ key: held ? 'topic.createdHeld' : 'topic.created' })
+      o.onCreated?.(state.created)
+      // The member's new topic heads the list (their own held one included: its author sees it, „čeká na kontrolu").
+      const mine = ++ticket
+      await firstPage(mine)
+      return
+    }
+    d.failure = r
+    switch (failureEffect(r.code)) {
+      case 'confirm':
+        if (r.codes && r.codes.length > 0) d.confirm = { codes: [...r.codes], checked: [] }
+        return
+      case 'wait':
+        d.waitUntil = waitUntilOf(r, now())
+        if (d.waitUntil !== null) startClock()
+        if (r.code === 'braked') state.brakedBy = r.surface === 'forum' ? 'forum' : 'module'
+        return
+      case 'onboard':
+        beginOnboarding({ forceArt9: true })
+        return
+      default:
+        if (r.code === 'topicCreationClosed') state.creationClosed = true
+        else if (r.code === 'membersOnly' || r.code === 'surfaceOff' || r.code === 'notFound') listFailed(r)
+        else if (r.code === 'readOnly' || r.code === 'signIn' || r.code === 'restricted' || r.code === 'suspended' || r.code === 'terminated') {
+          const me = await client.me.get(call)
+          if (!disposed && me.ok) state.me = me.value
+        }
+    }
+  }
+
+  return {
+    state,
+    onboarding,
+    load,
+    async loadMore() {
+      if (state.loadingMore || state.nextCursor === null || state.phase !== 'ready') return
+      const mine = ticket
+      state.loadingMore = true
+      const r = await client.forum.topics.list({ categorySlug: slug, sort: state.sort, cursor: state.nextCursor, limit: COMMUNITY_TOPICS_PAGE_SIZE }, call)
+      state.loadingMore = false
+      if (disposed || mine !== ticket) return
+      if (!r.ok) return listFailed(r)
+      const seen = new Set(state.items.map((i) => i.conversationId))
+      state.items = [...state.items, ...knownTopicItemsOf(r.value.items).filter((i) => !seen.has(i.conversationId))]
+      state.nextCursor = r.value.nextCursor
+    },
+    async setSort(sort) {
+      if (state.sort === sort || state.phase !== 'ready') return
+      state.sort = sort
+      const mine = ++ticket
+      state.sorting = true
+      await firstPage(mine)
+      if (mine === ticket) state.sorting = false
+    },
+    canCreate,
+    notCreating,
+    create: () => send(),
+    setConfirmed(code, checked) {
+      const c = state.composer.confirm
+      if (!c || !c.codes.includes(code)) return
+      const rest = c.checked.filter((x) => x !== code)
+      c.checked = checked ? [...rest, code] : rest
+    },
+    async sendConfirmed() {
+      const c = state.composer.confirm
+      if (!c || !c.codes.every((code) => c.checked.includes(code))) return
+      await send([...c.codes])
+    },
+    beginOnboarding,
+    cancelOnboarding() {
+      onboarding.value = null
+    },
+    waitLeft,
+    dispose() {
+      disposed = true
+      abort.abort()
+      if (ticker) clearInterval(ticker)
+      ticker = null
+      onboarding.value = null
+    },
+  }
+}

package/src/core/forum-search.ts

@@ -0,0 +1,153 @@
+/**
+ * `<blogmcp-forum-search>`'s brain (m3-contracts.md §3.2, §4.4, §5.3): the forum's search — topic titles and visible
+ * messages of topics and article discussions, for a member (anyone else: `membersOnly`), 20 hits a page and five pages
+ * at most (no deeper paging, no bulk read), a quota per call. The query is checked before it goes (forumSearchQueryOf:
+ * kb-api would refuse it and spend the quota); a hit is plain text — its title (null when withheld from the viewer)
+ * and a snippet of at most 200 characters. The forum's search box brings the query in the page's fragment (`#q=…`),
+ * which never reaches a server.
+ */
+import { reactive } from 'vue'
+import {
+  COMMUNITY_SEARCH_QUERY_MAX,
+  forumSearchQueryOf,
+  nextSearchPage,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type ForumCategory,
+  type ForumSearchResult,
+  type KnownForumSpace,
+} from '@blogmcp/sdk/community'
+
+export type SearchPhase = 'idle' | 'searching' | 'ready' | 'failed' | 'hidden' | 'membersOnly'
+
+export interface SearchUi {
+  phase: SearchPhase
+  failure: CommunityFailure | null
+  query: string
+  /** '' every space. */
+  space: KnownForumSpace | ''
+  /** '' every category. */
+  categoryId: string
+  /** The categories to narrow by (read once). */
+  categories: ForumCategory[]
+  /** The query is too short or too long to ask (said, nothing sent). */
+  invalid: 'short' | 'long' | null
+  results: ForumSearchResult[]
+  page: number
+  hasMore: boolean
+  loadingMore: boolean
+}
+
+export interface SearchController {
+  readonly state: SearchUi
+  /** The categories for the filter (and the forum's own refusals: a visitor learns the forum is for members). */
+  load(): Promise<void>
+  search(): Promise<void>
+  more(): Promise<void>
+  dispose(): void
+}
+
+/** The query a page's fragment carries (`#q=<encoded>`), or null. */
+export function queryFromHash(hash: string | null | undefined): string | null {
+  if (typeof hash !== 'string' || !hash.startsWith('#')) return null
+  for (const part of hash.slice(1).split('&')) {
+    if (!part.startsWith('q=')) continue
+    try {
+      const q = decodeURIComponent(part.slice(2).replace(/\+/g, ' '))
+      return q.length <= COMMUNITY_SEARCH_QUERY_MAX * 2 ? q : null
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/** The search page's link with the query in its fragment (the forum's search box), or null. */
+export function searchLink(searchPath: string, raw: string): string | null {
+  const q = forumSearchQueryOf(raw)
+  if (q === null || searchPath.includes('#')) return null
+  return `${searchPath}#q=${encodeURIComponent(q)}`
+}
+
+export function createSearch(o: { client: CommunityClient; query?: string | null }): SearchController {
+  const { client } = o
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  let ticket = 0
+  const state = reactive<SearchUi>({
+    phase: 'idle',
+    failure: null,
+    query: o.query ?? '',
+    space: '',
+    categoryId: '',
+    categories: [],
+    invalid: null,
+    results: [],
+    page: 0,
+    hasMore: false,
+    loadingMore: false,
+  }) as SearchUi
+
+  const refused = (f: CommunityFailure): void => {
+    state.failure = f
+    state.phase = f.code === 'surfaceOff' ? 'hidden' : f.code === 'membersOnly' ? 'membersOnly' : 'failed'
+  }
+
+  /** What the results on the page were asked with: „more" pages them, whatever was typed or chosen since. */
+  let asked: { query: string; categoryId?: string; space?: KnownForumSpace } | null = null
+
+  async function search(): Promise<void> {
+    const q = forumSearchQueryOf(state.query)
+    if (q === null) {
+      state.invalid = state.query.trim().length > COMMUNITY_SEARCH_QUERY_MAX ? 'long' : 'short'
+      return
+    }
+    state.invalid = null
+    const mine = ++ticket
+    state.phase = 'searching'
+    state.failure = null
+    const input = { query: q, ...(state.categoryId !== '' ? { categoryId: state.categoryId } : {}), ...(state.space !== '' ? { space: state.space } : {}) }
+    asked = input
+    const r = await client.forum.search({ ...input, page: 1 }, call)
+    if (disposed || mine !== ticket) return
+    if (!r.ok) return refused(r)
+    state.results = [...r.value.results]
+    state.page = r.value.page
+    state.hasMore = r.value.hasMore
+    state.phase = 'ready'
+  }
+
+  return {
+    state,
+    async load() {
+      const r = await client.forum.categories.list(call)
+      if (disposed) return
+      if (r.ok) state.categories = r.value.categories.filter((c) => c.kind === 'topics')
+      else if (r.code === 'membersOnly' || r.code === 'surfaceOff') refused(r)
+      if (forumSearchQueryOf(state.query) !== null && state.phase === 'idle') await search()
+    },
+    search,
+    async more() {
+      const next = nextSearchPage({ page: state.page, hasMore: state.hasMore })
+      if (next === null || asked === null || state.loadingMore || state.phase !== 'ready') return
+      const mine = ticket
+      state.loadingMore = true
+      const r = await client.forum.search({ ...asked, page: next }, call)
+      state.loadingMore = false
+      if (disposed || mine !== ticket) return
+      if (!r.ok) {
+        state.failure = r
+        return
+      }
+      state.results = [...state.results, ...r.value.results]
+      state.page = r.value.page
+      state.hasMore = r.value.hasMore
+    },
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}

package/src/core/forum-state.ts

@@ -0,0 +1,59 @@
+/**
+ * What every forum element reads out of `me/get` beside its own operation (m3-contracts.md §3.5, §4.8, §4.9, §5.3):
+ * the team's away mode (one sentence, `state.away`), the pause of the forum's writes — the module's brake (both
+ * surfaces: `state.braked`) or the forum's own (`state.forumBraked`; the article discussions go on) —, the module's
+ * `read_only` (the forum is one of its features), and what a `membersOnly` refusal asks of the viewer.
+ */
+import {
+  communityAwayOf,
+  isKnownModuleState,
+  isKnownNeed,
+  surfaceInfoOf,
+  type CommunityFailure,
+  type CommunityMessageKey,
+  type KnownNeed,
+  type MyState,
+} from '@blogmcp/sdk/community'
+
+export interface ForumNotices {
+  /** The team is away: new topics wait for review (`state.away`). */
+  away: boolean
+  /** The forum's writes are paused — the module's brake, or the forum's own — or not. */
+  paused: 'module' | 'forum' | null
+  /** The module is `read_only`: the forum takes no writes meanwhile (`error.readOnly`). */
+  readOnly: boolean
+}
+
+/** The notices of `me/get`'s module block, at `now`. */
+export function forumNoticesOf(me: MyState | null | undefined, now: number = Date.now()): ForumNotices {
+  const module = me?.module
+  if (!module) return { away: false, paused: null, readOnly: false }
+  const state = isKnownModuleState(module.state) ? module.state : 'dark'
+  const forumBrake = surfaceInfoOf(module, 'forum')?.brake ?? null
+  const forumBraked = forumBrake !== null && Date.parse(forumBrake.until) > now
+  return {
+    away: communityAwayOf(module, now) !== null,
+    paused: module.brake !== undefined || state === 'braked' ? 'module' : forumBraked ? 'forum' : null,
+    readOnly: state === 'read_only',
+  }
+}
+
+/** The sentence of a pause of the forum's writes. */
+export const pausedKey = (paused: ForumNotices['paused']): CommunityMessageKey | null =>
+  paused === 'module' ? 'state.braked' : paused === 'forum' ? 'state.forumBraked' : null
+
+/**
+ * What a `membersOnly` refusal asks of the viewer (§3.1 step 3): to join — a member session that has not finished its
+ * onboarding (`needs` `onboarding` or `reconsent_rules`) — or to sign in (a visitor, or a session the tenant does not
+ * admit as a member: `sign_in`, or no needs at all).
+ */
+export function membersOnlyAsk(failure: Pick<CommunityFailure, 'needs'> | null | undefined): 'join' | 'signIn' {
+  const needs: KnownNeed[] = (failure?.needs ?? []).filter(isKnownNeed)
+  return !needs.includes('sign_in') && (needs.includes('onboarding') || needs.includes('reconsent_rules')) ? 'join' : 'signIn'
+}
+
+/**
+ * Whether the viewer is a member who may take part (an onboarded member's session): me/get names a member and no
+ * need to sign in. The team at the keyboard reads the forum but writes through the KB admin.
+ */
+export const isForumMember = (me: MyState | null | undefined): boolean => !!me?.member && !me.needs.includes('sign_in')