dregs 0.1.0 → 1.0.0

data/lib/dregs/events.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "models"
+require_relative "resource"
+
+module Dregs
+  # The +client.events+ namespace: reading the events Dregs has recorded. To record one, use
+  # {Client#track}.
+  class Events < Resource
+    # Returns one page of events, newest first. Use {#list_all} to walk every page.
+    #
+    # @param identity [String, nil] only events from this identity
+    # @param group [String, nil] only events sent with the group with this id
+    # @param group_type [String, nil] only events sent with a group of this type
+    # @param device [String, nil] only events from the device with this fingerprint
+    # @param session [String, nil] only events from this browser session
+    # @param term [String, nil] free text matched against event names and data
+    # @param page [Integer] the page to return, counting from 0
+    # @param page_size [Integer, nil] items per page, at most 100
+    # @param sort [String, nil] the field to sort on, such as +"timestamp"+ or +"eventName"+
+    # @param order [Symbol, String, nil] +:asc+ or +:desc+
+    # @return [Page<Event>]
+    # @raise [ArgumentError] the page is negative or the order is not one of the two
+    def list(identity: nil, group: nil, group_type: nil, device: nil, session: nil, term: nil, page: 0,
+             page_size: nil, sort: nil, order: nil)
+      filters = list_filters(
+        identity: identity, group: group, group_type: group_type, device: device, session: session, term: term
+      )
+
+      list_page("/events", Event, filters, page: page, page_size: page_size, sort: sort, order: order)
+    end
+
+    # Walks every event that matches, fetching pages as it goes. Takes the filters {#list} does.
+    #
+    #   client.events.list_all(identity: "user_12345").each do |event|
+    #     puts "#{event.timestamp} #{event.name}"
+    #   end
+    #
+    # @return [Enumerator<Event>] a lazy enumerator, which fetches a page only when the items before
+    #   it have been used up; nil when a block is given, which is called with each event
+    # @raise [ArgumentError] the order is not one of the two
+    def list_all(identity: nil, group: nil, group_type: nil, device: nil, session: nil, term: nil,
+                 page_size: nil, sort: nil, order: nil, &block)
+      filters = list_filters(
+        identity: identity, group: group, group_type: group_type, device: device, session: session, term: term
+      )
+
+      list_every("/events", Event, filters, page_size: page_size, sort: sort, order: order, &block)
+    end
+
+    # Returns the event with this id.
+    #
+    # @param event_id [String] the event's id, either the one you sent or one Dregs generated
+    # @return [Event]
+    # @raise [NotFoundError] no event has this id
+    def get(event_id)
+      Event.from_api(@client.request(:get, "/events/#{segment(event_id, "An event id")}"))
+    end
+
+    private
+
+    def list_filters(identity:, group:, group_type:, device:, session:, term:)
+      {
+        "identity" => identity,
+        "group" => group,
+        "groupType" => group_type,
+        "device" => device,
+        "session" => session,
+        "term" => term
+      }
+    end
+  end
+end

