boostedtravel 0.2.1 → 0.2.3

package/dist/{chunk-AVADUS2V.mjs → chunk-RJB7OAS2.mjs}

@@ -1,26 +1,111 @@
 // src/index.ts
+var ErrorCode = {
+  // Transient (safe to retry after short delay)
+  SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT",
+  RATE_LIMITED: "RATE_LIMITED",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  // Validation (fix input, then retry)
+  INVALID_IATA: "INVALID_IATA",
+  INVALID_DATE: "INVALID_DATE",
+  INVALID_PASSENGERS: "INVALID_PASSENGERS",
+  UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE",
+  MISSING_PARAMETER: "MISSING_PARAMETER",
+  INVALID_PARAMETER: "INVALID_PARAMETER",
+  // Business (requires human decision)
+  AUTH_INVALID: "AUTH_INVALID",
+  PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
+  PAYMENT_DECLINED: "PAYMENT_DECLINED",
+  OFFER_EXPIRED: "OFFER_EXPIRED",
+  OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED",
+  FARE_CHANGED: "FARE_CHANGED",
+  ALREADY_BOOKED: "ALREADY_BOOKED",
+  BOOKING_FAILED: "BOOKING_FAILED"
+};
+var ErrorCategory = {
+  TRANSIENT: "transient",
+  VALIDATION: "validation",
+  BUSINESS: "business"
+};
+var CODE_TO_CATEGORY = {
+  [ErrorCode.SUPPLIER_TIMEOUT]: ErrorCategory.TRANSIENT,
+  [ErrorCode.RATE_LIMITED]: ErrorCategory.TRANSIENT,
+  [ErrorCode.SERVICE_UNAVAILABLE]: ErrorCategory.TRANSIENT,
+  [ErrorCode.NETWORK_ERROR]: ErrorCategory.TRANSIENT,
+  [ErrorCode.INVALID_IATA]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_DATE]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_PASSENGERS]: ErrorCategory.VALIDATION,
+  [ErrorCode.UNSUPPORTED_ROUTE]: ErrorCategory.VALIDATION,
+  [ErrorCode.MISSING_PARAMETER]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_PARAMETER]: ErrorCategory.VALIDATION,
+  [ErrorCode.AUTH_INVALID]: ErrorCategory.BUSINESS,
+  [ErrorCode.PAYMENT_REQUIRED]: ErrorCategory.BUSINESS,
+  [ErrorCode.PAYMENT_DECLINED]: ErrorCategory.BUSINESS,
+  [ErrorCode.OFFER_EXPIRED]: ErrorCategory.BUSINESS,
+  [ErrorCode.OFFER_NOT_UNLOCKED]: ErrorCategory.BUSINESS,
+  [ErrorCode.FARE_CHANGED]: ErrorCategory.BUSINESS,
+  [ErrorCode.ALREADY_BOOKED]: ErrorCategory.BUSINESS,
+  [ErrorCode.BOOKING_FAILED]: ErrorCategory.BUSINESS
+};
+function inferErrorCode(statusCode, detail) {
+  const d = detail.toLowerCase();
+  if (statusCode === 401) return ErrorCode.AUTH_INVALID;
+  if (statusCode === 402) return d.includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
+  if (statusCode === 410) return ErrorCode.OFFER_EXPIRED;
+  if (statusCode === 422) {
+    if (d.includes("iata") || d.includes("airport")) return ErrorCode.INVALID_IATA;
+    if (d.includes("date")) return ErrorCode.INVALID_DATE;
+    if (d.includes("passenger")) return ErrorCode.INVALID_PASSENGERS;
+    if (d.includes("route")) return ErrorCode.UNSUPPORTED_ROUTE;
+    return ErrorCode.INVALID_PARAMETER;
+  }
+  if (statusCode === 429) return ErrorCode.RATE_LIMITED;
+  if (statusCode === 503) return ErrorCode.SERVICE_UNAVAILABLE;
+  if (statusCode === 504) return ErrorCode.SUPPLIER_TIMEOUT;
+  if (statusCode === 409) return ErrorCode.ALREADY_BOOKED;
+  return statusCode >= 500 ? ErrorCode.BOOKING_FAILED : ErrorCode.INVALID_PARAMETER;
+}
 var BoostedTravelError = class extends Error {
   statusCode;
   response;
-  constructor(message, statusCode = 0, response = {}) {
+  errorCode;
+  errorCategory;
+  isRetryable;
+  constructor(message, statusCode = 0, response = {}, errorCode = "") {
     super(message);
     this.name = "BoostedTravelError";
     this.statusCode = statusCode;
     this.response = response;
+    this.errorCode = errorCode || response.error_code || "";
+    this.errorCategory = CODE_TO_CATEGORY[this.errorCode] || ErrorCategory.BUSINESS;
+    this.isRetryable = this.errorCategory === ErrorCategory.TRANSIENT;
   }
 };
 var AuthenticationError = class extends BoostedTravelError {
   constructor(message, response = {}) {
-    super(message, 401, response);
+    super(message, 401, response, ErrorCode.AUTH_INVALID);
     this.name = "AuthenticationError";
   }
 };
 var PaymentRequiredError = class extends BoostedTravelError {
   constructor(message, response = {}) {
-    super(message, 402, response);
+    const code = message.toLowerCase().includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
+    super(message, 402, response, code);
     this.name = "PaymentRequiredError";
   }
 };
+var OfferExpiredError = class extends BoostedTravelError {
+  constructor(message, response = {}) {
+    super(message, 410, response, ErrorCode.OFFER_EXPIRED);
+    this.name = "OfferExpiredError";
+  }
+};
+var ValidationError = class extends BoostedTravelError {
+  constructor(message, statusCode = 422, response = {}, errorCode = "") {
+    super(message, statusCode, response, errorCode || ErrorCode.INVALID_PARAMETER);
+    this.name = "ValidationError";
+  }
+};
 function routeStr(route) {
   if (!route.segments.length) return "";
   const codes = [route.segments[0].origin, ...route.segments.map((s) => s.destination)];
@@ -154,16 +239,20 @@ var BoostedTravel = class {
   /**
    * Book a flight — FREE after unlock.
    * Creates a real airline reservation with PNR.
+   *
+   * Always provide idempotencyKey to prevent double-bookings on retry.
    */
-  async book(offerId, passengers, contactEmail, contactPhone = "") {
+  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
     this.requireApiKey();
-    return this.post("/api/v1/bookings/book", {
+    const body = {
       offer_id: offerId,
       booking_type: "flight",
       passengers,
       contact_email: contactEmail,
       contact_phone: contactPhone
-    });
+    };
+    if (idempotencyKey) body.idempotency_key = idempotencyKey;
+    return this.post("/api/v1/bookings/book", body);
   }
   /**
    * Set up payment method (payment token).
@@ -232,9 +321,12 @@ var BoostedTravel = class {
       const data = await resp.json();
       if (!resp.ok) {
         const detail = data.detail || `API error (${resp.status})`;
+        const code = data.error_code || inferErrorCode(resp.status, detail);
         if (resp.status === 401) throw new AuthenticationError(detail, data);
         if (resp.status === 402) throw new PaymentRequiredError(detail, data);
-        throw new BoostedTravelError(detail, resp.status, data);
+        if (resp.status === 410) throw new OfferExpiredError(detail, data);
+        if (resp.status === 422) throw new ValidationError(detail, resp.status, data, code);
+        throw new BoostedTravelError(detail, resp.status, data, code);
       }
       return data;
     } finally {
@@ -245,9 +337,13 @@ var BoostedTravel = class {
 var index_default = BoostedTravel;
 
 export {
+  ErrorCode,
+  ErrorCategory,
   BoostedTravelError,
   AuthenticationError,
   PaymentRequiredError,
+  OfferExpiredError,
+  ValidationError,
   offerSummary,
   cheapestOffer,
   searchLocal,

package/dist/cli.js

@@ -2,28 +2,113 @@
 "use strict";
 
 // src/index.ts
+var ErrorCode = {
+  // Transient (safe to retry after short delay)
+  SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT",
+  RATE_LIMITED: "RATE_LIMITED",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  // Validation (fix input, then retry)
+  INVALID_IATA: "INVALID_IATA",
+  INVALID_DATE: "INVALID_DATE",
+  INVALID_PASSENGERS: "INVALID_PASSENGERS",
+  UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE",
+  MISSING_PARAMETER: "MISSING_PARAMETER",
+  INVALID_PARAMETER: "INVALID_PARAMETER",
+  // Business (requires human decision)
+  AUTH_INVALID: "AUTH_INVALID",
+  PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
+  PAYMENT_DECLINED: "PAYMENT_DECLINED",
+  OFFER_EXPIRED: "OFFER_EXPIRED",
+  OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED",
+  FARE_CHANGED: "FARE_CHANGED",
+  ALREADY_BOOKED: "ALREADY_BOOKED",
+  BOOKING_FAILED: "BOOKING_FAILED"
+};
+var ErrorCategory = {
+  TRANSIENT: "transient",
+  VALIDATION: "validation",
+  BUSINESS: "business"
+};
+var CODE_TO_CATEGORY = {
+  [ErrorCode.SUPPLIER_TIMEOUT]: ErrorCategory.TRANSIENT,
+  [ErrorCode.RATE_LIMITED]: ErrorCategory.TRANSIENT,
+  [ErrorCode.SERVICE_UNAVAILABLE]: ErrorCategory.TRANSIENT,
+  [ErrorCode.NETWORK_ERROR]: ErrorCategory.TRANSIENT,
+  [ErrorCode.INVALID_IATA]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_DATE]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_PASSENGERS]: ErrorCategory.VALIDATION,
+  [ErrorCode.UNSUPPORTED_ROUTE]: ErrorCategory.VALIDATION,
+  [ErrorCode.MISSING_PARAMETER]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_PARAMETER]: ErrorCategory.VALIDATION,
+  [ErrorCode.AUTH_INVALID]: ErrorCategory.BUSINESS,
+  [ErrorCode.PAYMENT_REQUIRED]: ErrorCategory.BUSINESS,
+  [ErrorCode.PAYMENT_DECLINED]: ErrorCategory.BUSINESS,
+  [ErrorCode.OFFER_EXPIRED]: ErrorCategory.BUSINESS,
+  [ErrorCode.OFFER_NOT_UNLOCKED]: ErrorCategory.BUSINESS,
+  [ErrorCode.FARE_CHANGED]: ErrorCategory.BUSINESS,
+  [ErrorCode.ALREADY_BOOKED]: ErrorCategory.BUSINESS,
+  [ErrorCode.BOOKING_FAILED]: ErrorCategory.BUSINESS
+};
+function inferErrorCode(statusCode, detail) {
+  const d = detail.toLowerCase();
+  if (statusCode === 401) return ErrorCode.AUTH_INVALID;
+  if (statusCode === 402) return d.includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
+  if (statusCode === 410) return ErrorCode.OFFER_EXPIRED;
+  if (statusCode === 422) {
+    if (d.includes("iata") || d.includes("airport")) return ErrorCode.INVALID_IATA;
+    if (d.includes("date")) return ErrorCode.INVALID_DATE;
+    if (d.includes("passenger")) return ErrorCode.INVALID_PASSENGERS;
+    if (d.includes("route")) return ErrorCode.UNSUPPORTED_ROUTE;
+    return ErrorCode.INVALID_PARAMETER;
+  }
+  if (statusCode === 429) return ErrorCode.RATE_LIMITED;
+  if (statusCode === 503) return ErrorCode.SERVICE_UNAVAILABLE;
+  if (statusCode === 504) return ErrorCode.SUPPLIER_TIMEOUT;
+  if (statusCode === 409) return ErrorCode.ALREADY_BOOKED;
+  return statusCode >= 500 ? ErrorCode.BOOKING_FAILED : ErrorCode.INVALID_PARAMETER;
+}
 var BoostedTravelError = class extends Error {
   statusCode;
   response;
-  constructor(message, statusCode = 0, response = {}) {
+  errorCode;
+  errorCategory;
+  isRetryable;
+  constructor(message, statusCode = 0, response = {}, errorCode = "") {
     super(message);
     this.name = "BoostedTravelError";
     this.statusCode = statusCode;
     this.response = response;
+    this.errorCode = errorCode || response.error_code || "";
+    this.errorCategory = CODE_TO_CATEGORY[this.errorCode] || ErrorCategory.BUSINESS;
+    this.isRetryable = this.errorCategory === ErrorCategory.TRANSIENT;
   }
 };
 var AuthenticationError = class extends BoostedTravelError {
   constructor(message, response = {}) {
-    super(message, 401, response);
+    super(message, 401, response, ErrorCode.AUTH_INVALID);
     this.name = "AuthenticationError";
   }
 };
 var PaymentRequiredError = class extends BoostedTravelError {
   constructor(message, response = {}) {
-    super(message, 402, response);
+    const code = message.toLowerCase().includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
+    super(message, 402, response, code);
     this.name = "PaymentRequiredError";
   }
 };
+var OfferExpiredError = class extends BoostedTravelError {
+  constructor(message, response = {}) {
+    super(message, 410, response, ErrorCode.OFFER_EXPIRED);
+    this.name = "OfferExpiredError";
+  }
+};
+var ValidationError = class extends BoostedTravelError {
+  constructor(message, statusCode = 422, response = {}, errorCode = "") {
+    super(message, statusCode, response, errorCode || ErrorCode.INVALID_PARAMETER);
+    this.name = "ValidationError";
+  }
+};
 function routeStr(route) {
   if (!route.segments.length) return "";
   const codes = [route.segments[0].origin, ...route.segments.map((s) => s.destination)];
@@ -105,16 +190,20 @@ var BoostedTravel = class {
   /**
    * Book a flight — FREE after unlock.
    * Creates a real airline reservation with PNR.
+   *
+   * Always provide idempotencyKey to prevent double-bookings on retry.
    */
-  async book(offerId, passengers, contactEmail, contactPhone = "") {
+  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
     this.requireApiKey();
-    return this.post("/api/v1/bookings/book", {
+    const body = {
       offer_id: offerId,
       booking_type: "flight",
       passengers,
       contact_email: contactEmail,
       contact_phone: contactPhone
-    });
+    };
+    if (idempotencyKey) body.idempotency_key = idempotencyKey;
+    return this.post("/api/v1/bookings/book", body);
   }
   /**
    * Set up payment method (payment token).
@@ -183,9 +272,12 @@ var BoostedTravel = class {
       const data = await resp.json();
       if (!resp.ok) {
         const detail = data.detail || `API error (${resp.status})`;
+        const code = data.error_code || inferErrorCode(resp.status, detail);
         if (resp.status === 401) throw new AuthenticationError(detail, data);
         if (resp.status === 402) throw new PaymentRequiredError(detail, data);
-        throw new BoostedTravelError(detail, resp.status, data);
+        if (resp.status === 410) throw new OfferExpiredError(detail, data);
+        if (resp.status === 422) throw new ValidationError(detail, resp.status, data, code);
+        throw new BoostedTravelError(detail, resp.status, data, code);
       }
       return data;
     } finally {

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   BoostedTravel,
   BoostedTravelError,
   offerSummary
-} from "./chunk-AVADUS2V.mjs";
+} from "./chunk-RJB7OAS2.mjs";
 
 // src/cli.ts
 function getFlag(args, flag, alias) {

package/dist/index.d.mts

@@ -118,10 +118,40 @@ interface BoostedTravelConfig {
     baseUrl?: string;
     timeout?: number;
 }
+declare const ErrorCode: {
+    readonly SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly INVALID_IATA: "INVALID_IATA";
+    readonly INVALID_DATE: "INVALID_DATE";
+    readonly INVALID_PASSENGERS: "INVALID_PASSENGERS";
+    readonly UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE";
+    readonly MISSING_PARAMETER: "MISSING_PARAMETER";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly AUTH_INVALID: "AUTH_INVALID";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly PAYMENT_DECLINED: "PAYMENT_DECLINED";
+    readonly OFFER_EXPIRED: "OFFER_EXPIRED";
+    readonly OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED";
+    readonly FARE_CHANGED: "FARE_CHANGED";
+    readonly ALREADY_BOOKED: "ALREADY_BOOKED";
+    readonly BOOKING_FAILED: "BOOKING_FAILED";
+};
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare const ErrorCategory: {
+    readonly TRANSIENT: "transient";
+    readonly VALIDATION: "validation";
+    readonly BUSINESS: "business";
+};
+type ErrorCategoryType = (typeof ErrorCategory)[keyof typeof ErrorCategory];
 declare class BoostedTravelError extends Error {
     statusCode: number;
     response: Record<string, unknown>;
-    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+    errorCode: string;
+    errorCategory: ErrorCategoryType;
+    isRetryable: boolean;
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>, errorCode?: string);
 }
 declare class AuthenticationError extends BoostedTravelError {
     constructor(message: string, response?: Record<string, unknown>);
@@ -129,6 +159,12 @@ declare class AuthenticationError extends BoostedTravelError {
 declare class PaymentRequiredError extends BoostedTravelError {
     constructor(message: string, response?: Record<string, unknown>);
 }
+declare class OfferExpiredError extends BoostedTravelError {
+    constructor(message: string, response?: Record<string, unknown>);
+}
+declare class ValidationError extends BoostedTravelError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>, errorCode?: string);
+}
 /** One-line offer summary */
 declare function offerSummary(offer: FlightOffer): string;
 /** Get cheapest offer from search results */
@@ -171,8 +207,10 @@ declare class BoostedTravel {
     /**
      * Book a flight — FREE after unlock.
      * Creates a real airline reservation with PNR.
+     *
+     * Always provide idempotencyKey to prevent double-bookings on retry.
      */
-    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string): Promise<BookingResult>;
+    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
     /**
      * Set up payment method (payment token).
      */
@@ -190,4 +228,4 @@ declare class BoostedTravel {
     private request;
 }
 
-export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, type Passenger, PaymentRequiredError, type SearchOptions, type UnlockResult, cheapestOffer, BoostedTravel as default, searchLocal as localSearch, offerSummary, searchLocal };
+export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, OfferExpiredError, type Passenger, PaymentRequiredError, type SearchOptions, type UnlockResult, ValidationError, cheapestOffer, BoostedTravel as default, searchLocal as localSearch, offerSummary, searchLocal };

package/dist/index.d.ts

@@ -118,10 +118,40 @@ interface BoostedTravelConfig {
     baseUrl?: string;
     timeout?: number;
 }
+declare const ErrorCode: {
+    readonly SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly INVALID_IATA: "INVALID_IATA";
+    readonly INVALID_DATE: "INVALID_DATE";
+    readonly INVALID_PASSENGERS: "INVALID_PASSENGERS";
+    readonly UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE";
+    readonly MISSING_PARAMETER: "MISSING_PARAMETER";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly AUTH_INVALID: "AUTH_INVALID";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly PAYMENT_DECLINED: "PAYMENT_DECLINED";
+    readonly OFFER_EXPIRED: "OFFER_EXPIRED";
+    readonly OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED";
+    readonly FARE_CHANGED: "FARE_CHANGED";
+    readonly ALREADY_BOOKED: "ALREADY_BOOKED";
+    readonly BOOKING_FAILED: "BOOKING_FAILED";
+};
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare const ErrorCategory: {
+    readonly TRANSIENT: "transient";
+    readonly VALIDATION: "validation";
+    readonly BUSINESS: "business";
+};
+type ErrorCategoryType = (typeof ErrorCategory)[keyof typeof ErrorCategory];
 declare class BoostedTravelError extends Error {
     statusCode: number;
     response: Record<string, unknown>;
-    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+    errorCode: string;
+    errorCategory: ErrorCategoryType;
+    isRetryable: boolean;
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>, errorCode?: string);
 }
 declare class AuthenticationError extends BoostedTravelError {
     constructor(message: string, response?: Record<string, unknown>);
@@ -129,6 +159,12 @@ declare class AuthenticationError extends BoostedTravelError {
 declare class PaymentRequiredError extends BoostedTravelError {
     constructor(message: string, response?: Record<string, unknown>);
 }
+declare class OfferExpiredError extends BoostedTravelError {
+    constructor(message: string, response?: Record<string, unknown>);
+}
+declare class ValidationError extends BoostedTravelError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>, errorCode?: string);
+}
 /** One-line offer summary */
 declare function offerSummary(offer: FlightOffer): string;
 /** Get cheapest offer from search results */
