@hermesihq/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,444 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Shared, framework-agnostic shapes for `HermsClient` and every React binding
+ * built on top of it. Camel-cased on purpose. The wire (§6.6 `/v1/client/inbox/*`)
+ * is snake_case; `HermsClient` is the one place that translation happens, the same
+ * posture the dashboard's own hand-written API layer takes (`frontend/src/api/*.ts`)
+ * until generated OpenAPI types exist for either surface.
+ */
+interface HermsClientOptions {
+    /** `hm_pk_<env>_<random>`, safe to embed in a browser bundle (§6.2: "grant
+     * nothing by themselves"). */
+    publicKey: string;
+    /** Base URL of the client API, e.g. `https://api.hermesi.dev/v1/client` or,
+     * same-origin behind a dev proxy, `/v1/client`. No trailing slash required:
+     * normalised internally. */
+    apiBaseUrl: string;
+    /**
+     * Host-app-supplied. This SDK never has the secret key and never could
+     * (F-INB-2: a subscriber token is minted server-side, by the host's own
+     * backend). Called fresh before *every* request; never cached past what the
+     * host itself returns, since refreshing ahead of expiry is explicitly the
+     * host's job, not this client's (see `onTokenExpiring`).
+     */
+    getSubscriberToken: () => string | Promise<string>;
+    /**
+     * Called proactively, once, some seconds before the *currently held* token's
+     * own `exp` claim (read back out of the token's payload segment client-side:
+     * it's HMAC-signed, not encrypted, so this never requires verifying the
+     * signature). This is a hook for the host app to refresh ahead of expiry rather
+     * than reactively after a `401`. Best-effort: a token whose payload can't be
+     * decoded (malformed, or a host app testing with a garbage string) simply
+     * never schedules a call.
+     */
+    onTokenExpiring?: () => void;
+}
+type HermsInboxReadStatus = 'read' | 'unread';
+interface HermsInboxCategory {
+    key: string;
+    name: string;
+}
+interface HermsInboxItem {
+    id: string;
+    title: string;
+    body: string;
+    actionUrl: string | null;
+    category: HermsInboxCategory | null;
+    seenAt: string | null;
+    readAt: string | null;
+    createdAt: string;
+}
+interface HermsInboxCounts {
+    unread: number;
+    unseen: number;
+}
+interface HermsInboxPage {
+    items: HermsInboxItem[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+interface HermsInboxListParams {
+    /** Maps to `GET /inbox?read=<bool>`: `'read'` -> `read=true`, `'unread'` ->
+     * `read=false`, omitted -> both. */
+    status?: HermsInboxReadStatus;
+    /** Category key(s), `?category=` (repeatable server-side). */
+    category?: string | string[];
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * Every channel Hermesi can hold an identity for.
+ *
+ * **Written out, and checked against the API by a test rather than trusted.** This
+ * union said `'push' | 'sms' | 'email' | 'in_app'` while the platform had grown to
+ * nine, so an integrator could not register a Telegram or Slack identity at all:
+ * TypeScript refused it at their call site, and no test here or in the dashboard had
+ * any reason to notice, because the demo page never registers a channel.
+ *
+ * It cannot be generated: this package is published standalone and must not depend on
+ * the repository's OpenAPI snapshot at build time. So `channelParity.test.ts` compares
+ * it to that snapshot's `Channel` enum instead. The list stays hand-written, and
+ * drifting from the server is what fails.
+ *
+ * `push` is included because the API accepts it. No adapter delivers it today, which is
+ * a deployment fact rather than a reason to refuse the identity.
+ *
+ * Exported as a value, not only a type: a host building a preference centre needs to
+ * iterate the channels at runtime, and deriving the type from the array means the two
+ * cannot disagree.
+ */
+declare const HERMS_CHANNELS: readonly ["in_app", "email", "push", "sms", "whatsapp", "telegram", "slack", "teams", "discord"];
+type HermsChannel = (typeof HERMS_CHANNELS)[number];
+interface HermsRegisterChannelParams {
+    channel: HermsChannel;
+    identifier: string;
+    metadata?: Record<string, unknown>;
+}
+/** One channel's setting, either globally or inside a category. `null` means the
+ *  subscriber has expressed no preference and the category's or platform's default
+ *  applies. It is not the same as `false`, and collapsing the two would silently
+ *  opt somebody out of something they never declined. */
+interface HermsChannelPreference {
+    channel: HermsChannel;
+    enabled: boolean | null;
+}
+interface HermsCategoryPreference {
+    categoryId: string;
+    key: string;
+    name: string;
+    /** A critical category is always delivered on every live channel and cannot be turned
+     *  off. Render it, but not as a control: an affordance that refuses is worse than
+     *  none. */
+    isCritical: boolean;
+    channels: HermsChannelPreference[];
+    emailEnabled: boolean | null;
+    inAppEnabled: boolean | null;
+}
+interface HermsPreferences {
+    /** For addressing the subscriber in a preference page's own copy. `null` when the
+     *  application never supplied one. */
+    firstName: string | null;
+    /** Settings that apply across every category. */
+    globalChannels: HermsChannelPreference[];
+    /** `email` and `in_app` again, as scalars.
+     *
+     *  Carried rather than dropped because the API publishes them, and dropping a
+     *  published field is the defect `HermsApiError` had. They are the same values as
+     *  the matching entries in `globalChannels`; read whichever suits, but do not treat
+     *  a disagreement between them as meaningful. */
+    globalEmailEnabled: boolean | null;
+    globalInAppEnabled: boolean | null;
+    categories: HermsCategoryPreference[];
+}
+/** One setting to change. Omit `categoryId` to change the global setting for that
+ *  channel; supply it to change the setting inside one category. */
+interface HermsPreferenceUpdate {
+    channel: HermsChannel;
+    enabled: boolean;
+    categoryId?: string;
+}
+interface HermsItemCreatedEvent {
+    type: 'item.created';
+    data: {
+        id: string;
+        title: string;
+        created_at: string;
+    };
+}
+interface HermsCountsChangedEvent {
+    type: 'counts.changed';
+    data: HermsInboxCounts;
+}
+type HermsRealtimeEvent = HermsItemCreatedEvent | HermsCountsChangedEvent;
+type HermsEventListener = (event: HermsRealtimeEvent) => void;
+/**
+ * One specific problem inside an error.
+ *
+ * Open, not closed, because the API says so: most entries name a request field
+ * (`field` + `issue`), some name a dependency instead, and its own schema declares
+ * `additionalProperties` rather than publishing a shape a client would be right to
+ * reject on. Typing it closed here would reintroduce exactly that.
+ */
+type HermsErrorDetail = Record<string, unknown>;
+/** Thrown for any failed request to the client API. It mirrors the server's error
+ * envelope where one was returned, and falls back to a generic shape when the body was
+ * not JSON at all, which is usually an upstream proxy's own HTML error page.
+ *
+ * `detail` and `docUrl` were missing for a long time while the API published both as
+ * required fields. A 422's per-field `detail` reached a consumer as a bare sentence,
+ * and `doc_url` (the one thing that lets an integrator resolve an error without
+ * asking anybody) never arrived at all. */
+declare class HermsApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly type: string;
+    readonly requestId: string;
+    /** Per-problem specifics. Possibly empty, never absent: the API's own words. */
+    readonly detail: readonly HermsErrorDetail[];
+    /** Documentation for this `code`, or `''` when the server sent none. */
+    readonly docUrl: string;
+    constructor(status: number, body: unknown);
+}
+
+declare class HermsClient {
+    private readonly options;
+    private readonly baseUrl;
+    private expiryTimer;
+    private lastScheduledExp;
+    constructor(options: HermsClientOptions);
+    /** Every request goes through here: always a *fresh* call to
+     * `getSubscriberToken()` (never cached past what the host itself returns,
+     * per this class's own contract), which also re-arms `onTokenExpiring`
+     * against whatever token comes back. */
+    private getFreshToken;
+    private scheduleExpiryHook;
+    /** Stops the scheduled `onTokenExpiring` timer. Called from
+     * `HermsProvider`'s unmount cleanup so a torn-down client never fires the
+     * hook after the app has stopped caring. */
+    destroy(): void;
+    /**
+     * `expectsBody` is how this knows a missing response body is a failure rather than a
+     * normal outcome. It defaults to `true` because most calls here read a payload; the
+     * methods that resolve to `void` pass `false`.
+     *
+     * Without it the success path did no checking at all. A `200` carrying a proxy's HTML
+     * page, or a `204` where a body was expected, left `parsed` null and returned it as
+     * `T`, so `listInbox()` rejected with `TypeError: Cannot read properties of null
+     * (reading 'data')` and the stack pointed at this SDK instead of at whatever was
+     * actually in the way. The *error* path already handled exactly that case carefully;
+     * only the success path did not.
+     */
+    private request;
+    listInbox(params?: HermsInboxListParams): Promise<HermsInboxPage>;
+    getCounts(): Promise<HermsInboxCounts>;
+    markRead(id: string): Promise<HermsInboxItem>;
+    markAllRead(): Promise<{
+        updated: number;
+    }>;
+    markSeen(ids: string[]): Promise<{
+        updated: number;
+    }>;
+    archive(id: string): Promise<HermsInboxItem>;
+    delete(id: string): Promise<void>;
+    registerChannel(params: HermsRegisterChannelParams): Promise<void>;
+    /**
+     * The subscriber's own notification settings, for rendering a preference centre.
+     *
+     * There is deliberately no `unsubscribe()` beside this, although the API exposes
+     * `POST /v1/client/unsubscribe`. That route is the target of a `List-Unsubscribe`
+     * one-click link (RFC 8058): its token is minted by Hermesi and embedded in an
+     * outgoing email's headers, and the API's own description says it is invoked by a
+     * mail client rather than by application code. Wrapping it here would invite a host
+     * to build an unsubscribe button on a token it cannot obtain. The equivalent here
+     * is `updatePreference({ channel: 'email', enabled: false })`.
+     */
+    getPreferences(): Promise<HermsPreferences>;
+    /**
+     * Change one setting, and receive the whole updated state back.
+     *
+     * The server answers `PATCH` with the full preferences rather than an
+     * acknowledgement, so a caller never has to refetch, and never renders a view
+     * assembled from its own optimistic guess plus whatever else has changed since.
+     * Omit `categoryId` for the global setting; supply it to change one category.
+     */
+    updatePreference(update: HermsPreferenceUpdate): Promise<HermsPreferences>;
+    /**
+     * **Path parameters, not a query string.** This sent
+     * `DELETE /channels?channel=...&identifier=...` for as long as the method has existed,
+     * and there is no `DELETE` on `/v1/client/channels` at all: the route is
+     * `/v1/client/channels/{channel}/{identifier}`, so every call 404'd. Nothing caught
+     * it: the reference integration never deregisters, and the package had no tests.
+     *
+     * `identifier` is encoded because it is somebody's address (an email, a phone
+     * number, a chat conversation id), and those carry `@`, `+` and `:`.
+     */
+    deregisterChannel(channel: HermsChannel, identifier: string): Promise<void>;
+    /**
+     * Opens a live connection for real-time inbox events and returns an
+     * unsubscribe function. SSR-safe: `window`/`EventSource` are only read here,
+     * at call time, never at module or constructor time.
+     *
+     * - Prefers SSE (`GET /inbox/stream`) when `EventSource` exists.
+     * - Falls back to polling `getCounts()` every 60s (§6.6) when `EventSource`
+     *   doesn't exist at all, or after `MAX_FAST_RECONNECT_ATTEMPTS` consecutive
+     *   immediate reconnect failures (an invalid/expired token, or a network
+     *   that blocks SSE outright). It still retries SSE in the background with
+     *   exponential backoff rather than abandoning it permanently, so a fixed
+     *   token/network problem self-heals without a page reload.
+     */
+    subscribe(onEvent: HermsEventListener): () => void;
+}
+
+/**
+ * Pure, dependency-free helpers for the *reading* half of F-INB-2's subscriber
+ * token (§6.2). `HermsClient` never mints or verifies a signature (it never has
+ * the secret key hash to do either), it only needs to read the `exp` claim back
+ * out of a token the host app already handed it, to drive `onTokenExpiring`.
+ *
+ * Token shape (verbatim, `hermesi.core.security`'s "F-INB-2 subscriber token"
+ * section): `base64url(payload) + "." + base64url(hmac_sha256(...))`, where
+ * `payload` is a plain JSON object `{sub, env, exp}`. No JOSE/JWT header segment.
+ */
+/**
+ * Returns the token's `exp` claim (unix seconds) or `null` for anything that
+ * isn't a well-formed `<payload>.<signature>` token with a numeric `exp`. A
+ * malformed value never throws, it just means `onTokenExpiring` won't be
+ * scheduled for this particular token.
+ */
+declare function decodeSubscriberTokenExp(token: string): number | null;
+
+interface HermsContextValue {
+    client: HermsClient;
+    /** Registers `listener` against the *one* `client.subscribe(...)` connection
+     * this provider owns for the whole subtree, returning an unsubscribe
+     * function. Every `useUnreadCount`/`useInbox` consumer calls this instead
+     * of opening its own `EventSource`/poll loop. */
+    addEventListener: (listener: HermsEventListener) => () => void;
+}
+interface HermsProviderProps {
+    client: HermsClient;
+    children: ReactNode;
+}
+/**
+ * `<HermsProvider client={new HermsClient({...})}>`: one `HermsClient`
+ * instance for the whole subtree. Opens the client's real-time subscription
+ * once on mount and tears it (and the client's own `onTokenExpiring` timer)
+ * down on unmount; every listener registered via `addEventListener` below
+ * shares that single connection rather than each hook paying for its own.
+ *
+ * `client` is expected to be a stable reference (constructed once, e.g. in
+ * `useMemo`/module scope in the host app). Passing a new instance on every
+ * render tears down and reopens the underlying connection every render.
+ */
+declare function HermsProvider({ client, children }: HermsProviderProps): react.JSX.Element;
+/** Every hook/component in this package throws this same error outside a
+ * `<HermsProvider>`: there is no sensible default client to fall back to. */
+declare function useHermsContext(): HermsContextValue;
+
+interface UseUnreadCountResult extends HermsInboxCounts {
+    isLoading: boolean;
+}
+/**
+ * Headless. `{unread, unseen, isLoading}`, kept live via the provider's
+ * shared subscription: one `getCounts()` call on mount, then recomputed on
+ * every `counts.changed` event (real-time push, or the client's own 60s
+ * polling fallback) for as long as this component stays mounted.
+ */
+declare function useUnreadCount(): UseUnreadCountResult;
+
+interface UseInboxOptions {
+    status?: HermsInboxReadStatus;
+    category?: string;
+}
+interface UseInboxResult {
+    items: HermsInboxItem[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    hasMore: boolean;
+    loadMore: () => void;
+    markRead: (id: string) => Promise<void>;
+    markAllRead: () => Promise<void>;
+    archive: (id: string) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refetch: () => void;
+}
+/**
+ * Headless, cursor-paginated inbox list state: thin wrappers around
+ * `HermsClient`'s own methods that also patch local state, so a consumer
+ * never has to manually refetch the whole list after every mutating action.
+ *
+ * Live-updated on `item.created`: the new item is prepended immediately from
+ * the (deliberately minimal: `{id, title, created_at}`, §6.6) SSE payload so
+ * the UI reacts instantly, then reconciled against a fresh first page fetched
+ * in the background so the authoritative row (body, category, action_url)
+ * lands without a full list reload/flicker.
+ */
+declare function useInbox(options?: UseInboxOptions): UseInboxResult;
+
+interface UsePreferencesResult {
+    /** `null` until the first read resolves. */
+    preferences: HermsPreferences | null;
+    isLoading: boolean;
+    /** The failure of the last read or write, or `null`. Kept rather than thrown so a
+     *  preference centre can show it beside the controls instead of unmounting them. */
+    error: Error | null;
+    /** Change one setting. Resolves once the server's new state has been applied. */
+    setPreference: (update: HermsPreferenceUpdate) => Promise<void>;
+    /** Re-read, for a retry button. */
+    reload: () => Promise<void>;
+}
+/**
+ * Headless preferences, the counterpart to `useInbox`.
+ *
+ * **No optimistic update, deliberately.** A toggle here is not a like button: turning
+ * off a channel is a consent decision, and showing it as done before the server agreed
+ * is showing somebody they have opted out when they may not have. The server answers
+ * `PATCH` with the *whole* updated state, so the correct view arrives with the write
+ * and there is nothing to reconcile. A per-row pending state in the host is a better
+ * answer to the latency than a lie.
+ *
+ * **`error` is state, not an exception.** `setPreference` still rejects, so a caller
+ * can `await` it and react per-control, but the hook also holds the failure so a
+ * preference centre can render it without every consumer writing the same try/catch.
+ * A failed write leaves the last known-good state on screen rather than an empty page.
+ *
+ * Critical categories arrive with `isCritical: true` and are always delivered. Render
+ * them (a subscriber should see what they are receiving), but not as a control: an
+ * affordance that refuses is worse than none.
+ */
+declare function usePreferences(): UsePreferencesResult;
+
+/**
+ * `<HermsInbox />`'s own tiny, self-contained EN/FR string table.
+ *
+ * Deliberately **not** i18next: this package ships to arbitrary host apps
+ * (§8.5: "zero hard dependency on the host app's state library") that may run
+ * their own i18n stack, a different one, or none at all. Pulling i18next in
+ * as a real dependency here would be exactly the kind of host-app-shaped
+ * assumption the SDK is supposed to avoid, for a handful of short strings.
+ * `locale` mirrors §8.5's own `<HermsProvider locale="fr">` example prop.
+ */
+type HermsLocale = 'en' | 'fr';
+
+type HermsInboxPlacement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+interface HermsInboxTheme {
+    accent?: string;
+    radius?: string;
+}
+interface HermsInboxProps {
+    /** Popover position relative to the bell trigger. Default `bottom-end`. */
+    placement?: HermsInboxPlacement;
+    /** Called when an item is activated (click, or Enter on a focused row).
+     * Lets a host app drive its own router (§8.5's own example:
+     * `onItemClick={(item) => navigate(item.actionUrl)}`) instead of a hard
+     * page navigation. When omitted, activating an item with a non-null
+     * `actionUrl` does a plain `window.location.assign` to it. Either way, the
+     * item is marked read first. */
+    onItemClick?: (item: HermsInboxItem) => void;
+    /** A couple of the most commonly re-themed CSS custom properties, settable
+     * without a host app writing any CSS of its own. Anything else is
+     * reachable by overriding `--herms-color-*`/`--herms-radius` variables
+     * directly (see `HermsInbox.css`). */
+    theme?: HermsInboxTheme;
+    /** `'auto'` (default) follows the visitor's OS `prefers-color-scheme`;
+     * `'light'`/`'dark'` force one regardless of it. */
+    colorScheme?: 'auto' | 'light' | 'dark';
+    locale?: HermsLocale;
+    className?: string;
+}
+/**
+ * `<HermsInbox />`: bell trigger + dropdown panel (§4.8/F-INB-5). Built
+ * entirely on the headless `useInbox`/`useUnreadCount` hooks; every state
+ * (loading, empty, error, populated) renders here, none of it invented by a
+ * host app. Accessible: a real `<button>` trigger with `aria-label`/
+ * `aria-expanded`, the panel as `role="menu"` with roving-tabindex arrow-key
+ * navigation, `Home`/`End`, `Escape`-to-close (native to Radix `Popover`,
+ * which also returns focus to the trigger), and `Enter`/`Space` (native
+ * `<button>` behavior) to activate the focused item.
+ */
+declare function HermsInbox({ placement, onItemClick, theme, colorScheme, locale, className }: HermsInboxProps): react.JSX.Element;
+
+export { HERMS_CHANNELS, HermsApiError, type HermsCategoryPreference, type HermsChannel, type HermsChannelPreference, HermsClient, type HermsClientOptions, type HermsErrorDetail, type HermsEventListener, HermsInbox, type HermsInboxCategory, type HermsInboxCounts, type HermsInboxItem, type HermsInboxListParams, type HermsInboxPage, type HermsInboxPlacement, type HermsInboxProps, type HermsInboxReadStatus, type HermsInboxTheme, type HermsLocale, type HermsPreferenceUpdate, type HermsPreferences, HermsProvider, type HermsProviderProps, type HermsRealtimeEvent, type HermsRegisterChannelParams, type UseInboxOptions, type UseInboxResult, type UsePreferencesResult, type UseUnreadCountResult, decodeSubscriberTokenExp, useHermsContext, useInbox, usePreferences, useUnreadCount };