x-resources 1.0.0

data/lib/x/resources/shape.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "utils"
+
+module X
+  module Resources
+    # Reads the objects and lists of a response, which must be what the API documents them to be
+    #
+    # A value the object layer reads into, such as the public_metrics a count is read from, or the links of a post, is
+    # checked to be an object or a list before it is read, so that one that is not raises InvalidAttribute, as any
+    # value of a response that cannot be read does, rather than the NoMethodError or TypeError of reading into it.
+    #
+    # @api private
+    module Shape
+      # The pattern of a conversation identifier: two user identifiers joined with a hyphen, or a group's own number
+      CONVERSATION_ID = /\A\d+(?:-\d+)?\z/
+
+      extend self
+
+      # Read the value at a path of keys, through the object each key but the last names
+      #
+      # A key that names nothing reads as nil, as Hash#dig does, but one that names something other than an object,
+      # such as a String where the API documents public_metrics, cannot be read further.
+      #
+      # @api private
+      # @param name [String] what the value is, such as the reader that reads it
+      # @param value [Hash, nil] the object the path starts at
+      # @param path [Array<String>] the keys
+      # @return [Object, nil] the value, or nil if a key names nothing
+      # @raise [InvalidAttribute] if the path passes through something other than an object
+      # @example Read the number of times a post was liked
+      #   X::Resources::Shape.dig("X::Post#like_count", attrs, %w[public_metrics like_count])
+      def dig(name, value, path) = path.reduce(value) { |current, key| read_object(name, current)&.[](key) }
+
+      # Read the value at the first of several paths of keys that names one
+      #
+      # @api private
+      # @param name [String] what the value is, such as the reader that reads it
+      # @param value [Hash, nil] the object the paths start at
+      # @param paths [Array<Array<String>>] the paths, in the order they are tried
+      # @return [Object, nil] the value, or nil if no path names one
+      # @raise [InvalidAttribute] if a path passes through something other than an object
+      # @example Read the number of times a post was reposted, by either name
+      #   X::Resources::Shape.dig_first("X::Post#repost_count", attrs, [%w[public_metrics repost_count], %w[public_metrics retweet_count]])
+      def dig_first(name, value, paths)
+        paths.each do |path|
+          found = dig(name, value, path)
+          return found unless found.nil?
+        end
+        nil
+      end
+
+      # Read a String, which the response may leave out
+      #
+      # @api private
+      # @param name [String] what the value is, such as the reader that reads it
+      # @param value [String, nil] the String
+      # @return [String, nil] the String, or nil if the value is missing
+      # @raise [InvalidAttribute] if the value is not a String
+      # @example Read the username a permalink names
+      #   X::Resources::Shape.read_string("X::User#permalink", user.username)
+      def read_string(name, value) = Utils.read(name, value) { String.try_convert(value) || (raise ArgumentError unless value.nil?) }
+
+      # Read an object, which the response may leave out
+      #
+      # @api private
+      # @param name [String] what the value is, such as the reader that reads it
+      # @param value [Hash, nil] the object
+      # @return [Hash, nil] the object, or nil if the value is missing
+      # @raise [InvalidAttribute] if the value is not an object
+      # @example Read the entities of a post
+      #   X::Resources::Shape.read_object("X::Post#entities", attrs["entities"])
+      def read_object(name, value) = Utils.read(name, value) { object(value) }
+
+      # Read a list of objects, which the response may leave out
+      #
+      # @api private
+      # @param name [String] what the value is, such as the reader that reads it
+      # @param value [Array<Hash>, nil] the list
+      # @return [Array<Hash>] the objects, empty if the list is missing
+      # @raise [InvalidAttribute] if the value is not a list, or holds something other than an object
+      # @example Read the links of a post
+      #   X::Resources::Shape.objects("X::Post#urls", entities["urls"])
+      def objects(name, value) = Utils.read(name, value) { object_list(value) }
+
+      # Check that a value the API documents as a list of objects is one, if it is there
+      #
+      # @api private
+      # @param value [Array<Hash>, nil] the value
+      # @return [Array<Hash>] the objects, empty if the value is missing
+      # @raise [ArgumentError] if the value is not a list, or holds something other than an object
+      def object_list(value) = Array(list(value)).each { |element| object!(element) }.freeze
+
+      # Check that a value the API documents as an object is one, if it is there
+      #
+      # @api private
+      # @param value [Hash, nil] the value
+      # @return [Hash, nil] the object, or nil if the value is missing
+      # @raise [ArgumentError] if the value is not an object
+      def object(value) = (object!(value) unless value.nil?)
+
+      # Check that a value the API documents as an object is one
+      #
+      # @api private
+      # @param value [Hash] the value
+      # @return [Hash] the object
+      # @raise [ArgumentError] if the value is not an object
+      def object!(value) = Hash.try_convert(value) || raise(ArgumentError, "#{value.inspect} is not an object")
+
+      # Check that a value the API documents as a list is one, if it is there
+      #
+      # @api private
+      # @param value [Array, nil] the value
+      # @return [Array, nil] the list, or nil if the value is missing
+      # @raise [ArgumentError] if the value is not a list
+      def list(value) = (Array.try_convert(value) || raise(ArgumentError, "#{value.inspect} is not a list") unless value.nil?)
+
+      # Read a range of characters, which the response may leave out
+      #
+      # The API gives a range as a list of its start and its end, which the range leaves out.
+      #
+      # @api private
+      # @param value [Array<Integer>, nil] the start and end of the range
+      # @return [Range<Integer>, nil] the range, which leaves out its end, or nil if the value is missing
+      # @raise [ArgumentError] if the value is not a list of two Integers that are not negative
+      # @example Read the range of the text a post shows
+      #   X::Resources::Shape.range([8, 10]) # => 8...10
+      def range(value)
+        bounds = list(value)
+        return if bounds.nil?
+        raise ArgumentError, "#{bounds} is not the start and end of a range" unless bounds.size.eql?(2) && bounds.all? { |bound| Integer === bound && !bound.negative? }
+
+        Range.new(bounds.first, bounds.last, true)
+      end
+
+      # Read a numeric identifier or a count as an Integer, if it is there
+      #
+      # It is read as strictly as an identifier is checked: an Integer that is not negative, or a String of digits
+      # alone, with no sign, underscore, or whitespace, so that a count reads as the whole number it is, and the
+      # identifier of a resource a reader such as author_id returns is one that resource is found by.
+      #
+      # @api private
+      # @param value [String, Integer, nil] the identifier or count
+      # @return [Integer, nil] the Integer, or nil if the value is missing
+      # @raise [ArgumentError] if the value is neither an Integer that is not negative nor a String of digits
+      def integer(value)
+        return value if value.nil? || (Integer === value && !value.negative?)
+        raise ArgumentError, "invalid value for Integer(): #{value.to_s.inspect}" unless String === value && Utils::NUMERIC_ID.match?(value)
+
+        Integer(value, 10)
+      end
+
+      # Read the identifier of a conversation of direct messages, if it is there
+      #
+      # @api private
+      # @param value [String, nil] the identifier
+      # @return [String, nil] the identifier, or nil if the value is missing
+      # @raise [ArgumentError] if the value is not a String of digits, or of two numbers joined with a hyphen
+      def conversation_id(value)
+        return value if value.nil? || (String === value && CONVERSATION_ID.match?(value))
+
+        raise ArgumentError, "#{value.inspect} is not a conversation identifier"
+      end
+    end
+    private_constant :Shape
+  end
+end

