terminal readers sit offline and take no payments

"""Report Stripe Terminal readers that are offline, stale, wedged or behind on firmware.

Read only. One paginated GET and no writes: give this a RESTRICTED key with read
access to Terminal. The repair is printed, never performed, because this script
holds a credential to a live payments account.
"""
import argparse
import collections
import logging
import os
import sys
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("stripe_terminal_readers")

API = "https://api.stripe.com/v1"

# last_seen_at is in MILLISECONDS, unlike almost every other Stripe timestamp.
# Anything below this is a seconds value that has been passed in by mistake:
# 1e11 ms is 1973, and 1e11 seconds is the year 5138, so no real reading is
# ambiguous. Refusing to judge beats reporting a fleet as decades stale.
MS_FLOOR = 100_000_000_000

STALE_HOURS = 6.0


def reader_state(status, last_seen_at_ms, now_ms, action_status=None,
                 failure_code=None, stale_hours=STALE_HOURS):
    """Classify one Terminal reader. Pure, so the units guard can be tested offline.

    `last_seen_at_ms` and `now_ms` are both milliseconds. Returns (state, detail).
    """
    if last_seen_at_ms is not None and last_seen_at_ms < MS_FLOOR:
        return ("unknown",
                "last_seen_at is %d, which is a seconds timestamp; this reader "
                "cannot be judged until the units are right" % last_seen_at_ms)
    age_h = (None if last_seen_at_ms is None
             else (now_ms - last_seen_at_ms) / 3_600_000.0)
    if status == "offline":
        seen = "never seen" if age_h is None else "last seen %.1f hour(s) ago" % age_h
        return ("offline", "status offline, %s; it will not take a payment" % seen)
    if age_h is None:
        return ("unknown", "no last_seen_at, so liveness cannot be confirmed")
    if age_h >= stale_hours:
        return ("stale",
                "status %s but no check-in for %.1f hour(s); status lags reality, "
                "so treat this as unusable" % (status, age_h))
    if action_status == "failed":
        return ("action_failed",
                "reachable but wedged on a failed action: %s"
                % (failure_code or "no failure_code on the action"))
    if status == "online":
        return ("online", "checked in %.1f hour(s) ago" % age_h)
    return ("unknown", "unrecognised status %r" % (status,))


def firmware_outliers(readers):
    """Readers not on the version most of their own device_type is running. Pure.

    `readers` is a list of dicts with id, device_type and device_sw_version. A
    device type with a single reader has no majority and is skipped rather than
    reported as an outlier against itself.
    """
    by_type = collections.defaultdict(list)
    for r in readers:
        by_type[r.get("device_type")].append(r)
    out = []
    for device_type, group in sorted(by_type.items(), key=lambda kv: str(kv[0])):
        versions = collections.Counter(r.get("device_sw_version") for r in group
                                       if r.get("device_sw_version"))
        if len(group) < 2 or not versions:
            continue
        majority, _ = versions.most_common(1)[0]
        for r in group:
            v = r.get("device_sw_version")
            if v and v != majority:
                out.append((r.get("id"), device_type, v, majority))
    return out


def get(session, path, params):
    r = session.get(API + path, params=params, timeout=30)
    if r.status_code == 401:
        raise SystemExit("401 from Stripe: the key is wrong, or is for the other mode")
    if r.status_code == 403:
        raise SystemExit("403 from Stripe: the restricted key has no read access to "
                         "Terminal")
    r.raise_for_status()
    return r.json()


