atlas_rb 1.8.7 → 1.8.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88e591bc06be2edcf972e7df8490f57656f0562680d3546598f7461b1ad25bc3
-  data.tar.gz: 997084c70c482d78cbc4627d7dcf65b91a1687b8bf6ed1855c0f46613b007389
+  metadata.gz: 1fd50831467b065989eb0ec39af5f96b87622c5d0e161e0e6a5bdef61764505a
+  data.tar.gz: 55c36e14086a0fab3776771c797af98c9a431cca3f0b09f14ffac478ab58067c
 SHA512:
-  metadata.gz: 87d74362da0a1b9fe6655c675fe834dce9c1ea824012d9f482c1828fbe6f299495793836c6840528d350aad020a1a28bf3a53f52136c336c114a3e41afb61096
-  data.tar.gz: b02aac392fa82e3f64c5a391e23215aa2eb6577285ddb0517ac2653ae67f33603dc05e4af018acb73c5a2d9859fc2b137309f51525db6b40aa36897cbe957cfa
+  metadata.gz: 7aea8252388df4686a31174ca154b7e76da1d97dd16a8509f773bd2b918dfb282ccb93960f5138b0581df9d32d20c45a0f8cf4a1475dda787468644e1d83cdbd
+  data.tar.gz: 25e3ecf9a7cc353645a8a1ad76700523bba185895fcf1df13b9b098549a45287fb3a9c41abb0eefa559f5e1d8b4c8c4b81b7c16e5e418f4cee39e5f0d554dc56

data/.version

@@ -1 +1 @@
-1.8.7
+1.8.9

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.8.8
+
+### Added — type-agnostic current MODS (`Resource.mods`)
+
+New polymorphic wrapper `AtlasRb::Resource.mods(id, kind = nil, …)` for Atlas's
+`GET /resources/:id/mods` — fetch the current descriptive MODS of any Modsable
+resource (Work / Collection / Community) by NOID, without knowing its type.
+Returns the raw response body, mirroring the typed `Work.mods` / `Collection.mods`
+/ `Community.mods`; output is byte-identical to the typed routes. `kind` omitted
+yields the JSON projection (server default); pass `"xml"` for MODS XML.
+
+Collapses the `children → find_many (for klass) → dispatch-by-klass` two-step a
+bulk MODS exporter needed just to pick the typed MODS URL down to one call per
+member. `404` (unknown id / non-Modsable / no MODS) comes back as an empty body.
+
 ## 1.8.7
 
 ### Added — personal-access token lifecycle (`System::Token.mint` / `.revoke`)

data/Gemfile.lock

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

data/lib/atlas_rb/resource.rb

@@ -88,6 +88,52 @@ module AtlasRb
       ).map { |node| AtlasRb::Mash.new(node) }
     end
 
+    # Every Work beneath a resource, at any depth — the structural counterpart
+    # to {Compilation.contents}. Wraps `GET /resources/<id>/descendant_works`,
+    # which flattens the resource's full descendant subtree to the Works it
+    # contains, gated to what the caller may read and paginated Solr-side. Gives
+    # a Collection the flatten-to-Works capability a Set already has, so a bulk
+    # export (e.g. hyperion) pages one gated, fast call family instead of the
+    # client-side `children → find_many → recurse` walk.
+    #
+    # Returns the same digest shape as {find_many} / {Compilation.contents}
+    # (`{ "id", "noid", "klass", "title", "thumbnail" }`) under a `"works"` key,
+    # plus a `"pagination"` envelope (`total` / `page` / `per_page` / `pages`).
+    # Membership is **structural** (`a_member_of`) only; pass
+    # `include_linked: true` to also surface linked members
+    # (`a_linked_member_of`). Restricted Works never appear for a caller who may
+    # not read them; tombstoned Works are dropped.
+    #
+    # @param id [String] an Atlas resource ID (subtree root; any type).
+    # @param page [Integer, nil] 1-based page (default 1 server-side).
+    # @param per_page [Integer, nil] page size (server default 25, capped 100).
+    # @param include_linked [Boolean, nil] also include linked members when
+    #   truthy; structural-only by default.
+    # @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).
+    # @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, nil] the parsed envelope, with a `"works"` digest
+    #   array and a `"pagination"` block; `nil` when the id resolves to nothing
+    #   (`404`).
+    #
+    # @example Page a Collection's whole subtree of Works
+    #   result = AtlasRb::Resource.descendant_works("col-456", per_page: 100)
+    #   result["works"].map { |w| w["noid"] }
+    #   result.dig("pagination", "pages")
+    def self.descendant_works(id, page: nil, per_page: nil, include_linked: nil, nuid: nil, on_behalf_of: nil)
+      params = {}
+      params[:page]           = page           if page
+      params[:per_page]       = per_page       if per_page
+      params[:include_linked] = include_linked unless include_linked.nil?
+      resp = connection(params, nuid, on_behalf_of: on_behalf_of)
+             .get('/resources/' + id + '/descendant_works')
+      return nil if resp.status == 404
+
+      AtlasRb::Mash.new(JSON.parse(resp.body))
+    end
+
     # Validate a MODS XML document against Atlas's schema *without* persisting it.
     #
     # Useful for surfacing validation errors in UIs before the user commits.
@@ -170,6 +216,38 @@ module AtlasRb
       ))
     end
 
+    # Fetch the CURRENT MODS of any Modsable resource by NOID — the polymorphic
+    # sibling of {Work.mods} / {Collection.mods} / {Community.mods}. Wraps
+    # `GET /resources/<id>/mods[.kind]` and returns the **raw response body**
+    # (not parsed), mirroring the typed wrappers. Lets a caller holding only a
+    # NOID (no type) fetch descriptive MODS in one call, instead of resolving
+    # the klass first to pick the typed route — e.g. a bulk Collection/Set MODS
+    # export that has bare member NOIDs from {Collection.children}.
+    #
+    # @param id [String] an Atlas resource ID (NOID).
+    # @param kind [String, nil] response-format extension: omit for the JSON
+    #   projection (the server default), or pass `"xml"` for MODS XML (`"json"`
+    #   / `"html"` also accepted). Output is byte-identical to the typed route
+    #   for the resolved type.
+    # @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).
+    # @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, nil] the raw MODS body (XML or JSON per `kind`). The
+    #   server returns `404` (empty body) for an unknown id, a non-Modsable
+    #   resource, or one with no MODS.
+    #
+    # @example Bulk-export a Set's members' MODS without klass dispatch
+    #   AtlasRb::Collection.children(set_id).each do |noid|
+    #     xml = AtlasRb::Resource.mods(noid, "xml")
+    #   end
+    def self.mods(id, kind = nil, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of).get(
+        '/resources/' + id + '/mods' + (kind.present? ? ".#{kind}" : '')
+      )&.body
+    end
+
     # List the retained MODS versions for a resource.
     #
     # Wraps Atlas's `GET /resources/<id>/mods/versions`, which returns the

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.8.7
+  version: 1.8.9
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday