craigslist-api 0.1.0

data/lib/craigslist/api/posting_block.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Remaining prepaid posting blocks for one area/product combination.
+    class PostingBlock
+      # @return [String] area abbreviation, e.g. "htf"
+      attr_reader :area
+
+      # @return [String] e.g. "CAR", "JOB"
+      attr_reader :product_class
+
+      # @return [String] e.g. "hartford cars & trucks - by dealer block"
+      attr_reader :product_name
+
+      # @return [Integer] postings still available against this block
+      attr_reader :remaining_posts
+
+      def initialize(area:, product_class:, product_name:, remaining_posts:)
+        @area = area
+        @product_class = product_class
+        @product_name = product_name
+        @remaining_posts = remaining_posts.to_i
+        freeze
+      end
+
+      # @param hash [Hash] raw payload
+      # @return [PostingBlock]
+      def self.from(hash)
+        new(
+          area: hash["area"],
+          product_class: hash["productClass"],
+          product_name: hash["productName"],
+          remaining_posts: hash["remainingPosts"]
+        )
+      end
+
+      def inspect
+        "#<#{self.class.name} area=#{area.inspect} class=#{product_class.inspect} " \
+          "remaining=#{remaining_posts}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/posting_handle.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # A live posting, addressed by id.
+    #
+    # Returned by {Client#posting}. Holds no state of its own beyond the id —
+    # every reader hits the API — so it is safe to keep around, and it never
+    # goes stale.
+    #
+    # @example
+    #   posting = client.posting("7123456780")
+    #   posting.status          #=> "active"
+    #   posting.price = 4200
+    #   posting.add_image("photo.jpg")
+    #   posting.delete
+    class PostingHandle
+      # @return [String]
+      attr_reader :id
+
+      def initialize(client, id)
+        @client = client
+        @id = id.to_s
+      end
+
+      # @return [String] one of {Resources::Postings::STATUSES}
+      def status
+        client.postings.status(id)
+      end
+
+      # @return [Boolean]
+      def active?
+        status == "active"
+      end
+
+      # @return [Boolean]
+      def deleted?
+        status == "deleted"
+      end
+
+      # @return [Boolean]
+      def expired?
+        status == "expired"
+      end
+
+      # @return [String]
+      def body
+        client.postings.body(id)
+      end
+
+      # @param value [String]
+      # @return [String]
+      def update_body(value)
+        client.postings.update_body(id, value)
+      end
+
+      # @param value [String]
+      def body=(value)
+        update_body(value)
+      end
+
+      # @return [Integer, nil]
+      def price
+        client.postings.price(id)
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def update_price(value)
+        client.postings.update_price(id, value)
+      end
+
+      # @param value [Integer]
+      def price=(value)
+        update_price(value)
+      end
+
+      # @return [String, nil]
+      def remuneration
+        client.postings.remuneration(id)
+      end
+
+      # @param value [String]
+      # @return [String]
+      def update_remuneration(value)
+        client.postings.update_remuneration(id, value)
+      end
+
+      # @param value [String]
+      def remuneration=(value)
+        update_remuneration(value)
+      end
+
+      # @return [true]
+      def delete
+        client.postings.delete(id)
+      end
+
+      # @return [true]
+      def undelete
+        client.postings.undelete(id)
+      end
+
+      # @return [Array<ImageInfo>]
+      def images
+        client.images.list(id)
+      end
+
+      # @see Resources::Images#upload
+      # @return [ImageInfo]
+      def add_image(source, **options)
+        client.images.upload(id, source, **options)
+      end
+
+      # @param image_id [String]
+      # @return [true]
+      def remove_image(image_id)
+        client.images.remove(id, image_id)
+      end
+
+      # @param image_ids [Array<String>]
+      # @return [true]
+      def reorder_images(image_ids)
+        client.images.reorder(id, image_ids)
+      end
+
+      # @see Resources::Account#posting_stats
+      # @return [PostingStats]
+      def stats(start: nil, stop: nil)
+        client.account.posting_stats(id, start: start, stop: stop)
+      end
+
+      def inspect
+        "#<#{self.class.name} id=#{id.inspect}>"
+      end
+
+      private
+
+      attr_reader :client
+    end
+  end
+end

