helpscout 0.0.3 → 0.0.4

data/lib/helpscout/models.rb

@@ -1,49 +1,170 @@
-require "date"
-require "httparty"
+# Help Scout API V1 Client
+# http://developer.helpscout.net/
+#
+# These models are used by the HelpScout client.
+#
+# They include wrappers for the three response envelopes, as well as wrappers
+# for the JSON hashes returned in SingleItemEnvelope and CollectionsEnvelope.
+#
+# All date/times returned by the API are in ISO8601 format and in UTC timezone.
 
 module HelpScout
+
+  # Response Envelopes
+  # http://developer.helpscout.net/
+  #
+  # The Help Scout API will return one of three envelopes, depending upon the 
+  # request issued.
+  
+  # Single Item Envelope
+  class SingleItemEnvelope
+    attr_reader :item
+
+    # Creates a new SingleItemEnvelope object from a Hash of attributes
+    def initialize(object)
+      @item = object["item"]
+    end
+  end
+
+  # Collections Envelope
+  class CollectionsEnvelope
+    attr_reader :page, :pages, :count, :items
+    
+    # Creates a new CollectionsEnvelope object from a Hash of attributes
+    def initialize(object)
+      @page = object["page"]
+      @pages = object["pages"]
+      @count = object["count"]
+      @items = object["items"]
+    end
+  end
+
+  # Error Envelope
+  class ErrorEnvelope
+    attr_reader :status, :message
+
+    # Creates a new ErrorEnvelope object from a Hash of attributes
+    def initialize(object)
+      @status = object["status"]
+      @message = object["message"]
+    end    
+  end
+
+
+  # Client Objects
+
+  # Mailbox
+  # http://developer.helpscout.net/objects/mailbox/
+  # http://developer.helpscout.net/objects/mailbox/mailbox-ref/
+  #
+  # MailboxRefs are a subset of a full Mailbox object, and only include the 
+  # attributes marked with a *.
+  #
+  # MailboxRefs are returned by endpoints that include multiple mailboxes.
+  # A full Mailbox object can be obtained by fetching a single mailbox directly.
+  #
+  #  Name       Type      Example               Notes
+  # *id         Int       1234                  Unique identifier
+  # *name       String    Feedback              Name of the Mailbox
+  #  slug       String    47204a026903ce6d      Key used to represent this 
+  #                                             Mailbox
+  #  email      String    feedback@support.com  Email address
+  #  createdAt  DateTime  2012-07-23T12:34:12Z  UTC time when this mailbox was 
+  #                                             created.
+  #  modifiedAt DateTime  2012-07-24T20:18:33Z  UTC time when this mailbox was 
+  #                                             modified.
+
   class Mailbox
-    attr_accessor :id, :name, :slug, :email, :createdAt, :modifiedAt
+    attr_reader :id, :name, :slug, :email, :createdAt, :modifiedAt
+
+    # Creates a new Mailbox object from a Hash of attributes
     def initialize(object)
+      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
+      @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
+
       @id = object["id"]
       @name = object["name"]
+      
       @slug = object["slug"]
       @email = object["email"]
-      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
-      @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
     end
+  end
 
-    class Folder
-      attr_accessor :id, :name, :type, :userId, :totalCount, :activeCount, :modifiedAt
-  
-      FOLDER_TYPE_UNASSIGNED = "unassigned"
-      FOLDER_TYPE_MY_TICKETS = "mytickets"
-      FOLDER_TYPE_DRAFTS = "drafts"
-      FOLDER_TYPE_ASSIGNED = "assigned"
-      FOLDER_TYPE_CLOSED = "closed"
-      FOLDER_TYPE_SPAM = "spam"
 
