basecamp-sdk 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39a8cc069aaa9ee04e3d91d46e8c06932aaac5947ccbb98da863ebca3a46eadd
-  data.tar.gz: c5d16c70981ddb8a784636578a211f3ae2e58636b664fe8d2be008604e95fa61
+  metadata.gz: 67da09be280f8e08a9639f77ea7d08f70e5327609cac6a46812bf76069a09a18
+  data.tar.gz: 98f22496c4a83e17e076e2339848ee6c1738b4f5382889114acb053ea010ffe1
 SHA512:
-  metadata.gz: 8cde71ee5f4b3957b62b281302e66ec5cf2eefd8a5ce91bcc658388933a2b3250b913ccb6081c1f6d9adb47c5e874f0341c5b2df1420d4e0550594d7ad5656e2
-  data.tar.gz: 486db1ccd6dfb83d41277f5c742306e7f7bfd13d3987a6fef5184a2b154c1025c5c5b5f94826dbb188c5c71c02390e18fa66156d31761f6fc829dd20e9482bf3
+  metadata.gz: 27cae3068542c51e3a02a994deaf8b68d6a91e8ddae6d5ce1ac7b98123718e5aa884879ee5ee679b432b30074d5f1c00d62ca2bd714ca144a2d3b352b398c961
+  data.tar.gz: 8da2274e9fcaa49289e5e6c0587dd396f2f56012146fa490decef7fb195be3223cd34f23c1ba3e227a6538b9620473ac98dbf856aeabfa845de59ff0bc984d1a

data/README.md

@@ -215,7 +215,7 @@ rescue Basecamp::RateLimitError => e
   puts "Rate limited, retry after: #{e.retry_after} seconds"
 rescue Basecamp::AuthError => e
   puts "Authentication failed: #{e.message}"
