x-resources 1.0.0

data/lib/x/resources/published_count.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module X
+  module Resources
+    # The number the API publishes for a collection of a resource, such as the followers_count of a user, which a
+    # cursor over the collection reads, included into Resource
+    # @api private
+    module PublishedCount
+      private
+
+      # A block reading the attribute holding the number the API publishes
+      #
+      # A resource without the attribute, such as a stub, is hydrated to read it, which costs one lookup rather than
+      # paging through the collection. Given fresh: true, as by a cursor that was refreshed, the block looks the
+      # resource up again, as refresh does, to read the number the API publishes now.
+      #
+      # @api private
+      # @param total [Symbol, nil] the attribute name, or nil if the API publishes no number
+      # @return [Proc, nil] the block, or nil if the API publishes no number
+      def counter(total)
+        return if total.nil?
+
+        lambda do |fresh: false|
+          # @type var fresh: bool
+          fresh ? refresh&.public_send(total) : public_send(total) || hydrate&.public_send(total)
+        end
+      end
+    end
+    private_constant :PublishedCount
+  end
+end

data/lib/x/resources/references.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module X
+  module Resources
+    # Resolves the posts a post refers to through its referenced_posts attribute
+    #
+    # Internal to x-resources: the methods it gives a post, such as replied_to, 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 References
+      # Referenced post type for replies
+      # @api private
+      REPLIED_TO = "replied_to"
+      # Referenced post type for quotes
+      # @api private
+      QUOTED = "quoted"
+      # Referenced post type for reposts, as the API labels them
+      # @api private
+      REPOSTED = "reposted"
+      # Referenced post type for reposts, as the API documentation labels them
+      # @api private
+      RETWEETED = "retweeted"
+      private_constant :REPLIED_TO, :QUOTED, :REPOSTED, :RETWEETED
+
+      # The referenced posts, resolved from the includes or built as stubs
+      #
+      # @api public
+      # @return [Array<Post>] the referenced posts
+      # @raise [InvalidAttribute] if the response holds a referenced post that is not an object
+      # @example Get the referenced posts
+      #   post.references
+      def references
+        referenced_posts.filter_map do |reference|
+          resolve(Post, reference["id"]) #: Post?
+        end.freeze
+      end
+
+      # The post this post replies to
+      #
+      # @api public
+      # @return [Post, nil] the replied-to post
+      # @raise [InvalidAttribute] if the response holds a referenced post that is not an object
+      # @example Get the replied-to post
+      #   post.replied_to
+      def replied_to
+        reference(REPLIED_TO)
+      end
+
+      # The post this post quotes
+      #
+      # @api public
+      # @return [Post, nil] the quoted post
+      # @raise [InvalidAttribute] if the response holds a referenced post that is not an object
+      # @example Get the quoted post
+      #   post.quoted
+      def quoted
+        reference(QUOTED)
+      end
+
+      # The post this post reposts
+      #
+      # @api public
+      # @return [Post, nil] the reposted post
+      # @raise [InvalidAttribute] if the response holds a referenced post that is not an object
+      # @example Get the reposted post
+      #   post.reposted
+      def reposted
+        reference(REPOSTED, RETWEETED)
+      end
+
+      # Check whether this post is a reply
+      #
+      # @api public
+      # @return [Boolean] true if the post replies to another post
+      # @example Check whether a post is a reply
+      #   post.reply?
+      def reply?
+        !replied_to.nil?
+      end
+
+      # Check whether this post is a quote
+      #
+      # @api public
+      # @return [Boolean] true if the post quotes another post
+      # @example Check whether a post is a quote
+      #   post.quote?
+      def quote?
+        !quoted.nil?
+      end
+
+      # Check whether this post is a repost
+      #
+      # @api public
+      # @return [Boolean] true if the post reposts another post
+      # @example Check whether a post is a repost
+      #   post.repost?
+      def repost?
+        !reposted.nil?
+      end
+
+      alias_method :retweeted, :reposted
+      alias_method :retweet?, :repost?
+
+      private
+
+      # Resolve the first referenced post of any of some types
+      # @api private
+      # @param types [Array<String>] the referenced post types
+      # @return [Post, nil] the referenced post or nil if there is none of those types
+      # @raise [InvalidAttribute] if the response holds a referenced post that is not an object
+      def reference(*types)
+        found = referenced_posts.find { |element| types.include?(element["type"]) }
+        return if found.nil?
+
+        resolve(Post, found["id"]) #: Post?
+      end
+    end
+    private_constant :References
+  end
+end

