craigslist-api 0.1.0

data/lib/craigslist/api/resources/postings.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    module Resources
+      # Reading and editing postings that already exist.
+      #
+      # Postings are created through the RSS interface ({Client#post}); this
+      # covers everything afterwards.
+      class Postings < Base
+        # Statuses a posting can report.
+        STATUSES = %w[active deleted expired pending removed].freeze
+
+        # @param posting_id [String, Integer]
+        # @return [String] one of {STATUSES}
+        def status(posting_id)
+          fetch(transport.get(path("postings", posting_id, "status")), "status")
+        end
+
+        # @param posting_id [String, Integer]
+        # @return [String] the posting body
+        def body(posting_id)
+          fetch(transport.get(path("postings", posting_id, "body")), "body")
+        end
+
+        # Replaces the posting body.
+        #
+        # Postings in "ctd" (cars & trucks by dealer) must keep the VIN they
+        # were created with; the API rejects a body that changes it.
+        #
+        # @param posting_id [String, Integer]
+        # @param body [String]
+        # @return [String] the updated body as the API echoes it back
+        def update_body(posting_id, body)
+          envelope = transport.put(path("postings", posting_id, "body"), form: {"body" => body})
+          fetch(envelope, "body")
+        end
+
+        # @param posting_id [String, Integer]
+        # @return [Integer, nil] for categories that carry a price
+        def price(posting_id)
+          fetch(transport.get(path("postings", posting_id, "price")), "price")
+        end
+
+        # @param posting_id [String, Integer]
+        # @param price [Integer] in the currency of the posting's location
+        # @return [Integer] the updated price
+        def update_price(posting_id, price)
+          envelope = transport.put(path("postings", posting_id, "price"), form: {"price" => price.to_i})
+          fetch(envelope, "price")
+        end
+
+        # @param posting_id [String, Integer]
+        # @return [String, nil] for jobs and gigs postings
+        def remuneration(posting_id)
+          fetch(transport.get(path("postings", posting_id, "remuneration")), "remuneration")
+        end
+
+        # @param posting_id [String, Integer]
+        # @param remuneration [String] free text, e.g. "$19.95/hr plus tips"
+        # @return [String] the updated value
+        def update_remuneration(posting_id, remuneration)
+          envelope = transport.put(
+            path("postings", posting_id, "remuneration"),
+            form: {"remuneration" => remuneration}
+          )
+          fetch(envelope, "remuneration")
+        end
+
+        # @param posting_id [String, Integer]
+        # @return [true]
+        def delete(posting_id)
+          transport.delete(path("postings", posting_id))
+          true
+        end
+
+        # @param posting_id [String, Integer]
+        # @return [true]
+        def undelete(posting_id)
+          transport.put(path("postings", posting_id, "undelete"))
+          true
+        end
+
+        # Maps a US ZIP code onto the craigslist area that covers it, and the
+        # subarea within it when there is one.
+        #
+        # @param zip [String]
+        # @return [ZipLocation]
+        def area_for_zip(zip)
+          ZipLocation.from(transport.get(path("posting", "zip", zip, "area")).data)
+        end
+      end
+    end
+  end
+end

