hookbridge 1.0.0 → 1.3.0

data/lib/hookbridge/client.rb

@@ -5,93 +5,64 @@ require "faraday/retry"
 require "json"
 
 module HookBridge
-  # Main client for interacting with the HookBridge API
   class Client
     DEFAULT_BASE_URL = "https://api.hookbridge.io"
+    DEFAULT_SEND_URL = "https://send.hookbridge.io"
     DEFAULT_TIMEOUT = 30
     DEFAULT_RETRIES = 3
 
-    attr_reader :api_key, :base_url, :timeout, :retries
+    attr_reader :api_key, :base_url, :send_url, :timeout, :retries
 
-    # Initialize a new HookBridge client
-    #
-    # @param api_key [String] Your HookBridge API key (starts with hb_live_ or hb_test_)
-    # @param base_url [String] API base URL (defaults to https://api.hookbridge.io)
-    # @param timeout [Integer] Request timeout in seconds (defaults to 30)
-    # @param retries [Integer] Number of retries for failed requests (defaults to 3)
-    def initialize(api_key:, base_url: nil, timeout: DEFAULT_TIMEOUT, retries: DEFAULT_RETRIES)
+    def initialize(api_key:, base_url: nil, send_url: nil, timeout: DEFAULT_TIMEOUT, retries: DEFAULT_RETRIES)
       raise ValidationError, "API key is required" if api_key.nil? || api_key.empty?
 
       @api_key = api_key
       @base_url = (base_url || ENV.fetch("HOOKBRIDGE_BASE_URL", DEFAULT_BASE_URL)).chomp("/")
+      @send_url = (send_url || ENV.fetch("HOOKBRIDGE_SEND_URL", DEFAULT_SEND_URL)).chomp("/")
       @timeout = timeout
       @retries = retries
-      @connection = build_connection
-    end
-
-    # Send a webhook for guaranteed delivery
-    #
-    # @param endpoint [String] The registered endpoint identifier
-    # @param payload [Hash, String] The webhook payload
-    # @param idempotency_key [String, nil] Optional idempotency key to prevent duplicates
-    # @param content_type [String] Content type of the payload (defaults to application/json)
-    # @return [SendResponse] The send response with message_id and status
-    def send(endpoint:, payload:, idempotency_key: nil, content_type: "application/json")
-      body = {
-        endpoint: endpoint,
-        payload: payload,
-        content_type: content_type
-      }
-      body[:idempotency_key] = idempotency_key if idempotency_key
+      @connection = build_connection(@base_url)
+      @send_connection = build_connection(@send_url)
+    end
 
-      data = request(:post, "/v1/webhooks/send", body)
-      SendResponse.new(data)
+    def send(endpoint_id:, payload:, headers: nil, idempotency_key: nil)
+      body = { endpoint_id: endpoint_id, payload: payload }
+      body[:headers] = headers if headers
+      body[:idempotency_key] = idempotency_key if idempotency_key
+      SendResponse.new(extract_data(request(:post, "/v1/webhooks/send", body, use_send_connection: true)))
     end
 
-    # Get detailed status for a specific message
-    #
-    # @param message_id [String] The message ID (UUIDv7)
-    # @return [Message] The message details
     def get_message(message_id)
-      data = request(:get, "/v1/messages/#{message_id}")
-      Message.new(data)
+      Message.new(extract_data(request(:get, "/v1/messages/#{message_id}")))
     end
 
-    # Manually replay a failed message
-    #
-    # @param message_id [String] The message ID to replay
-    # @return [ReplayResponse] The replay response
     def replay(message_id)
-      data = request(:post, "/v1/messages/#{message_id}/replay")
-      ReplayResponse.new(data)
+      ReplayResponse.new(extract_data(request(:post, "/v1/messages/#{message_id}/replay")))
     end
 
-    # Cancel a pending retry
-    #
-    # @param message_id [String] The message ID
-    # @return [Message] The updated message
     def cancel_retry(message_id)
