trmnl-api 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 569d9d6bbfd5690691f558a31079e9837b9c39141c02e5f43e44bd58cfbf2663
-  data.tar.gz: e77c972a0cebebc856605a9fb3c4b7fc99bb6c475f786900e7eba0e3b508875e
+  metadata.gz: db11ea72e435255e8f0aac6ab4a457c019a0a073abf35d4bae0e71c90b395b17
+  data.tar.gz: d571107317c9968116e3d3e6d66b73b9155641ebdffe723837cd40b223116e70
 SHA512:
-  metadata.gz: 26a8717e1cdd331584bc6f390bfc07ef30b072b2f9a5a406c562fd5eee369576b17b149f762ca4f9e48b0c763891e92618e0823eae384d549392910e917b1e8d
-  data.tar.gz: 5b9cfef970999778d870a606961a6dd54de4233eb2343a72b07ff11d26729d91652a324a99fda045998d6f706b91cf078e77ba077d047798ce77e058a162cdef
+  metadata.gz: 6287bd8712e51994d7e07915f6b3194f48498ca02b062844e19ed54d1c60e3d4b0c063c607cbd99a39efdceec912cb25f58d81b60d23e75bc31866b27adf8bf0
+  data.tar.gz: 04e59263fbdcaa32ea0e6eb41375f6007500bd4c34293fc3c4acbb0686457e95fe23f1dac234ecb7f004bba3cb690e0321f4cd271689d39cfa203c6ebe262304

data/README.adoc

@@ -174,6 +174,36 @@ client.log token: "secret",
 
 You'll either get a 204 No Content or 200 OK response depending on if the device exists or not.
 
+==== Models
+
+Allows you to obtain the model information for all devices and screens. Example:
+
+[source,ruby]
+----
+client = TRMNL::API::Client.new
+client.models
+
+# Success(
+#   #<data TRMNL::API::Models::Model
+#     name="test",
+#     label="Test",
+#     description="A test.",
+#     colors=2,
+#     bit_depth=1,
+#     scale_factor=1,
+#     rotation=90,
+#     mime_type="image/png",
+#     width=800,
+#     height=480,
+#     offset_x=10,
+#     offset_y=15,
+#     published_at="2025-07-16T18:18:11+00:00"
+#   >
+# )
+----
+
+ℹ️ The `scale_factor` can be an integer or float.
+
 ==== Setup
 
 Allows you to obtain the setup response for when a new device is setup. You must supply your device's MAC Address as the `id`. Example:

data/lib/trmnl/api/client.rb

@@ -13,6 +13,7 @@ module TRMNL
         endpoint_display: :display,
         endpoint_firmware: :firmware,
         endpoint_log: :log,
+        endpoint_models: :models,
         endpoint_setup: :setup
       ]
 
@@ -21,6 +22,7 @@ module TRMNL
         endpoint_display: :class,
         endpoint_firmware: :class,
         endpoint_log: :class,
+        endpoint_models: :class,
         endpoint_setup: :class
       ]
 
@@ -37,6 +39,8 @@ module TRMNL
 
       def log(**) = endpoint_log.call(**)
 
+      def models(**) = endpoint_models.call(**)
+
       def setup(**) = endpoint_setup.call(**)
     end
   end

data/lib/trmnl/api/container.rb

@@ -23,6 +23,7 @@ module TRMNL
         register :current_screen, Contracts::CurrentScreen
         register :display, Contracts::Display
         register :firmware, Contracts::Firmware
+        register :model, Contracts::Model
         register :setup, Contracts::Setup
       end
 
@@ -30,6 +31,7 @@ module TRMNL
         register :current_screen, Models::CurrentScreen
         register :display, Models::Display
         register :firmware, Models::Firmware
+        register :model, Models::Model
         register :setup, Models::Setup
       end
     end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module TRMNL
+  module API
+    module Contracts
+      # Validates API response.
+      Model = Dry::Schema.JSON do
+        required(:data).array(:hash) do
+          required(:name).filled :string
+          required(:label).filled :string
+          required(:description).filled :string
+          required(:colors).filled :integer
+          required(:bit_depth).filled :integer
+          required(:scale_factor) { filled? > int? | float? }
+          required(:rotation).filled :integer
+          required(:mime_type).filled :string
+          required(:width).filled :integer
+          required(:height).filled :integer
+          required(:offset_x).filled :integer
+          required(:offset_y).filled :integer
+          required(:published_at).filled :time
+        end
+      end
+    end
+  end
+end

data/lib/trmnl/api/endpoints/container.rb

@@ -13,6 +13,7 @@ module TRMNL
         register(:display) { Display.new }
         register(:firmware) { Firmware.new }
         register(:log) { Log.new }
+        register(:models) { Model.new }
         register(:setup) { Setup.new }
       end
     end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "inspectable"
