atlas_rb 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93e0688ad6097a3b6a36ed26db8c19d3416cb3c59beb3d95dd3cff61c6cdd176
-  data.tar.gz: 1af0ff155d288412bd6ab8a95fc50da55cfccd02d605b5bae1cf28cebdf33973
+  metadata.gz: 29da2e41c70d17572c6c24002ba0ff25beb2ad6cdd940dee157a83133c86efaf
+  data.tar.gz: 9e16fed8e22867c37647a12de104135d78f57995ba5e6decd4929ac6a402bae7
 SHA512:
-  metadata.gz: 44c8582605f238861c424a769fd4e788e08189edd969f3974d113a938f54ecce522e143ec0418cd813de958c1cbb6d9cd44b4796b6b9c190629af49a1d0417e9
-  data.tar.gz: 8ad34a6b44d4472ba300f8ef7b6c9f30d5d8674f0f69f7711e094d202ba07f2b428607b463ce8261e21e2fa5bbcbca865da9de3fb3af8e28d6e8906810037a12
+  metadata.gz: 7ba5a0216a5cc5dacce4f6822078eb07d71aa4e14b31142c83dd823c0ec177efa92e1712eac0b235c125870611dcd4633817066c5ee70a98d6f85adbec614a7f
+  data.tar.gz: b176fc377d6d802e356c5f0a0fd487c6c899d4b5e323e3017eb773fd11e06dd8ebb415329a4c4e81aef5f55f0086602fc33a6cb82c4699709e0a3209c542a48d

data/.version

@@ -1 +1 @@
-1.2.0
+1.2.2

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## Unreleased
+
+### Added — `AtlasRb::AuditEvent.emit` (session-scoped audit events)
+
+A new binding for Atlas's `POST /audit_events` endpoint, which records an
+AuditEvent with a **null `resource_id`** — an event not tied to any
+resource write. This is the gem's half of the impersonation audit trail
+(acting-as / view-as): the session lifecycle lives entirely in the calling
+application, and a view-as session performs no writes, so neither leaves a
+per-resource event for `Resource.history` to surface.
+
+```ruby
+AtlasRb::AuditEvent.emit(
+  action:            "impersonation_started",  # or "impersonation_ended"
+  actor_nuid:        admin_nuid,
+  on_behalf_of_nuid: target_nuid,
+  mode:              "acting_as"               # or "view_as"
+)
+```
+
+- The recorded principals (`actor_nuid`, `on_behalf_of_nuid`), `mode`, and
+  an optional free-form `payload:` travel in the request **body**, not in
+  ambient headers — so the call is self-describing even when fired as a
+  session is being torn down (e.g. `impersonation_ended`).
+- The request authenticates via the standard `connection` (system token),
+  with the `User: NUID` header pinned to `actor_nuid` so the server-side
+  admin gate holds regardless of ambient `Current` state.
+- `on_behalf_of_nuid`, `mode`, and `payload` are omitted from the body when
+  blank, leaving room for future, mode-less session events. Atlas stamps
+  `occurred_at` server-side.
+- Authorization errors (`401` / `403`) surface as raw Faraday responses,
+  matching `Resource.history`.
+
+Depends on the matching Atlas-side `POST /audit_events` emit endpoint
+(nullable resource scope, admin-gated); see the impersonation gap report.
+
+## 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.2.0)
+    atlas_rb (1.2.2)
       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

@@ -113,6 +113,7 @@ Community  →  Collection  →  Work
 | `AtlasRb::Blob`        | The binary bytes; supports streaming downloads.                           |
 | `AtlasRb::Authentication` | NUID → user record / group lookup.                                     |
 | `AtlasRb::Resource`    | Generic resolver, permissions lookup, and audit-event history.            |
+| `AtlasRb::AuditEvent`  | Emit a session-scoped (resource-less) audit event, e.g. impersonation.    |
 | `AtlasRb::Reset`       | Test-only — wipes Atlas state via `GET /reset`.                           |
 
 ## Namespace gradient: regular / Admin / System
