forest_admin_datasource_intercom 1.49.0

data/lib/forest_admin_datasource_intercom/pagination/cursor_walker.rb

@@ -0,0 +1,123 @@
+module ForestAdminDatasourceIntercom
+  module Pagination
+    # Intercom only paginates by cursor (no jump to page N), so an offset/limit window costs one sequential
+    # request per page. Capped for operator patience (R9), and every truncation is logged, never silent.
+    class CursorWalker
+      # 50 pages of 150 records. Intercom's quota lets these be generous: the
+      # walk is bounded by patience, and by the point past which a list view is
+      # not being read but scraped.
+      MAX_PAGES = 50
+      MAX_RECORDS = 7_500
+
+      def initialize(max_pages: MAX_PAGES, max_records: MAX_RECORDS)
+        @max_pages = max_pages
+        @max_records = max_records
+      end
+
+      # Yields `(per_page, cursor)` and expects a Client::Page back. A nil limit means every record past
+      # the offset, so a cap stopping the walk is known to be a truncation and is logged.
+      def walk(offset:, limit:, &page_source)
+        offset = offset.to_i.clamp(0, nil)
+        limit = limit&.to_i
+        return [] if limit && !limit.positive?
+
+        records = collect(offset, limit, &page_source)
+
+        limit ? (records[offset, limit] || []) : records.drop(offset)
+      end
+
+      private
+
+      # The walk itself: pages are collected until the window is covered, the
+      # source says there is nothing left, or a cap stops it. The slicing is
+      # `walk`'s; this only decides how far to go.
+      def collect(offset, limit)
+        needed = limit && (offset + limit)
+        records = []
+        cursor = nil
+        seen_ids = Set.new
+        seen_cursors = Set.new
+        pages = 0
+
+        loop do
+          page = yield(batch_size(needed, records.size), cursor)
+          records.concat(fresh(page.records, seen_ids))
+          pages += 1
+
+          # The only silent exits: Intercom said there is no page left, or the
+          # window asked for is covered. Everything below hands back less than
+          # was asked for, and says so.
+          break if page.next_cursor.nil?
+          break if needed && records.size >= needed
+          break if cut_short?(page, seen_cursors, pages, records: records.size, window: window_of(offset, limit))
+
+          cursor = page.next_cursor
+        end
+
+        records
+      end
+
+      # Whether the walk is handing back less than it was asked for, and which
+      # of the two reasons it is. Both are logged here rather than by the
+      # caller: a page that looks like the whole answer and is not is the
+      # failure this datasource exists to avoid, so there is no route out of
+      # this walk that is short and quiet.
+      def cut_short?(page, seen_cursors, pages, records:, window:)
+        if stalled?(page, seen_cursors)
+          log_stalled(window: window, pages: pages, collected: records)
+        elsif capped?(pages, records)
+          log_truncation(window: window, pages: pages, collected: records)
+        else
+          return false
+        end
+
+        true
+      end
+
+      # Intercom documents duplicate or missed records when items change mid-walk; duplicates are dropped
+      # here (missed ones cannot be). A record with no id is kept.
+      def fresh(records, seen_ids)
+        records.select { |record| record['id'].nil? || seen_ids.add?(record['id']) }
+      end
+
+      # An empty page with a next cursor, or a cursor already followed: Intercom does neither today, but a
+      # walk driven by a remote value must stop on its own terms -- and the stop is logged as a truncation.
+      def stalled?(page, seen_cursors)
+        page.records.empty? || !seen_cursors.add?(page.next_cursor)
+      end
+
+      def capped?(pages, collected)
+        pages >= @max_pages || collected >= @max_records
+      end
+
+      # Bounded by the record budget left, and by the window still missing when
+      # there is one, so the walk never collects past @max_records. `Client`
+      # bounds it again to what Intercom accepts.
+      def batch_size(needed, collected)
+        budget = @max_records - collected
+        budget = [needed - collected, budget].min if needed
+        Client.bounded_per_page(budget)
+      end
+
+      def log_truncation(window:, pages:, collected:)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] Stopped paginating after #{pages} page(s) / " \
+          "#{collected} record(s) while fetching #{window}; results are truncated. " \
+          'Narrow the filter to reach records past this point.'
+        )
+      end
+
+      def log_stalled(window:, pages:, collected:)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] Stopped paginating after #{pages} page(s) / " \
+          "#{collected} record(s) while fetching #{window}: Intercom advertised a next page this could not " \
+          'follow -- an empty page, or a cursor already read. Results are truncated.'
+        )
+      end
+
+      def window_of(offset, limit)
+        limit ? "offset=#{offset} limit=#{limit}" : "every record past offset=#{offset}"
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/query/caller_zone.rb

