google_apps 0.5 → 0.9

data/google_apps.gemspec

@@ -0,0 +1,20 @@
+Gem::Specification.new do |spec|
+  spec.name = 'google_apps'
+  spec.version = '0.9'
+  spec.date = '2013-03-11'
+  spec.license = "MIT"
+  spec.summary = 'Google Apps APIs'
+  spec.description = 'Library for interfacing with Google Apps\' Domain and Application APIs'
+  spec.authors = ['Glen Holcomb', 'Will Read']
+  spec.files = Dir.glob(File.join('**', 'lib', '**', '*.rb'))
+  spec.homepage = 'https://github.com/LeakyBucket/google_apps'
+
+  spec.add_dependency('libxml-ruby', '>= 2.2.2')
+  spec.add_dependency('httparty')
+
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'webmock'
+
+  spec.files = `git ls-files`.split("\n")
+  spec.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+end

data/lib/google_apps/atom/atom.rb

@@ -29,16 +29,13 @@ module GoogleApps
 
     ENTRY_TAG = ["<atom:entry xmlns:atom=\"#{NAMESPACES[:atom]}\" xmlns:apps=\"#{NAMESPACES[:apps]}\" xmlns:gd=\"#{NAMESPACES[:gd]}\">", '</atom:entry>']
 
-
-
-    # 
-    # Adds a Module Function that creates a corresponding document.
+    # Adds a Module Function that creates a corresponding document.
     # This allows for a centralized location for document creation.
-    # 
-    # @param [String] type
-    # 
-    # @visibility public
-    # @return 
+    #
+    # @param [String] type should correspond to the class name
+    #
+    # @visibility public
+    # @return
     def add_doc_dispatcher(type)
       eval "def #{type}(*args)\n  #{type.camel_up}.new *args\nend" # Needs __file__ and __line__
       module_function type.to_sym

data/lib/google_apps/atom/export.rb

@@ -13,8 +13,8 @@ module GoogleApps
       def to_s
         @doc.to_s
       end
-      
-      # start_date specifies a start date for the extract.  
+
+      # start_date specifies a start date for the extract.
       # Matching results that occurred before this date will
       # not be included in the result set.  start_date takes
       # a string as an argument, the format is as follows:
@@ -31,7 +31,7 @@ module GoogleApps
         add_prop('beginDate', date)
       end
 
-      # end_date specifies an end date for the extract.  
+      # end_date specifies an end date for the extract.
       # Matching results that occurred past this date will
       # not be included in the result set.  end_date takes
       # a string as an argument, the format is as follows:
@@ -49,7 +49,7 @@ module GoogleApps
       end
 
       # include_deleted will specify that matches which
-      # have been deleted should be returned as well.  
+      # have been deleted should be returned as well.
       # The default is to omit deleted matches.
       #
       # include_deleted
@@ -72,7 +72,7 @@ module GoogleApps
       end
 
       # content specifies the data to be returned in the
-      # mailbox export.  There are two valid arguments: 
+      # mailbox export.  There are two valid arguments:
       # 'FULL_MESSAGE' or 'HEADER_ONLY'
       #
       # content 'HEADER_ONLY'
@@ -82,7 +82,6 @@ module GoogleApps
         add_prop('packageContent', type)
       end
 
-      
       private
 
       # set_header adds the appropriate XML boilerplate for

data/lib/google_apps/atom/feed.rb

@@ -4,16 +4,12 @@ module GoogleApps
       # TODO: Google's feed responses are inconsistent.  Will need special fun time, assholes.
       attr_reader :doc, :items, :next_page
 
-      # TODO: Figure out how to handle Group Members.  The regex below
-      # doesn't work in that case as group members also have group in
-      # the id url.
+      # FIXED:  If we grab the first id element in the feed we can simply scan it.
       TYPE_MATCH = /\/(user|nickname|group|member)/
 
 
       def initialize(xml)
-        id_element = xml.scan(/<id.*?\/id/).first
-        matches = id_element.scan(TYPE_MATCH).flatten
-        type = matches.join '_'
+        type = determine_type xml # This only works when xml is a string.
 
         super(xml)
 
