atlas_rb 1.23.0 → 1.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8df0d572649e0456aa2a8e77b436114aa3a91a2fbfe0e6c05ce2a8426dd7c6ff
-  data.tar.gz: e368597905337f62111f4e649eb88a75f5e06c85202ff3dcf5cc3e99d283d948
+  metadata.gz: 2274a10469db90f642ca79a877ab37f9db69c294c55737a28824885249ef6220
+  data.tar.gz: c16a9865aa30a521823c17587e80179e681fab4a9c3747957ab0b943e8591548
 SHA512:
-  metadata.gz: 005ae8ac014dab468bbfb9c5da901c926ba2c746d78c3bedadda431e310d3d21b99f547b91f8e33563784ba45a782cefa4155c7fcfc35a09c11c8e9f43d9fe5b
-  data.tar.gz: 2d35888d562851ec0ad7cd9419faceee619568723f98c1a34e172ac01f33c56e2ae8491eedae2d851067969acfdd02bf6439364d3b2517448cfadb0a13436fa9
+  metadata.gz: fbf77b86e3b695401be85f2f913d4c71820ae2e1c2078884d6b13038d46cca749aaafaf7ef588e9f742db01e8b53b5375734893572430a9ccc7adbfed5444e50
+  data.tar.gz: baf502af151908b4da14e4e51597d60f7c88b90d7659deac2731bd44dc317376dce11bbb8e2c2e9f3d7fbfc33adc0e8b6572124769651e7917bfb51eaaac76b5

data/.version

@@ -1 +1 @@
-1.23.0
+1.25.0

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 1.25.0
+
+These bindings need Atlas 0.6.214 or later.
+
+### Added — `q:` on `Person.list`, and `Person.page`
+
+```ruby
+AtlasRb::Person.list(q: "gasp", nuid: admin_nuid)
+result = AtlasRb::Person.page(q: "doe", page: 2, per_page: 50, nuid: admin_nuid)
+result.pagination["count"] # => matches across every page
+```
+
+`q:` searches the People registry. Atlas returns the Persons whose
+`display_name` contains the fragment, whose NUID starts with it, or whose
+account email contains it, all case-insensitive and ordered by `display_name`.
+The search is admin-only. Anyone else gets a `403`, which raises
+`ResourceError`.
+
+`Person.page` takes the same arguments as `Person.list` and returns
+`{ "people" => [...], "pagination" => {...} }`, so a caller can show a page
+count and a total. With `q:`, the block counts the matches. `Person.list`
+still returns the rows alone.
+
+### Documented — `display_name` on the user directory
+
+`User.search`, `User.resolve` and `User.find_by_nuid` entries now carry
+`display_name`: the librarian-curated Person name for the NUID, or `nil` when
+there is no Person. `User.search` also matches on it, and Atlas orders entries
+by `display_name` when set, else `name`. No code changed: the gem already
+passes the whole entry through.
+
+## 1.24.0
+
+These bindings need Atlas 0.6.213 or later.
+
+### Added — `reason:` on `Resource.tombstone`
+
+```ruby
+AtlasRb::Resource.tombstone(work_id, reason: "Removed from view by legal order", nuid: admin_nuid)
+```
+
+The library's withdrawal policy requires a note saying why an object was
+removed, and fixes its wording. `reason:` must be one of the policy's five
+notes, word for word. Atlas answers `422` with `invalid_reason` for any other
+value, and the call returns that raw response as before. The note carries no
+date: read `tombstoned_at` for that.
+
+Community, Collection, Work and FileSet reads return the note as
+`tombstone_reason`, including the `410` body of a tombstoned read. A restore
+clears it. Omit the keyword to tombstone with no note, as before.
+
 ## 1.23.0
 
 These bindings need Atlas 0.6.212 or later.

data/Gemfile.lock

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

data/README.md

@@ -543,7 +543,7 @@ write. The whole surface:
 | `Resource.set_permissions(id, acl)` | `PATCH /resources/{id}/permissions` |
 | `Resource.set_thumbnails(id, thumbnail:, thumbnail_2x:, preview:)` | `PATCH /resources/{id}/thumbnails` |
 | `Resource.reparent(id, parent_id)` | `PATCH /resources/{id}/parent` |
