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

package/src/modules/staff/lib/support/notifications.ts

@@ -0,0 +1,138 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { notificationTypes } from '../../notifications'
+import { StaffSupportTicket, StaffTeamMember, StaffTimeProject, StaffTimeTask } from '../../data/entities'
+import { resolveAssignmentGraceDaysFromContainer } from '../time-tracking/projectAssignment'
+import {
+  loadActiveAssignerUserIds,
+  notifyProjectWork,
+  resolveProjectWorkRecipients,
+} from '../time-tracking/workRecipients'
+
+const logger = createLogger('staff').child({ component: 'lib/support/notifications' })
+
+type ContainerLike = { resolve: <T = unknown>(name: string) => T }
+
+export type SupportNotificationKind = 'created' | 'customer_replied'
+
+const TYPE_BY_KIND: Record<SupportNotificationKind, string> = {
+  created: 'staff.support_ticket.created',
+  customer_replied: 'staff.support_ticket.customer_replied',
+}
+
+async function resolveAssigneeUserId(em: EntityManager, task: StaffTimeTask): Promise<string | null> {
+  if (!task.assigneeStaffMemberId) return null
+  const member = await findOneWithDecryption(
+    em,
+    StaffTeamMember,
+    { id: task.assigneeStaffMemberId, tenantId: task.tenantId, organizationId: task.organizationId, deletedAt: null },
+    undefined,
+    { tenantId: task.tenantId, organizationId: task.organizationId },
+  )
+  return member?.userId ?? null
+}
+
+/**
+ * Notifies staff about a support ticket through the project escalation chain and
+ * records the outcome on the ticket: `unnotified_at` is set (earliest value kept)
+ * when the chain reached nobody, and cleared when a notification reaches someone.
+ * Notifying is best-effort — the ticket or reply that triggered it is never undone.
+ */
+export async function notifySupportTicket(
+  container: ContainerLike,
+  input: { taskId: string; tenantId: string; organizationId: string; kind: SupportNotificationKind },
+): Promise<{ notifiedCount: number; step: number } | null> {
+  const typeDef = notificationTypes.find((type) => type.type === TYPE_BY_KIND[input.kind])
+  if (!typeDef) return null
+  const scope = { tenantId: input.tenantId, organizationId: input.organizationId }
+  const em = (container.resolve('em') as EntityManager).fork()
+  const task = await em.findOne(StaffTimeTask, { id: input.taskId, ...scope, source: 'portal', deletedAt: null })
+  if (!task) return null
+  const ticket = await findOneWithDecryption(em, StaffSupportTicket, { taskId: task.id, ...scope, deletedAt: null }, undefined, scope)
+  if (!ticket) return null
+  const project = await em.findOne(StaffTimeProject, { id: task.timeProjectId, ...scope }, { fields: ['id', 'name'] })
+  const graceDays = await resolveAssignmentGraceDaysFromContainer(container, input.tenantId)
+
+  const assigneeUserId = await resolveAssigneeUserId(em, task)
+  const audience =
+    input.kind === 'created'
+      ? [assigneeUserId, ...(await loadActiveAssignerUserIds(em, scope, { timeProjectId: task.timeProjectId, graceDays }))]
+      : [assigneeUserId]
+  const recipients = await resolveProjectWorkRecipients(em, scope, {
+    timeProjectId: task.timeProjectId,
+    audienceUserIds: audience,
+    graceDays,
+  })
+
+  const snapshot = ticket.customerSnapshot ?? {}
+  const customerName =
+    (typeof snapshot.reporterDisplayName === 'string' && snapshot.reporterDisplayName) ||
+    (typeof snapshot.displayName === 'string' && snapshot.displayName) ||
+    ''
+  const request = ticket.customerRequestSnapshot
+  const subject = request && typeof request.subject === 'string' ? request.subject : task.title
+  const result = await notifyProjectWork(container, scope, {
+    typeDef,
+    recipients,
+    build: {
+      titleVariables: { reference: ticket.supportReference },
+      bodyVariables: {
+        reference: ticket.supportReference,
+        customer: customerName,
+        subject,
+        category: ticket.categorySnapshot?.label ?? ticket.categoryValue,
+        project: project?.name ?? '',
+      },
+      sourceEntityType: 'staff:staff_time_task',
+      sourceEntityId: task.id,
+      linkHref: `/backend/staff/time-tracking/support?task=${encodeURIComponent(task.id)}`,
+      groupKey: `staff:support-ticket-${input.kind}:${task.id}`,
+    },
+  })
+
+  const fresh = await findOneWithDecryption(em, StaffSupportTicket, { id: ticket.id, ...scope }, undefined, scope)
+  if (fresh) {
+    if (result.notifiedCount === 0) {
+      if (!fresh.unnotifiedAt) {
+        fresh.unnotifiedAt = new Date()
+        fresh.updatedAt = new Date()
+        await em.flush()
+      }
+      logger.warn('staff support ticket notification reached nobody', {
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+        timeProjectId: task.timeProjectId,
+        ticketId: ticket.id,
+        taskId: task.id,
+        eventType: typeDef.type,
+        emptyStep: result.step,
+      })
+    } else if (fresh.unnotifiedAt) {
+      fresh.unnotifiedAt = null
+      fresh.updatedAt = new Date()
+      await em.flush()
+    }
+  }
+  return result
+}
+
+/** The ticket got an assignee, so somebody now owns it: clear the "nobody notified" flag. */
+export async function clearSupportTicketUnnotified(
+  em: EntityManager,
+  input: { taskId: string; tenantId: string; organizationId: string },
+): Promise<boolean> {
+  const scope = { tenantId: input.tenantId, organizationId: input.organizationId }
+  const ticket = await findOneWithDecryption(
+    em,
+    StaffSupportTicket,
+    { taskId: input.taskId, ...scope, deletedAt: null, unnotifiedAt: { $ne: null } },
+    undefined,
+    scope,
+  )
+  if (!ticket) return false
+  ticket.unnotifiedAt = null
+  ticket.updatedAt = new Date()
+  await em.flush()
+  return true
+}

