atlas_rb 1.1.2 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 195a3c85a8653e6835bb472b7cda45847e254057075694e37ecfa779efe2dd39
-  data.tar.gz: ea58c157df06abcfa8d3f4c6b18fd00e5f87892a8b4231b526ac3e60a8e13510
+  metadata.gz: 30f433b53fc97128762eadbf01f12f975111c2b6e597469acc19831e3ef02bba
+  data.tar.gz: 3604a876f6061a2a4bf45953abae93faca9b7fdae27a9b264ec5e10526acaa0c
 SHA512:
-  metadata.gz: 2782eeb3e29454728e68e85144ba5046dd86d9b2ff58eea1cfd704bf2ce03e70f81e977a5b9ad5ffe4091d69d99225746ed2076e875891f358308038983cbfe6
-  data.tar.gz: 8dc180f51b17ffdb1feec818445573ec9c25eab3ee4e4245e9afb31f564a14dfbc93db40e3bd174a078e89f31bd57c240eb85b17f69828494ebaab3c0f23f9f4
+  metadata.gz: 62376e2b252c0269420ca89661bf7bb864b198f820076bd0c01210dc129adde111f218f2f33e7b3f88365a8b944cd5d2fda0758de050b9585c84ded5a1694309
+  data.tar.gz: d498f94bff1f2e13fcdacbca9ca05dce38bbcfe80209de0f3339f31b69aff8e47492980079096f2f141748845aab30e271ba54fa19639368c005a37d1cc0a9d7

data/.version

@@ -1 +1 @@
-1.1.2
+1.2.1

data/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 1.2.1
+
+### Added — typed errors for re-parent / linked-member rejections
+
+The re-parent and linked-member bindings no longer swallow Atlas's `4xx`
+error envelope. Previously a `422`/`403` parsed fine but lacked the
+success key (`"collection"` / `"work"` / `"community"`), so the binding
+returned `nil` and discarded Atlas's machine-readable `error` / `message`
+— callers could not tell an invalid move from a not-found from a
+forbidden one.
+
+- **`AtlasRb::ReparentError`** — raised on a `422` to a `.../parent` path
+  (`Collection`/`Community`/`Work.reparent`). Carries the envelope's
+  `error` discriminator as `#code` (`cycle`, `invalid_parent_type`,
+  `tombstoned_node`, `tombstoned_parent`, `parent_required`,
+  `parent_not_found`) plus `#resource_id` and `#message`.
+- **`AtlasRb::LinkedMemberError`** — raised on a `422` to a
+  `.../linked_members` path (`Work.add_linked_member` /
+  `remove_linked_member`). Same shape (`#code`, `#resource_id`, `#message`).
+- **`AtlasRb::ForbiddenError`** — raised on a `403` to either path.
+  Carries `#code`, `#action`, and `#subject` from the envelope.
+
+All three subclass `AtlasRb::Error`. A new
+`AtlasRb::Middleware::RaiseOnResourceError` (registered alongside
+`RaiseOnStaleResource`) performs the translation, keyed on the request
+**path + status** so it stays narrow: only the re-parent and linked-member
+write paths are affected, and only `403`/`422` bodies carrying an `error`
+discriminator. Other endpoints, other statuses, and the `tombstone`
+endpoint's `code: "has_live_children"` body are untouched, and the `409`
+optimistic-lock conflict still surfaces as `StaleResourceError`. Rescue is
+opt-in — callers that don't discriminate see the success payload exactly as
+before.
+
+## 1.2.0
+
+### Added — Tree/DAG foundation bindings
+
+Thin Faraday mirrors for the two membership mutations Atlas shipped as
+part of the DRS "Tree/DAG foundation" (re-parenting and linked members).
+No client-side logic — the gem mirrors Atlas's wire and never queries
+Solr.
+
+- **`AtlasRb::Collection.reparent(id, new_parent_id, nuid: nil, on_behalf_of: nil)`**
+- **`AtlasRb::Community.reparent(id, new_parent_id, nuid: nil, on_behalf_of: nil)`**
+- **`AtlasRb::Work.reparent(id, new_collection_id, nuid: nil, on_behalf_of: nil)`**
+
+  Bind `PATCH /<type>/:id/parent` with a `{ parent_id }` body, moving a
+  resource to a new structural parent. Mirrors `create`'s single-parent-id
+  shape and returns the updated resource (same shape as `find`), reflecting
+  the new `a_member_of`. `Community.reparent` accepts `new_parent_id: nil`
+  to promote a Community to the top of the tree — the same way
+  `Community.create(nil)` makes a top-level Community; a `nil` destination
+  is rejected by Atlas for Works and Collections. Atlas enforces the
+  structural rules (type, cycle, tombstone) server-side and synchronously
+  cascades the ancestry index over descendants, surfacing violations as
+  `422`. The Work re-parent endpoint is included — Atlas shipped it (the
+  plan had flagged it as optional). All three endpoints use the shared
+  `parent_id` body key, including the Work one (not `collection_id`).
+
+- **`AtlasRb::Work.linked_members(id, nuid: nil, on_behalf_of: nil)`** —
+  `GET /works/:id/linked_members`.
+- **`AtlasRb::Work.add_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)`** —
+  `POST /works/:id/linked_members` with a `{ collection_id }` body.
+- **`AtlasRb::Work.remove_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)`** —
+  `DELETE /works/:id/linked_members/:collection_id` (Collection as a path
+  segment).
+
+  The DAG overlay: a Work has one structural parent (`a_member_of`) but
+  may additionally be a *linked* member of any number of other Collections
+  (`a_linked_member_of`). These manage that overlay without moving the
+  Work. All three return the Work's current linked Collection noids as a
+  bare array (mirroring `Collection.children`); the two mutations return
+  the list *after* the change, so no follow-up GET is needed.
+
+  Cerberus consumes these from the re-parent and "add to collection" UI.
+
 ## 1.1.1
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.1.2)
+    atlas_rb (1.2.1)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -19,11 +19,11 @@ GEM
       faraday (>= 1, < 3)
     faraday-multipart (1.2.0)
       multipart-post (~> 2.0)
