@ossy/timesheets 3.9.0 → 3.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ossy/timesheets",
   "description": "Timesheets — generate, review, save, and export monthly work hours",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
@@ -17,7 +17,9 @@
     "src": "./src"
   },
   "dependencies": {
-    "@ossy/resources": "^3.9.0",
+    "@ossy/email": "^3.11.0",
+    "@ossy/resources": "^3.11.0",
+    "@ossy/schema": "^3.8.0",
     "html-to-image": "^1.11.13",
     "nanoid": "^5.1.11",
     "pdf-lib": "^1.17.1"
@@ -41,5 +43,5 @@
     "/src",
     "README.md"
   ],
-  "gitHead": "f404be69becb27a1fd853a6ff1903554e76e7d17"
+  "gitHead": "53ff8456920e09151c9d88df4a6c3ee958d811eb"
 }

package/src/TimesheetCard.jsx

@@ -33,6 +33,8 @@ export function TimesheetCard ({ timesheet, onClick, selected = false, actions }
       selected={selected}
       onClick={onClick}
       onContextMenu={handleContextMenu}
+      data-timesheet-id={timesheet?.id}
+      data-timesheet-status={status}
       leading={(
         <Icon size="s" name="calendar" style={{ fill: 'hsl(0, 0%, 80%)' }} />
       )}

package/src/TimesheetPanel.jsx

@@ -11,11 +11,16 @@ import { useTimesheetParties } from './TimesheetPartyFields.jsx'
 import { contractBillingMeta, labelForContract, labelForEmployee } from './timesheet-parties.js'
 import { metadata as GetTimesheet } from './get.action.js'
 import { metadata as SaveTimesheet } from './save.action.js'
+import { metadata as OpenDelete } from './open-delete.action.js'
+import { metadata as OpenExport } from './open-export.action.js'
+import { metadata as ExportCsv } from './export-csv.action.js'
+import { metadata as ExportPng } from './export-png.action.js'
+import { metadata as ExportPdf } from './export-pdf.action.js'
 
 /**
  * Storage-style side panel for reviewing and saving a timesheet.
  */
-export function TimesheetPanel ({ timesheetId, onClose, onSaved, width = '50%' }) {
+export function TimesheetPanel ({ timesheetId, onClose, onSaved, onRequestDelete, width = '50%' }) {
   const { t } = useLocale()
   const sdk = useSdk()
   const captureRef = useRef(null)
@@ -130,6 +135,8 @@ export function TimesheetPanel ({ timesheetId, onClose, onSaved, width = '50%' }
       surface="primary"
       bordered
       roundness="xs"
+      data-timesheet-panel={timesheetId || undefined}
+      data-timesheet-panel-status={timesheet?.status || (loading ? 'loading' : undefined)}
       style={{ height: '100%', width, minHeight: 0, minWidth: 0, flexShrink: 0 }}
     >
       <View.Item>
@@ -151,6 +158,8 @@ export function TimesheetPanel ({ timesheetId, onClose, onSaved, width = '50%' }
           <Dropdown
             trigger={(
               <Button
+                {...OpenExport}
+                label={undefined}
                 variant="command"
                 prefix="software-download"
                 disabled={exportDisabled}
@@ -160,25 +169,26 @@ export function TimesheetPanel ({ timesheetId, onClose, onSaved, width = '50%' }
           >
             <ContextMenu roundness="s" surface="primary">
               <ContextMenu.Item
+                {...ExportCsv}
                 prefix="list"
-                label="timesheets.exportCsv"
                 onClick={() => runExport('csv')}
               />
               <ContextMenu.Item
+                {...ExportPng}
                 prefix="image"
-                label="timesheets.exportPng"
                 onClick={() => runExport('png')}
               />
               <ContextMenu.Item
+                {...ExportPdf}
                 prefix="file-document"
-                label="timesheets.exportPdf"
                 onClick={() => runExport('pdf')}
               />
             </ContextMenu>
           </Dropdown>
 
           <Button
-            id={SaveTimesheet.id}
+            {...SaveTimesheet}
+            label={undefined}
             variant="command"
             prefix="check"
             disabled={!timesheet?.id || saving || loading}
@@ -186,6 +196,18 @@ export function TimesheetPanel ({ timesheetId, onClose, onSaved, width = '50%' }
             onClick={handleSave}
           />
 
+          {onRequestDelete && (
+            <Button
+              {...OpenDelete}
+              label={undefined}
+              variant="command-danger"
+              prefix="trash-empty"
+              disabled={!timesheet?.id || loading}
+              aria-label={t('timesheets.delete')}
+              onClick={() => onRequestDelete(timesheet)}
+            />
+          )}
+
           {onClose && (
             <Button
               prefix="close"

package/src/TimesheetsFreeTool.jsx

@@ -17,6 +17,10 @@ import { downloadTimesheetPdf } from './download-timesheet-pdf.js'
 import { invokeErrorMessage } from './invoke-error-message.js'
 import { sampleShowcaseTimesheet } from './sample-showcase-timesheet.js'
 import { timesheetsAuthHref } from './timesheets-auth-return.js'
+import { metadata as OpenExport } from './open-export.action.js'
+import { metadata as ExportCsv } from './export-csv.action.js'
+import { metadata as ExportPng } from './export-png.action.js'
+import { metadata as ExportPdf } from './export-pdf.action.js'
 
 /**
  * Client-only timesheet for the sales page — prefilled, editable, exportable.
@@ -230,29 +234,29 @@ export function TimesheetsFreeTool ({
             <Dropdown
               trigger={(
                 <Button
+                  {...OpenExport}
                   variant="secondary"
                   prefix="software-download"
                   suffix="chevron-down"
                   disabled={exportDisabled}
-                >
-                  {exporting ? t('timesheets.exporting') : t('timesheets.export')}
-                </Button>
+                  label={exporting ? 'timesheets.exporting' : OpenExport.label}
+                />
               )}
             >
               <ContextMenu roundness="s" surface="primary">
                 <ContextMenu.Item
+                  {...ExportCsv}
                   prefix="list"
-                  label="timesheets.exportCsv"
                   onClick={() => runExport('csv')}
                 />
                 <ContextMenu.Item
+                  {...ExportPng}
                   prefix="image"
-                  label="timesheets.exportPng"
                   onClick={() => runExport('png')}
                 />
                 <ContextMenu.Item
+                  {...ExportPdf}
                   prefix="file-document"
-                  label="timesheets.exportPdf"
                   onClick={() => runExport('pdf')}
                 />
               </ContextMenu>

package/src/TimesheetsProductHome.jsx

@@ -16,6 +16,10 @@ import { metadata as ListTimesheets } from './list.action.js'
 import { metadata as GenerateTimesheet } from './generate.action.js'
 import { metadata as OpenNewTimesheet } from './open-new.action.js'
 import { metadata as DeleteTimesheet } from './delete.action.js'
+import { metadata as OpenDelete } from './open-delete.action.js'
+import { metadata as ExportCsv } from './export-csv.action.js'
+import { metadata as ExportPng } from './export-png.action.js'
+import { metadata as ExportPdf } from './export-pdf.action.js'
 import { HolidayLocaleSelect } from './HolidayLocaleSelect.jsx'
 import { resolveHolidayLocale } from './holiday-locale.js'
 
@@ -212,6 +216,7 @@ export default function TimesheetsProductHome () {
     <>
       <Page
         scroll
+        data-timesheets-status="on"
         title="timesheets.home.title"
         near={statusTags.length > 0 ? <Tags tags={statusTags} size="s" /> : undefined}
         description="timesheets.home.description"
@@ -232,7 +237,8 @@ export default function TimesheetsProductHome () {
                     <Text as="h2" variant="small" weight="medium" text="timesheets.listTitle" />
                   </View.Item>
                   <Button
-                    id={OpenNewTimesheet.id}
+                    {...OpenNewTimesheet}
+                    label={undefined}
                     variant="command"
                     prefix="add"
                     aria-label={t('timesheets.new')}
@@ -272,25 +278,26 @@ export default function TimesheetsProductHome () {
                           />,
                           <ContextMenu.Item
                             key="csv"
+                            {...ExportCsv}
                             prefix="list"
-                            label="timesheets.exportCsv"
                             onClick={() => requestExport(sheet, 'csv')}
                           />,
                           <ContextMenu.Item
                             key="png"
+                            {...ExportPng}
                             prefix="image"
-                            label="timesheets.exportPng"
                             onClick={() => requestExport(sheet, 'png')}
                           />,
                           <ContextMenu.Item
                             key="pdf"
+                            {...ExportPdf}
                             prefix="file-document"
-                            label="timesheets.exportPdf"
                             onClick={() => requestExport(sheet, 'pdf')}
                           />,
                           <ContextMenu.Separator key="separator" />,
                           <ContextMenu.Item
                             key="delete"
+                            {...OpenDelete}
                             variant="command-danger"
                             prefix="trash-empty"
                             label="timesheets.delete"
@@ -309,6 +316,7 @@ export default function TimesheetsProductHome () {
             timesheetId={selectedResourceId}
             onClose={clearSelectedResourceId}
             onSaved={refreshList}
+            onRequestDelete={setSheetToDelete}
           />
         </View>
       </Page>
@@ -328,7 +336,7 @@ export default function TimesheetsProductHome () {
                     onClick: () => setSheetToDelete(null),
                   },
                   {
-                    label: 'timesheets.delete',
+                    ...DeleteTimesheet,
                     variant: 'command-danger',
                     disabled: deleting,
                     onClick: confirmDelete,
@@ -410,13 +418,12 @@ export default function TimesheetsProductHome () {
                   onClick={closeCreateModal}
                 />
                 <Button
-                  id={GenerateTimesheet.id}
+                  {...GenerateTimesheet}
+                  label={generating ? 'timesheets.loading' : GenerateTimesheet.label}
                   variant="cta"
                   disabled={generating || !selected}
                   onClick={handleGenerate}
-                >
-                  {generating ? t('timesheets.loading') : t('timesheets.generate')}
-                </Button>
+                />
               </View>
             </View>
           </View>

package/src/auto-generate-timesheets.js

@@ -0,0 +1,70 @@
+import { TimesheetRefs, TimesheetsSchema } from './schema-ids.js'
+import {
+  findTimesheetForContractPeriod,
+  isContractActive,
+  periodForContract,
+} from './billing-period.js'
+import { optionalReference } from './timesheet-refs.js'
+
+/** Company basic-info schema (consultancy) — used for holiday locale. */
+export const COMPANY_BASIC_INFO_SCHEMA = '@ossy/consultancy/schema/company-basic-info'
+
+/**
+ * Pick holiday locale for a workspace from company basic-info resources.
+ * @param {Array<{ belongsTo?: string, content?: { holidayLocale?: string } }>} companyResources
+ * @param {string} workspaceId
+ * @returns {string | undefined}
+ */
+export function holidayLocaleForWorkspace (companyResources, workspaceId) {
+  const match = (companyResources || []).find((r) => r.belongsTo === workspaceId)
+  return match?.content?.holidayLocale
+}
+
+/**
+ * Decide which active contracts need a new auto-generated sheet for `asOf`.
+ *
+ * @param {object} input
+ * @param {Array<{ id: string, belongsTo?: string, content?: object }>} input.contracts
+ * @param {Array<{ id: string, belongsTo?: string, createdAt?: number, content?: object }>} input.timesheets
+ * @param {Date | number} [input.asOf]
+ * @returns {Array<{
+ *   contractId: string,
+ *   workspaceId: string,
+ *   employeeId: string | null,
+ *   periodStart: number,
+ *   periodEnd: number,
+ *   billingPeriod: string,
+ * }>}
+ */
+export function contractsNeedingTimesheets ({ contracts, timesheets, asOf = Date.now() }) {
+  const needed = []
+
+  for (const contract of contracts || []) {
+    const workspaceId = contract.belongsTo
+    if (!workspaceId) continue
+    if (!isContractActive(contract.content, asOf)) continue
+
+    const { periodStart, periodEnd } = periodForContract(contract.content, asOf)
+    const existing = findTimesheetForContractPeriod(timesheets, contract.id, periodStart)
+    if (existing) continue
+
+    const employeeId = optionalReference(contract.content?.employeeId)?.resourceId ?? null
+
+    needed.push({
+      contractId: contract.id,
+      workspaceId,
+      employeeId,
+      periodStart,
+      periodEnd,
+      billingPeriod: contract.content?.billingPeriod === 'weekly' ? 'weekly' : 'monthly',
+    })
+  }
+
+  return needed
+}
+
+export const AUTO_GENERATE_QUERY = {
+  contracts: { type: TimesheetRefs.contract },
+  timesheets: { type: TimesheetsSchema.timesheet },
+  companies: { type: COMPANY_BASIC_INFO_SCHEMA },
+}

package/src/auto-generate-timesheets.spec.js

@@ -0,0 +1,90 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  contractsNeedingTimesheets,
+  holidayLocaleForWorkspace,
+} from './auto-generate-timesheets.js'
+
+describe('holidayLocaleForWorkspace', () => {
+  it('returns the company holidayLocale for the workspace', () => {
+    const companies = [
+      { belongsTo: 'ws-a', content: { holidayLocale: 'SE' } },
+      { belongsTo: 'ws-b', content: { holidayLocale: 'NO' } },
+    ]
+    expect(holidayLocaleForWorkspace(companies, 'ws-b')).toBe('NO')
+    expect(holidayLocaleForWorkspace(companies, 'ws-missing')).toBe(undefined)
+  })
+})
+
+describe('contractsNeedingTimesheets', () => {
+  const augustStart = new Date(2026, 7, 1).setHours(0, 0, 0, 0)
+  const asOf = new Date(2026, 7, 19)
+
+  it('skips inactive contracts and existing sheets', () => {
+    const contracts = [
+      {
+        id: 'c-active',
+        belongsTo: 'ws-1',
+        content: {
+          billingPeriod: 'monthly',
+          employeeId: 'emp-1',
+          startDate: new Date(2026, 0, 1).getTime(),
+        },
+      },
+      {
+        id: 'c-done',
+        belongsTo: 'ws-1',
+        content: {
+          billingPeriod: 'monthly',
+          startDate: new Date(2025, 0, 1).getTime(),
+          endDate: new Date(2026, 0, 1).getTime(),
+        },
+      },
+      {
+        id: 'c-has-sheet',
+        belongsTo: 'ws-1',
+        content: {
+          billingPeriod: 'monthly',
+          startDate: new Date(2026, 0, 1).getTime(),
+        },
+      },
+    ]
+
+    const timesheets = [
+      {
+        id: 'sheet-1',
+        createdAt: 1,
+        content: { periodStart: augustStart, contractId: 'c-has-sheet' },
+      },
+    ]
+
+    expect(contractsNeedingTimesheets({ contracts, timesheets, asOf })).toEqual([
+      {
+        contractId: 'c-active',
+        workspaceId: 'ws-1',
+        employeeId: 'emp-1',
+        periodStart: augustStart,
+        periodEnd: new Date(2026, 7, 31).setHours(0, 0, 0, 0),
+        billingPeriod: 'monthly',
+      },
+    ])
+  })
+
+  it('uses weekly period bounds when configured', () => {
+    const contracts = [{
+      id: 'c-week',
+      belongsTo: 'ws-2',
+      content: {
+        billingPeriod: 'weekly',
+        employeeId: { resourceId: 'emp-9' },
+        startDate: new Date(2026, 0, 1).getTime(),
+      },
+    }]
+
+    const [needed] = contractsNeedingTimesheets({ contracts, timesheets: [], asOf })
+    expect(needed.contractId).toBe('c-week')
+    expect(needed.employeeId).toBe('emp-9')
+    expect(needed.billingPeriod).toBe('weekly')
+    expect(new Date(needed.periodStart).getDay()).toBe(1)
+    expect(new Date(needed.periodEnd).getDay()).toBe(0)
+  })
+})

package/src/auto-generate-timesheets.task.js

@@ -0,0 +1,60 @@
+import { ResourcesQueries } from '@ossy/resources/server'
+import {
+  AUTO_GENERATE_QUERY,
+  contractsNeedingTimesheets,
+  holidayLocaleForWorkspace,
+} from './auto-generate-timesheets.js'
+import { createTimesheetDraft } from './create-timesheet-draft.js'
+
+export const metadata = {
+  id: '@ossy/timesheets/tasks/auto-generate',
+  // Daily at 06:00 UTC — create sheets when a billing period is open
+  schedule: '0 6 * * *',
+}
+
+/**
+ * Auto-generate draft timesheets for active consultancy contracts based on
+ * each contract's billing period (weekly / monthly). Idempotent per
+ * (workspace, contractId, periodStart).
+ */
+export async function run ({ log }) {
+  const now = Date.now()
+
+  const [contracts, timesheets, companies] = await Promise.all([
+    ResourcesQueries.GetResources(AUTO_GENERATE_QUERY.contracts),
+    ResourcesQueries.GetResources(AUTO_GENERATE_QUERY.timesheets),
+    ResourcesQueries.GetResources(AUTO_GENERATE_QUERY.companies),
+  ])
+
+  const needed = contractsNeedingTimesheets({ contracts, timesheets, asOf: now })
+  log?.info(`[timesheets/tasks/auto-generate] ${needed.length} contract(s) need a sheet`)
+
+  let created = 0
+  let failed = 0
+
+  for (const item of needed) {
+    try {
+      const locale = holidayLocaleForWorkspace(companies, item.workspaceId)
+      await createTimesheetDraft({
+        workspaceId: item.workspaceId,
+        periodStart: item.periodStart,
+        periodEnd: item.periodEnd,
+        locale,
+        employeeId: item.employeeId,
+        contractId: item.contractId,
+        createdBy: metadata.id,
+        autoGenerated: true,
+        log,
+      })
+      created++
+    } catch (err) {
+      failed++
+      log?.error(
+        `[timesheets/tasks/auto-generate] failed for contract ${item.contractId}`,
+        err,
+      )
+    }
+  }
+
+  return { created, failed, candidates: needed.length }
+}

package/src/billing-period.js

@@ -0,0 +1,123 @@
+import { optionalReference } from './timesheet-refs.js'
+
+export const BILLING_PERIODS = Object.freeze(['weekly', 'monthly'])
+export const DEFAULT_BILLING_PERIOD = 'monthly'
+
+/**
+ * @param {unknown} value
+ * @returns {'weekly' | 'monthly'}
+ */
+export function normalizeBillingPeriod (value) {
+  if (value === 'weekly' || value === 'monthly') return value
+  return DEFAULT_BILLING_PERIOD
+}
+
+/**
+ * @param {unknown} value — Unix ms, ISO string, or Date
+ * @returns {number | null}
+ */
+export function toMs (value) {
+  if (value == null || value === '') return null
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.getTime()
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value)
+    if (!Number.isNaN(parsed)) return parsed
+  }
+  return null
+}
+
+/**
+ * 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(),
+  }
+}
+
+/**
+ * ISO-week (Mon–Sun) period bounds as local midnights, returned as Unix ms.
+ * @param {Date | number} [asOf]
+ */
+export function weekPeriodBounds (asOf = Date.now()) {
+  const ref = new Date(asOf)
+  ref.setHours(0, 0, 0, 0)
+  const day = ref.getDay() // 0 Sun … 6 Sat
+  const daysFromMonday = day === 0 ? 6 : day - 1
+  const start = new Date(ref)
+  start.setDate(ref.getDate() - daysFromMonday)
+  start.setHours(0, 0, 0, 0)
+  const end = new Date(start)
+  end.setDate(start.getDate() + 6)
+  end.setHours(0, 0, 0, 0)
+  return {
+    periodStart: start.getTime(),
+    periodEnd: end.getTime(),
+  }
+}
+
+/**
+ * Billing period that contains `asOf` for a contract's billing policy.
+ * @param {{ billingPeriod?: string } | null | undefined} contract
+ * @param {Date | number} [asOf]
+ */
+export function periodForContract (contract, asOf = Date.now()) {
+  const billingPeriod = normalizeBillingPeriod(contract?.billingPeriod)
+  if (billingPeriod === 'weekly') return weekPeriodBounds(asOf)
+  const ref = new Date(asOf)
+  return monthPeriodBounds(ref.getFullYear(), ref.getMonth())
+}
+
+/**
+ * Contract is active on `asOf` when start ≤ asOf and (no end or end ≥ asOf day start).
+ * @param {{ startDate?: unknown, endDate?: unknown } | null | undefined} contract
+ * @param {Date | number} [asOf]
+ */
+export function isContractActive (contract, asOf = Date.now()) {
+  if (!contract) return false
+  const asOfMs = toMs(asOf) ?? Date.now()
+  const dayStart = new Date(asOfMs)
+  dayStart.setHours(0, 0, 0, 0)
+  const dayMs = dayStart.getTime()
+
+  const startMs = toMs(contract.startDate)
+  if (startMs != null) {
+    const startDay = new Date(startMs)
+    startDay.setHours(0, 0, 0, 0)
+    if (dayMs < startDay.getTime()) return false
+  }
+
+  const endMs = toMs(contract.endDate)
+  if (endMs != null) {
+    const endDay = new Date(endMs)
+    endDay.setHours(0, 0, 0, 0)
+    if (dayMs > endDay.getTime()) return false
+  }
+
+  return true
+}
+
+/**
+ * Newest timesheet for a contract + periodStart pair.
+ * @param {Array<{ id: string, createdAt?: number, content?: object }>} resources
+ * @param {string} contractId
+ * @param {number} periodStart
+ */
+export function findTimesheetForContractPeriod (resources, contractId, periodStart) {
+  if (!contractId || periodStart == null) return null
+  const matches = (resources || []).filter((r) => {
+    if (r.content?.periodStart !== periodStart) return false
+    const ref = optionalReference(r.content?.contractId)
+    return ref?.resourceId === contractId
+  })
+  if (matches.length === 0) return null
+  return [...matches].sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))[0]
+}