atlas_rb 1.9.2 → 1.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 235448544b8690ecf3a941cc259ab5f049442f609766666297c571e336ac3eae
-  data.tar.gz: d3dc2e59aab57397176e959eec0a28478d5a15dbc0ebe2be459c775a42ec00ce
+  metadata.gz: 808bf4695fcba808f36a2c808885529bdff8b8dae50ddfed71cd605115aa9014
+  data.tar.gz: 532e5bac353cceeff1806829f4e8d8f2421051799b3a249bf3119c4001c144fc
 SHA512:
-  metadata.gz: 786316240b620bed1a107503c2162d0add7979bbc70574a9f0d1b7cbc473e616e28001d8db9abc75edc972c544211207cbd93f1eee93e674f365d2b0cbecc5e0
-  data.tar.gz: aa6f59d62916ce00cb59ae8cca4e8e029ff96ff4c1fcb40041a4c4fd27d675dfcf98b7a2a04cca5a6f9876bdec846415196d09499f91ee170abb636964b22d25
+  metadata.gz: 177bfa1e9c486473285eba7fac243719f08af97ad58999fdb08c9d08725981ba8dce66143943768ff12a8e08d994ca34eb02a791cd567b7f98294732fd461a2a
+  data.tar.gz: 0eba14aa8d5ac54b4153fd48810c90fb979ac608cc3bf2b0fb68bdb039ed9b4db763d6610839a0656374f684fc9821bde4d3f7ae336f58ac9f894aa4aee2ad81

data/.version

@@ -1 +1 @@
-1.9.2
+1.9.4

data/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 1.9.4
+
+### Fixed — write bindings parsed the response body without checking the status
+
+A write aimed at a resource that is not there raised
+`JSON::ParserError: unexpected end of input at line 1 column 1`. Atlas is
+correct here: it answers `head :not_found`, a `404` with an empty body. The
+bindings then handed that empty body to `JSON.parse`.
+
+The message named neither the verb nor the resource, so an operator whose XML
+manifest carried a PID from another environment got five identical parser
+errors and nothing to act on. `Resource.fetch_resource` already guarded the
+**read** path against exactly this; the write half never got the same
+treatment.
+
+Every `create` / `update` / `metadata` / `parent` / `rollback` and sibling
+across `Work`, `Collection`, `Community`, `Blob`, `FileSet`, `Compilation` and
+`Person` now goes through a `write_resource` companion:
+
+- `404` → {AtlasRb::NotFoundError}, naming the verb and path.
+- `410` → the parsed body, as on the read path: an Idempotency-Key replay whose
+  resource has since been tombstoned answers `410 Gone` *with* the tombstone.
+- any other non-2xx → {AtlasRb::ResourceError}, carrying Atlas's status + body.
+- `2xx` → the parsed body, exactly as before.
+
+`NotFoundError` subclasses `ResourceError`, so a caller that only wants "the
+write failed" rescues the parent.
+
+Note the deliberate asymmetry with the read path, which keeps returning `nil`
+on a `404`: that answers a read, but not a write — the caller asked for a
+change and did not get one.
+
+Blast radius is which exception surfaces, not whether one does. The typed
+`403` / `422` translations raise inside the Faraday stack, so they still fire
+first; a `422` the middleware passes through on purpose (`tombstone`'s
+`has_live_children`) is unaffected, because `tombstone`, `destroy` and
+`complete` return the raw response and never parsed.
+
+## 1.9.3
+
+### Added — `depositor:` on `Collection.create` and `Community.create`
+
+`AtlasRb::Collection.create(parent_id, depositor: "000000099")` (and the same
+on `Community.create`) stamps a container's intellectual owner, matching what
+`Work.create` has always supported. Atlas already read the param; only the
+bindings couldn't pass it.
+
+The case it unblocks is seeding an institutional tree: the caller acts as an
+admin (the only identity whose wildcard carries a whole seed sequence) while
+attributing the containers to the anonymous NUID, since nobody personally owns
+them and access is via Grouper groups. That matters now that a depositor
+carries edit rights on their own resource — a container stamped with a real
+person's NUID would hand them edit over that whole subtree.
+
+Omitted, the depositor still falls through to the acting user, so existing
+callers are unaffected.
+
+### Added — typed errors for Atlas's container-create `403` and ACL-write `422`
+
+Atlas gained two refusals that the bindings previously swallowed, because
+`RaiseOnResourceError` was scoped to the re-parent / linked-member /
+Compilation / derivative-permissions / upload paths:
+
+- **A refused create.** `POST /{works,collections,communities}` now `403`s when
+  the caller holds no edit rights on the destination container. The binding's
+  `["collection"]` unwrap returned `nil`, so the caller's next `.id` raised
+  `NoMethodError` — an unhandled 500 instead of an authorization failure. Now
+  {AtlasRb::ForbiddenError}, carrying `action: "create_child"` and the parent
+  container's class as `subject`.
+- **A refused ACL write.** `PATCH /{type}/:id` with `metadata[permissions]`
+  now `422`s with `visibility_exceeds_parent` when the read audience would
+  exceed the structural container. The parsed envelope looked like a success
+  payload, so a user's visibility edit was discarded silently. Now
+  {AtlasRb::PermissionsError}, keyed on the `error` code rather than the path —
+  the same endpoint's other `422`s (tombstone's `has_live_children`) still pass
+  through untouched, which a path rule could not distinguish.
+
+The create branch matches the three paths exactly and only on `POST`, so member
+actions under the same prefix and the index `GET` are unaffected.
+
 ## 1.9.2
 
 ### Added — `read_only:` on `System::Token.mint`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.9.2)
