basecamp-sdk 0.7.3 → 0.9.0

data/lib/basecamp/services/todos_extensions.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Merge-safe +update+ and read-modify-write +edit+ for todos, prepended
+    # onto the generated {TodosService} (see the +on_load+ hook in
+    # +basecamp.rb+).
+    #
+    # Both compose the public +get+ and +replace+ methods, so hooks observe
+    # the two wire operations (+get+ then +replace+), not a synthetic
+    # composite.
+    #
+    # Neither is atomic: there is no conditional-update signal on this
+    # endpoint, so a concurrent write between the GET and PUT is
+    # overwritten — last write wins for the whole representation. The
+    # window is one round-trip. Use +replace+ to overwrite deliberately.
+    module TodosExtensions
+      # A todo's full writable state, yielded to the +edit+ block. The
+      # whole struct is PUT back to the server, so clearing a field means
+      # setting it empty (+""+ for strings and dates, +[]+ for ID lists) —
+      # there is no third state. +notify+ is a send directive, not todo
+      # state: never populated from the current todo, sent only when true.
+      TodoFields = Struct.new(
+        :content, :description, :assignee_ids, :completion_subscriber_ids,
+        :due_on, :starts_on, :notify,
+        keyword_init: true
+      )
+
+      # Sets the given fields on a todo and preserves everything else:
+      # GETs the current todo, overlays the explicitly-passed keyword
+      # arguments, and PUTs the full representation back. An omitted
+      # (+nil+) field is untouched, guaranteed; an explicitly-passed empty
+      # array clears.
+      #
+      # Not atomic — see the module docs for the GET→PUT race. Use
+      # {#replace} to overwrite deliberately, or {#edit} to clear fields.
+      #
+      # @param todo_id [Integer] todo id
+      # @param content [String, nil] new content (nil = keep current)
+      # @param description [String, nil] new description (nil = keep current)
+      # @param assignee_ids [Array, nil] complete assignee list ([] clears)
+      # @param completion_subscriber_ids [Array, nil] complete subscriber list ([] clears)
+      # @param notify [Boolean, nil] notify assignees about this write
+      # @param due_on [String, nil] due date YYYY-MM-DD (nil = keep current)
+      # @param starts_on [String, nil] start date YYYY-MM-DD (nil = keep current)
+      # @return [Hash] the updated todo
+      def update(todo_id:, content: nil, description: nil, assignee_ids: nil, completion_subscriber_ids: nil, notify: nil, due_on: nil, starts_on: nil)
+        fields = fields_from_todo(get(todo_id: todo_id))
+        fields.content = content unless content.nil?
+        fields.description = description unless description.nil?
+        fields.assignee_ids = assignee_ids unless assignee_ids.nil?
+        fields.completion_subscriber_ids = completion_subscriber_ids unless completion_subscriber_ids.nil?
+        fields.due_on = due_on unless due_on.nil?
+        fields.starts_on = starts_on unless starts_on.nil?
+        fields.notify = notify unless notify.nil?
+        put_fields(todo_id, fields)
+      end
+
+      # Applies a read-modify-write block to a todo: GETs the current todo,
+      # yields its full writable state ({TodoFields}), and PUTs the whole
+      # thing back. Clearing a field means setting it empty (+""+ / +[]+) —
+      # an untouched field keeps its current value. If the block raises,
+      # the edit aborts and nothing is written.
+      #
+      # Not atomic — see the module docs for the GET→PUT race.
+      #
+      # @example
+      #   account.todos.edit(todo_id: 123) do |t|
+      #     t.content = "🚨 #{t.content}"
+      #     t.due_on = "" # clearing = setting empty on a full object
+      #   end
+      #
+      # @param todo_id [Integer] todo id
+      # @yieldparam fields [TodoFields] the todo's writable state, to mutate in place
+      # @return [Hash] the updated todo
+      # @raise [ArgumentError] if no block is given
+      def edit(todo_id:)
+        raise ArgumentError, "edit requires a block" unless block_given?
+
+        fields = fields_from_todo(get(todo_id: todo_id))
+        yield fields
+        put_fields(todo_id, fields)
+      end
+
+      private
+
+      # Derives the full writable state from a GET response.
+      def fields_from_todo(todo)
+        TodoFields.new(
+          content: todo["content"] || "",
+          description: todo["description"] || "",
+          assignee_ids: (todo["assignees"] || []).map { |p| p["id"] },
+          completion_subscriber_ids: (todo["completion_subscribers"] || []).map { |p| p["id"] },
+          due_on: todo["due_on"] || "",
+          starts_on: todo["starts_on"] || "",
+          notify: false
+        )
+      end
+
+      # PUTs the full writable state via +replace+: content, description,
+      # and both ID lists are always sent (empties included, so clears
+      # survive); dates only when non-empty (the server clears an omitted
+      # date, and +""+ is a format error); notify only when true.
+      def put_fields(todo_id, fields)
+        %i[assignee_ids completion_subscriber_ids].each do |key|
+          raise UsageError, "#{key} must be an array of person IDs; use [] to clear — a full write has no nil state" if fields[key].nil?
+        end
+        replace(
+          todo_id: todo_id,
+          content: fields.content,
+          description: fields.description,
+          assignee_ids: fields.assignee_ids,
+          completion_subscriber_ids: fields.completion_subscriber_ids,
+          due_on: fields.due_on.to_s.empty? ? nil : fields.due_on,
+          starts_on: fields.starts_on.to_s.empty? ? nil : fields.starts_on,
+          notify: fields.notify ? true : nil
+        )
+      end
+    end
+  end
+end

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.7.3"
-  API_VERSION = "2026-03-23"
+  VERSION = "0.9.0"
+  API_VERSION = "2026-07-24"
 end

