basecamp-sdk 0.18.0 → 0.20.0

data/lib/basecamp/services/todolists_extensions.rb

@@ -180,9 +180,10 @@ module Basecamp
       # Ruby has no typed decoder between the GET and this read, unlike the Go,
       # Swift and Kotlin composites where a wrong-typed field fails at decode,
       # and flattening the shape did not add one: the generated method still
-      # returns <tt>http_get(...).json</tt> verbatim. The same shape is live in
-      # the shipped Todos composite; tracked in #576, with the generated
-      # validating layer that would retire this guard tracked in #578.
+      # returns <tt>http_get(...).json</tt> verbatim. The same shape in the
+      # shipped Todos composite is guarded by the MergeSafe checks #576 closed
+      # with; the generated validating layer that would retire this guard is
+      # tracked in #578.
       def writable_string(body, key, non_empty: false)
         raise_missing_field(key) unless body.key?(key)
 

data/lib/basecamp/text.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Text trimming that matches the reference's, byte for byte.
+  #
+  # Ruby's <tt>String#strip</tt> is NOT that function, and the difference runs
+  # in both directions. Measured over all 256 single bytes and the whole of
+  # +unicode.IsSpace+:
+  #
+  # * <tt>strip</tt> removes a leading or trailing NUL and +strings.TrimSpace+
+  #   does not — <tt>unicode.IsSpace</tt> has no NUL in it. That is the
+  #   ACCEPTING direction wherever a trimmed value is compared against a table:
+  #   <tt>"Comment\\0"</tt> selected a real recording type here and was
+  #   +unknown_recording_type+ there.
+  # * <tt>strip</tt> on a BYTE string removes none of the nineteen multi-byte
+  #   spaces +IsSpace+ carries — U+0085, U+00A0, U+1680, U+2000..U+200A,
+  #   U+2028, U+2029, U+202F, U+205F, U+3000 — which the reference trims. That
+  #   direction merely refuses, but it is still a divergence.
+  #
+  # One byte of the 256 diverges in the first direction and nineteen characters
+  # in the second, so neither <tt>strip</tt> nor a plain ASCII trim is the
+  # reference's function; this walk is.
+  #
+  # It lives here rather than in either caller because both {Basecamp::Mentions}
+  # and the recording-summary composite need the same trim, and a second
+  # hand-written copy of a byte walk is how the two would come apart.
+  module Text
+    # Every member of +unicode.IsSpace+, as its UTF-8 bytes. Built from the
+    # literals rather than a range so the set is readable, and keyed by byte
+    # string so a lookup needs no decoding. No member is a prefix, a suffix or a
+    # substring of another, which is what lets the walk below take the first
+    # width that matches rather than the longest.
+    UTF8_SPACE_BYTES = ([ " ", "\t", "\n", "\v", "\f", "\r", "…", " ", " ",
+                          "
", "
", " ", " ", "　" ] +
+                        (0x2000..0x200A).map { |codepoint| codepoint.chr(Encoding::UTF_8) })
+                       .to_h { |character| [ character.b, true ] }.freeze
+
+    # The widest member, so the walk knows how far to look.
+    MAX_SPACE_WIDTH = UTF8_SPACE_BYTES.keys.map(&:bytesize).max
+
+    module_function
+
+    # The value with leading and trailing +unicode.IsSpace+ runs removed, as
+    # +strings.TrimSpace+ removes them.
+    #
+    # @param value [String]
+    # @return [String] the trimmed bytes
+    def trim_space(value)
+      bytes = value.b
+      first = space_run_end(bytes)
+      bytes.byteslice(first, space_run_start(bytes, first) - first)
+    end
+
+    # The offset just past the leading run of spaces.
+    def space_run_end(bytes)
+      offset = 0
+      while (width = space_width_at(bytes, offset, bytes.bytesize))
+        offset += width
+      end
+      offset
+    end
+
+    # The offset where the trailing run of spaces begins, never below +floor+ —
+    # so a value that is nothing but spaces trims to empty rather than
+    # underflowing past the leading run already consumed.
+    def space_run_start(bytes, floor)
+      offset = bytes.bytesize
+      while (width = space_width_behind(bytes, offset, floor))
+        offset -= width
+      end
+      offset
+    end
+
+    # The width of the space at +offset+, or nil when there is none.
+    def space_width_at(bytes, offset, ceiling)
+      (1..MAX_SPACE_WIDTH).each do |width|
+        next if offset + width > ceiling
+        return width if UTF8_SPACE_BYTES.key?(bytes.byteslice(offset, width))
+      end
+      nil
+    end
+
+    # The width of the space ending at +offset+, or nil when there is none.
+    def space_width_behind(bytes, offset, floor)
+      (1..MAX_SPACE_WIDTH).each do |width|
+        next if offset - width < floor
+        return width if UTF8_SPACE_BYTES.key?(bytes.byteslice(offset - width, width))
+      end
+      nil
+    end
+
+    private_class_method :space_run_end, :space_run_start, :space_width_at, :space_width_behind
+  end
+end

data/lib/basecamp/unresolved_recording_error.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when a chat line was found under none of the Campfires the caller can
+  # currently see in its bucket.
+  #
+  # It is distinct from a failed read — any non-404 answer from a candidate is
+  # raised as itself and stops the loop — and from
+  # {CampfireDiscoveryIncompleteError}, where candidates were left unsearched:
+  # here EVERY candidate answered 404.
+  #
+  # It is NOT distinct from lost visibility. BC3 answers 404 for a Campfire the
+  # caller may not see, too, so "unresolved" means "under no Campfire the caller
+  # can currently see". {#stale_campfire_ids} is what lets a consumer tell the
+  # two apart: candidates the cache held that the refreshed sources no longer
+  # list are Campfires the caller could see when the cache filled and cannot
+  # now. A consumer marks the record blocked and retries on its own schedule.
+  #
+  # +code+ is +not_found+: the recording could not be located. The CLASS is what
+  # keeps it distinct from a read's {NotFoundError} — this error carries no
+  # +http_status+, because no single HTTP answer produced it.
+  class UnresolvedRecordingError < RecordingSummaryError
+    KIND = "recording_unresolved"
+
+    # @return [Integer] the bucket the pointer named
+    attr_reader :bucket_id
+
+    # @return [Integer] the chat line's id
+    attr_reader :recording_id
+
+    # @return [Array<Integer>] the candidates tried, in order; empty when the
+    #   bucket has no visible Campfire at all
+    attr_reader :campfire_ids
+
+    # @return [Array<Integer>] candidates from the cache that the refreshed
+    #   sources no longer list. Set only when {#refreshed?}.
+    attr_reader :stale_campfire_ids
+
+    # @param bucket_id [Integer]
+    # @param recording_id [Integer]
+    # @param campfire_ids [Array<Integer>]
+    # @param refreshed [Boolean] whether the cached discovery sources were
+    #   re-read before concluding. False when every source had been read within
+    #   the last +CampfireIndex::MIN_REFRESH+, so a Campfire created in that
+    #   window was not seen: the conclusion stands on data up to that old, and a
+    #   retry after the floor sees the current sources.
+    # @param stale_campfire_ids [Array<Integer>]
+    def initialize(bucket_id:, recording_id:, campfire_ids:, refreshed:, stale_campfire_ids: [])
+      super(
+        kind: KIND,
+        code: ErrorCode::NOT_FOUND,
+        message: "chat line found under no visible campfire: line #{recording_id} in bucket #{bucket_id} " \
+                 "(tried #{campfire_ids.length} campfires)"
+      )
+      @bucket_id = bucket_id
+      @recording_id = recording_id
+      @campfire_ids = campfire_ids
+      @refreshed = refreshed
+      @stale_campfire_ids = stale_campfire_ids
+    end
+
+    # @return [Boolean] whether the cached discovery sources were re-read before
+    #   concluding
+    def refreshed?
+      @refreshed
+    end
+  end
+end

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.18.0"
+  VERSION = "0.20.0"
   API_VERSION = "2026-09-02"
 end

data/lib/basecamp/webhooks/event.rb

@@ -5,7 +5,7 @@ module Basecamp
     # Structured wrapper around webhook event payloads.
     # Accepts any hash - does not reject unknown fields or event kinds.
     class Event
-      attr_reader :id, :kind, :details, :created_at, :recording, :creator, :copy, :raw
+      attr_reader :id, :kind, :details, :created_at, :recording, :creator, :performed_by, :copy, :raw
 
       def initialize(hash)
         @raw = hash
@@ -15,6 +15,9 @@ module Basecamp
         @created_at = hash["created_at"]
         @recording = hash["recording"] || {}
         @creator = hash["creator"] || {}
+        # The agent that carried out a delegated action (personable_type "Agent",
+        # or "Tombstone" once deleted); nil for actions performed directly.
+        @performed_by = hash["performed_by"]
         @copy = hash["copy"]
       end
 

data/lib/basecamp.rb

@@ -31,6 +31,17 @@ end
 loader.on_load("Basecamp::Services::SchedulesService") do |klass, _abspath|
   klass.prepend(Basecamp::Services::SchedulesExtensions)
 end
+# And for recordings: the generated class owns the status writes, and the
+# hand-written `summarize` projection — one typed read per recording type, plus
+# Campfire discovery for chat lines — is prepended over it.
+loader.on_load("Basecamp::Services::RecordingsService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::RecordingsExtensions)
+end
+# And for comments: the generated class owns `create`, and the mention-expanding
+# `create_with_mentions`/`expand_mentions` surface is prepended over it.
+loader.on_load("Basecamp::Services::CommentsService") do |klass, _abspath|
+  klass.prepend(Basecamp::Services::CommentsExtensions)
+end
 loader.setup
 
 # Load generated types if available
@@ -124,7 +135,7 @@ module Basecamp
     server_message = parse_error_message(body)
     message = server_message || "Request failed"
 
-    case status
+    err = case status
     when 400, 422
       field_errors = parse_field_errors(body)
       message = Security.truncate(compose_validation_message(server_message, field_errors) || "Request failed")
@@ -149,12 +160,19 @@ module Basecamp
       # transient server failure, and no retry can satisfy it.
       LimitExceededError.new(Security.truncate(message), hint: hint)
     when 500
-      ApiError.new("Server error (500)", http_status: 500, retryable: true, hint: hint)
+      ApiError.new("Server error (500)", http_status: 500, retryable: true, hint: hint, retry_after: retry_after)
     when 502, 503, 504
-      ApiError.new("Gateway error (#{status})", http_status: status, retryable: true, hint: hint)
+      ApiError.new("Gateway error (#{status})", http_status: status, retryable: true, hint: hint, retry_after: retry_after)
     else
-      ApiError.from_status(status, server_message, hint: hint)
+      ApiError.from_status(status, server_message, hint: hint, retry_after: retry_after)
     end
+
+    # Every status carries the parsed Retry-After (SPEC §6 "HTTP Status Mapping
+    # Algorithm"), including the arms whose error classes take no such
+    # argument — the same back-fill Http#handle_error applies, so this public
+    # mapper and the private one answer alike.
+    err.instance_variable_set(:@retry_after, retry_after) if retry_after && err.retry_after.nil?
+    err
   end
 
   # Extracts a filename from the last path segment of a URL.

data/scripts/generate-metadata.rb

@@ -3,6 +3,8 @@
 
 # Extracts x-basecamp-* extensions from OpenAPI spec into a runtime-accessible metadata file.
 # This allows the Ruby SDK to read operation metadata at runtime for retry, pagination, etc.
+# It also emits +personIdSites+, the per-operation table of response paths the
+# generated read path decodes a person id at (see {Basecamp::PersonIdSites}).
 #
 # Usage: ruby scripts/ruby/generate-metadata.rb > lib/basecamp/generated/metadata.json
 
@@ -11,7 +13,46 @@ require 'time'
 
 # Extract metadata from OpenAPI spec
 class MetadataExtractor
-  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, its extensions are `x-` prefixed, and every other
+  # field is an operation. A verb list here dropped an operation's metadata in
+  # silence for any method outside the five it knew (#925). Nothing in this
+  # file is verb-specific — metadata is keyed by operationId — so the walk is
+  # total and no verb bound belongs here.
+  NON_OPERATION_FIELDS = %w[summary description servers parameters].freeze
+
+  # Membership is decided above, by exclusion. The shared declaration every
+  # generator reads (spec/generated-verbs.json) is ORDERED, and that order is
+  # reused here to keep metadata.json byte-stable. Order is not membership: a
+  # verb absent from the declaration sorts deterministically to the end by name
+  # and is still extracted, because nothing in this file is verb-specific.
+  # 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__)
+  )
+
+  METHOD_ORDER = 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
 
   def initialize(openapi_path)
     # Read as UTF-8 regardless of process locale (LC_ALL=C would otherwise read
@@ -22,13 +63,9 @@ class MetadataExtractor
   def extract
     operations = {}
 
-    (@openapi['paths'] || {}).each_value do |path_item|
-      METHODS.each do |method|
-        operation = path_item[method]
-        next unless operation
-
+    (@openapi['paths'] || {}).each do |path, path_item|
+      each_operation(path, path_item) do |_method, operation|
         operation_id = operation['operationId']
-        next unless operation_id
 
         metadata = extract_operation_metadata(operation)
         operations[operation_id] = metadata if metadata.any?
@@ -39,10 +76,130 @@ class MetadataExtractor
       '$schema' => 'https://basecamp.com/schemas/sdk-metadata.json',
       'version' => '1.0.0',
       'generated' => Time.now.utc.iso8601,
-      'operations' => operations
+      'operations' => operations,
+      'personIdSites' => person_id_sites
     }
   end
 
