crawlbase 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a1ccd286be2a6973c23cc8c9dc84a292af4d49910995054312a68e9beca6761
-  data.tar.gz: 0da3a67ba36a2151d6b982f7a9dc961adae4a1a58f0aac311d089e2dfd99cce9
+  metadata.gz: 42efa911e98c21bc83337c2fd34524b205a04520ae7f13d8c90efd8832cadbee
+  data.tar.gz: a031d03c6ed8994135a50ae81279a866918e7feba128e630e22f7908d62c6dee
 SHA512:
-  metadata.gz: 4d4b9ce783a5fa43cb0dab14550f01f2fcaed958b31bceeab91a9540456361a226f18fb41e11ae874f7d20862ba49d62088ab492b44c8a9b73c96c5812b8d4f3
-  data.tar.gz: 39ce7ce6996726bb7a3043277b1170fbc06b05f4cebf2903dc1db242bb4ae865de7a5a7a5eaa5af9f7861fcbccbfff92cce8227f5b2ed7df284c47d4c9f7cbe0
+  metadata.gz: ffcd59a906f655aff0010147ab1db09544137344aa987617c544a058d14a3771694a0cf9e641c46cadc36fc42976156a2e1611af9742acc11119a362e4f694b8
+  data.tar.gz: 48cddc484f162578332f974b34b1921e7f5429b909bf71389134ec96cf6b0bf54deccd6301371f5680af20394a4b89192194f35986ab70543532d8351dec511c

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-07-15
+
+### Added
+
+- `cb_status` as the preferred public attribute for Crawlbase status on `Crawlbase::API` (and subclasses) and `Crawlbase::StorageAPI`.
+- Status resolution prefers the `cb_status` response header or JSON field, then falls back to `pc_status` when `cb_status` is absent.
+
+### Deprecated
+
+- `pc_status` is deprecated but still supported and returns the same resolved value as `cb_status`. A one-time deprecation warning is emitted when `pc_status` is accessed. Prefer `cb_status`. Removal is planned for a future major release.
+
+### Migration
+
+```ruby
+# Before (deprecated)
+response.pc_status
+
+# After (preferred)
+response.cb_status
+```

data/README.md

@@ -56,7 +56,7 @@ begin
   response = api.get('https://www.facebook.com/britneyspears')
   puts response.status_code
   puts response.original_status
-  puts response.pc_status
+  puts response.cb_status
   puts response.body
 rescue => exception
   puts exception.backtrace
@@ -125,17 +125,32 @@ response = api.get('https://www.freelancer.com', options: { page_wait: 5000 })
 puts response.status_code
 ```
 
-## Original status
+## Original status and Crawlbase status
 
-You can always get the original status and crawlbase status from the response. Read the [Crawlbase documentation](https://crawlbase.com/dashboard/docs) to learn more about those status.
+You can always get the original status and Crawlbase status from the response. Read the [Crawlbase documentation](https://crawlbase.com/dashboard/docs) to learn more about those statuses.
+
+Prefer `cb_status` for the Crawlbase status. `pc_status` is deprecated but still supported temporarily and returns the same resolved value.
 
 ```ruby
 response = api.get('https://sfbay.craigslist.org/')
 
 puts response.original_status