-    faraday-net_http (3.4.3)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
     hashie (5.1.0)
       logger
-    json (2.19.7)
+    json (2.19.8)
     logger (1.7.0)
     multipart-post (2.4.1)
     net-http (0.9.1)

data/README.md

@@ -205,6 +205,73 @@ result["events"].first["action"] # => "update"
 Authorization errors (`401` / `403`) are not caught here — they surface as
 raw Faraday responses for the calling application's rescue layer.
 
+### Re-parenting
+
+`reparent` moves a resource to a new structural parent, binding Atlas's
+`PATCH /<type>/:id/parent` endpoint. It mirrors `create`'s "single parent
+id" shape and returns the updated resource (same shape as `find`), so the
+caller sees the new `a_member_of` without a follow-up GET. Atlas enforces
+the structural rules (type, cycle, tombstone guards) server-side and
+synchronously cascades the ancestry index over descendants; rule
+violations come back as `422`.
+
+```ruby
+AtlasRb::Collection.reparent("col-456", "c-999")  # move collection to community c-999
+AtlasRb::Work.reparent("w-789", "col-999")         # move work to collection col-999
+AtlasRb::Community.reparent("c-123", "c-999")      # nest community under c-999
+AtlasRb::Community.reparent("c-123", nil)          # promote community to top of tree
+```
+
+Only `Community.reparent` accepts a `nil` destination (move to the top of
+the tree) — the same way `Community.create(nil)` makes a top-level
+community. A `nil` destination for a Work or Collection is rejected by
+Atlas.
+
+When Atlas rejects a move, the binding raises a typed error carrying the
+machine-readable `error` code from Atlas's envelope, rather than returning
+`nil` — so callers can message the *specific* reason:
+
+```ruby
+begin
+  AtlasRb::Collection.reparent("col-456", "c-999")
+rescue AtlasRb::ReparentError => e
+  e.code     # => "cycle" / "invalid_parent_type" / "tombstoned_parent" / …
+  e.message  # => human-readable description from Atlas
+rescue AtlasRb::ForbiddenError => e
+  e.code     # => the authz failure (HTTP 403)
+end
+```
+
+`ReparentError` (HTTP 422, structural rules: `cycle`, `invalid_parent_type`,
+`tombstoned_node`, `tombstoned_parent`, `parent_required`,
+`parent_not_found`) and `ForbiddenError` (HTTP 403, authorization) both
+subclass `AtlasRb::Error`. The `409` optimistic-lock conflict still surfaces
+as `StaleResourceError`, unchanged. Rescue is opt-in — callers that don't
+care keep the success payload as before.
+
+### Linked members (the DAG overlay)
+
+A Work has exactly one structural parent (`a_member_of`, set by `create` /
+`reparent`) but may additionally be a *linked* member of any number of
+other Collections (`a_linked_member_of`). The linked-member bindings on
+`Work` manage that overlay without ever moving the Work:
+
+```ruby
+AtlasRb::Work.linked_members("w-789")                 # => ["col-456", "col-457"]
+AtlasRb::Work.add_linked_member("w-789", "col-456")    # => ["col-456"]  (updated list)
+AtlasRb::Work.remove_linked_member("w-789", "col-456") # => []           (updated list)
+```
+
+All three return the Work's current linked Collection noids as a bare
+array (mirroring `Collection.children`); the two mutations return the list
+*after* the change, so no follow-up `linked_members` GET is needed.
+Resolving those Collections' full contents is a Cerberus/Solr concern —
+this gem never queries the index.
+
+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.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/collection.rb

