prusalink 0.1.0

data/lib/prusalink/transfer.rb

@@ -0,0 +1,108 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  # The printer's current file transfer (upload or download).
+  #
+  # @example
+  #   transfer = Prusalink::Transfer.get # => nil when nothing is transferring
+  #   transfer.transfer_type # => "FROM_WEB"
+  #   transfer.progress      # => 42.25
+  #   transfer.stop
+  class Transfer < BaseResource
+    extend T::Sig
+    include AutoInitializable
+    include Deserializable
+
+    resource_path("/api/v1/transfer")
+
+    # @!attribute [r] id
+    #   @return [Integer, nil] The transfer's id. Not documented in the API's Transfer schema, so it may be
+    #     absent; {Status#transfer} always includes it.
+    auto_attr :id, type: Integer
+
+    # @!attribute [r] transfer_type
+    #   @return [String] The transfer's source/destination: "NO_TRANSFER", "FROM_WEB", "FROM_CONNECT",
+    #     "FROM_PRINTER", "FROM_SLICER", "FROM_CLIENT", "TO_CONNECT" or "TO_CLIENT".
+    #     Renamed from the API's `type` field.
+    auto_attr :transfer_type, type: String
+
+    # @!attribute [r] display_name
+    #   @return [String] Long filename of the transferred file
+    auto_attr :display_name, type: String
+
+    # @!attribute [r] path
+    #   @return [String] Destination path, e.g. "/local"
+    auto_attr :path, type: String
+
+    # @!attribute [r] url
+    #   @return [String, nil] Source URL, for downloads
+    auto_attr :url, type: String
+
+    # @!attribute [r] size
+    #   @return [Integer, nil] Total size in bytes
+    auto_attr :size, type: Integer
+
+    # @!attribute [r] progress
+    #   @return [Float] Completion, in percent
+    auto_attr :progress, type: Float
+
+    # @!attribute [r] transferred
+    #   @return [Integer] Transferred data, in bytes
+    auto_attr :transferred, type: Integer
+
+    # @!attribute [r] time_remaining
+    #   @return [Integer, nil] Estimated time left, in seconds
+    auto_attr :time_remaining, type: Integer
+
+    # @!attribute [r] time_transferring
+    #   @return [Integer] Time spent transferring, in seconds
+    auto_attr :time_transferring, type: Integer
+
+    # @!attribute [r] to_print
+    #   @return [Boolean] Whether the file will be printed once the transfer finishes
+    auto_attr :to_print, type: T::Boolean
+
+    # @!attribute [r] extra
+    #   @return [Hash] Any additional fields returned by the API
+    auto_attr :extra, type: Hash
+
+    auto_initialize!
+
+    deserialize_config do
+      rename type: :transfer_type
+    end
+
+    # Retrieve the current transfer.
+    #
+    # @return [Transfer, nil] nil when nothing is transferring (the printer answers 204 No Content)
+    # @raise [Prusalink::Exceptions::Error] if the request fails
+    sig { returns(T.nilable(Transfer)) }
+    def self.get
+      fetch_resource
+    end
+
+    # Stop the transfer with the given id.
+    #
+    # @param id [Integer] The transfer's id
+    # @return [Boolean] true on success
+    # @raise [Prusalink::Exceptions::NotFoundError] if no transfer has this id
+    # @raise [Prusalink::Exceptions::ConflictError] if the transfer can't be stopped
+    sig { params(id: Integer).returns(T::Boolean) }
+    def self.stop(id)
+      delete(path: "/api/v1/transfer/#{id}")
+    end
+
+    # Stop this transfer. See {Transfer.stop}.
+    #
+    # @return [Boolean] true on success
+    # @raise [ArgumentError] if the printer didn't report the transfer's id
+    sig { returns(T::Boolean) }
+    def stop
+      transfer_id = id
+      raise ArgumentError, "This transfer has no id. Use Transfer.stop with Status#transfer's id" if transfer_id.nil?
+
+      self.class.stop(transfer_id)
+    end
+  end
+end