package/src/modules/staff/lib/support/portalAttachments.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { Attachment as AttachmentEntity } from '@open-mercato/core/modules/attachments/data/entities'
+import type { SupportPortalScope } from './portalTickets'
+import {
+  CUSTOMER_UPLOAD_TAG_PREFIX,
+  CUSTOMER_VISIBLE_ATTACHMENT_TAG,
+  SUPPORT_TICKET_ATTACHMENT_ENTITY_ID,
+  customerUploadTag,
+} from './attachments'
+
+const logger = createLogger('staff').child({ component: 'lib/support/portalAttachments' })
+
+export type PortalAttachmentsApi = {
+  Attachment: typeof import('@open-mercato/core/modules/attachments/data/entities').Attachment
+  AttachmentPartition: typeof import('@open-mercato/core/modules/attachments/data/entities').AttachmentPartition
+  StorageDriverFactory: typeof import('@open-mercato/core/modules/attachments/lib/drivers').StorageDriverFactory
+  checkAttachmentAccess: typeof import('@open-mercato/core/modules/attachments/lib/access').checkAttachmentAccess
+  attachmentCrudEvents: typeof import('@open-mercato/core/modules/attachments/lib/crud').attachmentCrudEvents
+  attachmentCrudIndexer: typeof import('@open-mercato/core/modules/attachments/lib/crud').attachmentCrudIndexer
+  readAttachmentMetadata: typeof import('@open-mercato/core/modules/attachments/lib/metadata').readAttachmentMetadata
+  slugifyAttachmentFileName: typeof import('@open-mercato/core/modules/attachments/lib/imageUrls').slugifyAttachmentFileName
+  clearAttachmentThumbnailCache: typeof import('@open-mercato/core/modules/attachments/lib/thumbnailCache').clearAttachmentThumbnailCache
+  isMultipartRequestWithinUploadLimit: typeof import('@open-mercato/core/modules/attachments/lib/upload-limits').isMultipartRequestWithinUploadLimit
+  resolveAttachmentMaxBytes: typeof import('@open-mercato/core/modules/attachments/lib/upload-limits').resolveAttachmentMaxBytes
+  isScopedAttachmentUploadError: typeof import('@open-mercato/core/modules/attachments/lib/scoped-upload-service').isScopedAttachmentUploadError
+}
+
+export const portalSupportAttachmentItemSchema = z.object({
+  id: z.string().uuid(),
+  fileName: z.string(),
+  fileSize: z.number(),
+  mimeType: z.string().nullable(),
+  downloadUrl: z.string(),
+  uploadedByCustomer: z.boolean(),
+  canDelete: z.boolean(),
+  createdAt: z.string().nullable(),
+})
+
+export type PortalSupportAttachmentItem = z.infer<typeof portalSupportAttachmentItemSchema>
+
+/**
+ * Staff keeps no static edge to the attachments module: it is loaded on demand and a
+ * deployment without it reads as "attachments unavailable" (`null`).
+ */
+export async function loadPortalAttachmentsApi(): Promise<PortalAttachmentsApi | null> {
+  try {
+    const [entities, drivers, access, crud, metadataLib, imageUrls, thumbnails, limits, uploadService] = await Promise.all([
+      import('@open-mercato/core/modules/attachments/data/entities'),
+      import('@open-mercato/core/modules/attachments/lib/drivers'),
+      import('@open-mercato/core/modules/attachments/lib/access'),
+      import('@open-mercato/core/modules/attachments/lib/crud'),
+      import('@open-mercato/core/modules/attachments/lib/metadata'),
+      import('@open-mercato/core/modules/attachments/lib/imageUrls'),
+      import('@open-mercato/core/modules/attachments/lib/thumbnailCache'),
+      import('@open-mercato/core/modules/attachments/lib/upload-limits'),
+      import('@open-mercato/core/modules/attachments/lib/scoped-upload-service'),
+    ])
+    return {
+      Attachment: entities.Attachment,
+      AttachmentPartition: entities.AttachmentPartition,
+      StorageDriverFactory: drivers.StorageDriverFactory,
+      checkAttachmentAccess: access.checkAttachmentAccess,
+      attachmentCrudEvents: crud.attachmentCrudEvents,
+      attachmentCrudIndexer: crud.attachmentCrudIndexer,
+      readAttachmentMetadata: metadataLib.readAttachmentMetadata,
+      slugifyAttachmentFileName: imageUrls.slugifyAttachmentFileName,
+      clearAttachmentThumbnailCache: thumbnails.clearAttachmentThumbnailCache,
+      isMultipartRequestWithinUploadLimit: limits.isMultipartRequestWithinUploadLimit,
+      resolveAttachmentMaxBytes: limits.resolveAttachmentMaxBytes,
+      isScopedAttachmentUploadError: uploadService.isScopedAttachmentUploadError,
+    }
+  } catch (err) {
+    logger.warn('staff portal support attachments module unavailable', { err })
+    return null
+  }
+}
+
+export function readAttachmentTags(api: PortalAttachmentsApi, attachment: AttachmentEntity): string[] {
+  return api.readAttachmentMetadata(attachment.storageMetadata).tags ?? []
+}
+
+export function portalAttachmentAuth(scope: SupportPortalScope) {
+  return { sub: scope.auth.sub, tenantId: scope.tenantId, orgId: scope.organizationId, email: scope.auth.email }
+}
+
+export function serializePortalAttachment(
+  api: PortalAttachmentsApi,
+  attachment: AttachmentEntity,
+  taskId: string,
+  customerUserId: string,
+  canManage = false,
+): PortalSupportAttachmentItem {
+  const tags = readAttachmentTags(api, attachment)
+  return {
+    id: attachment.id,
+    fileName: attachment.fileName,
+    fileSize: attachment.fileSize,
+    mimeType: attachment.mimeType ?? null,
+    downloadUrl: `/api/staff/portal/support-tickets/${encodeURIComponent(taskId)}/attachments?attachmentId=${encodeURIComponent(attachment.id)}`,
+    uploadedByCustomer: tags.some((tag) => tag.startsWith(CUSTOMER_UPLOAD_TAG_PREFIX)),
+    canDelete: canManage && tags.includes(customerUploadTag(customerUserId)),
+    createdAt: attachment.createdAt ? attachment.createdAt.toISOString() : null,
+  }
+}
+
+/**
+ * The files of a ticket the customer may see: tagged `customer-visible` and passing
+ * the attachments module's own access check. Internal staff files are never returned.
+ * `canManage` is whether the caller holds `portal.support_tickets.manage`; without it
+ * no item reports `canDelete`, matching the DELETE route's own feature check.
+ */
+export async function listCustomerVisibleAttachments(
+  api: PortalAttachmentsApi,
+  scope: SupportPortalScope,
+  taskId: string,
+  canManage = false,
+): Promise<PortalSupportAttachmentItem[]> {
+  const decryptionScope = { tenantId: scope.tenantId, organizationId: scope.organizationId }
+  const attachments = await findWithDecryption(
+    scope.em,
+    api.Attachment,
+    { entityId: SUPPORT_TICKET_ATTACHMENT_ENTITY_ID, recordId: taskId, ...decryptionScope },
+    { orderBy: { createdAt: 'ASC' } },
+    decryptionScope,
+  )
+  const codes = Array.from(new Set(attachments.map((attachment) => attachment.partitionCode)))
+  const partitions = codes.length ? await scope.em.find(api.AttachmentPartition, { code: { $in: codes } }) : []
+  const partitionByCode = new Map(partitions.map((partition) => [partition.code, partition]))
+  const auth = portalAttachmentAuth(scope)
+  return attachments
+    .filter((attachment) => {
+      const partition = partitionByCode.get(attachment.partitionCode)
+      if (!partition) return false
+      if (!readAttachmentTags(api, attachment).includes(CUSTOMER_VISIBLE_ATTACHMENT_TAG)) return false
+      return api.checkAttachmentAccess(auth, attachment, partition, { requireAuthForPublic: true }).ok
+    })
+    .map((attachment) => serializePortalAttachment(api, attachment, taskId, scope.auth.sub, canManage))
+}

