basecamp-sdk 0.18.0 → 0.20.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,7 +80,6 @@ class ServiceGenerator
     'Schedule' => 'Schedules',
     'People' => 'People',
     'Projects' => 'Projects',
-    'Automation' => 'Automation',
     'ClientFeatures' => 'ClientFeatures',
     'Boosts' => 'Boosts',
     'Untagged' => 'Miscellaneous'
@@ -56,6 +102,7 @@ class ServiceGenerator
         GetCardColumn UpdateCardColumn SetCardColumnColor
         EnableCardColumnOnHold DisableCardColumnOnHold
         CreateCardColumn MoveCardColumn
+        SubscribeToCardColumn UnsubscribeFromCardColumn
       ],
       'CardSteps' => %w[
         GetCardStep CreateCardStep UpdateCardStep SetCardStepCompletion
@@ -71,22 +118,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],
@@ -365,14 +401,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)
 
@@ -440,6 +540,14 @@ class ServiceGenerator
     # Extract body parameters from schema
     body_params = extract_body_params(body_schema_ref)
 
+    # Only "link" and "cursor" are implemented. Anything else -- a typo, or the
+    # "page" style the trait used to advertise -- must fail loudly: read as "not
+    # paginated" it would silently ship a method that never walks.
+    pagination_style = operation.dig('x-basecamp-pagination', 'style')
+    if operation['x-basecamp-pagination'] && !%w[ link cursor ].include?(pagination_style)
+      raise "#{operation_id}: unsupported pagination style #{pagination_style.inspect} (expected \"link\" or \"cursor\")"
+    end
+
     # Check response
     success_response = operation.dig('responses', '200') || operation.dig('responses', '201')
     response_schema = success_response&.dig('content', 'application/json', 'schema')
@@ -470,8 +578,18 @@ class ServiceGenerator
       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')
+      # Auto-pagination is the "link" style alone: the generated method follows
+      # Link: rel="next" and flattens the walk into one array. The "cursor"
+      # style is declared for the catalogue and generates none -- each call
+      # returns one page carrying its own opaque position, and flattening would
+      # swallow every intermediate one.
+      has_pagination: pagination_style == 'link',
+      # Carried separately because has_pagination is false for cursor, and the
+      # bare-array gate below would otherwise walk it anyway.
+      cursor_pagination: pagination_style == 'cursor',
+      # Link-style only: the key drives envelope unwrapping, and a cursor
+      # operation must be typed as its envelope rather than the item under it.
+      pagination_key: (pagination_style == 'link' ? operation.dig('x-basecamp-pagination', 'key') : nil)
     }
   end
 
@@ -657,7 +775,10 @@ class ServiceGenerator
   def generate_method(op, service_name:)
     lines = []
 
-    is_paginated = (op[:returns_array] || op[:has_pagination]) && !op[:pagination_key]
+    # A cursor operation never walks, whatever its response shape: has_pagination
+    # is already false for it, but a bare-array response would otherwise send it
+    # down the Link-following path through returns_array.
+    is_paginated = !op[:cursor_pagination] && (op[:returns_array] || op[:has_pagination]) && !op[:pagination_key]
     is_wrapped_paginated = op[:has_pagination] && op[:pagination_key]
 
     # Method signature (paginated operations gain a trailing max_items: kwarg)
@@ -903,6 +1024,11 @@ class ServiceGenerator
     # 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]}\"" : ''
+    # Every verb names its operation to the body decode, which is a separate
+    # channel from the retry keyword above: the typed person-id decode
+    # (Basecamp::PersonIdSites) is keyed by operation id, and a mutation's
+    # response carries people exactly as a read's does.
+    json_call = ".json(operation: \"#{op[:operation_id]}\")"
 
     if op[:has_binary_body]
       # Binary upload - use raw body and set Content-Type header
@@ -914,18 +1040,18 @@ class ServiceGenerator
         query_string = query_parts.join('&')
         # Modify path_expr to include query string
         path_expr_with_query = path_expr.sub(/"$/, "?#{query_string}\"")
-        lines << "        http_#{http_method}_raw(#{path_expr_with_query}, body: data, content_type: content_type).json"
+        lines << "        http_#{http_method}_raw(#{path_expr_with_query}, body: data, content_type: content_type)#{json_call}"
       else
-        lines << "        http_#{http_method}_raw(#{path_expr}, body: data, content_type: content_type).json"
+        lines << "        http_#{http_method}_raw(#{path_expr}, body: data, content_type: content_type)#{json_call}"
       end
     elsif op[:has_body]
       body_expr = build_body_expression(op)
-      lines << "        http_#{http_method}(#{path_expr}, body: #{body_expr}).json"
+      lines << "        http_#{http_method}(#{path_expr}, body: #{body_expr})#{json_call}"
     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(', ')})#{operation_arg}).json"
+      lines << "        http_#{http_method}(#{path_expr}, params: compact_query_params(#{param_names.join(', ')})#{operation_arg})#{json_call}"
     else
