basecamp-sdk 0.9.0 → 0.11.0

data/lib/basecamp/oauth/oauth_error.rb

@@ -4,7 +4,9 @@ module Basecamp
   module Oauth
     # OAuth-specific error class.
     #
-    # @attr type [String] Error type ("validation", "auth", "network", "api_error")
+    # @attr type [String] Error type ("validation", "auth", "network",
+    #   "api_error", or "usage" — the parent type {DeviceFlowError} derives for
+    #   a cancelled device flow)
     # @attr http_status [Integer, nil] HTTP status code if applicable
     # @attr hint [String, nil] Helpful hint for resolving the error
     # @attr retryable [Boolean] Whether the request can be retried

data/lib/basecamp/oauth/refresh_request.rb

@@ -9,19 +9,25 @@ module Basecamp
     # @attr client_id [String, nil] The client identifier (optional)
     # @attr client_secret [String, nil] The client secret (optional)
     # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
+    # @attr resource [String, nil] RFC 8707 resource indicator to bind the
+    #   refreshed token to, sent only when set. Echo the stored token's
+    #   resource: BC5 multi-account refresh tokens hard-require it (SPEC §16).
+    #   Appended last so earlier members keep their positions.
     RefreshRequest = Data.define(
       :token_endpoint,
       :refresh_token,
       :client_id,
       :client_secret,
-      :use_legacy_format
+      :use_legacy_format,
+      :resource
     ) do
       def initialize(
         token_endpoint:,
         refresh_token:,
         client_id: nil,
         client_secret: nil,
-        use_legacy_format: false
+        use_legacy_format: false,
+        resource: nil
       )
         super
       end

data/lib/basecamp/oauth/resource.rb

@@ -5,25 +5,28 @@ module Basecamp
     # Fetches RFC 9728 protected-resource metadata (hop 1 of resource-first
     # discovery) and binds the returned +resource+ to the requested origin.
     class Resource
-      # @param http_client [Faraday::Connection, nil] HTTP client (SSRF-hardened default if nil)
-      # @param timeout [Integer] request timeout in seconds (default: 10)
+      # @param http_client [Faraday::Connection, nil] injected Faraday client
+      #   (kept, verified redirect-free); nil selects the default headers-first
+      #   Net::HTTP transport ({Fetcher.stream_http})
+      # @param timeout [Numeric] request timeout in seconds (default: 10); an
+      #   invalid value falls back via {Fetcher.normalize_timeout}
       # @param max_body_bytes [Integer] bounded read cap in bytes
       def initialize(http_client: nil, timeout: 10, max_body_bytes: Fetcher::DEFAULT_MAX_BODY_BYTES)
         Fetcher.ensure_redirects_suppressed!(http_client) if http_client
-        # Normalize before building the client and before the fetch computes its
+        # Normalize before storing (nil selects the headers-first Net::HTTP
+        # transport; an injected client is kept) and before the fetch computes its
         # wall-clock deadline: a non-finite/non-positive timeout must not disable
         # either bound (see Fetcher.normalize_timeout).
         @timeout = Fetcher.normalize_timeout(timeout)
-        @http_client = http_client || Fetcher.build_client(@timeout)
+        # nil selects the headers-first {Fetcher.stream_http} transport (total
+        # wall-clock bound incl. the header phase); an injected connection keeps
+        # the Faraday path, verified redirect-free above.
+        @http_client = http_client
         # Normalize the public cap to a finite non-negative Integer: a nil, float,
         # or Float::INFINITY would otherwise disable the streaming memory bound
         # (an infinite/undefined cap never trips), reintroducing an SSRF/OOM risk.
-        @max_body_bytes =
-          if max_body_bytes.is_a?(Integer) && max_body_bytes >= 0
-            max_body_bytes
-          else
-            Fetcher::DEFAULT_MAX_BODY_BYTES
-          end
+        # Shared with Discovery and the device flow.
+        @max_body_bytes = Fetcher.normalize_body_cap(max_body_bytes)
       end
 
       # Discovers protected-resource metadata from

data/lib/basecamp/oauth/token.rb

@@ -10,13 +10,18 @@ module Basecamp
     # @attr expires_in [Integer, nil] Lifetime of the access token in seconds
     # @attr expires_at [Time, nil] Calculated expiration time
     # @attr scope [String, nil] OAuth scope granted
+    # @attr resource [String, nil] RFC 8707 resource indicator the token is
+    #   bound to (BC5: +urn:bc:account:<id>+). Echo it when refreshing —
+    #   BC5 multi-account refresh tokens reject a refresh without it
+    #   (SPEC §16). Appended last so earlier members keep their positions.
     Token = Data.define(
       :access_token,
       :token_type,
       :refresh_token,
       :expires_in,
       :expires_at,
-      :scope
+      :scope,
+      :resource
     ) do
       def initialize(
         access_token:,
@@ -24,7 +29,8 @@ module Basecamp
         refresh_token: nil,
         expires_in: nil,
         expires_at: nil,
-        scope: nil
+        scope: nil,
+        resource: nil
       )
         # Calculate expires_at from expires_in if not provided
         calculated_expires_at = expires_at || (expires_in ? Time.now + expires_in : nil)
@@ -34,7 +40,8 @@ module Basecamp
           refresh_token: refresh_token,
           expires_in: expires_in,
           expires_at: calculated_expires_at,
-          scope: scope
+          scope: scope,
+          resource: resource
         )
       end
 

data/lib/basecamp/oauth.rb

