zenbus-next-bus 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gautric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# zenbus-next-bus
+
+Real-time next bus ETA from [Zenbus](https://zenbus.net) networks, streamed to your terminal.
+
+Calls the Zenbus API directly using protobuf — no browser, no scraping.
+
+## Install
+
+```bash
+npm install -g zenbus-next-bus
+```
+
+## CLI Usage
+
+```bash
+zenbus-next-bus --alias gpso --itinerary 5426824545828864 --stop 5366312231501824
+```
+
+### Options
+
+| Option | Env var | Description | Required |
+|---|---|---|---|
+| `--alias` | `ZENBUS_ALIAS` | Network alias (e.g. `gpso`) | yes |
+| `--itinerary` | `ZENBUS_ITINERARY` | Itinerary ID | yes |
+| `--stop` | `ZENBUS_STOP` | Stop ID | yes |
+| `--interval` | `ZENBUS_INTERVAL` | Poll interval in seconds (default: 10) | no |
+| `--output` | | Output format: `terminal` or `json` (default: terminal) | no |
+
+### Terminal output (default)
+
+Live-updating display with real-time ETA, distance, scheduled time, and 2nd bus when available.
+
+### JSON output
+
+```bash
+zenbus-next-bus --alias gpso --itinerary ... --stop ... --output json
+```
+
+Outputs one JSON object per poll cycle to stdout — ideal for piping to other tools.
+
+## Programmatic Usage
+
+```js
+import { createClient } from 'zenbus-next-bus';
+
+const client = await createClient({ alias: 'gpso', itinerary: '...', stop: '...' });
+const data = await client.poll();
+console.log(data.next); // { etaMinutes, distanceM, estimatedArrival, scheduledTime, isLive }
+```
+
+## Node-RED
+
+Install in your Node-RED directory:
+
+```bash
+npm install zenbus-next-bus
+```
+
+The `zenbus-next-bus` node appears in the palette. Configure alias, itinerary, stop, and interval. It outputs `msg.payload` with the full poll data on each cycle.
+
+### Sample flow
+
+A ready-to-use example is bundled with the package. In Node-RED, go to **Menu → Import → Examples → zenbus-next-bus → debug-next-bus** to import a flow that wires the node to a debug output.
+
+You can also import it manually from `examples/debug-next-bus.json`.
+
+## Finding your IDs
+
+Open your stop on [zenbus.net](https://zenbus.net), the URL contains the IDs:
+
+```
+https://zenbus.net/publicapp/web/{alias}?line=...&stop={stop}&itinerary={itinerary}
+```
+
+## License
+
+MIT

package/examples/debug-next-bus.json

@@ -0,0 +1,39 @@
+[
+    {
+        "id": "zenbus1",
+        "type": "zenbus-next-bus",
+        "z": "flow1",
+        "name": "Zenbus ETA",
+        "alias": "gpso",
+        "itinerary": "5426824545828864",
+        "stop": "5366312231501824",
+        "interval": "10",
+        "x": 200,
+        "y": 200,
+        "wires": [["debug1"]]
+    },
+    {
+        "id": "debug1",
+        "type": "debug",
+        "z": "flow1",
+        "name": "Bus ETA Debug",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "complete": "payload",
+        "targetType": "msg",
+        "statusVal": "payload.next.etaMinutes",
+        "statusType": "auto",
+        "x": 450,
+        "y": 200,
+        "wires": []
+    },
+    {
+        "id": "flow1",
+        "type": "tab",
+        "label": "Zenbus Next Bus",
+        "disabled": false,
+        "info": ""
+    }
+]

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "zenbus-next-bus",
+  "version": "1.0.0",
+  "description": "Real-time next bus ETA from Zenbus networks via direct API (protobuf)",
+  "type": "module",
+  "bin": {
+    "zenbus-next-bus": "./zenbus-next-bus.mjs"
+  },
+  "exports": {
+    ".": "./zenbus-core.mjs",
+    "./core": "./zenbus-core.mjs",
+    "./node-red": "./zenbus-node-red.mjs"
+  },
+  "node-red": {
+    "nodes": {
+      "zenbus-next-bus": "zenbus-node-red.cjs"
+    },
+    "examples": {
+      "zenbus-next-bus": ["examples/debug-next-bus.json"]
+    }
+  },
+  "scripts": {
+    "start": "node zenbus-next-bus.mjs --alias gpso --itinerary 5426824545828864 --stop 5366312231501824"
+  },
+  "files": [
+    "zenbus-core.mjs",
+    "zenbus-next-bus.mjs",
+    "zenbus-node-red.cjs",
+    "zenbus-next-bus.html",
+    "icons",
+    "examples"
+  ],
+  "keywords": [
+    "zenbus",
+    "bus",
+    "transit",
+    "real-time",
+    "eta",
+    "protobuf",
+    "cli",
+    "node-red"
+  ],
+  "author": "gautric",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "protobufjs": "^8.0.1",
+    "yargs": "^17.7.2"
+  }
+}

