@blogmcp/community 0.0.0-stage → 0.2.0

package/src/core/panel.ts

@@ -0,0 +1,446 @@
+/**
+ * `<blogmcp-my-community>`'s brain (m1-contracts.md §7.4, §8.3, §10.4; community.md §5): the reader's
+ * „Moje komunita" — the statements of reasons about their content (the art. 17(3) fields, the appeal within
+ * its window, an open appeal's state), their reports, their notifications, the art. 9 consent's withdrawal (and,
+ * M2 T9, a refused one given after all — the onboarding's art. 9 step, opened here), their blocks, the export (a JSON download) and the profile's deletion with its grace and cancel.
+ *
+ * With a decision id it shows that one statement (the host's statement page). With a notifier's receipt it
+ * shows that notice's status and appeal — `notices/status`, `notices/appeal`: no session needed for that.
+ */
+import { reactive, shallowRef, type ShallowRef } from 'vue'
+import {
+  COMMUNITY_APPEAL_MAX,
+  isKnownNotificationCode,
+  type AppealItem,
+  type BlockEntry,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type DecisionSummary,
+  type MemberExport,
+  type MyState,
+  type NoticeStatus,
+  type NotificationItem,
+  type OwnProfile,
+  type ReportItem,
+  type Statement,
+} from '@blogmcp/sdk/community'
+import { pickLang, type TextRef } from './i18n'
+import { createOnboarding, type OnboardingModel } from './onboarding'
+import { isDisplayNameOk, isHandleOk, normalizeHandle, normalizeName } from './names'
+import { codePointLength, normalizeBody } from './text'
+
+export type LoadPhase = 'idle' | 'loading' | 'ready' | 'failed'
+
+export interface AppealDraft {
+  body: string
+  sending: boolean
+  failure: CommunityFailure | null
+}
+
+export interface ProfileDraft {
+  displayName: string
+  handle: string
+  avatarPreset: string | null
+  sending: boolean
+  failure: CommunityFailure | null
+  fields: string[]
+}
+
+export interface PanelUi {
+  /** The member's part: `signIn` when the session cannot act as a member (or there is none). */
+  phase: LoadPhase | 'signIn'
+  failure: CommunityFailure | null
+  me: MyState | null
+  notifications: NotificationItem[]
+  decisions: DecisionSummary[]
+  appeals: AppealItem[]
+  reports: ReportItem[]
+  blocks: BlockEntry[]
+  /** The statement the page opens (`decision-id`). */
+  statement: { phase: LoadPhase | 'signIn'; value: Statement | null; failure: CommunityFailure | null; appeal: AppealDraft }
+  /** The notifier's part (`#t=` in the address). `missing`: a `#t=` that holds no receipt. */
+  notice: { phase: LoadPhase | 'missing'; value: NoticeStatus | null; failure: CommunityFailure | null; appeal: AppealDraft }
+  profile: ProfileDraft | null
+  /** The profile's deletion: its date once requested here (kb-api's MyState does not carry it). */
+  purgeAfter: string | null
+  exporting: boolean
+  busy: Record<string, boolean>
+  announcement: TextRef | null
+  announceId: number
+}
+
+export interface PanelController {
+  readonly state: PanelUi
+  /** The give-consent flow (the onboarding's art. 9 step), while it is open. */
+  readonly consent: ShallowRef<OnboardingModel | null>
+  /** The member's sections (me/get and the lists). */
+  loadMember(): Promise<void>
+  loadStatement(decisionId: string): Promise<void>
+  loadNotice(receipt: string | null): Promise<void>
+  unreadCount(): number
+  markAllRead(): Promise<void>
+  fileAppeal(): Promise<void>
+  withdrawAppeal(): Promise<void>
+  fileNoticeAppeal(): Promise<void>
+  withdrawNoticeAppeal(): Promise<void>
+  withdrawConsent(): Promise<boolean>
+  /** A refused art. 9 consent (`acceptances.art9Refused`): opens its step to give it after all. */
+  giveConsent(): void
+  closeConsent(): void
+  unblock(memberId: string): Promise<void>
+  editProfile(): void
+  cancelProfile(): void
+  saveProfile(): Promise<void>
+  /** `me/export` as a JSON file the browser saves (`save` does the download; tests pass their own). */
+  exportData(save: (data: MemberExport) => void): Promise<void>
+  erase(): Promise<boolean>
+  cancelErase(): Promise<void>
+  /** The member asked for the deletion (here or before). */
+  erasing(): boolean
+  appealLength(draft: AppealDraft): number
+  canAppealWith(draft: AppealDraft): boolean
+  dispose(): void
+}
+
+export interface PanelOptions {
+  client: CommunityClient
+  lang: string
+}
+
+const appealDraft = (): AppealDraft => ({ body: '', sending: false, failure: null })
+
+export function createPanel(o: PanelOptions): PanelController {
+  const { client } = o
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  const state = reactive<PanelUi>({
+    phase: 'idle',
+    failure: null,
+    me: null,
+    notifications: [],
+    decisions: [],
+    appeals: [],
+    reports: [],
+    blocks: [],
+    statement: { phase: 'idle', value: null, failure: null, appeal: appealDraft() },
+    notice: { phase: 'idle', value: null, failure: null, appeal: appealDraft() },
+    profile: null,
+    purgeAfter: null,
+    exporting: false,
+    busy: {},
+    announcement: null,
+    announceId: 0,
+  }) as PanelUi
+  let disposed = false
+  const consent = shallowRef<OnboardingModel | null>(null)
+
+  const announce = (text: TextRef): void => {
+    state.announcement = text
+    state.announceId += 1
+  }
+  const failureRef = (f: CommunityFailure): TextRef => ({ key: `error.${f.code}` as TextRef['key'] })
+
+  async function loadMember(): Promise<void> {
+    state.phase = 'loading'
+    state.failure = null
+    const me = await client.me.get(call)
+    if (disposed) return
+    if (!me.ok) {
+      if (me.code === 'signIn') {
+        state.phase = 'signIn'
+        return
+      }
+      state.phase = 'failed'
+      state.failure = me
+      return
+    }
+    state.me = me.value
+    if (me.value.needs.includes('sign_in')) {
+      state.phase = 'signIn'
+      return
+    }
+    if (!me.value.member) {
+      // Signed in, never joined: nothing of theirs to list yet.
+      state.phase = 'ready'
+      return
+    }
+    const [notifications, decisions, appeals, reports, blocks] = await Promise.all([
+      client.me.notifications.list({}, call),
+      client.me.decisions.list({}, call),
+      client.me.appeals.list(call),
+      client.me.reports.list(call),
+      client.blocks.list(call),
+    ])
+    if (disposed) return
+    if (notifications.ok) state.notifications = notifications.value.items.filter((n) => isKnownNotificationCode(n.code))
+    if (decisions.ok) state.decisions = [...decisions.value.items]
+    if (appeals.ok) state.appeals = [...appeals.value.items]
+    if (reports.ok) state.reports = [...reports.value.items]
+    if (blocks.ok) state.blocks = [...blocks.value.blocks]
+    const first = [notifications, decisions, appeals, reports, blocks].find((r) => !r.ok)
+    if (first && !first.ok) announce(failureRef(first))
+    state.phase = 'ready'
+  }
+
+  // The statement the page shows now, and its load: a host that reuses the element for another decision-id
+  // (client-side navigation) must never see the late answer for the one before (nor appeal that one there).
+  let statementId: string | null = null
+  let statementLoad = 0
+
+  async function loadStatement(decisionId: string): Promise<void> {
+    const ticket = ++statementLoad
+    if (decisionId !== statementId) {
+      // Another decision: nothing of the one before stays on its page — its text, the appeal typed under it.
+      statementId = decisionId
+      state.statement.value = null
+      state.statement.appeal = appealDraft()
+    }
+    state.statement.phase = 'loading'
+    state.statement.failure = null
+    const r = await client.me.decisions.get({ decisionId }, call)
+    if (disposed || ticket !== statementLoad) return
+    if (r.ok) {
+      state.statement.value = r.value
+      state.statement.phase = 'ready'
+      return
+    }
+    state.statement.failure = r
+    state.statement.phase = r.code === 'signIn' ? 'signIn' : 'failed'
+  }
+
+  async function loadNotice(receipt: string | null): Promise<void> {
+    if (receipt === null) {
+      state.notice.phase = 'missing'
+      return
+    }
+    state.notice.phase = 'loading'
+    state.notice.failure = null
+    const r = await client.notices.status({ receipt }, call)
+    if (disposed) return
+    if (r.ok) {
+      state.notice.value = r.value
+      state.notice.phase = 'ready'
+      return
+    }
+    state.notice.failure = r
+    state.notice.phase = 'failed'
+  }
+  // The receipt is the notifier's capability: kept in this closure only, never in the state a view renders.
+  let noticeReceipt: string | null = null
+
+  const appealLength = (d: AppealDraft): number => codePointLength(normalizeBody(d.body))
+  const canAppealWith = (d: AppealDraft): boolean => !d.sending && appealLength(d) > 0 && appealLength(d) <= COMMUNITY_APPEAL_MAX
+
+  function giveConsent(): void {
+    if (consent.value || disposed || !state.me?.member || state.me.acceptances.art9Refused !== true) return
+    const model = createOnboarding({
+      client,
+      lang: pickLang(o.lang),
+      signal: abort.signal,
+      offerArt9: true,
+      onDone: (me) => {
+        state.me = me
+        consent.value = null
+        // Only a consent in force is announced: the flow also closes when no step was left to ask (nothing sent).
+        if (me.acceptances.art9Consent === 'accepted') announce({ key: 'panel.art9Given' })
+      },
+      onSignIn: () => {
+        consent.value = null
+        state.phase = 'signIn'
+      },
+    })
+    consent.value = model
+    void model.load()
+  }
+
+  return {
+    state,
+    consent,
+    giveConsent,
+    closeConsent() {
+      consent.value = null
+    },
+    loadMember,
+    loadStatement,
+    async loadNotice(receipt) {
+      noticeReceipt = receipt
+      await loadNotice(receipt)
+    },
+    unreadCount: () => state.notifications.filter((n) => n.readAt === null).length,
+    async markAllRead() {
+      const ids = state.notifications.filter((n) => n.readAt === null).map((n) => n.id)
+      if (ids.length === 0 || state.busy.markRead) return
+      state.busy.markRead = true
+      const r = await client.me.notifications.markRead({ ids }, call)
+      delete state.busy.markRead
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      const at = new Date().toISOString()
+      state.notifications = state.notifications.map((n) => (ids.includes(n.id) ? { ...n, readAt: at } : n))
+    },
+    async fileAppeal() {
+      const s = state.statement
+      const d = s.appeal
+      if (!s.value || !s.value.canAppeal || !canAppealWith(d)) return
+      const decisionId = s.value.decisionId
+      d.sending = true
+      d.failure = null
+      const r = await client.me.appeals.file({ decisionId, body: normalizeBody(d.body) }, call)
+      d.sending = false
+      // The page moved on to another statement meanwhile: the answer is that one's no more.
+      if (disposed || decisionId !== statementId) return
+      if (!r.ok) {
+        d.failure = r
+        return
+      }
+      d.body = ''
+      announce({ key: 'statement.appealSent' })
+      await loadStatement(decisionId)
+    },
+    async withdrawAppeal() {
+      const s = state.statement
+      const open = s.value?.appeal
+      if (!s.value || !open || open.status !== 'open' || state.busy.withdraw) return
+      const decisionId = s.value.decisionId
+      state.busy.withdraw = true
+      const r = await client.me.appeals.withdraw({ appealId: open.appealId }, call)
+      delete state.busy.withdraw
+      if (disposed || decisionId !== statementId) return
+      if (!r.ok) return announce(failureRef(r))
+      announce({ key: 'statement.appealWithdrawn' })
+      await loadStatement(decisionId)
+    },
+    async fileNoticeAppeal() {
+      const n = state.notice
+      const d = n.appeal
+      if (!n.value || !n.value.appeal.canAppeal || noticeReceipt === null || !canAppealWith(d)) return
+      d.sending = true
+      d.failure = null
+      const r = await client.notices.appeal({ receipt: noticeReceipt, body: normalizeBody(d.body) }, call)
+      d.sending = false
+      if (disposed) return
+      if (!r.ok) {
+        d.failure = r
+        return
+      }
+      d.body = ''
+      announce({ key: 'notice.appealSent' })
+      await loadNotice(noticeReceipt)
+    },
+    async withdrawNoticeAppeal() {
+      if (!state.notice.value?.appeal.open || noticeReceipt === null || state.busy.noticeWithdraw) return
+      state.busy.noticeWithdraw = true
+      const r = await client.notices.withdrawAppeal({ receipt: noticeReceipt }, call)
+      delete state.busy.noticeWithdraw
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      announce({ key: 'statement.appealWithdrawn' })
+      await loadNotice(noticeReceipt)
+    },
+    async withdrawConsent() {
+      if (state.busy.consent) return false
+      state.busy.consent = true
+      const r = await client.me.consents.withdraw({ kind: 'art9_consent' }, call)
+      delete state.busy.consent
+      if (disposed) return false
+      if (!r.ok) {
+        announce(failureRef(r))
+        return false
+      }
+      if (state.me) state.me = { ...state.me, acceptances: { ...state.me.acceptances, art9Consent: r.value.state as MyState['acceptances']['rules'] } }
+      announce({ key: 'panel.art9Withdrawn' })
+      return true
+    },
+    async unblock(memberId) {
+      const key = `block:${memberId}`
+      if (state.busy[key]) return
+      state.busy[key] = true
+      const r = await client.blocks.set({ memberId, blocked: false }, call)
+      delete state.busy[key]
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      state.blocks = state.blocks.filter((b) => b.memberId !== memberId)
+      announce({ key: 'discussion.unblocked' })
+    },
+    editProfile() {
+      const p: OwnProfile | null | undefined = state.me?.profile
+      if (!p) return
+      state.profile = { displayName: p.displayName, handle: p.handle, avatarPreset: p.avatarPreset, sending: false, failure: null, fields: [] }
+    },
+    cancelProfile() {
+      state.profile = null
+    },
+    async saveProfile() {
+      const d = state.profile
+      const current = state.me?.profile
+      if (!d || !current || d.sending || !isDisplayNameOk(d.displayName) || !isHandleOk(d.handle) || normalizeHandle(d.handle) === '') return
+      const input: { displayName?: string; handle?: string; avatarPreset?: string | null } = {}
+      const name = normalizeName(d.displayName)
+      const handle = normalizeHandle(d.handle)
+      if (name !== current.displayName) input.displayName = name
+      if (handle !== current.handle) input.handle = handle
+      if (d.avatarPreset !== current.avatarPreset) input.avatarPreset = d.avatarPreset
+      if (Object.keys(input).length === 0) {
+        state.profile = null
+        return
+      }
+      d.sending = true
+      d.failure = null
+      d.fields = []
+      const r = await client.me.updateProfile(input, call)
+      d.sending = false
+      if (disposed) return
+      if (!r.ok) {
+        d.failure = r
+        d.fields = r.code === 'handle' ? ['handle'] : r.code === 'name' ? ['displayName'] : (r.fields ?? [])
+        return
+      }
+      // The form closes on the new values (the catalogue has no sentence for a saved profile).
+      if (state.me) state.me = { ...state.me, profile: r.value.profile }
+      state.profile = null
+    },
+    async exportData(save) {
+      if (state.exporting) return
+      state.exporting = true
+      const r = await client.me.export(call)
+      state.exporting = false
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      save(r.value)
+    },
+    async erase() {
+      if (state.busy.erase) return false
+      state.busy.erase = true
+      const r = await client.me.erase(call)
+      delete state.busy.erase
+      if (disposed) return false
+      if (!r.ok) {
+        announce(failureRef(r))
+        return false
+      }
+      state.purgeAfter = r.value.purgeAfter
+      if (state.me?.member) state.me = { ...state.me, member: { ...state.me.member, status: r.value.status } }
+      return true
+    },
+    async cancelErase() {
+      if (state.busy.erase) return
+      state.busy.erase = true
+      const r = await client.me.cancelErase(call)
+      delete state.busy.erase
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      state.purgeAfter = null
+      if (state.me?.member) state.me = { ...state.me, member: { ...state.me.member, status: r.value.status } }
+      announce({ key: 'panel.eraseCancelled' })
+    },
+    erasing: () => state.me?.member?.status === 'deletion_requested',
+    appealLength,
+    canAppealWith,
+    dispose() {
+      disposed = true
+      abort.abort()
+      consent.value = null
+    },
+  }
+}

