atlas_rb 1.17.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a418fc64c12474c618d8bcffbaf01f116f0bb7c80c999f4c3bd4514cf47c879
-  data.tar.gz: ebfa9f0d7e85b884f6f96a16dd59861d01a0d03bbf6a25c94a0e92665add8d2d
+  metadata.gz: 528d764830f8e3a3fdaf376983d4ce3babe6ef0a19f5b1e2fe02fbceb0584bd0
+  data.tar.gz: 2d80d25327e3e43f389a0f71e84c2a880f5bc89905989ff22c16aabee90261c4
 SHA512:
-  metadata.gz: 1e2541b872b918215dd73155ae55fc8d841a7da7fce77f6b984dc82187148dce0a4698ee2b8aaa561b659d1fd253f2077f614cb8d592edaa54a10a343ea8664a
-  data.tar.gz: c0bb9652d3a1cfe08485d6057f23db0e7c493fefe4bfd23be7796e825e1a0bc998b4b02e625c2475e87b247ffc49ffb229469c35adb3b770010bda4cb42c1220
+  metadata.gz: 881ea22bc257423cbbeb748d26bc011371d5d9112be6e72106a60799215d59ce636ef566210a7b5cb93090d075f450f910f15a1040f321910869f358a01bb8cf
+  data.tar.gz: 97203339683115160ec8ef78e375f639d76d38716f2d29f190b2c80b01505f8eda85081e6d487510de0fc65308ae00afba7dbc18e956da16476a2bc3b6bc931b

data/.version

@@ -1 +1 @@
-1.17.0
+1.19.0

