sabre-client 0.2.3 → 0.3.0-next.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Carlos Ivan Soto Perez
+Copyright (c) 2026 Carlos Ivan Soto Perez
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.es.md

@@ -0,0 +1,264 @@
+# sabre-client
+
+SDK de TypeScript para las APIs de Sabre.
+
+[Read in English](./README.md)
+
+> **`0.3.0` es una reescritura completa, no una actualización incremental de `0.2.4`.**
+> Tiene otra arquitectura: un cliente REST `Sabre` con un `AuthManager` que gestiona el token,
+> una jerarquía de errores tipada, un logger inyectable con redacción obligatoria y solo Web
+> Standard APIs, para correr en cualquier runtime de servidor. El código escrito para `0.2.4`
+> no funciona sin cambios. Las versiones anteriores siguen publicadas tal como están.
+
+## Estado
+
+`0.3.0` **todavía no está publicada**. Se publica cuando estén terminados el Tier 1 y el
+Tier 2 del flujo de Air Booking. Mientras tanto, `npm install sabre-client` instala `0.2.4`.
+
+Las prereleases de la reescritura se publican con el tag `next`:
+
+```sh
+npm install sabre-client@next
+```
+
+La API todavía puede cambiar antes de `0.3.0`.
+
+El Tier 1 cubre el flujo básico de Air Booking por REST:
+
+| Paso | Servicio | Método |
+| - | - | - |
+| Autenticación | OAuth Token Create v3 / v2 | automática |
+| Búsqueda | Bargain Finder Max v5 | `sabre.air.bargainFinderMax` |
+| Revalidación | Revalidate Itinerary v5 | `sabre.air.revalidateItinerary` |
+| Reserva | Create Booking (Booking Management API v1, ATPCO por `flightDetails`) | `sabre.booking.create` |
+| Gestión de la reserva | Get Booking y Cancel Booking (Booking Management API v1) | `sabre.booking.get`, `sabre.booking.cancel` |
+
+Planeado: Get Seats y Get Ancillaries (Tier 2), y un cliente `SabreLegacy` para los servicios SOAP.
+
+## Requisitos
+
+- Node.js `>=22.12`, o un runtime edge de servidor con `fetch` y `crypto.subtle`
+  (Cloudflare Workers, Vercel Edge Functions, Deno Deploy). El paquete usa solo Web Standard
+  APIs.
+- Solo ESM.
+- **Nunca lo corras en un navegador.** Tus credenciales de Sabre quedarían expuestas a
+  cualquiera con las devtools.
+
+## Configuración
+
+El SDK nunca lee variables de entorno. La configuración se pasa explícitamente:
+
+```ts
+import { Sabre } from 'sabre-client';
+
+const sabre = new Sabre({
+  environment: 'sandbox', // 'sandbox' (CERT) o 'production'
+  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!,
+  },
+});
+```
+
+| Opción | Default | Descripción |
+| - | - | - |
+| `environment` | requerido | `'sandbox'` → `api.cert.platform.sabre.com`, `'production'` → `api.platform.sabre.com` |
+| `authVersion` | `'v3'` | Versión de OAuth Token Create. `'v3'` necesita `clientId`, `clientSecret`, `username` y `password`; `'v2'` solo el `username` EPR (`V1:<user>:<PCC>:AA`) y el `password` |
+| `credentials` | requerido | Ver arriba |
+| `logger` | ninguno | Cualquier objeto con `debug`, `info`, `warn` y `error` (ver [Logging](#logging)) |
+| `retry` | `{ maxRetries: 3, baseDelayMs: 500 }` | Política de reintentos del cliente; cada request puede pisarla |
+| `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)) |
+
+### Autenticación
+
+Nunca pides el token tú. El cliente lo obtiene en la primera llamada, lo cachea, lo renueva
+alrededor de una hora antes de que expire y comparte una sola petición en vuelo entre llamadas
+concurrentes. Si Sabre rechaza un token con `401`, el cliente obtiene uno nuevo y reintenta esa
+request una vez.
+
+## Reservar un vuelo
+
+El flujo completo del Tier 1: buscar, revalidar el itinerario elegido y reservarlo.
+
+```ts
+import { Sabre, buildRevalidateItineraryRequest, buildBookingFlightDetails } from 'sabre-client';
+
+const sabre = new Sabre({ environment: 'sandbox', credentials });
+
+// 1. Buscar con Bargain Finder Max. El request es el body que documenta Sabre.
+const search = {
+  OTA_AirLowFareSearchRQ: {
+    Version: '5',
+    POS: { Source: [{ PseudoCityCode: 'XXXX', RequestorID: { Type: '1', ID: '1', CompanyName: { Code: 'TN' } } }] },
+    OriginDestinationInformation: [
+      { DepartureDateTime: '2026-12-01T10:00:00', OriginLocation: { LocationCode: 'DFW' }, DestinationLocation: { LocationCode: 'LAX' } },
+    ],
+    TravelerInfoSummary: { AirTravelerAvail: [{ PassengerTypeQuantity: [{ Code: 'ADT', Quantity: 1 }] }] },
+    TPA_Extensions: { IntelliSellTransaction: { RequestType: { Name: '50ITINS' } } },
+  },
+};
+const found = await sabre.air.bargainFinderMax(search);
+
+// Las respuestas llegan con las referencias ya resueltas: cada itinerario trae sus tramos,
+// horarios y tarifas en línea, sin tener que buscar por `ref`.
+const group = found.itineraryGroups[0]!;
+const itinerary = group.itineraries[0]!;
+
+// 2. Revalidar el itinerario elegido (disponibilidad y precio, sin retener inventario).
+const revalidated = await sabre.air.revalidateItinerary(
+  buildRevalidateItineraryRequest({ search, group, itinerary }),
+);
+const confirmedGroup = revalidated.itineraryGroups[0]!;
+const confirmed = confirmedGroup.itineraries[0]!;
+
+// 3. Reservarlo por el camino ATPCO (`flightDetails`).
+const booking = await sabre.booking.create({
+  flightDetails: buildBookingFlightDetails({ group: confirmedGroup, itinerary: confirmed }),
+  travelers: [{ givenName: 'JANE', surname: 'DOE', passengerCode: 'ADT' }],
+  contactInfo: { emails: ['jane@example.com'], phones: ['5550000000'] },
+});
+
+console.log(booking.confirmationId); // localizador del PNR
+```
+
+`buildBookingFlightDetails` convierte el itinerario revalidado en el bloque `flightDetails` de
+Create Booking. Sabre no documenta ese mapeo y todavía no se comprobó con una reserva real en
+sandbox, así que revisa el request antes de depender de él.
+
+`sabre.booking.create` **nunca se reintenta automáticamente**, porque no es idempotente. Si
+Sabre crea la reserva con avisos o errores no fatales, la llamada no lanza: revisa
+`booking.warnings` y `booking.errors`.
+
+`sabre.booking.get` lee una reserva por `confirmationId`. A diferencia de Create Booking, la
+respuesta trae los campos de la reserva en el primer nivel (`bookingId`, `flights`,
+`travelers`, …), tal como la define Sabre. Usa `returnOnly` para pedir solo las secciones que
+necesitas; además, la llamada es más rápida:
+
+```ts
+const pnr = await sabre.booking.get({
+  confirmationId: booking.confirmationId,
+  returnOnly: ['FLIGHTS', 'TRAVELERS'],
+});
+```
+
+Solo lanza `SabreBusinessError` si no hay reserva (por ejemplo, `BOOKING_NOT_FOUND`). Si la
+reserva existe, los problemas parciales vuelven en `pnr.warnings` y `pnr.errors`; una reserva
+sin emitir suele traer el aviso `RESOURCE_UNAVAILABLE` porque todavía no tiene fare rules. Es
+una lectura, así que los fallos transitorios se reintentan.
+
+`sabre.booking.cancel` cancela la reserva entera (`cancelAll: true`) o productos concretos por
+el `itemId` que devuelve `get`:
+
+```ts
+await sabre.booking.cancel({ confirmationId: booking.confirmationId, cancelAll: true });
+await sabre.booking.cancel({ confirmationId: pnr.bookingId, flights: [{ itemId: '2' }] });
+```
+
+Como `create`, **nunca se reintenta automáticamente**. Las combinaciones que Sabre siempre
+rechaza (`cancelAll` junto con listas, ni `cancelAll` ni listas, `offerItemId` junto con
+`flightTicketOperation`) lanzan un `TypeError` antes de enviar nada. Si Sabre responde
+`NO_ITEMS_CANCELLED`, la llamada lanza `SabreBusinessError` aunque Sabre lo mande como aviso,
+porque no se canceló nada; los errores que explican el motivo están en `error.errors`. El aviso
+`END_TRANSACTION_PROBLEM` significa que la confirmación sigue pendiente: verifica el resultado
+con `sabre.booking.get`.
+
+Toda request acepta un `AbortSignal`. Las búsquedas aceptan además una política de reintentos
+propia:
+
+```ts
+await sabre.air.bargainFinderMax(search, { signal, retry: { maxRetries: 1 } });
+```
+
+## Manejo de errores
+
+Todos los errores que lanza el SDK extienden `SabreError`:
+
+| Clase | Cuándo | Campos extra |
+| - | - | - |
+| `SabreGatewayError` | Falla HTTP o del gateway (`ERR.2SG.*`, `401`, `429`, `5xx`, errores de OAuth) | `protocol`, `status`, `code` |
+| `SabreOrchestrationError` | Error de un servicio orquestado dentro de un `200` (`SP.*`) | `code` |
+| `SabreBusinessError` | Error del catálogo propio de un servicio (p. ej. `No Availability`, una reserva que no se creó) | `service`, `code`, `warnings`, `errors` |
+| `SabreWarning` | Aviso no fatal (p. ej. `category: WARNING` en Create Booking) | `service`, `code` |
+
+Todos tienen `retryable`, que indica si la política de reintentos puede volver a intentar.
+
+```ts
+import { SabreBusinessError, SabreGatewayError } from 'sabre-client';
+
+try {
+  await sabre.booking.create(request);
+} catch (error) {
+  if (error instanceof SabreBusinessError) {
+    console.error(error.service, error.code, error.message);
+  } else if (error instanceof SabreGatewayError) {
+    console.error(error.status, error.code);
+  }
+  throw error;
+}
+```
+
+> [!WARNING]
+> `SabreError.raw` guarda el fragmento original de la respuesta, sin tocar, para debugging.
+> **Puede contener credenciales o datos de pasajeros.** No es enumerable, así que no aparece en
+> `JSON.stringify` ni en un spread, pero sigue accesible como `error.raw`. Nunca lo mandes a un
+> logger, a un tracker de errores ni a un servicio de monitoreo sin sanitizarlo antes.
+
+## Reintentos
+
+Solo se reintentan las operaciones idempotentes: Bargain Finder Max y Revalidate Itinerary
+(ambas son `POST` de solo lectura). Create Booking nunca se reintenta. Los reintentos usan
+backoff exponencial con full jitter y un piso de 500 ms, ante `429`, `500`, `503`, `504`,
+`SP.PROVIDER_ERROR` y los errores temporales del catálogo de Bargain Finder Max.
+
+## Reutilizar el token
+
+Por defecto el token vive en memoria, uno por instancia de `Sabre`. Para compartirlo entre
+procesos (scripts, funciones serverless), pasa un `tokenStore`. El SDK no trae ninguna
+implementación:
+
+```ts
+import type { SabreTokenStore } from 'sabre-client';
+
+const tokenStore: SabreTokenStore = {
+  async get(key) {
+    return JSON.parse((await kv.get(key)) ?? 'null') ?? undefined;
+  },
+  async set(key, token) {
+    await kv.put(key, JSON.stringify(token));
+  },
+};
+```
+
+`key` identifica el entorno, la versión de OAuth y un hash de la identidad de la credencial,
+así que un mismo store sirve a varios clientes. No contiene secretos, pero el token guardado sí
+lo es: protegerlo te toca a ti. Si `get` o `set` lanzan, el SDK sigue con su caché en memoria.
+
+## Logging
+
+No hay logging salvo que pases un `logger`. Es compatible con `console` y `winston`; con `pino`,
+invierte los argumentos:
+
+```ts
+const sabre = new Sabre({
+  environment: 'sandbox',
+  credentials,
+  logger: {
+    debug: (m, c) => pino.debug(c, m),
+    info: (m, c) => pino.info(c, m),
+    warn: (m, c) => pino.warn(c, m),
+    error: (m, c) => pino.error(c, m),
+  },
+});
+```
+
+El SDK registra eventos estructurados (`sabre.request.start`, `sabre.request.end`,
+`sabre.request.retry`, `sabre.auth.token.refresh`, `sabre.auth.token.store`) 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.
+
+## Changelog
+
+Ver [CHANGELOG.md](./CHANGELOG.md).

package/README.md

@@ -1,148 +1,264 @@
-# Sabre Node.js SDK
+# sabre-client
 
-Node.js library for the Sabre API (REST).
+TypeScript SDK for the Sabre APIs.
 
-## Install
+[Leer en español](./README.es.md)
 
-```bash
-npm install sabre-client
-```
+> **`0.3.0` is a complete rewrite, not an incremental update to `0.2.4`.**
+> It is built on a different architecture (a `Sabre` REST client with a managed
+> `AuthManager`, a typed error hierarchy, injectable logging with mandatory redaction, and
+> runtime-agnostic Web Standard APIs). Code written against `0.2.4` will not work unchanged.
+> Older versions stay published as they are.
 
-## Setup
+## Status
 
-First, you need to get an username, password and pcc which is available in the [DEV STUDIO - Applications](https://developer.sabre.com/my-account/applications).
+`0.3.0` is **not released yet**. It will be released once both Tier 1 and Tier 2 of the
+Air Booking flow are done. Until then, `npm install sabre-client` installs `0.2.4`.
 
-```js
-import { Sabre } from 'sabre-client';
+Prereleases of the rewrite are published under the `next` tag:
 
-const sabre = new Sabre({
-  username: '773400', 
-  password: 'PASSWORD_GOES_HERE',
-  organization: '7TZA', // pcc
-});
+```sh
+npm install sabre-client@next
 ```
 
-## Documentation
-
-See http://developer.sabre.com
+The API may still change before `0.3.0`.
 
-## Usage
+Tier 1 covers the core Air Booking flow over REST:
 
-Send the request for acquiring an authentication ATK session token.
+| Step | Service | Method |
+| - | - | - |
+| Authentication | OAuth Token Create v3 / v2 | automatic |
+| Shopping | Bargain Finder Max v5 | `sabre.air.bargainFinderMax` |
+| Revalidation | Revalidate Itinerary v5 | `sabre.air.revalidateItinerary` |
+| Booking | Create Booking (Booking Management API v1, ATPCO by `flightDetails`) | `sabre.booking.create` |
+| Booking management | Get Booking and Cancel Booking (Booking Management API v1) | `sabre.booking.get`, `sabre.booking.cancel` |
 
-```js
-await sabre.authentication.OAuthTokenV2();
-```
+Planned: Get Seats and Get Ancillaries (Tier 2), and a `SabreLegacy` client for SOAP services.
 
-### Get booking v1.30
+## Requirements
 
-Displays comprehensive booking details irrespective of source, optionally narrowing down the response to selected elements.
+- Node.js `>=22.12`, or a server-side edge runtime with `fetch` and `crypto.subtle`
+  (Cloudflare Workers, Vercel Edge Functions, Deno Deploy). The package uses only Web
+  Standard APIs.
+- ESM only.
+- **Never run it in a browser.** Your Sabre credentials would be exposed to anyone with
+  devtools.
 
-```js
-await sabre.booking.get({
-  confirmationId: 'GLEBNY',
-  returnOnly: [],
-});
-```
+## Configuration
 
-### Create booking
+The SDK never reads environment variables. Pass the configuration explicitly:
 
-Creates an air booking (NDC/ATPCO/LCC).
+```ts
+import { Sabre } from 'sabre-client';
 
-```js
-await sabre.booking.create(options);
+const sabre = new Sabre({
+  environment: 'sandbox', // 'sandbox' (CERT) or 'production'
+  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!,
+  },
+});
 ```
 
-### Modify Booking
-
-Creates a list of booking items that need to be modified.
+| Option | Default | Description |
+| - | - | - |
+| `environment` | required | `'sandbox'` → `api.cert.platform.sabre.com`, `'production'` → `api.platform.sabre.com` |
+| `authVersion` | `'v3'` | OAuth Token Create version. `'v3'` needs `clientId`, `clientSecret`, `username` and `password`; `'v2'` only needs the EPR `username` (`V1:<user>:<PCC>:AA`) and `password` |
+| `credentials` | required | See above |
+| `logger` | none | Any object with `debug`, `info`, `warn` and `error` (see [Logging](#logging)) |
+| `retry` | `{ maxRetries: 3, baseDelayMs: 500 }` | Client-wide retry policy; every request can override it |
+| `fetch` | global `fetch` | Custom `fetch` (proxies, tests, other runtimes) |
+| `tokenStore` | in-memory only | Shares the token between processes (see [Token reuse](#token-reuse)) |
+
+### Authentication
+
+You never request a token yourself. The client gets one on the first call, caches it, renews
+it about an hour before it expires, and shares a single in-flight request between concurrent
+calls. If Sabre rejects a token with `401`, the client gets a new one and retries that request
+once.
+
+## Booking a flight
+
+The full Tier 1 flow: search, revalidate the chosen itinerary, and book it.
+
+```ts
+import { Sabre, buildRevalidateItineraryRequest, buildBookingFlightDetails } from 'sabre-client';
+
+const sabre = new Sabre({ environment: 'sandbox', credentials });
+
+// 1. Search with Bargain Finder Max. The request is the body Sabre documents.
+const search = {
+  OTA_AirLowFareSearchRQ: {
+    Version: '5',
+    POS: { Source: [{ PseudoCityCode: 'XXXX', RequestorID: { Type: '1', ID: '1', CompanyName: { Code: 'TN' } } }] },
+    OriginDestinationInformation: [
+      { DepartureDateTime: '2026-12-01T10:00:00', OriginLocation: { LocationCode: 'DFW' }, DestinationLocation: { LocationCode: 'LAX' } },
+    ],
+    TravelerInfoSummary: { AirTravelerAvail: [{ PassengerTypeQuantity: [{ Code: 'ADT', Quantity: 1 }] }] },
+    TPA_Extensions: { IntelliSellTransaction: { RequestType: { Name: '50ITINS' } } },
+  },
+};
+const found = await sabre.air.bargainFinderMax(search);
+
+// Responses come with references already resolved: every itinerary has its legs,
+// schedules and fares inline, no `ref` lookups needed.
+const group = found.itineraryGroups[0]!;
+const itinerary = group.itineraries[0]!;
+
+// 2. Revalidate the chosen itinerary (availability and price, no inventory held).
+const revalidated = await sabre.air.revalidateItinerary(
+  buildRevalidateItineraryRequest({ search, group, itinerary }),
+);
+const confirmedGroup = revalidated.itineraryGroups[0]!;
+const confirmed = confirmedGroup.itineraries[0]!;
+
+// 3. Book it through the ATPCO path (`flightDetails`).
+const booking = await sabre.booking.create({
+  flightDetails: buildBookingFlightDetails({ group: confirmedGroup, itinerary: confirmed }),
+  travelers: [{ givenName: 'JANE', surname: 'DOE', passengerCode: 'ADT' }],
+  contactInfo: { emails: ['jane@example.com'], phones: ['5550000000'] },
+});
 
-```js
-await sabre.booking.modify(options);
+console.log(booking.confirmationId); // PNR locator
 ```
 
-### Cancel Booking
+`buildBookingFlightDetails` maps the revalidated itinerary to the `flightDetails` block of
+Create Booking. That mapping is not documented by Sabre and has not been checked against a
+real sandbox booking yet, so review the request before you rely on it.
 
-Cancels a booking or specified booking items, optionally voiding or refunding related flight tickets.
+`sabre.booking.create` is **never retried automatically**, because it is not idempotent. If
+Sabre creates the booking with warnings or non-fatal errors, the call does not throw. Check
+`booking.warnings` and `booking.errors`.
 
-```js
-await sabre.booking.cancel(options);
-```
-
-### Void Flight Tickets
+`sabre.booking.get` reads a booking by `confirmationId`. Unlike Create Booking, the response
+has the booking fields at the top level (`bookingId`, `flights`, `travelers`, …), as Sabre
+defines it. Use `returnOnly` to ask only for the sections you need, which also makes the call
+faster:
 
-Voids tickets with ticket numbers listed in the request, optionally including nonelectronic tickets (paper).
-
-```js
-await sabre.flightTickets.void(options);
+```ts
+const pnr = await sabre.booking.get({
+  confirmationId: booking.confirmationId,
+  returnOnly: ['FLIGHTS', 'TRAVELERS'],
+});
 ```
 
-### Refund Flight Tickets
+It throws `SabreBusinessError` only when there is no booking (for example
+`BOOKING_NOT_FOUND`). If the booking exists, partial problems come back in `pnr.warnings`
+and `pnr.errors`; an unticketed booking usually carries a `RESOURCE_UNAVAILABLE` warning
+because it has no fare rules yet. It is a read, so transient failures are retried.
 
-Processes tickets by providing a request containing a list of ticket numbers which should be refunded. EMDs are currently not supported.
+`sabre.booking.cancel` cancels the whole booking (`cancelAll: true`) or specific items by the
+`itemId` that `get` returns:
 
-```js
-await sabre.flightTickets.refund(options);
+```ts
+await sabre.booking.cancel({ confirmationId: booking.confirmationId, cancelAll: true });
+await sabre.booking.cancel({ confirmationId: pnr.bookingId, flights: [{ itemId: '2' }] });
 ```
 
-### Check Flight Tickets
+Like `create`, it is **never retried automatically**. Combinations that Sabre always rejects
+(`cancelAll` together with item lists, no `cancelAll` and no list, `offerItemId` together with
+`flightTicketOperation`) throw a `TypeError` before any request is sent. If Sabre answers
+`NO_ITEMS_CANCELLED`, the call throws `SabreBusinessError` even though Sabre sends it as a
+warning, because nothing was cancelled; the errors that explain why are in `error.errors`. An
+`END_TRANSACTION_PROBLEM` warning means the confirmation is still pending: check the result
+with `sabre.booking.get`.
 
-Checks tickets with ticket numbers listed in the request for void, refund and exchange conditions. EMDs are currently not supported.
+Every request accepts an `AbortSignal`. Shopping calls also accept a per-request retry policy:
 
-```js
-await sabre.flightTickets.check(options);
+```ts
+await sabre.air.bargainFinderMax(search, { signal, retry: { maxRetries: 1 } });
 ```
 
-### Fulfill Flight Tickets
+## Error handling
 
-Processes the issuance of tickets and various electronic miscellaneous documents (EMDs). EMDs are currently not supported.
+Every error thrown by the SDK extends `SabreError`:
 
-```js
-await sabre.flightTickets.fulfill(options);
-```
+| Class | When | Extra fields |
+| - | - | - |
+| `SabreGatewayError` | HTTP or gateway failure (`ERR.2SG.*`, `401`, `429`, `5xx`, OAuth errors) | `protocol`, `status`, `code` |
+| `SabreOrchestrationError` | Orchestrated service error inside a `200` (`SP.*`) | `code` |
+| `SabreBusinessError` | Error from a service's own catalog (e.g. `No Availability`, a booking that was not created) | `service`, `code`, `warnings`, `errors` |
+| `SabreWarning` | Non-fatal warning (e.g. `category: WARNING` in Create Booking) | `service`, `code` |
 
-### Bargain Finder Max (Search)
+All of them have `retryable`, which says whether the retry policy may try again.
 
-Searches for the lowest available priced itineraries for a given origin and destination.
+```ts
+import { SabreBusinessError, SabreGatewayError } from 'sabre-client';
 
-```js
-await sabre.search.shop(options);
+try {
+  await sabre.booking.create(request);
+} catch (error) {
+  if (error instanceof SabreBusinessError) {
+    console.error(error.service, error.code, error.message);
+  } else if (error instanceof SabreGatewayError) {
+    console.error(error.status, error.code);
+  }
+  throw error;
+}
 ```
 
-### Revalidate Itinerary (Search)
+> [!WARNING]
+> `SabreError.raw` holds the original response fragment, untouched, for debugging. It **can
+> contain credentials or passenger data**. It is not enumerable, so it does not show up in
+> `JSON.stringify` or object spreads, but you can still read `error.raw`. Never send it to a
+> logger, error tracker or monitoring service without sanitizing it first.
 
-The Revalidate Itinerary API allows you to re-query the availability and price of a specific itinerary option without having to book it.
+## Retries
 
-```js
-await sabre.search.revalidate(options);
-```
+Only idempotent operations are retried: Bargain Finder Max and Revalidate Itinerary (both
+are read-only `POST`s). Create Booking is never retried. Retries use exponential backoff with
+full jitter and a 500 ms floor, on `429`, `500`, `503`, `504`, `SP.PROVIDER_ERROR` and the
+temporary errors in the Bargain Finder Max catalog.
 
-### Issue Ticket (Ticketing) 
+## Token reuse
 
-Issues an airline ticket from an existing PNR (booking).
+By default the token lives in memory, one per `Sabre` instance. To share it between
+processes (scripts, serverless functions), pass a `tokenStore`. The SDK does not ship any
+implementation:
 
-```js
-await sabre.ticketing.issue(options);
-```
+```ts
+import type { SabreTokenStore } from 'sabre-client';
 
-## Development
+const tokenStore: SabreTokenStore = {
+  async get(key) {
+    return JSON.parse((await kv.get(key)) ?? 'null') ?? undefined;
+  },
+  async set(key, token) {
+    await kv.put(key, JSON.stringify(token));
+  },
+};
+```
 
-#### Install dependencies
+`key` identifies the environment, the OAuth version and a hash of the credential identity,
+so one store can serve several clients. It contains no secrets, but the stored token is one:
+protecting it is up to you. If `get` or `set` throws, the SDK falls back to its in-memory
+cache.
 
-```sh
-npm install
-```
+## Logging
 
-#### Build and run packages
+Logging is off unless you pass a `logger`. It is compatible with `console` and `winston`;
+for `pino`, swap the arguments:
 
-```sh
-npm dev
+```ts
+const sabre = new Sabre({
+  environment: 'sandbox',
+  credentials,
+  logger: {
+    debug: (m, c) => pino.debug(c, m),
+    info: (m, c) => pino.info(c, m),
+    warn: (m, c) => pino.warn(c, m),
+    error: (m, c) => pino.error(c, m),
+  },
+});
 ```
 
-## Authors
-
-- Carlos Ivan Soto ([carlosivansotop](https://www.linkedin.com/in/carlosivansotop/))
+The SDK logs structured events (`sabre.request.start`, `sabre.request.end`,
+`sabre.request.retry`, `sabre.auth.token.refresh`, `sabre.auth.token.store`), never raw
+request or response bodies. Secrets, the `Authorization` header and passenger data are always
+redacted before they reach your logger.
 
-## License
+## Changelog
 
-MIT License
+See [CHANGELOG.md](./CHANGELOG.md).