forest_admin_datasource_zendesk 1.28.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad071bda5dc06de2f241d04c2676d8ddf28636a5fd96c6cee30d2390c874c537
+  data.tar.gz: 25f249e17a6b7ac578521940112b0918f8a0fb85aa3edbad66bdb59babc0d22e
+SHA512:
+  metadata.gz: 163fdfe79cea9ed7189eab4c583a946bd7de6aef5fbc9ffabffe7daede599d459509c8384bfc5fb29af7c160d98747c57a8a8c9e9ab42e76f70db7b469e9667f
+  data.tar.gz: 8cdefd1d17454792e5c80d442f262bfdbce5b6a14af9efaeb8b301a9a39f73c0e5732f865b801e81981f1f88129c56bb61b80e8e3b34a86c4dfc2372e749d2ee

data/.rspec

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

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_zendesk.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require_relative 'lib/forest_admin_datasource_zendesk/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'forest_admin_datasource_zendesk'
+  spec.version     = ForestAdminDatasourceZendesk::VERSION
+  spec.authors     = ['Forest Admin']
+  spec.email       = ['contact@forestadmin.com']
+  spec.homepage    = 'https://www.forestadmin.com'
+  spec.summary     = 'Zendesk datasource for Forest Admin Ruby agent.'
+  spec.description = 'Surface Zendesk tickets, users, organizations and comments 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 'zeitwerk', '~> 2.3'
+  spec.add_dependency 'zendesk_api', '~> 3.0'
+end

data/lib/forest_admin_datasource_zendesk/client/introspection.rb

@@ -0,0 +1,23 @@
+module ForestAdminDatasourceZendesk
+  class Client
+    module Introspection
+      def fetch_ticket_fields
+        best_effort('fetch_ticket_fields (custom fields will be unavailable)', default: []) do
+          Array(api.connection.get('ticket_fields').body['ticket_fields'])
+        end
+      end
+
+      def fetch_user_fields
+        best_effort('fetch_user_fields (custom fields will be unavailable)', default: []) do
+          Array(api.connection.get('user_fields').body['user_fields'])
+        end
+      end
+
+      def fetch_organization_fields
+        best_effort('fetch_organization_fields (custom fields will be unavailable)', default: []) do
+          Array(api.connection.get('organization_fields').body['organization_fields'])
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/client/writes.rb

@@ -0,0 +1,40 @@
+module ForestAdminDatasourceZendesk
+  class Client
+    module Writes
+      def create_ticket(attributes) = post_resource('tickets', 'ticket', attributes)
+      def update_ticket(id, attrs)  = put_resource('tickets', 'ticket', id, attrs)
+      def delete_ticket(id)         = delete_resource('tickets', id)
+
+      def create_user(attributes) = post_resource('users', 'user', attributes)
+      def update_user(id, attrs)  = put_resource('users', 'user', id, attrs)
+      def delete_user(id)         = delete_resource('users', id)
+
+      def create_organization(attrs)     = post_resource('organizations', 'organization', attrs)
+      def update_organization(id, attrs) = put_resource('organizations', 'organization', id, attrs)
+      def delete_organization(id)        = delete_resource('organizations', id)
+
+      private
+
+      def post_resource(path, key, attributes)
+        must_succeed("create(#{path})") do
+          body = api.connection.post(path) { |req| req.body = { key => attributes } }.body
+          body[key] || body
+        end
+      end
+
+      def put_resource(path, key, id, attributes)
+        must_succeed("update(#{path}/#{id})") do
+          body = api.connection.put("#{path}/#{id}") { |req| req.body = { key => attributes } }.body
+          body[key] || body
+        end
+      end
+
+      def delete_resource(path, id)
+        must_succeed("delete(#{path}/#{id})") do
+          api.connection.delete("#{path}/#{id}")
+          true
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/client.rb

