atlas_rb 1.3.3 → 1.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a36183e05b8c32292a5b0201db841ad961bcffcd51d546c0203d591cfbcfefce
-  data.tar.gz: 81d85278032e45d983dd5007b25ca3688cea9f23e3c8b5ce94a04727ef5d9497
+  metadata.gz: 3f1d65e6631474391c3971b939e6394049b6b5f4198a14ffd55bd5e9c51d2bbf
+  data.tar.gz: d3371babc6a6aca8141a3692b399fd9989d5f8f29341ac376e3d1bed5850d0f4
 SHA512:
-  metadata.gz: f4866c59b9c8a8321a0cc440139a5382ac03129e29e0130447da6ade868059dd484bed4029de404a61292058a0f32407266b20f707aa8757e65112d231c57374
-  data.tar.gz: ff821a348a98120bfe12da5f0e0de0594810ab93848f3db20e549951eabb205b330df5954d2e375836dab316d50178e80545cd1b69133165aee46567600f02b7
+  metadata.gz: f9450d1ed3d4c77708b619c4c48686c35606cee0d8633d9fcd448440127398b613f2d664fb672bbfaccb0bf44143ccbf8731aac29e3d967f09b56177ab7517ae
+  data.tar.gz: acb806ac1e60026594bac52eb124415439daa77ceb219cc5465dc961d16ab78b2dc481fe64256a5cbf109e67347170ac15e2f484fb7d19ea248b69406a950834

data/.version

@@ -1 +1 @@
-1.3.3
+1.3.4

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 1.3.4
+
+### Added — Compilation (DRS "Sets") bindings
+
+Bindings for Atlas's Compilation surface (Atlas v0.6.57) — personal,
+curated, recipe-based groupings of Works and Collections, the persistence
+behind the Cerberus Sets UI.
+
+```ruby
+set = AtlasRb::Compilation.create("Course readings", nuid: "000000002")
+
+# Recipe lines — each mutation returns the full updated compilation
+AtlasRb::Compilation.add_included_collection(set["id"], "col-456", nuid: "000000002")
+AtlasRb::Compilation.add_included_work(set["id"], "w-789", nuid: "000000002")
+AtlasRb::Compilation.add_exclusion(set["id"], "w-790", nuid: "000000002")   # set aside
+AtlasRb::Compilation.remove_exclusion(set["id"], "w-790", nuid: "000000002") # put back
+
+# Make public, resolve the recipe
+AtlasRb::Compilation.update(set["id"],
+                            permissions: { read: ["public"], edit: [], edit_users: [] },
+                            nuid: "000000002")
+AtlasRb::Compilation.contents(set["id"]).contents.map(&:noid)
+```
+
+- `Compilation.create / find / update / destroy / list` — owner-scoped
+  CRUD. The depositor is stamped server-side from the acting NUID and is
+  immutable; `list(owner:)` (cross-owner) is admin-only. `update` takes
+  `title:` / `description:` / `permissions:` (the ACL hash replaces all
+  three grant lists; ACL changes are audited server-side, no-ops
+  suppressed).
+- Six membership calls (`add/remove_included_collection`,
+  `add/remove_included_work`, `add/remove_exclusion`) — each returns the
+  updated `"compilation"` object so chip counts refresh without a
+  follow-up `find`. Adds and removes are idempotent; the type rules
+  (Works and Collections only, no Communities) are enforced by Atlas.
+- `Compilation.contents` wraps `GET /compilations/<id>/contents` — the
+  recipe resolved to `find_many`-style digests with Solr-side pagination
+  (`{ total, page, per_page, pages }`). Included for completeness; CERES
+  hits the endpoint directly and Cerberus resolves contents via its own
+  Blacklight query.
+- New `AtlasRb::CompilationError` (422 — blank title, wrong-type or
+  unknown membership noid), the Compilation sibling of
+  `LinkedMemberError`. `AtlasRb::ForbiddenError` now also covers 403s on
+  the Compilation surface, so a non-grantee reading a private Set gets a
+  typed refusal instead of a swallowed `nil`.
+
 ## 1.3.3
 
 ### Added — multipage bindings (FileSet ordinality)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.3.3)
+    atlas_rb (1.3.4)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -23,7 +23,7 @@ GEM
       net-http (~> 0.5)
     hashie (5.1.0)
       logger
-    json (2.19.8)
+    json (2.19.9)
     logger (1.7.0)
     multipart-post (2.4.1)
     net-http (0.9.1)

