njtransit 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5584ce2fe6e436ae468c2e608cdc02a0088ece0e9f60d3ffc38c17ab22d9e48
-  data.tar.gz: de15a15f37ee4a1ef04af7e584fd0598543f1816d905cbe145574aa652aaaac8
+  metadata.gz: 034142d76cecb98cbd1b456d75052081a766217e684d249e2f4a2541db35ff07
+  data.tar.gz: b9a8c8209fbb6602bf6b10daa4594a8c59ba1a843c48aa8ea63ee79104fdf286
 SHA512:
-  metadata.gz: 1ecaa2f41afc8b8f5428605f265e6809476be19de2c232839654b3f361d1c9a8c1439e19ac8a4bd506c95dac580a659016e519131c35cfcb8971e60c0b220514
-  data.tar.gz: d5c4df192020d8ff5d124a9c18cf991def5e485d01445079c31013f3c161cfc709a0f8608e778536090f4e1c3c87d838178705d0826e6ee5024dc2786685db8c
+  metadata.gz: 3114f42fa2517def6d6eba2b1f58059a9d21825d6993a730804899538f2627384e118b391e46988e5e0dee7120b2eede76adabb69f495c2c6d172e47427e48d2
+  data.tar.gz: 85929dbf8bfb5d3f5bf879973d1aca00e9e8f82e6953be6d6853f4bfaba83db2f2ed43b8de3198c70e078d791942b68706a7c0367450d1a2c3862c1b2afe197a

data/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-11-14
+
+### Added
+
+- Pluggable auth token store (`config.token_store` / `Client.new(token_store:)`): any object with `read`, `write` and `delete`, including `Rails.cache`. Lets long-running processes reuse a token across restarts instead of hitting NJ Transit's daily token cap
+- `NJTransit::TokenStores::Memory` (the default, shared per process) and `NJTransit::TokenStores::File` (JSON file, mode 0600, atomic writes under an exclusive `flock`, safe across processes)
+- Assigning a `token_store` without `read`/`write`/`delete` raises `ArgumentError`
+- `Client#token_key` and `Client.default_token_store`
+
+### Changed
+
+- Tokens are keyed by API host and username (`njtransit:token:<base_url>:<username>`), not host alone
+- Raw GTFS-RT requests now detect an expired token (a JSON `Invalid token.` body, or a 401/403), re-authenticate and retry once, as JSON requests already did. A JSON error body on a feed now raises `APIError` instead of being returned as feed bytes
+- Clearing an expired token deletes the stored copy only if it is still the stale one, so clients sharing a store don't discard each other's fresh tokens
+- A failing token store always warns on stderr (regardless of `log_level`) and is bypassed instead of raising
+
+### Deprecated
+
+- `Client.token_cache`: use `Client.default_token_store` or configure `token_store`
+
+## [1.1.5] - 2026-11-14
+
+### Added
+
+- GitHub Pages landing page (`docs/index.md`); https://jayravaliya.com/njtransit/ no longer 404s
+- `CLAUDE.md` Documentation Sync row for the landing page
+
 ## [1.1.4] - 2026-04-26
 
 ### Changed

data/CLAUDE.md

@@ -12,6 +12,7 @@ Any change that affects public behavior, configuration, dependencies, or the rel
 |---|---|
 | New or changed public API (method signature, return shape, error class raised) | `README.md` (capability section + relevant examples), `CHANGELOG.md` |
 | New resource class or API host | `CLAUDE.md` Architecture section, `README.md` "Two Clients" table, `CHANGELOG.md` |
+| Quick Start, install or headline capabilities | `README.md`, `docs/index.md` (the GitHub Pages landing page at jayravaliya.com/njtransit) |
 | New environment variable | `README.md` "Environment Variables" table, `CHANGELOG.md` if user-visible |
 | GTFS schema or data-layer changes | `CLAUDE.md` "GTFS Static Layer" section, `README.md` "GTFS Static Data" section if it surfaces in usage |
 | New rake task | `README.md` (where rake tasks are listed), `CHANGELOG.md` |
