plausible_api 0.3 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3164447cd3eac3c7a7cbf0c7e7cccd36eaf2bd195966283fc0da4ad023b7b21e
-  data.tar.gz: 34acbb3e21f80bd3537d4273b6555dea0da7e4fdb5cf3dcbf8bede5d477e8ce0
+  metadata.gz: 45537f5b6e81b09eb72e08831934672798f3cdbd9af9d003ac38680a2116cdd7
+  data.tar.gz: eaaa12cf820d0c2462670881cac678c2d58be6e763205291b271357d74eb78ac
 SHA512:
-  metadata.gz: 03273d140652347b6b282d94ff0c6294746fc7bd410dcaa1feab54a627d80ed64fa8eb1c9c56c0a3a0e3e2a95cb9cda755501987f46a3b795cb9dc2862aa1e01
-  data.tar.gz: b6e84673b3763918a28488c717e3be089107571ecb1b357b4d7e2b1ded589b68eade9d65f615e70a6655b4571a73c7bf767a0af3363b6ca90631cd0810ea91e8
+  metadata.gz: e4c268ef6298bef18548b52d6484193d065dcdee251f4a5c741cb77abafb0aecc4d86249c13a1ce0982491701c3d1a7d6d98c6b20f7456a091c197eb494b23e5
+  data.tar.gz: f8aaac22771ab3e1ec2a542414402d2eeb67e5b59aa5363dd4b78bb8bb51f2ecf5d6d4f46b4a01ecae173a3f24bb347bbc98e2cbd20a7146c1ad38b7d3360f8a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    plausible_api (0.3)
+    plausible_api (0.4.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -7,15 +7,38 @@ Add this gem to your Gemfile:
 ```rb
 gem 'plausible_api'
 ```
-Then you need to initialize a Client with your `site_id` (the domain) and your `token`.
+Then you need to initialize a Client with your `site_id` (the domain) and your `api_key`.
+Optionally, you can pass a third parameter in case you are using a self-hosted instance of Plausible (You don't need to add this third parameter if your are using the comercial version of Plausible).
 ```rb
-c = PlausibleApi::Client.new('dailytics.com', '123123')
+# Using the comercial version:
+c = PlausibleApi::Client.new("mysite.com", "MYAPIKEY")
+
+# Using a self hosted instance
+c = PlausibleApi::Client.new("mysite.com", "MYAPIKEY", "https://my-hosted-plausible.com")
 
 # Test if the site and token are valid
 c.valid?
 => true
 ```
 
+If you will always work with the same site, you can set some (or all) of these 3 parameters
+before initializing the client. On a Ruby on Rails app, you can add this to an initializer like
+`config/initializers/plausible.rb`
+
+```rb
+# Do not include a trailing slash
+PlausibleApi.configure do |config|
+  config.base_url = "https://your-plausible-instance.com"
+  config.site_id = "dailytics.com"
+  config.api_key = "123123"
+end
+```
+
+And then, initializing the client simply like this:
+```rb
+c = PlausibleApi::Client.new
+```
+
 ### Stats > Aggregate
 
 You have all these options to get the aggregate stats
@@ -87,18 +110,6 @@ c.event({
 })
 ```
 
-
-### Self-hosted Plausible instances
-
-If you are using a self-hosted Plausible instance, you can set the `base_url` before initializing the client. On a Ruby on Rails app, you can add this to an initializer like `config/initializers/plausible.rb`
-
-```rb
-# Do not include a trailing slash
-PlausibleApi.configure do |config|
-  config.base_url = "https://your-plausible-instance.com"
-end
-```
-
 ## Development
 
 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.

data/lib/plausible_api/api_base.rb

@@ -0,0 +1,41 @@
+module PlausibleApi
+  class ApiBase < Utils
+    def request_class
+      # Net::HTTP::Post
+      raise NotImplementedError
+    end
+
+    def request_path
+      # "/api/event"
+      raise NotImplementedError
+    end
+
+    def request_auth?
+      true
+    end
+
+    def request_body
+      nil
+    end
+
+    def request_body?
+      present?(request_body)
+    end
+
+    def request_headers
+      {"content-type" => "application/json"}
+    end
+
+    def parse_response(body)
+      raise NotImplementedError
+    end
+
+    def errors
+      raise NotImplementedError
+    end
+
+    def valid?
+      errors.empty?
+    end
+  end
+end

data/lib/plausible_api/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "plausible_api/utils"
+require "plausible_api/api_base"
 require "plausible_api/stats/base"
 require "plausible_api/stats/realtime/visitors"
 require "plausible_api/stats/aggregate"
@@ -14,10 +16,15 @@ require "uri"
 require "cgi"
 
 module PlausibleApi
-  class Client
-    def initialize(site_id, token)
-      @site_id = site_id.to_s
-      @token = token.to_s
+  class Client < Utils
+
+    attr_accessor :configuration
+
+    def initialize(site_id = nil, api_key = nil, base_url = nil)
+      @configuration = Configuration.new
+      @configuration.api_key = presence(api_key) || PlausibleApi.configuration.api_key
+      @configuration.site_id = presence(site_id) || PlausibleApi.configuration.site_id
+      @configuration.base_url = presence(base_url) || PlausibleApi.configuration.base_url
     end
 
     def aggregate(options = {})
@@ -44,7 +51,7 @@ module PlausibleApi
     end
 
     def event(options = {})
-      call PlausibleApi::Event::Post.new(options.merge(domain: @site_id))
+      call PlausibleApi::Event::Post.new(options.merge(domain: configuration.site_id))
     end
 
     private
@@ -53,14 +60,14 @@ module PlausibleApi
 
     def call(api)
       raise Error, api.errors unless api.valid?
-      raise ConfigurationError, PlausibleApi.configuration.errors unless PlausibleApi.configuration.valid?
+      raise ConfigurationError, configuration.errors unless configuration.valid?
 
-      url = "#{PlausibleApi.configuration.base_url}#{api.request_url.gsub("$SITE_ID", @site_id)}"
+      url = "#{configuration.base_url}#{api.request_path.gsub("$SITE_ID", configuration.site_id)}"
       uri = URI.parse(url)
 
       req = api.request_class.new(uri.request_uri)
       req.initialize_http_header(api.request_headers)
-      req.add_field("authorization", "Bearer #{@token}") if api.request_auth?
+      req.add_field("authorization", "Bearer #{configuration.api_key}") if api.request_auth?
       req.body = api.request_body if api.request_body?
 
       http = Net::HTTP.new(uri.host, uri.port)
@@ -71,7 +78,7 @@ module PlausibleApi
       if SUCCESS_CODES.include?(response.code)
         api.parse_response response.body
       else
-        raise StandardError.new response.body
+        raise Error.new response
       end
     end
   end

data/lib/plausible_api/configuration.rb

@@ -1,10 +1,13 @@
 module PlausibleApi
   class Configuration
-    attr_accessor :base_url
+    attr_accessor :base_url, :default_user_agent, :api_key, :site_id
 
     # Setting up default values
     def initialize
       @base_url = "https://plausible.io"
+      @default_user_agent = "plausible_api_ruby/#{PlausibleApi::VERSION}"
+      @api_key = nil
+      @site_id = nil
     end
 
     def valid?
@@ -20,6 +23,12 @@ module PlausibleApi
       elsif base_url.end_with?("/")
         errors.push(base_url: "base_url should not end with a trailing slash")
       end
+      if api_key.nil? || api_key.empty?
+        errors.push(api_key: "api_key is required")
+      end
+      if site_id.nil? || site_id.empty?
+        errors.push(site_id: "site_id is required")
+      end
       errors
     end
   end

data/lib/plausible_api/event/base.rb

@@ -1,31 +1,17 @@
 module PlausibleApi
   module Event
-    class Base
-      DEFAULT_USER_AGENT = "plausible_api_ruby/#{PlausibleApi::VERSION}"
-
+    class Base < ApiBase
       def request_class
         Net::HTTP::Post
       end
 
-      def request_url_base
+      def request_path
         "/api/event"
       end
 
-      def request_url
-        request_url_base
-      end
-
       def request_auth?
         false
       end
-
-      def request_body?
-        true
-      end
-
-      def valid?
-        errors.empty?
-      end
     end
   end
 end

data/lib/plausible_api/event/post.rb

@@ -3,7 +3,6 @@
 module PlausibleApi
   module Event
     class Post < Base
-      DEFAULT_USER_AGENT = "plausible_api_ruby/#{PlausibleApi::VERSION}"
       VALID_REVENUE_KEYS = %i[amount currency].freeze
       OPTIONS_IN_HEADERS = %i[ip user_agent].freeze
 
@@ -16,7 +15,7 @@ module PlausibleApi
 
         @domain = @options[:domain]
         @ip = @options[:ip]
-        @user_agent = presence(@options[:user_agent]) || DEFAULT_USER_AGENT
+        @user_agent = presence(@options[:user_agent]) || PlausibleApi.configuration.default_user_agent
         @name = presence(@options[:name]) || "pageview"
         @url = presence(@options[:url]) || "app://localhost/#{@name}"
         @referrer = @options[:referrer]
@@ -60,10 +59,10 @@ module PlausibleApi
 
         if present?(@revenue)
           if @revenue.is_a?(Hash)
-            unless valid_revenue_keys?(@revenue)
+            unless @revenue.keys.map(&:to_sym).all? { |key| VALID_REVENUE_KEYS.include?(key) }
               errors.push(
                 revenue: "revenue must have keys #{VALID_REVENUE_KEYS.join(", ")} " \
-                         "but was #{@revenue.inspect}"
+                        "but was #{@revenue.inspect}"
               )
             end
           else
@@ -83,19 +82,6 @@ module PlausibleApi
       def valid_revenue_keys?(revenue)
         revenue.keys.sort.map(&:to_sym) == VALID_REVENUE_KEYS.sort
       end
-
-      def present?(value)
-        !value.nil? && !value.empty?
-      end
-
-      def blank?(value)
-        !present?(value)
-      end
-
-      def presence(value)
-        return nil if blank?(value)
-        value
-      end
     end
   end
 end

data/lib/plausible_api/stats/aggregate.rb

@@ -3,20 +3,15 @@
 module PlausibleApi
   module Stats
     class Aggregate < Base
-
       def initialize(options = {})
-        super({ period: '30d',
-                metrics: 'visitors,visits,pageviews,views_per_visit,bounce_rate,visit_duration,events' }
-              .merge(options))
+        super({period: "30d",
+               metrics: "visitors,visits,pageviews,views_per_visit,bounce_rate,visit_duration,events"}
+          .merge(options))
       end
 
-      def request_url_base
+      def request_path_base
         "/api/v1/stats/aggregate?site_id=$SITE_ID"
       end
-
-      def parse_response(body)
-        JSON.parse(body)['results']
-      end
     end
   end
 end

data/lib/plausible_api/stats/base.rb

@@ -2,100 +2,79 @@
 
 module PlausibleApi
   module Stats
-    class Base
+    class Base < ApiBase
+      ALLOWED_PERIODS = %w[12mo 6mo month 30d 7d day custom]
+      ALLOWED_METRICS = %w[visitors visits pageviews views_per_visit bounce_rate visit_duration events]
+      ALLOWED_COMPARE = %w[previous_period]
+      ALLOWED_INTERVALS = %w[date month]
+      ALLOWED_PROPERTIES = %w[event:goal event:page visit:entry_page visit:exit_page visit:source
+        visit:referrer visit:utm_medium visit:utm_source visit:utm_campaign
+        visit:utm_content visit:utm_term visit:device visit:browser
+        visit:browser_version visit:os visit:os_version visit:country visit:region visit:city
+        event:props:.+]
+      ALLOWED_FILTER_OPERATORS = %w[== != \|]
 
       def initialize(options = {})
-        @options = { compare: nil, date: nil, filters: nil, interval: nil,
-                      limit: nil, metrics: nil, page: nil, period: nil,
-                      property: nil }.merge(options)
-        @options[:period] = 'custom' if @options[:date]
-      end
-
-      def request_url_base
-        raise NotImplementedError
+        @options = {compare: nil, date: nil, filters: nil, interval: nil,
+                    limit: nil, metrics: nil, page: nil, period: nil,
+                    property: nil}.merge(options)
+        @options[:period] = "custom" if @options[:date]
       end
 
       def request_class
         Net::HTTP::Get
       end
 
-      def request_body?
-        false
-      end
-
-      def request_body
-        nil
-      end
-
-      def request_url
-        params = @options.select{ |_,v| !v.to_s.empty? }
-        [request_url_base, URI.encode_www_form(params)].reject{|e| e.empty?}.join('&')
-      end
-
-      def request_headers
-        {}
-      end
-
-      def request_auth?
-        true
+      def request_path
+        params = @options.select { |_, v| !v.to_s.empty? }
+        [request_path_base, URI.encode_www_form(params)].reject { |e| e.empty? }.join("&")
       end
 
       def parse_response(body)
-        raise NotImplementedError
-      end
-
-      def valid?
-        errors.empty?
+        JSON.parse(body)["results"]
       end
 
       def errors
-        allowed_period   = %w(12mo 6mo month 30d 7d day custom)
-        allowed_metrics  = %w(visitors visits pageviews views_per_visit bounce_rate visit_duration events)
-        allowed_compare  = %w(previous_period)
-        allowed_interval = %w(date month)
-        allowed_property = %w(event:page visit:entry_page visit:exit_page visit:source visit:referrer
-          visit:utm_medium visit:utm_source visit:utm_campaign visit:device visit:browser
-          visit:browser_version visit:os visit:os_version visit:country)
-        e = 'Not a valid parameter. Allowed parameters are: '
+        e = "Not a valid parameter. Allowed parameters are: "
 
         errors = []
         if @options[:period]
-          errors.push({ period: "#{e}#{allowed_period.join(', ')}" }) unless allowed_period.include? @options[:period]
+          errors.push({period: "#{e}#{ALLOWED_PERIODS.join(", ")}"}) unless ALLOWED_PERIODS.include? @options[:period]
         end
         if @options[:metrics]
-          metrics_array = @options[:metrics].split(',')
-          errors.push({ metrics: "#{e}#{allowed_metrics.join(', ')}" }) unless metrics_array & allowed_metrics == metrics_array
+          metrics_array = @options[:metrics].split(",")
+          errors.push({metrics: "#{e}#{ALLOWED_METRICS.join(", ")}"}) unless metrics_array & ALLOWED_METRICS == metrics_array
         end
         if @options[:compare]
-          errors.push({ compare: "#{e}#{allowed_compare.join(', ')}" }) unless allowed_compare.include? @options[:compare]
+          errors.push({compare: "#{e}#{ALLOWED_COMPARE.join(", ")}"}) unless ALLOWED_COMPARE.include? @options[:compare]
         end
         if @options[:interval]
-          errors.push({ interval: "#{e}#{allowed_interval.join(', ')}" }) unless allowed_interval.include? @options[:interval]
+          errors.push({interval: "#{e}#{ALLOWED_INTERVALS.join(", ")}"}) unless ALLOWED_INTERVALS.include? @options[:interval]
         end
         if @options[:property]
-          errors.push({ property: "#{e}#{allowed_property.join(', ')}" }) unless allowed_property.include? @options[:property]
+          unless @options[:property].match?(/^(#{ALLOWED_PROPERTIES.join('|')})$/)
+            errors.push({property: "#{e}#{ALLOWED_PROPERTIES.join(", ")}"}) unless ALLOWED_PROPERTIES.include? @options[:property]
+          end
         end
-        if @options[:filters]
-          filters_array = @options[:filters].to_s.split(';')
-          filters_array.each do |f|
-            parts = f.split("==")
-            errors.push({ filters: "Unrecognized filter: #{f}" }) unless parts.length == 2
-            errors.push({ filters: "Unknown metric for filter: #{parts[0]}" }) unless allowed_property.include? parts[0]
+        @options[:filters]&.split(";")&.each do |filter|
+          unless filter.match?(/^(#{ALLOWED_PROPERTIES.join('|')})(#{ALLOWED_FILTER_OPERATORS.join('|')})(.+)$/)
+            errors.push({filters: "Filter #{filter} is not valid"})
           end
         end
+
         if @options[:limit]
-          errors.push({ limit: "Limit param must be a positive number" }) unless @options[:limit].is_a? Integer and @options[:limit] > 0
+          errors.push({limit: "Limit param must be a positive number"}) unless @options[:limit].to_i > 0
         end
         if @options[:page]
-          errors.push({ page: "Page param must be a positive number" }) unless @options[:page].is_a? Integer and @options[:page] > 0
+          errors.push({page: "Page param must be a positive number"}) unless @options[:page].to_i > 0
         end
         if @options[:date]
-          errors.push({ date: 'You must define the period parameter as custom' }) unless @options[:period] == 'custom'
+          errors.push({date: "You must define the period parameter as custom"}) unless @options[:period] == "custom"
           date_array = @options[:date].split(",")
-          errors.push({ date: 'You must define start and end dates divided by comma' }) unless date_array.length == 2
-          regex = /\d{4}\-\d{2}\-\d{2}/
-          errors.push({ date: 'Wrong format for the start date' }) unless date_array[0] =~ regex
-          errors.push({ date: 'Wrong format for the end date' }) unless date_array[1] =~ regex
+          errors.push({date: "You must define start and end dates divided by comma"}) unless date_array.length == 2
+          regex = /\d{4}-\d{2}-\d{2}/
+          errors.push({date: "Wrong format for the start date"}) unless date_array[0]&.match?(regex)
+          errors.push({date: "Wrong format for the end date"}) unless date_array[1]&.match?(regex)
         end
         errors
       end

data/lib/plausible_api/stats/breakdown.rb

@@ -3,18 +3,13 @@
 module PlausibleApi
   module Stats
     class Breakdown < Base
-
       def initialize(options = {})
-        super({ period: '30d', property: 'event:page' }.merge(options))
+        super({period: "30d", property: "event:page"}.merge(options))
       end
 
-      def request_url_base
+      def request_path_base
         "/api/v1/stats/breakdown?site_id=$SITE_ID"
       end
-
-      def parse_response(body)
-        JSON.parse(body)['results']
-      end
     end
   end
 end

data/lib/plausible_api/stats/realtime/visitors.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-module PlausibleApi 
+module PlausibleApi
   module Stats
     module Realtime
       class Visitors < PlausibleApi::Stats::Base
-        def request_url_base
+        def request_path_base
           "/api/v1/stats/realtime/visitors?site_id=$SITE_ID"
         end
 
@@ -14,4 +14,4 @@ module PlausibleApi
       end
     end
   end
-end
+end

data/lib/plausible_api/stats/timeseries.rb

@@ -3,18 +3,13 @@
 module PlausibleApi
   module Stats
     class Timeseries < Base
-
       def initialize(options = {})
-        super({ period: '30d' }.merge(options))
+        super({period: "30d"}.merge(options))
       end
 
-      def request_url_base
+      def request_path_base
         "/api/v1/stats/timeseries?site_id=$SITE_ID"
       end
-
-      def parse_response(body)
-        JSON.parse(body)['results']
-      end
     end
   end
 end

data/lib/plausible_api/utils.rb

@@ -0,0 +1,16 @@
+module PlausibleApi
+  class Utils
+    def present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def blank?(value)
+      !present?(value)
+    end
+
+    def presence(value)
+      return false if blank?(value)
+      value
+    end
+  end
+end

data/lib/plausible_api/version.rb

@@ -1,3 +1,3 @@
 module PlausibleApi
-  VERSION = "0.3"
+  VERSION = "0.4.1"
 end

data/lib/plausible_api.rb

@@ -7,7 +7,6 @@ module PlausibleApi
 
   class ConfigurationError < StandardError; end
 
-  # Your code goes here...
   class << self
     def configuration
       @configuration ||= Configuration.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plausible_api
 version: !ruby/object:Gem::Version
-  version: '0.3'
+  version: 0.4.1
 platform: ruby
 authors:
 - Gustavo Garcia
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-02 00:00:00.000000000 Z
+date: 2024-03-10 00:00:00.000000000 Z
 dependencies: []
 description: A very humble wrapper for the new API by Plausible
 email:
@@ -29,6 +29,7 @@ files:
 - examples/basic.rb
 - examples/event.rb
 - lib/plausible_api.rb
+- lib/plausible_api/api_base.rb
 - lib/plausible_api/client.rb
 - lib/plausible_api/configuration.rb
 - lib/plausible_api/event/base.rb
@@ -38,6 +39,7 @@ files:
 - lib/plausible_api/stats/breakdown.rb
 - lib/plausible_api/stats/realtime/visitors.rb
 - lib/plausible_api/stats/timeseries.rb
+- lib/plausible_api/utils.rb
 - lib/plausible_api/version.rb
 - plausible_api.gemspec
 homepage: https://github.com/dailytics/plausible_api