-      data = request(:post, "/v1/messages/#{message_id}/cancel")
-      Message.new(data)
+      request(:post, "/v1/messages/#{message_id}/cancel")
+      nil
     end
 
-    # Trigger immediate retry for a pending message
-    #
-    # @param message_id [String] The message ID
-    # @return [Message] The updated message
     def retry_now(message_id)
-      data = request(:post, "/v1/messages/#{message_id}/retry-now")
-      Message.new(data)
-    end
-
-    # Query delivery logs with optional filtering
-    #
-    # @param status [String, nil] Filter by message status
-    # @param start_time [Time, String, nil] Filter by start time
-    # @param end_time [Time, String, nil] Filter by end time
-    # @param limit [Integer, nil] Maximum number of results (default 50, max 100)
-    # @param cursor [String, nil] Pagination cursor from previous response
-    # @return [LogsResponse] Paginated list of message summaries
+      request(:post, "/v1/messages/#{message_id}/retry-now")
+      nil
+    end
+
+    def replay_all_messages(status:, endpoint_id: nil, limit: nil)
+      params = { status: status }
+      params[:endpoint_id] = endpoint_id if endpoint_id
+      params[:limit] = limit if limit
+      ReplayAllMessagesResponse.new(extract_data(request(:post, "/v1/messages/replay-all", nil, params)))
+    end
+
+    def replay_batch_messages(message_ids)
+      ReplayBatchMessagesResponse.new(
+        extract_data(request(:post, "/v1/messages/replay-batch", { message_ids: message_ids }))
+      )
+    end
+
     def get_logs(status: nil, start_time: nil, end_time: nil, limit: nil, cursor: nil)
       params = {}
       params[:status] = status if status
@@ -99,200 +70,414 @@ module HookBridge
       params[:end_time] = format_time(end_time) if end_time
       params[:limit] = limit if limit
       params[:cursor] = cursor if cursor
-
-      data = request(:get, "/v1/logs", nil, params)
-      LogsResponse.new(data)
+      response = request(:get, "/v1/logs", nil, params)
+      LogsResponse.new(
+        "data" => extract_data(response),
+        "has_more" => extract_meta(response)["has_more"] || response["has_more"],
+        "next_cursor" => extract_meta(response)["next_cursor"] || response["next_cursor"]
+      )
     end
 
-    # Retrieve aggregated delivery metrics
-    #
-    # @param window [String] Time window: "1h", "24h", "7d", or "30d"
-    # @return [Metrics] The delivery metrics
     def get_metrics(window: MetricsWindow::TWENTY_FOUR_HOURS)
-      data = request(:get, "/v1/metrics", nil, { window: window })
-      Metrics.new(data)
+      Metrics.new(extract_data(request(:get, "/v1/metrics", nil, { window: window })))
+    end
+
+    def get_timeseries_metrics(window: MetricsWindow::TWENTY_FOUR_HOURS, endpoint_id: nil)
+      params = { window: window }
+      params[:endpoint_id] = endpoint_id if endpoint_id
+      TimeSeriesMetrics.new(extract_data(request(:get, "/v1/metrics/timeseries", nil, params)))
+    end
+
+    def get_subscription
+      Subscription.new(extract_data(request(:get, "/v1/billing/subscription")))
     end
 
-    # List messages in the Dead Letter Queue
-    #
-    # @param limit [Integer, nil] Maximum number of results
-    # @param cursor [String, nil] Pagination cursor
-    # @return [DLQResponse] Paginated list of DLQ messages
     def get_dlq_messages(limit: nil, cursor: nil)
       params = {}
       params[:limit] = limit if limit
       params[:cursor] = cursor if cursor
-
-      data = request(:get, "/v1/dlq/messages", nil, params)
-      DLQResponse.new(data)
+      response = request(:get, "/v1/dlq/messages", nil, params)
+      DLQResponse.new(
+        "data" => extract_data(response),
+        "has_more" => extract_data(response)["has_more"] || response["has_more"],
+        "next_cursor" => extract_data(response)["next_cursor"] || response["next_cursor"]
+      )
     end
 