@@ -0,0 +1,48 @@
+module ForestAdminDatasourceIntercom
+  module Query
+    # The timezone a filter was written in, and what reading a value in it
+    # costs when the caller names one nothing knows.
+    #
+    # Split from FilterValue for the reason DayBounds was: that class knows
+    # what shape a field expects on the wire, and whether a value carries the
+    # caller's wall clock or the server's is a different question.
+    class CallerZone
+      # Kept stripped rather than only checked stripped: as it came, a
+      # `" Europe/Paris "` passes the blank guard and then fails the zone
+      # lookup, and a day boundary lands an offset away from where the filter
+      # meant it.
+      attr_reader :name
+
+      def initialize(identifier)
+        stripped = identifier.to_s.strip
+        @name = stripped.empty? ? 'UTC' : stripped
+      end
+
+      # A day with no time of day is the caller's day, not the server's: it is
+      # the timezone the filter was written in that says when that day starts.
+      def start_of_day(date)
+        read('the day boundary') { Time.zone.local(date.year, date.month, date.day).to_i }
+      end
+
+      # An offset-less timestamp is the caller's wall clock: FilterFactory writes previous-period bounds as
+      # `%Y-%m-%d %H:%M:%S`, and a midnight shifted by any offset truncates onto another UTC day.
+      def timestamp(value)
+        read('the timestamp') { Time.zone.parse(value).to_i }
+      end
+
+      private
+
+      # Falling back to UTC silently would move a boundary by the offset, which
+      # is the failure a timezone is read for in the first place.
+      def read(what, &block)
+        Time.use_zone(@name, &block)
+      rescue ArgumentError
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] unknown timezone #{@name.inspect}, reading #{what} of a date " \
+          'filter in UTC instead.'
+        )
+        Time.use_zone('UTC', &block)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/query/condition_tree_translator.rb