data/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 1.19.0
+
+### Added — `Resource.search`, the catalog keyword search
+
+```ruby
+AtlasRb::Resource.search("whaling logbook", type: "Work", page: 1, per_page: 25)
+# => Mash with "results" and "pagination"
+```
+
+Binds `GET /resources/search`, which needs Atlas 0.6.199 or later. It is
+Cerberus's search bar for a caller without Blacklight: the same field weights,
+because both come from the Solr core's search handler, and the same filters for
+the global catalog. It returns the whole envelope, as `descendant_works` does, so
+a caller pages with `pagination.pages`.
+
+Each row is a Solr digest, and `klass` is a name `Resource.class_for` accepts, so
+loading the full resource is `class_for(hit.klass).find(hit.noid)`.
+
+One difference from Cerberus is deliberate. Atlas gates the rows as its own
+`Ability` reads a resource, so an edit group and the depositor count as well as a
+read group. Cerberus's search still checks read groups only, so for staff and
+depositors this can return items that Cerberus's search does not. Every such item
+is one the user can already open.
+
+## 1.18.0
+
+### Changed — the write surface is type-agnostic, and the typed writes are gone
+
+Atlas moved every write that needs no type onto the `/resources/{id}`
+sub-resource that already served its `GET`, so the gem follows. Seven methods
+replace twenty-one:
+
+| Was | Is |
+|---|---|
+| `Work.update` / `Collection.update` / `Community.update` | `Resource.put_mods` |
+| `.metadata` ×3 | `Resource.set_permissions` |
+| `.set_thumbnails` ×3 | `Resource.set_thumbnails` |
+| `.reparent` ×3 | `Resource.reparent` |
+| `.tombstone` ×3 | `Resource.tombstone` |
+| `Admin::{Work,Collection,Community}.restore` | `Admin::Resource.restore` |
+| `Admin::{Work,Collection,Community}.destroy` | `Admin::Resource.destroy` |
+
+`AtlasRb::Admin::Work`, `::Collection` and `::Community` are **removed** —
+purge and restore were all they held.
+
+**Why not keep the typed names as delegators.** One URL now serves every type,
+so `Work.set_permissions(collection_id)` would succeed: the class would name a
+type it could not enforce. A method that cannot keep its own promise is worse
+than no method. Note that the subclasses still *answer* the generic writes,
+because they inherit them from `Resource` — that was already true of the
+generic reads (`history`, `permissions`, `find_many`), and `Resource.find`
+remains the call that reports a type.
+
+**`update` and `metadata` are not carried forward under any name.** Neither
+said which document it wrote: `update` was the MODS upload and `metadata` was
+the ACL. `Resource.mods` and `Resource.permissions` were already taken by the
+reads, so the writes take `put_mods` and `set_permissions` rather than
+overloading a name by arity on the ACL surface.
+
+### Changed — a generic write returns the resource unwrapped
+
+Atlas answers a write with the resource under its type key. A caller of a
+type-agnostic write does not know that key, so the gem unwraps it: `put_mods`,
+`set_permissions`, `set_thumbnails` and `reparent` return the resource itself.
+
+That also settles an inconsistency the typed methods carried — `reparent`
+unwrapped, `update` and `metadata` did not.
+
+`tombstone`, `Admin::Resource.restore` and `Admin::Resource.destroy` still
+return the raw `Faraday::Response`. Atlas answers a refused tombstone with
+`422 has_live_children`, which is a legitimate answer the caller reads rather
+than an error to raise on.
+
+### Changed — `Collection.set_featured` has its own path
+
+`PATCH /collections/{id}` had a **third** payload shape beside MODS and the
+ACL: the showcase `featured` flag. It is Collection-only, so it keeps its type
+and moves to `PATCH /collections/{id}/featured`. The binding signature is
+unchanged.
+
+### Kept per-type, on purpose
+
+`create` (it must name what to create), the Work-only writes (`complete`,
+`mark_incomplete`, `clear_incomplete`, `set_image_derivatives`,
+`set_derivative_permissions`, `set_full_text`, the linked-member and
+association pairs), `Collection.set_featured`, and every FileSet, Blob and
+Compilation write. Each addresses something only its own type has.
+
 ## 1.17.0
 
 ### Fixed — `Resource.find` emitted a type string this namespace cannot resolve

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.17.0)
+    atlas_rb (1.19.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -16,7 +16,7 @@ GEM
     base64 (0.3.0)
     connection_pool (2.5.5)
     diff-lcs (1.6.1)
-    faraday (2.14.3)
+    faraday (2.14.4)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger

data/README.md

@@ -277,18 +277,18 @@ radius and the kind of authentication they need:
 
 | Namespace            | What it does                                                                       | Auth                                                | Friction                              |
 |----------------------|------------------------------------------------------------------------------------|-----------------------------------------------------|---------------------------------------|
-| `AtlasRb::*`         | Regular CRUD (find / list / create / update / tombstone / metadata, etc.)          | Relay-signing (signed assertion, `sub` = acting NUID) | None — these are the daily-use paths. |
-| `AtlasRb::Admin::*`  | Hard delete (`destroy`) and un-tombstone (`restore`) for Work / Collection / Community. | Same as regular — a real operator is acting.        | `destroy` requires `confirm: :i_understand`. |
+| `AtlasRb::*`         | Regular CRUD — typed reads and `create`, plus every type-agnostic write on `Resource`. | Relay-signing (signed assertion, `sub` = acting NUID) | None — these are the daily-use paths. |
+| `AtlasRb::Admin::*`  | Hard delete (`destroy`) and un-tombstone (`restore`), on `Admin::Resource`.         | Same as regular — a real operator is acting.        | `destroy` requires `confirm: :i_understand`. |
 | `AtlasRb::System::*` | System-context provisioning (currently just SSO user find-or-create).              | System token (`Rails.application.credentials.atlas_system_token`) + `User: NUID 000000000`. | The namespace itself is the marker — there is no way to call these as a non-system principal. |
 
 ```ruby
 # Regular daily use — picks up Current.nuid via the configured default:
-AtlasRb::Work.find("w-789")
-AtlasRb::Work.tombstone("w-789")     # withdrawal (reversible)
+AtlasRb::Work.find("w-789")              # typed read
+AtlasRb::Resource.tombstone("w-789")     # withdrawal (reversible), any type
 
 # Operator-only, with a friction marker:
-AtlasRb::Admin::Work.destroy("w-789", confirm: :i_understand)
-AtlasRb::Admin::Work.restore("w-789")
+AtlasRb::Admin::Resource.destroy("w-789", confirm: :i_understand)
+AtlasRb::Admin::Resource.restore("w-789")
 
 # System-only — authenticates as Atlas's :system fixture:
 AtlasRb::System::User.find_or_create(
@@ -531,6 +531,59 @@ The two mutations raise the same way `reparent` does — `LinkedMemberError`
 on a structural `422` (carrying the envelope's `error` code as `#code`) and
 `ForbiddenError` on a `403` — instead of swallowing the envelope.
 
+### Writing without knowing the type
+
+Atlas serves the reads as sub-resources of `/resources/{id}` and serves the
+writes as verbs on those same paths, so a caller holding a NOID and no type can
+write. The whole surface:
+
+| Call | Endpoint |
+|---|---|
+| `Resource.put_mods(id, xml_path, origin:)` | `PUT /resources/{id}/mods` |
+| `Resource.set_permissions(id, acl)` | `PATCH /resources/{id}/permissions` |
+| `Resource.set_thumbnails(id, thumbnail:, thumbnail_2x:, preview:)` | `PATCH /resources/{id}/thumbnails` |
+| `Resource.reparent(id, parent_id)` | `PATCH /resources/{id}/parent` |
+| `Resource.tombstone(id)` | `POST /resources/{id}/tombstone` |
+| `Admin::Resource.restore(id)` | `POST /resources/{id}/restore` |
+| `Admin::Resource.destroy(id, confirm: :i_understand)` | `DELETE /resources/{id}` |
+
+```ruby
+AtlasRb::Resource.put_mods("xsj3xmz", "/tmp/work.xml", origin: "xml_editor")
+AtlasRb::Resource.set_permissions("xsj3xmz", { "read" => ["public"] })
+```
+
+**There are no typed counterparts.** One URL serves every type, so a typed
+write would name a type it could not enforce — `Work.set_permissions` given a
+Collection id would succeed. The subclasses still *answer* these methods,
+because they inherit them from `Resource`, but calling one on a subclass is the
+same call and checks nothing. That was already true of the generic reads;
+`Resource.find` is what reports a type.
+
+**The ACL merges per key.** A key you omit keeps its stored value, and a key
+sent explicitly empty is cleared. So changing one slot no longer means reading
+the whole envelope and writing it back to avoid erasing a field you never meant
+to touch.
+
+```ruby
+# publishes, and leaves the embargo, edit groups and depositor alone
+AtlasRb::Resource.set_permissions(id, { "read" => ["public"] })
+```
+
+**MODS is a PUT because the caller assembles the whole document** — descriptive
+merge logic lives in the client, not in Atlas. A type that holds no MODS
+answers `404`, exactly as the `GET` on that path does; the gem does not
+pre-check, so Atlas stays the one enforcer.
+
+A write returns the resource **unwrapped** from its type key, since the caller
+of a type-agnostic write has no key to index by. `tombstone`, `restore` and
+`destroy` return the raw `Faraday::Response`: Atlas answers a refused tombstone
+with `422 has_live_children`, which is an answer to read rather than an error
+to raise on.
+
+Writes that address something only one type has stay typed — `create`, the
+Work-only lifecycle and derivative writes, `Collection.set_featured`, and the
+FileSet, Blob and Compilation writes.
+
 ### Resolving one id of unknown type (`Resource.find` and `Resource.class_for`)
 
 When a NOID arrives as runtime data and you do not know its type, resolve
@@ -588,6 +641,31 @@ tombstoned resources come back flagged (`"tombstoned" => true`), so index
 by `"noid"` rather than assuming positional correspondence. NOIDs only —
 raw Valkyrie ids are not a supported input.
 
+### Searching the catalog (`Resource.search`)
+
+A keyword search, as Cerberus's search bar runs it, for a caller that has words
+rather than a NOID:
+
+```ruby
+result = AtlasRb::Resource.search("whaling logbook", type: "Work", per_page: 50)
+result.pagination.total                 # => 12
+hit = result.results.first
+hit.title                               # => "Whaling logbook, 1851"
+AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+```
+
+It searches Works, Collections, Communities and People, most relevant first.
+`type` narrows to one of those four; any other value is a `400`, raised as
+`AtlasRb::ResourceError`. Leave out the text to browse everything the user may
+read, newest first.
+
+Each row is a digest read off Solr — `{ "id", "noid", "klass", "title",
+"creators", "year", "thumbnail", "in_progress", "embargoed", "incomplete" }` —
+not the full typed payload. Rows are **gated to the acting user**: public, one of
+their read or edit groups, or a resource they deposited. So the same text can
+return different results for different users. There are no facets and no sort
+option.
+
 ### Missing resources: `nil` on a read, a raise on a write
 
 The two halves of the API answer an absent resource differently, on purpose.
@@ -637,16 +715,16 @@ written to prevent:
 
 ```ruby
 begin
-  AtlasRb::Work.update("doesnotexist", "/tmp/mods.xml")
+  AtlasRb::Resource.put_mods("doesnotexist", "/tmp/mods.xml")
 rescue AtlasRb::NotFoundError => e
   e.status    # => 404
-  e.message   # => "PATCH /works/doesnotexist → 404 (no such resource)"
+  e.message   # => "PUT /resources/doesnotexist/mods → 404 (no such resource)"
 end
 ```
 
-This covers every `create` / `update` / `metadata` / `parent` / `rollback` and
-their siblings on `Work`, `Collection`, `Community`, `Blob`, `FileSet`,
-`Compilation` and `Person`. Any other non-2xx a write gets raises
+This covers every write: `create` and the type-specific writes on `Work`,
+`Collection`, `Blob`, `FileSet`, `Compilation` and `Person`, and the
+type-agnostic ones on `Resource`. Any other non-2xx a write gets raises
 `AtlasRb::ResourceError`, which `NotFoundError` subclasses — so a caller that
 only wants "the write failed" rescues the parent.
 
@@ -668,7 +746,7 @@ Refused writes raise on **every** binding and **every** path:
 
 ```ruby
 begin
-  AtlasRb::Work.update("w-789", metadata)
+  AtlasRb::Resource.set_permissions("w-789", { "read" => ["public"] })
 rescue AtlasRb::ReadOnlyModeError => e
   e.retry_after  # => 900 (seconds, from Atlas's Retry-After header)
   e.message      # => "Atlas is in maintenance mode; writes are refused"

data/lib/atlas_rb/admin/resource.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Admin
+    # Destructive lifecycle operations that need no type, against Atlas's
+    # generic `/resources/{id}` surface.
+    #
+    # The typed {AtlasRb::Admin::Work}, {AtlasRb::Admin::Collection} and
+    # {AtlasRb::Admin::Community} delegate here. See {AtlasRb::Admin} for why
+    # the namespace exists and what `confirm: :i_understand` is for — both
+    # apply unchanged, which is why purge did not move onto
+    # {AtlasRb::Resource} beside the other generic writes.
+    class Resource
+      extend AtlasRb::FaradayHelper
+
+      # Atlas REST endpoint prefix.
+      # @api private
+      ROUTE = "/resources/"
+
+      # Hard-delete a resource — a purge, not a withdrawal.
+      #
+      # Removes the resource's metadata, cascades into its members, and removes
+      # the OCFL objects holding the preserved bytes: every retained revision,
+      # not only the current one. Nothing survives but the audit row, which
+      # records the NOIDs it removed.
+      #
+      # Unrecoverable — prefer {AtlasRb::Resource.tombstone} for the
+      # user-visible withdrawal path, which keeps everything and can be
+      # reversed. Admin-only.
+      #
+      # @param id [String] the resource's NOID.
+      # @param confirm [Symbol] must be `:i_understand`.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+      #   header.
+      # @return [Faraday::Response] the raw delete response.
+      # @raise [ArgumentError] if `confirm:` is missing or not the sentinel
+      #   value. Raised before any request goes out.
+      #
+      # @example
+      #   AtlasRb::Admin::Resource.destroy("xsj3xmz", confirm: :i_understand)
+      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
+        unless confirm == :i_understand
+          raise ArgumentError,
+                "AtlasRb::Admin::Resource.destroy requires confirm: :i_understand"
+        end
+        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
+      end
+
+      # Restore a previously-tombstoned resource.
+      #
+      # Reverses a withdrawal: search and show pages stop returning a withdrawn
+      # stub. No `confirm:` marker — restoring is itself reversible, by
+      # tombstoning again.
+      #
+      # @param id [String] the resource's NOID.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+      #   header.
+      # @return [Faraday::Response] the raw response.
+      #
+      # @example
+      #   AtlasRb::Admin::Resource.restore("xsj3xmz")
+      def self.restore(id, nuid: nil, on_behalf_of: nil)
+        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
+      end
+    end
+  end
+end

data/lib/atlas_rb/admin.rb

@@ -10,10 +10,11 @@ module AtlasRb
   #
   # ## Why a separate namespace
   #
-  # The class itself is the marker: `AtlasRb::Admin::Work.destroy(...)`
-  # is structurally distinct from `AtlasRb::Work.update(...)`. Mass-edits
-  # and code-search across a consumer codebase can quickly find every
-  # destructive call site by grepping `AtlasRb::Admin::`.
+  # The namespace itself is the marker: `AtlasRb::Admin::Resource.destroy(...)`
+  # is structurally distinct from every other write. Mass-edits and code-search
+  # across a consumer codebase can find every destructive call site by grepping
+  # `AtlasRb::Admin::`. That is also why purge did not move onto
+  # {AtlasRb::Resource} beside the other type-agnostic writes.
   #
   # ## `confirm: :i_understand`
   #

data/lib/atlas_rb/collection.rb

@@ -84,7 +84,9 @@ module AtlasRb
       ))["collection"]
       return result if xml_path.to_s.empty?
 
-      update(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
+      # The MODS seed is a second call: create takes the parent and the
+      # provenance slots, and the document goes through the write that owns it.
+      AtlasRb::Resource.put_mods(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
@@ -109,75 +111,11 @@ module AtlasRb
     #   AtlasRb::Collection.set_featured("col-456", true)
     def self.set_featured(id, featured, nuid: nil, on_behalf_of: nil)
       AtlasRb::Mash.new(write_resource(
-        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
+        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/featured')
       ))["collection"]
     end
 
-    # Move a Collection to a different parent (Community or Collection).
-    #
-    # Wraps `PATCH /collections/<id>/parent` with a `parent_id` of the new
-    # parent. Atlas re-parents the Collection and synchronously cascades
-    # the ancestry index over its Works; the structural rules (type, cycle,
-    # tombstone guards) are enforced server-side and surface as a `422`.
-    #
-    # Mirrors {.create}'s "single parent id" shape — same kwarg threading,
-    # the only difference is the verb and that the Collection already exists.
-    #
-    # @param id [String] the Collection ID to move.
-    # @param new_parent_id [String] the destination Community or Collection ID.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the updated `"collection"` object, already unwrapped —
-    #   the same shape {.find} returns, reflecting the new `a_member_of`.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::ReparentError] if Atlas rejects the move on structural
-    #   grounds (HTTP 422 — `cycle`, `invalid_parent_type`, `tombstoned_node`,
-    #   `tombstoned_parent`, `parent_required`, `parent_not_found`). The
-    #   envelope's `error` code is exposed as `#code`.
-    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the move on
-    #   authorization grounds (HTTP 403).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.reparent("col-456", "c-999")
-    def self.reparent(id, new_parent_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')
-      ))["collection"]
-    end
-
-    # Tombstone (withdraw) a Collection.
-    #
-    # The Collection remains in Atlas storage but is marked as withdrawn:
-    # search and show pages return a withdrawn stub for every user. Atlas
-    # rejects the request with `422 has_live_children` if the Collection
-    # still has live (non-tombstoned) Works.
-    #
-    # @param id [String] the Collection ID.
-    # @param nuid [String] the acting user's NUID, stamped on the resource
-    #   as `tombstoned_by` for audit purposes.
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Faraday::Response] the raw response. `200`/`204` on success;
-    #   `422` with `{"code":"has_live_children"}` if the Collection is not empty.
-    #
-    # @example
-    #   AtlasRb::Collection.tombstone("col-456", nuid: "000000002")
-    def self.tombstone(id, nuid: nil, on_behalf_of: nil)
-      connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/tombstone')
-    end
-
     # List the Works in a Collection.
     #
     # The endpoint returns just the noids; resolve each through
