@byline/admin 2.3.3 → 2.4.1

package/src/modules/admin-roles/components/update.tsx

@@ -0,0 +1,218 @@
+'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
+ */
+
+/**
+ * Role details drawer form.
+ *
+ * Mirrors the admin-users update pattern: TanStack Form + Zod, blur-then-
+ * change validation, diff-against-original patch, optimistic concurrency
+ * via `vid`. `machine_name` is read-only here — it is captured at create
+ * time and immutable thereafter.
+ */
+
+import { useState } from 'react'
+import { revalidateLogic, useForm } from '@tanstack/react-form-start'
+
+import { Alert, Button, Input, LoaderEllipsis, TextArea } from '@byline/ui/react'
+import cx from 'classnames'
+import { z } from 'zod'
+
+import { useBylineAdminServices } from '../../../services/admin-services-context.js'
+import styles from './update.module.css'
+import type { UpdateAdminRoleInput } from '../../../services/admin-services-types.js'
+import type { AdminRoleResponse } from '../index.js'
+
+const updateRoleSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(128, 'Name must not exceed 128 characters'),
+  description: z.string().max(2000, 'Description must not exceed 2000 characters'),
+})
+
+type UpdateRoleValues = z.infer<typeof updateRoleSchema>
+
+function defaultsFrom(role: AdminRoleResponse): UpdateRoleValues {
+  return {
+    name: role.name,
+    description: role.description ?? '',
+  }
+}
+
+/** Build a patch object containing only fields whose values differ from the original role. */
+function buildPatch(
+  values: UpdateRoleValues,
+  role: AdminRoleResponse
+): UpdateAdminRoleInput['patch'] {
+  const patch: UpdateAdminRoleInput['patch'] = {}
+  const normaliseText = (value: string): string | null => (value.trim().length > 0 ? value : null)
+  const nextDescription = normaliseText(values.description)
+  const nextName = values.name.trim()
+
+  if (nextName !== role.name) patch.name = nextName
+  if (nextDescription !== role.description) patch.description = nextDescription
+  return patch
+}
+
+interface UpdateRoleProps {
+  role: AdminRoleResponse
+  onClose?: () => void
+  onSuccess?: (role: AdminRoleResponse) => void
+}
+
+export function UpdateRole({ role, onClose, onSuccess }: UpdateRoleProps) {
+  const { updateAdminRole } = useBylineAdminServices()
+  const [formError, setFormError] = useState<string | null>(null)
+  const [successMessage, setSuccessMessage] = useState<string | null>(null)
+
+  const form = useForm({
+    defaultValues: defaultsFrom(role),
+    validationLogic: revalidateLogic({
+      mode: 'blur',
+      modeAfterSubmission: 'change',
+    }),
+    validators: {
+      onDynamic: updateRoleSchema,
+    },
+    onSubmit: async ({ value }) => {
+      setFormError(null)
+      setSuccessMessage(null)
+      const patch = buildPatch(value, role)
+      if (Object.keys(patch).length === 0) {
+        setSuccessMessage('No changes to save.')
+        return
+      }
+
+      try {
+        const updated = await updateAdminRole({
+          data: { id: role.id, vid: role.vid, patch },
+        })
+        setSuccessMessage('Saved.')
+        onSuccess?.(updated)
+      } catch (err) {
+        const code = getErrorCode(err)
+        if (code === 'admin.roles.versionConflict') {
+          setFormError(
+            'This role has been modified elsewhere since you opened this form. Reload to get the latest values and try again.'
+          )
+          return
+        }
+        if (code === 'admin.roles.notFound') {
+          setFormError('This role no longer exists.')
+          return
+        }
+        setFormError('Could not save changes. Please try again.')
+      }
+    },
+  })
+
+  return (
+    <div className={cx('byline-role-update-wrap', styles.wrap)}>
+      <form
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault()
+          event.stopPropagation()
+          void form.handleSubmit()
+        }}
+        className={cx('byline-role-update-form', styles.form)}
+      >
+        {formError ? <Alert intent="danger">{formError}</Alert> : null}
+        {successMessage ? <Alert intent="success">{successMessage}</Alert> : null}
+
+        <form.Field name="name">
+          {(field) => (
+            <Input
+              label="Name"
+              id="role-name"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              required
+            />
+          )}
+        </form.Field>
+
+        <Input
+          label="Machine name"
+          id="role-machine-name"
+          name="machine_name"
+          value={role.machine_name}
+          readOnly
+          disabled
+          helpText="The stable code-side handle. Cannot be changed after creation."
+        />
+
+        <form.Field name="description">
+          {(field) => (
+            <TextArea
+              label="Description"
+              id="role-description"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              rows={3}
+            />
+          )}
+        </form.Field>
+
+        <div className={cx('byline-role-update-actions', styles.actions)}>
+          <Button
+            type="button"
+            intent="secondary"
+            size="sm"
+            onClick={onClose}
+            className={cx('byline-role-update-action', styles.action)}
+          >
+            {successMessage ? 'Close' : 'Cancel'}
+          </Button>
+          <form.Subscribe
+            selector={(state) => ({
+              canSubmit: state.canSubmit,
+              isSubmitting: state.isSubmitting,
+            })}
+          >
+            {({ canSubmit, isSubmitting }) => (
+              <Button
+                size="sm"
+                intent="primary"
+                type="submit"
+                disabled={!canSubmit || isSubmitting}
+                className={cx('byline-role-update-action', styles.action)}
+              >
+                {isSubmitting === true ? <LoaderEllipsis size={42} /> : 'Save'}
+              </Button>
+            )}
+          </form.Subscribe>
+        </div>
+      </form>
+    </div>
+  )
+}
+
+function firstError(errors: readonly unknown[]): string | undefined {
+  for (const err of errors) {
+    if (typeof err === 'string') return err
+    if (err && typeof err === 'object' && 'message' in err) {
+      const msg = (err as { message?: unknown }).message
+      if (typeof msg === 'string') return msg
+    }
+  }
+  return undefined
+}
+
+function getErrorCode(err: unknown): string | null {
+  return typeof (err as { code?: unknown })?.code === 'string'
+    ? (err as { code: string }).code
+    : null
+}

