@byline/host-tanstack-start 4.15.0 → 4.17.0

package/src/server-fns/singletons/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 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
+ */
+
+export * from './cancel-scheduled-publish.js'
+export * from './change-status.js'
+export * from './confirm-scheduled-publish.js'
+export * from './copy-to-locale.js'
+export * from './find-by-version.js'
+export * from './get.js'
+export * from './get-scheduled-publish.js'
+export * from './history.js'
+export * from './restore-version.js'
+export * from './schedule-publish.js'
+export * from './unpublish.js'
+export * from './update.js'

package/src/server-fns/singletons/restore-version.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { getAdminBylineClient } from '@byline/client/server'
+
+import { serialise } from '../serialise.js'
+
+export const restoreSingletonVersion = createServerFn({ method: 'POST' })
+  .validator((input: { singleton: string; versionId: string }) => input)
+  .handler(async ({ data }) =>
+    serialise(await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId))
+  )

package/src/server-fns/singletons/schedule-publish.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 { getAdminBylineClient } from '@byline/client/server'
+
+import { serialise } from '../serialise.js'
+
+export const scheduleSingletonPublish = createServerFn({ method: 'POST' })
+  .validator((input: { singleton: string; publishAt: string; expectedVersionId: string }) => input)
+  .handler(async ({ data }) =>
+    serialise(
+      await getAdminBylineClient().singleton(data.singleton).schedulePublish({
+        publishAt: data.publishAt,
+        expectedVersionId: data.expectedVersionId,
+      })
+    )
+  )

package/src/server-fns/singletons/singletons.test.node.ts

