sabre-client 0.3.0 → 0.4.0

package/README.es.md

@@ -12,8 +12,9 @@ SDK de TypeScript para las APIs de Sabre.
 
 ## Estado
 
-`0.3.0` es la primera versión publicada 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).
+`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.
 
 ```sh
 npm install sabre-client
@@ -46,8 +47,9 @@ El Tier 3 agrega el cliente SOAP `SabreLegacy`, con una sesión stateful y Queue
 | 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` |
+| Comandos de host | `SabreCommandLLSRQ` 2.0.0 | `session.command` |
 
-Planeado después de `0.3.0`: Get Ancillaries (solo NDC).
+Planeado después de `0.4.0`: Get Ancillaries (solo NDC).
 
 ## Requisitos
 
@@ -70,8 +72,8 @@ const sabre = new Sabre({
   credentials: {
     clientId: process.env.SABRE_CLIENT_ID!,
     clientSecret: process.env.SABRE_CLIENT_SECRET!,
-    username: process.env.SABRE_EPR_USERNAME!, // usuario EPR, p. ej. `<user>-<PCC>-AA`
-    password: process.env.SABRE_EPR_PASSWORD!,
+    username: '<user>-<PCC>-AA', // usuario EPR ya armado (ver Credenciales abajo)
+    password: process.env.SABRE_PASSWORD!,
   },
 });
 ```
@@ -86,6 +88,37 @@ 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)) |
 
+### Credenciales
+
+Hay **un solo juego de credenciales** para REST y SOAP: el mismo objeto `credentials` sirve para
+`Sabre` y para `SabreLegacy`. Trae el usuario EPR, su PCC y su domain, el password del EPR y, de
+forma opcional, el `clientId`/`clientSecret` de la app. La versión de OAuth solo cambia cómo se
+escribe el `username` del EPR: `<user>-<PCC>-<domain>` (v3) o `V1:<user>:<PCC>:<domain>` (v2).
+
+`buildCredentials` arma ese objeto a partir de las partes, así que no necesitas conocer ninguno de
+los dos formatos. No lee variables de entorno y lanza un `TypeError` si algo no es válido:
+
+```ts
+import { Sabre, SabreLegacy, buildCredentials } from 'sabre-client';
+
+const credentials = buildCredentials({
+  authVersion: 'v3', // por defecto; 'v2' → `V1:<user>:<PCC>:<domain>`
+  user: process.env.SABRE_USERNAME!, // solo el usuario EPR
+  pcc: process.env.SABRE_PCC!, // el PCC al que pertenece el EPR
+  domain: process.env.SABRE_DOMAIN || undefined, // 'AA' por defecto
+  password: process.env.SABRE_PASSWORD!,
+  clientId: process.env.SABRE_CLIENT_ID!, // obligatorio con v3; con v2, los dos o ninguno
+  clientSecret: process.env.SABRE_CLIENT_SECRET!,
+});
+
+const sabre = new Sabre({ environment: 'sandbox', credentials });
+const legacy = new SabreLegacy({ environment: 'sandbox', credentials });
+```
+
+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
+`cancel`, o como `pcc` en las operaciones de colas.
+
 ### Autenticación
 
 Nunca pides el token tú. El cliente lo obtiene en la primera llamada, lo cachea, lo renueva
@@ -256,9 +289,12 @@ A tener en cuenta:
   que llega como `SabreGatewayError`.
 - **Qué está comprobado.** `byReservationPayload` se probó en producción, en solo lectura, con
   un vuelo directo y una conexión. La reserva con asiento se probó en sandbox: el asiento llega
-  al PNR y `sabre.booking.get` lo devuelve en `flights[].seats[]`. `byPnrLocator` todavía no se
-  probó contra Sabre, porque las únicas reservas posibles en sandbox viven en otro PCC. Los
-  precios llegan como número aunque el spec diga string, así que los tipos aceptan los dos.
+  al PNR y `sabre.booking.get` lo devuelve en `flights[].seats[]`. `byPnrLocator` se probó en
+  sandbox con una reserva hecha en el PCC con el que te autenticas: devuelve el mapa de los
+  segmentos del PNR, con ids propios de Sabre para pasajero y segmento (`pnr_pax_1`,
+  `segment_ancs_1`) en lugar de `P1` y `S1`. En sandbox ninguno de los dos endpoints refleja la
+  ocupación: todos los asientos vienen en `F`, también el que tiene el PNR. Los precios llegan
+  como número aunque el spec diga string, así que los tipos aceptan los dos.
 
 ## Sesiones SOAP y colas (`SabreLegacy`)
 
@@ -275,7 +311,7 @@ import { SabreLegacy } from 'sabre-client';
 const legacy = new SabreLegacy({
   environment: 'production',
   authVersion: 'v2',
-  credentials: { username: 'V1:<user>:<PCC>:AA', password: process.env.SABRE_EPR_PASSWORD! },
+  credentials: { username: 'V1:<user>:<PCC>:AA', password: process.env.SABRE_PASSWORD! },
 });
 
 const counts = await legacy.withSession((session) => session.queue.count());
@@ -302,6 +338,45 @@ const counts = await legacy.withSession((session) => session.queue.count());
   `session unusable` sin red, y `close()` resuelve sin red. El SDK no la reabre, porque el cursor
   de la cola ya se perdió. Volver a empezar es decisión tuya.
 
