@kernhq/module-hr 0.3.0 → 0.4.0

package/migrations/meta/_journal.json

@@ -22,6 +22,13 @@
       "when": 1787601877456,
       "tag": "0002_leave",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1787634652573,
+      "tag": "0003_attendance",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-hr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Kern HR module: people, offices, org chart, calendars",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/contract/attendance.ts

@@ -0,0 +1,180 @@
+import { Timestamp, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { IsoDate, TimeZone, WallClock } from './models.js'
+
+const ws = { workspaceId: WorkspaceId }
+
+/**
+ * Attendance: who was at work, when, and for how long.
+ *
+ * Two rules shape everything here:
+ *
+ * - **Raw punches are immutable.** A wrong punch is *voided* by a correcting row, never edited. An
+ *   attendance record somebody can quietly rewrite is worth nothing in the dispute it exists for.
+ * - **The day sheet is derived.** `AttendanceDay` is a projection of punches + schedule + calendar +
+ *   leave, recomputable from scratch at any time. It is never the source of truth, so a bad
+ *   computation is a bug to fix and re-run rather than data to repair by hand.
+ */
+
+export const PunchDirection = z.enum(['in', 'out', 'break_start', 'break_end'])
+export type PunchDirection = z.infer<typeof PunchDirection>
+
+export const PunchMethod = z.enum(['web', 'mobile', 'kiosk', 'qr', 'device', 'import', 'manual'])
+export type PunchMethod = z.infer<typeof PunchMethod>
+
+/**
+ * How much the recorded instant can be trusted.
+ *
+ * `trusted` was stamped by the server as it happened. `claimed` came from a client that was offline
+ * and is asserting when it happened — believed within a policy threshold, flagged beyond it.
+ * `disputed` is a claim somebody has to look at. Client clocks lie, sometimes by accident and
+ * sometimes not, and a system that cannot say which is which cannot defend any of its numbers.
+ */
+export const PunchTrust = z.enum(['trusted', 'claimed', 'disputed'])
+export type PunchTrust = z.infer<typeof PunchTrust>
+
+export const Punch = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  direction: PunchDirection,
+  /** Server-stamped, or the client's claim when it was offline. Always an instant, never a local time. */
+  at: Timestamp,
+  /** What the client believed the time was. Kept for audit even when it disagrees. */
+  clientReportedAt: Timestamp.nullable(),
+  /** How far the client's clock was out, in milliseconds. Null when the server stamped it. */
+  skewMs: z.number().int().nullable(),
+  /** The day this belongs to, in the person's schedule zone. A night shift lands on its start date. */
+  businessDate: IsoDate,
+  /** The zone the punch actually happened in — for audit, not for attribution. */
+  timezone: TimeZone,
+  method: PunchMethod,
+  /** The office whose geofence or allowlist accepted it; any office the person is assigned to. */
+  officeId: z.uuid().nullable(),
+  deviceId: z.uuid().nullable(),
+  geo: z.object({ lat: z.number(), lng: z.number(), accuracyM: z.number().optional() }).nullable(),
+  trust: PunchTrust,
+  /** Set when a later correction voided this row. The row itself never changes otherwise. */
+  voidedByPunchId: z.uuid().nullable(),
+  note: z.string().max(500).nullable(),
+  createdAt: Timestamp,
+})
+export type Punch = z.infer<typeof Punch>
+
+export const AttendanceStatus = z.enum([
+  'present',
+  'absent',
+  'leave',
+  'holiday',
+  'weekend',
+  'partial',
+  /** Something is unpaired — usually a missing clock-out. Needs a human. */
+  'pending',
+])
+export type AttendanceStatus = z.infer<typeof AttendanceStatus>
+
+/**
+ * One person, one day, derived.
+ *
+ * Recomputable from punches, schedule, calendar and leave at any moment. `policyHash` records what
+ * produced it, so a recomputation can tell whether a row is stale; `locked` mirrors the period, so
+ * a closed month cannot silently move.
+ */
+export const AttendanceDay = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  businessDate: IsoDate,
+  scheduledMinutes: z.number().int(),
+  workedMinutes: z.number().int(),
+  breakMinutes: z.number().int(),
+  overtimeMinutes: z.number().int(),
+  lateMinutes: z.number().int(),
+  earlyLeaveMinutes: z.number().int(),
+  status: AttendanceStatus,
+  leaveRequestId: z.uuid().nullable(),
+  anomalies: z.array(z.string()),
+  firstIn: Timestamp.nullable(),
+  lastOut: Timestamp.nullable(),
+  policyHash: z.string().max(64).nullable(),
+  locked: z.boolean(),
+  computedAt: Timestamp,
+})
+export type AttendanceDay = z.infer<typeof AttendanceDay>
+
+/** A week of shifts, in wall-clock readings. Meaningless until a date and a zone arrive. */
+export const ScheduleWeek = z.record(
+  z.enum(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']),
+  z
+    .object({
+      start: WallClock,
+      end: WallClock,
+      breakMinutes: z.number().int().min(0).max(480).default(0),
+    })
+    .nullable(),
+)
+export type ScheduleWeek = z.infer<typeof ScheduleWeek>
+
+export const Schedule = z.object({
+  id: z.uuid(),
+  ...ws,
+  name: z.string().min(1).max(120),
+  kind: z.enum(['fixed', 'flexible', 'shift']),
+  week: ScheduleWeek,
+  /** `office` means the person's primary office — the default, and almost always right. */
+  tzMode: z.enum(['office', 'person', 'fixed']),
+  tz: TimeZone.nullable(),
+  graceInMinutes: z.number().int().min(0).max(240),
+  graceOutMinutes: z.number().int().min(0).max(240),
+  roundingStepMinutes: z.number().int().min(0).max(60),
+  roundingDirection: z.enum(['nearest', 'employee', 'employer']),
+  /** Close an open shift automatically after this many minutes. Null leaves it for a human. */
+  autoClockOutAfterMinutes: z.number().int().min(60).nullable(),
+  archivedAt: Timestamp.nullable(),
+})
+export type Schedule = z.infer<typeof Schedule>
+
+export const ScheduleAssignment = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  scheduleId: z.uuid(),
+  effectiveFrom: IsoDate,
+  effectiveTo: IsoDate.nullable(),
+})
+export type ScheduleAssignment = z.infer<typeof ScheduleAssignment>
+
+/**
+ * A request to fix a wrong or missing punch.
+ *
+ * It does not edit anything. Approving it writes *new* punches that void the old ones, so the
+ * original record and the correction both survive — which is the difference between a corrected
+ * timesheet and an edited one.
+ */
+export const Regularization = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  businessDate: IsoDate,
+  /** Null when the person never punched at all and is asking for the whole day to be recorded. */
+  punchId: z.uuid().nullable(),
+  proposed: z.array(z.object({ direction: PunchDirection, at: Timestamp })),
+  reason: z.string().min(1).max(1000),
+  status: z.enum(['pending', 'approved', 'rejected', 'cancelled']),
+  approvalRequestId: z.uuid().nullable(),
+  appliedAt: Timestamp.nullable(),
+  createdAt: Timestamp,
+})
+export type Regularization = z.infer<typeof Regularization>
+
+/** The person's own live state: are they clocked in, since when, on a break? */
+export const ClockState = z.object({
+  personId: z.uuid(),
+  businessDate: IsoDate,
+  clockedIn: z.boolean(),
+  onBreak: z.boolean(),
+  since: Timestamp.nullable(),
+  workedMinutesToday: z.number().int(),
+  timezone: TimeZone,
+})
+export type ClockState = z.infer<typeof ClockState>

