atlas_rb 1.18.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfa719c8d880ec4ed326597fe0882537649b69b6e0e52a3df4123353c1019198
-  data.tar.gz: 1ffae14221914997c13572495b728dbb93cd02c81144cba4eb5ca33f64bb444a
+  metadata.gz: 528d764830f8e3a3fdaf376983d4ce3babe6ef0a19f5b1e2fe02fbceb0584bd0
+  data.tar.gz: 2d80d25327e3e43f389a0f71e84c2a880f5bc89905989ff22c16aabee90261c4
 SHA512:
-  metadata.gz: b4705dd193fec70bb702846a51aa08a902a772a76964873d89a11ef2963823e7b5217525a3fb2efed339596ce213f04d6aad3cd43bb8b9387c92ea246e1d4740
-  data.tar.gz: 3ab173992d0243e249f51dd385cb6b7507bd8478adac2abcb1077e49c04bc0dfcb2d4fc665b9e843e72b17337dd9cdf8e8709008078dc0909befd87ef5472ac1
+  metadata.gz: 881ea22bc257423cbbeb748d26bc011371d5d9112be6e72106a60799215d59ce636ef566210a7b5cb93090d075f450f910f15a1040f321910869f358a01bb8cf
+  data.tar.gz: 97203339683115160ec8ef78e375f639d76d38716f2d29f190b2c80b01505f8eda85081e6d487510de0fc65308ae00afba7dbc18e956da16476a2bc3b6bc931b

data/.version

@@ -1 +1 @@
-1.18.0
+1.19.0

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.19.0
+
+### Added — `Resource.search`, the catalog keyword search
+
+```ruby
+AtlasRb::Resource.search("whaling logbook", type: "Work", page: 1, per_page: 25)
+# => Mash with "results" and "pagination"
+```
+
+Binds `GET /resources/search`, which needs Atlas 0.6.199 or later. It is
+Cerberus's search bar for a caller without Blacklight: the same field weights,
+because both come from the Solr core's search handler, and the same filters for
+the global catalog. It returns the whole envelope, as `descendant_works` does, so
+a caller pages with `pagination.pages`.
+
+Each row is a Solr digest, and `klass` is a name `Resource.class_for` accepts, so
+loading the full resource is `class_for(hit.klass).find(hit.noid)`.
+
+One difference from Cerberus is deliberate. Atlas gates the rows as its own
+`Ability` reads a resource, so an edit group and the depositor count as well as a
+read group. Cerberus's search still checks read groups only, so for staff and
+depositors this can return items that Cerberus's search does not. Every such item
+is one the user can already open.
+
 ## 1.18.0
 
 ### Changed — the write surface is type-agnostic, and the typed writes are gone

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.18.0)
+    atlas_rb (1.19.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -16,7 +16,7 @@ GEM
     base64 (0.3.0)
     connection_pool (2.5.5)
     diff-lcs (1.6.1)
-    faraday (2.14.3)
+    faraday (2.14.4)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger

data/README.md

@@ -641,6 +641,31 @@ tombstoned resources come back flagged (`"tombstoned" => true`), so index
 by `"noid"` rather than assuming positional correspondence. NOIDs only —
 raw Valkyrie ids are not a supported input.
 
+### Searching the catalog (`Resource.search`)
+
+A keyword search, as Cerberus's search bar runs it, for a caller that has words
+rather than a NOID:
+
+```ruby
+result = AtlasRb::Resource.search("whaling logbook", type: "Work", per_page: 50)
+result.pagination.total                 # => 12
+hit = result.results.first
+hit.title                               # => "Whaling logbook, 1851"
+AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+```
+
+It searches Works, Collections, Communities and People, most relevant first.
+`type` narrows to one of those four; any other value is a `400`, raised as
+`AtlasRb::ResourceError`. Leave out the text to browse everything the user may
+read, newest first.
+
+Each row is a digest read off Solr — `{ "id", "noid", "klass", "title",
+"creators", "year", "thumbnail", "in_progress", "embargoed", "incomplete" }` —
+not the full typed payload. Rows are **gated to the acting user**: public, one of
+their read or edit groups, or a resource they deposited. So the same text can
+return different results for different users. There are no facets and no sort
+option.
+
 ### Missing resources: `nil` on a read, a raise on a write
 
 The two halves of the API answer an absent resource differently, on purpose.

data/lib/atlas_rb/resource.rb

@@ -155,6 +155,55 @@ module AtlasRb
                   .get('/resources/' + id + '/descendant_works')) { |body| AtlasRb::Mash.new(body) }
     end
 
+    # Keyword search over the catalog, as Cerberus's search bar searches it.
+    #
+    # Searches Works, Collections, Communities and People, most relevant
+    # first, and returns one page. Atlas gates every row to what the acting
+    # user may read — public, one of their read or edit groups, or a resource
+    # they deposited — so two users can get different results for the same
+    # text. Tombstoned resources, featured Collections, personal roots and
+    # unfinished deposits (except the caller's own) never appear.
+    #
+    # Each row is a digest read off Solr, not a resource: `{ "id", "noid",
+    # "klass", "title", "creators", "year", "thumbnail", "in_progress",
+    # "embargoed", "incomplete" }`. `klass` is one of the four type names
+    # above, which {class_for} accepts, so a caller loads the full resource
+    # with `class_for(hit.klass).find(hit.noid)`.
+    #
+    # @param query [String, nil] the search text. Omit or pass blank to browse
+    #   everything the user may read, newest first.
+    # @param type [String, nil] one of `"Work"`, `"Collection"`, `"Community"`,
+    #   `"Person"`, to narrow the search to that 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 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] the parsed envelope, with a `"results"` digest
+    #   array and a `"pagination"` block (`total` / `page` / `per_page` / `pages`).
+    #
+    # @raise [AtlasRb::ResourceError] on any non-2xx — a `400` for an unknown
+    #   `type`, an auth envelope, a `5xx` — carrying Atlas's status and body.
+    # @example Find a Work by a word in its title, then load it
+    #   result = AtlasRb::Resource.search("whaling logbook", type: "Work")
+    #   hit    = result.results.first
+    #   AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+    # @example Page through every match
+    #   (1..AtlasRb::Resource.search("whaling").pagination.pages).flat_map do |page|
+    #     AtlasRb::Resource.search("whaling", page: page).results
+    #   end
+    def self.search(query = nil, type: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+      params = {}
+      params[:q]        = query    if query
+      params[:type]     = type     if type
+      params[:page]     = page     if page
+      params[:per_page] = per_page if per_page
+      read_body(connection(params, nuid, on_behalf_of: on_behalf_of)
+                  .get("/resources/search")) { |body| AtlasRb::Mash.new(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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.19.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday