forest_admin_datasource_intercom 1.49.0

data/lib/forest_admin_datasource_intercom/collections/cursor_collection.rb

@@ -0,0 +1,363 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # Cursor-paginated tier: only a page is in hand, so nothing is filtered, sorted or counted in
+    # memory. Whatever the search DSL cannot express is refused, never served unfiltered.
+    # Long by line count only: half of it is the refusals and their remedies.
+    class CursorCollection < BaseCollection # rubocop:disable Metrics/ClassLength
+      include RecordsById
+
+      # Countable, and exactly: unlike the pages a walk collected, `total_count`
+      # is the whole dataset the filter names.
+      def initialize(datasource, name)
+        super
+        enable_count
+      end
+
+      # One request per id here, so a relation pointing at this tier resolves a
+      # slice at a time and is refused past what a slice may hold -- see
+      # `Relations#target_rows`. The collection that reads its ids in bulk
+      # widens both; see `Contact`.
+      def ids_per_read = max_id_reads
+      def max_resolvable_ids = max_id_reads
+
+      # The read scope spans the whole page rather than any one step of it: the
+      # enrichment and the relation embed below ask Intercom for the same
+      # contacts, from two places that cannot see each other. See
+      # `Client#with_read_scope`.
+      def list(caller, filter, projection)
+        client.with_read_scope do
+          records = fetch_records(caller, filter, server_sort(filter))
+          # Serialized whole and projected afterwards rather than the other way
+          # round: a projection reaching through a relation names no foreign
+          # key, and the key is where the relation is read from.
+          serialized = records.map { |record| serialize(record) }
+          rows = serialized.map { |record| project(record, projection) }
+
+          enrich(records, rows, projection)
+          embed_relations(caller, serialized, rows, projection)
+          rows
+        end
+      end
+
+      # Count only, and never a group: Intercom exposes no aggregate endpoint,
+      # and grouping over the pages a walk happened to collect would look exact
+      # while answering a fraction. Refused here rather than through the
+      # contract's NotImplementedError, which reads as an oversight.
+      def aggregate(caller, filter, aggregation, _limit = nil)
+        refuse_unsupported_aggregation!(aggregation)
+
+        [{ 'group' => {}, 'value' => count_records(caller, filter) }]
+      end
+
+      protected
+
+      def list_endpoint = raise(NotImplementedError, "#{self.class} did not implement list_endpoint")
+      def record_endpoint = list_endpoint
+      def list_key = 'data'
+      def read_params = {}
+
+      # The row of the measured table this collection is filtered through: what
+      # its columns may advertise, and what the translator is allowed to write.
+      def searchable = raise(NotImplementedError, "#{self.class} did not implement searchable")
+
+      def search_endpoint
+        @search_endpoint ||= Query::SearchFields.fetch(searchable)
+      end
+
+      # The column a free-text search is answered on, for a collection whose
+      # endpoint has one. Nil elsewhere, and a search is then refused rather than
+      # answered by a page that ignored it.
+      def search_column = nil
+
+      def serialize(_entity) = raise(NotImplementedError, "#{self.class} did not implement serialize")
+
+      # Hook for what a row needs beyond its own payload. Left empty here: what
+      # it costs is the collection's business, not this base's.
+      def enrich(_records, _rows, _projection); end
+
+      # Bounded per collection rather than by the API maximum: Intercom offers no
+      # field selection, so a collection whose rows carry their whole timeline
+      # pays for it by the page. See Ticket.
+      def max_page_size = Client::MAX_PER_PAGE
+
+      # One page of the collection. A listing for conversations, a search for
+      # tickets -- Intercom exposes no `GET /tickets` at all -- so the endpoint
+      # and its shape belong to the collection, while walking it does not.
+      def read_page(per_page:, cursor:, query: nil, sort: nil)
+        size = [per_page, max_page_size].min
+        # The listing endpoint neither filters nor sorts, and a collection whose
+        # records are only reachable through the search has no listing at all.
+        # Either way what routes the read to the search is a query, so the one
+        # that matches everything stands in for the condition there is none of.
+        query ||= match_all_query if sort || searchable_only?
+
+        if query.nil?
+          client.list_page(list_endpoint, per_page: size, starting_after: cursor,
+                                          params: read_params, list_key: list_key)
+        else
+          client.search_page(search_endpoint.path, query: query, per_page: size, starting_after: cursor,
+                                                   params: read_params, list_key: list_key, sort: sort)
+        end
+      end
+
+      # Operators come from the measured table only, so no column offers a filter the translator
+      # would refuse. Only `/contacts/search` honours a sort; the other search endpoints silently
+      # ignore one, so their columns are never sortable.
+      def add_column(name, type, is_primary_key: false)
+        add_field(name, ColumnSchema.new(column_type: type,
+                                         filter_operators: column_operators(name, is_primary_key),
+                                         is_primary_key: is_primary_key,
+                                         is_read_only: true,
+                                         is_sortable: sortable_column?(name),
+                                         is_groupable: false))
+      end
+
+      def sortable_column?(name)
+        search_endpoint.field(name)&.sortable? == true
+      end
+
+      # The Intercom query standing in for the condition a read has none of.
+      # Two collections need one and for different reasons: Intercom exposes no
+      # `GET /tickets` at all, and an order is applied by the search endpoint
+      # alone. Nil where the listing endpoint answers both, which is where a
+      # sort is reported as ignored rather than dropped.
+      def match_all_query = nil
+
+      def searchable_only? = false
+
+      # Bounded, unlike the tier read whole: one more than a group may hold is
+      # all it takes to know the fan-out will not fit, and reading further would
+      # walk a whole collection to refuse it afterwards.
+      def match_page
+        ForestAdminDatasourceToolkit::Components::Query::Page.new(
+          offset: 0, limit: Query::ConditionTreeTranslator::MAX_GROUP_SIZE + 1
+        )
+      end
+
+      def walker
+        @walker ||= Pagination::CursorWalker.new
+      end
+
+      # How many records a bulk read by id may fetch. A hook rather than the
+      # constant, since the collection that reads its ids in bulk answers far
+      # more of them for the same request count.
+      def max_id_reads = MAX_ID_READS
+
+      # Columns answered by a route of the collection's own rather than by its
+      # search endpoint, with the operators that route takes.
+      def routed_operators = {}
+
+      private
+
+      def column_operators(name, is_primary_key)
+        return [Operators::EQUAL, Operators::IN] if is_primary_key
+        return routed_operators[name] if routed_operators.key?(name)
+
+        field = search_endpoint.field(name)
+
+        field ? Query::OperatorTable.forest_operators(field) : []
+      end
+
+      def fetch_records(caller, filter, sort = nil)
+        ids = id_lookup(filter)
+        # The window is cut out of the ids rather than out of the records they
+        # read: Intercom reads them one request each, so paging after the read
+        # would pay for a whole page to hand back a slice of it -- and page 2 of
+        # a set larger than the cap would come back empty, the records it names
+        # having been dropped by the truncation before the window was applied.
+        if ids
+          # Which is also why an order cannot be honoured on this route: the
+          # window is cut in the order the ids were named, so sorting what comes
+          # back would order a slice picked by something else. Reported rather
+          # than dropped in silence, like every other order this tier cannot
+          # apply -- `server_sort` stayed quiet, having found a column Intercom
+          # does sort.
+          warn_unordered_ids(sort) if sort
+          return records_by_ids(page_window(ids, filter))
+        end
+
+        query = translate(caller, filter)
+        # A condition through a relation the target matched no record with names
+        # no row, and Intercom's DSL cannot say so: the read is skipped rather
+        # than sent as a filter that would come back with everything.
+        return [] if query == NOTHING
+
+        listed_records(filter, query, sort)
+      end
+
+      # The Intercom query a filter comes down to, or nil for a list view, which
+      # walks the listing endpoint instead. The free-text search is folded into
+      # the condition tree rather than added to the translated query: written as
+      # one tree, it is checked against the nesting Intercom allows like every
+      # other condition, instead of adding a level nothing counted.
+      def translate(caller, filter)
+        tree = rewrite_relation_conditions(caller, combined_tree(filter)) do |key, ids, leaf|
+          relation_group(key, ids, leaf)
+        end
+        return NOTHING if tree == NOTHING
+
+        Query::ConditionTreeTranslator.call(tree, endpoint: search_endpoint, collection: name,
+                                                  timezone: timezone_for(caller),
+                                                  attribute_columns: attribute_column_names)
+      end
+
+      # An OR of equalities: the DSL has no IN on foreign keys, and caps a group at 15 conditions,
+      # so a larger match is refused here where the relation can be named. A RelationBranch so it
+      # can be inlined into a same-aggregator parent, saving a nesting level.
+      def relation_group(key, ids, leaf)
+        refuse_fan_out!(leaf, key, ids) if ids.size > Query::ConditionTreeTranslator::MAX_GROUP_SIZE
+        return Leaf.new(key, Operators::EQUAL, ids.first) if ids.size == 1
+
+        RelationBranch.new('Or', ids.map { |id| Leaf.new(key, Operators::EQUAL, id) }, leaf.field)
+      end
+
+      # Inlining a relation group into its parent trades a level of nesting for
+      # width, and Intercom bounds both. Past the conditions a group may hold,
+      # the nested form is the one it answers.
+      def absorb_relation_group?(size)
+        size <= Query::ConditionTreeTranslator::MAX_GROUP_SIZE
+      end
+
+      # A relation this endpoint filters nothing through. It is navigable all the
+      # same -- the read costs nothing, the target being read whole -- and saying
+      # which of the two it is, is the whole point of the message.
+      def relation_key_filterable?(key) = !search_endpoint.field(key).nil?
+
+      def check_relation_filterable!(leaf, relation)
+        key = relation.foreign_key
+        refuse_unfilterable_key!(leaf, key) unless relation_key_filterable?(key)
+      end
+
+      def refuse_unfilterable_key!(leaf, key)
+        raise UnsupportedOperatorError,
+              "#{name} cannot filter #{leaf.field.inspect}: the relation resolves to #{key.inspect}, on " \
+              "which #{search_endpoint.path} takes no filter. The relation is there to be read and " \
+              "navigated; filter on one of: #{search_endpoint.filterable_columns.join(", ")}."
+      end
+
+      def refuse_fan_out!(leaf, key, _ids)
+        # "more than", never a count: the target is read one record past what a
+        # group may hold, so what is known is that it does not fit -- printing
+        # 16 where a workspace holds three thousand would read as a number the
+        # operator could go and narrow by one.
+        raise UnsupportedOperatorError,
+              "#{name} cannot filter #{leaf.field.inspect}: it names more than " \
+              "#{Query::ConditionTreeTranslator::MAX_GROUP_SIZE} records, " \
+              "#{search_endpoint.path} answers #{key.inspect} one value at a time, and Intercom takes " \
+              "#{Query::ConditionTreeTranslator::MAX_GROUP_SIZE} conditions per group. Narrow the condition " \
+              "on the relation, or filter on #{key.inspect} itself."
+      end
+
+      def combined_tree(filter)
+        conditions = [filter&.condition_tree, search_condition(filter)].compact
+        return conditions.first if conditions.size < 2
+
+        ForestAdminDatasourceToolkit::Components::Query::ConditionTree::ConditionTreeFactory.intersect(conditions)
+      end
+
+      # A free-text search reaches Intercom as a condition on the one column its
+      # endpoint matches text on -- per word, not as a substring, which the
+      # README says rather than the interface implying otherwise.
+      def search_condition(filter)
+        return nil if blank_search?(filter)
+
+        refuse_search! if search_column.nil?
+
+        Leaf.new(search_column, Operators::CONTAINS, filter.search.to_s.strip)
+      end
+
+      # The records of this tier carry bodies written by end customers, so every
+      # read of one asks Intercom for plain text (R10). `BaseCollection` reads
+      # this on the way to the record endpoint.
+      def record_read_params = read_params
+
+      def listed_records(filter, query, sort = nil)
+        offset, limit = translate_page(filter&.page)
+
+        walker.walk(offset: offset, limit: limit) do |per_page, cursor|
+          read_page(per_page: per_page, cursor: cursor, query: query, sort: sort)
+        end
+      end
+
+      # A filter with no page asks for every record it matched; the walker reads
+      # that as the nil limit it bounds with its own caps.
+      def translate_page(page)
+        return [0, nil] if page.nil?
+
+        [page.offset.to_i.clamp(0, nil), page_limit(page)]
+      end
+
+      # Exact, and one request: `total_count` counts what the filter names, not
+      # what a page happened to hold. An id lookup counts the records it found,
+      # which is cheaper still.
+      def count_records(caller, filter)
+        ids = id_lookup(filter)
+        return count_by_ids(ids) if ids
+
+        query = translate(caller, filter)
+        return 0 if query == NOTHING
+
+        exact_count(read_page(per_page: 1, cursor: nil, query: query))
+      end
+
+      def refuse_search!
+        raise UnsupportedOperatorError,
+              "#{name} cannot answer a free-text search: #{search_endpoint.path} matches values field by field, " \
+              'and this collection exposes no text column it searches. Filter on a column instead of searching.'
+      end
+
+      # The order Intercom will really apply, written the way the client sends
+      # it -- or nil, and the order the operator asked for is then reported
+      # rather than dropped in silence.
+      #
+      # The ascending primary-key sort the agent injects when a request names
+      # none is neither honoured nor reported: it is not an order anybody asked
+      # for, and `/contacts/search` does not sort on an id anyway.
+      def server_sort(filter)
+        clauses = Array(filter&.sort)
+        return nil if clauses.empty? || default_pk_sort?(clauses)
+
+        honoured = honourable_sort(clauses)
+        warn_ignored_sort(clauses) if honoured.nil?
+        honoured
+      end
+
+      # One clause, on a column the measured table says the endpoint sorts.
+      # Intercom takes a single `{ field, order }` and nothing composite, so a
+      # second clause is not half-honoured: honouring the first alone would
+      # order the page by something the operator did not ask for.
+      def honourable_sort(clauses)
+        return nil unless clauses.size == 1
+
+        clause = clauses.first
+        field = search_endpoint.field(sort_field(clause).to_s)
+        return nil unless field&.sortable?
+
+        { field: field.field, ascending: ascending?(clause) }
+      end
+
+      # Intercom accepts a `sort` on the other two endpoints and ignores it
+      # without a word -- measured -- so an order asked for and not applied has
+      # to be reported here or nowhere.
+      def warn_ignored_sort(clauses)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} was asked to sort on " \
+          "#{clauses.map { |clause| sort_field(clause) }.join(", ")}, which Intercom does not sort this " \
+          'collection on -- and it ignores a sort it refuses without reporting it. The rows come back in the ' \
+          'order the API imposes.'
+        )
+      end
+
+      # `sort` here is the clause `server_sort` found the endpoint does honour,
+      # which is why nothing has reported it yet: it is this route, not the
+      # column, that cannot carry it.
+      def warn_unordered_ids(sort)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} was asked to sort on #{sort[:field].inspect} while reading " \
+          'records by id, which Intercom reads by id and in no order. The rows come back in the order the ids ' \
+          'were named.'
+        )
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/custom_attributes.rb

