craigslist-api 0.1.0

data/lib/craigslist/api/errors.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Base class for every error raised by this library. Rescuing this catches
+    # anything the gem raises on purpose.
+    class Error < StandardError; end
+
+    # Raised when the client is constructed with missing or nonsensical
+    # credentials or options.
+    class ConfigurationError < Error; end
+
+    # Raised when a {Posting} is missing fields the interface requires, caught
+    # locally before a request is made.
+    class ValidationError < Error
+      # @return [Array<String>] every problem found, not just the first
+      attr_reader :errors
+
+      def initialize(errors)
+        @errors = Array(errors)
+        super(@errors.join("; "))
+      end
+    end
+
+    # Raised when a request never produced a usable HTTP response: DNS failure,
+    # connection refused, TLS problems, timeouts.
+    class ConnectionError < Error; end
+
+    # Raised when a request exceeded the configured timeout.
+    class TimeoutError < ConnectionError; end
+
+    # Raised when a response arrived but could not be parsed as the XML or JSON
+    # the endpoint promised.
+    class ParseError < Error; end
+
+    # Raised when Craigslist returned a response we understand as a failure.
+    #
+    # Carries the HTTP status and raw body so callers can inspect what actually
+    # came back, plus any structured errors extracted from a JSON envelope.
+    class ResponseError < Error
+      # @return [Integer, nil] HTTP status code
+      attr_reader :status
+
+      # @return [String, nil] raw response body
+      attr_reader :body
+
+      # @return [Array<Hash>] structured +{code:, message:}+ entries, when present
+      attr_reader :api_errors
+
+      def initialize(message = nil, status: nil, body: nil, api_errors: [])
+        @status = status
+        @body = body
+        @api_errors = api_errors
+        super(message)
+      end
+    end
+
+    # Raised for malformed requests. The RSS interface uses HTTP 415 for RSS it
+    # cannot parse; the JSON API uses 400.
+    class RequestError < ResponseError; end
+
+    # Raised when credentials were rejected, or the account is not authorized
+    # for bulk posting. Covers HTTP 401 and 403, and OAuth token failures.
+    class AuthenticationError < ResponseError; end
+
+    # Raised on HTTP 404.
+    class NotFoundError < ResponseError; end
+
+    # Raised on HTTP 429.
+    class RateLimitError < ResponseError; end
+
+    # Raised on any 5xx.
+    class ServerError < ResponseError; end
+
+    # Raised when a JSON response arrived with HTTP 200 but carried a non-empty
+    # +errors+ array in its envelope.
+    #
+    # This is separate from {ResponseError} subclasses keyed to status codes
+    # because the Bulkpost API reports application-level failures in-band.
+    class APIError < ResponseError; end
+  end
+end

