holidays-rest 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0dac7d315f912c59e080ba784b8cf3e468843d3899d7a3f6a9172f20775f649
+  data.tar.gz: 153118ea22cada7f0e902ed77f024c7ca7b3cd7fa6b08309beea5a204a30e4dc
+SHA512:
+  metadata.gz: 5937099897ea4b539d0c5a0529009f93685c3d5b87bc31b3e67da8977c5b9d082e869312afcccf7b67f9310549aa93ac89ae2a2d77dbd0a134e785ac01b07c0c
+  data.tar.gz: bea79bf17ce3e3b2872b76c76e0c6f3265b848e91b195b96968675a19c2e3b4b9d8767435f516fdac1e9b1cd5d26ced856418b4865908d8a9c070cb2e6544b80

data/README.md

@@ -0,0 +1,170 @@
+# holidays.rest Ruby SDK
+
+Official Ruby SDK for the [holidays.rest](https://www.holidays.rest) API.
+
+## Requirements
+
+- Ruby 3.2+
+- Zero runtime dependencies — uses only the standard library (`net/http`, `json`, `uri`)
+
+## Installation
+
+```bash
+gem install holidays-rest
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "holidays-rest"
+```
+
+## Quick Start
+
+```ruby
+require "holidays_rest"
+
+client = HolidaysRest::Client.new(api_key: "YOUR_API_KEY")
+
+holidays = client.holidays(country: "US", year: 2024)
+holidays.each { |h| puts "#{h.date} — #{h.name}" }
+```
+
+Get an API key at [holidays.rest/dashboard](https://www.holidays.rest/dashboard).
+
+---
+
+## API
+
+### `HolidaysRest::Client.new`
+
+```ruby
+client = HolidaysRest::Client.new(
+  api_key:      "YOUR_API_KEY",   # required
+  open_timeout: 5,                # optional, default 5s
+  read_timeout: 15,               # optional, default 15s
+  base_url:     "https://..."     # optional, override for testing
+)
+```
+
+---
+
+### `client.holidays(...)` → `Array<Holiday>`
+
+| Parameter  | Type                  | Required | Description                                      |
+|------------|-----------------------|----------|--------------------------------------------------|
+| `country`  | `String`              | yes      | ISO 3166 alpha-2 code (e.g. `"US"`)              |
+| `year`     | `Integer \| String`   | yes      | Four-digit year (e.g. `2024`)                    |
+| `month`    | `Integer \| String`   | no       | Month filter (1–12)                              |
+| `day`      | `Integer \| String`   | no       | Day filter (1–31)                                |
+| `type`     | `String \| Array`     | no       | `"religious"`, `"national"`, `"local"`           |
+| `religion` | `Integer \| Array`    | no       | Religion code(s) 1–11                            |
+| `region`   | `String \| Array`     | no       | Subdivision code(s) — from `#country`            |
+| `lang`     | `String \| Array`     | no       | Language code(s) — from `#languages`             |
+| `response` | `String`              | no       | `"json"` (default) \| `"xml"` \| `"yaml"` \| `"csv"` |
+
+```ruby
+# All US holidays in 2024
+client.holidays(country: "US", year: 2024)
+
+# National holidays only
+client.holidays(country: "DE", year: 2024, type: "national")
+
+# Multiple types
+client.holidays(country: "TR", year: 2024, type: ["national", "religious"])
+
+# Filter by month and day
+client.holidays(country: "GB", year: 2024, month: 12, day: 25)
+
+# Specific region
+client.holidays(country: "US", year: 2024, region: "US-CA")
+
+# Multiple regions
+client.holidays(country: "US", year: 2024, region: ["US-CA", "US-NY"])
+```
+
+---
+
+### `client.countries` → `Array<Country>`
+
+```ruby
+client.countries.each { |c| puts "#{c.alpha2} — #{c.name}" }
+```
+
+---
+
+### `client.country(country_code)` → `Country`
+
+Returns country details including subdivision codes usable as `region:` filters.
+
+```ruby
+us = client.country("US")
+us.subdivisions.each { |s| puts "#{s.code} — #{s.name}" }
+```
+
+---
+
+### `client.languages` → `Array<Language>`
+
+```ruby
+client.languages.each { |l| puts "#{l.code} — #{l.name}" }
+```
+
+---
+
+## Models
+
+All responses are deserialized into immutable `Data` objects.
+
+```ruby
+Holiday
+  .country_code   # String   — ISO 3166 alpha-2, e.g. "DE"
+  .country_name   # String   — e.g. "Germany"
+  .date           # String   — ISO 8601, e.g. "2026-01-01"
+  .name           # Hash     — language code => name, e.g. { "en" => "New Year's Day" }
+  .is_national    # Boolean
+  .is_religious   # Boolean
+  .is_local       # Boolean
+  .is_estimate    # Boolean
+  .day            # HolidayDay
+  .religion       # String   — e.g. "Christianity", or "" if not applicable
+  .regions        # Array<String> — subdivision codes, e.g. ["BW", "BY"]
+
+HolidayDay
+  .actual         # String   — day of week the holiday actually falls on
+  .observed       # String   — day of week the holiday is observed
+
+Country         # .name, .alpha2, .subdivisions → Array<Subdivision>
+Subdivision     # .code, .name
+Language        # .code, .name
+```
+
+---
+
+## Error Handling
+
+Non-2xx responses raise `HolidaysRest::ApiError`:
+
+```ruby
+begin
+  client.holidays(country: "US", year: 2024)
+rescue HolidaysRest::ApiError => e
+  puts e.status_code   # HTTP status code (Integer)
+  puts e.message       # Error message (String)
+  puts e.body          # Raw response body (String)
+end
+```
+
+| Status | Meaning             |
+|--------|---------------------|
+| 400    | Bad request         |
+| 401    | Invalid API key     |
+| 404    | Not found           |
+| 500    | Server error        |
+| 503    | Service unavailable |
+
+---
+
+## License
+
+MIT

data/holidays-rest.gemspec

@@ -0,0 +1,24 @@
+require_relative "lib/holidays_rest/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "holidays-rest"
+  spec.version     = HolidaysRest::VERSION
+  spec.authors     = ["msdundar"]
+  spec.summary     = "Official Ruby SDK for the holidays.rest API"
+  spec.description = "Fetch public holidays by country, year, region, type, and more."
+  spec.homepage    = "https://www.holidays.rest"
+  spec.license     = "MIT"
+
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/holidays-rest/sdk-ruby"
+  spec.metadata["documentation_uri"] = "https://docs.holidays.rest"
+
+  spec.files = Dir["lib/**/*.rb", "README.md", "holidays-rest.gemspec"]
+
+  # Zero runtime dependencies — uses only Ruby stdlib (net/http, json, uri)
+
+  spec.add_development_dependency "minitest", "~> 5"
+  spec.add_development_dependency "webmock",  "~> 3"
+end

data/lib/holidays_rest/client.rb

@@ -0,0 +1,109 @@
+require "json"
+require "net/http"
+require "uri"
+
+module HolidaysRest
+  class Client
+    BASE_URL = "https://api.holidays.rest/v1"
+
+    # @param api_key [String] Bearer token from https://www.holidays.rest/dashboard
+    # @param base_url [String] Override base URL (useful for testing)
+    # @param open_timeout [Integer] Seconds to wait for connection (default 5)
+    # @param read_timeout [Integer] Seconds to wait for response (default 15)
+    def initialize(api_key:, base_url: BASE_URL, open_timeout: 5, read_timeout: 15)
+      raise ArgumentError, "api_key must not be empty" if api_key.nil? || api_key.empty?
+
+      @api_key      = api_key
+      @base_url     = base_url.chomp("/")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Fetch public holidays.
+    #
+    # @param country [String] ISO 3166 alpha-2 code, e.g. "US"  (required)
+    # @param year    [Integer, String]  Four-digit year          (required)
+    # @param month   [Integer, String]  1–12                     (optional)
+    # @param day     [Integer, String]  1–31                     (optional)
+    # @param type    [String, Array<String>]  "religious", "national", "local"
+    # @param religion [Integer, Array<Integer>]  Religion code(s) 1–11
+    # @param region  [String, Array<String>]  Subdivision code(s)
+    # @param lang    [String, Array<String>]  Language code(s)
+    # @param response [String] "json" | "xml" | "yaml" | "csv"
+    # @return [Array<Holiday>]
+    def holidays(country:, year:, month: nil, day: nil, type: nil,
+                 religion: nil, region: nil, lang: nil, response: nil)
+      params = build_params(
+        country:  country,
+        year:     year,
+        month:    month,
+        day:      day,
+        type:     type,
+        religion: religion,
+        region:   region,
+        lang:     lang,
+        response: response
+      )
+      get("/holidays", params).map { Holiday.from_hash(_1) }
+    end
+
+    # Return all supported countries.
+    # @return [Array<Country>]
+    def countries
+      get("/countries", {}).map { Country.from_hash(_1) }
+    end
+
+    # Return details for one country, including subdivision codes.
+    # @param country_code [String] ISO 3166 alpha-2 code, e.g. "US"
+    # @return [Country]
+    def country(country_code)
+      raise ArgumentError, "country_code must not be empty" if country_code.nil? || country_code.empty?
+
+      Country.from_hash(get("/country/#{URI.encode_uri_component(country_code)}", {}))
+    end
+
+    # Return all supported language codes.
+    # @return [Array<Language>]
+    def languages
+      get("/languages", {}).map { Language.from_hash(_1) }
+    end
+
+    private
+
+    def build_params(**kwargs)
+      kwargs.each_with_object({}) do |(key, value), out|
+        next if value.nil?
+
+        out[key] = value.is_a?(Array) ? value.join(",") : value.to_s
+      end
+    end
+
+    def get(path, params)
+      uri = URI("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      request = Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"]        = "application/json"
+
+      response = http.request(request)
+      body     = response.body
+
+      unless response.is_a?(Net::HTTPSuccess)
+        message = begin
+          JSON.parse(body).fetch("message", response.message)
+        rescue JSON::ParserError
+          response.message
+        end
+        raise ApiError.new(message, response.code.to_i, body)
+      end
+
+      JSON.parse(body)
+    end
+  end
+end

data/lib/holidays_rest/errors.rb

@@ -0,0 +1,15 @@
+module HolidaysRest
+  class ApiError < StandardError
+    attr_reader :status_code, :body
+
+    def initialize(message, status_code, body)
+      super(message)
+      @status_code = status_code
+      @body = body
+    end
+
+    def inspect
+      "#<HolidaysRest::ApiError status_code=#{@status_code} message=#{message.inspect}>"
+    end
+  end
+end

data/lib/holidays_rest/models.rb

@@ -0,0 +1,52 @@
+module HolidaysRest
+  HolidayDay = Data.define(:actual, :observed) do
+    def self.from_hash(h)
+      new(
+        actual:   h.fetch("actual", ""),
+        observed: h.fetch("observed", "")
+      )
+    end
+  end
+
+  Holiday = Data.define(:country_code, :country_name, :date, :name,
+                        :is_national, :is_religious, :is_local, :is_estimate,
+                        :day, :religion, :regions) do
+    def self.from_hash(h)
+      new(
+        country_code: h.fetch("country_code", ""),
+        country_name: h.fetch("country_name", ""),
+        date:         h.fetch("date", ""),
+        name:         h.fetch("name", {}),
+        is_national:  h.fetch("isNational", false),
+        is_religious: h.fetch("isReligious", false),
+        is_local:     h.fetch("isLocal", false),
+        is_estimate:  h.fetch("isEstimate", false),
+        day:          HolidayDay.from_hash(h.fetch("day", {})),
+        religion:     h.fetch("religion", ""),
+        regions:      Array(h["regions"])
+      )
+    end
+  end
+
+  Subdivision = Data.define(:code, :name) do
+    def self.from_hash(h)
+      new(code: h.fetch("code", ""), name: h.fetch("name", ""))
+    end
+  end
+
+  Country = Data.define(:name, :alpha2, :subdivisions) do
+    def self.from_hash(h)
+      new(
+        name:         h.fetch("name", ""),
+        alpha2:       h.fetch("alpha2", ""),
+        subdivisions: Array(h["subdivisions"]).map { Subdivision.from_hash(_1) }
+      )
+    end
+  end
+
+  Language = Data.define(:code, :name) do
+    def self.from_hash(h)
+      new(code: h.fetch("code", ""), name: h.fetch("name", ""))
+    end
+  end
+end

data/lib/holidays_rest/version.rb

@@ -0,0 +1,3 @@
+module HolidaysRest
+  VERSION = "1.0.0"
+end

data/lib/holidays_rest.rb

@@ -0,0 +1,9 @@
+require_relative "holidays_rest/version"
+require_relative "holidays_rest/errors"
+require_relative "holidays_rest/models"
+require_relative "holidays_rest/client"
+
+# holidays.rest Ruby SDK
+# https://docs.holidays.rest
+module HolidaysRest
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: holidays-rest
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- msdundar
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Fetch public holidays by country, year, region, type, and more.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- holidays-rest.gemspec
+- lib/holidays_rest.rb
+- lib/holidays_rest/client.rb
+- lib/holidays_rest/errors.rb
+- lib/holidays_rest/models.rb
+- lib/holidays_rest/version.rb
+homepage: https://www.holidays.rest
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.holidays.rest
+  source_code_uri: https://github.com/holidays-rest/sdk-ruby
+  documentation_uri: https://docs.holidays.rest
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby SDK for the holidays.rest API
+test_files: []