forem-ruby 0.1.0.beta1

data/lib/forem/configuration.rb

@@ -0,0 +1,74 @@
+# lib/forem/configuration.rb
+module Forem
+  # Holds all configuration settings for the Forem API client.
+  #
+  # Instances are typically created and mutated through {Forem.configure}.
+  #
+  # @example Setting up configuration
+  #   Forem.configure do |config|
+  #     config.api_key  = "my_api_key"
+  #     config.api_base = "https://dev.to"
+  #   end
+  class Configuration
+    # @!attribute [rw] api_key
+    #   @return [String, nil] the API key used to authenticate requests.
+    #     Corresponds to the `api-key` HTTP header sent with every request.
+    #     Defaults to +nil+.
+
+    # @!attribute [rw] api_base
+    #   @return [String] the base URL of the Forem instance.
+    #     Defaults to <tt>"https://dev.to"</tt>.
+
+    # @!attribute [rw] api_version
+    #   @return [String] the API version string included in Accept headers.
+    #     Defaults to <tt>"v1"</tt>.
+
+    # @!attribute [rw] open_timeout
+    #   @return [Integer] number of seconds to wait while opening a TCP
+    #     connection to the server before raising a timeout error.
+    #     Defaults to +30+.
+
+    # @!attribute [rw] read_timeout
+    #   @return [Integer] number of seconds to wait for a response from the
+    #     server after the connection has been established before raising a
+    #     timeout error. Defaults to +80+.
+
+    # @!attribute [rw] max_network_retries
+    #   @return [Integer] maximum number of automatic retries on transient
+    #     network errors or rate-limit responses. Defaults to +1+.
+
+    # @!attribute [rw] log_level
+    #   @return [Integer, nil] the Logger severity level (e.g. Logger::DEBUG)
+    #     used when a custom {#logger} is configured. Defaults to +nil+
+    #     (logging disabled).
+
+    # @!attribute [rw] logger
+    #   @return [Logger, nil] a custom Logger instance to receive debug output.
+    #     Defaults to +nil+.
+    attr_accessor :api_key, :api_base, :api_version, :open_timeout, :read_timeout,
+                  :max_network_retries, :log_level, :logger
+
+    # Create a new Configuration with default values.
+    #
+    # @return [Configuration] a configuration object pre-populated with
+    #   library defaults.
+    def initialize
+      @api_key = nil
+      @api_base = "https://dev.to"
+      @api_version = "v1"
+      @open_timeout = 30
+      @read_timeout = 80
+      @max_network_retries = 1
+      @log_level = nil
+      @logger = nil
+    end
+
+    # Support duplicating a configuration via +dup+.
+    #
+    # @param source [Configuration] the configuration being duplicated
+    # @return [void]
+    def initialize_dup(source)
+      super
+    end
+  end
+end

data/lib/forem/connection_manager.rb

@@ -0,0 +1,75 @@
+require "net/http"
+require "uri"
+
+module Forem
+  # Manages a pool of persistent Net::HTTP connections keyed by host and port.
+  #
+  # {ConnectionManager} is used internally by {APIRequestor} to reuse
+  # keep-alive TCP connections across multiple requests to the same server,
+  # reducing connection-setup overhead.
+  #
+  # Each {APIRequestor} instance owns exactly one ConnectionManager. Connections
+  # are lazily created on first use and kept open with a 30-second keep-alive
+  # timeout.
+  #
+  # @example Creating a connection manager (internal use)
+  #   manager = Forem::ConnectionManager.new
+  #   uri     = URI("https://dev.to/api/articles")
+  #   conn    = manager.connection_for(uri)
+  class ConnectionManager
+    # Create a new, empty ConnectionManager with no active connections.
+    #
+    # @return [ConnectionManager]
+    def initialize
+      @connections = {}
+    end
+
+    # Return a Net::HTTP connection for the given URI, creating one if needed.
+    #
+    # Connections are keyed by <tt>"host:port"</tt> so the same object is
+    # reused for every request to the same server. SSL is enabled automatically
+    # when the URI scheme is <tt>"https"</tt>.
+    #
+    # @param uri [URI] the parsed URI whose host and port identify the server.
+    # @param open_timeout [Integer] seconds to wait while opening the TCP
+    #   connection. Defaults to +30+.
+    # @param read_timeout [Integer] seconds to wait for a response after the
+    #   connection is established. Defaults to +80+.
+    # @return [Net::HTTP] a (possibly already-started) HTTP connection object.
+    #
+    # @example
+    #   uri  = URI("https://dev.to/api/articles")
+    #   conn = manager.connection_for(uri, open_timeout: 10, read_timeout: 30)
+    def connection_for(uri, open_timeout: 30, read_timeout: 80)
+      key = "#{uri.host}:#{uri.port}"
+      return @connections[key] if @connections[key]
+
+      conn = Net::HTTP.new(uri.host, uri.port)
+      conn.use_ssl = uri.scheme == "https"
+      conn.open_timeout = open_timeout
+      conn.read_timeout = read_timeout
+      conn.keep_alive_timeout = 30
+      @connections[key] = conn
+    end
+
+    # Close all open connections and remove them from the pool.
+    #
+    # Gracefully handles connections that are already closed by swallowing
+    # any {IOError} raised during shutdown. After this call the manager is
+    # empty and new connections will be created on the next {#connection_for}
+    # call.
+    #
+    # @return [void]
+    #
+    # @example
+    #   manager.clear
+    def clear
+      @connections.each_value do |conn|
+        conn.finish if conn.started?
+      rescue IOError
+        # already closed
+      end
+      @connections.clear
+    end
+  end
+end

