crawlora 1.5.0.pre.sdk.2 → 1.6.0.pre.sdk.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5df185ab17cbdb8ee244385b900049f2209efe980e1a672f39a7f61d18bfd35
-  data.tar.gz: af839794521c83c882affd859e4929ec76225144e45bb3f29141795b0fbb9b69
+  metadata.gz: '06503911970d596c0e191164b365247bde58a78ce2cd840c0ff18492b9d1cc6b'
+  data.tar.gz: bf80854532f824cf8ce73881ed7c978fcd81073f178505f91e3723179ff6b7aa
 SHA512:
-  metadata.gz: ffd5f36fde004299e22e4f07d4c19e9904032d0ff78ee7c9a57b9d4d49964a2fba2fc0e7e14f412e9814b1c64e3d599c63259b69a6173dfbf50a71414354bd87
-  data.tar.gz: 2d529c261a355e69021267c41f520db47c0a8a399d107108ba08d3fe839158ef6929ef88986c6205592a144980a2f977af4eceeb42fa20ee2a2eb74568232874
+  metadata.gz: 14ee5fee236698951fa031eb8d86469fc481b27f18394d9dbffb6ba40301229f3a9a1806f2323c0576945e906cd961cb1a9576333b064354f497d7a5e52fc3c5
+  data.tar.gz: 9cad2508981712b0146393781dcbad62a28ab93ef17fae77f0159f97f4fef8c96ccc93aa2adcfa8bc8ed3ca9f00861ac3acf41b9bb1c3e8bcabd51e2d8ed755c

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.6.0-sdk.1
+
+- Added the **Reddit** platform (`reddit.search`, `reddit.post`,
+  `reddit.comments`, `reddit.subreddit_posts`) and the **Brand** platform
+  (`brand.retrieve`), plus Yahoo Finance `yahoo_finance.lookup`. Regenerated from
+  the public API contract.
+
+## 1.5.0-sdk.3
+
+- Richer RBS: generated `sig/crawlora.rbs` now declares typed keyword parameters
+  per operation (Steep/Sorbet users get real signatures instead of `**untyped`).
+- Internal cleanups: split the request and pagination methods into focused
+  private helpers, enabled tuned rubocop metric budgets, and hardened multipart
+  `Content-Disposition` field/filename escaping. No public API changes.
+
 ## 1.5.0-sdk.2
 
 - Packaging: point the gem homepage at https://crawlora.net/, expand the gem

data/README.md

@@ -11,13 +11,17 @@ plus retries, pagination, middleware hooks, and client-side rate limiting.
 
 ## Install
 
