rueda 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb546a4621da61ec3d034e31f02bf92707e0f255876d55b19998fede94d857da
+  data.tar.gz: 82371c1594ba2a17140c370f0804b80f3cec82c05935db3274fd21c2edb0cd07
+SHA512:
+  metadata.gz: e3c2d941a4c3fce7ebee89868cb0ebb1701a88f0a3af7c3f5723dc21afe11f09e39829965aec7aeb3a8d69dab6da9b188ae91571759a39743b7d73a5582f8922
+  data.tar.gz: 896de09eb7cd26ad7a426b6f4935bb676c156f0ebf57d62d0671c8d929738e055961707646ddd5771a9fa9e7b18315f6aa61ecb632cf0365aae3accd574cd4d8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel Rzezak
+
+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.

data/README.md

@@ -0,0 +1,105 @@
+# rueda
+
+A read-only command-line client for the Garmin Connect Personal API. It fetches your activities and prints them as a table, JSON, NDJSON, or CSV.
+
+```
+$ rueda activities --since 2025-09-30
+DATE        TYPE         NAME        KM    MOVING   KM/H  ELEV  HR   CAD
+2025-10-05  road_biking  Activity 1  26.0  1:05:05  23.9  155   146  86
+2025-10-03  road_biking  Activity 2  29.3  1:11:32  24.6  160   120  74
+2025-10-02  road_biking  Activity 3  35.7  1:32:40  23.1  195   136  73
+2025-09-30  road_biking  Activity 4  35.7  1:29:24  23.9  202   133  76
+```
+
+`SPEC.md` is the full specification.
+
+## Install
+
+rueda needs Ruby 3.4 or later.
+
+```bash
+gem install rueda
+```
+
+To run it from a clone instead, run `bundle install` and use `exe/rueda`.
+
+## Set up your API key
+
+1. In Garmin Connect, go to **Settings → Personal API** and create a key. Choose how long it lasts (30, 90, 180, or 365 days). Garmin shows it only once, so copy it right away.
+2. With the key copied to the clipboard, save it where rueda looks for it:
+
+   ```bash
+   mkdir -p ~/.config/rueda && (umask 077 && pbpaste > ~/.config/rueda/api_key)
+   ```
+
+   The file holds only the key, with `0600` permissions. If `~/.config` is in a dotfiles repo or synced, exclude `rueda/`. You can also set `GARMIN_API_KEY` instead, which takes precedence over the file. rueda never accepts the key as a command-line argument, so it stays out of your shell history and the process list.
+
+3. Check it works:
+
+   ```
+   $ rueda auth check
+   Token OK, valid until 2026-11-11 11:01 -03.
+   ```
+
+When the key expires, create a new one and replace the old one in the same place.
+
+## Usage
+
+```bash
+rueda activities                                  # the last 30 days
+rueda activities --since 2025-09-01 --until 2025-09-30
+rueda activities --type road_biking --limit 5     # --type takes Garmin's type key and can repeat
+rueda activity 900000001                          # one activity
+rueda activity 900000001 --fit                    # save the original file as activity-900000001.zip
+```
+
+In a terminal, rueda prints a table. When its output goes to a pipe or a file, it prints JSON, so scripts and agents get stable data by default:
+
+```
+$ rueda activities --limit 1 | jq
+{
+  "schema_version": 1,
+  "query": {
+    "since": "2025-09-06",
+    "until": "2025-10-06",
+    "type": []
+  },
+  "count": 1,
+  "activities": [
+    {
+      "garmin_id": 900000001,
+      "name": "Activity 1",
+      "type": "road_biking",
+      "started_at": "2025-10-05T17:55:26Z",
+      "local_date": "2025-10-05",
+      "distance_km": 26.0,
+      "moving_time_s": 3905,
+      "elapsed_time_s": 3916,
+      "avg_speed_kmh": 23.9,
+      "max_speed_kmh": 35.0,
+      "elevation_gain_m": 155,
+      "elevation_loss_m": 147,
+      "avg_hr_bpm": 146,
+      "max_hr_bpm": 170,
+      "avg_power_w": null,
+      "calories": 728,
+      "avg_cadence_rpm": 86,
+      "max_cadence_rpm": 125
+    }
+  ]
+}
+```
+
+Units are in the field names, and missing data is `null`, never `0`.
+
+Other options:
+
+- `--format table|json|ndjson|csv` picks the format. NDJSON prints one activity per line; CSV prints every field, in schema order.
+- `--raw` prints Garmin's JSON as it arrives, for fields rueda doesn't map yet. It works only with `json` and `ndjson`, and its shape is not guaranteed.
+- `--quiet` hides warnings. `--timeout SECONDS` changes the network timeout (30 by default).
+
+Data goes to stdout, and warnings and errors go to stderr. Each kind of error has its own exit code, such as 3 for no API key and 4 when Garmin rejects the key; `SPEC.md` lists them all.
+
+## License
+
+MIT. See `LICENSE`.

