lines: realtimeDataFrom -> realtimeDataUpdatedAt 💥✅📝

docs/lines.md

@@ -12,9 +12,16 @@ const svvProfile = require('hafas-client/p/svv')
 
 const client = createClient(svvProfile, 'my-awesome-program')
 
-await client.lines('S1')
+const {
+	lines,
+	realtimeDataUpdatedAt,
+} = await client.lines('S1')
 ```
 
+`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated.
+
+`lines` may look like this:
+
 ```js
 [
 	{

index.js

@@ -724,10 +724,9 @@ const createClient = (profile, userAgent, opt = {}) => {
 			res, common,
 		} = await profile.request({profile, opt}, userAgent, req)
 
-		// todo [breaking]: return object with realtimeDataUpdatedAt
 		if (!Array.isArray(res.lineL)) return []
 		const ctx = {profile, opt, common, res}
-		return res.lineL.map(l => {
+		const lines = res.lineL.map(l => {
 			const parseDirRef = i => (res.common.dirL[i] || {}).txt || null
 			return {
 				...omit(l.line, ['id', 'fahrtNr']),
@@ -741,6 +740,13 @@ const createClient = (profile, userAgent, opt = {}) => {
 					: null,
 			}
 		})
+
+		return {
+			lines,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
+		}
 	}
 
 	const serverInfo = async (opt = {}) => {

test/e2e/bvg.js

@@ -27,6 +27,7 @@ const testArrivals = require('./lib/arrivals')
 const testJourneysWithDetour = require('./lib/journeys-with-detour')
 const testReachableFrom = require('./lib/reachable-from')
 const testRemarks = require('./lib/remarks')
+const testLines = require('./lib/lines')
 
 const T_MOCK = 1641897000 * 1000 // 2022-01-11T11:30:00+01
 const when = createWhen(bvgProfile.timezone, bvgProfile.locale, T_MOCK)
@@ -458,3 +459,13 @@ tap.test('remarks', async (t) => {
 	})
 	t.end()
 })
+
+tap.test('lines', async (t) => {
+	await testLines({
+		test: t,
+		fetchLines: client.lines,
+		validate,
+		query: 'M10',
+	})
+	t.end()
+})

test/e2e/lib/lines.js

@@ -0,0 +1,26 @@
+'use strict'
+
+const testLines = async (cfg) => {
+	const {
+		test: t,
+		fetchLines,
+		validate,
+		query,
+	} = cfg
+
+	const res = await fetchLines(query)
+	const {
+		lines,
+		realtimeDataUpdatedAt,
+	} = res
+
+	for (let i = 0; i < res.lines.length; i++) {
+		const l = res.lines[i]
+		const name = `res.lines[${i}]`
+		validate(t, l, 'line', name)
+	}
+
+	validate(t, realtimeDataUpdatedAt, 'realtimeDataUpdatedAt', 'res.realtimeDataUpdatedAt')
+}
+
+module.exports = testLines