forem-ruby 0.1.0.beta1

data/lib/forem/resources/concept.rb

@@ -0,0 +1,192 @@
+module Forem
+  # Represents a Forem concept (a semantic, ML-generated tag).
+  #
+  # Concepts are semantic categories derived from article embeddings rather
+  # than from explicit user tags: each concept carries an anchor embedding
+  # generated from its +description+, and articles whose embeddings fall
+  # within the concept's +similarity_threshold+ are classified under it.
+  # They are used for advanced semantic categorization, automated feeds, and
+  # interest mapping.
+  #
+  # The public concepts endpoints are readable by any authenticated user (a
+  # super admin sees every concept, other users see the concepts they have
+  # been granted access to). Creating and deleting concepts is an admin-only
+  # operation exposed separately under +/api/admin/concepts+.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/concepts
+  #   - +Update+   — PUT /api/concepts/:id
+  #
+  # Custom class methods:
+  #   - +retrieve+ — GET /api/concepts/:id
+  #   - +articles+ — GET /api/concepts/:id/articles
+  #   - +search+   — GET /api/concepts/search
+  #
+  # == Concept Fields
+  #
+  # - +id+ (Integer) — Unique concept ID
+  # - +name+ (String) — Human readable label for the concept
+  # - +slug+ (String) — URL-friendly identifier
+  # - +description+ (String, nullable) — Semantic definition used to generate
+  #   the concept's anchor embedding
+  # - +parent_id+ (Integer, nullable) — Parent concept when using a hierarchy
+  # - +score+ (Float) — Concept popularity / curation score
+  # - +similarity_threshold+ (Float, nullable) — Cosine distance threshold
+  #   (0.0–1.0) an article embedding must satisfy to be classified under the
+  #   concept
+  # - +created_at+ / +updated_at+ (String) — ISO 8601 timestamps
+  # - +daily_metrics+ (Array) — Nested per-day activity rollups, newest first.
+  #   Each entry has +date+, +articles_count+, +comments_count+,
+  #   +page_views+, +reactions_count+, and +popularity_score+
+  # - +top_articles+ (Array) — Only on +retrieve+ / +update+ responses; the
+  #   three highest-scoring articles for the concept, each with +id+,
+  #   +title+, +slug+, +score+, and +published_at+
+  #
+  # Results from {search} carry two extra fields: +distance+ (cosine distance
+  # from the query embedding) and +similarity+ (+1.0 - distance+).
+  #
+  # @example List concepts with a 30-day metrics window
+  #   concepts = client.concepts.list(per_page: 20, days: 30)
+  #   concepts.each { |c| puts "#{c.id}: #{c.name} (#{c.score})" }
+  #
+  # @example Retrieve a concept and read its nested daily metrics
+  #   concept = client.concepts.retrieve(7)
+  #   concept.daily_metrics.each { |m| puts "#{m.date}: #{m.articles_count}" }
+  #
+  # @example Update a concept (params are wrapped in +concept:+ automatically)
+  #   client.concepts.update(7, description: "Databases and storage engines")
+  #
+  # @example List the articles classified under a concept
+  #   client.concepts.articles(7, sort: "score", per_page: 25).each do |a|
+  #     puts a.title
+  #   end
+  #
+  # @example Semantic search across accessible concepts
+  #   client.concepts.search(q: "vector databases", per_page: 5).each do |c|
+  #     puts "#{c.name}: #{c.similarity}"
+  #   end
+  #
+  # @see https://developers.forem.com/api/v1
+  class Concept < APIResource
+    extend APIOperations::List
+    extend APIOperations::Update
+
+    OBJECT_NAME = "concept"
+    RESOURCE_PATH = "/api/concepts"
+
+    # Retrieve a single concept by its numeric ID.
+    #
+    # Sends a GET request to +/api/concepts/:id+. Unlike the standard
+    # {APIOperations::Retrieve} mixin this accepts query params, because the
+    # endpoint takes a +days+ window that controls how many nested
+    # +daily_metrics+ entries are returned.
+    #
+    # @param id [Integer, String] the concept ID
+    # @param params [Hash] query parameters
+    # @option params [Integer] :days days of activity to include in
+    #   +daily_metrics+ (default: 7, minimum: 1)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::Concept] the concept with the given ID
+    # @example
+    #   Forem::Concept.retrieve(7, { days: 30 }, requestor: requestor)
+    # @see https://developers.forem.com/api/v1
+    def self.retrieve(id, params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "#{resource_path}/#{id}", params, opts)
+      construct_from(resp.parsed_body, requestor: requestor)
+    end
+
+    # Update an existing concept.
+    #
+    # Sends a PUT request to +/api/concepts/:id+. The Forem API expects the
+    # attributes to be nested under a +concept+ key, so flat params are
+    # wrapped automatically; already-wrapped params are passed through
+    # untouched.
+    #
+    # Only +score+, +description+, and +similarity_threshold+ are permitted
+    # by the API. Changing the description regenerates the concept's anchor
+    # embedding, and changing either the description or the similarity
+    # threshold enqueues a background re-classification of existing articles.
+    #
+    # @param id [Integer, String] the concept ID to update
+    # @param params [Hash] concept attributes to change
+    # @option params [Float] :score new curation score
+    # @option params [String] :description new semantic description
+    # @option params [Float] :similarity_threshold new cosine distance
+    #   threshold (0.0–1.0)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::Concept] the updated concept
+    # @example
+    #   Forem::Concept.update(7, { similarity_threshold: 0.8 }, requestor: requestor)
+    # @see https://developers.forem.com/api/v1
+    def self.update(id, params = {}, opts = {})
+      super(id, wrap_params(params), opts)
+    end
+
+    # Return the published articles classified under a concept.
+    #
+    # Sends a GET request to +/api/concepts/:id/articles+. Articles are
+    # ordered by cosine similarity to the concept (closest first), with the
+    # article score as a tiebreaker, unless +sort+ is +"score"+ in which case
+    # they are ordered by article score alone.
+    #
+    # @param id [Integer, String] the concept ID
+    # @param params [Hash] query parameters
+    # @option params [String] :sort +"score"+ to sort by article score;
+    #   omitted or any other value sorts by semantic distance
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page
+    #   (default: 10)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Article>] paginated list of articles
+    #   belonging to the concept
+    # @example
+    #   articles = Forem::Concept.articles(7, { sort: "score" }, requestor: requestor)
+    #   articles.each { |a| puts a.title }
+    # @see https://developers.forem.com/api/v1
+    def self.articles(id, params = {}, opts = {})
+      Forem::Article.paginated_list("#{resource_path}/#{id}/articles", params, opts)
+    end
+
+    # Semantically search the concepts accessible to the caller.
+    #
+    # Sends a GET request to +/api/concepts/search+. The query text is
+    # embedded and compared against each concept's anchor embedding; results
+    # are returned closest-first and are not paginated (only the number of
+    # results is configurable). Each returned concept carries +distance+ and
+    # +similarity+ in addition to the usual concept fields.
+    #
+    # Requires an API key — unlike the other concept endpoints, this action
+    # cannot be called with a session user.
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :q (required) the search text
+    # @option params [Integer] :per_page number of concepts to return
+    #   (default: 10, max: 50)
+    # @option params [Float] :threshold optional maximum cosine distance
+    #   (0.0–2.0); concepts further away are filtered out
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Array<Forem::Concept>] matching concepts, closest first
+    # @example
+    #   results = Forem::Concept.search({ q: "databases" }, requestor: requestor)
+    #   results.each { |c| puts "#{c.name} #{c.distance}" }
+    # @see https://developers.forem.com/api/v1
+    def self.search(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "#{resource_path}/search", params, opts)
+      (resp.parsed_body || []).map { |item| construct_from(item, requestor: requestor) }
+    end
+
+    # Nest flat attributes under the +concept+ key expected by the API.
+    #
+    # @param params [Hash] the caller-supplied attributes
+    # @return [Hash] params wrapped in a +concept+ key, or unchanged if they
+    #   already are
+    def self.wrap_params(params)
+      return params if params.key?(:concept) || params.key?("concept")
+
+      { concept: params }
+    end
+    private_class_method :wrap_params
+  end
+end

