@autobusal/routes-order 1.31.4 → 1.32.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.32.0
+
+### Added
+
+- **"Watch this fare" on the results page.** An inline control at the foot of the results asks for an email address and arms a price alert on the pair and date already searched (`POST /api/alerts/price/email`). It renders from `<Found>`, which is the one component mounted in every outcome a search can have - trips listed, every trip hidden by a filter, and nothing found at all; "no buses for this search" is exactly when somebody wants telling if that changes, so a control living inside the listing would have been missing where it matters most. On the return leg the pair is reversed and the return date used, the same swap `useGetDates` makes.
+- Every answer the endpoint can give is said out loud rather than swallowed: the confirmation quotes `baseline_price_display` so the customer knows which number is being watched, a 404 says plainly that nobody prices this pair, a 422 names the address, and a 429 asks for a minute. `retry: false` - none of those three get better by being asked again.
+- The email field has a real accessible name (`<label htmlFor>` over a `useId`-prefixed id), matching what the checkout and `@autobusal/auth` were fixed to do. No threshold field: "tell me if it drops" needs no number, and a second input is how a one-line control becomes a form nobody fills in. No `token` field either - obtapi validates it as `prohibited` here, it belongs to the device half of the same feature.
+
+## 1.31.5
+
+### Added
+
+- **BusTrip carries the pair's AggregateRating** when `/routes/search/facts` reports one (`FactsData.rating`). The aggregate is computed server-side over the same published-review rules the reviews listing uses, and rides the facts cache - the pair page keeps its one-fetch design. Absent rating, the key is not emitted at all.
+
 ## 1.31.4
 
 ### Fixed

package/Facts/types.ts

