Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,91 @@
import type { VMState } from "../index.js";
/**
* HR announcement view-models (AK-P17b). Pure functions. Feed (pinned first,
* optional unread-only filter) and detail (markdown body, grouped reactions,
* single-level comments, acknowledgement state, optional read-receipt table for
* managers). No React, no Prisma, no app imports. Author/commenter display names
* are resolved by the loader.
*/
export interface HrAnnouncementFeedRow {
readonly id: string;
readonly title: string;
readonly snippet: string;
readonly pinned: boolean;
readonly isRead: boolean;
readonly requiresAcknowledgement: boolean;
readonly isAcknowledged: boolean;
readonly reactionCount: number;
readonly commentCount: number;
readonly publishedIso: string;
readonly detailHref: string;
}
export interface HrAnnouncementFeedData {
readonly rows: readonly HrAnnouncementFeedRow[];
readonly unreadOnly: boolean;
readonly canManage: boolean;
readonly manageHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrAnnouncementFeedVM = VMState<HrAnnouncementFeedData>;
export interface HrReactionGroup {
readonly reaction: string;
readonly count: number;
readonly mine: boolean;
}
export interface HrAnnouncementComment {
readonly id: string;
readonly authorLabel: string;
readonly body: string;
readonly createdIso: string;
readonly canArchive: boolean;
}
export interface HrReadReceiptRow {
readonly userLabel: string;
readonly readIso: string;
readonly acknowledged: boolean;
}
export interface HrAnnouncementDetailData {
readonly id: string;
readonly title: string;
readonly bodyMarkdown: string;
readonly authorLabel: string;
readonly publishedIso: string;
readonly requiresAcknowledgement: boolean;
readonly isAcknowledged: boolean;
readonly reactions: readonly HrReactionGroup[];
readonly comments: readonly HrAnnouncementComment[];
readonly canManage: boolean;
/** Present only for managers (otherwise empty). */
readonly readReceipts: readonly HrReadReceiptRow[];
readonly commentEmptyKey: string;
}
export type HrAnnouncementDetailVM = VMState<HrAnnouncementDetailData>;
export function buildAnnouncementFeedVM(input: { rows: readonly HrAnnouncementFeedRow[]; unreadOnly: boolean; canManage: boolean; manageHref: string }): HrAnnouncementFeedVM {
const rows = input.unreadOnly ? input.rows.filter((row) => !row.isRead) : input.rows;
return {
status: "ready",
data: {
rows,
unreadOnly: input.unreadOnly,
canManage: input.canManage,
manageHref: input.manageHref,
emptyHeadlineKey: "hr.announcements.empty.headline",
emptyBodyKey: "hr.announcements.empty.body",
},
};
}
export function buildAnnouncementDetailVM(input: Omit<HrAnnouncementDetailData, "commentEmptyKey">): HrAnnouncementDetailVM {
return { status: "ready", data: { ...input, commentEmptyKey: "hr.announcements.comments.empty" } };
}
@@ -0,0 +1,79 @@
import { describe, expect, it } from "vitest";
import { buildHrDirectoryVM, type HrDirectoryRow } from "./hr-directory.vm.js";
import { buildHrLocationListVM, type HrLocationRow } from "./hr-location.vm.js";
import { buildHrDocumentListVM, hrDocumentKindKey, type HrDocumentRow } from "./hr-document.vm.js";
// AK-P17a — directory/location/document VMs are pure; these tests cover the
// ready/empty contract and the non-sensitive shape of the directory.
describe("buildHrDirectoryVM", () => {
const row: HrDirectoryRow = {
userId: "u1",
name: "Alex Doe",
email: "alex@acme.test",
position: "Engineer",
team: "Platform",
locationName: "HQ",
detailHref: "/acme/hr/directory/u1",
};
it("carries only non-sensitive display fields (no emergency contact)", () => {
const vm = buildHrDirectoryVM({ rows: [row], canManage: false });
const data = vm.data!.rows[0]! as unknown as Record<string, unknown>;
expect(data).not.toHaveProperty("emergencyContact");
expect(data).not.toHaveProperty("emergencyContactCiphertext");
expect(data.name).toBe("Alex Doe");
});
it("keeps an empty directory in a ready state", () => {
const vm = buildHrDirectoryVM({ rows: [], canManage: true });
expect(vm.status).toBe("ready");
expect(vm.data?.emptyHeadlineKey).toBe("hr.directory.empty.headline");
});
});
describe("buildHrLocationListVM", () => {
const row: HrLocationRow = {
id: "l1",
name: "HQ",
addressLine1: "Main St 1",
postalCode: "1010",
city: "Vienna",
country: "AT",
phone: null,
latitude: null,
longitude: null,
description: null,
isDefault: true,
employeeCount: 4,
detailHref: "/acme/hr/locations/l1",
};
it("exposes the employee count and default flag", () => {
const vm = buildHrLocationListVM({ rows: [row], canManage: true, createHref: "/x" });
expect(vm.data?.rows[0].employeeCount).toBe(4);
expect(vm.data?.rows[0].isDefault).toBe(true);
expect(vm.data?.canManage).toBe(true);
});
});
describe("buildHrDocumentListVM", () => {
const row: HrDocumentRow = {
id: "d1",
title: "Contract",
documentKind: "contract",
kindKey: hrDocumentKindKey("contract"),
createdAtIso: new Date("2026-01-01").toISOString(),
validUntilIso: null,
isExpired: false,
readOnly: true,
fileHref: "/acme/files/f1",
};
it("maps a kind to its i18n key and flags read-only office uploads", () => {
expect(hrDocumentKindKey("contract")).toBe("hr.document.kind.contract");
const vm = buildHrDocumentListVM({ rows: [row], canUpload: true, uploadHref: "/x" });
expect(vm.data?.rows[0].readOnly).toBe(true);
expect(vm.data?.rows[0].kindKey).toBe("hr.document.kind.contract");
});
});
@@ -0,0 +1,50 @@
import type { VMState } from "../index.js";
/**
* HR employee directory view-model (AK-P17a). Pure function: the loader builds it
* once server-side, the UI only renders. No React, no Prisma, no app imports
* (DoD A.3). All static texts are i18n keys; resolved names (employee label,
* location label) are data passed in by the loader.
*
* The directory carries ONLY non-sensitive display fields — emergency contacts
* and other sensitive data are never part of this list (reveal-on-demand only).
*/
export interface HrDirectoryRow {
readonly userId: string;
/** Resolved display name (data), built by the loader. */
readonly name: string;
readonly email: string;
readonly position: string | null;
readonly team: string | null;
/** Resolved location display name (data) or null. */
readonly locationName: string | null;
/** Internal detail route (e.g. `/acme/hr/directory/<userId>`). */
readonly detailHref: string;
}
export interface HrDirectoryData {
readonly rows: readonly HrDirectoryRow[];
readonly canManage: boolean;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrDirectoryVM = VMState<HrDirectoryData>;
export interface BuildHrDirectoryVMInput {
readonly rows: readonly HrDirectoryRow[];
readonly canManage: boolean;
}
export function buildHrDirectoryVM(input: BuildHrDirectoryVMInput): HrDirectoryVM {
// Empty stays a `ready` state with a plain-text empty state (DoD 23).
return {
status: "ready",
data: {
rows: input.rows,
canManage: input.canManage,
emptyHeadlineKey: "hr.directory.empty.headline",
emptyBodyKey: "hr.directory.empty.body",
},
};
}
@@ -0,0 +1,57 @@
import type { VMState } from "../index.js";
/**
* HR "my documents" view-model (AK-P17a). Pure function (DoD A.3). Office-uploaded
* documents are flagged read-only so the UI hides edit/delete for them; the
* employee can still open/download.
*/
export type HrDocumentKind = "contract" | "certificate" | "identification" | "qualification" | "other";
export interface HrDocumentRow {
readonly id: string;
readonly title: string;
readonly documentKind: HrDocumentKind;
/** i18n key for the kind label (e.g. `hr.document.kind.contract`). */
readonly kindKey: string;
readonly createdAtIso: string;
readonly validUntilIso: string | null;
/** Loader-computed: validUntil is set and in the past. */
readonly isExpired: boolean;
/** Office-uploaded → read-only for the employee (no edit/delete). */
readonly readOnly: boolean;
/** Internal auth-proxy route to view/download the underlying file. */
readonly fileHref: string;
}
export interface HrDocumentListData {
readonly rows: readonly HrDocumentRow[];
readonly canUpload: boolean;
readonly uploadHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrDocumentListVM = VMState<HrDocumentListData>;
export interface BuildHrDocumentListVMInput {
readonly rows: readonly HrDocumentRow[];
readonly canUpload: boolean;
readonly uploadHref: string;
}
export function hrDocumentKindKey(kind: HrDocumentKind): string {
return `hr.document.kind.${kind}`;
}
export function buildHrDocumentListVM(input: BuildHrDocumentListVMInput): HrDocumentListVM {
return {
status: "ready",
data: {
rows: input.rows,
canUpload: input.canUpload,
uploadHref: input.uploadHref,
emptyHeadlineKey: "hr.documents.empty.headline",
emptyBodyKey: "hr.documents.empty.body",
},
};
}
@@ -0,0 +1,111 @@
import { describe, expect, it } from "vitest";
import { buildHrLeaveOwnVM, buildHrLeaveApproverVM, type BuildHrLeaveOwnInput, type HrLeaveApproverInputRow } from "./hr-leave.vm.js";
import { buildHrSickOwnVM, buildHrSickOfficeVM, type HrSickLeaveInputRow } from "./hr-sickleave.vm.js";
// AK-P17b — leave/sick VMs are pure. These tests cover the status-derived action
// flags, the kind/status → i18n-key mapping and the approver conflict hint.
describe("buildHrLeaveOwnVM", () => {
const baseRow: BuildHrLeaveOwnInput["rows"][number] = {
id: "r1",
kind: "vacation",
status: "submitted",
startDateIso: "2026-07-01",
endDateIso: "2026-07-05",
note: null,
clarificationNote: null,
decisionNote: null,
detailHref: "/acme/hr/leave/r1",
};
it("maps kind/status to i18n keys and allows withdraw while open", () => {
const vm = buildHrLeaveOwnVM({ rows: [baseRow], canCreate: true, newHref: "/x" });
const row = vm.data!.rows[0]!;
expect(row.kindLabelKey).toBe("hr.leave.kind.vacation");
expect(row.statusLabelKey).toBe("hr.leave.status.submitted");
expect(row.canWithdraw).toBe(true);
expect(row.canReply).toBe(false);
});
it("requires a reply only in clarification, never after a decision", () => {
const vm = buildHrLeaveOwnVM({
rows: [
{ ...baseRow, id: "r2", status: "clarification" },
{ ...baseRow, id: "r3", status: "approved" },
],
canCreate: true,
newHref: "/x",
});
expect(vm.data!.rows[0]!.canReply).toBe(true);
expect(vm.data!.rows[0]!.canWithdraw).toBe(true);
expect(vm.data!.rows[1]!.canReply).toBe(false);
expect(vm.data!.rows[1]!.canWithdraw).toBe(false);
});
it("keeps an empty list in a ready state", () => {
const vm = buildHrLeaveOwnVM({ rows: [], canCreate: false, newHref: "/x" });
expect(vm.status).toBe("ready");
expect(vm.data?.emptyHeadlineKey).toBe("hr.leave.own.empty.headline");
});
});
describe("buildHrLeaveApproverVM", () => {
const row: HrLeaveApproverInputRow = {
id: "r1",
employeeLabel: "Alex Doe",
kind: "vacation",
status: "submitted",
startDateIso: "2026-07-01",
endDateIso: "2026-07-05",
note: null,
conflictCount: 0,
detailHref: "/acme/hr/leave/r1",
};
it("flags an overlapping approved absence as a conflict", () => {
const vm = buildHrLeaveApproverVM({ rows: [{ ...row, conflictCount: 2 }] });
expect(vm.data!.rows[0]!.hasConflict).toBe(true);
expect(vm.data!.rows[0]!.conflictCount).toBe(2);
expect(vm.data!.conflictHintKey).toBe("hr.leave.approver.conflictHint");
});
it("reports no conflict when nothing overlaps", () => {
const vm = buildHrLeaveApproverVM({ rows: [row] });
expect(vm.data!.rows[0]!.hasConflict).toBe(false);
});
});
describe("sick-leave VMs", () => {
const row: HrSickLeaveInputRow = {
id: "s1",
status: "reported",
startDateIso: "2026-07-01",
expectedReturnDateIso: "2026-07-04",
returnDateIso: null,
note: null,
hasCertificate: true,
revealHref: "/acme/hr/sick/s1/certificate",
};
it("never exposes the certificate id, only a hasCertificate flag", () => {
const vm = buildHrSickOwnVM({ rows: [row], canReport: true });
const data = vm.data!.rows[0]! as unknown as Record<string, unknown>;
expect(data).not.toHaveProperty("certificateFileId");
expect(data).not.toHaveProperty("certificateRefCiphertext");
expect(data.hasCertificate).toBe(true);
expect(data.statusLabelKey).toBe("hr.sick.status.reported");
});
it("derives close/cancel flags from status", () => {
const own = buildHrSickOwnVM({ rows: [row, { ...row, id: "s2", status: "cancelled" }], canReport: true });
expect(own.data!.rows[0]!.canClose).toBe(true);
expect(own.data!.rows[0]!.canCancel).toBe(true);
expect(own.data!.rows[1]!.canClose).toBe(false);
expect(own.data!.rows[1]!.canCancel).toBe(false);
});
it("adds the employee label in the office view", () => {
const vm = buildHrSickOfficeVM({ rows: [{ ...row, employeeLabel: "Alex Doe" }] });
expect(vm.data!.rows[0]!.employeeLabel).toBe("Alex Doe");
});
});
@@ -0,0 +1,122 @@
import type { VMState } from "../index.js";
/**
* HR leave/vacation view-models (AK-P17b). Pure functions: the loader builds
* them once server-side from already-resolved rows (dates as ISO strings,
* employee display names resolved by the loader). No React, no Prisma, no app
* imports (DoD A.3). All static texts are i18n keys.
*/
export type HrLeaveStatus = "submitted" | "clarification" | "approved" | "rejected" | "withdrawn";
export type HrVacationRequestKind = "vacation" | "special_leave" | "unpaid_leave" | "overtime_compensation";
export interface HrLeaveOwnRow {
readonly id: string;
readonly kind: HrVacationRequestKind;
/** i18n key for the kind label, e.g. `hr.leave.kind.vacation`. */
readonly kindLabelKey: string;
readonly status: HrLeaveStatus;
/** i18n key for the status label, e.g. `hr.leave.status.approved`. */
readonly statusLabelKey: string;
readonly startDateIso: string;
readonly endDateIso: string;
readonly note: string | null;
readonly clarificationNote: string | null;
readonly decisionNote: string | null;
readonly detailHref: string;
/** Requester may withdraw while still open. */
readonly canWithdraw: boolean;
/** Requester must reply when the approver asked a question. */
readonly canReply: boolean;
}
export interface HrLeaveOwnData {
readonly rows: readonly HrLeaveOwnRow[];
readonly canCreate: boolean;
readonly newHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrLeaveOwnVM = VMState<HrLeaveOwnData>;
export interface HrLeaveApproverRow {
readonly id: string;
readonly employeeLabel: string;
readonly kindLabelKey: string;
readonly statusLabelKey: string;
readonly startDateIso: string;
readonly endDateIso: string;
readonly note: string | null;
/** Number of OTHER approved absences overlapping this window. */
readonly conflictCount: number;
/** True when there is at least one overlapping approved absence. */
readonly hasConflict: boolean;
readonly detailHref: string;
}
export interface HrLeaveApproverData {
readonly rows: readonly HrLeaveApproverRow[];
readonly conflictHintKey: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrLeaveApproverVM = VMState<HrLeaveApproverData>;
const OPEN_STATUSES: ReadonlySet<HrLeaveStatus> = new Set<HrLeaveStatus>(["submitted", "clarification"]);
export interface BuildHrLeaveOwnInput {
readonly rows: ReadonlyArray<Omit<HrLeaveOwnRow, "kindLabelKey" | "statusLabelKey" | "canWithdraw" | "canReply">>;
readonly canCreate: boolean;
readonly newHref: string;
}
export function buildHrLeaveOwnVM(input: BuildHrLeaveOwnInput): HrLeaveOwnVM {
const rows: HrLeaveOwnRow[] = input.rows.map((row) => ({
...row,
kindLabelKey: `hr.leave.kind.${row.kind}`,
statusLabelKey: `hr.leave.status.${row.status}`,
canWithdraw: OPEN_STATUSES.has(row.status),
canReply: row.status === "clarification",
}));
return {
status: "ready",
data: {
rows,
canCreate: input.canCreate,
newHref: input.newHref,
emptyHeadlineKey: "hr.leave.own.empty.headline",
emptyBodyKey: "hr.leave.own.empty.body",
},
};
}
/** Raw approver input row: carries `kind`/`status` for label mapping; the
* derived `kindLabelKey`/`statusLabelKey`/`hasConflict` are added by the builder. */
export interface HrLeaveApproverInputRow extends Omit<HrLeaveApproverRow, "kindLabelKey" | "statusLabelKey" | "hasConflict"> {
readonly kind: HrVacationRequestKind;
readonly status: HrLeaveStatus;
}
export interface BuildHrLeaveApproverInput {
readonly rows: readonly HrLeaveApproverInputRow[];
}
export function buildHrLeaveApproverVM(input: BuildHrLeaveApproverInput): HrLeaveApproverVM {
const rows: HrLeaveApproverRow[] = input.rows.map(({ kind, status, ...row }) => ({
...row,
kindLabelKey: `hr.leave.kind.${kind}`,
statusLabelKey: `hr.leave.status.${status}`,
hasConflict: row.conflictCount > 0,
}));
return {
status: "ready",
data: {
rows,
conflictHintKey: "hr.leave.approver.conflictHint",
emptyHeadlineKey: "hr.leave.approver.empty.headline",
emptyBodyKey: "hr.leave.approver.empty.body",
},
};
}
@@ -0,0 +1,53 @@
import type { VMState } from "../index.js";
/**
* HR locations view-model (AK-P17a). Pure function (DoD A.3): the loader builds
* it once server-side; the UI only renders. Static texts are i18n keys; the
* employee count is loader-computed data.
*/
export interface HrLocationRow {
readonly id: string;
readonly name: string;
readonly addressLine1: string | null;
readonly postalCode: string | null;
readonly city: string | null;
readonly country: string | null;
readonly phone: string | null;
readonly latitude: number | null;
readonly longitude: number | null;
readonly description: string | null;
readonly isDefault: boolean;
/** Loader-computed number of employees at this location. */
readonly employeeCount: number;
/** Internal detail route (e.g. `/acme/hr/locations/<id>`). */
readonly detailHref: string;
}
export interface HrLocationListData {
readonly rows: readonly HrLocationRow[];
readonly canManage: boolean;
readonly createHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrLocationListVM = VMState<HrLocationListData>;
export interface BuildHrLocationListVMInput {
readonly rows: readonly HrLocationRow[];
readonly canManage: boolean;
readonly createHref: string;
}
export function buildHrLocationListVM(input: BuildHrLocationListVMInput): HrLocationListVM {
return {
status: "ready",
data: {
rows: input.rows,
canManage: input.canManage,
createHref: input.createHref,
emptyHeadlineKey: "hr.locations.empty.headline",
emptyBodyKey: "hr.locations.empty.body",
},
};
}
@@ -0,0 +1,73 @@
import { describe, expect, it } from "vitest";
import {
buildVaultDetailVM,
buildVaultListVM,
buildAdminVaultListVM,
PASSWORD_SAFE_COPY_AUTO_CLEAR_MS,
type EntryRow,
} from "./hr-password-safe.vm.js";
// AK-P17a — the password-safe VMs carry the security-critical "never list a
// secret value" contract. These pure-function tests lock that contract in.
const entry = (overrides: Partial<EntryRow> = {}): EntryRow => ({
id: "e1",
title: "Router admin",
tags: ["network"],
url: "https://router.local",
hasUsername: true,
hasPassword: true,
hasNotes: false,
revealHref: "/acme/hr/password-safe/v1/reveal",
...overrides,
});
describe("buildVaultDetailVM", () => {
it("never exposes a secret value field on an entry row", () => {
const vm = buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "read", rows: [entry()], exportHref: "/x" });
expect(vm.status).toBe("ready");
const row = vm.data!.rows[0]! as unknown as Record<string, unknown>;
// Only presence flags are allowed — never the plaintext.
expect(row).not.toHaveProperty("username");
expect(row).not.toHaveProperty("password");
expect(row).not.toHaveProperty("notes");
expect(row.hasUsername).toBe(true);
expect(row.hasPassword).toBe(true);
});
it("derives canWrite/canManageAccess from the access level", () => {
expect(buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "read", rows: [], exportHref: "/x" }).data?.canWrite).toBe(false);
expect(buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "write", rows: [], exportHref: "/x" }).data?.canWrite).toBe(true);
expect(buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "read", rows: [], exportHref: "/x" }).data?.canManageAccess).toBe(false);
expect(buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "admin", rows: [], exportHref: "/x" }).data?.canManageAccess).toBe(true);
});
it("enforces the 30s clipboard auto-clear window", () => {
const vm = buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "read", rows: [], exportHref: "/x" });
expect(vm.data?.copyAutoClearMs).toBe(30_000);
expect(PASSWORD_SAFE_COPY_AUTO_CLEAR_MS).toBe(30_000);
});
it("keeps an empty vault in a ready state with a plain-text empty state", () => {
const vm = buildVaultDetailVM({ vaultId: "v1", vaultName: "Ops", accessLevel: "read", rows: [], exportHref: "/x" });
expect(vm.status).toBe("ready");
expect(vm.data?.rows).toHaveLength(0);
expect(vm.data?.emptyHeadlineKey).toBe("hr.passwordSafe.entries.empty.headline");
});
});
describe("buildVaultListVM / buildAdminVaultListVM", () => {
it("the admin vault row carries only metadata + counts, never entry contents", () => {
const vm = buildAdminVaultListVM({ rows: [{ id: "v1", name: "Ops", entryCount: 3, accessCount: 2, archived: false, detailHref: "/x" }] });
const row = vm.data!.rows[0]! as unknown as Record<string, unknown>;
expect(row).not.toHaveProperty("entries");
expect(row.entryCount).toBe(3);
expect(row.accessCount).toBe(2);
});
it("an empty vault list stays ready with the empty-state keys", () => {
const vm = buildVaultListVM({ rows: [], canCreate: true, createHref: "/x" });
expect(vm.status).toBe("ready");
expect(vm.data?.emptyHeadlineKey).toBe("hr.passwordSafe.empty.headline");
});
});
@@ -0,0 +1,132 @@
import type { VMState } from "../index.js";
/**
* HR password-safe view-models (AK-P17a). Pure functions (DoD A.3).
*
* CRITICAL: no secret value ever enters a VM. The entry rows carry only titles,
* tags, url and BOOLEAN "hasX" flags — never the username/password/notes. The
* actual value is fetched on demand by a separate, audited reveal action and is
* never persisted in any rendered model.
*/
export type PasswordSafePermissionLevel = "read" | "write" | "admin";
export interface VaultRow {
readonly id: string;
readonly name: string;
readonly description: string | null;
/** The caller's own access level on this vault. */
readonly accessLevel: PasswordSafePermissionLevel;
/** Internal route to the vault's entries. */
readonly detailHref: string;
}
export interface VaultListData {
readonly rows: readonly VaultRow[];
readonly canCreate: boolean;
readonly createHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type VaultListVM = VMState<VaultListData>;
export function buildVaultListVM(input: { rows: readonly VaultRow[]; canCreate: boolean; createHref: string }): VaultListVM {
return {
status: "ready",
data: {
rows: input.rows,
canCreate: input.canCreate,
createHref: input.createHref,
emptyHeadlineKey: "hr.passwordSafe.empty.headline",
emptyBodyKey: "hr.passwordSafe.empty.body",
},
};
}
/** A single entry WITHOUT secret values — only presence flags. */
export interface EntryRow {
readonly id: string;
readonly title: string;
readonly tags: readonly string[];
readonly url: string | null;
readonly hasUsername: boolean;
readonly hasPassword: boolean;
readonly hasNotes: boolean;
/** Endpoint the UI calls to reveal a single field on demand (audited). */
readonly revealHref: string;
}
export interface VaultDetailData {
readonly vaultId: string;
readonly vaultName: string;
readonly accessLevel: PasswordSafePermissionLevel;
readonly canWrite: boolean;
readonly canManageAccess: boolean;
readonly rows: readonly EntryRow[];
/** 30s clipboard auto-clear window (ms) the UI enforces after a copy (DoD #3). */
readonly copyAutoClearMs: number;
readonly exportHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type VaultDetailVM = VMState<VaultDetailData>;
export const PASSWORD_SAFE_COPY_AUTO_CLEAR_MS = 30_000;
export interface BuildVaultDetailVMInput {
readonly vaultId: string;
readonly vaultName: string;
readonly accessLevel: PasswordSafePermissionLevel;
readonly rows: readonly EntryRow[];
readonly exportHref: string;
}
export function buildVaultDetailVM(input: BuildVaultDetailVMInput): VaultDetailVM {
const canWrite = input.accessLevel === "write" || input.accessLevel === "admin";
return {
status: "ready",
data: {
vaultId: input.vaultId,
vaultName: input.vaultName,
accessLevel: input.accessLevel,
canWrite,
canManageAccess: input.accessLevel === "admin",
rows: input.rows,
copyAutoClearMs: PASSWORD_SAFE_COPY_AUTO_CLEAR_MS,
exportHref: input.exportHref,
emptyHeadlineKey: "hr.passwordSafe.entries.empty.headline",
emptyBodyKey: "hr.passwordSafe.entries.empty.body",
},
};
}
/** Tenant-wide admin vault list (/admin/hr/password-safe) — metadata only, never
* content access. */
export interface AdminVaultRow {
readonly id: string;
readonly name: string;
readonly entryCount: number;
readonly accessCount: number;
readonly archived: boolean;
readonly detailHref: string;
}
export interface AdminVaultListData {
readonly rows: readonly AdminVaultRow[];
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type AdminVaultListVM = VMState<AdminVaultListData>;
export function buildAdminVaultListVM(input: { rows: readonly AdminVaultRow[] }): AdminVaultListVM {
return {
status: "ready",
data: {
rows: input.rows,
emptyHeadlineKey: "hr.admin.passwordSafe.empty.headline",
emptyBodyKey: "hr.admin.passwordSafe.empty.body",
},
};
}
@@ -0,0 +1,121 @@
import type { VMState } from "../index.js";
import type { PayslipMatchConfidence } from "./payslip-match.js";
/**
* HR payslip view-models (AK-P17b). Pure functions. Own list (PDF open marks
* read), admin list, and the bulk-upload match preview (hard/soft/none with a
* color-confidence key). No React, no Prisma, no app imports.
*/
export interface HrPayslipRow {
readonly id: string;
readonly periodLabel: string;
readonly periodYear: number;
readonly periodMonth: number;
readonly isRead: boolean;
readonly openHref: string;
}
export interface HrPayslipOwnData {
readonly rows: readonly HrPayslipRow[];
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrPayslipOwnVM = VMState<HrPayslipOwnData>;
export interface HrPayslipAdminRow extends HrPayslipRow {
readonly employeeLabel: string;
readonly uploadedByLabel: string;
}
export interface HrPayslipAdminData {
readonly rows: readonly HrPayslipAdminRow[];
readonly uploadHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrPayslipAdminVM = VMState<HrPayslipAdminData>;
export interface HrPayslipMatchRow {
readonly fileId: string;
readonly fileName: string;
readonly confidence: PayslipMatchConfidence;
/** i18n key for the confidence badge, e.g. `hr.payslips.match.confidence.hard`. */
readonly confidenceKey: string;
/** Color token for the confidence badge (UI maps to its palette). */
readonly confidenceTone: "success" | "warning" | "neutral";
readonly employeeUserId: string | null;
readonly employeeLabel: string | null;
readonly candidateUserIds: readonly string[];
}
export interface HrPayslipMatchPreviewData {
readonly rows: readonly HrPayslipMatchRow[];
readonly hardCount: number;
readonly softCount: number;
readonly noneCount: number;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrPayslipMatchPreviewVM = VMState<HrPayslipMatchPreviewData>;
function monthLabel(year: number, month: number): string {
// Plain numeric period (e.g. "2026-07"); locale month names are the UI's job.
return `${year}-${String(month).padStart(2, "0")}`;
}
export function buildHrPayslipOwnVM(input: { rows: ReadonlyArray<Omit<HrPayslipRow, "periodLabel">> }): HrPayslipOwnVM {
return {
status: "ready",
data: {
rows: input.rows.map((row) => ({ ...row, periodLabel: monthLabel(row.periodYear, row.periodMonth) })),
emptyHeadlineKey: "hr.payslips.own.empty.headline",
emptyBodyKey: "hr.payslips.own.empty.body",
},
};
}
export function buildHrPayslipAdminVM(input: { rows: ReadonlyArray<Omit<HrPayslipAdminRow, "periodLabel">>; uploadHref: string }): HrPayslipAdminVM {
return {
status: "ready",
data: {
rows: input.rows.map((row) => ({ ...row, periodLabel: monthLabel(row.periodYear, row.periodMonth) })),
uploadHref: input.uploadHref,
emptyHeadlineKey: "hr.payslips.admin.empty.headline",
emptyBodyKey: "hr.payslips.admin.empty.body",
},
};
}
const CONFIDENCE_TONE: Record<PayslipMatchConfidence, "success" | "warning" | "neutral"> = { hard: "success", soft: "warning", none: "neutral" };
export interface HrPayslipMatchInputRow {
readonly fileId: string;
readonly fileName: string;
readonly confidence: PayslipMatchConfidence;
readonly employeeUserId: string | null;
readonly employeeLabel: string | null;
readonly candidateUserIds: readonly string[];
}
export function buildHrPayslipMatchPreviewVM(input: { rows: readonly HrPayslipMatchInputRow[] }): HrPayslipMatchPreviewVM {
const rows: HrPayslipMatchRow[] = input.rows.map((row) => ({
...row,
confidenceKey: `hr.payslips.match.confidence.${row.confidence}`,
confidenceTone: CONFIDENCE_TONE[row.confidence],
}));
return {
status: "ready",
data: {
rows,
hardCount: rows.filter((r) => r.confidence === "hard").length,
softCount: rows.filter((r) => r.confidence === "soft").length,
noneCount: rows.filter((r) => r.confidence === "none").length,
emptyHeadlineKey: "hr.payslips.match.empty.headline",
emptyBodyKey: "hr.payslips.match.empty.body",
},
};
}
@@ -0,0 +1,122 @@
import type { VMState } from "../index.js";
/**
* HR request view-models (AK-P17b). Pure functions. Own list, approver list and
* the template picker. Mirrors the leave VM shape (status-derived action flags,
* kind/status → i18n keys). No React, no Prisma, no app imports.
*/
export type HrRequestKind = "expense" | "hardware" | "training" | "reference";
export type HrRequestStatus = "submitted" | "clarification" | "approved" | "rejected" | "withdrawn";
const OPEN: ReadonlySet<HrRequestStatus> = new Set<HrRequestStatus>(["submitted", "clarification"]);
export interface HrRequestRow {
readonly id: string;
readonly title: string;
readonly kind: HrRequestKind;
readonly kindLabelKey: string;
readonly status: HrRequestStatus;
readonly statusLabelKey: string;
readonly createdIso: string;
readonly detailHref: string;
readonly canWithdraw: boolean;
}
export interface HrRequestOwnData {
readonly rows: readonly HrRequestRow[];
readonly newHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrRequestOwnVM = VMState<HrRequestOwnData>;
export interface HrRequestApproverRow {
readonly id: string;
readonly title: string;
readonly employeeLabel: string;
readonly kindLabelKey: string;
readonly statusLabelKey: string;
readonly createdIso: string;
readonly detailHref: string;
}
export interface HrRequestApproverData {
readonly rows: readonly HrRequestApproverRow[];
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrRequestApproverVM = VMState<HrRequestApproverData>;
export interface HrRequestTemplateRow {
readonly id: string;
readonly title: string;
readonly kind: HrRequestKind;
readonly kindLabelKey: string;
readonly description: string | null;
readonly isActive: boolean;
readonly editHref: string;
}
export interface HrRequestTemplateListData {
readonly rows: readonly HrRequestTemplateRow[];
readonly createHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrRequestTemplateListVM = VMState<HrRequestTemplateListData>;
interface OwnInputRow {
readonly id: string;
readonly title: string;
readonly kind: HrRequestKind;
readonly status: HrRequestStatus;
readonly createdIso: string;
readonly detailHref: string;
}
export function buildHrRequestOwnVM(input: { rows: readonly OwnInputRow[]; newHref: string }): HrRequestOwnVM {
const rows: HrRequestRow[] = input.rows.map((row) => ({
...row,
kindLabelKey: `hr.requests.kind.${row.kind}`,
statusLabelKey: `hr.requests.status.${row.status}`,
canWithdraw: OPEN.has(row.status),
}));
return { status: "ready", data: { rows, newHref: input.newHref, emptyHeadlineKey: "hr.requests.own.empty.headline", emptyBodyKey: "hr.requests.own.empty.body" } };
}
interface ApproverInputRow {
readonly id: string;
readonly title: string;
readonly employeeLabel: string;
readonly kind: HrRequestKind;
readonly status: HrRequestStatus;
readonly createdIso: string;
readonly detailHref: string;
}
export function buildHrRequestApproverVM(input: { rows: readonly ApproverInputRow[] }): HrRequestApproverVM {
const rows: HrRequestApproverRow[] = input.rows.map(({ kind, status, ...row }) => ({
...row,
kindLabelKey: `hr.requests.kind.${kind}`,
statusLabelKey: `hr.requests.status.${status}`,
}));
return { status: "ready", data: { rows, emptyHeadlineKey: "hr.requests.approver.empty.headline", emptyBodyKey: "hr.requests.approver.empty.body" } };
}
interface TemplateInputRow {
readonly id: string;
readonly title: string;
readonly kind: HrRequestKind;
readonly description: string | null;
readonly isActive: boolean;
readonly editHref: string;
}
export function buildHrRequestTemplateListVM(input: { rows: readonly TemplateInputRow[]; createHref: string }): HrRequestTemplateListVM {
const rows: HrRequestTemplateRow[] = input.rows.map((row) => ({ ...row, kindLabelKey: `hr.requests.kind.${row.kind}` }));
return { status: "ready", data: { rows, createHref: input.createHref, emptyHeadlineKey: "hr.requests.templates.empty.headline", emptyBodyKey: "hr.requests.templates.empty.body" } };
}
@@ -0,0 +1,97 @@
import type { VMState } from "../index.js";
/**
* HR sick-leave view-models (AK-P17b). Pure functions. The AU certificate is
* sensitive: the VM NEVER carries the certificate File id or ciphertext — only a
* `hasCertificate` flag and a `revealHref` (a permission-checked + audited POST
* action decrypts it on demand). No React, no Prisma, no app imports.
*/
export type HrSickLeaveStatus = "reported" | "closed" | "cancelled";
export interface HrSickLeaveRow {
readonly id: string;
readonly status: HrSickLeaveStatus;
readonly statusLabelKey: string;
readonly startDateIso: string;
readonly expectedReturnDateIso: string | null;
readonly returnDateIso: string | null;
readonly note: string | null;
/** True when an (encrypted) certificate is attached; never the id itself. */
readonly hasCertificate: boolean;
/** POST action that decrypts + opens the certificate (gated + audited). */
readonly revealHref: string;
readonly canClose: boolean;
readonly canCancel: boolean;
}
export interface HrSickLeaveOwnData {
readonly rows: readonly HrSickLeaveRow[];
readonly canReport: boolean;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrSickLeaveOwnVM = VMState<HrSickLeaveOwnData>;
export interface HrSickLeaveOfficeRow extends HrSickLeaveRow {
readonly employeeLabel: string;
}
export interface HrSickLeaveOfficeData {
readonly rows: readonly HrSickLeaveOfficeRow[];
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrSickLeaveOfficeVM = VMState<HrSickLeaveOfficeData>;
export interface HrSickLeaveInputRow {
readonly id: string;
readonly status: HrSickLeaveStatus;
readonly startDateIso: string;
readonly expectedReturnDateIso: string | null;
readonly returnDateIso: string | null;
readonly note: string | null;
readonly hasCertificate: boolean;
readonly revealHref: string;
}
function toRow(row: HrSickLeaveInputRow): HrSickLeaveRow {
return {
id: row.id,
status: row.status,
statusLabelKey: `hr.sick.status.${row.status}`,
startDateIso: row.startDateIso,
expectedReturnDateIso: row.expectedReturnDateIso,
returnDateIso: row.returnDateIso,
note: row.note,
hasCertificate: row.hasCertificate,
revealHref: row.revealHref,
canClose: row.status === "reported",
canCancel: row.status !== "cancelled",
};
}
export function buildHrSickOwnVM(input: { rows: readonly HrSickLeaveInputRow[]; canReport: boolean }): HrSickLeaveOwnVM {
return {
status: "ready",
data: {
rows: input.rows.map(toRow),
canReport: input.canReport,
emptyHeadlineKey: "hr.sick.own.empty.headline",
emptyBodyKey: "hr.sick.own.empty.body",
},
};
}
export function buildHrSickOfficeVM(input: { rows: ReadonlyArray<HrSickLeaveInputRow & { employeeLabel: string }> }): HrSickLeaveOfficeVM {
return {
status: "ready",
data: {
rows: input.rows.map((row) => ({ ...toRow(row), employeeLabel: row.employeeLabel })),
emptyHeadlineKey: "hr.sick.office.empty.headline",
emptyBodyKey: "hr.sick.office.empty.body",
},
};
}
@@ -0,0 +1,122 @@
import type { VMState } from "../index.js";
/**
* HR survey view-models (AK-P17b). Pure functions. List, participation (items)
* and the gated results view (per-item distribution + average; chart rendering
* is the UI's job). No React, no Prisma, no app imports.
*/
export type HrSurveyItemType = "text" | "rating_5" | "nps" | "choice" | "boolean" | "date";
export type HrSurveyStatus = "draft" | "open" | "closed";
export interface HrSurveyListRow {
readonly id: string;
readonly title: string;
readonly status: HrSurveyStatus;
readonly statusLabelKey: string;
readonly isAnonymous: boolean;
readonly hasSubmitted: boolean;
readonly canViewResults: boolean;
readonly participateHref: string;
readonly resultsHref: string;
}
export interface HrSurveyListData {
readonly rows: readonly HrSurveyListRow[];
readonly canManage: boolean;
readonly createHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrSurveyListVM = VMState<HrSurveyListData>;
export interface HrSurveyItem {
readonly id: string;
readonly itemType: HrSurveyItemType;
readonly typeLabelKey: string;
readonly prompt: string;
readonly required: boolean;
readonly options: readonly string[];
}
export interface HrSurveyParticipationData {
readonly surveyId: string;
readonly title: string;
readonly description: string | null;
readonly isAnonymous: boolean;
readonly anonymousHintKey: string;
readonly items: readonly HrSurveyItem[];
readonly alreadySubmitted: boolean;
readonly submittedHintKey: string;
}
export type HrSurveyParticipationVM = VMState<HrSurveyParticipationData>;
export interface HrSurveyItemResult {
readonly itemId: string;
readonly prompt: string;
readonly itemType: HrSurveyItemType;
readonly responseCount: number;
readonly distribution: Readonly<Record<string, number>>;
readonly average: number | null;
readonly textResponses: readonly string[];
}
export interface HrSurveyResultsData {
readonly surveyId: string;
readonly title: string;
readonly submissionCount: number;
readonly isAnonymous: boolean;
readonly items: readonly HrSurveyItemResult[];
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrSurveyResultsVM = VMState<HrSurveyResultsData>;
interface SurveyListInputRow {
readonly id: string;
readonly title: string;
readonly status: HrSurveyStatus;
readonly isAnonymous: boolean;
readonly hasSubmitted: boolean;
readonly canViewResults: boolean;
readonly participateHref: string;
readonly resultsHref: string;
}
export function buildHrSurveyListVM(input: { rows: readonly SurveyListInputRow[]; canManage: boolean; createHref: string }): HrSurveyListVM {
const rows: HrSurveyListRow[] = input.rows.map((row) => ({ ...row, statusLabelKey: `hr.surveys.status.${row.status}` }));
return { status: "ready", data: { rows, canManage: input.canManage, createHref: input.createHref, emptyHeadlineKey: "hr.surveys.empty.headline", emptyBodyKey: "hr.surveys.empty.body" } };
}
export function buildHrSurveyParticipationVM(input: {
surveyId: string;
title: string;
description: string | null;
isAnonymous: boolean;
items: ReadonlyArray<Omit<HrSurveyItem, "typeLabelKey">>;
alreadySubmitted: boolean;
}): HrSurveyParticipationVM {
return {
status: "ready",
data: {
surveyId: input.surveyId,
title: input.title,
description: input.description,
isAnonymous: input.isAnonymous,
anonymousHintKey: "hr.surveys.participation.anonymousHint",
items: input.items.map((item) => ({ ...item, typeLabelKey: `hr.surveys.itemType.${item.itemType}` })),
alreadySubmitted: input.alreadySubmitted,
submittedHintKey: "hr.surveys.participation.submittedHint",
},
};
}
export function buildHrSurveyResultsVM(input: { surveyId: string; title: string; submissionCount: number; isAnonymous: boolean; items: readonly HrSurveyItemResult[] }): HrSurveyResultsVM {
return {
status: "ready",
data: { ...input, emptyHeadlineKey: "hr.surveys.results.empty.headline", emptyBodyKey: "hr.surveys.results.empty.body" },
};
}
@@ -0,0 +1,75 @@
import type { VMState } from "../index.js";
import type { HrReminderCadenceKind } from "./reminder-cadence.js";
/**
* HR upload-reminder admin view-model (AK-P17b). Pure function. Lists reminder
* definitions with cadence/audience/status labels and dispatch counts. No React,
* no Prisma, no app imports. `HrReminderCadenceKind` is reused from
* reminder-cadence.js to keep a single source of truth for the cadence union.
*/
export type HrReminderStatus = "active" | "paused" | "completed";
export interface HrReminderRow {
readonly id: string;
readonly title: string;
readonly cadenceKind: HrReminderCadenceKind;
readonly cadenceLabelKey: string;
readonly intervalMonths: number | null;
readonly documentKindKey: string;
readonly audienceLabelKey: string;
readonly mandatory: boolean;
readonly escalateToManager: boolean;
readonly status: HrReminderStatus;
readonly statusLabelKey: string;
readonly dueIso: string | null;
readonly pendingCount: number;
readonly detailHref: string;
}
export interface HrReminderListData {
readonly rows: readonly HrReminderRow[];
readonly createHref: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type HrReminderListVM = VMState<HrReminderListData>;
export interface HrReminderInputRow {
readonly id: string;
readonly title: string;
readonly cadenceKind: HrReminderCadenceKind;
readonly intervalMonths: number | null;
readonly documentKind: string;
readonly audienceKind: string;
readonly mandatory: boolean;
readonly escalateToManager: boolean;
readonly status: HrReminderStatus;
readonly dueIso: string | null;
readonly pendingCount: number;
readonly detailHref: string;
}
export function buildHrReminderListVM(input: { rows: readonly HrReminderInputRow[]; createHref: string }): HrReminderListVM {
const rows: HrReminderRow[] = input.rows.map((row) => ({
id: row.id,
title: row.title,
cadenceKind: row.cadenceKind,
cadenceLabelKey: `hr.reminders.cadence.${row.cadenceKind}`,
intervalMonths: row.intervalMonths,
documentKindKey: `hr.document.kind.${row.documentKind}`,
audienceLabelKey: `hr.audience.${row.audienceKind}`,
mandatory: row.mandatory,
escalateToManager: row.escalateToManager,
status: row.status,
statusLabelKey: `hr.reminders.status.${row.status}`,
dueIso: row.dueIso,
pendingCount: row.pendingCount,
detailHref: row.detailHref,
}));
return {
status: "ready",
data: { rows, createHref: input.createHref, emptyHeadlineKey: "hr.reminders.empty.headline", emptyBodyKey: "hr.reminders.empty.body" },
};
}
@@ -0,0 +1,48 @@
import { describe, expect, it } from "vitest";
import { matchPayslipFile, type PayslipMatchEmployee } from "./payslip-match.js";
// AK-P17b — payslip auto-match is pure. Covers hard (personal number), soft
// (name), ambiguous and no-match classifications.
const employees: PayslipMatchEmployee[] = [
{ userId: "u1", personalNumber: "0042", name: "Alex Doe" },
{ userId: "u2", personalNumber: "0043", name: "Sam Roe" },
{ userId: "u3", personalNumber: null, name: "Alex Smith" },
];
describe("matchPayslipFile", () => {
it("hard-matches on a unique personal number token", () => {
const r = matchPayslipFile("lohn_2026_07_0042.pdf", employees);
expect(r.confidence).toBe("hard");
expect(r.employeeUserId).toBe("u1");
});
it("normalises a prefixed personal number (PN-0043 ⇒ 0043)", () => {
const r = matchPayslipFile("payslip-PN-0043-juli.pdf", [{ userId: "u2", personalNumber: "PN-0043", name: "Sam Roe" }]);
expect(r.confidence).toBe("hard");
expect(r.employeeUserId).toBe("u2");
});
it("soft-matches on full name when no personal number hits", () => {
const r = matchPayslipFile("Sam_Roe_07_2026.pdf", employees);
expect(r.confidence).toBe("soft");
expect(r.employeeUserId).toBe("u2");
});
it("downgrades to ambiguous soft when a partial name matches several", () => {
const r = matchPayslipFile("Alex_2026.pdf", [
{ userId: "u1", personalNumber: "0042", name: "Alex" },
{ userId: "u3", personalNumber: null, name: "Alex" },
]);
expect(r.confidence).toBe("soft");
expect(r.employeeUserId).toBeNull();
expect(r.candidateUserIds).toHaveLength(2);
});
it("returns none when nothing matches", () => {
const r = matchPayslipFile("random_document.pdf", employees);
expect(r.confidence).toBe("none");
expect(r.employeeUserId).toBeNull();
expect(r.candidateUserIds).toHaveLength(0);
});
});
@@ -0,0 +1,76 @@
/**
* Payslip bulk-upload auto-match (AK-P17b). Pure function — no DB, no IO — so it
* is unit-testable in isolation. Given an uploaded file name and the tenant's
* employees, it classifies the match confidence:
* - `hard`: the file name contains the employee's personal number as a token.
* - `soft`: the file name contains the employee's (last) name but no personal
* number hit, OR more than one employee matches by name.
* - `none`: nothing matched.
* The admin confirms/overrides before any payslip is created. This module maps a
* file name to a single best classification plus the ambiguous candidate set.
*/
export type PayslipMatchConfidence = "hard" | "soft" | "none";
export interface PayslipMatchEmployee {
readonly userId: string;
readonly personalNumber: string | null;
/** Display name (e.g. "Alex Doe"); matched token-wise, case-insensitive. */
readonly name: string;
}
export interface PayslipMatchResult {
readonly fileName: string;
readonly confidence: PayslipMatchConfidence;
/** The single matched employee when unambiguous; null for none/ambiguous. */
readonly employeeUserId: string | null;
/** All plausible candidates (length > 1 ⇒ ambiguous ⇒ soft). */
readonly candidateUserIds: readonly string[];
}
/** Lowercased alphanumeric tokens of length ≥ 2 (drops the file extension). */
function tokenize(value: string): string[] {
const withoutExt = value.replace(/\.[a-z0-9]{1,5}$/i, "");
return withoutExt
.toLowerCase()
.split(/[^a-z0-9]+/i)
.filter((token) => token.length >= 2);
}
/** Normalised digits of a personal number (so "PN-0042" matches "0042"). */
function digitsOf(value: string): string {
return value.replace(/\D+/g, "");
}
export function matchPayslipFile(fileName: string, employees: readonly PayslipMatchEmployee[]): PayslipMatchResult {
const tokens = tokenize(fileName);
const tokenSet = new Set(tokens);
const haystackDigits = digitsOf(fileName);
// 1. Hard match on personal number (unique digit token in the file name).
const hardHits = employees.filter((employee) => {
const pn = employee.personalNumber ? digitsOf(employee.personalNumber) : "";
return pn.length >= 2 && haystackDigits.includes(pn);
});
if (hardHits.length === 1) {
return { fileName, confidence: "hard", employeeUserId: hardHits[0]!.userId, candidateUserIds: [hardHits[0]!.userId] };
}
if (hardHits.length > 1) {
// Multiple personal-number hits ⇒ ambiguous, downgrade to soft.
return { fileName, confidence: "soft", employeeUserId: null, candidateUserIds: hardHits.map((e) => e.userId) };
}
// 2. Soft match on name tokens (every name token present in the file name).
const nameHits = employees.filter((employee) => {
const nameTokens = tokenize(employee.name);
return nameTokens.length > 0 && nameTokens.every((token) => tokenSet.has(token));
});
if (nameHits.length === 1) {
return { fileName, confidence: "soft", employeeUserId: nameHits[0]!.userId, candidateUserIds: [nameHits[0]!.userId] };
}
if (nameHits.length > 1) {
return { fileName, confidence: "soft", employeeUserId: null, candidateUserIds: nameHits.map((e) => e.userId) };
}
return { fileName, confidence: "none", employeeUserId: null, candidateUserIds: [] };
}
@@ -0,0 +1,29 @@
import { describe, expect, it } from "vitest";
import { computeNextDue } from "./reminder-cadence.js";
// AK-P17b — cadence math is pure. Covers every cadence kind.
describe("computeNextDue", () => {
const from = new Date("2026-01-15T00:00:00.000Z");
it("returns null for a one-off reminder", () => {
expect(computeNextDue({ cadenceKind: "once", from })).toBeNull();
});
it("advances a yearly reminder by 12 months", () => {
const next = computeNextDue({ cadenceKind: "yearly", from })!;
expect(next.getFullYear()).toBe(2027);
expect(next.getMonth()).toBe(0);
});
it("advances every_n_months by the interval (default 1)", () => {
expect(computeNextDue({ cadenceKind: "every_n_months", intervalMonths: 3, from })!.getMonth()).toBe(3);
expect(computeNextDue({ cadenceKind: "every_n_months", intervalMonths: null, from })!.getMonth()).toBe(1);
});
it("uses the document expiry for on_expiry, null when absent", () => {
const expiry = new Date("2026-06-30T00:00:00.000Z");
expect(computeNextDue({ cadenceKind: "on_expiry", from, validUntil: expiry })).toEqual(expiry);
expect(computeNextDue({ cadenceKind: "on_expiry", from, validUntil: null })).toBeNull();
});
});
@@ -0,0 +1,42 @@
/**
* Upload-reminder cadence math (AK-P17b). Pure function — no DB, no IO — so it
* is unit-testable. Given a cadence and the current due date, it computes the
* NEXT due date (or null when the cadence does not repeat).
*/
export type HrReminderCadenceKind = "once" | "yearly" | "every_n_months" | "on_expiry";
export interface ComputeNextDueInput {
readonly cadenceKind: HrReminderCadenceKind;
/** Months between dispatches for `every_n_months` (defaults to 1 if absent). */
readonly intervalMonths?: number | null;
/** The current due date the next one is derived from. */
readonly from: Date;
/** Document expiry for `on_expiry`; the next due equals this date. */
readonly validUntil?: Date | null;
}
/** Add `months` calendar months to `date` (clamps to month length). */
function addMonths(date: Date, months: number): Date {
const result = new Date(date.getTime());
const targetMonth = result.getMonth() + months;
result.setMonth(targetMonth);
return result;
}
export function computeNextDue(input: ComputeNextDueInput): Date | null {
switch (input.cadenceKind) {
case "once":
return null;
case "yearly":
return addMonths(input.from, 12);
case "every_n_months": {
const interval = input.intervalMonths && input.intervalMonths > 0 ? Math.floor(input.intervalMonths) : 1;
return addMonths(input.from, interval);
}
case "on_expiry":
return input.validUntil ?? null;
default:
return null;
}
}