generatorlabs 2.0.0

data/lib/generatorlabs/rbl.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+#
+# This file is part of the Generator Labs Ruby SDK package.
+#
+# (c) Generator Labs <support@generatorlabs.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+
+module GeneratorLabs
+  # RBL monitoring API namespace
+  class RBL
+    def initialize(handler)
+      @handler = handler
+    end
+
+    # Access host management operations
+    # @return [RBLHosts]
+    def hosts
+      @hosts ||= RBLHosts.new(@handler)
+    end
+
+    # Access profile management operations
+    # @return [RBLProfiles]
+    def profiles
+      @profiles ||= RBLProfiles.new(@handler)
+    end
+
+    # Access source management operations
+    # @return [RBLSources]
+    def sources
+      @sources ||= RBLSources.new(@handler)
+    end
+
+    # Access manual RBL check operations
+    # @return [RBLCheck]
+    def check
+      @check ||= RBLCheck.new(@handler)
+    end
+
+    # Get current RBL listings for monitored hosts
+    # @return [Hash] Listing information
+    def listings
+      @handler.get('rbl/listings')
+    end
+  end
+
+  # Manual RBL check operations
+  class RBLCheck
+    def initialize(handler)
+      @handler = handler
+    end
+
+    # Start a manual RBL check
+    # @param params [Hash] Check parameters (host, callback, details)
+    # @return [Hash] Check result with check ID
+    def start(params)
+      @handler.post('rbl/check/start', params)
+    end
+
+    # Get the status of a manual RBL check
+    # @param id [String] Check ID
+    # @param params [Hash] Optional parameters (details)
+    # @return [Hash] Check status
+    def status(id, params = {})
+      @handler.get("rbl/check/status/#{id}", params)
+    end
+  end
+
+  # RBL host management
+  class RBLHosts
+    def initialize(handler)
+      @handler = handler
+    end
+
+    # Get hosts (all, by ID, or by array of IDs)
+    # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
+    # @return [Hash] Host data
+    def get(*ids)
+      return @handler.get('rbl/hosts') if ids.empty?
+
+      # Check if first argument is a hash (parameters)
+      return @handler.get('rbl/hosts', ids.first) if ids.first.is_a?(Hash)
+
+      return @handler.get("rbl/hosts/#{ids.first}") if ids.length == 1
+
+      @handler.get('rbl/hosts', { ids: ids.join(',') })
+    end
+
+    # Get all hosts with automatic pagination
+    # @param params [Hash] Optional parameters (e.g., page_size)
+    # @return [Array] All hosts across all pages
+    def get_all(params = {})
+      all_items = []
+      page = 1
+      params = params.dup
+
+      loop do
+        params[:page] = page
+        response = get(params)
+        hosts = response['hosts'] || []
+
+        all_items.concat(hosts)
+
+        break unless page < (response['total_pages'] || 1) && !hosts.empty?
+
+        page += 1
+      end
+
+      all_items
+    end
+
+    # Create a new monitored host
+    # @param params [Hash] Host parameters
+    # @return [Hash] Created host data
+    def create(params)
+      @handler.post('rbl/hosts', params)
+    end
+
+    # Update a monitored host
+    # @param id [String, Integer] Host ID
+    # @param params [Hash] Updated parameters
+    # @return [Hash] Updated host data
+    def update(id, params)
+      @handler.put("rbl/hosts/#{id}", params)
+    end
+
+    # Delete a monitored host
+    # @param id [String, Integer] Host ID
+    # @return [Hash] Deletion confirmation
+    def delete(id)
+      @handler.delete("rbl/hosts/#{id}")
+    end
+
+    # Pause monitoring for a host
+    # @param id [String, Integer] Host ID
+    # @return [Hash] Response
+    def pause(id)
+      @handler.post("rbl/hosts/#{id}/pause")
+    end
+
+    # Resume monitoring for a host
+    # @param id [String, Integer] Host ID
+    # @return [Hash] Response
+    def resume(id)
+      @handler.post("rbl/hosts/#{id}/resume")
+    end
+  end
+
+  # RBL profile management
+  class RBLProfiles
+    def initialize(handler)
+      @handler = handler
+    end
+
+    # Get profiles (all, by ID, or by array of IDs)
+    # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
+    # @return [Hash] Profile data
+    def get(*ids)
+      return @handler.get('rbl/profiles') if ids.empty?
+
+      # Check if first argument is a hash (parameters)
+      return @handler.get('rbl/profiles', ids.first) if ids.first.is_a?(Hash)
+
+      return @handler.get("rbl/profiles/#{ids.first}") if ids.length == 1
+
+      @handler.get('rbl/profiles', { ids: ids.join(',') })
+    end
+
+    # Get all profiles with automatic pagination
+    # @param params [Hash] Optional parameters (e.g., page_size)
+    # @return [Array] All profiles across all pages
+    def get_all(params = {})
+      all_items = []
+      page = 1
+      params = params.dup
+
+      loop do
+        params[:page] = page
+        response = get(params)
+        profiles = response['profiles'] || []
+
+        all_items.concat(profiles)
+
+        break unless page < (response['total_pages'] || 1) && !profiles.empty?
+
+        page += 1
+      end
+
+      all_items
+    end
+
+    # Create a new monitoring profile
+    # @param params [Hash] Profile parameters
+    # @return [Hash] Created profile data
+    def create(params)
+      @handler.post('rbl/profiles', params)
+    end
+
+    # Update a monitoring profile
+    # @param id [String, Integer] Profile ID
+    # @param params [Hash] Updated parameters
+    # @return [Hash] Updated profile data
+    def update(id, params)
+      @handler.put("rbl/profiles/#{id}", params)
+    end
+
+    # Delete a monitoring profile
+    # @param id [String, Integer] Profile ID
+    # @return [Hash] Deletion confirmation
+    def delete(id)
+      @handler.delete("rbl/profiles/#{id}")
+    end
+  end
+
+  # RBL source management
+  class RBLSources
+    def initialize(handler)
+      @handler = handler
+    end
+
+    # Get sources (all, by ID, or by array of IDs)
+    # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
+    # @return [Hash] Source data
+    def get(*ids)
+      return @handler.get('rbl/sources') if ids.empty?
+
+      # Check if first argument is a hash (parameters)
+      return @handler.get('rbl/sources', ids.first) if ids.first.is_a?(Hash)
+
+      return @handler.get("rbl/sources/#{ids.first}") if ids.length == 1
+
+      @handler.get('rbl/sources', { ids: ids.join(',') })
+    end
+
+    # Get all sources with automatic pagination
+    # @param params [Hash] Optional parameters (e.g., page_size)
+    # @return [Array] All sources across all pages
+    def get_all(params = {})
+      all_items = []
+      page = 1
+      params = params.dup
+
+      loop do
+        params[:page] = page
+        response = get(params)
+        sources = response['sources'] || []
+
+        all_items.concat(sources)
+
+        break unless page < (response['total_pages'] || 1) && !sources.empty?
+
+        page += 1
+      end
+
+      all_items
+    end
+
+    # Create a new RBL source
+    # @param params [Hash] Source parameters
+    # @return [Hash] Created source data
+    def create(params)
+      @handler.post('rbl/sources', params)
+    end
+
+    # Update an RBL source
+    # @param id [String, Integer] Source ID
+    # @param params [Hash] Updated parameters
+    # @return [Hash] Updated source data
+    def update(id, params)
+      @handler.put("rbl/sources/#{id}", params)
+    end
+
+    # Delete an RBL source
+    # @param id [String, Integer] Source ID
+    # @return [Hash] Deletion confirmation
+    def delete(id)
+      @handler.delete("rbl/sources/#{id}")
+    end
+
+    # Pause an RBL source
+    # @param id [String, Integer] Source ID
+    # @return [Hash] Response
+    def pause(id)
+      @handler.post("rbl/sources/#{id}/pause")
+    end
+
+    # Resume an RBL source
+    # @param id [String, Integer] Source ID
+    # @return [Hash] Response
+    def resume(id)
+      @handler.post("rbl/sources/#{id}/resume")
+    end
+  end
+end