@@ -17,6 +17,13 @@ export interface FactsData {
   // how many coaches serve the pair in the TIMETABLE, not on a given date
   departures: number
   operators: string[]
+  // Edited: Claude - Date: 2026-08-20
+  // The pair's own review score - the published reviews of every route in
+  // this very timetable, aggregated by obtapi with the same threshold rule
+  // as everything else (null until there is enough to say something honest).
+  // For structured data; note ScheduleRow.rating below is the OPERATOR's
+  // company-wide number, a different thing.
+  rating: { average: number, count: number } | null
   // Two numbers that must never be conflated.
   //
   // `road` is real driving distance from a routing service and is null unless

package/Found/Found.tsx

@@ -9,6 +9,7 @@ import Picks from './Picks/Picks';
 import Filters from './Filters/Filters';
 import Summary from './Summary/Summary';
 import SameDay from './SameDay/SameDay';
+import Watch from './Watch/Watch';
 import { Results, Sidebar, Listing } from '../styles';
 import { useGetAlternatives } from '../services';
 import { RoutesSearchForm } from '@autobusal/routes-search/types';
@@ -99,6 +100,21 @@ const Found = ({ type, loading, data, step1, preferredStop, t, onSearch, onSave
   // refine, and they'd only add noise above an empty state
   const showControls = !loading && items.length > 1;
 
+  /**
+   * The journey the "watch this fare" control below is about.
+   *
+   * Edited: Claude - Date: 2026-08-20
+   *
+   * On the return leg the pair is the reverse of the one that was searched
+   * and the date is the return date - the same swap useGetDates has always
+   * made for the date strip, and for the same reason: step 3 is a search
+   * from the destination back, and watching the outbound fare there would
+   * watch a journey the visitor is no longer looking at.
+   */
+  const watched = type === '_return'
+    ? { from: step1.to, to: step1.from, departure: step1._return ?? '' }
+    : { from: step1.from, to: step1.to, departure: step1.departure };
+
   return (
     <>
       <Dates type={ type } step1={ step1 } t={ t } onSearch={ onSearch } />
@@ -173,6 +189,26 @@ const Found = ({ type, loading, data, step1, preferredStop, t, onSearch, onSave
           />
         </Listing>
       </Results>
+
+      { /* Edited: Claude - Date: 2026-08-20
+           At the FOOT of the results, and outside <Results> so it spans the
+           full width rather than sitting under the filter column.
+
+           This is the one spot on the screen that is reached in every
+           outcome a search can have - a list of prices none of which was
+           the one the reader wanted, a filter that hid them all, and a
+           search that found nothing at all. That last case is the one that
+           decided the placement: "no buses for this search" is precisely
+           when somebody wants telling if that changes, and a control living
+           inside the listing would have been absent exactly there.
+
+           Held back while the search is still running - offering to watch a
+           fare before we know whether there is one to watch, under a
+           spinner, is noise. A pair nobody prices answers 404 and says so.
+           */ }
+      { !loading && watched.departure !== '' && (
+        <Watch from={ watched.from } to={ watched.to } departure={ watched.departure } t={ t } />
+      ) }
     </>
   );
 };

package/Found/Watch/Watch.tsx

@@ -0,0 +1,187 @@
+import { useState, useId } from 'react';
+import { TFunction } from 'i18next';
+import { useForm } from 'react-hook-form';
+import { AiOutlineBell, AiOutlineCheckCircle } from 'react-icons/ai';
+import { Button } from '@autobusal/common';
+import { Validate, Display } from '@autobusal/utilities';
+import { useGetSuggestions } from '@autobusal/routes-search/services';
+import { Container, Toggle, Panel, Lead, Journey, Fields, Field, Action, Privacy, Failure, Done } from './styles';
+import { PriceAlertForm, PriceAlertData } from '../../types';
+import { usePostPriceAlert } from '../../services';
+
+interface Props {
+  from: string
+  to: string
+  departure: string
+  t: TFunction<'common'>
+}
+
+/**
+ * "Watch this fare" - tell me by email if the price for this journey drops.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * WHERE IT SITS is the whole design. This renders at the END of the results,
+ * from <Found>, which is the one component on this screen that is mounted in
+ * every state it can be in: trips listed, trips all hidden by a filter, and
+ * nothing found at all. A control placed inside the listing would have
+ * disappeared in exactly the state that most needs it - "no buses for this
+ * search" is when somebody most wants telling if that changes - and one
+ * placed above the trips would have argued with the results for attention
+ * on the page whose entire job is showing them.
+ *
+ * The pair and the date are the search that has already been run, so the
+ * only thing asked for is an address. Collapsed until pressed: this is for
+ * the minority who did not find their price, and an open form under every
+ * result set is a second thing to read past.
+ *
+ * THRESHOLD IS DELIBERATELY NOT COLLECTED. The endpoint accepts one, but
+ * "tell me if it goes down" needs no number from the traveller, and a
+ * second field is how a one-line control becomes a form nobody fills in.
+ */
+const Watch = ({ from, to, departure, t }: Props): JSX.Element => {
+  const [ open, setOpen ] = useState<boolean>(false);
+  const [ done, setDone ] = useState<PriceAlertData | undefined>(undefined);
+  const [ failure, setFailure ] = useState<string | undefined>(undefined);
+
+  /**
+   * Edited: Claude - Date: 2026-08-20
+   * Same pairing @autobusal/auth and the checkout were just fixed to use: a
+   * real <label for> over an id nothing else can own. The results page also
+   * carries the footer's newsletter signup, so a bare id="email" would have
+   * been the second one on the page.
+   */
+  const uid = useId();
+
+  const id = (field: string): string => `${ uid }${ field }`;
+
+  const { register, handleSubmit, formState: { errors } } = useForm<PriceAlertForm>();
+
+  const { mutate: WatchFare, isPending } = usePostPriceAlert();
+
+  // the same cached city list the search form's autocomplete and the step
+  // heading already read, so naming the journey costs no extra request
+  const { data: cities } = useGetSuggestions();
+
+  const fromCity = cities.find(city => city.slug === from);
+  const toCity = cities.find(city => city.slug === to);
+
+  const names = {
+    from: fromCity?.name ?? from,
+    to: toCity?.name ?? to
+  };
+
+  /**
+   * Every answer this endpoint can give, turned into something readable.
+   *
+   * 404 is not an error the visitor made: nobody prices this pair, so there
+   * is genuinely no fare to watch, and saying that plainly is the only
+   * honest reply. 429 is the write-tier throttle (20/min). 422 also raises
+   * the global toast from apiClient's interceptor - it is repeated inline
+   * because a toast above the fold is easy to miss from the foot of a long
+   * result list, which is exactly where this control lives.
+   */
+  const message = (status?: number): string => {
+    if (status === 404) {
+      return t('routes_order.step2.watch.errors.not_found');
+    }
+
+    if (status === 422) {
+      return t('routes_order.step2.watch.errors.invalid');
+    }
+
+    if (status === 429) {
+      return t('routes_order.step2.watch.errors.throttled');
+    }
+
+    return t('routes_order.step2.watch.errors.failed');
+  };
+
+  const onSubmit = (data: PriceAlertForm): void => {
+    setFailure(undefined);
+
+    WatchFare({
+      email: data.email,
+      from,
+      to,
+      departure
+    }, {
+      onSuccess: (data) => {
+        setDone(data);
+      },
+      onError: (error) => {
+        setFailure(message(error.response?.status));
+      }
+    });
+  };
+
+  if (done !== undefined) {
+    return (
+      <Container className="box">
+        <Done>
+          <AiOutlineCheckCircle />
+
+          <span>
+            { t('routes_order.step2.watch.done', {
+              price: done.baseline_price_display,
+              from: names.from,
+              to: names.to
+            }) }
+          </span>
+        </Done>
+      </Container>
+    );
+  }
+
+  return (
+    <Container className="box">
+      <Toggle type="button" aria-expanded={ open } onClick={ () => setOpen(!open) }>
+        <AiOutlineBell />
+
+        <span>{ t('routes_order.step2.watch.toggle') }</span>
+      </Toggle>
+
+      { open && (
+        <Panel>
+          <Lead>{ t('routes_order.step2.watch.lead') }</Lead>
+
+          <Journey>
+            { t('routes_order.step2.watch.journey', {
+              from: names.from,
+              to: names.to,
+              date: departure
+            }) }
+          </Journey>
+
+          <form onSubmit={ handleSubmit(onSubmit) }>
+            <Fields>
+              <Field>
+                <label htmlFor={ id('email') }>{ t('routes_order.step2.watch.email') }</label>
+
+                <input type="email" id={ id('email') } { ...register('email', Validate('required|email|max_length:255', t)) } />
+              </Field>
+
+              <Action>
+                <Button
+                  type="submit"
+                  size="medium"
+                  loading={ isPending }
+                  text={ t('routes_order.step2.watch.submit') }
+                  noMargin
+                />
+              </Action>
+            </Fields>
+
+            { Display(errors.email) }
+
+            { failure !== undefined && <Failure role="alert">{ failure }</Failure> }
+
+            <Privacy>{ t('routes_order.step2.watch.privacy') }</Privacy>
+          </form>
+        </Panel>
+      ) }
+    </Container>
+  );
+};
+
+export default Watch;

package/Found/Watch/styles.ts

@@ -0,0 +1,118 @@
+import styled from 'styled-components';
+
+/**
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * A strip under the results, not a panel over them. This sits at the end of
+ * the list - where somebody has read every price and none of them was the
+ * one they wanted - so it has to be findable without ever competing with
+ * the trips themselves for attention.
+ */
+export const Container = styled.div`
+  margin-top: 15px;
+
+  &.box {
+    padding: 12px 15px;
+  }
+`;
+
+export const Toggle = styled.button`
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  text-align: left;
+  font-size: ${ props => props.theme.size.s };
+  font-weight: 700;
+  color: ${ props => props.theme.font.normal };
+
+  & > svg {
+    flex: 0 0 auto;
+    font-size: ${ props => props.theme.size.l };
+    color: ${ props => props.theme.primary.normal };
+  }
+
+  &:hover {
+    color: ${ props => props.theme.primary.normal };
+  }
+`;
+
+export const Panel = styled.div`
+  margin-top: 12px;
+`;
+
+export const Lead = styled.p`
+  margin: 0 0 4px;
+  font-size: ${ props => props.theme.size.s };
+`;
+
+export const Journey = styled.p`
+  margin: 0 0 12px;
+  font-size: ${ props => props.theme.size.xs };
+  color: ${ props => props.theme.font.faded };
+`;
+
+/**
+ * The field and its action on one line from the tablet up, stacked on a
+ * phone - the same shape the coupon box uses, so the two read as siblings.
+ */
+export const Fields = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+
+  @media (min-width: 640px) {
+    flex-direction: row;
+    align-items: flex-end;
+  }
+`;
+
+export const Field = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+  font-weight: 700;
+  font-size: calc(${ props => props.theme.size.m } - 1px);
+`;
+
+export const Action = styled.div`
+  flex: 0 0 auto;
+`;
+
+export const Privacy = styled.p`
+  margin: 10px 0 0;
+  font-size: ${ props => props.theme.size.xs };
+  color: ${ props => props.theme.font.faded };
+`;
+
+/**
+ * Every answer the server can give, said out loud.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * The contact form swallowed submissions for months because a failure had
+ * nowhere to render. A 404 (nobody prices this pair), a 429 (throttled) and
+ * an unreachable API all end up here rather than in the console.
+ */
+export const Failure = styled.p`
+  margin: 10px 0 0;
+  font-size: ${ props => props.theme.size.s };
+  color: ${ props => props.theme.font.error };
+`;
+
+export const Done = styled.div`
+  display: flex;
+  gap: 8px;
+  align-items: flex-start;
+  font-size: ${ props => props.theme.size.s };
+  line-height: 1.4;
+
+  & > svg {
+    flex: 0 0 auto;
+    margin-top: 2px;
+    font-size: ${ props => props.theme.size.l };
+    color: ${ props => props.theme.primary.normal };
+  }
+`;

package/Sections/Schema.tsx

@@ -27,6 +27,19 @@ interface Props {
  * claiming travellers rated this journey when they rated the company. When
  * an operator has no published rating - below the display threshold - it is
  * simply absent, exactly as it is on the page.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * The trip now ALSO carries its own AggregateRating - and that is not the
+ * claim the paragraph above forbids, because `facts.rating` is a different
+ * number: obtapi aggregates the published reviews of exactly the routes in
+ * this timetable (Facts::rating, the same set Reviews\BrowseController's
+ * `pair` mode reads), not a company-wide score stretched over one leg.
+ * Travellers who booked these very coaches wrote those reviews, and every
+ * card on the page links to the operator profile where they are read in
+ * full. Below the display threshold obtapi sends null and nothing is
+ * emitted here - an AggregateRating of nothing is a guideline violation,
+ * worse than none.
  */
 const Schema = ({ facts, t }: Props): (JSX.Element | null) => {
   const schedule = facts.schedule ?? [];
@@ -62,6 +75,19 @@ const Schema = ({ facts, t }: Props): (JSX.Element | null) => {
     departureBusStop: { '@type': 'BusStop', name: facts.from },
     arrivalBusStop: { '@type': 'BusStop', name: facts.to },
 
+    // Edited: Claude - Date: 2026-08-20
+    // The pair's own score - see the header comment. Null below the
+    // display threshold, and then the property simply does not exist.
+    ...(facts.rating ? {
+      aggregateRating: {
+        '@type': 'AggregateRating',
+        ratingValue: facts.rating.average,
+        reviewCount: facts.rating.count,
+        bestRating: 5,
+        worstRating: 1
+      }
+    } : {}),
+
     ...(providers.length > 0 ? {
       provider: providers.map(item => organisation(item.name, item.rating))
     } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/routes-order",
-  "version": "1.31.4",
+  "version": "1.32.0",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"

package/services.ts

@@ -1,10 +1,11 @@
 import { useMutation, UseMutationResult, useQuery, UseQueryResult } from '@tanstack/react-query';
+import { AxiosError } from 'axios';
 import { apiClient } from '@autobusal/providers';
 import { RoutesSearchForm } from '@autobusal/routes-search/types';
 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, AlternativesData } from './types';
+import { FoundDay, ActionData, SaveData, OrderedData, CouponForm, AddonsSelection, AlternativesData, PriceAlertRequest, PriceAlertData } from './types';
 
 export const useGetDepartures = (data: RoutesSearchForm): UseQueryResult<FoundData[]> => (
   useQuery({
@@ -273,3 +274,42 @@ export const useGetFlex = (
     )
   })
 );
+
+/**
+ * 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
+  })
+);

package/types.ts

@@ -86,4 +86,34 @@ export interface AddonsSelection {
   // price are the server's to decide (Libraries\Orders\Flex), and a client
   // that sent either would be ignored.
   flex: 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
+}