Class: X::User

Inherits:
Resource show all
Extended by:
UserFinders
Includes:
Relationships, UserCollections
Defined in:
x-objects/lib/x/objects/user.rb

Overview

A user account

Constant Summary collapse

FIELDS =

The user fields the object layer requests: every one that does not depend on who is authenticated, since a field that does, such as connection_status, would make every request fail for a client that cannot read it; the identifiers of referenced posts, and the affiliation, come with their expansions

A minor release may add to it the fields the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of fields of its own.

%w[created_at description entities id is_identity_verified location name parody profile_banner_url
profile_image_url protected public_metrics subscriber_count subscription_type url username verified
verified_followers_count verified_type withheld].freeze
EXPANSIONS =

Every expansion available on user endpoints

The API gives a user its affiliation when a request asks for the affiliation expansion, which it takes only at the endpoints whose data is users, so the users a post, a list, a space, or a direct message includes hold none, and hydrate looks them up with it.

A minor release may add to it the expansions the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of expansions of its own.

%w[affiliation most_recent_post_id pinned_post_id].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from X::Resource

Instance Attribute Details

#affiliated_with_ids ⇒ Array<Integer> (readonly)

The identifiers of the accounts this account is affiliated with

Examples:

Get the identifiers of the accounts it is affiliated with

user.affiliated_with_ids

Returns:

  • (Array<Integer>) —

    the identifiers, empty if there are none



254
# File 'x-objects/lib/x/objects/user.rb', line 254

attribute :affiliated_with_ids, :integers, key: %w[affiliation user_id]

#affiliation ⇒ Hash? (readonly)

The organization the account is affiliated with, with its badge

The API gives it for the affiliation expansion, which only the endpoints whose data is users take, so a user a post, a list, a space, or a direct message includes holds none until it is hydrated.

Examples:

Get the affiliated organization

user.affiliation&.fetch("description")

Returns:

  • (Hash, nil) —

    the affiliation, with its description, url, badge_url, and user_id



246
# File 'x-objects/lib/x/objects/user.rb', line 246

attribute :affiliation, :object

#connection_status ⇒ Array<String>? (readonly)

How the authenticated user and this user are connected

No lookup asks for it unless user.fields names it, so a user looked up otherwise holds none, and reads nil rather than an empty list, which would say the users are not connected.

Examples:

Check whether this user follows the authenticated user

client.find_user("sferik", "user.fields": "connection_status").connection_status.include?("followed_by")

Returns:

  • (Array<String>, nil) —

    following, followed_by, blocking, muting, follow_request_sent, or follow_request_received, or nil when the response holds none



283
# File 'x-objects/lib/x/objects/user.rb', line 283

attribute :connection_status, :requested_list

#created_at ⇒ Time? (readonly)

The time when the account was created

Examples:

Get the creation time

user.created_at

Returns:

  • (Time, nil) —

    the creation time



158
# File 'x-objects/lib/x/objects/user.rb', line 158

attribute :created_at, :time

#description ⇒ String? (readonly)

The profile description

Examples:

Get the description

user.description

Returns:

  • (String, nil) —

    the description



114
# File 'x-objects/lib/x/objects/user.rb', line 114

attribute :description

#entities ⇒ Hash? (readonly)

The entities found in the description and URL

Examples:

Get the entities

user.entities

Returns:

  • (Hash, nil) —

    the entities



366
# File 'x-objects/lib/x/objects/user.rb', line 366

attribute :entities, :object

#followers_count ⇒ Integer? (readonly)

The number of followers

Examples:

Get the follower count

user.followers_count

Returns:

  • (Integer, nil) —

    the follower count



390
# File 'x-objects/lib/x/objects/user.rb', line 390

attribute :followers_count, :integer, key: %w[public_metrics followers_count]

#following_count ⇒ Integer? (readonly)

The number of followed users

Examples:

Get the following count

user.following_count

Returns:

  • (Integer, nil) —

    the following count



398
# File 'x-objects/lib/x/objects/user.rb', line 398

attribute :following_count, :integer, key: %w[public_metrics following_count]

#identity_verified ⇒ Boolean? (readonly)

Whether the account's identity is verified, the is_identity_verified field

Examples:

Check whether a user's identity is verified

user.identity_verified?

Returns:

  • (Boolean, nil) —

    true if the identity is verified



219
# File 'x-objects/lib/x/objects/user.rb', line 219

attribute :identity_verified, :boolean, key: %w[is_identity_verified]

#like_count ⇒ Integer? (readonly)

The number of posts the user has liked

Examples:

Get the like count

user.like_count

Returns:

  • (Integer, nil) —

    the like count



422
# File 'x-objects/lib/x/objects/user.rb', line 422

attribute :like_count, :integer, key: %w[public_metrics like_count]

#listed_count ⇒ Integer? (readonly)

The number of lists the user is a member of

Examples:

Get the listed count

user.listed_count

Returns:

  • (Integer, nil) —

    the listed count



414
# File 'x-objects/lib/x/objects/user.rb', line 414

attribute :listed_count, :integer, key: %w[public_metrics listed_count]

#location ⇒ String? (readonly)

The profile location

Examples:

Get the location

user.location

Returns:

  • (String, nil) —

    the location



122
# File 'x-objects/lib/x/objects/user.rb', line 122

attribute :location

#media_count ⇒ Integer? (readonly)

The number of photos and videos the user has posted

Examples:

Get the media count

user.media_count

Returns:

  • (Integer, nil) —

    the media count



430
# File 'x-objects/lib/x/objects/user.rb', line 430

attribute :media_count, :integer, key: %w[public_metrics media_count]

#most_recent_post_id ⇒ Integer? (readonly)

The identifier of the most recent post

Examples:

Get the most recent post identifier

user.most_recent_post_id

Returns:

  • (Integer, nil) —

    the most recent post identifier



358
# File 'x-objects/lib/x/objects/user.rb', line 358

attribute :most_recent_post_id, :integer, tweet_key: %w[most_recent_tweet_id]

#name ⇒ String? (readonly)

The display name

Examples:

Get the name

user.name # => "Erik Berlin"

Returns:

  • (String, nil) —

    the display name



98
# File 'x-objects/lib/x/objects/user.rb', line 98

attribute :name

#parody ⇒ Boolean? (readonly)

Whether the account labels itself a parody

Examples:

Check whether a user is a parody account

user.parody?

Returns:

  • (Boolean, nil) —

    true if the account is labelled a parody



204
# File 'x-objects/lib/x/objects/user.rb', line 204

attribute :parody, :boolean

#pinned_post_id ⇒ Integer? (readonly)

The identifier of the pinned post

Examples:

Get the pinned post identifier

user.pinned_post_id

Returns:

  • (Integer, nil) —

    the pinned post identifier



350
# File 'x-objects/lib/x/objects/user.rb', line 350

attribute :pinned_post_id, :integer, tweet_key: %w[pinned_tweet_id]

#post_count ⇒ Integer? (readonly)

The number of posts

Examples:

Get the post count

user.post_count

Returns:

  • (Integer, nil) —

    the post count



406
# File 'x-objects/lib/x/objects/user.rb', line 406

attribute :post_count, :integer, key: %w[public_metrics post_count], tweet_key: %w[public_metrics tweet_count]

#profile_banner_url ⇒ String? (readonly)

The profile banner URL

Examples:

Get the profile banner URL

user.profile_banner_url

Returns:

  • (String, nil) —

    the profile banner URL



150
# File 'x-objects/lib/x/objects/user.rb', line 150

attribute :profile_banner_url

#profile_image_url ⇒ String? (readonly)

The profile image URL

Examples:

Get the profile image URL

user.profile_image_url

Returns:

  • (String, nil) —

    the profile image URL



142
# File 'x-objects/lib/x/objects/user.rb', line 142

attribute :profile_image_url

#protected ⇒ Boolean? (readonly)

Whether the account's posts are protected

Examples:

Check whether a user is protected

user.protected?

Returns:

  • (Boolean, nil) —

    true if the posts are protected



166
# File 'x-objects/lib/x/objects/user.rb', line 166

attribute :protected, :boolean

#public_metrics ⇒ Hash? (readonly)

The public metrics

Examples:

Get the public metrics

user.public_metrics

Returns:

  • (Hash, nil) —

    the public metrics



382
# File 'x-objects/lib/x/objects/user.rb', line 382

attribute :public_metrics, :object

#receives_your_dm ⇒ Boolean? (readonly)

Whether the authenticated user can send this user a direct message

It depends on who is authenticated, so no lookup asks for it unless user.fields names it, and a user looked up otherwise holds none, and reads nil rather than false, which would say the user receives none.

Examples:

Check whether a user can be sent a direct message

client.find_user("sferik", "user.fields": "receives_your_dm").receives_your_dm?

Returns:

  • (Boolean, nil) —

    true if the authenticated user can send this user a direct message, or nil when the response holds none



