@nuxt-customer-portal/timesheets 0.3.0

package/server/plugins/openapi-contracts.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+import { registerPortalOpenApiContracts } from '@nuxt-customer-portal/core/server/utils/openapi-contracts'
+import {
+  activityCreateSchema,
+  activityDeleteSchema,
+  activityListQuerySchema,
+  activityUpdateSchema,
+  clientCreateSchema,
+  clientDeleteSchema,
+  clientListQuerySchema,
+  entryCreateSchema,
+  entryUpdateSchema,
+  projectCreateSchema,
+  projectDeleteSchema,
+  projectListQuerySchema,
+  projectUpdateSchema,
+  reportQuerySchema,
+  reviewSchema,
+  settingsUpdateSchema,
+  tariffUpdateSchema,
+  teamMemberSettingsUpdateSchema,
+  timerStartSchema,
+  weekQuerySchema
+} from '../utils/timesheet-validation'
+
+export default defineNitroPlugin(() => {
+  registerPortalOpenApiContracts({
+    owner: 'timesheets',
+    query: {
+      timesheetsBootstrapGet: weekQuerySchema,
+      timesheetsAdminBootstrapGet: z.object({
+        section: z.enum(['approvals', 'clients', 'projects', 'activities', 'rates', 'settings', 'reports']).optional()
+      }),
+      timesheetsAdminActivitiesGet: activityListQuerySchema,
+      timesheetsAdminClientsGet: clientListQuerySchema,
+      timesheetsAdminProjectsGet: projectListQuerySchema,
+      timesheetsAdminReportGet: reportQuerySchema
+    },
+    body: {
+      timesheetsEntriesPost: entryCreateSchema,
+      timesheetsEntriesByIdPatch: entryUpdateSchema,
+      timesheetsTimerPost: timerStartSchema,
+      timesheetsAdminClientsPost: clientCreateSchema,
+      timesheetsAdminClientsByIdDelete: clientDeleteSchema,
+      timesheetsAdminActivitiesPost: activityCreateSchema,
+      timesheetsAdminActivitiesByIdPatch: activityUpdateSchema,
+      timesheetsAdminActivitiesByIdDelete: activityDeleteSchema,
+      timesheetsAdminProjectsPost: projectCreateSchema,
+      timesheetsAdminProjectsByIdPatch: projectUpdateSchema,
+      timesheetsAdminProjectsByIdDelete: projectDeleteSchema,
+      timesheetsAdminTariffsPut: tariffUpdateSchema,
+      timesheetsAdminTeamMemberPut: teamMemberSettingsUpdateSchema,
+      timesheetsAdminSettingsPatch: settingsUpdateSchema,
+      timesheetsAdminApprovalsByIdPost: reviewSchema
+    }
+  })
+})

package/server/utils/timesheet-admin-listing.ts

