fathom_api 0.0.1.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 383fe933e050720106a996b57b7e38b57dac79a43519e9f805841a6451f0e109
-  data.tar.gz: 4e84e923b29770c5d378d62b588d14b3ad45d48926aae63f2c817e6881a6e57e
+  metadata.gz: 2b56f8631f9278d0a5e8631b168d07b807ef191896284e69711fac634da46efe
+  data.tar.gz: c66e9928e9c6ebff67d46fbe7479220bdbf13489a070c9e390a6f096294a3782
 SHA512:
-  metadata.gz: 01420b80e38343bce522d01685ba5cfd3105c42993a68e0304ebc8dd351d5bc27ccec3803742202c8de966a1544c025a7fbb3e62d1b5da945f6620bd5228f91b
-  data.tar.gz: b93cf09226c87fec0e98a9d10eaa1cac00d9df90a26e0ed98ea3c5708887fac668ea36114c64e2b789be32ffa66e394cebc8d78f3274845bea42e182630c13d9
+  metadata.gz: 3b0bb564ab470ae7e84af648dfd9d16ba792bee3366e54dd1ea4308d30b0457c6e46967fafcd3fe03af8ab5f04c7dd0a59936eec8f24bc853904e0b2b8511e20
+  data.tar.gz: be65304241b52804ed71a5830a75d06aa6be83a0d9015a1d4ccc04ad24de4977ff5058cee0db14b6b6b588a025f72d2499291f097aa923bed95b5d3e1438b3db

data/.github/workflows/main.yml

@@ -1,18 +1,31 @@
-name: Ruby
-
-on: [push,pull_request]
+name: Tests
+on:
+  pull_request:
+    branches:
+      - "*"
+  push:
+    branches:
+      - main
 
 jobs:
-  build:
+  tests:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ["2.7", "3.0"]
+
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 3.0.0
-    - name: Run the default task
-      run: |
-        gem install bundler -v 2.2.3
-        bundle install
-        bundle exec rake
+      - uses: actions/checkout@main
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: StandardRb check
+        run: bundle exec standardrb
+
+      - name: Run tests
+        run: |
+          bundle exec rake test

data/Gemfile

@@ -8,3 +8,5 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "minitest", "~> 5.0"
+
+gem "standard"

data/Gemfile.lock

@@ -1,21 +1,74 @@
 PATH
   remote: .
   specs:
-    fathom_api (0.0.1.1)
+    fathom_api (0.1.0)
+      faraday (~> 1.7)
+      faraday_middleware (~> 1.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.2)
+    faraday (1.7.0)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
+      faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0.1)
+      faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.1)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
+      multipart-post (>= 1.2, < 3)
+      ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
+    faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
+    faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    faraday_middleware (1.1.0)
+      faraday (~> 1.0)
     minitest (5.14.4)
+    multipart-post (2.1.1)
+    parallel (1.20.1)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
     rake (13.0.6)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rubocop (1.18.4)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.8.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.10.0)
+      parser (>= 3.0.1.1)
+    rubocop-performance (1.11.4)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
+    standard (1.1.7)
+      rubocop (= 1.18.4)
+      rubocop-performance (= 1.11.4)
+    unicode-display_width (2.0.0)
 
 PLATFORMS
   x86_64-darwin-20
+  x86_64-linux
 
 DEPENDENCIES
   fathom_api!
   minitest (~> 5.0)
   rake (~> 13.0)
+  standard
 
 BUNDLED WITH
    2.2.3

data/README.md

@@ -1,45 +1,128 @@
-# FathomApi
-
 ### Hello there! This gem is a placeholder and will be updated and working soon. Please do not install it yet.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fathom_api`. To experiment with that code, run `bin/console` for an interactive prompt.