def page_all(session, path, params, cap=2000):
    out = []
    params = dict(params)
    while True:
        page = get(session, path, params)
        data = page.get("data", [])
        out.extend(data)
        if not data or not page.get("has_more") or len(out) >= cap:
            return out
        params["starting_after"] = data[-1]["id"]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--location", help="only check readers at this location id")
    ap.add_argument("--stale-hours", type=float, default=STALE_HOURS,
                    help="check-in age past which a reader is unusable")
    args = ap.parse_args()

    key = os.environ.get("STRIPE_API_KEY")
    if not key:
        log.error("set STRIPE_API_KEY (use a restricted, read-only key)")
        return 2

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + key})

    params = {"limit": 100}
    if args.location:
        params["location"] = args.location
    readers = page_all(s, "/terminal/readers", params)

    now_ms = int(time.time() * 1000)
    bad = 0
    freshest = None
    for r in readers:
        action = r.get("action") or {}
        state, detail = reader_state(r.get("status"), r.get("last_seen_at"), now_ms,
                                     action.get("status"), action.get("failure_code"),
                                     args.stale_hours)
        seen = r.get("last_seen_at")
        if seen and seen >= MS_FLOOR and (freshest is None or seen > freshest):
            freshest = seen
        if state != "online":
            bad += 1
            log.warning("  %-13s %s  %s  %s", state, r.get("id"),
                        r.get("label") or r.get("device_type"), detail)

    drift = firmware_outliers(readers)
    for rid, device_type, version, majority in drift:
        log.warning("  %-13s %s  %s on %s, the rest of the fleet is on %s",
                    "firmware", rid, device_type, version, majority)

    if not bad and not drift:
        age = 0.0 if freshest is None else (now_ms - freshest) / 3_600_000.0
        log.info("%-11s %d reader(s) online, newest check-in %.1fh, firmware consistent",
                 "clear", len(readers), age)
        return 0

    log.warning("%-11s %d of %d reader(s) not usable, %d on odd firmware",
                "offline", bad, len(readers), len(drift))
    log.warning("  power-cycle the reader and confirm the location's network reaches "
                "Stripe, then re-check:")
    log.warning("  GET %s/terminal/readers/<tmr_id>   "
                "(want status online AND a fresh last_seen_at)", API)
    log.warning("  leave drifting readers powered and connected through their "
                "configured update window")
    log.warning("  retire dead hardware so it stops filling this report:")
    log.warning("  DELETE %s/terminal/readers/<tmr_id>", API)
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report Stripe Terminal readers that are offline, stale, wedged or behind on firmware.
 *
 * Read only. One paginated GET and no writes: give this a RESTRICTED key with
 * read access to Terminal. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// last_seen_at is in MILLISECONDS, unlike almost every other Stripe timestamp.
// Anything below this is a seconds value passed in by mistake.
export const MS_FLOOR = 100000000000;

export const STALE_HOURS = 6.0;

/**
 * Classify one Terminal reader. Pure, so the units guard can be tested offline.
 * `lastSeenAtMs` and `nowMs` are both milliseconds.
 */
export function readerState(status, lastSeenAtMs, nowMs, actionStatus = null,
                            failureCode = null, staleHours = STALE_HOURS) {
  const missing = (v) => v === null || v === undefined;
  if (!missing(lastSeenAtMs) && lastSeenAtMs < MS_FLOOR) {
    return ['unknown',
      `last_seen_at is ${lastSeenAtMs}, which is a seconds timestamp; this reader ` +
      'cannot be judged until the units are right'];
  }
  const ageH = missing(lastSeenAtMs) ? null : (nowMs - lastSeenAtMs) / 3600000;
  if (status === 'offline') {
    const seen = ageH === null ? 'never seen' : `last seen ${ageH.toFixed(1)} hour(s) ago`;
    return ['offline', `status offline, ${seen}; it will not take a payment`];
  }
  if (ageH === null) {
    return ['unknown', 'no last_seen_at, so liveness cannot be confirmed'];
  }
  if (ageH >= staleHours) {
    return ['stale',
      `status ${status} but no check-in for ${ageH.toFixed(1)} hour(s); status lags ` +
      'reality, so treat this as unusable'];
  }
  if (actionStatus === 'failed') {
    return ['action_failed',
      `reachable but wedged on a failed action: ${failureCode || 'no failure_code on the action'}`];
  }
  if (status === 'online') return ['online', `checked in ${ageH.toFixed(1)} hour(s) ago`];
  return ['unknown', `unrecognised status ${JSON.stringify(status)}`];
}

