trmnl-api 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dedac6b2c46579d646be122b295be973bb3c39bbc35847da48d77f9ce2f506ae
-  data.tar.gz: dd7ec7571e0c2cc0f74c67bfc78c4e157b8590a8736913102e582959a85f920c
+  metadata.gz: 31b74fda2dfe3464acf9af9f49d56fd0836170d300229e32f46bbe3b468042ef
+  data.tar.gz: ce20f646705190666a4b1e59f04afafc94349e5099bad69b5392f015b26dccff
 SHA512:
-  metadata.gz: 4b18624c8fb2ec5c395a58824691d5da9a1495f8bc26fe41f1119de67cde3aa6d1d2ef4657a72a490e74db51343c7aceea5930887624cdb5c9ae3a7e1fb46f65
-  data.tar.gz: 91c83467a642383c7edf9ed5decd35b9514fbf45382a9574e39e4510dc48ac748bc70ae0cec6a218fa312652268968826cd2c65c216015d589564a6cd64c07dc
+  metadata.gz: d51252433f8303f6c47d26dec1db210304086a90a3feb2de6470cee096cb223e08817c937de85ee3ccd202dd84cec6c5de1093841be805b58b9d4c3f9e53d250
+  data.tar.gz: 8633a2468b9397c236a15f3a531a256c414bfae4f1187b76916f9de150e394c2b10363ed6a7f3779fe5c112f23846bacfaec1e789367a17a5f36f43f64010a08

data/README.adoc

@@ -62,13 +62,17 @@ See xref:_endpoints[Endpoints] for further details.
 
 === Configuration
 
-By default, you shouldn't need to change the default configuration but you can always use a block to adjust settings as desired. If you don't configure the client, then the following defaults will be used:
+By default, you shouldn't need to change the default configuration but you can use a block to adjust settings as desired. If you don't configure the client, then the following defaults will be used:
 
 [source,ruby]
 ----
 client = TRMNL::API.new do |settings|
   settings.content_type = "application/json",
+  settings.timeout_connect = 2
+  settings.timeout_read = 10
+  settings.timeout_write = 10
   settings.uri = "https://trmnl.app/api"
+  settings.user_agent = "TRMNL API"
 end
 ----
 
@@ -77,7 +81,11 @@ end
 You can configure the client via the following environment variables:
 
 * `TRMNL_API_CONTENT_TYPE`: Defines the HTTP `Content-Type` header. You shouldn't need to change this but is here if you need it. Default: `"application/json"`.
+* `TRMNL_API_TIMEOUT_CONNECT`: Defines the time, in seconds, for establishing a connection. Default: `2`.
+* `TRMNL_API_TIMEOUT_READ`: Defines the time, in seconds, for reading content. Default: `10`.
+* `TRMNL_API_TIMEOUT_WRITE`: Defines the time, in seconds, for writing content. Default: `10`.
 * `TRMNL_API_URI`: Defines the API URI. Default: `"https://trmnl.app/api"`.
+* `TRMNL_API_USER_AGENT`: Defines the HTTP `User-Agent` header. You shouldn't need to change this but is here if you need need to customize this for upstream application identification. Default: `"TRMNL API"`. The fully computed user agent ends up being: `"http.rb/6.0.0 (TRMNL API)"` (only the value in parenthesis is configurable).
 
 Any/all environment changes will be applied unless you override these settings via the client configuration block shown above.
 
@@ -143,18 +151,6 @@ client.display token: "secret"
 # )
 ----
 
-==== Firmware
-
-Allows you to obtain the current stable firmware version. Example:
-
-[source,ruby]
-----
-client = TRMNL::API.new
-client.firmware
-
-# Success(#<data TRMNL::API::Models::Firmware url="https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin", version="1.4.8">)
-----
-
 ==== IP Addresses
 
 Allows you obtain a list of public IP addresses for all TRMNL core servers because plugin poll requests will only originate from these IPs. Example:
@@ -178,6 +174,22 @@ client.ip_addresses
 # )
 ----
 