-      def initialize(object)
-        @id = object["id"]
-        @name = object["name"]
-        @type = object["type"]
-        @userId = object["userId"] # 0, unless type == FOLDER_TYPE_MY_TICKETS
-        @totalCount = object["totalCount"]
-        @activeCount = object["activeCount"]
-        @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
-      end
-    end
-  end
+  # Conversation
+  # http://developer.helpscout.net/objects/conversation/
+  #
+  #  Name         Type        Example               Notes
+  #  id           Int         2391938111            Unique identifier
+  #  folderId     Int         1234                  ID of the Folder to which 
+  #                                                 this conversation resides.
+  #  isDraft      Boolean     false                 Is this a draft?
+  #  number       Int         349                   The conversation number 
+  #                                                 displayed in the UI.
+  #  owner        User                              User of the Help Scout user 
+  #                                                 that is currently assigned 
+  #                                                 to this conversation
+  #  mailbox      Mailbox                           Mailbox to which this 
+  #                                                 conversation belongs.
+  #  customer     Customer                          Customer to which this 
+  #                                                 conversation belongs.
+  #  threadCount  Int         4                     This count represents the 
+  #                                                 number of published threads 
+  #                                                 found on the conversation 
+  #                                                 (it does not include line 
+  #                                                 items, drafts or threads 
+  #                                                 held for review by Traffic 
+  #                                                 Cop).
+  #  status       String      active                Status of the conversation.
+  #  subject      String      I need help!   
+  #  preview      String      Hello, I...   
+  #  createdBy    Customer                          Either the Customer or User 
+  #               - or -                            that created this 
+  #               User                              conversation. 
+  #                                                 Inspect the Source object 
+  #                                                 for clarification.
+  #  createdAt    DateTime    2012-07-23T12:34:12Z  UTC time when this 
+  #                                                 conversation was created.
+  #  modifiedAt   DateTime    2012-07-24T20:18:33Z  UTC time when this.
+  #                                                 conversation was modified.
+  #  closedAt     DateTime                          UTC time when this 
+  #                                                 conversation was closed.
+  #                                                 Null if not closed.
+  #  closedBy     User                              User of the Help Scout user 
+  #                                                 that closed this 
+  #                                                 conversation.
+  #  source       Source                            Specifies the method in 
+  #                                                 which this conversation was 
+  #                                                 created.
+  #  cc           Array                             Collection of strings 
+  #                                                 representing emails.
+  #  bcc          Array                             Collection of strings
+  #                                                 representing emails.
+  #  tags         Array                             Collection of strings
+  #  threads      Array                             Collection of Thread 
+  #                                                 objects. Only available when
+  #                                                 retrieving a single 
+  #                                                 Conversation
+  #
+  # Possible values for status include:
+  # * STATUS_ACTIVE
+  # * STATUS_PENDING
+  # * STATUS_CLOSED
+  # * STATUS_SPAM
 
   class Conversation
-    attr_accessor :id, :folderId, :isDraft, :number, :owner, :mailbox, :customer, :threadCount, :status, :subject, :preview, :createdBy, :createdAt, :modifiedAt, :closedAt, :closedBy, :source, :cc, :bcc, :tags, :threads
+    attr_reader :id, :folderId, :isDraft, :number, :owner, :mailbox, :customer, :threadCount, :status, :subject, :preview, :createdBy, :createdAt, :modifiedAt, :closedAt, :closedBy, :source, :cc, :bcc, :tags, :threads, :url
 
-    CONVERSATION_STATUS_ACTIVE = "active"
-    CONVERSATION_STATUS_PENDING = "pending"
-    CONVERSATION_STATUS_CLOSED = "closed"
-    CONVERSATION_STATUS_SPAM = "spam"
+    STATUS_ACTIVE = "active"
+    STATUS_PENDING = "pending"
+    STATUS_CLOSED = "closed"
+    STATUS_SPAM = "spam"
 
+    # Creates a new Conversation object from a Hash of attributes
     def initialize(object)
+      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
+      @modifiedAt = DateTime.iso8601(object["userModifiedAt"]) if object["userModifiedAt"]
+      @closedAt = DateTime.iso8601(object["closedAt"]) if object["closedAt"]
       @id = object["id"]
       @folderId = object["folderId"]
       @isDraft = object["isDraft"]
@@ -55,9 +176,6 @@ module HelpScout
       @status = object["status"]
       @subject = object["subject"]
       @preview = object["preview"]
-      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
-      @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
-      @closedAt = DateTime.iso8601(object["closedAt"]) if object["closedAt"]
       @closedBy = User.new(object["closedBy"]) if object["closedBy"]
 
       @source = nil
@@ -65,9 +183,9 @@ module HelpScout
         @source = Source.new(object["source"])
 
         if object["createdBy"]
-          if @source.type == Source::SOURCE_VIA_CUSTOMER
+          if @source.type == Source::VIA_CUSTOMER
             @createdBy = Customer.new(object["createdBy"])
-          elsif @source.type == Source::SOURCE_VIA_USER
+          elsif @source.type == Source::VIA_USER
             @createdBy = User.new(object["createdBy"])
           end
         end
@@ -83,91 +201,135 @@ module HelpScout
           @threads << Thread.new(thread)
         end
       end
-    end
 
-    def to_s
-      "Last Modified: #{@modifiedAt}\nAssigned to: #{@owner}\nSubject: #{@subject}\n#{@preview}"
+      @url = "https://secure.helpscout.net/conversation/#{@id}/#{@number}/"
     end
 
