@open-mercato/core 0.6.6-develop.6153.1.b4c555b820 → 0.6.6-develop.6156.1.5ac693a69a

package/src/modules/messages/api/[id]/conversation/read/route.ts

@@ -2,6 +2,7 @@ import type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
 import { attachOperationMetadataHeader } from '../../../../lib/operationMetadata'
 import { resolveMessageContext } from '../../../../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from '../../../guards'
 import {
   conversationMutationResponseSchema,
   errorResponseSchema,
@@ -15,6 +16,28 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
   const { ctx, scope } = await resolveMessageContext(req)
   const commandBus = ctx.container.resolve('commandBus') as CommandBus
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.conversation',
+      resourceId: params.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: null,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   try {
     const { result, logEntry } = await commandBus.execute('messages.conversation.mark_unread_for_actor', {
       input: {
@@ -38,6 +61,16 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
       resourceKind: 'messages.conversation',
       resourceId: params.id,
     })
+    await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.conversation',
+      resourceId: params.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
     return response
   } catch (error) {
     if (error instanceof Error) {

package/src/modules/messages/api/[id]/conversation/route.ts

@@ -2,6 +2,7 @@ import type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
 import { attachOperationMetadataHeader } from '../../../lib/operationMetadata'
 import { resolveMessageContext } from '../../../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from '../../guards'
 import {
   conversationMutationResponseSchema,
   errorResponseSchema,
@@ -15,6 +16,28 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
   const { ctx, scope } = await resolveMessageContext(req)
   const commandBus = ctx.container.resolve('commandBus') as CommandBus
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.conversation',
+      resourceId: params.id,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: null,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   try {
     const { result, logEntry } = await commandBus.execute('messages.conversation.delete_for_actor', {
       input: {
@@ -38,6 +61,16 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
       resourceKind: 'messages.conversation',
       resourceId: params.id,
     })
+    await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.conversation',
+      resourceId: params.id,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
     return response
   } catch (error) {
     if (error instanceof Error) {

package/src/modules/messages/api/[id]/forward/route.ts

@@ -2,6 +2,7 @@ import type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'
 import { forwardMessageSchema } from '../../../data/validators'
 import { attachOperationMetadataHeader, OperationLogEntryLike } from '../../../lib/operationMetadata'
 import { canUseMessageEmailFeature, parseRequestBodySafe, resolveMessageContext } from '../../../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from '../../guards'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
 import { forwardResponseSchema, forwardMessageSchema as forwardSchema } from '../../openapi'
 import { MessageCommandExecuteResult } from '../../../commands/shared'
@@ -19,6 +20,28 @@ export async function POST(req: Request, { params }: { params: { id: string } })
     return Response.json({ error: 'Missing feature: messages.email' }, { status: 403 })
   }
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: null,
+      operation: 'create',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: input as Record<string, unknown>,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   let commandResult: { result: MessageCommandExecuteResult; logEntry: unknown }
   try {
     commandResult = await commandBus.execute<unknown, MessageCommandExecuteResult>('messages.messages.forward', {
@@ -62,6 +85,16 @@ export async function POST(req: Request, { params }: { params: { id: string } })
     resourceKind: 'messages.message',
     resourceId: newMessageId,
   })
+  await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId,
+    resourceKind: 'messages.message',
+    resourceId: newMessageId,
+    operation: 'create',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  })
   return response
 }
 

package/src/modules/messages/api/[id]/read/route.ts

@@ -5,6 +5,7 @@ import { Message, MessageRecipient } from '../../../data/entities'
 import { attachOperationMetadataHeader } from '../../../lib/operationMetadata'
 import { hasOrganizationAccess, resolveMessageContext } from '../../../lib/routeHelpers'
 import type { MessageScope } from '../../../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from '../../guards'
 import { errorResponseSchema, okResponseSchema } from '../../openapi'
 
 export const metadata = {
@@ -56,6 +57,27 @@ export async function PUT(req: Request, { params }: { params: { id: string } })
   if ('response' in context) return context.response
   const { ctx, scope } = context
   const commandBus = ctx.container.resolve('commandBus') as CommandBus
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: params.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: null,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
   const { logEntry } = await commandBus.execute('messages.recipients.mark_read', {
     input: {
       messageId: params.id,
@@ -78,6 +100,16 @@ export async function PUT(req: Request, { params }: { params: { id: string } })
     resourceKind: 'messages.message',
     resourceId: params.id,
   })
+  await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId,
+    resourceKind: 'messages.message',
+    resourceId: params.id,
+    operation: 'update',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  })
   return response
 }
 
@@ -86,6 +118,27 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
   if ('response' in context) return context.response
   const { ctx, scope } = context
   const commandBus = ctx.container.resolve('commandBus') as CommandBus
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: params.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: null,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
   const { logEntry } = await commandBus.execute('messages.recipients.mark_unread', {
     input: {
       messageId: params.id,
@@ -108,6 +161,16 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
     resourceKind: 'messages.message',
     resourceId: params.id,
   })
+  await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId,
+    resourceKind: 'messages.message',
+    resourceId: params.id,
+    operation: 'update',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  })
   return response
 }
 

package/src/modules/messages/api/[id]/reply/route.ts

@@ -3,6 +3,7 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
 import { replyMessageSchema } from '../../../data/validators'
 import { attachOperationMetadataHeader } from '../../../lib/operationMetadata'
 import { canUseMessageEmailFeature, resolveMessageContext } from '../../../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from '../../guards'
 import {
   errorResponseSchema,
   forwardResponseSchema,
@@ -23,6 +24,28 @@ export async function POST(req: Request, { params }: { params: { id: string } })
     return Response.json({ error: 'Missing feature: messages.email' }, { status: 403 })
   }
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: null,
+      operation: 'create',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: input as Record<string, unknown>,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   let commandResult
   try {
     commandResult = await commandBus.execute<unknown, MessageCommandExecuteResult>('messages.messages.reply', {
@@ -66,6 +89,16 @@ export async function POST(req: Request, { params }: { params: { id: string } })
     resourceKind: 'messages.message',
     resourceId: messageId,
   })
+  await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId,
+    resourceKind: 'messages.message',
+    resourceId: messageId,
+    operation: 'create',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  })
   return response
 }
 

