basecamp-sdk 0.8.0 → 0.10.0

data/lib/basecamp/http.rb

@@ -377,7 +377,8 @@ module Basecamp
         end
       end
 
-      raise last_error || Basecamp::ApiError.new("Request failed after #{@config.max_retries} retries")
+      noun = @config.max_retries == 1 ? "attempt" : "attempts"
+      raise last_error || Basecamp::ApiError.new("Request failed after #{@config.max_retries} #{noun}")
     end
 
     def single_request(method, url, params:, body:, attempt:, retry_count: 0, allow_cross_origin: false)

data/lib/basecamp/services/cards_extensions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Merge-safe +update+ for cards, prepended onto the generated
+    # {CardsService} (see the +on_load+ hook in +basecamp.rb+).
+    #
+    # BC3 builds the card's update params as
+    # <tt>{ due_on: nil }.merge(card_params)</tt>
+    # (+kanban/cards_controller.rb+), so *any* update whose body omits +due_on+
+    # erases the card's due date. A sparse PUT — the natural thing to write —
+    # is therefore destructive on the raw endpoint, which remains available as
+    # {#update_verbatim}.
+    #
+    # +update+ composes the public +get+ and +update_verbatim+ methods, so
+    # hooks observe the two wire operations, not a synthetic composite.
+    #
+    # Not atomic: a concurrent due-date change landing between the GET and the
+    # PUT is overwritten with the value this call read. The window is one
+    # round-trip.
+    module CardsExtensions
+      # Updates a card without disturbing fields the caller did not mention.
+      #
+      # +due_on+ is tri-state, which is what makes this safe:
+      #
+      # * +nil+ (omitted) — the current due date is fetched and resent
+      # * <tt>""</tt> — the due date is cleared
+      # * a date — the due date is set
+      #
+      # The extra GET is only paid for in the +nil+ case, the one where the
+      # API would otherwise destroy something.
+      #
+      # Assignees are never resent on the caller's behalf: BC3 filters incoming
+      # IDs through +reachable_people+, so echoing back an id belonging to
+      # someone who has since lost board access would silently unassign them.
+      #
+      # @param card_id [Integer] card id
+      # @param title [String, nil] new title (nil = keep current)
+      # @param content [String, nil] new content (nil = keep current, "" clears)
+      # @param due_on [String, nil] new due date (nil = keep current, "" clears)
+      # @param assignee_ids [Array, nil] new assignees (nil = keep current, [] clears)
+      # @return [Hash] the updated card
+      def update(card_id:, title: nil, content: nil, due_on: nil, assignee_ids: nil)
+        resolved_due_on =
+          if due_on.nil?
+            get(card_id: card_id)["due_on"]
+          elsif due_on.to_s.empty?
+            # Clearing is encoded by OMITTING due_on — compact_params strips the
+            # nil below, and BC3 nils an omitted due date. Sending an explicit
+            # null would violate body compaction (SPEC §18), and sending ""
+            # risks a date-format error.
+            nil
+          else
+            due_on
+          end
+
+        update_verbatim(
+          card_id: card_id,
+          title: title,
+          content: content,
+          due_on: resolved_due_on,
+          assignee_ids: assignee_ids
+        )
+      end
+    end
+  end
+end

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.8.0"
-  API_VERSION = "2026-07-22"
+  VERSION = "0.10.0"
+  API_VERSION = "2026-07-28"
 end

data/lib/basecamp.rb

@@ -10,6 +10,11 @@ loader.collapse("#{__dir__}/basecamp/generated")
 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.
