@hermesihq/react 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,429 +1,17 @@
-// src/core/subscriberToken.ts
-function base64UrlDecodeToString(segment) {
-  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
-  const binary = atob(padded);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
-  return new TextDecoder().decode(bytes);
-}
-function decodeSubscriberTokenExp(token) {
-  const [payloadSegment] = token.split(".");
-  if (!payloadSegment) return null;
-  try {
-    const parsed = JSON.parse(base64UrlDecodeToString(payloadSegment));
-    if (typeof parsed === "object" && parsed !== null && "exp" in parsed && typeof parsed.exp === "number") {
-      return parsed.exp;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-// src/core/types.ts
-var HERMS_CHANNELS = [
-  "in_app",
-  "email",
-  "push",
-  "sms",
-  "whatsapp",
-  "telegram",
-  "slack",
-  "teams",
-  "discord"
-];
-var HermsApiError = class extends Error {
-  status;
-  code;
-  type;
-  requestId;
-  /** Per-problem specifics. Possibly empty, never absent: the API's own words. */
-  detail;
-  /** Documentation for this `code`, or `''` when the server sent none. */
-  docUrl;
-  constructor(status, body) {
-    const envelope = typeof body === "object" && body !== null && "error" in body ? body.error : void 0;
-    const message = typeof envelope?.message === "string" ? envelope.message : `Hermesi client API request failed with status ${status}.`;
-    super(message);
-    this.name = "HermsApiError";
-    this.status = status;
-    this.code = typeof envelope?.code === "string" ? envelope.code : "unknown_error";
-    this.type = typeof envelope?.type === "string" ? envelope.type : "unknown_error";
-    this.requestId = typeof envelope?.request_id === "string" ? envelope.request_id : "";
-    this.detail = Array.isArray(envelope?.detail) ? envelope.detail.filter(
-      (entry) => typeof entry === "object" && entry !== null
-    ) : [];
-    this.docUrl = typeof envelope?.doc_url === "string" ? envelope.doc_url : "";
-  }
-};
-
-// src/core/HermsClient.ts
-var POLL_INTERVAL_MS = 6e4;
-var MAX_FAST_RECONNECT_ATTEMPTS = 3;
-var BASE_RECONNECT_DELAY_MS = 1e3;
-var MAX_RECONNECT_DELAY_MS = 3e4;
-var TOKEN_EXPIRY_BUFFER_SECONDS = 60;
-function backoffDelayMs(attempt) {
-  const exponential = BASE_RECONNECT_DELAY_MS * 2 ** Math.max(0, attempt - 1);
-  return Math.min(MAX_RECONNECT_DELAY_MS, exponential);
-}
-function buildQueryString(params) {
-  const search = new URLSearchParams();
-  for (const [key, value] of Object.entries(params)) {
-    if (value === void 0) continue;
-    if (Array.isArray(value)) {
-      for (const item of value) search.append(key, item);
-    } else {
-      search.append(key, String(value));
-    }
-  }
-  const qs = search.toString();
-  return qs ? `?${qs}` : "";
-}
-function fromWireItem(wire) {
-  return {
-    id: wire.id,
-    title: wire.title,
-    body: wire.body,
-    actionUrl: wire.action_url,
-    category: wire.category ? { key: wire.category.key, name: wire.category.name } : null,
-    seenAt: wire.seen_at,
-    readAt: wire.read_at,
-    createdAt: wire.created_at
-  };
-}
-function fromWirePreferences(wire) {
-  return {
-    firstName: wire.first_name,
-    globalChannels: wire.global_channels.map((c) => ({ channel: c.channel, enabled: c.enabled })),
-    globalEmailEnabled: wire.global_email_enabled,
-    globalInAppEnabled: wire.global_in_app_enabled,
-    categories: wire.categories.map((category) => ({
-      categoryId: category.category_id,
-      key: category.key,
-      name: category.name,
-      isCritical: category.is_critical,
-      channels: category.channels.map((c) => ({ channel: c.channel, enabled: c.enabled })),
-      emailEnabled: category.email_enabled,
-      inAppEnabled: category.in_app_enabled
-    }))
-  };
-}
-var HermsClient = class {
-  options;
-  baseUrl;
-  expiryTimer = null;
-  lastScheduledExp = null;
-  constructor(options) {
-    this.options = options;
-    this.baseUrl = options.apiBaseUrl.replace(/\/+$/, "");
-  }
-  // --- Token handling ----------------------------------------------------
-  /** 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. */
-  async getFreshToken() {
-    const token = await this.options.getSubscriberToken();
-    this.scheduleExpiryHook(token);
-    return token;
-  }
-  scheduleExpiryHook(token) {
-    const { onTokenExpiring } = this.options;
-    if (!onTokenExpiring) return;
-    const exp = decodeSubscriberTokenExp(token);
-    if (exp === null || exp === this.lastScheduledExp) return;
-    if (this.expiryTimer !== null) clearTimeout(this.expiryTimer);
-    this.lastScheduledExp = exp;
-    const delayMs = Math.max(0, exp * 1e3 - TOKEN_EXPIRY_BUFFER_SECONDS * 1e3 - Date.now());
-    this.expiryTimer = setTimeout(() => {
-      onTokenExpiring();
-    }, delayMs);
-  }
-  /** 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() {
-    if (this.expiryTimer !== null) clearTimeout(this.expiryTimer);
-    this.expiryTimer = null;
-  }
-  // --- Transport -----------------------------------------------------------
-  /**
-   * `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.
-   */
-  async request(path, init = {}) {
-    const token = await this.getFreshToken();
-    const qs = init.query ? buildQueryString(init.query) : "";
-    const headers = {
-      Authorization: `Bearer ${this.options.publicKey}`,
-      "X-Hermesi-Subscriber-Token": token,
-      Accept: "application/json"
-    };
-    if (init.body !== void 0) headers["Content-Type"] = "application/json";
-    const response = await fetch(`${this.baseUrl}${path}${qs}`, {
-      method: init.method ?? "GET",
-      headers,
-      body: init.body !== void 0 ? JSON.stringify(init.body) : void 0
-    });
-    const expectsBody = init.expectsBody ?? true;
-    if (response.status === 204) {
-      if (expectsBody) throw new HermsApiError(response.status, null);
-      return void 0;
-    }
-    const rawText = await response.text();
-    let parsed = null;
-    if (rawText) {
-      try {
-        parsed = JSON.parse(rawText);
-      } catch {
-        parsed = null;
-      }
-    }
-    if (!response.ok) {
-      throw new HermsApiError(response.status, parsed);
-    }
-    if (expectsBody && parsed === null) {
-      throw new HermsApiError(response.status, null);
-    }
-    return parsed;
-  }
-  // --- Inbox reads -----------------------------------------------------------
-  async listInbox(params = {}) {
-    const wire = await this.request("/inbox", {
-      query: {
-        limit: params.limit,
-        cursor: params.cursor,
-        read: params.status === void 0 ? void 0 : params.status === "read" ? "true" : "false",
-        category: params.category
-      }
-    });
-    return {
-      items: wire.data.map(fromWireItem),
-      hasMore: wire.has_more,
-      nextCursor: wire.next_cursor
-    };
-  }
-  async getCounts() {
-    const wire = await this.request("/inbox/counts");
-    return { unread: wire.unread, unseen: wire.unseen };
-  }
-  // --- Inbox writes ------------------------------------------------------
-  async markRead(id) {
-    const wire = await this.request(`/inbox/${encodeURIComponent(id)}/read`, { method: "POST" });
-    return fromWireItem(wire);
-  }
-  async markAllRead() {
-    const wire = await this.request("/inbox/read-all", { method: "POST" });
-    return { updated: wire.updated };
-  }
-  async markSeen(ids) {
-    if (ids.length === 0) return { updated: 0 };
-    const wire = await this.request("/inbox/seen", { method: "POST", body: { ids } });
-    return { updated: wire.updated };
-  }
-  async archive(id) {
-    const wire = await this.request(`/inbox/${encodeURIComponent(id)}/archive`, { method: "POST" });
-    return fromWireItem(wire);
-  }
-  async delete(id) {
-    await this.request(`/inbox/${encodeURIComponent(id)}`, { method: "DELETE", expectsBody: false });
-  }
-  // --- Channels (device-token self-registration) --------------------------
-  //
-  // `POST/DELETE /v1/client/channels`: landing alongside this SDK, not yet
-  // live in every deployment at the time this client was written. Implemented
-  // against the documented shape (§8.5/§6.10) so the SDK's public surface is
-  // complete; a backend that hasn't shipped the route yet will 404, surfaced
-  // to the caller as an ordinary `HermsApiError`, same as any other endpoint.
-  async registerChannel(params) {
-    await this.request("/channels", {
-      method: "POST",
-      expectsBody: false,
-      body: { channel: params.channel, identifier: params.identifier, metadata: params.metadata }
-    });
-  }
-  // --- Preferences -----------------------------------------------------------
-  /**
-   * 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 })`.
-   */
-  async getPreferences() {
-    return fromWirePreferences(await this.request("/preferences"));
-  }
-  /**
-   * 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.
-   */
-  async updatePreference(update) {
-    const wire = await this.request("/preferences", {
-      method: "PATCH",
-      body: {
-        channel: update.channel,
-        enabled: update.enabled,
-        // Sent as `null` rather than omitted: the API reads its absence and its null
-        // the same way, and being explicit keeps "global" visible in a request log.
-        category_id: update.categoryId ?? null
-      }
-    });
-    return fromWirePreferences(wire);
-  }
-  /**
-   * **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 `:`.
-   */
-  async deregisterChannel(channel, identifier) {
-    await this.request(`/channels/${encodeURIComponent(channel)}/${encodeURIComponent(identifier)}`, {
-      method: "DELETE",
-      expectsBody: false
-    });
-  }
-  // --- Real-time -----------------------------------------------------------
-  /**
-   * 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) {
-    let stopped = false;
-    let eventSource = null;
-    let pollTimer = null;
-    let reconnectTimer = null;
-    let consecutiveFailures = 0;
-    const hasEventSource = typeof window !== "undefined" && typeof EventSource !== "undefined";
-    const startPolling = () => {
-      if (pollTimer !== null) return;
-      pollTimer = setInterval(() => {
-        this.getCounts().then((counts) => onEvent({ type: "counts.changed", data: counts })).catch(() => {
-        });
-      }, POLL_INTERVAL_MS);
-    };
-    const stopPolling = () => {
-      if (pollTimer !== null) {
-        clearInterval(pollTimer);
-        pollTimer = null;
-      }
-    };
-    const scheduleReconnect = () => {
-      if (stopped) return;
-      consecutiveFailures += 1;
-      if (consecutiveFailures >= MAX_FAST_RECONNECT_ATTEMPTS) startPolling();
-      const delay = backoffDelayMs(consecutiveFailures);
-      reconnectTimer = setTimeout(() => {
-        void connect();
-      }, delay);
-    };
-    const connect = async () => {
-      if (stopped || !hasEventSource) return;
-      let token;
-      try {
-        token = await this.getFreshToken();
-      } catch {
-        scheduleReconnect();
-        return;
-      }
-      if (stopped) return;
-      const qs = buildQueryString({ public_key: this.options.publicKey, subscriber_token: token });
-      const source = new EventSource(`${this.baseUrl}/inbox/stream${qs}`);
-      eventSource = source;
-      source.addEventListener("item.created", (evt) => {
-        consecutiveFailures = 0;
-        try {
-          const data = JSON.parse(evt.data);
-          onEvent({ type: "item.created", data });
-        } catch {
-        }
-      });
-      source.addEventListener("counts.changed", (evt) => {
-        consecutiveFailures = 0;
-        try {
-          const data = JSON.parse(evt.data);
-          onEvent({ type: "counts.changed", data });
-        } catch {
-        }
-      });
-      source.onopen = () => {
-        consecutiveFailures = 0;
-        stopPolling();
-      };
-      source.onerror = () => {
-        source.close();
-        if (eventSource === source) eventSource = null;
-        if (!stopped) scheduleReconnect();
-      };
-    };
-    if (hasEventSource) {
-      void connect();
-    } else {
-      startPolling();
-    }
-    return () => {
-      stopped = true;
-      stopPolling();
-      if (reconnectTimer !== null) clearTimeout(reconnectTimer);
-      eventSource?.close();
-    };
-  }
-};
+// src/index.ts
+import { HermsClient, HermsApiError, HERMS_CHANNELS, decodeSubscriberTokenExp } from "@hermesihq/js";
 
-// src/react/HermsProvider.tsx
-import { createContext, useContext, useEffect, useMemo, useRef } from "react";
+// src/HermsProvider.tsx
+import { createContext, useContext, useEffect, useMemo } from "react";
+import { HermsSession } from "@hermesihq/js";
 import { jsx } from "react/jsx-runtime";
 var HermsContext = createContext(null);
 function HermsProvider({ client, children }) {
-  const listenersRef = useRef(/* @__PURE__ */ new Set());
-  useEffect(() => {
-    const unsubscribe = client.subscribe((event) => {
-      for (const listener of listenersRef.current) listener(event);
-    });
-    return () => {
-      unsubscribe();
-      client.destroy();
-    };
-  }, [client]);
+  const session = useMemo(() => new HermsSession(client), [client]);
+  useEffect(() => session.connect(), [session]);
   const value = useMemo(
-    () => ({
-      client,
-      addEventListener: (listener) => {
-        listenersRef.current.add(listener);
-        return () => listenersRef.current.delete(listener);
-      }
-    }),
-    [client]
+    () => ({ client, addEventListener: session.addEventListener }),
+    [client, session]
   );
   return /* @__PURE__ */ jsx(HermsContext.Provider, { value, children });
 }
@@ -435,203 +23,63 @@ function useHermsContext() {
   return ctx;
 }
 
-// src/react/useUnreadCount.ts
-import { useEffect as useEffect2, useState } from "react";
+// src/useUnreadCount.ts
+import { useEffect as useEffect2, useMemo as useMemo2, useSyncExternalStore } from "react";
+import { CountsStore } from "@hermesihq/js";
 function useUnreadCount() {
-  const { client, addEventListener } = useHermsContext();
-  const [counts, setCounts] = useState({ unread: 0, unseen: 0 });
-  const [isLoading, setIsLoading] = useState(true);
-  useEffect2(() => {
-    let cancelled = false;
-    setIsLoading(true);
-    client.getCounts().then((fresh) => {
-      if (!cancelled) setCounts(fresh);
-    }).catch(() => {
-    }).finally(() => {
-      if (!cancelled) setIsLoading(false);
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [client]);
-  useEffect2(
-    () => addEventListener((event) => {
-      if (event.type === "counts.changed") setCounts(event.data);
-    }),
-    [addEventListener]
-  );
-  return { ...counts, isLoading };
+  const host = useHermsContext();
+  const store = useMemo2(() => new CountsStore(host), [host]);
+  useEffect2(() => store.connect(), [store]);
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
 }
 
-// src/react/useInbox.ts
-import { useCallback, useEffect as useEffect3, useRef as useRef2, useState as useState2 } from "react";
+// src/useInbox.ts
+import { useEffect as useEffect3, useMemo as useMemo3, useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { InboxStore } from "@hermesihq/js";
 function useInbox(options = {}) {
-  const { client, addEventListener } = useHermsContext();
+  const host = useHermsContext();
   const { status, category } = options;
-  const [items, setItems] = useState2([]);
-  const [isLoading, setIsLoading] = useState2(true);
-  const [isLoadingMore, setIsLoadingMore] = useState2(false);
-  const [error, setError] = useState2(null);
-  const [hasMore, setHasMore] = useState2(false);
-  const cursorRef = useRef2(null);
-  const requestIdRef = useRef2(0);
-  const fetchFirstPage = useCallback(() => {
-    const requestId = ++requestIdRef.current;
-    setIsLoading(true);
-    setError(null);
-    client.listInbox({ status, category }).then((page) => {
-      if (requestIdRef.current !== requestId) return;
-      setItems(page.items);
-      setHasMore(page.hasMore);
-      cursorRef.current = page.nextCursor;
-    }).catch((err) => {
-      if (requestIdRef.current !== requestId) return;
-      setError(err instanceof Error ? err : new Error("Failed to load inbox."));
-    }).finally(() => {
-      if (requestIdRef.current === requestId) setIsLoading(false);
-    });
-  }, [client, status, category]);
+  const store = useMemo3(() => new InboxStore(host, { status, category }), [host]);
+  useEffect3(() => store.connect(), [store]);
   useEffect3(() => {
-    fetchFirstPage();
-  }, [fetchFirstPage]);
-  const loadMore = useCallback(() => {
-    if (isLoadingMore || !hasMore || cursorRef.current === null) return;
-    setIsLoadingMore(true);
-    client.listInbox({ status, category, cursor: cursorRef.current }).then((page) => {
-      setItems((prev) => [...prev, ...page.items]);
-      setHasMore(page.hasMore);
-      cursorRef.current = page.nextCursor;
-    }).catch((err) => {
-      setError(err instanceof Error ? err : new Error("Failed to load more of the inbox."));
-    }).finally(() => setIsLoadingMore(false));
-  }, [client, status, category, isLoadingMore, hasMore]);
-  const reconcileFirstPage = useCallback(() => {
-    client.listInbox({ status, category }).then((page) => {
-      setItems((prev) => {
-        const freshById = new Map(page.items.map((item) => [item.id, item]));
-        const merged = prev.map((item) => freshById.get(item.id) ?? item);
-        const knownIds = new Set(merged.map((item) => item.id));
-        const additions = page.items.filter((item) => !knownIds.has(item.id));
-        return [...additions, ...merged];
-      });
-    }).catch(() => {
-    });
-  }, [client, status, category]);
-  useEffect3(
-    () => addEventListener((event) => {
-      if (event.type !== "item.created") return;
-      const partial = {
-        id: event.data.id,
-        title: event.data.title,
-        body: "",
-        actionUrl: null,
-        category: null,
-        seenAt: null,
-        readAt: null,
-        createdAt: event.data.created_at
-      };
-      setItems((prev) => prev.some((item) => item.id === partial.id) ? prev : [partial, ...prev]);
-      reconcileFirstPage();
+    store.setFilter({ status, category });
+  }, [store, status, category]);
+  const state = useSyncExternalStore2(store.subscribe, store.getSnapshot, store.getSnapshot);
+  return useMemo3(
+    () => ({
+      ...state,
+      // Arrow-function fields on the store: the same references for its whole life, so a
+      // consumer's `useCallback`/`memo` dependencies do not churn as the state changes.
+      loadMore: store.loadMore,
+      markRead: store.markRead,
+      markAllRead: store.markAllRead,
+      archive: store.archive,
+      remove: store.remove,
+      refetch: store.refetch
     }),
-    [addEventListener, reconcileFirstPage]
+    [state, store]
   );
-  const markRead = useCallback(
-    async (id) => {
-      const updated = await client.markRead(id);
-      setItems((prev) => prev.map((item) => item.id === id ? updated : item));
-    },
-    [client]
-  );
-  const markAllRead = useCallback(async () => {
-    await client.markAllRead();
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    setItems((prev) => prev.map((item) => item.readAt ? item : { ...item, readAt: now }));
-  }, [client]);
-  const archive = useCallback(
-    async (id) => {
-      await client.archive(id);
-      setItems((prev) => prev.filter((item) => item.id !== id));
-    },
-    [client]
-  );
-  const remove = useCallback(
-    async (id) => {
-      await client.delete(id);
-      setItems((prev) => prev.filter((item) => item.id !== id));
-    },
-    [client]
-  );
-  return {
-    items,
-    isLoading,
-    isLoadingMore,
-    error,
-    hasMore,
-    loadMore,
-    markRead,
-    markAllRead,
-    archive,
-    remove,
-    refetch: fetchFirstPage
-  };
 }
 
-// src/react/usePreferences.ts
-import { useCallback as useCallback2, useEffect as useEffect4, useState as useState3 } from "react";
+// src/usePreferences.ts
+import { useEffect as useEffect4, useMemo as useMemo4, useSyncExternalStore as useSyncExternalStore3 } from "react";
+import { PreferencesStore } from "@hermesihq/js";
 function usePreferences() {
-  const { client } = useHermsContext();
-  const [preferences, setPreferences] = useState3(null);
-  const [isLoading, setIsLoading] = useState3(true);
-  const [error, setError] = useState3(null);
-  const load = useCallback2(async () => {
-    setIsLoading(true);
-    try {
-      const fresh = await client.getPreferences();
-      setPreferences(fresh);
-      setError(null);
-    } catch (caught) {
-      setError(caught instanceof Error ? caught : new Error(String(caught)));
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client]);
-  useEffect4(() => {
-    let cancelled = false;
-    setIsLoading(true);
-    client.getPreferences().then((fresh) => {
-      if (cancelled) return;
-      setPreferences(fresh);
-      setError(null);
-    }).catch((caught) => {
-      if (cancelled) return;
-      setError(caught instanceof Error ? caught : new Error(String(caught)));
-    }).finally(() => {
-      if (!cancelled) setIsLoading(false);
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [client]);
-  const setPreference = useCallback2(
-    async (update) => {
-      try {
-        setPreferences(await client.updatePreference(update));
-        setError(null);
-      } catch (caught) {
-        setError(caught instanceof Error ? caught : new Error(String(caught)));
-        throw caught;
-      }
-    },
-    [client]
+  const host = useHermsContext();
+  const store = useMemo4(() => new PreferencesStore(host), [host]);
+  useEffect4(() => store.connect(), [store]);
+  const state = useSyncExternalStore3(store.subscribe, store.getSnapshot, store.getSnapshot);
+  return useMemo4(
+    () => ({ ...state, setPreference: store.setPreference, reload: store.reload }),
+    [state, store]
   );
-  return { preferences, isLoading, error, setPreference, reload: load };
 }
 
-// src/react/HermsInbox.tsx
-import { useCallback as useCallback3, useEffect as useEffect5, useMemo as useMemo2, useRef as useRef3, useState as useState4 } from "react";
+// src/HermsInbox.tsx
+import { useCallback, useEffect as useEffect5, useId, useMemo as useMemo5, useRef, useState } from "react";
 import * as Popover from "@radix-ui/react-popover";
 
-// src/react/locale.ts
+// src/locale.ts
 var en = {
   bellLabel: "Notifications",
   bellLabelWithUnread: (count) => `Notifications, ${count} unread`,
@@ -667,7 +115,7 @@ function getHermsInboxStrings(locale) {
   return dictionaries[locale ?? "en"] ?? en;
 }
 
-// src/react/HermsInbox.tsx
+// src/HermsInbox.tsx
 import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
 var placementToSideAlign = {
   "bottom-start": { side: "bottom", align: "start" },
@@ -714,11 +162,12 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
   const { client } = useHermsContext();
   const { unread, unseen } = useUnreadCount();
   const { items, isLoading, isLoadingMore, error, hasMore, loadMore, markRead, markAllRead, archive, refetch } = useInbox();
-  const [open, setOpen] = useState4(false);
-  const [activeIndex, setActiveIndex] = useState4(0);
-  const itemRefs = useRef3([]);
-  const seenIdsRef = useRef3(/* @__PURE__ */ new Set());
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const itemRefs = useRef([]);
+  const seenIdsRef = useRef(/* @__PURE__ */ new Set());
   const strings = getHermsInboxStrings(locale);
+  const titleId = useId();
   useEffect5(() => {
     if (!open || items.length === 0) return;
     const toMark = items.filter((item) => !seenIdsRef.current.has(item.id)).map((item) => item.id);
@@ -729,11 +178,11 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
   useEffect5(() => {
     if (open) setActiveIndex(0);
   }, [open]);
-  const focusItem = useCallback3((index) => {
+  const focusItem = useCallback((index) => {
     setActiveIndex(index);
     itemRefs.current[index]?.focus();
   }, []);
-  const handleListKeyDown = useCallback3(
+  const handleListKeyDown = useCallback(
     (event) => {
       if (items.length === 0) return;
       switch (event.key) {
@@ -759,7 +208,7 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
     },
     [items.length, activeIndex, focusItem]
   );
-  const handleActivate = useCallback3(
+  const handleActivate = useCallback(
     (item) => {
       if (!item.readAt) void markRead(item.id);
       if (onItemClick) {
@@ -770,7 +219,7 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
     },
     [markRead, onItemClick]
   );
-  const rootStyle = useMemo2(() => {
+  const rootStyle = useMemo5(() => {
     const style = {};
     if (theme?.accent) style["--herms-color-accent"] = theme.accent;
     if (theme?.radius) style["--herms-radius"] = theme.radius;
@@ -778,7 +227,9 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
   }, [theme?.accent, theme?.radius]);
   const { side, align } = placementToSideAlign[placement];
   const rootClassName = ["herms-inbox", className].filter(Boolean).join(" ");
-  return /* @__PURE__ */ jsxs("div", { className: rootClassName, style: rootStyle, "data-herms-color-scheme": colorScheme === "auto" ? void 0 : colorScheme, children: [
+  const panelClassName = ["herms-inbox__panel", className].filter(Boolean).join(" ");
+  const colorSchemeAttribute = colorScheme === "auto" ? void 0 : colorScheme;
+  return /* @__PURE__ */ jsxs("div", { className: rootClassName, style: rootStyle, "data-herms-color-scheme": colorSchemeAttribute, children: [
     /* @__PURE__ */ jsx2("span", { className: "herms-inbox__visually-hidden", role: "status", "aria-live": "polite", children: unread > 0 ? strings.bellLabelWithUnread(unread) : "" }),
     /* @__PURE__ */ jsxs(Popover.Root, { open, onOpenChange: setOpen, children: [
       /* @__PURE__ */ jsx2(Popover.Trigger, { asChild: true, children: /* @__PURE__ */ jsxs(
@@ -797,7 +248,10 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
       /* @__PURE__ */ jsx2(Popover.Portal, { children: /* @__PURE__ */ jsxs(
         Popover.Content,
         {
-          className: "herms-inbox__panel",
+          className: panelClassName,
+          style: rootStyle,
+          "data-herms-color-scheme": colorSchemeAttribute,
+          "aria-labelledby": titleId,
           side,
           align,
           sideOffset: 8,
@@ -809,7 +263,7 @@ function HermsInbox({ placement = "bottom-end", onItemClick, theme, colorScheme
           },
           children: [
             /* @__PURE__ */ jsxs("div", { className: "herms-inbox__header", children: [
-              /* @__PURE__ */ jsx2("p", { className: "herms-inbox__title", children: strings.panelTitle }),
+              /* @__PURE__ */ jsx2("p", { className: "herms-inbox__title", id: titleId, children: strings.panelTitle }),
               /* @__PURE__ */ jsxs("div", { className: "herms-inbox__header-actions", children: [
                 /* @__PURE__ */ jsx2("button", { type: "button", className: "herms-inbox__text-button", onClick: () => void markAllRead(), disabled: unread === 0, children: strings.markAllRead }),
                 /* @__PURE__ */ jsx2(Popover.Close, { asChild: true, children: /* @__PURE__ */ jsx2("button", { type: "button", className: "herms-inbox__icon-button", "aria-label": strings.close, children: /* @__PURE__ */ jsx2(CloseIcon, {}) }) })