Class: Forem::User

Inherits:
APIResource show all
Extended by:
APIOperations::Retrieve
Defined in:
lib/forem/resources/user.rb

Overview

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.

Examples:

Retrieve the authenticated user

me = client.users.me
puts "Hello, #{me.name}!"

Retrieve a user by ID

user = client.users.retrieve(12345)
puts user.username

Look up a user by exact email

results = client.users.search(email: "alice@example.com")
results.each { |u| puts u.username }

See Also:

Constant Summary collapse

OBJECT_NAME = 
"user"
RESOURCE_PATH = 
"/api/users"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Retrieve

retrieve

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Class Method Details

.me(opts = {}) ⇒ Forem::User

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.

Examples:

me = client.users.me
puts "Logged in as #{me.username}"

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



46
47
48
49
50
 
# File 'lib/forem/resources/user.rb', line 46

def self.me(opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/users/me", {}, opts)
  construct_from(resp.parsed_body, requestor: requestor)
end

.search(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::User>

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.

Examples:

results = client.users.search(email: "alice@example.com")
if (user = results.first)
  puts user.username
end

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :email (String) — default: required —

    the email address to look up.

Returns:

  • (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.

See Also:



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/forem/resources/user.rb', line 72

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

Instance Method Details

#add_limited(opts = {}) ⇒ ForemResponse

Apply the "limited" role to this user, restricting their posting ability.

Sends a PUT request to /api/users/:id/limited. Requires admin privileges.

Examples:

user = client.users.retrieve(42)
user.add_limited

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



152
153
154
 
# File 'lib/forem/resources/user.rb', line 152

def add_limited(opts = {})
  request(:put, "#{resource_url}/limited", {}, opts)
end

#add_spam(opts = {}) ⇒ ForemResponse

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.

Examples:

user = client.users.retrieve(42)
user.add_spam

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



183
184
185
 
# File 'lib/forem/resources/user.rb', line 183

def add_spam(opts = {})
  request(:put, "#{resource_url}/spam", {}, opts)
end

#add_trusted(opts = {}) ⇒ ForemResponse

Grant the "trusted" role to this user, giving them elevated moderation privileges.

Sends a PUT request to /api/users/:id/trusted. Requires admin privileges.

Examples:

user = client.users.retrieve(42)
user.add_trusted

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



211
212
213
 
# File 'lib/forem/resources/user.rb', line 211

def add_trusted(opts = {})
  request(:put, "#{resource_url}/trusted", {}, opts)
end

#remove_limited(opts = {}) ⇒ ForemResponse

Remove the "limited" role from this user.

Sends a DELETE request to /api/users/:id/limited. Requires admin privileges.

Examples:

user = client.users.retrieve(42)
user.remove_limited

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



166
167
168
 
# File 'lib/forem/resources/user.rb', line 166

def remove_limited(opts = {})
  request(:delete, "#{resource_url}/limited", {}, opts)
end

#remove_spam(opts = {}) ⇒ ForemResponse

Remove the spam flag from this user.

Sends a DELETE request to /api/users/:id/spam. Requires admin privileges.

Examples:

user = client.users.retrieve(42)
user.remove_spam

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



197
198
199
 
# File 'lib/forem/resources/user.rb', line 197

def remove_spam(opts = {})
  request(:delete, "#{resource_url}/spam", {}, opts)
end

#remove_trusted(opts = {}) ⇒ ForemResponse

Remove the "trusted" role from this user.

Sends a DELETE request to /api/users/:id/trusted. Requires admin privileges.

Examples:

user = client.users.retrieve(42)
user.remove_trusted

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



225
226
227
 
# File 'lib/forem/resources/user.rb', line 225

def remove_trusted(opts = {})
  request(:delete, "#{resource_url}/trusted", {}, opts)
end

#suspend(opts = {}) ⇒ ForemResponse

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.

Examples:

user = client.users.retrieve(42)
user.suspend

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



124
125
126
 
# File 'lib/forem/resources/user.rb', line 124

def suspend(opts = {})
  request(:put, "#{resource_url}/suspend", {}, opts)
end

#unpublish(opts = {}) ⇒ ForemResponse

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.

Examples:

user = client.users.retrieve(42)
user.unpublish

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



107
108
109
 
# File 'lib/forem/resources/user.rb', line 107

def unpublish(opts = {})
  request(:put, "#{resource_url}/unpublish", {}, opts)
end

#unsuspend(opts = {}) ⇒ ForemResponse

Remove the suspension from this user, restoring their access.

Sends a DELETE request to /api/users/:id/suspend. Requires admin privileges.

Examples:

user = client.users.retrieve(42)
user.unsuspend

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



138
139
140
 
# File 'lib/forem/resources/user.rb', line 138

def unsuspend(opts = {})
  request(:delete, "#{resource_url}/suspend", {}, opts)
end