+==== Latest Firmware
+
+Allows you to obtain the latest stable firmware version. Example:
+
+[source,ruby]
+----
+client = TRMNL::API.new
+client.latest_firmware
+
+# Success(
+#   #<data TRMNL::API::Models::LatestFirmware
+#          url="https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin",
+#          version="1.4.8">
+# )
+----
+
 ==== Log
 
 Allows you to create a log entry (which is what the device reports when it captures an error). You must supply your device's API token as the `token`. Example:

data/lib/trmnl/api/client.rb

@@ -13,8 +13,8 @@ module TRMNL
         categories: Endpoints::Category,
         current_screen: Endpoints::CurrentScreen,
         display: Endpoints::Display,
-        firmware: Endpoints::Firmware,
         ip_addresses: Endpoints::IPAddress,
+        latest_firmware: Endpoints::LatestFirmware,
         log: Endpoints::Log,
         models: Endpoints::Model,
         palettes: Endpoints::Palette,
@@ -40,10 +40,10 @@ module TRMNL
 
       def display(**) = endpoints.fetch(__method__).call(**)
 
-      def firmware = endpoints.fetch(__method__).call
-
       def ip_addresses = endpoints.fetch(__method__).call
 
+      def latest_firmware = endpoints.fetch(__method__).call
+
       def log(**) = endpoints.fetch(__method__).call(**)
 
       def models(**) = endpoints.fetch(__method__).call(**)

data/lib/trmnl/api/configuration/content.rb

@@ -1,11 +1,25 @@
 # frozen_string_literal: true
 
+require "http"
+
 module TRMNL
   module API
     module Configuration
       # Provides API client configuration content.
-      Content = Struct.new :content_type, :uri do
-        def headers = {"Content-Type" => content_type}.compact
+      Content = Struct.new(
+        :content_type,
+        :timeout_connect,
+        :timeout_read,
+        :timeout_write,
+        :uri,
+        :user_agent
+      ) do
+        def headers
+          agent = " (#{user_agent})" if user_agent
+          {content_type: content_type, user_agent: "http.rb/#{HTTP::VERSION}#{agent}"}.compact
+        end
+
+        def timeout = {connect: timeout_connect, read: timeout_read, write: timeout_write}
       end
     end
   end

data/lib/trmnl/api/configuration/loader.rb

@@ -13,13 +13,21 @@ module TRMNL
         def call
           model[
             content_type: environment.fetch("TRMNL_API_CONTENT_TYPE", "application/json"),
-            uri: environment.fetch("TRMNL_API_URI", "https://trmnl.com/api")
+            timeout_connect: environment.fetch("TRMNL_API_TIMEOUT_CONNECT", 2).to_i,
+            timeout_read: environment.fetch("TRMNL_API_TIMEOUT_READ", 10).to_i,
+            timeout_write: environment.fetch("TRMNL_API_TIMEOUT_WRITE", 10).to_i,
+            uri: environment.fetch("TRMNL_API_URI", "https://trmnl.com/api"),
+            user_agent: "http.rb/#{HTTP::VERSION} (#{default_user_agent})"
           ]
         end
 
         private
 
         attr_reader :model, :environment
+
+        def default_user_agent
+          environment.fetch "TRMNL_API_USER_AGENT", TRMNL::API.name.gsub("::", " ")
+        end
       end
     end
   end

data/lib/trmnl/api/container.rb

@@ -8,22 +8,25 @@ module TRMNL
   module API
     # Registers application dependencies.
     module Container
-      extend Containable
+      extend Containable[register: Containers::Register]
 
       register(:settings, as: :fresh) { TRMNL::API::Configuration::Loader.new.call }
       register(:requester) { API::Requester.new }
       register(:logger) { Cogger.new id: "trmnl-api", formatter: :json }
 
       register :http do
-        HTTP.default_options = HTTP::Options.new features: {logging: {logger: self[:logger]}}
-        HTTP
+        settings = self[:settings]
+
+        HTTP.timeout(settings.timeout)
+            .headers(settings.headers)
+            .use(logging: {logger: self[:logger]})
       end
 
       namespace :schemas do
         register :category, Schemas::Category
         register :current_screen, Schemas::CurrentScreen
         register :display, Schemas::Display
