@patroltech/agent-capabilities 0.0.0-stage → 0.2.0

package/dist/domain/route-checkpoints.js

@@ -0,0 +1,27 @@
+/**
+ * Qué le pasa a una ruta al quitarle checkpoints. Regla del backend: una ruta
+ * que se queda sin checkpoints se desactiva (deja de generar rondas) y no se
+ * puede volver a activar hasta que tenga alguno. Añadir uno no la reactiva.
+ */
+/** El efecto de quitar `quitados` de la ruta (un checkpoint repetido en ella cuenta como uno). */
+export function efectoDeQuitar(ruta, quitados) {
+    const vacia = ruta.checkpoints.every((c) => quitados.has(c.checkpointId));
+    return { vacia, seDesactiva: vacia && ruta.isActive };
+}
+/**
+ * La ruta tal como la dejan los cambios previos del lote, aplicados en el orden
+ * en que se ejecutarán: con lo añadido, sin lo quitado y desactivada si en algún
+ * momento se quedó vacía.
+ */
+export function aplicarCambios(ruta, cambios) {
+    return cambios.reduce((r, c) => {
+        if (c.op === 'añadir')
+            return { ...r, checkpoints: [...r.checkpoints, { checkpointId: c.checkpointId }] };
+        const { vacia } = efectoDeQuitar(r, new Set([c.checkpointId]));
+        return {
+            isActive: r.isActive && !vacia,
+            checkpoints: r.checkpoints.filter((x) => x.checkpointId !== c.checkpointId),
+        };
+    }, ruta);
+}
+//# sourceMappingURL=route-checkpoints.js.map

package/dist/domain/route-checkpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-checkpoints.js","sourceRoot":"","sources":["../../src/domain/route-checkpoints.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,kGAAkG;AAClG,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,QAA6B;IAE7B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IAC1E,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;AACxD,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,OAAsC;IAEtC,OAAO,OAAO,CAAC,MAAM,CAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,EAAE,KAAK,QAAQ;YACnB,OAAO,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC;QACrF,MAAM,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC/D,OAAO;YACL,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,CAAC,KAAK;YAC9B,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY,CAAC;SAC5E,CAAC;IACJ,CAAC,EAAE,IAAI,CAAC,CAAC;AACX,CAAC"}

