trmnl-api 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cfbabf5898c2d22a9c6ec94054d5a6aacea3f7f67665075657869a4fb60f5c1
-  data.tar.gz: 683715537fcbe499691d19cfb4f8fe50a63d2ac9c4783fa82b8a9c44630c096e
+  metadata.gz: 6159aaeff6f5885bfb0b4b94feb6f4d99fe55c3e4ae6b87c64009eda6014c397
+  data.tar.gz: c86fe1cc48d9521ea6130951469d3c78505c297fe2b1ac03ae188582268213bf
 SHA512:
-  metadata.gz: 983d4a70dc3421c50eb008cdcd7784a6c26d03e8e2bc012d50948201073fa3ed887e3bad7d2b4033f9a3067fe32ee003ee8fb34b710c872d4db386cdfd8cd764
-  data.tar.gz: 42ec614353a7193a95ecdc38400abf95b6cb4d17f54704d6a689b2b5b7a8f05b3593735924df3e7f557388d736037db08547481629818b56047143bbfaed65f8
+  metadata.gz: d2d17033a2207edd65d2c0fe14fc07bd68e31fc520467833be1cbcd35f8d752b299c72d7394c67f8463ba18d9fbd1aa3854ba7610012383eabe2c1e1dd9341be
+  data.tar.gz: 0e8e4a98208e47f3ed3eeab06e06b82f0e7693349108a74b59a0590ff06e839f1d4f671fde9233b3dceee71421d463f4beacd41ce3397b6b01277286ed139f9f

data/README.adoc

@@ -82,6 +82,24 @@ Any/all environment changes will be applied unless you override these settings v
 
 === Endpoints
 
+==== Categories
+
+Allows you to obtain the list of approved plugin categories. Example:
+
+[source,ruby]
+----
+client = TRMNL::API::Client.new
+client.categories
+
+# Success(
+#   [
+#     "analytics",
+#     "art",
+#     "calendar"
+#   ]
+# )
+----
+
 ==== 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:
@@ -135,6 +153,29 @@ 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:
+
+[source,ruby]
+----
+client = TRMNL::API::Client.new
+client.ip_addresses
+
+# Success(
+#   #<data TRMNL::API::Models::IPAddress
+#     version_4=[
+#       #<IPAddr: IPv4:111.230.59.36/255.255.255.255>,
+#       #<IPAddr: IPv4:222.9.106.45/255.255.255.255>
+#     ],
+#     version_6=[
+#       #<IPAddr: IPv6:1:2:0400:00d0:0000:0000:1874:e001/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff>,
+#       #<IPAddr: IPv6:1:2:0400:00d1:0000:0001:705e:1001/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff>
+#     ]
+#   >
+# )
+----
+
 ==== 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:
@@ -188,6 +229,7 @@ client.models
 #     name="test",
 #     label="Test",
 #     description="A test.",
+#     kind="trmnl",
 #     colors=2,
 #     bit_depth=1,
 #     scale_factor=1,
@@ -197,13 +239,66 @@ client.models
 #     height=480,
 #     offset_x=10,
 #     offset_y=15,
-#     published_at="2025-07-16T18:18:11+00:00"
+#     palette_ids=["bw"],
+#     css: {
+#       classes: {
+#         device: "screen--og_png",
+#         size: "screen--md"
+#       },
+#       variables: [
+#         [
+#           "--screen-w",
+#           "800px"
+#         ],
+#         [
+#           "--screen-h",
+#           "480px"
+#         ],
+#         [
+#           "--ui-scale",
+#           "1.0"
+#         ],
+#         [
+#           "--gap-scale",
+#           "1.0"
+#         ]
+#       ]
+#     }
 #   >
 # )
 ----
 
 ℹ️ The `scale_factor` can be an integer or float.
 
