@blogmcp/community 0.0.0-stage → 0.1.0

package/src/core/onboarding.ts

@@ -0,0 +1,345 @@
+/**
+ * The light onboarding inside the discussion (m1-contracts.md §7.4.2, §10.4; community.md §4.4–§4.6): what a
+ * reader does once before their first comment, and again when the tenant's rules change or it starts to ask
+ * for the art. 9 consent. In order, only the steps still missing:
+ *
+ *   age      the age band, asked once and never offered again (`16_17`, `18_plus`); below the tenant's
+ *            minimum kb-api stores nothing and the reader is told from what age the discussion is open;
+ *   rules    the rules' summary (`legal/current` → `bodyJson`, text only) with a link to the full text, and
+ *            the acceptance;
+ *   art9     the art. 9 consent's text and the acceptance, when the tenant asks for it;
+ *   profile  the display name, the handle (kb-api makes one when none is given; the element shows what it
+ *            would be), an avatar preset.
+ *
+ * One `me/onboard` at the end carries them all; kb-api records only what is still missing, so a member who
+ * comes back for a newer rules text sends the band and the profile they already have untouched.
+ *
+ * kb-api records the acceptance of whatever CURRENT text id it is sent (§7.4.2), so a text id goes only for a text
+ * this model showed and the reader ticked: the rules text when the rules are a step, else none. A text published
+ * meanwhile, or the art. 9 consent switched on meanwhile, is kb-api's VALIDATION on that id: the steps are read
+ * again from me/get (a step may be new), the reader goes to the first one left, nothing goes until it is answered.
+ */
+import { reactive } from 'vue'
+import {
+  communityRulesOf,
+  isKnownNeed,
+  type AgeBand,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type CommunityRule,
+  type CurrentLegalText,
+  type MyState,
+  type OnboardInput,
+} from '@blogmcp/sdk/community'
+import type { Lang } from './i18n'
+import { isDisplayNameOk, isHandleOk, normalizeHandle, normalizeName, suggestedHandle } from './names'
+import { htmlToParagraphs } from './text'
+
+export type OnboardingStep = 'age' | 'rules' | 'art9' | 'profile'
+
+export type OnboardingPhase = 'loading' | 'ready' | 'sending' | 'done' | 'failed' | 'refused'
+
+export interface OnboardingState {
+  /** `refused`: the age band is below the minimum — nothing was stored, the reader may go on reading. */
+  phase: OnboardingPhase
+  steps: OnboardingStep[]
+  index: number
+  me: MyState | null
+  rulesText: CurrentLegalText | null
+  rules: CommunityRule[]
+  art9Text: CurrentLegalText | null
+  art9Paragraphs: string[]
+  /** The member accepted an older rules text; this one asks again. */
+  reconsent: boolean
+  ageBand: AgeBand | null
+  rulesAccepted: boolean
+  art9Accepted: boolean
+  displayName: string
+  handle: string
+  avatarPreset: string | null
+  failure: CommunityFailure | null
+  /** The fields a refusal named (`displayName`, `handle`, …). */
+  fields: string[]
+  /** The minimum age, once a refusal told it (a refused `16_17` means 18). */
+  minAge: number | null
+}
+
+export interface OnboardingModel {
+  readonly state: OnboardingState
+  load(): Promise<void>
+  step(): OnboardingStep | null
+  isLast(): boolean
+  canContinue(): boolean
+  /** The next step, or — on the last one — `me/onboard`. */
+  next(): Promise<void>
+  back(): void
+  suggestedHandle(): string | null
+  hasFieldError(field: string): boolean
+}
+
+export interface OnboardingOptions {
+  client: Pick<CommunityClient, 'me' | 'legal'>
+  lang: Lang
+  /** Called with the member's state once kb-api took the onboarding. */
+  onDone(state: MyState): void
+  /** The session cannot act as a member any more (signed out meanwhile). */
+  onSignIn(): void
+  /** The age band was below the tenant's minimum (AGE_BELOW_MINIMUM): kb-api kept nothing, the element keeps this. */
+  onRefused?(minAge: number): void
+  signal?: AbortSignal
+}
+
+const PROFILE_FIELDS = new Set(['displayName', 'handle', 'avatarPreset'])
+const TEXT_FIELDS = new Set(['rulesTextId', 'art9TextId'])
+
+/** What is still missing for this member, in order (MyState and its known needs). */
+function stepsOf(me: MyState, needs: readonly string[]): OnboardingStep[] {
+  const steps: OnboardingStep[] = []
+  if (!me.member?.ageBand) steps.push('age')
+  if (me.acceptances.rules !== 'accepted') steps.push('rules')
+  if (needs.includes('art9_consent')) steps.push('art9')
+  if (!me.profile) steps.push('profile')
+  return steps
+}
+
+/** The texts of the steps shown. */
+interface Texts {
+  rules: CurrentLegalText | null
+  art9: CurrentLegalText | null
+}
+
+/** One reading of what is left to ask: me/get, its steps, their texts. */
+interface Read {
+  me: MyState
+  steps: OnboardingStep[]
+  texts: Texts
+}
+
+export function createOnboarding(o: OnboardingOptions): OnboardingModel {
+  const call: CommunityCallOptions = o.signal ? { signal: o.signal } : {}
+  const state = reactive<OnboardingState>({
+    phase: 'loading',
+    steps: [],
+    index: 0,
+    me: null,
+    rulesText: null,
+    rules: [],
+    art9Text: null,
+    art9Paragraphs: [],
+    reconsent: false,
+    ageBand: null,
+    rulesAccepted: false,
+    art9Accepted: false,
+    displayName: '',
+    handle: '',
+    avatarPreset: null,
+    failure: null,
+    fields: [],
+    minAge: null,
+  }) as OnboardingState
+
+  const fail = (failure: CommunityFailure): void => {
+    state.failure = failure
+    state.phase = 'failed'
+  }
+
+  /** The texts of these steps — none for a step that is not one, so its id can never be sent; null when one fails. */
+  async function textsFor(steps: OnboardingStep[]): Promise<Texts | null> {
+    const [rules, art9] = await Promise.all([
+      steps.includes('rules') ? o.client.legal.current({ kind: 'rules', locale: o.lang }, call) : null,
+      steps.includes('art9') ? o.client.legal.current({ kind: 'art9_consent', locale: o.lang }, call) : null,
+    ])
+    for (const r of [rules, art9]) {
+      if (r && !r.ok) {
+        fail(r)
+        return null
+      }
+    }
+    return { rules: rules?.ok ? rules.value : null, art9: art9?.ok ? art9.value : null }
+  }
+
+  /** me/get and what it leaves to ask, with the texts; null when it went elsewhere (a failure, a signed-out session). */
+  async function read(): Promise<Read | null> {
+    const me = await o.client.me.get(call)
+    if (!me.ok) {
+      fail(me)
+      return null
+    }
+    const needs = me.value.needs.filter(isKnownNeed)
+    if (needs.includes('sign_in')) {
+      o.onSignIn()
+      return null
+    }
+    const steps = stepsOf(me.value, needs)
+    const texts = await textsFor(steps)
+    return texts ? { me: me.value, steps, texts } : null
+  }
+
+  /** What was read, shown at once; an acceptance holds only for the very text it was given to. */
+  function apply(r: Read): void {
+    if (r.texts.rules?.textId !== state.rulesText?.textId) state.rulesAccepted = false
+    if (r.texts.art9?.textId !== state.art9Text?.textId) state.art9Accepted = false
+    state.me = r.me
+    state.steps = r.steps
+    state.reconsent = r.me.acceptances.rules === 'reconsent_required'
+    state.rulesText = r.texts.rules
+    state.rules = r.texts.rules ? communityRulesOf(r.texts.rules.bodyJson) : []
+    state.art9Text = r.texts.art9
+    state.art9Paragraphs = r.texts.art9 ? htmlToParagraphs(r.texts.art9.body) : []
+  }
+
+  async function load(): Promise<void> {
+    state.phase = 'loading'
+    state.failure = null
+    const r = await read()
+    if (!r) return
+    apply(r)
+    state.index = 0
+    // Nothing left to ask (another tab finished it): kb-api's answer settles the needs.
+    if (r.steps.length === 0) return submit()
+    state.phase = 'ready'
+  }
+
+  const step = (): OnboardingStep | null => state.steps[state.index] ?? null
+
+  /** Whether a step has its answer (a text accepted is the text shown). */
+  function answered(s: OnboardingStep): boolean {
+    switch (s) {
+      case 'age':
+        return state.ageBand !== null
+      case 'rules':
+        return state.rulesAccepted && state.rulesText !== null
+      case 'art9':
+        return state.art9Accepted && state.art9Text !== null
+      case 'profile':
+        return isDisplayNameOk(state.displayName) && isHandleOk(state.handle)
+    }
+  }
+
+  function canContinue(): boolean {
+    const s = step()
+    return state.phase === 'ready' && s !== null && answered(s)
+  }
+
+  function goTo(s: OnboardingStep): void {
+    const i = state.steps.indexOf(s)
+    if (i >= 0) state.index = i
+  }
+
+  /** The first step without its answer, or -1. */
+  const firstOpen = (): number => state.steps.findIndex((s) => !answered(s))
+
+  async function submit(): Promise<void> {
+    // Every step shown has its answer before anything goes (a step a refusal added is still open).
+    const open = firstOpen()
+    if (open >= 0) {
+      state.index = open
+      return
+    }
+    state.phase = 'sending'
+    state.failure = null
+    state.fields = []
+    // kb-api records whatever current text id it gets: only the ones shown and ticked here go. The field itself is
+    // kb-api's schema's; empty is no text (checked only while the rules are still to accept, and then refused).
+    const input: OnboardInput = {
+      ageBand: state.ageBand ?? state.me?.member?.ageBand ?? '18_plus',
+      rulesTextId: state.steps.includes('rules') && state.rulesText ? state.rulesText.textId : '',
+    }
+    if (state.steps.includes('art9') && state.art9Text) input.art9TextId = state.art9Text.textId
+    if (state.steps.includes('profile')) {
+      input.displayName = normalizeName(state.displayName)
+      const handle = normalizeHandle(state.handle)
+      if (handle !== '') input.handle = handle
+      input.avatarPreset = state.avatarPreset
+    }
+    const r = await o.client.me.onboard(input, call)
+    if (r.ok) {
+      state.phase = 'done'
+      o.onDone(r.value)
+      return
+    }
+    state.failure = r
+    state.phase = 'ready'
+    switch (r.code) {
+      case 'age':
+        // Two bands only: a refused band is 16–17 under an 18 minimum.
+        state.minAge = 18
+        state.phase = 'refused'
+        o.onRefused?.(state.minAge)
+        return
+      case 'name':
+        state.fields = normalizeHandle(state.handle) !== '' ? ['displayName', 'handle'] : ['displayName']
+        return goTo('profile')
+      case 'handle':
+        state.fields = ['handle']
+        return goTo('profile')
+      case 'invalid': {
+        state.fields = r.fields ?? []
+        if (state.fields.some((f) => PROFILE_FIELDS.has(f))) return goTo('profile')
+        if (state.fields.some((f) => TEXT_FIELDS.has(f))) return reread(r)
+        if (state.fields.includes('ageBand')) return goTo('age')
+        return
+      }
+      case 'signIn':
+        return o.onSignIn()
+      default:
+        return
+    }
+  }
+
+  /**
+   * kb-api refused a text id: a newer text was published meanwhile, or the art. 9 consent was switched on. What is
+   * left is read again from me/get — a step may be new, with its text —, the acceptance of a text kb-api named is
+   * asked again, and the reader goes to the first step left. Nothing is sent again by itself.
+   */
+  async function reread(refusal: CommunityFailure): Promise<void> {
+    const named = [...state.fields]
+    // The form stays as it is (disabled) while the steps are read again.
+    state.phase = 'sending'
+    const r = await read()
+    if (!r) return
+    apply(r)
+    if (named.includes('rulesTextId')) state.rulesAccepted = false
+    if (named.includes('art9TextId')) state.art9Accepted = false
+    state.failure = refusal
+    state.fields = named
+    const open = firstOpen()
+    if (open >= 0) {
+      state.index = open
+      state.phase = 'ready'
+      return
+    }
+    // Nothing this model can still ask: finished elsewhere (no need left), or a refusal it cannot answer — shown.
+    if (r.me.needs.filter(isKnownNeed).length === 0) {
+      state.phase = 'done'
+      o.onDone(r.me)
+      return
+    }
+    fail(refusal)
+  }
+
+  return {
+    state,
+    load,
+    step,
+    isLast: () => state.index >= state.steps.length - 1,
+    canContinue,
+    async next() {
+      if (!canContinue()) return
+      state.failure = null
+      if (state.index < state.steps.length - 1) {
+        state.index += 1
+        return
+      }
+      await submit()
+    },
+    back() {
+      if (state.phase !== 'ready' || state.index === 0) return
+      state.failure = null
+      state.index -= 1
+    },
+    suggestedHandle: () => (normalizeHandle(state.handle) === '' ? suggestedHandle(state.displayName) : null),
+    hasFieldError: (field) => state.fields.includes(field),
+  }
+}

