trmnl-api 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ba1eee66530c227b2e43b24de28e6913753d4f627af3d979c3add5cbba3846c
-  data.tar.gz: da5463562b79f6b883f90925cb61ffc44b357c3e64eec615f5cbb0a433f3a36a
+  metadata.gz: 569d9d6bbfd5690691f558a31079e9837b9c39141c02e5f43e44bd58cfbf2663
+  data.tar.gz: e77c972a0cebebc856605a9fb3c4b7fc99bb6c475f786900e7eba0e3b508875e
 SHA512:
-  metadata.gz: 03430a130bfa5a302b67c674ece3951b88e0629f256c7937351d562a7f52117b7b0a0704817fbda6a4d771ee0ddd59542f80e9cccd5970c6ab5a8dfe1e9be0ba
-  data.tar.gz: 71d6d93f75797dad4ef0ae37e6b454d65adcff265149de1f6e32175ae7d5970b4aa590283eed5d95ae93ccfad89672c1a835ce4529af8e1ea5d53a4844a5f532
+  metadata.gz: 26a8717e1cdd331584bc6f390bfc07ef30b072b2f9a5a406c562fd5eee369576b17b149f762ca4f9e48b0c763891e92618e0823eae384d549392910e917b1e8d
+  data.tar.gz: 5b9cfef970999778d870a606961a6dd54de4233eb2343a72b07ff11d26729d91652a324a99fda045998d6f706b91cf078e77ba077d047798ce77e058a162cdef

data/README.adoc

@@ -48,14 +48,28 @@ require "trmnl/api"
 This client provides access to multiple endpoints. Each endpoint will answer either a `Success` or `Failure` (as provided by {dry_monads_link}) based on result of the API call. This allows you pattern match in your own code when using each endpoint. Example:
 
 ``` ruby
-case endpoint.call token: "secret"
+client = TRMNL::API::Client.new
+
+case client.display token: "secret"
   in Success(payload) then puts payload
   in Failure(response) then puts response
-  else puts "Unknown HTTP response."
+  else puts "Unknown response."
 end
 ```
 
-See each endpoint for further details.
+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:
+
+[source,ruby]
+----
+client = TRMNL::API::Client.new do |settings|
+  settings.content_type = "application/json",
+  settings.uri = "https://trmnl.app/api"
+end
+----
 
 === Environment
 
