piloterr 0.1.0

data/lib/piloterr/responses.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Piloterr
+  # Buffered HTTP response: status, lower-cased multi-value headers, content type and body bytes.
+  RawResponse = Struct.new(:status, :headers, :content_type, :body, keyword_init: true)
+
+  # Outcome of one Client#batch item: +value+ when +ok?+, else +error+.
+  BatchResult = Struct.new(:index, :value, :error, keyword_init: true) do
+    def ok? = error.nil?
+  end
+
+  # A successful JSON response; +data+ is the parsed body (string keys).
+  class JsonResponse
+    attr_reader :data, :raw_response
+
+    def initialize(data:, raw_response:)
+      @data = data
+      @raw_response = raw_response
+    end
+
+    def kind = :json
+    def json? = true
+    def binary? = false
+  end
+
+  # A successful non-JSON response (image, PDF, HTML…).
+  class BinaryResponse
+    attr_reader :bytes, :content_type, :raw_response
+
+    def initialize(bytes:, content_type:, raw_response:)
+      @bytes = bytes
+      @content_type = content_type
+      @raw_response = raw_response
+    end
+
+    def kind = :binary
+    def json? = false
+    def binary? = true
+
+    # Writes the body to +path+ and returns the number of bytes written.
+    def save(path)
+      File.binwrite(path, bytes)
+    end
+  end
+end

data/lib/piloterr/serialization.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Piloterr
+  # Request serialization: path filling, query pairs and JSON bodies.
+  module Serialization
+    QUERY_STRING_PARAMS = %w[fields is_async soft_fail].freeze
+
+    module_function
+
+    # Fills {name} path segments, then returns [path, query_pairs, body].
+    # nil values are omitted; false and 0 are sent.
+    def serialize(method, path_template, params)
+      raise SerializationError, "Request parameters must be a Hash." unless params.nil? || params.is_a?(Hash)
+
+      remaining = {}
+      (params || {}).each { |name, value| remaining[name.to_s] = value unless value.nil? }
+      path = path_template.gsub(/\{([^}]+)\}/) do
+        name = Regexp.last_match(1)
+        raise SerializationError.new("The \"#{name}\" path parameter is required.", name) unless remaining.key?(name)
+
+        URI.encode_www_form_component(wire_string(name, remaining.delete(name))).gsub("+", "%20")
+      end
+
+      if method == "POST"
+        # The API reads the global parameters from the query string, whatever the method.
+        globals = QUERY_STRING_PARAMS.filter_map { |name| [name, wire_string(name, remaining.delete(name))] if remaining.key?(name) }
+        return [path, globals, remaining]
+      end
+
+      pairs = []
+      remaining.each do |name, value|
+        if value.is_a?(Array)
+          value.each { |item| pairs << [name, wire_string(name, item)] unless item.nil? }
+        else
+          pairs << [name, wire_string(name, value)]
+        end
+      end
+      [path, pairs, nil]
+    end
+
+    def wire_string(name, value)
+      case value
+      when String then value
+      when true, false, Integer, Symbol then value.to_s
+      when Float
+        raise SerializationError.new("The \"#{name}\" parameter must be a finite number.", name) unless value.finite?
+
+        value == value.floor ? value.to_i.to_s : value.to_s
+      when Hash, Array then JSON.generate(value)
+      else
+        raise SerializationError.new("The \"#{name}\" parameter has an unsupported type (#{value.class}).", name)
+      end
+    end
+
+    def encode_query(pairs)
+      pairs.map { |name, value| "#{escape(name)}=#{escape(value)}" }.join("&")
+    end
+
+    def escape(value)
+      URI.encode_www_form_component(value).gsub("+", "%20")
+    end
+  end
+end

data/lib/piloterr/transport.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Piloterr
+  # Default transport on Net::HTTP. A custom transport is any object with
+  # +call(method:, url:, headers:, body:, timeout:)+ returning +[status, headers, body]+,
+  # where headers is a Hash of lower-cased names to arrays of values.
+  class NetHTTPTransport
+    def call(method:, url:, headers:, body:, timeout:)
+      uri = URI(url)
+      request = (method == "POST" ? Net::HTTP::Post : Net::HTTP::Get).new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body if body
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      if timeout
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+      end
+      response = http.start { |connection| connection.request(request) }
+      [response.code.to_i, response.to_hash, response.body || ""]
+    end
+  end
+end

data/lib/piloterr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Piloterr
+  VERSION = "0.1.0"
+end

data/lib/piloterr.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "piloterr/version"
+require_relative "piloterr/errors"
+require_relative "piloterr/responses"
+require_relative "piloterr/serialization"
+require_relative "piloterr/transport"
+require_relative "piloterr/endpoints"
+require_relative "piloterr/operations"
+require_relative "piloterr/client"
+
+# Official Ruby SDK for the Piloterr API (https://www.piloterr.com).
+module Piloterr
+end