forest_admin_datasource_intercom 1.49.0

data/lib/forest_admin_datasource_intercom/query/search_fields.yml

@@ -0,0 +1,663 @@
+# The table of (endpoint x field x operator): what Intercom's search endpoints
+# really filter, and with which operators. It is the single source of truth of
+# this datasource's filtering -- the schema derives every column's
+# filter_operators from it, so no collection can advertise a filter the
+# translator would then refuse.
+#
+# `source` is the provenance of a row, and it is not decoration:
+#
+#   measured -- observed against a real workspace, by `forest_admin_intercom_probe`
+#               or during a spike, and recorded here with the date;
+#   spec     -- read off Intercom's documentation and nothing else.
+#
+# The distinction exists because the two disagree. Measured during lot 1:
+# `company_id` is documented on a ticket and refused by `/tickets/search` with
+# `invalid_field`. A `spec` row is therefore a candidate, never a promise, and
+# the probe is what turns it into one. Run it against the customer's workspace
+# and merge the evidence it writes into this table by hand.
+#
+# `type` decides how a column's Forest operators are derived from the Intercom
+# ones, and how a value reaches the wire:
+#
+#   string   -- an exact-match field
+#   text     -- a field Intercom also matches per word (`~`)
+#   date     -- epoch seconds on the wire, truncated to the UTC day on read
+#   boolean, number
+version: 1
+
+endpoints:
+  conversations:
+    path: conversations/search
+    # Nothing has been probed yet: fill this in with the probe's output.
+    measured_at: null
+    fields:
+      # The primary key, and the one column whose Forest operators are not
+      # derived from this table: every collection publishes `equal` and `in` on
+      # its key whatever is written here, the toolkit refusing a collection
+      # whose key carries neither. It has to be declared all the same, or the
+      # schema advertises a filter the translator has no row to write -- which
+      # is what a record detail becomes the moment a permission scope turns
+      # `id equals X` into an `and` the record endpoint cannot answer alone.
+      #
+      # A bare `id equals X` still reads the record endpoint, one request
+      # instead of a search. This row is for the compound case.
+      id:
+        field: id
+        type: string
+        operators: ['=', 'IN']
+        source: spec
+      state:
+        field: state
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      open:
+        field: open
+        type: boolean
+        operators: ['=']
+        source: spec
+      read:
+        field: read
+        type: boolean
+        operators: ['=']
+        source: spec
+      priority:
+        field: priority
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      title:
+        field: title
+        type: text
+        operators: ['=', '!=', '~', '!~', '^', '$']
+        source: spec
+      admin_assignee_id:
+        field: admin_assignee_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      team_assignee_id:
+        field: team_assignee_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      source_type:
+        field: source.type
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      source_delivered_as:
+        field: source.delivered_as
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      source_subject:
+        field: source.subject
+        type: text
+        operators: ['=', '!=', '~', '!~', '^', '$']
+        source: spec
+      # The full-text search of the collection: Intercom matches `~` per word,
+      # not as a substring, which the README states rather than the interface
+      # implying otherwise.
+      source_body:
+        field: source.body
+        type: text
+        operators: ['~', '!~']
+        source: spec
+      source_author_email:
+        field: source.author.email
+        type: text
+        operators: ['=', '!=', '~', '!~', '^', '$']
+        source: spec
+      # The date operators are measured, and they are not the same on every
+      # endpoint: `/contacts/search` refuses `>=`, `<=` and `!=` where this one
+      # accepts them (25 August 2026, API 2.16). Whatever this table allows, a
+      # Date column publishes the two bounds alone -- see the translator.
+      created_at:
+        field: created_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: measured
+      updated_at:
+        field: updated_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: measured
+      waiting_since:
+        field: waiting_since
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      snoozed_until:
+        field: snoozed_until
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      closed_at:
+        field: statistics.last_close_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      first_closed_at:
+        field: statistics.first_close_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      closed_by_id:
+        field: statistics.last_closed_by_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      first_contact_reply_at:
+        field: statistics.first_contact_reply_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      last_contact_reply_at:
+        field: statistics.last_contact_reply_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      last_admin_reply_at:
+        field: statistics.last_admin_reply_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: spec
+      reopen_count:
+        field: statistics.count_reopens
+        type: number
+        operators: ['=', '!=', '>', '<']
+        source: spec
+      part_count:
+        field: statistics.count_conversation_parts
+        type: number
+        operators: ['=', '!=', '>', '<']
+        source: spec
+      ai_agent_participated:
+        field: ai_agent_participated
+        type: boolean
+        operators: ['=']
+        source: spec
+      # The foreign key of the `contact` relation, and the reason lot 4 could
+      # turn the denormalized contact columns into one: Intercom matches a
+      # conversation against one of the contacts it carries. The column is
+      # singular and the wire field plural on purpose -- the row names its first
+      # contact, the endpoint asks "is this contact one of yours".
+      #
+      # `!=` is deliberately absent: on a field holding a list, "not that
+      # contact" is a question Intercom's DSL does not clearly answer, and the
+      # one thing this table may not do is publish a filter whose meaning is a
+      # guess.
+      contact_id:
+        field: contact_ids
+        type: string
+        operators: ['=']
+        source: measured
+    # Columns this collection publishes and will not filter, with the reason an
+    # operator reads when they try. A column absent from both tables is refused
+    # by name too -- these are the ones whose refusal is permanent and has an
+    # explanation worth giving.
+    refused:
+      tag_names:
+        reason: >-
+          Intercom filters conversations by tag id, and this column holds the
+          tag names. Filtering it would mean resolving a name to an id per
+          request, and a name the workspace renamed would silently match
+          nothing.
+        source: spec
+      company_name:
+        reason: >-
+          The conversation carries its company as an object read from the
+          payload; the search endpoint filters no company field.
+        source: spec
+      company_id:
+        reason: >-
+          The search endpoint filters no company field. Measured on
+          `/tickets/search`, which refuses `company_id` with `invalid_field`
+          although a ticket carries one; the same is assumed here until probed.
+        source: spec
+      timeline:
+        reason: >-
+          Built by the agent from the parts of a conversation, which the search
+          endpoint does not read.
+        source: measured
+      contact_name:
+        reason: >-
+          Read from the Contacts endpoint, not from the conversation. Filter
+          through the `contact` relation, which resolves against
+          `/contacts/search` and rewrites onto the contact id -- or on
+          `source_author_email`, which is on the conversation itself.
+        source: spec
+      contact_count:
+        reason: Counted by the agent from the contacts the payload carries.
+        source: measured
+      source_author_name:
+        reason: >-
+          The endpoint matches the author of the opening message by e-mail
+          alone -- `source.author.email` is a field, `source.author.name` is
+          not. Filter on `source_author_email`.
+        source: spec
+    # What `forest_admin_intercom_probe` enumerates on top of the fields above:
+    # names the documentation mentions, or that an ops team would plausibly
+    # search on. A candidate that turns out to be filterable becomes a field
+    # above -- with a column to expose it on, or with none, in which case it is
+    # a column the next lot may add.
+    candidates:
+      - source.id
+      - source.author.id
+      - source.author.type
+      - source.author.name
+      - statistics.time_to_assignment
+      - statistics.time_to_admin_reply
+      - statistics.time_to_first_close
+      - statistics.median_time_to_reply
+      - statistics.first_assignment_at
+      - statistics.first_admin_reply_at
+      - statistics.last_assignment_at
+      - statistics.count_assignments
+      - conversation_rating.score
+      - conversation_rating.remark
+      - conversation_rating.contact_id
+      - ai_agent.resolution_state
+      - ai_agent.last_answer_type
+      - ai_agent.rating
+      - channel_initiated
+      - tag_ids
+      - teammate_ids
+      - company_id
+      - topics
+
+  tickets:
+    path: tickets/search
+    measured_at: null
+    fields:
+      # The primary key, declared here for the same reason as on conversations:
+      # the schema publishes `equal` and `in` on it whatever this table says,
+      # so a row has to exist for the translator to write. `GET /tickets/{id}`
+      # answers the key on its own; the search answers it in an `and`.
+      id:
+        field: id
+        type: string
+        operators: ['=', 'IN']
+        source: spec
+      open:
+        field: open
+        type: boolean
+        operators: ['=']
+        source: spec
+      category:
+        field: category
+        type: string
+        operators: ['=', '!=']
+        source: spec
+        # A ticket reads its category as a label; the search takes another
+        # word for each (OpenAPI 2.16, "Searching by Category").
+        values:
+          Customer: request
+          Back-office: task
+          Tracker: tracker
+      ticket_type_id:
+        field: ticket_type_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      admin_assignee_id:
+        field: admin_assignee_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      team_assignee_id:
+        field: team_assignee_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      created_at:
+        field: created_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: measured
+      updated_at:
+        field: updated_at
+        type: date
+        operators: ['>', '<', '>=', '<=', '=', '!=']
+        source: measured
+      # The foreign key of the `contact` relation. `spec` rather than
+      # `measured`, and the difference is visible to an operator: it is what
+      # decides whether the contacts of a ticket can be filtered at all, and the
+      # probe has not run on this endpoint. If Intercom refuses it, this row
+      # moves to the refused table and the relation stays navigable without
+      # being filterable -- the way `state` already is.
+      contact_id:
+        field: contact_ids
+        type: string
+        operators: ['=']
+        source: spec
+    refused:
+      company_id:
+        reason: >-
+          Measured during lot 1: `/tickets/search` refuses `company_id` with
+          `invalid_field`, although a ticket carries one. Filtering tickets by
+          account is not something this endpoint does.
+        source: measured
+      closed_at:
+        reason: >-
+          Derived by the agent from the parts of the ticket. The search endpoint
+          filters nothing of the sort, and ignores a sort on it without a word.
+        source: measured
+      closed_by_name:
+        reason: Derived by the agent from the parts of the ticket.
+        source: measured
+      last_reply_at:
+        reason: Derived by the agent from the parts of the ticket.
+        source: measured
+      last_responder_name:
+        reason: Derived by the agent from the parts of the ticket.
+        source: measured
+      last_responder_type:
+        reason: Derived by the agent from the parts of the ticket.
+        source: measured
+      state_label:
+        reason: >-
+          Read off the state object the ticket embeds. Whether the endpoint
+          filters a ticket state at all, and under which name, is one of the
+          probe's questions.
+        source: spec
+      ticket_type_name:
+        reason: >-
+          Read off the type object the ticket embeds. Filter on
+          `ticket_type_id`, which the endpoint does take.
+        source: spec
+      ticket_id:
+        reason: >-
+          The number the support team says out loud, which is not the id the
+          API answers by. The search endpoint carries no field for it. Filter
+          on `id`, which takes the value the url and the record page use.
+        source: spec
+      is_shared:
+        reason: >-
+          Whether the ticket is visible to the customer. On the payload and not
+          in the search DSL; the probe lists it as a candidate.
+        source: spec
+      state_id:
+        reason: >-
+          Read off the state object the ticket embeds. The endpoint takes no
+          filter on a ticket state under any name this table knows, which is
+          what keeps the `state` relation navigable without being filterable.
+          Whether it filters one at all is the probe's second question. Filter
+          on `open` or on `category` meanwhile.
+        source: spec
+      previous_state_id:
+        reason: >-
+          The state the ticket left, read off its payload. Filterable no more
+          than the state it is in, and for the same reason.
+        source: spec
+      contact_name:
+        reason: >-
+          Read from the Contacts endpoint, not from the ticket. Filter through
+          the `contact` relation, which resolves against `/contacts/search` and
+          rewrites onto `contact_ids`.
+        source: spec
+      contact_count:
+        reason: Counted by the agent from the contacts the payload carries.
+        source: spec
+      part_count:
+        reason: Counted by the agent from the parts the payload carries.
+        source: measured
+      timeline:
+        reason: >-
+          Built by the agent from the parts of the ticket, which the search
+          endpoint does not read. Filter on `last_reply_at` or on the state
+          instead.
+        source: measured
+    # R7, and it is a product decision rather than an implementation choice: a
+    # ticket attribute is filtered as `ticket_attribute.{id}`, and a same-named
+    # attribute carries a different id per ticket type (measured:
+    # `_default_title_` is 14162161 on one type and 14162165 on another). One
+    # union column cannot know which id a row's type uses, so filtering it
+    # server-side would take one collection per ticket type -- more collections
+    # in the interface, and a schema that changes shape when the customer adds a
+    # type. Until the customer says that trade is worth it, the attributes stay
+    # display-only, as lot 1 published them.
+    ticket_attributes:
+      filterable: false
+      reason: >-
+        An Intercom ticket attribute is filtered through an id that differs from
+        one ticket type to the next, so a column showing the attribute of every
+        type at once cannot say which id to filter on. Filter on the ticket type
+        and a native field instead.
+      source: measured
+
+    candidates:
+      - ticket_id
+      - state
+      - ticket_state.category
+      - ticket_state.id
+      - state_id
+      - is_shared
+      - previous_state_id
+      - company_ids
+      - source.author.email
+      - source.subject
+      - source.body
+      - title
+      - description
+
+  # The one endpoint of the whole API that sorts. `sortable: true` is what a
+  # column reads to publish `isSortable`, and it appears nowhere else in this
+  # file on purpose: `/conversations/search` accepts a `sort` and ignores it
+  # without a word (measured), so a row that stayed silent there would be a
+  # column promising an order Intercom never applies.
+  #
+  # The set is deliberately narrower than what the documentation implies. It
+  # says the results may be sorted by any attribute; nothing has been measured,
+  # and a sort Intercom refuses is a list view that fails rather than one that
+  # comes back unordered. These are the fields an ops team orders a contact list
+  # by, and the probe is what may widen the set.
+  contacts:
+    path: contacts/search
+    measured_at: null
+    fields:
+      # Measured rather than taken from the documentation: lot 1 reads the
+      # contacts of a page through `id IN [...]` on this endpoint, which is the
+      # membership operator every other field refuses.
+      id:
+        field: id
+        type: string
+        operators: ['=', 'IN']
+        source: measured
+      role:
+        field: role
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      name:
+        field: name
+        type: text
+        operators: ['=', '!=', '~', '!~', '^', '$']
+        source: spec
+        sortable: true
+      email:
+        field: email
+        type: text
+        operators: ['=', '!=', '~', '!~', '^', '$']
+        source: spec
+        sortable: true
+      # Derived by the agent from the address, and filtered by Intercom all the
+      # same: the endpoint carries a field of its own for it, which is what
+      # makes "everyone at this customer" a filter rather than a wildcard.
+      email_domain:
+        field: email_domain
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      phone:
+        field: phone
+        type: text
+        operators: ['=', '!=', '~', '!~', '^', '$']
+        source: spec
+      external_id:
+        field: external_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      owner_id:
+        field: owner_id
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      # Measured on 25 August 2026, API 2.16, and this is the asymmetry the
+      # per-endpoint table exists for: `/conversations/search` and
+      # `/tickets/search` accept `>=`, `<=` and `!=` on a date where this
+      # endpoint answers `data_invalid`. `IN` is refused on a date everywhere.
+      #
+      # Nothing is lost that an operator can see: a Date column publishes the
+      # two bounds alone whatever this table allows -- see the operator table --
+      # and the toolkit derives `before`, `after`, `today` and the whole
+      # `previous_*` family from them.
+      created_at:
+        field: created_at
+        type: date
+        operators: ['>', '<']
+        source: measured
+        sortable: true
+      updated_at:
+        field: updated_at
+        type: date
+        operators: ['>', '<']
+        source: measured
+        sortable: true
+      signed_up_at:
+        field: signed_up_at
+        type: date
+        operators: ['>', '<']
+        source: spec
+        sortable: true
+      last_seen_at:
+        field: last_seen_at
+        type: date
+        operators: ['>', '<']
+        source: spec
+        sortable: true
+      last_contacted_at:
+        field: last_contacted_at
+        type: date
+        operators: ['>', '<']
+        source: spec
+        sortable: true
+      last_replied_at:
+        field: last_replied_at
+        type: date
+        operators: ['>', '<']
+        source: spec
+        sortable: true
+      last_email_opened_at:
+        field: last_email_opened_at
+        type: date
+        operators: ['>', '<']
+        source: spec
+      last_email_clicked_at:
+        field: last_email_clicked_at
+        type: date
+        operators: ['>', '<']
+        source: spec
+      unsubscribed_from_emails:
+        field: unsubscribed_from_emails
+        type: boolean
+        operators: ['=']
+        source: spec
+      has_hard_bounced:
+        field: has_hard_bounced
+        type: boolean
+        operators: ['=']
+        source: spec
+      marked_email_as_spam:
+        field: marked_email_as_spam
+        type: boolean
+        operators: ['=']
+        source: spec
+      language_override:
+        field: language_override
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      browser:
+        field: browser
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      browser_language:
+        field: browser_language
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      os:
+        field: os
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      location_country:
+        field: location.country
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      location_region:
+        field: location.region
+        type: string
+        operators: ['=', '!=']
+        source: spec
+      location_city:
+        field: location.city
+        type: string
+        operators: ['=', '!=']
+        source: spec
+    refused:
+      avatar:
+        reason: >-
+          The url of the contact's picture. Nothing filters an image, and
+          Intercom's search does not carry the field.
+        source: spec
+      company_id:
+        reason: >-
+          The first of the companies the contact belongs to, read off the
+          payload. `/contacts/search` filters no company field, so a company
+          list is reached from the company side -- open the company and read
+          its contacts.
+        source: spec
+      company_count:
+        reason: Counted by the agent from the companies the payload carries.
+        source: spec
+      session_count:
+        reason: >-
+          On the contact payload and not in the search DSL. Filter on
+          `last_seen_at` instead, which the endpoint does take.
+        source: spec
+    # Contact custom attributes are filtered as `custom_attributes.{name}` --
+    # by name, unlike a ticket attribute, which carries a different id per
+    # ticket type. So the obstacle is not R7 here, it is measurement: the
+    # operator set Intercom answers on a custom attribute of each data type has
+    # not been probed, and this package does not publish a filter it has not
+    # seen work. They ship typed and display-only, and the probe is what turns
+    # that around.
+    custom_attributes:
+      filterable: false
+      reason: >-
+        Contact custom attributes are published for reading only: which
+        operators Intercom answers on `custom_attributes.{name}` has not been
+        measured on a real workspace, and this datasource does not offer a
+        filter it has not seen work. Filter on a native field instead.
+      source: spec
+    candidates:
+      - tag_ids
+      - segment_id
+      - company_id
+      - companies.id
+      - companies.name
+      - android_app_name
+      - android_last_seen_at
+      - ios_app_name
+      - ios_last_seen_at
+      - utm_source
+      - utm_campaign
+      - utm_medium
+      - referrer
+      - session_count