sabre-client 0.4.1 → 0.5.0

package/README.es.md

@@ -12,17 +12,31 @@ SDK de TypeScript para las APIs de Sabre.
 
 ## Estado
 
-`0.4.0` es la versión actual de la reescritura. Cubre el Tier 1 y el Tier 2 del flujo de Air
-Booking por REST, y el Tier 3 (sesiones SOAP y colas). Sobre la `0.3.0` agrega `buildCredentials`
-y los comandos de host (`session.command`), sin cambios incompatibles.
+La `0.5.0` está publicada con el dist-tag `next` mientras se prueba; `latest` sigue en la `0.4.1`.
+Cubre el Tier 1 y el Tier 2 del flujo de Air Booking por REST, el Tier 3 (sesiones SOAP y colas) y
+el Tier 4: actividad de colas, historial del PNR, la cola de mensajes `S`, `selection` en `list` y
+`onRawRequest`. Trae tres cambios incompatibles (ver [Actualizar desde la 0.4](#actualizar-desde-la-04)).
 
 ```sh
-npm install sabre-client
+npm install sabre-client@next   # 0.5.0
+npm install sabre-client        # 0.4.1
 ```
 
 El paquete sigue en `0.x`: una versión minor puede traer cambios incompatibles, y el
 [CHANGELOG](./CHANGELOG.md) los marca.
 
+### Actualizar desde la 0.4
+
+- **`pcc` ya no está en la config.** Pasarlo a `new Sabre` o a `new SabreLegacy` da un error de
+  tipos, y en JavaScript se ignora. El PCC con el que te autenticas va en `credentials` (ver
+  [Credenciales](#credenciales)); otro PCC se pasa en cada operación, como `targetPcc` en REST o
+  `pcc` en las operaciones de colas.
+- **`QueueRef` puede ser un `string`.** Una cola alfabética como `'S'` es `'S'`, y `count` y
+  `place` la devuelven así en lugar de `{ name: 'S' }`. El código que hace
+  `typeof q === 'number' ? … : q.name` tiene que manejar el caso `string`.
+- **Un `QueueStep` que no terminó tiene `kind`.** Revisa `step.kind === 'pnr'` antes de leer
+  `step.item`; `kind: 'message'` trae un mensaje de la cola `S`.
+
 El Tier 1 cubre el flujo básico de Air Booking por REST:
 
 | Paso | Servicio | Método |
@@ -45,11 +59,12 @@ El Tier 3 agrega el cliente SOAP `SabreLegacy`, con una sesión stateful y Queue
 | Paso | Servicio | Método |
 | - | - | - |
 | Sesión | `SessionCreateRQ` 2.0.0 / 1.0.0, `OTA_PingRQ`, `SessionCloseRQ` | `legacy.withSession`, `legacy.openSession` |
-| Colas | Get Queue Count, Access Queue, Place Queue Message | `session.queue.count`, `list`, `access`, `ignore`, `remove`, `place`, `exit`, `process` |
-| Párrafo de cola | — (función pura) | `parseQueueParagraph`, `resolveHostDate` |
+| Colas | Get Queue Count, Get Queue Activity, Access Queue, Place Queue Message | `session.queue.count`, `activity`, `list`, `access`, `ignore`, `remove`, `place`, `exit`, `process` |
+| Párrafo de cola | — (función pura) | `parseQueueParagraph`, `parseQueuePlaceRemark`, `resolveHostDate` |
+| Historial del PNR | `TravelItineraryHistoryLLSRQ` 2.4.0 | `session.reservation.history` |
 | Comandos de host | `SabreCommandLLSRQ` 2.0.0 | `session.command` |
 
-Planeado después de `0.4.0`: Get Ancillaries (solo NDC).
+Planeado después de `0.5.0`: Get Ancillaries (solo NDC).
 
 ## Requisitos
 
@@ -88,11 +103,6 @@ const sabre = new Sabre({
 | `fetch` | `fetch` global | `fetch` propio (proxies, tests, otros runtimes) |
 | `tokenStore` | solo en memoria | Comparte el token entre procesos (ver [Reutilizar el token](#reutilizar-el-token)) |
 
-> **`pcc` está deprecado** desde la `0.4.1` y se quita en la `0.5.0`. Era un campo reservado, y
-> ningún cliente lo lee. El PCC con el que te autenticas va en `credentials` (ver
-> [Credenciales](#credenciales) y `buildCredentials`). Para trabajar en otro PCC, pásalo en cada
-> operación: `targetPcc` en REST y `pcc` en las operaciones de colas.
-
 ### Credenciales
 
 Hay **un solo juego de credenciales** para REST y SOAP: el mismo objeto `credentials` sirve para
@@ -124,7 +134,9 @@ El objeto que devuelve `buildCredentials` lleva su `authVersion`, así que la co
 repetirlo: con `authVersion: 'v2'` en `buildCredentials`, `{ environment, credentials }` ya es una
 config v2. Si también pasas `authVersion` en la config, tiene que coincidir; si no, el cliente lanza
 un `TypeError`. Las credenciales que armas a mano no llevan `authVersion`, así que con v2 la config
-sigue necesitando `authVersion: 'v2'`.
+sigue necesitando `authVersion: 'v2'`. Si la versión solo se conoce en runtime (por ejemplo, leída
+de una variable de entorno a un `BuildCredentialsOptions`), el resultado de `buildCredentials`
+también va directo a la config, sin `authVersion` en ella.
 
 El PCC de las credenciales es con el que te autenticas. Trabajar en otro PCC no requiere otro
 juego de credenciales: se pasa en cada operación, como `targetPcc` en `booking.create`, `get` y
@@ -361,6 +373,7 @@ const screen = await legacy.withSession((session) => session.command('W/PT¥*',
 // screen.text      → 'PSGR TYPE - ON' (como lo manda Sabre, sin recortar)
 // screen.warnings  → los stl:Warning, si los hay
 // screen.messageId → eb:MessageId, para soporte de Sabre
+// screen.respondedAt → eb:Timestamp en UTC, p. ej. '2026-11-06T17:34:16Z'
 ```
 
 - **El comando va tal cual.** En este servicio, el separador `‡` de Sabre se escribe `¥`
@@ -388,16 +401,63 @@ const screen = await legacy.withSession((session) => session.command('W/PT¥*',
   caracteres (`W/PT`, `DC`, `*IM`), nunca el comando entero ni la pantalla. La respuesta completa
   está disponible en `onRawResponse`.
 
+### Historial del PNR
+
+`session.reservation.history(locator, options?)` lee el historial del PNR (Get Itinerary History,
+`TravelItineraryHistoryLLSRQ` 2.4.0, el `*H` del host), una entrada por transacción:
+
+```ts
+const { transactions } = await legacy.withSession((session) => session.reservation.history('ABC123'));
+// transactions[0] → { rph, createdAt: '2026-11-04T17:15', agent, agentDutyCode, pcc, aaaPcc,
+//                     receivedFrom, flightSegments, generalInfo, remarks, accounting }
+```
+
+- **Quién, cuándo y desde dónde**: `createdAt` (con año, sin zona horaria), el sine y el duty code
+  del agente, el `pcc` de la firma, el `aaaPcc` del AAA y `receivedFrom`.
+- **Qué cambió, con su `action`**: `flightSegments` con su estado en ese momento (`AS` alta, `XS`
+  baja; fechas sin año, como las manda el host), y SSR, ticketing, teléfonos, nombres y emails como
+  texto en `generalInfo` (`A4S`, `A7`, `A9`, `AN`, `APE`…). Sabre no publica la lista de valores de
+  `action`. Asientos, autos, hoteles, tren, seguros y facturas no se tipan: quedan en la respuesta
+  cruda (`onRawResponse`).
+- **Trae datos del pasajero** (nombres, teléfonos, emails). El SDK nunca los manda al log.
+- **No registra las colocaciones en cola**, ni las del sistema ni un `place` manual (CERT): para eso están
+  `queue.list`/`access` o los remarks `QUEUE_PLACE` de Get Booking.
+- **Llámalo fuera de un recorrido de cola.** Dentro de una cola, Sabre rechaza el historial de otro
+  PNR con `NAK6 -NOT ALLOWED- FINISH OR IGNORE OTHER ACTIVITY`, un `SabreBusinessError` (CERT). El
+  PNR del AAA no cambia, `queue.state` sigue en `'inside'` y el recorrido sigue con `ignore`.
+- Es una lectura: se reintenta. Un `locator` que no es de 6 caracteres alfanuméricos en mayúscula
+  lanza un `TypeError` sin llamar a la red. Un PNR que no existe lanza un `SabreBusinessError`
+  (`service: 'itineraryHistory'`).
+
 ### Colas
 
 Las operaciones de cola están en `session.queue`. `pcc` es opcional en cada llamada, y por defecto
-es el de la sesión. Una cola es un número de 0 a 511, o `{ name }` para las colas alfabéticas
-(`QueueRef`). Las colas que devuelve `count` se pasan tal cual a las demás operaciones.
+es el de la sesión. Una cola (`QueueRef`) tiene tres formas:
+
+| Cola | `QueueRef` | Viaja como |
+| - | - | - |
+| Numérica, de 0 a 511 | `400` | `Number="400"` |
+| Alfabética, una o dos letras mayúsculas | `'S'` | `Number="S"` |
+| Con nombre (tablas QN y QNB) | `{ name: 'HOTELS' }` | `Name="HOTELS"` |
+
+Las colas que devuelve `count` se pasan tal cual a las demás operaciones. `'S'` es la **cola de
+mensajes** del PCC: tiene mensajes y no PNR, y Sabre no la lista, así que `list({ queue: 'S' })`
+lanza un `TypeError` sin llamar a Sabre. Se recorre a mano: `access({ queue: 'S' })` devuelve el
+primer mensaje (`kind: 'message'`) e `ignore()` el siguiente, sin sacarlo de la cola. `process` y
+`place` dentro de la `S` lanzan un `TypeError` sin llamar a Sabre. `remove()` manda `QR`, pero
+todavía no hay evidencia de qué hace Sabre con el mensaje.
+
+> **Migración desde la 0.4.x**: `count` devolvía la cola `S` como `{ name: 'S' }`, que Sabre
+> rechaza (`INVALID QUEUE NAME FORMAT`). Ahora devuelve `'S'`. Un código como
+> `typeof q === 'number' ? … : q.name` deja de compilar, porque `q` puede ser un `string`. Un
+> `{ name }` de una o dos letras mayúsculas ahora lanza un `TypeError` que pide pasar la letra, y
+> `'12'` o `'s'` también lanzan: cada cola tiene una sola forma.
 
 | Método | Servicio de Sabre | Devuelve |
 | - | - | - |
 | `count({ pcc? })` | `QueueCountLLSRQ` | `{ queues: [{ queue, count }], totals, countedAt, warnings }` |
-| `list({ queue, pcc?, primaryPassenger? })` | `QueueAccessLLSRQ` (`List`) | `{ locators, entries, paragraph, warnings }`, sin entrar a la cola |
+| `activity({ pcc? })` | `QueueAnalysisLLSRQ` | `{ queues: [{ queue, numMessages, ended, ignored, … }], totals, analyzedAt, warnings }` |
+| `list({ queue, pcc?, primaryPassenger?, selection? })` | `QueueAccessLLSRQ` (`List`) | `{ locators, entries, paragraph, warnings }`, sin entrar a la cola |
 | `access({ queue, pcc?, selection? })` | `QueueAccessLLSRQ` | `QueueStep` |
 | `ignore()` | `QueueAccessLLSRQ` (`I`) | `QueueStep` |
 | `remove({ from? })` | `QueueAccessLLSRQ` (`QR`) | `QueueStep` |
@@ -406,10 +466,30 @@ es el de la sesión. Una cola es un número de 0 a 511, o `{ name }` para las co
 
 ```ts
 type QueueStep =
-  | { done: false; item: QueueItem; warnings: SabreWarning[] }
+  | { done: false; kind: 'pnr'; item: QueueItem; warnings: SabreWarning[] }
+  | { done: false; kind: 'message'; message: { text: string[] }; warnings: SabreWarning[] } // cola 'S'
   | { done: true; reason: 'end-of-display' | 'empty'; message: string; warnings: SabreWarning[] };
 ```
 
+> **Migración desde la 0.4.x**: un paso que no terminó ahora trae `kind`. Comprueba
+> `step.kind === 'pnr'` antes de leer `step.item`. Solo la cola `S` devuelve `kind: 'message'`.
+
+- **`list` devuelve la cola entera en una respuesta**: no pagina, ni con más de 1000 PNR (1221 en
+  unos 279 KB, en producción). `selection` la acota, pero en la lista Sabre solo acepta `QD`
+  (fecha de colocación en la cola, p. ej. `{ function: 'QD', criteria: '05NOV' }`) o `AK` (el
+  agente que lo colocó, PCC más firma, p. ej. `'PCC1AAT'`; todavía no se probó en la lista). Otro
+  código lanza `TypeError` sin llamar a Sabre. El `placedAt` de una entrada de la lista es cuándo
+  se colocó el PNR en la cola, la fecha por la que filtra `QD`.
+- **`activity`** devuelve, por cola, los ocho contadores de la pantalla `QA` del host:
+  `numMessages` (los que están hoy en la cola), `ended`, `ignored`, `moved`, `removed`,
+  `transferred`, `leftMessageToContact` y `unableToReach`, más `totals` para el PCC. Sabre lista
+  también colas vacías con contadores. Ninguna fuente dice desde cuándo cuentan, así que el SDK los
+  devuelve tal cual. Como `count`, es una lectura: se reintenta, funciona dentro o fuera de una
+  cola y no pide duty code 9.
+- **Cada resultado de colas trae `respondedAt`**: el `eb:Timestamp` de Sabre, en ISO 8601 UTC
+  (`'2026-11-06T17:34:16Z'`). A diferencia de `countedAt` y `placedAt`, que llegan como los manda
+  el host (sin año y en hora local del PCC), trae año y zona. Solo falta si Sabre no lo manda.
+
 - **El fin de cola es un resultado, no un error.** `END OF DISPLAY FOR REQUESTED DATA` da
   `{ done: true, reason: 'end-of-display' }`, y una cola vacía (`QUEUE SELECTED WAS EMPTY`) da
   `reason: 'empty'`. En los dos casos la sesión queda fuera de la cola. Cualquier otro error de
@@ -430,7 +510,9 @@ type QueueStep =
   0–191 o 200–254. Producción rechaza un `place` sin PIC, aunque el design lo dé como opcional.
 - **`QueueItem`** trae `locator`, el `placedAt` y el `placedBy` de `Line`, `primaryPassenger` y
   `group` cuando Sabre los manda, y `paragraph`: el PNR en formato de host, línea por línea y
-  sin tocar. `placedAt` es el texto que llegó, con o sin año. `resolveHostDate` lo convierte en una
+  sin tocar. `placedAt` es el texto que llegó, con o sin año. Dentro de una cola es la última
+  modificación del PNR, no su colocación en la cola: esa es el `placedAt` de `list`, y para un
+  mismo PNR no coinciden. `resolveHostDate` lo convierte en una
   fecha completa.
 - `count` dentro de una cola no cuenta el PNR que está en pantalla.
 
@@ -472,6 +554,19 @@ segmentos con su estado, el campo de ticketing con una marca `issued` y la líne
 - No lee los plazos que las aerolíneas escriben como texto libre en remarks, SSR u OSI. Su formato
   lo pone cada aerolínea. El texto sigue en `paragraph`.
 
+### Leer un remark `QUEUE_PLACE`
+
+Get Booking devuelve dónde se colocó el PNR como un remark con `type: 'QUEUE_PLACE'`. Su `text`
+junta el PCC, la fecha, la cola y el PIC sin separadores. `parseQueuePlaceRemark(text)` lo separa:
+
+```ts
+parseQueuePlaceRemark('MEX25SEP146/015'); // { pcc: 'MEX', date: '25SEP', queue: 146, pic: 15 }
+```
+
+Devuelve `null` si el texto no tiene esa forma, o si el día, el mes, la cola (0–511) o el PIC
+(0–191, 200–254) están fuera de rango. `date` viene sin año: se resuelve con
+`resolveHostDate(date, referenceDate)`. Leer los remarks de la reserva le toca al consumidor.
+
 ### Probar tu lógica de colas: `sabre-client/testing`
 
 `sabre-client/testing` es una entrada aparte, con un fake de las sesiones y las colas de Sabre. No
@@ -503,16 +598,68 @@ fake.openSessions; // 0: la sesión se cerró
   `{ locator, paragraph?, placedAt?, placedBy?, primaryPassenger? }`. A un párrafo sin línea de
   firma se le agrega una sintética. `pnrs` agrega PNR que no están en ninguna cola, para
   `place({ locators })`. El fake no tiene AAA: fuera de una cola, `place` necesita `locators`.
+- `queues['S']` es la cola de mensajes: cada elemento es el texto de un mensaje (`string[]`), no
+  un PNR. `access` lo muestra sin `Line`, como Sabre, y `fake.messages()` da los que quedan. Que
+  `remove` saque el mensaje es un supuesto del fake, no se probó con Sabre.
+- `queue.activity`: `numMessages` sale de las colas del fake (sin el PNR en pantalla, como en
+  `count`, igual que CERT). Los otros siete contadores valen 0, salvo que los siembres con
+  `activity: { '9': { ignored: 27 } }`. Las acciones del fake **no** los cambian: nadie probó qué
+  contador sube Sabre con cada acción.
+- `reservation.history`: `histories: { AAAAAA: [transacciones] }` fija lo que devuelve cada PNR,
+  con la forma de `ReservationHistoryTransaction` (las listas que falten llegan vacías). Un PNR que
+  el fake conoce sin historial sembrado devuelve una transacción sintética (su creación), y un
+  localizador desconocido da un error de host marcado como no simulado. Dentro de una cola, el
+  historial de otro PNR se rechaza con `NAK6 -NOT ALLOWED- FINISH OR IGNORE OTHER ACTIVITY` y el del
+  PNR en pantalla se devuelve, como en CERT.
 - Responde como producción: colas vacías, el fin de cola, `place` que mueve el PNR, el PIC
   obligatorio y una sesión vencida con `fake.expireSessions()`. `fake.calls` lista lo que pidió el
   SDK.
 - **No simula** los PCC (las colas son las mismas para cualquier `pcc`) ni `selection`, que recibe
-  un error en vez de la cola entera.
+  un error en vez de la cola entera, en `access` y en `list`.
 - `queueFixtures` trae las respuestas anonimizadas que se grabaron en producción (`walk`,
-  `emptyQueue`, `place`…), como `{ operation, status, body }`.
+  `emptyQueue`, `place`…), como `{ operation, status, body }`. Cada una tiene sus propios alias de
+  localizador (`walk`: `AAAAAA`–`AAAAAD`, `place`: `AAAAAE`–`AAAAAF`,
+  `placeWithoutInstructionCodeInside`: `AAAAAG`–`AAAAAH`), y sus líneas de firma conservan la
+  forma (`… <alias> H`).
+- `queueFakePnrs(fixture)` convierte una grabación en los PNR del fake: primero los de `list`, en
+  orden, con su `Line`, y el párrafo que mostró `access`, `ignore`, `remove` o `place` para cada
+  uno. La cola la eliges tú, y puedes juntar fixtures:
+
+  ```ts
+  const fake = createQueueFake({
+    queues: { '9': queueFakePnrs(queueFixtures.walk), '50': [] },
+    pnrs: queueFakePnrs(queueFixtures.place),
+  });
+  ```
 
 `examples/queue-review.mjs` es un ejemplo completo, y su test lo corre contra el fake.
 
+#### Anonimizar respuestas grabadas
+
+`createAnonymizer` aplica la regla con la que se grabaron las fixtures del SDK, para guardar las
+respuestas de Sabre (por ejemplo, las de `onRawResponse`) sin datos de pasajeros:
+
+```ts
+import { createAnonymizer } from 'sabre-client/testing';
+
+const anonymizer = createAnonymizer({ secrets: [pcc, username] });
+const safe = anonymizer.anonymize(raw.body); // un sobre SOAP entero
+anonymizer.maskParagraph(item.paragraph); // líneas en formato de host
+if (anonymizer.leaks(safe).length > 0) throw new Error('quedan datos reales');
+```
+
+- Cada localizador recibe un alias (`AAAAAA`, `AAAAAB`…), el mismo en todos los lugares donde
+  aparece, también en los textos que pasen después por el mismo anonimizador. `PassengerName` pasa
+  a `PASAJERO/UNO`, `Group` a `GRUPO`, `AgentSine` a `AAA` (salvo `SABRE`), `PseudoCityCode` a
+  `XXXX`, `LNIATA` a `XXXXXX` y cada `secret` a `XXXX`.
+- En las líneas en formato de host (`<Text>`, o `maskLine` y `maskParagraph`), solo quedan tal cual
+  las de una lista blanca (`isSafeHostLine`: líneas vacías, avisos PIC como `011  SEE REMARKS`,
+  títulos de sección, el fin de cola). En las demás, las letras pasan a `X` y los dígitos a `9`. La
+  línea de firma conserva su forma, y su localizador solo si ya es un alias.
+- `leaks(text)` lista los datos reales que siguen en `text` (`'secreto'`, `'localizador'`,
+  `'nombre'`, `'línea del PNR'`, `'token'`): úsalo antes de escribir un archivo.
+- Usa un anonimizador por grabación. Es una regla, no una garantía: revisa lo que guardas.
+
 ## Manejo de errores
 
 Todos los errores que lanza el SDK extienden `SabreError`:
@@ -583,6 +730,39 @@ En `SabreLegacy`, `protocol` es `'soap'`, `body` es el sobre SOAP completo, y `o
 > `body` es la respuesta cruda y **trae datos de pasajeros**. El SDK nunca lo manda al logger.
 > Dónde lo guardas es tu responsabilidad.
 
+## Request crudo
+
+Las mismas operaciones aceptan `onRawRequest`, al lado de `onRawResponse`. Recibe lo que el SDK
+mandó por la red, por ejemplo para mostrar el request real junto a la respuesta:
+
+```ts
+import type { SabreRawRequest } from 'sabre-client';
+
+let sent: SabreRawRequest | undefined;
+await sabre.booking.get({ confirmationId }, { onRawRequest: (r) => (sent = r) });
+// sent: { operation: 'booking.get', protocol: 'rest', method, url, headers, body, attempts }
+```
+
+- `operation` es el mismo valor que recibe `onRawResponse`. `url` es la URL completa, con su query
+  string. `headers` son los que se mandaron, **sin `Authorization`** (se quita el header entero).
+  `body` es el texto que se mandó, o `undefined` si no hubo. En REST va tal cual; en
+  `SabreLegacy` es el sobre SOAP completo con el `BinarySecurityToken` reemplazado por
+  `[REDACTED]`, igual que en la respuesta.
+- Se llama **una vez**, con el último intento que se mandó, antes de que la operación devuelva o
+  lance y antes que `onRawResponse`. A diferencia de este, se llama también si ningún intento tuvo
+  respuesta HTTP (error de red, abort), siempre que se haya mandado al menos uno. No se llama si la
+  operación lanza antes de mandar nada (por ejemplo, un `TypeError` de validación).
+- En SOAP, `eb:MessageId` y `eb:Timestamp` son nuevos en cada intento, así que el sobre que llega
+  es el del último intento.
+- No se llama con la autenticación: el request de token de OAuth, `openSession`
+  (`SessionCreateRQ`, cuyo sobre lleva la contraseña del EPR) y `close` (`SessionCloseRQ`).
+- Es síncrono y su retorno se ignora. Si lanza, el SDK registra
+  `sabre.request.rawRequestHookFailed` sin el body y la operación sigue.
+
+> [!WARNING]
+> `body` y `url` **traen datos de pasajeros** (localizadores, nombres, contactos). El SDK nunca los
+> manda al logger. Dónde los guardas es tu responsabilidad.
+
 ## Reintentos
 
 Solo se reintentan las operaciones idempotentes: Bargain Finder Max y Revalidate Itinerary
@@ -638,7 +818,8 @@ const sabre = new Sabre({
 ```
 
 El SDK registra eventos estructurados (`sabre.request.start`, `sabre.request.end`,
-`sabre.request.retry`, `sabre.request.rawResponseHookFailed`, `sabre.auth.token.refresh`,
+`sabre.request.retry`, `sabre.request.rawResponseHookFailed`,
+`sabre.request.rawRequestHookFailed`, `sabre.auth.token.refresh`,
 `sabre.auth.token.store`, `sabre.booking.seat.priced`, `sabre.session.open`,
 `sabre.session.close`, `sabre.session.closeFailed`, `sabre.session.keepAliveFailed`,
 `sabre.session.command`, `sabre.queue.exitTolerated`, `sabre.queue.exitFailed`) y nunca los bodies