basecamp-sdk 0.2.1

data/lib/basecamp/hooks.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Interface for observability hooks.
+  # Implement this to add logging, metrics, or tracing to HTTP requests.
+  #
+  # @example Custom hooks with logging
+  #   class LoggingHooks
+  #     include Basecamp::Hooks
+  #
+  #     def on_request_start(info)
+  #       puts "Starting #{info.method} #{info.url}"
+  #     end
+  #
+  #     def on_request_end(info, result)
+  #       puts "Completed #{info.method} #{info.url} - #{result.status_code} (#{result.duration}s)"
+  #     end
+  #   end
+  #
+  #   client = Basecamp::Client.new(config: config, token_provider: provider, hooks: LoggingHooks.new)
+  module Hooks
+    # Called when a service operation starts (e.g., projects.list, todos.create).
+    # @param info [OperationInfo] operation information
+    # @return [void]
+    def on_operation_start(info)
+      # Override in implementation
+    end
+
+    # Called when a service operation completes (success or failure).
+    # @param info [OperationInfo] operation information
+    # @param result [OperationResult] result information
+    # @return [void]
+    def on_operation_end(info, result)
+      # Override in implementation
+    end
+
+    # Called when an HTTP request starts.
+    # @param info [RequestInfo] request information
+    # @return [void]
+    def on_request_start(info)
+      # Override in implementation
+    end
+
+    # Called when an HTTP request completes (success or failure).
+    # @param info [RequestInfo] request information
+    # @param result [RequestResult] result information
+    # @return [void]
+    def on_request_end(info, result)
+      # Override in implementation
+    end
+
+    # Called when a request is retried.
+    # @param info [RequestInfo] request information
+    # @param attempt [Integer] the next attempt number
+    # @param error [Exception] the error that triggered the retry
+    # @param delay [Float] seconds until retry
+    # @return [void]
+    def on_retry(info, attempt, error, delay)
+      # Override in implementation
+    end
+
+    # Called when pagination fetches the next page.
+    # @param url [String] the next page URL
+    # @param page [Integer] the page number
+    # @return [void]
+    def on_paginate(url, page)
+      # Override in implementation
+    end
+  end
+end

data/lib/basecamp/http.rb