-    class Attachment
-      attr_accessor :id, :mimeType, :filename, :size, :width, :height, :url
-
-      def initialize(object)
-        @id = object["id"]
-        @mimeType = object["mimeType"]
-        @filename = object["filename"]
-        @size = object["size"]
-        @width = object["width"]
-        @height = object["height"]
-        @url = object["url"]
-      end
-    end
-
-    class AttachmentData
-      attr_accessor :id, :data
-
-      def initialize(object)
-        @id = object["id"]
-        @data = object["data"]
-      end
+    # Returns a String suitable for display
+    def to_s
+      "Last Modified: #{@modifiedAt}\nStatus: #{@status}\nAssigned to: #{@owner}\nSubject: #{@subject}\n#{@preview}"
     end
 
-    class Source
-      attr_accessor :type, :via
-
-      SOURCE_TYPE_EMAIL = "email"
-      SOURCE_TYPE_WEB = "web"
-      SOURCE_TYPE_NOTIFICATION = "notification"
-      SOURCE_TYPE_EMAIL_FWD = "emailfwd"
 
-      SOURCE_VIA_USER = "user"
-      SOURCE_VIA_CUSTOMER = "customer"
-
-      def initialize(object)
-        @type = object["type"]
-        @via = object["via"]
-      end
-    end
+    # Conversation::Thread
+    # http://developer.helpscout.net/objects/conversation/thread/
+    #
+    #  Name         Type      Example               Notes
+    #  id           Int       88171881              Unique identifier
+    #  assignedTo   User                            User of the Help Scout user 
+    #                                               to which this conversation 
+    #                                               has been assigned.
+    #  status       String    active                Status of the thread. Thread
+    #                                               status is only updated when 
+    #                                               there is a status change. 
+    #                                               Otherwise, the status will 
+    #                                               be set to STATUS_NO_CHANGE.
+    #  createdAt    DateTime  2012-07-23T12:34:12Z  UTC time when this thread 
+    #                                               was created.
+    #  createdBy    Customer                        Either the Customer or User 
+    #               - or -                          that created this 
+    #               User                            conversation. Inspect the 
+    #                                               Source object for 
+    #                                               clarification.
+    #  source       Source     
+    #  fromMailbox  Mailbox                         If the conversation was 
+    #                                               moved, fromMailbox 
+    #                                               represents the Mailbox from 
+    #                                               which it was moved.
+    #  type         String    message               The type of thread. 
+    #  state        String    published             The state of the thread. 
+    #  customer     Customer                        If type is message, this is 
+    #                                               the Customer of the customer
+    #                                               in which the message was 
+    #                                               sent. If type is customer, 
+    #                                               this is the Customer of the 
+    #                                               customer that initiated the 
+    #                                               thread.
+    #  body         String    Thank you.   
+    #  to           Array                           Collection of Strings 
+    #                                               representing emails.
+    #  cc           Array                           Collection of Strings
+    #                                               representing emails.
+    #  bcc          Array                           Collection of Strings
+    #                                               representing emails.
+    #  attachments  Array                           Collection of Attachment 
+    #                                               objects, if they exist.
+    #
+    # Possible values for state include:
+    # * STATE_PUBLISHED
+    # * STATE_DRAFT
+    # * STATE_UNDER_REVIEW
+    #
+    # A state of STATE_UNDER_REVIEW means the thread has been stopped by Traffic
+    # Cop and is waiting to be confirmed (or discarded) by the person that 
+    # created the thread.
+    #
+    # Traffic Cop is the Help Scout feature that stops a thread from going out 
+    # if multiple Users act on the same Help Scout simultaneously.
+    #
+    # Possible values for status include:
+    # * STATUS_ACTIVE
+    # * STATUS_NO_CHANGE
+    # * STATUS_PENDING
+    # * STATUS_CLOSED
+    # * STATUS_SPAM
+    #
+    # Possible values for type include:
+    # * TYPE_NOTE
+    # * TYPE_MESSAGE
+    # * TYPE_CUSTOMER
+    # * TYPE_LINEITEM
+    # * TYPE_FWD_PARENT
+    # * TYPE_FWD_CHILD
+    #
+    # TYPE_LINEITEM represents a change of state on the conversation. This could
+    # include, but not limited to, the conversation was assigned, the status 
+    # changed, the conversation was moved from one mailbox to another, etc. A 
+    # line item won't have a body, to/cc/bcc lists, or attachments.
+    #
+    # When a conversation is forwarded, a new conversation is created to 
+    # represent the forwarded conversation.
+    # * TYPE_FWD_PARENT is the type set on the thread of the original 
+    #   conversation that initiated the forward event.
+    # * TYPE_FWD_CHILD is the type set on the first thread of the new forwarded 
+    #   conversation.
 
     class Thread