data/lib/forem/errors.rb

@@ -0,0 +1,118 @@
+module Forem
+  # Base error class for all errors raised by the forem-ruby library.
+  #
+  # Every error exposes the raw HTTP context (status code, body, headers) so
+  # callers can inspect the upstream response without re-issuing the request.
+  #
+  # @example Rescuing a specific subclass
+  #   begin
+  #     Forem::Article.retrieve(99999999)
+  #   rescue Forem::NotFoundError => e
+  #     puts "#{e.http_status}: #{e.message}"
+  #   end
+  #
+  # @example Rescuing any Forem error
+  #   rescue Forem::ForemError => e
+  #     logger.error(e.message)
+  #   end
+  class ForemError < StandardError
+    # @return [Integer, nil] the HTTP status code returned by the server
+    #   (e.g. +401+, +404+, +429+), or +nil+ if no HTTP response was received.
+    attr_reader :http_status
+
+    # @return [String, nil] the raw HTTP response body as a string, or +nil+.
+    attr_reader :http_body
+
+    # @return [Hash, nil] a hash of HTTP response headers, or +nil+.
+    attr_reader :http_headers
+
+    # @return [String, nil] an optional machine-readable error code extracted
+    #   from the API response body, or +nil+.
+    attr_reader :code
+
+    # Initialize a new ForemError.
+    #
+    # @param message [String, nil] a human-readable description of the error.
+    # @param http_status [Integer, nil] the HTTP status code from the response.
+    # @param http_body [String, nil] the raw HTTP response body.
+    # @param http_headers [Hash, nil] a hash of HTTP response headers.
+    # @param code [String, nil] a machine-readable error code from the API.
+    # @return [ForemError]
+    def initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil, code: nil)
+      @http_status = http_status
+      @http_body = http_body
+      @http_headers = http_headers
+      @code = code
+      super(message)
+    end
+  end
+
+  # Raised when the server responds with HTTP 401 Unauthorized.
+  #
+  # Typically indicates a missing or invalid API key.
+  #
+  # @see https://developers.forem.com/api/v1
+  class AuthenticationError < ForemError; end
+
+  # Raised when the server responds with HTTP 403 Forbidden.
+  #
+  # Indicates the authenticated user does not have permission to perform
+  # the requested action.
+  #
+  # @see https://developers.forem.com/api/v1
+  class AuthorizationError < ForemError; end
+
+  # Raised when the server responds with HTTP 404 Not Found.
+  #
+  # The requested resource does not exist on the server.
+  #
+  # @see https://developers.forem.com/api/v1
+  class NotFoundError < ForemError; end
+
+  # Raised when the server responds with HTTP 409 Conflict.
+  #
+  # Usually indicates a duplicate resource or a state conflict (e.g. trying
+  # to publish an article that is already published).
+  #
+  # @see https://developers.forem.com/api/v1
+  class ConflictError < ForemError; end
+
+  # Raised when the server responds with HTTP 422 Unprocessable Entity.
+  #
+  # The request parameters failed server-side validation.
+  #
+  # @see https://developers.forem.com/api/v1
+  class InvalidRequestError < ForemError; end
+
+  # Raised when the server responds with HTTP 429 Too Many Requests.
+  #
+  # The client has exceeded its request quota. The library will automatically
+  # retry rate-limited requests up to {Configuration#max_network_retries}
+  # times, honoring integer +Retry-After+ seconds when supplied and otherwise
+  # using exponential back-off.
+  #
+  # @see https://developers.forem.com/api/v1
+  class RateLimitError < ForemError
+    # Return the number of seconds requested by the server before retrying.
+    #
+    # @return [Integer, nil] +Retry-After+ seconds when the normalized header
+    #   contains only ASCII decimal digits, or +nil+ otherwise.
+    def retry_after
+      value = http_headers&.fetch("retry-after", nil)
+      Integer(value, 10) if value.is_a?(String) && value.match?(/\A[0-9]+\z/)
+    end
+  end
+
+  # Raised when the server returns any HTTP 5xx error or an unrecognised
+  # non-2xx status code not covered by a more specific subclass.
+  #
+  # @see https://developers.forem.com/api/v1
+  class APIError < ForemError; end
+
+  # Raised when a network-level error prevents the library from reaching the
+  # Forem server at all (e.g. DNS failure, connection refused, timeout).
+  #
+  # The library will automatically retry up to
+  # {Configuration#max_network_retries} times before re-raising.
+  class APIConnectionError < ForemError; end
+end

