craigslist-api 0.1.0

data/lib/craigslist/api/bulk_transport.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Submits postings to the RSS bulk interface.
+    #
+    # Validate and post take identical documents and differ only in the URL, so
+    # validating is a genuine dry run of the exact payload that would be posted.
+    class BulkTransport
+      # The protocol section of the documentation asks for text/xml. The
+      # changelog mentions application/xml and the sample client still sends
+      # form encoding; text/xml is the one the protocol itself specifies.
+      CONTENT_TYPE = "text/xml; charset=utf-8"
+
+      # Dry-run endpoint. Takes the same document as {POST_PATH}.
+      VALIDATE_PATH = "/bulk-rss/validate"
+
+      # Endpoint that actually creates postings.
+      POST_PATH = "/bulk-rss/post"
+
+      def initialize(config:, connection:)
+        @config = config
+        @connection = connection
+        @serializer = Serializer.new(config)
+      end
+
+      # Dry run: checks the document without creating anything.
+      #
+      # @param postings [Posting, Array<Posting>]
+      # @return [ResultSet]
+      def validate(postings)
+        submit(VALIDATE_PATH, postings)
+      end
+
+      # Creates the postings.
+      #
+      # @param postings [Posting, Array<Posting>]
+      # @return [ResultSet]
+      def post(postings)
+        submit(POST_PATH, postings)
+      end
+
+      private
+
+      attr_reader :config, :connection, :serializer
+
+      def submit(path, postings)
+        list = Array(postings)
+        raise ValidationError, ["at least one posting is required"] if list.empty?
+
+        assert_unique_keys!(list)
+
+        response = Connection.perform do
+          connection.post(path) do |req|
+            req.headers["Content-Type"] = CONTENT_TYPE
+            req.headers["Accept"] = "text/xml"
+            req.body = serializer.serialize(list)
+          end
+        end
+
+        raise_for_status(response)
+        ResponseParser.parse(response.body)
+      end
+
+      # Keys identify postings within the document and are how results are
+      # matched back to submissions, so a collision would silently lose one.
+      def assert_unique_keys!(postings)
+        duplicates = postings.map(&:key).tally.select { |_, count| count > 1 }.keys
+        return if duplicates.empty?
+
+        raise ValidationError, ["duplicate posting keys: #{duplicates.inspect}"]
+      end
+
+      def raise_for_status(response)
+        return if response.success?
+
+        body = response.body.to_s
+        message = "bulk submission failed with HTTP #{response.status}"
+        message += ": #{body.strip}" unless body.strip.empty?
+
+        error_class =
+          case response.status
+          when 403 then AuthenticationError
+          when 400, 415 then RequestError
+          when 429 then RateLimitError
+          when 500..599 then ServerError
+          else ResponseError
+          end
+
+        raise error_class.new(message, status: response.status, body: body)
+      end
+    end
+  end
+end