data/lib/atlas_rb/compilation.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # A Compilation (DRS "Set") — a personal, curated, recipe-based grouping
+  # of {Work}s and {Collection}s.
+  #
+  # The recipe is three noid lists: included collections (resolved
+  # transitively — the collection plus everything beneath it), individually
+  # included works, and excluded works ("set-asides", subtracted from the
+  # resolved union). Atlas resolves the recipe at read time via
+  # {.contents}; nothing is materialized.
+  #
+  # Compilations are Atlas-side ActiveRecord (ephemeral curation, not
+  # repository content), but carry a minted NOID as their public id — so
+  # ids here look exactly like every other resource's. There is no `/mods`,
+  # thumbnail, or tombstone surface to bind. Membership rules (Works and
+  # Collections only, no Communities) are enforced server-side; a rejected
+  # add surfaces as {AtlasRb::CompilationError} (422), an authorization
+  # refusal as {AtlasRb::ForbiddenError} (403).
+  #
+  # See also: {Work.add_linked_member} — the membership add/remove pairs
+  # here mirror that precedent.
+  class Compilation < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
+    ROUTE = "/compilations/"
+
+    # Fetch a single Compilation by ID.
+    #
+    # Visibility is per-row: the owner, holders of an explicit read/edit
+    # grant, and (for public Sets) anyone — a private Set read by a
+    # non-grantee raises {AtlasRb::ForbiddenError}.
+    #
+    # @param id [String] the Compilation ID (NOID).
+    # @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 `"compilation"` object, already unwrapped — `id`,
+    #   `title`, `description`, `depositor`, the three recipe arrays
+    #   (`included_collections`, `included_works`, `excluded_works`), the
+    #   ACL arrays, and timestamps.
+    # @raise [AtlasRb::ForbiddenError] if the caller may not read this Set.
+    #
+    # @example
+    #   AtlasRb::Compilation.find("c-123", nuid: "000000002")
+    #   # => { "id" => "c-123", "title" => "Course readings", ... }
+    def self.find(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id)&.body
+      ))["compilation"]
+    end
+
+    # List Compilations, owner-scoped and paginated (newest first).
+    #
+    # Defaults to the acting user's own Sets. Pass `owner:` to list another
+    # user's — that is admin-only and raises {AtlasRb::ForbiddenError} for
+    # anyone else. There is no public browse surface.
+    #
+    # @param owner [String, nil] NUID whose Sets to list (admin-only when it
+    #   isn't the acting user). Omit for "my Sets".
+    # @param page [Integer, nil] 1-indexed page number.
+    # @param per_page [Integer, nil] page size override.
+    # @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 [AtlasRb::Mash] `{ "compilations" => [...], "pagination" => {...} }`.
+    #   Each entry wraps the same `"compilation"` object {.find} returns.
+    # @raise [AtlasRb::ForbiddenError] on a cross-owner listing without admin.
+    #
+    # @example My Sets
+    #   AtlasRb::Compilation.list(nuid: "000000002")
+    #
+    # @example Another user's Sets (admin)
+    #   AtlasRb::Compilation.list(owner: "000000002", nuid: "000000004")
+    def self.list(owner: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+      params = {}
+      params[:owner]    = owner    if owner
+      params[:page]     = page     if page
+      params[:per_page] = per_page if per_page
+      AtlasRb::Mash.new(JSON.parse(
+        connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE)&.body
+      ))
+    end
+
+    # Create a Compilation owned by the acting user.
+    #
+    # The depositor (owner) is stamped server-side from the authenticated
+    # NUID — it is not a parameter and is immutable post-create. New Sets
+    # are born private: empty ACLs, no staff default.
+    #
+    # @param title [String] the Set's title (required; blank is a 422).
+    # @param description [String, nil] optional free-text description.
+    # @param nuid [String, nil] the acting user's NUID, forwarded as the
+    #   `User:` header — the created Set's owner. Required for
+    #   cerberus-token requests.
+    # @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 created `"compilation"` object, already unwrapped.
+    # @raise [AtlasRb::CompilationError] if Atlas rejects the create (422 —
+    #   e.g. a blank title).
+    # @raise [AtlasRb::ForbiddenError] if the caller may not create Sets
+    #   (guests cannot).
+    #
+    # @example
+    #   AtlasRb::Compilation.create("Course readings",
+    #                               description: "HIST 1101",
+    #                               nuid: "000000002")
+    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
+      ))["compilation"]
+    end
+
+    # Update a Compilation's title / description / ACL.
+    #
+    # Only the keys you pass are written. The `permissions:` hash replaces
+    # all three grant lists at once (`read:` / `edit:` group lists plus
+    # `edit_users:` NUIDs); the depositor is never writable. Server-side,
+    # an ACL change emits a `permissions` audit event (no-op ACL writes are
+    # suppressed); recipe membership has its own calls and emits nothing.
+    #
+    # @param id [String] the Compilation ID.
+    # @param title [String, nil] new title.
+    # @param description [String, nil] new description.
+    # @param permissions [Hash, nil] ACL replacement, e.g.
+    #   `{ read: ["public"], edit: [], edit_users: ["000000003"] }`.
+    # @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 `"compilation"` object, already unwrapped.
+    # @raise [AtlasRb::CompilationError] if Atlas rejects the update (422).
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights
+    #   (owner / explicit grant / admin).
+    #
+    # @example Rename
+    #   AtlasRb::Compilation.update("c-123", title: "Renamed", nuid: "000000002")
+    #
+    # @example Make public (the CERES case)
+    #   AtlasRb::Compilation.update("c-123",
+    #                               permissions: { read: ["public"], edit: [], edit_users: [] },
+    #                               nuid: "000000002")
+    def self.update(id, title: nil, description: nil, permissions: nil, nuid: nil, on_behalf_of: nil)
+      params = {}
+      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
+      ))["compilation"]
+    end
+
+    # Destroy a Compilation.
+    #
+    # Owner (or edit-grantee / admin) only. The recipe rows go with it; the
+    # Works and Collections it referenced are untouched — a Set is a view,
+    # not a container.
+    #
+    # @param id [String] the Compilation 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 [Faraday::Response] the raw response. Status `204` on success.
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    #
+    # @example
+    #   AtlasRb::Compilation.destroy("c-123", nuid: "000000002")
+    def self.destroy(id, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
+    end
+
+    # Add an include-collection recipe line: everything under the
+    # Collection (transitively) joins the Set's resolved contents.
+    #
+    # Idempotent — re-adding an included collection is a no-op. The noid
+    # must resolve to a Collection: Communities and unknown ids are
+    # rejected server-side as a 422.
+    #
+    # @param id [String] the Compilation ID.
+    # @param collection_id [String] the Collection NOID to include.
+    # @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 `"compilation"` object — the response is
+    #   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.
+    #
+    # @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(
+        connection({ collection_id: collection_id }, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + id + '/included_collections')&.body
+      ))["compilation"]
+    end
+
+    # Remove an include-collection recipe line.
+    #
+    # Idempotent — removing a collection that is not in the recipe is a
+    # 200 no-op (nothing for a client to recover from).
+    #
+    # @param id [String] the Compilation ID.
+    # @param collection_id [String] the Collection NOID 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 [Hash] the updated `"compilation"` object.
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    #
+    # @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(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + id + '/included_collections/' + collection_id)&.body
+      ))["compilation"]
+    end
+
+    # Add an include-work recipe line: one Work, included individually.
+    #
+    # Idempotent. The noid must resolve to a Work; anything else is a 422.
+    #
+    # @param id [String] the Compilation ID.
+    # @param work_id [String] the Work NOID to include.
+    # @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 `"compilation"` object.
+    # @raise [AtlasRb::CompilationError] if the noid is not a Work (422).
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    #
+    # @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(
+        connection({ work_id: work_id }, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + id + '/included_works')&.body
+      ))["compilation"]
+    end
+
+    # Remove an include-work recipe line. Idempotent.
+    #
+    # @param id [String] the Compilation ID.
+    # @param work_id [String] the Work NOID 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 [Hash] the updated `"compilation"` object.
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    #
+    # @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(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + id + '/included_works/' + work_id)&.body
+      ))["compilation"]
+    end
+
+    # Set a Work aside: subtract it from the Set's resolved contents even
+    # though an included collection covers it.
+    #
+    # Idempotent. The noid must resolve to a Work. Setting aside a Work
+    # that no inclusion currently covers is legal — the recipe lines are
+    # independent; the subtraction just matches nothing.
+    #
+    # @param id [String] the Compilation ID.
+    # @param work_id [String] the Work NOID to set aside.
+    # @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 `"compilation"` object.
+    # @raise [AtlasRb::CompilationError] if the noid is not a Work (422).
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    #
+    # @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(
+        connection({ work_id: work_id }, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + id + '/exclusions')&.body
+      ))["compilation"]
+    end
+
+    # Put a set-aside Work back. Idempotent.
+    #
+    # @param id [String] the Compilation ID.
+    # @param work_id [String] the Work NOID to restore to the resolved set.
+    # @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 `"compilation"` object.
+    # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    #
+    # @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(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + id + '/exclusions/' + work_id)&.body
+      ))["compilation"]
+    end
+
+    # Resolve a Compilation's recipe into the Works it currently denotes.
+    #
+    # Wraps `GET /compilations/<id>/contents` — included for completeness;
+    # the endpoint's primary consumer is CERES (which calls Atlas directly),
+    # and Cerberus resolves Set contents via its own Blacklight query.
+    # Results are gated to what the caller may discover (public + the
+    # caller's groups; admins see everything; tombstoned works excluded) —
+    # the same semantics as Cerberus gated discovery.
+    #
+    # @param id [String] the Compilation ID.
+    # @param page [Integer, nil] 1-indexed page number (default 1).
+    # @param per_page [Integer, nil] page size (default 25, capped at 100).
+    # @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 [AtlasRb::Mash] `{ "contents" => [...], "pagination" =>
+    #   { "total", "page", "per_page", "pages" } }`. Each entry is a
+    #   lightweight digest in the {Resource.find_many} vocabulary —
+    #   `id` / `noid` / `klass` / `title` / `thumbnail`.
+    # @raise [AtlasRb::ForbiddenError] if the caller may not read this Set.
+    #
+    # @example
+    #   page = AtlasRb::Compilation.contents("c-123", nuid: "000000002")
+    #   page.contents.map(&:noid)
+    #   page.pagination.total
+    def self.contents(id, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+      params = {}
+      params[:page]     = page     if page
+      params[:per_page] = per_page if per_page
+      AtlasRb::Mash.new(JSON.parse(
+        connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/contents')&.body
+      ))
+    end
+  end
+end

data/lib/atlas_rb/errors.rb

@@ -101,14 +101,48 @@ module AtlasRb
     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.
+  # Raised when Atlas rejects a Compilation (Set) write with a `422`
+  # carrying a machine-readable `error` discriminator — a blank title on
+  # create/update (`invalid_record`), or a membership add whose noid does
+  # not resolve to the expected type (a Community where a Collection is
+  # required, an unknown id, a Collection where a Work is required).
   #
-  # @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.
+  # The Compilation sibling of {LinkedMemberError}; same shape, same
+  # rationale (the binding's `["compilation"]` unwrap would otherwise
+  # discard the envelope on a non-2xx).
+  #
+  #   rescue AtlasRb::CompilationError => e
+  #     flash.now[:alert] = e.message
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403).
+  class CompilationError < Error
+    # @return [String, nil] the machine-readable error code from the
+    #   envelope (currently `"invalid_record"`).
+    attr_reader :code
+
+    # @return [String, nil] the rejected resource's ID, from the envelope
+    #   (may be nil — validation envelopes don't always carry one).
+    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, linked-member, or Compilation
+  # request with an HTTP `403`, whose envelope is
+  # `{ "error", "action", "subject" }`. Lets callers distinguish "you may
+  # not do this" from a structural rejection ({ReparentError} /
+  # {LinkedMemberError} / {CompilationError}) or a not-found.
+  #
+  # @note Scoped to the re-parent / linked-member write paths and the
+  #   Compilation surface — `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

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -15,30 +15,34 @@ module AtlasRb
     # {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.