+# Fathom API
+
+### 🛠 An easy to use client with the Fathom API
+
+You'll need a usefathom.com account to use the API, if you don't have one [click here to sign up](https://usefathom.com/ref/CVNWHD).
 
-TODO: Delete this and the text above, and describe your gem
+As of August 17th, 2021 the API was still early-access, so some endpoints may be different than in production. Feel free to submit a PR or issue. Contributions are welcome!
+
+[![Build Status](https://github.com/afomera/fathom_api/workflows/Tests/badge.svg)](https://github.com/afomera/fathom_api/actions) [![Gem Version](https://badge.fury.io/rb/fathom_api.svg)](https://badge.fury.io/rb/fathom_api)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add `fathom_api` to your application's Gemfile:
+
+```bash
+bundle add fathom_api
+
+# OR in the Gemfile
+gem "fathom_api"
+```
+
+## Usage
+
+Create a client to get started, passing an `api_key` you generate in your Fathom API settings.
 
 ```ruby
-gem 'fathom_api'
+client = Fathom::Client.new(api_key: ENV['FATHOM_API_KEY'])
 ```
 
-And then execute:
+### Fetch account details
 
-    $ bundle install
+```ruby
+# Get account details
+client.account.info
+# => Fathom::Account
+```
 
-Or install it yourself as:
+Responses are wrapped in an object that dynamically allows you to call the attributes as if they are an OpenStruct... IE
 
-    $ gem install fathom_api
+```ruby
+response = client.account.info
+# => #<Fathom::Account:0x00007fee844068c8 @attributes=#<OpenStruct id=12345, name="Your account name", email="you@starfleet.org", object="account">>
 
-## Usage
+response.name
+# => "Your account name"
+response.email
+# => "you@starfleet.org"
+```
+
+### A note on Fathom::List objects
+
+When an API's response comes back with a object of "list", we automatically wrap that to attempt to provide some helper methods to ease your implementations.
+
+```ruby
+list = client.sites.list
+# => Fathom::List
 
-TODO: Write usage instructions here
+# get the cursor you can pass to the next request's starting_after param
+list.next_page
+# or get the ending_before param's cursor
+list.prev_page
 
-## Development
+# check if the list has more after it with
+list.has_more?
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Sites
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+client.sites.list
+# Optionally, pass params in to filter / limit responses
+# Limit can be between 1 and 100
+client.sites.list(limit: 1, starting_after: "SITE_ID")
+# => Fathom::List
+
+client.sites.retrieve(site_id: site_id)
+client.sites.create({}) # Include `name` and other params
+client.sites.update(site_id: site_id, {}) # Params being updated
+client.sites.delete(site_id: site_id)
+client.sites.wipe(site_id: site_id)
+# All return
+# => Fathom::Site
+```
 
-## Contributing
+### Events
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fathom_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/fathom_api/blob/master/CODE_OF_CONDUCT.md).
+```ruby
+client.events.list(site_id: site_id)
+# => Fathom::List
+# Optionally, pass params in to filter / limit responses
+# Limit can be between 1 and 100
+client.events.list(site_id: site_id, limit: 10, starting_after: "EVENT_ID")
+# => Fathom::List
+
+client.events.retrieve(site_id: site_id, event_id: event_id)
+client.events.create(site_id: site_id, {}) # Attributes for event
+client.events.update(site_id: site_id, {}) # Attributes being updated
+client.events.delete(site_id: site_id, event_id: event_id)
+client.events.wipe(site_id: site_id, event_id: event_id)
+# All return
+# Fathom::Event
+```
 
-## License
+### Current Visitors
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```ruby
+client.current_visitors(site_id: site_id, {}) # Can add detailed: true for a more detailed report
+```
+
+### Aggregation
+
+```ruby
+client.aggregations.list(entity_id: entity_id, entity_type: entity_type, aggregates: aggregates, **params)
+```
+
+## 🙏 Contributing
+
+This project uses Standard for formatting Ruby code. Please make sure to run standardrb before submitting pull requests. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/afomera/fathom_api/blob/main/CODE_OF_CONDUCT.md).
 
 ## Code of Conduct
 
-Everyone interacting in the FathomApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/fathom_api/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the FathomApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/afomera/fathom_api/blob/main/CODE_OF_CONDUCT.md).
+
+## 📝 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -11,5 +11,9 @@ require "fathom_api"
 # require "pry"
 # Pry.start
 
+client = Fathom::Client.new(api_key: ENV['FATHOM_API_KEY'])
+
+
+puts "`client` is now set with the api_key equal to ENV['FATHOM_API_KEY']"
 require "irb"
 IRB.start(__FILE__)

data/fathom_api.gemspec

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "lib/fathom_api/version"
+require_relative "lib/fathom/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "fathom_api"
-  spec.version       = FathomApi::VERSION
-  spec.authors       = ["Andrea Fomera"]
-  spec.email         = ["afomera@hey.com"]
-
-  spec.summary       = "A gem for using the Fathom API"
-  spec.homepage      = "https://github.com/afomera/fathom_api"
-  spec.license       = "MIT"
+  spec.name = "fathom_api"
+  spec.version = Fathom::VERSION
+  spec.authors = ["Andrea Fomera"]
+  spec.email = ["afomera@hey.com"]
+
+  spec.summary = "A gem for using the Fathom API"
+  spec.homepage = "https://github.com/afomera/fathom_api"
+  spec.license = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
-
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/afomera/fathom_api"
   # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
