add docs for refreshJourneys (c88071f) 📝

docs/readme.md

@@ -1,6 +1,7 @@
 # API documentation
 
 - [`journeys(from, to, [opt])`](journeys.md) – get journeys between locations
+- [`refreshJourney(refreshToken, [opt])`](refresh-journey.md) – fetch up-to-date/more details of a `journey`
 - [`trip(id, lineName, [opt])`](trip.md) – get details for a trip
 - [`departures(station, [opt])`](departures.md) – query the next departures at a station
 - [`arrivals(station, [opt])`](arrivals.md) – query the next arrivals at a station

docs/refresh-journey.md

@@ -0,0 +1,38 @@
+# `refreshJourney(refreshToken, [opt])`
+
+`refreshToken` must be a string, taken from `journey.refreshToken`.
+
+With `opt`, you can override the default options, which look like this:
+
+```js
+{
+	stopovers: false, // return stations on the way?
+	polylines: false, // return a shape for each leg?
+	tickets: false, // return tickets? only available with some profiles
+	remarks: true, // parse & expose hints & warnings?
+	language: 'en' // language to get results in
+}
+```
+
+## Response
+
+As an example, we're going to use the [VBB profile](../p/vbb):
+
+```js
+const createClient = require('hafas-client')
+const vbbProfile = require('hafas-client/p/vbb')
+
+const client = createClient(vbbProfile)
+
+// Hauptbahnhof to Heinrich-Heine-Str.
+client.journeys('900000003201', '900000100008', {results: 1})
+.then(([journey]) => {
+	// later, fetch up-to-date info on the journey
+	client.refreshJourney(journey.refreshToken, {stopovers: true, remarks: true})
+	.then(console.log)
+	.catch(console.error)
+})
+.catch(console.error)
+```
+
+`refreshJourney()` will return a *single* [*Friendly Public Transport Format* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/tree/1.0.1) `journey`, in the same format as with `journeys()`.

p/insa/example.js

@@ -29,6 +29,10 @@ client.journeys('008010226', '008013456', {results: 1})
 // 	return client.trip(leg.id, leg.line.name)
 // })
 
+// .then(([journey]) => {
+// 	return client.refreshJourney(journey.refreshToken, {stopovers: true, remarks: true})
+// })
+
 .then(data => {
 	console.log(require('util').inspect(data, { depth: null }))
 })

p/vbb/example.js

@@ -27,6 +27,10 @@ client.journeys('900000003201', '900000024101', {results: 1, polylines: true})
 // 	const leg = journey.legs[0]
 // 	return client.trip(leg.id, leg.line.name, {polyline: true})
 // })
+
+// .then(([journey]) => {
+// 	return client.refreshJourney(journey.refreshToken, {stopovers: true, remarks: true})
+// })
 .then((data) => {
 	console.log(require('util').inspect(data, {depth: null}))
 })