@@ -0,0 +1,169 @@
+module ForestAdminDatasourceIntercom
+  module Query
+    # Whatever it cannot translate it refuses, naming the field or operator: a dropped condition would serve
+    # an unfiltered page that looks filtered. What each endpoint filters comes from `search_fields.yml`.
+    class ConditionTreeTranslator
+      Branch = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeBranch
+      Leaf = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+
+      AGGREGATORS = { 'and' => 'AND', 'or' => 'OR' }.freeze
+
+      # Intercom nests a search two levels deep and takes fifteen conditions per
+      # group. Both are checked here rather than left to the API: over either,
+      # Intercom answers a 400 whose body names neither the limit nor the part of
+      # the filter that reached it, and an operator reading it has no way of
+      # knowing that their segment plus their scope plus their own filter is what
+      # went over.
+      MAX_DEPTH = 2
+      MAX_GROUP_SIZE = 15
+
+      def self.call(condition_tree, endpoint:, collection:, timezone: nil, attribute_columns: [])
+        return nil if condition_tree.nil?
+
+        new(endpoint: endpoint, collection: collection, timezone: timezone,
+            attribute_columns: attribute_columns).translate(condition_tree)
+      end
+
+      # `attribute_columns` are the columns a workspace's own attributes became,
+      # which no row of the table can name: they are discovered at boot. They
+      # share one refusal, carried by the endpoint, and passing them here is
+      # what lets it be read instead of the generic message.
+      def initialize(endpoint:, collection:, timezone: nil, attribute_columns: [])
+        @endpoint = endpoint
+        @collection = collection
+        @attribute_columns = Array(attribute_columns).map(&:to_s)
+        @value = FilterValue.new(collection: collection, timezone: timezone)
+      end
+
+      def translate(node, depth = 1)
+        case node
+        when Branch then translate_branch(node, depth)
+        when Leaf then translate_leaf(node)
+        else raise UnsupportedOperatorError, "#{@collection} cannot read #{node.class} as a condition."
+        end
+      end
+
+      private
+
+      def translate_branch(branch, depth)
+        conditions = Array(branch.conditions)
+        refuse_empty_branch!(branch) if conditions.empty?
+
+        # Read before the unwrap below, so a branch is refused on the aggregator
+        # it carries rather than on how many conditions it holds.
+        operator = aggregator(branch)
+
+        # A branch holding one condition needs no group of its own. The agent
+        # builds a tree one branch at a time -- a scope, then a segment, then the
+        # operator's own filter -- and the nesting Intercom allows is shallow
+        # enough that a wrapper around nothing is a level worth not spending.
+        return translate(conditions.first, depth) if conditions.size == 1
+
+        refuse_too_deep!(branch, depth) if depth > MAX_DEPTH
+        refuse_too_wide!(branch, conditions.size) if conditions.size > MAX_GROUP_SIZE
+
+        { 'operator' => operator, 'value' => conditions.map { |condition| translate(condition, depth + 1) } }
+      end
+
+      # What reaches this depth is a group inside a group inside a group. The
+      # message names the shape rather than a number, since the tree an operator
+      # can act on is the segment and the scope they wrote, not the one the agent
+      # assembled out of them.
+      def refuse_too_deep!(branch, depth)
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot answer this filter: Intercom nests a search #{MAX_DEPTH} levels deep and this " \
+              "one reaches #{depth}. #{deepening_cause(branch)}"
+      end
+
+      # A group the operator wrote is theirs to flatten. A group a relation
+      # expanded into is not: it is the several records the relation matched,
+      # written one equality each because Intercom takes no membership operator
+      # on a foreign key -- and telling them to flatten a nesting they never
+      # wrote is a refusal they cannot act on.
+      def deepening_cause(branch)
+        field = branch.respond_to?(:relation_field) ? branch.relation_field : nil
+
+        if field.nil?
+          'A group inside a group inside a group is one level too many -- flatten the segment, the scope or the ' \
+            'filter carrying the innermost one.'
+        else
+          "The innermost group is what #{field.inspect} expanded into, one equality per record it matched: narrow " \
+            'that condition until it names a single record, or lift it out of the groups nesting it.'
+        end
+      end
+
+      # Fifteen is reached without trying: a scope, a segment and a filter add up,
+      # and a condition naming several values is expanded into one condition per
+      # value on the way here, Intercom taking no membership operator on these
+      # fields.
+      def refuse_too_wide!(branch, size)
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot answer this filter: Intercom takes #{MAX_GROUP_SIZE} conditions per group and " \
+              "this #{branch.aggregator} carries #{size}. A filter naming several values counts one condition per " \
+              'value here, so narrowing the list, the segment or the scope is what brings it back under the limit.'
+      end
+
+      def aggregator(branch)
+        AGGREGATORS[branch.aggregator.to_s.downcase] ||
+          raise(UnsupportedOperatorError,
+                "#{@collection} cannot read #{branch.aggregator.inspect} as a condition tree aggregator; " \
+                "expected 'And' or 'Or'.")
+      end
+
+      def translate_leaf(leaf)
+        field = @endpoint.field(leaf.field.to_s) || refuse_unfilterable!(leaf.field.to_s)
+        spelling = OperatorTable.intercom_operator(field, leaf.operator) || refuse_operator!(leaf, field)
+
+        { 'field' => field.field, 'operator' => spelling, 'value' => @value.call(leaf, field, spelling) }
+      end
+
+      # A column the endpoint does not filter, and the reason it does not, taken
+      # from the table when it carries one: those reasons are the difference
+      # between "no" and a message an operator can do something with.
+      def refuse_unfilterable!(column)
+        raise UnsupportedOperatorError, "#{@collection} cannot filter #{column.inspect}: #{unfilterable_reason(column)}"
+      end
+
+      def unfilterable_reason(column)
+        return relation_reason(column) if column.include?(':')
+
+        refusal = @endpoint.refusal(column) || attribute_refusal(column)
+        return refusal.reason if refusal
+
+        "#{@endpoint.path} takes no filter on it. Filter on one of: #{@endpoint.filterable_columns.join(", ")}."
+      end
+
+      # A relation reaches the translator as `relation:field`, and it should not:
+      # `Relations#rewrite_relation_conditions` trades every one of them for a
+      # condition on the foreign key before a tree gets this far, or refuses it
+      # by name -- with the relations the collection does declare. So this is
+      # the message for a caller that skipped that pass, and it names what this
+      # endpoint filters rather than a relation nobody resolved.
+      def relation_reason(_column)
+        "#{@endpoint.path} filters columns, not paths through a relation -- those are resolved against the " \
+          'collection they point at before a condition reaches here. Filter on one of: ' \
+          "#{@endpoint.filterable_columns.join(", ")}."
+      end
+
+      # A column the table cannot carry a row for, the workspace having named it:
+      # the endpoint's one refusal for the whole family answers for it.
+      def attribute_refusal(column)
+        @attribute_columns.include?(column) ? @endpoint.attribute_refusal : nil
+      end
+
+      def refuse_operator!(leaf, field)
+        supported = OperatorTable.forest_operators(field)
+
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot filter #{leaf.field.inspect} with #{leaf.operator.inspect}: " \
+              "#{@endpoint.path} answers #{supported.join(", ")} on #{field.field.inspect} and nothing else."
+      end
+
+      def refuse_empty_branch!(branch)
+        raise UnsupportedOperatorError,
+              "#{@collection} was given a #{branch.aggregator} branch carrying no condition, which names no record " \
+              'and no filter.'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/query/day_bounds.rb

