@autobusal/routes-order 1.21.1 → 1.23.0

package/CHANGELOG.md

@@ -1,11 +1,41 @@
 # Changelog
 
+## 1.23.0
+
+**Flexible Ticket at checkout.**
+
+- New `useGetFlex(departurePriceId, returnPriceId, adults, children)`. Its own request rather than a field on the search result, because the answer depends on **both legs 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.
+- `Addons` renders the option below passenger details, where it already sat. It shows the **default first** — "without it, this ticket cannot be cancelled or changed" — then only the capabilities this booking actually includes, then that the fee itself is not refunded, then that statutory rights when the *operator* cancels are untouched. Nothing renders at all when the offer is unavailable: a checkbox that unlocks nothing is worse than no checkbox.
+- `AddonsSelection` gains `flex`; the order payload gains `addon_flex`.
+- `Found/Route` reads `routes_order.step2.route.information.*` after the `policies` rename.
+
+Copy is **Flexible Ticket** / **Biletë Fleksibël**, never insurance — the distinction decides how the line is taxed and whether selling it needs a licence.
+
 All notable changes to this package are documented here. This project follows
 [Keep a Changelog](https://keepachangelog.com/) and [Semantic Versioning](https://semver.org/).
 
 > Note: 1.8.0 was published without a changelog entry. The gap is left as-is
 > rather than reconstructed after the fact.
 
+## 1.22.0
+
+Structured data on route-pair pages: `BusTrip` with its operators and
+fares-from, and a `FAQPage` answering the five things people actually search
+for — how long, how much, how many a day, when the first and last leave, and
+who runs it.
+
+One rule governs all of it: **never state anything the page does not show.**
+Every value is the same one rendered in the facts block or the timetable a few
+hundred pixels below. A rich result built on a claim a visitor cannot find is
+the mismatch that gets a site's snippets pulled, and it is also just a lie told
+to a machine.
+
+The rating hangs off the **provider**, not the trip. An operator's rating is
+earned across everything they run; attaching it to one city pair would claim
+travellers rated this journey when they rated the company. Operators below the
+review display threshold carry no rating in the markup, exactly as they carry
+none on the page.
+
 ## 1.21.1
 
 No horizontal scroll on a tablet's date strip. The 900px floor belongs to the

package/Checkout/Checkout.tsx

@@ -24,7 +24,7 @@ import { CouponData } from '@autobusal/providers/types/orders';
 import { TotalData } from '../types';
 import { useUserStore } from '@autobusal/providers/stores/user';
 import { useGetSettings } from '@autobusal/providers/services';
-import { usePostOrder } from '../services';
+import { usePostOrder, useGetFlex } from '../services';
 
 interface Props {
   values?: PersonData
@@ -75,6 +75,7 @@ const Checkout = ({ values, step1, step2, step3, isPartner, t, onStore, onBack }
   const [ addonWhatsapp, setAddonWhatsapp ] = useState<boolean>(false);
   const [ addonWhatsappNumber, setAddonWhatsappNumber ] = useState<string>('');
   const [ addonTelegram, setAddonTelegram ] = useState<boolean>(false);
+  const [ addonFlex, setAddonFlex ] = useState<boolean>(false);
 
   const { data: UserData } = useUserStore();
   const { data: SettingsData } = useGetSettings();
@@ -93,6 +94,19 @@ const Checkout = ({ values, step1, step2, step3, isPartner, t, onStore, onBack }
 
   const currency = total.display.split(' ')[1] ?? '';
 
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Flexible Ticket, for the routes actually chosen. Asked for BOTH legs at
+  // once: the price is computed on the combined fare and an operator who
+  // will not amend one half removes the offer from the whole booking, so a
+  // per-leg question could not be answered honestly.
+  const { data: FlexData } = useGetFlex(
+    step2.price.id as number,
+    step3?.price.id as (number | undefined),
+    step1.adults ?? 1,
+    step1.children ?? 0,
+    step1.babies ?? 0
+  );
+
   const addonItems = [
     addonWhatsapp && SettingsData?.addons?.whatsapp.available ? {
       label: t('routes_order.step5.addons.whatsapp.label'),
@@ -101,6 +115,10 @@ const Checkout = ({ values, step1, step2, step3, isPartner, t, onStore, onBack }
     addonTelegram && SettingsData?.addons?.telegram.available ? {
       label: t('routes_order.step5.addons.telegram.label'),
       price: SettingsData.addons.telegram.price
+    } : null,
+    addonFlex && FlexData?.available && FlexData.price !== undefined ? {
+      label: t('routes_order.step5.flex.title'),
+      price: FlexData.price
     } : null
   ].filter((item): item is { label: string, price: number } => item !== null);
 
@@ -114,7 +132,8 @@ const Checkout = ({ values, step1, step2, step3, isPartner, t, onStore, onBack }
   const { mutate: OrderSend, isPending } = usePostOrder(step1, step2, step3, coupon, action, {
     whatsapp: addonWhatsapp,
     whatsappNumber: addonWhatsappNumber,
-    telegram: addonTelegram
+    telegram: addonTelegram,
+    flex: addonFlex
   });
 
   const onApplyCoupon = (data: CouponData): void => {
@@ -215,14 +234,17 @@ const Checkout = ({ values, step1, step2, step3, isPartner, t, onStore, onBack }
 
           <Addons
             data={ SettingsData?.addons }
+            flexOffer={ FlexData }
             currency={ currency }
             whatsapp={ addonWhatsapp }
             whatsappNumber={ addonWhatsappNumber }
             telegram={ addonTelegram }
+            flex={ addonFlex }
             t={ t }
             onChangeWhatsapp={ setAddonWhatsapp }
             onChangeWhatsappNumber={ setAddonWhatsappNumber }
             onChangeTelegram={ setAddonTelegram }
+            onChangeFlex={ setAddonFlex }
           />
 
           { UserData === undefined && (

package/Facts/types.ts

@@ -6,6 +6,9 @@ export interface FactsData {
   // formatted by the API with the brand's own currency - the PUBLIC settings
   // payload carries no currency, so a frontend has nothing to format with
   price_from_display: string | null
+  // ISO 4217, for schema.org's Offer - the display string has the symbol
+  // baked in and guessing a code back out of it would be confidently wrong
+  currency: string | null
   // both ends of the range, in minutes
   duration_min: number | null
   duration_max: number | null

package/Found/Route/Route.tsx

@@ -4,7 +4,7 @@ import { HiOutlineArrowNarrowRight, HiOutlineDocumentText, HiChevronDown, HiChev
 import { BiHourglass } from 'react-icons/bi';
 import { RiBus2Line } from 'react-icons/ri';
 import { formatDuration, splitPrice } from '../refine';
-import { Button, RouteFeature, Policy, Rating } from '@autobusal/common';
+import { Button, RouteFeature, Information, Rating } from '@autobusal/common';
 import { Container, ButtonDetails, SpecialOffer, FavoriteStop, Trip, Company, Location, Stop, Iso, Time, Price, Amount, Decimals, Currency, PriceNotice, LinkCompany, Details, Detail, ButtonPolicy, TitleDetail, LinkRoute, FeaturesItems, Leaves } from './styles';
 import { FoundData } from '@autobusal/providers/types/routes';
 
@@ -25,7 +25,7 @@ interface Props {
 }
 
 const Route = ({ data, type, passengers, t, onSave, children }: Props): JSX.Element => {
-  const [ policy, setPolicy ] = useState<boolean>(false);
+  const [ information, setInformation ] = useState<boolean>(false);
 
   // Edited: Ferjolt Ozuni - Date: 2026-08-03
   // Closed to begin with. Amenities, route code, transit and policies are
@@ -203,17 +203,17 @@ const Route = ({ data, type, passengers, t, onSave, children }: Props): JSX.Elem
 
         { !data.external && (
           <Detail>
-            <TitleDetail>{ t('routes_order.step2.route.policies.title') }</TitleDetail>
+            <TitleDetail>{ t('routes_order.step2.route.information.title') }</TitleDetail>
 
-            <ButtonPolicy type="button" onClick={ () => setPolicy(true) }>
+            <ButtonPolicy type="button" onClick={ () => setInformation(true) }>
               <HiOutlineDocumentText />
-              { t('routes_order.step2.route.policies.view') }
+              { t('routes_order.step2.route.information.view') }
             </ButtonPolicy>
           </Detail>
         ) }
       </Details>
 
-      { policy && typeof data.id === 'number' && <Policy id={ data.id } t={ t } onClose={ () => setPolicy(false) } /> }
+      { information && typeof data.id === 'number' && <Information id={ data.id } t={ t } onClose={ () => setInformation(false) } /> }
     </Container>
   );
 };

package/Sections/Schema.tsx

@@ -0,0 +1,148 @@
+import { TFunction } from 'i18next';
+import { JsonLd } from '@autobusal/common';
+import { FactsData } from '../Facts/types';
+
+interface Props {
+  facts: FactsData
+  t: TFunction<'common'>
+}
+
+/**
+ * Structured data for a route-pair page.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ *
+ * Roadmap Tier 3.5, and the cheapest item in the tier because the page
+ * already computes everything it needs.
+ *
+ * ONE RULE GOVERNS ALL OF IT: never state something here that the page does
+ * not show. A rich result built on a claim a visitor cannot find is the
+ * mismatch that gets a site's snippets pulled, and it is also just a lie
+ * told to a machine. Every value below is the same value rendered in the
+ * facts block or the timetable a few hundred pixels down - the duration
+ * range, the fares-from, the departure count, the operators.
+ *
+ * The rating hangs off the PROVIDER, not the trip. An operator's rating is
+ * earned across everything they run; attaching it to one city pair would be
+ * 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.
+ */
+const Schema = ({ facts, t }: Props): (JSX.Element | null) => {
+  const schedule = facts.schedule ?? [];
+
+  // Deduplicated operators, each keeping whatever rating it actually has.
+  const providers = schedule.reduce<{ name: string, rating: { average: number, count: number } | null }[]>((all, row) => {
+    if (!row.operator || all.some(item => item.name === row.operator)) {
+      return all;
+    }
+
+    return [ ...all, { name: row.operator, rating: row.rating } ];
+  }, []);
+
+  const organisation = (name: string, rating: { average: number, count: number } | null) => ({
+    '@type': 'Organization',
+    name,
+    ...(rating ? {
+      aggregateRating: {
+        '@type': 'AggregateRating',
+        ratingValue: rating.average,
+        reviewCount: rating.count,
+        bestRating: 5,
+        worstRating: 1
+      }
+    } : {})
+  });
+
+  const trip = {
+    '@context': 'https://schema.org',
+    '@type': 'BusTrip',
+    name: t('routes_order.facts.title', { from: facts.from, to: facts.to }),
+
+    departureBusStop: { '@type': 'BusStop', name: facts.from },
+    arrivalBusStop: { '@type': 'BusStop', name: facts.to },
+
+    ...(providers.length > 0 ? {
+      provider: providers.map(item => organisation(item.name, item.rating))
+    } : {}),
+
+    // Only with a real ISO 4217 code. `price_from_display` is a formatted
+    // string with the symbol baked in, and guessing a code from it would
+    // produce structured data that is confidently wrong.
+    ...(facts.price_from !== null && facts.currency ? {
+      offers: {
+        '@type': 'Offer',
+        price: facts.price_from,
+        priceCurrency: facts.currency,
+        availability: 'https://schema.org/InStock'
+      }
+    } : {})
+  };
+
+  const questions: { q: string, a: string }[] = [];
+
+  const duration = (minutes: number): string => (
+    minutes % 60 === 0
+      ? t('routes_order.facts.duration_hours', { hours: minutes / 60 })
+      : t('routes_order.facts.duration_value', { hours: Math.floor(minutes / 60), minutes: minutes % 60 })
+  );
+
+  if (facts.duration_min !== null && facts.duration_max !== null) {
+    questions.push({
+      q: t('routes_order.schema.duration_q', { from: facts.from, to: facts.to }),
+      a: facts.duration_min === facts.duration_max
+        ? t('routes_order.schema.duration_a', { from: facts.from, to: facts.to, duration: duration(facts.duration_min) })
+        : t('routes_order.schema.duration_a_range', { from: facts.from, to: facts.to, min: duration(facts.duration_min), max: duration(facts.duration_max) })
+    });
+  }
+
+  if (facts.price_from_display) {
+    questions.push({
+      q: t('routes_order.schema.price_q', { from: facts.from, to: facts.to }),
+      a: t('routes_order.schema.price_a', { from: facts.from, to: facts.to, price: facts.price_from_display })
+    });
+  }
+
+  if (facts.departures > 0) {
+    questions.push({
+      q: t('routes_order.schema.departures_q', { from: facts.from, to: facts.to }),
+      a: t('routes_order.schema.departures_a', { count: facts.departures, from: facts.from, to: facts.to })
+    });
+  }
+
+  if (facts.departure_first && facts.departure_last) {
+    questions.push({
+      q: t('routes_order.schema.times_q', { from: facts.from, to: facts.to }),
+      a: t('routes_order.schema.times_a', { first: facts.departure_first, last: facts.departure_last })
+    });
+  }
+
+  if (facts.operators.length > 0) {
+    questions.push({
+      q: t('routes_order.schema.operators_q', { from: facts.from, to: facts.to }),
+      a: t('routes_order.facts.operators', { operators: facts.operators.join(', ') })
+    });
+  }
+
+  // Google requires a FAQPage to carry at least one question, and a page
+  // claiming to be an FAQ with nothing on it is worse than not claiming it.
+  const faq = questions.length > 0 ? {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: questions.map(item => ({
+      '@type': 'Question',
+      name: item.q,
+      acceptedAnswer: { '@type': 'Answer', text: item.a }
+    }))
+  } : null;
+
+  return (
+    <>
+      <JsonLd data={ trip } />
+
+      { faq && <JsonLd data={ faq } /> }
+    </>
+  );
+};
+
+export default Schema;

package/Sections/Sections.tsx

@@ -2,6 +2,7 @@ import { TFunction } from 'i18next';
 import Facts from '../Facts/Facts';
 import Schedule from '../Schedule/Schedule';
 import Links from '../Links/Links';
+import Schema from './Schema';
 import { useGetFacts } from '../Facts/services';
 import { Nav, Anchor, Anchored } from './styles';
 
@@ -64,6 +65,11 @@ const Sections = ({ from, to, t }: Props): (JSX.Element | null) => {
         ) }
       </Nav>
 
+      { /* Edited: Ferjolt Ozuni - Date: 2026-08-03
+           Roadmap Tier 3.5. Emits nothing the sections below do not also
+           show - same facts, same numbers, same operators. */ }
+      <Schema facts={ facts } t={ t } />
+
       <Anchored>
         <Facts id={ FACTS } facts={ facts } t={ t } />
       </Anchored>

package/Step5/Addons/Addons.tsx

@@ -1,7 +1,8 @@
 import { TFunction } from 'i18next';
-import { RiWhatsappLine, RiTelegramLine } from 'react-icons/ri';
+import { RiWhatsappLine, RiTelegramLine, RiCalendarCheckLine } from 'react-icons/ri';
+import { FlexOffer } from '@autobusal/providers/types/routes';
 import { SubTitle } from '../../styles';
-import { Container, Option, Notice } from './styles';
+import { Container, Option, Notice, Terms, Term } from './styles';
 
 interface AddonsData {
   whatsapp: { available: boolean, price: number }
@@ -10,14 +11,17 @@ interface AddonsData {
 
 interface Props {
   data?: AddonsData
+  flexOffer?: FlexOffer
   currency: string
   whatsapp: boolean
   whatsappNumber: string
   telegram: boolean
+  flex: boolean
   t: TFunction<'common'>
   onChangeWhatsapp: (value: boolean) => void
   onChangeWhatsappNumber: (value: string) => void
   onChangeTelegram: (value: boolean) => void
+  onChangeFlex: (value: boolean) => void
 }
 
 // Edited: Ferjolt Ozuni - Date: 2026-07-25
@@ -25,8 +29,17 @@ interface Props {
 // enabled (an empty box would be confusing). The WhatsApp addon collects
 // the number here; Telegram is a "connect after purchase" flow (a bot
 // can't message a bare phone number cold), so it's just a checkbox.
-const Addons = ({ data, currency, whatsapp, whatsappNumber, telegram, t, onChangeWhatsapp, onChangeWhatsappNumber, onChangeTelegram }: Props): (JSX.Element | null) => {
-  if (!data || (!data.whatsapp.available && !data.telegram.available)) {
+const Addons = ({ data, flexOffer, currency, whatsapp, whatsappNumber, telegram, flex, t, onChangeWhatsapp, onChangeWhatsappNumber, onChangeTelegram, onChangeFlex }: Props): (JSX.Element | null) => {
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Flexible Ticket is only on offer where the operators behind the chosen
+  // routes have agreed to honour it, which is a per-booking answer the
+  // settings payload cannot give - hence the separate offer (see
+  // useGetFlex). When it is unavailable nothing renders for it at all,
+  // rather than a disabled row: a checkbox that unlocks nothing is worse
+  // than no checkbox.
+  const hasFlex = flexOffer?.available === true;
+
+  if (!data || (!data.whatsapp.available && !data.telegram.available && !hasFlex)) {
     return null;
   }
 
@@ -80,6 +93,56 @@ const Addons = ({ data, currency, whatsapp, whatsappNumber, telegram, t, onChang
           <Notice>{ t('routes_order.step5.addons.telegram.description') }</Notice>
         </Option>
       ) }
+
+      { hasFlex && (
+        <Option>
+          <label>
+            <input
+              type="checkbox"
+              checked={ flex }
+              onChange={ (event) => onChangeFlex(event.target.checked) }
+            />
+
+            <RiCalendarCheckLine />
+
+            { t('routes_order.step5.flex.add', { price: flexOffer?.price_display }) }
+          </label>
+
+          {/*
+            * The default is stated FIRST and plainly. The passenger is being
+            * asked to pay for flexibility, so what they get without paying
+            * has to be the thing they read before the price, not a
+            * disclosure buried under it.
+            */}
+          <Notice>{ t('routes_order.step5.flex.default') }</Notice>
+
+          <Terms>
+            { flexOffer?.refund_hours != null && (
+              <Term>{ t('routes_order.step5.flex.refund', { hours: flexOffer.refund_hours }) }</Term>
+            ) }
+
+            {/*
+              * Either half can be absent on its own. An operator who will
+              * move a booking but not refund it is a real case, and listing
+              * only what this booking actually includes is the difference
+              * between an offer and a misrepresentation.
+              */}
+            { flexOffer?.reschedule_hours != null && (
+              <Term>{ t('routes_order.step5.flex.reschedule', { hours: flexOffer.reschedule_hours }) }</Term>
+            ) }
+          </Terms>
+
+          <Notice>{ t('routes_order.step5.flex.nonrefundable') }</Notice>
+
+          {/*
+            * Statutory rights when the OPERATOR cancels are untouched by
+            * this and by anything else sold here. Saying so at the point of
+            * sale is both accurate and reassuring; leaving it out would
+            * imply the add-on is what grants them.
+            */}
+          <Notice>{ t('routes_order.step5.flex.carrier') }</Notice>
+        </Option>
+      ) }
     </Container>
   );
 };

package/Step5/Addons/styles.ts

@@ -30,3 +30,23 @@ export const Notice = styled.div`
   font-size: ${ props => props.theme.size.xs };
   color: ${ props => props.theme.font.faded };
 `;
+
+/**
+ * What the add-on actually unlocks, as a short list.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ * A list rather than a sentence because the two windows can differ, and
+ * because either can be absent - prose would have to be rewritten for each
+ * combination, a list simply gets shorter.
+ */
+export const Terms = styled.ul`
+  margin: 8px 0 10px;
+  padding: 0 0 0 18px;
+  list-style: disc;
+`;
+
+export const Term = styled.li`
+  margin: 2px 0;
+  font-size: 14px;
+  line-height: 1.5;
+`;

package/package.json

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

package/services.ts

@@ -1,7 +1,7 @@
 import { useMutation, UseMutationResult, useQuery, UseQueryResult } from '@tanstack/react-query';
 import { apiClient } 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, AlternativesData } from './types';
@@ -156,6 +156,10 @@ export const usePostOrder = (
         order.addon_telegram = '1';
       }
 
+      if (addons.flex) {
+        order.addon_flex = '1';
+      }
+
       Object.keys(step4).forEach(index => {
         order[index] = step4[index];
       });
@@ -207,4 +211,44 @@ export const useGetPayments = (): UseQueryResult<ActionData> => (
         ))
     )
   })
-);
+);
+
+/**
+ * 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
+): UseQueryResult<FlexOffer> => (
+  useQuery({
+    queryKey: ['flex-offer', { departurePriceId, returnPriceId, adults, children, babies }],
+    enabled: departurePriceId !== undefined,
+    queryFn: async () => (
+      await apiClient
+        .get('/api/orders/flex', {
+          params: {
+            departure_price_id: departurePriceId,
+            return_price_id: returnPriceId,
+            adults,
+            children,
+            babies
+          }
+        })
+        .then(response => response.data)
+    )
+  })
+);

package/types.ts

@@ -71,4 +71,10 @@ export interface AddonsSelection {
   whatsapp: boolean
   whatsappNumber: string
   telegram: boolean
+
+  // 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
 }