@ossy/timesheets 3.9.0 → 3.10.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.10.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.0.9",
+    "@ossy/resources": "^3.10.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": "198084eb98871876396ae625d043dd0f03aa0325"
 }

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]
+}

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-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/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

@@ -16,6 +16,15 @@ 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/send-timesheet-reminder.task.js

@@ -0,0 +1,76 @@
+import { viewResource } from '@ossy/resources/server'
+import { TimesheetsSchema } from './schema-ids.js'
+import TimesheetReminderEmail, { subject as assignedSubject } from './timesheet-reminder.email.jsx'
+import {
+  formatPeriodLabel,
+  resolveTimesheetReminderRecipient,
+  shouldNotifyTimesheetCreated,
+  timesheetAssignedUrl,
+} from './timesheet-reminder.js'
+import { optionalReference } from './timesheet-refs.js'
+
+export const metadata = {
+  id: '@ossy/timesheets/tasks/send-reminder',
+  triggers: [
+    { type: TimesheetsSchema.timesheet, event: 'Created' },
+  ],
+}
+
+/**
+ * Email the linked employee when an auto-generated timesheet is created.
+ * Manual generate does not notify. Created fires once, so there is no daily cron.
+ */
+export async function run ({ event, log, integrations }) {
+  if (!shouldNotifyTimesheetCreated(event)) {
+    return { sent: 0, skipped: 1 }
+  }
+
+  const content = event.payload?.content ?? {}
+  const resourceId = event.resourceId
+  const timesheet = { id: resourceId, belongsTo: event.payload?.belongsTo, content }
+
+  const employeeId = optionalReference(content.employeeId)?.resourceId
+  const contractId = optionalReference(content.contractId)?.resourceId
+
+  const [employee, contract] = await Promise.all([
+    employeeId ? viewResource(employeeId).catch(() => null) : null,
+    contractId ? viewResource(contractId).catch(() => null) : null,
+  ])
+
+  const recipient = resolveTimesheetReminderRecipient(
+    employee ? [employee] : [],
+    timesheet,
+  )
+  if (!recipient) {
+    log?.warn(`[timesheets/tasks/send-reminder] no employee email for timesheet ${resourceId}`)
+    return { sent: 0, skipped: 1 }
+  }
+
+  const emailClient = integrations?.get?.('email')
+  if (!emailClient) {
+    log?.warn('[timesheets/tasks/send-reminder] No email integration available, skipping')
+    return { sent: 0, skipped: 1 }
+  }
+
+  const clientName = contract?.content?.clientName ?? null
+  const periodLabel = formatPeriodLabel(content.periodStart, content.periodEnd)
+  const timesheetsUrl = timesheetAssignedUrl(resourceId)
+
+  await emailClient.sendTemplate(
+    TimesheetReminderEmail,
+    {
+      employeeName: recipient.name,
+      clientName,
+      periodLabel,
+      timesheetsUrl,
+    },
+    {
+      to: recipient.email,
+      from: 'noreply@ossy.se',
+      subject: assignedSubject,
+    },
+  )
+
+  log?.info(`[timesheets/tasks/send-reminder] Assigned-timesheet email sent to ${recipient.email}`)
+  return { sent: 1, skipped: 0 }
+}

package/src/timesheet-dto.js

@@ -0,0 +1,26 @@
+import { optionalReference } from './timesheet-refs.js'
+
+export { optionalReference } from './timesheet-refs.js'
+
+/** Newest sheet for a period. Generate always creates a new resource; use get-by-id for a specific sheet. */
+export function findTimesheetForPeriod (resources, periodStart) {
+  const matches = (resources || []).filter((r) => r.content?.periodStart === periodStart)
+  if (matches.length === 0) return null
+  return [...matches].sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))[0]
+}
+
+export function toTimesheetDto (resource) {
+  if (!resource) return null
+  return {
+    id: resource.id,
+    periodStart: resource.content?.periodStart,
+    periodEnd: resource.content?.periodEnd,
+    status: resource.content?.status ?? 'draft',
+    holidayLocale: resource.content?.holidayLocale ?? null,
+    employeeId: optionalReference(resource.content?.employeeId),
+    contractId: optionalReference(resource.content?.contractId),
+    lines: resource.content?.lines ?? [],
+    createdAt: resource.createdAt,
+    updatedAt: resource.updatedAt,
+  }
+}

package/src/timesheet-refs.js

@@ -0,0 +1,16 @@
+/**
+ * Normalize an optional document reference to `{ resourceId }` or `null`.
+ * Accepts a stored object, a plain id string, or empty.
+ */
+export function optionalReference (value) {
+  if (value == null || value === '') return null
+  if (typeof value === 'string') {
+    const id = value.trim()
+    return id ? { resourceId: id } : null
+  }
+  if (typeof value === 'object' && typeof value.resourceId === 'string') {
+    const id = value.resourceId.trim()
+    return id ? { resourceId: id } : null
+  }
+  return null
+}

