forem-ruby 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe5320646c371a3a708ad3f52c847bb9580341799d60e16624bb731c47a70dac
+  data.tar.gz: 28292cfa205edaaa90346520b1b4ae448dea0ee698c67dff48c45cd5cdd8fb4c
+SHA512:
+  metadata.gz: 966257cf5cf0b1034a98e227ebdd01801c2fd66667d426c7d07a53bd5d9b0130f3fb82a43b5159126c09afcbbdd83202439504221e499bc7ef62e572457d1be1
+  data.tar.gz: '057930af643ab8c4c90a30a44c9e80066626256eadec4917f2e36c565444d00ea0f0dc4456f223b3bbc30cdad9f2288f480e8dd0f3c326da012668ecb51fbc47'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forem
+
+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/forem-ruby.gemspec

@@ -0,0 +1,17 @@
+require_relative "lib/forem/version"
+
+Gem::Specification.new do |s|
+  s.name = "forem-ruby"
+  s.version = Forem::VERSION
+  s.required_ruby_version = ">= 3.1.0"
+  s.summary = "Ruby client for the Forem API"
+  s.description = "A Ruby client library for the Forem API, modeled after stripe-ruby patterns."
+  s.authors = ["Forem"]
+  s.homepage = "https://github.com/forem/forem-ruby"
+  s.license = "MIT"
+  s.files = Dir["lib/**/*.rb"] + ["forem-ruby.gemspec", "LICENSE"]
+  s.require_paths = ["lib"]
+  s.metadata = {
+    "rubygems_mfa_required" => "true",
+  }
+end

data/lib/forem/api_operations/create.rb

@@ -0,0 +1,47 @@
+module Forem
+  module APIOperations
+    # Adds a +create+ class method to any resource that extends this module.
+    #
+    # Sends a POST request to the resource's collection path with the supplied
+    # parameters as a JSON body, and returns a new resource instance populated
+    # from the API response.
+    #
+    # @example Extending a resource class
+    #   class Forem::Article < Forem::APIResource
+    #     extend APIOperations::Create
+    #   end
+    module Create
+      # Create a new resource via the Forem API.
+      #
+      # Sends a +POST+ request to {APIResource.resource_path} with +params+
+      # serialised as a JSON body. The server response is used to construct
+      # and return a new resource instance.
+      #
+      # @param params [Hash] the attributes for the new resource (e.g.
+      #   <tt>{ article: { title: "Hello", body_markdown: "..." } }</tt>).
+      # @param opts [Hash] per-request options.
+      # @option opts [String] :api_key override the API key for this request.
+      # @option opts [APIRequestor] :requestor a custom requestor to use.
+      # @return [ForemObject] the newly-created resource, constructed from the
+      #   API response body.
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors).
+      # @raise [AuthenticationError] on HTTP 401.
+      # @raise [AuthorizationError] on HTTP 403.
+      # @raise [ForemError] on other API or network errors.
+      #
+      # @example Creating an article
+      #   article = client.articles.create(
+      #     article: { title: "Hello, world!", body_markdown: "**hi**", published: true }
+      #   )
+      #   article.id     #=> 12345
+      #   article.title  #=> "Hello, world!"
+      #
+      # @see https://developers.forem.com/api/v1#tag/articles/operation/createArticle
+      def create(params = {}, opts = {})
+        requestor = opts[:requestor]
+        resp = request(:post, resource_path, params, opts)
+        construct_from(resp.parsed_body, requestor: requestor)
+      end
+    end
+  end
+end

data/lib/forem/api_operations/delete.rb

