forem-ruby 0.1.0.beta1

data/lib/forem/resources/reading_list.rb

@@ -0,0 +1,29 @@
+module Forem
+  # Represents an item saved to the authenticated user's reading list.
+  #
+  # When a user bookmarks an article on Forem, it appears in their reading
+  # list. This resource supports listing those saved articles with optional
+  # filtering by status.
+  #
+  # Requires authentication. Returns articles saved to the user's reading
+  # list. Default: 30 per page.
+  #
+  # Available operations (via mixins):
+  #   - +List+ — GET /api/readinglist
+  #
+  # @example List all bookmarked articles
+  #   items = client.reading_list.list
+  #   items.data.each { |item| puts item.article.title }
+  #
+  # @example List only confirmed (active) reading list items
+  #   items = client.reading_list.list(status: "confirmed")
+  #   items.data.each { |item| puts item.article.title }
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getReadinglist
+  class ReadingList < APIResource
+    extend APIOperations::List
+
+    OBJECT_NAME = "reading_list"
+    RESOURCE_PATH = "/api/readinglist"
+  end
+end

data/lib/forem/resources/recommended_articles_list.rb

@@ -0,0 +1,45 @@
+module Forem
+  # Represents a curated list of recommended articles on a Forem instance.
+  #
+  # Curated lists of recommended articles. Used by admins to manage content
+  # recommendations.
+  #
+  # RecommendedArticlesLists are editorial curation objects that group
+  # articles for display in recommendation widgets or featured sections.
+  # Full CRUD operations are supported. Managing these lists typically
+  # requires an admin API key.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/recommended_articles_lists
+  #   - +Create+   — POST /api/recommended_articles_lists
+  #   - +Retrieve+ — GET /api/recommended_articles_lists/:id
+  #   - +Update+   — PUT /api/recommended_articles_lists/:id
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # @example List all recommended article lists
+  #   lists = client.recommended_articles_lists.list
+  #   lists.each { |l| puts l.name }
+  #
+  # @example Create a recommended articles list (flat params)
+  #   list = client.recommended_articles_lists.create(
+  #     name: "Top Ruby Articles",
+  #     article_ids: [101, 202, 303]
+  #   )
+  #
+  # @example Retrieve a list by ID and update it
+  #   list = client.recommended_articles_lists.retrieve(1)
+  #   list.name = "Updated Name"
+  #   list.save
+  #
+  # @see https://developers.forem.com/api/v1
+  class RecommendedArticlesList < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Save
+
+    OBJECT_NAME = "recommended_articles_list"
+    RESOURCE_PATH = "/api/recommended_articles_lists"
+  end
+end

data/lib/forem/resources/request_redirect.rb

@@ -0,0 +1,60 @@
+module Forem
+  # Represents a request redirect used to map legacy or custom-domain paths
+  # to a destination URL.
+  #
+  # Request redirects power organization custom domains: when a request
+  # comes in for +request_domain+ at path +original_url+, Forem redirects
+  # the visitor to +destination_url+. Managing request redirects is an
+  # admin-only operation and requires an admin API key.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/admin/request_redirects
+  #   - +Create+   — POST /api/admin/request_redirects
+  #   - +Retrieve+ — GET /api/admin/request_redirects/:id
+  #   - +Update+   — PUT /api/admin/request_redirects/:id
+  #   - +Delete+   — instance-level delete (DELETE /api/admin/request_redirects/:id)
+  #   - +Save+     — instance-level save (create or update)
+  #
+  # == RequestRedirect Fields
+  #
+  # - +original_url+ (String, required) — the incoming request path; must
+  #   start with +/+ and is unique per +request_domain+
+  # - +destination_url+ (String, required) — the fully-qualified HTTP/HTTPS
+  #   URL to redirect to
+  # - +request_domain+ (String, required) — the domain the redirect applies
+  #   to; normalized to lowercase by the server
+  #
+  # The create/update endpoints require request bodies wrapped in a
+  # +request_redirect:+ key (the API uses strong parameters with
+  # +params.require(:request_redirect)+), so callers of the class methods
+  # here must supply that wrapper explicitly. {Forem::Services::RequestRedirectService}
+  # handles the wrapping automatically for the friendlier, flat-params
+  # service interface.
+  #
+  # @example List all request redirects
+  #   redirects = client.request_redirects.list
+  #   redirects.each { |r| puts "#{r.request_domain}#{r.original_url} -> #{r.destination_url}" }
+  #
+  # @example Create a request redirect (params must be wrapped in +request_redirect:+)
+  #   redirect = Forem::RequestRedirect.create(
+  #     { request_redirect: { original_url: "/old", destination_url: "https://example.com/new", request_domain: "example.com" } },
+  #     requestor: client.requestor
+  #   )
+  #
+  # @example Retrieve a request redirect by ID
+  #   redirect = client.request_redirects.retrieve(7)
+  #   puts redirect.destination_url
+  #
+  # @see https://developers.forem.com/api/v1
+  class RequestRedirect < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    extend APIOperations::Update
+    include APIOperations::Delete
+    include APIOperations::Save
+
+    OBJECT_NAME = "request_redirect"
+    RESOURCE_PATH = "/api/admin/request_redirects"
+  end
+end

