basecamp-sdk 0.12.0 → 0.13.0

data/lib/basecamp/validation_error.rb

@@ -3,13 +3,23 @@
 module Basecamp
   # Raised for validation errors (400, 422).
   class ValidationError < Error
-    def initialize(message, hint: nil, http_status: 400)
+    # @return [Hash{String => Array<String>}, nil] field-keyed validation
+    #   messages from a 400/422 body — either {"errors" => {"field" => ["msg"]}},
+    #   the Rails RecordInvalid rendering, or the same map with no wrapper at all
+    #   ({"field" => ["msg"]}), which some controllers emit. Nil for every other
+    #   error shape.
+    #   The flattened form is also folded into the message; this slot preserves
+    #   the raw, untruncated per-field messages.
+    attr_reader :field_errors
+
+    def initialize(message, hint: nil, http_status: 400, field_errors: nil)
       super(
         code: ErrorCode::VALIDATION,
         message: message,
         hint: hint,
         http_status: http_status
       )
+      @field_errors = field_errors
     end
   end
 end

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.12.0"
-  API_VERSION = "2026-07-31"
+  VERSION = "0.13.0"
+  API_VERSION = "2026-08-05"
 end

data/lib/basecamp.rb

@@ -11,10 +11,26 @@ loader.on_load("Basecamp::Services::TodosService") do |klass, _abspath|
   klass.prepend(Basecamp::Services::TodosExtensions)
 end
 # Same shape for cards: the generated class owns the constant and the
-# merge-safe update is prepended over the generated update_verbatim.
+# tri-state `due_on` update is prepended over the generated update_verbatim.
 loader.on_load("Basecamp::Services::CardsService") do |klass, _abspath|
   klass.prepend(Basecamp::Services::CardsExtensions)
 end