data/lib/x/resources/space.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require_relative "batch_finders"
+require_relative "cursor"
+require_relative "resource"
+require_relative "topic"
+
+module X
+  module Resources
+    # A live audio space
+    #
+    # The space endpoints, but for buyers, take app-only authentication or OAuth 2.0 user context, not OAuth 1.0a, so
+    # a client that signs with OAuth 1.0a reads spaces with a copy that authenticates as the app, while the spaces and
+    # posts it reads hold the client, so that they act as the user.
+    #
+    # @api public
+    class ::X::Space < Resource
+      extend BatchFinders
+
+      # 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::BatchFinders
+
+      # Every public space 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 ended_at id is_ticketed lang participant_count scheduled_start started_at state
+        subscriber_count title updated_at].freeze
+      # Every expansion available on space 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[creator_id host_ids invited_user_ids speaker_ids topic_ids].freeze
+      # Maximum number of posts or buyers per page, or of spaces a search returns
+      # @api private
+      MAX_RESULTS = 100
+      private_constant :MAX_RESULTS
+
+      class << self
+        # The API endpoint used to look up spaces by identifier
+        #
+        # @api private
+        # @return [String] the endpoint
+        # @example Get the endpoint
+        #   X::Space.__send__(:endpoint) # => "spaces"
+        def endpoint
+          "spaces"
+        end
+
+        # The type of the identifier, which is letters and digits rather than a number
+        #
+        # @api private
+        # @return [Symbol] raw
+        # @example Get the identifier type
+        #   X::Space.__send__(:id_type) # => :raw
+        def id_type = :raw
+
+        # The client a space lookup requests with
+        #
+        # The space endpoints refuse OAuth 1.0a, so a client that signs with it looks spaces up with a copy that
+        # reuses its bearer token, as a client signed in with OAuth 2.0 as a user that holds the app's credentials does.
+        # One that holds none looks them up as it is.
+        #
+        # @api private
+        # @param client [Object] the client the lookup was given
+        # @return [Object] the client's app-only client, or the client itself
+        # @example Get the client a space lookup requests with
+        #   X::Space.__send__(:client_for, client)
+        def client_for(client) = Utils.app_client(client)
+
+        # The query parameter that selects space fields
+        #
+        # @api private
+        # @return [String] the fields parameter
+        # @example Get the fields parameter
+        #   X::Space.__send__(:fields_key) # => "space.fields"
+        def fields_key = "space.fields"
+
+        private :endpoint, :id_type, :client_for, :fields_key
+
+        # The default query parameters requesting every space field and expansion
+        #
+        # @api public
+        # @return [Hash{String => Array<String>}] the default query parameters
+        # @example Get the default parameters
+        #   X::Space.default_params["space.fields"]
+        def default_params
+          {"space.fields" => FIELDS, "user.fields" => User::FIELDS, "topic.fields" => Topic::FIELDS, "expansions" => EXPANSIONS}
+        end
+
+        # Search spaces by their titles
+        #
+        # The API returns the matching spaces in one response, of up to 100 spaces.
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param client [Object] the client used to make the request
+        # @param params [Hash] query parameters merged over the default parameters, such as state: live or scheduled
+        # @return [Cursor] a cursor over the matching spaces
+        # @example Print the live spaces about Ruby
+        #   X::Space.search("ruby", client: client, state: "live").each { |space| puts space.title }
+        def search(query, client:, **params)
+          Cursor.__send__(:build, self, "spaces/search", client:, params: {query:, max_results: MAX_RESULTS}.merge(params), app_only: true)
+        end
+      end
+
+      # Look up the live and scheduled spaces many users created, in parallel batches
+      #
+      # The API returns the spaces of up to 100 users at a time, in one response without pages, so the users are
+      # looked up that many at a time.
+      #
+      # @api public
+      # @param users [Array<User, String, Integer>] the users who created the spaces, or their identifiers
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Array<Space>] the spaces, frozen, empty if the users created none
+      # @raise [ArgumentError] if a user is not a user or the identifier of one, or the concurrency is less than one,
+      #   before a request
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Print the spaces two users created
+      #   X::Space.find_all_by_creator([7505382, 783214], client: client).each { |space| puts space.title }
+      def self.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+        ids = users.map { |user| Utils.id_of(user, User) }
+        spaces = lookup_in_batches("spaces/by/creator_ids", :user_ids, ids, client:, concurrency:, **params, &) #: Array[Space]
+        spaces.freeze
+      end
+
+      # @!attribute [r] title
+      #   The title
+      #   @api public
+      #   @return [String, nil] the title
+      #   @example Get the title
+      #     space.title
+      attribute :title
+
+      # @!attribute [r] state
+      #   The state: live, scheduled, or ended
+      #   @api public
+      #   @return [String, nil] the state
+      #   @example Get the state
+      #     space.state
+      attribute :state
+
+      # @!attribute [r] lang
+      #   The BCP 47 language tag
+      #   @api public
+      #   @return [String, nil] the language tag
+      #   @example Get the language
+      #     space.lang
+      attribute :lang
+
+      # @!attribute [r] created_at
+      #   The time when the space was created
+      #   @api public
+      #   @return [Time, nil] the creation time
+      #   @example Get the creation time
+      #     space.created_at
+      attribute :created_at, :time
+
+      # @!attribute [r] started_at
+      #   The time when the space started
+      #   @api public
+      #   @return [Time, nil] the start time
+      #   @example Get the start time
+      #     space.started_at
+      attribute :started_at, :time
+
+      # @!attribute [r] ended_at
+      #   The time when the space ended
+      #   @api public
+      #   @return [Time, nil] the end time
+      #   @example Get the end time
+      #     space.ended_at
+      attribute :ended_at, :time
+
+      # @!attribute [r] scheduled_start
+      #   The scheduled start time
+      #   @api public
+      #   @return [Time, nil] the scheduled start time
+      #   @example Get the scheduled start time
+      #     space.scheduled_start
+      attribute :scheduled_start, :time
+
+      # @!attribute [r] updated_at
+      #   The time when the space was last updated
+      #   @api public
+      #   @return [Time, nil] the update time
+      #   @example Get the update time
+      #     space.updated_at
+      attribute :updated_at, :time
+
+      # @!attribute [r] ticketed
+      #   Whether the space requires a ticket, the is_ticketed field
+      #   @api public
+      #   @return [Boolean, nil] true if the space is ticketed
+      #   @example Check whether a space is ticketed
+      #     space.ticketed?
+      attribute :ticketed, :boolean, key: %w[is_ticketed]
+
+      # @!method ticketed?
+      #   Check whether the space requires a ticket
+      #   @api public
+      #   @return [Boolean] true if the space is ticketed
+      #   @example Check whether a space is ticketed
+      #     space.ticketed?
+
+      # @!attribute [r] participant_count
+      #   The number of participants
+      #   @api public
+      #   @return [Integer, nil] the participant count
+      #   @example Get the participant count
+      #     space.participant_count
+      attribute :participant_count, :integer
+
+      # @!attribute [r] subscriber_count
+      #   The number of subscribers
+      #   @api public
+      #   @return [Integer, nil] the subscriber count
+      #   @example Get the subscriber count
+      #     space.subscriber_count
+      attribute :subscriber_count, :integer
+
+      # @!attribute [r] creator_id
+      #   The identifier of the creator
+      #   @api public
+      #   @return [Integer, nil] the creator identifier
+      #   @example Get the creator identifier
+      #     space.creator_id
+      attribute :creator_id, :integer
+
+      # @!attribute [r] host_ids
+      #   The identifiers of the hosts
+      #   @api public
+      #   @return [Array<Integer>] the host identifiers, empty if there are none
+      #   @example Get the host identifiers
+      #     space.host_ids
+      attribute :host_ids, :integers
+
+      # @!attribute [r] speaker_ids
+      #   The identifiers of the speakers
+      #   @api public
+      #   @return [Array<Integer>] the speaker identifiers, empty if there are none
+      #   @example Get the speaker identifiers
+      #     space.speaker_ids
+      attribute :speaker_ids, :integers
+
+      # @!attribute [r] invited_user_ids
+      #   The identifiers of the invited users
+      #   @api public
+      #   @return [Array<Integer>] the invited user identifiers, empty if there are none
+      #   @example Get the invited user identifiers
+      #     space.invited_user_ids
+      attribute :invited_user_ids, :integers
+
+      # @!attribute [r] topic_ids
+      #   The identifiers of the topics
+      #   @api public
+      #   @return [Array<Integer>] the topic identifiers, empty if there are none
+      #   @example Get the topic identifiers
+      #     space.topic_ids
+      attribute :topic_ids, :integers
+
+      # @!method creator
+      #   The creator, resolved from the includes or as a stub holding only its identifier
+      #   @api public
+      #   @return [User, nil] the creator
+      #   @example Get the creator's username
+      #     space.creator.username
+      reference :creator, :User, key: %w[creator_id]
+
+      # @!method hosts
+      #   The hosts, resolved from the includes or as stubs holding only their identifiers
+      #   @api public
+      #   @return [Array<User>] the hosts
+      #   @example Get the hosts
+      #     space.hosts
+      references :hosts, :User, key: %w[host_ids]
+
+      # @!method speakers
+      #   The speakers, from the includes or as stubs holding only their identifiers
+      #   @api public
+      #   @return [Array<User>] the speakers
+      #   @example Get the speakers
+      #     space.speakers
+      references :speakers, :User, key: %w[speaker_ids]
+
+      # @!method invited_users
+      #   The invited users, from the includes or as stubs holding only their identifiers
+      #   @api public
+      #   @return [Array<User>] the invited users
+      #   @example Get the invited users
+      #     space.invited_users
+      references :invited_users, :User, key: %w[invited_user_ids]
+
+      # @!method topics
+      #   The topics, from the includes or as stubs holding only their identifiers
+      #   @api public
+      #   @return [Array<Topic>] the topics
+      #   @example Get the names of the topics
+      #     space.topics.map(&:name)
+      references :topics, :Topic, key: %w[topic_ids]
+
+      # The posts shared in this space
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the posts
+      # @example Print the shared posts
+      #   space.posts.each { |post| puts post.text }
+      def posts(**params)
+        cursor(Post, "spaces/#{id}/tweets", max_results: MAX_RESULTS, app_only: true, **params)
+      end
+
+      # The users who bought a ticket to this space
+      #
+      # The authenticated user must have created the space. The endpoint takes only OAuth 2.0 user context, which the object layer cannot route around, so a client that
+      # signs with OAuth 1.0a, or authenticates as the app, is refused.
+      #
+      # @api public
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Cursor] a cursor over the buyers
+      # @example Print the buyers of a ticketed space
+      #   space.buyers.each { |user| puts user.username }
+      def buyers(**params) = cursor(User, "spaces/#{id}/buyers", max_results: MAX_RESULTS, **params)
+
+      alias_method :tweets, :posts
+    end
+  end
+end

