trmnl-api 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb8a2557d167924338d70a68b91207d89f48b72a44e66e252fd0760fc3ffc035
-  data.tar.gz: 4c3329056c42c1b57347eb00b748f0baf384720c67aeacf938ce2dcecee4a2e3
+  metadata.gz: ff7ecb483d86f9e68a550342e7e923e08ac1ef5d7330a12f4631e94e7a517438
+  data.tar.gz: a249a3fd8c173416d35fb2da4a15be7accf19e29e6505e667c90b4f440866047
 SHA512:
-  metadata.gz: 6b7a621e59c10820c52b5dbad143b03399544297fba3faa89078a938539ef53cbb7c823a1028f24930fa4edd56d21c2788a440bdf5b3310ccba8d8dac1fc7f06
-  data.tar.gz: b67362a9aa48c7a4009e5b7f59201378c69bca85de6bb560e4c1b208ab6c5bc15c64e6edceb17d3d6a163b7f1fae00fffb3052c987cb9ee4a851c131b713ead9
+  metadata.gz: 40d5b26f6f84761379eb2078048ed792eb376506c3e7bc4d59bd05f08215008be16ccff61548cbd63a302350b357174c479fefcce692cd0d34c6fac3d280dd05
+  data.tar.gz: c8ac0a599cf3743f67f58ac0e9021277b08327110b952b4b7c0aabf45ad3679eeae05b0bfe44dc2ea39e191c6370a857558b3422193d01edb82d49c2b4b2d4d3

data/README.adoc

@@ -2,8 +2,8 @@
 :toclevels: 5
 :figure-caption!:
 
-:trmnl_link: link:https://usetrmnl.com[TRMNL]
-:trmnl_api_link: link:https://usetrmnl.com/api-docs/index.html[TRMNL API]
+:trmnl_link: link:https://trmnl.com[TRMNL]
+:trmnl_api_link: link:https://trmnl.com/api-docs/index.html[TRMNL API]
 :dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]
 
 = TRMNL API
@@ -113,7 +113,7 @@ client.current_screen token: "secret"
 # Success(
 #   #<data TRMNL::API::Models::CurrentScreen
 #      refresh_rate=1773,
-#      image_url="https://usetrmnl.com/plugin-2025-04-10T11-34-38Z-380c77",
+#      image_url="https://trmnl.com/plugin-2025-04-10T11-34-38Z-380c77",
 #      filename="plugin-2025-04-10T11-34-38Z-380c77"
 #   >
 # )
@@ -132,6 +132,7 @@ client.display token: "secret"
 #   #<struct TRMNL::API::Models::Display
 #     filename="plugin-1745348489",
 #     firmware_url="https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin",
+#     firmware_version="1.4.8",
 #     image_url="https://trmnl.s3.us-east-2.amazonaws.com/plugin-1745348489",
 #     image_url_timeout=0,
 #     refresh_rate=1771,