package/src/modules/admin-roles/dto.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { AdminRoleRow } from './repository.js'
+import type { AdminRoleResponse } from './schemas.js'
+
+/**
+ * Shape an `AdminRoleRow` into its public `AdminRoleResponse` form.
+ *
+ * Effectively an identity map today — the indirection exists so future
+ * row-only fields (tenant id, soft-delete) stay opted out of the public
+ * shape by default.
+ */
+export function toAdminRole(row: AdminRoleRow): AdminRoleResponse {
+  return {
+    id: row.id,
+    vid: row.vid,
+    name: row.name,
+    machine_name: row.machine_name,
+    description: row.description,
+    order: row.order,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  }
+}

package/src/modules/admin-roles/errors.ts

@@ -0,0 +1,76 @@
+/**
+ * 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
+ */
+
+/**
+ * Module-local error codes for admin-roles.
+ *
+ * Mirrors the `code + factory` shape used by `AdminUsersError`. Codes
+ * are dot-prefixed (`admin.roles.*`) so they sort alongside the matching
+ * ability keys in logs and admin UI messages.
+ */
+
+export const AdminRolesErrorCodes = {
+  NOT_FOUND: 'admin.roles.notFound',
+  MACHINE_NAME_IN_USE: 'admin.roles.machineNameInUse',
+  VERSION_CONFLICT: 'admin.roles.versionConflict',
+  USER_NOT_FOUND: 'admin.roles.userNotFound',
+} as const
+
+export type AdminRolesErrorCode = (typeof AdminRolesErrorCodes)[keyof typeof AdminRolesErrorCodes]
+
+export interface AdminRolesErrorOptions {
+  message?: string
+  cause?: unknown
+}
+
+export class AdminRolesError extends Error {
+  public readonly code: AdminRolesErrorCode
+
+  constructor(code: AdminRolesErrorCode, options: { message: string; cause?: unknown }) {
+    super(options.message, options.cause != null ? { cause: options.cause } : undefined)
+    this.name = 'AdminRolesError'
+    this.code = code
+  }
+}
+
+const make =
+  (code: AdminRolesErrorCode, defaultMessage: string) =>
+  (options?: AdminRolesErrorOptions): AdminRolesError =>
+    new AdminRolesError(code, {
+      message: options?.message ?? defaultMessage,
+      cause: options?.cause,
+    })
+
+/** The referenced admin role id does not exist. */
+export const ERR_ADMIN_ROLE_NOT_FOUND = make(AdminRolesErrorCodes.NOT_FOUND, 'admin role not found')
+
+/** Creating a role conflicts with an existing `machine_name`. */
+export const ERR_ADMIN_ROLE_MACHINE_NAME_IN_USE = make(
+  AdminRolesErrorCodes.MACHINE_NAME_IN_USE,
+  'machine name already in use'
+)
+
+/**
+ * The stored `vid` does not match the client-supplied `expectedVid` —
+ * the caller is holding a stale version of the row. Typical admin-UI
+ * response is to reload the edit form with the current values.
+ */
+export const ERR_ADMIN_ROLE_VERSION_CONFLICT = make(
+  AdminRolesErrorCodes.VERSION_CONFLICT,
+  'admin role has been modified elsewhere — please reload and try again'
+)
+
+/**
+ * The admin user targeted by a role-assignment operation does not exist.
+ * Module-local rather than reaching into `@byline/admin/admin-users`'
+ * error codes — keeps the modules decoupled.
+ */
+export const ERR_ADMIN_ROLE_USER_NOT_FOUND = make(
+  AdminRolesErrorCodes.USER_NOT_FOUND,
+  'admin user not found'
+)

