hvp-shared 13.1.0 → 13.3.0

package/dist/constants/google-calendar.constants.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Google Calendar Integration — Constants
+ *
+ * Implements the appointment standard documented in
+ * `resources/notes/google-calendar/standard-v1.md`.
+ *
+ * Consumed by:
+ * - Backend diagnostic engine (parser + scorer)
+ * - Frontend dashboard (dimension labels, weights)
+ *
+ * Changes to scoring rules require a new version (STANDARD_V2) so previous
+ * runs remain reproducible.
+ */
+import type { AppointmentBranch, AppointmentStandard } from "../contracts/google-calendar/responses";
+/**
+ * Multi-factor appointment standard v1.
+ *
+ * Weights sum to 100. An event is "compliant" when its score >= 80.
+ */
+export declare const STANDARD_V1: AppointmentStandard;
+/**
+ * Google Calendar colorId values mapped to HVP branches.
+ *
+ * Confirmed via Phase 0 discovery (2026-05-18):
+ * - 11 (Tomato) → Urban
+ * - 9  (Blueberry) → Harbor
+ * - 3  (Grape) → Montejo (citas) + recordatorios operacionales
+ */
+export declare const BRANCH_COLOR_IDS: Readonly<Record<AppointmentBranch, string>>;
+/**
+ * Reverse lookup: colorId → branch.
+ */
+export declare const COLOR_ID_TO_BRANCH: Readonly<Record<string, AppointmentBranch>>;
+/** colorId 8 (Graphite) = cancelled. Tracked as a separate metric. */
+export declare const CANCELLED_COLOR_ID = "8";
+/**
+ * colorIds reserved for special events (NOT patient appointments).
+ *
+ * - 2 (Sage) — aniversario HVP, "no agendar nada", recordatorios admin
+ * - 4 (Flamingo) — cumpleaños colaboradores
+ * - 5 (Banana) — bloqueos (vacaciones, cursos, NO AGENDAR)
+ * - 10 (Basil) — reuniones, eventos importantes
+ */
+export declare const EXCLUDED_COLOR_IDS: ReadonlySet<string>;
+/**
+ * Canonical service codes — the diagnostic engine's source of truth.
+ *
+ * The parser maps free-form prefixes (via SERVICE_CODE_SYNONYMS) to one of these.
+ */
+export declare const CANONICAL_SERVICE_CODES: readonly ["CONSULTA", "SIN_CITA", "CONSULTA_SEGUIMIENTO", "VACUNA", "CIRUGIA", "CERTIFICADO", "ULTRASONIDO", "RADIOGRAFIA", "ECOCARDIO", "OVH", "PROFILAXIS_DENTAL", "ANESTESIA", "EUTANASIA", "RETIRO_PUNTOS", "REVISION", "DESPARASITACION", "APLICACION", "TOMA_MUESTRAS", "TERAPIA_MEDICA", "INYECCION"];
+export type CanonicalServiceCode = (typeof CANONICAL_SERVICE_CODES)[number];
+/**
+ * Maps free-form prefixes (uppercase, trimmed, period-stripped) to canonical codes.
+ *
+ * Example: title "C. OFT LUKE RGL*" → first token "C" → CONSULTA.
+ */
+export declare const SERVICE_CODE_SYNONYMS: Readonly<Record<string, CanonicalServiceCode>>;
+/**
+ * Title prefixes (uppercase, first token) that mark NON-clinical events.
+ *
+ * Diagnostic engine excludes these — they are not patient appointments.
+ */
+export declare const EXCLUDED_TITLE_PREFIXES: ReadonlySet<string>;
+/**
+ * Detects an asterisk at the end of the title (after optional whitespace).
+ * `*` at the end = "médico preferido" = the vet earns a commission.
+ *
+ * Examples that match:
+ *   "C. ARCHIE AAT*"
+ *   "C. ARCHIE AAT *"
+ *   "AM CAMILA APL*"
+ */
+export declare const PREFERRED_VET_REGEX: RegExp;
+/**
+ * Detects "ENVIAR RECORDATORIOS *" titles (Montejo recordatorios). Even though
+ * they live in colorId 3 (Montejo), they are NOT patient appointments.
+ */
+export declare const REMINDER_TITLE_REGEX: RegExp;
+/**
+ * Detects cancelled events by title content. Used in addition to colorId 8.
+ */
+export declare const CANCELLED_TITLE_REGEX: RegExp;
+/**
+ * Matches a QVET client id ("Q123456").
+ * Range chosen wide enough to cover historical and future ids.
+ */
+export declare const QVET_ID_REGEX: RegExp;
+/**
+ * Captures Mexican phone numbers in any of the common written formats.
+ * Returns the full match; caller normalizes to last 10 digits.
+ *
+ * Tolerates:
+ *   +52 1 999 442 9488
+ *   +52 999 442 9488
+ *   999 442 9488
+ *   999-442-9488
+ *   9994429488
+ */
+export declare const PHONE_REGEX: RegExp;
+/**
+ * Captures the "agendado por" col_code from a description.
+ *
+ * Variants observed:
+ *   "AGENDO XZA 16 MAYO"
+ *   "AG YMP 14.05.26"
+ *   "AGENDADA POR SLR 02/12/25"
+ *   "AGENDADO POR SLR 02/12/25"
+ */
+export declare const SCHEDULER_REGEX: RegExp;
+/**
+ * Keys used in Google Calendar `extendedProperties.private` for events created
+ * from HVP. Phase 2 writes these; Phase 1 reads them for full attribution.
+ */
+export declare const HVP_EVENT_PROP_KEYS: {
+    readonly qvetClientId: "qvetClientId";
+    readonly qvetPetId: "qvetPetId";
+    readonly serviceCode: "serviceCode";
+    readonly branchId: "branchId";
+    readonly vetColCode: "vetColCode";
+    readonly scheduledByColCode: "scheduledByColCode";
+    readonly isPreferredVet: "isPreferredVet";
+    readonly source: "source";
+    readonly standardVersion: "standardVersion";
+};

