hvp-shared 13.2.0 → 13.4.0

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

@@ -0,0 +1,161 @@
+/**
+ * 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 v2.
+ *
+ * Ten dimensions covering everything a recepción needs to capture to make an
+ * appointment actionable: branch, title format, pet identity (name/age/breed),
+ * tutor identity (name/phone), motive, and scheduling provenance (who and when).
+ *
+ * Weights sum to 100. An event is "compliant" when its score >= 80.
+ */
+export declare const STANDARD_V2: AppointmentStandard;
+/**
+ * Backward-compatible alias for existing code/tests that imported `STANDARD_V1`.
+ * Always points to the current standard.
+ *
+ * @deprecated Use `STANDARD_V2` (or whatever the current version is) explicitly.
+ */
+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;
+/**
+ * Captures the "agendado por" col_code AND the date annotation that often follows it.
+ *
+ *   "AGENDO XZA 16 MAYO"            → groups: XZA, "16 MAYO"
+ *   "AG YMP 14.05.26"               → groups: YMP, "14.05.26"
+ *   "AGENDADA POR SLR 02/12/25"     → groups: SLR, "02/12/25"
+ *   "AGENDADO POR SLR"              → groups: SLR, undefined
+ */
+export declare const SCHEDULER_WITH_DATE_REGEX: RegExp;
+/**
+ * Captures pet age expressions in Spanish from descriptions.
+ *
+ *   "YORKIE 4 MESES"             → "4 MESES"
+ *   "11 MESES, COCKER SPANIEL"    → "11 MESES"
+ *   "1 año y 4 meses"            → "1 año y 4 meses"
+ *   "8 semanas"                  → "8 semanas"
+ *   "2 AÑOS"                     → "2 AÑOS"
+ */
+export declare const PET_AGE_REGEX: RegExp;
+/**
+ * Common dog/cat breeds observed in HVP descriptions. Used by the parser to
+ * detect a breed mention. Match is case-insensitive whole-word.
+ *
+ * NOT exhaustive — extend as new breeds appear in real data.
+ */
+export declare const KNOWN_BREEDS: readonly string[];
+/**
+ * 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,428 @@
+"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.KNOWN_BREEDS = exports.PET_AGE_REGEX = exports.SCHEDULER_WITH_DATE_REGEX = 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 = exports.STANDARD_V2 = void 0;
+// ─── Standard v1 ─────────────────────────────────────────────────────────────
+/**
+ * Multi-factor appointment standard v2.
+ *
+ * Ten dimensions covering everything a recepción needs to capture to make an
+ * appointment actionable: branch, title format, pet identity (name/age/breed),
+ * tutor identity (name/phone), motive, and scheduling provenance (who and when).
+ *
+ * Weights sum to 100. An event is "compliant" when its score >= 80.
+ */
+exports.STANDARD_V2 = {
+    version: "2.0",
+    minimumCompliantScore: 80,
+    dimensions: [
+        {
+            id: "branch",
+            weight: 10,
+            label: "Sucursal",
+            description: "El evento tiene un color asignado (Urban=rojo, Harbor=azul, Montejo=morado). Sin color, no se puede asignar carga ni recursos por sucursal.",
+        },
+        {
+            id: "title",
+            weight: 10,
+            label: "Título bien formado",
+            description: "El título empieza con un código de servicio del diccionario (C, V, SC, CS, CX, USG, CERT, etc.).",
+        },
+        {
+            id: "pet_name",
+            weight: 10,
+            label: "Nombre de la mascota",
+            description: "Nombre de la mascota detectable en el título.",
+        },
+        {
+            id: "pet_age",
+            weight: 8,
+            label: "Edad de la mascota",
+            description: 'Edad anotada en la descripción (ej. "4 meses", "1 año", "8 semanas"). Importante para vacunación, dosis y diagnóstico.',
+        },
+        {
+            id: "pet_breed",
+            weight: 8,
+            label: "Raza de la mascota",
+            description: 'Raza detectada en la descripción (ej. "Yorkie", "Shih Tzu", "Cocker Spaniel"). Útil para protocolos clínicos.',
+        },
+        {
+            id: "owner_name",
+            weight: 12,
+            label: "Nombre del tutor",
+            description: "Nombre del cliente/tutor detectable en la descripción, o linkeable a QVET vía Q{id} (auto-pasa).",
+        },
+        {
+            id: "owner_phone",
+            weight: 12,
+            label: "Teléfono del tutor",
+            description: "Teléfono del tutor en la descripción (cualquier formato común). Necesario para confirmar y avisar de cambios.",
+        },
+        {
+            id: "context",
+            weight: 10,
+            label: "Motivo / contexto",
+            description: 'Descripción tiene contexto clínico relevante (motivo, síntomas, antecedentes). >20 caracteres tras descontar nombre/teléfono/Q{id}.',
+        },
+        {
+            id: "scheduler",
+            weight: 10,
+            label: "Iniciales de quien agendó",
+            description: 'Iniciales del colaborador que agendó la cita ("AGENDO XZA", "AG YMP"). Permite reporte de productividad por persona.',
+        },
+        {
+            id: "scheduling_date",
+            weight: 10,
+            label: "Fecha en que se agendó",
+            description: 'Fecha de la anotación de quién agendó (ej. "AGENDO XZA 16 MAYO"). Permite medir lead time entre agendado y atención.',
+        },
+    ],
+};
+/**
+ * Backward-compatible alias for existing code/tests that imported `STANDARD_V1`.
+ * Always points to the current standard.
+ *
+ * @deprecated Use `STANDARD_V2` (or whatever the current version is) explicitly.
+ */
+exports.STANDARD_V1 = exports.STANDARD_V2;
+// ─── 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;
+/**
+ * Captures the "agendado por" col_code AND the date annotation that often follows it.
+ *
+ *   "AGENDO XZA 16 MAYO"            → groups: XZA, "16 MAYO"
+ *   "AG YMP 14.05.26"               → groups: YMP, "14.05.26"
+ *   "AGENDADA POR SLR 02/12/25"     → groups: SLR, "02/12/25"
+ *   "AGENDADO POR SLR"              → groups: SLR, undefined
+ */
+exports.SCHEDULER_WITH_DATE_REGEX = /\b(?:AG|AGENDO|AGENDAD[OA]\s+POR)\s+([A-Z]{2,4})(?:\s+(\d{1,2}[./\-]\d{1,2}(?:[./\-]\d{2,4})?|\d{1,2}\s+(?:ENE|FEB|MAR|ABR|MAY|JUN|JUL|AGO|SEP|OCT|NOV|DIC|ENERO|FEBRERO|MARZO|ABRIL|MAYO|JUNIO|JULIO|AGOSTO|SEPTIEMBRE|OCTUBRE|NOVIEMBRE|DICIEMBRE)))?\b/i;
+// ─── Pet age detection ───────────────────────────────────────────────────────
+/**
+ * Captures pet age expressions in Spanish from descriptions.
+ *
+ *   "YORKIE 4 MESES"             → "4 MESES"
+ *   "11 MESES, COCKER SPANIEL"    → "11 MESES"
+ *   "1 año y 4 meses"            → "1 año y 4 meses"
+ *   "8 semanas"                  → "8 semanas"
+ *   "2 AÑOS"                     → "2 AÑOS"
+ */
+exports.PET_AGE_REGEX = /\b\d+\s*(?:años?|añoss?|meses?|semanas?|días?|años?\s+y\s+\d+\s+meses?)\b/i;
+// ─── Pet breed detection ────────────────────────────────────────────────────
+/**
+ * Common dog/cat breeds observed in HVP descriptions. Used by the parser to
+ * detect a breed mention. Match is case-insensitive whole-word.
+ *
+ * NOT exhaustive — extend as new breeds appear in real data.
+ */
+exports.KNOWN_BREEDS = [
+    // Perros
+    "yorkie",
+    "yorkshire",
+    "shih tzu",
+    "shihtzu",
+    "schnauzer",
+    "schnauzer mini",
+    "cocker spaniel",
+    "cocker",
+    "golden retriever",
+    "golden",
+    "labrador",
+    "labrador retriever",
+    "chihuahua",
+    "bulldog",
+    "bulldog frances",
+    "bulldog francés",
+    "bulldog ingles",
+    "bulldog inglés",
+    "french bulldog",
+    "poodle",
+    "french poodle",
+    "caniche",
+    "bichon",
+    "bichón",
+    "bichon maltes",
+    "maltes",
+    "maltés",
+    "border collie",
+    "border",
+    "pug",
+    "carlino",
+    "pastor aleman",
+    "pastor alemán",
+    "pastor",
+    "husky",
+    "husky siberiano",
+    "boxer",
+    "boxer aleman",
+    "pitbull",
+    "pit bull",
+    "american bully",
+    "doberman",
+    "rottweiler",
+    "dachshund",
+    "salchicha",
+    "beagle",
+    "dalmata",
+    "dalmata",
+    "san bernardo",
+    "akita",
+    "shar pei",
+    "sharpei",
+    "mestizo",
+    "criollo",
+    "xolo",
+    "xoloitzcuintle",
+    "chow chow",
+    // Gatos
+    "persa",
+    "siames",
+    "siamés",
+    "british shorthair",
+    "maine coon",
+    "ragdoll",
+    "bengala",
+    "esfinge",
+    "sphynx",
+    "mestizo",
+    "domestic shorthair",
+    "domestic short hair",
+    "domestico",
+    "doméstico",
+];
+// ─── 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,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const google_calendar_constants_1 = require("./google-calendar.constants");
+describe("STANDARD_V2", () => {
+    it("has weights that sum to 100", () => {
+        const total = google_calendar_constants_1.STANDARD_V2.dimensions.reduce((sum, d) => sum + d.weight, 0);
+        expect(total).toBe(100);
+    });
+    it("declares the ten expected dimensions", () => {
+        const ids = google_calendar_constants_1.STANDARD_V2.dimensions.map((d) => d.id).sort();
+        expect(ids).toEqual([
+            "branch",
+            "context",
+            "owner_name",
+            "owner_phone",
+            "pet_age",
+            "pet_breed",
+            "pet_name",
+            "scheduler",
+            "scheduling_date",
+            "title",
+        ]);
+    });
+    it("every dimension has a label and a description (used by the dashboard tooltip)", () => {
+        for (const dim of google_calendar_constants_1.STANDARD_V2.dimensions) {
+            expect(dim.label.length).toBeGreaterThan(0);
+            expect(dim.description.length).toBeGreaterThan(0);
+        }
+    });
+    it("has a sensible compliance threshold", () => {
+        expect(google_calendar_constants_1.STANDARD_V2.minimumCompliantScore).toBeGreaterThanOrEqual(50);
+        expect(google_calendar_constants_1.STANDARD_V2.minimumCompliantScore).toBeLessThanOrEqual(100);
+    });
+    it("uses semver-like version 2.x", () => {
+        expect(google_calendar_constants_1.STANDARD_V2.version).toMatch(/^2\.\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);
+        }
+    });
+    it("SCHEDULER_WITH_DATE_REGEX captures both col_code and date annotation", () => {
+        const cases = [
+            ["AGENDO XZA 16 MAYO", "XZA", "16 MAYO"],
+            ["AG YMP 14.05.26", "YMP", "14.05.26"],
+            ["AGENDADA POR SLR 02/12/25", "SLR", "02/12/25"],
+            ["AGENDADO POR SCP", "SCP", undefined],
+        ];
+        for (const [text, codeExp, dateExp] of cases) {
+            const match = text.match(google_calendar_constants_1.SCHEDULER_WITH_DATE_REGEX);
+            expect(match?.[1]?.toUpperCase()).toBe(codeExp);
+            if (dateExp) {
+                expect(match?.[2]?.toUpperCase()).toBe(dateExp.toUpperCase());
+            }
+            else {
+                expect(match?.[2]).toBeUndefined();
+            }
+        }
+    });
+});
+describe("PET_AGE_REGEX", () => {
+    it("detects age in months / years / weeks", () => {
+        expect("YORKIE 4 MESES".match(google_calendar_constants_1.PET_AGE_REGEX)?.[0]?.toUpperCase()).toBe("4 MESES");
+        expect("11 MESES, COCKER SPANIEL".match(google_calendar_constants_1.PET_AGE_REGEX)?.[0]?.toUpperCase()).toBe("11 MESES");
+        expect("Shih tzu 1 año y 4 meses".match(google_calendar_constants_1.PET_AGE_REGEX)?.[0]?.toLowerCase()).toContain("1 año");
+        expect("8 semanas".match(google_calendar_constants_1.PET_AGE_REGEX)?.[0]).toBe("8 semanas");
+        expect("2 AÑOS".match(google_calendar_constants_1.PET_AGE_REGEX)?.[0]).toBe("2 AÑOS");
+    });
+    it("does not match arbitrary numbers", () => {
+        expect("Peso: 8.7 Kg".match(google_calendar_constants_1.PET_AGE_REGEX)).toBeNull();
+        expect("Cytopoint 30MG".match(google_calendar_constants_1.PET_AGE_REGEX)).toBeNull();
+    });
+});
+describe("KNOWN_BREEDS", () => {
+    it("includes common breeds observed in the discovery data", () => {
+        const lower = google_calendar_constants_1.KNOWN_BREEDS.map((b) => b.toLowerCase());
+        expect(lower).toContain("yorkie");
+        expect(lower).toContain("shih tzu");
+        expect(lower).toContain("cocker spaniel");
+        expect(lower).toContain("french bulldog");
+        expect(lower).toContain("chihuahua");
+    });
+    it("includes both dog and cat breeds", () => {
+        const lower = google_calendar_constants_1.KNOWN_BREEDS.map((b) => b.toLowerCase());
+        expect(lower.some((b) => b.includes("persa"))).toBe(true);
+        expect(lower.some((b) => b.includes("maine"))).toBe(true);
+    });
+});

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/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,148 @@
+/**
+ * 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' | 'title' | 'pet_name' | 'pet_age' | 'pet_breed' | 'owner_name' | 'owner_phone' | 'context' | 'scheduler' | 'scheduling_date';
+/**
+ * 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;
+        /** One-sentence explanation of what the dimension evaluates (shown as a tooltip in the frontend). */
+        description: 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;
+    /** Pet age detected from description (e.g. "4 meses", "1 año"). Null if not found. */
+    inferredPetAge: string | null;
+    /** Pet breed detected from description (e.g. "YORKIE", "SHIH TZU"). Null if not found. */
+    inferredPetBreed: string | null;
+    /** Tutor (client) full name as detected from description. */
+    inferredOwnerName: 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;
+    /** Date string near the scheduler annotation (e.g. "16 MAYO", "02/12/25"). Null if not found. */
+    inferredSchedulingDate: 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.2.0",
+  "version": "13.4.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",