-rescue Basecamp::APIError => e
+rescue Basecamp::ApiError => e
   puts "API error (#{e.http_status}): #{e.message}"
 end
 ```
@@ -224,7 +224,7 @@ end
 
 | Error | Description |
 |-------|-------------|
-| `APIError` | Base error class for all API errors |
+| `ApiError` | Base error class for all API errors |
 | `AuthError` | Authentication failures (401) |
 | `ForbiddenError` | Access denied (403) |
 | `NotFoundError` | Resource not found (404) |

data/lib/basecamp/ambiguous_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when a name/identifier matches multiple resources.
+  class AmbiguousError < Error
+    # @return [Array<String>] list of matching resources
+    attr_reader :matches
+
+    def initialize(resource, matches: [])
+      @matches = matches
+      hint = if matches.any? && matches.length <= 5
+               "Did you mean: #{matches.join(", ")}"
+      else
+               "Be more specific"
+      end
+      super(
+        code: ErrorCode::AMBIGUOUS,
+        message: "Ambiguous #{resource}",
+        hint: hint
+      )
+    end
+  end
+end

data/lib/basecamp/api_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised for generic API errors.
+  class ApiError < Error
+    def initialize(message, http_status: nil, hint: nil, retryable: false, cause: nil)
+      super(
+        code: ErrorCode::API,
+        message: message,
+        hint: hint,
+        http_status: http_status,
+        retryable: retryable,
+        cause: cause
+      )
+    end
+
+    # Creates an ApiError from an HTTP status code.
+    # @param status [Integer] HTTP status code
+    # @param message [String, nil] optional error message
+    # @return [ApiError]
+    def self.from_status(status, message = nil)
+      message ||= "Request failed (HTTP #{status})"
+      retryable = status >= 500 && status < 600
+      new(message, http_status: status, retryable: retryable)
+    end
+  end
+end

data/lib/basecamp/auth_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when authentication fails (401).
+  class AuthError < Error
+    def initialize(message = "Authentication required", hint: nil, cause: nil)
+      super(
+        code: ErrorCode::AUTH,
+        message: message,
+        hint: hint || "Check your access token or refresh it if expired",
+        http_status: 401,
+        cause: cause
+      )
+    end
+  end
+end

data/lib/basecamp/auth_strategy.rb

@@ -17,22 +17,4 @@ module Basecamp
       raise NotImplementedError, "#{self.class} must implement #authenticate"
     end
   end
-
-  # Bearer token authentication strategy (default).
-  # Sets the Authorization header with "Bearer {token}".
-  class BearerAuth
-    include AuthStrategy
-
-    # @param token_provider [TokenProvider] provides access tokens
-    def initialize(token_provider)
-      @token_provider = token_provider
-    end
-
-    # @return [TokenProvider] the underlying token provider
-    attr_reader :token_provider
-
-    def authenticate(headers)
-      headers["Authorization"] = "Bearer #{@token_provider.access_token}"
-    end
-  end
 end

data/lib/basecamp/bearer_auth.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Bearer token authentication strategy (default).
+  # Sets the Authorization header with "Bearer {token}".
+  class BearerAuth
+    include AuthStrategy
+
+    # @param token_provider [TokenProvider] provides access tokens
+    def initialize(token_provider)
+      @token_provider = token_provider
+    end
+
+    # @return [TokenProvider] the underlying token provider
+    attr_reader :token_provider
+
+    def authenticate(headers)
+      headers["Authorization"] = "Bearer #{@token_provider.access_token}"
+    end
+  end
+end

data/lib/basecamp/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+
 module Basecamp
   # Main client for the Basecamp API.
   #
@@ -188,6 +189,16 @@ module Basecamp
       @parent.http.post_raw(account_path(path), body: body, content_type: content_type)
     end
 
+    # Performs a PUT request with raw binary data scoped to this account.
+    # Used for multipart uploads (e.g., account logo).
+    # @param path [String] URL path (without account prefix)
+    # @param body [String, IO] raw binary data
+    # @param content_type [String] MIME content type
+    # @return [Response]
+    def put_raw(path, body:, content_type:)
+      @parent.http.put_raw(account_path(path), body: body, content_type: content_type)
+    end
+
     # Fetches all pages of a paginated resource.
     # @param path [String] URL path (without account prefix)
     # @param params [Hash] query parameters
@@ -217,6 +228,92 @@ module Basecamp
       @parent.http.paginate_wrapped(account_path(path), key: key, params: params)
     end
 
+    # Downloads file content from any API-routable download URL.
+    #
+    # Handles the full download flow: URL rewriting to the configured API host,
+    # authenticated first hop (which typically 302s to a signed download URL),
+    # and unauthenticated second hop to fetch the actual file content.
+    #
+    # @param raw_url [String] absolute download URL (e.g., from bc-attachment elements)
+    # @return [DownloadResult] the download result with body, content_type, content_length, filename
+    # @raise [UsageError] if raw_url is empty or not absolute
+    # @raise [NetworkError] if a network error occurs
+    # @raise [ApiError] if the API or download returns an error
+    def download_url(raw_url)
+      # Validation
+      raise UsageError.new("download URL is required") if raw_url.nil? || raw_url.to_s.empty?
+
+      begin
+        parsed = URI.parse(raw_url)
+      rescue URI::InvalidURIError
+        raise UsageError.new("download URL must be an absolute URL")
+      end
+      raise UsageError.new("download URL must be an absolute URL") unless parsed.is_a?(URI::HTTP)
+
+      # Operation hooks
+      op = OperationInfo.new(
+        service: "Account", operation: "DownloadURL",
+        resource_type: "download", is_mutation: false
+      )
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      safe_hook { hooks.on_operation_start(op) }
+
+      begin
+        # URL rewriting: replace scheme+host with config.base_url origin, preserve path+query+fragment
+        base = URI.parse(config.base_url)
+        rewritten = parsed.dup
+        rewritten.scheme = base.scheme
+        rewritten.host = base.host
+        rewritten.port = base.port
+        rewritten_url = rewritten.to_s
+
+        # Hop 1: Authenticated API request (no retry, captures redirect)
+        response = http.get_no_retry(rewritten_url)
+
+        result = case response.status
+        when 301, 302, 303, 307, 308
+          # Redirect — extract Location, proceed to hop 2
+          location = response.headers["Location"] || response.headers["location"]
+          raise ApiError.new("redirect #{response.status} with no Location header") if location.nil? || location.empty?
+
+          # Resolve relative Location against the rewritten API URL
+          resolved_url = Security.resolve_url(rewritten_url, location)
+
+          # Hop 2: fetch from signed URL (no auth, no hooks)
+          signed_response = fetch_signed_download(resolved_url)
+
+          DownloadResult.new(
+            body: signed_response.body,
+            content_type: signed_response["Content-Type"] || "",
+            content_length: parse_content_length(signed_response["Content-Length"]),
+            filename: Basecamp.filename_from_url(raw_url)
+          )
+
+        when 200..299
+          # Direct download — no second hop
+          DownloadResult.new(
+            body: response.body,
+            content_type: response.headers["Content-Type"] || response.headers["content-type"] || "",
+            content_length: parse_content_length(response.headers["Content-Length"] || response.headers["content-length"]),
+            filename: Basecamp.filename_from_url(raw_url)
+          )
+
+        else
+          # This shouldn't happen because Faraday's raise_error middleware
+          # handles 4xx/5xx, but handle it defensively
+          raise Basecamp.error_from_response(response.status, response.body)
+        end
+      rescue => e
+        duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        safe_hook { hooks.on_operation_end(op, OperationResult.new(duration_ms: duration, error: e)) }
+        raise
+      else
+        duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        safe_hook { hooks.on_operation_end(op, OperationResult.new(duration_ms: duration, error: nil)) }
+        result
+      end
+    end
+
     # @!group Services
 
     # @return [Services::ProjectsService]
@@ -234,6 +331,11 @@ module Basecamp
       service(:todosets) { Services::TodosetsService.new(self) }
     end
 
+    # @return [Services::HillChartsService]
+    def hill_charts
+      service(:hill_charts) { Services::HillChartsService.new(self) }
+    end
+
     # @return [Services::TodolistsService]
     def todolists
       service(:todolists) { Services::TodolistsService.new(self) }
@@ -359,6 +461,11 @@ module Basecamp
       service(:lineup) { Services::LineupService.new(self) }
     end
 
+    # @return [Services::AutomationService]
+    def automation
+      service(:automation) { Services::AutomationService.new(self) }
+    end
+
     # @return [Services::MessageTypesService]
     def message_types
       service(:message_types) { Services::MessageTypesService.new(self) }
@@ -409,6 +516,26 @@ module Basecamp
       service(:boosts) { Services::BoostsService.new(self) }
     end
 
+    # @return [Services::AccountService]
+    def account
+      service(:account) { Services::AccountService.new(self) }
+    end
+
+    # @return [Services::GaugesService]
+    def gauges
+      service(:gauges) { Services::GaugesService.new(self) }
+    end
+
+    # @return [Services::MyAssignmentsService]
+    def my_assignments
+      service(:my_assignments) { Services::MyAssignmentsService.new(self) }
+    end
+
+    # @return [Services::MyNotificationsService]
+    def my_notifications
+      service(:my_notifications) { Services::MyNotificationsService.new(self) }
+    end
+
     # @!endgroup
 
     private
@@ -433,5 +560,40 @@ module Basecamp
         @services[name] ||= yield
       end
     end
+
+    def fetch_signed_download(url)
+      uri = URI.parse(url)
+      http_client = Net::HTTP.new(uri.host, uri.port)
+      http_client.use_ssl = (uri.scheme == "https")
+      http_client.open_timeout = config.timeout
+      http_client.read_timeout = config.timeout
+
+      request = Net::HTTP::Get.new(uri)
+
+      begin
+        response = http_client.request(request)
+      rescue StandardError => e
+        raise NetworkError.new("Download failed: #{e.message}", cause: e)
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise ApiError.new("download failed with status #{response.code}", http_status: response.code.to_i)
+      end
+
+      response
+    end
+
+    def safe_hook
+      yield
+    rescue => e
+      warn "Basecamp hook error: #{e.class}: #{e.message}"
+    end
+
+    def parse_content_length(value)
+      return -1 if value.nil? || value.to_s.empty?
+
+      parsed = value.to_i
+      parsed >= 0 ? parsed : -1
+    end
   end
 end

data/lib/basecamp/download_result.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Result of downloading file content from a URL.
+  DownloadResult = Data.define(:body, :content_type, :content_length, :filename) do
+    def initialize(body:, content_type: "", content_length: -1, filename: "download")
+      super
+    end
+  end
+end

data/lib/basecamp/error.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Base error class for all Basecamp SDK errors.
+  # Provides structured error handling with codes, hints, and CLI exit codes.
+  #
+  # @example Catching errors
+  #   begin
+  #     client.projects.list
+  #   rescue Basecamp::Error => e
+  #     puts "#{e.code}: #{e.message}"
+  #     puts "Hint: #{e.hint}" if e.hint
+  #     exit e.exit_code
+  #   end
+  class Error < StandardError
+    # @return [String] error category code
+    attr_reader :code
+
+    # @return [String, nil] user-friendly hint for resolving the error
+    attr_reader :hint
+
+    # @return [Integer, nil] HTTP status code that caused the error
+    attr_reader :http_status
+
+    # @return [Boolean] whether the operation can be retried
+    attr_reader :retryable
+
+    # @return [Integer, nil] seconds to wait before retrying (for rate limits)
+    attr_reader :retry_after
+
+    # @return [String, nil] X-Request-Id from the response
+    attr_reader :request_id
+
+    # @return [Exception, nil] original error that caused this error
+    attr_reader :cause
+
+    # @param code [String] error category code
+    # @param message [String] error message
+    # @param hint [String, nil] user-friendly hint
+    # @param http_status [Integer, nil] HTTP status code
+    # @param retryable [Boolean] whether operation can be retried
+    # @param retry_after [Integer, nil] seconds to wait before retry
+    # @param request_id [String, nil] X-Request-Id from response
+    # @param cause [Exception, nil] underlying cause
+    def initialize(code:, message:, hint: nil, http_status: nil, retryable: false, retry_after: nil, request_id: nil, cause: nil)
+      super(message)
+      @code = code
+      @hint = hint
+      @http_status = http_status
+      @retryable = retryable
+      @retry_after = retry_after
+      @request_id = request_id
+      @cause = cause
+    end
+
+    # Returns the exit code for CLI applications.
+    # @return [Integer]
+    def exit_code
+      self.class.exit_code_for(@code)
+    end
+
+    # Returns whether this error can be retried.
+    # @return [Boolean]
+    def retryable?
+      @retryable
+    end
+
+    # Maps error codes to exit codes.
+    # @param code [String]
+    # @return [Integer]
+    def self.exit_code_for(code)
+      case code
+      when ErrorCode::USAGE then ExitCode::USAGE
+      when ErrorCode::NOT_FOUND then ExitCode::NOT_FOUND
+      when ErrorCode::AUTH then ExitCode::AUTH
+      when ErrorCode::FORBIDDEN then ExitCode::FORBIDDEN
+      when ErrorCode::RATE_LIMIT then ExitCode::RATE_LIMIT
+      when ErrorCode::NETWORK then ExitCode::NETWORK
+      when ErrorCode::API then ExitCode::API
+      when ErrorCode::AMBIGUOUS then ExitCode::AMBIGUOUS
+      when ErrorCode::VALIDATION then ExitCode::VALIDATION
+      else ExitCode::API
+      end
+    end
+  end
+end

data/lib/basecamp/error_code.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Error codes for API responses
+  module ErrorCode
+    USAGE = "usage"
+    NOT_FOUND = "not_found"
+    AUTH = "auth_required"
+    FORBIDDEN = "forbidden"
+    RATE_LIMIT = "rate_limit"
+    NETWORK = "network"
+    API = "api_error"
+    AMBIGUOUS = "ambiguous"
+    VALIDATION = "validation"
+  end
+end

data/lib/basecamp/exit_code.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Exit codes for CLI tools
+  module ExitCode
+    OK = 0
+    USAGE = 1
+    NOT_FOUND = 2
+    AUTH = 3
+    FORBIDDEN = 4
+    RATE_LIMIT = 5
+    NETWORK = 6
+    API = 7
+    AMBIGUOUS = 8
+    VALIDATION = 9
+  end
+end

data/lib/basecamp/forbidden_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when access is denied (403).
+  class ForbiddenError < Error
+    def initialize(message = "Access denied", hint: nil)
+      super(
+        code: ErrorCode::FORBIDDEN,
+        message: message,
+        hint: hint || "You do not have permission to access this resource",
+        http_status: 403
+      )
+    end
+
+    # Creates a forbidden error due to insufficient OAuth scope.
+    def self.insufficient_scope
+      new("Access denied: insufficient scope", hint: "Re-authenticate with full scope")
+    end
+  end
+end