@molecule/api-flights 1.0.3 → 1.0.5

package/README.md

@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-04T01:48:14.014Z
+Generated: 2026-10-26T04:22:46.981Z
 -->
 
 # @molecule/api-flights
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 Provider-agnostic flights interface for molecule.dev.
 
 Defines the {@link FlightsProvider} interface for flight search +
@@ -20,6 +16,10 @@ interface. Application code uses the convenience functions
 (`searchFlights`, `getOffer`, `priceOffer`) which delegate to the bonded
 provider.
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```typescript
@@ -50,6 +50,73 @@ npm install @molecule/api-flights @molecule/api-bond @molecule/api-i18n
 
 ### Interfaces
 
+#### `Segment`
+
+One leg of a {@link FlightOffer} — a single take-off / landing pair on a
+single operated flight.
+
+```typescript
+interface Segment {
+  /**
+   * Departure airport / instant.
+   */
+  departure: SegmentEndpoint
+
+  /**
+   * Arrival airport / instant.
+   */
+  arrival: SegmentEndpoint
+
+  /**
+   * Marketing carrier IATA code (e.g. `'AA'`, `'BA'`).
+   */
+  carrier: CarrierCode
+
+  /**
+   * Marketing flight number (e.g. `'100'`, `'1234'`).
+   *
+   * String rather than number to preserve any leading zeros and to
+   * accommodate alphanumeric carriers (e.g. EasyJet's `'EZY'` prefix).
+   */
+  flightNumber: string
+
+  /**
+   * IATA aircraft code (e.g. `'77W'`, `'320'`). `null` when the upstream
+   * does not supply aircraft data for this segment.
+   */
+  aircraft?: string | null
+
+  /**
+   * Block / total time the segment is in the air. `null` when the upstream
+   * does not supply per-segment duration.
+   */
+  duration?: IsoDuration | null
+}
+```
+
+#### `SegmentEndpoint`
+
+Departure or arrival point on a {@link Segment}.
+
+```typescript
+interface SegmentEndpoint {
+  /**
+   * IATA airport code (e.g. `'JFK'`).
+   */
+  airport: AirportCode
+
+  /**
+   * Local-time instant including timezone offset.
+   */
+  at: IsoDateTime
+
+  /**
+   * Terminal designator (e.g. `'4'`, `'2A'`). `null` when not supplied.
+   */
+  terminal?: string | null
+}
+```
+
 #### `FlightOffer`
 
 Normalized flight offer returned by
@@ -105,45 +172,34 @@ interface FlightOfferDetail extends FlightOffer {
 }
 ```
 
-#### `FlightsProvider`
-
-Flights provider interface.
+#### `TravelerPricing`
 
-All flight providers (Amadeus, Duffel, Sabre, etc.) implement this
-interface. The interface is deliberately minimal so providers with very
-different upstream APIs can satisfy it identically. Providers that lack
-a "fetch single offer" call typically implement {@link getOffer} by
-round-tripping through their pricing endpoint and returning the priced
-offer.
+Per-passenger price row inside {@link FlightOfferDetail.travelerPricings}.
 
 ```typescript
-interface FlightsProvider {
+interface TravelerPricing {
   /**
-   * Searches for flight offers matching the supplied itinerary.
-   *
-   * @param options - Search parameters (origin, destination, dates,
-   *   passenger counts, cabin, etc.).
-   * @returns Array of normalized flight offers.
+   * Provider-specific traveler id (typically a 1-indexed string).
    */
-  searchFlights(options: SearchFlightsOptions): Promise<FlightOffer[]>
+  travelerId: string
 
   /**
-   * Retrieves a previously-searched offer in detail.
-   *
-   * @param offerId - Opaque offer identifier returned by
-   *   {@link searchFlights}.
-   * @returns The offer with per-passenger price breakdown when available.
+   * Adult, child, or infant. The infant variant is split between
+   * lap-infants (`'held-infant'`) and seated infants (`'seated-infant'`)
+   * because they are priced differently by most carriers.
    */
-  getOffer(offerId: OfferId): Promise<FlightOfferDetail>
+  travelerType: 'adult' | 'child' | 'held-infant' | 'seated-infant'
 
   /**
-   * Confirms the up-to-the-minute price for a previously-searched offer.
-   *
-   * @param offerId - Opaque offer identifier returned by
-   *   {@link searchFlights}.
-   * @returns Authoritative price snapshot.
+   * Total price for this traveler in the offer's currency.
    */
-  priceOffer(offerId: OfferId): Promise<PricingResult>
+  price: number
+
+  /**
+   * Cabin class booked for this traveler. `null` when mixed across
+   * segments or not supplied.
+   */
+  cabin?: CabinClass | null
 }
 ```
 