@@ -171,8 +207,10 @@ declare class BoostedTravel {
     /**
      * Book a flight — FREE after unlock.
      * Creates a real airline reservation with PNR.
+     *
+     * Always provide idempotencyKey to prevent double-bookings on retry.
      */
-    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string): Promise<BookingResult>;
+    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
     /**
      * Set up payment method (payment token).
      */
@@ -190,4 +228,4 @@ declare class BoostedTravel {
     private request;
 }
 
-export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, type Passenger, PaymentRequiredError, type SearchOptions, type UnlockResult, cheapestOffer, BoostedTravel as default, searchLocal as localSearch, offerSummary, searchLocal };
+export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, OfferExpiredError, type Passenger, PaymentRequiredError, type SearchOptions, type UnlockResult, ValidationError, cheapestOffer, BoostedTravel as default, searchLocal as localSearch, offerSummary, searchLocal };

package/dist/index.js

@@ -33,7 +33,11 @@ __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   BoostedTravel: () => BoostedTravel,
   BoostedTravelError: () => BoostedTravelError,
+  ErrorCategory: () => ErrorCategory,
+  ErrorCode: () => ErrorCode,
+  OfferExpiredError: () => OfferExpiredError,
   PaymentRequiredError: () => PaymentRequiredError,
+  ValidationError: () => ValidationError,
   cheapestOffer: () => cheapestOffer,
   default: () => index_default,
   localSearch: () => searchLocal,
