basecamp-sdk 0.15.0 → 0.17.0

data/lib/basecamp/oauth_token_provider.rb

@@ -16,6 +16,22 @@ module Basecamp
     # Token endpoint for Basecamp OAuth
     TOKEN_URL = "https://launchpad.37signals.com/authorization/token"
 
+    # The redirect statuses a token endpoint response is refused for
+    # (SPEC §16 "Token-Endpoint Transport Policy") — the refresh POST carries
+    # the refresh token and client secret, and a redirect must surface as a
+    # typed fault rather than re-issue those credentials toward Location.
+    # 304 stays on the generic non-success path (a cache validator, not a
+    # redirect-with-Location).
+    REDIRECT_STATUSES = [ 301, 302, 303, 307, 308 ].freeze
+
+    # Whole-request bound in seconds for the refresh POST — the shared
+    # credential-POST default (SPEC §16). Enforced as socket timeouts AND a
+    # monotonic wall-clock deadline by the transport below.
+    REFRESH_TIMEOUT = 30
+
+    # Cap on a refresh response body (1 MiB), matching the exchange path.
+    MAX_RESPONSE_BYTES = 1 * 1024 * 1024
+
     # @return [String, nil] the current refresh token
     attr_reader :refresh_token
 
@@ -77,30 +93,51 @@ module Basecamp
         perform_refresh if expired? && refreshable?
       end
 
+      # The refresh POST runs on the headers-first {Oauth::Fetcher.stream_http}
+      # primitive — the same transport as the exchange and device paths — so it
+      # gets the full SPEC §16 discipline rather than a bare Faraday.post:
+      # redirects structurally never followed and classified at header time,
+      # socket timeouts plus a monotonic whole-request watchdog (a slow-drip
+      # peer cannot hold the refresh open past REFRESH_TIMEOUT), and a bounded
+      # streaming body read.
       def perform_refresh
         require "faraday"
         require "json"
-        require "uri"
-
-        response = Faraday.post(TOKEN_URL) do |req|
-          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-          req.body = URI.encode_www_form(
-            type: "refresh",
-            refresh_token: @refresh_token,
-            client_id: @client_id,
-            client_secret: @client_secret
-          )
-        end
 
-        raise AuthError.new("Token refresh failed: #{response.status}") unless response.success?
+        status, body = Oauth::Fetcher.stream_http(
+          :post, TOKEN_URL,
+          headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+          form: {
+            "type" => "refresh",
+            "refresh_token" => @refresh_token,
+            "client_id" => @client_id,
+            "client_secret" => @client_secret
+          },
+          timeout: REFRESH_TIMEOUT,
+          max_body_bytes: MAX_RESPONSE_BYTES,
+          skip_status: ->(s) { REDIRECT_STATUSES.include?(s) }
+        )
+
+        # A refused redirect is a typed api fault carrying the real status —
+        # not the generic AuthError below, which would imply the credentials
+        # were judged and rejected when no such judgement happened.
+        if REDIRECT_STATUSES.include?(status)
+          raise ApiError.new("redirect #{status} on the token endpoint is not followed", http_status: status)
+        end
+        raise AuthError.new("Token refresh failed: #{status}") unless (200..299).cover?(status)
 
-        data = JSON.parse(response.body)
+        data = JSON.parse(body)
         @access_token = data["access_token"]
         @expires_at = Time.now + data["expires_in"].to_i if data["expires_in"]
 
         @on_refresh&.call(@access_token, @refresh_token, @expires_at)
 
         true
+      rescue Oauth::Fetcher::BodyTooLarge
+        raise ApiError.new("Token refresh response exceeds size cap")
+      rescue Oauth::Fetcher::ReadDeadlineExceeded => e
+        # A slow-drip read past the deadline is a transport timeout.
+        raise NetworkError.new("Token refresh network error", cause: e)
       rescue Faraday::Error => e
         raise NetworkError.new("Token refresh network error", cause: e)
       end

data/lib/basecamp/people_confirmation_required_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when a template copy requires confirmation before granting project access.
+  class PeopleConfirmationRequiredError < ValidationError
+    # @return [Array<Basecamp::Types::TemplateLibraryConfirmationPerson>]
+    attr_reader :people
+
+    def initialize(message, people:, hint: nil, http_status: 422, field_errors: nil)
+      super(message, hint: hint, http_status: http_status, field_errors: field_errors)
+      @people = people
+    end
+  end
+end

data/lib/basecamp/rate_limit_error.rb

@@ -3,8 +3,10 @@
 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"
