@blogmcp/community 0.0.0-stage → 0.1.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,147 @@
-# 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);
+- `<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, 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).
+
+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` and `KbMyCommunity` 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)` and `mountMyCommunity(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.1.0/dist/blogmcp-community.global.js" nonce="…"></script>
+```
+
+The script build (`@blogmcp/community/global`) registers all three 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 |
+
+`routes` names your community pages: `statementPath` (with `{id}`), `myCommunityPath`, `rulesPath`,
+`reportPath` and `noticesPath`. 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/…`. 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.
+
+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.
+- 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)
+```