basecamp-sdk 0.5.0 → 0.6.0

data/lib/basecamp/http.rb

@@ -80,6 +80,14 @@ module Basecamp
       single_request_raw(:post, url, body: body, content_type: content_type, attempt: 1)
     end
 
+    # Performs a GET request without retry logic.
+    # Used for the download flow where retry is not appropriate.
+    # @param url [String] absolute URL
+    # @return [Response]
+    def get_no_retry(url)
+      single_request(:get, url, params: {}, body: nil, attempt: 1)
+    end
+
     # Fetches all pages of a paginated resource.
     # @param path [String] initial URL path
     # @param params [Hash] query parameters
@@ -104,7 +112,7 @@ module Basecamp
         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)}")
+          raise Basecamp::ApiError.new("Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}")
         end
         items.each(&block)
 
@@ -114,7 +122,7 @@ module Basecamp
         next_url = Security.resolve_url(url, next_url)
 
         unless Security.same_origin?(next_url, base_url)
-          raise Basecamp::APIError.new(
+          raise Basecamp::ApiError.new(
             "Pagination Link header points to different origin: #{Security.truncate(next_url)}"
           )
         end
@@ -149,7 +157,7 @@ module Basecamp
         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)}")
+          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})"
@@ -163,7 +171,7 @@ module Basecamp
         next_url = Security.resolve_url(url, next_url)
 
         unless Security.same_origin?(next_url, base_url)