-      attr_accessor :id, :assignedTo, :status, :createdAt, :createdBy, :source, :fromMailbox, :type, :state, :customer, :body, :to, :cc, :bcc, :attachments
-
-      THREAD_STATE_PUBLISHED = "published"
-      THREAD_STATE_DRAFT = "draft"
-      THREAD_STATE_UNDER_REVIEW = "underreview"
-
-      THREAD_STATUS_ACTIVE = "active"
-      THREAD_STATUS_NO_CHANGE = "nochange"
-      THREAD_STATUS_PENDING = "pending"
-      THREAD_STATUS_CLOSED = "closed"
-      THREAD_STATUS_SPAM = "spam"
-
-      THREAD_TYPE_NOTE = "note"
-      THREAD_TYPE_MESSAGE = "message"
-      THREAD_TYPE_CUSTOMER = "customer"
-
-      # A lineitem represents a change of state on the conversation. This could include, but not limited to, the conversation was assigned, the status changed, the conversation was moved from one mailbox to another, etc. A line item won't have a body, to/cc/bcc lists, or attachments.
-      THREAD_TYPE_LINEITEM = "lineitem" 
-
-      # When a conversation is forwarded, a new conversation is created to represent the forwarded conversation.
-      THREAD_TYPE_FWD_PARENT = "forwardparent" # forwardparent is the type set on the thread of the original conversation that initiated the forward event.
-      THREAD_TYPE_FWD_CHILD = "forwardchild" # forwardchild is the type set on the first thread of the new forwarded conversation.
-
-      
+      attr_reader :id, :assignedTo, :status, :createdAt, :createdBy, :source, :fromMailbox, :type, :state, :customer, :body, :to, :cc, :bcc, :attachments
+
+      STATE_PUBLISHED = "published"
+      STATE_DRAFT = "draft"
+      STATE_UNDER_REVIEW = "underreview"
+
+      STATUS_ACTIVE = "active"
+      STATUS_NO_CHANGE = "nochange"
+      STATUS_PENDING = "pending"
+      STATUS_CLOSED = "closed"
+      STATUS_SPAM = "spam"
+
+      TYPE_NOTE = "note"
+      TYPE_MESSAGE = "message"
+      TYPE_CUSTOMER = "customer"
+      TYPE_LINEITEM = "lineitem" 
+      TYPE_FWD_PARENT = "forwardparent"
+      TYPE_FWD_CHILD = "forwardchild"
+    
+      # Creates a new Conversation::Thread object from a Hash of attributes
       def initialize(object)
+        @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
+
         @id = object["id"]
         @assignedTo = User.new(object["assignedTo"]) if object["assignedTo"]
         @status = object["status"]
-        @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
 
         @source = nil
         if object["source"]
           @source = Source.new(object["source"])
 
           if object["createdBy"]
-            if @source.type == Source::SOURCE_VIA_CUSTOMER
+            if @source.type == Source::VIA_CUSTOMER
               @createdBy = Customer.new(object["createdBy"])
-            elsif @source.type == Source::SOURCE_VIA_USER
+            elsif @source.type == Source::VIA_USER
               @createdBy = User.new(object["createdBy"])
             end
           end
@@ -190,21 +352,102 @@ module HelpScout
         end
       end
 
+      # Returns a String suitable for display
       def to_s
         "#{@customer}: #{@body}"
       end
     end
 
+
+    # Conversation::Attachment
+    # http://developer.helpscout.net/objects/conversation/attachment/
+    # 
+    #  Name      Type    Example               Notes
+    #  id        Int     12391                 Unique identifier
+    #  mimeType  String  image/jpeg   
+    #  filename  String  logo.jpg   
+    #  size      Int     22                    Size of the attachment in bytes.
+    #  width     Int     160  
+    #  height    Int     160  
+    #  url       String  https://.../logo.jpg  Public-facing url where 
+    #                    attachment can be downloaded
+
+    class Attachment
+      attr_reader :id, :mimeType, :filename, :size, :width, :height, :url
+
+      # Creates a new Conversation::Attachment object from a Hash of attributes
+      def initialize(object)
+        @id = object["id"]
+        @mimeType = object["mimeType"]
+        @filename = object["filename"]
+        @size = object["size"]
+        @width = object["width"]
+        @height = object["height"]
+        @url = object["url"]
+      end
+    end
+
+
+    # Conversation::AttachmentData
+    # http://developer.helpscout.net/objects/conversation/attachment-data/
+    #
+    #  Name  Type    Example  Notes
+    #  id    Int     887171   Unique identifier
+    #  data  String           base64 encoded data
+
+    class AttachmentData
+      attr_reader :id, :data
+
+      # Creates a new Conversation::AttachmentData object from a Hash of 
+      # attributes
+      def initialize(object)
+        @id = object["id"]
+        @data = object["data"]
+      end
+    end
   end
 
