basecamp-sdk 0.7.3 → 0.8.0

data/lib/basecamp/security.rb

@@ -10,6 +10,15 @@ module Basecamp
     MAX_RESPONSE_BODY_BYTES = 50 * 1024 * 1024 # 50 MB
     MAX_ERROR_BODY_BYTES = 1 * 1024 * 1024      # 1 MB
 
+    # The Launchpad authorization endpoint is on a different origin than the
+    # configured API base URL, so it is a sanctioned destination for a
+    # credentialed cross-origin request. Resource-first discovery may also
+    # authorize one specific discovered-and-validated issuer origin (see
+    # Http#get_authorization_document, whose issuer comes from internal discovery
+    # of the configured base URL, not a caller argument); every other foreign
+    # origin is rejected.
+    LAUNCHPAD_AUTHORIZATION_URL = "https://launchpad.37signals.com/authorization.json"
+
     def self.truncate(str, max = MAX_ERROR_MESSAGE_BYTES)
       return str if str.nil? || str.bytesize <= max
 
@@ -64,6 +73,9 @@ module Basecamp
       uri = URI.parse(url.to_s)
       host = uri.host&.downcase
       return false if host.nil?
+      # The carve-out is limited to HTTP(S) so credential guards fail closed
+      # on any other scheme (e.g. ws://localhost).
+      return false unless %w[http https].include?(uri.scheme&.downcase)
 
       host == "localhost" ||
         host == "127.0.0.1" ||
@@ -80,6 +92,77 @@ module Basecamp
       require_https!(url, label)
     end
 