package/src/modules/staff/lib/support/portalBroadcast.ts

@@ -0,0 +1,161 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { StaffSupportTicket, StaffTimeTask, StaffTimeTaskComment, StaffTimeTaskStatus } from '../../data/entities'
+import { emitStaffEvent } from '../../events'
+import { filterPortalRecipientsByFeatureStrict, resolvePortalRecipientUserIdsStrict } from '../time-tracking/portalRecipients'
+import { derivePortalStatus } from './portalStatus'
+import { PORTAL_SUPPORT_TICKETS_VIEW_FEATURE } from './portalTickets'
+
+const logger = createLogger('staff').child({ component: 'lib/support/portalBroadcast' })
+
+export const PORTAL_FANOUT_BATCH_SIZE = 200
+
+type Scope = { tenantId: string; organizationId: string }
+
+export type PortalUpdateKind = 'status' | 'reply'
+
+/**
+ * `version` names the change being announced (the task version for a status change,
+ * the comment for a reply). The portal event bridge drops an event whose payload
+ * repeats one seen in the last 500 ms, so two different changes must never produce
+ * identical payloads, while two publishers of the same change still collapse.
+ *
+ * Resolves `true` when the update was emitted and `false` when there is genuinely no
+ * one to tell (no customer, no portal users, nobody holding the view feature, or the
+ * `customer_accounts` module absent). Any other recipient-lookup failure rejects, so a
+ * caller never records a publication that did not happen.
+ */
+async function emitPortalUpdate(
+  em: EntityManager,
+  task: StaffTimeTask,
+  ticket: StaffSupportTicket,
+  portalStatus: string,
+  kind: PortalUpdateKind,
+  version: string,
+): Promise<boolean> {
+  if (!task.customerId) return false
+  const customerUserIds = await resolvePortalRecipientUserIdsStrict(em, {
+    tenantId: task.tenantId,
+    organizationId: task.organizationId,
+    customerId: task.customerId,
+  })
+  const recipientUserIds = await filterPortalRecipientsByFeatureStrict(
+    em,
+    customerUserIds,
+    { tenantId: task.tenantId, organizationId: task.organizationId },
+    PORTAL_SUPPORT_TICKETS_VIEW_FEATURE,
+  )
+  if (recipientUserIds.length === 0) return false
+  await emitStaffEvent(
+    'staff.support_ticket.portal_updated',
+    {
+      id: task.id,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId,
+      ticketId: task.id,
+      supportReference: ticket.supportReference,
+      portalStatus,
+      kind,
+      version,
+      recipientUserIds,
+    },
+    { persistent: true },
+  )
+  return true
+}
+
+function emitActivity(task: StaffTimeTask, ticket: StaffSupportTicket, kind: 'portal_status'): void {
+  void emitStaffEvent(
+    'staff.support_ticket.activity_recorded',
+    {
+      id: ticket.id,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId,
+      taskId: task.id,
+      projectId: task.timeProjectId,
+      kind,
+    },
+    { persistent: true },
+  ).catch((err) => {
+    logger.error('staff support activity emit failed', { err, taskId: task.id })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_activity_emit_failed' })
+  })
+}
+
+/**
+ * Compare-and-publish: re-derive the customer-facing status of a portal ticket and
+ * broadcast only when it differs from what the portal was last told. Safe to call
+ * on any task event; internal tasks and tasks without a ticket row are ignored.
+ *
+ * `always` skips the comparison for triggers that are a status change by definition.
+ * Concurrent publishers (a reopen followed quickly by a resolve) each run on their own
+ * fork, so both can read a stale `portalStatusPublished` and skip; the portal refetches
+ * the ticket on every event, so publishing after each status change keeps it correct.
+ *
+ * `portalStatusPublished` advances only after `emitPortalUpdate` settles: an emitted
+ * update or a genuinely empty audience. A recipient-lookup or emit failure propagates
+ * with the marker untouched, so the persistent fan-out retries and republishes.
+ */
+export async function publishTaskPortalStatus(
+  em: EntityManager,
+  taskId: string,
+  scope: Scope,
+  options: { always?: boolean } = {},
+): Promise<boolean> {
+  const task = await em.findOne(StaffTimeTask, { id: taskId, ...scope, source: 'portal', deletedAt: null })
+  if (!task) return false
+  const ticket = await findOneWithDecryption(em, StaffSupportTicket, { taskId: task.id, ...scope, deletedAt: null }, undefined, scope)
+  if (!ticket) return false
+  const status = await em.findOne(StaffTimeTaskStatus, { id: task.taskStatusId, ...scope }, { fields: ['id', 'isDefault', 'isDone'] })
+  const portalStatus = derivePortalStatus(status)
+  const unchanged = ticket.portalStatusPublished === portalStatus
+  if (unchanged && !options.always) return false
+  await emitPortalUpdate(em, task, ticket, portalStatus, 'status', task.updatedAt ? task.updatedAt.toISOString() : task.id)
+  if (!unchanged) {
+    ticket.portalStatusPublished = portalStatus
+    ticket.updatedAt = new Date()
+    await em.flush()
+  }
+  emitActivity(task, ticket, 'portal_status')
+  return true
+}
+
+/** A status column's `isDone`/`isDefault` flags changed: re-derive every live portal ticket in it, in batches. */
+export async function fanOutStatusColumn(em: EntityManager, taskStatusId: string, scope: Scope): Promise<number> {
+  let published = 0
+  let offset = 0
+  for (;;) {
+    const tasks = await em.find(
+      StaffTimeTask,
+      { taskStatusId, ...scope, source: 'portal', deletedAt: null },
+      { fields: ['id'], limit: PORTAL_FANOUT_BATCH_SIZE, offset, orderBy: { id: 'asc' } },
+    )
+    if (tasks.length === 0) break
+    for (const task of tasks) {
+      if (await publishTaskPortalStatus(em.fork(), task.id, scope)) published += 1
+    }
+    if (tasks.length < PORTAL_FANOUT_BATCH_SIZE) break
+    offset += PORTAL_FANOUT_BATCH_SIZE
+  }
+  return published
+}
+
+/** A customer-visible comment was published, retracted or deleted: tell the ticket's own customer users to refetch. */
+export async function publishTicketReply(em: EntityManager, commentId: string, scope: Scope): Promise<boolean> {
+  const comment = await em.findOne(StaffTimeTaskComment, { id: commentId, ...scope }, { fields: ['id', 'taskId', 'updatedAt'] })
+  if (!comment) return false
+  const task = await em.findOne(StaffTimeTask, { id: comment.taskId, ...scope, source: 'portal', deletedAt: null })
+  if (!task) return false
+  const ticket = await findOneWithDecryption(em, StaffSupportTicket, { taskId: task.id, ...scope, deletedAt: null }, undefined, scope)
+  if (!ticket) return false
+  const status = await em.findOne(StaffTimeTaskStatus, { id: task.taskStatusId, ...scope }, { fields: ['id', 'isDefault', 'isDone'] })
+  return emitPortalUpdate(em, task, ticket, derivePortalStatus(status), 'reply', `${comment.id}:${comment.updatedAt ? comment.updatedAt.toISOString() : ''}`)
+}
+
+export function readEventScope(payload: { tenantId?: unknown; organizationId?: unknown }): Scope | null {
+  const tenantId = typeof payload.tenantId === 'string' ? payload.tenantId : null
+  const organizationId = typeof payload.organizationId === 'string' ? payload.organizationId : null
+  return tenantId && organizationId ? { tenantId, organizationId } : null
+}

