@arquimedes.co/eureka-forms 3.0.71 → 3.0.72

package/dist/Services/BookingService.d.ts

@@ -1,4 +1,4 @@
-import { BookingSlot } from '../@Types/BookingFormStep';
+import { BookingSlot, BookingValue } from '../@Types/BookingFormStep';
 /**
  * Cómo llegar al paso BOOKING de un formulario publicado. Misma regla que el envío del formulario:
  * un form embebido o interno nombra su organización y sale por el dominio de forms; uno servido por
@@ -18,6 +18,20 @@ export interface BookingOfferPerson {
     avatarUrl?: string;
     description?: string;
 }
+/** An event template of the step as the offer publishes it: a signed handle, never the template's id. */
+export interface BookingOfferEventTemplate {
+    token: string;
+    name: string;
+    description?: string;
+    /** The template's own duration, or the step's when the template has none. */
+    durationMinutes: number;
+    bookingMode?: string;
+}
+/** The event template an appointment was booked with: what the summary and the manage page show. */
+export interface BookingEventTemplateSummary {
+    name: string;
+    durationMinutes: number;
+}
 /** Lo que el picker necesita para dibujarse: en qué zona horaria leer las horas y qué días tienen cupo. */
 export interface BookingOffer {
     timeZone: string;
@@ -29,6 +43,15 @@ export interface BookingOffer {
     days: string[];
     from: string;
     to: string;
+    /** The step's event templates with something on offer; empty when the step has none. */
+    eventTemplates?: BookingOfferEventTemplate[];
+    /** The requester picks an event template first: the step lets them and there are two or more. */
+    requesterPicksType?: boolean;
+}
+/** What narrows a read of the offer: one person's calendar, one event template's slots and duration. */
+export interface BookingOfferQuery {
+    person?: string;
+    eventTemplate?: string;
 }
 /** Un slot tal como lo ofrece el backend: instantes ISO y el handle firmado que lo nombra. */
 export interface BookingOfferSlot {
@@ -36,29 +59,119 @@ export interface BookingOfferSlot {
     end: string;
     token: string;
 }
-/** Un slot retirado de la oferta mientras se termina el formulario. */
+/**
+ * Un slot retirado de la oferta mientras se termina el formulario. `start`/`end` son los instantes
+ * reales reservados y `person` es quien atenderá (el servidor la elige cuando hay varias libres).
+ */
 export interface BookingHold {
     appointment: string;
+    /** Secreto del dueño de la reserva: viaja con el envío del formulario. */
     hold: string;
     lockedUntil: string;
+    /** Token para la próxima renovación; vive hasta `lockedUntil` y cada renovación devuelve uno nuevo. */
+    renew: string;
+    start: string;
+    end: string;
+    /** Falta solo si el agente dejó la organización. */
+    person?: BookingOfferPerson;
+    /** The event template the hold was made with, when the requester picked one. */
+    eventTemplate?: BookingEventTemplateSummary;
 }
 export interface BookingContact {
     name: string;
-    email?: string;
+    email: string;
     phone?: string;
 }
-/** La oferta del paso; con `person`, la oferta de esa persona (los días que ella tiene libres). */
-export declare function fetchBookingOffer(route: BookingRoute, person?: string): Promise<BookingOffer>;
+/** Los códigos con los que el borde de agendamiento explica un rechazo. */
+export declare enum BookingErrorCodes {
+    INVALID_REQUEST = "INVALID_REQUEST",
+    NOT_FOUND = "NOT_FOUND",
+    FORBIDDEN = "FORBIDDEN",
+    /** Un token de persona o de cupo venció: hay que recargar la oferta (o las horas). */
+    STALE_OFFER = "STALE_OFFER",
+    CONTACT_REQUIRED = "CONTACT_REQUIRED",
+    SLOT_TAKEN = "SLOT_TAKEN",
+    /** La renovación llegó tarde: la reserva ya venció. */
+    HOLD_EXPIRED = "HOLD_EXPIRED",
+    /** El enlace de la cita venció, fue alterado o ya no nombra ninguna cita. */
+    INVALID_LINK = "INVALID_LINK",
+    /** La cita ya no se puede cancelar ni mover: está cancelada o su paso ya no existe. */
+    APPOINTMENT_CLOSED = "APPOINTMENT_CLOSED",
+    RATE_LIMITED = "RATE_LIMITED",
+    METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED",
+    INTERNAL = "INTERNAL"
+}
+/** Un rechazo del borde ya leído: el mensaje es apto para mostrarse a quien agenda. */
+export declare class BookingEdgeError extends Error {
+    readonly code?: string;
+    readonly status?: number;
+    constructor(message: string, code?: string, status?: number);
+}
+/** El texto que muestra el picker cuando la renovación de la reserva falla para siempre. */
+export declare const HOLD_LAPSED_MESSAGE = "Tu reserva venci\u00F3; elige la hora de nuevo.";
+/**
+ * Una cita ya agendada, vista desde el enlace de sus correos: cuándo, con quién y cómo, y lo que quien
+ * la agendó todavía puede hacer con ella.
+ */
+export interface BookingAppointment {
+    /** El handle del enlace para esta cita; cambia cuando la cita se mueve, y el siguiente pedido usa este. */
+    token: string;
+    status: 'CONFIRMED' | 'CANCELLED';
+    start: string;
+    end: string;
+    /** La zona horaria de la organización, en la que se muestran `start` y `end`. */
+    timeZone: string;
+    person?: Omit<BookingOfferPerson, 'token'>;
+    bookingMode?: string;
+    eventTemplateName?: string;
+    eventTemplate?: BookingEventTemplateSummary;
+    joinUrl?: string;
+    /**
+     * Cómo ofrecer otra hora con la misma persona; falta cuando la cita ya no se puede mover desde aquí.
+     * `eventTemplate` is the handle of the appointment's template, so the new hour keeps its type.
+     */
+    reschedule?: {
+        apiKey: string;
+        idStep: string;
+        person: string;
+        durationMinutes: number;
+        eventTemplate?: string;
+    };
+}
+/** La cita que nombra el enlace. Un enlace vencido o alterado responde 404 `INVALID_LINK`. */
+export declare function fetchBookingAppointment(token: string, idOrganization?: string): Promise<BookingAppointment>;
+/** Cancela la cita; responde la cita ya cancelada. Una cita que ya no está vigente responde 409 `APPOINTMENT_CLOSED`. */
+export declare function cancelBookingAppointment(token: string, idOrganization?: string): Promise<BookingAppointment>;
+/**
+ * Mueve la cita al cupo `slot` (un handle de la oferta del mismo paso y la misma persona). Responde la
+ * cita movida con su handle nuevo; 409 `SLOT_TAKEN` si alguien tomó la hora primero.
+ */
+export declare function moveBookingAppointment(token: string, slot: string, idOrganization?: string): Promise<BookingAppointment>;
+/**
+ * La oferta del paso; con `person`, la oferta de esa persona (los días que ella tiene libres), y con
+ * `eventTemplate`, los días de ese tipo de atención con su duración.
+ */
+export declare function fetchBookingOffer(route: BookingRoute, query?: BookingOfferQuery): Promise<BookingOffer>;
 /** Los slots de un día, `date` en `YYYY-MM-DD` de la zona horaria de la organización. */
-export declare function fetchBookingSlots(route: BookingRoute, date: string, person?: string): Promise<BookingOfferSlot[]>;
+export declare function fetchBookingSlots(route: BookingRoute, date: string, query?: BookingOfferQuery): Promise<BookingOfferSlot[]>;
 /**
- * Bloquea un slot (o renueva un bloqueo propio si se envía su `hold`). El backend responde 409 cuando
- * otra persona ya lo tomó, y 422 cuando el paso exige contacto y no llegó.
+ * Bloquea un slot a nombre de quien agenda. El borde responde 409 `SLOT_TAKEN` cuando nadie quedó
+ * libre a esa hora y 422 `CONTACT_REQUIRED` sin nombre o sin correo válido. `eventTemplate` is the
+ * handle of the type the requester picked; the appointment takes that type's duration.
  */
 export declare function holdBookingSlot(route: BookingRoute, body: {
     slot: string;
-    hold?: string;
-    contact?: BookingContact;
+    contact: BookingContact;
+    eventTemplate?: string;
+}): Promise<BookingHold>;
+/**
+ * Extiende una reserva propia con el `renew` de la última respuesta. No depende del token del cupo,
+ * así que una reserva renovada a tiempo vive lo que tarde el formulario. Una reserva ya vencida
+ * responde 409 `HOLD_EXPIRED`.
+ */
+export declare function renewBookingHold(route: BookingRoute, body: {
+    renew: string;
+    hold: string;
 }): Promise<BookingHold>;
 /** Devuelve un slot antes de que venza su bloqueo, para que se ofrezca de nuevo de inmediato. */
 export declare function releaseBookingSlot(route: BookingRoute, body: {
@@ -71,9 +184,43 @@ export declare function releaseBookingSlot(route: BookingRoute, body: {
  * que agenda esté en Madrid.
  */
 export declare function clockIn(iso: string, timeZone: string): string;
+/** El día `YYYY-MM-DD` de un instante en una zona horaria. */
+export declare function dayIn(iso: string, timeZone: string): string;
+/** La zona horaria del navegador, o `undefined` si no se puede leer. */
+export declare function browserTimeZone(): string | undefined;
+/**
+ * Cómo se nombra la zona de la organización junto a las horas: "hora de Bogotá (GMT-5)". El desfase
+ * se calcula en `at`, porque en las zonas con horario de verano cambia según el día.
+ */
+export declare function zoneLabel(timeZone: string, at?: Date): string;
 /** Un slot de la oferta como lo consume el picker: el handle es su id y las horas van en el reloj de la organización. */
 export declare function toPickerSlot(slot: BookingOfferSlot, timeZone: string): BookingSlot;
+/**
+ * Las horas de un día como las muestra el picker: una por instante y en orden. El borde ya agrupa por
+ * instante; si llegara un instante repetido, gana el primero y el servidor elige a la persona al reservar.
+ */
+export declare function toPickerSlots(slots: BookingOfferSlot[], timeZone: string): BookingSlot[];
+/**
+ * Lo que la reserva aporta al valor del paso: día y horas reales en el reloj de la organización, la
+ * persona asignada y el tipo de atención elegido.
+ */
+export declare function holdToValue(held: BookingHold, timeZone: string): Pick<BookingValue, 'appointment' | 'hold' | 'lockedUntil' | 'date' | 'startTime' | 'endTime'> & Partial<Pick<BookingValue, 'personId' | 'personName' | 'eventTemplate'>>;
 /** Un texto opcional de un campo de contacto: vacío o solo espacios cuenta como no dado. */
 export declare function nonEmpty(text?: string): string | undefined;
-/** El motivo de un rechazo del backend, que llega como texto plano, o un mensaje genérico. */
-export declare function bookingErrorMessage(error: unknown): string;
+/** Si un texto es un correo con forma válida (lo mismo que exige el borde al reservar). */
+export declare function isValidEmail(text?: string): boolean;
+/** El código HTTP de un error del cliente HTTP, si lo hay. */
+export declare function statusOf(error: unknown): number | undefined;
+/**
+ * Lee un rechazo del borde. El borde responde `{ code, message }` con el mensaje en español; los
+ * errores que el gateway responde antes de la lambda siguen llegando como texto plano.
+ */
+export declare function toBookingError(error: unknown, fallback?: string): BookingEdgeError;
+/** El motivo de un rechazo del borde, o un mensaje genérico. */
+export declare function bookingErrorMessage(error: unknown, fallback?: string): string;
+/**
+ * Si una renovación fallida significa que la reserva ya no existe: el borde lo dice (`HOLD_EXPIRED`,
+ * o el token venció), o el plazo pasó sin una renovación que llegara. Un corte de red o un 429 antes
+ * del plazo se reintenta en la siguiente vuelta.
+ */
+export declare function holdLapsed(error: BookingEdgeError, lockedUntil: string | undefined, now?: number): boolean;

package/dist/Services/BookingService.js

@@ -1,5 +1,48 @@
 import axiosInstance from '../Utils/AxiosAPI';
 import widgetInstance from '../Utils/AxiosWidget';
+/** Los códigos con los que el borde de agendamiento explica un rechazo. */
+export var BookingErrorCodes;
+(function (BookingErrorCodes) {
+    BookingErrorCodes["INVALID_REQUEST"] = "INVALID_REQUEST";
+    BookingErrorCodes["NOT_FOUND"] = "NOT_FOUND";
+    BookingErrorCodes["FORBIDDEN"] = "FORBIDDEN";
+    /** Un token de persona o de cupo venció: hay que recargar la oferta (o las horas). */
+    BookingErrorCodes["STALE_OFFER"] = "STALE_OFFER";
+    BookingErrorCodes["CONTACT_REQUIRED"] = "CONTACT_REQUIRED";
+    BookingErrorCodes["SLOT_TAKEN"] = "SLOT_TAKEN";
+    /** La renovación llegó tarde: la reserva ya venció. */
+    BookingErrorCodes["HOLD_EXPIRED"] = "HOLD_EXPIRED";
+    /** El enlace de la cita venció, fue alterado o ya no nombra ninguna cita. */
+    BookingErrorCodes["INVALID_LINK"] = "INVALID_LINK";
+    /** La cita ya no se puede cancelar ni mover: está cancelada o su paso ya no existe. */
+    BookingErrorCodes["APPOINTMENT_CLOSED"] = "APPOINTMENT_CLOSED";
+    BookingErrorCodes["RATE_LIMITED"] = "RATE_LIMITED";
+    BookingErrorCodes["METHOD_NOT_ALLOWED"] = "METHOD_NOT_ALLOWED";
+    BookingErrorCodes["INTERNAL"] = "INTERNAL";
+})(BookingErrorCodes || (BookingErrorCodes = {}));
+/** Un rechazo del borde ya leído: el mensaje es apto para mostrarse a quien agenda. */
+export class BookingEdgeError extends Error {
+    constructor(message, code, status) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'BookingEdgeError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/** El texto que muestra el picker cuando la renovación de la reserva falla para siempre. */
+export const HOLD_LAPSED_MESSAGE = 'Tu reserva venció; elige la hora de nuevo.';
 function client(route) {
     return route.idOrganization || route.internal ? widgetInstance : axiosInstance;
 }
@@ -14,24 +57,62 @@ function url(route, suffix, params = {}) {
     const query = search.toString();
     return `/booking/${route.apiKey}/${route.idStep}${suffix}${query ? `?${query}` : ''}`;
 }
-/** La oferta del paso; con `person`, la oferta de esa persona (los días que ella tiene libres). */
-export async function fetchBookingOffer(route, person) {
-    const response = await client(route).get(url(route, '', { person }));
+function appointmentUrl(token, idOrganization, suffix = '') {
+    const query = idOrganization ? `?${new URLSearchParams({ idOrganization }).toString()}` : '';
+    return `/booking/appointment/${encodeURIComponent(token)}${suffix}${query}`;
+}
+function appointmentClient(idOrganization) {
+    return idOrganization ? widgetInstance : axiosInstance;
+}
+/** La cita que nombra el enlace. Un enlace vencido o alterado responde 404 `INVALID_LINK`. */
+export async function fetchBookingAppointment(token, idOrganization) {
+    const response = await appointmentClient(idOrganization).get(appointmentUrl(token, idOrganization));
+    return response.data;
+}
+/** Cancela la cita; responde la cita ya cancelada. Una cita que ya no está vigente responde 409 `APPOINTMENT_CLOSED`. */
+export async function cancelBookingAppointment(token, idOrganization) {
+    const response = await appointmentClient(idOrganization).post(appointmentUrl(token, idOrganization, '/cancel'));
+    return response.data;
+}
+/**
+ * Mueve la cita al cupo `slot` (un handle de la oferta del mismo paso y la misma persona). Responde la
+ * cita movida con su handle nuevo; 409 `SLOT_TAKEN` si alguien tomó la hora primero.
+ */
+export async function moveBookingAppointment(token, slot, idOrganization) {
+    const response = await appointmentClient(idOrganization).post(appointmentUrl(token, idOrganization, '/move'), { slot });
+    return response.data;
+}
+/**
+ * La oferta del paso; con `person`, la oferta de esa persona (los días que ella tiene libres), y con
+ * `eventTemplate`, los días de ese tipo de atención con su duración.
+ */
+export async function fetchBookingOffer(route, query = {}) {
+    const response = await client(route).get(url(route, '', { person: query.person, eventTemplate: query.eventTemplate }));
     return response.data;
 }
 /** Los slots de un día, `date` en `YYYY-MM-DD` de la zona horaria de la organización. */
-export async function fetchBookingSlots(route, date, person) {
-    const response = await client(route).get(url(route, '/slots', { date, person }));
+export async function fetchBookingSlots(route, date, query = {}) {
+    const response = await client(route).get(url(route, '/slots', { date, person: query.person, eventTemplate: query.eventTemplate }));
     return response.data.slots;
 }
 /**
- * Bloquea un slot (o renueva un bloqueo propio si se envía su `hold`). El backend responde 409 cuando
- * otra persona ya lo tomó, y 422 cuando el paso exige contacto y no llegó.
+ * Bloquea un slot a nombre de quien agenda. El borde responde 409 `SLOT_TAKEN` cuando nadie quedó
+ * libre a esa hora y 422 `CONTACT_REQUIRED` sin nombre o sin correo válido. `eventTemplate` is the
+ * handle of the type the requester picked; the appointment takes that type's duration.
  */
 export async function holdBookingSlot(route, body) {
     const response = await client(route).post(url(route, '/hold'), body);
     return response.data;
 }
+/**
+ * Extiende una reserva propia con el `renew` de la última respuesta. No depende del token del cupo,
+ * así que una reserva renovada a tiempo vive lo que tarde el formulario. Una reserva ya vencida
+ * responde 409 `HOLD_EXPIRED`.
+ */
+export async function renewBookingHold(route, body) {
+    const response = await client(route).post(url(route, '/hold'), body);
+    return response.data;
+}
 /** Devuelve un slot antes de que venza su bloqueo, para que se ofrezca de nuevo de inmediato. */
 export async function releaseBookingSlot(route, body) {
     await client(route).post(url(route, '/release'), body);
@@ -44,6 +125,49 @@ export async function releaseBookingSlot(route, body) {
 export function clockIn(iso, timeZone) {
     return new Intl.DateTimeFormat('en-GB', { hour: '2-digit', minute: '2-digit', hourCycle: 'h23', timeZone }).format(new Date(iso));
 }
+/** El día `YYYY-MM-DD` de un instante en una zona horaria. */
+export function dayIn(iso, timeZone) {
+    return new Intl.DateTimeFormat('en-CA', { year: 'numeric', month: '2-digit', day: '2-digit', timeZone }).format(new Date(iso));
+}
+/** La zona horaria del navegador, o `undefined` si no se puede leer. */
+export function browserTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ciudades de zonas IANA cuyo nombre en español lleva tilde o cambia. */
+const CITY_NAMES = {
+    Bogota: 'Bogotá',
+    Mexico_City: 'Ciudad de México',
+    Panama: 'Panamá',
+    Asuncion: 'Asunción',
+    Sao_Paulo: 'São Paulo',
+    New_York: 'Nueva York',
+    Los_Angeles: 'Los Ángeles',
+    Merida: 'Mérida',
+    Cancun: 'Cancún',
+};
+/**
+ * Cómo se nombra la zona de la organización junto a las horas: "hora de Bogotá (GMT-5)". El desfase
+ * se calcula en `at`, porque en las zonas con horario de verano cambia según el día.
+ */
+export function zoneLabel(timeZone, at = new Date()) {
+    const id = timeZone.split('/').pop() ?? timeZone;
+    const city = CITY_NAMES[id] ?? id.replace(/_/g, ' ');
+    let offset;
+    try {
+        offset = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'shortOffset' })
+            .formatToParts(at)
+            .find((part) => part.type === 'timeZoneName')?.value;
+    }
+    catch {
+        offset = undefined;
+    }
+    return offset ? `hora de ${city} (${offset})` : `hora de ${city}`;
+}
 /** Un slot de la oferta como lo consume el picker: el handle es su id y las horas van en el reloj de la organización. */
 export function toPickerSlot(slot, timeZone) {
     return {
@@ -51,16 +175,90 @@ export function toPickerSlot(slot, timeZone) {
         startTime: clockIn(slot.start, timeZone),
         endTime: clockIn(slot.end, timeZone),
         available: true,
+        start: slot.start,
+    };
+}
+/**
+ * Las horas de un día como las muestra el picker: una por instante y en orden. El borde ya agrupa por
+ * instante; si llegara un instante repetido, gana el primero y el servidor elige a la persona al reservar.
+ */
+export function toPickerSlots(slots, timeZone) {
+    const seen = new Set();
+    return [...slots]
+        .sort((a, b) => a.start.localeCompare(b.start))
+        .filter((slot) => {
+        if (seen.has(slot.start))
+            return false;
+        seen.add(slot.start);
+        return true;
+    })
+        .map((slot) => toPickerSlot(slot, timeZone));
+}
+/**
+ * Lo que la reserva aporta al valor del paso: día y horas reales en el reloj de la organización, la
+ * persona asignada y el tipo de atención elegido.
+ */
+export function holdToValue(held, timeZone) {
+    return {
+        appointment: held.appointment,
+        hold: held.hold,
+        lockedUntil: held.lockedUntil,
+        date: dayIn(held.start, timeZone),
+        startTime: clockIn(held.start, timeZone),
+        endTime: clockIn(held.end, timeZone),
+        ...(held.person ? { personId: held.person.token, personName: held.person.name } : {}),
+        ...(held.eventTemplate
+            ? { eventTemplate: { name: held.eventTemplate.name, durationMinutes: held.eventTemplate.durationMinutes } }
+            : {}),
     };
 }
 /** Un texto opcional de un campo de contacto: vacío o solo espacios cuenta como no dado. */
 export function nonEmpty(text) {
-    return text?.trim() ? text : undefined;
+    return text?.trim() ? text.trim() : undefined;
+}
+/** Si un texto es un correo con forma válida (lo mismo que exige el borde al reservar). */
+export function isValidEmail(text) {
+    return !!text && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(text.trim());
+}
+/** El código HTTP de un error del cliente HTTP, si lo hay. */
+export function statusOf(error) {
+    return error?.response?.status;
 }
-/** El motivo de un rechazo del backend, que llega como texto plano, o un mensaje genérico. */
-export function bookingErrorMessage(error) {
+/**
+ * Lee un rechazo del borde. El borde responde `{ code, message }` con el mensaje en español; los
+ * errores que el gateway responde antes de la lambda siguen llegando como texto plano.
+ */
+export function toBookingError(error, fallback = 'No pudimos reservar ese horario. Intenta de nuevo.') {
+    if (error instanceof BookingEdgeError)
+        return error;
+    const status = statusOf(error);
     const data = error?.response?.data;
+    if (data && typeof data === 'object') {
+        const { code, message } = data;
+        if (typeof message === 'string' && message.trim()) {
+            return new BookingEdgeError(message, typeof code === 'string' ? code : undefined, status);
+        }
+    }
     if (typeof data === 'string' && data.trim())
-        return data;
-    return 'No pudimos reservar ese horario. Intenta de nuevo.';
+        return new BookingEdgeError(data, undefined, status);
+    if (status === 429) {
+        return new BookingEdgeError('Hay muchas consultas en este momento. Intenta de nuevo en unos segundos.', BookingErrorCodes.RATE_LIMITED, status);
+    }
+    return new BookingEdgeError(fallback, undefined, status);
+}
+/** El motivo de un rechazo del borde, o un mensaje genérico. */
+export function bookingErrorMessage(error, fallback) {
+    return toBookingError(error, fallback).message;
+}
+/**
+ * Si una renovación fallida significa que la reserva ya no existe: el borde lo dice (`HOLD_EXPIRED`,
+ * o el token venció), o el plazo pasó sin una renovación que llegara. Un corte de red o un 429 antes
+ * del plazo se reintenta en la siguiente vuelta.
+ */
+export function holdLapsed(error, lockedUntil, now = Date.now()) {
+    if (error.code === BookingErrorCodes.HOLD_EXPIRED || error.code === BookingErrorCodes.STALE_OFFER)
+        return true;
+    if (error.code === BookingErrorCodes.NOT_FOUND || error.code === BookingErrorCodes.INVALID_REQUEST)
+        return true;
+    return !!lockedUntil && new Date(lockedUntil).getTime() <= now;
 }

package/dist/Services/BookingService.test.js

@@ -2,7 +2,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import axiosInstance from '../Utils/AxiosAPI';
 import widgetInstance from '../Utils/AxiosWidget';
-import { bookingErrorMessage, clockIn, fetchBookingOffer, fetchBookingSlots, holdBookingSlot, releaseBookingSlot, toPickerSlot, } from './BookingService';
+import { BookingEdgeError, BookingErrorCodes, bookingErrorMessage, cancelBookingAppointment, clockIn, dayIn, fetchBookingAppointment, fetchBookingOffer, fetchBookingSlots, holdBookingSlot, holdLapsed, holdToValue, isValidEmail, moveBookingAppointment, releaseBookingSlot, renewBookingHold, toBookingError, toPickerSlot, toPickerSlots, zoneLabel, } from './BookingService';
 vi.mock('../Utils/AxiosWidget', () => ({
     default: { get: vi.fn(), post: vi.fn() },
 }));
@@ -20,13 +20,93 @@ describe('BookingService', () => {
         expect(clockIn('2026-09-22T14:00:00.000Z', 'America/Bogota')).toBe('09:00');
         expect(clockIn('2026-09-22T14:00:00.000Z', 'Europe/Madrid')).toBe('16:00');
         expect(clockIn('2026-09-22T05:00:00.000Z', 'America/Bogota')).toBe('00:00');
-        expect(toPickerSlot({ start: '2026-09-22T14:00:00.000Z', end: '2026-09-22T14:30:00.000Z', token: 'tok' }, 'America/Bogota')).toEqual({ id: 'tok', startTime: '09:00', endTime: '09:30', available: true });
+        expect(toPickerSlot({ start: '2026-09-22T14:00:00.000Z', end: '2026-09-22T14:30:00.000Z', token: 'tok' }, 'America/Bogota')).toEqual({
+            id: 'tok',
+            startTime: '09:00',
+            endTime: '09:30',
+            available: true,
+            start: '2026-09-22T14:00:00.000Z',
+        });
+    });
+    it('shows one hour per instant, in order', () => {
+        const slots = toPickerSlots([
+            { start: '2026-09-22T14:15:00.000Z', end: '2026-09-22T14:45:00.000Z', token: 'b' },
+            { start: '2026-09-22T14:00:00.000Z', end: '2026-09-22T14:30:00.000Z', token: 'a' },
+            { start: '2026-09-22T14:00:00.000Z', end: '2026-09-22T14:30:00.000Z', token: 'a2' },
+        ], 'America/Bogota');
+        expect(slots.map((slot) => [slot.id, slot.startTime])).toEqual([
+            ['a', '09:00'],
+            ['b', '09:15'],
+        ]);
+    });
+    it('names the organization clock with its offset on the given day', () => {
+        expect(zoneLabel('America/Bogota', new Date('2026-10-14T12:00:00Z'))).toBe('hora de Bogotá (GMT-5)');
+        expect(zoneLabel('Europe/Madrid', new Date('2026-07-01T12:00:00Z'))).toBe('hora de Madrid (GMT+2)');
+        expect(zoneLabel('Europe/Madrid', new Date('2026-12-01T12:00:00Z'))).toBe('hora de Madrid (GMT+1)');
+    });
+    it('takes the day, hours and assigned person of a hold from the hold itself', () => {
+        // 04:30Z is still the previous day in Bogotá.
+        expect(dayIn('2026-10-15T04:30:00.000Z', 'America/Bogota')).toBe('2026-10-14');
+        expect(holdToValue({
+            appointment: 'a1',
+            hold: 'h1',
+            lockedUntil: '2026-10-14T15:30:00.000Z',
+            renew: 'r1',
+            start: '2026-10-15T14:00:00.000Z',
+            end: '2026-10-15T14:30:00.000Z',
+            person: { token: 'pt', name: 'Bruno Pérez', role: 'Asesor' },
+        }, 'America/Bogota')).toEqual({
+            appointment: 'a1',
+            hold: 'h1',
+            lockedUntil: '2026-10-14T15:30:00.000Z',
+            date: '2026-10-15',
+            startTime: '09:00',
+            endTime: '09:30',
+            personId: 'pt',
+            personName: 'Bruno Pérez',
+        });
+    });
+    it('keeps the event template the hold was made with', () => {
+        expect(holdToValue({
+            appointment: 'a1',
+            hold: 'h1',
+            lockedUntil: '2026-10-14T15:30:00.000Z',
+            renew: 'r1',
+            start: '2026-10-15T14:00:00.000Z',
+            end: '2026-10-15T14:45:00.000Z',
+            eventTemplate: { name: 'Asesoría de crédito', durationMinutes: 45 },
+        }, 'America/Bogota').eventTemplate).toEqual({ name: 'Asesoría de crédito', durationMinutes: 45 });
+    });
+    it('narrows the offer, the slots and the hold to the picked event template', async () => {
+        vi.mocked(axiosInstance.get).mockResolvedValue({ data: { days: [], slots: [] } });
+        vi.mocked(axiosInstance.post).mockResolvedValue({ data: {} });
+        await fetchBookingOffer(ROUTE, { eventTemplate: 'tt-1' });
+        expect(axiosInstance.get).toHaveBeenLastCalledWith('/booking/form-key/BOOKING-1?eventTemplate=tt-1');
+        await fetchBookingSlots(ROUTE, '2026-09-22', { person: 'p', eventTemplate: 'tt-1' });
+        expect(axiosInstance.get).toHaveBeenLastCalledWith('/booking/form-key/BOOKING-1/slots?date=2026-09-22&person=p&eventTemplate=tt-1');
+        await holdBookingSlot(ROUTE, {
+            slot: 's',
+            contact: { name: 'Ana', email: 'ana@correo.com' },
+            eventTemplate: 'tt-1',
+        });
+        expect(axiosInstance.post).toHaveBeenLastCalledWith('/booking/form-key/BOOKING-1/hold', {
+            slot: 's',
+            contact: { name: 'Ana', email: 'ana@correo.com' },
+            eventTemplate: 'tt-1',
+        });
+    });
+    it('accepts only well-formed emails', () => {
+        expect(isValidEmail('juan@correo.com')).toBe(true);
+        expect(isValidEmail(' juan@correo.com ')).toBe(true);
+        expect(isValidEmail('juan@')).toBe(false);
+        expect(isValidEmail('juan correo.com')).toBe(false);
+        expect(isValidEmail(undefined)).toBe(false);
     });
     it('talks to the same-origin API for a form served under the organization', async () => {
         vi.mocked(axiosInstance.get).mockResolvedValue({ data: { days: ['2026-09-22'] } });
         await fetchBookingOffer(ROUTE);
         expect(axiosInstance.get).toHaveBeenCalledWith('/booking/form-key/BOOKING-1');
-        await fetchBookingSlots(ROUTE, '2026-09-22', 'person-token');
+        await fetchBookingSlots(ROUTE, '2026-09-22', { person: 'person-token' });
         expect(axiosInstance.get).toHaveBeenLastCalledWith('/booking/form-key/BOOKING-1/slots?date=2026-09-22&person=person-token');
         expect(widgetInstance.get).not.toHaveBeenCalled();
     });
@@ -34,14 +114,23 @@ describe('BookingService', () => {
         vi.mocked(widgetInstance.get).mockResolvedValue({ data: { days: [] } });
         vi.mocked(widgetInstance.post).mockResolvedValue({ data: { appointment: 'a1', hold: 'h1', lockedUntil: 'x' } });
         const route = { ...ROUTE, idOrganization: 'acme' };
-        await fetchBookingOffer(route, 'p');
+        await fetchBookingOffer(route, { person: 'p' });
         expect(widgetInstance.get).toHaveBeenCalledWith('/booking/form-key/BOOKING-1?idOrganization=acme&person=p');
-        const held = await holdBookingSlot(route, { slot: 'slot-token', contact: { name: 'Ana' } });
+        const held = await holdBookingSlot(route, {
+            slot: 'slot-token',
+            contact: { name: 'Ana', email: 'ana@correo.com' },
+        });
         expect(widgetInstance.post).toHaveBeenCalledWith('/booking/form-key/BOOKING-1/hold?idOrganization=acme', {
             slot: 'slot-token',
-            contact: { name: 'Ana' },
+            contact: { name: 'Ana', email: 'ana@correo.com' },
         });
         expect(held).toEqual({ appointment: 'a1', hold: 'h1', lockedUntil: 'x' });
+        // A renewal carries only the renewal token and the hold secret: no slot, no contact.
+        await renewBookingHold(route, { renew: 'r1', hold: 'h1' });
+        expect(widgetInstance.post).toHaveBeenLastCalledWith('/booking/form-key/BOOKING-1/hold?idOrganization=acme', {
+            renew: 'r1',
+            hold: 'h1',
+        });
         await releaseBookingSlot(route, { appointment: 'a1', hold: 'h1' });
         expect(widgetInstance.post).toHaveBeenLastCalledWith('/booking/form-key/BOOKING-1/release?idOrganization=acme', {
             appointment: 'a1',
@@ -49,9 +138,41 @@ describe('BookingService', () => {
         });
         expect(axiosInstance.get).not.toHaveBeenCalled();
     });
-    it('surfaces the edge’s plain-text refusal, and a generic message otherwise', () => {
-        expect(bookingErrorMessage({ response: { data: 'That slot is no longer available' } })).toBe('That slot is no longer available');
-        expect(bookingErrorMessage({ response: { data: { message: 'Forbidden' } } })).toBe('No pudimos reservar ese horario. Intenta de nuevo.');
+    it('talks about an appointment by its link, on the same origin or naming the organization', async () => {
+        vi.mocked(axiosInstance.get).mockResolvedValue({ data: { token: 't1' } });
+        vi.mocked(widgetInstance.post).mockResolvedValue({ data: { token: 't2' } });
+        await expect(fetchBookingAppointment('a.b')).resolves.toEqual({ token: 't1' });
+        expect(axiosInstance.get).toHaveBeenCalledWith('/booking/appointment/a.b');
+        await expect(cancelBookingAppointment('a.b', 'acme')).resolves.toEqual({ token: 't2' });
+        expect(widgetInstance.post).toHaveBeenCalledWith('/booking/appointment/a.b/cancel?idOrganization=acme');
+        await moveBookingAppointment('a.b', 'slot-1', 'acme');
+        expect(widgetInstance.post).toHaveBeenLastCalledWith('/booking/appointment/a.b/move?idOrganization=acme', {
+            slot: 'slot-1',
+        });
+    });
+    it('reads the edge’s { code, message } refusal, plain text, and a generic message otherwise', () => {
+        const stale = toBookingError({
+            response: { status: 403, data: { code: 'STALE_OFFER', message: 'Esa persona ya no está disponible' } },
+        });
+        expect(stale).toBeInstanceOf(BookingEdgeError);
+        expect(stale.code).toBe(BookingErrorCodes.STALE_OFFER);
+        expect(stale.status).toBe(403);
+        expect(stale.message).toBe('Esa persona ya no está disponible');
+        expect(bookingErrorMessage({ response: { status: 404, data: 'Organization not found' } })).toBe('Organization not found');
+        expect(toBookingError({ response: { status: 429, data: '' } }).code).toBe(BookingErrorCodes.RATE_LIMITED);
         expect(bookingErrorMessage(new Error('network'))).toBe('No pudimos reservar ese horario. Intenta de nuevo.');
+        expect(bookingErrorMessage(new Error('network'), 'No pudimos cargar los horarios.')).toBe('No pudimos cargar los horarios.');
+    });
+    it('gives a hold up only when the edge says so or its time ran out', () => {
+        const now = new Date('2026-10-14T15:00:00.000Z').getTime();
+        const later = '2026-10-14T15:10:00.000Z';
+        const earlier = '2026-10-14T14:59:00.000Z';
+        const refusal = (code) => new BookingEdgeError('x', code);
+        expect(holdLapsed(refusal(BookingErrorCodes.HOLD_EXPIRED), later, now)).toBe(true);
+        expect(holdLapsed(refusal(BookingErrorCodes.STALE_OFFER), later, now)).toBe(true);
+        // A network failure or a rate limit is retried on the next round, while the lock still runs.
+        expect(holdLapsed(refusal(), later, now)).toBe(false);
+        expect(holdLapsed(refusal(BookingErrorCodes.RATE_LIMITED), later, now)).toBe(false);
+        expect(holdLapsed(refusal(), earlier, now)).toBe(true);
     });
 });