+# And for todolists: PUT /todolists/{id} is a full replace, so the generated
+# class owns `replace` and the merge-safe update/edit surface is prepended.
+loader.on_load("Basecamp::Services::TodolistsService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::TodolistsExtensions)
+end
+# And for documents: PUT /documents/{id} is a full replace, so the generated
+# class owns `replace` and the merge-safe update/edit surface is prepended.
+loader.on_load("Basecamp::Services::DocumentsService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::DocumentsExtensions)
+end
+# And for schedule entries: PUT /schedule_entries/{id} is a full replace, so
+# the generated class owns `replace_entry` and the merge-safe
+# `update_entry`/`edit_entry` surface is prepended.
+loader.on_load("Basecamp::Services::SchedulesService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::SchedulesExtensions)
+end
 loader.setup
 
 # Load generated types if available
@@ -105,7 +121,9 @@ module Basecamp
 
     case status
     when 400, 422
-      ValidationError.new(message, http_status: status)
+      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)
     when 401
       AuthError.new(message)
     when 403
@@ -141,7 +159,9 @@ module Basecamp
     "download"
   end
 
-  # Parses error message from response body.
+  # Parses error message from response body. A key is used only when its
+  # value is a String (SPEC section 6), so a malformed scalar member such as
+  # {"error": {}} cannot raise or leak a non-string into the message.
   # @param body [String, nil]
   # @return [String, nil]
   def self.parse_error_message(body)
@@ -150,9 +170,79 @@ module Basecamp
     Security.check_body_size!(body, Security::MAX_ERROR_BODY_BYTES, "Error")
 
     data = JSON.parse(body)
-    msg = data["error"] || data["message"]
+    msg = data.is_a?(Hash) ? [ data["error"], data["message"] ].find { |value| value.is_a?(String) } : nil
     msg ? Security.truncate(msg) : nil
   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
+  # dropped, and a map with no usable entries is treated as absent (nil).
+  # @param body [String, nil]
+  # @return [Hash{String => Array<String>}, nil]
+  def self.parse_field_errors(body)
+    return nil if body.nil? || body.empty?
+
+    Security.check_body_size!(body, Security::MAX_ERROR_BODY_BYTES, "Error")
+
+    data = JSON.parse(body)
+    errors = data.is_a?(Hash) ? data["errors"] : nil
+    if errors.is_a?(Hash)
+      field_errors = errors.each_with_object({}) do |(field, values), result|
+        next unless values.is_a?(Array)
+
+        messages = values.grep(String)
+        result[field.to_s] = messages unless messages.empty?
+      end
+      field_errors.empty? ? nil : field_errors
+    else
+      parse_bare_field_errors(data)
+    end
+  rescue JSON::ParserError, ApiError
+    nil
+  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
+  # declare intent, only shape distinguishes a field map from any other JSON
+  # object, so a single non-conforming member means this is not one.
+  # @param data [Object] the parsed body
+  # @return [Hash{String => Array<String>}, nil]
+  def self.parse_bare_field_errors(data)
+    return nil unless data.is_a?(Hash) && !data.empty?
+    # Only "errors" is structurally reserved (it belongs to the wrapped path).
+    # "error" and "message" are not excluded by name: a flat body carries them
+    # as strings, which the shape gate below already rejects.
+    return nil if data.key?("errors")
+
+    data.each_with_object({}) do |(field, values), result|
+      return nil unless values.is_a?(Array) && !values.empty?
+      return nil unless values.all? { |message| message.is_a?(String) && !message.empty? }
+
+      result[field.to_s] = values
+    end
+  end
+
+  # Merges the top-level error message with the flattened field-keyed errors:
+  # appended in parentheses when both are present, standing alone when only the
+  # field errors are. The flattened shape — fields sorted lexicographically, a
+  # field's messages joined with "; ", fields joined with ", " — is shared by
+  # all six SDKs; change it everywhere or nowhere. Callers truncate the
+  # composed result so the appended tail is capped too.
+  # @param message [String, nil]
+  # @param field_errors [Hash{String => Array<String>}, nil]
+  # @return [String, nil]
+  def self.compose_validation_message(message, field_errors)
+    if field_errors.nil?
+      message
+    else
+      flat = field_errors.keys.sort \
+        .map { |field| "#{field}: #{field_errors[field].join("; ")}" } \
+        .join(", ")
+      message ? "#{message} (#{flat})" : flat
+    end
+  end
 end

data/scripts/generate-services.rb

@@ -67,11 +67,13 @@ class ServiceGenerator
       'Attachments' => %w[CreateAttachment],
       'Uploads' => %w[GetUpload UpdateUpload ListUploads CreateUpload ListUploadVersions],
       'Vaults' => %w[GetVault UpdateVault ListVaults CreateVault],
-      'Documents' => %w[GetDocument UpdateDocument ListDocuments CreateDocument]
+      'Documents' => %w[GetDocument ReplaceDocument ListDocuments CreateDocument],
+      'CloudFiles' => %w[GetCloudFile CreateCloudFile UpdateCloudFile],
+      'GoogleDocuments' => %w[GetGoogleDocument CreateGoogleDocument UpdateGoogleDocument]
     },
     'Automation' => {
       'Tools' => %w[GetTool UpdateTool DeleteTool CreateTool EnableTool DisableTool RepositionTool],
-      'Recordings' => %w[GetRecording ArchiveRecording UnarchiveRecording TrashRecording ListRecordings],
+      'Recordings' => %w[ArchiveRecording UnarchiveRecording TrashRecording ListRecordings],
       'Webhooks' => %w[ListWebhooks CreateWebhook GetWebhook UpdateWebhook DeleteWebhook],
       'Events' => %w[ListEvents],
       'Lineup' => %w[CreateLineupMarker UpdateLineupMarker DeleteLineupMarker],
@@ -104,10 +106,10 @@ class ServiceGenerator
     'Schedule' => {
       'Schedules' => %w[
         GetSchedule UpdateScheduleSettings ListScheduleEntries
-        CreateScheduleEntry GetScheduleEntry UpdateScheduleEntry
+        CreateScheduleEntry GetScheduleEntry ReplaceScheduleEntry
         GetScheduleEntryOccurrence
       ],
-      'Timesheets' => %w[GetRecordingTimesheet GetProjectTimesheet GetTimesheetReport GetTimesheetEntry CreateTimesheetEntry UpdateTimesheetEntry]
+      'Timesheets' => %w[GetRecordingTimesheet GetProjectTimesheet GetTimesheetReport GetTimesheetEntry CreateTimesheetEntry UpdateTimesheetEntry DestroyTimesheetEntry]
     },
     'ClientFeatures' => {
       'ClientApprovals' => %w[ListClientApprovals GetClientApproval],
@@ -116,7 +118,7 @@ class ServiceGenerator
       'ClientVisibility' => %w[SetClientVisibility]
     },
     'Todos' => {
-      'Todos' => %w[ListTodos CreateTodo CreateTodosetTodo GetTodo ReplaceTodo CompleteTodo UncompleteTodo TrashTodo],
+      'Todos' => %w[ListTodos CreateTodo CreateTodosetTodo GetTodo ReplaceTodo CompleteTodo UncompleteTodo],
       'Todolists' => %w[GetTodolistOrGroup UpdateTodolistOrGroup ListTodolists CreateTodolist RepositionTodolist],
       'Todosets' => %w[GetTodoset],
       'HillCharts' => %w[GetHillChart UpdateHillChartSettings],
@@ -139,15 +141,19 @@ class ServiceGenerator
   METHOD_NAME_OVERRIDES = {
     'GetMyProfile' => 'my_profile',
     'GetTodolistOrGroup' => 'get',
-    'UpdateTodolistOrGroup' => 'update',
+    # The plain `update` name belongs to the merge-safe composite; the raw
+    # single-PUT path keeps a name that says what it does. BC3 rebuilds the
+    # todolist from the permitted params, so omission clears. See #374.
+    'UpdateTodolistOrGroup' => 'replace',
     'SetCardColumnColor' => 'set_color',
     'EnableCardColumnOnHold' => 'enable_on_hold',
     'DisableCardColumnOnHold' => 'disable_on_hold',
     'RepositionCardStep' => 'reposition',
     'CreateCardStep' => 'create',
     'UpdateCardStep' => 'update',
-    # The plain `update` name belongs to the merge-safe composite; the raw
-    # single-PUT path keeps a name that says what it does. See #467.
+    # The plain `update` name belongs to the tri-state `due_on` wrapper in
+    # CardsExtensions; the unnormalised path keeps a name that says what it
+    # does. See #467.
     'UpdateCard' => 'update_verbatim',
     'SetCardStepCompletion' => 'set_completion',
     'GetQuestionnaire' => 'get_questionnaire',
@@ -175,6 +181,7 @@ class ServiceGenerator
     'GetTimesheetEntry' => 'get',
     'CreateTimesheetEntry' => 'create',
     'UpdateTimesheetEntry' => 'update',
+    'DestroyTimesheetEntry' => 'destroy',
     'GetProgressReport' => 'progress',
     'GetUpcomingSchedule' => 'upcoming',
     'GetAssignedTodos' => 'assigned',
@@ -203,7 +210,6 @@ class ServiceGenerator
     'ListForwards' => 'list',
     'GetForwardReply' => 'get_reply',
     'ListForwardReplies' => 'list_replies',
-    'CreateForwardReply' => 'create_reply',
     'GetInbox' => 'get_inbox',
     # Uploads - use specific names to avoid conflicts with versions
     'GetUpload' => 'get',
@@ -233,7 +239,11 @@ class ServiceGenerator
     'GetSchedule' => 'get',
     'UpdateScheduleSettings' => 'update_settings',
     'GetScheduleEntry' => 'get_entry',
-    'UpdateScheduleEntry' => 'update_entry',
+    # The plain `update_entry` name belongs to the merge-safe composite; the raw
+    # single-PUT path keeps a name that says what it does. Without the override
+    # the algorithm yields a bare `replace` (scheduleentry is a SIMPLE_RESOURCE),
+    # which reads as "replace the schedule". See #547.
+    'ReplaceScheduleEntry' => 'replace_entry',
     'CreateScheduleEntry' => 'create_entry',
     'ListScheduleEntries' => 'list_entries',
     'GetScheduleEntryOccurrence' => 'get_entry_occurrence',
@@ -571,6 +581,34 @@ class ServiceGenerator
        .downcase
   end
 
+  # Folds a multi-line description into the body of a YARD `@param` tag.
+  #
+  # The first line is returned bare — the caller has already written
+  # `# @param name [Type] ` in front of it. Every later line is indented under
+  # it, EXCEPT a blank one: a paragraph break must emit a bare `#`, not `#`
+  # followed by the continuation padding. Padding an empty line is trailing
+  # whitespace, which `git diff --check` fails on, and it stayed fixed only
+  # because this lives in the generator — patching the emitted file put it back
+  # on the next `make generate`.
+  #
+  # Any trailing whitespace already in the description is stripped for the same
+  # reason: a Smithy doc comment can carry it, and the generator should not
+  # launder it into a generated file.
+  YARD_CONTINUATION_INDENT = '      #   '
+
+  def yard_param_description(text)
+    text.to_s.split("\n", -1).each_with_index.map do |line, index|
+      stripped = line.rstrip
+      if index.zero?
+        stripped
+      elsif stripped.empty?
+        '      #'
+      else
+        "#{YARD_CONTINUATION_INDENT}#{stripped}"
+      end
+    end.join("\n")
+  end
+
   def generate_service(service)
     lines = []
 
@@ -611,8 +649,11 @@ class ServiceGenerator
   def generate_method(op, service_name:)
     lines = []
 
-    # Method signature
-    params = build_params(op)
+    is_paginated = (op[:returns_array] || op[:has_pagination]) && !op[:pagination_key]
+    is_wrapped_paginated = op[:has_pagination] && op[:pagination_key]
+
+    # Method signature (paginated operations gain a trailing max_items: kwarg)
+    params = build_params(op, paginated: is_paginated || is_wrapped_paginated)
 
     # YARD documentation
     lines << "      # #{op[:description]}"
@@ -644,7 +685,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('_', ' ')).gsub("\n", "\n      #   ")
+        desc = yard_param_description(b[:description] || ruby_name.gsub('_', ' '))
         format_hint = b[:format_hint] ? " (#{b[:format_hint]})" : ''
         lines << "      # @param #{ruby_name} [#{type}] #{desc}#{format_hint}"
       end
@@ -655,20 +696,22 @@ 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('_', ' ')).gsub("\n", "\n      #   ")
+      desc = yard_param_description(q[:description] || ruby_name.gsub('_', ' '))
       lines << "      # @param #{ruby_name} [#{type}] #{desc}"
     end
 
-    # Add @return tag
-    is_paginated = (op[:returns_array] || op[:has_pagination]) && !op[:pagination_key]
-    is_wrapped_paginated = op[:has_pagination] && op[:pagination_key]
+    # Add @param tag for the pagination cap on paginated operations
+    if is_paginated || is_wrapped_paginated
+      lines << '      # @param max_items [Integer, nil] cap on items yielded across pages; nil or non-positive means no cap'
+    end
 
+    # Add @return tag
     if op[:returns_void]
       lines << '      # @return [void]'
     elsif is_wrapped_paginated
-      lines << '      # @return [Hash] response data'
+      lines << '      # @return [Hash] wrapper fields merged with a ListEnumerator of the paginated items'
     elsif is_paginated
-      lines << '      # @return [Enumerator<Hash>] paginated results'
+      lines << '      # @return [ListEnumerator<Hash>] lazily paginated results (#meta carries pagination metadata)'
     elsif op[:returns_bare_array]
       # Unpaginated bare array (single request, no Link-following) — e.g. the
       # overdue todo/card feeds. Returns the parsed JSON array, not a Hash.
@@ -691,7 +734,8 @@ class ServiceGenerator
       body_lines.each { |l| lines << "  #{l}" }
       lines << '        end'
     elsif is_paginated
-      # wrap_paginated defers hooks to actual iteration time (lazy-safe)
+      # wrap_paginated fires the start hook eagerly (page 1 is fetched inside
+      # the block) and the end hook when iteration completes
       lines << "        wrap_paginated(#{hook_kwargs}) do"
       body_lines = generate_list_method_body(op, path_expr)
       body_lines.each { |l| lines << "  #{l}" }
@@ -729,7 +773,7 @@ class ServiceGenerator
     kwargs.join(', ')
   end
 
-  def build_params(op)
+  def build_params(op, paginated: false)
     params = []
 
     # Path parameters as keyword args
@@ -772,6 +816,9 @@ class ServiceGenerator
       params << "#{to_snake_case(q[:name])}: nil"
     end
 
+    # Client-side pagination cap, threaded into the base paginators
+    params << 'max_items: nil' if paginated
+
     params.join(', ')
   end
 
@@ -818,9 +865,9 @@ class ServiceGenerator
     if op[:query_params].any?
       param_names = op[:query_params].map { |q| "#{to_snake_case(q[:name])}: #{to_snake_case(q[:name])}" }
       lines << "        params = compact_query_params(#{param_names.join(', ')})"
-      lines << "        paginate(#{path_expr}, params: params, operation: \"#{op[:operation_id]}\")"
+      lines << "        paginate(#{path_expr}, params: params, operation: \"#{op[:operation_id]}\", max_items: max_items)"
     else
-      lines << "        paginate(#{path_expr}, operation: \"#{op[:operation_id]}\")"
+      lines << "        paginate(#{path_expr}, operation: \"#{op[:operation_id]}\", max_items: max_items)"
     end
 
     lines
@@ -832,9 +879,11 @@ class ServiceGenerator
     if op[:query_params].any?
       param_names = op[:query_params].map { |q| "#{to_snake_case(q[:name])}: #{to_snake_case(q[:name])}" }
       lines << "        params = compact_query_params(#{param_names.join(', ')})"
-      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", params: params, operation: \"#{op[:operation_id]}\")"
+      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", params: params, " \
+               "operation: \"#{op[:operation_id]}\", max_items: max_items)"
     else
-      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", operation: \"#{op[:operation_id]}\")"
+      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", " \
+               "operation: \"#{op[:operation_id]}\", max_items: max_items)"
     end
 
     lines

data/scripts/generate-types.rb

@@ -9,6 +9,7 @@
 require 'json'
 require 'set'
 require 'time'
+require_relative 'go_type_spellings'
 
 # Schemas to skip (internal/generated response wrappers)
 SKIP_PATTERNS = [
@@ -207,7 +208,7 @@ if __FILE__ == $PROGRAM_NAME
                     "parse_float(data[\"#{prop_name}\"])"
       elsif prop_schema['type'] == 'boolean'
                     "parse_boolean(data[\"#{prop_name}\"])"
-      elsif prop_schema['x-go-type'] == 'time.Time'
+      elsif GoTypeSpellings.timestamp_go_type?(prop_schema['x-go-type'])
                     "parse_datetime(data[\"#{prop_name}\"])"
       else
                     "data[\"#{prop_name}\"]"

data/scripts/go_type_spellings.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Go type spellings the Ruby generator needs to reason about, extracted so the
+# generator and its tests can share one definition — the test used to `load`
+# the whole generator script, which defined every one of its helpers on the
+# test process.
+module GoTypeSpellings
+  module_function
+
+  # Spellings that mean "full timestamp" and therefore get Time coercion in
+  # Ruby. Matched after stripping a leading `*`: the Go optional-pointer policy
+  # (SPEC.md §10) means a schema may carry either `time.Time` or `*time.Time`
+  # for the same wire contract, and an exact-string match silently degrades the
+  # pointer spelling to a raw String (#537).
+  #
+  # types.FlexibleTime is deliberately NOT here: it also accepts date-only
+  # values, and Ruby has passed those through as strings since it was
+  # introduced. Adding it is a behavior change, not a spelling fix.
+  TIMESTAMP_GO_TYPES = [ 'time.Time' ].freeze
+
+  def timestamp_go_type?(go_type)
+    return false unless go_type.is_a?(String)
+
+    TIMESTAMP_GO_TYPES.include?(go_type.delete_prefix('*'))
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -195,13 +195,16 @@ files:
 - lib/basecamp/generated/services/client_correspondences_service.rb
 - lib/basecamp/generated/services/client_replies_service.rb
 - lib/basecamp/generated/services/client_visibility_service.rb
+- lib/basecamp/generated/services/cloud_files_service.rb
 - lib/basecamp/generated/services/comments_service.rb
 - lib/basecamp/generated/services/documents_service.rb
 - lib/basecamp/generated/services/drafts_service.rb
 - lib/basecamp/generated/services/events_service.rb
 - lib/basecamp/generated/services/everything_service.rb
+- lib/basecamp/generated/services/folders_service.rb
 - lib/basecamp/generated/services/forwards_service.rb
 - lib/basecamp/generated/services/gauges_service.rb
+- lib/basecamp/generated/services/google_documents_service.rb
 - lib/basecamp/generated/services/hill_charts_service.rb
 - lib/basecamp/generated/services/lineup_service.rb
 - lib/basecamp/generated/services/message_boards_service.rb
@@ -232,6 +235,8 @@ files:
 - lib/basecamp/generated/types.rb
 - lib/basecamp/hooks.rb
 - lib/basecamp/http.rb
+- lib/basecamp/list_enumerator.rb
+- lib/basecamp/list_meta.rb
 - lib/basecamp/logger_hooks.rb
 - lib/basecamp/network_error.rb
 - lib/basecamp/noop_hooks.rb
@@ -262,6 +267,10 @@ files:
 - lib/basecamp/security.rb
 - lib/basecamp/services/authorization_service.rb
 - lib/basecamp/services/cards_extensions.rb
+- lib/basecamp/services/documents_extensions.rb
+- lib/basecamp/services/merge_safe.rb
+- lib/basecamp/services/schedules_extensions.rb
+- lib/basecamp/services/todolists_extensions.rb
 - lib/basecamp/services/todos_extensions.rb
 - lib/basecamp/static_token_provider.rb
 - lib/basecamp/token_provider.rb
@@ -276,6 +285,7 @@ files:
 - scripts/generate-metadata.rb
 - scripts/generate-services.rb
 - scripts/generate-types.rb
+- scripts/go_type_spellings.rb
 homepage: https://github.com/basecamp/basecamp-sdk
 licenses:
 - MIT