From 8a45d26fda79ad35bf804e6dba1bf8960c067911 Mon Sep 17 00:00:00 2001
From: Jannis R <mail@jannisr.de>
Date: Tue, 24 Jul 2018 18:16:14 +0200
Subject: [PATCH] add docs for refreshJourneys (c88071f) :memo:

---
 docs/readme.md          |  1 +
 docs/refresh-journey.md | 38 ++++++++++++++++++++++++++++++++++++++
 p/insa/example.js       |  4 ++++
 p/vbb/example.js        |  4 ++++
 4 files changed, 47 insertions(+)
 create mode 100644 docs/refresh-journey.md

diff --git a/docs/readme.md b/docs/readme.md
index f7d3a42b..9c85bce2 100644
--- a/docs/readme.md
+++ b/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
diff --git a/docs/refresh-journey.md b/docs/refresh-journey.md
new file mode 100644
index 00000000..94e6025c
--- /dev/null
+++ b/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()`.
diff --git a/p/insa/example.js b/p/insa/example.js
index a697f110..8d92c4fe 100644
--- a/p/insa/example.js
+++ b/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 }))
 })
diff --git a/p/vbb/example.js b/p/vbb/example.js
index 6a1968c2..5a79930f 100644
--- a/p/vbb/example.js
+++ b/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}))
 })