data/lib/craigslist/api/category.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # A craigslist posting category, as published by the public reference
+    # service.
+    class Category
+      # Categories the bulk posting interface explicitly does not support.
+      # Submitting to one of these is documented as something not to do.
+      UNSUPPORTED = %w[sbw rew swp sub reo prk hou sha].freeze
+
+      attr_reader :abbreviation, :description, :type, :id
+
+      def initialize(abbreviation:, description: nil, type: nil, id: nil)
+        @abbreviation = abbreviation
+        @description = description
+        @type = type
+        @id = id
+        freeze
+      end
+
+      # @param hash [Hash] raw payload
+      # @return [Category]
+      def self.from(hash)
+        new(
+          abbreviation: hash["Abbreviation"],
+          description: hash["Description"],
+          type: hash["Type"],
+          id: hash["CategoryID"]
+        )
+      end
+
+      # @return [Boolean] whether bulk posting to this category is disallowed
+      def unsupported?
+        UNSUPPORTED.include?(abbreviation)
+      end
+
+      def to_s
+        abbreviation.to_s
+      end
+
+      def inspect
+        "#<#{self.class.name} #{abbreviation.inspect} #{description.inspect} type=#{type.inspect}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/client.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # The single entry point for both halves of the Craigslist bulk posting
+    # platform.
+    #
+    # Craigslist splits the work across two services with different formats and
+    # different authentication: postings are *created* through an RSS interface
+    # authenticated with credentials embedded in the XML, and *managed*
+    # afterwards through a JSON API authenticated with an OAuth2 bearer token.
+    # One set of credentials covers both. This client owns that seam so callers
+    # do not have to think about it — {#post} and {#posting} are the same
+    # object's methods, and the token lifecycle is invisible.
+    #
+    # Configuration is frozen and nothing mutates at request time, so a client
+    # is safe to share across threads. Talking to several accounts means
+    # building several clients, which is deliberate: there is no global to
+    # reconfigure and no ambient state to get wrong.
+    #
+    # @example Creating postings
+    #   client = Craigslist::API::Client.new(
+    #     email: "you@example.com",
+    #     password: ENV.fetch("CRAIGSLIST_PASSWORD"),
+    #     account_id: 1234
+    #   )
+    #
+    #   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"}
+    #   )
+    #
+    #   results = client.validate(posting)   # dry run
+    #   results = client.post(posting) if results.all_successful?
+    #
+    # @example Managing what you created
+    #   live = client.posting(results.posting_ids.first)
+    #   live.price = 4200
+    #   live.add_image("front.jpg")
+    class Client
+      # @return [Configuration]
+      attr_reader :config
+
+      # @param email [String] craigslist account email
+      # @param password [String] craigslist account password
+      # @param account_id [String, Integer] craigslist account number
+      # @param options [Hash] any other {Configuration} keyword
+      # @raise [ConfigurationError] when credentials are missing
+      def initialize(email:, password:, account_id:, **options)
+        @config = Configuration.new(
+          email: email,
+          password: password,
+          account_id: account_id,
+          **options
+        )
+
+        build_components
+      end
+
+      # Builds a client from an existing {Configuration}.
+      #
+      # @param config [Configuration]
+      # @return [Client]
+      def self.from_config(config)
+        allocate.tap do |client|
+          client.instance_variable_set(:@config, config)
+          client.send(:build_components)
+        end
+      end
+
+      # Checks postings without creating anything.
+      #
+      # Sends the identical document {#post} would, so a clean validation is a
+      # real rehearsal rather than an approximation.
+      #
+      # @param postings [Posting, Array<Posting>]
+      # @return [ResultSet]
+      # @raise [ValidationError] if no postings were given, or keys collide
+      def validate(postings)
+        bulk.validate(postings)
+      end
+
+      # Creates postings.
+      #
+      # Does not raise when individual postings fail — a batch with some
+      # rejections is ordinary. Inspect the returned {ResultSet}.
+      #
+      # @param postings [Posting, Array<Posting>]
+      # @return [ResultSet]
+      def post(postings)
+        bulk.post(postings)
+      end
+
+      # A handle for working with one live posting.
+      #
+      # @param posting_id [String, Integer]
+      # @return [PostingHandle]
+      def posting(posting_id)
+        PostingHandle.new(self, posting_id)
+      end
+
+      # @return [Resources::Postings]
+      attr_reader :postings
+
+      # @return [Resources::Images]
+      attr_reader :images
+
+      # @return [Resources::Billing]
+      attr_reader :billing
+
+      # @return [Resources::Account]
+      attr_reader :account
+
+      # @return [Reference] public areas and categories data
+      attr_reader :reference
+
+      # @return [CreditSummary]
+      def credit
+        billing.credit
+      end
+
+      # @return [Array<PostingBlock>]
+      def posting_blocks
+        billing.posting_blocks
+      end
+
+      # @param area [String]
+      # @param category [String]
+      # @return [Money, nil]
+      def pricing(area:, category:)
+        billing.pricing(area: area, category: category)
+      end
+
+      # @param zip [String]
+      # @return [Hash{Symbol => String}]
+      def area_for_zip(zip)
+        postings.area_for_zip(zip)
+      end
+
+      # @see Resources::Account#stats
+      # @return [Array<PostingStats>]
+      def stats(start: nil, stop: nil)
+        account.stats(start: start, stop: stop)
+      end
+
+      # Notices attached to the most recent JSON API response.
+      #
+      # Craigslist repeats these on every response until acknowledged, so it is
+      # worth surfacing them somewhere a human will look.
+      #
+      # @return [Array<Hash>] +{"messageId", "message"}+ entries
+      def account_messages
+        @json_transport.account_messages
+      end
+
+      # Discards the cached OAuth token, forcing the next JSON call to
+      # re-authenticate. Rarely needed; the token refreshes itself.
+      #
+      # @return [void]
+      def reset_token!
+        @token_provider.invalidate!
+      end
+
+      def inspect
+        "#<#{self.class.name} email=#{config.email.inspect} account_id=#{config.account_id.inspect}>"
+      end
+      alias_method :to_s, :inspect
+
+      private
+
+      # Built eagerly rather than memoized: connections are cheap, and lazy
+      # construction would race two threads into two token providers.
+      def build_components
+        bapi_connection = Connection.build(url: config.bapi_host, config: config)
+
+        @token_provider = TokenProvider.new(config: config, connection: bapi_connection)
+
+        @json_transport = JsonTransport.new(
+          config: config,
+          connection: Connection.build(url: config.bapi_host, config: config, multipart: true),
+          token_provider: @token_provider
+        )
+
+        @bulk = BulkTransport.new(
+          config: config,
+          connection: Connection.build(url: config.bulk_host, config: config)
+        )
+
+        @postings = Resources::Postings.new(@json_transport)
+        @images = Resources::Images.new(@json_transport)
+        @billing = Resources::Billing.new(@json_transport)
+        @account = Resources::Account.new(@json_transport)
+        @reference = Reference.new(
+          Connection.build(url: config.reference_host, config: config)
+        )
+      end
+
+      attr_reader :bulk
+    end
+  end
+end