+    # (`.../parent`) and linked-member (`.../linked_members...`) write paths
+    # and the Compilation surface (`/compilations...`), 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`)
+    # - `403` (any covered path) → {AtlasRb::ForbiddenError} (`error`/`action`/`subject`)
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
+    # - `422` on `/compilations...` → {AtlasRb::CompilationError}
     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::ForbiddenError] on a 403 to a covered path.
       # @raise [AtlasRb::ReparentError] on a 422 to a re-parent path.
       # @raise [AtlasRb::LinkedMemberError] on a 422 to a linked-member path.
+      # @raise [AtlasRb::CompilationError] on a 422 to a Compilation 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
+        path        = env.url&.path.to_s
+        reparent    = path.end_with?("/parent")
+        linked      = path.include?("/linked_members")
+        compilation = path.start_with?("/compilations")
+        return unless reparent || linked || compilation
 
         body = parse_json(env.body)
         return unless body.is_a?(Hash) && body["error"]
@@ -56,12 +60,18 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
-        else
+        elsif linked
           raise AtlasRb::LinkedMemberError.new(
             body["message"] || "Atlas rejected the linked-member write",
             code: body["error"],
             resource_id: body["resource_id"]
           )
+        else
+          raise AtlasRb::CompilationError.new(
+            body["message"] || "Atlas rejected the compilation write",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
         end
       end
 

data/lib/atlas_rb.rb

@@ -18,6 +18,7 @@ require_relative "atlas_rb/work"
 require_relative "atlas_rb/file_set"
 require_relative "atlas_rb/blob"
 require_relative "atlas_rb/delegate"
+require_relative "atlas_rb/compilation"
 require_relative "atlas_rb/user"
 require_relative "atlas_rb/admin"
 require_relative "atlas_rb/admin/work"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.3.4
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -124,6 +124,7 @@ files:
 - lib/atlas_rb/blob.rb
 - lib/atlas_rb/collection.rb
 - lib/atlas_rb/community.rb
+- lib/atlas_rb/compilation.rb
 - lib/atlas_rb/configuration.rb
 - lib/atlas_rb/delegate.rb
 - lib/atlas_rb/errors.rb