basecamp-sdk 0.19.0 → 0.21.0

data/scripts/generate-services.rb

@@ -17,7 +17,54 @@ require 'set'
 
 # Service generator for Ruby SDK
 class ServiceGenerator
-  METHODS = %w[get post put patch delete].freeze
+  # A Path Item Object is read by EXCLUSION. Its non-operation fields are a
+  # closed, spec-defined set and its extensions are `x-` prefixed, so every
+  # OTHER field is an operation. Enumerating the verbs instead is the defect
+  # this replaces (#925): Smithy's `@http` trait takes the method as a
+  # free-form string it "will use literally and will perform no validation
+  # on", so a model author writing `method: "HEAD"` produced a valid model, a
+  # valid openapi.json, and no method on any service — the verb was not in the
+  # list, so the operation was stepped over in silence.
+  NON_OPERATION_FIELDS = %w[summary description servers parameters].freeze
+
+  # Discovery above is total; emission is bounded by the ONE declaration every
+  # generator reads (spec/generated-verbs.json), whose header carries the
+  # reasoning. Each verb in it has an `Http` helper (`http_get`, `http_post`, …)
+  # the emitted method body calls. An operation on any other verb stops this
+  # generator by name instead of vanishing from the SDK — a loud refusal is the
+  # acceptable outcome, a silent drop never was.
+  #
+  # The declaration is ORDERED, and that order is emission order. Ordering is a
+  # different job from deciding membership and cannot reproduce #925: membership
+  # is decided by exclusion above, so a verb absent from the declaration is
+  # refused, never skipped.
+  # The self-test points this at a crafted declaration to prove the bound is
+  # sourced from the shared file rather than a private literal; production runs
+  # never set it.
+  GENERATED_VERBS_FILE = ENV.fetch(
+    'BASECAMP_GENERATED_VERBS', File.expand_path('../../spec/generated-verbs.json', __dir__)
+  )
+
+  EMITTABLE_METHODS = begin
+    verbs = JSON.parse(File.read(GENERATED_VERBS_FILE, encoding: 'UTF-8'))['verbs']
+    # An HTTP method is a TOKEN, so the rule is a positive character class rather
+    # than a blankness predicate: `[a-z]+`, identical in all six loaders. Two
+    # review rounds chased "blank" across languages — Kotlin and Rust rejected a
+    # space while the others accepted it, then Ruby's ASCII `strip` accepted a
+    # non-breaking space the Unicode-aware ones rejected — and the next
+    # disagreement was guaranteed, because every language defines whitespace
+    # differently (Java's Character.isWhitespace excludes U+00A0; Rust's
+    # char::is_whitespace includes it; Ruby's String#strip is ASCII-only). A
+    # closed positive rule has no such seam: "", " ", "\u00a0", "GET" and 1 are
+    # all rejected the same way everywhere.
+    unless verbs.is_a?(Array) && !verbs.empty? && verbs.all? { |v| v.is_a?(String) && v.match?(/\A[a-z]+\z/) }
+      abort "Error: #{GENERATED_VERBS_FILE} must declare a non-empty `verbs` array of lowercase " \
+            'ASCII method names (/\A[a-z]+\z/).'
+    end
+    verbs.freeze
+  rescue Errno::ENOENT, JSON::ParserError => e
+    abort "Error: cannot read the generated-verb declaration #{GENERATED_VERBS_FILE}: #{e.message}"
+  end
 
   # Schema reference cache for resolving $ref
   attr_reader :schemas
@@ -33,9 +80,9 @@ class ServiceGenerator
     'Schedule' => 'Schedules',
     'People' => 'People',
     'Projects' => 'Projects',
-    'Automation' => 'Automation',
     'ClientFeatures' => 'ClientFeatures',
     'Boosts' => 'Boosts',
+    'Subtasks' => 'Subtasks',
     'Untagged' => 'Miscellaneous'
   }.freeze
 
@@ -72,22 +119,11 @@ class ServiceGenerator
       'CloudFiles' => %w[GetCloudFile CreateCloudFile UpdateCloudFile],
       'GoogleDocuments' => %w[GetGoogleDocument CreateGoogleDocument UpdateGoogleDocument]
     },