data/lib/basecamp.rb

@@ -4,6 +4,12 @@ require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
 loader.collapse("#{__dir__}/basecamp/generated")
+# The generated class owns the Basecamp::Services::TodosService constant
+# (generated/ is collapsed), so the hand-written merge-safe update/edit
+# surface is prepended onto it as soon as zeitwerk loads it.
+loader.on_load("Basecamp::Services::TodosService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::TodosExtensions)
+end
 loader.setup
 
 # Load generated types if available

data/scripts/generate-services.rb

@@ -45,7 +45,7 @@ class ServiceGenerator
       'Campfires' => %w[
         GetCampfire ListCampfires
         ListChatbots CreateChatbot GetChatbot UpdateChatbot DeleteChatbot
-        ListCampfireLines CreateCampfireLine GetCampfireLine DeleteCampfireLine
+        ListCampfireLines CreateCampfireLine GetCampfireLine UpdateCampfireLine DeleteCampfireLine
         ListCampfireUploads CreateCampfireUpload
       ]
     },
@@ -60,7 +60,8 @@ class ServiceGenerator
       'CardSteps' => %w[
         GetCardStep CreateCardStep UpdateCardStep SetCardStepCompletion
         RepositionCardStep
-      ]
+      ],
+      'Wormholes' => %w[CreateWormhole UpdateWormhole DeleteWormhole]
     },
     'Files' => {
       'Attachments' => %w[CreateAttachment],
@@ -69,7 +70,7 @@ class ServiceGenerator
       'Documents' => %w[GetDocument UpdateDocument ListDocuments CreateDocument]
     },
     'Automation' => {
-      'Tools' => %w[GetTool UpdateTool DeleteTool CloneTool EnableTool DisableTool RepositionTool],
+      'Tools' => %w[GetTool UpdateTool DeleteTool CreateTool EnableTool DisableTool RepositionTool],
       'Recordings' => %w[GetRecording ArchiveRecording UnarchiveRecording TrashRecording ListRecordings],
       'Webhooks' => %w[ListWebhooks CreateWebhook GetWebhook UpdateWebhook DeleteWebhook],
       'Events' => %w[ListEvents],
@@ -115,8 +116,8 @@ class ServiceGenerator
       'ClientVisibility' => %w[SetClientVisibility]
     },
     'Todos' => {
-      'Todos' => %w[ListTodos CreateTodo GetTodo UpdateTodo CompleteTodo UncompleteTodo TrashTodo],
-      'Todolists' => %w[GetTodolistOrGroup UpdateTodolistOrGroup ListTodolists CreateTodolist],
+      'Todos' => %w[ListTodos CreateTodo GetTodo ReplaceTodo CompleteTodo UncompleteTodo TrashTodo],
+      'Todolists' => %w[GetTodolistOrGroup UpdateTodolistOrGroup ListTodolists CreateTodolist RepositionTodolist],
       'Todosets' => %w[GetTodoset],
       'HillCharts' => %w[GetHillChart UpdateHillChartSettings],
       'TodolistGroups' => %w[ListTodolistGroups CreateTodolistGroup RepositionTodolistGroup]
@@ -190,6 +191,7 @@ class ServiceGenerator
     'ListCampfireLines' => 'list_lines',
     'CreateCampfireLine' => 'create_line',
     'GetCampfireLine' => 'get_line',
+    'UpdateCampfireLine' => 'update_line',
     'DeleteCampfireLine' => 'delete_line',
     'ListCampfireUploads' => 'list_uploads',
     'CreateCampfireUpload' => 'create_upload',
@@ -244,6 +246,7 @@ class ServiceGenerator
     { prefix: 'Get', method: 'get' },
     { prefix: 'Create', method: 'create' },
     { prefix: 'Update', method: 'update' },
+    { prefix: 'Replace', method: 'replace' },
     { prefix: 'Delete', method: 'delete' },
     { prefix: 'Trash', method: 'trash' },
     { prefix: 'Archive', method: 'archive' },
@@ -263,6 +266,31 @@ class ServiceGenerator
     { prefix: 'Search', method: 'search' }
   ].freeze
 
