@byline/admin 4.14.1 → 4.16.0

package/src/forms/scheduled-publication-state.test.node.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 } from 'vitest'
+
+import { deriveScheduledPublicationState } from './scheduled-publication-state.js'
+import type { ScheduledPublicationInfo } from './scheduled-publication-state.js'
+
+const NOW = Date.parse('2026-08-22T12:00:00.000Z')
+
+const ALL_CAPABILITIES = { canSchedule: true, canConfirm: true, canCancel: true }
+const NO_CAPABILITIES = { canSchedule: false, canConfirm: false, canCancel: false }
+
+function schedule(overrides: Partial<ScheduledPublicationInfo> = {}): ScheduledPublicationInfo {
+  return {
+    publishAt: '2026-08-24T09:00:00.000Z',
+    targetVersionId: '019f0000-0000-7000-8000-000000000001',
+    state: 'armed',
+    lastAuthorizedBy: '019e3daa-42dd-70bb-9be3-5f18b1594b0a',
+    lastError: null,
+    nextAttemptAt: '2026-08-24T09:00:00.000Z',
+    attemptCount: 0,
+    ...overrides,
+  }
+}
+
+describe('deriveScheduledPublicationState', () => {
+  describe('with no schedule', () => {
+    it('offers only the schedule action', () => {
+      const state = deriveScheduledPublicationState(null, ALL_CAPABILITIES, NOW)
+
+      expect(state.kind).toBe('none')
+      expect(state.isExceptional).toBe(false)
+      expect(state.actions).toEqual({
+        schedule: true,
+        reschedule: false,
+        confirm: false,
+        cancel: false,
+      })
+    })
+
+    it('offers nothing at all to an actor without the abilities', () => {
+      const state = deriveScheduledPublicationState(null, NO_CAPABILITIES, NOW)
+
+      expect(state.actions.schedule).toBe(false)
+    })
+  })
+
+  describe('armed', () => {
+    it('reads as a quiet, non-exceptional state', () => {
+      const state = deriveScheduledPublicationState(schedule(), ALL_CAPABILITIES, NOW)
+
+      expect(state.kind).toBe('armed')
+      expect(state.tone).toBe('info')
+      expect(state.isExceptional).toBe(false)
+      expect(state.isPastDue).toBe(false)
+      expect(state.publishAt?.toISOString()).toBe('2026-08-24T09:00:00.000Z')
+    })
+
+    it('offers reschedule and cancel but never confirm', () => {
+      const state = deriveScheduledPublicationState(schedule(), ALL_CAPABILITIES, NOW)
+
+      expect(state.actions).toEqual({
+        schedule: false,
+        reschedule: true,
+        confirm: false,
+        cancel: true,
+      })
+    })
+
+    it('becomes overdue the instant the authorized time is reached', () => {
+      const due = Date.parse('2026-08-24T09:00:00.000Z')
+
+      expect(deriveScheduledPublicationState(schedule(), ALL_CAPABILITIES, due - 1).kind).toBe(
+        'armed'
+      )
+      expect(deriveScheduledPublicationState(schedule(), ALL_CAPABILITIES, due).kind).toBe(
+        'overdue'
+      )
+    })
+  })
+
+  describe('needs re-confirmation', () => {
+    it('escalates and offers confirm alongside reschedule and cancel', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ state: 'needs_reconfirm' }),
+        ALL_CAPABILITIES,
+        NOW
+      )
+
+      expect(state.kind).toBe('needs_reconfirm')
+      expect(state.tone).toBe('warning')
+      expect(state.isExceptional).toBe(true)
+      expect(state.actions).toEqual({
+        schedule: false,
+        reschedule: true,
+        confirm: true,
+        cancel: true,
+      })
+    })
+
+    it('stays suspended rather than overdue once its instant has passed', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ state: 'needs_reconfirm' }),
+        ALL_CAPABILITIES,
+        Date.parse('2026-08-25T09:00:00.000Z')
+      )
+
+      // The reason it did not publish is the suspension, not the clock — but
+      // the elapsed instant still has to be reportable to the editor.
+      expect(state.kind).toBe('needs_reconfirm')
+      expect(state.isPastDue).toBe(true)
+    })
+
+    it('withholds confirm from an actor who cannot confirm', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ state: 'needs_reconfirm' }),
+        { canSchedule: false, canConfirm: false, canCancel: true },
+        NOW
+      )
+
+      expect(state.actions.confirm).toBe(false)
+      expect(state.actions.reschedule).toBe(false)
+      expect(state.actions.cancel).toBe(true)
+    })
+  })
+
+  describe('overdue', () => {
+    const overdueNow = Date.parse('2026-08-24T09:05:00.000Z')
+
+    it('escalates and exposes the retry count', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ attemptCount: 3 }),
+        ALL_CAPABILITIES,
+        overdueNow
+      )
+
+      expect(state.kind).toBe('overdue')
+      expect(state.isExceptional).toBe(true)
+      expect(state.attemptCount).toBe(3)
+    })
+
+    it('raises the tone to danger when the sweep reported an error', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ attemptCount: 2, lastError: 'workflow transition rejected' }),
+        ALL_CAPABILITIES,
+        overdueNow
+      )
+
+      expect(state.tone).toBe('danger')
+      expect(state.lastError).toBe('workflow transition rejected')
+    })
+
+    it('raises the tone to danger even while still armed and not yet due', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ lastError: 'transient database error' }),
+        ALL_CAPABILITIES,
+        NOW
+      )
+
+      expect(state.kind).toBe('armed')
+      expect(state.tone).toBe('danger')
+    })
+
+    it('still offers cancel so a stuck schedule can be cleared', () => {
+      const state = deriveScheduledPublicationState(
+        schedule({ attemptCount: 5, lastError: 'boom' }),
+        { canSchedule: false, canConfirm: false, canCancel: true },
+        overdueNow
+      )
+
+      expect(state.actions.cancel).toBe(true)
+    })
+  })
+
+  it('accepts a Date instant as readily as an ISO string', () => {
+    const state = deriveScheduledPublicationState(
+      schedule({ publishAt: new Date('2026-08-24T09:00:00.000Z') }),
+      ALL_CAPABILITIES,
+      NOW
+    )
+
+    expect(state.publishAt?.toISOString()).toBe('2026-08-24T09:00:00.000Z')
+  })
+})

