x-resources 1.0.0

data/lib/x/resources/actions/engagement.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "../post"
+require_relative "../relation_writes"
+require_relative "../utils"
+
+module X
+  module Resources
+    module Actions
+      # Like, repost, and bookmark posts as the authenticated user
+      #
+      # 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 Engagement
+        # Like a post as the authenticated user
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the authenticated user now likes the post
+        # @example Like a post
+        #   client.like("1234567890")
+        def like(post)
+          RelationWrites.relate(self, current_user_id, "likes", {"tweet_id" => Utils.id_of(post, Post)}, "liked")
+        end
+
+        # Unlike a post as the authenticated user
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the authenticated user no longer likes the post
+        # @example Unlike a post
+        #   client.unlike("1234567890")
+        def unlike(post)
+          RelationWrites.unrelate(self, current_user_id, "likes", Utils.id_of(post, Post), "liked")
+        end
+
+        # Repost a post as the authenticated user
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the authenticated user has reposted the post
+        # @example Repost a post
+        #   client.repost("1234567890")
+        def repost(post)
+          RelationWrites.relate(self, current_user_id, "retweets", {"tweet_id" => Utils.id_of(post, Post)}, "retweeted")
+        end
+
+        # Undo a repost as the authenticated user
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the authenticated user no longer reposts the post
+        # @example Undo a repost
+        #   client.unrepost("1234567890")
+        def unrepost(post)
+          RelationWrites.unrelate(self, current_user_id, "retweets", Utils.id_of(post, Post), "retweeted")
+        end
+
+        # Bookmark a post as the authenticated user
+        #
+        # Bookmarking a post takes only OAuth 2.0 user context, which the object layer cannot route around, so a
+        # client that signs with OAuth 1.0a is refused.
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the authenticated user has bookmarked the post
+        # @example Bookmark a post
+        #   client.bookmark("1234567890")
+        def bookmark(post)
+          RelationWrites.relate(self, current_user_id, "bookmarks", {"tweet_id" => Utils.id_of(post, Post)}, "bookmarked")
+        end
+
+        # Remove a bookmark as the authenticated user
+        #
+        # Removing a bookmark takes only OAuth 2.0 user context, which the object layer cannot route around, so a
+        # client that signs with OAuth 1.0a is refused.
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the authenticated user no longer has the post bookmarked
+        # @example Remove a bookmark
+        #   client.unbookmark("1234567890")
+        def unbookmark(post)
+          RelationWrites.unrelate(self, current_user_id, "bookmarks", Utils.id_of(post, Post), "bookmarked")
+        end
+
+        alias_method :retweet, :repost
+        alias_method :unretweet, :unrepost
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "../list"
+require_relative "../relation_writes"
+require_relative "../user"
+require_relative "../utils"
+
+module X
+  module Resources
+    module Actions
+      # Create, update, delete, follow, and pin lists as the authenticated user
+      #
+      # 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
+        # Create a list owned by the authenticated user
+        #
+        # @api public
+        # @param name [String] the name of the list
+        # @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
+        #   client.create_list("Rubyists", private: true)
+        def create_list(name, **params)
+          List.create(name, client: self, **params)
+        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 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 Make a list private
+        #   client.update_list("1234567890", private: true)
+        def update_list(list, **params)
+          List.update(list, client: self, **params)
+        end
+
+        # Delete a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @return [Boolean] true if the list was deleted
+        # @example Delete a list
+        #   client.delete_list("1234567890")
+        def delete_list(list)
+          List.delete(list, client: self)
+        end
+
+        # Add a member to a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the user is now a member
+        # @example Add a member to a list
+        #   client.add_list_member("1234567890", user)
+        def add_list_member(list, user)
+          List.from_id(list, client: self).add_member(user)
+        end
+
+        # Remove a member from a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @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 from a list
+        #   client.remove_list_member("1234567890", user)
+        def remove_list_member(list, user)
+          List.from_id(list, client: self).remove_member(user)
+        end
+
+        # Follow a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @return [Boolean] true if the authenticated user now follows the list
+        # @example Follow a list
+        #   client.follow_list("1234567890")
+        def follow_list(list)
+          RelationWrites.relate(self, current_user_id, "followed_lists", {"list_id" => Utils.id_of(list, List)}, "following")
+        end
+
+        # Unfollow a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @return [Boolean] true if the authenticated user no longer follows the list
+        # @example Unfollow a list
+        #   client.unfollow_list("1234567890")
+        def unfollow_list(list)
+          RelationWrites.unrelate(self, current_user_id, "followed_lists", Utils.id_of(list, List), "following")
+        end
+
+        # Pin a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @return [Boolean] true if the authenticated user has pinned the list
+        # @example Pin a list
+        #   client.pin_list("1234567890")
+        def pin_list(list)
+          RelationWrites.relate(self, current_user_id, "pinned_lists", {"list_id" => Utils.id_of(list, List)}, "pinned")
+        end
+
+        # Unpin a list as the authenticated user
+        #
+        # @api public
+        # @param list [List, String, Integer] the list or its identifier
+        # @return [Boolean] true if the authenticated user no longer has the list pinned
+        # @example Unpin a list
+        #   client.unpin_list("1234567890")
+        def unpin_list(list)
+          RelationWrites.unrelate(self, current_user_id, "pinned_lists", Utils.id_of(list, List), "pinned")
+        end
+      end
+    end
+  end
+end