@@ -0,0 +1,88 @@
+module Forem
+  module APIOperations
+    # Adds +delete+ as both a class method and an instance method to any
+    # resource that includes this module.
+    #
+    # The class method deletes by ID; the instance method deletes the receiver
+    # using its own {APIResource#resource_url}. Both methods return a resource
+    # object if the server responds with a body, otherwise they return +nil+
+    # (class method) or +self+ (instance method).
+    #
+    # The +self.included+ hook extends the including class with {ClassMethods}
+    # so the class-level +delete+ is available alongside the instance method.
+    #
+    # @example Extending a resource class
+    #   class Forem::Article < Forem::APIResource
+    #     include APIOperations::Delete
+    #   end
+    module Delete
+      # Hook called when {Delete} is included in a class.
+      #
+      # Extends the including class with {ClassMethods}.
+      #
+      # @param base [Class] the class including this module.
+      # @return [void]
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level delete helpers.
+      module ClassMethods
+        # Delete a resource by its ID via the Forem API.
+        #
+        # Sends a +DELETE+ request to <tt>{resource_path}/{id}</tt>. If the
+        # server responds with a non-empty body it is used to construct a
+        # resource instance (representing the deleted object); otherwise
+        # +nil+ is returned.
+        #
+        # @param id [Integer, String] the unique identifier of the resource to
+        #   delete.
+        # @param opts [Hash] per-request options.
+        # @option opts [String] :api_key override the API key for this request.
+        # @option opts [APIRequestor] :requestor a custom requestor to use.
+        # @return [ForemObject, nil] the deleted resource (if the API returns
+        #   a body), or +nil+.
+        # @raise [NotFoundError] on HTTP 404.
+        # @raise [AuthenticationError] on HTTP 401.
+        # @raise [AuthorizationError] on HTTP 403.
+        # @raise [ForemError] on other API or network errors.
+        #
+        # @example Deleting an article by ID
+        #   client.articles.delete(12345)
+        #
+        # @see https://developers.forem.com/api/v1
+        def delete(id, opts = {})
+          requestor = opts[:requestor]
+          resp = request(:delete, "#{resource_path}/#{id}", {}, opts)
+          resp.parsed_body ? construct_from(resp.parsed_body, requestor: requestor) : nil
+        end
+      end
+
+      # Delete this resource instance via the Forem API.
+      #
+      # Sends a +DELETE+ request to this instance's {APIResource#resource_url}.
+      # If the server responds with a non-empty body it is used to construct
+      # a new resource instance (representing the deleted state); otherwise
+      # +self+ is returned.
+      #
+      # @param opts [Hash] per-request options.
+      # @option opts [String] :api_key override the API key for this request.
+      # @option opts [APIRequestor] :requestor a custom requestor to use.
+      # @return [ForemObject] a new resource instance built from the response
+      #   body, or +self+ if the response has no body.
+      # @raise [InvalidRequestError] if the instance has no +id+.
+      # @raise [NotFoundError] on HTTP 404.
+      # @raise [AuthenticationError] on HTTP 401.
+      # @raise [AuthorizationError] on HTTP 403.
+      # @raise [ForemError] on other API or network errors.
+      #
+      # @example Deleting the current instance
+      #   article.delete
+      def delete(opts = {})
+        requestor = opts[:requestor] || @requestor
+        resp = request(:delete, resource_url, {}, opts)
+        resp.parsed_body ? self.class.construct_from(resp.parsed_body, requestor: requestor) : self
+      end
+    end
+  end
+end

data/lib/forem/api_operations/list.rb

