atlas_rb 1.3.0 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d65fea7329731bd0fa0a397a19f5764a05e88397c522baf28721e4a08282e2d3
-  data.tar.gz: 7b2db70c9e1a7d9e8fad5194bcb045baeed562561b1c36a60c174e2c1fc5d0aa
+  metadata.gz: 54691ff87af06d611d63a27333682abfd284c67d6990d0c8400ea2b9b80adb92
+  data.tar.gz: 7d3119d56763694dad36c69ded4cbf975af62d6eb070baf36c0df02f422259f1
 SHA512:
-  metadata.gz: 335c7d4bd02d6bdb6f297cf86857c042d515680fb8e36991d98a7a7bf4fdd1e52470f0dda4b40605f79d0618c7260a64f2125af2a3100a693c920b51ebc1c1f5
-  data.tar.gz: ce1bc4b16ce482975af0785138574aa6b42fc2cc05ddfee777adbef2834b733bdb93df5390cfc4e9a5012af4b9483cf5676f7213edc8e79afc0fd886d2b84545
+  metadata.gz: 86dc095d2be7db4fdefe997cc6b33fabd0d3c1826804b0521fda48b06d17ec4cd3fde492a3926114965d4354823f55043ea7559d4ce82dcc06a288b7fa8afecd
+  data.tar.gz: c31c2bea0442ec082ede4a2328c6f7471eb02151021c6e08620b4fef5b254996ad424816493e8d955e202f5c5444e800393b85064dc9feb58a61cbaf126a9e08

data/.version

@@ -1 +1 @@
-1.3.0
+1.3.2

data/CHANGELOG.md

@@ -1,5 +1,72 @@
 # 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)
+
+Two bindings for Atlas's MODS version-history endpoints. `mods_versions`
+lists the retained versions of a resource's descriptive metadata;
+`mods_version` fetches the raw MODS XML as of a specific version — together
+enough to drive a line-diff between any two MODS states.
+
+```ruby
+history = AtlasRb::Resource.mods_versions("w-789")
+history["versions"].first["version_id"]  # => "v5"   (newest)
+history["versions"].first["actor_nuid"]   # => "000000002"
+
+old_xml = AtlasRb::Resource.mods_version("w-789", "v3")
+new_xml = AtlasRb::Resource.mods_version("w-789", "v5")
+```
+
+- `mods_versions` returns the full envelope (`resource_id` + a
+  reverse-chronological `versions` array) as an `AtlasRb::Mash`. Each
+  descriptor mirrors the audit-event shape (`version_id`, `created`,
+  `actor_nuid`, `on_behalf_of_nuid`, `source`, `note`); actor fields are
+  correlated from the audit log and may be `null`. Admin-gated server-side.
+- `mods_version` returns the **raw XML body** (mirroring `Work.mods`). Only
+  XML is version-recoverable — the JSON access copy is overwritten in place
+  — so `kind:` is accepted for parity but XML is the only retained format.
+- Version labels are opaque, sortable OCFL `vN` strings (a Blob's
+  preservation envelope occupies earlier versions, so the first MODS
+  version is typically `v3`). Treat them as identifiers to feed back into
+  `mods_version`, not as ordinals.
+- Both are type-agnostic (Community / Collection / Work) and live on
+  `Resource` beside `history` / `permissions`. A resource with no MODS
+  returns `{ "versions" => [] }`.
+
 ## 1.3.0
 
 ### Added — `AtlasRb::Resource.find_many` (batch resolve by NOID)

data/Gemfile.lock

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

data/README.md

@@ -245,6 +245,44 @@ mode-less session events. Atlas stamps `occurred_at` server-side.
 Authorization errors (`401` / `403`) surface as raw Faraday responses,
 matching `Resource.history`.
 