data/lib/craigslist/api/response_parser.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+
+module Craigslist
+  module API
+    # Turns the RSS document returned by validate/post into a {ResultSet}.
+    #
+    # Element lookups use the literal prefixed names as they appear on the wire
+    # rather than XPath namespace resolution, which REXML handles awkwardly when
+    # a default namespace is in play.
+    class ResponseParser
+      # Prefix craigslist puts on the channel description in post mode.
+      UPLOAD_ID_PREFIX = "upload-id:"
+
+      class << self
+        # @param xml [String] raw response body
+        # @return [ResultSet]
+        # @raise [ParseError] if the body is not well-formed XML
+        def parse(xml)
+          document = build(xml)
+          root = document.root
+          raise ParseError, "response contained no root element" if root.nil?
+
+          new(root, xml.to_s).result_set
+        end
+
+        private
+
+        def build(xml)
+          REXML::Document.new(xml.to_s)
+        rescue REXML::ParseException => e
+          raise ParseError, "could not parse the bulk posting response: #{e.message}"
+        end
+      end
+
+      def initialize(root, raw = nil)
+        @root = root
+        @raw = raw
+      end
+
+      # @return [ResultSet]
+      def result_set
+        ResultSet.new(results: results, upload_id: upload_id, raw: raw)
+      end
+
+      private
+
+      attr_reader :root, :raw
+
+      def results
+        root.get_elements("item").map { |item| build_result(item) }
+      end
+
+      def build_result(item)
+        Result.new(
+          key: item.attributes["rdf:about"].to_s,
+          status: value_of(item, "cl:postedStatus"),
+          explanation: value_of(item, "cl:postedExplanation"),
+          posting_id: value_of(item, "cl:postingID"),
+          manage_url: value_of(item, "cl:postingManageURL"),
+          view_url: value_of(item, "cl:postingViewURL"),
+          preview_html: value_of(item, "cl:previewHTML"),
+          warnings: item.get_elements("cl:warning").filter_map { |w| text_of(w) }
+        )
+      end
+
+      def upload_id
+        description = root.get_elements("channel/description").first
+        text = text_of(description)
+        return nil if text.nil? || !text.start_with?(UPLOAD_ID_PREFIX)
+
+        text.delete_prefix(UPLOAD_ID_PREFIX)
+      end
+
+      def value_of(parent, name)
+        text_of(parent.get_elements(name).first)
+      end
+
+      # Reads every text child, CDATA included, and strips surrounding
+      # whitespace — craigslist pretty-prints URLs onto their own lines, which
+      # leaves newlines inside the element.
+      def text_of(element)
+        return nil if element.nil?
+
+        text = element.texts.map(&:value).join.strip
+        text.empty? ? nil : text
+      end
+    end
+  end
+end