@@ -109,6 +105,21 @@ module GoogleApps
       def entry_wrap(content_array)
         content_array.unshift(Atom::ENTRY_TAG[0]).push(Atom::ENTRY_TAG[1])
       end
+
+
+      #
+      # Determine the feed type from the feed id element.
+      #
+      # @param [String] xml
+      #
+      # @visibility public
+      # @return snake cased doc type
+      def determine_type(xml)
+        id_element = xml.scan(/<id.*?\/id/).first
+        matches = id_element.scan(TYPE_MATCH).flatten
+
+        matches.join '_'
+      end
     end
   end
 end

data/lib/google_apps/document_handler.rb

@@ -1,71 +1,39 @@
 module GoogleApps
   class DocumentHandler
-    # TODO: Should get type list from Document Parent class, not format namespace.
-    attr_accessor :format
-
-    def initialize(args)
-      set_format args[:format]
+    def initialize
+      @documents = look_up_doc_types
     end
 
-
     # create_doc creates a document of the specified format
     # from the given string.
     def create_doc(text, type = nil)
       @documents.include?(type) ? doc_of_type(text, type) : unknown_type(text)
     end
 
-
     # unknown_type takes a string and returns a document of
     # of the corresponding @format.
     def unknown_type(text)
-      case @format
-      when :atom, :xml
-        Atom::XML::Document.string(text)
-      end
+      Atom::XML::Document.string(text)
     end
 
-
-    # format= sets the format for the DocumentHandler
-    def format=(format)
-      set_format format
-    end
-
-
     # doc_of_type takes a document type and a string and
     # returns a document of that type in the current format.
     def doc_of_type(text, type)
-      raise "No #{@format.to_s.capitalize} document of type: #{type}" unless @documents.include?(type.to_s)
+      raise "No Atom document of type: #{type}" unless @documents.include?(type.to_s)
 
-      case @format
-      when :atom, :xml
-        GoogleApps::Atom.send(type, text)
-      end
+      GoogleApps::Atom.send(type, text)
     end
 
-
-
     private
 
-
     # look_up_doc_types returns a list of document types the
     # library supports in the current format.
     def look_up_doc_types
-      case @format
-      when :atom, :xml
-        Atom::Document.types.inject([]) { |types, subclass| types | [sub_to_meth(subclass)] }
-      end
+      Atom::Document.types.map { |subclass| sub_to_meth(subclass) }
     end
 
-
     def sub_to_meth(subclass) # TODO: This shouldn't be both here and in GoogleApps::Atom::Document
       subclass.to_s.split('::').last.scan(/[A-Z][a-z0-9]+/).map(&:downcase).join('_')
     end
-
-
-    # set_format Sets @format and @documents
-    def set_format(format)
-      @format = format
-      @documents = look_up_doc_types
-    end
   end
 end

data/lib/google_apps/transport.rb

@@ -4,53 +4,35 @@ require 'rexml/document'
 
 module GoogleApps
   class Transport
-    attr_reader :request, :response, :domain, :feeds
-    attr_accessor :auth, :user, :group, :nickname, :export, :group, :requester, :migration
+    attr_reader :domain, :token
+    attr_reader :user, :group, :nickname, :export, :pubkey, :requester, :migration
 
-    SUCCESS_CODES = [200, 201, 202]
     BOUNDARY = "=AaB03xDFHT8xgg"
     PAGE_SIZE = {
       user: 100,
       group: 200
     }
+    FEEDS_ROOT = 'https://apps-apis.google.com/a/feeds'
 
-    def initialize(domain, targets = {})
-      @feeds_root = 'https://apps-apis.google.com/a/feeds'
-      @auth = targets[:auth] || "https://www.google.com/accounts/ClientLogin"
-      @user = targets[:user] || "#{@feeds_root}/#{domain}/user/2.0"
-      @pubkey = targets[:pubkey] || "#{@feeds_root}/compliance/audit/publickey/#{domain}"
-      @migration = targets[:migration] || "#{@feeds_root}/migration/2.0/#{domain}"
-      @group = targets[:group] || "#{@feeds_root}/group/2.0/#{domain}"
-      @nickname = targets[:nickname] || "#{@feeds_root}/#{domain}/nickname/2.0"
-      @audit = "#{@feeds_root}/compliance/audit/mail"
-      @export = targets[:export] || "#{@audit}/export/#{domain}"
-      @monitor = targets[:monitor] || "#{@audit}/monitor/#{domain}"
-      @domain = domain
-      @requester = AppsRequest || targets[:requester]
-      @doc_handler = DocumentHandler.new format: (targets[:format] || :atom)
-      @token = nil
-      @response = nil
-      @request = nil
-      @feeds = []
-    end
-
-
-    # authenticate will take the provided account and
-    # password and attempt to authenticate them with
-    # Google
-    #
-    # authenticate 'username@domain', 'password'
-    #
-    # authenticate returns the HTTP response received
-    # from Google
-    def authenticate(account, pass)
-      add(@auth, nil, auth_body(account, pass), :auth)
+    def initialize(options)
+      @domain = options[:domain]
+      @token = options[:token]
+      @refresh_token = options[:refresh_token]
+      @token_changed_callback = options[:token_changed_callback]
 
-      set_auth_token
+      @user       = "#{FEEDS_ROOT}/#{@domain}/user/2.0"
+      @pubkey     = "#{FEEDS_ROOT}/compliance/audit/publickey/#{@domain}"
+      @migration  = "#{FEEDS_ROOT}/migration/2.0/#{@domain}"
+      @group      = "#{FEEDS_ROOT}/group/2.0/#{@domain}"
+      @nickname   = "#{FEEDS_ROOT}/#{@domain}/nickname/2.0"
 
-      @response
-    end
+      audit_root  = "#{FEEDS_ROOT}/compliance/audit/mail"
+      @export     = "#{audit_root}/export/#{@domain}"
+      @monitor    = "#{audit_root}/monitor/#{@domain}"
 
+      @requester = AppsRequest
+      @doc_handler = DocumentHandler.new
+    end
 
     # request_export performs the GoogleApps API call to
     # generate a mailbox export.  It takes the username
@@ -62,9 +44,11 @@ module GoogleApps
     # request_export returns the request ID on success or
     # the HTTP response object on failure.
     def request_export(username, document)
-      result = add(@export + "/#{username}", :export_response, document)
+      response = add(export + "/#{username}", document)
+      process_response(response)
+      export = create_doc(response.body, :export_response)
 
-      result.find('//apps:property').inject(nil) do |request_id, node|
+      export.find('//apps:property').inject(nil) do |request_id, node|
         node.attributes['name'] == 'requestId' ? node.attributes['value'].to_i : request_id
       end
     end
@@ -79,26 +63,28 @@ module GoogleApps
     # export_status will return the body of the HTTP response
     # from Google
     def export_status(username, req_id)
-      get(@export + "/#{username}", :export_status, req_id)
+      response = get(export + "/#{username}", req_id)
+      process_response(response)
+      create_doc(response.body, :export_status)
     end
 
+    def create_doc(response_body, type = nil)
+      @doc_handler.create_doc(response_body, type)
+    end
 
     # export_ready? checks the export_status response for the
     # presence of an apps:property element with a fileUrl name
     # attribute.
     #
-    # export_ready? 'lholcomb2', 82834
+    # export_ready?(export_status('username', 847576))
     #
     # export_ready? returns true if there is a fileUrl present
     # in the response and false if there is no fileUrl present
     # in the response.
-    def export_ready?(username, req_id)
-      export_status(username, req_id)
-
-      !(export_file_urls.empty?)
+    def export_ready?(export_status_doc)
+      export_file_urls(export_status_doc).any?
     end
 
-
     # fetch_export downloads the mailbox export from Google.
     # It takes a username, request id and a filename as
     # arguments.  If the export consists of more than one file
@@ -110,8 +96,9 @@ module GoogleApps
     # fetch_export reutrns nil in the event that the export is
     # not yet ready.
     def fetch_export(username, req_id, filename)
-      if export_ready?(username, req_id)
-        download_export(filename).each_with_index { |url, index| url.gsub!(/.*/, "#{filename}#{index}")}
+      export_status_doc = export_status(username, req_id)
+      if export_ready?(export_status_doc)
+        download_export(export_status_doc, filename).each_with_index { |url, index| url.gsub!(/.*/, "#{filename}#{index}")}
       else
         nil
       end
