trmnl-api 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ba1eee66530c227b2e43b24de28e6913753d4f627af3d979c3add5cbba3846c
-  data.tar.gz: da5463562b79f6b883f90925cb61ffc44b357c3e64eec615f5cbb0a433f3a36a
+  metadata.gz: f8a754ac699d2142cb950f2bc7739616181a33f085c99b244856f9115f823b6e
+  data.tar.gz: 8a221272e414bed3c1c25a8517c91bbce9286655c51057d9487077abdad22d6c
 SHA512:
-  metadata.gz: 03430a130bfa5a302b67c674ece3951b88e0629f256c7937351d562a7f52117b7b0a0704817fbda6a4d771ee0ddd59542f80e9cccd5970c6ab5a8dfe1e9be0ba
-  data.tar.gz: 71d6d93f75797dad4ef0ae37e6b454d65adcff265149de1f6e32175ae7d5970b4aa590283eed5d95ae93ccfad89672c1a835ce4529af8e1ea5d53a4844a5f532
+  metadata.gz: fadb0d344109f6a8ae6b84f411ee7f7363c708daa823a68c5adcd875871dc41928526505241587fa3218a48ece69acc2142d787245c2ce41a28e0cb30e3d28b5
+  data.tar.gz: 3ae4afaab60d62d8a1d8e6d776175031915cea50f237af2a025686c769a02651bc9137e2e3ffd4aa95bc24c925bc2f18b6a04161e33c1b8a683c1b7adb2467c4

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.call
 
 # 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.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"
+                }
+              ]
+            }
 
 # 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.call 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,33 @@
 # frozen_string_literal: true
 
-require "dry/monads"
-require "http"
-
 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
+      ]
+
+      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

@@ -7,8 +7,8 @@ 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"
         ]
@@ -16,7 +16,7 @@ module TRMNL
         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

@@ -7,11 +7,16 @@ 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 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

@@ -7,11 +7,16 @@ 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 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

@@ -7,11 +7,16 @@ 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 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.1.0"
   spec.authors = ["TRMNL"]
   spec.email = ["support@usetrmnl.com"]
   spec.homepage = "https://github.com/usetrmnl/trmnl-api"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl-api
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - TRMNL
@@ -167,7 +167,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 +178,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: