Module: X::Objects::API

Includes:
X::Objects::Actions::DirectMessages, X::Objects::Actions::Engagement, X::Objects::Actions::Lists, X::Objects::Actions::Posts, X::Objects::Actions::Relationships, Lookups::Communities, Lookups::DirectMessages, Lookups::Lists, Lookups::Media, Lookups::Posts, Lookups::Spaces, Lookups::Trends, Lookups::Users
Included in:
Client
Defined in:
x-objects/lib/x/objects/api.rb

Overview

The resource methods mixed into a client that responds to get, post, put, and delete

The x gem includes it into X::Client. With x-core and x-objects alone, or with a client of your own, include it yourself: X::Client.include(X::Objects::API).

It is the one module of the object layer to include. The modules it includes, those of Lookups and Actions, are internal: their methods are public API of the client that includes API, but how they are grouped can change within 1.x, and some need the methods of another, such as current_user_id. So are the modules the resource classes extend and include, such as Finders and Relationships: the methods they give a resource class are public API, the modules are not.

Neither API nor a module it includes holds a constant, as a constant of a module is a constant of each class that includes it: a class that inherits from the client and names Media, or Users, reads the constant the name reads anywhere else, not a module of the object layer.

Instance Method Summary collapse

Instance Method Details

#add_list_member(list, user) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Add a member to a list as the authenticated user

Examples:

Add a member to a list

client.add_list_member("1234567890", user)

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the user is now a member

#block(user) ⇒ Boolean Originally defined in module X::Objects::Actions::Relationships

Block a user as the authenticated user

Examples:

Block a user

client.block("7505382")

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the authenticated user now blocks the user

#bookmark(post) ⇒ Boolean Originally defined in module X::Objects::Actions::Engagement

Bookmark a post as the authenticated user

The bookmark endpoints take only OAuth 2.0 user context, which the object layer cannot route around, so a client that signs with OAuth 1.0a is refused.

Examples:

Bookmark a post

