@autobusal/routes-order 1.8.0 → 1.9.1

package/services.ts

@@ -1,10 +1,11 @@
 import { useMutation, UseMutationResult, useQuery, UseQueryResult } from '@tanstack/react-query';
-import { apiClient } from '@autobusal/providers';
+import { AxiosError } from 'axios';
+import { apiClient, storedReferral } from '@autobusal/providers';
 import { RoutesSearchForm } from '@autobusal/routes-search/types';
-import { FoundData } from '@autobusal/providers/types/routes';
+import { FoundData, FlexOffer } from '@autobusal/providers/types/routes';
 import { CouponData } from '@autobusal/providers/types/orders';
-import { BillingData, PersonData } from '@autobusal/providers/types/persons';
-import { FoundDay, ActionData, SaveData, OrderedData, CouponForm, AddonsSelection } from './types';
+import { BillingData, PersonData, SavedPassengerRecord, SavedPassengersData } from '@autobusal/providers/types/persons';
+import { FoundDay, ActionData, SaveData, OrderedData, CouponForm, AddonsSelection, AlternativesData, PriceAlertRequest, PriceAlertData } from './types';
 
 export const useGetDepartures = (data: RoutesSearchForm): UseQueryResult<FoundData[]> => (
   useQuery({
@@ -21,6 +22,44 @@ export const useGetDepartures = (data: RoutesSearchForm): UseQueryResult<FoundDa
   })
 );
 