package/src/modules/messages/api/[id]/route.ts

@@ -10,6 +10,7 @@ import { getMessageObjectType } from '../../lib/message-objects-registry'
 import { getMessageTypeOrDefault } from '../../lib/message-types-registry'
 import { attachOperationMetadataHeader } from '../../lib/operationMetadata'
 import { hasOrganizationAccess, resolveMessageContext } from '../../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from '../guards'
 import {
   errorResponseSchema,
   messageDetailResponseSchema,
@@ -275,6 +276,28 @@ export async function PATCH(req: Request, { params }: { params: { id: string } }
     return Response.json({ error: 'Only draft messages can be edited' }, { status: 409 })
   }
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: message.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: input as Record<string, unknown>,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   try {
     const { logEntry } = await commandBus.execute('messages.messages.update_draft', {
       input: {
@@ -299,6 +322,16 @@ export async function PATCH(req: Request, { params }: { params: { id: string } }
       resourceKind: 'messages.message',
       resourceId: message.id,
     })
+    await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: message.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
     return response
   } catch (error) {
     if (error instanceof Error) {
@@ -336,6 +369,28 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
     return Response.json({ error: 'Access denied' }, { status: 403 })
   }
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: params.id,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: null,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   try {
     const { logEntry } = await commandBus.execute('messages.messages.delete_for_actor', {
       input: {
@@ -359,6 +414,16 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
       resourceKind: 'messages.message',
       resourceId: params.id,
     })
+    await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: params.id,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
     return response
   } catch (error) {
     if (error instanceof Error && error.message === 'Access denied') {

package/src/modules/messages/api/guards.ts

@@ -0,0 +1,59 @@
+import type { AwilixContainer } from 'awilix'
+import {
+  bridgeLegacyGuard,
+  runMutationGuards,
+  type MutationGuard,
+  type MutationGuardInput,
+} from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+
+type GuardAfterCallback = {
+  guard: MutationGuard
+  metadata: Record<string, unknown> | null
+}
+
+export function resolveUserFeatures(auth: unknown): string[] {
+  const features = (auth as { features?: unknown })?.features
+  if (!Array.isArray(features)) return []
+  return features.filter((value): value is string => typeof value === 'string')
+}
+
+export async function runMessageMutationGuards(
+  container: AwilixContainer,
+  input: MutationGuardInput,
+  userFeatures: string[],
+): Promise<{
+  ok: boolean
+  errorBody?: Record<string, unknown>
+  errorStatus?: number
+  modifiedPayload?: Record<string, unknown>
+  afterSuccessCallbacks: GuardAfterCallback[]
+}> {
+  const legacyGuard = bridgeLegacyGuard(container)
+  if (!legacyGuard) {
+    return { ok: true, afterSuccessCallbacks: [] }
+  }
+
+  return runMutationGuards([legacyGuard], input, { userFeatures })
+}
+
+export async function runMessageMutationGuardAfterSuccess(
+  callbacks: GuardAfterCallback[],
+  input: {
+    tenantId: string
+    organizationId: string | null
+    userId: string
+    resourceKind: string
+    resourceId: string
+    operation: 'create' | 'update' | 'delete'
+    requestMethod: string
+    requestHeaders: Headers
+  },
+): Promise<void> {
+  for (const callback of callbacks) {
+    if (!callback.guard.afterSuccess) continue
+    await callback.guard.afterSuccess({
+      ...input,
+      metadata: callback.metadata ?? null,
+    })
+  }
+}

package/src/modules/messages/api/route.ts

@@ -13,6 +13,7 @@ import { getMessageType } from '../lib/message-types-registry'
 import { validateMessageObjectsForType } from '../lib/object-validation'
 import { attachOperationMetadataHeader } from '../lib/operationMetadata'
 import { canUseMessageEmailFeature, resolveMessageContext } from '../lib/routeHelpers'
+import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMutationGuards } from './guards'
 import { findMessageIdsBySearchTokens } from '../lib/searchLookup'
 import { MessageCommandExecuteResult } from '../commands/shared'
 import {
@@ -351,6 +352,28 @@ export async function POST(req: Request) {
     }
   }
 
+  const guardResult = await runMessageMutationGuards(
+    ctx.container,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      userId: scope.userId,
+      resourceKind: 'messages.message',
+      resourceId: null,
+      operation: 'create',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: input as Record<string, unknown>,
+    },
+    resolveUserFeatures(ctx.auth),
+  )
+  if (!guardResult.ok) {
+    return Response.json(
+      guardResult.errorBody ?? { error: 'Operation blocked by guard' },
+      { status: guardResult.errorStatus ?? 422 },
+    )
+  }
+
   const { result, logEntry } = await commandBus.execute('messages.messages.compose', {
     input: {
       ...input,
@@ -375,6 +398,16 @@ export async function POST(req: Request) {
     resourceKind: 'messages.message',
     resourceId: messageId,
   })
+  await runMessageMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId,
+    resourceKind: 'messages.message',
+    resourceId: messageId,
+    operation: 'create',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  })
   return response
 }
 

package/src/modules/staff/api/timesheets/time-entries/start-timer/route.ts

@@ -0,0 +1,110 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+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 { CommandRuntimeContext, CommandBus } from '@open-mercato/shared/lib/commands'
+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 type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { staffTimeEntryStartTimerSchema, type StaffTimeEntryStartTimerInput } from '../../../../data/validators'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['staff.timesheets.manage_own'] },
+}
+
+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 }
+}
+
+export async function POST(req: Request) {
+  try {
+    const { ctx, translate } = await buildContext(req)
+    const body = await req.json().catch(() => ({}))
+    const input = parseScopedCommandInput(staffTimeEntryStartTimerSchema, body, ctx, translate)
+    const commandBus = (ctx.container.resolve('commandBus') as CommandBus)
+    const { result, logEntry } = await commandBus.execute<StaffTimeEntryStartTimerInput, { timeEntryId: string }>(
+      'staff.timesheets.time_entries.start_timer',
+      { input, ctx },
+    )
+    const response = NextResponse.json({ ok: true, id: result?.timeEntryId ?? null }, { status: 201 })
+    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 ?? 'staff.timesheets.time_entry',
+          resourceId: logEntry.resourceId ?? result?.timeEntryId ?? null,
+          executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString() : undefined,
+        }),
+      )
+    }
+    return response
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    const { translate } = await resolveTranslations()
+    console.error('staff.timesheets.time-entries.start-timer failed', err)
+    return NextResponse.json(
+      { error: translate('staff.timesheets.errors.timerStart', 'Failed to start timer.') },
+      { status: 400 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Start a timesheet timer',
+  methods: {
+    POST: {
+      summary: 'Start a timesheet timer',
+      description:
+        'Atomically creates a timer-sourced time entry and starts it (sets startedAt and creates the initial work segment) in a single transaction, so a partial failure cannot leave an orphaned, unstarted entry.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: staffTimeEntryStartTimerSchema,
+      },
+      responses: [
+        {
+          status: 201,
+          description: 'Timer started',
+          schema: z.object({ ok: z.literal(true), id: z.string().uuid().nullable() }),
+        },
+        { status: 400, description: 'Invalid payload', schema: z.object({ error: z.string() }) },
+        { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
+        { status: 403, description: 'Forbidden', schema: z.object({ error: z.string() }) },
+        {
+          status: 409,
+          description: 'Another timer is already running for this staff member',
+          schema: z.object({ error: z.string() }),
+        },
+        {
+          status: 422,
+          description: 'Referenced time project not found or out of scope',
+          schema: z.object({ error: z.string() }),
+        },
+      ],
+    },
+  },
+}