budurl 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+group :development do
+  gem "rake"
+end
+
+gemspec

data/README.md

@@ -0,0 +1,14 @@
+# BudURL
+
+### About
+
+This gem provides a simple interface to the BudURL.Pro API, documented [here](http://budurl.com/page/budurlpro-api). BudURL provides URL shortening services as well as analytics, some of which is available externally. In particular, the API allows:
+* **Shortening URLs** along with adding notes, setting redirect types, and checking for duplicates,
+* **Expanding URLs** which have been shortened using the service,
+* **Gathering analytics** such as click counts either since link creation or on a day-by-day basis, filterable by time period.
+
+### Usage
+
+The BudURL API requires an API key for any usage other than URL expansion. More details at their website, [BudURL.Pro](http://budurl.pro).
+
+Initialise a client using `Budurl.new(<API_KEY>)`. It provides `shorten(url, opts)` and `expand(short_url)` functionality; the resulting `Budurl::Url` objects can be used to acquire additional information such as click counts. Options not exposed in code can be passed in as options; generally speaking, any option available through the API should be accessible.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./test/unit/*.rb"
+end
+
+desc "Run tests"
+task :default => :spec

data/bin/expand

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$:.push("lib")
+
+require 'budurl'
+
+budurl = Budurl.new(ARGV[0])
+
+puts budurl.expand(ARGV[1]).long_url

data/bin/shorten

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$:.push("lib")
+
+require 'budurl'
+
+budurl = Budurl.new(ARGV[0])
+
+puts budurl.shorten(ARGV[1]).link

data/bin/stats

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+require 'date'
+
+$:.push("lib")
+
+require 'budurl'
+
+budurl = Budurl.new(ARGV[0])
+
+url = budurl.expand(ARGV[1])
+
+date_from = ARGV[2] ? Date.parse(ARGV[2]) : nil
+date_to = ARGV[3] ? Date.parse(ARGV[3]) : nil
+
+count = url.clicks(false, date_from, date_to)
+dates = url.clicks(true, date_from, date_to)
+
+puts "URL: #{url.long_url}"
+puts "Total clicks: #{count}"
+puts "Per date:"
+dates.each {|date,clicks| puts "#{date}: #{clicks}"}

data/budurl.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "budurl/version"
+
+Gem::Specification.new do |s|
+  s.name        = "budurl"
+  s.version     = Budurl::VERSION
+  s.authors     = ["Anuj Das"]
+  s.email       = ["anuj.das@mylookout.com"]
+  s.homepage    = "https://github.com/lookout/budurl-gem"
+  s.summary     = %q{A gem for interfacing with the BudURL.Pro url shortener API}
+  s.description = %q{Supported operations include shrinking, expanding, and counting clicks.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'httparty'
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency 'ruby-debug'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'mimic'
+  s.add_development_dependency 'json'
+end

data/lib/budurl.rb

@@ -0,0 +1,9 @@
+require 'httparty'
+require 'budurl/url'
+require 'budurl/client'
+require 'budurl/version'
+
+module Budurl
+  # default BudURL.Pro API url
+  BUDURL_PRO_BASE_URI = 'http://BudURL.Pro/api/v2'
+end

data/lib/budurl/client.rb

@@ -0,0 +1,67 @@
+module Budurl
+  def self.new(api_key, uri = BUDURL_PRO_BASE_URI)
+    Budurl::Client.new(api_key, uri)
+  end
+
+  class Client
+    include HTTParty
+
+    format :json
+
+    # Returns a Budurl client which can be used to query API services.
+    # uri is the base uri for the BudURL API.
+    def initialize(api_key, uri)
+      self.class.base_uri uri
+      @default_query_opts = { :api_key => api_key }
+    end
+
+    # Returns a Budurl::Url object containing a shorturl.
+    # opts allow duplicate checking, notes, etc. For all options,
+    # see the BudURL API: http://budurl.com/page/budurlpro-api
+    def shorten(url, opts = {})
+      query_opts = {:long_url => url}.merge(opts)
+      response = get('/links/shrink', :query => query_opts)
+      Budurl::Url.new(self, response)
+    end
+
+    # Returns a Budurl::Url object containing a longurl.
+    def expand(short_url)
+      query_opts = {:link => short_url}
+      response = get('/links/expand', :query => query_opts)
+      Budurl::Url.new(self, response)
+    end
+
+    # Returns a hash containing click counts since creation.
+    # opts allow daily click counts and date filters. For all options,
+    # see the BudURL API: http://budurl.com/page/budurlpro-api
+    def clicks(short_url, opts = {})
+      query_opts = {:link => short_url}.merge(opts)
+      response = get('/clicks/count', :query => query_opts)
+    end
+
+    def get(uri, opts = {})
+      opts[:query] ||= {}
+      opts[:query].merge!(@default_query_opts)
+      response = self.class.get(uri, opts).parsed_response
+      if response.nil?
+        raise Error.new('No response from server.', 0)
+      elsif response['success'] == 1
+        response
+      else
+        raise Error.new(response['error_message'], response['error_code'])
+      end
+    end
+    private :get
+  end
+
+  # This class encapsulates BudURL API errors into a usable form.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code)
+      @code = code
+      super("#{code} - #{message}")
+    end
+  end
+end
+

data/lib/budurl/url.rb

@@ -0,0 +1,31 @@
+require 'date'
+
+module Budurl
+  class Url
+
+    attr_accessor :link, :long_url, :hash
+
+    # Create a Url with values filled in from a Client response.
+    def initialize(client, response = nil)
+      @client = client
+
+      if response && response.is_a?(Hash)
+        @link = response['link']
+        @long_url = response['long_url']
+        @hash = response['hash']
+      end
+    end
+
+    # Retrieve click counts for this shorturl.
+    # daily flag allows day-by-day breakdowns.
+    # date_from and date_to are Date objects which allow filtering.
+    def clicks(daily=false, date_from=nil, date_to=nil)
+      opts = { :daily => daily ? 1 : 0 }
+      opts.merge!(:date_from => date_from.to_s) if date_from
+      opts.merge!(:date_to => date_to.to_s) if date_to
+
+      response = @client.clicks(@link, opts)
+      daily ? response['dates'] : response['count']
+    end
+  end
+end

data/lib/budurl/version.rb

@@ -0,0 +1,3 @@
+module Budurl
+  VERSION = "0.0.1"
+end

data/test/helpers/budurl_mock.rb

@@ -0,0 +1,112 @@
+require 'rubygems'
+require 'mimic'
+require 'json'
+
+class BudurlMock
+
+  API_KEY_ERROR = 100
+  LONG_URL_ERROR = 200
+  SHORT_URL_ERROR = 400
+
+  def initialize
+    self.clear
+  end
+
+  [:api_keys, :short_to_long_urls].each do |var|
+    class_eval %{
+      def self.#{var.to_s}
+        @@#{var}
+      end
+    }
+  end
+
+  def self.clear
+    # valid api keys
+    @@api_keys = []
+
+    # url mappings: short_url => {link, api_key, count, dates => {date => count, ...}}
+    @@short_to_long_urls = {}
+
+    # next unused short_url
+    @@next_hash = 0
+  end
+
+  def self.hash_from_short_url(url)
+    url.match(/^http:\/\/Ez\.com\/(\d{4})$/)[1]
+  end
+
+  def self.short_url_from_hash(hash)
+    "http://Ez.com/#{hash}"
+  end
+
+  def self.find_by_long_url(long_url)
+    short_url = @@short_to_long_urls.select{|k,v| v[:link] == long_url}.last
+    short_url ? short_url[0] : nil
+  end
+
+  def self.error_response(code)
+    {:success => 0, :error_code => code, :error_message => "Error"}
+  end
+
+  Mimic.mimic do
+    get '/links/shrink' do
+      if !@@api_keys.include?(params[:api_key])
+        response = BudurlMock.error_response(API_KEY_ERROR)
+      elsif params[:long_url].empty?
+        response = BudurlMock.error_response(LONG_URL_ERROR)
+      else
+        if params[:dupe_check] != '1' || !(short_url = BudurlMock.find_by_long_url(params[:long_url]))
+          short_url = BudurlMock.short_url_from_hash("%04d" % @@next_hash += 1)
+          @@short_to_long_urls[short_url] = {:link => params[:long_url],
+                                             :api_key => params[:api_key],
+                                             :count => 0,
+                                             :date => {}}
+        end
+        response = {:success => 1,
+                    :link => short_url,
+                    :hash => BudurlMock.hash_from_short_url(short_url),
+                    :link_preview => short_url + '?'}
+      end
+
+      return [200, response.to_json]
+    end
+
+    get '/links/expand' do
+      if !@@api_keys.include?(params[:api_key])
+        response = BudurlMock.error_response(API_KEY_ERROR)
+      elsif params[:link].nil?
+        return [200, nil]
+      else
+        url = @@short_to_long_urls[params[:link]]
+        if url.nil?
+          response = BudurlMock.error_response(SHORT_URL_ERROR)
+        else
+          response = {:success => 1,
+                      :long_url => url[:link]}
+        end
+      end
+
+      return [200, response.to_json]
+    end
+
+    get '/clicks/count' do
+      if !@@api_keys.include?(params[:api_key])
+        response = BudurlMock.error_response(API_KEY_ERROR)
+      elsif params[:link].nil?
+        return [200, nil]
+      elsif !(url = @@short_to_long_urls[params[:link]])
+        response = BudurlMock.error_response(SHORT_URL_ERROR)
+      elsif params[:api_key] != url[:api_key]
+        response = BudurlMock.error_response(API_KEY_ERROR)
+      else
+        response = {:success => 1,
+                    :link => params[:link],
+                    :hash => BudurlMock.hash_from_short_url(params[:link]),
+                    :count => url[:count]}
+        response.merge!(:dates => url[:dates]) if params[:daily] == '1'
+      end
+
+      return [200, response.to_json]
+    end
+  end
+end

data/test/unit/client_spec.rb

@@ -0,0 +1,141 @@
+require 'rubygems'
+require 'rspec'
+require 'budurl'
+require 'budurl/client'
+require File.dirname(__FILE__) + '/../helpers/budurl_mock'
+
+require 'ruby-debug'
+
+describe Budurl::Client do
+
+  MIMIC_BASE_URI = 'http://127.0.0.1:11988'
+  API_KEY = '12345'
+
+  SHORT_URL = 'http://Ez.com/1234'
+  LONG_URL = 'http://www.example.com'
+
+  def create_short_url(long_url, short_url, opts={})
+    data = {:link => long_url,
+            :api_key => API_KEY,
+            :count => 0,
+            :dates => {}}.merge(opts)
+    BudurlMock.short_to_long_urls[short_url] = data
+  end
+
+  before :all do
+    @budurl = Budurl.new(API_KEY, MIMIC_BASE_URI)
+  end
+
+  before :each do
+    BudurlMock.clear
+    BudurlMock.api_keys << API_KEY
+  end
+
+  it 'initialises with the correct API key' do
+    @budurl.instance_variable_get(:@default_query_opts).should == {:api_key => API_KEY}
+  end
+
+  it 'returns a Budurl::Client object' do
+    @budurl.should be_an_instance_of(Budurl::Client)
+  end
+
+  describe '#shorten' do
+    it 'successfully shortens a URL' do
+      url = @budurl.shorten(LONG_URL)
+
+      url.link.should == BudurlMock.find_by_long_url(LONG_URL)
+      url.hash.should == BudurlMock.hash_from_short_url(url.link)
+      url.long_url.should be_nil
+    end
+
+    it 'creates unique short URLs if dupe_check is off' do
+      create_short_url(LONG_URL, SHORT_URL)
+      url = @budurl.shorten(LONG_URL)
+
+      url.link.should_not == SHORT_URL
+      url.hash.should_not == BudurlMock.hash_from_short_url(SHORT_URL)
+      url.long_url.should be_nil
+    end
+
+    it 'returns the last address if dupe_check is on' do
+      create_short_url(LONG_URL, SHORT_URL)
+      url = @budurl.shorten(LONG_URL, :dupe_check => 1)
+
+      url.link.should == SHORT_URL
+      url.hash.should == BudurlMock.hash_from_short_url(SHORT_URL)
+      url.long_url.should be_nil
+    end
+
+    it 'creates a new short URL if dupe_check is on but no duplicates exist' do
+      url = @budurl.shorten(LONG_URL, :dupe_check => 1)
+
+      url.link.should == BudurlMock.find_by_long_url(LONG_URL)
+      url.hash.should == BudurlMock.hash_from_short_url(url.link)
+      url.long_url.should be_nil
+    end
+
+    it 'reports Error 200 when called without a URL' do
+      lambda { @budurl.shorten(nil) }.should raise_error(Budurl::Error, /200/)
+    end
+
+    it 'reports Error 100 when called with an invalid API key' do
+      BudurlMock.api_keys.delete(API_KEY)
+      lambda { @budurl.shorten(LONG_URL) }.should raise_error(Budurl::Error, /100/)
+    end
+  end
+
+  describe '#expand' do
+    it 'successfully expands an extant short URL' do
+      create_short_url(LONG_URL, SHORT_URL)
+      url = @budurl.expand(SHORT_URL)
+
+      url.long_url.should == LONG_URL
+      url.link.should be_nil
+      url.hash.should be_nil
+    end
+
+    it 'reports Error 400 when passed an invalid short URL' do
+      lambda { @budurl.expand(SHORT_URL) }.should raise_error(Budurl::Error, /400/)
+    end
+  end
+
+  describe '#clicks' do
+    it 'produces a total click count' do
+      create_short_url(LONG_URL, SHORT_URL, :count => 10)
+      count = @budurl.clicks(SHORT_URL)
+
+      count.should be_an_instance_of(Hash)
+      count['link'].should == SHORT_URL
+      count['hash'].should == BudurlMock.hash_from_short_url(SHORT_URL)
+      count['count'].should == 10
+      count['dates'].should be_nil
+    end
+
+    it 'produces a day-to-day click count hash with the correct options' do
+      dates = {'2012-01-01' => 3, '2012-01-02' => 4, '2012-01-03' => 3}
+      create_short_url(LONG_URL, SHORT_URL, :count => 10, :dates => dates)
+      count = @budurl.clicks(SHORT_URL, :daily => 1)
+
+      count.should be_an_instance_of(Hash)
+      count['link'].should == SHORT_URL
+      count['hash'].should == BudurlMock.hash_from_short_url(SHORT_URL)
+      count['count'].should == 10
+      count['dates'].should be_an_instance_of(Hash)
+      count['dates'].should == dates
+    end
+
+    it 'reports Error 400 when passed an invalid short URL' do
+      lambda { @budurl.clicks(SHORT_URL) }.should raise_error(Budurl::Error, /400/)
+    end
+
+    it 'reports Error 100 when passed a short URL not belonging to us' do
+      create_short_url(LONG_URL, SHORT_URL, :api_key => '00000')
+      lambda { @budurl.clicks(SHORT_URL) }.should raise_error(Budurl::Error, /100/)
+    end
+
+    it 'reports Error 100 when called with an invalid API key' do
+      BudurlMock.api_keys.delete(API_KEY)
+      lambda { @budurl.clicks(SHORT_URL) }.should raise_error(Budurl::Error, /100/)
+    end
+  end
+end

data/test/unit/url_spec.rb

@@ -0,0 +1,87 @@
+require 'rubygems'
+require 'rspec'
+require 'budurl'
+require 'budurl/url'
+require File.dirname(__FILE__) + '/../helpers/budurl_mock'
+
+require 'ruby-debug'
+
+describe Budurl::Url do
+
+  MIMIC_BASE_URI = 'http://127.0.0.1:11988'
+  API_KEY = '12345'
+
+  SHORT_URL = 'http://Ez.com/1234'
+  LONG_URL = 'http://www.example.com'
+
+  def create_short_url(long_url, short_url, opts={})
+    data = {:link => long_url,
+            :api_key => API_KEY,
+            :count => 0,
+            :dates => {}}.merge(opts)
+    BudurlMock.short_to_long_urls[short_url] = data
+  end
+
+  before :all do
+    @budurl = Budurl.new(API_KEY, MIMIC_BASE_URI)
+  end
+
+  before :each do
+    BudurlMock.clear
+    BudurlMock.api_keys << API_KEY
+  end
+
+  it 'saves the calling Budurl client internally' do
+    url = Budurl::Url.new(@budurl)
+    url.instance_variable_get(:@client).should be_an_instance_of(Budurl::Client)
+  end
+
+  it 'internalizes relevant information from a hash' do
+    data = {'success' => '1',
+            'link' => SHORT_URL,
+            'long_url' => LONG_URL,
+            'hash' => BudurlMock.hash_from_short_url(SHORT_URL)}
+    url = Budurl::Url.new(@budurl, data)
+
+    url.link.should == SHORT_URL
+    url.long_url.should == LONG_URL
+    url.hash.should == BudurlMock.hash_from_short_url(SHORT_URL)
+  end
+
+  describe '#clicks' do
+    it 'returns the click count for a short URL' do
+      create_short_url(LONG_URL, SHORT_URL, :count => 10, :dates => {'2012-01-01' => 10})
+
+      data = {'success' => '1',
+              'link' => SHORT_URL,
+              'long_url' => LONG_URL,
+              'hash' => BudurlMock.hash_from_short_url(SHORT_URL)}
+      url = Budurl::Url.new(@budurl, data)
+
+      url.clicks.should == 10
+    end
+
+    it 'returns the daily click counts for a URL with daily = true' do
+      create_short_url(LONG_URL, SHORT_URL, :count => 10, :dates => {'2012-01-01' => 10})
+
+      data = {'success' => '1',
+              'link' => SHORT_URL,
+              'long_url' => LONG_URL,
+              'hash' => BudurlMock.hash_from_short_url(SHORT_URL)}
+      url = Budurl::Url.new(@budurl, data)
+
+      url.clicks(true).should == {'2012-01-01' => 10}
+    end
+
+    it 'raises Error 0 for a long URL with no short URL associated' do
+      data = {'success' => '1',
+              'link' => SHORT_URL,
+              'long_url' => LONG_URL,
+              'hash' => BudurlMock.hash_from_short_url(SHORT_URL)}
+      url = Budurl::Url.new(@budurl)
+
+      lambda { url.clicks }.should raise_error(Budurl::Error, /0/)
+      lambda { url.clicks(true) }.should raise_error(Budurl::Error, /0/)
+    end
+  end
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification 
+name: budurl
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Anuj Das
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-04-25 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: mimic
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: Supported operations include shrinking, expanding, and counting clicks.
+email: 
+- anuj.das@mylookout.com
+executables: 
+- expand
+- shorten
+- stats
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- bin/expand
+- bin/shorten
+- bin/stats
+- budurl.gemspec
+- lib/budurl.rb
+- lib/budurl/client.rb
+- lib/budurl/url.rb
+- lib/budurl/version.rb
+- test/helpers/budurl_mock.rb
+- test/unit/client_spec.rb
+- test/unit/url_spec.rb
+homepage: https://github.com/lookout/budurl-gem
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A gem for interfacing with the BudURL.Pro url shortener API
+test_files: 
+- test/helpers/budurl_mock.rb
+- test/unit/client_spec.rb
+- test/unit/url_spec.rb