@blogmcp/community 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Zubal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,244 @@
-# Temporary Holding Version
+# @blogmcp/community
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The community elements for your own site, over `@blogmcp/sdk/community`:
+
+- `<blogmcp-discussion>`: the discussion under an article. A two-level thread, the composer, reactions,
+  reports, blocks, the inline onboarding, and the states of a member's own messages ("awaiting review",
+  removed, deleted). Where the tenant asks for the art. 9 consent, the onboarding asks it the way the tenant set
+  it in kb-api: one consent, or one per controller the consent text names, and a refusal that still lets the
+  member write in public where the tenant allows it. Your site passes nothing for this;
+- `<blogmcp-notice-form>`: the notice form for anyone, signed in or not (DSA art. 16), with Cloudflare
+  Turnstile;
+- `<blogmcp-my-community>`: the reader's „Moje komunita" panel. It holds statements of reasons and appeals,
+  reports, notifications, the consent (to withdraw it, or to give one the member refused), the export and the
+  profile's deletion. It also renders a statement
+  page (`decision-id`) and a notifier's status page (`#t=<receipt>` in the address).
+
+With the community module (M2) there are five more:
+
+- `<blogmcp-notification-centre>`: the member's notifications, newest first. Older ones load a page at a time,
+  „Jen nepřečtené" filters them, each one or all can be marked read, and each row links its subject where your
+  site has a page for it (a decision's statement, the settings, „Moje komunita"). It links your settings page;
+- `<blogmcp-badge>`: the unread count for your header, a link to the centre. It asks once who is viewing, then
+  the count every 60 s while the tab is visible and again when it is shown again. It renders nothing for a
+  visitor, a reader who never joined, a module that is off, or nothing unread;
+- `<blogmcp-member-settings>`: the six notification switches (replies, mentions, topics, browser notifications,
+  the daily e-mail digest, the quiet night 22:00–7:00), each saved on its own; this browser's notifications;
+  and the digest e-mail's unsubscribe link (below);
+- `<blogmcp-profile handle="…">`: a member's public profile: name, avatar, since when they are a member, the
+  bio as text and the trust level as a label („Nový člen", „Člen", „Stálý člen", „Moderátor"), never a number;
+- `<blogmcp-welcome>`: the page after joining: the rules in summary and three links (the discussions, the
+  settings, the member's own profile; a visitor gets your sign-in link instead).
+
+`<blogmcp-discussion>` also links every `@handle` in a comment to that member's profile page (for a signed-in
+reader; an anonymous one reads the mention as text), and takes live updates through its `realtime` property
+(below).
+
+Each element lives in a shadow root and renders text only. A member's links pass through `sanitizeUrl` and
+carry `rel="nofollow ugc noopener noreferrer"`. Every text comes from the SDK's catalogue
+(`communityMessage`), in Czech or English.
+
+## Your site's side: one relative base
+
+The elements never call kb-api. They POST to **your site's** relative base: `api-base`, by default
+`/api/community` under your `site-base` (the root when you set none):
+
+- a headless site or the storefront, served at the root: the BFF from `@blogmcp/sdk/community/server`,
+  mounted at `/api/community`;
+- a managed blog, served under `/blog`: its own `/api` proxy, so set `site-base="/blog"`. The element then
+  posts to `/blog/api/community`, and its default pages are `/blog/community/…`.
+
+> **On a managed blog, never `api-base="/api/community"`.** On the tenant's host, `/api/` is kb-api itself, not
+> the blog. A request there skips the blog's proxy, so it carries no reader session. Every reader reads as
+> signed out, every write is refused, and the notice form reaches no route. The defaults have the same trap:
+> without `site-base`, the links go to `/community/…`, outside the blog.
+
+```ts
+// e.g. app/routes/api/community.$.ts (POST only)
+import { createCommunityBff, communityServerEnv, fromWebRequest } from '@blogmcp/sdk/community/server'
+
+const bff = createCommunityBff({
+  // kb-api as your server reaches it, WITH the `/api` prefix your instance serves it under:
+  // KB_API_URL = https://<your instance>/api (or `${process.env.BLOGMCP_API_URL}/api`).
+  kbApiUrl: process.env.KB_API_URL!,
+  siteUrls: ['https://www.example.com'],
+  memberToken: async (http) => /* your session → the member's JWT, or null */ null,
+  ...communityServerEnv(process.env), // COMMUNITY_NOTICE_KEY
+})
+
+export async function action({ request }: { request: Request }) {
+  const { http, respond } = fromWebRequest(request)
+  return respond(await bff.handle(http))
+}
+```
+
+An absolute `api-base` (or `site-base`) is refused, and the element renders nothing: kb-api's community
+routes answer no CORS.
+
+## Mount the elements
+
+**Vue / Nuxt**
+
+```vue
+<script setup lang="ts">
+import { KbDiscussion } from '@blogmcp/community/vue'
+</script>
+<template>
+  <article>…</article>
+  <KbDiscussion :article-id="article.id" api-base="/api/community" sign-in-href="/prihlaseni" />
+</template>
+```
+
+**React / Next.js**
+
+```tsx
+import { KbDiscussion } from '@blogmcp/community/react' // a client component
+
+<KbDiscussion articleId={article.id} apiBase="/api/community" signInHref="/sign-in" />
+```
+
+`KbNoticeForm`, `KbMyCommunity`, `KbNotificationCentre`, `KbBadge`, `KbMemberSettings`, `KbProfile` and
+`KbWelcome` work the same way. Each wrapper mounts its element after hydration and
+removes it on unmount. It renders a single empty `<div data-blogmcp-community="…">` as the mount point: the
+discussion is part of the page's flow, so the element goes where the wrapper is.
+
+`mountDiscussion(o)`, `mountNoticeForm(o)`, `mountMyCommunity(o)`, `mountNotificationCentre(o)`, `mountBadge(o)`,
+`mountMemberSettings(o)`, `mountProfile(o)` and `mountWelcome(o)` do the same from any client-side hook. Each
+returns the unmount function.
+
+**Plain HTML**
+
+```html
+<blogmcp-discussion article-id="…" api-base="/api/community" sign-in-href="/prihlaseni"></blogmcp-discussion>
+<script src="https://cdn.jsdelivr.net/npm/@blogmcp/community@0.2.0/dist/blogmcp-community.global.js" nonce="…"></script>
+```
+
+The script build (`@blogmcp/community/global`) registers all eight elements. It exposes
+`window.BlogmcpCommunity` and gives the elements its own `nonce`.
+
+## Attributes
+
+| Element | Attribute | |
+|---|---|---|
+| all | `api-base` | your relative base (default `/api/community` under `site-base`) |
+| all | `site-base` | the path your site is served under (`/blog` on a managed blog); the defaults go under it |
+| all | `lang` | `cs` or `en` (`sk` reads Czech); default `<html lang>` |
+| all | `routes` | JSON with your pages (below) |
+| all | `nonce` | CSP nonce for the element's stylesheet and the Turnstile script |
+| `<blogmcp-discussion>` | `article-id` | the article |
+| | `sign-in-href` | your sign-in page; the current path goes in its fragment |
+| | `poll-ms` | how often to check for new comments while the discussion is in view (default 20000; 0 = off) |
+| `<blogmcp-notice-form>` | `target` | JSON: `{ conversationId, seq }`, `{ memberId }`, `{ handle }` or `{ articleId }` |
+| | `article-id` | or the article; without either, the discussion's report link (`#c=…&s=…`). With no target at all, the element shows where a report starts and links to `rulesPath` instead of the form |
+| | `turnstile-site-key` | your Turnstile site key; without it no widget renders |
+| `<blogmcp-my-community>` | `decision-id` | open this statement of reasons |
+| | `sign-in-href` | your sign-in page |
+| `<blogmcp-notification-centre>` | `sign-in-href` | your sign-in page (a visitor's link) |
+| `<blogmcp-badge>` | `poll-ms` | how often to read the count while the tab is visible (default 60000, and never less — a smaller value reads as 60000; 0 = once, and when the tab is shown again) |
+| `<blogmcp-member-settings>` | `sw-path` | your service worker route (default `${site-base}/sw.js`) |
+| | `sign-in-href` | your sign-in page |
+| `<blogmcp-profile>` | `handle` | the member's handle (an `@` in front is fine) |
+| | `sign-in-href` | your sign-in page (profiles are for signed-in readers) |
+| `<blogmcp-welcome>` | `sign-in-href` | your sign-in page (in the profile link's place, for a visitor) |
+
+`routes` names your community pages: `statementPath` (with `{id}`), `myCommunityPath`, `rulesPath`,
+`reportPath`, `noticesPath` and, with the module, `profilePath` (with `{handle}`), `settingsPath`,
+`notificationsPath`, `welcomePath` and `discussionsPath`. Each is a full path on your site, used as it is. A page you leave out
+falls back to the managed blog's pages: `${site-base}/community/…`. `articlePath` (with `{slug}`; no default)
+is your article page — the managed blogs' `/blog/articles/{slug}`, a shop's `/blog/{slug}`: the notification
+centre links a reply or a mention to its message there (`…/<slug>#bcm-msg-<seq>`), and without it those rows stay
+text. The discussion gives every message the anchor `bcm-msg-<seq>` and, opened at one, scrolls to it itself once
+its first page is in (the rows live in a shadow root, where the browser's own jump cannot reach). The tenant's own statement and „Moje
+komunita" paths, set in its community settings, come before that fallback.
+`consultationPath` (no default) turns the regulated preset's adverse-event note into a link to your
+consultation page.
+The receipt in a status link always goes in the fragment (`#t=…`). The page clears it from the address bar
+as soon as it reads it.
+
+A `transport` property replaces the HTTP layer, for tests.
+
+## Live updates (`realtime`)
+
+The discussion keeps itself fresh by polling. For live updates, import the SDK's realtime entry yourself and pass
+its `createRealtimeSession` as the discussion's `realtime` property (a property, never an attribute). Your bundle
+then needs `centrifuge` (≥ 5.7), the entry's peer dependency; the elements never import either, so a site
+without it ships no socket code.
+
+```ts
+import { createRealtimeSession } from '@blogmcp/sdk/community/realtime'
+import { KbDiscussion } from '@blogmcp/community/react'
+
+<KbDiscussion articleId={article.id} apiBase="/api/community" realtime={createRealtimeSession} />
+// plain: document.querySelector('blogmcp-discussion').realtime = createRealtimeSession
+```
+
+The element starts the session over its own discussion after the first page is read, and stops it when it
+unmounts. It starts none for an anonymous reader, nor while the community's live updates are off (the module is
+`read_only` or off, or the instance runs no realtime): the discussion polls then, with no socket. A session that
+falls back to polling — kb-api answers `REALTIME_OFF`, or the server ends the connection for good — makes the
+discussion say once that live updates are off; it is never reopened. When the session was revoked (4501), the
+session asks kb-api for a fresh token once first: a member whose own password change ended the old session keeps
+the page live under the new one; a refusal, or a second 4501, falls back for good. While the socket cannot get
+through (the subscription is not live 15 s after connecting, or after the connection dropped), the discussion polls
+meanwhile and says so once; Centrifuge keeps reconnecting, and the sentence goes when it is live again. An article
+without comments yet has no channel to subscribe to: it polls for the first one and is never called off for that.
+
+The composer knows the member's mention limit (`me/get`'s `caps.mentionsPerMessage`, by trust level): a comment
+that mentions more distinct `@handle`s says so as it is typed and is not sent (kb-api refuses it too).
+
+The URL to connect to comes from kb-api's token answer (the instance's own host, `/rt/…`), never from your
+configuration.
+
+## Browser notifications and the digest's unsubscribe link
+
+`<blogmcp-member-settings>` shows this browser's notifications only while the community offers them. „Zapnout
+upozornění" (the member's click; nothing is registered on page load) registers **your** service worker at
+`sw-path`, asks the member's permission, subscribes the browser and hands the subscription to kb-api; „Vypnout"
+ends it. Serve the worker from `@blogmcp/sdk/community/sw` (`communityServiceWorkerSource`, as
+`COMMUNITY_SW_CONTENT_TYPE`, `Cache-Control: no-cache`) at that route, and the manifest from
+`@blogmcp/sdk/community/manifest`. Inside Facebook's or Instagram's app the element offers „Otevřít v prohlížeči"
+with the page's URL instead; on an iPhone or iPad it explains that the site must be added to the home screen first.
+After a key rotation (or kb-api's „switch it on again" notice) it asks the member to switch them on again. The
+switch reads on only for a subscription this member made in this browser (a shared browser shows another member's
+as off) and that kb-api still holds: with the permission granted, the element asks kb-api on load whether it still
+holds this browser's endpoint (`me/push/status` — a read: no worker registered, no permission asked, nothing
+subscribed). kb-api drops a subscription after a sign-out everywhere or a dead endpoint without telling the page;
+the switch then reads off and stays off until the member presses „Zapnout upozornění" — a sign-out everywhere never
+brings notifications back on its own. When kb-api cannot answer (the status, or the current key's `me/push/vapid` that is checked first), the switch
+reads off too, without a sentence. The element also clears `#u=` from the address when
+it is misconfigured and renders nothing.
+
+The digest e-mail links to your settings page with the unsubscribe token in the fragment (`#u=…`). The element
+reads it once, clears it from the address bar, and sends it only when the member clicks „Odhlásit denní souhrn"
+(a mail scanner that opens the link unsubscribes nobody). That works without a session. Route your settings page
+(`settingsPath`) where kb-api's e-mails point.
+
+Events (bubbling, composed):
+- `bcm-posted`, `{ state: 'visible' | 'held' }`: the reader's comment went out;
+- `bcm-notice-submitted`, `{ contactKept }`: a notice was received.
+
+## Look
+
+Theme the elements with the custom properties on them: `blogmcp-discussion { --bcm-accent: #2b7a4b }`.
+The properties are `--bcm-bg`, `-fg`, `-muted`, `-line`, `-soft`, `-accent`, `-accent-fg`, `-danger`,
+`-ok`, `-warn-bg`, `-shadow` and `-z`, plus `--bcm-font` and `--bcm-font-size`. Dark mode follows
+`prefers-color-scheme`.
+
+## Content Security Policy
+
+- The styles are one `<style>` in each shadow root, carrying the nonce you pass.
+- `connect-src 'self'` is enough: the elements only talk to your own base. With live updates on a headless
+  site, add your instance's host (`https://<instance host>` and `wss://<instance host>`): the socket goes there.
+- Browser notifications need `worker-src 'self'` (and `manifest-src 'self'` for the manifest).
+- The notice form with Turnstile needs `script-src` and `frame-src` for `https://challenges.cloudflare.com`.
+  Only a page with the notice form loads that script.
+
+## Development
+
+```bash
+npm run build       # ESM + the <script> build (+ size budget, 200 KiB gzip)
+npm test            # vitest (happy-dom): controllers, store, onboarding, outcomes, elements, text-only and closed-path scans
+npm run test:e2e    # Playwright: desktop + iPhone profile + a plain bundler, mocked community API (ports 8286/8287);
+                    # m2.e2e.ts drives the centre (its link to a reply's message), the badge, the settings,
+                    # a profile, the welcome page and the composer's mention limit
+```