@hermesihq/react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -19,6 +19,39 @@ at least one real integration exists.
 Each release lists breaking changes first, because that is the only section that
 decides whether an upgrade is a decision or a formality.
 
+## 0.2.0 (2026-09-30)
+
+No breaking changes, and nothing to change in your code: everything this package exported
+before it exports now, from the same place.
+
+**The client and the state moved into a new package, `@hermesihq/js`, which this one now
+depends on.** The list, count and preference state that lived inside the hooks is now held
+in framework-free stores, and the hooks are a thin binding over them. That is what lets a
+Vue, Angular or plain JavaScript page use the same code. You do not need to install or
+import `@hermesihq/js` yourself; `HermsClient`, `HermsApiError`, `HERMS_CHANNELS` and the
+rest are still exported from here. If you also import `@hermesihq/js` directly, npm
+installs one shared copy, so both see the same `HermsClient` class.
+
+Four things a consumer can notice:
+
+- **A further page for the previous filter no longer lands in the new list.** With
+  `useInbox`, switching tabs while "load more" was in flight could append the old tab's
+  rows to the new tab's list. Any response that arrives after the list was reloaded, the
+  filter changed or the hook unmounted is now discarded.
+- **A load's result and its loading flag now change together.** The rows, or the error,
+  used to be published one update before `isLoading` cleared, so a component that
+  renders on every update could briefly show "failed and still loading" or "here are
+  your rows and still loading".
+- **The functions `useInbox` and `usePreferences` return keep their identity.**
+  `loadMore`, `markRead`, `archive` and the rest used to be recreated whenever
+  `isLoadingMore` or `hasMore` changed, so a `useCallback` or `memo` listing one re-ran
+  on every page.
+- **Two providers over one client no longer close each other's connection.** The
+  real-time stream is reference-counted: it opens for the first and closes with the last.
+
+A listener that throws is now reported to the host without stopping the other listeners
+or corrupting the state it was notified about.
+
 ## 0.1.0 (2026-09-28)
 
 The first published release. Nothing precedes it, so there is nothing to migrate from

package/README.md

@@ -1,128 +1,120 @@
 # @hermesihq/react
 