data/lib/forem/resources/follow.rb

@@ -0,0 +1,78 @@
+module Forem
+  # Represents a follow relationship — a user, organization, or tag the
+  # authenticated user follows.
+  #
+  # The +list+ endpoint returns followed tags only (the route is
+  # +/api/follows/tags+). The +create+ endpoint follows users and/or
+  # organizations in bulk.
+  #
+  # @example List the tags the authenticated user is following
+  #   follows = client.follows.list(per_page: 10)
+  #   follows.each { |f| puts f.name }
+  #
+  # @example Follow users in bulk
+  #   client.follows.create(user_ids: [42, 99])
+  #   #=> #<Forem::Follow {"outcome" => "followed 2 users"}>
+  #
+  # @example Follow organizations in bulk
+  #   client.follows.create(organization_ids: [7])
+  #
+  # @example Combined call
+  #   client.follows.create(user_ids: [42], organization_ids: [7])
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getFollowedTags
+  class Follow < APIResource
+    OBJECT_NAME = "follow"
+    RESOURCE_PATH = "/api/follows"
+
+    # Return a paginated list of tags followed by the authenticated user.
+    #
+    # Requires authentication. Sends a GET request to +/api/follows/tags+
+    # (the +list+ verb is mapped to the tags collection rather than the
+    # base resource path on this endpoint).
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options
+    # @return [Forem::ListObject<Forem::Follow>] paginated list of followed tags
+    # @example
+    #   follows = client.follows.list(per_page: 10)
+    #   follows.each { |f| puts f.name }
+    # @see https://developers.forem.com/api/v1#/operations/getFollowedTags
+    def self.list(params = {}, opts = {})
+      paginated_list("/api/follows/tags", params, opts)
+    end
+
+    # Follow one or more users and/or organizations on behalf of the
+    # authenticated user.
+    #
+    # Sends a POST request to +/api/follows+. The Forem API does *not*
+    # follow tags through this endpoint (unlike what {#list} returns). It
+    # accepts:
+    #
+    # * +user_ids:+         — Array<Integer> of user IDs to follow
+    # * +organization_ids:+ — Array<Integer> of organization IDs to follow
+    #
+    # The response is an outcome summary (e.g.
+    # +{"outcome" => "followed 2 users"}+), not a full follow record.
+    # If neither param is supplied, the API silently reports
+    # +"followed 0 users"+ — pass +user_ids+ or +organization_ids+
+    # explicitly.
+    #
+    # @param params [Hash] request body
+    # @option params [Array<Integer>] :user_ids list of user IDs to follow
+    # @option params [Array<Integer>] :organization_ids list of org IDs to follow
+    # @param opts [Hash] per-request options
+    # @return [Forem::Follow] the outcome object returned by the API
+    # @example
+    #   client.follows.create(user_ids: [42, 99])
+    #   #=> #<Forem::Follow {"outcome" => "followed 2 users"}>
+    # @see https://developers.forem.com/api/v1
+    def self.create(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:post, resource_path, params, opts)
+      construct_from(resp.parsed_body, requestor: requestor)
+    end
+  end
+end