data/lib/generatorlabs/request_handler.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+#
+# This file is part of the Generator Labs Ruby SDK package.
+#
+# (c) Generator Labs <support@generatorlabs.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+
+module GeneratorLabs
+  # Handles HTTP requests to the Generator Labs API.
+  #
+  # This class manages HTTP client configuration, authentication, retry logic,
+  # and error handling for all API requests. It automatically retries failed
+  # requests using exponential backoff on connection errors, 5xx server errors,
+  # and 429 rate limit errors.
+  class RequestHandler
+    # Initialize request handler with authentication and retry logic.
+    #
+    # This creates a Faraday connection with:
+    # - Automatic retries on connection errors, 5xx errors, and 429 rate limits
+    # - Exponential backoff based on config.retry_backoff
+    # - Configurable timeouts from config.timeout and config.connect_timeout
+    # - HTTP Basic Authentication using account_sid and auth_token
+    #
+    # @param account_sid [String] Account SID for authentication
+    # @param auth_token [String] Auth token for authentication
+    # @param config [Config] Configuration object with timeouts and retry settings
+    def initialize(account_sid, auth_token, config)
+      @account_sid = account_sid
+      @auth_token = auth_token
+      @config = config
+
+      # Create Faraday connection with retry middleware
+      @connection = Faraday.new(url: config.base_url) do |faraday_config|
+        faraday_config.request :url_encoded
+        faraday_config.request :authorization, :basic, account_sid, auth_token
+        # Retry with exponential backoff; faraday-retry respects Retry-After
+        # headers automatically on rate limit (429) responses
+        faraday_config.request :retry,
+                               max: config.max_retries,
+                               interval: 1.0,
+                               backoff_factor: config.retry_backoff,
+                               retry_statuses: [429, 500, 502, 503, 504],
+                               methods: %i[get post put delete]
+
+        faraday_config.adapter Faraday.default_adapter
+        faraday_config.options.timeout = config.timeout
+        faraday_config.options.open_timeout = config.connect_timeout
+      end
+    end
+
+    # Make a GET request to the API.
+    #
+    # Parameters are sent as query string parameters. The request includes
+    # automatic retry logic for failures.
+    #
+    # @param path [String] API endpoint path (e.g., 'rbl/hosts')
+    # @param params [Hash, nil] Query parameters (e.g., {status: 'active'})
+    # @return [Response] Response wrapper with parsed data and rate limit info
+    # @raise [Error] if request fails after all retries
+    #
+    # @example
+    #   handler.get('rbl/hosts', { status: 'active' })
+    def get(path, params = nil)
+      make_request(:get, path, params)
+    end
+
+    # Make a POST request to the API.
+    #
+    # Parameters are sent as application/x-www-form-urlencoded data.
+    # The request includes automatic retry logic for failures.
+    #
+    # @param path [String] API endpoint path (e.g., 'rbl/hosts')
+    # @param params [Hash, nil] Request parameters (e.g., {name: 'My Host', host: '1.2.3.4'})
+    # @return [Response] Response wrapper with parsed data and rate limit info
+    # @raise [Error] if request fails after all retries
+    #
+    # @example
+    #   handler.post('rbl/hosts', { name: 'My Host', host: '1.2.3.4', type: 'rbl' })
+    def post(path, params = nil)
+      make_request(:post, path, params)
+    end
+
+    # Make a PUT request to the API.
+    #
+    # Parameters are sent as application/x-www-form-urlencoded data.
+    # The request includes automatic retry logic for failures.
+    #
+    # @param path [String] API endpoint path (e.g., 'rbl/hosts/HTxxxxxxxx')
+    # @param params [Hash, nil] Request parameters (e.g., {name: 'Updated Name'})
+    # @return [Response] Response wrapper with parsed data and rate limit info
+    # @raise [Error] if request fails after all retries
+    #
+    # @example
+    #   handler.put('rbl/hosts/HT1a2b3c4d5e6f7890abcdef1234567890', { name: 'Updated Name' })
+    def put(path, params = nil)
+      make_request(:put, path, params)
+    end
+
+    # Make a DELETE request to the API.
+    #
+    # No parameters are sent with DELETE requests. The request includes
+    # automatic retry logic for failures.
+    #
+    # @param path [String] API endpoint path (e.g., 'rbl/hosts/HTxxxxxxxx')
+    # @return [Response] Response wrapper with parsed data and rate limit info
+    # @raise [Error] if request fails after all retries
+    #
+    # @example
+    #   handler.delete('rbl/hosts/HT1a2b3c4d5e6f7890abcdef1234567890')
+    def delete(path)
+      make_request(:delete, path, nil)
+    end
+
+    private
+
+    # Make HTTP request to API with automatic retries.
+    #
+    # This method handles:
+    # - Building the request URL with .json extension
+    # - Adding query parameters for GET requests
+    # - Adding form data for POST/PUT/DELETE requests
+    # - Setting authentication headers
+    # - Executing the request with retry logic
+    # - Parsing JSON responses
+    # - Checking for API errors in the response
+    #
+    # Errors are raised if:
+    # - All retry attempts fail
+    # - The response body cannot be parsed
+    # - The API returns success=false in the response
+    # - The HTTP status code is >= 400
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param path [String] API endpoint path
+    # @param params [Hash, nil] Request parameters
+    # @return [Response] Response wrapper with parsed data and rate limit info
+    # @raise [Error] if request fails or response is invalid
+    def make_request(method, path, params)
+      url = "#{path}.json"
+      params = convert_params(params)
+
+      response = @connection.send(method) do |req|
+        req.url url
+        req.headers['User-Agent'] = "GeneratorLabs-Ruby/#{VERSION}"
+        req.headers['Accept'] = 'application/json'
+        apply_params(req, method, params)
+      end
+
+      data = parse_response(response)
+
+      #
+      # parse rate limit headers
+      #
+      rate_limit_info = nil
+      if response.headers['ratelimit-limit']
+        rate_limit_info = RateLimitInfo.new(
+          limit: response.headers['ratelimit-limit'],
+          remaining: response.headers['ratelimit-remaining'].to_i,
+          reset: response.headers['ratelimit-reset'].to_i
+        )
+      end
+
+      Response.new(data, rate_limit_info)
+    rescue Faraday::Error => e
+      raise Error, "API request failed: #{e.message}"
+    end
+
+    # Convert array values to comma-separated strings for form encoding.
+    def convert_params(params)
+      return unless params
+
+      params.transform_values { |v| v.is_a?(Array) ? v.join(',') : v }
+    end
+
+    # Apply parameters to request based on HTTP method.
+    def apply_params(req, method, params)
+      return unless params
+
+      if method == :get
+        req.params = params
+      else
+        req.body = params
+      end
+    end
+
+    # Parse JSON response and check for errors.
+    def parse_response(response)
+      data = JSON.parse(response.body)
+
+      if data.is_a?(Hash) && data['success'] == false
+        error_msg = data.dig('error', 'message') || data['message'] || 'Unknown error'
+        raise Error, "API error: #{error_msg}"
+      end
+
+      if response.status >= 400
+        error_msg = data.dig('error', 'message') || data['message'] || "HTTP #{response.status} error"
+        raise Error, "API error: #{error_msg}"
+      end
+
+      data
+    rescue JSON::ParserError => e
+      raise Error, "Failed to parse JSON response: #{e.message}"
+    end
+  end
+end