@@ -210,104 +148,6 @@ module AtlasRb
       read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children'))
     end
 
-    # Replace a Collection's metadata by uploading a MODS XML document.
-    #
-    # @param id [String] the Collection ID.
-    # @param xml_path [String] path to a MODS XML file on disk.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @param origin [String, nil] free-text tag naming the surface that made this
-    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
-    #   on the audit event; omit it and the event carries no origin.
-    # @return [Hash] the parsed JSON response from the patch.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml")
-    #
-    # @example Recording which editing surface made the change
-    #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml", origin: "xml_editor")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
-      AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
-      ))
-    end
-
-    # Patch individual descriptive-metadata fields without uploading a
-    # full MODS document.
-    #
-    # Scoped to user-authored descriptive metadata only. Programmatic
-    # writes of machine-set Delegate URIs (thumbnails) have their own
-    # purpose-specific endpoint — see {.set_thumbnails}.
-    #
-    # @param id [String] the Collection ID.
-    # @param values [Hash] field-level metadata updates.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the parsed JSON response.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.metadata("col-456", title: "Renamed Collection")
-    def self.metadata(id, values, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
-      ))
-    end
-
-    # Attach the three thumbnail/preview Delegate URIs to a Collection.
-    #
-    # Collection-level mirror of {Work.set_thumbnails}. Atlas dispatches
-    # each non-blank URI to its matching Delegate role
-    # (`thumbnail_image` / `thumbnail_image_2x` / `preview_image`) via
-    # `DelegateUpdater`. Missing keys are left untouched.
-    #
-    # @param id [String] the Collection ID.
-    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
-    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
-    # @param preview [String, nil] IIIF URI for the ~500w preview image.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @return [AtlasRb::Mash] the parsed JSON response.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.set_thumbnails(
-    #     "col-456",
-    #     thumbnail:    "https://iiif.example.edu/iiif/3/c.jp2/full/!85,85/0/default.jpg",
-    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/c.jp2/full/!170,170/0/default.jpg",
-    #     preview:      "https://iiif.example.edu/iiif/3/c.jp2/full/500,/0/default.jpg"
-    #   )
-    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil, on_behalf_of: nil)
-      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
-      AtlasRb::Mash.new(write_resource(
-        connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
-      ))
-    end
-
     # Fetch the Collection's MODS representation in the requested format.
     #
     # @param id [String] the Collection ID.