package/dist/domain/route-schedule.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Horarios (franjas) de una ruta. El backend SOLO guarda y compara horas UTC
+ * (`HH:MM` + días ISO 1=lun..7=dom); convertir desde la hora local del cliente es
+ * cosa de quien envía (`AddTimeWindowBody` en el contrato de la API).
+ *
+ * Mismo criterio que el panel:
+ * se desplazan las dos horas con el desfase de la zona y los días se mueven según
+ * lo que le pase a la hora de INICIO (la franja «pertenece» al día en que empieza).
+ * Solapes con la regla del backend: semana
+ * circular de minutos, intervalos semiabiertos, una franja que acaba antes de
+ * empezar cruza la medianoche.
+ */
+import type { FixedTextLanguage } from './language.js';
+export declare const DIAS: readonly ["lun", "mar", "mie", "jue", "vie", "sab", "dom"];
+export type Dia = (typeof DIAS)[number];
+/** Tope del panel por ruta (PT dashboard: recurrence.ts `MAX_WINDOWS_PER_ROUTE`): una semana de franjas de una hora. */
+export declare const MAX_HORARIOS_POR_RUTA = 168;
+/** Intervalo mínimo al repetir una franja (el mismo que el generador del panel). */
+export declare const MIN_REPETICION_MIN = 5;
+/** Un horario tal como lo entiende el backend (o su equivalente local): horas `HH:MM` y días ISO. */
+export interface Horario {
+    startTime: string;
+    endTime: string;
+    days: number[];
+}
+/** Lo que dice el cliente: días en los que EMPIEZA, desde/hasta en SU hora y, opcional, «una ronda cada N minutos». */
+export interface Franja {
+    dias: readonly Dia[];
+    desde: string;
+    hasta: string;
+    repetir_cada_min?: number;
+}
+/** `HH:MM:SS` (como lo devuelve el backend) → `HH:MM`. */
+export declare const normalizeTime: (t: string) => string;
+/**
+ * Los horarios LOCALES de una franja. Sin repetición es uno solo; con
+ * `repetir_cada_min` se trocea en horarios consecutivos de esa duración (el
+ * último, recortado a `hasta`), y los que empiezan pasada la medianoche caen en
+ * el día siguiente: «lun a vie de 20:00 a 05:00 cada hora» da 20-21 … 23-00 de
+ * lun a vie y 00-01 … 04-05 de mar a sáb.
+ */
+export declare function expandirFranja(f: Franja): Horario[] | {
+    error: string;
+};
+/** Hora local → UTC. `offsetMin` es el desfase de la zona (Madrid en verano: +120; Bogotá: -300). */
+export declare const horarioAUtc: (h: Horario, offsetMin: number) => Horario;
+/** UTC → hora local (para enseñárselo al cliente). */
+export declare const horarioALocal: (h: Horario, offsetMin: number) => Horario;
+/** La primera pareja de horarios que comparten algún minuto de la semana, o null. */
+export declare function buscarSolape(horarios: readonly Horario[]): [number, number] | null;
+/** «lun, mar, mié 20:00-21:00» (o en inglés). */
+export declare function describirHorario(h: Horario, idioma?: FixedTextLanguage): string;
+/** Días de una franja tal como los dijo el cliente, en su idioma. */
+export declare const describirDias: (dias: readonly Dia[], idioma?: FixedTextLanguage) => string;
+/**
+ * Los horarios en UTC listos para el backend a partir de las franjas locales:
+ * expande repeticiones, convierte y comprueba solapes (con los que ya tiene la
+ * ruta, si se pasan) y el tope de 168. Los errores van en palabras para el modelo.
+ */
+export declare function horariosParaBackend(franjas: readonly Franja[], offsetMin: number, existentesUtc?: readonly Horario[]): Horario[] | {
+    error: string;
+};
+/** Un horario de la ruta visto por el cliente: su id, en hora local y en texto. */
+export interface HorarioLocal {
+    id: string;
+    local: Horario;
+    texto: string;
+}
+/**
+ * Los horarios de la ruta (UTC, del backend) en hora local, ordenados por
+ * primer día y hora: es la numeración que ve el cliente («1. lun 20:00-21:00»)
+ * y con la que luego dice cuál borrar.
+ */
+export declare function listarHorarios(ventanas: readonly (Horario & {
+    id: string;
+})[], offsetMin: number): HorarioLocal[];
+/**
+ * Cuál de los horarios dice el cliente: su número en la lista o una descripción
+ * («lun 20:00-21:00», «el de las 20:00 a 21:00 del martes»). Casa por horas y,
+ * si nombra días, se queda con los que los incluyen. Ninguno o varios → error
+ * con la lista numerada para que pregunte.
+ */
+export declare function elegirHorario(horarios: readonly HorarioLocal[], entrada: string): {
+    item: HorarioLocal;
+} | {
+    error: string;
+};
+//# sourceMappingURL=route-schedule.d.ts.map

package/dist/domain/route-schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-schedule.d.ts","sourceRoot":"","sources":["../../src/domain/route-schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,eAAO,MAAM,IAAI,4DAA6D,CAAC;AAC/E,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;AAOxC,wHAAwH;AACxH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAKpC,qGAAqG;AACrG,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,uHAAuH;AACvH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,SAAS,GAAG,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAcD,0DAA0D;AAC1D,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,KAAG,MAAuB,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAyBvE;AAaD,qGAAqG;AACrG,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,EAAE,WAAW,MAAM,KAAG,OAAmC,CAAC;AAChG,sDAAsD;AACtD,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,EAAE,WAAW,MAAM,KAAG,OAAkC,CAAC;AAmBjG,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQlF;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAE,iBAAwB,GAAG,MAAM,CAErF;AAED,qEAAqE;AACrE,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,GAAG,EAAE,EAAE,SAAQ,iBAAwB,KAAG,MAGxE,CAAC;AAEhB;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,SAAS,OAAO,EAAO,GACrC,OAAO,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA2B/B;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,EAC/C,SAAS,EAAE,MAAM,GAChB,YAAY,EAAE,CAWhB;AAcD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA0B5C"}

package/dist/domain/route-schedule.js