@@ -0,0 +1,55 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # An attribute whose name is already a column or relation (measured: a contact attribute named `id`) is
+    # skipped with a warning, so relations must be declared first. Dates arrive as epoch seconds.
+    module CustomAttributes
+      private
+
+      def register_attribute_columns
+        @attribute_columns = @attributes.reject { |attribute| collides?(attribute) }
+        @attribute_columns.each { |attribute| add_column(attribute.column_name, attribute.column_type) }
+      end
+
+      def attribute_columns = @attribute_columns || []
+
+      # What the translator needs of them: the names the schema published, so a
+      # filter reaching one is refused with the reason the table carries for
+      # the whole family rather than with the message for a column that is not
+      # in it.
+      def attribute_column_names = attribute_columns.map(&:column_name)
+
+      # What the log calls these, which is the workspace's own vocabulary: a
+      # ticket attribute is declared per ticket type, a contact attribute per
+      # model.
+      def attribute_kind = raise(NotImplementedError, "#{self.class} did not implement attribute_kind")
+
+      def collides?(attribute)
+        return false unless fields.key?(attribute.column_name)
+
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} skips the #{attribute_kind} attribute " \
+          "#{attribute.name.inspect}: a native column or relation already carries the name " \
+          "#{attribute.column_name.inspect}, and overwriting it would show the attribute where the operator " \
+          'expects the record field. Rename it in Intercom to publish it.'
+        )
+        true
+      end
+
+      # Nil rather than absent when the record lacks the attribute: the column exists on every row.
+      def attribute_values(values)
+        held = values.is_a?(Hash) ? values : {}
+
+        attribute_columns.to_h do |attribute|
+          [attribute.column_name, coerce_attribute(held[attribute.name], attribute)]
+        end
+      end
+
+      def coerce_attribute(value, attribute)
+        return nil if value.nil?
+        return stamp(value) if attribute.column_type == 'Date' && value.is_a?(Numeric)
+
+        value
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/fetch_all_collection.rb

