forest_admin_datasource_intercom 1.49.0

data/lib/forest_admin_datasource_intercom/collections/base_collection.rb

@@ -0,0 +1,161 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # Read-only for now: writes arrive with lots 3 and 4b, actions as plugins, never on a collection. A relation to
+    # a collection not served yet is a schema the agent refuses to boot on.
+    class BaseCollection < ForestAdminDatasourceToolkit::Collection
+      include Relations
+
+      ColumnSchema = ForestAdminDatasourceToolkit::Schema::ColumnSchema
+      Operators = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+      Equivalent = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::ConditionTreeEquivalent
+      Leaf = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+
+      def initialize(datasource, name)
+        super
+        define_schema
+      end
+
+      def client
+        datasource.client
+      end
+
+      # How many ids this collection resolves per `list`, and in total, as a relation target.
+      # Nil means unbounded: the tier read whole answers any number of ids in one request.
+      def ids_per_read = nil
+      def max_resolvable_ids = nil
+
+      protected
+
+      def define_schema = raise(NotImplementedError, "#{self.class} did not implement define_schema")
+
+      # A missing field yields nil rather than an absent key; relation paths are left to
+      # `embed_relations`. No projection means every column, not every serialized key:
+      # some keys are internal plumbing (e.g. the ids behind a membership).
+      def project(record, projection)
+        asked = Array(projection).map(&:to_s)
+        return record.slice(*column_names) if asked.empty?
+
+        asked.reject { |field| field.include?(':') }.to_h { |field| [field, record[field]] }
+      end
+
+      # Whether a projection asks for a column. No projection at all asks for
+      # every declared column, which is how `project` reads it -- an enrichment
+      # guarded on the column being named would leave nil the very column the
+      # projection publishes.
+      def column_asked?(projection, column)
+        asked = Array(projection).map(&:to_s)
+
+        asked.empty? || asked.include?(column)
+      end
+
+      # Whether a projection asks for any of a group of columns, read the same
+      # way: no projection at all asks for every one of them.
+      def any_column_asked?(projection, columns)
+        asked = Array(projection).map(&:to_s)
+
+        asked.empty? || columns.any? { |column| asked.include?(column) }
+      end
+
+      # The window a list view asked for, cut out of records already in hand.
+      #
+      # A filter with no page -- or a page naming no limit -- asks for every
+      # record it matched, and there is nothing to cut. How far the read that
+      # collected them went is a different question, answered by the walker and
+      # its caps.
+      def page_window(records, filter)
+        page = filter&.page
+        return records if page.nil?
+
+        offset = page.offset.to_i.clamp(0, nil)
+        limit = page_limit(page)
+        return records.drop(offset) if limit.nil?
+
+        records[offset, limit] || []
+      end
+
+      # Nil when the page names no limit, and an explicit zero kept as one: the
+      # toolkit's `Page#apply` reads it as an empty window, never as "all".
+      def page_limit(page)
+        page.limit&.to_i&.clamp(0, nil)
+      end
+
+      def column_names
+        @column_names ||= fields.select { |_, field| field.is_a?(ColumnSchema) }.keys
+      end
+
+      # The columns a workspace's own attributes became. None here; the
+      # collections that carry any override this through `CustomAttributes`.
+      # The translator reads them to answer a filter on one with the refusal
+      # covering the family rather than with the message for a column nobody
+      # declared.
+      def attribute_column_names = []
+
+      # The timezone in-memory date comparisons are evaluated in. The caller's,
+      # since that is whose "today" the filter was written against.
+      def timezone_for(caller)
+        caller.respond_to?(:timezone) ? caller.timezone : nil
+      end
+
+      # Ids reach this datasource as strings -- a filter value from Forest, a
+      # segment, a url -- while Intercom types them inconsistently: a team id is
+      # a string, the same team's id inside `admin_ids` is a number. Left as it
+      # comes, an integer id would never match the string the filter carries.
+      def stringify_id(value)
+        value&.to_s
+      end
+
+      # Intercom nests its lists twice -- `{"type": "contact.list", "contacts":
+      # [...]}` -- and answers a null instead of an empty list when there is
+      # nothing.
+      def nested_list(container, key)
+        return [] unless container.is_a?(Hash)
+
+        list = container[key]
+        list.is_a?(Array) ? list : []
+      end
+
+      # Intercom dates travel as epoch seconds; Forest reads a Date column as an
+      # ISO8601 string, and a filter carries one too, so comparing the two is the
+      # ordering itself. UTC deliberately: that is where Intercom stores and
+      # truncates, and rendering a local time here would hide the very shift that
+      # makes a day-granular date filter wrong.
+      def stamp(seconds)
+        return nil unless seconds.is_a?(Numeric) && seconds.positive?
+
+        Time.at(seconds).utc.iso8601
+      end
+
+      # --- Reading a sort clause -------------------------------------------
+      #
+      # Forest hands a clause keyed with symbols or with strings depending on
+      # where it was written, and all three tiers have to read one.
+
+      def primary_key
+        @primary_key ||= fields.find do |_name, field|
+          field.respond_to?(:is_primary_key) && field.is_primary_key
+        end&.first
+      end
+
+      def sort_field(clause) = clause[:field] || clause['field']
+
+      # `key?` rather than `||`: a descending clause carries `false`, which an
+      # `||` fallback reads as "absent" -- so an explicit `?sort=-id` would be
+      # taken for the ascending default the agent injects.
+      def ascending?(clause)
+        clause.key?(:ascending) ? clause[:ascending] : clause['ascending']
+      end
+
+      # The ascending primary-key sort the agent injects when a request names
+      # none. Not an order anybody asked for, so a tier that cannot honour one
+      # stays quiet about this one.
+      def default_pk_sort?(clauses)
+        return false unless clauses.size == 1
+
+        clause = clauses.first
+        return false unless sort_field(clause).to_s == primary_key
+
+        ascending?(clause) != false
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/company/serializer.rb

