squawk 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Avand Amiri
+
+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,107 @@
+Squawk
+==================
+
+Squawk gives you a very simple way to keep track of activity on your site.
+
+With Squawk you can keep tabs on what's happening on your website with simple commands like this:
+
+    Squawk.user_signed_in! @user
+
+You define the message and see it all happen in real-time on the Twitter account of your choice
+
+Installation
+============
+Because Squawk talks to Twitter, it has to run in the background. At least for now, Squawk assumes that you're using delayed_job.
+
+Install Squawk like a typical Rails plugin:
+
+    script/plugin install git://github.com/avand/squawk.git
+
+Then create your the initializer config/initializers/squawk.rb:
+
+    # Set up all the authorization stuff:
+    Squawk.twitter_consumer_key    = "..." # Get this from Twitter
+    Squawk.twitter_consumer_secret = "..." # Get this from Twitter
+    Squawk.twitter_handle          = "..." # i.e. mycoolproduct_app
+    Squawk.twitter_access_token    = "..." # Get this from Twitter
+    Squawk.twitter_secret          = "..." # Get this from Twitter
+
+    # Register events you'd like to call in your application with plain old strings:
+    Squawk.register_event :site_down, "Site just went down"
+
+    # Register events that create dynamic alerts:
+    Squawk.register_event :user_signed_up, lambda { |user| "#{user.name} just signed up" }
+
+    # Use Squawk to catch exceptions (useful in those hard to reach places exception apps miss):
+    Squawk.register_event :error_caught, lambda { |error| "Boom! #{error.message}" }
+
+Usage
+=====
+    
+Register a new event in config/initializers/squawk.rb:
+
+    Squawk.register_event :not_found, "Someone just hit a page that does not exist"
+
+Want a more dynamic message? No problem, use a lambda to construct your own message at runtime:
+
+    Squawk.register_event :user_created, lambda { |user| "#{user.name} just created the #{User.count.ordinalize} account" }
+
+Fire an event from anywhere in your app (controller, background job, mailer, go nuts):
+
+    Squawk.event_name!
+
+At at time, see all the registered events:
+
+    Squawk.events
+
+Notes
+=====
+
+Squawk only tweets in production. In non-production environments you can grep the log ("Squawk") to see what it would have tweeted.
+
+Twitter enforces [rate limits](http://apiwiki.twitter.com/Rate-limiting), so play nice!
+
+This plugin uses [Twitter's OAuth](http://dev.twitter.com/pages/oauth_faq), so you need:
+
+* A Twitter browser-based application (something like "<your app name> Squawk Gem" with a callback of 'http://127.0.0.1')
+* A protected Twitter account to post activity to (something like "<your app name>_squawk")
+* Grant access to that account from the Twitter app you created
+
+Installation
+============
+
+This plugin uses [Twitter's OAuth](http://dev.twitter.com/pages/oauth_faq), so first you'll need to set up:
+
+1. A Twitter browser-based application (something like "<your app name> Squawk Gem" with a callback of 'http://127.0.0.1')
+2. A protected Twitter account to post activity to (something like "<your app name>_squawk")
+3. Grant access to that account from the Twitter app you created
+
+Unfortunately, to get that last step working is kind of pain:
+
+    > require 'twitter'
+    
+    > consumer_key    = '...' # Your Twitter app's consumer key
+    > consumer_secret = '...' # Your Twitter app's secret key
+    
+    > oauth = Twitter::OAuth.new consumer_key, consumer_secret
+    > oauth.set_callback_url('http://127.0.0.1:3000') # really anything your machine can GET
+    
+    > request_token  = oauth.request_token.token
+    > request_secret = oauth.request_token.secret
+    
+    > authorize_url = oauth.request_token.authorize_url
+    
+    # Browse to that authorize url.
+    # You'll be asked to authorize your app. Use the protected Twitter account's credentials.
+    # Twitter will redirect you back to whatever URL you specified.
+    
+    > oauth_verifier = '...' # Grab the oauth_verifier from the query parameters of the callback.
+    
+    > oauth.authorize_from_request(request_token, request_secret, oauth_verifier)
+    
+    > token  = oauth.access_token.token  # Set this in the initializer as Squawk.twitter_access_token
+    > secret = oauth.access_token.secret # Set this in the initializer as Squawk.twitter_secret
+
+Please [contact me](http://avandamiri.com/talk_to_me.html) if you find this useful and/or would like to contribute.
+
+Copyright (c) 2010 Avand Amiri, released under the MIT license

data/Rakefile

@@ -0,0 +1,13 @@
+require "jeweler"
+
+Jeweler::Tasks.new do |gem|
+  gem.name     = "squawk"
+  gem.summary  = "Get a feel for what's happening in your app with protected tweets"
+  gem.email    = "avand@avandamiri.com"
+  gem.homepage = "http://github.com/avand/squawk"
+  gem.authors  = ["Avand Amiri"]
+  gem.files    = FileList["[A-Z]*", "{lib}/**/*"]
+  gem.version  = '1.0.0'
+
+  gem.add_dependency("twitter", "0.9.8")
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/lib/squawk.rb

@@ -0,0 +1,62 @@
+class Squawk < Struct.new(:status)
+  cattr_accessor :twitter_consumer_key, :twitter_consumer_secret, :twitter_handle, :twitter_access_token, :twitter_secret
+  cattr_reader :events
+
+  class << self
+    # Registers an update event. For example:
+    #   Squawk.register_event :site_down, "Site just went down"
+    #   Squawk.register_event :user_signed_up, lambda { |user| "#{user.name} just signed up" }
+    # provide you with:
+    #   Squawk.site_down!
+    #   Squawk.user_signed_up! @user
+    def register_event(event_name, message_or_method)
+      @@events ||= []
+      
+      event_name = event_name.to_sym
+      
+      return if @@events.include?(event_name)
+      
+      @@events << event_name.to_sym
+      
+      method_name = "#{event_name}!"
+
+      (class << self; self; end).class_eval do # http://blog.jayfields.com/2008/02/ruby-dynamically-define-method.html
+        # First, the easy case - string
+        if message_or_method.is_a?(String)
+          define_method method_name do
+            update message_or_method
+          end
+        # Now, the harder case - lambda
+        else
+          define_method method_name do |*params|
+            update(message_or_method.call(*params))
+          end
+        end
+      end  
+    end
+
+    def test!
+      update "The time is currently #{Time.now}"
+    end
+
+    private
+
+      def update(status)
+        status = status[0...140] # trim status to min Twitter length
+      
+        Rails.logger.info("Squawk (@#{@@twitter_handle}): #{status}")
+        Delayed::Job.enqueue new(status[0...140]) if Rails.env.production?
+      
+        status
+      end
+  end
+
+  def perform
+    oauth = Twitter::OAuth.new(@@twitter_consumer_key, @@twitter_consumer_secret, :sign_in => true)
+    oauth.authorize_from_access(@@twitter_access_token, @@twitter_secret)
+
+    twitter = Twitter::Base.new(oauth)
+
+    twitter.update(status)
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: squawk
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Avand Amiri
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-19 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: twitter
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: avand@avandamiri.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- MIT-LICENSE
+- README.md
+- Rakefile
+- VERSION
+- lib/squawk.rb
+has_rdoc: true
+homepage: http://github.com/avand/squawk
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Get a feel for what's happening in your app with protected tweets
+test_files: []
+