@blogmcp/community 0.0.0-stage → 0.2.0

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/client.ts

@@ -0,0 +1,54 @@
+/**
+ * The client an element talks through: the SDK's `createCommunityClient` over the HOST's relative base
+ * (`api-base`; default `/api/community` under the site's `site-base` — a headless site's BFF, the storefront's,
+ * or with `site-base="/blog"` a managed blog's own proxy). Never kb-api directly: its community namespaces answer
+ * no CORS (m1-contracts.md §7.1), and the client refuses an absolute base. On a managed blog the tenant host's
+ * `/api/` IS kb-api, so `/api/community` there would skip the blog's proxy and its session. An element with an
+ * unusable base warns once and renders nothing.
+ */
+import { createCommunityClient, isRelativeCommunityBase, type CommunityClient, type CommunityTransport } from '@blogmcp/sdk/community'
+import { siteBaseOf } from './attrs'
+
+/** The base the hosts serve the community under, below their site base (§12; the BFF's default basePath). */
+export const DEFAULT_API_BASE = '/api/community'
+
+const warned = new Set<string>()
+
+/**
+ * One console line per problem and page, for the site's developer — never a value from the page. The
+ * message starts with `[blogmcp-community]` (test/text-only.spec.ts tells developer lines from reader text
+ * by it).
+ */
+export function warnOnce(key: string, message: `[blogmcp-community] ${string}`): void {
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(message)
+}
+
+/**
+ * The `site-base` attribute as a path prefix ('' at the site's root), or null — the developer told once — when it
+ * is no path on this site.
+ */
+export function siteBaseFor(value: string | null | undefined): string | null {
+  const base = siteBaseOf(value)
+  if (base === null) warnOnce('site-base', '[blogmcp-community] site-base must be a path on this site (e.g. "/blog"), never a URL: the site’s pages and its proxy are found under it')
+  return base
+}
+
+/**
+ * The client for an element's `api-base` (and an injected transport), or null when the base is not a relative
+ * path. Without an `api-base`: `/api/community` under the site's base.
+ */
+export function communityClientFor(apiBase: string | null | undefined, transport?: CommunityTransport | null, siteBase = ''): CommunityClient | null {
+  const base = apiBase === undefined || apiBase === null || apiBase === '' ? `${siteBase}${DEFAULT_API_BASE}` : apiBase
+  if (!isRelativeCommunityBase(base)) {
+    warnOnce('api-base', '[blogmcp-community] api-base must be a path on this site (e.g. "/api/community"), never a URL: the community API is reached through the site’s own proxy or BFF')
+    return null
+  }
+  try {
+    return createCommunityClient(transport ? { base, transport } : { base })
+  } catch {
+    warnOnce('api-base', '[blogmcp-community] api-base was refused by the community client')
+    return null
+  }
+}

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
+}