sirv_rest_api 1.0.0

data/lib/sirv_rest_api/client.rb

@@ -0,0 +1,882 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module SirvRestApi
+  # Main client for interacting with the Sirv REST API
+  class Client
+    DEFAULT_BASE_URL = "https://api.sirv.com"
+    DEFAULT_TOKEN_REFRESH_BUFFER = 60
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+
+    attr_reader :config
+
+    # Initialize a new Sirv API client
+    #
+    # @param client_id [String] Your Sirv API client ID (required)
+    # @param client_secret [String] Your Sirv API client secret (required)
+    # @param base_url [String] Base URL for API (default: https://api.sirv.com)
+    # @param auto_refresh_token [Boolean] Auto-refresh token before expiry (default: true)
+    # @param token_refresh_buffer [Integer] Seconds before token expiry to trigger refresh (default: 60)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param max_retries [Integer] Maximum number of retries for failed requests (default: 3)
+    def initialize(client_id:, client_secret:, base_url: DEFAULT_BASE_URL,
+                   auto_refresh_token: true, token_refresh_buffer: DEFAULT_TOKEN_REFRESH_BUFFER,
+                   timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+      raise ArgumentError, "client_id is required" if client_id.nil? || client_id.empty?
+      raise ArgumentError, "client_secret is required" if client_secret.nil? || client_secret.empty?
+
+      @config = {
+        client_id: client_id,
+        client_secret: client_secret,
+        base_url: base_url,
+        auto_refresh_token: auto_refresh_token,
+        token_refresh_buffer: token_refresh_buffer,
+        timeout: timeout,
+        max_retries: max_retries
+      }
+      @token = nil
+      @token_expiry = nil
+      @mutex = Mutex.new
+    end
+
+    # ============================================================================
+    # Authentication
+    # ============================================================================
+
+    # Authenticate and obtain a bearer token
+    #
+    # @param expires_in [Integer, nil] Token expiry time in seconds (5-604800). Default is 1200 (20 minutes).
+    # @return [TokenResponse] Token response with token, expiration, and scopes
+    def connect(expires_in: nil)
+      body = {
+        clientId: @config[:client_id],
+        clientSecret: @config[:client_secret]
+      }
+
+      if expires_in
+        raise ValidationError.new("expires_in must be between 5 and 604800 seconds") unless expires_in.between?(5, 604800)
+        body[:expiresIn] = expires_in
+      end
+
+      response = request_without_auth(:post, "/v2/token", body)
+      token_response = TokenResponse.new(response)
+
+      @mutex.synchronize do
+        @token = token_response.token
+        @token_expiry = Time.now + token_response.expires_in
+      end
+
+      token_response
+    end
+
+    # Check if client is connected with a valid token
+    #
+    # @return [Boolean] true if connected with valid token
+    def connected?
+      @mutex.synchronize do
+        !@token.nil? && !token_expired?
+      end
+    end
+
+    # Get the current access token
+    #
+    # @return [String, nil] Current token or nil
+    def access_token
+      @mutex.synchronize { @token }
+    end
+
+    # ============================================================================
+    # Account API
+    # ============================================================================
+
+    # Get account information
+    #
+    # @return [AccountInfo] Account information
+    def get_account_info
+      response = request(:get, "/v2/account")
+      AccountInfo.new(response)
+    end
+
+    # Update account settings
+    #
+    # @param options [Hash] Account update options
+    # @return [void]
+    def update_account(options)
+      request(:post, "/v2/account", options)
+      nil
+    end
+
+    # Get API rate limits
+    #
+    # @return [AccountLimits] Rate limit information
+    def get_account_limits
+      response = request(:get, "/v2/account/limits")
+      AccountLimits.new(response)
+    end
+
+    # Get storage usage information
+    #
+    # @return [StorageInfo] Storage information
+    def get_storage_info
+      response = request(:get, "/v2/account/storage")
+      StorageInfo.new(response)
+    end
+
+    # Get all account users
+    #
+    # @return [Array<AccountUser>] List of account users
+    def get_account_users
+      response = request(:get, "/v2/account/users")
+      response.map { |user| AccountUser.new(user) }
+    end
+
+    # Get billing plan details
+    #
+    # @return [BillingPlan] Billing plan information
+    def get_billing_plan
+      response = request(:get, "/v2/billing/plan")
+      BillingPlan.new(response)
+    end
+
+    # Search account events
+    #
+    # @param params [Hash] Search parameters (module, type, level, filename, from, to)
+    # @return [Array<AccountEvent>] List of events
+    def search_events(params = {})
+      response = request(:post, "/v2/account/events/search", params)
+      response.map { |event| AccountEvent.new(event) }
+    end
+
+    # Mark events as seen
+    #
+    # @param event_ids [Array<String>] Event IDs to mark as seen
+    # @return [void]
+    def mark_events_seen(event_ids)
+      request(:post, "/v2/account/events/seen", event_ids)
+      nil
+    end
+
+    # ============================================================================
+    # User API
+    # ============================================================================
+
+    # Get user information
+    #
+    # @param user_id [String, nil] User ID (optional, defaults to current user)
+    # @return [UserInfo] User information
+    def get_user_info(user_id: nil)
+      params = user_id ? { userId: user_id } : {}
+      response = request(:get, "/v2/user", params)
+      UserInfo.new(response)
+    end
+
+    # ============================================================================
+    # Files API - Reading
+    # ============================================================================
+
+    # Get file information
+    #
+    # @param filename [String] File path
+    # @return [FileInfo] File information
+    def get_file_info(filename)
+      response = request(:get, "/v2/files/stat", { filename: filename })
+      FileInfo.new(response)
+    end
+
+    # Read folder contents
+    #
+    # @param dirname [String] Directory path
+    # @param continuation [String, nil] Continuation token for pagination
+    # @return [FolderContents] Folder contents with files and continuation token
+    def read_folder_contents(dirname, continuation: nil)
+      params = { dirname: dirname }
+      params[:continuation] = continuation if continuation
+      response = request(:get, "/v2/files/readdir", params)
+      FolderContents.new(response)
+    end
+
+    # Iterate through all items in a folder (handles pagination automatically)
+    #
+    # @param dirname [String] Directory path
+    # @yield [FileInfo] Each file/folder in the directory
+    # @return [Enumerator] If no block given
+    def each_folder_item(dirname, &block)
+      return enum_for(:each_folder_item, dirname) unless block_given?
+
+      continuation = nil
+      loop do
+        result = read_folder_contents(dirname, continuation: continuation)
+        result.contents.each(&block)
+        break if result.continuation.nil? || result.continuation.empty?
+        continuation = result.continuation
+      end
+    end
+
+    # Get folder options
+    #
+    # @param dirname [String] Directory path
+    # @return [Hash] Folder options
+    def get_folder_options(dirname)
+      request(:get, "/v2/files/options", { dirname: dirname })
+    end
+
+    # Set folder options
+    #
+    # @param dirname [String] Directory path
+    # @param options [Hash] Folder options (scanSpins, allowListing)
+    # @return [void]
+    def set_folder_options(dirname, options)
+      request(:post, "/v2/files/options", { dirname: dirname }.merge(options))
+      nil
+    end
+
+    # Search files
+    #
+    # @param params [Hash] Search parameters (query, from, size, sort, filters)
+    # @return [SearchResult] Search results
+    def search_files(params = {})
+      response = request(:post, "/v2/files/search", params)
+      SearchResult.new(response)
+    end
+
+    # Continue paginated search
+    #
+    # @param scroll_id [String] Scroll ID from previous search
+    # @return [SearchResult] Search results
+    def scroll_search(scroll_id)
+      response = request(:post, "/v2/files/search/scroll", { scrollId: scroll_id })
+      SearchResult.new(response)
+    end
+
+    # Iterate through all search results (handles pagination automatically)
+    #
+    # @param params [Hash] Search parameters
+    # @yield [FileInfo] Each file in search results
+    # @return [Enumerator] If no block given
+    def each_search_result(params = {}, &block)
+      return enum_for(:each_search_result, params) unless block_given?
+
+      result = search_files(params)
+      result.hits.each(&block)
+
+      while result.scroll_id && !result.hits.empty?
+        result = scroll_search(result.scroll_id)
+        result.hits.each(&block)
+      end
+    end
+
+    # Download a file
+    #
+    # @param filename [String] File path on Sirv
+    # @return [String] File contents as binary string
+    def download_file(filename)
+      request_raw(:get, "/v2/files/download", { filename: filename })
+    end
+
+    # Download a file to local path
+    #
+    # @param filename [String] File path on Sirv
+    # @param local_path [String] Local file path to save to
+    # @return [void]
+    def download_file_to(filename, local_path)
+      content = download_file(filename)
+      File.binwrite(local_path, content)
+      nil
+    end
+
+    # ============================================================================
+    # Files API - Writing
+    # ============================================================================
+
+    # Upload a file from content
+    #
+    # @param target_path [String] Target path on Sirv
+    # @param content [String] File content
+    # @param content_type [String, nil] Content type (optional)
+    # @return [void]
+    def upload_file(target_path, content, content_type: nil)
+      upload_raw(target_path, content, content_type: content_type)
+      nil
+    end
+
+    # Upload a file from local path
+    #
+    # @param target_path [String] Target path on Sirv
+    # @param local_path [String] Local file path
+    # @param content_type [String, nil] Content type (optional)
+    # @return [void]
+    def upload_file_from_path(target_path, local_path, content_type: nil)
+      content = File.binread(local_path)
+      upload_file(target_path, content, content_type: content_type)
+    end
+
+    # Create a new folder
+    #
+    # @param dirname [String] Directory path
+    # @return [void]
+    def create_folder(dirname)
+      request(:post, "/v2/files/mkdir", { dirname: dirname })
+      nil
+    end
+
+    # Delete a file or empty folder
+    #
+    # @param filename [String] File or folder path
+    # @return [void]
+    def delete_file(filename)
+      request(:post, "/v2/files/delete", { filename: filename })
+      nil
+    end
+
+    # Delete multiple files/folders
+    #
+    # @param filenames [Array<String>] List of file paths
+    # @return [BatchDeleteResult] Batch delete result
+    def batch_delete(filenames)
+      response = request(:post, "/v2/files/delete", filenames)
+      BatchDeleteResult.new(response)
+    end
+
+    # Get batch delete job status
+    #
+    # @param job_id [String] Job ID
+    # @return [BatchDeleteResult] Job status
+    def get_batch_delete_status(job_id)
+      response = request(:get, "/v2/files/delete/#{job_id}")
+      BatchDeleteResult.new(response)
+    end
+
+    # Copy a file
+    #
+    # @param from [String] Source path
+    # @param to [String] Destination path
+    # @return [void]
+    def copy_file(from:, to:)
+      request(:post, "/v2/files/copy", { from: from, to: to })
+      nil
+    end
+
+    # Rename or move a file/folder
+    #
+    # @param from [String] Current path
+    # @param to [String] New path
+    # @return [void]
+    def rename_file(from:, to:)
+      request(:post, "/v2/files/rename", { from: from, to: to })
+      nil
+    end
+
+    # Fetch file from external URL
+    #
+    # @param url [String] Source URL
+    # @param filename [String] Target filename on Sirv
+    # @param wait [Boolean, nil] Wait for completion
+    # @return [void]
+    def fetch_url(url:, filename:, wait: nil)
+      body = { url: url, filename: filename }
+      body[:wait] = wait unless wait.nil?
+      request(:post, "/v2/files/fetch", body)
+      nil
+    end
+
+    # Create ZIP archive from multiple files
+    #
+    # @param filenames [Array<String>] Files to include
+    # @param filename [String] Output ZIP filename
+    # @return [BatchZipResult] Batch ZIP result
+    def batch_zip(filenames:, filename:)
+      response = request(:post, "/v2/files/zip", { filenames: filenames, filename: filename })
+      BatchZipResult.new(response)
+    end
+
+    # Get ZIP job status
+    #
+    # @param job_id [String] Job ID
+    # @return [BatchZipResult] Job status
+    def get_zip_status(job_id)
+      response = request(:get, "/v2/files/zip/#{job_id}")
+      BatchZipResult.new(response)
+    end
+
+    # ============================================================================
+    # Metadata API
+    # ============================================================================
+
+    # Get all file metadata
+    #
+    # @param filename [String] File path
+    # @return [FileMeta] File metadata
+    def get_file_meta(filename)
+      response = request(:get, "/v2/files/meta", { filename: filename })
+      FileMeta.new(response)
+    end
+
+    # Set file metadata
+    #
+    # @param filename [String] File path
+    # @param meta [Hash, FileMeta] Metadata to set
+    # @return [void]
+    def set_file_meta(filename, meta)
+      body = meta.is_a?(FileMeta) ? meta.to_h : meta
+      request(:post, "/v2/files/meta", { filename: filename }.merge(body))
+      nil
+    end
+
+    # Get file title
+    #
+    # @param filename [String] File path
+    # @return [String] File title
+    def get_file_title(filename)
+      response = request(:get, "/v2/files/meta/title", { filename: filename })
+      response["title"]
+    end
+
+    # Set file title
+    #
+    # @param filename [String] File path
+    # @param title [String] New title
+    # @return [void]
+    def set_file_title(filename, title)
+      request(:post, "/v2/files/meta/title", { filename: filename, title: title })
+      nil
+    end
+
+    # Get file description
+    #
+    # @param filename [String] File path
+    # @return [String] File description
+    def get_file_description(filename)
+      response = request(:get, "/v2/files/meta/description", { filename: filename })
+      response["description"]
+    end
+
+    # Set file description
+    #
+    # @param filename [String] File path
+    # @param description [String] New description
+    # @return [void]
+    def set_file_description(filename, description)
+      request(:post, "/v2/files/meta/description", { filename: filename, description: description })
+      nil
+    end
+
+    # Get file tags
+    #
+    # @param filename [String] File path
+    # @return [Array<String>] File tags
+    def get_file_tags(filename)
+      response = request(:get, "/v2/files/meta/tags", { filename: filename })
+      response["tags"] || []
+    end
+
+    # Add tags to file
+    #
+    # @param filename [String] File path
+    # @param tags [Array<String>] Tags to add
+    # @return [void]
+    def add_file_tags(filename, tags)
+      request(:post, "/v2/files/meta/tags", { filename: filename, tags: tags })
+      nil
+    end
+
+    # Remove tags from file
+    #
+    # @param filename [String] File path
+    # @param tags [Array<String>] Tags to remove
+    # @return [void]
+    def remove_file_tags(filename, tags)
+      request(:delete, "/v2/files/meta/tags", { filename: filename, tags: tags })
+      nil
+    end
+
+    # Get product metadata
+    #
+    # @param filename [String] File path
+    # @return [ProductMeta] Product metadata
+    def get_product_meta(filename)
+      response = request(:get, "/v2/files/meta/product", { filename: filename })
+      ProductMeta.new(response)
+    end
+
+    # Set product metadata
+    #
+    # @param filename [String] File path
+    # @param meta [Hash, ProductMeta] Product metadata
+    # @return [void]
+    def set_product_meta(filename, meta)
+      body = meta.is_a?(ProductMeta) ? meta.to_h : meta
+      request(:post, "/v2/files/meta/product", { filename: filename }.merge(body))
+      nil
+    end
+
+    # Get approval flag
+    #
+    # @param filename [String] File path
+    # @return [Boolean] Approval status
+    def get_approval_flag(filename)
+      response = request(:get, "/v2/files/meta/approval", { filename: filename })
+      response["approved"]
+    end
+
+    # Set approval flag
+    #
+    # @param filename [String] File path
+    # @param approved [Boolean] Approval status
+    # @return [void]
+    def set_approval_flag(filename, approved)
+      request(:post, "/v2/files/meta/approval", { filename: filename, approved: approved })
+      nil
+    end
+
+    # ============================================================================
+    # JWT API
+    # ============================================================================
+
+    # Generate JWT protected URL
+    #
+    # @param filename [String] File path
+    # @param expires_in [Integer, nil] Expiration time in seconds
+    # @param secure_params [Hash, nil] Additional secure parameters
+    # @return [JwtResponse] JWT response with URL and token
+    def generate_jwt(filename:, expires_in: nil, secure_params: nil)
+      body = { filename: filename }
+      body[:expiresIn] = expires_in if expires_in
+      body[:secureParams] = secure_params if secure_params
+      response = request(:post, "/v2/files/jwt", body)
+      JwtResponse.new(response)
+    end
+
+    # ============================================================================
+    # Spins/360 API
+    # ============================================================================
+
+    # Convert spin to video
+    #
+    # @param filename [String] Spin filename
+    # @param options [Hash, nil] Conversion options (width, height, loops, format)
+    # @return [String] Output video filename
+    def spin_to_video(filename, options: nil)
+      body = { filename: filename }
+      body[:options] = options if options
+      response = request(:post, "/v2/files/spin2video", body)
+      response["filename"]
+    end
+
+    # Convert video to spin
+    #
+    # @param filename [String] Video filename
+    # @param target_filename [String, nil] Target spin filename
+    # @param options [Hash, nil] Conversion options (frames, start, duration)
+    # @return [String] Output spin filename
+    def video_to_spin(filename, target_filename: nil, options: nil)
+      body = { filename: filename }
+      body[:targetFilename] = target_filename if target_filename
+      body[:options] = options if options
+      response = request(:post, "/v2/files/video2spin", body)
+      response["filename"]
+    end
+
+    # Export spin to Amazon
+    #
+    # @param filename [String] Spin filename
+    # @param asin [String, nil] Amazon ASIN
+    # @param product_id [String, nil] Product ID
+    # @return [void]
+    def export_spin_to_amazon(filename:, asin: nil, product_id: nil)
+      body = { filename: filename }
+      body[:asin] = asin if asin
+      body[:productId] = product_id if product_id
+      request(:post, "/v2/files/spin/export/amazon", body)
+      nil
+    end
+
+    # Export spin to Walmart
+    #
+    # @param filename [String] Spin filename
+    # @param product_id [String, nil] Product ID
+    # @return [void]
+    def export_spin_to_walmart(filename:, product_id: nil)
+      body = { filename: filename }
+      body[:productId] = product_id if product_id
+      request(:post, "/v2/files/spin/export/walmart", body)
+      nil
+    end
+
+    # Export spin to Home Depot
+    #
+    # @param filename [String] Spin filename
+    # @param product_id [String, nil] Product ID
+    # @return [void]
+    def export_spin_to_home_depot(filename:, product_id: nil)
+      body = { filename: filename }
+      body[:productId] = product_id if product_id
+      request(:post, "/v2/files/spin/export/homedepot", body)
+      nil
+    end
+
+    # Export spin to Lowe's
+    #
+    # @param filename [String] Spin filename
+    # @param product_id [String, nil] Product ID
+    # @return [void]
+    def export_spin_to_lowes(filename:, product_id: nil)
+      body = { filename: filename }
+      body[:productId] = product_id if product_id
+      request(:post, "/v2/files/spin/export/lowes", body)
+      nil
+    end
+
+    # Export spin to Grainger
+    #
+    # @param filename [String] Spin filename
+    # @param product_id [String, nil] Product ID
+    # @return [void]
+    def export_spin_to_grainger(filename:, product_id: nil)
+      body = { filename: filename }
+      body[:productId] = product_id if product_id
+      request(:post, "/v2/files/spin/export/grainger", body)
+      nil
+    end
+
+    # ============================================================================
+    # Points of Interest API
+    # ============================================================================
+
+    # Get points of interest for a file
+    #
+    # @param filename [String] File path
+    # @return [Array<PointOfInterest>] List of points of interest
+    def get_points_of_interest(filename)
+      response = request(:get, "/v2/files/poi", { filename: filename })
+      response.map { |poi| PointOfInterest.new(poi) }
+    end
+
+    # Set point of interest
+    #
+    # @param filename [String] File path
+    # @param poi [Hash, PointOfInterest] Point of interest data
+    # @return [void]
+    def set_point_of_interest(filename, poi)
+      body = poi.is_a?(PointOfInterest) ? poi.to_h : poi
+      request(:post, "/v2/files/poi", { filename: filename }.merge(body))
+      nil
+    end
+
+    # Delete point of interest
+    #
+    # @param filename [String] File path
+    # @param name [String] POI name
+    # @return [void]
+    def delete_point_of_interest(filename, name)
+      request(:delete, "/v2/files/poi", { filename: filename, name: name })
+      nil
+    end
+
+    # ============================================================================
+    # Statistics API
+    # ============================================================================
+
+    # Get HTTP transfer statistics
+    #
+    # @param from [String] Start date (ISO format)
+    # @param to [String] End date (ISO format)
+    # @return [Array<HttpStats>] HTTP statistics
+    def get_http_stats(from:, to:)
+      response = request(:get, "/v2/stats/http", { from: from, to: to })
+      response.map { |stat| HttpStats.new(stat) }
+    end
+
+    # Get spin views statistics (max 5-day range)
+    #
+    # @param from [String] Start date (ISO format)
+    # @param to [String] End date (ISO format)
+    # @return [Array<SpinViewStats>] Spin view statistics
+    def get_spin_views_stats(from:, to:)
+      response = request(:get, "/v2/stats/spins/views", { from: from, to: to })
+      response.map { |stat| SpinViewStats.new(stat) }
+    end
+
+    # Get storage statistics
+    #
+    # @param from [String] Start date (ISO format)
+    # @param to [String] End date (ISO format)
+    # @return [Array<StorageStats>] Storage statistics
+    def get_storage_stats(from:, to:)
+      response = request(:get, "/v2/stats/storage", { from: from, to: to })
+      response.map { |stat| StorageStats.new(stat) }
+    end
+
+    private
+
+    def token_expired?
+      return true if @token_expiry.nil?
+      buffer = @config[:auto_refresh_token] ? @config[:token_refresh_buffer] : 0
+      Time.now >= (@token_expiry - buffer)
+    end
+
+    def ensure_token
+      @mutex.synchronize do
+        if @token.nil? || token_expired?
+          # Release lock during network call
+          @mutex.unlock
+          begin
+            connect
+          ensure
+            @mutex.lock
+          end
+        end
+        @token
+      end
+    end
+
+    def request(method, endpoint, body_or_params = nil, retries = 0)
+      token = ensure_token
+
+      uri = build_uri(endpoint, method == :get ? body_or_params : nil)
+      http = build_http(uri)
+      req = build_request(method, uri, body_or_params, token)
+
+      response = http.request(req)
+      handle_response(response)
+    rescue ApiError => e
+      if e.status_code >= 500 && retries < @config[:max_retries]
+        sleep(2 ** retries)
+        request(method, endpoint, body_or_params, retries + 1)
+      else
+        raise
+      end
+    end
+
+    def request_without_auth(method, endpoint, body = nil)
+      uri = build_uri(endpoint)
+      http = build_http(uri)
+      req = build_request(method, uri, body, nil)
+
+      response = http.request(req)
+      handle_response(response)
+    end
+
+    def request_raw(method, endpoint, params = nil)
+      token = ensure_token
+
+      uri = build_uri(endpoint, params)
+      http = build_http(uri)
+      req = build_request(method, uri, nil, token)
+
+      response = http.request(req)
+
+      if response.code.to_i >= 400
+        handle_error_response(response)
+      end
+
+      response.body
+    end
+
+    def upload_raw(target_path, content, content_type: nil)
+      token = ensure_token
+
+      uri = URI.parse("#{@config[:base_url]}/v2/files/upload?filename=#{URI.encode_www_form_component(target_path)}")
+      http = build_http(uri)
+
+      boundary = "----RubyFormBoundary#{rand(1_000_000_000)}"
+
+      body = ""
+      body << "--#{boundary}\r\n"
+      body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{File.basename(target_path)}\"\r\n"
+      body << "Content-Type: #{content_type || 'application/octet-stream'}\r\n\r\n"
+      body << content
+      body << "\r\n--#{boundary}--\r\n"
+
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{token}"
+      req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      req.body = body
+
+      response = http.request(req)
+
+      if response.code.to_i >= 400
+        handle_error_response(response)
+      end
+    end
+
+    def build_uri(endpoint, params = nil)
+      url = "#{@config[:base_url]}#{endpoint}"
+      if params && !params.empty?
+        query = params.map { |k, v| "#{URI.encode_www_form_component(k.to_s)}=#{URI.encode_www_form_component(v.to_s)}" }.join("&")
+        url = "#{url}?#{query}"
+      end
+      URI.parse(url)
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @config[:timeout]
+      http.open_timeout = @config[:timeout]
+      http
+    end
+
+    def build_request(method, uri, body, token)
+      req_class = case method
+                  when :get then Net::HTTP::Get
+                  when :post then Net::HTTP::Post
+                  when :delete then Net::HTTP::Delete
+                  when :put then Net::HTTP::Put
+                  else raise ArgumentError, "Unknown HTTP method: #{method}"
+                  end
+
+      req = req_class.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{token}" if token
+
+      if body && method != :get
+        req.body = body.to_json
+      end
+
+      req
+    end
+
+    def handle_response(response)
+      if response.code.to_i >= 400
+        handle_error_response(response)
+      end
+
+      return {} if response.body.nil? || response.body.empty?
+
+      content_type = response["Content-Type"]
+      if content_type && content_type.include?("application/json")
+        JSON.parse(response.body)
+      else
+        response.body
+      end
+    end
+
+    def handle_error_response(response)
+      status_code = response.code.to_i
+
+      begin
+        error_data = JSON.parse(response.body)
+        message = error_data["message"] || response.message
+        error_code = error_data["error"]
+      rescue JSON::ParserError
+        message = response.message
+        error_code = nil
+      end
+
+      case status_code
+      when 401
+        raise AuthenticationError.new(message, status_code)
+      when 404
+        raise NotFoundError.new(message, status_code)
+      when 429
+        raise RateLimitError.new(message, status_code)
+      else
+        raise ApiError.new(message, status_code, error_code)
+      end
+    end
+  end
+end