data/SPEC.md

@@ -0,0 +1,228 @@
+# rueda — a Garmin training data client
+
+> The name comes from the Spanish cycling term _ir a rueda_ ("riding on a wheel", i.e. drafting): it sits behind Garmin and lets Garmin do the work.
+
+## What it is
+
+A read-only command-line client for the **Garmin Connect Personal API**. It fetches data on demand, normalizes it into its own stable schema, and prints it in the requested format.
+
+It serves two kinds of consumers equally:
+
+- **Humans** at a terminal: readable tables, and pipes into other tools.
+- **Agents** (Claude Code and similar) via the shell: stable JSON, predictable errors and exit codes.
+
+## What it is not
+
+- It does not sync or store data. Garmin is the source of truth; what happens to the output is up to the caller.
+- It does not write to Garmin. The Personal API is read-only.
+- It has no GUI and no server.
+- It is not multi-user: one account, the one that owns the key.
+
+The only thing persisted locally is the cached access token.
+
+## v1 scope
+
+- Authentication with a personal API key, plus token caching.
+- Listing activities with filters.
+- Activity detail.
+- Downloading an activity's original file (a ZIP containing the .FIT).
+- Output as `table`, `json`, `ndjson`, and `csv`.
+
+## Architecture
+
+```
+lib/rueda/
+  auth/          # key → token, caching, renewal
+  garmin/        # HTTP client and endpoints (the only code that knows Garmin)
+  model/         # Activity and other normalized types
+  normalize/     # Garmin JSON → model
+  output/        # formatters: table, json, ndjson, csv
+  cli/           # commands; a thin layer over the above
+```
+
+## Stack
+
+- Ruby ≥ 3.4, distributed as a gem.
+- CLI: `OptionParser` from the stdlib. Four commands don't need a framework.
+- Tests: Minitest with WebMock. Linter: Standard (no rule configuration).
+
+## Authentication
+
+Flow per the official Personal API FAQ:
+
+1. The user creates a key in Garmin Connect → Settings → Personal API. It is shown only once and expires after the chosen period (30, 90, 180, or 365 days).
+2. The client exchanges the key for a token: `POST https://personal.connectapi.garmin.com/personalapitoken-service/personal-api/personal-api-key/token` with the header `Authorization: ApiKey <key>`.
+3. The response body is the bare JWT, not JSON (see `test/fixtures/token.txt`). The token is valid for 24 h (or until the key expires). There are no refresh tokens: when it expires, request a new one with the key.
+4. Data requests use `Authorization: Bearer <token>`.
+
+### Key sources (in order of precedence)
+
+1. `--api-key-file <path>`
+2. The `GARMIN_API_KEY` environment variable
+3. The default file `~/.config/rueda/api_key`
+
+The key is **not** accepted as a direct argument: it would end up in shell history and the process list.
+
+### Token cache
+
+- File `~/.config/rueda/token.json`, created with `0600` permissions.
+- Reused if it was issued for the current key (store a hash of the key, never the key itself) and has more than one hour left before the JWT `exp`.
+- On a `401`, discard the cache, request a new token, and retry **once**.
+- Warn on stderr if the key file or token file has permissions looser than `0600`.
+
+## Garmin endpoints
+
+| Purpose         | Request                                                                                             | Status                                                   |
+| --------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| Token           | `POST /personalapitoken-service/personal-api/personal-api-key/token`                                | Confirmed (official FAQ and fixture; not in the OpenAPI) |
+| List activities | `GET /activitylist-service/activities/search/activities?start&limit&startDate&endDate`              | Confirmed (OpenAPI and fixture)                          |
+| Detail          | `GET /activity-service/activity/{id}`                                                               | Confirmed (OpenAPI; `404` if the activity doesn't exist) |
+| Original file   | `GET /download-service/files/activity/{id}` → ZIP                                                   | Confirmed (OpenAPI)                                      |
+
+Host: `https://personal.connectapi.garmin.com`, from the OpenAPI `servers` field (which also lists `https://personal.connectapi.garmin.cn`).
+
+List response fields match the OpenAPI: `activityId`, `activityName`, `startTimeLocal` and `startTimeGMT` (`yyyy-MM-dd HH:mm:ss`, no offset), `activityType.typeKey`, `distance` in meters, `movingDuration` and `elapsedDuration` in seconds (floats), `elevationGain` and `elevationLoss` in meters, `averageHR`, `maxHR`, `averageSpeed` and `maxSpeed` in m/s, `avgPower` in watts, `calories` in kcal. Fields can be absent or `null` (for example `averageHR`).
+
+Rate limits: neither the FAQ nor the OpenAPI documents `429` or a limit. Handle `429` anyway, without assuming a number.
+
+Pagination: `start` is a zero-based offset; `limit` defaults to 99, and rueda requests pages of 99. Advance by the number of records received (not by `limit`, since Garmin may return fewer) and stop on an empty page.
+
+Detail response: the type is in `activityTypeDTO.typeKey` and the measurements are in `summaryDTO`, with the same names as the list except `averagePower` (list: `avgPower`) and `averageBikeCadence`/`maxBikeCadence` (list: `averageBikingCadenceInRevPerMinute`/`maxBikingCadenceInRevPerMinute`). Start times look like `2025-10-05T14:55:26.0` instead of `2025-10-05 14:55:26`. Confirmed by `test/fixtures/activity_detail.json`.
+
+Type filter: Garmin's `activityType` parameter takes a single parent type key (such as `cycling`), not a `typeKey` like `road_biking`. rueda filters by `--type` itself after fetching and does not send `activityType`.
+
+## Commands
+
+```
+rueda auth check
+rueda activities [--since DATE] [--until DATE] [--type TYPE] [--limit N]
+rueda activity <id>
+rueda activity <id> --fit [-o FILE]
+rueda version
+```
+
+Global options: `--format table|json|ndjson|csv`, `--raw`, `--api-key-file PATH`, `--timeout SECONDS`, `--quiet`.
+
+### `rueda auth check`
+
+Checks that a key is available and that Garmin accepts it: it always requests a new token, skipping the cache (so a revoked key fails here), then caches it. Prints when that token expires. Never shows credentials.
+
+### `rueda activities`
+
+- `--since` / `--until`: `YYYY-MM-DD` dates, in local time. Defaults to the last 30 days: `--until` defaults to today and `--since` to 30 days before `--until`. Both ends are inclusive.
+- `--type`: filter by Garmin's `typeKey` (see [Activity types](#activity-types)). Repeatable.
+- `--limit`: cap on results. No cap by default within the date range.
+- Order: most recent first.
+
+### `rueda activity <id>`
+
+Detail for one activity, using the same schema as the list plus any optional fields the detail provides (none yet). `<id>` must be a positive integer. JSON output is `{"schema_version": 1, "activity": {...}}`; `ndjson`, `csv` and `table` print one activity as they would in a list. `--raw` prints Garmin's detail object.
+
+With `--fit`, downloads the original ZIP. By default it saves `activity-<id>.zip` in the current directory and reports the path on stderr. It does not overwrite an existing file unless `--force` is given (exit 2 otherwise). With `-o -` it writes to stdout, and refuses if stdout is a terminal. A response that isn't a ZIP exits 8 and writes nothing.
+
+## Output
+
+### Formats
+
+| Format   | Use                                                                        |
+| -------- | -------------------------------------------------------------------------- |
+| `table`  | Default when stdout is a terminal. For reading, not parsing.               |
+| `json`   | Default when stdout is not a terminal. An object with metadata and a list. |
+| `ndjson` | One activity per line. For streams and `jq`.                               |
+| `csv`    | Header in the first row; columns in schema order.                          |
+
+`--raw` returns Garmin's JSON unnormalized (only with `json`/`ndjson`): a plain array of Garmin's activity objects with `json`, one per line with `ndjson`, and no envelope. `--type` and `--limit` still apply. With `--raw` and no `--format`, the output is `json` even in a terminal. Useful for debugging and for reading fields not yet mapped. Its shape is not guaranteed.
+
+The `table` columns for activities are `DATE` (`local_date`), `TYPE`, `NAME`, `KM`, `MOVING` (moving time as `h:mm:ss`), `KM/H` (average), `ELEV` (gain), `HR` (average) and `CAD` (average biking cadence). Missing values show as `—`, and control characters (such as terminal escape codes) are removed. `ndjson` prints nothing for an empty result; `table` and `csv` print just the header.
+
+### JSON envelope
+
+```json
+{
+  "schema_version": 1,
+  "query": { "since": "2026-10-01", "until": "2026-11-10", "type": ["road_biking"] },
+  "count": 1,
+  "activities": [{ "...": "see schema" }]
+}
+```
+
+### Activity schema (v1)
+
+| Field              | Type            | Notes                                                                                          |
+| ------------------ | --------------- | ---------------------------------------------------------------------------------------------- |
+| `garmin_id`        | integer         | Stable Garmin identifier.                                                                      |
+| `name`             | string \| null  | Activity name.                                                                                 |
+| `type`             | string          | Garmin's `typeKey`, unchanged.                                                                 |
+| `started_at`       | string          | ISO 8601, UTC.                                                                                 |
+| `local_date`       | string          | `YYYY-MM-DD` in the activity's local time.                                                     |
+| `distance_km`      | number \| null  | One decimal place.                                                                             |
+| `moving_time_s`    | integer \| null | From `movingDuration`, rounded.                                                                |
+| `elapsed_time_s`   | integer \| null | From `elapsedDuration` (not `duration`), rounded.                                              |
+| `avg_speed_kmh`    | number \| null  | Computed from distance and moving time, one decimal place. Falls back to elapsed time if moving time is missing. |
+| `max_speed_kmh`    | number \| null  | One decimal place.                                                                             |
+| `elevation_gain_m` | integer \| null |                                                                                                |
+| `elevation_loss_m` | integer \| null |                                                                                                |
+| `avg_hr_bpm`       | integer \| null |                                                                                                |
+| `max_hr_bpm`       | integer \| null |                                                                                                |
+| `avg_power_w`      | integer \| null |                                                                                                |
+| `calories`         | integer \| null |                                                                                                |
+| `avg_cadence_rpm`  | integer \| null | Biking cadence, revolutions per minute. `null` when Garmin has none.                           |
+| `max_cadence_rpm`  | integer \| null | Biking cadence, revolutions per minute. `null` when Garmin has none.                           |
+
+Schema rules:
+
+- Units go in the field name.
+- Missing data is `null`, never `0`.
+- New fields are added without bumping `schema_version`. Renaming, removing, or changing a field's type does bump it.
+- Until v1 is first released, the schema can still change without a bump.
+
+### Activity types
+
+`type` is Garmin's `typeKey` as-is, with no mapping (for example `road_biking`). Seen in fixtures: `road_biking`. The OpenAPI's examples use `road_cycling`, but the fixtures show `road_biking`; the fixtures win.
+
+## Errors and exit codes
+
+Data goes to stdout; logs, warnings, and errors go to stderr. With `--format json`, errors are also emitted as JSON on stderr:
+
+```json
+{ "error": { "code": "auth_failed", "message": "The key has expired or been revoked." } }
+```
+
+| Exit code | `error.code`   | Case                                                         |
+| --------- | -------------- | ------------------------------------------------------------ |
+| 0         | —              | OK (including an empty result).                              |
+| 1         | `unexpected`   | Unexpected error (a bug in rueda).                           |
+| 2         | `usage`        | Invalid arguments.                                           |
+| 3         | `no_api_key`   | No key found.                                                |
+| 4         | `auth_failed`  | Garmin rejected the key or token (`401` or `403`).           |
+| 5         | `not_found`    | Garmin returned `404` (for example, no such activity).       |
+| 6         | `rate_limited` | Garmin returned `429`.                                       |
+| 7         | `network`      | Timeout or connection failure.                               |
+| 8         | `bad_response` | Response had an unexpected shape or was malformed.           |
+| 9         | `garmin_error` | Garmin returned any other error status (for example `5xx`).  |
+
+## Tests
+
+- Unit tests for `normalize/` against real (anonymized) JSON fixtures.
+- CLI integration tests with WebMock: output formats, exit codes, and key precedence.
+- A separate command or script, outside CI, to record fixtures with a real key.
+
+## Roadmap
+
+Out of scope for v1, in order:
+
+1. **Health data:** sleep, HRV, Body Battery, resting heart rate. Same pattern: endpoint → normalizer → schema.
+2. **MCP server:** an adapter over the same core, for clients without a shell.
+
+## Open decisions
+
+- **Aggregates (`rueda stats`).** Out for now: the client fetches data and consumers do the math. Reconsider if agents keep repeating the same calculations.
+- **Distribution:** an installable gem, or also a standalone binary.
+- **Confirm `rueda` is available** on RubyGems and GitHub.
+
+## References
+
+- [Garmin Connect Personal API](https://developer.garmin.com/gc-developer-program/personal/personal-api/)
+- [Personal API FAQ](https://developer.garmin.com/gc-developer-program/personal/personal-faq/)
+- [Personal API Swagger](https://developer.garmin.com/gc-developer-program/personal/swagger-docs/)
+- [Official Python client](https://github.com/garmin/connect-personal-api-python)

data/exe/rueda

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/rueda"
+
+Rueda::CLI.new.run(ARGV)

data/lib/rueda/activities.rb

@@ -0,0 +1,33 @@
+require_relative "normalize/activity"
+
+module Rueda
+  class Activities
+    def initialize(client:, authenticator:)
+      @client = client
+      @authenticator = authenticator
+    end
+
+    def list(from:, to:, types:, limit:, raw: false)
+      @authenticator.with_token do |token|
+        matching = @client.each_activity(token, from:, to:).lazy.select { of_type?(it, types) }
+        matching = matching.map { Normalize::Activity.call(it) } unless raw
+        limit ? matching.first(limit) : matching.to_a
+      end
+    end
+
+    def find(id, raw: false)
+      detail = @authenticator.with_token { @client.activity(it, id) }
+      raw ? detail : Normalize::ActivityDetail.call(detail)
+    end
+
+    def fit_file(id)
+      @authenticator.with_token { @client.activity_file(it, id) }
+    end
+
+    private
+
+    def of_type?(raw, types)
+      types.empty? || types.include?(Normalize::Activity.type(raw))
+    end
+  end
+end

data/lib/rueda/auth/api_key.rb

@@ -0,0 +1,44 @@
+require_relative "../errors"
+require_relative "secret_file"
+
+module Rueda
+  module Auth
+    class ApiKey
+      ENV_VAR = "GARMIN_API_KEY".freeze
+
+      def initialize(file:, env:, default_path:, warn:)
+        @file = file
+        @env = env
+        @default_path = default_path
+        @warn = warn
+      end
+
+      def value
+        from_env || from_file || raise(NoApiKey, missing_message)
+      end
+
+      private
+
+      def from_env
+        presence(@env[ENV_VAR]) unless @file
+      end
+
+      def from_file
+        presence(SecretFile.new(@file || @default_path, warn: @warn).read)
+      end
+
+      def presence(text)
+        text = text.to_s.strip
+        text unless text.empty?
+      end
+
+      def missing_message
+        if @file
+          "No key in the file passed with --api-key-file."
+        else
+          "No API key: set #{ENV_VAR} or create #{@default_path}"
+        end
+      end
+    end
+  end
+end

data/lib/rueda/auth/authenticator.rb

@@ -0,0 +1,30 @@
+require_relative "../errors"
+
+module Rueda
+  module Auth
+    class Authenticator
+      def initialize(api_key:, client:, cache:)
+        @api_key = api_key
+        @client = client
+        @cache = cache
+      end
+
+      def token
+        @cache.fetch(@api_key) || fresh_token
+      end
+
+      def fresh_token
+        @client.token(@api_key).tap { @cache.store(@api_key, it) }
+      end
+
+      def with_token
+        current = token
+        begin
+          yield current
+        rescue AuthFailed
+          yield fresh_token
+        end
+      end
+    end
+  end
+end

data/lib/rueda/auth/secret_file.rb

@@ -0,0 +1,43 @@
+require "fileutils"
+
+module Rueda
+  module Auth
+    class SecretFile
+      PRIVATE = 0o600
+
+      def initialize(path, warn:)
+        @path = path
+        @warn = warn
+      end
+
+      def read
+        return unless File.file?(@path)
+
+        warn_if_loose
+        File.read(@path)
+      end
+
+      def write(content)
+        FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+        File.open(@path, "w", PRIVATE) do |file|
+          file.chmod(PRIVATE)
+          file.write(content)
+        end
+      end
+
+      private
+
+      def warn_if_loose
+        @warn.call("#{@path} has permissions #{format("%04o", mode)}; it should be 0600") if loose?
+      end
+
+      def loose?
+        mode.anybits?(0o077)
+      end
+
+      def mode
+        File.stat(@path).mode & 0o777
+      end
+    end
+  end
+end

data/lib/rueda/auth/token.rb

@@ -0,0 +1,35 @@
+require "json"
+require_relative "../errors"
+
+module Rueda
+  module Auth
+    class Token
+      FORMAT = /\A[\w-]+\.[\w-]+\.[\w-]*\z/
+
+      attr_reader :expires_at
+
+      def initialize(jwt)
+        raise BadResponse, "The token is not a JWT." unless jwt.match?(FORMAT)
+
+        @jwt = jwt
+        @expires_at = Time.at(Integer(claims.fetch("exp"))).utc
+      rescue JSON::ParserError, KeyError, TypeError, ArgumentError
+        raise BadResponse, "The token has no readable expiry."
+      end
+
+      def expires_within?(seconds)
+        expires_at - Time.now < seconds
+      end
+
+      def to_s = @jwt
+
+      def inspect = "#<#{self.class} expires_at=#{expires_at}>"
+
+      private
+
+      def claims
+        JSON.parse(@jwt.split(".")[1].tr("-_", "+/").unpack1("m"))
+      end
+    end
+  end
+end

data/lib/rueda/auth/token_cache.rb

@@ -0,0 +1,41 @@
+require "digest"
+require "json"
+require_relative "../errors"
+require_relative "secret_file"
+require_relative "token"
+
+module Rueda
+  module Auth
+    class TokenCache
+      MIN_REMAINING = 3600
+
+      def initialize(path:, warn:)
+        @file = SecretFile.new(path, warn:)
+        @warn = warn
+      end
+
+      def fetch(key)
+        content = @file.read
+        return unless content
+
+        data = JSON.parse(content)
+        return unless data.is_a?(Hash) && data["key_sha256"] == digest(key)
+
+        token = Token.new(data["token"].to_s)
+        token unless token.expires_within?(MIN_REMAINING)
+      rescue JSON::ParserError, SystemCallError, BadResponse
+        nil
+      end
+
+      def store(key, token)
+        @file.write(JSON.generate(key_sha256: digest(key), token: token.to_s))
+      rescue SystemCallError => e
+        @warn.call("could not cache the token (#{e.class})")
+      end
+
+      private
+
+      def digest(key) = Digest::SHA256.hexdigest(key)
+    end
+  end
+end