Class: Craigslist::API::Posting

Inherits:
Object
  • Object
show all
Defined in:
lib/craigslist/api/posting.rb

Overview

A posting to be submitted through the bulk RSS interface.

Validated on construction, so a malformed posting fails locally instead of consuming a round trip. Everything is frozen afterwards.

The interface exposes two generations of optional fields. This models the newer flat attribute groups (+cl:housing_basics+, cl:job_basics, cl:auto_basics, cl:forsale, cl:generic, cl:housing_terms, cl:housing_pets), whose keys are already snake_case and pass through unchanged. The legacy camelCase groups (+cl:housingInfo+, cl:jobInfo) are not modelled; cl:brokerInfo is, because housing postings still need it and it has no modern equivalent.

Examples:

A minimal for-sale posting

Craigslist::API::Posting.new(
  key: "listing-1",
  title: "1998 Toyota Hilux",
  description: "Runs great.",
  category: "ctd",
  area: "sfo",
  price: 4500,
  reply_email: "sales@example.com",
  location: {postal: "94110"}
)

Constant Summary collapse

PRIVACY =

How the reply address is displayed on the posting.

{
  none: "A",        # show no email address
  anonymous: "C",   # use an anonymous craigslist relay address
  public: "P"       # show the address as given
}.freeze
LOCATION_ATTRIBUTES =

Ruby-side names for cl:mapLocation attributes, which are camelCase on the wire.

{
  postal: "postal",
  city: "city",
  state: "state",
  cross_street1: "crossStreet1",
  cross_street2: "crossStreet2",
  latitude: "latitude",
  longitude: "longitude"
}.freeze
BROKER_ATTRIBUTES =

Ruby-side names for cl:brokerInfo attributes.

{
  company_name: "companyName",
  fee_disclosure: "feeDisclosure"
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key:, title:, description:, category:, area:, subarea: nil, neighborhood: nil, price: nil, po_number: nil, reply_email: nil, reply_privacy: :anonymous, other_contact_info: nil, location: {}, images: [], broker: {}, generic: {}, housing_basics: {}, housing_pets: {}, housing_terms: {}, job_basics: {}, auto_basics: {}, forsale: {}) ⇒ Posting

Returns a new instance of Posting.

Parameters:

  • key (String) —

    identifier unique within the submission document. Echoed back on the matching result, and how you correlate a response to what you sent.

  • title (String)
  • description (String) —

    the posting body

  • category (String) —

    category abbreviation, e.g. "ctd"

  • area (String) —

    area abbreviation, e.g. "sfo"

  • subarea (String, nil) (defaults to: nil) —

    required in areas that have subareas

  • neighborhood (String, nil) (defaults to: nil)
  • price (Integer, nil) (defaults to: nil)
  • po_number (String, nil) (defaults to: nil) —

    your own tracking reference

  • reply_email (String, nil) (defaults to: nil)
  • reply_privacy (Symbol, String) (defaults to: :anonymous) —

    one of :none, :anonymous, :public, or a raw "A"/"C"/"P"

  • other_contact_info (String, nil) (defaults to: nil) —

    free-text alternate contact

  • location (Hash) (defaults to: {}) —

    see LOCATION_ATTRIBUTES. Either :postal or both :latitude and :longitude is required.

  • images (Array<Image, IO, String, Pathname>) (defaults to: []) —

    see Image.wrap

  • broker (Hash) (defaults to: {}) —

    see BROKER_ATTRIBUTES

  • generic (Hash) (defaults to: {}) —

    cl:generic attributes

  • housing_basics (Hash) (defaults to: {}) —

    cl:housing_basics attributes

  • housing_pets (Hash) (defaults to: {}) —

    cl:housing_pets attributes

  • housing_terms (Hash) (defaults to: {}) —

    cl:housing_terms attributes

  • job_basics (Hash) (defaults to: {}) —

    cl:job_basics attributes

  • auto_basics (Hash) (defaults to: {}) —

    cl:auto_basics attributes

  • forsale (Hash) (defaults to: {}) —

    cl:forsale attributes

Raises:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/craigslist/api/posting.rb', line 88