+### Comandos de host
+
+`session.command(command, options?)` manda un comando de host de Sabre (`SabreCommandLLSRQ` 2.0.0)
+dentro de la sesión y devuelve la pantalla como texto. **Es una vía de escape**, sin tipos ni
+garantías: el SDK no interpreta la pantalla, y un comando puede cambiar la configuración del PCC o
+emitir boletos. El SDK no tiene una lista de comandos permitidos o bloqueados.
+
+```ts
+const screen = await legacy.withSession((session) => session.command('W/PT¥*', { idempotent: true }));
+// 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
+```
+
+- **El comando va tal cual.** En este servicio, el separador `‡` de Sabre se escribe `¥`
+  (`W/PT‡*` en Sabre Red es `W/PT¥*` aquí); el SDK no lo convierte.
+- **La pantalla no se recorta.** Las pantallas del host van alineadas por columna y pueden empezar
+  con un espacio (` 17MAR  WED…`), así que `text` es el contenido de `Response` tal cual. Si
+  necesitas recortarla, hazlo tú.
+- **Hasta 1023 caracteres, contados como Sabre:** `!`, `%`, `$`, `&`, `¥` y `§` cuentan 2. Un
+  comando más largo lanza un `TypeError` sin llamar a la red (Sabre respondería
+  `REQUEST EXCEEDED MAXIMUM LENGTH`).
+- **Sabre bloquea algunos comandos por su cuenta** (`SO`, `/@`, `¤¤`, según su whitelist), aunque
+  el SDK no tenga una lista propia.
+- **Algunos comandos cuestan más.** `JR` y `WPNI` cuentan como búsquedas "Worldfare".
+- **Las máscaras del host** se responden con los dos primeros caracteres de la máscara.
+- **Prefiere una API estructurada.** Sabre pide no usar este servicio para lo que ya tiene una:
+  si el SDK tiene una operación para eso, úsala.
+- **Sin reintentos por defecto**, porque el SDK no distingue una lectura de un cambio. Pasa
+  `{ idempotent: true }` en los comandos de solo lectura y siguen la
+  [política de reintentos](#reintentos).
+- **Un mensaje del host no es un error.** `DUTY CODE 9 REQUIRED` o `FORMAT` llegan en `text`. Un
+  SOAP fault o un `stl:Error` lanzan, como en cualquier otra llamada de la sesión.
+- Los comandos que dependen de la misma firma (`SI9` y luego `W/PT¥ON`) tienen que ir en la misma
+  sesión.
+- El log de debug (`sabre.session.command`) lleva solo el primer token del comando, cortado a 4
+  caracteres (`W/PT`, `DC`, `*IM`), nunca el comando entero ni la pantalla. La respuesta completa
+  está disponible en `onRawResponse`.
+
 ### Colas
 
 Las operaciones de cola están en `session.queue`. `pcc` es opcional en cada llamada, y por defecto
@@ -490,7 +565,7 @@ const booking = await sabre.booking.get({ confirmationId }, { onRawResponse: (r)
   conserva el valor y escríbelo cuando la llamada vuelva.
 
 En `SabreLegacy`, `protocol` es `'soap'`, `body` es el sobre SOAP completo, y `operation` es
-`'openSession'`, `'close'`, `'ping'` o `'queue.<método>'`. El token de la sesión
+`'openSession'`, `'close'`, `'ping'`, `'command'` o `'queue.<método>'`. El token de la sesión
 (`BinarySecurityToken`) se reemplaza por `[REDACTED]` donde aparezca. No se cambia nada más.
 
 > [!WARNING]
@@ -555,7 +630,7 @@ El SDK registra eventos estructurados (`sabre.request.start`, `sabre.request.end
 `sabre.request.retry`, `sabre.request.rawResponseHookFailed`, `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.queue.exitTolerated`, `sabre.queue.exitFailed`) y nunca los bodies
+`sabre.session.command`, `sabre.queue.exitTolerated`, `sabre.queue.exitFailed`) y nunca los bodies
 crudos de request o response. Los secretos, el header `Authorization` y los datos de pasajeros
 se redactan siempre antes de llegar a tu logger.
 

package/README.md

@@ -12,8 +12,9 @@ TypeScript SDK for the Sabre APIs.
 
 ## Status
 
-`0.3.0` is the first 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).
+`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.
 
 ```sh
 npm install sabre-client
@@ -46,8 +47,9 @@ Tier 3 adds the `SabreLegacy` SOAP client, with a stateful session and Queue Man
 | 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` |
+| Host commands | `SabreCommandLLSRQ` 2.0.0 | `session.command` |
 
-Planned after `0.3.0`: Get Ancillaries (NDC only).
+Planned after `0.4.0`: Get Ancillaries (NDC only).
 
 ## Requirements
 
@@ -70,8 +72,8 @@ const sabre = new Sabre({
   credentials: {
     clientId: process.env.SABRE_CLIENT_ID!,
     clientSecret: process.env.SABRE_CLIENT_SECRET!,
-    username: process.env.SABRE_EPR_USERNAME!, // EPR user, e.g. `<user>-<PCC>-AA`
-    password: process.env.SABRE_EPR_PASSWORD!,
+    username: '<user>-<PCC>-AA', // EPR username, already built (see Credentials below)
+    password: process.env.SABRE_PASSWORD!,
   },
 });
 ```
@@ -86,6 +88,37 @@ 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)) |
 
+### Credentials
+
+There is **one set of credentials** for REST and SOAP: the same `credentials` object works for
+`Sabre` and for `SabreLegacy`. It holds the EPR user, its PCC and domain, the EPR password and,
+optionally, the app's `clientId`/`clientSecret`. The OAuth version only changes how the EPR
+`username` is written: `<user>-<PCC>-<domain>` (v3) or `V1:<user>:<PCC>:<domain>` (v2).
+
+`buildCredentials` builds that object from the parts, so you don't have to know either format.
+It does not read environment variables and throws a `TypeError` on invalid input:
+
+```ts
+import { Sabre, SabreLegacy, buildCredentials } from 'sabre-client';
+
+const credentials = buildCredentials({
+  authVersion: 'v3', // default; 'v2' → `V1:<user>:<PCC>:<domain>`
+  user: process.env.SABRE_USERNAME!, // the EPR user alone
+  pcc: process.env.SABRE_PCC!, // the PCC the EPR belongs to
+  domain: process.env.SABRE_DOMAIN || undefined, // 'AA' by default
+  password: process.env.SABRE_PASSWORD!,
+  clientId: process.env.SABRE_CLIENT_ID!, // required with v3; with v2, both or neither
+  clientSecret: process.env.SABRE_CLIENT_SECRET!,
+});
+
+const sabre = new Sabre({ environment: 'sandbox', credentials });
+const legacy = new SabreLegacy({ environment: 'sandbox', credentials });
+```
+
+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
+`cancel`, or as `pcc` in the queue operations.
+
 ### Authentication
 
 You never request a token yourself. The client gets one on the first call, caches it, renews
@@ -255,9 +288,12 @@ Things to know:
   which surfaces as a `SabreGatewayError`.
 - **What has been checked.** `byReservationPayload` was checked read-only in production, for
   a nonstop and a connection. Booking with a seat was checked in sandbox: the seat reaches the
-  PNR and `sabre.booking.get` returns it in `flights[].seats[]`. `byPnrLocator` has not been
-  checked against Sabre yet, because the only sandbox bookings available live in another PCC.
-  Prices arrive as numbers even though the spec says strings, so the types accept both.
+  PNR and `sabre.booking.get` returns it in `flights[].seats[]`. `byPnrLocator` was checked in
+  sandbox with a booking made in the PCC you authenticate with: it returns the map for the PNR's
+  segments, with Sabre's own passenger and segment ids (`pnr_pax_1`, `segment_ancs_1`) instead
+  of `P1` and `S1`. In sandbox neither endpoint reflects occupancy: every seat comes back as
+  `F`, including the one the PNR holds. Prices arrive as numbers even though the spec says
+  strings, so the types accept both.
 
 ## SOAP sessions and queues (`SabreLegacy`)
 
@@ -273,7 +309,7 @@ import { SabreLegacy } from 'sabre-client';
 const legacy = new SabreLegacy({
   environment: 'production',
   authVersion: 'v2',
-  credentials: { username: 'V1:<user>:<PCC>:AA', password: process.env.SABRE_EPR_PASSWORD! },
+  credentials: { username: 'V1:<user>:<PCC>:AA', password: process.env.SABRE_PASSWORD! },
 });
 
 const counts = await legacy.withSession((session) => session.queue.count());
@@ -301,6 +337,42 @@ const counts = await legacy.withSession((session) => session.queue.count());
   calling the network, and `close()` resolves without calling it. The SDK does not reopen the
   session, because the queue cursor is already lost. Starting over is your decision.
 
+### Host commands
+
+`session.command(command, options?)` sends a Sabre host command (`SabreCommandLLSRQ` 2.0.0)
+inside the session and returns the screen as text. **It is an escape hatch**, with no types and
+no guarantees: the SDK does not parse the screen, and a command can change the PCC configuration
+or issue tickets. There is no list of allowed or blocked commands.
+
+```ts
+const screen = await legacy.withSession((session) => session.command('W/PT¥*', { idempotent: true }));
+// 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
+```
+
+- **The command is sent as is.** In this service Sabre's `‡` separator is written `¥`
+  (`W/PT‡*` in Sabre Red is `W/PT¥*` here); the SDK does not convert it.
+- **The screen is not trimmed.** Host screens are aligned by column and can start with a space
+  (` 17MAR  WED…`), so `text` is the content of `Response` as is. Trim it yourself if you need to.
+- **Up to 1023 characters, counted as Sabre does:** `!`, `%`, `$`, `&`, `¥` and `§` count 2. A
+  longer command throws a `TypeError` without calling the network (Sabre would answer
+  `REQUEST EXCEEDED MAXIMUM LENGTH`).
+- **Sabre blocks some commands on its own** (`SO`, `/@`, `¤¤`, per its whitelist), even though
+  the SDK has no list of its own.
+- **Some commands cost more.** `JR` and `WPNI` count as "Worldfare" searches.
+- **Host masks** are answered with the first two characters of the mask.
+- **Prefer a structured API.** Sabre asks not to use this service for what already has one: when
+  the SDK has an operation for it, use that.
+- **No retries by default**, because the SDK cannot tell a read from a change. Pass
+  `{ idempotent: true }` for read-only commands and they follow the [retry policy](#retries).
+- **A host message is not an error.** `DUTY CODE 9 REQUIRED` or `FORMAT` come back in `text`. A
+  SOAP fault or an `stl:Error` throws, like any other session call.
+- Commands that need the same sign-in (`SI9` followed by `W/PT¥ON`) must run in the same session.
+- The debug log (`sabre.session.command`) carries only the first token of the command, cut to 4
+  characters (`W/PT`, `DC`, `*IM`), never the whole command or the screen. The full response is
+  available through `onRawResponse`.
+
 ### Queues
 
 The queue operations live in `session.queue`. `pcc` is optional in every call and defaults to the
@@ -486,7 +558,7 @@ const booking = await sabre.booking.get({ confirmationId }, { onRawResponse: (r)
   asynchronously, keep the value and write it after the call returns.
 
 In `SabreLegacy`, `protocol` is `'soap'`, `body` is the whole SOAP envelope, and `operation` is
-`'openSession'`, `'close'`, `'ping'` or `'queue.<method>'`. The session token
+`'openSession'`, `'close'`, `'ping'`, `'command'` or `'queue.<method>'`. The session token
 (`BinarySecurityToken`) is replaced by `[REDACTED]` wherever it appears. Nothing else is changed.
 
 > [!WARNING]
@@ -552,7 +624,7 @@ The SDK logs structured events (`sabre.request.start`, `sabre.request.end`,
 `sabre.request.retry`, `sabre.request.rawResponseHookFailed`, `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.queue.exitTolerated`, `sabre.queue.exitFailed`), never raw
+`sabre.session.command`, `sabre.queue.exitTolerated`, `sabre.queue.exitFailed`), never raw
 request or response bodies. Secrets, the `Authorization` header and passenger data are always
 redacted before they reach your logger.
 

package/dist/index.d.ts

@@ -41,7 +41,7 @@ interface SabreLogger {
 }
 type SabreLogLevel = keyof SabreLogger;
 /** Eventos estables que emite el SDK como `message`. */
-type SabreLogEvent = 'sabre.request.start' | 'sabre.request.end' | 'sabre.request.retry' | 'sabre.request.rawResponseHookFailed' | '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.queue.exitTolerated' | 'sabre.queue.exitFailed';
+type SabreLogEvent = 'sabre.request.start' | 'sabre.request.end' | 'sabre.request.retry' | 'sabre.request.rawResponseHookFailed' | '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';
 /** Logger interno: redacta siempre el contexto y no hace nada si no hay logger. */
 declare class EventLogger {
     #private;
@@ -1893,6 +1893,27 @@ declare class QueueManagement {
     place(request: QueuePlaceRequest, options?: QueuePlaceOptions): Promise<QueuePlaceResponse>;
 }
 
+interface SabreCommandOptions extends RequestOptions {
+    /**
+     * `true` solo si el comando es una lectura (`W/PT¥*`, `DC¥…`): entra en la política de
+     * reintentos. Por defecto `false`, porque el SDK no sabe si un comando cambia algo.
+     */
+    idempotent?: boolean;
+}
+interface SabreCommandResponse {
+    /**
+     * La pantalla tal como la devuelve Sabre (`Response`), sin interpretar y sin recortar: las
+     * pantallas van alineadas por columna y pueden empezar con un espacio (` 17MAR  WED…`). Recortar
+     * es decisión de quien la lee. Un mensaje de host (`DUTY CODE 9 REQUIRED`, `FORMAT`) llega aquí:
+     * no lanza.
+     */
+    text: string;
+    /** Los `stl:Warning` de la respuesta. No lanzan. */
+    warnings: SabreWarning[];
+    /** `eb:MessageId` de la respuesta, el dato que pide soporte de Sabre. */
+    messageId: string | undefined;
+}
+
 /** Lo que una operación pide al transporte. La sesión agrega `CPAId`, `ConversationId` y el token. */
 type SessionRequest = Omit<SoapRequest, 'cpaId' | 'conversationId' | 'security'>;
 /**
@@ -1937,6 +1958,14 @@ declare class SabreSession {
      * recorrido de cola no hace falta: cada operación ya lo reinicia.
      */
     ping(options?: RequestOptions): Promise<void>;
+    /**
+     * Manda un comando de host (`SabreCommandLLSRQ` 2.0.0) y devuelve la pantalla como texto, sin
+     * interpretarla. Es una vía de escape: sin tipos ni garantías, y un comando puede cambiar la
+     * configuración del PCC o emitir. El comando va tal cual; el separador de Sabre Red (`‡`) se
+     * escribe `¥`. Sin reintento salvo `{ idempotent: true }`, para comandos de solo lectura. La
+     * pantalla llega sin recortar, y más de 1023 caracteres (contados como Sabre) lanza sin red.
+     */
+    command(command: string, options?: SabreCommandOptions): Promise<SabreCommandResponse>;
     /**
      * Cierra la sesión con `SessionCloseRQ`: Sabre descarta el AAA e invalida el token. Es
      * idempotente: las llamadas siguientes devuelven la misma promesa, sin volver a la red. Si el
@@ -1975,6 +2004,42 @@ declare class SabreLegacy {
     withSession<T>(callback: (session: SabreSession) => Promise<T>): Promise<T>;
 }
 
+interface BuildCredentialsBase {
+    /** Usuario EPR, sin PCC ni domain. */
+    user: string;
+    /** PCC del EPR (el *group*): 3 o 4 caracteres alfanuméricos. */
+    pcc: string;
+    /** Domain del EPR. Default `'AA'`. */
+    domain?: string;
+    /** Contraseña EPR. */
+    password: string;
+}
+/** Partes para OAuth Token Create v3 (default): `clientId` y `clientSecret` son obligatorios. */
+interface BuildCredentialsOptionsV3 extends BuildCredentialsBase {
+    authVersion?: 'v3';
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Partes para OAuth Token Create v2: `clientId`/`clientSecret` son opcionales. REST los ignora,
+ * pero si vienen los dos, `SabreLegacy` abre la sesión con `SessionCreateRQ` 2.0.0.
+ */
+interface BuildCredentialsOptionsV2 extends BuildCredentialsBase {
+    authVersion: 'v2';
+    clientId?: string;
+    clientSecret?: string;
+}
+type BuildCredentialsOptions = BuildCredentialsOptionsV3 | BuildCredentialsOptionsV2;
+/**
+ * Arma el `credentials` para `Sabre` y `SabreLegacy` a partir del usuario, el PCC, el domain y
+ * la contraseña del EPR, más `clientId`/`clientSecret` cuando los hay. El username queda como
+ * `<user>-<PCC>-<domain>` (v3) o `V1:<user>:<PCC>:<domain>` (v2). No lee variables de entorno
+ * ni toca la red; un dato inválido lanza `TypeError` sin repetir secretos.
+ */
+declare function buildCredentials(options: BuildCredentialsOptionsV3): SabreCredentials;
+declare function buildCredentials(options: BuildCredentialsOptionsV2): SabreCredentialsV2;
+declare function buildCredentials(options: BuildCredentialsOptions): SabreCredentials | SabreCredentialsV2;
+
 /**
  * Cómo se elige el año cuando el texto no lo trae:
  *
@@ -2219,6 +2284,6 @@ interface BookingFlightDetailsSource {
  */
 declare function buildBookingFlightDetails(source: BookingFlightDetailsSource): FlightDetails;
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.0";
 
-export { Air, type BaggageAllowanceDesc, type BaggageInformation, type BargainFinderMaxRequest, type BargainFinderMaxResponse, type BookContactInformation, type BookGenericSeat, type BookSeat, type BookTraveler, type Booking, type BookingAgency, type BookingFlightDetailsSource, type BookingItemReference, BookingManagement, type BookingResponseError, type BookingSeatSelection, type BookingSource, type BrandedFare, type CancelBookingErrorPolicy, type CancelBookingNotification, type CancelBookingOptions, type CancelBookingRequest, type CancelBookingResponse, type CancelSegmentReference, type CreateBookingErrorPolicy, type CreateBookingOptions, type CreateBookingRequest, type CreateBookingResponse, type CreateBookingResponseError, type CurrencyConversion, type Fare, type FareComponent, type FareComponentDesc, type FareComponentDescSegment, type FareComponentSegment, type FareComponentSegmentDetail, type FareMessage, type FlightDetails, type FlightStatusCode, type FlightTicketOperation, type FlightToBook, type GetBookingExtraFeatures, type GetBookingOptions, type GetBookingRequest, type GetBookingResponse, type GetBookingReturnOnly, type GetSeatsRequest, type GetSeatsResponse, type GroupedItineraryResponse, type HostDateDirection, type Itinerary, type ItineraryGroup, type ItineraryMessage, type Leg, type LegDesc, type LegDescription, type LegSchedule, type LegScheduleRef, type LowFareSearchFlight, type LowFareSearchLocation, type LowFareSearchOriginDestination, type LowFareSearchPassengerTypeQuantity, type LowFareSearchRequestorId, type LowFareSearchSource, type LowFareSearchTpaExtensions, type LowFareSearchTravelPreferences, type LowFareSearchTravelerInfoSummary, type ObFeeDesc, type OpenSessionOptions, type OtaAirLowFareSearchRq, type PassengerInfo, type PassengerPricing, type PassengerTotalFare, type PaymentMethod, type PriceComparison, type PriceComparisonType, type PricedSeat, type PricingDetails, type PricingInformation, type PricingQualifiers, type QueueAccessOptions, type QueueAccessRequest, type QueueCount, type QueueCountOptions, type QueueCountRequest, type QueueCountResponse, type QueueEndReason, type QueueItem, type QueueListEntry, type QueueListOptions, type QueueListRequest, type QueueListResponse, QueueManagement, type QueueNavigationOptions, type QueueParagraph, type QueueParagraphAirSegment, type QueueParagraphMessage, type QueueParagraphOptions, type QueueParagraphOtherSegment, type QueueParagraphPassenger, type QueueParagraphReceivedFrom, type QueueParagraphSegment, type QueueParagraphTicketing, type QueueParagraphTicketingEntry, type QueuePlaceOptions, type QueuePlaceRequest, type QueuePlaceResponse, type QueuePlaceResult, type QueuePlaceTarget, type QueuePlacement, type QueueProcessAction, type QueueProcessRequest, type QueueProcessResult, QueueRef, type QueueRemoveRequest, type QueueRemoveTarget, type QueueSelection, type QueueState, type QueueStep, type RawSeatAvailabilityRs, type Ref, type RefundDocumentsType, type RequestOptions, type ResolveHostDateOptions, type RetryOptions, type RevalidateItineraryRequest, type RevalidateItineraryRequestSource, type RevalidateItineraryResponse, Sabre, type SabreAuthVersion, SabreBusinessError, type SabreBusinessErrorOptions, type SabreConfig, type SabreConfigV2, type SabreConfigV3, type SabreCredentials, type SabreCredentialsV2, type SabreEnvironment, SabreError, type SabreErrorOptions, SabreGatewayError, type SabreGatewayErrorOptions, SabreLegacy, type SabreLogEvent, type SabreLogLevel, type SabreLogger, SabreOrchestrationError, type SabreOrchestrationErrorOptions, type SabreProtocol, type SabreRawResponse, type SabreRawResponseCallback, type SabreServiceErrorOptions, SabreSession, SabreSessionError, type SabreSessionErrorKind, type SabreSessionErrorOptions, type SabreTokenStore, SabreWarning, type ScheduleCarrier, type ScheduleDesc, type ScheduleEndpoint, type ScheduleEquipment, type Seat, type SeatAreaPreference, type SeatAvailabilityByPayloadRq, type SeatAvailabilityByPnrLocatorRq, type SeatAvailabilityIssue, type SeatAvailabilityRequestSource, type SeatAvailabilityResponse, type SeatCabinCompartment, type SeatCabinFacility, type SeatCabinLayout, type SeatCabinRowPosition, type SeatCharacteristic, type SeatDisplayOnlyItem, type SeatFareComponent, type SeatFareDetail, type SeatFareSegmentAssociation, type SeatFlightLeg, type SeatKeyValuePair, type SeatLoyaltyProgramAccount, type SeatMap, type SeatOfferItem, type SeatOfferItemDetails, type SeatPassenger, type SeatPassengerPayloadRq, type SeatPassengerRs, type SeatPriceBreakdown, type SeatPriceDefinition, type SeatRow, type SeatSegment, type SeatSegmentPayloadRq, type SeatSegmentRs, type SeatServiceDefinition, type SeatSpecialServiceRequest, type SeatTax, type SpecificFare, type StoredToken, type TaxDesc, type TaxSummaryDesc, type TicketingPolicy, type TotalFare, type TravelerPhone, type TravelerTitle, VERSION, type ValidatingCarrierDesc, buildBookingFlightDetails, buildRevalidateItineraryRequest, buildSeatAvailabilityRequest, parseQueueParagraph, resolveHostDate };
+export { Air, type BaggageAllowanceDesc, type BaggageInformation, type BargainFinderMaxRequest, type BargainFinderMaxResponse, type BookContactInformation, type BookGenericSeat, type BookSeat, type BookTraveler, type Booking, type BookingAgency, type BookingFlightDetailsSource, type BookingItemReference, BookingManagement, type BookingResponseError, type BookingSeatSelection, type BookingSource, type BrandedFare, type BuildCredentialsOptions, type BuildCredentialsOptionsV2, type BuildCredentialsOptionsV3, type CancelBookingErrorPolicy, type CancelBookingNotification, type CancelBookingOptions, type CancelBookingRequest, type CancelBookingResponse, type CancelSegmentReference, type CreateBookingErrorPolicy, type CreateBookingOptions, type CreateBookingRequest, type CreateBookingResponse, type CreateBookingResponseError, type CurrencyConversion, type Fare, type FareComponent, type FareComponentDesc, type FareComponentDescSegment, type FareComponentSegment, type FareComponentSegmentDetail, type FareMessage, type FlightDetails, type FlightStatusCode, type FlightTicketOperation, type FlightToBook, type GetBookingExtraFeatures, type GetBookingOptions, type GetBookingRequest, type GetBookingResponse, type GetBookingReturnOnly, type GetSeatsRequest, type GetSeatsResponse, type GroupedItineraryResponse, type HostDateDirection, type Itinerary, type ItineraryGroup, type ItineraryMessage, type Leg, type LegDesc, type LegDescription, type LegSchedule, type LegScheduleRef, type LowFareSearchFlight, type LowFareSearchLocation, type LowFareSearchOriginDestination, type LowFareSearchPassengerTypeQuantity, type LowFareSearchRequestorId, type LowFareSearchSource, type LowFareSearchTpaExtensions, type LowFareSearchTravelPreferences, type LowFareSearchTravelerInfoSummary, type ObFeeDesc, type OpenSessionOptions, type OtaAirLowFareSearchRq, type PassengerInfo, type PassengerPricing, type PassengerTotalFare, type PaymentMethod, type PriceComparison, type PriceComparisonType, type PricedSeat, type PricingDetails, type PricingInformation, type PricingQualifiers, type QueueAccessOptions, type QueueAccessRequest, type QueueCount, type QueueCountOptions, type QueueCountRequest, type QueueCountResponse, type QueueEndReason, type QueueItem, type QueueListEntry, type QueueListOptions, type QueueListRequest, type QueueListResponse, QueueManagement, type QueueNavigationOptions, type QueueParagraph, type QueueParagraphAirSegment, type QueueParagraphMessage, type QueueParagraphOptions, type QueueParagraphOtherSegment, type QueueParagraphPassenger, type QueueParagraphReceivedFrom, type QueueParagraphSegment, type QueueParagraphTicketing, type QueueParagraphTicketingEntry, type QueuePlaceOptions, type QueuePlaceRequest, type QueuePlaceResponse, type QueuePlaceResult, type QueuePlaceTarget, type QueuePlacement, type QueueProcessAction, type QueueProcessRequest, type QueueProcessResult, QueueRef, type QueueRemoveRequest, type QueueRemoveTarget, type QueueSelection, type QueueState, type QueueStep, type RawSeatAvailabilityRs, type Ref, type RefundDocumentsType, type RequestOptions, type ResolveHostDateOptions, type RetryOptions, type RevalidateItineraryRequest, type RevalidateItineraryRequestSource, type RevalidateItineraryResponse, Sabre, type SabreAuthVersion, SabreBusinessError, type SabreBusinessErrorOptions, type SabreCommandOptions, type SabreCommandResponse, type SabreConfig, type SabreConfigV2, type SabreConfigV3, type SabreCredentials, type SabreCredentialsV2, type SabreEnvironment, SabreError, type SabreErrorOptions, SabreGatewayError, type SabreGatewayErrorOptions, SabreLegacy, type SabreLogEvent, type SabreLogLevel, type SabreLogger, SabreOrchestrationError, type SabreOrchestrationErrorOptions, type SabreProtocol, type SabreRawResponse, type SabreRawResponseCallback, type SabreServiceErrorOptions, SabreSession, SabreSessionError, type SabreSessionErrorKind, type SabreSessionErrorOptions, type SabreTokenStore, SabreWarning, type ScheduleCarrier, type ScheduleDesc, type ScheduleEndpoint, type ScheduleEquipment, type Seat, type SeatAreaPreference, type SeatAvailabilityByPayloadRq, type SeatAvailabilityByPnrLocatorRq, type SeatAvailabilityIssue, type SeatAvailabilityRequestSource, type SeatAvailabilityResponse, type SeatCabinCompartment, type SeatCabinFacility, type SeatCabinLayout, type SeatCabinRowPosition, type SeatCharacteristic, type SeatDisplayOnlyItem, type SeatFareComponent, type SeatFareDetail, type SeatFareSegmentAssociation, type SeatFlightLeg, type SeatKeyValuePair, type SeatLoyaltyProgramAccount, type SeatMap, type SeatOfferItem, type SeatOfferItemDetails, type SeatPassenger, type SeatPassengerPayloadRq, type SeatPassengerRs, type SeatPriceBreakdown, type SeatPriceDefinition, type SeatRow, type SeatSegment, type SeatSegmentPayloadRq, type SeatSegmentRs, type SeatServiceDefinition, type SeatSpecialServiceRequest, type SeatTax, type SpecificFare, type StoredToken, type TaxDesc, type TaxSummaryDesc, type TicketingPolicy, type TotalFare, type TravelerPhone, type TravelerTitle, VERSION, type ValidatingCarrierDesc, buildBookingFlightDetails, buildCredentials, buildRevalidateItineraryRequest, buildSeatAvailabilityRequest, parseQueueParagraph, resolveHostDate };

package/dist/index.js

@@ -1491,14 +1491,16 @@ var TRANSIENT_CODES = /* @__PURE__ */ new Set([
 var PREVIOUS_ENTRY_ACTIVE_RETRIES = 3;
 var PREVIOUS_ENTRY_ACTIVE_DELAY_MS = 1e3;
 var PREVIOUS_ENTRY_ACTIVE = /PREVIOUS ENTRY ACTIVE/i;
-var parser = new XMLParser({
+var PARSER_OPTIONS = {
   ignoreAttributes: false,
   attributeNamePrefix: "@",
   removeNSPrefix: true,
   parseTagValue: false,
   parseAttributeValue: false,
   processEntities: true
-});
+};
+var parser = new XMLParser(PARSER_OPTIONS);
+var untrimmedParser = new XMLParser({ ...PARSER_OPTIONS, trimValues: false });
 var SoapTransport = class {
   #config;
   #log;
@@ -1738,11 +1740,11 @@ function scrubToken(text, security) {
   const token = security.binarySecurityToken;
   return text.split(token).join(REDACTED).split(xmlEscape(token)).join(REDACTED);
 }
-function parseEnvelope(text) {
+function parseEnvelope(text, xmlParser = parser) {
   if (text.trim() === "") return void 0;
   let parsed;
   try {
-    parsed = parser.parse(text);
+    parsed = xmlParser.parse(text);
   } catch {
     return void 0;
   }
@@ -1807,6 +1809,10 @@ function retryReason(error, idempotent) {
   if (error.status === void 0 || TRANSIENT_STATUS.has(error.status)) return "transient";
   return void 0;
 }
+function untrimmedPayload(raw) {
+  const document = parseEnvelope(raw, untrimmedParser);
+  return document === void 0 ? void 0 : asNode(firstElement(document.Body)[1]);
+}
 function firstElement(node2) {
   for (const [key, value] of Object.entries(node2)) {
     if (!key.startsWith("@") && key !== "#text") return [key, Array.isArray(value) ? value[0] : value];
@@ -2511,11 +2517,63 @@ function validateSelection(selection) {
   });
 }
 
+// src/session/command.ts
+var SABRE_COMMAND_SERVICE = "sabreCommand";
+var NAMESPACE5 = "http://webservices.sabre.com/sabreXML/2011/10";
+var MAX_COMMAND_LENGTH = 1023;
+var DOUBLE_WIDTH = /* @__PURE__ */ new Set(["!", "%", "$", "&", "\xA5", "\xA7"]);
+function fail4(message) {
+  throw new TypeError(`sabre-client: ${message}`);
+}
+function sabreCommandPayload(command) {
+  return `<SabreCommandLLSRQ xmlns="${NAMESPACE5}" Version="2.0.0" ReturnHostCommand="true"><Request Output="SCREEN"><HostCommand>${xmlEscape(command)}</HostCommand></Request></SabreCommandLLSRQ>`;
+}
+function commandToken(command) {
+  return (command.trim().split(/[¥‡\s]/u)[0] ?? "").slice(0, 4);
+}
+function sabreCommandLength(command) {
+  let length = 0;
+  for (const char of command) length += DOUBLE_WIDTH.has(char) ? 2 : 1;
+  return length;
+}
+function sabreCommandRequest(command, options) {
+  if (typeof command !== "string" || command.trim() === "") fail4("command es requerido y debe ser un string no vac\xEDo");
+  const length = sabreCommandLength(command);
+  if (length > MAX_COMMAND_LENGTH) {
+    fail4(`command mide ${length} y el m\xE1ximo es ${MAX_COMMAND_LENGTH} (!, %, $, &, \xA5 y \xA7 cuentan 2); Sabre responder\xEDa REQUEST EXCEEDED MAXIMUM LENGTH`);
+  }
+  const { idempotent = false, ...requestOptions } = options;
+  if (typeof idempotent !== "boolean") fail4("idempotent debe ser un boolean");
+  return {
+    service: SABRE_COMMAND_SERVICE,
+    action: "SabreCommandLLSRQ",
+    payload: sabreCommandPayload(command),
+    idempotent,
+    operation: "command",
+    ...requestOptions
+  };
+}
+function parseSabreCommandResponse(response) {
+  if (response.payloadName !== "SabreCommandLLSRS") {
+    throw new SabreGatewayError(`${SABRE_COMMAND_SERVICE}: respuesta no reconocida (${response.payloadName})`, {
+      protocol: "soap",
+      status: response.status,
+      retryable: false,
+      raw: response.raw
+    });
+  }
+  return {
+    text: textOf((untrimmedPayload(response.raw) ?? response.payload).Response) ?? "",
+    warnings: response.warnings,
+    messageId: response.messageId
+  };
+}
+
 // src/session/session.ts
 var OTA_NAMESPACE = "http://www.opentravel.org/OTA/2002/11";
 var SWS_NAMESPACE = "http://webservices.sabre.com";
 var sessionSend = /* @__PURE__ */ Symbol("sabre-client.session.send");
-function fail4(message) {
+function fail5(message) {
   throw new TypeError(`sabre-client: ${message}`);
 }
 var SESSION_ERROR_KINDS = /* @__PURE__ */ new Map([
@@ -2587,6 +2645,18 @@ var SabreSession = class {
   async ping(options = {}) {
     checkPingResponse(await this[sessionSend]({ ...pingRequest(), ...options }));
   }
+  /**
+   * Manda un comando de host (`SabreCommandLLSRQ` 2.0.0) y devuelve la pantalla como texto, sin
+   * interpretarla. Es una vía de escape: sin tipos ni garantías, y un comando puede cambiar la
+   * configuración del PCC o emitir. El comando va tal cual; el separador de Sabre Red (`‡`) se
+   * escribe `¥`. Sin reintento salvo `{ idempotent: true }`, para comandos de solo lectura. La
+   * pantalla llega sin recortar, y más de 1023 caracteres (contados como Sabre) lanza sin red.
+   */
+  async command(command, options = {}) {
+    const request = sabreCommandRequest(command, options);
+    this.#transport.log.emit("debug", "sabre.session.command", { command: commandToken(command) });
+    return parseSabreCommandResponse(await this[sessionSend](request));
+  }
   /**
    * Cierra la sesión con `SessionCloseRQ`: Sabre descarta el AAA e invalida el token. Es
    * idempotente: las llamadas siguientes devuelven la misma promesa, sin volver a la red. Si el
@@ -2614,11 +2684,11 @@ var SabreSession = class {
     return this.#send(request);
   }
   async #send(request) {
-    if (this.#closing !== void 0) fail4("session closed");
+    if (this.#closing !== void 0) fail5("session closed");
     if (this.#unusable !== void 0) {
       throw new TypeError(`sabre-client: session unusable (${this.#unusable.kind})`, { cause: this.#unusable });
     }
-    if (this.#busy) fail4("session busy");
+    if (this.#busy) fail5("session busy");
     this.#busy = true;
     try {
       const response = await this.#transport.request({ ...request, ...this.#envelopeFields() });
@@ -2773,7 +2843,7 @@ function usernameToken(credentials) {
 }
 async function openSession(transport, credentials, options = {}) {
   const { keepAlive = false, ...requestOptions } = options;
-  if (typeof keepAlive !== "boolean") fail4("keepAlive debe ser un boolean");
+  if (typeof keepAlive !== "boolean") fail5("keepAlive debe ser un boolean");
   const conversationId = globalThis.crypto.randomUUID();
   const request = {
     service: "sessionCreate",
@@ -2876,6 +2946,38 @@ var SabreLegacy = class {
   }
 };
 
+// src/auth/credentials.ts
+var DEFAULT_DOMAIN = "AA";
+function fail6(message) {
+  throw new TypeError(`sabre-client: ${message}`);
+}
+function requireString2(value, field) {
+  if (typeof value !== "string" || value.trim() === "") fail6(`${field} es requerido y debe ser un string no vac\xEDo`);
+}
+function buildCredentials(options) {
+  if (typeof options !== "object" || options === null) fail6("buildCredentials recibe un objeto");
+  const authVersion = options.authVersion ?? "v3";
+  if (authVersion !== "v3" && authVersion !== "v2") {
+    fail6(`authVersion debe ser 'v3' o 'v2' (recibido: ${JSON.stringify(authVersion)})`);
+  }
+  const { user, pcc, password, clientId, clientSecret } = options;
+  const domain = options.domain ?? DEFAULT_DOMAIN;
+  requireString2(user, "user");
+  requireString2(password, "password");
+  if (!isPseudoCityCode(pcc)) fail6("pcc debe tener 3 o 4 caracteres alfanum\xE9ricos");
+  requireString2(domain, "domain");
+  if (/[-:]/.test(domain)) fail6("domain no puede contener '-' ni ':'");
+  if (clientId === void 0 !== (clientSecret === void 0)) {
+    fail6("clientId y clientSecret van juntos: pasa los dos o ninguno");
+  }
+  if (authVersion === "v3" || clientId !== void 0) {
+    requireString2(clientId, authVersion === "v3" ? "clientId (requerido con authVersion v3)" : "clientId");
+    requireString2(clientSecret, authVersion === "v3" ? "clientSecret (requerido con authVersion v3)" : "clientSecret");
+  }
+  const username = authVersion === "v3" ? `${user}-${pcc}-${domain}` : `V1:${user}:${pcc}:${domain}`;
+  return clientId === void 0 ? { username, password } : { clientId, clientSecret, username, password };
+}
+
 // src/queue/host-date.ts
 var MONTHS = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"];
 var DAY_MS = 864e5;
@@ -3258,7 +3360,7 @@ function fareComponent(fareComponentId, component) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 export {
   Sabre,
   SabreBusinessError,
@@ -3270,6 +3372,7 @@ export {
   SabreWarning,
   VERSION,
   buildBookingFlightDetails,
+  buildCredentials,
   buildRevalidateItineraryRequest,
   buildSeatAvailabilityRequest,
   parseQueueParagraph,