@ossy/timesheets 3.9.0 → 3.11.0

package/src/billing-period.spec.js

@@ -0,0 +1,89 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  findTimesheetForContractPeriod,
+  isContractActive,
+  normalizeBillingPeriod,
+  periodForContract,
+  weekPeriodBounds,
+} from './billing-period.js'
+
+describe('normalizeBillingPeriod', () => {
+  it('defaults unknown values to monthly', () => {
+    expect(normalizeBillingPeriod('weekly')).toBe('weekly')
+    expect(normalizeBillingPeriod('monthly')).toBe('monthly')
+    expect(normalizeBillingPeriod(undefined)).toBe('monthly')
+    expect(normalizeBillingPeriod('quarterly')).toBe('monthly')
+  })
+})
+
+describe('weekPeriodBounds', () => {
+  it('returns Mon–Sun containing the reference day', () => {
+    // Wednesday 2026-08-19 local
+    const { periodStart, periodEnd } = weekPeriodBounds(new Date(2026, 7, 19))
+    expect(new Date(periodStart).getDay()).toBe(1) // Monday
+    expect(new Date(periodEnd).getDay()).toBe(0) // Sunday
+    expect(new Date(periodStart).getDate()).toBe(17)
+    expect(new Date(periodEnd).getDate()).toBe(23)
+  })
+
+  it('treats Sunday as end of the current ISO week', () => {
+    const { periodStart, periodEnd } = weekPeriodBounds(new Date(2026, 7, 23))
+    expect(new Date(periodStart).getDate()).toBe(17)
+    expect(new Date(periodEnd).getDate()).toBe(23)
+  })
+})
+
+describe('periodForContract', () => {
+  it('uses calendar month when billingPeriod is monthly or missing', () => {
+    const asOf = new Date(2026, 7, 19)
+    expect(periodForContract({ billingPeriod: 'monthly' }, asOf)).toEqual({
+      periodStart: new Date(2026, 7, 1).setHours(0, 0, 0, 0),
+      periodEnd: new Date(2026, 7, 31).setHours(0, 0, 0, 0),
+    })
+    expect(periodForContract({}, asOf).periodStart).toBe(
+      new Date(2026, 7, 1).setHours(0, 0, 0, 0),
+    )
+  })
+
+  it('uses ISO week when billingPeriod is weekly', () => {
+    const asOf = new Date(2026, 7, 19)
+    expect(periodForContract({ billingPeriod: 'weekly' }, asOf)).toEqual(
+      weekPeriodBounds(asOf),
+    )
+  })
+})
+
+describe('isContractActive', () => {
+  it('requires start ≤ asOf and end ≥ asOf when set', () => {
+    const asOf = new Date(2026, 7, 19)
+    expect(isContractActive({
+      startDate: new Date(2026, 0, 1).getTime(),
+      endDate: new Date(2026, 11, 31).getTime(),
+    }, asOf)).toBe(true)
+
+    expect(isContractActive({
+      startDate: new Date(2026, 8, 1).getTime(),
+    }, asOf)).toBe(false)
+
+    expect(isContractActive({
+      startDate: new Date(2026, 0, 1).getTime(),
+      endDate: new Date(2026, 6, 1).getTime(),
+    }, asOf)).toBe(false)
+
+    expect(isContractActive({
+      startDate: new Date(2026, 0, 1).getTime(),
+    }, asOf)).toBe(true)
+  })
+})
+
+describe('findTimesheetForContractPeriod', () => {
+  it('matches contract id + period and returns the newest', () => {
+    const resources = [
+      { id: 'a', createdAt: 1, content: { periodStart: 100, contractId: 'c1' } },
+      { id: 'b', createdAt: 3, content: { periodStart: 100, contractId: { resourceId: 'c1' } } },
+      { id: 'c', createdAt: 9, content: { periodStart: 100, contractId: 'c2' } },
+    ]
+    expect(findTimesheetForContractPeriod(resources, 'c1', 100)?.id).toBe('b')
+    expect(findTimesheetForContractPeriod(resources, 'c1', 999)).toBe(null)
+  })
+})

