@byline/host-tanstack-start 0.9.3

package/src/integrations/start-errors.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
+ */
+
+/**
+ * Serialization adapter for coded errors thrown from server fns.
+ *
+ * TanStack Start's default `ShallowErrorPlugin` matches any `Error` and
+ * serialises only `message` — `code`, `cause`, and custom fields are
+ * dropped on the wire. That makes client-side branching on `err.code`
+ * dead code: every failure reaches the caller as a plain `Error(message)`.
+ *
+ * This adapter is registered via `createStart(...)` in `src/start.ts`.
+ * TanStack prepends `serializationAdapters` before the default plugins,
+ * so our `test` matches first and our errors skip the shallow fallback.
+ *
+ * The adapter is intentionally duck-typed (`name + code`) rather than
+ * using `instanceof AdminUsersError` / `instanceof AuthError`. Both error
+ * classes live in packages whose barrel exports pull argon2 / other
+ * server-only code into whatever bundle imports them — a direct import
+ * here would drag that into the browser bundle. The string check is
+ * equally reliable in practice and keeps this module client-safe.
+ *
+ * On the client side we rebuild the error as `BylineCodedError` — a
+ * lightweight local class that preserves `name`, `code`, and `message`.
+ * The admin forms branch on `err.code === '...'` (string), not on the
+ * original class, so the UI behaves identically to a real throw.
+ */
+
+import { createSerializationAdapter } from '@tanstack/react-router'
+
+/**
+ * Names of server-side error classes we want to preserve across the
+ * server-fn boundary. Add a new entry when introducing another typed
+ * error class that carries a string `code`.
+ */
+const CODED_ERROR_NAMES = new Set([
+  'AdminAccountError',
+  'AdminPermissionsError',
+  'AdminRolesError',
+  'AdminUsersError',
+  'AuthError',
+])
+
+export interface BylineCodedErrorPayload {
+  name: string
+  code: string
+  message: string
+}
+
+/**
+ * Minimal `Error` subclass reconstructed on the deserialize side. Does
+ * not reference the original server-side classes — intentional, to keep
+ * this module free of server-only dependencies.
+ */
+export class BylineCodedError extends Error {
+  public readonly code: string
+
+  constructor(payload: BylineCodedErrorPayload) {
+    super(payload.message)
+    this.name = payload.name
+    this.code = payload.code
+  }
+}
+
+function isCodedError(value: unknown): value is Error & { code: string } {
+  if (!(value instanceof Error)) return false
+  if (!CODED_ERROR_NAMES.has(value.name)) return false
+  const code = (value as { code?: unknown }).code
+  return typeof code === 'string'
+}
+
+export const bylineCodedErrorAdapter = createSerializationAdapter({
+  key: 'BylineCodedError',
+  test: isCodedError,
+  toSerializable: (err): BylineCodedErrorPayload => ({
+    name: err.name,
+    code: err.code,
+    message: err.message,
+  }),
+  fromSerializable: (payload: BylineCodedErrorPayload) => new BylineCodedError(payload),
+})

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

