journeys/refreshJourney/journeysFromTrip: realtimeDataFrom -> realtimeDataUpdatedAt 💥✅📝

docs/journeys-from-trip.md

@@ -39,7 +39,12 @@ const leg = journey.legs.find(l => l.line.product === 'nationalExpress')
 const previousStopover = leg.stopovers.find(st => st.departure && new Date(st.departure) < Date.now())
 
 // find journeys from the ICE train to Köln Hbf
-const journeys = await client.journeysFromTrip(leg.id, previousStopover, kölnHbf)
+const {
+	journeys,
+	realtimeDataUpdatedAt,
+} = await client.journeysFromTrip(leg.id, previousStopover, kölnHbf)
 ```
 
-`journeys` will be an array of [FPTF `journey`s](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md#journey), as documented in [`journeys()`](journeys.md).
+`journeys` is an array of [FPTF `journey`s](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md#journey), as documented in [`journeys()`](journeys.md).
+
+`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated.

docs/journeys.md

@@ -97,7 +97,12 @@ await client.journeys('900000003201', '900000100008', {
 })
 ```
 
-`journeys()` will resolve with an object with the `journeys` & `earlierRef`/`laterRef` fields. It might look like this:
+`journeys()` will resolve with an object with the following fields:
+- `journeys`
+- `earlierRef`/`laterRef` – pass them as `opt.earlierThan`/`opt.laterThan` into another `journeys()` call to retrieve the next "page" of journeys
+- `realtimeDataUpdatedAt` – a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated
+
+This object might look like this:
 
 ```js
 {
@@ -267,6 +272,7 @@ await client.journeys('900000003201', '900000100008', {
 	} ],
 	earlierRef: '…', // use with the `earlierThan` option
 	laterRef: '…' // use with the `laterThan` option
+	realtimeDataUpdatedAt: 1531259400, // 2018-07-10T23:50:00+02
 }
 ```
 

docs/refresh-journey.md

@@ -30,7 +30,10 @@ const client = createClient(vbbProfile)
 const {journeys} = await client.journeys('900000003201', '900000100008', {results: 1})
 
 // later, fetch up-to-date info on the journey
-await client.refreshJourney(journeys[0].refreshToken, {stopovers: true, remarks: true})
+const journey = await client.refreshJourney(journeys[0].refreshToken, {stopovers: true, remarks: true})
+const {realtimeDataUpdatedAt} = journey
 ```
 
-`refreshJourney()` will return a *single* [*Friendly Public Transport Format* v2 draft](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md) `journey`, in the same format as with `journeys()`.
+`journey` is a *single* [*Friendly Public Transport Format* v2 draft](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md) `journey`, in the same format as returned by [`journeys()`](journeys.md).
+
+`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated.

index.js

@@ -231,8 +231,9 @@ const createClient = (profile, userAgent, opt = {}) => {
 			earlierRef: res.outCtxScrB,
 			laterRef: res.outCtxScrF,
 			journeys,
-			// todo [breaking]: rename to realtimeDataUpdatedAt
-			realtimeDataFrom: res.planrtTS ? parseInt(res.planrtTS) : null,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
 		}
 	}
 
@@ -261,8 +262,9 @@ const createClient = (profile, userAgent, opt = {}) => {
 		const ctx = {profile, opt, common, res}
 
 		return {
-			// todo [breaking]: rename to realtimeDataUpdatedAt
-			realtimeDataFrom: res.planrtTS ? parseInt(res.planrtTS) : null,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
 			...profile.parseJourney(ctx, res.outConL[0])
 		}
 	}
@@ -368,8 +370,7 @@ const createClient = (profile, userAgent, opt = {}) => {
 		if (!Array.isArray(res.outConL)) return []
 
 		const ctx = {profile, opt, common, res}
-		// todo [breaking]: return object with realtimeDataUpdatedAt
-		return res.outConL
+		const journeys = res.outConL
 		.map(rawJourney => profile.parseJourney(ctx, rawJourney))
 		.map((journey) => {
 			// For the first (transit) leg, HAFAS sometimes returns *all* past
@@ -388,6 +389,13 @@ const createClient = (profile, userAgent, opt = {}) => {
 				],
 			}
 		})
+
+		return {
+			journeys,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
+		}
 	}
 
 	const locations = async (query, opt = {}) => {

test/e2e/lib/refresh-journey.js

@@ -15,16 +15,17 @@ const testRefreshJourney = async (cfg) => {
 		test: t,
 		fetchJourneys,
 		refreshJourney,
+		validate,
 		fromId,
 		toId,
 		when,
-		// todo: validate
 	} = cfg
 
 	const modelRes = await fetchJourneys(fromId, toId, {
 		results: 1, departure: when,
 		stopovers: false
 	})
+	validate(t, modelRes, 'journeysResult', 'modelRes')
 	const [model] = modelRes.journeys
 
 	// todo: move to journeys validator?
@@ -34,6 +35,8 @@ const testRefreshJourney = async (cfg) => {
 	const refreshed = await refreshJourney(model.refreshToken, {
 		stopovers: false
 	})
+	validate(t, refreshed, 'refreshJourneyResult', 'refreshed')
+
 	t.same(simplify(refreshed), simplify(model))
 }
 

test/e2e/lib/validators.js

@@ -428,6 +428,14 @@ const validateJourneysResult = (val, res, name = 'journeysResult') => {
 	a.ok(isObj(res), name + ' must be an object')
 	// todo: `earlierRef`, `laterRef`
 	val.journeys(val, res.journeys, name + '.journeys')
+
+	val.realtimeDataUpdatedAt(val, res.realtimeDataUpdatedAt, name + '.realtimeDataUpdatedAt')
+}
+
+const validateRefreshJourneyResult = (val, res, name = 'refreshJourneyResult') => {
+	val.journey(val, res, name + '.journey')
+
+	val.realtimeDataUpdatedAt(val, res.realtimeDataUpdatedAt, name + '.realtimeDataUpdatedAt')
 }
 
 const validateTrip = (val, trip, name = 'trip') => {
@@ -619,6 +627,7 @@ module.exports = {
 	journey: () => validateJourney,
 	journeys: () => validateJourneys,
 	journeysResult: () => validateJourneysResult,
+	refreshJourneyResult: () => validateRefreshJourneyResult,
 	trip: () => validateTrip,
 	arrival: createValidateArrival,
 	departure: createValidateDeparture,