trmnl-api 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb8a2557d167924338d70a68b91207d89f48b72a44e66e252fd0760fc3ffc035
-  data.tar.gz: 4c3329056c42c1b57347eb00b748f0baf384720c67aeacf938ce2dcecee4a2e3
+  metadata.gz: 168b5086d30774ef88cc9d12ae187ffa4da349bfe10456c64a5e2fe7e94372a3
+  data.tar.gz: d7c785269f0ddf0238d399a352cef774c9081bb6706a238cf9ead6bcc413ff0e
 SHA512:
-  metadata.gz: 6b7a621e59c10820c52b5dbad143b03399544297fba3faa89078a938539ef53cbb7c823a1028f24930fa4edd56d21c2788a440bdf5b3310ccba8d8dac1fc7f06
-  data.tar.gz: b67362a9aa48c7a4009e5b7f59201378c69bca85de6bb560e4c1b208ab6c5bc15c64e6edceb17d3d6a163b7f1fae00fffb3052c987cb9ee4a851c131b713ead9
+  metadata.gz: 4b6cdd52fa7cc10214220a4906298a1d2243d1da94f8854d1dd1eb67cdcd70a761655a717630bb561151e84c01b8926e7b9fac65e1cd84c9fb7590cddc164f7e
+  data.tar.gz: 732532ba60f51c994898d1a982f404ba0d38b419ccc2c6cc95b46548234c51e1b40eedeeda6b4047d81b46f03408b4fccaa8dc8bef3b85dbcef70c0a4a355576

data/README.adoc

@@ -304,82 +304,81 @@ Success(
 
 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.
-
 [source,ruby]
 ----
 client = TRMNL::API.new { |settings| settings.uri = "https://usetrmnl.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://usetrmnl.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
 

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/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.10.0"
   spec.authors = ["TRMNL"]
   spec.email = ["engineering@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.9.0
+  version: 0.10.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