x-resources 1.0.0

data/lib/x/resources/post_counts.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "errors"
+require_relative "shape"
+require_relative "page_limit"
+require_relative "utils"
+
+module X
+  module Resources
+    # Counts of the posts that match a query, which the API bills by the request rather than by the post
+    #
+    # The counts endpoints refuse OAuth 1.0a, so a client that signs with it counts with a copy that authenticates as
+    # the app. A client signed in with OAuth 2.0 as a user that holds no credentials of the app counts as the user,
+    # which the count of recent posts takes, and the count of the full archive, which takes app-only authentication
+    # alone, refuses with 403 Forbidden, raising X::Forbidden.
+    #
+    # Internal to x-resources: the methods it gives Post, such as X::Post.count, 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 PostCounts
+      # The endpoint that counts the posts from the last seven days
+      # @api private
+      RECENT_ENDPOINT = "tweets/counts/recent"
+      # The endpoint that counts the posts from the full archive
+      # @api private
+      ALL_ENDPOINT = "tweets/counts/all"
+      # The granularity that makes the fewest periods, and so the least data
+      # @api private
+      DEFAULT_GRANULARITY = "day"
+      private_constant :RECENT_ENDPOINT, :ALL_ENDPOINT, :DEFAULT_GRANULARITY
+
+      # Count the recent posts that match a query, without reading them
+      #
+      # The recent posts are counted a page of periods at a time, as the full archive is, which max_pages limits.
+      #
+      # @api public
+      # @param query [String] the search query
+      # @param client [Object] the client used to make the requests
+      # @param max_pages [Integer, nil] the most pages of counts to request, or nil for no limit
+      # @param params [Hash] query parameters, such as start_time and end_time
+      # @return [Integer] the number of matching posts
+      # @raise [ArgumentError] if max_pages is neither an Integer of at least 1 nor nil, before a request
+      # @raise [InvalidAttribute] if the response holds a total that is not a number
+      # @raise [UnreadableResponse] if a page names the token of a page before it as the next
+      # @raise [PageLimitReached] if the count requests max_pages pages, and the API names another
+      # @example Count the recent posts about Ruby
+      #   X::Post.count("ruby", client: client)
+      def count(query, client:, max_pages: nil, **params) = total(pages(RECENT_ENDPOINT, query, client:, max_pages:, **params))
+
+      # Count the posts from the full archive that match a query, without reading them
+      #
+      # The archive is counted a page of periods at a time, and the API bills each page, so a count over many years
+      # can take many requests, which max_pages limits, raising PageLimitReached rather than read past them.
+      #
+      # @api public
+      # @param query [String] the search query
+      # @param client [Object] the client used to make the requests
+      # @param max_pages [Integer, nil] the most pages of counts to request, or nil for no limit
+      # @param params [Hash] query parameters, such as start_time and end_time
+      # @return [Integer] the number of matching posts
+      # @raise [ArgumentError] if max_pages is neither an Integer of at least 1 nor nil, before a request
+      # @raise [InvalidAttribute] if the response holds a total that is not a number
+      # @raise [UnreadableResponse] if a page names the token of a page before it as the next
+      # @raise [PageLimitReached] if the count requests max_pages pages, and the API names another
+      # @example Count every post about Ruby
+      #   X::Post.count_all("ruby", client: client)
+      # @example Count the posts about Ruby in no more than three requests
+      #   X::Post.count_all("ruby", client: client, max_pages: 3)
+      def count_all(query, client:, max_pages: nil, **params) = total(pages(ALL_ENDPOINT, query, client:, max_pages:, **params))
+
+      # Count the posts from the last seven days that match a query, by period
+      #
+      # The recent posts are counted a page of periods at a time, as the full archive is, which max_pages limits.
+      #
+      # @api public
+      # @param query [String] the search query
+      # @param client [Object] the client used to make the requests
+      # @param max_pages [Integer, nil] the most pages of counts to request, or nil for no limit
+      # @param params [Hash] query parameters, such as granularity, which is day by default
+      # @return [Hash{Range<Time> => Integer}] the number of matching posts, keyed by the time each period spans, from
+      #   its start up to, but not including, its end, oldest first
+      # @raise [ArgumentError] if max_pages is neither an Integer of at least 1 nor nil, before a request
+      # @raise [InvalidAttribute] if the response holds a period without a start and an end in ISO 8601, or without a
+      #   count
+      # @raise [UnreadableResponse] if a page names the token of a page before it as the next
+      # @raise [PageLimitReached] if the count requests max_pages pages, and the API names another
+      # @example Count the recent posts about Ruby by hour
+      #   X::Post.count_by_period("ruby", client: client, granularity: "hour")
+      def count_by_period(query, client:, max_pages: nil, **params) = periods(pages(RECENT_ENDPOINT, query, client:, max_pages:, **params))
+
+      # Count the posts from the full archive that match a query, by period
+      #
+      # The archive is counted a page of periods at a time, and the API bills each page, so a count over many years
+      # can take many requests, which max_pages limits, raising PageLimitReached rather than read past them.
+      #
+      # @api public
+      # @param query [String] the search query
+      # @param client [Object] the client used to make the requests
+      # @param max_pages [Integer, nil] the most pages of counts to request, or nil for no limit
+      # @param params [Hash] query parameters, such as granularity, which is day by default
+      # @return [Hash{Range<Time> => Integer}] the number of matching posts, keyed by the time each period spans, from
+      #   its start up to, but not including, its end, oldest first
+      # @raise [ArgumentError] if max_pages is neither an Integer of at least 1 nor nil, before a request
+      # @raise [InvalidAttribute] if the response holds a period without a start and an end in ISO 8601, or without a
+      #   count
+      # @raise [UnreadableResponse] if a page names the token of a page before it as the next
+      # @raise [PageLimitReached] if the count requests max_pages pages, and the API names another
+      # @example Count every post about Ruby by day
+      #   X::Post.count_all_by_period("ruby", client: client)
+      def count_all_by_period(query, client:, max_pages: nil, **params) = periods(pages(ALL_ENDPOINT, query, client:, max_pages:, **params))
+
+      private
+
+      # Request every page of counts, following the next page token, up to a limit
+      # @api private
+      # @param path [String] the counts endpoint path
+      # @param query [String] the search query
+      # @param client [Object] the client used to make the requests
+      # @param max_pages [Integer, nil] the most pages to request, or nil for no limit
+      # @param params [Hash] query parameters
+      # @return [Array<Hash>] the response bodies
+      # @raise [ArgumentError] if max_pages is neither an Integer of at least 1 nor nil, before a request
+      # @raise [InvalidAttribute] if a response holds a meta that is not an object
+      # @raise [UnreadableResponse] if a response names the token of a page before it as the next
+      # @raise [PageLimitReached] if the pages requested reach max_pages, and the last names another
+      def pages(path, query, client:, max_pages:, **params)
+        params, max_pages = {query:, granularity: DEFAULT_GRANULARITY}.merge(params), PageLimit.check!(max_pages)
+        client = Utils.app_client(client)
+        bodies = [] #: Array[Hash[String, untyped]]
+        given = params[:next_token]
+        loop do
+          bodies << client.get(Utils.path(path, params), **Utils::JSON_CLASSES).to_h
+          token = next_token(bodies, given, max_pages) or break
+          params = params.merge(next_token: token)
+        end
+        bodies
+      end
+
+      # The token of the page of counts after the last, which fetched no page before it
+      #
+      # A page that names the token of a page before it as the next would have the pages requested again for good,
+      # and the API bill each request, so it raises instead. The next_token the counts were given, which fetched the
+      # first page, is the token of a page before each of them too. An empty token names no page, so the page that
+      # names one is the last, as a page that names none is. A page after as many as max_pages allows raises too,
+      # rather than be requested.
+      #
+      # @api private
+      # @param bodies [Array<Hash>] the response bodies so far
+      # @param given [String, nil] the next_token the counts were given, or nil for none
+      # @param max_pages [Integer, nil] the most pages to request, or nil for no limit
+      # @return [String, nil] the token, or nil if the last page is the last of the counts
+      # @raise [InvalidAttribute] if the last response holds a meta that is not an object
+      # @raise [UnreadableResponse] if the last response names the token of a page before it as the next
+      # @raise [PageLimitReached] if the pages requested reach max_pages, and the last names another
+      def next_token(bodies, given, max_pages)
+        tokens = bodies.map { |body| Shape.dig("The next page of the counts of #{self}", body, %w[meta next_token]) }
+        token = tokens.pop
+        return if token.nil? || token.eql?("")
+
+        raise UnreadableResponse, "The counts of #{self} name the next_token #{token.inspect}, which fetched an earlier page" if [given, *tokens].include?(token)
+
+        PageLimit.reached!("The counts of #{self}", read: bodies.size, max_pages:, next_token: token)
+        token
+      end
+
+      # The total count of every page, which the API names for tweets or for posts
+      # @api private
+      # @param bodies [Array<Hash>] the response bodies
+      # @return [Integer] the total
+      # @raise [InvalidAttribute] if a page holds a total that is not a number
+      def total(bodies) = bodies.sum { |body| page_total(body.dig("meta", "total_tweet_count") || body.dig("meta", "total_post_count")) }
+
+      # The total count of one page, which is zero when the page holds none
+      # @api private
+      # @param value [Integer, String, nil] the total the page holds
+      # @return [Integer] the total
+      # @raise [InvalidAttribute] if the total is not a number
+      def page_total(value) = Utils.read("The total of the counts of #{self}", value) { Shape.integer(value) } || 0
+
+      # The count of each period of every page, oldest first
+      #
+      # The API serves the newest page first while each page runs oldest to newest, so the periods of a paginated
+      # count are sorted before they are frozen, and the result reads in time order however many pages it took.
+      #
+      # @api private
+      # @param bodies [Array<Hash>] the response bodies
+      # @return [Hash{Range<Time> => Integer}] the counts, keyed by the time each period spans, in time order
+      # @raise [InvalidAttribute] if a period has no start and end in ISO 8601, or no count that is a number, or a
+      #   response holds the periods as something other than a list of objects
+      def periods(bodies)
+        entries = bodies.flat_map { |body| Shape.objects("A period of the counts of #{self}", body["data"]) } #: Array[Hash[String, untyped]]
+        entries.map { |entry| period(entry) }.sort_by { |span, _count| span.begin }.to_h.freeze
+      end
+
+      # The time a period spans and the number of posts in it
+      #
+      # The period spans its start up to, but not including, its end, which is the start of the period after it. The
+      # API names the number for tweets or for posts.
+      #
+      # @api private
+      # @param entry [Hash] the period, with its start, its end, and its count
+      # @return [Array(Range<Time>, Integer)] the time it spans and the count
+      # @raise [InvalidAttribute] if the period has no start and end in ISO 8601, or no count that is an Integer that is
+      #   not negative or a String of digits
+      def period(entry)
+        Utils.read("A period of the counts of #{self}", entry) do
+          [Time.iso8601(entry["start"].to_s)...Time.iso8601(entry["end"].to_s), Shape.integer(entry["tweet_count"] || entry["post_count"]) || raise(ArgumentError, "a period needs a count")]
+        end
+      end
+    end
+    private_constant :PostCounts
+  end
+end

