@byline/host-tanstack-start 4.15.0 → 4.16.0

package/dist/server-fns/analytics/queries.d.ts

@@ -0,0 +1,25 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { AnalyticsCountryTotal, AnalyticsDateRange, AnalyticsEventKind, AnalyticsPathTotal, AnalyticsRankedTotals, AnalyticsReferrerTotal, AnalyticsReportCoverage, AnalyticsSummary } from '@byline/analytics';
+export interface AnalyticsTopInput extends AnalyticsDateRange {
+    kind: AnalyticsEventKind;
+    limit?: number;
+}
+export interface AnalyticsRuntimeState {
+    enabled: boolean;
+}
+export declare const getAnalyticsRuntime: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, Promise<AnalyticsRuntimeState>>;
+export declare const getAnalyticsSummary: import("@tanstack/react-start").RequiredFetcher<undefined, (input: AnalyticsDateRange) => AnalyticsDateRange, Promise<AnalyticsSummary>>;
+export declare const getAnalyticsReportCoverage: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, Promise<AnalyticsReportCoverage>>;
+export declare const getAnalyticsTop: import("@tanstack/react-start").RequiredFetcher<undefined, (input: AnalyticsTopInput) => AnalyticsTopInput, Promise<AnalyticsRankedTotals<AnalyticsPathTotal>>>;
+export declare const getAnalyticsReferrers: import("@tanstack/react-start").RequiredFetcher<undefined, (input: AnalyticsDateRange & {
+    limit?: number;
+}) => AnalyticsDateRange & {
+    limit?: number;
+}, Promise<AnalyticsRankedTotals<AnalyticsReferrerTotal>>>;
+export declare const getAnalyticsCountries: import("@tanstack/react-start").RequiredFetcher<undefined, (input: AnalyticsDateRange) => AnalyticsDateRange, Promise<AnalyticsCountryTotal[]>>;

package/dist/server-fns/analytics/queries.js

@@ -0,0 +1,54 @@
+import { createServerFn } from "@tanstack/react-start";
+import { assertAdminActor, requireAdminActor } from "@byline/admin";
+import { ANALYTICS_ABILITIES } from "@byline/admin/analytics";
+import { getAdminRequestContext } from "@byline/client/server";
+const getAnalyticsRuntime = createServerFn({
+    method: 'GET'
+}).handler(async ()=>{
+    const context = await getAdminRequestContext();
+    requireAdminActor(context, 'reading analytics runtime state');
+    const { isAnalyticsRegistered } = await import("@byline/analytics");
+    return {
+        enabled: isAnalyticsRegistered()
+    };
+});
+const getAnalyticsSummary = createServerFn({
+    method: 'GET'
+}).validator((input)=>input).handler(async ({ data })=>{
+    await assertAnalyticsRead();
+    const { getAnalytics } = await import("@byline/analytics");
+    return getAnalytics().getSummary(data);
+});
+const getAnalyticsReportCoverage = createServerFn({
+    method: 'GET'
+}).handler(async ()=>{
+    await assertAnalyticsRead();
+    const { getAnalytics } = await import("@byline/analytics");
+    return getAnalytics().getReportCoverage();
+});
+const getAnalyticsTop = createServerFn({
+    method: 'GET'
+}).validator((input)=>input).handler(async ({ data })=>{
+    await assertAnalyticsRead();
+    const { getAnalytics } = await import("@byline/analytics");
+    return getAnalytics().getTopPaths(data);
+});
+const getAnalyticsReferrers = createServerFn({
+    method: 'GET'
+}).validator((input)=>input).handler(async ({ data })=>{
+    await assertAnalyticsRead();
+    const { getAnalytics } = await import("@byline/analytics");
+    return getAnalytics().getReferrers(data);
+});
+const getAnalyticsCountries = createServerFn({
+    method: 'GET'
+}).validator((input)=>input).handler(async ({ data })=>{
+    await assertAnalyticsRead();
+    const { getAnalytics } = await import("@byline/analytics");
+    return getAnalytics().getCountries(data);
+});
+async function assertAnalyticsRead() {
+    const context = await getAdminRequestContext();
+    assertAdminActor(context, ANALYTICS_ABILITIES.read);
+}
+export { getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop };

package/dist/vite/analytics-dev.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { Plugin } from 'vite';
+/**
+ * Complete the first-party analytics transport during Vite development.
+ *
+ * Browser script requests carry `Sec-Fetch-Dest: script`, which Vite routes
+ * into its module pipeline before TanStack Start can serve the agent route.
+ * This plugin serves the agent directly. The application event route remains
+ * responsible for its development identity because POST server routes can
+ * bypass Vite's ordinary middleware chain. Production continues to use the
+ * application-owned agent route.
+ */
+export declare function bylineAnalyticsDev(options?: {
+    /** Public path that serves the standalone agent. */
+    agentPath?: string;
+}): Plugin;

package/dist/vite/analytics-dev.js

@@ -0,0 +1,28 @@
+import { serveAnalyticsAgent } from "../integrations/serve-analytics-agent.js";
+function bylineAnalyticsDev(options = {}) {
+    const agentPath = options.agentPath ?? '/b.js';
+    return {
+        name: 'byline:analytics-dev',
+        apply: 'serve',
+        configureServer (server) {
+            server.middlewares.use(async (request, response, next)=>{
+                const pathname = request.url?.split('?', 1)[0];
+                if ('GET' === request.method && pathname === agentPath) {
+                    try {
+                        const agentResponse = serveAnalyticsAgent();
+                        response.statusCode = agentResponse.status;
+                        agentResponse.headers.forEach((value, name)=>{
+                            response.setHeader(name, value);
+                        });
+                        response.end(await agentResponse.text());
+                    } catch (error) {
+                        next(error);
+                    }
+                    return;
+                }
+                next();
+            });
+        }
+    };
+}
+export { bylineAnalyticsDev };

package/dist/vite/index.d.ts

@@ -5,4 +5,5 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+export { bylineAnalyticsDev } from './analytics-dev.js';
 export { bylineClientHookBoundary } from './client-hook-boundary.js';

package/dist/vite/index.js

@@ -1 +1,2 @@
+export { bylineAnalyticsDev } from "./analytics-dev.js";
 export { bylineClientHookBoundary } from "./client-hook-boundary.js";

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -45,6 +45,10 @@
       "types": "./dist/server-fns/admin-account/index.d.ts",
       "import": "./dist/server-fns/admin-account/index.js"
     },
