atlas_rb 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8b62042df9f4d715469ba7cf23dcf352485552aa9d73c55290312c3055800c
-  data.tar.gz: d435ed7a4fb953f2d82dd6f304232731802b2e8fe68a5e055fecd51e972c560a
+  metadata.gz: 9660fb0f48db5601e75f8fb0579794cd398d42fbdbe1c2e849b67bb32569d9c1
+  data.tar.gz: fa8f43e4f7577027c3368e30f4ebf5c231202edbcaa1004ef0711582925680ee
 SHA512:
-  metadata.gz: 3dffc895e6bee5bce6dbe907488a72a240c55b7d5ae5a506bff61d81a451a97490090d576c575fa07cf82ffbaf023109a9938aa66adf872e892b3a2fc37f3e13
-  data.tar.gz: 7076d8304048de5f20b8560875fbaddcac8ab29a4c3cf3d37ac54b95c3bac4cb6aff56bc503967ec3a5e41289bf4173055b9d8ced278ac9b63849231e0e09ea2
+  metadata.gz: b98eab79df77eda36139468d6701ea8e56f5ae16ee85e3ef22635bc11f42aed762654bd9dbf02b87a4f8521bb4de335724b249c3700397d748572bd734bf62b4
+  data.tar.gz: c8f565644a54f99e6110131e6d1b361c21f51e068c565837c5226d21eb700b488fa13e1be9e59d591b587b4303196c785abf0c1fc8bb5eec000840b1515f2961

data/.version

@@ -1 +1 @@
-1.0.0
+1.1.1

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.1.1
+
+### Added
+
+- **`depositor:` kwarg on `AtlasRb::Work.create`** — optional NUID
+  forwarded as the `depositor` query param on `POST /works`. When
+  omitted, behaviour is unchanged: Atlas defaults the depositor to the
+  acting user. When provided, Atlas stamps the named NUID as the Work's
+  `depositor` and records the acting user as the `proxy_uploader`.
+
+  Motivation: proxy deposit. Librarians and bulk-deposit jobs frequently
+  upload Works on behalf of a researcher who is the rightful credited
+  depositor. Until now there was no way to express that split through
+  the gem — callers had to choose between misattributing the deposit to
+  the librarian or dropping to a raw Faraday call. The depositor is
+  immutable post-create; there is no corresponding setter on the update
+  surface.
+
+## 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.1)
       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

data/lib/atlas_rb/work.rb

@@ -93,6 +93,13 @@ module AtlasRb
     # @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.
+    # @param depositor [String, nil] optional NUID to stamp on the new Work's
+    #   `depositor` field. When omitted, Atlas defaults the depositor to the
+    #   acting user (`nuid:`); this kwarg is the proxy / batch escape hatch
+    #   where the librarian who uploaded the Work is distinct from the person
+    #   it should be attributed to. The acting user becomes the Work's
+    #   `proxy_uploader`. The depositor is immutable post-create; there is no
+    #   setter on the update surface.
     # @return [Hash] the created Work payload (post-update if `xml_path` was
     #   supplied).
     #
@@ -105,9 +112,15 @@ module AtlasRb
     # @example Retry-safe bulk-deposit create
     #   key = SecureRandom.uuid
     #   AtlasRb::Work.create("col-456", idempotency_key: key)
-    def self.create(id, xml_path = nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+    #
+    # @example Proxy deposit — librarian uploads on behalf of a researcher
+    #   AtlasRb::Work.create("col-456", depositor: "000000123")
+    def self.create(id, xml_path = nil, idempotency_key: nil, nuid: nil,
+                    on_behalf_of: nil, depositor: nil)
+      params = { collection_id: id }
+      params[:depositor] = depositor if depositor
       result = AtlasRb::Mash.new(JSON.parse(
-        connection({ collection_id: id }, nuid,
+        connection(params, nuid,
                    on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
       ))["work"]
       return result unless xml_path.present?

metadata

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