plausible_api 0.1.10 → 0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fcd7e3adaeb1c8fb8dc1de67e305573708d04e971e995bcffeb4d0fe71ec8ff
-  data.tar.gz: b729b5a5de1b5f6572c175879e77daed92aba1cc60075033b1e693752e13b7ce
+  metadata.gz: 3164447cd3eac3c7a7cbf0c7e7cccd36eaf2bd195966283fc0da4ad023b7b21e
+  data.tar.gz: 34acbb3e21f80bd3537d4273b6555dea0da7e4fdb5cf3dcbf8bede5d477e8ce0
 SHA512:
-  metadata.gz: 0d0757ae94943225433757648bc542dd2afa2a1706696b35cdb179f7f117cb8a8b34581ea0bc7a50ac1d8973c137206bf520e2b6d27129d06c7ff310ca757d6e
-  data.tar.gz: db68b71615cb9026ae5a9dddaa1fee92c51740d0314f556e032cd0975ea71675fbade8733e80c1b4975e53d64d7f1347747b10cb1a73b8f5c034d29b3f396590
+  metadata.gz: 03273d140652347b6b282d94ff0c6294746fc7bd410dcaa1feab54a627d80ed64fa8eb1c9c56c0a3a0e3e2a95cb9cda755501987f46a3b795cb9dc2862aa1e01
+  data.tar.gz: b6e84673b3763918a28488c717e3be089107571ecb1b357b4d7e2b1ded589b68eade9d65f615e70a6655b4571a73c7bf767a0af3363b6ca90631cd0810ea91e8

data/Gemfile.lock

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

data/README.md

@@ -9,7 +9,7 @@ gem 'plausible_api'
 ```
 Then you need to initialize a Client with your `site_id` (the domain) and your `token`.
 ```rb
-c = PlausibleApi::Client.new('dailytics.com', '123123') 
+c = PlausibleApi::Client.new('dailytics.com', '123123')
 
 # Test if the site and token are valid
 c.valid?
