umami-read-models 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2c2f6153e25093f6b47ff480dcad0305d3729725541ce61fe814c5551f52ad3f
+  data.tar.gz: e81abfd30bf2a212a5f8ca47847720a3760358c58cf5da14c659519e4d068c35
+SHA512:
+  metadata.gz: 4867b41518f09623a58584e9130aab9314d89366e9d97d0a5b8826d953156d20004ba3df88087e459bd0757e263331bb71bb14a149d6eb49caf6e8159ef63d15
+  data.tar.gz: 30676022f6642b95b55658364d072a1bb282e0df36c5c01e4f158cefac29af0465d7697b813b5b40814cba45c444bd99edfee818e1c3555a456d46b5eaa91b01

data/.rubocop.yml

@@ -0,0 +1,16 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Exclude:
+    - 'test/**/*'
+
+Style/ClassAndModuleChildren:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-26
+
+### Added
+- Initial release of umami-read-models gem
+- Read-only ActiveRecord models for all Umami database tables
+- Support for PostgreSQL connections
+- Rails multi-database support with external configuration
+- Comprehensive query scopes for analytics queries
+- Full association mappings between models
+- Configurable table prefix support
+- Thread-safe connection management
+- Documentation and usage examples

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Andreas Zeitler
+
+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,278 @@
+# Umami::Models
+
+A Ruby gem that provides read-only ActiveRecord models for accessing Umami Analytics data directly from Rails applications. This gem allows you to query Umami's database directly for analytics data, reports, and user information.
+
+## Features
+
+- Read-only ActiveRecord models for all Umami database tables
+- Support for PostgreSQL connections
+- Built-in query scopes for common analytics queries
+- Association mappings between models
+- Configurable table prefix support
+- Thread-safe connection management
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'umami-read-models'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install umami-read-models
+
+## Configuration
+
+### Setup with Rails Multi-Database Support
+
+This gem is designed to work with Rails 6+ multiple database support. Configure your database in `config/database.yml`:
+
+```yaml
+# config/database.yml
+production:
+  primary:
+    # Your main Rails database configuration
+  umami:
+    adapter: postgresql
+    host: <%= ENV['UMAMI_DB_HOST'] %>
+    port: <%= ENV['UMAMI_DB_PORT'] || 5432 %>
+    database: <%= ENV['UMAMI_DB_NAME'] %>
+    username: <%= ENV['UMAMI_DB_USER'] %>
+    password: <%= ENV['UMAMI_DB_PASSWORD'] %>
+```
+
+Then configure the gem in an initializer (e.g., `config/initializers/umami_read_models.rb`):
+
+```ruby
+Umami::Models.configure do |config|
+  # Specify which database configuration to use
+  config.database = :umami
+  
+  # Optional: Set a table prefix if your Umami tables use one
+  config.table_prefix = "umami_"
+end
+```
+
+### Advanced Multi-Database Configuration
+
+For read replicas:
+
+```ruby
+Umami::Models.configure do |config|
+  config.database = { writing: :umami, reading: :umami_replica }
+end
+```
+
+This uses Rails' built-in database roles. Even though the models are read-only, Rails still requires 
+a `:writing` connection to be defined. Both connections can point to the same database, or you can 
+use a read replica for the `:reading` connection for better performance.
+
+## Usage
+
+### Available Models
+
+- `Umami::Models::User` - Umami users
+- `Umami::Models::Website` - Tracked websites
+- `Umami::Models::Session` - Visitor sessions
+- `Umami::Models::WebsiteEvent` - Page views and custom events
+- `Umami::Models::EventData` - Custom event data
+- `Umami::Models::SessionData` - Session metadata
+- `Umami::Models::Team` - Teams
+- `Umami::Models::TeamUser` - Team memberships
+- `Umami::Models::Report` - Saved reports
+
+### Basic Queries
+
+```ruby
+# Get all websites
+websites = Umami::Models::Website.all
+
+# Get active websites for a user
+user_websites = Umami::Models::Website
+  .active
+  .by_user(user_id)
+
+# Get recent sessions for a website
+recent_sessions = Umami::Models::Session
+  .by_website(website_id)
+  .recent
+  .limit(100)
+
+# Get page views for the last 7 days
+page_views = Umami::Models::WebsiteEvent
+  .by_website(website_id)
+  .page_views
+  .by_date_range(7.days.ago, Time.current)
+```
+
+### Working with Sessions
+
+```ruby
+# Get sessions by browser
+chrome_sessions = Umami::Models::Session
+  .by_website(website_id)
+  .by_browser('Chrome')
+  .by_date_range(start_date, end_date)
+
+# Get sessions by country
+us_sessions = Umami::Models::Session
+  .by_website(website_id)
+  .by_country('US')
+
+# Get session with events
+session = Umami::Models::Session.find(session_id)
+events = session.website_events.page_views
+```
+
+### Working with Events
+
+```ruby
+# Get custom events
+custom_events = Umami::Models::WebsiteEvent
+  .by_website(website_id)
+  .custom_events
+  .by_event_name('button_click')
+
+# Get events with UTM parameters
+campaign_events = Umami::Models::WebsiteEvent
+  .by_website(website_id)
+  .with_utm_campaign('summer_sale')
+
+# Get event data
+event = Umami::Models::WebsiteEvent.find(event_id)
+event_data = event.event_data
+```
+
+### Analytics Queries
+
+```ruby
+# Get unique visitors (sessions) by day
+daily_visitors = Umami::Models::Session
+  .by_website(website_id)
+  .group("DATE(created_at)")
+  .count
+
+# Get top pages
+top_pages = Umami::Models::WebsiteEvent
+  .by_website(website_id)
+  .page_views
+  .group(:url_path)
+  .order('count_all DESC')
+  .limit(10)
+  .count
+
+# Get referrer domains
+referrers = Umami::Models::WebsiteEvent
+  .by_website(website_id)
+  .where.not(referrer_domain: nil)
+  .group(:referrer_domain)
+  .order('count_all DESC')
+  .count
+
+# Get browser statistics
+browser_stats = Umami::Models::Session
+  .by_website(website_id)
+  .group(:browser)
+  .count
+```
+
+### Working with Reports
+
+```ruby
+# Get user reports
+user_reports = Umami::Models::Report
+  .by_user(user_id)
+  .recent
+
+# Get report with parsed parameters
+report = Umami::Models::Report.find(report_id)
+params = report.parsed_parameters
+```
+
+## Read-Only Protection
+
+All models are read-only by default. Any attempt to create, update, or delete records will fail:
+
+```ruby
+# This will raise an error
+website = Umami::Models::Website.new(name: "Test")
+website.save # => raises ActiveRecord::ReadOnlyRecord
+
+# This will also raise an error
+Umami::Models::Website.find(id).update(name: "New Name")
+```
+
+## Advanced Usage
+
+### Custom Queries
+
+You can use all ActiveRecord query methods:
+
+```ruby
+# Complex query example
+Umami::Models::WebsiteEvent
+  .joins(:session)
+  .where(website_id: website_id)
+  .where(sessions: { country: 'US' })
+  .where(created_at: 30.days.ago..Time.current)
+  .group(:url_path)
+  .having('COUNT(*) > ?', 100)
+  .pluck(:url_path, 'COUNT(*)')
+```
+
+### Raw SQL
+
+For complex analytics queries, you can use raw SQL:
+
+```ruby
+results = Umami::Models::Base.connection.execute(<<-SQL)
+  SELECT 
+    DATE(created_at) as date,
+    COUNT(DISTINCT session_id) as visitors,
+    COUNT(*) as page_views
+  FROM website_event
+  WHERE website_id = '#{website_id}'
+    AND created_at >= '#{30.days.ago}'
+  GROUP BY DATE(created_at)
+  ORDER BY date DESC
+SQL
+```
+
+## 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.
+
+### Releasing a New Version
+
+1. Update the version number in `lib/umami/models/version.rb`
+2. Update the CHANGELOG.md with the new version and changes
+3. Commit the changes: `git commit -am "Release version X.Y.Z"`
+4. Create a tag: `git tag vX.Y.Z`
+5. Push the changes and tag: `git push origin main --tags`
+
+The GitHub Action will automatically:
+- Run the test suite
+- Build the gem
+- Publish to RubyGems.org
+- Create a GitHub release
+
+**Note**: You need to set up the `RUBYGEMS_API_KEY` secret in your GitHub repository settings for automatic publishing to work.
+
+### Manual Release
+
+If you need to release manually:
+
+```bash
+gem build umami-read-models.gemspec
+gem push umami-read-models-*.gem
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/azeitler/umami-read-models.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/umami/models/event_data.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents custom data associated with an event
+    class EventData < Base
+      self.table_name = "event_data"
+      self.primary_key = "event_data_id"
+      belongs_to :website, foreign_key: "website_id"
+      belongs_to :website_event, foreign_key: "website_event_id"
+      scope :by_website, ->(website_id) { where(website_id: website_id) }
+      scope :by_key, ->(key) { where(data_key: key) }
+      scope :string_type, -> { where(data_type: 1) }
+      scope :number_type, -> { where(data_type: 2) }
+      scope :date_type, -> { where(data_type: 3) }
+      scope :by_date_range, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+      def value
+        case data_type
+        when 1 then string_value
+        when 2 then number_value
+        when 3 then date_value
+        end
+      end
+    end
+  end
+end

data/lib/umami/models/report.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents a saved report configuration
+    class Report < Base
+      self.table_name = "report"
+      self.primary_key = "report_id"
+      belongs_to :user, foreign_key: "user_id"
+      belongs_to :website, foreign_key: "website_id"
+      scope :by_type, ->(type) { where(type: type) }
+      scope :by_name, ->(name) { where(name: name) }
+      scope :by_user, ->(user_id) { where(user_id: user_id) }
+      scope :by_website, ->(website_id) { where(website_id: website_id) }
+      scope :recent, -> { order(created_at: :desc) }
+      def parsed_parameters
+        JSON.parse(parameters)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/umami/models/session.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents a visitor session
+    class Session < Base
+      self.table_name = "session"
+      self.primary_key = "session_id"
+
+      has_many :website_events, class_name: "WebsiteEvent", foreign_key: "session_id"
+      has_many :session_data, class_name: "SessionData", foreign_key: "session_id"
+
+      scope :recent, -> { order(created_at: :desc) }
+      scope :by_website, ->(website_id) { where(website_id: website_id) }
+      scope :by_browser, ->(browser) { where(browser: browser) }
+      scope :by_os, ->(os) { where(os: os) }
+      scope :by_device, ->(device) { where(device: device) }
+      scope :by_country, ->(country) { where(country: country) }
+      scope :by_date_range, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+    end
+  end
+end

data/lib/umami/models/session_data.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents custom data associated with a session
+    class SessionData < Base
+      self.table_name = "session_data"
+      self.primary_key = "session_data_id"
+      belongs_to :website, foreign_key: "website_id"
+      belongs_to :session, foreign_key: "session_id"
+      scope :by_website, ->(website_id) { where(website_id: website_id) }
+      scope :by_session, ->(session_id) { where(session_id: session_id) }
+      scope :by_key, ->(key) { where(data_key: key) }
+      scope :by_distinct_id, ->(distinct_id) { where(distinct_id: distinct_id) }
+      scope :string_type, -> { where(data_type: 1) }
+      scope :number_type, -> { where(data_type: 2) }
+      scope :date_type, -> { where(data_type: 3) }
+      scope :by_date_range, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+      def value
+        case data_type
+        when 1 then string_value
+        when 2 then number_value
+        when 3 then date_value
+        end
+      end
+    end
+  end
+end

data/lib/umami/models/team.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents a team for multi-tenancy
+    class Team < Base
+      self.table_name = "team"
+      self.primary_key = "team_id"
+      has_many :websites, foreign_key: "team_id"
+      has_many :team_users, class_name: "TeamUser", foreign_key: "team_id"
+      has_many :users, through: :team_users
+      scope :active, -> { where(deleted_at: nil) }
+      scope :by_access_code, ->(code) { where(access_code: code) }
+    end
+  end
+end

data/lib/umami/models/team_user.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents team membership
+    class TeamUser < Base
+      self.table_name = "team_user"
+      self.primary_key = "team_user_id"
+      belongs_to :team, foreign_key: "team_id"
+      belongs_to :user, foreign_key: "user_id"
+      scope :by_role, ->(role) { where(role: role) }
+      scope :admins, -> { where(role: "admin") }
+      scope :members, -> { where(role: "member") }
+    end
+  end
+end

data/lib/umami/models/user.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents a user in the Umami analytics system
+    class User < Base
+      self.table_name = "user"
+      self.primary_key = "user_id"
+
+      has_many :owned_websites, class_name: "Website", foreign_key: "user_id"
+      has_many :created_websites, class_name: "Website", foreign_key: "created_by"
+      has_many :team_users, class_name: "TeamUser", foreign_key: "user_id"
+      has_many :teams, through: :team_users
+      has_many :reports, foreign_key: "user_id"
+
+      scope :active, -> { where(deleted_at: nil) }
+      scope :with_role, ->(role) { where(role: role) }
+    end
+  end
+end

data/lib/umami/models/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    VERSION = "0.1.0"
+  end
+end

data/lib/umami/models/website.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents a website being tracked
+    class Website < Base
+      self.table_name = "website"
+      self.primary_key = "website_id"
+      belongs_to :user, foreign_key: "user_id", optional: true
+      belongs_to :created_by_user, class_name: "User", foreign_key: "created_by", optional: true
+      belongs_to :team, foreign_key: "team_id", optional: true
+      has_many :event_data, class_name: "EventData", foreign_key: "website_id"
+      has_many :reports, foreign_key: "website_id"
+      has_many :session_data, class_name: "SessionData", foreign_key: "website_id"
+      scope :active, -> { where(deleted_at: nil) }
+      scope :by_user, ->(user_id) { where(user_id: user_id) }
+      scope :by_team, ->(team_id) { where(team_id: team_id) }
+      scope :public_shares, -> { where.not(share_id: nil) }
+      def sessions
+        Session.by_website(website_id)
+      end
+
+      def website_events
+        WebsiteEvent.by_website(website_id)
+      end
+    end
+  end
+end

data/lib/umami/models/website_event.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Umami
+  module Models
+    # Represents a page view or custom event
+    class WebsiteEvent < Base
+      self.table_name = "website_event"
+      self.primary_key = "event_id"
+      belongs_to :session, foreign_key: "session_id"
+      has_many :event_data, class_name: "EventData", foreign_key: "website_event_id"
+      scope :recent, -> { order(created_at: :desc) }
+      scope :by_website, ->(website_id) { where(website_id: website_id) }
+      scope :by_session, ->(session_id) { where(session_id: session_id) }
+      scope :by_visit, ->(visit_id) { where(visit_id: visit_id) }
+      scope :by_date_range, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+      scope :page_views, -> { where(event_type: 1) }
+      scope :custom_events, -> { where(event_type: 2) }
+      scope :by_event_name, ->(name) { where(event_name: name) }
+      scope :by_url_path, ->(path) { where(url_path: path) }
+      scope :by_hostname, ->(hostname) { where(hostname: hostname) }
+      scope :with_utm_source, ->(source) { where(utm_source: source) }
+      scope :with_utm_campaign, ->(campaign) { where(utm_campaign: campaign) }
+    end
+  end
+end

data/lib/umami/models.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "models/version"
+require "active_record"
+
+module Umami
+  # Provides read-only ActiveRecord models for accessing Umami Analytics data
+  module Models
+    class Error < StandardError; end
+
+    class << self
+      attr_accessor :table_prefix, :database
+
+      def configure
+        yield self
+      end
+    end
+
+    self.table_prefix = ""
+    self.database = nil
+
+    # Base class for all Umami models with read-only enforcement
+    class Base < ActiveRecord::Base
+      self.abstract_class = true
+
+      def self.inherited(subclass)
+        super
+        # Apply the database configuration when a model inherits from Base
+        return unless Umami::Models.database
+
+        subclass.connects_to database: Umami::Models.database
+      end
+
+      def readonly?
+        true
+      end
+
+      def self.table_name
+        "#{Umami::Models.table_prefix}#{super}"
+      end
+    end
+  end
+end
+
+require_relative "models/user"
+require_relative "models/session"
+require_relative "models/website"
+require_relative "models/website_event"
+require_relative "models/event_data"
+require_relative "models/session_data"
+require_relative "models/team"
+require_relative "models/team_user"
+require_relative "models/report"

data/sig/umami/models.rbs

@@ -0,0 +1,6 @@
+module Umami
+  module Models
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: umami-read-models
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andreas Zeitler
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Provides read-only ActiveRecord models for accessing Umami Analytics
+  data directly from Rails applications
+email:
+- me@azeitler.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/umami/models.rb
+- lib/umami/models/event_data.rb
+- lib/umami/models/report.rb
+- lib/umami/models/session.rb
+- lib/umami/models/session_data.rb
+- lib/umami/models/team.rb
+- lib/umami/models/team_user.rb
+- lib/umami/models/user.rb
+- lib/umami/models/version.rb
+- lib/umami/models/website.rb
+- lib/umami/models/website_event.rb
+- sig/umami/models.rbs
+homepage: https://github.com/azeitler/umami-read-models
+licenses: []
+metadata:
+  homepage_uri: https://github.com/azeitler/umami-read-models
+  source_code_uri: https://github.com/azeitler/umami-read-models
+  changelog_uri: https://github.com/azeitler/umami-read-models/blob/main/CHANGELOG.md
+  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: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Read-only ActiveRecord models for Umami Analytics database
+test_files: []