data/lib/x/resources/topic.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module X
+  # A topic a space is about
+  #
+  # The API offers no lookup of topics, so a topic is read from the response of the space that expanded it, and the
+  # class answers no finder. from_id builds one from its identifier, which a topic the response did not expand is built
+  # as too, and which compares equal to the topic it identifies, but hydrate and refresh raise UnsupportedOperation for
+  # one that is not hydrated, since there is nothing to look it up with.
+  #
+  # @api public
+  class Topic < Resource
+    # Every public topic 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[description id name].freeze
+
+    # The default query parameters, which request every field
+    #
+    # The API offers no lookup of topics, so they are requested by the spaces that expand them, which ask for these
+    # fields, and a topic a response included with all of them is hydrated.
+    #
+    # @api public
+    # @return [Hash{String => Array<String>}] the default query parameters
+    # @example Get the default parameters
+    #   X::Topic.default_params # => {"topic.fields" => [...]}
+    def self.default_params = {"topic.fields" => FIELDS}
+
+    # The key under which topics appear in the includes of a response
+    #
+    # @api private
+    # @return [String] the includes key
+    # @example Get the includes key
+    #   X::Topic.__send__(:includes_key) # => "topics"
+    def self.includes_key
+      "topics"
+    end
+    private_class_method :includes_key
+
+    # @!attribute [r] name
+    #   The name of the topic
+    #   @api public
+    #   @return [String, nil] the name
+    #   @example Get the name
+    #     topic.name # => "Technology"
+    attribute :name
+
+    # @!attribute [r] description
+    #   What the topic is about
+    #   @api public
+    #   @return [String, nil] the description
+    #   @example Get the description
+    #     topic.description # => "All about technology"
+    attribute :description
+  end
+end

