atlas_rb 1.3.1 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0947add262eb2b9b4ab993f16c2c379877455e9ece3bca04f41a61bfddf79ee3'
-  data.tar.gz: d239887dfaac21e78a7118503d4ed8ab79b12b3aa174ee18f5a8f31f253ca866
+  metadata.gz: a36183e05b8c32292a5b0201db841ad961bcffcd51d546c0203d591cfbcfefce
+  data.tar.gz: 81d85278032e45d983dd5007b25ca3688cea9f23e3c8b5ce94a04727ef5d9497
 SHA512:
-  metadata.gz: b4d59334c7730d11f9f7779b1cbef5c7cef49ce4b1726257a9c8590f258ab4c8aac80ffffa10c1111a38b4d98b95c7b36e824eab925aff4aae1ff87336f7e37e
-  data.tar.gz: a5c0484e6d4204758dc1eee8e2ca6086a289e19e250a404fbdffc4af65eaa7864f2da7f93a9586d4d84776c76b33dbdebb5147ae4d728baed51110864c347e30
+  metadata.gz: f4866c59b9c8a8321a0cc440139a5382ac03129e29e0130447da6ade868059dd484bed4029de404a61292058a0f32407266b20f707aa8757e65112d231c57374
+  data.tar.gz: ff821a348a98120bfe12da5f0e0de0594810ab93848f3db20e549951eabb205b330df5954d2e375836dab316d50178e80545cd1b69133165aee46567600f02b7

data/.version

@@ -1 +1 @@
-1.3.1
+1.3.3

data/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 1.3.3
+
+### Added — multipage bindings (FileSet ordinality)
+
+Bindings for Atlas's FileSet-ordinality surface (Atlas v0.6.53) — the
+primitive behind multipage Works (postcards, scanned books, photo albums):
+one Work, N ordered page FileSets.
+
+```ruby
+# Ordered create — one FileSet per page
+page = AtlasRb::FileSet.create("w-789", "image", position: 1)
+AtlasRb::FileSet.update(page["id"], "/tmp/page-001.tiff")
+
+# Ordered listing — the read a IIIF manifest assembler needs
+AtlasRb::Work.file_sets("w-789")
+# => [{ "noid" => ..., "position" => 1, "assets" => [...] }, ...]
+
+# Preservation-record view — the Work-level METS physical structMap
+AtlasRb::Work.mets("w-789").mets.pages.map(&:order)
+# => [1, 2, 3]
+```
+
+- `FileSet.create` gains an optional `position:` kwarg — 1-based page
+  order, set at create time only; omitted = unordered (every existing
+  call is unaffected). Sequence validation (contiguity, uniqueness) stays
+  the caller's job — Atlas stores what it is given.
+- `Work.file_sets` wraps `GET /works/<id>/file_sets`: one entry per
+  page-bearing FileSet, `position` ascending with unordered FileSets
+  last, each nesting its downloadable assets (content Blobs + per-page
+  IIIF Delegates). **Unpaginated** by design — the whole page sequence
+  arrives in one call. Grouped sibling of `.assets`, which flattens.
+- `Work.mets` wraps `GET /works/<id>/mets`: the Work-level METS JSON
+  projection; `mets.pages` carries the preserved page order. Atlas builds
+  the document at `Work.complete`, so a never-completed Work has no METS
+  yet — the binding returns `nil` on the 404, matching
+  `User.find_by_nuid`'s convention.
+
+## 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.3)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/lib/atlas_rb/file_set.rb

@@ -39,6 +39,12 @@ module AtlasRb
     # @param classification [String] role tag for the FileSet — e.g.
     #   `"primary"`, `"supplemental"`, `"thumbnail"`. The exact set is
     #   defined by the Atlas server.
+    # @param position [Integer, nil] optional 1-based page order within the
+    #   parent Work, for multipage Works (one FileSet per page). Omit for
+    #   unordered FileSets — every non-multipage FileSet stays unordered.
+    #   Set at create time only; Atlas stores what it is given (sequence
+    #   validation — contiguity, uniqueness — is the caller's job, e.g. the
+    #   Cerberus loader rejecting bad manifests before any create).
     # @param idempotency_key [String, nil] optional UUID. A repeat call with
     #   the same key returns the originally-created FileSet instead of
     #   creating a new one. See {AtlasRb::Work.create} for full semantics.