+loader.on_load("Basecamp::Services::CardsService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::CardsExtensions)
+end
 loader.setup
 
 # Load generated types if available

data/scripts/generate-services.rb

@@ -60,7 +60,8 @@ class ServiceGenerator
       'CardSteps' => %w[
         GetCardStep CreateCardStep UpdateCardStep SetCardStepCompletion
         RepositionCardStep
-      ]
+      ],
+      'Wormholes' => %w[CreateWormhole UpdateWormhole DeleteWormhole]
     },
     'Files' => {
       'Attachments' => %w[CreateAttachment],
@@ -116,7 +117,7 @@ class ServiceGenerator
     },
     'Todos' => {
       'Todos' => %w[ListTodos CreateTodo GetTodo ReplaceTodo CompleteTodo UncompleteTodo TrashTodo],
-      'Todolists' => %w[GetTodolistOrGroup UpdateTodolistOrGroup ListTodolists CreateTodolist],
+      'Todolists' => %w[GetTodolistOrGroup UpdateTodolistOrGroup ListTodolists CreateTodolist RepositionTodolist],
       'Todosets' => %w[GetTodoset],
       'HillCharts' => %w[GetHillChart UpdateHillChartSettings],
       'TodolistGroups' => %w[ListTodolistGroups CreateTodolistGroup RepositionTodolistGroup]
@@ -145,6 +146,9 @@ class ServiceGenerator
     '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.
+    'UpdateCard' => 'update_verbatim',
     'SetCardStepCompletion' => 'set_completion',
     'GetQuestionnaire' => 'get_questionnaire',
     'GetQuestion' => 'get_question',
@@ -302,6 +306,7 @@ class ServiceGenerator
     clientcorrespondences clientreply clientreplies forwardreply
     forwardreplies campfireline campfirelines todolistgroup todolistgroups
     todolistorgroup uploadversions hillchart hillcharts
+    wormhole wormholes
   ].freeze
 
   def initialize(openapi_path)