data/lib/x/resources/trend.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "serialization"
+require_relative "shape"
+require_relative "utils"
+require_relative "value_equality"
+require_relative "value_marshalling"
+
+module X
+  module Resources
+    # A topic trending in a place, as the trends of the place report it
+    #
+    # A trend has no identifier, and the API offers no lookup of one, so trends are read a place at a time, a place
+    # named by its Yahoo! Where On Earth identifier (WOEID), such as 1 for the whole world.
+    #
+    # @api public
+    class ::X::Trend
+      include Serialization
+      include ValueEquality
+      include ValueMarshalling
+
+      # The mixins of the class by their full names, which YARD needs to resolve them in a class opened under X
+      #
+      # @!parse
+      #   include X::Resources::Serialization
+      #   include X::Resources::ValueEquality
+      #   include X::Resources::ValueMarshalling
+
+      # Every trend field
+      #
+      # A minor release may add to it the fields the API adds, so that the trends of a place ask for them too.
+      FIELDS = %w[trend_name tweet_count].freeze
+      # The most trends the API returns for a place, which it returns 20 of unless asked for more
+      # @api private
+      MAX_TRENDS = 50
+      private_constant :MAX_TRENDS
+
+      # The raw attributes of the trend
+      # @api public
+      # @return [Hash{String => Object}] the attributes
+      # @example Get the raw attributes
+      #   trend.attrs # => {"trend_name" => "#ruby", "tweet_count" => 1234}
+      attr_reader :attrs
+
+      # The topics trending in a place
+      #
+      # The endpoint takes app-only authentication, or OAuth 2.0 as a user, so a client that signs with OAuth 1.0a
+      # reads the trends with a copy that authenticates as the app.
+      #
+      # @api public
+      # @param woeid [Integer, String] the Yahoo! Where On Earth identifier of the place, such as 1 for the world
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters, such as max_trends, which is 50, the most the API returns, unless given
+      # @return [Array<Trend>] the trends, frozen
+      # @raise [ArgumentError] if the WOEID is not a number, before a request
+      # @raise [InvalidAttribute] if the response holds the trends as something other than a list of objects
+      # @example Print the topics trending in the world
+      #   X::Trend.at(1, client: client).each { |trend| puts trend.name }
+      def self.at(woeid, client:, **params)
+        path = "trends/by/woeid/#{woeid_of(woeid)}"
+        body = Utils.app_client(client).get(Utils.path(path, {"trend.fields" => FIELDS, "max_trends" => MAX_TRENDS}.merge(params)), **Utils::JSON_CLASSES)
+        Shape.objects("#{self}.at", body.to_h["data"]).map { |attrs| new(attrs) }.freeze
+      end
+
+      # The WOEID of a place, which must be a number
+      #
+      # @api private
+      # @param woeid [Integer, String] the WOEID
+      # @return [String] the WOEID
+      # @raise [ArgumentError] if the WOEID is not an Integer or a String of digits
+      def self.woeid_of(woeid)
+        value = case woeid
+        when String, Integer then woeid.to_s
+        end
+        return value if value&.match?(Utils::NUMERIC_ID)
+
+        raise ArgumentError, "#{woeid.inspect} is not a WOEID: pass an Integer, or a String of digits"
+      end
+      private_class_method :woeid_of
+
+      # Initialize a trend from the attributes the API reported
+      #
+      # @api public
+      # @param attrs [Hash{String, Symbol => Object}] the attributes
+      # @return [Trend] a new trend
+      # @raise [ArgumentError] if the attributes are not a Hash
+      # @example Build a trend
+      #   X::Trend.new({"trend_name" => "#ruby", "tweet_count" => 1234})
+      def initialize(attrs)
+        @attrs = Utils.deep_freeze(Utils.attributes!(attrs))
+        freeze
+      end
+
+      # The name of the trend, such as a hashtag or a phrase
+      #
+      # @api public
+      # @return [String, nil] the name
+      # @example Get the name
+      #   trend.name # => "#ruby"
+      def name = attrs["trend_name"]
+
+      # The number of posts about the trend
+      #
+      # It is read from post_count, or from tweet_count, the name the API gives it before it names tweets posts there,
+      # as the post count of a user is.
+      #
+      # @api public
+      # @return [Integer, nil] the number of posts, or nil if the API reported none
+      # @raise [InvalidAttribute] if the response holds a number of posts that is not a number
+      # @example Get the number of posts
+      #   trend.post_count # => 1234
+      def post_count = Utils.read("#{self.class}#post_count", attrs["post_count"] || attrs["tweet_count"]) { |value| Shape.integer(value) }
+
+      alias_method :tweet_count, :post_count
+
+      # Deconstruct the trend into what its readers read, so it matches a hash pattern
+      #
+      # A pattern that asks for every key gets name and post_count, and one can ask for the number of posts as
+      # tweet_count too, as it can of a user.
+      #
+      # @api public
+      # @param keys [Array<Symbol>, nil] the keys the pattern asks for, or nil for every reader
+      # @return [Hash{Symbol => Object}] what the readers read
+      # @raise [InvalidAttribute] if the pattern asks for a number of posts the response holds as something else
+      # @example Keep the topics of more than 10,000 posts
+      #   X::Trend.at(1, client: client).select { |trend| trend in {post_count: 10_000..} }
+      def deconstruct_keys(keys) = Utils.deconstruct(self, keys, %i[name post_count], %i[tweet_count])
+    end
+  end
+end