package/src/forms/scheduled-publication-state.ts

@@ -0,0 +1,146 @@
+/**
+ * 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
+ */
+
+/**
+ * Presentation state for a document's pending publication schedule.
+ *
+ * The editor surfaces four situations, and they differ in how loudly they
+ * should be presented, not just in wording:
+ *
+ *   - `none`            — nothing scheduled; only the "schedule" action applies.
+ *   - `armed`           — a future instant is authorized against a reviewed
+ *                         version. Quiet: a metadata cell in the status bar.
+ *   - `needs_reconfirm` — content was saved after the time was authorized, so
+ *                         the schedule is suspended until an editor reviews and
+ *                         confirms the current version. Loud, and durable: this
+ *                         has to stay discoverable long after the toast is gone.
+ *   - `overdue`         — armed, due, and not yet finalized. The sweep may still
+ *                         be retrying, and `lastError` may carry a bounded
+ *                         reason. Loud.
+ *
+ * Deriving this in one pure place keeps the branching out of the components and
+ * makes the awkward combinations (a suspended schedule whose instant has also
+ * passed; an overdue schedule the actor may not cancel) testable without a DOM.
+ */
+
+export type ScheduledPublicationStateKind = 'none' | 'armed' | 'needs_reconfirm' | 'overdue'
+
+/** How prominently the state should be rendered. */
+export type ScheduledPublicationTone = 'neutral' | 'info' | 'warning' | 'danger'
+
+export interface ScheduledPublicationInfo {
+  publishAt: string | Date
+  targetVersionId: string
+  state: 'armed' | 'needs_reconfirm'
+  lastAuthorizedBy: string | null
+  lastError: string | null
+  nextAttemptAt: string | Date
+  attemptCount: number
+}
+
+/**
+ * Which operations the host has wired up for this document and actor. A
+ * missing handler means the actor cannot perform the operation — the server
+ * decides, and the editor never renders an action it cannot complete.
+ */
+export interface ScheduledPublicationCapabilities {
+  canSchedule: boolean
+  canConfirm: boolean
+  canCancel: boolean
+}
+
+export interface ScheduledPublicationState {
+  kind: ScheduledPublicationStateKind
+  tone: ScheduledPublicationTone
+  /** The authorized instant, or null when nothing is scheduled. */
+  publishAt: Date | null
+  /**
+   * True when the authorized instant has passed. Tracked separately from
+   * `kind` so a suspended schedule that is also past due still reads as
+   * "needs re-confirmation" — the reason it did not publish — while the
+   * elapsed time remains available to the summary.
+   */
+  isPastDue: boolean
+  /** Bounded failure reason from the last sweep attempt, when the server sent one. */
+  lastError: string | null
+  /** Sweep attempts so far. Only meaningful once the instant has passed. */
+  attemptCount: number
+  /** True when the state warrants an escalated, dismissible-proof notice rather than a metadata cell. */
+  isExceptional: boolean
+  actions: {
+    schedule: boolean
+    reschedule: boolean
+    confirm: boolean
+    cancel: boolean
+  }
+}
+
+function toDate(value: string | Date): Date {
+  return value instanceof Date ? value : new Date(value)
+}
+
+/**
+ * Derive the editor's presentation state from the server's schedule record.
+ *
+ * `now` is injected rather than read from the clock so the boundary between
+ * armed and overdue is testable, and so a single render pass cannot disagree
+ * with itself.
+ */
+export function deriveScheduledPublicationState(
+  schedule: ScheduledPublicationInfo | null,
+  capabilities: ScheduledPublicationCapabilities,
+  now: number
+): ScheduledPublicationState {
+  if (schedule == null) {
+    return {
+      kind: 'none',
+      tone: 'neutral',
+      publishAt: null,
+      isPastDue: false,
+      lastError: null,
+      attemptCount: 0,
+      isExceptional: false,
+      actions: {
+        schedule: capabilities.canSchedule,
+        reschedule: false,
+        confirm: false,
+        cancel: false,
+      },
+    }
+  }
+
+  const publishAt = toDate(schedule.publishAt)
+  const isPastDue = Number.isFinite(publishAt.getTime()) && publishAt.getTime() <= now
+  const needsReconfirm = schedule.state === 'needs_reconfirm'
+  const kind: ScheduledPublicationStateKind = needsReconfirm
+    ? 'needs_reconfirm'
+    : isPastDue
+      ? 'overdue'
+      : 'armed'
+
+  // An error the sweep reported outranks the state's own tone: it is the only
+  // signal that automatic publication is actively failing rather than pending.
+  const tone: ScheduledPublicationTone =
+    schedule.lastError != null ? 'danger' : kind === 'armed' ? 'info' : 'warning'
+
+  return {
+    kind,
+    tone,
+    publishAt,
+    isPastDue,
+    lastError: schedule.lastError,
+    attemptCount: schedule.attemptCount,
+    isExceptional: kind !== 'armed',
+    actions: {
+      schedule: false,
+      reschedule: capabilities.canSchedule,
+      confirm: needsReconfirm && capabilities.canConfirm,
+      cancel: capabilities.canCancel,
+    },
+  }
+}