+/**
+ * What to offer when a search finds nothing.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * `enabled` is the whole point: this only runs once the departure search
+ * has come back empty, so a search that succeeded never pays for it. On
+ * obtapi's side it costs a handful of real searches, which is why it is
+ * not simply folded into /departure.
+ */
+export const useGetAlternatives = (data: RoutesSearchForm, enabled: boolean): UseQueryResult<AlternativesData> => (
+  useQuery({
+    queryKey: ['search-alternatives', { data }],
+    enabled,
+    queryFn: async () => (
+      await apiClient
+        .get('/api/routes/search/alternatives', {
+          params: data
+        })
+        .then(response => (
+          response?.data ?? { from: [], to: [], dates: [] }
+        ))
+    )
+  })
+);
+
+/**
+ * The return legs on offer for an already-chosen outbound.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-05
+ * The return date goes over as `return`. The form calls it `_return`
+ * because `return` is a reserved word in JS, and spreading the form
+ * straight into the query string therefore sent a field the API does not
+ * know while omitting the one it validates - so this request answered 422
+ * "The return field is required" every single time, and step 3 could never
+ * list anything. The order builder below has always done this mapping
+ * (`order.return = step1._return`); only this call was missed.
+ */
 export const useGetReturns = (data: RoutesSearchForm, departure: FoundData): UseQueryResult<FoundData[]> => (
   useQuery({
     queryKey: ['search-routes-step3', { data }],
@@ -29,6 +68,7 @@ export const useGetReturns = (data: RoutesSearchForm, departure: FoundData): Use
         .get('/api/routes/search/return', {
           params: {
             ...data,
+            return: data._return,
             operator_id: departure.operator.id
           }
         })
@@ -52,13 +92,23 @@ export const useGetDates = (step1: RoutesSearchForm, type: ('departure' | '_retu
   }
 
   return useQuery({
-    queryKey: ['step2-dates', { number }],
+    // Edited: Ferjolt Ozuni - Date: 2026-08-01
+    // The key was ['step2-dates', { number }] - the search itself was not in
+    // it, so every city pair and passenger mix shared one cache entry and
+    // the strip kept showing the previous trip's days. Invisible while the
+    // strip was only booleans; with per-day prices on it, it would have
+    // quoted one route's fares under another route's dates.
+    queryKey: ['step2-dates', { step, number }],
     queryFn: async () => (
       await apiClient
         .get('/api/routes/search/dates', {
           params: {
             ...step,
-            number
+            number,
+            // which half of a round trip this strip prices (BOOK-02-b):
+            // the from/to swap above handles the direction, this handles
+            // the FARE - a return leg sells at adult_return
+            leg: type === '_return' ? 'return' : 'departure'
           }
         })
         .then(response => (
@@ -68,18 +118,34 @@ export const useGetDates = (step1: RoutesSearchForm, type: ('departure' | '_retu
   })
 };
 
+/**
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * The passenger details moved from a hook argument into the mutation
+ * variables. On the merged checkout screen they are only known at the
+ * moment the buyer presses pay - validated right then, in the same handler
+ * - so baking them into the hook's closure at render time would have sent
+ * whatever was in state one render earlier.
+ */
+export interface OrderSubmission {
+  billing: BillingData
+  person: PersonData
+}
+
 export const usePostOrder = (
   step1: RoutesSearchForm,
   step2: FoundData,
   step3: (FoundData | undefined),
-  step4: PersonData,
   coupon: (CouponData | undefined),
   action: (string | undefined),
   addons: AddonsSelection
-): UseMutationResult<OrderedData, Error, BillingData, unknown> => (
+): UseMutationResult<OrderedData, Error, OrderSubmission, unknown> => (
   useMutation({
     mutationKey: ['save-order'],
-    mutationFn: async (data: BillingData) => {
+    mutationFn: async ({ billing, person }: OrderSubmission) => {
+      const data = billing;
+      const step4 = person;
+
       const type =  step1.type ?? 'departure';
 
       const order: SaveData = {};
@@ -108,14 +174,71 @@ export const usePostOrder = (
         order.addon_telegram = '1';
       }
 
+      // The number may be blank here: obtapi falls back to the first
+      // passenger phone the form already collected (Orders\Make\Addons),
+      // so ticking the box on a route that asks for a phone is enough.
+      if (addons.sms) {
+        order.addon_sms = '1';
+        order.addon_sms_number = addons.smsNumber;
+      }
+
+      if (addons.flex) {
+        order.addon_flex = '1';
+      }
+
       Object.keys(step4).forEach(index => {
         order[index] = step4[index];
       });
 
+      /*
+       * Edited: Claude - Date: 2026-08-26
+       *
+       * Seat fields. A zero means "no choice made": with the seat-selection
+       * add-on the picker is optional and 0 is its resting value, and the
+       * API auto-assigns ABSENT fields but rejects a literal zero as a
+       * taken seat - so unpicked fields must not travel at all. Stripping
+       * unconditionally is safe for the legacy mode too: there the fields
+       * are validated required|min:1, so a zero cannot reach this line.
+       *
+       * addon_seats goes over only when the brand sells the add-on AND at
+       * least one hand-picked seat survived the strip - the flag is the
+       * buyer's opt-in, the server's Buses\Assign counts what it charges.
+       */
+      let chosenSeats = 0;
+
+      Object.keys(order).forEach(key => {
+        if (/_s[dr]$/.test(key)) {
+          if (Number(order[key]) > 0) {
+            chosenSeats++;
+          } else {
+            delete order[key];
+          }
+        }
+      });
+
+      if (addons.seats && chosenSeats > 0) {
+        order.addon_seats = '1';
+      }
+
       if (action !== undefined) {
         order.action = action;
       }
 
+      /*
+       * Edited: Claude - Date: 2026-08-28
+       *
+       * The referral token minted when this visitor arrived through ?ref=
+       * (providers useReferralTouch) - replayed under the exact field name
+       * obtapi's Attribution::FIELD declares. Expiry is checked client-side
+       * only to avoid sending a corpse; the server re-validates everything
+       * and a stale or self-referred token simply attributes nothing.
+       */
+      const referral = storedReferral();
+
+      if (referral !== null) {
+        order.referral = referral.token;
+      }
+
       if (data !== undefined) {
         Object.keys(data).forEach(index => {
           order[index] = data[index as keyof typeof data];
@@ -148,15 +271,181 @@ export const useGetCoupon = (routeId: number, total: number): UseMutationResult<
   })
 );
 
-export const useGetPayments = (): UseQueryResult<ActionData> => (
+/*
+ * Claude - 2026-08-22 (audit decision BOOK-07): asks with the route being
+ * sold, so the API can offer Complimentary to an operator/employee on
+ * their own operator's route. External routes carry string ids and can
+ * never be own inventory, so those simply don't send the parameter.
+ */
+export const useGetPayments = (routeId?: number | string): UseQueryResult<ActionData> => (
+  useQuery({
+    queryKey: ['allowed-funds', { routeId }],
+    queryFn: async () => (
+      await apiClient
+        .get('/api/funds/allowed', {
+          params: typeof routeId === 'number' ? { route: routeId } : {}
+        })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+/**
+ * The Flexible Ticket offer for the routes actually chosen.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ *
+ * Its own request rather than a field on the search result, because the
+ * answer depends on BOTH legs of a return trip at once: an operator who will
+ * not amend one half removes the add-on from the whole booking, and the
+ * price is computed on the combined fare. A per-route field could not say
+ * either of those things.
+ *
+ * Disabled until there is a departure price to ask about, so it never fires
+ * on a half-built booking.
+ */
+export const useGetFlex = (
+  departurePriceId: (number | undefined),
+  returnPriceId: (number | undefined),
+  adults: number,
+  children: number,
+  babies: number,
+  // Edited: Claude - Date: 2026-08-28 (sweep, low): the coupon-adjusted
+  // fare, so the quoted flex price matches what Make\Addons will charge -
+  // without it a couponed booking showed one figure and billed another
+  total?: number
+): UseQueryResult<FlexOffer> => (
   useQuery({
-    queryKey: ['allowed-funds'],
+    queryKey: ['flex-offer', { departurePriceId, returnPriceId, adults, children, babies, total }],
+    enabled: departurePriceId !== undefined,
     queryFn: async () => (
       await apiClient
-        .get('/api/funds/allowed')
+        .get('/api/orders/flex', {
+          params: {
+            departure_price_id: departurePriceId,
+            return_price_id: returnPriceId,
+            adults,
+            children,
+            babies,
+            ...(total !== undefined ? { total } : {})
+          }
+        })
+        .then(response => response.data)
+    )
+  })
+);
+
+/**
+ * Watch a fare: email me if the price for this pair and date drops.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * Typed against AxiosError rather than Error, and that is the point of the
+ * signature: the caller has four different things to say depending on the
+ * status (404 nobody prices this pair, 422 bad address, 429 throttled,
+ * anything else unreachable), and with a bare `Error` the status would be
+ * an unchecked cast at the one place it matters.
+ *
+ * NO `token` FIELD, ever. obtapi validates it as `prohibited` on this
+ * endpoint - it identifies a mobile device on the push half of the same
+ * feature - so sending one turns a working request into a 422.
+ *
+ * `Content-Language` is not set here: apiClient's request interceptor
+ * already sends the live UI language on every call, and the server reads
+ * the alert's language off it. That is the honest answer to "which language
+ * should these emails be in" - the one they are reading the site in right
+ * now - and one nobody can get wrong in a form.
+ */
+export const usePostPriceAlert = (): UseMutationResult<PriceAlertData, AxiosError, PriceAlertRequest, unknown> => (
+  useMutation({
+    mutationKey: ['watch-price-alert'],
+    mutationFn: async (data: PriceAlertRequest) => (
+      await apiClient
+        .post('/api/alerts/price/email', data)
+        .then(response => (
+          response.data
+        ))
+    ),
+
+    // the two answers that are not "try again" - an unpriced pair and a
+    // rejected address - are both final, and retrying a 429 is the one
+    // thing guaranteed to keep it a 429
+    retry: false
+  })
+);
+
+/**
+ * The travellers this account has saved, measured against THIS journey.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * The price ids are what make the answer journey-specific: obtapi puts a
+ * `missing` array on every row naming the fields these particular routes
+ * collect and this particular saved traveller has not got (see
+ * Account\PassengersController::browse). Without them the rows come back
+ * with no `missing` key at all, which is a different answer from an empty
+ * one - so they are always sent from here.
+ *
+ * `enabled` is the whole gate, and it is not an optimisation. The endpoint
+ * is `role:visitor`, so a guest or a member of staff gets a 404 - a correct
+ * refusal that confirms nothing, and one this UI must never turn into an
+ * error on somebody's checkout. Not asking is the only way to be sure of
+ * that; `retry: false` covers the case where the account changes underneath
+ * a query already in flight.
+ */
+export const useGetSavedPassengers = (
+  departurePriceId: (number | undefined),
+  returnPriceId: (number | undefined),
+  enabled: boolean
+): UseQueryResult<SavedPassengersData> => (
+  useQuery({
+    queryKey: ['saved-passengers-checkout', { departurePriceId, returnPriceId }],
+    enabled: enabled && departurePriceId !== undefined,
+    retry: false,
+    queryFn: async () => (
+      await apiClient
+        .get('/api/account/passengers/browse', {
+          params: {
+            departure_price_id: departurePriceId,
+            return_price_id: returnPriceId
+          }
+        })
         .then(response => (
           response.data
         ))
     )
   })
-);
+);
+
+/**
+ * One saved traveller, passport included.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * A mutation for a GET, deliberately. This is not data the screen renders -
+ * it is fetched at the moment somebody picks a name out of the chooser, and
+ * what comes back is written into a form rather than displayed. A query
+ * would need the chosen id in render state and an effect to notice it
+ * landing; `mutate(id, { onSuccess })` is the same fetch with the answer
+ * arriving where the decision was made.
+ *
+ * This is also the ONLY request in the app that returns a stored passport
+ * number, which is why it is one traveller at a time and only after a
+ * customer has said who is sitting in this seat.
+ */
+export const useGetSavedPassenger = (): UseMutationResult<SavedPassengerRecord, Error, number, unknown> => (
+  useMutation({
+    mutationKey: ['saved-passenger-record'],
+    mutationFn: async (id: number) => (
+      await apiClient
+        .get('/api/account/passengers/get', {
+          params: { id }
+        })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);

package/styles.ts

@@ -21,4 +21,130 @@ export const Actions = styled.div`
   justify-content: center;
   gap: 20px;
   margin-top: 25px;
+`;
+
+/**
+ * The search form kept on screen while browsing results.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * Changing a date or a city used to mean going Back to Search and losing
+ * your place. The form stays available above the results so an adjustment
+ * is one edit rather than a round trip.
+ */
+export const SearchAgain = styled.div<{ $background: string }>`
+  position: relative;
+  margin: -35px calc(50% - 50vw) 20px;
+  padding: 18px calc(50vw - 50%);
+  background-image: url('${ props => props.$background }');
+  background-size: cover;
+  background-repeat: no-repeat;
+  background-position: center;
+
+  /**
+   * Same scrim as the homepage hero, for the same reason: the artwork a
+   * brand supplies may be light or dark, and the controls on top of it must
+   * read either way.
+   */
+  &::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    background: rgba(0, 0, 0, .45);
+  }
+`;
+
+export const SearchInner = styled.div`
+  position: relative;
+`;
+
+export const SearchToggle = styled.button`
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 14px;
+  font-size: ${ props => props.theme.size.s };
+  font-weight: 700;
+  color: #FFF;
+  border: 1px solid rgba(255, 255, 255, .45);
+  border-radius: 100px;
+  transition: all 0.2s ease;
+
+  &:hover {
+    border-color: #FFF;
+    background: rgba(255, 255, 255, .12);
+  }
+`;
+
+export const SearchSummary = styled.span`
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`;
+
+/**
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * Collapsed by default: the form is there for the minority who want to
+ * change something, and left open it pushed the results themselves below
+ * the fold on the page whose whole job is showing results.
+ */
+export const SearchPanel = styled.div<{ $open: boolean }>`
+  display: ${ props => props.$open ? 'block' : 'none' };
+  margin-top: 14px;
+  padding: 20px;
+
+  /**
+   * Edited: Claude - Date: 2026-08-29
+   *
+   * ABOVE THE STEPS, because backdrop-filter below creates a stacking
+   * context: everything inside this panel is confined to it, so the date
+   * picker's own z-index (100) could never beat the step markers sitting
+   * at z-index 1 in the page's context. Opening the collapsed search and
+   * clicking a date drew the calendar UNDERNEATH the 1-2-3-4 circles.
+   * Raising the panel itself lifts its whole subtree with it.
+   */
+  position: relative;
+  z-index: 20;
+  background: ${ props => props.theme.header.transparent };
+  backdrop-filter: blur(25px);
+  -webkit-backdrop-filter: blur(25px);
+  border-radius: ${ props => props.theme.borderRadius };
+`;
+
+/**
+ * Results layout: filters beside the list, not above it.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * Below 1280px this is a plain column and the filters stay a collapsible
+ * panel. At and above it the filters take a fixed column and the results
+ * take the rest. See Found/Filters/styles.ts for why the breakpoint is
+ * 1280 rather than 1024.
+ */
+export const Results = styled.div`
+  display: flex;
+  flex-direction: column;
+
+  @media (min-width: 1280px) {
+    flex-direction: row;
+    align-items: flex-start;
+    gap: 20px;
+  }
+`;
+
+export const Sidebar = styled.aside`
+  min-width: 0;
+
+  @media (min-width: 1280px) {
+    flex: 0 0 290px;
+  }
+`;
+
+export const Listing = styled.div`
+  // min-width:0 stops a long stop name inside a card from forcing this
+  // column wider than its share of the row
+  flex: 1;
+  min-width: 0;
 `;

package/types.ts

@@ -2,6 +2,36 @@ export interface FoundDay {
   day: string
   id: string
   routes: boolean
+  // Edited: Ferjolt Ozuni - Date: 2026-08-01
+  // Cheapest fare that day for the current passenger mix, null when the day
+  // has nothing. Optional so an older obtapi - and any API partner reading
+  // /routes/search/dates - keeps type-checking.
+  from_price?: number | null
+  from_price_display?: string | null
+}
+
+/**
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ * Alternatives offered when a search finds nothing - see obtapi's
+ * Routes\Search\Nearby.
+ */
+export interface NearbyCity {
+  city: {
+    id: number
+    name: string
+    slug: string
+  }
+  /** kilometres from the city the passenger actually asked for */
+  distance: number
+  routes: number
+  from_price: number
+  from_price_display: string
+}
+
+export interface AlternativesData {
+  from: NearbyCity[]
+  to: NearbyCity[]
+  dates: FoundDay[]
 }
 
 export interface CouponForm {
@@ -12,6 +42,7 @@ export interface ActionData {
   fake: boolean
   reserve: boolean
   funds: boolean
+  complimentary?: boolean
   bkt: boolean
   stripe: boolean
   mollie: boolean
@@ -41,4 +72,56 @@ export interface AddonsSelection {
   whatsapp: boolean
   whatsappNumber: string
   telegram: boolean
-}
+
+  /**
+   * Edited: Ferjolt Ozuni - Date: 2026-08-05
+   * The paid per-order CONFIRMATION by SMS - route alerts over SMS are free
+   * and need nothing here. Carries its own number like WhatsApp does, since
+   * somebody booking for a relative wants the text to reach the traveller.
+   */
+  sms: boolean
+  smsNumber: string
+
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Flexible Ticket. A bare boolean, like Telegram - the window and the
+  // price are the server's to decide (Libraries\Orders\Flex), and a client
+  // that sent either would be ignored.
+  flex: boolean
+
+  // Edited: Claude - Date: 2026-08-26
+  // Seat selection is SOLD on this brand (settings addons.seats). What is
+  // actually bought is implicit in the seat fields themselves: the
+  // submission strips unpicked (zero) fields and sends addon_seats only
+  // when at least one hand-picked seat remains - see usePostOrder.
+  seats: boolean
+}
+/**
+ * "Watch this fare" - see Found/Watch/Watch.tsx.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * The form is one field because the pair and the date are the search that
+ * has already been run. `token` is NOT here and must never be: obtapi's
+ * Alerts\PriceController::email() validates it as `prohibited`, since that
+ * field identifies a mobile device on the push half of the same feature and
+ * an alert notifies exactly one way.
+ */
+export interface PriceAlertForm {
+  email: string
+}
+
+export interface PriceAlertRequest extends PriceAlertForm {
+  from: string
+  to: string
+  /** d/m/Y, the format the search form already holds a date in */
+  departure: string
+}
+
+export interface PriceAlertData {
+  id: number
+
+  // the fare the alert was armed against, already formatted in the label's
+  // currency by the server - the customer is told the number being watched
+  // rather than being left to guess which of the prices on screen it was
+  baseline_price_display: string
+}

package/Found/Booking/Booking.tsx

@@ -1,61 +0,0 @@
-import { TFunction } from 'i18next';
-import { createDate } from '@autobusal/utilities';
-import { Container, About, LinkBooking } from './styles';
-import { RoutesSearchForm } from '@autobusal/routes-search/types';
-import { FoundData } from '@autobusal/providers/types/routes';
-import { useGetSettings } from '@autobusal/providers/services';
-
-interface Props {
-  data?: FoundData[]
-  step1: RoutesSearchForm
-  t: TFunction<'public'>
-}
-
-const Booking = ({ data, step1, t }: Props): (JSX.Element | null) => {
-  const { data: settings } = useGetSettings();
-
-  if (data === undefined || data?.length === 0) {
-    return null;
-  }
-
-  const destination = data[0].locations.to;
-
-  // stop if no booking city
-  if (destination.city.booking_id === undefined) {
-    return null;
-  }
-
-  // stop if no booking id
-  if (settings.preferences.bookingID === undefined) {
-    return null;
-  }
-
-  const from = createDate(step1.departure);
-  const to = getReturnDate(step1._return, from);
-
-  const location = `https://www.booking.com/searchresults.xu.html?city=${ destination.city.booking_id }&aid=&checkin_monthday=${ from.getDate() }&checkin_month=${ from.getMonth() + 1 }&checkin_year=${ from.getFullYear() }&checkout_monthday=${ to.getDate() }&checkout_month=${ to.getMonth() + 1 }&checkout_year=${ to.getFullYear() }&no_rooms=1&group_adults=2&room1=A%2CA`;
-
-  return (
-    <Container>
-      <About>
-        { t('routes_order.step2.booking.title', { location: destination.city.name }) }
-        <img src="https://s-ec.bstatic.com/static/img/b26logo/booking_logo_retina/22615963add19ac6b6d715a97c8d477e8b95b7ea.png" alt="Booking.com" />
-      </About>
-
-      <LinkBooking to={ location } target="_blank" rel="noopener noreferrer">{ t('routes_order.step2.booking.search') }</LinkBooking>
-    </Container>
-  );
-};
-
-const getReturnDate = (_return: (string | undefined), from: Date): Date => {
-  if (_return !== undefined) {
-    return createDate(_return);
-  }
-
-  const to = new Date(from);
-  to.setDate(to.getDate() + 2);
-
-  return to;
-};
-
-export default Booking;