cannikin-postal 0.1.0

data/lib/postal/mailing.rb

@@ -0,0 +1,171 @@
+module Postal
+  class Mailing < Postal::Base
+    
+    class << self
+      
+    end
+    
+    
+    DEFAULT_ATTRIBUTES = {:additional_headers => nil, 
+                          :attachments => nil, 
+                          :bypass_moderation => nil, 
+                          :campaign => nil, 
+                          :char_set_id => nil, 
+                          :detect_html => nil, 
+                          :dont_attempt_after_date => nil, 
+                          :enable_recovery => nil, 
+                          :from => nil, 
+                          :html_message => nil, 
+                          :html_section_encoding => nil, 
+                          :is_html_section_encoded => nil, 
+                          :is_text_section_encoded => nil,
+                          :list_name => nil,
+                          :recency_number_of_mailings => nil,
+                          :recency_which => nil,
+                          :reply_to => nil,
+                          :resend_after_days => nil,
+                          :sample_size => nil,
+                          :scheduled_mailing_date => nil,
+                          :subject => nil,
+                          :text_message => nil,
+                          :text_section_encoding => nil,
+                          :title => nil,
+                          :to => nil,
+                          :track_opens => nil,
+                          :rewrite_date_when_sent => nil }
+    
+    attr_accessor :additional_headers, 
+                  :attachments, 
+                  :bypass_moderation, 
+                  :campaign, 
+                  :char_set_id, 
+                  :detect_html, 
+                  :dont_attempt_after_date, 
+                  :enable_recovery, 
+                  :from, 
+                  :html_message, 
+                  :html_section_encoding, 
+                  :is_html_section_encoded, 
+                  :is_text_section_encoded,
+                  :list_name,
+                  :recency_number_of_mailings,
+                  :recency_which,
+                  :reply_to,
+                  :resend_after_days,
+                  :sample_size,
+                  :scheduled_mailing_date,
+                  :subject,
+                  :text_message,
+                  :text_section_encoding,
+                  :title,
+                  :to,
+                  :track_opens,
+                  :rewrite_date_when_sent
+    
+    # Create a new mailing ready to send
+    def initialize(args={})
+      args = DEFAULT_ATTRIBUTES.merge(args)
+      @to = args[:to] 
+      @additional_headers = args[:additional_headers] 
+      @attachments = args[:attachments] 
+      @bypass_moderation = args[:bypass_moderation] 
+      @campaign = args[:campaign] 
+      @char_set_id = args[:char_set_id] 
+      @detect_html = args[:detect_html] 
+      @dont_attempt_after_date = args[:dont_attempt_after_date] 
+      @enable_recovery = args[:enable_recovery] 
+      @from = args[:from] 
+      @html_message = args[:html_message] 
+      @html_section_encoding = args[:html_section_encoding] 
+      @is_html_section_encoded = args[:is_html_section_encoded] 
+      @is_text_section_encoded = args[:is_text_section_encoded]
+      @list_name = args[:list_name]
+      @recency_number_of_mailings = args[:recency_number_of_mailings]
+      @recency_which = args[:recency_which]
+      @reply_to = args[:reply_to]
+      @resend_after_days = args[:resend_after_days]
+      @sample_size = args[:sample_size]
+      @scheduled_mailing_date = args[:scheduled_mailing_date]
+      @subject = args[:subject]
+      @text_message = args[:text_message]
+      @text_section_encoding = args[:text_section_encoding]
+      @title = args[:title]
+      @to = args[:to]
+      @track_opens = args[:track_opens]
+      @rewrite_date_when_sent = args[:rewrite_date_when_sent]
+    end
+    
+    
+    # Send the mailing
+    def send
+      if valid?
+        mail = Postal::Lmapi::MailingStruct.new(:additionalHeaders => @additional_headers, 
+                                                :attachments => @attachments, 
+                                                :bypassModeration => @bypass_moderation, 
+                                                :campaign => @campaign, 
+                                                :charSetID => @char_set_id, 
+                                                :detectHtml => @detect_html, 
+                                                :dontAttemptAfterDate => @dont_attempt_after_date, 
+                                                :enableRecovery => @enable_recovery, 
+                                                :from => @from, 
+                                                :htmlMessage => @html_message, 
+                                                :htmlSectionEncoding => @html_section_encoding, 
+                                                :isHtmlSectionEncoded => @is_html_section_encoded, 
+                                                :isTextSectionEncoded => @is_text_section_encoded,
+                                                :listName => @list_name,
+                                                :recencyNumberOfMailings => @recency_number_of_mailings,
+                                                :recencyWhich => @recency_which,
+                                                :replyTo => @reply_to,
+                                                :resendAfterDays => @resend_after_days,
+                                                :sampleSize => @sample_size,
+                                                :scheduledMailingDate => @scheduled_mailing_date,
+                                                :subject => @subject,
+                                                :textMessage => @text_message,
+                                                :textSectionEncoding => @text_section_encoding,
+                                                :title => @title,
+                                                :trackOpens => @track_opens,
+                                                :rewriteDateWhenSent => @rewrite_date_when_sent )
+        
+        # are we sending to a list of email addresses or member ids
+        case @to.to_a.first
+        when ::String
+          emails = @to.to_a
+          member_ids = []
+        when ::Fixnum
+          emails = []
+          member_ids = @to.to_a
+        end
+
+        return Postal.driver.sendMailingDirect(emails,member_ids,mail)
+      else
+        return false
+      end
+    end
+    
+    
+    # same as send() but throws an error instead of just returning false
+    def send!
+      if id = send
+        return id
+      else
+        raise Postal::CouldNotSendMailing, 'Your mail was invalid and could not be sent.'
+      end
+    end
+    
+    alias_method :save, :send
+    alias_method :save!, :send!
+    
+    
+    # Determines whether the email is valid to send
+    def valid?
+      return validate
+    end
+    
+    
+    # Determines whether we have everything we need to send an email
+    def validate
+      return (@list_name && @to && @subject) ? true : false
+    end
+    
+  end
+end

