forest_admin_datasource_pylon 1.41.0

data/lib/forest_admin_datasource_pylon/collections/issue/messages_embedder.rb

@@ -0,0 +1,89 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Issue < BaseCollection
+      # The conversation of an issue, embedded as a structured array column the
+      # way the Zendesk datasource embeds a ticket's comments.
+      #
+      # Pylon has no way to read the threads of several issues at once, so the
+      # thread costs one request per row — against an endpoint allowing 20 per
+      # minute. The fan-out is therefore bounded like the primary-key lookups of
+      # this collection: truncated with a warning rather than turned into a rate
+      # limit error halfway through the page. A relation the projection does not
+      # ask for costs no request at all.
+      module MessagesEmbedder
+        include RecordSerialization
+
+        private
+
+        # The thread is read only when the projection names it. A nil projection
+        # — what a count or an export goes through — asks for the record as
+        # Pylon returns it, and embeds nothing, exactly like RelationEmbedder:
+        # spending one request per row on a path that never asked for the
+        # conversation is the very fan-out MAX_MESSAGE_EMBEDS exists to bound.
+        def want_messages?(projection)
+          Array(projection).map(&:to_s).any? { |p| p == 'messages' || p.start_with?('messages:') }
+        end
+
+        # A row past the cap, and a row whose thread failed to be read, are left
+        # at nil: "unknown", never the empty list, which would read as "this
+        # issue has no message" — the kind of answer that looks complete without
+        # being it.
+        def embed_messages(records, rows)
+          embedded = rows.first(MAX_MESSAGE_EMBEDS)
+          warn_truncated_threads(rows.size) if rows.size > embedded.size
+
+          embedded.each_with_index do |row, index|
+            messages = datasource.client.fetch_issue_messages(records[index]['id'])
+            row['messages'] = messages&.map { |message| serialize_message(message) }
+          end
+        end
+
+        def serialize_message(message)
+          attrs = message.is_a?(Hash) ? message : {}
+
+          {
+            'id' => attrs['id'],
+            'body_html' => attrs['message_html'],
+            'is_private' => attrs['is_private'],
+            'source' => attrs['source'],
+            'thread_id' => attrs['thread_id'],
+            'file_urls' => attrs['file_urls'],
+            'created_at' => attrs['timestamp']
+          }.merge(flatten_author(attrs['author']))
+        end
+
+        # Pylon nests the author's contact and user sides side by side, both
+        # optional and with nothing telling them apart: a message written by an
+        # agent carries `user`, one written by a customer carries `contact`. Both
+        # ids are kept, so a message stays traceable to the PylonContact or
+        # PylonUser record it came from, and the email is taken from whichever
+        # side is there.
+        def flatten_author(author)
+          attrs   = author.is_a?(Hash) ? author : {}
+          contact = attrs['contact']
+          user    = attrs['user']
+
+          {
+            'author_name' => attrs['name'],
+            'author_avatar_url' => attrs['avatar_url'],
+            'author_email' => nested_email(contact) || nested_email(user),
+            'author_contact_id' => nested_id(contact),
+            'author_user_id' => nested_id(user)
+          }
+        end
+
+        def nested_email(value)
+          value['email'] if value.is_a?(Hash)
+        end
+
+        def warn_truncated_threads(asked)
+          ForestAdminDatasourcePylon.logger.warn(
+            "[forest_admin_datasource_pylon] Asked for the message thread of #{asked} issues, reading the first " \
+            "#{MAX_MESSAGE_EMBEDS}: one request per issue, each carrying a whole conversation. " \
+            'Narrow the selection, or take the thread out of the projection, to reach the records past this point.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/issue/schema_definition.rb

@@ -0,0 +1,122 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Issue < BaseCollection
+      # A column is writable when `POST /issues` or `PATCH /issues/{id}` accepts
+      # it, the two directions being told apart by `Issue::CREATE_ONLY` and
+      # `Issue::UPDATE_ONLY`; everything Pylon computes stays read-only. No
+      # column is sortable, `/issues/search` exposing no sort parameter at all:
+      # results always come back ordered by `created_at` descending, so
+      # advertising a sortable column would let the UI ask for an order the API
+      # cannot honour.
+      #
+      # Filter operators are not chosen here: they come from
+      # `ApiFilters::API_FILTERS`, which mirrors the allow-list of the API. A
+      # column missing from that table gets no operator, so the UI offers no
+      # filter of this collection's own that Pylon would refuse — the absence
+      # family the agent derives above the datasource being the exception
+      # `Query::OperatorMaps::Table` describes.
+      module SchemaDefinition
+        ColumnSchema    = BaseCollection::ColumnSchema
+        ManyToOneSchema = BaseCollection::ManyToOneSchema
+        Operators       = BaseCollection::Operators
+
+        private
+
+        def define_schema
+          define_identity_fields
+          define_content_fields
+          define_party_fields
+          define_time_fields
+        end
+
+        # The four parties of an issue, each pointing at the collection owning its
+        # shape: the flattened `*_id` columns stay, as the keys the relation is
+        # read through and as the columns the search endpoint filters.
+        #
+        # RelationEmbedder resolves them at read time, in bulk. The reverse sides
+        # are declared by the collections they belong to; `/issues/search`
+        # filters every one of these keys, so they are answered server-side.
+        def define_relations
+          add_field('account', ManyToOneSchema.new(foreign_collection: 'PylonAccount',
+                                                   foreign_key: 'account_id', foreign_key_target: 'id'))
+          add_field('requester', ManyToOneSchema.new(foreign_collection: 'PylonContact',
+                                                     foreign_key: 'requester_id', foreign_key_target: 'id'))
+          add_field('assignee', ManyToOneSchema.new(foreign_collection: 'PylonUser',
+                                                    foreign_key: 'assignee_id', foreign_key_target: 'id'))
+          add_field('team', ManyToOneSchema.new(foreign_collection: 'PylonTeam',
+                                                foreign_key: 'team_id', foreign_key_target: 'id'))
+        end
+
+        def define_identity_fields
+          # Only equal/in: these are the two the primary-key short-circuit can
+          # actually serve through GET /issues/{id}. `id` is not part of the
+          # search allow-list, so it never reaches the translator.
+          add_field('id', ColumnSchema.new(column_type: 'String',
+                                           filter_operators: [Operators::EQUAL, Operators::IN],
+                                           is_primary_key: true, is_groupable: false, is_read_only: true))
+          add_column('number', 'Number')
+          add_column('link', 'String')
+        end
+
+        def define_content_fields
+          add_column('title', 'String', writable: true)
+          # Writable on creation only: it is the first message of the thread,
+          # which `PATCH /issues/{id}` does not carry.
+          add_column('body_html', 'String', writable: true)
+          # Left as String rather than Enum: Pylon ships five built-in states
+          # but organisations define their own on top of them. Writable on an
+          # update only — every issue is created `new`.
+          add_column('state', 'String', writable: true)
+          add_column('type', 'String', writable: true)
+          # Where the issue came from: Pylon sets it, no endpoint takes it.
+          add_column('source', 'String')
+          add_column('tags', 'Json', writable: true)
+          add_column('customer_portal_visible', 'Boolean', writable: true)
+          add_column('author_unverified', 'Boolean', writable: true)
+          add_column('number_of_touches', 'Number')
+          define_thread_field
+        end
+
+        # The conversation, embedded at read time by MessagesEmbedder. Declared
+        # by hand rather than through `add_column`: its type is the shape of one
+        # message, not a primitive.
+        #
+        # Neither filterable nor sortable — `POST /issues/search` covers no
+        # message field, and the thread is not even part of the payload the
+        # search endpoint returns — and not groupable either: `ColumnSchema`
+        # defaults that flag to true, where the `add_column` of the base passes
+        # false for every Pylon column, a thread being both an array and a value
+        # the pages of a cursor walk do not carry.
+        def define_thread_field
+          add_field('messages', ColumnSchema.new(column_type: [Issue::MESSAGE_THREAD_SCHEMA],
+                                                 filter_operators: [], is_groupable: false,
+                                                 is_read_only: true))
+        end
+
+        # Flattened from the nested `{id: …}` objects Pylon returns, and kept as
+        # columns next to the relations they are the keys of: they are what the
+        # search endpoint filters, on this side and on the reverse one.
+        #
+        # Writable, although `GeneratorField` forces a foreign key read-only in
+        # the emitted schema whatever the datasource says, so the detail view has
+        # one editor per key rather than two. What the flag opens is that editor:
+        # the `BelongsTo` reads its own read-only state off the key column, and
+        # the front sends the choice back as the very column named here.
+        def define_party_fields
+          %w[account_id requester_id assignee_id team_id].each do |field|
+            add_column(field, 'String', writable: true)
+          end
+        end
+
+        def define_time_fields
+          %w[first_response_time resolution_time latest_message_time created_at updated_at].each do |field|
+            add_column(field, 'Date')
+          end
+          %w[time_in_status_seconds business_hours_time_in_status_seconds].each do |field|
+            add_column(field, 'Json')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/issue/serializer.rb

@@ -0,0 +1,26 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Issue < BaseCollection
+      module Serializer
+        PARTY_FIELDS = { 'account_id' => 'account', 'requester_id' => 'requester',
+                         'assignee_id' => 'assignee', 'team_id' => 'team' }.freeze
+
+        NATIVE_FIELDS = %w[id number link title body_html state type source tags
+                           customer_portal_visible author_unverified number_of_touches
+                           first_response_time resolution_time latest_message_time
+                           created_at updated_at time_in_status_seconds
+                           business_hours_time_in_status_seconds].freeze
+
+        private
+
+        def serialize(issue)
+          attrs = issue.is_a?(Hash) ? issue : {}
+          record = NATIVE_FIELDS.to_h { |field| [field, attrs[field]] }
+          PARTY_FIELDS.each { |column, source| record[column] = nested_id(attrs[source]) }
+          add_custom_field_values(record, attrs['custom_fields'])
+          record
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/issue.rb

@@ -0,0 +1,128 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Issue < BaseCollection
+      include SchemaDefinition
+      include RecordSerialization
+      include Serializer
+      include RelationEmbedder
+      include MessagesEmbedder
+      include IdLookupReader
+
+      # `/issues/search` exposes no sort parameter, so the allow-list is empty and
+      # every requested order is reported instead of being silently swallowed.
+      # The mechanism stays in place for the collections whose endpoint sorts.
+      PYLON_SORTABLE = {}.freeze
+
+      # A primary-key lookup spends one `GET /issues/{id}` per id, sequentially.
+      # The fan-out is bounded like the cursor walk, and for the same reason:
+      # `RateLimiter` keeps the requests inside the 300 a minute that endpoint
+      # grants, but nothing makes two hundred round-trips fast.
+      #
+      # What it bounds is one page, not the selection behind it: the window is
+      # taken off the ids first, so a selection wider than this is read a page
+      # at a time rather than truncated at its first #{MAX_ID_LOOKUPS}. See
+      # `IdLookupReader`, and the one case that cannot be paged.
+      MAX_ID_LOOKUPS = 20
+
+      # The shape of one message inside the `messages` column. Field names follow
+      # the columns of this collection rather than the payload: Pylon spells them
+      # `message_html` and `timestamp`, which would put two conventions in the
+      # same schema for the operator to reconcile.
+      MESSAGE_THREAD_SCHEMA = {
+        'id' => 'String',
+        'body_html' => 'String',
+        'is_private' => 'Boolean',
+        'source' => 'String',
+        'thread_id' => 'String',
+        'file_urls' => 'Json',
+        'created_at' => 'Date',
+        'author_name' => 'String',
+        'author_email' => 'String',
+        'author_avatar_url' => 'String',
+        'author_contact_id' => 'String',
+        'author_user_id' => 'String'
+      }.freeze
+
+      # One thread is one `GET /issues/{id}/messages`, and a thread is the whole
+      # conversation rather than a page of it. A list view asking for more of
+      # them than this reads the first ones and reports the rest, for the same
+      # reason MAX_ID_LOOKUPS bounds the primary-key fan-out — sequential
+      # round-trips, each carrying an unbounded payload. Lower than
+      # MAX_ID_LOOKUPS because of that payload, not because of the quota: the
+      # endpoint grants 120 requests a minute.
+      MAX_MESSAGE_EMBEDS = 10
+
+      # `body_html` is the first message of the thread, which `POST /issues`
+      # requires and `PATCH /issues/{id}` does not carry; `author_unverified`
+      # qualifies that message and travels with it.
+      CREATE_ONLY = %w[body_html author_unverified].freeze
+
+      # Pylon creates every issue as `new`, of the type it decides, and takes
+      # both on an update only.
+      UPDATE_ONLY = %w[state type].freeze
+
+      def initialize(datasource, custom_fields: [])
+        super(datasource, 'PylonIssue', custom_fields: custom_fields, searchable: true)
+      end
+
+      def list(caller, filter, projection)
+        records = fetch_records(caller, filter)
+        rows = records.map { |record| project(record, projection) }
+        embed_relations(records, rows, projection)
+        embed_messages(records, rows) if want_messages?(projection)
+        rows
+      end
+
+      protected
+
+      def filter_table = ApiFilters
+
+      def create_record(payload) = datasource.client.create_issue(payload)
+      def update_record(id, payload) = datasource.client.update_issue(id, payload)
+      def delete_record(id) = datasource.client.delete_issue(id)
+
+      def create_only_fields = CREATE_ONLY
+      def update_only_fields = UPDATE_ONLY
+
+      # An issue is read through `GET /issues/{id}`, one request per record: a
+      # selection resolved or compared that way spends the write budget twice
+      # over, so it divides the records one pass reaches rather than fitting
+      # beside them.
+      def requests_per_record_read = 1
+
+      # Never past the primary-key fan-out either: a write resolving named ids
+      # through `list` reads them one request apiece, and a resolution the page
+      # cap trimmed would write to a subset of the selection while reporting the
+      # whole of it. The budget is the tighter of the two at today's numbers;
+      # the clamp keeps that true if either moves.
+      def max_resolvable_ids(reads: 0) = [super, MAX_ID_LOOKUPS].min
+
+      def sortable_fields
+        PYLON_SORTABLE
+      end
+
+      def unsortable_warning
+        '[forest_admin_datasource_pylon] PylonIssue cannot honour the requested order; ' \
+          'POST /issues/search always returns issues from the most recent to the oldest.'
+      end
+
+      def search_page(limit:, cursor:, filter:, search_text:)
+        datasource.client.search_issues(limit: limit, cursor: cursor, filter: filter, search_text: search_text)
+      end
+
+      private
+
+      def fetch_records(caller, filter)
+        warn_unsortable(filter&.sort)
+
+        with_resolved_relations(caller, filter) do |query|
+          lookup = extract_id_lookup(query&.condition_tree)
+          next search_records(caller, query) unless lookup
+
+          ensure_searchless_lookup!(query)
+          records_by_id(caller, lookup, query)
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/record_serialization.rb

@@ -0,0 +1,84 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    # The two parts of a Pylon payload every collection reads the same way: the
+    # nested `{ id: ... }` objects it flattens into foreign-key columns, and the
+    # custom fields the organization defined, which are columns of their own.
+    module RecordSerialization
+      private
+
+      def nested_id(value)
+        value['id'] if value.is_a?(Hash)
+      end
+
+      def add_custom_field_values(record, values)
+        custom_fields.each do |cf|
+          entry = values.is_a?(Hash) ? values[cf[:column_name]] : nil
+          record[cf[:column_name]] = coerce_custom_field(custom_field_value(entry), cf[:schema].column_type)
+        end
+      end
+
+      # Pylon spells a custom field as `slug => {"slug": ..., "value": ...}`,
+      # with `"values": [...]` instead of `"value"` for multi-value fields.
+      def custom_field_value(entry)
+        return entry unless entry.is_a?(Hash)
+
+        entry.key?('value') ? entry['value'] : entry['values']
+      end
+
+      # The API reference documents what a custom field *is*, never the form its
+      # value is read back in, so a Number answering `"42"` is not ruled out. A
+      # value that is not already of its column's type is therefore converted --
+      # the in-memory pass of the primary-key short-circuit would otherwise drop
+      # a row on `"42" == 42.0`, comparing a read string with the float
+      # `ConditionTreeParser.cast_to_type` casts the filter to.
+      #
+      # A date stays the string it is: the filter carries an ISO8601 string too,
+      # and comparing two of those is the ordering itself.
+      def coerce_custom_field(value, column_type)
+        return nil if value.nil?
+
+        case column_type
+        when 'Number'  then coerce_number(value)
+        when 'Boolean' then coerce_boolean(value)
+        else                value
+        end
+      end
+
+      # A value already numeric is handed back untouched: `ConditionTreeLeaf#match`
+      # compares with `==` and `Array#include?`, both of which hold across Integer
+      # and Float, so nothing needs widening -- and widening would make an integer
+      # field display the `12.0` it does not hold, where `FilterValue#format_float`
+      # narrows the very same value on the way out. A string is read to the
+      # tightest form for that reason, the two halves agreeing on what an integer
+      # looks like.
+      #
+      # A number that cannot be read reads as absent rather than as zero.
+      #
+      # Integers are parsed as integers rather than reached through a Float: past
+      # 2**53 the intermediate loses the last digits, and `"9007199254740993"`
+      # would be both displayed and compared as ...992. Base 10 is passed
+      # explicitly -- `Integer("012")` is 10, Ruby reading a leading zero as
+      # octal, which would silently renumber every zero-padded value Pylon holds.
+      def coerce_number(value)
+        return value if value.is_a?(Numeric)
+
+        integer = Integer(value, 10, exception: false)
+        return integer unless integer.nil?
+
+        float = Float(value, exception: false)
+        return nil if float.nil?
+
+        float == float.to_i ? float.to_i : float
+      end
+
+      # An empty boolean reads as absent as well: `false` is an answer of its own,
+      # and Pylon gave none.
+      def coerce_boolean(value)
+        return value if [true, false].include?(value)
+        return nil if value.to_s.strip.empty?
+
+        !%w[false 0 no].include?(value.to_s.strip.downcase)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/relation_embedder.rb

@@ -0,0 +1,101 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    # Forest asks for a ManyToOne relation as `relation:field` entries in the
+    # projection and expects the related record nested under the relation name on
+    # every row. Pylon has no join and no include parameter, so the records are
+    # read from the foreign collection — in bulk, from the foreign keys the
+    # serialized records already carry, never one request per row.
+    #
+    # What to embed comes from the schema rather than from a list kept here: a
+    # collection embeds whatever ManyToOne relations it declares, and a relation
+    # the projection does not ask for costs no request at all.
+    module RelationEmbedder
+      ManyToOneSchema = BaseCollection::ManyToOneSchema
+      Projection      = BaseCollection::Projection
+
+      private
+
+      # `records` are the serialized records, carrying the foreign keys `project`
+      # strips off the rows; `rows` are the projected rows, in the same order.
+      def embed_relations(records, rows, projection)
+        # Rebuilt rather than read off the argument: `list` is also called with
+        # a plain array of field names, inside the agent and in the specs, and a
+        # relation read from one of those would go unprojected -- which is the
+        # one shape this must not have.
+        sub_projections = Projection.new(Array(projection).map(&:to_s)).relations
+
+        projected_relations(projection).group_by { |_name, relation| relation.foreign_collection }
+                                       .each do |foreign, group|
+          embed_foreign(foreign, group, records, rows, sub_projections)
+        end
+      end
+
+      # Grouped by foreign collection, so two relations pointing at the same one
+      # are answered by a single read and their ids are deduped together.
+      #
+      # A relation the projection asked for is written on every row, whether or
+      # not it resolved: a null foreign key, and a record the operator can no
+      # longer reach, both read as "no related record" rather than as a row
+      # missing the field.
+      #
+      # The nested record is cut down to the fields the projection named, the
+      # way `project` cuts the row it sits on. The foreign collection hands back
+      # everything it holds -- Pylon has no join, so a related record is read
+      # through its own endpoint, which takes no field list -- and nesting that
+      # whole record would answer `account:name` with every column of the
+      # account, the ones the caller's permissions had the agent take out of the
+      # projection included.
+      #
+      # The primary key is added back rather than assumed: the route's
+      # projection carries it, but the nested record is what the serializer
+      # reads an `included` resource's id off, and a caller inside the agent may
+      # well have projected without it.
+      def embed_foreign(foreign_collection, relations, records, rows, sub_projections)
+        ids     = foreign_ids(records, relations)
+        foreign = datasource.get_collection(foreign_collection)
+        indexed = ids.empty? ? {} : foreign.records_indexed_by_id(ids)
+        relations.each do |name, relation|
+          wanted = projected_fields(sub_projections[name], foreign)
+          rows.each_with_index do |row, index|
+            related = indexed[records[index][relation.foreign_key]]
+            row[name] = wanted ? wanted.re_project(related) : related
+          end
+        end
+      end
+
+      # The fields of the relation, plus the primary key of the collection it
+      # points at. The key is unioned in by hand rather than through
+      # `Projection#with_pks`, which also walks the relations of the projection
+      # it is given and dereferences their schema without a nil guard: a
+      # projection reaching through a relation this collection does not declare
+      # would raise there, where it used to be ignored. Only the immediate
+      # foreign key is wanted here, so only that is added.
+      def projected_fields(sub_projection, foreign)
+        return nil if sub_projection.nil?
+
+        Projection.new(sub_projection | ForestAdminDatasourceToolkit::Utils::Schema.primary_keys(foreign))
+      end
+
+      # A foreign key Pylon left empty asks for nothing — a blank one no more
+      # than a null one, and it would reach the `in` filter of the read below,
+      # which refuses a blank inside a list and would fail the whole page over
+      # one malformed key. The same id is asked for once however many rows point
+      # at it.
+      def foreign_ids(records, relations)
+        keys = relations.map { |_name, relation| relation.foreign_key }
+        records.flat_map { |record| keys.map { |key| record[key] } }
+               .reject { |id| id.nil? || id.to_s.empty? }
+               .uniq
+      end
+
+      # `account:name` asks for the `account` relation; a projected column, and a
+      # relation that is not a ManyToOne, name no field to embed.
+      def projected_relations(projection)
+        Array(projection).map { |field| field.to_s.split(':').first }.uniq.filter_map do |name|
+          relation = schema[:fields][name]
+          [name, relation] if relation.is_a?(ManyToOneSchema)
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/team.rb

@@ -0,0 +1,49 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Team < FetchAllCollection
+      def initialize(datasource)
+        super(datasource, 'PylonTeam')
+      end
+
+      protected
+
+      # Pylon exposes no DELETE on a team, so that hook is left to refuse.
+      def create_record(payload) = datasource.client.create_team(payload)
+      def update_record(id, payload) = datasource.client.update_team(id, payload)
+
+      def fetch_all
+        datasource.client.fetch_teams
+      end
+
+      # `users` is flattened to the ids of the members: the emails Pylon nests
+      # there belong to PylonUser, which is where they stay up to date.
+      def serialize(team)
+        attrs = team.is_a?(Hash) ? team : {}
+
+        { 'id' => attrs['id'], 'name' => attrs['name'],
+          'user_ids' => Array(attrs['users']).filter_map { |user| user['id'] if user.is_a?(Hash) } }
+      end
+
+      private
+
+      # `/issues/search` filters `team_id` server-side, so the issues assigned to
+      # a team are listed by one request. `user_ids` gets no relation: Pylon
+      # nests the members here rather than pointing at the team from a user, so
+      # the membership is a ManyToMany with no join collection to declare it on.
+      def define_relations
+        add_field('issues', OneToManySchema.new(foreign_collection: 'PylonIssue',
+                                                origin_key: 'team_id', origin_key_target: 'id'))
+      end
+
+      def define_schema
+        add_column('id', 'String', is_primary_key: true)
+        add_column('name', 'String', writable: true)
+        # A list, so neither filterable nor sortable, and no relation either:
+        # see `define_relations` above. `POST /teams` and `PATCH /teams/{id}`
+        # take the members as this very list, and the one sent replaces the
+        # membership whole.
+        add_column('user_ids', 'Json', writable: true)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/user.rb

@@ -0,0 +1,69 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class User < FetchAllCollection
+      NATIVE_FIELDS = %w[id name email emails avatar_url status role_id is_deactivated].freeze
+
+      def initialize(datasource)
+        super(datasource, 'PylonUser')
+      end
+
+      protected
+
+      # Pylon exposes no POST and no DELETE on a user: an agent is invited and
+      # deactivated from Pylon itself, so the other two hooks are left to refuse.
+      def update_record(id, payload) = datasource.client.update_user(id, payload)
+
+      # `include_deactivated` is left at the client default of true on purpose:
+      # a deactivated agent stays the assignee and the author of the issues they
+      # handled, and a record the rest of the panel points at has to stay
+      # readable. `is_deactivated` is exposed as a column so an operator can
+      # filter them out when they want to.
+      def fetch_all
+        datasource.client.fetch_users
+      end
+
+      # `role` is flattened to its name only: its id is already carried by
+      # `role_id`, and the name is what an operator recognises. Its slug is left
+      # out — Pylon derives it from the name.
+      def serialize(user)
+        attrs = user.is_a?(Hash) ? user : {}
+        role = attrs['role']
+
+        NATIVE_FIELDS.to_h { |field| [field, attrs[field]] }
+                     .merge('role_name' => role.is_a?(Hash) ? role['name'] : nil)
+      end
+
+      private
+
+      # `/issues/search` filters `assignee_id` server-side, so the issues of an
+      # agent are listed by one request.
+      #
+      # The teams of a user are left out: Pylon nests the members inside a team
+      # and exposes no team id on a user, so that side is a ManyToMany with no
+      # key column to build it on.
+      def define_relations
+        add_field('assigned_issues', OneToManySchema.new(foreign_collection: 'PylonIssue',
+                                                         origin_key: 'assignee_id', origin_key_target: 'id'))
+      end
+
+      # `PATCH /users/{id}` takes the name, the avatar, the role and the status,
+      # and nothing else.
+      def define_schema
+        add_column('id', 'String', is_primary_key: true)
+        add_column('name', 'String', writable: true)
+        add_column('email', 'String')
+        # The other addresses of the same agent: a list, so it is neither
+        # filterable nor sortable. `email` carries the primary one.
+        add_column('emails', 'Json')
+        add_column('avatar_url', 'String', writable: true)
+        # Left as String rather than Enum: Pylon documents active / away /
+        # out_of_office on the update endpoint, but does not promise the read
+        # side is limited to them.
+        add_column('status', 'String', writable: true)
+        add_column('role_id', 'String', writable: true)
+        add_column('role_name', 'String')
+        add_column('is_deactivated', 'Boolean')
+      end
+    end
+  end
+end