@@ -0,0 +1,118 @@
+module ForestAdminDatasourceZendesk
+  class Client
+    include Writes
+    include Introspection
+
+    MAX_PER_PAGE = 100
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def search(type, **opts)
+      params = build_search_params(type, opts)
+      must_succeed("search(#{type})") { api.search(params).to_a }
+    end
+
+    def count(type, query:)
+      must_succeed("count(#{type})") do
+        body = api.connection.get('search/count', query: compose_query(type, query)).body
+        Integer(body['count'] || 0)
+      end
+    end
+
+    def fetch_ticket_comments(ticket_id)
+      must_succeed("fetch_ticket_comments(#{ticket_id})") do
+        Array(api.connection.get("tickets/#{ticket_id}/comments").body['comments'])
+      end
+    end
+
+    def find_ticket(id)       = find_one(api.tickets, id)
+    def find_user(id)         = find_one(api.users, id)
+    def find_organization(id) = find_one(api.organizations, id)
+
+    def fetch_user_emails(ids)
+      best_effort('fetch_user_emails', default: {}) do
+        bulk_show_many('users', ids) { |u| [u['id'], u['email']] }
+      end
+    end
+
+    def fetch_tickets_by_ids(ids)
+      must_succeed('fetch_tickets_by_ids') do
+        bulk_show_many('tickets', ids) { |t| [t['id'], t] }
+      end
+    end
+
+    def fetch_users_by_ids(ids)
+      best_effort('fetch_users_by_ids', default: {}) do
+        bulk_show_many('users', ids) { |u| [u['id'], u] }
+      end
+    end
+
+    def fetch_organizations_by_ids(ids)
+      best_effort('fetch_organizations_by_ids', default: {}) do
+        bulk_show_many('organizations', ids) { |o| [o['id'], o] }
+      end
+    end
+
+    private
+
+    def find_one(api_collection, id)
+      api_collection.find(id: id)
+    rescue ZendeskAPI::Error::RecordNotFound
+      nil
+    end
+
+    def bulk_show_many(resource, ids)
+      ids = Array(ids).compact.uniq
+      return {} if ids.empty?
+
+      ids.each_slice(MAX_PER_PAGE).with_object({}) do |batch, acc|
+        body = api.connection.get("#{resource}/show_many", ids: batch.join(',')).body
+        Array(body[resource]).each do |item|
+          k, v = yield(item)
+          acc[k] = v
+        end
+      end
+    end
+
+    def must_succeed(operation)
+      yield
+    rescue StandardError => e
+      raise APIError, "Zendesk API call failed: #{operation}: #{e.class}: #{e.message}"
+    end
+
+    def best_effort(operation, default:)
+      yield
+    rescue StandardError => e
+      ForestAdminDatasourceZendesk.logger.warn(
+        "[forest_admin_datasource_zendesk] #{operation} failed; degrading: #{e.class}: #{e.message}"
+      )
+      default
+    end
+
+    def compose_query(type, query)
+      [type ? "type:#{type}" : nil, query.to_s.strip].compact.reject(&:empty?).join(' ')
+    end
+
+    def build_search_params(type, opts)
+      params = {
+        query: compose_query(type, opts[:query]),
+        per_page: [opts[:per_page] || MAX_PER_PAGE, MAX_PER_PAGE].min,
+        page: opts[:page] || 1
+      }
+      params[:sort_by]    = opts[:sort_by]    if opts[:sort_by]
+      params[:sort_order] = opts[:sort_order] if opts[:sort_order]
+      params
+    end
+
+    def api
+      @api ||= ZendeskAPI::Client.new do |c|
+        c.url      = @configuration.url
+        c.username = @configuration.username
+        c.token    = @configuration.token
+        c.retry    = true
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/base_collection.rb

