Class: Forem::AdminUser

Inherits:
APIResource show all
Extended by:
Forem::APIOperations::Create
Defined in:
lib/forem/resources/admin_user.rb

Overview

Provides admin-level user creation and synchronization for a Forem instance.

Requires super_admin privileges. Sends an invitation email to the provided email address.

AdminUser exposes the privileged user-creation endpoint under /api/admin/users (postAdminUsersCreate). Unlike the regular User resource, this resource is scoped to admin operations and requires an admin API key to use. General retrieval and moderation of existing users remains on User; identity and notification synchronization lives here.

Available operations (via mixins):

- +Create+ — POST /api/admin/users
- +link_identity+ — POST /api/admin/users/:user_id/identities
- +bulk_link_identities+ — POST /api/admin/users/identities/bulk
- +identities+ — GET /api/admin/users/:user_id/identities
- +unlink_identity+ — DELETE /api/admin/users/:user_id/identities/:id
- +update_notification_settings+ — PUT notification settings for a user

Examples:

Create a new user as an admin (flat params)

client.admin_users.create(
  email: "alice@example.com",
  name: "Alice Example"
)

See Also:

Constant Summary collapse

OBJECT_NAME = 
"admin_user"
RESOURCE_PATH = 
"/api/admin/users"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Methods included from Forem::APIOperations::Create

create

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 Forem::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

Submit multiple external identity links in one request.

Parameters:

  • provider (String) —

    the identity provider shared by the identities.

  • identities (Array<Hash>) —

    identity hashes containing user_id and uid.

  • opts (Hash) —

    per-request options.

Returns:

  • (Array<ForemObject>) —

    per-item results containing user_id, status, and an error_code when that item fails.



87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/forem/resources/admin_user.rb', line 87

def self.bulk_link_identities(provider:, identities:, **opts)
  requestor = opts[:requestor]
  resp = request(
    :post,
    "#{resource_path}/identities/bulk",
    { provider: provider, identities: identities },
    opts
  )
  results = resp.parsed_body["results"] || []
  results.map do |result|
    ForemObject.construct_from(result, requestor: requestor)
  end
end

.create(params = {}, opts = {}) ⇒ Forem::AdminUser

Invite a new user by email (postAdminUsersCreate).

Requires super_admin privileges. Sends an invitation email to the provided email address. The endpoint takes flat params — there is no user: wrapper.

The Forem API generates the username from the email address, so passing :username has no effect. Optional invite-customization parameters are also accepted: :custom_invite_subject, :custom_invite_message, :custom_invite_footnote.

The response body is intentionally empty (HTTP 200) — there is no created-user record returned.

Parameters:

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

    request body

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

    per-request options

Options Hash (params):

  • :email (String) — default: required —

    the email address to invite

  • :name (String) —

    the user's display name

  • :custom_invite_subject (String) —

    override the invite subject line

  • :custom_invite_message (String) —

    override the invite body

  • :custom_invite_footnote (String) —

    override the invite footer

Returns:



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/forem/resources/admin_user.rb', line 55

class AdminUser < APIResource
  extend APIOperations::Create

  OBJECT_NAME = "admin_user"
  RESOURCE_PATH = "/api/admin/users"

  # Link an external provider identity to a user.
  #
  # @param user_id [Integer, String] the Forem user ID.
  # @param provider [String] the identity provider name.
  # @param uid [String] the provider's stable user identifier.
  # @param opts [Hash] per-request options.
  # @return [ForemObject] the linked identity.
  def self.link_identity(user_id, provider:, uid:, **opts)
    requestor = opts[:requestor]
    resp = request(
      :post,
      "#{resource_path}/#{user_id}/identities",
      { provider: provider, uid: uid },
      opts
    )
    ForemObject.construct_from(resp.parsed_body, requestor: requestor)
  end

  # Submit multiple external identity links in one request.
  #
  # @param provider [String] the identity provider shared by the identities.
  # @param identities [Array<Hash>] identity hashes containing +user_id+ and
  #   +uid+.
  # @param opts [Hash] per-request options.
  # @return [Array<ForemObject>] per-item results containing +user_id+,
  #   +status+, and an +error_code+ when that item fails.
  def self.bulk_link_identities(provider:, identities:, **opts)
    requestor = opts[:requestor]
    resp = request(
      :post,
      "#{resource_path}/identities/bulk",
      { provider: provider, identities: identities },
      opts
    )
    results = resp.parsed_body["results"] || []
    results.map do |result|
      ForemObject.construct_from(result, requestor: requestor)
    end
  end

  # List a user's linked external identities.
  #
  # @param user_id [Integer, String] the Forem user ID.
  # @param opts [Hash] per-request options.
  # @return [Array<ForemObject>] the user's linked identities.
  def self.identities(user_id, **opts)
    requestor = opts[:requestor]
    resp = request(:get, "#{resource_path}/#{user_id}/identities", {}, opts)
    identities = resp.parsed_body["identities"] || []
    identities.map do |identity|
      ForemObject.construct_from(identity, requestor: requestor)
    end
  end

  # Unlink an external identity from a user.
  #
  # @param user_id [Integer, String] the Forem user ID.
  # @param identity_id [Integer, String] the linked identity ID.
  # @param opts [Hash] per-request options.
  # @return [ForemObject, nil] the unlinked identity when returned by the
  #   API, otherwise +nil+ for an empty response.
  def self.unlink_identity(user_id, identity_id, **opts)
    requestor = opts[:requestor]
    resp = request(
      :delete,
      "#{resource_path}/#{user_id}/identities/#{identity_id}",
      {},
      opts
    )
    return nil unless resp.parsed_body

    ForemObject.construct_from(resp.parsed_body, requestor: requestor)
  end

  # @param user_id [Integer, String] the Forem user ID.
  # @param settings [Hash] notification setting columns to write, e.g.
  #   +{ email_newsletter: false, email_digest_periodic: false }+. Sent
  #   verbatim under the +notification_setting+ wrapper; the server owns
  #   which keys it accepts.
  # @param opts [Hash] per-request options.
  # @return [ForemObject] the updated notification setting.
  def self.update_notification_settings(user_id, settings:, **opts)
    requestor = opts[:requestor]
    resp = request(
      :put,
      "#{resource_path}/#{user_id}/notification_settings",
      { notification_setting: settings },
      opts
    )
    ForemObject.construct_from(resp.parsed_body, requestor: requestor)
  end