@@ -23,13 +22,10 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
-
-  # For more information and examples about making a new gem, checkout our
-  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.add_dependency "faraday", "~> 1.7"
+  spec.add_dependency "faraday_middleware", "~> 1.1"
 end

data/lib/fathom.rb

@@ -0,0 +1,31 @@
+require "faraday"
+require "faraday_middleware"
+require "fathom/version"
+
+module Fathom
+  autoload :Client, "fathom/client"
+  autoload :Resource, "fathom/resource"
+  autoload :Object, "fathom/object"
+
+  # Resources (like high level API endpoints)
+  autoload :AccountResource, "fathom/resources/account"
+  autoload :AggregationsResource, "fathom/resources/aggregations"
+  autoload :CurrentVisitorsResource, "fathom/resources/current_visitors"
+  autoload :EventsResource, "fathom/resources/events"
+  autoload :SitesResource, "fathom/resources/sites"
+
+  # Objects we wrap the responses in
+  autoload :Account, "fathom/objects/account"
+  autoload :Event, "fathom/objects/event"
+  autoload :List, "fathom/objects/list"
+  autoload :Site, "fathom/objects/site"
+
+  class Error < StandardError; end
+
+  def self.build_object(data)
+    return data unless data.is_a?(Hash)
+    type = data.fetch("object", "object")
+    class_name = type.split("_").map(&:capitalize).join
+    Fathom.const_get(class_name).new(data)
+  end
+end

data/lib/fathom/client.rb

@@ -0,0 +1,41 @@
+module Fathom
+  class Client
+    BASE_URL = "https://api.usefathom.com/v1"
+
+    attr_reader :api_key, :adapter
+
+    def initialize(api_key:, adapter: Faraday.default_adapter)
+      @api_key = api_key
+      @adapter = adapter
+    end
+
+    def account
+      AccountResource.new(self)
+    end
+
+    def aggregations
+      AggregationsResource.new(self)
+    end
+
+    def current_visitors
+      CurrentVisitorsResource.new(self)
+    end
+
+    def events
+      EventsResource.new(self)
+    end
+
+    def sites
+      SitesResource.new(self)
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.url_prefix = BASE_URL
+        conn.request :json
+        conn.response :json, content_type: "application/json"
+        conn.adapter adapter
+      end
+    end
+  end
+end

data/lib/fathom/object.rb

@@ -0,0 +1,18 @@
+require "ostruct"
+
+module Fathom
+  class Object
+    def initialize(attributes)
+      @attributes = OpenStruct.new(attributes)
+    end
+
+    def method_missing(method, *args, &block)
+      attribute = @attributes.send(method, *args, &block)
+      attribute.is_a?(Hash) ? Object.new(attribute) : attribute
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      true
+    end
+  end
+end

data/lib/fathom/objects/account.rb

@@ -0,0 +1,4 @@
+module Fathom
+  class Account < Object
+  end
+end

data/lib/fathom/objects/event.rb

@@ -0,0 +1,4 @@
+module Fathom
+  class Event < Object
+  end
+end

data/lib/fathom/objects/list.rb

@@ -0,0 +1,22 @@
+module Fathom
+  class List < Object
+    def initialize(attributes)
+      super
+      @attributes["data"].map! do |entry|
+        Fathom.build_object(entry)
+      end
+    end
+
+    def has_more?
+      @attributes["has_more"]
+    end
+
+    def next_page
+      @attributes["data"].last.id
+    end
+
+    def prev_page
+      @attributes["data"].first.id
+    end
+  end
+end

data/lib/fathom/objects/site.rb

@@ -0,0 +1,4 @@
+module Fathom
+  class Site < Object
+  end
+end

data/lib/fathom/resource.rb

@@ -0,0 +1,54 @@
+module Fathom
+  class Resource
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    def get_request(url, params: {}, headers: {})
+      handle_response client.connection.get(url, params, default_headers.merge(headers))
+    end
+
+    def post_request(url, body:, headers: {})
+      handle_response client.connection.post(url, body, default_headers.merge(headers))
+    end
+
+    def patch_request(url, body:, headers: {})
+      handle_response client.connection.patch(url, body, default_headers.merge(headers))
+    end
+
+    def put_request(url, body:, headers: {})
+      handle_response client.connection.put(url, body, default_headers.merge(headers))
+    end
+
+    def delete_request(url, params: {}, headers: {})
+      handle_response client.connection.delete(url, params, default_headers.merge(headers))
+    end
+
+    def default_headers
+      {Authorization: "Bearer #{client.api_key}"}
+    end
+
+    def handle_response(response)
+      case response.status
+      when 400
+        raise Error, "Your request was malformed. #{response.body}"
+      when 401
+        raise Error, "You did not supply valid authentication credentials. #{response.body}"
+      when 403
+        raise Error, "You are not allowed to perform that action. #{response.body}"
+      when 404
+        raise Error, "No results were found for your request. #{response.body}"
+      when 429
+        raise Error, "Your request exceeded the API rate limit. #{response.body}"
+      when 500
+        raise Error, "We were unable to perform the request due to server-side problems. #{response.body}"
+      end
+
+      Fathom.build_object(response.body)
+    end
+  end
+end