+Published on [RubyGems](https://rubygems.org/gems/crawlora). The current release
+is a prerelease (`1.5.0.pre.sdk.3`), so install it with `--pre` or pin the
+version:
+
 ```ruby
 # Gemfile
-gem "crawlora"
+gem "crawlora", "1.5.0.pre.sdk.3"
 ```
 
 ```sh
-gem install crawlora
+gem install crawlora --pre
 ```
 
 ## Quick start

data/docs/operations.md

@@ -2,7 +2,7 @@
 
 Generated from `openapi/public.json`. Deprecated, admin, and internal operations are excluded from this SDK contract.
 
-Total operations: `330`
+Total operations: `336`
 
 | Group | SDK method | Operation ID | HTTP | Params | Auth | Response | Notes |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -41,6 +41,7 @@ Total operations: `330`
 | bing | `bing.search` | `bing-search` | `GET /bing/search` | `q` (query String required)<br>`page` (query Integer)<br>`count` (query Integer)<br>`country` (query String)<br>`lang` (query String) | `ApiKeyAuth` | `BingSearchResponse` |  |
 | bing | `bing.suggest` | `bing-suggest` | `GET /bing/suggest` | `q` (query String required)<br>`count` (query Integer)<br>`country` (query String)<br>`lang` (query String) | `ApiKeyAuth` | `BingSuggestResponse` |  |
 | bing | `bing.videos` | `bing-videos` | `GET /bing/videos` | `q` (query String required)<br>`page` (query Integer)<br>`count` (query Integer)<br>`country` (query String)<br>`lang` (query String) | `ApiKeyAuth` | `BingVideosResponse` |  |
+| brand | `brand.retrieve` | `brand-retrieve` | `GET /brand/retrieve` | `domain` (query String required)<br>`force_language` (query String)<br>`maxSpeed` (query bool)<br>`maxAgeMs` (query Integer)<br>`timeoutMS` (query Integer) | `ApiKeyAuth` | `BrandRetrieveResponse` |  |
 | brave | `brave.images` | `brave-images` | `GET /brave/images` | `q` (query String required)<br>`offset` (query Integer)<br>`count` (query Integer)<br>`country` (query "all" \| "ar" \| "at" \| "au" \| "be" \| "br" \| "ca" \| "ch" \| "cl" \| "cn" \| "de" \| "dk" \| "es" \| "fi" \| "fr" \| "gb" \| "gr" \| "hk" \| "id" \| "in" \| "it" \| "jp" \| "kr" \| "mx" \| "my" \| "nl" \| "no" \| "nz" \| "ph" \| "pl" \| "pt" \| "ru" \| "sa" \| "se" \| "sg" \| "tr" \| "tw" \| "us" \| "za")<br>`lang` (query "de-de" \| "en-ca" \| "en-gb" \| "en-in" \| "en-us" \| "fi-fi" \| "fr-ca" \| "fr-fr" \| "ja-jp" \| "pt-br" \| "sq-al" \| "sw-ke" \| "zh-tw") | `ApiKeyAuth` | `BraveImagesResponse` |  |
 | brave | `brave.news` | `brave-news` | `GET /brave/news` | `q` (query String required)<br>`offset` (query Integer)<br>`count` (query Integer)<br>`country` (query "all" \| "ar" \| "at" \| "au" \| "be" \| "br" \| "ca" \| "ch" \| "cl" \| "cn" \| "de" \| "dk" \| "es" \| "fi" \| "fr" \| "gb" \| "gr" \| "hk" \| "id" \| "in" \| "it" \| "jp" \| "kr" \| "mx" \| "my" \| "nl" \| "no" \| "nz" \| "ph" \| "pl" \| "pt" \| "ru" \| "sa" \| "se" \| "sg" \| "tr" \| "tw" \| "us" \| "za")<br>`lang` (query "de-de" \| "en-ca" \| "en-gb" \| "en-in" \| "en-us" \| "fi-fi" \| "fr-ca" \| "fr-fr" \| "ja-jp" \| "pt-br" \| "sq-al" \| "sw-ke" \| "zh-tw")<br>`time_range` (query "any" \| "day" \| "week" \| "month" \| "year" \| "custom")<br>`date_from` (query String)<br>`date_to` (query String) | `ApiKeyAuth` | `BraveNewsResponse` |  |
 | brave | `brave.search` | `brave-search` | `GET /brave/search` | `q` (query String required)<br>`offset` (query Integer)<br>`country` (query "all" \| "ar" \| "at" \| "au" \| "be" \| "br" \| "ca" \| "ch" \| "cl" \| "cn" \| "de" \| "dk" \| "es" \| "fi" \| "fr" \| "gb" \| "gr" \| "hk" \| "id" \| "in" \| "it" \| "jp" \| "kr" \| "mx" \| "my" \| "nl" \| "no" \| "nz" \| "ph" \| "pl" \| "pt" \| "ru" \| "sa" \| "se" \| "sg" \| "tr" \| "tw" \| "us" \| "za")<br>`lang` (query "de-de" \| "en-ca" \| "en-gb" \| "en-in" \| "en-us" \| "fi-fi" \| "fr-ca" \| "fr-fr" \| "ja-jp" \| "pt-br" \| "sq-al" \| "sw-ke" \| "zh-tw")<br>`time_range` (query "any" \| "day" \| "week" \| "month" \| "year" \| "custom")<br>`date_from` (query String)<br>`date_to` (query String) | `ApiKeyAuth` | `BraveSearchResponse` |  |
@@ -167,6 +168,10 @@ Total operations: `330`
 | product_hunt | `product_hunt.makers` | `producthunt-makers` | `GET /producthunt/product/{id}/makers` | `id` (path String required)<br>`cursor` (query String) | `ApiKeyAuth` | `ProductHuntMakersResponse` |  |
 | product_hunt | `product_hunt.reviews` | `producthunt-reviews` | `GET /producthunt/product/{id}/reviews` | `id` (path String required) | `ApiKeyAuth` | `ProductHuntReviewsResponse` |  |
 | product_hunt | `product_hunt.search` | `producthunt-search` | `GET /producthunt/search` | `query` (query String required)<br>`type` (query "product" \| "user" \| "launch")<br>`page` (query Integer)<br>`featured` (query bool)<br>`topics` (query String) | `ApiKeyAuth` | `ProductHuntSearchResponse` |  |
+| reddit | `reddit.comments` | `reddit-comments` | `GET /reddit/comments/{id}` | `id` (path String required)<br>`sort` (query "confidence" \| "top" \| "new" \| "controversial" \| "old" \| "qa")<br>`limit` (query Integer)<br>`depth` (query Integer) | `ApiKeyAuth` | `RedditCommentsResponse` |  |
+| reddit | `reddit.post` | `reddit-post` | `GET /reddit/post/{id}` | `id` (path String required) | `ApiKeyAuth` | `RedditPostResponse` |  |
+| reddit | `reddit.search` | `reddit-search` | `GET /reddit/search` | `q` (query String required)<br>`subreddit` (query String)<br>`sort` (query "relevance" \| "hot" \| "new" \| "top" \| "comments")<br>`time` (query "hour" \| "day" \| "week" \| "month" \| "year" \| "all")<br>`limit` (query Integer)<br>`after` (query String) | `ApiKeyAuth` | `RedditSearchResponse` |  |
+| reddit | `reddit.subreddit_posts` | `reddit-subreddit-posts` | `GET /reddit/subreddit/{subreddit}/posts` | `subreddit` (path String required)<br>`sort` (query "hot" \| "new" \| "top" \| "rising")<br>`time` (query "hour" \| "day" \| "week" \| "month" \| "year" \| "all")<br>`limit` (query Integer)<br>`after` (query String) | `ApiKeyAuth` | `RedditSubredditPostsResponse` |  |
 | referrals | `referrals.click` | `referrals-click` | `POST /referrals/click` | `request` (body String required) | none | `ReferralsClickResponse` |  |
 | referrals | `referrals.me` | `referrals-me` | `GET /referrals/me` | none | `JWTAuth` | `ReferralsMeResponse` |  |
 | referrals | `referrals.me_events` | `referrals-me-events` | `GET /referrals/me/events` | `limit` (query Integer) | `JWTAuth` | `ReferralsMeEventsResponse` |  |
@@ -274,10 +279,10 @@ Total operations: `330`
 | trustpilot | `trustpilot.categories` | `trustpilot-categories` | `GET /trustpilot/categories` | none | `ApiKeyAuth` | `TrustpilotCategoriesResponse` |  |
 | trustpilot | `trustpilot.category_search` | `trustpilot-category-search` | `GET /trustpilot/categories/search` | `q` (query String required)<br>`country` (query String)<br>`locale` (query String)<br>`size` (query Integer) | `ApiKeyAuth` | `TrustpilotCategorySearchResponse` |  |
 | trustpilot | `trustpilot.category` | `trustpilot-category` | `GET /trustpilot/category/{slug}` | `slug` (path String required)<br>`page` (query Integer) | `ApiKeyAuth` | `TrustpilotCategoryResponse` |  |
-| usage | `usage.me_endpoints` | `usage-me-endpoints` | `GET /usage/me/endpoints` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`limit` (query Integer)<br>`from` (query String)<br>`to` (query String) | `JWTAuth` | `UsageMeEndpointsResponse` |  |
-| usage | `usage.me_overview` | `usage-me-overview` | `GET /usage/me/overview` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`from` (query String)<br>`to` (query String) | `JWTAuth` | `UsageMeOverviewResponse` |  |
-| usage | `usage.me_recent_ips` | `usage-me-recent-ips` | `GET /usage/me/recent-ips` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`limit` (query Integer)<br>`from` (query String)<br>`to` (query String) | `JWTAuth` | `UsageMeRecentIpsResponse` |  |
-| usage | `usage.me_timeseries` | `usage-me-timeseries` | `GET /usage/me/timeseries` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`bucket` (query "hour" \| "day")<br>`endpoint` (query String)<br>`from` (query String)<br>`to` (query String) | `JWTAuth` | `UsageMeTimeseriesResponse` |  |
+| usage | `usage.me_endpoints` | `usage-me-endpoints` | `GET /usage/me/endpoints` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`limit` (query Integer)<br>`from` (query String)<br>`to` (query String) | `ApiKeyAuth` | `UsageMeEndpointsResponse` |  |
+| usage | `usage.me_overview` | `usage-me-overview` | `GET /usage/me/overview` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`from` (query String)<br>`to` (query String) | `ApiKeyAuth` | `UsageMeOverviewResponse` |  |
+| usage | `usage.me_recent_ips` | `usage-me-recent-ips` | `GET /usage/me/recent-ips` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`limit` (query Integer)<br>`from` (query String)<br>`to` (query String) | `ApiKeyAuth` | `UsageMeRecentIpsResponse` |  |
+| usage | `usage.me_timeseries` | `usage-me-timeseries` | `GET /usage/me/timeseries` | `range` (query "period" \| "day" \| "week" \| "month" \| "custom")<br>`bucket` (query "hour" \| "day")<br>`endpoint` (query String)<br>`from` (query String)<br>`to` (query String) | `ApiKeyAuth` | `UsageMeTimeseriesResponse` |  |
 | user | `user.me` | `user-me` | `GET /user/me` | none | `JWTAuth` | `UserMeResponse` |  |
 | user | `user.me_api_keys` | `user-me-api-keys` | `GET /user/me/api-keys` | none | `JWTAuth` | `UserMeApiKeysResponse` |  |
 | user | `user.me_api_keys_rotate` | `user-me-api-keys-rotate` | `POST /user/me/api-keys/rotate` | none | `JWTAuth` | `UserMeApiKeysRotateResponse` |  |
@@ -287,6 +292,7 @@ Total operations: `330`
 | yahoo_finance | `yahoo_finance.download` | `yahoo-finance-download` | `POST /yahoo-finance/download` | `request` (body String required) | `ApiKeyAuth` | `YahooFinanceDownloadResponse` |  |
 | yahoo_finance | `yahoo_finance.industries` | `yahoo-finance-industries` | `GET /yahoo-finance/industries` | none | `ApiKeyAuth` | `YahooFinanceIndustriesResponse` |  |
 | yahoo_finance | `yahoo_finance.industry` | `yahoo-finance-industry` | `GET /yahoo-finance/industries/{key}` | `key` (path String required) | `ApiKeyAuth` | `YahooFinanceIndustryResponse` |  |
+| yahoo_finance | `yahoo_finance.lookup` | `yahoo-finance-lookup` | `GET /yahoo-finance/lookup` | `query` (query String required)<br>`type` (query "all" \| "equity" \| "etf" \| "mutualfund" \| "index" \| "future" \| "currency" \| "cryptocurrency")<br>`count` (query Integer)<br>`start` (query Integer) | `ApiKeyAuth` | `YahooFinanceLookupResponse` |  |
 | yahoo_finance | `yahoo_finance.market_status` | `yahoo-finance-market-status` | `GET /yahoo-finance/market/{market}/status` | `market` (path String required) | `ApiKeyAuth` | `YahooFinanceMarketStatusResponse` |  |
 | yahoo_finance | `yahoo_finance.market_summary` | `yahoo-finance-market-summary` | `GET /yahoo-finance/market/{market}/summary` | `market` (path String required) | `ApiKeyAuth` | `YahooFinanceMarketSummaryResponse` |  |
 | yahoo_finance | `yahoo_finance.screener_custom` | `yahoo-finance-screener-custom` | `POST /yahoo-finance/screener` | `request` (body String required) | `ApiKeyAuth` | `YahooFinanceScreenerCustomResponse` |  |

data/docs/recipes.md

@@ -17,6 +17,15 @@ Crawlora.client(jwt_token: "eyJ…")
 Both fall back to environment variables: `CRAWLORA_API_KEY` and
 `CRAWLORA_BASE_URL`.
 
+## Reddit and Brand
+
+Newer platforms are grouped like every other endpoint:
+
+```ruby
+posts = client.reddit.search(q: "ruby", subreddit: "programming")
+brand = client.brand.retrieve(domain: "stripe.com")
+```
+
 ## Retries and Retry-After
 
 ```ruby

data/lib/crawlora/client.rb

@@ -167,7 +167,7 @@ module Crawlora
       @on_retry = on_retry
       @request_id = request_id
       @idempotency_keys = idempotency_keys
-      @rate_limiter = rate_limit || max_concurrency ? RateLimiter.new(rate_limit, max_concurrency) : nil
+      @rate_limiter = (rate_limit || max_concurrency) ? RateLimiter.new(rate_limit, max_concurrency) : nil
       @logger = logger
       @before_request = as_hook_list(before_request)
       @after_response = as_hook_list(after_response)
@@ -200,7 +200,7 @@ module Crawlora
       log(event: "request", operation: operation_id)
       max_retries = retries.nil? ? @retries : [0, retries.to_i].max
       idempotency_key =
-        @idempotency_keys && %w[POST PATCH].include?(operation["method"]) ? SecureRandom.hex(16) : nil
+        (@idempotency_keys && %w[POST PATCH].include?(operation["method"])) ? SecureRandom.hex(16) : nil
 
       attempt = 0
       loop do
@@ -225,8 +225,8 @@ module Crawlora
     # +next_cursor+ extractor) sends the cursor parameter and stops when
     # +next_cursor+ returns a falsy value.
     def paginate(operation_id, params = {}, page_param: nil, cursor_param: nil, next_cursor: nil,
-                 start: nil, step: 1, max_pages: nil, response_type: "auto", timeout: nil, headers: nil)
-      unless block_given?
+                 start: nil, step: 1, max_pages: nil, response_type: "auto", timeout: nil, headers: nil, &block)
+      unless block
         return enum_for(:paginate, operation_id, params, page_param: page_param, cursor_param: cursor_param,
                                                          next_cursor: next_cursor, start: start, step: step, max_pages: max_pages,
                                                          response_type: response_type, timeout: timeout, headers: headers)
@@ -236,29 +236,56 @@ module Crawlora
       raise ArgumentError, "unknown Crawlora operation: #{operation_id}" if operation.nil?
 
       base_params = stringify_keys(params)
+      opts = { response_type: response_type, timeout: timeout, headers: headers }
 
       if cursor_param || next_cursor
-        raise ArgumentError, "cursor pagination requires both cursor_param and next_cursor" unless cursor_param && next_cursor
+        paginate_cursor(operation_id, operation, base_params, cursor_param: cursor_param, next_cursor: next_cursor,
+                                                              start: start, max_pages: max_pages, opts: opts, &block)
+      else
+        paginate_numeric(operation_id, operation, base_params, page_param: page_param, start: start, step: step,
+                                                               max_pages: max_pages, opts: opts, &block)
+      end
+    end
 
-        query_names = (operation["queryParams"] || []).map { |p| p["name"] }
-        unless query_names.include?(cursor_param)
-          raise ArgumentError, "cursor_param #{cursor_param.inspect} is not a query parameter of operation #{operation_id}"
-        end
+    # Yield individual items across pages. +items+ extracts the list from a page
+    # (default: the Crawlora +data+ array).
+    def paginate_items(operation_id, params = {}, items: nil, **options, &block)
+      return enum_for(:paginate_items, operation_id, params, items: items, **options) unless block_given?
 
-        cursor = start
-        fetched = 0
-        while max_pages.nil? || fetched < max_pages
-          page_params = base_params.dup
-          page_params[cursor_param] = cursor unless cursor.nil?
-          response = request(operation_id, page_params, response_type: response_type, timeout: timeout, headers: headers)
-          yield response
-          fetched += 1
-          cursor = next_cursor.call(response)
-          break unless cursor && !(cursor.respond_to?(:empty?) && cursor.empty?)
-        end
-        return
+      extract = items || Pagination.method(:default_items)
+      paginate(operation_id, params, **options) do |page|
+        extract.call(page).each(&block)
+      end
+    end
+
+    private
+
+    # Yield successive pages by advancing a cursor query parameter until
+    # +next_cursor+ returns a blank value.
+    def paginate_cursor(operation_id, operation, base_params, cursor_param:, next_cursor:, start:, max_pages:, opts:)
+      raise ArgumentError, "cursor pagination requires both cursor_param and next_cursor" unless cursor_param && next_cursor
+
+      query_names = (operation["queryParams"] || []).map { |p| p["name"] }
+      unless query_names.include?(cursor_param)
+        raise ArgumentError, "cursor_param #{cursor_param.inspect} is not a query parameter of operation #{operation_id}"
+      end
+
+      cursor = start
+      fetched = 0
+      while max_pages.nil? || fetched < max_pages
+        page_params = base_params.dup
+        page_params[cursor_param] = cursor unless cursor.nil?
+        response = request(operation_id, page_params, **opts)
+        yield response
+        fetched += 1
+        cursor = next_cursor.call(response)
+        break unless cursor && !(cursor.respond_to?(:empty?) && cursor.empty?)
       end
+    end
 
+    # Yield successive pages by advancing the page/offset query parameter until
+    # a page comes back empty.
+    def paginate_numeric(operation_id, operation, base_params, page_param:, start:, step:, max_pages:, opts:)
       page_param ||= Pagination.detect_page_param(operation)
       raise ArgumentError, "operation #{operation_id} has no page or offset query parameter to paginate" unless page_param
 
@@ -266,7 +293,7 @@ module Crawlora
       fetched = 0
       while max_pages.nil? || fetched < max_pages
         page_params = base_params.merge(page_param => page_value)
-        response = request(operation_id, page_params, response_type: response_type, timeout: timeout, headers: headers)
+        response = request(operation_id, page_params, **opts)
         yield response
         fetched += 1
         break if Pagination.page_empty?(response)
@@ -275,21 +302,30 @@ module Crawlora
       end
     end
 
-    # Yield individual items across pages. +items+ extracts the list from a page
-    # (default: the Crawlora +data+ array).
-    def paginate_items(operation_id, params = {}, items: nil, **options, &block)
-      return enum_for(:paginate_items, operation_id, params, items: items, **options) unless block_given?
+    def send_request(operation, params, response_type:, timeout:, headers:, idempotency_key: nil)
+      url, body, body_headers = build_request(@base_url, operation, params)
+      request_headers, req_id = prepare_request(operation, body_headers, headers, idempotency_key)
+      unless @before_request.empty?
+        ctx = { operation: operation["id"], method: operation["method"], url: url, headers: request_headers }
+        @before_request.each { |hook| hook.call(ctx) }
+        url = ctx[:url]
+        request_headers = ctx[:headers]
+      end
 
-      extract = items || Pagination.method(:default_items)
-      paginate(operation_id, params, **options) do |page|
-        extract.call(page).each(&block)
+      request_timeout = timeout.nil? ? @timeout : timeout
+      begin
+        response = call_transport(method: operation["method"], url: url, headers: request_headers, body: body, timeout: request_timeout)
+      rescue StandardError => e
+        message = timeout_error?(e) ? "Crawlora request timed out" : "Crawlora transport error"
+        raise NetworkError.new(message, request_id: req_id, cause: e)
       end
-    end
 
-    private
+      handle_response(operation, response, response_type, req_id)
+    end
 
-    def send_request(operation, params, response_type:, timeout:, headers:, idempotency_key: nil)
-      url, body, body_headers = build_request(@base_url, operation, params)
+    # Build the merged request headers and resolve the request id, attaching an
+    # idempotency key when one was generated.
+    def prepare_request(operation, body_headers, headers, idempotency_key)
       request_headers = merge_headers(
         @headers,
         auth_headers(operation["security"] || [], @api_key, @jwt_token),
@@ -301,53 +337,47 @@ module Crawlora
         if @request_id
           ensure_request_id(request_headers)
         else
-          v = header_value(request_headers, "x-request-id")
-          v.empty? ? nil : v
+          existing = header_value(request_headers, "x-request-id")
+          existing.empty? ? nil : existing
         end
       request_headers["Idempotency-Key"] = idempotency_key if idempotency_key && header_value(request_headers, "idempotency-key").empty?
-      unless @before_request.empty?
-        ctx = { operation: operation["id"], method: operation["method"], url: url, headers: request_headers }
-        @before_request.each { |hook| hook.call(ctx) }
-        url = ctx[:url]
-        request_headers = ctx[:headers]
-      end
+      [request_headers, req_id]
+    end
 
-      request_timeout = timeout.nil? ? @timeout : timeout
-      begin
-        response =
-          if @rate_limiter
-            @rate_limiter.run do
-              @transport.call(method: operation["method"], url: url, headers: request_headers, body: body, timeout: request_timeout)
-            end
-          else
-            @transport.call(method: operation["method"], url: url, headers: request_headers, body: body, timeout: request_timeout)
-          end
-      rescue StandardError => e
-        message = timeout_error?(e) ? "Crawlora request timed out" : "Crawlora transport error"
-        raise NetworkError.new(message, request_id: req_id, cause: e)
-      end
+    def call_transport(method:, url:, headers:, body:, timeout:)
+      call = -> { @transport.call(method: method, url: url, headers: headers, body: body, timeout: timeout) }
+      @rate_limiter ? @rate_limiter.run(&call) : call.call
+    end
 
+    # Parse the response, raise the typed API error on non-2xx, and run the
+    # after_response hooks on success.
+    def handle_response(operation, response, response_type, req_id)
       raw_body = response.body.to_s
       is_error = response.status < 200 || response.status >= 300
-      return StringIO.new(response.body.to_s) if response_type == "stream" && !is_error
+      return StringIO.new(raw_body) if response_type == "stream" && !is_error
 
-      parse_mode = response_type == "stream" ? "auto" : response_type
+      parse_mode = (response_type == "stream") ? "auto" : response_type
       begin
-        parsed = parse_response(response.body.to_s, header_value(response.headers, "content-type"), parse_mode)
+        parsed = parse_response(raw_body, header_value(response.headers, "content-type"), parse_mode)
       rescue JSON::ParserError => e
         raise Error.new("Crawlora JSON parse error", status: response.status, raw_body: raw_body,
                                                      headers: response.headers, request_id: req_id, cause: e)
       end
 
-      if is_error
-        code = parsed.is_a?(Hash) ? parsed["code"] : nil
-        message = parsed.is_a?(Hash) && parsed["msg"] && !parsed["msg"].to_s.empty? ? parsed["msg"] : "HTTP #{response.status}"
-        raise Crawlora.error_class_for(response.status).new(
-          message, status: response.status, code: code, body: parsed,
-                   raw_body: raw_body, headers: response.headers, request_id: req_id
-        )
-      end
+      raise_api_error(response, parsed, raw_body, req_id) if is_error
+      run_after_response(operation, response, parsed)
+    end
+
+    def raise_api_error(response, parsed, raw_body, req_id)
+      code = parsed.is_a?(Hash) ? parsed["code"] : nil
+      message = (parsed.is_a?(Hash) && parsed["msg"] && !parsed["msg"].to_s.empty?) ? parsed["msg"] : "HTTP #{response.status}"
+      raise Crawlora.error_class_for(response.status).new(
+        message, status: response.status, code: code, body: parsed,
+                 raw_body: raw_body, headers: response.headers, request_id: req_id
+      )
+    end
 
+    def run_after_response(operation, response, parsed)
       @after_response.each do |hook|
         result = hook.call(operation["id"], response.status, response.headers, parsed)
         parsed = result unless result.nil?
@@ -476,18 +506,23 @@ module Crawlora
         chunks << "--#{boundary}\r\n"
         if parameter["type"] == "file"
           filename, data = read_file_value(value)
-          chunks << %(Content-Disposition: form-data; name="#{name}"; filename="#{filename}"\r\n)
+          chunks << %(Content-Disposition: form-data; name="#{quote_escape(name)}"; filename="#{quote_escape(filename)}"\r\n)
           chunks << "Content-Type: application/octet-stream\r\n\r\n"
           chunks << data
           chunks << "\r\n"
         else
-          chunks << %(Content-Disposition: form-data; name="#{name}"\r\n\r\n#{value}\r\n)
+          chunks << %(Content-Disposition: form-data; name="#{quote_escape(name)}"\r\n\r\n#{value}\r\n)
         end
       end
       chunks << "--#{boundary}--\r\n"
       [chunks, { "content-type" => "multipart/form-data; boundary=#{boundary}" }]
     end
 
+    # Escape characters that would break a multipart Content-Disposition header.
+    def quote_escape(value)
+      value.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"').gsub(/[\r\n]/, " ")
+    end
+
     def read_file_value(value)
       return ["upload.bin", value] if value.is_a?(String) && !File.exist?(value)
       return [File.basename(value), File.binread(value)] if value.is_a?(String)