@byline/host-tanstack-start 4.15.0 → 4.16.0

package/src/server-fns/analytics/queries.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { createServerFn } from '@tanstack/react-start'
+
+import { assertAdminActor, requireAdminActor } from '@byline/admin'
+import { ANALYTICS_ABILITIES } from '@byline/admin/analytics'
+import type {
+  AnalyticsCountryTotal,
+  AnalyticsDateRange,
+  AnalyticsEventKind,
+  AnalyticsPathTotal,
+  AnalyticsRankedTotals,
+  AnalyticsReferrerTotal,
+  AnalyticsReportCoverage,
+  AnalyticsSummary,
+} from '@byline/analytics'
+import { getAdminRequestContext } from '@byline/client/server'
+
+export interface AnalyticsTopInput extends AnalyticsDateRange {
+  kind: AnalyticsEventKind
+  limit?: number
+}
+
+export interface AnalyticsRuntimeState {
+  enabled: boolean
+}
+
+export const getAnalyticsRuntime = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<AnalyticsRuntimeState> => {
+    const context = await getAdminRequestContext()
+    requireAdminActor(context, 'reading analytics runtime state')
+    const { isAnalyticsRegistered } = await import('@byline/analytics')
+    return { enabled: isAnalyticsRegistered() }
+  }
+)
+
+export const getAnalyticsSummary = createServerFn({ method: 'GET' })
+  .validator((input: AnalyticsDateRange) => input)
+  .handler(async ({ data }): Promise<AnalyticsSummary> => {
+    await assertAnalyticsRead()
+    const { getAnalytics } = await import('@byline/analytics')
+    return getAnalytics().getSummary(data)
+  })
+
+export const getAnalyticsReportCoverage = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<AnalyticsReportCoverage> => {
+    await assertAnalyticsRead()
+    const { getAnalytics } = await import('@byline/analytics')
+    return getAnalytics().getReportCoverage()
+  }
+)
+
+export const getAnalyticsTop = createServerFn({ method: 'GET' })
+  .validator((input: AnalyticsTopInput) => input)
+  .handler(async ({ data }): Promise<AnalyticsRankedTotals<AnalyticsPathTotal>> => {
+    await assertAnalyticsRead()
+    const { getAnalytics } = await import('@byline/analytics')
+    return getAnalytics().getTopPaths(data)
+  })
+
+export const getAnalyticsReferrers = createServerFn({ method: 'GET' })
+  .validator((input: AnalyticsDateRange & { limit?: number }) => input)
+  .handler(async ({ data }): Promise<AnalyticsRankedTotals<AnalyticsReferrerTotal>> => {
+    await assertAnalyticsRead()
+    const { getAnalytics } = await import('@byline/analytics')
+    return getAnalytics().getReferrers(data)
+  })
+
+export const getAnalyticsCountries = createServerFn({ method: 'GET' })
+  .validator((input: AnalyticsDateRange) => input)
+  .handler(async ({ data }): Promise<AnalyticsCountryTotal[]> => {
+    await assertAnalyticsRead()
+    const { getAnalytics } = await import('@byline/analytics')
+    return getAnalytics().getCountries(data)
+  })
+
+async function assertAnalyticsRead(): Promise<void> {
+  const context = await getAdminRequestContext()
+  assertAdminActor(context, ANALYTICS_ABILITIES.read)
+}