@@ -49,18 +55,25 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @return [Hash] the created `"file_set"` payload, including its `"id"`
-    #   which can then be passed to {.update} to attach a binary.
+    #   which can then be passed to {.update} to attach a binary, and its
+    #   `"position"` (`nil` when unordered).
     #
     # @example
     #   fs = AtlasRb::FileSet.create("w-789", "primary")
     #   AtlasRb::FileSet.update(fs["id"], "/tmp/article.pdf")
     #
+    # @example Multipage ingest — one ordered FileSet per page
+    #   page = AtlasRb::FileSet.create("w-789", "image", position: 1)
+    #   AtlasRb::FileSet.update(page["id"], "/tmp/page-001.tiff")
+    #
     # @example Retry-safe bulk-deposit create
     #   key = SecureRandom.uuid
     #   AtlasRb::FileSet.create("w-789", "primary", idempotency_key: key)
-    def self.create(id, classification, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+    def self.create(id, classification, position: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+      params = { work_id: id, classification: classification }
+      params[:position] = position if position
       AtlasRb::Mash.new(JSON.parse(
-        connection({ work_id: id, classification: classification }, nuid,
+        connection(params, nuid,
                    on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
       ))["file_set"]
     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/work.rb

@@ -371,6 +371,78 @@ module AtlasRb
       ).map { |entry| AtlasRb::Mash.new(entry) }
     end
 
+    # List a Work's page FileSets in order, each with its assets.
+    #
+    # Wraps `GET /works/<id>/file_sets` — the ordered, grouped sibling of
+    # {.assets} (which flattens FileSet membership away). One entry per
+    # page-bearing FileSet, sorted `position` ascending with unordered
+    # (`null`-position) FileSets last; metadata and derivative-container
+    # FileSets are excluded as entries. Each entry nests its downloadable
+    # assets — the page's content Blobs plus any per-page IIIF Delegates —
+    # in the same polymorphic shape {.assets} returns.
+    #
+    # This is the read a IIIF Presentation manifest assembler needs: the
+    # response is **unpaginated** by design, so the whole page sequence
+    # arrives in one call.
+    #
+    # @param id [String] the Work 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 [Array<AtlasRb::Mash>] one entry per page FileSet, in page
+    #   order: `{ "noid", "type", "position", "tombstoned", "assets" => [...] }`.
+    #
+    # @example Assemble manifest canvases in page order
+    #   AtlasRb::Work.file_sets("w-789").each do |page|
+    #     iiif = page.assets.find { |a| a["uri"] }
+    #     add_canvas(order: page.position, image: iiif&.uri)
+    #   end
+    def self.file_sets(id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/file_sets')&.body
+      ).map { |entry| AtlasRb::Mash.new(entry) }
+    end
+
+    # Fetch the Work-level METS structural metadata (page order).
+    #
+    # Wraps `GET /works/<id>/mets` — the JSON projection of the Work's METS
+    # document, whose physical structMap is the preservation record of page
+    # order. The page sequence surfaces under `"mets" => "pages"` (one entry
+    # per page: `noid` / `order` / `label`). Atlas builds the document when
+    # the Work is completed ({.complete}) and rebuilds it on page changes
+    # thereafter, so a Work that has never been completed has no METS yet —
+    # Atlas answers `404` and this binding returns `nil` (matching
+    # {User.find_by_nuid}'s missing-resource convention).
+    #
+    # For runtime page listing (e.g. manifest assembly) prefer {.file_sets},
+    # which needs no completion and carries each page's assets; this read is
+    # the preservation-record view.
+    #
+    # @param id [String] the Work 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 [Hash, nil] the `"work"` object, already unwrapped: `{ "id",
+    #   "mets" => { "created_at_iso", "agent", "files", "structure_label",
+    #   "pages" => [...] } }` — or `nil` when the Work has no METS yet
+    #   (never completed) or does not exist.
+    #
+    # @example
+    #   AtlasRb::Work.mets("w-789").mets.pages.map(&:order)
+    #   # => [1, 2, 3]
+    def self.mets(id, nuid: nil, on_behalf_of: nil)
+      response = connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/mets')
+      return nil if response.status == 404
+
+      AtlasRb::Mash.new(JSON.parse(response.body))["work"]
+    end
+
     # Fetch the Work's MODS representation in the requested format.
     #
     # @param id [String] the Work ID.

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.3
 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