-puts response.pc_status
+puts response.cb_status # preferred
+# puts response.pc_status # deprecated; same value as cb_status
 ```
 
+### Migrating from `pc_status` to `cb_status`
+
+```ruby
+# Before (deprecated)
+response.pc_status
+
+# After (preferred)
+response.cb_status
+```
+
+The library reads `cb_status` from the API response first, then falls back to `pc_status` if `cb_status` is not present.
+
 ## Scraper API usage
 
 Initialize the Scraper API using your normal token and call the `get` method.
@@ -254,7 +269,7 @@ Pass the [url](https://crawlbase.com/docs/storage-api/parameters/#url) that you
 begin
   response = storage_api.get('https://www.apple.com')
   puts response.original_status
-  puts response.pc_status
+  puts response.cb_status
   puts response.url
   puts response.status_code
   puts response.rid
@@ -271,7 +286,7 @@ or you can use the [RID](https://crawlbase.com/docs/storage-api/parameters/#rid)
 begin
   response = storage_api.get(RID)
   puts response.original_status
-  puts response.pc_status
+  puts response.cb_status
   puts response.url
   puts response.status_code
   puts response.rid
@@ -304,7 +319,7 @@ To do a bulk request with a list of RIDs, please send the list of rids as an arr
 begin
   response = storage_api.bulk([RID1, RID2, RID3, ...])
   puts response.original_status
-  puts response.pc_status
+  puts response.cb_status
   puts response.url
   puts response.status_code
   puts response.rid
@@ -367,4 +382,4 @@ Everyone interacting in the Crawlbase project's codebases, issue trackers, chat
 
 ---
 
-Copyright 2025 Crawlbase
+Copyright 2026 Crawlbase

data/lib/crawlbase/api.rb

@@ -6,7 +6,11 @@ require 'uri'
 
 module Crawlbase
   class API
-    attr_reader :token, :body, :status_code, :original_status, :pc_status, :url, :storage_url, :timeout
+    # Crawlbase HTTP response code for the API call itself.
+    attr_reader :token, :body, :status_code, :original_status, :url, :storage_url, :timeout
+
+    # Crawlbase status from the response (preferred name for former +pc_status+).
+    attr_reader :cb_status
 
     INVALID_TOKEN = 'Token is required'
     INVALID_URL = 'URL is required'
@@ -19,6 +23,12 @@ module Crawlbase
       @timeout = options.fetch(:timeout, DEFAULT_TIMEOUT)
     end
 
+    # Deprecated: use {#cb_status}. Returns the same resolved Crawlbase status.
+    def pc_status
+      StatusResolution.warn_pc_status_deprecated
+      @pc_status
+    end
+
     def get(url, options = {})
       raise INVALID_URL if url.empty?
 
@@ -80,7 +90,8 @@ module Crawlbase
       res = format == 'json' || base_url.include?('/scraper') ? JSON.parse(response.body) : response
 
       @original_status = res['original_status'].to_i
-      @pc_status = res['pc_status'].to_i
+      @cb_status = StatusResolution.resolve_cb_status(res)
+      @pc_status = @cb_status
       @url = res['url']
       @storage_url = res['storage_url']
       @status_code = response.code.to_i

data/lib/crawlbase/status_resolution.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Crawlbase
+  # Resolves Crawlbase status from response headers or JSON bodies.
+  # Prefers +cb_status+, falling back to deprecated +pc_status+.
+  module StatusResolution
+    PC_STATUS_DEPRECATION =
+      '[Crawlbase] `pc_status` is deprecated and will be removed in a future major release. Use `cb_status` instead.'
+
+    module_function
+
+    def resolve_cb_status(source)
+      raw = source['cb_status']
+      raw = source['pc_status'] if raw.nil? || raw.to_s.empty?
+      raw.to_i
+    end
+
+    def warn_pc_status_deprecated
+      return if Crawlbase.instance_variable_get(:@pc_status_deprecation_warned)
+
+      Crawlbase.instance_variable_set(:@pc_status_deprecation_warned, true)
+      warn PC_STATUS_DEPRECATION, uplevel: 1
+    end
+  end
+end

data/lib/crawlbase/storage_api.rb

@@ -6,7 +6,10 @@ require 'uri'
 
 module Crawlbase
   class StorageAPI
-    attr_reader :token, :original_status, :pc_status, :url, :status_code, :rid, :body, :stored_at
+    attr_reader :token, :original_status, :url, :status_code, :rid, :body, :stored_at
+
+    # Crawlbase status from the response (preferred name for former +pc_status+).
+    attr_reader :cb_status
 
     INVALID_TOKEN = 'Token is required'
     INVALID_RID = 'RID is required'
@@ -20,6 +23,12 @@ module Crawlbase
       @token = options[:token]
     end
 
+    # Deprecated: use {#cb_status}. Returns the same resolved Crawlbase status.
+    def pc_status
+      StatusResolution.warn_pc_status_deprecated
+      @pc_status
+    end
+
     def get(url_or_rid, format = 'html')
       raise INVALID_URL_OR_RID if url_or_rid.nil? || url_or_rid.empty?
 
@@ -30,7 +39,8 @@ module Crawlbase
       res = format == 'json' ? JSON.parse(response.body) : response
 
       @original_status = res['original_status'].to_i
-      @pc_status = res['pc_status'].to_i
+      @cb_status = StatusResolution.resolve_cb_status(res)
+      @pc_status = @cb_status
       @url = res['url']
       @rid = res['rid']
       @stored_at = res['stored_at']
@@ -50,7 +60,7 @@ module Crawlbase
       request = Net::HTTP::Delete.new(uri.request_uri)
       response = http.request(request)
 
-      @url, @original_status, @pc_status, @stored_at = nil
+      @url, @original_status, @cb_status, @pc_status, @stored_at = nil
       @status_code = response.code.to_i
       @rid = rid
       @body = JSON.parse(response.body)
@@ -71,7 +81,8 @@ module Crawlbase
       @body = JSON.parse(response.body)
       @original_status = @body.map { |item| item['original_status'].to_i }
       @status_code = response.code.to_i
-      @pc_status = @body.map { |item| item['pc_status'].to_i }
+      @cb_status = @body.map { |item| StatusResolution.resolve_cb_status(item) }
+      @pc_status = @cb_status
       @url = @body.map { |item| item['url'] }
       @rid = @body.map { |item| item['rid'] }
       @stored_at = @body.map { |item| item['stored_at'] }
@@ -86,7 +97,7 @@ module Crawlbase
       uri.query = URI.encode_www_form(query_hash)
 
       response = Net::HTTP.get_response(uri)
-      @url, @original_status, @pc_status, @stored_at = nil
+      @url, @original_status, @cb_status, @pc_status, @stored_at = nil
       @status_code = response.code.to_i
       @body = JSON.parse(response.body)
       @rid = @body
@@ -99,7 +110,7 @@ module Crawlbase
       uri.query = URI.encode_www_form(token: token)
 
       response = Net::HTTP.get_response(uri)
-      @url, @original_status, @pc_status, @stored_at = nil
+      @url, @original_status, @cb_status, @pc_status, @stored_at = nil
       @status_code = response.code.to_i
       @rid = rid
       @body = JSON.parse(response.body)

data/lib/crawlbase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crawlbase
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/lib/crawlbase.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'crawlbase/version'
+require 'crawlbase/status_resolution'
 require 'crawlbase/api'
 require 'crawlbase/scraper_api'
 require 'crawlbase/leads_api'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: crawlbase
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - crawlbase
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-25 00:00:00.000000000 Z
+date: 2026-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -89,6 +89,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -102,6 +103,7 @@ files:
 - lib/crawlbase/leads_api.rb
 - lib/crawlbase/scraper_api.rb
 - lib/crawlbase/screenshots_api.rb
+- lib/crawlbase/status_resolution.rb
 - lib/crawlbase/storage_api.rb
 - lib/crawlbase/version.rb
 homepage: https://github.com/crawlbase-source/crawlbase-ruby
@@ -123,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.0.dev
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Crawlbase API client for web scraping and crawling