+  # Hand-written methods appended to specific generated services.
+  # Keyed by service name; value is an array of method code strings indented to match generated output.
+  HAND_WRITTEN_METHODS = {
+    'Uploads' => [
+      <<~RUBY.chomp
+        # Download an upload's file content in one call.
+        # Fetches upload metadata, then delegates to the AccountClient download
+        # primitive so the auth'd-hop + 302-follow flow lives in one place.
+        # @param upload_id [Integer] upload id ID
+        # @return [Basecamp::DownloadResult]
+        def download(upload_id:)
+          with_operation(service: "uploads", operation: "download", is_mutation: false, resource_id: upload_id) do
+            upload = get(upload_id: upload_id)
+            url = upload["download_url"]
+            raise UsageError.new("upload \#{upload_id} has no download_url") if url.nil? || url.empty?
+
+            result = @client.download_url(url)
+            filename = upload["filename"]
+            filename.to_s.empty? ? result : result.with(filename: filename)
+          end
+        end
+      RUBY
+    ]
+  }.freeze
+
   SIMPLE_RESOURCES = %w[
     todo todos todolist todolists todoset message messages comment comments
     card cards cardtable cardcolumn cardstep column step project projects
@@ -275,6 +303,7 @@ class ServiceGenerator
     clientcorrespondences clientreply clientreplies forwardreply
     forwardreplies campfireline campfirelines todolistgroup todolistgroups
     todolistorgroup uploadversions hillchart hillcharts
+    wormhole wormholes
   ].freeze
 
   def initialize(openapi_path)
@@ -369,7 +398,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']
@@ -506,7 +540,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'
@@ -542,6 +582,13 @@ class ServiceGenerator
       lines.concat(generate_method(op, service_name: service[:name]))
     end
 
+    (HAND_WRITTEN_METHODS[service[:name]] || []).each do |method_code|
+      lines << ''
+      method_code.each_line do |l|
+        lines << (l.chomp.empty? ? '' : "      #{l.chomp}")
+      end
+    end
+
     lines << '    end'
     lines << '  end'
     lines << 'end'
@@ -657,10 +704,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(', ')
@@ -754,7 +802,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})"
@@ -768,7 +816,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}\")"
@@ -800,7 +848,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