package/src/timesheet-reminder.email.jsx

@@ -0,0 +1,47 @@
+import React from 'react'
+import { EmailLayout, EmailButton, EmailText } from '@ossy/email'
+
+export const id = '@ossy/timesheets/emails/reminder'
+export const subject = 'En tidrapport har skapats åt dig'
+
+export default function TimesheetReminderEmail ({
+  employeeName,
+  clientName,
+  periodLabel,
+  timesheetsUrl,
+}) {
+  const greeting = employeeName ? `Hej ${employeeName},` : 'Hej,'
+
+  return (
+    <EmailLayout>
+      <h1 style={{ color: '#111111', fontSize: 24, fontWeight: 700, margin: '0 0 24px' }}>
+        Du har tilldelats en tidrapport
+      </h1>
+
+      <EmailText>{greeting}</EmailText>
+
+      <EmailText>
+        En tidrapport har skapats åt dig
+        {clientName ? (
+          <>
+            {' '}för uppdraget <strong>{clientName}</strong>
+          </>
+        ) : null}
+        {periodLabel ? (
+          <>
+            {' '}för perioden <strong>{periodLabel}</strong>
+          </>
+        ) : null}
+        . Kontrollera timmarna och spara när de stämmer.
+      </EmailText>
+
+      {timesheetsUrl ? (
+        <EmailButton href={timesheetsUrl}>Öppna tidrapporten</EmailButton>
+      ) : null}
+
+      <EmailText style={{ color: '#888888', fontSize: 13 }}>
+        Du får det här mejlet för att en tidrapport skapades automatiskt utifrån ditt avtal.
+      </EmailText>
+    </EmailLayout>
+  )
+}

package/src/timesheet-reminder.js

@@ -0,0 +1,62 @@
+import { isEmailLike } from '@ossy/schema'
+import { optionalReference } from './timesheet-refs.js'
+
+/**
+ * Whether a timesheet Created event should notify the assigned employee.
+ * Manual generate does not email; auto-generate does, once, on create.
+ *
+ * @param {{ payload?: { content?: object }, resourceId?: string } | null | undefined} event
+ */
+export function shouldNotifyTimesheetCreated (event) {
+  const content = event?.payload?.content ?? {}
+  return content.autoGenerated === true && Boolean(event?.resourceId)
+}
+
+/**
+ * Resolve reminder recipient from the linked employee resource.
+ *
+ * @param {Array<{ id: string, content?: { name?: string, email?: string } }>} employees
+ * @param {{ content?: { employeeId?: unknown } }} timesheet
+ * @returns {{ email: string, name: string | null } | null}
+ */
+export function resolveTimesheetReminderRecipient (employees, timesheet) {
+  const employeeId = optionalReference(timesheet?.content?.employeeId)?.resourceId
+  if (!employeeId) return null
+
+  const employee = (employees || []).find((e) => e.id === employeeId)
+  const email = employee?.content?.email?.trim?.() ?? employee?.content?.email
+  if (!isEmailLike(email)) return null
+
+  return {
+    email: String(email).trim(),
+    name: employee?.content?.name ?? null,
+  }
+}
+
+/**
+ * Public timesheets home URL, optionally opening a specific sheet (`?r=`).
+ * Swedish email copy uses `/tidrapporter`.
+ *
+ * @param {string} [resourceId]
+ * @param {string} [origin]
+ */
+export function timesheetAssignedUrl (resourceId, origin = process.env.WEB_CLIENT_DOMAIN) {
+  const base = String(origin || '').replace(/\/$/, '')
+  if (!base) return null
+  const path = '/tidrapporter'
+  if (!resourceId) return `${base}${path}`
+  return `${base}${path}?r=${encodeURIComponent(resourceId)}`
+}
+
+/**
+ * Format a period for email copy (local calendar dates).
+ * @param {number} periodStart
+ * @param {number} periodEnd
+ * @param {string} [locale]
+ */
+export function formatPeriodLabel (periodStart, periodEnd, locale = 'sv-SE') {
+  const start = new Date(periodStart)
+  const end = new Date(periodEnd)
+  const opts = { year: 'numeric', month: 'long', day: 'numeric' }
+  return `${start.toLocaleDateString(locale, opts)} – ${end.toLocaleDateString(locale, opts)}`
+}