data/lib/forem/resources/follower.rb

@@ -0,0 +1,56 @@
+module Forem
+  # Represents a user who follows the authenticated user.
+  #
+  # A Follower record describes a user that has subscribed to the
+  # authenticated user's content. Only listing is supported — you cannot
+  # create or delete follower relationships through this resource directly.
+  #
+  # Requires authentication. Default: 80 per page.
+  #
+  # Note: the list endpoint hits +/api/followers/users+ (not +/api/followers+),
+  # and the default page size is 80 (larger than most other resources).
+  #
+  # @example List users who follow the authenticated user
+  #   followers = client.followers.list
+  #   followers.data.each { |f| puts f.name }
+  #
+  # @example Iterate over all followers using auto-pagination
+  #   client.followers.list.auto_paging_each { |f| puts f.username }
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getFollowers
+  class Follower < APIResource
+    OBJECT_NAME = "follower"
+    RESOURCE_PATH = "/api/followers"
+
+    # Return a paginated list of users who follow the authenticated user.
+    #
+    # Requires authentication. Default: 80 per page.
+    #
+    # Sends a GET request to +/api/followers/users+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 80)
+    # @option params [String] :sort sort order; default +'created_at'+; use
+    #   +'-created_at'+ for newest first
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::Follower>] paginated list of followers
+    # @example
+    #   followers = client.followers.list(per_page: 25, sort: "name")
+    #   followers.data.each { |f| puts f.name }
+    # @see https://developers.forem.com/api/v1#/operations/getFollowers
+    def self.list(params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/followers/users", params, opts)
+      data = (resp.parsed_body || []).map { |item| construct_from(item) }
+      per_page = params[:per_page] || params["per_page"] || 80
+      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

data/lib/forem/resources/health_check.rb

@@ -0,0 +1,70 @@
+module Forem
+  # Provides access to the health-check endpoints of a Forem instance.
+  #
+  # Health checks let you verify that the various subsystems of a Forem
+  # deployment are operational. There are three separate checks: the
+  # application server, the database, and the cache layer.
+  #
+  # == Authentication
+  #
+  # In production, the endpoints require an +health-check-token+ header
+  # whose value matches the instance's
+  # +Settings::General.health_check_token+ setting. The Forem controller
+  # bypasses the token check for requests originating from +localhost+,
+  # so a local-development instance accepts unauthenticated calls.
+  #
+  # Pass the token via the +token:+ keyword on each method (or on the
+  # service-level wrapper). The +api-key+ header is *not* used by these
+  # endpoints — the token is a separate, dedicated mechanism.
+  #
+  # @example Production: pass the configured token
+  #   client.health_checks.app(token: ENV.fetch("FOREM_HEALTH_CHECK_TOKEN"))
+  #   #=> #<Forem::ForemObject {"message" => "App is up!"}>
+  #
+  # @example Local-development Forem (token bypassed for localhost)
+  #   client.health_checks.app
+  #   #=> #<Forem::ForemObject {"message" => "App is up!"}>
+  #
+  # @see https://developers.forem.com/api/v1
+  class HealthCheck < APIResource
+    OBJECT_NAME = "health_check"
+    RESOURCE_PATH = "/api/health_checks"
+
+    # Application-server health.
+    # @param token [String, nil] value for the +health-check-token+ header
+    #   (required in production).
+    # @param opts [Hash] per-request options
+    # @return [Forem::ForemObject] response body
+    def self.app(token: nil, **opts)
+      check("/api/health_checks/app", token, opts)
+    end
+
+    # Database connectivity & responsiveness.
+    # @param token [String, nil] value for the +health-check-token+ header.
+    # @param opts [Hash] per-request options
+    # @return [Forem::ForemObject] response body
+    def self.database(token: nil, **opts)
+      check("/api/health_checks/database", token, opts)
+    end
+
+    # Cache (Redis) connectivity & responsiveness.
+    # @param token [String, nil] value for the +health-check-token+ header.
+    # @param opts [Hash] per-request options
+    # @return [Forem::ForemObject] response body
+    def self.cache(token: nil, **opts)
+      check("/api/health_checks/cache", token, opts)
+    end
+
+    def self.check(path, token, opts)
+      requestor = opts[:requestor]
+      opts = opts.dup
+      if token
+        existing = opts[:headers] || {}
+        opts[:headers] = existing.merge("health-check-token" => token)
+      end
+      resp = request(:get, path, {}, opts)
+      Forem::ForemObject.construct_from(resp.parsed_body, requestor: requestor)
+    end
+    private_class_method :check
+  end
+end

data/lib/forem/resources/organization.rb

@@ -0,0 +1,79 @@
+module Forem
+  # Represents a Forem organization (a group account that can publish articles).
+  #
+  # Organizations are team or company accounts on a Forem instance. They
+  # support full CRUD operations and expose sub-collection endpoints for
+  # listing their members and articles. Organizations can be retrieved by
+  # either numeric ID or username slug.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/organizations  (default: 10 per page)
+  #   - +Create+   — POST /api/organizations
+  #   - +Retrieve+ — GET /api/organizations/:id_or_username
+  #   - +Update+   — PUT /api/organizations/:id
+  #   - +Delete+   — instance-level delete
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # @example List all organizations
+  #   orgs = client.organizations.list(per_page: 20)
+  #   orgs.data.each { |o| puts o.name }
+  #
+  # @example Create an organization
+  #   org = client.organizations.create(
+  #     organization: { name: "Acme Corp", summary: "We make things." }
+  #   )
+  #
+  # @example Retrieve an organization by username
+  #   org = client.organizations.retrieve("acme-corp")
+  #   puts org.name
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getOrganizations
+  # @see https://developers.forem.com/api/v1#/operations/createOrganization
+  class Organization < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Delete
+    include APIOperations::Save
+
+    OBJECT_NAME = "organization"
+    RESOURCE_PATH = "/api/organizations"
+
+    # Return the members of this organization.
+    #
+    # Sends a GET request to +/api/organizations/:id/users+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Array<Forem::User>] members of the organization
+    # @example
+    #   org = client.organizations.retrieve("acme-corp")
+    #   org.users.each { |u| puts u.username }
+    # @see https://developers.forem.com/api/v1#/operations/getOrgUsers
+    def users(params = {}, opts = {})
+      resp = request(:get, "#{resource_url}/users", params, opts)
+      (resp.parsed_body || []).map { |item| Forem::User.construct_from(item) }
+    end
+
+    # Return articles published under this organization.
+    #
+    # Sends a GET request to +/api/organizations/:id/articles+.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 30)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Array<Forem::Article>] articles belonging to the organization
+    # @example
+    #   org = client.organizations.retrieve("acme-corp")
+    #   org.articles.each { |a| puts a.title }
+    # @see https://developers.forem.com/api/v1
+    def articles(params = {}, opts = {})
+      resp = request(:get, "#{resource_url}/articles", params, opts)
+      (resp.parsed_body || []).map { |item| Forem::Article.construct_from(item) }
+    end
+  end
+end

data/lib/forem/resources/page.rb

@@ -0,0 +1,52 @@
+module Forem
+  # Represents a custom static page on a Forem instance.
+  #
+  # Pages are CMS-style content pages on a Forem instance (e.g., about
+  # pages, code of conduct).
+  #
+  # Pages are standalone content items (not articles) used for things like
+  # an "About" page, a "Code of Conduct", or any other informational page
+  # that lives at a dedicated URL on the community site. Full CRUD operations
+  # are available, but managing pages requires an admin API key.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/pages
+  #   - +Create+   — POST /api/pages
+  #   - +Retrieve+ — GET /api/pages/:id
+  #   - +Update+   — PUT /api/pages/:id
+  #   - +Delete+   — instance-level delete (DELETE /api/pages/:id)
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # @example List all pages
+  #   pages = client.pages.list
+  #   pages.each { |p| puts "#{p.slug}: #{p.title}" }
+  #
+  # @example Create a new page (flat params — no +page:+ wrapper)
+  #   page = client.pages.create(
+  #     title: "About Us",
+  #     slug: "about",
+  #     body_markdown: "We are a community of developers.",
+  #     is_top_level_path: true
+  #   )
+  #
+  # @example Retrieve a page by ID
+  #   page = client.pages.retrieve(3)
+  #   puts page.title
+  #
+  # @example Delete a page
+  #   page = client.pages.retrieve(3)
+  #   page.delete
+  #
+  # @see https://developers.forem.com/api/v1
+  class Page < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Delete
+    include APIOperations::Save
+
+    OBJECT_NAME = "page"
+    RESOURCE_PATH = "/api/pages"
+  end
+end

data/lib/forem/resources/podcast_episode.rb

@@ -0,0 +1,36 @@
+module Forem
+  # Represents a podcast episode published on a Forem instance.
+  #
+  # Podcast episodes are audio content items associated with a podcast channel.
+  # The public API supports listing episodes, optionally filtered by username
+  # (the podcast owner) or a specific podcast slug.
+  #
+  # Returns active episodes from published podcasts, ordered by descending
+  # publication date. Default: 30 per page.
+  #
+  # Available operations (via mixins):
+  #   - +List+ — GET /api/podcast_episodes
+  #
+  # @example List all podcast episodes
+  #   episodes = client.podcast_episodes.list(per_page: 30)
+  #   episodes.data.each { |ep| puts ep.title }
+  #
+  # @example List episodes for a specific podcast
+  #   episodes = client.podcast_episodes.list(username: "codenewbie")
+  #   episodes.data.each { |ep| puts ep.title }
+  #
+  # == List Parameters
+  #
+  # - +username+ (String) — Retrieve episodes from a specific podcast
+  #   (e.g., +'codenewbie'+)
+  # - +page+ (Integer) — Page number (default: 1)
+  # - +per_page+ (Integer) — Items per page (default: 30)
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getPodcastEpisodes
+  class PodcastEpisode < APIResource
+    extend APIOperations::List
+
+    OBJECT_NAME = "podcast_episode"
+    RESOURCE_PATH = "/api/podcast_episodes"
+  end
+end

data/lib/forem/resources/profile_image.rb

@@ -0,0 +1,44 @@
+require "cgi"
+
+module Forem
+  # Represents the profile image associated with a Forem user or organization.
+  #
+  # Retrieve a user's profile image URL by their username.
+  #
+  # Profile images are avatar graphics that appear alongside user and
+  # organization names across the Forem UI. This resource exposes a single
+  # retrieve operation that looks up the image by username (or organization
+  # slug) and returns URLs to the image at various sizes.
+  #
+  # @example Retrieve a user's profile image
+  #   image = client.profile_images.retrieve("alice")
+  #   puts image.profile_image
+  #   puts image.profile_image_90
+  #
+  # @example Retrieve an organization's profile image
+  #   image = client.profile_images.retrieve("acme-corp")
+  #   puts image.profile_image
+  #
+  # @see https://developers.forem.com/api/v1
+  class ProfileImage < APIResource
+    OBJECT_NAME = "profile_image"
+    RESOURCE_PATH = "/api/profile_images"
+
+    # Retrieve the profile image URLs for a user or organization.
+    #
+    # Sends a GET request to +/api/profile_images/:username+.
+    #
+    # @param username [String] the username or organization slug to look up
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ProfileImage] object containing +profile_image+ and +profile_image_90+ URL fields
+    # @example
+    #   image = client.profile_images.retrieve("alice")
+    #   puts image.profile_image        # full-size URL
+    #   puts image.profile_image_90     # 90px thumbnail URL
+    # @see https://developers.forem.com/api/v1
+    def self.retrieve(username, opts = {})
+      resp = request(:get, "#{resource_path}/#{CGI.escape(username)}", {}, opts)
+      construct_from(resp.parsed_body)
+    end
+  end
+end

data/lib/forem/resources/reaction.rb

@@ -0,0 +1,61 @@
+module Forem
+  # Represents a reaction (like, unicorn, exploding head, etc.) on a Forem article or comment.
+  #
+  # Toggle user's reaction to a reactable (Article, Comment, or User). First
+  # call creates the reaction; second call removes it.
+  #
+  # Reactions are emoji-style responses that authenticated users can add to
+  # articles or comments. The create endpoint adds a reaction, and the toggle
+  # endpoint adds it if it does not exist or removes it if it already does.
+  #
+  # Available operations (via mixins):
+  #   - +Create+ — POST /api/reactions
+  #
+  # @example Create a reaction on an article
+  #   client.reactions.create(
+  #     reactable_id: 12345,
+  #     reactable_type: "Article",
+  #     category: "like"
+  #   )
+  #
+  # @example Toggle a reaction (add if absent, remove if present)
+  #   result = client.reactions.toggle(
+  #     reactable_id: 12345,
+  #     reactable_type: "Article",
+  #     category: "unicorn"
+  #   )
+  #   puts result.result   # => "create" or "destroy"
+  #
+  # @see https://developers.forem.com/api/v1
+  class Reaction < APIResource
+    extend APIOperations::Create
+
+    OBJECT_NAME = "reaction"
+    RESOURCE_PATH = "/api/reactions"
+
+    # Toggle a reaction on a reactable object.
+    #
+    # If the authenticated user has not yet reacted with the given category,
+    # the reaction is created. If they have already reacted, it is removed.
+    # Sends a POST request to +/api/reactions/toggle+.
+    #
+    # @param params [Hash] request body
+    # @option params [String] :category the reaction type (e.g., +"like"+, +"readinglist"+)
+    # @option params [Integer] :reactable_id the ID of the object to react to
+    # @option params [String] :reactable_type One of: +"Article"+, +"Comment"+, +"User"+
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::Reaction] reaction object with a +result+ field (++"create"++ or ++"destroy"++)
+    # @example
+    #   result = client.reactions.toggle(
+    #     reactable_id: 42,
+    #     reactable_type: "Article",
+    #     category: "fire"
+    #   )
+    #   puts result.result   # => "create" or "destroy"
+    # @see https://developers.forem.com/api/v1
+    def self.toggle(params = {}, opts = {})
+      resp = request(:post, "/api/reactions/toggle", params, opts)
+      construct_from(resp.parsed_body)
+    end
+  end
+end