data/lib/x/resources/post_search.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "cursor"
+require_relative "utils"
+
+module X
+  module Resources
+    # The searches of posts, and the posts of the authenticated user that others reposted
+    #
+    # Internal to x-resources: the methods it gives Post, such as X::Post.search, 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 PostSearch
+      # Maximum number of posts per page of a search, or of the reposts of the authenticated user
+      # @api private
+      MAX_RESULTS = 100
+      # Maximum number of posts per page of full-archive search, which allows only MAX_RESULTS with context annotations
+      # @api private
+      MAX_ARCHIVE_RESULTS = 500
+      private_constant :MAX_RESULTS, :MAX_ARCHIVE_RESULTS
+
+      # Search recent posts
+      #
+      # @api public
+      # @param query [String] the search query
+      # @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 matching posts
+      # @example Print posts about Ruby
+      #   X::Post.search("ruby -is:retweet", client: client).each { |post| puts post.text }
+      def search(query, client:, **params)
+        # @type self: singleton(Post)
+        Cursor.__send__(:build, self, "tweets/search/recent", client:, params: {query:, max_results: MAX_RESULTS}.merge(params), min_results: 10)
+      end
+
+      # Search the full archive of posts
+      #
+      # A page holds up to 500 posts, or 100 when the request asks for context annotations, as the default fields do.
+      #
+      # @api public
+      # @param query [String] the search query
+      # @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 matching posts
+      # @example Print every post about Ruby
+      #   X::Post.search_all("ruby -is:retweet", client: client).each { |post| puts post.text }
+      # @example Page through every post about Ruby 500 at a time, without context annotations
+      #   X::Post.search_all("ruby", client: client, "post.fields": %w[created_at text])
+      def search_all(query, client:, **params)
+        # @type self: singleton(Post)
+        max_results = context_annotations?(params) ? MAX_RESULTS : MAX_ARCHIVE_RESULTS
+        Cursor.__send__(:build, self, "tweets/search/all", client:, params: {query:, max_results:}.merge(params), min_results: 10)
+      end
+
+      # The posts of the authenticated user that other users have reposted
+      #
+      # The endpoint names no user, so these are always the posts of the user the client authenticates as.
+      #
+      # @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 reposted posts
+      # @example Print the reposted posts
+      #   X::Post.reposts_of_me(client: client).each { |post| puts post.text }
+      def reposts_of_me(client:, **params)
+        # @type self: singleton(Post)
+        Cursor.__send__(:build, self, "users/reposts_of_me", client:, params: {max_results: MAX_RESULTS}.merge(params))
+      end
+
+      alias_method :retweets_of_me, :reposts_of_me
+
+      private
+
+      # Check whether a request asks for the context annotations of its posts
+      # @api private
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Boolean] true if the post fields include context_annotations
+      def context_annotations?(params)
+        # @type self: singleton(Post)
+        Utils.merge_params(default_params, params)["post.fields"].to_s.split(",").include?("context_annotations")
+      end
+    end
+    private_constant :PostSearch
+  end
+end