-    'Automation' => {
-      'Tools' => %w[GetTool UpdateTool DeleteTool CreateTool EnableTool DisableTool RepositionTool],
-      'Recordings' => %w[ArchiveRecording UnarchiveRecording TrashRecording ListRecordings SpotlightRecording UnspotlightRecording],
-      'Webhooks' => %w[ListWebhooks CreateWebhook GetWebhook UpdateWebhook DeleteWebhook],
-      'Events' => %w[ListEvents],
-      'Lineup' => %w[CreateLineupMarker UpdateLineupMarker DeleteLineupMarker],
-      'Search' => %w[Search GetSearchMetadata],
-      'Templates' => %w[
-        ListTemplates CreateTemplate GetTemplate UpdateTemplate
-        DeleteTemplate CreateProjectFromTemplate GetProjectConstruction
-        GetTemplateLibrary CreateTemplateLibraryCopy GetTemplateLibraryCopy
-      ],
-      'Checkins' => %w[
-        GetQuestionnaire ListQuestions CreateQuestion GetQuestion
-        UpdateQuestion ListAnswers CreateAnswer GetAnswer UpdateAnswer
-      ]
+    'Dock' => {
+      'Tools' => %w[GetTool UpdateTool DeleteTool CreateTool EnableTool DisableTool RepositionTool]
+    },
+    'Recordings' => {
+      'Events' => %w[ListEvents]
     },
     'Messages' => {
       'Messages' => %w[GetMessage UpdateMessage CreateMessage ListMessages PinMessage UnpinMessage],
@@ -179,7 +215,10 @@ class ServiceGenerator
     'Search' => 'search',
     'CreateProjectFromTemplate' => 'create_project',
     'GetProjectConstruction' => 'get_construction',
-    'GetTemplateLibrary' => 'get_library',
+    'GetTemplateLibraryTodolists' => 'get_library_todolists',
+    'GetTemplateLibraryCardTables' => 'get_library_card_tables',
+    'CreateTemplateLibraryCardTable' => 'create_library_card_table',
+    'CreateTemplateLibraryTodolist' => 'create_library_todolist',
     'CreateTemplateLibraryCopy' => 'create_library_copy',
     'GetTemplateLibraryCopy' => 'get_library_copy',
     'GetRecordingTimesheet' => 'for_recording',
@@ -323,7 +362,7 @@ class ServiceGenerator
     lineupmarker clientapproval clientapprovals clientcorrespondence
     clientcorrespondences clientreply clientreplies forwardreply
     forwardreplies campfireline campfirelines todolistgroup todolistgroups
-    todolistorgroup uploadversions hillchart hillcharts
+    todolistorgroup uploadversions hillchart hillcharts subtask subtasks
     wormhole wormholes
   ].freeze
 
@@ -366,14 +405,78 @@ class ServiceGenerator
 
   private
 
+  # Yields [verb, operation] for every operation in a path item, identifying an
+  # operation by what it is NOT (see NON_OPERATION_FIELDS). Anything this
+  # generator cannot render aborts the run naming the operation.
+  def each_operation(path, path_item)
+    unless path_item.is_a?(Hash)
+      abort "Error: openapi.json path #{path} is a #{path_item.class}, not a path item object."
+    end
+
+    # A `$ref` path item points at operations this generator cannot see without
+    # resolving the reference. Skipping it is the same silent under-count the
+    # exclusion walk exists to prevent, so refuse until someone teaches it to
+    # follow one.
+    if path_item.key?('$ref')
+      abort "Error: openapi.json path #{path} is a $ref to #{path_item['$ref'].inspect}. " \
+            'This generator cannot resolve a path-item reference, and skipping it would hide ' \
+            'every operation behind it from the SDK. Inline the path item, or teach this ' \
+            'generator to resolve local references.'
+    end
+
+    # OpenAPI 3.2's `additionalOperations` is a MAP of method to Operation, not an
+    # operation. Read as one it carries no operationId, so it would drop every
+    # operation inside it without saying so. Refuse by name until the walk learns
+    # the map shape.
+    if path_item.key?('additionalOperations')
+      abort "Error: openapi.json path #{path} declares `additionalOperations`, which OpenAPI 3.2 " \
+            'defines as a map of method to Operation. This walk reads a path-item field as a ' \
+            'single operation, so it would drop every operation inside it. Teach the walk the map ' \
+            'shape, or take the field out of the spec.'
+    end
+
+    fields = path_item.keys.reject { |f| NON_OPERATION_FIELDS.include?(f) || f.start_with?('x-') }
+    fields.sort_by! { |f| [ EMITTABLE_METHODS.index(f) || EMITTABLE_METHODS.length, f ] }
+
+    fields.each do |field|
+      operation = path_item[field]
+
+      unless operation.is_a?(Hash)
+        abort "Error: openapi.json path #{path} field #{field.inspect} is a #{operation.class}, " \
+              'which is neither a known non-operation field nor an operation object. If a later ' \
+              'OpenAPI version added it, add it to NON_OPERATION_FIELDS with a reason.'
+      end
+
+      unless EMITTABLE_METHODS.include?(field)
+        op_id = operation['operationId'] || '(no operationId)'
+        abort "Error: openapi.json declares #{field.upcase} #{path} (#{op_id}), and this generator " \
+              "emits only #{EMITTABLE_METHODS.map(&:upcase).join('/')}. Generating the rest of the " \
+              'SDK without it would drop the operation from every Ruby client in silence, which is ' \
+              'the failure #925 closed. Give Basecamp::Http a ' \
+              "http_#{field} helper, add #{field.inspect} to spec/generated-verbs.json (read that " \
+              'file first — the other five SDKs need the same helper), or take the operation out ' \
+              'of the Smithy model.'
+      end
+
+      # An operation has to be IDENTIFIABLE. OpenAPI lets operationId be omitted,
+      # and every walker here used to step over one that was — a silent drop of a
+      # real operation, which is #925 wearing a different field.
+      op_id = operation['operationId']
+      unless op_id.is_a?(String) && !op_id.empty?
+        abort "Error: openapi.json declares #{field.upcase} #{path} with no operationId. " \
+              'Everything downstream is keyed by it, and skipping the operation would drop it ' \
+              'from the SDK in silence.'
+      end
+
+      yield field, operation
+    end
+  end
+
   def group_operations
     services = {}
 
     @openapi['paths'].each do |path, path_item|
-      METHODS.each do |method|
-        operation = path_item[method]
-        next unless operation
-
+      each_operation(path, path_item) do |method, operation|
         tag = operation['tags']&.first || 'Untagged'
         parsed = parse_operation(path, method, operation)
 
@@ -692,7 +795,7 @@ class ServiceGenerator
     op[:path_params].each do |p|
       ruby_name = to_snake_case(p[:name])
       type = p[:type] || 'Integer'
-      desc = p[:description] || "#{ruby_name.gsub('_', ' ')} ID"
+      desc = yard_param_description(p[:description] || "#{ruby_name.gsub('_', ' ')} ID")
       lines << "      # @param #{ruby_name} [#{type}] #{desc}"
     end
 

data/scripts/generate-types.rb

@@ -132,6 +132,59 @@ def deprecation_doc_lines(reason, indent:, tag_prefix: '')
   out
 end
 
+# Whether the main loop emits a class for this component. The alias pass checks
+# its targets against exactly this predicate, so an alias can never name a
+# class that was not emitted (a *RequestContent target used to produce
+# `Alias = CreateCardStepRequestContent`, a NameError the moment types.rb loads).
+def emits_class?(name, schema)
+  return false if SKIP_PATTERNS.any? { |p| name.match?(p) }
+
+  schema.is_a?(Hash) && schema['type'] == 'object' && !(schema['properties'] || {}).empty?
+end
+
+DEPRECATED_ALIAS_KEYS = %w[$ref deprecated description x-deprecated-reason].freeze
+
+# A component that is nothing but a deprecated $ref: a rename kept for
+# compatibility, e.g. CardStep -> Subtask. `deprecated` must be the JSON boolean
+# true, as in every other generator; 1 or "false" is not an alias.
+def deprecated_alias?(schema)
+  schema.is_a?(Hash) && schema['deprecated'] == true && schema['$ref'].is_a?(String) &&
+    (schema.keys - DEPRECATED_ALIAS_KEYS).empty?
+end
+
+# Constants Basecamp::Types already holds besides the generated classes.
+RESERVED_TYPE_CONSTANTS = %w[TypeHelpers].freeze
+
+# Every deprecated alias as [alias, target], sorted by alias. Aborts on one this
+# generator cannot place, the same cases every SDK generator refuses: a missing
+# target, an alias of an alias (rejected, not resolved), a target that is not an
+# object model, a target this generator does not emit, and a name collision.
+def deprecated_aliases(schemas)
+  schemas.keys.sort.filter_map do |name|
+    schema = schemas[name]
+    next unless deprecated_alias?(schema)
+
+    target = schema['$ref'].split('/').last
+    target_schema = schemas[target]
+    problem =
+      if !schemas.key?(target)
+        'target schema does not exist'
+      elsif deprecated_alias?(target_schema)
+        "target is itself a deprecated alias; point #{name} at the model directly"
+      elsif !(target_schema.is_a?(Hash) && target_schema['type'] == 'object' &&
+              !(target_schema['properties'] || {}).empty?)
+        'target is not an object model'
+      elsif !emits_class?(target, target_schema)
+        'target class was not emitted (SKIP_PATTERNS excludes it)'
+      elsif RESERVED_TYPE_CONSTANTS.include?(name)
+        "#{name} collides with an existing constant in Basecamp::Types"
+      end
+    abort "Error: deprecated alias #{name} -> #{target}: #{problem}" if problem
+
+    [ name, target ]
+  end
+end
+
 # Main execution
 if __FILE__ == $PROGRAM_NAME
   openapi_path = ARGV[0] || File.expand_path('../../openapi.json', __dir__)
@@ -141,6 +194,13 @@ if __FILE__ == $PROGRAM_NAME
     exit 1
   end
 
+  # UTF-8 regardless of process locale — see generate-metadata.rb
+  schemas = JSON.parse(File.read(openapi_path, encoding: 'UTF-8'))['components']['schemas'] || {}
+  sorted = schemas.keys.sort
+  # Validated before the first line is printed, so a refusal leaves no partial
+  # types.rb on stdout.
+  aliases = deprecated_aliases(schemas)
+
   puts header
   puts generate_helpers
   puts ''
@@ -148,18 +208,11 @@ if __FILE__ == $PROGRAM_NAME
   puts '  module Types'
   puts '    include TypeHelpers'
 
-  # UTF-8 regardless of process locale — see generate-metadata.rb
-  schemas = JSON.parse(File.read(openapi_path, encoding: 'UTF-8'))['components']['schemas'] || {}
-  sorted = schemas.keys.sort
-
   sorted.each do |name|
-    next if SKIP_PATTERNS.any? { |p| name.match?(p) }
-
     schema = schemas[name]
-    next unless schema['type'] == 'object'
+    next unless emits_class?(name, schema)
 
-    properties = schema['properties'] || {}
-    next if properties.empty?
+    properties = schema['properties']
 
     required_fields = schema['required'] || []
     required_set = required_fields.to_set
@@ -273,6 +326,17 @@ if __FILE__ == $PROGRAM_NAME
     puts '    end'
   end
 
+  # Deprecated former names (see deprecated_aliases), emitted after every class
+  # because the alias must reference an already-defined constant. The alias
+  # also keeps Basecamp::Types.const_get("CardStep") resolving.
+  aliases.each do |name, target|
+    schema = schemas[name]
+    puts ''
+    puts "    # #{name}"
+    puts deprecation_doc_lines(schema['x-deprecated-reason'] || 'deprecated', indent: '    ')
+    puts "    #{name} = #{target}"
+  end
+
   puts '  end'
   puts 'end'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -183,7 +183,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/automation_service.rb
 - lib/basecamp/generated/services/base_service.rb
 - lib/basecamp/generated/services/bookmarks_service.rb
 - lib/basecamp/generated/services/boosts_service.rb
@@ -225,6 +224,7 @@ files:
 - lib/basecamp/generated/services/schedules_service.rb
 - lib/basecamp/generated/services/search_service.rb
 - lib/basecamp/generated/services/subscriptions_service.rb
+- lib/basecamp/generated/services/subtasks_service.rb
 - lib/basecamp/generated/services/templates_service.rb
 - lib/basecamp/generated/services/timeline_service.rb
 - lib/basecamp/generated/services/timesheets_service.rb

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

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Basecamp
-  module Services
-    # Service for Automation operations
-    #
-    # @generated from OpenAPI spec
-    class AutomationService < BaseService
-
-      # List all lineup markers for the account
-      # @return [Array<Hash>] response data
-      def list_lineup_markers()
-        with_operation(service: "automation", operation: "list_lineup_markers", is_mutation: false) do
-          http_get("/lineup/markers.json", operation: "ListLineupMarkers").json(operation: "ListLineupMarkers")
-        end
-      end
-    end
-  end
-end