package/zenbus-core.mjs

@@ -0,0 +1,82 @@
+import protobuf from 'protobufjs';
+
+const BASE = 'https://zenbus.net';
+
+async function fetchProto(url, Type) {
+  const buf = Buffer.from(await (await fetch(url)).arrayBuffer());
+  return Type.decode(buf);
+}
+
+function secsToHHMM(secs) {
+  const h = Math.floor(secs / 3600);
+  const m = Math.floor((secs % 3600) / 60);
+  return `${h}h${String(m).padStart(2, '0')}`;
+}
+
+export async function createClient({ alias, itinerary, stop }) {
+  const protoText = await (await fetch(`${BASE}/poll/cdn/zenbus.proto`)).text();
+  const { root } = protobuf.parse(protoText);
+  const StaticMessage = root.lookupType('zenbus_realtime.StaticMessage');
+  const LiveMessage = root.lookupType('zenbus_realtime.LiveMessage');
+
+  const staticData = await fetchProto(`${BASE}/publicapp/static-data?alias=${alias}`, StaticMessage);
+  const shape = staticData.shape?.find(s => s.itineraryId?.toString() === itinerary);
+  const stopAnchor = shape?.anchor?.find(a => a.stopId?.toString() === stop);
+  const stopIndex = stopAnchor?.stopIndexInItinerary ?? -1;
+  const stopDistanceM = stopAnchor?.distanceTravelled ?? 0;
+  const stopName = staticData.stop?.find(s => s.stopId?.toString() === stop)?.name || 'Unknown';
+  const itin = staticData.itinerary?.find(i => i.itineraryId?.toString() === itinerary);
+  const lineCode = staticData.line?.find(l => l.lineId?.toString() === itin?.lineId?.toString())?.code || 'Unknown';
+
+  const pollUrl = `${BASE}/publicapp/poll?alias=${alias}&itinerary=${itinerary}`;
+
+  return {
+    stopName, lineCode,
+    async poll() {
+      const liveData = await fetchProto(pollUrl, LiveMessage);
+      const now = new Date();
+      const midnightUtcSecs = liveData.timetable?.[0]?.midnight?.toNumber?.()
+        ?? Math.floor(new Date(now).setHours(0, 0, 0, 0) / 1000);
+      const nowSecs = Math.floor(now.getTime() / 1000) - midnightUtcSecs;
+
+      const allColumns = [...(liveData.tripColumn || [])];
+      for (const tt of liveData.timetable || []) {
+        for (const col of tt.column || []) allColumns.push(col);
+      }
+
+      const candidates = [];
+      for (const tc of allColumns) {
+        const est = tc.estimactual?.find(s => s.stopIndexInItinerary === stopIndex);
+        const etaSecs = est?.arrival || est?.departure || 0;
+        if (!etaSecs || etaSecs <= nowSecs) continue;
+
+        const vehicleDist = tc.distanceTravelled || 0;
+        const hasStarted = tc.previousIndexInItinerary >= 0 && tc.pos?.length > 0;
+        if (hasStarted && vehicleDist > stopDistanceM) continue;
+
+        const remainingDist = hasStarted ? Math.max(0, stopDistanceM - vehicleDist) : stopDistanceM;
+        const aimed = tc.aimed?.find(s => s.stopIndexInItinerary === stopIndex);
+        const schedSecs = aimed?.arrival || aimed?.departure || aimed?.arriparture || 0;
+
+        candidates.push({
+          etaMinutes: Math.round((etaSecs - nowSecs) / 60),
+          distanceM: Math.round(remainingDist),
+          estimatedArrival: secsToHHMM(etaSecs),
+          scheduledTime: schedSecs ? secsToHHMM(schedSecs) : null,
+          isLive: hasStarted,
+        });
+      }
+
+      candidates.sort((a, b) => a.etaMinutes - b.etaMinutes);
+      const best = candidates[0] || null;
+      const second = candidates.find((c, i) => i > 0 && c.isLive) || null;
+
+      return {
+        stop: stopName, line: lineCode,
+        timestamp: now.toISOString(),
+        now: secsToHHMM(nowSecs),
+        next: best, secondBus: second,
+      };
+    },
+  };
+}