+  # The Go-type marker that makes a schema's +id+ a flexible person id. Go
+  # generates +Person.Id+ as +types.FlexibleInt64+ from exactly this extension,
+  # and it is the only field that carries it, so the table is selected on the
+  # marker and never on a key name: +UpcomingSchedulePerson+,
+  # +MyAssignmentAssignee+, +OutOfOfficePerson+ and
+  # +TemplateLibraryConfirmationPerson+ sit under the same key names with a
+  # plain int64 id, where a string is a decode error in the reference.
+  FLEXIBLE_PERSON_ID = 'types.FlexibleInt64'
+
+  # {operationId => [path, ...]} for every operation whose 2xx JSON response
+  # reaches a schema whose +id+ is {FLEXIBLE_PERSON_ID}. A path is its
+  # components joined by "."; "[]" is an array element, and a path that ENDS
+  # in "[]" names an array of people. "$" is the body itself.
+  def person_id_sites
+    sites = {}
+    (@openapi['paths'] || {}).each do |path, path_item|
+      each_operation(path, path_item) do |_method, operation|
+        paths = (operation['responses'] || {}).flat_map do |code, response|
+          next [] unless code.to_s.start_with?('2')
+
+          response = resolve_response(response)
+          (response['content'] || {}).values.flat_map do |media|
+            found = []
+            walk_person_sites(media['schema'] || {}, [], [], found)
+            found
+          end
+        end.uniq.sort
+        sites[operation['operationId']] = paths if paths.any?
+      end
+    end
+    sites.sort.to_h
+  end
+
+  def resolve_response(response)
+    return response unless response['$ref']
+
+    @openapi.dig('components', 'responses', response['$ref'].split('/').last)
+  end
+
+  # Walks $ref, allOf/oneOf/anyOf, items and properties. A schema already on
+  # the $ref stack is a cycle and is not re-entered. additionalProperties has
+  # no runtime path syntax, so a person reached through one fails generation
+  # rather than being silently left out of the table.
+  def walk_person_sites(schema, path, stack, found)
+    if (ref = schema['$ref'])
+      name = ref.split('/').last
+      return if stack.include?(name)
+
+      target = @openapi.dig('components', 'schemas', name)
+      found << (path.empty? ? '$' : path.join('.')) if target.dig('properties', 'id', 'x-go-type') == FLEXIBLE_PERSON_ID
+      walk_person_sites(target, path, stack + [ name ], found)
+      return
+    end
+
+    %w[allOf oneOf anyOf].each do |key|
+      (schema[key] || []).each { |sub| walk_person_sites(sub, path, stack, found) }
+    end
+    walk_person_sites(schema['items'] || {}, path + [ '[]' ], stack, found) if schema['type'] == 'array' || schema['items']
+    (schema['properties'] || {}).each { |key, sub| walk_person_sites(sub, path + [ key ], stack, found) }
+
+    extra = schema['additionalProperties']
+    return unless extra.is_a?(Hash)
+
+    nested = []
+    walk_person_sites(extra, path + [ '{}' ], stack, nested)
+    raise "person id site under additionalProperties at #{nested.first} has no runtime path syntax" if nested.any?
+  end
+
+  # Yields [verb, operation] for every operation in a path item. A field that is
+  # neither a known non-operation field nor a readable operation object stops
+  # the run by name rather than being stepped over.
+  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
+
+    if path_item.key?('$ref')
+      abort "Error: openapi.json path #{path} is a $ref to #{path_item['$ref'].inspect}. " \
+            'This extractor cannot resolve a path-item reference, and skipping it would leave ' \
+            'every operation behind it without runtime metadata.'
+    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| [ METHOD_ORDER.index(f) || METHOD_ORDER.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
+
+      # 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
+
   private
 
   def extract_operation_metadata(operation)
@@ -62,7 +219,6 @@ class MetadataExtractor
     if (pagination = operation['x-basecamp-pagination'])
       metadata['pagination'] = {
         'style' => pagination['style'],
-        'pageParam' => pagination['pageParam'],
         'totalCountHeader' => pagination['totalCountHeader'],
         'maxPageSize' => pagination['maxPageSize']
       }.compact