package/src/build-prefilled-lines.js

@@ -1,25 +1,12 @@
 import { CalendarClient } from '@ossy/calendar'
 import { DEFAULT_HOLIDAY_LOCALE, resolveHolidayLocale } from './holiday-locale.js'
+import { monthPeriodBounds } from './billing-period.js'
+
+export { monthPeriodBounds }
 
 /** Prefill hours for a workday (SPEC). */
 export const WORKDAY_HOURS = 8
 
-/**
- * Calendar-month period bounds as local midnights, returned as Unix ms.
- * @param {number} year
- * @param {number} monthIndex 0–11
- */
-export function monthPeriodBounds (year, monthIndex) {
-  const start = new Date(year, monthIndex, 1)
-  const end = new Date(year, monthIndex + 1, 0)
-  start.setHours(0, 0, 0, 0)
-  end.setHours(0, 0, 0, 0)
-  return {
-    periodStart: start.getTime(),
-    periodEnd: end.getTime(),
-  }
-}
-
 /**
  * Build prefilled timesheet lines for an inclusive period.
  * Workdays → 8h; non-workdays → 0h. `isWorkday` is snapshotted.

package/src/create-and-save-timesheet.flow.js

@@ -0,0 +1,34 @@
+import enableTimesheetsFlow from './enable-timesheets.flow.js'
+import { metadata as OpenNewTimesheet } from './open-new.action.js'
+import { metadata as GenerateTimesheet } from './generate.action.js'
+import { metadata as SaveTimesheet } from './save.action.js'
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/create-and-save-timesheet',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+  timeout: 150_000,
+}
+
+/**
+ * After enabling timesheets, open the create modal, generate a draft for the
+ * current month, and save it from the side panel.
+ */
+export default {
+  title: 'Create and save timesheet',
+  description:
+    'Signed-in user enables timesheets, generates a draft timesheet, saves it, and sees saved status in the panel and list',
+  steps: [
+    ...enableTimesheetsFlow.steps,
+    { result: { action: OpenNewTimesheet, timeout: 10000 } },
+    { action: OpenNewTimesheet },
+    { result: { action: GenerateTimesheet, timeout: 10000 } },
+    { action: GenerateTimesheet },
+    { result: { action: SaveTimesheet, timeout: 20000 } },
+    { result: { selector: '[data-timesheet-panel-status="draft"]', timeout: 20000 } },
+    { result: { selector: '[data-timesheet-status="draft"]', timeout: 20000 } },
+    { action: SaveTimesheet },
+    { result: { selector: '[data-timesheet-panel-status="saved"]', timeout: 20000 } },
+    { result: { selector: '[data-timesheet-status="saved"]', timeout: 20000 } },
+  ],
+}

package/src/create-timesheet-draft.js

