njtransit 1.0.0

data/README.md

@@ -0,0 +1,148 @@
+# NJTransit
+
+A Ruby gem for NJ Transit's real-time and schedule data — buses, trains, and light rail. Built to be easy to drop into AI agents, chatbots, and creative projects that need live transit data.
+
+## What You Can Do
+
+- **Real-time departures** — "When is the next bus/train?" with live arrival times and delay status
+- **Train tracking** — GPS positions, speed, and delay info for every active train
+- **Schedule lookups** — Full timetables via GTFS static data, not just the next hour
+- **Stop discovery** — Find nearby stops by coordinates
+- **Route planning** — Find which routes connect two stops
+- **Light rail** — Hudson-Bergen, Newark, and RiverLINE via the same API
+- **GTFS-RT feeds** — Raw protobuf feeds for alerts, trip updates, and vehicle positions
+
+## Quick Start
+
+### 1. Get API Credentials
+
+Register at [developer.njtransit.com](https://developer.njtransit.com/registration) to get a username and password.
+
+### 2. Install
+
+```ruby
+gem 'njtransit'
+```
+
+### 3. Configure
+
+```ruby
+require 'njtransit'
+
+NJTransit.configure do |config|
+  config.username = ENV['NJTRANSIT_USERNAME']
+  config.password = ENV['NJTRANSIT_PASSWORD']
+end
+```
+
+### 4. Start Querying
+
+```ruby
+# Two clients: one for buses/light rail, one for trains
+client = NJTransit.client
+rail_client = NJTransit.rail_client
+
+# When is the next bus from Port Authority?
+client.bus.departures(stop: "PABT", enrich: false)
+
+# Next trains from NY Penn Station
+rail_client.rail.train_schedule_19(station: "NY")
+
+# Where is train #3837 right now?
+rail_client.rail.train_stop_list(train_id: "3837")
+
+# What stops are within 2000 feet of me?
+client.bus.stops_nearby(lat: 40.878, lon: -74.221, radius: 2000, enrich: false)
+# radius is in feet
+
+# Light rail routes
+client.bus.routes(mode: "HBLR")  # Hudson-Bergen Light Rail
+```
+
+## Two Clients, One Gem
+
+NJ Transit splits its API across two hosts. The gem handles this with two clients:
+
+| Client | Host | What it covers |
+|--------|------|----------------|
+| `NJTransit.client` | pcsdata.njtransit.com | Buses, light rail, bus GTFS-RT |
+| `NJTransit.rail_client` | raildata.njtransit.com | Trains, rail GTFS-RT |
+
+Both authenticate automatically. The bus client also supports light rail by passing a `mode` parameter (`HBLR`, `NLR`, `RL`, or `ALL`).
+
+## Capabilities Overview
+
+### Bus & Light Rail (`client.bus`)
+
+Real-time departures, routes, stops, directions, nearby stops/vehicles, and trip tracking. Most methods accept an `enrich` flag — set `enrich: false` if you haven't imported GTFS static data.
+
+### Rail (`rail_client.rail`)
+
+Train schedules (real-time and full-day), station alerts and delay messages, train stop lists, and live vehicle positions for every active train.
+
+### GTFS Static Data
+
+Full offline schedules imported into a local SQLite database. Useful for answering "what's the schedule tomorrow?" when the real-time API only shows the next hour.
+
+```ruby
+# Import once
+NJTransit::GTFS.import("/path/to/gtfs/data")
+
+# Then query
+gtfs = NJTransit::GTFS.new
+gtfs.schedule(route: "191", stop: "27005", date: Date.new(2026, 3, 28))
+gtfs.routes_between(from: "WBRK", to: "PABT")
+```
+
+Rake tasks are also available: `rake njtransit:gtfs:import`, `rake njtransit:gtfs:status`, `rake njtransit:gtfs:clear`.
+
+### GTFS-RT Feeds
+
+Raw protobuf feeds for real-time alerts, trip updates, and vehicle positions:
+
+```ruby
+client.bus_gtfs.alerts            # Bus alerts
+client.bus_gtfs.vehicle_positions # Bus vehicle positions
+rail_client.rail_gtfs.trip_updates # Rail trip updates
+```
+
+A newer G2 version of the bus feeds is also available via `client.bus_gtfs_g2`.
+
+## Using with Claude Code
+
+If you have [Claude Code](https://claude.ai/code) installed, the `/njtransit` skill lets you ask transit questions directly from your terminal:
+
+```
+/njtransit when is the next train from NY Penn to Trenton?
+/njtransit what buses stop near 40.878, -74.221?
+/njtransit is the Northeast Corridor delayed?
+```
+
+Claude writes and runs Ruby code against the gem to answer your question. It's a good way to explore what the API can do without writing code yourself.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NJTRANSIT_USERNAME` | API username | — |
+| `NJTRANSIT_PASSWORD` | API password | — |
+| `NJTRANSIT_LOG_LEVEL` | `silent`, `info`, or `debug` | `silent` |
+| `NJTRANSIT_BASE_URL` | Bus API base URL | `https://pcsdata.njtransit.com` |
+| `NJTRANSIT_TIMEOUT` | Request timeout (seconds) | `30` |
+| `NJTRANSIT_GTFS_DATABASE_PATH` | SQLite database path | `~/.local/share/njtransit/gtfs.sqlite3` |
+
+## Development
+
+```sh
+bin/setup          # Install dependencies
+bundle exec rspec  # Run tests (153 specs)
+bin/console        # Interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at [github.com/jayrav13/njtransit](https://github.com/jayrav13/njtransit).
+
+## License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/plans/2025-01-24-njtransit-gem-design.md

@@ -0,0 +1,112 @@
+# NJTransit Ruby Gem Design
+
+## Overview
+
+A developer-friendly Ruby gem for interacting with NJTransit's API. Designed for both personal use and open-source distribution.
+
+## Design Decisions
+
+| Aspect | Decision | Rationale |
+|--------|----------|-----------|
+| Name | `njtransit` | Simple, direct, recognizable |
+| Ruby version | 3.2+ | Modern Ruby, allows newest syntax |
+| HTTP client | Faraday + Typhoeus adapter | Typhoeus performance with Faraday middleware flexibility |
+| Logging | Environment-based (silent/info/debug) | Selective logging based on `NJTRANSIT_LOG_LEVEL` |
+| Testing | RSpec | Most common for gems, expressive syntax |
+| API pattern | Global config + explicit instances | Convenience for simple apps, flexibility for advanced use |
+| Errors | Comprehensive hierarchy | Granular error handling for all HTTP status codes |
+
+## Architecture
+
+### Module Structure
+
+```
+lib/
+├── njtransit.rb              # Entry point, global config
+└── njtransit/
+    ├── version.rb
+    ├── configuration.rb      # Config object with env var defaults
+    ├── client.rb             # HTTP client (Faraday + Typhoeus)
+    ├── error.rb              # Error class hierarchy
+    └── resources/            # One file per API domain
+        └── base.rb           # Base class for resources
+```
+
+### Usage Patterns
+
+**Global configuration (convenience):**
+
+```ruby
+NJTransit.configure do |config|
+  config.api_key = ENV['NJTRANSIT_API_KEY']
+  config.log_level = 'debug'  # silent, info, or debug
+end
+
+client = NJTransit.client
+client.stations.list
+```
+
+**Explicit instance (flexibility):**
+
+```ruby
+client = NJTransit::Client.new(
+  api_key: "your_key",
+  log_level: "info"
+)
+client.stations.list
+```
+
+Both patterns use the same `Client` class - no code duplication.
+
+### Configuration
+
+Supports environment variables with sensible defaults:
+
+- `NJTRANSIT_API_KEY` - API key (required for most endpoints)
+- `NJTRANSIT_LOG_LEVEL` - Logging verbosity (silent/info/debug, default: silent)
+- `NJTRANSIT_BASE_URL` - API base URL (overridable for testing)
+- `NJTRANSIT_TIMEOUT` - Request timeout in seconds (default: 30)
+
+### Error Hierarchy
+
+```
+NJTransit::Error
+├── ClientError (4xx)
+│   ├── BadRequestError (400)
+│   ├── AuthenticationError (401)
+│   ├── ForbiddenError (403)
+│   ├── NotFoundError (404)
+│   ├── MethodNotAllowedError (405)
+│   ├── ConflictError (409)
+│   ├── GoneError (410)
+│   ├── UnprocessableEntityError (422)
+│   └── RateLimitError (429)
+├── ServerError (5xx)
+│   ├── InternalServerError (500)
+│   ├── BadGatewayError (502)
+│   ├── ServiceUnavailableError (503)
+│   └── GatewayTimeoutError (504)
+└── ConnectionError
+    └── TimeoutError
+```
+
+All errors include the original response for inspection.
+
+### Logging Levels
+
+- **silent** (default): No output
+- **info**: Request URLs and response status codes
+- **debug**: Full request/response headers and bodies
+
+## Next Steps
+
+1. Drop NJTransit API documentation into `docs/api/`
+2. Review available endpoints
+3. Create resource classes for each API domain (stations, routes, schedules, etc.)
+4. Add comprehensive specs with mocked responses
+5. Document usage in README
+
+## Notes
+
+- `docs/api/` is gitignored - API docs are private/behind auth
+- Full API coverage is the goal - establish patterns early, then the rest becomes mechanical

data/docs/plans/2026-01-24-bus-api-design.md

@@ -0,0 +1,119 @@
+# NJ Transit Bus API Integration Design
+
+## Overview
+
+Add support for the NJ Transit BUSDV2 API, providing access to bus schedules, real-time departures, stops, routes, and vehicle locations.
+
+## Configuration
+
+Replace `api_key` with `username` and `password`. Update default `base_url` to production endpoint.
+
+```ruby
+NJTransit.configure do |c|
+  c.username = ENV["NJTRANSIT_USERNAME"]
+  c.password = ENV["NJTRANSIT_PASSWORD"]
+  c.base_url = "https://pcsdata.njtransit.com"  # new default
+  c.timeout = 30
+end
+```
+
+## Authentication
+
+Lazy authentication by default:
+
+1. First API call checks for cached token
+2. If no token, call `authenticateUser` with username/password
+3. Cache token in memory on client instance
+4. If response contains `{"errorMessage": "Invalid token."}`, re-authenticate once and retry
+5. If re-auth fails, raise `NJTransit::AuthenticationError`
+
+No cross-process token persistence. Each client instance manages its own token.
+
+## Client Changes
+
+The Bus API requires `multipart/form-data` POST requests (not JSON).
+
+Add `post_form` method to client:
+
+```ruby
+def post_form(path, params = {})
+  response = connection.post(path) do |req|
+    req.body = params  # Faraday handles form encoding
+  end
+  handle_response(response)
+end
+```
+
+The `Bus` resource injects the token automatically into all requests.
+
+## Bus Resource
+
+Single flat resource at `client.bus` with hardcoded `mode: "BUS"`. Future modes (light rail, etc.) will be separate resources using the same underlying API.
+
+### Methods
+
+| Method | Required Params | Optional Params | API Endpoint |
+|--------|----------------|-----------------|--------------|
+| `locations` | - | - | `getLocations` |
+| `routes` | - | - | `getBusRoutes` |
+| `directions` | `route:` | - | `getBusDirectionsData` |
+| `stops` | `route:`, `direction:` | `name_contains:` | `getStops` |
+| `stop_name` | `stop_number:` | - | `getStopName` |
+| `route_trips` | `location:`, `route:` | - | `getRouteTrips` |
+| `departures` | `stop:` | `route:`, `direction:` | `getBusDV` |
+| `trip_stops` | `internal_trip_number:`, `sched_dep_time:` | `timing_point_id:` | `getTripStops` |
+| `stops_nearby` | `lat:`, `lon:`, `radius:` | `route:`, `direction:` | `getBusLocationsData` |
+| `vehicles_nearby` | `lat:`, `lon:`, `radius:` | - | `getVehicleLocations` |
+
+### Return Values
+
+All methods return raw hashes/arrays as returned by the API. No object wrapping.
+
+## Error Handling
+
+The Bus API returns errors in response body, not HTTP status codes.
+
+Detection:
+- Check response for `errorMessage` key
+- `"Invalid token."` → re-authenticate, retry once, raise `AuthenticationError` if still failing
+- Other `errorMessage` values → raise `NJTransit::APIError`
+
+New error class:
+
+```ruby
+class APIError < Error; end
+```
+
+Existing errors (ConnectionError, TimeoutError, HTTP status errors) remain unchanged.
+
+## File Structure
+
+```
+lib/njtransit/
+├── configuration.rb      # Modified: username/password, new base_url
+├── client.rb             # Modified: post_form, token management, bus accessor
+├── error.rb              # Modified: add APIError
+└── resources/
+    ├── base.rb           # Unchanged
+    └── bus.rb            # New
+```
+
+## Usage Example
+
+```ruby
+NJTransit.configure do |c|
+  c.username = "myuser"
+  c.password = "mypass"
+end
+
+client = NJTransit.client
+
+# Get all routes
+client.bus.routes
+
+# Get real-time departures at Port Authority
+client.bus.departures(stop: "PABT")
+
+# Find vehicles near Newark
+client.bus.vehicles_nearby(lat: 40.737, lon: -74.170, radius: 2000)
+```