basecamp-sdk 0.12.0 → 0.14.0

data/lib/basecamp/services/schedules_extensions.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Merge-safe +update_entry+ and read-modify-write +edit_entry+ for schedule
+    # entries, prepended onto the generated {SchedulesService} (see the
+    # +on_load+ hook in +basecamp.rb+).
+    #
+    # BC3's +Schedules::EntriesController#update+ rebuilds the recordable from
+    # the submitted params, so <tt>PUT /schedule_entries/{id}</tt> is a full
+    # replace: a body that omits +description+ ERASES it, and one that omits
+    # +summary+ erases that too — the entry then reads back as
+    # <tt>"Untitled"</tt>, because +Schedule::Entry#summary+ is
+    # <tt>super.presence || "Untitled"</tt>. The sparse PUT — the natural thing
+    # to write — is therefore destructive on the raw endpoint, which stays
+    # available as +replace_entry+.
+    #
+    # == Two classes of writable field
+    #
+    # Unlike documents and todolists, this record's writable set does not have
+    # one uniform rule. It splits in two:
+    #
+    # [full state] +summary+, +starts_at+, +ends_at+, +description+, +all_day+.
+    #              Always resent, empties included: <tt>""</tt> is how a clear is
+    #              expressed on a full-replace endpoint, never JSON null and
+    #              never an omission.
+    # [addressed-only] +participant_ids+, +url+, +highlighted+, +notify+. Sent
+    #                  *only* when the caller addressed them, and never seeded
+    #                  onto the wire from the read-back.
+    #
+    # The first three of the addressed-only set are the operation's
+    # +preservedOnOmission+ carve-out: BC3 seeds them from the existing
+    # recordable when the request does not address them, so resending them is
+    # redundant at best and wrong if the GET raced a concurrent change. Echoing
+    # the response's +url+ would be worse than redundant — that key is the
+    # entry's own Basecamp API URL, written by +recordings/_recording+ before
+    # the entry partial renders, so BC3 emits the join link under the
+    # non-colliding +join_url+. Writing +url+ back would store the API URL as
+    # the join link. +notify+ is addressed-only for a different reason: it is a
+    # directive, not state — sending it makes BC3 recompute a drafted entry's
+    # subscriber list — and the read-back carries nothing to seed it from.
+    #
+    # An explicitly *empty* value in that second class is an address, not an
+    # absence: <tt>participant_ids: []</tt> clears participants,
+    # <tt>url: ""</tt> clears the join link, <tt>highlighted: false</tt> removes
+    # the highlight. All three survive body compaction, which strips only nil
+    # (SPEC section 18).
+    #
+    # == Recurring entries
+    #
+    # +ensure_non_recurring_event+ 302-redirects both +show+ and +update+ for a
+    # recurring entry, so this route serves non-recurring entries only. The SDK
+    # does not follow redirects on a PUT, and the GET's redirect lands on a body
+    # this composite refuses rather than reads. Recurrence itself
+    # (+recurrence_schedule+, +recurs_until+, +time_zone_name+) is unmodelled
+    # here and stays unmodelled: BC3 forces all three to nil for a non-recurring
+    # entry.
+    #
+    # Both methods compose the public +get_entry+ and +replace_entry+, so hooks
+    # observe the two wire operations (+get_entry+ then +replace_entry+), 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_entry+ to overwrite deliberately.
+    module SchedulesExtensions
+      # The deliberate-overwrite escape hatch named in every malformed-response
+      # hint raised out of this composite.
+      ESCAPE_HATCH = "replace_entry"
+
+      # The record name interpolated into {MergeSafe}'s messages.
+      RECORD = "Schedule entry"
+
+      # The writable members BC3 preserves when the request does not address
+      # them, plus +notify+, which is a directive rather than state. Sent only
+      # on an explicit address; never seeded from the read-back.
+      CARVE_OUTS = %i[participant_ids url highlighted notify].freeze
+
+      # How each writable member spells "cleared" on the wire.
+      #
+      # +compact_params+ strips nil (SPEC section 18), so a nil that reached the
+      # request would silently become an omission — an address turned back into
+      # an absence, which on a full-replace endpoint is exactly the defect this
+      # composite exists to prevent. Every member whose type has an empty value
+      # is normalised to it here. The three booleans (+all_day+, +highlighted+,
+      # +notify+) have none: a boolean is true or false, so a nil assigned to
+      # one is caller error and is refused rather than dropped.
+      CLEARED = {
+        summary: "",
+        starts_at: "",
+        ends_at: "",
+        description: "",
+        participant_ids: [].freeze,
+        url: ""
+      }.freeze
+
+      # A schedule entry's writable state, yielded to the {#edit_entry} block.
+      #
+      # The full-state members are plain accessors: they are resent whether or
+      # not the block touches them, so nothing has to be recorded. The
+      # carve-outs are readable — seeded from the read-back so a block can
+      # inspect the current join link, highlight and participants before
+      # deciding — but each writer *records the address*, and only an addressed
+      # carve-out reaches the wire.
+      #
+      # Dirty tracking is by setter invocation, deliberately, and not by
+      # comparing the block's result against the read-back: assigning a
+      # carve-out the value the GET just returned is an address like any other.
+      # A diff would drop it, and the server would then hold whatever a
+      # concurrent writer left there instead of the value the caller stated.
+      class ScheduleEntryFields
+        attr_accessor :summary, :starts_at, :ends_at, :description, :all_day
+        attr_reader :participant_ids, :url, :highlighted, :notify
+
+        def initialize(summary:, starts_at:, ends_at:, description:, all_day:,
+                       participant_ids:, url:, highlighted:)
+          @summary = summary
+          @starts_at = starts_at
+          @ends_at = ends_at
+          @description = description
+          @all_day = all_day
+          @participant_ids = participant_ids
+          @url = url
+          @highlighted = highlighted
+          # Nothing in the response seeds a directive.
+          @notify = nil
+          @addressed = {}
+        end
+
+        def participant_ids=(value)
+          @addressed[:participant_ids] = true
+          @participant_ids = value
+        end
+
+        def url=(value)
+          @addressed[:url] = true
+          @url = value
+        end
+
+        def highlighted=(value)
+          @addressed[:highlighted] = true
+          @highlighted = value
+        end
+
+        def notify=(value)
+          @addressed[:notify] = true
+          @notify = value
+        end
+
+        # Whether the caller addressed this carve-out, by assignment.
+        def addressed?(name)
+          @addressed.key?(name)
+        end
+      end
+
+      # Sets the given fields on a schedule entry and preserves everything else:
+      # GETs the current entry, overlays the explicitly-passed keyword
+      # arguments, and PUTs the full representation back.
+      #
+      # An omitted (+nil+) argument is untouched, guaranteed. For the full-state
+      # fields that means the read-back value is resent; for the addressed-only
+      # fields it means the key never reaches the wire, leaving BC3 to seed it
+      # from the record it already holds. An explicitly-passed <tt>""</tt>,
+      # <tt>[]</tt> or +false+ is an address and is sent.
+      #
+      # +nil+ is an unambiguous "not addressed" for every one of these
+      # arguments: none of them has a JSON null wire spelling — a clear is
+      # <tt>""</tt>, <tt>[]</tt> or +false+ — and +compact_params+ strips nil
+      # before serialization anyway, so no sentinel is needed to tell "passed
+      # nil" from "not passed".
+      #
+      # Not atomic — see the module docs for the GET→PUT race, and for the
+      # recurring-entry redirect. Use +replace_entry+ to overwrite deliberately.
+      #
+      # @param entry_id [Integer] entry id
+      # @param summary [String, nil] new summary (nil = keep current)
+      # @param starts_at [String, nil] new start, a date or timestamp (nil = keep current)
+      # @param ends_at [String, nil] new end, a date or timestamp (nil = keep current)
+      # @param description [String, nil] new description (nil = keep current, "" clears)
+      # @param all_day [Boolean, nil] new all-day flag (nil = keep current)
+      # @param participant_ids [Array<Integer>, nil] replaces participants (nil = leave to BC3, [] clears)
+      # @param url [String, nil] new join link (nil = leave to BC3, "" clears)
+      # @param highlighted [Boolean, nil] new highlight (nil = leave to BC3, false removes)
+      # @param notify [Boolean, nil] notify participants (nil = do not address)
+      # @return [Hash] the updated schedule entry
+      def update_entry(entry_id:, summary: nil, starts_at: nil, ends_at: nil, description: nil,
+                       all_day: nil, participant_ids: nil, url: nil, highlighted: nil, notify: nil)
+        # Delegating to edit_entry is not a shortcut: it makes "the caller
+        # addressed this" one rule with one implementation. A non-nil argument
+        # invokes the same writer a block would, so the carve-outs are recorded
+        # by exactly the mechanism edit_entry documents.
+        edit_entry(entry_id: entry_id) do |entry|
+          entry.summary = summary unless summary.nil?
+          entry.starts_at = starts_at unless starts_at.nil?
+          entry.ends_at = ends_at unless ends_at.nil?
+          entry.description = description unless description.nil?
+          entry.all_day = all_day unless all_day.nil?
+          entry.participant_ids = participant_ids unless participant_ids.nil?
+          entry.url = url unless url.nil?
+          entry.highlighted = highlighted unless highlighted.nil?
+          entry.notify = notify unless notify.nil?
+        end
+      end
+
+      # Applies a read-modify-write block to a schedule entry: GETs the current
+      # entry, yields its writable state ({ScheduleEntryFields}), and PUTs it
+      # back. The full-state fields are resent whether or not the block touches
+      # them; a carve-out is sent only if the block assigns it, even when it
+      # assigns the value the read already returned. If the block raises, the
+      # edit aborts and nothing is written.
+      #
+      # Not atomic — see the module docs for the GET→PUT race, and for the
+      # recurring-entry redirect.
+      #
+      # @example Clear the description, leave the join link and highlight alone
+      #   account.schedules.edit_entry(entry_id: 123) do |entry|
+      #     entry.summary = "🚨 #{entry.summary}"
+      #     entry.description = "" # clearing = setting empty on a full object
+      #   end
+      #
+      # @example Address a carve-out
+      #   account.schedules.edit_entry(entry_id: 123) do |entry|
+      #     entry.url = "" if entry.url.start_with?("https://meet.example.com/")
+      #   end
+      #
+      # @param entry_id [Integer] entry id
+      # @yieldparam fields [ScheduleEntryFields] the entry's writable state, to mutate in place
+      # @return [Hash] the updated schedule entry
+      # @raise [ArgumentError] if no block is given
+      def edit_entry(entry_id:)
+        raise ArgumentError, "edit_entry requires a block" unless block_given?
+
+        fields = fields_from_entry(get_entry(entry_id: entry_id))
+        yield fields
+        put_entry_fields(entry_id, fields)
+      end
+
+      private
+
+      # Derives the writable state from a GET response.
+      #
+      # Every full-state value here is resent in the full-replace PUT, so every
+      # one is validated before it is read. Ruby has no typed decoder between
+      # the GET and this read (+get_entry+ returns a raw Hash), so the check is
+      # explicit work here rather than something the layer below already did.
+      # See {MergeSafe} and #576.
+      #
+      # The guards differ per field because the spec models the fields
+      # differently:
+      #
+      # * +summary+, +starts_at+ and +ends_at+ are <tt>@required</tt> on the
+      #   response and BC3 can never render them absent, null or blank —
+      #   +Schedule::Entry#summary+ falls back to <tt>"Untitled"</tt>, and
+      #   +starts_at+/+ends_at+ are NOT NULL columns every partial emits — so
+      #   any of those shapes is a malformed response, not an empty value.
+      # * +starts_at+/+ends_at+ are read as strings and round-tripped verbatim,
+      #   never parsed: the wire value is a bare date (<tt>"2026-06-05"</tt>)
+      #   for an all-day entry and a timestamp otherwise, and reformatting it
+      #   would rewrite a value the caller never mentioned.
+      # * +all_day+ is <tt>@required</tt> and NOT NULL DEFAULT false. It cannot
+      #   be read with a truthiness test, because +false+ is the value the read
+      #   most needs to admit; and defaulting a missing one to +false+ would
+      #   silently convert an all-day event into a midnight-to-midnight timed
+      #   one on a call that only changed the summary.
+      # * +description+ is optional and nullable — the rich-text partial always
+      #   sets the key but the value may be null — so absent or null is
+      #   genuinely empty.
+      #
+      # The carve-outs are seeded for *reading*, so a block can inspect the
+      # current join link, highlight and participants before deciding; seeding
+      # alone puts nothing on the wire. They are guarded all the same, because
+      # "reaches the wire only when addressed" is not "never reaches the wire":
+      # dirty tracking is by setter invocation, so <tt>entry.url = entry.url</tt>
+      # is an address like any other and sends whatever the seed held — and a
+      # block that merely inspects a corrupt seed decides on garbage. +url+ is
+      # seeded from +join_url+, never from +url+ (see the module docs).
+      # +highlighted+ takes the *optional* boolean guard: the member is absent
+      # from the reduced calendar partial +GetUpcomingSchedule+ renders, so a
+      # missing one is genuinely "not highlighted" rather than malformed — but a
+      # <tt>"yes"</tt> or a +1+ is refused, not coerced.
+      def fields_from_entry(entry)
+        body = MergeSafe.require_hash(
+          entry, record: RECORD, operation: "GetScheduleEntry", escape: ESCAPE_HATCH
+        )
+        ScheduleEntryFields.new(
+          summary: required_string(body, "summary"),
+          starts_at: required_string(body, "starts_at"),
+          ends_at: required_string(body, "ends_at"),
+          description: MergeSafe.writable_string(body, "description", record: RECORD, escape: ESCAPE_HATCH),
+          all_day: MergeSafe.required_writable_boolean(body, "all_day", record: RECORD, escape: ESCAPE_HATCH),
+          participant_ids: MergeSafe.writable_id_list(body, "participants", record: RECORD, escape: ESCAPE_HATCH),
+          url: MergeSafe.writable_string(body, "join_url", record: RECORD, escape: ESCAPE_HATCH),
+          highlighted: MergeSafe.writable_boolean(body, "highlighted", record: RECORD, escape: ESCAPE_HATCH)
+        )
+      end
+
+      def required_string(body, key)
+        MergeSafe.required_writable_string(body, key, record: RECORD, escape: ESCAPE_HATCH)
+      end
+
+      # PUTs the writable state via +replace_entry+.
+      #
+      # The five full-state members are always sent, empties included: a cleared
+      # field travels as <tt>""</tt> rather than JSON null, and omitting it
+      # would hand the clear back to the server's rebuild instead of stating it.
+      # The carve-outs are splatted in only when addressed, so an untouched one
+      # leaves no key at all and BC3 seeds it from the record it holds.
+      #
+      # As in Documents (#576), validating the *type* of what the caller assigns
+      # is out of scope: a value the caller chose is not a value silently
+      # substituted for one they asked to preserve. Normalising nil is not that
+      # check — it is the addressedness contract, since a nil would be stripped
+      # by +compact_params+ and turn a stated clear into an omission.
+      def put_entry_fields(entry_id, fields)
+        replace_entry(
+          entry_id: entry_id,
+          summary: caller_value(fields.summary, :summary),
+          starts_at: caller_value(fields.starts_at, :starts_at),
+          ends_at: caller_value(fields.ends_at, :ends_at),
+          description: caller_value(fields.description, :description),
+          all_day: caller_value(fields.all_day, :all_day),
+          **addressed_carve_outs(fields)
+        )
+      end
+
+      # The addressed carve-outs, as replace_entry keyword arguments. An
+      # unaddressed one is absent from the Hash, so it is absent from the body.
+      def addressed_carve_outs(fields)
+        CARVE_OUTS.select { |name| fields.addressed?(name) } \
+                  .to_h { |name| [ name, caller_value(fields.public_send(name), name) ] }
+      end
+
+      # Normalises a nil the caller left or assigned into that member's empty
+      # spelling, and refuses it where the member has none.
+      def caller_value(value, key)
+        if value.nil?
+          CLEARED.fetch(key) { raise nil_boolean(key) }
+        else
+          value
+        end
+      end
+
+      def nil_boolean(key)
+        UsageError.new(
+          "schedule entry #{key} must be true or false, not nil",
+          hint: "#{key} is a boolean with no empty value, and body compaction drops nil — " \
+            "sending it would omit the field rather than state it, letting the server " \
+            "decide. Assign true or false, or leave the member alone."
+        )
+      end
+    end
+  end
+end