@@ -0,0 +1,65 @@
+/**
+ * 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 } from '@tanstack/react-router'
+
+import { AccountSelfContainer } from '@byline/ui'
+import { Container, Section } from '@infonomic/uikit/react'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { type AccountResponse, getAccount } from '../server-fns/admin-account/index.js'
+
+function displayNameFor(account: {
+  given_name: string | null
+  family_name: string | null
+  email: string
+}): string {
+  const parts = [account.given_name, account.family_name].filter(
+    (part): part is string => typeof part === 'string' && part.length > 0
+  )
+  return parts.length > 0 ? parts.join(' ') : account.email
+}
+
+export function createAdminAccountRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async () => {
+      // The slim `user` on the admin route's context (CurrentAdminUser)
+      // doesn't carry `vid` or the createdAt/updatedAt/lastLogin
+      // timestamps, so the self-service drawer needs the full row.
+      const account = await getAccount({ data: {} })
+      return { account }
+    },
+    component: function AdminAccountComponent() {
+      const { account } = Route.useLoaderData() as { account: AccountResponse }
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: 'Account', href: '/admin/account' },
+            ]}
+          />
+          <Section className="pb-2">
+            <Container>
+              <h1 className="mb-2">{displayNameFor(account)}</h1>
+              <p className="muted">Manage your own profile and password.</p>
+            </Container>
+          </Section>
+          <Section>
+            <Container>
+              <AccountSelfContainer account={account} />
+            </Container>
+          </Section>
+        </>
+      )
+    },
+  })
+
+  return Route
+}

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

@@ -0,0 +1,52 @@
+/**
+ * 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 } from '@tanstack/react-router'
+
+import { getClientConfig } from '@byline/core'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { AdminDashboard } from '../admin-shell/chrome/dashboard.js'
+import { type CollectionStatusCount, getCollectionStats } from '../server-fns/collections/index.js'
+
+export function createAdminDashboardRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async () => {
+      const { collections } = getClientConfig()
+      const statsMap: Record<string, CollectionStatusCount[]> = {}
+
+      await Promise.all(
+        collections
+          .filter((c) => c.showStats === true)
+          .map(async (c) => {
+            try {
+              statsMap[c.path] = await getCollectionStats(c.path)
+            } catch {
+              statsMap[c.path] = []
+            }
+          })
+      )
+
+      return { statsMap }
+    },
+    component: function AdminDashboardComponent() {
+      const { statsMap } = Route.useLoaderData() as {
+        statsMap: Record<string, CollectionStatusCount[]>
+      }
+      return (
+        <>
+          <BreadcrumbsClient breadcrumbs={[{ label: 'Dashboard', href: '/admin' }]} />
+          <AdminDashboard statsMap={statsMap} />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

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

@@ -0,0 +1,89 @@
+/**
+ * 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
+ */
+
+/**
+ * Admin shell layout — authenticated-only.
+ *
+ * `beforeLoad` resolves the current admin user (which internally verifies
+ * the session cookies, refreshes transparently when needed, and throws
+ * `ERR_UNAUTHENTICATED` when there is no session). On unauthenticated
+ * requests we redirect to `/sign-in` with a `callbackUrl` so the user
+ * lands back on the page they originally requested.
+ *
+ * The resolved user is returned as route context so every nested admin
+ * route (and the `AdminAppBar`) can read it without an extra fetch.
+ */
+
+import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
+
+import { BylineAdminServicesProvider, BylineFieldServicesProvider } from '@byline/ui'
+import cx from 'classnames'
+
+import { AdminAppBar } from '../admin-shell/chrome/admin-app-bar.js'
+import layoutStyles from '../admin-shell/chrome/admin-layout.module.css'
+import { Content } from '../admin-shell/chrome/content.js'
+import { DrawerToggle } from '../admin-shell/chrome/drawer-toggle.js'
+import { AdminMenuDrawer } from '../admin-shell/chrome/menu-drawer.js'
+import { AdminMenuProvider } from '../admin-shell/chrome/menu-provider.js'
+import { RouteError, RouteNotFound } from '../admin-shell/chrome/route-error.js'
+import { bylineAdminServices } from '../integrations/byline-admin-services.js'
+import { bylineFieldServices } from '../integrations/byline-field-services.js'
+import { getCurrentAdminUser } from '../server-fns/auth/index.js'
+
+interface AdminLayoutOpts {
+  /** Path users are redirected to when unauthenticated. Defaults to `/sign-in`. */
+  signInPath?: string
+}
+
+export function createAdminLayoutRoute(path: string, opts: AdminLayoutOpts = {}) {
+  const signInPath = opts.signInPath ?? '/sign-in'
+
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    beforeLoad: async ({ location }: { location: { href: string } }) => {
+      try {
+        const user = await getCurrentAdminUser()
+        return { user }
+      } catch {
+        // `getCurrentAdminUser` (via `getAdminRequestContext`) throws
+        // `ERR_UNAUTHENTICATED` or a related auth error when no valid
+        // session is present. Redirect to sign-in with the original path
+        // so we can send the user back after they authenticate.
+        throw redirect({
+          to: signInPath as never,
+          search: { callbackUrl: location.href } as never,
+        })
+      }
+    },
+    component: function AdminLayoutComponent() {
+      const { user } = Route.useRouteContext() as {
+        user: Awaited<ReturnType<typeof getCurrentAdminUser>>
+      }
+      return (
+        <BylineAdminServicesProvider services={bylineAdminServices}>
+          <BylineFieldServicesProvider services={bylineFieldServices}>
+            <AdminMenuProvider>
+              <AdminAppBar user={user} />
+              <main className={cx('byline-admin-layout-main', layoutStyles.main)}>
+                <DrawerToggle />
+                <AdminMenuDrawer />
+                <Content>
+                  <Outlet />
+                </Content>
+              </main>
+            </AdminMenuProvider>
+          </BylineFieldServicesProvider>
+        </BylineAdminServicesProvider>
+      )
+    },
+    errorComponent: RouteError,
+    notFoundComponent: RouteNotFound,
+  })
+
+  return Route
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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 } from '@tanstack/react-router'
+
+import { AbilitiesInspector } from '@byline/ui'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import {
+  type ListRegisteredAbilitiesResponse,
+  listRegisteredAbilities,
+} from '../server-fns/admin-permissions/index.js'
+
+export function createAdminPermissionsRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async () => {
+      const data = await listRegisteredAbilities()
+      return { data }
+    },
+    component: function AdminPermissionsComponent() {
+      const { data } = Route.useLoaderData() as { data: ListRegisteredAbilitiesResponse }
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: 'Permissions', href: '/admin/permissions' },
+            ]}
+          />
+          <AbilitiesInspector data={data} />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-admin-role-edit-route.tsx