-Hermesi's embeddable inbox SDK: a framework-agnostic
-`HermsClient` core plus React bindings (`<HermsProvider>`, `useUnreadCount()`,
-`useInbox()`, `<HermsInbox />`).
-
-## Scope of this package, honestly
-
-This repo has no monorepo tooling (no pnpm/Turborepo workspaces, no root
-`package.json`). The dashboard (`frontend/`) still consumes this package as
-TypeScript source in development, via a `resolve.alias` in
-`frontend/vite.config.ts` (for the real bundler) and a matching `paths` entry
-in `frontend/tsconfig.app.json` (for `tsc -b`), not through `node_modules`,
-and not via a `file:` dependency. That wiring is deliberately left as-is: the
-dashboard isn't this package's audience, external integrators are, and
-changing how the dashboard resolves its own in-repo copy isn't needed to make
-*this package* installable elsewhere.
-
-`npm run build` now runs `tsup` (`tsup.config.ts`), which really does produce
-`dist/index.js` (ESM), `dist/index.cjs` (CJS), `dist/index.d.ts`/`.d.cts`, and
-`dist/index.css` (extracted from `HermsInbox.tsx`'s `import
-'./HermsInbox.css'`). `main`/`module`/`types`/`exports` point at that `dist/`
-output, `files` publishes only `dist/`, this `README.md`, and `LICENSE`
-(MIT, see that file), and `prepublishOnly` reruns the typecheck and the
-build before anything ships. `private: true` has been removed. `npm publish`
-from this directory (after `npm login` with an account that has publish
-rights on the `@hermesi` npm org/scope) now does the real thing.
-
-The `repository`/`homepage`/`bugs` URLs were placeholders pointing at
-`github.com/hermesi/hermesi`, a repository that is not this one. npm renders
-those as the package's own links, so they would have sent every integrator
-somewhere that does not exist. They point at the real remote now.
-
-**Still worth deciding before v1:** semver policy, a bundle-size CI gate, and a
-fuller SSR render test matrix (see "Not in this pass" below).
-
-## What's real here
-
-The packaging is real too, now: `npm run verify:package` builds, packs,
-installs the tarball into a throwaway consumer and imports from it under ESM,
-CJS and two TypeScript module resolutions, and CI runs it on every change.
-Until that existed nothing had ever loaded `dist/`: the dashboard imports this
-package's *source* through a bundler alias, so every test proved the source
-works and nothing at all about what npm would serve.
-
-`HermsClient` makes real HTTP requests
-against `/v1/client/inbox/*`, opens a real `EventSource` against
-`/v1/client/inbox/stream` (falling back to polling `/v1/client/inbox/counts`
-every 60s when SSE isn't available or keeps failing), and
-`<HermsInbox />` is a real, accessible bell + dropdown panel wired to that
-client through the headless hooks.
-
-A full working consumer lives in this package's repository, at
-`frontend/src/pages/InboxWidgetDemoPage.tsx`. It is linked rather than
-described because an integrator installing from npm does not have that
-file. See the repository link in `package.json`.
-
-## Exports a consumer needs and this README used to omit
-
-`HermsApiError`: every failed request rejects with it, carrying the API's own
-`type`, `code`, `message` and `request_id`. Catching it by type is the
-difference between showing a user "rate limited, try again" and showing them
-nothing. It was exported and undocumented, which means it was effectively
-unavailable.
-
-`HERMS_CHANNELS`: the channels an identity can be registered for, as an array
-so a preference centre can iterate them, with `HermsChannel` derived from it.
-
-`decodeSubscriberTokenExp`: reads a subscriber token's `exp` client-side so a
-host can refresh ahead of expiry. It parses; it does **not** validate a
-signature and cannot, since this package never holds a key.
-
-`client.registerChannel({ channel, identifier })` and
-`client.deregisterChannel(channel, identifier)`: where a subscriber can be
-reached on a channel that needs an address.
-
-`client.getPreferences()` / `client.updatePreference({ channel, enabled,
-categoryId })` and the `usePreferences()` hook: the subscriber's own
-notification settings, for building a preference centre. `PATCH` answers with
-the whole updated state, so a caller never refetches, and the hook does **not**
-update optimistically: turning off a channel is a consent decision, and showing
-it as done before the server agreed shows somebody they have opted out when
-they may not have.
-
-A setting of `null` means no preference was expressed and the default applies.
-It is not `false`, and collapsing the two would opt somebody out of something
-they never declined. Categories with `isCritical: true` are always delivered.
-Render them so a subscriber can see what they receive, but not as a control.
-
-There is deliberately **no** `unsubscribe()`, although `POST
-/v1/client/unsubscribe` exists. It is the target of a `List-Unsubscribe`
-one-click link (RFC 8058) whose token Hermesi mints into an outgoing email's
-headers, invoked by a mail client rather than by application code. Wrapping it
-here would invite you to build a button on a token you cannot obtain. The
-equivalent is `updatePreference({ channel: 'email', enabled: false })`.
-
-## Not in this pass
-
-For `<HermsPreferences />`, the headless surface is here
-(`usePreferences()`), the rendered component is not: a preference centre is a
-real interface design, and inventing one without that pass is how you get a
-screen that technically works. A Vue/vanilla wrapper (the framework-agnostic core is
-what makes one *possible* later, not a promise it exists), a category-filter
-picker inside `<HermsInbox />`'s own chrome, and the real-repo-URL/semver/CI
-follow-ups called out just above. See the task this package was built
-against for the exact, deliberate cut lines.
-
-## Layout
+React bindings for Hermesi's in-app inbox: a ready-made bell and panel, and the hooks it is
+built on if you would rather build your own.
 
+```sh
+npm install @hermesihq/react
 ```
-src/
-  core/            HermsClient: no React import anywhere in this directory.
-    HermsClient.ts
-    subscriberToken.ts   Reads (never verifies/mints) a token's `exp` claim.
-    types.ts
-  react/
-    HermsProvider.tsx
-    useUnreadCount.ts
-    useInbox.ts
-    HermsInbox.tsx
-    HermsInbox.css  Scoped under `.herms-inbox`, CSS custom properties only:
-                     no Tailwind dependency, so a host app's Tailwind build
-                     can never bleed into the widget (and vice versa).
-    locale.ts        A tiny built-in EN/FR string table, not i18next, so this
-                     package stays independent of whatever i18n stack (or
-                     none) a host app runs.
-  index.ts
+
+Requires React 18 or newer. It depends on [`@hermesihq/js`](https://github.com/hermesihq/sdk/tree/main/packages/js),
+which npm installs for you. You do not import it yourself unless you want the stores directly.
+
+## Before you start
+
+Three things: a **public key** (`hm_pk_...`, safe to ship in a bundle), your **API base URL
+ending in `/v1/client`**, and a **subscriber token minted by your own backend**. The token
+proves which subscriber this page acts for. Your backend signs it with your secret key; this
+package never sees that key and cannot mint a token. You give the client a function that
+asks your backend for a fresh one, and it calls that function before every request.
+
+The base URL is the client API, not the host root: every request is this string plus a path
+such as `/inbox`. A base URL without `/v1/client` makes every request a 404.
+
+## Quick start
+
+```tsx
+import { HermsClient, HermsInbox, HermsProvider } from '@hermesihq/react'
+import '@hermesihq/react/styles.css'
+
+const client = new HermsClient({
+  publicKey: 'hm_pk_prod_...',
+  apiBaseUrl: 'https://your-hermesi-host/v1/client',
+  getSubscriberToken: () => fetch('/api/hermesi-token').then((response) => response.text()), // calls *your* backend
+})
+
+export function AppHeader() {
+  return (
+    <HermsProvider client={client}>
+      <HermsInbox />
+    </HermsProvider>
+  )
+}
 ```
+
+Two lines are easy to miss. The stylesheet import is required: **the bundle does not load its
+own CSS**, so without it the panel renders with no styling. And `HermsProvider` must sit above
+anything that uses a hook, or the hook throws an error that names the missing provider.
+
+Create the client **once**, at module scope or in a `useMemo`, not on every render. A new
+client each render closes and reopens the real-time connection each render.
+
+## `<HermsInbox />`
+
+A real `<button>` with an accessible name that includes the unread count, and a panel with
+arrow-key navigation, `Home` and `End`, and `Escape` to close.
+
+| Prop | Default | |
+|---|---|---|
+| `placement` | `'bottom-end'` | `'bottom-start'`, `'bottom-end'`, `'top-start'` or `'top-end'` |
+| `onItemClick` | | Called with the item when one is activated. Use it to drive your own router. Without it, an item with an `actionUrl` navigates there. Either way the item is marked read first. |
+| `theme` | | `{ accent, radius }`, the two most re-themed values |
+| `colorScheme` | `'auto'` | `'auto'` follows the visitor's OS setting; `'light'` or `'dark'` force one |
+| `locale` | `'en'` | `'en'` or `'fr'` |
+| `className` | | Added to the root element |
+
+Everything else is reachable by overriding these CSS custom properties: `--herms-color-accent`,
+`--herms-color-accent-foreground`, `--herms-color-bg`, `--herms-color-border`,
+`--herms-color-danger`, `--herms-color-hover`, `--herms-color-muted`, `--herms-color-surface`,
+`--herms-color-text`, `--herms-color-unread-dot`, `--herms-font-family` and `--herms-radius`.
+The stylesheet is scoped under `.herms-inbox` and uses no Tailwind, so your build cannot bleed
+into the widget or the reverse.
+
+## Hooks
+
+Use these when the bell and panel are not what you want. Same data, no chrome.
+
+| Hook | Returns |
+|---|---|
+| `useUnreadCount()` | `{ unread, unseen, isLoading }`, kept live |
+| `useInbox({ status?, category? })` | `{ items, isLoading, isLoadingMore, error, hasMore, loadMore, markRead, markAllRead, archive, remove, refetch }` |
+| `usePreferences()` | `{ preferences, isLoading, error, setPreference, reload }` |
+
+They are a thin binding over the stores in `@hermesihq/js`, which is where the behaviour is
+documented. The parts worth knowing here:
+
+- The functions a hook returns keep the same identity for as long as it is mounted, so they
+  are safe in a `useCallback` or `memo` dependency list.
+- Changing `status` or `category` reloads the list and keeps the previous rows on screen,
+  flagged as loading, until the new ones arrive. A response for the old filter that lands
+  late is discarded.
+- Mutations go to the server first and patch local state with what it answered. A failed one
+  rejects.
+- `usePreferences` does not update optimistically. Turning off a channel is a consent
+  decision, and showing it as done before the server agreed tells somebody they have opted
+  out when they may not have.
+- A setting of `null` means no preference was expressed and the default applies. It is not
+  `false`, and treating them as the same would opt somebody out of something they never
+  declined. Categories with `isCritical: true` are always delivered: show them, but not as a
+  control.
+
+## Server rendering
+
+Importing this package touches no DOM, and a component using the hooks renders its loading
+state on the server. Nothing connects and no request is made until it mounts in the browser.
+
+## Also exported
+
+`HermsClient`, `HermsApiError`, `HERMS_CHANNELS` and `decodeSubscriberTokenExp`, with their
+types, are re-exported from `@hermesihq/js`, so an existing import from this package keeps
+working. Every failed request rejects with a `HermsApiError`; quote its `requestId` in a
+support conversation.
+
+## Not included
+
+A rendered preference centre. The headless `usePreferences()` is here; the interface is not,
+because it wants a design pass rather than an invention.
+
+## License
+
+MIT