data/lib/forem/forem_object.rb

@@ -0,0 +1,264 @@
+module Forem
+  # Base object class for all Forem API objects. Provides dynamic attribute
+  # access from API response data.
+  #
+  # Attributes are stored internally as a plain +Hash+ with string keys.
+  # They can be read and written using either method-call syntax
+  # (<tt>obj.title</tt>) or hash-subscript syntax (<tt>obj["title"]</tt>).
+  # Nested hashes are recursively converted to {ForemObject} instances via
+  # {Util.convert_to_forem_object}.
+  #
+  # @example Constructing from an API response hash
+  #   obj = Forem::ForemObject.construct_from({ "id" => 1, "title" => "Hello" })
+  #   obj.id      #=> 1
+  #   obj.title   #=> "Hello"
+  #   obj["title"] #=> "Hello"
+  #
+  # @example Writing attributes
+  #   obj.title = "Updated"
+  #   obj["title"] = "Updated again"
+  class ForemObject
+    include APIOperations::Request
+
+    # @return [APIRequestor, nil] the requestor that produced this object,
+    #   used by instance methods (e.g. {APIOperations::Save#save}) when no
+    #   explicit +:requestor+ option is supplied.
+    attr_accessor :requestor
+
+    # Wrap a custom-path GET-array endpoint as a page-based {ListObject}.
+    #
+    # Used by resource methods that hit a non-standard path (e.g.
+    # +/api/articles/me/published+) but otherwise behave like
+    # {APIOperations::List#list}: page-based pagination with
+    # +page+/+per_page+ query params, returning a JSON array of resource
+    # objects.
+    #
+    # The returned ListObject re-uses this same helper for {#next_page} and
+    # {#previous_page}, so pagination works without any further wiring.
+    #
+    # @param path [String] the API path to GET.
+    # @param params [Hash] query parameters (filters and pagination).
+    # @param opts [Hash] per-request options including +:requestor+.
+    # @return [ListObject]
+    def self.paginated_list(path, params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, path, params, opts)
+      per_page = (params[:per_page] || params["per_page"] || 30).to_i
+      page = (params[:page] || params["page"] || 1).to_i
+      klass = self
+      data = (resp.parsed_body || []).map { |item| klass.construct_from(item, requestor: requestor) }
+
+      fetcher = lambda do |direction, state, extra|
+        target = direction == :next ? state.current_page + 1 : state.current_page - 1
+        return nil if target < 1
+        new_params = state.filters.merge(page: target, per_page: state.per_page).merge(extra)
+        klass.paginated_list(path, new_params, { requestor: state.requestor })
+      end
+
+      ListObject.new(
+        data: data,
+        current_page: page,
+        per_page: per_page,
+        resource_class: klass,
+        filters: params.reject { |k, _| [:page, :per_page, "page", "per_page"].include?(k) },
+        requestor: requestor,
+        fetcher: fetcher
+      )
+    end
+
+    # Wrap a cursor-based ("after") GET-array endpoint as a {ListObject}.
+    #
+    # Used by endpoints (e.g. survey poll votes) that use an +after+-style
+    # cursor — successive pages are fetched by passing the last seen ID as
+    # the cursor. Cursor pagination is forward-only; {ListObject#previous_page}
+    # returns +nil+.
+    #
+    # @param path [String] the API path to GET.
+    # @param params [Hash] query parameters (filters and per_page).
+    # @param opts [Hash] per-request options including +:requestor+.
+    # @param cursor_param [Symbol] the query-string key for the cursor
+    #   (default +:after+).
+    # @param cursor_from [Proc] a callable returning the cursor value for an
+    #   item (default extracts +"id"+).
+    # @return [ListObject]
+    def self.cursor_list(path, params = {}, opts = {}, cursor_param: :after, cursor_from: ->(item) { item["id"] })
+      requestor = opts[:requestor]
+      resp = request(:get, path, params, opts)
+      per_page = (params[:per_page] || params["per_page"] || 30).to_i
+      klass = self
+      data = (resp.parsed_body || []).map { |item| klass.construct_from(item, requestor: requestor) }
+
+      fetcher = lambda do |direction, state, extra|
+        return nil unless direction == :next
+        return nil if state.data.empty?
+        next_cursor = cursor_from.call(state.data.last)
+        new_params = state.filters.merge(cursor_param => next_cursor, per_page: state.per_page).merge(extra)
+        klass.cursor_list(path, new_params, { requestor: state.requestor },
+                          cursor_param: cursor_param, cursor_from: cursor_from)
+      end
+
+      ListObject.new(
+        data: data,
+        current_page: nil,
+        per_page: per_page,
+        resource_class: klass,
+        filters: params.reject { |k, _| [cursor_param, cursor_param.to_s, :per_page, "per_page"].include?(k) },
+        requestor: requestor,
+        fetcher: fetcher
+      )
+    end
+
+    # Initialise a new object, optionally pre-populating it with values.
+    #
+    # @param values [Hash] initial attribute hash. Keys are coerced to strings.
+    # @return [ForemObject]
+    def initialize(values = {})
+      @values = {}
+      @requestor = nil
+      update_attributes(values)
+    end
+
+    # Construct a new {ForemObject} from an API response hash.
+    #
+    # This is the preferred factory method — it is called by {Util} and
+    # resource class methods rather than {#initialize} directly.
+    #
+    # @param values [Hash] the API response data. Nested Hashes and Arrays
+    #   are recursively converted via {Util.convert_to_forem_object}.
+    # @param requestor [APIRequestor, nil] the requestor to attach so that
+    #   subsequent instance methods (e.g. +article.save+) can issue
+    #   follow-up calls without having to be passed a +:requestor+ opt
+    #   explicitly.
+    # @return [ForemObject] a new object populated with the given attributes.
+    #
+    # @example
+    #   obj = Forem::ForemObject.construct_from({ "id" => 42, "user" => { "name" => "Alice" } })
+    #   obj.user.name  #=> "Alice"
+    def self.construct_from(values, requestor: nil)
+      obj = new
+      obj.send(:update_attributes, values)
+      obj.requestor = requestor
+      obj
+    end
+
+    # Read an attribute by key.
+    #
+    # @param key [String, Symbol] the attribute name. Symbols are coerced to
+    #   strings before lookup.
+    # @return [Object, nil] the stored value, or +nil+ if the key is absent.
+    #
+    # @example
+    #   obj["id"]    #=> 42
+    #   obj[:title]  #=> "Hello"
+    def [](key)
+      @values[key.to_s]
+    end
+
+    # Write an attribute by key.
+    #
+    # The value is passed through {Util.convert_to_forem_object} so nested
+    # Hashes become {ForemObject} instances automatically.
+    #
+    # @param key [String, Symbol] the attribute name. Symbols are coerced to
+    #   strings.
+    # @param value [Object] the value to store.
+    # @return [Object] the stored (possibly converted) value.
+    #
+    # @example
+    #   obj["title"] = "New title"
+    #   obj[:count]  = 5
+    def []=(key, value)
+      @values[key.to_s] = Util.convert_to_forem_object(value)
+    end
+
+    # Recursively convert this object to a plain Ruby Hash.
+    #
+    # Nested {ForemObject} instances are converted via their own +#to_hash+;
+    # Arrays whose elements are {ForemObject} instances are mapped similarly.
+    #
+    # @return [Hash{String => Object}] a plain Hash representation of all
+    #   attributes.
+    #
+    # @example
+    #   obj.to_hash  #=> { "id" => 1, "title" => "Hello" }
+    def to_hash
+      @values.transform_values do |v|
+        case v
+        when ForemObject then v.to_hash
+        when Array then v.map { |e| e.is_a?(ForemObject) ? e.to_hash : e }
+        else v
+        end
+      end
+    end
+
+    # Compare two {ForemObject} instances by their internal value hash.
+    #
+    # @param other [Object] the object to compare against.
+    # @return [Boolean] +true+ if +other+ is a {ForemObject} with identical
+    #   attribute values.
+    def ==(other)
+      other.is_a?(ForemObject) && @values == other.instance_variable_get(:@values)
+    end
+
+    # Allow +respond_to?+ checks for dynamic attribute accessors.
+    #
+    # Returns +true+ for any key currently stored in the internal values hash,
+    # as well as the corresponding setter (e.g. +title=+).
+    #
+    # @param method [Symbol] the method name being queried.
+    # @param include_private [Boolean] whether to include private methods.
+    # @return [Boolean]
+    def respond_to_missing?(method, include_private = false)
+      name = method.to_s
+      name = name.chomp("=")
+      @values.key?(name) || super
+    end
+
+    # Dynamic getter/setter for API attributes.
+    #
+    # * <tt>obj.title</tt>   — returns <tt>@values["title"]</tt>
+    # * <tt>obj.title = x</tt> — delegates to {#[]=}
+    #
+    # Raises +NoMethodError+ for names that are neither setters nor present in
+    # the values hash.
+    #
+    # @param method [Symbol] the missing method name.
+    # @param args [Array] arguments (used only for setter calls).
+    # @return [Object] the attribute value for getters.
+    # @raise [NoMethodError] if the attribute does not exist in the values hash
+    #   and it is not a setter call.
+    def method_missing(method, *args)
+      name = method.to_s
+      if name.end_with?("=")
+        attr = name.chomp("=")
+        self[attr] = args[0]
+      elsif @values.key?(name)
+        @values[name]
+      else
+        super
+      end
+    end
+
+    # Return a human-readable string representation of the object.
+    #
+    # @return [String] the class name, object ID, and internal values hash.
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} #{@values.inspect}>"
+    end
+
+    private
+
+    # Bulk-update internal attributes from a hash.
+    #
+    # Each value is passed through {Util.convert_to_forem_object} so nested
+    # structures are converted recursively.
+    #
+    # @param values [Hash] attribute key/value pairs to merge.
+    # @return [void]
+    def update_attributes(values)
+      values.each do |k, v|
+        @values[k.to_s] = Util.convert_to_forem_object(v)
+      end
+    end
+  end
+end