@@ -0,0 +1,44 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    class Company < OffsetCollection
+      # One Intercom company flattened into the row the schema declares.
+      module Serializer
+        protected
+
+        def serialize(company)
+          attrs = company.is_a?(Hash) ? company : {}
+          plan = attrs['plan'].is_a?(Hash) ? attrs['plan'] : {}
+
+          identity(attrs).merge(
+            'plan_name' => plan['name'],
+            'user_count' => attrs['user_count'],
+            'session_count' => attrs['session_count']
+          ).merge(dates_of(attrs)).merge(attribute_values(attrs['custom_attributes']))
+        end
+
+        private
+
+        def identity(attrs)
+          {
+            'id' => stringify_id(attrs['id']),
+            'company_id' => stringify_id(attrs['company_id']),
+            'name' => attrs['name'],
+            'size' => attrs['size'],
+            'industry' => attrs['industry'],
+            'website' => attrs['website'],
+            'monthly_spend' => attrs['monthly_spend']
+          }
+        end
+
+        def dates_of(attrs)
+          {
+            'created_at' => stamp(attrs['created_at']),
+            'updated_at' => stamp(attrs['updated_at']),
+            'last_request_at' => stamp(attrs['last_request_at']),
+            'remote_created_at' => stamp(attrs['remote_created_at'])
+          }
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/company.rb

