turbovax 0.0.2pre

data/README.md

@@ -0,0 +1,91 @@
+# Turbovax
+
+Turbovax gem helps you quickly stand up bots that can:
+1) fetch data from vaccine websites
+2) tweet appointment data
+3) return structured appointment data
+
+It does not provide any data storage or web server layers. You can build that functionality on top of the gem by yourself.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'turbovax'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install turbovax
+
+## Usage
+
+Initialize configuration (optional):
+
+    Turbovax.configure do |config|
+      config.logger = Logger.new($stdout, level: Logger::DEBUG)
+      config.twitter_enabled = true
+      config.twitter_credentials = {
+        consumer_key: "CONSUMER_KEY",
+        consumer_secret: "CONSUMER_SECRET",
+        access_token: "ACCESS_TOKEN",
+        access_token_secret: "ACCESS_TOKEN_SECRET"
+      }
+
+      config.faraday_logging_config = {
+        headers: true,
+        bodies: true,
+        log_level: :info
+      }
+    end
+
+Create test portal:
+
+    class TestPortal < Turbovax::Portal
+      name "Gotham City Clinic"
+      key "gotham_city"
+      public_url "https://www.turbovax.info/"
+      api_url "http://api.turbovax.info/v1/test.json"
+      request_http_method Turbovax::Constants::GET_REQUEST_METHOD
+
+      parse_response do |response|
+        response_json = JSON.parse(response)
+        Array(response_json["appointments"]).map do |location_json|
+          appointments = Array(location_json["slots"]).map do |appointment_string|
+            {
+              time: DateTime.parse(appointment_string)
+            }
+          end
+
+          Turbovax::Location.new(
+            id: "ID",
+            name: location_json["clinic_name"],
+            full_address: location_json["area"],
+            time_zone: "America/New_York",
+            data: {
+              vaccine_types: [location_json["vaccine"]],
+              appointments: appointments,
+            }
+          )
+        end
+      end
+    end
+
+Execute operation:
+
+    locations = Turbovax::DataFetcher.new(TestPortal, twitter_handler: Turbovax::Handlers::LocationHandler).execute!
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hugem/turbovax-gem.

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/bin/console

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "pry"
+require "turbovax"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+def reload!
+  reload_paths("turbovax")
+end
+
+def reload_paths(require_regex)
+  $LOADED_FEATURES.grep(/#{require_regex}/).each { |e| $LOADED_FEATURES.delete(e) && require(e) }
+end
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/turbovax/appointment.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/all"
+
+module Turbovax
+  # Class that encapsulates a singular appointment
+  class Appointment
+    # @return [DateTime]
+    attr_accessor :time
+    # @return [String]
+    # Can automatically be set by Turbovax::Location instance
+    attr_accessor :time_zone
+    # @return [Boolean]
+    attr_accessor :is_second_dose
+    # @return [String]
+    attr_accessor :vaccine_type
+
+    # @param params hash mapping of attribute => value
+    def initialize(**params)
+      params.each do |attribute, value|
+        value_to_save =
+          if attribute.to_s == "time"
+            if value.is_a?(DateTime) || value.is_a?(Time)
+              value
+            else
+              DateTime.parse(value)
+            end
+          else
+            value
+          end
+
+        send("#{attribute}=", value_to_save)
+      end
+    end
+
+    # If time_zone is set on instance, returns appointment time in time zone
+    # @return [DateTime]
+    def time_in_time_zone
+      time_zone ? time.in_time_zone(time_zone) : time
+    end
+
+    private
+
+    def <=>(other)
+      time <=> other.time
+    end
+  end
+end

data/lib/turbovax/constants.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Turbovax
+  module Constants
+    GET_REQUEST_METHOD = :get
+    POST_REQUEST_METHOD = :post
+  end
+end

data/lib/turbovax/data_fetcher.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "date"
+require "faraday"
+
+module Turbovax
+  # This class, given a portal and a twitter handler:
+  #  1) executes request for data
+  #  2) passes structured appointment data to twitter handler
+  #  3) returns appointment data
+  class DataFetcher
+    # @param [Turbovax::Portal] portal
+    # @param [TurboVax::Twitter::Handler] twitter_handler a class handles if appointments are found
+    # @param [Hash] extra_params other info that can be provided to portal when executing blocks
+    def initialize(portal, twitter_handler: nil, extra_params: {})
+      @portal = portal
+      @extra_params = { date: DateTime.now }.merge(extra_params)
+      @conn = create_request_connection
+      @twitter_handler = twitter_handler
+    end
+
+    # @return [Array<Turbovax::Location>] List of locations and appointments
+    def execute!
+      response = make_request
+      log("make request [DONE]")
+      locations = @portal.parse_response_with_portal(response.body, @extra_params)
+      log("parse response [DONE]")
+
+      send_to_twitter_handler(locations)
+
+      locations
+    end
+
+    private
+
+    def send_to_twitter_handler(locations)
+      if !Turbovax.twitter_enabled
+        log("twitter handler [SKIP] not enabled")
+      elsif !locations.size.positive?
+        log("twitter handler [SKIP]: no location data")
+      else
+        @twitter_handler&.new(locations)&.execute!
+        log("twitter handler [DONE]")
+      end
+    end
+
+    def create_request_connection
+      Faraday.new(
+        url: @portal.api_base_url,
+        headers: @portal.request_headers,
+        ssl: { verify: false }
+      ) do |faraday|
+        faraday.response :logger, Turbovax.logger,
+                         Turbovax.faraday_logging_config
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def make_request
+      request_type = @portal.request_http_method
+      path = @portal.api_path
+      query_params = @portal.api_query_params(@extra_params)
+
+      case request_type
+      when Turbovax::Constants::GET_REQUEST_METHOD
+        make_get_request(path, query_params)
+      when Turbovax::Constants::POST_REQUEST_METHOD
+        make_post_request(path, query_params)
+      else
+        raise Turbovax::InvalidRequestTypeError
+      end
+    end
+
+    def make_get_request(path, query_params)
+      @conn.get(path) do |req|
+        # only set params if they are present, otherwise this will overwrite any string query
+        # param values that are existing in the url path
+        req.params = query_params if query_params.nil? || query_params != {}
+      end
+    end
+
+    def make_post_request(path, query_params)
+      @conn.post(path) do |req|
+        # only set params if they are present, otherwise this will overwrite any string query
+        # param values that are existing in the url path
+        req.params = query_params if query_params.nil? || query_params != {}
+        req.body = @portal.request_body(@extra_params)
+      end
+    end
+
+    def log(message)
+      Turbovax.logger.info("[#{self.class}] #{message}")
+    end
+  end
+end

data/lib/turbovax/handlers/location_handler.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "twitter"
+
+module Turbovax
+  module Handlers
+    # Given a list of locations, tweet appointment info for each location
+    class LocationHandler
+      def initialize(locations)
+        @locations = locations
+      end
+
+      def execute!
+        count = 0
+        @locations.each do |location|
+          next if count >= max_location_limit
+
+          count += 1 if handle_location(location)
+        end
+      end
+
+      # Max locations to tweet at a given time
+      def max_location_limit
+        2
+      end
+
+      # Max number of days included in a tweet
+      def day_limit
+        3
+      end
+
+      # Max number of appointment times included per day
+      def daily_appointment_limit
+        3
+      end
+
+      # Format of each individual date. See APIdoc for format
+      # https://apidock.com/ruby/DateTime/strftime
+      # @example Datetime to default time format
+      #   Wed, 21 Apr 2021 09:23:15 -0400 => Apr 21
+      def date_format
+        "%b %-e"
+      end
+
+      # Format of each individual appointment time. See APIdoc for format
+      # https://apidock.com/ruby/DateTime/strftime
+      # @example Datetime to default time format
+      #   Wed, 21 Apr 2021 09:23:15 -0400 => 9:23AM
+      def appointment_time_format
+        "%-l:%M%p"
+      end
+
+      # @return [Boolean]
+      # Override this method to to add caching logic
+      def should_tweet_for_location(location)
+        location.available
+      end
+
+      private
+
+      def handle_location(location)
+        return false unless should_tweet_for_location(location)
+
+        text = format_tweet(location)
+
+        send_tweet(text)
+        true
+      end
+
+      def send_tweet(text)
+        Turbovax::TwitterClient.send_tweet(text)
+      end
+
+      def format_tweet(location)
+        to_join = []
+
+        portal = location.portal
+        appointment_count = location.appointment_count ? "#{location.appointment_count} appts" : nil
+
+        summary_string = "[#{join(portal.name, location.area, delimiter: " · ")}] "
+        summary_string += join(location.name, appointment_count, delimiter: ": ")
+        to_join << summary_string
+
+        to_join << format_appointments(location)
+        to_join << portal.public_url
+
+        to_join.join("\n\n")
+      end
+
+      def format_appointments(location)
+        to_join = []
+
+        appointments_by_day =
+          group_appointments_by_day(location.appointments.sort)
+
+        appointments_by_day.each.with_index do |(day, appointments), index|
+          next if index >= day_limit
+
+          to_join << format_appointments_for_day(day, appointments)
+        end
+
+        to_join.join("\n")
+      end
+
+      def group_appointments_by_day(appointments)
+        appointments.each_with_object({}) do |appointment, memo|
+          day = appointment.time_in_time_zone.strftime(date_format)
+
+          memo[day] ||= []
+          memo[day] << appointment
+        end
+      end
+
+      def format_appointments_for_day(day_string, appointments)
+        use_extra_appointment_count = appointments.size > daily_appointment_limit
+        extra_appointment_count = appointments.size - daily_appointment_limit
+
+        sorted_times = appointments.first(daily_appointment_limit).sort.map do |appointment|
+          appointment.time_in_time_zone.strftime(appointment_time_format)
+        end
+
+        time_string = sorted_times.join(", ")
+        time_string += " + #{extra_appointment_count}" if use_extra_appointment_count
+
+        "#{day_string}: #{time_string}"
+      end
+
+      def join(*args, delimiter:)
+        args.compact.join(delimiter)
+      end
+    end
+  end
+end

data/lib/turbovax/location.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Turbovax
+  # Representation of an individual vaccination site
+  class Location
+    # @return [String]
+    # Turbovax-specific unique ID for identification purposes
+    attr_accessor :id
+    # @return [String]
+    # Human readable name
+    attr_accessor :name
+    # @return [Turbovax::Portal]
+    attr_accessor :portal
+    # @return [String]
+    # Portal specific ID
+    attr_accessor :portal_id
+    # @return [String]
+    attr_accessor :full_address
+    # @return [String]
+    attr_accessor :area
+    # @return [String]
+    attr_accessor :zipcode
+    # @return [String]
+    attr_accessor :latitude
+    # @return [String]
+    attr_accessor :longitude
+    # @return [String]
+    # Valid values in https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html
+    attr_accessor :time_zone
+    # @return [Hash]
+    # Use this nested hash to specify appointments, appointment_count, available, vaccine_types
+    attr_accessor :data
+    # @return [Hash]
+    # Use this attribute to add any metadata
+    attr_accessor :metadata
+
+    def initialize(**params)
+      params.each do |attribute, value|
+        send("#{attribute}=", value)
+      end
+    end
+
+    # @return [Boolean]
+    # This can be manually specified via data hash or automatically calculated if
+    # appointment_count > 0
+    def available
+      data_hash[:available] || appointment_count.positive?
+    end
+
+    # This can be manually specified via data hash or automatically calculated
+    def vaccine_types
+      data_hash[:vaccine_types] || appointments.map(&:vaccine_type).uniq
+    end
+
+    # Returns a list of appointment instances (which are defined via) data hash
+    def appointments
+      Array(data_hash[:appointments]).map do |appointment|
+        if appointment.is_a?(Turbovax::Appointment)
+          appointment.time_zone = time_zone
+          appointment
+        else
+          Turbovax::Appointment.new(appointment.merge(time_zone: time_zone))
+        end
+      end
+    end
+
+    def appointment_count
+      data_hash[:appointment_count] || appointments.size
+    end
+
+    private
+
+    def data_hash
+      data || {}
+    end
+  end
+end