package/src/modules/admin-roles/index.ts

@@ -0,0 +1,81 @@
+/**
+ * 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
+ */
+
+/**
+ * `@byline/admin/admin-roles` — role CRUD, reorder, and role ↔ user
+ * assignment.
+ *
+ * Exports the adapter-facing `AdminRolesRepository` contract, ability
+ * keys, transport-agnostic commands, the `AdminRolesService`, and the
+ * module's error types. Commands are the recommended entry point for
+ * any caller; the service is exposed for internal uses (other services,
+ * future seeds) that want to skip Zod/ability overhead.
+ *
+ * Per-role ability grants live on the sibling
+ * `@byline/admin/admin-permissions` module, not here.
+ */
+
+export {
+  ADMIN_ROLES_ABILITIES,
+  type AdminRolesAbilityKey,
+  registerAdminRolesAbilities,
+} from './abilities.js'
+export {
+  createAdminRoleCommand,
+  deleteAdminRoleCommand,
+  getAdminRoleCommand,
+  getRolesForUserCommand,
+  listAdminRolesCommand,
+  reorderAdminRolesCommand,
+  setRolesForUserCommand,
+  updateAdminRoleCommand,
+} from './commands.js'
+export { toAdminRole } from './dto.js'
+export {
+  AdminRolesError,
+  type AdminRolesErrorCode,
+  AdminRolesErrorCodes,
+  ERR_ADMIN_ROLE_MACHINE_NAME_IN_USE,
+  ERR_ADMIN_ROLE_NOT_FOUND,
+  ERR_ADMIN_ROLE_USER_NOT_FOUND,
+  ERR_ADMIN_ROLE_VERSION_CONFLICT,
+} from './errors.js'
+export {
+  adminRoleListResponseSchema,
+  adminRoleResponseSchema,
+  createAdminRoleRequestSchema,
+  deleteAdminRoleRequestSchema,
+  getAdminRoleRequestSchema,
+  getRolesForUserRequestSchema,
+  listAdminRolesRequestSchema,
+  reorderAdminRolesRequestSchema,
+  setRolesForUserRequestSchema,
+  updateAdminRoleRequestSchema,
+  userRolesResponseSchema,
+} from './schemas.js'
+export { AdminRolesService } from './service.js'
+export type { AdminRolesCommandDeps } from './commands.js'
+export type {
+  AdminRoleRow,
+  AdminRolesRepository,
+  CreateAdminRoleInput,
+  UpdateAdminRoleInput,
+} from './repository.js'
+export type {
+  AdminRoleListResponse,
+  AdminRoleResponse,
+  CreateAdminRoleRequest,
+  DeleteAdminRoleRequest,
+  GetAdminRoleRequest,
+  GetRolesForUserRequest,
+  ListAdminRolesRequest,
+  ReorderAdminRolesRequest,
+  SetRolesForUserRequest,
+  UpdateAdminRoleRequest,
+  UserRolesResponse,
+} from './schemas.js'

