@kernhq/module-hr 0.2.0 → 0.4.0

package/migrations/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1787567807015,
       "tag": "0001_rls",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "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.2.0",
+  "version": "0.4.0",
   "description": "Kern HR module: people, offices, org chart, calendars",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/contract/approvals.ts

@@ -0,0 +1,149 @@
+import { Timestamp, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { IsoDate } from './models.js'
+
+const ws = { workspaceId: WorkspaceId }
+
+/**
+ * One approval engine, for everything that needs signing off.
+ *
+ * Keyed by `subjectType` + `subjectId` rather than by a foreign key to leave, so regularization,
+ * overtime and timesheets attach to it later without a schema change. That seam is the reason this
+ * is not just a few columns on `leave_requests`.
+ *
+ * The chain is **snapshotted onto the request when it is raised**. Editing the workflow afterwards
+ * must not change who has to sign a request already in flight — the version of that mistake where
+ * somebody's approved leave silently needs another signature is very hard to explain.
+ */
+
+export const ApprovalSubjectType = z.enum(['leave', 'regularization', 'overtime', 'timesheet', 'shift_swap'])
+export type ApprovalSubjectType = z.infer<typeof ApprovalSubjectType>
+
+/**
+ * Who is being asked. Resolved to people when the request is raised, so a later reorganisation does
+ * not silently move an in-flight approval to somebody else.
+ */
+export const ApproverSubject = z.object({
+  kind: z.enum([
+    'person',
+    /** The requester's manager on the day the request was raised. */
+    'manager',
+    /** Two levels up. Falls back to one level if there is nobody above. */
+    'manager_of_manager',
+    /** Whoever heads the requester's department. */
+    'org_unit_head',
+    /** Whoever heads the requester's primary office — the local-HR step. */
+    'office_head',
+    /** Anybody holding a permission key, workspace-wide. */
+    'permission',
+    'group',
+  ]),
+  /** Person id, permission key or group id, depending on `kind`. */
+  id: z.string().max(128).optional(),
+})
+export type ApproverSubject = z.infer<typeof ApproverSubject>
+
+export const ApprovalStepMode = z.enum([
+  /** Everyone named must approve. */
+  'all',
+  /** Any one of them is enough. */
+  'any',
+  /** `minApprovals` of them. */
+  'quorum',
+])
+
+export const ApprovalStepSpec = z.object({
+  name: z.string().max(80),
+  approvers: z.array(ApproverSubject).min(1),
+  mode: ApprovalStepMode,
+  minApprovals: z.number().int().min(1),
+  /** Hours before the step is escalated or auto-decided. Null means it waits forever. */
+  slaHours: z.number().int().min(1).nullable(),
+  onTimeout: z.enum(['remind', 'escalate', 'auto_approve']),
+})
+export type ApprovalStepSpec = z.infer<typeof ApprovalStepSpec>
+
+/** Steps run in order; the request advances only when the current one is satisfied. */
+export const ApprovalChainSpec = z.object({
+  steps: z.array(ApprovalStepSpec).min(1),
+})
+export type ApprovalChainSpec = z.infer<typeof ApprovalChainSpec>
+
+export const ApprovalChain = z.object({
+  id: z.uuid(),
+  ...ws,
+  name: z.string().min(1).max(120),
+  subjectType: ApprovalSubjectType,
+  spec: ApprovalChainSpec,
+  /** Used when nothing more specific matches. Exactly one per subject type. */
+  isDefault: z.boolean(),
+  archivedAt: Timestamp.nullable(),
+})
+export type ApprovalChain = z.infer<typeof ApprovalChain>
+
+export const ApprovalStatus = z.enum(['pending', 'approved', 'rejected', 'cancelled'])
+export type ApprovalStatus = z.infer<typeof ApprovalStatus>
+
+export const ApprovalDecision = z.object({
+  id: z.uuid(),
+  stepId: z.uuid(),
+  approverId: z.uuid(),
+  /** Set when somebody decided in another person's place through a delegation. */
+  onBehalfOfId: z.uuid().nullable(),
+  decision: z.enum(['approve', 'reject']),
+  comment: z.string().max(1000).nullable(),
+  at: Timestamp,
+})
+export type ApprovalDecision = z.infer<typeof ApprovalDecision>
+
+export const ApprovalStep = z.object({
+  id: z.uuid(),
+  requestId: z.uuid(),
+  stepIndex: z.number().int(),
+  name: z.string(),
+  mode: ApprovalStepMode,
+  minApprovals: z.number().int(),
+  /** Expanded at request time; a later reorganisation does not move an in-flight approval. */
+  approverIds: z.array(z.uuid()),
+  status: ApprovalStatus,
+  dueAt: Timestamp.nullable(),
+  escalatedAt: Timestamp.nullable(),
+  decisions: z.array(ApprovalDecision),
+})
+export type ApprovalStep = z.infer<typeof ApprovalStep>
+
+export const ApprovalRequest = z.object({
+  id: z.uuid(),
+  ...ws,
+  subjectType: ApprovalSubjectType,
+  subjectId: z.uuid(),
+  /** A one-line description of what is being approved, so an inbox is readable without joins. */
+  summary: z.string().max(200),
+  status: ApprovalStatus,
+  currentStep: z.number().int(),
+  requestedBy: z.uuid().nullable(),
+  requestedAt: Timestamp,
+  decidedAt: Timestamp.nullable(),
+  steps: z.array(ApprovalStep),
+})
+export type ApprovalRequest = z.infer<typeof ApprovalRequest>
+
+/**
+ * Somebody else may decide in my place while I am away.
+ *
+ * A delegation does not move the request; it lets the delegate act on it, and the decision records
+ * both people. "Who approved this" must never become ambiguous.
+ */
+export const Delegation = z.object({
+  id: z.uuid(),
+  ...ws,
+  fromPersonId: z.uuid(),
+  toPersonId: z.uuid(),
+  /** Null delegates every subject type. */
+  subjectType: ApprovalSubjectType.nullable(),
+  startsOn: IsoDate,
+  endsOn: IsoDate,
+  reason: z.string().max(200).nullable(),
+  createdAt: Timestamp,
+})
+export type Delegation = z.infer<typeof Delegation>

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

@@ -64,6 +64,44 @@ export const hrCapabilities = defineCapabilities([
     defaultEnabled: true,
     level: 1,
   },
+  {
+    id: 'leave',
+    label: 'Leave',
+    description: 'Time off: types, balances, requests and approvals',
+    dependsOn: ['core', 'calendars'],
+    // On by default. Leave is what most companies come to an HR system for, and a directory that
+    // cannot answer "who is off next week" is answering a question nobody asked.
+    defaultEnabled: true,
+    level: 1,
+  },
+  {
+    id: 'approvals',
+    label: 'Approval chains',
+    description: 'Named multi-step approvals with delegation, instead of a single manager',
+    dependsOn: ['core'],
+    // Off by default: at Level 1 the requester's manager approves, implicitly, and a company with
+    // one approver does not need a chain editor to find out that it has one.
+    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',
@@ -114,4 +152,46 @@ export const hrCapabilityProcedures: Record<string, readonly string[]> = {
     'calendars.workingDays',
   ],
   documents: ['documents.list', 'documents.attach', 'documents.remove'],
+  leave: [
+    'leave.types.list',
+    'leave.types.create',
+    'leave.types.update',
+    'leave.types.archive',
+    'leave.balance.get',
+    'leave.ledger.list',
+    'leave.adjust',
+    'leave.requests.list',
+    'leave.requests.get',
+    'leave.requests.simulate',
+    'leave.requests.create',
+    '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',
+    'approvals.chains.update',
+    'approvals.chains.archive',
+    'approvals.delegate',
+    'approvals.revokeDelegation',
+    'approvals.delegations',
+  ],
 }

package/src/contract/events.ts

@@ -72,6 +72,87 @@ export const hrEvents = {
    * sheet) is stale from here. The payload names the date range touched so a consumer can recompute
    * that window rather than everything.
    */
+  leaveRequested: defineEvent(
+    'hr.leave.requested',
+    z.object({
+      requestId: z.uuid(),
+      workspaceId: WorkspaceId,
+      personId: z.uuid(),
+      startsOn: z.iso.date(),
+      endsOn: z.iso.date(),
+    }),
+  ),
+  /**
+   * Decided either way, with the outcome in the payload.
+   *
+   * One event rather than approved/rejected pairs: every consumer so far cares that a decision
+   * happened and then branches, and two events means two subscriptions to keep in step.
+   */
+  leaveDecided: defineEvent(
+    'hr.leave.decided',
+    z.object({
+      requestId: z.uuid(),
+      workspaceId: WorkspaceId,
+      personId: z.uuid(),
+      status: z.string(),
+      startsOn: z.iso.date(),
+      endsOn: z.iso.date(),
+    }),
+  ),
+  /** A balance moved. Carries the delta so a consumer need not re-sum the ledger. */
+  leaveBalanceChanged: defineEvent(
+    'hr.leave.balance_changed',
+    z.object({
+      workspaceId: WorkspaceId,
+      personId: z.uuid(),
+      leaveTypeId: z.uuid(),
+      deltaMinutes: z.number().int(),
+    }),
+  ),
+  approvalRequested: defineEvent(
+    'hr.approval.requested',
+    z.object({
+      requestId: z.uuid(),
+      workspaceId: WorkspaceId,
+      subjectType: z.string(),
+      subjectId: z.uuid(),
+      approverIds: z.array(z.uuid()),
+    }),
+  ),
+  approvalDecided: defineEvent(
+    'hr.approval.decided',
+    z.object({
+      requestId: z.uuid(),
+      workspaceId: WorkspaceId,
+      subjectType: z.string(),
+      subjectId: z.uuid(),
+      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

@@ -6,8 +6,11 @@
  * exists here and not in the router is a lie that compiles. `module.test.ts` checks exactly that,
  * 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'
 export * from './models.js'
 export * from './permissions.js'
 export * from './router.js'