@@ -0,0 +1,69 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # No `/companies/search`: `GET /companies` answers exact lookups on `name`, `company_id`,
+    # `tag_id` and `segment_id`. Tag and segment filters wait for those collections (lot 5).
+    class Company < OffsetCollection
+      include Company::Serializer
+      include CustomAttributes
+
+      # The column each lookup is written on, and the query parameter Intercom
+      # answers it under. They happen to share a name; keeping the mapping
+      # explicit is what lets a column be renamed without silently dropping the
+      # lookup.
+      LOOKUPS = { 'name' => 'name', 'company_id' => 'company_id' }.freeze
+
+      def initialize(datasource, attributes: [])
+        @attributes = attributes
+        super(datasource, 'IntercomCompany')
+      end
+
+      protected
+
+      def list_path = 'companies/list'
+      def record_endpoint = 'companies'
+      def lookups = LOOKUPS
+
+      private
+
+      def define_schema
+        add_column('id', 'String', is_primary_key: true)
+        # Intercom's id and the workspace's own are two different things, and an
+        # ops team knows the second one: it is what their billing system calls
+        # the account.
+        add_column('company_id', 'String')
+        add_column('name', 'String')
+        define_profile_columns
+        define_activity_columns
+        # Before the attribute columns, so an attribute whose name lands on the
+        # relation is skipped with a warning rather than taking the boot with
+        # it.
+        add_one_to_many('contacts', foreign_collection: 'IntercomContact', origin_key: 'company_id')
+        register_attribute_columns
+      end
+
+      def define_profile_columns
+        add_column('plan_name', 'String')
+        add_column('size', 'Number')
+        add_column('industry', 'String')
+        add_column('website', 'String')
+        add_column('monthly_spend', 'Number')
+      end
+
+      def define_activity_columns
+        add_column('user_count', 'Number')
+        add_column('session_count', 'Number')
+        add_column('created_at', 'Date')
+        add_column('updated_at', 'Date')
+        add_column('last_request_at', 'Date')
+        # When the account was created in the customer's own system, which is
+        # not when Intercom heard about it.
+        add_column('remote_created_at', 'Date')
+      end
+
+      # Typed from `GET /data_attributes?model=company`, and unfilterable for
+      # the same reason as everything else here: this collection is looked up,
+      # not searched.
+      def attribute_kind = 'company'
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/contact/serializer.rb

@@ -0,0 +1,106 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    class Contact < CursorCollection
+      # One Intercom contact flattened into the row the schema declares.
+      # Nothing here reads a sub-resource: every value comes from the payload
+      # the search already returned.
+      module Serializer
+        protected
+
+        def serialize(contact)
+          attrs = contact.is_a?(Hash) ? contact : {}
+
+          native(attrs)
+            .merge(account_of(attrs['companies']))
+            .merge(location_of(attrs['location']))
+            .merge(attribute_values(attrs['custom_attributes']))
+        end
+
+        private
+
+        def native(attrs)
+          identity(attrs).merge(dates_of(attrs)).merge(flags(attrs)).merge(device_of(attrs))
+        end
+
+        def identity(attrs)
+          {
+            'id' => stringify_id(attrs['id']),
+            'role' => attrs['role'],
+            'name' => attrs['name'],
+            'email' => attrs['email'],
+            # Derived rather than read, and filterable all the same: the search
+            # endpoint carries a field of its own for it, which is what turns
+            # "everyone at this customer" into a filter instead of a wildcard.
+            'email_domain' => domain_of(attrs['email']),
+            'phone' => attrs['phone'],
+            'external_id' => attrs['external_id'],
+            'avatar' => attrs['avatar'],
+            'owner_id' => stringify_id(attrs['owner_id']),
+            'session_count' => attrs['session_count']
+          }
+        end
+
+        def dates_of(attrs)
+          {
+            'created_at' => stamp(attrs['created_at']),
+            'updated_at' => stamp(attrs['updated_at']),
+            'signed_up_at' => stamp(attrs['signed_up_at']),
+            'last_seen_at' => stamp(attrs['last_seen_at']),
+            'last_contacted_at' => stamp(attrs['last_contacted_at']),
+            'last_replied_at' => stamp(attrs['last_replied_at']),
+            'last_email_opened_at' => stamp(attrs['last_email_opened_at']),
+            'last_email_clicked_at' => stamp(attrs['last_email_clicked_at'])
+          }
+        end
+
+        def flags(attrs)
+          {
+            'unsubscribed_from_emails' => attrs['unsubscribed_from_emails'],
+            'has_hard_bounced' => attrs['has_hard_bounced'],
+            'marked_email_as_spam' => attrs['marked_email_as_spam']
+          }
+        end
+
+        def device_of(attrs)
+          {
+            'language_override' => attrs['language_override'],
+            'browser' => attrs['browser'],
+            'browser_language' => attrs['browser_language'],
+            'os' => attrs['os']
+          }
+        end
+
+        # A contact belongs to several accounts, and the row names the first of
+        # them and counts them -- the same reading a conversation gives its
+        # contacts. The whole list is a hop away, on the `company` relation.
+        def account_of(companies)
+          list = nested_list(companies, 'data')
+          first = list.first.is_a?(Hash) ? list.first : {}
+
+          { 'company_id' => stringify_id(first['id']), 'company_count' => account_count(companies, list) }
+        end
+
+        # Intercom caps the accounts it nests on a contact and says how many
+        # there really are, so the count is read rather than measured on the
+        # list -- a contact belonging to twelve accounts must not read as
+        # belonging to the ten the payload had room for.
+        def account_count(companies, list)
+          declared = companies['total_count'] if companies.is_a?(Hash)
+
+          declared.is_a?(Numeric) ? declared : list.size
+        end
+
+        def location_of(location)
+          attrs = location.is_a?(Hash) ? location : {}
+
+          { 'location_country' => attrs['country'], 'location_region' => attrs['region'],
+            'location_city' => attrs['city'] }
+        end
+
+        def domain_of(email)
+          email.to_s[/@(.+)\z/, 1]
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/contact.rb