package/src/modules/staff/lib/support/portalRoute.ts

@@ -0,0 +1,108 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { checkRateLimit, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_ERROR_KEY } from '@open-mercato/shared/lib/ratelimit/helpers'
+import { readEndpointRateLimitConfig } from '@open-mercato/shared/lib/ratelimit/config'
+import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import type { SupportPortalScope } from './portalTickets'
+
+const logger = createLogger('staff').child({ component: 'lib/support/portalRoute' })
+
+export const SUPPORT_TICKET_RESOURCE_KIND = 'staff.support_ticket'
+
+const RATE_LIMITS = {
+  create: readEndpointRateLimitConfig('STAFF_SUPPORT_TICKET_CREATE', {
+    points: 10,
+    duration: 3600,
+    keyPrefix: 'staff_support_ticket_create',
+  }),
+  message: readEndpointRateLimitConfig('STAFF_SUPPORT_TICKET_MESSAGE', {
+    points: 60,
+    duration: 3600,
+    keyPrefix: 'staff_support_ticket_message',
+  }),
+  upload: readEndpointRateLimitConfig('STAFF_SUPPORT_TICKET_UPLOAD', {
+    points: 30,
+    duration: 3600,
+    keyPrefix: 'staff_support_ticket_upload',
+  }),
+} as const
+
+export type PortalRateLimitKind = keyof typeof RATE_LIMITS
+
+export function buildPortalCommandContext(scope: SupportPortalScope, req: Request): CommandRuntimeContext {
+  const auth: NonNullable<AuthContext> = {
+    sub: scope.auth.sub,
+    sid: scope.auth.sid,
+    tenantId: scope.auth.tenantId,
+    orgId: scope.auth.orgId,
+    email: scope.auth.email,
+    customerEntityId: scope.auth.customerEntityId ?? null,
+    personEntityId: scope.auth.personEntityId ?? null,
+  }
+  return {
+    container: scope.container,
+    auth,
+    organizationScope: null,
+    selectedOrganizationId: scope.organizationId,
+    organizationIds: [scope.organizationId],
+    request: req,
+  }
+}
+
+/** Per customer user, so one noisy account cannot exhaust its colleagues' budget. */
+export async function checkPortalRateLimit(
+  scope: SupportPortalScope,
+  kind: PortalRateLimitKind,
+): Promise<Response | null> {
+  let service: RateLimiterService | null = null
+  try {
+    service = scope.container.resolve('rateLimiterService') as RateLimiterService
+  } catch {
+    return null
+  }
+  if (!service) return null
+  const { translate } = await resolveTranslations()
+  return checkRateLimit(
+    service,
+    RATE_LIMITS[kind],
+    `${scope.tenantId}:${scope.auth.sub}`,
+    translate(RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK),
+  )
+}
+
+export async function portalErrorResponse(err: unknown, label: string): Promise<Response> {
+  if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+  const rejection = getCommandInterceptorHttpRejection(err)
+  if (rejection) return NextResponse.json(rejection.body, { status: rejection.status })
+  if (err instanceof z.ZodError) {
+    const { translate } = await resolveTranslations()
+    return NextResponse.json(
+      { ok: false, error: translate('staff.errors.invalid_request', 'Invalid request'), details: err.issues },
+      { status: 400 },
+    )
+  }
+  logger.error(label, { err })
+  getTelemetryRuntime()?.reportError(err, {
+    module: 'staff',
+    code: 'staff.portal_support_route_failed',
+    attributes: { operation: label },
+  })
+  return NextResponse.json({ ok: false, error: 'staff.errors.internal' }, { status: 500 })
+}
+
+export function readPathId(req: Request, pattern: RegExp): string | null {
+  try {
+    const match = new URL(req.url).pathname.match(pattern)
+    const id = match?.[1] ? decodeURIComponent(match[1]) : null
+    return id && z.string().uuid().safeParse(id).success ? id : null
+  } catch {
+    return null
+  }
+}

package/src/modules/staff/lib/support/portalStatus.ts

@@ -0,0 +1,15 @@
+import type { StaffSupportPortalStatus } from '../../data/entities'
+
+export type PortalStatusFlags = {
+  isDefault: boolean
+  isDone: boolean
+}
+
+export function derivePortalStatus(status: PortalStatusFlags | null | undefined): StaffSupportPortalStatus {
+  if (!status) return 'received'
+  if (status.isDone) return 'resolved'
+  if (status.isDefault) return 'received'
+  return 'in_progress'
+}
+
+export const SUPPORT_PORTAL_STATUSES: readonly StaffSupportPortalStatus[] = ['received', 'in_progress', 'resolved']