296
# File 'x-objects/lib/x/objects/user.rb', line 296

attribute :receives_your_dm, :boolean

#subscriber_count ⇒ Integer? (readonly)

The number of users who subscribe to the user

Examples:

Get the subscriber count

user.subscriber_count

Returns:

  • (Integer, nil) —

    the subscriber count



270
# File 'x-objects/lib/x/objects/user.rb', line 270

attribute :subscriber_count, :integer

#subscribes_to_you ⇒ Boolean? (readonly)

Whether this user subscribes to the authenticated user

It depends on who is authenticated, so no lookup asks for it unless user.fields names it, and a user looked up otherwise holds none, and reads nil rather than false.

Examples:

Check whether a user subscribes to the authenticated user

client.find_user("sferik", "user.fields": "subscribes_to_you").subscribes_to_you?

Returns:

  • (Boolean, nil) —

    true if this user subscribes to the authenticated user, or nil when the response holds none



320
# File 'x-objects/lib/x/objects/user.rb', line 320

attribute :subscribes_to_you, :boolean

#subscription ⇒ Hash? (readonly)

The subscription between this user and the authenticated user

It depends on who is authenticated, so no lookup asks for it unless user.fields names it, and a user looked up otherwise holds none.

Examples:

Check whether a user subscribes to the authenticated user

client.find_user("sferik", "user.fields": "subscription").subscription&.fetch("subscribes_to_you")

Returns:

  • (Hash, nil) —

    the subscription, with subscribes_to_you, or nil when the response holds none



342
# File 'x-objects/lib/x/objects/user.rb', line 342

attribute :subscription, :object

#subscription_type ⇒ String? (readonly)

The subscription the account pays for: Basic, Premium, PremiumPlus, or None

Examples:

Get the subscription type

user.subscription_type

Returns:

  • (String, nil) —

    the subscription type



234
# File 'x-objects/lib/x/objects/user.rb', line 234

attribute :subscription_type

#url ⇒ String? (readonly)

The URL of the website the profile links to

The API gives it shortened, as a t.co link, and the URL it stands for is in the url entities of #entities. It is not the address of the profile on x.com, which #permalink and #uri read.

Examples:

Get the URL

user.url # => "https://t.co/abc"

Returns:

  • (String, nil) —

    the URL, or nil for a profile that links to no website



134
# File 'x-objects/lib/x/objects/user.rb', line 134

attribute :url

#username ⇒ String? (readonly)

The handle, without the leading at sign

Examples:

Get the username

user.username # => "sferik"

Returns:

  • (String, nil) —

    the username



106
# File 'x-objects/lib/x/objects/user.rb', line 106

attribute :username

#verified ⇒ Boolean? (readonly)

Whether the account is verified

Examples:

Check whether a user is verified

user.verified?

Returns:

  • (Boolean, nil) —

    true if the account is verified



181
# File 'x-objects/lib/x/objects/user.rb', line 181

attribute :verified, :boolean

#verified_followers_count ⇒ Integer? (readonly)

The number of verified followers

Examples:

Get the verified follower count

user.verified_followers_count

Returns:

  • (Integer, nil) —

    the verified follower count



262
# File 'x-objects/lib/x/objects/user.rb', line 262

attribute :verified_followers_count, :integer

#verified_type ⇒ String? (readonly)

The verification type: blue, business, government, or none

Examples:

Get the verification type

user.verified_type

Returns:

  • (String, nil) —

    the verification type



196
# File 'x-objects/lib/x/objects/user.rb', line 196

attribute :verified_type

#withheld ⇒ Hash? (readonly)

The withholding details

Examples:

Get the withholding details

user.withheld

Returns:

  • (Hash, nil) —

    the withholding details



374
# File 'x-objects/lib/x/objects/user.rb', line 374

attribute :withheld, :object

Class Method Details

.default_params ⇒ Hash{String => Array<String>}

The default query parameters requesting every user field and expansion

Examples:

Get the default parameters

X::User.default_params["user.fields"]

Returns:

  • (Hash{String => Array<String>}) —

    the default query parameters



74
75
76
# File 'x-objects/lib/x/objects/user.rb', line 74

def default_params
  {"user.fields" => FIELDS, "post.fields" => Post::FIELDS, "expansions" => EXPANSIONS}
end

.search(query, client:, **params) ⇒ Cursor

Search users

Examples:

Print the users matching a query

X::User.search("ruby", client: client).each { |user| puts user.username }

Parameters:

  • query (String) —

    the search query

  • client (Object) —

    the client used to make the requests

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the matching users