@@ -0,0 +1,75 @@
+module ForestAdminDatasourceIntercom
+  module Query
+    # Intercom truncates a date search to the UTC day (measured; the docs promise the workspace timezone):
+    # `> V` starts at the day after V's, `< V` stops before V's day. Each bound is moved one day outward (a `<`
+    # already on a day boundary stays) so Intercom answers the day the filter named: the window is day-granular.
+    # A bound inside a day would be answered for the whole of it, rows outside the window included, so it is
+    # refused -- `future`, `after_x_hours_ago`, a time of day. Except a `<` at the present (`past`, the
+    # `*_to_date` family): widened to midnight it only adds rows dated after now, and a column holding past
+    # instants has none.
+    class DayBounds
+      UTC_DAY = 86_400
+
+      # The one filterable date that can lie ahead of the present.
+      FUTURE_DATED = %w[snoozed_until].freeze
+
+      # The toolkit reads the clock before this does and writes the bound to the second.
+      CLOCK_SLACK = 5
+
+      def initialize(collection:, timezone:, now: -> { Time.now.to_i })
+        @collection = collection
+        @timezone = timezone
+        @now = now
+      end
+
+      def call(seconds, spelling, leaf, field)
+        open_ended = open_ended?(seconds, spelling, field)
+        refuse_inside_a_day!(seconds, leaf) unless midnight?(seconds) || open_ended
+
+        day = seconds - (seconds % UTC_DAY)
+        report_utc_day unless seconds == day || open_ended
+
+        return day - UTC_DAY if spelling == '>'
+
+        seconds == day ? seconds : day + UTC_DAY
+      end
+
+      private
+
+      # The caller's midnight, which is where the toolkit puts the bounds of `today` and the previous periods,
+      # or the UTC one, which is the day Intercom compares by.
+      def midnight?(seconds)
+        return true if (seconds % UTC_DAY).zero?
+
+        Time.use_zone(@timezone) { Time.zone.at(seconds) == Time.zone.at(seconds).beginning_of_day }
+      rescue ArgumentError
+        false
+      end
+
+      def open_ended?(seconds, spelling, field)
+        spelling == '<' && !FUTURE_DATED.include?(field.field) && seconds >= @now.call - CLOCK_SLACK
+      end
+
+      def refuse_inside_a_day!(seconds, leaf)
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot filter #{leaf.field.inspect} on #{Time.at(seconds).utc.iso8601}, a time " \
+              'inside a day: Intercom compares a date by the UTC day, so it would answer the whole day and ' \
+              'return rows outside the window. Filter by day instead -- before or after a date, today, ' \
+              'yesterday, a previous period.'
+      end
+
+      # A bound on the caller's midnight but not the UTC one is widened to the UTC day, whichever side of UTC
+      # the caller sits. Reported once per filter rather than per bound.
+      def report_utc_day
+        return if @reported
+
+        @reported = true
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{@collection} was filtered on a date written in #{@timezone}, and " \
+          'Intercom truncates a date search to the UTC day whatever the workspace timezone says. The rows come ' \
+          'back for the UTC days the window overlaps, which is up to a day wider at each end.'
+        )
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/query/filter_value.rb