@@ -65,6 +65,45 @@ module AtlasRb
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
+    # Move a Collection to a different parent Community.
+    #
+    # Wraps `PATCH /collections/<id>/parent` with a `parent_id` of the new
+    # Community. 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 ID.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @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).
+    #
+    # @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(
+        connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/parent')&.body
+      ))["collection"]
+    end
+
     # Tombstone (withdraw) a Collection.
     #
     # The Collection remains in Atlas storage but is marked as withdrawn:

data/lib/atlas_rb/community.rb

@@ -69,6 +69,50 @@ module AtlasRb
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
+    # Move a Community to a different parent Community — or to the top of the
+    # tree.
+    #
+    # Wraps `PATCH /communities/<id>/parent` with a `parent_id` of the new
+    # parent Community. Pass `new_parent_id = nil` to promote the Community to
+    # a top-level node (no parent) — mirroring how {.create} treats a `nil`
+    # `id`; the gem omits the blank param and Atlas reads it as "move to top".
+    # Atlas re-parents the Community and synchronously cascades the ancestry
+    # index over its descendant Collections and Works; the structural rules
+    # (cycle, tombstone guards) are enforced server-side and surface as a
+    # `422`.
+    #
+    # @param id [String] the Community ID to move.
+    # @param new_parent_id [String, nil] the destination Community ID, or
+    #   `nil` to move the Community to the top of the tree.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @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 `"community"` 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`, `tombstoned_node`, `tombstoned_parent`,
+    #   `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).
+    #
+    # @example Move under another Community
+    #   AtlasRb::Community.reparent("c-123", "c-999")
+    #
+    # @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(
+        connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/parent')&.body
+      ))["community"]
+    end
+
     # Tombstone (withdraw) a Community.
     #
     # The Community remains in Atlas storage but is marked as withdrawn:

data/lib/atlas_rb/errors.rb

@@ -36,4 +36,98 @@ module AtlasRb
       @action = action
     end
   end