@@ -0,0 +1,103 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class BaseCollection < ForestAdminDatasourceToolkit::Collection
+      ColumnSchema = ForestAdminDatasourceToolkit::Schema::ColumnSchema
+      Operators    = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+      Leaf         = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+
+      STRING_OPS  = [Operators::EQUAL, Operators::NOT_EQUAL, Operators::IN, Operators::NOT_IN,
+                     Operators::PRESENT, Operators::BLANK].freeze
+      NUMBER_OPS  = (STRING_OPS + [Operators::GREATER_THAN, Operators::LESS_THAN]).freeze
+      DATE_OPS    = [Operators::EQUAL, Operators::BEFORE, Operators::AFTER,
+                     Operators::PRESENT, Operators::BLANK].freeze
+
+      def aggregate(caller, filter, aggregation, _limit = nil)
+        unless aggregation.operation == 'Count' && aggregation.field.nil? && aggregation.groups.empty?
+          raise ForestAdminDatasourceToolkit::Exceptions::ForestException,
+                'Zendesk datasource only supports Count aggregation without groups.'
+        end
+
+        [{ 'value' => aggregate_count(caller, filter), 'group' => {} }]
+      end
+
+      protected
+
+      def aggregate_count(_caller, _filter)
+        raise NotImplementedError, "#{self.class} did not implement aggregate_count"
+      end
+
+      # Zendesk Search has no `id:` operator, so collections short-circuit
+      # PK lookups to /resource/{id} when the filter is `id = N` or `id IN [...]`.
+      def extract_id_lookup(node)
+        return nil unless node.is_a?(Leaf) && node.field == 'id'
+
+        case node.operator
+        when Operators::EQUAL then [node.value]
+        when Operators::IN    then Array(node.value)
+        end
+      end
+
+      def project(record, projection)
+        return record if projection.nil?
+
+        wanted = Array(projection).map(&:to_s).reject { |p| p.include?(':') }
+        return record if wanted.empty?
+
+        wanted.to_h { |k| [k, record[k]] }
+      end
+
+      # Unknown fields silently disable sorting — Zendesk's Search API only
+      # honours a fixed allow-list per resource.
+      def translate_sort(sort, allow_list)
+        return [nil, nil] if sort.nil? || sort.empty?
+
+        field, ascending = sort_field_and_direction(sort.first)
+        zd_field = allow_list[field.to_s]
+        return [nil, nil] unless zd_field
+
+        [zd_field, ascending ? 'asc' : 'desc']
+      end
+
+      def translate_page(page)
+        return [1, Client::MAX_PER_PAGE] if page.nil?
+
+        per_page = page.limit&.positive? ? [page.limit, Client::MAX_PER_PAGE].min : Client::MAX_PER_PAGE
+        page_num = (page.offset.to_i / per_page) + 1
+        [page_num, per_page]
+      end
+
+      def attrs_of(record)
+        record.respond_to?(:attributes) ? record.attributes : record.to_h
+      end
+
+      def ids_for(caller, filter)
+        list(caller, filter, ['id']).filter_map { |row| row['id'] }
+      end
+
+      def timezone_for(caller)
+        return 'UTC' unless caller.respond_to?(:timezone)
+
+        tz = caller.timezone
+        tz.nil? || tz.empty? ? 'UTC' : tz
+      end
+
+      def build_zendesk_query(caller, filter)
+        translated = ForestAdminDatasourceZendesk::Query::ConditionTreeTranslator.call(
+          filter.condition_tree, timezone: timezone_for(caller),
+                                 custom_fields: datasource.custom_field_mapping
+        )
+        [translated, filter.search].compact.reject(&:empty?).join(' ')
+      end
+
+      private
+
+      def sort_field_and_direction(entry)
+        return [entry.field, entry.ascending] if entry.respond_to?(:field)
+
+        field     = entry.key?(:field)     ? entry[:field]     : entry['field']
+        ascending = entry.key?(:ascending) ? entry[:ascending] : entry['ascending']
+        [field, ascending]
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/organization.rb