@@ -0,0 +1,266 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # `/contacts/search` is the only endpoint that honours a sort and answers `id IN`. It filters
+    # no company field, hence the `GET /companies/{id}/contacts` route. A merged contact vanishes
+    # from search and listing. Long by line count only: most of it declares the columns.
+    class Contact < CursorCollection # rubocop:disable Metrics/ClassLength
+      include Contact::Serializer
+      include CustomAttributes
+
+      # `/contacts/search` demands a query, so a read with no condition of its
+      # own -- a list view asking for an order -- sends the least noisy
+      # predicate that matches everything. Every contact has a creation date,
+      # and a bound at the epoch keeps whatever the day-granular truncation does
+      # to it harmless. The same predicate `Ticket` sends, for the same reason.
+      MATCH_EVERY_CONTACT = { 'field' => 'created_at', 'operator' => '>', 'value' => '0' }.freeze
+
+      # `ContactIdentity::CONTACT_CHUNK` must equal IDS_PER_READ, or the enrichment and the
+      # relation send different request bodies and the page pays for both.
+      IDS_PER_READ = Query::FilterValue::MAX_LIST_SIZE
+      MAX_IDS_READ = 300
+
+      def initialize(datasource, attributes: [])
+        @attributes = attributes
+        super(datasource, 'IntercomContact')
+        # Answered on the e-mail address, which is what an ops team types when
+        # they are looking for someone. Per word, not as a substring -- see the
+        # README.
+        enable_search
+      end
+
+      # This endpoint answers `id IN [...]`, so fifteen ids cost one request
+      # rather than fifteen: a relation pointing here resolves a whole page of
+      # rows for a handful of requests, and there is no fan-out to refuse. That
+      # is why `max_resolvable_ids` is nil where the other two tiers bound it --
+      # the read is proportional to the rows already collected, and the walk
+      # that collected them is bounded.
+      def ids_per_read = IDS_PER_READ
+      def max_resolvable_ids = nil
+
+      protected
+
+      def list_endpoint = 'contacts'
+      def searchable = 'contacts'
+      def search_column = 'email'
+      def match_all_query = MATCH_EVERY_CONTACT
+      def max_id_reads = MAX_IDS_READ
+      def routed_operators = { 'company_id' => [Operators::EQUAL] }
+
+      private
+
+      def define_schema
+        add_column('id', 'String', is_primary_key: true)
+        define_identity_columns
+        define_date_columns
+        define_reachability_columns
+        define_device_columns
+        # Before the attribute columns rather than after: a workspace attribute
+        # whose name lands on a relation is then skipped with a warning, the way
+        # one landing on a column already is. Declared after, it would collide
+        # and take the boot with it.
+        define_relations
+        register_attribute_columns
+      end
+
+      def define_identity_columns
+        add_column('role', 'String')
+        add_column('name', 'String')
+        add_column('email', 'String')
+        add_column('email_domain', 'String')
+        add_column('phone', 'String')
+        add_column('external_id', 'String')
+        add_column('avatar', 'String')
+        add_column('owner_id', 'String')
+        add_column('session_count', 'Number')
+        # The first of the accounts the contact belongs to, and how many there
+        # are: the same reading a conversation gives its contacts, and the
+        # foreign key the `company` relation is built on.
+        add_column('company_id', 'String')
+        add_column('company_count', 'Number')
+      end
+
+      def define_date_columns
+        add_column('created_at', 'Date')
+        add_column('updated_at', 'Date')
+        add_column('signed_up_at', 'Date')
+        add_column('last_seen_at', 'Date')
+        add_column('last_contacted_at', 'Date')
+        add_column('last_replied_at', 'Date')
+        add_column('last_email_opened_at', 'Date')
+        add_column('last_email_clicked_at', 'Date')
+      end
+
+      def define_reachability_columns
+        add_column('unsubscribed_from_emails', 'Boolean')
+        add_column('has_hard_bounced', 'Boolean')
+        add_column('marked_email_as_spam', 'Boolean')
+      end
+
+      def define_device_columns
+        add_column('language_override', 'String')
+        add_column('browser', 'String')
+        add_column('browser_language', 'String')
+        add_column('os', 'String')
+        add_column('location_country', 'String')
+        add_column('location_region', 'String')
+        add_column('location_city', 'String')
+      end
+
+      # Typed from `GET /data_attributes?model=contact` rather than guessed from
+      # a payload, and published unfilterable: which operators Intercom answers
+      # on `custom_attributes.{name}` has not been measured, and this package
+      # offers no filter it has not seen work. `api_writable` travels on the
+      # introspected attribute for lot 4b, not on the column -- everything here
+      # is read-only.
+      def attribute_kind = 'contact'
+
+      # The owner is a teammate, read whole in one request, and
+      # `/contacts/search` filters on the key -- so that relation is readable,
+      # navigable and filterable alike.
+      #
+      # The company is none of those last two: the endpoint filters no company
+      # field, so the traversal is refused by name (see `check_relation_filterable!`
+      # on the tier). The two lists are the 360 degrees this lot exists for.
+      def define_relations
+        add_many_to_one('owner', foreign_collection: 'IntercomAdmin', foreign_key: 'owner_id')
+        add_many_to_one('company', foreign_collection: 'IntercomCompany', foreign_key: 'company_id')
+        add_one_to_many('conversations', foreign_collection: 'IntercomConversation', origin_key: 'contact_id')
+        add_one_to_many('tickets', foreign_collection: 'IntercomTicket', origin_key: 'contact_id')
+      end
+
+      # The contacts of an account, which `/contacts/search` cannot answer and
+      # `GET /companies/{id}/contacts` can. Anything else goes the usual way.
+      def fetch_records(caller, filter, sort = nil)
+        company = company_lookup(filter)
+        unless company
+          refuse_narrowed_company!(filter) if narrowed_company?(filter)
+          return super
+        end
+
+        warn_unordered_company_contacts(Array(filter&.sort)) if sort
+        offset, limit = translate_page(filter&.page)
+
+        walker.walk(offset: offset, limit: limit) do |per_page, cursor|
+          read_company_page(company, per_page: per_page, cursor: cursor)
+        end
+      end
+
+      def count_records(caller, filter)
+        company = company_lookup(filter)
+        unless company
+          refuse_narrowed_company!(filter) if narrowed_company?(filter)
+          return super
+        end
+
+        exact_count(read_company_page(company, per_page: 1, cursor: nil))
+      end
+
+      # A bare equality and nothing else: an `and` also carrying a scope names a
+      # narrower set than the account does, and answering it with the account
+      # alone would serve contacts the scope excludes.
+      def company_lookup(filter)
+        tree = filter&.condition_tree
+        return nil unless tree.is_a?(Leaf) && tree.field.to_s == 'company_id'
+        return nil unless tree.operator == Operators::EQUAL && blank_search?(filter)
+
+        tree.value&.to_s
+      end
+
+      # `company_id` plus another condition (e.g. a scope) or a search: `GET /companies/{id}/contacts`
+      # narrows nothing and `/contacts/search` filters no company field, so no request answers both.
+      def narrowed_company?(filter)
+        tree = filter&.condition_tree
+        return false if tree.nil?
+        return false if tree.is_a?(Leaf) && blank_search?(filter)
+
+        tree.some_leaf { |leaf| leaf.field.to_s == 'company_id' && leaf.operator == Operators::EQUAL }
+      end
+
+      def refuse_narrowed_company!(filter)
+        raise UnsupportedOperatorError,
+              "#{name} cannot answer this filter: the contacts of an account are read through " \
+              'GET /companies/{id}/contacts, which returns them whole and narrows nothing, and ' \
+              "#{search_endpoint.path} filters no company field -- so the account and the " \
+              "#{narrowing_cause(filter)} cannot be asked for in one request. Read the account's contacts " \
+              'without it, or filter on a column this collection is searched on: ' \
+              "#{search_endpoint.filterable_columns.join(", ")}."
+      end
+
+      # A scope and a segment are what put a condition next to the account's in
+      # practice, and the operator can act on neither the same way -- so the
+      # message names what it can see rather than guessing.
+      def narrowing_cause(filter)
+        others = []
+        filter.condition_tree.some_leaf do |leaf|
+          others << leaf.field.to_s unless leaf.field.to_s == 'company_id'
+          false
+        end
+
+        causes = []
+        causes << "condition on #{others.uniq.join(", ")}" unless others.empty?
+        causes << "search #{filter.search.to_s.strip.inspect}" unless blank_search?(filter)
+        causes.empty? ? 'condition filtered alongside it' : causes.join(' and the ')
+      end
+
+      # An account Intercom no longer answers for -- deleted, or moved outside
+      # the token's reach between the moment the row was rendered and the
+      # moment its related list was opened -- reads as an account with no
+      # contact rather than as a failed page, the way a record read by its id
+      # already does.
+      def read_company_page(company, per_page:, cursor:)
+        client.list_page("companies/#{Faraday::Utils.escape(company)}/contacts",
+                         per_page: [per_page, max_page_size].min, starting_after: cursor)
+      rescue APIError => e
+        raise unless e.status == 404
+
+        Client::Page.new(records: [], next_cursor: nil, total_count: 0)
+      end
+
+      # One request per fifteen ids instead of one per id: this endpoint answers
+      # `id IN [...]`, which is what lot 1 already reads the contacts of a page
+      # through. A contact that was merged away is simply absent from the
+      # answer -- the row reads as gone, not as a failure.
+      #
+      # Put back in the order the ids were named: the search answers in its own,
+      # and the window was cut on the ids.
+      def records_by_ids(ids)
+        refuse_id_reads!(ids.size, 'list') if ids.size > max_id_reads
+
+        records = ids.each_slice(IDS_PER_READ).flat_map do |chunk|
+          client.search_page(search_endpoint.path, per_page: chunk.size,
+                                                   query: { 'field' => 'id', 'operator' => 'IN',
+                                                            'value' => chunk }).records
+        end
+        position = ids.each_with_index.to_h
+        records.sort_by { |record| position.fetch(record['id'].to_s, ids.size) }
+      end
+
+      # The same searches, each asked for one record: Intercom counts the slice
+      # in `total_count`, so nothing needs reading to be counted.
+      def count_by_ids(ids)
+        refuse_id_reads!(ids.size, 'count') if ids.size > max_id_reads
+
+        ids.each_slice(IDS_PER_READ).sum do |chunk|
+          exact_count(client.search_page(search_endpoint.path, per_page: 1,
+                                                               query: { 'field' => 'id', 'operator' => 'IN',
+                                                                        'value' => chunk }))
+        end
+      end
+
+      # `sort` here is the clause `server_sort` found `/contacts/search` does
+      # honour, which is why nothing has reported it yet: it is this route that
+      # cannot carry the order, not the column. Saying Intercom does not sort
+      # this collection would be wrong -- it is the one collection it sorts --
+      # so this is the counterpart of `warn_unordered_ids`, for the other route
+      # that leaves the search behind.
+      def warn_unordered_company_contacts(clauses)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} was asked to sort on " \
+          "#{clauses.map { |clause| sort_field(clause) }.join(", ")} while reading the contacts of an account, " \
+          'which Intercom answers through GET /companies/{id}/contacts -- a route that takes no order, unlike ' \
+          'the search this collection is otherwise read through. The rows come back in the order the API imposes.'
+        )
+      end
+    end
+  end
+end