@@ -0,0 +1,81 @@
+import { nanoid } from 'nanoid'
+import { ResourcesEvents, commitResource } from '@ossy/resources/server'
+import { TimesheetsSchema } from './schema-ids.js'
+import { timesheets } from './locations.js'
+import { buildPrefilledLines } from './build-prefilled-lines.js'
+import { DEFAULT_HOLIDAY_LOCALE, resolveHolidayLocale } from './holiday-locale.js'
+import { toTimesheetDto } from './timesheet-dto.js'
+import { optionalReference } from './timesheet-refs.js'
+
+/**
+ * Create a draft timesheet resource (shared by manual generate and auto-generate).
+ *
+ * @param {object} options
+ * @param {string} options.workspaceId
+ * @param {number} options.periodStart
+ * @param {number} options.periodEnd
+ * @param {string} [options.locale]
+ * @param {unknown} [options.employeeId]
+ * @param {unknown} [options.contractId]
+ * @param {string} [options.createdBy]
+ * @param {boolean} [options.autoGenerated]
+ * @param {{ info?: Function }} [options.log]
+ */
+export async function createTimesheetDraft ({
+  workspaceId,
+  periodStart,
+  periodEnd,
+  locale,
+  employeeId: employeeIdRaw,
+  contractId: contractIdRaw,
+  createdBy = 'system',
+  autoGenerated = false,
+  log,
+} = {}) {
+  if (!workspaceId) {
+    throw Object.assign(new Error('workspaceId is required'), { status: 400 })
+  }
+
+  periodStart = Number(periodStart)
+  periodEnd = Number(periodEnd)
+
+  if (!Number.isFinite(periodStart) || !Number.isFinite(periodEnd) || periodEnd < periodStart) {
+    throw Object.assign(new Error('invalid period'), { status: 400 })
+  }
+
+  const holidayLocale = resolveHolidayLocale(locale, DEFAULT_HOLIDAY_LOCALE)
+  const employeeId = optionalReference(employeeIdRaw)
+  const contractId = optionalReference(contractIdRaw)
+
+  log?.info?.(
+    `[timesheets] create draft ${periodStart}–${periodEnd} for workspace ${workspaceId} (locale ${holidayLocale})`,
+  )
+
+  const lines = buildPrefilledLines(periodStart, periodEnd, holidayLocale)
+  const content = {
+    periodStart,
+    periodEnd,
+    status: 'draft',
+    holidayLocale,
+    lines,
+    ...(employeeId ? { employeeId } : {}),
+    ...(contractId ? { contractId } : {}),
+    ...(autoGenerated ? { autoGenerated: true } : {}),
+  }
+
+  const resourceId = nanoid()
+  const event = ResourcesEvents.Created({
+    resourceId,
+    schemaId: TimesheetsSchema.timesheet,
+    createdBy,
+    belongsTo: workspaceId,
+    location: timesheets,
+    name: `timesheet-${periodStart}-${resourceId}.json`,
+    content,
+  })
+
+  const created = await commitResource(event)
+  log?.info?.(`[timesheets] Created timesheet ${resourceId}`)
+
+  return toTimesheetDto({ id: resourceId, content, ...created })
+}

package/src/delete-timesheet.flow.js

@@ -0,0 +1,41 @@
+import createAndSaveTimesheetFlow from './create-and-save-timesheet.flow.js'
+import { metadata as OpenDelete } from './open-delete.action.js'
+import { metadata as DeleteTimesheet } from './delete.action.js'
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/delete-timesheet',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+  timeout: 150_000,
+}
+
+/**
+ * After creating and saving a timesheet, open delete from the panel, confirm,
+ * and assert the saved row leaves the list.
+ */
+export default {
+  title: 'Delete timesheet',
+  description:
+    'Signed-in user creates and saves a timesheet, deletes it from the panel confirm dialog, and sees it leave the list',
+  steps: [
+    ...createAndSaveTimesheetFlow.steps,
+    { result: { action: OpenDelete, timeout: 10000 } },
+    { action: OpenDelete },
+    { result: { action: DeleteTimesheet, timeout: 10000 } },
+    { action: DeleteTimesheet },
+    {
+      result: {
+        selector: '[data-timesheet-status="saved"]',
+        hidden: true,
+        timeout: 20000,
+      },
+    },
+    {
+      result: {
+        selector: '[data-timesheet-panel]',
+        hidden: true,
+        timeout: 10000,
+      },
+    },
+  ],
+}

package/src/disable-timesheets.flow.js

@@ -0,0 +1,58 @@
+import enableTimesheetsFlow from './enable-timesheets.flow.js'
+import { DisableService, EnableService } from '@ossy/workspaces'
+
+const TIMESHEETS = '@ossy/timesheets'
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/disable-timesheets',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+  timeout: 120_000,
+}
+
+/**
+ * After enabling timesheets, disable the package from the catalog detail
+ * toggle and confirm the timesheets home returns to the sales (off) state.
+ */
+export default {
+  title: 'Disable timesheets',
+  description:
+    'Signed-in user enables timesheets, disables it from the package catalog, and sees the sales home again',
+  steps: [
+    ...enableTimesheetsFlow.steps,
+    { page: '@packages/detail', params: { packageSlug: 'timesheets' } },
+    {
+      result: {
+        action: { ...DisableService, service: TIMESHEETS },
+        timeout: 15000,
+      },
+    },
+    {
+      result: {
+        selector: `[data-package-service="${TIMESHEETS}"][data-service-enabled="true"]`,
+        timeout: 10000,
+      },
+    },
+    { action: { ...DisableService, service: TIMESHEETS } },
+    {
+      result: {
+        action: { ...EnableService, service: TIMESHEETS },
+        timeout: 20000,
+      },
+    },
+    {
+      result: {
+        selector: `[data-package-service="${TIMESHEETS}"][data-service-enabled="false"]`,
+        timeout: 10000,
+      },
+    },
+    { page: '@timesheets/home' },
+    { result: { selector: '[data-timesheets-status="off"]', timeout: 20000 } },
+    {
+      result: {
+        action: { ...EnableService, service: TIMESHEETS },
+        timeout: 10000,
+      },
+    },
+  ],
+}

package/src/enable-timesheets.flow.js

@@ -0,0 +1,24 @@
+import signUpFlow from '@ossy/authentication/sign-up.flow.js'
+import { EnableService } from '@ossy/workspaces'
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/enable-timesheets',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+}
+
+/**
+ * New workspace owner signs up and enables timesheets from the sales home.
+ */
+export default {
+  title: 'Enable timesheets',
+  description:
+    'New user registers, verifies email, and activates timesheets from the timesheets home sales page',
+  steps: [
+    ...signUpFlow.steps,
+    { page: '@timesheets/home' },
+    { result: { action: { ...EnableService, service: '@ossy/timesheets' }, timeout: 15000 } },
+    { action: { ...EnableService, service: '@ossy/timesheets' } },
+    { result: { selector: '[data-timesheets-status="on"]', timeout: 20000 } },
+  ],
+}

package/src/export-csv.action.js

@@ -0,0 +1,7 @@
+/** Client-only — downloads the open timesheet as CSV. */
+export const metadata = {
+  id: '@ossy/timesheets/actions/export-csv',
+  access: 'workspace',
+  label: 'timesheets.exportCsv',
+  icon: 'list',
+}

package/src/export-pdf.action.js

@@ -0,0 +1,7 @@
+/** Client-only — downloads the open timesheet as PDF. */
+export const metadata = {
+  id: '@ossy/timesheets/actions/export-pdf',
+  access: 'workspace',
+  label: 'timesheets.exportPdf',
+  icon: 'file-document',
+}

package/src/export-png.action.js

@@ -0,0 +1,7 @@
+/** Client-only — downloads the open timesheet as a PNG image. */
+export const metadata = {
+  id: '@ossy/timesheets/actions/export-png',
+  access: 'workspace',
+  label: 'timesheets.exportPng',
+  icon: 'image',
+}

package/src/export-timesheet-csv.flow.js

@@ -0,0 +1,39 @@
+import createAndSaveTimesheetFlow from './create-and-save-timesheet.flow.js'
+import { monthPeriodBounds } from './billing-period.js'
+import { formatDateKey } from './build-prefilled-lines.js'
+import { metadata as OpenExport } from './open-export.action.js'
+import { metadata as ExportCsv } from './export-csv.action.js'
+
+const now = new Date()
+const { periodStart } = monthPeriodBounds(now.getFullYear(), now.getMonth())
+const csvFilename = `timesheet-${formatDateKey(periodStart)}.csv`
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/export-timesheet-csv',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+  timeout: 150_000,
+}
+
+/**
+ * After creating and saving a timesheet, open the panel export menu and
+ * download CSV (browser download event).
+ */
+export default {
+  title: 'Export timesheet CSV',
+  description:
+    'Signed-in user creates and saves a timesheet, opens export from the panel, and downloads CSV',
+  steps: [
+    ...createAndSaveTimesheetFlow.steps,
+    { result: { action: OpenExport, timeout: 10000 } },
+    { action: OpenExport },
+    { result: { action: ExportCsv, timeout: 10000 } },
+    {
+      download: {
+        action: ExportCsv,
+        filename: csvFilename,
+        timeout: 30000,
+      },
+    },
+  ],
+}

package/src/export-timesheet-pdf.flow.js

@@ -0,0 +1,39 @@
+import createAndSaveTimesheetFlow from './create-and-save-timesheet.flow.js'
+import { monthPeriodBounds } from './billing-period.js'
+import { timesheetExportFilename } from './export-capture.js'
+import { metadata as OpenExport } from './open-export.action.js'
+import { metadata as ExportPdf } from './export-pdf.action.js'
+
+const now = new Date()
+const { periodStart } = monthPeriodBounds(now.getFullYear(), now.getMonth())
+const pdfFilename = timesheetExportFilename(periodStart, 'pdf')
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/export-timesheet-pdf',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+  timeout: 150_000,
+}
+
+/**
+ * After creating and saving a timesheet, open the panel export menu and
+ * download PDF (browser download event from html-to-image + pdf-lib).
+ */
+export default {
+  title: 'Export timesheet PDF',
+  description:
+    'Signed-in user creates and saves a timesheet, opens export from the panel, and downloads PDF',
+  steps: [
+    ...createAndSaveTimesheetFlow.steps,
+    { result: { action: OpenExport, timeout: 10000 } },
+    { action: OpenExport },
+    { result: { action: ExportPdf, timeout: 10000 } },
+    {
+      download: {
+        action: ExportPdf,
+        filename: pdfFilename,
+        timeout: 60000,
+      },
+    },
+  ],
+}

package/src/export-timesheet-png.flow.js

@@ -0,0 +1,39 @@
+import createAndSaveTimesheetFlow from './create-and-save-timesheet.flow.js'
+import { monthPeriodBounds } from './billing-period.js'
+import { timesheetExportFilename } from './export-capture.js'
+import { metadata as OpenExport } from './open-export.action.js'
+import { metadata as ExportPng } from './export-png.action.js'
+
+const now = new Date()
+const { periodStart } = monthPeriodBounds(now.getFullYear(), now.getMonth())
+const pngFilename = timesheetExportFilename(periodStart, 'png')
+
+export const metadata = {
+  id: '@ossy/timesheets/flows/export-timesheet-png',
+  feature: 'timesheets',
+  requires: ['server', 'database'],
+  timeout: 150_000,
+}
+
+/**
+ * After creating and saving a timesheet, open the panel export menu and
+ * download PNG (browser download event from html-to-image capture).
+ */
+export default {
+  title: 'Export timesheet PNG',
+  description:
+    'Signed-in user creates and saves a timesheet, opens export from the panel, and downloads PNG',
+  steps: [
+    ...createAndSaveTimesheetFlow.steps,
+    { result: { action: OpenExport, timeout: 10000 } },
+    { action: OpenExport },
+    { result: { action: ExportPng, timeout: 10000 } },
+    {
+      download: {
+        action: ExportPng,
+        filename: pngFilename,
+        timeout: 60000,
+      },
+    },
+  ],
+}

package/src/generate.task.js

@@ -1,10 +1,5 @@
-import { nanoid } from 'nanoid'
-import { ResourcesEvents, commitResource } from '@ossy/resources/server'
-import { TimesheetsSchema } from './schema-ids.js'
-import { timesheets } from './locations.js'
-import { buildPrefilledLines, monthPeriodBounds } from './build-prefilled-lines.js'
-import { DEFAULT_HOLIDAY_LOCALE, resolveHolidayLocale } from './holiday-locale.js'
-import { toTimesheetDto, optionalReference } from './timesheet-resources.js'
+import { monthPeriodBounds } from './billing-period.js'
+import { createTimesheetDraft } from './create-timesheet-draft.js'
 
 export const metadata = { id: '@ossy/timesheets/tasks/generate' }
 
@@ -37,46 +32,14 @@ export async function run ({ payload, req, log }) {
     ;({ periodStart, periodEnd } = monthPeriodBounds(Number(year), Number(monthIndex)))
   }
 