@@ -241,101 +297,45 @@ interface SearchFlightsOptions {
 }
 ```
 
-#### `Segment`
-
-One leg of a {@link FlightOffer} — a single take-off / landing pair on a
-single operated flight.
-
-```typescript
-interface Segment {
-  /**
-   * Departure airport / instant.
-   */
-  departure: SegmentEndpoint
-
-  /**
-   * Arrival airport / instant.
-   */
-  arrival: SegmentEndpoint
-
-  /**
-   * Marketing carrier IATA code (e.g. `'AA'`, `'BA'`).
-   */
-  carrier: CarrierCode
-
-  /**
-   * Marketing flight number (e.g. `'100'`, `'1234'`).
-   *
-   * String rather than number to preserve any leading zeros and to
-   * accommodate alphanumeric carriers (e.g. EasyJet's `'EZY'` prefix).
-   */
-  flightNumber: string
-
-  /**
-   * IATA aircraft code (e.g. `'77W'`, `'320'`). `null` when the upstream
-   * does not supply aircraft data for this segment.
-   */
-  aircraft?: string | null
-
-  /**
-   * Block / total time the segment is in the air. `null` when the upstream
-   * does not supply per-segment duration.
-   */
-  duration?: IsoDuration | null
-}
-```
-
-#### `SegmentEndpoint`
-
-Departure or arrival point on a {@link Segment}.
-
-```typescript
-interface SegmentEndpoint {
-  /**
-   * IATA airport code (e.g. `'JFK'`).
-   */
-  airport: AirportCode
-
-  /**
-   * Local-time instant including timezone offset.
-   */
-  at: IsoDateTime
-
-  /**
-   * Terminal designator (e.g. `'4'`, `'2A'`). `null` when not supplied.
-   */
-  terminal?: string | null
-}
-```
+#### `FlightsProvider`
 
-#### `TravelerPricing`
+Flights provider interface.
 
-Per-passenger price row inside {@link FlightOfferDetail.travelerPricings}.
+All flight providers (Amadeus, Duffel, Sabre, etc.) implement this
+interface. The interface is deliberately minimal so providers with very
+different upstream APIs can satisfy it identically. Providers that lack
+a "fetch single offer" call typically implement {@link getOffer} by
+round-tripping through their pricing endpoint and returning the priced
+offer.
 
 ```typescript
