chameleon-ruby 0.1.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 063b39158b4215a5571222f799ac1780895db5710d667507041eb984985ab62f
+  data.tar.gz: 65939c62ec99e9e0bcd177515aa6faf54d291264c5e2273c8f203f0e259b1e31
+SHA512:
+  metadata.gz: 35920fd3e874f5a10aeaa6a1b2b9ac66186fa52f4a021cd9b8cdbe819c70ef6ee92b0c0e14c06e1356bb824891ee0717014a98c0f8e83b9bed7cf27117fbedd8
+  data.tar.gz: e13d11ac0ca4c0f8e0dbcf0031e44577253c610c6ab638153f6cf096ba8740bb9f3f3441674fb0127b564b08205060b831881dd29fdd9ffa31047e6969ce93cb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Brian Norton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# chameleon-ruby
+
+[![Gem Version](https://badge.fury.io/rb/chameleon-ruby.svg)](https://rubygems.org/gems/chameleon-ruby)
+[![CI](https://github.com/chamaeleonidae/chameleon-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/chamaeleonidae/chameleon-ruby/actions/workflows/ci.yml)
+
+A Ruby gem for simple interactions with the Chameleon APIs
+
+> Your API Secret is generated on the [Integrations page](https://app.chameleon.io/integrations/tokens). The Full API documentation can be found on our [Developer hub](https://developers.chameleon.io)!
+
+---
+
+- [Quick start](#quick-start)
+- [Usage and Examples](#usage-and-examples)
+- [Support](#support)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
+- [Contribution guide](#contribution-guide)
+
+## Quick start
+
+```ruby
+gem 'chameleon-ruby' # in your Gemfile
+```
+
+```ruby
+require 'chameleon' # if needed
+```
+
+## Usage and Examples
+
+```ruby
+# configs/initializers/chameleon/rb
+Chameleon.configure do |config|
+  config.secret = ENV['CHAMELEON_SECRET']
+end
+```
+
+```ruby
+##
+# In a Background job when content is created / updated
+#
+Chameleon::SearchItem.index(uid, title: title, actions: actions)
+
+##
+# More options and inspiration for what you can do
+#
+# This example assumes you have a model in your database called `Document` but
+#   this can be anything users can create in your system
+#
+
+uid = "documents:#{model.id}" # or "#{model.class.name.underscore}:#{model.id}"
+
+title = model.name # the main unit of searchability; for a document this is the user generated title; for a
+description = model.description # user generated description; may include tags or other identifying info about this content
+
+actions = [{ kind: 'navigate', url: "/documents/#{model.id}/edit" }]                      # navigate to /documents/3327/edit when clicked
+# or
+actions = [{ kind: 'navigate', url: "/#{model.class.name.underscore}/#{model.id}/edit" }] # navigate to /documents/3327/edit when clicked
+
+icon = { kind: 'uid', uid: 'cog' } # the icon displayed for this item from the Chameleon icon library
+# or
+icon = { kind: 'image', image_url: 'https://cdn-icons-png.flaticon.com/512/9908/9908192.png' } # the icon displayed for this item from a public url
+
+##
+# Index the content by uid
+#
+Chameleon::SearchItem.index(uid, title: title, actions: actions)
+
+# Remove when deleted/archived in your system or no longer searchable
+#
+Chameleon::SearchItem.remove(uid)
+
+##
+# Add a user-generated description, if you have it
+#
+Chameleon::SearchItem.index(uid, title: title, description: description, actions: actions)
+
+##
+# Customize the icon from the Chameleon icon library
+#
+icon = { kind: 'uid', uid: 'cog' } # the icon displayed for this item from the Chameleon icon library
+Chameleon::SearchItem.index(uid, title: title, actions: actions, icon: icon)
+
+##
+# To restrict content to a specific Chameleon user, set the profile_uids to just that single user
+#   This is the only user that will be able to find this content
+#
+# Use cases:
+#   - This document is only visible to the creator
+#   - This design or prototype has not been shared yet
+#   - A part of the users' onboarding that is not yet complete
+#
+Chameleon::SearchItem.index(uid, title: title, description: description, actions: actions, profile_uids: [user.id])
+
+##
+# Now to extend the Use case to a Document that the creator shares with their co-workers
+#   This example assumes that Document has an array of User IDs (an ACL) to share with
+#
+Chameleon::SearchItem.index(uid, title: title, actions: actions, profile_uids: [user.id, *document.shared_to_user_ids])
+
+##
+# To restrict content to a specific Chameleon company, set the company_uids to just that single company
+#   This is the only company that will be able to find this content -- all users in this company are able to search for it
+#
+# Use cases:
+#   - This document is only visible to the Company/Account/Tenant of the creator
+#   - This design or prototype has been published/shared to your Company
+#   - A part of the company's onboarding that is not yet complete
+#
+Chameleon::SearchItem.index(uid, title: title, actions: actions, company_uids: [company.id])
+
+##
+# To restrict content to a specific Chameleon Segment, set the segment_ids to one or many Segments
+#   Only current members of these Segments will be able to search for this content
+#
+# Use cases:
+#   - This document is only visible to Company/Account/Tenant administrators (Segment is set to "roles contains admin")
+#   - This page is only available to the Enterprise plan (Segment is set to is "plan is enterprise")
+#   - An upsell prompt is only relevant for trialing users (Segment is set to "plan_status is trialing")
+#
+Chameleon::SearchItem.index(uid, title: title, actions: actions, segment_ids: [segment1_id, segment2_id])
+```
+
+#### Support
+
+If you want to report a bug, or have ideas, feedback or questions about the gem itself, [let us know via GitHub issues](https://github.com/chamaeleonidae/chameleon-ruby/issues/new) and the Chameleon team will do their best to provide a helpful answer.
+Or another to reach us is to [Contact us](https://app.chameleon.io/help) in your dashboard. 
+
+#### License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+#### Code of conduct
+
+Everyone interacting in this project’s codebases and issue trackers is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+#### Contribution guide
+
+Pull requests are welcome!

data/lib/chameleon/config.rb

@@ -0,0 +1,10 @@
+module Chameleon
+  class Config
+    attr_accessor :secret, :base_url, :user_agent, :use_staging
+
+    def initialize
+      self.base_url = 'https://api.chameleon.io'
+      self.user_agent = "Chameleon Ruby v#{VERSION} (chameleon.io)"
+    end
+  end
+end

data/lib/chameleon/errors.rb

@@ -0,0 +1,42 @@
+module Chameleon
+  module Errors
+    # When a model does not have all of the required attributes
+    class Invalid < StandardError; end
+
+    # When the Chameleon API returns an error
+    #
+    class ApiError < StandardError
+      attr_reader :request, :response, :status, :body, :messages
+
+      def initialize(request, response)
+        @request = request
+        @response = response
+        @status = response.code
+        @body = JSON.parse(response.body) rescue response.body
+        @messages = @body['messages'].is_a?(Array) ? @body['messages'] : []
+
+        super("Chameleon API error with code: #{status}, message: #{messages[1] || 'Unknown error'}")
+      end
+    end
+
+    class AuthError < ApiError; end             # 403
+    class NotFoundError < ApiError; end         # 404
+    class ConflictError < ApiError; end         # 409
+    class InputError < ApiError; end            # 422
+    class RateLimitError < ApiError; end        # 429
+    class ServerError < ApiError; end           # 500
+    class TimeoutError < ApiError; end          # 503
+
+    VIA_STATUS_CODE = Hash.new(ApiError)
+    VIA_STATUS_CODE.merge!(
+      403 => AuthError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => InputError,
+      429 => RateLimitError,
+      500 => ServerError,
+      503 => TimeoutError,
+    )
+    VIA_STATUS_CODE.freeze
+  end
+end

data/lib/chameleon/model.rb

@@ -0,0 +1,78 @@
+class Chameleon::Model
+  attr_accessor :id
+  attr_reader :attributes
+
+  def initialize(attributes={})
+    @attributes = {}
+
+    refresh(attributes)
+  end
+
+  def [](key)
+    @attributes[key.to_s]
+  end
+
+  def []=(key, value)
+    @attributes[key.to_s] = Chameleon::Support.value_of(value)
+  end
+
+  def model_name
+    Chameleon::Support.underscore(self.class.name.gsub('Chameleon::', ''))
+  end
+
+  def clear
+    @attributes.clear
+  end
+
+  def refresh(attributes)
+    return self unless attributes.respond_to?(:each_pair)
+
+    attributes.each_pair { |key, value| @attributes[key.to_s] = Chameleon::Support.value_of(value) }
+    @id = @attributes.delete('id') if @attributes.key?('id')
+    self
+  end
+
+  def url
+    base = "/v3/edit/#{Chameleon::Support.pluralize(model_name)}"
+    base << "/#{id}" if id
+    base
+  end
+
+  def create
+    Chameleon::Request.post(self)
+  end
+
+  def fetch
+    Chameleon::Request.get(self)
+  end
+
+  def delete
+    Chameleon::Request.delete(self)
+  end
+
+  def inspect
+    string = "#<#{self.class.name}"
+    string << " id=#{id}" if id
+    string << " attributes=#{attributes}"
+    string << '>'
+  end
+
+  private
+
+  def respond_to_missing?(symbol, other)
+    key = symbol.to_s
+    key[-1] == '=' || @attributes.key?(key)
+  end
+
+  def method_missing(symbol, *args)
+    key = symbol.to_s
+
+    if key[-1] == '=' # setter
+      self[key[0..-2]] = args.first
+    elsif @attributes.key?(key)
+      self[key]
+    else
+      super
+    end
+  end
+end

data/lib/chameleon/models/company.rb

@@ -0,0 +1,43 @@
+module Chameleon
+  class Company < Chameleon::Model
+    # https://developers.chameleon.io/#/webhooks/companies
+
+    ##
+    # Identify an account/Company/tenant to Chameleon
+    #
+    # @param uid The database ID for this Company (same as the uid passed to `chmln.identify` in the JS API)
+    # @param options Any additional user data you want Chameleon to know about
+    #
+    # @returns Chameleon::Company
+    #
+    def self.identify(uid, options={})
+      item = new(options.merge(uid: uid))
+      item.save
+      item
+    end
+
+    ##
+    # Retrieve an Chameleon Company
+    #
+    # @param uid The database ID for this Company (same as the uid passed to `chmln.identify` in the JS API)
+    #
+    # @returns Chameleon::Company
+    #
+    def self.fetch(uid)
+      item = new(uid: uid)
+      item.fetch
+      item
+    end
+
+    def url
+      path = 'v3/analyze/company'
+      path.gsub!(/y$/, "ies/#{id}") if id
+      path
+    end
+
+    def save
+      Chameleon::Request.model_request(:post, self, path: 'v3/observe/hooks/companies')
+    end
+
+  end
+end

data/lib/chameleon/models/deletion.rb

@@ -0,0 +1,5 @@
+module Chameleon
+  class Deletion < Chameleon::Model
+    # placeholder model that will have only an `id` field
+  end
+end

data/lib/chameleon/models/event.rb

@@ -0,0 +1,24 @@
+module Chameleon
+  class Event < Chameleon::Model
+    # https://developers.chameleon.io/#/webhooks/events
+
+    ##
+    # Track an Event user to Chameleon
+    #
+    # @param uid The database ID for this user (same as the uid passed to `chmln.identify` in the JS API)
+    # @param name The human-readable name for this event
+    # @param options Any additional user data you want Chameleon to know about
+    #
+    # @returns Chameleon::Event
+    #
+    def self.track(uid, name, options={})
+      item = new(options.merge(uid: uid, name: name))
+      item.save
+      item
+    end
+
+    def save
+      Chameleon::Request.model_request(:post, self, path: 'v3/observe/hooks/events')
+    end
+  end
+end

data/lib/chameleon/models/profile.rb

@@ -0,0 +1,54 @@
+module Chameleon
+  class Profile < Chameleon::Model
+    # https://developers.chameleon.io/#/webhooks/profiles
+
+    ##
+    # Identify a user to Chameleon
+    #
+    # @param uid The database ID for this user (same as the uid passed to `chmln.identify` in the JS API)
+    # @param options Any additional user data you want Chameleon to know about
+    #
+    # @returns Chameleon::Profile
+    #
+    def self.identify(uid, options={})
+      item = new(options.merge(uid: uid))
+      item.save
+      item
+    end
+
+    ##
+    # Retrieve a Chameleon user profile
+    #
+    # @param uid The database ID for this user (same as the uid passed to `chmln.identify` in the JS API)
+    #
+    # @returns Chameleon::Profile
+    #
+    def self.fetch(uid)
+      item = new(uid: uid)
+      item.fetch
+      item
+    end
+
+    ##
+    # Remove this user from Chameleon and purge all of their associated data
+    #
+    # @param uid The database ID for this user (same as the uid passed to `chmln.identify` in the JS API)
+    # @returns Chameleon::Deletion
+    #
+    def self.forget(uid)
+      response = Chameleon::Request.request(:delete, 'v3/edit/profiles/forget', options: { uid: uid })
+      Chameleon::Deletion.new(JSON.parse(response.body)['deletion'])
+    end
+
+    def url
+      path = 'v3/analyze/profile'
+      path << "s/#{id}" if id
+      path
+    end
+
+    def save
+      Chameleon::Request.model_request(:post, self, path: 'v3/observe/hooks/profiles')
+    end
+
+  end
+end

data/lib/chameleon/models/search_item.rb

@@ -0,0 +1,69 @@
+module Chameleon
+  class SearchItem < Chameleon::Model
+    # https://developers.chameleon.io/#/apis/search
+
+    ##
+    # Add a SearchItem to the HelpBar search index
+    #
+    # @param uid The unique ID you assign for this piece of content
+    #
+    # @param options
+    # @param options[:title] The title of the content
+    # @param options[:description] The description of the content; how your user would describe it in their words
+    #
+    # @param options[:actions] An Array of the actions to take when clicking/selecting this item
+    #
+    # Content in the HelpBar can be Pinned and will display as default items when the HelpBar is first opened
+    #
+    # @param options[:pinned_at] A timestamp representing the ordering of pinned content (1.hour.ago will display above 1.day.ago)
+    #
+    # To add a specific icon to this; by default icons are inherited from the search group they are added to.
+    #
+    # @param options[:icon] The hash specifying which icon to use
+    # @param options[:icon][:kind] One of 'uid' or 'image'
+    # @param options[:icon][:uid] Required with kind=uid: The Chameleon Icon uid from the Icon library
+    # @param options[:icon][:image_url] Required with kind=image: The URL of an icon to use
+    #
+    # For the following params, your end-user will first be matched against these groups to build the set
+    #   of searchable content they have access to, then the search is performed on only the filtered content.
+    #
+    # @param options[:profile_uids] The UID (your database ID) of the Chameleon User Profiles this is searchable for (same as the uid passed to `chmln.identify` in the JS API)
+    # @param options[:company_uids] The UID (your database ID) of the Chameleon Companies this is searchable for (same as the uid passed to `chmln.identify` in the JS API)
+    # @param options[:segment_ids] The ID of the Chameleon Segments this is searchable for (found on https://app.chameleon.io/segments)
+    #
+    def self.index(uid, options)
+      item = new(options.merge(uid: uid))
+      item.create
+      item
+    end
+
+    ##
+    # Retrieve a Chameleon Search item
+    #
+    # @param uid The unique ID you previously assigned to this piece of content
+    #
+    # @returns Chameleon::SearchItem
+    #
+    def self.fetch(uid)
+      item = new(uid: uid)
+      item.fetch
+      item
+    end
+
+    ##
+    # Remove the SearchItem with the given uid from the HelpBar search index
+    #
+    # @param uid The unique ID you previously assigned to this piece of content
+    #
+    def self.remove(uid)
+      item = new(uid: uid)
+      item.delete
+      item
+    end
+
+    def url
+      'v3/edit/search_items'
+    end
+
+  end
+end

data/lib/chameleon/request.rb

@@ -0,0 +1,64 @@
+module Chameleon
+  class Request
+    def self.get(model)
+      raise ArgumentError, 'Fetching a Chameleon model requires at `id` or `uid`' unless model.id || model.uid
+
+      model_request :get, model, options: model.attributes.slice(*%w[uid]).compact
+    end
+
+    def self.post(model)
+      model_request :post, model
+    end
+
+    def self.patch(model)
+      model_request :patch, model
+    end
+
+    def self.delete(model)
+      model_request :delete, model, options: model.attributes.slice(*%w[uid]).compact
+      model.clear
+      model.deleted_at = Time.now
+      model
+    end
+
+    def self.model_request(method, model, options: model.attributes, path: nil)
+      response = request(method, path || model.url, options: options)
+      body = JSON.parse(response.body)
+
+      model.refresh(body[model.model_name])
+      model
+    end
+
+    def self.request(method, path, options: {})
+      url = "#{Chameleon.config.base_url}/#{path.gsub(/^\//, '')}"
+      url = staging_url(url) if Chameleon.config.use_staging
+      req_opts = { method: method, accept_encoding: 'gzip', headers: { 'X-Account-Secret' => Chameleon.config.secret, 'User-Agent' => Chameleon.config.user_agent } }
+
+      request = if %i[get delete].include?(method)
+        Typhoeus::Request.new(url, req_opts.merge(params: options))
+      else
+        req_opts[:headers]['Content-Type'] = 'application/json'
+
+        Typhoeus::Request.new(url, req_opts.merge(body: JSON.dump(options)))
+      end
+
+      response = request.run
+      error(request, response) if response.code > 300
+
+      response
+    end
+
+    def self.error(request, response)
+      raise Chameleon::Errors::VIA_STATUS_CODE[response.code].new(request, response)
+    end
+
+    ##
+    # Chameleon staging postfixes `-staging` on the environment
+    #
+    def self.staging_url(url)
+      env = /v3\/([^\/]+)\// =~ url && Regexp.last_match[1]
+
+      "https://#{env}-staging.#{url.split('.', 2)[1]}".gsub("/#{env}/", '/')
+    end
+  end
+end

data/lib/chameleon/support.rb

@@ -0,0 +1,39 @@
+class Chameleon::Support
+  def self.value_of(value)
+    value = case value
+    when Array then value.map { |v| value_of(v) }.compact
+    when Hash then value.dup.tap { |v| v.each_key { |k| v[k] = value_of(v[k]) } }
+    when String
+      value = value.strip
+
+      case value
+      when '' then nil
+      when /^true$/i then true
+      when /^false$/i then false
+      when '$now' then Time.now
+      when /^\d{4}-(0[1-9]|1[0-2])-([0-2][1-9]|[1-3]0|3[01])/ then DateTime.parse(value).to_time
+      when /^-?\d+\.\d+(e\d+)?$/ then value.to_f
+      when /^-?\d+$/ then value.to_i
+      else value
+      end
+    else value
+    end
+
+    value
+  end
+
+  def self.underscore(string)
+    string.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2'.freeze)
+    string.gsub!(/([a-z\d])([A-Z])/, '\1_\2'.freeze)
+    string.downcase!
+    string
+  end
+
+  ##
+  # super naive yes, but effective for the use case here; special cases can be added if needed
+  #
+  def self.pluralize(string)
+    string += 's'
+    string
+  end
+end

data/lib/chameleon/version.rb

@@ -0,0 +1,3 @@
+module Chameleon
+  VERSION = '0.1.6'.freeze
+end

data/lib/chameleon.rb

@@ -0,0 +1,23 @@
+module Chameleon
+  autoload :VERSION, 'chameleon/version'
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure(&block)
+    yield config
+  end
+end
+
+require 'time'
+require 'typhoeus'
+require 'json'
+
+require 'chameleon/config'
+require 'chameleon/errors'
+require 'chameleon/model'
+require 'chameleon/request'
+require 'chameleon/support'
+
+Dir[File.expand_path('chameleon/models/*.rb', __dir__)].sort.each { |f| require(f) }

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: chameleon-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.6
+platform: ruby
+authors:
+- Brian Norton
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-03-23 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- brian.nort@gmail.com
+- brian@chameleon.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/chameleon.rb
+- lib/chameleon/config.rb
+- lib/chameleon/errors.rb
+- lib/chameleon/model.rb
+- lib/chameleon/models/company.rb
+- lib/chameleon/models/deletion.rb
+- lib/chameleon/models/event.rb
+- lib/chameleon/models/profile.rb
+- lib/chameleon/models/search_item.rb
+- lib/chameleon/request.rb
+- lib/chameleon/support.rb
+- lib/chameleon/version.rb
+homepage: https://github.com/chamaeleonidae/chameleon-ruby
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/chamaeleonidae/chameleon-ruby/issues
+  changelog_uri: https://github.com/chamaeleonidae/chameleon-ruby/releases
+  source_code_uri: https://github.com/chamaeleonidae/chameleon-ruby
+  homepage_uri: https://github.com/chamaeleonidae/chameleon-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: A Ruby gem wrapper for the Chameleon REST API
+test_files: []