package/src/core/outcomes.ts

@@ -0,0 +1,74 @@
+/**
+ * How a refusal reads (m1-contracts.md §10.2, §10.4): the client turns every kb-api and host code into one
+ * of COMMUNITY_UI_CODES; this turns that into the catalogue's sentence — `error.<code>`, or a sanction's
+ * own sentence with its end date — and says what the element does about it besides showing it.
+ */
+import type { CommunityFailure, CommunityMessageKey, CommunityUiCode } from '@blogmcp/sdk/community'
+import { formatDate } from './format'
+import type { Lang, TextRef } from './i18n'
+
+/** The sentence a refusal shows. Total over COMMUNITY_UI_CODES (test/outcomes.spec.ts). */
+export function failureText(failure: Pick<CommunityFailure, 'code' | 'until'>, lang: Lang): TextRef {
+  const until = failure.until ? formatDate(lang, failure.until) : ''
+  if (failure.code === 'restricted' && until) return { key: 'sanction.restrictionUntil', params: { date: until } }
+  if (failure.code === 'suspended' && until) return { key: 'sanction.suspensionUntil', params: { date: until } }
+  return { key: `error.${failure.code}` as CommunityMessageKey }
+}
+
+/** Seconds a refusal asks to wait before the same write may go (the burst, a quota, the limiter). */
+export const DEFAULT_WAIT_S: Partial<Record<CommunityUiCode, number>> = Object.freeze({ fast: 3, quota: 60 })
+
+/** The epoch milliseconds until which a write waits after `failure`, or null when it may go again at once. */
+export function waitUntilOf(failure: Pick<CommunityFailure, 'code' | 'retryAfterS'>, now: number): number | null {
+  const fallback = DEFAULT_WAIT_S[failure.code]
+  if (fallback === undefined) return null
+  const seconds = typeof failure.retryAfterS === 'number' && failure.retryAfterS > 0 ? failure.retryAfterS : fallback
+  return now + seconds * 1000
+}
+
+/** A countdown shows only for a short wait (a quota until midnight reads `error.quota` alone). */
+export const COUNTDOWN_MAX_S = 120
+
+/**
+ * What the element does with a refusal of a write, besides showing its sentence:
+ *   - `confirm`  the author confirms the codes and sends again (the Russmedia confirmation);
+ *   - `wait`     the write waits (a cooldown);
+ *   - `onboard`  the inline onboarding opens (ONBOARDING_REQUIRED);
+ *   - `reload`   the discussion is read again (the viewer's state changed: a sanction, a session);
+ *   - `notMoved` the discussion does not take writes yet: one sentence instead of the composer;
+ *   - `hide`     discussions are switched off: the element renders nothing;
+ *   - `retry`    nothing was decided (no answer, the ledger): the same write may go again as it is;
+ *   - `show`     anything else: the sentence, the text stays for the author to change.
+ */
+export type FailureEffect = 'confirm' | 'wait' | 'onboard' | 'reload' | 'notMoved' | 'hide' | 'retry' | 'show'
+
+const EFFECTS: Readonly<Record<CommunityUiCode, FailureEffect>> = Object.freeze({
+  method: 'show',
+  origin: 'show',
+  unavailable: 'retry',
+  invalid: 'show',
+  signIn: 'reload',
+  onboarding: 'onboard',
+  age: 'show',
+  name: 'show',
+  handle: 'show',
+  restricted: 'reload',
+  suspended: 'reload',
+  terminated: 'reload',
+  links: 'show',
+  fast: 'wait',
+  blocked: 'show',
+  confirm: 'confirm',
+  removed: 'reload',
+  quota: 'wait',
+  captcha: 'show',
+  notFound: 'reload',
+  surfaceOff: 'hide',
+  notMoved: 'notMoved',
+  ledger: 'retry',
+  submit: 'show',
+} satisfies Record<CommunityUiCode, FailureEffect>)
+
+export function failureEffect(code: CommunityUiCode): FailureEffect {
+  return EFFECTS[code] ?? 'show'
+}