-        register :firmware, Schemas::Firmware
+        register :latest_firmware, Schemas::LatestFirmware
         register :ip_address, Schemas::IPAddress
         register :model, Schemas::Model
         register :palette, Schemas::Palette
@@ -34,7 +37,7 @@ module TRMNL
       namespace :models do
         register :current_screen, Models::CurrentScreen
         register :display, Models::Display
-        register :firmware, Models::Firmware
+        register :latest_firmware, Models::LatestFirmware
         register :ip_address, Models::IPAddress
         register :model, Models::Model
         register :palette, Models::Palette

data/lib/trmnl/api/containers/register.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "containable"
+require "refinements/array"
+
+module TRMNL
+  module API
+    module Containers
+      # A custom Containable register that allows specific dependencies to be overwritten.
+      class Register < Containable::Register
+        using Refinements::Array
+
+        def initialize(*, allowed_keys: %w[http logger], **)
+          super(*, **)
+          @allowed_keys = allowed_keys
+        end
+
+        protected
+
+        def check_duplicate key, namespaced_key
+          return if allowed_keys.include? namespaced_key
+
+          message = "Dependency is already registered: #{key.inspect}."
+
+          fail KeyError, message if dependencies.key? namespaced_key
+        end
+
+        private
+
+        attr_reader :allowed_keys
+      end
+    end
+  end
+end

data/lib/trmnl/api/endpoints/{firmware.rb → latest_firmware.rb}

@@ -7,11 +7,11 @@ module TRMNL
   module API
     module Endpoints
       # Handles API request/response.
-      class Firmware
+      class LatestFirmware
         include TRMNL::API::Dependencies[
           :requester,
-          schema: "schemas.firmware",
-          model: "models.firmware"
+          schema: "schemas.latest_firmware",
+          model: "models.latest_firmware"
         ]
 
         include Inspectable[schema: :type]

data/lib/trmnl/api/models/{firmware.rb → latest_firmware.rb}

@@ -4,7 +4,7 @@ module TRMNL
   module API
     module Models
       # Models the data of the API response.
-      Firmware = ::Data.define :url, :version do
+      LatestFirmware = ::Data.define :url, :version do
         def self.for(attributes) = new(**attributes)
       end
     end

data/lib/trmnl/api/models/model.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "core"
 require "refinements/hash"
 
 module TRMNL
@@ -36,7 +37,7 @@ module TRMNL
         private
 
         def apply_defaults
-          self[:palette_names] ||= []
+          self[:palette_names] ||= Core::EMPTY_ARRAY
 
           %i[colors bit_depth scale_factor rotation width height offset_x offset_y].each do |name|
             self[name] ||= 0

data/lib/trmnl/api/models/palette.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "core"
 require "refinements/hash"
 
 module TRMNL
@@ -14,7 +15,7 @@ module TRMNL
         def initialize(**)
           super
           self[:grays] ||= 0
-          self[:colors] ||= []
+          self[:colors] ||= Core::EMPTY_ARRAY
           freeze
         end
       end

data/lib/trmnl/api/models/recipe.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require "core"
+
 module TRMNL
   module API
     module Models
       # Models the payload of the API response.
       Recipe = ::Data.define :data, :meta do
-        def self.empty(meta: Recipes::Meta.new) = new(data: [], meta:)
+        def self.empty(meta: Recipes::Meta.new) = new(data: Core::EMPTY_ARRAY, meta:)
 
         def self.for(**attributes)
           meta = attributes.slice :from,

data/lib/trmnl/api/requester.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "core"
 require "dry/monads"
 require "http"
 
@@ -10,22 +11,20 @@ module TRMNL
       include Dependencies[:settings, :http, :logger]
       include Dry::Monads[:result]
 
-      HEADERS = {}.freeze
-
       def initialize(**)
         super
         yield settings if block_given?
       end
 
-      def get(path, headers: HEADERS, **params) = call(__method__, path, headers, params:)
+      def get(path, headers: Core::EMPTY_HASH, **params) = call(__method__, path, headers, params:)
 
-      def post(path, headers: HEADERS, **json) = call(__method__, path, headers, json:)
+      def post(path, headers: Core::EMPTY_HASH, **json) = call(__method__, path, headers, json:)
 
       private
 
       def call method, path, headers, **options
