cubesmart 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea9ec6ccaa984aec55a381edbdb9bf8998b2d2e60274ae4440f6a6ee7476730e
+  data.tar.gz: 787a788d8d62665887f49dd8ae34e6f9ff6d0f0d3f31b507602e719a4d826e95
+SHA512:
+  metadata.gz: 9e68c9af8d7bef159d0a0c920fefe68dcdfa2bc3ac87bbf81217bc7f9a42e7520d8a154135a2e05b52530becf577b6ce9adeae53c15cee18306098f5b2affb6e
+  data.tar.gz: ad330358eb510641de1d7f6c94580895730ff443074d38babf561f0625fc093d220630c56a6ba3a4a19c47d53507c887a1db399d6df8ddaf3e438d30ae03511b

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+gem 'rspec'
+gem 'rspec_junit_formatter'
+gem 'rubocop'
+gem 'rubocop-rake'
+gem 'rubocop-rspec'
+gem 'vcr'
+gem 'webmock'
+gem 'yard'

data/README.md

@@ -0,0 +1,50 @@
+# CubeSmart
+
+[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ksylvest/cubesmart/blob/main/LICENSE)
+[![RubyGems](https://img.shields.io/gem/v/cubesmart)](https://rubygems.org/gems/cubesmart)
+[![GitHub](https://img.shields.io/badge/github-repo-blue.svg)](https://github.com/ksylvest/cubesmart)
+[![Yard](https://img.shields.io/badge/docs-site-blue.svg)](https://cubesmart.ksylvest.com)
+[![CircleCI](https://img.shields.io/circleci/build/github/ksylvest/cubesmart)](https://circleci.com/gh/ksylvest/cubesmart)
+
+## Installation
+
+```bash
+gem install extrapsace
+```
+
+## Configuration
+
+```ruby
+require 'cubesmart'
+
+CubeSmart.configure do |config|
+  config.user_agent = '../..' # ENV['CUBESMART_USER_AGENT']
+  config.timeout = 30 # ENV['CUBESMART_TIMEOUT']
+end
+```
+
+## Usage
+
+```ruby
+require 'cubesmart'
+
+sitemap = CubeSmart::Facility.sitemap
+sitemap.links.each do |link|
+  url = link.loc
+  facility = CubeSmart::Facility.fetch(url:)
+
+  puts facility.text
+
+  facility.prices.each do |price|
+    puts price.text
+  end
+
+  puts
+end
+```
+
+## CLI
+
+```bash
+cubesmart crawl
+```

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'cubesmart'
+
+# 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.
+
+require 'irb'
+IRB.start(__FILE__)

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/exe/cubesmart

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'cubesmart'
+
+cli = CubeSmart::CLI.new
+cli.parse

data/lib/cubesmart/address.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # The address (street + city + state + zip) of a facility.
+  class Address
+    # @attribute [rw] street
+    #   @return [String]
+    attr_accessor :street
+
+    # @attribute [rw] city
+    #   @return [String]
+    attr_accessor :city
+
+    # @attribute [rw] state
+    #   @return [String]
+    attr_accessor :state
+
+    # @attribute [rw] zip
+    #   @return [String]
+    attr_accessor :zip
+
+    # @param street [String]
+    # @param city [String]
+    # @param state [String]
+    # @param zip [String]
+    def initialize(street:, city:, state:, zip:)
+      @street = street
+      @city = city
+      @state = state
+      @zip = zip
+    end
+
+    # @return [String]
+    def inspect
+      props = [
+        "street=#{@street.inspect}",
+        "city=#{@city.inspect}",
+        "state=#{@state.inspect}",
+        "zip=#{@zip.inspect}"
+      ]
+      "#<#{self.class.name} #{props.join(' ')}>"
+    end
+
+    # @return [String]
+    def text
+      "#{street}, #{city}, #{state} #{zip}"
+    end
+
+    # @param data [Hash]
+    #
+    # @return [Address]
+    def self.parse(data:)
+      lines = %w[line1 line2 line3 line4].map { |key| data[key] }
+
+      new(
+        street: lines.compact.reject(&:empty?).join(' '),
+        city: data['city'],
+        state: data['stateName'],
+        zip: data['postalCode']
+      )
+    end
+  end
+end

data/lib/cubesmart/cli.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module CubeSmart
+  # Used when interacting with the library from the command line interface (CLI).
+  #
+  # Usage:
+  #
+  #   cli = CubeSmart::CLI.new
+  #   cli.parse
+  class CLI
+    module Code
+      OK = 0
+      ERROR = 1
+    end
+
+    # @param argv [Array<String>]
+    def parse(argv = ARGV)
+      parser.parse!(argv)
+      command = argv.shift
+
+      case command
+      when 'crawl' then crawl
+      else
+        warn("unsupported command=#{command.inspect}")
+        exit(Code::ERROR)
+      end
+    end
+
+    private
+
+    def crawl
+      CubeSmart::Facility.crawl
+      exit(Code::OK)
+    end
+
+    def help(options)
+      puts(options)
+      exit(Code::OK)
+    end
+
+    def version
+      puts(VERSION)
+      exit(Code::OK)
+    end
+
+    # @return [OptionParser]
+    def parser
+      OptionParser.new do |options|
+        options.banner = 'usage: cubesmart [options] <command> [<args>]'
+
+        options.on('-h', '--help', 'help') { help(options) }
+        options.on('-v', '--version', 'version') { version }
+      end
+    end
+  end
+end

data/lib/cubesmart/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # The core configuration.
+  class Config
+    # @attribute [rw] user_agent
+    #   @return [String]
+    attr_accessor :user_agent
+
+    # @attribute [rw] timeout
+    #   @return [Integer]
+    attr_accessor :timeout
+
+    def initialize
+      @user_agent = ENV.fetch('CUBESMART_USER_AGENT', "cubesmart.rb/#{VERSION}")
+      @timeout = Integer(ENV.fetch('CUBESMART_TIMEOUT', 60))
+    end
+  end
+end

data/lib/cubesmart/crawler.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # Used to fetch and parse either HTML or XML via a URL.
+  class Crawler
+    HOST = 'https://www.cubesmart.com'
+
+    # Raised for unexpected HTTP responses.
+    class FetchError < StandardError
+      # @param url [String]
+      # @param response [HTTP::Response]
+      def initialize(url:, response:)
+        super("url=#{url} status=#{response.status.inspect} body=#{String(response.body).inspect}")
+      end
+    end
+
+    # @param url [String]
+    # @raise [FetchError]
+    # @return [Nokogiri::HTML::Document]
+    def self.html(url:)
+      new.html(url:)
+    end
+
+    # @param url [String]
+    # @raise [FetchError]
+    # @return [Nokogiri::XML::Document]
+    def self.xml(url:)
+      new.xml(url:)
+    end
+
+    # @return [HTTP::Client]
+    def connection
+      @connection ||= begin
+        config = CubeSmart.config
+
+        connection = HTTP.persistent(HOST)
+        connection = connection.headers('User-Agent' => config.user_agent) if config.user_agent
+        connection = connection.timeout(config.timeout) if config.timeout
+        connection
+      end
+    end
+
+    # @param url [String]
+    # @return [HTTP::Response]
+    def fetch(url:)
+      response = connection.get(url)
+      raise FetchError.new(url:, response: response.flush) unless response.status.ok?
+
+      response
+    end
+
+    # @param url [String]
+    # @raise [FetchError]
+    # @return [Nokogiri::XML::Document]
+    def html(url:)
+      Nokogiri::HTML(String(fetch(url:).body))
+    end
+
+    # @param url [String]
+    # @raise [FetchError]
+    # @return [Nokogiri::XML::Document]
+    def xml(url:)
+      Nokogiri::XML(String(fetch(url:).body))
+    end
+  end
+end

data/lib/cubesmart/dimensions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # The dimensions (width + depth + sqft) of a price.
+  class Dimensions
+    # @attribute [rw] depth
+    #   @return [Integer]
+    attr_accessor :depth
+
+    # @attribute [rw] width
+    #  @return [Integer]
+    attr_accessor :width
+
+    # @attribute [rw] sqft
+    #   @return [Integer]
+    attr_accessor :sqft
+
+    # @param depth [Integer]
+    # @param width [Integer]
+    # @param sqft [Integer]
+    def initialize(depth:, width:, sqft:)
+      @depth = depth
+      @width = width
+      @sqft = sqft
+    end
+
+    # @return [String]
+    def inspect
+      props = [
+        "depth=#{@depth.inspect}",
+        "width=#{@width.inspect}",
+        "sqft=#{@sqft.inspect}"
+      ]
+      "#<#{self.class.name} #{props.join(' ')}>"
+    end
+
+    # @return [String] e.g. "10' × 10' (100 sqft)"
+    def text
+      "#{format('%g', @width)}' × #{format('%g', @depth)}' (#{@sqft} sqft)"
+    end
+
+    # @param data [Hash]
+    #
+    # @return [Dimensions]
+    def self.parse(data:)
+      new(depth: data['depth'], width: data['width'], sqft: data['squareFoot'])
+    end
+  end
+end

data/lib/cubesmart/facility.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # A facility (address + geocode + prices) on cubesmart.com.
+  #
+  # e.g. https://www.cubesmart.com/arizona-self-storage/chandler-self-storage/2.html
+  class Facility
+    class ParseError < StandardError; end
+
+    SITEMAP_URL = 'https://www.cubesmart.com/sitemap-facility.xml'
+
+    ID_REGEX = /(?<id>\d+)\.html/
+
+    # @attribute [rw] id
+    #   @return [String]
+    attr_accessor :id
+
+    # @attribute [rw] name
+    #   @return [String]
+    attr_accessor :name
+
+    # @attribute [rw] address
+    #   @return [Address]
+    attr_accessor :address
+
+    # @attribute [rw] geocode
+    #   @return [Geocode]
+    attr_accessor :geocode
+
+    # @attribute [rw] prices
+    #   @return [Array<Price>]
+    attr_accessor :prices
+
+    # @return [Sitemap]
+    def self.sitemap
+      Sitemap.fetch(url: SITEMAP_URL)
+    end
+
+    # @param url [String]
+    #
+    # @return [Facility]
+    def self.fetch(url:)
+      document = Crawler.html(url:)
+      parse(document:)
+    end
+
+    # @param document [Nokogiri::HTML::Document]
+    #
+    # @return [Facility]
+    def self.parse(document:)
+      data = parse_json_ld(document:)
+
+      id = data['url'].match(ID_REGEX)[:id]
+      name = data['name']
+      address = Address.parse(data: data['address'])
+      geocode = Geocode.parse(data: data['geo'])
+      prices = []
+
+      new(id:, name:, address:, geocode:, prices:)
+    end
+
+    # @param document [Nokogiri::HTML::Document]
+    #
+    # @raise [ParseError]
+    #
+    # @return [Hash]
+    def self.parse_json_ld(document:)
+      graph = JSON.parse(document.at_xpath('//script[contains(text(), "@graph")]').text)['@graph']
+      graph.find { |entry| entry['@type'] == 'SelfStorage' } || raise(ParseError, 'missing @graph')
+    end
+
+    def self.crawl
+      sitemap.links.each do |link|
+        url = link.loc
+
+        facility = fetch(url:)
+        puts facility.text
+
+        facility.prices.each do |price|
+          puts price.text
+        end
+
+        puts
+      end
+    end
+
+    # @param id [String]
+    # @param name [String]
+    # @param address [Address]
+    # @param geocode [Geocode]
+    # @param prices [Array<Price>]
+    def initialize(id:, name:, address:, geocode:, prices:)
+      @id = id
+      @name = name
+      @address = address
+      @geocode = geocode
+      @prices = prices
+    end
+
+    # @return [String]
+    def inspect
+      props = [
+        "id=#{@id.inspect}",
+        "address=#{@address.inspect}",
+        "geocode=#{@geocode.inspect}",
+        "prices=#{@prices.inspect}"
+      ]
+      "#<#{self.class.name} #{props.join(' ')}>"
+    end
+
+    # @return [String]
+    def text
+      "#{@id} | #{@name} | #{@address.text} | #{@geocode.text}"
+    end
+  end
+end

data/lib/cubesmart/geocode.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # The geocode (latitude + longitude) of a facility.
+  class Geocode
+    # @attribute [rw] latitude
+    #   @return [Float]
+    attr_accessor :latitude
+
+    # @attribute [rw] longitude
+    #   @return [Float]
+    attr_accessor :longitude
+
+    # @param latitude [Float]
+    # @param longitude [Float]
+    def initialize(latitude:, longitude:)
+      @latitude = latitude
+      @longitude = longitude
+    end
+
+    # @return [String]
+    def inspect
+      props = [
+        "latitude=#{@latitude.inspect}",
+        "longitude=#{@longitude.inspect}"
+      ]
+      "#<#{self.class.name} #{props.join(' ')}>"
+    end
+
+    # @return [String]
+    def text
+      "#{@latitude},#{@longitude}"
+    end
+
+    # @param data [Hash]
+    #
+    # @return [Geocode]
+    def self.parse(data:)
+      new(
+        latitude: data['latitude'],
+        longitude: data['longitude']
+      )
+    end
+  end
+end

data/lib/cubesmart/link.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # A link in a sitemap.
+  class Link
+    # @attribute [rw] loc
+    #   @return [String]
+    attr_accessor :loc
+
+    # @attribute [rw] lastmod
+    #   @return [Time]
+    attr_accessor :lastmod
+
+    # @param loc [String]
+    # @param lastmod [String]
+    def initialize(loc:, lastmod:)
+      @loc = loc
+      @lastmod = Time.parse(lastmod)
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} loc=#{@loc.inspect} lastmod=#{@lastmod.inspect}>"
+    end
+  end
+end

data/lib/cubesmart/price.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # The price (id + dimensions + rate) for a facility
+  class Price
+    # @attribute [rw] id
+    #   @return [String]
+    attr_accessor :id
+
+    # @attribute [rw] dimensions
+    #   @return [Dimensions]
+    attr_accessor :dimensions
+
+    # @attribute [rw] rates
+    #   @return [Rates]
+    attr_accessor :rates
+
+    # @param id [String]
+    # @param dimensions [Dimensions]
+    # @param rates [Rates]
+    def initialize(id:, dimensions:, rates:)
+      @id = id
+      @dimensions = dimensions
+      @rates = rates
+    end
+
+    # @return [String]
+    def inspect
+      props = [
+        "id=#{@id.inspect}",
+        "dimensions=#{@dimensions.inspect}",
+        "rates=#{@rates.inspect}"
+      ]
+      "#<#{self.class.name} #{props.join(' ')}>"
+    end
+
+    # @return [String] e.g. "123 | 5' × 5' (25 sqft) | $100 (street) / $90 (web)"
+    def text
+      "#{@id} | #{@dimensions.text} | #{@rates.text}"
+    end
+
+    # @param data [Hash]
+    #
+    # @return [Price]
+    def self.parse(data:)
+      dimensions = Dimensions.parse(data: data['dimensions'])
+      rates = Rates.parse(data: data['rates'])
+      new(
+        id: data['uid'],
+        dimensions: dimensions,
+        rates: rates
+      )
+    end
+  end
+end

data/lib/cubesmart/rates.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # The rates (street + web) for a facility
+  class Rates
+    # @attribute [rw] street
+    #   @return [Integer]
+    attr_accessor :street
+
+    # @attribute [rw] web
+    #   @return [Integer]
+    attr_accessor :web
+
+    # @param street [Integer]
+    # @param web [Integer]
+    def initialize(street:, web:)
+      @street = street
+      @web = web
+    end
+
+    # @return [String]
+    def inspect
+      props = [
+        "street=#{@street.inspect}",
+        "web=#{@web.inspect}"
+      ]
+      "#<#{self.class.name} #{props.join(' ')}>"
+    end
+
+    # @return [String] e.g. "$80 (street) | $60 (web)"
+    def text
+      "$#{@street} (street) | $#{@web} (web)"
+    end
+
+    # @param data [Hash]
+    #
+    # @return [Rates]
+    def self.parse(data:)
+      new(
+        street: data['street'],
+        web: data['web']
+      )
+    end
+  end
+end

data/lib/cubesmart/sitemap.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  # A sitemap on cubesmart.com.
+  #
+  # e.g. https://www.cubesmart.com/sitemap-facility.xml
+  class Sitemap
+    # @attribute [rw] links
+    #   @return [Array<Link>]
+    attr_accessor :links
+
+    # @param document [NokoGiri::XML::Document]
+    #
+    # @return [Sitemap]
+    def self.parse(document:)
+      links = document.xpath('//xmlns:url').map do |url|
+        loc = url.at_xpath('xmlns:loc')&.text
+        lastmod = url.at_xpath('xmlns:lastmod')&.text
+        Link.new(loc:, lastmod:)
+      end
+
+      new(links: links)
+    end
+
+    # @param url [String]
+    #
+    # @return [Sitemap]
+    def self.fetch(url:)
+      document = Crawler.xml(url:)
+      parse(document:)
+    end
+
+    # @param links [Array<Link>]
+    def initialize(links:)
+      @links = links
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} links=#{@links.inspect}>"
+    end
+  end
+end

data/lib/cubesmart/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CubeSmart
+  VERSION = '0.1.0'
+end

data/lib/cubesmart.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'http'
+require 'nokogiri'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect 'cubesmart' => 'CubeSmart'
+loader.inflector.inflect 'cli' => 'CLI'
+loader.setup
+
+# An interface for CubeSmart.
+module CubeSmart
+  class Error < StandardError; end
+
+  # @return [Config]
+  def self.config
+    @config ||= Config.new
+  end
+
+  # @yield [config]
+  # @yieldparam config [Config]
+  def self.configure
+    yield config
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: cubesmart
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kevin Sylvestre
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Uses HTTP.rb to scrape cubesmart.com.
+email:
+- kevin@ksylvest.com
+executables:
+- cubesmart
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- bin/console
+- bin/setup
+- exe/cubesmart
+- lib/cubesmart.rb
+- lib/cubesmart/address.rb
+- lib/cubesmart/cli.rb
+- lib/cubesmart/config.rb
+- lib/cubesmart/crawler.rb
+- lib/cubesmart/dimensions.rb
+- lib/cubesmart/facility.rb
+- lib/cubesmart/geocode.rb
+- lib/cubesmart/link.rb
+- lib/cubesmart/price.rb
+- lib/cubesmart/rates.rb
+- lib/cubesmart/sitemap.rb
+- lib/cubesmart/version.rb
+homepage: https://github.com/ksylvest/cubesmart
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/ksylvest/cubesmart
+  source_code_uri: https://github.com/ksylvest/cubesmart
+  changelog_uri: https://github.com/ksylvest/cubesmart
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A crawler for CubeSmart.
+test_files: []