data/lib/craigslist/api/configuration.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Immutable configuration for a {Client}.
+    #
+    # Instances are frozen on construction. Nothing mutates configuration at
+    # request time, which keeps a single client safe to share across threads.
+    # Multi-account setups build one client per account rather than swapping
+    # credentials on a global.
+    class Configuration
+      # Host serving the RSS bulk posting interface (posting creation).
+      DEFAULT_BULK_HOST = "https://post.craigslist.org"
+
+      # Host serving the JSON Bulkpost API (everything after creation).
+      DEFAULT_BAPI_HOST = "https://bapi.craigslist.org"
+
+      # Host serving public areas/categories reference data. No auth required.
+      DEFAULT_REFERENCE_HOST = "https://reference.craigslist.org"
+
+      # Top-level OAuth scopes. Scopes are hierarchical, so requesting
+      # +bulkpost.posting+ also grants +bulkpost.posting.delete+ and friends.
+      DEFAULT_SCOPES = %w[
+        bulkpost.posting
+        bulkpost.account.billing
+        bulkpost.account.message
+        bulkpost.account.stats
+      ].freeze
+
+      # Bulk submissions can carry base64 image payloads, so the default read
+      # timeout is generous.
+      DEFAULT_TIMEOUT = 120
+
+      # Connection establishment timeout, in seconds.
+      DEFAULT_OPEN_TIMEOUT = 15
+
+      attr_reader :email, :password, :account_id, :scopes, :bulk_host, :bapi_host,
+        :reference_host, :timeout, :open_timeout, :user_agent, :logger, :adapter
+
+      # @param email [String] the craigslist account email used to log in
+      # @param password [String] the craigslist account password
+      # @param account_id [String, Integer] craigslist account number with
+      #   posting credit, for which +email+ is an authorized buyer
+      # @param scopes [Array<String>] OAuth scopes to request
+      # @param bulk_host [String] override the RSS interface host
+      # @param bapi_host [String] override the JSON API host
+      # @param reference_host [String] override the reference data host
+      # @param timeout [Integer] read timeout in seconds
+      # @param open_timeout [Integer] connection timeout in seconds
+      # @param user_agent [String] value sent as +User-Agent+
+      # @param logger [Logger, nil] when set, Faraday logs requests to it
+      # @param adapter [Symbol] Faraday adapter to use
+      # @raise [ConfigurationError] if any credential is blank
+      def initialize(
+        email:,
+        password:,
+        account_id:,
+        scopes: DEFAULT_SCOPES,
+        bulk_host: DEFAULT_BULK_HOST,
+        bapi_host: DEFAULT_BAPI_HOST,
+        reference_host: DEFAULT_REFERENCE_HOST,
+        timeout: DEFAULT_TIMEOUT,
+        open_timeout: DEFAULT_OPEN_TIMEOUT,
+        user_agent: "craigslist-api-ruby/#{VERSION}",
+        logger: nil,
+        adapter: Faraday.default_adapter
+      )
+        @email = presence!(email, :email)
+        @password = presence!(password, :password)
+        @account_id = presence!(account_id, :account_id).to_s
+        @scopes = Array(scopes).map(&:to_s).freeze
+        @bulk_host = bulk_host
+        @bapi_host = bapi_host
+        @reference_host = reference_host
+        @timeout = timeout
+        @open_timeout = open_timeout
+        @user_agent = user_agent
+        @logger = logger
+        @adapter = adapter
+
+        freeze
+      end
+
+      # The OAuth2 +client_id+, which Craigslist defines as the account email
+      # and account id joined by a semicolon.
+      #
+      # @return [String]
+      def client_id
+        "#{email};#{account_id}"
+      end
+
+      # HTTP Basic credential for the token endpoint.
+      #
+      # Encoded with +Array#pack+ rather than the +base64+ gem, which stopped
+      # being a default gem in Ruby 3.4 and would otherwise add a dependency.
+      #
+      # @return [String]
+      def basic_authorization
+        "Basic #{["#{client_id}:#{password}"].pack("m0")}"
+      end
+
+      # @return [String] the URL RSS submissions are validated against
+      def validate_url
+        "#{bulk_host}/bulk-rss/validate"
+      end
+
+      # @return [String] the URL RSS submissions are posted to
+      def post_url
+        "#{bulk_host}/bulk-rss/post"
+      end
+
+      # Redacts the password so credentials never leak into logs or exception
+      # output through a stray +inspect+.
+      #
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} email=#{email.inspect} account_id=#{account_id.inspect} password=[FILTERED]>"
+      end
+      alias_method :to_s, :inspect
+
+      private
+
+      def presence!(value, name)
+        string = value.to_s.strip
+        raise ConfigurationError, "#{name} is required" if string.empty?
+        value.is_a?(String) ? string : value
+      end
+    end
+  end
+end