@@ -0,0 +1,70 @@
+module Forem
+  module APIOperations
+    # Adds a +list+ class method to any resource that extends this module.
+    #
+    # Fetches a paginated collection from the resource's path and wraps the
+    # result in a {ListObject} that supports manual and automatic pagination.
+    #
+    # @example Extending a resource class
+    #   class Forem::Article < Forem::APIResource
+    #     extend APIOperations::List
+    #   end
+    module List
+      # Retrieve a paginated list of resources from the Forem API.
+      #
+      # Sends a +GET+ request to {APIResource.resource_path} with +params+
+      # appended as query-string parameters. The response array is converted
+      # into an array of resource instances and wrapped in a {ListObject} that
+      # exposes pagination helpers.
+      #
+      # Pagination defaults: +page+ 1, +per_page+ 30 (matching Forem API
+      # defaults). These can be overridden via +params+.
+      #
+      # @param params [Hash] query parameters for filtering and pagination.
+      # @option params [Integer] :page the page number to fetch (default +1+).
+      # @option params [Integer] :per_page the number of items per page
+      #   (default +30+, maximum varies by endpoint).
+      # @option params [String] :tag filter articles by tag (articles endpoint).
+      # @option params [String] :username filter by username.
+      # @option params [String] :state filter by state (e.g. +"fresh"+,
+      #   +"rising"+, +"all"+).
+      # @param opts [Hash] per-request options.
+      # @option opts [String] :api_key override the API key for this request.
+      # @option opts [APIRequestor] :requestor a custom requestor to use and
+      #   to forward to subsequent page fetches.
+      # @return [ListObject] a paginated list object wrapping the current
+      #   page's resources.
+      # @raise [AuthenticationError] on HTTP 401.
+      # @raise [AuthorizationError] on HTTP 403.
+      # @raise [ForemError] on other API or network errors.
+      #
+      # @example Fetching the first page of articles
+      #   articles = client.articles.list(per_page: 10)
+      #   articles.map(&:title)
+      #   #=> ["Article 1", "Article 2", ...]
+      #
+      # @example Filtering articles by tag
+      #   client.articles.list(tag: "ruby", per_page: 5).each do |a|
+      #     puts a.title
+      #   end
+      #
+      # @see https://developers.forem.com/api/v1#tag/articles/operation/getArticles
+      def list(params = {}, opts = {})
+        requestor = opts[:requestor]
+        resp = request(:get, resource_path, params, opts)
+        data = (resp.parsed_body || []).map { |item| construct_from(item, requestor: requestor) }
+        per_page = params[:per_page] || params["per_page"] || 30
+        page = params[:page] || params["page"] || 1
+
+        ListObject.new(
+          data: data,
+          current_page: page.to_i,
+          per_page: per_page.to_i,
+          resource_class: self,
+          filters: params.reject { |k, _| [:page, :per_page, "page", "per_page"].include?(k) },
+          requestor: requestor
+        )
+      end
+    end
+  end
+end

data/lib/forem/api_operations/request.rb

@@ -0,0 +1,83 @@
+module Forem
+  module APIOperations
+    # Provides +request+ as both a class method and an instance method on any
+    # class that includes this module.
+    #
+    # Including {Request} is the only prerequisite for a class to issue
+    # authenticated HTTP requests. It is included in {APIResource} and
+    # therefore inherited by every concrete resource class.
+    #
+    # The module uses a +self.included+ hook to also extend the including
+    # class with {ClassMethods}, making the class-level +request+ available
+    # for module methods such as {APIOperations::Create#create} and
+    # {APIOperations::List#list}.
+    #
+    # The +:requestor+ key in +opts+ is consumed here and never forwarded to
+    # {APIRequestor#request}.
+    module Request
+      # Hook called when {Request} is included in a class.
+      #
+      # @param base [Class] the class including this module.
+      # @return [void]
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level request helpers mixed into every class that includes
+      # {Request}.
+      module ClassMethods
+        # Issue an authenticated HTTP request using the supplied requestor.
+        #
+        # The +:requestor+ key in +opts+ is required — there is no global
+        # default. In normal use this is supplied automatically by a
+        # {Forem::Client} via its service objects.
+        #
+        # @param method [Symbol] the HTTP verb (+:get+, +:post+, +:put+,
+        #   +:delete+).
+        # @param path [String] the API path (e.g. +"/api/articles"+).
+        # @param params [Hash] query parameters or JSON body payload.
+        # @param opts [Hash] per-request options.
+        # @option opts [APIRequestor] :requestor (required) the requestor
+        #   that issues this call. Normally injected by a {Forem::Client}.
+        # @option opts [String] :api_key override the API key for this request.
+        # @option opts [String] :api_base override the base URL for this request.
+        # @return [ForemResponse] the response wrapper.
+        # @raise [ArgumentError] if no +:requestor+ is supplied.
+        # @raise [ForemError] on any API or network error.
+        def request(method, path, params = {}, opts = {})
+          requestor = opts.delete(:requestor)
+          unless requestor
+            raise ArgumentError,
+                  "Forem requires an explicit requestor — call this method " \
+                  "through a Forem::Client (e.g. client.articles.list)."
+          end
+          requestor.request(method, path, params, opts)
+        end
+      end
+
+      # Issue an authenticated HTTP request on behalf of this resource
+      # instance.
+      #
+      # Falls back to the requestor stored on the instance (set when the
+      # object was constructed by a service call) if no explicit
+      # +:requestor+ is supplied in +opts+. Delegates to the class-level
+      # {ClassMethods#request} for the actual transport.
+      #
+      # @param method [Symbol] the HTTP verb.
+      # @param path [String] the API path.
+      # @param params [Hash] query parameters or JSON body payload.
+      # @param opts [Hash] per-request options.
+      # @option opts [APIRequestor] :requestor override the instance's
+      #   stored requestor for this call.
+      # @return [ForemResponse] the response wrapper.
+      # @raise [ArgumentError] if neither the instance nor +opts+ supply a
+      #   requestor.
+      # @raise [ForemError] on any API or network error.
+      def request(method, path, params = {}, opts = {})
+        opts = opts.dup
+        opts[:requestor] ||= @requestor if instance_variable_defined?(:@requestor)
+        self.class.request(method, path, params, opts)
+      end
+    end
+  end
+end

