atlas_rb 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8b62042df9f4d715469ba7cf23dcf352485552aa9d73c55290312c3055800c
-  data.tar.gz: d435ed7a4fb953f2d82dd6f304232731802b2e8fe68a5e055fecd51e972c560a
+  metadata.gz: b3406190d2c893eccbd1b8d47f20efe85ecb01d404145294352e1db61133406b
+  data.tar.gz: 0a178b48eee743a8e3275dcdf999451b3f811e3af214e163ba675eb4487e5d22
 SHA512:
-  metadata.gz: 3dffc895e6bee5bce6dbe907488a72a240c55b7d5ae5a506bff61d81a451a97490090d576c575fa07cf82ffbaf023109a9938aa66adf872e892b3a2fc37f3e13
-  data.tar.gz: 7076d8304048de5f20b8560875fbaddcac8ab29a4c3cf3d37ac54b95c3bac4cb6aff56bc503967ec3a5e41289bf4173055b9d8ced278ac9b63849231e0e09ea2
+  metadata.gz: bde03915384d45748a5c74c7235890e4f64116470f1146775e7480077aac9cf7778d867f526f24dc1470f481837b5b0933794234df3da0254f7eb8aff3ae1539
+  data.tar.gz: 86bb05b0b0d9b3be8ea8a3f219e1c6137548255312e80a7bf7eabbe809a110993a48dca16a4fe2aaf55def9cd8627389c0796a6e6ed218d054bc945b4068439b

data/.version

@@ -1 +1 @@
-1.0.0
+1.1.0

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.1.0
+
+### Added
+
+- **`AtlasRb::Resource.history(id, nuid: nil, on_behalf_of: nil)`** —
+  wraps Atlas's `GET /resources/:id/history` endpoint. Returns the full
+  envelope (`resource_id` + reverse-chronological `events` array) as an
+  `AtlasRb::Mash`, matching the gem's convention for cross-resource
+  bindings. Authorization errors (`401` / `403`) surface as raw Faraday
+  responses for the caller's rescue layer. Pagination is not yet
+  supported by the server; a TODO is in place for when it lands.
+
+  Cerberus consumes this binding for the "History" tab on resource show
+  pages.
+
 ## 1.0.0 — major restructure: namespace gradient + ambient identity
 
 This release reshapes the gem's API surface. Downstream consumers

data/Gemfile.lock

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

data/README.md

@@ -112,7 +112,7 @@ Community  →  Collection  →  Work
 | `AtlasRb::FileSet`     | Classified slot under a Work (e.g. `"primary"`, `"supplemental"`).        |
 | `AtlasRb::Blob`        | The binary bytes; supports streaming downloads.                           |
 | `AtlasRb::Authentication` | NUID → user record / group lookup.                                     |
-| `AtlasRb::Resource`    | Generic resolver and permissions lookup.                                  |
+| `AtlasRb::Resource`    | Generic resolver, permissions lookup, and audit-event history.            |
 | `AtlasRb::Reset`       | Test-only — wipes Atlas state via `GET /reset`.                           |
 
 ## Namespace gradient: regular / Admin / System
@@ -187,6 +187,24 @@ AtlasRb::Work.list(in_progress: false, page: 2)   # completed deposits, page 2
 AtlasRb::Work.complete("w-789")                   # mark w-789 done
 ```
 
+### Audit-event history
+
+`Resource.history` wraps Atlas's `GET /resources/<id>/history` endpoint
+and returns the full envelope — `resource_id` plus a reverse-chronological
+`events` array — as an `AtlasRb::Mash`. It is type-agnostic: pass any
+Community, Collection, Work, FileSet, or Blob ID. Pagination is not yet
+supported on the server side; the endpoint returns the full history in
+one shot.
+
+```ruby
+result = AtlasRb::Resource.history("w-789")
+result["resource_id"]            # => "w-789"
+result["events"].first["action"] # => "update"
+```
+
+Authorization errors (`401` / `403`) are not caught here — they surface as
+raw Faraday responses for the calling application's rescue layer.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/resource.rb

@@ -5,9 +5,9 @@ module AtlasRb
   #
   # Subclasses define a `ROUTE` constant (e.g. `"/communities/"`) and override
   # whichever of `find / create / destroy / update / metadata / mods` apply.
-  # The {Resource} class itself ships three endpoints that are not
-  # type-specific: a generic resolver, an XML preview helper, and a
-  # permissions lookup.
+  # The {Resource} class itself ships four endpoints that are not
+  # type-specific: a generic resolver, an XML preview helper, a permissions
+  # lookup, and an audit-event history fetch.
   #
   # The Atlas resource hierarchy is:
   #
@@ -91,5 +91,42 @@ module AtlasRb
           .get('/resources/' + id + '/permissions')&.body
       ))["resource"]
     end
+
+    # Fetch the audit-event history for a resource.
+    #
+    # Wraps Atlas's `GET /resources/<id>/history` endpoint, which returns the
+    # full envelope (`resource_id` + reverse-chronological `events` array).
+    # The whole envelope is preserved so callers can confirm the events
+    # belong to the requested resource; access events as `result["events"]`.
+    #
+    # Authorization errors (`401` / `403`) are intentionally **not** caught
+    # here — they surface as raw Faraday responses for the calling
+    # application's rescue layer to translate.
+    #
+    # @todo Add pagination support once Atlas's history endpoint exposes
+    #   page / per_page query params. Today the endpoint returns the full
+    #   history in one shot.
+    #
+    # @param id [String] an Atlas resource 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 [AtlasRb::Mash] the parsed envelope from
+    #   `GET /resources/<id>/history`, with `"resource_id"` and an `"events"`
+    #   array (reverse chronological; possibly empty).
+    #
+    # @example
+    #   result = AtlasRb::Resource.history("abc12345")
+    #   result["resource_id"]            # => "abc12345"
+    #   result["events"].first["action"] # => "create"
+    def self.history(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .get('/resources/' + id + '/history')&.body
+      ))
+    end
   end
 end

metadata

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