@blogmcp/community 0.1.0 → 0.2.0

package/src/core/discussion.ts

@@ -8,8 +8,10 @@
  */
 import { reactive, shallowRef, type ShallowRef } from 'vue'
 import {
+  isKnownModuleState,
   COMMUNITY_MESSAGE_MAX,
   COMMUNITY_REPORT_NOTE_MAX,
+  communityMentionHandles,
   communityRulesOf,
   createDiscussionStore,
   findMessage,
@@ -40,6 +42,7 @@ import { warnOnce } from './client'
 import type { Lang, TextRef } from './i18n'
 import { createOnboarding, type OnboardingModel } from './onboarding'
 import { failureEffect, failureText, waitUntilOf } from './outcomes'
+import type { DiscussionRealtime, DiscussionRealtimeSession } from './realtime'
 import { codePointLength, normalizeBody } from './text'
 
 export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden'
@@ -86,9 +89,13 @@ export interface ReportDraft {
  * onboarding waits); `ageRefused` (the age band declared in it was below the minimum: reading only, the
  * onboarding is not offered again); `sanction` (a restriction, suspension or ban in effect); `notMoved` (the
  * discussion takes no writes yet — one sentence); `restricted` (the member is read-only or deleting their
- * profile); `pending` (being decided).
+ * profile); `braked` (M2: the community is paused — `me/get`'s `module.brake`, or a write refused BRAKED: reading
+ * goes on, every member write waits — one sentence); `pending` (being decided).
+ *
+ * A module that is `read_only` changes nothing here (m2-contracts.md §3.1: the discussions under articles keep
+ * taking writes; only live updates, push and the Pro surfaces stop) — the discussion polls instead of a socket.
  */