package/dist/constants/google-calendar.constants.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Google Calendar Integration — Constants
+ *
+ * Implements the appointment standard documented in
+ * `resources/notes/google-calendar/standard-v1.md`.
+ *
+ * Consumed by:
+ * - Backend diagnostic engine (parser + scorer)
+ * - Frontend dashboard (dimension labels, weights)
+ *
+ * Changes to scoring rules require a new version (STANDARD_V2) so previous
+ * runs remain reproducible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HVP_EVENT_PROP_KEYS = exports.SCHEDULER_REGEX = exports.PHONE_REGEX = exports.QVET_ID_REGEX = exports.CANCELLED_TITLE_REGEX = exports.REMINDER_TITLE_REGEX = exports.PREFERRED_VET_REGEX = exports.EXCLUDED_TITLE_PREFIXES = exports.SERVICE_CODE_SYNONYMS = exports.CANONICAL_SERVICE_CODES = exports.EXCLUDED_COLOR_IDS = exports.CANCELLED_COLOR_ID = exports.COLOR_ID_TO_BRANCH = exports.BRANCH_COLOR_IDS = exports.STANDARD_V1 = void 0;
+// ─── Standard v1 ─────────────────────────────────────────────────────────────
+/**
+ * Multi-factor appointment standard v1.
+ *
+ * Weights sum to 100. An event is "compliant" when its score >= 80.
+ */
+exports.STANDARD_V1 = {
+    version: "1.0",
+    minimumCompliantScore: 80,
+    dimensions: [
+        { id: "branch", weight: 15, label: "Sucursal" },
+        { id: "service", weight: 20, label: "Servicio" },
+        { id: "pet", weight: 15, label: "Paciente" },
+        { id: "client", weight: 25, label: "Cliente (linkable a QVET)" },
+        { id: "context", weight: 10, label: "Motivo / contexto" },
+        { id: "vet", weight: 15, label: "Atribución del vet" },
+    ],
+};
+// ─── ColorId → Branch mapping ────────────────────────────────────────────────
+/**
+ * Google Calendar colorId values mapped to HVP branches.
+ *
+ * Confirmed via Phase 0 discovery (2026-05-18):
+ * - 11 (Tomato) → Urban
+ * - 9  (Blueberry) → Harbor
+ * - 3  (Grape) → Montejo (citas) + recordatorios operacionales
+ */
+exports.BRANCH_COLOR_IDS = {
+    urban: "11",
+    harbor: "9",
+    montejo: "3",
+};
+/**
+ * Reverse lookup: colorId → branch.
+ */
+exports.COLOR_ID_TO_BRANCH = {
+    "11": "urban",
+    "9": "harbor",
+    "3": "montejo",
+};
+// ─── Excluded colorIds ───────────────────────────────────────────────────────
+/** colorId 8 (Graphite) = cancelled. Tracked as a separate metric. */
+exports.CANCELLED_COLOR_ID = "8";
+/**
+ * colorIds reserved for special events (NOT patient appointments).
+ *
+ * - 2 (Sage) — aniversario HVP, "no agendar nada", recordatorios admin
+ * - 4 (Flamingo) — cumpleaños colaboradores
+ * - 5 (Banana) — bloqueos (vacaciones, cursos, NO AGENDAR)
+ * - 10 (Basil) — reuniones, eventos importantes
+ */
+exports.EXCLUDED_COLOR_IDS = new Set([
+    "2",
+    "4",
+    "5",
+    "10",
+]);
+// ─── Service codes ───────────────────────────────────────────────────────────
+/**
+ * Canonical service codes — the diagnostic engine's source of truth.
+ *
+ * The parser maps free-form prefixes (via SERVICE_CODE_SYNONYMS) to one of these.
+ */
+exports.CANONICAL_SERVICE_CODES = [
+    "CONSULTA",
+    "SIN_CITA",
+    "CONSULTA_SEGUIMIENTO",
+    "VACUNA",
+    "CIRUGIA",
+    "CERTIFICADO",
+    "ULTRASONIDO",
+    "RADIOGRAFIA",
+    "ECOCARDIO",
+    "OVH",
+    "PROFILAXIS_DENTAL",
+    "ANESTESIA",
+    "EUTANASIA",
+    "RETIRO_PUNTOS",
+    "REVISION",
+    "DESPARASITACION",
+    "APLICACION",
+    "TOMA_MUESTRAS",
+    "TERAPIA_MEDICA",
+    "INYECCION",
+];
+/**
+ * Maps free-form prefixes (uppercase, trimmed, period-stripped) to canonical codes.
+ *
+ * Example: title "C. OFT LUKE RGL*" → first token "C" → CONSULTA.
+ */
+exports.SERVICE_CODE_SYNONYMS = {
+    // Consulta
+    C: "CONSULTA",
+    CONSULTA: "CONSULTA",
+    // Sin Cita (walk-in)
+    SC: "SIN_CITA",
+    // Consulta Seguimiento
+    CS: "CONSULTA_SEGUIMIENTO",
+    // Vacuna
+    V: "VACUNA",
+    VAC: "VACUNA",
+    VACUNA: "VACUNA",
+    // Cirugía
+    CX: "CIRUGIA",
+    CIRUGIA: "CIRUGIA",
+    CIRUGÍA: "CIRUGIA",
+    // Certificado
+    CERT: "CERTIFICADO",
+    CERTIF: "CERTIFICADO",
+    CERTIFICADO: "CERTIFICADO",
+    // Ultrasonido
+    USG: "ULTRASONIDO",
+    ULTRASONIDO: "ULTRASONIDO",
+    // Radiografía
+    RX: "RADIOGRAFIA",
+    RADIOGRAFIA: "RADIOGRAFIA",
+    RADIOGRAFÍA: "RADIOGRAFIA",
+    // Ecocardio
+    ECO: "ECOCARDIO",
+    ECOCARDIOGRAMA: "ECOCARDIO",
+    // OVH (ovariohisterectomía)
+    OVH: "OVH",
+    // Profilaxis dental
+    PROFILAXIS: "PROFILAXIS_DENTAL",
+    LIMPIEZA: "PROFILAXIS_DENTAL",
+    // Anestesia
+    ANESTESIA: "ANESTESIA",
+    // Eutanasia
+    EUTANASIA: "EUTANASIA",
+    // Retiro de puntos / vendaje
+    RETIRO: "RETIRO_PUNTOS",
+    RET: "RETIRO_PUNTOS",
+    // Revisión
+    REV: "REVISION",
+    REVISION: "REVISION",
+    REVISIÓN: "REVISION",
+    // Desparasitación
+    D: "DESPARASITACION",
+    DES: "DESPARASITACION",
+    DESPARASITACION: "DESPARASITACION",
+    DESPARASITACIÓN: "DESPARASITACION",
+    // Aplicación de medicamento / microchip / etc.
+    AP: "APLICACION",
+    APL: "APLICACION",
+    AM: "APLICACION",
+    APLI: "APLICACION",
+    APLICACION: "APLICACION",
+    APLICACIÓN: "APLICACION",
+    // Toma de muestras
+    TM: "TOMA_MUESTRAS",
+    // Terapia médica (visto como "T.M." → TM)
+    T: "TERAPIA_MEDICA",
+    // Inyección
+    INYECCION: "INYECCION",
+    INYECCIÓN: "INYECCION",
+};
+/**
+ * Title prefixes (uppercase, first token) that mark NON-clinical events.
+ *
+ * Diagnostic engine excludes these — they are not patient appointments.
+ */
+exports.EXCLUDED_TITLE_PREFIXES = new Set([
+    "RECIBIR",
+    "ENTREGAR",
+    "DESPACHAR",
+    "DESP",
+    "ENVIAR",
+    "RECEPCION",
+    "RECEPCIÓN",
+    "RECORDATORIO",
+    "RECORDATORIOS",
+    "ENTREVISTA",
+    "REUNION",
+    "REUNIÓN",
+    "CUMPLE",
+    "CUMPLEAÑOS",
+    "ANIVERSARIO",
+    "VACACIONES",
+    "NO",
+    "IMPORTANTE",
+]);
+// ─── Title patterns ──────────────────────────────────────────────────────────
+/**
+ * Detects an asterisk at the end of the title (after optional whitespace).
+ * `*` at the end = "médico preferido" = the vet earns a commission.
+ *
+ * Examples that match:
+ *   "C. ARCHIE AAT*"
+ *   "C. ARCHIE AAT *"
+ *   "AM CAMILA APL*"
+ */
+exports.PREFERRED_VET_REGEX = /\*\s*$/;
+/**
+ * Detects "ENVIAR RECORDATORIOS *" titles (Montejo recordatorios). Even though
+ * they live in colorId 3 (Montejo), they are NOT patient appointments.
+ */
+exports.REMINDER_TITLE_REGEX = /^ENVIAR\s+RECORDATORIOS\b/i;
+/**
+ * Detects cancelled events by title content. Used in addition to colorId 8.
+ */
+exports.CANCELLED_TITLE_REGEX = /\b(?:CANCEL(?:ADA|ADO))\b|\bse\s+cancela\b/i;
+// ─── Description patterns ────────────────────────────────────────────────────
+/**
+ * Matches a QVET client id ("Q123456").
+ * Range chosen wide enough to cover historical and future ids.
+ */
+exports.QVET_ID_REGEX = /Q\d{4,7}/;
+/**
+ * Captures Mexican phone numbers in any of the common written formats.
+ * Returns the full match; caller normalizes to last 10 digits.
+ *
+ * Tolerates:
+ *   +52 1 999 442 9488
+ *   +52 999 442 9488
+ *   999 442 9488
+ *   999-442-9488
+ *   9994429488
+ */
+exports.PHONE_REGEX = /(?:\+?52\s?1?\s?)?(?:\d{3}[\s-]?\d{3}[\s-]?\d{4}|\d{10})/;
+/**
+ * Captures the "agendado por" col_code from a description.
+ *
+ * Variants observed:
+ *   "AGENDO XZA 16 MAYO"
+ *   "AG YMP 14.05.26"
+ *   "AGENDADA POR SLR 02/12/25"
+ *   "AGENDADO POR SLR 02/12/25"
+ */
+exports.SCHEDULER_REGEX = /\b(?:AG|AGENDO|AGENDAD[OA]\s+POR)\s+([A-Z]{2,4})\b/i;
+// ─── HVP-created extendedProperties keys ─────────────────────────────────────
+/**
+ * Keys used in Google Calendar `extendedProperties.private` for events created
+ * from HVP. Phase 2 writes these; Phase 1 reads them for full attribution.
+ */
+exports.HVP_EVENT_PROP_KEYS = {
+    qvetClientId: "qvetClientId",
+    qvetPetId: "qvetPetId",
+    serviceCode: "serviceCode",
+    branchId: "branchId",
+    vetColCode: "vetColCode",
+    scheduledByColCode: "scheduledByColCode",
+    isPreferredVet: "isPreferredVet",
+    source: "source", // "hvp"
+    standardVersion: "standardVersion",
+};

