basecamp-sdk 0.12.0 → 0.14.0

data/lib/basecamp/limit_exceeded_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when an account limit blocks the request (HTTP 507) — file storage
+  # exhausted, or a webhook ceiling reached.
+  #
+  # Never retryable: no amount of backoff frees storage or raises a plan limit.
+  # That is the whole reason this is not an ApiError, which a 507 would
+  # otherwise become through the 5xx catch-all.
+  class LimitExceededError < Error
+    def initialize(message = "Account limit reached", hint: nil, cause: nil)
+      super(
+        code: ErrorCode::LIMIT_EXCEEDED,
+        message: message,
+        hint: hint,
+        http_status: 507,
+        retryable: false,
+        cause: cause
+      )
+    end
+  end
+end

data/lib/basecamp/list_enumerator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # A lazy Enumerator over paginated items that carries pagination metadata.
+  #
+  # Behaves exactly like the plain Enumerator it replaces — each/next/peek/
+  # take/first/lazy all work, and pages beyond the first are fetched only as
+  # iteration demands them — while additionally exposing {#meta}.
+  #
+  # The metadata object is shared with the paginator: meta.total_count is
+  # populated from the eagerly fetched first page, and meta.truncated is
+  # finalized by consuming the enumeration (see {ListMeta}).
+  #
+  # Re-enumerating restarts pagination: the eagerly fetched first page is
+  # served from memory on the first pass only, and later passes refetch
+  # every page for a consistent snapshot, refreshing meta from their own
+  # first-page response — metadata always describes the most recent
+  # traversal.
+  class ListEnumerator < Enumerator
+    # @return [ListMeta] pagination metadata
+    attr_reader :meta
+
+    # @param meta [ListMeta] metadata shared with the producing paginator
+    def initialize(meta, &block)
+      @meta = meta
+      super(&block)
+    end
+  end
+end

data/lib/basecamp/list_meta.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Pagination metadata carried by {ListEnumerator}.
+  #
+  # total_count comes from the X-Total-Count header on the first page (0 when
+  # absent) and is available as soon as the list call returns, because the
+  # first page is fetched eagerly.
+  #
+  # truncated starts false and flips to true when enumeration discovers that
+  # items beyond those yielded were available: items dropped by a max_items
+  # cap, or a next Link left unfetched when the max_items or max_pages cap
+  # stopped pagination. It is final only once enumeration completes; landing
+  # exactly on the final item is not truncation.
+  class ListMeta
+    # @return [Integer] total item count from X-Total-Count (0 if absent)
+    attr_reader :total_count
+
+    # @return [Boolean] whether items beyond those yielded were available
+    attr_reader :truncated
+
+    alias truncated? truncated
+
+    # @param total_count [Integer] value of the X-Total-Count header
+    def initialize(total_count: 0)
+      @total_count = total_count
+      @truncated = false
+    end
+
+    # Records that truncation was discovered during enumeration.
+    # @api private
+    def mark_truncated!
+      @truncated = true
+    end
+
+    # Re-initializes the metadata when a traversal restarts, so it describes
+    # the restarted pass's own snapshot rather than a previous traversal's.
+    # @api private
+    def restart!(total_count:)
+      @total_count = total_count
+      @truncated = false
+    end
+  end
+end

data/lib/basecamp/services/authorization_service.rb

@@ -5,11 +5,20 @@ module Basecamp
     # Service for authorization operations.
     # This is the only service that doesn't require an account context.
     #
+    # The document's shape depends on which issuer served it. Discovery selects a
+    # BC5 issuer whenever one is advertised, and a BC5 issuer serves its *own*
+    # document (+app/views/api/authorizations/show.json.jbuilder+), which is not
+    # Launchpad's: it carries +identity.id+ and nothing else of the identity, no
+    # +product+ or +app_href+ on accounts, an RFC 8707 +resource+ indicator
+    # instead, a top-level +scope+ for BC3-issued tokens, and +expires_at+ as
+    # integer epoch seconds rather than ISO-8601. Only +identity.id+,
+    # +accounts[].id+, +accounts[].name+ and +accounts[].href+ are common to both.
+    #
     # @example Get authorization info
     #   auth = client.authorization.get