+    # Parses a caller- or metadata-supplied origin and enforces the origin-root
+    # profile (SPEC.md §16): https (or http on localhost), host present, optional
+    # valid numeric port, path empty or exactly "/", and no query, fragment, or
+    # userinfo. Parsing uses Ruby's +URI+ (never a regex) so bracketed IPv6
+    # (+http://[::1]:3000+) and ports agree with the host the client dials.
+    #
+    # A bad *caller* origin is a usage error; callers validating an *advertised*
+    # origin rescue {UsageError} and reclassify.
+    #
+    # @param raw [String] the origin to validate
+    # @param label [String] a label for error messages
+    # @return [String] the normalized origin (+scheme://host[:port]+, no trailing slash)
+    # @raise [UsageError] on any profile violation or parse failure
+    def self.require_origin_root!(raw, label = "origin")
+      # Reject C0 controls, space, and backslash up front: URL parsers variously
+      # strip tabs/newlines/surrounding spaces or convert backslashes, so a
+      # malformed spelling could be cleaned and accepted. None is legitimate here.
+      if raw.to_s.match?(/[\x00-\x20\\]/)
+        raise UsageError.new("#{label} contains invalid characters: #{raw}")
+      end
+
+      uri = URI.parse(raw.to_s)
+      scheme = uri.scheme&.downcase
+
+      unless scheme == "https" || (scheme == "http" && localhost?(raw))
+        raise UsageError.new("#{label} must use HTTPS (or http on localhost): #{raw}")
+      end
+      raise UsageError.new("#{label} has no host: #{raw}") if uri.host.nil? || uri.host.empty?
+
+      # The raw authority (between "://" and the first "/?#") backs the presence
+      # checks the parsed fields miss: URI reports delimiter-only userinfo
+      # ("https://@example.com") as an empty (falsy) string, and normalizes a
+      # dangling port ("https://example.com:") to the default-port origin.
+      authority = raw.to_s.split("://", 2)[1].to_s.split(%r{[/?#]}, 2)[0].to_s
+
+      # Reject on the PRESENCE of userinfo, not truthiness: an "@" in the authority
+      # is always a userinfo delimiter (a host cannot contain one).
+      if uri.userinfo || authority.include?("@")
+        raise UsageError.new("#{label} must not contain userinfo: #{raw}")
+      end
+      raise UsageError.new("#{label} must not contain a query or fragment: #{raw}") if uri.query || uri.fragment
+      unless uri.path.nil? || uri.path.empty? || uri.path == "/"
+        raise UsageError.new("#{label} must be an origin root (no path): #{raw}")
+      end
+
+      # A dangling port delimiter ("https://example.com:") silently accepts a
+      # malformed authority. IPv6 authorities legitimately end with "]" (e.g.
+      # "[::1]"), so only a trailing ":" is a dangling port.
+      if authority.end_with?(":")
+        raise UsageError.new("#{label} has an invalid port: #{raw}")
+      end
+
+      # URI.parse rejects a non-numeric port, but it happily accepts a numeric
+      # port outside the valid TCP range (e.g. :0 or :99999). Reject anything
+      # outside 1–65535 so a structurally-parseable-but-undialable port can never
+      # be treated as a trusted origin.
+      if uri.port && !uri.port.between?(1, 65_535)
+        raise UsageError.new("#{label} has an out-of-range port: #{raw}")
+      end
+
+      # A surviving uri now has a structurally valid, in-range (or default) port.
+      # Drop the default port.
+      if uri.port && uri.port != uri.default_port
+        "#{scheme}://#{uri.host}:#{uri.port}"
+      else
+        "#{scheme}://#{uri.host}"
+      end
+    rescue URI::InvalidURIError
+      raise UsageError.new("Invalid #{label}: not a valid absolute URL: #{raw}")
+    end
+
     # Headers that contain sensitive values and should be redacted.
     SENSITIVE_HEADERS = %w[
       authorization

data/lib/basecamp/services/authorization_service.rb

@@ -0,0 +1,45 @@
+# 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
+      # Gets authorization information for the current user.
+      #
+      # Delegates to {Basecamp::Http#get_authorization_document}, which resolves
+      # the issuer via resource-first OAuth discovery (SPEC.md §16) on the client's
+      # own configured base URL and fetches the fixed +authorization.json+ path.
+      # Only the two *soft* fallback outcomes (+resource_discovery_failed+,
+      # +no_as_advertised+) fall back to Launchpad; every *hard* selection failure
+      # propagates as a {Oauth::DiscoverySelectionError} — a hard failure is never
+      # silently converted into a Launchpad request. This service passes NO issuer,
+      # config, or origin to the credentialed fetch, so there is no caller-supplied
+      # path through which the bearer token could be sent to a foreign host.
+      #
+      # Returns the authenticated user's identity and list of accounts
+      # they have access to.
+      #
+      # @return [Hash] authorization info with string keys "identity" and
+      #   "accounts" (parsed JSON, not symbol keys)
+      # @raise [Oauth::DiscoverySelectionError] on a hard discovery failure after
+      #   a BC5 issuer was advertised and selected
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md
+      def get
+        # Wrap in with_operation like every other service call so observability
+        # hooks (logging, metrics, tracing) see this credentialed request and its
+        # failures too.
+        with_operation(service: "authorization", operation: "get", is_mutation: false) do
+          http.get_authorization_document.json
+        end
+      end
+    end
+  end
+end

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.8.0"
+  API_VERSION = "2026-07-22"
 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
       ]
     },
@@ -69,7 +69,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,7 +115,7 @@ class ServiceGenerator
       'ClientVisibility' => %w[SetClientVisibility]
     },
     'Todos' => {
-      'Todos' => %w[ListTodos CreateTodo GetTodo UpdateTodo CompleteTodo UncompleteTodo TrashTodo],
+      'Todos' => %w[ListTodos CreateTodo GetTodo ReplaceTodo CompleteTodo UncompleteTodo TrashTodo],
       'Todolists' => %w[GetTodolistOrGroup UpdateTodolistOrGroup ListTodolists CreateTodolist],
       'Todosets' => %w[GetTodoset],
       'HillCharts' => %w[GetHillChart UpdateHillChartSettings],
@@ -190,6 +190,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 +245,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 +265,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
@@ -542,6 +569,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'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-07-22 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
@@ -248,11 +233,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 +251,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