@@ -123,10 +110,10 @@ module GoogleApps
     #
     # download 'url', 'save_file'
     def download(url, filename)
-      @request = @requester.new :get, URI(url), headers(:other)
+      request = requester.new :get, URI(url), headers(:other)
 
       File.open(filename, "w") do |file|
-        file.puts @request.send_request.body
+        file.puts request.send_request.body
       end
     end
 
@@ -139,13 +126,11 @@ module GoogleApps
     # get 'endpoint', 'username'
     #
     # get returns the HTTP response received from Google.
-    def get(endpoint, type, id = nil)
+    def get(endpoint, id = nil)
       id ? uri = URI(endpoint + build_id(id)) : uri = URI(endpoint)
-      @request = @requester.new :get, uri, headers(:other)
-
-      @response = @request.send_request
+      request = requester.new :get, uri, headers(:other)
 
-      process_response(type)
+      request.send_request
     end
 
 
@@ -158,9 +143,14 @@ module GoogleApps
     #
     # get_users returns the final response from google.
     def get_users(options = {})
-      get_all :users, options
-    end
+      limit = options[:limit] || 1000000
+      response = get(user + "?startUsername=#{options[:start]}")
+      process_response(response)
+
+      pages = fetch_pages(response, limit, :feed)
 
+      return_all(pages)
+    end
 
     # get_groups retrieves all the groups from the domain
     #
@@ -168,31 +158,14 @@ module GoogleApps
     #
     # get_groups returns the final response from Google.
     def get_groups(options = {})
-      get_all :groups, options
-    end
+      limit = options[:limit] || 1000000
+      response = get(group + "#{options[:extra]}" + "?startGroup=#{options[:start]}")
+      process_response(response, :feed)
+      pages = fetch_pages(response, limit, :feed)
 
-
-    # get_all retrieves a batch of records of the specified type
-    # from google.  You must specify the type of object you want
-    # to retreive.  You can also specify a start point and a limit.
-    #
-    # get_all 'users', start: 'lholcomb2', limit: 300
-    #
-    # get_all returns the HTTP response received from Google.
-    def get_all(type, options = {})
-      @feeds, page = [], 0
-      type = normalize_type type
-
-      options[:limit] ? limit = options[:limit] : limit = 1000000
-      options[:start] ? get(instance_variable_get("@#{type}") + "#{options[:extra]}" + "?#{start_query(type)}=#{options[:start]}", :feed) : get(instance_variable_get("@#{type}") + "#{options[:extra]}", :feed)
-
-      fetch_feed(page, limit, :feed)
-
-      #@response
-      return_all
+      return_all(pages)
     end
 
-
     # Retrieves the members of the requested group.
     #
     # @param [String] group_id the Group ID in the Google Apps Environment
@@ -201,7 +174,7 @@ module GoogleApps
     # @return
     def get_members_of(group_id, options = {})
       options[:extra] = "/#{group_id}/member"
-      get_all :groups, options
+      get_groups options
     end
 
 
@@ -216,7 +189,9 @@ module GoogleApps
     #
     # add_member_to returns the response received from Google.
     def add_member_to(group_id, document)
-      add(@group + "/#{group_id}/member", nil, document)
+      response = add(group + "/#{group_id}/member", document)
+      process_response(response)
+      create_doc(response.body)
     end
 
 
@@ -227,7 +202,7 @@ module GoogleApps
     # @visibility public
     # @return
     def add_owner_to(group_id, document)
-      add(@group + "/#{group_id}/owner", nil, document)
+      add(group + "/#{group_id}/owner", nil, document)
     end
 
     # TODO: Refactor delete froms.
@@ -239,18 +214,16 @@ module GoogleApps
     #
     # delete_member_from returns the respnse received from Google.
     def delete_member_from(group_id, member_id)
-      delete(@group + "/#{group_id}/member", member_id)
+      delete(group + "/#{group_id}/member", member_id)
     end
 
-
-    #
     # @param [String] group_id Email address of group
     # @param [String] owner_id Email address of owner to remove
     #
     # @visibility public
     # @return
     def delete_owner_from(group_id, owner_id)
-      delete(@group + "/#{group_id}/owner", owner_id)
+      delete(group + "/#{group_id}/owner", owner_id)
     end
 
 