@@ -73,6 +73,31 @@ c.realtime_visitors
 => 13
 ```
 
+### Events
+
+You can send an event like this:
+
+```rb
+# Example using Rack::Request in Rails for user_agent and ip.
+c.event({
+  name: "signup",
+  url: 'https://dailytics.com/users/new',
+  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.3",
+  ip: "127.0.0.1"
+})
+```
+
+
+### 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
 

data/examples/basic.rb

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+require 'plausible_api'
+
+client = PlausibleApi::Client.new(ENV["SITE_ID"], ENV["TOKEN"])
+p client.valid?

data/examples/event.rb

@@ -0,0 +1,23 @@
+require 'bundler/setup'
+require 'plausible_api'
+
+client = PlausibleApi::Client.new(ENV["SITE_ID"], ENV["TOKEN"])
+
+# default all the things, pointless but works
+p client.event
+
+# change the name
+p client.event(
+  name: "test",
+)
+
+# send the whole kitchen sink
+p client.event(
+  ip: "127.0.0.1",
+  user_agent: "test",
+  name: "test",
+  url: "app://localhost/test",
+  referrer: "https://example.com",
+  revenue: {currency: "USD", amount: 1.00},
+  props: {foo: "bar"},
+)

data/lib/plausible_api/client.rb

@@ -1,24 +1,23 @@
 # frozen_string_literal: true
 
-require 'plausible_api/stats/base'
-require 'plausible_api/stats/realtime/visitors'
-require 'plausible_api/stats/aggregate'
-require 'plausible_api/stats/timeseries'
-require 'plausible_api/stats/breakdown'
+require "plausible_api/stats/base"
+require "plausible_api/stats/realtime/visitors"
+require "plausible_api/stats/aggregate"
+require "plausible_api/stats/timeseries"
+require "plausible_api/stats/breakdown"
+require "plausible_api/event/base"
+require "plausible_api/event/post"
 
-require 'json'
+require "json"
 require "net/http"
 require "uri"
 require "cgi"
 
 module PlausibleApi
   class Client
-    
-    BASE_URL = 'https://plausible.io'
-
     def initialize(site_id, token)
       @site_id = site_id.to_s
-      @token   = token.to_s
+      @token = token.to_s
     end
 
     def aggregate(options = {})
@@ -38,34 +37,42 @@ module PlausibleApi
     end
 
     def valid?
-      begin
-        realtime_visitors
-        return true
-      rescue
-        return false
-      end
+      realtime_visitors
+      true
+    rescue
+      false
+    end
+
+    def event(options = {})
+      call PlausibleApi::Event::Post.new(options.merge(domain: @site_id))
     end
 
     private
-    def call(api)      
-      raise StandardError.new api.errors unless api.valid?
-      
-      url = "#{BASE_URL}#{api.request_url.gsub('$SITE_ID', @site_id)}"
+
+    SUCCESS_CODES = %w[200 202].freeze
+
+    def call(api)
+      raise Error, api.errors unless api.valid?
+      raise ConfigurationError, PlausibleApi.configuration.errors unless PlausibleApi.configuration.valid?
+
+      url = "#{PlausibleApi.configuration.base_url}#{api.request_url.gsub("$SITE_ID", @site_id)}"
       uri = URI.parse(url)
 
-      req = Net::HTTP::Get.new(uri.request_uri)
-      req.add_field('Authorization', "Bearer #{@token}")
+      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.body = api.request_body if api.request_body?
 
       http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true  
+      http.use_ssl = true
 
       response = http.request(req)
 
-      if response.code == "200"
+      if SUCCESS_CODES.include?(response.code)
         api.parse_response response.body
       else
         raise StandardError.new response.body
       end
     end
   end
-end
+end

data/lib/plausible_api/configuration.rb

@@ -0,0 +1,26 @@
+module PlausibleApi
+  class Configuration
+    attr_accessor :base_url
+
+    # Setting up default values
+    def initialize
+      @base_url = "https://plausible.io"
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def errors
+      errors = []
+      if base_url.nil? || base_url.empty?
+        errors.push(base_url: "base_url is required")
+      elsif !(URI.parse base_url).is_a? URI::HTTP
+        errors.push(base_url: "base_url is not a valid URL")
+      elsif base_url.end_with?("/")
+        errors.push(base_url: "base_url should not end with a trailing slash")
+      end
+      errors
+    end
+  end
+end

data/lib/plausible_api/event/base.rb

@@ -0,0 +1,31 @@
+module PlausibleApi
+  module Event
+    class Base
+      DEFAULT_USER_AGENT = "plausible_api_ruby/#{PlausibleApi::VERSION}"
+
+      def request_class
+        Net::HTTP::Post
+      end
+
+      def request_url_base
+        "/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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+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
+
+      attr_reader :domain
+      attr_reader :ip, :user_agent, :url
+      attr_reader :name, :props, :referrer, :revenue
+
+      def initialize(options = {})
+        @options = options.transform_keys(&:to_sym)
+
+        @domain = @options[:domain]
+        @ip = @options[:ip]
+        @user_agent = presence(@options[:user_agent]) || DEFAULT_USER_AGENT
+        @name = presence(@options[:name]) || "pageview"
+        @url = presence(@options[:url]) || "app://localhost/#{@name}"
+        @referrer = @options[:referrer]
+        @revenue = @options[:revenue]
+        @props = @options[:props]
+      end
+
+      def request_body
+        data = {
+          url: @url,
+          name: @name,
+          domain: @domain
+        }
+
+        data[:props] = @props if present?(@props)
+        data[:revenue] = @revenue if present?(@revenue)
+        data[:referrer] = @referrer if present?(@referrer)
+
+        JSON.generate(data)
+      end
+
+      def request_headers
+        headers = {
+          "content-type" => "application/json",
+          "user-agent" => @user_agent
+        }
+        headers["x-forwarded-for"] = @ip if present?(@ip)
+        headers
+      end
+
+      def parse_response(body)
+        body == "ok"
+      end
+
+      def errors
+        errors = []
+        errors.push(url: "url is required") if blank?(@url)
+        errors.push(name: "name is required") if blank?(@name)
+        errors.push(domain: "domain is required") if blank?(@domain)
+        errors.push(user_agent: "user_agent is required") if blank?(@user_agent)
+
+        if present?(@revenue)
+          if @revenue.is_a?(Hash)
+            unless valid_revenue_keys?(@revenue)
+              errors.push(
+                revenue: "revenue must have keys #{VALID_REVENUE_KEYS.join(", ")} " \
+                         "but was #{@revenue.inspect}"
+              )
+            end
+          else
+            errors.push(revenue: "revenue must be a Hash")
+          end
+        end
+
+        if present?(@props) && !@props.is_a?(Hash)
+          errors.push(props: "props must be a Hash")
+        end
+
+        errors
+      end
+
+      private
+
+      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

@@ -5,11 +5,11 @@ module PlausibleApi
     class Aggregate < Base
 
       def initialize(options = {})
-        super({ period: '30d', 
+        super({ period: '30d',
                 metrics: 'visitors,visits,pageviews,views_per_visit,bounce_rate,visit_duration,events' }
               .merge(options))
       end
-      
+
       def request_url_base
         "/api/v1/stats/aggregate?site_id=$SITE_ID"
       end

data/lib/plausible_api/stats/base.rb

@@ -15,11 +15,31 @@ module PlausibleApi
         raise NotImplementedError
       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
+      end
+
       def parse_response(body)
         raise NotImplementedError
       end

data/lib/plausible_api/stats/breakdown.rb

@@ -7,7 +7,7 @@ module PlausibleApi
       def initialize(options = {})
         super({ period: '30d', property: 'event:page' }.merge(options))
       end
-      
+
       def request_url_base
         "/api/v1/stats/breakdown?site_id=$SITE_ID"
       end
@@ -17,4 +17,4 @@ module PlausibleApi
       end
     end
   end
-end
+end

data/lib/plausible_api/stats/timeseries.rb

@@ -7,7 +7,7 @@ module PlausibleApi
       def initialize(options = {})
         super({ period: '30d' }.merge(options))
       end
-      
+
       def request_url_base
         "/api/v1/stats/timeseries?site_id=$SITE_ID"
       end
@@ -17,4 +17,4 @@ module PlausibleApi
       end
     end
   end
-end
+end

data/lib/plausible_api/version.rb

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

data/lib/plausible_api.rb

@@ -1,7 +1,20 @@
-require 'plausible_api/version'
-require 'plausible_api/client'
+require "plausible_api/version"
+require "plausible_api/client"
+require "plausible_api/configuration"
 
 module PlausibleApi
   class Error < StandardError; end
+
+  class ConfigurationError < StandardError; end
+
   # Your code goes here...
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plausible_api
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: '0.3'
 platform: ruby
 authors:
 - Gustavo Garcia
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-14 00:00:00.000000000 Z
+date: 2024-02-02 00:00:00.000000000 Z
 dependencies: []
 description: A very humble wrapper for the new API by Plausible
 email:
@@ -26,8 +26,13 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples/basic.rb
+- examples/event.rb
 - lib/plausible_api.rb
 - lib/plausible_api/client.rb
+- lib/plausible_api/configuration.rb
+- lib/plausible_api/event/base.rb
+- lib/plausible_api/event/post.rb
 - lib/plausible_api/stats/aggregate.rb
 - lib/plausible_api/stats/base.rb
 - lib/plausible_api/stats/breakdown.rb