client.bookmark("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user has bookmarked the post

#count_all_posts(query, **params) ⇒ Integer Also known as: count_all_tweets Originally defined in module Lookups::Posts

Count the posts from the full archive that match a query, without reading them

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user that holds no credentials of the app counts as the user, which the full archive refuses with X::Forbidden.

Examples:

Count every post about Ruby from 2024

client.count_all_posts("ruby", start_time: "2024-01-01T00:00:00Z", end_time: "2025-01-01T00:00:00Z")

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters, such as start_time and end_time, and the max_pages of X::Post.count_all, which limits the pages of counts requested

Returns:

  • (Integer) —

    the number of matching posts

#count_all_posts_by_period(query, **params) ⇒ Hash{Range<Time> => Integer} Also known as: count_all_tweets_by_period Originally defined in module Lookups::Posts

Count the posts from the full archive that match a query, by period

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user that holds no credentials of the app counts as the user, which the full archive refuses with X::Forbidden.

Examples:

Count the posts about Ruby by day in 2024

client.count_all_posts_by_period("ruby", start_time: "2024-01-01T00:00:00Z", end_time: "2025-01-01T00:00:00Z")

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters, such as granularity, which is day by default, and the max_pages of X::Post.count_all_by_period, which limits the pages of counts requested

Returns:

  • (Hash{Range<Time> => Integer}) —

    the number of matching posts, keyed by the time each period spans, from its start up to, but not including, its end, oldest first

#count_posts(query, **params) ⇒ Integer Also known as: count_tweets Originally defined in module Lookups::Posts

Count the recent posts that match a query, without reading them

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app.

Examples:

Count the recent posts about Ruby with an app-only client

client.count_posts("ruby")

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters, such as start_time and end_time, and max_pages, the most pages of counts to request

Returns:

  • (Integer) —

    the number of matching posts

#count_posts_by_period(query, **params) ⇒ Hash{Range<Time> => Integer} Also known as: count_tweets_by_period Originally defined in module Lookups::Posts

Count the posts from the last seven days that match a query, by period

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app.

Examples:

Count the recent posts about Ruby by hour

client.count_posts_by_period("ruby", granularity: "hour")

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters, such as granularity, which is day by default, and max_pages, the most pages of counts to request

Returns:

  • (Hash{Range<Time> => Integer}) —

    the number of matching posts, keyed by the time each period spans, from its start up to, but not including, its end, oldest first

#create_direct_message(user, text = nil, **params) ⇒ DirectMessage Also known as: create_dm Originally defined in module X::Objects::Actions::DirectMessages

Send a direct message to a user as the authenticated user

Examples:

Send a direct message

client.create_direct_message(user, "Hello!")

Send an image without text

client.create_direct_message(user, media_ids: media)

Parameters:

  • user (User, String, Integer) —

    the recipient or their identifier

  • text (String, nil) (defaults to: nil) —

    the text of the message, or nil for a message of attachments alone

  • params (Hash) —

    additional request body fields, such as media_ids or attachments

Options Hash (**params):

  • :media_ids (Array<String, Integer, #fetch, Media>, String, Integer, #fetch, Media) —

    the identifiers or media keys of uploaded media to attach, what the uploads returned, or media, such as that of a post, one or many

Returns:

  • (DirectMessage) —

    the sent message, holding only its identifiers

Raises:

  • (ArgumentError) —

    if the message has neither text nor any other field, or has both media_ids and attachments

  • (MissingResource) —

    if the API answers without the message

#create_direct_message_in(conversation, text = nil, **params) ⇒ DirectMessage Also known as: create_dm_in Originally defined in module X::Objects::Actions::DirectMessages

Send a direct message to a conversation as the authenticated user

The conversation can be one-to-one or a group.

Examples:

Reply to the conversation of a message

client.create_direct_message_in(message, "Sounds good")

Reply with an image

client.create_direct_message_in(message, media_ids: media)

Parameters:

  • conversation (DirectMessage, String, Integer) —

    a message of the conversation, or the conversation's identifier

  • text (String, nil) (defaults to: nil) —

    the text of the message, or nil for a message of attachments alone

  • params (Hash) —

    additional request body fields, such as media_ids or attachments

Options Hash (**params):

  • :media_ids (Array<String, Integer, #fetch, Media>, String, Integer, #fetch, Media) —

    the identifiers or media keys of uploaded media to attach, what the uploads returned, or media, such as that of a post, one or many

Returns:

  • (DirectMessage) —

    the sent message, holding only its identifiers

Raises:

  • (ArgumentError) —

    if the conversation identifier is not one, the message has neither text nor any other field, or it has both media_ids and attachments

  • (MissingResource) —

    if the API answers without the message

#create_group_direct_message(users, text = nil, **params) ⇒ DirectMessage Also known as: create_group_dm Originally defined in module X::Objects::Actions::DirectMessages

Start a group conversation, sending its first message as the authenticated user

Examples:

Start a group conversation

client.create_group_direct_message([alice, bob], "Hello, both of you!")

Start a group conversation with an image

client.create_group_direct_message([alice, bob], media_ids: media)

Parameters:

  • users (Array<User, String, Integer>) —

    the other participants or their identifiers

  • text (String, nil) (defaults to: nil) —

    the text of the first message, or nil for a message of attachments alone

  • params (Hash) —

    additional fields of the message, such as media_ids or attachments

Options Hash (**params):

  • :media_ids (Array<String, Integer, #fetch, Media>, String, Integer, #fetch, Media) —

    the identifiers or media keys of uploaded media to attach, what the uploads returned, or media, such as that of a post, one or many

Returns:

  • (DirectMessage) —

    the sent message, holding only its identifiers, among them the conversation's

Raises:

  • (ArgumentError) —

    if the message has neither text nor any other field, or has both media_ids and attachments

  • (MissingResource) —

    if the API answers without the message

#create_list(name, **params) ⇒ List Originally defined in module X::Objects::Actions::Lists

Create a list owned by the authenticated user

Examples:

Create a private list

client.create_list("Rubyists", private: true)

Parameters:

  • name (String) —

    the name of the list

  • params (Hash) —

    additional request body fields: description and private

Returns:

  • (List) —

    the created list, holding only its identifier and name

Raises:

#create_post(text = nil, **params) ⇒ Post Also known as: create_tweet Originally defined in module X::Objects::Actions::Posts

Create a post as the authenticated user

The API bills each post created, and bills a post whose text holds a URL more than ten times as much. A post needs no text when it has something else to show, such as media.

Examples:

Create a post

client.create_post("Hello, World!")

Post an image without text

client.create_post(media_ids: [media])

Reply to a post with an image

client.create_post("Hello!", reply_to: post, media_ids: [media["id"]])

Quote a post

client.create_post("Worth reading", quote: post)

Parameters:

  • text (String, nil) (defaults to: nil) —

    the text of the post, or nil for a post without text, such as one of media alone

  • params (Hash) —

    additional request body fields, such as reply_to, quote, media_ids, or poll

Returns:

  • (Post) —

    the created post, holding only its identifier and text

Raises:

  • (ArgumentError) —

    if the post has neither text nor any other field

  • (MissingResource) —

    if the API answers without the post

#current_user(**params) {|problem| ... } ⇒ User? Originally defined in module Lookups::Users

Look up the authenticated user

Each call looks the user up, as X::User.current does, so its counts and profile are as they are now. Keep the user it returns to read them again without a request.

Examples:

Print the name of the authenticated user

puts client.current_user&.name

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported

Returns:

  • (User, nil) —

    the authenticated user, or nil if the API returns none

#current_user!(**params) ⇒ User Originally defined in module Lookups::Users

Look up the authenticated user, who must be found

Each call looks the user up, as X::User.current! does, so its counts and profile are as they are now. Keep the user it returns to read them again without a request.

Examples:

Print the home timeline of the authenticated user

client.current_user!.home_timeline.each { |post| puts post.text }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (User) —

    the authenticated user

Raises:

#current_user_id ⇒ Integer Originally defined in module Lookups::Users

The identifier of the authenticated user, from an OAuth 1.0a token if possible

An OAuth 1.0a access token begins with the identifier of its user, so a client that holds one needs no lookup. Any other client looks the user up the first time, unless current_user or current_user! already has, and keeps the identifier, which never changes, for as long as it holds the same authenticator, since a client whose credentials change authenticates as someone else. A frozen client keeps nothing, and looks the user up each time.

Examples:

Get the identifier of the authenticated user

client.current_user_id # => 7505382

Returns:

  • (Integer) —

    the identifier

Raises:

#delete_direct_message(message) ⇒ Boolean Also known as: delete_dm Originally defined in module X::Objects::Actions::DirectMessages

Delete a direct message event as the authenticated user

Examples:

Delete a direct message

client.delete_direct_message("1234567890")

Parameters:

  • message (DirectMessage, String, Integer) —

    the event or its identifier

Returns:

  • (Boolean) —

    true if the event was deleted

#delete_list(list) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Delete a list as the authenticated user

Examples:

Delete a list

client.delete_list("1234567890")

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

Returns:

  • (Boolean) —

    true if the list was deleted

#delete_post(post) ⇒ Boolean Also known as: delete_tweet Originally defined in module X::Objects::Actions::Posts

Delete a post as the authenticated user

Examples:

Delete a post

client.delete_post("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the post was deleted

#direct_messages(**params) ⇒ Cursor Also known as: dms Originally defined in module Lookups::DirectMessages

The most recent direct message events across every conversation

Examples:

Print the most recent direct messages

client.direct_messages.first(10).each { |message| puts message.text }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the events

#direct_messages_in(conversation, **params) ⇒ Cursor Also known as: dms_in Originally defined in module Lookups::DirectMessages

The direct message events of a conversation, one-to-one or group

Examples:

Print the conversation a message belongs to

client.direct_messages_in(message).each { |event| puts event.text }

Parameters:

  • conversation (DirectMessage, String, Integer) —

    a message of the conversation, or the conversation's identifier

  • params (Hash) —

    query parameters merged over the default parameters, such as event_types

Returns:

  • (Cursor) —

    a cursor over the events

Raises:

  • (ArgumentError) —

    if the conversation identifier is not one

#direct_messages_with(user, **params) ⇒ Cursor Also known as: dms_with Originally defined in module Lookups::DirectMessages

The direct message events in the one-to-one conversation with a user

Examples:

Print the conversation with a user

client.direct_messages_with(user).each { |message| puts message.text }

Parameters:

  • user (User, String, Integer) —

    the other participant or their identifier

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the events

#find_all_media(media, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<X::Media> Originally defined in module Lookups::Media

Look up media by media key, in parallel batches

Examples:

Look up the media of a post

client.find_all_media(post.media)

Look up media by media key

client.find_all_media(%w[3_1880028106020515840 3_1880028106020515841])

Parameters:

  • media (Array<String, X::Media, #media_key>) —

    the media keys, or the media, or what the uploads returned, whose keys are taken

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one; each is a request of up to 100 media keys, so a lower number spends a rate limit more slowly

  • params (Hash) —

    query parameters merged over the default parameters; one that overrides a default field parameter builds media that is not hydrated, so hydrate fetches the rest

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a media key that was not found

Returns:

  • (Array<X::Media>) —

    the media that was found

Raises:

  • (ArgumentError) —

    if the concurrency is less than one

#find_all_posts(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Post> Also known as: find_all_tweets Originally defined in module Lookups::Posts

Look up many posts by identifier, in parallel batches

Examples:

Look up many posts

client.find_all_posts([1234567890, 1234567891])

Look up many posts one batch at a time

client.find_all_posts(ids, concurrency: 1)

Parameters:

  • ids (Array<String, Integer, Post>) —

    the identifiers

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one; each is a request of up to 100 posts, so a lower number spends a rate limit more slowly

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Array<Post>) —

    the posts that were found

Raises:

  • (ArgumentError) —

    if the concurrency is less than one

#find_all_spaces(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Space> Originally defined in module Lookups::Spaces

Look up many spaces by identifier, in parallel batches

Examples:

Look up many spaces

client.find_all_spaces(["1DXxyRYNejbKM", "1OwGWzarWnNKQ"]).map(&:title)

Parameters:

  • ids (Array<String, Integer, Space>) —

    the identifiers

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Array<Space>) —

    the spaces that were found

Raises:

  • (ArgumentError) —

    if the concurrency is less than one

#find_all_spaces_by_creator(users, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Space> Originally defined in module Lookups::Spaces

Look up the live and scheduled spaces many users created, in parallel batches

Examples:

Print the live spaces a user created

client.find_all_spaces_by_creator([7505382]).select { |space| space.state.eql?("live") }.map(&:title)

Parameters:

  • users (Array<User, String, Integer>) —

    the users who created the spaces, or their identifiers

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported

Returns:

  • (Array<Space>) —

    the spaces, frozen, empty if the users created none

Raises:

  • (ArgumentError) —

    if a user is not a user or the identifier of one, or the concurrency is less than one, before a request

#find_all_users(ids_or_usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User> Originally defined in module Lookups::Users

Look up many users by identifier or username, in parallel batches

Examples:

Look up many users by username

client.find_all_users(["sferik", "gem"])

Look up many users one batch at a time

client.find_all_users(ids, concurrency: 1)

Parameters:

  • ids_or_usernames (Array<Integer, User, String>) —

    identifiers or users, or usernames

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one; each is a request of up to 100 users, so a lower number spends a rate limit more slowly

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Array<User>) —

    the users that were found

Raises:

  • (ArgumentError) —

    if the concurrency is less than one

#find_all_users_by_id(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User> Originally defined in module Lookups::Users

Look up many users by identifier, in parallel batches

A String of digits is an identifier, as it is read from a response or an environment variable, so this looks the accounts those numbers identify up, where find_all_users would take them for usernames.

Examples:

Look up many users by identifier, read as Strings

client.find_all_users_by_id(ENV.fetch("USER_IDS").split(","))

Parameters:

  • ids (Array<String, Integer, User>) —

    the identifiers, or users

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as an identifier that was not found

Returns:

  • (Array<User>) —

    the users that were found

Raises:

  • (ArgumentError) —

    if a value is not an identifier, or if the concurrency is less than one

#find_all_users_by_username(usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User> Originally defined in module Lookups::Users

Look up many users by username, in parallel batches

It looks every value up as a username, Strings of digits as the accounts whose handles are those numbers, as find_all_users looks up any String, so code that reads values from elsewhere says which it means, as find_all_users_by_id does.

Examples:

Look up many users by username

client.find_all_users_by_username(["sferik", "1234567890"])

Parameters:

  • usernames (Array<String>) —

    the usernames, with or without leading at signs

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a username that was not found

Returns:

  • (Array<User>) —

    the users that were found

Raises:

  • (ArgumentError) —

    if a value is not a username, or if the concurrency is less than one

#find_community(id, **params) {|problem| ... } ⇒ Community? Originally defined in module Lookups::Communities

Look up a community by identifier

Examples:

Look up a community

client.find_community(1234567890).name

Parameters:

  • id (String, Integer, Community) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Community, nil) —

    the community or nil if the community was not found

#find_community!(id, **params) ⇒ Community Originally defined in module Lookups::Communities

Look up a community by identifier, which must exist

Examples:

Look up a community

client.find_community!(1234567890).name

Parameters:

  • id (String, Integer, Community) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

Raises:

#find_direct_message(id, **params) {|problem| ... } ⇒ DirectMessage? Also known as: find_dm Originally defined in module Lookups::DirectMessages

Look up a direct message event by identifier

Examples:

Look up a direct message

client.find_direct_message(1234567890).text

Parameters:

  • id (String, Integer, DirectMessage) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (DirectMessage, nil) —

    the event or nil if the event was not found

#find_direct_message!(id, **params) ⇒ DirectMessage Also known as: find_dm! Originally defined in module Lookups::DirectMessages

Look up a direct message event by identifier, which must exist

Examples:

Look up a direct message

client.find_direct_message!(1234567890).text

Parameters:

  • id (String, Integer, DirectMessage) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

Raises:

#find_list(id, **params) {|problem| ... } ⇒ List? Originally defined in module Lookups::Lists

Look up a list by identifier

Examples:

Look up a list

client.find_list(1234567890).name

Parameters:

  • id (String, Integer, List) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (List, nil) —

    the list or nil if the list was not found

#find_list!(id, **params) ⇒ List Originally defined in module Lookups::Lists

Look up a list by identifier, which must exist

Examples:

Look up a list

client.find_list!(1234567890).name

Parameters:

  • id (String, Integer, List) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (List) —

    the list

Raises:

#find_media(media_key, **params) {|problem| ... } ⇒ X::Media? Originally defined in module Lookups::Media

Look up media by media key

A post refers to its media by media key, and so does what an upload returns, so this reads the photo, video, or animated GIF that was uploaded, with its URL and variants.

Examples:

Look up media by media key

client.find_media("3_1880028106020515840")

Look up media that was uploaded

client.find_media(uploaded)

Parameters:

  • media_key (String, X::Media, #media_key) —

    the media key, such as 3_1880028106020515840, media, or what an upload returned

  • params (Hash) —

    query parameters merged over the default parameters; one that overrides a default field parameter to leave some out builds media that is not hydrated, so hydrate fetches the rest

Yield Parameters:

  • problem (Problem) —

    each problem the API reported

Returns:

  • (X::Media, nil) —

    the media, or nil if it was not found

#find_media!(media_key, **params) ⇒ X::Media Originally defined in module Lookups::Media

Look up media by media key, raising if it is not found

Examples:

Look up media that must exist

client.find_media!("3_1880028106020515840")

Parameters:

  • media_key (String, X::Media, #media_key) —

    the media key, media, or what an upload returned

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

Raises:

#find_post(id, **params) {|problem| ... } ⇒ Post? Also known as: find_tweet Originally defined in module Lookups::Posts

Look up a post by identifier

Examples:

Look up a post

client.find_post(1234567890).text

Parameters:

  • id (String, Integer, Post) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Post, nil) —

    the post or nil if the post was not found

#find_post!(id, **params) ⇒ Post Also known as: find_tweet! Originally defined in module Lookups::Posts

Look up a post by identifier, which must exist

Examples:

Look up a post

client.find_post!(1234567890).text

Parameters:

  • id (String, Integer, Post) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Post) —

    the post

Raises:

#find_space(id, **params) {|problem| ... } ⇒ Space? Originally defined in module Lookups::Spaces

Look up a space by identifier

Examples:

Look up a space

client.find_space("1DXxyRYNejbKM").title

Parameters:

  • id (String, Integer, Space) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Space, nil) —

    the space or nil if the space was not found

#find_space!(id, **params) ⇒ Space Originally defined in module Lookups::Spaces

Look up a space by identifier, which must exist

Examples:

Look up a space

client.find_space!("1DXxyRYNejbKM").title

Parameters:

  • id (String, Integer, Space) —

    the identifier

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

Raises:

#find_user(id_or_username, **params) {|problem| ... } ⇒ User? Originally defined in module Lookups::Users

Look up a user by identifier or username

Examples:

Look up a user by username

client.find_user("sferik")

Look up a user by identifier

client.find_user(7505382)

Parameters:

  • id_or_username (Integer, User, String) —

    an identifier or a user, or a username

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (User, nil) —

    the user or nil if the user was not found

#find_user!(id_or_username, **params) ⇒ User Originally defined in module Lookups::Users

Look up a user by identifier or username, which must exist

Examples:

Look up a user by username

client.find_user!("sferik")

Parameters:

  • id_or_username (Integer, User, String) —

    an identifier or a user, or a username

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (User) —

    the user

Raises:

#find_user_by_id(id, **params) {|problem| ... } ⇒ User? Originally defined in module Lookups::Users

Look up a user by identifier

A String of digits is an identifier, as it is read from a response or an environment variable, so this looks the account that number identifies up, where find_user would take it for a username.

Examples:

Look up a user by an identifier read as a String

client.find_user_by_id(ENV.fetch("USER_ID"))

Parameters:

  • id (String, Integer, User) —

    the identifier, or a user

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (User, nil) —

    the user or nil if the user was not found

Raises:

  • (ArgumentError) —

    if the value is not an identifier

#find_user_by_id!(id, **params) ⇒ User Originally defined in module Lookups::Users

Look up a user by identifier, which must exist

Examples:

Look up a user by an identifier read as a String

client.find_user_by_id!("7505382")

Parameters:

  • id (String, Integer, User) —

    the identifier, or a user

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (User) —

    the user

Raises:

  • (ArgumentError) —

    if the value is not an identifier

  • (MissingResource) —

    if the user was not found

#find_user_by_username(username, **params) {|problem| ... } ⇒ User? Originally defined in module Lookups::Users

Look up a user by username

It looks every value up as a username, a String of digits as the account whose handle is that number, as find_user looks up any String, so code that reads a value from elsewhere says which it means, as find_user_by_id does.

Examples:

Look up a user whose username is a number

client.find_user_by_username("1234567890")

Parameters:

  • username (String) —

    the username, with or without a leading at sign

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (User, nil) —

    the user or nil if the user was not found

Raises:

  • (ArgumentError) —

    if the value is not a username

#find_user_by_username!(username, **params) ⇒ User Originally defined in module Lookups::Users

Look up a user by username, which must exist

Examples:

Look up a user by username

client.find_user_by_username!("sferik")

Parameters:

  • username (String) —

    the username, with or without a leading at sign

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (User) —

    the user

Raises:

  • (ArgumentError) —

    if the value is not a username

  • (MissingResource) —

    if the user was not found

#follow(user) ⇒ Boolean Originally defined in module X::Objects::Actions::Relationships

Follow a user as the authenticated user

A protected user must accept a request to follow them first, so for a protected user true means the follow was requested, not that the authenticated user follows them: until they accept it, the follows? of the authenticated user, as in client.current_user!.follows?(user), answers false.

Examples:

Follow a user

client.follow("7505382")

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the authenticated user now follows the user, or, for a protected user, has requested to follow them

#follow_list(list) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Follow a list as the authenticated user

Examples:

Follow a list

client.follow_list("1234567890")

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user now follows the list

#hide_reply(post) ⇒ Boolean Originally defined in module X::Objects::Actions::Posts

Hide a reply to a post of the authenticated user

Examples:

Hide a reply

client.hide_reply("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the reply or its identifier

Returns:

  • (Boolean) —

    true if the reply is now hidden

#like(post) ⇒ Boolean Originally defined in module X::Objects::Actions::Engagement

Like a post as the authenticated user

Examples:

Like a post

client.like("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user now likes the post

#mute(user) ⇒ Boolean Originally defined in module X::Objects::Actions::Relationships

Mute a user as the authenticated user

Examples:

Mute a user

client.mute("7505382")

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the authenticated user now mutes the user

#personalized_trends(**params) ⇒ Array<PersonalizedTrend> Originally defined in module Lookups::Trends

The topics trending for the authenticated user

Examples:

Print the topics trending for the authenticated user

client.personalized_trends.each { |trend| puts trend.name }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

#pin_list(list) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Pin a list as the authenticated user

Examples:

Pin a list

client.pin_list("1234567890")

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user has pinned the list

#post_usage(**params) {|problem| ... } ⇒ PostUsage? Originally defined in module Lookups::Posts

Look up how many posts the app's project has read

The usage endpoint takes app-only authentication alone, so a client that signs with OAuth 1.0a looks it up with a copy that authenticates as the app, and one signed in with OAuth 2.0 as a user that holds no credentials of the app is refused with X::Forbidden.

A response that holds no usage returns nil, as current_user does for a users/me that holds no user, and passes the problems it reported to the block, if there is one.

Examples:

Check how much of the monthly cap remains

usage = client.post_usage
usage.project_cap - usage.project_usage if usage

Parameters:

  • params (Hash) —

    query parameters, such as days, the number of days to report, which is 7 by default

Yield Parameters:

  • problem (Problem) —

    each problem the API reported

Returns:

  • (PostUsage, nil) —

    the usage, or nil if the response holds none

#post_usage!(**params) ⇒ PostUsage Originally defined in module Lookups::Posts

Look up how many posts the app's project has read, which must be returned

Examples:

Check how much of the monthly cap remains

usage = client.post_usage!
usage.project_cap - usage.project_usage

Parameters:

  • params (Hash) —

    query parameters, such as days, the number of days to report, which is 7 by default

Returns:

Raises:

#remove_list_member(list, user) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Remove a member from a list as the authenticated user

Examples:

Remove a member from a list

client.remove_list_member("1234567890", user)

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the user is no longer a member

#repost(post) ⇒ Boolean Also known as: retweet Originally defined in module X::Objects::Actions::Engagement

Repost a post as the authenticated user

Examples:

Repost a post

client.repost("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user has reposted the post

#reposts_of_me(**params) ⇒ Cursor Also known as: retweets_of_me Originally defined in module Lookups::Posts

The posts of the authenticated user that other users have reposted

Examples:

Print the reposted posts

client.reposts_of_me.each { |post| puts post.text }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the reposted posts

#search_all_posts(query, **params) ⇒ Cursor Also known as: search_all_tweets Originally defined in module Lookups::Posts

Search the full archive of posts

Examples:

Print every post about Ruby

client.search_all_posts("ruby -is:retweet").each { |post| puts post.text }

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the matching posts

#search_communities(query, **params) ⇒ Cursor Originally defined in module Lookups::Communities

Search communities

Examples:

Print the communities matching a query

client.search_communities("ruby").each { |community| puts community.name }

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the matching communities

#search_posts(query, **params) ⇒ Cursor Also known as: search_tweets Originally defined in module Lookups::Posts

Search recent posts

Examples:

Print posts about Ruby

client.search_posts("ruby -is:retweet").each { |post| puts post.text }

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the matching posts

#search_spaces(query, **params) ⇒ Cursor Originally defined in module Lookups::Spaces

Search spaces by their titles

Examples:

Print the live spaces about Ruby

client.search_spaces("ruby", state: "live").each { |space| puts space.title }

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters merged over the default parameters, such as state: live or scheduled

Returns:

  • (Cursor) —

    a cursor over the matching spaces

#search_users(query, **params) ⇒ Cursor Originally defined in module Lookups::Users

Search users

Examples:

Print the users matching a query

client.search_users("ruby").each { |user| puts user.username }

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the matching users

#trends(woeid, **params) ⇒ Array<Trend> Originally defined in module Lookups::Trends

The topics trending in a place

Examples:

Print the ten topics trending most in the world

client.trends(1, max_trends: 10).each { |trend| puts trend.name }

Parameters:

  • woeid (Integer, String) —

    the Yahoo! Where On Earth identifier of the place, such as 1 for the world

  • params (Hash) —

    query parameters, such as max_trends, which is 50, the most the API returns, unless given

Returns:

  • (Array<Trend>) —

    the trends, frozen

Raises:

  • (ArgumentError) —

    if the WOEID is not a number, before a request

#unblock(user) ⇒ Boolean Originally defined in module X::Objects::Actions::Relationships

Unblock a user as the authenticated user

Examples:

Unblock a user

client.unblock("7505382")

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer blocks the user

#unbookmark(post) ⇒ Boolean Originally defined in module X::Objects::Actions::Engagement

Remove a bookmark as the authenticated user

The bookmark endpoints take only OAuth 2.0 user context, which the object layer cannot route around, so a client that signs with OAuth 1.0a is refused.

Examples:

Remove a bookmark

client.unbookmark("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer has the post bookmarked

#unfollow(user) ⇒ Boolean Originally defined in module X::Objects::Actions::Relationships

Unfollow a user as the authenticated user

Examples:

Unfollow a user

client.unfollow("7505382")

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer follows the user

#unfollow_list(list) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Unfollow a list as the authenticated user

Examples:

Unfollow a list

client.unfollow_list("1234567890")

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer follows the list

#unhide_reply(post) ⇒ Boolean Originally defined in module X::Objects::Actions::Posts

Show a reply to a post of the authenticated user after hiding it

Examples:

Show a hidden reply

client.unhide_reply("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the reply or its identifier

Returns:

  • (Boolean) —

    true if the reply is no longer hidden

#unlike(post) ⇒ Boolean Originally defined in module X::Objects::Actions::Engagement

Unlike a post as the authenticated user

Examples:

Unlike a post

client.unlike("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer likes the post

#unmute(user) ⇒ Boolean Originally defined in module X::Objects::Actions::Relationships

Unmute a user as the authenticated user

Examples:

Unmute a user

client.unmute("7505382")

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer mutes the user

#unpin_list(list) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Unpin a list as the authenticated user

Examples:

Unpin a list

client.unpin_list("1234567890")

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer has the list pinned

#unrepost(post) ⇒ Boolean Also known as: unretweet Originally defined in module X::Objects::Actions::Engagement

Undo a repost as the authenticated user

Examples:

Undo a repost

client.unrepost("1234567890")

Parameters:

  • post (Post, String, Integer) —

    the post or its identifier

Returns:

  • (Boolean) —

    true if the authenticated user no longer reposts the post

#update_list(list, **params) ⇒ Boolean Originally defined in module X::Objects::Actions::Lists

Update the name, description, or privacy of a list as the authenticated user

Examples:

Make a list private

client.update_list("1234567890", private: true)

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

  • params (Hash) —

    the request body fields to change: name, description, and private

Returns:

  • (Boolean) —

    true if the list was updated

Raises:

  • (ArgumentError) —

    if no field is given to change, before any request