+    def initialize(retry_after: nil, hint: nil, cause: nil)
+      # A concrete Retry-After beats a body-derived hint; the class default
+      # fills in when neither is present.
+      hint = retry_after ? "Try again in #{retry_after} seconds" : (hint || "Please slow down requests")
       super(
         code: ErrorCode::RATE_LIMIT,
         message: "Rate limit exceeded",

data/lib/basecamp/security.rb

@@ -32,6 +32,26 @@ module Basecamp
       raise UsageError.new("Invalid #{label}: #{url}")
     end
 
+    # Renders a URL for hooks as origin+path only (SPEC section 9): no
+    # userinfo, query or fragment. The download flow's hop-1 URL can carry a
+    # signed credential in its query; the wire request keeps the whole URL. A
+    # URL with no complete origin renders as the fixed token, never as any of
+    # its own text.
+    # @param url [String]
+    # @return [String]
+    def self.display_url(url)
+      uri = URI.parse(url)
+      return "unparsable" if uri.scheme.nil? || uri.host.nil? || uri.host.empty?
+
+      uri.password = nil
+      uri.user = nil
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::Error
+      "unparsable"
+    end
+
     def self.same_origin?(a, b)
       ua = URI.parse(a)
       ub = URI.parse(b)

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.15.0"
-  API_VERSION = "2026-08-11"
+  VERSION = "0.17.0"
+  API_VERSION = "2026-09-02"
 end

data/lib/basecamp.rb

@@ -117,31 +117,43 @@ module Basecamp
   # @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"
+    # SPEC §6 step 3: a body's error_description becomes the hint. Step 5:
+    # with no body message, the else arm falls back (via from_status) to the
+    # fixed code-bearing phrase, never a reason phrase.
+    hint = parse_error_hint(body)
+    server_message = parse_error_message(body)
+    message = server_message || "Request failed"
 
     case status
     when 400, 422
       field_errors = parse_field_errors(body)
-      message = Security.truncate(compose_validation_message(parse_error_message(body), field_errors) || "Request failed")
-      ValidationError.new(message, http_status: status, field_errors: field_errors)
+      message = Security.truncate(compose_validation_message(server_message, field_errors) || "Request failed")
+      people = status == 422 ? parse_template_library_confirmation_people(body) : nil
+      if people
+        PeopleConfirmationRequiredError.new(
+          message, people: people, hint: hint, http_status: status, field_errors: field_errors
+        )
+      else
+        ValidationError.new(message, hint: hint, http_status: status, field_errors: field_errors)
+      end
     when 401
-      AuthError.new(message)
+      AuthError.new(message, hint: hint)
     when 403
-      ForbiddenError.new(message)
+      ForbiddenError.new(message, hint: hint)
     when 404
-      NotFoundError.new(message: message)
+      NotFoundError.new(message: message, hint: hint)
     when 429
-      RateLimitError.new(retry_after: retry_after)
+      RateLimitError.new(retry_after: retry_after, hint: hint)
     when 507
       # Decided before the 5xx arms: a 507 is an account limit, not a
       # transient server failure, and no retry can satisfy it.
-      LimitExceededError.new(Security.truncate(message))
+      LimitExceededError.new(Security.truncate(message), hint: hint)
     when 500
-      ApiError.new("Server error (500)", http_status: 500, retryable: true)
+      ApiError.new("Server error (500)", http_status: 500, retryable: true, hint: hint)
     when 502, 503, 504
-      ApiError.new("Gateway error (#{status})", http_status: status, retryable: true)
+      ApiError.new("Gateway error (#{status})", http_status: status, retryable: true, hint: hint)
     else
-      ApiError.from_status(status, message)
+      ApiError.from_status(status, server_message, hint: hint)
     end
   end
 
@@ -180,6 +192,46 @@ module Basecamp
     nil
   end
 
+  # Parses the SPEC section 6 step-3 hint from a response body: the
+  # "error_description" key, used only when its value is a non-empty String,
+  # truncated like the message.
+  # @param body [String, nil]
+  # @return [String, nil]
+  def self.parse_error_hint(body)
+    return nil if body.nil? || body.empty?
+
+    Security.check_body_size!(body, Security::MAX_ERROR_BODY_BYTES, "Error")
+
+    data = JSON.parse(body)
+    hint = data.is_a?(Hash) ? data["error_description"] : nil
+    hint.is_a?(String) && !hint.empty? ? Security.truncate(hint) : nil
+  rescue JSON::ParserError, ApiError
+    nil
+  end
+
+  # Extracts the people whose destination-project access requires confirmation.
+  # @param body [String, nil]
+  # @return [Array<Basecamp::Types::TemplateLibraryConfirmationPerson>, nil]
+  def self.parse_template_library_confirmation_people(body)
+    return nil if body.nil? || body.empty?
+
+    Security.check_body_size!(body, Security::MAX_ERROR_BODY_BYTES, "Error")
+    data = JSON.parse(body)
+    people = data.is_a?(Hash) ? data["people"] : nil
+    return nil unless people.is_a?(Array) && !people.empty?
+
+    valid = people.all? do |person|
+      person.is_a?(Hash) && person["id"].is_a?(Integer) && person["id"].positive? &&
+        person["name"].is_a?(String) && !person["name"].empty? &&
+        person["avatar_url"].is_a?(String) && !person["avatar_url"].empty?
+    end
+    return nil unless valid
+
+    people.map { |person| Types::TemplateLibraryConfirmationPerson.new(person) }
+  rescue JSON::ParserError, ApiError
+    nil
+  end
+
   # Extracts the field-keyed validation errors map from a response body — the
   # Rails RecordInvalid rendering {"errors" => {"field" => ["msg", ...]}}.
   # Entries whose value is not an array are skipped, non-string elements are
@@ -193,7 +245,9 @@ module Basecamp
 
     data = JSON.parse(body)
     errors = data.is_a?(Hash) ? data["errors"] : nil
-    if errors.is_a?(Hash)
+    if errors.is_a?(Array)
+      parse_row_errors(errors)
+    elsif errors.is_a?(Hash)
       field_errors = errors.each_with_object({}) do |(field, values), result|
         next unless values.is_a?(Array)
 
@@ -208,6 +262,35 @@ module Basecamp
     nil
   end
 
+  # Extracts a row-keyed errors list — the batch-invite rendering
+  # {"errors" => [{"email_address" => "...", "messages" => ["..."]}, ...]}
+  # (SPEC section 6 step 1b), one element per rejected row. Rows are keyed by
+  # their email_address when it is a non-empty string, else by an integer
+  # index, else by their position in the list; a repeated key appends.
+  # All-or-nothing: one element without a usable messages array means this is
+  # some other list, and the slot stays absent.
+  # @param rows [Array] the parsed "errors" array
+  # @return [Hash{String => Array<String>}, nil]
+  def self.parse_row_errors(rows)
+    return nil if rows.empty?
+
+    rows.each_with_index.each_with_object({}) do |(row, position), result|
+      return nil unless row.is_a?(Hash) && row["messages"].is_a?(Array)
+
+      messages = row["messages"].select { |message| message.is_a?(String) && !message.empty? }
+      return nil if messages.empty?
+
+      key = if row["email_address"].is_a?(String) && !row["email_address"].empty?
+        row["email_address"]
+      elsif row["index"].is_a?(Integer)
+        row["index"].to_s
+      else
+        position.to_s
+      end
+      (result[key] ||= []).concat(messages)
+    end
+  end
+
   # Extracts an unwrapped field map — the `render json: @webhook.errors`
   # rendering, where the whole body is {"field" => ["msg", ...]}. The gate is
   # all-or-nothing by design (SPEC section 6 step 2): with no "errors" key to

data/scripts/generate-services.rb

@@ -73,7 +73,7 @@ class ServiceGenerator
     },
     'Automation' => {
       'Tools' => %w[GetTool UpdateTool DeleteTool CreateTool EnableTool DisableTool RepositionTool],
-      'Recordings' => %w[ArchiveRecording UnarchiveRecording TrashRecording ListRecordings],
+      'Recordings' => %w[ArchiveRecording UnarchiveRecording TrashRecording ListRecordings SpotlightRecording UnspotlightRecording],
       'Webhooks' => %w[ListWebhooks CreateWebhook GetWebhook UpdateWebhook DeleteWebhook],
       'Events' => %w[ListEvents],
       'Lineup' => %w[CreateLineupMarker UpdateLineupMarker DeleteLineupMarker],
@@ -81,6 +81,7 @@ class ServiceGenerator
       'Templates' => %w[
         ListTemplates CreateTemplate GetTemplate UpdateTemplate
         DeleteTemplate CreateProjectFromTemplate GetProjectConstruction
+        GetTemplateLibrary CreateTemplateLibraryCopy GetTemplateLibraryCopy
       ],
       'Checkins' => %w[
         GetQuestionnaire ListQuestions CreateQuestion GetQuestion
@@ -139,6 +140,8 @@ class ServiceGenerator
 
   # Method name overrides
   METHOD_NAME_OVERRIDES = {
+    'SpotlightRecording' => 'spotlight',
+    'UnspotlightRecording' => 'unspotlight',
     'GetMyProfile' => 'my_profile',
     'GetTodolistOrGroup' => 'get',
     # The plain `update` name belongs to the merge-safe composite; the raw
@@ -175,6 +178,9 @@ class ServiceGenerator
     'Search' => 'search',
     'CreateProjectFromTemplate' => 'create_project',
     'GetProjectConstruction' => 'get_construction',
+    'GetTemplateLibrary' => 'get_library',
+    'CreateTemplateLibraryCopy' => 'create_library_copy',
+    'GetTemplateLibraryCopy' => 'get_library_copy',
     'GetRecordingTimesheet' => 'for_recording',
     'GetProjectTimesheet' => 'for_project',
     'GetTimesheetReport' => 'report',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -184,6 +184,7 @@ files:
 - lib/basecamp/generated/services/base_service.rb
 - lib/basecamp/generated/services/bookmarks_service.rb
 - lib/basecamp/generated/services/boosts_service.rb
+- lib/basecamp/generated/services/bubble_ups_service.rb
 - lib/basecamp/generated/services/calendars_service.rb
 - lib/basecamp/generated/services/campfires_service.rb
 - lib/basecamp/generated/services/card_columns_service.rb
@@ -262,6 +263,7 @@ files:
 - lib/basecamp/oauth_token_provider.rb
 - lib/basecamp/operation_info.rb
 - lib/basecamp/operation_result.rb
+- lib/basecamp/people_confirmation_required_error.rb
 - lib/basecamp/rate_limit_error.rb
 - lib/basecamp/request_info.rb
 - lib/basecamp/request_result.rb