x-resources 1.0.0

data/lib/x/resources/direct_message.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require_relative "cursor"
+require_relative "direct_message_conversations"
+require_relative "finders"
+require_relative "resource"
+
+module X
+  module Resources
+    # A direct message event
+    # @api public
+    class ::X::DirectMessage < Resource
+      extend Finders
+      extend DirectMessageConversations
+
+      # 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
+      #   extend X::Resources::DirectMessageConversations
+
+      # The direct message event fields the object layer requests; the sender, the participants, and the posts a
+      # message refers to come with their expansions
+      #
+      # 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[attachments created_at dm_conversation_id entities event_type id text].freeze
+      # Every expansion available on direct message 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[attachments.media_keys participant_ids referenced_posts sender_id].freeze
+      # Maximum number of events per page
+      # @api private
+      MAX_RESULTS = 100
+      private_constant :MAX_RESULTS
+
+      class << self
+        # The API endpoint used to look up direct message events by identifier
+        #
+        # @api private
+        # @return [String] the endpoint
+        # @example Get the endpoint
+        #   X::DirectMessage.__send__(:endpoint) # => "dm_events"
+        def endpoint
+          "dm_events"
+        end
+
+        # The query parameter that selects direct message event fields
+        #
+        # @api private
+        # @return [String] the fields parameter
+        # @example Get the fields parameter
+        #   X::DirectMessage.__send__(:fields_key) # => "dm_event.fields"
+        def fields_key = "dm_event.fields"
+
+        private :endpoint, :fields_key
+
+        # The default query parameters requesting every direct message field and expansion
+        #
+        # @api public
+        # @return [Hash{String => Array<String>}] the default query parameters
+        # @example Get the default parameters
+        #   X::DirectMessage.default_params["dm_event.fields"]
+        def default_params
+          {"dm_event.fields" => FIELDS, "user.fields" => User::FIELDS, "post.fields" => Post::FIELDS,
+           "media.fields" => Media::FIELDS, "expansions" => EXPANSIONS}
+        end
+
+        # The most recent direct message events across every conversation
+        #
+        # @api public
+        # @param client [Object] the client used to make the requests
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the events
+        # @example Print the most recent direct messages
+        #   X::DirectMessage.all(client: client).first(10).each { |message| puts message.text }
+        def all(client:, **params)
+          Cursor.__send__(:build, self, "dm_events", client:, params: {max_results: MAX_RESULTS}.merge(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 client [Object] the client used to make the requests
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the events
+        # @example Print the conversation with a user
+        #   X::DirectMessage.with(user, client: client).each { |message| puts message.text }
+        def with(user, client:, **params)
+          path = "dm_conversations/with/#{Utils.id_of(user, User)}/dm_events"
+          Cursor.__send__(:build, self, path, client:, params: {max_results: MAX_RESULTS}.merge(params))
+        end
+
+        # Send a direct message to a user as the authenticated user
+        #
+        # @api public
+        # @param user [User, String, Integer] the recipient or their identifier
+        # @param text [String, nil] the text of the message, or nil for a message of attachments alone
+        # @param client [Object] the client used to make the request
+        # @param media_ids [Array<String, Integer, #fetch, Media>, String, Integer, #fetch, Media, nil] the identifiers or
+        #   media keys of uploaded media to attach, what the uploads returned, or media, such as that of a post, one or
+        #   many
+        # @param params [Hash] additional request body fields, such as attachments
+        # @return [DirectMessage] the sent message, holding only its identifiers
+        # @raise [ArgumentError] if the message has neither text nor any other field, or has both media_ids and
+        #   attachments
+        # @raise [MissingResource] if the API answers without the message
+        # @example Send a direct message
+        #   X::DirectMessage.create(user, "Hello!", client: client)
+        # @example Send an image without text
+        #   X::DirectMessage.create(user, client: client, media_ids: media)
+        def create(user, text = nil, client:, media_ids: nil, **params)
+          path = "dm_conversations/with/#{Utils.id_of(user, User)}/messages"
+          sent(client.post(path, message(text, params, media_ids), **Utils::JSON_CLASSES), path, client:)
+        end
+
+        # Delete a direct message event as the authenticated user
+        #
+        # @api public
+        # @param message [DirectMessage, String, Integer] the event or its identifier
+        # @param client [Object] the client used to make the request
+        # @return [Boolean] true if the event was deleted
+        # @example Delete a direct message
+        #   X::DirectMessage.delete("1234567890", client: client)
+        def delete(message, client:)
+          body = client.delete("dm_events/#{Utils.id_of(message, self)}", **Utils::JSON_CLASSES)
+          Utils.written(body, "deleted").eql?(true)
+        end
+      end
+
+      # @!attribute [r] text
+      #   The text
+      #
+      #   It is the text as the API sends it, which escapes &, <, and > as &amp;, &lt;, and &gt;, and it stays so
+      #   throughout 1.x, so unescape it to display it.
+      #
+      #   @api public
+      #   @return [String, nil] the text, HTML-escaped as the API sends it
+      #   @example Get the text
+      #     message.text # => "Ruby &amp; Rails"
+      #   @example Display the text
+      #     CGI.unescapeHTML(message.text) # => "Ruby & Rails"
+      attribute :text
+
+      # @!attribute [r] event_type
+      #   The event type: MessageCreate, ParticipantsJoin, or ParticipantsLeave
+      #   @api public
+      #   @return [String, nil] the event type
+      #   @example Get the event type
+      #     message.event_type
+      attribute :event_type
+
+      # @!attribute [r] created_at
+      #   The time when the event occurred
+      #   @api public
+      #   @return [Time, nil] the event time
+      #   @example Get the event time
+      #     message.created_at
+      attribute :created_at, :time
+
+      # @!attribute [r] sender_id
+      #   The identifier of the sender
+      #   @api public
+      #   @return [Integer, nil] the sender identifier
+      #   @example Get the sender identifier
+      #     message.sender_id
+      attribute :sender_id, :integer
+
+      # @!attribute [r] dm_conversation_id
+      #   The identifier of the conversation
+      #   @api public
+      #   @return [String, nil] the conversation identifier: the identifiers of the two users of a one-to-one
+      #     conversation joined with a hyphen, or the number of a group conversation
+      #   @raise [InvalidAttribute] if the response holds an identifier that is neither
+      #   @example Get the conversation identifier
+      #     message.dm_conversation_id
+      attribute :dm_conversation_id, :conversation_id
+
+      # @!attribute [r] participant_ids
+      #   The identifiers of the participants who joined or left
+      #   @api public
+      #   @return [Array<Integer>] the participant identifiers, empty if there are none
+      #   @example Get the participant identifiers
+      #     message.participant_ids
+      attribute :participant_ids, :integers
+
+      # @!attribute [r] referenced_posts
+      #   The referenced posts with their identifiers
+      #   @api public
+      #   @return [Array<Hash>] the referenced posts, empty if there are none
+      #   @example Get the referenced posts
+      #     message.referenced_posts
+      attribute :referenced_posts, :objects, tweet_key: %w[referenced_tweets]
+      reference_keys.push(%w[referenced_posts], %w[referenced_tweets])
+
+      # @!attribute [r] attachments
+      #   The attachment keys
+      #   @api public
+      #   @return [Hash, nil] the attachments
+      #   @example Get the attachments
+      #     message.attachments
+      attribute :attachments, :object
+
+      # @!attribute [r] entities
+      #   The entities found in the text: its URLs, hashtags, mentions, and cashtags
+      #   @api public
+      #   @return [Hash, nil] the entities
+      #   @example Get the URLs of a message
+      #     message.entities&.dig("urls")
+      attribute :entities, :object
+
+      # @!method sender
+      #   The sender, resolved from the includes or as a stub holding only its identifier
+      #   @api public
+      #   @return [User, nil] the sender
+      #   @example Get the sender's username
+      #     message.sender.username
+      reference :sender, :User, key: %w[sender_id]
+
+      # @!method participants
+      #   The participants who joined or left, from the includes or as stubs
+      #   @api public
+      #   @return [Array<User>] the participants
+      #   @example Get the participants
+      #     message.participants
+      references :participants, :User, key: %w[participant_ids]
+
+      # @!method media
+      #   The attached media, from the includes or as stubs holding only their keys
+      #   @api public
+      #   @return [Array<Media>] the media
+      #   @example Get the media URLs
+      #     message.media.map(&:url)
+      references :media, :Media, key: %w[attachments media_keys]
+
+      # 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
+      #   message.references
+      def references
+        referenced_posts.filter_map do |reference|
+          resolve(Post, reference["id"]) #: Post?
+        end.freeze
+      end
+
+      # Check whether a user sent this message
+      #
+      # A message that does not name its sender, as the message a new direct message returns does not, or one fetched
+      # with dm_event.fields that leave sender_id out, cannot say the user sent it, so it answers false; its sender_id
+      # is nil.
+      #
+      # @api public
+      # @param user [User, String, Integer] the user or their identifier
+      # @return [Boolean] true if the user sent the message, false if another user did, or the message does not name
+      #   its sender
+      # @example Split messages into sent and received
+      #   me = client.current_user_id
+      #   messages.partition { |message| message.from?(me) }
+      def from?(user) = sender_id.to_s.eql?(Utils.id_of(user, User))
+
+      # Check whether the message belongs to a group conversation
+      #
+      # The identifier of a one-to-one conversation joins the identifiers of its two participants with a hyphen, and
+      # the identifier of a group conversation is a number of its own.
+      #
+      # @api public
+      # @return [Boolean] true if the message belongs to a group conversation, false if to a one-to-one conversation or
+      #   the message does not say
+      # @raise [InvalidAttribute] if the response holds a conversation identifier that is not one
+      # @example Leave out the messages of group conversations
+      #   client.direct_messages.reject(&:group?)
+      def group?
+        conversation_id = dm_conversation_id
+        !conversation_id.nil? && !conversation_id.include?("-")
+      end
+
+      # The other participant of a one-to-one conversation, as seen by a user
+      #
+      # The sender, when the user did not send the message, and otherwise the other member of the
+      # conversation, from the includes or as a stub holding only its identifier. A message that does not name its
+      # sender, as the message a new direct message returns does not, is read by its conversation alone, whose other
+      # member is the peer of a user who is one of its two. A message whose conversation the user is not one of the
+      # two members of has no peer for that user, even one another user sent, so neither has a message of a group
+      # conversation, whose identifier names none of its members.
+      #
+      # @api public
+      # @param user [User, String, Integer] the user, usually the authenticated user, or their identifier
+      # @return [User, nil] the other participant, or nil for a group conversation, one without another participant,
+      #   or one the user is not a member of
+      # @raise [InvalidAttribute] if the response holds a conversation identifier that is not one
+      # @example Print the identifier of the user each message was exchanged with
+      #   me = client.current_user_id
+      #   client.direct_messages.reject(&:group?).each { |message| puts message.peer(me)&.id }
+      def peer(user)
+        user_id = Utils.id_of(user, User)
+        members = dm_conversation_id.to_s.split("-")
+        return unless members.empty? || members.include?(user_id)
+        return sender unless sender_id.nil? || from?(user_id)
+
+        resolve(User, members.find { |id| !id.eql?(user_id) }) #: User?
+      end
+
+      # Delete this direct message event as the authenticated user
+      #
+      # @api public
+      # @return [Boolean] true if the event was deleted
+      # @example Delete a direct message
+      #   message.delete
+      def delete
+        self.class.delete(self, client: client!)
+      end
+
+      # The other names of attributes, as the aliases YARD reads them as
+      #
+      # @!parse
+      #   alias_method :referenced_tweets, :referenced_posts
+      attribute_alias :referenced_tweets, :referenced_posts
+    end
+  end
+end

data/lib/x/resources/direct_message_conversations.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "cursor"
+require_relative "media_ids"
+require_relative "shape"
+require_relative "utils"
+
+module X
+  module Resources
+    # Group conversations of direct messages: starting one, sending to one, and reading one, extended by DirectMessage
+    #
+    # Internal to x-resources: the methods it gives DirectMessage, such as X::DirectMessage.create_group, 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 DirectMessageConversations
+      # Maximum number of events per page of a conversation
+      # @api private
+      MAX_RESULTS = 100
+      private_constant :MAX_RESULTS
+
+      # Start a group conversation, sending its first message as the authenticated user
+      #
+      # @api public
+      # @param users [Array<User, String, Integer>] the other participants or their identifiers
+      # @param text [String, nil] the text of the first message, or nil for a message of attachments alone
+      # @param client [Object] the client used to make the request
+      # @param media_ids [Array<String, Integer, #fetch, Media>, String, Integer, #fetch, Media, nil] the identifiers or
+      #   media keys of uploaded media to attach, what the uploads returned, or media, such as that of a post, one or
+      #   many
+      # @param params [Hash] additional fields of the message, such as attachments
+      # @return [DirectMessage] the sent message, holding only its identifiers, among them the new conversation's
+      # @raise [ArgumentError] if the message has neither text nor any other field, or has both media_ids and
+      #   attachments
+      # @raise [MissingResource] if the API answers without the message
+      # @example Start a group conversation
+      #   X::DirectMessage.create_group([alice, bob], "Hello, both of you!", client: client)
+      # @example Start a group conversation with an image
+      #   X::DirectMessage.create_group([alice, bob], client: client, media_ids: media)
+      def create_group(users, text = nil, client:, media_ids: nil, **params)
+        body = {conversation_type: "Group", participant_ids: users.map { |user| Utils.id_of(user, User) }, message: message(text, params, media_ids)}
+        sent(client.post("dm_conversations", body, **Utils::JSON_CLASSES), "dm_conversations", client:)
+      end
+
+      # Send a direct message to a conversation as the authenticated user
+      #
+      # @api public
+      # @param conversation [DirectMessage, String, Integer] a message of the conversation, or the conversation's identifier
+      # @param text [String, nil] the text of the message, or nil for a message of attachments alone
+      # @param client [Object] the client used to make the request
+      # @param media_ids [Array<String, Integer, #fetch, Media>, String, Integer, #fetch, Media, nil] the identifiers or
+      #   media keys of uploaded media to attach, what the uploads returned, or media, such as that of a post, one or
+      #   many
+      # @param params [Hash] additional request body fields, such as attachments
+      # @return [DirectMessage] the sent message, holding only its identifiers
+      # @raise [ArgumentError] if the conversation identifier is not one, the message has neither text nor any other
+      #   field, or it has both media_ids and attachments
+      # @raise [MissingResource] if the API answers without the message
+      # @example Reply to the conversation of a message
+      #   X::DirectMessage.create_in(message, "Sounds good", client: client)
+      # @example Reply with an image
+      #   X::DirectMessage.create_in(message, client: client, media_ids: media)
+      def create_in(conversation, text = nil, client:, media_ids: nil, **params)
+        path = "dm_conversations/#{conversation_id_of(conversation)}/messages"
+        sent(client.post(path, message(text, params, media_ids), **Utils::JSON_CLASSES), path, client:)
+      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 client [Object] the client used to make the requests
+      # @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
+      #   X::DirectMessage.in(message, client: client).each { |event| puts event.text }
+      def in(conversation, client:, **params)
+        path = "dm_conversations/#{conversation_id_of(conversation)}/dm_events"
+        Cursor.__send__(:build, DirectMessage, path, client:, params: {max_results: MAX_RESULTS}.merge(params))
+      end
+
+      private
+
+      # The identifier of a conversation, from a message of it or as given
+      # @api private
+      # @param conversation [DirectMessage, String, Integer] a message of the conversation, or the conversation's identifier
+      # @return [String] the conversation identifier
+      # @raise [ArgumentError] if the identifier is not one
+      def conversation_id_of(conversation)
+        id = case conversation
+        when DirectMessage then conversation.dm_conversation_id.to_s
+        else conversation.to_s
+        end
+        return id if id.match?(Shape::CONVERSATION_ID)
+
+        raise ArgumentError, "#{conversation.inspect} is not a conversation: pass a direct message or a conversation identifier"
+      end
+
+      # The fields of a message to send, which needs text or attachments
+      #
+      # The API takes media as attachments, each an object holding the identifier of one upload as a String, so
+      # media_ids builds them, and a caller who builds them itself passes attachments instead, by a String or a Symbol.
+      #
+      # @api private
+      # @param text [String, nil] the text of the message
+      # @param params [Hash] additional fields of the message, such as attachments
+      # @param media_ids [Array, #fetch, Media, String, Integer, nil] the identifiers of uploaded media to attach, what
+      #   the uploads returned, or media, one or many; an empty list attaches nothing, as nil does
+      # @return [Hash{Symbol => Object}] the fields, without the text when there is none
+      # @raise [ArgumentError] if the message has neither text nor any other field, or attaches media by both
+      #   media_ids and attachments
+      def message(text, params, media_ids)
+        fields = {text:, **Utils.fields(params)}.compact
+        attachments = MediaIds.media_ids_of(media_ids).map { |media_id| {media_id:} }
+        unless attachments.empty?
+          raise ArgumentError, "pass media_ids or attachments, not both" if fields.key?(:attachments)
+
+          fields[:attachments] = attachments
+        end
+        raise ArgumentError, "a direct message needs text, or something else to show, such as media_ids" if fields.empty?
+
+        fields
+      end
+
+      # The message a send created, from the identifiers the API returned
+      #
+      # It is built as the resources of any response are, so a response without the message, or without its event
+      # identifier, raises, as any request that creates a resource does.
+      #
+      # @api private
+      # @param body [Hash, nil] the response body
+      # @param path [String] the path the message was sent to
+      # @param client [Object] the client used to make the request
+      # @return [DirectMessage] the message
+      # @raise [MissingResource] if the response holds no data, or no event identifier
+      # @raise [InvalidAttribute] if the response holds an event identifier that is not one
+      def sent(body, path, client:)
+        body = body.to_h
+        data = body["data"]
+        data = {"id" => data["dm_event_id"], "dm_conversation_id" => data["dm_conversation_id"]} if data.is_a?(Hash)
+        created_from_response(body.merge("data" => data), "POST #{path}", client:)
+      end
+    end
+    private_constant :DirectMessageConversations
+  end
+end

data/lib/x/resources/errors.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "x/core"
+
+module X
+  module Resources
+    # Base error class for the failures of the object layer, which every error x-resources raises of its own descends from
+    #
+    # It descends from X::Error, so that rescuing the errors of the X API catches one of them as well. The errors
+    # that descend from it are named directly under X, as the errors of x-core are, so that this is the one name
+    # under X::Resources a rescue reaches for: it catches the failure of the object layer alone.
+    #
+    # @api public
+    class Error < X::Error; end
+  end
+
+  # Raised when a resource that was asked for by identifier or name does not exist
+  #
+  # A lookup of one resource that is not there raises it whether the API answers 200 OK with no data or a 404 that
+  # reports the resource as not found, so code that rescues it need not know which. It is not
+  # the NotFound of x-core, which holds the response, and which every other 404 raises, such as one from a client
+  # pointed at the wrong host or API version; the NotFound of a 404 that reports the resource is the cause of this.
+  #
+  # It is raised as well when a request that creates a resource, such as X::Post.create, succeeds without returning
+  # it, as X::User.current! raises it when users/me returns no user, holding the problems the response reported.
+  #
+  # @api public
+  class MissingResource < Resources::Error
+    # The problems the API reported about the resource
+    # @api public
+    # @return [Array<Problem>] the problems, empty if the API reported none
+    # @example Read why a user was not found
+    #   error.problems.first&.detail # => "Could not find user with username: [nobody]."
+    attr_reader :problems
+
+    # Initialize the error, adding the detail of the first problem to the message
+    #
+    # @api public
+    # @param message [String, nil] the message
+    # @param problems [Array<Problem>] the problems the API reported
+    # @return [MissingResource] a new error
+    # @example Raise the error
+    #   raise X::MissingResource.new("Could not find X::User nobody", problems: problems)
+    def initialize(message = nil, problems: [])
+      explanation = problems.first&.then { |problem| problem.detail || problem.title }
+      super(([message, explanation].compact.join(": ") if message || explanation))
+      @problems = problems.dup.freeze
+    end
+  end
+
+  # Raised when a successful response holds what the object layer cannot read as what the API documents
+  #
+  # It is the base of InvalidAttribute, for one value of a response, and is raised itself for what a response says
+  # beside its values, such as a page that names the token of a page before it as the next, which would have the
+  # pages requested again for good. It is not the InvalidResponse of x-core, which a body that is not JSON raises,
+  # and which holds the response.
+  #
+  # @api public
+  # @example Rescue what the object layer cannot read of a response
+  #   begin
+  #     user.followers.to_a
+  #   rescue X::UnreadableResponse => e
+  #     logger.warn(e.message)
+  #   end
+  class UnreadableResponse < Resources::Error; end
+
+  # Raised when a response holds a value that cannot be read as what the API documents it to be
+  #
+  # A timestamp that is not ISO 8601, or an identifier that is not one, is read when the attribute or the reference
+  # that holds it is read, and the identifier of a resource when the resource is built from the response, so that one
+  # value the object layer cannot read raises where it is read, as this error, which descends from X::Error, rather
+  # than as the ArgumentError the same value raises when a caller passes it. The cause is the error that refused it.
+  #
+  # @api public
+  class InvalidAttribute < UnreadableResponse; end
+
+  # Raised when a resource that holds no client is asked for what only a request can answer
+  #
+  # A resource built without a client, such as one Marshal read back, or one built with from_id and no client, holds
+  # its attributes, which it reads as any resource does, but cannot hydrate, refresh, page a collection, or act, since
+  # each of them is a request, and the client is what makes it. Build the resource with the client: of from_id, or
+  # look it up again with a client.
+  #
+  # @api public
+  # @example Hydrate a resource that has a client
+  #   X::User.from_id(7_505_382, client: client).hydrate
+  class MissingClient < Resources::Error; end
+
+  # Raised when a scan or a count reads the pages its max_pages allows, and the API names a page after them
+  #
+  # A check that pages through a collection, such as List#member? or User#follows?, and a count of posts, such as
+  # X::Post.count_all, read as many pages as the answer takes, and the API bills each one. Given max_pages,
+  # each reads no more pages than that, and raises this rather than answer from the pages it read, which would be
+  # wrong: a member on a page it did not read, or posts counted on one, would go unseen.
+  #
+  # @api public
+  # @example Give up on a check that would read more than ten pages
+  #   begin
+  #     list.member?(user, max_pages: 10)
+  #   rescue X::PageLimitReached
+  #     nil
+  #   end
+  class PageLimitReached < Resources::Error; end
+end