atlas_rb 1.6.2 → 1.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d84aa1546173f2a0ad397f7bb8f960be544c79c02187013fadf82301efa8afcf
-  data.tar.gz: 7873dec712e7bc46d10fd081e2401a96ff980c3c93d97a35799f08edbe701f26
+  metadata.gz: 5c1b8b2ec2ef5cadfe63ee85f618f8ef0ce394e9d7cc49637750250594ecd414
+  data.tar.gz: d59e9ac145408d33e00ddcc89f92cee6126b32e5c1959467a042080f14f49bb6
 SHA512:
-  metadata.gz: 431d703701ca9f01511894590c3680147f96daf702930796acc8bfe6678b7c34eba571087c6ce491daf144797ea2c07bfd345e04d20cf077ff92034ec2c0c886
-  data.tar.gz: 83dc3bd542faa2ccca914f0f4029f4ef5427fd0971c641edeeacf607927d93d818e71faa45c9b5637f7f6ed9df0df7600a66bfa420a86965d3a59f71726d4b64
+  metadata.gz: 42992114ad5685f700294dd0f52d5c55507182d4ae0f907a2077c35a534cb7e8052a5d4a7a266f435ae1964341ca15d28c85688e8ff559ff60eb067c48994a7d
+  data.tar.gz: dc7a7df1a1fba8e4766a47c648c37f85a99244d105ebe6f564f09953fcda29837b111f41e730e871ca20afd032ed9db46dfe7dcd64e41badc550816d8c66f56e

data/.version

@@ -1 +1 @@
-1.6.2
+1.6.4

data/Gemfile.lock

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

data/lib/atlas_rb/collection.rb

@@ -44,6 +44,9 @@ module AtlasRb
     # @param xml_path [String, nil] optional path to a MODS XML file used to
     #   seed metadata. When given, the Collection is created and immediately
     #   patched with the metadata in the file.
+    # @param featured [Boolean] mark the Collection as a genre-showcase
+    #   ("Featured") Collection. Defaults to false. Use when provisioning a
+    #   Community's showcase set (loop create + featured: true).
     # @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).
@@ -53,11 +56,11 @@ module AtlasRb
     # @return [Hash] the created Collection payload (post-update if
     #   `xml_path` was supplied).
     #