data/lib/postal/member.rb

@@ -0,0 +1,115 @@
+module Postal
+  class Member < Postal::Base
+    
+    class << self
+      
+      def find_by_filter(args)
+        return Postal.driver.selectMembers(args)
+      end
+      
+      
+      # Will NOT let you delete the entire list's members (only pass a ListName) Returns the number of members that were deleted, or nil if none were
+      def destroy(args)
+        raise Postal::WouldDeleteAllMembers, 'Not passing any parameters (other than ListName) to this method will delete ALL members of a list. If you really want to delete all members of this list, use destroy! instead.' if args.to_a.size == 1 && args.to_a.first.match(/ListName/)
+        return Postal.driver.deleteMembers(args)
+      end
+      
+      
+      # WILL let you delete an entire list's members (only pass a ListName). Returns the number of members that were deleted, or nil if none were
+      def destroy!(args)
+        return Postal.driver.deleteMembers(args)
+      end
+      
+      
+      protected
+      
+        def find_by_email(args,options)
+          list_name = args.last
+          member_id = 0
+          email = args.first
+          begin
+            return Postal.driver.getMemberID(Postal::Lmapi::SimpleMemberStruct.new(list_name,member_id,email))
+          rescue SOAP::FaultError
+            return nil
+          end
+        end
+      
+      
+        def find_by_id(args,options)
+          member_id = args.first
+          return Postal.driver.getEmailFromMemberID(member_id)
+        end
+        
+      
+        # Find one or more members by name
+        def find_some(args,options={})
+          case args.first
+          when ::String
+            find_by_email(args,options)
+          when ::Fixnum
+            find_by_id(args,options)
+          when nil
+            find_by_struct(options)
+          end
+        end
+      
+    end
+    
+    DEFAULT_ATTRIBUTES = { :id => nil, :email => nil, :name => nil, :list_name => nil, :demographics => nil }
+    
+    attr_accessor :id, :email, :name, :list_name, :demographics
+    
+    # Create a new member instance
+    def initialize(email,name,list_name,demographics={})
+      @id = nil
+      @email = email
+      @name = name
+      @list_name = list_name
+      @demographics = demographics
+    end
+    
+    
+    # Save the member to Lyris and returns the member ID that was created. Returns `false` if the save fails.
+    def save
+      # if @list is a list Object then get the name out (all Lyris wants is the name)
+      list_name = @list_name
+      begin
+        @id = Postal.driver.createSingleMember(@email, @name, list_name)
+        update_attributes(@demographics) unless @demographics.empty?
+        return @id
+      rescue SOAP::FaultError
+        return false
+      end
+    end
+    
+    
+    # Saves the member to Lyris and returns the member ID that was created. Throws an error if the save fails.
+    def save!
+      if id = save
+        return id
+      else
+        raise Postal::CouldNotCreateMember, 'Could not create a new member. The most likely cause is that the specified list already contains this email address.'
+      end
+    end
+    
+    
+    # Update the demographics for a user
+    def update_attributes(attributes={})
+      list_name = @list_name
+      demos = attributes.collect { |key,value| Postal::Lmapi::KeyValueType.new(value,key.to_s) }
+      member = Postal::Lmapi::SimpleMemberStruct.new(list_name, @id, @email)
+      return Postal.driver.updateMemberDemographics(member,demos)
+    end
+    
+    
+    # Throw an error if demographics couldn't be saved
+    def update_attributes!(attributes={})
+      if update_attributes(attributes)
+        return true
+      else
+        raise Postal::CouldNotUpdateMember, 'Could not update the member. The most likely cause is that your demographics are invalid.'
+      end
+    end
+    
+  end
+end

