remarks: realtimeDataFrom -> realtimeDataUpdatedAt 💥✅📝

docs/remarks.md

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

index.js

@@ -702,10 +702,16 @@ const createClient = (profile, userAgent, opt = {}) => {
 			res, common,
 		} = await profile.request({profile, opt}, userAgent, req)
 
-		// todo [breaking]: return object with realtimeDataUpdatedAt
 		const ctx = {profile, opt, common, res}
-		return (res.msgL || [])
+		const remarks = (res.msgL || [])
 		.map(w => profile.parseWarning(ctx, w))
+
+		return {
+			remarks,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
+		}
 	}
 
 	const lines = async (query, opt = {}) => {

test/e2e/bvg.js

@@ -26,6 +26,7 @@ const testDeparturesInDirection = require('./lib/departures-in-direction')
 const testArrivals = require('./lib/arrivals')
 const testJourneysWithDetour = require('./lib/journeys-with-detour')
 const testReachableFrom = require('./lib/reachable-from')
+const testRemarks = require('./lib/remarks')
 
 const T_MOCK = 1641897000 * 1000 // 2022-01-11T11:30:00+01
 const when = createWhen(bvgProfile.timezone, bvgProfile.locale, T_MOCK)
@@ -447,3 +448,13 @@ tap.test('reachableFrom', async (t) => {
 	})
 	t.end()
 })
+
+tap.test('remarks', async (t) => {
+	await testRemarks({
+		test: t,
+		fetchRemarks: client.remarks,
+		when,
+		validate,
+	})
+	t.end()
+})

test/e2e/lib/remarks.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const WEEK = 7 * 24 * 60 * 60 * 1000
+
+const testRemarks = async (cfg) => {
+	const {
+		test: t,
+		fetchRemarks,
+		validate,
+		when,
+	} = cfg
+
+	const res = await fetchRemarks({
+		results: 10,
+		from: when,
+		to: new Date(when + WEEK),
+	})
+	const {
+		remarks,
+		realtimeDataUpdatedAt,
+	} = res
+
+	for (let i = 0; i < res.remarks.length; i++) {
+		const rem = res.remarks[i]
+		const name = `res.remarks[${i}]`
+		validate(t, rem, 'remark', name)
+	}
+
+	// most endpoints currently don't provide this info for remarks()
+	if (realtimeDataUpdatedAt !== null) {
+		validate(t, realtimeDataUpdatedAt, 'realtimeDataUpdatedAt', 'res.realtimeDataUpdatedAt')
+	}
+}
+
+module.exports = testRemarks