+
+  # User
+  # http://developer.helpscout.net/objects/user/
+  # http://developer.helpscout.net/objects/user/user-ref/
+  #
+  # UserRefs are a subset of a full User object, and only include the attributes
+  # marked with a *.
+  # 
+  # UserRefs are returned by endpoints that include multiple users.
+  # A full User object can be obtained by fetching a single user directly.
+  #
+  #  Name        Type      Example                 Notes
+  # *id          Int       1234                    Unique identifier
+  # *firstName   String    Jack   
+  # *lastName    String    Sprout   
+  # *email       String    jack.sprout@gmail.com  
+  #  role        String    owner                   Role of this user.
+  #  timezone    String    America/New_York   
+  #  photoUrl    String    http://.../avatar.jpg   The user's photo, if one 
+  #                                                exists.
+  #  createdAt   DateTime  2011-04-01T03:18:33Z    UTC time when this user was 
+  #                                                created.
+  #  modifiedAt  DateTime  2012-07-24T20:18:33Z    UTC time when this user was 
+  #                                                modified.
+  #
+  # Possible values for role include:
+  # * ROLE_OWNER
+  # * ROLE_ADMIN
+  # * ROLE_USER
+
   class User
-    attr_accessor :id, :firstName, :lastName, :email, :role, :timezone, :photoUrl, :createdAt, :createdBy
+    attr_reader :id, :firstName, :lastName, :email, :role, :timezone, :photoUrl, :createdAt, :createdBy
 
-    USER_ROLE_OWNER = "owner"
-    USER_ROLE_ADMIN = "admin"
-    USER_ROLE_USER = "user"
+    ROLE_OWNER = "owner"
+    ROLE_ADMIN = "admin"
+    ROLE_USER = "user"
 
+    # Creates a new User object from a Hash of attributes
     def initialize(object)
+      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
+
       @id = object["id"]
       @firstName = object["firstName"]
       @lastName = object["lastName"]
@@ -212,31 +455,80 @@ module HelpScout
       @role = object["role"]
       @timezone = object["timezone"]
       @photoUrl = object["photoUrl"]
-      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
       @createdBy = object["createdBy"]
     end
 
+    # Returns a String suitable for display
     def to_s
       "#{@firstName} #{@lastName}"
     end
   end
 
+
+  # Customer
+  # http://developer.helpscout.net/objects/customer/
+  # http://developer.helpscout.net/objects/customer/customer-ref/
+  #
+  # CustomerRefs are a subset of a full Customer object, and only include the 
+  # attributes marked with a *.
+  #
+  # CustomerRefs are returned by endpoints that include multiple customers.
+  #
+  # A full Customer object can be obtained by fetching a single customer 
+  # directly.
+  #
+  #  Name          Type      Example               Notes
+  # *id            Int       29418                 Unique identifier
+  # *firstName     String    Vernon   
+  # *lastName      String    Bear   
+  # *email         String    vbear@mywork.com      If the customer has multiple 
+  #                                                emails, only one is returned.
+  #  photoUrl      String    http://../avatar.jpg   
+  #  photoType     String    twitter               Type of photo.
+  #  gender        String    Male                  Gender of this customer.
+  #  age           String    30-35  
+  #  organization  String    Acme, Inc  
+  #  jobTitle      String    CEO and Co-Founder   
+  #  location      String    Austin
+  #  createdAt     DateTime  2012-07-23T12:34:12Z  UTC time when this customer 
+  #                                                was created.
+  #  modifiedAt    DateTime  2012-07-24T20:18:33Z  UTC time when this customer 
+  #                                                was modified.
+  #
+  # Possible values for photoType include:
+  # * PHOTO_TYPE_UNKNOWN
+  # * PHOTO_TYPE_GRAVATAR
+  # * PHOTO_TYPE_TWITTER
+  # * PHOTO_TYPE_FACEBOOK
+  # * PHOTO_TYPE_GOOGLE_PROFILE
+  # * PHOTO_TYPE_GOOGLE_PLUS
+  # * PHOTO_TYPE_LINKEDIN
+  #
+  # Possible values for gender include: 
+  # * GENDER_MALE
+  # * GENDER_FEMALE
+  # * GENDER_UNKNOWN
+
   class Customer
-    attr_accessor :id, :firstName, :lastName, :photoUrl, :photoType, :gender, :age, :organization, :jobTitle, :location, :createdAt, :modifiedAt, :background, :address, :socialProfiles, :emails, :phones, :chats, :websites
+    attr_reader :id, :firstName, :lastName, :photoUrl, :photoType, :gender, :age, :organization, :jobTitle, :location, :createdAt, :modifiedAt, :background, :address, :socialProfiles, :emails, :phones, :chats, :websites
 