/** Readers not on the version most of their own device_type is running. Pure. */
export function firmwareOutliers(readers) {
  const byType = new Map();
  for (const r of readers) {
    if (!byType.has(r.device_type)) byType.set(r.device_type, []);
    byType.get(r.device_type).push(r);
  }
  const out = [];
  for (const deviceType of [...byType.keys()].sort((a, b) => String(a).localeCompare(String(b)))) {
    const group = byType.get(deviceType);
    const counts = new Map();
    for (const r of group) {
      if (r.device_sw_version) {
        counts.set(r.device_sw_version, (counts.get(r.device_sw_version) ?? 0) + 1);
      }
    }
    if (group.length < 2 || counts.size === 0) continue;
    let majority = null;
    let best = -1;
    for (const [v, n] of counts) if (n > best) { majority = v; best = n; }
    for (const r of group) {
      if (r.device_sw_version && r.device_sw_version !== majority) {
        out.push([r.id, deviceType, r.device_sw_version, majority]);
      }
    }
  }
  return out;
}

async function get(key, path, params) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  if (res.status === 401) {
    throw new Error('401 from Stripe: the key is wrong, or is for the other mode');
  }
  if (res.status === 403) {
    throw new Error('403 from Stripe: the restricted key has no read access to Terminal');
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

async function pageAll(key, path, params, cap = 2000) {
  const out = [];
  const p = { ...params };
  for (;;) {
    const page = await get(key, path, p);
    const data = page.data ?? [];
    out.push(...data);
    if (data.length === 0 || !page.has_more || out.length >= cap) return out;
    p.starting_after = data[data.length - 1].id;
  }
}

async function main() {
  const key = process.env.STRIPE_API_KEY;
  if (!key) {
    console.error('set STRIPE_API_KEY (use a restricted, read-only key)');
    process.exitCode = 2;
    return;
  }
  const staleHours = Number(process.env.STALE_HOURS ?? STALE_HOURS);
  const params = { limit: 100 };
  if (process.env.LOCATION) params.location = process.env.LOCATION;
  const readers = await pageAll(key, '/terminal/readers', params);

  const nowMs = Date.now();
  let bad = 0;
  let freshest = null;
  for (const r of readers) {
    const action = r.action ?? {};
    const [state, detail] = readerState(r.status, r.last_seen_at, nowMs,
      action.status, action.failure_code, staleHours);
    if (r.last_seen_at && r.last_seen_at >= MS_FLOOR
        && (freshest === null || r.last_seen_at > freshest)) {
      freshest = r.last_seen_at;
    }
    if (state !== 'online') {
      bad += 1;
      console.warn(`  ${state.padEnd(13)} ${r.id}  ${r.label ?? r.device_type}  ${detail}`);
    }
  }

  const drift = firmwareOutliers(readers);
  for (const [rid, deviceType, version, majority] of drift) {
    console.warn(`  firmware      ${rid}  ${deviceType} on ${version}, the rest of ` +
                 `the fleet is on ${majority}`);
  }

  if (!bad && drift.length === 0) {
    const age = freshest === null ? 0 : (nowMs - freshest) / 3600000;
    console.log(`clear       ${readers.length} reader(s) online, newest check-in ` +
                `${age.toFixed(1)}h, firmware consistent`);
    return;
  }

  console.warn(`offline     ${bad} of ${readers.length} reader(s) not usable, ` +
               `${drift.length} on odd firmware`);
  console.warn('  power-cycle the reader and confirm the location network reaches ' +
               'Stripe, then re-check:');
  console.warn(`  GET ${API}/terminal/readers/<tmr_id>   ` +
               '(want status online AND a fresh last_seen_at)');
  console.warn('  leave drifting readers powered and connected through their ' +
               'configured update window');
  console.warn('  retire dead hardware so it stops filling this report:');
  console.warn(`  DELETE ${API}/terminal/readers/<tmr_id>`);
  process.exitCode = 1;
}

// Only run when invoked directly, so importing this module from the test file
// does not fire main() and fail the suite on the missing key.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from stripe_terminal_readers import firmware_outliers, reader_state

NOW_MS = 1_756_000_000_000
HOUR = 3_600_000


def test_a_seconds_timestamp_is_refused_not_believed():
    # 1756000000 is a perfectly good seconds timestamp and a nonsense millisecond
    # one. Reporting it as 50 years stale is how this check gets ignored.
    state, detail = reader_state("online", NOW_MS // 1000, NOW_MS)
    assert state == "unknown"
    assert "seconds timestamp" in detail


def test_recent_check_in_on_an_online_reader_is_fine():
    state, _ = reader_state("online", NOW_MS - HOUR, NOW_MS)
    assert state == "online"


def test_stale_beats_a_cheerful_status():
    # status lags reality, so six hours without a check-in is unusable even while
    # the reader still claims to be online.
    assert reader_state("online", NOW_MS - 5 * HOUR, NOW_MS)[0] == "online"
    state, detail = reader_state("online", NOW_MS - 6 * HOUR, NOW_MS)
    assert state == "stale"
    assert "status lags reality" in detail


def test_offline_and_wedged_are_different_problems():
    assert reader_state("offline", NOW_MS - HOUR, NOW_MS)[0] == "offline"
    state, detail = reader_state("online", NOW_MS - HOUR, NOW_MS,
                                 "failed", "reader_timeout")
    assert state == "action_failed"
    assert "reader_timeout" in detail


def test_firmware_outliers_need_a_majority_to_be_outliers_from():
    fleet = [
        {"id": "tmr_1", "device_type": "bbpos_wisepos_e", "device_sw_version": "2.24"},
        {"id": "tmr_2", "device_type": "bbpos_wisepos_e", "device_sw_version": "2.24"},
        {"id": "tmr_3", "device_type": "bbpos_wisepos_e", "device_sw_version": "2.11"},
        {"id": "tmr_4", "device_type": "stripe_s700", "device_sw_version": "1.4"},
    ]
    out = firmware_outliers(fleet)
    assert [row[0] for row in out] == ["tmr_3"]
    assert out[0][3] == "2.24"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { firmwareOutliers, readerState } from './stripe-terminal-readers.mjs';

const NOW_MS = 1756000000000;
const HOUR = 3600000;

test('a seconds timestamp is refused, not believed', () => {
  const [state, detail] = readerState('online', Math.floor(NOW_MS / 1000), NOW_MS);
  assert.equal(state, 'unknown');
  assert.match(detail, /seconds timestamp/);
});

test('recent check-in on an online reader is fine', () => {
  assert.equal(readerState('online', NOW_MS - HOUR, NOW_MS)[0], 'online');
});

test('stale beats a cheerful status', () => {
  assert.equal(readerState('online', NOW_MS - 5 * HOUR, NOW_MS)[0], 'online');
  const [state, detail] = readerState('online', NOW_MS - 6 * HOUR, NOW_MS);
  assert.equal(state, 'stale');
  assert.match(detail, /status lags reality/);
});

test('offline and wedged are different problems', () => {
  assert.equal(readerState('offline', NOW_MS - HOUR, NOW_MS)[0], 'offline');
  const [state, detail] = readerState('online', NOW_MS - HOUR, NOW_MS,
    'failed', 'reader_timeout');
  assert.equal(state, 'action_failed');
  assert.match(detail, /reader_timeout/);
});

test('firmware outliers need a majority to be outliers from', () => {
  const fleet = [
    { id: 'tmr_1', device_type: 'bbpos_wisepos_e', device_sw_version: '2.24' },
    { id: 'tmr_2', device_type: 'bbpos_wisepos_e', device_sw_version: '2.24' },
    { id: 'tmr_3', device_type: 'bbpos_wisepos_e', device_sw_version: '2.11' },
    { id: 'tmr_4', device_type: 'stripe_s700', device_sw_version: '1.4' },
  ];
  const out = firmwareOutliers(fleet);
  assert.deepEqual(out.map((row) => row[0]), ['tmr_3']);
  assert.equal(out[0][3], '2.24');
});