@autobusal/providers 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ adheres to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 > Note: 1.8.0 through 1.11.0 were published without changelog entries. The
 > gap is left as-is rather than reconstructed after the fact.
 
+## 1.20.0
+
+`FoundData.departs_in` — minutes until departure, for same-day searches only,
+null on every other date.
+
+## 1.19.0
+
+`types/reviews.ts` — `RatingData`, `ReviewData`, `ReviewSummaryData`. `rating`
+added to `OperatorData` and `RouteData`, always optional and often absent.
+
 ## 1.18.0
 
 `LabelSettings.reviews` — the per-brand review moderation setting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/providers",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"

package/types/operators.ts

@@ -1,7 +1,11 @@
 import { RouteData } from './routes';
+import { RatingData } from './reviews';
 import { UserData } from './users';
 
 export interface OperatorData {
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Absent until the operator has enough published reviews - see RatingData.
+  rating?: RatingData | null
   id: number
   company: string
   nipt: string

package/types/reviews.ts

@@ -0,0 +1,43 @@
+/**
+ * Published reviews, as the public route and operator pages read them.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ */
+
+/**
+ * A score worth showing.
+ *
+ * ALWAYS optional and often absent: obtapi withholds it entirely until a
+ * route or operator has enough published reviews to say something honest
+ * (App\Traits\Rateable). "5.0 from one review" reads worse than no rating at
+ * all, so the absence is the feature - never fill it in with a zero.
+ */
+export interface RatingData {
+  average: number
+  count: number
+}
+
+export interface ReviewSummaryData extends RatingData {
+  // 5 down to 1, each mapped to how many reviews gave that many stars. An
+  // average of 4.0 from straight fours and one from fives and ones describe
+  // different operators, and only the spread tells them apart.
+  histogram: Record<string, number>
+}
+
+export interface ReviewReplyData {
+  body: string
+  published_at: string | null
+}
+
+export interface ReviewData {
+  id: number
+  rating: number
+  // rating-only reviews are deliberately allowed, so this is often null
+  body: string | null
+  // what it was WRITTEN in - shown as-is, never machine translated
+  language: string
+  // first name plus an initial, built server-side
+  author: string
+  published: string | null
+  reply: ReviewReplyData | null
+}

package/types/routes.ts

@@ -2,9 +2,13 @@ import { AgentData } from './agents';
 import { BusData } from './buses';
 import { LocationData, CountryData } from './locations';
 import { OperatorData } from './operators';
+import { RatingData } from './reviews';
 import { OrderData } from './orders';
 
 export interface RouteData {
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Absent until the route has enough published reviews - see RatingData.
+  rating?: RatingData | null
   id: number
   name: string
   code: string
@@ -109,6 +113,13 @@ export interface FoundData extends Omit<RouteData, 'locations' | 'id'> {
   // must read "missing" as unknown, never as direct.
   stops_count?: number
   // Edited: Ferjolt Ozuni - Date: 2026-08-01
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Minutes until this coach leaves, for TODAY's searches only - null on
+  // every other date. Computed server-side, because a countdown built from
+  // the visitor's own clock is wrong for anybody whose device is off or in
+  // another timezone, and "leaves in 20 minutes" must not be wrong.
+  departs_in?: number | null
+
   // The operator's subscription priority, as obtapi already sends it.
   // Used only as a tiebreak in the "recommended" ordering - see
   // routes-order's Found/refine.ts. Absent on external-provider offers.