package/dist/constants/google-calendar.constants.test.d.ts

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

package/dist/constants/google-calendar.constants.test.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const google_calendar_constants_1 = require("./google-calendar.constants");
+describe("STANDARD_V1", () => {
+    it("has weights that sum to 100", () => {
+        const total = google_calendar_constants_1.STANDARD_V1.dimensions.reduce((sum, d) => sum + d.weight, 0);
+        expect(total).toBe(100);
+    });
+    it("declares exactly the six expected dimensions", () => {
+        const ids = google_calendar_constants_1.STANDARD_V1.dimensions.map((d) => d.id).sort();
+        expect(ids).toEqual(["branch", "client", "context", "pet", "service", "vet"]);
+    });
+    it("has a sensible compliance threshold", () => {
+        expect(google_calendar_constants_1.STANDARD_V1.minimumCompliantScore).toBeGreaterThanOrEqual(50);
+        expect(google_calendar_constants_1.STANDARD_V1.minimumCompliantScore).toBeLessThanOrEqual(100);
+    });
+    it("has a non-empty version string", () => {
+        expect(google_calendar_constants_1.STANDARD_V1.version).toMatch(/^\d+\.\d+$/);
+    });
+});
+describe("Branch ↔ colorId mapping", () => {
+    it("is a round-trip", () => {
+        for (const [branch, colorId] of Object.entries(google_calendar_constants_1.BRANCH_COLOR_IDS)) {
+            expect(google_calendar_constants_1.COLOR_ID_TO_BRANCH[colorId]).toBe(branch);
+        }
+    });
+    it("uses the discovery-confirmed colorIds", () => {
+        expect(google_calendar_constants_1.BRANCH_COLOR_IDS.urban).toBe("11");
+        expect(google_calendar_constants_1.BRANCH_COLOR_IDS.harbor).toBe("9");
+        expect(google_calendar_constants_1.BRANCH_COLOR_IDS.montejo).toBe("3");
+    });
+    it("does not collide with excluded or cancelled colorIds", () => {
+        for (const colorId of Object.values(google_calendar_constants_1.BRANCH_COLOR_IDS)) {
+            expect(google_calendar_constants_1.EXCLUDED_COLOR_IDS.has(colorId)).toBe(false);
+            expect(colorId).not.toBe(google_calendar_constants_1.CANCELLED_COLOR_ID);
+        }
+    });
+});
+describe("Service code synonyms", () => {
+    it("only maps to canonical codes", () => {
+        const canonicalSet = new Set(google_calendar_constants_1.CANONICAL_SERVICE_CODES);
+        for (const [synonym, canonical] of Object.entries(google_calendar_constants_1.SERVICE_CODE_SYNONYMS)) {
+            expect(canonicalSet.has(canonical)).toBe(true);
+            // synonyms should be uppercase (we normalize before lookup)
+            expect(synonym).toBe(synonym.toUpperCase());
+        }
+    });
+    it("covers every canonical code with at least one synonym", () => {
+        const reverseIndex = new Map();
+        for (const [syn, canonical] of Object.entries(google_calendar_constants_1.SERVICE_CODE_SYNONYMS)) {
+            const arr = reverseIndex.get(canonical) ?? [];
+            arr.push(syn);
+            reverseIndex.set(canonical, arr);
+        }
+        for (const canonical of google_calendar_constants_1.CANONICAL_SERVICE_CODES) {
+            expect(reverseIndex.get(canonical)?.length ?? 0).toBeGreaterThan(0);
+        }
+    });
+    it("collapses VACUNA variants", () => {
+        expect(google_calendar_constants_1.SERVICE_CODE_SYNONYMS.V).toBe("VACUNA");
+        expect(google_calendar_constants_1.SERVICE_CODE_SYNONYMS.VAC).toBe("VACUNA");
+        expect(google_calendar_constants_1.SERVICE_CODE_SYNONYMS.VACUNA).toBe("VACUNA");
+    });
+    it("collapses APLICACION variants (AP/APL/AM)", () => {
+        expect(google_calendar_constants_1.SERVICE_CODE_SYNONYMS.AP).toBe("APLICACION");
+        expect(google_calendar_constants_1.SERVICE_CODE_SYNONYMS.APL).toBe("APLICACION");
+        expect(google_calendar_constants_1.SERVICE_CODE_SYNONYMS.AM).toBe("APLICACION");
+    });
+});
+describe("Title regexes", () => {
+    it("detects the preferred-vet asterisk at the end of titles", () => {
+        expect(google_calendar_constants_1.PREFERRED_VET_REGEX.test("C. ARCHIE AAT*")).toBe(true);
+        expect(google_calendar_constants_1.PREFERRED_VET_REGEX.test("AM CAMILA APL* ")).toBe(true);
+        expect(google_calendar_constants_1.PREFERRED_VET_REGEX.test("CX. DANNA MAT*")).toBe(true);
+    });
+    it("does not flag asterisk in the middle of a title", () => {
+        expect(google_calendar_constants_1.PREFERRED_VET_REGEX.test("C. MILO *fpo IS A BUG")).toBe(false);
+    });
+    it("identifies Montejo reminder events", () => {
+        expect(google_calendar_constants_1.REMINDER_TITLE_REGEX.test("ENVIAR RECORDATORIOS MONT")).toBe(true);
+        expect(google_calendar_constants_1.REMINDER_TITLE_REGEX.test("enviar recordatorios mont")).toBe(true);
+        expect(google_calendar_constants_1.REMINDER_TITLE_REGEX.test("D. MILO")).toBe(false);
+    });
+    it("flags operational prefixes as excluded", () => {
+        expect(google_calendar_constants_1.EXCLUDED_TITLE_PREFIXES.has("RECIBIR")).toBe(true);
+        expect(google_calendar_constants_1.EXCLUDED_TITLE_PREFIXES.has("ENTREGAR")).toBe(true);
+        expect(google_calendar_constants_1.EXCLUDED_TITLE_PREFIXES.has("ENTREVISTA")).toBe(true);
+        expect(google_calendar_constants_1.EXCLUDED_TITLE_PREFIXES.has("C")).toBe(false);
+    });
+});
+describe("Description regexes", () => {
+    it("captures Q{id} client ids", () => {
+        expect("DIANA LAURA | KIRI | Q913562".match(google_calendar_constants_1.QVET_ID_REGEX)?.[0]).toBe("Q913562");
+        expect("Q966648".match(google_calendar_constants_1.QVET_ID_REGEX)?.[0]).toBe("Q966648");
+        expect("no qvet here".match(google_calendar_constants_1.QVET_ID_REGEX)).toBeNull();
+    });
+    it("captures phones in common Mexican formats", () => {
+        expect("+52 1 999 442 9488".match(google_calendar_constants_1.PHONE_REGEX)?.[0]).toBe("+52 1 999 442 9488");
+        expect("999 442 9488".match(google_calendar_constants_1.PHONE_REGEX)?.[0]).toBe("999 442 9488");
+        expect("9994429488".match(google_calendar_constants_1.PHONE_REGEX)?.[0]).toBe("9994429488");
+        expect("999-442-9488".match(google_calendar_constants_1.PHONE_REGEX)?.[0]).toBe("999-442-9488");
+    });
+    it("captures scheduler col_code from descriptions", () => {
+        const cases = [
+            ["AGENDO XZA 16 MAYO", "XZA"],
+            ["AG YMP 14.05.26", "YMP"],
+            ["AGENDADA POR SLR 02/12/25", "SLR"],
+            ["AGENDADO POR SCP", "SCP"],
+        ];
+        for (const [text, expected] of cases) {
+            const match = text.match(google_calendar_constants_1.SCHEDULER_REGEX);
+            expect(match?.[1]?.toUpperCase()).toBe(expected);
+        }
+    });
+});