@@ -0,0 +1,203 @@
+/**
+ * Horarios (franjas) de una ruta. El backend SOLO guarda y compara horas UTC
+ * (`HH:MM` + días ISO 1=lun..7=dom); convertir desde la hora local del cliente es
+ * cosa de quien envía (`AddTimeWindowBody` en el contrato de la API).
+ *
+ * Mismo criterio que el panel:
+ * se desplazan las dos horas con el desfase de la zona y los días se mueven según
+ * lo que le pase a la hora de INICIO (la franja «pertenece» al día en que empieza).
+ * Solapes con la regla del backend: semana
+ * circular de minutos, intervalos semiabiertos, una franja que acaba antes de
+ * empezar cruza la medianoche.
+ */
+export const DIAS = ['lun', 'mar', 'mie', 'jue', 'vie', 'sab', 'dom'];
+const DIAS_TEXTO = {
+    es: ['lun', 'mar', 'mié', 'jue', 'vie', 'sáb', 'dom'],
+    en: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    fr: ['lun', 'mar', 'mer', 'jeu', 'ven', 'sam', 'dim'],
+};
+/** Tope del panel por ruta (PT dashboard: recurrence.ts `MAX_WINDOWS_PER_ROUTE`): una semana de franjas de una hora. */
+export const MAX_HORARIOS_POR_RUTA = 168;
+/** Intervalo mínimo al repetir una franja (el mismo que el generador del panel). */
+export const MIN_REPETICION_MIN = 5;
+const DAY = 1440;
+const WEEK = 7 * DAY;
+const toMin = (hhmm) => {
+    const [h, m] = hhmm.split(':').map(Number);
+    return h * 60 + m;
+};
+const toHHMM = (min) => {
+    const m = ((min % DAY) + DAY) % DAY;
+    return `${String(Math.floor(m / 60)).padStart(2, '0')}:${String(m % 60).padStart(2, '0')}`;
+};
+/** 1..7 desplazado `n` días, dando la vuelta a la semana (dom+1 = lun). */
+const shiftDay = (d, n) => ((((d - 1 + n) % 7) + 7) % 7) + 1;
+const sortDays = (days) => [...new Set(days)].sort((a, b) => a - b);
+/** `HH:MM:SS` (como lo devuelve el backend) → `HH:MM`. */
+export const normalizeTime = (t) => t.slice(0, 5);
+/**
+ * Los horarios LOCALES de una franja. Sin repetición es uno solo; con
+ * `repetir_cada_min` se trocea en horarios consecutivos de esa duración (el
+ * último, recortado a `hasta`), y los que empiezan pasada la medianoche caen en
+ * el día siguiente: «lun a vie de 20:00 a 05:00 cada hora» da 20-21 … 23-00 de
+ * lun a vie y 00-01 … 04-05 de mar a sáb.
+ */
+export function expandirFranja(f) {
+    const desde = toMin(f.desde);
+    const hasta = toMin(f.hasta);
+    if (desde === hasta)
+        return {
+            error: `La franja ${f.desde}-${f.hasta} empieza y acaba a la misma hora: pregunta al usuario la hora de fin.`,
+        };
+    const days = sortDays(f.dias.map((d) => DIAS.indexOf(d) + 1));
+    if (!f.repetir_cada_min)
+        return [{ startTime: f.desde, endTime: f.hasta, days }];
+    if (f.repetir_cada_min < MIN_REPETICION_MIN)
+        return { error: `No se puede repetir cada menos de ${MIN_REPETICION_MIN} minutos.` };
+    const total = hasta > desde ? hasta - desde : hasta + DAY - desde;
+    const horarios = [];
+    for (let offset = 0; offset < total; offset += f.repetir_cada_min) {
+        const start = desde + offset;
+        const end = desde + Math.min(offset + f.repetir_cada_min, total);
+        const shift = Math.floor(start / DAY);
+        horarios.push({
+            startTime: toHHMM(start),
+            endTime: toHHMM(end),
+            days: sortDays(days.map((d) => shiftDay(d, shift))),
+        });
+    }
+    return horarios;
+}
+/** Desplaza un horario `delta` minutos; los días se mueven con la hora de inicio. */
+function desplazar(h, delta) {
+    const start = toMin(h.startTime) + delta;
+    const shift = start < 0 ? -1 : start >= DAY ? 1 : 0;
+    return {
+        startTime: toHHMM(start),
+        endTime: toHHMM(toMin(h.endTime) + delta),
+        days: sortDays(h.days.map((d) => shiftDay(d, shift))),
+    };
+}
+/** Hora local → UTC. `offsetMin` es el desfase de la zona (Madrid en verano: +120; Bogotá: -300). */
+export const horarioAUtc = (h, offsetMin) => desplazar(h, -offsetMin);
+/** UTC → hora local (para enseñárselo al cliente). */
+export const horarioALocal = (h, offsetMin) => desplazar(h, offsetMin);
+/** Intervalos semiabiertos del horario en la semana circular (el que cruza el domingo se parte en dos). */
+function intervalos(h) {
+    const start = toMin(h.startTime);
+    const end = toMin(h.endTime);
+    // Que acabe antes de empezar = cruza la medianoche; igual = un minuto (lo que hace el backend).
+    const dur = end > start ? end - start : end < start ? end + DAY - start : 1;
+    return h.days.flatMap((d) => {
+        const a = (d - 1) * DAY + start;
+        return a + dur <= WEEK
+            ? [[a, a + dur]]
+            : [
+                [a, WEEK],
+                [0, a + dur - WEEK],
+            ];
+    });
+}
+/** La primera pareja de horarios que comparten algún minuto de la semana, o null. */
+export function buscarSolape(horarios) {
+    const iv = horarios.map(intervalos);
+    for (let i = 0; i < iv.length; i++) {
+        for (let j = i + 1; j < iv.length; j++) {
+            if (iv[i].some(([a1, b1]) => iv[j].some(([a2, b2]) => a1 < b2 && a2 < b1)))
+                return [i, j];
+        }
+    }
+    return null;
+}
+/** «lun, mar, mié 20:00-21:00» (o en inglés). */
+export function describirHorario(h, idioma = 'es') {
+    return `${h.days.map((d) => DIAS_TEXTO[idioma][d - 1]).join(', ')} ${h.startTime}-${h.endTime}`;
+}
+/** Días de una franja tal como los dijo el cliente, en su idioma. */
+export const describirDias = (dias, idioma = 'es') => sortDays(dias.map((d) => DIAS.indexOf(d) + 1))
+    .map((d) => DIAS_TEXTO[idioma][d - 1])
+    .join(', ');
+/**
+ * Los horarios en UTC listos para el backend a partir de las franjas locales:
+ * expande repeticiones, convierte y comprueba solapes (con los que ya tiene la
+ * ruta, si se pasan) y el tope de 168. Los errores van en palabras para el modelo.
+ */
+export function horariosParaBackend(franjas, offsetMin, existentesUtc = []) {
+    const locales = [];
+    for (const f of franjas) {
+        const r = expandirFranja(f);
+        if ('error' in r)
+            return r;
+        locales.push(...r);
+    }
+    const total = existentesUtc.length + locales.length;
+    if (total > MAX_HORARIOS_POR_RUTA) {
+        return {
+            error: `Serían ${total} horarios y una ruta admite como máximo ${MAX_HORARIOS_POR_RUTA}: propón franjas más largas o menos repeticiones.`,
+        };
+    }
+    const utc = locales.map((h) => horarioAUtc(h, offsetMin));
+    const todos = [...existentesUtc, ...utc];
+    const solape = buscarSolape(todos);
+    if (solape) {
+        const txt = (i) => describirHorario(horarioALocal(todos[i], offsetMin));
+        const cual = (i) => i < existentesUtc.length ? 'el horario que ya tiene la ruta' : 'el horario';
+        return {
+            error: `${cual(solape[0])} «${txt(solape[0])}» se solapa con ${cual(solape[1])} «${txt(solape[1])}» (hora del cliente). ` +
+                'Dos horarios de una ruta no pueden compartir ningún minuto: pregunta al usuario cómo quiere ajustarlos.',
+        };
+    }
+    return utc;
+}
+/**
+ * Los horarios de la ruta (UTC, del backend) en hora local, ordenados por
+ * primer día y hora: es la numeración que ve el cliente («1. lun 20:00-21:00»)
+ * y con la que luego dice cuál borrar.
+ */
+export function listarHorarios(ventanas, offsetMin) {
+    return ventanas
+        .map((v) => {
+        const local = horarioALocal(v, offsetMin);
+        return { id: v.id, local, texto: describirHorario(local) };
+    })
+        .sort((a, b) => (a.local.days[0] ?? 0) - (b.local.days[0] ?? 0) ||
+        a.local.startTime.localeCompare(b.local.startTime));
+}
+const DIA_EN_TEXTO = {
+    lun: 1,
+    mar: 2,
+    mie: 3,
+    mié: 3,
+    jue: 4,
+    vie: 5,
+    sab: 6,
+    sáb: 6,
+    dom: 7,
+};
+/**
+ * Cuál de los horarios dice el cliente: su número en la lista o una descripción
+ * («lun 20:00-21:00», «el de las 20:00 a 21:00 del martes»). Casa por horas y,
+ * si nombra días, se queda con los que los incluyen. Ninguno o varios → error
+ * con la lista numerada para que pregunte.
+ */
+export function elegirHorario(horarios, entrada) {
+    const numerada = horarios.map((h, i) => `${i + 1}. ${h.texto}`).join('; ');
+    const pregunta = {
+        error: `No sé cuál de los horarios es «${entrada}». Pregunta al usuario cuál (hora local): ${numerada}.`,
+    };
+    const texto = entrada.trim().toLowerCase();
+    if (/^\d+$/.test(texto)) {
+        const indice = Number(texto) - 1;
+        const h = indice >= 0 ? horarios[indice] : undefined;
+        return h ? { item: h } : pregunta;
+    }
+    const horas = [...texto.matchAll(/(\d{1,2})[:.h](\d{2})/g)].map(([, h, m]) => `${h.padStart(2, '0')}:${m}`);
+    const dias = [...texto.matchAll(/\b(lun|mar|mi[eé]|jue|vie|s[aá]b|dom)/g)].map(([d]) => DIA_EN_TEXTO[d]);
+    const candidatos = horarios.filter((h) => (horas.length === 0 || h.local.startTime === horas[0]) &&
+        (horas.length < 2 || h.local.endTime === horas[1]) &&
+        dias.every((d) => h.local.days.includes(d)));
+    return candidatos.length === 1 && (horas.length > 0 || dias.length > 0)
+        ? { item: candidatos[0] }
+        : pregunta;
+}
+//# sourceMappingURL=route-schedule.js.map

package/dist/domain/route-schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-schedule.js","sourceRoot":"","sources":["../../src/domain/route-schedule.ts"],"names":[],"mappings":"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"}

package/dist/domain/scan-explanation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Traduce el estado de validación y las señales antifraude de un escaneo a
+ * lenguaje de cliente. Sin esto el modelo solo veía `verified` + `flagged` y
+ * decía «sospechoso pero ya verificado» inventándose el motivo. Validación y sospecha son independientes: un escaneo puede
+ * ser válido y a la vez sospechoso.
+ *
+ * Fuente: la validación de escaneos y los tipos de fraude del backend.
+ */
+/** De vuelta del texto de `validacion` a su estado, para contar (empieza siempre por la palabra del estado). */
+export declare function validationBucket(validacion: string): 'valido' | 'pendiente' | 'rechazado' | null;
+export interface ScanValidationInput {
+    validationStatus: string | null;
+    validationReason: string | null;
+    fraudFlags: {
+        flagged?: boolean;
+        [regla: string]: unknown;
+    } | null;
+}
+export interface ScanExplanation {
+    validacion: string;
+    /** Vacío si el escaneo no está marcado como sospechoso. */
+    motivosSospecha: string[];
+}
+export declare function explainScan(scan: ScanValidationInput): ScanExplanation;
+//# sourceMappingURL=scan-explanation.d.ts.map