@@ -205,6 +206,45 @@ 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.
 
+### Session-scoped audit events
+
+`Resource.history` only reads events that hang off a resource write. Some
+auditable events have no resource to attach to — most notably impersonation
+sessions (acting-as / view-as): the session lifecycle lives in the calling
+app, and a view-as session performs no writes at all, so it would otherwise
+leave no audit trail. `AtlasRb::AuditEvent.emit` wraps Atlas's
+`POST /audit_events` endpoint, which records an event with a **null
+`resource_id`**.
+
+The principals and metadata travel in the request body — not inferred from
+ambient headers — so the call is self-describing even when fired as a
+session is being torn down. The request is admin-gated server-side; the
+`User: NUID` header is pinned to the `actor_nuid` you pass.
+
+```ruby
+# An admin starts acting as another user:
+AtlasRb::AuditEvent.emit(
+  action:            "impersonation_started",
+  actor_nuid:        Current.nuid,   # the admin (also the User: header)
+  on_behalf_of_nuid: target_nuid,    # the impersonated user
+  mode:              "acting_as"      # or "view_as"
+)
+
+# …and later ends the session:
+AtlasRb::AuditEvent.emit(
+  action:            "impersonation_ended",
+  actor_nuid:        admin_nuid,
+  on_behalf_of_nuid: target_nuid,
+  mode:              "acting_as"
+)
+```
+
+`on_behalf_of_nuid`, `mode`, and `payload:` (free-form metadata) are
+omitted from the body when blank, so `emit` can also carry future,
+mode-less session events. Atlas stamps `occurred_at` server-side.
+Authorization errors (`401` / `403`) surface as raw Faraday responses,
+matching `Resource.history`.
+
 ### Re-parenting
 
 `reparent` moves a resource to a new structural parent, binding Atlas's
