@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/modules/staff/api/timesheets/tags/access.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared access filtering for the two tag-assignment endpoints (T3.4).
+ *
+ * Tagging a task or a time entry is a write on a project-scoped row, so it goes
+ * through the same resolver every other project-scoped read and write uses: a
+ * caller without `staff.timesheets.projects.manage` only reaches the projects
+ * they are an active member of. Skipping the resolver here would let anyone with
+ * `tasks.manage` tag a task on a project they cannot even see — that is the R3
+ * defect class, and it is why the target lookup below is never done without it.
+ *
+ * The refusal is a flat 404 with a generic message. "Not yours" and "does not
+ * exist" are deliberately indistinguishable, so the endpoint cannot be used to
+ * probe which task or entry ids exist.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { StaffTimeEntry, StaffTimeTask } from '../../../data/entities'
+import { MANAGE_PROJECTS_FEATURE, resolveProjectAccess, type ProjectAccess } from '../../../lib/time-tracking/access'
+import { resolveFeatureAccess } from '../../../lib/time-tracking/featureAccess'
+import { readTimeTrackingSettings } from '../../../lib/time-tracking/settings'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/tags' })
+
+const DENIED_ACCESS: ProjectAccess = { canManageAll: false, projectIds: [], staffMemberId: null }
+
+export type ContainerLike = { resolve: (name: string) => unknown }
+
+export type TagAssignmentScope = {
+  tenantId: string
+  organizationId: string
+  userId: string
+}
+
+async function resolveAssignmentGraceDays(container: ContainerLike, tenantId: string): Promise<number | null> {
+  try {
+    const configService = container.resolve('moduleConfigService') as ModuleConfigService
+    const settings = await readTimeTrackingSettings(configService, { tenantId })
+    return settings.access.assignmentGraceDays
+  } catch {
+    // Fail safe to the documented default rather than widening the window.
+    return null
+  }
+}
+
+export async function loadTagProjectAccess(
+  container: ContainerLike,
+  scope: TagAssignmentScope,
+): Promise<ProjectAccess> {
+  try {
+    // One lookup, one authority, one failure direction. The hand-rolled grant read
+    // this replaces could not tell "denied" from "could not ask", so an RBAC hiccup
+    // silently demoted a manager to their own memberships.
+    const access = await resolveFeatureAccess(container, scope.userId, [MANAGE_PROJECTS_FEATURE], {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+    })
+    const em = container.resolve('em') as EntityManager
+    return await resolveProjectAccess({
+      em: em.fork(),
+      userId: scope.userId,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      canManageAll: access.allowed,
+      userFeatures: access.grantedFeatures,
+      assignmentGraceDays: await resolveAssignmentGraceDays(container, scope.tenantId),
+    })
+  } catch (err) {
+    logger.error('staff.timesheets.tags access resolution failed', { err })
+    return { ...DENIED_ACCESS }
+  }
+}
+
+function targetNotFound(translate: (key: string, fallback: string) => string, target: 'task' | 'time_entry'): CrudHttpError {
+  const message =
+    target === 'task'
+      ? translate('staff.time_tracking.tags.errors.taskNotFound', 'Task not found or not accessible.')
+      : translate('staff.time_tracking.tags.errors.entryNotFound', 'Time entry not found or not accessible.')
+  return new CrudHttpError(404, { error: message })
+}
+
+/**
+ * Loads the task inside the caller's tenant/organization AND inside the projects
+ * the resolver grants them. Both misses answer the same 404.
+ */
+export async function requireAccessibleTask(
+  em: EntityManager,
+  taskId: string,
+  scope: TagAssignmentScope,
+  access: ProjectAccess,
+  translate: (key: string, fallback: string) => string,
+): Promise<{ id: string; timeProjectId: string }> {
+  const task = await em.findOne(StaffTimeTask, {
+    id: taskId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+  })
+  if (!task) throw targetNotFound(translate, 'task')
+  if (!access.canManageAll && !access.projectIds.includes(task.timeProjectId)) {
+    throw targetNotFound(translate, 'task')
+  }
+  return { id: task.id, timeProjectId: task.timeProjectId }
+}
+
+/**
+ * Same rule for a time entry, with one extra branch: an entry that carries no
+ * project is personal time, reachable only by the member who logged it (or by a
+ * manager).
+ */
+export async function requireAccessibleTimeEntry(
+  em: EntityManager,
+  timeEntryId: string,
+  scope: TagAssignmentScope,
+  access: ProjectAccess,
+  translate: (key: string, fallback: string) => string,
+): Promise<{ id: string; timeProjectId: string | null }> {
+  const entry = await em.findOne(StaffTimeEntry, {
+    id: timeEntryId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+  })
+  if (!entry) throw targetNotFound(translate, 'time_entry')
+  if (!access.canManageAll) {
+    const projectId = entry.timeProjectId ?? null
+    const reachable = projectId
+      ? access.projectIds.includes(projectId)
+      : access.staffMemberId != null && entry.staffMemberId === access.staffMemberId
+    if (!reachable) throw targetNotFound(translate, 'time_entry')
+  }
+  return { id: entry.id, timeProjectId: entry.timeProjectId ?? null }
+}