data/lib/prusalink/types.rb

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  # Common type aliases for use with auto_attr and Sorbet signatures.
+  module Types
+    # A hash with symbol keys and untyped values (common for API responses)
+    Hash = T::Hash[Symbol, T.untyped]
+
+    # A boolean type (true or false)
+    Boolean = T.any(TrueClass, FalseClass)
+
+    # A nullable boolean (true, false or nil)
+    NilableBoolean = T.nilable(T.any(TrueClass, FalseClass))
+
+    # A number that PrusaLink may send as an integer or a float
+    Number = T.any(Integer, Float)
+
+    # Printer states reported by /api/v1/status
+    # IDLE, BUSY, PRINTING, PAUSED, FINISHED, STOPPED, ERROR, ATTENTION, READY
+    PrinterState = String
+
+    # Job states reported by /api/v1/job
+    # PRINTING, PAUSED, FINISHED, STOPPED, ERROR
+    JobState = String
+  end
+end

data/lib/prusalink/version.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Prusalink
+  # This gem's version
+  VERSION = "0.1.0"
+end

data/lib/prusalink.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+require "active_support/all"
+require "zeitwerk"
+require "sorbet-runtime"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/tapioca")
+loader.setup
+
+# Load Tapioca compiler if available
+require_relative "tapioca/dsl/compilers/auto_initializable" if defined?(Tapioca)
+
+# Ruby client for PrusaLink, the local REST API of Prusa 3D printers.
+#
+# @example Configure the gem once, then call resources
+#   Prusalink.configure(host: "http://prusa-mk4.local", password: "from-the-printer-screen")
+#   Prusalink::Status.get.printer.state # => "PRINTING"
+#
+# @attr [Prusalink::Client] client      The configured API client
+module Prusalink
+  class << self
+    extend T::Sig
+
+    # Configure the API client with the printer's address and credentials.
+    #
+    # PrusaLink uses HTTP Digest authentication. The username is "maker" by default and the
+    # password is shown on the printer (Settings > Network > PrusaLink). Older firmware uses an
+    # API key instead: pass `api_key:` and leave the password out.
+    #
+    # @example Digest authentication (current firmware)
+    #   Prusalink.configure(host: "http://192.168.1.42", password: "s3cr3t")
+    #
+    # @example API key (older firmware)
+    #   Prusalink.configure(host: "http://192.168.1.42", api_key: "abcdef")
+    #
+    # @param [String] host                  Printer's address
+    # @param [String, nil] password         PrusaLink password (Digest auth)
+    # @param [String] username              PrusaLink username (Digest auth)
+    # @param [String, nil] api_key          PrusaLink API key (older firmware)
+    # @param [Numeric, nil] open_timeout    Seconds to wait for the connection to open
+    # @param [Numeric, nil] timeout         Seconds to wait for a read or a write
+    # @return [nil]
+    sig do
+      params(
+        host: String,
+        password: T.nilable(String),
+        username: String,
+        api_key: T.nilable(String),
+        open_timeout: T.nilable(Numeric),
+        timeout: T.nilable(Numeric)
+      ).void
+    end
+    def configure(host:, password: nil, username: Client::DEFAULT_USERNAME, api_key: nil,
+                  open_timeout: Client::DEFAULT_OPEN_TIMEOUT, timeout: Client::DEFAULT_TIMEOUT)
+      self.client = Client.new(host: host, password: password, username: username, api_key: api_key,
+                               open_timeout: open_timeout, timeout: timeout)
+
+      nil
+    end
+
+    # The API client used for the requests in the current thread
+    # @return [Client, nil]
+    sig { returns(T.nilable(Client)) }
+    def client
+      Thread.current[:prusalink_client]
+    end
+
+    # Sets the API client used for the requests in the current thread
+    # @param [Client, nil] client
+    sig { params(client: T.nilable(Client)).void }
+    def client=(client)
+      Thread.current[:prusalink_client] = client
+    end
+  end
+end

data/lib/tapioca/dsl/compilers/auto_initializable.rb

