Companion app (beta)

Beta

The TravStats Companion app is in testing. It has no store listing, and this page carries no download link. The Devices section that mints a claim code sits behind the instance beta switch, off by default: with the switch off, nobody but someone who knows the section’s address can pair a phone. Pairing works end to end; the app and the flows behind it are unfinished, which is why the owner ruled all of it beta for 2.6.0.

The Companion is a phone app that reads your instance: the start board with your headline figures, the globe, the countries, the passport. It talks to the same API the web UI does, over a device-bound token you never see, against the public URL your administrator configured.

What it reads

The app consumes the server’s answers rather than deriving its own — that is the point of the endpoints added in 2.6.0:

• The hero tile — flights, distance, countries, counted by the same evidence rule the web UI uses, so a swipe apart the two never disagree.
• The route network (/stats/network) — every airport with coordinates, every route with a count and a distance, unbounded, because a truncated network is a wrong globe, not a smaller one. A route is the pair, not the direction.
• The records (/stats/records) — as numbers with units, so the app formats them in its own language.
• The passport (/stats/passport) — and it reads that endpoint whatever the instance’s beta switch says, because the switch hides the web page, not the API.
• Country flags (/country-flags?codes=) — up to 250 in one request, so the app can preload the countries it actually has.
• Your display preferences — units, formats and the like sync to and from the server, so a re-paired or new device restores them.

Places, when the app writes them, go through the same import routes the web import uses (/place-import/preview and /commit), so a place recorded on the phone carries the identity a later import would mint.

Pairing a phone

Under Settings → Devices (with the beta switch on):

1. Connect new device mints a single-use claim code and renders it as a QR code. The code expires after ten minutes, with a live countdown; you can generate a fresh one.
2. In the app, open Connect and scan the QR. The app exchanges the code for a device-bound access token — you never type or copy a token by hand.
3. The browser shows “connected” as soon as the phone claims the code.

Below the pairing panel, Connected devices lists every paired device with its platform, last-used time and address. Sign out revokes that device’s token immediately.

Security properties

• A claim code can only be minted from a browser session — an API token cannot mint one, so a leaked token cannot escalate itself into a device token.
• The code travels in the request body, never in a URL, so it never lands in access logs. Only its SHA-256 is stored.
• Re-pairing the same physical device revokes its previous token, so orphaned credentials do not accumulate.
• Pairing needs a public URL configured under Admin → Instance; without one the panel shows a warning instead of a QR, because the app would have no address to reach.
• The pairing routes (/pairing/*) stay reachable whatever the beta switch says. The switch hides the Devices UI; it is a visibility gate, not a security boundary, and the token the phone holds is a real credential with the account’s read scope.

The app’s own manual

This page describes the Companion from the server’s side — what it reads, how a phone is paired, what the pairing guarantees. The app has a manual of its own: twenty-five pages covering installing, pairing, capture, places, the globe, settings and troubleshooting.

Open the Companion manual

It asks for a user name and a password, because it is closed while the app is in beta — it documents builds that change between weeks, and saying so in a manual is not the same as publishing one. Testers have the credentials; ask if you are one and do not.

The door opens for everybody on the day the app ships.

What “in testing” means

The app is being used by testers against instances that run the release candidates. It is not in an app store, it is not signed for general distribution, and screens change between builds. If you have been given a build, expect the flows around places and photographs to move; the read-only surfaces — start board, globe, passport — are the stable part.

Limits

• No public download. This page will link one when there is one.
• It writes, and that is the newer half. This page used to say the app was read-mostly and that places were its only write path. That stopped being true: the app records flights, cruises and stays as well, from a scanned boarding pass, a photographed document, a pasted email or the manual form — with price, board, room, cabin, booking reference and, for a cruise, the whole itinerary. What is still unfinished is the polish around those flows, not their existence.
• One instance per pairing. A device token belongs to one account on one instance.
• The Devices section is the only place a claim code is minted. With the beta switch off, an instance owner can still reach the section by its address (/settings?section=devices), which is a deliberate property of the gate rather than a gap in it — otherwise the switch would lock the owner out of pairing.
• Sync is one-way for travel data. Preferences sync both ways; travel records are read from the server.