data/lib/generatorlabs/response.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+#
+# This file is part of the Generator Labs Ruby SDK package.
+#
+# (c) Generator Labs <support@generatorlabs.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+
+module GeneratorLabs
+  # API response wrapper providing Hash-like access to response data and rate limit info.
+  #
+  # Supports bracket notation (response['key']) for backward compatibility
+  # with raw Hash returns, while also exposing rate_limit_info.
+  class Response
+    # @return [RateLimitInfo, nil] Rate limit information from response headers
+    attr_reader :rate_limit_info
+
+    # @param data [Hash] Parsed JSON response body
+    # @param rate_limit_info [RateLimitInfo, nil] Rate limit information
+    def initialize(data, rate_limit_info = nil)
+      @data = data
+      @rate_limit_info = rate_limit_info
+    end
+
+    # Access response data by key (Hash-like access).
+    # @param key [String] The key to look up
+    # @return [Object] The value
+    def [](key)
+      @data[key]
+    end
+
+    # Dig into nested response data.
+    # @param keys [Array] Keys to dig through
+    # @return [Object] The nested value
+    def dig(*keys)
+      @data.dig(*keys)
+    end
+
+    # Check if a key exists in the response data.
+    # @param key [String] The key to check
+    # @return [Boolean]
+    def key?(key)
+      @data.key?(key)
+    end
+
+    # Convert to a plain Hash.
+    # @return [Hash]
+    def to_h
+      @data
+    end
+
+    # Check if the response data is a Hash (for type compatibility).
+    # @param klass [Class] The class to check
+    # @return [Boolean]
+    def is_a?(klass)
+      klass == Hash ? true : super
+    end
+  end
+end