package/src/core/profile.ts

@@ -0,0 +1,144 @@
+/**
+ * `<blogmcp-profile handle>`'s and `<blogmcp-welcome>`'s brains (m2-contracts.md §3.2, §3.10).
+ *
+ *   - The profile: `profile/get { handle }` — the public projection (the author, `memberSince` as `YYYY-MM`, the bio
+ *     as text, the trust level as its LABEL, never the number). kb-api answers a signed-in host session only; an
+ *     unknown handle, an erased member and one hidden from the viewer are the same `notFound`.
+ *   - The welcome page: the tenant's current rules (`legal/current`, their summary from `bodyJson` as the onboarding
+ *     shows it) and who is viewing (`me/get`: the profile link needs the member's handle).
+ */
+import { reactive } from 'vue'
+import {
+  COMMUNITY_HANDLE_RE,
+  communityRulesOf,
+  isKnownAuthor,
+  trustLabelMessageKey,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type CommunityMessageKey,
+  type CommunityRule,
+  type KnownAuthor,
+  type PublicProfile,
+} from '@blogmcp/sdk/community'
+
+export type LoadPhase = 'idle' | 'loading' | 'ready' | 'failed' | 'signIn' | 'notFound'
+
+export interface ProfileUi {
+  phase: LoadPhase
+  failure: CommunityFailure | null
+  author: KnownAuthor | null
+  memberSince: string | null
+  bio: string | null
+  /** The trust level's catalogue key (`trust.<n>`), or null for a label this SDK does not know. */
+  trustKey: CommunityMessageKey | null
+}
+
+export interface ProfileController {
+  readonly state: ProfileUi
+  load(handle: string): Promise<void>
+  dispose(): void
+}
+
+/** A handle as an attribute may give it (`@jana_n`, `Jana_N`): lower case, without the `@`; null for none. */
+export function handleOf(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const h = value.trim().replace(/^@/, '').toLowerCase()
+  return COMMUNITY_HANDLE_RE.test(h) ? h : null
+}
+
+export function createProfile(o: { client: CommunityClient }): ProfileController {
+  const { client } = o
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  let ticket = 0
+  const state = reactive<ProfileUi>({ phase: 'idle', failure: null, author: null, memberSince: null, bio: null, trustKey: null }) as ProfileUi
+
+  return {
+    state,
+    async load(handle) {
+      const mine = ++ticket
+      state.failure = null
+      state.author = null
+      state.memberSince = null
+      state.bio = null
+      state.trustKey = null
+      const h = handleOf(handle)
+      if (h === null) {
+        state.phase = 'notFound'
+        return
+      }
+      state.phase = 'loading'
+      const r = await client.profile.get({ handle: h }, call)
+      if (disposed || mine !== ticket) return
+      if (!r.ok) {
+        state.phase = r.code === 'signIn' ? 'signIn' : r.code === 'notFound' ? 'notFound' : 'failed'
+        state.failure = r
+        return
+      }
+      const p: PublicProfile = r.value
+      // A profile is a member's; an author of another kind (or one a newer kb-api added) is no profile to show.
+      if (!isKnownAuthor(p.author) || p.author.kind !== 'member' || p.author.memberId === null) {
+        state.phase = 'notFound'
+        return
+      }
+      state.author = p.author
+      state.memberSince = typeof p.memberSince === 'string' ? p.memberSince : null
+      state.bio = typeof p.bio === 'string' && p.bio.trim() !== '' ? p.bio : null
+      state.trustKey = trustLabelMessageKey(p.trustLabel)
+      state.phase = 'ready'
+    },
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}
+
+export interface WelcomeUi {
+  phase: 'idle' | 'loading' | 'ready'
+  rules: CommunityRule[]
+  /** The rules could not be read: the page still links them. */
+  rulesFailed: boolean
+  /** The signed-in member's handle (the profile link), or null for a visitor and a reader who never joined. */
+  handle: string | null
+  /** Nobody is signed in: the sign-in link takes the profile link's place. */
+  visitor: boolean
+}
+
+export interface WelcomeController {
+  readonly state: WelcomeUi
+  load(): Promise<void>
+  dispose(): void
+}
+
+export function createWelcome(o: { client: CommunityClient; lang: string }): WelcomeController {
+  const { client } = o
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  const state = reactive<WelcomeUi>({ phase: 'idle', rules: [], rulesFailed: false, handle: null, visitor: false }) as WelcomeUi
+
+  return {
+    state,
+    async load() {
+      state.phase = 'loading'
+      const [rules, me] = await Promise.all([client.legal.current({ kind: 'rules', locale: o.lang }, call), client.me.get(call)])
+      if (disposed) return
+      if (rules.ok) state.rules = communityRulesOf(rules.value.bodyJson)
+      else state.rulesFailed = true
+      if (me.ok) {
+        state.visitor = me.value.needs.includes('sign_in')
+        state.handle = me.value.member ? handleOf(me.value.profile?.handle) : null
+      } else {
+        state.visitor = me.code === 'signIn'
+      }
+      state.phase = 'ready'
+    },
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}