package/dist/domain/scan-explanation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-explanation.d.ts","sourceRoot":"","sources":["../../src/domain/scan-explanation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,gHAAgH;AAChH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,IAAI,CAKhG;AA+CD,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACpE;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAyBD,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAuBtE"}

package/dist/domain/scan-explanation.js

@@ -0,0 +1,99 @@
+/**
+ * Traduce el estado de validación y las señales antifraude de un escaneo a
+ * lenguaje de cliente. Sin esto el modelo solo veía `verified` + `flagged` y
+ * decía «sospechoso pero ya verificado» inventándose el motivo. Validación y sospecha son independientes: un escaneo puede
+ * ser válido y a la vez sospechoso.
+ *
+ * Fuente: la validación de escaneos y los tipos de fraude del backend.
+ */
+// Sin prometer si cuenta o no en la ronda: con Guardia Estricto un válido fuera
+// de orden no cuenta, y un rechazado con checkpoint identificado sí la avanza.
+const ESTADOS = {
+    verified: 'válido: es un escaneo auténtico de un punto real',
+    pending_review: 'pendiente de revisión: faltaban datos para verificarlo; no se descarta, y hoy no se puede aprobar ni rechazar a mano',
+    rejected: 'rechazado: la verificación falló',
+};
+/** De vuelta del texto de `validacion` a su estado, para contar (empieza siempre por la palabra del estado). */
+export function validationBucket(validacion) {
+    if (validacion.startsWith('válido'))
+        return 'valido';
+    if (validacion.startsWith('pendiente'))
+        return 'pendiente';
+    if (validacion.startsWith('rechazado'))
+        return 'rechazado';
+    return null;
+}
+const CHIP_CORRUPTO = 'los datos del chip NFC están corruptos';
+const CLAVE_CHIP = 'problema interno con la clave criptográfica del chip NFC';
+const MOTIVOS = {
+    checkpoint_not_found: 'la etiqueta o código no está vinculado a ningún checkpoint',
+    checkpoint_archived: 'el checkpoint está archivado (dado de baja)',
+    untyped_scan_on_protected_checkpoint: 'escaneo sin datos de verificación en un checkpoint protegido',
+    missing_verification_payload: 'faltan los datos de verificación',
+    unsupported_verification_type: 'tipo de verificación no soportado',
+    no_methods_configured: 'el checkpoint no tiene métodos activos de este tipo',
+    method_not_configured: 'el método de verificación no está bien configurado',
+    no_matching_method: 'no coincidió con ningún método configurado en el checkpoint',
+    invalid_payload: 'datos de verificación inválidos',
+    code_mismatch: 'el código no coincide con el del checkpoint',
+    invalid_uid: 'el UID de la etiqueta no es válido',
+    uid_mismatch: 'el UID de la etiqueta no coincide con el configurado',
+    checkpoint_has_no_coords: 'el checkpoint no tiene coordenadas, así que no se puede comprobar la geocerca',
+    out_of_radius: 'fuera de la distancia máxima configurada del checkpoint',
+    chip_uid_missing: 'falta el UID del chip NFC',
+    chip_not_registered: 'el chip NFC no está registrado',
+    chip_does_not_belong_to_checkpoint: 'el chip NFC pertenece a otro checkpoint',
+    master_key_unavailable: CLAVE_CHIP,
+    key_decryption_failed: CLAVE_CHIP,
+    invalid_key: CLAVE_CHIP,
+    malformed_picc: CHIP_CORRUPTO,
+    malformed_cmac: CHIP_CORRUPTO,
+    sig_mismatch: 'firma no válida',
+    cmac_mismatch: 'firma anticlonado inválida (posible clonación de la etiqueta)',
+    counter_replay: 'se detectó una repetición de un escaneo anterior (anticlonado)',
+    physical_uid_mismatch: 'etiqueta clonada: el enlace está grabado en un chip físico distinto',
+    physical_uid_required: 'falta el UID físico del chip para comprobar que no está clonado',
+};
+const REGLAS_FRAUDE = {
+    gpsProximity: 'el GPS del móvil estaba más lejos del punto que la distancia máxima configurada (severidad media)',
+    // Falla cuando el punto es subterráneo pero el móvil SÍ tenía cobertura.
+    undergroundMode: 'el punto está marcado como subterráneo, pero el móvil tenía cobertura (wifi o datos móviles), lo que sugiere que no estaba en ese lugar (señal leve) (severidad baja)',
+    patrollerLocationMismatch: 'el vigilante escaneó en una ubicación a la que no está asignado (severidad alta)',
+};
+function reglaFallida(valor) {
+    return (typeof valor === 'object' && valor !== null && valor.status === 'fail');
+}
+/**
+ * A cuánto estaba el móvil del punto: con unos metros de más, la distancia es
+ * demasiado ajustada; con cientos o miles, el punto está mal situado en el mapa.
+ */
+function distanciaGps(valor) {
+    const { distanceMeters, accuracyMeters } = valor;
+    if (typeof distanceMeters !== 'number')
+        return '';
+    const precision = typeof accuracyMeters === 'number'
+        ? `, con precisión GPS de ±${Math.round(accuracyMeters)} m`
+        : '';
+    return ` (el móvil estaba a ${Math.round(distanceMeters)} m del punto guardado${precision})`;
+}
+export function explainScan(scan) {
+    const estado = scan.validationStatus
+        ? (ESTADOS[scan.validationStatus] ?? scan.validationStatus)
+        : 'sin estado de validación';
+    const motivo = scan.validationReason
+        ? (MOTIVOS[scan.validationReason] ?? scan.validationReason)
+        : null;
+    const validacion = motivo ? `${estado} (motivo: ${motivo})` : estado;
+    if (scan.fraudFlags?.flagged !== true)
+        return { validacion, motivosSospecha: [] };
+    const motivosSospecha = Object.entries(scan.fraudFlags)
+        .filter(([regla, valor]) => regla !== 'flagged' && reglaFallida(valor))
+        .map(([regla, valor]) => (REGLAS_FRAUDE[regla] ?? regla) + (regla === 'gpsProximity' ? distanciaGps(valor) : ''));
+    return {
+        validacion,
+        motivosSospecha: motivosSospecha.length > 0
+            ? motivosSospecha
+            : ['marcado como sospechoso sin motivo detallado'],
+    };
+}
+//# sourceMappingURL=scan-explanation.js.map