data/lib/fathom/resources/account.rb

@@ -0,0 +1,7 @@
+module Fathom
+  class AccountResource < Resource
+    def info
+      get_request("account")
+    end
+  end
+end

data/lib/fathom/resources/aggregations.rb

@@ -0,0 +1,9 @@
+module Fathom
+  class AggregationsResource < Resource
+    # TODO: Ensure this works properly
+    def list(entity_id:, entity_type:, aggregates:, **params)
+      get_request("aggregations", params: params.merge(entity_id: entity_id,
+        entity_type: entity_type, aggregates: aggregates))
+    end
+  end
+end

data/lib/fathom/resources/current_visitors.rb

@@ -0,0 +1,7 @@
+module Fathom
+  class CurrentVisitorsResource < Resource
+    def list(site_id:, **params)
+      get_request("current_visitors", params: params.merge(site_id: site_id))
+    end
+  end
+end

data/lib/fathom/resources/events.rb

@@ -0,0 +1,27 @@
+module Fathom
+  class EventsResource < Resource
+    def list(site_id:, **params)
+      get_request("sites/#{site_id}/events", params: params)
+    end
+
+    def retrieve(site_id:, event_id:)
+      get_request("sites/#{site_id}/events/#{event_id}")
+    end
+
+    def create(site_id:, **attributes)
+      post_request("sites/#{site_id}/events", body: attributes)
+    end
+
+    def update(site_id:, event_id:, **attributes)
+      post_request("sites/#{site_id}/events/#{event_id}", body: attributes)
+    end
+
+    def delete(site_id:, event_id:)
+      delete_request("sites/#{site_id}/events/#{event_id}")
+    end
+
+    def wipe(site_id:, event_id:)
+      delete_request("sites/#{site_id}/events/#{event_id}/data")
+    end
+  end
+end

data/lib/fathom/resources/sites.rb

@@ -0,0 +1,27 @@
+module Fathom
+  class SitesResource < Resource
+    def list(**params)
+      get_request("sites", params: params)
+    end
+
+    def retrieve(site_id:)
+      get_request("sites/#{site_id}")
+    end
+
+    def create(**attributes)
+      post_request("sites", body: attributes)
+    end
+
+    def update(site_id:, **attributes)
+      post_request("sites/#{site_id}", body: attributes)
+    end
+
+    def delete(site_id:)
+      delete_request("sites/#{site_id}")
+    end
+
+    def wipe(site_id:)
+      delete_request("sites/#{site_id}/data")
+    end
+  end
+end

data/lib/fathom/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fathom
+  VERSION = "0.1.0"
+end

data/lib/fathom_api.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "fathom_api/version"
-
-module FathomApi
-  class Error < StandardError; end
-  # Your code goes here...
-end
+# Empty, but used to require and load in the Fathom namespace automatically
+# So we have saner class names rather than FathomApi::Client
+require "fathom"

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: fathom_api
 version: !ruby/object:Gem::Version
-  version: 0.0.1.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Andrea Fomera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-08-16 00:00:00.000000000 Z
-dependencies: []
+date: 2021-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 description:
 email:
 - afomera@hey.com
@@ -28,8 +56,21 @@ files:
 - bin/console
 - bin/setup
 - fathom_api.gemspec
+- lib/fathom.rb
+- lib/fathom/client.rb
+- lib/fathom/object.rb
+- lib/fathom/objects/account.rb
+- lib/fathom/objects/event.rb
+- lib/fathom/objects/list.rb
+- lib/fathom/objects/site.rb
+- lib/fathom/resource.rb
+- lib/fathom/resources/account.rb
+- lib/fathom/resources/aggregations.rb
+- lib/fathom/resources/current_visitors.rb
+- lib/fathom/resources/events.rb
+- lib/fathom/resources/sites.rb
+- lib/fathom/version.rb
 - lib/fathom_api.rb
-- lib/fathom_api/version.rb
 homepage: https://github.com/afomera/fathom_api
 licenses:
 - MIT

data/lib/fathom_api/version.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-module FathomApi
-  VERSION = "0.0.1.1"
-end