data/lib/x/resources/post_usage.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "serialization"
+require_relative "shape"
+require_relative "utils"
+require_relative "value_equality"
+require_relative "value_marshalling"
+
+module X
+  module Resources
+    # How many posts the app's project has read, as the usage endpoint reports it
+    #
+    # The API caps the posts a project reads each month, and bills each post read, so the usage shows both what a
+    # project has spent and how much of its cap remains.
+    #
+    # @api public
+    class ::X::PostUsage
+      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
+
+      # The endpoint that reports the post usage of the project
+      # @api private
+      ENDPOINT = "usage/tweets"
+      private_constant :ENDPOINT
+      # Every field of the usage
+      FIELDS = %w[cap_reset_day daily_client_app_usage daily_project_usage project_cap project_id project_usage].freeze
+
+      # The raw attributes of the usage
+      # @api public
+      # @return [Hash{String => Object}] the attributes
+      # @example Get the raw attributes
+      #   usage.attrs # => {"project_usage" => "1234", "project_cap" => "3000000", ...}
+      attr_reader :attrs
+
+      # Look up the current post usage of the project the client's app belongs to
+      #
+      # A project has one usage, so it is looked up by no identifier, as X::User.current looks up the one user a
+      # client signs in as. The usage endpoint takes app-only authentication, so a client that signs its requests with OAuth 1.0a
+      # looks the usage up with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user that
+      # holds no credentials of the app requests as the user, which the endpoint refuses with X::Forbidden.
+      #
+      # A response that holds no usage returns nil, as X::User.current does for a users/me that holds no user, and
+      # passes the problems it reported to the block, if there is one.
+      #
+      # @api public
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters, such as days, the number of days to report, which is 7 by default
+      # @return [PostUsage, nil] the usage, or nil if the response holds none
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Look up the usage of the last 30 days
+      #   X::PostUsage.current(client: client, days: 30)&.project_usage
+      # @example Log why the API returned no usage
+      #   X::PostUsage.current(client: client) { |problem| warn problem.detail }
+      def self.current(client:, **params)
+        body = Utils.app_client(client).get(Utils.path(ENDPOINT, {"usage.fields" => FIELDS}.merge(params)), **Utils::JSON_CLASSES)
+        Problem.all_from(body).each { |problem| yield problem } if block_given?
+        Hash.try_convert(body.to_h["data"])&.then { |data| new(data) }
+      end
+
+      # Look up the current post usage of the project, which must be returned
+      #
+      # @api public
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters, such as days, the number of days to report, which is 7 by default
+      # @return [PostUsage] the usage
+      # @raise [MissingResource] if the API returns no usage
+      # @example Look up the usage of the last 30 days
+      #   X::PostUsage.current!(client: client, days: 30).project_usage
+      def self.current!(client:, **params)
+        problems = [] #: Array[Problem]
+        current(client:, **params) { |problem| problems << problem } || raise(MissingResource.new("#{ENDPOINT} returned no usage", problems:))
+      end
+
+      # Initialize the usage from the attributes the API reported
+      #
+      # @api public
+      # @param attrs [Hash{String, Symbol => Object}] the attributes
+      # @return [PostUsage] a new usage
+      # @raise [ArgumentError] if the attributes are not a Hash
+      # @example Build a usage
+      #   X::PostUsage.new({"project_usage" => "1234"})
+      def initialize(attrs)
+        @attrs = Utils.deep_freeze(Utils.attributes!(attrs))
+        freeze
+      end
+
+      # The identifier of the project
+      #
+      # @api public
+      # @return [Integer, nil] the identifier
+      # @example Get the project identifier
+      #   usage.project_id # => 1234567890
+      def project_id = integer("project_id", attrs["project_id"])
+
+      # The number of posts the project has read in the current billing cycle
+      #
+      # @api public
+      # @return [Integer, nil] the number of posts
+      # @example Get the posts read this cycle
+      #   usage.project_usage # => 1234
+      def project_usage = integer("project_usage", attrs["project_usage"])
+
+      # The number of posts the project may read in a billing cycle
+      #
+      # @api public
+      # @return [Integer, nil] the cap
+      # @example Get the cap
+      #   usage.project_cap # => 3000000
+      def project_cap = integer("project_cap", attrs["project_cap"])
+
+      # The day of the month the billing cycle, and so the usage, starts over
+      #
+      # It is an Integer whether the response holds it as a number or as a String, as it holds the other counts.
+      #
+      # @api public
+      # @return [Integer, nil] the day of the month
+      # @raise [InvalidAttribute] if the response holds a value that is not a number
+      # @example Get the reset day
+      #   usage.cap_reset_day # => 16
+      def cap_reset_day = integer("cap_reset_day", attrs["cap_reset_day"])
+
+      # The number of posts the project read each day
+      #
+      # @api public
+      # @return [Hash{Time => Integer}] the number of posts, keyed by the start of each day
+      # @raise [InvalidAttribute] if the response holds a day without a date in ISO 8601, or a number that is not one,
+      #   or holds the days as something other than a list of objects
+      # @example Get the posts read yesterday
+      #   usage.daily.values.last(2).first
+      def daily = days("daily", Shape.dig("#{self.class}#daily", attrs, %w[daily_project_usage usage]))
+
+      # The number of posts each of the project's apps read each day
+      #
+      # @api public
+      # @return [Hash{Integer, nil => Hash{Time => Integer}}] the daily usage, keyed by the identifier of each app
+      # @raise [InvalidAttribute] if the response holds an app identifier that is not a number, a day without a date in
+      #   ISO 8601, or a number that is not one, or holds the apps or their days as something other than a list of objects
+      # @example Total the posts each app read
+      #   usage.daily_by_app.transform_values { |days| days.values.sum }
+      def daily_by_app
+        by_app = {} #: Hash[Integer?, Hash[Time, Integer]]
+        Shape.objects("#{self.class}#daily_by_app", attrs["daily_client_app_usage"]).each do |app|
+          by_app[integer("daily_by_app", app["client_app_id"])] = days("daily_by_app", app["usage"])
+        end
+        by_app.freeze
+      end
+
+      # Deconstruct the usage into what its readers read, so it matches a hash pattern
+      #
+      # Only the readers a pattern names are read, so one that names the counts of the project matches a usage whose
+      # days cannot be read.
+      #
+      # @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 what the response holds as something that cannot be read
+      # @example Warn when the project has read nine tenths of its cap
+      #   warn "near the cap" if usage in {project_usage: Integer => used, project_cap: Integer => cap} and used * 10 >= cap * 9
+      def deconstruct_keys(keys) = Utils.deconstruct(self, keys, %i[project_id project_usage project_cap cap_reset_day daily daily_by_app])
+
+      private
+
+      # Read daily usage entries, counting a day without a number as zero
+      # @api private
+      # @param reader [String] the name of the reader that reads them
+      # @param entries [Array<Hash>, nil] the entries, each with a date and a usage
+      # @return [Hash{Time => Integer}] the number of posts, keyed by the start of each day
+      # @raise [InvalidAttribute] if an entry has no date in ISO 8601, or a number that is not one, or the entries are
+      #   not a list of objects
+      def days(reader, entries)
+        counts = {} #: Hash[Time, Integer]
+        entries = Shape.objects("#{self.class}##{reader}", entries)
+        entries.each { |entry| counts[time(reader, entry["date"])] = integer(reader, entry["usage"]) || 0 }
+        counts.freeze
+      end
+
+      # Read an identifier or a count the response holds as an Integer
+      # @api private
+      # @param reader [String] the name of the reader that reads it
+      # @param value [String, Integer, nil] the value
+      # @return [Integer, nil] the Integer, or nil if the value is missing
+      # @raise [InvalidAttribute] if the value is not a number
+      def integer(reader, value) = Utils.read("#{self.class}##{reader}", value) { Shape.integer(value) }
+
+      # Read a date the response holds as a Time, which it must hold
+      # @api private
+      # @param reader [String] the name of the reader that reads it
+      # @param value [String, nil] the date, in ISO 8601
+      # @return [Time] the time
+      # @raise [InvalidAttribute] if the value is missing, or is not ISO 8601
+      def time(reader, value) = Utils.read("#{self.class}##{reader}", value) { Time.iso8601(value.to_s) }
+    end
+  end
+end