+### MODS version history
+
+Every descriptive-metadata edit retains the prior MODS XML on the server.
+`Resource.mods_versions` lists the retained versions; `Resource.mods_version`
+fetches the raw MODS XML as of one of them — together enough to render a
+line-diff between any two MODS states. Both are type-agnostic (pass any
+Community, Collection, or Work ID).
+
+```ruby
+history = AtlasRb::Resource.mods_versions("w-789")
+history["resource_id"]                    # => "w-789"
+history["versions"].first["version_id"]   # => "v5"  (newest first)
+history["versions"].first["actor_nuid"]    # => "000000002" (or nil)
+
+# Fetch two versions and diff them:
+old_xml = AtlasRb::Resource.mods_version("w-789", "v3")
+new_xml = AtlasRb::Resource.mods_version("w-789", "v5")
+```
+
+`mods_versions` returns the full envelope (`resource_id` + a
+reverse-chronological `versions` array) as an `AtlasRb::Mash`; each
+descriptor mirrors the audit-event shape (`version_id`, `created`,
+`actor_nuid`, `on_behalf_of_nuid`, `source`, `note`), so the two streams
+render with the same helpers. Actor attribution is correlated from the
+audit log and may be `null`. The endpoint is admin-gated server-side
+(it exposes edit attribution).
+
+`mods_version` returns the **raw XML body** — like `Work.mods`, not a Mash.
+Only XML is version-recoverable (the JSON access copy is overwritten in
+place), so the server serves historical XML; `kind:` is accepted for parity
+with `Work.mods` but XML is the only retained format.
+
+Version labels are **opaque, sortable OCFL `vN` strings**, not a 1-based
+counter — a Blob's preservation envelope occupies earlier versions, so the
+first MODS version is typically `v3`. Treat them as identifiers to feed back
+into `mods_version`. A resource with no MODS returns `{ "versions" => [] }`;
+`401` / `403` surface as raw Faraday responses, matching `Resource.history`.
+
 ### Re-parenting
 
 `reparent` moves a resource to a new structural parent, binding Atlas's

data/lib/atlas_rb/resource.rb

@@ -166,5 +166,81 @@ module AtlasRb
           .get('/resources/' + id + '/history')&.body
       ))
     end
+
+    # List the retained MODS versions for a resource.
+    #
+    # Wraps Atlas's `GET /resources/<id>/mods/versions`, which returns the
+    # full envelope — `resource_id` plus a reverse-chronological `versions`
+    # array — as an `AtlasRb::Mash`. Each version descriptor mirrors the
+    # audit-event shape (`version_id`, `created`, `actor_nuid`,
+    # `on_behalf_of_nuid`, `source`, `note`) so the two streams render with
+    # the same helpers; actor fields are correlated from the audit log and
+    # may be `null` when a version has no matching edit event.
+    #
+    # Type-agnostic: pass any Modsable resource ID (Community, Collection,
+    # Work). A resource with no MODS comes back as `{ "versions" => [] }`.
+    #
+    # Version labels are opaque, sortable OCFL `vN` strings — not a 1-based
+    # counter — so treat them as identifiers to feed back into
+    # {mods_version}, not as ordinals. The server admin-gates this endpoint
+    # (it exposes edit attribution); `401` / `403` surface as raw Faraday
+    # responses, matching {history}.
+    #
+    # @param id [String] an Atlas resource 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 [AtlasRb::Mash] the parsed envelope, with `"resource_id"` and a
+    #   `"versions"` array (reverse chronological; possibly empty).
+    #
+    # @example
+    #   history = AtlasRb::Resource.mods_versions("w-789")
+    #   history["versions"].first["version_id"] # => "v5"
+    #   history["versions"].first["actor_nuid"]  # => "000000002"
+    def self.mods_versions(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .get('/resources/' + id + '/mods/versions')&.body
+      ))
+    end
+
+    # Fetch the MODS document as of a specific version.
+    #
+    # Wraps Atlas's `GET /resources/<id>/mods/versions/<version_id>` and
+    # returns the **raw response body** (not parsed) — mirroring
+    # {Work.mods}. Pass a `version_id` obtained from {mods_versions} (an
+    # opaque OCFL `vN` label).
+    #
+    # Only XML is version-recoverable: the JSON access copy is overwritten in
+    # place, so the server serves historical XML (the default). `kind:` is
+    # accepted for parity with {Work.mods} but XML is currently the only
+    # supported format. An unknown version yields a `404` (raw Faraday
+    # response).
+    #
+    # @param id [String] an Atlas resource ID.
+    # @param version_id [String] an OCFL version label from {mods_versions},
+    #   e.g. `"v3"`.
+    # @param kind [String, nil] response format extension. Omit (or pass
+    #   `"xml"`) for the historical XML — the only format the server retains.
+    # @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 [String] the raw MODS XML body for that version.
+    #
+    # @example Diff two MODS versions
+    #   old_xml = AtlasRb::Resource.mods_version("w-789", "v3")
+    #   new_xml = AtlasRb::Resource.mods_version("w-789", "v5")
+    def self.mods_version(id, version_id, kind: nil, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of).get(
+        '/resources/' + id + '/mods/versions/' + version_id +
+          (kind.present? ? ".#{kind}" : '')
+      )&.body
+    end
   end
 end

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.0
+  version: 1.3.2
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-06 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