data/lib/dregs/groups.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "models"
+require_relative "resource"
+
+module Dregs
+  # The +client.groups+ namespace: the organizations, teams, or workspaces your users belong to.
+  #
+  # {Client#track} already records groups and memberships as events arrive. These calls are for
+  # reading them back, and for keeping Dregs in step when something changes outside an event, such
+  # as a user leaving a team.
+  #
+  # A group is identified by its type and id together, so the calls that address one take both.
+  class Groups < Resource
+    # Returns one page of groups, most recently active first.
+    #
+    # The groups in a list leave out their attributes; {#get} returns them. Use {#list_all} to walk
+    # every page.
+    #
+    # @param group_type [String, nil] only groups of this type, such as +"team"+
+    # @param identity [String, nil] only groups this identity belongs to
+    # @param term [String, nil] free text matched against group ids and names
+    # @param page [Integer] the page to return, counting from 0
+    # @param page_size [Integer, nil] items per page, at most 100
+    # @param sort [String, nil] the field to sort on, such as +"displayName"+ or +"lastTrackedAt"+
+    # @param order [Symbol, String, nil] +:asc+ or +:desc+
+    # @return [Page<Group>]
+    # @raise [ArgumentError] the page is negative or the order is not one of the two
+    def list(group_type: nil, identity: nil, term: nil, page: 0, page_size: nil, sort: nil, order: nil)
+      filters = list_filters(group_type: group_type, identity: identity, term: term)
+
+      list_page("/groups", Group, filters, page: page, page_size: page_size, sort: sort, order: order)
+    end
+
+    # Walks every group that matches, fetching pages as it goes. Takes the filters {#list} does.
+    #
+    #   client.groups.list_all(group_type: "team", identity: "user_12345").each do |team|
+    #     puts "#{team.id} #{team.display_name}"
+    #   end
+    #
+    # @return [Enumerator<Group>] a lazy enumerator, which fetches a page only when the items before
+    #   it have been used up; nil when a block is given, which is called with each group
+    # @raise [ArgumentError] the order is not one of the two
+    def list_all(group_type: nil, identity: nil, term: nil, page_size: nil, sort: nil, order: nil, &block)
+      filters = list_filters(group_type: group_type, identity: identity, term: term)
+
+      list_every("/groups", Group, filters, page_size: page_size, sort: sort, order: order, &block)
+    end
+
+    # Returns the group, with its attributes.
+    #
+    #   group = client.groups.get("organization", "org_678")
+    #
+    #   group.identity_count  #=> 12
+    #
+    # @param group_type [String] the kind of group, such as +"organization"+
+    # @param group_id [String] your own id for the group
+    # @return [Group]
+    # @raise [NotFoundError] no group of this type has this id
+    def get(group_type, group_id)
+      Group.from_api(@client.request(:get, path_for(group_type, group_id)))
+    end
+
+    # Creates a group, or merges +attributes:+ into the group that already has this type and id,
+    # so it is safe to call on every sync.
+    #
+    #   client.groups.create("org_678", attributes: { name: "Acme Inc", plan: "enterprise" })
+    #
+    # @param group_id [String] your own id for the group
+    # @param group_type [String, nil] the kind of group; +"organization"+ when omitted
+    # @param attributes [Hash, nil] attributes such as a name or plan
+    # @return [Group]
+    def create(group_id, group_type: nil, attributes: nil)
+      segment(group_id, "A group id")
+
+      group_type = Client::DEFAULT_GROUP_TYPE if group_type.nil? || group_type.to_s.empty?
+      body = { "type" => group_type.to_s, "id" => group_id.to_s, "attributes" => attributes_hash(attributes) }
+
+      Group.from_api(@client.request(:post, "/groups", body: body))
+    end
+
+    # Merges +attributes+ into the group and returns it.
+    #
+    #   client.groups.update("organization", "org_678", { plan: "business" })
+    #
+    # @param group_type [String] the kind of group
+    # @param group_id [String] your own id for the group
+    # @param attributes [Hash] the attributes to merge
+    # @return [Group]
+    # @raise [NotFoundError] no group of this type has this id
+    def update(group_type, group_id, attributes)
+      body = { "attributes" => attributes_hash(attributes) }
+
+      Group.from_api(@client.request(:patch, path_for(group_type, group_id), body: body))
+    end
+
+    # Makes the identity a member of the group. Adding an existing member does nothing.
+    #
+    # @param group_type [String] the kind of group
+    # @param group_id [String] your own id for the group
+    # @param identity_id [String] your own id for the user
+    # @return [nil]
+    # @raise [NotFoundError] the group or the identity is unknown
+    def add_member(group_type, group_id, identity_id)
+      @client.request(:put, member_path(group_type, group_id, identity_id))
+
+      nil
+    end
+
+    # Removes the identity from the group, such as when a user leaves a team.
+    #
+    # @param group_type [String] the kind of group
+    # @param group_id [String] your own id for the group
+    # @param identity_id [String] your own id for the user
+    # @return [nil]
+    # @raise [NotFoundError] the group or the identity is unknown
+    def remove_member(group_type, group_id, identity_id)
+      @client.request(:delete, member_path(group_type, group_id, identity_id))
+
+      nil
+    end
+
+    private
+
+    def path_for(group_type, group_id)
+      "/groups/#{segment(group_type, "A group type")}/#{segment(group_id, "A group id")}"
+    end
+
+    def member_path(group_type, group_id, identity_id)
+      "#{path_for(group_type, group_id)}/identities/#{identity_segment(identity_id)}"
+    end
+
+    def list_filters(group_type:, identity:, term:)
+      { "type" => group_type, "identity" => identity, "term" => term }
+    end
+  end
+end