data/lib/forem/resources/segment.rb

@@ -0,0 +1,103 @@
+module Forem
+  # Represents a user segment used for targeted content delivery on Forem.
+  #
+  # Audience segments for billboard targeting. The API only permits managing
+  # segments you create yourself.
+  #
+  # Segments are named groups of users that can be targeted with specific
+  # billboards or other content. Admins can create and delete segments, list
+  # their members, and add or remove users from them. Managing segments
+  # requires an admin API key.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/segments          (getSegments)
+  #   - +Create+   — POST /api/segments         (createSegment)
+  #   - +Retrieve+ — GET /api/segments/:id
+  #   - +Delete+   — instance-level delete (DELETE /api/segments/:id)
+  #
+  # == Segment Fields
+  #
+  # - +id+ (Integer) — The segment ID
+  # - +type_of+ (String) — Marks segment as manually managed
+  # - +user_count+ (Integer) — Current number of users in the segment
+  #
+  # @example List all segments
+  #   segments = client.segments.list
+  #   segments.each { |s| puts s.id }
+  #
+  # @example Create a segment (no params accepted — the API ignores anything passed)
+  #   segment = client.segments.create
+  #   #=> #<Forem::Segment id=14 type_of="manual">
+  #
+  # @example List users in a segment
+  #   segment = client.segments.retrieve(5)
+  #   segment.users.auto_paging_each { |u| puts u.username }
+  #
+  # @see https://developers.forem.com/api/v1
+  class Segment < APIResource
+    extend APIOperations::Create
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+    include APIOperations::Delete
+
+    OBJECT_NAME = "segment"
+    RESOURCE_PATH = "/api/segments"
+
+    # Return the users who belong to this segment.
+    #
+    # Returns users in this segment. Default: 30 per page, max: 1000.
+    #
+    # Sends a GET request to +/api/segments/:id/users+ (getUsersInSegment).
+    #
+    # @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, max: 1000)
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::User>] paginated list of users
+    #   belonging to this segment.
+    # @example
+    #   segment = client.segments.retrieve(5)
+    #   segment.users.auto_paging_each { |u| puts u.username }
+    # @see https://developers.forem.com/api/v1
+    def users(params = {}, opts = {})
+      opts = opts.dup
+      opts[:requestor] ||= @requestor
+      Forem::User.paginated_list("#{resource_url}/users", params, opts)
+    end
+
+    # Add one or more users to this segment.
+    #
+    # Add users in bulk. The response distinguishes successes (added) from
+    # failures (couldn't add).
+    #
+    # Sends a PUT request to +/api/segments/:id/add_users+ (addUsersToSegment).
+    #
+    # @param params [Hash] request body
+    # @option params [Array<Integer>] :user_ids list of user IDs to add
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   segment = client.segments.retrieve(5)
+    #   segment.add_users(user_ids: [101, 102, 103])
+    # @see https://developers.forem.com/api/v1
+    def add_users(params = {}, opts = {})
+      request(:put, "#{resource_url}/add_users", params, opts)
+    end
+
+    # Remove one or more users from this segment.
+    #
+    # Sends a PUT request to +/api/segments/:id/remove_users+.
+    #
+    # @param params [Hash] request body
+    # @option params [Array<Integer>] :user_ids list of user IDs to remove
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   segment = client.segments.retrieve(5)
+    #   segment.remove_users(user_ids: [101, 102])
+    # @see https://developers.forem.com/api/v1
+    def remove_users(params = {}, opts = {})
+      request(:put, "#{resource_url}/remove_users", params, opts)
+    end
+  end
+end