data/lib/x/resources/relation_writes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "user"
+require_relative "utils"
+
+module X
+  module Resources
+    # Relating users, posts, and lists to the authenticated user, and removing the relations
+    #
+    # A relation, such as following a user or liking a post, is written as the authenticated user alone, so the methods
+    # of a client that write one, such as follow and like, write it here, for the user the client authenticates as,
+    # and no user does.
+    #
+    # @api private
+    module RelationWrites
+      extend self
+
+      # Relate a resource to the authenticated user and report the resulting state
+      #
+      # @api private
+      # @param client [Object] the client used to make the request
+      # @param user [Integer, String] the identifier of the authenticated user
+      # @param relation [String] the relation endpoint, such as following, likes, or pinned_lists
+      # @param field [Hash{String => String}] the request body, the identifier of the related resource under its field
+      # @param states [Array<String>] the response fields reporting the state, any of which is true once it exists
+      # @return [Boolean] true if the relation now exists
+      # @raise [ArgumentError] if the identifier of the authenticated user is not a number, before a request
+      # @example Like a post as the authenticated user
+      #   X::Resources::RelationWrites.relate(client, client.current_user_id, "likes", {"tweet_id" => "1234567890"}, "liked")
+      def relate(client, user, relation, field, *states)
+        body = client.post("users/#{Utils.id_of(user, User)}/#{relation}", field, **Utils::JSON_CLASSES)
+        states.any? { |state| Utils.written(body, state).eql?(true) }
+      end
+
+      # Remove a relation from the authenticated user and report the resulting state
+      #
+      # @api private
+      # @param client [Object] the client used to make the request
+      # @param user [Integer, String] the identifier of the authenticated user
+      # @param relation [String] the relation endpoint, such as following, likes, or pinned_lists
+      # @param target [String] the identifier of the related resource
+      # @param state [String] the response field reporting the state
+      # @return [Boolean] true if the relation no longer exists
+      # @raise [ArgumentError] if the identifier of the authenticated user is not a number, before a request
+      # @example Unlike a post as the authenticated user
+      #   X::Resources::RelationWrites.unrelate(client, client.current_user_id, "likes", "1234567890", "liked")
+      def unrelate(client, user, relation, target, state)
+        body = client.delete("users/#{Utils.id_of(user, User)}/#{relation}/#{target}", **Utils::JSON_CLASSES)
+        Utils.written(body, state).eql?(false)
+      end
+    end
+    private_constant :RelationWrites
+  end
+end

data/lib/x/resources/relationships.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "page_limit"
+require_relative "utils"
+
+module X
+  module Resources
+    # The relationships of a user with other users, read as the authenticated user sees them
+    #
+    # It reads them and changes none: a relationship changes as the authenticated user alone, so the client changes it,
+    # as in client.follow(user), rather than a user, which may be anyone.
+    #
+    # Internal to x-resources: the methods it gives a user, such as follows?, 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 Relationships
+      # Check whether this user follows a user
+      #
+      # When either user is the authenticated user, one lookup of the other's connection_status answers.
+      # Otherwise the users this user follows are scanned until one matches, up to 1,000 a page, and the
+      # API bills every user returned, so checking an account that follows thousands can cost dollars, and max_pages
+      # limits the pages the scan reads, raising PageLimitReached rather than read past them. A client that
+      # authenticates as the app alone has no authenticated user, which the API refuses to look up, so it scans.
+      # Any other failure to look the authenticated user up raises, rather than scan every user this one follows.
+      #
+      # @api public
+      # @param user [User, String, Integer] the user or their identifier
+      # @param max_pages [Integer, nil] the most pages of followed users to scan, or nil for no limit
+      # @return [Boolean] true if this user follows the user
+      # @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 the authenticated user follows someone, in one lookup
+      #   client.current_user!.follows?(other)
+      # @example Scan no more than five pages of the users another user follows
+      #   X::User.find("jack", client: client).follows?(other, max_pages: 5)
+      def follows?(user, max_pages: nil)
+        target, max_pages = User.from_id(user), PageLimit.check!(max_pages)
+        case authenticated_user_id
+        when id then connection_status_of(target).include?("following")
+        when target.id then connection_status_of(self).include?("followed_by")
+        else PageLimit.scan(following.stubs, target, what: "User#follows?", max_pages:)
+        end
+      end
+
+      private
+
+      # The identifier of the authenticated user, when the client knows it
+      #
+      # A client that authenticates as the app alone has no authenticated user, and asks the API for one in vain,
+      # so the refusal of the credentials of the client leaves the identifier unknown rather than end the check. Any
+      # other error, such as a rate limit, a failure of the API, or of the network, ends it, since a scan in its place
+      # would page through every user this one follows, which the API bills.
+      #
+      # @api private
+      # @return [Integer, nil] the identifier, or nil if the client has no current_user_id or cannot read one
+      # @raise [X::Error] if the API fails to answer for another reason than the credentials of the client
+      def authenticated_user_id
+        current = client! #: untyped
+        current.current_user_id if current.respond_to?(:current_user_id)
+      rescue X::Forbidden, X::Unauthorized
+        nil
+      end
+
+      # How the authenticated user is connected to a user, in one lookup
+      # @api private
+      # @param user [User, String, Integer] the user or their identifier
+      # @return [Array<String>] the connection statuses, empty if the user was not found
+      def connection_status_of(user)
+        found = User.find(user, client: client!, "user.fields": "connection_status", "post.fields": nil, expansions: nil)
+        Array(found&.connection_status)
+      end
+    end
+    private_constant :Relationships
+  end
+end