-interface TravelerPricing {
-  /**
-   * Provider-specific traveler id (typically a 1-indexed string).
-   */
-  travelerId: string
-
+interface FlightsProvider {
   /**
-   * Adult, child, or infant. The infant variant is split between
-   * lap-infants (`'held-infant'`) and seated infants (`'seated-infant'`)
-   * because they are priced differently by most carriers.
+   * Searches for flight offers matching the supplied itinerary.
+   *
+   * @param options - Search parameters (origin, destination, dates,
+   *   passenger counts, cabin, etc.).
+   * @returns Array of normalized flight offers.
    */
-  travelerType: 'adult' | 'child' | 'held-infant' | 'seated-infant'
+  searchFlights(options: SearchFlightsOptions): Promise<FlightOffer[]>
 
   /**
-   * Total price for this traveler in the offer's currency.
+   * Retrieves a previously-searched offer in detail.
+   *
+   * @param offerId - Opaque offer identifier returned by
+   *   {@link searchFlights}.
+   * @returns The offer with per-passenger price breakdown when available.
    */
-  price: number
+  getOffer(offerId: OfferId): Promise<FlightOfferDetail>
 
   /**
-   * Cabin class booked for this traveler. `null` when mixed across
-   * segments or not supplied.
+   * Confirms the up-to-the-minute price for a previously-searched offer.
+   *
+   * @param offerId - Opaque offer identifier returned by
+   *   {@link searchFlights}.
+   * @returns Authoritative price snapshot.
    */
-  cabin?: CabinClass | null
+  priceOffer(offerId: OfferId): Promise<PricingResult>
 }
 ```
 
@@ -353,17 +353,6 @@ upstream exposes.
 type AirportCode = string
 ```
 
-#### `CabinClass`
-
-Cabin class enumeration.
-
-Providers map each value onto whatever upstream code they require
-(e.g. Amadeus uses `'ECONOMY' | 'PREMIUM_ECONOMY' | 'BUSINESS' | 'FIRST'`).
-
-```typescript
-type CabinClass = 'economy' | 'premium-economy' | 'business' | 'first'
-```
-
 #### `CarrierCode`
 
 IATA two-character airline / marketing carrier code (e.g. `'AA'`,
@@ -373,17 +362,6 @@ IATA two-character airline / marketing carrier code (e.g. `'AA'`,
 type CarrierCode = string
 ```
 
-#### `CurrencyCode`
-
-ISO 4217 three-letter currency code (e.g. `'USD'`, `'EUR'`, `'JPY'`).
-
-Conventionally upper-case to match {@link FlightOffer.currency} and the
-vast majority of upstream travel APIs.
-
-```typescript
-type CurrencyCode = string
-```
-
 #### `IsoDate`
 
 ISO 8601 calendar date (e.g. `'2026-07-15'`). Time-of-day MUST NOT be
@@ -416,6 +394,17 @@ whether they expose seconds-precision, fractional minutes, etc.
 type IsoDuration = string
 ```
 
+#### `CurrencyCode`
+
+ISO 4217 three-letter currency code (e.g. `'USD'`, `'EUR'`, `'JPY'`).
+
+Conventionally upper-case to match {@link FlightOffer.currency} and the
+vast majority of upstream travel APIs.
+
+```typescript
+type CurrencyCode = string
+```
+
 #### `OfferId`
 
 Provider-specific offer identifier.
@@ -429,19 +418,30 @@ and MUST NOT be parsed by consumers.
 type OfferId = string
 ```
 
-### Functions
+#### `CabinClass`
 
-#### `getOffer(offerId)`
+Cabin class enumeration.
 
-Retrieves a previously-searched offer in detail.
+Providers map each value onto whatever upstream code they require
+(e.g. Amadeus uses `'ECONOMY' | 'PREMIUM_ECONOMY' | 'BUSINESS' | 'FIRST'`).
 
 ```typescript
-function getOffer(offerId: string): Promise<FlightOfferDetail>
+type CabinClass = 'economy' | 'premium-economy' | 'business' | 'first'
 ```
 
-- `offerId` — Opaque offer identifier returned by `searchFlights`.
+### Functions
 
-**Returns:** The offer with per-passenger price breakdown when available.
+#### `setProvider(provider)`
+
+Registers a flights provider as the active singleton. Called by bond
+packages (e.g. `@molecule/api-flights-amadeus`) during application
+startup.
+
+```typescript
+function setProvider(provider: FlightsProvider): void
+```
+
+- `provider` — The flights provider implementation to bond.
 
 #### `getProvider()`
 
@@ -463,41 +463,41 @@ function hasProvider(): boolean
 
 **Returns:** `true` if a flights provider is bonded.
 
-#### `priceOffer(offerId)`
+#### `searchFlights(options)`
 
-Confirms the up-to-the-minute price for a previously-searched offer.
+Searches for flight offers matching the supplied itinerary.
 
 ```typescript
-function priceOffer(offerId: string): Promise<PricingResult>
+function searchFlights(options: SearchFlightsOptions): Promise<FlightOffer[]>
 ```
 
-- `offerId` — Opaque offer identifier returned by `searchFlights`.
+- `options` — Search parameters (origin, destination, dates, passenger counts, cabin, etc.).
 
-**Returns:** Authoritative price snapshot.
+**Returns:** Array of normalized flight offers.
 
-#### `searchFlights(options)`
+#### `getOffer(offerId)`
 
-Searches for flight offers matching the supplied itinerary.
+Retrieves a previously-searched offer in detail.
 
 ```typescript
-function searchFlights(options: SearchFlightsOptions): Promise<FlightOffer[]>
+function getOffer(offerId: OfferId): Promise<FlightOfferDetail>
 ```
 
-- `options` — Search parameters (origin, destination, dates, passenger counts, cabin, etc.).
+- `offerId` — Opaque offer identifier returned by `searchFlights`.
 
-**Returns:** Array of normalized flight offers.
+**Returns:** The offer with per-passenger price breakdown when available.
 
-#### `setProvider(provider)`
+#### `priceOffer(offerId)`
 
-Registers a flights provider as the active singleton. Called by bond
-packages (e.g. `@molecule/api-flights-amadeus`) during application
-startup.
+Confirms the up-to-the-minute price for a previously-searched offer.
 
 ```typescript
-function setProvider(provider: FlightsProvider): void
+function priceOffer(offerId: OfferId): Promise<PricingResult>
 ```
 
-- `provider` — The flights provider implementation to bond.
+- `offerId` — Opaque offer identifier returned by `searchFlights`.
+
+**Returns:** Authoritative price snapshot.
 
 ## Available Providers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-flights",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Flight search + offer pricing core interface for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -33,11 +33,11 @@
     "@molecule/api-i18n": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-bond": "1.0.2",
-    "@molecule/api-i18n": "1.0.3",
-    "@types/node": "26.1.2",
+    "@molecule/api-bond": "1.0.4",
+    "@molecule/api-i18n": "1.0.5",
+    "@types/node": "26.6.5",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "repository": {
     "type": "git",