-    # @example
-    #   AtlasRb::Collection.create("c-123", "/tmp/collection-mods.xml")
-    def self.create(id, xml_path = nil, nuid: nil, on_behalf_of: nil)
+    # @example A featured showcase collection
+    #   AtlasRb::Collection.create("c-123", featured: true)
+    def self.create(id, xml_path = nil, featured: false, nuid: nil, on_behalf_of: nil)
       result = AtlasRb::Mash.new(JSON.parse(
-        connection({ parent_id: id }, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+        connection({ parent_id: id, featured: featured }, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
       ))["collection"]
       return result unless xml_path.present?
 
@@ -65,6 +68,27 @@ module AtlasRb
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
+    # Toggle the showcase "Featured" flag on an existing Collection.
+    #
+    # A resource-attribute write (not a MODS update), so it does not touch
+    # descriptive metadata. Cerberus reads the projected `featured_bsi` to
+    # badge the Collection in a community's browse.
+    #
+    # @param id [String] the Collection ID.
+    # @param featured [Boolean] the new flag value.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @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 updated `"collection"` object, already unwrapped.
+    #
+    # @example
+    #   AtlasRb::Collection.set_featured("col-456", true)
+    def self.set_featured(id, featured, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      ))["collection"]
+    end
+
     # Move a Collection to a different parent Community.
     #
     # Wraps `PATCH /collections/<id>/parent` with a `parent_id` of the new

data/lib/atlas_rb/person.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # A neutral curatorial identity in Atlas, distinct from the auth-side users
+  # directory. A Person correlates the several `users` rows that share a NUID
+  # and carries the authoritative, librarian-editable `display_name` (the SSO
+  # `users.name` is frequently wrong and is clobbered on every login), plus
+  # community affiliations.
+  #
+  # Addressed by NUID, not NOID — the NUID is the correlation key consumers
+  # hold. So the positional `id` argument below is the person's **NUID**, and
+  # the `nuid:` / `on_behalf_of:` keywords keep their usual gem meaning (the
+  # acting principal). The one exception is {.create}, whose `nuid:` keyword is
+  # the *new person's* NUID (matching the gap's signature); the acting principal
+  # there comes from the ambient `AtlasRb.config.default_nuid`.
+  #
+  # Create / update / affiliation writes are :system + admin on the server; a
+  # non-privileged caller gets a 403.
+  class Person < Resource
+    ROUTE = "/people/"
+
+    # Fetch a Person by NUID.
+    #
+    # @param id [String] the person's NUID.
+    # @param nuid [String, nil] acting principal (signed into the assertion sub).
+    # @param on_behalf_of [String, nil] acting-as target.
+    # @return [AtlasRb::Mash] the unwrapped `"person"` object.
+    def self.find(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id)&.body
+      ))["person"]
+    end
+
+    # Batch-resolve people to their authoritative display_name in one call
+    # (supersedes the SSO users directory's resolve). Unresolved NUIDs drop.
+    #
+    # @param nuids [Array<String>] the NUIDs to resolve.
+    # @param nuid [String, nil] acting principal.
+    # @param on_behalf_of [String, nil] acting-as target.
+    # @return [Array<AtlasRb::Mash>] one unwrapped `"person"` per resolved NUID.
+    def self.resolve(nuids, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({ nuids: Array(nuids).join(",") }, nuid, on_behalf_of: on_behalf_of).get(ROUTE)&.body
+      )["people"].map { |entry| AtlasRb::Mash.new(entry["person"]) }
+    end
+
+    # Create a Person. One Person per NUID — a duplicate NUID is a 409.
+    #
+    # @param nuid [String] the **new person's** NUID (the subject, not the actor).
+    # @param display_name [String] authoritative display name.
+    # @param bio [String, nil]
+    # @param orcid [String, nil]
+    # @param title [String, nil]
+    # @param on_behalf_of [String, nil] acting-as target (the acting principal
+    #   itself comes from the ambient AtlasRb.config.default_nuid).
+    # @return [AtlasRb::Mash] the unwrapped `"person"` object.
+    def self.create(nuid:, display_name:, bio: nil, orcid: nil, title: nil, on_behalf_of: nil)
+      body = { nuid: nuid, display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nil, on_behalf_of: on_behalf_of).post(ROUTE, JSON.dump(body))&.body
+      ))["person"]
+    end
+
+    # Edit a Person's authority fields. NUID is immutable and not patchable.
+    # Only supplied fields are changed.
+    #
+    # @param id [String] the person's NUID.
+    # @param display_name [String, nil]
+    # @param bio [String, nil]
+    # @param orcid [String, nil]
+    # @param title [String, nil]
+    # @param nuid [String, nil] acting principal.
+    # @param on_behalf_of [String, nil] acting-as target.
+    # @return [AtlasRb::Mash] the unwrapped, updated `"person"` object.
+    def self.update(id, display_name: nil, bio: nil, orcid: nil, title: nil, nuid: nil, on_behalf_of: nil)
+      body = { display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, JSON.dump(body))&.body
+      ))["person"]
+    end
+
+    # Add a community affiliation (idempotent; audited server-side).
+    #
+    # @param id [String] the person's NUID.
+    # @param community_id [String] the community's NOID.
+    # @param nuid [String, nil] acting principal.
+    # @param on_behalf_of [String, nil] acting-as target.
+    # @return [AtlasRb::Mash] the unwrapped `"person"` object, with the updated
+    #   `affiliated_community_ids`.
+    def self.add_affiliation(id, community_id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + id + "/affiliations", JSON.dump(community_id: community_id))&.body
+      ))["person"]
+    end
+
+    # Remove a community affiliation (tolerant; audited server-side).
+    #
+    # @param id [String] the person's NUID.
+    # @param community_id [String] the community's NOID.
+    # @param nuid [String, nil] acting principal.
+    # @param on_behalf_of [String, nil] acting-as target.
+    # @return [AtlasRb::Mash] the unwrapped `"person"` object.
+    def self.remove_affiliation(id, community_id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + id + "/affiliations/" + community_id)&.body
+      ))["person"]
+    end
+  end
+end

data/lib/atlas_rb.rb

@@ -22,6 +22,7 @@ require_relative "atlas_rb/file_set"
 require_relative "atlas_rb/blob"
 require_relative "atlas_rb/delegate"
 require_relative "atlas_rb/compilation"
+require_relative "atlas_rb/person"
 require_relative "atlas_rb/user"
 require_relative "atlas_rb/admin"
 require_relative "atlas_rb/admin/work"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.6.4
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-17 00:00:00.000000000 Z
+date: 2026-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -147,6 +147,7 @@ files:
 - lib/atlas_rb/mash.rb
 - lib/atlas_rb/middleware/raise_on_resource_error.rb
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
+- lib/atlas_rb/person.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/system.rb
 - lib/atlas_rb/system/user.rb