@@ -302,84 +303,83 @@ Success(
 
 ==== Recipes
 
-Allows you to obtain information about link:https://usetrmnl.com/recipes[Recipes]. Example:
-
-⚠️ This _does not_ use the {trmnl_api_link} like every other endpoint documented here. This is why you must customize the settings URI to point to the root of the TRMNL application instead of using the default API endpoint.
+Allows you to obtain information about link:https://trmnl.com/recipes[Recipes]. Example:
 
 [source,ruby]
 ----
-client = TRMNL::API.new { |settings| settings.uri = "https://usetrmnl.com" }
+client = TRMNL::API.new { |settings| settings.uri = "https://trmnl.com" }
 
-client.recipes                          # Answers first page.
-client.recipes page: 10                 # Answers page ten.
-client.recipes search: "comic"          # Answers first page of comics.
-client.recipes "sort-by": "popularity"  # Answers first page sorted by popularity.
+client.recipes                     # Answers first page.
+client.recipes page: 10            # Answers page ten.
+client.recipes search: "comic"     # Answers first page of comics.
+client.recipes sort: "popularity"  # Answers first page sorted by popularity.
 
 # Success(
-#   #<data TRMNL::API::Models::Recipe:0x0000b4d0
-#     current_page = 1,
-#     data = [
-#       #<Struct:TRMNL::API::Models::Recipes::Entry:0x0000b4f0
-#         author = #<Struct:TRMNL::API::Models::Recipes::Author:0x0000b500
-#           category = "travel",
-#           description = "Displays upcoming...",
-#           description_locales = {},
-#           email_address = nil,
-#           field_type = "author_bio",
-#           github_url = "https://github.com/CaptainProton42/trmnl-bustimes-org",
-#           keyname = "readme",
-#           learn_more_url = nil,
-#           name = "About This Plugin",
-#           youtube_url = nil
-#         >,
-#         custom_fields = [
-#           {
-#                 "keyname" => "readme",
-#                    "name" => "About This Plugin",
-#                "category" => "travel",
-#              "field_type" => "author_bio",
-#             "description" => "Displays upcoming...",
-#              "github_url" => "https://github.com/CaptainProton42/trmnl-bustimes-org"
-#           },
-#           {
-#                 "keyname" => "atco",
-#              "field_type" => "string",
-#                    "name" => "Bus Stop",
-#             "description" => "The <a href=\"https://mullinscr.github.io/naptan/atco_codes/\">ATCO</a> code for your bus stop.",
-#               "help_text" => "You can find this..."
-#           },
-#           {
-#                 "keyname" => "bus",
-#              "field_type" => "multi_string",
-#                    "name" => "Busses",
-#             "description" => "Optionally, choose specific bus services you want to display departures for.",
-#               "help_text" => "Use the name of the service, e.g. '10' or '3A'.",
-#                "optional" => true
-#           }
-#         ],
-#         icon_content_type = "image/png",
-#         icon_url = "https://trmnl-public.s3.us-east-2.amazonaws.com/59lqujqwid1cvzsd7sr3erfuexur",
-#         id = 222328,
-#         name = "UK Bus Departures (bustimes.org)",
-#         published_at = 2026-01-14 22:53:07.587 UTC,
-#         screenshot_url = "https://trmnl.s3.us-east-2.amazonaws.com...",
-#         statistics = #<data TRMNL::API::Models::Recipes::Statistics:0x0000b710
-#           forks = 0,
-#           installs = 1
-#         >
-#       >
-#     ],
-#     from = 1,
-#     next_page_url = "/recipes.json?page=2",
-#     per_page = 25,
-#     prev_page_url = nil,
-#     to = 25,
-#     total = 658
-#   >
+#  #<data TRMNL::API::Models::Recipe:0x00010fc0
+#    data = [
+#      #<Struct:TRMNL::API::Models::Recipes::Data:0x00010fe0
+#        author = #<Struct:TRMNL::API::Models::Recipes::Author:0x00010ff0
+#          category = nil,
+#          description = nil,
+#          description_locales = {},
+#          email_address = nil,
+#          field_type = nil,
+#          github_url = nil,
+#          keyname = nil,
+#          learn_more_url = nil,
+#          name = nil,
+#          youtube_url = nil
+#        >,
+#        custom_fields = [
+#          {
+#                "keyname" => "user_location",
+#             "field_type" => "string",
+#                   "name" => "Weather Location",
+#            "placeholder" => "New York, NY",
+#            "description" => "Choose a location",
+#              "help_text" => "Please be precise...",
+#               "required" => true
+#          },
+#          {
+#                "keyname" => "metric",
+#                   "name" => "Temperature Metric",
+#            "description" => "Celsius or Fahrenheit?",
+#             "field_type" => "select",
+#                "options" => [
+#              "Fahrenheit",
+#              "Celsius"
+#            ],
+#                "default" => "Fahrenheit"
+#          }
+#        ],
+#        icon_content_type = "image/png",
+#        icon_url = "https://trmnl-public.s3.us-east-2.amazonaws.com/ajjlbek4cabcvhk3s1lxggn8cgon",
+#        id = 49610,
+#        name = "Weather Chum",
+#        published_at = 2025-05-14 05:32:00 UTC,
+#        screenshot_url = "https://trmnl.s3.us-east-2.amazonaws.com...",
+#        statistics = #<data TRMNL::API::Models::Recipes::Statistics:0x00011170
+#          forks = 1710,
+#          installs = 1
+#        >
+#      >
+#    ],
+#    meta = #<data TRMNL::API::Models::Recipes::Meta:0x00016e20
+#      current_page = 1,
+#      from = 1,
+#      next_page_url = "/recipes.json?page=2&sort_by=popularity",
+#      per_page = 25,
+#      prev_page_url = nil,
+#      to = 25,
+#      total = 678
+#    >
+#  >
 # )
 ----
 
-You'll always get a `data` array with may or may not be filled. Pagination information is listed at the bottom.
+⚠️ This _does not_ use the {trmnl_api_link} like every other endpoint documented here. Instead, you must customize the settings URI to point to the root of the TRMNL application (i.e. `https://trmnl.com`) instead of using the default API endpoint.
+
+You'll always get a `data` array which may or may not be filled and `meta` (metadata) for handling pagination information. You can also combine the `page`, `search`, and `page` parameters as you see fit.
 
 ==== Setup
 
@@ -394,7 +394,7 @@ client.setup id: "A1:B2:C3:D4:E5:F6"
 #   #<data TRMNL::API::Models::Setup
 #     api_key="secret",
 #     friendly_id="F51FDE",
-#     image_url="https://usetrmnl.com/images/setup/setup-logo.bmp",
+#     image_url="https://trmnl.com/images/setup/setup-logo.bmp",
 #     message="Register at usetrmnl.com/signup with Device ID 'F51FDE'"
 #   >
 # )
@@ -430,4 +430,4 @@ bin/rake
 == Credits
 
 * Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
-* Engineered by link:https://usetrmnl.com/developers[TRMNL].
+* Engineered by link:https://trmnl.com/developers[TRMNL].

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

@@ -13,7 +13,7 @@ module TRMNL
         def call
           model[
             content_type: environment.fetch("TRMNL_API_CONTENT_TYPE", "application/json"),
-            uri: environment.fetch("TRMNL_API_URI", "https://usetrmnl.com/api")
+            uri: environment.fetch("TRMNL_API_URI", "https://trmnl.com/api")
           ]
         end
 

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

@@ -9,6 +9,7 @@ module TRMNL
       Display = Dry::Schema.JSON do
         required(:filename).filled :string
         required(:firmware_url).filled :string
+        optional(:firmware_version).maybe :string
         required(:image_url).filled :string
         required(:refresh_rate).filled :integer
         required(:reset_firmware).filled :bool

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

@@ -2,6 +2,7 @@
 
 require "inspectable"
 require "pipeable"
+require "refinements/hash"
 
 module TRMNL
   module API
@@ -17,9 +18,13 @@ module TRMNL
         include Inspectable[contract: :type]
         include Pipeable
 
-        def call(**)
+        using Refinements::Hash
+
+        def call(**parameters)
+          parameters.transform_keys! sort: "sort-by"
+
           pipe(
-            requester.get("recipes.json", **),
+            requester.get("recipes.json", **parameters),
             try(:parse, catch: JSON::ParserError),
             validate(contract, as: :to_h),
             to(model, :for)

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

@@ -4,7 +4,7 @@ module TRMNL
   module API
     module Models
       # Models the data of the API response.
-      CurrentScreen = Data.define :refresh_rate, :image_url, :filename do
+      CurrentScreen = ::Data.define :refresh_rate, :image_url, :filename do
         def self.for(attributes) = new(**attributes)
       end
     end

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

@@ -7,6 +7,7 @@ module TRMNL
       Display = Struct.new(
         :filename,
         :firmware_url,
+        :firmware_version,
         :image_url,
         :image_url_timeout,
         :refresh_rate,

data/lib/trmnl/api/models/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
+      Firmware = ::Data.define :url, :version do
         def self.for(attributes) = new(**attributes)
       end
     end

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

@@ -4,7 +4,7 @@ module TRMNL
   module API
     module Models
       # Models the data of the API response.
-      IPAddress = Data.define :version_4, :version_6 do
+      IPAddress = ::Data.define :version_4, :version_6 do
         def self.for attributes
           new(**attributes.transform_keys(ipv4: :version_4, ipv6: :version_6))
         end

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

@@ -3,20 +3,20 @@
 module TRMNL
   module API
     module Models
-      # Models the data of the API response.
-      Recipe = Data.define(
-        :data,
-        :total,
-        :from,
-        :to,
-        :per_page,
-        :current_page,
-        :prev_page_url,
-        :next_page_url
-      ) do
+      # Models the payload of the API response.
+      Recipe = ::Data.define :data, :meta do
         def self.for(**attributes)
-          data = attributes[:data].map { Recipes::Entry.for(**it) }
-          new(**attributes.merge!(data:))
+          meta = attributes.slice :from,
+                                  :to,
+                                  :current_page,
+                                  :per_page,
+                                  :total,
+                                  :prev_page_url,
+                                  :next_page_url
+
+          data = attributes[:data].map { Recipes::Data.for(**it) }
+
+          new meta: Recipes::Meta[**meta], data:
         end
       end
     end

data/lib/trmnl/api/models/recipes/{entry.rb → data.rb}

@@ -5,7 +5,7 @@ module TRMNL
     module Models
       module Recipes
         # Models the data of the API response.
-        Entry = Struct.new(
+        Data = Struct.new(
           :id,
           :name,
           :icon_url,

data/lib/trmnl/api/models/recipes/meta.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TRMNL
+  module API
+    module Models
+      module Recipes
+        # Models the metadata of the API response.
+        Meta = ::Data.define(
+          :from,
+          :to,
+          :current_page,
+          :per_page,
+          :total,
+          :prev_page_url,
+          :next_page_url
+        ) do
+          def initialize from: 0,
+                         to: 0,
+                         current_page: 0,
+                         per_page: 0,
+                         total: 0,
+                         prev_page_url: nil,
+                         next_page_url: nil
+            super
+          end
+
+          def more? = to.positive? && to < total
+
+          def next_page = current_page + 1
+        end
+      end
+    end
+  end
+end

data/lib/trmnl/api/models/recipes/statistics.rb

@@ -5,7 +5,7 @@ module TRMNL
     module Models
       module Recipes
         # Models the statistics of the API response.
-        Statistics = Data.define :installs, :forks
+        Statistics = ::Data.define :installs, :forks
       end
     end
   end

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

@@ -4,7 +4,7 @@ module TRMNL
   module API
     module Models
       # Models the data of the API response.
-      Setup = Data.define :api_key, :friendly_id, :image_url, :message do
+      Setup = ::Data.define :api_key, :friendly_id, :image_url, :message do
         def self.for(attributes) = new(**attributes)
       end
     end

data/trmnl-api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "trmnl-api"
-  spec.version = "0.9.0"
+  spec.version = "0.11.0"
   spec.authors = ["TRMNL"]
   spec.email = ["engineering@usetrmnl.com"]
   spec.homepage = "https://github.com/usetrmnl/trmnl-api"

data.tar.gz.sig

@@ -1,2 +1 @@
-m�ڡN!A�*��v�*����U�}��7��
$ⳟY�X�z��_��*����~���]?��(⚚17��tzdLFǬ�?o8�,�I.�@��G�>kY'`-��w��P��'r1C.�=����uL�i�F��M��MSٽ���Ϯ)�������<*
t$9�s�^P�=�(����1�i�8KI»`����\Jb��G��͒.S���䔫�D���K�z��v����g�u[Y��
-�#	�	�%���n#�w�JO.��tο�4�?�`��YA��Ϧv������ݸ��%�A�$�C��G
+gU����|��߷k1mҟoSZ)Qx��q��"h��֠F�3�kA]�Drʴ\<Ϗ��f�T�	-��f��J�x��K�q����ul��e´���j!�P��k`"��1�ZK��-������dԻ$l���9SQ�����S���^�*;��4���j�3L'�W����'�e��y,� 2��.�'��o��6����Ð�$"J����w��G�NR*p��(u���G�[G����/8�s�a0����]���(�����CPP��C$my٦=�ziw�r�b��A�$b�F�*�n�~c�#[�Їv`\�d���ɝ:�-�(��O�ޟJ��ٷs����Zop��2�r艉loHX�'�ZG��{���z�)Vx�mx�r���9

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl-api
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - TRMNL
@@ -222,7 +222,8 @@ files:
 - lib/trmnl/api/models/palette.rb
 - lib/trmnl/api/models/recipe.rb
 - lib/trmnl/api/models/recipes/author.rb
-- lib/trmnl/api/models/recipes/entry.rb
+- lib/trmnl/api/models/recipes/data.rb
+- lib/trmnl/api/models/recipes/meta.rb
 - lib/trmnl/api/models/recipes/statistics.rb
 - lib/trmnl/api/models/setup.rb
 - lib/trmnl/api/requester.rb