package/src/vite/analytics-dev.test.node.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 { IncomingMessage, ServerResponse } from 'node:http'
+
+import { ANALYTICS_AGENT_SOURCE } from '@byline/analytics-agent/source'
+import type { Plugin } from 'vite'
+import { describe, expect, it, vi } from 'vitest'
+
+import { bylineAnalyticsDev } from './analytics-dev.js'
+
+type Middleware = (
+  request: IncomingMessage,
+  response: ServerResponse,
+  next: (error?: unknown) => void
+) => void | Promise<void>
+
+describe('bylineAnalyticsDev', () => {
+  it('directly serves browser script requests before Vite can transform them', async () => {
+    const handler = captureMiddleware(bylineAnalyticsDev())
+    const request = requestStub('GET', '/b.js?version=current', {
+      accept: '*/*',
+      'sec-fetch-dest': 'script',
+    })
+    const { response, headers, end } = responseStub()
+    const next = vi.fn()
+
+    await handler(request, response, next)
+
+    expect(response.statusCode).toBe(200)
+    expect(headers).toEqual({
+      'cache-control': 'public, max-age=3600, must-revalidate',
+      'content-type': 'text/javascript; charset=utf-8',
+      'x-content-type-options': 'nosniff',
+    })
+    expect(end).toHaveBeenCalledWith(ANALYTICS_AGENT_SOURCE)
+    expect(next).not.toHaveBeenCalled()
+    expect(request.headers).toEqual({
+      accept: '*/*',
+      'sec-fetch-dest': 'script',
+    })
+  })
+
+  it('continues unrelated requests through the Vite middleware chain', async () => {
+    const handler = captureMiddleware(bylineAnalyticsDev())
+    const { response, end } = responseStub()
+    const next = vi.fn()
+
+    await handler(requestStub('GET', '/about'), response, next)
+    await handler(requestStub('POST', '/api/events'), response, next)
+
+    expect(next).toHaveBeenCalledTimes(2)
+    expect(end).not.toHaveBeenCalled()
+  })
+
+  it('supports a custom public agent path', async () => {
+    const handler = captureMiddleware(bylineAnalyticsDev({ agentPath: '/first-party.js' }))
+    const defaultResponse = responseStub()
+    const customResponse = responseStub()
+    const next = vi.fn()
+
+    await handler(requestStub('GET', '/b.js'), defaultResponse.response, next)
+    await handler(requestStub('GET', '/first-party.js'), customResponse.response, next)
+
+    expect(next).toHaveBeenCalledOnce()
+    expect(defaultResponse.end).not.toHaveBeenCalled()
+    expect(customResponse.end).toHaveBeenCalledWith(ANALYTICS_AGENT_SOURCE)
+  })
+})
+
+function captureMiddleware(plugin: Plugin): Middleware {
+  const handlers: Middleware[] = []
+  const configureServer = plugin.configureServer
+
+  expect(typeof configureServer).toBe('function')
+  if (typeof configureServer !== 'function') {
+    throw new Error('Expected a Vite configureServer hook')
+  }
+
+  configureServer.call(
+    {} as never,
+    {
+      middlewares: {
+        use(handler: Middleware) {
+          handlers.push(handler)
+        },
+      },
+    } as never
+  )
+
+  const handler = handlers[0]
+  expect(handler).toBeDefined()
+  if (handler == null) throw new Error('Expected a Vite middleware')
+  return handler
+}
+
+function requestStub(
+  method: string,
+  url: string,
+  headers: IncomingMessage['headers'] = {}
+): IncomingMessage {
+  return { method, url, headers } as IncomingMessage
+}
+
+function responseStub(): {
+  response: ServerResponse
+  headers: Record<string, string | number | readonly string[]>
+  end: ReturnType<typeof vi.fn>
+} {
+  const headers: Record<string, string | number | readonly string[]> = {}
+  const end = vi.fn()
+  const response = {
+    statusCode: 0,
+    setHeader(name: string, value: string | number | readonly string[]) {
+      headers[name] = value
+      return response
+    },
+    end,
+  } as unknown as ServerResponse
+  return { response, headers, end }
+}

package/src/vite/analytics-dev.ts

@@ -0,0 +1,56 @@
+/**
+ * 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'
+
+import { serveAnalyticsAgent } from '../integrations/serve-analytics-agent.js'
+
+/**
+ * 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 function bylineAnalyticsDev(
+  options: {
+    /** Public path that serves the standalone agent. */
+    agentPath?: string
+  } = {}
+): Plugin {
+  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 (request.method === 'GET' && 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()
+      })
+    },
+  }
+}

package/src/vite/index.ts

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