package/zenbus-next-bus.html

@@ -0,0 +1,77 @@
+<script type="text/javascript">
+  RED.nodes.registerType('zenbus-next-bus', {
+    category: 'transport',
+    color: '#8e6538',
+    defaults: {
+      name: { value: '' },
+      alias: { value: '', required: true },
+      itinerary: { value: '', required: true },
+      stop: { value: '', required: true },
+      interval: { value: 10, validate: RED.validators.number() }
+    },
+    inputs: 0,
+    outputs: 1,
+    icon: 'zenbus.png',
+    label: function () {
+      return this.name || 'zenbus ' + (this.alias || '');
+    },
+    paletteLabel: 'zenbus next bus'
+  });
+</script>
+
+<script type="text/html" data-template-name="zenbus-next-bus">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Name">
+  </div>
+  <div class="form-row">
+    <label for="node-input-alias"><i class="fa fa-globe"></i> Alias</label>
+    <input type="text" id="node-input-alias" placeholder="e.g. gpso">
+  </div>
+  <div class="form-row">
+    <label for="node-input-itinerary"><i class="fa fa-road"></i> Itinerary</label>
+    <input type="text" id="node-input-itinerary" placeholder="Itinerary ID">
+  </div>
+  <div class="form-row">
+    <label for="node-input-stop"><i class="fa fa-map-marker"></i> Stop</label>
+    <input type="text" id="node-input-stop" placeholder="Stop ID">
+  </div>
+  <div class="form-row">
+    <label for="node-input-interval"><i class="fa fa-clock-o"></i> Interval (s)</label>
+    <input type="number" id="node-input-interval" min="5" step="1">
+  </div>
+</script>
+
+<script type="text/html" data-help-name="zenbus-next-bus">
+  <p>Polls the <a href="https://zenbus.net">Zenbus</a> real-time API and outputs next bus ETA.</p>
+
+  <h3>Configuration</h3>
+  <dl class="message-properties">
+    <dt>Alias <span class="property-type">string</span></dt>
+    <dd>Network alias (e.g. <code>gpso</code>). Found in the Zenbus URL.</dd>
+    <dt>Itinerary <span class="property-type">string</span></dt>
+    <dd>Itinerary ID from the Zenbus URL.</dd>
+    <dt>Stop <span class="property-type">string</span></dt>
+    <dd>Stop ID from the Zenbus URL.</dd>
+    <dt>Interval <span class="property-type">number</span></dt>
+    <dd>Poll interval in seconds (default 10).</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>payload.stop <span class="property-type">string</span></dt>
+    <dd>Stop name.</dd>
+    <dt>payload.line <span class="property-type">string</span></dt>
+    <dd>Line code.</dd>
+    <dt>payload.next <span class="property-type">object | null</span></dt>
+    <dd>Next bus: <code>etaMinutes</code>, <code>distanceM</code>, <code>estimatedArrival</code>, <code>scheduledTime</code>, <code>isLive</code>.</dd>
+    <dt>payload.secondBus <span class="property-type">object | null</span></dt>
+    <dd>Second tracked bus (same fields), only when live distance is available.</dd>
+    <dt>payload.timestamp <span class="property-type">string</span></dt>
+    <dd>ISO timestamp of the poll.</dd>
+  </dl>
+
+  <h3>Finding your IDs</h3>
+  <p>Open your stop on <a href="https://zenbus.net">zenbus.net</a>. The URL contains:</p>
+  <pre>https://zenbus.net/publicapp/web/{alias}?line=...&amp;stop={stop}&amp;itinerary={itinerary}</pre>
+</script>

