@activescott/analytics 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# @activescott/analytics
+
+PostHog analytics integration for React Router apps — SPA pageview tracking, user identification, and a reverse proxy helper to avoid ad blockers.
+
+## Install
+
+```bash
+npm install @activescott/analytics posthog-js
+```
+
+`posthog-js` is a peer dependency so consumers control its version. When
+bumping the peer floor, check the
+[posthog-js changelog](https://github.com/PostHog/posthog-js/releases) for
+breaking changes to `PostHogConfig` or the `posthog-js/react` exports, then
+release a matching minor of this package.
+
+## Quick Start
+
+### 1. Add the provider to your app
+
+Mount it where loader data is available (in React Router v7, that means `App`,
+not `Layout` — `Layout` renders with undefined loader data on error
+boundaries, and error pages intentionally get no pageview):
+
+```tsx
+// app/root.tsx
+import { PostHogProvider } from "@activescott/analytics"
+
+export function App() {
+  const { posthogKey, user } = useLoaderData<typeof loader>()
+  // Dynamic-import the provider module only when a key is configured so
+  // disabled/self-host installs pay zero bundle cost for posthog-js.
+  ...
+}
+```
+
+Identify by stable id only — never pass emails, phone numbers, or other PII in
+`properties` unless your privacy policy explicitly covers it:
+
+```tsx
+<PostHogProvider
+  apiKey={posthogKey}
+  options={{ api_host: "/ph", ui_host: "https://us.posthog.com" }}
+  user={user ? { distinctId: user.id } : undefined}
+>
+  ...
+</PostHogProvider>
+```
+
+With no `apiKey` the provider renders children with zero PostHog code paths.
+
+### 2. Add the reverse proxy route
+
+Create `app/routes/ph.$.ts`:
+
+```ts
+import { createPostHogProxy } from "@activescott/analytics/proxy"
+
+export const { loader, action } = createPostHogProxy({
+  apiHost: "https://us.i.posthog.com",
+  assetsHost: "https://us-assets.i.posthog.com",
+  // Opt in only if your privacy policy covers it: forwards the ingress-set
+  // X-Forwarded-For chain so PostHog sees client IPs for geoIP.
+  forwardIp: true,
+})
+```
+
+Register the route in `app/routes.ts`:
+
+```ts
+route("ph/*", "routes/ph.$.ts"),
+```
+
+The proxy hardens the relay for you: upstream origins are fixed at
+configuration time, `Cookie`/`Authorization` (and everything but content-type +
+user-agent) are stripped, `Set-Cookie` is stripped from responses, request
+bodies are capped (default 1 MiB), the upstream call has a timeout (default
+10s), and only known PostHog path prefixes (`e`, `batch`, `decide`, `flags`,
+`s`, `surveys`, `array`, `static`) are proxied. IP forwarding is deliberately
+absent — `X-Forwarded-For` passthrough vs `?ip=` is a privacy decision for you
+to make explicitly.
+
+That's it! PostHog will now:
+
+- Track pageviews on every client-side navigation
+- Identify logged-in users by id
+- Receive events through your own domain (`/ph/*`)
+
+## Versioning
+
+Independent plain-npm versions with git tags of the form `analytics@<version>`
+(see repo README). Consumers pin the versioned package normally — lockfile,
+Dependabot, and Docker all work unchanged.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PostHogProvider } from "./post-hog-provider.js";
+export { PostHogPageviewTracker } from "./post-hog-pageview-tracker.js";
+export { PostHogIdentifier } from "./post-hog-identifier.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,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { PostHogProvider } from "./post-hog-provider.js";
+export { PostHogPageviewTracker } from "./post-hog-pageview-tracker.js";
+export { PostHogIdentifier } from "./post-hog-identifier.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/post-hog-identifier.d.ts

@@ -0,0 +1,12 @@
+interface PostHogIdentifierProps {
+    distinctId?: string | null;
+    properties?: Record<string, unknown>;
+}
+/**
+ * Identifies the current user to PostHog for analytics tracking.
+ * When `distinctId` is provided, calls `posthog.identify()`.
+ * When transitioning from identified to anonymous (distinctId removed), calls `posthog.reset()`.
+ */
+export declare function PostHogIdentifier({ distinctId, properties, }: PostHogIdentifierProps): null;
+export {};
+//# sourceMappingURL=post-hog-identifier.d.ts.map

package/dist/post-hog-identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-identifier.d.ts","sourceRoot":"","sources":["../src/post-hog-identifier.tsx"],"names":[],"mappings":"AAGA,UAAU,sBAAsB;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,UAAU,GACX,EAAE,sBAAsB,QAiBxB"}

package/dist/post-hog-identifier.js

@@ -0,0 +1,23 @@
+import { useEffect, useRef } from "react";
+import { usePostHog } from "posthog-js/react";
+/**
+ * Identifies the current user to PostHog for analytics tracking.
+ * When `distinctId` is provided, calls `posthog.identify()`.
+ * When transitioning from identified to anonymous (distinctId removed), calls `posthog.reset()`.
+ */
+export function PostHogIdentifier({ distinctId, properties, }) {
+    const posthog = usePostHog();
+    const previousDistinctIdReference = useRef(distinctId);
+    useEffect(() => {
+        const previousDistinctId = previousDistinctIdReference.current;
+        if (distinctId) {
+            posthog.identify(distinctId, properties);
+        }
+        else if (previousDistinctId && !distinctId) {
+            posthog.reset();
+        }
+        previousDistinctIdReference.current = distinctId;
+    }, [distinctId, properties, posthog]);
+    return null;
+}
+//# sourceMappingURL=post-hog-identifier.js.map

package/dist/post-hog-identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-identifier.js","sourceRoot":"","sources":["../src/post-hog-identifier.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAO7C;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAChC,UAAU,EACV,UAAU,GACa;IACvB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,MAAM,2BAA2B,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;IAEtD,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,kBAAkB,GAAG,2BAA2B,CAAC,OAAO,CAAA;QAE9D,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;QAC1C,CAAC;aAAM,IAAI,kBAAkB,IAAI,CAAC,UAAU,EAAE,CAAC;YAC7C,OAAO,CAAC,KAAK,EAAE,CAAA;QACjB,CAAC;QAED,2BAA2B,CAAC,OAAO,GAAG,UAAU,CAAA;IAClD,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAA;IAErC,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/post-hog-pageview-tracker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Captures `$pageview` events on client-side route changes.
+ * Required because `capture_pageview` is set to `false` in the PostHog config
+ * (the built-in capture only fires on initial page load, missing SPA navigations).
+ */
+export declare function PostHogPageviewTracker(): null;
+//# sourceMappingURL=post-hog-pageview-tracker.d.ts.map

package/dist/post-hog-pageview-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-pageview-tracker.d.ts","sourceRoot":"","sources":["../src/post-hog-pageview-tracker.tsx"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,sBAAsB,SASrC"}

package/dist/post-hog-pageview-tracker.js

@@ -0,0 +1,17 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+import { usePostHog } from "posthog-js/react";
+/**
+ * Captures `$pageview` events on client-side route changes.
+ * Required because `capture_pageview` is set to `false` in the PostHog config
+ * (the built-in capture only fires on initial page load, missing SPA navigations).
+ */
+export function PostHogPageviewTracker() {
+    const location = useLocation();
+    const posthog = usePostHog();
+    useEffect(() => {
+        posthog.capture("$pageview");
+    }, [location.pathname, location.search, posthog]);
+    return null;
+}
+//# sourceMappingURL=post-hog-pageview-tracker.js.map

package/dist/post-hog-pageview-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-pageview-tracker.js","sourceRoot":"","sources":["../src/post-hog-pageview-tracker.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAE5B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9B,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAEjD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/post-hog-provider.d.ts

@@ -0,0 +1,18 @@
+import type { PostHogConfig } from "posthog-js";
+interface PostHogProviderProps {
+    apiKey?: string;
+    options?: Partial<PostHogConfig>;
+    user?: {
+        distinctId: string;
+        properties?: Record<string, unknown>;
+    };
+    children: React.ReactNode;
+}
+/**
+ * All-in-one PostHog provider for React Router apps.
+ * Wraps children with PostHog context, tracks SPA pageviews, and identifies users.
+ * If `apiKey` is omitted, renders children without any PostHog functionality.
+ */
+export declare function PostHogProvider({ apiKey, options, user, children, }: PostHogProviderProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=post-hog-provider.d.ts.map

package/dist/post-hog-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-provider.d.ts","sourceRoot":"","sources":["../src/post-hog-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAK/C,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;IACnE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACT,EAAE,oBAAoB,+BAqBtB"}

package/dist/post-hog-provider.js

@@ -0,0 +1,19 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PostHogProvider as PHProvider } from "posthog-js/react";
+import { PostHogPageviewTracker } from "./post-hog-pageview-tracker.js";
+import { PostHogIdentifier } from "./post-hog-identifier.js";
+/**
+ * All-in-one PostHog provider for React Router apps.
+ * Wraps children with PostHog context, tracks SPA pageviews, and identifies users.
+ * If `apiKey` is omitted, renders children without any PostHog functionality.
+ */
+export function PostHogProvider({ apiKey, options, user, children, }) {
+    if (!apiKey) {
+        return _jsx(_Fragment, { children: children });
+    }
+    return (_jsxs(PHProvider, { apiKey: apiKey, options: {
+            ...options,
+            capture_pageview: false,
+        }, children: [_jsx(PostHogPageviewTracker, {}), _jsx(PostHogIdentifier, { distinctId: user?.distinctId, properties: user?.properties }), children] }));
+}
+//# sourceMappingURL=post-hog-provider.js.map

package/dist/post-hog-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-provider.js","sourceRoot":"","sources":["../src/post-hog-provider.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,eAAe,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAS5D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACa;IACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,4BAAG,QAAQ,GAAI,CAAA;IACxB,CAAC;IAED,OAAO,CACL,MAAC,UAAU,IACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;YACP,GAAG,OAAO;YACV,gBAAgB,EAAE,KAAK;SACxB,aAED,KAAC,sBAAsB,KAAG,EAC1B,KAAC,iBAAiB,IAChB,UAAU,EAAE,IAAI,EAAE,UAAU,EAC5B,UAAU,EAAE,IAAI,EAAE,UAAU,GAC5B,EACD,QAAQ,IACE,CACd,CAAA;AACH,CAAC"}

package/dist/proxy.d.ts

@@ -0,0 +1,76 @@
+interface PostHogProxyOptions {
+    /**
+     * PostHog API origin, e.g. `"https://us.i.posthog.com"`. Full origin, not a
+     * region — the region choice stays explicit at the call site.
+     */
+    apiHost: string;
+    /**
+     * PostHog static-assets origin. Defaults to `apiHost`. PostHog cloud serves
+     * assets from `<region>-assets.i.posthog.com`; pass it explicitly when the
+     * `static/` prefix must not hit the API origin.
+     */
+    assetsHost?: string;
+    /**
+     * Path prefix this route is mounted at. Defaults to `"/ph"`.
+     */
+    mountPath?: string;
+    /**
+     * Maximum proxied request body in bytes, enforced BEFORE buffering (the
+     * Content-Length header is rejected first, then the stream is accumulated
+     * with a running cap). Defaults to 1 MiB — events are kilobytes.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Upstream timeout in milliseconds. Defaults to 10s; a hung PostHog must
+     * never pin server resources.
+     */
+    timeoutMs?: number;
+    /**
+     * Forward the incoming `X-Forwarded-For` header unchanged so PostHog sees
+     * the client IP chain (set by your ingress, used for geoIP). Defaults to
+     * false — no IP signal leaves your infrastructure unless you opt in.
+     * Spoofing caveat: clients can prepend entries to the chain; PostHog
+     * parses it per its own rules, same as every PostHog proxy setup.
+     */
+    forwardIp?: boolean;
+}
+/**
+ * Creates React Router `loader` and `action` handlers that proxy requests to
+ * PostHog. Use this in a splat route (e.g. `ph.$.ts`) to reverse-proxy all
+ * PostHog requests through your own domain, preventing CSP/CORS issues and ad
+ * blocker interference.
+ *
+ * Hardening (this route is same-origin, so browsers attach your session
+ * cookie to every `/ph` request):
+ *
+ * - Upstream origins are fixed at configuration time, never derived from
+ *   request input.
+ * - `Cookie` and `Authorization` headers are stripped before proxying; only a
+ *   deliberate allowlist of headers is forwarded.
+ * - Response `Set-Cookie` is stripped so PostHog can never plant cookies on
+ *   your domain.
+ * - Request bodies are capped and the upstream call has a timeout.
+ * - Bodies are never logged or echoed back in error responses.
+ * - Client IPs are NOT forwarded by default; pass `forwardIp: true` to send
+ *   the ingress-set `X-Forwarded-For` chain upstream for geoIP.
+ *
+ * @example
+ * ```ts
+ * // app/routes/ph.$.ts
+ * import { createPostHogProxy } from "@activescott/analytics/proxy"
+ * export const { loader, action } = createPostHogProxy({
+ *   apiHost: "https://us.i.posthog.com",
+ *   assetsHost: "https://us-assets.i.posthog.com",
+ * })
+ * ```
+ */
+export declare function createPostHogProxy(options: PostHogProxyOptions): {
+    loader: (loaderArguments: {
+        request: Request;
+    }) => Promise<Response>;
+    action: (actionArguments: {
+        request: Request;
+    }) => Promise<Response>;
+};
+export {};
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAiCA,UAAU,mBAAmB;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAChE,MAAM,EAAE,CAAC,eAAe,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpE,MAAM,EAAE,CAAC,eAAe,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CACrE,CA0HA"}

package/dist/proxy.js

@@ -0,0 +1,215 @@
+const HTTP_NO_CONTENT = 204;
+const HTTP_NOT_MODIFIED = 304;
+const HTTP_NOT_FOUND = 404;
+const HTTP_METHOD_NOT_ALLOWED = 405;
+const HTTP_PAYLOAD_TOO_LARGE = 413;
+const HTTP_BAD_GATEWAY = 502;
+const HTTP_GATEWAY_TIMEOUT = 504;
+const HTTP_INTERNAL_SERVER_ERROR = 500;
+const DEFAULT_MOUNT_PATH = "/ph";
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * First path segments (after the mount prefix) that may be proxied. Everything
+ * else answers 404 so this route can never become a generic relay. Covers
+ * posthog-js capture (`e`, `batch`), flags (`decide`, `flags`), session
+ * replay (`s`), surveys (`surveys`), autotrack/toolbar helpers (`array`) and
+ * static assets (`static`, routed to the assets host). Widen with care.
+ */
+const ALLOWED_PREFIXES = [
+    "e",
+    "batch",
+    "decide",
+    "flags",
+    "s",
+    "surveys",
+    "array",
+    "static",
+];
+const ALLOWED_METHODS = ["GET", "POST", "OPTIONS"];
+/**
+ * Creates React Router `loader` and `action` handlers that proxy requests to
+ * PostHog. Use this in a splat route (e.g. `ph.$.ts`) to reverse-proxy all
+ * PostHog requests through your own domain, preventing CSP/CORS issues and ad
+ * blocker interference.
+ *
+ * Hardening (this route is same-origin, so browsers attach your session
+ * cookie to every `/ph` request):
+ *
+ * - Upstream origins are fixed at configuration time, never derived from
+ *   request input.
+ * - `Cookie` and `Authorization` headers are stripped before proxying; only a
+ *   deliberate allowlist of headers is forwarded.
+ * - Response `Set-Cookie` is stripped so PostHog can never plant cookies on
+ *   your domain.
+ * - Request bodies are capped and the upstream call has a timeout.
+ * - Bodies are never logged or echoed back in error responses.
+ * - Client IPs are NOT forwarded by default; pass `forwardIp: true` to send
+ *   the ingress-set `X-Forwarded-For` chain upstream for geoIP.
+ *
+ * @example
+ * ```ts
+ * // app/routes/ph.$.ts
+ * import { createPostHogProxy } from "@activescott/analytics/proxy"
+ * export const { loader, action } = createPostHogProxy({
+ *   apiHost: "https://us.i.posthog.com",
+ *   assetsHost: "https://us-assets.i.posthog.com",
+ * })
+ * ```
+ */
+export function createPostHogProxy(options) {
+    const apiHost = normalizeOrigin(options.apiHost);
+    const assetsHost = normalizeOrigin(options.assetsHost ?? options.apiHost);
+    const mountPath = (options.mountPath ?? DEFAULT_MOUNT_PATH).replace(/\/$/, "");
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const forwardIp = options.forwardIp ?? false;
+    async function proxyRequest(request) {
+        if (!ALLOWED_METHODS.includes(request.method)) {
+            return new Response("Method Not Allowed", {
+                status: HTTP_METHOD_NOT_ALLOWED,
+            });
+        }
+        let pathname;
+        try {
+            const url = new URL(request.url);
+            pathname = url.pathname;
+            if (!pathname.startsWith(`${mountPath}/`) && pathname !== mountPath) {
+                return new Response("Not Found", { status: HTTP_NOT_FOUND });
+            }
+            const stripped = pathname.slice(mountPath.length).replace(/^\//, "");
+            const firstSegment = stripped.split("/", 1)[0] ?? "";
+            const isAllowed = ALLOWED_PREFIXES.includes(firstSegment);
+            if (!isAllowed) {
+                return new Response("Not Found", { status: HTTP_NOT_FOUND });
+            }
+            const targetHost = firstSegment === "static" ? assetsHost : apiHost;
+            const targetUrl = new URL(`${stripped}${url.search}`, `${targetHost}/`);
+            const headers = new Headers();
+            const contentType = request.headers.get("content-type");
+            // Accept whatever content type the client sent (posthog-js uses
+            // `text/plain` for sendBeacon fallbacks) — the body is opaque bytes.
+            if (contentType) {
+                headers.set("content-type", contentType);
+            }
+            const userAgent = request.headers.get("user-agent");
+            if (userAgent) {
+                headers.set("user-agent", userAgent);
+            }
+            // Opt-in only: pass the ingress-set client IP chain through for
+            // PostHog geoIP. Forwarded unchanged (never synthesized here) and never
+            // logged. See the `forwardIp` option docs for the spoofing caveat.
+            if (forwardIp) {
+                const forwardedFor = request.headers.get("x-forwarded-for");
+                if (forwardedFor) {
+                    headers.set("x-forwarded-for", forwardedFor);
+                }
+            }
+            // Deliberately NOT forwarded: Cookie, Authorization, and everything
+            // else.
+            let body;
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                const contentLength = request.headers.get("content-length");
+                if (contentLength && Number(contentLength) > maxBodyBytes) {
+                    return new Response("Payload Too Large", {
+                        status: HTTP_PAYLOAD_TOO_LARGE,
+                    });
+                }
+                body = await readCappedBody(request.body, maxBodyBytes);
+                if (!body) {
+                    return new Response("Payload Too Large", {
+                        status: HTTP_PAYLOAD_TOO_LARGE,
+                    });
+                }
+            }
+            const phResponse = await fetch(targetUrl.toString(), {
+                method: request.method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (phResponse.status === HTTP_NO_CONTENT ||
+                phResponse.status === HTTP_NOT_MODIFIED ||
+                !phResponse.body) {
+                return new Response(null, {
+                    status: phResponse.status,
+                    statusText: phResponse.statusText,
+                });
+            }
+            const responseHeaders = new Headers(phResponse.headers);
+            responseHeaders.delete("content-encoding");
+            responseHeaders.delete("content-length");
+            responseHeaders.delete("set-cookie");
+            return new Response(phResponse.body, {
+                status: phResponse.status,
+                statusText: phResponse.statusText,
+                headers: responseHeaders,
+            });
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === "TimeoutError") {
+                return new Response("Gateway Timeout", {
+                    status: HTTP_GATEWAY_TIMEOUT,
+                });
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                return new Response("Gateway Timeout", {
+                    status: HTTP_GATEWAY_TIMEOUT,
+                });
+            }
+            return new Response("Bad Gateway", { status: HTTP_BAD_GATEWAY });
+        }
+    }
+    return {
+        loader({ request }) {
+            return proxyRequest(request);
+        },
+        action({ request }) {
+            return proxyRequest(request);
+        },
+    };
+}
+function normalizeOrigin(origin) {
+    const url = new URL(origin);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`PostHog origin must be http(s): received ${url.protocol}`);
+    }
+    return url.origin;
+}
+/**
+ * Accumulates a request stream up to `maxBytes`. Returns undefined when the
+ * body exceeds the cap (caller answers 413 without ever buffering it whole).
+ */
+async function readCappedBody(stream, maxBytes) {
+    if (!stream) {
+        return new Uint8Array(0);
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => { });
+                return undefined;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@activescott/analytics",
+  "version": "0.2.0",
+  "description": "PostHog analytics integration for React Router apps — provider, SPA pageview tracking, user identification, and reverse proxy helper",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "import": "./dist/proxy.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "posthog",
+    "analytics",
+    "react-router",
+    "spa",
+    "pageview",
+    "proxy"
+  ],
+  "author": "Scott Willeke",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/activescott/js-utils.git",
+    "directory": "packages/analytics"
+  },
+  "peerDependencies": {
+    "posthog-js": "^1.200.0",
+    "react": ">=18",
+    "react-router": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/react": "^19.2.14",
+    "posthog-js": "^1.351.4",
+    "react": "^19.2.4",
+    "react-router": "^7.10.1",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.10"
+  }
+}