forem-ruby 0.1.0.beta1

data/lib/forem/api_requestor.rb

@@ -0,0 +1,283 @@
+require "json"
+require "uri"
+require "securerandom"
+
+module Forem
+  # Executes authenticated HTTP requests against the Forem API.
+  #
+  # {APIRequestor} is the single entry-point for all network I/O in the
+  # library. It builds requests (including authentication headers), delegates
+  # transport to a {ConnectionManager}, parses the response, maps HTTP error
+  # status codes to typed {ForemError} subclasses, and applies automatic
+  # retry logic for transient failures.
+  #
+  # Each {Forem::Client} owns its own {APIRequestor}, built from the
+  # client's {Configuration}. There is no global default requestor — every
+  # call must originate from a specific client instance (or pass an
+  # explicit +:requestor+ option to a class-level resource method).
+  #
+  # @example Constructing directly (uncommon — prefer {Forem::Client.new})
+  #   config = Forem::Configuration.new
+  #   config.api_key = "my_key"
+  #   requestor = Forem::APIRequestor.new(config: config)
+  #   requestor.request(:get, "/api/articles")
+  class APIRequestor
+    # Create a new APIRequestor.
+    #
+    # @param config [Configuration] the configuration to use for this
+    #   requestor.
+    # @return [APIRequestor]
+    def initialize(config:)
+      @config = config
+      @connection_manager = ConnectionManager.new
+    end
+
+    # Execute an HTTP request against the Forem API.
+    #
+    # Builds the request, attaches authentication headers, sends it, and
+    # returns a {ForemResponse}. On HTTP 4xx/5xx responses the method raises
+    # the appropriate {ForemError} subclass. Transient failures
+    # ({APIConnectionError}, {RateLimitError}, server 5xx) are automatically
+    # retried up to {Configuration#max_network_retries} times. Rate-limit
+    # retries honor integer +Retry-After+ seconds; other retries use
+    # exponential back-off.
+    #
+    # @param method [Symbol] the HTTP verb — +:get+, +:post+, +:put+, or
+    #   +:delete+.
+    # @param path [String] the API path relative to {Configuration#api_base}
+    #   (e.g. +"/api/articles"+).
+    # @param params [Hash] query parameters for GET requests, or the JSON
+    #   request body for POST/PUT requests. Defaults to +{}+.
+    # @param opts [Hash] per-request overrides.
+    # @option opts [String] :api_key override the API key for this request.
+    # @option opts [String] :api_base override the base URL for this request.
+    # @option opts [APIRequestor] :requestor an alternative requestor to use
+    #   (consumed by higher-level helpers before reaching this method).
+    # @return [ForemResponse] the parsed response wrapper.
+    # @raise [AuthenticationError] on HTTP 401.
+    # @raise [AuthorizationError] on HTTP 403.
+    # @raise [NotFoundError] on HTTP 404.
+    # @raise [ConflictError] on HTTP 409.
+    # @raise [InvalidRequestError] on HTTP 422.
+    # @raise [RateLimitError] on HTTP 429.
+    # @raise [APIError] on other HTTP 4xx/5xx responses.
+    # @raise [APIConnectionError] when a network-level error prevents the
+    #   request from reaching the server and retries are exhausted.
+    #
+    # @example Fetching articles with pagination
+    #   resp = requestor.request(:get, "/api/articles", { page: 2, per_page: 10 })
+    #   resp.http_status  #=> 200
+    #   resp.parsed_body  #=> [{ "id" => 1, ... }, ...]
+    #
+    # @see https://developers.forem.com/api/v1
+    def request(method, path, params = {}, opts = {})
+      api_key = opts.delete(:api_key) || @config.api_key
+      api_base = opts.delete(:api_base) || @config.api_base
+      extra_headers = opts.delete(:headers) || {}
+      uri = URI("#{api_base}#{path}")
+
+      retries_left = @config.max_network_retries
+      begin
+        response = execute_request(method, uri, params, api_key, extra_headers)
+        handle_error_response(response) if response.http_status >= 400
+        response
+      rescue Forem::APIConnectionError
+        if retries_left > 0
+          retries_left -= 1
+          sleep backoff_duration(@config.max_network_retries - retries_left)
+          retry
+        end
+        raise
+      rescue Forem::RateLimitError, Forem::APIError => e
+        if retries_left > 0 && retryable_error?(e)
+          retries_left -= 1
+          retry_count = @config.max_network_retries - retries_left
+          sleep retry_delay(e, retry_count)
+          retry
+        end
+        raise
+      end
+    end
+
+    private
+
+    # Send the HTTP request through the connection manager and return a
+    # {ForemResponse}.
+    #
+    # @param method [Symbol] the HTTP verb.
+    # @param uri [URI] the fully-qualified request URI.
+    # @param params [Hash] parameters/body payload.
+    # @param api_key [String, nil] the API key to attach.
+    # @return [ForemResponse]
+    # @raise [APIConnectionError] on any network-level exception.
+    def execute_request(method, uri, params, api_key, extra_headers = {})
+      http = @connection_manager.connection_for(uri, open_timeout: @config.open_timeout, read_timeout: @config.read_timeout)
+      request = build_request(method, uri, params, api_key, extra_headers)
+
+      begin
+        http_response = http.request(request)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT, Errno::EHOSTUNREACH, SocketError => e
+        raise APIConnectionError.new("Connection to #{uri.host} failed: #{e.message}")
+      end
+
+      ForemResponse.new(
+        http_status: http_response.code.to_i,
+        http_body: http_response.body,
+        http_headers: headers_to_hash(http_response)
+      )
+    end
+
+    # Build a Net::HTTPRequest object for the given method and parameters.
+    #
+    # Sets +api-key+, +Accept+, and +User-Agent+ headers on every request.
+    # POST and PUT requests encode +params+ as a JSON body and set
+    # +Content-Type: application/json+. GET requests append +params+ as a
+    # URL query string.
+    #
+    # @param method [Symbol] the HTTP verb (+:get+, +:post+, +:put+, +:delete+).
+    # @param uri [URI] the request URI (modified in-place for GET params).
+    # @param params [Hash] the parameters or body payload.
+    # @param api_key [String, nil] the API key value.
+    # @return [Net::HTTPRequest] the fully-configured request object.
+    # @raise [ArgumentError] if +method+ is not one of the supported verbs.
+    def build_request(method, uri, params, api_key, extra_headers = {})
+      req = case method
+            when :get
+              uri.query = URI.encode_www_form(params) unless params.empty?
+              Net::HTTP::Get.new(uri)
+            when :post
+              r = Net::HTTP::Post.new(uri)
+              r.body = JSON.generate(params) unless params.empty?
+              r["Content-Type"] = "application/json"
+              r
+            when :put
+              r = Net::HTTP::Put.new(uri)
+              r.body = JSON.generate(params) unless params.empty?
+              r["Content-Type"] = "application/json"
+              r
+            when :delete
+              Net::HTTP::Delete.new(uri)
+            else
+              raise ArgumentError, "Unsupported HTTP method: #{method}"
+            end
+
+      req["api-key"] = api_key if api_key
+      req["Accept"] = "application/vnd.forem.api-v1+json"
+      req["User-Agent"] = "forem-ruby/#{Forem::VERSION} ruby/#{RUBY_VERSION}"
+      extra_headers.each { |name, value| req[name.to_s] = value.to_s }
+      req
+    end
+
+    # Raise the appropriate {ForemError} subclass for a non-2xx response.
+    #
+    # @param response [ForemResponse] the error response.
+    # @return [void]
+    # @raise [ForemError] always raises a subclass matching the HTTP status.
+    def handle_error_response(response)
+      message = extract_error_message(response)
+      kwargs = {
+        http_status: response.http_status,
+        http_body: response.http_body,
+        http_headers: response.http_headers,
+        code: extract_error_code(response),
+      }
+
+      error_class = case response.http_status
+                    when 401 then AuthenticationError
+                    when 403 then AuthorizationError
+                    when 404 then NotFoundError
+                    when 409 then ConflictError
+                    when 422 then InvalidRequestError
+                    when 429 then RateLimitError
+                    else APIError
+                    end
+
+      raise error_class.new(message, **kwargs)
+    end
+
+    # Extract a human-readable error message from an error response.
+    #
+    # Looks for +error+ (string) or +errors+ (array) keys in the JSON body.
+    # Falls back to the raw body string if parsing fails or the expected keys
+    # are absent.
+    #
+    # @param response [ForemResponse] the error response.
+    # @return [String] the best available error message.
+    def extract_error_message(response)
+      body = response.parsed_body
+      return response.http_body unless body.is_a?(Hash)
+
+      if body["error"]
+        body["error"]
+      elsif body["errors"].is_a?(Array)
+        body["errors"].join(", ")
+      else
+        response.http_body
+      end
+    rescue JSON::ParserError
+      response.http_body
+    end
+
+    # Extract a machine-readable error code from an error response.
+    #
+    # @param response [ForemResponse] the error response.
+    # @return [String, nil] the +error_code+ value, or +nil+ when unavailable.
+    def extract_error_code(response)
+      body = response.parsed_body
+      body["error_code"] if body.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Convert a Net::HTTPResponse header enumerable into a plain Hash.
+    #
+    # @param http_response [Net::HTTPResponse] the raw response object.
+    # @return [Hash{String => String}] downcased header names mapped to values.
+    def headers_to_hash(http_response)
+      h = {}
+      http_response.each_header { |k, v| h[k] = v }
+      h
+    end
+
+    # Determine whether a given error is eligible for an automatic retry.
+    #
+    # {RateLimitError} is always retryable. {APIError} is retryable only when
+    # the HTTP status is 500 or greater (server errors).
+    #
+    # @param error [ForemError] the error to evaluate.
+    # @return [Boolean] +true+ if the request should be retried.
+    def retryable_error?(error)
+      case error
+      when RateLimitError then true
+      when APIError then error.http_status >= 500
+      else false
+      end
+    end
+
+    # Calculate the delay for a retryable HTTP error.
+    #
+    # Rate-limit responses with an integer +Retry-After+ header use the
+    # server-provided delay. All other retryable errors retain the standard
+    # jittered exponential back-off.
+    #
+    # @param error [ForemError] the retryable error.
+    # @param retry_count [Integer] the 1-based retry count.
+    # @return [Numeric] seconds to sleep.
+    def retry_delay(error, retry_count)
+      retry_after = error.retry_after if error.is_a?(RateLimitError)
+      retry_after || backoff_duration(retry_count)
+    end
+
+    # Calculate the sleep duration before the next retry attempt.
+    #
+    # Uses truncated exponential back-off with jitter:
+    # <tt>(0.5 * 2^retry_count) + rand(0..0.5)</tt> seconds.
+    #
+    # @param retry_count [Integer] how many retries have already been attempted
+    #   (1-based: pass 1 for the first retry).
+    # @return [Float] seconds to sleep before retrying.
+    def backoff_duration(retry_count)
+      (0.5 * (2**retry_count)) + rand * 0.5
+    end
+  end
+end

