basecamp-sdk 0.4.0 → 0.6.0

data/lib/basecamp/oauth.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "oauth/errors"
-require_relative "oauth/types"
-require_relative "oauth/discovery"
-require_relative "oauth/exchange"
-
 module Basecamp
   # OAuth 2 module for Basecamp SDK.
   #
@@ -49,8 +44,45 @@ module Basecamp
   #
   # @see https://github.com/basecamp/api/blob/master/sections/authentication.md
   module Oauth
-    # Re-export constants
-    # @return [String] Default Launchpad base URL
-    # LAUNCHPAD_BASE_URL is defined in discovery.rb
+    LAUNCHPAD_BASE_URL = "https://launchpad.37signals.com"
+
+    def self.discover(base_url, timeout: 10)
+      Discovery.new(timeout: timeout).discover(base_url)
+    end
+
+    def self.discover_launchpad(timeout: 10)
+      discover(LAUNCHPAD_BASE_URL, timeout: timeout)
+    end
+
+    def self.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
+      )
+      Exchange.new(timeout: timeout).exchange(request)
+    end
+
+    def self.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
+      )
+      Exchange.new(timeout: timeout).refresh(request)
+    end
+
+    def self.token_expired?(token, buffer_seconds = 60)
+      token.expired?(buffer_seconds)
+    end
   end
 end

data/lib/basecamp/operation_info.rb

@@ -7,11 +7,4 @@ module Basecamp
       super
     end
   end
-
-  # Result information for completed service operations.
-  OperationResult = Data.define(:duration_ms, :error) do
-    def initialize(duration_ms: 0, error: nil)
-      super
-    end
-  end
 end

data/lib/basecamp/operation_result.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Result information for completed service operations.
+  OperationResult = Data.define(:duration_ms, :error) do
+    def initialize(duration_ms: 0, error: nil)
+      super
+    end
+  end
+end

data/lib/basecamp/rate_limit_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when rate limited (429).
+  class RateLimitError < Error
+    def initialize(retry_after: nil, cause: nil)
+      hint = retry_after ? "Try again in #{retry_after} seconds" : "Please slow down requests"
+      super(
+        code: ErrorCode::RATE_LIMIT,
+        message: "Rate limit exceeded",
+        hint: hint,
+        http_status: 429,
+        retryable: true,
+        retry_after: retry_after,
+        cause: cause
+      )
+    end
+  end
+end

data/lib/basecamp/security.rb

@@ -54,7 +54,7 @@ module Basecamp
       return if body.nil?
 
       if body.bytesize > max