package/zenbus-next-bus.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { createClient } from './zenbus-core.mjs';
+
+const argv = yargs(hideBin(process.argv))
+  .env('ZENBUS')
+  .option('alias', { type: 'string', demandOption: true, describe: 'Network alias (e.g. gpso)' })
+  .option('itinerary', { type: 'string', demandOption: true, describe: 'Itinerary ID' })
+  .option('stop', { type: 'string', demandOption: true, describe: 'Stop ID' })
+  .option('interval', { type: 'number', default: 10, describe: 'Poll interval in seconds' })
+  .option('output', { type: 'string', choices: ['terminal', 'json'], default: 'terminal', describe: 'Output format' })
+  .strict()
+  .parseSync();
+
+const client = await createClient(argv);
+
+function renderTerminal(data) {
+  process.stdout.write('\x1B[2J\x1B[H');
+  console.log('🚌 ZENBUS - Live Stream (Ctrl+C to quit)\n');
+  console.log('═══════════════════════════════════════');
+  console.log(`  🚏 Stop:       ${data.stop}`);
+  console.log(`  🚌 Line:       ${data.line}`);
+  if (data.next) {
+    const n = data.next;
+    console.log(`  ⏱️  ETA:        ${n.etaMinutes} min${n.isLive ? ' (real-time)' : ' (scheduled)'}`);
+    console.log(`  📏 Distance:   ${n.distanceM} m away`);
+    console.log(`  🕐 Arrival:    ${n.estimatedArrival}`);
+    if (n.scheduledTime) console.log(`  📅 Scheduled:  ${n.scheduledTime}`);
+    if (data.secondBus) {
+      const s = data.secondBus;
+      console.log(`  ───────────────────────────────────`);
+      console.log(`  2️⃣  2nd bus:    ${s.etaMinutes} min (${s.distanceM} m away)`);
+      console.log(`  🕐 Arrival:    ${s.estimatedArrival}`);
+    }
+  } else {
+    console.log(`  ⏱️  ETA:        No upcoming bus`);
+  }
+  console.log(`  🕑 Now:        ${data.now}`);
+  console.log('═══════════════════════════════════════');
+}
+
+const render = argv.output === 'json'
+  ? (data) => console.log(JSON.stringify(data))
+  : renderTerminal;
+
+while (true) {
+  try { render(await client.poll()); } catch (e) { console.error('⚠️', e.message); }
+  await new Promise(r => setTimeout(r, argv.interval * 1000));
+}

package/zenbus-node-red.cjs

@@ -0,0 +1,41 @@
+module.exports = function (RED) {
+  function ZenbusNextBusNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    let timer = null;
+
+    const interval = (config.interval || 10) * 1000;
+
+    import('./zenbus-core.mjs').then(({ createClient }) => {
+      createClient({
+        alias: config.alias,
+        itinerary: config.itinerary,
+        stop: config.stop,
+      }).then(client => {
+        async function tick() {
+          try {
+            const data = await client.poll();
+            node.send({ payload: data });
+            node.status({
+              fill: data.next?.isLive ? 'green' : 'yellow',
+              shape: 'dot',
+              text: data.next ? `${data.next.etaMinutes} min – ${data.next.distanceM} m` : 'no bus',
+            });
+          } catch (e) {
+            node.error(e.message);
+            node.status({ fill: 'red', shape: 'ring', text: e.message });
+          }
+          timer = setTimeout(tick, interval);
+        }
+        tick();
+      }).catch(e => {
+        node.error(e.message);
+        node.status({ fill: 'red', shape: 'ring', text: 'init failed' });
+      });
+    });
+
+    node.on('close', () => { if (timer) clearTimeout(timer); });
+  }
+
+  RED.nodes.registerType('zenbus-next-bus', ZenbusNextBusNode);
+};