package/src/modules/admin-roles/repository.ts

@@ -0,0 +1,96 @@
+/**
+ * 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
+ */
+
+/**
+ * `AdminRolesRepository` — role CRUD plus role ↔ user assignments.
+ *
+ * Deliberately does *not* cover per-role ability grants — those live on
+ * `AdminPermissionsRepository` (`modules/admin-permissions/repository.ts`),
+ * which owns the `byline_admin_permissions` table. The split follows the
+ * admin UI: role identity and membership live together; ability grants
+ * are a separate editor surface driven by the ability registry.
+ *
+ * **Optimistic concurrency.** `update`, `delete`, and `reorder` take an
+ * `expectedVid` and bump the stored `vid` on success. Adapters throw
+ * `AdminRolesError(VERSION_CONFLICT)` when the stored vid differs from
+ * the expected one — typical client response is to reload the form.
+ *
+ * `machine_name` is **immutable post-create**. The `UpdateAdminRoleInput`
+ * type omits it deliberately so renaming the slug is a deliberate
+ * separate operation if it ever ships.
+ */
+
+export interface AdminRoleRow {
+  id: string
+  vid: number
+  name: string
+  machine_name: string
+  description: string | null
+  order: number
+  created_at: Date
+  updated_at: Date
+}
+
+export interface CreateAdminRoleInput {
+  name: string
+  machine_name: string
+  description?: string | null
+  order?: number
+}
+
+export interface UpdateAdminRoleInput {
+  name?: string
+  description?: string | null
+  order?: number
+}
+
+export interface AdminRolesRepository {
+  create(input: CreateAdminRoleInput): Promise<AdminRoleRow>
+  getById(id: string): Promise<AdminRoleRow | null>
+  getByMachineName(machineName: string): Promise<AdminRoleRow | null>
+  /** Roles ordered by their `order` column then `created_at`. No paging — the list is small by design. */
+  list(): Promise<AdminRoleRow[]>
+  /**
+   * Content update with optimistic concurrency. Throws
+   * `AdminRolesError(VERSION_CONFLICT)` if the stored `vid` differs from
+   * `expectedVid`. Bumps `vid` on success and returns the fresh row.
+   */
+  update(id: string, expectedVid: number, patch: UpdateAdminRoleInput): Promise<AdminRoleRow>
+  /**
+   * Delete with optimistic concurrency. Version-gated on `expectedVid` to
+   * prevent races against a concurrent update.
+   */
+  delete(id: string, expectedVid: number): Promise<void>
+  /**
+   * Bulk reorder. The provided `ids` array fixes the new `order` value
+   * for each role to its index in the array. Runs in a single
+   * transaction. Roles not present in `ids` are left untouched.
+   *
+   * Vid-less by design — reorder mutates only the `order` column and
+   * the UX shape is always "drag, then save the whole list", which would
+   * pointlessly conflict with concurrent edits to other fields. Last
+   * writer on the order column wins.
+   */
+  reorder(ids: string[]): Promise<void>
+
+  /** Assign a role to a user. Idempotent via the composite primary key. */
+  assignToUser(roleId: string, userId: string): Promise<void>
+  unassignFromUser(roleId: string, userId: string): Promise<void>
+  listRolesForUser(userId: string): Promise<AdminRoleRow[]>
+  listUsersForRole(roleId: string): Promise<string[]>
+  /**
+   * Replace the role-set for a user wholesale. Runs in a single
+   * transaction so the user is never observed mid-edit. Vid-less by
+   * design — assignments live in the join table, not on the user row,
+   * and the editor UX is "drag, save the whole list" rather than
+   * field-level concurrency. Caller is responsible for validating that
+   * `userId` and every `roleId` exist; the repo trusts its inputs and
+   * lets the FK constraint surface as the ultimate backstop.
+   */
+  setRolesForUser(userId: string, roleIds: readonly string[]): Promise<void>
+}