data/lib/x/resources/actions/posts.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../post"
+
+module X
+  module Resources
+    module Actions
+      # Create and delete posts as the authenticated user
+      #
+      # 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 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.
+        #
+        # @api public
+        # @param text [String, nil] the text of the post, or nil for a post without text, such as one of media alone
+        # @param params [Hash] additional request body fields, such as reply_to, quote, media_ids, or poll
+        # @return [Post] the created post, holding only its identifier and text
+        # @raise [ArgumentError] if the post has neither text nor any other field
+        # @raise [MissingResource] if the API answers without the post
+        # @example Create a post
+        #   client.create_post("Hello, World!")
+        # @example Post an image without text
+        #   client.create_post(media_ids: [media])
+        # @example Reply to a post with an image
+        #   client.create_post("Hello!", reply_to: post, media_ids: [media["id"]])
+        # @example Quote a post
+        #   client.create_post("Worth reading", quote: post)
+        def create_post(text = nil, **params) # steep:ignore DifferentMethodParameterKind
+          Post.create(text, client: self, **params)
+        end
+
+        # Delete a post as the authenticated user
+        #
+        # @api public
+        # @param post [Post, String, Integer] the post or its identifier
+        # @return [Boolean] true if the post was deleted
+        # @example Delete a post
+        #   client.delete_post("1234567890")
+        def delete_post(post)
+          Post.delete(post, client: self)
+        end
+
+        # Hide a reply to a post of the authenticated user
+        #
+        # @api public
+        # @param post [Post, String, Integer] the reply or its identifier
+        # @return [Boolean] true if the reply is now hidden
+        # @example Hide a reply
+        #   client.hide_reply("1234567890")
+        def hide_reply(post)
+          Post.hide_reply(post, client: self)
+        end
+
+        # Show a reply to a post of the authenticated user after hiding it
+        #
+        # @api public
+        # @param post [Post, String, Integer] the reply or its identifier
+        # @return [Boolean] true if the reply is no longer hidden
+        # @example Show a hidden reply
+        #   client.unhide_reply("1234567890")
+        def unhide_reply(post)
+          Post.unhide_reply(post, client: self)
+        end
+
+        alias_method :create_tweet, :create_post
+        alias_method :delete_tweet, :delete_post
+      end
+    end
+  end
+end

