subscription API: basic E2E test ✅, API docs 📝 [todo]

Author: derhuerst

docs/readme.md

@@ -14,6 +14,7 @@
 - [`remarks([opt])`](remarks.md) – get all remarks
 - [`lines(query, [opt])`](lines.md) – get all lines matching a name
 - [`serverInfo([opt])`](server-info.md) – fetch meta information from HAFAS
+- [subscription-related methods](subscription-api.md)
 
 ## Migrating from an old `hafas-client` version
 

docs/subscription-api.md

@@ -0,0 +1,20 @@
+# subscription-related methods
+
+todo: explanation
+
+```js
+const {journeys} = await client.journeys(ludwigshafen, meckesheim, {
+	results: 1, polylines: true,
+})
+const journey = journeys[0]
+const channelId = 'some-channel'
+
+const userId = await client.createSubscriptionsUser([channelId])
+const subId = await client.subscribeToJourney(userId, [channelId], journey.refreshToken)
+
+const sub = await client.subscription(userId, subId, {journey: true, activeDays: true})
+
+await client.unsubscribe(userId, subId)
+```
+
+todo: API docs

index.js

@@ -691,6 +691,8 @@ const createClient = (profile, userAgent, opt = {}) => {
 			userId,
 			channels: channelIds.map((channelId) => ({channelId})),
 			conSubscr: {
+				// todo: data?
+				// seems like without it, HAFAS ignores the data inside `journeyRefreshToken`
 				ctxRecon: journeyRefreshToken,
 				hysteresis: {
 					minDeviationInterval: opt.minimumDelay,

test/e2e/vrn.js

@@ -227,3 +227,46 @@ test('radar', async (t) => {
 	validate(t, vehicles, 'movements', 'vehicles')
 	t.end()
 })
+
+test('subscribing to a journey works', async (t) => {
+	const {journeys} = await client.journeys(ludwigshafen, meckesheim, {
+		departure: when, results: 1,
+	})
+	const journey = journeys[0]
+	const channelId = 'some-channel'
+
+	const userId = await client.createSubscriptionsUser([channelId])
+	t.equal(typeof userId, 'string')
+	t.ok(userId)
+	t.deepEqual(await client.subscriptions(userId), [])
+
+	const subId = await client.subscribeToJourney(userId, [channelId], journey.refreshToken)
+	t.ok(subId !== undefined && subId !== null, 'subId')
+
+	const {
+		subscription: sub, rtEvents, himEvents,
+	} = await client.subscription(userId, subId, {activeDays: true})
+	t.ok(sub)
+	t.equal(sub.id, subId)
+	t.deepEqual(sub.hysteresis, {minDeviationInterval: 1, notificationStart: 30})
+	t.deepEqual(sub.monitorFlags, ['AF', 'DF', 'DV', 'FTF', 'OF', 'PF'])
+	t.ok(Array.isArray(sub.connectionInfo))
+	t.ok(sub.connectionInfo.length > 0)
+	t.equal(sub.journeyRefreshToken, journey.refreshToken)
+	t.ok(sub.activeDays)
+	t.ok(Array.isArray(rtEvents))
+	t.ok(Array.isArray(himEvents))
+
+	const subs = await client.subscriptions(userId)
+	t.deepEqual(subs, [{
+		id: subId,
+		status: 'ACTIVE',
+		channels: [{id: channelId}],
+		journeyRefreshToken: journey.refreshToken,
+	}])
+
+	await client.unsubscribe(userId, subId)
+	t.deepEqual(await client.subscriptions(userId), [])
+
+	t.end()
+})