@kernhq/module-hr 0.2.0 → 0.3.0

package/migrations/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1787567807015,
       "tag": "0001_rls",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1787601877456,
+      "tag": "0002_leave",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-hr",
-  "version": "0.2.0",
+  "version": "0.3.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/capabilities.ts

@@ -64,6 +64,26 @@ 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: 'documents',
     label: 'Employee documents',
@@ -114,4 +134,28 @@ 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',
+  ],
+  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,63 @@ 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(),
+    }),
+  ),
   calendarChanged: defineEvent(
     'hr.calendar.changed',
     z.object({

package/src/contract/index.ts

@@ -6,8 +6,10 @@
  * 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 './capabilities.js'
 export * from './events.js'
+export * from './leave.js'
 export * from './models.js'
 export * from './permissions.js'
 export * from './router.js'

package/src/contract/leave.ts

@@ -0,0 +1,171 @@
+import { Timestamp, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { IsoDate } from './models.js'
+
+const ws = { workspaceId: WorkspaceId }
+
+/**
+ * Leave, and the one rule everything here follows: **a balance is a sum, never a stored number.**
+ *
+ * Every grant, accrual, consumption, reversal, expiry and adjustment is an append-only ledger entry.
+ * Cancelling approved leave inserts a reversal; it does not delete the consumption. That costs a
+ * little arithmetic and buys the only thing that matters when an employee and HR disagree about a
+ * balance: a list of what happened, in order, that nobody edited.
+ */
+
+export const LeaveUnit = z.enum(['day', 'half_day', 'hour'])
+export type LeaveUnit = z.infer<typeof LeaveUnit>
+
+export const LeaveType = z.object({
+  id: z.uuid(),
+  ...ws,
+  key: z
+    .string()
+    .min(1)
+    .max(48)
+    .regex(/^[a-z][a-z0-9_]*$/),
+  name: z.string().min(1).max(120),
+  /** Unpaid leave still consumes calendar days; it just does not cost money. */
+  paid: z.boolean(),
+  unit: LeaveUnit,
+  color: z.string().max(32).nullable(),
+  icon: z.string().max(48).nullable(),
+  /** A sick note after N consecutive days. Null means never. */
+  requiresDocumentAfterDays: z.number().int().min(1).nullable(),
+  /** Weekends and public holidays inside a request do not consume balance. Almost always true. */
+  countsWorkingDaysOnly: z.boolean(),
+  allowNegative: z.boolean(),
+  /** How far below zero, in minutes. Only consulted when `allowNegative`. */
+  maxNegativeMinutes: z.number().int().min(0),
+  /** Sort order in pickers. */
+  order: z.number().int(),
+  archivedAt: Timestamp.nullable(),
+})
+export type LeaveType = z.infer<typeof LeaveType>
+
+/**
+ * Why a ledger entry exists. The set is closed on purpose — a new kind of movement is a decision,
+ * not a string somebody passes in.
+ */
+export const LedgerKind = z.enum([
+  /** An allowance handed out: the annual entitlement, a one-off award. */
+  'grant',
+  /** Earned over time by an accrual policy. */
+  'accrual',
+  /** Spent by an approved request. Negative. */
+  'consumption',
+  /** Undoes an earlier entry, cancellation or a retroactive correction. Points at what it reverses. */
+  'reversal',
+  /** Unused balance lapsing at a carry-forward deadline. Negative. */
+  'expiry',
+  /** A human decided. Always carries a reason. */
+  'adjustment',
+  'carry_in',
+  'carry_out',
+  /** Paid out instead of taken. Negative. */
+  'encashment',
+])
+export type LedgerKind = z.infer<typeof LedgerKind>
+
+export const LeaveLedgerEntry = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  leaveTypeId: z.uuid(),
+  kind: LedgerKind,
+  /**
+   * Signed, in minutes. Minutes rather than days because half-days, hourly leave and part-time
+   * fractions all divide a day, and a decimal day accumulates rounding error across a year of them.
+   */
+  amountMinutes: z.number().int(),
+  effectiveOn: IsoDate,
+  /** Which entitlement year this belongs to. Carry-forward and expiry work on it. */
+  periodYear: z.number().int(),
+  requestId: z.uuid().nullable(),
+  reversesEntryId: z.uuid().nullable(),
+  /** Which policy version produced it, so a recomputation can tell what it was computed with. */
+  policyHash: z.string().max(64).nullable(),
+  reason: z.string().max(500).nullable(),
+  createdBy: z.uuid().nullable(),
+  createdAt: Timestamp,
+})
+export type LeaveLedgerEntry = z.infer<typeof LeaveLedgerEntry>
+
+export const LeaveBalance = z.object({
+  personId: z.uuid(),
+  leaveTypeId: z.uuid(),
+  leaveTypeName: z.string(),
+  unit: LeaveUnit,
+  periodYear: z.number().int(),
+  /** The sum of every entry. Minutes. */
+  balanceMinutes: z.number().int(),
+  /** Approved but not yet taken — already spent, shown separately so "remaining" is not a surprise. */
+  bookedMinutes: z.number().int(),
+  /** Submitted and not yet decided. Not spent, but not available either. */
+  pendingMinutes: z.number().int(),
+  /** `balance - pending`. What a person can actually request today without going negative. */
+  availableMinutes: z.number().int(),
+  /** The same figures in whatever unit the type uses, for display. */
+  balance: z.number(),
+  available: z.number(),
+})
+export type LeaveBalance = z.infer<typeof LeaveBalance>
+
+export const LeaveRequestStatus = z.enum([
+  'draft',
+  'pending',
+  'approved',
+  'rejected',
+  'cancelled',
+  /** Approved, then cancelled or corrected afterwards. The ledger carries a reversal. */
+  'withdrawn',
+])
+export type LeaveRequestStatus = z.infer<typeof LeaveRequestStatus>
+
+/** Which half of a day a request starts or ends on. */
+export const DayPart = z.enum(['full', 'morning', 'afternoon'])
+export type DayPart = z.infer<typeof DayPart>
+
+export const LeaveRequest = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  leaveTypeId: z.uuid(),
+  startsOn: IsoDate,
+  endsOn: IsoDate,
+  startPart: DayPart,
+  endPart: DayPart,
+  /** For hourly leave. Null for day-based types. */
+  hours: z.number().min(0).max(24).nullable(),
+  /** Working days consumed, after the calendar is applied. Recomputed on approval. */
+  workingDays: z.number(),
+  minutes: z.number().int(),
+  status: LeaveRequestStatus,
+  reason: z.string().max(1000).nullable(),
+  documentFileId: z.uuid().nullable(),
+  approvalRequestId: z.uuid().nullable(),
+  decidedAt: Timestamp.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+})
+export type LeaveRequest = z.infer<typeof LeaveRequest>
+
+/** What a request would cost, before anybody submits it. */
+export const LeaveSimulation = z.object({
+  workingDays: z.number(),
+  minutes: z.number().int(),
+  /** Day by day, so somebody can see *why* a five-day request costs three. */
+  days: z.array(
+    z.object({
+      date: IsoDate,
+      fraction: z.number(),
+      counted: z.boolean(),
+      reason: z.string().nullable(),
+    }),
+  ),
+  balanceBeforeMinutes: z.number().int(),
+  balanceAfterMinutes: z.number().int(),
+  /** Reasons this would be refused if submitted. Empty means it would go through. */
+  blockers: z.array(z.object({ code: z.string(), message: z.string() })),
+})
+export type LeaveSimulation = z.infer<typeof LeaveSimulation>