@@ -0,0 +1,440 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "time"
+require "uri"
+
+module Basecamp
+  # HTTP client layer with retry, backoff, and caching support.
+  # This is an internal class used by Client; you typically don't use it directly.
+  class Http
+    # Default User-Agent header
+    USER_AGENT = "basecamp-sdk-ruby/#{VERSION} (api:#{API_VERSION})".freeze
+
+    # @param config [Config] configuration settings
+    # @param token_provider [TokenProvider, nil] OAuth token provider (deprecated, use auth_strategy)
+    # @param auth_strategy [AuthStrategy, nil] authentication strategy
+    # @param hooks [Hooks] observability hooks
+    def initialize(config:, token_provider: nil, auth_strategy: nil, hooks: nil)
+      @config = config
+      @auth_strategy = auth_strategy || BearerAuth.new(token_provider)
+      @token_provider = token_provider || (@auth_strategy.is_a?(BearerAuth) ? @auth_strategy.token_provider : nil)
+      @hooks = hooks || NoopHooks.new
+      @faraday = build_faraday_client
+    end
+
+    # @return [String] the configured base URL
+    def base_url
+      @config.base_url
+    end
+
+    # Performs a GET request.
+    # @param path [String] URL path
+    # @param params [Hash] query parameters
+    # @return [Response]
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    # Performs a GET request to an absolute URL.
+    # Used for endpoints not on the base API (e.g., Launchpad).
+    # @param url [String] absolute URL
+    # @param params [Hash] query parameters
+    # @return [Response]
+    def get_absolute(url, params: {})
+      request(:get, url, params: params)
+    end
+
+    # Performs a POST request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def post(path, body: nil)
+      request(:post, path, body: body)
+    end
+
+    # Performs a PUT request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def put(path, body: nil)
+      request(:put, path, body: body)
+    end
+
+    # Performs a DELETE request.
+    # @param path [String] URL path
+    # @return [Response]
+    def delete(path)
+      request(:delete, path)
+    end
+
+    # Performs a POST request with raw binary data.
+    # Used for file uploads (attachments).
+    # @param path [String] URL path
+    # @param body [String, IO] raw binary data
+    # @param content_type [String] MIME content type
+    # @return [Response]
+    def post_raw(path, body:, content_type:)
+      url = build_url(path)
+      single_request_raw(:post, url, body: body, content_type: content_type, attempt: 1)
+    end
+
+    # Fetches all pages of a paginated resource.
+    # @param path [String] initial URL path
+    # @param params [Hash] query parameters
+    # @yield [Hash] each item from the response
+    # @return [Enumerator] if no block given
+    def paginate(path, params: {}, &block)
+      return to_enum(:paginate, path, params: params) unless block
+
+      base_url = build_url(path)
+      url = base_url
+      page = 0
+
+      loop do
+        page += 1
+        break if page > @config.max_pages
+
+        @hooks.on_paginate(url, page)
+        response = get(url, params: page == 1 ? params : {})
+
+        Security.check_body_size!(response.body, Security::MAX_RESPONSE_BODY_BYTES)
+
+        begin
+          items = JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Basecamp::APIError.new("Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}")
+        end
+        items.each(&block)
+
+        next_url = parse_next_link(response.headers["Link"])
+        break if next_url.nil?
+
+        next_url = Security.resolve_url(url, next_url)
+
+        unless Security.same_origin?(next_url, base_url)
+          raise Basecamp::APIError.new(
+            "Pagination Link header points to different origin: #{Security.truncate(next_url)}"
+          )
+        end
+
+        url = next_url
+      end
+    end
+
+    # Fetches all pages of a paginated resource, extracting items from a key.
+    # Use this for endpoints that return objects like { "events": [...] }.
+    # @param path [String] initial URL path
+    # @param key [String] the key containing the array of items
+    # @param params [Hash] query parameters
+    # @yield [Hash] each item from the response
+    # @return [Enumerator] if no block given
+    def paginate_key(path, key:, params: {}, &block)
+      return to_enum(:paginate_key, path, key: key, params: params) unless block
+
+      base_url = build_url(path)
+      url = base_url
+      page = 0
+
+      loop do
+        page += 1
+        break if page > @config.max_pages
+
+        @hooks.on_paginate(url, page)
+        response = get(url, params: page == 1 ? params : {})
+
+        Security.check_body_size!(response.body, Security::MAX_RESPONSE_BODY_BYTES)
+
+        begin
+          data = JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Basecamp::APIError.new("Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}")
+        end
+        unless data.key?(key)
+          warn "[Basecamp SDK] paginate_key: expected key '#{key}' not found in response (page #{page})"
+        end
+        items = data[key] || []
+        items.each(&block)
+
+        next_url = parse_next_link(response.headers["Link"])
+        break if next_url.nil?
+
+        next_url = Security.resolve_url(url, next_url)
+
+        unless Security.same_origin?(next_url, base_url)
+          raise Basecamp::APIError.new(
+            "Pagination Link header points to different origin: #{Security.truncate(next_url)}"
+          )
+        end
+
+        url = next_url
+      end
+    end
+
+    private
+
+    def build_faraday_client
+      Faraday.new(url: @config.base_url) do |f|
+        f.options.timeout = @config.timeout
+        f.options.open_timeout = 10
+        f.request :json
+        f.response :raise_error
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, path, params: {}, body: nil)
+      url = build_url(path)
+
+      # Mutations don't retry on 429/5xx to avoid duplicating data
+      if method == :get
+        request_with_retry(method, url, params: params)
+      else
+        single_request(method, url, params: params, body: body, attempt: 1)
+      end
+    end
+
+    def request_with_retry(method, url, params: {})
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+        break if attempt > @config.max_retries
+
+        begin
+          return single_request(method, url, params: params, body: nil, attempt: attempt)
+        rescue Basecamp::RateLimitError, Basecamp::NetworkError, Basecamp::APIError => e
+          raise e unless e.retryable?
+
+          last_error = e
+
+          # Don't sleep if this was the last attempt
+          break if attempt >= @config.max_retries
+
+          delay = calculate_delay(attempt, e.retry_after)
+
+          @hooks.on_retry(RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt), attempt + 1, e,
+                          delay)
+          sleep(delay)
+        end
+      end
+
+      raise last_error || Basecamp::APIError.new("Request failed after #{@config.max_retries} retries")
+    end
+
+    def single_request(method, url, params:, body:, attempt:, retry_count: 0)
+      info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
+      @hooks.on_request_start(info)
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      begin
+        response = @faraday.run_request(method, url, body, request_headers) do |req|
+          req.params.merge!(params) if params.any?
+        end
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        result = RequestResult.new(status_code: response.status, duration: duration)
+        @hooks.on_request_end(info, result)
+
+        Response.new(
+          body: response.body,
+          status: response.status,
+          headers: response.headers
+        )
+      rescue Faraday::ClientError => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = handle_error(e)
+        result = RequestResult.new(
+          status_code: e.response&.dig(:status),
+          duration: duration,
+          error: error,
+          retry_after: error.respond_to?(:retry_after) ? error.retry_after : nil
+        )
+        @hooks.on_request_end(info, result)
+
+        # After a successful token refresh on 401, retry the request once
+        if error.is_a?(Basecamp::AuthError) && error.http_status == 401 && retry_count < 1 && @token_refreshed
+          @token_refreshed = false
+          return single_request(method, url, params: params, body: body, attempt: attempt, retry_count: retry_count + 1)
+        end
+
+        raise error
+      rescue Faraday::Error => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = Basecamp::NetworkError.new("Connection failed", cause: e)
+        result = RequestResult.new(duration: duration, error: error)
+        @hooks.on_request_end(info, result)
+        raise error
+      end
+    end
+
+    def request_headers
+      headers = {
+        "User-Agent" => USER_AGENT,
+        "Accept" => "application/json"
+      }
+      @auth_strategy.authenticate(headers)
+      headers
+    end
+
+    def single_request_raw(method, url, body:, content_type:, attempt:)
+      info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
+      @hooks.on_request_start(info)
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      begin
+        headers = request_headers.merge("Content-Type" => content_type)
+        response = @faraday.run_request(method, url, body, headers)
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        result = RequestResult.new(status_code: response.status, duration: duration)
+        @hooks.on_request_end(info, result)
+
+        Response.new(
+          body: response.body,
+          status: response.status,
+          headers: response.headers
+        )
+      rescue Faraday::ClientError => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = handle_error(e)
+        result = RequestResult.new(
+          status_code: e.response&.dig(:status),
+          duration: duration,
+          error: error,
+          retry_after: error.respond_to?(:retry_after) ? error.retry_after : nil
+        )
+        @hooks.on_request_end(info, result)
+        raise error
+      rescue Faraday::Error => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = Basecamp::NetworkError.new("Connection failed", cause: e)
+        result = RequestResult.new(duration: duration, error: error)
+        @hooks.on_request_end(info, result)
+        raise error
+      end
+    end
+
+    def handle_error(error)
+      status = error.response&.dig(:status)
+      body = error.response&.dig(:body)
+      headers = error.response&.dig(:headers) || {}
+
+      retry_after = parse_retry_after(headers["Retry-After"] || headers["retry-after"])
+
+      case status
+      when 401
+        # Try token refresh; flag for caller to retry
+        @token_refreshed = @token_provider&.refreshable? && @token_provider.refresh
+
+        Basecamp::AuthError.new("Authentication failed")
+      when 403
+        Basecamp::ForbiddenError.new("Access denied")
+      when 404
+        Basecamp::NotFoundError.new("Resource", "unknown")
+      when 429
+        Basecamp::RateLimitError.new(retry_after: retry_after)
+      when 400, 422
+        message = Security.truncate(Basecamp.parse_error_message(body) || "Validation failed")
+        Basecamp::ValidationError.new(message, http_status: status)
+      when 500
+        Basecamp::APIError.new("Server error (500)", http_status: 500)
+      when 502, 503, 504
+        Basecamp::APIError.new("Gateway error (#{status})", http_status: status, retryable: true)
+      else
+        message = Security.truncate(Basecamp.parse_error_message(body) || "Request failed (HTTP #{status})")
+        Basecamp::APIError.from_status(status || 0, message)
+      end
+    end
+
+    def build_url(path)
+      if path.start_with?("https://")
+        return path
+      elsif path.start_with?("http://")
+        raise Basecamp::UsageError.new("URL must use HTTPS: #{path}")
+      end
+
+      path = "/#{path}" unless path.start_with?("/")
+      "#{@config.base_url}#{path}"
+    end
+
+    def calculate_delay(attempt, server_retry_after)
+      return server_retry_after if server_retry_after&.positive?
+
+      # Exponential backoff: base_delay * 2^(attempt-1) + jitter
+      base = @config.base_delay * (2**(attempt - 1))
+      jitter = rand * @config.max_jitter
+      base + jitter
+    end
+
+    def parse_retry_after(value)
+      return nil if value.nil? || value.empty?
+
+      # Try parsing as seconds (integer)
+      seconds = Integer(value, exception: false)
+      return seconds if seconds&.positive?
+
+      # Try parsing as HTTP-date
+      begin
+        date = Time.httpdate(value)
+        diff = (date - Time.now).to_i
+        return diff if diff.positive?
+      rescue ArgumentError
+        # Not a valid HTTP-date
+      end
+
+      nil
+    end
+
+    def parse_next_link(link_header)
+      return nil if link_header.nil? || link_header.empty?
+
+      link_header.split(",").each do |part|
+        part = part.strip
+        next unless part.include?('rel="next"')
+
+        match = part.match(/<([^>]+)>/)
+        return match[1] if match
+      end
+
+      nil
+    end
+  end
+
+  # Wraps an HTTP response.
+  class Response
+    # @return [String] response body
+    attr_reader :body
+
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [Hash] response headers
+    attr_reader :headers
+
+    def initialize(body:, status:, headers:)
+      @body = body
+      @status = status
+      @headers = headers
+    end
+
+    # Parses the response body as JSON.
+    # @return [Hash, Array]
+    def json
+      @json ||= begin
+        Security.check_body_size!(@body, Security::MAX_RESPONSE_BODY_BYTES)
+        JSON.parse(@body)
+      end
+    end
+
+    # Returns whether the response was successful (2xx).
+    # @return [Boolean]
+    def success?
+      status >= 200 && status < 300
+    end
+  end
+end