@@ -0,0 +1,177 @@
+module ForestAdminDatasourceIntercom
+  module Query
+    # Intercom types its filter values, and a wrongly shaped one fails with `data_invalid`, the same code as an
+    # unsupported operator, so values are converted here rather than by reading error codes.
+    # Long by line count only: most of it is the refusals, one per shape.
+    class FilterValue # rubocop:disable Metrics/ClassLength
+      # What the frontend sends for a Dateonly column, and what a segment written
+      # in Ruby carries: a day with no time of day, which is midnight in the
+      # timezone of whoever wrote the filter rather than in the server's.
+      DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
+
+      # What `Date._parse` has to have found for a string to name a day at all.
+      DATE_PARTS = %i[year mon mday].freeze
+
+      INTEGER = /\A-?\d+\z/
+
+      # Measured on every list, whatever group it stands in: Intercom counts
+      # each value as an element of a composite query and answers a 400 naming
+      # neither the field nor the condition past 15.
+      MAX_LIST_SIZE = 15
+
+      def initialize(collection:, timezone: nil, now: -> { Time.now.to_i })
+        @collection = collection
+        @zone = CallerZone.new(timezone)
+        @day_bounds = DayBounds.new(collection: collection, timezone: @zone.name, now: now)
+      end
+
+      def call(leaf, field, spelling)
+        return list(leaf, field) if OperatorTable.list_operator?(spelling)
+
+        refuse_absence!(leaf, field) if blank?(leaf.value)
+
+        value = scalar(leaf.value, leaf, field)
+        field.type == 'date' ? @day_bounds.call(value, spelling, leaf, field) : value
+      end
+
+      private
+
+      # Dropping the blanks would answer a different question: `not_in [nil,
+      # 'open']` was asked to exclude the records carrying neither and would come
+      # back including them. An empty list is as bad the other way round, being a
+      # filter that matches everything.
+      def list(leaf, field)
+        values = Array(leaf.value)
+        refuse_empty_list!(leaf) if values.empty?
+        refuse_long_list!(leaf, values.size) if values.size > MAX_LIST_SIZE
+        refuse_absence!(leaf, field) if values.any? { |value| blank?(value) }
+
+        values.map { |value| scalar(value, leaf, field) }
+      end
+
+      def scalar(value, leaf, field)
+        case field.type
+        when 'date' then epoch(value, leaf)
+        when 'number' then number(value, leaf)
+        when 'boolean' then boolean(value, leaf)
+        else field.value_map ? mapped(value.to_s, leaf, field) : value.to_s
+        end
+      end
+
+      # A value outside the map is refused rather than sent as typed: Intercom
+      # would compare it against a vocabulary the column never shows.
+      def mapped(value, leaf, field)
+        field.value_map.fetch(value) { refuse_value!(leaf, value, "one of #{field.value_map.keys.join(", ")}") }
+      end
+
+      # Intercom stores and compares its dates as epoch seconds. What arrives
+      # here is an ISO8601 string most of the time -- the frontend sends one, and
+      # so does every interval operator the toolkit rewrites into a pair of
+      # bounds -- but a scope or a segment written in Ruby carries a Time or a
+      # Date, and neither has a timezone of its own.
+      def epoch(value, leaf)
+        case value
+        when DateTime then value.to_time.to_i
+        when Date then @zone.start_of_day(value)
+        when Time then value.to_i
+        when Numeric then seconds(value, leaf)
+        when String then parse(value, leaf)
+        else refuse_value!(leaf, value, 'a date')
+        end
+      end
+
+      # An Infinity or a NaN -- a cast that overflowed above this datasource --
+      # makes `Integer()` raise a FloatDomainError naming a float where the
+      # operator asked for a date, and a Complex a RangeError, which is the
+      # same class one level up. Refused like every other value the field
+      # cannot take, for the reason `number` refuses them too.
+      def seconds(value, leaf)
+        Integer(value)
+      rescue RangeError, TypeError
+        refuse_value!(leaf, value, 'a date')
+      end
+
+      # Refuses a string lacking a year, month or day instead of letting a parser complete it: `Time.zone.parse`
+      # answers today for `last tuesday`, and `Time.parse` fills in the server's date for `12:00`.
+      def parse(value, leaf)
+        return @zone.start_of_day(Date.parse(value)) if DATE_ONLY.match?(value)
+
+        refuse_value!(leaf, value, 'a date') unless dated?(value)
+
+        @zone.timestamp(value)
+      rescue ArgumentError, TypeError
+        refuse_value!(leaf, value, 'a date')
+      end
+
+      def dated?(value)
+        parts = Date._parse(value)
+
+        DATE_PARTS.all? { |part| parts.key?(part) }
+      end
+
+      # The agent casts every Number column with `to_f`, so an integer field
+      # would be filtered with `42.0` -- a form none of its values carry. A float
+      # with nothing after the point travels as the integer it is.
+      #
+      # A cast that overflowed to Infinity, or a NaN, is refused rather than
+      # passed on: the JSON encoder raises on both, a step later, as a 500 naming
+      # nothing the operator can act on.
+      def number(value, leaf)
+        case value
+        when Integer then value
+        when Float then finite(value, leaf)
+        when String then value.match?(INTEGER) ? value.to_i : finite(Float(value, exception: false), leaf)
+        else refuse_value!(leaf, value, 'a number')
+        end
+      end
+
+      def finite(value, leaf)
+        refuse_value!(leaf, value, 'a number') unless value.is_a?(Float) && value.finite?
+
+        value == value.to_i ? value.to_i : value
+      end
+
+      def boolean(value, leaf)
+        case value
+        when true, false then value
+        when 'true' then true
+        when 'false' then false
+        else refuse_value!(leaf, value, 'a true or a false')
+        end
+      end
+
+      def blank?(value) = value.nil? || value.to_s.empty?
+
+      # `present`, `blank` and `missing` are derived by the agent from an
+      # equality, above this datasource, and rewritten into a comparison with an
+      # empty value. Intercom's search matches values and has no spelling for the
+      # absence of one, so the rewritten condition is refused here rather than
+      # sent as a comparison against the empty string -- which Intercom would
+      # answer as if it were a value of its own.
+      def refuse_absence!(leaf, field)
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot filter #{leaf.field.inspect} for absence: Intercom's search matches values " \
+              "and has no operator for the lack of one, so a #{leaf.operator} condition on " \
+              "#{field.field.inspect} cannot be translated. Filter on a value instead."
+      end
+
+      def refuse_empty_list!(leaf)
+        raise UnsupportedOperatorError,
+              "#{@collection} was asked to filter #{leaf.field.inspect} with #{leaf.operator} and an empty list, " \
+              'which names no record and no filter. Pass at least one value.'
+      end
+
+      def refuse_long_list!(leaf, size)
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot filter #{leaf.field.inspect} with #{leaf.operator} and #{size} values: " \
+              "Intercom takes #{MAX_LIST_SIZE} at most in one list. Narrow the list, or split the filter."
+      end
+
+      def refuse_value!(leaf, value, expected)
+        raise UnsupportedOperatorError,
+              "#{@collection} cannot filter #{leaf.field.inspect} with #{value.inspect}: Intercom expects " \
+              "#{expected} on this field."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/query/operator_table.rb