def initialize(
  key:,
  title:,
  description:,
  category:,
  area:,
  subarea: nil,
  neighborhood: nil,
  price: nil,
  po_number: nil,
  reply_email: nil,
  reply_privacy: :anonymous,
  other_contact_info: nil,
  location: {},
  images: [],
  broker: {},
  generic: {},
  housing_basics: {},
  housing_pets: {},
  housing_terms: {},
  job_basics: {},
  auto_basics: {},
  forsale: {}
)
  @key = key.to_s
  @title = title.to_s
  @description = description.to_s
  @category = category.to_s
  @area = area.to_s
  @subarea = subarea&.to_s
  @neighborhood = neighborhood&.to_s
  @price = price
  @po_number = po_number&.to_s
  @reply_email = reply_email&.to_s
  @reply_privacy = normalize_privacy(reply_privacy)
  @other_contact_info = other_contact_info&.to_s
  @location = compact(location).freeze
  @images = build_images(images).freeze
  @broker = compact(broker).freeze
  @generic = compact(generic).freeze
  @housing_basics = compact(housing_basics).freeze
  @housing_pets = compact(housing_pets).freeze
  @housing_terms = compact(housing_terms).freeze
  @job_basics = compact(job_basics).freeze
  @auto_basics = compact(auto_basics).freeze
  @forsale = compact(forsale).freeze

  validate!
  freeze
end

Instance Attribute Details

#area ⇒ Object (readonly)

Returns the value of attribute area.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def area
  @area
end

#auto_basics ⇒ Object (readonly)

Returns the value of attribute auto_basics.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def auto_basics
  @auto_basics
end

#broker ⇒ Object (readonly)

Returns the value of attribute broker.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def broker
  @broker
end

#category ⇒ Object (readonly)

Returns the value of attribute category.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def category
  @category
end

#description ⇒ Object (readonly)

Returns the value of attribute description.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def description
  @description
end

#forsale ⇒ Object (readonly)

Returns the value of attribute forsale.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def forsale
  @forsale
end

#generic ⇒ Object (readonly)

Returns the value of attribute generic.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def generic
  @generic
end

#housing_basics ⇒ Object (readonly)

Returns the value of attribute housing_basics.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def housing_basics
  @housing_basics
end

#housing_pets ⇒ Object (readonly)

Returns the value of attribute housing_pets.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def housing_pets
  @housing_pets
end

#housing_terms ⇒ Object (readonly)

Returns the value of attribute housing_terms.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def housing_terms
  @housing_terms
end

#images ⇒ Object (readonly)

Returns the value of attribute images.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def images
  @images
end

#job_basics ⇒ Object (readonly)

Returns the value of attribute job_basics.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def job_basics
  @job_basics
end

#key ⇒ Object (readonly)

Returns the value of attribute key.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def key
  @key
end

#location ⇒ Object (readonly)

Returns the value of attribute location.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def location
  @location
end

#neighborhood ⇒ Object (readonly)

Returns the value of attribute neighborhood.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def neighborhood
  @neighborhood
end

#other_contact_info ⇒ Object (readonly)

Returns the value of attribute other_contact_info.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def other_contact_info
  @other_contact_info
end

#po_number ⇒ Object (readonly)

Returns the value of attribute po_number.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def po_number
  @po_number
end

#price ⇒ Object (readonly)

Returns the value of attribute price.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def price
  @price
end

#reply_email ⇒ Object (readonly)

Returns the value of attribute reply_email.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def reply_email
  @reply_email
end

#reply_privacy ⇒ Object (readonly)

Returns the value of attribute reply_privacy.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def reply_privacy
  @reply_privacy
end

#subarea ⇒ Object (readonly)

Returns the value of attribute subarea.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def subarea
  @subarea
end

#title ⇒ Object (readonly)

Returns the value of attribute title.



55
56
57
 
# File 'lib/craigslist/api/posting.rb', line 55

def title
  @title
end

Instance Method Details

#errors ⇒ Array<String>

Returns problems with this posting, empty when valid.

Returns:

  • (Array<String>) —

    problems with this posting, empty when valid



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/craigslist/api/posting.rb', line 140

def errors
  problems = []
  problems << "key is required" if key.empty?
  problems << "title is required" if title.empty?
  problems << "description is required" if description.empty?
  problems << "category is required" if category.empty?
  problems << "area is required" if area.empty?
  problems.concat(location_errors)
  problems.concat(image_errors)
  problems
end

#inspect ⇒ Object 



157
158
159
160
 
# File 'lib/craigslist/api/posting.rb', line 157

def inspect
  "#<#{self.class.name} key=#{key.inspect} category=#{category.inspect} " \
    "area=#{area.inspect} images=#{images.size}>"
end

#valid? ⇒ Boolean

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/craigslist/api/posting.rb', line 153

def valid?
  errors.empty?
end