-    CUSTOMER_PHOTO_TYPE_UNKNOWN = "unknown"
-    CUSTOMER_PHOTO_TYPE_GRAVATAR = "gravatar"
-    CUSTOMER_PHOTO_TYPE_TWITTER = "twitter"
-    CUSTOMER_PHOTO_TYPE_FACEBOOK = "facebook"
-    CUSTOMER_PHOTO_TYPE_GOOGLE_PROFILE = "googleprofile"
-    CUSTOMER_PHOTO_TYPE_GOOGLE_PLUS = "googleplus"
-    CUSTOMER_PHOTO_TYPE_LINKEDIN = "linkedin"
+    PHOTO_TYPE_UNKNOWN = "unknown"
+    PHOTO_TYPE_GRAVATAR = "gravatar"
+    PHOTO_TYPE_TWITTER = "twitter"
+    PHOTO_TYPE_FACEBOOK = "facebook"
+    PHOTO_TYPE_GOOGLE_PROFILE = "googleprofile"
+    PHOTO_TYPE_GOOGLE_PLUS = "googleplus"
+    PHOTO_TYPE_LINKEDIN = "linkedin"
 
-    CUSTOMER_GENDER_MALE = "male"
-    CUSTOMER_GENDER_FEMALE = "female"
-    CUSTOMER_GENDER_UNKNOWN = "unknown"
+    GENDER_MALE = "male"
+    GENDER_FEMALE = "female"
+    GENDER_UNKNOWN = "unknown"
 
+    # Creates a new Customer object from a Hash of attributes
     def initialize(object)
+      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
+      @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
+
       @id = object["id"]
       @firstName = object["firstName"]
       @lastName = object["lastName"]
@@ -288,42 +580,83 @@ module HelpScout
           @websites << Website.new(item)
         end
       end
-
-      @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
-      @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
     end
 
+    # Returns a String suitable for display
     def to_s
       "#{@firstName} #{@lastName}"
     end
 
+
+    # Customer::Address
+    # http://developer.helpscout.net/objects/customer/address/
+    #
+    #  Name        Type            Example               Notes
+    #  id          Int             1234                  Unique identifier
+    #  lines       Array                                 Collection of strings 
+    #                                                    representing the 
+    #                                                    customer's street 
+    #                                                    address.
+    #  city        String          Dallas   
+    #  state       String          TX   
+    #  postalCode  String          74206  
+    #  country     String          US   
+    #  createdAt   DateTime        2012-07-23T12:34:12Z  UTC time when this 
+    #                                                    address was created.
+    #  modifiedAt  DateTime        2012-07-24T20:18:33Z  UTC time when this 
+    #                                                    address was modified.
+
     class Address
-      attr_accessor :id, :lines, :city, :state, :postalCode, :country, :createdAt, :modifiedAt
+      attr_reader :id, :lines, :city, :state, :postalCode, :country, :createdAt, :modifiedAt
+      
+      # Creates a new Address object from a Hash of attributes
       def initialize(object)
+        @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
+        @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
+  
         @id = object["id"]
         @lines = object["lines"]
         @city = object["city"]
         @state = object["state"]
         @postalCode = object["postalCode"]
         @country = object["country"]
-        @createdAt = DateTime.iso8601(object["createdAt"]) if object["createdAt"]
-        @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
       end
     end
 
-    class Chat
-      attr_accessor :id, :value, :type
-
-      CHAT_TYPE_AIM = "aim"
-      CHAT_TYPE_GTALK = "gtalk"
-      CHAT_TYPE_ICQ = "icq"
-      CHAT_TYPE_XMPP = "xmpp"
-      CHAT_TYPE_MSN = "msn"
-      CHAT_TYPE_SKYPE = "skype"
-      CHAT_TYPE_YAHOO = "yahoo"
-      CHAT_TYPE_QQ = "qq"
-      CHAT_TYPE_OTHER = "other"
 
+    # Customer::Chat
+    # http://developer.helpscout.net/objects/customer/chat/
+    #
+    #  Name   Type    Example  Notes
+    #  id     Int     77183    Unique identifier
+    #  value  String  jsprout  
+    #  type   String  aim      Chat type
+    #
+    # Possible values for type include:
+    # * TYPE_AIM
+    # * TYPE_GTALK
+    # * TYPE_ICQ
+    # * TYPE_XMPP
+    # * TYPE_MSN
+    # * TYPE_SKYPE
+    # * TYPE_YAHOO
+    # * TYPE_QQ
+    # * TYPE_OTHER
+
+    class Chat
+      attr_reader :id, :value, :type
+
+      TYPE_AIM = "aim"
+      TYPE_GTALK = "gtalk"
+      TYPE_ICQ = "icq"
+      TYPE_XMPP = "xmpp"
+      TYPE_MSN = "msn"
+      TYPE_SKYPE = "skype"
+      TYPE_YAHOO = "yahoo"
+      TYPE_QQ = "qq"
+      TYPE_OTHER = "other"
+
+      # Creates a new Customer::Chat object from a Hash of attributes
       def initialize(object)
         @id = object["id"]
         @value = object["value"]