data/lib/dregs/identities.rb

@@ -1,20 +1,56 @@
 # frozen_string_literal: true
 
-require "uri"
-
 require_relative "models"
+require_relative "resource"
 
 module Dregs
   # The +client.identities+ namespace: reading identities, their scores, and the reasoning behind
-  # them.
+  # them, and the few writes that go with them.
   #
   # These methods are thin. They name the endpoint and hand the response to a model; the
   # transport, the retries, and the error mapping all live on {Client}.
-  class Identities
-    # @api private
-    # @param client [Client]
-    def initialize(client)
-      @client = client
+  class Identities < Resource
+    # Returns one page of identities, most recently updated first.
+    #
+    #   page = client.identities.list(term: "example.com", page_size: 50)
+    #
+    #   page.total_elements  #=> how many match in all
+    #
+    # Use {#list_all} to walk every page.
+    #
+    # @param term [String, nil] free text matched against ids, names, emails, and usernames
+    # @param group [String, nil] only members of the group with this id. Pair it with
+    #   +group_type:+ when your group ids are not unique across types.
+    # @param group_type [String, nil] only members of groups of this type
+    # @param device [String, nil] only identities seen on the device with this fingerprint
+    # @param badge [String, nil] only identities carrying the badge with this slug
+    # @param page [Integer] the page to return, counting from 0
+    # @param page_size [Integer, nil] items per page, at most 100
+    # @param sort [String, nil] the field to sort on, such as +"lastTrackedAt"+ or +"humanityScore"+
+    # @param order [Symbol, String, nil] +:asc+ or +:desc+
+    # @return [Page<Identity>]
+    # @raise [ArgumentError] the page is negative or the order is not one of the two
+    def list(term: nil, group: nil, group_type: nil, device: nil, badge: nil, page: 0, page_size: nil,
+             sort: nil, order: nil)
+      filters = list_filters(term: term, group: group, group_type: group_type, device: device, badge: badge)
+
+      list_page("/identities", Identity, filters, page: page, page_size: page_size, sort: sort, order: order)
+    end
+
+    # Walks every identity that matches, fetching pages as it goes. Takes the filters {#list} does.
+    #
+    #   client.identities.list_all(group: "org_678").each do |identity|
+    #     puts identity.display_email
+    #   end
+    #
+    # @return [Enumerator<Identity>] a lazy enumerator, which fetches a page only when the items
+    #   before it have been used up; nil when a block is given, which is called with each identity
+    # @raise [ArgumentError] the order is not one of the two
+    def list_all(term: nil, group: nil, group_type: nil, device: nil, badge: nil, page_size: nil, sort: nil,
+                 order: nil, &block)
+      filters = list_filters(term: term, group: group, group_type: group_type, device: device, badge: badge)
+
+      list_every("/identities", Identity, filters, page_size: page_size, sort: sort, order: order, &block)
     end
 
     # Returns the identity, with its current scores, badges, and attributes.
@@ -47,15 +83,48 @@ module Dregs
       Scores.from_api(@client.request(:get, path_for(identity_id, "/scores")))
     end
 
-    # Returns the most recent analysis cycle, with the observations behind each score.
+    # Returns an analysis cycle, with the observations behind each score.
     #
     # Use this when you need to show or log *why* an identity scored the way it did.
     #
+    #   analysis = client.identities.analysis("user_12345")
+    #   older = client.identities.analysis("user_12345", cycle_id: entry.cycle_id)
+    #
     # @param identity_id [String] your own id for the user
+    # @param cycle_id [Integer, nil] a past cycle to return, from {#history}; the most recent cycle
+    #   when omitted
     # @return [Analysis]
     # @raise [NotFoundError] the identity is unknown, or it has not been analyzed yet