-        http.headers(settings.headers.merge(headers))
-            .public_send(method, uri(path), options)
+        http.headers(headers)
+            .public_send(method, uri(path), **options)
             .then { |response| response.status.success? ? Success(response) : Failure(response) }
       rescue HTTP::RequestError => error then handle_bad_request path, error
       rescue HTTP::ConnectionError => error then handle_bad_connection path, error

data/lib/trmnl/api/schemas/{firmware.rb → latest_firmware.rb}

@@ -6,7 +6,7 @@ module TRMNL
   module API
     module Schemas
       # Validates API response.
-      Firmware = Dry::Schema.JSON do
+      LatestFirmware = Dry::Schema.JSON do
         required(:url).filled :string
         required(:version).filled :string
       end

data/trmnl-api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "trmnl-api"
-  spec.version = "0.14.0"
+  spec.version = "0.15.0"
   spec.authors = ["TRMNL"]
   spec.email = ["engineering@trmnl.com"]
   spec.homepage = "https://github.com/usetrmnl/trmnl-api"
@@ -25,10 +25,11 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "cogger", "~> 2.0"
   spec.add_dependency "containable", "~> 2.0"
+  spec.add_dependency "core", "~> 3.2"
   spec.add_dependency "dry-monads", "~> 1.9"
   spec.add_dependency "dry-schema", "~> 1.14"
   spec.add_dependency "dry-types", "~> 1.8"
-  spec.add_dependency "http", "~> 5.3"
+  spec.add_dependency "http", "~> 6.0"
   spec.add_dependency "infusible", "~> 5.0"
   spec.add_dependency "inspectable", "~> 1.0"
   spec.add_dependency "pipeable", "~> 2.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl-api
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - TRMNL
@@ -63,6 +63,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: dry-monads
   requirement: !ruby/object:Gem::Requirement
@@ -111,14 +125,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.3'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.3'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: infusible
   requirement: !ruby/object:Gem::Requirement
@@ -190,14 +204,15 @@ files:
 - lib/trmnl/api/configuration/content.rb
 - lib/trmnl/api/configuration/loader.rb
 - lib/trmnl/api/container.rb
+- lib/trmnl/api/containers/register.rb
 - lib/trmnl/api/dependencies.rb
 - lib/trmnl/api/endpoints/category.rb
 - lib/trmnl/api/endpoints/container.rb
 - lib/trmnl/api/endpoints/current_screen.rb
 - lib/trmnl/api/endpoints/dependencies.rb
 - lib/trmnl/api/endpoints/display.rb
-- lib/trmnl/api/endpoints/firmware.rb
 - lib/trmnl/api/endpoints/ip_address.rb
+- lib/trmnl/api/endpoints/latest_firmware.rb
 - lib/trmnl/api/endpoints/log.rb
 - lib/trmnl/api/endpoints/model.rb
 - lib/trmnl/api/endpoints/palette.rb
@@ -206,8 +221,8 @@ files:
 - lib/trmnl/api/locale_reducer.rb
 - lib/trmnl/api/models/current_screen.rb
 - lib/trmnl/api/models/display.rb
-- lib/trmnl/api/models/firmware.rb
 - lib/trmnl/api/models/ip_address.rb
+- lib/trmnl/api/models/latest_firmware.rb
 - lib/trmnl/api/models/model.rb
 - lib/trmnl/api/models/palette.rb
 - lib/trmnl/api/models/recipe.rb
@@ -220,8 +235,8 @@ files:
 - lib/trmnl/api/schemas/category.rb
 - lib/trmnl/api/schemas/current_screen.rb
 - lib/trmnl/api/schemas/display.rb
-- lib/trmnl/api/schemas/firmware.rb
 - lib/trmnl/api/schemas/ip_address.rb
+- lib/trmnl/api/schemas/latest_firmware.rb
 - lib/trmnl/api/schemas/model.rb
 - lib/trmnl/api/schemas/palette.rb
 - lib/trmnl/api/schemas/recipe.rb
@@ -253,7 +268,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 4.0.11
 specification_version: 4
 summary: A monadic TRMNL API client.
 test_files: []