-    #   puts "Identity: #{auth["identity"]["email_address"]}"
+    #   puts "Identity: #{auth["identity"]["id"]}"
     #   auth["accounts"].each do |account|
-    #     puts "Account: #{account["name"]} (#{account["id"]})"
+    #     puts "Account: #{account["name"]} (#{account["href"]})"
     #   end
     class AuthorizationService < BaseService
       # Gets authorization information for the current user.

data/lib/basecamp/services/cards_extensions.rb

@@ -2,37 +2,45 @@
 
 module Basecamp
   module Services
-    # Merge-safe +update+ for cards, prepended onto the generated
+    # Tri-state +due_on+ for card updates, prepended onto the generated
     # {CardsService} (see the +on_load+ hook in +basecamp.rb+).
     #
-    # BC3 builds the card's update params as
-    # <tt>{ due_on: nil }.merge(card_params)</tt>
-    # (+kanban/cards_controller.rb+), so *any* update whose body omits +due_on+
-    # erases the card's due date. A sparse PUT — the natural thing to write —
-    # is therefore destructive on the raw endpoint, which remains available as
-    # {#update_verbatim}.
+    # BC3's card controller is presence-aware on the JSON representation
+    # (+kanban/cards_controller.rb+, basecamp/bc3#12521): +card_update_params+
+    # is plain +card_params+, so an update writes exactly the keys the body
+    # carries. An omitted +due_on+ leaves the card's due date UNCHANGED; an
+    # explicit <tt>""</tt> (or +null+) clears it. The
+    # <tt>{ due_on: nil }.merge(card_params)</tt> default survives only for the
+    # HTML/turbo_stream web forms, which post every field on every submit.
     #
-    # +update+ composes the public +get+ and +update_verbatim+ methods, so
-    # hooks observe the two wire operations, not a synthetic composite.
+    # A clear therefore has to be *stated*, never encoded as an omission —
+    # omitting +due_on+ to clear it is a silent no-op. <tt>""</tt> is the
+    # spelling that travels: JSON +null+ cannot reach the wire from here at
+    # all, because +compact_params+ is +kwargs.compact+ and drops nils (SPEC
+    # section 18 body compaction). Rails casts the blank string to nil on the
+    # date column, so <tt>""</tt> is what a clear looks like end to end.
     #
-    # Not atomic: a concurrent due-date change landing between the GET and the
-    # PUT is overwritten with the value this call read. The window is one
-    # round-trip.
+    # There is no read-before-write. An earlier version GET the card and resent
+    # its due date, because the server then nil'd an unmentioned one and a
+    # sparse PUT was destructive. Presence-awareness removed the hazard the
+    # extra round-trip covered, and with it the race the round-trip opened
+    # between the read and the write. Every case is a single PUT.
     module CardsExtensions
-      # Updates a card without disturbing fields the caller did not mention.
+      # Updates a card, addressing only what the caller named.
       #
-      # +due_on+ is tri-state, which is what makes this safe:
+      # +due_on+ is tri-state:
       #
-      # * +nil+ (omitted) — the current due date is fetched and resent
-      # * <tt>""</tt> — the due date is cleared
+      # * +nil+ (unaddressed) — no +due_on+ key is sent; BC3 leaves the current
+      #   due date alone
+      # * <tt>""</tt> — a stated clear, sent as <tt>""</tt>
       # * a date — the due date is set
       #
-      # The extra GET is only paid for in the +nil+ case, the one where the
-      # API would otherwise destroy something.
+      # Every other argument is plain send-when-set: +nil+ leaves the field off
+      # the body, and BC3 leaves the stored value untouched.
       #
-      # Assignees are never resent on the caller's behalf: BC3 filters incoming
-      # IDs through +reachable_people+, so echoing back an id belonging to
-      # someone who has since lost board access would silently unassign them.
+      # This is the same single PUT as {#update_verbatim}, which stays as the
+      # unnormalised path; +update+ differs only in mapping an empty +due_on+ to
+      # the <tt>""</tt> the server reads as a clear.
       #
       # @param card_id [Integer] card id
       # @param title [String, nil] new title (nil = keep current)
@@ -43,13 +51,13 @@ module Basecamp
       def update(card_id:, title: nil, content: nil, due_on: nil, assignee_ids: nil)
         resolved_due_on =
           if due_on.nil?
