@hermesihq/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to `@hermesihq/react`.
+
+This file describes what a consumer gets, not how it was built. The repository's
+history is where the reasoning lives.
+
+## Versioning
+
+**`0.x` means the public API can still change.** A minor bump (`0.1` → `0.2`) may
+contain a breaking change; a patch bump will not. That is the ordinary `0.x` reading
+of semver and it is chosen deliberately rather than by default: this SDK's shape is
+still being learned from the first integrations, and promising stability before anyone
+has built against it would be a promise made to nobody and broken later.
+
+`1.0.0` is the commitment that a breaking change requires a major bump. It waits until
+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.1.0 (2026-09-28)
+
+The first published release. Nothing precedes it, so there is nothing to migrate from
+and no deprecations; the entries below describe the surface rather than changes to one.
+
+### The inbox
+
+- `HermsClient`: the framework-agnostic core. Reads and writes the subscriber's inbox,
+  opens a realtime stream for new items and unread counts, and falls back to polling
+  when the runtime has no `EventSource` or the stream keeps failing. It imports nothing
+  from React, so a Vue or vanilla wrapper is a thin layer rather than a second
+  implementation.
+- `HermsProvider` / `useHermsContext`: one shared connection per provider, fanned out
+  to every hook beneath it. Mounting three components does not open three streams.
+- `useInbox`: the item list, with filtering, cursor pagination, and mark-read,
+  mark-all-read, archive and delete.
+- `useUnreadCount`: the badge, kept live off the same stream.
+- `HermsInbox`: a rendered bell and panel, keyboard-navigable, in English or French.
+  Optional: the hooks above are the whole API if you would rather build your own.
+
+### Preferences
+
+- `client.getPreferences()` and `client.updatePreference({ channel, enabled, categoryId })`,
+  plus the `usePreferences` hook.
+- `PATCH` answers with the whole updated state, so a caller never refetches. The hook
+  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`. 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()`. `POST /v1/client/unsubscribe` is the target
+  of a `List-Unsubscribe` one-click link (RFC 8058) whose token is minted into an
+  outgoing email's headers and invoked by a mail client, not by application code. The
+  equivalent here is `updatePreference({ channel: 'email', enabled: false })`.
+
+### Identities and errors
+
+- `client.registerChannel` / `client.deregisterChannel`, and `HERMS_CHANNELS`: the
+  channels an identity can be registered for, exported as an array so a preference
+  centre can iterate them, with `HermsChannel` derived from it.
+- `HermsApiError`: every failed request rejects with it, carrying the API's `type`,
+  `code`, `message`, `request_id`, `detail` and `docUrl`. A response that is not JSON
+  (a proxy's error page, an empty body where one was expected) arrives as this too,
+  rather than as a `TypeError` from inside the SDK.
+- `decodeSubscriberTokenExp`: reads a subscriber token's expiry so a host can refresh
+  ahead of it. It parses; it does not validate a signature and cannot, since this
+  package never holds a key.
+
+### Requirements
+
+React 18 or newer, as a peer dependency with no upper bound. That is deliberate and
+the opposite of how this repository pins its own dependencies: an application locks its
+versions so two builds of one commit are identical, whereas a library that bounds a
+peer range forces a warning on every consumer the day React ships a major, whether or
+not anything actually broke. You control React; this package should not have an opinion
+about which one you run.
+
+Ships ESM and CommonJS builds with type declarations for both, and
+`@hermesihq/react/styles.css` for `HermsInbox`.
+
+### Known gaps
+
+- No `<HermsPreferences />` component. The headless surface for one is here; the
+  rendered interface is not, because it wants a design pass rather than an invention.
+- No Vue or vanilla wrapper yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermesi
+
+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

@@ -0,0 +1,128 @@
+# @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
+
+```
+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
+```