data/lib/basecamp/services/todolists_extensions.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Merge-safe +update+ and read-modify-write +edit+ for todolists (and
+    # todolist groups), prepended onto the generated {TodolistsService} (see
+    # the +on_load+ hook in +basecamp.rb+).
+    #
+    # BC3's +TodolistsController#update+ rebuilds the recordable from only the
+    # permitted params, so <tt>PUT /todolists/{id}</tt> is a full replace:
+    # a body that omits +description+ ERASES it. 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 TodolistsExtensions
+      # A todolist'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: +name+ and +description+.
+      TodolistFields = Struct.new(:name, :description, keyword_init: true)
+
+      # Sets the given fields on a todolist and preserves everything else:
+      # GETs the current todolist, 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, or {#edit} to clear fields.
+      #
+      # @param id [Integer] todolist id
+      # @param name [String, nil] new name (nil = keep current)
+      # @param description [String, nil] new description (nil = keep current, "" clears)
+      # @return [Hash] the updated todolist
+      # @raise [Basecamp::UsageError] if the resulting name would be empty
+      def update(id:, name: nil, description: nil)
+        fields = fields_from_todolist(get(id: id))
+        fields.name = name unless name.nil?
+        fields.description = description unless description.nil?
+        put_fields(id, fields)
+      end
+
+      # Applies a read-modify-write block to a todolist: GETs the current
+      # todolist, yields its full writable state ({TodolistFields}), 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.todolists.edit(id: 123) do |list|
+      #     list.name = "🚨 #{list.name}"
+      #     list.description = "" # clearing = setting empty on a full object
+      #   end
+      #
+      # @param id [Integer] todolist id
+      # @yieldparam fields [TodolistFields] the todolist's writable state, to mutate in place
+      # @return [Hash] the updated todolist
+      # @raise [ArgumentError] if no block is given
+      # @raise [Basecamp::UsageError] if the block leaves the name empty
+      def edit(id:)
+        raise ArgumentError, "edit requires a block" unless block_given?
+
+        fields = fields_from_todolist(get(id: id))
+        yield fields
+        put_fields(id, fields)
+      end
+
+      private
+
+      # Derives the full writable state from a GET response.
+      #
+      # BC3 answers this route with the recordable's flat JSON, and since #544
+      # the Smithy model says the same: one flat +Todolist+ structure, no
+      # +todolist+/+group+ envelope and no union. A group is a Todolist —
+      # +todolists/groups/{index,show}.json.jbuilder+ render
+      # +todolists/_todolist.json.jbuilder+ — so both projections arrive here
+      # with +name+ and +description+ at the top level and are read the same
+      # way. Nothing branches on the +type+ string; the structural
+      # discriminator (+groups_url+ for a list, +group_position_url+ for a
+      # group) is not writable state and is none of this method's business.
+      #
+      # The former arm lookup is gone with the union that motivated it: an
+      # unmodelled +todolist+/+group+ wrapper is now a malformed response, and
+      # unwrapping one would write the wrapper's contents over the record.
+      def fields_from_todolist(todolist)
+        body = require_hash(todolist)
+        TodolistFields.new(
+          name: writable_string(body, "name", non_empty: true),
+          description: writable_string(body, "description")
+        )
+      end
+
+      # 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
+
+      # The response must be a Hash before any field is read.
+      #
+      # Level 1 of the wire-to-written-value path, one level up from the
+      # malformed-field guards. Since #544 flattened the shape the path is
+      # object -> scalar and has exactly two levels — the body and each writable
+      # field — where it used to have three. Two, not none: a flat wire shape
+      # says what the API returns, not that anything validates it. The generated
+      # +get+ returns <tt>http_get(...).json</tt>, a raw Hash with no decoder
+      # behind it, so a successful GET can still hand this method a scalar, an
+      # Array or nil.
+      #
+      # +body["name"]+ raises TypeError on an Integer or Array, and on a String
+      # it does not raise at all: it is a substring search. A body of
+      # <tt>"no name here"</tt> answers <tt>"name"</tt> for +name+ and +nil+ for
+      # +description+, so without this guard the composite would PUT the literal
+      # string "name" over the record's real name and clear its description —
+      # failing silently, which is why that defect outlived eight review passes
+      # on #574. A String has no interior, so there is no third level.
+      def require_hash(body)
+        unless body.is_a?(Hash)
+          raise ApiError.new(
+            Security.truncate("GetTodolistOrGroup returned #{describe(body)} where a todolist object was expected"),
+            hint: "The merge-safe update/edit read this record's fields before rewriting them, " \
+              "so a non-object body cannot be used. Use replace to write the record deliberately."
+          )
+        end
+
+        body
+      end
+
+      # Reads a writable string field, refusing to coerce a malformed one.
+      #
+      # *Classification is by origin, not by value.* The same empty string is a
+      # caller error when the caller passed it and malformed response data when
+      # it came off the wire, so each provenance is checked where it is
+      # unambiguous: this read step owns the response, and +put_fields+ owns the
+      # caller. That is why an empty +name+ here raises ApiError while an empty
+      # +name+ the caller supplied raises UsageError — same value, different
+      # origin, different fault.
+      #
+      # *Presence and non-emptiness are two different claims, and only one of
+      # them is per-field.* Since #544 +name+ and +description+ are both
+      # +@required+ and never null on this shape — +format_api_content+ funnels
+      # a blank rich text through +call_pipeline+, which returns <tt>""</tt>
+      # rather than nil — so for BOTH a missing key and an explicit +nil+ are
+      # malformed and are refused here, before any PUT. Reading either as
+      # <tt>""</tt> would put that <tt>""</tt> in the full-replace body and
+      # erase the record's real value on a call that never mentioned the field.
+      #
+      # +non_empty+ is the OTHER claim and holds for +name+ alone: BC3
+      # presence-validates the attribute, so no real todolist carries an empty
+      # one and <tt>""</tt> off the wire is malformed too. +description+ has no
+      # such validation — a description-less list carries <tt>""</tt>, which is
+      # the ordinary case, and the canonical group fixture ships one — so an
+      # empty description is a real value, preserved and resent verbatim.
+      # Conflating the two flags would refuse every description-less record.
+      #
+      # A wrong type is malformed either way and must NOT be coerced: a plain
+      # <tt>|| ""</tt> turns +false+ into <tt>""</tt> and passes arrays, hashes
+      # and numbers straight through. This endpoint is full-replace, so either
+      # outcome is written back over the real value.
+      #
+      # 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.
+      def writable_string(body, key, non_empty: false)
+        raise_missing_field(key) unless body.key?(key)
+
+        value = body[key]
+
+        if value.nil?
+          raise_null_field(key)
+        elsif !value.is_a?(String)
+          raise ApiError.new(
+            Security.truncate("Todolist field #{key.inspect} is not a string: #{describe(value)}"),
+            hint: "The merge-safe update/edit resend this field verbatim, so a coerced or " \
+              "empty value would overwrite the current one. Use replace to write the record " \
+              "deliberately."
+          )
+        elsif non_empty && value.empty?
+          raise ApiError.new(
+            "Todolist field #{key.inspect} is empty in the response",
+            hint: "#{key} is presence-validated server-side, so an empty one is a malformed " \
+              "response. The caller did not ask to clear it."
+          )
+        else
+          value
+        end
+      end
+
+      def raise_missing_field(key)
+        raise ApiError.new(
+          "Todolist field #{key.inspect} is missing from the response",
+          hint: "#{key} is required on every todolist, so a body without one is a malformed " \
+            "response, not an empty value to preserve. The merge-safe update/edit PUT the full " \
+            "writable state back, so reading it as empty would erase the real value."
+        )
+      end
+
+      def raise_null_field(key)
+        raise ApiError.new(
+          "Todolist field #{key.inspect} is null in the response",
+          hint: "#{key} is required and never null, so a null one is a malformed response, not " \
+            "an empty value to preserve. The merge-safe update/edit PUT the full writable state " \
+            "back, so reading it as empty would erase the real value."
+        )
+      end
+
+      # PUTs the full writable state via +replace+. Both fields are always
+      # sent, description included when empty: the generated layer's
+      # +compact_params+ strips nils, so a cleared description 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.
+      #
+      # An empty name is refused rather than sent: BC3 presence-validates it,
+      # so a blank name is a 422 and never a preserve.
+      def put_fields(id, fields)
+        name = caller_string(fields.name, "name")
+        description = caller_string(fields.description, "description")
+
+        if name.empty?
+          raise UsageError, "name must be present; a full write has no nil state and BC3 rejects a blank name with 422"
+        end
+
+        replace(id: id, name: name, description: description)
+      end
+
+      # Validates a caller-supplied writable value, the mirror of the read step.
+      #
+      # +writable_string+ owns *response* provenance; this owns *caller*
+      # provenance, and the two are one rule seen from opposite ends. +edit+
+      # yields a mutable view of the full writable state and Ruby enforces
+      # nothing about what comes back — a block assigning +42+ or +[]+ would
+      # otherwise walk straight into the full-replace PUT and write it. That is
+      # caller misuse, hence UsageError, where the same wrong type arriving from
+      # the server is an ApiError. +nil+ is accepted as the empty string: the
+      # struct starts nil-valued and clearing by assigning nil is idiomatic.
+      def caller_string(value, key)
+        if value.nil?
+          ""
+        elsif value.is_a?(String)
+          value
+        else
+          raise UsageError.new(
+            Security.truncate("todolist #{key} must be a String, got #{describe(value)}"),
+            hint: "The full writable state is PUT back verbatim, so a non-String would be " \
+              "written to the record. Assign a String; use \"\" to clear."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/basecamp/services/todos_extensions.rb

@@ -26,6 +26,10 @@ module Basecamp
         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 todo and preserves everything else:
       # GETs the current todo, overlays the explicitly-passed keyword
       # arguments, and PUTs the full representation back. An omitted
@@ -85,14 +89,26 @@ module Basecamp
       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. The plain <tt>|| ""</tt> this replaced
+      # turned +false+ into <tt>""</tt> — erasing the field on a call that never
+      # mentioned it — and passed 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.
       def fields_from_todo(todo)
+        body = MergeSafe.require_hash(todo, record: "Todo", operation: "GetTodo", escape: ESCAPE_HATCH)
         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"] || "",
+          content: MergeSafe.writable_string(body, "content", record: "Todo", escape: ESCAPE_HATCH),
+          description: MergeSafe.writable_string(body, "description", record: "Todo", escape: ESCAPE_HATCH),
+          assignee_ids: MergeSafe.writable_id_list(body, "assignees", record: "Todo", escape: ESCAPE_HATCH),
+          completion_subscriber_ids: MergeSafe.writable_id_list(
+            body, "completion_subscribers", record: "Todo", escape: ESCAPE_HATCH
+          ),
+          due_on: MergeSafe.writable_string(body, "due_on", record: "Todo", escape: ESCAPE_HATCH),
+          starts_on: MergeSafe.writable_string(body, "starts_on", record: "Todo", escape: ESCAPE_HATCH),
           notify: false
         )
       end