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

package/src/modules/staff/api/portal/time-reports/route.ts

@@ -0,0 +1,270 @@
+/**
+ * `GET /api/staff/portal/time-reports` — EP-50, the customer-facing half of the
+ * time-tracking suite.
+ *
+ * **The ownership check, spelled out, because it is the only thing standing
+ * between a client and another client's hours.** Every row this route can return
+ * satisfies all four of:
+ *
+ *   `tenant_id      = auth.tenantId`          (from the customer JWT, never input)
+ *   `organization_id= auth.orgId`             (ditto; the portal shell already
+ *                                              refuses a URL whose org slug does
+ *                                              not resolve to this org)
+ *   `customer_id    = auth.customerEntityId`  (the signed-in portal user's own
+ *                                              customer entity — the same id
+ *                                              `staff_time_reports.customer_id`
+ *                                              holds, see `data/extensions.ts`)
+ *   `status         = 'closed' AND deleted_at IS NULL`
+ *
+ * A portal user with no `customerEntityId` is refused with `403` rather than
+ * being shown an unscoped list: an unlinked portal account is not a customer, and
+ * a null in that column would otherwise match nothing or — worse, in a future
+ * refactor — everything.
+ *
+ * **Money is absent, not blanked.** The response has no rate, cost, amount or
+ * currency field in its schema at all. `staff.timesheets.rates.view` is a *staff*
+ * feature resolved by `rbacService`; a portal identity is graded by
+ * `CustomerRbacService` against the disjoint `portal.*` namespace and can never
+ * hold it, so the module's own rule — money is added for a holder and absent for
+ * everyone else — resolves to "absent, always" here. Making that structural
+ * rather than conditional means no later edit can accidentally open it.
+ *
+ * Draft reports are invisible. A draft is working material whose entries are not
+ * frozen; only a closed report is a statement the business has stood behind.
+ */
+
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CustomerAuthContext } from '@open-mercato/shared/modules/customer-auth'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  PORTAL_TIME_REPORTS_VIEW_FEATURE,
+  portalOwnedReportClause,
+} from '../../../lib/time-tracking/portalReports'
+
+const logger = createLogger('staff').child({ component: 'api/portal/time-reports' })
+
+export const metadata: { path?: string; requireAuth?: boolean } = { requireAuth: false }
+
+const listQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(50).default(20),
+})
+
+const reportItemSchema = z.object({
+  id: z.string().uuid(),
+  reference: z.string(),
+  title: z.string(),
+  periodFrom: z.string(),
+  periodTo: z.string(),
+  closedAt: z.string().nullable(),
+  totalBillableMinutes: z.number().int(),
+  totalNonbillableMinutes: z.number().int(),
+})
+
+const errorResponseSchema = z.object({ ok: z.literal(false), error: z.string() })
+
+const listResponseSchema = z.object({
+  items: z.array(reportItemSchema),
+  total: z.number().int(),
+  page: z.number().int(),
+  pageSize: z.number().int(),
+  totalPages: z.number().int(),
+})
+
+type PortalScope = {
+  auth: CustomerAuthContext
+  customerId: string
+  tenantId: string
+  organizationId: string
+  em: EntityManager
+}
+
+type ReportRow = {
+  id: string
+  reference: string
+  title: string
+  period_from: Date | string
+  period_to: Date | string
+  closed_at: Date | string | null
+  total_billable_minutes: number | string | null
+  total_nonbillable_minutes: number | string | null
+}
+
+export function toIsoDate(value: Date | string | null | undefined): string | null {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null
+    return value.toISOString().slice(0, 10)
+  }
+  if (typeof value === 'string' && value.trim().length > 0) return value.trim().slice(0, 10)
+  return null
+}
+
+function toIsoDateTime(value: Date | string | null | undefined): string | null {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null
+    return value.toISOString()
+  }
+  if (typeof value === 'string' && value.trim().length > 0) return value.trim()
+  return null
+}
+
+export function toMinutes(value: number | string | null | undefined): number {
+  const parsed = typeof value === 'number' ? value : Number(value ?? 0)
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : 0
+}
+
+/**
+ * Resolves the portal identity through `customer_accounts` with a dynamic import.
+ * Staff must stay extractable into its own package, so the module graph carries no
+ * static edge to `customer_accounts`; a deployment without the portal installed
+ * answers `401` here instead of failing to load.
+ */
+type CustomerFeatureGuard = (
+  auth: CustomerAuthContext,
+  features: string[],
+  rbac: unknown,
+) => Promise<void>
+
+export async function resolvePortalScope(req: Request): Promise<PortalScope | Response> {
+  let auth: CustomerAuthContext | null = null
+  let requireFeature: CustomerFeatureGuard | null = null
+  try {
+    const customerAuth = await import('@open-mercato/core/modules/customer_accounts/lib/customerAuth')
+    auth = await customerAuth.getCustomerAuthFromRequest(req)
+    const guard: unknown = (customerAuth as { requireCustomerFeature?: unknown }).requireCustomerFeature
+    requireFeature = typeof guard === 'function' ? (guard as CustomerFeatureGuard) : null
+  } catch (err) {
+    logger.warn('staff portal time-reports could not resolve customer auth', { err })
+    return NextResponse.json({ ok: false, error: 'staff.errors.unauthorized' }, { status: 401 })
+  }
+  if (!auth) {
+    return NextResponse.json({ ok: false, error: 'staff.errors.unauthorized' }, { status: 401 })
+  }
+  const customerId =
+    typeof auth.customerEntityId === 'string' && auth.customerEntityId.trim().length > 0
+      ? auth.customerEntityId.trim()
+      : null
+  if (!customerId) {
+    return NextResponse.json({ ok: false, error: 'staff.errors.customerAccountNotLinked' }, { status: 403 })
+  }
+
+  // A missing guard is a failed feature check, not an absent one: without it the
+  // tenant loses the ability to REVOKE `portal.time_reports.view`, since a customer
+  // role stripped of the grant would keep reading reports. (Not a disclosure —
+  // `portalOwnedReportClause` still pins tenant, organization, customer and
+  // `status = 'closed'` — but revocation has to keep working.)
+  if (!requireFeature) {
+    logger.error('staff portal time-reports could not resolve requireCustomerFeature; refusing the request', {
+      feature: PORTAL_TIME_REPORTS_VIEW_FEATURE,
+    })
+    return NextResponse.json({ ok: false, error: 'staff.errors.forbidden' }, { status: 403 })
+  }
+
+  const container = await createRequestContainer()
+  try {
+    const rbac = container.resolve('customerRbacService')
+    await requireFeature(auth, [PORTAL_TIME_REPORTS_VIEW_FEATURE], rbac)
+  } catch (response) {
+    if (response instanceof Response) return response
+    logger.warn('staff portal time-reports feature check failed', { err: response })
+    return NextResponse.json({ ok: false, error: 'staff.errors.forbidden' }, { status: 403 })
+  }
+
+  return {
+    auth,
+    customerId,
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    em: (container.resolve('em') as EntityManager).fork(),
+  }
+}
+
+export async function GET(req: Request) {
+  try {
+    const scopeOrResponse = await resolvePortalScope(req)
+    if (scopeOrResponse instanceof Response) return scopeOrResponse
+    const scope = scopeOrResponse
+
+    const url = new URL(req.url)
+    const parsedQuery = listQuerySchema.safeParse({
+      page: url.searchParams.get('page') ?? undefined,
+      pageSize: url.searchParams.get('pageSize') ?? undefined,
+    })
+    if (!parsedQuery.success) {
+      return NextResponse.json({ ok: false, error: 'staff.errors.invalidInput' }, { status: 400 })
+    }
+    const { page, pageSize } = parsedQuery.data
+
+    const connection = scope.em.getConnection()
+    const owned = portalOwnedReportClause(scope)
+    const countRows = (await connection.execute(
+      `SELECT COUNT(*)::bigint AS total FROM staff_time_reports WHERE ${owned.sql}`,
+      owned.params,
+    )) as Array<{ total: string | number | null }>
+    const total = toMinutes(countRows?.[0]?.total)
+
+    const rows = (await connection.execute(
+      `
+        SELECT id, reference, title, period_from, period_to, closed_at,
+               total_billable_minutes, total_nonbillable_minutes
+        FROM staff_time_reports
+        WHERE ${owned.sql}
+        ORDER BY period_from DESC, reference DESC
+        LIMIT ? OFFSET ?
+      `,
+      [...owned.params, pageSize, (page - 1) * pageSize],
+    )) as ReportRow[]
+
+    const items = rows
+      .map((row) => {
+        const periodFrom = toIsoDate(row.period_from)
+        const periodTo = toIsoDate(row.period_to)
+        if (!periodFrom || !periodTo) return null
+        return {
+          id: row.id,
+          reference: row.reference,
+          title: row.title,
+          periodFrom,
+          periodTo,
+          closedAt: toIsoDateTime(row.closed_at),
+          totalBillableMinutes: toMinutes(row.total_billable_minutes),
+          totalNonbillableMinutes: toMinutes(row.total_nonbillable_minutes),
+        }
+      })
+      .filter((item): item is z.infer<typeof reportItemSchema> => item !== null)
+
+    return NextResponse.json(
+      listResponseSchema.parse({
+        items,
+        total,
+        page,
+        pageSize,
+        totalPages: Math.max(1, Math.ceil(total / pageSize)),
+      }),
+    )
+  } catch (err) {
+    logger.error('staff portal time-reports list failed', { err })
+    return NextResponse.json({ ok: false, error: 'staff.errors.internal' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff Portal',
+  methods: {
+    GET: {
+      summary: 'List the signed-in customer\u2019s closed time reports',
+      description:
+        'Returns the closed, non-deleted `staff_time_reports` rows whose `customer_id` matches the portal session\u2019s own customer entity, inside that session\u2019s tenant and organization. Draft reports are never listed. The response carries hours only \u2014 no rate, cost, amount or currency \u2014 because `staff.timesheets.rates.view` is a staff feature a portal identity cannot hold.',
+      query: listQuerySchema,
+      responses: [{ status: 200, description: 'Closed reports for the signed-in customer', schema: listResponseSchema }],
+      errors: [
+        { status: 401, description: 'Not signed in to the portal', schema: errorResponseSchema },
+        { status: 403, description: 'The portal account is not linked to a customer', schema: errorResponseSchema },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/team-members/self/route.ts

@@ -17,7 +17,6 @@ import {
   type StaffTeamMemberCreateInput,
 } from '../../../data/validators'
 import {
-  resolveUserFeatures,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../guards'
@@ -126,7 +125,6 @@ export async function POST(req: Request) {
         requestHeaders: req.headers,
         mutationPayload: parsed,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(

package/src/modules/staff/api/team-members/tags/assign/route.ts

@@ -14,7 +14,6 @@ import {
   type StaffTeamMemberTagAssignmentInput,
 } from '../../../../data/validators'
 import {
-  resolveUserFeatures,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../guards'
@@ -68,7 +67,6 @@ export async function POST(req: Request) {
         requestHeaders: req.headers,
         mutationPayload: input,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(

package/src/modules/staff/api/team-members/tags/unassign/route.ts

@@ -14,7 +14,6 @@ import {
   type StaffTeamMemberTagAssignmentInput,
 } from '../../../../data/validators'
 import {
-  resolveUserFeatures,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../guards'
@@ -68,7 +67,6 @@ export async function POST(req: Request) {
         requestHeaders: req.headers,
         mutationPayload: input,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(

package/src/modules/staff/api/timesheets/_shared/withTimesheetInterceptors.ts

@@ -0,0 +1,292 @@
+/**
+ * API interceptors for the hand-rolled `/api/staff/timesheets/*` routes.
+ *
+ * The eight `makeCrudRoute` time-tracking resources run `runApiInterceptorsBefore`
+ * and `runApiInterceptorsAfter` through the CRUD factory. The ~23 routes written by
+ * hand beside them ran neither, so a third party could rewrite the body of a create
+ * on `/time-entries` but not on `/time-entries/bulk`, and could not shape the
+ * response of a single aggregate. This wraps the two shared runners in the one shape
+ * those routes need: one call before the work, one call around the response.
+ *
+ * `routePath` is derived from the request URL exactly as the factory derives it
+ * (`normalizeInterceptorRoutePath`) — the pathname with the leading `/api/` removed,
+ * so an interceptor targets `staff/timesheets/time-entries/bulk`. A route with a
+ * dynamic segment carries the CONCRETE id in that path
+ * (`staff/timesheets/time-entries/<uuid>/duplicate`), so an interceptor for one of
+ * those must use the registry's prefix wildcard — `staff/timesheets/time-entries/*`
+ * — rather than a literal with a placeholder in it.
+ *
+ * Scope: the interceptor context carries `tenantId` and `organizationId` and this
+ * helper fails closed with a 400 when either is missing, so no interceptor ever runs
+ * — and no route body is ever handed to one — outside a resolved tenant scope.
+ */
+
+import { NextResponse } from 'next/server'
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type {
+  ApiInterceptorMethod,
+  InterceptorRequest,
+} from '@open-mercato/shared/lib/crud/api-interceptor'
+import { getApiInterceptorsForRoute } from '@open-mercato/shared/lib/crud/interceptor-registry'
+import { runApiInterceptorsBefore } from '@open-mercato/shared/lib/crud/interceptor-runner'
+import { runCustomRouteAfterInterceptors } from '@open-mercato/shared/lib/crud/custom-route-interceptor'
+import { parseExtensionHeaders } from '@open-mercato/shared/lib/umes/extension-headers'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+type RbacServiceLike = {
+  getGrantedFeatures?: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<string[]>
+}
+
+export type TimesheetInterceptorScope = {
+  container: AwilixContainer
+  userId: string | null | undefined
+  tenantId: string | null | undefined
+  organizationId: string | null | undefined
+  /**
+   * The caller's granted features, when the route already resolved them — through
+   * `resolveFeatureAccess`, which always yields an array. Deliberately not
+   * nullable: a grant list that can be `null` cannot say whether an empty answer
+   * means "no grants" or "could not ask", and passing that ambiguity on is what
+   * this helper's own fallback exists to avoid.
+   *
+   * Omitted, the helper asks `rbacService.getGrantedFeatures` once — the same
+   * source the CRUD factory uses — so a feature-gated interceptor is evaluated
+   * against a real grant set rather than an empty one, and an unreadable set gates
+   * every feature-scoped interceptor off.
+   */
+  userFeatures?: readonly string[]
+  /**
+   * Opt-in for the tenant-global routes (`/settings`, `/settings/reapply-rounding`),
+   * whose records have no organization at all. Without it a request that resolved no
+   * organization is refused rather than interceptor-scoped to an empty organization —
+   * the same fail-closed default every org-scoped route here keeps. With it, the
+   * context carries the empty organization id the CRUD factory also passes for a
+   * tenant-global caller.
+   */
+  tenantGlobal?: boolean
+}
+
+export type TimesheetInterceptorSession = {
+  /** The request body after the before-pass, or `{}` for a route that sends none. */
+  body: Record<string, unknown>
+  /** The query after the before-pass. */
+  query: Record<string, unknown>
+  /** `query` as `URLSearchParams`, for routes that read their input that way. */
+  searchParams: URLSearchParams
+  /**
+   * Runs the after-pass over a successful JSON response and returns it. An
+   * interceptor that fails or times out replaces the response with its own error.
+   */
+  respond(statusCode: number, body: Record<string, unknown>): Promise<NextResponse>
+  /**
+   * Runs the after-pass over a descriptor for a non-JSON response (a file export).
+   * The interceptors cannot rewrite the bytes, so the descriptor is what they shape;
+   * the caller applies whatever came back. A failed interceptor yields a JSON error
+   * response instead of the file.
+   */
+  respondWithDescriptor(
+    descriptor: Record<string, unknown>,
+  ): Promise<{ ok: true; descriptor: Record<string, unknown> } | { ok: false; response: NextResponse }>
+}
+
+export type TimesheetInterceptorRun =
+  | { ok: true; session: TimesheetInterceptorSession }
+  | { ok: false; response: NextResponse }
+
+/**
+ * Duplicates and repeated keys collapse to arrays so a rewritten query round-trips
+ * `?tagIds=a&tagIds=b` unchanged.
+ */
+export function readSearchParamsRecord(url: string): Record<string, unknown> {
+  const record: Record<string, unknown> = {}
+  let params: URLSearchParams
+  try {
+    params = new URL(url).searchParams
+  } catch {
+    return record
+  }
+  params.forEach((value, key) => {
+    const existing = record[key]
+    if (existing === undefined) {
+      record[key] = value
+      return
+    }
+    if (Array.isArray(existing)) {
+      existing.push(value)
+      return
+    }
+    record[key] = [existing, value]
+  })
+  return record
+}
+
+function toSearchParams(query: Record<string, unknown>): URLSearchParams {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === null || item === undefined) continue
+        params.append(key, String(item))
+      }
+      continue
+    }
+    params.append(key, String(value))
+  }
+  return params
+}
+
+function normalizeRoutePath(url: string): string {
+  try {
+    const pathname = new URL(url).pathname
+    if (pathname.startsWith('/api/')) return pathname.slice(5)
+    if (pathname === '/api') return ''
+    return pathname.replace(/^\/+/, '')
+  } catch {
+    return ''
+  }
+}
+
+function toHeaderRecord(headers: Headers): Record<string, string> {
+  const output: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    output[key] = value
+  })
+  return output
+}
+
+async function resolveUserFeatures(scope: TimesheetInterceptorScope): Promise<string[]> {
+  if (scope.userFeatures) return [...scope.userFeatures]
+  if (!scope.userId) return []
+  try {
+    const rbac = scope.container.resolve('rbacService') as RbacServiceLike | undefined
+    if (!rbac?.getGrantedFeatures) return []
+    return await rbac.getGrantedFeatures(scope.userId, {
+      tenantId: scope.tenantId ?? null,
+      organizationId: scope.organizationId ?? null,
+    })
+  } catch {
+    // An unreadable grant set gates every feature-scoped interceptor off rather
+    // than running it unauthorized.
+    return []
+  }
+}
+
+export async function runTimesheetInterceptors(args: {
+  request: Request
+  method: ApiInterceptorMethod
+  scope: TimesheetInterceptorScope
+  /** `readJsonSafe` returns `null` for an unparseable body; that reaches here as `{}`. */
+  body?: Record<string, unknown> | null
+  query?: Record<string, unknown>
+}): Promise<TimesheetInterceptorRun> {
+  const { request, method, scope } = args
+  const tenantId = scope.tenantId || null
+  const resolvedOrganizationId = scope.organizationId || null
+  const organizationId = resolvedOrganizationId ?? (scope.tenantGlobal ? '' : null)
+  if (!tenantId || organizationId === null) {
+    const { translate } = await resolveTranslations()
+    return {
+      ok: false,
+      response: NextResponse.json(
+        { error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.') },
+        { status: 400 },
+      ),
+    }
+  }
+
+  const routePath = normalizeRoutePath(request.url)
+  const headers = toHeaderRecord(request.headers)
+  const requestPayload: InterceptorRequest = {
+    method,
+    url: request.url,
+    body: args.body ?? {},
+    query: args.query ?? {},
+    headers,
+  }
+
+  // No interceptor targets this route and method, so neither pass can observe or
+  // change anything. Skipping here keeps the request off the RBAC grant read and the
+  // `em` resolve that assembling an interceptor context would otherwise cost on every
+  // call to every one of these routes.
+  if (getApiInterceptorsForRoute(routePath, method).length === 0) {
+    const query = requestPayload.query ?? {}
+    return {
+      ok: true,
+      session: {
+        body: requestPayload.body ?? {},
+        query,
+        searchParams: toSearchParams(query),
+        async respond(statusCode, body) {
+          return NextResponse.json(body, { status: statusCode })
+        },
+        async respondWithDescriptor(descriptor) {
+          return { ok: true, descriptor }
+        },
+      },
+    }
+  }
+
+  const context = {
+    userId: scope.userId ?? '',
+    organizationId,
+    tenantId,
+    em: scope.container.resolve('em') as EntityManager,
+    container: scope.container,
+    userFeatures: await resolveUserFeatures(scope),
+    extensionHeaders: parseExtensionHeaders(headers),
+  }
+
+  const before = await runApiInterceptorsBefore({
+    routePath,
+    method,
+    request: requestPayload,
+    context,
+  })
+  if (!before.ok) {
+    return { ok: false, response: NextResponse.json(before.body, { status: before.statusCode }) }
+  }
+
+  const interceptedRequest = before.request
+  const query = interceptedRequest.query ?? {}
+
+  const runAfter = async (body: Record<string, unknown>, statusCode: number) =>
+    runCustomRouteAfterInterceptors({
+      routePath,
+      method,
+      request: interceptedRequest,
+      response: { statusCode, body, headers: {} },
+      context,
+      metadataByInterceptor: before.metadataByInterceptor,
+    })
+
+  return {
+    ok: true,
+    session: {
+      body: interceptedRequest.body ?? {},
+      query,
+      searchParams: toSearchParams(query),
+      async respond(statusCode, body) {
+        const after = await runAfter(body, statusCode)
+        return NextResponse.json(after.body, {
+          status: after.statusCode,
+          ...(Object.keys(after.headers).length ? { headers: after.headers } : {}),
+        })
+      },
+      async respondWithDescriptor(descriptor) {
+        const after = await runAfter(descriptor, 200)
+        if (!after.ok) {
+          return {
+            ok: false,
+            response: NextResponse.json(after.body, { status: after.statusCode }),
+          }
+        }
+        return { ok: true, descriptor: after.body }
+      },
+    },
+  }
+}