-| `Resource.tombstone(id)` | `POST /resources/{id}/tombstone` |
+| `Resource.tombstone(id, reason:)` | `POST /resources/{id}/tombstone` |
 | `Admin::Resource.restore(id)` | `POST /resources/{id}/restore` |
 | `Admin::Resource.destroy(id, confirm: :i_understand)` | `DELETE /resources/{id}` |
 

data/lib/atlas_rb/person.rb

@@ -20,8 +20,8 @@ module AtlasRb
   # keep their usual gem meaning (the acting principal). NUID stays the key only
   # for {.create} (one Person per NUID — and there `nuid:` is the *new person's*
   # NUID, acting principal coming from the ambient `AtlasRb.config.default_nuid`)
-  # and {.resolve} (the server-side name-resolution batch). {.list} is the
-  # NOID-keyed People-index source.
+  # and {.resolve} (the server-side name-resolution batch). {.list} and
+  # {.page} are the NOID-keyed People-index source.
   #
   # Create / update / affiliation writes are :system + admin on the server; a
   # non-privileged caller gets a 403.
@@ -50,6 +50,14 @@ module AtlasRb
     # through atlas_rb without
     # routing People through the catalog/Solr or exposing a NUID publicly.
     #
+    # Pass `q:` to search: Atlas returns the Persons whose `display_name`
+    # contains the fragment, whose NUID starts with it, or whose account email
+    # contains it, all case-insensitive and ordered by `display_name`. The
+    # search is admin-only; anyone else gets a `403`. Use {.page} for the
+    # match count.
+    #
+    # @param q [String, nil] typeahead fragment (admin only). Blank lists
+    #   everyone.
     # @param page [Integer, nil] 1-based page (server default when nil).
     # @param per_page [Integer, nil] page size (server default when nil; capped
     #   server-side).
@@ -62,10 +70,36 @@ module AtlasRb
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
     #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
     #   Atlas's status and body so the failure is attributable at the boundary.