package/dist/domain/scan-explanation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-explanation.js","sourceRoot":"","sources":["../../src/domain/scan-explanation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gFAAgF;AAChF,+EAA+E;AAC/E,MAAM,OAAO,GAA2B;IACtC,QAAQ,EAAE,kDAAkD;IAC5D,cAAc,EACZ,sHAAsH;IACxH,QAAQ,EAAE,kCAAkC;CAC7C,CAAC;AAEF,gHAAgH;AAChH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrD,IAAI,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,WAAW,CAAC;IAC3D,IAAI,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,WAAW,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,aAAa,GAAG,wCAAwC,CAAC;AAC/D,MAAM,UAAU,GAAG,0DAA0D,CAAC;AAE9E,MAAM,OAAO,GAA2B;IACtC,oBAAoB,EAAE,4DAA4D;IAClF,mBAAmB,EAAE,6CAA6C;IAClE,oCAAoC,EAClC,8DAA8D;IAChE,4BAA4B,EAAE,kCAAkC;IAChE,6BAA6B,EAAE,mCAAmC;IAClE,qBAAqB,EAAE,qDAAqD;IAC5E,qBAAqB,EAAE,oDAAoD;IAC3E,kBAAkB,EAAE,6DAA6D;IACjF,eAAe,EAAE,iCAAiC;IAClD,aAAa,EAAE,6CAA6C;IAC5D,WAAW,EAAE,oCAAoC;IACjD,YAAY,EAAE,sDAAsD;IACpE,wBAAwB,EACtB,+EAA+E;IACjF,aAAa,EAAE,yDAAyD;IACxE,gBAAgB,EAAE,2BAA2B;IAC7C,mBAAmB,EAAE,gCAAgC;IACrD,kCAAkC,EAAE,yCAAyC;IAC7E,sBAAsB,EAAE,UAAU;IAClC,qBAAqB,EAAE,UAAU;IACjC,WAAW,EAAE,UAAU;IACvB,cAAc,EAAE,aAAa;IAC7B,cAAc,EAAE,aAAa;IAC7B,YAAY,EAAE,iBAAiB;IAC/B,aAAa,EAAE,+DAA+D;IAC9E,cAAc,EAAE,gEAAgE;IAChF,qBAAqB,EAAE,qEAAqE;IAC5F,qBAAqB,EAAE,iEAAiE;CACzF,CAAC;AAEF,MAAM,aAAa,GAA2B;IAC5C,YAAY,EACV,mGAAmG;IACrG,yEAAyE;IACzE,eAAe,EACb,uKAAuK;IACzK,yBAAyB,EACvB,kFAAkF;CACrF,CAAC;AAcF,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA8B,CAAC,MAAM,KAAK,MAAM,CACjG,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,GAAG,KAG1C,CAAC;IACF,IAAI,OAAO,cAAc,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAClD,MAAM,SAAS,GACb,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,2BAA2B,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI;QAC3D,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,uBAAuB,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,wBAAwB,SAAS,GAAG,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAyB;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB;QAClC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,gBAAgB,CAAC;QAC3D,CAAC,CAAC,0BAA0B,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB;QAClC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,gBAAgB,CAAC;QAC3D,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,aAAa,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;IAErE,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IAClF,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;SACpD,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;SACtE,GAAG,CACF,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CACjB,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAC1F,CAAC;IACJ,OAAO;QACL,UAAU;QACV,eAAe,EACb,eAAe,CAAC,MAAM,GAAG,CAAC;YACxB,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,CAAC,8CAA8C,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/domain/scans-csv.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lo que el CSV necesita de un escaneo reciente. Es un subconjunto estructural
+ * del escaneo que devuelve el backend: cualquier `RecentScan` lo cumple, y este
+ * módulo no depende de la forma completa del cliente.
+ */
+export interface ScanCsvRow {
+    timestamp: string;
+    checkpointName: string | null;
+    patrollerName: string | null;
+    fraudFlagged: boolean;
+    /** Estado de validación en lenguaje de cliente. */
+    validacion: string;
+    /** Motivos reales de la sospecha; vacío si no es sospechoso. */
+    motivosSospecha: string[];
+    dispositivo?: {
+        modelo?: string;
+        sistema?: string;
+        bateriaPct?: number;
+    };
+    distanciaGpsM?: number;
+}
+/**
+ * Una celda: texto neutralizado si parece fórmula y entre comillas si lleva `;`, `,`,
+ * tabulador, comillas o saltos.
+ */
+export declare function csvCell(value: string | number | null | undefined): string;
+/** `YYYY-MM-DD HH:mm:ss` en la hora del cliente: Excel lo reconoce como fecha en cualquier idioma. */
+export declare function fechaLocal(iso: string, tz: string): string;
+export declare function scansCsv(scans: readonly ScanCsvRow[], opts: {
+    tz: string;
+    ubicacionDe: (scan: ScanCsvRow) => string;
+}): Buffer;
+type Celda = string | number | null | undefined;
+/** Cabeceras y filas → el fichero. Lo comparten todos los Excel que envía el bot. */
+export declare function csvBytes(cabeceras: readonly string[], filas: readonly (readonly Celda[])[]): Buffer;
+export {};
+//# sourceMappingURL=scans-csv.d.ts.map