@@ -227,6 +267,28 @@ 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` /
@@ -246,6 +308,10 @@ array (mirroring `Collection.children`); the two mutations return the list
 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/audit_event.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Session-scoped AuditEvent emit — record an audit event that is **not**
+  # tied to a resource write.
+  #
+  # ## Why this exists
+  #
+  # Every other AuditEvent in Atlas is a side effect of a resource mutation
+  # (`create`, `update`, `tombstone`, …) and is read back per-resource via
+  # {AtlasRb::Resource.history} (`GET /resources/<id>/history`). Some
+  # auditable events have **no resource to hang on**: impersonation sessions.
+  # An admin starting/ending an acting-as or view-as session is a security
+  # event worth recording, but view-as performs no writes at all, and the
+  # session lifecycle lives entirely in the calling application (a cookie),
+  # so there is no resource mutation to attach the event to.
+  #
+  # This binding wraps Atlas's `POST /audit_events` emit endpoint, which
+  # writes an AuditEvent with a **null `resource_id`** (a session-scoped
+  # event). The recorded principals are passed explicitly in the body rather
+  # than inferred from request headers, so the call is self-describing and
+  # does not depend on the ambient {AtlasRb.config} identity being intact at
+  # emit time (it may not be — e.g. an `impersonation_ended` emit fires as
+  # the session is being torn down).
+  #
+  # ## Authorization
+  #
+  # The endpoint is system-token + admin-gated. The request authenticates via
+  # the standard {FaradayHelper#connection} — the `Authorization: Bearer`
+  # token plus a `User: NUID <admin>` header pinned to `actor_nuid` — and
+  # Atlas gates the emit to admin operators. `actor_nuid` is passed
+  # explicitly (rather than left to {AtlasRb.config}.default_nuid) so the
+  # admin gate holds even when the ambient session identity is mid-teardown,
+  # as it is for an `impersonation_ended` emit. The same `actor_nuid` is the
+  # principal recorded on the event.
+  #
+  # @example Recording the start of an acting-as session (from Cerberus)
+  #   AtlasRb::AuditEvent.emit(
+  #     action:            "impersonation_started",
+  #     actor_nuid:        Current.nuid,          # the admin
+  #     on_behalf_of_nuid: target_nuid,           # the impersonated user
+  #     mode:              "acting_as"
+  #   )
+  #
+  # @example Recording the end of a view-as session
+  #   AtlasRb::AuditEvent.emit(
+  #     action:            "impersonation_ended",
+  #     actor_nuid:        admin_nuid,
+  #     on_behalf_of_nuid: target_nuid,
+  #     mode:              "view_as"
+  #   )
+  class AuditEvent
+    extend AtlasRb::FaradayHelper
+
+    # Atlas REST endpoint for the session-scoped emit.
+    # @api private
+    ROUTE = "/audit_events"
+
+    # Emit a session-scoped AuditEvent (one with no resource scope).
+    #
+    # Wraps `POST /audit_events`. The principals and metadata travel in the
+    # JSON body — not in request headers — so the recorded event does not
+    # depend on the ambient {AtlasRb.config} identity. The request still
+    # authenticates as the configured caller (system token + the admin
+    # `User:` header); Atlas admin-gates the endpoint server-side.
+    #
+    # Atlas stamps `occurred_at` server-side, so it is not part of the body.
+    #
+    # Authorization errors (`401` / `403`) are intentionally **not** caught
+    # here — they surface as raw Faraday responses for the calling
+    # application's rescue layer to translate, matching
+    # {AtlasRb::Resource.history}.
+    #
+    # @param action [String] the audit action, e.g. `"impersonation_started"`
+    #   or `"impersonation_ended"`.
+    # @param actor_nuid [String] NUID of the principal performing the action
+    #   (the admin, in the impersonation flow).
+    # @param on_behalf_of_nuid [String, nil] NUID of the attribution target
+    #   (the impersonated user). Omitted from the body when `nil`.
+    # @param mode [String, nil] session mode, e.g. `"acting_as"` or
+    #   `"view_as"`. Omitted from the body when `nil` so the binding can also
+    #   carry future, mode-less session events.
+    # @param payload [Hash] optional free-form metadata to record alongside
+    #   the event. Omitted from the body when empty.
+    # @return [AtlasRb::Mash] the parsed envelope returned by
+    #   `POST /audit_events` (the created event).
+    #
+    # @example
+    #   AtlasRb::AuditEvent.emit(
+    #     action:            "impersonation_started",
+    #     actor_nuid:        "000000001",
+    #     on_behalf_of_nuid: "000000123",
+    #     mode:              "acting_as"
+    #   )
+    def self.emit(action:, actor_nuid:, on_behalf_of_nuid: nil, mode: nil, payload: {})
+      body = {
+        action: action,
+        actor_nuid: actor_nuid,
+        on_behalf_of_nuid: on_behalf_of_nuid,
+        mode: mode,
+        payload: (payload unless payload.nil? || payload.empty?)
+      }.compact
+
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, actor_nuid).post(ROUTE, JSON.dump(body))&.body
+      ))
+    end
+  end
+end

data/lib/atlas_rb/collection.rb

@@ -88,6 +88,12 @@ 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::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")

data/lib/atlas_rb/community.rb

@@ -95,6 +95,11 @@ 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::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")

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

@@ -156,6 +156,12 @@ 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::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")
@@ -439,6 +445,11 @@ 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::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")
@@ -472,6 +483,11 @@ 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::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")

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"
@@ -22,6 +23,7 @@ require_relative "atlas_rb/admin/work"
 require_relative "atlas_rb/admin/collection"
 require_relative "atlas_rb/admin/community"
 require_relative "atlas_rb/system/user"
+require_relative "atlas_rb/audit_event"
 
 # Ruby client for the Atlas API — Northeastern University's institutional
 # digital repository.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.2
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -119,6 +119,7 @@ files:
 - lib/atlas_rb/admin/collection.rb
 - lib/atlas_rb/admin/community.rb
 - lib/atlas_rb/admin/work.rb
+- lib/atlas_rb/audit_event.rb
 - lib/atlas_rb/authentication.rb
 - lib/atlas_rb/blob.rb
 - lib/atlas_rb/collection.rb
@@ -129,6 +130,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