@open-mercato/core 0.10.1-develop.7717.1.2befe9c634 → 0.10.1-develop.7721.1.b5c4a00a68

package/src/modules/staff/api/timesheets/support-routing-rules/route.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
+import { StaffSupportRoutingRule } from '../../../data/entities'
+import {
+  staffSupportRoutingRuleCreateSchema,
+  staffSupportRoutingRuleUpdateSchema,
+} from '../../../data/validators'
+import { staffSupportRoutingRuleCommandIds } from '../../../commands/support-routing-rules'
+import { createStaffCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from '../../openapi'
+
+const SETTINGS_FEATURE = 'staff.timesheets.settings.manage'
+
+const F = {
+  id: 'id',
+  tenant_id: 'tenant_id',
+  organization_id: 'organization_id',
+  category_value: 'category_value',
+  time_project_id: 'time_project_id',
+  is_active: 'is_active',
+  created_at: 'created_at',
+  updated_at: 'updated_at',
+} as const
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: [SETTINGS_FEATURE] },
+  POST: { requireAuth: true, requireFeatures: [SETTINGS_FEATURE] },
+  PUT: { requireAuth: true, requireFeatures: [SETTINGS_FEATURE] },
+  DELETE: { requireAuth: true, requireFeatures: [SETTINGS_FEATURE] },
+}
+
+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(100),
+    ids: z.string().optional(),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+  })
+  .passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: StaffSupportRoutingRule,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: 'staff:staff_support_routing_rule' },
+  list: {
+    schema: listSchema,
+    entityId: 'staff:staff_support_routing_rule',
+    fields: [
+      F.id,
+      F.organization_id,
+      F.tenant_id,
+      F.category_value,
+      F.time_project_id,
+      F.is_active,
+      F.created_at,
+      F.updated_at,
+    ],
+    defaultSort: { field: F.created_at, dir: 'asc' },
+    sortFieldMap: { 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 }
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: staffSupportRoutingRuleCommandIds.create,
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(staffSupportRoutingRuleCreateSchema, raw ?? {}, ctx, translate)
+      },
+      response: ({ result }) => ({ id: result?.ruleId ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: staffSupportRoutingRuleCommandIds.update,
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(staffSupportRoutingRuleUpdateSchema, raw ?? {}, ctx, translate)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: staffSupportRoutingRuleCommandIds.delete,
+      schema: rawBodySchema,
+      mapInput: async ({ parsed, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return { id: resolveCrudRecordId(parsed, ctx, translate) }
+      },
+      response: () => ({ ok: true }),
+    },
+  },
+})
+
+export const GET = crud.GET
+export const POST = crud.POST
+export const PUT = crud.PUT
+export const DELETE = crud.DELETE
+
+export const supportRoutingRuleListItemSchema = z.object({
+  id: z.string().uuid().nullable().optional(),
+  organization_id: z.string().uuid().nullable().optional(),
+  tenant_id: z.string().uuid().nullable().optional(),
+  category_value: z.string().nullable().optional(),
+  time_project_id: z.string().uuid().nullable().optional(),
+  is_active: z.boolean().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+export const openApi = createStaffCrudOpenApi({
+  resourceName: 'Support routing rule',
+  pluralName: 'Support routing rules',
+  querySchema: listSchema,
+  listResponseSchema: createPagedListResponseSchema(supportRoutingRuleListItemSchema),
+  create: {
+    schema: staffSupportRoutingRuleCreateSchema.omit({ tenantId: true, organizationId: true }),
+    responseSchema: z.object({ id: z.string().uuid().nullable() }),
+    description:
+      'Creates a routing rule. A null `categoryValue` is the organization fallback rule (exactly one; it can be repointed but not deleted or paused). A rule with a category sends that category to its own project.',
+  },
+  update: {
+    schema: staffSupportRoutingRuleUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Repoints a rule at another project or pauses/resumes a per-category rule. Pausing the fallback rule answers 422.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Deletes a per-category rule so the category falls back to the fallback project. Deleting the fallback rule answers 422.',
+  },
+})

package/src/modules/staff/api/timesheets/support-tickets/options/route.ts

@@ -0,0 +1,181 @@
+/**
+ * `GET /api/staff/timesheets/support-tickets/options` — the filter options behind
+ * the Support Inbox.
+ *
+ * The inbox is open to every holder of `staff.timesheets.tasks.view`, so its option
+ * lists cannot come from routes that need more: the routing preview needs
+ * `staff.timesheets.settings.manage` and the team directory needs `staff.view`,
+ * which an agent with the `employee` role holds neither of.
+ *
+ *  * `categories` is the organization's support category dictionary — the exact
+ *    organization, never an inherited one, the same lookup the portal form and the
+ *    ticket command use.
+ *  * `assignees` is limited to the people the caller can already see through their
+ *    project access: everyone actively assigned to one of the caller's projects, or,
+ *    for a holder of `staff.timesheets.projects.manage`, every active staff member of
+ *    the organization.
+ */
+
+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 { resolveSingleOrganizationIdOrDeny } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { StaffTeamMember, StaffTimeProjectMember } from '../../../../data/entities'
+import { loadSupportTicketCategories } from '../../../../lib/support/dictionaries'
+import { resolveFeatureAccess } from '../../../../lib/time-tracking/featureAccess'
+import { MANAGE_PROJECTS_FEATURE, resolveProjectAccess } from '../../../../lib/time-tracking/access'
+import {
+  isActiveAssignment,
+  normalizeAssignmentGraceDays,
+  resolveAssignmentGraceDaysFromContainer,
+} from '../../../../lib/time-tracking/projectAssignment'
+import { readSearchParamsRecord, runTimesheetInterceptors } from '../../_shared/withTimesheetInterceptors'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/support-tickets/options' })
+
+const VIEW_FEATURE = 'staff.timesheets.tasks.view'
+const MAX_ASSIGNEES = 500
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: [VIEW_FEATURE] },
+}
+
+const optionsResponseSchema = z.object({
+  categories: z.array(z.object({ value: z.string(), label: z.string() })),
+  assignees: z.array(z.object({ id: z.string().uuid(), displayName: z.string() })),
+})
+
+type SupportInboxOptions = z.infer<typeof optionsResponseSchema>
+
+type Scope = { tenantId: string; organizationId: string }
+
+async function loadAssignableStaffMemberIds(
+  em: EntityManager,
+  scope: Scope,
+  projectIds: string[],
+  graceDays: number | null,
+): Promise<string[]> {
+  if (projectIds.length === 0) return []
+  const memberships = await em.find(StaffTimeProjectMember, {
+    timeProjectId: { $in: projectIds },
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    status: 'active',
+    deletedAt: null,
+  })
+  const now = new Date()
+  return Array.from(
+    new Set(
+      memberships
+        .filter((membership) => isActiveAssignment(membership, now, normalizeAssignmentGraceDays(graceDays)))
+        .map((membership) => membership.staffMemberId),
+    ),
+  )
+}
+
+async function loadAssignees(
+  em: EntityManager,
+  scope: Scope,
+  staffMemberIds: string[] | null,
+): Promise<SupportInboxOptions['assignees']> {
+  if (staffMemberIds !== null && staffMemberIds.length === 0) return []
+  const where: Record<string, unknown> = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    isActive: true,
+    deletedAt: null,
+  }
+  if (staffMemberIds !== null) where.id = { $in: staffMemberIds }
+  const members = await findWithDecryption(em, StaffTeamMember, where, { limit: MAX_ASSIGNEES }, scope)
+  return members
+    .map((member) => ({ id: member.id, displayName: member.displayName || member.id }))
+    .sort((left, right) => left.displayName.localeCompare(right.displayName))
+}
+
+export async function GET(req: Request) {
+  try {
+    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 orgScope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const tenantId = orgScope?.tenantId ?? auth.tenantId ?? null
+    const organizationId = resolveSingleOrganizationIdOrDeny(orgScope, auth) ?? null
+    if (!tenantId || !organizationId) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.'),
+      })
+    }
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'GET',
+      scope: { container, userId: auth.sub, tenantId, organizationId },
+      query: readSearchParamsRecord(req.url),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const scope: Scope = { tenantId, organizationId }
+    const em = (container.resolve('em') as EntityManager).fork()
+    const manageAccess = await resolveFeatureAccess(container, auth.sub ?? null, [MANAGE_PROJECTS_FEATURE], scope)
+    const graceDays = await resolveAssignmentGraceDaysFromContainer(container, tenantId)
+    const access = await resolveProjectAccess({
+      em,
+      userId: auth.sub ?? null,
+      tenantId,
+      organizationId,
+      canManageAll: manageAccess.allowed,
+      userFeatures: manageAccess.grantedFeatures,
+      assignmentGraceDays: graceDays,
+    })
+
+    const assignableIds = access.canManageAll
+      ? null
+      : await loadAssignableStaffMemberIds(em, scope, access.projectIds, graceDays)
+
+    const [categories, assignees] = await Promise.all([
+      loadSupportTicketCategories(em, scope),
+      loadAssignees(em.fork(), scope, assignableIds),
+    ])
+
+    const payload: SupportInboxOptions = optionsResponseSchema.parse({ categories, assignees })
+    return session.respond(200, payload)
+  } catch (err) {
+    if (err instanceof CrudHttpError) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('staff.support.inbox options failed', { err })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_inbox_options_failed' })
+    const { translate } = await resolveTranslations()
+    return NextResponse.json({ error: translate('staff.errors.internal', 'Internal server error') }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Support Inbox filter options',
+  methods: {
+    GET: {
+      summary: 'Support Inbox filter options',
+      description:
+        "The organization's support ticket categories and the staff members a ticket can be filtered by assignee. Assignees are limited to the people actively assigned to the caller's projects; a holder of `staff.timesheets.projects.manage` gets every active staff member of the organization.",
+      responses: [{ status: 200, description: 'Filter options', schema: optionsResponseSchema }],
+      errors: [
+        { status: 400, description: 'Missing tenant or organization scope' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.tasks.view' },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/tasks/[id]/claim/route.ts

@@ -0,0 +1,31 @@
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  TASK_ASSIGNMENT_VIEW_FEATURE,
+  createTaskAssignmentPostHandler,
+  taskAssignmentResponseSchema,
+} from '../../../../../lib/time-tracking/taskAssignmentRoute'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [TASK_ASSIGNMENT_VIEW_FEATURE] },
+}
+
+export const POST = createTaskAssignmentPostHandler('claim')
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Claim an unassigned task',
+  methods: {
+    POST: {
+      summary: 'Claim an unassigned task',
+      description: 'Sets the caller as the assignee of an unassigned, not-done task. Only active assigners of the task project (a project member flagged as assigner, inside the assignment window) may claim; `staff.timesheets.tasks.manage` is not required. The update is conditional on the task still being unassigned, so of two concurrent claims exactly one wins and the other answers 409. Accepts `x-om-ext-optimistic-lock-expected-updated-at`.',
+      responses: [{ status: 200, description: 'Claim an unassigned task', schema: taskAssignmentResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'The caller is not an active assigner of the project' },
+        { status: 404, description: 'Task not found, or not on a project the caller can see' },
+        { status: 409, description: 'The task was already claimed, or changed since the version the caller sent' },
+        { status: 422, description: 'The task is in a done status' },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/tasks/[id]/comments/route.ts

@@ -50,7 +50,7 @@ import { User } from '@open-mercato/core/modules/auth/data/entities'
 import { StaffTimeTaskComment } from '../../../../../data/entities'
 import {
   staffTimeTaskCommentCreateSchema,
-  staffTimeTaskCommentUpdateSchema,
+  staffTimeTaskCommentUpdateRequestSchema,
 } from '../../../../../data/validators'
 import { staffTimeTaskCommentCommandIds } from '../../../../../commands/timesheets-task-comments'
 import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../../../guards'
@@ -86,6 +86,8 @@ const commentItemSchema = z.object({
   authorUserId: z.string().uuid().nullable(),
   authorName: z.string().nullable(),
   authorEmail: z.string().nullable(),
+  visibility: z.enum(['internal', 'customer']),
+  authorKind: z.enum(['staff', 'customer']),
   createdAt: z.string().nullable(),
   updatedAt: z.string().nullable(),
 })
@@ -106,8 +108,16 @@ const createResponseSchema = z.object({
 
 const okResponseSchema = z.object({ ok: z.boolean() })
 
-const createBodySchema = z.object({ body: z.string().trim().min(1).max(5000) })
-const updateBodySchema = z.object({ id: z.string().uuid(), body: z.string().trim().min(1).max(5000) })
+const visibilitySchema = z.enum(['internal', 'customer'])
+const createBodySchema = z.object({
+  body: z.string().trim().min(1).max(5000),
+  visibility: visibilitySchema.optional(),
+})
+const updateBodySchema = z.object({
+  id: z.string().uuid(),
+  body: z.string().trim().min(1).max(5000).optional(),
+  visibility: visibilitySchema.optional(),
+})
 
 type RouteContext = {
   ctx: CommandRuntimeContext
@@ -233,13 +243,17 @@ async function resolveAuthorMeta(
 function serializeComment(comment: StaffTimeTaskComment, authors: Map<string, AuthorMeta>) {
   const authorUserId = comment.authorUserId ?? null
   const meta = authorUserId ? authors.get(authorUserId) ?? null : null
+  const authorKind = comment.authorKind === 'customer' ? 'customer' : 'staff'
+  const customerName = comment.authorDisplaySnapshot?.displayName ?? null
   return {
     id: comment.id,
     taskId: comment.taskId,
     body: comment.body,
     authorUserId,
-    authorName: meta?.name ?? null,
-    authorEmail: meta?.email ?? null,
+    authorName: authorKind === 'customer' ? customerName : meta?.name ?? null,
+    authorEmail: authorKind === 'customer' ? null : meta?.email ?? null,
+    visibility: comment.visibility === 'customer' ? 'customer' : 'internal',
+    authorKind,
     createdAt: comment.createdAt ? comment.createdAt.toISOString() : null,
     updatedAt: comment.updatedAt ? comment.updatedAt.toISOString() : null,
   }
@@ -373,7 +387,7 @@ export async function POST(req: Request) {
     // here and the command stamps the authenticated caller instead.
     const input = parseScopedCommandInput(
       staffTimeTaskCommentCreateSchema,
-      { taskId: route.taskId, body: parsedBody.body },
+      { taskId: route.taskId, body: parsedBody.body, visibility: parsedBody.visibility ?? 'internal' },
       route.ctx,
       route.translate,
     )
@@ -416,7 +430,11 @@ export async function PUT(req: Request) {
     const parsedBody = updateBodySchema.parse(raw ?? {})
     await requireCommentOnTask(route, parsedBody.id)
 
-    const input = staffTimeTaskCommentUpdateSchema.parse({ id: parsedBody.id, body: parsedBody.body })
+    const input = staffTimeTaskCommentUpdateRequestSchema.parse({
+      id: parsedBody.id,
+      body: parsedBody.body,
+      visibility: parsedBody.visibility,
+    })
 
     const guardResult = await runGuards(route, 'update', input.id, input as unknown as Record<string, unknown>)
     if (!guardResult.ok) return guardResult.response

package/src/modules/staff/api/timesheets/tasks/[id]/release/route.ts

@@ -0,0 +1,30 @@
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  TASK_ASSIGNMENT_VIEW_FEATURE,
+  createTaskAssignmentPostHandler,
+  taskAssignmentResponseSchema,
+} from '../../../../../lib/time-tracking/taskAssignmentRoute'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [TASK_ASSIGNMENT_VIEW_FEATURE] },
+}
+
+export const POST = createTaskAssignmentPostHandler('release')
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Release a task you hold',
+  methods: {
+    POST: {
+      summary: 'Release a task you hold',
+      description: 'Clears the assignee of a task the caller is assigned to, making it claimable again; the project assigners are notified. Only the current assignee may release (403 otherwise); managers keep using PUT /api/staff/timesheets/tasks.',
+      responses: [{ status: 200, description: 'Release a task you hold', schema: taskAssignmentResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'The caller is not the current assignee' },
+        { status: 404, description: 'Task not found, or not on a project the caller can see' },
+        { status: 409, description: 'The task changed since the version the caller sent, or it is no longer assigned to the caller (`task_assignment_changed`)' },
+      ],
+    },
+  },
+}