87
88
89
# File 'x-objects/lib/x/objects/user.rb', line 87

def search(query, client:, **params)
  Cursor.__send__(:build, self, "users/search", client:, params: {query:, max_results: MAX_SEARCH_RESULTS}.merge(params), token_param: "next_token")
end

Instance Method Details

#affiliated_with ⇒ Array<User>

The accounts this account is affiliated with, such as its organization

They come from the includes, or as stubs holding their identifiers. They point the other way from affiliates, the accounts affiliated with this one.

Examples:

Get the username of the affiliated organization

user.affiliated_with.first&.hydrate&.username

Returns:

  • (Array<User>) —

    the accounts it is affiliated with, empty if there are none



457
# File 'x-objects/lib/x/objects/user.rb', line 457

references :affiliated_with, :User, key: %w[affiliation user_id]

#identity_verified? ⇒ Boolean

Check whether the account's identity is verified

Examples:

Check whether a user's identity is verified

user.identity_verified?

Returns:

  • (Boolean) —

    true if the identity is verified



# File 'x-objects/lib/x/objects/user.rb', line 221

#most_recent_post ⇒ Post? Also known as: most_recent_tweet

The most recent post, from the includes or as a stub holding only its identifier

Examples:

Get the most recent post

user.most_recent_post

Returns:

  • (Post, nil) —

    the most recent post



446
# File 'x-objects/lib/x/objects/user.rb', line 446

reference :most_recent_post, :Post, key: %w[most_recent_post_id], tweet_key: %w[most_recent_tweet_id]

#parody? ⇒ Boolean

Check whether the account labels itself a parody

Examples:

Leave out the parody accounts

users.reject(&:parody?)

Returns:

  • (Boolean) —

    true if the account is labelled a parody



# File 'x-objects/lib/x/objects/user.rb', line 206

The permalink of the profile, by username when known and by identifier otherwise

It is the address of the profile on x.com, not the website the profile links to, which #url reads.

Examples:

Get the permalink

user.permalink # => "https://x.com/sferik"

Returns:

  • (String) —

    the x.com address of the profile



473
# File 'x-objects/lib/x/objects/user.rb', line 473

def permalink = "https://x.com/#{username || "i/user/#{id}"}"

#pinned_post ⇒ Post? Also known as: pinned_tweet

The pinned post, from the includes or as a stub holding only its identifier

Examples:

Get the pinned post

user.pinned_post

Returns:

  • (Post, nil) —

    the pinned post



438
# File 'x-objects/lib/x/objects/user.rb', line 438

reference :pinned_post, :Post, key: %w[pinned_post_id], tweet_key: %w[pinned_tweet_id]

#protected? ⇒ Boolean

Check whether the account's posts are protected

Examples:

Check whether the account's posts are protected

user.protected?

Returns:

  • (Boolean) —

    true if the posts are protected



# File 'x-objects/lib/x/objects/user.rb', line 168

#receives_your_dm? ⇒ Boolean

Check whether the authenticated user can send this user a direct message

A user whose response holds no receives_your_dm, such as one looked up without asking for it, is not known to receive one, and reads false.

Examples:

Message the users who can be sent one

users.select(&:receives_your_dm?).each { |user| client.create_dm(user, "Hello!") }

Returns:

  • (Boolean) —

    true if the response says the authenticated user can send this user a direct message



# File 'x-objects/lib/x/objects/user.rb', line 298

#subscribes_to_you? ⇒ Boolean

Check whether this user subscribes to the authenticated user

A user whose response holds no subscribes_to_you, such as one looked up without asking for it, reads false.

Examples:

Find the subscribers among some users

users.select(&:subscribes_to_you?)

Returns:

  • (Boolean) —

    true if the response says this user subscribes to the authenticated user



# File 'x-objects/lib/x/objects/user.rb', line 322

#uri ⇒ URI::Generic

The permalink of the user as a URI

It is the address of the profile on x.com, not the website the profile links to, which #url reads.

Examples:

Get the address as a URI

user.uri # => #<URI::HTTPS https://x.com/sferik>

Returns:

  • (URI::Generic) —

    the x.com address of the user



483
# File 'x-objects/lib/x/objects/user.rb', line 483

def uri = URI(permalink)

#verified? ⇒ Boolean

Check whether the account is verified

Examples:

Check whether the account is verified

user.verified?

Returns:

  • (Boolean) —

    true if the account is verified



# File 'x-objects/lib/x/objects/user.rb', line 183