basecamp-sdk 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39a8cc069aaa9ee04e3d91d46e8c06932aaac5947ccbb98da863ebca3a46eadd
-  data.tar.gz: c5d16c70981ddb8a784636578a211f3ae2e58636b664fe8d2be008604e95fa61
+  metadata.gz: da0e2d03c80b5801b886da56a59535f99cb521bd8233a146720ee117f76954b8
+  data.tar.gz: 4a3ea1075d88cac04a7dcc796f3c21d235aaffbb9d036be088321746c435c012
 SHA512:
-  metadata.gz: 8cde71ee5f4b3957b62b281302e66ec5cf2eefd8a5ce91bcc658388933a2b3250b913ccb6081c1f6d9adb47c5e874f0341c5b2df1420d4e0550594d7ad5656e2
-  data.tar.gz: 486db1ccd6dfb83d41277f5c742306e7f7bfd13d3987a6fef5184a2b154c1025c5c5b5f94826dbb188c5c71c02390e18fa66156d31761f6fc829dd20e9482bf3
+  metadata.gz: e5d5298402d8239d525cff7aeac7815254cb7a1a3a967ed6f29fe9fea581432f0c2e7b272edc52a866b457ec988afc11f3ff6dbb48977b5e2ac716af8bbdb46a
+  data.tar.gz: f37ba99c63d4fb9836fe9fc5e6e717e0166f97892069da141f2be746ac95c8e15629319fb1deb4c23cdd4a7ee30d1ac84a83bf183e19930c9d394e47995704e6

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

@@ -217,6 +217,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]
@@ -359,6 +445,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) }
@@ -433,5 +524,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

data/lib/basecamp/generated/metadata.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://basecamp.com/schemas/sdk-metadata.json",
   "version": "1.0.0",
-  "generated": "2026-03-12T01:04:29Z",
+  "generated": "2026-03-16T01:24:22Z",
   "operations": {
     "CreateAttachment": {
       "retry": {
@@ -243,6 +243,17 @@
         "natural": true
       }
     },
+    "GetCardStep": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
     "UpdateCardStep": {
       "retry": {
         "maxAttempts": 3,

data/lib/basecamp/{services → generated/services}/authorization_service.rb

@@ -38,7 +38,7 @@ module Basecamp
           config = Oauth.discover(http.base_url)
           # Use issuer as base for authorization.json
           "#{config.issuer.chomp("/")}/authorization.json"
-        rescue Oauth::OAuthError
+        rescue Oauth::OauthError
           # Fall back to Launchpad
           LAUNCHPAD_AUTHORIZATION_URL
         end

data/lib/basecamp/generated/services/automation_service.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for Automation operations
+    #
+    # @generated from OpenAPI spec
+    class AutomationService < BaseService
+
+      # List all lineup markers for the account
+      # @return [Hash] response data
+      def list_lineup_markers()
+        with_operation(service: "automation", operation: "list_lineup_markers", is_mutation: false) do
+          http_get("/lineup/markers.json").json
+        end
+      end
+    end
+  end
+end

data/lib/basecamp/{services → generated/services}/base_service.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "cgi/escape"
-require_relative "../errors"
 
 module Basecamp
   module Services

data/lib/basecamp/generated/services/card_steps_service.rb

@@ -31,6 +31,15 @@ module Basecamp
         end
       end
 
+      # Get a step by ID
+      # @param step_id [Integer] step id ID
+      # @return [Hash] response data
+      def get(step_id:)
+        with_operation(service: "cardsteps", operation: "get", is_mutation: false, resource_id: step_id) do
+          http_get("/card_tables/steps/#{step_id}").json
+        end
+      end
+
       # Update an existing step
       # @param step_id [Integer] step id ID
       # @param title [String, nil] title

data/lib/basecamp/generated/services/search_service.rb

@@ -9,7 +9,7 @@ module Basecamp
 
       # Search for content across the account
       # @param q [String] q
-      # @param sort [String, nil] created_at|updated_at
+      # @param sort [String, nil] best_match|created_at
       # @return [Enumerator<Hash>] paginated results
       def search(q:, sort: nil)
         wrap_paginated(service: "search", operation: "search", is_mutation: false) do

data/lib/basecamp/generated/services/tools_service.rb

@@ -9,10 +9,11 @@ module Basecamp
 
       # Clone an existing tool to create a new one
       # @param source_recording_id [Integer] source recording id
+      # @param title [String, nil] title
       # @return [Hash] response data
-      def clone(source_recording_id:)
+      def clone(source_recording_id:, title: nil)
         with_operation(service: "tools", operation: "clone", is_mutation: true) do
-          http_post("/dock/tools.json", body: compact_params(source_recording_id: source_recording_id)).json
+          http_post("/dock/tools.json", body: compact_params(source_recording_id: source_recording_id, title: title)).json
         end
       end
 

data/lib/basecamp/generated/types.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Auto-generated from OpenAPI spec. Do not edit manually.
-# Generated: 2026-03-12T01:04:29Z
+# Generated: 2026-03-16T01:24:22Z
 
 require "json"
 require "time"