-        raise Basecamp::APIError.new(
+        raise Basecamp::ApiError.new(
           "#{label} body too large (#{body.bytesize} bytes, max #{max})"
         )
       end

data/lib/basecamp/usage_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when there's a usage error (invalid arguments, missing config).
+  class UsageError < Error
+    def initialize(message, hint: nil)
+      super(code: ErrorCode::USAGE, message: message, hint: hint)
+    end
+  end
+end

data/lib/basecamp/validation_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised for validation errors (400, 422).
+  class ValidationError < Error
+    def initialize(message, hint: nil, http_status: 400)
+      super(
+        code: ErrorCode::VALIDATION,
+        message: message,
+        hint: hint,
+        http_status: http_status
+      )
+    end
+  end
+end

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
   API_VERSION = "2026-01-26"
 end

data/lib/basecamp/webhooks/rack_middleware.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "receiver"
-
 module Basecamp
   module Webhooks
     # Rack middleware that intercepts POST requests to a configurable path

data/lib/basecamp/webhooks/receiver.rb

@@ -1,13 +1,9 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "event"
-require_relative "verify"
 
 module Basecamp
   module Webhooks
-    class VerificationError < StandardError; end
-
     # Receives and routes webhook events from Basecamp.
     # Framework-agnostic: works with raw body strings and a header accessor.
     class Receiver

data/lib/basecamp/webhooks/verification_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Webhooks
+    class VerificationError < StandardError; end
+  end
+end

data/lib/basecamp.rb

@@ -2,32 +2,10 @@
 
 require "zeitwerk"
 
-# Set up Zeitwerk loader
 loader = Zeitwerk::Loader.for_gem
-# No custom inflections - use standard Ruby camelcase (Http, Oauth, etc.)
-
-# Ignore hand-written services - we use generated services instead (spec-conformant)
-# EXCEPT: base_service.rb (infrastructure) and authorization_service.rb (OAuth, not in spec)
-loader.ignore("#{__dir__}/basecamp/services")
-
-# Collapse the generated directory so Basecamp::Generated::Services becomes Basecamp::Services
 loader.collapse("#{__dir__}/basecamp/generated")
-
-# Ignore errors.rb - it defines multiple classes, loaded explicitly below
-loader.ignore("#{__dir__}/basecamp/errors.rb")
-# Ignore auth_strategy.rb - defines both AuthStrategy and BearerAuth
-loader.ignore("#{__dir__}/basecamp/auth_strategy.rb")
-# Ignore operation_info.rb - defines both OperationInfo and OperationResult
-loader.ignore("#{__dir__}/basecamp/operation_info.rb")
 loader.setup
 
-# Load infrastructure that generated services depend on
-require_relative "basecamp/errors"
-require_relative "basecamp/auth_strategy"
-require_relative "basecamp/operation_info"
-require_relative "basecamp/services/base_service"
-require_relative "basecamp/services/authorization_service"
-
 # Load generated types if available
 begin
   require_relative "basecamp/generated/types"
@@ -104,4 +82,66 @@ module Basecamp
 
     account_id ? client.for_account(account_id) : client
   end
+
+  # Maps an HTTP response to the appropriate error class.
+  #
+  # @param status [Integer] HTTP status code
+  # @param body [String, nil] response body (will attempt JSON parse)
+  # @param retry_after [Integer, nil] Retry-After header value
+  # @return [Error]
+  def self.error_from_response(status, body = nil, retry_after: nil)
+    message = parse_error_message(body) || "Request failed"
+
+    case status
+    when 400, 422
+      ValidationError.new(message, http_status: status)
+    when 401
+      AuthError.new(message)
+    when 403
+      ForbiddenError.new(message)
+    when 404
+      NotFoundError.new(message: message)
+    when 429
+      RateLimitError.new(retry_after: retry_after)
+    when 500
+      ApiError.new("Server error (500)", http_status: 500, retryable: true)
+    when 502, 503, 504
+      ApiError.new("Gateway error (#{status})", http_status: status, retryable: true)
+    else
+      ApiError.from_status(status, message)
+    end
+  end
+
+  # Extracts a filename from the last path segment of a URL.
+  # Falls back to "download" if the URL is unparseable or has no path segments.
+  def self.filename_from_url(raw_url)
+    uri = URI.parse(raw_url)
+    path = uri.path
+    return "download" if path.nil? || path.empty? || path == "/" || path.end_with?("/")
+
+    segments = path.split("/").reject(&:empty?)
+    return "download" if segments.empty?
+
+    last = segments.last
+    return "download" if last.nil? || last.empty? || last == "." || last == "/"
+
+    URI::RFC2396_PARSER.unescape(last)
+  rescue URI::InvalidURIError
+    "download"
+  end
+
+  # Parses error message from response body.
+  # @param body [String, nil]
+  # @return [String, nil]
+  def self.parse_error_message(body)
+    return nil if body.nil? || body.empty?
+
+    Security.check_body_size!(body, Security::MAX_ERROR_BODY_BYTES, "Error")
+
+    data = JSON.parse(body)
+    msg = data["error"] || data["message"]
+    msg ? Security.truncate(msg) : nil
+  rescue JSON::ParserError, ApiError
+    nil
+  end
 end

data/scripts/generate-services.rb

@@ -57,7 +57,7 @@ class ServiceGenerator
         CreateCardColumn MoveCardColumn
       ],
       'CardSteps' => %w[
-        CreateCardStep UpdateCardStep SetCardStepCompletion
+        GetCardStep CreateCardStep UpdateCardStep SetCardStepCompletion
         RepositionCardStep
       ]
     },
@@ -559,7 +559,7 @@ class ServiceGenerator
         ruby_name = to_snake_case(b[:name])
         type = b[:type] || 'Object'
         type = "#{type}, nil" unless b[:required]
-        desc = b[:description] || ruby_name.gsub('_', ' ')
+        desc = (b[:description] || ruby_name.gsub('_', ' ')).gsub("\n", "\n      #   ")
         format_hint = b[:format_hint] ? " (#{b[:format_hint]})" : ''
         lines << "      # @param #{ruby_name} [#{type}] #{desc}#{format_hint}"
       end
@@ -570,7 +570,7 @@ class ServiceGenerator
       ruby_name = to_snake_case(q[:name])
       type = q[:type] || 'String'
       type = "#{type}, nil" unless q[:required]
-      desc = q[:description] || ruby_name.gsub('_', ' ')
+      desc = (q[:description] || ruby_name.gsub('_', ' ')).gsub("\n", "\n      #   ")
       lines << "      # @param #{ruby_name} [#{type}] #{desc}"
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-11 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -178,13 +178,24 @@ files:
 - Rakefile
 - basecamp-sdk.gemspec
 - lib/basecamp.rb
+- lib/basecamp/ambiguous_error.rb
+- lib/basecamp/api_error.rb
+- lib/basecamp/auth_error.rb
 - lib/basecamp/auth_strategy.rb