+==== Palettes
+
+Allows you to obtain palettes details. The IDs correlate to the `palette_ids` as found in the Models API. Example:
+
+[source,ruby]
+----
+client = TRMNL::API::Client.new
+client.palettes
+
+Success(
+  [
+    #<data TRMNL::API::Models::Palette
+      id="bw",
+      name="Black & White (1-bit)",
+      grays=2,
+      colors=nil,
+      framework_class="screen--1bit"
+    >,
+    #<data TRMNL::API::Models::Palette
+      id="color-24bit",
+      name="Color (24-bit)",
+      grays=nil,
+      colors=nil,
+      framework_class=""
+    >
+  ]
+)
+----
+
 ==== 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

@@ -9,21 +9,27 @@ module TRMNL
       include Dependencies[:settings]
 
       include Endpoints::Dependencies[
+        endpoint_categories: :categories,
         endpoint_current_screen: :current_screen,
         endpoint_display: :display,
         endpoint_firmware: :firmware,
+        endpoint_ip_addresses: :ip_addresses,
         endpoint_log: :log,
         endpoint_models: :models,
+        endpoint_palettes: :palettes,
         endpoint_setup: :setup
       ]
 
       include Inspectable[
-        endpoint_current_screen: :class,
-        endpoint_display: :class,
-        endpoint_firmware: :class,
-        endpoint_log: :class,
-        endpoint_models: :class,
-        endpoint_setup: :class
+        endpoint_categories: :type,
+        endpoint_current_screen: :type,
+        endpoint_display: :type,
+        endpoint_firmware: :type,
+        endpoint_ip_addresses: :type,
+        endpoint_log: :type,
+        endpoint_models: :type,
+        endpoint_palettes: :type,
+        endpoint_setup: :type
       ]
 
       def initialize(**)
@@ -31,16 +37,22 @@ module TRMNL
         yield settings if block_given?
       end
 
+      def categories = endpoint_categories.call
+
       def current_screen(**) = endpoint_current_screen.call(**)
 
       def display(**) = endpoint_display.call(**)
 
       def firmware = endpoint_firmware.call
 
+      def ip_addresses = endpoint_ip_addresses.call
+
       def log(**) = endpoint_log.call(**)
 
       def models(**) = endpoint_models.call(**)
 
+      def palettes = endpoint_palettes.call
+
       def setup(**) = endpoint_setup.call(**)
     end
   end

data/lib/trmnl/api/container.rb

@@ -20,10 +20,13 @@ module TRMNL
       end
 
       namespace :contracts do
+        register :category, Contracts::Category
         register :current_screen, Contracts::CurrentScreen
         register :display, Contracts::Display
         register :firmware, Contracts::Firmware
+        register :ip_address, Contracts::IPAddress
         register :model, Contracts::Model
+        register :palette, Contracts::Palette
         register :setup, Contracts::Setup
       end
 
@@ -31,7 +34,9 @@ module TRMNL
         register :current_screen, Models::CurrentScreen
         register :display, Models::Display
         register :firmware, Models::Firmware
+        register :ip_address, Models::IPAddress
         register :model, Models::Model
+        register :palette, Models::Palette
         register :setup, Models::Setup
       end
     end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module TRMNL
+  module API
+    module Contracts
+      # Validates API response.
+      Category = Dry::Schema.JSON { required(:data).array(:string) }
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module TRMNL
+  module API
+    module Contracts
+      # Validates API response.
+      IPAddress = Dry::Schema.JSON do
+        required(:data).hash do
+          required(:ipv4).array(Types::IPAddress)
+          required(:ipv6).array(Types::IPAddress)
+        end
+      end
+    end
+  end
+end

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

@@ -21,7 +21,15 @@ module TRMNL
           required(:height).filled :integer
           required(:offset_x).filled :integer
           required(:offset_y).filled :integer
-          required(:published_at).filled :time
+          required(:palette_ids).array(:string)
+          optional(:css).hash do
+            optional(:classes).hash do
+              required(:device).filled :string
+              required(:size).filled :string
+            end
+
+            optional(:variables).filled(Types::CSSVariables)
+          end
         end
       end
     end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module TRMNL
