craigslist-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9a564a5e0b54cd65ef0712f045d2fc7aee5cf9c321e7c5cfa6d00112bb91352
+  data.tar.gz: 7c456966c241b46bff3d55d3175c39b823e149bfd39d4d7522b7673a302190ae
+SHA512:
+  metadata.gz: f39a965ba62a0c0c1b0854b4e67f56d4c61ba03265ec3544d29d9f8b3672cf2b7cfec9fce6a8a5407002d0707e7e22a099a9973d0d66aed1fefdb1ac4285f629
+  data.tar.gz: 797c855211e745fc1aa3830af823707fbaae3f60752bf2dfb00d4b7ac6034d9e401d6d05d4ba6a0d74b41aac2d326d661a0cd8663ff8ec55619882f46517fcf9

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+While the version is below 1.0.0 the public API may change between minor
+versions. The gem wraps an API that cannot be exercised without access granted
+by Craigslist, so real-world use may surface corrections.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-17
+
+Initial release.
+
+### Added
+
+- `Craigslist::API::Client`, a single client covering both halves of the bulk
+  posting platform: the RSS interface used to create postings and the JSON
+  Bulkpost API used to manage them afterwards.
+- Posting creation via `#validate` and `#post`, returning a `ResultSet` of
+  per-posting outcomes rather than raising, since a bulk submission succeeds
+  and fails per item.
+- `Posting` and `Image` models with local validation, covering the newer flat
+  attribute groups (`housing_basics`, `job_basics`, `auto_basics`, `forsale`,
+  `generic`, `housing_terms`, `housing_pets`) and `brokerInfo`.
+- `PostingHandle` for live postings, via `client.posting(id)`: status, body,
+  price, remuneration, delete/undelete, images, and statistics.
+- Resource groups for postings, images, billing, and account.
+- Areas and categories from the public reference service, memoized per client.
+- OAuth2 client credentials flow with automatic token caching and refresh,
+  including a single retry on a 401.
+- Value objects for `Money`, `CreditSummary`, `PostingBlock`, `PostingStats`,
+  `ImageInfo`, `Area`, and `Category`.
+- An error hierarchy rooted at `Craigslist::API::Error`, including `APIError`
+  for the case where an HTTP 200 carries a populated `errors` array.
+- `ZipLocation`, returned by `#area_for_zip`. Carries the subarea, which a
+  flat return value would discard -- and a missing subarea is the most common
+  cause of a `NOT_VALID` posting. `#to_h` splats straight into `Posting.new`.
+- `ResultSet#raw`, the unparsed response body, so an unexplained rejection can
+  be inspected without rebuilding the request by hand.
+
+### Notes
+
+Verified against a live bulk posting account: postings created and removed in
+`pit`/`ctd`, plus management, billing, image and error paths. Two corrections
+came out of that run, both folded in above -- the zip lookup shape, and the
+missing subarea in the smoke-test example.
+
+[Unreleased]: https://github.com/biggeektx/craigslist-api-gem/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/biggeektx/craigslist-api-gem/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Nick Chewning
+
+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 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.md