@@ -331,13 +664,29 @@ module HelpScout
       end
     end
 
+
+    # Customer::Email
+    # http://developer.helpscout.net/objects/customer/email/
+    #
+    #  Name      Type    Example           Notes
+    #  id        Int     98131             Unique identifier
+    #  value     String  vbear@mywork.com   
+    #  location  String  work              Location for this email address. 
+    #                                      Defaults to LOCATION_WORK
+    #
+    # Possible values for location include:
+    # * LOCATION_WORK (Default)
+    # * LOCATION_HOME
+    # * LOCATION_OTHER
+
     class Email
-      attr_accessor :id, :value, :location
+      attr_reader :id, :value, :location
 
-      EMAIL_LOCATION_WORK = "work"
-      EMAIL_LOCATION_HOME = "home"
-      EMAIL_LOCATION_OTHER = "other"
+      LOCATION_WORK = "work"
+      LOCATION_HOME = "home"
+      LOCATION_OTHER = "other"
 
+      # Creates a new Customer::Email object from a Hash of attributes
       def initialize(object)
         @id = object["id"]
         @value = object["value"]
@@ -345,16 +694,34 @@ module HelpScout
       end
     end
 
+
+    # Customer::Phone
+    # http://developer.helpscout.net/objects/customer/phone/
+    #
+    #  Name      Type    Example       Notes
+    #  id        Int     22381         Unique identifier
+    #  value     String  222-333-4444   
+    #  location  String  home          Location for this phone
+    #
+    # Possible values for location include:
+    # * LOCATION_HOME
+    # * LOCATION_WORK
+    # * LOCATION_MOBILE
+    # * LOCATION_FAX
+    # * LOCATION_PAGER
+    # * LOCATION_OTHER
+
     class Phone
-      attr_accessor :id, :value, :location
+      attr_reader :id, :value, :location
 
-      PHONE_LOCATION_HOME = "home"
-      PHONE_LOCATION_WORK = "work"
-      PHONE_LOCATION_MOBILE = "mobile"
-      PHONE_LOCATION_FAX = "fax"
-      PHONE_LOCATION_PAGER = "pager"
-      PHONE_LOCATION_OTHER = "other"
+      LOCATION_HOME = "home"
+      LOCATION_WORK = "work"
+      LOCATION_MOBILE = "mobile"
+      LOCATION_FAX = "fax"
+      LOCATION_PAGER = "pager"
+      LOCATION_OTHER = "other"
 
+      # Creates a new Customer::Phone object from a Hash of attributes
       def initialize(object)
         @id = object["id"]
         @value = object["value"]
@@ -362,36 +729,159 @@ module HelpScout
       end
     end
 
-    class SocialProfile
-      attr_accessor :id, :value, :type
-
-      SOCIAL_PROFILE_TYPE_TWITTER = "twitter"
-      SOCIAL_PROFILE_TYPE_FACEBOOK = "facebook"
-      SOCIAL_PROFILE_TYPE_LINKEDIN = "linkedin"
-      SOCIAL_PROFILE_TYPE_ABOUTME = "aboutme"
-      SOCIAL_PROFILE_TYPE_GOOGLE = "google"
-      SOCIAL_PROFILE_TYPE_GOOGLE_PLUS = "googleplus"
-      SOCIAL_PROFILE_TYPE_TUNGLEME = "tungleme"
-      SOCIAL_PROFILE_TYPE_QUORA = "quora"
-      SOCIAL_PROFILE_TYPE_FOURSQUARE = "foursquare"
-      SOCIAL_PROFILE_TYPE_YOUTUBE = "youtube"
-      SOCIAL_PROFILE_TYPE_FLICKR = "flickr"
-      SOCIAL_PROFILE_TYPE_OTHER = "other"
 
