hvp-shared 7.6.0 → 7.7.0

package/dist/constants/document.enums.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Document Enums — new document management system (GH#21).
+ *
+ * Replaces the legacy `documentation.enums.ts` (which keeps serving the legacy
+ * `documentations` collection during the 60-day retention window). Do not mix
+ * the two — `documentation.*` = legacy, `document.*` = new system.
+ *
+ * Conventions:
+ * - snake_case values per `.claude/rules/enums.md`
+ * - `*_LABELS: Record<Enum, string>` Spanish labels alongside each enum
+ *
+ * @see .claude/plans/active/20260427-GH21-documentation-system-redesign.md
+ */
+/**
+ * Sentinel value for `audience: WebAppRole[]` meaning "visible to everyone".
+ * Stored as a literal string in the audience array; resolved at query time to
+ * skip the role filter.
+ */
+export declare const AUDIENCE_ALL = "all";
+/**
+ * High-level reason a document exists. The first axis of the 3-tier
+ * classification (purpose → type → tags).
+ */
+export declare enum Purpose {
+    operational = "operational",
+    resource = "resource",
+    archive = "archive"
+}
+export declare const PURPOSE_LABELS: Record<Purpose, string>;
+/**
+ * Specific kind of document within a purpose. Second axis of classification.
+ *
+ * Mapping of legacy `DocumentationType` is documented in the migration script
+ * (`migrate-documentations-to-documents.ts`). Some values exist purely so
+ * legacy docs map cleanly (e.g. `meeting_recording` for `admon` videos).
+ */
+export declare enum DocumentType {
+    protocol = "protocol",
+    guidance = "guidance",
+    tutorial = "tutorial",
+    format = "format",
+    tool = "tool",
+    policy = "policy",
+    reference_data = "reference_data",
+    training_material = "training_material",
+    legal_document = "legal_document",
+    brand_asset = "brand_asset",
+    meeting_recording = "meeting_recording",
+    historical = "historical"
+}
+export declare const DOCUMENT_TYPE_LABELS: Record<DocumentType, string>;
+/**
+ * Lifecycle state of the document.
+ *
+ * Per workflow decision (master plan §Decision 3): there are NO automatic
+ * direct-publish rules per criticality — author chooses to publish directly
+ * or send to in_review. Reviewer (different person from author) approves.
+ */
+export declare enum DocumentStatus {
+    draft = "draft",
+    in_review = "in_review",
+    published = "published",
+    archived = "archived"
+}
+export declare const DOCUMENT_STATUS_LABELS: Record<DocumentStatus, string>;
+/**
+ * How critical the document is. Used for ranking, badge color, and (in SP4)
+ * acknowledgment urgency.
+ */
+export declare enum Criticality {
+    informational = "informational",
+    standard = "standard",
+    important = "important",
+    critical = "critical"
+}
+export declare const CRITICALITY_LABELS: Record<Criticality, string>;
+/**
+ * Semver-style classification of a new version's changes.
+ *
+ * Drives ack invalidation logic in SP4: `major`/`minor` invalidate prior acks;
+ * `patch` does not (per master plan §4.3).
+ */
+export declare enum ChangeType {
+    patch = "patch",
+    minor = "minor",
+    major = "major"
+}
+export declare const CHANGE_TYPE_LABELS: Record<ChangeType, string>;
+/**
+ * How the document body is stored.
+ *
+ * - `markdown`: body is in `DocumentVersion.markdown`
+ * - `external_link`: body lives outside the system (Dropbox/YouTube/etc.)
+ * - `mixed`: both — markdown wraps an embedded link
+ */
+export declare enum ContentType {
+    markdown = "markdown",
+    external_link = "external_link",
+    mixed = "mixed"
+}
+export declare const CONTENT_TYPE_LABELS: Record<ContentType, string>;
+/**
+ * Known providers for `external_link` content. Drives icon + preview card +
+ * disclaimer in the doc viewer.
+ */
+export declare enum ExternalLinkProvider {
+    youtube = "youtube",
+    dropbox = "dropbox",
+    google_drive = "google_drive",
+    dailymotion = "dailymotion",
+    other = "other"
+}
+export declare const EXTERNAL_LINK_PROVIDER_LABELS: Record<ExternalLinkProvider, string>;

package/dist/constants/document.enums.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Document Enums — new document management system (GH#21).
+ *
+ * Replaces the legacy `documentation.enums.ts` (which keeps serving the legacy
+ * `documentations` collection during the 60-day retention window). Do not mix
+ * the two — `documentation.*` = legacy, `document.*` = new system.
+ *
+ * Conventions:
+ * - snake_case values per `.claude/rules/enums.md`
+ * - `*_LABELS: Record<Enum, string>` Spanish labels alongside each enum
+ *
+ * @see .claude/plans/active/20260427-GH21-documentation-system-redesign.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTERNAL_LINK_PROVIDER_LABELS = exports.ExternalLinkProvider = exports.CONTENT_TYPE_LABELS = exports.ContentType = exports.CHANGE_TYPE_LABELS = exports.ChangeType = exports.CRITICALITY_LABELS = exports.Criticality = exports.DOCUMENT_STATUS_LABELS = exports.DocumentStatus = exports.DOCUMENT_TYPE_LABELS = exports.DocumentType = exports.PURPOSE_LABELS = exports.Purpose = exports.AUDIENCE_ALL = void 0;
+// ─── Audience sentinel ──────────────────────────────────────────────────────
+/**
+ * Sentinel value for `audience: WebAppRole[]` meaning "visible to everyone".
+ * Stored as a literal string in the audience array; resolved at query time to
+ * skip the role filter.
+ */
+exports.AUDIENCE_ALL = "all";
+// ─── Purpose ────────────────────────────────────────────────────────────────
+/**
+ * High-level reason a document exists. The first axis of the 3-tier
+ * classification (purpose → type → tags).
+ */
+var Purpose;
+(function (Purpose) {
+    Purpose["operational"] = "operational";
+    Purpose["resource"] = "resource";
+    Purpose["archive"] = "archive";
+})(Purpose || (exports.Purpose = Purpose = {}));
+exports.PURPOSE_LABELS = {
+    [Purpose.operational]: "Operativo",
+    [Purpose.resource]: "Recurso",
+    [Purpose.archive]: "Archivo",
+};
+// ─── DocumentType ───────────────────────────────────────────────────────────
+/**
+ * Specific kind of document within a purpose. Second axis of classification.
+ *
+ * Mapping of legacy `DocumentationType` is documented in the migration script
+ * (`migrate-documentations-to-documents.ts`). Some values exist purely so
+ * legacy docs map cleanly (e.g. `meeting_recording` for `admon` videos).
+ */
+var DocumentType;
+(function (DocumentType) {
+    // Operational
+    DocumentType["protocol"] = "protocol";
+    DocumentType["guidance"] = "guidance";
+    DocumentType["tutorial"] = "tutorial";
+    DocumentType["format"] = "format";
+    DocumentType["tool"] = "tool";
+    DocumentType["policy"] = "policy";
+    // Resource
+    DocumentType["reference_data"] = "reference_data";
+    DocumentType["training_material"] = "training_material";
+    DocumentType["legal_document"] = "legal_document";
+    DocumentType["brand_asset"] = "brand_asset";
+    // Archive
+    DocumentType["meeting_recording"] = "meeting_recording";
+    DocumentType["historical"] = "historical";
+})(DocumentType || (exports.DocumentType = DocumentType = {}));
+exports.DOCUMENT_TYPE_LABELS = {
+    [DocumentType.protocol]: "Protocolo",
+    [DocumentType.guidance]: "Lineamiento",
+    [DocumentType.tutorial]: "Tutorial",
+    [DocumentType.format]: "Formato",
+    [DocumentType.tool]: "Herramienta",
+    [DocumentType.policy]: "Política",
+    [DocumentType.reference_data]: "Datos de referencia",
+    [DocumentType.training_material]: "Material de capacitación",
+    [DocumentType.legal_document]: "Documento legal",
+    [DocumentType.brand_asset]: "Activo de marca",
+    [DocumentType.meeting_recording]: "Grabación de reunión",
+    [DocumentType.historical]: "Histórico",
+};
+// ─── DocumentStatus ─────────────────────────────────────────────────────────
+/**
+ * Lifecycle state of the document.
+ *
+ * Per workflow decision (master plan §Decision 3): there are NO automatic
+ * direct-publish rules per criticality — author chooses to publish directly
+ * or send to in_review. Reviewer (different person from author) approves.
+ */
+var DocumentStatus;
+(function (DocumentStatus) {
+    DocumentStatus["draft"] = "draft";
+    DocumentStatus["in_review"] = "in_review";
+    DocumentStatus["published"] = "published";
+    DocumentStatus["archived"] = "archived";
+})(DocumentStatus || (exports.DocumentStatus = DocumentStatus = {}));
+exports.DOCUMENT_STATUS_LABELS = {
+    [DocumentStatus.draft]: "Borrador",
+    [DocumentStatus.in_review]: "En revisión",
+    [DocumentStatus.published]: "Publicado",
+    [DocumentStatus.archived]: "Archivado",
+};
+// ─── Criticality ────────────────────────────────────────────────────────────
+/**
+ * How critical the document is. Used for ranking, badge color, and (in SP4)
+ * acknowledgment urgency.
+ */
+var Criticality;
+(function (Criticality) {
+    Criticality["informational"] = "informational";
+    Criticality["standard"] = "standard";
+    Criticality["important"] = "important";
+    Criticality["critical"] = "critical";
+})(Criticality || (exports.Criticality = Criticality = {}));
+exports.CRITICALITY_LABELS = {
+    [Criticality.informational]: "Informativo",
+    [Criticality.standard]: "Estándar",
+    [Criticality.important]: "Importante",
+    [Criticality.critical]: "Crítico",
+};
+// ─── ChangeType ─────────────────────────────────────────────────────────────
+/**
+ * Semver-style classification of a new version's changes.
+ *
+ * Drives ack invalidation logic in SP4: `major`/`minor` invalidate prior acks;
+ * `patch` does not (per master plan §4.3).
+ */
+var ChangeType;
+(function (ChangeType) {
+    ChangeType["patch"] = "patch";
+    ChangeType["minor"] = "minor";
+    ChangeType["major"] = "major";
+})(ChangeType || (exports.ChangeType = ChangeType = {}));
+exports.CHANGE_TYPE_LABELS = {
+    [ChangeType.patch]: "Corrección menor",
+    [ChangeType.minor]: "Cambio menor",
+    [ChangeType.major]: "Cambio mayor",
+};
+// ─── ContentType ────────────────────────────────────────────────────────────
+/**
+ * How the document body is stored.
+ *
+ * - `markdown`: body is in `DocumentVersion.markdown`
+ * - `external_link`: body lives outside the system (Dropbox/YouTube/etc.)
+ * - `mixed`: both — markdown wraps an embedded link
+ */
+var ContentType;
+(function (ContentType) {
+    ContentType["markdown"] = "markdown";
+    ContentType["external_link"] = "external_link";
+    ContentType["mixed"] = "mixed";
+})(ContentType || (exports.ContentType = ContentType = {}));
+exports.CONTENT_TYPE_LABELS = {
+    [ContentType.markdown]: "Markdown",
+    [ContentType.external_link]: "Enlace externo",
+    [ContentType.mixed]: "Mixto",
+};
+// ─── ExternalLinkProvider ───────────────────────────────────────────────────
+/**
+ * Known providers for `external_link` content. Drives icon + preview card +
+ * disclaimer in the doc viewer.
+ */
+var ExternalLinkProvider;
+(function (ExternalLinkProvider) {
+    ExternalLinkProvider["youtube"] = "youtube";
+    ExternalLinkProvider["dropbox"] = "dropbox";
+    ExternalLinkProvider["google_drive"] = "google_drive";
+    ExternalLinkProvider["dailymotion"] = "dailymotion";
+    ExternalLinkProvider["other"] = "other";
+})(ExternalLinkProvider || (exports.ExternalLinkProvider = ExternalLinkProvider = {}));
+exports.EXTERNAL_LINK_PROVIDER_LABELS = {
+    [ExternalLinkProvider.youtube]: "YouTube",
+    [ExternalLinkProvider.dropbox]: "Dropbox",
+    [ExternalLinkProvider.google_drive]: "Google Drive",
+    [ExternalLinkProvider.dailymotion]: "Dailymotion",
+    [ExternalLinkProvider.other]: "Otro",
+};

package/dist/constants/index.d.ts

@@ -23,6 +23,7 @@ export * from './hris.constants';
 export * from './payroll-features.constants';
 export * from './inventory-session.enums';
 export * from './documentation.enums';
+export * from './document.enums';
 export * from './settlement.enums';
 export * from './client-billing.enums';
 export * from './sat-income-invoice';

package/dist/constants/index.js

@@ -39,6 +39,7 @@ __exportStar(require("./hris.constants"), exports);
 __exportStar(require("./payroll-features.constants"), exports);
 __exportStar(require("./inventory-session.enums"), exports);
 __exportStar(require("./documentation.enums"), exports);
+__exportStar(require("./document.enums"), exports);
 __exportStar(require("./settlement.enums"), exports);
 __exportStar(require("./client-billing.enums"), exports);
 __exportStar(require("./sat-income-invoice"), exports);

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

@@ -0,0 +1,6 @@
+/**
+ * Document API Contracts (GH#21)
+ * Request and Response types for the new document management system.
+ */
+export * from "./requests";
+export * from "./responses";

package/dist/contracts/document/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Document API Contracts (GH#21)
+ * Request and Response types for the new document management system.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./requests"), exports);
+__exportStar(require("./responses"), exports);

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

@@ -0,0 +1,184 @@
+/**
+ * Document API Request Contracts (GH#21)
+ *
+ * Shapes the frontend (and migration script) sends to the backend.
+ * Per `api-contracts.md`:
+ *   - Date fields are ISO 8601 strings, never `Date` objects.
+ *   - Update requests are partial; Create requests are complete.
+ */
+import { ChangeType, ContentType, Criticality, DocumentStatus, DocumentType, ExternalLinkProvider, Purpose } from "../../constants/document.enums";
+import { WebAppRole } from "../../constants/collaborator.constants";
+/**
+ * One element of `audience[]`. Either a role or the `"all"` sentinel.
+ *
+ * Stored as plain strings in DB (e.g. `["Administrador", "Gerente"]` or
+ * `["all"]`); resolved at query time.
+ */
+export type DocumentAudienceEntry = WebAppRole | "all";
+/**
+ * Body for a document version's content. Exactly one of `markdown` /
+ * `externalLink` is required for `markdown` / `external_link` contentType;
+ * BOTH are required for `mixed`.
+ */
+export interface DocumentVersionContent {
+    contentType: ContentType;
+    markdown?: string;
+    externalLink?: {
+        url: string;
+        provider: ExternalLinkProvider;
+    };
+}
+/**
+ * Create Document Request
+ *
+ * Creates a new document AND its initial version (always status=draft,
+ * versionNumber="1.0.0"). Author becomes `createdBy`.
+ *
+ * @example POST /api/documents
+ */
+export interface CreateDocumentRequest {
+    title: string;
+    /** Optional — auto-generated from title via slugify if omitted. */
+    slug?: string;
+    /** Optional human-readable code (e.g. "PROT-EGO-01"). */
+    code?: string;
+    purpose: Purpose;
+    type: DocumentType;
+    tags?: string[];
+    audience: DocumentAudienceEntry[];
+    criticality: Criticality;
+    requiredForOnboarding?: boolean;
+    requiresAcknowledgment?: boolean;
+    /** ObjectIds (as strings) of related documents. */
+    references?: string[];
+    /** Initial version content. */
+    initialVersion: DocumentVersionContent;
+}
+/**
+ * Update Document Metadata Request
+ *
+ * Updates metadata only (no version change). For content edits use
+ * SaveDraftVersionRequest or CreateNewVersionRequest.
+ *
+ * @example PATCH /api/documents/:id
+ */
+export interface UpdateDocumentMetadataRequest {
+    title?: string;
+    slug?: string;
+    code?: string | null;
+    purpose?: Purpose;
+    type?: DocumentType;
+    tags?: string[];
+    audience?: DocumentAudienceEntry[];
+    criticality?: Criticality;
+    requiredForOnboarding?: boolean;
+    requiresAcknowledgment?: boolean;
+    references?: string[];
+}
+/**
+ * Save Draft Version Request
+ *
+ * Updates the existing draft version row in place (no new row created).
+ * Only valid while a draft version exists.
+ *
+ * @example PATCH /api/documents/:id/versions/draft
+ */
+export interface SaveDraftVersionRequest {
+    content: DocumentVersionContent;
+}
+/**
+ * Create New Version Request
+ *
+ * Branches a new draft version from the currently published version.
+ * Used when editing an already-published document.
+ *
+ * @example POST /api/documents/:id/versions
+ */
+export interface CreateNewVersionRequest {
+    changeType: ChangeType;
+    changeNotes: string;
+    content: DocumentVersionContent;
+}
+/**
+ * Submit For Review Request
+ *
+ * Transitions a draft to `in_review`. Empty body — context comes from URL.
+ *
+ * @example POST /api/documents/:id/submit-for-review
+ */
+export type SubmitForReviewRequest = Record<string, never>;
+/**
+ * Publish Document Request
+ *
+ * Transitions a draft or in_review version to `published`. The current
+ * published version (if any) becomes superseded.
+ *
+ * Per master plan §Decision 3: no automatic enforcement of review-required
+ * rules per criticality — backend trusts the caller's authorization.
+ *
+ * @example POST /api/documents/:id/publish
+ */
+export interface PublishDocumentRequest {
+    /** Required if publishing without prior in_review (audit trail). */
+    changeNotes?: string;
+}
+/**
+ * Archive Document Request
+ *
+ * Marks the document as `archived`. Archived docs are hidden from default
+ * lists but data is preserved. Restricted to admin for `legal_document` and
+ * `brand_asset` types.
+ *
+ * @example POST /api/documents/:id/archive
+ */
+export interface ArchiveDocumentRequest {
+    reason?: string;
+}
+/**
+ * Unarchive Document Request
+ *
+ * Returns an archived doc to its prior `published` state. Admin only.
+ *
+ * @example POST /api/documents/:id/unarchive
+ */
+export type UnarchiveDocumentRequest = Record<string, never>;
+/**
+ * Acknowledge Version Request
+ *
+ * Records that the calling user has read the current version of the document.
+ * Idempotent — second call is a no-op.
+ *
+ * @example POST /api/documents/:id/acknowledge
+ */
+export type AcknowledgeVersionRequest = Record<string, never>;
+/**
+ * List Documents Query Filters
+ *
+ * Query string parameters for `GET /api/documents`. All optional. Audience
+ * filtering by current user role is implicit (handled server-side).
+ *
+ * @example GET /api/documents?purpose=operational&status=published
+ */
+export interface ListDocumentsQuery {
+    purpose?: Purpose;
+    type?: DocumentType;
+    status?: DocumentStatus;
+    criticality?: Criticality;
+    /** Comma-separated tag list, OR semantics. */
+    tags?: string;
+    /** Substring match on title (server may also $text-search). */
+    search?: string;
+    requiredForOnboarding?: boolean;
+    requiresAcknowledgment?: boolean;
+    limit?: number;
+    skip?: number;
+}
+/**
+ * Search Documents Query
+ *
+ * @example GET /api/documents/search?q=comisiones
+ */
+export interface SearchDocumentsQuery {
+    q: string;
+    limit?: number;
+}

package/dist/contracts/document/requests.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Document API Request Contracts (GH#21)
+ *
+ * Shapes the frontend (and migration script) sends to the backend.
+ * Per `api-contracts.md`:
+ *   - Date fields are ISO 8601 strings, never `Date` objects.
+ *   - Update requests are partial; Create requests are complete.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,129 @@
+/**
+ * Document API Response Contracts (GH#21)
+ *
+ * Shapes the backend returns. Per `api-contracts.md`:
+ *   - Date fields are ISO 8601 strings (server converts Date → ISO at the mapper layer).
+ *   - Use Public → View → Admin inheritance where it adds value.
+ */
+import { ChangeType, ContentType, Criticality, DocumentStatus, DocumentType, ExternalLinkProvider, Purpose } from "../../constants/document.enums";
+import { DocumentAudienceEntry } from "./requests";
+/**
+ * Public Document Response
+ *
+ * Minimal fields. Used for related-doc previews in the viewer sidebar.
+ */
+export interface PublicDocumentResponse {
+    id: string;
+    slug: string;
+    title: string;
+    code: string | null;
+    purpose: Purpose;
+    type: DocumentType;
+    status: DocumentStatus;
+    criticality: Criticality;
+}
+/**
+ * Document View Response
+ *
+ * Standard fields shown in lists and the viewer header. Used by all
+ * authenticated endpoints unless admin-only fields are needed.
+ */
+export interface DocumentViewResponse extends PublicDocumentResponse {
+    tags: string[];
+    audience: DocumentAudienceEntry[];
+    requiredForOnboarding: boolean;
+    requiresAcknowledgment: boolean;
+    references: string[];
+    /** ObjectId of the current published version (or null for draft-only docs). */
+    currentVersionId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    createdBy: string;
+    updatedBy: string;
+}
+/**
+ * Admin Document Response
+ *
+ * Adds audit metadata. Used in admin tooling.
+ */
+export interface AdminDocumentResponse extends DocumentViewResponse {
+    /** Total versions ever created (current + superseded + drafts). */
+    versionCount: number;
+    /** Count of users who have acked the current version (null if requiresAck=false). */
+    currentVersionAckCount: number | null;
+}
+/**
+ * Document Summary Response
+ *
+ * Compact card used in list views and Cmd+K search results. Excludes heavy
+ * fields like `references`, `audience`, audit metadata.
+ */
+export interface DocumentSummaryResponse {
+    id: string;
+    slug: string;
+    title: string;
+    code: string | null;
+    purpose: Purpose;
+    type: DocumentType;
+    status: DocumentStatus;
+    criticality: Criticality;
+    tags: string[];
+    updatedAt: string;
+    /** Match snippet — only present in search responses. */
+    snippet?: string;
+}
+/**
+ * Document Version Response
+ *
+ * Full version row. Returned by the viewer, version history, and
+ * acknowledgment lookups.
+ */
+export interface DocumentVersionResponse {
+    id: string;
+    documentId: string;
+    versionNumber: string;
+    status: "draft" | "in_review" | "current" | "superseded";
+    contentType: ContentType;
+    markdown: string | null;
+    externalLink: {
+        url: string;
+        provider: ExternalLinkProvider;
+    } | null;
+    changeType: ChangeType;
+    changeNotes: string | null;
+    createdAt: string;
+    createdBy: string;
+    publishedAt: string | null;
+    publishedBy: string | null;
+}
+/**
+ * Document Acknowledgment Response
+ *
+ * One ack record. Used in the admin "who acknowledged" view.
+ */
+export interface DocumentAcknowledgmentResponse {
+    id: string;
+    documentId: string;
+    documentVersionId: string;
+    userId: string;
+    acknowledgedAt: string;
+    /** Distinguishes onboarding acks from voluntary ones. */
+    source: "voluntary" | "onboarding";
+}
+/**
+ * Pending Acknowledgment Response
+ *
+ * One row in the user-facing "pendientes de acuse" widget. Combines doc + version
+ * snapshot needed to render the card.
+ */
+export interface PendingAcknowledgmentResponse {
+    documentId: string;
+    documentSlug: string;
+    documentTitle: string;
+    documentVersionId: string;
+    versionNumber: string;
+    criticality: Criticality;
+    /** Days since the version was published (used for the 7-day red badge). */
+    pendingDays: number;
+    isFromOnboarding: boolean;
+}

package/dist/contracts/document/responses.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Document API Response Contracts (GH#21)
+ *
+ * Shapes the backend returns. Per `api-contracts.md`:
+ *   - Date fields are ISO 8601 strings (server converts Date → ISO at the mapper layer).
+ *   - Use Public → View → Admin inheritance where it adds value.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/index.d.ts

@@ -20,3 +20,4 @@ export * from './study-type-catalog';
 export * from './supplier-overlay';
 export * from './external-study';
 export * from './pending-dashboard';
+export * from './document';

package/dist/contracts/index.js

@@ -36,3 +36,4 @@ __exportStar(require("./study-type-catalog"), exports);
 __exportStar(require("./supplier-overlay"), exports);
 __exportStar(require("./external-study"), exports);
 __exportStar(require("./pending-dashboard"), exports);
+__exportStar(require("./document"), exports);

package/dist/validation/document.validation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Document Validation (GH#21)
+ *
+ * Pure validation functions for document fields. Mirrors the pattern of
+ * `rfc.validation.ts`, `email.validation.ts`, etc. — returns
+ * `ValidationResult` so callers (Value Objects in backend, frontend Zod
+ * schemas, migration scripts) all share one source of truth.
+ */
+import { ValidationResult } from "./rfc.validation";
+/**
+ * Validates a document slug.
+ *
+ * Rules:
+ * - 3–80 chars
+ * - lowercase alphanumeric + hyphens only
+ * - no leading/trailing/consecutive hyphens
+ *
+ * @example
+ *   validateDocumentSlug("protocolo-ego")        // { isValid: true }
+ *   validateDocumentSlug("Protocolo EGO")        // { isValid: false, error: ... }
+ *   validateDocumentSlug("ab")                    // { isValid: false, error: ... }
+ *   validateDocumentSlug("foo--bar")              // { isValid: false, error: ... }
+ */
+export declare function validateDocumentSlug(value: string | null | undefined): ValidationResult;
+/**
+ * Generates a slug candidate from arbitrary text. Caller is responsible for
+ * resolving collisions (typically by appending `-2`, `-3`, ...).
+ *
+ * NOTE: this is a best-effort transliteration. Spanish accents are mapped to
+ * their unaccented form. Other unicode is dropped.
+ */
+export declare function slugifyTitle(title: string): string;
+/**
+ * Validates a semver-style version number `major.minor.patch`.
+ *
+ * @example
+ *   validateVersionNumber("1.0.0")     // { isValid: true }
+ *   validateVersionNumber("1.0")        // { isValid: false }
+ *   validateVersionNumber("v1.0.0")     // { isValid: false }
+ */
+export declare function validateVersionNumber(value: string | null | undefined): ValidationResult;
+/**
+ * Parses a validated version string into its three numeric components.
+ * Throws if the input is invalid — call `validateVersionNumber` first.
+ */
+export declare function parseVersionNumber(value: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};

package/dist/validation/document.validation.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Document Validation (GH#21)
+ *
+ * Pure validation functions for document fields. Mirrors the pattern of
+ * `rfc.validation.ts`, `email.validation.ts`, etc. — returns
+ * `ValidationResult` so callers (Value Objects in backend, frontend Zod
+ * schemas, migration scripts) all share one source of truth.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDocumentSlug = validateDocumentSlug;
+exports.slugifyTitle = slugifyTitle;
+exports.validateVersionNumber = validateVersionNumber;
+exports.parseVersionNumber = parseVersionNumber;
+// ─── Slug ───────────────────────────────────────────────────────────────────
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_MIN_LENGTH = 3;
+const SLUG_MAX_LENGTH = 80;
+/**
+ * Validates a document slug.
+ *
+ * Rules:
+ * - 3–80 chars
+ * - lowercase alphanumeric + hyphens only
+ * - no leading/trailing/consecutive hyphens
+ *
+ * @example
+ *   validateDocumentSlug("protocolo-ego")        // { isValid: true }
+ *   validateDocumentSlug("Protocolo EGO")        // { isValid: false, error: ... }
+ *   validateDocumentSlug("ab")                    // { isValid: false, error: ... }
+ *   validateDocumentSlug("foo--bar")              // { isValid: false, error: ... }
+ */
+function validateDocumentSlug(value) {
+    if (!value || !value.trim()) {
+        return { isValid: false, error: "El slug es requerido" };
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < SLUG_MIN_LENGTH) {
+        return {
+            isValid: false,
+            error: `El slug debe tener al menos ${SLUG_MIN_LENGTH} caracteres`,
+        };
+    }
+    if (trimmed.length > SLUG_MAX_LENGTH) {
+        return {
+            isValid: false,
+            error: `El slug no puede exceder ${SLUG_MAX_LENGTH} caracteres`,
+        };
+    }
+    if (!SLUG_PATTERN.test(trimmed)) {
+        return {
+            isValid: false,
+            error: "El slug solo puede contener minúsculas, números y guiones (sin espacios ni guiones consecutivos)",
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Generates a slug candidate from arbitrary text. Caller is responsible for
+ * resolving collisions (typically by appending `-2`, `-3`, ...).
+ *
+ * NOTE: this is a best-effort transliteration. Spanish accents are mapped to
+ * their unaccented form. Other unicode is dropped.
+ */
+function slugifyTitle(title) {
+    return title
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "") // strip accents
+        .replace(/ñ/g, "n")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX_LENGTH)
+        .replace(/-+$/g, ""); // re-trim if slice landed on a hyphen
+}
+// ─── Version Number ─────────────────────────────────────────────────────────
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+/**
+ * Validates a semver-style version number `major.minor.patch`.
+ *
+ * @example
+ *   validateVersionNumber("1.0.0")     // { isValid: true }
+ *   validateVersionNumber("1.0")        // { isValid: false }
+ *   validateVersionNumber("v1.0.0")     // { isValid: false }
+ */
+function validateVersionNumber(value) {
+    if (!value || !value.trim()) {
+        return { isValid: false, error: "El número de versión es requerido" };
+    }
+    if (!VERSION_PATTERN.test(value.trim())) {
+        return {
+            isValid: false,
+            error: "Versión inválida. Formato esperado: MAJOR.MINOR.PATCH (ej. 1.0.0)",
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Parses a validated version string into its three numeric components.
+ * Throws if the input is invalid — call `validateVersionNumber` first.
+ */
+function parseVersionNumber(value) {
+    const result = validateVersionNumber(value);
+    if (!result.isValid) {
+        throw new Error(result.error ?? "Versión inválida");
+    }
+    const [major, minor, patch] = value.trim().split(".").map(Number);
+    return { major, minor, patch };
+}

package/dist/validation/document.validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/validation/document.validation.test.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const document_validation_1 = require("./document.validation");
+describe("validateDocumentSlug", () => {
+    describe("valid", () => {
+        it("accepts a kebab-case word", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("protocolo")).toEqual({ isValid: true });
+        });
+        it("accepts hyphens between segments", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("protocolo-ego")).toEqual({ isValid: true });
+        });
+        it("accepts numbers", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("manual-mpp-v20")).toEqual({ isValid: true });
+        });
+        it("accepts the minimum length", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("abc")).toEqual({ isValid: true });
+        });
+    });
+    describe("invalid", () => {
+        it("rejects empty", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("")).toMatchObject({ isValid: false });
+            expect((0, document_validation_1.validateDocumentSlug)("   ")).toMatchObject({ isValid: false });
+            expect((0, document_validation_1.validateDocumentSlug)(null)).toMatchObject({ isValid: false });
+            expect((0, document_validation_1.validateDocumentSlug)(undefined)).toMatchObject({ isValid: false });
+        });
+        it("rejects too short", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("ab")).toMatchObject({ isValid: false });
+        });
+        it("rejects too long", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("a".repeat(81))).toMatchObject({
+                isValid: false,
+            });
+        });
+        it("rejects uppercase", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("Protocolo")).toMatchObject({
+                isValid: false,
+            });
+        });
+        it("rejects spaces", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("protocolo ego")).toMatchObject({
+                isValid: false,
+            });
+        });
+        it("rejects underscores", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("protocolo_ego")).toMatchObject({
+                isValid: false,
+            });
+        });
+        it("rejects leading/trailing hyphens", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("-protocolo")).toMatchObject({
+                isValid: false,
+            });
+            expect((0, document_validation_1.validateDocumentSlug)("protocolo-")).toMatchObject({
+                isValid: false,
+            });
+        });
+        it("rejects consecutive hyphens", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("foo--bar")).toMatchObject({
+                isValid: false,
+            });
+        });
+        it("rejects accented characters", () => {
+            expect((0, document_validation_1.validateDocumentSlug)("protocolo-ñ")).toMatchObject({
+                isValid: false,
+            });
+        });
+    });
+});
+describe("slugifyTitle", () => {
+    it("converts spaces to hyphens", () => {
+        expect((0, document_validation_1.slugifyTitle)("Protocolo EGO")).toBe("protocolo-ego");
+    });
+    it("strips Spanish accents", () => {
+        expect((0, document_validation_1.slugifyTitle)("Anestésica común")).toBe("anestesica-comun");
+    });
+    it("converts ñ to n", () => {
+        expect((0, document_validation_1.slugifyTitle)("Compañeros")).toBe("companeros");
+    });
+    it("collapses repeated hyphens", () => {
+        expect((0, document_validation_1.slugifyTitle)("foo  bar — baz")).toBe("foo-bar-baz");
+    });
+    it("trims leading/trailing hyphens", () => {
+        expect((0, document_validation_1.slugifyTitle)("--foo--")).toBe("foo");
+    });
+    it("preserves digits", () => {
+        expect((0, document_validation_1.slugifyTitle)("Manual MPP v20")).toBe("manual-mpp-v20");
+    });
+    it("returns a slug that passes validateDocumentSlug for typical titles", () => {
+        const cases = [
+            "Protocolo para Examen General de Orina (EGO)",
+            "Reunión enero 2020",
+            "Política interna de venta de medicamentos",
+            "HVP Web - Módulo documentación",
+        ];
+        for (const title of cases) {
+            const slug = (0, document_validation_1.slugifyTitle)(title);
+            expect((0, document_validation_1.validateDocumentSlug)(slug).isValid).toBe(true);
+        }
+    });
+});
+describe("validateVersionNumber", () => {
+    it("accepts valid semver", () => {
+        expect((0, document_validation_1.validateVersionNumber)("1.0.0")).toEqual({ isValid: true });
+        expect((0, document_validation_1.validateVersionNumber)("12.34.56")).toEqual({ isValid: true });
+    });
+    it("rejects empty", () => {
+        expect((0, document_validation_1.validateVersionNumber)("")).toMatchObject({ isValid: false });
+        expect((0, document_validation_1.validateVersionNumber)(null)).toMatchObject({ isValid: false });
+        expect((0, document_validation_1.validateVersionNumber)(undefined)).toMatchObject({ isValid: false });
+    });
+    it("rejects 2-part versions", () => {
+        expect((0, document_validation_1.validateVersionNumber)("1.0")).toMatchObject({ isValid: false });
+    });
+    it("rejects v-prefix", () => {
+        expect((0, document_validation_1.validateVersionNumber)("v1.0.0")).toMatchObject({ isValid: false });
+    });
+    it("rejects non-numeric segments", () => {
+        expect((0, document_validation_1.validateVersionNumber)("1.0.x")).toMatchObject({ isValid: false });
+    });
+});
+describe("parseVersionNumber", () => {
+    it("parses each segment", () => {
+        expect((0, document_validation_1.parseVersionNumber)("1.2.3")).toEqual({
+            major: 1,
+            minor: 2,
+            patch: 3,
+        });
+    });
+    it("throws on invalid input", () => {
+        expect(() => (0, document_validation_1.parseVersionNumber)("1.0")).toThrow();
+    });
+});

package/dist/validation/index.d.ts

@@ -8,3 +8,4 @@ export * from './nss.validation';
 export * from './email.validation';
 export * from './phone.validation';
 export * from './address.validation';
+export * from './document.validation';

package/dist/validation/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./nss.validation"), exports);
 __exportStar(require("./email.validation"), exports);
 __exportStar(require("./phone.validation"), exports);
 __exportStar(require("./address.validation"), exports);
+__exportStar(require("./document.validation"), exports);

package/package.json

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