@@ -0,0 +1,405 @@
+# craigslist-api
+
+[![CI](https://github.com/biggeektx/craigslist-api-gem/actions/workflows/ci.yml/badge.svg)](https://github.com/biggeektx/craigslist-api-gem/actions/workflows/ci.yml)
+
+A Ruby client for Craigslist's bulk posting platform.
+
+Craigslist splits this platform across two services that look nothing alike:
+
+| | Creating postings | Managing them afterwards |
+|---|---|---|
+| Service | `post.craigslist.org/bulk-rss` | `bapi.craigslist.org/bulkpost/v1` |
+| Format | RDF/RSS XML | JSON (writes are form-encoded) |
+| Auth | credentials inside the XML body | OAuth2 bearer token |
+
+One set of credentials covers both, and neither can do the other's job — you
+cannot create a posting over the JSON API, and you cannot edit one over RSS.
+This gem hides that seam behind a single client.
+
+```ruby
+client  = Craigslist::API.new(email: ..., password: ..., account_id: ...)
+results = client.post(postings)          # RSS under the hood
+client.posting(results.posting_ids.first).price = 4200   # JSON under the hood
+```
+
+## Before you start
+
+**Bulk posting access is not self-serve.** Craigslist grants it case by case to
+high-volume posters (hundreds of postings per month), and only for paid US
+categories: jobs (offered), apartment rentals in NYC, and for-sale-by-dealer.
+Contact them at 415-399-5200 x8283.
+
+Without a granted account, every call in this README will return HTTP 403.
+
+## Installation
+
+```ruby
+gem "craigslist-api"
+```
+
+Then `bundle install`. Requires Ruby 3.3 or newer.
+
+## Quick start
+
+```ruby
+require "craigslist/api"
+
+client = Craigslist::API.new(
+  email:      "you@example.com",
+  password:   ENV.fetch("CRAIGSLIST_PASSWORD"),
+  account_id: 1234
+)
+
+posting = Craigslist::API::Posting.new(
+  key:         "listing-1",              # your own identifier for this posting
+  title:       "1998 Toyota Hilux",
+  description: "Runs great. Highway miles.",
+  category:    "ctd",                    # cars & trucks - by dealer
+  area:        "sfo",
+  price:       4500,
+  reply_email: "sales@example.com",
+  location:    {postal: "94110"}
+)
+
+# Dry run first. This sends the identical document that #post would.
+check = client.validate(posting)
+abort check.failed.map(&:explanation).join("\n") if check.any_failures?
+
+results = client.post(posting)
+results.posting_ids  #=> ["7123456780"]
+```
+
+## Creating postings
+
+### Results, not exceptions
+
+A bulk submission succeeds and fails *per posting*, and the HTTP status tells
+you nothing about it — a 200 can carry a document in which every posting
+failed. So `#post` and `#validate` return a `ResultSet` rather than raising.
+A batch with a few rejections is ordinary, not exceptional.
+
+```ruby
+results = client.post(postings)
+
+results.all_successful?   #=> false
+results.successful        #=> [Result, ...]
+results.failed            #=> [Result, ...]
+results.posting_ids       #=> ids of postings that were created
+results.upload_id         #=> craigslist's id for the whole batch
+results["listing-1"]      #=> the Result for the key you submitted
+
+results.failed.each do |result|
+  warn "#{result.key}: #{result.status} — #{result.explanation}"
+end
+```
+
+Transport and authentication failures *do* raise. See [Errors](#errors).
+
+When a rejection is opaque, the unparsed response is always on hand:
+
+```ruby
+puts results.raw    # the RSS document exactly as craigslist sent it
+```
+
+Each `Result` answers the status it came back with:
+
+| Predicate | Status | Meaning |
+|---|---|---|
+| `valid?` | `VALID` | passed validation (validate mode only) |
+| `posted?` | `POSTED` | accepted (post mode only) |
+| `not_valid?` | `NOT_VALID` | rejected; see `explanation` |
+| `insufficient_blocks?` | `INSUFFICIENT_BLOCKS` | out of prepaid blocks for this area/category |
+| `credit_limit_reached?` | `CREDIT_LIMIT_REACHED` | invoiced account hit its limit |
+| `credit_card_error?` | `CREDIT_CARD_ERROR` | card could not be billed |
+| — | `FAILED` | unexpected error at post time |
+
+`success?` covers `VALID` and `POSTED`; `failure?` is everything else.
+
+### Don't skip the warnings
+
+Craigslist returns non-fatal warnings — usually XML it had to paper over —
+**alongside successes**, which makes them easy to miss entirely:
+
+```ruby
+results.warned.each do |result|
+  warn "#{result.key} posted with warnings: #{result.warnings.join(", ")}"
+end
+```
+
+### Posting fields
+
+Only `key`, `title`, `description`, `category`, `area` and a location are
+required. A location means either `:postal`, or both `:latitude` and
+`:longitude`.
+
+> **Subarea is required in any area that has subareas**, and omitting it is the
+> most common reason a posting comes back `NOT_VALID`. `sfo` has six; `pit` has
+> none. Let the ZIP lookup tell you rather than guessing:
+>
+> ```ruby
+> place = client.area_for_zip("94110")   #=> area "sfo", subarea "sfc"
+> Craigslist::API::Posting.new(**place.to_h, key: ..., title: ...)
+> ```
+>
+> Or check directly with `client.reference.area("sfo").subareas?`.
+
+```ruby
+Craigslist::API::Posting.new(
+  key:                "listing-2",
+  title:              "1BR in Chelsea",
+  description:        "Sunny, quiet block.",
+  category:           "apa",
+  area:               "nyc",
+  subarea:            "mnh",             # required where an area has subareas
+  neighborhood:       "Chelsea",
+  price:              4875,
+  po_number:          "PO-094122",       # your own tracking reference
+  reply_email:        "leasing@example.com",
+  reply_privacy:      :anonymous,        # :none | :anonymous | :public
+  other_contact_info: "212.555.1212",
+
+  location: {
+    postal: "10011", city: "New York", state: "NY",
+    cross_street1: "23rd Street", cross_street2: "9th Avenue",
+    latitude: 40.746492, longitude: -74.001326
+  },
+
+  housing_basics: {bedrooms: 1, bathrooms: 1, surface_area: 850,
+                   housing_type: "apartment", laundry: "w/d in unit",
+                   is_furnished: false},
+  housing_terms:  {rent_period: "monthly", broker_fee: true},
+  housing_pets:   {pets_cat: true, pets_dog: false},
+  broker:         {company_name: "Sample & Associates", fee_disclosure: "One month"},
+
+  images: ["photos/living-room.jpg", "photos/kitchen.jpg"]
+)
+```
+
+Booleans are written as the `0`/`1` the interface expects — pass `true`/`false`
+and the gem translates.
+
+The attribute groups map straight onto the interface's newer flat field sets:
+`generic`, `housing_basics`, `housing_pets`, `housing_terms`, `job_basics`,
+`auto_basics`, `forsale`, plus `broker` for `cl:brokerInfo`. Their keys pass
+through unchanged, so anything Craigslist documents for a group works without
+this gem needing to know about it.
+
+Postings are validated on construction and raise `ValidationError` listing
+*every* problem, not just the first:
+
+```ruby
+Craigslist::API::Posting.new(key: "x", title: "", description: "b",
+                             category: "", area: "sfo", location: {})
+# => Craigslist::API::ValidationError:
+#      title is required; category is required;
+#      location requires :postal, or both :latitude and :longitude
+```
+
+### Images
+
+Up to 24 per posting, sent inline as base64. Position is zero-based and
+position 0 is the image featured on search pages.
+
+```ruby
+images: [
+  "photos/front.jpg",                                    # path
+  Pathname("photos/side.jpg"),                           # Pathname
+  File.open("photos/rear.jpg", "rb"),                    # any IO
+  Craigslist::API::Image.from_base64(encoded, position: 5)
+]
+```
+
+Positions are assigned in order when you don't set them. Raw base64 must go
+through `Image.from_base64` — guessing whether a String is a path or a payload
+would be worse than asking.
+
+> Bulk submissions with many images get large fast: 24 images at 200KB each is
+> roughly 6MB of base64 *per posting*. Submit in modest batches.
+
+## Managing live postings
+
+`client.posting(id)` returns a handle. It caches nothing, so it can never go
+stale:
+
+```ruby
+posting = client.posting("7123456780")
+
+posting.status              #=> "active" | "deleted" | "expired" | "pending" | "removed"
+posting.active?             #=> true
+
+posting.body                #=> "The posting body"
+posting.body = "New text"
+posting.price = 4200
+posting.remuneration = "$19.95/hr plus tips"   # jobs and gigs
+
+posting.images              #=> [ImageInfo, ...]
+posting.add_image("new.jpg")
+posting.add_image("hero.jpg", insert_position: 0)
+posting.reorder_images(%w[4:00202_x 4:00101_y])
+posting.remove_image("4:00101_y")
+
+posting.stats.total_views   #=> 1_284
+
+posting.delete
+posting.undelete
+```
+
+Two API quirks worth knowing: postings in `ctd` (cars & trucks by dealer) must
+keep the VIN they were created with, and removing an image only *detaches* it —
+the image itself stays publicly retrievable.
+
+The same operations are available grouped by resource if you prefer:
+`client.postings`, `client.images`, `client.billing`, `client.account`.
+
+## Billing, stats, and reference data
+
+```ruby
+credit = client.credit
+credit.remaining.to_s              #=> "3.00 USD"
+credit.remaining.to_f              #=> 3.0
+
+client.posting_blocks.each do |block|
+  puts "#{block.area} #{block.product_class}: #{block.remaining_posts} left"
+end
+
+client.pricing(area: "sfo", category: "ofc").to_s   #=> "1000.00 USD"
+client.billing.create_invoice                       #=> ["1234321"]
+
+place = client.area_for_zip("02134")
+place.area        #=> "bos"
+place.subarea     #=> "gbs"
+place.to_h        #=> {area: "bos", subarea: "gbs"}
+```
+
+Money keeps Craigslist's minor-unit representation and converts through
+`Rational`, so scaling is exact.
+
+Statistics cover a rolling 30-day window ending midnight UTC yesterday, and
+count requests rather than unique viewers:
+
+```ruby
+stats = client.stats(start: "2026-01-01", stop: "2026-01-31")
+
+stats.each do |posting|
+  puts "#{posting.posting_id}: #{posting.total_views} views, #{posting.total_contact} contacts"
+end
+
+stats.first[:impressions]   #=> [[2026-01-01 00:00:00 UTC, 57], ...]
+```
+
+Metrics: `impressions`, `views`, `contact`, `contact_chat`, `contact_phone`,
+`contact_email`, `share`, `favorite`.
+
+Areas and categories come from Craigslist's public reference service (no auth
+needed) and are memoized per client:
+
+```ruby
+client.reference.area("sfo").subareas.map(&:abbreviation)  #=> ["sfc", "sby", ...]
+client.reference.area("sfo").subareas?                     #=> true
+client.reference.category("ctd").description               #=> "cars & trucks - by dealer"
+client.reference.category("prk").unsupported?              #=> true
+```
+
+### Account messages
+
+Craigslist attaches notices to every JSON response and repeats them until
+acknowledged. Surface them somewhere a human will look:
+
+```ruby
+client.account_messages.each do |message|
+  logger.info("craigslist: #{message["message"]}")
+  client.account.acknowledge(message["messageId"])
+end
+```
+
+## Errors
+
+Everything raised derives from `Craigslist::API::Error`.
+
+```
+Error
+├── ConfigurationError    missing or blank credentials
+├── ValidationError       caught locally, before any request; carries #errors
+├── ConnectionError       DNS, refused, TLS
+│   └── TimeoutError
+├── ParseError            response was not the XML/JSON it promised
+└── ResponseError         carries #status, #body, #api_errors
+    ├── RequestError            400, or 415 for unparseable RSS
+    ├── AuthenticationError     401/403, or a rejected token
+    ├── NotFoundError           404
+    ├── RateLimitError          429
+    ├── ServerError             5xx
+    └── APIError                HTTP 200 with a populated errors array
+```
+
+`APIError` exists because the JSON API reports application-level failures
+in-band. A 200 is not proof of success:
+
+```ruby
+begin
+  client.posting("7123456780").body = "updated"
+rescue Craigslist::API::APIError => e
+  e.api_errors  #=> [{"code" => 0, "message" => "posting 7123456780 not found"}]
+end
+```
+
+## Configuration
+
+```ruby
+Craigslist::API.new(
+  email:      "you@example.com",
+  password:   ENV.fetch("CRAIGSLIST_PASSWORD"),
+  account_id: 1234,
+
+  timeout:      120,          # read timeout; generous, submissions can be large
+  open_timeout: 15,
+  logger:       Rails.logger, # logs request lines via Faraday
+  adapter:      :net_http,    # any Faraday adapter
+  scopes:       %w[bulkpost.posting bulkpost.account.billing],
+  user_agent:   "my-app/1.0"
+)
+```
+
+Scopes are hierarchical — `bulkpost.posting` grants `bulkpost.posting.delete`
+and the rest beneath it. The default requests all four top-level scopes.
+
+### Threads and multiple accounts
+
+Configuration is frozen and nothing mutates at request time, so a client is
+safe to share across threads. The OAuth token is cached per client behind a
+mutex and refreshed automatically, including once on a 401 in case it was
+revoked early.
+
+There is no global to configure. Talking to several accounts means building
+several clients, which is deliberate — ambient credentials are exactly the
+thing that breaks when one process serves more than one account.
+
+```ruby
+CLIENTS = accounts.to_h { |a| [a.id, Craigslist::API.new(**a.credentials)] }
+```
+
+Passwords and tokens are redacted from `inspect` output, so a stray `inspect`
+in a log line or exception backtrace will not leak them.
+
+## Development
+
+```bash
+bin/setup           # install dependencies
+bundle exec rake    # specs + linter
+bundle exec rspec
+bundle exec standardrb --fix
+bin/console         # IRB with the gem loaded
+```
+
+The suite is fully offline — WebMock blocks net connections outright. Response
+parsing is tested against fixtures transcribed from Craigslist's own published
+samples.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/biggeektx/craigslist-api-gem>.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/craigslist/api/access_token.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # An OAuth2 bearer token with an expiry.
+    #
+    # Immutable. {TokenProvider} discards and re-fetches rather than mutating.
+    class AccessToken
+      # Treat a token as expired this many seconds early, so a token does not
+      # die in flight between the expiry check and the server receiving it.
+      LEEWAY = 60
+
+      # @return [String] the raw token value
+      attr_reader :value
+
+      # @return [Time] the moment the token stops being valid
+      attr_reader :expires_at
+
+      # @return [Array<String>] scopes the token was granted
+      attr_reader :scopes
+
+      # @return [String] usually "Bearer"
+      attr_reader :token_type
+
+      def initialize(value:, expires_in:, scopes: [], token_type: "Bearer", now: Time.now)
+        @value = value
+        @expires_at = now + expires_in.to_i
+        @scopes = Array(scopes).flat_map { |s| s.to_s.split(/\s+/) }.freeze
+        @token_type = token_type || "Bearer"
+        freeze
+      end
+
+      # Builds a token from the token endpoint's JSON payload.
+      #
+      # @param payload [Hash]
+      # @return [AccessToken]
+      # @raise [AuthenticationError] if the payload carries no token
+      def self.from_payload(payload, now: Time.now)
+        value = payload["access_token"]
+        raise AuthenticationError, "token endpoint returned no access_token" if value.nil? || value.empty?
+
+        new(
+          value: value,
+          expires_in: payload.fetch("expires_in", 3600),
+          scopes: payload["scopes"] || payload["scope"] || [],
+          token_type: payload["token_type"],
+          now: now
+        )
+      end
+
+      # @return [Boolean] whether the token is expired, or close enough to it
+      def expired?(now: Time.now)
+        now >= (expires_at - LEEWAY)
+      end
+
+      # @return [String] value for the +Authorization+ header
+      def to_header
+        "#{token_type} #{value}"
+      end
+
+      # Keeps the token value out of logs and exception output.
+      def inspect
+        "#<#{self.class.name} token=[FILTERED] expires_at=#{expires_at.iso8601} scopes=#{scopes.inspect}>"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/craigslist/api/area.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # A craigslist area (a city or region), as published by the public
+    # reference service.
+    class Area
+      # A subdivision of an {Area}. Postings in areas that have subareas are
+      # expected to name one.
+      class SubArea
+        attr_reader :abbreviation, :description, :short_description, :id
+
+        def initialize(abbreviation:, description: nil, short_description: nil, id: nil)
+          @abbreviation = abbreviation
+          @description = description
+          @short_description = short_description
+          @id = id
+          freeze
+        end
+
+        # @param hash [Hash] raw payload
+        # @return [SubArea]
+        def self.from(hash)
+          new(
+            abbreviation: hash["Abbreviation"],
+            description: hash["Description"],
+            short_description: hash["ShortDescription"],
+            id: hash["SubAreaID"]
+          )
+        end
+
+        def to_s
+          abbreviation.to_s
+        end
+
+        def inspect
+          "#<#{self.class.name} #{abbreviation.inspect} #{description.inspect}>"
+        end
+      end
+
+      attr_reader :abbreviation, :description, :short_description, :hostname,
+        :country, :region, :latitude, :longitude, :id, :subareas
+
+      def initialize(abbreviation:, description: nil, short_description: nil,
+        hostname: nil, country: nil, region: nil, latitude: nil,
+        longitude: nil, id: nil, subareas: [])
+        @abbreviation = abbreviation
+        @description = description
+        @short_description = short_description
+        @hostname = hostname
+        @country = country
+        @region = region
+        @latitude = latitude
+        @longitude = longitude
+        @id = id
+        @subareas = subareas.freeze
+        freeze
+      end
+
+      # @param hash [Hash] raw payload
+      # @return [Area]
+      def self.from(hash)
+        new(
+          abbreviation: hash["Abbreviation"],
+          description: hash["Description"],
+          short_description: hash["ShortDescription"],
+          hostname: hash["Hostname"],
+          country: hash["Country"],
+          region: hash["Region"],
+          latitude: hash["Latitude"],
+          longitude: hash["Longitude"],
+          id: hash["AreaID"],
+          subareas: Array(hash["SubAreas"]).map { |sub| SubArea.from(sub) }
+        )
+      end
+
+      # @return [Boolean] whether a subarea must be supplied when posting here
+      def subareas?
+        !subareas.empty?
+      end
+
+      # @param abbreviation [String]
+      # @return [SubArea, nil]
+      def subarea(abbreviation)
+        subareas.find { |sub| sub.abbreviation == abbreviation.to_s }
+      end
+
+      def to_s
+        abbreviation.to_s
+      end
+
+      def inspect
+        "#<#{self.class.name} #{abbreviation.inspect} #{description.inspect} " \
+          "subareas=#{subareas.size}>"
+      end
+    end
+  end
+end