data/lib/basecamp/logger_hooks.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Hooks implementation that logs to Ruby's Logger.
+  #
+  # @example
+  #   require "logger"
+  #   logger = Logger.new($stdout)
+  #   hooks = Basecamp::LoggerHooks.new(logger)
+  #   client = Basecamp::Client.new(config: config, token_provider: provider, hooks: hooks)
+  class LoggerHooks
+    include Hooks
+
+    # @param logger [Logger] Ruby logger instance
+    # @param level [Symbol] log level (:debug, :info, :warn, :error)
+    def initialize(logger, level: :debug)
+      @logger = logger
+      @level = level
+    end
+
+    def on_request_start(info)
+      @logger.send(@level, "HTTP #{info.method} #{info.url} (attempt #{info.attempt})")
+    end
+
+    def on_request_end(info, result)
+      if result.error
+        @logger.send(@level, "HTTP #{info.method} #{info.url} failed: #{result.error.message}")
+      else
+        cache_info = result.from_cache ? " (cached)" : ""
+        @logger.send(@level,
+                     "HTTP #{info.method} #{info.url} -> #{result.status_code}#{cache_info} (#{format("%.3f",
+                                                                                                      result.duration)}s)")
+      end
+    end
+
+    def on_retry(info, attempt, error, delay)
+      @logger.send(@level,
+                   "Retrying #{info.method} #{info.url} (attempt #{attempt}) in #{format("%.2f",
+                                                                                         delay)}s: #{error.message}")
+    end
+
+    def on_paginate(url, page)
+      @logger.send(@level, "Fetching page #{page}: #{url}")
+    end
+  end
+end