package/src/contract/permissions.ts

@@ -181,6 +181,69 @@ export const hrPermissions = definePermissions([
     dangerous: true,
   },
 
+  // ---------------------------------------------------------------- leave
+  {
+    key: 'hr.leave.request',
+    label: 'Request time off',
+    // Everybody. A permission an employee cannot lack is noise, but this one is genuinely revocable
+    // — a contractor who books time off through their agency should not have the button.
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.leave.view',
+    label: 'View leave types and your own balance',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.leave.view_team',
+    label: "View your team's leave and balances",
+    scope: 'object',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.leave.view_ledger',
+    label: "View the movements behind somebody's balance",
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.leave.manage',
+    label: 'Configure leave types',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.leave.adjust',
+    label: "Change somebody's balance by hand",
+    description: 'Adds or removes leave directly. Every adjustment is recorded with its reason.',
+    scope: 'workspace',
+    defaultRoles: [],
+    dangerous: true,
+  },
+
+  // ---------------------------------------------------------------- approvals
+  {
+    key: 'hr.approval.manage',
+    label: 'Configure approval chains',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.approval.delegate',
+    label: 'Hand your approvals to somebody else while away',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+
   // ---------------------------------------------------------------- fields
   {
     key: 'hr.field.manage',
@@ -214,4 +277,12 @@ export const HR_PERMISSIONS = {
   documentView: 'hr.document.view',
   documentManage: 'hr.document.manage',
   fieldManage: 'hr.field.manage',
+  leaveRequest: 'hr.leave.request',
+  leaveView: 'hr.leave.view',
+  leaveViewTeam: 'hr.leave.view_team',
+  leaveViewLedger: 'hr.leave.view_ledger',
+  leaveManage: 'hr.leave.manage',
+  leaveAdjust: 'hr.leave.adjust',
+  approvalManage: 'hr.approval.manage',
+  approvalDelegate: 'hr.approval.delegate',
 } as const