@@ -124,6 +124,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 "    # @deprecated #{schema['x-deprecated-reason'] || 'deprecated'}"
+    end
     puts "    class #{name}"
     puts '      include TypeHelpers'
 
@@ -131,6 +137,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 "      #   @deprecated #{ps['x-deprecated-reason'] || 'deprecated'}"
+    end
+
     puts "      attr_accessor #{attr_names.map { |n| ":#{n}" }.join(", ")}"
 
     unless required_props.empty?
@@ -182,7 +201,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.7.3
+  version: 0.9.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -128,28 +128,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
-- !ruby/object:Gem::Dependency
-  name: webrick
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -194,7 +180,6 @@ files:
 - lib/basecamp/generated/metadata.json
 - lib/basecamp/generated/services/account_service.rb
 - lib/basecamp/generated/services/attachments_service.rb
-- lib/basecamp/generated/services/authorization_service.rb
 - lib/basecamp/generated/services/automation_service.rb
 - lib/basecamp/generated/services/base_service.rb
 - lib/basecamp/generated/services/boosts_service.rb
@@ -238,6 +223,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
@@ -248,11 +234,16 @@ files:
 - lib/basecamp/oauth.rb
 - lib/basecamp/oauth/config.rb
 - lib/basecamp/oauth/discovery.rb
+- lib/basecamp/oauth/discovery_result.rb
+- lib/basecamp/oauth/discovery_selection_error.rb
 - lib/basecamp/oauth/exchange.rb
 - lib/basecamp/oauth/exchange_request.rb
+- lib/basecamp/oauth/fetcher.rb
 - lib/basecamp/oauth/oauth_error.rb
 - lib/basecamp/oauth/pkce.rb
+- lib/basecamp/oauth/protected_resource_metadata.rb
 - lib/basecamp/oauth/refresh_request.rb
+- lib/basecamp/oauth/resource.rb
 - lib/basecamp/oauth/token.rb
 - lib/basecamp/oauth_token_provider.rb
 - lib/basecamp/operation_info.rb
@@ -261,6 +252,8 @@ files:
 - lib/basecamp/request_info.rb
 - lib/basecamp/request_result.rb
 - lib/basecamp/security.rb
+- lib/basecamp/services/authorization_service.rb
+- lib/basecamp/services/todos_extensions.rb
 - lib/basecamp/static_token_provider.rb
 - lib/basecamp/token_provider.rb
 - lib/basecamp/usage_error.rb

data/lib/basecamp/generated/services/authorization_service.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Basecamp
-  module Services
-    # Service for authorization operations.
-    # This is the only service that doesn't require an account context.
-    #
-    # @example Get authorization info
-    #   auth = client.authorization.get
-    #   puts "Identity: #{auth["identity"]["email_address"]}"
-    #   auth["accounts"].each do |account|
-    #     puts "Account: #{account["name"]} (#{account["id"]})"
-    #   end
-    class AuthorizationService < BaseService
-      # Fallback Launchpad endpoint for authorization
-      LAUNCHPAD_AUTHORIZATION_URL = "https://launchpad.37signals.com/authorization.json"
-
-      # Gets authorization information for the current user.
-      #
-      # Attempts to use the authorization endpoint discovered via OAuth discovery
-      # on the configured base URL. Falls back to Launchpad if discovery fails.
-      #
-      # Returns the authenticated user's identity and list of accounts
-      # they have access to.
-      #
-      # @return [Hash] authorization info with :identity and :accounts
-      # @see https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md
-      def get
-        url = discover_authorization_url
-        response = http.get_absolute(url)
-        response.json
-      end
-
-      private
-
-        def discover_authorization_url
-          # Try OAuth discovery on the configured base URL
-          config = Oauth.discover(http.base_url)
-          # Use issuer as base for authorization.json
-          "#{config.issuer.chomp("/")}/authorization.json"
-        rescue Oauth::OauthError
-          # Fall back to Launchpad
-          LAUNCHPAD_AUTHORIZATION_URL
-        end
-    end
-  end
-end