prusalink 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51c60c7c6eff2e6ac93c9bb3e3e95973f756dd33b01e5b7064667f9b3b460c9e
+  data.tar.gz: 1986ff7d2a7ef7f183e0259003181b3fc912adfc44e1aad9b0978ebbbaf90e4c
+SHA512:
+  metadata.gz: c1e9d55a44bb104802c96a1232383b13a7e589d61e2abee09349d05efd0718c6bb2711ee1f05dfc9c6888a6a2d45fbf8337204c44501821650dc6ff592e49a91
+  data.tar.gz: 7d6a4f0e004066aeb8550b7368952548e616617c33c8b265ec110ec3ed60ce761b557cf0b732bf799bd9c7f2eb2f170e52cf6b9d5212144aae4d9c8a7fae6887

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+
+- Initial release: client with HTTP Digest auth, version, info, status, job, storage, transfer and files resources

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sophie Déziel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# PrusaLink Ruby Gem
+
+A type-safe Ruby wrapper for **PrusaLink**, the local REST API built into Prusa 3D printers, with full Sorbet integration.
+
+Works with printers running PrusaLink: MK4/MK4S, MK3.9, MK3.5, XL, MINI/MINI+ and Core One with recent firmware, and MK3/MK3S/MK2.5 with a Raspberry Pi running PrusaLink.
+
+Same architecture as the [`octoprint`](https://github.com/sophiedeziel/octoprint) gem.
+
+## ✨ Key Features
+
+- **🔐 Digest auth built in**: PrusaLink uses HTTP Digest authentication, and the gem handles the challenge, nonce rotation and retries for you. API keys (older firmware) work too.
+- **🛡️ Type Safety**: Sorbet signatures on every resource, and RBI files generated for every attribute
+- **🔥 Smart Error Handling**: HTTP statuses mapped to specific exception types
+- **🎯 Multi-Printer Support**: thread-local clients, and `client.use { }` to talk to several printers
+- **⚡ Modern Ruby**: Ruby 3.3+, Zeitwerk autoloading
+
+## Installation
+
+```ruby
+gem "prusalink", github: "sophiedeziel/prusalink"
+```
+
+## Usage
+
+### Configuration
+
+Turn on PrusaLink on the printer (Settings > Network > PrusaLink). The screen shows the username (`maker` by default) and the password.
+
+```ruby
+require "prusalink"
+
+Prusalink.configure(host: "http://192.168.1.42", password: "from-the-printer-screen")
+
+# Older firmware with an API key
+Prusalink.configure(host: "http://192.168.1.43", api_key: "abcdef")
+
+# Custom username and timeouts (defaults: open_timeout 3s, timeout 10s)
+Prusalink.configure(host: "http://prusa-xl.local", username: "maker", password: "...", timeout: 30)
+```
+
+### Several printers
+
+```ruby
+mk4  = Prusalink::Client.new(host: "http://192.168.1.42", password: "...")
+mini = Prusalink::Client.new(host: "http://192.168.1.43", api_key: "...")
+
+mk4.use  { Prusalink::Status.get }
+mini.use { Prusalink::Status.get }
+```
+
+### Printer status and telemetry
+
+```ruby
+status = Prusalink::Status.get
+status.printer.state        # => "PRINTING"
+status.printer.printing?    # => true
+status.printer.temp_nozzle  # => 214.9
+status.printer.temp_bed     # => 59.5
+status.job&.progress        # => 42.0
+status.job&.time_remaining  # => 520 (seconds)
+
+info = Prusalink::Info.get
+info.name                   # => "MuadDib"
+info.serial                 # => "CZPX4720X004XC34242"
+
+Prusalink::ServerVersion.get.text # => "PrusaLink"
+```
+
+### Jobs
+
+```ruby
+job = Prusalink::Job.get    # => nil when nothing is printing
+job.state                   # => "PRINTING"
+job.progress                # => 42.0
+job.file.display_name       # => "benchy_0.4n_0.2mm_PLA_MK4_1h2m.bgcode"
+
+job.pause
+job.resume
+job.stop
+
+Prusalink::Job.pause(job.id) # or by id
+```
+
+### Files and storage
+
+```ruby
+Prusalink::Storage.list.map(&:path)   # => ["/usb"]
+
+# Upload, and optionally start printing
+Prusalink::Files.upload("benchy.bgcode", storage: "usb", path: "benchy.bgcode", print_after_upload: true)
+
+# Browse
+folder = Prusalink::Files.get(storage: "usb")
+folder.children.map(&:display_name)
+
+# Print, check and delete existing files
+Prusalink::Files.print(storage: "usb", path: "benchy.bgcode")
+Prusalink::Files.exists?(storage: "usb", path: "benchy.bgcode") # => true
+Prusalink::Files.delete(storage: "usb", path: "benchy.bgcode")
+```
+
+For large uploads, give the client a longer `timeout:`.
+
+### Transfers
+
+```ruby
+transfer = Prusalink::Transfer.get    # => nil when nothing is uploading
+transfer&.progress                    # => 65.82
+```
+
+### Error handling
+
+```ruby
+begin
+  Prusalink::Job.pause(42)
+rescue Prusalink::Exceptions::ConflictError => e
+  # The printer isn't printing
+rescue Prusalink::Exceptions::AuthenticationError
+  # Wrong password or API key
+rescue Prusalink::Exceptions::TimeoutError, Prusalink::Exceptions::ConnectionError
+  # Printer offline or unreachable
+end
+```
+
+| Status | Exception |
+|---|---|
+| 400 | `BadRequestError` |
+| 401, 403 | `AuthenticationError` |
+| 404 | `NotFoundError` |
+| 409 | `ConflictError` |
+| 415 | `UnsupportedMediaTypeError` |
+| 500 | `InternalServerError` |
+| 501 | `NotImplementedError` |
+| 503 | `ServiceUnavailableError` |
+| other | `UnknownError` |
+
+All of them inherit from `Prusalink::Exceptions::Error`.
+
+## API coverage
+
+| Endpoint | Resource |
+|---|---|
+| `GET /api/version` | `ServerVersion.get` |
+| `GET /api/v1/info` | `Info.get` |
+| `GET /api/v1/status` | `Status.get` |
+| `GET/DELETE /api/v1/job`, `PUT .../pause`, `.../resume`, `.../continue` | `Job` |
+| `GET /api/v1/storage` | `Storage.list` |
+| `GET/DELETE /api/v1/transfer` | `Transfer` |
+| `GET/PUT/POST/HEAD/DELETE /api/v1/files/{storage}/{path}` | `Files` |
+| `/api/v1/cameras/*` | not yet |
+| `/api/v1/update/*` | not yet |
+
+## Development
+
+```bash
+bin/setup        # install dependencies
+bin/check        # rspec + rubocop + sorbet
+bin/tapioca dsl  # regenerate RBIs after changing auto_attr declarations
+bin/console      # interactive prompt
+```
+
+To record VCR cassettes against a real printer, see [CLAUDE.md](CLAUDE.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/lib/prusalink/auto_initializable.rb

@@ -0,0 +1,224 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  # AutoInitializable provides automatic initialization and typed attribute generation.
+  #
+  # This module eliminates repetitive initialization code by automatically generating:
+  # - Typed instance variables from keyword arguments
+  # - Sorbet-typed attr_reader methods
+  # - Type conversion for nested objects
+  #
+  # @example Basic usage
+  #   class User
+  #     include AutoInitializable
+  #
+  #     auto_attr :name, type: String, nilable: false
+  #     auto_attr :email, type: String
+  #     auto_attr :age, type: Integer
+  #
+  #     auto_initialize!
+  #   end
+  #
+  #   user = User.new(name: "John", email: "john@example.com", age: 30)
+  #   user.name  # => "John" (typed as String)
+  #   user.email # => "john@example.com" (typed as T.nilable(String))
+  #
+  # @example With custom classes and arrays
+  #   class Profile
+  #     include AutoInitializable
+  #
+  #     auto_attr :user, type: User
+  #     auto_attr :tags, type: String, array: true
+  #     auto_attr :metadata, type: Hash
+  #
+  #     auto_initialize!
+  #   end
+  #
+  #   profile = Profile.new(
+  #     user: { name: "John", email: "john@example.com" },  # Auto-converted to User
+  #     tags: ["admin", "developer"],                       # Typed as T.nilable(T::Array[String])
+  #     metadata: { created_at: Time.now }                  # Preserved as Hash
+  #   )
+  #
+  # @example Type conversion behavior
+  #   # Basic Ruby types (Hash, Array, String, Integer) are preserved as-is
+  #   auto_attr :data, type: Hash        # No conversion, preserves original hash
+  #
+  #   # Custom classes are auto-converted from hash data
+  #   auto_attr :user, type: User        # Calls User.new(**hash_data)
+  #
+  #   # Arrays of custom classes
+  #   auto_attr :users, type: User, array: true  # Maps each hash to User.new(**hash)
+  module AutoInitializable
+    extend T::Sig
+    extend T::Helpers
+
+    # Class methods added when AutoInitializable is included.
+    #
+    # These methods provide the DSL for declaring auto-initialized attributes
+    # and generating the corresponding initialization logic.
+    module ClassMethods
+      extend T::Sig
+
+      # Declares an attribute that will be automatically initialized and typed.
+      #
+      # @param name [Symbol] The name of the attribute
+      # @param type [Class, T.untyped] The type of the attribute (String, Integer, Hash, custom classes, etc.)
+      # @param from [Symbol, nil] The source key in initialization hash (defaults to name)
+      # @param array [Boolean] Whether this attribute is an array of the specified type
+      # @param nilable [Boolean] Whether this attribute can be nil
+      #
+      # @example Basic attributes
+      #   auto_attr :name, type: String, nilable: false
+      #   auto_attr :email, type: String
+      #   auto_attr :age, type: Integer
+      #
+      # @example Arrays
+      #   auto_attr :tags, type: String, array: true
+      #   auto_attr :users, type: User, array: true
+      #
+      # @example Custom key mapping
+      #   auto_attr :display_name, type: String, from: :display
+      #
+      # @example Complex types
+      #   auto_attr :metadata, type: Hash
+      #   auto_attr :profile, type: Profile
+      #
+      # @note Basic Ruby types (Hash, Array, String, Integer, Float) are preserved without conversion.
+      #   Custom classes will be instantiated from hash data using Class.new(**hash).
+      sig do
+        params(
+          name: Symbol,
+          type: T.untyped,
+          from: T.nilable(Symbol),
+          array: T::Boolean,
+          nilable: T::Boolean
+        ).void
+      end
+      def auto_attr(name, type: T.untyped, from: nil, array: false, nilable: true)
+        @auto_attrs ||= {}
+        @auto_attrs[name] = {
+          type: type,
+          from: from || name,
+          array: array,
+          nilable: nilable
+        }
+      end
+
+      # Generates the initialize method and typed attr_readers based on declared auto_attr calls.
+      #
+      # This method must be called after all auto_attr declarations to generate the actual
+      # initialization code and Sorbet-typed attribute readers.
+      #
+      # @example
+      #   class User
+      #     include AutoInitializable
+      #
+      #     auto_attr :name, type: String
+      #     auto_attr :age, type: Integer
+      #
+      #     auto_initialize!  # Must be called after auto_attr declarations
+      #   end
+      #
+      # @note This method generates:
+      #   - An initialize method that accepts keyword arguments
+      #   - Type conversion for nested objects
+      #   - Sorbet-typed attr_reader methods
+      #   - Automatic validation that required attributes are provided
+      sig { void }
+      def auto_initialize!
+        attrs = @auto_attrs || {}
+        klass = self
+
+        T.unsafe(self).define_method :initialize do |**kwargs|
+          attrs.each do |name, config|
+            source_key = config[:from]
+            value = kwargs[source_key]
+
+            # Skip if nil and nilable
+            if value.nil?
+              T.unsafe(self).instance_variable_set("@#{name}", nil)
+              next
+            end
+
+            # Handle type conversion
+            converted_value = if config[:type]
+                                if config[:array] && value.is_a?(Array)
+                                  # Handle array of objects
+                                  value.map do |item|
+                                    T.unsafe(klass).send(:convert_value, item, config[:type])
+                                  end
+                                else
+                                  T.unsafe(klass).send(:convert_value, value, config[:type])
+                                end
+                              else
+                                value
+                              end
+
+            T.unsafe(self).instance_variable_set("@#{name}", converted_value)
+          end
+
+          # Call parent initializer if it exists and has an initialize method
+          return unless T.unsafe(self).class.superclass.method_defined?(:initialize)
+
+          super()
+        end
+
+        # Create simple attr_readers
+        # Type signatures are provided by generated RBI files
+        attrs.each_key do |name|
+          T.unsafe(self).attr_reader name
+        end
+      end
+
+      # Returns the hash of declared attributes and their configuration.
+      #
+      # @return [Hash<Symbol, Hash>] Hash mapping attribute names to their configuration
+      #
+      # @example
+      #   User.auto_attrs
+      #   # => {
+      #   #   name: { type: String, from: :name, array: false, nilable: false },
+      #   #   email: { type: String, from: :email, array: false, nilable: true }
+      #   # }
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def auto_attrs
+        @auto_attrs || {}
+      end
+
+      private
+
+      # Converts a value to the specified type if appropriate.
+      #
+      # This method handles type conversion for nested objects during initialization.
+      # Basic Ruby types (Hash, Array, String, etc.) are preserved as-is to avoid
+      # unwanted conversions. Custom classes are instantiated from hash data.
+      #
+      # @param value [Object] The value to potentially convert
+      # @param type [Class] The target type for conversion
+      # @return [Object] The converted value or original value if no conversion needed
+      #
+      # @example
+      #   convert_value({ name: "John" }, User)     # => User.new(name: "John")
+      #   convert_value({ key: "value" }, Hash)     # => { key: "value" } (unchanged)
+      #   convert_value("text", String)             # => "text" (unchanged)
+      sig { params(value: T.untyped, type: T.untyped).returns(T.untyped) }
+      def convert_value(value, type)
+        return value unless value.is_a?(Hash)
+
+        # Don't try to convert basic Ruby types like Hash, Array, String, etc.
+        return value if [Hash, Array, String, Integer, Float, TrueClass, FalseClass].include?(type)
+
+        # Check if type is a class that responds to new (for our custom classes)
+        if type.is_a?(Class) && type.respond_to?(:new)
+          type.new(**value)
+        else
+          value
+        end
+      end
+    end
+
+    mixes_in_class_methods(ClassMethods)
+  end
+end

data/lib/prusalink/base_resource.rb

@@ -0,0 +1,92 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  # Base class for all API resources.
+  class BaseResource
+    class << self
+      extend T::Sig
+
+      # Defines the path for the resource's endpoint
+      #
+      # @param [String] path      The API's endpoint path
+      sig { params(path: String).void }
+      def resource_path(path)
+        @path = path
+      end
+
+      # Gets a single resource and instantiates the object.
+      #
+      # @param path [String, nil]   appended to the resource path
+      # @param deserialize [Boolean] whether to build an object from the response
+      # @param options [Hash]       query string parameters
+      # @return [BaseResource, Hash, nil] nil when the printer answers 204 No Content
+      def fetch_resource(path = nil, deserialize: true, options: {})
+        path = [@path, path].compact.join("/")
+        path += "?#{Faraday::Utils.build_query(options)}" if options.any?
+        response = client.request(path, http_method: :get)
+        return nil if response.nil?
+        return deserialize(response) if deserialize
+
+        response
+      end
+
+      # Sends a POST request to the resource's endpoint.
+      sig do
+        params(path: String, params: T.untyped, headers: T::Hash[T.any(String, Symbol), String]).returns(T.untyped)
+      end
+      def post(path: @path, params: nil, headers: {})
+        client.request(path, http_method: :post, body: params, headers: headers)
+      end
+
+      # Sends a PUT request to the resource's endpoint. `params` may be a Hash (sent as JSON),
+      # a String or an IO (sent as-is).
+      sig do
+        params(path: String, params: T.untyped, headers: T::Hash[T.any(String, Symbol), String]).returns(T.untyped)
+      end
+      def put(path: @path, params: nil, headers: {})
+        client.request(path, http_method: :put, body: params, headers: headers)
+      end
+
+      # Sends a PATCH request to the resource's endpoint.
+      sig do
+        params(path: String, params: T.untyped, headers: T::Hash[T.any(String, Symbol), String]).returns(T.untyped)
+      end
+      def patch(path: @path, params: nil, headers: {})
+        client.request(path, http_method: :patch, body: params, headers: headers)
+      end
+
+      # Sends a DELETE request to the resource's endpoint.
+      sig { params(path: String, headers: T::Hash[T.any(String, Symbol), String]).returns(T.untyped) }
+      def delete(path: @path, headers: {})
+        client.request(path, http_method: :delete, headers: headers)
+      end
+
+      # Sends a HEAD request to the resource's endpoint and returns the response headers.
+      sig { params(path: String).returns(T::Hash[String, String]) }
+      def head(path: @path)
+        client.head(path)
+      end
+
+      # Instantiates an object from a hash. Can be overridden by child classes
+      #
+      # @param [Hash] attrs      the object's attributes
+      # @return [BaseResource]
+      def deserialize(attrs)
+        new(**attrs)
+      end
+
+      private
+
+      sig { returns(Client) }
+      def client
+        client = Prusalink.client
+        raise Exceptions::NotConfiguredError, "No client configured. Use Prusalink.configure" unless client
+
+        client
+      end
+    end
+
+    def initialize(**attrs); end
+  end
+end