-  periodStart = Number(periodStart)
-  periodEnd = Number(periodEnd)
-
-  if (!Number.isFinite(periodStart) || !Number.isFinite(periodEnd) || periodEnd < periodStart) {
-    throw Object.assign(new Error('invalid period'), { status: 400 })
-  }
-
-  const holidayLocale = resolveHolidayLocale(payloadLocale, DEFAULT_HOLIDAY_LOCALE)
-
-  log?.info(
-    `[timesheets/tasks/generate] period ${periodStart}–${periodEnd} for workspace ${workspaceId} (locale ${holidayLocale})`,
-  )
-
-  const employeeId = optionalReference(payload?.employeeId)
-  const contractId = optionalReference(payload?.contractId)
-
-  const lines = buildPrefilledLines(periodStart, periodEnd, holidayLocale)
-  const content = {
+  return createTimesheetDraft({
+    workspaceId,
     periodStart,
     periodEnd,
-    status: 'draft',
-    holidayLocale,
-    lines,
-    ...(employeeId ? { employeeId } : {}),
-    ...(contractId ? { contractId } : {}),
-  }
-
-  const resourceId = nanoid()
-  const event = ResourcesEvents.Created({
-    resourceId,
-    schemaId: TimesheetsSchema.timesheet,
+    locale: payloadLocale,
+    employeeId: payload?.employeeId,
+    contractId: payload?.contractId,
     createdBy: req?.userId ?? 'system',
-    belongsTo: workspaceId,
-    location: timesheets,
-    name: `timesheet-${periodStart}-${resourceId}.json`,
-    content,
+    log,
   })
-
-  const created = await commitResource(event)
-  log?.info(`[timesheets/tasks/generate] Created timesheet ${resourceId}`)
-
-  return toTimesheetDto({ id: resourceId, content, ...created })
 }

package/src/index.js

@@ -11,11 +11,25 @@ export { metadata as ListTimesheets } from './list.action.js'
 export { metadata as GetTimesheet } from './get.action.js'
 export { metadata as DeleteTimesheet } from './delete.action.js'
 export { metadata as OpenNewTimesheet } from './open-new.action.js'
+export { metadata as OpenDeleteTimesheet } from './open-delete.action.js'
+export { metadata as OpenExportTimesheet } from './open-export.action.js'
+export { metadata as ExportTimesheetCsv } from './export-csv.action.js'
+export { metadata as ExportTimesheetPng } from './export-png.action.js'
+export { metadata as ExportTimesheetPdf } from './export-pdf.action.js'
 export { invokeErrorMessage } from './invoke-error-message.js'
 export { downloadTimesheetCsv } from './download-timesheet-csv.js'
 export { downloadTimesheetImage } from './download-timesheet-image.js'
 export { downloadTimesheetPdf } from './download-timesheet-pdf.js'
 export { buildPrefilledLines, monthPeriodBounds, WORKDAY_HOURS } from './build-prefilled-lines.js'
+export {
+  BILLING_PERIODS,
+  DEFAULT_BILLING_PERIOD,
+  findTimesheetForContractPeriod,
+  isContractActive,
+  normalizeBillingPeriod,
+  periodForContract,
+  weekPeriodBounds,
+} from './billing-period.js'
 export { resolveHolidayLocale, DEFAULT_HOLIDAY_LOCALE, HOLIDAY_COUNTRY_CODES } from './holiday-locale.js'
 export { Timesheet } from './Timesheet.jsx'
 export { TimesheetExportCard } from './TimesheetExportCard.jsx'

package/src/open-delete.action.js

@@ -0,0 +1,7 @@
+/** Client-only — opens the timesheet delete confirmation dialog. */
+export const metadata = {
+  id: '@ossy/timesheets/actions/open-delete',
+  access: 'workspace',
+  label: 'timesheets.delete',
+  icon: 'trash-empty',
+}

package/src/open-export.action.js

@@ -0,0 +1,7 @@
+/** Client-only — opens the timesheet export menu. */
+export const metadata = {
+  id: '@ossy/timesheets/actions/open-export',
+  access: 'workspace',
+  label: 'timesheets.export',
+  icon: 'software-download',
+}