x-resources 1.0.0

data/lib/x/resources/user_collections.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "bookmark_folder"
+require_relative "utils"
+
+module X
+  module Resources
+    # The collections of a user: the users they follow and are followed by, their posts, timelines, bookmarks, and
+    # lists, included into User
+    #
+    # Internal to x-resources: the methods it gives a user, such as followers, are public API, but the module is only how
+    # they are shared, and which classes extend or include it can change within 1.x.
+    #
+    # @api semipublic
+    module UserCollections
+      # Maximum number of users per page of the followers, followed users, affiliates, blocked users, or muted users
+      # @api private
+      MAX_FOLLOW_RESULTS = 1000
+      # Maximum number of posts, lists, or bookmark folders per page of the other collections of a user
+      # @api private
+      MAX_RESULTS = 100
+      private_constant :MAX_FOLLOW_RESULTS, :MAX_RESULTS
+
+      # The users following this user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the followers
+      # @example Print every follower
+      #   user.followers.each { |follower| puts follower.username }
+      def followers(**params)
+        cursor(User, "users/#{id}/followers", max_results: MAX_FOLLOW_RESULTS, total: :followers_count, **params)
+      end
+
+      # The users this user follows
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the followed users
+      # @example Count the followed users
+      #   user.following.count
+      def following(**params)
+        cursor(User, "users/#{id}/following", max_results: MAX_FOLLOW_RESULTS, total: :following_count, **params)
+      end
+
+      # The users affiliated with this user, such as the people of an organization
+      #
+      # They are the accounts whose affiliation names this user, which affiliated_with reads of each of them, so they
+      # point the other way from the affiliated_with of this user.
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the users affiliated with this one
+      # @example Print the users affiliated with an organization
+      #   client.find_user!("X").affiliates.each { |user| puts user.username }
+      def affiliates(**params) = cursor(User, "users/#{id}/affiliates", max_results: MAX_FOLLOW_RESULTS, **params)
+
+      # The users this user blocks, which must be the authenticated user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the blocked users
+      # @example Print every blocked user
+      #   client.current_user!.blocking.each { |user| puts user.username }
+      def blocking(**params)
+        cursor(User, "users/#{id}/blocking", max_results: MAX_FOLLOW_RESULTS, **params)
+      end
+
+      # The users this user mutes, which must be the authenticated user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the muted users
+      # @example Print every muted user
+      #   client.current_user!.muting.each { |user| puts user.username }
+      def muting(**params)
+        cursor(User, "users/#{id}/muting", max_results: MAX_FOLLOW_RESULTS, **params)
+      end
+
+      # The posts by this user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the posts
+      # @example Print the most recent posts
+      #   user.posts.first(10).each { |post| puts post.text }
+      def posts(**params)
+        cursor(Post, "users/#{id}/tweets", max_results: MAX_RESULTS, min_results: 5, **params)
+      end
+
+      # The home timeline of this user, which must be the authenticated user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the posts by the users this user follows, newest first
+      # @example Print the home timeline
+      #   client.current_user!.home_timeline.first(10).each { |post| puts post.text }
+      def home_timeline(**params)
+        cursor(Post, "users/#{id}/timelines/reverse_chronological", max_results: MAX_RESULTS, **params)
+      end
+
+      # The posts mentioning this user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the mentions
+      # @example Print the most recent mentions
+      #   user.mentions.first(10).each { |post| puts post.text }
+      def mentions(**params)
+        cursor(Post, "users/#{id}/mentions", max_results: MAX_RESULTS, min_results: 5, **params)
+      end
+
+      # The posts liked by this user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the liked posts
+      # @example Print the most recently liked posts
+      #   user.liked_posts.first(10).each { |post| puts post.text }
+      def liked_posts(**params)
+        cursor(Post, "users/#{id}/liked_tweets", max_results: MAX_RESULTS, min_results: 5, **params)
+      end
+
+      # The posts bookmarked by the authenticated user, or those of one of their folders
+      #
+      # The API gives the posts of a folder by their identifiers alone, and takes no fields for them, so they are
+      # stubs, which hydrate together, a lookup's worth at a time, as the stubs of any cursor do.
+      #
+      # The bookmark endpoints take only the authentication of a user, OAuth 2.0 user context or OAuth 1.0a, so an
+      # app-only client is refused them; only bookmarking and unbookmarking a post refuse OAuth 1.0a too.
+      #
+      # @api public
+      # @param folder [BookmarkFolder, String, Integer, nil] the folder or its identifier, or nil for every bookmark
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the bookmarked posts
+      # @raise [ArgumentError] if the folder is not a folder or the identifier of one, before a request
+      # @example Print the bookmarked posts
+      #   client.current_user!.bookmarks.each { |post| puts post.text }
+      # @example Print the posts of the first bookmark folder
+      #   user = client.current_user!
+      #   if (folder = user.bookmark_folders.first)
+      #     posts = user.bookmarks(folder:).to_a
+      #     X::Post.hydrate_all(posts, client: client).each { |post| puts post.text }
+      #   end
+      def bookmarks(folder: nil, **params)
+        return cursor(Post, "users/#{id}/bookmarks", max_results: MAX_RESULTS, **params) if folder.nil?
+
+        cursor(Post, "users/#{id}/bookmarks/folders/#{Utils.id_of(folder, BookmarkFolder)}", max_results: MAX_RESULTS, ids_only: true, **params)
+      end
+
+      # The bookmark folders of the authenticated user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the folders
+      # @example Print the names of the bookmark folders
+      #   client.current_user!.bookmark_folders.each { |folder| puts folder.name }
+      def bookmark_folders(**params)
+        cursor(BookmarkFolder, "users/#{id}/bookmarks/folders", max_results: MAX_RESULTS, **params)
+      end
+
+      # The lists owned by this user
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the owned lists
+      # @example Print the owned lists
+      #   user.owned_lists.each { |list| puts list.name }
+      def owned_lists(**params)
+        cursor(List, "users/#{id}/owned_lists", max_results: MAX_RESULTS, **params)
+      end
+
+      # The lists this user is a member of
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the list memberships
+      # @example Print the list memberships
+      #   user.list_memberships.each { |list| puts list.name }
+      def list_memberships(**params)
+        cursor(List, "users/#{id}/list_memberships", max_results: MAX_RESULTS, total: :listed_count, **params)
+      end
+
+      # The lists this user follows
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the followed lists
+      # @example Print the followed lists
+      #   user.followed_lists.each { |list| puts list.name }
+      def followed_lists(**params)
+        cursor(List, "users/#{id}/followed_lists", max_results: MAX_RESULTS, **params)
+      end
+
+      # The lists this user has pinned
+      #
+      # The API returns them in one response, without pages.
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the pinned lists
+      # @example Print the pinned lists
+      #   client.current_user!.pinned_lists.each { |list| puts list.name }
+      def pinned_lists(**params)
+        cursor(List, "users/#{id}/pinned_lists", max_results: nil, **params)
+      end
+
+      alias_method :tweets, :posts
+      alias_method :liked_tweets, :liked_posts
+    end
+    private_constant :UserCollections
+  end
+end

