@kernhq/module-hr 0.2.0 → 0.4.0

package/dist/contract/approvals.d.ts

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+/**
+ * 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 declare const ApprovalSubjectType: z.ZodEnum<{
+    leave: "leave";
+    regularization: "regularization";
+    overtime: "overtime";
+    timesheet: "timesheet";
+    shift_swap: "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 declare const ApproverSubject: z.ZodObject<{
+    kind: z.ZodEnum<{
+        person: "person";
+        manager: "manager";
+        manager_of_manager: "manager_of_manager";
+        org_unit_head: "org_unit_head";
+        office_head: "office_head";
+        permission: "permission";
+        group: "group";
+    }>;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ApproverSubject = z.infer<typeof ApproverSubject>;
+export declare const ApprovalStepMode: z.ZodEnum<{
+    any: "any";
+    all: "all";
+    quorum: "quorum";
+}>;
+export declare const ApprovalStepSpec: z.ZodObject<{
+    name: z.ZodString;
+    approvers: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            person: "person";
+            manager: "manager";
+            manager_of_manager: "manager_of_manager";
+            org_unit_head: "org_unit_head";
+            office_head: "office_head";
+            permission: "permission";
+            group: "group";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    mode: z.ZodEnum<{
+        any: "any";
+        all: "all";
+        quorum: "quorum";
+    }>;
+    minApprovals: z.ZodNumber;
+    slaHours: z.ZodNullable<z.ZodNumber>;
+    onTimeout: z.ZodEnum<{
+        remind: "remind";
+        escalate: "escalate";
+        auto_approve: "auto_approve";
+    }>;
+}, z.core.$strip>;
+export type ApprovalStepSpec = z.infer<typeof ApprovalStepSpec>;
+/** Steps run in order; the request advances only when the current one is satisfied. */
+export declare const ApprovalChainSpec: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        approvers: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                person: "person";
+                manager: "manager";
+                manager_of_manager: "manager_of_manager";
+                org_unit_head: "org_unit_head";
+                office_head: "office_head";
+                permission: "permission";
+                group: "group";
+            }>;
+            id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        mode: z.ZodEnum<{
+            any: "any";
+            all: "all";
+            quorum: "quorum";
+        }>;
+        minApprovals: z.ZodNumber;
+        slaHours: z.ZodNullable<z.ZodNumber>;
+        onTimeout: z.ZodEnum<{
+            remind: "remind";
+            escalate: "escalate";
+            auto_approve: "auto_approve";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ApprovalChainSpec = z.infer<typeof ApprovalChainSpec>;
+export declare const ApprovalChain: z.ZodObject<{
+    name: z.ZodString;
+    subjectType: z.ZodEnum<{
+        leave: "leave";
+        regularization: "regularization";
+        overtime: "overtime";
+        timesheet: "timesheet";
+        shift_swap: "shift_swap";
+    }>;
+    spec: z.ZodObject<{
+        steps: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            approvers: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    person: "person";
+                    manager: "manager";
+                    manager_of_manager: "manager_of_manager";
+                    org_unit_head: "org_unit_head";
+                    office_head: "office_head";
+                    permission: "permission";
+                    group: "group";
+                }>;
+                id: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            mode: z.ZodEnum<{
+                any: "any";
+                all: "all";
+                quorum: "quorum";
+            }>;
+            minApprovals: z.ZodNumber;
+            slaHours: z.ZodNullable<z.ZodNumber>;
+            onTimeout: z.ZodEnum<{
+                remind: "remind";
+                escalate: "escalate";
+                auto_approve: "auto_approve";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    isDefault: z.ZodBoolean;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+export type ApprovalChain = z.infer<typeof ApprovalChain>;
+export declare const ApprovalStatus: z.ZodEnum<{
+    pending: "pending";
+    approved: "approved";
+    rejected: "rejected";
+    cancelled: "cancelled";
+}>;
+export type ApprovalStatus = z.infer<typeof ApprovalStatus>;
+export declare const ApprovalDecision: z.ZodObject<{
+    id: z.ZodUUID;
+    stepId: z.ZodUUID;
+    approverId: z.ZodUUID;
+    onBehalfOfId: z.ZodNullable<z.ZodUUID>;
+    decision: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+    }>;
+    comment: z.ZodNullable<z.ZodString>;
+    at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ApprovalDecision = z.infer<typeof ApprovalDecision>;
+export declare const ApprovalStep: z.ZodObject<{
+    id: z.ZodUUID;
+    requestId: z.ZodUUID;
+    stepIndex: z.ZodNumber;
+    name: z.ZodString;
+    mode: z.ZodEnum<{
+        any: "any";
+        all: "all";
+        quorum: "quorum";
+    }>;
+    minApprovals: z.ZodNumber;
+    approverIds: z.ZodArray<z.ZodUUID>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        rejected: "rejected";
+        cancelled: "cancelled";
+    }>;
+    dueAt: z.ZodNullable<z.ZodISODateTime>;
+    escalatedAt: z.ZodNullable<z.ZodISODateTime>;
+    decisions: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        stepId: z.ZodUUID;
+        approverId: z.ZodUUID;
+        onBehalfOfId: z.ZodNullable<z.ZodUUID>;
+        decision: z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+        }>;
+        comment: z.ZodNullable<z.ZodString>;
+        at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ApprovalStep = z.infer<typeof ApprovalStep>;
+export declare const ApprovalRequest: z.ZodObject<{
+    subjectType: z.ZodEnum<{
+        leave: "leave";
+        regularization: "regularization";
+        overtime: "overtime";
+        timesheet: "timesheet";
+        shift_swap: "shift_swap";
+    }>;
+    subjectId: z.ZodUUID;
+    summary: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        rejected: "rejected";
+        cancelled: "cancelled";
+    }>;
+    currentStep: z.ZodNumber;
+    requestedBy: z.ZodNullable<z.ZodUUID>;
+    requestedAt: z.ZodISODateTime;
+    decidedAt: z.ZodNullable<z.ZodISODateTime>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        requestId: z.ZodUUID;
+        stepIndex: z.ZodNumber;
+        name: z.ZodString;
+        mode: z.ZodEnum<{
+            any: "any";
+            all: "all";
+            quorum: "quorum";
+        }>;
+        minApprovals: z.ZodNumber;
+        approverIds: z.ZodArray<z.ZodUUID>;
+        status: z.ZodEnum<{
+            pending: "pending";
+            approved: "approved";
+            rejected: "rejected";
+            cancelled: "cancelled";
+        }>;
+        dueAt: z.ZodNullable<z.ZodISODateTime>;
+        escalatedAt: z.ZodNullable<z.ZodISODateTime>;
+        decisions: z.ZodArray<z.ZodObject<{
+            id: z.ZodUUID;
+            stepId: z.ZodUUID;
+            approverId: z.ZodUUID;
+            onBehalfOfId: z.ZodNullable<z.ZodUUID>;
+            decision: z.ZodEnum<{
+                approve: "approve";
+                reject: "reject";
+            }>;
+            comment: z.ZodNullable<z.ZodString>;
+            at: z.ZodISODateTime;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+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 declare const Delegation: z.ZodObject<{
+    fromPersonId: z.ZodUUID;
+    toPersonId: z.ZodUUID;
+    subjectType: z.ZodNullable<z.ZodEnum<{
+        leave: "leave";
+        regularization: "regularization";
+        overtime: "overtime";
+        timesheet: "timesheet";
+        shift_swap: "shift_swap";
+    }>>;
+    startsOn: z.ZodISODate;
+    endsOn: z.ZodISODate;
+    reason: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+export type Delegation = z.infer<typeof Delegation>;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/contract/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/contract/approvals.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,mBAAmB;;;;;;EAA6E,CAAA;AAC7G,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAErE;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;iBAiB1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D,eAAO,MAAM,gBAAgB;;;;EAO3B,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D,uFAAuF;AACvF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAE5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBASxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD,eAAO,MAAM,cAAc;;;;;EAA2D,CAAA;AACtF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAS3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAavB,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEvD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAa1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;iBAWrB,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA"}

package/dist/contract/approvals.js

@@ -0,0 +1,127 @@
+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']);
+/**
+ * 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 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']),
+});
+/** 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 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 const ApprovalStatus = z.enum(['pending', 'approved', 'rejected', 'cancelled']);
+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 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 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),
+});
+/**
+ * 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,
+});
+//# sourceMappingURL=approvals.js.map

package/dist/contract/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../src/contract/approvals.ts"],"names":[],"mappings":"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"}

package/dist/contract/attendance.d.ts

@@ -0,0 +1,240 @@
+import { z } from 'zod';
+/**
+ * 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 declare const PunchDirection: z.ZodEnum<{
+    out: "out";
+    in: "in";
+    break_start: "break_start";
+    break_end: "break_end";
+}>;
+export type PunchDirection = z.infer<typeof PunchDirection>;
+export declare const PunchMethod: z.ZodEnum<{
+    web: "web";
+    mobile: "mobile";
+    kiosk: "kiosk";
+    qr: "qr";
+    device: "device";
+    import: "import";
+    manual: "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 declare const PunchTrust: z.ZodEnum<{
+    trusted: "trusted";
+    claimed: "claimed";
+    disputed: "disputed";
+}>;
+export type PunchTrust = z.infer<typeof PunchTrust>;
+export declare const Punch: z.ZodObject<{
+    personId: z.ZodUUID;
+    direction: z.ZodEnum<{
+        out: "out";
+        in: "in";
+        break_start: "break_start";
+        break_end: "break_end";
+    }>;
+    at: z.ZodISODateTime;
+    clientReportedAt: z.ZodNullable<z.ZodISODateTime>;
+    skewMs: z.ZodNullable<z.ZodNumber>;
+    businessDate: z.ZodISODate;
+    timezone: z.ZodString;
+    method: z.ZodEnum<{
+        web: "web";
+        mobile: "mobile";
+        kiosk: "kiosk";
+        qr: "qr";
+        device: "device";
+        import: "import";
+        manual: "manual";
+    }>;
+    officeId: z.ZodNullable<z.ZodUUID>;
+    deviceId: z.ZodNullable<z.ZodUUID>;
+    geo: z.ZodNullable<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+        accuracyM: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    trust: z.ZodEnum<{
+        trusted: "trusted";
+        claimed: "claimed";
+        disputed: "disputed";
+    }>;
+    voidedByPunchId: z.ZodNullable<z.ZodUUID>;
+    note: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+export type Punch = z.infer<typeof Punch>;
+export declare const AttendanceStatus: z.ZodEnum<{
+    leave: "leave";
+    pending: "pending";
+    present: "present";
+    absent: "absent";
+    holiday: "holiday";
+    weekend: "weekend";
+    partial: "partial";
+}>;
+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 declare const AttendanceDay: z.ZodObject<{
+    personId: z.ZodUUID;
+    businessDate: z.ZodISODate;
+    scheduledMinutes: z.ZodNumber;
+    workedMinutes: z.ZodNumber;
+    breakMinutes: z.ZodNumber;
+    overtimeMinutes: z.ZodNumber;
+    lateMinutes: z.ZodNumber;
+    earlyLeaveMinutes: z.ZodNumber;
+    status: z.ZodEnum<{
+        leave: "leave";
+        pending: "pending";
+        present: "present";
+        absent: "absent";
+        holiday: "holiday";
+        weekend: "weekend";
+        partial: "partial";
+    }>;
+    leaveRequestId: z.ZodNullable<z.ZodUUID>;
+    anomalies: z.ZodArray<z.ZodString>;
+    firstIn: z.ZodNullable<z.ZodISODateTime>;
+    lastOut: z.ZodNullable<z.ZodISODateTime>;
+    policyHash: z.ZodNullable<z.ZodString>;
+    locked: z.ZodBoolean;
+    computedAt: z.ZodISODateTime;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+export type AttendanceDay = z.infer<typeof AttendanceDay>;
+/** A week of shifts, in wall-clock readings. Meaningless until a date and a zone arrive. */
+export declare const ScheduleWeek: z.ZodRecord<z.ZodEnum<{
+    mon: "mon";
+    tue: "tue";
+    wed: "wed";
+    thu: "thu";
+    fri: "fri";
+    sat: "sat";
+    sun: "sun";
+}>, z.ZodNullable<z.ZodObject<{
+    start: z.ZodString;
+    end: z.ZodString;
+    breakMinutes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>>;
+export type ScheduleWeek = z.infer<typeof ScheduleWeek>;
+export declare const Schedule: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        fixed: "fixed";
+        flexible: "flexible";
+        shift: "shift";
+    }>;
+    week: z.ZodRecord<z.ZodEnum<{
+        mon: "mon";
+        tue: "tue";
+        wed: "wed";
+        thu: "thu";
+        fri: "fri";
+        sat: "sat";
+        sun: "sun";
+    }>, z.ZodNullable<z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+        breakMinutes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    tzMode: z.ZodEnum<{
+        person: "person";
+        office: "office";
+        fixed: "fixed";
+    }>;
+    tz: z.ZodNullable<z.ZodString>;
+    graceInMinutes: z.ZodNumber;
+    graceOutMinutes: z.ZodNumber;
+    roundingStepMinutes: z.ZodNumber;
+    roundingDirection: z.ZodEnum<{
+        nearest: "nearest";
+        employee: "employee";
+        employer: "employer";
+    }>;
+    autoClockOutAfterMinutes: z.ZodNullable<z.ZodNumber>;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+export type Schedule = z.infer<typeof Schedule>;
+export declare const ScheduleAssignment: z.ZodObject<{
+    personId: z.ZodUUID;
+    scheduleId: z.ZodUUID;
+    effectiveFrom: z.ZodISODate;
+    effectiveTo: z.ZodNullable<z.ZodISODate>;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+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 declare const Regularization: z.ZodObject<{
+    personId: z.ZodUUID;
+    businessDate: z.ZodISODate;
+    punchId: z.ZodNullable<z.ZodUUID>;
+    proposed: z.ZodArray<z.ZodObject<{
+        direction: z.ZodEnum<{
+            out: "out";
+            in: "in";
+            break_start: "break_start";
+            break_end: "break_end";
+        }>;
+        at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    reason: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        rejected: "rejected";
+        cancelled: "cancelled";
+    }>;
+    approvalRequestId: z.ZodNullable<z.ZodUUID>;
+    appliedAt: z.ZodNullable<z.ZodISODateTime>;
+    createdAt: z.ZodISODateTime;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    id: z.ZodUUID;
+}, z.core.$strip>;
+export type Regularization = z.infer<typeof Regularization>;
+/** The person's own live state: are they clocked in, since when, on a break? */
+export declare const ClockState: z.ZodObject<{
+    personId: z.ZodUUID;
+    businessDate: z.ZodISODate;
+    clockedIn: z.ZodBoolean;
+    onBreak: z.ZodBoolean;
+    since: z.ZodNullable<z.ZodISODateTime>;
+    workedMinutesToday: z.ZodNumber;
+    timezone: z.ZodString;
+}, z.core.$strip>;
+export type ClockState = z.infer<typeof ClockState>;
+//# sourceMappingURL=attendance.d.ts.map

package/dist/contract/attendance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attendance.d.ts","sourceRoot":"","sources":["../../src/contract/attendance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,cAAc;;;;;EAAoD,CAAA;AAC/E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D,eAAO,MAAM,WAAW;;;;;;;;EAAyE,CAAA;AACjG,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;EAA6C,CAAA;AACpE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AAEnD,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBhB,CAAA;AACF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA;AAEzC,eAAO,MAAM,gBAAgB;;;;;;;;EAS3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD,4FAA4F;AAC5F,eAAO,MAAM,YAAY;;;;;;;;;;;;mBASxB,CAAA;AACD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEvD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBnB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAE/C,eAAO,MAAM,kBAAkB;;;;;;;iBAO7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;iBAazB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D,gFAAgF;AAChF,eAAO,MAAM,UAAU;;;;;;;;iBAQrB,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA"}