x-resources 1.0.0

data/lib/x/resources/list.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "cursor"
+require_relative "finders"
+require_relative "page_limit"
+require_relative "resource"
+
+module X
+  module Resources
+    # A curated list of users
+    # @api public
+    class ::X::List < Resource
+      extend Finders
+
+      # The mixins of the class by their full names, which YARD needs to resolve them in a class opened under X
+      #
+      # @!parse
+      #   extend X::Resources::Finders
+
+      # Every public list field
+      #
+      # 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.
+      FIELDS = %w[created_at description follower_count id member_count name private].freeze
+      # Every expansion available on list endpoints
+      #
+      # 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.
+      EXPANSIONS = %w[owner_id].freeze
+      # Maximum number of users or posts per page
+      # @api private
+      MAX_RESULTS = 100
+      private_constant :MAX_RESULTS
+
+      class << self
+        # The API endpoint used to look up lists by identifier
+        #
+        # @api private
+        # @return [String] the endpoint
+        # @example Get the endpoint
+        #   X::List.__send__(:endpoint) # => "lists"
+        def endpoint
+          "lists"
+        end
+
+        # The query parameter that selects list fields
+        #
+        # @api private
+        # @return [String] the fields parameter
+        # @example Get the fields parameter
+        #   X::List.__send__(:fields_key) # => "list.fields"
+        def fields_key = "list.fields"
+
+        private :endpoint, :fields_key
+
+        # The default query parameters requesting every list field and expansion
+        #
+        # @api public
+        # @return [Hash{String => Array<String>}] the default query parameters
+        # @example Get the default parameters
+        #   X::List.default_params["list.fields"]
+        def default_params
+          {"list.fields" => FIELDS, "user.fields" => User::FIELDS, "expansions" => EXPANSIONS}
+        end
+
+        # Create a list owned by the authenticated user
+        #
+        # @api public
+        # @param name [String] the name of the list
+        # @param client [Object] the client used to make the request
+        # @param params [Hash] additional request body fields: description and private
+        # @return [List] the created list, holding only its identifier and name
+        # @raise [MissingResource] if the API answers without the list
+        # @example Create a private list
+        #   X::List.create("Rubyists", client: client, description: "People who write Ruby", private: true)
+        def create(name, client:, **params)
+          body = client.post("lists", {name:, **params}, **Utils::JSON_CLASSES)
+          created_from_response(body, "POST lists", client:)
+        end
+
+        # Update the name, description, or privacy of a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @param client [Object] the client used to make the request
+        # @param params [Hash] the request body fields to change: name, description, and private
+        # @return [Boolean] true if the list was updated
+        # @raise [ArgumentError] if no field is given to change, before any request
+        # @example Rename a list and make it private
+        #   X::List.update("1234567890", client: client, name: "Rubyists", private: true)
+        def update(list, client:, **params)
+          raise ArgumentError, "a list update needs a field to change, such as name, description, or private" if params.empty?
+
+          body = client.put("lists/#{Utils.id_of(list, self)}", params, **Utils::JSON_CLASSES)
+          Utils.written(body, "updated").eql?(true)
+        end
+
+        # Delete a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @param client [Object] the client used to make the request
+        # @return [Boolean] true if the list was deleted
+        # @example Delete a list
+        #   X::List.delete("1234567890", client: client)
+        def delete(list, client:)
+          body = client.delete("lists/#{Utils.id_of(list, self)}", **Utils::JSON_CLASSES)
+          Utils.written(body, "deleted").eql?(true)
+        end
+      end
+
+      # @!attribute [r] name
+      #   The name
+      #   @api public
+      #   @return [String, nil] the name
+      #   @example Get the name
+      #     list.name
+      attribute :name
+
+      # @!attribute [r] description
+      #   The description
+      #   @api public
+      #   @return [String, nil] the description
+      #   @example Get the description
+      #     list.description
+      attribute :description
+
+      # @!attribute [r] created_at
+      #   The time when the list was created
+      #   @api public
+      #   @return [Time, nil] the creation time
+      #   @example Get the creation time
+      #     list.created_at
+      attribute :created_at, :time
+
+      # @!attribute [r] follower_count
+      #   The number of followers
+      #   @api public
+      #   @return [Integer, nil] the follower count
+      #   @example Get the follower count
+      #     list.follower_count
+      attribute :follower_count, :integer
+
+      # @!attribute [r] member_count
+      #   The number of members
+      #   @api public
+      #   @return [Integer, nil] the member count
+      #   @example Get the member count
+      #     list.member_count
+      attribute :member_count, :integer
+
+      # @!attribute [r] owner_id
+      #   The identifier of the owner
+      #   @api public
+      #   @return [Integer, nil] the owner identifier
+      #   @example Get the owner identifier
+      #     list.owner_id
+      attribute :owner_id, :integer
+
+      # @!attribute [r] private
+      #   Whether the list is private
+      #   @api public
+      #   @return [Boolean, nil] true if the list is private
+      #   @example Check whether a list is private
+      #     list.private?
+      attribute :private, :boolean
+
+      # @!method private?
+      #   Check whether the list is private
+      #   @api public
+      #   @return [Boolean] true if the list is private
+      #   @example Check whether the list is private
+      #     list.private?
+
+      # @!method owner
+      #   The owner, resolved from the includes or as a stub holding only its identifier
+      #   @api public
+      #   @return [User, nil] the owner
+      #   @example Get the owner's username
+      #     list.owner.username
+      reference :owner, :User, key: %w[owner_id]
+
+      # The members of this list
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the members
+      # @example Print every member
+      #   list.members.each { |user| puts user.username }
+      def members(**params)
+        cursor(User, "lists/#{id}/members", max_results: MAX_RESULTS, total: :member_count, **params)
+      end
+
+      # The followers of this list
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the followers
+      # @example Print every follower
+      #   list.followers.each { |user| puts user.username }
+      def followers(**params)
+        cursor(User, "lists/#{id}/followers", max_results: MAX_RESULTS, total: :follower_count, **params)
+      end
+
+      # The posts by members of this list
+      #
+      # @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
+      #   list.posts.first(10).each { |post| puts post.text }
+      def posts(**params)
+        cursor(Post, "lists/#{id}/tweets", max_results: MAX_RESULTS, **params)
+      end
+
+      # Check whether a user is a member of this list, scanning until one matches
+      #
+      # The API has no lookup for a membership, so this scans either the members of the list or the lists
+      # the user is on. A private list scans its members, since a user's memberships leave private lists
+      # out. A public list scans the lists the user is on when there are fewer of them than members, as its
+      # member_count and the user's listed_count tell, looking up the list or the user first when either is
+      # a stub. The API bills every resource a scan returns, so max_pages limits the pages it reads, raising
+      # PageLimitReached rather than read past them.
+      #
+      # @api public
+      # @param user [User, String, Integer] the user or their identifier
+      # @param max_pages [Integer, nil] the most pages of members or memberships to read, or nil for no limit
+      # @return [Boolean] true if the user is a member
+      # @raise [ArgumentError] if max_pages is neither an Integer of at least 1 nor nil, before a request
+      # @raise [PageLimitReached] if the scan reads max_pages pages without the user, and the API names another
+      # @example Check whether a user is on a list
+      #   list.member?(user)
+      # @example Read no more than ten pages to tell
+      #   list.member?(user, max_pages: 10)
+      def member?(user, max_pages: nil)
+        member, max_pages = User.from_id(user), PageLimit.check!(max_pages)
+        return PageLimit.scan(members.stubs, member, what: "List#member?", max_pages:) unless fewer_memberships?(user)
+
+        PageLimit.scan(User.from_id(member, client: client!).list_memberships.stubs, self, what: "List#member?", max_pages:)
+      end
+
+      # The permalink of the list
+      #
+      # @api public
+      # @return [String] the x.com address of the list
+      # @example Get the permalink
+      #   list.permalink # => "https://x.com/i/lists/1234567890"
+      def permalink = "https://x.com/i/lists/#{id}"
+
+      # The permalink of the list as a URI
+      #
+      # @api public
+      # @return [URI::Generic] the x.com address of the list
+      # @example Get the address as a URI
+      #   list.uri # => #<URI::HTTPS https://x.com/i/lists/1234567890>
+      def uri = URI(permalink)
+
+      # Add a member to this list as the authenticated user
+      #
+      # @api public
+      # @param user [User, String, Integer] the user or their identifier
+      # @return [Boolean] true if the user is now a member
+      # @example Add a member
+      #   list.add_member(user)
+      def add_member(user)
+        body = client!.post("lists/#{id}/members", {user_id: Utils.id_of(user, User)}, **Utils::JSON_CLASSES)
+        Utils.written(body, "is_member").eql?(true)
+      end
+
+      # Remove a member from this list as the authenticated user
+      #
+      # @api public
+      # @param user [User, String, Integer] the user or their identifier
+      # @return [Boolean] true if the user is no longer a member
+      # @example Remove a member
+      #   list.remove_member(user)
+      def remove_member(user)
+        body = client!.delete("lists/#{id}/members/#{Utils.id_of(user, User)}", **Utils::JSON_CLASSES)
+        Utils.written(body, "is_member").eql?(false)
+      end
+
+      # Update the name, description, or privacy of this list as the authenticated user
+      #
+      # The list keeps the attributes it was built with, so refresh it to read the new ones.
+      #
+      # @api public
+      # @param params [Hash] the request body fields to change: name, description, and private
+      # @return [Boolean] true if the list was updated
+      # @raise [ArgumentError] if no field is given to change, before any request
+      # @example Change the description of a list
+      #   list.update(description: "People who write Ruby")
+      def update(**params)
+        self.class.update(self, client: client!, **params)
+      end
+
+      # Delete this list as the authenticated user
+      #
+      # @api public
+      # @return [Boolean] true if the list was deleted
+      # @example Delete a list
+      #   list.delete
+      def delete
+        self.class.delete(self, client: client!)
+      end
+
+      alias_method :tweets, :posts
+
+      private
+
+      # Check whether the user is on fewer lists than this public list has members
+      # @api private
+      # @param user [User, String, Integer] the user or their identifier
+      # @return [Boolean] true if the lists the user is on are fewer than the members of this public list
+      def fewer_memberships?(user)
+        list = hydrate
+        return false if list.nil? || list.private?
+
+        member_count = list.member_count
+        return false if member_count.nil?
+
+        listed_count = listed_count_of(user)
+        !listed_count.nil? && listed_count < member_count
+      end
+
+      # The number of lists a user is on, looking up a user that is not hydrated
+      # @api private
+      # @param user [User, String, Integer] the user or their identifier
+      # @return [Integer, nil] the listed count, or nil if the user was not found
+      def listed_count_of(user)
+        known = user if user.is_a?(User) && user.hydrated?
+        (known || User.find(User.from_id(user), client: client!))&.listed_count
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/communities.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../community"
+
+module X
+  module Resources
+    module Lookups
+      # Look up and search communities, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module Communities
+        # Look up a community by identifier
+        #
+        # @api public
+        # @param id [String, Integer, Community] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Community, nil] the community or nil if the community was not found
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a community
+        #   client.find_community(1234567890).name
+        def find_community(id, **params, &)
+          Community.find(id, client: self, **params, &)
+        end
+
+        # Look up a community by identifier, which must exist
+        #
+        # @api public
+        # @param id [String, Integer, Community] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Community] the community
+        # @raise [MissingResource] if the community was not found
+        # @example Look up a community
+        #   client.find_community!(1234567890).name
+        def find_community!(id, **params)
+          Community.find!(id, client: self, **params)
+        end
+
+        # Search communities
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the matching communities
+        # @example Print the communities matching a query
+        #   client.search_communities("ruby").each { |community| puts community.name }
+        def search_communities(query, **params)
+          Community.search(query, client: self, **params)
+        end
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/direct_messages.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../direct_message"
+
+module X
+  module Resources
+    module Lookups
+      # Look up direct messages, and the conversations they belong to, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module DirectMessages
+        # Look up a direct message event by identifier
+        #
+        # @api public
+        # @param id [String, Integer, DirectMessage] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [DirectMessage, nil] the event or nil if the event was not found
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a direct message
+        #   client.find_direct_message(1234567890).text
+        def find_direct_message(id, **params, &)
+          DirectMessage.find(id, client: self, **params, &)
+        end
+
+        # Look up a direct message event by identifier, which must exist
+        #
+        # @api public
+        # @param id [String, Integer, DirectMessage] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [DirectMessage] the event
+        # @raise [MissingResource] if the event was not found
+        # @example Look up a direct message
+        #   client.find_direct_message!(1234567890).text
+        def find_direct_message!(id, **params)
+          DirectMessage.find!(id, client: self, **params)
+        end
+
+        # The most recent direct message events across every conversation
+        #
+        # @api public
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the events
+        # @example Print the most recent direct messages
+        #   client.direct_messages.first(10).each { |message| puts message.text }
+        def direct_messages(**params)
+          DirectMessage.all(client: self, **params)
+        end
+
+        # The direct message events in the one-to-one conversation with a user
+        #
+        # @api public
+        # @param user [User, String, Integer] the other participant or their identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the events
+        # @example Print the conversation with a user
+        #   client.direct_messages_with(user).each { |message| puts message.text }
+        def direct_messages_with(user, **params)
+          DirectMessage.with(user, client: self, **params)
+        end
+
+        # The direct message events of a conversation, one-to-one or group
+        #
+        # @api public
+        # @param conversation [DirectMessage, String, Integer] a message of the conversation, or the conversation's identifier
+        # @param params [Hash] query parameters merged over the default parameters, such as event_types
+        # @return [Cursor] a cursor over the events
+        # @raise [ArgumentError] if the conversation identifier is not one
+        # @example Print the conversation a message belongs to
+        #   client.direct_messages_in(message).each { |event| puts event.text }
+        def direct_messages_in(conversation, **params)
+          DirectMessage.in(conversation, client: self, **params)
+        end
+
+        alias_method :find_dm, :find_direct_message
+        alias_method :find_dm!, :find_direct_message!
+        alias_method :dms, :direct_messages
+        alias_method :dms_with, :direct_messages_with
+        alias_method :dms_in, :direct_messages_in
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/lists.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../list"
+
+module X
+  module Resources
+    module Lookups
+      # Look up lists, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module Lists
+        # Look up a list by identifier
+        #
+        # @api public
+        # @param id [String, Integer, List] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [List, nil] the list or nil if the list was not found
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a list
+        #   client.find_list(1234567890).name
+        def find_list(id, **params, &)
+          List.find(id, client: self, **params, &)
+        end
+
+        # Look up a list by identifier, which must exist
+        #
+        # @api public
+        # @param id [String, Integer, List] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [List] the list
+        # @raise [MissingResource] if the list was not found
+        # @example Look up a list
+        #   client.find_list!(1234567890).name
+        def find_list!(id, **params)
+          List.find!(id, client: self, **params)
+        end
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/media.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../batch_finders"
+require_relative "../media"
+
+module X
+  module Resources
+    module Lookups
+      # Look up media by media key
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module 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.
+        #
+        # @api public
+        # @param media_key [String, X::Media, #media_key] the media key, such as 3_1880028106020515840, media, or what
+        #   an upload returned
+        # @param 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
+        # @return [X::Media, nil] the media, or nil if it was not found
+        # @yieldparam problem [Problem] each problem the API reported
+        # @example Look up media by media key
+        #   client.find_media("3_1880028106020515840")
+        # @example Look up media that was uploaded
+        #   client.find_media(uploaded)
+        def find_media(media_key, **params, &)
+          X::Media.find(media_key, client: self, **params, &)
+        end
+
+        # Look up media by media key, in parallel batches
+        #
+        # @api public
+        # @param media [Array<String, X::Media, #media_key>] the media keys, or the media, or what the uploads
+        #   returned, whose keys are taken
+        # @param concurrency [Integer] 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
+        # @param 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
+        # @return [Array<X::Media>] the media that was found
+        # @raise [ArgumentError] if the concurrency is less than one
+        # @yieldparam problem [Problem] each problem the API reported, such as a media key that was not found
+        # @example Look up the media of a post
+        #   client.find_all_media(post.media)
+        # @example Look up media by media key
+        #   client.find_all_media(%w[3_1880028106020515840 3_1880028106020515841])
+        def find_all_media(media, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          X::Media.find_all(media, client: self, concurrency:, **params, &)
+        end
+
+        # Look up media by media key, raising if it is not found
+        #
+        # @api public
+        # @param media_key [String, X::Media, #media_key] the media key, media, or what an upload returned
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [X::Media] the media
+        # @raise [MissingResource] if the media was not found
+        # @example Look up media that must exist
+        #   client.find_media!("3_1880028106020515840")
+        def find_media!(media_key, **params)
+          X::Media.find!(media_key, client: self, **params)
+        end
+      end
+    end
+  end
+end