+    "./server-fns/analytics": {
+      "types": "./dist/server-fns/analytics/index.d.ts",
+      "import": "./dist/server-fns/analytics/index.js"
+    },
     "./server-fns/admin-activity": {
       "types": "./dist/server-fns/admin-activity/index.d.ts",
       "import": "./dist/server-fns/admin-activity/index.js"
@@ -117,13 +121,15 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.4.3",
-    "@byline/admin": "4.15.0",
-    "@byline/auth": "4.15.0",
-    "@byline/ai": "4.15.0",
-    "@byline/ui": "4.15.0",
-    "@byline/core": "4.15.0",
-    "@byline/client": "4.15.0",
-    "@byline/i18n": "4.15.0"
+    "@byline/admin": "4.16.0",
+    "@byline/analytics-agent": "4.16.0",
+    "@byline/ai": "4.16.0",
+    "@byline/analytics": "4.16.0",
+    "@byline/client": "4.16.0",
+    "@byline/core": "4.16.0",
+    "@byline/auth": "4.16.0",
+    "@byline/i18n": "4.16.0",
+    "@byline/ui": "4.16.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

package/src/admin-shell/chrome/admin-menu-drawer.tsx

@@ -13,10 +13,12 @@ import { ADMIN_ACTIVITY_ABILITIES } from '@byline/admin/admin-activity'
 import { ADMIN_PERMISSIONS_ABILITIES } from '@byline/admin/admin-permissions'
 import { ADMIN_ROLES_ABILITIES } from '@byline/admin/admin-roles'
 import { ADMIN_USERS_ABILITIES } from '@byline/admin/admin-users'
+import { ANALYTICS_ABILITIES } from '@byline/admin/analytics'
 import { collectionAbilityKey, getAdminConfig } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import {
   ActivityIcon,
+  AnalyticsIcon,
   CalendarIcon,
   HomeIcon,
   RolesIcon,
@@ -78,8 +80,10 @@ function MenuItem({ to, label, icon, pathname, compact }: MenuItemProps) {
 }
 
 export function AdminMenuDrawer({
+  analyticsEnabled = false,
   scheduledPublicationEnabled = false,
 }: {
+  analyticsEnabled?: boolean
   scheduledPublicationEnabled?: boolean
 }): React.JSX.Element | null {
   const pathname = useRouterState({ select: (s) => s.location.pathname })
@@ -96,6 +100,7 @@ export function AdminMenuDrawer({
   const canReadRoles = has(ADMIN_ROLES_ABILITIES.read)
   const canReadPermissions = has(ADMIN_PERMISSIONS_ABILITIES.read)
   const canReadActivity = has(ADMIN_ACTIVITY_ABILITIES.read)
+  const canReadAnalytics = analyticsEnabled && has(ANALYTICS_ABILITIES.read)
   const canSeeScheduledPublications =
     scheduledPublicationEnabled &&
     getAdminConfig().collections.some(
@@ -152,6 +157,15 @@ export function AdminMenuDrawer({
               compact={compact}
             />
           )}
+          {canReadAnalytics && (
+            <MenuItem
+              to={getAdminRoutePath('analytics')}
+              label={t('chrome.menu.analytics')}
+              icon={<AnalyticsIcon width="20px" height="20px" />}
+              pathname={pathname}
+              compact={compact}
+            />
+          )}
           {showAdminSection && (
             <>
               <li className="menu-separator" />

package/src/integrations/analytics-agent.tsx

@@ -0,0 +1,91 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type React from 'react'
+import { useEffect, useRef } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+
+import { ANALYTICS_NAVIGATION_EVENT, ANALYTICS_STOP_EVENT } from '@byline/analytics-agent'
+
+let pendingStopTimer: number | undefined
+
+export interface AnalyticsAgentProps {
+  /** Application-owned same-origin route that receives browser events. */
+  endpoint: string
+  src?: string
+  cdnHosts?: readonly string[]
+  downloadExtensions?: readonly string[]
+  ignoredPathPrefixes?: readonly string[]
+  countSearchChanges?: boolean
+  countHashChanges?: boolean
+}
+
+/** Render the standalone script and bridge only committed router locations into it. */
+export function AnalyticsAgent({
+  endpoint,
+  src = '/b.js',
+  cdnHosts,
+  downloadExtensions,
+  ignoredPathPrefixes,
+  countSearchChanges = false,
+  countHashChanges = false,
+}: AnalyticsAgentProps): React.JSX.Element {
+  return (
+    <>
+      <script
+        defer
+        src={src}
+        data-endpoint={endpoint}
+        data-cdn-hosts={boundedAttribute(cdnHosts)}
+        data-download-extensions={boundedAttribute(downloadExtensions)}
+        data-ignore-prefixes={boundedAttribute(ignoredPathPrefixes)}
+        data-count-search={countSearchChanges ? 'true' : undefined}
+        data-count-hash={countHashChanges ? 'true' : undefined}
+      />
+      <AnalyticsNavigationBridge />
+    </>
+  )
+}
+
+function AnalyticsNavigationBridge(): null {
+  const href = useRouterState({ select: (state) => state.location.href })
+  const previousHref = useRef<string | undefined>(undefined)
+
+  useEffect(() => {
+    const previous = previousHref.current
+    previousHref.current = href
+    if (previous == null || previous === href) return
+    document.dispatchEvent(new CustomEvent(ANALYTICS_NAVIGATION_EVENT, { detail: href }))
+  }, [href])
+
+  useEffect(() => {
+    if (pendingStopTimer !== undefined) {
+      window.clearTimeout(pendingStopTimer)
+      pendingStopTimer = undefined
+    }
+
+    return () => {
+      // React Strict Mode immediately re-runs this effect after its simulated
+      // cleanup. Deferring the stop lets that setup cancel it, while a real
+      // consent-driven unmount leaves the timer in place.
+      pendingStopTimer = window.setTimeout(() => {
+        pendingStopTimer = undefined
+        document.dispatchEvent(new Event(ANALYTICS_STOP_EVENT))
+      }, 0)
+    }
+  }, [])
+
+  return null
+}
+
+function boundedAttribute(values: readonly string[] | undefined): string | undefined {
+  if (values == null || values.length === 0) return undefined
+  return values.slice(0, 64).join(',').slice(0, 2_048)
+}

package/src/integrations/analytics-events.test.node.ts

@@ -0,0 +1,245 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createAnalyticsEventHandler,
+  localAnalyticsRequestContext,
+  trustedAnalyticsHeaders,
+} from './analytics-events.js'
+
+describe('createAnalyticsEventHandler', () => {
+  it('passes only explicit trusted request facts and emits no CORS response header', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 202, accepted: true })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+        countryHeader: 'x-byline-client-country',
+      }),
+      analytics: () => ({ ingest }),
+    })
+    const body = JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' })
+    const response = await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body,
+        headers: {
+          origin: 'https://www.example.com',
+          'user-agent': 'Mozilla/5.0',
+          'x-byline-client-country': 'TH',
+          'x-byline-client-ip': '203.0.113.10',
+          'x-forwarded-for': '198.51.100.99',
+        },
+      })
+    )
+
+    expect(response.status).toBe(202)
+    expect(response.headers.has('access-control-allow-origin')).toBe(false)
+    expect(ingest).toHaveBeenCalledOnce()
+    expect(ingest.mock.calls[0]?.[0]).toMatchObject({
+      clientIp: '203.0.113.10',
+      country: 'TH',
+      origin: 'https://www.example.com',
+    })
+    expect(ingest.mock.calls[0]?.[0]).not.toHaveProperty('xForwardedFor')
+  })
+
+  it('stops reading an oversized stream and reports the contract body-size rejection', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 400, accepted: false, reason: 'body-size' })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+      }),
+      analytics: () => ({ ingest }),
+    })
+
+    const response = await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body: 'x'.repeat(1_025),
+        headers: { 'x-byline-client-ip': '203.0.113.10' },
+      })
+    )
+
+    expect(response.status).toBe(400)
+    const received = ingest.mock.calls.at(0)?.at(0)
+    expect(received).toBeDefined()
+    expect((received?.body as Uint8Array | undefined)?.byteLength).toBe(1_025)
+  })
+
+  it('uses an explicit development identity only when the trusted header is absent', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 202, accepted: true })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+        fallback: { clientIp: 'vite-development' },
+      }),
+      analytics: () => ({ ingest }),
+    })
+    const body = JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' })
+
+    await handler(
+      new Request('http://localhost:5173/api/events', {
+        method: 'POST',
+        body,
+      })
+    )
+    await handler(
+      new Request('http://localhost:5173/api/events', {
+        method: 'POST',
+        body,
+        headers: { 'x-byline-client-ip': '203.0.113.10' },
+      })
+    )
+
+    expect(ingest.mock.calls[0]?.[0].clientIp).toBe('vite-development')
+    expect(ingest.mock.calls[1]?.[0].clientIp).toBe('203.0.113.10')
+  })
+
+  it.each(['127.0.0.1', '::1', '::ffff:127.0.0.1'])(
+    'accepts direct loopback identity %s for a localhost production preview',
+    async (clientIp) => {
+      const resolver = localAnalyticsRequestContext({ resolveClientIp: () => clientIp })
+
+      await expect(resolver(new Request('http://localhost:5173/api/events'))).resolves.toEqual({
+        clientIp,
+      })
+    }
+  )
+
+  it('requires both a loopback URL and a loopback direct peer', async () => {
+    const loopbackPeer = localAnalyticsRequestContext({ resolveClientIp: () => '127.0.0.1' })
+    const publicPeer = localAnalyticsRequestContext({ resolveClientIp: () => '203.0.113.10' })
+
+    await expect(loopbackPeer(new Request('https://www.example.com/api/events'))).resolves.toEqual(
+      {}
+    )
+    await expect(publicPeer(new Request('http://localhost:5173/api/events'))).resolves.toEqual({})
+  })
+
+  it('prefers the trusted proxy header over a local fallback resolver', async () => {
+    const resolver = trustedAnalyticsHeaders({
+      clientIpHeader: 'x-byline-client-ip',
+      fallback: localAnalyticsRequestContext({ resolveClientIp: () => '127.0.0.1' }),
+    })
+
+    await expect(
+      resolver(
+        new Request('http://localhost:5173/api/events', {
+          headers: { 'x-byline-client-ip': '203.0.113.10' },
+        })
+      )
+    ).resolves.toEqual({ clientIp: '203.0.113.10', country: undefined })
+  })
+
+  it('rejects an empty development identity', () => {
+    expect(() =>
+      trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+        fallback: { clientIp: ' ' },
+      })
+    ).toThrow('fallback.clientIp must contain 1 to 255 characters')
+  })
+
+  it('rejects an invalid configured trust header before serving requests', () => {
+    expect(() =>
+      trustedAnalyticsHeaders({
+        clientIpHeader: 'not a header:',
+      })
+    ).toThrow('valid HTTP header name')
+  })
+
+  it('accepts deployment facts from a host resolver without assuming a proxy', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 202, accepted: true })
+    const resolveRequestContext = vi.fn().mockReturnValue({
+      clientIp: 'direct-platform-client',
+      country: 'NZ',
+    })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext,
+      analytics: () => ({ ingest }),
+    })
+    const request = new Request('https://www.example.com/telemetry/events', {
+      method: 'POST',
+      body: JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' }),
+    })
+
+    expect((await handler(request)).status).toBe(202)
+    expect(resolveRequestContext).toHaveBeenCalledWith(request)
+    expect(ingest.mock.calls[0]?.[0]).toMatchObject({
+      clientIp: 'direct-platform-client',
+      country: 'NZ',
+    })
+  })
+
+  it('contains persistence failures as an empty 503 and logs no request facts', async () => {
+    const visitorHash = 'a'.repeat(64)
+    const error = Object.assign(new Error('new row violates analytics constraint'), {
+      code: '23514',
+      detail: `Failing row contains visitor ${visitorHash}`,
+    })
+    const ingest = vi.fn().mockRejectedValue(error)
+    const logError = vi.fn()
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+      }),
+      analytics: () => ({ ingest }),
+      logger: () => ({ error: logError }),
+    })
+
+    const response = await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body: JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' }),
+        headers: {
+          origin: 'https://www.example.com',
+          'user-agent': 'Mozilla/5.0',
+          'x-byline-client-ip': '203.0.113.10',
+        },
+      })
+    )
+
+    expect(response.status).toBe(503)
+    expect(await response.text()).toBe('')
+    expect(logError).toHaveBeenCalledWith(
+      { errorCode: '23514' },
+      '[analytics] event persistence failed'
+    )
+    const logged = JSON.stringify(logError.mock.calls)
+    expect(logged).not.toContain('203.0.113.10')
+    expect(logged).not.toContain(visitorHash)
+    expect(logged).not.toContain(error.message)
+    expect(logged).not.toContain(error.detail)
+  })
+
+  it('does not trust arbitrary persistence error codes', async () => {
+    const ingest = vi.fn().mockRejectedValue({ code: 'unsafe value: 203.0.113.10' })
+    const logError = vi.fn()
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+      }),
+      analytics: () => ({ ingest }),
+      logger: () => ({ error: logError }),
+    })
+
+    await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body: JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' }),
+      })
+    )
+
+    expect(logError).toHaveBeenCalledWith(
+      { errorCode: 'UNKNOWN' },
+      '[analytics] event persistence failed'
+    )
+  })
+})