data/lib/forem/api_resource.rb

@@ -0,0 +1,77 @@
+module Forem
+  # Base class for all Forem API resource objects (articles, users, etc.).
+  #
+  # {APIResource} extends {ForemObject} with the concepts of a canonical
+  # resource path and the ability to refresh an instance from the API.
+  # Concrete resource classes must define a +RESOURCE_PATH+ constant
+  # (e.g. <tt>"/api/articles"</tt>).
+  #
+  # Resource classes mix in {APIOperations::Request} so that both the class
+  # and its instances can issue authenticated HTTP requests. Class methods
+  # require an explicit +:requestor+ option (normally injected by a
+  # {Forem::Client} via its service objects); instance methods fall back to
+  # the requestor stored on the object at construction time.
+  #
+  # @example Defining a resource subclass
+  #   class Forem::Article < Forem::APIResource
+  #     RESOURCE_PATH = "/api/articles"
+  #     extend APIOperations::List
+  #     extend APIOperations::Retrieve
+  #   end
+  class APIResource < ForemObject
+    # Return the API collection path for this resource class.
+    #
+    # Delegates to the +RESOURCE_PATH+ constant that every concrete subclass
+    # must define.
+    #
+    # @return [String] the collection path, e.g. <tt>"/api/articles"</tt>.
+    # @raise [NameError] if the subclass has not defined +RESOURCE_PATH+.
+    #
+    # @example
+    #   Forem::Article.resource_path  #=> "/api/articles"
+    def self.resource_path
+      self::RESOURCE_PATH
+    end
+
+    # Return the API path for this specific resource instance.
+    #
+    # Combines {.resource_path} with the instance's +id+ attribute.
+    #
+    # @return [String] the instance path, e.g. <tt>"/api/articles/42"</tt>.
+    # @raise [InvalidRequestError] if the instance does not have an +id+
+    #   attribute (i.e. the object was not constructed from a full API
+    #   response).
+    #
+    # @example
+    #   article.resource_url  #=> "/api/articles/42"
+    def resource_url
+      id = self["id"]
+      raise InvalidRequestError.new("Could not determine resource ID") unless id
+      "#{self.class.resource_path}/#{id}"
+    end
+
+    # Reload this resource instance from the API, replacing all attributes
+    # with the latest server data.
+    #
+    # @param opts [Hash] per-request options forwarded to {APIRequestor#request}.
+    # @option opts [String] :api_key override the API key for this request.
+    # @option opts [APIRequestor] :requestor a custom requestor to use.
+    # @return [self] the same instance, now populated with refreshed data.
+    # @raise [InvalidRequestError] if the instance has no +id+.
+    # @raise [NotFoundError] if the resource no longer exists on the server.
+    # @raise [ForemError] for other API-level errors.
+    #
+    # @example
+    #   article = client.articles.retrieve(42)
+    #   # ... time passes ...
+    #   article.refresh   #=> same article object with updated attributes
+    #
+    # @see https://developers.forem.com/api/v1
+    def refresh(opts = {})
+      resp = request(:get, resource_url, {}, opts)
+      @values = {}
+      send(:update_attributes, resp.parsed_body)
+      self
+    end
+  end
+end

