@blogmcp/community 0.1.0 → 0.3.0

package/src/core/badge.ts

@@ -0,0 +1,120 @@
+/**
+ * `<blogmcp-badge>`'s brain (m2-contracts.md §3.3, §3.10): the unread count of the member's notifications for a
+ * site's header. `me/get` once (who is viewing, the module's state); then `me/notifications/unread-count` at once
+ * when the page is visible, every `intervalMs` (60 s, never less) while it is visible, and again when it is shown again (`visibilitychange`). A
+ * visitor, a reader who never joined and a module that is `dark` get nothing: no count, no further request.
+ */
+import { reactive } from 'vue'
+import { isKnownModuleState, type CommunityCallOptions, type CommunityClient } from '@blogmcp/sdk/community'
+
+/** The badge's poll (the contract's 60 s). */
+export const BADGE_INTERVAL_MS = 60_000
+/** A count above it reads `99+`. */
+export const BADGE_MAX = 99
+
+export interface BadgeUi {
+  /** `hidden`: nothing to show (a visitor, no member, a dark module, or not decided yet). */
+  phase: 'pending' | 'hidden' | 'shown'
+  count: number
+}
+
+export interface BadgeController {
+  readonly state: BadgeUi
+  start(): Promise<void>
+  /** Read the count now (coalesced with one on its way). */
+  refresh(): Promise<void>
+  dispose(): void
+}
+
+export interface BadgeOptions {
+  client: CommunityClient
+  /**
+   * Default 60 s, and never more often (a smaller value above 0 reads as 60 s: the contract's rate per open tab);
+   * 0 or less = no poll (the count is read once and on visibility).
+   */
+  intervalMs?: number
+  /** Whether the page is visible now (default: document.visibilityState). */
+  visible?: () => boolean
+}
+
+/** The count as the badge shows it. */
+export const badgeText = (count: number): string => (count > BADGE_MAX ? `${BADGE_MAX}+` : String(count))
+
+export function createBadge(o: BadgeOptions): BadgeController {
+  const { client } = o
+  const asked = typeof o.intervalMs === 'number' && Number.isFinite(o.intervalMs) ? o.intervalMs : BADGE_INTERVAL_MS
+  const interval = asked > 0 ? Math.max(asked, BADGE_INTERVAL_MS) : 0
+  // `!== 'hidden'` as the discussion's head poll reads it: a browser without the API (or a prerendered page) counts.
+  const visible = o.visible ?? ((): boolean => typeof document === 'undefined' || document.visibilityState !== 'hidden')
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  const state = reactive<BadgeUi>({ phase: 'pending', count: 0 }) as BadgeUi
+  let disposed = false
+  let active = false
+  let timer: ReturnType<typeof setInterval> | null = null
+  let reading: Promise<void> | null = null
+
+  function stop(): void {
+    active = false
+    if (timer) clearInterval(timer)
+    timer = null
+    if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility)
+  }
+
+  function hide(): void {
+    state.phase = 'hidden'
+    state.count = 0
+    stop()
+  }
+
+  function refresh(): Promise<void> {
+    if (disposed || !active) return Promise.resolve()
+    reading ??= (async () => {
+      const r = await client.me.notifications.unreadCount(call)
+      if (disposed || !active) return
+      if (r.ok) {
+        state.count = Math.max(0, Math.floor(r.value.count))
+        state.phase = 'shown'
+        return
+      }
+      // The session ended (signed out elsewhere): nothing to count any more.
+      if (r.code === 'signIn') hide()
+      // Any other failure keeps what the badge shows; the next tick tries again.
+    })().finally(() => {
+      reading = null
+    })
+    return reading
+  }
+
+  function onVisibility(): void {
+    if (visible()) void refresh()
+  }
+
+  return {
+    state,
+    async start() {
+      const me = await client.me.get(call)
+      if (disposed) return
+      const moduleState = me.ok ? me.value.module?.state : undefined
+      // An unknown state reads as dark (the SDK's open enum); a kb-api older than M2 sends none: the badge counts.
+      const dark = moduleState !== undefined && (!isKnownModuleState(moduleState) || moduleState === 'dark')
+      if (!me.ok || me.value.needs.includes('sign_in') || !me.value.member || dark) return hide()
+      active = true
+      if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility)
+      if (interval > 0) {
+        timer = setInterval(() => {
+          if (visible()) void refresh()
+        }, interval)
+      }
+      // A tab opened in the background asks nothing until it is shown (the visibilitychange listener reads it then).
+      if (visible()) await refresh()
+    },
+    refresh,
+    dispose() {
+      if (disposed) return
+      disposed = true
+      stop()
+      abort.abort()
+    },
+  }
+}

package/src/core/centre.ts