data/lib/craigslist/api/connection.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+
+module Craigslist
+  module API
+    # Builds the Faraday connections the client uses.
+    #
+    # Connections are built once per client and reused. The adapter is taken
+    # from configuration so host applications can swap in their own (or a test
+    # stub) without this gem forcing a choice on them.
+    module Connection
+      module_function
+
+      # @param url [String] base URL for the connection
+      # @param config [Configuration]
+      # @param multipart [Boolean] enable the multipart request middleware
+      # @return [Faraday::Connection]
+      def build(url:, config:, multipart: false)
+        Faraday.new(url: url) do |f|
+          f.request :multipart if multipart
+
+          f.headers["User-Agent"] = config.user_agent
+          f.options.timeout = config.timeout
+          f.options.open_timeout = config.open_timeout
+
+          f.response :logger, config.logger, headers: false, bodies: false if config.logger
+
+          f.adapter config.adapter
+        end
+      end
+
+      # Runs a request, translating Faraday's transport exceptions into this
+      # library's error hierarchy.
+      #
+      # Deliberately does not use Faraday's +:raise_error+ middleware. That
+      # middleware keys purely on HTTP status, and neither Craigslist API treats
+      # status as the source of truth — so status handling lives with the code
+      # that also understands in-band failures.
+      #
+      # @yieldreturn [Faraday::Response]
+      # @return [Faraday::Response]
+      # @raise [TimeoutError, ConnectionError]
+      def perform
+        yield
+      rescue Faraday::TimeoutError => e
+        raise TimeoutError, "request timed out: #{e.message}"
+      rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise ConnectionError, "connection failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/craigslist/api/credit_summary.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Credit standing for an invoiced account.
+    class CreditSummary
+      # @return [Money, nil] total credit extended
+      attr_reader :credit_line
+
+      # @return [Money, nil] credit still available
+      attr_reader :remaining
+
+      # @return [Money, nil] credit consumed so far
+      attr_reader :used
+
+      def initialize(credit_line: nil, remaining: nil, used: nil)
+        @credit_line = credit_line
+        @remaining = remaining
+        @used = used
+        freeze
+      end
+
+      # @param hash [Hash] raw payload
+      # @return [CreditSummary]
+      def self.from(hash)
+        hash ||= {}
+        new(
+          credit_line: Money.from(hash["creditLine"]),
+          remaining: Money.from(hash["creditRemaining"]),
+          used: Money.from(hash["creditUsed"])
+        )
+      end
+
+      def inspect
+        "#<#{self.class.name} line=#{credit_line} remaining=#{remaining} used=#{used}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/envelope.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Craigslist
+  module API
+    # The response wrapper every JSON Bulkpost endpoint returns.
+    #
+    #   {"apiVersion": 1, "data": {...}, "errors": [], "accountMessages": []}
+    #
+    # Note that +errors+ can be populated on an HTTP 200 — status alone is not
+    # enough to tell whether a call worked.
+    class Envelope
+      # @return [Numeric, nil]
+      attr_reader :api_version
+
+      # @return [Hash, Array, nil] the useful payload
+      attr_reader :data
+
+      # @return [Array<Hash>] +{"code", "message"}+ entries
+      attr_reader :errors
+
+      # @return [Array<Hash>] +{"messageId", "message"}+ notices, which keep
+      #   appearing until acknowledged via {Resources::Account#acknowledge}
+      attr_reader :account_messages
+
+      def initialize(api_version: nil, data: nil, errors: [], account_messages: [])
+        @api_version = api_version
+        @data = data
+        @errors = Array(errors)
+        @account_messages = Array(account_messages)
+        freeze
+      end
+
+      # @param body [String] raw JSON response body
+      # @return [Envelope]
+      # @raise [ParseError] if the body is not JSON
+      def self.parse(body)
+        payload = JSON.parse(body.to_s)
+
+        # A few error paths return a bare object rather than a full envelope.
+        payload = {} unless payload.is_a?(Hash)
+
+        new(
+          api_version: payload["apiVersion"],
+          data: payload["data"],
+          errors: payload["errors"],
+          account_messages: payload["accountMessages"]
+        )
+      rescue JSON::ParserError => e
+        raise ParseError, "expected JSON from the Bulkpost API: #{e.message}"
+      end
+
+      # @return [Boolean]
+      def error?
+        !errors.empty?
+      end
+
+      # @return [String] errors joined into one human-readable line
+      def error_message
+        errors.map { |e| e["message"] }.compact.join("; ")
+      end
+    end
+  end
+end