data/lib/generatorlabs/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+#
+# This file is part of the Generator Labs Ruby SDK package.
+#
+# (c) Generator Labs <support@generatorlabs.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+
+module GeneratorLabs
+  # Current version of the SDK
+  VERSION = '2.0.0'
+end

data/lib/generatorlabs/webhook.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+#
+# This file is part of the Generator Labs Ruby SDK package.
+#
+# (c) Generator Labs <support@generatorlabs.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+
+require 'openssl'
+require 'json'
+
+module GeneratorLabs
+  # Webhook signature verification utility.
+  #
+  # Verifies that incoming webhook requests were sent by Generator Labs
+  # using HMAC-SHA256 signatures.
+  #
+  # @example
+  #   payload = GeneratorLabs::Webhook.verify(body, header, signing_secret)
+  class Webhook
+    # Default tolerance in seconds for timestamp validation (5 minutes).
+    DEFAULT_TOLERANCE = 300
+
+    # Verify a webhook signature and return the decoded payload.
+    #
+    # @param body [String] The raw request body string
+    # @param header [String] The X-Webhook-Signature header value
+    # @param secret [String] Your webhook's signing secret
+    # @param tolerance [Integer] Maximum age in seconds (0 to disable, default: 300)
+    # @return [Hash] The decoded JSON payload
+    # @raise [Error] if verification fails
+    def self.verify(body, header, secret, tolerance = DEFAULT_TOLERANCE)
+      raise Error, 'Missing X-Webhook-Signature header.' if header.nil? || header.empty?
+
+      # Parse the header: t=timestamp,v1=signature
+      parts = {}
+      header.split(',').each do |part|
+        key, value = part.split('=', 2)
+        parts[key] = value
+      end
+
+      raise Error, 'Invalid X-Webhook-Signature header format.' unless parts.key?('t') && parts.key?('v1')
+
+      # Check timestamp tolerance
+      if tolerance.positive? && (Time.now.to_i - parts['t'].to_i).abs > tolerance
+        raise Error, 'Webhook timestamp is outside the tolerance window.'
+      end
+
+      # Compute and compare the signature
+      expected = OpenSSL::HMAC.hexdigest('sha256', secret, "#{parts['t']}.#{body}")
+
+      raise Error, 'Webhook signature verification failed.' unless secure_compare(expected, parts['v1'])
+
+      # Decode and return the payload
+      JSON.parse(body)
+    end
+
+    # Constant-time string comparison.
+    def self.secure_compare(left, right)
+      return false unless left.bytesize == right.bytesize
+
+      OpenSSL.fixed_length_secure_compare(left, right)
+    end
+
+    private_class_method :secure_compare
+  end
+end

data/lib/generatorlabs.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#
+# This file is part of the Generator Labs Ruby SDK package.
+#
+# (c) Generator Labs <support@generatorlabs.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+
+require_relative 'generatorlabs/version'
+require_relative 'generatorlabs/config'
+require_relative 'generatorlabs/rate_limit_info'
+require_relative 'generatorlabs/response'
+require_relative 'generatorlabs/client'
+require_relative 'generatorlabs/request_handler'
+require_relative 'generatorlabs/webhook'
+require_relative 'generatorlabs/rbl'
+require_relative 'generatorlabs/contact'
+require_relative 'generatorlabs/cert'
+
+# Generator Labs API SDK
+module GeneratorLabs
+  class Error < StandardError; end
+end