basecamp-sdk 0.9.0 → 0.10.0

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.9.0"
-  API_VERSION = "2026-07-24"
+  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

@@ -146,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',
@@ -424,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,
@@ -440,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')
@@ -658,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

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__)
@@ -128,7 +155,7 @@ if __FILE__ == $PROGRAM_NAME
     # not individual params, so a class-level @deprecated tag documents a wholly
     # deprecated type.
     if schema['deprecated']
-      puts "    # @deprecated #{schema['x-deprecated-reason'] || 'deprecated'}"
+      puts deprecation_doc_lines(schema['x-deprecated-reason'] || 'deprecated', indent: '    ')
     end
     puts "    class #{name}"
     puts '      include TypeHelpers'
@@ -147,7 +174,7 @@ if __FILE__ == $PROGRAM_NAME
 
       ruby_name = k.gsub(/([A-Z])/, '_\1').downcase.gsub(/^_/, '')
       puts "      # @!attribute [rw] #{ruby_name}"
-      puts "      #   @deprecated #{ps['x-deprecated-reason'] || 'deprecated'}"
+      puts deprecation_doc_lines(ps['x-deprecated-reason'] || 'deprecated', indent: '      ', tag_prefix: '  ')
     end
 
     puts "      attr_accessor #{attr_names.map { |n| ":#{n}" }.join(", ")}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-26 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
@@ -253,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