-      lines << "        http_#{http_method}(#{path_expr}#{operation_arg}).json"
+      lines << "        http_#{http_method}(#{path_expr}#{operation_arg})#{json_call}"
     end
 
     lines

data/scripts/generate-types.rb

@@ -47,6 +47,23 @@ def generate_helpers
         value.to_i
       end
 
+      # A PERSON's id: the one field in this model the reference decodes
+      # flexibly (x-go-type: types.FlexibleInt64), and the only one that may
+      # arrive as a JSON string.
+      #
+      # Read with Basecamp::Ids.person_from_wire, which is Go's
+      # strconv.ParseInt(s, 10, 64) and is already the rule at the other two
+      # person-id sites (the pre-decode normalizer in Basecamp::Http and the
+      # flexible reader itself). NOT parse_integer, whose to_i answers 0 for
+      # "basecamp" without recording the label, 8 for "010", and — since the
+      # normalizer now leaves an out-of-range id as a String for the reader to
+      # refuse — a bignum for "18446744073709551616x", which is not an id any
+      # API can hold. A refused id is nil here, the same nil a malformed value
+      # of any other type gets.
+      def parse_flexible_person_id(value)
+        Basecamp::Ids.person_from_wire(value)
+      end
+
       def parse_float(value)
         return nil if value.nil?
         value.to_f
@@ -203,6 +220,8 @@ if __FILE__ == $PROGRAM_NAME
       elsif prop_schema['type'] == 'array' && prop_schema.dig('items', '$ref')
                     ref_name = prop_schema['items']['$ref'].split('/').last
                     "parse_array(data[\"#{prop_name}\"], \"#{ref_name}\")"
+      elsif prop_schema['x-go-type']&.include?('FlexibleInt64')
+                    "parse_flexible_person_id(data[\"#{prop_name}\"])"
       elsif prop_schema['type'] == 'integer'
                     "parse_integer(data[\"#{prop_name}\"])"
       elsif prop_schema['type'] == 'number'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -169,6 +169,9 @@ files:
 - lib/basecamp/auth_error.rb
 - lib/basecamp/auth_strategy.rb
 - lib/basecamp/bearer_auth.rb
+- lib/basecamp/bucket_mismatch_error.rb
+- lib/basecamp/campfire_discovery_incomplete_error.rb
+- lib/basecamp/campfire_index.rb
 - lib/basecamp/chain_hooks.rb
 - lib/basecamp/client.rb
 - lib/basecamp/config.rb
@@ -180,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
@@ -200,6 +202,7 @@ files:
 - lib/basecamp/generated/services/comments_service.rb
 - lib/basecamp/generated/services/documents_service.rb
 - lib/basecamp/generated/services/drafts_service.rb
+- lib/basecamp/generated/services/event_feed_service.rb
 - lib/basecamp/generated/services/events_service.rb
 - lib/basecamp/generated/services/everything_service.rb
 - lib/basecamp/generated/services/folders_service.rb
@@ -236,10 +239,12 @@ files:
 - lib/basecamp/generated/types.rb
 - lib/basecamp/hooks.rb
 - lib/basecamp/http.rb
+- lib/basecamp/ids.rb
 - lib/basecamp/limit_exceeded_error.rb
 - lib/basecamp/list_enumerator.rb
 - lib/basecamp/list_meta.rb
 - lib/basecamp/logger_hooks.rb
+- lib/basecamp/mentions.rb
 - lib/basecamp/network_error.rb
 - lib/basecamp/noop_hooks.rb
 - lib/basecamp/not_found_error.rb
@@ -264,19 +269,26 @@ files:
 - lib/basecamp/operation_info.rb
 - lib/basecamp/operation_result.rb
 - lib/basecamp/people_confirmation_required_error.rb
+- lib/basecamp/person_id_sites.rb
 - lib/basecamp/rate_limit_error.rb
+- lib/basecamp/recording_routing_error.rb
+- lib/basecamp/recording_summary_error.rb
 - lib/basecamp/request_info.rb
 - lib/basecamp/request_result.rb
 - lib/basecamp/security.rb
 - lib/basecamp/services/authorization_service.rb
 - lib/basecamp/services/cards_extensions.rb
+- lib/basecamp/services/comments_extensions.rb
 - lib/basecamp/services/documents_extensions.rb
 - lib/basecamp/services/merge_safe.rb
+- lib/basecamp/services/recordings_extensions.rb
 - lib/basecamp/services/schedules_extensions.rb
 - lib/basecamp/services/todolists_extensions.rb
 - lib/basecamp/services/todos_extensions.rb
 - lib/basecamp/static_token_provider.rb
+- lib/basecamp/text.rb
 - lib/basecamp/token_provider.rb
+- lib/basecamp/unresolved_recording_error.rb
 - lib/basecamp/usage_error.rb
 - lib/basecamp/validation_error.rb
 - lib/basecamp/version.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
-        end
-      end
-    end
-  end
-end