package/src/forms/scheduled-publication-time.test.node.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 { describe, expect, it } from 'vitest'
+
+import {
+  joinWallTime,
+  resolveScheduledPublicationWallTime,
+  wallTimeInZone,
+} from './scheduled-publication-time.js'
+
+describe('resolveScheduledPublicationWallTime', () => {
+  it('rejects a calendar date that the Date constructor would normalize', () => {
+    expect(resolveScheduledPublicationWallTime('2026-02-30T12:00', 'UTC')).toEqual({
+      status: 'invalid',
+    })
+  })
+
+  it('resolves an ordinary wall time to one ISO instant', () => {
+    expect(resolveScheduledPublicationWallTime('2026-08-23T12:00', 'America/New_York')).toEqual({
+      status: 'valid',
+      choices: [{ iso: '2026-08-23T16:00:00.000Z', offsetLabel: 'UTC-04:00' }],
+    })
+  })
+
+  it('rejects a daylight-saving gap instead of silently shifting it', () => {
+    expect(resolveScheduledPublicationWallTime('2026-03-08T02:30', 'America/New_York')).toEqual({
+      status: 'nonexistent',
+    })
+  })
+
+  it('returns both instants in a daylight-saving overlap', () => {
+    expect(resolveScheduledPublicationWallTime('2026-11-01T01:30', 'America/New_York')).toEqual({
+      status: 'valid',
+      choices: [
+        { iso: '2026-11-01T05:30:00.000Z', offsetLabel: 'UTC-04:00' },
+        { iso: '2026-11-01T06:30:00.000Z', offsetLabel: 'UTC-05:00' },
+      ],
+    })
+  })
+})
+
+describe('wallTimeInZone', () => {
+  it('splits an instant into the day and clock reading shown in the zone', () => {
+    expect(wallTimeInZone(new Date('2026-08-23T16:00:00.000Z'), 'America/New_York')).toEqual({
+      date: '2026-08-23',
+      time: '12:00',
+    })
+  })
+
+  it('reports the previous day when the zone is behind the instant', () => {
+    expect(wallTimeInZone(new Date('2026-08-24T02:00:00.000Z'), 'America/New_York')).toEqual({
+      date: '2026-08-23',
+      time: '22:00',
+    })
+  })
+
+  it('round-trips an overlap instant back to the wall time that produced it', () => {
+    // The second 01:30 of the fall-back overlap. Both instants share a wall
+    // time, so re-opening the modal must show 01:30 rather than a UTC spelling.
+    expect(wallTimeInZone(new Date('2026-11-01T06:30:00.000Z'), 'America/New_York')).toEqual({
+      date: '2026-11-01',
+      time: '01:30',
+    })
+  })
+})
+
+describe('joinWallTime', () => {
+  it('joins the two halves into the resolver grammar', () => {
+    expect(joinWallTime({ date: '2026-08-23', time: '12:00' })).toBe('2026-08-23T12:00')
+  })
+
+  it('drops the seconds a native time input may append', () => {
+    expect(joinWallTime({ date: '2026-08-23', time: '12:00:00' })).toBe('2026-08-23T12:00')
+  })
+
+  it('returns null while either half is still blank', () => {
+    expect(joinWallTime({ date: '', time: '12:00' })).toBeNull()
+    expect(joinWallTime({ date: '2026-08-23', time: '' })).toBeNull()
+  })
+})