@@ -0,0 +1,298 @@
+/**
+ * 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 { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  getAdminBylineClient: vi.fn(),
+  resolveActorLabels: vi.fn(),
+}))
+
+vi.mock('@tanstack/react-start', () => ({
+  createServerFn: () => {
+    let validate = (input: unknown) => input
+    const chain = {
+      validator(validator: (input: unknown) => unknown) {
+        validate = validator
+        return chain
+      },
+      handler(handler: (options: { data: any }) => Promise<unknown>) {
+        return async (options: { data: unknown }) => handler({ data: validate(options.data) })
+      },
+    }
+    return chain
+  },
+}))
+
+vi.mock('@byline/client/server', () => ({
+  getAdminBylineClient: mocks.getAdminBylineClient,
+}))
+
+vi.mock('../actors.js', () => ({
+  resolveActorLabels: mocks.resolveActorLabels,
+}))
+
+import { cancelSingletonScheduledPublish } from './cancel-scheduled-publish.js'
+import { changeSingletonStatus } from './change-status.js'
+import { confirmSingletonScheduledPublish } from './confirm-scheduled-publish.js'
+import { copySingletonToLocale } from './copy-to-locale.js'
+import { findSingletonByVersion } from './find-by-version.js'
+import { getSingleton } from './get.js'
+import { getSingletonScheduledPublish } from './get-scheduled-publish.js'
+import { getSingletonHistory } from './history.js'
+import { restoreSingletonVersion } from './restore-version.js'
+import { scheduleSingletonPublish } from './schedule-publish.js'
+import { unpublishSingleton } from './unpublish.js'
+import { updateSingleton } from './update.js'
+
+type ServerFunction = (options: { data: any }) => Promise<any>
+
+const invoke = (serverFunction: unknown, data: Record<string, any>) =>
+  (serverFunction as ServerFunction)({ data })
+
+const handle = {
+  get: vi.fn(),
+  update: vi.fn(),
+  changeStatus: vi.fn(),
+  unpublish: vi.fn(),
+  schedulePublish: vi.fn(),
+  confirmScheduledPublish: vi.fn(),
+  cancelScheduledPublish: vi.fn(),
+  getScheduledPublish: vi.fn(),
+  history: vi.fn(),
+  findByVersion: vi.fn(),
+  restoreVersion: vi.fn(),
+  copyToLocale: vi.fn(),
+}
+
+const client = { singleton: vi.fn(() => handle) }
+
+describe('singleton server functions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.getAdminBylineClient.mockReturnValue(client)
+    mocks.resolveActorLabels.mockResolvedValue({ actor: { label: 'Ada Editor' } })
+  })
+
+  it('delegates every operation to the singleton handle for the requested path', async () => {
+    const cases = [
+      {
+        serverFunction: getSingleton,
+        method: 'get',
+        input: { singleton: 'site-settings', locale: 'fr' },
+        args: [
+          {
+            locale: 'fr',
+            populate: undefined,
+            depth: undefined,
+            status: 'any',
+            onMissingLocale: 'empty',
+            lenient: true,
+          },
+        ],
+        result: { title: 'Site' },
+      },
+      {
+        serverFunction: updateSingleton,
+        method: 'update',
+        input: {
+          singleton: 'site-settings',
+          data: { title: 'Changed' },
+          locale: 'fr',
+          expectedVersionId: 'version-1',
+        },
+        args: [{ title: 'Changed' }, { locale: 'fr', expectedVersionId: 'version-1' }],
+        result: { versionId: 'version-2' },
+      },
+      {
+        serverFunction: changeSingletonStatus,
+        method: 'changeStatus',
+        input: { singleton: 'site-settings', status: 'published' },
+        args: ['published'],
+        result: { newStatus: 'published' },
+      },
+      {
+        serverFunction: unpublishSingleton,
+        method: 'unpublish',
+        input: { singleton: 'site-settings' },
+        args: [],
+        result: { archivedCount: 1 },
+      },
+      {
+        serverFunction: scheduleSingletonPublish,
+        method: 'schedulePublish',
+        input: {
+          singleton: 'site-settings',
+          publishAt: '2026-09-01T10:00:00Z',
+          expectedVersionId: 'version-2',
+        },
+        args: [
+          {
+            publishAt: '2026-09-01T10:00:00Z',
+            expectedVersionId: 'version-2',
+          },
+        ],
+        result: { state: 'armed' },
+      },
+      {
+        serverFunction: confirmSingletonScheduledPublish,
+        method: 'confirmScheduledPublish',
+        input: { singleton: 'site-settings', expectedVersionId: 'version-3' },
+        args: [{ expectedVersionId: 'version-3' }],
+        result: { state: 'armed' },
+      },
+      {
+        serverFunction: cancelSingletonScheduledPublish,
+        method: 'cancelScheduledPublish',
+        input: { singleton: 'site-settings' },
+        args: [],
+        result: { state: 'cancelled' },
+      },
+      {
+        serverFunction: getSingletonScheduledPublish,
+        method: 'getScheduledPublish',
+        input: { singleton: 'site-settings' },
+        args: [],
+        result: { state: 'armed' },
+      },
+      {
+        serverFunction: getSingletonHistory,
+        method: 'history',
+        input: {
+          singleton: 'site-settings',
+          params: { locale: 'all', page: 2, page_size: 10, order: 'created_at', desc: true },
+        },
+        args: [{ locale: 'all', page: 2, pageSize: 10, order: 'created_at', desc: true }],
+        result: {
+          docs: [{ createdBy: 'actor', versionId: 'version-1' }],
+          meta: { total: 1, page: 2, pageSize: 10, totalPages: 1 },
+        },
+        actors: true,
+      },
+      {
+        serverFunction: findSingletonByVersion,
+        method: 'findByVersion',
+        input: { singleton: 'site-settings', versionId: 'version-1', locale: 'fr' },
+        args: ['version-1', { locale: 'fr' }],
+        result: { title: 'Historical' },
+      },
+      {
+        serverFunction: restoreSingletonVersion,
+        method: 'restoreVersion',
+        input: { singleton: 'site-settings', versionId: 'version-1' },
+        args: ['version-1'],
+        result: { versionId: 'version-4' },
+      },
+      {
+        serverFunction: copySingletonToLocale,
+        method: 'copyToLocale',
+        input: {
+          singleton: 'site-settings',
+          sourceLocale: 'en',
+          targetLocale: 'fr',
+          overwrite: true,
+        },
+        args: [{ sourceLocale: 'en', targetLocale: 'fr', overwrite: true }],
+        result: { versionId: 'version-5' },
+      },
+    ] as const
+
+    for (const testCase of cases) {
+      const method = handle[testCase.method]
+      method.mockResolvedValueOnce(testCase.result)
+
+      const result = await invoke(testCase.serverFunction, testCase.input)
+
+      expect(client.singleton).toHaveBeenLastCalledWith('site-settings')
+      expect(method).toHaveBeenCalledWith(...testCase.args)
+      expect(result).toEqual(
+        testCase.actors
+          ? { ...testCase.result, actors: { actor: { label: 'Ada Editor' } } }
+          : testCase.result
+      )
+    }
+  })
+
+  it('forwards the optimistic version to update unchanged', async () => {
+    handle.update.mockResolvedValueOnce({ versionId: 'version-next' })
+
+    await invoke(updateSingleton, {
+      singleton: 'site-settings',
+      data: { title: 'Changed' },
+      expectedVersionId: 'version-current',
+    })
+
+    expect(handle.update).toHaveBeenCalledWith(
+      { title: 'Changed' },
+      { locale: undefined, expectedVersionId: 'version-current' }
+    )
+  })
+
+  it('preserves authentication failures from the handle', async () => {
+    const error = { code: 'ERR_UNAUTHENTICATED', message: 'sign in required' }
+    handle.get.mockRejectedValueOnce(error)
+
+    await expect(invoke(getSingleton, { singleton: 'site-settings' })).rejects.toBe(error)
+  })
+
+  it('preserves the requested empty history envelope from an unmaterialised slot', async () => {
+    handle.history.mockResolvedValueOnce({
+      docs: [],
+      meta: { total: 0, page: 4, pageSize: 30, totalPages: 0 },
+    })
+    mocks.resolveActorLabels.mockResolvedValueOnce({})
+
+    await expect(
+      invoke(getSingletonHistory, {
+        singleton: 'site-settings',
+        params: { page: 4, page_size: 30 },
+      })
+    ).resolves.toEqual({
+      docs: [],
+      meta: { total: 0, page: 4, pageSize: 30, totalPages: 0 },
+      actors: {},
+    })
+    expect(handle.history).toHaveBeenCalledWith({
+      locale: 'en',
+      page: 4,
+      pageSize: 30,
+      order: undefined,
+      desc: undefined,
+    })
+    expect(mocks.resolveActorLabels).toHaveBeenCalledWith([])
+  })
+
+  it('keeps missing-slot and stale-write failures distinguishable', async () => {
+    const missing = { code: 'ERR_NOT_FOUND', message: 'slot is empty' }
+    const stale = { code: 'ERR_CONFLICT', message: 'version changed' }
+    handle.changeStatus.mockRejectedValueOnce(missing)
+    handle.update.mockRejectedValueOnce(stale)
+
+    await expect(
+      invoke(changeSingletonStatus, { singleton: 'site-settings', status: 'published' })
+    ).rejects.toMatchObject({ code: 'ERR_NOT_FOUND' })
+    await expect(
+      invoke(updateSingleton, {
+        singleton: 'site-settings',
+        data: { title: 'Changed' },
+        expectedVersionId: 'stale',
+      })
+    ).rejects.toMatchObject({ code: 'ERR_CONFLICT' })
+  })
+
+  it('serialises schedule dates at the transport boundary', async () => {
+    handle.getScheduledPublish.mockResolvedValueOnce({
+      state: 'armed',
+      publishAt: new Date('2026-09-01T10:00:00Z'),
+    })
+
+    await expect(
+      invoke(getSingletonScheduledPublish, { singleton: 'site-settings' })
+    ).resolves.toMatchObject({ publishAt: '2026-09-01T10:00:00.000Z' })
+  })
+})

package/src/server-fns/singletons/unpublish.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { getAdminBylineClient } from '@byline/client/server'
+
+import { serialise } from '../serialise.js'
+
+export const unpublishSingleton = createServerFn({ method: 'POST' })
+  .validator((input: { singleton: string }) => input)
+  .handler(async ({ data }) =>
+    serialise(await getAdminBylineClient().singleton(data.singleton).unpublish())
+  )

package/src/server-fns/singletons/update.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { getAdminBylineClient } from '@byline/client/server'
+
+import { serialise } from '../serialise.js'
+
+export interface UpdateSingletonInput {
+  singleton: string
+  data: Record<string, any>
+  locale?: string
+  expectedVersionId?: string
+}
+
+export const updateSingleton = createServerFn({ method: 'POST' })
+  .validator((input: UpdateSingletonInput) => input)
+  .handler(async ({ data }) => {
+    const { singleton, data: fields, locale, expectedVersionId } = data
+    const result = await getAdminBylineClient().singleton(singleton).update(fields, {
+      locale,
+      expectedVersionId,
+    })
+    return serialise(result)
+  })

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'

package/src/vitest-jsdom.test.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 { act } from 'react'
+
+import { createRoot } from 'react-dom/client'
+import { expect, it } from 'vitest'
+
+it('collects and renders React component tests in jsdom mode', () => {
+  const reactGlobals = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+  reactGlobals.IS_REACT_ACT_ENVIRONMENT = true
+  const container = document.createElement('div')
+  document.body.append(container)
+  const root = createRoot(container)
+
+  act(() => root.render(<span data-testid="probe">jsdom ready</span>))
+  expect(container.querySelector('[data-testid="probe"]')?.textContent).toBe('jsdom ready')
+
+  act(() => root.unmount())
+  container.remove()
+  delete reactGlobals.IS_REACT_ACT_ENVIRONMENT
+})