data/lib/craigslist/api/result.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # The outcome of a single posting within a bulk submission.
+    #
+    # Bulk submissions succeed and fail per item, and the HTTP status says
+    # nothing about it — a 200 can carry a document in which every posting
+    # failed. So submissions return results rather than raising: a batch with a
+    # few rejections is ordinary, not exceptional.
+    class Result
+      # Returned by validate when the posting looks acceptable.
+      VALID = "VALID"
+
+      # Validation failed. {#explanation} says why.
+      NOT_VALID = "NOT_VALID"
+
+      # The posting was accepted.
+      POSTED = "POSTED"
+
+      # Unexpected error at post time.
+      FAILED = "FAILED"
+
+      # The account has no remaining blocks for this area/category and is not
+      # invoiced. More must be purchased before the posting is processed.
+      INSUFFICIENT_BLOCKS = "INSUFFICIENT_BLOCKS"
+
+      # The invoiced account hit its credit limit.
+      CREDIT_LIMIT_REACHED = "CREDIT_LIMIT_REACHED"
+
+      # Billing the card named by +cl:purchaseWithCreditCardID+ failed.
+      CREDIT_CARD_ERROR = "CREDIT_CARD_ERROR"
+
+      # @return [String] the key you supplied for this posting
+      attr_reader :key
+
+      # @return [String, nil] one of the status constants above
+      attr_reader :status
+
+      # @return [String, nil] human-readable detail, populated on failure
+      attr_reader :explanation
+
+      # @return [String, nil] craigslist's id for the new posting, on success
+      attr_reader :posting_id
+
+      # @return [String, nil] URL for editing or deleting the posting
+      attr_reader :manage_url
+
+      # @return [String, nil] public URL of the posting
+      attr_reader :view_url
+
+      # @return [String, nil] HTML preview of the posting as submitted
+      attr_reader :preview_html
+
+      # @return [Array<String>] non-fatal warnings, typically XML parsing
+      #   complaints. Worth logging even when the posting succeeded.
+      attr_reader :warnings
+
+      def initialize(key:, status: nil, explanation: nil, posting_id: nil,
+        manage_url: nil, view_url: nil, preview_html: nil, warnings: [])
+        @key = key
+        @status = status
+        @explanation = explanation
+        @posting_id = posting_id
+        @manage_url = manage_url
+        @view_url = view_url
+        @preview_html = preview_html
+        @warnings = Array(warnings).freeze
+        freeze
+      end
+
+      # @return [Boolean] validated successfully (validate mode only)
+      def valid?
+        status == VALID
+      end
+
+      # @return [Boolean] accepted for posting (post mode only)
+      def posted?
+        status == POSTED
+      end
+
+      # @return [Boolean] either valid or posted
+      def success?
+        valid? || posted?
+      end
+
+      # @return [Boolean]
+      def failure?
+        !success?
+      end
+
+      # @return [Boolean] rejected during validation
+      def not_valid?
+        status == NOT_VALID
+      end
+
+      # @return [Boolean] the account is out of posting blocks
+      def insufficient_blocks?
+        status == INSUFFICIENT_BLOCKS
+      end
+
+      # @return [Boolean] the invoiced account hit its credit limit
+      def credit_limit_reached?
+        status == CREDIT_LIMIT_REACHED
+      end
+
+      # @return [Boolean] the credit card could not be billed
+      def credit_card_error?
+        status == CREDIT_CARD_ERROR
+      end
+
+      # @return [Boolean] whether any non-fatal warnings came back
+      def warnings?
+        !warnings.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} key=#{key.inspect} status=#{status.inspect} " \
+          "posting_id=#{posting_id.inspect}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/result_set.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Every {Result} from one bulk submission, plus the upload id Craigslist
+    # assigns to the batch.
+    #
+    # Enumerable, so it behaves like the array of results it wraps while still
+    # answering the questions you actually have after a submission.
+    class ResultSet
+      include Enumerable
+
+      # @return [Array<Result>]
+      attr_reader :results
+
+      # @return [String, nil] craigslist's identifier for this submission,
+      #   taken from the channel description. Present in post mode.
+      attr_reader :upload_id
+
+      # The unparsed response body.
+      #
+      # Kept because a NOT_VALID with no explanation is otherwise a dead end,
+      # and reaching the raw XML should not require rebuilding the request by
+      # hand.
+      #
+      # @return [String, nil]
+      attr_reader :raw
+
+      def initialize(results:, upload_id: nil, raw: nil)
+        @results = Array(results).freeze
+        @upload_id = upload_id
+        @raw = raw
+        @index = @results.each_with_object({}) { |r, memo| memo[r.key] = r }.freeze
+        freeze
+      end
+
+      # @yieldparam result [Result]
+      # @return [Enumerator, ResultSet]
+      def each(&block)
+        results.each(&block)
+      end
+
+      # @param key [String] the key supplied when building the posting
+      # @return [Result, nil]
+      def [](key)
+        @index[key.to_s]
+      end
+
+      # @return [Array<Result>]
+      def successful
+        select(&:success?)
+      end
+
+      # @return [Array<Result>]
+      def failed
+        select(&:failure?)
+      end
+
+      # @return [Array<Result>] results carrying non-fatal warnings, which are
+      #   easy to miss because they can accompany a success
+      def warned
+        select(&:warnings?)
+      end
+
+      # @return [Boolean] whether every posting succeeded
+      def all_successful?
+        failed.empty?
+      end
+
+      # @return [Boolean]
+      def any_failures?
+        !failed.empty?
+      end
+
+      # @return [Array<String>] ids of postings that were created
+      def posting_ids
+        select(&:posted?).map(&:posting_id).compact
+      end
+
+      # @return [Integer] number of results in the batch
+      def size
+        results.size
+      end
+      alias_method :length, :size
+
+      def empty?
+        results.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} size=#{size} successful=#{successful.size} " \
+          "failed=#{failed.size} upload_id=#{upload_id.inspect}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/serializer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+
+module Craigslist
+  module API
+    # Renders {Posting} objects into the RDF/RSS document the bulk interface
+    # expects.
+    #
+    # REXML lives here and nowhere else. Bulk submissions inline base64 images,
+    # so a large batch is a large document; if building a DOM ever becomes a
+    # memory problem this class can be reimplemented as a streaming writer
+    # without changing anything public.
+    class Serializer
+      # Default namespace for the RSS 1.0 elements.
+      RSS_NAMESPACE = "http://purl.org/rss/1.0/"
+
+      # RDF namespace, used for the item manifest.
+      RDF_NAMESPACE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+
+      # Craigslist's own namespace, carrying every cl:* element.
+      CL_NAMESPACE = "http://www.craigslist.org/about/cl-bulk-ns/1.0"
+
+      # @param config [Configuration] supplies the +cl:auth+ credentials
+      def initialize(config)
+        @config = config
+      end
+
+      # @param postings [Array<Posting>]
+      # @param io [IO, String, nil] destination; a new String is used if omitted
+      # @return [String, IO] whatever was written to
+      def serialize(postings, io: nil)
+        output = io || +""
+        build_document(Array(postings)).write(output)
+        output
+      end
+
+      private
+
+      attr_reader :config
+
+      def build_document(postings)
+        doc = REXML::Document.new
+        doc << REXML::XMLDecl.new("1.0", "UTF-8")
+
+        root = doc.add_element("rdf:RDF",
+          "xmlns" => RSS_NAMESPACE,
+          "xmlns:rdf" => RDF_NAMESPACE,
+          "xmlns:cl" => CL_NAMESPACE)
+
+        append_channel(root, postings)
+        postings.each { |posting| append_item(root, posting) }
+
+        doc
+      end
+
+      def append_channel(root, postings)
+        channel = root.add_element("channel")
+
+        items = channel.add_element("items")
+        postings.each do |posting|
+          items.add_element("rdf:li", "rdf:resource" => posting.key)
+        end
+
+        channel.add_element("cl:auth",
+          "username" => config.email,
+          "password" => config.password,
+          "accountID" => config.account_id)
+      end
+
+      def append_item(root, posting)
+        item = root.add_element("item", "rdf:about" => posting.key)
+
+        text_element(item, "cl:category", posting.category)
+        text_element(item, "cl:area", posting.area)
+        text_element(item, "cl:subarea", posting.subarea)
+        text_element(item, "cl:neighborhood", posting.neighborhood)
+        text_element(item, "cl:price", posting.price)
+
+        attribute_element(item, "cl:housing_basics", posting.housing_basics)
+        attribute_element(item, "cl:housing_pets", posting.housing_pets)
+        attribute_element(item, "cl:housing_terms", posting.housing_terms)
+        attribute_element(item, "cl:job_basics", posting.job_basics)
+        attribute_element(item, "cl:auto_basics", posting.auto_basics)
+        attribute_element(item, "cl:forsale", posting.forsale)
+        attribute_element(item, "cl:generic", posting.generic)
+
+        attribute_element(item, "cl:mapLocation",
+          rename(posting.location, Posting::LOCATION_ATTRIBUTES))
+        append_reply_email(item, posting)
+        attribute_element(item, "cl:brokerInfo",
+          rename(posting.broker, Posting::BROKER_ATTRIBUTES))
+
+        text_element(item, "title", posting.title)
+        cdata_element(item, "description", posting.description)
+        text_element(item, "cl:PONumber", posting.po_number)
+
+        posting.images.each { |image| append_image(item, image) }
+      end
+
+      def append_reply_email(item, posting)
+        return if posting.reply_email.nil? || posting.reply_email.empty?
+
+        attributes = {"privacy" => posting.reply_privacy}
+        unless posting.other_contact_info.nil? || posting.other_contact_info.empty?
+          attributes["otherContactInfo"] = posting.other_contact_info
+        end
+
+        item.add_element("cl:replyEmail", attributes).add_text(posting.reply_email)
+      end
+
+      def append_image(item, image)
+        attributes = image.position.nil? ? {} : {"position" => image.position.to_s}
+        element = item.add_element("cl:image", attributes)
+
+        # Written raw: base64 is alphanumeric plus "+/=", so it needs no
+        # escaping, and skipping the escape pass matters on megabyte payloads.
+        element.add(REXML::Text.new(image.data, true, nil, true))
+      end
+
+      def text_element(parent, name, value)
+        return if value.nil? || value.to_s.empty?
+
+        parent.add_element(name).add_text(value.to_s)
+      end
+
+      # Emits text as CDATA, split around any literal "]]>".
+      #
+      # A "]]>" in a posting body would otherwise close the section early and
+      # corrupt the whole document. REXML does not guard against this and
+      # posting bodies are arbitrary user text, so split the run across
+      # adjacent sections: "a]]>b" becomes CDATA("a]]") + CDATA(">b"), which
+      # concatenates back to the original on the far end.
+      def cdata_element(parent, name, value)
+        element = parent.add_element(name)
+        chunks = value.to_s.split("]]>", -1)
+        final = chunks.size - 1
+
+        chunks.each_with_index do |chunk, index|
+          content = +""
+          content << ">" unless index.zero?
+          content << chunk
+          content << "]]" unless index == final
+
+          element.add(REXML::CData.new(content))
+        end
+
+        element
+      end
+
+      def attribute_element(parent, name, attributes)
+        return if attributes.nil? || attributes.empty?
+
+        parent.add_element(name, stringify(attributes))
+      end
+
+      def rename(hash, mapping)
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[mapping.fetch(key.to_sym, key.to_s)] = value
+        end
+      end
+
+      # The interface expresses booleans as 0/1, so accept Ruby booleans and
+      # translate rather than making callers remember.
+      def stringify(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[key.to_s] =
+            case value
+            when true then "1"
+            when false then "0"
+            else value.to_s
+            end
+        end
+      end
+    end
+  end
+end

data/lib/craigslist/api/token_provider.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Craigslist
+  module API
+    # Acquires and caches the OAuth2 access token used by the JSON API.
+    #
+    # Tokens live an hour. This holds one per client instance, guarded by a
+    # mutex so concurrent callers on a shared client cannot stampede the token
+    # endpoint or read a half-replaced token. Deliberately an instance, not a
+    # class-level cache: one process may talk to several accounts.
+    class TokenProvider
+      # OAuth2 token endpoint.
+      TOKEN_PATH = "/bulkpost/oauth/access-token"
+
+      # @param config [Configuration]
+      # @param connection [Faraday::Connection] pointed at the bapi host
+      def initialize(config:, connection:)
+        @config = config
+        @connection = connection
+        @mutex = Mutex.new
+        @token = nil
+      end
+
+      # Returns a live token, fetching or refreshing if needed.
+      #
+      # @return [AccessToken]
+      def token
+        @mutex.synchronize do
+          @token = fetch if @token.nil? || @token.expired?
+          @token
+        end
+      end
+
+      # Drops the cached token so the next call re-authenticates.
+      #
+      # Called after a 401, which can happen before the recorded expiry if the
+      # token was revoked server-side.
+      #
+      # @return [void]
+      def invalidate!
+        @mutex.synchronize { @token = nil }
+      end
+
+      private
+
+      def fetch
+        response = Connection.perform do
+          @connection.post(TOKEN_PATH) do |req|
+            req.headers["Authorization"] = @config.basic_authorization
+            req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+            req.headers["Accept"] = "application/json"
+            req.body = URI.encode_www_form(
+              grant_type: "client_credentials",
+              scope: @config.scopes.join(" ")
+            )
+          end
+        end
+
+        unless response.success?
+          raise AuthenticationError.new(
+            "token request failed with HTTP #{response.status}",
+            status: response.status,
+            body: response.body
+          )
+        end
+
+        AccessToken.from_payload(parse(response))
+      end
+
+      def parse(response)
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError => e
+        raise ParseError, "token endpoint returned invalid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/craigslist/api/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Current gem version.
+    VERSION = "0.1.0"
+  end
+end