@@ -55,6 +56,7 @@ SQLite-backed offline schedule data. Import from GTFS zip, then query via `NJTra
 - **`enrich` flag**: Bus API methods default to `enrich: true`, which joins GTFS static data (lat/lon, route names). Use `enrich: false` if GTFS isn't imported or you don't need it.
 - **`mode` parameter**: Bus methods default to `mode: "BUS"`. Pass `"HBLR"`, `"NLR"`, `"RL"`, or `"ALL"` for light rail.
 - **`stops_nearby` radius**: The radius parameter is in **feet**, not miles.
+- **Token store**: Auth tokens go through a pluggable `token_store` (`lib/njtransit/token_stores.rb`): any object with `read`/`write`/`delete`, such as `TokenStores::File` or `Rails.cache`. The default is one shared `TokenStores::Memory` per process. Expired tokens are deleted from the store and the request is retried once, on both the JSON and raw (GTFS-RT) paths.
 - **Raw responses**: GTFS-RT methods (`bus_gtfs`, `rail_gtfs`) return binary protobuf data via `post_form_raw`.
 
 ## Testing

data/README.md

@@ -61,6 +61,24 @@ client.bus.stops_nearby(lat: 40.878, lon: -74.221, radius: 2000, enrich: false)
 client.bus.routes(mode: "HBLR")  # Hudson-Bergen Light Rail
 ```
 
+## Keeping Auth Tokens Across Restarts
+
+NJ Transit caps how many auth tokens you can create per day (as low as 5–10 on some endpoints). By default the gem caches tokens in memory, so every new process authenticates again. A service that restarts often (deploys, crash loops, containers) can hit the cap and be locked out for the rest of the day.
+
+Configure a `token_store` to reuse tokens across restarts:
+
+```ruby
+NJTransit.configure do |config|
+  # A JSON file (created with mode 0600)
+  config.token_store = NJTransit::TokenStores::File.new("tmp/njtransit_tokens.json")
+
+  # ...or, in Rails, any ActiveSupport cache (persists if its backend does)
+  config.token_store = Rails.cache
+end
+```
+
+A token store is any object with `read(key)`, `write(key, token)` and `delete(key)`; anything else raises `ArgumentError` when you assign it. Tokens are keyed by API host and username, so clients and processes sharing a store share one token per account. When the API reports an expired token (a JSON `Invalid token.` error, or a 401/403 on a GTFS-RT feed), the gem deletes it from the store (unless another client already replaced it), authenticates, stores the new one and retries the request once. If the store itself fails, the gem warns on stderr and falls back to authenticating, so a broken cache never breaks requests. `TokenStores::File` locks a `<path>.lock` file around each write, so several processes can share one file.
+
 ## Two Clients, One Gem
 
 NJ Transit splits its API across two hosts. The gem handles this with two clients:

data/docs/index.md

