@molecule/api-flights 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-flights` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-flights is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,gGAAgG;QAC9F,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Provider-agnostic flights interface for molecule.dev.
+ *
+ * Defines the {@link FlightsProvider} interface for flight search +
+ * pricing. Bond packages (Amadeus, Duffel, Sabre, etc.) implement this
+ * interface. Application code uses the convenience functions
+ * (`searchFlights`, `getOffer`, `priceOffer`) which delegate to the bonded
+ * provider.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, searchFlights, priceOffer } from '@molecule/api-flights'
+ * import { provider as amadeus } from '@molecule/api-flights-amadeus'
+ *
+ * setProvider(amadeus)
+ * const offers = await searchFlights({
+ *   origin: 'JFK',
+ *   destination: 'LHR',
+ *   departureDate: '2026-07-15',
+ *   adults: 1,
+ * })
+ * const priced = await priceOffer(offers[0].id)
+ * ```
+ *
+ * @remarks
+ * - **Offer ids are opaque, provider-scoped, and short-lived.** Never parse
+ *   them and never persist them as durable references — a stale id fails
+ *   `getOffer`/`priceOffer`; re-run the search instead of replaying old ids.
+ * - **Re-price before you commit.** `PricingResult.price` is the
+ *   authoritative total at pricing time and MAY differ from the search-time
+ *   `FlightOffer.price` — call `priceOffer()` right before the checkout/
+ *   summary step and display the re-priced figure.
+ * - **This contract is search + pricing only — there is no booking method.**
+ *   Don't invent a `bookFlight()`; booking needs vendor-specific work outside
+ *   this interface.
+ * - **Server-side only; cache searches.** Flight-search APIs are slow,
+ *   rate-limited, and often billed per call — cache results per (origin,
+ *   destination, dates, passengers) for a short TTL and never fire a search
+ *   per keystroke.
+ * - Airports/cities are IATA codes (`'JFK'`, `'NYC'`), dates are ISO calendar
+ *   dates (`'2026-07-15'`), and prices carry an explicit ISO 4217 `currency` —
+ *   format with it, never a hardcoded `$`.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual search / results screens, and check every box
+ * off one by one. A box you can't check is an integration bug to fix — not a
+ * skip:
+ * - [ ] Searching a real route + future date (e.g. JFK→LHR, a date weeks out)
+ *   returns REAL `searchFlights` offers rendered in the results list — each
+ *   showing an origin, a destination, departure/arrival times, and a price. No
+ *   empty list, `null`, or placeholder row is presented as a successful search.
+ * - [ ] Results match the query: each offer's first `segment.departure.airport`
+ *   and last `segment.arrival.airport` are the searched cities and the
+ *   `departure.at` falls on the requested date — not random routes or dates.
+ * - [ ] Every price shows its `currency` (ISO 4217, formatted with it — never a
+ *   hardcoded `$`) and is sane (positive, right order of magnitude). If a
+ *   checkout/summary step re-prices via `priceOffer`/`getOffer`, the displayed
+ *   total is the re-priced figure, not the stale search-time price.
+ * - [ ] Any exposed filter/sort (price, stops, departure/arrival time, cabin)
+ *   actually narrows or reorders the SAME result set — not a fresh random list.
+ * - [ ] An impossible or invalid search — no availability, a past date, or a
+ *   bad airport code — shows a clear "no flights" / "invalid" state, not a
+ *   crash and not a blank list presented as a successful search.
+ * - [ ] A provider outage or rate-limit (HTTP 429) surfaces as a graceful,
+ *   retryable error in the UI — not a hung spinner or a silent empty list.
+ * - [ ] This contract is search + pricing ONLY (there is no `bookFlight`). If
+ *   the app adds a book/hold step it goes OUT-OF-BAND to the vendor — verify
+ *   the app records the SELECTED offer (its priced total + itinerary), since
+ *   opaque `OfferId`s are short-lived and can't be replayed later.
+ * - [ ] The provider API key stays server-side: searches run through the API
+ *   bond and no key or upstream credential is ever exposed to the browser.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './types.js';
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAGH,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAG1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,81 @@
+/**
+ * Provider-agnostic flights interface for molecule.dev.
+ *
+ * Defines the {@link FlightsProvider} interface for flight search +
+ * pricing. Bond packages (Amadeus, Duffel, Sabre, etc.) implement this
+ * interface. Application code uses the convenience functions
+ * (`searchFlights`, `getOffer`, `priceOffer`) which delegate to the bonded
+ * provider.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, searchFlights, priceOffer } from '@molecule/api-flights'
+ * import { provider as amadeus } from '@molecule/api-flights-amadeus'
+ *
+ * setProvider(amadeus)
+ * const offers = await searchFlights({
+ *   origin: 'JFK',
+ *   destination: 'LHR',
+ *   departureDate: '2026-07-15',
+ *   adults: 1,
+ * })
+ * const priced = await priceOffer(offers[0].id)
+ * ```
+ *
+ * @remarks
+ * - **Offer ids are opaque, provider-scoped, and short-lived.** Never parse
+ *   them and never persist them as durable references — a stale id fails
+ *   `getOffer`/`priceOffer`; re-run the search instead of replaying old ids.
+ * - **Re-price before you commit.** `PricingResult.price` is the
+ *   authoritative total at pricing time and MAY differ from the search-time
+ *   `FlightOffer.price` — call `priceOffer()` right before the checkout/
+ *   summary step and display the re-priced figure.
+ * - **This contract is search + pricing only — there is no booking method.**
+ *   Don't invent a `bookFlight()`; booking needs vendor-specific work outside
+ *   this interface.
+ * - **Server-side only; cache searches.** Flight-search APIs are slow,
+ *   rate-limited, and often billed per call — cache results per (origin,
+ *   destination, dates, passengers) for a short TTL and never fire a search
+ *   per keystroke.
+ * - Airports/cities are IATA codes (`'JFK'`, `'NYC'`), dates are ISO calendar
+ *   dates (`'2026-07-15'`), and prices carry an explicit ISO 4217 `currency` —
+ *   format with it, never a hardcoded `$`.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual search / results screens, and check every box
+ * off one by one. A box you can't check is an integration bug to fix — not a
+ * skip:
+ * - [ ] Searching a real route + future date (e.g. JFK→LHR, a date weeks out)
+ *   returns REAL `searchFlights` offers rendered in the results list — each
+ *   showing an origin, a destination, departure/arrival times, and a price. No
+ *   empty list, `null`, or placeholder row is presented as a successful search.
+ * - [ ] Results match the query: each offer's first `segment.departure.airport`
+ *   and last `segment.arrival.airport` are the searched cities and the
+ *   `departure.at` falls on the requested date — not random routes or dates.
+ * - [ ] Every price shows its `currency` (ISO 4217, formatted with it — never a
+ *   hardcoded `$`) and is sane (positive, right order of magnitude). If a
+ *   checkout/summary step re-prices via `priceOffer`/`getOffer`, the displayed
+ *   total is the re-priced figure, not the stale search-time price.
+ * - [ ] Any exposed filter/sort (price, stops, departure/arrival time, cabin)
+ *   actually narrows or reorders the SAME result set — not a fresh random list.
+ * - [ ] An impossible or invalid search — no availability, a past date, or a
+ *   bad airport code — shows a clear "no flights" / "invalid" state, not a
+ *   crash and not a blank list presented as a successful search.
+ * - [ ] A provider outage or rate-limit (HTTP 429) surfaces as a graceful,
+ *   retryable error in the UI — not a hung spinner or a silent empty list.
+ * - [ ] This contract is search + pricing ONLY (there is no `bookFlight`). If
+ *   the app adds a book/hold step it goes OUT-OF-BAND to the vendor — verify
+ *   the app records the SELECTED offer (its priced total + itinerary), since
+ *   opaque `OfferId`s are short-lived and can't be replayed later.
+ * - [ ] The provider API key stays server-side: searches run through the API
+ *   bond and no key or upstream credential is ever exposed to the browser.
+ *
+ * @module
+ */
+// Type exports
+export * from './browser-guard.js';
+export * from './types.js';
+// Provider exports
+export * from './provider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,eAAe;AACf,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAE1B,mBAAmB;AACnB,cAAc,eAAe,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Flights provider bond accessor and convenience functions.
+ *
+ * Bond packages (e.g. `@molecule/api-flights-amadeus`) call
+ * `setProvider()` during application startup. Application code uses the
+ * convenience functions (`searchFlights`, `getOffer`, `priceOffer`) which
+ * delegate to the bonded provider via `@molecule/api-bond`.
+ *
+ * @module
+ */
+import type { FlightOffer, FlightOfferDetail, FlightsProvider, OfferId, PricingResult, SearchFlightsOptions } from './types.js';
+/**
+ * Registers a flights provider as the active singleton. Called by bond
+ * packages (e.g. `@molecule/api-flights-amadeus`) during application
+ * startup.
+ *
+ * @param provider - The flights provider implementation to bond.
+ */
+export declare const setProvider: (provider: FlightsProvider) => void;
+/**
+ * Retrieves the bonded flights provider, throwing if none is configured.
+ *
+ * @returns The bonded flights provider.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export declare const getProvider: () => FlightsProvider;
+/**
+ * Checks whether a flights provider is currently bonded.
+ *
+ * @returns `true` if a flights provider is bonded.
+ */
+export declare const hasProvider: () => boolean;
+/**
+ * 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.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export declare const searchFlights: (options: SearchFlightsOptions) => Promise<FlightOffer[]>;
+/**
+ * Retrieves a previously-searched offer in detail.
+ *
+ * @param offerId - Opaque offer identifier returned by `searchFlights`.
+ * @returns The offer with per-passenger price breakdown when available.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export declare const getOffer: (offerId: OfferId) => Promise<FlightOfferDetail>;
+/**
+ * Confirms the up-to-the-minute price for a previously-searched offer.
+ *
+ * @param offerId - Opaque offer identifier returned by `searchFlights`.
+ * @returns Authoritative price snapshot.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export declare const priceOffer: (offerId: OfferId) => Promise<PricingResult>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,OAAO,EACP,aAAa,EACb,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAKnB;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,eAAe,KAAG,IAEvD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,eAW9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAE9B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAU,SAAS,oBAAoB,KAAG,OAAO,CAAC,WAAW,EAAE,CAExF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAU,SAAS,OAAO,KAAG,OAAO,CAAC,iBAAiB,CAE1E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAU,SAAS,OAAO,KAAG,OAAO,CAAC,aAAa,CAExE,CAAA"}

package/dist/provider.js

@@ -0,0 +1,80 @@
+/**
+ * Flights provider bond accessor and convenience functions.
+ *
+ * Bond packages (e.g. `@molecule/api-flights-amadeus`) call
+ * `setProvider()` during application startup. Application code uses the
+ * convenience functions (`searchFlights`, `getOffer`, `priceOffer`) which
+ * delegate to the bonded provider via `@molecule/api-bond`.
+ *
+ * @module
+ */
+import { bond, expectBond, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'flights';
+expectBond(BOND_TYPE);
+/**
+ * Registers a flights provider as the active singleton. Called by bond
+ * packages (e.g. `@molecule/api-flights-amadeus`) during application
+ * startup.
+ *
+ * @param provider - The flights provider implementation to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded flights provider, throwing if none is configured.
+ *
+ * @returns The bonded flights provider.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export const getProvider = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (error) {
+        throw new Error(t('flights.error.noProvider', undefined, {
+            defaultValue: 'Flights provider not configured. Call setProvider() first.',
+        }), { cause: error });
+    }
+};
+/**
+ * Checks whether a flights provider is currently bonded.
+ *
+ * @returns `true` if a flights provider is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * 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.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export const searchFlights = async (options) => {
+    return getProvider().searchFlights(options);
+};
+/**
+ * Retrieves a previously-searched offer in detail.
+ *
+ * @param offerId - Opaque offer identifier returned by `searchFlights`.
+ * @returns The offer with per-passenger price breakdown when available.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export const getOffer = async (offerId) => {
+    return getProvider().getOffer(offerId);
+};
+/**
+ * Confirms the up-to-the-minute price for a previously-searched offer.
+ *
+ * @param offerId - Opaque offer identifier returned by `searchFlights`.
+ * @returns Authoritative price snapshot.
+ * @throws {Error} If no flights provider has been bonded.
+ */
+export const priceOffer = async (offerId) => {
+    return getProvider().priceOffer(offerId);
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACvF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAWtC,MAAM,SAAS,GAAG,SAAS,CAAA;AAC3B,UAAU,CAAC,SAAS,CAAC,CAAA;AAErB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAyB,EAAQ,EAAE;IAC7D,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAoB,EAAE;IAC/C,IAAI,CAAC;QACH,OAAO,WAAW,CAAkB,SAAS,CAAC,CAAA;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,0BAA0B,EAAE,SAAS,EAAE;YACvC,YAAY,EAAE,4DAA4D;SAC3E,CAAC,EACF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE;IACvC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,OAA6B,EAA0B,EAAE;IAC3F,OAAO,WAAW,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;AAC7C,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,OAAgB,EAA8B,EAAE;IAC7E,OAAO,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AACxC,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAAE,OAAgB,EAA0B,EAAE;IAC3E,OAAO,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;AAC1C,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Type definitions for the flights core interface.
+ *
+ * @module
+ */
+/**
+ * IATA airport or city code (e.g. `'JFK'`, `'LAX'`, `'PAR'`).
+ *
+ * Kept as a plain `string` alias rather than a string-literal union so
+ * providers can support whatever set of airports / metropolitan codes their
+ * upstream exposes.
+ */
+export type AirportCode = string;
+/**
+ * IATA two-character airline / marketing carrier code (e.g. `'AA'`,
+ * `'BA'`, `'AF'`).
+ */
+export type CarrierCode = string;
+/**
+ * ISO 8601 calendar date (e.g. `'2026-07-15'`). Time-of-day MUST NOT be
+ * included; this is a date for searching availability, not a timestamp.
+ */
+export type IsoDate = string;
+/**
+ * ISO 8601 instant including timezone offset
+ * (e.g. `'2026-07-15T08:30:00+02:00'`).
+ *
+ * Providers SHOULD preserve the upstream offset where available; consumers
+ * that want a `Date` can `new Date(value)` it.
+ */
+export type IsoDateTime = string;
+/**
+ * ISO 8601 duration string (e.g. `'PT2H30M'`, `'PT11H45M'`).
+ *
+ * Plain string for the same reason as {@link IsoDate} — providers differ on
+ * whether they expose seconds-precision, fractional minutes, etc.
+ */
+export type IsoDuration = string;
+/**
+ * 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.
+ */
+export type CurrencyCode = string;
+/**
+ * Provider-specific offer identifier.
+ *
+ * Opaque token returned by {@link FlightsProvider.searchFlights} that can
+ * be passed back to {@link FlightsProvider.getOffer} or
+ * {@link FlightsProvider.priceOffer}. Identifier scheme is provider-defined
+ * and MUST NOT be parsed by consumers.
+ */
+export type OfferId = string;
+/**
+ * Cabin class enumeration.
+ *
+ * Providers map each value onto whatever upstream code they require
+ * (e.g. Amadeus uses `'ECONOMY' | 'PREMIUM_ECONOMY' | 'BUSINESS' | 'FIRST'`).
+ */
+export type CabinClass = 'economy' | 'premium-economy' | 'business' | 'first';
+/**
+ * One leg of a {@link FlightOffer} — a single take-off / landing pair on a
+ * single operated flight.
+ */
+export 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;
+}
+/**
+ * Departure or arrival point on a {@link Segment}.
+ */
+export 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;
+}
+/**
+ * Normalized flight offer returned by
+ * {@link FlightsProvider.searchFlights}.
+ */
+export interface FlightOffer {
+    /**
+     * Provider-specific opaque offer identifier.
+     */
+    id: OfferId;
+    /**
+     * Total grand-total price for ALL passengers in {@link currency}.
+     */
+    price: number;
+    /**
+     * Currency the {@link price} is expressed in (e.g. `'USD'`).
+     */
+    currency: CurrencyCode;
+    /**
+     * Flight segments, in chronological order. For round-trip itineraries
+     * outbound segments precede return segments. For multi-city the order
+     * matches the requested itinerary.
+     */
+    segments: Segment[];
+    /**
+     * Total elapsed time across all segments (including layovers).
+     */
+    duration: IsoDuration;
+}
+/**
+ * Detailed flight offer returned by {@link FlightsProvider.getOffer}.
+ *
+ * Extends {@link FlightOffer} with a per-passenger price breakdown and an
+ * optional source-data envelope. Providers that do not naturally support a
+ * "fetch single offer" call MAY return the same offer they previously
+ * returned from `searchFlights` here (without a fresh upstream round-trip).
+ */
+export interface FlightOfferDetail extends FlightOffer {
+    /**
+     * Per-passenger price breakdown rows. `null` when the upstream does not
+     * supply the breakdown.
+     */
+    travelerPricings?: TravelerPricing[] | null;
+}
+/**
+ * Per-passenger price row inside {@link FlightOfferDetail.travelerPricings}.
+ */
+export interface TravelerPricing {
+    /**
+     * Provider-specific traveler id (typically a 1-indexed string).
+     */
+    travelerId: string;
+    /**
+     * 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.
+     */
+    travelerType: 'adult' | 'child' | 'held-infant' | 'seated-infant';
+    /**
+     * Total price for this traveler in the offer's currency.
+     */
+    price: number;
+    /**
+     * Cabin class booked for this traveler. `null` when mixed across
+     * segments or not supplied.
+     */
+    cabin?: CabinClass | null;
+}
+/**
+ * Result returned by {@link FlightsProvider.priceOffer}.
+ *
+ * The `price` and `currency` reflect the upstream's authoritative price as
+ * of the moment of the call — providers MAY return a different price than
+ * the original {@link FlightOffer.price} if availability or fare rules
+ * have shifted between search and pricing.
+ */
+export interface PricingResult {
+    /**
+     * Original opaque offer identifier the call was made for.
+     */
+    offerId: OfferId;
+    /**
+     * Authoritative grand-total price as of the moment of pricing.
+     */
+    price: number;
+    /**
+     * Currency the {@link price} is expressed in.
+     */
+    currency: CurrencyCode;
+    /**
+     * Per-passenger price breakdown rows. `null` when the upstream does not
+     * supply the breakdown.
+     */
+    travelerPricings?: TravelerPricing[] | null;
+    /**
+     * Timestamp the pricing snapshot was observed/published.
+     */
+    pricedAt: Date;
+}
+/**
+ * Options accepted by {@link FlightsProvider.searchFlights}.
+ */
+export interface SearchFlightsOptions {
+    /**
+     * Origin IATA airport / city code (e.g. `'JFK'`, `'NYC'`).
+     */
+    origin: AirportCode;
+    /**
+     * Destination IATA airport / city code.
+     */
+    destination: AirportCode;
+    /**
+     * Outbound departure date (ISO 8601 calendar date, e.g. `'2026-07-15'`).
+     */
+    departureDate: IsoDate;
+    /**
+     * Return date for round-trip searches. Omit for one-way.
+     */
+    returnDate?: IsoDate;
+    /**
+     * Adult passenger count (>=12 years). Defaults to `1` when omitted.
+     */
+    adults?: number;
+    /**
+     * Child passenger count (2-11 years). Defaults to `0` when omitted.
+     */
+    children?: number;
+    /**
+     * Infant passenger count (<2 years, lap or seated). Defaults to `0`
+     * when omitted.
+     */
+    infants?: number;
+    /**
+     * Cabin class to search for. Defaults to `'economy'` when omitted.
+     */
+    cabin?: CabinClass;
+    /**
+     * Maximum number of offers to return. Implementations MAY clamp this
+     * to whatever upper bound their upstream API enforces.
+     */
+    maxResults?: number;
+}
+/**
+ * Flights provider interface.
+ *
+ * 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.
+ */
+export interface FlightsProvider {
+    /**
+     * 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.
+     */
+    searchFlights(options: SearchFlightsOptions): Promise<FlightOffer[]>;
+    /**
+     * 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.
+     */
+    getOffer(offerId: OfferId): Promise<FlightOfferDetail>;
+    /**
+     * 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.
+     */
+    priceOffer(offerId: OfferId): Promise<PricingResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the flights core interface.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@molecule/api-flights",
+  "version": "1.0.0",
+  "description": "Flight search + offer pricing core interface for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "flights",
+    "travel",
+    "search",
+    "pricing"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-i18n": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/flights"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/core/flights",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}