data/lib/craigslist/api/image.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Craigslist
+  module API
+    # An image attached to a bulk posting.
+    #
+    # The RSS interface takes images inline as base64 JPEG data, up to 24 per
+    # posting. Position is zero-based and the image at position 0 is the one
+    # featured on search pages.
+    class Image
+      # Craigslist rejects postings carrying more than this many images.
+      MAX_PER_POSTING = 24
+
+      # Highest valid zero-based position.
+      MAX_POSITION = MAX_PER_POSTING - 1
+
+      # @return [String] base64-encoded image data
+      attr_reader :data
+
+      # @return [Integer, nil] zero-based position within the posting
+      attr_reader :position
+
+      # @param data [String] already base64-encoded data
+      # @param position [Integer, nil]
+      def initialize(data, position: nil)
+        @data = data
+        @position = position
+        freeze
+      end
+
+      class << self
+        # Coerces a caller-supplied image into an {Image}.
+        #
+        # Accepts an existing {Image}, an IO-like object, or a path as a String
+        # or Pathname. Raw base64 has to go through {from_base64} — guessing
+        # whether a String is a path or a payload would be worse than asking.
+        #
+        # @param source [Image, IO, Pathname, String]
+        # @param position [Integer, nil]
+        # @return [Image]
+        # @raise [ValidationError] if the source type is not supported
+        def wrap(source, position: nil)
+          case source
+          when Image
+            position.nil? ? source : new(source.data, position: position)
+          when Pathname
+            from_file(source, position: position)
+          when String
+            from_file(source, position: position)
+          else
+            if source.respond_to?(:read)
+              from_io(source, position: position)
+            else
+              raise ValidationError, ["cannot build an image from #{source.class}"]
+            end
+          end
+        end
+
+        # @param path [String, Pathname]
+        # @return [Image]
+        def from_file(path, position: nil)
+          from_data(File.binread(path.to_s), position: position)
+        rescue SystemCallError => e
+          raise ValidationError, ["could not read image #{path}: #{e.message}"]
+        end
+
+        # @param io [IO]
+        # @return [Image]
+        def from_io(io, position: nil)
+          io.binmode if io.respond_to?(:binmode)
+          from_data(io.read, position: position)
+        end
+
+        # @param binary [String] raw (unencoded) image bytes
+        # @return [Image]
+        def from_data(binary, position: nil)
+          # pack("m") produces RFC 2045 base64 with line breaks, matching the
+          # form Craigslist's own documentation shows. Using Array#pack rather
+          # than the base64 gem keeps this dependency-free on Ruby 3.4+.
+          new([binary].pack("m"), position: position)
+        end
+
+        # @param encoded [String] data that is already base64
+        # @return [Image]
+        def from_base64(encoded, position: nil)
+          new(encoded, position: position)
+        end
+      end
+
+      # @return [Image] a copy pinned to +index+ when no position was set
+      def with_default_position(index)
+        position.nil? ? self.class.new(data, position: index) : self
+      end
+
+      def inspect
+        "#<#{self.class.name} position=#{position.inspect} bytes=#{data.bytesize}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/image_info.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Metadata about an image attached to a live posting.
+    class ImageInfo
+      # @return [String] craigslist's image id, e.g. "4:00101_b1ztTgNtBAU"
+      attr_reader :id
+
+      # @return [String, nil]
+      attr_reader :filename
+
+      # @return [String, nil] e.g. "JPEG", "GIF", "WEBP"
+      attr_reader :format
+
+      # @return [Integer, nil]
+      attr_reader :width
+
+      # @return [Integer, nil]
+      attr_reader :height
+
+      # @return [Integer, nil] zero-based position within the posting
+      attr_reader :position
+
+      def initialize(id:, filename: nil, format: nil, width: nil, height: nil, position: nil)
+        @id = id
+        @filename = filename
+        @format = format
+        @width = width
+        @height = height
+        @position = position
+        freeze
+      end
+
+      # @param hash [Hash] raw payload
+      # @return [ImageInfo]
+      def self.from(hash)
+        new(
+          id: hash["id"],
+          filename: hash["filename"],
+          format: hash["format"],
+          width: hash["width"],
+          height: hash["height"],
+          position: hash["position"]
+        )
+      end
+
+      def inspect
+        "#<#{self.class.name} id=#{id.inspect} position=#{position.inspect} #{width}x#{height} #{format}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/json_transport.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Craigslist
+  module API
+    # Request plumbing for the JSON Bulkpost API.
+    #
+    # Owns three concerns the resource classes should not repeat: attaching a
+    # bearer token (refreshing once on a 401), mapping HTTP status onto this
+    # library's error classes, and unwrapping the response envelope.
+    class JsonTransport
+      # Writes to the Bulkpost API are form-encoded, not JSON, even though the
+      # responses are JSON.
+      FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+
+      # @return [Array<Hash>] account notices seen on the most recent response
+      attr_reader :account_messages
+
+      def initialize(config:, connection:, token_provider:)
+        @config = config
+        @connection = connection
+        @token_provider = token_provider
+        @account_messages = []
+      end
+
+      # @return [Envelope]
+      def get(path, params: {})
+        run(:get, path, params: params)
+      end
+
+      # @return [Envelope]
+      def post(path, form: nil)
+        run(:post, path, form: form)
+      end
+
+      # @return [Envelope]
+      def put(path, form: nil)
+        run(:put, path, form: form)
+      end
+
+      # @return [Envelope]
+      def delete(path)
+        run(:delete, path)
+      end
+
+      # Uploads a file as +multipart/form-data+.
+      #
+      # @param path [String]
+      # @param part [Faraday::Multipart::FilePart]
+      # @param fields [Hash] additional form fields
+      # @return [Envelope]
+      def upload(path, part:, fields: {})
+        run(:put, path, body: fields.merge("file" => part), content_type: nil)
+      end
+
+      private
+
+      def run(method, path, params: {}, form: nil, body: nil, content_type: FORM_CONTENT_TYPE, retried: false)
+        response = Connection.perform do
+          @connection.public_send(method, path) do |req|
+            req.headers["Authorization"] = @token_provider.token.to_header
+            req.headers["Accept"] = "application/json"
+            req.params.update(stringify(params)) unless params.empty?
+
+            if form && !form.empty?
+              req.headers["Content-Type"] = content_type if content_type
+              req.body = URI.encode_www_form(form)
+            elsif body
+              req.body = body
+            end
+          end
+        end
+
+        # A 401 can precede the recorded expiry if the token was revoked, so
+        # give it exactly one refresh-and-retry before surfacing the failure.
+        if response.status == 401 && !retried
+          @token_provider.invalidate!
+          return run(method, path,
+            params: params, form: form, body: body,
+            content_type: content_type, retried: true)
+        end
+
+        handle(response)
+      end
+
+      def handle(response)
+        envelope = parse_envelope(response)
+        @account_messages = envelope&.account_messages || []
+
+        raise_for_status(response, envelope) unless response.success?
+
+        # Only reachable on a 2xx, so an unparseable body here is a genuine
+        # surprise rather than an error page.
+        if envelope.nil?
+          raise ParseError, "expected JSON from the Bulkpost API, got #{response.body.to_s[0, 200].inspect}"
+        end
+
+        # HTTP 200 with a populated errors array is a real failure mode here.
+        if envelope.error?
+          raise APIError.new(
+            envelope.error_message,
+            status: response.status,
+            body: response.body,
+            api_errors: envelope.errors
+          )
+        end
+
+        envelope
+      end
+
+      # Returns nil only when a non-empty body could not be parsed. An empty
+      # body is treated as an empty envelope, since some writes reply with no
+      # payload at all.
+      def parse_envelope(response)
+        body = response.body.to_s
+        return Envelope.new if body.strip.empty?
+
+        Envelope.parse(body)
+      rescue ParseError
+        nil
+      end
+
+      def raise_for_status(response, envelope)
+        message = envelope&.error? ? envelope.error_message : "HTTP #{response.status}"
+
+        raise error_class(response.status).new(
+          message,
+          status: response.status,
+          body: response.body,
+          api_errors: envelope&.errors || []
+        )
+      end
+
+      def error_class(status)
+        case status
+        when 400 then RequestError
+        when 401, 403 then AuthenticationError
+        when 404 then NotFoundError
+        when 429 then RateLimitError
+        when 500..599 then ServerError
+        else ResponseError
+        end
+      end
+
+      def stringify(params)
+        params.each_with_object({}) do |(key, value), memo|
+          memo[key.to_s] = value unless value.nil?
+        end
+      end
+    end
+  end
+end