-    # Replay a message from the Dead Letter Queue
-    #
-    # @param message_id [String] The message ID to replay
-    # @return [ReplayResponse] The replay response
     def replay_from_dlq(message_id)
-      data = request(:post, "/v1/dlq/replay/#{message_id}")
-      ReplayResponse.new(data)
+      ReplayResponse.new(extract_data(request(:post, "/v1/dlq/replay/#{message_id}")))
     end
 
-    # List all API keys for the project
-    #
-    # @return [APIKeysResponse] List of API keys
     def list_api_keys
-      data = request(:get, "/v1/api-keys")
-      APIKeysResponse.new(data)
+      APIKeysResponse.new("data" => extract_data(request(:get, "/v1/api-keys")))
     end
 
-    # Create a new API key
-    #
-    # @param name [String] Name for the API key
-    # @param mode [String] Key mode: "live" or "test"
-    # @return [APIKeyCreated] The created API key (includes full key, only shown once)
     def create_api_key(label: nil, mode: APIKeyMode::LIVE)
       body = { mode: mode }
       body[:label] = label if label
-      data = request(:post, "/v1/api-keys", body)
-      APIKeyCreated.new(data)
+      APIKeyCreated.new(extract_data(request(:post, "/v1/api-keys", body)))
     end
 
-    # Delete an API key
-    #
-    # @param key_id [String] The API key ID to delete
-    # @return [Boolean] true if successful
     def delete_api_key(key_id)
       request(:delete, "/v1/api-keys/#{key_id}")
       true
     end
 
