mts-booking-library 3.5.0 → 3.7.0

package/lib/booking/journeyBooking.d.ts

@@ -12,6 +12,17 @@ type JourneyLineRouteFilters = {
     lineId?: number | null;
     routeId?: number | null;
 };
+/**
+ * A stop with optional metadata. `region` and `hint` may be null when the
+ * backend has no Province / City data for the underlying physical stop.
+ * Returned by {@link JourneyBooking.getJourneysDeparturesEnriched} and
+ * {@link JourneyBooking.getJourneysDestinationsEnriched}.
+ */
+export type EnrichedStop = {
+    name: string;
+    region?: string | null;
+    hint?: string | null;
+};
 export declare class JourneyBooking extends Booking {
     private cart?;
     /**
@@ -121,12 +132,25 @@ export declare class JourneyBooking extends Booking {
      * @returns The list of possible departures
      */
     getJourneysDepartures(filtersOrOptions?: JourneyLineRouteFilters | ApiCallOptions, options?: ApiCallOptions): Promise<ErrorResponse | string[]>;
+    /**
+     * Like {@link getJourneysDepartures}, but returns the enriched representation
+     * (name + optional region + optional hint) when the backend exposes it.
+     * Falls back to a flat {name}-only list when the backend response only
+     * carries the legacy `stops` field. Separate from the original method to
+     * avoid breaking the existing `string[]` contract used by other clients.
+     */
+    getJourneysDeparturesEnriched(filtersOrOptions?: JourneyLineRouteFilters | ApiCallOptions, options?: ApiCallOptions): Promise<ErrorResponse | EnrichedStop[]>;
     /**
      * This method returns the possible destination for the journeys sold by this seller that start at the selected departure.
      * @param departureStopName The departure stop name (as returned by {@link getJourneysDepartures})
      * @returns The list of possible destinations
      */
     getJourneysDestinations(departureStopName: string, filtersOrOptions?: JourneyLineRouteFilters | ApiCallOptions, options?: ApiCallOptions): Promise<ErrorResponse | string[]>;
+    /**
+     * Like {@link getJourneysDestinations}, but returns the enriched
+     * representation (see {@link getJourneysDeparturesEnriched}).
+     */
+    getJourneysDestinationsEnriched(departureStopName: string, filtersOrOptions?: JourneyLineRouteFilters | ApiCallOptions, options?: ApiCallOptions): Promise<ErrorResponse | EnrichedStop[]>;
     /**
      * This method returns the journeys that match the given parameters.
      * Note that it will always return the journeys for the one-way trip.

package/lib/booking/journeyBooking.js

@@ -81,6 +81,24 @@ var utils_1 = require("../utils/utils");
 var booking_1 = require("./booking");
 var isJourneyLineRouteFilters = function (value) { return !!value && ("lineId" in value || "routeId" in value); };
 var getJourneyLineRouteParams = function (filters) { return (__assign(__assign({}, ((filters === null || filters === void 0 ? void 0 : filters.lineId) && { lineId: filters.lineId.toString() })), ((filters === null || filters === void 0 ? void 0 : filters.routeId) && { routeId: filters.routeId.toString() }))); };
+var isEnrichedStop = function (x) {
+    return typeof x === "object" && x !== null && typeof x.name === "string";
+};
+/**
+ * Parses the booking-API stop response into the enriched shape. When the
+ * backend doesn't populate `stopsEnriched` (older deployment), reconstructs
+ * a minimal `{name}` list from the flat `stops` array so callers always
+ * receive the same shape.
+ */
+var enrichedStopsFromResponse = function (response) {
+    var _a;
+    var enriched = Array.isArray(response.stopsEnriched)
+        ? response.stopsEnriched.filter(isEnrichedStop)
+        : [];
+    if (enriched.length > 0)
+        return enriched;
+    return ((_a = response.stops) !== null && _a !== void 0 ? _a : []).map(function (name) { return ({ name: name }); });
+};
 var JourneyBooking = /** @class */ (function (_super) {
     __extends(JourneyBooking, _super);
     /**
@@ -235,6 +253,29 @@ var JourneyBooking = /** @class */ (function (_super) {
             });
         });
     };
+    /**
+     * Like {@link getJourneysDepartures}, but returns the enriched representation
+     * (name + optional region + optional hint) when the backend exposes it.
+     * Falls back to a flat {name}-only list when the backend response only
+     * carries the legacy `stops` field. Separate from the original method to
+     * avoid breaking the existing `string[]` contract used by other clients.
+     */
+    JourneyBooking.prototype.getJourneysDeparturesEnriched = function (filtersOrOptions, options) {
+        return __awaiter(this, void 0, void 0, function () {
+            var filters, requestOptions, searchParams, url;
+            return __generator(this, function (_a) {
+                filters = isJourneyLineRouteFilters(filtersOrOptions) ? filtersOrOptions : undefined;
+                requestOptions = isJourneyLineRouteFilters(filtersOrOptions) ? options : filtersOrOptions;
+                searchParams = new URLSearchParams(getJourneyLineRouteParams(filters));
+                url = "".concat(this.config.API_ENDPOINT, "/v3_booking/journeys/departures?").concat(searchParams);
+                return [2 /*return*/, this.callGetApi(url, requestOptions).then(function (response) {
+                        if ((0, ErrorResponse_1.objectIsMTSErrorResponse)(response))
+                            return response;
+                        return enrichedStopsFromResponse(response);
+                    })];
+            });
+        });
+    };
     /**
      * This method returns the possible destination for the journeys sold by this seller that start at the selected departure.
      * @param departureStopName The departure stop name (as returned by {@link getJourneysDepartures})
@@ -254,6 +295,26 @@ var JourneyBooking = /** @class */ (function (_super) {
             });
         });
     };