+
+  # Raised when Atlas rejects a re-parent (`PATCH /<type>/:id/parent`) with a
+  # structural `422` carrying a machine-readable `error` discriminator —
+  # `tombstoned_node`, `tombstoned_parent`, `parent_required`,
+  # `invalid_parent_type`, `cycle`, or `parent_not_found`.
+  #
+  # Mirrors {StaleResourceError}: a narrow translation of one wire signal
+  # callers need to discriminate on. Without it the binding's `["collection"]`
+  # / `["work"]` / `["community"]` unwrap silently returns `nil` on a 422,
+  # discarding Atlas's `error`/`message` and leaving the caller unable to tell
+  # an invalid move from a not-found from a forbidden one.
+  #
+  # Callers key on {#code} for specific messaging, falling back to {#message}:
+  #
+  #   rescue AtlasRb::ReparentError => e
+  #     flash.now[:alert] = t("reparent.errors.#{e.code}", default: e.message)
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403), not
+  #   this — even on a re-parent path.
+  class ReparentError < Error
+    # @return [String, nil] the machine-readable error code from the envelope
+    #   (e.g. `"cycle"`), suitable for keying an i18n map.
+    attr_reader :code
+
+    # @return [String, nil] the rejected resource's ID, from the envelope.
+    attr_reader :resource_id
+
+    # @param message [String] human-readable rejection description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param resource_id [String, nil] the rejected resource's ID.
+    def initialize(message, code: nil, resource_id: nil)
+      super(message)
+      @code = code
+      @resource_id = resource_id
+    end
+  end
+
+  # Raised when Atlas rejects a linked-member write
+  # (`POST` / `DELETE /works/:id/linked_members`) with a `422` carrying a
+  # machine-readable `error` discriminator. The linked-member sibling of
+  # {ReparentError}; same shape, same rationale (the binding would otherwise
+  # discard the envelope on a non-2xx).
+  #
+  #   rescue AtlasRb::LinkedMemberError => e
+  #     flash.now[:alert] = t("linked_member.errors.#{e.code}", default: e.message)
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403).
+  class LinkedMemberError < Error
+    # @return [String, nil] the machine-readable error code from the envelope,
+    #   suitable for keying an i18n map.
+    attr_reader :code
+
+    # @return [String, nil] the rejected resource's ID, from the envelope.
+    attr_reader :resource_id
+
+    # @param message [String] human-readable rejection description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param resource_id [String, nil] the rejected resource's ID.
+    def initialize(message, code: nil, resource_id: nil)
+      super(message)
+      @code = code
+      @resource_id = resource_id
+    end
+  end
+
+  # Raised when Atlas refuses a re-parent or linked-member write with an
+  # HTTP `403`, whose envelope is `{ "error", "action", "subject" }`. Lets
+  # callers distinguish "you may not do this" from a structural rejection
+  # ({ReparentError} / {LinkedMemberError}) or a not-found.
+  #
+  # @note Scoped to the re-parent / linked-member write paths — `403`s on
+  #   other endpoints still surface as raw responses for the caller's own
+  #   rescue layer, unchanged.
+  class ForbiddenError < Error
+    # @return [String, nil] the envelope's `error` value.
+    attr_reader :code
+
+    # @return [String, nil] the action that was forbidden (e.g. `"reparent"`).
+    attr_reader :action
+
+    # @return [String, nil] the subject (resource) the action was forbidden on.
+    attr_reader :subject
+
+    # @param message [String] human-readable authorization-failure description.
+    # @param code [String, nil] the envelope's `error` value.
+    # @param action [String, nil] the forbidden action.
+    # @param subject [String, nil] the subject the action was forbidden on.
+    def initialize(message, code: nil, action: nil, subject: nil)
+      super(message)
+      @code = code
+      @action = action
+      @subject = subject
+    end
+  end
 end

data/lib/atlas_rb/faraday_helper.rb

@@ -60,6 +60,7 @@ module AtlasRb
         headers: headers
       ) do |f|
         f.use AtlasRb::Middleware::RaiseOnStaleResource
