forest_admin_datasource_pylon 1.46.4 → 1.48.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4389b0a59c9ca74a680cbee11060edc05b2002ef40da37eedd54822d7bebc8e0
-  data.tar.gz: 000e8cd7807e8b41377b048da09d16a0408e29b17324f066a1eeafb71295ae1c
+  metadata.gz: 33487254f529083347aab6801d80be282d51eae68e4e1c9206c570930bed7949
+  data.tar.gz: 14768f83aa896b2340d46a514cb12b64ed8052b8f59cdb71e7fbb2e7c7707700
 SHA512:
-  metadata.gz: b16b5c3af5b709048ff760d4e2ffd36a9cb389ba21b28b57d20c4ac6a5fbb4f5a51b0b04a4a55442801c4f4984e75ef4a697adcc8dfb4b1da8f6de1bea0de0c9
-  data.tar.gz: 56cefaf1671be2ac107bfd4ccbb012e9b6db05cad4089701650d017deccfc215486ad9c0a0f7cb2fa3d2e51f2c01992ddea60ca6f04151d782f5396387de53e1
+  metadata.gz: 141c4d7b99d1d81bde81cd0959b29a1541102f06b6b5dc68ae11d34ad4a86e87ab962714c74d580503eb919447b6e0cc7fc33f4becc32f3a7d71ef268c353809
+  data.tar.gz: 1608a31298e52286cc8741a3acbab9eecb9565718c08164c4a1cf1d9b65cab89ee728fc76d517307167203ab9d3473cdb458221d985a925bbfb5664e22d284e4

data/README.md

@@ -169,6 +169,61 @@ The message body is HTML the operator writes and Pylon delivers to the requester
 requester address is a free-text field. Restrict both actions to the roles that should be able to
 send mail on your organization's behalf.
 
