forest_admin_datasource_intercom 1.49.0

data/lib/forest_admin_datasource_intercom/collections/contact_identity.rb

@@ -0,0 +1,77 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # Intercom nests only contact ids, so `contact_name` costs one bulk read per page, never per row.
+    module ContactIdentity
+      COLUMNS = %w[contact_name].freeze
+
+      # Must match the `contact` relation's chunking so `Client#with_read_scope` dedups the two
+      # reads into one request (guarded by `ticket_list_budget_spec`).
+      CONTACT_CHUNK = Contact::IDS_PER_READ
+
+      private
+
+      def define_contact_columns
+        add_column('contact_id', 'String')
+        add_column('contact_count', 'Number')
+        add_column('contact_name', 'String')
+      end
+
+      # A group conversation, or a ticket opened for several people, has more
+      # than one contact: the row names the first and counts them, rather than
+      # presenting one of several as the one. The `contact` relation resolves
+      # that same first contact, so the column and the relation cannot disagree;
+      # the others are reached through the contact's own conversations.
+      def contact_columns_for(attrs)
+        ids = nested_list(attrs['contacts'], 'contacts').filter_map { |contact| stringify_id(contact['id']) }
+
+        { 'contact_id' => ids.first, 'contact_count' => ids.size,
+          # Filled by the bulk read below, and left nil when the projection did
+          # not ask for it.
+          'contact_name' => nil }
+      end
+
+      def first_contact_id(record)
+        contact = nested_list((record || {})['contacts'], 'contacts').first
+        contact.is_a?(Hash) ? stringify_id(contact['id']) : nil
+      end
+
+      # The Contacts endpoint as the table spells it, rather than a path written
+      # a second time here: this is the same `/contacts/search` the Contacts
+      # collection reads itself through, and a table that renamed it would
+      # otherwise leave this one behind.
+      def contact_search_path
+        @contact_search_path ||= Query::SearchFields.fetch('contacts').path
+      end
+
+      def embed_contact_identity(records, rows, projection)
+        return unless any_column_asked?(projection, COLUMNS)
+
+        identities = contact_identities(records)
+        records.each_with_index do |record, index|
+          identity = identities[first_contact_id(record)] || {}
+          rows[index]['contact_name'] = identity['name'] if rows[index].key?('contact_name')
+        end
+      end
+
+      # A failure costs the column and nothing else: an identity that could not
+      # be read is not a page that could not be served.
+      def contact_identities(records)
+        ids = records.filter_map { |record| first_contact_id(record) }.uniq
+        return {} if ids.empty?
+
+        ids.each_slice(CONTACT_CHUNK).with_object({}) do |chunk, indexed|
+          page = client.search_page(contact_search_path, per_page: chunk.size,
+                                                         query: { 'field' => 'id', 'operator' => 'IN',
+                                                                  'value' => chunk })
+          page.records.each { |contact| indexed[contact['id'].to_s] = contact }
+        end
+      rescue APIError => e
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} could not read the contacts of this page (HTTP " \
+          "#{e.status || "-"}); the name column is left empty for it."
+        )
+        {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    class Conversation < CursorCollection
+      # One Intercom conversation flattened into the row the schema declares.
+      # Nothing here reads a sub-resource: every value comes from the payload the
+      # listing already returned.
+      module Serializer
+        protected
+
+        def serialize(conversation)
+          attrs = conversation.is_a?(Hash) ? conversation : {}
+
+          native(attrs)
+            .merge(contact_columns_for(attrs))
+            .merge(source_of(attrs['source']))
+            .merge(statistics_of(attrs['statistics']))
+        end
+
+        private
+
+        def native(attrs)
+          company = attrs['company'].is_a?(Hash) ? attrs['company'] : {}
+
+          {
+            'id' => stringify_id(attrs['id']),
+            'title' => attrs['title'],
+            'state' => attrs['state'],
+            'priority' => attrs['priority'],
+            'open' => attrs['open'],
+            'read' => attrs['read'],
+            'created_at' => stamp(attrs['created_at']),
+            'updated_at' => stamp(attrs['updated_at']),
+            'waiting_since' => stamp(attrs['waiting_since']),
+            'snoozed_until' => stamp(attrs['snoozed_until']),
+            'admin_assignee_id' => stringify_id(attrs['admin_assignee_id']),
+            'team_assignee_id' => stringify_id(attrs['team_assignee_id']),
+            'company_id' => stringify_id(company['id']),
+            'company_name' => company['name'],
+            'tag_names' => nested_list(attrs['tags'], 'tags').filter_map { |tag| tag['name'] if tag.is_a?(Hash) },
+            'ai_agent_participated' => attrs['ai_agent_participated']
+          }
+        end
+
+        def source_of(source)
+          attrs = source.is_a?(Hash) ? source : {}
+          author = attrs['author'].is_a?(Hash) ? attrs['author'] : {}
+
+          { 'source_type' => attrs['type'],
+            'source_subject' => attrs['subject'],
+            # Plaintext, because `display_as=plaintext` rides on every read: the
+            # bodies are HTML written by end customers.
+            'source_body' => attrs['body'],
+            'source_author_name' => author['name'],
+            'source_author_email' => author['email'],
+            'source_delivered_as' => attrs['delivered_as'] }
+        end
+
+        # `statistics` is null on a conversation Intercom has computed nothing
+        # for yet; every column then reads as absent rather than as zero.
+        def statistics_of(statistics)
+          attrs = statistics.is_a?(Hash) ? statistics : {}
+
+          { 'closed_at' => stamp(attrs['last_close_at']),
+            'first_closed_at' => stamp(attrs['first_close_at']),
+            'closed_by_id' => stringify_id(attrs['last_closed_by_id']),
+            'first_contact_reply_at' => stamp(attrs['first_contact_reply_at']),
+            'last_contact_reply_at' => stamp(attrs['last_contact_reply_at']),
+            'last_admin_reply_at' => stamp(attrs['last_admin_reply_at']),
+            'reopen_count' => attrs['count_reopens'],
+            'part_count' => attrs['count_conversation_parts'] }
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/conversation/timeline.rb

@@ -0,0 +1,40 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    class Conversation < CursorCollection
+      # What a conversation adds to the shared thread: where its parts live, and
+      # the entry that opens it.
+      #
+      # The opening message lives in `source`, not in the parts -- a timeline
+      # built from the parts alone opens on the first reply and loses what the
+      # customer actually asked.
+      module Timeline
+        # The pseudo type of the opening entry. Not an Intercom part type: it is
+        # the source, and calling it `comment` would make it indistinguishable
+        # from the replies that follow.
+        SOURCE_PART_TYPE = 'conversation_started'.freeze
+
+        private
+
+        # nil rather than an empty list when the payload carries no parts at all:
+        # a listing response has none, and reading that as "this conversation is
+        # empty" is exactly the answer that looks complete without being it.
+        def parts_of(conversation)
+          container = (conversation || {})['conversation_parts']
+          return nil unless container.is_a?(Hash)
+
+          parts = container['conversation_parts']
+          parts.is_a?(Array) ? parts : nil
+        end
+
+        def opening_entry(attrs)
+          source = attrs['source']
+          return nil unless source.is_a?(Hash)
+
+          entry(part_type: SOURCE_PART_TYPE, created_at: attrs['created_at'], author: source['author'],
+                body: source['body'], attachments: source['attachments'])
+            .merge('id' => stringify_id(source['id']))
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_intercom/collections/conversation.rb

@@ -0,0 +1,153 @@
+module ForestAdminDatasourceIntercom
+  module Collections
+    # Records come back under `conversations`, not `data`. Every read sends `display_as=plaintext`: bodies
+    # are customer-written HTML, unsafe to render inside Forest (R10).
+    # Long by line count only: most of it declares the columns, one call each.
+    class Conversation < CursorCollection
+      include ContactIdentity
+      include Conversation::Serializer
+      # The shared thread, then the hooks this collection puts over it.
+      include Collections::Timeline
+      include Conversation::Timeline
+
+      # How many conversations of one page may have their timeline read. The
+      # parts are absent from the listing response -- Intercom returns them only
+      # when retrieving a single conversation -- so a timeline asked for in a
+      # list view costs one request per row. Bounded rather than turned into a
+      # page the operator waits half a minute for; rows past the cap are left at
+      # nil, which reads as "unknown", never as "this conversation is empty".
+      MAX_TIMELINE_READS = 10
+
+      def initialize(datasource)
+        super(datasource, 'IntercomConversation')
+        # The one collection of this datasource Intercom matches text on: `~` on
+        # `source.body`, which is the message that opened the conversation.
+        enable_search
+      end
+
+      protected
+
+      def list_endpoint = 'conversations'
+      def list_key = 'conversations'
+      def searchable = 'conversations'
+      def search_column = 'source_body'
+
+      # Sent on the search too, where Intercom does not document it: the bodies
+      # are HTML written by end customers (R10), and a parameter it ignores costs
+      # a query string while the one it honours saves every filtered row from
+      # coming back as markup.
+      def read_params = { 'display_as' => 'plaintext' }
+
+      # The contact identity and the timeline, each read only when the projection
+      # names it: neither is on the conversation payload, and a page that never
+      # asked for them must not pay for them.
+      def enrich(records, rows, projection)
+        embed_contact_identity(records, rows, projection)
+        embed_timeline(records, rows, projection)
+      end
+
+      private
+
+      def define_schema
+        add_column('id', 'String', is_primary_key: true)
+        add_column('title', 'String')
+        # Left plain strings rather than enums: the values a workspace really
+        # serves are worth measuring before the interface offers them as a
+        # closed list, and nothing filters on them in this lot anyway.
+        add_column('state', 'String')
+        add_column('priority', 'String')
+        add_column('open', 'Boolean')
+        add_column('read', 'Boolean')
+        add_column('created_at', 'Date')
+        add_column('updated_at', 'Date')
+        add_column('waiting_since', 'Date')
+        add_column('snoozed_until', 'Date')
+        define_assignment_columns
+        define_contact_columns
+        define_source_columns
+        define_statistics_columns
+        add_column('tag_names', 'Json')
+        add_column('ai_agent_participated', 'Boolean')
+        add_column('timeline', 'Json')
+        define_relations
+      end
+
+      # /conversations/search filters on all three keys and on a contact id (measured), so `contact:email` is
+      # resolved through /contacts/search. No company relation: Intercom filters no company field here. A group
+      # conversation names its first contact.
+      def define_relations
+        add_many_to_one('admin_assignee', foreign_collection: 'IntercomAdmin', foreign_key: 'admin_assignee_id')
+        add_many_to_one('team_assignee', foreign_collection: 'IntercomTeam', foreign_key: 'team_assignee_id')
+        add_many_to_one('closed_by', foreign_collection: 'IntercomAdmin', foreign_key: 'closed_by_id')
+        add_many_to_one('contact', foreign_collection: 'IntercomContact', foreign_key: 'contact_id')
+      end
+
+      # Who the conversation sits with, and which account it belongs to. The
+      # conversation carries its company as a whole object, so the account name
+      # is free here -- unlike on a ticket, which carries the id alone.
+      def define_assignment_columns
+        add_column('admin_assignee_id', 'String')
+        add_column('team_assignee_id', 'String')
+        add_column('company_id', 'String')
+        add_column('company_name', 'String')
+      end
+
+      # The message that opened the conversation lives in `source`, not in the
+      # parts. A timeline built from the parts alone loses it, which is the one
+      # message nobody opens a conversation without wanting to read.
+      def define_source_columns
+        add_column('source_type', 'String')
+        add_column('source_subject', 'String')
+        add_column('source_body', 'String')
+        add_column('source_author_name', 'String')
+        add_column('source_author_email', 'String')
+        add_column('source_delivered_as', 'String')
+      end
+
+      # Intercom keeps the lifecycle of a conversation in `statistics`, which is
+      # where the closure date and the reply timestamps come from. Flattened onto
+      # the row: they cost nothing, they are exact, and they are what an ops lead
+      # reads a queue for.
+      def define_statistics_columns
+        add_column('closed_at', 'Date')
+        add_column('first_closed_at', 'Date')
+        add_column('closed_by_id', 'String')
+        add_column('first_contact_reply_at', 'Date')
+        add_column('last_contact_reply_at', 'Date')
+        add_column('last_admin_reply_at', 'Date')
+        add_column('reopen_count', 'Number')
+        add_column('part_count', 'Number')
+      end
+
+      # A record read through the record endpoint already carries its parts, so
+      # its timeline is free; one read from the listing does not, and pays a
+      # request. Rows past the cap keep the nil the projection put there.
+      def embed_timeline(records, rows, projection)
+        return unless column_asked?(projection, 'timeline')
+
+        unread = []
+        records.each_with_index do |record, index|
+          if parts_of(record)
+            rows[index]['timeline'] = build_timeline(record)
+          else
+            unread << index
+          end
+        end
+        read = unread.first(MAX_TIMELINE_READS)
+        details = client.fetch_records(list_endpoint, read.map { |index| records[index]['id'] }, params: read_params)
+        read.zip(details) { |index, detail| rows[index]['timeline'] = detail && build_timeline(detail) }
+
+        missing = unread.size - read.size
+        warn_truncated_timelines(missing) if missing.positive?
+      end
+
+      def warn_truncated_timelines(missing)
+        ForestAdminDatasourceIntercom.logger.warn(
+          "[forest_admin_datasource_intercom] #{name} left the timeline of #{missing} row(s) unread: Intercom " \
+          'returns the parts only when retrieving one conversation, so a list view pays a request per row and ' \
+          "this reads at most #{MAX_TIMELINE_READS}. Those rows show no timeline rather than an empty one."
+        )
+      end
+    end
+  end
+end