+  module API
+    module Contracts
+      # Validates API response.
+      Palette = Dry::Schema.JSON do
+        required(:data).array(:hash) do
+          required(:id).filled :string
+          required(:name).filled :string
+          optional(:grays).maybe :integer
+          optional(:colors).maybe(:array)
+          optional(:framework_class).maybe :string
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "inspectable"
+require "pipeable"
+
+module TRMNL
+  module API
+    module Endpoints
+      # Handles API request/response.
+      class Category
+        include TRMNL::API::Dependencies[:requester, contract: "contracts.category"]
+
+        include Inspectable[contract: :type]
+        include Pipeable
+
+        def call
+          pipe(
+            requester.get("categories"),
+            try(:parse, catch: JSON::ParserError),
+            validate(contract, as: :to_h),
+            as(:fetch, :data)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -9,11 +9,14 @@ module TRMNL
       module Container
         extend Containable
 
+        register(:categories) { Category.new }
         register(:current_screen) { CurrentScreen.new }
         register(:display) { Display.new }
         register(:firmware) { Firmware.new }
+        register(:ip_addresses) { IPAddress.new }
         register(:log) { Log.new }
         register(:models) { Model.new }
+        register(:palettes) { Palette.new }
         register(:setup) { Setup.new }
       end
     end

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

@@ -14,7 +14,7 @@ module TRMNL
           model: "models.current_screen"
         ]
 
-        include Inspectable[contract: :class]
+        include Inspectable[contract: :type]
         include Pipeable
 
         def call token:

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

@@ -14,7 +14,7 @@ module TRMNL
           model: "models.display"
         ]
 
-        include Inspectable[contract: :class]
+        include Inspectable[contract: :type]
         include Pipeable
 
         def call token:

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

@@ -14,7 +14,7 @@ module TRMNL
           model: "models.firmware"
         ]
 
-        include Inspectable[contract: :class]
+        include Inspectable[contract: :type]
         include Pipeable
 
         def call

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

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

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

@@ -14,7 +14,7 @@ module TRMNL
           model: "models.model"
         ]
 
-        include Inspectable[contract: :class]
+        include Inspectable[contract: :type]
         include Pipeable
 
         def call

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "inspectable"
+require "pipeable"
+
+module TRMNL
+  module API
+    module Endpoints
+      # Handles API request/response.
+      class Palette
+        include TRMNL::API::Dependencies[
+          :requester,
+          contract: "contracts.palette",
+          model: "models.palette"
+        ]
+
+        include Inspectable[contract: :type]
+        include Pipeable
+
+        def call
+          pipe(
+            requester.get("palettes"),
+            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/endpoints/setup.rb

@@ -14,7 +14,7 @@ module TRMNL
           model: "models.setup"
         ]
 
-        include Inspectable[contract: :class]
+        include Inspectable[contract: :type]
         include Pipeable
 
         def call id:

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TRMNL
+  module API
+    module Models
+      # IPs API response.
+      IPAddress = Data.define :version_4, :version_6 do
+        def self.for attributes
+          new(**attributes.transform_keys(ipv4: :version_4, ipv6: :version_6))
+        end
+      end
+    end
+  end
+end

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

@@ -18,7 +18,8 @@ module TRMNL
         :height,
         :offset_x,
         :offset_y,
-        :published_at
+        :palette_ids,
+        :css
       ) do
         def self.for(attributes) = new(**attributes)
 

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module TRMNL
+  module API
+    module Models
+      # IPs API response.
+      Palette = Data.define :id, :name, :grays, :colors, :framework_class do
+        def self.for(attributes) = new(**attributes)
+      end
+    end
+  end
+end

data/lib/trmnl/api/types.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "dry/types"
+require "ipaddr"
+
+module TRMNL
+  module API
+    # A collection of custom types.
+    module Types
+      include Dry.Types(default: :strict)
+
+      CSSVariables = Dry::Types["array"].of(
+        Dry::Types["array"].constrained(filled: true, size: 2).of(Dry::Types["coercible.string"])
+      )
+
+      IPAddress = Constructor IPAddr
+    end
+  end
+end