@@ -133,12 +133,12 @@ module Basecamp
     def self.refresh_token(
       token_endpoint:, refresh_token:,
       client_id: nil, client_secret: nil,
-      use_legacy_format: false, timeout: 30
+      use_legacy_format: false, timeout: 30, resource: nil
     )
       request = RefreshRequest.new(
         token_endpoint: token_endpoint, refresh_token: refresh_token,
         client_id: client_id, client_secret: client_secret,
-        use_legacy_format: use_legacy_format
+        use_legacy_format: use_legacy_format, resource: resource
       )
       Exchange.new(timeout: timeout).refresh(request)
     end
@@ -147,6 +147,51 @@ module Basecamp
       token.expired?(buffer_seconds)
     end
 
+    # Requests an RFC 8628 device/user code pair. Thin delegator to
+    # {DeviceFlow.request_device_authorization}.
+    #
+    # @return [DeviceAuthorization]
+    def self.request_device_authorization(device_authorization_endpoint:, client_id:, scope: nil, timeout: DeviceFlow::DEVICE_REQUEST_TIMEOUT)
+      DeviceFlow.request_device_authorization(
+        device_authorization_endpoint: device_authorization_endpoint,
+        client_id: client_id, scope: scope, timeout: timeout
+      )
+    end
+
+    # Polls the token endpoint for a device grant (RFC 8628 §3.5). Thin delegator
+    # to {DeviceFlow.poll_device_token}; +clock+, +sleeper+, and +cancelled+ are
+    # injectable for tests.
+    #
+    # @return [Token]
+    def self.poll_device_token(
+      token_endpoint:, client_id:, device_code:, interval:, expires_in:,
+      clock: DeviceFlow::DEFAULT_CLOCK, sleeper: DeviceFlow::DEFAULT_SLEEPER,
+      cancelled: DeviceFlow::DEFAULT_CANCELLED, timeout: DeviceFlow::DEVICE_REQUEST_TIMEOUT,
+      deadline_at: nil
+    )
+      DeviceFlow.poll_device_token(
+        token_endpoint: token_endpoint, client_id: client_id,
+        device_code: device_code, interval: interval, expires_in: expires_in,
+        clock: clock, sleeper: sleeper, cancelled: cancelled, timeout: timeout,
+        deadline_at: deadline_at
+      )
+    end
+
+    # Runs the full device authorization grant against an already-selected
+    # {Config} (RFC 8628). Thin delegator to {DeviceFlow.perform_device_login}.
+    #
+    # @return [Token]
+    def self.perform_device_login(
+      config:, client_id:, display:, scope: nil,
+      clock: DeviceFlow::DEFAULT_CLOCK, sleeper: DeviceFlow::DEFAULT_SLEEPER,
+      cancelled: DeviceFlow::DEFAULT_CANCELLED, timeout: DeviceFlow::DEVICE_REQUEST_TIMEOUT
+    )
+      DeviceFlow.perform_device_login(
+        config: config, client_id: client_id, display: display, scope: scope,
+        clock: clock, sleeper: sleeper, cancelled: cancelled, timeout: timeout
+      )
+    end
+
     # Selects an issuer from the advertised set and — once a BC5 issuer is
     # committed — binds its AS metadata. From this point on, every failure is
     # fatal: no Launchpad request may be issued.

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.11.0"
+  API_VERSION = "2026-07-30"
 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
@@ -803,9 +818,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)"
+      lines << "        paginate(#{path_expr}, params: params, operation: \"#{op[:operation_id]}\")"
     else
-      lines << "        paginate(#{path_expr})"
+      lines << "        paginate(#{path_expr}, operation: \"#{op[:operation_id]}\")"
     end
 
     lines
@@ -817,9 +832,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_wrapped(#{path_expr}, key: \"#{pagination_key}\", params: params)"
+      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", params: params, operation: \"#{op[:operation_id]}\")"
     else
-      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\")"
+      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", operation: \"#{op[:operation_id]}\")"
     end
 
     lines
@@ -828,6 +843,9 @@ class ServiceGenerator
   def generate_get_method_body(op, path_expr)
     lines = []
     http_method = op[:http_method].downcase
+    # Only GETs are retry-governed in Ruby, and only Http#get accepts the
+    # operation keyword — mutations go through single_request with no retry.
+    operation_arg = http_method == 'get' ? ", operation: \"#{op[:operation_id]}\"" : ''
 
     if op[:has_binary_body]
       # Binary upload - use raw body and set Content-Type header
@@ -848,9 +866,9 @@ 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_query_params(#{param_names.join(', ')})).json"
+      lines << "        http_#{http_method}(#{path_expr}, params: compact_query_params(#{param_names.join(', ')})#{operation_arg}).json"
     else
-      lines << "        http_#{http_method}(#{path_expr}).json"
+      lines << "        http_#{http_method}(#{path_expr}#{operation_arg}).json"
     end
 
     lines

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.11.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-26 00:00:00.000000000 Z
+date: 2026-07-31 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
@@ -233,6 +234,9 @@ files:
 - lib/basecamp/not_found_error.rb
 - lib/basecamp/oauth.rb
 - lib/basecamp/oauth/config.rb
+- lib/basecamp/oauth/device_authorization.rb
+- lib/basecamp/oauth/device_flow.rb
+- lib/basecamp/oauth/device_flow_error.rb
 - lib/basecamp/oauth/discovery.rb
 - lib/basecamp/oauth/discovery_result.rb
 - lib/basecamp/oauth/discovery_selection_error.rb
@@ -253,6 +257,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