data/lib/x/resources/actions/relationships.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../relation_writes"
+require_relative "../user"
+require_relative "../utils"
+
+module X
+  module Resources
+    module Actions
+      # Follow, block, and mute users as the authenticated user
+      #
+      # 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 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.
+        #
+        # @api public
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the authenticated user now follows the user, or, for a protected user, has requested
+        #   to follow them
+        # @example Follow a user
+        #   client.follow("7505382")
+        def follow(user)
+          RelationWrites.relate(self, current_user_id, "following", {"target_user_id" => Utils.id_of(user, User)}, "following", "pending_follow")
+        end
+
+        # Unfollow a user as the authenticated user
+        #
+        # @api public
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the authenticated user no longer follows the user
+        # @example Unfollow a user
+        #   client.unfollow("7505382")
+        def unfollow(user)
+          RelationWrites.unrelate(self, current_user_id, "following", Utils.id_of(user, User), "following")
+        end
+
+        # Block a user as the authenticated user
+        #
+        # @api public
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the authenticated user now blocks the user
+        # @example Block a user
+        #   client.block("7505382")
+        def block(user)
+          RelationWrites.relate(self, current_user_id, "blocking", {"target_user_id" => Utils.id_of(user, User)}, "blocking")
+        end
+
+        # Unblock a user as the authenticated user
+        #
+        # @api public
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the authenticated user no longer blocks the user
+        # @example Unblock a user
+        #   client.unblock("7505382")
+        def unblock(user)
+          RelationWrites.unrelate(self, current_user_id, "blocking", Utils.id_of(user, User), "blocking")
+        end
+
+        # Mute a user as the authenticated user
+        #
+        # @api public
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the authenticated user now mutes the user
+        # @example Mute a user
+        #   client.mute("7505382")
+        def mute(user)
+          RelationWrites.relate(self, current_user_id, "muting", {"target_user_id" => Utils.id_of(user, User)}, "muting")
+        end
+
+        # Unmute a user as the authenticated user
+        #
+        # @api public
+        # @param user [User, String, Integer] the user or their identifier
+        # @return [Boolean] true if the authenticated user no longer mutes the user
+        # @example Unmute a user
+        #   client.unmute("7505382")
+        def unmute(user)
+          RelationWrites.unrelate(self, current_user_id, "muting", Utils.id_of(user, User), "muting")
+        end
+      end
+    end
+  end
+end

data/lib/x/resources/actions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "actions/direct_messages"
+require_relative "actions/engagement"
+require_relative "actions/lists"
+require_relative "actions/posts"
+require_relative "actions/relationships"
+
+module X
+  module Resources
+    # Actions taken as the authenticated user, the modules of which X::Resources::API includes
+    #
+    # Internal to x-resources: a namespace of the modules API includes into a client, and not itself included, so that
+    # the modules it holds are not constants of the client, where the name of one, such as Media, would shadow a
+    # constant of the same name in a class that inherits from the client. Include API rather than any of them.
+    #
+    # @api private
+    module Actions
+    end
+    private_constant :Actions
+  end
+end

data/lib/x/resources/api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "actions"
+require_relative "lookups"
+
+module X
+  module Resources
+    # 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-resources alone, or with a client of your own,
+    # include it yourself: X::Client.include(X::Resources::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.
+    #
+    # @api public
+    module API
+      include Lookups::Users
+      include Lookups::Posts
+      include Lookups::Lists
+      include Lookups::Media
+      include Lookups::Spaces
+      include Lookups::Communities
+      include Lookups::DirectMessages
+      include Lookups::Trends
+      include Actions::Posts
+      include Actions::Lists
+      include Actions::DirectMessages
+      include Actions::Relationships
+      include Actions::Engagement
+    end
+  end
+end