data/lib/craigslist/api/money.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # A monetary amount as the Bulkpost API reports it: an integer in minor
+    # units plus the exponent needed to scale it.
+    #
+    # +{amount: 100000, currency: "USD", exponent: 2}+ is $1,000.00.
+    #
+    # Conversion goes through +Rational+ rather than +Float+ so the scaling is
+    # exact, and deliberately avoids +BigDecimal+, which stopped being a default
+    # gem in Ruby 3.4 and would add a dependency.
+    class Money
+      # @return [Integer] value in minor units
+      attr_reader :amount
+
+      # @return [String] ISO 4217 currency code
+      attr_reader :currency
+
+      # @return [Integer] power of ten separating minor units from major
+      attr_reader :exponent
+
+      def initialize(amount:, currency: "USD", exponent: 2)
+        @amount = amount.to_i
+        @currency = currency.to_s
+        @exponent = exponent.to_i
+        freeze
+      end
+
+      # @param hash [Hash, nil] raw +{"amount", "currency", "exponent"}+ payload
+      # @return [Money, nil]
+      def self.from(hash)
+        return nil if hash.nil?
+
+        new(
+          amount: hash["amount"],
+          currency: hash.fetch("currency", "USD"),
+          exponent: hash.fetch("exponent", 2)
+        )
+      end
+
+      # @return [Rational] exact value in major units
+      def to_r
+        Rational(amount, 10**exponent)
+      end
+
+      # @return [Float] value in major units, with the usual float caveats
+      def to_f
+        to_r.to_f
+      end
+
+      # @return [String] e.g. "1000.00 USD"
+      def to_s
+        "#{format("%.#{exponent}f", to_r)} #{currency}"
+      end
+
+      # @param other [Object]
+      # @return [Boolean] true when amount, currency and exponent all match
+      def ==(other)
+        other.is_a?(Money) &&
+          amount == other.amount &&
+          currency == other.currency &&
+          exponent == other.exponent
+      end
+      alias_method :eql?, :==
+
+      # @return [Integer] value-based hash, so Money can key a Hash
+      def hash
+        [amount, currency, exponent].hash
+      end
+
+      def inspect
+        "#<#{self.class.name} #{self}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/posting.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # 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.
+    #
+    # @example 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"}
+    #   )
+    class Posting
+      # How the reply address is displayed on the posting.
+      PRIVACY = {
+        none: "A",        # show no email address
+        anonymous: "C",   # use an anonymous craigslist relay address
+        public: "P"       # show the address as given
+      }.freeze
+
+      # Ruby-side names for +cl:mapLocation+ attributes, which are camelCase on
+      # the wire.
+      LOCATION_ATTRIBUTES = {
+        postal: "postal",
+        city: "city",
+        state: "state",
+        cross_street1: "crossStreet1",
+        cross_street2: "crossStreet2",
+        latitude: "latitude",
+        longitude: "longitude"
+      }.freeze
+
+      # Ruby-side names for +cl:brokerInfo+ attributes.
+      BROKER_ATTRIBUTES = {
+        company_name: "companyName",
+        fee_disclosure: "feeDisclosure"
+      }.freeze
+
+      attr_reader :key, :title, :description, :category, :area, :subarea,
+        :neighborhood, :price, :po_number, :reply_email, :reply_privacy,
+        :other_contact_info, :location, :images, :broker, :generic,
+        :housing_basics, :housing_pets, :housing_terms, :job_basics,
+        :auto_basics, :forsale
+
+      # @param key [String] identifier unique within the submission document.
+      #   Echoed back on the matching result, and how you correlate a response
+      #   to what you sent.
+      # @param title [String]
+      # @param description [String] the posting body
+      # @param category [String] category abbreviation, e.g. "ctd"
+      # @param area [String] area abbreviation, e.g. "sfo"
+      # @param subarea [String, nil] required in areas that have subareas
+      # @param neighborhood [String, nil]
+      # @param price [Integer, nil]
+      # @param po_number [String, nil] your own tracking reference
+      # @param reply_email [String, nil]
+      # @param reply_privacy [Symbol, String] one of +:none+, +:anonymous+,
+      #   +:public+, or a raw "A"/"C"/"P"
+      # @param other_contact_info [String, nil] free-text alternate contact
+      # @param location [Hash] see {LOCATION_ATTRIBUTES}. Either +:postal+ or
+      #   both +:latitude+ and +:longitude+ is required.
+      # @param images [Array<Image, IO, String, Pathname>] see {Image.wrap}
+      # @param broker [Hash] see {BROKER_ATTRIBUTES}
+      # @param generic [Hash] +cl:generic+ attributes
+      # @param housing_basics [Hash] +cl:housing_basics+ attributes
+      # @param housing_pets [Hash] +cl:housing_pets+ attributes
+      # @param housing_terms [Hash] +cl:housing_terms+ attributes
+      # @param job_basics [Hash] +cl:job_basics+ attributes
+      # @param auto_basics [Hash] +cl:auto_basics+ attributes
+      # @param forsale [Hash] +cl:forsale+ attributes
+      # @raise [ValidationError] if anything required is missing
+      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
+
+      # @return [Array<String>] problems with this posting, empty when valid
+      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
+
+      # @return [Boolean]
+      def valid?
+        errors.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} key=#{key.inspect} category=#{category.inspect} " \
+          "area=#{area.inspect} images=#{images.size}>"
+      end
+
+      private
+
+      def validate!
+        found = errors
+        raise ValidationError, found unless found.empty?
+      end
+
+      def location_errors
+        has_postal = !location[:postal].to_s.empty?
+        has_coords = !location[:latitude].nil? && !location[:longitude].nil?
+        return [] if has_postal || has_coords
+
+        ["location requires :postal, or both :latitude and :longitude"]
+      end
+
+      def image_errors
+        problems = []
+
+        if images.size > Image::MAX_PER_POSTING
+          problems << "a posting accepts at most #{Image::MAX_PER_POSTING} images, got #{images.size}"
+        end
+
+        positions = images.map(&:position).compact
+        out_of_range = positions.reject { |p| p.between?(0, Image::MAX_POSITION) }
+        unless out_of_range.empty?
+          problems << "image positions must be 0..#{Image::MAX_POSITION}, got #{out_of_range.inspect}"
+        end
+
+        duplicates = positions.tally.select { |_, count| count > 1 }.keys
+        problems << "duplicate image positions: #{duplicates.inspect}" unless duplicates.empty?
+
+        problems
+      end
+
+      def build_images(sources)
+        Array(sources).each_with_index.map do |source, index|
+          Image.wrap(source).with_default_position(index)
+        end
+      end
+
+      def normalize_privacy(value)
+        return PRIVACY.fetch(value) if value.is_a?(Symbol) && PRIVACY.key?(value)
+
+        string = value.to_s.upcase
+        return string if PRIVACY.value?(string)
+
+        raise ValidationError, ["reply_privacy must be one of #{PRIVACY.keys.inspect} or #{PRIVACY.values.inspect}"]
+      end
+
+      def compact(hash)
+        (hash || {}).reject { |_, value| value.nil? }
+      end
+    end
+  end
+end