jservice 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f53336cab276a74062a123630cc3103f5742aa1d079312b2a2930d01f9141df3
+  data.tar.gz: 7d06d26403e0c67b131ffad3161e21d49b3c65e0e0151bfe1bc27723e6006862
+SHA512:
+  metadata.gz: 1d89290313cf883e68e32da4637a860c07a8dc24687a2957d2b4852cc813c9314c3c3cbc3194afc2b27406a6ba58d101790ec44b15625221eca5ef9d35073adb
+  data.tar.gz: 175a528755c07a062780da3a46d33baa09ceeca8541a2435b08a94433d6a3e2a24558b6eb7e870803d866ad2cd283e06bf6156ea1b24e32f6dcd4b82ef295c2c

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-03-09
+
+- Initial release

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in jservice.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -0,0 +1,57 @@
+PATH
+  remote: .
+  specs:
+    jservice (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    json (2.6.3)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.2)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.44.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.4.2)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  jservice!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.3.7

data/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2023 Alex Craik.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,125 @@
+# Jservice
+
+This gem provides bindings to the HTTP REST API hosted at [jService](https://jservice.io). This is a simple 1 to 1 API binding, nothing extra like caching is provided.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jservice'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install jservice
+
+## Usage
+
+### 1. Create Jservice class
+```ruby
+js = Jservice.new(
+  # base URL of API
+  url: 'jservice.io',
+  # use https
+  use_ssl: true,
+  # port to use for API (`nil` for default)
+  port: nil
+)
+```
+All hash options are optional and will use the default values if not given. 99% of the time, you just want `Jservice.new()`.
+
+### 2. Get a page of clues
+```ruby
+clues = js.clues(
+  # value of clue (100-1000 or nil for Final Jeopardy)
+  value: 100,
+  # ID of category you want
+  # you'll likely want to use `categories` to find these
+  category: 0,
+  # specify a range of dates for clues
+  min_date: "1993-11-17T20:00:00.000Z"
+  max_date: "1993-11-20T20:00:00.000Z"
+  # offset of returned clues. used for paginating results
+  offset: 0
+)
+```
+`Jservice#clues` returns an array of clue objects as Hashes (with String keys.) As before, all options are optional and if not given the server will use whatever defaults. The clues are returned in a fixed order (evidently most recently added to the database.)
+
+Example clue output (JSON):
+
+```json
+{
+  "id": 35885,
+  "answer": "Madagascar",
+  "question": "Extinct for hundreds of years, the elephant bird weighed 1,000 pounds & lived on this east African island",
+  "value": 500,
+  "airdate": "1993-11-17T20:00:00.000Z",
+  "created_at": "2022-12-30T18:52:26.957Z",
+  "updated_at": "2022-12-30T18:52:26.957Z",
+  "category_id": 109,
+  "game_id": 1411,
+  "invalid_count": null,
+  "category": {
+    "id": 109,
+    "title": "animals",
+    "created_at": "2022-12-30T18:37:49.289Z",
+    "updated_at": "2022-12-30T18:37:49.289Z",
+    "clues_count": 536
+  }
+}
+```
+
+### 3. Get random clues
+```ruby
+clues = js.random_clues(5)
+```
+`Jservice#random_clues` returns `count` random clues from the API. Notably, this endpoint does **not** support any kind of search parameters.
+
+### 4. Get random Final Jeopardies
+```ruby
+clues = js.random_finals(5)
+```
+`Jservice#random_finals` returns `count` random Final Jeopardies from the API.
+Notably, this endpoint does **not** support any kind of search parameters.
+
+### 5. Get a list of categories
+```ruby
+cats = js.categories(
+  # number of categories
+  count: 1,
+  # offset of returned categories. used for paginating results
+  offset: 0
+)
+```
+`Jservice#categories` is similar to `clues`. It returns a list of categories from the server (seemingly in most-recently-added order.) Both options are optional.
+
+Category object example (JSON):
+
+```json
+{
+  "id":68,
+  "title": "gardens",
+  "clues_count": 18
+}
+```
+
+### 6. Get a specific category by ID
+```ruby
+cat = js.category(68)
+```
+`Jservice#category` returns a specific category given its ID
+
+## 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/ajc2/jservice-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/lib/jservice/version.rb

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+class Jservice
+  VERSION = "1.0.0"
+end

data/lib/jservice.rb

@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+require_relative "jservice/version"
+
+class Jservice
+  class Error < StandardError; end
+
+  def initialize(**config)
+    @config = {
+      # base URL of API
+      url: 'jservice.io',
+      # use https
+      use_ssl: true,
+      # port to use for API (`nil` for default)
+      port: nil,
+      # ignore clues above the given invalid_count (`nil` ignored)
+      invalid_filter: nil
+    }
+    @config.merge!(config)
+    @config[:port] ||= @config[:use_ssl] ? 443 : 80
+
+    @http = Net::HTTP.new(@config[:url], @config[:port])
+    @http.use_ssl = @config[:use_ssl]
+    @http.start()
+  end
+
+  # request a page of clues
+  # = options =
+  #    value ( int): the value of the clue in dollars
+  # category ( int): the id of the category you want to return
+  # min_date (date): earliest date to show, based on original air date
+  # max_date (date): latest date to show, based on original air date
+  #   offset ( int): offsets the returned clues. Useful in pagination
+  def clues(**options)
+    # validate input
+    filter_keys(options, :value, :category, :min_date, :max_date, :offset, :page)
+    
+    result = nil
+    begin
+      result = api_request('clues', options)
+    rescue ex
+      raise ex
+    else
+      return result
+    end
+  end
+  
+  # request random clues
+  # count: number of clues to return
+  def random_clues(count = 1)
+    result = nil
+    begin
+      result = api_request('random', count: count)
+    rescue ex
+      raise ex
+    else
+      return result
+    end
+  end
+  
+  # request random final jeopardy clues
+  # count: number of clues to return
+  def random_finals(count = 1)
+    result = nil
+    begin
+      result = api_request('final', count: count)
+    rescue ex
+      raise ex
+    else
+      return result
+    end
+  end
+  
+  # request a list/page of categories
+  # = options =
+  #  count (int): amount of categories to return, limited to 100 at a time
+  # offset (int): offsets the starting id of categories returned. Useful in pagination.
+  def categories(**options)
+    # validate input
+    filter_keys(options, :count, :offset)
+    
+    result = nil
+    begin
+      result = api_request('categories', options)
+    rescue ex
+      raise ex
+    else
+      return result
+    end
+  end
+  
+  # request a specific category
+  # id: integer ID of category
+  def category(id)
+    result = nil
+    begin
+      result = api_request('category', id: id)
+    rescue ex
+      raise ex
+    else
+      return result
+    end
+  end
+  
+
+  private def filter_keys(options, *keys)
+    bad_keys = options.except(*keys).keys
+    unless bad_keys.empty?
+      # build error message
+      msg = "Unrecognized options: #{bad_keys.join(', ')}"
+      raise Jservice::Error.new(msg)
+    end
+  end
+  
+  private def api_request(endpoint, options)
+    uri_hash = {
+      host: @config[:url],
+      path: "/api/#{endpoint}",
+      port: @config[:port],
+      query: URI.encode_www_form(options)
+    }
+    uri = nil
+    if @config[:use_ssl]
+      uri = URI::HTTPS.build(uri_hash)
+    else
+      uri = URI::HTTP.build(uri_hash)
+    end
+    
+    req = @http.get(uri)
+  
+    unless req.code == '200'
+      raise Jservice::Error.new("HTTP response #{req.code}")
+    end
+    
+    JSON.parse(req.body)
+  end
+end

data/sig/jservice.rbs

@@ -0,0 +1,4 @@
+module Jservice
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: jservice
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alex Craik
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-01-25 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- contact@ajc2.xyz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- lib/jservice.rb
+- lib/jservice/version.rb
+- sig/jservice.rbs
+homepage: https://github.com/ajc2/jservice-gem
+licenses:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://github.com/ajc2/jservice-gem
+  source_code_uri: https://github.com/ajc2/jservice-gem
+  changelog_uri: https://github.com/ajc2/jservice-gem
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Bindings to the jService REST API for Jeopardy questions.
+test_files: []