-          raise Basecamp::APIError.new(
+          raise Basecamp::ApiError.new(
             "Pagination Link header points to different origin: #{Security.truncate(next_url)}"
           )
         end
@@ -188,7 +196,7 @@ module Basecamp
       begin
         first_data = JSON.parse(first_response.body)
       rescue JSON::ParserError => e
-        raise Basecamp::APIError.new(
+        raise Basecamp::ApiError.new(
           "Failed to parse paginated response (page 1): #{Security.truncate(e.message)}"
         )
       end
@@ -208,7 +216,7 @@ module Basecamp
           next_url = Security.resolve_url(url, next_link)
 
           unless Security.same_origin?(next_url, base_url)
-            raise Basecamp::APIError.new(
+            raise Basecamp::ApiError.new(
               "Pagination Link header points to different origin: " \
               "#{Security.truncate(next_url)}"
             )
@@ -221,7 +229,7 @@ module Basecamp
           begin
             data = JSON.parse(response.body)
           rescue JSON::ParserError => e
-            raise Basecamp::APIError.new(
+            raise Basecamp::ApiError.new(
               "Failed to parse paginated response (page #{page}): " \
               "#{Security.truncate(e.message)}"
             )
@@ -271,7 +279,7 @@ module Basecamp
 
         begin
           return single_request(method, url, params: params, body: nil, attempt: attempt)
-        rescue Basecamp::RateLimitError, Basecamp::NetworkError, Basecamp::APIError => e
+        rescue Basecamp::RateLimitError, Basecamp::NetworkError, Basecamp::ApiError => e
           raise e unless e.retryable?
 
           last_error = e
@@ -287,7 +295,7 @@ module Basecamp
         end
       end
 
-      raise last_error || Basecamp::APIError.new("Request failed after #{@config.max_retries} retries")
+      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)
@@ -401,19 +409,20 @@ module Basecamp
       when 403
         Basecamp::ForbiddenError.new("Access denied")
       when 404
-        Basecamp::NotFoundError.new("Resource", "unknown")
+        message = Security.truncate(Basecamp.parse_error_message(body) || "Not found")
+        Basecamp::NotFoundError.new(message: message)
       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, retryable: true)
+        Basecamp::ApiError.new("Server error (500)", http_status: 500, retryable: true)
       when 502, 503, 504
-        Basecamp::APIError.new("Gateway error (#{status})", http_status: status, retryable: true)
+        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)
+        Basecamp::ApiError.from_status(status || 0, message)
       end
 
       err.instance_variable_set(:@request_id, request_id) if request_id

data/lib/basecamp/network_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when there's a network error (connection, timeout, DNS).
+  class NetworkError < Error
+    def initialize(message = "Network error", cause: nil)
+      super(
+        code: ErrorCode::NETWORK,
+        message: message,
+        hint: cause&.message || "Check your network connection",
+        retryable: true,
+        cause: cause
+      )
+    end
+  end
+end

data/lib/basecamp/not_found_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when a resource is not found (404).
+  class NotFoundError < Error
+    def initialize(resource = nil, identifier = nil, message: nil, hint: nil)
+      message ||= if resource
+        "#{resource} not found: #{identifier}"
+      else
+        "Not found"
+      end
+      super(
+        code: ErrorCode::NOT_FOUND,
+        message: message,
+        hint: hint,
+        http_status: 404
+      )
+    end
+  end
+end

data/lib/basecamp/oauth/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # OAuth 2 server configuration from discovery endpoint.
+    #
+    # @attr issuer [String] The authorization server's issuer identifier
+    # @attr authorization_endpoint [String] URL of the authorization endpoint
+    # @attr token_endpoint [String] URL of the token endpoint
+    # @attr registration_endpoint [String, nil] URL of the dynamic client registration endpoint
+    # @attr scopes_supported [Array<String>, nil] List of OAuth 2 scopes supported
+    Config = Data.define(
+      :issuer,
+      :authorization_endpoint,
+      :token_endpoint,
+      :registration_endpoint,
+      :scopes_supported
+    ) do
+      def initialize(
+        issuer:,
+        authorization_endpoint:,
+        token_endpoint:,
+        registration_endpoint: nil,
+        scopes_supported: nil
+      )
+        super
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/discovery.rb

@@ -4,13 +4,9 @@ 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
+    # Fetches OAuth 2 server configuration from discovery endpoints.
+    class Discovery
       # @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)
@@ -24,11 +20,11 @@ module Basecamp
       #
       # @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
+      # @raise [OauthError] on network or parsing errors
       #
       # @example
-      #   discoverer = Basecamp::Oauth::Discoverer.new
-      #   config = discoverer.discover("https://launchpad.37signals.com")
+      #   discovery = Basecamp::Oauth::Discovery.new
+      #   config = discovery.discover("https://launchpad.37signals.com")
       #   puts config.token_endpoint
       #   # => "https://launchpad.37signals.com/authorization/token"
       def discover(base_url)
@@ -42,7 +38,7 @@ module Basecamp
         end
 
         unless response.success?
-          raise OAuthError.new(
+          raise OauthError.new(
             "network",
             "OAuth discovery failed with status #{response.status}: #{Basecamp::Security.truncate(response.body)}",
             http_status: response.status
@@ -62,9 +58,9 @@ module Basecamp
           scopes_supported: data["scopes_supported"]
         )
       rescue Faraday::Error => e
-        raise OAuthError.new("network", "OAuth discovery failed: #{e.message}", retryable: true)
+        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}")
+        raise OauthError.new("api_error", "Failed to parse discovery response: #{e.message}")
       end
 
       private
@@ -85,39 +81,11 @@ module Basecamp
 
         return if missing.empty?
 
-        raise OAuthError.new(
+        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

data/lib/basecamp/oauth/exchange.rb

@@ -5,10 +5,9 @@ require "json"
 require "uri"
 
 module Basecamp
-  # OAuth 2 helpers for Basecamp authentication.
   module Oauth
-    # Exchanger handles OAuth 2 token exchange and refresh operations.
-    class Exchanger
+    # Handles OAuth 2 token exchange and refresh operations.
+    class Exchange
       # @param http_client [Faraday::Connection, nil] HTTP client (uses default if nil)
       # @param timeout [Integer] Request timeout in seconds (default: 30)
       def initialize(http_client: nil, timeout: 30)
@@ -22,10 +21,10 @@ module Basecamp
       #
       # @param request [ExchangeRequest] Exchange request parameters
       # @return [Token] The token response
-      # @raise [OAuthError] on validation, network, or authentication errors
+      # @raise [OauthError] on validation, network, or authentication errors
       #
       # @example Standard OAuth 2
-      #   token = exchanger.exchange(ExchangeRequest.new(
+      #   token = exchange.exchange(ExchangeRequest.new(
       #     token_endpoint: config.token_endpoint,
       #     code: "auth_code_from_callback",
       #     redirect_uri: "https://myapp.com/callback",
@@ -34,7 +33,7 @@ module Basecamp
       #   ))
       #
       # @example Launchpad legacy format
-      #   token = exchanger.exchange(ExchangeRequest.new(
+      #   token = exchange.exchange(ExchangeRequest.new(
       #     token_endpoint: config.token_endpoint,
       #     code: "auth_code",
       #     redirect_uri: "https://myapp.com/callback",
@@ -56,10 +55,10 @@ module Basecamp
       #
       # @param request [RefreshRequest] Refresh request parameters
       # @return [Token] The new token response
-      # @raise [OAuthError] on validation, network, or authentication errors
+      # @raise [OauthError] on validation, network, or authentication errors
       #
       # @example Standard OAuth 2
-      #   new_token = exchanger.refresh(RefreshRequest.new(
+      #   new_token = exchange.refresh(RefreshRequest.new(
       #     token_endpoint: config.token_endpoint,
       #     refresh_token: old_token.refresh_token,
       #     client_id: "my_client_id",
@@ -67,7 +66,7 @@ module Basecamp
       #   ))
       #
       # @example Launchpad legacy format
-      #   new_token = exchanger.refresh(RefreshRequest.new(
+      #   new_token = exchange.refresh(RefreshRequest.new(
       #     token_endpoint: config.token_endpoint,
       #     refresh_token: old_token.refresh_token,
       #     use_legacy_format: true
@@ -90,15 +89,15 @@ module Basecamp
       end
 
       def validate_exchange_request!(request)
-        raise OAuthError.new("validation", "Token endpoint is required") if request.token_endpoint.to_s.empty?
-        raise OAuthError.new("validation", "Authorization code is required") if request.code.to_s.empty?
-        raise OAuthError.new("validation", "Redirect URI is required") if request.redirect_uri.to_s.empty?
-        raise OAuthError.new("validation", "Client ID is required") if request.client_id.to_s.empty?
+        raise OauthError.new("validation", "Token endpoint is required") if request.token_endpoint.to_s.empty?
+        raise OauthError.new("validation", "Authorization code is required") if request.code.to_s.empty?
+        raise OauthError.new("validation", "Redirect URI is required") if request.redirect_uri.to_s.empty?
+        raise OauthError.new("validation", "Client ID is required") if request.client_id.to_s.empty?
       end
 
       def validate_refresh_request!(request)
-        raise OAuthError.new("validation", "Token endpoint is required") if request.token_endpoint.to_s.empty?
-        raise OAuthError.new("validation", "Refresh token is required") if request.refresh_token.to_s.empty?
+        raise OauthError.new("validation", "Token endpoint is required") if request.token_endpoint.to_s.empty?
+        raise OauthError.new("validation", "Refresh token is required") if request.refresh_token.to_s.empty?
       end
 
       def build_exchange_params(request)
@@ -150,9 +149,9 @@ module Basecamp
 
         parse_token_response(response)
       rescue Faraday::TimeoutError
-        raise OAuthError.new("network", "Token request timed out", retryable: true)
+        raise OauthError.new("network", "Token request timed out", retryable: true)
       rescue Faraday::Error => e
-        raise OAuthError.new("network", "Token request failed: #{e.message}", retryable: true)
+        raise OauthError.new("network", "Token request failed: #{e.message}", retryable: true)
       end
 
       def parse_token_response(response)
@@ -162,7 +161,7 @@ module Basecamp
 
         handle_error_response(response.status, data) unless response.success?
 
-        raise OAuthError.new("api_error", "Token response missing access_token") unless data["access_token"]
+        raise OauthError.new("api_error", "Token response missing access_token") unless data["access_token"]
 
         Token.new(
           access_token: data["access_token"],
@@ -172,7 +171,7 @@ module Basecamp
           scope: data["scope"]
         )
       rescue JSON::ParserError
-        raise OAuthError.new(
+        raise OauthError.new(
           "api_error",
           "Failed to parse token response: #{Basecamp::Security.truncate(response.body)}",
           http_status: response.status
@@ -183,7 +182,7 @@ module Basecamp
         error_msg = Basecamp::Security.truncate(data["error_description"] || data["error"] || "Token request failed")
 
         if status == 401 || data["error"] == "invalid_grant"
-          raise OAuthError.new(
+          raise OauthError.new(
             "auth",
             error_msg,
             http_status: status,
@@ -191,101 +190,8 @@ module Basecamp
           )
         end
 
-        raise OAuthError.new("api_error", error_msg, http_status: status)
+        raise OauthError.new("api_error", error_msg, http_status: status)
       end
     end
-
-    module_function
-
-    # Exchanges an authorization code for access and refresh tokens.
-    #
-    # @param token_endpoint [String] URL of the token endpoint
-    # @param code [String] The authorization code
-    # @param redirect_uri [String] The redirect URI used in the authorization request
-    # @param client_id [String] The client identifier
-    # @param client_secret [String, nil] The client secret
-    # @param code_verifier [String, nil] PKCE code verifier
-    # @param use_legacy_format [Boolean] Use Launchpad's non-standard format
-    # @param timeout [Integer] Request timeout in seconds (default: 30)
-    # @return [Token] The token response
-    #
-    # @example
-    #   token = Basecamp::Oauth.exchange_code(
-    #     token_endpoint: config.token_endpoint,
-    #     code: "auth_code",
-    #     redirect_uri: "https://myapp.com/callback",
-    #     client_id: ENV["BASECAMP_CLIENT_ID"],
-    #     client_secret: ENV["BASECAMP_CLIENT_SECRET"],
-    #     use_legacy_format: true
-    #   )
-    def exchange_code(
-      token_endpoint:,
-      code:,
-      redirect_uri:,
-      client_id:,
-      client_secret: nil,
-      code_verifier: nil,
-      use_legacy_format: false,
-      timeout: 30
-    )
-      request = ExchangeRequest.new(
-        token_endpoint: token_endpoint,
-        code: code,
-        redirect_uri: redirect_uri,
-        client_id: client_id,
-        client_secret: client_secret,
-        code_verifier: code_verifier,
-        use_legacy_format: use_legacy_format
-      )
-      Exchanger.new(timeout: timeout).exchange(request)
-    end
-
-    # Refreshes an access token using a refresh token.
-    #
-    # @param token_endpoint [String] URL of the token endpoint
-    # @param refresh_token [String] The refresh token
-    # @param client_id [String, nil] The client identifier
-    # @param client_secret [String, nil] The client secret
-    # @param use_legacy_format [Boolean] Use Launchpad's non-standard format
-    # @param timeout [Integer] Request timeout in seconds (default: 30)
-    # @return [Token] The new token response
-    #
-    # @example
-    #   new_token = Basecamp::Oauth.refresh_token(
-    #     token_endpoint: config.token_endpoint,
-    #     refresh_token: old_token.refresh_token,
-    #     use_legacy_format: true
-    #   )
-    def refresh_token(
-      token_endpoint:,
-      refresh_token:,
-      client_id: nil,
-      client_secret: nil,
-      use_legacy_format: false,
-      timeout: 30
-    )
-      request = RefreshRequest.new(
-        token_endpoint: token_endpoint,
-        refresh_token: refresh_token,
-        client_id: client_id,
-        client_secret: client_secret,
-        use_legacy_format: use_legacy_format
-      )
-      Exchanger.new(timeout: timeout).refresh(request)
-    end
-
-    # Checks if a token is expired or about to expire.
-    #
-    # @param token [Token] The token to check
-    # @param buffer_seconds [Integer] Buffer time before actual expiration (default: 60)
-    # @return [Boolean] true if expired or will expire within buffer time
-    #
-    # @example
-    #   if Basecamp::Oauth.token_expired?(token)
-    #     token = Basecamp::Oauth.refresh_token(...)
-    #   end
-    def token_expired?(token, buffer_seconds = 60)
-      token.expired?(buffer_seconds)
-    end
   end
 end

data/lib/basecamp/oauth/exchange_request.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # Parameters for exchanging an authorization code for tokens.
+    #
+    # @attr token_endpoint [String] URL of the token endpoint
+    # @attr code [String] The authorization code received from the authorization server
+    # @attr redirect_uri [String] The redirect URI used in the authorization request
+    # @attr client_id [String] The client identifier
+    # @attr client_secret [String, nil] The client secret (optional for public clients)
+    # @attr code_verifier [String, nil] PKCE code verifier (optional)
+    # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
+    ExchangeRequest = Data.define(
+      :token_endpoint,
+      :code,
+      :redirect_uri,
+      :client_id,
+      :client_secret,
+      :code_verifier,
+      :use_legacy_format
+    ) do
+      def initialize(
+        token_endpoint:,
+        code:,
+        redirect_uri:,
+        client_id:,
+        client_secret: nil,
+        code_verifier: nil,
+        use_legacy_format: false
+      )
+        super
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/{errors.rb → oauth_error.rb}

@@ -8,7 +8,7 @@ module Basecamp
     # @attr http_status [Integer, nil] HTTP status code if applicable
     # @attr hint [String, nil] Helpful hint for resolving the error
     # @attr retryable [Boolean] Whether the request can be retried
-    class OAuthError < StandardError
+    class OauthError < StandardError
       attr_reader :type, :http_status, :hint, :retryable
 
       # @param type [String] Error type

data/lib/basecamp/oauth/refresh_request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # Parameters for refreshing an access token.
+    #
+    # @attr token_endpoint [String] URL of the token endpoint
+    # @attr refresh_token [String] The refresh token
+    # @attr client_id [String, nil] The client identifier (optional)
+    # @attr client_secret [String, nil] The client secret (optional)
+    # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
+    RefreshRequest = Data.define(
+      :token_endpoint,
+      :refresh_token,
+      :client_id,
+      :client_secret,
+      :use_legacy_format
+    ) do
+      def initialize(
+        token_endpoint:,
+        refresh_token:,
+        client_id: nil,
+        client_secret: nil,
+        use_legacy_format: false
+      )
+        super
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/token.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # OAuth 2 access token response.
+    #
+    # @attr access_token [String] The access token string
+    # @attr token_type [String] Token type (usually "Bearer")
+    # @attr refresh_token [String, nil] The refresh token string
+    # @attr expires_in [Integer, nil] Lifetime of the access token in seconds
+    # @attr expires_at [Time, nil] Calculated expiration time
+    # @attr scope [String, nil] OAuth scope granted
+    Token = Data.define(
+      :access_token,
+      :token_type,
+      :refresh_token,
+      :expires_in,
+      :expires_at,
+      :scope
+    ) do
+      def initialize(
+        access_token:,
+        token_type: "Bearer",
+        refresh_token: nil,
+        expires_in: nil,
+        expires_at: nil,
+        scope: nil
+      )
+        # Calculate expires_at from expires_in if not provided
+        calculated_expires_at = expires_at || (expires_in ? Time.now + expires_in : nil)
+        super(
+          access_token: access_token,
+          token_type: token_type,
+          refresh_token: refresh_token,
+          expires_in: expires_in,
+          expires_at: calculated_expires_at,
+          scope: scope
+        )
+      end
+
+      # Checks if the token is expired or about to expire.
+      #
+      # @param buffer_seconds [Integer] Buffer time before actual expiration (default: 60)
+      # @return [Boolean] true if expired or will expire within buffer time
+      def expired?(buffer_seconds = 60)
+        return false unless expires_at
+
+        Time.now + buffer_seconds >= expires_at
+      end
+    end
+  end
+end