@@ -41,28 +45,113 @@ __export(index_exports, {
   searchLocal: () => searchLocal
 });
 module.exports = __toCommonJS(index_exports);
+var ErrorCode = {
+  // Transient (safe to retry after short delay)
+  SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT",
+  RATE_LIMITED: "RATE_LIMITED",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  // Validation (fix input, then retry)
+  INVALID_IATA: "INVALID_IATA",
+  INVALID_DATE: "INVALID_DATE",
+  INVALID_PASSENGERS: "INVALID_PASSENGERS",
+  UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE",
+  MISSING_PARAMETER: "MISSING_PARAMETER",
+  INVALID_PARAMETER: "INVALID_PARAMETER",
+  // Business (requires human decision)
+  AUTH_INVALID: "AUTH_INVALID",
+  PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
+  PAYMENT_DECLINED: "PAYMENT_DECLINED",
+  OFFER_EXPIRED: "OFFER_EXPIRED",
+  OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED",
+  FARE_CHANGED: "FARE_CHANGED",
+  ALREADY_BOOKED: "ALREADY_BOOKED",
+  BOOKING_FAILED: "BOOKING_FAILED"
+};
+var ErrorCategory = {
+  TRANSIENT: "transient",
+  VALIDATION: "validation",
+  BUSINESS: "business"
+};
+var CODE_TO_CATEGORY = {
+  [ErrorCode.SUPPLIER_TIMEOUT]: ErrorCategory.TRANSIENT,
+  [ErrorCode.RATE_LIMITED]: ErrorCategory.TRANSIENT,
+  [ErrorCode.SERVICE_UNAVAILABLE]: ErrorCategory.TRANSIENT,
+  [ErrorCode.NETWORK_ERROR]: ErrorCategory.TRANSIENT,
+  [ErrorCode.INVALID_IATA]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_DATE]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_PASSENGERS]: ErrorCategory.VALIDATION,
+  [ErrorCode.UNSUPPORTED_ROUTE]: ErrorCategory.VALIDATION,
+  [ErrorCode.MISSING_PARAMETER]: ErrorCategory.VALIDATION,
+  [ErrorCode.INVALID_PARAMETER]: ErrorCategory.VALIDATION,
+  [ErrorCode.AUTH_INVALID]: ErrorCategory.BUSINESS,
+  [ErrorCode.PAYMENT_REQUIRED]: ErrorCategory.BUSINESS,
+  [ErrorCode.PAYMENT_DECLINED]: ErrorCategory.BUSINESS,
+  [ErrorCode.OFFER_EXPIRED]: ErrorCategory.BUSINESS,
+  [ErrorCode.OFFER_NOT_UNLOCKED]: ErrorCategory.BUSINESS,
+  [ErrorCode.FARE_CHANGED]: ErrorCategory.BUSINESS,
+  [ErrorCode.ALREADY_BOOKED]: ErrorCategory.BUSINESS,
+  [ErrorCode.BOOKING_FAILED]: ErrorCategory.BUSINESS
+};
+function inferErrorCode(statusCode, detail) {
+  const d = detail.toLowerCase();
+  if (statusCode === 401) return ErrorCode.AUTH_INVALID;
+  if (statusCode === 402) return d.includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
+  if (statusCode === 410) return ErrorCode.OFFER_EXPIRED;
+  if (statusCode === 422) {
+    if (d.includes("iata") || d.includes("airport")) return ErrorCode.INVALID_IATA;
+    if (d.includes("date")) return ErrorCode.INVALID_DATE;
+    if (d.includes("passenger")) return ErrorCode.INVALID_PASSENGERS;
+    if (d.includes("route")) return ErrorCode.UNSUPPORTED_ROUTE;
+    return ErrorCode.INVALID_PARAMETER;
+  }
+  if (statusCode === 429) return ErrorCode.RATE_LIMITED;
+  if (statusCode === 503) return ErrorCode.SERVICE_UNAVAILABLE;
+  if (statusCode === 504) return ErrorCode.SUPPLIER_TIMEOUT;
+  if (statusCode === 409) return ErrorCode.ALREADY_BOOKED;
+  return statusCode >= 500 ? ErrorCode.BOOKING_FAILED : ErrorCode.INVALID_PARAMETER;
+}
 var BoostedTravelError = class extends Error {
   statusCode;
   response;
-  constructor(message, statusCode = 0, response = {}) {
+  errorCode;
+  errorCategory;
+  isRetryable;
+  constructor(message, statusCode = 0, response = {}, errorCode = "") {
     super(message);
     this.name = "BoostedTravelError";
     this.statusCode = statusCode;
     this.response = response;
+    this.errorCode = errorCode || response.error_code || "";
+    this.errorCategory = CODE_TO_CATEGORY[this.errorCode] || ErrorCategory.BUSINESS;
+    this.isRetryable = this.errorCategory === ErrorCategory.TRANSIENT;
   }
 };
 var AuthenticationError = class extends BoostedTravelError {
   constructor(message, response = {}) {
-    super(message, 401, response);
+    super(message, 401, response, ErrorCode.AUTH_INVALID);
     this.name = "AuthenticationError";
   }
 };
 var PaymentRequiredError = class extends BoostedTravelError {
   constructor(message, response = {}) {
-    super(message, 402, response);
+    const code = message.toLowerCase().includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
+    super(message, 402, response, code);
     this.name = "PaymentRequiredError";
   }
 };
+var OfferExpiredError = class extends BoostedTravelError {
+  constructor(message, response = {}) {
+    super(message, 410, response, ErrorCode.OFFER_EXPIRED);
+    this.name = "OfferExpiredError";
+  }
+};
+var ValidationError = class extends BoostedTravelError {
+  constructor(message, statusCode = 422, response = {}, errorCode = "") {
+    super(message, statusCode, response, errorCode || ErrorCode.INVALID_PARAMETER);
+    this.name = "ValidationError";
+  }
+};
 function routeStr(route) {
   if (!route.segments.length) return "";
   const codes = [route.segments[0].origin, ...route.segments.map((s) => s.destination)];
@@ -196,16 +285,20 @@ var BoostedTravel = class {
   /**
    * Book a flight — FREE after unlock.
    * Creates a real airline reservation with PNR.
+   *
+   * Always provide idempotencyKey to prevent double-bookings on retry.
    */
-  async book(offerId, passengers, contactEmail, contactPhone = "") {
+  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
     this.requireApiKey();
-    return this.post("/api/v1/bookings/book", {
+    const body = {
       offer_id: offerId,
       booking_type: "flight",
       passengers,
       contact_email: contactEmail,
       contact_phone: contactPhone
-    });
+    };
+    if (idempotencyKey) body.idempotency_key = idempotencyKey;
+    return this.post("/api/v1/bookings/book", body);
   }
   /**
    * Set up payment method (payment token).
@@ -274,9 +367,12 @@ var BoostedTravel = class {
       const data = await resp.json();
       if (!resp.ok) {
         const detail = data.detail || `API error (${resp.status})`;
+        const code = data.error_code || inferErrorCode(resp.status, detail);
         if (resp.status === 401) throw new AuthenticationError(detail, data);
         if (resp.status === 402) throw new PaymentRequiredError(detail, data);
-        throw new BoostedTravelError(detail, resp.status, data);
+        if (resp.status === 410) throw new OfferExpiredError(detail, data);
+        if (resp.status === 422) throw new ValidationError(detail, resp.status, data, code);
+        throw new BoostedTravelError(detail, resp.status, data, code);
       }
       return data;
     } finally {
@@ -290,7 +386,11 @@ var index_default = BoostedTravel;
   AuthenticationError,
   BoostedTravel,
   BoostedTravelError,
+  ErrorCategory,
+  ErrorCode,
+  OfferExpiredError,
   PaymentRequiredError,
+  ValidationError,
   cheapestOffer,
   localSearch,
   offerSummary,

package/dist/index.mjs

@@ -2,17 +2,25 @@ import {
   AuthenticationError,
   BoostedTravel,
   BoostedTravelError,
+  ErrorCategory,
+  ErrorCode,
+  OfferExpiredError,
   PaymentRequiredError,
+  ValidationError,
   cheapestOffer,
   index_default,
   offerSummary,
   searchLocal
-} from "./chunk-AVADUS2V.mjs";
+} from "./chunk-RJB7OAS2.mjs";
 export {
   AuthenticationError,
   BoostedTravel,
   BoostedTravelError,
+  ErrorCategory,
+  ErrorCode,
+  OfferExpiredError,
   PaymentRequiredError,
+  ValidationError,
   cheapestOffer,
   index_default as default,
   searchLocal as localSearch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boostedtravel",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Agent-native flight search & booking. 48 LCC scrapers run locally + GDS/NDC APIs. Built for autonomous AI agents.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",