@@ -0,0 +1,118 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class Organization < BaseCollection
+      include Searchable
+
+      OneToManySchema = ForestAdminDatasourceToolkit::Schema::Relations::OneToManySchema
+
+      ZENDESK_SORTABLE = {
+        'created_at' => 'created_at',
+        'updated_at' => 'updated_at',
+        'name' => 'name'
+      }.freeze
+
+      def initialize(datasource, custom_fields: [])
+        super(datasource, 'ZendeskOrganization')
+        @custom_fields = custom_fields
+        define_schema
+        define_relations
+        enable_search
+        enable_count
+      end
+
+      def create(_caller, data)
+        payload = build_payload(data)
+        created = datasource.client.create_organization(payload)
+        serialize(created)
+      end
+
+      def update(caller, filter, patch)
+        ids = ids_for(caller, filter)
+        payload = build_payload(patch)
+        ids.each { |id| datasource.client.update_organization(id, payload) }
+      end
+
+      def delete(caller, filter)
+        ids_for(caller, filter).each { |id| datasource.client.delete_organization(id) }
+      end
+
+      protected
+
+      def zendesk_resource = 'organization'
+      def sortable_fields  = ZENDESK_SORTABLE
+      def find_one(id)     = datasource.client.find_organization(id)
+
+      private
+
+      def build_payload(data)
+        attrs = data.transform_keys(&:to_s)
+        cf_keys = @custom_fields.to_h { |cf| [cf[:column_name], cf[:zendesk_key]] }
+        org_fields = {}
+        base = attrs.each_with_object({}) do |(k, v), h|
+          if (key = cf_keys[k])
+            org_fields[key] = v
+          else
+            h[k] = v
+          end
+        end
+        %w[id created_at updated_at].each { |k| base.delete(k) }
+        base['organization_fields'] = org_fields unless org_fields.empty?
+        base
+      end
+
+      def define_schema
+        add_field('id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                         is_primary_key: true, is_read_only: true, is_sortable: true))
+        add_field('name', ColumnSchema.new(column_type: 'String', filter_operators: STRING_OPS,
+                                           is_read_only: false, is_sortable: true))
+        add_field('domain_names', ColumnSchema.new(column_type: 'Json', filter_operators: [],
+                                                   is_read_only: false, is_sortable: false))
+        add_field('details', ColumnSchema.new(column_type: 'String', filter_operators: [],
+                                              is_read_only: false, is_sortable: false))
+        add_field('notes', ColumnSchema.new(column_type: 'String', filter_operators: [],
+                                            is_read_only: false, is_sortable: false))
+        add_field('group_id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                               is_read_only: false, is_sortable: false))
+        add_field('shared_tickets', ColumnSchema.new(column_type: 'Boolean', filter_operators: [],
+                                                     is_read_only: false, is_sortable: false))
+        add_field('created_at', ColumnSchema.new(column_type: 'Date', filter_operators: DATE_OPS,
+                                                 is_read_only: true, is_sortable: true))
+        add_field('updated_at', ColumnSchema.new(column_type: 'Date', filter_operators: DATE_OPS,
+                                                 is_read_only: true, is_sortable: true))
+
+        @custom_fields.each { |cf| add_field(cf[:column_name], cf[:schema]) }
+      end
+
+      def define_relations
+        add_field('users', OneToManySchema.new(
+                             foreign_collection: 'ZendeskUser',
+                             origin_key: 'organization_id',
+                             origin_key_target: 'id'
+                           ))
+        add_field('tickets', OneToManySchema.new(
+                               foreign_collection: 'ZendeskTicket',
+                               origin_key: 'organization_id',
+                               origin_key_target: 'id'
+                             ))
+      end
+
+      def serialize(org)
+        attrs = attrs_of(org)
+        result = base_attributes(attrs)
+        org_fields = attrs['organization_fields'] || {}
+        @custom_fields.each { |cf| result[cf[:column_name]] = org_fields[cf[:zendesk_key]] }
+        result
+      end
+
+      def base_attributes(attrs)
+        {
+          'id' => attrs['id'], 'name' => attrs['name'],
+          'domain_names' => attrs['domain_names'], 'details' => attrs['details'],
+          'notes' => attrs['notes'], 'group_id' => attrs['group_id'],
+          'shared_tickets' => attrs['shared_tickets'],
+          'created_at' => attrs['created_at'], 'updated_at' => attrs['updated_at']
+        }
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/searchable.rb

@@ -0,0 +1,38 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    # Including classes must define `zendesk_resource`, `find_one(id)`,
+    # `sortable_fields`, and `serialize(record)`.
+    module Searchable
+      def list(caller, filter, projection)
+        records = ids_in_filter(filter) ? find_records_by_id(filter) : search_records(caller, filter)
+        records.map { |r| project(serialize(r), projection) }
+      end
+
+      protected
+
+      def aggregate_count(caller, filter)
+        datasource.client.count(zendesk_resource, query: build_zendesk_query(caller, filter))
+      end
+
+      private
+
+      def ids_in_filter(filter)
+        extract_id_lookup(filter.condition_tree)
+      end
+
+      def find_records_by_id(filter)
+        ids_in_filter(filter).filter_map { |id| find_one(id) }
+      end
+
+      def search_records(caller, filter)
+        sort_by, sort_order = translate_sort(filter.sort, sortable_fields)
+        page, per_page      = translate_page(filter.page)
+
+        datasource.client.search(zendesk_resource,
+                                 query: build_zendesk_query(caller, filter),
+                                 sort_by: sort_by, sort_order: sort_order,
+                                 page: page, per_page: per_page)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/ticket/comments_embedder.rb

@@ -0,0 +1,40 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class Ticket < BaseCollection
+      module CommentsEmbedder
+        private
+
+        def want_comments?(projection)
+          projection.nil? ||
+            Array(projection).map(&:to_s).any? { |p| p == 'comments' || p.start_with?('comments:') }
+        end
+
+        def embed_comments(records, rows)
+          comments_by_ticket = records.to_h do |t|
+            id = attrs_of(t)['id']
+            [id, datasource.client.fetch_ticket_comments(id)]
+          end
+          author_ids = comments_by_ticket.values.flatten.filter_map { |c| c['author_id'] }.uniq
+          users = datasource.client.fetch_users_by_ids(author_ids)
+          rows.each_with_index do |row, i|
+            row['comments'] = comments_by_ticket[attrs_of(records[i])['id']].map { |c| serialize_comment(c, users) }
+          end
+        end
+
+        def serialize_comment(comment, users)
+          author = users[comment['author_id']]
+          author_attrs = author && (author.is_a?(Hash) ? author : attrs_of(author))
+          {
+            'id' => comment['id'],
+            'body' => comment['body'],
+            'html_body' => comment['html_body'],
+            'public' => comment['public'],
+            'author_email' => author_attrs && author_attrs['email'],
+            'author_name' => author_attrs && author_attrs['name'],
+            'created_at' => comment['created_at']
+          }
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/ticket/relation_embedder.rb

@@ -0,0 +1,70 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class Ticket < BaseCollection
+      # Bulk-loads requester/assignee/organization records from the source
+      # tickets and writes them back onto the projected rows by index.
+      module RelationEmbedder
+        private
+
+        def embed_relations(records, rows, projection)
+          return if projection.nil?
+
+          relations = relations_in(projection)
+          return if relations.empty?
+
+          sources = records.map { |t| attrs_of(t) }
+          embed_users(rows, sources, relations) if (relations & %w[requester assignee]).any?
+          embed_organizations(rows, sources) if relations.include?('organization')
+        end
+
+        def embed_users(rows, sources, relations)
+          ids = sources.flat_map { |a| [a['requester_id'], a['assignee_id']] }.compact.uniq
+          users = datasource.client.fetch_users_by_ids(ids)
+          rows.each_with_index do |row, i|
+            row['requester'] = serialized_user(users[sources[i]['requester_id']]) if relations.include?('requester')
+            row['assignee']  = serialized_user(users[sources[i]['assignee_id']]) if relations.include?('assignee')
+          end
+        end
+
+        def embed_organizations(rows, sources)
+          ids = sources.filter_map { |a| a['organization_id'] }.uniq
+          orgs = datasource.client.fetch_organizations_by_ids(ids)
+          rows.each_with_index do |row, i|
+            row['organization'] = serialized_org(orgs[sources[i]['organization_id']])
+          end
+        end
+
+        def relations_in(projection)
+          Array(projection).map(&:to_s).filter_map { |p| p.split(':').first if p.include?(':') }.uniq
+        end
+
+        def serialized_user(raw)
+          return nil if raw.nil?
+
+          attrs = raw.is_a?(Hash) ? raw : attrs_of(raw)
+          {
+            'id' => attrs['id'], 'email' => attrs['email'], 'name' => attrs['name'],
+            'role' => attrs['role'], 'organization_id' => attrs['organization_id'],
+            'phone' => attrs['phone'], 'time_zone' => attrs['time_zone'],
+            'locale' => attrs['locale'], 'verified' => attrs['verified'],
+            'suspended' => attrs['suspended'], 'created_at' => attrs['created_at'],
+            'updated_at' => attrs['updated_at']
+          }
+        end
+
+        def serialized_org(raw)
+          return nil if raw.nil?
+
+          attrs = raw.is_a?(Hash) ? raw : attrs_of(raw)
+          {
+            'id' => attrs['id'], 'name' => attrs['name'],
+            'domain_names' => attrs['domain_names'], 'details' => attrs['details'],
+            'notes' => attrs['notes'], 'group_id' => attrs['group_id'],
+            'shared_tickets' => attrs['shared_tickets'],
+            'created_at' => attrs['created_at'], 'updated_at' => attrs['updated_at']
+          }
+        end
+      end
+    end
+  end
+end