package/src/timesheet-reminder.spec.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  formatPeriodLabel,
+  resolveTimesheetReminderRecipient,
+  shouldNotifyTimesheetCreated,
+  timesheetAssignedUrl,
+} from './timesheet-reminder.js'
+
+describe('shouldNotifyTimesheetCreated', () => {
+  it('notifies only auto-generated creates', () => {
+    expect(shouldNotifyTimesheetCreated({
+      resourceId: 'sheet-1',
+      payload: { content: { autoGenerated: true } },
+    })).toBe(true)
+
+    expect(shouldNotifyTimesheetCreated({
+      resourceId: 'sheet-2',
+      payload: { content: { autoGenerated: false } },
+    })).toBe(false)
+
+    expect(shouldNotifyTimesheetCreated({
+      resourceId: 'sheet-3',
+      payload: { content: {} },
+    })).toBe(false)
+
+    expect(shouldNotifyTimesheetCreated({
+      payload: { content: { autoGenerated: true } },
+    })).toBe(false)
+  })
+})
+
+describe('resolveTimesheetReminderRecipient', () => {
+  it('requires a linked employee with a valid email', () => {
+    const employees = [
+      { id: 'emp-1', content: { name: 'Ada', email: 'ada@example.com' } },
+      { id: 'emp-2', content: { name: 'Bob', email: 'not-an-email' } },
+    ]
+
+    expect(resolveTimesheetReminderRecipient(employees, {
+      content: { employeeId: 'emp-1' },
+    })).toEqual({ email: 'ada@example.com', name: 'Ada' })
+
+    expect(resolveTimesheetReminderRecipient(employees, {
+      content: { employeeId: 'emp-2' },
+    })).toBe(null)
+
+    expect(resolveTimesheetReminderRecipient(employees, {
+      content: {},
+    })).toBe(null)
+  })
+})
+
+describe('timesheetAssignedUrl', () => {
+  it('builds the Swedish home URL with an optional sheet query', () => {
+    expect(timesheetAssignedUrl(undefined, 'https://app.ossy.se/')).toBe(
+      'https://app.ossy.se/tidrapporter',
+    )
+    expect(timesheetAssignedUrl('sheet-1', 'https://app.ossy.se')).toBe(
+      'https://app.ossy.se/tidrapporter?r=sheet-1',
+    )
+    expect(timesheetAssignedUrl('sheet-1', '')).toBe(null)
+  })
+})
+
+describe('formatPeriodLabel', () => {
+  it('formats inclusive local dates', () => {
+    const label = formatPeriodLabel(
+      new Date(2026, 7, 1).getTime(),
+      new Date(2026, 7, 31).getTime(),
+      'en-US',
+    )
+    expect(label).toContain('2026')
+    expect(label).toContain('–')
+  })
+})

package/src/timesheet-resources.js

@@ -1,5 +1,11 @@
 import { ResourcesQueries } from '@ossy/resources/server'
 
+export {
+  optionalReference,
+  findTimesheetForPeriod,
+  toTimesheetDto,
+} from './timesheet-dto.js'
+
 /**
  * List timesheet resources by schema id (and optional workspace).
  */
@@ -8,43 +14,3 @@ export function getTimesheetResources ({ schemaId, belongsTo } = {}) {
   if (belongsTo) query.belongsTo = belongsTo
   return ResourcesQueries.GetResources(query)
 }
-
-/** Newest sheet for a period. Generate always creates a new resource; use get-by-id for a specific sheet. */
-export function findTimesheetForPeriod (resources, periodStart) {
-  const matches = (resources || []).filter((r) => r.content?.periodStart === periodStart)
-  if (matches.length === 0) return null
-  return [...matches].sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))[0]
-}
-
-/**
- * Normalize an optional document reference to `{ resourceId }` or `null`.
- * Accepts a stored object, a plain id string, or empty.
- */
-export function optionalReference (value) {
-  if (value == null || value === '') return null
-  if (typeof value === 'string') {
-    const id = value.trim()
-    return id ? { resourceId: id } : null
-  }
-  if (typeof value === 'object' && typeof value.resourceId === 'string') {
-    const id = value.resourceId.trim()
-    return id ? { resourceId: id } : null
-  }
-  return null
-}
-
-export function toTimesheetDto (resource) {
-  if (!resource) return null
-  return {
-    id: resource.id,
-    periodStart: resource.content?.periodStart,
-    periodEnd: resource.content?.periodEnd,
-    status: resource.content?.status ?? 'draft',
-    holidayLocale: resource.content?.holidayLocale ?? null,
-    employeeId: optionalReference(resource.content?.employeeId),
-    contractId: optionalReference(resource.content?.contractId),
-    lines: resource.content?.lines ?? [],
-    createdAt: resource.createdAt,
-    updatedAt: resource.updatedAt,
-  }
-}

package/src/timesheet-resources.spec.js

@@ -3,7 +3,7 @@ import {
   findTimesheetForPeriod,
   optionalReference,
   toTimesheetDto,
-} from './timesheet-resources.js'
+} from './timesheet-dto.js'
 
 describe('optionalReference', () => {
   it('normalizes ids, objects, and empty values', () => {

package/src/timesheet.schema.js

@@ -38,6 +38,11 @@ export default {
       of: TimesheetRefs.contract,
       description: 'Optional contract this timesheet belongs to',
     },
+    {
+      name: 'autoGenerated',
+      type: 'boolean',
+      description: 'Set when the daily auto-generate cron created this sheet',
+    },
     // `lines` is stored in content (array of day rows) — same nested-content pattern as booking availability.
   ],
 }