data/lib/x/resources/user_finders.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "batch_finders"
+require_relative "utils"
+
+module X
+  module Resources
+    # Class methods that look users up by identifier or username, and the authenticated user, extended into User
+    #
+    # Internal to x-resources: the methods it gives User, such as X::User.find_by_username, are public API, but the module
+    # is only how they are shared, and which classes extend or include it can change within 1.x.
+    #
+    # @api semipublic
+    module UserFinders
+      include BatchFinders
+
+      # Look up a user by identifier or username
+      #
+      # An Integer or a user is looked up by identifier, and a String by username, with or without a leading at sign.
+      #
+      # @api public
+      # @param id_or_username [Integer, User, String] an identifier or a user, or a username
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User, nil] the user or nil if the user was not found, whether the API answers 200 with no data or a 404
+      #   that reports the user as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @raise [ArgumentError] if the value is neither an identifier nor a username
+      # @yieldparam problem [Problem] each problem the API reported, such as a user that was not found
+      # @example Look up a user by username
+      #   X::User.find("sferik", client: client)
+      def find(id_or_username, client:, **params, &)
+        return super if Utils.id?(id_or_username)
+
+        find_by_username(_ = id_or_username, client:, **params, &)
+      end
+
+      # Look up a user by identifier or username, which must exist
+      #
+      # An Integer or a user is looked up by identifier, and a String by username, as find looks them up, so the error
+      # it raises names a username as find_by_username! names one, with the at sign of a handle.
+      #
+      # @api public
+      # @param id_or_username [Integer, User, String] an identifier or a user, or a username
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User] the user
+      # @raise [ArgumentError] if the value is neither an identifier nor a username
+      # @raise [MissingResource] if the user was not found, whether the API answers 200 with no data or a 404 that
+      #   reports the user as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @example Look up a user by username
+      #   X::User.find!("sferik", client: client)
+      def find!(id_or_username, client:, **params)
+        return super if Utils.id?(id_or_username)
+
+        find_by_username!(_ = id_or_username, client:, **params)
+      end
+
+      # Look up many users by identifier or username, in parallel batches
+      #
+      # Integers and users are looked up by identifier, and Strings by username. The users come back in the
+      # order they were asked for, one for each value that was found, so a user asked for twice, by identifier or by
+      # username, comes back twice, without the ones that were not found. Every username is checked before any
+      # request, so one that is not a username raises before the identifiers are looked up, and billed.
+      #
+      # @api public
+      # @param ids_or_usernames [Array<Integer, User, String>] identifiers or users, or usernames
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batches looked up at once, which must be at least one; the
+      #   identifiers and the usernames are looked up one kind after the other, each kind that many batches at a time
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Array<User>] the users that were found, one for each value that names one, frozen
+      # @raise [ArgumentError] if a String is not a username, or if the concurrency is less than one, before any request
+      # @yieldparam problem [Problem] each problem the API reported, such as a user that was not found
+      # @example Look up many users by username
+      #   X::User.find_all(["sferik", "gem"], client: client)
+      def find_all(ids_or_usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params, &)
+        ids, usernames = ids_or_usernames.partition { |value| Utils.id?(value) }
+        usernames.each { |username| Utils.username!(username) }
+        found = super(ids, client:, concurrency:, **params) #: Array[User]
+        in_order(found + find_all_by_username(_ = usernames, client:, concurrency:, **params, &), ids_or_usernames)
+      end
+
+      # 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 would take them for usernames. The users come back in
+      # the order they were asked for, one for each identifier that was found, as find_all returns them.
+      #
+      # @api public
+      # @param ids [Array<String, Integer, User>] the identifiers, or users
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Array<User>] the users that were found, one for each identifier that names one, frozen
+      # @raise [ArgumentError] if a value is not an identifier, or if the concurrency is less than one
+      # @yieldparam problem [Problem] each problem the API reported, such as an identifier that was not found
+      # @example Look up many users by identifier, read as Strings
+      #   X::User.find_all_by_id(ENV.fetch("USER_IDS").split(","), client: client)
+      def find_all_by_id(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params, &)
+        ids = ids.map { |id| Utils.id_of(id, self) }
+        in_order_of(lookup_in_batches(endpoint!, batch_key, ids, client:, concurrency:, **params, &), ids) #: Array[User]
+      end
+
+      # 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 would take it for a username.
+      #
+      # @api public
+      # @param id [String, Integer, User] the identifier, or a user
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User, nil] the user or nil if the user was not found, whether the API answers 200 with no data or a 404
+      #   that reports the user as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @raise [ArgumentError] if the value is not an identifier
+      # @yieldparam problem [Problem] each problem the API reported, such as a user that was not found
+      # @example Look up a user by an identifier read as a String
+      #   X::User.find_by_id(ENV.fetch("USER_ID"), client: client)
+      def find_by_id(id, client:, **params, &)
+        locate("#{endpoint!}/#{Utils.id_of(id, self)}", client:, **params, &) #: User?
+      end
+
+      # Look up a user by identifier, which must exist
+      #
+      # @api public
+      # @param id [String, Integer, User] the identifier, or a user
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User] the user
+      # @raise [ArgumentError] if the value is not an identifier
+      # @raise [MissingResource] if the user was not found, whether the API answers 200 with no data or a 404 that
+      #   reports the user as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @example Look up a user by an identifier read as a String
+      #   X::User.find_by_id!("7505382", client: client)
+      def find_by_id!(id, client:, **params)
+        name = Utils.id_of(id, self)
+        locate!("#{endpoint!}/#{name}", name, client:, **params) #: User
+      end
+
+      # Look up many users by username, in parallel batches
+      #
+      # The users come back in the order they were asked for, one for each username that was found, whatever its
+      # case, as find_all returns them, and each username is asked for once, however often, and in whatever case, it
+      # is given.
+      #
+      # @api public
+      # @param usernames [Array<String>] the usernames, with or without leading at signs
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Array<User>] the users that were found, one for each username that names one, frozen
+      # @raise [ArgumentError] if a value is not a username, or if the concurrency is less than one
+      # @yieldparam problem [Problem] each problem the API reported, such as a username that was not found
+      # @example Look up many users by username
+      #   X::User.find_all_by_username(["sferik", "gem"], client: client)
+      def find_all_by_username(usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params, &)
+        usernames = usernames.map { |username| normalize(Utils.username!(username)) }
+        found = lookup_in_batches("users/by", :usernames, usernames, client:, concurrency:, **params, &) #: Array[User]
+        in_order(found, usernames)
+      end
+
+      # 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
+      # looks up any String, so code that reads a value from elsewhere says which it means, as find_by_id does.
+      #
+      # @api public
+      # @param username [String] the username, with or without a leading at sign
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User, nil] the user or nil if the user was not found, whether the API answers 200 with no data or a 404
+      #   that reports the user as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @raise [ArgumentError] if the value is not a username
+      # @yieldparam problem [Problem] each problem the API reported, such as a user that was not found
+      # @example Look up a user by username
+      #   X::User.find_by_username("sferik", client: client)
+      def find_by_username(username, client:, **params, &)
+        locate("users/by/username/#{Utils.username!(username)}", client:, **params, &) #: User?
+      end
+
+      # Look up a user by username, which must exist
+      #
+      # @api public
+      # @param username [String] the username, with or without a leading at sign
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User] the user
+      # @raise [ArgumentError] if the value is not a username
+      # @raise [MissingResource] if the user was not found, whether the API answers 200 with no data or a 404 that
+      #   reports the user as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @example Look up a user by username
+      #   X::User.find_by_username!("sferik", client: client)
+      def find_by_username!(username, client:, **params)
+        locate!("users/by/username/#{Utils.username!(username)}", "@#{Utils.username(username)}", client:, **params) #: User
+      end
+
+      # Look up the authenticated user
+      #
+      # Its path names no user, so a 404 to it is no user that is missing, and raises X::NotFound as any request does.
+      #
+      # @api public
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User, nil] the authenticated user
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Look up the authenticated user
+      #   X::User.current(client: client)
+      def current(client:, **params, &)
+        lookup("users/me", client:, **params, &) #: User?
+      end
+
+      # Look up the authenticated user, who must be found
+      #
+      # @api public
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [User] the authenticated user
+      # @raise [MissingResource] if the API returns no user
+      # @example Look up the authenticated user
+      #   X::User.current!(client: client)
+      def current!(client:, **params)
+        problems = [] #: Array[Problem]
+        current(client:, **params) { |problem| problems << problem } || raise(MissingResource.new("users/me returned no user", problems:))
+      end
+
+      private
+
+      # Order users as they were asked for, one for each value that names one
+      # @api private
+      # @param users [Array<User>] the users found
+      # @param ids_or_usernames [Array<Integer, User, String>] the identifiers, users, and usernames asked for
+      # @return [Array<User>] the user each value names, in the order of the values, frozen
+      # @raise [InvalidAttribute] if the response holds a username that is not a String
+      def in_order(users, ids_or_usernames)
+        by_key = users.to_h { |user| [key_of(user), user] }.merge(users.filter_map { |user| username_key(user) }.to_h)
+        ids_or_usernames.filter_map { |value| by_key[key_of(value)] }.freeze
+      end
+
+      # The key that matches a user found to a username it was asked for by
+      #
+      # It is nil for a user without one. A username is a String, so it is keyed as one, after an at sign, and never
+      # matches an identifier.
+      #
+      # @api private
+      # @param user [User] the user found
+      # @return [Array(String, User), nil] the key of the username and the user, or nil if the user holds no username
+      # @raise [InvalidAttribute] if the response holds a username that is not a String
+      def username_key(user)
+        username = user.username
+        ["@#{Utils.read("#{self}#username", username) { normalize(String.try_convert(username) || raise(ArgumentError)) }}", user] unless username.nil?
+      end
+
+      # The key that matches a user to the identifier or username it was asked for by
+      # @api private
+      # @param value [Integer, User, String] an identifier or user, or a username
+      # @return [String] the identifier, or the username in lowercase after an at sign
+      def key_of(value)
+        Utils.id?(value) ? Utils.id_of(value, self) : "@#{normalize(value)}"
+      end
+
+      # A username without an at sign, in lowercase, since case does not matter
+      # @api private
+      # @param username [String] the username, with or without a leading at sign
+      # @return [String] the normalized username
+      def normalize(username) = Utils.username(username).downcase
+    end
+    private_constant :UserFinders
+  end
+end