sabre-client 0.4.1 → 0.5.0

package/README.md

@@ -12,17 +12,31 @@ TypeScript SDK for the Sabre APIs.
 
 ## Status
 
-`0.4.0` is the current release of the rewrite. It covers Tier 1 and Tier 2 of the Air Booking
-flow over REST, and Tier 3 (SOAP sessions and queues). It adds `buildCredentials` and host
-commands (`session.command`) to `0.3.0`, with no breaking changes.
+`0.5.0` is published under the `next` dist-tag while it is tested; `latest` stays on `0.4.1`.
+It covers Tier 1 and Tier 2 of the Air Booking flow over REST, Tier 3 (SOAP sessions and queues)
+and Tier 4: queue activity, PNR history, the `S` message queue, `selection` in `list` and
+`onRawRequest`. It has three breaking changes (see [Upgrading from 0.4](#upgrading-from-04)).
 
 ```sh
-npm install sabre-client
+npm install sabre-client@next   # 0.5.0
+npm install sabre-client        # 0.4.1
 ```
 
 The package is still `0.x`: a minor version may include breaking changes, and the
 [CHANGELOG](./CHANGELOG.md) marks them.
 
+### Upgrading from 0.4
+
+- **`pcc` is no longer in the config.** Passing it to `new Sabre` or `new SabreLegacy` is a type
+  error, and in JavaScript it is ignored. The PCC you authenticate with goes in `credentials`
+  (see [Credentials](#credentials)); another PCC goes per operation, as `targetPcc` in REST or
+  `pcc` in the queue operations.
+- **`QueueRef` can be a `string`.** An alphabetic queue like `'S'` is `'S'`, and `count` and
+  `place` return it that way instead of `{ name: 'S' }`. Code that does
+  `typeof q === 'number' ? … : q.name` must handle the `string` case.
+- **A `QueueStep` that is not done has a `kind`.** Check `step.kind === 'pnr'` before reading
+  `step.item`; `kind: 'message'` carries a message of the `S` queue.
+
 Tier 1 covers the core Air Booking flow over REST:
 
 | Step | Service | Method |
@@ -45,11 +59,12 @@ Tier 3 adds the `SabreLegacy` SOAP client, with a stateful session and Queue Man
 | Step | Service | Method |
 | - | - | - |
 | Session | `SessionCreateRQ` 2.0.0 / 1.0.0, `OTA_PingRQ`, `SessionCloseRQ` | `legacy.withSession`, `legacy.openSession` |
-| Queues | Get Queue Count, Access Queue, Place Queue Message | `session.queue.count`, `list`, `access`, `ignore`, `remove`, `place`, `exit`, `process` |
-| Queue paragraph | — (pure function) | `parseQueueParagraph`, `resolveHostDate` |
+| Queues | Get Queue Count, Get Queue Activity, Access Queue, Place Queue Message | `session.queue.count`, `activity`, `list`, `access`, `ignore`, `remove`, `place`, `exit`, `process` |
+| Queue paragraph | — (pure function) | `parseQueueParagraph`, `parseQueuePlaceRemark`, `resolveHostDate` |
+| PNR history | `TravelItineraryHistoryLLSRQ` 2.4.0 | `session.reservation.history` |
 | Host commands | `SabreCommandLLSRQ` 2.0.0 | `session.command` |
 
-Planned after `0.4.0`: Get Ancillaries (NDC only).
+Planned after `0.5.0`: Get Ancillaries (NDC only).
 
 ## Requirements
 
@@ -88,11 +103,6 @@ const sabre = new Sabre({
 | `fetch` | global `fetch` | Custom `fetch` (proxies, tests, other runtimes) |
 | `tokenStore` | in-memory only | Shares the token between processes (see [Token reuse](#token-reuse)) |
 
-> **`pcc` is deprecated** since `0.4.1` and will be removed in `0.5.0`. It was a reserved field,
-> and no client reads it. The PCC you authenticate with goes in `credentials` (see
-> [Credentials](#credentials) and `buildCredentials`). To work in another PCC, pass it per
-> operation: `targetPcc` in REST, `pcc` in the queue operations.
-
 ### Credentials
 
 There is **one set of credentials** for REST and SOAP: the same `credentials` object works for
@@ -124,7 +134,9 @@ The object that `buildCredentials` returns carries its `authVersion`, so the con
 need to repeat it: with `authVersion: 'v2'` in `buildCredentials`, `{ environment, credentials }`
 is already a v2 config. If you pass `authVersion` in the config too, it must match, or the client
 throws a `TypeError`. Credentials you build by hand have no `authVersion`, so with v2 the config
-still needs `authVersion: 'v2'`.
+still needs `authVersion: 'v2'`. If the version is only known at runtime (for example, read
+from an environment variable into a `BuildCredentialsOptions`), the result of `buildCredentials`
+can still go straight into the config, with no `authVersion` there.
 
 The PCC in the credentials is the one you authenticate with. Working in another PCC is not a
 second set of credentials: pass it per operation, as `targetPcc` in `booking.create`, `get` and
@@ -360,6 +372,7 @@ const screen = await legacy.withSession((session) => session.command('W/PT¥*',
 // screen.text      → 'PSGR TYPE - ON' (as Sabre sends it, not trimmed)
 // screen.warnings  → the stl:Warning entries, if any
 // screen.messageId → eb:MessageId, for Sabre support
+// screen.respondedAt → eb:Timestamp in UTC, e.g. '2026-11-06T17:34:16Z'
 ```
 
 - **The command is sent as is.** In this service Sabre's `‡` separator is written `¥`
@@ -384,16 +397,63 @@ const screen = await legacy.withSession((session) => session.command('W/PT¥*',
   characters (`W/PT`, `DC`, `*IM`), never the whole command or the screen. The full response is
   available through `onRawResponse`.
 
+### PNR history
+
+`session.reservation.history(locator, options?)` reads the PNR history (Get Itinerary History,
+`TravelItineraryHistoryLLSRQ` 2.4.0, the host's `*H`), one entry per transaction:
+
+```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 }
+```
+
+- **Who, when and from where**: `createdAt` (with a year, no time zone), the agent's sine and duty
+  code, the signing `pcc`, the AAA's `aaaPcc` and `receivedFrom`.
+- **What changed, with its `action`**: `flightSegments` with their status at that moment
+  (`AS` added, `XS` cancelled; dates without a year, as the host sends them), and SSR, ticketing,
+  phones, names and emails as text in `generalInfo` (`A4S`, `A7`, `A9`, `AN`, `APE`…). Sabre does
+  not publish the list of `action` values. Seats, cars, hotels, rail, insurance and invoices are
+  not typed: they stay in the raw response (`onRawResponse`).
+- **It carries passenger data** (names, phones, emails). The SDK never logs it.
+- **It does not record queue placements**, neither the system's nor a manual `place` (CERT): for that, use
+  `queue.list`/`access` or the `QUEUE_PLACE` remarks of Get Booking.
+- **Call it outside a queue walk.** Inside a queue, Sabre rejects the history of another PNR with
+  `NAK6 -NOT ALLOWED- FINISH OR IGNORE OTHER ACTIVITY`, a `SabreBusinessError` (CERT). The PNR in
+  the AAA does not change, `queue.state` stays `'inside'`, and the walk goes on with `ignore`.
+- It is a read: it is retried. A `locator` that is not 6 uppercase alphanumeric characters throws a
+  `TypeError` without calling the network. A PNR that does not exist throws a `SabreBusinessError`
+  (`service: 'itineraryHistory'`).
+
 ### Queues
 
 The queue operations live in `session.queue`. `pcc` is optional in every call and defaults to the
-session's PCC. A queue is a number from 0 to 511 or `{ name }` for alphabetic queues
-(`QueueRef`). The queues returned by `count` can be passed straight to the other operations.
+session's PCC. A queue (`QueueRef`) comes in three forms:
+
+| Queue | `QueueRef` | Sent as |
+| - | - | - |
+| Numeric, 0 to 511 | `400` | `Number="400"` |
+| Alphabetic, one or two uppercase letters | `'S'` | `Number="S"` |
+| Named (QN and QNB tables) | `{ name: 'HOTELS' }` | `Name="HOTELS"` |
+
+The queues returned by `count` can be passed straight to the other operations. `'S'` is the PCC's
+**message queue**: it holds messages, not PNRs, and Sabre does not list it, so `list({ queue: 'S' })`
+throws a `TypeError` without calling Sabre. Walk it by hand: `access({ queue: 'S' })` returns the
+first message (`kind: 'message'`) and `ignore()` the next one, leaving it in the queue. `process`
+and `place` inside `S` throw a `TypeError` without calling Sabre. `remove()` sends `QR`, but there
+is no evidence yet of what Sabre does with the message.
+
+> **Migrating from 0.4.x**: `count` used to return the `S` queue as `{ name: 'S' }`, which Sabre
+> rejects (`INVALID QUEUE NAME FORMAT`). It now returns `'S'`. Code that does
+> `typeof q === 'number' ? … : q.name` no longer compiles, because `q` can be a `string`. A
+> `{ name }` of one or two uppercase letters now throws a `TypeError` that tells you to pass the
+> letter instead, and `'12'` or `'s'` throw too: each queue has a single form.
 
 | Method | Sabre service | Returns |
 | - | - | - |
 | `count({ pcc? })` | `QueueCountLLSRQ` | `{ queues: [{ queue, count }], totals, countedAt, warnings }` |
-| `list({ queue, pcc?, primaryPassenger? })` | `QueueAccessLLSRQ` (`List`) | `{ locators, entries, paragraph, warnings }`, without entering the queue |
+| `activity({ pcc? })` | `QueueAnalysisLLSRQ` | `{ queues: [{ queue, numMessages, ended, ignored, … }], totals, analyzedAt, warnings }` |
+| `list({ queue, pcc?, primaryPassenger?, selection? })` | `QueueAccessLLSRQ` (`List`) | `{ locators, entries, paragraph, warnings }`, without entering the queue |
 | `access({ queue, pcc?, selection? })` | `QueueAccessLLSRQ` | `QueueStep` |
 | `ignore()` | `QueueAccessLLSRQ` (`I`) | `QueueStep` |
 | `remove({ from? })` | `QueueAccessLLSRQ` (`QR`) | `QueueStep` |
@@ -402,10 +462,30 @@ session's PCC. A queue is a number from 0 to 511 or `{ name }` for alphabetic qu
 
 ```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[] } // queue 'S'
   | { done: true; reason: 'end-of-display' | 'empty'; message: string; warnings: SabreWarning[] };
 ```
 
+> **Migrating from 0.4.x**: a step that is not done now has a `kind`. Check `step.kind === 'pnr'`
+> before reading `step.item`. Only the `S` queue returns `kind: 'message'`.
+
+- **`list` returns the whole queue in one response**: there is no paging, even with more than 1000
+  PNRs (1221 in about 279 KB, in production). `selection` narrows it, but in the list Sabre only
+  accepts `QD` (date placed on the queue, e.g. `{ function: 'QD', criteria: '05NOV' }`) or `AK`
+  (the agent who placed it, PCC plus sine, e.g. `'PCC1AAT'`; not tested in the list yet).
+  Any other code throws a `TypeError` without calling Sabre. The `placedAt` of a list entry is
+  when the PNR was placed on the queue, the date `QD` filters on.
+- **`activity`** returns, per queue, the eight counters of the host's `QA` screen: `numMessages`
+  (on the queue now), `ended`, `ignored`, `moved`, `removed`, `transferred`,
+  `leftMessageToContact` and `unableToReach`, plus `totals` for the PCC. Sabre also lists empty
+  queues that have counters. No source says since when the counters run, so the SDK returns them
+  as they come. Like `count`, it is a read: it is retried, it works inside or outside a queue, and
+  it does not need duty code 9.
+- **Every queue result carries `respondedAt`**: Sabre's `eb:Timestamp`, in ISO 8601 UTC
+  (`'2026-11-06T17:34:16Z'`). Unlike `countedAt` and `placedAt`, which come as the host sends them
+  (no year, PCC local time), it has a year and a zone. It is missing only if Sabre does not send it.
+
 - **The end of the queue is a result, not an error.** `END OF DISPLAY FOR REQUESTED DATA` gives
   `{ done: true, reason: 'end-of-display' }`, and an empty queue (`QUEUE SELECTED WAS EMPTY`)
   gives `reason: 'empty'`. In both cases the session is left outside the queue. Any other Sabre
@@ -425,7 +505,9 @@ type QueueStep =
   Production rejects a `place` without it, although the design says it is optional.
 - **`QueueItem`** has `locator`, the `placedAt` and `placedBy` of `Line`, `primaryPassenger` and
   `group` when Sabre sends them, and `paragraph`: the PNR in host format, line by line and
-  untouched. `placedAt` is the text that arrived, with or without the year. `resolveHostDate`
+  untouched. `placedAt` is the text that arrived, with or without the year. Inside a queue it is
+  the PNR's last change, not when it was placed on the queue: that one is the `placedAt` of
+  `list`, and the two differ for the same PNR. `resolveHostDate`
   turns it into a full date.
 - `count` inside a queue does not count the PNR on screen.
 
@@ -466,6 +548,20 @@ segments with their status, the ticketing field with an `issued` flag, and the r
 - It does not read deadlines that airlines write as free text in remarks, SSR or OSI. Their format
   belongs to each airline. The text is still in `paragraph`.
 
+### Reading a `QUEUE_PLACE` remark
+
+Get Booking returns where the PNR was placed as a remark with `type: 'QUEUE_PLACE'`. Its `text`
+packs the PCC, the date, the queue and the PIC with no separators. `parseQueuePlaceRemark(text)`
+splits it:
+
+```ts
+parseQueuePlaceRemark('MEX25SEP146/015'); // { pcc: 'MEX', date: '25SEP', queue: 146, pic: 15 }
+```
+
+It returns `null` if the text does not have that shape, or if the day, month, queue (0–511) or PIC
+(0–191, 200–254) are out of range. `date` has no year: resolve it with
+`resolveHostDate(date, referenceDate)`. Reading the remarks from the booking is up to you.
+
 ### Testing your queue logic: `sabre-client/testing`
 
 `sabre-client/testing` is a separate entry point with a fake of Sabre's sessions and queues. It is
@@ -496,16 +592,67 @@ fake.openSessions; // 0: the session was closed
   `{ locator, paragraph?, placedAt?, placedBy?, primaryPassenger? }`. A paragraph without a
   signature line gets a synthetic one. `pnrs` adds PNRs that are not in any queue, for
   `place({ locators })`. The fake has no AAA: outside a queue, `place` needs `locators`.
+- `queues['S']` is the message queue: each item is a message's text (`string[]`), not a PNR.
+  `access` shows it without `Line`, as Sabre does, and `fake.messages()` lists the ones left.
+  That `remove` takes a message out is an assumption of the fake, not tested against Sabre.
+- `queue.activity`: `numMessages` comes from the fake's queues (without the PNR on screen, as in
+  `count`, as CERT does). The other seven counters are 0 unless you seed them with
+  `activity: { '9': { ignored: 27 } }`. The fake's actions do **not** change them: no one has
+  tested which counter Sabre raises for each action.
+- `reservation.history`: `histories: { AAAAAA: [transactions] }` sets what each PNR returns, in
+  the shape of `ReservationHistoryTransaction` (missing lists come back empty). A PNR the fake
+  knows without a seeded history returns one synthetic transaction (its creation), and an unknown
+  locator gives a host error marked as not simulated. Inside a queue, the history of another PNR
+  is rejected with `NAK6 -NOT ALLOWED- FINISH OR IGNORE OTHER ACTIVITY` and the one on screen is
+  returned, as in CERT.
 - It answers like production: empty queues, the end of the queue, `place` moving the PNR, the
   required PIC, and an expired session with `fake.expireSessions()`. `fake.calls` lists what the
   SDK asked for.
 - **Not simulated**: PCCs (the queues are the same for any `pcc`) and `selection`, which gets an
-  error instead of the whole queue.
+  error instead of the whole queue, in `access` and in `list`.
 - `queueFixtures` holds the anonymized responses recorded in production (`walk`, `emptyQueue`,
-  `place`, …), as `{ operation, status, body }`.
+  `place`, …), as `{ operation, status, body }`. Each one has its own locator aliases (`walk`:
+  `AAAAAA`–`AAAAAD`, `place`: `AAAAAE`–`AAAAAF`, `placeWithoutInstructionCodeInside`:
+  `AAAAAG`–`AAAAAH`), and their signature lines keep their shape (`… <alias> H`).
+- `queueFakePnrs(fixture)` turns a recording into the fake's PNRs: those of `list` first, in
+  order, with their `Line`, and the paragraph `access`, `ignore`, `remove` or `place` showed for
+  each one. You choose the queue, and you can mix fixtures:
+
+  ```ts
+  const fake = createQueueFake({
+    queues: { '9': queueFakePnrs(queueFixtures.walk), '50': [] },
+    pnrs: queueFakePnrs(queueFixtures.place),
+  });
+  ```
 
 `examples/queue-review.mjs` is a full example, and its test runs it against the fake.
 
+#### Anonymizing recorded responses
+
+`createAnonymizer` applies the rule the SDK's fixtures were recorded with, so you can store
+Sabre's responses (for example from `onRawResponse`) without passenger data:
+
+```ts
+import { createAnonymizer } from 'sabre-client/testing';
+
+const anonymizer = createAnonymizer({ secrets: [pcc, username] });
+const safe = anonymizer.anonymize(raw.body); // a whole SOAP envelope
+anonymizer.maskParagraph(item.paragraph); // host-format lines
+if (anonymizer.leaks(safe).length > 0) throw new Error('real data left');
+```
+
+- Each locator gets an alias (`AAAAAA`, `AAAAAB`…), the same one everywhere it appears, also in
+  later texts passed to the same anonymizer. `PassengerName` becomes `PASAJERO/UNO`, `Group`
+  becomes `GRUPO`, `AgentSine` becomes `AAA` (except `SABRE`), `PseudoCityCode` becomes `XXXX`,
+  `LNIATA` becomes `XXXXXX`, and each `secret` becomes `XXXX`.
+- In host-format lines (`<Text>`, or `maskLine` and `maskParagraph`), only the lines of a
+  whitelist stay as they are (`isSafeHostLine`: empty lines, PIC notices like `011  SEE REMARKS`,
+  section titles, the end of the queue). In the others, letters become `X` and digits `9`. The
+  signature line keeps its shape, and its locator only if it is already an alias.
+- `leaks(text)` lists the real data still in `text` (`'secreto'`, `'localizador'`, `'nombre'`,
+  `'línea del PNR'`, `'token'`): use it before writing a file.
+- Use one anonymizer per recording. It is a rule, not a guarantee: check what you store.
+
 ## Error handling
 
 Every error thrown by the SDK extends `SabreError`:
@@ -576,6 +723,39 @@ In `SabreLegacy`, `protocol` is `'soap'`, `body` is the whole SOAP envelope, and
 > `body` is the raw response and **contains passenger data**. The SDK never sends it to the
 > logger. Where you store it is up to you.
 
+## Raw request
+
+The same operations accept `onRawRequest`, next to `onRawResponse`. It receives what the SDK sent
+over the network, for example to show the real request next to the response:
+
+```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` is the same value `onRawResponse` gets. `url` is the full URL, with its query
+  string. `headers` are the ones sent, **without `Authorization`** (the whole header is dropped).
+  `body` is the text sent, or `undefined` if there was none. In REST it is untouched; in
+  `SabreLegacy` it is the whole SOAP envelope with the `BinarySecurityToken` replaced by
+  `[REDACTED]`, as in the response.
+- It is called **once**, with the last attempt sent, before the operation returns or throws and
+  before `onRawResponse`. Unlike `onRawResponse`, it is also called when no attempt got an HTTP
+  response (network error, abort), as long as at least one was sent. It is not called if the
+  operation throws before sending anything (for example a `TypeError` from validation).
+- In SOAP, `eb:MessageId` and `eb:Timestamp` are new on every attempt, so the envelope you get is
+  the one of the last attempt.
+- It is not called for authentication: the OAuth token request, `openSession`
+  (`SessionCreateRQ`, whose envelope carries the EPR password) and `close` (`SessionCloseRQ`).
+- It is synchronous and its return value is ignored. If it throws, the SDK logs
+  `sabre.request.rawRequestHookFailed` without the body, and the operation carries on.
+
+> [!WARNING]
+> `body` and `url` **contain passenger data** (locators, names, contact details). The SDK never
+> sends them to the logger. Where you store them is up to you.
+
 ## Retries
 
 Only idempotent operations are retried: Bargain Finder Max and Revalidate Itinerary (both
@@ -632,7 +812,8 @@ const sabre = new Sabre({
 ```
 
 The SDK logs structured events (`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`), never raw