+    def list_projects
+      extract_data(request(:get, "/v1/projects")).map { |project| Project.new(project) }
+    end
+
+    def create_project(name:, rate_limit_default: nil)
+      body = { name: name }
+      body[:rate_limit_default] = rate_limit_default if rate_limit_default
+      Project.new(extract_data(request(:post, "/v1/projects", body)))
+    end
+
+    def get_project(project_id)
+      Project.new(extract_data(request(:get, "/v1/projects/#{project_id}")))
+    end
+
+    def update_project(project_id, name: nil, rate_limit_default: nil)
+      body = {}
+      body[:name] = name if name
+      body[:rate_limit_default] = rate_limit_default if rate_limit_default
+      Project.new(extract_data(request(:put, "/v1/projects/#{project_id}", body)))
+    end
+
+    def delete_project(project_id)
+      request(:delete, "/v1/projects/#{project_id}")
+      true
+    end
+
+    def create_endpoint(url:, description: nil, hmac_enabled: nil, rate_limit_rps: 0, burst: 0, headers: nil)
+      body = { url: url }
+      body[:description] = description if description
+      body[:hmac_enabled] = hmac_enabled unless hmac_enabled.nil?
+      body[:rate_limit_rps] = rate_limit_rps if rate_limit_rps.positive?
+      body[:burst] = burst if burst.positive?
+      body[:headers] = headers if headers
+      CreateEndpointResponse.new(extract_data(request(:post, "/v1/endpoints", body)))
+    end
+
+    def get_endpoint(endpoint_id)
+      Endpoint.new(extract_data(request(:get, "/v1/endpoints/#{endpoint_id}")))
+    end
+
+    def list_endpoints(limit: nil, cursor: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:cursor] = cursor if cursor
+      response = request(:get, "/v1/endpoints", nil, params)
+      ListEndpointsResponse.new(
+        "data" => extract_data(response),
+        "has_more" => extract_meta(response)["has_more"] || response["has_more"],
+        "next_cursor" => extract_meta(response)["next_cursor"] || response["next_cursor"]
+      )
+    end
+
+    def update_endpoint(endpoint_id, url: nil, description: nil, hmac_enabled: nil, rate_limit_rps: nil, burst: nil, headers: nil)
+      body = {}
+      body[:url] = url if url
+      body[:description] = description if description
+      body[:hmac_enabled] = hmac_enabled unless hmac_enabled.nil?
+      body[:rate_limit_rps] = rate_limit_rps if rate_limit_rps
+      body[:burst] = burst if burst
+      body[:headers] = headers if headers
+      request(:patch, "/v1/endpoints/#{endpoint_id}", body)
+      nil
+    end
+
+    def delete_endpoint(endpoint_id)
+      request(:delete, "/v1/endpoints/#{endpoint_id}")
+      true
+    end
+
+    def create_endpoint_signing_key(endpoint_id)
+      RotateSecretResponse.new(extract_data(request(:post, "/v1/endpoints/#{endpoint_id}/signing-keys")))
+    end
+
+    def list_endpoint_signing_keys(endpoint_id)
+      extract_data(request(:get, "/v1/endpoints/#{endpoint_id}/signing-keys")).map do |entry|
+        SigningKey.new(entry)
+      end
+    end
+
+    def delete_endpoint_signing_key(endpoint_id, key_id)
+      request(:delete, "/v1/endpoints/#{endpoint_id}/signing-keys/#{key_id}")
+      true
+    end
+
+    def rotate_endpoint_secret(endpoint_id)
+      create_endpoint_signing_key(endpoint_id)
+    end
+
+    def create_checkout(plan:, interval:)
+      CheckoutSession.new(extract_data(request(:post, "/v1/billing/checkout", { plan: plan, interval: interval })))
+    end
+
+    def create_portal(return_url: nil)
+      body = {}
+      body[:return_url] = return_url if return_url
+      PortalSession.new(extract_data(request(:post, "/v1/billing/portal", body)))
+    end
+
+    def get_usage_history(limit: 12, offset: 0)
+      response = request(:get, "/v1/billing/usage-history", nil, { limit: limit, offset: offset })
+      UsageHistoryResponse.new(extract_data(response), extract_meta(response))
+    end
+
+    def get_invoices(limit: 12, starting_after: nil)
+      params = { limit: limit }
+      params[:starting_after] = starting_after if starting_after
+      response = request(:get, "/v1/billing/invoices", nil, params)
+      InvoicesResponse.new(extract_data(response), extract_meta(response))
+    end
+
+    def create_inbound_endpoint(url:, name: nil, description: nil, verify_static_token: nil, token_header_name: nil, token_query_param: nil, token_value: nil, verify_hmac: nil, hmac_header_name: nil, hmac_secret: nil, timestamp_header_name: nil, timestamp_ttl_seconds: nil, verify_ip_allowlist: nil, allowed_cidrs: nil, idempotency_header_names: nil, ingest_response_code: nil, signing_enabled: nil)
+      body = { url: url }
+      {
+        name: name,
+        description: description,
+        verify_static_token: verify_static_token,
+        token_header_name: token_header_name,
+        token_query_param: token_query_param,
+        token_value: token_value,
+        verify_hmac: verify_hmac,
+        hmac_header_name: hmac_header_name,
+        hmac_secret: hmac_secret,
+        timestamp_header_name: timestamp_header_name,
+        timestamp_ttl_seconds: timestamp_ttl_seconds,
+        verify_ip_allowlist: verify_ip_allowlist,
+        allowed_cidrs: allowed_cidrs,
+        idempotency_header_names: idempotency_header_names,
+        ingest_response_code: ingest_response_code,
+        signing_enabled: signing_enabled
+      }.each do |key, value|
+        body[key] = value unless value.nil?
+      end
+      CreateInboundEndpointResponse.new(extract_data(request(:post, "/v1/inbound-endpoints", body)))
+    end
+
+    def list_inbound_endpoints(limit: nil, cursor: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:cursor] = cursor if cursor
+      response = request(:get, "/v1/inbound-endpoints", nil, params)
+      ListInboundEndpointsResponse.new(
+        "data" => extract_data(response),
+        "has_more" => extract_meta(response)["has_more"] || response["has_more"],
+        "next_cursor" => extract_meta(response)["next_cursor"] || response["next_cursor"]
+      )
+    end
+
+    def get_inbound_endpoint(endpoint_id)
+      InboundEndpoint.new(extract_data(request(:get, "/v1/inbound-endpoints/#{endpoint_id}")))
+    end
+
+    def update_inbound_endpoint(endpoint_id, **attributes)
+      UpdateResult.new(extract_data(request(:patch, "/v1/inbound-endpoints/#{endpoint_id}", compact_hash(attributes))))
+    end
+
+    def delete_inbound_endpoint(endpoint_id)
+      DeleteResult.new(extract_data(request(:delete, "/v1/inbound-endpoints/#{endpoint_id}")))
+    end
+
+    def pause_inbound_endpoint(endpoint_id)
+      PauseState.new(extract_data(request(:post, "/v1/inbound-endpoints/#{endpoint_id}/pause")))
+    end
+
+    def resume_inbound_endpoint(endpoint_id)
+      PauseState.new(extract_data(request(:post, "/v1/inbound-endpoints/#{endpoint_id}/resume")))
+    end
+
+    def replay_inbound_message(message_id)
+      ReplayResponse.new(extract_data(request(:post, "/v1/inbound-messages/#{message_id}/replay")))
+    end
+
+    def replay_all_inbound_messages(status:, inbound_endpoint_id: nil, limit: nil)
+      params = { status: status }
+      params[:inbound_endpoint_id] = inbound_endpoint_id if inbound_endpoint_id
+      params[:limit] = limit if limit
+      ReplayAllMessagesResponse.new(extract_data(request(:post, "/v1/inbound-messages/replay-all", nil, params)))
+    end
+
+    def replay_batch_inbound_messages(message_ids)
+      ReplayBatchMessagesResponse.new(
+        extract_data(request(:post, "/v1/inbound-messages/replay-batch", { message_ids: message_ids }))
+      )
+    end
+
+    def get_inbound_logs(status: nil, inbound_endpoint_id: nil, start_time: nil, end_time: nil, limit: nil, cursor: nil)
+      params = {}
+      params[:status] = status if status
+      params[:inbound_endpoint_id] = inbound_endpoint_id if inbound_endpoint_id
+      params[:start_time] = format_time(start_time) if start_time
+      params[:end_time] = format_time(end_time) if end_time
+      params[:limit] = limit if limit
+      params[:cursor] = cursor if cursor
+      response = request(:get, "/v1/inbound-logs", nil, params)
+      InboundLogsResponse.new(
+        "data" => extract_data(response),
+        "has_more" => extract_meta(response)["has_more"] || response["has_more"],
+        "next_cursor" => extract_meta(response)["next_cursor"] || response["next_cursor"]
+      )
+    end
+
+    def get_inbound_metrics(window: MetricsWindow::TWENTY_FOUR_HOURS, inbound_endpoint_id: nil)
+      params = { window: window }
+      params[:inbound_endpoint_id] = inbound_endpoint_id if inbound_endpoint_id
+      InboundMetrics.new(extract_data(request(:get, "/v1/inbound-metrics", nil, params)))
+    end
+
+    def get_inbound_timeseries_metrics(window: MetricsWindow::TWENTY_FOUR_HOURS, inbound_endpoint_id: nil)
+      params = { window: window }
+      params[:inbound_endpoint_id] = inbound_endpoint_id if inbound_endpoint_id
+      TimeSeriesMetrics.new(extract_data(request(:get, "/v1/inbound-metrics/timeseries", nil, params)))
+    end
+
+    def list_inbound_rejections(inbound_endpoint_id: nil, start_time: nil, end_time: nil, limit: nil, cursor: nil)
+      params = {}
+      params[:inbound_endpoint_id] = inbound_endpoint_id if inbound_endpoint_id
+      params[:start_time] = format_time(start_time) if start_time
+      params[:end_time] = format_time(end_time) if end_time
+      params[:limit] = limit if limit
+      params[:cursor] = cursor if cursor
+      response = request(:get, "/v1/inbound-rejections", nil, params)
+      InboundRejectionsResponse.new(
+        "data" => extract_data(response),
+        "has_more" => extract_meta(response)["has_more"] || response["has_more"],
+        "next_cursor" => extract_meta(response)["next_cursor"] || response["next_cursor"]
+      )
+    end
+
+    def create_export(start_time:, end_time:, status: nil, endpoint_id: nil)
+      body = { start_time: format_time(start_time), end_time: format_time(end_time) }
+      body[:status] = status if status
+      body[:endpoint_id] = endpoint_id if endpoint_id
+      ExportRecord.new(extract_data(request(:post, "/v1/exports", body)))
+    end
+
+    def list_exports
+      extract_data(request(:get, "/v1/exports")).map { |entry| ExportRecord.new(entry) }
+    end
+
+    def get_export(export_id)
+      ExportRecord.new(extract_data(request(:get, "/v1/exports/#{export_id}")))
+    end
+
+    def download_export(export_id)
+      request(:get, "/v1/exports/#{export_id}/download", nil, nil, allow_redirect: true)
+    end
+
     private
 