+- lib/basecamp/bearer_auth.rb
 - lib/basecamp/chain_hooks.rb
 - lib/basecamp/client.rb
 - lib/basecamp/config.rb
-- lib/basecamp/errors.rb
+- lib/basecamp/download_result.rb
+- lib/basecamp/error.rb
+- lib/basecamp/error_code.rb
+- lib/basecamp/exit_code.rb
+- lib/basecamp/forbidden_error.rb
 - lib/basecamp/generated/metadata.json
 - lib/basecamp/generated/services/attachments_service.rb
+- lib/basecamp/generated/services/authorization_service.rb
+- lib/basecamp/generated/services/automation_service.rb
+- lib/basecamp/generated/services/base_service.rb
 - lib/basecamp/generated/services/boosts_service.rb
 - lib/basecamp/generated/services/campfires_service.rb
 - lib/basecamp/generated/services/card_columns_service.rb
@@ -226,62 +237,34 @@ files:
 - lib/basecamp/hooks.rb
 - lib/basecamp/http.rb
 - lib/basecamp/logger_hooks.rb
+- lib/basecamp/network_error.rb
 - lib/basecamp/noop_hooks.rb
+- lib/basecamp/not_found_error.rb
 - lib/basecamp/oauth.rb
+- lib/basecamp/oauth/config.rb
 - lib/basecamp/oauth/discovery.rb
-- lib/basecamp/oauth/errors.rb
 - lib/basecamp/oauth/exchange.rb
+- lib/basecamp/oauth/exchange_request.rb
+- lib/basecamp/oauth/oauth_error.rb
 - lib/basecamp/oauth/pkce.rb
-- lib/basecamp/oauth/types.rb
+- lib/basecamp/oauth/refresh_request.rb
+- lib/basecamp/oauth/token.rb
 - lib/basecamp/oauth_token_provider.rb
 - lib/basecamp/operation_info.rb
+- lib/basecamp/operation_result.rb
+- lib/basecamp/rate_limit_error.rb
 - lib/basecamp/request_info.rb
 - lib/basecamp/request_result.rb
 - lib/basecamp/security.rb
-- lib/basecamp/services/attachments_service.rb
-- lib/basecamp/services/authorization_service.rb
-- lib/basecamp/services/base_service.rb
-- lib/basecamp/services/campfires_service.rb
-- lib/basecamp/services/card_columns_service.rb
-- lib/basecamp/services/card_steps_service.rb
-- lib/basecamp/services/card_tables_service.rb
-- lib/basecamp/services/cards_service.rb
-- lib/basecamp/services/checkins_service.rb
-- lib/basecamp/services/client_approvals_service.rb
-- lib/basecamp/services/client_correspondences_service.rb
-- lib/basecamp/services/client_replies_service.rb
-- lib/basecamp/services/comments_service.rb
-- lib/basecamp/services/documents_service.rb
-- lib/basecamp/services/events_service.rb
-- lib/basecamp/services/forwards_service.rb
-- lib/basecamp/services/lineup_service.rb
-- lib/basecamp/services/message_boards_service.rb
-- lib/basecamp/services/message_types_service.rb
-- lib/basecamp/services/messages_service.rb
-- lib/basecamp/services/people_service.rb
-- lib/basecamp/services/projects_service.rb
-- lib/basecamp/services/recordings_service.rb
-- lib/basecamp/services/reports_service.rb
-- lib/basecamp/services/schedules_service.rb
-- lib/basecamp/services/search_service.rb
-- lib/basecamp/services/subscriptions_service.rb
-- lib/basecamp/services/templates_service.rb
-- lib/basecamp/services/timeline_service.rb
-- lib/basecamp/services/timesheet_service.rb
-- lib/basecamp/services/todolist_groups_service.rb
-- lib/basecamp/services/todolists_service.rb
-- lib/basecamp/services/todos_service.rb
-- lib/basecamp/services/todosets_service.rb
-- lib/basecamp/services/tools_service.rb
-- lib/basecamp/services/uploads_service.rb
-- lib/basecamp/services/vaults_service.rb
-- lib/basecamp/services/webhooks_service.rb
 - lib/basecamp/static_token_provider.rb
 - lib/basecamp/token_provider.rb
+- lib/basecamp/usage_error.rb
+- lib/basecamp/validation_error.rb
 - lib/basecamp/version.rb
 - lib/basecamp/webhooks/event.rb
 - lib/basecamp/webhooks/rack_middleware.rb
 - lib/basecamp/webhooks/receiver.rb
+- lib/basecamp/webhooks/verification_error.rb
 - lib/basecamp/webhooks/verify.rb
 - scripts/generate-metadata.rb
 - scripts/generate-services.rb