+    atlas_rb (1.9.4)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -222,6 +222,11 @@ AtlasRb::FileSet.create("w-789", "primary") # file_set under work w-789, classif
 AtlasRb::Blob.create("w-789", path, name)  # blob under work w-789 with original filename preserved
 ```
 
+`Community.create`, `Collection.create`, and `Work.create` each accept an
+optional `depositor:` kwarg — the NUID to stamp as the resource's intellectual
+owner, independent of who authorizes the call. Omitted, Atlas falls through to
+the acting user.
+
 `Work.create`, `FileSet.create`, and `Blob.create` each accept an optional
 `idempotency_key:` kwarg for retry-safe bulk-deposit jobs. The caller
 generates the UUID; the Atlas server enforces uniqueness scoped to the
@@ -433,6 +438,43 @@ 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.
 
+### Missing resources: `nil` on a read, a raise on a write
+
+The two halves of the API answer an absent resource differently, on purpose.
+
+A **read** returns `nil`. "There is nothing there" is a legitimate answer to a
+question, and callers already nil-check a `find`:
+
+```ruby
+AtlasRb::Work.find("doesnotexist")   # => nil
+```
+
+A **write** raises `AtlasRb::NotFoundError`. The caller asked for a change and
+did not get one, so `nil` would invite the silent failure the read guard was
+written to prevent:
+
+```ruby
+begin
+  AtlasRb::Work.update("doesnotexist", "/tmp/mods.xml")
+rescue AtlasRb::NotFoundError => e
+  e.status    # => 404
+  e.message   # => "PATCH /works/doesnotexist → 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
+`AtlasRb::ResourceError`, which `NotFoundError` subclasses — so a caller that
+only wants "the write failed" rescues the parent.
+
+Two neighbours are deliberately untouched. A `410 Gone` is returned, not
+raised, the same way a read returns it: an `Idempotency-Key` replay whose
+resource has since been tombstoned answers `410` *with* the tombstone, and the
+caller reads `tombstoned`. And the typed `403` / `422` translations above still
+fire first, while `tombstone` / `destroy` / `complete` keep returning the raw
+Faraday response for the caller to read.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/blob.rb

@@ -157,6 +157,10 @@ module AtlasRb
     #   `"digest"` (the recorded fixity digest, `"sha512:<hex>"`).
     # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
     #   the uploaded bytes did not match (or the algorithm is unsupported).
+    # @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.
     #
     # @note Streams the file (FD closed deterministically); a multi-GB upload is
     #   not buffered in memory. See {AtlasRb::FaradayHelper#with_file_part}.
@@ -175,9 +179,9 @@ module AtlasRb
         payload = { work_id: id, original_filename: original_filename, binary: part }
         payload[:expected_digest] = expected_digest if expected_digest
 
-        AtlasRb::Mash.new(JSON.parse(
+        AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-            .post(ROUTE, payload)&.body
+            .post(ROUTE, payload)
         ))['blob']
       end
     end
@@ -223,6 +227,10 @@ module AtlasRb
     #   `"blob"`, with a refreshed `"digest"` for the new revision).
     # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
     #   the uploaded bytes did not match (or the algorithm is unsupported).
+    # @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.
     #
     # @note Streams the file with the FD closed deterministically — see {.create}.
     #
@@ -236,9 +244,9 @@ module AtlasRb
         payload = { binary: part }
         payload[:expected_digest] = expected_digest if expected_digest
 
-        AtlasRb::Mash.new(JSON.parse(
+        AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-            .patch(ROUTE + id, payload)&.body
+            .patch(ROUTE + id, payload)
         ))
       end
     end