@@ -0,0 +1,196 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # Collections Intercom returns whole in one unpaginated response, so filtering, sorting and
+    # counting in memory is exact. The response is cached for `reference_cache_ttl` (0 disables).
+    class FetchAllCollection < BaseCollection # rubocop:disable Metrics/ClassLength
+      # The filters a column may advertise, per column type. Restricted to what
+      # the toolkit can evaluate in memory, since the in-memory pass is the only
+      # pass there is here: an operator with no equivalence makes `match` answer
+      # nil, which `apply` reads as "no match" and would empty the page instead
+      # of filtering it.
+      OPERATOR_CANDIDATES = {
+        'String' => [Operators::EQUAL, Operators::NOT_EQUAL, Operators::IN, Operators::NOT_IN,
+                     Operators::PRESENT, Operators::BLANK, Operators::CONTAINS, Operators::I_CONTAINS,
+                     Operators::NOT_CONTAINS, Operators::STARTS_WITH, Operators::ENDS_WITH],
+        'Boolean' => [Operators::EQUAL, Operators::NOT_EQUAL, Operators::IN, Operators::NOT_IN,
+                      Operators::PRESENT, Operators::BLANK]
+      }.freeze
+
+      # The operators `ConditionTreeLeaf#match` evaluates natively; anything else
+      # needs an equivalence for the column's type to be evaluable at all.
+      IN_MEMORY_OPERATORS = [Operators::IN, Operators::EQUAL, Operators::LESS_THAN, Operators::GREATER_THAN,
+                             Operators::MATCH, Operators::STARTS_WITH, Operators::ENDS_WITH,
+                             Operators::LONGER_THAN, Operators::SHORTER_THAN, Operators::INCLUDES_ALL,
+                             Operators::NOT_IN, Operators::NOT_EQUAL, Operators::NOT_CONTAINS].freeze
+
+      # Candidates are re-checked against the toolkit rather than trusted, so an
+      # equivalence it stops providing takes the filter out of the schema instead
+      # of turning every page using it into an empty one.
+      def self.operators_for(column_type)
+        Array(OPERATOR_CANDIDATES[column_type]).select do |operator|
+          Equivalent.equivalent_tree?(operator, IN_MEMORY_OPERATORS, column_type)
+        end
+      end
+
+      # Countable, unlike the cursor-paginated collections: the count answered
+      # here is taken over every record Intercom holds rather than over the pages
+      # a walk happened to collect.
+      def initialize(datasource, name)
+        super
+        enable_count
+      end
+
+      def list(caller, filter, projection)
+        client.with_read_scope do
+          records = sort_in_memory(filtered_records(caller, filter), filter&.sort)
+          window = page_window(records, filter)
+          rows = window.map { |record| project(record, projection) }
+
+          enrich(window, rows, projection)
+          embed_relations(caller, window, rows, projection)
+          rows
+        end
+      end
+
+      # Relations are embedded first: a group through one (`team:name`) would otherwise read nil
+      # and fold every row into one group.
+      def aggregate(caller, filter, aggregation, limit = nil)
+        client.with_read_scope do
+          records = filtered_records(caller, filter)
+          rows = records.map(&:dup)
+          embed_relations(caller, records, rows, aggregation.projection)
+
+          aggregation.apply(rows, timezone_for(caller), limit)
+                     .map { |row| { 'group' => row[:group], 'value' => row[:value] } }
+        end
+      end
+
+      protected
+
+      # Read-only: an editable column would offer a Save reaching an unimplemented `update`.
+      def add_column(name, type, is_primary_key: false)
+        add_field(name, ColumnSchema.new(column_type: type,
+                                         filter_operators: self.class.operators_for(type),
+                                         is_primary_key: is_primary_key,
+                                         is_read_only: true,
+                                         is_sortable: type != 'Json',
+                                         is_groupable: type != 'Json'))
+      end
+
+      # Hook for what a row needs beyond the endpoint this collection reads --
+      # a name held on the other side of a membership, say. Called with the rows
+      # of the page only, and with the projection, so a column nobody asked for
+      # costs no request.
+      def enrich(_records, _rows, _projection); end
+
+      # Every record of the collection, straight from its endpoint.
+      def fetch_all = raise(NotImplementedError, "#{self.class} did not implement fetch_all")
+
+      def serialize(_entity) = raise(NotImplementedError, "#{self.class} did not implement serialize")
+
+      private
+
+      # The complete dataset, serialized and narrowed to the rows the filter
+      # keeps: what `list` pages and what `aggregate` counts are the same rows.
+      def filtered_records(caller, filter)
+        records = fetch_all.map { |entity| serialize(entity) }
+        tree = filter&.condition_tree
+        return records if tree.nil?
+
+        # A condition through a relation becomes a membership on the foreign key:
+        # this tier filters in memory, where a list of ids costs no more than one
+        # id and none of Intercom's group limits apply -- they bound its search
+        # DSL, which nothing here goes through.
+        tree = rewrite_relation_conditions(caller, tree) { |key, ids, _| Leaf.new(key, Operators::IN, ids) }
+        return [] if tree == NOTHING
+
+        refuse_unevaluable!(tree)
+        tree.apply(records, self, timezone_for(caller))
+      end
+
+      # A condition this collection cannot evaluate is refused rather than
+      # applied. `match` answers nil for an operator with no in-memory
+      # equivalence and `apply` reads that as "no match", so an unevaluable
+      # condition would hand back an empty page that looks like a filter
+      # matching nothing -- indistinguishable, to the operator, from a real
+      # answer. The schema advertises no such operator; a scope, a segment or a
+      # customizer can still send one.
+      def refuse_unevaluable!(tree)
+        offender = nil
+        tree.some_leaf do |leaf|
+          offender = leaf unless evaluable?(leaf)
+          !offender.nil?
+        end
+        return if offender.nil?
+
+        raise UnsupportedOperatorError,
+              "#{name} cannot filter '#{offender.field}' with '#{offender.operator}': it is read whole from " \
+              'Intercom and filtered in memory, which supports only the operators its columns advertise. ' \
+              'Change the condition, or the scope or segment carrying it.'
+      end
+
+      def evaluable?(leaf)
+        schema = fields[leaf.field]
+        schema.is_a?(ColumnSchema) && schema.filter_operators.include?(leaf.operator)
+      end
+
+      # Not `sort`/`Sort#apply`: `sort` is unstable and `<=>` answers nil on nulls, booleans and
+      # mixed types. Ties fall back to Intercom's order.
+      def sort_in_memory(records, sort)
+        clauses = sort_clauses(sort)
+        return records if clauses.empty?
+
+        records.each_with_index.sort do |(left, left_index), (right, right_index)|
+          compare_clauses(left, right, clauses).nonzero? || (left_index <=> right_index)
+        end.map(&:first)
+      end
+
+      # Unsortable clauses are dropped with a warning. They do arrive: `Filter#nest` prefixes the
+      # condition tree but not the sort, so a many-to-many membership gets the target's columns.
+      def sort_clauses(sort)
+        known, unknown = Array(sort).partition { |clause| sortable_column?(sort_field(clause)) }
+        warn_unsortable(unknown) unless unknown.empty?
+
+        known.map { |clause| [sort_field(clause), ascending?(clause) != false] }
+      end
+
+      def sortable_column?(field)
+        schema = fields[field]
+        schema.is_a?(ColumnSchema) && schema.is_sortable
+      end
+
+      def warn_unsortable(clauses)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} was asked to sort on " \
+          "#{clauses.map { |clause| sort_field(clause).inspect }.join(", ")}, which it does not carry as a " \
+          'sortable column; the rows ' \
+          'come back in the order Intercom returned them. A related list through a many-to-many is ordered by the ' \
+          'columns of the collection it travels through, not by those of the collection it reaches.'
+        )
+      end
+
+      def compare_clauses(left, right, clauses)
+        clauses.each do |field, ascending|
+          comparison = compare_values(left[field], right[field])
+          next if comparison.zero?
+
+          return ascending ? comparison : -comparison
+        end
+
+        0
+      end
+
+      # Nulls sort last ascending and first descending, the way a database orders
+      # them; values `<=>` cannot compare -- two booleans, for one -- are
+      # compared through their string form rather than left undefined, which puts
+      # `false` before `true`, again like a database.
+      def compare_values(left, right)
+        return 0 if left.nil? && right.nil?
+        return 1 if left.nil?
+        return -1 if right.nil?
+
+        (left <=> right) || (left.to_s <=> right.to_s)
+      end
+    end
+  end
+end