package/src/forms/scheduled-publication-time.ts

@@ -0,0 +1,218 @@
+/**
+ * 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 interface ScheduledPublicationInstantChoice {
+  iso: string
+  offsetLabel: string
+}
+
+/**
+ * A wall time as the editor sees it: a calendar day and a clock reading, with
+ * no instant attached yet.
+ *
+ * The schedule modal takes these two halves from the date picker's
+ * `onWallTimeChange` and keeps them as strings all the way to
+ * `resolveScheduledPublicationWallTime`, never routing them through a `Date`.
+ * That is deliberate: `setHours` silently normalizes a nonexistent wall time (a
+ * spring-forward 02:30 becomes 03:30) and silently picks the first of two
+ * ambiguous instants at a fall-back overlap. Both are exactly the cases the
+ * editor has to be asked about, so the only safe carrier between the picker and
+ * the resolver is text.
+ */
+export interface ScheduledPublicationWallTime {
+  /** Calendar day as `YYYY-MM-DD`. */
+  date: string
+  /** Clock reading as `HH:mm`, 24-hour. */
+  time: string
+}
+
+export type ScheduledPublicationWallTimeResolution =
+  | { status: 'invalid' }
+  | { status: 'nonexistent' }
+  | { status: 'valid'; choices: ScheduledPublicationInstantChoice[] }
+
+interface WallParts {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+}
+
+function parseWallParts(value: string): WallParts | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/.exec(value)
+  if (match == null) return null
+  const [, year, month, day, hour, minute] = match
+  const parts = {
+    year: Number(year),
+    month: Number(month),
+    day: Number(day),
+    hour: Number(hour),
+    minute: Number(minute),
+  }
+  if (
+    parts.year < 1 ||
+    parts.month < 1 ||
+    parts.month > 12 ||
+    parts.day < 1 ||
+    parts.day > 31 ||
+    parts.hour > 23 ||
+    parts.minute > 59
+  ) {
+    return null
+  }
+  const calendar = new Date(0)
+  calendar.setUTCFullYear(parts.year, parts.month - 1, parts.day)
+  calendar.setUTCHours(parts.hour, parts.minute, 0, 0)
+  if (
+    calendar.getUTCFullYear() !== parts.year ||
+    calendar.getUTCMonth() !== parts.month - 1 ||
+    calendar.getUTCDate() !== parts.day
+  ) {
+    return null
+  }
+  return parts
+}
+
+function formatter(timeZone: string): Intl.DateTimeFormat {
+  return new Intl.DateTimeFormat('en-US-u-ca-iso8601-nu-latn', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hourCycle: 'h23',
+  })
+}
+
+function zonedParts(format: Intl.DateTimeFormat, epochMs: number): WallParts & { second: number } {
+  const values = Object.fromEntries(
+    format
+      .formatToParts(epochMs)
+      .filter((part) => part.type !== 'literal')
+      .map((part) => [part.type, Number(part.value)])
+  )
+  return {
+    year: values.year ?? Number.NaN,
+    month: values.month ?? Number.NaN,
+    day: values.day ?? Number.NaN,
+    hour: values.hour ?? Number.NaN,
+    minute: values.minute ?? Number.NaN,
+    second: values.second ?? Number.NaN,
+  }
+}
+
+function sameWallTime(actual: WallParts, expected: WallParts): boolean {
+  return (
+    actual.year === expected.year &&
+    actual.month === expected.month &&
+    actual.day === expected.day &&
+    actual.hour === expected.hour &&
+    actual.minute === expected.minute
+  )
+}
+
+function offsetMinutes(format: Intl.DateTimeFormat, epochMs: number): number {
+  const parts = zonedParts(format, epochMs)
+  const localAsUtc = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second
+  )
+  return Math.round((localAsUtc - epochMs) / 60_000)
+}
+
+function formatOffset(minutes: number): string {
+  const sign = minutes < 0 ? '-' : '+'
+  const absolute = Math.abs(minutes)
+  const hours = String(Math.floor(absolute / 60)).padStart(2, '0')
+  const remainingMinutes = String(absolute % 60).padStart(2, '0')
+  return `UTC${sign}${hours}:${remainingMinutes}`
+}
+
+/**
+ * Resolve a browser-entered wall time in an explicit IANA zone. Returns no
+ * choice for a daylight-saving gap and two choices for an overlap, forcing
+ * the editor to choose an actual instant rather than accepting JS Date's
+ * silent normalization.
+ */
+export function resolveScheduledPublicationWallTime(
+  value: string,
+  timeZone: string
+): ScheduledPublicationWallTimeResolution {
+  const wall = parseWallParts(value)
+  if (wall == null) return { status: 'invalid' }
+
+  let format: Intl.DateTimeFormat
+  try {
+    format = formatter(timeZone)
+  } catch {
+    return { status: 'invalid' }
+  }
+
+  const wallAsUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute)
+  const offsets = new Set<number>()
+  for (let hours = -36; hours <= 36; hours += 6) {
+    offsets.add(offsetMinutes(format, wallAsUtc + hours * 3_600_000))
+  }
+
+  const choices = Array.from(offsets)
+    .map((offset) => ({ epochMs: wallAsUtc - offset * 60_000, offset }))
+    .filter(({ epochMs }) => sameWallTime(zonedParts(format, epochMs), wall))
+    .sort((left, right) => left.epochMs - right.epochMs)
+    .map(({ epochMs, offset }) => ({
+      iso: new Date(epochMs).toISOString(),
+      offsetLabel: formatOffset(offset),
+    }))
+
+  if (choices.length === 0) return { status: 'nonexistent' }
+  return { status: 'valid', choices }
+}
+
+/**
+ * Split an instant into the calendar day and clock reading it shows in
+ * `timeZone`. Used to seed the modal when rescheduling, so the editor starts
+ * from the time they authorized rather than from its UTC spelling.
+ */
+export function wallTimeInZone(instant: Date, timeZone: string): ScheduledPublicationWallTime {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat('en-US-u-ca-iso8601-nu-latn', {
+      timeZone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      hourCycle: 'h23',
+    })
+      .formatToParts(instant)
+      .filter((part) => part.type !== 'literal')
+      .map((part) => [part.type, part.value])
+  )
+  return {
+    date: `${parts.year}-${parts.month}-${parts.day}`,
+    time: `${parts.hour}:${parts.minute}`,
+  }
+}
+
+/**
+ * Join a wall time back into the `YYYY-MM-DDTHH:mm` string that
+ * `resolveScheduledPublicationWallTime` parses. Returns null when either half
+ * is still blank, which is the modal's "nothing to validate yet" signal.
+ */
+export function joinWallTime(wall: ScheduledPublicationWallTime): string | null {
+  if (wall.date.length === 0 || wall.time.length === 0) return null
+  // Trim to minutes: the resolver's grammar stops there, and scheduling has no
+  // sub-minute meaning even if a clock reading arrives carrying seconds.
+  return `${wall.date}T${wall.time.slice(0, 5)}`
+}