-    def build_connection
-      Faraday.new(url: @base_url) do |conn|
+    def build_connection(url)
+      Faraday.new(url: url) do |conn|
         conn.request :retry,
                      max: @retries,
                      interval: 0.1,
                      interval_randomness: 0.5,
                      backoff_factor: 2,
                      retry_statuses: [500, 502, 503, 504],
-                     methods: %i[get post put delete],
-                     retry_block: lambda { |env, _options, retries, exception|
-                       # Don't retry client errors
-                       return false if env.status && env.status < 500
-
-                       true
-                     }
+                     methods: %i[get post put patch delete]
 
         conn.options.timeout = @timeout
         conn.options.open_timeout = 10
-
         conn.headers["Authorization"] = "Bearer #{@api_key}"
         conn.headers["Content-Type"] = "application/json"
         conn.headers["Accept"] = "application/json"
         conn.headers["User-Agent"] = "hookbridge-ruby/#{VERSION}"
-
         conn.adapter Faraday.default_adapter
       end
     end
 
-    def request(method, path, body = nil, params = nil)
-      response = @connection.run_request(method, path, body&.to_json, nil) do |req|
+    def request(method, path, body = nil, params = nil, use_send_connection: false, allow_redirect: false)
+      conn = use_send_connection ? @send_connection : @connection
+      response = conn.run_request(method, path, body&.to_json, nil) do |req|
         req.params.update(params) if params
       end
 