data/lib/x/resources/post_writes.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "media_ids"
+require_relative "utils"
+
+module X
+  module Resources
+    # Creating and deleting posts, and hiding replies, as the authenticated user
+    #
+    # Internal to x-resources: the methods it gives Post, such as X::Post.create, 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 PostWrites
+      # 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 client [Object] the client used to make the request
+      # @param reply_to [Post, String, Integer, nil] the post to reply to or its identifier
+      # @param quote [Post, String, Integer, nil] the post to quote or its identifier
+      # @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; an empty list attaches nothing, as nil does
+      # @param community [Community, String, Integer, nil] the community to post in or its identifier
+      # @param params [Hash] additional request body fields, such as poll or reply_settings, among them reply and
+      #   media, whose other fields reply_to and media_ids are merged into, each named by a String or a Symbol
+      # @return [Post] the created post, holding only its identifier and text
+      # @raise [ArgumentError] if the post has neither text nor any other field, which an empty media_ids is not
+      # @raise [MissingResource] if the API answers without the post
+      # @example Create a post
+      #   X::Post.create("Hello, World!", client: client)
+      # @example Post an image without text
+      #   X::Post.create(client: client, media_ids: media)
+      # @example Reply to a post with an image
+      #   X::Post.create("Hello!", client: client, reply_to: post, media_ids: [media["id"]])
+      # @example Reply without the users a thread would otherwise mention
+      #   X::Post.create("Hello!", client: client, reply_to: post, reply: {exclude_reply_user_ids: ["7505382"]})
+      # @example Post in a community
+      #   X::Post.create("Hello, Rubyists!", client: client, community: community)
+      # @example Quote a post
+      #   X::Post.create("Worth reading", client: client, quote: post)
+      def create(text = nil, client:, reply_to: nil, quote: nil, media_ids: nil, community: nil, **params)
+        params = Utils.fields(params)
+        fields = {text:, **params, **referenced(params, reply_to:, quote:, media_ids:, community:)}.compact
+        raise ArgumentError, "a post needs text, or something else to show, such as media_ids" if fields.empty?
+
+        created_from_response(client.post("tweets", fields, **Utils::JSON_CLASSES), "POST tweets", client:)
+      end
+
+      # Delete a post as the authenticated user
+      #
+      # @api public
+      # @param post [Post, String, Integer] the post or its identifier
+      # @param client [Object] the client used to make the request
+      # @return [Boolean] true if the post was deleted
+      # @example Delete a post
+      #   X::Post.delete("1234567890", client: client)
+      def delete(post, client:)
+        body = client.delete("tweets/#{Utils.id_of(post, Post)}", **Utils::JSON_CLASSES)
+        Utils.written(body, "deleted").eql?(true)
+      end
+
+      # Hide a reply to a post of the authenticated user
+      #
+      # X still shows a hidden reply, behind a notice that its author was hidden.
+      #
+      # @api public
+      # @param post [Post, String, Integer] the reply or its identifier
+      # @param client [Object] the client used to make the request
+      # @return [Boolean] true if the reply is now hidden
+      # @example Hide a reply
+      #   X::Post.hide_reply("1234567890", client: client)
+      def hide_reply(post, client:)
+        change_visibility(post, true, client:).eql?(true)
+      end
+
+      # Show a reply that was hidden, as the author of the post it replies to
+      #
+      # @api public
+      # @param post [Post, String, Integer] the reply or its identifier
+      # @param client [Object] the client used to make the request
+      # @return [Boolean] true if the reply is no longer hidden
+      # @example Show a hidden reply
+      #   X::Post.unhide_reply("1234567890", client: client)
+      def unhide_reply(post, client:)
+        change_visibility(post, false, client:).eql?(false)
+      end
+
+      private
+
+      # Hide or show a reply, and read whether it is hidden
+      # @api private
+      # @param post [Post, String, Integer] the reply or its identifier
+      # @param hidden [Boolean] whether to hide the reply
+      # @param client [Object] the client used to make the request
+      # @return [Boolean, nil] whether the reply is hidden, as the response reports, or nil if it does not
+      def change_visibility(post, hidden, client:)
+        Utils.written(client.put("tweets/#{Utils.id_of(post, Post)}/hidden", {hidden:}, **Utils::JSON_CLASSES), "hidden")
+      end
+
+      # The fields of a new post that refer to other posts, media, or a community
+      #
+      # The API nests the post replied to within reply, and the media within media, beside other fields a caller may
+      # set, so reply_to and media_ids are merged into what the caller gave rather than replace it, and they win the
+      # one field each of them sets. An empty media_ids sets no media field, which the API would refuse.
+      #
+      # @api private
+      # @param params [Hash] the request body fields the caller gave, such as reply, media, or poll
+      # @param reply_to [Post, String, Integer, nil] the post to reply to or its identifier
+      # @param quote [Post, String, Integer, nil] the post to quote or its identifier
+      # @param media_ids [Array, #fetch, Media, String, Integer, nil] the identifiers of uploaded media, what the uploads
+      #   returned, or media, one or many
+      # @param community [Community, String, Integer, nil] the community to post in or its identifier
+      # @return [Hash{Symbol => Object}] the fields, without those given nil
+      def referenced(params, reply_to:, quote:, media_ids:, community:)
+        fields = {} #: Hash[Symbol, untyped]
+        fields[:reply] = merged(params, :reply, in_reply_to_tweet_id: Utils.id_of(reply_to, Post)) unless reply_to.nil?
+        fields[:quote_tweet_id] = Utils.id_of(quote, Post) unless quote.nil?
+        ids = MediaIds.media_ids_of(media_ids)
+        fields[:media] = merged(params, :media, media_ids: ids) unless ids.empty?
+        fields[:community_id] = Utils.id_of(community, Community) unless community.nil?
+        fields
+      end
+
+      # One nested field, with the convenience key merged over what the caller gave
+      #
+      # @api private
+      # @param params [Hash{Symbol => Object}] the request body fields the caller gave
+      # @param key [Symbol] the nested field, reply or media
+      # @param field [Hash] the one field the convenience key sets, which wins over the caller's, by a String or a Symbol
+      # @return [Hash{Symbol => Object}] the nested field
+      def merged(params, key, **field) = Utils.fields(params[key]).merge(field)
+    end
+    private_constant :PostWrites
+  end
+end