@@ -0,0 +1,136 @@
+/**
+ * `<blogmcp-notification-centre>`'s brain (m2-contracts.md §3.3, §3.10): the member's notifications newest first —
+ * `me/notifications/list` with its cursor and the unread-only filter —, one marked read at a time or all at once
+ * (`mark-read { all: true }`). Codes only, never anything a member wrote: each row is the catalogue's sentence of
+ * its code, and its subject a link the host's routes build (a decision → its statement).
+ */
+import { reactive } from 'vue'
+import {
+  isKnownNotificationCode,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type NotificationItem,
+} from '@blogmcp/sdk/community'
+import type { TextRef } from './i18n'
+
+export type CentrePhase = 'idle' | 'loading' | 'ready' | 'failed' | 'signIn'
+
+export interface CentreUi {
+  phase: CentrePhase
+  failure: CommunityFailure | null
+  /** Known codes only (a code a newer kb-api sends is skipped, never shown raw). */
+  items: NotificationItem[]
+  nextCursor: string | null
+  unreadOnly: boolean
+  loadingMore: boolean
+  busy: Record<string, boolean>
+  announcement: TextRef | null
+  announceId: number
+}
+
+export interface NotificationCentreController {
+  readonly state: CentreUi
+  load(): Promise<void>
+  loadMore(): Promise<void>
+  setUnreadOnly(on: boolean): Promise<void>
+  markRead(id: string): Promise<void>
+  markAllRead(): Promise<void>
+  unread(): number
+  dispose(): void
+}
+
+export function createNotificationCentre(o: { client: CommunityClient }): NotificationCentreController {
+  const { client } = o
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  /** The list that is current: an older one still on its way (the filter changed meanwhile) is dropped. */
+  let ticket = 0
+  const state = reactive<CentreUi>({
+    phase: 'idle',
+    failure: null,
+    items: [],
+    nextCursor: null,
+    unreadOnly: false,
+    loadingMore: false,
+    busy: {},
+    announcement: null,
+    announceId: 0,
+  }) as CentreUi
+
+  const announce = (text: TextRef): void => {
+    state.announcement = text
+    state.announceId += 1
+  }
+  const failureRef = (f: CommunityFailure): TextRef => ({ key: `error.${f.code}` as TextRef['key'] })
+  const known = (items: readonly NotificationItem[]): NotificationItem[] => items.filter((n) => isKnownNotificationCode(n.code))
+
+  async function load(): Promise<void> {
+    const mine = ++ticket
+    state.phase = 'loading'
+    state.failure = null
+    const r = await client.me.notifications.list(state.unreadOnly ? { unreadOnly: true } : {}, call)
+    if (disposed || mine !== ticket) return
+    if (!r.ok) {
+      state.phase = r.code === 'signIn' ? 'signIn' : 'failed'
+      state.failure = r
+      return
+    }
+    state.items = known(r.value.items)
+    state.nextCursor = r.value.nextCursor
+    state.phase = 'ready'
+  }
+
+  return {
+    state,
+    load,
+    async loadMore() {
+      if (state.loadingMore || state.nextCursor === null || state.phase !== 'ready') return
+      const mine = ticket
+      state.loadingMore = true
+      const r = await client.me.notifications.list({ cursor: state.nextCursor, ...(state.unreadOnly ? { unreadOnly: true } : {}) }, call)
+      state.loadingMore = false
+      if (disposed || mine !== ticket) return
+      if (!r.ok) return announce(failureRef(r))
+      const seen = new Set(state.items.map((n) => n.id))
+      state.items = [...state.items, ...known(r.value.items).filter((n) => !seen.has(n.id))]
+      state.nextCursor = r.value.nextCursor
+    },
+    async setUnreadOnly(on) {
+      if (state.unreadOnly === on) return
+      state.unreadOnly = on
+      await load()
+    },
+    async markRead(id) {
+      const key = `read:${id}`
+      const item = state.items.find((n) => n.id === id)
+      if (!item || item.readAt !== null || state.busy[key]) return
+      state.busy[key] = true
+      const r = await client.me.notifications.markRead({ ids: [id] }, call)
+      delete state.busy[key]
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      const at = new Date().toISOString()
+      state.items = state.items.map((n) => (n.id === id ? { ...n, readAt: at } : n))
+    },
+    async markAllRead() {
+      // Nothing unread among the loaded rows and no older page: nothing to mark (older pages may hold unread rows).
+      if (state.busy.all || (!state.items.some((n) => n.readAt === null) && state.nextCursor === null)) return
+      state.busy.all = true
+      const r = await client.me.notifications.markRead({ all: true }, call)
+      delete state.busy.all
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      const at = new Date().toISOString()
+      // Under the unread-only filter nothing is left to show; otherwise every row reads as read.
+      state.items = state.unreadOnly ? [] : state.items.map((n) => (n.readAt === null ? { ...n, readAt: at } : n))
+      if (state.unreadOnly) state.nextCursor = null
+    },
+    unread: () => state.items.filter((n) => n.readAt === null).length,
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}

package/src/core/digest-token.ts

@@ -0,0 +1,26 @@
+/**
+ * The digest's unsubscribe token as `<blogmcp-member-settings>` takes it (m2-contracts.md §3.3, §9.4): from its OWN
+ * page's address only — `#u=` in `location.hash` when it mounts —, and the address bar cleared at once (the SDK's
+ * readDigestTokenFromHash, which also clears the router's copy in `history.state`). The token is never sent on load:
+ * the element POSTs it on the member's click only (a mail scanner that opens the link must not unsubscribe anyone).
+ *
+ * As with a notifier's receipt (receipt.ts), the element keeps what it took for itself; a later page of the same tab
+ * never inherits it.
+ */
+import { digestTokenFromHash, forgetDigestToken, readDigestTokenFromHash } from '@blogmcp/sdk/community'
+
+const taken = new WeakMap<object, string | null>()
+
+/** The token this element's page carries, or null (none, or a cut link). */
+export function digestTokenForElement(owner: object | null): string | null {
+  if (typeof location !== 'undefined' && location.hash.startsWith('#u=')) {
+    // This address's own token (a cut link is none, never an older one the window remembers); then the bar is cleared.
+    const token = digestTokenFromHash(location.hash)
+    readDigestTokenFromHash()
+    // The element keeps its own copy (below); the SDK's per-window memory is dropped at once, so no later mount offers it.
+    forgetDigestToken()
+    if (owner) taken.set(owner, token)
+    return token
+  }
+  return owner && taken.has(owner) ? (taken.get(owner) ?? null) : null
+}