+    /**
+     * Like {@link getJourneysDestinations}, but returns the enriched
+     * representation (see {@link getJourneysDeparturesEnriched}).
+     */
+    JourneyBooking.prototype.getJourneysDestinationsEnriched = function (departureStopName, filtersOrOptions, options) {
+        return __awaiter(this, void 0, void 0, function () {
+            var filters, requestOptions, searchParams, url;
+            return __generator(this, function (_a) {
+                filters = isJourneyLineRouteFilters(filtersOrOptions) ? filtersOrOptions : undefined;
+                requestOptions = isJourneyLineRouteFilters(filtersOrOptions) ? options : filtersOrOptions;
+                searchParams = new URLSearchParams(__assign({ departureStopName: departureStopName }, getJourneyLineRouteParams(filters)));
+                url = "".concat(this.config.API_ENDPOINT, "/v3_booking/journeys/destinations?").concat(searchParams);
+                return [2 /*return*/, this.callGetApi(url, requestOptions).then(function (response) {
+                        if ((0, ErrorResponse_1.objectIsMTSErrorResponse)(response))
+                            return response;
+                        return enrichedStopsFromResponse(response);
+                    })];
+            });
+        });
+    };
     /**
      * This method returns the journeys that match the given parameters.
      * Note that it will always return the journeys for the one-way trip.

package/lib/booking/tplBooking.js

@@ -253,7 +253,7 @@ var TplBooking = /** @class */ (function (_super) {
         return __awaiter(this, void 0, void 0, function () {
             var searchParams, url;
             return __generator(this, function (_a) {
-                searchParams = new URLSearchParams(__assign(__assign(__assign({ includeBasicInfo: "true", includeImage: "true", includeAreaIds: "false", includeTariffIds: "false", includeRouteIds: "false", includeMultilingualDescriptions: "false" }, (request.cityId && { cityId: request.cityId.toString() })), (request.tripId && { tripId: request.tripId.toString() })), (request.type && { type: request.type })));
+                searchParams = new URLSearchParams(__assign(__assign(__assign({ includeBasicInfo: "true", includeImage: "true", includeAreaIds: "false", includeTariffIds: "false", includeRouteIds: "false", includeMultilingualDescriptions: request.includeMultilingualDescriptions ? "true" : "false" }, (request.cityId && { cityId: request.cityId.toString() })), (request.tripId && { tripId: request.tripId.toString() })), (request.type && { type: request.type })));
                 url = "".concat(this.config.API_ENDPOINT, "/v3_resources/superAreas?").concat(searchParams);
                 return [2 /*return*/, this.callGetApi(url, options).then(function (response) {
                         return (0, ErrorResponse_1.objectIsMTSErrorResponse)(response) ? response : response.superAreas;

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { Booking } from "./booking/booking";
-export { JourneyBooking } from "./booking/journeyBooking";
+export { JourneyBooking, EnrichedStop } from "./booking/journeyBooking";
 export { ServiceBooking } from "./booking/serviceBooking";
 export { SubscriptionBooking } from "./booking/subscriptionBooking";
 export { TplBooking } from "./booking/tplBooking";
@@ -27,7 +27,7 @@ export { Service, ServiceTrip } from "./types/services/Service";
 export { ServiceCart, ServiceBookingType } from "./types/services/ServiceCart";
 export { ServiceInfo } from "./types/services/ServiceInfo";
 export { GetTariffsResponse } from "./types/tpl/GetTariffsResponse";
-export { SuperArea, GetSuperAreasRequest, GetCitiesRequest, SuperAreasTypeFilter } from "./types/tpl/SuperArea";
+export { SuperArea, MTSStringDTO, GetSuperAreasRequest, GetCitiesRequest, SuperAreasTypeFilter } from "./types/tpl/SuperArea";
 export { TplCart, TplBookingType, TplBookingInfo } from "./types/tpl/TplCart";
 export { Subscription } from "./types/subscriptions/Subscriptions";
 export { GetSubscriptionAvailabilityRequest, GetSubscriptionAvailabilityResponse, SubscriptionCalendarDayPeriodInfo } from "./types/subscriptions/SubscriptionAvailabilities";

package/lib/types/tpl/SuperArea.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Multilingual string returned by the backend. Each key holds the
+ * translation for that language; consumers should fall back to `it`
+ * when the active language is missing, matching the backend's
+ * `MTSStringDTO.GetValue` resolution rules.
+ */
+export type MTSStringDTO = {
+    en: string | null;
+    it: string | null;
+    fr: string | null;
+    de: string | null;
+    es: string | null;
+};
 /** This type represents a super area. It is the return object of the {@link TplBooking.getSuperAreas} method. */
 export type SuperArea = {
     /** The id of the super area in the database */
@@ -12,6 +25,11 @@ export type SuperArea = {
     bookingProcessDescription: string;
     /** The url of the image of the super area */
     imageUrl: string;
+    /**
+     * LinkAvel-specific multilingual description. Only present when the
+     * request is made with `includeMultilingualDescriptions: true`.
+     */
+    linkAvelDescription?: MTSStringDTO;
 };
 export declare enum SuperAreasTypeFilter {
     /** No filter applied (default). */
@@ -33,6 +51,12 @@ export type GetSuperAreasRequest = {
      * A super area cannot simultaneously be a tour and a regular super area.
      */
     type?: SuperAreasTypeFilter;
+    /**
+     * When true, the response includes the multilingual `linkAvelDescription`
+     * field on each super area. Defaults to false to keep payloads minimal
+     * for callers that only need basic info.
+     */
+    includeMultilingualDescriptions?: boolean;
 };
 /** Request options for {@link TplBooking.getCities}. */
 export type GetCitiesRequest = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mts-booking-library",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "Library for using MyTicketSolution Booking API",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",