atlas_rb 1.3.1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0947add262eb2b9b4ab993f16c2c379877455e9ece3bca04f41a61bfddf79ee3'
-  data.tar.gz: d239887dfaac21e78a7118503d4ed8ab79b12b3aa174ee18f5a8f31f253ca866
+  metadata.gz: 54691ff87af06d611d63a27333682abfd284c67d6990d0c8400ea2b9b80adb92
+  data.tar.gz: 7d3119d56763694dad36c69ded4cbf975af62d6eb070baf36c0df02f422259f1
 SHA512:
-  metadata.gz: b4d59334c7730d11f9f7779b1cbef5c7cef49ce4b1726257a9c8590f258ab4c8aac80ffffa10c1111a38b4d98b95c7b36e824eab925aff4aae1ff87336f7e37e
-  data.tar.gz: a5c0484e6d4204758dc1eee8e2ca6086a289e19e250a404fbdffc4af65eaa7864f2da7f93a9586d4d84776c76b33dbdebb5147ae4d728baed51110864c347e30
+  metadata.gz: 86dc095d2be7db4fdefe997cc6b33fabd0d3c1826804b0521fda48b06d17ec4cd3fde492a3926114965d4354823f55043ea7559d4ce82dcc06a288b7fa8afecd
+  data.tar.gz: c31c2bea0442ec082ede4a2328c6f7471eb02151021c6e08620b4fef5b254996ad424816493e8d955e202f5c5444e800393b85064dc9feb58a61cbaf126a9e08

data/.version

@@ -1 +1 @@
-1.3.1
+1.3.2

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.3.2
+
+### Added — `AtlasRb::User` (read-only user directory)
+
+A user-context binding for Atlas's user directory endpoints — recipient
+typeahead and NUID → name resolution for any surface that today renders a
+bare NUID (User Inbox sender display, Audit History chips, Rights history).
+
+```ruby
+AtlasRb::User.search("jan", nuid: "000000002")
+# => [{ "nuid" => "001234567", "name" => "Doe, Jane" }, ...]
+
+AtlasRb::User.find_by_nuid("001234567")
+# => { "nuid" => "001234567", "name" => "Doe, Jane" }
+
+AtlasRb::User.resolve(["001234567", "007654321"])
+# => one entry per resolvable NUID, ordered by name
+```
+
+- `search` is the typeahead: case-insensitive match on name, prefix match
+  on NUID. Atlas caps the list at 10 and orders by name.
+- `resolve` batch-resolves up to 100 NUIDs in one round-trip (an inbox
+  page of senders in one call). Unresolvable NUIDs are dropped — callers
+  index by `nuid`.
+- `find_by_nuid` resolves a single NUID; returns `nil` on Atlas's 404
+  (unknown NUID, or one held by an excluded role — indistinguishable on
+  the wire by design).
+- Minimal disclosure is enforced server-side: entries carry `nuid` +
+  `name` only, and `anonymous` / `guest` / `system` rows never appear.
+- Deliberately **not** under `AtlasRb::System` — this is an acting-user
+  capability on the ordinary `ATLAS_TOKEN` + `User:` header pairing; the
+  `System` namespace stays reserved for system-token calls.
+
 ## 1.3.1
 
 ### Added — `AtlasRb::Resource.mods_versions` / `mods_version` (MODS version history)

data/Gemfile.lock

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

data/lib/atlas_rb/user.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Read-only user directory lookups — typeahead search and NUID → name
+  # resolution.
+  #
+  # This is a **user-context** binding: calls authenticate as the acting
+  # user via the standard `ATLAS_TOKEN` + `User:` header pairing, like every
+  # other top-level class. It is deliberately *not* part of
+  # {AtlasRb::System} — that namespace is structurally reserved for
+  # system-token calls ({System::User.find_or_create}), and directory
+  # lookups are an ordinary logged-in-user capability.
+  #
+  # Atlas enforces minimal disclosure: every entry carries `nuid` + `name`
+  # only (no email, role, or groups), and rows with role `anonymous`,
+  # `guest`, or `system` are never returned. Per the layering principle the
+  # gem adds nothing on top — no caching, no name parsing, no result
+  # shaping; presentation belongs to the host application.
+  class User
+    extend AtlasRb::FaradayHelper
+
+    # Atlas REST endpoint prefix for the user directory.
+    # @api private
+    ROUTE = "/users"
+
+    # 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.
+    #
+    # @param query [String] name fragment or NUID prefix to match.
+    # @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.
+    # @return [Array<AtlasRb::Mash>] matching directory entries, each
+    #   carrying `nuid` and `name`.
+    #
+    # @example Recipient typeahead
+    #   AtlasRb::User.search("jan", nuid: "000000002")
+    #   # => [{ "nuid" => "001234567", "name" => "Doe, Jane" }, ...]
+    def self.search(query, nuid: nil)
+      JSON.parse(
+        connection({ q: query }, nuid).get(ROUTE)&.body
+      ).map { |entry| AtlasRb::Mash.new(entry) }
+    end
+
+    # Resolve a single NUID to a directory entry.
+    #
+    # @param target_nuid [String] the NUID being looked up — the *subject*
+    #   of the call, distinct from the acting `nuid:` kwarg.
+    # @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.
+    # @return [AtlasRb::Mash, nil] the `nuid` + `name` entry, 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).
+    #
+    # @example Sender-name display
+    #   AtlasRb::User.find_by_nuid("001234567")
+    #   # => { "nuid" => "001234567", "name" => "Doe, Jane" }
+    def self.find_by_nuid(target_nuid, nuid: nil)
+      response = connection({}, nuid).get("#{ROUTE}/by_nuid/#{target_nuid}")
+      return nil if response.status == 404
+
+      AtlasRb::Mash.new(JSON.parse(response.body))
+    end
+
+    # Batch-resolve a set of NUIDs to directory entries in one call.
+    #
+    # Same response shape as {.search}. Unresolvable NUIDs (unknown or
+    # excluded-role) are dropped, so the result may be shorter than the
+    # input — callers index by `nuid`. Atlas caps the batch at 100.
+    #
+    # @param nuids [Array<String>, String] the NUIDs to resolve.
+    # @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.
+    # @return [Array<AtlasRb::Mash>] resolved entries, each carrying `nuid`
+    #   and `name`, ordered by name.
+    #
+    # @example Resolve an inbox page of senders in one round-trip
+    #   senders = AtlasRb::User.resolve(["001234567", "007654321"])
+    #   by_nuid = senders.index_by { |entry| entry["nuid"] }
+    def self.resolve(nuids, nuid: nil)
+      JSON.parse(
+        connection({ nuids: Array(nuids).join(",") }, nuid).get(ROUTE)&.body
+      ).map { |entry| AtlasRb::Mash.new(entry) }
+    end
+  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/user"
 require_relative "atlas_rb/admin"
 require_relative "atlas_rb/admin/work"
 require_relative "atlas_rb/admin/collection"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.2
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-07 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -134,6 +134,7 @@ files:
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/system/user.rb
+- lib/atlas_rb/user.rb
 - lib/atlas_rb/version.rb
 - lib/atlas_rb/work.rb
 - sig/atlas_rb.rbs