@byline/host-tanstack-start 4.14.0 → 4.15.0

package/src/admin-shell/scheduled-publications/list.tsx

@@ -0,0 +1,292 @@
+'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 { useMemo, useState } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+
+import { deriveScheduledPublicationState } from '@byline/admin/react'
+import { useTranslation } from '@byline/i18n/react'
+import {
+  Alert,
+  Badge,
+  Button,
+  Container,
+  Section,
+  Select,
+  Table,
+  useToastManager,
+} from '@byline/ui/react'
+import cx from 'clsx'
+
+import { getAdminRoutePath } from '../../routes/admin-path.js'
+import { cancelCollectionDocumentScheduledPublish } from '../../server-fns/collections/index.js'
+import { Link, useNavigate } from '../chrome/loose-router.js'
+import { RouterPager } from '../chrome/router-pager.js'
+import styles from './list.module.css'
+import type { ScheduledPublicationListResponse } from '../../server-fns/collections/index.js'
+
+/**
+ * Badge intent per state. Armed is informational; the two states that mean
+ * automatic publication is not going to happen unaided are warnings.
+ */
+const STATE_INTENT = {
+  none: 'noeffect',
+  armed: 'info',
+  needs_reconfirm: 'warning',
+  overdue: 'warning',
+} as const
+
+export function ScheduledPublicationsView({ data }: { data: ScheduledPublicationListResponse }) {
+  const { t, locale } = useTranslation('byline-admin')
+  // One clock reading for the whole render, so every row's armed/overdue
+  // boundary is decided against the same instant.
+  const now = Date.now()
+  const timeZone = useMemo(() => Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC', [])
+  const instantFormat = useMemo(
+    () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short', timeZone }),
+    [locale, timeZone]
+  )
+  const navigate = useNavigate()
+  const toastManager = useToastManager()
+  const location = useRouterState({ select: (state) => state.location })
+  const search = location.search as {
+    state?: 'armed' | 'needs_reconfirm'
+    page?: number
+  }
+  const [cancelling, setCancelling] = useState<string | null>(null)
+
+  const applySearch = (patch: Record<string, unknown>) => {
+    navigate({
+      to: getAdminRoutePath('scheduled-publications'),
+      search: { ...(location.search as Record<string, unknown>), ...patch, page: undefined },
+    })
+  }
+
+  const cancel = async (collection: string, documentId: string) => {
+    setCancelling(documentId)
+    try {
+      const result = await cancelCollectionDocumentScheduledPublish({
+        data: { collection, id: documentId },
+      })
+      const cancelled = result.status === 'cancelled'
+      toastManager.add({
+        title: cancelled
+          ? t('scheduledPublication.toast.cancelledTitle')
+          : t('scheduledPublication.toast.cancelLostTitle'),
+        description: cancelled
+          ? t('scheduledPublication.toast.cancelledDescription')
+          : t('scheduledPublication.toast.cancelLostDescription'),
+        data: {
+          intent: cancelled ? 'success' : 'warning',
+          iconType: cancelled ? 'success' : 'warning',
+          icon: true,
+          close: true,
+        },
+      })
+      navigate({
+        to: getAdminRoutePath('scheduled-publications'),
+        search: location.search as Record<string, unknown>,
+      })
+    } catch (error) {
+      toastManager.add({
+        title: t('scheduledPublication.toast.failedTitle'),
+        description: (error as Error).message,
+        data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
+      })
+    } finally {
+      setCancelling(null)
+    }
+  }
+
+  const unhealthy = data.runtime.health?.status !== 'healthy'
+
+  return (
+    <Section>
+      <Container>
+        <div className={cx('byline-scheduled-list-head', styles.head)}>
+          <h1 className={styles.title}>{t('scheduledPublication.list.title')}</h1>
+          <p className={styles.intro}>{t('scheduledPublication.list.intro')}</p>
+        </div>
+
+        {unhealthy && (
+          <Alert
+            className={styles.health}
+            intent="warning"
+            icon={true}
+            close={false}
+            title={t('scheduledPublication.list.schedulerWarningTitle')}
+          >
+            {t('scheduledPublication.list.schedulerWarningBody', {
+              status: data.runtime.health?.status ?? 'not_started',
+            })}
+          </Alert>
+        )}
+
+        <div className={styles.controls}>
+          <div className={styles.filters}>
+            <div className={styles.filter}>
+              <Select<string>
+                id="scheduled-publication-state"
+                name="scheduled-publication-state"
+                ariaLabel={t('scheduledPublication.list.filters.state')}
+                size="sm"
+                value={search.state ?? '_all'}
+                items={[
+                  { value: '_all', label: t('scheduledPublication.list.filters.allStates') },
+                  { value: 'armed', label: t('scheduledPublication.list.states.armed') },
+                  {
+                    value: 'needs_reconfirm',
+                    label: t('scheduledPublication.list.states.needsReconfirm'),
+                  },
+                ]}
+                onValueChange={(value) =>
+                  applySearch({ state: value === '_all' ? undefined : value })
+                }
+              />
+            </div>
+          </div>
+          <RouterPager
+            page={data.meta.page}
+            count={data.meta.totalPages}
+            showFirstButton
+            showLastButton
+            componentName="scheduledPublicationsPagerTop"
+            aria-label={t('scheduledPublication.list.pagerAriaLabel')}
+          />
+        </div>
+
+        {data.schedules.length === 0 ? (
+          <p className={styles.empty}>{t('scheduledPublication.list.empty')}</p>
+        ) : (
+          <Table.Container className={styles.tableWrap}>
+            <Table>
+              <Table.Header>
+                <Table.Row>
+                  <Table.HeadingCell scope="col">
+                    {t('scheduledPublication.list.columns.document')}
+                  </Table.HeadingCell>
+                  <Table.HeadingCell scope="col">
+                    {t('scheduledPublication.list.columns.publishAt')}
+                  </Table.HeadingCell>
+                  <Table.HeadingCell scope="col">
+                    {t('scheduledPublication.list.columns.state')}
+                  </Table.HeadingCell>
+                  <Table.HeadingCell scope="col">
+                    {t('scheduledPublication.list.columns.authorizer')}
+                  </Table.HeadingCell>
+                  <Table.HeadingCell scope="col">
+                    {t('scheduledPublication.list.columns.attempt')}
+                  </Table.HeadingCell>
+                  <Table.HeadingCell scope="col">
+                    {t('scheduledPublication.list.columns.actions')}
+                  </Table.HeadingCell>
+                </Table.Row>
+              </Table.Header>
+              <Table.Body>
+                {data.schedules.map((schedule) => {
+                  // Same derivation the document editor uses, so a row here and
+                  // the document it links to can never disagree about whether a
+                  // schedule has gone overdue.
+                  const state = deriveScheduledPublicationState(
+                    schedule,
+                    { canSchedule: false, canConfirm: false, canCancel: true },
+                    now
+                  )
+                  const publishAt = new Date(schedule.publishAt)
+                  return (
+                    <Table.Row key={schedule.documentId}>
+                      <Table.Cell>
+                        <Link
+                          to={getAdminRoutePath('collections', '$collection', '$id')}
+                          params={{
+                            collection: schedule.collectionPath,
+                            id: schedule.documentId,
+                          }}
+                        >
+                          {schedule.documentPath || schedule.documentId}
+                        </Link>
+                        <span className={styles.collection}>{schedule.collectionLabel}</span>
+                      </Table.Cell>
+                      <Table.Cell>
+                        <time className={styles.instant} dateTime={publishAt.toISOString()}>
+                          {instantFormat.format(publishAt)}
+                        </time>
+                        <span className={styles.zone}>{timeZone}</span>
+                      </Table.Cell>
+                      <Table.Cell>
+                        <Badge intent={STATE_INTENT[state.kind]}>
+                          {state.kind === 'needs_reconfirm'
+                            ? t('scheduledPublication.list.states.needsReconfirm')
+                            : state.kind === 'overdue'
+                              ? t('scheduledPublication.list.states.overdue')
+                              : t('scheduledPublication.list.states.armed')}
+                        </Badge>
+                      </Table.Cell>
+                      <Table.Cell>
+                        {schedule.lastAuthorizedByName != null ? (
+                          <span>{schedule.lastAuthorizedByName}</span>
+                        ) : schedule.lastAuthorizedBy != null ? (
+                          // The account is gone — the schedule outlives it by
+                          // design — so the id is all there is left to identify
+                          // who authorized this.
+                          <span
+                            className={styles.authorizer}
+                            title={t('scheduledPublication.list.authorizerMissing')}
+                          >
+                            {schedule.lastAuthorizedBy}
+                          </span>
+                        ) : (
+                          <span>—</span>
+                        )}
+                      </Table.Cell>
+                      <Table.Cell>
+                        <span>{schedule.attemptCount}</span>
+                        {schedule.lastError != null && (
+                          <span className={styles.error}>{schedule.lastError}</span>
+                        )}
+                      </Table.Cell>
+                      <Table.Cell>
+                        <Button
+                          size="xs"
+                          type="button"
+                          intent="danger"
+                          disabled={cancelling === schedule.documentId}
+                          // The column header already says Actions and the row
+                          // is a schedule, so the short label carries here —
+                          // unlike the editor's menu, where "Cancel schedule"
+                          // has to distinguish itself from cancelling an edit.
+                          aria-label={t('scheduledPublication.actions.cancel')}
+                          onClick={() => cancel(schedule.collectionPath, schedule.documentId)}
+                        >
+                          {t('common.actions.cancel')}
+                        </Button>
+                      </Table.Cell>
+                    </Table.Row>
+                  )
+                })}
+              </Table.Body>
+            </Table>
+          </Table.Container>
+        )}
+
+        <div className={styles.pagerBottom}>
+          <RouterPager
+            page={data.meta.page}
+            count={data.meta.totalPages}
+            showFirstButton
+            showLastButton
+            componentName="scheduledPublicationsPagerBottom"
+            aria-label={t('scheduledPublication.list.pagerAriaLabel')}
+          />
+        </div>
+      </Container>
+    </Section>
+  )
+}

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