@@ -0,0 +1,52 @@
+---
+title: NJTransit Ruby gem
+---
+
+# NJTransit
+
+A Ruby gem for NJ Transit's real-time and schedule data: buses, trains and light rail.
+
+[![Gem Version](https://badge.fury.io/rb/njtransit.svg)](https://rubygems.org/gems/njtransit)
+
+- **Real-time departures** for buses, trains and light rail
+- **Train tracking:** GPS positions, speed and delay for every active train
+- **Full schedules** from GTFS static data, not just the next hour
+- **GTFS-RT feeds:** raw protobuf alerts, trip updates and vehicle positions
+
+## Get started
+
+Register at [developer.njtransit.com](https://developer.njtransit.com/registration) for API credentials, then:
+
+```ruby
+# Gemfile
+gem 'njtransit'
+```
+
+```ruby
+require 'njtransit'
+
+NJTransit.configure do |config|
+  config.username = ENV['NJTRANSIT_USERNAME']
+  config.password = ENV['NJTRANSIT_PASSWORD']
+end
+
+# Next trains from NY Penn Station
+NJTransit.rail_client.rail.train_schedule_19(station: "NY")
+```
+
+## Documentation
+
+- [README](https://github.com/jayrav13/njtransit#readme): every capability, both clients, GTFS static data, environment variables and the Claude Code skill
+- [CHANGELOG](https://github.com/jayrav13/njtransit/blob/main/CHANGELOG.md)
+- [RubyGems](https://rubygems.org/gems/njtransit)
+- [Source on GitHub](https://github.com/jayrav13/njtransit)
+
+## Design plans
+
+- [Gem design](plans/2025-01-24-njtransit-gem-design.md)
+- [Bus API design](plans/2026-01-24-bus-api-design.md)
+- [GTFS loader design](plans/2026-01-24-gtfs-loader-design.md)
+- [GTFS implementation](plans/2026-01-24-gtfs-implementation.md)
+- [Dev infrastructure and agent](superpowers/plans/2026-03-26-dev-infra-and-agent.md)
+
+MIT licensed.

data/lib/njtransit/client.rb

@@ -15,11 +15,12 @@ module NJTransit
   class Client
     DEFAULT_AUTH_PATH = "/api/BUSDV2/authenticateUser"
 
-    attr_reader :username, :password, :log_level, :base_url, :timeout, :auth_path
+    attr_reader :username, :password, :log_level, :base_url, :timeout, :auth_path, :token_store
 
     def initialize(username:, password:, log_level: "silent", base_url: Configuration::DEFAULT_BASE_URL,
-                   timeout: Configuration::DEFAULT_TIMEOUT, auth_path: DEFAULT_AUTH_PATH)
+                   timeout: Configuration::DEFAULT_TIMEOUT, auth_path: DEFAULT_AUTH_PATH, token_store: nil)
       @username = username
+      @token_store = token_store ? TokenStores.validate!(token_store) : self.class.default_token_store
       @password = password
       @log_level = log_level
       @base_url = base_url
@@ -77,7 +78,7 @@ module NJTransit
     end
 
     def authenticate!
-      cached = self.class.token_cache[base_url]
+      cached = read_stored_token
       if cached
         @token = cached
         return @token
@@ -95,7 +96,7 @@ module NJTransit
       end
 
       @token = result["UserToken"]
-      self.class.token_cache[base_url] = @token
+      write_stored_token(@token)
       @token
     end
 
@@ -104,17 +105,32 @@ module NJTransit
       @token
     end
 
+    # Forget this client's token. The stored copy is deleted only if it is still the
+    # token this client held, so a fresh token another client just stored survives.
     def clear_token!
+      stale = @token
       @token = nil
-      self.class.token_cache.delete(base_url)
+      store_call(:delete, token_key) if stale.nil? || read_stored_token == stale
     end
 
+    # Store key for this client's token: one per API host and username.
+    def token_key
+      "njtransit:token:#{base_url}:#{username}"
+    end
+
+    def self.default_token_store
+      @default_token_store ||= TokenStores::Memory.new
+    end
+
+    # Deprecated: use default_token_store, or configure a token_store.
     def self.token_cache
-      @token_cache ||= {}
+      warn "[njtransit] Client.token_cache is deprecated; use Client.default_token_store " \
+           "or configure token_store. Keys are now \"njtransit:token:<base_url>:<username>\"."
+      default_token_store.to_h
     end
 
     def self.clear_token_cache!
-      @token_cache = {}
+      default_token_store.clear
     end
 
     private
@@ -159,15 +175,22 @@ module NJTransit
       raise ConnectionError, e.message
     end
 
-    def request_form_raw(method, path, params = {})
+    def request_form_raw(method, path, params = {}, retry_auth: true)
       params[:token] = token
       response = raw_connection.public_send(method) do |req|
         req.url(path)
         req.body = params
       end
 
+      if retry_auth && raw_auth_failure?(response)
+        clear_token!
+        return request_form_raw(method, path, params, retry_auth: false)
+      end
+
       raise error_for_status(response.status).new(error_message(response), response: response) unless response.success?
 
+      # Feeds are protobuf, which never starts with "{": a JSON body is an API error.
+      check_api_error!(parse_body(response.body)) if json_body?(response.body)
       response.body
     rescue Faraday::TimeoutError => e
       raise TimeoutError, e.message
@@ -179,6 +202,34 @@ module NJTransit
       result.is_a?(Hash) && result["errorMessage"] == "Invalid token."
     end
 
+    # An expired token on a feed: a JSON "Invalid token." error, or a 401/403.
+    def raw_auth_failure?(response)
+      return true if [401, 403].include?(response.status)
+
+      response.success? && json_body?(response.body) && token_expired?(parse_body(response.body))
+    end
+
+    def json_body?(body)
+      body.is_a?(String) && body.start_with?("{")
+    end
+
+    def read_stored_token
+      store_call(:read, token_key)
+    end
+
+    def write_stored_token(token)
+      store_call(:write, token_key, token)
+    end
+
+    # A broken store must not break requests: fall back to authenticating, but always
+    # warn (whatever log_level is), since each fallback spends a capped token.
+    def store_call(method, *)
+      token_store.public_send(method, *)
+    rescue StandardError => e
+      warn "[njtransit] token store #{method} failed: #{e.class}: #{e.message}"
+      nil
+    end
+
     def check_api_error!(result)
       return unless result.is_a?(Hash) && result["errorMessage"]
 

data/lib/njtransit/configuration.rb

@@ -8,7 +8,7 @@ module NJTransit
     DEFAULT_TIMEOUT = 30
 
     attr_accessor :username, :password, :base_url, :timeout, :gtfs_database_path
-    attr_reader :log_level
+    attr_reader :log_level, :token_store
 
     def initialize
       @username = ENV.fetch("NJTRANSIT_USERNAME", nil)
@@ -29,13 +29,19 @@ module NJTransit
       @log_level = level
     end
 
+    # Any object with read, write and delete (e.g. NJTransit::TokenStores::File, Rails.cache); nil for in-memory.
+    def token_store=(store)
+      @token_store = store.nil? ? nil : TokenStores.validate!(store)
+    end
+
     def to_h
       {
         username: username,
         password: password,
         log_level: log_level,
         base_url: base_url,
-        timeout: timeout
+        timeout: timeout,
+        token_store: token_store
       }
     end
 

data/lib/njtransit/token_stores.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+
+module NJTransit
+  # Where clients keep NJ Transit auth tokens. NJ Transit caps token creation
+  # (as low as 5-10 a day on some endpoints), so a long-running process that
+  # restarts should reuse its token instead of authenticating on every boot.
+  #
+  # A token store is any object that responds to:
+  #
+  #   read(key)          -> token String or nil
+  #   write(key, token)
+  #   delete(key)
+  #
+  # That is the ActiveSupport::Cache::Store interface, so `Rails.cache`
+  # works as-is (it persists only if its backend does).
+  module TokenStores
+    INTERFACE = %i[read write delete].freeze
+
+    def self.validate!(store)
+      missing = INTERFACE.reject { |m| store.respond_to?(m) }
+      return store if missing.empty?
+
+      raise ArgumentError, "token_store must respond to #{INTERFACE.join(", ")} " \
+                           "(missing #{missing.join(", ")}): got #{store.inspect}"
+    end
+
+    # Process-local store: tokens are lost when the process exits.
+    # Clients share one of these unless configured otherwise.
+    class Memory
+      def initialize
+        @tokens = {}
+        @mutex = Mutex.new
+      end
+
+      def read(key)
+        @mutex.synchronize { @tokens[key] }
+      end
+
+      def write(key, token)
+        @mutex.synchronize { @tokens[key] = token }
+      end
+
+      def delete(key)
+        @mutex.synchronize { @tokens.delete(key) }
+      end
+
+      def clear
+        @mutex.synchronize { @tokens.clear }
+      end
+
+      # The live hash behind the store; only for the deprecated Client.token_cache.
+      def to_h
+        @tokens
+      end
+    end
+
+    # JSON file store: tokens survive process restarts. Writes take an
+    # exclusive flock on "<path>.lock" (so concurrent processes and instances
+    # don't lose each other's keys) and replace the file atomically, mode 0600.
+    class File
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+        @mutex = Mutex.new
+      end
+
+      def read(key)
+        load[key]
+      end
+
+      def write(key, token)
+        update { |tokens| tokens.merge(key => token) }
+      end
+
+      def delete(key)
+        update { |tokens| tokens.key?(key) ? tokens.except(key) : nil }
+      end
+
+      private
+
+      # Read-modify-write under the lock; the block returns the new hash, or nil for no change.
+      def update
+        @mutex.synchronize do
+          FileUtils.mkdir_p(::File.dirname(path))
+          ::File.open("#{path}.lock", ::File::RDWR | ::File::CREAT, 0o600) do |lock|
+            lock.flock(::File::LOCK_EX)
+            tokens = yield(load)
+            save(tokens) if tokens
+          end
+        end
+      end
+
+      def load
+        return {} unless ::File.exist?(path)
+
+        data = JSON.parse(::File.read(path))
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def save(tokens)
+        tmp = "#{path}.#{Process.pid}.#{SecureRandom.hex(6)}.tmp"
+        ::File.open(tmp, ::File::WRONLY | ::File::CREAT | ::File::EXCL, 0o600) { |f| f.write(JSON.generate(tokens)) }
+        ::File.rename(tmp, path)
+      end
+    end
+  end
+end

data/lib/njtransit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NJTransit
-  VERSION = "1.1.4"
+  VERSION = "1.2.0"
 end

data/lib/njtransit.rb

@@ -3,6 +3,7 @@
 require_relative "njtransit/version"
 require_relative "njtransit/configuration"
 require_relative "njtransit/error"
+require_relative "njtransit/token_stores"
 require_relative "njtransit/client"
 require_relative "njtransit/gtfs"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: njtransit
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.0
 platform: ruby
 authors:
 - Jay Ravaliya
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -135,6 +135,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/index.md
 - docs/plans/2025-01-24-njtransit-gem-design.md
 - docs/plans/2026-01-24-bus-api-design.md
 - docs/plans/2026-01-24-gtfs-implementation.md
@@ -162,6 +163,7 @@ files:
 - lib/njtransit/resources/rail_gtfs.rb
 - lib/njtransit/skill.md
 - lib/njtransit/tasks.rb
+- lib/njtransit/token_stores.rb
 - lib/njtransit/version.rb
 - sig/njtransit.rbs
 homepage: https://github.com/jayrav13/njtransit