ledger 0.0.1 → 0.0.3

data/README.md

@@ -1,6 +1,12 @@
 # Ledger
 
-TODO: Write a gem description
+Does your app have the concept of accounts, with multiple users per account?
+
+Yes?
+
+Great.
+
+Ledger will easily allow you to create an activity stream of user events on a per account basis.
 
 ## Installation
 
@@ -18,7 +24,165 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Start by adding the `HasEvents` module to your account object.
+
+```ruby
+class Account < ActiveRecord::Base
+	…
+	include Ledger::HasEvents
+	…
+end
+```
+
+Add in the `CreatesEvents` module to your controller.
+
+```ruby
+class CategoriesController < ApplicationController
+	…
+	include Ledger::CreatesEvents
+	…
+end
+```
+
+Now all you need to do is call `#create_event` when you do something.
+
+```ruby
+def update
+	@category.update_attributes! params[:category]
+	create_event :updateated, @category
+end
+```
+
+Retrieve your event stream like so
+
+```ruby
+account.event_stream.each do |e|
+	puts "#{a.actor['name']} #{a.action} #{a.object} #{a.data['name']}"
+end
+"Mal Curtis updated Category Food"
+```
+
+`#event_stream` brings back the last 10 events. Send through an integer to get more.
+
+Each event has the following (by default, for options see further down).
+
+```
+{
+	"key"=>"category_updated",
+	"action"=>"updated",
+	"object"=>"Category",
+	"actor"=>{
+		"id"=>1,
+		"email"=>"mal@mal.co.nz",
+		"name"=>"Mal Curtis"
+	},
+	"data"=>{
+		"id"=>1515,
+		"name"=>"Food"
+	},
+	"created_at"=>2013-03-03 09:28:59 +1300
+}
+```
+
+Ledger isn’t opinionated about how you display your events in your app. You’ll need to figure that one out.
+
+## Customizing
+
+### Accounts & Users
+
+Ledger expects there to be a `current_account` and `current_user` method when creating an event. If this doesn’t suit your app, smash this into an initializer.
+
+```ruby
+Ledger.configure do |config|
+	config.event_scope_method = :current_account # Or whatevs
+	config.event_actor_method = :current_user # as above
+end
+```
+
+### Moar object data
+
+Ledger will try and add `id`, `email` and `name` from your user object and `id` and `name` from the object passed to `#create_event`. If you don’t have some of these methods, or want to add more information, just define `#event_details` and return a hash.
+
+```ruby
+class User
+	include Ledger::HasEvents
+	def event_details
+		{ id: id, email: email, username: username }
+	end
+end
+
+class Category
+	def event_details
+		{ id: id, parent: parent_id, description: description }
+	end
+end
+```
+
+### Moar event data
+
+Want to send more information about events? Just send through the information at the end of the `#create_event` call.
+
+```
+create_event :state_changed, @category, from: from_state, to: @category.state
+```
+```
+
+{
+	"key"=>"category_state_changed",
+	"action"=>"state_changed",
+	"object"=>"Category",
+	"actor"=>{
+		"id"=>1,
+		"email"=>"mal@mal.co.nz",
+		"name"=>"Mal Curtis"
+	},
+	"data"=>{
+		"id"=>1515,
+		"name"=>"Food",
+		"from"=>"available",
+		"to"=>"unavailable"
+	},
+	"created_at"=>2013-03-03 09:28:59 +1300
+}
+```
+
+
+### Redis connection
+
+Ledger defaults to `$redis`. If you want to set this manually, customize it in an initializer. Here's an example:
+
+```ruby
+Ledger.configure do |config|
+	uri = URI.parse(ENV["REDISTOGO_URL"] || 'redis://127.0.0.1:6379')
+	config.redis = Redis.new(
+		:host => uri.host,
+		:port => uri.port,
+		:password => uri.password
+	)
+end
+```
+
+### Manual Events
+
+You can add an event manually by creating an instance of `Ledger::Event`, then adding than in via `account.add_event`.
+
+```ruby
+new_event = Ledger::Event.new key: "manual_event", data: { some: "thing" }
+account.add_event new_event
+```
+
+### Direct Redis access
+
+You can access redis directly through `#events`. This will be a [Nest](https://github.com/soveran/nest) instance, and you can call on this, or use its naming schema to do some other magic.
+
+```ruby
+# Trim the events down to the last 100 events
+account.events.ltrim 0, 100
+
+# Create a new redis key (account:xxx:events:something_else)
+account.events["something_else"].lpush "Some data"
+```
+
 
 ## Contributing
 

data/ledger.gemspec

@@ -5,7 +5,7 @@ Gem::Specification.new do |gem|
   gem.authors       = ["Mal Curtis"]
   gem.email         = ["mal@sitepoint.com"]
   gem.description   = %q{Redis backed account activity streams}
-  gem.summary       = %q{Redis backed account activity streams}
+  gem.summary       = %q{Creates a per account activity stream for your Saas Ruby app}
   gem.homepage      = ""
 
   gem.files         = `git ls-files`.split($\)
@@ -14,4 +14,7 @@ Gem::Specification.new do |gem|
   gem.name          = "ledger"
   gem.require_paths = ["lib"]
   gem.version       = Ledger::VERSION
+
+  # Declaritive Redis Keys
+  gem.add_runtime_dependency "nest"
 end

data/lib/ledger.rb

@@ -1,5 +1,17 @@
 require "ledger/version"
+require 'ledger/event'
+require 'ledger/has_events'
+require 'ledger/creates_events'
 
 module Ledger
-  # Your code goes here...
+  mattr_accessor :event_scope_method, :event_actor_method, :redis
+
+  @@event_scope_method = :current_account
+  @@event_actor_method = :current_user
+
+  class << self
+    def configure
+      yield self
+    end
+  end
 end

data/lib/ledger/creates_events.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+module Ledger
+  module CreatesEvents
+    def create_event action, object, data = {}
+      unless event_scope.respond_to? :add_event
+        raise "#{Ledger.event_scope_method} does not respond to #add_event.
+        Either include Ledger::HasEvents in that scope, or set the
+        'event_scope_method' in your Ledger configuration to an
+        object that does."
+      end
+
+      object_name = object.class.name.downcase
+      key = [object_name, action].join('_')
+
+      details = {
+        key: key,
+        action: action,
+        object: object_name,
+        actor: {},
+        data: data || {}
+      }
+
+      details[:data].merge! object.respond_to?(:event_details) ? \
+        object.event_details : \
+        { id: object.id, name: object.name }
+
+      details[:actor].merge! event_actor.respond_to?(:event_details) ? \
+        event_actor.event_details : \
+        { id: event_actor.id, email: event_actor.email, name: event_actor.name }
+
+      event_scope.add_event Ledger::Event.new(details)
+    end
+
+    def event_scope
+      send(Ledger.event_scope_method)
+    rescue NoMethodError
+      raise "Hey, I tried calling #{Ledger.event_scope_method} but it doesn't exist. You’ll need to set the `event_scope_method` configuration value to the method that returns your current account object."
+    end
+
+    def event_actor
+      send(Ledger.event_actor_method)
+    rescue NoMethodError
+      raise "Hey, I tried calling #{Ledger.event_scope_method} but it doesn't exist. You’ll need to set the `event_actor_method` configuration value to the method that returns your current user object."
+    end
+  end
+end
+

data/lib/ledger/event.rb

@@ -0,0 +1,19 @@
+module Ledger
+  class Event
+    attr_accessor :actor, :key, :action, :object, :data, :created_at
+
+    def initialize opts
+      opts.each do |attr, value|
+        self.send("#{attr}=", value) if respond_to?("#{attr}=")
+      end
+      self.created_at = Time.now
+    end
+    
+    class << self
+      def from_json json
+        require 'json'
+        self.new JSON.parse json
+      end
+    end
+  end
+end

data/lib/ledger/has_events.rb

@@ -0,0 +1,26 @@
+require 'nest'
+module Ledger
+  module HasEvents
+    def rdb
+      Nest.new(self.class.name.downcase)[to_param]
+    end
+
+    def self.rdb
+      Nest.new(name, Ledger.redis)
+    end
+
+    def event_stream length = 10
+      events.lrange(0, length).map do |json|
+        Ledger::Event.from_json json
+      end
+    end
+
+    def add_event event
+      events.lpush event.to_json
+    end
+
+    def events
+      rdb[:events]
+    end
+  end
+end

data/lib/ledger/version.rb

@@ -1,3 +1,3 @@
 module Ledger
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ledger
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-02 00:00:00.000000000 Z
-dependencies: []
+date: 2013-03-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Redis backed account activity streams
 email:
 - mal@sitepoint.com
@@ -25,6 +41,9 @@ files:
 - Rakefile
 - ledger.gemspec
 - lib/ledger.rb
+- lib/ledger/creates_events.rb
+- lib/ledger/event.rb
+- lib/ledger/has_events.rb
 - lib/ledger/version.rb
 homepage: ''
 licenses: []
@@ -49,6 +68,6 @@ rubyforge_project:
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Redis backed account activity streams
+summary: Creates a per account activity stream for your Saas Ruby app
 test_files: []
 has_rdoc: