atlas_rb 1.6.1 → 1.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0b6def06432136a4f0fda238a5c8ff3599de63234325e8609d0fcc49012d42d
-  data.tar.gz: a50c8fbbcaa1776a171f199e86e5ab90a8034f8c9415547c97893f52dc26a449
+  metadata.gz: 63326317e9bb9abcd730807bdfe9870d24685da7fec108474f676198ed1de200
+  data.tar.gz: 16a31a4c9708699c92f4651714594a3ead821a882cc4e958b0ae81a86b0c5146
 SHA512:
-  metadata.gz: 19578a460cb38f49fd97a7513cc2ba6d782fa260a82f3c1071cc88e01a6a21ad6026969422033af5ad013f3e81d2d4d400fab42c72b300bd410582dc806d7f29
-  data.tar.gz: 941ce0caf062890a63891e5a458d83e1300e9240240f8adaf39a9e7ed7879ddaf4ef8168c566b052c5c7f7fde50c66e00e93baa66f71462a5464f2ea1b4a03ad
+  metadata.gz: 6236b86dd4a2b0c2c8740fb9479a9584a59fe1303464b7731ae955e0ceb5489e920d7a119d1bac6afb1535933310b7ccecee74d3da6a865a6bdb755a38a9c095
+  data.tar.gz: 0c80e8c9f82b3a05ba5560e703db3da1c1c10ceae61dd95a06c3e8368fa07a503e8a12bcb66d2ae5d0ed398af7386d54943cad754f319ef31dd9669149e8c490

data/.version

@@ -1 +1 @@
-1.6.1
+1.6.3

data/Gemfile.lock

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

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/system.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # System-context callers — see {AtlasRb::System::User} for the namespace
+  # rationale (separate bearer token, hard-pinned `User:` header, the class
+  # itself as the carve-out marker).
+  #
+  # Beyond user provisioning, the namespace exposes Atlas's operational,
+  # `:system`-gated maintenance actions. These are not user operations — they
+  # never appear on the human CRUD surface — so they ride the system path.
+  module System
+    extend AtlasRb::FaradayHelper
+
+    # Re-project a single resource's Solr doc from Atlas's current
+    # Postgres/OCFL state. Solr-only on the server — no lifecycle transition,
+    # no audit event, no optimistic-lock bump. The purpose-built lever for
+    # refreshing a stale projection after an indexer ships or changes (e.g.
+    # the catalog's `classification_ssim` "Content" facet), without abusing
+    # `AtlasRb::Work.complete` to nudge Solr as a finalize side effect.
+    #
+    # Idempotent. Authenticates as the Atlas `:system` fixture via
+    # {FaradayHelper#system_connection}, so there is no way to issue it as a
+    # regular user.
+    #
+    # @param id [String] the NOID of any resource (Work, Collection,
+    #   Community, FileSet, ...).
+    # @return [Faraday::Response] the raw response. Status `204` on success;
+    #   `404` if the id does not resolve.
+    #
+    # @example Refresh one drifted Work after a new indexer shipped
+    #   AtlasRb::System.reindex("neu:abc123")
+    def self.reindex(id)
+      system_connection.post("/resources/#{id}/reindex")
+    end
+
+    # Re-project a resource AND its full descendant subtree — descendant
+    # containers (Collection/Community) plus the Works beneath them, a superset
+    # of Atlas's re-parent cascade so Work-level projections refresh too. Same
+    # Solr-only, side-effect-free semantics as {.reindex}.
+    #
+    # Synchronous on the server: rooted at a Collection it refreshes that
+    # Collection's contents; rooted at the top Community it backfills the whole
+    # repository. For a pathologically large subtree, root lower or drive the
+    # cascade in chunks (repeated calls) rather than relying on Atlas to grow a
+    # job runner — bulk orchestration lives in the consumer.
+    #
+    # @param id [String] the NOID of the subtree root.
+    # @return [Integer] the number of resources re-projected (the server's
+    #   `reindexed` count).
+    #
+    # @example Backfill a Collection's contents after an indexer change
+    #   AtlasRb::System.reindex_subtree("neu:collection1")  # => 42
+    def self.reindex_subtree(id)
+      response = system_connection.post("/resources/#{id}/reindex_subtree")
+      JSON.parse(response.body)["reindexed"]
+    end
+  end
+end

data/lib/atlas_rb.rb

@@ -22,11 +22,13 @@ 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"
 require_relative "atlas_rb/admin/collection"
 require_relative "atlas_rb/admin/community"
+require_relative "atlas_rb/system"
 require_relative "atlas_rb/system/user"
 require_relative "atlas_rb/audit_event"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.6.3
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -147,7 +147,9 @@ 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
 - lib/atlas_rb/user.rb
 - lib/atlas_rb/version.rb