@@ -273,15 +246,13 @@ module GoogleApps
     # add 'endpoint', document
     #
     # add returns the HTTP response received from Google.
-    def add(endpoint, type, document, header_type = nil)
+    def add(endpoint, document, header_type = nil)
       header_type = :others unless header_type
       uri = URI(endpoint)
-      @request = @requester.new :post, uri, headers(header_type)
-      @request.add_body document.to_s
-
-      @response = @request.send_request
+      request = requester.new :post, uri, headers(header_type)
+      request.add_body document.to_s
 
-      process_response type
+      request.send_request
     end
 
     # update is a generic target for method_missing.  It is
@@ -290,17 +261,15 @@ module GoogleApps
     # It takes an API endpoint and a GoogleApps::Atom document
     # as arguments.
     #
-    # update 'endpoint', document
+    # update 'endpoint', target, document
     #
     # update returns the HTTP response received from Google
-    def update(endpoint, type, target, document)
+    def update(endpoint, target, document)
       uri = URI(endpoint + "/#{target}")
-      @request = @requester.new :put, uri, headers(:other)
-      @request.add_body document.to_s
+      request = requester.new :put, uri, headers(:other)
+      request.add_body document.to_s
 
-      @response = @request.send_request
-
-      process_response type
+      request.send_request
     end
 
     # delete is a generic target for method_missing.  It is
@@ -313,9 +282,9 @@ module GoogleApps
     # delete returns the HTTP response received from Google.
     def delete(endpoint, id)
       uri = URI(endpoint + "/#{id}")
-      @request = @requester.new :delete, uri, headers(:other)
+      request = requester.new :delete, uri, headers(:other)
 
-      @response = @request.send_request
+      request.send_request
     end
 
     # migration performs mail migration from a local
@@ -327,47 +296,39 @@ module GoogleApps
     #
     # migrate returns the HTTP response received from Google.
     def migrate(username, properties, message)
-      @request = @requester.new(:post, URI(@migration + "/#{username}/mail"), headers(:migration))
-      @request.add_body multi_part(properties.to_s, message)
+      request = requester.new(:post, URI(migration + "/#{username}/mail"), headers(:migration))
+      request.add_body multi_part(properties.to_s, message)
 
-      @request.send_request
+      request.send_request
     end
 
-
-
     def method_missing(name, *args)
       super unless name.match /([a-z]*)_([a-z]*)/
 
       case $1
       when "new", "add"
-        self.send(:add, instance_variable_get("@#{$2}"), $2, *args)
+        response = self.send(:add, send($2), *args)
+        process_response(response)
+        create_doc(response.body, $2)
       when "delete"
-        self.send(:delete, instance_variable_get("@#{$2}"), *args)
+        response = self.send(:delete, send($2), *args)
+        process_response(response)
+        create_doc(response.body, $2)
       when "update"
-        self.send(:update, instance_variable_get("@#{$2}"), $2, *args)
+        response = self.send(:update, send($2), *args)
+        process_response(response)
+        create_doc(response.body, $2)
       when "get"
-        self.send(:get, instance_variable_get("@#{$2}"), $2, *args)
+        response = self.send(:get, send($2), *args)
+        process_response(response)
+        create_doc(response.body, $2)
       else
         super
       end
     end
 
-
     private
 
-
-    # auth_body generates the body for the authentication
-    # request made by authenticate.
-    #
-    # auth_body 'username@domain', 'password'
-    #
-    # auth_body returns a string in the form of HTTP
-    # query parameters.
-    def auth_body(account, pass)
-      "&Email=#{CGI::escape(account)}&Passwd=#{CGI::escape(pass)}&accountType=HOSTED&service=apps"
-    end
-
-
     # build_id checks the id string.  If it is formatted
     # as a query string it is returned as is.  If not
     # a / is prepended to the id string.
@@ -375,19 +336,16 @@ module GoogleApps
       id =~ /^\?/ ? id : "/#{id}"
     end
 
-
-    # export_file_urls searches @response for any apps:property elements with a
+    # export_file_urls searches an export status doc for any apps:property elements with a
     # fileUrl name attribute and returns an array of the values.