package/src/index.ts

@@ -36,5 +36,6 @@ export * from './modules/admin-activity/index.js'
 export * from './modules/admin-permissions/index.js'
 export * from './modules/admin-roles/index.js'
 export * from './modules/admin-users/index.js'
+export * from './modules/analytics/index.js'
 export * from './modules/auth/index.js'
 export type { AdminStore } from './store.js'

package/src/modules/analytics/abilities.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { AbilityRegistry } from '@byline/auth'
+
+export const ANALYTICS_ABILITIES = {
+  read: 'analytics.read',
+  maintain: 'analytics.maintain',
+} as const
+
+export type AnalyticsAbilityKey = (typeof ANALYTICS_ABILITIES)[keyof typeof ANALYTICS_ABILITIES]
+
+export function registerAnalyticsAbilities(registry: AbilityRegistry): void {
+  registry.register({
+    key: ANALYTICS_ABILITIES.read,
+    label: 'Read analytics',
+    description: 'View installation-level page, visitor, download, referrer, and country totals.',
+    group: 'analytics',
+    source: 'admin',
+  })
+  registry.register({
+    key: ANALYTICS_ABILITIES.maintain,
+    label: 'Maintain analytics',
+    description: 'Delete retained analytics events and rebuild affected daily aggregates.',
+    group: 'analytics',
+    source: 'admin',
+  })
+}