-            get(card_id: card_id)["due_on"]
-          elsif due_on.to_s.empty?
-            # Clearing is encoded by OMITTING due_on — compact_params strips the
-            # nil below, and BC3 nils an omitted due date. Sending an explicit
-            # null would violate body compaction (SPEC §18), and sending ""
-            # risks a date-format error.
+            # Unaddressed. +compact_params+ drops the nil, so no key is sent and
+            # the presence-aware update never touches the stored date.
             nil
+          elsif due_on.to_s.empty?
+            # A stated clear. "" survives +compact_params+ (it removes only
+            # nils) and reaches the wire as {"due_on": ""}.
+            ""
           else
             due_on
           end

data/lib/basecamp/services/documents_extensions.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Merge-safe +update+ and read-modify-write +edit+ for documents,
+    # prepended onto the generated {DocumentsService} (see the +on_load+ hook
+    # in +basecamp.rb+).
+    #
+    # BC3's +DocumentsController#update+ builds a brand-new +Document+ from
+    # only the permitted params and swaps the recordable wholesale, so
+    # <tt>PUT /documents/{id}</tt> is a full replace: a body that omits
+    # +content+ ERASES it, and one that omits +title+ erases that too — the
+    # document then reads back as <tt>"Untitled"</tt>, because +Document#title+
+    # falls back when blank. Neither attribute is presence-validated, so
+    # *neither omission is a 422*; both are a 200 that quietly clears. What BC3
+    # does require is the wrapping +document+ object, so a body naming neither
+    # field is a 400. The sparse PUT — the natural thing to write — is
+    # therefore destructive on the raw endpoint, which stays available as
+    # {#replace}.
+    #
+    # 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 DocumentsExtensions
+      # A document'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 (<tt>""</tt>) — there is no third state. The writable
+      # set is exactly what BC3 permits: +title+ and +content+.
+      DocumentFields = Struct.new(:title, :content, keyword_init: true)
+
+      # The deliberate-overwrite escape hatch named in every malformed-response
+      # hint raised out of this composite.
+      ESCAPE_HATCH = "replace"
+
+      # Sets the given fields on a document and preserves everything else:
+      # GETs the current document, overlays the explicitly-passed keyword
+      # arguments, and PUTs the full representation back. An omitted (+nil+)
+      # field is untouched, guaranteed; an explicitly-passed <tt>""</tt>
+      # clears.
+      #
+      # Not atomic — see the module docs for the GET→PUT race. Use {#replace}
+      # to overwrite deliberately.
+      #
+      # @param document_id [Integer] document id
+      # @param title [String, nil] new title (nil = keep current, "" clears)
+      # @param content [String, nil] new content (nil = keep current, "" clears)
+      # @return [Hash] the updated document
+      def update(document_id:, title: nil, content: nil)
+        fields = fields_from_document(get(document_id: document_id))
+        fields.title = title unless title.nil?
+        fields.content = content unless content.nil?
+        put_fields(document_id, fields)
+      end
+
+      # Applies a read-modify-write block to a document: GETs the current
+      # document, yields its full writable state ({DocumentFields}), and PUTs
+      # the whole thing back. Clearing a field means setting it empty
+      # (<tt>""</tt>) — 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.documents.edit(document_id: 123) do |doc|
+      #     doc.title = "🚨 #{doc.title}"
+      #     doc.content = "" # clearing = setting empty on a full object
+      #   end
+      #
+      # @param document_id [Integer] document id
+      # @yieldparam fields [DocumentFields] the document's writable state, to mutate in place
+      # @return [Hash] the updated document
+      # @raise [ArgumentError] if no block is given
+      def edit(document_id:)
+        raise ArgumentError, "edit requires a block" unless block_given?
+
+        fields = fields_from_document(get(document_id: document_id))
+        yield fields
+        put_fields(document_id, fields)
+      end
+
+      private
+
+      # Derives the full writable state from a GET response.
+      #
+      # Every value here is resent in the full-replace PUT, so every value is
+      # validated before it is read. A plain <tt>|| ""</tt> would turn +false+
+      # into <tt>""</tt> — erasing the field on a call that never mentioned
+      # it — and pass arrays, hashes, numbers and +true+ straight through to be
+      # written verbatim. Ruby has no typed decoder between the GET and this
+      # read (+get+ returns a raw Hash), so the check is explicit work here
+      # rather than something the layer below already did. See {MergeSafe} and
+      # #576.
+      #
+      # The two writable fields read differently because the spec models them
+      # differently: +title+ is <tt>@required</tt>, so absent or nil is
+      # malformed; +content+ is optional, so absent or nil is a genuinely empty
+      # body.
+      def fields_from_document(document)
+        body = MergeSafe.require_hash(
+          document, record: "Document", operation: "GetDocument", escape: ESCAPE_HATCH
+        )
+        DocumentFields.new(
+          title: MergeSafe.required_writable_string(body, "title", record: "Document", escape: ESCAPE_HATCH),
+          content: MergeSafe.writable_string(body, "content", record: "Document", escape: ESCAPE_HATCH)
+        )
+      end
+
+      # PUTs the full writable state via +replace+. Both fields are always
+      # sent, empties included: the generated layer's +compact_params+ strips
+      # nils, so a cleared field travels as <tt>""</tt> rather than JSON null
+      # (SPEC section 18 body compaction) — and omitting it would hand the
+      # clear back to the server's rebuild instead of stating it.
+      #
+      # +nil+ is normalised to <tt>""</tt> rather than coerced with +to_s+: the
+      # struct starts nil-valued and clearing by assigning nil is idiomatic,
+      # but +to_s+ would silently turn a block's +42+ into <tt>"42"</tt> and
+      # write it — the same corruption {MergeSafe} refuses on the read side.
+      # Validating what the *caller* assigns is the mirror of that rule and is
+      # deliberately out of scope here, exactly as in #576: a value the caller
+      # chose is not a value silently substituted for one they asked to
+      # preserve.
+      def put_fields(document_id, fields)
+        replace(
+          document_id: document_id,
+          title: fields.title.nil? ? "" : fields.title,
+          content: fields.content.nil? ? "" : fields.content
+        )
+      end
+    end
+  end
+end