-    def self.list(page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
-      params = { page: page, per_page: per_page }.compact
+    # @example Admin typeahead
+    #   AtlasRb::Person.list(q: "gasp", nuid: admin_nuid)
+    def self.list(q: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+      self.page(q: q, page: page, per_page: per_page, nuid: nuid, on_behalf_of: on_behalf_of)&.people
+    end
+
+    # One page of the People index with its pagination block — {.list} with
+    # the counts kept, for a consumer that shows "page 2 of 7" or a total.
+    # With `q:`, the block counts the matches, not the whole registry.
+    #
+    # @param q [String, nil] typeahead fragment (admin only), as on {.list}.
+    # @param page [Integer, nil] 1-based page (server default when nil).
+    # @param per_page [Integer, nil] page size (server default when nil; capped
+    #   server-side).
+    # @param nuid [String, nil] acting principal.
+    # @param on_behalf_of [String, nil] acting-as target.
+    # @return [AtlasRb::Mash, nil] `{ "people" => [...], "pagination" => {...} }`,
+    #   each `"people"` entry in the {.list} row shape.
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
+    # @example
+    #   result = AtlasRb::Person.page(q: "doe", page: 2, per_page: 50, nuid: admin_nuid)
+    #   result.pagination["count"] # => matches across every page (Hash#count shadows .count)
+    def self.page(q: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+      params = { q: q, page: page, per_page: per_page }.compact
       read_body(connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE)) do |body|
-        body["people"].map { |entry| AtlasRb::Mash.new(entry) }
+        AtlasRb::Mash.new(body)
       end
     end
 

data/lib/atlas_rb/resource_writes.rb

@@ -144,14 +144,23 @@ module AtlasRb
     # {Work.file_sets}. Atlas refuses a FileSet from anyone outside the admin and
     # devolved-admin tiers with `403`, even a user who can edit the Work.
     #
+    # `reason:` records why the resource was removed (Atlas 0.6.213 or later).
+    # It must be one of the removal notes the library's withdrawal policy
+    # allows, word for word; Atlas answers `422` with `invalid_reason` for any
+    # other value. The note carries no date: read `tombstoned_at` for that.
+    # The resource returns it as `tombstone_reason`, and a restore clears it.
+    #
     # @param id [String] the resource's NOID.
+    # @param reason [String, nil] one of the policy's removal notes, or `nil`
+    #   for none.
     # @param nuid [String, nil] the acting user's NUID, stamped on the resource
     #   as `tombstoned_by`.
     # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
     #   header.
     # @return [Faraday::Response] the raw response — read `status` yourself.
-    def self.tombstone(id, nuid: nil, on_behalf_of: nil)
-      connection({}, nuid, on_behalf_of: on_behalf_of).post('/resources/' + id + '/tombstone')
+    def self.tombstone(id, reason: nil, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of)
+        .post('/resources/' + id + '/tombstone', { reason: reason }.compact.to_json)
     end
 
     # Atlas answers a write with the resource under its type key, matching what

data/lib/atlas_rb/user.rb

@@ -14,7 +14,9 @@ module AtlasRb
   # logged-in-user capabilities.
   #
   # The directory lookups enforce minimal disclosure: every entry carries
-  # `nuid` + `name` only (no email, role, or groups), and rows with role
+  # `nuid`, `name` and `display_name` only (no email, role, or groups). `name`
+  # is the SSO-fed account name; `display_name` is the librarian-curated Person
+  # name for that NUID, or `nil` when the NUID has no Person. Rows with role
   # `anonymous`, `guest`, or `system` are never returned. The account methods
   # ({.accounts} / {.set_preferred}) *do* disclose email/groups/affiliation, so
   # Atlas limits them to the person themselves (matching NUID), an admin, or the
@@ -30,16 +32,18 @@ module AtlasRb
 
     # Typeahead search of the user directory.
     #
-    # Case-insensitive match on name, prefix match on NUID (so typing a
-    # known NUID works too). Atlas caps the result (10 entries) and orders
-    # it by name; a blank query resolves to an empty list.
+    # Case-insensitive match on the account `name` or the curated
+    # `display_name`, prefix match on NUID (so typing a known NUID works too).
+    # Atlas caps the result (10 entries) and orders it by the name an entry
+    # shows — `display_name` when set, else `name`; a blank query resolves to
+    # an empty list.
     #
     # @param query [String] name fragment or NUID prefix to match.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
     #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
     #   path it is ignored (identity lives in the token).
     # @return [Array<AtlasRb::Mash>, nil] matching directory entries, each
-    #   carrying `nuid` and `name`.
+    #   carrying `nuid`, `name` and `display_name` (`nil` without a Person).
     #
     #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
     #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
@@ -48,7 +52,7 @@ module AtlasRb
     #   Atlas's status and body so the failure is attributable at the boundary.
     # @example Recipient typeahead
     #   AtlasRb::User.search("jan", nuid: "000000002")
-    #   # => [{ "nuid" => "001234567", "name" => "Doe, Jane" }, ...]
+    #   # => [{ "nuid" => "001234567", "name" => "Doe, Jane", "display_name" => "Jane Doe" }, ...]
     def self.search(query, nuid: nil)
       read_body(connection({ q: query }, nuid).get(ROUTE)) do |body|
         body.map { |entry| AtlasRb::Mash.new(entry) }
@@ -62,7 +66,8 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
     #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
     #   path it is ignored (identity lives in the token).
-    # @return [AtlasRb::Mash, nil] the `nuid` + `name` entry, or `nil` when
+    # @return [AtlasRb::Mash, nil] the `nuid`, `name` and `display_name`
+    #   entry (`display_name` is `nil` without a Person), or `nil` when
     #   Atlas reports the NUID as absent (unknown, or held by an excluded
     #   role — the two are indistinguishable on the wire by design).
     #
@@ -71,7 +76,7 @@ module AtlasRb
     #   Atlas's status and body so the failure is attributable at the boundary.
     # @example Sender-name display
     #   AtlasRb::User.find_by_nuid("001234567")
-    #   # => { "nuid" => "001234567", "name" => "Doe, Jane" }
+    #   # => { "nuid" => "001234567", "name" => "Doe, Jane", "display_name" => "Jane Doe" }
     def self.find_by_nuid(target_nuid, nuid: nil)
       read_body(connection({}, nuid).get("#{ROUTE}/by_nuid/#{target_nuid}")) do |body|
         AtlasRb::Mash.new(body)
@@ -88,8 +93,8 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
     #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
     #   path it is ignored (identity lives in the token).
-    # @return [Array<AtlasRb::Mash>, nil] resolved entries, each carrying `nuid`
-    #   and `name`, ordered by name.
+    # @return [Array<AtlasRb::Mash>, nil] resolved entries, each carrying `nuid`,
+    #   `name` and `display_name`, ordered by the name an entry shows.
     #
     #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
     #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.23.0
+  version: 1.25.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday