@lunardinos/tanstack-router 0.2.0

package/README.md

@@ -0,0 +1,94 @@
+# @lunardinos/tanstack-router
+
+[Lunar Dinos](https://lunardinos.com) session recording SDK for apps using [TanStack Router](https://tanstack.com/router).
+
+Captures session replays, page navigations, clicks, inputs, and errors — with zero configuration beyond wrapping your app.
+
+## Installation
+
+```bash
+npm install @lunardinos/tanstack-router
+```
+
+## Setup
+
+Wrap your app with `LunarDinosProvider` inside your router context:
+
+```tsx
+import { LunarDinosProvider } from "@lunardinos/tanstack-router"
+
+function App() {
+  return (
+    <LunarDinosProvider apiKey="your-api-key">
+      <Outlet />
+    </LunarDinosProvider>
+  )
+}
+```
+
+Route changes are tracked automatically via TanStack Router's `useMatches()`.
+
+## Identifying users
+
+```tsx
+import { useLunarDinos } from "@lunardinos/tanstack-router"
+
+function Dashboard() {
+  const { identify } = useLunarDinos()
+
+  useEffect(() => {
+    identify({
+      user: { id: "user-123", email: "jane@acme.com" },
+      account: { id: "acme", name: "Acme Inc" },
+    })
+  }, [])
+
+  return <div>...</div>
+}
+```
+
+## Cookie consent
+
+By default the recorder persists session and visitor IDs in cookies. If your site requires consent before setting cookies, start in `cookieless` mode and upgrade after consent:
+
+```tsx
+import { LunarDinosProvider, useLunarDinos } from "@lunardinos/tanstack-router"
+
+// 1. Start without cookies — recording works, but sessions are not persisted
+//    across page loads. Identity is handled server-side via hashing.
+function App() {
+  return (
+    <LunarDinosProvider apiKey="your-api-key" defaultPersistence="cookieless">
+      <Outlet />
+    </LunarDinosProvider>
+  )
+}
+
+// 2. After consent, switch to cookie-based persistence.
+//    The server automatically links the previous server-side identity
+//    to the new cookie-based one.
+function CookieBanner() {
+  const { setPersistence } = useLunarDinos()
+
+  return (
+    <button onClick={() => setPersistence("cookie")}>
+      Accept cookies
+    </button>
+  )
+}
+```
+
+In `cookieless` mode no data is stored on the user's device. Each page load gets a fresh session ID and the server stitches sessions together using a visitor hash, referrer, and timing. Note that recording and data collection still happen — only client-side storage is removed.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | required | Your Lunar Dinos API key |
+| `endpoint` | `string` | `https://ingest.lunardinos.com` | Custom ingestion endpoint |
+| `enabled` | `boolean` | `true` | Disable recording (e.g. in dev) |
+| `defaultPersistence` | `"cookie" \| "cookieless"` | `"cookie"` | Initial persistence mode — can be changed at runtime via `setPersistence()` |
+
+## Learn more
+
+Visit [lunardinos.com](https://lunardinos.com) to get started.

package/dist/index.js

@@ -0,0 +1,142 @@
+// src/provider.tsx
+import {
+  createLunarDinosRecorder
+} from "@lunardinos/browser";
+import { useMatches } from "@tanstack/react-router";
+import {
+  Component,
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var RecorderContext = createContext(null);
+function useLunarDinos() {
+  const ctx = useContext(RecorderContext);
+  if (!ctx)
+    throw new Error("useLunarDinos must be used within LunarDinosProvider");
+  return ctx;
+}
+function buildRoutePattern(matches) {
+  const deepest = matches[matches.length - 1];
+  return deepest?.fullPath ?? deepest?.id ?? "/";
+}
+function extractParams(matches) {
+  const deepest = matches[matches.length - 1];
+  const raw = deepest?.params;
+  if (!raw || Object.keys(raw).length === 0)
+    return null;
+  return Object.fromEntries(Object.entries(raw).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+}
+var noopContextValue = {
+  identify: () => {},
+  setPersistence: () => {}
+};
+
+class RecorderErrorBoundary extends Component {
+  state = { hasError: false };
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+  componentDidCatch(_error, _info) {}
+  render() {
+    return this.props.children;
+  }
+}
+function RecorderInner({
+  apiKey,
+  endpoint,
+  enabled = true,
+  defaultPersistence,
+  children
+}) {
+  const matches = useMatches();
+  const recorderRef = useRef(null);
+  const prevRouteRef = useRef(null);
+  const matchesRef = useRef(matches);
+  matchesRef.current = matches;
+  useEffect(() => {
+    if (!enabled)
+      return;
+    try {
+      const initMatches = matchesRef.current;
+      const routePattern = buildRoutePattern(initMatches);
+      const params = extractParams(initMatches);
+      const recorder = createLunarDinosRecorder({ apiKey, endpoint, defaultPersistence });
+      recorderRef.current = recorder;
+      prevRouteRef.current = routePattern;
+      recorder.start({
+        pageMetadata: {
+          href: window.location.href,
+          title: document.title,
+          routePattern,
+          params
+        }
+      });
+      const onBeforeUnload = () => {
+        try {
+          recorder.flush({ beacon: true });
+          recorder.stop();
+        } catch {}
+      };
+      window.addEventListener("beforeunload", onBeforeUnload);
+      return () => {
+        window.removeEventListener("beforeunload", onBeforeUnload);
+        try {
+          recorder.flush({ beacon: true });
+          recorder.stop();
+        } catch {}
+        recorderRef.current = null;
+      };
+    } catch {
+      recorderRef.current = null;
+    }
+  }, [apiKey, endpoint, enabled, defaultPersistence]);
+  useEffect(() => {
+    try {
+      const recorder = recorderRef.current;
+      if (!enabled || !recorder || !recorder.isRecording())
+        return;
+      const routePattern = buildRoutePattern(matches);
+      if (routePattern === prevRouteRef.current)
+        return;
+      prevRouteRef.current = routePattern;
+      const params = extractParams(matches);
+      recorder.emitPageEvent({
+        href: window.location.href,
+        title: document.title,
+        routePattern,
+        params
+      });
+    } catch {}
+  }, [matches, enabled]);
+  const contextValue = useMemo(() => enabled ? {
+    identify: (payload) => {
+      try {
+        recorderRef.current?.identify(payload);
+      } catch {}
+    },
+    setPersistence: (mode) => {
+      try {
+        recorderRef.current?.setPersistence(mode);
+      } catch {}
+    }
+  } : noopContextValue, [enabled]);
+  return /* @__PURE__ */ jsx(RecorderContext.Provider, {
+    value: contextValue,
+    children
+  });
+}
+function LunarDinosProvider(props) {
+  return /* @__PURE__ */ jsx(RecorderErrorBoundary, {
+    children: /* @__PURE__ */ jsx(RecorderInner, {
+      ...props
+    })
+  });
+}
+export {
+  useLunarDinos,
+  LunarDinosProvider
+};

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export type { IdentifyPayload } from "./provider";
+export { LunarDinosProvider, useLunarDinos } from "./provider";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/index.js

@@ -0,0 +1 @@
+export { LunarDinosProvider, useLunarDinos } from "./provider";

package/dist/src/provider.d.ts

@@ -0,0 +1,18 @@
+import { type IdentifyPayload, type PersistenceMode } from "@lunardinos/browser";
+import { type ReactNode } from "react";
+export type { IdentifyPayload, PersistenceMode } from "@lunardinos/browser";
+interface RecorderContextValue {
+    identify: (payload: IdentifyPayload) => void;
+    setPersistence: (mode: PersistenceMode) => void;
+}
+export declare function useLunarDinos(): RecorderContextValue;
+interface RecorderProviderProps {
+    apiKey: string;
+    endpoint?: string;
+    enabled?: boolean;
+    /** Initial persistence mode: 'cookie' (default) or 'cookieless'. Can be changed at runtime via setPersistence(). */
+    defaultPersistence?: PersistenceMode;
+    children: ReactNode;
+}
+export declare function LunarDinosProvider(props: RecorderProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/src/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAIL,KAAK,SAAS,EAKf,MAAM,OAAO,CAAA;AAEd,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAE3E,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC5C,cAAc,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;CAChD;AAID,wBAAgB,aAAa,IAAI,oBAAoB,CAIpD;AAED,UAAU,qBAAqB;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,oHAAoH;IACpH,kBAAkB,CAAC,EAAE,eAAe,CAAA;IACpC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAuJD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,qBAAqB,2CAM9D"}

package/dist/src/provider.js

@@ -0,0 +1,142 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createLunarDinosRecorder, } from "@lunardinos/browser";
+import { useMatches } from "@tanstack/react-router";
+import { Component, createContext, useContext, useEffect, useMemo, useRef, } from "react";
+const RecorderContext = createContext(null);
+export function useLunarDinos() {
+    const ctx = useContext(RecorderContext);
+    if (!ctx)
+        throw new Error("useLunarDinos must be used within LunarDinosProvider");
+    return ctx;
+}
+function buildRoutePattern(matches) {
+    const deepest = matches[matches.length - 1];
+    return deepest?.fullPath ?? deepest?.id ?? "/";
+}
+function extractParams(matches) {
+    const deepest = matches[matches.length - 1];
+    const raw = deepest?.params;
+    if (!raw || Object.keys(raw).length === 0)
+        return null;
+    return Object.fromEntries(Object.entries(raw)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => [k, String(v)]));
+}
+const noopContextValue = {
+    identify: () => { },
+    setPersistence: () => { },
+};
+/** Error boundary that swallows SDK errors and renders children unaffected. */
+class RecorderErrorBoundary extends Component {
+    state = { hasError: false };
+    static getDerivedStateFromError() {
+        return { hasError: true };
+    }
+    componentDidCatch(_error, _info) {
+        // Silently swallow — the SDK should never crash the host app
+    }
+    render() {
+        return this.props.children;
+    }
+}
+function RecorderInner({ apiKey, endpoint, enabled = true, defaultPersistence, children, }) {
+    const matches = useMatches();
+    const recorderRef = useRef(null);
+    const prevRouteRef = useRef(null);
+    const matchesRef = useRef(matches);
+    matchesRef.current = matches;
+    // Initialize recorder on mount — pass initial page metadata so the
+    // first rrweb snapshot already carries route info (avoids race where
+    // rrweb hasn't set recording=true yet when emitPageEvent is called).
+    useEffect(() => {
+        if (!enabled)
+            return;
+        try {
+            const initMatches = matchesRef.current;
+            const routePattern = buildRoutePattern(initMatches);
+            const params = extractParams(initMatches);
+            const recorder = createLunarDinosRecorder({ apiKey, endpoint, defaultPersistence });
+            recorderRef.current = recorder;
+            prevRouteRef.current = routePattern;
+            recorder.start({
+                pageMetadata: {
+                    href: window.location.href,
+                    title: document.title,
+                    routePattern,
+                    params,
+                },
+            });
+            const onBeforeUnload = () => {
+                try {
+                    recorder.flush({ beacon: true });
+                    recorder.stop();
+                }
+                catch {
+                    /* swallow */
+                }
+            };
+            window.addEventListener("beforeunload", onBeforeUnload);
+            return () => {
+                window.removeEventListener("beforeunload", onBeforeUnload);
+                try {
+                    recorder.flush({ beacon: true });
+                    recorder.stop();
+                }
+                catch {
+                    /* swallow */
+                }
+                recorderRef.current = null;
+            };
+        }
+        catch {
+            // SDK init failed — degrade silently
+            recorderRef.current = null;
+        }
+    }, [apiKey, endpoint, enabled, defaultPersistence]);
+    // Emit page event on subsequent navigations (initial page handled by start())
+    useEffect(() => {
+        try {
+            const recorder = recorderRef.current;
+            if (!enabled || !recorder || !recorder.isRecording())
+                return;
+            const routePattern = buildRoutePattern(matches);
+            if (routePattern === prevRouteRef.current)
+                return;
+            prevRouteRef.current = routePattern;
+            const params = extractParams(matches);
+            recorder.emitPageEvent({
+                href: window.location.href,
+                title: document.title,
+                routePattern,
+                params,
+            });
+        }
+        catch {
+            /* swallow */
+        }
+    }, [matches, enabled]);
+    const contextValue = useMemo(() => enabled
+        ? {
+            identify: (payload) => {
+                try {
+                    recorderRef.current?.identify(payload);
+                }
+                catch {
+                    /* swallow */
+                }
+            },
+            setPersistence: (mode) => {
+                try {
+                    recorderRef.current?.setPersistence(mode);
+                }
+                catch {
+                    /* swallow */
+                }
+            },
+        }
+        : noopContextValue, [enabled]);
+    return _jsx(RecorderContext.Provider, { value: contextValue, children: children });
+}
+export function LunarDinosProvider(props) {
+    return (_jsx(RecorderErrorBoundary, { children: _jsx(RecorderInner, { ...props }) }));
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@lunardinos/tanstack-router",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun run build.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lunardinos/browser": "^0.1.9"
+  },
+  "devDependencies": {
+    "@types/react": "^19"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": ">=1",
+    "react": ">=18"
+  }
+}