@@ -0,0 +1,54 @@
+module ForestAdminDatasourceIntercom
+  module Query
+    # Read by both the schema and the translator, so a column never advertises an operator the translator
+    # refuses. Which operators an endpoint accepts per field lives in `search_fields.yml`.
+    module OperatorTable
+      Operators = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+
+      EQUALITY = { Operators::EQUAL => '=', Operators::NOT_EQUAL => '!=',
+                   Operators::IN => 'IN', Operators::NOT_IN => 'NIN' }.freeze
+
+      # `contains` and `i_contains` both map to `~`, Intercom's only substring operator. `not_i_contains` is
+      # absent: the toolkit's `Rules` rejects it on a String column (PRD-989).
+      SUBSTRING = { Operators::CONTAINS => '~', Operators::I_CONTAINS => '~',
+                    Operators::NOT_CONTAINS => '!~',
+                    Operators::STARTS_WITH => '^', Operators::ENDS_WITH => '$' }.freeze
+
+      BOUNDS = { Operators::GREATER_THAN => '>', Operators::LESS_THAN => '<' }.freeze
+
+      # Dates publish only the two bounds although both endpoints accept `=`, `!=`, `>=`, `<=` (measured):
+      # declaring `equal` makes the toolkit republish `in`, which its validator refuses (PRD-989). The toolkit
+      # still derives `today`, `past`, `previous_*` and the rest from the two bounds.
+      MAPS = {
+        'string' => EQUALITY,
+        'boolean' => EQUALITY,
+        'number' => EQUALITY.merge(BOUNDS),
+        'text' => EQUALITY.merge(SUBSTRING),
+        'date' => BOUNDS
+      }.freeze
+
+      # The operators that take a list rather than a value, on the wire.
+      LIST_OPERATORS = %w[IN NIN].freeze
+
+      class << self
+        def types = MAPS.keys
+
+        # What the column publishes: the Forest operators whose Intercom spelling
+        # this endpoint accepts on this field, and no other.
+        def forest_operators(field)
+          MAPS.fetch(field.type).select { |_, spelling| field.operators.include?(spelling) }.keys
+        end
+
+        # nil when the endpoint does not accept that operator on that field,
+        # which the translator turns into a refusal naming what it does accept.
+        def intercom_operator(field, forest_operator)
+          spelling = MAPS.fetch(field.type)[forest_operator]
+
+          spelling if spelling && field.operators.include?(spelling)
+        end
+
+        def list_operator?(spelling) = LIST_OPERATORS.include?(spelling)
+      end
+    end
+  end
+end