@@ -0,0 +1,281 @@
+import type {
+  ActivityTypeDto,
+  ClientApprovalItemDto,
+  ClientDto,
+  ClientSupplierTimesheetItemDto,
+  ProjectDto,
+  TimesheetsListResponse
+} from '@nuxt-customer-portal/timesheets/shared/types/timesheet'
+import type {
+  ActivityListQuery,
+  InternalApprovalListQuery,
+  ClientApprovalListQuery,
+  ClientListQuery,
+  ClientSupplierTimesheetListQuery,
+  ProjectListQuery
+} from './timesheet-validation'
+import {
+  listActivities,
+  listApprovalQueue,
+  listClientApprovals,
+  listClientSupplierTimesheets,
+  listClients,
+  listProjects
+} from './timesheet-repository'
+
+const compareText = (left: string | null | undefined, right: string | null | undefined) =>
+  (left ?? '').localeCompare(right ?? '', undefined, { sensitivity: 'base', numeric: true })
+const direction = (value: number, sortDir: 'asc' | 'desc') => (sortDir === 'asc' ? value : -value)
+const includes = (value: string | null | undefined, search: string) =>
+  (value ?? '').toLocaleLowerCase().includes(search)
+const paginate = <T>(items: T[], page: number, pageSize: number): TimesheetsListResponse<T> => {
+  const total = items.length
+  const pageCount = Math.ceil(total / pageSize)
+  const safePage = pageCount ? Math.min(page, pageCount) : 1
+  return {
+    items: items.slice((safePage - 1) * pageSize, safePage * pageSize),
+    pagination: { total, page: safePage, pageSize, pageCount }
+  }
+}
+
+export const listInternalApprovalsPage = async (
+  organizationId: string,
+  actorUserId: string,
+  query: InternalApprovalListQuery
+) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const rows = (await listApprovalQueue(organizationId, actorUserId))
+    .filter((item) => !query.userId || item.userId === query.userId)
+    .filter((item) => !search || includes(item.userName, search))
+    .filter((item) => !query.status || item.status === query.status)
+    .sort(
+      (a, b) =>
+        direction(
+          query.sortBy === 'totalMinutes'
+            ? a.totalMinutes - b.totalMinutes
+            : compareText(a[query.sortBy], b[query.sortBy]),
+          query.sortDir
+        ) || compareText(a.id, b.id)
+    )
+  return paginate(rows, query.page, query.pageSize)
+}
+
+export const listProviderClientApprovalsPage = async (
+  organizationId: string,
+  actorUserId: string,
+  query: Omit<InternalApprovalListQuery, 'status'> & {
+    status?: 'PENDING' | 'APPROVED' | 'DISPUTED' | 'AUTO_APPROVED'
+    clientOrganizationId?: string
+  }
+) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const [projects, clients] = await Promise.all([listProjects(organizationId), listClients(organizationId)])
+  const rows = (await listApprovalQueue(organizationId, actorUserId, 'provider'))
+    .flatMap((item) =>
+      [
+        ...item.clientReviews,
+        ...(item.status === 'APPROVED'
+          ? clients
+              .filter(
+                (client) =>
+                  !item.clientReviews.some((review) => review.clientOrganizationId === client.organizationId) &&
+                  item.entries.some((entry) =>
+                    projects.some(
+                      (project) =>
+                        project.id === entry.projectId && project.clientOrganizationId === client.organizationId
+                    )
+                  )
+              )
+              .map((client) => ({
+                clientOrganizationId: client.organizationId,
+                status: 'AUTO_APPROVED' as const,
+                version: 0,
+                canReply: false,
+                comment: null,
+                createdAt:
+                  [...(item.history ?? [])]
+                    .reverse()
+                    .find((event) => event.action === 'APPROVED' && !event.clientOrganizationId)?.createdAt ??
+                  item.submittedAt!
+              }))
+          : [])
+      ].map((review) => {
+        const entries = item.entries.filter((entry) =>
+          projects.some(
+            (project) => project.id === entry.projectId && project.clientOrganizationId === review.clientOrganizationId
+          )
+        )
+        return {
+          ...item,
+          clientReviews: [review],
+          messages: [],
+          history: [
+            {
+              id: `client-review-created:${item.id}:${review.clientOrganizationId}`,
+              action: review.status === 'AUTO_APPROVED' ? 'AUTO_APPROVED' : 'CLIENT_SUBMITTED',
+              actorUserId: item.userId,
+              actorName: item.userName,
+              actorImage: null,
+              clientName: null,
+              clientOrganizationId: review.clientOrganizationId,
+              comment: null,
+              createdAt: review.createdAt
+            },
+            ...(item.history ?? []).filter((event) => event.clientOrganizationId === review.clientOrganizationId)
+          ],
+          entries,
+          totalMinutes: entries.reduce((sum, entry) => sum + entry.durationMinutes, 0),
+          billableMinutes: entries
+            .filter((entry) => entry.billable)
+            .reduce((sum, entry) => sum + entry.durationMinutes, 0),
+          billableAmountMinor: entries.reduce(
+            (sum, entry) => sum + Math.round((entry.durationMinutes * entry.hourlyRateMinor) / 60),
+            0
+          )
+        }
+      })
+    )
+    .filter((item) => item.entries.length > 0)
+    .filter(
+      (item) =>
+        !query.clientOrganizationId ||
+        item.clientReviews.some((review) => review.clientOrganizationId === query.clientOrganizationId)
+    )
+    .filter((item) => !query.userId || item.userId === query.userId)
+    .filter((item) => !search || includes(item.userName, search))
+    .filter((item) => !query.status || item.clientReviews.some((review) => review.status === query.status))
+    .sort(
+      (a, b) =>
+        direction(
+          query.sortBy === 'totalMinutes'
+            ? a.totalMinutes - b.totalMinutes
+            : compareText(a[query.sortBy], b[query.sortBy]),
+          query.sortDir
+        ) || compareText(a.id, b.id)
+    )
+  return paginate(rows, query.page, query.pageSize)
+}
+
+export const listProjectsPage = async (organizationId: string, query: ProjectListQuery) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const rows = (await listProjects(organizationId))
+    .filter((item) => !search || [item.name, item.code, item.clientName].some((value) => includes(value, search)))
+    .filter((item) => !query.clientOrganizationId || item.clientOrganizationId === query.clientOrganizationId)
+    .filter((item) => !query.status || query.status === 'ALL' || item.status === query.status)
+    .sort(
+      (a, b) =>
+        direction(
+          query.sortBy === 'clientName'
+            ? compareText(a.clientName, b.clientName)
+            : query.sortBy === 'startsOn'
+              ? compareText(a.startsOn, b.startsOn)
+              : compareText(a.name, b.name),
+          query.sortDir
+        ) || compareText(a.id, b.id)
+    )
+  return paginate<ProjectDto>(rows, query.page, query.pageSize)
+}
+
+export const listClientsPage = async (organizationId: string, query: ClientListQuery) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const configured = (item: ClientDto) => item.accessMode !== 'DISABLED'
+  const rows = (await listClients(organizationId))
+    .filter((item) => !search || [item.name, item.officialName, item.slug].some((value) => includes(value, search)))
+    .filter((item) => !query.configured || configured(item) === (query.configured === 'configured'))
+    .sort((a, b) => direction(compareText(a.name, b.name), query.sortDir) || compareText(a.id, b.id))
+  return paginate<ClientDto>(rows, query.page, query.pageSize)
+}
+
+export const listActivitiesPage = async (organizationId: string, query: ActivityListQuery) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const rows = (await listActivities(organizationId))
+    .filter((item) => !search || includes(item.name, search))
+    .filter((item) => query.active === undefined || item.active === (query.active === 'true'))
+    .filter((item) => query.billable === undefined || item.billable === (query.billable === 'true'))
+    .sort(
+      (a, b) =>
+        direction(
+          query.sortBy === 'active'
+            ? Number(a.active) - Number(b.active)
+            : query.sortBy === 'billable'
+              ? Number(a.billable) - Number(b.billable)
+              : compareText(a.name, b.name),
+          query.sortDir
+        ) || compareText(a.id, b.id)
+    )
+  return paginate<ActivityTypeDto>(rows, query.page, query.pageSize)
+}
+
+export const listClientApprovalsPage = async (
+  clientOrganizationId: string,
+  actorUserId: string,
+  isAdmin: boolean,
+  query: ClientApprovalListQuery
+) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const rows = (await listClientApprovals(clientOrganizationId, actorUserId, isAdmin)).items
+    .filter((item) => !query.userId || item.userId === query.userId)
+    .filter(
+      (item) =>
+        !search ||
+        [
+          item.supplierName,
+          item.person,
+          item.reviewerName,
+          item.comment,
+          ...item.entries.flatMap((entry) => [entry.project, entry.activity, entry.note])
+        ].some((value) => includes(value, search))
+    )
+    .filter((item) => !query.workspaceClientId || item.workspaceClientId === query.workspaceClientId)
+    .filter((item) => !query.status || item.status === query.status)
+    .sort(
+      (a, b) =>
+        direction(
+          query.sortBy === 'supplierName'
+            ? compareText(a.supplierName, b.supplierName)
+            : query.sortBy === 'person'
+              ? compareText(a.person, b.person)
+              : query.sortBy === 'status'
+                ? compareText(a.status, b.status)
+                : query.sortBy === 'totalMinutes'
+                  ? a.totalMinutes - b.totalMinutes
+                  : compareText(a.weekStartsOn, b.weekStartsOn),
+          query.sortDir
+        ) || compareText(a.id, b.id)
+    )
+  return paginate<ClientApprovalItemDto>(rows, query.page, query.pageSize)
+}
+
+export const listClientSupplierTimesheetsPage = async (
+  clientOrganizationId: string,
+  actorUserId: string,
+  isAdmin: boolean,
+  query: ClientSupplierTimesheetListQuery
+) => {
+  const search = query.search?.toLocaleLowerCase() ?? ''
+  const rows = (await listClientSupplierTimesheets(clientOrganizationId, actorUserId, isAdmin))
+    .filter(
+      (item) =>
+        !search ||
+        [
+          item.supplierName,
+          item.person,
+          ...item.entries.flatMap((entry) => [entry.project, entry.activity, entry.note])
+        ].some((value) => includes(value, search))
+    )
+    .filter((item) => !query.workspaceClientId || item.workspaceClientId === query.workspaceClientId)
+    .sort(
+      (a, b) =>
+        direction(
+          query.sortBy === 'supplierName'
+            ? compareText(a.supplierName, b.supplierName)
+            : query.sortBy === 'person'
+              ? compareText(a.person, b.person)
+              : query.sortBy === 'totalMinutes'
+                ? a.totalMinutes - b.totalMinutes
+                : compareText(a.weekStartsOn, b.weekStartsOn),
+          query.sortDir
+        ) || compareText(a.id, b.id)
+    )
+  return paginate<ClientSupplierTimesheetItemDto>(rows, query.page, query.pageSize)
+}