-      handle_response(response)
+      handle_response(response, allow_redirect: allow_redirect)
     rescue Faraday::TimeoutError => e
-      raise TimeoutError.new("Request timed out: #{e.message}")
+      raise TimeoutError, "Request timed out: #{e.message}"
     rescue Faraday::ConnectionFailed => e
-      raise NetworkError.new("Connection failed: #{e.message}")
+      raise NetworkError, "Connection failed: #{e.message}"
     rescue Faraday::Error => e
-      raise NetworkError.new("Network error: #{e.message}")
+      raise NetworkError, "Network error: #{e.message}"
     end
 
-    def handle_response(response)
-      request_id = response.headers["x-request-id"]
+    def handle_response(response, allow_redirect: false)
+      return response.headers["location"] if allow_redirect && response.status.between?(300, 399)
+      return {} if response.status == 204
 
       case response.status
       when 200..299
-        return nil if response.body.nil? || response.body.empty?
-
-        parsed = JSON.parse(response.body)
-        # API wraps responses in { data: ..., meta: ... }
-        # Return data field if present, otherwise return parsed response
-        if parsed.is_a?(Hash) && parsed.key?("data")
-          # For paginated responses, include meta info
-          if parsed["meta"]&.key?("has_more") || parsed["meta"]&.key?("next_cursor")
-            {
-              "data" => parsed["data"],
-              "has_more" => parsed.dig("meta", "has_more"),
-              "next_cursor" => parsed.dig("meta", "next_cursor")
-            }
-          else
-            parsed["data"]
-          end
-        else
-          parsed
-        end
+        return {} if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
       when 400
-        error_data = parse_error(response.body)
-        raise ValidationError.new(error_data[:message], request_id: request_id)
+        error = parse_error(response.body)
+        raise ValidationError.new(error[:message], request_id: error[:request_id])
       when 401