package/src/contract/capabilities.ts

@@ -84,6 +84,24 @@ export const hrCapabilities = defineCapabilities([
     defaultEnabled: false,
     level: 2,
   },
+  {
+    id: 'attendance',
+    label: 'Attendance',
+    description: 'Clock in and out, schedules and a daily sheet',
+    dependsOn: ['core', 'calendars'],
+    // Off by default. Plenty of companies never clock anybody in, and a directory that offers a
+    // clock button to salaried staff is offering a feature nobody asked for.
+    defaultEnabled: false,
+    level: 1,
+  },
+  {
+    id: 'overtime',
+    label: 'Overtime',
+    description: 'Detect and approve time worked beyond the schedule',
+    dependsOn: ['attendance'],
+    defaultEnabled: false,
+    level: 2,
+  },
   {
     id: 'documents',
     label: 'Employee documents',
@@ -149,6 +167,24 @@ export const hrCapabilityProcedures: Record<string, readonly string[]> = {
     'leave.requests.cancel',
     'leave.team.calendar',
   ],
+  attendance: [
+    'attendance.state',
+    'attendance.clockIn',
+    'attendance.clockOut',
+    'attendance.breakStart',
+    'attendance.breakEnd',
+    'attendance.punches.list',
+    'attendance.punches.void',
+    'attendance.days.list',
+    'attendance.days.recompute',
+    'attendance.schedules.list',
+    'attendance.schedules.create',
+    'attendance.schedules.update',
+    'attendance.schedules.archive',
+    'attendance.schedules.assign',
+    'attendance.regularizations.list',
+    'attendance.regularizations.request',
+  ],
   approvals: [
     'approvals.chains.list',
     'approvals.chains.create',

package/src/contract/events.ts

@@ -129,6 +129,30 @@ export const hrEvents = {
       status: z.string(),
     }),
   ),
+  punchRecorded: defineEvent(
+    'hr.punch.recorded',
+    z.object({
+      punchId: z.uuid(),
+      workspaceId: WorkspaceId,
+      personId: z.uuid(),
+      direction: z.string(),
+      businessDate: z.iso.date(),
+    }),
+  ),
+  /**
+   * A derived day changed. Carries the date so a consumer recomputes that window rather than
+   * everything — this fires on every punch, so a coarse payload would be a stampede.
+   */
+  attendanceDayComputed: defineEvent(
+    'hr.attendance.day_computed',
+    z.object({
+      workspaceId: WorkspaceId,
+      personId: z.uuid(),
+      businessDate: z.iso.date(),
+      status: z.string(),
+      workedMinutes: z.number().int(),
+    }),
+  ),
   calendarChanged: defineEvent(
     'hr.calendar.changed',
     z.object({

package/src/contract/index.ts

@@ -7,6 +7,7 @@
  * and also that every procedure listed in `hrCapabilityProcedures` carries its capability guard.
  */
 export * from './approvals.js'
+export * from './attendance.js'
 export * from './capabilities.js'
 export * from './events.js'
 export * from './leave.js'

package/src/contract/permissions.ts

@@ -228,6 +228,51 @@ export const hrPermissions = definePermissions([
     dangerous: true,
   },
 
+  // ---------------------------------------------------------------- attendance
+  {
+    key: 'hr.attendance.punch',
+    label: 'Clock yourself in and out',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.attendance.view',
+    label: 'View your own attendance',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.attendance.view_team',
+    label: "View your team's attendance",
+    scope: 'object',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.attendance.manage',
+    label: 'Correct punches, schedules and day sheets',
+    description: 'Voids punches and recomputes days. Every change leaves the original visible.',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: true,
+  },
+  {
+    key: 'hr.overtime.view',
+    label: 'View overtime',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.overtime.manage',
+    label: 'Approve and adjust overtime',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+
   // ---------------------------------------------------------------- approvals
   {
     key: 'hr.approval.manage',
@@ -283,6 +328,12 @@ export const HR_PERMISSIONS = {
   leaveViewLedger: 'hr.leave.view_ledger',
   leaveManage: 'hr.leave.manage',
   leaveAdjust: 'hr.leave.adjust',
+  attendancePunch: 'hr.attendance.punch',
+  attendanceView: 'hr.attendance.view',
+  attendanceViewTeam: 'hr.attendance.view_team',
+  attendanceManage: 'hr.attendance.manage',
+  overtimeView: 'hr.overtime.view',
+  overtimeManage: 'hr.overtime.manage',
   approvalManage: 'hr.approval.manage',
   approvalDelegate: 'hr.approval.delegate',
 } as const

package/src/contract/router.ts

@@ -7,6 +7,17 @@ import {
   ApprovalSubjectType,
   Delegation,
 } from './approvals.js'
+import {
+  AttendanceDay,
+  ClockState,
+  Punch,
+  PunchDirection,
+  PunchMethod,
+  Regularization,
+  Schedule,
+  ScheduleAssignment,
+  ScheduleWeek,
+} from './attendance.js'
 import {
   DayPart,
   LeaveBalance,
@@ -585,6 +596,191 @@ export const hrContract = {
       .output(ok),
   },
 
+  // ---------------------------------------------------------------- attendance
+  attendance: {
+    /** Am I clocked in? The one call a clock widget makes. */
+    state: baseContract
+      .route({ method: 'GET', path: '/attendance/state', tags: t })
+      .input(ws.extend({ personId: z.uuid().optional() }))
+      .output(ClockState),
+
+    /**
+     * Clock in. The instant is **stamped by the server**, never taken from the caller.
+     *
+     * `clientReportedAt` is recorded alongside it for audit — a device whose clock is an hour out is
+     * worth knowing about — but it never decides anything.
+     */
+    clockIn: baseContract
+      .route({ method: 'POST', path: '/attendance/clock-in', tags: t })
+      .input(
+        ws.extend({
+          personId: z.uuid().optional(),
+          method: PunchMethod.default('web'),
+          clientReportedAt: z.iso.datetime({ offset: true }).nullish(),
+          geo: z.object({ lat: z.number(), lng: z.number(), accuracyM: z.number().optional() }).nullish(),
+          note: z.string().max(500).nullish(),
+          idempotencyKey: z.string().min(8).max(128).optional(),
+        }),
+      )
+      .output(Punch),
+    clockOut: baseContract
+      .route({ method: 'POST', path: '/attendance/clock-out', tags: t })
+      .input(
+        ws.extend({
+          personId: z.uuid().optional(),
+          method: PunchMethod.default('web'),
+          clientReportedAt: z.iso.datetime({ offset: true }).nullish(),
+          geo: z.object({ lat: z.number(), lng: z.number(), accuracyM: z.number().optional() }).nullish(),
+          note: z.string().max(500).nullish(),
+          idempotencyKey: z.string().min(8).max(128).optional(),
+        }),
+      )
+      .output(Punch),
+    breakStart: baseContract
+      .route({ method: 'POST', path: '/attendance/break-start', tags: t })
+      .input(
+        ws.extend({ personId: z.uuid().optional(), idempotencyKey: z.string().min(8).max(128).optional() }),
+      )
+      .output(Punch),
+    breakEnd: baseContract
+      .route({ method: 'POST', path: '/attendance/break-end', tags: t })
+      .input(
+        ws.extend({ personId: z.uuid().optional(), idempotencyKey: z.string().min(8).max(128).optional() }),
+      )
+      .output(Punch),
+
+    punches: {
+      list: baseContract
+        .route({ method: 'GET', path: '/attendance/punches', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid().optional(),
+            from: IsoDate,
+            to: IsoDate,
+            includeVoided: z.boolean().default(false),
+            ...PageInput.shape,
+          }),
+        )
+        .output(page(Punch)),
+      /**
+       * Void a punch by writing a correcting row.
+       *
+       * The original is never edited or deleted — an attendance record somebody can quietly rewrite
+       * is worth nothing in the dispute it exists for.
+       */
+      void: baseContract
+        .route({ method: 'POST', path: '/attendance/punches/{punchId}/void', tags: t })
+        .input(ws.extend({ punchId: z.uuid(), reason: z.string().min(1).max(500) }))
+        .output(ok),
+    },
+
+    days: {
+      list: baseContract
+        .route({ method: 'GET', path: '/attendance/days', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid().optional(),
+            officeId: z.uuid().optional(),
+            from: IsoDate,
+            to: IsoDate,
+            ...PageInput.shape,
+          }),
+        )
+        .output(page(AttendanceDay)),
+      /**
+       * Recompute a range from the punches.
+       *
+       * Safe to call at any time — the day sheet is a projection, so this is idempotent by
+       * construction. Locked days are skipped and named in the response rather than silently
+       * ignored.
+       */
+      recompute: baseContract
+        .route({ method: 'POST', path: '/attendance/days/recompute', tags: t })
+        .input(ws.extend({ personId: z.uuid().optional(), from: IsoDate, to: IsoDate }))
+        .output(z.object({ recomputed: z.number().int(), skippedLocked: z.array(IsoDate) })),
+    },
+
+    schedules: {
+      list: baseContract
+        .route({ method: 'GET', path: '/attendance/schedules', tags: t })
+        .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+        .output(z.array(Schedule)),
+      create: baseContract
+        .route({ method: 'POST', path: '/attendance/schedules', tags: t })
+        .input(
+          ws.extend({
+            name: z.string().min(1).max(120),
+            kind: Schedule.shape.kind.default('fixed'),
+            week: ScheduleWeek,
+            tzMode: Schedule.shape.tzMode.default('office'),
+            tz: Schedule.shape.tz.optional(),
+            graceInMinutes: z.number().int().min(0).max(240).default(0),
+            graceOutMinutes: z.number().int().min(0).max(240).default(0),
+            roundingStepMinutes: z.number().int().min(0).max(60).default(0),
+            roundingDirection: Schedule.shape.roundingDirection.default('nearest'),
+            autoClockOutAfterMinutes: z.number().int().min(60).nullish(),
+          }),
+        )
+        .output(Schedule),
+      update: baseContract
+        .route({ method: 'PATCH', path: '/attendance/schedules/{scheduleId}', tags: t })
+        .input(
+          ws.extend({
+            scheduleId: z.uuid(),
+            name: z.string().min(1).max(120).optional(),
+            week: ScheduleWeek.optional(),
+            graceInMinutes: z.number().int().min(0).max(240).optional(),
+            graceOutMinutes: z.number().int().min(0).max(240).optional(),
+            roundingStepMinutes: z.number().int().min(0).max(60).optional(),
+            roundingDirection: Schedule.shape.roundingDirection.optional(),
+            autoClockOutAfterMinutes: z.number().int().min(60).nullish(),
+          }),
+        )
+        .output(Schedule),
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/attendance/schedules/{scheduleId}', tags: t })
+        .input(ws.extend({ scheduleId: z.uuid() }))
+        .output(ok),
+      assign: baseContract
+        .route({ method: 'POST', path: '/attendance/schedules/{scheduleId}/assign', tags: t })
+        .input(ws.extend({ scheduleId: z.uuid(), personId: z.uuid(), effectiveFrom: IsoDate }))
+        .output(z.array(ScheduleAssignment)),
+    },
+
+    regularizations: {
+      list: baseContract
+        .route({ method: 'GET', path: '/attendance/regularizations', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid().optional(),
+            status: z.array(Regularization.shape.status).optional(),
+            ...PageInput.shape,
+          }),
+        )
+        .output(page(Regularization)),
+      /** Ask for a wrong or missing punch to be fixed. Goes through the same approval engine. */
+      request: baseContract
+        .route({ method: 'POST', path: '/attendance/regularizations', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid().optional(),
+            businessDate: IsoDate,
+            punchId: z.uuid().nullish(),
+            proposed: z
+              .array(
+                z.object({
+                  direction: PunchDirection,
+                  at: z.iso.datetime({ offset: true }),
+                }),
+              )
+              .min(1),
+            reason: z.string().min(1).max(1000),
+          }),
+        )
+        .output(Regularization),
+    },
+  },
+
   // ---------------------------------------------------------------- leave
   leave: {
     types: {