@curvenote/analytics-posthog 2.0.0

package/README.md

@@ -0,0 +1,178 @@
+# @curvenote/analytics-posthog
+
+[![@curvenote/analytics-posthog on npm](https://img.shields.io/npm/v/@curvenote/analytics-posthog.svg)](https://www.npmjs.com/package/@curvenote/analytics-posthog)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/curvenote/curvenote/blob/main/LICENSE)
+
+Shared PostHog client integration for Curvenote React Router apps. Wires the `posthog-js` singleton into `@curvenote/theme-ui`’s `AnalyticsBoundary` so `useAnalytics()` calls from theme UI and renderers reach PostHog reliably.
+
+Used by `apps/theme` (`app: scms-theme`) and `apps/openrxiv` (`app: openrxiv-reader`). See [docs/analytics.md](../../docs/analytics.md) for the full monorepo setup guide.
+
+## Install
+
+```bash
+bun add @curvenote/analytics-posthog posthog-js @posthog/react @curvenote/theme-ui
+```
+
+Peer dependencies: `react`, `react-dom`, `react-router`, `@curvenote/theme-ui`.
+
+## Quick start
+
+### 1. Vite build-time config
+
+Load PostHog credentials from app-config and expose them to the client bundle (do not import secrets via `@app-config/main` in client code):
+
+```ts
+// vite.config.ts
+const posthogProjectToken = analytics.posthog?.projectToken ?? '';
+const posthogApiHost = analytics.posthog?.apiHost ?? '';
+
+export default defineConfig({
+  define: {
+    __POSTHOG_PROJECT_TOKEN__: JSON.stringify(posthogProjectToken),
+    __POSTHOG_API_HOST__: JSON.stringify(posthogApiHost),
+  },
+  resolve: {
+    dedupe: ['@curvenote/theme-ui', '@curvenote/analytics-posthog', 'posthog-js', '@posthog/react', 'react', 'react-dom'],
+  },
+});
+```
+
+Set `APP_CONFIG_ENV` when running `react-router build` so the correct token is inlined.
+
+### 2. Client entry
+
+```tsx
+// app/entry.client.tsx
+import { initPosthogClient, posthog } from '@curvenote/analytics-posthog';
+import { PostHogProvider } from '@posthog/react';
+
+declare const __POSTHOG_PROJECT_TOKEN__: string;
+declare const __POSTHOG_API_HOST__: string;
+
+initPosthogClient({
+  projectToken: __POSTHOG_PROJECT_TOKEN__,
+  apiHost: __POSTHOG_API_HOST__,
+  app: 'my-app-id', // PostHog super-property on every event
+});
+
+hydrateRoot(
+  document,
+  <PostHogProvider client={posthog}>
+    <HydratedRouter />
+  </PostHogProvider>,
+);
+```
+
+### 3. Root layout — site super-properties
+
+Pass `site` from the root loader into `PostHogRootProvider` / `initPosthogClient` so `site_id`, `site_name`, and `site_private` register synchronously at init (alongside `app`). Optionally keep `usePostHogSiteRegistration({ site })` to re-register if site loader data changes.
+
+```tsx
+import { usePostHogSiteRegistration } from '@curvenote/analytics-posthog';
+
+function PostHogLayout({ site, posthog, children }) {
+  usePostHogSiteRegistration({ site });
+  return (
+    <PostHogRootProvider config={posthog} site={site}>
+      {children}
+    </PostHogRootProvider>
+  );
+}
+```
+
+### 4. Routes — boundary + page views
+
+```tsx
+import { PostHogAnalyticsBoundary, useAnalyticsPageView } from '@curvenote/analytics-posthog';
+import { useAnalytics } from '@curvenote/theme-ui';
+
+function PageViewedEvent({ slug }: { slug: string }) {
+  useAnalyticsPageView('article_viewed', { slug }, [slug]);
+  return null;
+}
+
+export default function ArticleRoute() {
+  const metadata = useMemo(() => ({ workVersionId, doi, /* camelCase */ }), [/* … */]);
+
+  return (
+    <PostHogAnalyticsBoundary context={metadata}>
+      <PageViewedEvent slug={page.slug} />
+      {/* MystProviders, PageProviders, ArticleBar, etc. */}
+    </PostHogAnalyticsBoundary>
+  );
+}
+
+function MyButton() {
+  const capture = useAnalytics();
+  return <button onClick={() => capture('button_clicked', { surface: 'toolbar' })} />;
+}
+```
+
+## API
+
+### `initPosthogClient(options)`
+
+Initialize the shared `posthog-js` instance. Call once from `entry.client.tsx`.
+
+| Option | Description |
+|--------|-------------|
+| `projectToken` | Public `phc_*` project token |
+| `apiHost` | Ingestion host (e.g. `https://us.i.posthog.com` or a reverse proxy) |
+| `app` | Value for the `app` super-property (e.g. `scms-theme`) |
+| `site` | Optional root-loader site; registers `site_id`, `site_name`, `site_private` at init |
+
+No-op when `projectToken` is empty. Dispatches a `posthog:loaded` custom event when ready (`POSTHOG_LOADED_EVENT`).
+
+### `PostHogAnalyticsBoundary`
+
+React provider that connects `useAnalytics()` from `@curvenote/theme-ui` to PostHog.
+
+- **`context`** — optional route-level metadata (`camelCase`); merged into every event and converted to `snake_case` by `useAnalytics()`.
+- Uses the **posthog-js singleton**, not `usePostHog()`, so capture works before the React provider settles.
+
+### `useAnalyticsPageView(event, properties?, deps?, options?)`
+
+Fire a custom page-view-style event once per React Router navigation (`location.key`). Dedupes Strict Mode double-mounts.
+
+```tsx
+useAnalyticsPageView(
+  'submissions_index_viewed',
+  { submissionCount: 10 },
+  [submissionCount],
+  { enabled: true }, // optional; default true
+);
+```
+
+Do **not** gate on `usePostHog().__loaded` — `initPosthogClient()` runs before hydrate and posthog-js queues events until ready.
+
+### `usePostHogSiteRegistration({ site })`
+
+Re-registers site super-properties when root loader site data changes. Primary registration is at `initPosthogClient()` time via the `site` option.
+
+### Low-level helpers
+
+| Export | Use when |
+|--------|----------|
+| `capturePosthogBoundaryEvent(event, props)` | Properties already `snake_case` (boundary `capture` fn) |
+| `capturePosthogClientEvent(event, props)` | Direct capture; converts `camelCase` → `snake_case` |
+| `isPosthogClientEnabled()` | Build had a non-empty project token |
+| `posthog` | Same singleton passed to `PostHogProvider` |
+
+## Conventions
+
+- **Event names** in PostHog: `snake_case` (e.g. `article_viewed`, `submission_card_clicked`).
+- **Properties** passed to `useAnalytics()`: `camelCase`; the theme-ui hook converts to `snake_case`.
+- **Product analytics**: use `useAnalytics()` inside a `PostHogAnalyticsBoundary`.
+- **Exceptions**: `usePostHog().captureException()` in error boundaries is fine.
+
+## Vite monorepo notes
+
+In development, alias `@curvenote/analytics-posthog` to `packages/analytics-posthog/src/index.ts`. In production, alias to `dist/index.js` after `bun run build` in this package.
+
+Also alias `@curvenote/theme-ui` and `@curvenote/renderers` to workspace `src` in dev so a single `AnalyticsBoundary` context is shared (see `resolve.dedupe` above).
+
+## Related docs
+
+- [docs/analytics.md](../../docs/analytics.md) — monorepo integration checklist
+- [apps/theme/ANALYTICS_INSTRUMENTATION.md](../../apps/theme/ANALYTICS_INSTRUMENTATION.md) — ArticleBar / UI event catalog
+- [apps/openrxiv/ANALYTICS_INSTRUMENTATION.md](../../apps/openrxiv/ANALYTICS_INSTRUMENTATION.md) — OpenRxiv route and server events

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { POSTHOG_LOADED_EVENT, capturePosthogBoundaryEvent, capturePosthogClientEvent, initPosthogClient, isPosthogClientEnabled, posthog, registerPosthogSiteSuperProperties, setPosthogClientEnabled, siteToPosthogSuperProperties, type InitPosthogClientOptions, type PosthogSiteSuperProperties, } from './posthog-client.js';
+export { toSnakeKeys } from './property-keys.js';
+export { PostHogAnalyticsBoundary } from './posthog-analytics-boundary.js';
+export { useAnalyticsPageView, type UseAnalyticsPageViewOptions, } from './use-analytics-page-view.js';
+export { usePostHogSiteRegistration, type PostHogSiteRegistrationArgs, type PostHogSiteRegistrationSite, } from './use-posthog-site-registration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,OAAO,EACP,kCAAkC,EAClC,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,0BAA0B,EAC1B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,oCAAoC,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { POSTHOG_LOADED_EVENT, capturePosthogBoundaryEvent, capturePosthogClientEvent, initPosthogClient, isPosthogClientEnabled, posthog, registerPosthogSiteSuperProperties, setPosthogClientEnabled, siteToPosthogSuperProperties, } from './posthog-client.js';
+export { toSnakeKeys } from './property-keys.js';
+export { PostHogAnalyticsBoundary } from './posthog-analytics-boundary.js';
+export { useAnalyticsPageView, } from './use-analytics-page-view.js';
+export { usePostHogSiteRegistration, } from './use-posthog-site-registration.js';

package/dist/posthog-analytics-boundary.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from 'react';
+/**
+ * Wires PostHog into the @curvenote/theme-ui AnalyticsBoundary so that
+ * useAnalytics() calls from packages/ui forward to the configured PostHog
+ * client. The supplied `context` (camelCase) is merged into every captured
+ * event with keys converted to snake_case.
+ *
+ * Uses the posthog-js singleton from initPosthogClient() (not usePostHog()) so
+ * capture stays wired even before the React provider settles.
+ */
+export declare function PostHogAnalyticsBoundary({ context, children, }: {
+    context?: Record<string, unknown>;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=posthog-analytics-boundary.d.ts.map

package/dist/posthog-analytics-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-analytics-boundary.d.ts","sourceRoot":"","sources":["../src/posthog-analytics-boundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIpD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,QAAQ,GACT,EAAE;IACD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE,SAAS,CAAC;CACrB,2CASA"}

package/dist/posthog-analytics-boundary.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback } from 'react';
+import { AnalyticsBoundary } from '@curvenote/theme-ui';
+import { capturePosthogBoundaryEvent } from './posthog-client.js';
+/**
+ * Wires PostHog into the @curvenote/theme-ui AnalyticsBoundary so that
+ * useAnalytics() calls from packages/ui forward to the configured PostHog
+ * client. The supplied `context` (camelCase) is merged into every captured
+ * event with keys converted to snake_case.
+ *
+ * Uses the posthog-js singleton from initPosthogClient() (not usePostHog()) so
+ * capture stays wired even before the React provider settles.
+ */
+export function PostHogAnalyticsBoundary({ context, children, }) {
+    const capture = useCallback((event, properties) => {
+        capturePosthogBoundaryEvent(event, properties);
+    }, []);
+    return (_jsx(AnalyticsBoundary, { capture: capture, context: context, children: children }));
+}

package/dist/posthog-client.d.ts

@@ -0,0 +1,32 @@
+import posthog from 'posthog-js';
+export declare const POSTHOG_LOADED_EVENT = "posthog:loaded";
+export declare function setPosthogClientEnabled(enabled: boolean): void;
+export declare function isPosthogClientEnabled(): boolean;
+/** Site fields registered as PostHog super-properties (`SiteDTO` and similar shapes satisfy this). */
+export type PosthogSiteSuperProperties = {
+    id: string;
+    name: string;
+    private?: boolean;
+};
+export type InitPosthogClientOptions = {
+    projectToken: string;
+    apiHost: string;
+    /** Registered as a PostHog super-property on every event (e.g. `scms-theme`, `openrxiv-reader`). */
+    app: string;
+    /** When set, `site_id`, `site_name`, and `site_private` are registered at init (not after async load). */
+    site?: PosthogSiteSuperProperties | null;
+};
+export declare function siteToPosthogSuperProperties(site: PosthogSiteSuperProperties): Record<string, unknown>;
+/** Register site super-properties on the PostHog client. No-op when analytics is disabled or `site.name` is missing. */
+export declare function registerPosthogSiteSuperProperties(site: PosthogSiteSuperProperties | null | undefined): void;
+/**
+ * Initialize the shared posthog-js singleton. Call once per page load from a root provider
+ * (e.g. with PostHog settings from a React Router loader).
+ */
+export declare function initPosthogClient({ projectToken, apiHost, app, site }: InitPosthogClientOptions): void;
+/** PostHog capture with camelCase → snake_case (direct callers outside useAnalytics). */
+export declare function capturePosthogClientEvent(event: string, properties?: Record<string, unknown>): void;
+/** PostHog capture when properties are already snake_case (AnalyticsBoundary → useAnalytics). */
+export declare function capturePosthogBoundaryEvent(event: string, properties?: Record<string, unknown>): void;
+export { posthog };
+//# sourceMappingURL=posthog-client.d.ts.map

package/dist/posthog-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-client.d.ts","sourceRoot":"","sources":["../src/posthog-client.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,YAAY,CAAC;AAGjC,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAKrD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAEvD;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,sGAAsG;AACtG,MAAM,MAAM,0BAA0B,GAAG;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,GAAG,EAAE,MAAM,CAAC;IACZ,0GAA0G;IAC1G,IAAI,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;CAC1C,CAAC;AAEF,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED,wHAAwH;AACxH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GAClD,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,wBAAwB,QAqB/F;AAED,yFAAyF;AACzF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI,CAGN;AAED,iGAAiG;AACjG,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI,CAGN;AAED,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/posthog-client.js

@@ -0,0 +1,62 @@
+import posthog from 'posthog-js';
+import { toSnakeKeys } from './property-keys.js';
+export const POSTHOG_LOADED_EVENT = 'posthog:loaded';
+let clientEnabled = false;
+let clientInitialized = false;
+export function setPosthogClientEnabled(enabled) {
+    clientEnabled = enabled;
+}
+export function isPosthogClientEnabled() {
+    return clientEnabled;
+}
+export function siteToPosthogSuperProperties(site) {
+    return {
+        site_id: site.id,
+        site_name: site.name,
+        site_private: site.private === true,
+    };
+}
+/** Register site super-properties on the PostHog client. No-op when analytics is disabled or `site.name` is missing. */
+export function registerPosthogSiteSuperProperties(site) {
+    if (!site?.name || !isPosthogClientEnabled())
+        return;
+    posthog.register(siteToPosthogSuperProperties(site));
+}
+/**
+ * Initialize the shared posthog-js singleton. Call once per page load from a root provider
+ * (e.g. with PostHog settings from a React Router loader).
+ */
+export function initPosthogClient({ projectToken, apiHost, app, site }) {
+    if (clientInitialized)
+        return;
+    const token = projectToken?.trim();
+    setPosthogClientEnabled(Boolean(token));
+    if (!token)
+        return;
+    clientInitialized = true;
+    posthog.init(token, {
+        api_host: apiHost?.trim() || 'https://us.i.posthog.com',
+        defaults: '2026-01-30',
+        __add_tracing_headers: [window.location.host],
+        loaded: () => {
+            window.dispatchEvent(new CustomEvent(POSTHOG_LOADED_EVENT));
+        },
+    });
+    posthog.register({
+        app,
+        ...(site?.name ? siteToPosthogSuperProperties(site) : {}),
+    });
+}
+/** PostHog capture with camelCase → snake_case (direct callers outside useAnalytics). */
+export function capturePosthogClientEvent(event, properties) {
+    if (!isPosthogClientEnabled())
+        return;
+    posthog.capture(event, toSnakeKeys(properties));
+}
+/** PostHog capture when properties are already snake_case (AnalyticsBoundary → useAnalytics). */
+export function capturePosthogBoundaryEvent(event, properties) {
+    if (!isPosthogClientEnabled())
+        return;
+    posthog.capture(event, properties);
+}
+export { posthog };

package/dist/property-keys.d.ts

@@ -0,0 +1,4 @@
+export declare function camelToSnake(s: string): string;
+/** Convert analytics property keys from camelCase to PostHog snake_case. Skips undefined values. */
+export declare function toSnakeKeys(input?: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=property-keys.d.ts.map

package/dist/property-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-keys.d.ts","sourceRoot":"","sources":["../src/property-keys.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQpF"}

package/dist/property-keys.js

@@ -0,0 +1,18 @@
+export function camelToSnake(s) {
+    return s
+        .replace(/([A-Z])/g, '_$1')
+        .replace(/^_/, '')
+        .toLowerCase();
+}
+/** Convert analytics property keys from camelCase to PostHog snake_case. Skips undefined values. */
+export function toSnakeKeys(input) {
+    if (!input)
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (v === undefined)
+            continue;
+        out[camelToSnake(k)] = v;
+    }
+    return out;
+}

package/dist/use-analytics-page-view.d.ts

@@ -0,0 +1,13 @@
+export type UseAnalyticsPageViewOptions = {
+    /** When false, the event is not captured. Defaults to true. */
+    enabled?: boolean;
+};
+/**
+ * Captures a page-view-style analytics event once per navigation (location.key),
+ * after optional readiness gates pass. Dedupes React Strict Mode double-mounts.
+ *
+ * Does not wait on usePostHog().__loaded — initPosthogClient() runs before hydrate
+ * and posthog-js queues events until the client is ready.
+ */
+export declare function useAnalyticsPageView(event: string, properties?: Record<string, unknown>, deps?: readonly unknown[], options?: UseAnalyticsPageViewOptions): void;
+//# sourceMappingURL=use-analytics-page-view.d.ts.map

package/dist/use-analytics-page-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-analytics-page-view.d.ts","sourceRoot":"","sources":["../src/use-analytics-page-view.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,2BAA2B,GAAG;IACxC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,IAAI,GAAE,SAAS,OAAO,EAAO,EAC7B,OAAO,CAAC,EAAE,2BAA2B,QAgBtC"}

package/dist/use-analytics-page-view.js

@@ -0,0 +1,25 @@
+import { useEffect, useRef } from 'react';
+import { useLocation } from 'react-router';
+import { useAnalytics } from '@curvenote/theme-ui';
+/**
+ * Captures a page-view-style analytics event once per navigation (location.key),
+ * after optional readiness gates pass. Dedupes React Strict Mode double-mounts.
+ *
+ * Does not wait on usePostHog().__loaded — initPosthogClient() runs before hydrate
+ * and posthog-js queues events until the client is ready.
+ */
+export function useAnalyticsPageView(event, properties, deps = [], options) {
+    const enabled = options?.enabled ?? true;
+    const capture = useAnalytics();
+    const location = useLocation();
+    const lastKeyRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const dedupeKey = `${location.key}:${event}`;
+        if (lastKeyRef.current === dedupeKey)
+            return;
+        lastKeyRef.current = dedupeKey;
+        capture(event, properties);
+    }, [enabled, location.key, event, capture, ...deps]);
+}

package/dist/use-posthog-site-registration.d.ts

@@ -0,0 +1,13 @@
+import { type PosthogSiteSuperProperties } from './posthog-client.js';
+/** Site fields read for PostHog super-properties (`SiteDTO` and similar shapes satisfy this). */
+export type PostHogSiteRegistrationSite = PosthogSiteSuperProperties;
+export type PostHogSiteRegistrationArgs = {
+    site: PostHogSiteRegistrationSite | null | undefined;
+};
+/**
+ * Keeps site super-properties (`site_id`, `site_name`, `site_private`) in sync when site
+ * loader data changes. Primary registration happens in `initPosthogClient()`; this hook covers
+ * late-arriving site data or updates after the first init.
+ */
+export declare function usePostHogSiteRegistration({ site }: PostHogSiteRegistrationArgs): void;
+//# sourceMappingURL=use-posthog-site-registration.d.ts.map

package/dist/use-posthog-site-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-posthog-site-registration.d.ts","sourceRoot":"","sources":["../src/use-posthog-site-registration.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,iGAAiG;AACjG,MAAM,MAAM,2BAA2B,GAAG,0BAA0B,CAAC;AAErE,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,2BAA2B,GAAG,IAAI,GAAG,SAAS,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,IAAI,EAAE,EAAE,2BAA2B,QAI/E"}

package/dist/use-posthog-site-registration.js

@@ -0,0 +1,12 @@
+import { useEffect } from 'react';
+import { registerPosthogSiteSuperProperties, } from './posthog-client.js';
+/**
+ * Keeps site super-properties (`site_id`, `site_name`, `site_private`) in sync when site
+ * loader data changes. Primary registration happens in `initPosthogClient()`; this hook covers
+ * late-arriving site data or updates after the first init.
+ */
+export function usePostHogSiteRegistration({ site }) {
+    useEffect(() => {
+        registerPosthogSiteSuperProperties(site);
+    }, [site?.id, site?.name, site?.private]);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@curvenote/analytics-posthog",
+  "version": "2.0.0",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "compile": "bun run typecheck",
+    "lint": "eslint \"src/**/*.ts*\" -c ./.eslintrc.cjs",
+    "lint:format": "prettier --check \"src/**/*.{ts,tsx,md}\"",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "posthog-js": "^1.372.8"
+  },
+  "peerDependencies": {
+    "@curvenote/theme-ui": "^2.0.0",
+    "react": "^16.8 || ^17.0 || ^18.0 || ^19.0",
+    "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0",
+    "react-router": "^7.0.0"
+  },
+  "devDependencies": {
+    "@curvenote/theme-ui": "workspace:*",
+    "react-router": "^7.5.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}