data/lib/forem/forem_response.rb

@@ -0,0 +1,50 @@
+require "json"
+
+module Forem
+  # Wraps a raw HTTP response from the Forem API.
+  #
+  # {ForemResponse} is an internal value object created by {APIRequestor} after
+  # every successful round-trip to the server. It normalises the Net::HTTP
+  # response into a simple struct and provides lazy JSON parsing via
+  # {#parsed_body}.
+  #
+  # @example Inspecting a raw response (inside a custom requestor)
+  #   resp = requestor.request(:get, "/api/articles/1")
+  #   resp.http_status   #=> 200
+  #   resp.parsed_body   #=> { "id" => 1, "title" => "Hello" }
+  class ForemResponse
+    # @return [Integer] the HTTP status code of the response (e.g. +200+, +404+).
+    attr_reader :http_status
+
+    # @return [String] the raw, unparsed HTTP response body as a string.
+    attr_reader :http_body
+
+    # @return [Hash] a hash of downcased HTTP response header names to their
+    #   string values (e.g. <tt>{ "content-type" => "application/json" }</tt>).
+    attr_reader :http_headers
+
+    # Create a new ForemResponse.
+    #
+    # @param http_status [Integer] the HTTP status code.
+    # @param http_body [String] the raw response body.
+    # @param http_headers [Hash] the response headers.
+    # @return [ForemResponse]
+    def initialize(http_status:, http_body:, http_headers:)
+      @http_status = http_status
+      @http_body = http_body
+      @http_headers = http_headers
+    end
+
+    # Parse the response body as JSON, caching the result after the first call.
+    #
+    # Returns +nil+ when the body is absent or blank (e.g. HTTP 204 No Content).
+    #
+    # @return [Hash, Array, nil] the decoded JSON value, or +nil+ if the body
+    #   is empty.
+    # @raise [JSON::ParserError] if the body is non-empty but not valid JSON.
+    def parsed_body
+      return nil if http_body.nil? || http_body.empty?
+      @parsed_body ||= JSON.parse(http_body)
+    end
+  end
+end