+require "pipeable"
+
+module TRMNL
+  module API
+    module Endpoints
+      # Handles API request/response.
+      class Model
+        include TRMNL::API::Dependencies[
+          :requester,
+          contract: "contracts.model",
+          model: "models.model"
+        ]
+
+        include Inspectable[contract: :class]
+        include Pipeable
+
+        def call
+          pipe(
+            requester.get("models"),
+            try(:parse, catch: JSON::ParserError),
+            validate(contract, as: :to_h),
+            as(:fetch, :data),
+            map { |data| model.for(**data) }
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module TRMNL
+  module API
+    module Models
+      # Models data for API display responses.
+      Model = Struct.new(
+        :name,
+        :label,
+        :description,
+        :colors,
+        :bit_depth,
+        :scale_factor,
+        :rotation,
+        :mime_type,
+        :width,
+        :height,
+        :offset_x,
+        :offset_y,
+        :published_at
+      ) do
+        def self.for(attributes) = new(**attributes)
+
+        def initialize(**)
+          super
+          apply_defaults
+          freeze
+        end
+
+        def to_json(*) = to_h.to_json(*)
+
+        private
+
+        def apply_defaults
+          %i[colors bit_depth scale_factor rotation width height offset_x offset_y].each do |name|
+            self[name] ||= 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnl/api/requester.rb

@@ -6,9 +6,8 @@ require "http"
 module TRMNL
   module API
     # Provides a low level configurable and monadic API client.
-    # :reek:DataClump
     class Requester
-      include Dependencies[:settings, :http]
+      include Dependencies[:settings, :http, :logger]
       include Dry::Monads[:result]
 
       HEADERS = {}.freeze
@@ -26,13 +25,32 @@ module TRMNL
 
       attr_reader :settings, :http
 
-      # rubocop:todo Metrics/ParameterLists
       def call method, path, headers, **options
         http.headers(settings.headers.merge(headers))
-            .public_send(method, "#{settings.uri}/#{path}", options)
+            .public_send(method, uri(path), options)
             .then { |response| response.status.success? ? Success(response) : Failure(response) }
+      rescue HTTP::ConnectionError => error then handle_bad_connection path, error
+      rescue HTTP::TimeoutError => error then handle_timeout path, error
+      rescue OpenSSL::SSL::SSLError => error then handle_bad_ssl path, error
+      end
+
+      def uri(path) = "#{settings.uri}/#{path}"
+
+      def handle_bad_connection path, error
+        logger.debug { error.message }
+        Failure "Unable to connect: #{uri(path).inspect}. Is the network intermittent or down?"
+      end
+
+      def handle_timeout path, error
+        logger.debug { error.message }
+        Failure "Connection timed out: #{uri(path).inspect}."
+      end
+
+      def handle_bad_ssl path, error
+        logger.debug { error.message }
+        Failure "Unable to secure connection: #{uri(path).inspect}. " \
+                "Is your certificate or SSL valid?"
       end
-      # rubocop:enable Metrics/ParameterLists
     end
   end
 end

data/lib/trmnl/api.rb

@@ -16,7 +16,7 @@ module TRMNL
   # Main namespace.
   module API
     def self.loader registry = Zeitwerk::Registry
-      @loader ||= registry.loaders.find { |loader| loader.tag == "trmnl-api" }
+      @loader ||= registry.loaders.each.find { |loader| loader.tag == "trmnl-api" }
     end
 
     def self.new(&) = Client.new(&)

data/trmnl-api.gemspec

@@ -2,9 +2,9 @@
 
 Gem::Specification.new do |spec|
   spec.name = "trmnl-api"
-  spec.version = "0.2.0"
+  spec.version = "0.4.0"
   spec.authors = ["TRMNL"]
-  spec.email = ["support@usetrmnl.com"]
+  spec.email = ["engineering@usetrmnl.com"]
   spec.homepage = "https://github.com/usetrmnl/trmnl-api"
   spec.summary = "A monadic TRMNL API client."
   spec.license = "MIT"
@@ -23,11 +23,11 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = "~> 3.4"
 
-  spec.add_dependency "cogger", "~> 1.2"
+  spec.add_dependency "cogger", "~> 1.4"
   spec.add_dependency "containable", "~> 1.2"
   spec.add_dependency "dry-monads", "~> 1.8"
   spec.add_dependency "dry-schema", "~> 1.14"
-  spec.add_dependency "http", "~> 5.2"
+  spec.add_dependency "http", "~> 5.3"
   spec.add_dependency "infusible", "~> 4.3"
   spec.add_dependency "inspectable", "~> 0.3"
   spec.add_dependency "pipeable", "~> 1.3"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl-api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - TRMNL
@@ -41,14 +41,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: containable
   requirement: !ruby/object:Gem::Requirement
@@ -97,14 +97,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '5.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '5.3'
 - !ruby/object:Gem::Dependency
   name: infusible
   requirement: !ruby/object:Gem::Requirement
@@ -162,7 +162,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.7'
 email:
-- support@usetrmnl.com
+- engineering@usetrmnl.com
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -179,6 +179,7 @@ files:
 - lib/trmnl/api/contracts/current_screen.rb
 - lib/trmnl/api/contracts/display.rb
 - lib/trmnl/api/contracts/firmware.rb
+- lib/trmnl/api/contracts/model.rb
 - lib/trmnl/api/contracts/setup.rb
 - lib/trmnl/api/dependencies.rb
 - lib/trmnl/api/endpoints/container.rb
@@ -187,10 +188,12 @@ files:
 - lib/trmnl/api/endpoints/display.rb
 - lib/trmnl/api/endpoints/firmware.rb
 - lib/trmnl/api/endpoints/log.rb
+- lib/trmnl/api/endpoints/model.rb
 - lib/trmnl/api/endpoints/setup.rb
 - lib/trmnl/api/models/current_screen.rb
 - lib/trmnl/api/models/display.rb
 - lib/trmnl/api/models/firmware.rb
+- lib/trmnl/api/models/model.rb
 - lib/trmnl/api/models/setup.rb
 - lib/trmnl/api/requester.rb
 - trmnl-api.gemspec
@@ -218,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A monadic TRMNL API client.
 test_files: []