data/lib/forem/api_operations/retrieve.rb

@@ -0,0 +1,43 @@
+module Forem
+  module APIOperations
+    # Adds a +retrieve+ class method to any resource that extends this module.
+    #
+    # Fetches a single resource by its ID with a GET request and returns a
+    # resource instance populated from the API response.
+    #
+    # @example Extending a resource class
+    #   class Forem::Article < Forem::APIResource
+    #     extend APIOperations::Retrieve
+    #   end
+    module Retrieve
+      # Retrieve a single resource by its ID from the Forem API.
+      #
+      # Sends a +GET+ request to <tt>{resource_path}/{id}</tt> and constructs
+      # a resource instance from the response body.
+      #
+      # @param id [Integer, String] the unique identifier of the resource to
+      #   fetch.
+      # @param opts [Hash] per-request options.
+      # @option opts [String] :api_key override the API key for this request.
+      # @option opts [APIRequestor] :requestor a custom requestor to use.
+      # @return [ForemObject] the resource instance populated with data from
+      #   the API response.
+      # @raise [NotFoundError] on HTTP 404 (resource does not exist).
+      # @raise [AuthenticationError] on HTTP 401.
+      # @raise [AuthorizationError] on HTTP 403.
+      # @raise [ForemError] on other API or network errors.
+      #
+      # @example Fetching an article by ID
+      #   article = client.articles.retrieve(12345)
+      #   article.title   #=> "Hello, world!"
+      #   article.id      #=> 12345
+      #
+      # @see https://developers.forem.com/api/v1#tag/articles/operation/getArticleById
+      def retrieve(id, opts = {})
+        requestor = opts[:requestor]
+        resp = request(:get, "#{resource_path}/#{id}", {}, opts)
+        construct_from(resp.parsed_body, requestor: requestor)
+      end
+    end
+  end
+end

data/lib/forem/api_operations/save.rb