@@ -396,7 +401,12 @@ class ServiceGenerator
                    .select { |p| p['in'] == 'query' }
                    .map do |p|
       {
-        name: p['name'],
+        # Strip a trailing `[]` from bracketed array wire names (e.g.
+        # `bucket_ids[]`): the kwarg and the params-hash key are both clean
+        # `bucket_ids`, and Faraday's NestedParamsEncoder re-adds the `[]` when
+        # serializing the array value (a raw `bucket_ids[]` key would double to
+        # `bucket_ids[][]=`).
+        name: p['name'].sub(/\[\]\z/, ''),
         type: schema_to_ruby_type(p['schema']),
         required: p['required'] || false,
         description: p['description']
@@ -417,6 +427,13 @@ class ServiceGenerator
     response_schema = success_response&.dig('content', 'application/json', 'schema')
     returns_void = response_schema.nil?
     returns_array = response_schema&.dig('type') == 'array'
+    # Bare-array responses are usually a $ref to a single-member output alias, so
+    # the inline `type` is absent. Resolve the ref to detect them — used only for
+    # the YARD @return doc (an unpaginated bare array returns an Array, not a
+    # Hash); the pagination/body logic deliberately keys off the raw `type` so a
+    # bare array without x-basecamp-pagination stays a single request.
+    resolved_response = response_schema && response_schema['$ref'] ? resolve_schema_ref(response_schema) : response_schema
+    returns_bare_array = resolved_response&.dig('type') == 'array'
 
     {
       operation_id: operation_id,
@@ -433,6 +450,7 @@ class ServiceGenerator
       multipart_field: multipart_field,
       returns_void: returns_void,
       returns_array: returns_array,
+      returns_bare_array: returns_bare_array,
       is_mutation: http_method != 'GET',
       has_pagination: !!operation['x-basecamp-pagination'],
       pagination_key: operation.dig('x-basecamp-pagination', 'key')
@@ -533,7 +551,13 @@ class ServiceGenerator
   def schema_to_ruby_type(schema)
     return 'Object' unless schema
 
-    case schema['type']
+    # Object-valued members (e.g. a `project`/`gauge`/`schedule` envelope) are passed
+    # as a Hash. Resolve $refs and treat only object-typed schemas as Hash; a string
+    # ref such as FirstWeekDay must stay String.
+    resolved = schema['$ref'] ? resolve_schema_ref(schema) : schema
+    return 'Hash' if resolved && resolved['type'] == 'object'
+
+    case resolved&.fetch('type', nil)
     when 'integer' then 'Integer'
     when 'boolean' then 'Boolean'
     when 'array' then 'Array'
@@ -645,6 +669,10 @@ class ServiceGenerator
       lines << '      # @return [Hash] response data'
     elsif is_paginated
       lines << '      # @return [Enumerator<Hash>] paginated results'
+    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.
+      lines << '      # @return [Array<Hash>] response data'
     else
       lines << '      # @return [Hash] response data'
     end
@@ -691,10 +719,11 @@ class ServiceGenerator
     kwargs << "operation: \"#{op[:method_name]}\""
     kwargs << "is_mutation: #{op[:is_mutation]}"
 
-    project_param = op[:path_params].find { |p| p[:name] == 'projectId' }
-    resource_param = op[:path_params].reject { |p| p[:name] == 'projectId' }.last
+    project_param = op[:path_params].find { |p| %w[projectId bucketId].include?(p[:name]) }
+    resource_param = op[:path_params].reject { |p| %w[projectId bucketId].include?(p[:name]) }
+      .select { |p| p[:name].end_with?("Id") || p[:name] == "id" }.last
 
-    kwargs << "project_id: project_id" if project_param
+    kwargs << "project_id: #{to_snake_case(project_param[:name])}" if project_param
     kwargs << "resource_id: #{to_snake_case(resource_param[:name])}" if resource_param
 
     kwargs.join(', ')
@@ -788,7 +817,7 @@ class ServiceGenerator
     # Build params hash for query params
     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_params(#{param_names.join(', ')})"
+      lines << "        params = compact_query_params(#{param_names.join(', ')})"
       lines << "        paginate(#{path_expr}, params: params)"
     else
       lines << "        paginate(#{path_expr})"
@@ -802,7 +831,7 @@ 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_params(#{param_names.join(', ')})"
+      lines << "        params = compact_query_params(#{param_names.join(', ')})"
       lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", params: params)"
     else
       lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\")"
@@ -834,7 +863,7 @@ class ServiceGenerator
       lines << "        http_#{http_method}(#{path_expr}, body: #{body_expr}).json"
     elsif op[:query_params].any?
       param_names = op[:query_params].map { |q| "#{to_snake_case(q[:name])}: #{to_snake_case(q[:name])}" }
-      lines << "        http_#{http_method}(#{path_expr}, params: compact_params(#{param_names.join(', ')})).json"
+      lines << "        http_#{http_method}(#{path_expr}, params: compact_query_params(#{param_names.join(', ')})).json"
     else
       lines << "        http_#{http_method}(#{path_expr}).json"
     end

data/scripts/generate-types.rb

@@ -87,6 +87,33 @@ def generate_helpers
   HELPERS
 end
 
+# Renders a deprecation +reason+ as one or more Ruby comment lines (#406).
+#
+# A reason can be sourced from a multi-line OpenAPI description. Interpolating
+# one into a single "# @deprecated ..." line would leave every continuation on a
+# bare, un-commented source line, which is a syntax error in the generated
+# types.rb — Ruby is the only owned generator exposed this way (Python escapes
+# the reason, Kotlin/TypeScript emit block comments). Splitting on line
+# boundaries and prefixing each line with the comment leader keeps the output
+# valid for any reason.
+#
+# +indent+ is the leading source indentation; +tag_prefix+ is inserted between
+# the "# " leader and the YARD tag (the per-attribute site nests its tag under
+# an @!attribute directive). Continuation lines are indented two columns past
+# the tag so YARD folds them into the same tag's text.
+#
+# Single-line reasons render byte-identically to the previous single-line
+# interpolation, so this is output-neutral for the current spec.
+def deprecation_doc_lines(reason, indent:, tag_prefix: '')
+  lines = reason.to_s.split(/\r?\n/, -1)
+  out = [ "#{indent}# #{tag_prefix}@deprecated #{lines.first}" ]
+  continuation = "#{indent}# #{tag_prefix}  "
+  lines.drop(1).each do |line|
+    out << (line.empty? ? "#{indent}#" : "#{continuation}#{line}")
+  end
+  out
+end
+
 # Main execution
 if __FILE__ == $PROGRAM_NAME
   openapi_path = ARGV[0] || File.expand_path('../../openapi.json', __dir__)
@@ -124,6 +151,12 @@ if __FILE__ == $PROGRAM_NAME
 
     puts ''
     puts "    # #{name}"
+    # Documentation-only deprecation (see #406): YARD marks a whole class/method,
+    # not individual params, so a class-level @deprecated tag documents a wholly
+    # deprecated type.
+    if schema['deprecated']
+      puts deprecation_doc_lines(schema['x-deprecated-reason'] || 'deprecated', indent: '    ')
+    end
     puts "    class #{name}"
     puts '      include TypeHelpers'
 
@@ -131,6 +164,19 @@ if __FILE__ == $PROGRAM_NAME
     # Add system_label for schemas with flexible integer fields
     has_flexible = ordered_props.any? { |k| properties[k]['x-go-type']&.include?('FlexibleInt64') }
     attr_names << 'system_label' if has_flexible
+
+    # Per-attribute deprecation. The accessors are declared in one grouped
+    # attr_accessor, so a bare comment would wrongly document every attribute;
+    # a YARD @!attribute directive scopes the @deprecated tag to just this one.
+    ordered_props.each do |k|
+      ps = properties[k]
+      next unless ps['deprecated']
+
+      ruby_name = k.gsub(/([A-Z])/, '_\1').downcase.gsub(/^_/, '')
+      puts "      # @!attribute [rw] #{ruby_name}"
+      puts deprecation_doc_lines(ps['x-deprecated-reason'] || 'deprecated', indent: '      ', tag_prefix: '  ')
+    end
+
     puts "      attr_accessor #{attr_names.map { |n| ":#{n}" }.join(", ")}"
 
     unless required_props.empty?
@@ -182,7 +228,20 @@ if __FILE__ == $PROGRAM_NAME
       attr_name = prop_name.gsub(/([A-Z])/, '_\1').downcase.gsub(/^_/, '')
       puts "          \"#{prop_name}\" => @#{attr_name},"
     end
-    puts '        }.compact'
+    # A required-and-nullable field (OpenAPI 3.1 `type: [..., "null"]`) carries an
+    # explicit null that must survive to_h; plain .compact would drop it. Keep
+    # nil for exactly those keys — required-but-non-nullable fields still get
+    # dropped when nil, like any other nil. Everything else keeps .compact.
+    required_nullable = required_fields.select do |k|
+      t = properties[k] && properties[k]['type']
+      t.is_a?(Array) && t.include?('null')
+    end
+    if required_nullable.any?
+      keep_list = required_nullable.map { |k| "\"#{k}\"" }.join(', ')
+      puts "        }.reject { |k, v| v.nil? && ![#{keep_list}].include?(k) }"
+    else
+      puts '        }.compact'
+    end
     puts '      end'
     puts ''
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -196,6 +196,7 @@ files:
 - lib/basecamp/generated/services/comments_service.rb
 - lib/basecamp/generated/services/documents_service.rb
 - lib/basecamp/generated/services/events_service.rb
+- lib/basecamp/generated/services/everything_service.rb
 - lib/basecamp/generated/services/forwards_service.rb
 - lib/basecamp/generated/services/gauges_service.rb
 - lib/basecamp/generated/services/hill_charts_service.rb
@@ -223,6 +224,7 @@ files:
 - lib/basecamp/generated/services/uploads_service.rb
 - lib/basecamp/generated/services/vaults_service.rb
 - lib/basecamp/generated/services/webhooks_service.rb
+- lib/basecamp/generated/services/wormholes_service.rb
 - lib/basecamp/generated/types.rb
 - lib/basecamp/hooks.rb
 - lib/basecamp/http.rb
@@ -252,6 +254,7 @@ files:
 - lib/basecamp/request_result.rb
 - lib/basecamp/security.rb
 - lib/basecamp/services/authorization_service.rb
+- lib/basecamp/services/cards_extensions.rb
 - lib/basecamp/services/todos_extensions.rb
 - lib/basecamp/static_token_provider.rb
 - lib/basecamp/token_provider.rb