forest_admin_datasource_pylon 1.41.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f400c44e13350edf1d12e584a23df0baf4441fefac43bf549e6247c5528d7faf
+  data.tar.gz: d6e26553966604b9f146a0dd90c2b660c153e70438569829ea452bc6fd1a7f46
+SHA512:
+  metadata.gz: 96156637324e2961eec8c4b67ffdd1d6ae2c4f35287e26ba77e70a1933118336f8e54e14523f11547129703ca26b82cd4b03a7fda8f4cd3432ec9e925c86e3e2
+  data.tar.gz: 0d7e86625aa670bbec771b87a8e101aa8db884aaea650990221bf3bce0a2a215687aca441efa23b6a8c788445cca01905adbfd6ec98ed918f21537a8005ff96d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/README.md

@@ -0,0 +1,179 @@
+# Forest — Pylon datasource
+
+Surface [Pylon](https://usepylon.com) issues, accounts, contacts, users and teams as Forest
+collections, with filters, free-text search, relations, the conversation thread, custom fields,
+CRUD writes and two action plugins.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'forest_admin_datasource_pylon'
+```
+
+## Usage
+
+```ruby
+# app/lib/forest_admin_rails/create_agent.rb
+ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(
+  ForestAdminDatasourcePylon::Datasource.new(api_key: ENV['PYLON_API_KEY'])
+)
+```
+
+A single Bearer token is the whole configuration. `GET /me` is the health check: it returns the
+organization owning the token, which is enough to prove the credentials are usable.
+
+## Collections
+
+| Collection | Pylon resource | Read | Write |
+| --- | --- | --- | --- |
+| `PylonIssue` | `/issues` | `POST /issues/search`, cursor-paginated | create / update / delete |
+| `PylonAccount` | `/accounts` | search + list, cursor-paginated | create / update / delete |
+| `PylonContact` | `/contacts` | search + list, cursor-paginated | create / update / delete |
+| `PylonUser` | `/users` | whole dataset, unpaginated | update |
+| `PylonTeam` | `/teams` | whole dataset, unpaginated | create / update |
+
+`PylonIssue`, `PylonAccount` and `PylonContact` also carry their Pylon custom fields, introspected
+at boot from `GET /custom-fields`.
+
+## What the API cannot do, and what this does about it
+
+Pylon is a ticketing API, not a database, and several things Forest asks for have no equivalent.
+Where that happens this datasource **refuses with a message naming the reason** rather than
+answering something that looks right and is not. All of these arrive as a 400 carrying the text.
+
+- **No aggregate endpoint and no total.** `aggregate` is refused on the cursor-backed collections:
+  counting the pages a walk collected would answer a fraction of a collection as if it were the
+  whole of it, so those are not advertised as countable. `PylonUser` and `PylonTeam` are the
+  exception — their endpoint hands back every record, so a count or a group over it is the figure
+  a server-side aggregation would have given. That claim is checked rather than assumed: the read
+  follows a cursor if Pylon ever advertises one, and refuses outright rather than answer over a
+  fraction of the collection should it paginate past what one walk covers.
+- **No sort parameter on `/issues/search`.** Issues always come back newest first. A requested
+  order is reported in the log rather than silently swallowed.
+- **No `id` filter on the search endpoints.** A primary-key lookup is short-circuited to
+  `GET /issues/{id}`, one request per id. That fan-out is capped per page (`MAX_ID_LOOKUPS`), and
+  a selection naming more ids *and* filtering them further is refused, since which records the
+  page holds could only be known by reading all of them.
+- **No joins.** A condition on a relation is answered by reading the foreign collection for its
+  keys and sending them as an `in`. Past `MAX_RELATION_KEYS` the condition is refused.
+- **Search and id lookup are different endpoints.** Combining a free-text search with a filter on
+  `id` is refused: neither endpoint can do the other's half.
+- **Writes are one record per request.** A write reaching more records than one pass covers is
+  refused up front; one that fails halfway reports exactly which records were written, so a retry
+  can target the untouched ones rather than performing the write twice.
+- **Not every column can be written.** A read-only column sent alongside a real edit is dropped
+  and the edit performed. An edit naming *only* such columns is refused, naming them: it would
+  write nothing, and the record the route reads back would show the operator their change
+  reverting with no reason given.
+
+## Rate limits
+
+Pylon meters **per endpoint**, not per token, from 30 to 300 requests a minute depending on the
+endpoint. `RateLimits` holds the documented budget of every endpoint this client calls, and
+`RateLimiter` spaces requests out so each one is spent rather than exceeded — a sliding window per
+endpoint, in front of the 429 retry rather than instead of it.
+
+The limiter is a smoother, not a guarantee: past `DEFAULT_MAX_WAIT` a request goes out anyway and
+the 429 retry takes over, with one log line per endpoint per window saying so. Under real
+saturation — several agents or processes on the same token — the retry is the defence.
+
+The retry is bounded, deliberately. A 429 carries a `Retry-After` of up to a full minute, and
+waiting one out on every attempt held the calling thread for minutes on a request the Forest
+server had already timed out. `RetryPolicy::DEFAULT_MAX_INTERVAL` caps what one attempt waits;
+past it the 429 surfaces as an error instead. So a saturated endpoint answers the operator with a
+message rather than with a page that arrives after they gave up. Raise it — or lower
+`max_retries` — to trade the other way:
+
+```ruby
+ForestAdminDatasourcePylon::Datasource.new(
+  api_key: ENV['PYLON_API_KEY'],
+  retry_policy: ForestAdminDatasourcePylon::RetryPolicy.new(max_retries: 1, max_interval: 65)
+)
+```
+
+To meter on your own side instead, pass `rate_limiter: nil`:
+
+```ruby
+ForestAdminDatasourcePylon::Datasource.new(api_key: ENV['PYLON_API_KEY'], rate_limiter: nil)
+```
+
+## Boot-time introspection
+
+Custom fields are read while the datasource is being constructed, one call per object type. That
+sits in front of a Rails boot, so it runs on its own connection with short timeouts and a single
+quick retry (`boot_open_timeout`, `boot_timeout`, `boot_retry_policy`), and the first failure
+stops the remaining object types from being tried.
+
+An introspection that fails costs the custom columns, not the datasource: the agent boots on the
+native schema and says so in the log.
+
+## Action plugins
+
+### `CloseIssue`
+
+Moves the selected issues to a state, single and bulk, one request per issue with a per-id rescue
+so one failure does not abort the batch.
+
+```ruby
+@agent.collection :Ticket do |collection|
+  collection.use(ForestAdminDatasourcePylon::Plugins::CloseIssue, {
+    datasource: pylon_datasource,        # required
+    issue_id_field: 'pylon_issue_id',    # omit when the action sits on PylonIssue itself
+    state: 'closed',                     # default
+    scopes: %i[single bulk]              # default
+  })
+end
+```
+
+Two things to know before granting it.
+
+**Which scope bounds it.** The state is written straight through the Pylon client rather than
+through `PylonIssue`, because the action is registered on the host collection — but the ids were
+read before that write, through the collection the action sits on, and the agent intersects the
+operator's scope into the filter that read them. So the scope that bounds this is the scope of the
+**host** collection: mounted on `PylonIssue`, a scope or segment on `PylonIssue` bounds exactly what
+it closes; mounted on a business collection with `issue_id_field`, what bounds it is the records the
+operator may see there, and the issue ids those records carry. In that second form the column is
+the authority — an operator who can write it can name any Pylon issue — so treat it as one.
+
+**The batch is capped at `MAX_TARGETS` (20) issues**, the budget a filter-driven write already gets:
+Pylon takes one request per issue, so a wider selection is a long run of sequential writes the
+request may time out on, leaving the issues closed up to that point closed and reporting which ones
+to nobody. Past the cap the run is refused before its first write, the way `update` and `delete`
+refuse a selection costing more than `MAX_WRITE_REQUESTS`. The cap counts the issues named, not the
+records selected: a column of issue ids is not a key, so a hundred host records naming ten issues is
+a batch of ten.
+
+### `CreateIssueWithNotification`
+
+Creates an issue from a form and notifies the requester, optionally writing the new issue id back
+onto the host record.
+
+```ruby
+@agent.collection :Customer do |collection|
+  collection.use(ForestAdminDatasourcePylon::Plugins::CreateIssueWithNotification, {
+    datasource: pylon_datasource,        # required
+    sender_email: 'support@example.com', # required when the destination is email
+    issue_id_field: 'pylon_issue_id',    # optional id writeback
+    email_templates: [{ title: 'Outage', content: '<p>Sorry {{ record.name }}</p>' }]
+  })
+end
+```
+
+`{{ record.field }}` tokens are interpolated from the host record, HTML-escaped in the message
+body. Template titles must be unique and cannot be `"No template"`, which names the option that
+picks none of them.
+
+The message body is HTML the operator writes and Pylon delivers to the requester, and the
+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.
+
+## Development
+
+```bash
+cd packages/forest_admin_datasource_pylon
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/forest_admin_datasource_pylon.gemspec

@@ -0,0 +1,36 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require_relative 'lib/forest_admin_datasource_pylon/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'forest_admin_datasource_pylon'
+  spec.version     = ForestAdminDatasourcePylon::VERSION
+  spec.authors     = ['Forest Admin']
+  spec.email       = ['contact@forestadmin.com']
+  spec.homepage    = 'https://www.forestadmin.com'
+  spec.summary     = 'Pylon datasource for Forest Admin Ruby agent.'
+  spec.description = 'Surface Pylon issues, accounts, contacts, users and teams as Forest Admin collections.'
+  spec.license     = 'GPL-3.0'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ForestAdmin/agent-ruby'
+  spec.metadata['changelog_uri']   = 'https://github.com/ForestAdmin/agent-ruby/blob/main/CHANGELOG.md'
+  spec.metadata['rubygems_mfa_required'] = 'false'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 6.1'
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'faraday-retry', '~> 2.0'
+  spec.add_dependency 'zeitwerk', '~> 2.3'
+end

data/lib/forest_admin_datasource_pylon/client/writes.rb

@@ -0,0 +1,88 @@
+module ForestAdminDatasourcePylon
+  class Client
+    # The write half of the client: one explicit method per Pylon write
+    # endpoint, each delegating to the shared helpers below.
+    #
+    # Nothing here degrades. `best_effort` exists for the calls whose result
+    # enriches a page — a thread that could not be read costs a column — where a
+    # write that silently did nothing would tell the operator their edit landed.
+    #
+    # Pylon exposes no POST or DELETE on users, and no DELETE on teams. The
+    # collections answer those, not the client, which only spells the endpoints
+    # that exist.
+    module Writes
+      # `title` and `body_html` are the two fields POST /issues requires.
+      def create_issue(attributes) = post_resource('issues', attributes)
+      def update_issue(id, attributes) = patch_resource('issues', id, attributes)
+      def delete_issue(id) = delete_resource('issues', id)
+
+      def create_account(attributes) = post_resource('accounts', attributes)
+      def update_account(id, attributes) = patch_resource('accounts', id, attributes)
+      def delete_account(id) = delete_resource('accounts', id)
+
+      def create_contact(attributes) = post_resource('contacts', attributes)
+      def update_contact(id, attributes) = patch_resource('contacts', id, attributes)
+      def delete_contact(id) = delete_resource('contacts', id)
+
+      def create_team(attributes) = post_resource('teams', attributes)
+      def update_team(id, attributes) = patch_resource('teams', id, attributes)
+
+      def update_user(id, attributes) = patch_resource('users', id, attributes)
+
+      private
+
+      def post_resource(resource, attributes)
+        operation = "create(#{resource})"
+
+        must_succeed(operation) { extract_written(connection.post(resource, attributes).body, operation) }
+      end
+
+      # The id comes from the record the operator acted on, so it is escaped
+      # before being joined to the path, like every read does.
+      def patch_resource(resource, id, attributes)
+        path      = "#{resource}/#{Faraday::Utils.escape(id)}"
+        operation = "update(#{path})"
+
+        must_succeed(operation) { extract_updated(connection.patch(path, attributes).body, operation) }
+      end
+
+      # Answers true rather than the body: Pylon returns 200 or 204 with nothing
+      # worth reading, and a caller has no record left to serialize.
+      def delete_resource(resource, id)
+        path = "#{resource}/#{Faraday::Utils.escape(id)}"
+
+        must_succeed("delete(#{path})") do
+          connection.delete(path)
+          true
+        end
+      end
+
+      # Pylon answers a write with the written record under `data`. Anything else
+      # broke the contract: `extract_data` hands the body back untouched when
+      # `data` is absent, which is what a read wants and a write must not accept
+      # — the collection would serialize the envelope into a record with no id.
+      def extract_written(body, operation)
+        record = body['data'] if body.is_a?(Hash)
+        return record if record.is_a?(Hash)
+
+        refuse_body_shape(body, operation, "missing 'data'")
+      end
+
+      # An update discards its record, so a 204, an empty body or a null `data`
+      # is the write having landed with nothing to hand back: raising there would
+      # report a failure on a record Pylon already patched, and abort the records
+      # a bulk edit had left to write.
+      def extract_updated(body, operation)
+        record = body['data'] if body.is_a?(Hash)
+        return record if record.nil? || record.is_a?(Hash)
+
+        refuse_body_shape(body, operation, "'data' is not a record")
+      end
+
+      def refuse_body_shape(body, operation, detail)
+        raise APIError,
+              "Pylon API #{operation} returned an unexpected body shape (#{detail}): #{body.inspect}"
+      end
+    end
+  end
+end