x-resources 1.0.0

data/lib/x/resources/utils.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+require_relative "errors"
+
+module X
+  module Resources
+    # Helpers shared across the object layer
+    # @api private
+    module Utils
+      # Parsing options that make a client return plain hashes and arrays, whatever its defaults
+      JSON_CLASSES = {array_class: Array, object_class: Hash}.freeze
+
+      # The pattern of an identifier that is a number, which most resources are identified by
+      NUMERIC_ID = /\A\d+\z/
+
+      # The pattern of the identifiers of each type, as the id_type of a resource class names it: a number; the word
+      # characters the identifier of a space or a place is written with; and a media key, which is the number of the
+      # type of media and the numeric identifier of the media, joined with an underscore
+      ID_PATTERNS = {integer: NUMERIC_ID, raw: /\A\w+\z/, media_key: /\A\d+_\d+\z/}.freeze
+
+      # What an identifier of each type is, which the error raised for one that is not names
+      ID_DESCRIPTIONS = {integer: "an Integer, or a String of digits", raw: "or a String of word characters", media_key: "what an upload returned, or a media key, such as \"3_1880028106020515840\""}.freeze
+
+      # The pattern of a username: one to fifteen word characters, which the at sign a handle is often written with
+      # may precede
+      USERNAME = /\A@?\w{1,15}\z/
+      private_constant :ID_PATTERNS, :ID_DESCRIPTIONS, :USERNAME
+
+      # The message of the error raised for a resource of another class than the one an identifier was expected of
+      FOREIGN_RESOURCE = "%<given>s %<id>s is not %<expected>s: pass %<expected>s or its identifier"
+      # The key a client keeps the identifier of the authenticated user under, named for this gem
+      CURRENT_USER_ID = :x_resources_current_user_id
+      private_constant :FOREIGN_RESOURCE, :CURRENT_USER_ID
+
+      extend self
+
+      # Return a deep-frozen copy of a value with string keys
+      #
+      # @api private
+      # @param value [Object] the value to copy and freeze
+      # @return [Object] the frozen copy
+      def deep_freeze(value)
+        case value
+        when Hash then value.transform_keys(&:to_s).transform_values { |element| deep_freeze(element) }.freeze
+        when Array then value.map { |element| deep_freeze(element) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
+      end
+
+      # The number of resources a count asks for, converted as Array#first converts it
+      #
+      # @api private
+      # @param count [Object] the count
+      # @return [Integer] the count, as an Integer
+      # @raise [TypeError] if the count does not convert to an Integer
+      # @example Read a count given as a Float
+      #   X::Resources::Utils.count!(2.5) # => 2
+      def count!(count) = Integer.try_convert(count) || raise(TypeError, "no implicit conversion of #{count.class} into Integer")
+
+      # The attributes a public constructor is given, which must be a Hash
+      #
+      # Attributes that are not one, such as nil, would otherwise be taken, and raise NoMethodError from a reader, far
+      # from where they were given.
+      #
+      # @api private
+      # @param attrs [Hash] the attributes
+      # @return [Hash] the attributes
+      # @raise [ArgumentError] if the attributes are not a Hash
+      # @example Refuse attributes that are not a Hash
+      #   X::Resources::Utils.attributes!(nil) # raises ArgumentError
+      def attributes!(attrs) = Hash.try_convert(attrs) || raise(ArgumentError, "attrs must be a Hash, not #{attrs.inspect}")
+
+      # Build an endpoint path with an encoded query string
+      #
+      # @api private
+      # @param base [String] the endpoint path without a query string
+      # @param params [Hash] the query parameters
+      # @return [String] the endpoint path with a query string
+      def path(base, params)
+        query = query(params)
+        return base if query.empty?
+
+        "#{base}?#{URI.encode_www_form(query)}"
+      end
+
+      # Normalize query parameters into string keys and comma-separated values
+      #
+      # @api private
+      # @param params [Hash] the query parameters
+      # @return [Hash{String => String, Integer}] the normalized parameters
+      def query(params)
+        params.transform_keys(&:to_s).compact.transform_values { |value| query_value(value) }
+      end
+
+      # Normalize the fields of a request body into Symbol keys
+      #
+      # A caller may name a field by a String or by a Symbol, so each is read by its Symbol, by which a field the
+      # object layer sets, such as attachments or reply, is checked and merged, and a body never names a field twice.
+      #
+      # @api private
+      # @param fields [Hash, nil] the fields
+      # @return [Hash{Symbol => Object}] the fields, keyed by Symbol
+      def fields(fields) = fields.to_h.transform_keys(&:to_sym)
+
+      # Normalize a query parameter value
+      #
+      # An Array is joined with commas, and a Time is given in UTC in the ISO 8601 form the API takes.
+      #
+      # @api private
+      # @param value [Object] the value
+      # @return [Object] the normalized value
+      def query_value(value)
+        case value
+        when Array then value.join(",")
+        when Time then value.getutc.iso8601
+        else value
+        end
+      end
+
+      # Merge query parameters over defaults, dropping parameters set to nil
+      #
+      # @api private
+      # @param defaults [Hash] the default query parameters
+      # @param params [Hash] the query parameters to merge over the defaults
+      # @return [Hash{String => String, Integer}] the normalized parameters
+      def merge_params(defaults, params)
+        query(defaults.merge(params))
+      end
+
+      # Extract the identifier of a resource of a class from the resource or a raw value
+      #
+      # The identifiers of most resources are numbers, so a value that is not, such as a username, raises rather than
+      # reach the API as an identifier it cannot be. The identifiers that are not numbers, such as those of spaces, are
+      # word characters, so anything else raises rather than reach the API as part of a path, and a media key is two
+      # numbers joined with an underscore, so the numeric identifier of media raises rather than look up nothing. A
+      # resource of another class raises too, since its identifier is one of another kind of resource, which the API
+      # would read as the identifier of a resource of this class, such as a list followed as though it were a user.
+      #
+      # @api private
+      # @param value [Resource, String, Integer] a resource or an identifier
+      # @param klass [Class] the resource class the identifier is of
+      # @return [String] the identifier
+      # @raise [ArgumentError] if the value is a resource of another class, is neither a resource nor an identifier,
+      #   or the identifier is not a number, or is not word characters for a resource whose identifiers are not
+      #   numbers, such as a space, or is not a media key for media
+      def id_of(value, klass)
+        id = id_from(value, klass)
+        return id if id.match?(ID_PATTERNS.fetch(klass.__send__(:id_type)))
+
+        not_an_identifier(value, klass)
+      end
+
+      # The identifier a value carries, read from a resource or taken as it is
+      #
+      # The resource this builds checks the identifier when it is made, so this only reads one, and refuses a
+      # resource of another class, whose identifier is not one of this class. Anything else that answers id, such as a
+      # record of an application's database, is refused too, rather than send an identifier of its own to the API as
+      # one of X.
+      #
+      # @api private
+      # @param value [Resource, String, Integer] a resource or an identifier
+      # @param klass [Class] the resource class the identifier is of
+      # @return [String] the identifier
+      # @raise [ArgumentError] if the value is a resource of another class, or is neither a resource nor an identifier
+      def id_from(value, klass)
+        return value.id.to_s if value.is_a?(klass)
+        return value.to_s if value.is_a?(String) || value.instance_of?(Integer)
+        raise ArgumentError, format(FOREIGN_RESOURCE, given: value.class, id: value.id, expected: klass) if value.is_a?(Resource)
+
+        not_an_identifier(value, klass)
+      end
+
+      # Refuse a value that is not an identifier of a resource of a class
+      #
+      # @api private
+      # @param value [Object] the value
+      # @param klass [Class] the resource class the identifier is of
+      # @return [void]
+      # @raise [ArgumentError] always
+      def not_an_identifier(value, klass)
+        raise ArgumentError, "#{value.inspect} is not an identifier: pass #{klass}, #{ID_DESCRIPTIONS.fetch(klass.__send__(:id_type))}"
+      end
+
+      # Normalize a username, dropping the at sign a handle is often written with
+      #
+      # @api private
+      # @param value [String] the username, with or without a leading at sign
+      # @return [String] the username
+      def username(value) = value.to_s.delete_prefix("@")
+
+      # Normalize a username, which must be one, so nothing else reaches a path
+      #
+      # @api private
+      # @param value [String] the username, with or without a leading at sign
+      # @return [String] the username, without the at sign
+      # @raise [ArgumentError] if the value is not one to fifteen word characters
+      def username!(value)
+        name = value.to_s
+        return name.delete_prefix("@") if name.match?(USERNAME)
+
+        raise ArgumentError, "#{value.inspect} is not a username: pass one to fifteen letters, digits, or underscores"
+      end
+
+      # The identifier of the user a client's credentials name, when they name one
+      #
+      # The client's authenticator is where a client keeps the credentials it signs with, and it answers the user
+      # they act for; only an OAuth 1.0a access token names one, since it begins with the identifier of the user who
+      # authorized it. The secrets a client signs with are its authenticator's to keep, so this asks for the user
+      # rather than for a credential to read it out of. An authenticator of another's making may answer the identifier
+      # as the String of digits it read off a token, so it is read as an Integer, as every identifier is, and compared
+      # with the identifiers of users as one.
+      #
+      # @api private
+      # @param client [Object] the client, whose credentials may name a user
+      # @return [Integer, nil] the identifier, or nil if the client's credentials name no user
+      # @raise [ArgumentError] if the authenticator answers a user_id that is not an identifier
+      def authenticated_user_id(client)
+        authenticator = authenticator_of(client)
+        Shape.integer(authenticator.user_id) if authenticator.respond_to?(:user_id)
+      end
+
+      # The identifier of the user a lookup found for a client's credentials
+      #
+      # X::Client keeps it with memoize, under a lock, for the authenticator it holds, and a frozen client keeps it
+      # too. Any class can include X::Resources::API, so a client that does not memoize keeps it in an instance variable
+      # named for this gem, rather than one named @current_user_id, as an application often names its own, which
+      # would be overwritten.
+      #
+      # @api private
+      # @param client [Object] the client
+      # @return [Integer, nil] the identifier, or nil if none was found for the authenticator the client holds
+      def remembered_user_id(client)
+        return client.memoized(CURRENT_USER_ID) if client.respond_to?(:memoized)
+
+        owner, id = client.instance_variable_get(:@x_resources_current_user_id)
+        id if owner.equal?(authenticator_of(client))
+      end
+
+      # Keep the identifier of the authenticated user, with the authenticator
+      #
+      # A frozen client that does not memoize keeps nothing.
+      #
+      # @api private
+      # @param client [Object] the client
+      # @param id [Integer] the identifier
+      # @return [void]
+      def remember_user_id(client, id)
+        if client.respond_to?(:memoize)
+          client.memoize(CURRENT_USER_ID, id)
+        elsif !client.frozen?
+          client.instance_variable_set(:@x_resources_current_user_id, [authenticator_of(client), id])
+        end
+      end
+
+      # The authenticator of a client, which is replaced whenever its credentials change
+      #
+      # @api private
+      # @param client [Object] the client, which may have an authenticator
+      # @return [Object, nil] the authenticator, or nil if the client has none
+      def authenticator_of(client)
+        client.authenticator if client.respond_to?(:authenticator)
+      end
+
+      # The client for an endpoint that refuses OAuth 1.0a
+      #
+      # A space endpoint refuses it, and so does one that takes app-only authentication alone, as the count of the
+      # full archive does. A client that signs with OAuth 1.0a requests as the app, with a copy that reuses its bearer token, as one
+      # signed in with OAuth 2.0 as a user that holds the app's credentials does. One that holds none, and so has no
+      # app-only client, requests as the user, and the API answers as it answers those credentials: an endpoint that
+      # takes OAuth 2.0 user authentication answers it, and one that takes app-only authentication alone refuses it
+      # with 403 Forbidden, which raises X::Forbidden, as any request refused for its credentials does.
+      #
+      # @api private
+      # @param client [Object] the client
+      # @return [Object] the client's app-only client, which reuses its bearer token, or the client itself
+      def app_client(client)
+        client.respond_to?(:app_only) ? client.app_only : client
+      rescue UnsupportedOperation
+        client
+      end
+
+      # Check whether a value identifies a resource rather than naming one
+      #
+      # An Integer is an identifier and a String is a name, such as a username, so that an
+      # account whose username is all digits is looked up as the name it is.
+      #
+      # @api private
+      # @param value [Resource, String, Integer] a resource, an identifier, or a username
+      # @return [Boolean] true if the value is a resource or an Integer identifier
+      def id?(value)
+        value.is_a?(Resource) || value.instance_of?(Integer)
+      end
+
+      # Read a value of the data of the response to a write
+      #
+      # It is such a value as whether a user is now followed.
+      #
+      # @api private
+      # @param body [Hash, nil] the parsed body of the response
+      # @param key [String] the key of the value in the data
+      # @return [Object, nil] the value, or nil if the response holds no data or no such value
+      # @raise [InvalidAttribute] if the data of the response is not an object
+      # @example Read whether a post was deleted
+      #   X::Resources::Utils.written(body, "deleted")
+      def written(body, key) = Shape.read_object("the data of the response", body.to_h["data"])&.[](key)
+
+      # Read a value of a response, which must be what the API documents it to be
+      #
+      # @api private
+      # @param name [String] what the value is, such as the reader that reads it
+      # @param value [Object] the value the response holds
+      # @yieldparam value [Object] the value
+      # @return [Object] what the block returns
+      # @raise [InvalidAttribute] if the block raises ArgumentError for the value
+      # @example Read the time a post was created
+      #   X::Resources::Utils.read("X::Post#created_at", attrs["created_at"]) { |value| X::Resources::Utils.time(value) }
+      def read(name, value)
+        yield value
+      rescue ArgumentError
+        raise InvalidAttribute, "#{name} cannot be read from #{value.inspect}"
+      end
+
+      # Deconstruct a value into what its readers read, so it matches a hash pattern
+      #
+      # A pattern that asks for every key gets each reader by the name it is declared by, and one that names keys
+      # gets those of them it names, by any name they are read by, as a resource matches a pattern.
+      #
+      # @api private
+      # @param value [Object] the value, which answers each reader
+      # @param keys [Array<Symbol>, nil] the keys the pattern asks for, or nil for every reader
+      # @param names [Array<Symbol>] the readers
+      # @param aliases [Array<Symbol>] the other names some of the readers are read by
+      # @return [Hash{Symbol => Object}] what the readers the pattern asks for read
+      # @example Deconstruct a trend
+      #   X::Resources::Utils.deconstruct(trend, [:name], %i[name post_count], %i[tweet_count]) # => {name: "#ruby"}
+      def deconstruct(value, keys, names, aliases = [])
+        names = (names + aliases) & keys unless keys.nil?
+        names.to_h { |name| [name, value.public_send(name)] }
+      end
+
+      # Parse an ISO 8601 timestamp
+      #
+      # A value that is not a String, such as a number, is not ISO 8601 either, and raises ArgumentError as one.
+      #
+      # @api private
+      # @param value [String, nil] the timestamp
+      # @return [Time, nil] the parsed time or nil if the timestamp is missing
+      # @raise [ArgumentError] if the timestamp is not ISO 8601
+      def time(value)
+        Time.iso8601(value.to_s) unless value.nil?
+      end
+    end
+    private_constant :Utils
+  end
+end

data/lib/x/resources/value_equality.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module X
+  module Resources
+    # Equality of what an API response held that has no identifier, by its class and attributes
+    #
+    # A trend or the usage of a project has no identifier to tell it by, and a rule a post matched is told by its tag
+    # as well as its identifier, so two are equal when they are of the same class and hold the same attributes, and
+    # equal ones share a hash, so that uniq and a Hash key tell them apart. Every attribute counts, so a topic that
+    # trends in two places, with a count of posts in each, is two trends that differ; compare their names to find the
+    # topics two places share, as trends.map(&:name).intersect?(other_trends.map(&:name)).
+    #
+    # Internal to x-resources: the methods it gives X::Trend, X::PersonalizedTrend, X::PostUsage, and X::MatchingRule are
+    # public API, but the module is only how they are shared, and which classes include it can change within 1.x.
+    #
+    # @api semipublic
+    module ValueEquality
+      # Check whether another object holds the same attributes
+      #
+      # @api public
+      # @param other [Object] the other object
+      # @return [Boolean] true if the other is of the same class and holds the same attributes
+      # @example Check whether the trends of the world changed since they were last read, a count included
+      #   X::Trend.at(1, client: client) == trends
+      def ==(other) = other.instance_of?(self.class) && attrs.eql?((_ = other).attrs)
+      alias_method :eql?, :==
+
+      # The hash of the object, which equal objects share
+      #
+      # @api public
+      # @return [Integer] the hash
+      # @example Collect the distinct rules the posts of a stream matched
+      #   posts.flat_map(&:matching_rules).uniq
+      def hash = [self.class, attrs].hash
+    end
+    private_constant :ValueEquality
+  end
+end

data/lib/x/resources/value_marshalling.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module X
+  module Resources
+    # The state Marshal writes and reads of what an API response held that is not a resource
+    #
+    # A trend, the usage of a project, and a rule a post matched hold their attributes alone, so what is written is
+    # those attributes, led by the number of their format, as a resource is written, and what is read is built of
+    # them as the constructor builds it, frozen.
+    #
+    # Internal to x-resources: the methods it gives X::Trend, X::PersonalizedTrend, X::PostUsage, and X::MatchingRule,
+    # marshal_dump, marshal_load, encode_with, and init_with, are public API, but the module is only how they are shared,
+    # and which classes include it can change within 1.x.
+    #
+    # @api semipublic
+    module ValueMarshalling
+      # The number of the format of the state Marshal writes, which every release of 1.x writes
+      #
+      # A later release of 1.x adds to the state only what an earlier one ignores, parts after those it reads and keys of a
+      # Hash it does not read, so that the state one release of 1.x writes is read by every other, earlier or later.
+      #
+      # @api private
+      MARSHAL_FORMAT = 1
+      # The name YAML writes each part of the state under, in the order Marshal writes them
+      # @api private
+      YAML_KEYS = %w[format attrs].freeze
+      private_constant :MARSHAL_FORMAT, :YAML_KEYS
+
+      # The state Marshal writes
+      #
+      # What is written is plain data, led by the number of its format, so that a value written by one release of 1.x
+      # is read by a later one: its attributes, as the API sent them.
+      #
+      # @api public
+      # @return [Array(Integer, Hash{String => Object})] the number of the format, then the attributes
+      # @example Cache the trends of a place
+      #   Rails.cache.write("trends", X::Trend.at(1, client: client))
+      def marshal_dump = [MARSHAL_FORMAT, attrs]
+
+      # Restore a value Marshal read, frozen as the value that was written was
+      #
+      # @api public
+      # @param state [Array] the state Marshal wrote
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read cached trends
+      #   Marshal.load(Marshal.dump(trend)).name
+      def marshal_load(state)
+        format, attrs = state
+        raise UnsupportedFormat, "#{self.class} reads format #{MARSHAL_FORMAT} of Marshal, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)
+
+        restore(attrs)
+      end
+
+      # Write the state Marshal writes as YAML
+      #
+      # YAML would write the instance variables of the value, and read them back into one that is not frozen, so it says
+      # how it is written: each part of the state Marshal writes, under its name.
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML writes the value with
+      # @return [void]
+      # @example Write a value as YAML
+      #   YAML.dump(trend)
+      def encode_with(coder) = YAML_KEYS.zip(marshal_dump) { |key, value| coder[key] = value }
+
+      # Restore a value YAML read, frozen, as Marshal restores one
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML read the value with
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read a value written as YAML
+      #   YAML.unsafe_load(YAML.dump(trend)).name
+      def init_with(coder) = marshal_load(coder.map.values_at(*YAML_KEYS))
+
+      private
+
+      # Build the value of the attributes Marshal read, as its constructor builds it
+      # @api private
+      # @param attrs [Hash{String => Object}] the attributes
+      # @return [void]
+      def restore(attrs) = initialize(attrs) # steep:ignore UnexpectedPositionalArgument
+    end
+    private_constant :ValueMarshalling
+  end
+end

data/lib/x/resources/version.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rubygems/version"
+
+module X
+  # The object layer of the X gem
+  # @api public
+  module Resources
+    # The current version of the x-resources gem
+    # @api public
+    VERSION = "1.0.0"
+
+    # The version as a Gem::Version, which compares one release with another
+    #
+    # VERSION is a String, as a version constant is throughout Ruby, so that what reads it can split it, match it,
+    # or send it wherever a String belongs. This builds the Gem::Version that compares it with another version,
+    # which a String compares by character rather than by segment.
+    #
+    # @api public
+    # @return [Gem::Version] the version
+    # @example Take a path that a later release opened
+    #   X::Resources.gem_version >= Gem::Version.new("1.1")
+    def self.gem_version = Gem::Version.new(VERSION)
+  end
+end

data/lib/x/resources.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "resources/version"
+require_relative "resources/errors"
+require_relative "resources/api"
+require_relative "resources/relationships"
+require_relative "resources/bookmark_folder"
+require_relative "resources/community"
+require_relative "resources/cursor"
+require_relative "resources/direct_message"
+require_relative "resources/list"
+require_relative "resources/media"
+require_relative "resources/place"
+require_relative "resources/poll"
+require_relative "resources/post"
+require_relative "resources/space"
+require_relative "resources/topic"
+require_relative "resources/trend"
+require_relative "resources/personalized_trend"
+require_relative "resources/user"
+require_relative "resources/post_usage"

data/sig/manifest.yaml

@@ -0,0 +1,7 @@
+# The standard libraries the signatures of x-resources refer to, which rbs collection loads for code that depends on it
+#
+# rbs collection reads every library named here as a standard library, so the gems x-resources depends on are left to its
+# gemspec, from which it installs their signatures.
+dependencies:
+  - name: json
+  - name: uri