@byline/host-tanstack-start 4.14.1 → 4.15.0

package/src/routes/create-admin-layout-route.tsx

@@ -42,6 +42,7 @@ import { bylineAdminServices } from '../integrations/byline-admin-services.js'
 import { BylineAiAdminProvider } from '../integrations/byline-ai.js'
 import { bylineFieldServices } from '../integrations/byline-field-services.js'
 import { getCurrentAdminUser } from '../server-fns/auth/index.js'
+import { getScheduledPublicationRuntime } from '../server-fns/collections/index.js'
 import { getActiveLocaleFn, setAdminLocaleFn } from '../server-fns/i18n/index.js'
 import { getSignInRoutePath } from './sign-in-path.js'
 
@@ -58,7 +59,8 @@ export function createAdminLayoutRoute(path: string) {
         // `@tanstack/react-start/server` out of the client bundle — the
         // same pattern `getCurrentAdminUser` uses for `getAdminRequestContext`.
         const activeLocale = await getActiveLocaleFn()
-        return { user, activeLocale }
+        const scheduledPublicationRuntime = await getScheduledPublicationRuntime()
+        return { user, activeLocale, scheduledPublicationRuntime }
       } catch {
         // `getCurrentAdminUser` (via `getAdminRequestContext`) throws
         // `ERR_UNAUTHENTICATED` or a related auth error when no valid
@@ -71,9 +73,10 @@ export function createAdminLayoutRoute(path: string) {
       }
     },
     component: function AdminLayoutComponent() {
-      const { user, activeLocale } = Route.useRouteContext() as {
+      const { user, activeLocale, scheduledPublicationRuntime } = Route.useRouteContext() as {
         user: Awaited<ReturnType<typeof getCurrentAdminUser>>
         activeLocale: LocaleCode
+        scheduledPublicationRuntime: Awaited<ReturnType<typeof getScheduledPublicationRuntime>>
       }
       const { i18n } = getAdminConfig()
       const localeDefinitions = buildLocaleDefinitions(
@@ -109,7 +112,9 @@ export function createAdminLayoutRoute(path: string) {
                   <RouteProgressBar />
                   <AdminAppBar user={user} />
                   <main className={cx('byline-admin-layout-main', layoutStyles.main)}>
-                    <AdminMenuDrawer />
+                    <AdminMenuDrawer
+                      scheduledPublicationEnabled={scheduledPublicationRuntime.enabled}
+                    />
                     <Content>
                       <Outlet />
                     </Content>

package/src/routes/create-admin-scheduled-publications-route.tsx

@@ -0,0 +1,83 @@
+/**
+ * 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 { createFileRoute, notFound } from '@tanstack/react-router'
+
+import { useTranslation } from '@byline/i18n/react'
+import { z } from 'zod'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { ScheduledPublicationsView } from '../admin-shell/scheduled-publications/list.js'
+import {
+  getScheduledPublicationRuntime,
+  listScheduledPublications,
+} from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
+import type { ScheduledPublicationListResponse } from '../server-fns/collections/index.js'
+
+// Every member is an optional filter, so an unusable value should narrow to
+// "no filter" rather than take the page down. Without the `.catch`, a hand-typed
+// or stale `?lastAuthorizedBy=…` that is not a UUID replaced the whole view with
+// an error screen quoting the raw regex. `lastAuthorizedBy` has no UI control
+// any more — the authorizer is a column, not a filter — but the parameter and
+// the server fn behind it still work for a caller that constructs the URL.
+const searchSchema = z.object({
+  page: z.coerce.number().int().min(1).optional().catch(undefined),
+  page_size: z.coerce.number().int().min(1).max(100).optional().catch(undefined),
+  state: z.enum(['armed', 'needs_reconfirm']).optional().catch(undefined),
+  lastAuthorizedBy: z
+    .string()
+    .trim()
+    .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+    .optional()
+    .catch(undefined),
+})
+
+type ScheduledPublicationsSearch = z.infer<typeof searchSchema>
+
+export function createAdminScheduledPublicationsRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    shouldReload: true,
+    validateSearch: searchSchema,
+    loaderDeps: ({ search }: { search: ScheduledPublicationsSearch }) => search,
+    loader: async ({ deps }: { deps: ScheduledPublicationsSearch }) => {
+      const runtime = await getScheduledPublicationRuntime()
+      if (!runtime.enabled) throw notFound()
+      const data = await listScheduledPublications({
+        data: {
+          page: deps.page,
+          pageSize: deps.page_size,
+          states: deps.state == null ? undefined : [deps.state],
+          lastAuthorizedBy: deps.lastAuthorizedBy,
+        },
+      })
+      return { data }
+    },
+    component: function AdminScheduledPublicationsComponent() {
+      const { data } = Route.useLoaderData() as { data: ScheduledPublicationListResponse }
+      const { t } = useTranslation('byline-admin')
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              {
+                label: t('scheduledPublication.list.title'),
+                href: getAdminRoutePath('scheduled-publications'),
+              },
+            ]}
+          />
+          <ScheduledPublicationsView data={data} />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/index.ts

@@ -38,6 +38,7 @@ export { createAdminLayoutRoute } from './create-admin-layout-route.js'
 export { createAdminPermissionsRoute } from './create-admin-permissions-route.js'
 export { createAdminRoleEditRoute } from './create-admin-role-edit-route.js'
 export { createAdminRolesListRoute } from './create-admin-roles-list-route.js'
+export { createAdminScheduledPublicationsRoute } from './create-admin-scheduled-publications-route.js'
 export { createAdminUserEditRoute } from './create-admin-user-edit-route.js'
 export { createAdminUsersListRoute } from './create-admin-users-list-route.js'
 export { createCollectionApiRoute } from './create-collection-api-route.js'

package/src/server-fns/collections/get.ts

@@ -8,10 +8,11 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
-import { getAdminBylineClient } from '@byline/client/server'
+import { getAdminBylineClient, getAdminRequestContext } from '@byline/client/server'
 import {
   BylineError,
   buildRelationSummaryPopulateMap,
+  collectionAbilityKey,
   ERR_NOT_FOUND,
   ErrorCodes,
   getCollectionAdminConfig,
@@ -165,6 +166,25 @@ const getDocumentFn = createServerFn({ method: 'GET' })
       | string[]
       | undefined
 
+    // Scheduled publication is editorial system metadata, not authored
+    // content. Do not join it into ordinary client reads: that would leak
+    // timing to public callers or make every read require publish abilities.
+    // The authenticated admin loader adds it only when the installation is
+    // enabled and this actor holds both schedule abilities for this collection.
+    const scheduledPublicationEnabled = getServerConfig().scheduledPublication?.enabled === true
+    let canSchedulePublication = false
+    let scheduledPublish: Awaited<ReturnType<typeof handle.getScheduledPublish>> = null
+    if (scheduledPublicationEnabled) {
+      const actor = (await getAdminRequestContext()).actor
+      canSchedulePublication =
+        actor?.hasAbility(collectionAbilityKey(path, 'changeStatus')) === true &&
+        actor.hasAbility(collectionAbilityKey(path, 'publish'))
+      if (canSchedulePublication) {
+        scheduledPublish = await handle.getScheduledPublish(id)
+      }
+    }
+    const serializedSchedule = scheduledPublish == null ? null : serialise(scheduledPublish)
+
     return {
       ...(parsed as Record<string, any>),
       _publishedVersion: publishedVersion,
@@ -175,6 +195,15 @@ const getDocumentFn = createServerFn({ method: 'GET' })
       ...(Array.isArray(availableVersionLocales)
         ? { _availableVersionLocales: availableVersionLocales }
         : {}),
+      _scheduledPublicationEnabled: scheduledPublicationEnabled,
+      _canSchedulePublication: canSchedulePublication,
+      _scheduledPublish: serializedSchedule,
+      ...(serializedSchedule == null
+        ? {}
+        : {
+            scheduledPublishAt: serializedSchedule.publishAt,
+            scheduledPublishVersionId: serializedSchedule.targetVersionId,
+          }),
     }
   })
 

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

@@ -18,6 +18,7 @@ export * from './list'
 export * from './reindex'
 export * from './reorder'
 export * from './restore-version'
+export * from './scheduled-publication'
 export * from './set-list-view-preference'
 export * from './stats'
 export * from './status'

package/src/server-fns/collections/scheduled-publication-response.test.node.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { DocumentPublishSchedule } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import { omitScheduleExecutionState } from './scheduled-publication-response.js'
+
+describe('scheduled-publication transport response', () => {
+  it('does not expose the execution fencing token or its lease', () => {
+    const now = new Date('2026-08-22T12:00:00.000Z')
+    const schedule: DocumentPublishSchedule = {
+      documentId: 'doc-1',
+      collectionId: 'collection-1',
+      targetVersionId: 'version-1',
+      publishAt: now,
+      state: 'armed',
+      suspendedAt: null,
+      suspendedReason: null,
+      scheduledBy: null,
+      lastAuthorizedBy: null,
+      lastAuthorizedAt: now,
+      scheduledAt: now,
+      updatedAt: now,
+      executionToken: 'sweep-fencing-secret',
+      executionExpiresAt: new Date('2026-08-22T12:05:00.000Z'),
+      lastAttemptAt: now,
+      nextAttemptAt: now,
+      attemptCount: 1,
+      lastError: null,
+    }
+
+    const response = omitScheduleExecutionState(schedule)
+
+    expect(response).not.toHaveProperty('executionToken')
+    expect(response).not.toHaveProperty('executionExpiresAt')
+    expect(JSON.stringify(response)).not.toContain('sweep-fencing-secret')
+    expect(response).toMatchObject({ documentId: 'doc-1', state: 'armed', attemptCount: 1 })
+  })
+})

package/src/server-fns/collections/scheduled-publication-response.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 { DocumentPublishScheduleInfo } from '@byline/client'
+import type { DocumentPublishSchedule } from '@byline/core'
+
+/** Remove sweep-owned fencing credentials before a schedule crosses a transport boundary. */
+export function omitScheduleExecutionState(
+  schedule: DocumentPublishScheduleInfo | DocumentPublishSchedule
+): DocumentPublishScheduleInfo {
+  const {
+    executionToken: _executionToken,
+    executionExpiresAt: _executionExpiresAt,
+    ...editorialSchedule
+  } = schedule as DocumentPublishSchedule
+  return editorialSchedule
+}

package/src/server-fns/collections/scheduled-publication.ts

@@ -0,0 +1,270 @@
+/**
+ * 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 type { DocumentPublishScheduleInfo } from '@byline/client'
+import { getAdminBylineClient, getAdminRequestContext } from '@byline/client/server'
+import {
+  type DocumentPublishSchedule,
+  type DocumentPublishScheduleState,
+  ERR_NOT_FOUND,
+  ERR_VALIDATION,
+  type RecurringTaskHealth,
+} from '@byline/core'
+import { listDocumentPublishSchedules } from '@byline/core/services'
+
+import { bylineCore } from '../../integrations/byline-core.js'
+import { omitScheduleExecutionState } from './scheduled-publication-response.js'
+import { serialise } from './utils.js'
+
+const TASK_NAME = 'documents.publish-scheduled'
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export interface ScheduledPublicationRuntime {
+  enabled: boolean
+  health: {
+    status: 'healthy' | 'failed' | 'stale' | 'not_started'
+    task: SerializedRecurringTaskHealth | null
+  } | null
+}
+
+type SerializedRecurringTaskHealth = Omit<
+  RecurringTaskHealth,
+  'nextRunAt' | 'lastStartedAt' | 'lastSucceededAt' | 'lastFailedAt' | 'databaseNow'
+> & {
+  nextRunAt: string
+  lastStartedAt: string | null
+  lastSucceededAt: string | null
+  lastFailedAt: string | null
+  databaseNow: string
+}
+
+export type SerializedDocumentPublishSchedule = Omit<
+  DocumentPublishScheduleInfo,
+  | 'publishAt'
+  | 'suspendedAt'
+  | 'lastAuthorizedAt'
+  | 'scheduledAt'
+  | 'updatedAt'
+  | 'lastAttemptAt'
+  | 'nextAttemptAt'
+> & {
+  publishAt: string
+  suspendedAt: string | null
+  lastAuthorizedAt: string
+  scheduledAt: string
+  updatedAt: string
+  lastAttemptAt: string | null
+  nextAttemptAt: string
+}
+
+export interface ScheduledPublicationListItem extends SerializedDocumentPublishSchedule {
+  collectionPath: string
+  collectionLabel: string
+  documentPath: string | null
+  /**
+   * Display name for `lastAuthorizedBy` — full name, or email when the account
+   * has no name set. `null` when the account no longer exists, which is a real
+   * state rather than an error: the authorizer column is not a foreign key, so
+   * a schedule outlives the account that authorized it. Callers fall back to
+   * showing the id.
+   */
+  lastAuthorizedByName: string | null
+}
+
+export interface ScheduledPublicationListResponse {
+  schedules: ScheduledPublicationListItem[]
+  meta: {
+    page: number
+    pageSize: number
+    total: number
+    totalPages: number
+  }
+  runtime: ScheduledPublicationRuntime
+}
+
+function assertFeatureEnabled(): void {
+  if (bylineCore().config.scheduledPublication?.enabled === true) return
+  throw ERR_NOT_FOUND({ message: 'Scheduled publication is not enabled for this installation' })
+}
+
+function serializeSchedule(
+  schedule: DocumentPublishScheduleInfo | DocumentPublishSchedule
+): SerializedDocumentPublishSchedule {
+  return serialise(
+    omitScheduleExecutionState(schedule)
+  ) as unknown as SerializedDocumentPublishSchedule
+}
+
+async function scheduledPublicationRuntime(): Promise<ScheduledPublicationRuntime> {
+  const core = bylineCore()
+  if (core.config.scheduledPublication?.enabled !== true) {
+    return { enabled: false, health: null }
+  }
+
+  const scheduler = core.db.scheduler
+  if (scheduler == null) {
+    return { enabled: true, health: { status: 'not_started', task: null } }
+  }
+  const [task] = await scheduler.health([TASK_NAME])
+  if (task == null) {
+    return { enabled: true, health: { status: 'not_started', task: null } }
+  }
+
+  const staleAfter = task.nextRunAt.getTime() + task.intervalMs * 2
+  const status = task.leaseExpired
+    ? 'stale'
+    : task.lastStatus === 'failed'
+      ? 'failed'
+      : staleAfter < task.databaseNow.getTime()
+        ? 'stale'
+        : 'healthy'
+  return {
+    enabled: true,
+    health: {
+      status,
+      task: serialise(task) as unknown as SerializedRecurringTaskHealth,
+    },
+  }
+}
+
+/** Authenticated feature discovery for the admin shell and health warning. */
+export const getScheduledPublicationRuntime = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    await getAdminRequestContext()
+    return scheduledPublicationRuntime()
+  }
+)
+
+export const scheduleCollectionDocumentPublish = createServerFn({ method: 'POST' })
+  .validator(
+    (input: { collection: string; id: string; publishAt: string; expectedVersionId: string }) =>
+      input
+  )
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    const schedule = await getAdminBylineClient()
+      .collection(data.collection)
+      .schedulePublish(data.id, {
+        publishAt: data.publishAt,
+        expectedVersionId: data.expectedVersionId,
+      })
+    return serializeSchedule(schedule)
+  })
+
+export const confirmCollectionDocumentScheduledPublish = createServerFn({ method: 'POST' })
+  .validator((input: { collection: string; id: string; expectedVersionId: string }) => input)
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    const schedule = await getAdminBylineClient()
+      .collection(data.collection)
+      .confirmScheduledPublish(data.id, { expectedVersionId: data.expectedVersionId })
+    return serializeSchedule(schedule)
+  })
+
+export const cancelCollectionDocumentScheduledPublish = createServerFn({ method: 'POST' })
+  .validator((input: { collection: string; id: string }) => input)
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    const schedule = await getAdminBylineClient()
+      .collection(data.collection)
+      .cancelScheduledPublish(data.id)
+    return schedule == null
+      ? { status: 'not_found' as const }
+      : { status: 'cancelled' as const, schedule: serializeSchedule(schedule) }
+  })
+
+export const listScheduledPublications = createServerFn({ method: 'GET' })
+  .validator(
+    (input: {
+      states?: readonly DocumentPublishScheduleState[]
+      lastAuthorizedBy?: string
+      page?: number
+      pageSize?: number
+    }) => input
+  )
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    if (data.states?.some((state) => state !== 'armed' && state !== 'needs_reconfirm') === true) {
+      throw ERR_VALIDATION({ message: 'state must be armed or needs_reconfirm' })
+    }
+    if (data.lastAuthorizedBy != null && !UUID_RE.test(data.lastAuthorizedBy)) {
+      throw ERR_VALIDATION({ message: 'lastAuthorizedBy must be a UUID' })
+    }
+    const core = bylineCore()
+    const page = data.page ?? 1
+    const pageSize = data.pageSize ?? 25
+    const requestContext = await getAdminRequestContext()
+    const result = await listDocumentPublishSchedules(core, requestContext, {
+      states: data.states,
+      lastAuthorizedBy: data.lastAuthorizedBy,
+      page,
+      pageSize,
+    })
+    const collections = new Map(
+      core.collections.map((definition) => {
+        const record = core.getCollectionRecord(definition.path)
+        return [record.collectionId, definition] as const
+      })
+    )
+    // Resolve authorizer names in one query for the whole page rather than one
+    // per row. `last_authorized_by` is deliberately not a foreign key — deleting
+    // an admin account must not revoke a schedule it authorized — so an id here
+    // may simply have no user row left, and the caller falls back to the id.
+    const authorizerIds = [
+      ...new Set(
+        result.schedules
+          .map((schedule) => schedule.lastAuthorizedBy)
+          .filter((id): id is string => id != null)
+      ),
+    ]
+    const authorizerNames = new Map<string, string>()
+    // `adminStore` is optional on core — an installation can run without the
+    // admin subsystem — so a missing store simply means no names to resolve and
+    // the column falls back to ids.
+    const adminUsers = core.adminStore?.adminUsers
+    if (authorizerIds.length > 0 && adminUsers != null) {
+      const users = await adminUsers.getByIds(authorizerIds)
+      for (const user of users) {
+        const fullName = [user.given_name, user.family_name].filter(Boolean).join(' ').trim()
+        authorizerNames.set(user.id, fullName.length > 0 ? fullName : user.email)
+      }
+    }
+
+    const schedules = await Promise.all(
+      result.schedules.map(async (schedule): Promise<ScheduledPublicationListItem> => {
+        const definition = collections.get(schedule.collectionId)
+        const documentPath = await core.db.queries.documents.getCurrentPath({
+          collection_id: schedule.collectionId,
+          document_id: schedule.documentId,
+        })
+        return {
+          ...serializeSchedule(schedule),
+          collectionPath: definition?.path ?? schedule.collectionId,
+          collectionLabel: definition?.labels.plural ?? definition?.path ?? schedule.collectionId,
+          documentPath,
+          lastAuthorizedByName:
+            schedule.lastAuthorizedBy == null
+              ? null
+              : (authorizerNames.get(schedule.lastAuthorizedBy) ?? null),
+        }
+      })
+    )
+
+    return {
+      schedules,
+      meta: {
+        page,
+        pageSize,
+        total: result.total,
+        totalPages: Math.max(1, Math.ceil(result.total / pageSize)),
+      },
+      runtime: await scheduledPublicationRuntime(),
+    } satisfies ScheduledPublicationListResponse
+  })