@@ -324,8 +332,9 @@ module AtlasRb
     # recopied. Avoids a full round-trip of the bytes back through the caller
     # (vs. re-streaming {.version_content} into {.update}).
     #
-    # Pass a `version_id` obtained from {.versions}. An unknown id or version
-    # yields a `404` (raw Faraday response).
+    # Pass a `version_id` obtained from {.versions}. Atlas answers an unknown id
+    # or version with a `404`, which raises {AtlasRb::NotFoundError} — a write
+    # that did not happen must not read like one that did.
     #
     # @param id [String] the Blob ID.
     # @param version_id [String] the OCFL version label to reinstate, e.g. `"v1"`.
@@ -337,13 +346,17 @@ module AtlasRb
     #   omitted.
     # @return [AtlasRb::Mash] the updated `"blob"` payload (NOID unchanged,
     #   `"digest"` refreshed to the reinstated bytes).
+    # @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::Blob.rollback("b-321", "v1")
     def self.rollback(id, version_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .post("#{ROUTE}#{id}/rollback", JSON.dump(version_id: version_id))&.body
+          .post("#{ROUTE}#{id}/rollback", JSON.dump(version_id: version_id))
       ))['blob']
     end
   end

data/lib/atlas_rb/collection.rb

@@ -57,14 +57,30 @@ module AtlasRb
     # @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 depositor [String, nil] NUID to stamp as the Collection's
+    #   intellectual owner. Omit it and Atlas falls through to the acting user.
+    #   Supply it to attribute a container to someone other than whoever is
+    #   authorizing the call — e.g. seeding an institutional tree as an admin
+    #   while attributing it to the anonymous NUID, since nobody personally owns
+    #   those containers and access to them is via Grouper groups. The depositor
+    #   is immutable post-create; there is no setter on the update surface.
     # @return [Hash] the created Collection payload (post-update if
     #   `xml_path` was supplied).
+    # @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 A featured showcase collection
     #   AtlasRb::Collection.create("c-123", featured: true)
-    def self.create(id, xml_path = nil, featured: false, nuid: nil, on_behalf_of: nil)
-      result = AtlasRb::Mash.new(JSON.parse(
-        connection({ parent_id: id, featured: featured }, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+    #
+    # @example An institutional container owned by nobody
+    #   AtlasRb::Collection.create("c-123", depositor: "000000099")
+    def self.create(id, xml_path = nil, featured: false, nuid: nil, on_behalf_of: nil, depositor: nil)
+      params = { parent_id: id, featured: featured }
+      params[:depositor] = depositor if depositor
+      result = AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
       ))["collection"]
       return result if xml_path.to_s.empty?
 
@@ -84,12 +100,16 @@ module AtlasRb
     # @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 [AtlasRb::Mash] the updated `"collection"` object, already unwrapped.
+    # @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_featured("col-456", true)
     def self.set_featured(id, featured, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
-        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))["collection"]
     end
 
@@ -122,13 +142,17 @@ module AtlasRb
     #   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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')&.body
+          .patch(ROUTE + id + '/parent')
       ))["collection"]
     end
 
@@ -188,6 +212,10 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @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")
@@ -195,8 +223,8 @@ module AtlasRb
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
                                                            File.basename(xml_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+      AtlasRb::Mash.new(write_resource(
+        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
       ))
     end
 
@@ -216,12 +244,16 @@ module AtlasRb
     #   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(JSON.parse(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))
     end
 
@@ -243,6 +275,10 @@ module AtlasRb
     # @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(
@@ -253,9 +289,9 @@ module AtlasRb
     #   )
     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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
       ))
     end
 

data/lib/atlas_rb/community.rb

@@ -52,17 +52,33 @@ module AtlasRb
     # @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 depositor [String, nil] NUID to stamp as the Community's
+    #   intellectual owner. Omit it and Atlas falls through to the acting user.
+    #   Supply it to attribute a container to someone other than whoever is
+    #   authorizing the call — e.g. seeding an institutional tree as an admin
+    #   while attributing it to the anonymous NUID, since nobody personally owns
+    #   those containers and access to them is via Grouper groups. The depositor
+    #   is immutable post-create; there is no setter on the update surface.
     # @return [Hash] the created Community payload (post-update if `xml_path`
     #   was supplied).
+    # @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 Top-level community, no metadata
     #   AtlasRb::Community.create(nil)
     #
     # @example Sub-community seeded from MODS
     #   AtlasRb::Community.create("c-parent", "/tmp/dept-mods.xml")