@@ -0,0 +1,88 @@
+/**
+ * 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 { Container, Section } from '@infonomic/uikit/react'
+
+import { RoleContainer } from '../admin-shell/admin-roles/container.js'
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import {
+  getRoleAbilities,
+  type ListRegisteredAbilitiesResponse,
+  listRegisteredAbilities,
+} from '../server-fns/admin-permissions/index.js'
+import { type AdminRoleResponse, getAdminRole } from '../server-fns/admin-roles/index.js'
+
+interface LoaderData {
+  role: AdminRoleResponse
+  registered: ListRegisteredAbilitiesResponse
+  initialAbilities: string[]
+}
+
+export function createAdminRoleEditRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async ({ params }: { params: { id: string } }): Promise<LoaderData> => {
+      try {
+        // Three independent reads — fetch in parallel so the role-detail
+        // page lands ready to open the permissions editor without a
+        // second waterfall.
+        const [role, registered, currentAbilities] = await Promise.all([
+          getAdminRole({ data: { id: params.id } }),
+          listRegisteredAbilities(),
+          getRoleAbilities({ data: { id: params.id } }),
+        ])
+        return { role, registered, initialAbilities: currentAbilities.abilities }
+      } catch (err) {
+        // Match on the string code rather than importing the error class —
+        // the subpath would pull argon2 into the browser bundle transitively.
+        if (
+          typeof err === 'object' &&
+          err !== null &&
+          'code' in err &&
+          ((err as { code?: unknown }).code === 'admin.roles.notFound' ||
+            (err as { code?: unknown }).code === 'admin.permissions.roleNotFound')
+        ) {
+          throw notFound()
+        }
+        throw err
+      }
+    },
+    component: function AdminRoleEditComponent() {
+      const { role, registered, initialAbilities } = Route.useLoaderData() as LoaderData
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: 'Admin Roles', href: '/admin/roles' },
+              { label: 'Role', href: `/admin/roles/${role.id}` },
+            ]}
+          />
+          <Section className="py-5 pb-2">
+            <Container>
+              <h1 className="mb-2">{role.name}</h1>
+            </Container>
+          </Section>
+          <Section>
+            <Container>
+              <RoleContainer
+                role={role}
+                registered={registered}
+                initialAbilities={initialAbilities}
+              />
+            </Container>
+          </Section>
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-admin-roles-list-route.tsx

@@ -0,0 +1,39 @@
+/**
+ * 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 } from '@tanstack/react-router'
+
+import { AdminRolesListView } from '../admin-shell/admin-roles/list.js'
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { type AdminRoleListResponse, listAdminRoles } from '../server-fns/admin-roles/index.js'
+
+export function createAdminRolesListRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async () => {
+      const data = await listAdminRoles()
+      return { data }
+    },
+    component: function AdminRolesListComponent() {
+      const { data } = Route.useLoaderData() as { data: AdminRoleListResponse }
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: 'Admin Roles', href: '/admin/roles' },
+            ]}
+          />
+          <AdminRolesListView data={data} />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-admin-user-edit-route.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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 { Container, Section } from '@infonomic/uikit/react'
+
+import { AccountContainer } from '../admin-shell/admin-users/container.js'
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { type AdminRoleResponse, listAdminRoles } from '../server-fns/admin-roles/index.js'
+import {
+  type AdminUserResponse,
+  getAdminUser,
+  getUserRoles,
+} from '../server-fns/admin-users/index.js'
+
+interface LoaderData {
+  user: AdminUserResponse
+  allRoles: AdminRoleResponse[]
+  initialUserRoles: AdminRoleResponse[]
+}
+
+function displayNameFor(user: {
+  given_name: string | null
+  family_name: string | null
+  email: string
+}): string {
+  const parts = [user.given_name, user.family_name].filter(
+    (part): part is string => typeof part === 'string' && part.length > 0
+  )
+  return parts.length > 0 ? parts.join(' ') : user.email
+}
+
+export function createAdminUserEditRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async ({ params }: { params: { id: string } }): Promise<LoaderData> => {
+      try {
+        // Three independent reads in parallel — the user row, the full
+        // role catalog (for the roles drawer's checkbox list), and the
+        // user's current role assignments.
+        const [user, rolesList, userRoles] = await Promise.all([
+          getAdminUser({ data: { id: params.id } }),
+          listAdminRoles(),
+          getUserRoles({ data: { userId: params.id } }),
+        ])
+        return { user, allRoles: rolesList.roles, initialUserRoles: userRoles.roles }
+      } catch (err) {
+        // Service emits `AdminUsersError(NOT_FOUND)` when the id resolves
+        // to no row; the user-roles command uses
+        // `admin.roles.userNotFound` for the same condition. Map either
+        // to the framework `notFound()` so the route renders the 404
+        // boundary rather than the generic error boundary. Matching on
+        // the string avoids importing from `@byline/admin` in a
+        // client-reachable module — the subpath pulls argon2 into the
+        // browser bundle transitively.
+        if (
+          typeof err === 'object' &&
+          err !== null &&
+          'code' in err &&
+          ((err as { code?: unknown }).code === 'admin.users.notFound' ||
+            (err as { code?: unknown }).code === 'admin.roles.userNotFound')
+        ) {
+          throw notFound()
+        }
+        throw err
+      }
+    },
+    component: function AdminUserEditComponent() {
+      const { user, allRoles, initialUserRoles } = Route.useLoaderData() as LoaderData
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: 'Admin Users', href: '/admin/users' },
+              { label: 'User', href: `/admin/users/${user.id}` },
+            ]}
+          />
+          <Section className="py-5 pb-2">
+            <Container>
+              <h1 className="mb-2">{displayNameFor(user)}</h1>
+            </Container>
+          </Section>
+          <Section>
+            <Container>
+              <AccountContainer
+                user={user}
+                allRoles={allRoles}
+                initialUserRoles={initialUserRoles}
+              />
+            </Container>
+          </Section>
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-admin-users-list-route.tsx

@@ -0,0 +1,84 @@
+/**
+ * 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 } from '@tanstack/react-router'
+
+import { z } from 'zod'
+
+import { AdminUsersListView } from '../admin-shell/admin-users/list.js'
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { type AdminUserListResponse, listAdminUsers } from '../server-fns/admin-users/index.js'
+
+const orderSchema = z.enum([
+  'given_name',
+  'family_name',
+  'email',
+  'username',
+  'created_at',
+  'updated_at',
+])
+
+const searchSchema = z.object({
+  page: z.coerce.number().int().min(1).optional(),
+  page_size: z.coerce.number().int().min(1).max(100).optional(),
+  query: z.string().optional(),
+  order: orderSchema.optional(),
+  desc: z.coerce.boolean().optional(),
+})
+
+export function createAdminUsersListRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    validateSearch: searchSchema,
+    loaderDeps: ({ search }: { search: z.infer<typeof searchSchema> }) => ({
+      page: search.page,
+      page_size: search.page_size,
+      query: search.query,
+      order: search.order,
+      desc: search.desc,
+    }),
+    loader: async ({
+      deps,
+    }: {
+      deps: {
+        page?: number
+        page_size?: number
+        query?: string
+        order?: string
+        desc?: boolean
+      }
+    }) => {
+      const data = await listAdminUsers({
+        data: {
+          page: deps.page,
+          pageSize: deps.page_size,
+          query: deps.query,
+          order: deps.order as never,
+          desc: deps.desc,
+        },
+      })
+      return { data }
+    },
+    component: function AdminUsersListComponent() {
+      const { data } = Route.useLoaderData() as { data: AdminUserListResponse }
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: 'Admin Users', href: '/admin/users' },
+            ]}
+          />
+          <AdminUsersListView data={data} />
+        </>
+      )
+    },
+  })
+
+  return Route
+}