+        f.use AtlasRb::Middleware::RaiseOnResourceError
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Middleware
+    # Translates Atlas's structured re-parent / linked-member rejections into
+    # typed Ruby exceptions, so the resource bindings don't silently swallow
+    # the error envelope.
+    #
+    # The re-parent and linked-member bindings unwrap their success payload by
+    # a fixed key (`["collection"]` / `["work"]` / `["community"]`, or the
+    # bare linked-member array). On a `4xx` that key is absent, so the binding
+    # would return `nil` and discard Atlas's machine-readable `error` /
+    # `message`. This middleware keys on the **request path + status** and
+    # raises a typed error carrying the envelope through, parallel to
+    # {RaiseOnStaleResource}.
+    #
+    # It is intentionally narrow — it only fires on the re-parent
+    # (`.../parent`) and linked-member (`.../linked_members...`) write paths,
+    # and only on `403` / `422` bodies carrying an `error` discriminator.
+    # Everything else (other paths, other statuses, a `422` whose body uses a
+    # different discriminator such as `tombstone`'s `code: "has_live_children"`)
+    # passes through untouched, so atlas_rb stays a thin Faraday binding that
+    # translates only the wire signals callers genuinely need to discriminate.
+    #
+    # Mapping:
+    # - `403` (either path) → {AtlasRb::ForbiddenError} (`error`/`action`/`subject`)
+    # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
+    # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
+    class RaiseOnResourceError < Faraday::Middleware
+      # @param env [Faraday::Env] the completed response environment.
+      # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent / linked-member path.
+      # @raise [AtlasRb::ReparentError] on a 422 to a re-parent path.
+      # @raise [AtlasRb::LinkedMemberError] on a 422 to a linked-member path.
+      # @return [void]
+      def on_complete(env)
+        return unless env.status == 403 || env.status == 422
+
+        path     = env.url&.path.to_s
+        reparent = path.end_with?("/parent")
+        linked   = path.include?("/linked_members")
+        return unless reparent || linked
+
+        body = parse_json(env.body)
+        return unless body.is_a?(Hash) && body["error"]
+
+        if env.status == 403
+          raise AtlasRb::ForbiddenError.new(
+            body["message"] || "Atlas refused the request",
+            code: body["error"],
+            action: body["action"],
+            subject: body["subject"]
+          )
+        elsif reparent
+          raise AtlasRb::ReparentError.new(
+            body["message"] || "Atlas rejected the re-parent",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
+        else
+          raise AtlasRb::LinkedMemberError.new(
+            body["message"] || "Atlas rejected the linked-member write",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
+        end
+      end
+
+      private
+
+      def parse_json(body)
+        return body if body.is_a?(Hash)
+
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/atlas_rb/work.rb

@@ -129,6 +129,49 @@ module AtlasRb
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
+    # Move a Work to a different parent Collection.
+    #
+    # Wraps `PATCH /works/<id>/parent` with a `parent_id` of the new
+    # Collection. This changes the Work's single **structural** home
+    # (`a_member_of`) — distinct from {.add_linked_member}, which adds an
+    # additional *linked* membership without moving the Work. Atlas
+    # re-parents the Work and synchronously updates its ancestry index; the
+    # structural rules (type, cycle, tombstone guards) are enforced
+    # server-side and surface as a `422`.
+    #
+    # **Note**: like {.create}, the destination here is a **Collection**, but
+    # the underlying request still uses the shared `parent_id` body key (not
+    # `collection_id`) — every re-parent endpoint posts `{ parent_id }`.
+    #
+    # @param id [String] the Work ID to move.
+    # @param new_collection_id [String] the destination Collection ID.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @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 `"work"` 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).
+    #
+    # @example
+    #   AtlasRb::Work.reparent("w-789", "col-999")
+    def self.reparent(id, new_collection_id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({ parent_id: new_collection_id }, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/parent')&.body
+      ))["work"]
+    end
+
     # Tombstone (withdraw) a Work.
     #
     # The Work remains in Atlas storage along with its FileSets and Blobs,
@@ -349,5 +392,111 @@ module AtlasRb
         ROUTE + id + '/mods' + (kind.present? ? ".#{kind}" : '')
         )&.body
     end
+
+    # List the Collections a Work is a *linked* member of.
+    #
+    # Wraps `GET /works/<id>/linked_members`. Linked membership is the DAG
+    # overlay — a Work has exactly one structural parent (`a_member_of`, set
+    # by {.create} / {.reparent}) but may additionally appear in any number
+    # of other Collections as a linked member (`a_linked_member_of`). This
+    # returns just those linked Collection noids; the structural parent is
+    # not included.
+    #
+    # @param id [String] the Work ID.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @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 [Array<String>] linked Collection noids (possibly empty). The
+    #   shape mirrors {Collection.children} — a bare array of ids, not an
+    #   envelope.
+    #
+    # @example
+    #   AtlasRb::Work.linked_members("w-789")
+    #   # => ["col-456", "col-457"]
+    def self.linked_members(id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/linked_members')&.body
+      )
+    end
+
+    # Add a linked membership: surface a Work in an additional Collection.
+    #
+    # Wraps `POST /works/<id>/linked_members` with a `collection_id` body.
+    # This does **not** move the Work — its structural parent (`a_member_of`)
+    # is untouched; the Collection is added to `a_linked_member_of`. Atlas
+    # enforces two-sided authorization (edit on the Work *and* the target
+    # Collection) and the structural guards, surfacing failures as a `422`.
+    # Permissions are never changed by this call.
+    #
+    # @param work_id [String] the Work ID.
+    # @param collection_id [String] the Collection to link the Work into.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @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 [Array<String>] the Work's full set of linked Collection noids
+    #   *after* the add — the affected sub-resource, so no follow-up
+    #   {.linked_members} GET is needed.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
+    # @raise [AtlasRb::LinkedMemberError] if Atlas rejects the link on
+    #   structural grounds (HTTP 422). The envelope's `error` code is exposed
+    #   as `#code`.
+    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the link on
+    #   authorization grounds (HTTP 403).
+    #
+    # @example
+    #   AtlasRb::Work.add_linked_member("w-789", "col-456")
+    #   # => ["col-456"]
+    def self.add_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({ collection_id: collection_id }, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + work_id + '/linked_members')&.body
+      )
+    end
+
+    # Remove a linked membership: drop a Work from an additional Collection.
+    #
+    # Wraps `DELETE /works/<id>/linked_members/<collection_id>` — the
+    # Collection is passed as a path segment, not a body. This removes the
+    # Collection from the Work's `a_linked_member_of`; the structural parent
+    # (`a_member_of`) is untouched. Atlas enforces the same two-sided
+    # authorization as {.add_linked_member}. Removing a link that does not
+    # exist is a server-side concern; this binding simply forwards the call.
+    #
+    # @param work_id [String] the Work ID.
+    # @param collection_id [String] the linked Collection to remove.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @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 [Array<String>] the Work's remaining linked Collection noids
+    #   *after* the removal (possibly empty).
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
+    # @raise [AtlasRb::LinkedMemberError] if Atlas rejects the removal on
+    #   structural grounds (HTTP 422). The envelope's `error` code is exposed
+    #   as `#code`.
+    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the removal on
+    #   authorization grounds (HTTP 403).
+    #
+    # @example
+    #   AtlasRb::Work.remove_linked_member("w-789", "col-456")
+    #   # => []
+    def self.remove_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + work_id + '/linked_members/' + collection_id)&.body
+      )
+    end
   end
 end

data/lib/atlas_rb.rb

@@ -7,6 +7,7 @@ require_relative "atlas_rb/version"
 require_relative "atlas_rb/errors"
 require_relative "atlas_rb/configuration"
 require_relative "atlas_rb/middleware/raise_on_stale_resource"
+require_relative "atlas_rb/middleware/raise_on_resource_error"
 require_relative "atlas_rb/faraday_helper"
 require_relative "atlas_rb/mash"
 require_relative "atlas_rb/authentication"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -129,6 +129,7 @@ files:
 - lib/atlas_rb/faraday_helper.rb
 - lib/atlas_rb/file_set.rb
 - lib/atlas_rb/mash.rb
+- lib/atlas_rb/middleware/raise_on_resource_error.rb
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/system/user.rb