defender 0.1.1 → 0.2.0

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2009 Henrik Hodne
+  Copyright (c) 2009-2010 Henrik Hodne
 
-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:
+  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 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.
+  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.rdoc

@@ -2,6 +2,10 @@
 
 This is a Ruby wrapper of the Defensio[http://defensio.com] spam filtering API. To use this library, you need an API key from Defensio. Go ahead and {get one}[http://defensio.com/signup/].
 
+Thanks to Defensio for the excellent documentation, the documentation in the code is more or less copied from them.
+
+Defender follows the {Semantic Versioning}[http://semver.org/] spec.
+
 == Note on Patches/Pull Requests
  
 * Fork the project.
@@ -15,4 +19,4 @@ This is a Ruby wrapper of the Defensio[http://defensio.com] spam filtering API.
 
 == Copyright
 
-Copyright (c) 2009 Henrik Hodne. See LICENSE for details.
+Copyright (c) 2009-2010 Henrik Hodne. See LICENSE for details.

data/Rakefile

@@ -10,9 +10,10 @@ begin
     gem.email = "henrik.hodne@binaryhex.com"
     gem.homepage = "http://github.com/dvyjones/defender"
     gem.authors = ["Henrik Hodne"]
-    gem.add_development_dependency "rspec", ">= 1.2.9"
-    gem.add_development_dependency "yard", ">= 0"
-    gem.add_development_dependency "mocha", ">= 0.9.8"
+    gem.add_dependency "httparty", "~> 0.4.3"
+    gem.add_development_dependency "rspec", "~> 1.2.9"
+    gem.add_development_dependency "yard", "~> 0.4.0" 
+    gem.add_development_dependency "fakeweb", "~> 1.2.7"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
@@ -62,9 +63,12 @@ task :default => :spec
 
 begin
   require 'yard'
-  YARD::Rake::YardocTask.new
+  YARD::Rake::YardocTask.new do |conf|
+    #conf.options = ["-mmarkdown"]
+    conf.files = ["lib/**/*.rb", "-", "LICENSE"]
+  end
 rescue LoadError
-  task :yardoc do
+  task :yard do
     abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
   end
 end

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/defender.gemspec

@@ -0,0 +1,70 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{defender}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Henrik Hodne"]
+  s.date = %q{2010-01-20}
+  s.description = %q{A wrapper of the Defensio spam filtering service.}
+  s.email = %q{henrik.hodne@binaryhex.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "defender.gemspec",
+     "lib/defender.rb",
+     "lib/defender/document.rb",
+     "lib/defender/statistics.rb",
+     "spec/defender_spec.rb",
+     "spec/document_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/statistics_spec.rb"
+  ]
+  s.homepage = %q{http://github.com/dvyjones/defender}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Ruby API wrapper for Defensio}
+  s.test_files = [
+    "spec/spec_helper.rb",
+     "spec/document_spec.rb",
+     "spec/defender_spec.rb",
+     "spec/statistics_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<httparty>, ["~> 0.4.3"])
+      s.add_development_dependency(%q<rspec>, ["~> 1.2.9"])
+      s.add_development_dependency(%q<yard>, ["~> 0.4.0"])
+      s.add_development_dependency(%q<fakeweb>, ["~> 1.2.7"])
+    else
+      s.add_dependency(%q<httparty>, ["~> 0.4.3"])
+      s.add_dependency(%q<rspec>, ["~> 1.2.9"])
+      s.add_dependency(%q<yard>, ["~> 0.4.0"])
+      s.add_dependency(%q<fakeweb>, ["~> 1.2.7"])
+    end
+  else
+    s.add_dependency(%q<httparty>, ["~> 0.4.3"])
+    s.add_dependency(%q<rspec>, ["~> 1.2.9"])
+    s.add_dependency(%q<yard>, ["~> 0.4.0"])
+    s.add_dependency(%q<fakeweb>, ["~> 1.2.7"])
+  end
+end
+

data/lib/defender.rb

@@ -1,299 +1,67 @@
-require 'yaml'
-require 'net/http'
+require 'httparty'
+
+require 'defender/document'
+require 'defender/statistics'
+
+module Defender
+  VERSION = "0.2.0"
+
+  include HTTParty
 
-class Defender
   # The Defensio API version currently supported by Defender
-  API_VERSION = "1.2"
-  
-  ROOT_URL = "http://api.defensio.com/"
-  
-  DEFAULT_OPTIONS = {
-    :service_type => "blog",
-    :api_key => "",
-    :owner_url => ""
-  }
-  
-  ##
-  # Raised if an invalid or no API key is given
-  class APIKeyError < StandardError; end
-  
-  ##
-  # The response from the {Defender#audit_comment} method. Should only be
-  # initialized by the library.
-  class CommentResponse
+  API_VERSION = "2.0"
+
+  # HTTParty config
+  format :json
+  base_uri "api.defensio.com/#{API_VERSION}/users"
+
+  class << self
     ##
-    # A message signature that uniquely identifies the comment in the Defensio
-    # system. This signature should be stored by the client for retraining
-    # purposes.
-    attr_reader :signature
-    
+    # Your Defensio API key. You need to register at defensio.com to get a key.
+    attr_accessor :api_key
+
     ##
-    # A value indicating the relative likelihood of the comment being spam.
-    # This value should be stored by the client for use in building convenient
-    # spam sorting user-interfaces.
+    # The URL that will be called when Defensio is done analyzing a comment with
+    # asynchronous callbacks. You should be able to pass the request parameters
+    # straight into {Document#set_attributes}. The signature will be in the
+    # `signature` parameter.
     #
-    # @return [Float] A value between 0 and 1.
-    attr_reader :spaminess
-    
-    ##
-    # Initialize a CommentResponse. Should only be called by the library.
+    # *IMPORTANT*: Defensio will NOT retry unsuccessful callbacks to your
+    # server. If you do not see a POST originating from Defensio after 5
+    # minutes, call {Document#refresh!} on the document to obtain the analysis
+    # result.
     #
-    # @param [Hash] response The response from the audit-comment call.
-    def initialize(response)
-      @signature = response["signature"]
-      @spam = response["spam"]
-      @spaminess = response["spaminess"].to_f
-    end
-    
-    ##
-    # Returns true if Defensio marked the comment as spam, returns false
-    # otherwise.
+    # Occasionally, Defensio may perform more than one POST request to your
+    # server for the same document. For example, if new evidence indicates that
+    # a document is unwanted, even though it was originally identified as
+    # legitimate, Defensio might notify you that the classification has changed.
     #
-    # @return [Boolean]
-    def spam?; @spam; end
-    
-    def to_s; @signature; end
-  end
-  
-  ##
-  # The response from the {Defender#statistics} method. Should only be
-  # initialized by the library.
-  class Statistics
-    ##
-    # Describes the percentage of comments correctly identified as spam/ham by
-    # Defensio on this blog.
+    # If you do not provide this and use asynchronous calling, you need to call
+    # {Document#refresh!} to get the analysis result.
     #
-    # @return [Float<0..1>]
-    def accuracy; @response["accuracy"]; end
-    
-    ##
-    # The number of spam comments caught by the filter.
-    def spam; @response["spam"]; end
-    
-    ##
-    # The number of ham (legitimate) comments accepted by the filter.
-    def ham; @response["ham"]; end
-    
-    ##
-    # The number of times a legitimate message was retrained from the spambox
-    # (i.e. "de-spammed" by the user)
-    def false_positives; @response["false-positives"]; end
-    
-    ##
-    # The number of times a spam message was retrained from comments box (i.e.
-    # "de-legitimized" by the user)
-    def false_negatives; @response["false-negatives"]; end
-    
-    ##
-    # A boolean value indicating whether Defensio is still in its initial
-    # learning phase.
+    # You can debug callbacks using http://postbin.org. See the Defensio API
+    # documents for the format of the requests.
     #
-    # @return [Boolean]
-    def learning; @response["learning"]; end
-    
-    ##
-    # More details on the reason(s) why Defensio is still in its initial
-    # learning phase.
-    def learning_status; @response["learning-status"]; end
-    
-    def initialize(response); @response = response; end
-  end
-  
-  attr_accessor :service_type, :api_key, :owner_url
-  
-  ##
-  # Raises a StandardError with the error message from Defensio if the
-  # response is a "failed" one.
-  #
-  # @param [Hash] response The return value from {#call_action}.
-  def self.raise_if_error(response)
-    if response["status"] == "fail"
-      raise StandardError, response["message"]
-    end
-    response
-  end
-  
-  ##
-  # Converts a hash with symbol keys and underscores to a hash with string
-  # keys and hyphens. Calls #strftime or #to_s on the values.
-  #
-  # @param [Hash] options Input options.
-  # @return [Hash]
-  def self.options_to_parameters(options)
-    opts = {}
-    options.each do |key, val|
-      opts[key.to_s.gsub("_", "-").downcase] = val.respond_to?(:strftime) ? 
-        val.strftime("%Y/%m/%d") : val.to_s
-    end
-    opts
+    # @return [String]
+    attr_accessor :async_callback
   end
 
   ##
-  # Initialize Defender
+  # Determines if the given API key is valid or not. This should only be used
+  # when configuring the client and prior to every content analysis (Document
+  # POST).
   #
-  # @param [Hash] opts The options hash.
-  # @option opts ["blog","app"] :service_type ("blog") The service type. May be
-  #   "app" (use of Defender within an application) or "blog" (use of Defender
-  #   to support a blogging platform).
-  # @option opts [String] :api_key Your API key. This option is required, the
-  #   method calls will fail without it.
-  def initialize(opts={})
-    opts = DEFAULT_OPTIONS.merge(opts)
-    @service_type = opts[:service_type]
-    @api_key = opts[:api_key]
-    @owner_url = opts[:owner_url]
-  end
-  
-  ##
-  # Checks if the given key is valid.
-  #
-  # @return [Boolean]
-  # @see http://defensio.com/api/#validate-key
-  def valid_key?
-    call_action("validate-key")["status"] == "success" ? true : false
-  end
-  
-  ##
-  # Announce an article existence. This should (if feasible) be called when an
-  # article or blogpost is created so Defensio can analyse it.
+  # Set the API key using {Defender.api_key}.
   #
-  # @param [Hash] opts All options are required.
-  # @option opts [#to_s] :article_title The title of the article
-  # @option opts [#to_s] :article_author The name of the author of the article
-  # @option opts [#to_s] :article_author_email The email address of the person posting the
-  #   article.
-  # @option opts [#to_s] :article_content The content of the article itself.
-  # @option opts [#to_s] :permalink The permalink of the article just posted.
-  # @raise [StandardError] If the call fails, a StandardError is raised with
-  #   the error message given from Defensio.
-  # @return [Boolean] Returns true if the article was successfully announced,
-  #   raises StandardError otherwise.
-  # @see http://defensio.com/api/#announce-article
-  def announce_article(opts={})
-    response = call_action(Defender.options_to_parameters(opts))
-    true
-  end
-  
-  ##
-  # Check if a comment is spam. This is the central action of Defensio.
-  #
-  # @param [Hash] opts All options are recommended, but only required if noted.
-  # @option opts [#to_s] :user_ip The IP address of whomever is posting the
-  #   comment. This option is required.
-  # @option opts [#to_s, #strftime] :article_date The date the original blog
-  #   article was posted. If a string is given, it must be in the format
-  #   "yyyy/mm/dd". This option is required.
-  # @option opts [#to_s] :comment_author The name of the author of the comment.
-  #   This option is required.
-  # @option opts ["comment", "trackback", "pingback", "other"] :comment_type
-  #   The type of the comment being posted to the blog. This option is required
-  # @option opts [#to_s] :comment_content The actual content of the comment
-  #   (strongly recommended to be included where ever possible).
-  # @option opts [#to_s] :comment_author_email The email address of the person
-  #   posting the comment.
-  # @option opts [#to_s] :comment_author_url The URL of the person posting the
-  #   comment.
-  # @option opts [#to_s] :permalink The permalink of the blog post to which
-  #   the comment is being posted.
-  # @option opts [#to_s] :referrer The URL of the site that brought commenter
-  #   to this page.
-  # @option opts [Boolean] :user_logged_in Whether or not the user posting
-  #   the comment is logged-into the blogging platform
-  # @option opts [Boolean] :trusted_user Whether or not the user is an
-  #   administrator, moderator or editor of this blog; the client should pass
-  #   true only if blogging platform can guarantee that the user has been
-  #   authenticated and has a role of responsibility on this blog.
-  # @option opts [#to_s] :openid The OpenID URL of the currently logged in
-  #   user. Must be used in conjunction with :user_logged_in => true. OpenID
-  #   authentication must be taken care of by your application.
-  # @option opts [#to_s] :test_force For testing purposes only: Use this
-  #   parameter to force the outcome of audit_comment. Optionally affix (with
-  #   a comma) a desired spaminess return value (in the range 0 to 1).
-  #   Example: "spam,0.5000" or "ham,0.0010".
-  # @raise [StandardError] If the call fails, a StandardError is raised with
-  #   the error message given from Defensio.
-  # @return [Defender::CommentResponse]
-  # @see http://defensio.com/api/#audit-comment
-  def audit_comment(opts={})
-    response = call_action("audit-comment", Defender.options_to_parameters(opts))
-    return CommentResponse.new(response)
-  end
-  
-  ##
-  # This action is used to retrain false negatives. False negatives are
-  # comments that were originally tagged as "ham" (i.e. legitimate) but were
-  # in fact spam.
-  # 
-  # @param [Array<#to_s, CommentResponse>] signatures List of signatures (may
-  #   contain a single entry) of the comments to be submitted for retraining.
-  #   Note that a signature for each comment was originally provided by the
-  #   {#audit_comment} method.
-  # @raise [StandardError] If the call fails, a StandardError is raised with
-  #   the error message given from Defensio.
-  # @return [Boolean] Returns true if the comments were successfully marked,
-  #   raises StandardError otherwise.
-  def report_false_negatives(signatures)
-    report_false(:negatives, signatures)
-  end
-  
-  ##
-  # This action is used to retrain false negatives. False negatives are
-  # comments that were originally tagged as spam but were in fact "ham" (i.e.
-  # legitimate).
-  # 
-  # @param [Array<#to_s, CommentResponse>] signatures List of signatures (may
-  #   contain a single entry) of the comments to be submitted for retraining.
-  #   Note that a signature for each comment was originally provided by the
-  #   {#audit_comment} method.
-  # @raise [StandardError] If the call fails, a StandardError is raised with
-  #   the error message given from Defensio.
-  # @return [Boolean] Returns true if the comments were successfully marked,
-  #   raises StandardError otherwise.
-  def report_false_positives(signatures)
-    report_false(:positives, signatures)
-  end
-  
-  ##
-  # This action returns basic statistics regarding the performance of Defensio
-  # since activation.
-  #
-  # @return [Defender::Statistics]
-  def statistics
-    response = call_action("get-stats")
-    return Statistics.new(response)
-  end
-  
-  private
-    def report_false(type, signatures)
-      call_action("report-false-#{type}",
-                           "signatures" => signatures.join(","))
-      true
-    end
-  
-    ##
-    # Returns the url for the given action.
-    #
-    # @param [#to_s] action The action to generate the URL for.
-    # @return [String] The URL for the action.
-    # @raise [APIKeyError] Raises this if no API key is given.
-    def url(action)
-      raise APIKeyError unless @api_key.length > 0
-      "#{ROOT_URL}#{@service_type}/#{API_VERSION}/#{action}/#{@api_key}.yaml"
-    end
-    
-    ##
-    # Backend function for calling an action.
-    #
-    # @param [#to_s] action The action to call.
-    # @param [Hash] params The parameters for the action.
-    # @return [Hash] The raw response, only parsed from YAML.
-    # @raise [APIKeyError] If an invalid (or no) API key is given, this is
-    #   raised
-    def call_action(action, params={})
-      response = Net::HTTP.post_form(URI.parse(url(action)),
-        {"owner-url" => @owner_url}.merge(params))
-      response.code == 401 ?
-        raise(APIKeyError) :
-        Defender.raise_if_error(YAML.load(response.body)["defensio-result"])
+  # @return [Boolean] Whether the API key was valid or not.
+  def self.check_api_key
+    key = Defender.api_key
+    return false unless key
+    resp = get("/#{key}.json")['defensio-result']
+    if resp['status'] == 'success'
+      return true
+    else
+      return false
     end
+  end
 end