data/lib/forem/resources/survey.rb

@@ -0,0 +1,96 @@
+module Forem
+  # Represents a survey published on a Forem instance.
+  #
+  # Surveys are structured questionnaires that can be presented to community
+  # members. They can be listed or retrieved individually. Survey responses
+  # are exposed through two endpoints — {#poll_votes} for multiple-choice
+  # poll selections and {#poll_text_responses} for free-text answers.
+  #
+  # The +/api/surveys/{id}/responses+ endpoint that earlier versions of
+  # this gem hit no longer exists in the Forem API; it was replaced by
+  # those two cursor-paginated endpoints.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/surveys
+  #   - +Retrieve+ — GET /api/surveys/:id_or_slug (getSurveyByIdOrSlug)
+  #
+  # == Survey Fields
+  #
+  # - +id+ (Integer)
+  # - +title+ (String)
+  # - +slug+ (String)
+  # - +survey_type_of+ (String) — Survey category
+  # - +active+ (Boolean) — Whether the survey is currently active
+  #
+  # == Authentication
+  #
+  # All survey endpoints require an admin API key.
+  #
+  # @example List active surveys
+  #   surveys = client.surveys.list(active: true)
+  #   surveys.each { |s| puts s.title }
+  #
+  # @example Retrieve a specific survey by id or slug
+  #   survey = client.surveys.retrieve(3)
+  #   survey = client.surveys.retrieve("my-survey-slug")
+  #
+  # @example Iterate every poll vote across all pages
+  #   survey = client.surveys.retrieve(3)
+  #   survey.poll_votes.auto_paging_each { |v| puts v.poll_option_id }
+  #
+  # @see https://developers.forem.com/api/v1
+  class Survey < APIResource
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+
+    OBJECT_NAME = "survey"
+    RESOURCE_PATH = "/api/surveys"
+
+    # Return the multiple-choice poll selections recorded for this survey.
+    #
+    # Sends a GET request to +/api/surveys/:id_or_slug/poll_votes+.
+    # Pagination is cursor-based — pass the last seen vote id as +:after+
+    # (or use {Forem::ListObject#auto_paging_each}, which threads the
+    # cursor automatically).
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :after return only votes with id strictly
+    #   greater than this value (cursor)
+    # @option params [Integer] :per_page page size (default 30)
+    # @param opts [Hash] per-request options
+    # @return [Forem::ListObject<Forem::ForemObject>] cursor-paginated list
+    #   of poll-vote objects.
+    # @example
+    #   survey = client.surveys.retrieve(3)
+    #   survey.poll_votes.auto_paging_each { |v| puts v.id }
+    # @see https://developers.forem.com/api/v1
+    def poll_votes(params = {}, opts = {})
+      opts = opts.dup
+      opts[:requestor] ||= @requestor
+      Forem::ForemObject.cursor_list("#{resource_url}/poll_votes", params, opts)
+    end
+
+    # Return the free-text answers recorded for this survey.
+    #
+    # Sends a GET request to +/api/surveys/:id_or_slug/poll_text_responses+.
+    # Cursor-paginated by +:after+ on the last seen response id; see
+    # {#poll_votes} for paging details.
+    #
+    # @param params [Hash] query parameters
+    # @option params [Integer] :after return only responses with id
+    #   strictly greater than this value (cursor)
+    # @option params [Integer] :per_page page size (default 30)
+    # @param opts [Hash] per-request options
+    # @return [Forem::ListObject<Forem::ForemObject>] cursor-paginated list
+    #   of poll text-response objects.
+    # @example
+    #   survey = client.surveys.retrieve(3)
+    #   survey.poll_text_responses.each { |r| puts r.text_content }
+    # @see https://developers.forem.com/api/v1
+    def poll_text_responses(params = {}, opts = {})
+      opts = opts.dup
+      opts[:requestor] ||= @requestor
+      Forem::ForemObject.cursor_list("#{resource_url}/poll_text_responses", params, opts)
+    end
+  end
+end

data/lib/forem/resources/tag.rb

@@ -0,0 +1,27 @@
+module Forem
+  # Represents a Forem tag used to categorize articles.
+  #
+  # Tags are keywords attached to articles that help readers discover related
+  # content. Only listing is supported through the public API; tags are created
+  # implicitly when articles are published with new tag names.
+  #
+  # Tags are ordered by popularity. Default: 10 per page.
+  #
+  # Available operations (via mixins):
+  #   - +List+ — GET /api/tags
+  #
+  # @example List tags ordered by popularity
+  #   tags = client.tags.list(per_page: 50)
+  #   tags.data.each { |t| puts "#{t.name} (#{t.points} points)" }
+  #
+  # @example Iterate over every tag using auto-pagination
+  #   client.tags.list.auto_paging_each { |t| puts t.name }
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getTags
+  class Tag < APIResource
+    extend APIOperations::List
+
+    OBJECT_NAME = "tag"
+    RESOURCE_PATH = "/api/tags"
+  end
+end

data/lib/forem/resources/trend.rb

@@ -0,0 +1,80 @@
+module Forem
+  # Represents a trend detected across a Forem instance's content.
+  #
+  # Trends are algorithmically-derived topic clusters ("hot and recent"
+  # subject areas) made up of related articles. They are read-only via the
+  # public API — there is no create/update/delete surface, only listing,
+  # retrieval, and a nested endpoint for the articles that make up a trend.
+  #
+  # Available operations (via mixins):
+  #   - +List+     — GET /api/trends
+  #   - +Retrieve+ — GET /api/trends/:id_or_slug
+  #
+  # == Trend Fields
+  #
+  # - +id+ (Integer)
+  # - +name+ (String)
+  # - +slug+ (String)
+  # - +description+ (String)
+  # - +key_questions+ (Array<String>) — Questions the trend's content clusters around
+  # - +score+ (Float) — Relative trend strength/ranking score
+  # - +articles_count+ (Integer) — Number of articles associated with the trend
+  # - +cover_image+ (String) — URL of the trend's cover image
+  # - +first_observed_at+ (String) — ISO 8601 timestamp
+  # - +last_observed_at+ (String) — ISO 8601 timestamp
+  # - +created_at+ (String) — ISO 8601 timestamp
+  # - +updated_at+ (String) — ISO 8601 timestamp
+  # - +type_of+ (String) — Always +"trend"+
+  #
+  # The +show+ response additionally includes +top_articles+, an array of up
+  # to three of the trend's highest-scoring published articles, each with
+  # +id+, +title+, +slug+, +score+, and +published_at+.
+  #
+  # @example List hot and recent trends
+  #   trends = client.trends.list(per_page: 10)
+  #   trends.data.each { |t| puts "#{t.name} (#{t.score})" }
+  #
+  # @example Retrieve a trend by ID or slug
+  #   trend = client.trends.retrieve("ai-agents")
+  #   puts trend.description
+  #   trend.top_articles.each { |a| puts a["title"] }
+  #
+  # @example List the articles that make up a trend
+  #   articles = client.trends.articles("ai-agents", per_page: 20, sort: "score")
+  #   articles.each { |a| puts a.title }
+  #
+  # @see https://developers.forem.com/api/v1
+  class Trend < APIResource
+    extend APIOperations::List
+    extend APIOperations::Retrieve
+
+    OBJECT_NAME = "trend"
+    RESOURCE_PATH = "/api/trends"
+
+    # Return the articles belonging to a trend.
+    #
+    # Sends a GET request to +/api/trends/:id_or_slug/articles+. Unlike
+    # {.list} and {.retrieve}, this is a class method that takes the trend's
+    # ID or slug directly, so it can be called without first retrieving the
+    # trend itself.
+    #
+    # @param id_or_slug [Integer, String] the trend's numeric ID or slug
+    # @param params [Hash] query parameters
+    # @option params [Integer] :page page number (default: 1)
+    # @option params [Integer] :per_page number of results per page (default: 10)
+    # @option params [String] :sort +"score"+ to sort purely by article score;
+    #   omit for the default ordering (trend membership distance, then score)
+    # @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 [Array<Forem::Article>] articles associated with the trend
+    # @example
+    #   Forem::Trend.articles("ai-agents", per_page: 5, requestor: requestor)
+    # @see https://developers.forem.com/api/v1
+    def self.articles(id_or_slug, params = {}, opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "#{resource_path}/#{id_or_slug}/articles", params, opts)
+      (resp.parsed_body || []).map { |item| Forem::Article.construct_from(item, requestor: requestor) }
+    end
+  end
+end