data/lib/basecamp/noop_hooks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # No-op implementation of Hooks.
+  # Used as the default when no hooks are configured.
+  class NoopHooks
+    include Hooks
+  end
+end

data/lib/basecamp/oauth/discovery.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Basecamp
+  # OAuth 2 helpers for Basecamp authentication.
+  module Oauth
+    # Default Basecamp/Launchpad OAuth server URL.
+    LAUNCHPAD_BASE_URL = "https://launchpad.37signals.com"
+
+    # Discoverer fetches OAuth 2 server configuration from discovery endpoints.
+    class Discoverer
+      # @param http_client [Faraday::Connection, nil] HTTP client (uses default if nil)
+      # @param timeout [Integer] Request timeout in seconds (default: 10)
+      def initialize(http_client: nil, timeout: 10)
+        @http_client = http_client || build_default_client(timeout)
+      end
+
+      # Discovers OAuth configuration from the well-known endpoint.
+      #
+      # Fetches the OAuth 2 Authorization Server Metadata from:
+      # `{base_url}/.well-known/oauth-authorization-server`
+      #
+      # @param base_url [String] The OAuth server's base URL (e.g., "https://launchpad.37signals.com")
+      # @return [Config] The OAuth server configuration
+      # @raise [OAuthError] on network or parsing errors
+      #
+      # @example
+      #   discoverer = Basecamp::Oauth::Discoverer.new
+      #   config = discoverer.discover("https://launchpad.37signals.com")
+      #   puts config.token_endpoint
+      #   # => "https://launchpad.37signals.com/authorization/token"
+      def discover(base_url)
+        Basecamp::Security.require_https_unless_localhost!(base_url, "discovery base URL")
+
+        normalized_base = base_url.chomp("/")
+        discovery_url = "#{normalized_base}/.well-known/oauth-authorization-server"
+
+        response = @http_client.get(discovery_url) do |req|
+          req.headers["Accept"] = "application/json"
+        end
+
+        unless response.success?
+          raise OAuthError.new(
+            "network",
+            "OAuth discovery failed with status #{response.status}: #{Basecamp::Security.truncate(response.body)}",
+            http_status: response.status
+          )
+        end
+
+        Basecamp::Security.check_body_size!(response.body, Basecamp::Security::MAX_ERROR_BODY_BYTES, "Discovery")
+
+        data = JSON.parse(response.body)
+        validate_discovery_response!(data)
+
+        Config.new(
+          issuer: data["issuer"],
+          authorization_endpoint: data["authorization_endpoint"],
+          token_endpoint: data["token_endpoint"],
+          registration_endpoint: data["registration_endpoint"],
+          scopes_supported: data["scopes_supported"]
+        )
+      rescue Faraday::Error => e
+        raise OAuthError.new("network", "OAuth discovery failed: #{e.message}", retryable: true)
+      rescue JSON::ParserError => e
+        raise OAuthError.new("api_error", "Failed to parse discovery response: #{e.message}")
+      end
+
+      private
+
+      def build_default_client(timeout)
+        Faraday.new do |conn|
+          conn.options.timeout = timeout
+          conn.options.open_timeout = timeout
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def validate_discovery_response!(data)
+        missing = []
+        missing << "issuer" unless data["issuer"]
+        missing << "authorization_endpoint" unless data["authorization_endpoint"]
+        missing << "token_endpoint" unless data["token_endpoint"]
+
+        return if missing.empty?
+
+        raise OAuthError.new(
+          "api_error",
+          "Invalid OAuth discovery response: missing required fields: #{missing.join(", ")}"
+        )
+      end
+    end
+
+    module_function
+
+    # Discovers OAuth configuration from the well-known endpoint.
+    #
+    # @param base_url [String] The OAuth server's base URL
+    # @param timeout [Integer] Request timeout in seconds (default: 10)
+    # @return [Config] The OAuth server configuration
+    #
+    # @example
+    #   config = Basecamp::Oauth.discover("https://launchpad.37signals.com")
+    def discover(base_url, timeout: 10)
+      Discoverer.new(timeout: timeout).discover(base_url)
+    end
+
+    # Discovers OAuth configuration from Basecamp's Launchpad server.
+    #
+    # Convenience function that calls discover() with the Launchpad base URL.
+    #
+    # @param timeout [Integer] Request timeout in seconds (default: 10)
+    # @return [Config] The OAuth server configuration
+    #
+    # @example
+    #   config = Basecamp::Oauth.discover_launchpad
+    #   # Use config.authorization_endpoint to start OAuth flow
+    def discover_launchpad(timeout: 10)
+      discover(LAUNCHPAD_BASE_URL, timeout: timeout)
+    end
+  end
+end