craigslist-api 0.1.0

data/lib/craigslist/api/zip_location.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Craigslist
+  module API
+    # Where a US ZIP code maps to on craigslist.
+    #
+    # Carries a subarea when the ZIP resolves to one. That matters more than it
+    # looks: subarea is required in every area that has subareas, and omitting
+    # it is the most common reason a posting comes back NOT_VALID.
+    #
+    # @example Feeding a posting directly
+    #   place = client.area_for_zip("94110")
+    #   place.area      #=> "sfo"
+    #   place.subarea   #=> "sfc"
+    #
+    #   Craigslist::API::Posting.new(**place.to_h, key: ..., title: ...)
+    class ZipLocation
+      # @return [String, nil] area abbreviation, e.g. "sfo"
+      attr_reader :area
+
+      # @return [String, nil] e.g. "SF bay area"
+      attr_reader :area_description
+
+      # @return [String, nil] subarea abbreviation, e.g. "sfc"
+      attr_reader :subarea
+
+      # @return [String, nil] e.g. "city of san francisco"
+      attr_reader :subarea_description
+
+      def initialize(area: nil, area_description: nil, subarea: nil, subarea_description: nil)
+        @area = area
+        @area_description = area_description
+        @subarea = subarea
+        @subarea_description = subarea_description
+        freeze
+      end
+
+      # Builds from the endpoint payload.
+      #
+      # The live API nests under "area" and "subarea". The published OpenAPI
+      # spec documents a flat shape instead, so both are accepted.
+      #
+      # @param data [Hash, nil]
+      # @return [ZipLocation]
+      def self.from(data)
+        data ||= {}
+        nested = data["area"]
+
+        if nested.is_a?(Hash)
+          sub = data["subarea"].is_a?(Hash) ? data["subarea"] : {}
+          new(
+            area: nested["abbreviation"],
+            area_description: nested["description"],
+            subarea: sub["abbreviation"],
+            subarea_description: sub["description"]
+          )
+        else
+          new(area: data["abbreviation"], area_description: data["description"])
+        end
+      end
+
+      # @return [Boolean] whether this ZIP resolved to a subarea
+      def subarea?
+        !subarea.nil?
+      end
+
+      # Posting keywords, ready to splat. Omits +:subarea+ when there is none,
+      # rather than passing an explicit nil.
+      #
+      # @return [Hash]
+      def to_h
+        subarea? ? {area: area, subarea: subarea} : {area: area}
+      end
+
+      def inspect
+        "#<#{self.class.name} area=#{area.inspect} subarea=#{subarea.inspect}>"
+      end
+    end
+  end
+end

data/lib/craigslist/api.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "time"
+
+require "craigslist/api/version"
+require "craigslist/api/errors"
+
+require "craigslist/api/connection"
+require "craigslist/api/configuration"
+
+require "craigslist/api/money"
+require "craigslist/api/envelope"
+require "craigslist/api/access_token"
+require "craigslist/api/token_provider"
+require "craigslist/api/json_transport"
+
+require "craigslist/api/image"
+require "craigslist/api/posting"
+require "craigslist/api/serializer"
+require "craigslist/api/result"
+require "craigslist/api/result_set"
+require "craigslist/api/response_parser"
+require "craigslist/api/bulk_transport"
+
+require "craigslist/api/image_info"
+require "craigslist/api/posting_block"
+require "craigslist/api/credit_summary"
+require "craigslist/api/posting_stats"
+require "craigslist/api/area"
+require "craigslist/api/category"
+require "craigslist/api/zip_location"
+require "craigslist/api/reference"
+
+require "craigslist/api/resources/base"
+require "craigslist/api/resources/postings"
+require "craigslist/api/resources/images"
+require "craigslist/api/resources/billing"
+require "craigslist/api/resources/account"
+
+require "craigslist/api/posting_handle"
+require "craigslist/api/client"
+
+# Top-level namespace. This gem defines everything under {Craigslist::API}.
+module Craigslist
+  # Ruby client for the Craigslist bulk posting platform.
+  #
+  # Access to bulk posting is granted by Craigslist on a case-by-case basis to
+  # high-volume posters, and is limited to paid US categories: jobs (offered),
+  # apartment rentals in NYC, and for-sale-by-dealer.
+  #
+  # @see Client the single entry point
+  module API
+    # Convenience constructor.
+    #
+    #   client = Craigslist::API.new(email: ..., password: ..., account_id: ...)
+    #
+    # @see Client#initialize
+    # @return [Client]
+    def self.new(...)
+      Client.new(...)
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: craigslist-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick Chewning
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: |-
+  A single-client Ruby wrapper around both halves of Craigslist's bulk posting
+  platform: the RSS bulk interface used to create postings, and the JSON
+  Bulkpost API used to manage them afterwards. Handles OAuth2 token lifecycle,
+  XML serialization, and per-posting result reporting behind one object.
+email:
+- nchewning@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/craigslist/api.rb
+- lib/craigslist/api/access_token.rb
+- lib/craigslist/api/area.rb
+- lib/craigslist/api/bulk_transport.rb
+- lib/craigslist/api/category.rb
+- lib/craigslist/api/client.rb
+- lib/craigslist/api/configuration.rb
+- lib/craigslist/api/connection.rb
+- lib/craigslist/api/credit_summary.rb
+- lib/craigslist/api/envelope.rb
+- lib/craigslist/api/errors.rb
+- lib/craigslist/api/image.rb
+- lib/craigslist/api/image_info.rb
+- lib/craigslist/api/json_transport.rb
+- lib/craigslist/api/money.rb
+- lib/craigslist/api/posting.rb
+- lib/craigslist/api/posting_block.rb
+- lib/craigslist/api/posting_handle.rb
+- lib/craigslist/api/posting_stats.rb
+- lib/craigslist/api/reference.rb
+- lib/craigslist/api/resources/account.rb
+- lib/craigslist/api/resources/base.rb
+- lib/craigslist/api/resources/billing.rb
+- lib/craigslist/api/resources/images.rb
+- lib/craigslist/api/resources/postings.rb
+- lib/craigslist/api/response_parser.rb
+- lib/craigslist/api/result.rb
+- lib/craigslist/api/result_set.rb
+- lib/craigslist/api/serializer.rb
+- lib/craigslist/api/token_provider.rb
+- lib/craigslist/api/version.rb
+- lib/craigslist/api/zip_location.rb
+homepage: https://github.com/biggeektx/craigslist-api-gem
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/biggeektx/craigslist-api-gem
+  source_code_uri: https://github.com/biggeektx/craigslist-api-gem/tree/v0.1.0
+  changelog_uri: https://github.com/biggeektx/craigslist-api-gem/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/biggeektx/craigslist-api-gem/issues
+  documentation_uri: https://rubydoc.info/gems/craigslist-api/0.1.0
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Craigslist bulk posting APIs
+test_files: []