package/src/modules/admin-roles/schemas.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 { uuidSchema } from '@byline/core/validation'
+import { z } from 'zod'
+
+/**
+ * Zod request/response schemas for the admin-roles commands.
+ *
+ * `vid` gates writes for optimistic concurrency; `machine_name` is
+ * accepted only at create time and validated as a slug-shaped string.
+ *
+ * Reorder takes the full ordered id list — the index in the array
+ * becomes each role's new `order` value. The list-view UX is "drag,
+ * then save the whole order" so a partial-update payload would add no
+ * value and complicate atomicity.
+ */
+
+// ---------------------------------------------------------------------------
+// Field-level schemas
+// ---------------------------------------------------------------------------
+
+const idSchema = uuidSchema
+
+const vidSchema = z
+  .number({ message: 'vid is required' })
+  .int({ message: 'vid must be an integer' })
+  .positive({ message: 'vid must be positive' })
+
+const nameSchema = z.string().min(1).max(128)
+
+const machineNameSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9][a-z0-9_-]*$/, {
+    message: 'machine_name may contain lowercase letters, numbers, hyphens, and underscores only',
+  })
+
+const descriptionSchema = z.string().max(2000).nullish()
+
+const orderSchema = z.number().int().min(0)
+
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+
+export const listAdminRolesRequestSchema = z.object({}).optional()
+export type ListAdminRolesRequest = z.infer<typeof listAdminRolesRequestSchema>
+
+export const getAdminRoleRequestSchema = z.object({
+  id: idSchema,
+})
+export type GetAdminRoleRequest = z.infer<typeof getAdminRoleRequestSchema>
+
+export const createAdminRoleRequestSchema = z.object({
+  name: nameSchema,
+  machine_name: machineNameSchema,
+  description: descriptionSchema,
+  order: orderSchema.optional(),
+})
+export type CreateAdminRoleRequest = z.infer<typeof createAdminRoleRequestSchema>
+
+export const updateAdminRoleRequestSchema = z.object({
+  id: idSchema,
+  vid: vidSchema,
+  patch: z
+    .object({
+      name: nameSchema.optional(),
+      description: descriptionSchema,
+      order: orderSchema.optional(),
+    })
+    .refine((p) => Object.keys(p).length > 0, { message: 'patch cannot be empty' }),
+})
+export type UpdateAdminRoleRequest = z.infer<typeof updateAdminRoleRequestSchema>
+
+export const deleteAdminRoleRequestSchema = z.object({
+  id: idSchema,
+  vid: vidSchema,
+})
+export type DeleteAdminRoleRequest = z.infer<typeof deleteAdminRoleRequestSchema>
+
+export const reorderAdminRolesRequestSchema = z.object({
+  ids: z.array(idSchema).min(1, { message: 'at least one id is required' }),
+})
+export type ReorderAdminRolesRequest = z.infer<typeof reorderAdminRolesRequestSchema>
+
+export const getRolesForUserRequestSchema = z.object({
+  userId: idSchema,
+})
+export type GetRolesForUserRequest = z.infer<typeof getRolesForUserRequestSchema>
+
+export const setRolesForUserRequestSchema = z.object({
+  userId: idSchema,
+  roleIds: z.array(idSchema),
+})
+export type SetRolesForUserRequest = z.infer<typeof setRolesForUserRequestSchema>
+
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+
+export const adminRoleResponseSchema = z.object({
+  id: z.string(),
+  vid: z.number().int(),
+  name: z.string(),
+  machine_name: z.string(),
+  description: z.string().nullable(),
+  order: z.number().int(),
+  created_at: z.date(),
+  updated_at: z.date(),
+})
+export type AdminRoleResponse = z.infer<typeof adminRoleResponseSchema>
+
+export const adminRoleListResponseSchema = z.object({
+  roles: z.array(adminRoleResponseSchema),
+})
+export type AdminRoleListResponse = z.infer<typeof adminRoleListResponseSchema>
+
+/**
+ * User-roles editor payload. `userId` is echoed back so the caller can
+ * match async writes; `roles` is the authoritative role-set after the
+ * write, shaped as full role rows so the drawer renders names without a
+ * second fetch.
+ */
+export const userRolesResponseSchema = z.object({
+  userId: z.string(),
+  roles: z.array(adminRoleResponseSchema),
+})
+export type UserRolesResponse = z.infer<typeof userRolesResponseSchema>
+
+/** Empty response for void-returning mutations (delete, reorder). */
+export const okResponseSchema = z.object({ ok: z.literal(true) })
+export type OkResponse = z.infer<typeof okResponseSchema>