@@ -64,16 +78,18 @@ 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_URI`: Defines the API URI. Default: "https://trmnl.app/api".
 
-Any/all environment changes will be applied to all endpoint objects.
+Any/all environment changes will be applied unless you override these settings via the client configuration block shown above.
+
+=== Endpoints
 
-=== Current Screen
+==== Current Screen
 
 Allows you to obtain current screen being displayed for your device. You must supply your device's API token as the `token`. Example:
 
 [source,ruby]
 ----
-endpoint = TRMNL::API::Endpoints::CurrentScreen.new
-endpoint.call token: "secret"
+client = TRMNL::API::Client.new
+client.current_screen token: "secret"
 
 # Success(
 #   #<data TRMNL::API::Models::CurrentScreen
@@ -84,14 +100,14 @@ endpoint.call token: "secret"
 # )
 ----
 
-=== Display
+==== Display
 
-Allows you to obtain current screen being displayed for your device. You must supply your device's API token as the `token`. Example:
+Allows you to obtain current screen being displayed for your device with additional information not provided by the xref:_current_screen[Current Screen] endpoint. You must supply your device's API token as the `token`. Example:
 
 [source,ruby]
 ----
-endpoint = TRMNL::API::Endpoints::Display.new
-endpoint.call token: "secret"
+client = TRMNL::API::Client.new
+client.display token: "secret"
 
 # Success(
 #   #<struct TRMNL::API::Models::Display
@@ -107,73 +123,72 @@ endpoint.call token: "secret"
 # )
 ----
 
-=== Firmware
+==== Firmware
 
 Allows you to obtain the current stable firmware version. Example:
 
 [source,ruby]
 ----
-endpoint = TRMNL::API::Endpoints::Firmware.new
-endpoint.call
+client = TRMNL::API::Client.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">)
 ----
 
-=== Log
+==== 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:
 
 [source,ruby]
 ----
-endpoint = TRMNL::API::Endpoints::Log.new
-endpoint.call token: "secret",
-              log: {
-                logs_array: [
-                  {
-                    log_id: 1,
-                    creation_timestamp: 1742022124,
-                    log_message: "returned code is not OK: 404",
-                    log_codeline: 597,
-                    device_status_stamp: {
-                      wifi_status: "connected",
-                      wakeup_reason: "timer",
-                      current_fw_version: "1.4.7",
-                      free_heap_size: 160656,
-                      special_function: "none",
-                      refresh_rate: 30,
-                      battery_voltage: 4.772,
-                      time_since_last_sleep_start: 31,
-                      wifi_rssi_level: -54
-                    },
-                    additional_info: {
-                      retry_attempt: 1
-                    },
-                    log_sourcefile: "src/bl.cpp"
-                  }
-                ]
-              }
+client = TRMNL::API::Client.new
+client.log token: "secret",
+            log: {
+              logs_array: [
+                {
+                  log_id: 1,
+                  creation_timestamp: 1742022124,
+                  log_message: "returned code is not OK: 404",
+                  log_codeline: 597,
+                  device_status_stamp: {
+                    wifi_status: "connected",
+                    wakeup_reason: "timer",
+                    current_fw_version: "1.4.7",
+                    free_heap_size: 160656,
+                    special_function: "none",
+                    refresh_rate: 30,
+                    battery_voltage: 4.772,
+                    time_since_last_sleep_start: 31,
+                    wifi_rssi_level: -54
+                  },
+                  additional_info: {
+                    retry_attempt: 1
+                  },
+                  log_sourcefile: "src/bl.cpp"
+                }
+              ]
+            }
 
 # Success(#<HTTP::Response/1.1 204 No Content...)
 ----
 
 You'll either get a 204 No Content or 200 OK response depending on if the device exists or not.
 
-=== Setup
+==== 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:
 
-
 [source,ruby]
 ----
-endpoint = TRMNL::API::Endpoints::Setup.new
-endpoint.call id: "B0:81:84:22:BD:E8"
+client = TRMNL::API::Client.new
+client.setup id: "A1:B2:C3:D4:E5:F6"
 
 # Success(
 #   #<data TRMNL::API::Models::Setup
 #     api_key="secret",
-#     friendly_id="40DEF8",
+#     friendly_id="F51FDE",
 #     image_url="https://usetrmnl.com/images/setup/setup-logo.bmp",
-#     message="Register at usetrmnl.com/signup with Device ID '40DEF8'"
+#     message="Register at usetrmnl.com/signup with Device ID 'F51FDE'"
 #   >
 # )
 ----

data/lib/trmnl/api/client.rb

@@ -1,39 +1,43 @@
 # frozen_string_literal: true
 
-require "dry/monads"
-require "http"
+require "inspectable"
 
 module TRMNL
   module API
-    # Provides a low level configurable and monadic API client.
-    # :reek:DataClump
+    # Provides the primary client for making API requests.
     class Client
-      include Dry::Monads[:result]
-
-      HEADERS = {}.freeze
-
-      def initialize settings: TRMNL::API::Configuration::Loader.new.call, http: HTTP
-        @settings = settings
-        @http = http
-
+      include Dependencies[:settings]
+
+      include Endpoints::Dependencies[
+        endpoint_current_screen: :current_screen,
+        endpoint_display: :display,
+        endpoint_firmware: :firmware,
+        endpoint_log: :log,
+        endpoint_setup: :setup
+      ]
+
+      include Inspectable[
+        endpoint_current_screen: :class,
+        endpoint_display: :class,
+        endpoint_firmware: :class,
+        endpoint_log: :class,
+        endpoint_setup: :class
+      ]
+
+      def initialize(**)
+        super
         yield settings if block_given?
       end
 
-      def get(path, headers: HEADERS, **params) = call(__method__, path, headers, params:)
+      def current_screen(**) = endpoint_current_screen.call(**)
 
-      def post(path, headers: HEADERS, **json) = call(__method__, path, headers, json:)
+      def display(**) = endpoint_display.call(**)
 
-      private
+      def firmware = endpoint_firmware.call
 
-      attr_reader :settings, :http
+      def log(**) = endpoint_log.call(**)
 
-      # rubocop:todo Metrics/ParameterLists
-      def call method, path, headers, **options
-        http.headers(settings.headers.merge(headers))
-            .public_send(method, "#{settings.uri}/#{path}", options)
-            .then { |response| response.status.success? ? Success(response) : Failure(response) }
-      end
-      # rubocop:enable Metrics/ParameterLists
+      def setup(**) = endpoint_setup.call(**)
     end
   end
 end

data/lib/trmnl/api/container.rb

@@ -10,11 +10,12 @@ module TRMNL
     module Container
       extend Containable
 
-      register(:client) { API::Client.new }
+      register(:settings) { 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.default_options = HTTP::Options.new features: {logging: {logger: self[:logger]}}
         HTTP
       end
 

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "containable"
+
+module TRMNL
+  module API
+    module Endpoints
+      # Registers all endpoints.
+      module Container
+        extend Containable
+
+        register(:current_screen) { CurrentScreen.new }
+        register(:display) { Display.new }
+        register(:firmware) { Firmware.new }
+        register(:log) { Log.new }
+        register(:setup) { Setup.new }
+      end
+    end
+  end
+end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "inspectable"
 require "pipeable"
 
 module TRMNL
@@ -7,16 +8,17 @@ module TRMNL
     module Endpoints
       # Handles API request/response.
       class CurrentScreen
-        include Dependencies[
-          :client,
+        include TRMNL::API::Dependencies[
+          :requester,
           contract: "contracts.current_screen",
           model: "models.current_screen"
         ]
 
+        include Inspectable[contract: :class]
         include Pipeable
 
         def call token:
-          pipe client.get("current_screen", headers: {"Access-Token" => token}),
+          pipe requester.get("current_screen", headers: {"Access-Token" => token}),
                try(:parse, catch: JSON::ParserError),
                validate(contract, as: :to_h),
                to(model, :for)

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "infusible"
+
+module TRMNL
+  module API
+    module Endpoints
+      Dependencies = Infusible[Container]
+    end
+  end
+end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "inspectable"
 require "pipeable"
 
 module TRMNL
@@ -7,11 +8,17 @@ module TRMNL
     module Endpoints
       # Handles API request/response.
       class Display
-        include Dependencies[:client, contract: "contracts.display", model: "models.display"]
+        include TRMNL::API::Dependencies[
+          :requester,
+          contract: "contracts.display",
+          model: "models.display"
+        ]
+
+        include Inspectable[contract: :class]
         include Pipeable
 
         def call token:
-          pipe client.get("display", headers: {"Access-Token" => token}),
+          pipe requester.get("display", headers: {"Access-Token" => token}),
                try(:parse, catch: JSON::ParserError),
                validate(contract, as: :to_h),
                to(model, :for)

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "inspectable"
 require "pipeable"
 
 module TRMNL
@@ -7,11 +8,17 @@ module TRMNL
     module Endpoints
       # Handles API request/response.
       class Firmware
-        include Dependencies[:client, contract: "contracts.firmware", model: "models.firmware"]
+        include TRMNL::API::Dependencies[
+          :requester,
+          contract: "contracts.firmware",
+          model: "models.firmware"
+        ]
+
+        include Inspectable[contract: :class]
         include Pipeable
 
         def call
-          pipe client.get("firmware/latest"),
+          pipe requester.get("firmware/latest"),
                try(:parse, catch: JSON::ParserError),
                validate(contract, as: :to_h),
                to(model, :for)

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

@@ -5,9 +5,9 @@ module TRMNL
     module Endpoints
       # Handles API request/response.
       class Log
-        include Dependencies[:client]
+        include TRMNL::API::Dependencies[:requester]
 
-        def call(token:, **) = client.post("log", headers: {"Access-Token" => token}, **)
+        def call(token:, **) = requester.post("log", headers: {"Access-Token" => token}, **)
       end
     end
   end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "inspectable"
 require "pipeable"
 
 module TRMNL
@@ -7,11 +8,17 @@ module TRMNL
     module Endpoints
       # Handles API request/response.
       class Setup
-        include Dependencies[:client, contract: "contracts.setup", model: "models.setup"]
+        include TRMNL::API::Dependencies[
+          :requester,
+          contract: "contracts.setup",
+          model: "models.setup"
+        ]
+
+        include Inspectable[contract: :class]
         include Pipeable
 
         def call id:
-          pipe client.get("setup", headers: {"ID" => id}),
+          pipe requester.get("setup", headers: {"ID" => id}),
                try(:parse, catch: JSON::ParserError),
                validate(contract, as: :to_h),
                to(model, :for)

data/lib/trmnl/api/requester.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "http"
+
+module TRMNL
+  module API
+    # Provides a low level configurable and monadic API client.
+    # :reek:DataClump
+    class Requester
+      include Dependencies[:settings, :http]
+      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 post(path, headers: HEADERS, **json) = call(__method__, path, headers, json:)
+
+      private
+
+      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)
+            .then { |response| response.status.success? ? Success(response) : Failure(response) }
+      end
+      # rubocop:enable Metrics/ParameterLists
+    end
+  end
+end

data/lib/trmnl/api.rb

@@ -18,5 +18,7 @@ module TRMNL
     def self.loader registry = Zeitwerk::Registry
       @loader ||= registry.loaders.find { |loader| loader.tag == "trmnl-api" }
     end
+
+    def self.new(&) = Client.new(&)
   end
 end

data/trmnl-api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "trmnl-api"
-  spec.version = "0.0.0"
+  spec.version = "0.2.0"
   spec.authors = ["TRMNL"]
   spec.email = ["support@usetrmnl.com"]
   spec.homepage = "https://github.com/usetrmnl/trmnl-api"
@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dry-schema", "~> 1.14"
   spec.add_dependency "http", "~> 5.2"
   spec.add_dependency "infusible", "~> 4.3"
+  spec.add_dependency "inspectable", "~> 0.3"
   spec.add_dependency "pipeable", "~> 1.3"
   spec.add_dependency "zeitwerk", "~> 2.7"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl-api
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - TRMNL
@@ -119,6 +119,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.3'
+- !ruby/object:Gem::Dependency
+  name: inspectable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: pipeable
   requirement: !ruby/object:Gem::Requirement
@@ -167,7 +181,9 @@ files:
 - lib/trmnl/api/contracts/firmware.rb
 - lib/trmnl/api/contracts/setup.rb
 - lib/trmnl/api/dependencies.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/log.rb
@@ -176,6 +192,7 @@ files:
 - lib/trmnl/api/models/display.rb
 - lib/trmnl/api/models/firmware.rb
 - lib/trmnl/api/models/setup.rb
+- lib/trmnl/api/requester.rb
 - trmnl-api.gemspec
 homepage: https://github.com/usetrmnl/trmnl-api
 licenses:
@@ -201,7 +218,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A monadic TRMNL API client.
 test_files: []