data/lib/postal.rb

@@ -0,0 +1,47 @@
+$:.unshift File.dirname(__FILE__) # for use/testing when no gem is installed
+
+# external
+require 'logger'
+
+# internal
+require 'postal/lmapi/lmapi.rb'
+require 'postal/lmapi/lmapi_driver.rb'
+require 'postal/lmapi/lmapi_mapping_registry.rb'
+require 'postal/base'
+require 'postal/list'
+require 'postal/member'
+require 'postal/mailing'
+
+module Postal
+  
+  # error classes
+  class CouldNotCreateMember < StandardError; end;
+  class CouldNotUpdateMember < StandardError; end;
+  class CouldNotSendMailing < StandardError; end;
+  class WouldDeleteAllMembers < StandardError; end;
+  
+  VERSION = '0.1.0'
+  LOGGER = Logger.new(STDOUT)
+  
+  DEFAULT_OPTIONS = { :debug => false }
+  
+  @options = {  :wsdl => nil, 
+                :username => nil, 
+                :password => nil }
+  @driver = nil
+  
+  attr_accessor :options
+  
+  # Make a driver instance available at Postal.driver
+  def driver
+    unless @driver
+      @driver = Postal::Lmapi::Soap.new
+      @driver.options['protocol.http.basic_auth'] << [@options[:wsdl], @options[:username], @options[:password]]
+    end
+    return @driver
+  end
+  
+  # make @options available so it can be set externally when using the library
+  extend self
+  
+end

data/postal.gemspec

@@ -0,0 +1,63 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{postal}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Rob Cameron"]
+  s.date = %q{2009-08-28}
+  s.description = %q{Lyris is an enterprise email service. Postal makes it easy for Ruby to talk to Lyris's API.}
+  s.email = %q{cannikinn@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/postal.rb",
+     "lib/postal/base.rb",
+     "lib/postal/list.rb",
+     "lib/postal/lmapi/lmapi.rb",
+     "lib/postal/lmapi/lmapi_driver.rb",
+     "lib/postal/lmapi/lmapi_mapping_registry.rb",
+     "lib/postal/mailing.rb",
+     "lib/postal/member.rb",
+     "postal.gemspec",
+     "test/list_test.rb",
+     "test/lmapiClient.rb",
+     "test/lyris_sample.yml",
+     "test/mailing_test.rb",
+     "test/member_test.rb",
+     "test/postal_suite.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/cannikin/postal}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Gem for talking to the Lyris API}
+  s.test_files = [
+    "test/list_test.rb",
+     "test/lmapiClient.rb",
+     "test/mailing_test.rb",
+     "test/member_test.rb",
+     "test/postal_suite.rb",
+     "test/test_helper.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
+    else
+    end
+  else
+  end
+end

data/test/list_test.rb

@@ -0,0 +1,20 @@
+require 'test_helper'
+
+class ListTest < Test::Unit::TestCase
+  
+  @config = nil
+
+  def setup
+    load_config
+  end
+  
+  # lists
+  def test_can_find_list_that_exists
+    assert Postal::List.find(@config['list_name'])
+  end
+  
+  def test_returns_nil_if_list_not_found
+    assert_nil Postal::List.find('foo')
+  end
+  
+end