njtransit 1.0.0

data/lib/njtransit/client.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/typhoeus"
+require "faraday/multipart"
+require "json"
+
+require_relative "resources/base"
+require_relative "resources/bus"
+require_relative "resources/rail"
+require_relative "resources/bus_gtfs"
+require_relative "resources/rail_gtfs"
+
+module NJTransit
+  class Client
+    DEFAULT_AUTH_PATH = "/api/BUSDV2/authenticateUser"
+
+    attr_reader :username, :password, :log_level, :base_url, :timeout, :auth_path
+
+    def initialize(username:, password:, log_level: "silent", base_url: Configuration::DEFAULT_BASE_URL,
+                   timeout: Configuration::DEFAULT_TIMEOUT, auth_path: DEFAULT_AUTH_PATH)
+      @username = username
+      @password = password
+      @log_level = log_level
+      @base_url = base_url
+      @timeout = timeout
+      @auth_path = auth_path
+      @token = nil
+    end
+
+    def bus
+      @bus ||= Resources::Bus.new(self)
+    end
+
+    def rail
+      @rail ||= Resources::Rail.new(self)
+    end
+
+    def bus_gtfs
+      @bus_gtfs ||= Resources::BusGTFS.new(self)
+    end
+
+    def bus_gtfs_g2
+      @bus_gtfs_g2 ||= Resources::BusGTFS.new(self, api_prefix: "/api/GTFSG2")
+    end
+
+    def rail_gtfs
+      @rail_gtfs ||= Resources::RailGTFS.new(self)
+    end
+
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    def post(path, body = {})
+      request(:post, path, body)
+    end
+
+    def post_form(path, params = {})
+      request_form(:post, path, params)
+    end
+
+    def put(path, body = {})
+      request(:put, path, body)
+    end
+
+    def patch(path, body = {})
+      request(:patch, path, body)
+    end
+
+    def delete(path, params = {})
+      request(:delete, path, params)
+    end
+
+    def post_form_raw(path, params = {})
+      request_form_raw(:post, path, params)
+    end
+
+    def authenticate!
+      cached = self.class.token_cache[base_url]
+      if cached
+        @token = cached
+        return @token
+      end
+
+      response = form_connection.post(auth_path) do |req|
+        req.body = { username: username, password: password }
+      end
+
+      result = parse_body(response.body)
+
+      unless result.is_a?(Hash) && result["Authenticated"] == "True"
+        message = result.is_a?(Hash) && result["errorMessage"] ? result["errorMessage"] : "Authentication failed"
+        raise AuthenticationError, message
+      end
+
+      @token = result["UserToken"]
+      self.class.token_cache[base_url] = @token
+      @token
+    end
+
+    def token
+      authenticate! if @token.nil?
+      @token
+    end
+
+    def clear_token!
+      @token = nil
+      self.class.token_cache.delete(base_url)
+    end
+
+    def self.token_cache
+      @token_cache ||= {}
+    end
+
+    def self.clear_token_cache!
+      @token_cache = {}
+    end
+
+    private
+
+    def request(method, path, params_or_body = {})
+      response = json_connection.public_send(method) do |req|
+        req.url(path)
+        if %i[get delete].include?(method)
+          req.params = params_or_body
+        else
+          req.body = JSON.generate(params_or_body)
+        end
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, e.message
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, e.message
+    end
+
+    def request_form(method, path, params = {}, retry_auth: true)
+      response = form_connection.public_send(method) do |req|
+        req.url(path)
+        req.body = params
+      end
+
+      result = handle_response(response)
+
+      if token_expired?(result) && retry_auth
+        clear_token!
+        authenticate!
+        params[:token] = @token
+        return request_form(method, path, params, retry_auth: false)
+      end
+
+      check_api_error!(result)
+      result
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, e.message
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, e.message
+    end
+
+    def request_form_raw(method, path, params = {})
+      params[:token] = token
+      response = raw_connection.public_send(method) do |req|
+        req.url(path)
+        req.body = params
+      end
+
+      raise error_for_status(response.status).new(error_message(response), response: response) unless response.success?
+
+      response.body
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, e.message
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, e.message
+    end
+
+    def token_expired?(result)
+      result.is_a?(Hash) && result["errorMessage"] == "Invalid token."
+    end
+
+    def check_api_error!(result)
+      return unless result.is_a?(Hash) && result["errorMessage"]
+
+      raise APIError, result["errorMessage"]
+    end
+
+    def json_connection
+      @json_connection ||= Faraday.new(url: base_url) do |f|
+        f.request :json
+        f.response :logger, logger, { headers: log_headers?, bodies: log_bodies? } if logging_enabled?
+        f.adapter :typhoeus
+        f.options.timeout = timeout
+        f.options.open_timeout = timeout
+        f.headers["Content-Type"] = "application/json"
+        f.headers["Accept"] = "application/json"
+      end
+    end
+
+    def form_connection
+      @form_connection ||= Faraday.new(url: base_url) do |f|
+        f.request :multipart
+        f.request :url_encoded
+        f.response :logger, logger, { headers: log_headers?, bodies: log_bodies? } if logging_enabled?
+        f.adapter :typhoeus
+        f.options.timeout = timeout
+        f.options.open_timeout = timeout
+        f.headers["Accept"] = "text/plain"
+      end
+    end
+
+    def raw_connection
+      @raw_connection ||= Faraday.new(url: base_url) do |f|
+        f.request :multipart
+        f.request :url_encoded
+        f.adapter :typhoeus
+        f.options.timeout = timeout
+        f.options.open_timeout = timeout
+        f.headers["Accept"] = "*/*"
+      end
+    end
+
+    def handle_response(response)
+      return parse_body(response.body) if response.success?
+
+      raise error_for_status(response.status).new(
+        error_message(response),
+        response: response
+      )
+    end
+
+    def parse_body(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def error_message(response)
+      parsed = parse_body(response.body)
+      if parsed.is_a?(Hash)
+        parsed["error"] || parsed["message"] || parsed["errorMessage"] || response.body
+      else
+        response.body
+      end
+    end
+
+    def error_for_status(status)
+      case status
+      when 400 then BadRequestError
+      when 401 then AuthenticationError
+      when 403 then ForbiddenError
+      when 404 then NotFoundError
+      when 405 then MethodNotAllowedError
+      when 409 then ConflictError
+      when 410 then GoneError
+      when 422 then UnprocessableEntityError
+      when 429 then RateLimitError
+      when 500 then InternalServerError
+      when 502 then BadGatewayError
+      when 503 then ServiceUnavailableError
+      when 504 then GatewayTimeoutError
+      when 400..499 then ClientError
+      when 500..599 then ServerError
+      else Error
+      end
+    end
+
+    def logging_enabled?
+      %w[info debug].include?(log_level)
+    end
+
+    def log_headers?
+      log_level == "debug"
+    end
+
+    def log_bodies?
+      log_level == "debug"
+    end
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.level = log_level == "debug" ? Logger::DEBUG : Logger::INFO
+        log.formatter = proc do |severity, _datetime, _progname, msg|
+          "[NJTransit #{severity}] #{msg}\n"
+        end
+      end
+    end
+  end
+end

data/lib/njtransit/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module NJTransit
+  class Configuration
+    VALID_LOG_LEVELS = %w[silent info debug].freeze
+    DEFAULT_BASE_URL = "https://pcsdata.njtransit.com"
+    DEFAULT_RAIL_BASE_URL = "https://raildata.njtransit.com"
+    DEFAULT_TIMEOUT = 30
+
+    attr_accessor :username, :password, :base_url, :timeout, :gtfs_database_path
+    attr_reader :log_level
+
+    def initialize
+      @username = ENV.fetch("NJTRANSIT_USERNAME", nil)
+      @password = ENV.fetch("NJTRANSIT_PASSWORD", nil)
+      @log_level = ENV.fetch("NJTRANSIT_LOG_LEVEL", "silent")
+      @base_url = ENV.fetch("NJTRANSIT_BASE_URL", DEFAULT_BASE_URL)
+      @timeout = ENV.fetch("NJTRANSIT_TIMEOUT", DEFAULT_TIMEOUT).to_i
+      @gtfs_database_path = ENV.fetch("NJTRANSIT_GTFS_DATABASE_PATH", nil) || default_gtfs_database_path
+    end
+
+    def log_level=(level)
+      level = level.to_s.downcase
+      unless VALID_LOG_LEVELS.include?(level)
+        raise ArgumentError,
+              "Invalid log level: #{level}. Valid levels: #{VALID_LOG_LEVELS.join(", ")}"
+      end
+
+      @log_level = level
+    end
+
+    def to_h
+      {
+        username: username,
+        password: password,
+        log_level: log_level,
+        base_url: base_url,
+        timeout: timeout
+      }
+    end
+
+    private
+
+    def default_gtfs_database_path
+      base = ENV["XDG_DATA_HOME"] || File.expand_path("~/.local/share")
+      File.join(base, "njtransit", "gtfs.sqlite3")
+    end
+  end
+end

data/lib/njtransit/error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module NJTransit
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  # API-level errors (returned in response body)
+  class APIError < Error; end
+
+  # Client errors (4xx)
+  class ClientError < Error; end
+  class BadRequestError < ClientError; end        # 400
+  class AuthenticationError < ClientError; end    # 401
+  class ForbiddenError < ClientError; end         # 403
+  class NotFoundError < ClientError; end          # 404
+  class MethodNotAllowedError < ClientError; end  # 405
+  class ConflictError < ClientError; end          # 409
+  class GoneError < ClientError; end              # 410
+  class UnprocessableEntityError < ClientError; end # 422
+  class RateLimitError < ClientError; end # 429
+
+  # Server errors (5xx)
+  class ServerError < Error; end
+  class InternalServerError < ServerError; end    # 500
+  class BadGatewayError < ServerError; end        # 502
+  class ServiceUnavailableError < ServerError; end # 503
+  class GatewayTimeoutError < ServerError; end # 504
+
+  # Connection issues
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+
+  # GTFS not imported
+  class GTFSNotImportedError < Error
+    def initialize(detected_path: nil)
+      message = "GTFS data not found. Run: rake njtransit:gtfs:import[/path/to/bus_data]"
+      if detected_path
+        message += "\n\nDetected GTFS files at: #{detected_path}"
+        message += "\nHint: rake njtransit:gtfs:import[#{detected_path}]"
+      end
+      super(message)
+    end
+  end
+end

data/lib/njtransit/gtfs/database.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "fileutils"
+
+module NJTransit
+  module GTFS
+    # Database module for managing GTFS SQLite storage
+    module Database
+      class << self
+        def connection(path = nil)
+          @path = path if path
+          @connection ||= begin
+            FileUtils.mkdir_p(File.dirname(@path))
+            Sequel.sqlite(@path)
+          end
+        end
+
+        def disconnect
+          @connection&.disconnect
+          @connection = nil
+        end
+
+        def exists?(path)
+          return false unless File.exist?(path)
+
+          db = Sequel.sqlite(path)
+          db.table_exists?(:agencies) && db.table_exists?(:stops)
+        rescue StandardError
+          false
+        ensure
+          db&.disconnect
+        end
+
+        def setup_schema!
+          create_agencies_table
+          create_routes_table
+          create_stops_table
+          create_trips_table
+          create_stop_times_table
+          create_calendar_dates_table
+          create_shapes_table
+          create_import_metadata_table
+        end
+
+        def clear!
+          db = connection
+          %i[agencies routes stops trips stop_times calendar_dates shapes import_metadata].each do |table|
+            db.drop_table?(table)
+          end
+        end
+
+        private
+
+        def create_agencies_table
+          connection.create_table?(:agencies) do
+            String :agency_id, primary_key: true
+            String :agency_name
+            String :agency_url
+            String :agency_timezone
+          end
+        end
+
+        def create_routes_table
+          connection.create_table?(:routes) do
+            String :route_id, primary_key: true
+            String :agency_id
+            String :route_short_name
+            String :route_long_name
+            Integer :route_type
+            String :route_color
+            index :route_short_name
+          end
+        end
+
+        def create_stops_table
+          connection.create_table?(:stops) do
+            String :stop_id, primary_key: true
+            String :stop_code
+            String :stop_name
+            Float :stop_lat
+            Float :stop_lon
+            String :zone_id
+            index :stop_code
+          end
+        end
+
+        def create_trips_table
+          connection.create_table?(:trips) do
+            String :trip_id, primary_key: true
+            String :route_id
+            String :service_id
+            String :trip_headsign
+            Integer :direction_id
+            String :shape_id
+            index :route_id
+            index :service_id
+          end
+        end
+
+        def create_stop_times_table
+          connection.create_table?(:stop_times) do
+            primary_key :id
+            String :trip_id
+            String :stop_id
+            String :arrival_time
+            String :departure_time
+            Integer :stop_sequence
+            index :trip_id
+            index :stop_id
+          end
+        end
+
+        def create_calendar_dates_table
+          connection.create_table?(:calendar_dates) do
+            primary_key :id
+            String :service_id
+            String :date
+            Integer :exception_type
+            index %i[service_id date]
+          end
+        end
+
+        def create_shapes_table
+          connection.create_table?(:shapes) do
+            primary_key :id
+            String :shape_id
+            Float :shape_pt_lat
+            Float :shape_pt_lon
+            Integer :shape_pt_sequence
+            index :shape_id
+          end
+        end
+
+        def create_import_metadata_table
+          connection.create_table?(:import_metadata) do
+            primary_key :id
+            DateTime :imported_at
+            String :source_path
+          end
+        end
+      end
+    end
+  end
+end

data/lib/njtransit/gtfs/importer.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module NJTransit
+  module GTFS
+    class Importer
+      REQUIRED_FILES = %w[agency.txt routes.txt stops.txt].freeze
+      OPTIONAL_FILES = %w[trips.txt stop_times.txt calendar_dates.txt shapes.txt].freeze
+
+      # Table configurations: [filename, table, batch_size, field_mapper]
+      TABLE_CONFIGS = {
+        agencies: ["agency.txt", 1000, ->(r) { agency_fields(r) }],
+        routes: ["routes.txt", 1000, ->(r) { route_fields(r) }],
+        stops: ["stops.txt", 1000, ->(r) { stop_fields(r) }],
+        trips: ["trips.txt", 1000, ->(r) { trip_fields(r) }],
+        stop_times: ["stop_times.txt", 10_000, ->(r) { stop_time_fields(r) }],
+        calendar_dates: ["calendar_dates.txt", 1000, ->(r) { calendar_date_fields(r) }],
+        shapes: ["shapes.txt", 50_000, ->(r) { shape_fields(r) }]
+      }.freeze
+
+      attr_reader :source_path, :db_path
+
+      def initialize(source_path, db_path)
+        @source_path = source_path
+        @db_path = db_path
+      end
+
+      def import(force: false)
+        validate_can_import!(force)
+        prepare_database(force)
+        import_all_tables
+        record_metadata
+      end
+
+      def valid_gtfs_directory?
+        return false unless File.directory?(source_path)
+
+        REQUIRED_FILES.all? { |f| File.exist?(File.join(source_path, f)) }
+      end
+
+      class << self
+        def agency_fields(row)
+          { agency_id: row["agency_id"], agency_name: row["agency_name"],
+            agency_url: row["agency_url"], agency_timezone: row["agency_timezone"] }
+        end
+
+        def route_fields(row)
+          { route_id: row["route_id"], agency_id: row["agency_id"],
+            route_short_name: row["route_short_name"], route_long_name: row["route_long_name"],
+            route_type: row["route_type"]&.to_i, route_color: row["route_color"] }
+        end
+
+        def stop_fields(row)
+          { stop_id: row["stop_id"], stop_code: row["stop_code"], stop_name: row["stop_name"],
+            stop_lat: row["stop_lat"]&.to_f, stop_lon: row["stop_lon"]&.to_f, zone_id: row["zone_id"] }
+        end
+
+        def trip_fields(row)
+          { trip_id: row["trip_id"], route_id: row["route_id"], service_id: row["service_id"],
+            trip_headsign: row["trip_headsign"], direction_id: row["direction_id"]&.to_i, shape_id: row["shape_id"] }
+        end
+
+        def stop_time_fields(row)
+          { trip_id: row["trip_id"], stop_id: row["stop_id"], arrival_time: row["arrival_time"],
+            departure_time: row["departure_time"], stop_sequence: row["stop_sequence"]&.to_i }
+        end
+
+        def calendar_date_fields(row)
+          { service_id: row["service_id"], date: row["date"], exception_type: row["exception_type"]&.to_i }
+        end
+
+        def shape_fields(row)
+          { shape_id: row["shape_id"], shape_pt_lat: row["shape_pt_lat"]&.to_f,
+            shape_pt_lon: row["shape_pt_lon"]&.to_f, shape_pt_sequence: row["shape_pt_sequence"]&.to_i }
+        end
+      end
+
+      private
+
+      def validate_can_import!(force)
+        return unless Database.exists?(db_path) && !force
+
+        raise NJTransit::Error, "GTFS database already exists at #{db_path}. Use force: true to reimport."
+      end
+
+      def prepare_database(force)
+        Database.disconnect
+        FileUtils.rm_f(db_path) if force
+        Database.connection(db_path)
+        Database.setup_schema!
+      end
+
+      def import_all_tables
+        TABLE_CONFIGS.each do |table, (filename, batch_size, mapper)|
+          import_csv(filename, table, batch_size: batch_size, &mapper)
+        end
+      end
+
+      def import_csv(filename, table, batch_size: 1000)
+        path = File.join(source_path, filename)
+        return unless File.exist?(path)
+
+        batch = []
+        CSV.foreach(path, headers: true) do |row|
+          batch << yield(row)
+          flush_batch(table, batch) if batch.size >= batch_size
+        end
+        flush_batch(table, batch)
+      end
+
+      def flush_batch(table, batch)
+        return if batch.empty?
+
+        Database.connection[table].multi_insert(batch)
+        batch.clear
+      end
+
+      def record_metadata
+        Database.connection[:import_metadata].insert(imported_at: Time.now, source_path: source_path)
+      end
+    end
+  end
+end