package/src/modules/staff/api/timesheets/tags/entry-assignments/route.ts

@@ -0,0 +1,290 @@
+/**
+ * Time entry tag assignment (T3.4) — the tag list of the entry form on screen 8
+ * and the badges the entries list of screen 10 renders.
+ *
+ * Mirrors the task endpoint: `POST` adds, `DELETE` removes, both idempotent, and
+ * both filter through `resolveProjectAccess` before the entry is even loaded. An
+ * entry frozen in a closed report is refused by the command with `409`.
+ */
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { emitStaffEvent } from '../../../../events'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runTimesheetInterceptors } from '../../_shared/withTimesheetInterceptors'
+import {
+  staffTimeEntryTagAssignmentSchema,
+  type StaffTimeEntryTagAssignmentInput,
+} from '../../../../data/validators'
+import { staffTimeTagCommandIds } from '../../../../commands/timesheets-tags'
+import {
+  STAFF_TIME_TRACKING_RESOURCE_KINDS,
+  runStaffMutationGuardAfterSuccess,
+  runStaffMutationGuards,
+} from '../../../guards'
+import { loadTagProjectAccess, requireAccessibleTimeEntry, type TagAssignmentScope } from '../access'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/tags/entry-assignments' })
+
+const RESOURCE_KIND = STAFF_TIME_TRACKING_RESOURCE_KINDS.entryTag
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['staff.timesheets.tasks.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['staff.timesheets.tasks.manage'] },
+}
+
+const assignResponseSchema = z.object({
+  timeEntryId: z.string().uuid(),
+  tagIds: z.array(z.string().uuid()),
+  assignedTagIds: z.array(z.string().uuid()),
+  alreadyAssignedTagIds: z.array(z.string().uuid()),
+})
+
+const unassignResponseSchema = z.object({
+  timeEntryId: z.string().uuid(),
+  tagIds: z.array(z.string().uuid()),
+  removedTagIds: z.array(z.string().uuid()),
+  notAssignedTagIds: z.array(z.string().uuid()),
+})
+
+type AssignmentResult = {
+  targetId: string
+  assignedTagIds: string[]
+  alreadyAssignedTagIds: string[]
+  tagIds: string[]
+}
+
+type UnassignmentResult = {
+  targetId: string
+  removedTagIds: string[]
+  notAssignedTagIds: string[]
+  tagIds: string[]
+}
+
+async function buildContext(
+  req: Request,
+): Promise<{ ctx: CommandRuntimeContext; translate: (key: string, fallback?: string) => string }> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth) throw new CrudHttpError(401, { error: translate('staff.errors.unauthorized', 'Unauthorized') })
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const ctx: CommandRuntimeContext = {
+    container,
+    auth,
+    organizationScope: scope,
+    selectedOrganizationId: scope?.selectedId ?? auth.orgId ?? null,
+    organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+    request: req,
+  }
+  return { ctx, translate }
+}
+
+function requireAssignmentScope(
+  ctx: CommandRuntimeContext,
+  translate: (key: string, fallback?: string) => string,
+): TagAssignmentScope {
+  const tenantId = ctx.auth?.tenantId ?? null
+  const organizationId = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+  const userId = ctx.auth?.sub ?? null
+  if (!tenantId || !organizationId || !userId) {
+    throw new CrudHttpError(400, {
+      error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.'),
+    })
+  }
+  return { tenantId, organizationId, userId }
+}
+
+async function handle(req: Request, commandId: string, operation: 'create' | 'delete'): Promise<Response> {
+  const { ctx, translate } = await buildContext(req)
+  const scope = requireAssignmentScope(ctx, translate)
+
+  const interceptors = await runTimesheetInterceptors({
+    request: req,
+    method: operation === 'create' ? 'POST' : 'DELETE',
+    scope: {
+      container: ctx.container,
+      userId: scope.userId,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+    },
+    body: await readJsonSafe<Record<string, unknown>>(req, {}),
+  })
+  if (!interceptors.ok) return interceptors.response
+  const { session } = interceptors
+
+  const input = parseScopedCommandInput(staffTimeEntryTagAssignmentSchema, session.body, ctx, translate)
+
+  const access = await loadTagProjectAccess(ctx.container, scope)
+  const em = (ctx.container.resolve('em') as EntityManager).fork()
+  await requireAccessibleTimeEntry(em, input.timeEntryId, scope, access, translate)
+
+  const guardResult = await runStaffMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: RESOURCE_KIND,
+      resourceId: input.timeEntryId,
+      operation,
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: input,
+    },
+  )
+  if (!guardResult.ok) {
+    return NextResponse.json(guardResult.errorBody ?? { error: 'Operation blocked by guard' }, {
+      status: guardResult.errorStatus ?? 422,
+    })
+  }
+
+  const commandBus = ctx.container.resolve('commandBus') as CommandBus
+  const { result, logEntry } = await commandBus.execute<
+    StaffTimeEntryTagAssignmentInput,
+    AssignmentResult | UnassignmentResult
+  >(commandId, { input, ctx })
+
+  if (guardResult.afterSuccessCallbacks.length) {
+    await runStaffMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: RESOURCE_KIND,
+      resourceId: input.timeEntryId,
+      operation,
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
+  }
+
+  // A tag write is a change to the entry itself, so it travels as the entry's own
+  // `updated` event rather than an assignment-shaped one no subscriber knows about.
+  void emitStaffEvent('staff.timesheets.time_entry.updated', {
+    id: input.timeEntryId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  }, { persistent: true }).catch((err) => {
+    logger.error('staff.timesheets emit time_entry.updated failed', { err })
+  })
+
+  const assignment = result as AssignmentResult | undefined
+  const unassignment = result as UnassignmentResult | undefined
+  const payload =
+    operation === 'create'
+      ? {
+          timeEntryId: input.timeEntryId,
+          tagIds: assignment?.tagIds ?? [],
+          assignedTagIds: assignment?.assignedTagIds ?? [],
+          alreadyAssignedTagIds: assignment?.alreadyAssignedTagIds ?? [],
+        }
+      : {
+          timeEntryId: input.timeEntryId,
+          tagIds: unassignment?.tagIds ?? [],
+          removedTagIds: unassignment?.removedTagIds ?? [],
+          notAssignedTagIds: unassignment?.notAssignedTagIds ?? [],
+        }
+
+  const response = await session.respond(200, payload)
+  if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
+    response.headers.set(
+      'x-om-operation',
+      serializeOperationMetadata({
+        id: logEntry.id,
+        undoToken: logEntry.undoToken,
+        commandId: logEntry.commandId,
+        actionLabel: logEntry.actionLabel ?? null,
+        resourceKind: logEntry.resourceKind ?? RESOURCE_KIND,
+        resourceId: logEntry.resourceId ?? input.timeEntryId,
+        executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString() : undefined,
+      }),
+    )
+  }
+  return response
+}
+
+async function errorResponse(err: unknown, message: string): Promise<Response> {
+  if (isCrudHttpError(err)) {
+    return NextResponse.json(err.body, { status: err.status })
+  }
+  const { translate } = await resolveTranslations()
+  if (err instanceof z.ZodError) {
+    return NextResponse.json(
+      { error: translate('staff.errors.invalid_request', 'Invalid request'), details: err.issues },
+      { status: 400 },
+    )
+  }
+  logger.error(message, { err })
+  return NextResponse.json({ error: translate('staff.errors.internal', 'Internal server error') }, { status: 500 })
+}
+
+export async function POST(req: Request) {
+  try {
+    return await handle(req, staffTimeTagCommandIds.assignEntry, 'create')
+  } catch (err) {
+    const interceptorRejection = getCommandInterceptorHttpRejection(err)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    return errorResponse(err, 'staff.timesheets.tags.entry-assignments.POST failed')
+  }
+}
+
+export async function DELETE(req: Request) {
+  try {
+    return await handle(req, staffTimeTagCommandIds.unassignEntry, 'delete')
+  } catch (err) {
+    const interceptorRejection = getCommandInterceptorHttpRejection(err)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    return errorResponse(err, 'staff.timesheets.tags.entry-assignments.DELETE failed')
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Time entry tag assignments',
+  methods: {
+    POST: {
+      summary: 'Assign tags to a time entry',
+      description:
+        'Adds tags to a time entry. Idempotent — a tag the entry already carries comes back in alreadyAssignedTagIds. Refused with 404 when the entry is outside the caller\'s project access, and with 409 when it is locked in a closed report.',
+      requestBody: { contentType: 'application/json', schema: staffTimeEntryTagAssignmentSchema },
+      responses: [{ status: 200, description: 'Tags assigned', schema: assignResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid payload or missing organization scope' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.tasks.manage' },
+        { status: 404, description: 'Time entry not found or not accessible' },
+        { status: 409, description: 'Time entry locked in a closed report' },
+        { status: 422, description: 'Unknown tag ids' },
+      ],
+    },
+    DELETE: {
+      summary: 'Unassign tags from a time entry',
+      description:
+        'Removes tags from a time entry. Idempotent — a tag the entry does not carry comes back in notAssignedTagIds.',
+      requestBody: { contentType: 'application/json', schema: staffTimeEntryTagAssignmentSchema },
+      responses: [{ status: 200, description: 'Tags unassigned', schema: unassignResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid payload or missing organization scope' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.tasks.manage' },
+        { status: 404, description: 'Time entry not found or not accessible' },
+        { status: 409, description: 'Time entry locked in a closed report' },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/tags/route.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { staffTimeTagCrudEvents } from '../../../lib/crud'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { StaffTimeTag } from '../../../data/entities'
+import { staffTimeTagCreateSchema } from '../../../data/validators'
+import { staffTimeTagCommandIds, staffTimeTagUpdateSchema } from '../../../commands/timesheets-tags'
+import { sanitizeSearchTerm } from '../../helpers'
+import { createStaffCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from '../../openapi'
+
+const F = {
+  id: 'id',
+  tenant_id: 'tenant_id',
+  organization_id: 'organization_id',
+  slug: 'slug',
+  label: 'label',
+  color: 'color',
+  created_at: 'created_at',
+  updated_at: 'updated_at',
+} as const
+
+/**
+ * Tags are org-wide vocabulary shared by the board (screen 6), the task drawer
+ * (screen 7) and the time entry form (screens 8 and 10). Everyone who can open a
+ * timesheet needs to read the list to render a badge, while maintaining the
+ * vocabulary belongs with task management — hence `timesheets.view` to read and
+ * `tasks.manage` to write.
+ *
+ * No `runRouteMutationGuards` here on purpose: every write goes through the
+ * command bus via the factory's `actions`, which is already the guard wiring.
+ */
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['staff.timesheets.view'] },
+  POST: { requireAuth: true, requireFeatures: ['staff.timesheets.tasks.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['staff.timesheets.tasks.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['staff.timesheets.tasks.manage'] },
+}
+
+export const metadata = routeMetadata
+
+const rawBodySchema = z.object({}).passthrough()
+
+const listSchema = z
+  .object({
+    page: z.coerce.number().min(1).default(1),
+    pageSize: z.coerce.number().min(1).max(100).default(50),
+    q: z.string().optional(),
+    ids: z.string().optional(),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+  })
+  .passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: StaffTimeTag,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  events: staffTimeTagCrudEvents,
+  indexer: { entityType: 'staff:staff_time_tag' },
+  list: {
+    schema: listSchema,
+    entityId: 'staff:staff_time_tag',
+    fields: [F.id, F.organization_id, F.tenant_id, F.slug, F.label, F.color, F.created_at, F.updated_at],
+    // Tag pickers read alphabetically; a chip list has no other natural order.
+    defaultSort: { field: F.label, dir: 'asc' },
+    sortFieldMap: {
+      label: F.label,
+      slug: F.slug,
+      createdAt: F.created_at,
+      updatedAt: F.updated_at,
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      if (typeof query.ids === 'string' && query.ids.trim().length > 0) {
+        const ids = query.ids
+          .split(',')
+          .map((value) => value.trim())
+          .filter((value) => value.length > 0)
+        if (ids.length > 0) filters[F.id] = { $in: ids }
+      }
+      const term = sanitizeSearchTerm(query.q)
+      if (term) {
+        filters[F.label] = { $ilike: `%${escapeLikePattern(term)}%` }
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: staffTimeTagCommandIds.create,
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(staffTimeTagCreateSchema, raw ?? {}, ctx, translate)
+      },
+      response: ({ result }) => ({ id: result?.tagId ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: staffTimeTagCommandIds.update,
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(staffTimeTagUpdateSchema, raw ?? {}, ctx, translate)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: staffTimeTagCommandIds.delete,
+      schema: rawBodySchema,
+      mapInput: async ({ parsed, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const id = resolveCrudRecordId(parsed, ctx, translate)
+        return { id }
+      },
+      // Deleting a tag cascades to its assignments; the counts travel back so the
+      // caller sees how far the badge disappeared.
+      response: ({ result }) => ({
+        ok: true,
+        removedTaskAssignments: result?.removedTaskAssignments ?? 0,
+        removedEntryAssignments: result?.removedEntryAssignments ?? 0,
+      }),
+    },
+  },
+})
+
+export const GET = crud.GET
+export const POST = crud.POST
+export const PUT = crud.PUT
+export const DELETE = crud.DELETE
+
+export const tagListItemSchema = z.object({
+  id: z.string().uuid().nullable().optional(),
+  organization_id: z.string().uuid().nullable().optional(),
+  tenant_id: z.string().uuid().nullable().optional(),
+  slug: z.string().nullable().optional(),
+  label: z.string().nullable().optional(),
+  color: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+const tagDeleteResponseSchema = z.object({
+  ok: z.literal(true),
+  removedTaskAssignments: z.number().int(),
+  removedEntryAssignments: z.number().int(),
+})
+
+export const openApi = createStaffCrudOpenApi({
+  resourceName: 'TimeTag',
+  pluralName: 'Time Tags',
+  querySchema: listSchema,
+  listResponseSchema: createPagedListResponseSchema(tagListItemSchema),
+  create: {
+    schema: staffTimeTagCreateSchema,
+    description:
+      'Creates a time tracking tag. The slug is unique per organization and tenant; a collision answers 409 with fieldErrors.slug.',
+  },
+  update: {
+    schema: staffTimeTagUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Renames, re-slugs or recolours a tag. A slug collision answers 409 with fieldErrors.slug.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: tagDeleteResponseSchema,
+    description:
+      'Soft-deletes a tag and removes every task and time entry assignment it had, reporting how many of each were removed.',
+  },
+})