@byline/host-tanstack-start 4.15.0 → 4.17.0

package/src/admin-shell/singletons/view.tsx

@@ -0,0 +1,351 @@
+'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 { useRouter } from '@tanstack/react-router'
+
+import { FormRenderer } from '@byline/admin/react'
+import type { SingletonAdminConfig, SingletonDefinition } from '@byline/core'
+import {
+  ErrorCodes,
+  getDefaultStatus,
+  getWorkflow,
+  getWorkflowStatuses,
+  validateStatusTransition,
+} from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Container, Section, useToastManager } from '@byline/ui/react'
+
+import { getAdminRoutePath } from '../../routes/admin-path.js'
+import {
+  cancelSingletonScheduledPublish,
+  changeSingletonStatus,
+  confirmSingletonScheduledPublish,
+  copySingletonToLocale,
+  scheduleSingletonPublish,
+  unpublishSingleton,
+  updateSingleton,
+} from '../../server-fns/singletons/index.js'
+import { useNavigate } from '../chrome/loose-router.js'
+import { useTanStackNavigationGuard } from '../collections/tanstack-navigation-guard.js'
+import { SingletonViewMenu } from './view-menu.js'
+import type { SerializedDocumentPublishSchedule } from '../../server-fns/collections/index.js'
+import type { ContentLocaleOption } from '../collections/view-menu.js'
+
+type SingletonDocument = Record<string, any> & {
+  id: string
+  status: string
+  fields: Record<string, any>
+}
+
+function errorCode(error: unknown): string | null {
+  return typeof (error as { code?: unknown })?.code === 'string'
+    ? (error as { code: string }).code
+    : null
+}
+
+export function SingletonView({
+  singletonDefinition,
+  adminConfig,
+  document,
+  initialData,
+  locale,
+  contentLocales,
+  defaultContentLocale,
+}: {
+  singletonDefinition: SingletonDefinition
+  adminConfig?: SingletonAdminConfig
+  document: SingletonDocument | null
+  /** Schema defaults resolved by the server-side route loader for an empty slot. */
+  initialData?: Record<string, any>
+  locale?: string
+  contentLocales: ReadonlyArray<ContentLocaleOption>
+  defaultContentLocale: string
+}) {
+  const router = useRouter()
+  const navigate = useNavigate()
+  const toastManager = useToastManager()
+  const { t } = useTranslation('byline-admin')
+  const { path, label, fields } = singletonDefinition
+
+  const workflowStatuses = getWorkflowStatuses(singletonDefinition)
+  const currentStatus = document?.status ?? getDefaultStatus(singletonDefinition)
+  const currentIndex = workflowStatuses.findIndex((status) => status.name === currentStatus)
+  const nextStatus =
+    currentIndex !== -1 && currentIndex < workflowStatuses.length - 1
+      ? workflowStatuses[currentIndex + 1]
+      : undefined
+  const publishedVersion = document?._publishedVersion ?? null
+  const restoreWarnings = document?._restoreWarnings as string[] | undefined
+  const scheduledPublicationEnabled = document?._scheduledPublicationEnabled === true
+  const canSchedulePublication = document?._canSchedulePublication === true
+  const scheduledPublication = (document?._scheduledPublish ??
+    null) as SerializedDocumentPublishSchedule | null
+  const publishTransitionValid =
+    document != null &&
+    currentStatus !== 'published' &&
+    workflowStatuses.length > 1 &&
+    validateStatusTransition(getWorkflow(singletonDefinition), currentStatus, 'published').valid
+  const canArmSchedule =
+    scheduledPublicationEnabled && canSchedulePublication && publishTransitionValid
+
+  const reload = async () => {
+    // Invalidation is load-bearing after the first save: the refreshed loader
+    // supplies the mapped document id/version, flips FormRenderer to edit mode,
+    // and unlocks fields that require a saved document.
+    await router.invalidate()
+  }
+
+  const toast = (title: string, description: string, intent: 'success' | 'warning' | 'danger') => {
+    toastManager.add({
+      title,
+      description,
+      data: { intent, iconType: intent, icon: true, close: true },
+    })
+  }
+
+  const notifyScheduleSuspended = () => {
+    if (scheduledPublication?.state !== 'armed') return
+    toast(
+      t('scheduledPublication.toast.suspendedTitle'),
+      t('scheduledPublication.toast.suspendedDescription'),
+      'warning'
+    )
+  }
+
+  const handleSubmit = async ({ data }: { data: Record<string, any> }) => {
+    try {
+      await updateSingleton({
+        data: {
+          singleton: path,
+          data,
+          locale: locale ?? defaultContentLocale,
+          expectedVersionId: document?.versionId,
+        },
+      })
+      if (document != null) notifyScheduleSuspended()
+      toast(
+        t('singletons.edit.updateTitle', { label }),
+        t('singletons.edit.updatedDescription', { label: label.toLowerCase() }),
+        'success'
+      )
+      await reload()
+    } catch (err) {
+      const code = errorCode(err)
+      const description =
+        code === ErrorCodes.CONFLICT
+          ? t('singletons.edit.conflictDescription')
+          : code === ErrorCodes.NOT_FOUND
+            ? t('singletons.edit.notConfiguredDescription')
+            : t('singletons.edit.updateFailedDescription', { label: label.toLowerCase() })
+      toast(t('singletons.edit.updateTitle', { label }), description, 'danger')
+
+      // FormRenderer commits its clean baseline only when this promise
+      // resolves. Rethrow so a failed singleton save leaves the editor dirty
+      // and its navigation guard active.
+      throw err
+    }
+  }
+
+  const handleStatusChange = async (status: string) => {
+    try {
+      await changeSingletonStatus({ data: { singleton: path, status } })
+      toast(
+        t('collections.edit.statusUpdateTitle', { label }),
+        t('collections.edit.statusChangedDescription', { status }),
+        'success'
+      )
+      await reload()
+    } catch (err) {
+      toast(
+        t('collections.edit.statusUpdateTitle', { label }),
+        t('collections.edit.statusChangeFailedDescription', { message: (err as Error).message }),
+        'danger'
+      )
+      throw err
+    }
+  }
+
+  const handleUnpublish = async () => {
+    try {
+      await unpublishSingleton({ data: { singleton: path } })
+      toast(
+        t('collections.edit.unpublishTitle', { label }),
+        t('collections.edit.unpublishedDescription'),
+        'success'
+      )
+      await reload()
+    } catch (err) {
+      toast(
+        t('collections.edit.unpublishTitle', { label }),
+        t('collections.edit.unpublishFailedDescription', { message: (err as Error).message }),
+        'danger'
+      )
+      throw err
+    }
+  }
+
+  const handleCopyToLocale = async ({
+    targetLocale,
+    overwrite,
+  }: {
+    targetLocale: string
+    overwrite: boolean
+  }) => {
+    try {
+      await copySingletonToLocale({
+        data: {
+          singleton: path,
+          sourceLocale: locale ?? defaultContentLocale,
+          targetLocale,
+          overwrite,
+        },
+      })
+      const sourceLocale = locale ?? defaultContentLocale
+      const sourceLabel =
+        contentLocales.find((entry) => entry.code === sourceLocale)?.label ?? sourceLocale
+      const targetLabel =
+        contentLocales.find((entry) => entry.code === targetLocale)?.label ?? targetLocale
+      toast(
+        t('collections.edit.copyToLocaleTitle', { label }),
+        t('collections.edit.copiedSuccessMessage', {
+          source: sourceLabel,
+          target: targetLabel,
+        }),
+        'success'
+      )
+      notifyScheduleSuspended()
+      navigate({
+        to: getAdminRoutePath('singletons', '$singleton'),
+        params: { singleton: path },
+        search: { locale: targetLocale },
+      })
+    } catch (err) {
+      toast(
+        t('collections.edit.copyToLocaleTitle', { label }),
+        t('collections.edit.copyFailedDescription', { message: (err as Error).message }),
+        'danger'
+      )
+      throw err
+    }
+  }
+
+  const handleSchedulePublication = async ({ publishAt }: { publishAt: string }) => {
+    try {
+      await scheduleSingletonPublish({
+        data: { singleton: path, publishAt, expectedVersionId: String(document?.versionId) },
+      })
+      toast(
+        t('scheduledPublication.toast.scheduledTitle'),
+        t('scheduledPublication.toast.scheduledDescription'),
+        'success'
+      )
+      await reload()
+    } catch (err) {
+      toast(t('scheduledPublication.toast.failedTitle'), (err as Error).message, 'danger')
+      throw err
+    }
+  }
+
+  const handleConfirmScheduledPublication = async () => {
+    try {
+      await confirmSingletonScheduledPublish({
+        data: { singleton: path, expectedVersionId: String(document?.versionId) },
+      })
+      toast(
+        t('scheduledPublication.toast.confirmedTitle'),
+        t('scheduledPublication.toast.confirmedDescription'),
+        'success'
+      )
+      await reload()
+    } catch (err) {
+      toast(t('scheduledPublication.toast.failedTitle'), (err as Error).message, 'danger')
+      throw err
+    }
+  }
+
+  const handleCancelScheduledPublication = async () => {
+    try {
+      await cancelSingletonScheduledPublish({ data: { singleton: path } })
+      toast(
+        t('scheduledPublication.toast.cancelledTitle'),
+        t('scheduledPublication.toast.cancelledDescription'),
+        'success'
+      )
+      await reload()
+    } catch (err) {
+      toast(t('scheduledPublication.toast.failedTitle'), (err as Error).message, 'danger')
+      throw err
+    }
+  }
+
+  return (
+    <Section>
+      <Container>
+        <FormRenderer
+          mode={document == null ? 'create' : 'edit'}
+          fields={fields}
+          onSubmit={handleSubmit}
+          initialData={document ?? (initialData ? { fields: initialData } : undefined)}
+          adminConfig={adminConfig}
+          heading={label}
+          showPath={false}
+          initialLocale={locale}
+          defaultLocale={defaultContentLocale}
+          onLocaleChange={
+            document == null
+              ? undefined
+              : (nextLocale) =>
+                  navigate({
+                    to: getAdminRoutePath('singletons', '$singleton'),
+                    params: { singleton: path },
+                    search: { locale: nextLocale },
+                  })
+          }
+          useNavigationGuard={useTanStackNavigationGuard}
+          headerSlot={
+            document == null ? undefined : (
+              <SingletonViewMenu
+                singleton={path}
+                activeView="edit"
+                locale={locale}
+                contentLocales={contentLocales}
+                defaultContentLocale={defaultContentLocale}
+                adminConfig={adminConfig}
+                doc={document}
+              />
+            )
+          }
+          onStatusChange={document == null ? undefined : handleStatusChange}
+          onUnpublish={document != null && publishedVersion ? handleUnpublish : undefined}
+          scheduledPublication={document == null ? null : scheduledPublication}
+          onSchedulePublication={canArmSchedule ? handleSchedulePublication : undefined}
+          onConfirmScheduledPublication={
+            canArmSchedule && scheduledPublication?.state === 'needs_reconfirm'
+              ? handleConfirmScheduledPublication
+              : undefined
+          }
+          onCancelScheduledPublication={
+            document != null && scheduledPublication != null
+              ? handleCancelScheduledPublication
+              : undefined
+          }
+          onCopyToLocale={document == null ? undefined : handleCopyToLocale}
+          contentLocales={document == null ? undefined : contentLocales}
+          publishedVersion={document == null ? null : publishedVersion}
+          restoreWarnings={restoreWarnings}
+          nextStatus={document == null ? undefined : nextStatus}
+          workflowStatuses={document == null ? undefined : workflowStatuses}
+          onCancel={() => navigate({ to: getAdminRoutePath() })}
+          collectionPath={path}
+        />
+      </Container>
+    </Section>
+  )
+}

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'
+    )
+  })
+})