@@ -0,0 +1,88 @@
+# typed: false
+# frozen_string_literal: true
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Tapioca compiler for classes using AutoInitializable module.
+      #
+      # This compiler generates RBI files with proper Sorbet type signatures
+      # for classes that include the AutoInitializable module, replacing the
+      # need for dynamic code generation at runtime.
+      class AutoInitializable < Tapioca::Dsl::Compiler
+        ConstantType = type_member { { upper: Module } }
+
+        # Gather all classes that include AutoInitializable module.
+        sig { override.returns(T::Enumerable[Module]) }
+        def self.gather_constants
+          # Ensure our classes are loaded (fallback if require.rb doesn't work)
+          unless defined?(::Prusalink::AutoInitializable)
+            gem_root = File.expand_path("../../../..", __dir__)
+            require File.join(gem_root, "lib", "prusalink")
+
+            Zeitwerk::Registry.loaders.each(&:eager_load) if defined?(Zeitwerk::Registry)
+          end
+
+          all_modules.select do |constant|
+            constant.is_a?(Class) &&
+              constant.respond_to?(:auto_attrs) &&
+              constant.included_modules.any? { |mod| mod.name == "Prusalink::AutoInitializable" }
+          end
+        end
+
+        # Generates RBI content for the AutoInitializable class.
+        sig { override.void }
+        def decorate
+          auto_attrs = constant.auto_attrs
+          return if auto_attrs.empty?
+
+          root.create_path(constant) do |klass|
+            auto_attrs.each do |name, config|
+              sorbet_type = generate_sorbet_type(config)
+
+              klass.create_method(
+                name.to_s,
+                return_type: sorbet_type,
+                class_method: false
+              )
+            end
+          end
+        end
+
+        private
+
+        # Generates Sorbet type string for a configuration.
+        def generate_sorbet_type(config)
+          type = config[:type]
+
+          # Handle the case where type is already a Sorbet type
+          return type.to_s if type.respond_to?(:to_s) && (type.to_s.start_with?("T.") || type.to_s.start_with?("T::"))
+
+          # Convert type to string representation
+          base_type = case type
+                      when Class
+                        # For regular classes, use the class name
+                        qualified_name_of(type)
+                      when String
+                        # For primitive types passed as strings
+                        type
+                      when Symbol
+                        # For primitive types passed as symbols
+                        type.to_s.capitalize
+                      else
+                        # Handle T.untyped case and other untyped cases
+                        "T.untyped"
+                      end
+
+          # Handle array types
+          base_type = "T::Array[#{base_type}]" if config[:array]
+
+          # Handle nilable types
+          base_type = "T.nilable(#{base_type})" if config[:nilable]
+
+          base_type
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: prusalink
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sophie Déziel
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: net-http-digest_auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.10908
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.10908
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: A type-safe Ruby wrapper for PrusaLink, the local web API of Prusa 3D
+  printers (MK4, MK3.9, MK3.5, XL, MINI, Core One and MK3 with a Raspberry Pi). Supports
+  printer status, jobs, storage, transfers and file uploads with HTTP Digest authentication.
+email:
+- courrier@sophiedeziel.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/prusalink.rb
+- lib/prusalink/auto_initializable.rb
+- lib/prusalink/base_resource.rb
+- lib/prusalink/client.rb
+- lib/prusalink/deserializable.rb
+- lib/prusalink/digest_auth.rb
+- lib/prusalink/exceptions.rb
+- lib/prusalink/files.rb
+- lib/prusalink/files/file.rb
+- lib/prusalink/files/folder.rb
+- lib/prusalink/files/refs.rb
+- lib/prusalink/info.rb
+- lib/prusalink/job.rb
+- lib/prusalink/job/file.rb
+- lib/prusalink/server_version.rb
+- lib/prusalink/status.rb
+- lib/prusalink/status/camera.rb
+- lib/prusalink/status/job.rb
+- lib/prusalink/status/printer.rb
+- lib/prusalink/status/storage.rb
+- lib/prusalink/status/transfer.rb
+- lib/prusalink/storage.rb
+- lib/prusalink/transfer.rb
+- lib/prusalink/types.rb
+- lib/prusalink/version.rb
+- lib/tapioca/dsl/compilers/auto_initializable.rb
+homepage: https://github.com/sophiedeziel/prusalink
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/sophiedeziel/prusalink
+  source_code_uri: https://github.com/sophiedeziel/prusalink
+  changelog_uri: https://github.com/sophiedeziel/prusalink/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A type-safe Ruby wrapper for the PrusaLink REST API with full Sorbet integration.
+test_files: []