end

.identities(user_id, **opts) ⇒ Array<ForemObject>

List a user's linked external identities.

Parameters:

  • user_id (Integer, String) —

    the Forem user ID.

  • opts (Hash) —

    per-request options.

Returns:

  • (Array<ForemObject>) —

    the user's linked identities.



106
107
108
109
110
111
112
113
 
# File 'lib/forem/resources/admin_user.rb', line 106

def self.identities(user_id, **opts)
  requestor = opts[:requestor]
  resp = request(:get, "#{resource_path}/#{user_id}/identities", {}, opts)
  identities = resp.parsed_body["identities"] || []
  identities.map do |identity|
    ForemObject.construct_from(identity, requestor: requestor)
  end
end

.link_identity(user_id, provider:, uid:, **opts) ⇒ ForemObject

Link an external provider identity to a user.

Parameters:

  • user_id (Integer, String) —

    the Forem user ID.

  • provider (String) —

    the identity provider name.

  • uid (String) —

    the provider's stable user identifier.

  • opts (Hash) —

    per-request options.

Returns:



68
69
70
71
72
73
74
75
76
77
 
# File 'lib/forem/resources/admin_user.rb', line 68

def self.link_identity(user_id, provider:, uid:, **opts)
  requestor = opts[:requestor]
  resp = request(
    :post,
    "#{resource_path}/#{user_id}/identities",
    { provider: provider, uid: uid },
    opts
  )
  ForemObject.construct_from(resp.parsed_body, requestor: requestor)
end

.unlink_identity(user_id, identity_id, **opts) ⇒ ForemObject?

Unlink an external identity from a user.

Parameters:

  • user_id (Integer, String) —

    the Forem user ID.

  • identity_id (Integer, String) —

    the linked identity ID.

  • opts (Hash) —

    per-request options.

Returns:

  • (ForemObject, nil) —

    the unlinked identity when returned by the API, otherwise nil for an empty response.



122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/forem/resources/admin_user.rb', line 122

def self.unlink_identity(user_id, identity_id, **opts)
  requestor = opts[:requestor]
  resp = request(
    :delete,
    "#{resource_path}/#{user_id}/identities/#{identity_id}",
    {},
    opts
  )
  return nil unless resp.parsed_body

  ForemObject.construct_from(resp.parsed_body, requestor: requestor)
end

.update_notification_settings(user_id, settings:, **opts) ⇒ ForemObject

Returns the updated notification setting.

Parameters:

  • user_id (Integer, String) —

    the Forem user ID.

  • settings (Hash) —

    notification setting columns to write, e.g. { email_newsletter: false, email_digest_periodic: false }. Sent verbatim under the notification_setting wrapper; the server owns which keys it accepts.

  • opts (Hash) —

    per-request options.

Returns:



142
143
144
145
146
147
148
149
150
151
 
# File 'lib/forem/resources/admin_user.rb', line 142

def self.update_notification_settings(user_id, settings:, **opts)
  requestor = opts[:requestor]
  resp = request(
    :put,
    "#{resource_path}/#{user_id}/notification_settings",
    { notification_setting: settings },
    opts
  )
  ForemObject.construct_from(resp.parsed_body, requestor: requestor)
end