package/dist/constants/index.d.ts

@@ -28,3 +28,4 @@ export * from './settlement.enums';
 export * from './client-billing.enums';
 export * from './sat-income-invoice';
 export * from './global-invoice.enums';
+export * from './google-calendar.constants';

package/dist/constants/index.js

@@ -44,3 +44,4 @@ __exportStar(require("./settlement.enums"), exports);
 __exportStar(require("./client-billing.enums"), exports);
 __exportStar(require("./sat-income-invoice"), exports);
 __exportStar(require("./global-invoice.enums"), exports);
+__exportStar(require("./google-calendar.constants"), exports);

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/dist/contracts/google-calendar/index.d.ts

@@ -0,0 +1,2 @@
+export * from './requests';
+export * from './responses';

package/dist/contracts/google-calendar/index.js

@@ -0,0 +1,18 @@
+"use strict";
+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/google-calendar/requests.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Google Calendar Integration - Request Types
+ *
+ * Request contracts for the Google Calendar diagnostic + appointment management feature.
+ * See: resources/notes/google-calendar/standard-v1.md
+ */
+/**
+ * Diagnose request — score appointments against the standard for a date window.
+ *
+ * @example GET /api/google-calendar/diagnose?from=2026-04-01&to=2026-05-01
+ */
+export interface DiagnoseAppointmentsRequest {
+    /** ISO date (inclusive). Start of the window in Mexico_City timezone. */
+    from: string;
+    /** ISO date (inclusive). End of the window in Mexico_City timezone. */
+    to: string;
+    /** Filter results to a single branch. Optional. */
+    branchId?: 'urban' | 'harbor' | 'montejo';
+    /** Filter to events where this col_code is detected as the attending vet. Optional. */
+    vetColCode?: string;
+}
+/**
+ * Single-event diagnose request.
+ *
+ * @example GET /api/google-calendar/diagnose/event/:eventId
+ */
+export interface DiagnoseEventRequest {
+    eventId: string;
+}

