hvp-shared 13.1.0 → 13.2.0

package/dist/contracts/document/requests.d.ts

@@ -240,3 +240,26 @@ export interface SearchDocumentsQuery {
     q: string;
     limit?: number;
 }
+/**
+ * Compliance Matrix Query
+ *
+ * Filters for the admin/manager `GET /api/documents/acknowledgments/matrix`
+ * endpoint. All optional. The endpoint always restricts to docs that
+ * `requiresAcknowledgment === true` AND `status === "current"` — those are
+ * the only docs an ack is meaningful on.
+ *
+ * @example GET /api/documents/acknowledgments/matrix?category=operational
+ */
+export interface DocumentComplianceMatrixQuery {
+    /** Restrict rows to these doc IDs. */
+    documentIds?: string[];
+    /** Restrict columns to these collaborator IDs. */
+    collaboratorIds?: string[];
+    /** Filter rows by document category. */
+    category?: Category;
+    /**
+     * Filter rows whose audience includes this role (or `"all"`). Lets admin
+     * scope the matrix to docs everyone has to read, or only managers, etc.
+     */
+    audienceRole?: DocumentAudienceEntry;
+}

package/dist/contracts/document/responses.d.ts

@@ -6,6 +6,7 @@
  *   - Use Public → View → Admin inheritance where it adds value.
  */
 import { Category, ChangeType, ContentType, Criticality, DocumentStatus, DocumentType, ExternalLinkProvider } from "../../constants/document.enums";
+import { WebAppRole } from "../../constants/collaborator.constants";
 import { DocumentAudienceEntry } from "./requests";
 /**
  * Compact reference to a document's current version, embedded in
@@ -160,3 +161,74 @@ export interface PendingAcknowledgmentResponse {
     pendingDays: number;
     isFromOnboarding: boolean;
 }
+/**
+ * Compliance Matrix Cell
+ *
+ * Per `(document, collaborator)` pair, the read state.
+ *
+ * - `acked` — collaborator has a valid ack on the doc's current version
+ *   (covers patch chains; major/minor invalidates).
+ * - `pending` — collaborator is in the doc's audience and has NOT acked.
+ * - `not_applicable` — collaborator's role is outside the doc's audience.
+ */
+export type DocumentComplianceCellStatus = "acked" | "pending" | "not_applicable";
+export interface DocumentComplianceCell {
+    collaboratorId: string;
+    status: DocumentComplianceCellStatus;
+    /** Present when `status === "acked"`. ISO 8601. */
+    acknowledgedAt?: string;
+}
+/**
+ * Compliance Matrix Collaborator (column header)
+ *
+ * Compact info needed to render a column header. Order of `collaborators[]`
+ * in the response matches order of `cells[]` on each row.
+ */
+export interface DocumentComplianceCollaborator {
+    id: string;
+    col_code: string;
+    fullName: string;
+    role: WebAppRole;
+}
+/**
+ * Compliance Matrix Row (one document)
+ */
+export interface DocumentComplianceRow {
+    documentId: string;
+    documentSlug: string;
+    documentTitle: string;
+    category: Category;
+    criticality: Criticality;
+    audience: DocumentAudienceEntry[];
+    currentVersionId: string | null;
+    /** Semver string of the current version, e.g. "1.2.0". */
+    versionNumber: string | null;
+    /** Number of collaborators in the matrix that the audience applies to. */
+    totalApplicable: number;
+    /** Of those, how many have a valid ack on the current version. */
+    totalAcked: number;
+    /** `totalAcked / totalApplicable * 100`, rounded to 0 decimals. 0 when N/A. */
+    pctRead: number;
+    /** Index-aligned with the response's `collaborators[]`. */
+    cells: DocumentComplianceCell[];
+}
+/**
+ * Document Compliance Matrix Response
+ *
+ * Admin/manager view: matrix of "who has read what". Rows are documents,
+ * columns are collaborators.
+ *
+ * Used for: `GET /api/documents/acknowledgments/matrix`
+ */
+export interface DocumentComplianceMatrixResponse {
+    collaborators: DocumentComplianceCollaborator[];
+    rows: DocumentComplianceRow[];
+    /** Total docs in the response (rows.length, surfaced for KPI). */
+    totalDocs: number;
+    /** Total applicable doc-collaborator pairs across all rows. */
+    totalApplicablePairs: number;
+    /** Of those, how many are acked. */
+    totalAckedPairs: number;
+    /** Average of pctRead across rows (or `totalAckedPairs / totalApplicablePairs * 100`). */
+    pctReadOverall: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvp-shared",
-  "version": "13.1.0",
+  "version": "13.2.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",