data/lib/forem/resources/user.rb

@@ -0,0 +1,229 @@
+module Forem
+  # Represents a Forem user account.
+  #
+  # Users can be retrieved by ID or by looking up the currently authenticated
+  # user. Admin-level operations (suspend, unsuspend, flag as spam, etc.) are
+  # also exposed as instance methods and require an admin API key.
+  #
+  # Available operations (via mixins):
+  #   - +Retrieve+ — GET /api/users/:id
+  #
+  # Note: the +id+ parameter passed to +retrieve+ can be a numeric ID or a
+  # username string.
+  #
+  # @example Retrieve the authenticated user
+  #   me = client.users.me
+  #   puts "Hello, #{me.name}!"
+  #
+  # @example Retrieve a user by ID
+  #   user = client.users.retrieve(12345)
+  #   puts user.username
+  #
+  # @example Look up a user by exact email
+  #   results = client.users.search(email: "alice@example.com")
+  #   results.each { |u| puts u.username }
+  #
+  # @see https://developers.forem.com/api/v1#/operations/getUser
+  class User < APIResource
+    extend APIOperations::Retrieve
+
+    OBJECT_NAME = "user"
+    RESOURCE_PATH = "/api/users"
+
+    # Return the currently authenticated user's profile.
+    #
+    # Returns extended user info including +email+ (if the user allows it
+    # on their profile).
+    #
+    # Sends a GET request to +/api/users/me+.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::User] the authenticated user
+    # @example
+    #   me = client.users.me
+    #   puts "Logged in as #{me.username}"
+    # @see https://developers.forem.com/api/v1#/operations/getUserMe
+    def self.me(opts = {})
+      requestor = opts[:requestor]
+      resp = request(:get, "/api/users/me", {}, opts)
+      construct_from(resp.parsed_body, requestor: requestor)
+    end
+
+    # Look up a single user by exact email address.
+    #
+    # Sends a GET request to +/api/users/search+. Despite the endpoint
+    # name, this is an exact-match email lookup — there is no name- or
+    # username-prefix search. The endpoint is V1-only, requires admin
+    # privileges, and is not currently documented in the public swagger.
+    #
+    # @param params [Hash] query parameters
+    # @option params [String] :email (required) the email address to look up.
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [Forem::ListObject<Forem::User>] a list containing the matched
+    #   user, or an empty list if none matches. The list is wrapped for
+    #   API consistency with other search-style methods even though the
+    #   endpoint returns at most one result.
+    # @example
+    #   results = client.users.search(email: "alice@example.com")
+    #   if (user = results.first)
+    #     puts user.username
+    #   end
+    # @see https://developers.forem.com/api/v1
+    def self.search(params = {}, opts = {})
+      requestor = opts[:requestor]
+      data = begin
+        resp = request(:get, "/api/users/search", params, opts)
+        body = resp.parsed_body
+        if body.is_a?(Hash) && !body.empty?
+          [construct_from(body, requestor: requestor)]
+        else
+          []
+        end
+      rescue NotFoundError
+        []
+      end
+      ListObject.new(
+        data: data,
+        per_page: [data.length, 1].max,
+        resource_class: self,
+        filters: params.reject { |k, _| [:per_page, "per_page"].include?(k) },
+        requestor: requestor,
+        fetcher: ->(*) { nil }
+      )
+    end
+
+    # Unpublish all articles and comments authored by this user.
+    #
+    # Unpublishes all articles by this user.
+    #
+    # Sends a PUT request to +/api/users/:id/unpublish+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.unpublish
+    # @see https://developers.forem.com/api/v1#/operations/unpublishUser
+    def unpublish(opts = {})
+      request(:put, "#{resource_url}/unpublish", {}, opts)
+    end
+
+    # Suspend this user, preventing them from logging in or posting.
+    #
+    # Prevents new posts and comments but does not delete existing content.
+    # The user is not notified in the UI.
+    #
+    # Sends a PUT request to +/api/users/:id/suspend+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.suspend
+    # @see https://developers.forem.com/api/v1#/operations/suspendUser
+    def suspend(opts = {})
+      request(:put, "#{resource_url}/suspend", {}, opts)
+    end
+
+    # Remove the suspension from this user, restoring their access.
+    #
+    # Sends a DELETE request to +/api/users/:id/suspend+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.unsuspend
+    # @see https://developers.forem.com/api/v1#/operations/suspendUser
+    def unsuspend(opts = {})
+      request(:delete, "#{resource_url}/suspend", {}, opts)
+    end
+
+    # Apply the "limited" role to this user, restricting their posting ability.
+    #
+    # Sends a PUT request to +/api/users/:id/limited+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.add_limited
+    # @see https://developers.forem.com/api/v1
+    def add_limited(opts = {})
+      request(:put, "#{resource_url}/limited", {}, opts)
+    end
+
+    # Remove the "limited" role from this user.
+    #
+    # Sends a DELETE request to +/api/users/:id/limited+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.remove_limited
+    # @see https://developers.forem.com/api/v1
+    def remove_limited(opts = {})
+      request(:delete, "#{resource_url}/limited", {}, opts)
+    end
+
+    # Flag this user as a spam account.
+    #
+    # Prevents new posts and comments but does not delete existing content.
+    # The user is not notified in the UI.
+    #
+    # Sends a PUT request to +/api/users/:id/spam+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.add_spam
+    # @see https://developers.forem.com/api/v1#/operations/spamUser
+    def add_spam(opts = {})
+      request(:put, "#{resource_url}/spam", {}, opts)
+    end
+
+    # Remove the spam flag from this user.
+    #
+    # Sends a DELETE request to +/api/users/:id/spam+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.remove_spam
+    # @see https://developers.forem.com/api/v1#/operations/spamUser
+    def remove_spam(opts = {})
+      request(:delete, "#{resource_url}/spam", {}, opts)
+    end
+
+    # Grant the "trusted" role to this user, giving them elevated moderation privileges.
+    #
+    # Sends a PUT request to +/api/users/:id/trusted+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.add_trusted
+    # @see https://developers.forem.com/api/v1
+    def add_trusted(opts = {})
+      request(:put, "#{resource_url}/trusted", {}, opts)
+    end
+
+    # Remove the "trusted" role from this user.
+    #
+    # Sends a DELETE request to +/api/users/:id/trusted+. Requires admin privileges.
+    #
+    # @param opts [Hash] per-request options (e.g., +:api_key+)
+    # @return [ForemResponse] the raw API response
+    # @example
+    #   user = client.users.retrieve(42)
+    #   user.remove_trusted
+    # @see https://developers.forem.com/api/v1
+    def remove_trusted(opts = {})
+      request(:delete, "#{resource_url}/trusted", {}, opts)
+    end
+  end
+end