package/server/utils/timesheet-email.ts

@@ -0,0 +1,221 @@
+import { formatTimesheetPeriod } from '../../shared/timesheet-dates'
+import { getClientEmailLocale } from '@nuxt-customer-portal/clients/server/utils/client-email-locale'
+import { and, eq, isNotNull } from 'drizzle-orm'
+import { db } from '@nuxt-customer-portal/core/server/portal'
+import { member, organization, user } from '@nuxt-customer-portal/core/schema'
+import { getPortalEmailSettings, sendPortalEmail } from '@nuxt-customer-portal/core/server/utils/portal-email'
+import { timesheetEmails } from '../../shared/emails'
+import {
+  internalApproverAssignment,
+  timesheetSubmission,
+  timesheetClientReview,
+  workspaceClient,
+  workspaceClientReviewer,
+  type TimesheetSubmissionRecord
+} from '../db/schema/timesheets'
+
+const escapeHtml = (value: string) =>
+  value.replace(
+    /[&<>"']/g,
+    (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]!
+  )
+
+type NotificationEvent = 'submitted' | 'approved' | 'rejected' | 'reopened'
+
+// Delivery is deliberately outside the transaction. An unavailable provider must not
+// turn a committed approval into an API error that invites a duplicate action.
+export const notifyTimesheetEvent = async (
+  submission: TimesheetSubmissionRecord | undefined,
+  event: NotificationEvent,
+  client?: { id: string; version: number; status: string; comment: string | null },
+  reply?: string,
+  replyClientId?: string
+) => {
+  if (!submission) {
+    return
+  }
+  try {
+    const [person] = await db.select().from(user).where(eq(user.id, submission.userId)).limit(1)
+    const [workspace] = await db
+      .select()
+      .from(organization)
+      .where(eq(organization.id, submission.organizationId))
+      .limit(1)
+    if (!person || !workspace) {
+      return
+    }
+    const { defaultLocale: locale } = await getPortalEmailSettings()
+    const baseUrl = process.env.BETTER_AUTH_URL || process.env.PUBLIC_URL || 'http://localhost:3051'
+    const send = async (
+      id: string,
+      recipient: { id: string; email: string; name: string },
+      path: string,
+      clientName = '',
+      comment = '',
+      scope = '',
+      emailLocale = locale
+    ) => {
+      try {
+        await sendPortalEmail({
+          moduleId: 'timesheets',
+          locale: emailLocale,
+          definition: timesheetEmails.find((definition) => definition.id === id)!,
+          to: recipient.email,
+          idempotencyKey: `timesheet/${submission.id}/${submission.version}/${id}/${scope}/${recipient.id}`,
+          values: {
+            recipient_name: escapeHtml(recipient.name),
+            person_name: escapeHtml(person.name),
+            organization_name: escapeHtml(workspace.name),
+            period: escapeHtml(formatTimesheetPeriod(submission.periodStartsOn, submission.periodEndsOn, emailLocale)),
+            period_start: submission.periodStartsOn,
+            period_end: submission.periodEndsOn,
+            client_name: escapeHtml(clientName),
+            comment: escapeHtml(comment),
+            action_url: escapeHtml(new URL(path, baseUrl).href)
+          }
+        })
+      } catch (error) {
+        console.error(
+          'Timesheet email delivery failed',
+          { submissionId: submission.id, event: id, recipientId: recipient.id },
+          error
+        )
+      }
+    }
+    if (client) {
+      const [clientOrganization] = await db.select().from(organization).where(eq(organization.id, client.id)).limit(1)
+      await send(
+        client.status === 'APPROVED' ? 'client-approved' : 'client-disputed',
+        person,
+        '/timesheets',
+        clientOrganization?.name,
+        client.comment ?? '',
+        `${client.id}/${client.version}`
+      )
+      return
+    }
+    if (event === 'submitted' && submission.status === 'SUBMITTED') {
+      const reviewers = await db
+        .selectDistinct({ id: user.id, email: user.email, name: user.name })
+        .from(internalApproverAssignment)
+        .innerJoin(user, eq(user.id, internalApproverAssignment.approverUserId))
+        .innerJoin(member, and(eq(member.userId, user.id), eq(member.organizationId, submission.organizationId)))
+        .where(
+          and(
+            eq(internalApproverAssignment.organizationId, submission.organizationId),
+            eq(internalApproverAssignment.submitterUserId, submission.userId)
+          )
+        )
+      await Promise.all(
+        reviewers.map((reviewer) =>
+          send(
+            'internal-requested',
+            reviewer,
+            `/timesheets/internal-approvals?${new URLSearchParams({ status: 'SUBMITTED', userId: submission.userId })}`,
+            '',
+            reply ?? ''
+          )
+        )
+      )
+      return
+    }
+    const outcome = event === 'submitted' ? 'approved' : event
+    if (!replyClientId) {
+      await send(`internal-${outcome}`, person, '/timesheets', '', reply ?? submission.rejectionComment ?? '')
+    }
+    if (submission.status !== 'APPROVED') {
+      return
+    }
+    const links = await db
+      .select({ id: workspaceClient.id, clientId: workspaceClient.clientOrganizationId })
+      .from(workspaceClient)
+      .where(
+        and(
+          eq(workspaceClient.workspaceOrganizationId, submission.organizationId),
+          eq(workspaceClient.accessMode, 'REVIEW')
+        )
+      )
+    const { ensureClientReviewers } = await import('./timesheet-repository')
+    await Promise.all(links.map((link) => ensureClientReviewers(link.id, link.clientId)))
+    const reviewers = await db
+      .selectDistinct({
+        id: user.id,
+        email: user.email,
+        name: user.name,
+        clientId: organization.id,
+        clientName: organization.name,
+        reviewId: timesheetClientReview.id,
+        version: timesheetClientReview.version
+      })
+      .from(timesheetClientReview)
+      .innerJoin(
+        workspaceClient,
+        and(
+          eq(workspaceClient.clientOrganizationId, timesheetClientReview.clientOrganizationId),
+          eq(workspaceClient.workspaceOrganizationId, submission.organizationId),
+          eq(workspaceClient.accessMode, 'REVIEW')
+        )
+      )
+      .innerJoin(member, eq(member.organizationId, workspaceClient.clientOrganizationId))
+      .innerJoin(user, eq(user.id, member.userId))
+      .leftJoin(
+        workspaceClientReviewer,
+        and(
+          eq(workspaceClientReviewer.workspaceClientId, workspaceClient.id),
+          eq(workspaceClientReviewer.userId, member.userId)
+        )
+      )
+      .innerJoin(organization, eq(organization.id, workspaceClient.clientOrganizationId))
+      .where(
+        and(
+          eq(timesheetClientReview.submissionId, submission.id),
+          eq(timesheetClientReview.status, 'PENDING'),
+          isNotNull(workspaceClientReviewer.userId)
+        )
+      )
+    await Promise.all(
+      reviewers
+        .filter((reviewer) => !replyClientId || reviewer.clientId === replyClientId)
+        .map(async (reviewer) =>
+          send(
+            'client-requested',
+            reviewer,
+            `/timesheets/approvals?${new URLSearchParams({ status: 'PENDING', userId: submission.userId })}`,
+            reviewer.clientName,
+            replyClientId ? (reply ?? '') : '',
+            `${reviewer.reviewId}/${reviewer.version}`,
+            await getClientEmailLocale(reviewer.clientId)
+          )
+        )
+    )
+  } catch (error) {
+    console.error('Timesheet email notification failed', { submissionId: submission.id, event }, error)
+  }
+}
+
+export const notifyClientTimesheetEvent = async (review: {
+  submissionId: string | null
+  clientOrganizationId: string
+  version: number
+  status: string
+  comment: string | null
+}) => {
+  if (!review.submissionId) {
+    return
+  }
+  try {
+    const [submission] = await db
+      .select()
+      .from(timesheetSubmission)
+      .where(eq(timesheetSubmission.id, review.submissionId))
+      .limit(1)
+    await notifyTimesheetEvent(submission, 'approved', {
+      id: review.clientOrganizationId,
+      version: review.version,
+      status: review.status,
+      comment: review.comment
+    })
+  } catch (error) {
+    console.error('Client timesheet email notification failed', { submissionId: review.submissionId }, error)
+  }
+}