-    def analysis(identity_id)
-      Analysis.from_api(@client.request(:get, path_for(identity_id, "/analysis")))
+    def analysis(identity_id, cycle_id: nil)
+      suffix = cycle_id.nil? ? "/analysis" : "/analysis/#{segment(cycle_id, "A cycle id")}"
+
+      Analysis.from_api(@client.request(:get, path_for(identity_id, suffix)))
+    end
+
+    # Returns the scores of past analysis cycles, newest first.
+    #
+    #   client.identities.history("user_12345", limit: 10).each do |entry|
+    #     puts "#{entry.finished_at} #{entry.humanity}"
+    #   end
+    #
+    # @param identity_id [String] your own id for the user
+    # @param limit [Integer, nil] the most cycles to return; the API's default is 100
+    # @return [Array<ScoreHistoryEntry>]
+    # @raise [NotFoundError] Dregs has never seen this identity
+    def history(identity_id, limit: nil)
+      payload = @client.request(:get, path_for(identity_id, "/history"), params: { "limit" => limit })
+
+      parse_each(ScoreHistoryEntry, payload)
+    end
+
+    # Returns the other identities Dregs believes are connected to this one, such as by a shared
+    # device.
+    #
+    # @param identity_id [String] your own id for the user
+    # @return [Array<LinkedIdentity>]
+    # @raise [NotFoundError] Dregs has never seen this identity
+    def links(identity_id)
+      parse_each(LinkedIdentity, @client.request(:get, path_for(identity_id, "/links")))
     end
 
     # Queues a re-analysis of the identity.
@@ -74,18 +143,66 @@ module Dregs
       nil
     end
 
+    # Updates an identity and returns it. Only what you pass is sent.
+    #
+    #   client.identities.update("qa_bot_7", disregarded: true)
+    #
+    # @param identity_id [String] your own id for the user
+    # @param disregarded [Boolean, nil] true to leave the identity out of scoring and escalations,
+    #   such as for your own staff or test accounts. Linked identities are re-scored.
+    # @param attributes [Hash, nil] attributes to merge into the identity, as +identity_data:+ on
+    #   {Client#track} would
+    # @return [Identity]
+    # @raise [NotFoundError] Dregs has never seen this identity
+    # @raise [ArgumentError] neither +disregarded:+ nor +attributes:+ was given
+    def update(identity_id, disregarded: nil, attributes: nil)
+      body = {}
+
+      body["disregarded"] = disregarded ? true : false unless disregarded.nil?
+      body["attributes"] = attributes_hash(attributes) unless attributes.nil?
+
+      raise ArgumentError, "Pass disregarded:, attributes:, or both." if body.empty?
+
+      Identity.from_api(@client.request(:patch, path_for(identity_id), body: body))
+    end
+
+    # Returns the AI reviews requested for this identity, newest first.
+    #
+    # @param identity_id [String] your own id for the user
+    # @return [Array<IdentityReview>]
+    # @raise [NotFoundError] Dregs has never seen this identity
+    def reviews(identity_id)
+      parse_each(IdentityReview, @client.request(:get, path_for(identity_id, "/reviews")))
+    end
+
+    # Asks Dregs's AI reviewer to look over the identity's analysis.
+    #
+    # The review runs in the background, so the result comes back +"PENDING"+. Read it again with
+    # {#reviews} once it has finished.
+    #
+    #   review = client.identities.review("user_12345", feedback: "This is a long-standing customer.")
+    #
+    #   review.status  #=> "PENDING"
+    #
+    # @param identity_id [String] your own id for the user
+    # @param feedback [String, nil] what you think the analysis got wrong, such as "this is a real
+    #   customer"
+    # @return [IdentityReview]
+    # @raise [NotFoundError] Dregs has never seen this identity
+    def review(identity_id, feedback: nil)
+      body = feedback.nil? || feedback.to_s.empty? ? {} : { "feedback" => feedback.to_s }
+
+      IdentityReview.from_api(@client.request(:post, path_for(identity_id, "/actions/review"), body: body))
+    end
+
     private
 
     def path_for(identity_id, suffix = "")
-      raise ArgumentError, "An identity id is required." if identity_id.nil? || identity_id.to_s.empty?
-
-      # Identity ids are the caller's own user ids and routinely contain characters that need
-      # escaping, an email address being the common one.
-      "/identities/#{escape(identity_id.to_s)}#{suffix}"
+      "/identities/#{identity_segment(identity_id)}#{suffix}"
     end
 
-    def escape(value)
-      URI.encode_www_form_component(value).gsub("+", "%20")
+    def list_filters(term:, group:, group_type:, device:, badge:)
+      { "term" => term, "group" => group, "groupType" => group_type, "device" => device, "badge" => badge }
     end
   end
 end