data/lib/forem/client.rb

@@ -0,0 +1,279 @@
+module Forem
+  # Client for making authenticated requests to the Forem API.
+  #
+  # Use this when you need per-instance configuration (e.g., different API keys
+  # for different Forem instances). For simple single-instance use, configure
+  # the global {Forem.api_key} instead.
+  #
+  # @example Basic client usage
+  #   client = Forem::Client.new("your-api-key")
+  #   articles = client.articles.list(per_page: 10)
+  #
+  # @example Connecting to a custom Forem instance
+  #   client = Forem::Client.new("key", api_base: "https://my-forem.com")
+  #   user = client.users.me
+  #
+  # @see https://developers.forem.com/api/v1
+  class Client
+    # @return [Configuration] the configuration object for this client
+    attr_reader :config
+
+    # @return [APIRequestor] the requestor used to make HTTP calls
+    attr_reader :requestor
+
+    # Create a new Forem API client.
+    #
+    # @param api_key [String] your Forem API key
+    # @param api_base [String] base URL for the Forem API (default: "https://dev.to")
+    # @param opts [Hash] additional configuration options passed to {Configuration}
+    # @return [Client] a new client instance
+    #
+    # @example
+    #   client = Forem::Client.new("my-secret-api-key")
+    #
+    # @example With a custom Forem instance
+    #   client = Forem::Client.new("my-key", api_base: "https://community.example.com")
+    def initialize(api_key, api_base: "https://dev.to", **opts)
+      @config = Configuration.new
+      @config.api_key = api_key
+      @config.api_base = api_base
+      opts.each { |k, v| @config.send(:"#{k}=", v) if @config.respond_to?(:"#{k}=") }
+      @requestor = APIRequestor.new(config: @config)
+    end
+
+    # Access the Articles API.
+    #
+    # @return [Services::ArticleService] the articles service
+    # @see https://developers.forem.com/api/v1#tag/articles
+    #
+    # @example
+    #   client.articles.list(per_page: 5)
+    #   client.articles.retrieve(12345)
+    def articles;                    @articles ||= Services::ArticleService.new(@requestor); end
+
+    # Access the Users API.
+    #
+    # @return [Services::UserService] the users service
+    # @see https://developers.forem.com/api/v1#tag/users
+    #
+    # @example
+    #   client.users.me
+    #   client.users.retrieve(42)
+    def users;                       @users ||= Services::UserService.new(@requestor); end
+
+    # Access the Comments API.
+    #
+    # @return [Services::CommentService] the comments service
+    # @see https://developers.forem.com/api/v1#tag/comments
+    #
+    # @example
+    #   client.comments.list(a_id: 123)
+    #   client.comments.retrieve("abc123")
+    def comments;                    @comments ||= Services::CommentService.new(@requestor); end
+
+    # Access the Organizations API.
+    #
+    # @return [Services::OrganizationService] the organizations service
+    # @see https://developers.forem.com/api/v1#tag/organizations
+    #
+    # @example
+    #   client.organizations.list
+    #   client.organizations.retrieve(7)
+    def organizations;               @organizations ||= Services::OrganizationService.new(@requestor); end
+
+    # Access the Tags API.
+    #
+    # @return [Services::TagService] the tags service
+    # @see https://developers.forem.com/api/v1#tag/tags
+    #
+    # @example
+    #   client.tags.list(per_page: 20)
+    def tags;                        @tags ||= Services::TagService.new(@requestor); end
+
+    # Access the Follows API.
+    #
+    # @return [Services::FollowService] the follows service
+    # @see https://developers.forem.com/api/v1#tag/follows
+    #
+    # @example
+    #   client.follows.list
+    #   client.follows.create(followable_type: "User", followable_id: 99)
+    def follows;                     @follows ||= Services::FollowService.new(@requestor); end
+
+    # Access the Followers API.
+    #
+    # @return [Services::FollowerService] the followers service
+    # @see https://developers.forem.com/api/v1#tag/followers
+    #
+    # @example
+    #   client.followers.list(per_page: 50)
+    def followers;                   @followers ||= Services::FollowerService.new(@requestor); end
+
+    # Access the Reading List API.
+    #
+    # @return [Services::ReadingListService] the reading list service
+    # @see https://developers.forem.com/api/v1#tag/readinglist
+    #
+    # @example
+    #   client.reading_list.list(page: 1)
+    def reading_list;                @reading_list ||= Services::ReadingListService.new(@requestor); end
+
+    # Access the Podcast Episodes API.
+    #
+    # @return [Services::PodcastEpisodeService] the podcast episodes service
+    # @see https://developers.forem.com/api/v1#tag/podcast-episodes
+    #
+    # @example
+    #   client.podcast_episodes.list(username: "someshow")
+    def podcast_episodes;            @podcast_episodes ||= Services::PodcastEpisodeService.new(@requestor); end
+
+    # Access the Videos API.
+    #
+    # @return [Services::VideoService] the videos service
+    # @see https://developers.forem.com/api/v1#tag/videos
+    #
+    # @example
+    #   client.videos.list(page: 1)
+    def videos;                      @videos ||= Services::VideoService.new(@requestor); end
+
+    # Access the Profile Images API.
+    #
+    # @return [Services::ProfileImageService] the profile images service
+    # @see https://developers.forem.com/api/v1#tag/profile-images
+    #
+    # @example
+    #   client.profile_images.retrieve("jsmith")
+    def profile_images;              @profile_images ||= Services::ProfileImageService.new(@requestor); end
+
+    # Access the Billboards API.
+    #
+    # @return [Services::BillboardService] the billboards service
+    # @see https://developers.forem.com/api/v1#tag/billboards
+    #
+    # @example
+    #   client.billboards.list
+    #   client.billboards.retrieve(3)
+    def billboards;                  @billboards ||= Services::BillboardService.new(@requestor); end
+
+    # Access the Pages API.
+    #
+    # @return [Services::PageService] the pages service
+    # @see https://developers.forem.com/api/v1#tag/pages
+    #
+    # @example
+    #   client.pages.list
+    #   client.pages.create(title: "About", slug: "about", body_markdown: "...")
+    def pages;                       @pages ||= Services::PageService.new(@requestor); end
+
+    # Access the Segments API.
+    #
+    # @return [Services::SegmentService] the segments service
+    # @see https://developers.forem.com/api/v1#tag/segments
+    #
+    # @example
+    #   client.segments.list
+    #   client.segments.retrieve(5)
+    def segments;                    @segments ||= Services::SegmentService.new(@requestor); end
+
+    # Access the Reactions API.
+    #
+    # @return [Services::ReactionService] the reactions service
+    # @see https://developers.forem.com/api/v1#tag/reactions
+    #
+    # @example
+    #   client.reactions.create(reactable_type: "Article", reactable_id: 1, category: "like")
+    #   client.reactions.toggle(reactable_type: "Article", reactable_id: 1, category: "like")
+    def reactions;                   @reactions ||= Services::ReactionService.new(@requestor); end
+
+    # Access the Recommended Articles Lists API.
+    #
+    # @return [Services::RecommendedArticlesListService] the recommended articles lists service
+    # @see https://developers.forem.com/api/v1#tag/articles
+    #
+    # @example
+    #   client.recommended_articles_lists.list
+    #   client.recommended_articles_lists.retrieve(2)
+    def recommended_articles_lists;  @recommended_articles_lists ||= Services::RecommendedArticlesListService.new(@requestor); end
+
+    # Access the Agent Sessions API.
+    #
+    # @return [Services::AgentSessionService] the agent sessions service
+    # @see https://developers.forem.com/api/v1
+    #
+    # @example
+    #   client.agent_sessions.list
+    #   client.agent_sessions.presign(filename: "upload.jpg")
+    def agent_sessions;              @agent_sessions ||= Services::AgentSessionService.new(@requestor); end
+
+    # Access the Surveys API.
+    #
+    # @return [Services::SurveyService] the surveys service
+    # @see https://developers.forem.com/api/v1
+    #
+    # @example
+    #   client.surveys.list
+    #   client.surveys.retrieve(8)
+    def surveys;                     @surveys ||= Services::SurveyService.new(@requestor); end
+
+    # Access the Analytics API.
+    #
+    # @return [Services::AnalyticsService] the analytics service
+    # @see https://developers.forem.com/api/v1#tag/analytics
+    #
+    # @example
+    #   client.analytics.totals(username: "jsmith")
+    #   client.analytics.historical(username: "jsmith", start: "2024-01-01")
+    def analytics;                   @analytics ||= Services::AnalyticsService.new(@requestor); end
+
+    # Access the Health Checks API.
+    #
+    # @return [Services::HealthCheckService] the health check service
+    # @see https://developers.forem.com/api/v1#tag/health-checks
+    #
+    # @example
+    #   client.health_checks.app
+    #   client.health_checks.database
+    def health_checks;               @health_checks ||= Services::HealthCheckService.new(@requestor); end
+
+    # Access the Admin Users API.
+    #
+    # @return [Services::AdminUserService] the admin users service
+    # @see https://developers.forem.com/api/v1#tag/users
+    #
+    # @example
+    #   client.admin_users.create(email: "new@example.com", name: "New User")
+    def admin_users;                 @admin_users ||= Services::AdminUserService.new(@requestor); end
+
+    # Access the Trends API.
+    #
+    # @return [Services::TrendService] the trends service
+    #
+    # @example
+    #   client.trends.list
+    def trends;                      @trends ||= Services::TrendService.new(@requestor); end
+
+    # Access the Concepts API.
+    #
+    # @return [Services::ConceptService] the concepts service
+    #
+    # @example
+    #   client.concepts.list
+    def concepts;                    @concepts ||= Services::ConceptService.new(@requestor); end
+
+    # Access the Admin Concepts API.
+    #
+    # @return [Services::AdminConceptService] the admin concepts service
+    #
+    # @example
+    #   client.admin_concepts.list
+    def admin_concepts;              @admin_concepts ||= Services::AdminConceptService.new(@requestor); end
+
+    # Access the Admin Request Redirects API.
+    #
+    # @return [Services::RequestRedirectService] the request redirects service
+    #
+    # @example
+    #   client.request_redirects.list
+    def request_redirects;           @request_redirects ||= Services::RequestRedirectService.new(@requestor); end
+  end
+end