+    # Customer::SocialProfile
+    # http://developer.helpscout.net/objects/customer/social-profile/
+    #
+    #  Name  Type    Example                        Notes
+    #  id    Int     9184                           Unique identifier
+    #  value String  https://twitter.com/helpscout  
+    #  type  String  twitter                        Type of social profile.
+    #
+    # Possible values for type include:
+    # * TYPE_TWITTER
+    # * TYPE_FACEBOOK
+    # * TYPE_LINKEDIN
+    # * TYPE_ABOUTME
+    # * TYPE_GOOGLE
+    # * TYPE_GOOGLE_PLUS
+    # * TYPE_TUNGLEME
+    # * TYPE_QUORA
+    # * TYPE_FOURSQUARE
+    # * TYPE_YOUTUBE
+    # * TYPE_FLICKR
+    # * TYPE_OTHER
+
+    class SocialProfile
+      attr_reader :id, :value, :type
+
+      TYPE_TWITTER = "twitter"
+      TYPE_FACEBOOK = "facebook"
+      TYPE_LINKEDIN = "linkedin"
+      TYPE_ABOUTME = "aboutme"
+      TYPE_GOOGLE = "google"
+      TYPE_GOOGLE_PLUS = "googleplus"
+      TYPE_TUNGLEME = "tungleme"
+      TYPE_QUORA = "quora"
+      TYPE_FOURSQUARE = "foursquare"
+      TYPE_YOUTUBE = "youtube"
+      TYPE_FLICKR = "flickr"
+      TYPE_OTHER = "other"
+
+      # Creates a new Customer::SocialProfile object from a Hash of attributes
       def initialize(object)
         @id = object["id"]
         @value = object["value"]
-        @type = object["type"] # twitter, facebook, linkedin, aboutme, google, googleplus, tungleme, quora, foursquare, youtube, flickr, other
+        @type = object["type"]
       end
     end
 
+
+    # Customer::Website
+    # http://developer.helpscout.net/objects/customer/website/
+    #
+    #  Name   Type    Example                   Notes
+    #  id     Int     5584                      Unique identifier
+    #  value  String  http://www.somewhere.com   
+
     class Website
-      attr_accessor :id, :value
+      attr_reader :id, :value
+
+      # Creates a new Customer::Website object from a Hash of attributes
       def initialize(object)
         @id = object["id"]
         @value = object["value"]
       end
     end
   end
-end
 
+
+  # Source
+  # http://developer.helpscout.net/objects/source/
+  #
+  #  Name  Type    Example   Notes
+  #  type  String  email     The method from which this conversation (or thread) 
+  #                          was created.
+  #  via   String  customer
+  #
+  # Possible values for type include:
+  # * TYPE_EMAIL
+  # * TYPE_WEB
+  # * TYPE_NOTIFICATION
+  # * TYPE_FWD
+  # 
+  # Possible values for via include:
+  # * VIA_USER
+  # * VIA_CUSTOMER
+
+  class Source
+    attr_reader :type, :via
+
+    TYPE_EMAIL = "email"
+    TYPE_WEB = "web"
+    TYPE_NOTIFICATION = "notification"
+    TYPE_FWD = "emailfwd"
+
+    VIA_USER = "user"
+    VIA_CUSTOMER = "customer"
+
+    # Creates a new Source object from a Hash of attributes
+    def initialize(object)
+      @type = object["type"]
+      @via = object["via"]
+    end
+  end
+
+
+  # Folder
+  # http://developer.helpscout.net/objects/folder/
+  #
+  #  Name         Type      Example               Notes
+  #  id           Int       1234                  Unique identifier
+  #  name         String    My Tickets            Folder name
+  #  type         String    mytickets             The type this folder 
+  #                                               represents.
+  #  userId       Int       4532                  If the folder type is 
+  #                                               TYPE_MY_TICKETS, userId 
+  #                                               represents the Help Scout user
+  #                                               to which this folder belongs. 
+  #                                               Otherwise userId is 0.
+  #  totalCount   Int       2                     Total number of conversations 
+  #                                               in this folder
+  #  activeCount  Int       1                     Total number of conversations 
+  #                                               in this folder that are in an 
+  #                                               active state (vs pending).
+  #  modifiedAt   DateTime  2012-07-24T20:18:33Z  UTC time when this folder was 
+  #                                               modified.
+  #
+  # Possible values for type include:
+  # * TYPE_UNASSIGNED
+  # * TYPE_MY_TICKETS
+  # * TYPE_DRAFTS
+  # * TYPE_ASSIGNED
+  # * TYPE_CLOSED
+  # * TYPE_SPAM
+
+  class Folder
+    attr_reader :id, :name, :type, :userId, :totalCount, :activeCount, :modifiedAt
+
+    TYPE_UNASSIGNED = "open"
+    TYPE_MY_TICKETS = "mytickets"
+    TYPE_DRAFTS = "drafts"
+    TYPE_ASSIGNED = "assigned"
+    TYPE_CLOSED = "closed"
+    TYPE_SPAM = "spam"
+
+    # Creates a new Folder object from a Hash of attributes
+    def initialize(object)
+      @modifiedAt = DateTime.iso8601(object["modifiedAt"]) if object["modifiedAt"]
+
+      @id = object["id"]
+      @name = object["name"]
+      @type = object["type"]
+      @userId = object["userId"]
+      @totalCount = object["totalCount"]
+      @activeCount = object["activeCount"]
+    end
+  end
+end