-    def export_file_urls
-      Atom::XML::Document.string(@response.body).find('//apps:property').inject([]) do |urls, prop|
-        urls << prop.attributes['value'] if prop.attributes['name'].match 'fileUrl'
-        urls
+    def export_file_urls(export_status_doc)
+      export_status_doc.find("//apps:property[contains(@name, 'fileUrl')]").collect do |prop|
+        prop.attributes['value']
       end
     end
 
-
-    def download_export(filename)
-      export_file_urls.each_with_index do |url, index|
+    def download_export(export, filename)
+      export_file_urls(export).each_with_index do |url, index|
         download(url, filename + "#{index}")
       end
     end
@@ -396,100 +354,58 @@ module GoogleApps
     # process_response takes the HTTPResponse and either returns a
     # document of the specified type or in the event of an error it
     # returns the HTTPResponse.
-    def process_response(doc_type = nil)
-      case doc_type
-      when nil
-        success_response? ? true : raise("Error: #{response.code}, #{response.message}")
-      else
-        success_response? ? @doc_handler.create_doc(@response.body, doc_type) : raise("Error: #{response.code}, #{response.message}")
-      end
+    def process_response(response)
+      raise("Error: #{response.code}, #{response.message}") unless success_response?(response)
     end
 
-
-    # error_response? checks to see if Google Responded with a success
-    # code.
-    def success_response?
-      SUCCESS_CODES.include?(@response.code.to_i)
+    def success_response?(response)
+      response.kind_of?(Net::HTTPSuccess)
     end
 
-
-    #
-
     # Takes all the items in each feed and puts them into one array.
     #
     # @visibility private
     # @return Array of Documents
-    def return_all
-      @feeds.inject([]) do |results, feed|
+    def return_all(pages)
+      pages.inject([]) do |results, feed|
         results | feed.items
       end
     end
 
-
-    # Grab the auth token from the response body
-    def set_auth_token
-      @response.body.split("\n").grep(/auth=(.*)/i)
-
-      @token = $1
-    end
-
-
     # get_next_page retrieves the next page in the response.
-    def get_next_page(type)
-      get @feeds.last.next_page, type
-      add_feed
+    def get_next_page(next_page_url, type)
+      response = get(next_page_url)
+      process_response(response)
+      GoogleApps::Atom.feed(response.body)
     end
 
 
     # fetch_feed retrieves the remaining pages in the request.
     # It takes a page and a limit as arguments.
-    def fetch_feed(page, limit, type)
-      add_feed
-      page += 1
+    def fetch_pages(response, limit, type)
+      pages = [GoogleApps::Atom.feed(response.body)]
 
-      while (@feeds.last.next_page) and (page * PAGE_SIZE[:user] < limit)
-        get_next_page type
-        page += 1
+      while (pages.last.next_page) and (pages.count * PAGE_SIZE[:user] < limit)
+        pages << get_next_page(pages.last.next_page, type)
       end
+      pages
     end
 
-
-    # start_query builds the value for the starting point
-    # query string used for retrieving batches of objects
-    # from Google.
-    def start_query(type)
-      case type
-      when 'user'
-        "startUsername"
-      when 'group'
-        "startGroup"
-      end
+    def singularize(type)
+      type.to_s.gsub(/s$/, '')
     end
 
-
-    def normalize_type(type)
-      type.to_s.gsub!(/\w*s$/) { |match| match[0..-2] }
-    end
-
-
-    # add_feed adds a feed to the @feeds array.
-    def add_feed
-      @feeds << GoogleApps::Atom.feed(@response.body)
-    end
-
-
     def headers(category)
       case category
       when :auth
         [['content-type', 'application/x-www-form-urlencoded']]
       when :migration
-        [['content-type', "multipart/related; boundary=\"#{BOUNDARY}\""], ['authorization', "GoogleLogin auth=#{@token}"]]
+        [['content-type', "multipart/related; boundary=\"#{BOUNDARY}\""], ['Authorization', "OAuth #{@token}"]]
       else
-        [['content-type', 'application/atom+xml'], ['authorization', "GoogleLogin auth=#{@token}"]]
+        [['content-type', 'application/atom+xml'], ['Authorization', "OAuth #{@token}"]]
       end
     end
 
-
     def multi_part(properties, message)
       post_body = []
       post_body << "--#{BOUNDARY}\n"