package/dist/contracts/google-calendar/requests.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Google Calendar Integration - Request Types
+ *
+ * Request contracts for the Google Calendar diagnostic + appointment management feature.
+ * See: resources/notes/google-calendar/standard-v1.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/google-calendar/responses.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Google Calendar Integration - Response Types
+ *
+ * Response contracts for the Google Calendar diagnostic feature.
+ * See: resources/notes/google-calendar/standard-v1.md
+ */
+/**
+ * One of the six dimensions of the appointment standard.
+ */
+export type AppointmentStandardDimensionId = 'branch' | 'service' | 'pet' | 'client' | 'context' | 'vet';
+/**
+ * One of the three branches.
+ */
+export type AppointmentBranch = 'urban' | 'harbor' | 'montejo';
+/**
+ * Definition of the multi-factor scoring standard used by the diagnostic engine.
+ *
+ * Defined in code as a constant (see constants/google-calendar.constants.ts).
+ * Sent to the frontend so the dashboard can render dimension names/weights without
+ * hardcoding.
+ */
+export interface AppointmentStandard {
+    /** Semver-like version identifier (e.g. "1.0"). */
+    version: string;
+    /** Dimensions and their weights (must sum to 100). */
+    dimensions: ReadonlyArray<{
+        id: AppointmentStandardDimensionId;
+        weight: number;
+        /** Display label in Spanish. */
+        label: string;
+    }>;
+    /** Threshold above which an event is considered "compliant". */
+    minimumCompliantScore: number;
+}
+/**
+ * A single dimension result for one event.
+ */
+export interface DiagnosticDimensionResult {
+    id: AppointmentStandardDimensionId;
+    passed: boolean;
+    weight: number;
+    /** Human-readable evidence ("Q966648 in description", "phone 999... matched", etc.) or null when missing. */
+    evidence: string | null;
+}
+/**
+ * Reason an event was excluded from scoring.
+ */
+export type DiagnosticExclusionReason = 'cancelled' | 'blocker' | 'special' | 'operational' | 'interview' | 'reminder';
+/**
+ * Full diagnostic result for one event.
+ */
+export interface DiagnosticResult {
+    eventId: string;
+    /** ISO datetime in Mexico_City. */
+    eventStart: string;
+    /** Duration in minutes. */
+    durationMinutes: number;
+    /** Title as it appears in GCal. */
+    title: string;
+    /** htmlLink to the event in Google Calendar. */
+    htmlLink: string | null;
+    /** Score 0-100. */
+    score: number;
+    /** Score >= minimumCompliantScore. */
+    isCompliant: boolean;
+    /** Per-dimension results. */
+    dimensions: DiagnosticDimensionResult[];
+    /** Inferred branch from colorId or extendedProperties. Null if undetected. */
+    inferredBranch: AppointmentBranch | null;
+    /** Inferred canonical service code (e.g. "CONSULTA"). Null if undetected. */
+    inferredService: string | null;
+    /** Inferred pet name from the title. */
+    inferredPetName: string | null;
+    /** col_code of the attending vet, when detectable. */
+    inferredVetColCode: string | null;
+    /** col_code of the person who scheduled, when detectable in description. */
+    inferredSchedulerColCode: string | null;
+    /** Q{id} or null. */
+    inferredQvetClientId: string | null;
+    /** Last 10 digits of phone, normalized. Null if not found. */
+    inferredPhone: string | null;
+    /** Asterisk at end of title => preferred vet => generates commission. */
+    isPreferredVet: boolean;
+    /** True iff event has extendedProperties.private (HVP-created). */
+    isHvpCreated: boolean;
+}
+/**
+ * Excluded event — does not have a score.
+ */
+export interface DiagnosticExcludedEvent {
+    eventId: string;
+    eventStart: string;
+    title: string;
+    reason: DiagnosticExclusionReason;
+}
+/**
+ * Aggregated summary of diagnostic results for a window.
+ *
+ * @example GET /api/google-calendar/diagnose
+ */
+export interface DiagnoseAppointmentsResponse {
+    /** Window inputs echoed back. */
+    window: {
+        from: string;
+        to: string;
+    };
+    /** Standard used for scoring (so frontend can render labels/weights). */
+    standard: AppointmentStandard;
+    /** Counts. */
+    totalFetched: number;
+    totalEvaluated: number;
+    totalExcluded: number;
+    totalCancelled: number;
+    /** totalEvaluated where score >= minimumCompliantScore. */
+    compliantCount: number;
+    /** Average score across evaluated events (0-100). */
+    averageScore: number;
+    /** Per-dimension breakdown: how many evaluated events passed each dimension. */
+    byDimension: Record<AppointmentStandardDimensionId, {
+        passed: number;
+        total: number;
+    }>;
+    /** Per-branch breakdown. */
+    byBranch: Record<AppointmentBranch | 'unknown', {
+        count: number;
+        avgScore: number;
+    }>;
+    /** Per-vet breakdown (top 20 by count). col_code => { totalCount, preferredCount }. */
+    byVet: Record<string, {
+        count: number;
+        preferredCount: number;
+        avgScore: number;
+    }>;
+    /** Detailed results per evaluated event (paginated by caller — capped at 500 in response for now). */
+    results: DiagnosticResult[];
+    /** Detailed excluded events (capped at 100). */
+    excluded: DiagnosticExcludedEvent[];
+}

package/dist/contracts/google-calendar/responses.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Google Calendar Integration - Response Types
+ *
+ * Response contracts for the Google Calendar diagnostic feature.
+ * See: resources/notes/google-calendar/standard-v1.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/index.d.ts

@@ -16,6 +16,7 @@ export * from './client-billing';
 export * from './global-invoice';
 export * from './inventory-report';
 export * from './google-contacts';
+export * from './google-calendar';
 export * from './study-type-catalog';
 export * from './supplier-overlay';
 export * from './external-study';

package/dist/contracts/index.js

@@ -32,6 +32,7 @@ __exportStar(require("./client-billing"), exports);
 __exportStar(require("./global-invoice"), exports);
 __exportStar(require("./inventory-report"), exports);
 __exportStar(require("./google-contacts"), exports);
+__exportStar(require("./google-calendar"), exports);
 __exportStar(require("./study-type-catalog"), exports);
 __exportStar(require("./supplier-overlay"), exports);
 __exportStar(require("./external-study"), exports);

package/package.json

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