@@ -0,0 +1,53 @@
+module Forem
+  module APIOperations
+    # Adds a +save+ instance method to any resource that includes this module.
+    #
+    # +save+ is the instance-level complement to the class-level
+    # {APIOperations::Update#update}. It persists the current resource to the
+    # API by issuing a PUT request to the instance's own
+    # {APIResource#resource_url}, and returns a new resource object reflecting
+    # the server's response.
+    #
+    # @example Including in a resource class
+    #   class Forem::Article < Forem::APIResource
+    #     include APIOperations::Save
+    #   end
+    module Save
+      # Save (update) this resource instance via the Forem API.
+      #
+      # Sends a +PUT+ request to {APIResource#resource_url} with +params+
+      # serialised as a JSON body. The server response is used to construct
+      # and return a new resource instance representing the updated state.
+      #
+      # Unlike {APIResource#refresh}, which reloads in-place, +save+ returns
+      # a *new* instance and does not mutate the receiver.
+      #
+      # @param params [Hash] the attributes to update (e.g.
+      #   <tt>{ article: { title: "New title" } }</tt>). Defaults to +{}+.
+      # @param opts [Hash] per-request keyword options.
+      # @option opts [String] :api_key override the API key for this request.
+      # @option opts [APIRequestor] :requestor a custom requestor to use.
+      # @return [ForemObject] a new resource instance populated with the
+      #   updated data returned by the API.
+      # @raise [InvalidRequestError] if this instance has no +id+ (via
+      #   {APIResource#resource_url}).
+      # @raise [NotFoundError] on HTTP 404.
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors).
+      # @raise [AuthenticationError] on HTTP 401.
+      # @raise [AuthorizationError] on HTTP 403.
+      # @raise [ForemError] on other API or network errors.
+      #
+      # @example Updating a fetched article
+      #   article = client.articles.retrieve(12345)
+      #   updated = article.save(article: { title: "Brand new title" })
+      #   updated.title  #=> "Brand new title"
+      #
+      # @see https://developers.forem.com/api/v1#tag/articles/operation/updateArticle
+      def save(params = {}, **opts)
+        requestor = opts[:requestor] || @requestor
+        resp = request(:put, resource_url, params, opts)
+        self.class.construct_from(resp.parsed_body, requestor: requestor)
+      end
+    end
+  end
+end

data/lib/forem/api_operations/update.rb

@@ -0,0 +1,47 @@
+module Forem
+  module APIOperations
+    # Adds an +update+ class method to any resource that extends this module.
+    #
+    # Sends a PUT request to a specific resource URL with the supplied
+    # parameters as a JSON body, and returns a new resource instance
+    # constructed from the API response.
+    #
+    # @example Extending a resource class
+    #   class Forem::Article < Forem::APIResource
+    #     extend APIOperations::Update
+    #   end
+    module Update
+      # Update an existing resource via the Forem API.
+      #
+      # Sends a +PUT+ request to <tt>{resource_path}/{id}</tt> with +params+
+      # serialised as a JSON body, and returns a new resource instance
+      # reflecting the updated state as returned by the server.
+      #
+      # @param id [Integer, String] the unique identifier of the resource to
+      #   update.
+      # @param params [Hash] the attributes to update (e.g.
+      #   <tt>{ article: { title: "New title" } }</tt>).
+      # @param opts [Hash] per-request options.
+      # @option opts [String] :api_key override the API key for this request.
+      # @option opts [APIRequestor] :requestor a custom requestor to use.
+      # @return [ForemObject] a resource instance populated with the updated
+      #   data returned by the API.
+      # @raise [NotFoundError] on HTTP 404 (resource does not exist).
+      # @raise [InvalidRequestError] on HTTP 422 (validation errors).
+      # @raise [AuthenticationError] on HTTP 401.
+      # @raise [AuthorizationError] on HTTP 403.
+      # @raise [ForemError] on other API or network errors.
+      #
+      # @example Updating an article's title
+      #   article = client.articles.update(12345, article: { title: "Updated title" })
+      #   article.title  #=> "Updated title"
+      #
+      # @see https://developers.forem.com/api/v1#tag/articles/operation/updateArticle
+      def update(id, params = {}, opts = {})
+        requestor = opts[:requestor]
+        resp = request(:put, "#{resource_path}/#{id}", params, opts)
+        construct_from(resp.parsed_body, requestor: requestor)
+      end
+    end
+  end
+end