data/lib/x/resources/attributes.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "shape"
+require_relative "utils"
+
+module X
+  module Resources
+    # Class-level macros for declaring resource attributes and references
+    # @api private
+    module Attributes
+      # The value of a list the response omitted, which reads as empty, as a list of references does, rather than nil
+      EMPTY_LIST = [] #: Array[untyped]
+      EMPTY_LIST.freeze
+      private_constant :EMPTY_LIST
+      # The values a flag is read from, which the API gives as true or false, and a response that omits it as nil
+      FLAGS = [true, false, nil].freeze
+      private_constant :FLAGS
+      # Converters keyed by attribute type
+      CONVERTERS = {
+        raw: ->(value) { value },
+        media_key: ->(value) { value },
+        conversation_id: ->(value) { Shape.conversation_id(value) },
+        boolean: ->(value) { FLAGS.include?(value) ? value : raise(ArgumentError, "#{value.inspect} is not true or false") },
+        time: ->(value) { Utils.time(value) },
+        integer: ->(value) { Shape.integer(value) },
+        integers: ->(value) { (Shape.list(value) || EMPTY_LIST).map { |id| Shape.integer(id) }.freeze },
+        list: ->(value) { Shape.list(value) || EMPTY_LIST },
+        object: ->(value) { Shape.object(value) },
+        objects: ->(value) { Shape.object_list(value) },
+        range: ->(value) { Shape.range(value) },
+        requested_list: ->(value) { Shape.list(value) }
+      }.freeze
+
+      # The names of the attributes declared on this class, which pattern matching reads
+      #
+      # @api private
+      # @return [Array<Symbol>] the attribute names
+      # @example Get the attributes of a user
+      #   X::User.__send__(:attribute_names)
+      def attribute_names
+        parent = superclass
+        @attribute_names ||= parent.respond_to?(:attribute_names, true) ? parent.__send__(:attribute_names).dup : [:id]
+      end
+
+      # The other names some attributes are read by, which a pattern can ask for
+      #
+      # @api private
+      # @return [Array<Symbol>] the alias names
+      # @example Get the attribute aliases of a user
+      #   X::User.__send__(:attribute_aliases) # => [:tweet_count, :pinned_tweet_id, :most_recent_tweet_id]
+      def attribute_aliases
+        parent = superclass
+        @attribute_aliases ||= parent.respond_to?(:attribute_aliases, true) ? parent.__send__(:attribute_aliases).dup : []
+      end
+
+      # The key paths of the identifiers of the resources this class refers to
+      #
+      # The problems of a resource are read by them. A key path holds an identifier, a list of them, or a list of objects that each hold one as id, as the
+      # referenced_posts of a post do.
+      #
+      # @api private
+      # @return [Array<Array<String>>] the key paths
+      # @example Get the key paths of the references of a list
+      #   X::List.__send__(:reference_keys) # => [["owner_id"]]
+      def reference_keys
+        parent = superclass
+        @reference_keys ||= parent.respond_to?(:reference_keys, true) ? parent.__send__(:reference_keys).dup : []
+      end
+
+      # The identifiers of the resources that attributes of this class refer to
+      #
+      # A problem is read to tell which resource it is about, so a key path the attributes hold something other than
+      # an object along reads as no identifier, rather than raise as the reader of the reference does.
+      #
+      # @api private
+      # @param attrs [Hash{String => Object}] the attributes
+      # @return [Array<Object>] the identifiers, as the attributes hold them
+      # @example Get the identifiers a post refers to
+      #   X::Post.__send__(:referenced_ids, {"id" => "1", "author_id" => "2"}) # => ["2"]
+      def referenced_ids(attrs) = reference_keys.flat_map { |path| ids_at(attrs, path) }
+
+      private :attribute_names, :attribute_aliases, :reference_keys, :referenced_ids
+
+      private
+
+      # Define another name for an attribute, which a pattern can ask for
+      #
+      # @api private
+      # @param name [Symbol] the alias name
+      # @param original [Symbol] the name of the attribute
+      # @return [void]
+      def attribute_alias(name, original)
+        attribute_aliases << name
+        alias_method name, original
+      end
+
+      # Define a reader for an attribute
+      #
+      # @api private
+      # @param name [Symbol] the reader name
+      # @param type [Symbol] the attribute type: raw, boolean, time, integer, integers, list, object, objects, range,
+      #   conversation_id, or requested_list, of which integers, list, and objects read a list the response omitted as empty, and
+      #   requested_list, the type of a field no lookup asks for unless it is requested, reads it as nil, since a
+      #   response that omits it does not say the list is empty; object is the type of an object the API nests in a
+      #   resource, and objects of a list of them
+      # @param key [Array<String>] the key path
+      # @param tweet_key [Array<String>, nil] the key path of the name the API gave the attribute before it named
+      #   tweets posts, which it still gives it where it has not renamed it, such as in a stream, read when the
+      #   response holds nothing at the key path
+      # @return [void]
+      # @raise [InvalidAttribute] from the reader, if the response holds a value the type cannot be read from
+      def attribute(name, type = :raw, key: [name.to_s], tweet_key: nil)
+        attribute_names << name
+        paths = key_paths(key, tweet_key)
+        converter = CONVERTERS.fetch(type)
+        define_method(name) do
+          # @type self: Resource
+          Utils.read("#{self.class}##{name}", Shape.dig_first("#{self.class}##{name}", attrs, paths)) { |value| converter.call(value) }
+        end
+        return unless type.eql?(:boolean)
+
+        define_method(:"#{name}?") do
+          # @type self: Resource
+          public_send(name).eql?(true)
+        end
+      end
+
+      # Define a reader that resolves a referenced resource
+      #
+      # @api private
+      # @param name [Symbol] the reader name
+      # @param klass_name [Symbol] the referenced resource class name under X
+      # @param key [Array<String>] the key path holding the identifier
+      # @param tweet_key [Array<String>, nil] the key path of the name the API gave it before it named tweets posts,
+      #   read when the response holds nothing at the key path
+      # @return [void]
+      # @raise [InvalidAttribute] from the reader, if the response holds an identifier that is not one, or a key path
+      #   that passes through something other than an object
+      def reference(name, klass_name, key:, tweet_key: nil)
+        paths = key_paths(key, tweet_key)
+        reference_keys.concat(paths)
+        define_method(name) do
+          # @type self: Resource
+          resolve(X.const_get(klass_name), Shape.dig_first("#{self.class}##{name}", attrs, paths))
+        end
+      end
+
+      # Define a reader that resolves a list of referenced resources
+      #
+      # @api private
+      # @param name [Symbol] the reader name
+      # @param klass_name [Symbol] the referenced resource class name under X
+      # @param key [Array<String>] the key path holding the identifiers
+      # @return [void]
+      # @raise [InvalidAttribute] from the reader, if the response holds something other than a list of identifiers
+      def references(name, klass_name, key:)
+        path = key_path(key)
+        reference_keys << path
+        define_method(name) do
+          # @type self: Resource
+          reader = "#{self.class}##{name}"
+          ids = Utils.read(reader, Shape.dig(reader, attrs, path)) { |value| Shape.list(value) } || EMPTY_LIST
+          ids.map { |id| resolve(X.const_get(klass_name), id) }.freeze
+        end
+      end
+
+      # Check that a key path is an array of keys
+      #
+      # @api private
+      # @param key [Object] the key path to check
+      # @return [Array<String>] the key path
+      # @raise [ArgumentError] if the key path is not an array
+      def key_path(key)
+        raise ArgumentError, "key must be an Array of keys, not #{key.inspect}" unless key.is_a?(Array)
+
+        key
+      end
+
+      # The key paths an attribute is read at, in the order they are tried
+      #
+      # @api private
+      # @param key [Object] the key path
+      # @param tweet_key [Object, nil] the key path of the name the API gave it before it named tweets posts, if any
+      # @return [Array<Array<String>>] the key paths
+      # @raise [ArgumentError] if a key path is not an array
+      def key_paths(key, tweet_key) = [key, tweet_key].compact.each { |path| key_path(path) }
+
+      # The identifiers at a key path
+      #
+      # A key path holds an identifier, a list of them, or a list of objects that each hold one as id.
+      #
+      # @api private
+      # @param attrs [Hash{String => Object}] the attributes
+      # @param path [Array<String>] the key path
+      # @return [Array<Object>] the identifiers, with nil for a path that holds none
+      def ids_at(attrs, path)
+        found = path.reduce(attrs) { |value, key| Hash.try_convert(value)&.[](key) }
+        (Array.try_convert(found) || [found]).map { |element| Hash.try_convert(element)&.[]("id") || element }
+      end
+    end
+    private_constant :Attributes
+  end
+end