@kernhq/module-hr 0.2.0 → 0.4.0

package/src/contract/router.ts

@@ -1,5 +1,33 @@
 import { baseContract, PageInput, page, WorkspaceId } from '@kernhq/contracts'
 import { z } from 'zod'
+import {
+  ApprovalChain,
+  ApprovalChainSpec,
+  ApprovalRequest,
+  ApprovalSubjectType,
+  Delegation,
+} from './approvals.js'
+import {
+  AttendanceDay,
+  ClockState,
+  Punch,
+  PunchDirection,
+  PunchMethod,
+  Regularization,
+  Schedule,
+  ScheduleAssignment,
+  ScheduleWeek,
+} from './attendance.js'
+import {
+  DayPart,
+  LeaveBalance,
+  LeaveLedgerEntry,
+  LeaveRequest,
+  LeaveSimulation,
+  LeaveType,
+  LeaveUnit,
+  LedgerKind,
+} from './leave.js'
 import {
   Calendar,
   CalendarDayKind,
@@ -568,6 +596,459 @@ 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: {
+      list: baseContract
+        .route({ method: 'GET', path: '/leave/types', tags: t })
+        .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+        .output(z.array(LeaveType)),
+      create: baseContract
+        .route({ method: 'POST', path: '/leave/types', tags: t })
+        .input(
+          ws.extend({
+            key: z.string().min(1).max(48),
+            name: z.string().min(1).max(120),
+            paid: z.boolean().default(true),
+            unit: LeaveUnit.default('day'),
+            color: z.string().max(32).nullish(),
+            icon: z.string().max(48).nullish(),
+            requiresDocumentAfterDays: z.number().int().min(1).nullish(),
+            countsWorkingDaysOnly: z.boolean().default(true),
+            allowNegative: z.boolean().default(false),
+            maxNegativeMinutes: z.number().int().min(0).default(0),
+          }),
+        )
+        .output(LeaveType),
+      update: baseContract
+        .route({ method: 'PATCH', path: '/leave/types/{leaveTypeId}', tags: t })
+        .input(
+          ws.extend({
+            leaveTypeId: z.uuid(),
+            name: z.string().min(1).max(120).optional(),
+            paid: z.boolean().optional(),
+            color: z.string().max(32).nullish(),
+            icon: z.string().max(48).nullish(),
+            requiresDocumentAfterDays: z.number().int().min(1).nullish(),
+            countsWorkingDaysOnly: z.boolean().optional(),
+            allowNegative: z.boolean().optional(),
+            maxNegativeMinutes: z.number().int().min(0).optional(),
+            order: z.number().int().optional(),
+          }),
+        )
+        .output(LeaveType),
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/leave/types/{leaveTypeId}', tags: t })
+        .input(ws.extend({ leaveTypeId: z.uuid() }))
+        .output(ok),
+    },
+
+    /** Everything a person has, per type. Defaults to the caller when `personId` is omitted. */
+    balance: {
+      get: baseContract
+        .route({ method: 'GET', path: '/leave/balance', tags: t })
+        .input(ws.extend({ personId: z.uuid().optional(), periodYear: z.number().int().optional() }))
+        .output(z.array(LeaveBalance)),
+    },
+
+    /**
+     * The movements behind a balance.
+     *
+     * The reason the ledger is append-only: when somebody disputes a number, this is the answer —
+     * a list of what happened, in order, that nobody edited.
+     */
+    ledger: {
+      list: baseContract
+        .route({ method: 'GET', path: '/leave/ledger', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid(),
+            leaveTypeId: z.uuid().optional(),
+            periodYear: z.number().int().optional(),
+            ...PageInput.shape,
+          }),
+        )
+        .output(page(LeaveLedgerEntry)),
+    },
+
+    /** A manual movement. Always carries a reason — an unexplained balance change is the thing HR gets asked about. */
+    adjust: baseContract
+      .route({ method: 'POST', path: '/leave/adjust', tags: t })
+      .input(
+        ws.extend({
+          personId: z.uuid(),
+          leaveTypeId: z.uuid(),
+          kind: LedgerKind.default('adjustment'),
+          amountMinutes: z.number().int(),
+          effectiveOn: IsoDate,
+          reason: z.string().min(1).max(500),
+        }),
+      )
+      .output(LeaveLedgerEntry),
+
+    requests: {
+      list: baseContract
+        .route({ method: 'GET', path: '/leave/requests', tags: t })
+        .input(
+          ws.extend({
+            ...PageInput.shape,
+            personId: z.uuid().optional(),
+            officeId: z.uuid().optional(),
+            status: z.array(LeaveRequest.shape.status).optional(),
+            from: IsoDate.optional(),
+            to: IsoDate.optional(),
+          }),
+        )
+        .output(page(LeaveRequest)),
+      get: baseContract
+        .route({ method: 'GET', path: '/leave/requests/{requestId}', tags: t })
+        .input(ws.extend({ requestId: z.uuid() }))
+        .output(LeaveRequest),
+      /** What it would cost and whether it would be refused — before anybody submits. */
+      simulate: baseContract
+        .route({ method: 'POST', path: '/leave/requests/simulate', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid().optional(),
+            leaveTypeId: z.uuid(),
+            startsOn: IsoDate,
+            endsOn: IsoDate,
+            startPart: DayPart.default('full'),
+            endPart: DayPart.default('full'),
+            hours: z.number().min(0).max(24).nullish(),
+          }),
+        )
+        .output(LeaveSimulation),
+      create: baseContract
+        .route({ method: 'POST', path: '/leave/requests', tags: t })
+        .input(
+          ws.extend({
+            personId: z.uuid().optional(),
+            leaveTypeId: z.uuid(),
+            startsOn: IsoDate,
+            endsOn: IsoDate,
+            startPart: DayPart.default('full'),
+            endPart: DayPart.default('full'),
+            hours: z.number().min(0).max(24).nullish(),
+            reason: z.string().max(1000).nullish(),
+            documentFileId: z.uuid().nullish(),
+            /**
+             * Makes a retried submission safe. Two clicks on a slow connection must not book the
+             * same week twice and spend the balance twice.
+             */
+            idempotencyKey: z.string().min(8).max(128).optional(),
+          }),
+        )
+        .output(LeaveRequest),
+      /**
+       * Cancels a request. An approved one is reversed in the ledger rather than deleted, so the
+       * balance goes back up and the history still says what happened.
+       */
+      cancel: baseContract
+        .route({ method: 'POST', path: '/leave/requests/{requestId}/cancel', tags: t })
+        .input(ws.extend({ requestId: z.uuid(), reason: z.string().max(500).nullish() }))
+        .output(LeaveRequest),
+    },
+
+    /** Who is off, over a range — the answer a team actually looks at. */
+    team: {
+      calendar: baseContract
+        .route({ method: 'GET', path: '/leave/calendar', tags: t })
+        .input(
+          ws.extend({
+            from: IsoDate,
+            to: IsoDate,
+            officeId: z.uuid().optional(),
+            orgUnitId: z.uuid().optional(),
+          }),
+        )
+        .output(
+          z.array(
+            z.object({
+              personId: z.uuid(),
+              displayName: z.string(),
+              requestId: z.uuid(),
+              startsOn: IsoDate,
+              endsOn: IsoDate,
+              status: LeaveRequest.shape.status,
+              /**
+               * The type's name, or null when the viewer may not see it. Most companies want the
+               * team to know somebody is away without knowing it is sick leave.
+               */
+              leaveTypeName: z.string().nullable(),
+              color: z.string().nullable(),
+            }),
+          ),
+        ),
+    },
+  },
+
+  // ---------------------------------------------------------------- approvals
+  approvals: {
+    /** Everything waiting on the caller, across every subject type. */
+    inbox: baseContract
+      .route({ method: 'GET', path: '/approvals/inbox', tags: t })
+      .input(ws.extend({ ...PageInput.shape, includeDecided: z.boolean().default(false) }))
+      .output(page(ApprovalRequest)),
+    get: baseContract
+      .route({ method: 'GET', path: '/approvals/{requestId}', tags: t })
+      .input(ws.extend({ requestId: z.uuid() }))
+      .output(ApprovalRequest),
+    /**
+     * Approve or reject. Idempotent per approver per step — a double click is one decision, and the
+     * database refuses the second rather than counting it twice.
+     */
+    decide: baseContract
+      .route({ method: 'POST', path: '/approvals/{requestId}/decide', tags: t })
+      .input(
+        ws.extend({
+          requestId: z.uuid(),
+          decision: z.enum(['approve', 'reject']),
+          comment: z.string().max(1000).nullish(),
+          /** Deciding in somebody's place, through a delegation they created. */
+          onBehalfOfId: z.uuid().nullish(),
+        }),
+      )
+      .output(ApprovalRequest),
+    chains: {
+      list: baseContract
+        .route({ method: 'GET', path: '/approvals/chains', tags: t })
+        .input(ws.extend({ subjectType: ApprovalSubjectType.optional() }))
+        .output(z.array(ApprovalChain)),
+      create: baseContract
+        .route({ method: 'POST', path: '/approvals/chains', tags: t })
+        .input(
+          ws.extend({
+            name: z.string().min(1).max(120),
+            subjectType: ApprovalSubjectType,
+            spec: ApprovalChainSpec,
+            isDefault: z.boolean().default(false),
+          }),
+        )
+        .output(ApprovalChain),
+      update: baseContract
+        .route({ method: 'PATCH', path: '/approvals/chains/{chainId}', tags: t })
+        .input(
+          ws.extend({
+            chainId: z.uuid(),
+            name: z.string().min(1).max(120).optional(),
+            spec: ApprovalChainSpec.optional(),
+            isDefault: z.boolean().optional(),
+          }),
+        )
+        .output(ApprovalChain),
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/approvals/chains/{chainId}', tags: t })
+        .input(ws.extend({ chainId: z.uuid() }))
+        .output(ok),
+    },
+    delegations: baseContract
+      .route({ method: 'GET', path: '/approvals/delegations', tags: t })
+      .input(ws.extend({ personId: z.uuid().optional() }))
+      .output(z.array(Delegation)),
+    delegate: baseContract
+      .route({ method: 'POST', path: '/approvals/delegations', tags: t })
+      .input(
+        ws.extend({
+          toPersonId: z.uuid(),
+          subjectType: ApprovalSubjectType.nullish(),
+          startsOn: IsoDate,
+          endsOn: IsoDate,
+          reason: z.string().max(200).nullish(),
+        }),
+      )
+      .output(Delegation),
+    revokeDelegation: baseContract
+      .route({ method: 'DELETE', path: '/approvals/delegations/{delegationId}', tags: t })
+      .input(ws.extend({ delegationId: z.uuid() }))
+      .output(ok),
+  },
+
   // ---------------------------------------------------------------- custom fields
   fields: {
     list: baseContract