-    def self.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil)
-      result = AtlasRb::Mash.new(JSON.parse(
-        connection({ parent_id: id }, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+    #
+    # @example An institutional container owned by nobody
+    #   AtlasRb::Community.create("c-parent", depositor: "000000099")
+    def self.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil, depositor: nil)
+      params = { parent_id: id }
+      params[:depositor] = depositor if depositor
+      result = AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
       ))["community"]
       return result if xml_path.to_s.empty?
 
@@ -101,6 +117,10 @@ module AtlasRb
     #   `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 Move under another Community
     #   AtlasRb::Community.reparent("c-123", "c-999")
@@ -108,9 +128,9 @@ module AtlasRb
     # @example Promote to a top-level Community
     #   AtlasRb::Community.reparent("c-123", nil)
     def self.reparent(id, new_parent_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')&.body
+          .patch(ROUTE + id + '/parent')
       ))["community"]
     end
 
@@ -171,6 +191,10 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @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::Community.update("c-123", "/tmp/community-mods.xml")
@@ -178,8 +202,8 @@ module AtlasRb
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
                                                            File.basename(xml_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+      AtlasRb::Mash.new(write_resource(
+        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
       ))
     end
 
@@ -200,12 +224,16 @@ module AtlasRb
     #   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::Community.metadata("c-123", title: "New Name")
     def self.metadata(id, values, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))
     end
 
@@ -227,6 +255,10 @@ module AtlasRb
     # @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::Community.set_thumbnails(
@@ -237,9 +269,9 @@ module AtlasRb
     #   )
     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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
       ))
     end
 

data/lib/atlas_rb/compilation.rb

@@ -136,6 +136,10 @@ module AtlasRb
     #   e.g. a blank title).
     # @raise [AtlasRb::ForbiddenError] if the caller may not create Sets
     #   (guests cannot).
+    # @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::Compilation.create("Course readings",
@@ -144,8 +148,8 @@ module AtlasRb
     def self.create(title, description: nil, nuid: nil, on_behalf_of: nil)
       params = { title: title }
       params[:description] = description if description
-      AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
       ))["compilation"]
     end
 
@@ -172,6 +176,10 @@ module AtlasRb
     # @raise [AtlasRb::CompilationError] if Atlas rejects the update (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights
     #   (owner / explicit grant / admin).
+    # @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 Rename
     #   AtlasRb::Compilation.update("c-123", title: "Renamed", nuid: "000000002")
@@ -185,8 +193,8 @@ module AtlasRb
       params[:title]       = title       if title
       params[:description] = description if description
       params[:permissions] = permissions if permissions
-      AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))["compilation"]
     end
 
@@ -231,13 +239,17 @@ module AtlasRb
     #   the full recipe, so chip counts refresh without a follow-up {.find}.
     # @raise [AtlasRb::CompilationError] if the noid is not a Collection (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.add_included_collection("c-123", "col-456", nuid: "000000002")
     def self.add_included_collection(id, collection_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ collection_id: collection_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + '/included_collections')&.body
+          .post(ROUTE + id + '/included_collections')
       ))["compilation"]
     end
 
@@ -256,13 +268,17 @@ module AtlasRb
     #   omitted.
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.remove_included_collection("c-123", "col-456", nuid: "000000002")
     def self.remove_included_collection(id, collection_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + '/included_collections/' + collection_id)&.body
+          .delete(ROUTE + id + '/included_collections/' + collection_id)
       ))["compilation"]
     end
 
@@ -281,13 +297,17 @@ module AtlasRb
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::CompilationError] if the noid is not a Work (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.add_included_work("c-123", "w-789", nuid: "000000002")
     def self.add_included_work(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ work_id: work_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + '/included_works')&.body
+          .post(ROUTE + id + '/included_works')
       ))["compilation"]
     end
 
@@ -303,13 +323,17 @@ module AtlasRb
     #   omitted.
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.remove_included_work("c-123", "w-789", nuid: "000000002")
     def self.remove_included_work(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + '/included_works/' + work_id)&.body
+          .delete(ROUTE + id + '/included_works/' + work_id)
       ))["compilation"]
     end
 
@@ -331,13 +355,17 @@ module AtlasRb
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::CompilationError] if the noid is not a Work (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.add_exclusion("c-123", "w-789", nuid: "000000002")
     def self.add_exclusion(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ work_id: work_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + '/exclusions')&.body
+          .post(ROUTE + id + '/exclusions')
       ))["compilation"]
     end
 
@@ -353,13 +381,17 @@ module AtlasRb
     #   omitted.
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.remove_exclusion("c-123", "w-789", nuid: "000000002")
     def self.remove_exclusion(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + '/exclusions/' + work_id)&.body
+          .delete(ROUTE + id + '/exclusions/' + work_id)
       ))["compilation"]
     end