data/lib/basecamp/services/merge_safe.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Response guards shared by the merge-safe composites.
+    #
+    # A merge-safe +update+/+edit+ GETs a record, reads each writable field,
+    # and PUTs the *full* representation back. The endpoint is full-replace, so
+    # every value read here is written — including one the caller never
+    # mentioned. If the read step coerces or forwards a malformed value instead
+    # of refusing it, that value lands on the record.
+    #
+    # Two failure modes, the same defect wearing different clothes:
+    #
+    # * *erasure* — <tt>|| ""</tt> turns +false+ into <tt>""</tt>, wiping the
+    #   field;
+    # * *corruption* — everything else falsey-in-other-languages (+0+, +[]+,
+    #   <tt>{}</tt>) and every truthy non-string (+42+, +true+,
+    #   <tt>["x"]</tt>) is forwarded verbatim, writing a number, boolean, array
+    #   or hash where a String belongs.
+    #
+    # Ruby's +||+ treats only +nil+ and +false+ as falsy, so it erases in one
+    # case and corrupts in the rest. Testing only for erasure is what let this
+    # class survive five review passes, so both are refused here.
+    #
+    # *The rule: a composite is safe exactly when a typed decoder sits between
+    # the GET and the field read.* Go (+json.Unmarshal+), Swift (+Codable+) and
+    # Kotlin (kotlinx.serialization) get one for free from their models. Ruby
+    # does not — the generated services return a raw Hash, so nothing rejects a
+    # wrong-typed field and the check has to be explicit. That is why these
+    # guards exist in Ruby, Python and TypeScript and nowhere else (#576).
+    #
+    # Todolists carries its own copy of these guards (#574). #544 flattened the
+    # shape those guards read — dropping the envelope-arm rung, not the guards —
+    # but did not unify them here. A generated validating layer (#578) is the
+    # intended end state for all of them.
+    module MergeSafe
+      RESEND_HINT = "The merge-safe update/edit resend this field verbatim, so a coerced or " \
+        "empty value would overwrite the current one. Use %<escape>s to write the record " \
+        "deliberately."
+
+      module_function
+
+      # Renders a value for an error message without ever throwing.
+      #
+      # The guard's own error path must not fail while explaining a failure:
+      # +inspect+ is arbitrary user code and can raise. The class name is always
+      # available; the rendering is a bonus, capped per SPEC section 9 and
+      # dropped if it fails.
+      def describe(value)
+        kind = value.class.to_s
+        begin
+          Security.truncate("#{kind} #{value.inspect}")
+        rescue StandardError
+          kind
+        end
+      end
+
+      # Builds the malformed-response error.
+      #
+      # ApiError, not UsageError: the value arrived in a successful API
+      # response, so nothing the caller passed is at fault. Non-retryable,
+      # because re-requesting cannot repair a malformed body.
+      def malformed(message, hint)
+        ApiError.new(Security.truncate(message), hint: hint, retryable: false)
+      end
+
+      # The response must be a Hash before any field is read.
+      #
+      # One level up from the malformed-field guards: a successful GET can
+      # return a scalar, an Array, or nil. <tt>body["due_on"]</tt> raises
+      # TypeError on an Integer or Array and returns a silent nil substring
+      # match on a String, so a malformed envelope would surface as a native
+      # TypeError instead of the documented statusless +api_error+.
+      def require_hash(body, record:, operation:, escape:)
+        return body if body.is_a?(Hash)
+
+        raise malformed(
+          "#{operation} returned #{describe(body)} where a #{record.downcase} object was expected",
+          "The merge-safe update/edit read this record's fields before rewriting them, so a " \
+            "non-object body cannot be used. Use #{escape} to write the record deliberately."
+        )
+      end
+
+      # Reads a writable string field, refusing to coerce a malformed one.
+      #
+      # A missing key or an explicit +nil+ is genuinely empty — there is nothing
+      # to preserve and <tt>""</tt> is what the server already holds. An actual
+      # String passes verbatim. Anything else is a malformed response and is
+      # refused *before* the PUT, naming the offending field.
+      def writable_string(body, key, record:, escape:)
+        value = body[key]
+
+        if value.nil?
+          ""
+        elsif value.is_a?(String)
+          value
+        else
+          raise malformed(
+            "#{record} field #{key.inspect} is not a string: #{describe(value)}",
+            format(RESEND_HINT, escape: escape)
+          )
+        end
+      end
+
+      # Reads a writable string the record is *required* to carry.
+      #
+      # {writable_string} treats an absent key or an explicit +nil+ as genuinely
+      # empty, which is right for an optional field — <tt>""</tt> is what the
+      # server already holds. It is wrong for a required one. Where the spec
+      # marks a response member <tt>@required</tt> and BC3 can never render it
+      # blank, an absent, nil or blank value in a 2xx body is a *malformed
+      # response*, not an empty field. Coalescing it to <tt>""</tt> and sending
+      # that in the full-replace PUT would blank the real value on a call that
+      # never mentioned it — #576's defect exactly.
+      #
+      # Two records rely on this today and for the same reason: +Document#title+
+      # is <tt>super.presence || "Untitled"</tt> and +Schedule::Entry#summary+ is
+      # <tt>super.presence || "Untitled"</tt>, so neither can come back blank
+      # from a healthy server.
+      #
+      # The wrong-type branch is delegated to {writable_string}, so a required
+      # field and an optional one report a non-string identically.
+      def required_writable_string(body, key, record:, escape:)
+        value = body[key]
+        if value.nil? || (value.is_a?(String) && value.strip.empty?)
+          raise malformed(
+            %(#{record} field "#{key}" is required but the response carried #{describe(value)}),
+            "The merge-safe update/edit resend this field verbatim, so a missing or blank " \
+              "value would blank the current one. Use #{escape} to write the record deliberately."
+          )
+        end
+
+        writable_string(body, key, record: record, escape: escape)
+      end
+
+      # Reads a writable boolean the record is *required* to carry.
+      #
+      # The boolean analogue of {required_writable_string}, and it cannot be
+      # expressed with a truthiness test: the value this guard most needs to
+      # admit is +false+, which every <tt>||</tt> idiom would treat as missing
+      # and replace with a default. +Schedule::Entry#all_day+ is NOT NULL with a
+      # +false+ default in BC3 and every partial emits it, so absent or nil is a
+      # malformed response — and defaulting it to +false+ would silently convert
+      # an all-day event into a midnight-to-midnight timed one on a call that
+      # only changed the summary.
+      #
+      # +0+/+1+ are refused rather than coerced, for the same reason
+      # {writable_string} refuses +42+: JSON has a boolean type and the server
+      # uses it.
+      def required_writable_boolean(body, key, record:, escape:)
+        value = body[key]
+
+        if value.nil?
+          raise malformed(
+            %(#{record} field "#{key}" is required but the response carried #{describe(value)}),
+            "The merge-safe update/edit resend this field verbatim, so a missing value would " \
+              "replace the current one with a default. Use #{escape} to write the record deliberately."
+          )
+        end
+
+        unless [ true, false ].include?(value)
+          raise malformed(
+            "#{record} field #{key.inspect} is not a boolean: #{describe(value)}",
+            format(RESEND_HINT, escape: escape)
+          )
+        end
+
+        value
+      end
+
+      # Reads an *optional* writable boolean, refusing to coerce a malformed one.
+      #
+      # {writable_string}'s boolean sibling, standing in the same relation to
+      # {required_writable_boolean} that +writable_string+ does to
+      # +required_writable_string+: a missing key or an explicit +nil+ is
+      # genuinely "not set" and returns +false+, because that is what the server
+      # already holds.
+      #
+      # +ScheduleEntry#highlighted+ is the case it exists for. The entry partial
+      # emits it unconditionally, but the reduced calendar partial behind
+      # GetUpcomingSchedule does not, and both render through the same schema —
+      # so the member is optional and absence is legitimate rather than
+      # malformed.
+      #
+      # What still cannot be tolerated is the *wrong type*: a <tt>"yes"</tt> or a
+      # +1+ must be refused, not coerced, because a caller who assigns the seeded
+      # value straight back sends whatever it was seeded with. That branch is
+      # delegated to {required_writable_boolean}, so an optional boolean and a
+      # required one report a non-boolean identically.
+      def writable_boolean(body, key, record:, escape:)
+        if body[key].nil?
+          false
+        else
+          required_writable_boolean(body, key, record: record, escape: escape)
+        end
+      end
+
+      # Reads a list of person records and projects it to their Integer ids.
+      #
+      # The analogue of {writable_string} for the id-list fields. The +map+ it
+      # replaces (<tt>(body[key] || []).map { |p| p["id"] }</tt>) has three ways
+      # to go wrong on malformed data: a non-Array has no +map+ (or, for a Hash,
+      # maps over its pairs), a non-Hash element raises TypeError on +[]+, and a
+      # non-Integer +id+ rides through verbatim into the full-replace PUT — the
+      # same corruption as a wrong-typed string, one level down.
+      #
+      # +true+/+false+ are refused explicitly: they are not Integers in Ruby, so
+      # +is_a?(Integer)+ already rejects them, but the message names them as ids
+      # rather than as an unexplained type error.
+      def writable_id_list(body, key, record:, escape:)
+        value = body[key]
+        return [] if value.nil?
+
+        unless value.is_a?(Array)
+          raise malformed(
+            "#{record} field #{key.inspect} is not an array: #{describe(value)}",
+            format(RESEND_HINT, escape: escape)
+          )
+        end
+
+        value.each_with_index.map do |element, index|
+          person_id(element, index, key, record: record, escape: escape)
+        end
+      end
+
+      # Validates one element of an id-list field and returns its id.
+      def person_id(element, index, key, record:, escape:)
+        unless element.is_a?(Hash)
+          raise malformed(
+            "#{record} field #{key.inspect}[#{index}] is not an object: #{describe(element)}",
+            format(RESEND_HINT, escape: escape)
+          )
+        end
+
+        id = element["id"]
+        if id.nil?
+          raise malformed(
+            "#{record} field #{key.inspect}[#{index}] has no \"id\"",
+            format(RESEND_HINT, escape: escape)
+          )
+        end
+
+        unless id.is_a?(Integer)
+          raise malformed(
+            "#{record} field #{key.inspect}[#{index}].id is not an integer: #{describe(id)}",
+            format(RESEND_HINT, escape: escape)
+          )
+        end
+
+        id
+      end
+    end
+  end
+end