-        error_data = parse_error(response.body)
-        raise AuthenticationError.new(error_data[:message], request_id: request_id)
+        error = parse_error(response.body)
+        raise AuthenticationError.new(error[:message], request_id: error[:request_id])
       when 404
-        error_data = parse_error(response.body)
-        raise NotFoundError.new(error_data[:message], request_id: request_id)
+        error = parse_error(response.body)
+        raise NotFoundError.new(error[:message], request_id: error[:request_id])
       when 409
-        error_data = parse_error(response.body)
-        code = error_data[:code]
-        if code == "REPLAY_LIMIT_EXCEEDED"
-          raise ReplayLimitError.new(error_data[:message], request_id: request_id)
-        else
-          raise IdempotencyError.new(error_data[:message], request_id: request_id)
+        error = parse_error(response.body)
+        if %w[IDEMPOTENCY_MISMATCH IDEMPOTENCY_CONFLICT].include?(error[:code])
+          raise IdempotencyError.new(error[:message], request_id: error[:request_id])
         end
+        raise ReplayLimitError.new(error[:message], request_id: error[:request_id]) if error[:code] == "REPLAY_LIMIT_EXCEEDED"
+
+        raise Error.new(error[:message], code: error[:code], request_id: error[:request_id], status_code: 409)
       when 429
-        error_data = parse_error(response.body)
-        retry_after = response.headers["retry-after"]&.to_i
-        raise RateLimitError.new(error_data[:message], request_id: request_id, retry_after: retry_after)
+        error = parse_error(response.body)
+        raise ReplayLimitError.new(error[:message], request_id: error[:request_id]) if error[:code] == "REPLAY_LIMIT_EXCEEDED"
+
+        raise RateLimitError.new(error[:message], request_id: error[:request_id], retry_after: response.headers["retry-after"]&.to_i)
       else
-        error_data = parse_error(response.body)
-        raise Error.new(
-          error_data[:message] || "HTTP #{response.status}",
-          code: error_data[:code],
-          request_id: request_id,
-          status_code: response.status
-        )
+        error = parse_error(response.body)
+        raise Error.new(error[:message], code: error[:code], request_id: error[:request_id], status_code: response.status)
       end
     end
 
     def parse_error(body)
-      return { message: "Unknown error", code: nil } if body.nil? || body.empty?
-
-      data = JSON.parse(body)
-      # API wraps errors in { error: { code: ..., message: ... }, meta: ... }
-      if data["error"].is_a?(Hash)
+      parsed = body && !body.empty? ? JSON.parse(body) : {}
+      error_data = parsed["error"]
+      if error_data.is_a?(Hash)
         {
-          message: data["error"]["message"] || "Unknown error",
-          code: data["error"]["code"]
+          code: error_data["code"],
+          message: error_data["message"] || "Request failed",
+          request_id: parsed.dig("meta", "request_id")
         }
       else
         {
-          message: data["error"] || data["message"] || "Unknown error",
-          code: data["code"]
+          code: parsed["code"],
+          message: error_data || parsed["message"] || "Request failed",
+          request_id: parsed.dig("meta", "request_id")
         }
       end
     rescue JSON::ParserError
-      { message: body, code: nil }
+      { code: nil, message: "Request failed", request_id: nil }
     end
 
-    def format_time(time)
-      case time
-      when Time
-        time.utc.iso8601
-      when String
-        time
-      else
-        time.to_s
+    def extract_data(response)
+      response.is_a?(Hash) && response.key?("data") ? response["data"] : response
+    end
+
+    def extract_meta(response)
+      response.is_a?(Hash) ? (response["meta"] || {}) : {}
+    end
+
+    def format_time(value)
+      value.respond_to?(:iso8601) ? value.iso8601 : value
+    end
+
+    def compact_hash(hash)
+      hash.each_with_object({}) do |(key, value), memo|
+        memo[key] = value unless value.nil?
       end
     end
   end