+### `ReplyToIssue`
+
+Answers one issue on the channel the customer used — a Slack issue gets a Slack reply, an email
+issue an email — or posts an internal note on it. Single scope only.
+
+```ruby
+@agent.collection :Ticket do |collection|
+  collection.use(ForestAdminDatasourcePylon::Plugins::ReplyToIssue, {
+    datasource: pylon_datasource,          # required
+    issue_id_field: 'pylon_issue_id',      # omit when the action sits on PylonIssue itself
+    action_name: 'Reply to Pylon issue',   # default
+    allow_internal_note: true,             # default
+    support_emails: ['support@example.com'],
+    post_as_operator: false                # default
+  })
+end
+```
+
+**Which channel.** Pylon delivers a reply into the conversation of the message it names, so the
+action picks that message: the channel is the one of the first customer-visible message, and the
+reply answers the latest customer-visible message on that channel. The form shows the channel
+read-only. An issue with no customer-visible message — one created as an internal note, for
+instance — cannot get a public reply; only the internal note is offered.
+
+**Email recipients.** Pylon does not infer them, so the form pre-fills To and CC from the latest
+email of the conversation. When the customer wrote it, To is its sender only: the addresses the
+customer wrote to include your support inbox. When the team wrote it, To is whom it went to. The
+`support_emails` and the addresses the team wrote from in the thread are always left out, from what
+the operator types as well, and the result message names any typed address left out. Set
+`support_emails`: before the team's first email in a thread, it is the only way to know your own
+addresses. A reply with no To is refused.
+
+**When Pylon does not confirm.** A 4xx is shown with Pylon's own reason. Any other failure, a
+timeout included, may come after Pylon delivered the message, so the action says so and asks to
+check the issue before sending again.
+
+**Who signs.** By default the account owning the API token signs every reply, and the success
+message says so. With `post_as_operator: true`, a public reply is signed by the active Pylon user
+whose email matches the Forest user's, primary or secondary address. With no such user, or several,
+the reply is refused and nothing is sent: it never falls back to the token. Internal notes are
+always signed by the token.
+
+Three things to know before granting it.
+
+- **The column is the authority.** With `issue_id_field`, as with `CloseIssue`, an operator who can
+  write that column can reply to any Pylon issue, on your organization's behalf.
+- **`post_as_operator` trusts emails.** The token can sign as any agent of the workspace; the only
+  thing tying a Forest user to a Pylon user is that they share an email. Keep both user lists
+  consistent, and restrict the action to the roles that should answer customers.
+- **The thread is read on every form render**, one `GET /issues/{id}/messages` (120 a minute).
+  A submit costs one or two more: the agent renders the form again before running the action, and
+  a public reply reads the thread once more to answer its latest state, plus one `GET /users` with
+  `post_as_operator`. An unreadable thread is shown as an error, never as an issue without customer
+  message: both reply types stay offered, and an internal note does not depend on the thread.
+
 ## Development
 
 ```bash

data/lib/forest_admin_datasource_pylon/client/writes.rb

@@ -29,8 +29,23 @@ module ForestAdminDatasourcePylon
 
       def update_user(id, attributes) = patch_resource('users', id, attributes)
 
+      # `message_id` picks the customer conversation the reply is delivered to.
+      def reply_to_issue(id, attributes) = post_message(issue_path(id, 'reply'), attributes)
+      def create_issue_note(id, attributes) = post_message(issue_path(id, 'note'), attributes)
+
       private
 
+      def issue_path(id, action) = "issues/#{Faraday::Utils.escape(id)}/#{action}"
+
+      # A 2xx means Pylon delivered the message, whatever the body says:
+      # refusing an unexpected body would invite the operator to send it twice.
+      def post_message(path, attributes)
+        must_succeed("create(#{path})") do
+          body = connection.post(path, attributes).body
+          body['data'] if body.is_a?(Hash) && body['data'].is_a?(Hash)
+        end
+      end
+
       def post_resource(resource, attributes)
         operation = "create(#{resource})"
 

data/lib/forest_admin_datasource_pylon/client.rb

@@ -53,11 +53,19 @@ module ForestAdminDatasourcePylon
     # when asked to, so a future default page size stays handled rather than
     # silently truncating the thread.
     def fetch_issue_messages(issue_id)
-      path = "issues/#{Faraday::Utils.escape(issue_id)}/messages"
+      path = issue_messages_path(issue_id)
 
       best_effort("fetch_issue_messages(#{issue_id})", default: nil) { must_succeed(path) { collect_pages(path) } }
     end
 
+    # For a caller acting on the thread: a thread that could not be read, or
+    # only in part, raises instead of reading as a conversation without it.
+    def fetch_complete_issue_messages(issue_id)
+      path = issue_messages_path(issue_id)
+
+      must_succeed(path) { collect_pages(path, refuse_past_cap: true) }
+    end
+
     def search_accounts(limit:, cursor: nil, filter: nil, search_text: nil)
       search_resource('accounts/search', limit: limit, cursor: cursor, filter: filter, search_text: search_text)
     end
@@ -144,6 +152,8 @@ module ForestAdminDatasourcePylon
 
     private
 
+    def issue_messages_path(issue_id) = "issues/#{Faraday::Utils.escape(issue_id)}/messages"
+
     def search_resource(path, limit:, cursor: nil, filter: nil, search_text: nil)
       body = { 'limit' => clamp_limit(limit) }
       body['cursor']      = cursor unless blank?(cursor)
@@ -168,12 +178,14 @@ module ForestAdminDatasourcePylon
     # so the walk costs the single request it always did and only does something
     # the day that changes.
     #
-    # Past the cap the walk is refused rather than truncated, unlike the thread
-    # and the custom fields: `FetchAllCollection` filters, sorts, counts and
-    # groups in memory over what this returns, and calls the result exact
-    # BECAUSE it is every record Pylon holds. Truncated, that claim would stand
-    # over a fraction of the collection -- a count answered short and presented
-    # as exact, which is the one answer this datasource refuses everywhere else.
+    # Past the cap the walk is refused rather than truncated, like the thread a
+    # reply acts on (`fetch_complete_issue_messages`) and unlike the thread a
+    # page shows and the custom fields: `FetchAllCollection` filters, sorts,
+    # counts and groups in memory over what this returns, and calls the result
+    # exact BECAUSE it is every record Pylon holds. Truncated, that claim would
+    # stand over a fraction of the collection -- a count answered short and
+    # presented as exact, which is the one answer this datasource refuses
+    # everywhere else.
     def fetch_all(path, params = {})
       must_succeed(path) { collect_pages(path, params, refuse_past_cap: true) }
     end
@@ -193,7 +205,8 @@ module ForestAdminDatasourcePylon
     # Only `next_cursor` being nil is Pylon saying there is nothing more. Every
     # other stop leaves records behind, and `refuse_past_cap` is which of the two
     # answers the caller wants to those: a warning and a short list, or a refusal.
-    # See `fetch_all`, whose answer is only correct whole.
+    # See `fetch_all`, whose answer is only correct whole, and
+    # `fetch_complete_issue_messages`, whose caller acts on the latest message.
     #
     # `conn` is what a caller reading on the boot path hands its own connection
     # through: every page of the walk is then bounded like the first.
@@ -241,10 +254,8 @@ module ForestAdminDatasourcePylon
     def refuse_truncated_walk(path, reason, pages, collected)
       raise APIError,
             "Pylon left the walk of #{path} short after #{pages} page(s) / #{collected} record(s): #{reason}. " \
-            'That endpoint is documented as answering with the whole collection in one response, which is what ' \
-            'PylonUser and PylonTeam filter, sort and count in memory as an exact answer. Refusing rather ' \
-            'than answering over a fraction of the collection: reading it needs cursor pagination, the way ' \
-            'PylonIssue reads its own.'
+            'That endpoint is documented as answering with the whole collection in one response, and its ' \
+            'caller needs all of it. Refusing rather than answering over a fraction of it.'
     end
 
     def log_truncated_walk(path, reason, pages, collected)

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

@@ -5,7 +5,7 @@ module ForestAdminDatasourcePylon
       # 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
+      # thread costs one request per row — against an endpoint allowing 120 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
@@ -49,7 +49,19 @@ module ForestAdminDatasourcePylon
             'thread_id' => attrs['thread_id'],
             'file_urls' => attrs['file_urls'],
             'created_at' => attrs['timestamp']
-          }.merge(flatten_author(attrs['author']))
+          }.merge(flatten_author(attrs['author'])).merge(flatten_email(attrs['email_info']))
+        end
+
+        # Null outside email. `bcc_emails` and the RFC 5322 `message_id` header
+        # are left out: neither is something a reply should be built from.
+        def flatten_email(email_info)
+          attrs = email_info.is_a?(Hash) ? email_info : {}
+
+          {
+            'email_from' => attrs['from_email'],
+            'email_to' => attrs['to_emails'],
+            'email_cc' => attrs['cc_emails']
+          }
         end
 
         # Pylon nests the author's contact and user sides side by side, both

data/lib/forest_admin_datasource_pylon/collections/issue.rb

@@ -40,7 +40,10 @@ module ForestAdminDatasourcePylon
         'author_email' => 'String',
         'author_avatar_url' => 'String',
         'author_contact_id' => 'String',
-        'author_user_id' => 'String'
+        'author_user_id' => 'String',
+        'email_from' => 'String',
+        'email_to' => 'Json',
+        'email_cc' => 'Json'
       }.freeze
 
       # One thread is one `GET /issues/{id}/messages`, and a thread is the whole

data/lib/forest_admin_datasource_pylon/plugins/reply_to_issue/form_builder.rb

@@ -0,0 +1,88 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    class ReplyToIssue
+      # Every dynamic property of the form reads the same ThreadLookup state,
+      # kept on the render's context so it lives exactly as long as the render.
+      # A WeakMap would let the state be collected mid-render.
+      module FormBuilder
+        FieldType = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        TYPE_LABEL    = 'Reply type'.freeze
+        CHANNEL_LABEL = 'Channel'.freeze
+        TO_LABEL      = 'To'.freeze
+        CC_LABEL      = 'CC'.freeze
+        MESSAGE_LABEL = 'Message'.freeze
+
+        PUBLIC_REPLY  = 'Public reply'.freeze
+        INTERNAL_NOTE = 'Internal note'.freeze
+
+        module_function
+
+        def build(datasource, opts)
+          ivar  = :"@forest_admin_datasource_pylon_reply_state_#{opts.object_id}"
+          state = lambda do |context|
+            next context.instance_variable_get(ivar) if context.instance_variable_defined?(ivar)
+
+            context.instance_variable_set(ivar, ThreadLookup.call(datasource, context, opts))
+          end
+
+          fields = []
+          fields << type_field(state) if opts[:allow_internal_note]
+          fields << channel_field(state, opts)
+          fields << recipients_field(TO_LABEL, state, opts, :to)
+          fields << recipients_field(CC_LABEL, state, opts, :cc)
+          fields << message_field
+        end
+
+        def public_reply?(context, opts)
+          !opts[:allow_internal_note] || context.get_form_value(TYPE_LABEL) == PUBLIC_REPLY
+        end
+
+        def type_field(state)
+          { type: FieldType::ENUM, label: TYPE_LABEL, is_required: true,
+            enum_values: lambda { |context|
+              reply_possible?(state.call(context)) ? [PUBLIC_REPLY, INTERNAL_NOTE] : [INTERNAL_NOTE]
+            },
+            default_value: ->(context) { state.call(context).target ? PUBLIC_REPLY : INTERNAL_NOTE },
+            description: 'A public reply reaches the customer; an internal note is seen by your team only.' }
+        end
+
+        # A thread that could not be read may well have a customer message: the
+        # public reply stays offered, not picked, and picking it renders the
+        # form again, which reads the thread again.
+        def reply_possible?(state)
+          !state.target.nil? || !state.error.nil?
+        end
+
+        def channel_field(state, opts)
+          { type: FieldType::STRING, label: CHANNEL_LABEL, is_read_only: true,
+            if_condition: ->(context) { public_reply?(context, opts) || state.call(context).target.nil? },
+            value: ->(context) { channel_text(state.call(context), opts) },
+            description: 'Pylon delivers the reply on the channel the customer used. It cannot be changed here.' }
+        end
+
+        def channel_text(state, opts)
+          return state.error if state.error
+          return "Replies via #{state.target.channel_label}" if state.target
+
+          no_target = 'This issue has no customer-visible message, so it cannot get a public reply.'
+          opts[:allow_internal_note] ? "#{no_target} Post an internal note instead." : no_target
+        end
+
+        def recipients_field(label, state, opts, side)
+          { type: FieldType::STRING_LIST, label: label, is_required: side == :to,
+            if_condition: lambda { |context|
+              target = state.call(context).target
+              public_reply?(context, opts) && !target.nil? && target.email?
+            },
+            default_value: ->(context) { state.call(context).target&.public_send(side) || [] },
+            description: 'Pre-filled from the latest email of the conversation, support addresses left out.' }
+        end
+
+        def message_field
+          { type: FieldType::STRING, label: MESSAGE_LABEL, widget: 'RichText', is_required: true }
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/reply_to_issue/operator_lookup.rb

@@ -0,0 +1,47 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    class ReplyToIssue
+      # The active Pylon user a reply is signed as, matched on the email of the
+      # Forest user running the action. Anything short of exactly one match
+      # refuses the reply rather than letting the token sign it instead.
+      module OperatorLookup
+        Result = Struct.new(:user, :error, keyword_init: true)
+
+        module_function
+
+        def call(datasource, caller)
+          email = caller.respond_to?(:email) ? caller.email.to_s.strip.downcase : ''
+          return Result.new(error: 'Your Forest user has no email to sign the reply with.') if email.empty?
+
+          users   = datasource.client.fetch_users(include_deactivated: false)
+          matches = users.select { |user| active?(user) && addresses(user).include?(email) }
+          return Result.new(error: refusal(email, matches.size)) unless matches.size == 1
+          return Result.new(user: matches.first) unless matches.first['id'].to_s.strip.empty?
+
+          Result.new(error: "The Pylon user with the email #{email} has no id, so the reply cannot be signed in " \
+                            'your name and was not sent.')
+        rescue APIError => e
+          Result.new(error: "Could not read the Pylon users to sign the reply in your name: #{e.message}")
+        end
+
+        def active?(user)
+          user.is_a?(Hash) && user['is_deactivated'] != true
+        end
+
+        def addresses(user)
+          [user['email'], *Array(user['emails'])].map { |address| address.to_s.strip.downcase }
+        end
+
+        def refusal(email, count)
+          if count.zero?
+            return "No active Pylon user has the email #{email}, so the reply cannot be signed in your name and " \
+                   'was not sent. Use the same email in Forest and Pylon.'
+          end
+
+          "#{count} active Pylon users have the email #{email}, so the reply cannot be signed in your name and " \
+            'was not sent.'
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/reply_to_issue/reply_target.rb

@@ -0,0 +1,86 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    class ReplyToIssue
+      # The customer-visible message a public reply answers. The channel is the
+      # `source` of the first such message; the reply goes to the latest message
+      # on that channel, so an email answers the latest recipients rather than
+      # those of the opening message.
+      class ReplyTarget
+        EMAIL_SOURCE = 'email'.freeze
+        CHANNEL_LABELS = { 'email' => 'email', 'slack' => 'Slack' }.freeze
+
+        attr_reader :message_id, :source, :to, :cc
+
+        def self.resolve(messages, support_emails: [])
+          visible = Array(messages).select { |message| message.is_a?(Hash) && message['is_private'] != true }
+          return nil if visible.empty?
+
+          source = visible.first['source']
+          excluded = support_emails.map(&:downcase) + team_addresses(visible)
+          new(visible.reverse.find { |message| message['source'] == source }, excluded)
+        end
+
+        # The addresses the team itself wrote from, read off the thread: what
+        # keeps a reply out of the support inbox when `support_emails` misses one.
+        def self.team_addresses(messages)
+          messages.select { |message| team_authored?(message) }
+                  .map { |message| email_info(message)['from_email'].to_s.strip.downcase }
+                  .reject(&:empty?)
+        end
+
+        def self.email_info(message)
+          message['email_info'].is_a?(Hash) ? message['email_info'] : {}
+        end
+
+        def self.team_authored?(message)
+          author = message['author']
+          author.is_a?(Hash) && author['user'].is_a?(Hash)
+        end
+
+        def self.unique_addresses(addresses, excluded = [])
+          addresses.map { |address| address.to_s.strip }
+                   .reject { |address| address.empty? || excluded.include?(address.downcase) }
+                   .uniq(&:downcase)
+        end
+
+        def initialize(message, excluded)
+          @message_id = message['id']
+          @source     = message['source']
+          @email_info = self.class.email_info(message)
+          @excluded   = excluded
+          @to, @cc    = sanitize(to: default_to(message), cc: @email_info['cc_emails'])
+        end
+
+        # The excluded addresses come back apart, so an operator who typed one
+        # is told it was left out rather than finding it silently gone.
+        def sanitize(to:, cc:)
+          to_kept = self.class.unique_addresses(Array(to), @excluded)
+          cc_kept = self.class.unique_addresses(Array(cc), @excluded + to_kept.map(&:downcase))
+          dropped = (Array(to) + Array(cc)).map { |address| address.to_s.strip }
+                                           .select { |address| @excluded.include?(address.downcase) }
+                                           .uniq(&:downcase)
+          [to_kept, cc_kept, dropped]
+        end
+
+        def email?
+          @source == EMAIL_SOURCE || !@email_info['from_email'].to_s.empty? || Array(@email_info['to_emails']).any?
+        end
+
+        def channel_label
+          return CHANNEL_LABELS[EMAIL_SOURCE] if email?
+
+          CHANNEL_LABELS.fetch(@source.to_s) { @source.to_s.empty? ? 'an unnamed channel' : @source.to_s.tr('_', ' ') }
+        end
+
+        private
+
+        # Answering a customer's email writes back to its sender only: its own
+        # To is where the customer wrote, the support inbox among them. Answering
+        # the team's last email writes again to whom it went.
+        def default_to(message)
+          self.class.team_authored?(message) ? @email_info['to_emails'] : [@email_info['from_email']]
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/reply_to_issue/thread_lookup.rb

@@ -0,0 +1,37 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    class ReplyToIssue
+      # The issue an action targets and the reply target its thread resolves to,
+      # or why neither could be had. `error` set means `target` is not.
+      module ThreadLookup
+        State = Struct.new(:issue_id, :target, :error, keyword_init: true)
+
+        module_function
+
+        def call(datasource, context, opts)
+          issue_id = issue_id(context, opts)
+          return State.new(error: no_issue(opts[:issue_id_field])) if issue_id.nil?
+
+          read(datasource, issue_id, opts)
+        end
+
+        def issue_id(context, opts)
+          IssueTargets.resolve_issue_ids(context, opts[:issue_id_field]).first
+        end
+
+        def read(datasource, issue_id, opts)
+          messages = datasource.client.fetch_complete_issue_messages(issue_id)
+          State.new(issue_id: issue_id,
+                    target: ReplyTarget.resolve(messages, support_emails: opts[:support_emails]))
+        rescue APIError => e
+          State.new(issue_id: issue_id, error: "Could not read the conversation of Pylon issue #{issue_id}: " \
+                                               "#{e.message}")
+        end
+
+        def no_issue(field)
+          field.nil? ? 'No Pylon issue selected.' : "No Pylon issue id found in '#{field}'."
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/reply_to_issue.rb

@@ -0,0 +1,142 @@
+require 'cgi'
+
+module ForestAdminDatasourcePylon
+  module Plugins
+    # Answers a Pylon issue on the channel the customer used, or posts an
+    # internal note on it. See the README for the channel rule and who signs.
+    class ReplyToIssue < ForestAdminDatasourceCustomizer::Plugins::Plugin
+      BaseAction      = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+      ActionScope     = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+      ForestException = ForestAdminDatasourceToolkit::Exceptions::ForestException
+
+      NAME = 'Reply to Pylon issue'.freeze
+
+      def run(_datasource_customizer, collection_customizer = nil, options = {})
+        options = {} unless options.is_a?(Hash)
+        datasource = options[:datasource]
+        raise ForestException, 'ReplyToIssue plugin requires :datasource' unless datasource
+        raise ForestException, 'ReplyToIssue plugin requires a collection' unless collection_customizer
+
+        opts = {
+          issue_id_field: options[:issue_id_field],
+          allow_internal_note: options.fetch(:allow_internal_note, true) ? true : false,
+          post_as_operator: options[:post_as_operator] ? true : false,
+          support_emails: normalize_emails(options[:support_emails])
+        }
+
+        collection_customizer.add_action((options[:action_name] || NAME).to_s, build_action(datasource, opts))
+      end
+
+      private
+
+      def normalize_emails(value)
+        Array(value).map { |email| email.to_s.strip.downcase }.reject(&:empty?).uniq
+      end
+
+      def build_action(datasource, opts)
+        BaseAction.new(scope: ActionScope::SINGLE, form: FormBuilder.build(datasource, opts),
+                       &executor(datasource, opts))
+      end
+
+      # A note needs the issue only. A reply reads the thread again rather than
+      # trusting the form: the conversation may have moved since it rendered.
+      def executor(datasource, opts)
+        lambda do |context, result_builder|
+          issue_id = ThreadLookup.issue_id(context, opts)
+          next result_builder.error(message: ThreadLookup.no_issue(opts[:issue_id_field])) if issue_id.nil?
+
+          body = context.form_values[FormBuilder::MESSAGE_LABEL].to_s
+          next result_builder.error(message: 'A message is required.') if blank_html?(body)
+
+          status, message = if FormBuilder.public_reply?(context, opts)
+                              reply(datasource, ThreadLookup.read(datasource, issue_id, opts), body, context, opts)
+                            else
+                              note(datasource, issue_id, body)
+                            end
+          result_builder.public_send(status, message: message)
+        end
+      end
+
+      # An emptied rich-text editor still submits markup such as `<p><br></p>`.
+      def blank_html?(body)
+        return false if body.match?(/<img\b/i)
+
+        text = CGI.unescapeHTML(body.gsub(/<[^>]*>/, ' ').gsub(/&nbsp;/i, ' '))
+        text.gsub(/[[:space:]\u200B-\u200D\u2060\uFEFF]/, '').empty?
+      end
+
+      def reply(datasource, state, body, context, opts)
+        return [:error, state.error] if state.error
+        return [:error, no_target_message(state.issue_id, opts)] if state.target.nil?
+
+        payload, dropped, refusal = reply_payload(state.target, body, context)
+        return [:error, refusal] if refusal
+
+        operator = OperatorLookup.call(datasource, context.caller) if opts[:post_as_operator]
+        return [:error, operator.error] if operator&.error
+
+        payload['user_id'] = operator.user['id'] if operator
+        write(state.issue_id, 'reply', reply_success(state, payload, operator&.user) + left_out(dropped)) do
+          datasource.client.reply_to_issue(state.issue_id, payload)
+        end
+      end
+
+      def reply_payload(target, body, context)
+        payload = { 'body_html' => body, 'message_id' => target.message_id }
+        return [payload, []] unless target.email?
+
+        to, cc, dropped = target.sanitize(to: context.form_values[FormBuilder::TO_LABEL],
+                                          cc: context.form_values[FormBuilder::CC_LABEL])
+        refusal = "At least one recipient (To) is required to reply by email.#{left_out(dropped)}" if to.empty?
+        return [nil, dropped, refusal] if refusal
+
+        [payload.merge('email_info' => { 'to_emails' => to, 'cc_emails' => cc }), dropped]
+      end
+
+      def left_out(dropped)
+        dropped.empty? ? '' : " Left out as addresses of your team: #{dropped.join(", ")}."
+      end
+
+      def note(datasource, issue_id, body)
+        write(issue_id, 'internal note', "Internal note added to Pylon issue #{issue_id}.") do
+          datasource.client.create_issue_note(issue_id, 'body_html' => body)
+        end
+      end
+
+      # A 4xx is Pylon naming what is wrong, handed over as it is. Anything else
+      # may have failed after Pylon delivered the message, so the operator is
+      # told to check before sending it again rather than shown a bare failure.
+      def write(issue_id, what, success)
+        yield
+        [:success, success]
+      rescue APIError => e
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] #{what} on issue #{issue_id} failed: #{e.message}"
+        )
+        return [:error, e.message] if (400..499).cover?(e.status.to_i)
+
+        [:error, "Pylon did not confirm the #{what} on issue #{issue_id} (#{e.message}). It may have been " \
+                 'delivered: check the issue in Pylon before sending it again.']
+      end
+
+      def no_target_message(issue_id, opts)
+        message = "Pylon issue #{issue_id} has no customer-visible message, so it cannot get a public reply."
+        opts[:allow_internal_note] ? "#{message} Post an internal note instead." : message
+      end
+
+      def reply_success(state, payload, operator)
+        signed = if operator
+                   "signed by #{[operator["name"], operator["email"]].find { |v| !v.to_s.strip.empty? }}"
+                 else
+                   'signed by the account of the Pylon API token'
+                 end
+        if payload['email_info']
+          return "Reply emailed to #{payload["email_info"]["to_emails"].join(", ")} on Pylon issue " \
+                 "#{state.issue_id}, #{signed}."
+        end
+
+        "Reply sent via #{state.target.channel_label} on Pylon issue #{state.issue_id}, #{signed}."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/rate_limits.rb

@@ -40,6 +40,8 @@ module ForestAdminDatasourcePylon
       ['get /issues/:id/messages',      :get,    %r{\A/issues/#{ID}/messages\z},      120],
       ['get /issues',                   :get,    %r{\A/issues\z},                      30],
       ['post /issues',                  :post,   %r{\A/issues\z},                      30],
+      ['post /issues/:id/reply',        :post,   %r{\A/issues/#{ID}/reply\z},         30],
+      ['post /issues/:id/note',         :post,   %r{\A/issues/#{ID}/note\z},          30],
       ['get /issues/:id',               :get,    %r{\A/issues/#{ID}\z},               300],
       ['patch /issues/:id',             :patch,  %r{\A/issues/#{ID}\z},               120],
       ['get /accounts',                 :get,    %r{\A/accounts\z},                   300],

data/lib/forest_admin_datasource_pylon/version.rb

@@ -1,3 +1,3 @@
 module ForestAdminDatasourcePylon
-  VERSION = "1.46.4"
+  VERSION = "1.48.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: forest_admin_datasource_pylon
 version: !ruby/object:Gem::Version
-  version: 1.46.4
+  version: 1.48.0
 platform: ruby
 authors:
 - Forest Admin
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -58,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.46.4
+        version: 1.48.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.46.4
+        version: 1.48.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -128,6 +127,11 @@ files:
 - lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification/form_builder.rb
 - lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification/payload.rb
 - lib/forest_admin_datasource_pylon/plugins/issue_targets.rb
+- lib/forest_admin_datasource_pylon/plugins/reply_to_issue.rb
+- lib/forest_admin_datasource_pylon/plugins/reply_to_issue/form_builder.rb
+- lib/forest_admin_datasource_pylon/plugins/reply_to_issue/operator_lookup.rb
+- lib/forest_admin_datasource_pylon/plugins/reply_to_issue/reply_target.rb
+- lib/forest_admin_datasource_pylon/plugins/reply_to_issue/thread_lookup.rb
 - lib/forest_admin_datasource_pylon/query/condition_tree_translator.rb
 - lib/forest_admin_datasource_pylon/query/filter_value.rb
 - lib/forest_admin_datasource_pylon/query/operator_maps.rb
@@ -145,7 +149,6 @@ metadata:
   source_code_uri: https://github.com/ForestAdmin/agent-ruby
   changelog_uri: https://github.com/ForestAdmin/agent-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'false'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -160,8 +163,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Pylon datasource for Forest Admin Ruby agent.
 test_files: []