-export type ComposerMode = 'write' | 'signIn' | 'onboarding' | 'ageRefused' | 'sanction' | 'notMoved' | 'restricted' | 'pending'
+export type ComposerMode = 'write' | 'signIn' | 'onboarding' | 'ageRefused' | 'sanction' | 'notMoved' | 'restricted' | 'braked' | 'pending'
 
 export interface DiscussionUi {
   phase: DiscussionPhase
@@ -100,8 +107,8 @@ export interface DiscussionUi {
   /** A head poll saw messages the page does not show yet. */
   newMessages: boolean
   me: MyState | null
-  /** What a write or the member's state taught: no writes yet, or none for this member. */
-  block: 'notMoved' | 'restricted' | null
+  /** What a write or the member's state taught: no writes yet, none for this member, or a pause (BRAKED). */
+  block: 'notMoved' | 'restricted' | 'braked' | null
   composer: Draft
   inline: InlineDraft | null
   report: ReportDraft | null
@@ -117,6 +124,16 @@ export interface DiscussionUi {
    * (§7.4.2), so the element does: the onboarding is not offered again while it lives.
    */
   refusedAge: number | null
+  /**
+   * M2 T9: the onboarding just finished with the art. 9 consent refused (`public_write`): the composer says once,
+   * in view, what the refusal leaves (writing in the public discussion). Not kept beyond this element.
+   */
+  art9RefusedNote: boolean
+  /**
+   * M2 (§3.5): the live updates' session fell back to polling (live updates are off here, or the server cut the
+   * socket for good — 4501): the discussion says so once and keeps polling; it never opens the socket again itself.
+   */
+  realtimeOff: boolean
 }
 
 export interface DiscussionControllerOptions {
@@ -132,6 +149,11 @@ export interface DiscussionControllerOptions {
   refusedAge?: number | null
   /** The onboarding's age band was refused: the element keeps it for its next discussions. */
   onAgeRefused?(minAge: number): void
+  /**
+   * M2 (§3.5, §3.10): the host's live-updates session factory (`createRealtimeSession` of
+   * `@blogmcp/sdk/community/realtime`). Absent: the head poll, as before.
+   */
+  realtime?: DiscussionRealtime | null
 }
 
 export interface DiscussionController {
@@ -172,10 +194,19 @@ export interface DiscussionController {
   openReport(m: DiscussionMessage): void
   closeReport(): void
   submitReport(): Promise<void>
-  beginOnboarding(): void
+  /**
+   * The onboarding inline; `offerArt9` asks the art. 9 consent also of a member who refused it (`public_write`, M2 T9) —
+   * the give-consent link on their own message held until the consent.
+   */
+  beginOnboarding(options?: { offerArt9?: boolean }): void
   cancelOnboarding(): void
   /** Seconds a draft still waits (0 when it may go). */
   waitLeft(draft: Draft): number
+  /**
+   * M2 T10: the distinct `@handle`s one message of the viewer may carry (me/get's `caps.mentionsPerMessage`), or null
+   * when nothing is known to limit it (no member yet, an older kb-api, a module whose mentions notify nobody).
+   */
+  mentionCap(): number | null
   dispose(): void
 }
 
@@ -208,19 +239,28 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     clock: now(),
     busy: {},
     refusedAge: o.refusedAge ?? null,
+    art9RefusedNote: false,
+    realtimeOff: false,
   }) as DiscussionUi
   const unsubscribe = store.subscribe((s) => {
     state.thread = s
   })
   const onboarding = shallowRef<OnboardingModel | null>(null)
+  /** The open onboarding is the give-consent flow (read with `onboarding`, which it is set beside). */
+  let consentFlow = false
 
   let poller: DiscussionHeadPoller | null = null
+  let session: DiscussionRealtimeSession | null = null
   let inView = true
   let disposed = false
   let lastSync = 0
   let refreshing: Promise<void> | null = null
   let mePromise: Promise<void> | null = null
   let ticker: ReturnType<typeof setInterval> | null = null
+  /** The brake's end (its `until`, or a BRAKED refusal's): me/get is read again then. */
+  let brakeTimer: ReturnType<typeof setTimeout> | null = null
+  /** A BRAKED refusal's own end (epoch ms), while `state.block` is `braked` because of it; null: none given. */
+  let refusedBrakeUntil: number | null = null
   const interval = o.pollMs ?? 20_000
 
   function announce(text: TextRef): void {
@@ -232,26 +272,81 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     state.phase = 'hidden'
     poller?.stop()
     poller = null
+    session?.stop()
+    session = null
   }
 
   // ───────────────────────── loading ─────────────────────────
 
-  function ensureMe(): Promise<void> {
-    if (state.me) return Promise.resolve()
+  /** me/get once (`fresh`: again, keeping what is shown until the answer is in — the composer does not flicker). */
+  function ensureMe(fresh = false): Promise<void> {
+    if (state.me && !fresh) return Promise.resolve()
     mePromise ??= client.me.get(call).then((r) => {
       mePromise = null
-      if (r.ok && !disposed) state.me = r.value
+      if (!r.ok || disposed) return
+      state.me = r.value
+      scheduleBrakeEnd()
     })
     return mePromise
   }
 
-  /** canPost is false, nothing is needed and no sanction applies: the member's status says whether it is the cutover. */
+  /** The end of a brake as me/get states it (`module.brake.until`, or `module.until` of a braked module), epoch ms. */
+  function brakeEndOf(me: MyState | null): number | null {
+    const m = me?.module
+    if (!m) return null
+    const until = m.brake ? m.brake.until : isKnownModuleState(m.state) && m.state === 'braked' ? m.until : undefined
+    const at = typeof until === 'string' ? Date.parse(until) : NaN
+    return Number.isFinite(at) ? at : null
+  }
+
+  /**
+   * While the discussion is braked, a timer at the brake's end (the later of me/get's `until` and a refusal's): then
+   * me/get is read again and the composer comes back when the brake is over. A brake without an end waits for the
+   * next refresh (afterLoad reads me/get again while braked).
+   */
+  function scheduleBrakeEnd(): void {
+    if (brakeTimer) clearTimeout(brakeTimer)
+    brakeTimer = null
+    if (disposed) return
+    const ends: number[] = []
+    if (brakedNow()) {
+      const at = brakeEndOf(state.me)
+      if (at !== null) ends.push(at)
+    }
+    if (state.block === 'braked' && refusedBrakeUntil !== null) ends.push(refusedBrakeUntil)
+    if (ends.length === 0) return
+    // A second after the end (clocks differ by a little), within setTimeout's range; an end me/get still reports
+    // after it passed (the brake not lifted yet on kb-api's side) is asked again every 30 s, never in a tight loop.
+    const left = Math.max(...ends) - now()
+    const delay = left > 0 ? Math.min(left + 1000, 2_147_000_000) : 30_000
+    brakeTimer = setTimeout(() => {
+      brakeTimer = null
+      if (disposed) return
+      liftRefusedBrake()
+      void ensureMe(true)
+    }, delay)
+  }
+
+  /** A BRAKED refusal's block ends once its own end has passed (or it gave none): me/get decides from then on. */
+  function liftRefusedBrake(): void {
+    if (state.block !== 'braked') return
+    if (refusedBrakeUntil !== null && refusedBrakeUntil > now()) return
+    state.block = null
+    refusedBrakeUntil = null
+  }
+
+  /**
+   * canPost is false, nothing is needed and no sanction applies: a brake (M2 T10: kb-api's canPost is false while one
+   * is in effect — me/get, read again, names it, and the composer gives way to the brake's sentence), else the
+   * member's status says whether it is the cutover.
+   */
   function decideBlock(): void {
     const s = store.getState()
     if (s.viewer.canPost || viewerNeeds(s).any || s.viewer.restrictions.length > 0) return
-    void ensureMe().then(() => {
+    void ensureMe(state.block === null).then(() => {
       const me = state.me
       if (disposed || !me || store.getState().viewer.canPost) return
+      if (brakedNow()) return
       // An active member who may not post: the discussion takes no writes yet (the cutover).
       state.block = !me.member || me.member.status === 'active' ? 'notMoved' : 'restricted'
     })
@@ -259,8 +354,11 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   function afterLoad(): void {
     const s = store.getState()
-    if (s.viewer.canPost) state.block = null
-    if (s.viewer.memberId !== null) void ensureMe()
+    // A braked discussion asks me/get again on every refresh: the brake may be over (kb-api's canPost does not know it).
+    const wasBraked = state.block === 'braked' || brakedNow()
+    if (s.viewer.canPost && state.block !== 'braked') state.block = null
+    if (wasBraked) liftRefusedBrake()
+    if (s.viewer.memberId !== null) void ensureMe(wasBraked)
     decideBlock()
     // Finished elsewhere (another tab): nothing left to onboard.
     if (onboarding.value && !viewerNeeds(s).any && onboarding.value.state.phase !== 'sending') onboarding.value = null
@@ -341,6 +439,47 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     })
   }
 
+  /**
+   * Live updates (M2, §3.5): the host's session over this element's store, after the first list. Not for an anonymous
+   * reader (no host session: the token route refuses it) nor while `me/get` says the module offers none (`read_only`,
+   * `dark`, live updates not configured) — the head poll then, and no socket. The session falls back to polling by
+   * itself (`realtimeOff`, the server's terminal 4501) and the element never starts it again.
+   */
+  async function startRealtime(factory: DiscussionRealtime): Promise<void> {
+    if (session || disposed || state.phase === 'hidden') return
+    if (viewerNeeds(store.getState()).signIn) return startPolling()
+    await ensureMe()
+    // The discussion may have been hidden (SURFACE_OFF) while me/get was on its way.
+    if (disposed || session || (state.phase as DiscussionPhase) === 'hidden') return
+    if (state.me?.module && state.me.module.features.realtime !== true) return startPolling()
+    try {
+      session = factory({
+        client,
+        store,
+        languageCode: lang,
+        visible: () => documentVisible() && inView,
+        ...(interval > 0 ? { pollIntervalMs: interval } : {}),
+        onMode: (mode) => {
+          if (disposed) return
+          // Said once per fallback: live again (the SDK session reconnected) takes the sentence away.
+          if (mode === 'polling' && !state.realtimeOff) state.realtimeOff = true
+          else if (mode === 'live' && state.realtimeOff) state.realtimeOff = false
+        },
+      })
+    } catch {
+      warnOnce('realtime', '[blogmcp-community] the realtime property is not a session factory (createRealtimeSession of @blogmcp/sdk/community/realtime): the discussion polls')
+      session = null
+      startPolling()
+    }
+  }
+
+  /** The member's community is paused (`me/get`'s module.brake or state, M2 §3.1): every member write is refused. */
+  function brakedNow(): boolean {
+    const m = state.me?.module
+    if (!m) return false
+    return m.brake !== undefined || (isKnownModuleState(m.state) && m.state === 'braked')
+  }
+
   // ───────────────────────── who may do what ─────────────────────────
 
   function mode(): ComposerMode {
@@ -348,13 +487,30 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     const n = viewerNeeds(s)
     if (n.signIn) return 'signIn'
     if (state.block === 'notMoved') return 'notMoved'
+    if (state.block === 'braked' || brakedNow()) return 'braked'
     if (!s.viewer.canPost && s.viewer.restrictions.length > 0) return 'sanction'
     // A refused age band: the refusal stays where the composer was once the reader closed it.
     if (n.any) return state.refusedAge !== null && !onboarding.value ? 'ageRefused' : 'onboarding'
+    // The give-consent flow of a member who refused the consent (needs name none): its step where the composer was.
+    if (onboarding.value && consentFlow) return 'onboarding'
     if (state.block === 'restricted') return 'restricted'
     return s.viewer.canPost ? 'write' : 'pending'
   }
 
+  /** me/get's per-message mention cap, where kb-api applies it (a member, the module live or braked: §3.3). */
+  function mentionCap(): number | null {
+    const me = state.me
+    const cap = me?.caps?.mentionsPerMessage
+    const m = me?.module?.state
+    if (!me?.member || typeof cap !== 'number' || !Number.isSafeInteger(cap) || cap < 0) return null
+    return m === 'live' || m === 'braked' ? cap : null
+  }
+  /** The draft mentions more distinct handles than the cap (kb-api's count: as typed, whether they exist or not). */
+  const overMentionCap = (body: string): boolean => {
+    const cap = mentionCap()
+    return cap !== null && communityMentionHandles(body).length > cap
+  }
+
   const isOwn = (m: Pick<DiscussionMessage, 'author'>): boolean => isOwnMessage(state.thread, m)
   const settled = (m: DiscussionMessage): boolean => !m.pending && m.seq > 0
   const canWrite = (): boolean => mode() === 'write'
@@ -409,7 +565,14 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       case 'wait':
         if (d) {
           d.waitUntil = waitUntilOf(f, now())
-          startClock()
+          if (d.waitUntil !== null) startClock()
+        }
+        if (f.code === 'braked') {
+          // Paused (BRAKED): the composer gives way to the sentence until the brake's end; me/get is read again.
+          state.block = 'braked'
+          refusedBrakeUntil = waitUntilOf(f, now())
+          scheduleBrakeEnd()
+          void ensureMe(true)
         }
         return
       case 'onboard':
@@ -423,7 +586,8 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
         state.block = 'notMoved'
         return
       case 'hide':
-        return hide()
+        // Live updates switched off hide nothing: the discussion polls (no write answers it; a realtime route does).
+        return f.code === 'realtimeOff' ? undefined : hide()
       default:
         return
     }
@@ -440,6 +604,12 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     if (n.any) return beginOnboarding()
     const parent = target.kind === 'new' ? null : findMessage(state.thread, target.seq)
     if (target.kind !== 'new' && (!parent || !settled(parent))) return
+    // Too many mentions for the member's level: said before posting (the composer shows it as it is typed); kb-api's
+    // MENTION_LIMIT stays the rule.
+    if (overMentionCap(body)) {
+      d.failure = { ok: false, code: 'mentionLimit' }
+      return
+    }
 
     d.sending = true
     d.failure = null
@@ -581,12 +751,15 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   // ───────────────────────── onboarding ─────────────────────────
 
-  function beginOnboarding(): void {
+  function beginOnboarding(options: { offerArt9?: boolean } = {}): void {
     if (onboarding.value || disposed || state.refusedAge !== null) return
+    const offerArt9 = options.offerArt9 === true
+    consentFlow = offerArt9
     const model = createOnboarding({
       client,
       lang,
       signal: abort.signal,
+      ...(offerArt9 ? { offerArt9: true } : {}),
       onRefused: (minAge) => {
         state.refusedAge = minAge
         o.onAgeRefused?.(minAge)
@@ -594,7 +767,12 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       onDone: (me) => {
         state.me = me
         onboarding.value = null
-        announce({ key: 'onboarding.done' })
+        // A refused art. 9 consent (`public_write`): the member joined, and is told what the refusal leaves.
+        state.art9RefusedNote = model.state.art9RefusedSent
+        if (offerArt9) {
+          // The give-consent flow: announced only when a consent is in force (it also closes with nothing left to ask).
+          if (me.acceptances.art9Consent === 'accepted') announce({ key: 'panel.art9Given' })
+        } else announce({ key: model.state.art9RefusedSent ? 'onboarding.art9RefusedDone' : 'onboarding.done' })
         void refresh()
       },
       onSignIn: () => {
@@ -612,7 +790,8 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     onboarding,
     async start() {
       await refresh()
-      startPolling()
+      if (o.realtime && state.phase === 'ready') await startRealtime(o.realtime)
+      else startPolling()
     },
     refresh,
     loadMore,
@@ -626,8 +805,10 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       return parent !== null && settled(parent) && parent.state === 'visible'
     },
     canEdit: (m) => canWrite() && isOwn(m) && settled(m) && m.body !== null && (m.state === 'visible' || m.state === 'held'),
-    canDelete: (m) => state.thread.viewer.memberId !== null && isOwn(m) && settled(m) && m.body !== null && m.state !== 'deleted',
+    // Not under a brake: kb-api refuses `messages/delete` BRAKED too (assertNotBraked).
+    canDelete: (m) => state.thread.viewer.memberId !== null && mode() !== 'braked' && isOwn(m) && settled(m) && m.body !== null && m.state !== 'deleted',
     canReact: canWrite,
+    mentionCap,
     canReport: (m) => !viewerNeeds(state.thread).signIn && !isOwn(m) && settled(m) && m.body !== null && m.author.kind !== 'system',
     canReportAsNotifier: (m) => viewerNeeds(state.thread).signIn && settled(m) && m.body !== null && m.author.kind !== 'system',
     canBlock: (m) =>
@@ -682,9 +863,13 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       abort.abort()
       poller?.stop()
       poller = null
+      session?.stop()
+      session = null
       unsubscribe()
       if (ticker) clearInterval(ticker)
       ticker = null
+      if (brakeTimer) clearTimeout(brakeTimer)
+      brakeTimer = null
       onboarding.value = null
     },
   }

package/src/core/format.ts

@@ -31,6 +31,28 @@ export function formatDate(lang: Lang, iso: string | null | undefined, withTime
   return format(lang, withTime)?.format(new Date(at)) ?? iso
 }
 
+const months = new Map<Lang, Intl.DateTimeFormat | null>()
+
+/**
+ * A month as `profile/get`'s `memberSince` gives it (`YYYY-MM`, UTC) in the reader's language, in the form a date
+ * takes inside a sentence („Členem od října 2026", "Member since October 2026"): Intl formats the first of the month
+ * and the day is left out — a month on its own would be the nominative („říjen"). The value as it came when Intl has
+ * no words, '' for anything that is no month.
+ */
+export function formatMonth(lang: Lang, ym: string | null | undefined): string {
+  if (typeof ym !== 'string' || !/^\d{4}-(?:0[1-9]|1[0-2])$/.test(ym)) return ''
+  const f = cached(months, lang, (locale) => new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' }))
+  try {
+    const parts = f?.formatToParts(new Date(`${ym}-01T00:00:00.000Z`))
+    if (!parts) return ym
+    const day = parts.findIndex((p) => p.type === 'day')
+    const kept = parts.filter((_p, i) => i !== day && !(i === day + 1 && parts[i]!.type === 'literal'))
+    return kept.map((p) => p.value).join('').trim() || ym
+  } catch {
+    return ym
+  }
+}
+
 /** Whether an ISO timestamp lies in the past (an appeal window, a sanction's end). */
 export function isPast(iso: string | null | undefined, now: number = Date.now()): boolean {
   if (typeof iso !== 'string') return false