data/lib/craigslist/api/posting_stats.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Daily engagement counts for a posting.
+    #
+    # Craigslist reports each metric as +[unix_timestamp, count]+ pairs, one per
+    # UTC day, over a rolling thirty-day window ending at midnight UTC yesterday.
+    # Counts are requests, not unique viewers.
+    class PostingStats
+      # Every metric the API reports.
+      METRICS = %i[
+        impressions
+        views
+        contact
+        contact_chat
+        contact_phone
+        contact_email
+        share
+        favorite
+      ].freeze
+
+      # @return [String, nil] absent when the stats were requested for a single
+      #   posting, since the id is then already known
+      attr_reader :posting_id
+
+      # @return [Hash{Symbol => Array<Array(Time, Integer)>}]
+      attr_reader :series
+
+      def initialize(posting_id: nil, series: {})
+        @posting_id = posting_id
+        @series = series.freeze
+        freeze
+      end
+
+      # @param hash [Hash] raw payload for one posting
+      # @return [PostingStats]
+      def self.from(hash)
+        hash ||= {}
+
+        series = METRICS.each_with_object({}) do |metric, memo|
+          points = hash[metric.to_s]
+          next if points.nil?
+
+          memo[metric] = Array(points).map do |(timestamp, count)|
+            [Time.at(timestamp.to_i).utc, count.to_i]
+          end
+        end
+
+        new(posting_id: hash["postingId"], series: series)
+      end
+
+      # Time series for one metric.
+      #
+      # @param metric [Symbol] one of {METRICS}
+      # @return [Array<Array(Time, Integer)>] empty when not reported
+      def [](metric)
+        series.fetch(metric.to_sym, [])
+      end
+
+      # Sum of a metric across the whole window.
+      #
+      # @param metric [Symbol] one of {METRICS}
+      # @return [Integer]
+      def total(metric)
+        self[metric].sum { |(_, count)| count }
+      end
+
+      METRICS.each do |metric|
+        # @return [Integer] total for this metric over the window
+        define_method(:"total_#{metric}") { total(metric) }
+      end
+
+      # @return [Array<Symbol>] metrics that carry data
+      def reported_metrics
+        series.keys
+      end
+
+      def inspect
+        "#<#{self.class.name} posting_id=#{posting_id.inspect} " \
+          "metrics=#{reported_metrics.inspect}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api/reference.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Craigslist
+  module API
+    # Areas and categories, from craigslist's public reference service.
+    #
+    # These endpoints need no authentication and return bare JSON arrays rather
+    # than the Bulkpost envelope, so they bypass {JsonTransport} entirely.
+    #
+    # Both payloads are static enough to fetch once and hold — areas is around
+    # 165KB — so results are memoized per client behind a mutex.
+    class Reference
+      # Public endpoint listing every area and its subareas.
+      AREAS_PATH = "/Areas"
+
+      # Public endpoint listing every posting category.
+      CATEGORIES_PATH = "/Categories"
+
+      def initialize(connection)
+        @connection = connection
+        @mutex = Mutex.new
+        @areas = nil
+        @categories = nil
+      end
+
+      # @return [Array<Area>]
+      def areas
+        @mutex.synchronize do
+          @areas ||= get(AREAS_PATH).map { |entry| Area.from(entry) }.freeze
+        end
+      end
+
+      # @return [Array<Category>]
+      def categories
+        @mutex.synchronize do
+          @categories ||= get(CATEGORIES_PATH).map { |entry| Category.from(entry) }.freeze
+        end
+      end
+
+      # @param abbreviation [String] e.g. "sfo"
+      # @return [Area, nil]
+      def area(abbreviation)
+        areas.find { |a| a.abbreviation == abbreviation.to_s }
+      end
+
+      # @param abbreviation [String] e.g. "ctd"
+      # @return [Category, nil]
+      def category(abbreviation)
+        categories.find { |c| c.abbreviation == abbreviation.to_s }
+      end
+
+      # Drops the cached payloads so the next call refetches.
+      #
+      # @return [void]
+      def reload
+        @mutex.synchronize do
+          @areas = nil
+          @categories = nil
+        end
+      end
+
+      private
+
+      def get(path)
+        response = Connection.perform { @connection.get(path) }
+
+        unless response.success?
+          raise ResponseError.new(
+            "reference request failed with HTTP #{response.status}",
+            status: response.status,
+            body: response.body
+          )
+        end
+
+        parsed = JSON.parse(response.body.to_s)
+        parsed.is_a?(Array) ? parsed : []
+      rescue JSON::ParserError => e
+        raise ParseError, "reference service returned invalid JSON: #{e.message}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    module Resources
+      # Account notices and posting statistics.
+      class Account < Base
+        # Acknowledges an account message so it stops appearing on subsequent
+        # responses.
+        #
+        # Craigslist attaches these notices to every response until they are
+        # acknowledged, which is why {Client#account_messages} exists.
+        #
+        # @param message_id [String]
+        # @return [true]
+        def acknowledge(message_id)
+          transport.put(path("account", "message", message_id, "ack"))
+          true
+        end
+
+        # Engagement statistics for every posting on the account.
+        #
+        # @param start [String, Date, Time, nil] window start, "yyyy-mm-dd".
+        #   Defaults server-side to 31 days ago.
+        # @param stop [String, Date, Time, nil] window end, "yyyy-mm-dd".
+        #   Defaults server-side to yesterday.
+        # @return [Array<PostingStats>]
+        def stats(start: nil, stop: nil)
+          envelope = transport.get(
+            path("account", "stats", "all-postings"),
+            params: window(start, stop)
+          )
+
+          Array(envelope.data).map { |entry| PostingStats.from(entry) }
+        end
+
+        # Engagement statistics for one posting.
+        #
+        # @param posting_id [String, Integer]
+        # @param start [String, Date, Time, nil] see {#stats}
+        # @param stop [String, Date, Time, nil] see {#stats}
+        # @return [PostingStats]
+        def posting_stats(posting_id, start: nil, stop: nil)
+          envelope = transport.get(
+            path("account", "stats", "posting", posting_id),
+            params: window(start, stop)
+          )
+
+          # This endpoint returns a single-element array rather than an object.
+          payload = envelope.data.is_a?(Array) ? envelope.data.first : envelope.data
+          stats = PostingStats.from(payload || {})
+
+          return stats unless stats.posting_id.nil?
+
+          PostingStats.new(posting_id: posting_id.to_s, series: stats.series)
+        end
+
+        private
+
+        def window(start, stop)
+          {"start" => format_date(start), "stop" => format_date(stop)}.compact
+        end
+
+        def format_date(value)
+          return nil if value.nil?
+          return value if value.is_a?(String)
+
+          value.strftime("%Y-%m-%d")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Endpoint groups for the JSON Bulkpost API, reached through {Client}.
+    module Resources
+      # Shared plumbing for the JSON API resource groups.
+      class Base
+        # Every JSON endpoint hangs off this prefix.
+        BASE_PATH = "/bulkpost/v1"
+
+        # Characters RFC 3986 leaves unreserved in a path segment.
+        RESERVED = /[^A-Za-z0-9\-._~]/
+
+        def initialize(transport)
+          @transport = transport
+        end
+
+        private
+
+        attr_reader :transport
+
+        # Joins path segments, percent-encoding each one.
+        #
+        # Encoding matters here: image ids look like "4:00101_b1ztTgNtBAU" and
+        # the colon would otherwise land in the path unescaped.
+        #
+        # @return [String]
+        def path(*segments)
+          [BASE_PATH, *segments.map { |segment| escape(segment) }].join("/")
+        end
+
+        def escape(segment)
+          segment.to_s.b.gsub(RESERVED) { |char| format("%%%02X", char.ord) }
+        end
+
+        # Most endpoints wrap a single scalar in +data+; this pulls it out.
+        def fetch(envelope, key)
+          data = envelope.data
+          data.is_a?(Hash) ? data[key] : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    module Resources
+      # Account credit, prepaid posting blocks, pricing, and invoicing.
+      class Billing < Base
+        # @return [CreditSummary]
+        def credit
+          CreditSummary.from(transport.get(path("account", "billing", "credit")).data)
+        end
+
+        # Prepaid blocks still available, per area and product.
+        #
+        # @return [Array<PostingBlock>]
+        def posting_blocks
+          Array(transport.get(path("account", "billing", "posting-block-balances")).data)
+            .map { |entry| PostingBlock.from(entry) }
+        end
+
+        # Current cost of posting in an area and category.
+        #
+        # Prices can change without notice, so treat the result as a quote
+        # rather than something to cache.
+        #
+        # @param area [String] area abbreviation, e.g. "sfo"
+        # @param category [String] category abbreviation, e.g. "ofc"
+        # @return [Money, nil]
+        def pricing(area:, category:)
+          data = transport.get(
+            path("account", "billing", "current-pricing", "area", area, "category", category)
+          ).data || {}
+
+          Money.from(data["currentPricing"])
+        end
+
+        # Invoices everything not yet invoiced, ahead of the normal cycle.
+        #
+        # @return [Array<String>] ids of the invoices created
+        def create_invoice
+          data = transport.post(path("account", "billing", "make-invoice")).data || {}
+          Array(data["invoiceIDs"]).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "faraday/multipart"
+require "pathname"
+
+module Craigslist
+  module API
+    module Resources
+      # Images on a live posting.
+      #
+      # Note the API's verb choices are inverted from the usual convention:
+      # PUT uploads a new image, POST reorders the existing ones. The method
+      # names here describe the effect rather than the verb.
+      class Images < Base
+        # Assumed when the caller does not say otherwise.
+        DEFAULT_CONTENT_TYPE = "image/jpeg"
+
+        # @param posting_id [String, Integer]
+        # @return [Array<ImageInfo>] ordered as they appear on the posting
+        def list(posting_id)
+          data = transport.get(path("postings", posting_id, "images")).data || {}
+          Array(data["imageInfo"]).map { |info| ImageInfo.from(info) }
+        end
+
+        # Uploads an image and attaches it to the posting.
+        #
+        # With neither position given the image is appended. Positions are
+        # zero-based.
+        #
+        # @param posting_id [String, Integer]
+        # @param source [String, Pathname, IO] the image
+        # @param filename [String, nil] defaults to the basename of a path
+        # @param content_type [String]
+        # @param insert_position [Integer, nil] insert at this position
+        # @param replace_position [Integer, nil] replace the image here
+        # @return [ImageInfo] the newly attached image
+        # @raise [ValidationError] if both positions are given
+        def upload(posting_id, source, filename: nil, content_type: DEFAULT_CONTENT_TYPE,
+          insert_position: nil, replace_position: nil)
+          if !insert_position.nil? && !replace_position.nil?
+            raise ValidationError, ["pass insert_position or replace_position, not both"]
+          end
+
+          fields = {}
+          fields["insert_position"] = insert_position.to_s unless insert_position.nil?
+          fields["replace_position"] = replace_position.to_s unless replace_position.nil?
+
+          envelope = transport.upload(
+            path("postings", posting_id, "images"),
+            part: file_part(source, filename, content_type),
+            fields: fields
+          )
+
+          ImageInfo.from((envelope.data || {})["imageInfo"] || {})
+        end
+
+        # Sets the order of the posting's images.
+        #
+        # @param posting_id [String, Integer]
+        # @param image_ids [Array<String>] every image id, in the desired order
+        # @return [true]
+        def reorder(posting_id, image_ids)
+          transport.post(
+            path("postings", posting_id, "images"),
+            form: {"imageIdList" => Array(image_ids).join(",")}
+          )
+          true
+        end
+
+        # Detaches an image from the posting.
+        #
+        # The image itself is not destroyed — it stays publicly retrievable and
+        # can still be referenced by other postings.
+        #
+        # @param posting_id [String, Integer]
+        # @param image_id [String]
+        # @return [true]
+        def remove(posting_id, image_id)
+          transport.delete(path("postings", posting_id, "images", image_id))
+          true
+        end
+
+        private
+
+        def file_part(source, filename, content_type)
+          case source
+          when Pathname, String
+            Faraday::Multipart::FilePart.new(
+              source.to_s,
+              content_type,
+              filename || File.basename(source.to_s)
+            )
+          else
+            unless source.respond_to?(:read)
+              raise ValidationError, ["cannot upload a #{source.class}; pass a path or an IO"]
+            end
+
+            Faraday::Multipart::FilePart.new(source, content_type, filename || "upload.jpg")
+          end
+        end
+      end
+    end
+  end
+end