package/dist/domain/scans-csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scans-csv.d.ts","sourceRoot":"","sources":["../../src/domain/scans-csv.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8BD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAKzE;AAID,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAG1D;AAOD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAA;CAAE,GAC9D,MAAM,CAaR;AAED,KAAK,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEhD,qFAAqF;AACrF,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,KAAK,EAAE,SAAS,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,GACnC,MAAM,CAGR"}

package/dist/domain/scans-csv.js

@@ -0,0 +1,67 @@
+import { zonedParts } from './timezone.js';
+/**
+ * Escaneos como CSV que Excel abre bien sin dependencias: UTF-8 con BOM (sin él
+ * Excel lee los acentos como Latin-1) y separador `;` (el de Excel en español y
+ * en Latinoamérica, donde la coma es el separador decimal).
+ */
+const CABECERAS = [
+    'Fecha y hora',
+    'Vigilante',
+    'Checkpoint',
+    'Ubicación',
+    'Validación',
+    'Sospechoso',
+    'Distancia GPS (m)',
+    'Dispositivo',
+    'Batería %',
+];
+// Inyección de fórmulas (OWASP «CSV injection»): una celda que empieza por uno
+// de estos caracteres Excel la ejecuta como fórmula. El apóstrofo la deja en texto.
+const FORMULA_RE = /^[=+\-@\t\r]/;
+// Excel con `,` como separador de lista (configuración regional) parte la fila por comas
+// aunque el fichero use `;`: una celda sin comillas como `Nave,=1+1` dejaría el fragmento
+// tras la coma como celda nueva que empieza por `=` y se ejecutaría. Por eso también se
+// entrecomilla toda celda con coma o tabulador.
+const QUOTE_RE = /[";,\t\r\n]/;
+/**
+ * Una celda: texto neutralizado si parece fórmula y entre comillas si lleva `;`, `,`,
+ * tabulador, comillas o saltos.
+ */
+export function csvCell(value) {
+    if (value === null || value === undefined)
+        return '';
+    let text = String(value);
+    if (typeof value === 'string' && FORMULA_RE.test(text))
+        text = `'${text}`;
+    return QUOTE_RE.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+const dos = (n) => String(n).padStart(2, '0');
+/** `YYYY-MM-DD HH:mm:ss` en la hora del cliente: Excel lo reconoce como fecha en cualquier idioma. */
+export function fechaLocal(iso, tz) {
+    const p = zonedParts(new Date(iso), tz);
+    return `${p.y}-${dos(p.m)}-${dos(p.d)} ${dos(p.h)}:${dos(p.mi)}:${dos(p.s)}`;
+}
+function dispositivo(scan) {
+    const { modelo, sistema } = scan.dispositivo ?? {};
+    return [modelo, sistema].filter(Boolean).join(' · ');
+}
+export function scansCsv(scans, opts) {
+    const filas = scans.map((s) => [
+        fechaLocal(s.timestamp, opts.tz),
+        s.patrollerName,
+        s.checkpointName,
+        opts.ubicacionDe(s),
+        s.validacion,
+        s.fraudFlagged ? `sí: ${s.motivosSospecha.join('; ')}` : 'no',
+        s.distanciaGpsM,
+        dispositivo(s),
+        s.dispositivo?.bateriaPct,
+    ]);
+    return csvBytes(CABECERAS, filas);
+}
+/** Cabeceras y filas → el fichero. Lo comparten todos los Excel que envía el bot. */
+export function csvBytes(cabeceras, filas) {
+    const lineas = [cabeceras, ...filas].map((fila) => fila.map(csvCell).join(';'));
+    return Buffer.from(`\uFEFF${lineas.join('\r\n')}\r\n`, 'utf8');
+}
+//# sourceMappingURL=scans-csv.js.map

package/dist/domain/scans-csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scans-csv.js","sourceRoot":"","sources":["../../src/domain/scans-csv.ts"],"names":[],"mappings":"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"}