data/lib/trmnl/api.rb

@@ -6,7 +6,7 @@ require "zeitwerk"
 Dry::Schema.load_extensions :monads
 
 Zeitwerk::Loader.new.then do |loader|
-  loader.inflector.inflect "api" => "API", "trmnl" => "TRMNL"
+  loader.inflector.inflect "api" => "API", "ip_address" => "IPAddress", "trmnl" => "TRMNL"
   loader.tag = "trmnl-api"
   loader.push_dir "#{__dir__}/.."
   loader.setup

data/trmnl-api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "trmnl-api"
-  spec.version = "0.6.1"
+  spec.version = "0.8.0"
   spec.authors = ["TRMNL"]
   spec.email = ["engineering@usetrmnl.com"]
   spec.homepage = "https://github.com/usetrmnl/trmnl-api"
@@ -21,17 +21,17 @@ Gem::Specification.new do |spec|
   spec.signing_key = Gem.default_key_path
   spec.cert_chain = [Gem.default_cert_path]
 
-  spec.required_ruby_version = ">= 3.4"
+  spec.required_ruby_version = ">= 4.0"
 
-  spec.add_dependency "cogger", "~> 1.4"
-  spec.add_dependency "containable", "~> 1.2"
-  spec.add_dependency "dry-monads", "~> 1.8"
+  spec.add_dependency "cogger", "~> 2.0"
+  spec.add_dependency "containable", "~> 2.0"
+  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 "infusible", "~> 4.3"
-  spec.add_dependency "inspectable", "~> 0.3"
-  spec.add_dependency "openssl", "~> 3.3"
-  spec.add_dependency "pipeable", "~> 1.3"
+  spec.add_dependency "infusible", "~> 5.0"
+  spec.add_dependency "inspectable", "~> 1.0"
+  spec.add_dependency "pipeable", "~> 2.0"
   spec.add_dependency "zeitwerk", "~> 2.7"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl-api
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - TRMNL
@@ -41,42 +41,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: containable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: dry-monads
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: dry-schema
   requirement: !ruby/object:Gem::Requirement
@@ -92,75 +92,75 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.14'
 - !ruby/object:Gem::Dependency
-  name: http
+  name: dry-types
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.3'
+        version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.3'
+        version: '1.8'
 - !ruby/object:Gem::Dependency
-  name: infusible
+  name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.3'
+        version: '5.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.3'
+        version: '5.3'
 - !ruby/object:Gem::Dependency
-  name: inspectable
+  name: infusible
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: openssl
+  name: inspectable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: pipeable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -190,26 +190,35 @@ files:
 - lib/trmnl/api/configuration/content.rb
 - lib/trmnl/api/configuration/loader.rb
 - lib/trmnl/api/container.rb
+- lib/trmnl/api/contracts/category.rb
 - lib/trmnl/api/contracts/current_screen.rb
 - lib/trmnl/api/contracts/display.rb
 - lib/trmnl/api/contracts/firmware.rb
+- lib/trmnl/api/contracts/ip_address.rb
 - lib/trmnl/api/contracts/model.rb
+- lib/trmnl/api/contracts/palette.rb
 - lib/trmnl/api/contracts/setup.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/log.rb
 - lib/trmnl/api/endpoints/model.rb
+- lib/trmnl/api/endpoints/palette.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/ip_address.rb
 - lib/trmnl/api/models/model.rb
+- lib/trmnl/api/models/palette.rb
 - lib/trmnl/api/models/setup.rb
 - lib/trmnl/api/requester.rb
+- lib/trmnl/api/types.rb
 - trmnl-api.gemspec
 homepage: https://github.com/usetrmnl/trmnl-api
 licenses:
@@ -228,14 +237,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A monadic TRMNL API client.
 test_files: []