atlas_rb 0.0.89 → 0.0.92

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a987c6f2b9d67ba84bfb29752682c630a47d69e943af83d44f5957136b2ae680
-  data.tar.gz: 5b2eea6ac511508959d56be1d7dce4306a2187eba6eeb5e1e4556ed7efe3fc9c
+  metadata.gz: 9ecdf5a4da61e030d7220fc9094a43bd91a850eaa1c599179d75c3d5381b300a
+  data.tar.gz: eea705d4f0601b112b2182848241c5439ef4beb10b87e87939e73ea70eb30907
 SHA512:
-  metadata.gz: b0279a6e5f20724c89a4e5bb31232e33c9860f4a28ee416a34539e279715e43c8229e436f41a696cc56d762049e4b69abde7a21ba72adaf687bebc5330044e8c
-  data.tar.gz: a480b47e2927b337e222d4890d5903b366acebfc27283d366d3967fb98c53a96a84ff039c590ba1a2d67751982c8dd379123a2ad86391e84cf4f937c30225956
+  metadata.gz: 4aa3b1a2367bde1309f589eebf0bf9bf8ff9f744dc1cdf5648c820cd4d38b4e2afa496a9b50308947f00cb9ceab4d10df4e92018d7715ad7928aa415fb556e0c
+  data.tar.gz: b006492ee9c5adde683c863d06cf7cbd233848709e6aa6176e0e6b2fbd663f81f70166b0e7da4889a9005e47c7ecd3cc39e7aa58bde32461b15b4448b18d786d

data/.version

@@ -1 +1 @@
-0.0.89
+0.0.92

data/Gemfile.lock

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

data/README.md

@@ -73,6 +73,34 @@ AtlasRb::FileSet.create("w-789", "primary") # file_set under work w-789, classif
 AtlasRb::Blob.create("w-789", path, name)  # blob under work w-789 with original filename preserved
 ```
 
+`Work.create`, `FileSet.create`, and `Blob.create` each accept an optional
+`idempotency_key:` kwarg for retry-safe bulk-deposit jobs. The caller
+generates the UUID; the Atlas server enforces uniqueness scoped to the
+acting user. A repeat call with the same key returns the originally-created
+resource (or `410` if it has since been tombstoned). The gem does **not**
+generate keys, cache responses, or retry — those concerns belong to the
+calling job runner (e.g. Cerberus's Solid Queue).
+
+```ruby
+key = SecureRandom.uuid
+AtlasRb::Work.create("col-456", idempotency_key: key)
+AtlasRb::FileSet.create("w-789", "primary", idempotency_key: key)
+AtlasRb::Blob.create("w-789", path, name, idempotency_key: key)
+```
+
+### Listing and monitoring Works
+
+`Work.list` exposes the paginated `GET /works` index, with an optional
+`in_progress:` filter for finding deposits that haven't yet been marked
+complete. `Work.complete` flips a Work's `in_progress` flag to `false`
+once a bulk-deposit job confirms all expected children have been deposited.
+
+```ruby
+AtlasRb::Work.list(in_progress: true)             # stuck deposits
+AtlasRb::Work.list(in_progress: false, page: 2)   # completed deposits, page 2
+AtlasRb::Work.complete("w-789")                   # mark w-789 done
+```
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/blob.rb

@@ -65,19 +65,29 @@ module AtlasRb
     # @param blob_path [String] path to the binary file on disk to upload.
     # @param original_filename [String] the user-facing filename Atlas
     #   should record (e.g. `"final_thesis.pdf"`).
+    # @param idempotency_key [String, nil] optional UUID. A repeat call with
+    #   the same key returns the originally-created Blob instead of creating
+    #   a new one. See {AtlasRb::Work.create} for full semantics.
     # @return [Hash] the created `"blob"` payload, including its `"id"`.
     #
     # @example
     #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "final_thesis.pdf")
     #   # => { "id" => "b-321", "original_filename" => "final_thesis.pdf", ... }
-    def self.create(id, blob_path, original_filename)
+    #
+    # @example Retry-safe bulk-deposit create
+    #   key = SecureRandom.uuid
+    #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "thesis.pdf",
+    #                        idempotency_key: key)
+    def self.create(id, blob_path, original_filename, idempotency_key: nil)
       payload = { work_id: id,
                   original_filename: original_filename,
                   binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
                                                           "application/octet-stream",
                                                           File.basename(blob_path)) }
 
-      AtlasRb::Mash.new(JSON.parse(multipart({}).post(ROUTE, payload)&.body))['blob']
+      AtlasRb::Mash.new(JSON.parse(
+        multipart(nil, idempotency_key: idempotency_key).post(ROUTE, payload)&.body
+      ))['blob']
     end
 
     # Delete a Blob (the bytes *and* the metadata record).

data/lib/atlas_rb/collection.rb

@@ -60,6 +60,41 @@ module AtlasRb
       connection({}).delete(ROUTE + id)
     end
 
+    # Tombstone (withdraw) a Collection.
+    #
+    # The Collection remains in Atlas storage but is marked as withdrawn:
+    # search and show pages return a withdrawn stub for every user. Atlas
+    # rejects the request with `422 has_live_children` if the Collection
+    # still has live (non-tombstoned) Works.
+    #
+    # @param id [String] the Collection ID.
+    # @param nuid [String] the acting user's NUID, stamped on the resource
+    #   as `tombstoned_by` for audit purposes.
+    # @return [Faraday::Response] the raw response. `200`/`204` on success;
+    #   `422` with `{"code":"has_live_children"}` if the Collection is not empty.
+    #
+    # @example
+    #   AtlasRb::Collection.tombstone("col-456", nuid: "000000002")
+    def self.tombstone(id, nuid:)
+      connection({}, nuid).post(ROUTE + id + '/tombstone')
+    end
+
+    # Restore a previously tombstoned Collection.
+    #
+    # **Operator-only.** Restoration is intentionally not exposed in any
+    # end-user UI; call this from a Rails console session (or a future
+    # admin panel) when the library has decided an object should come back.
+    #
+    # @param id [String] the Collection ID.
+    # @param nuid [String] the acting user's NUID.
+    # @return [Faraday::Response] the raw response.
+    #
+    # @example Operator restoring from `bundle exec rails console`
+    #   AtlasRb::Collection.restore("col-456", nuid: "000000002")
+    def self.restore(id, nuid:)
+      connection({}, nuid).post(ROUTE + id + '/restore')
+    end
+
     # List the Works in a Collection.
     #
     # The endpoint returns just the noids; resolve each through

data/lib/atlas_rb/community.rb

@@ -64,6 +64,41 @@ module AtlasRb
       connection({}).delete(ROUTE + id)
     end
 
+    # Tombstone (withdraw) a Community.
+    #
+    # The Community remains in Atlas storage but is marked as withdrawn:
+    # search and show pages return a withdrawn stub for every user. Atlas
+    # rejects the request with `422 has_live_children` if the Community
+    # still has live (non-tombstoned) members.
+    #
+    # @param id [String] the Community ID.
+    # @param nuid [String] the acting user's NUID, stamped on the resource
+    #   as `tombstoned_by` for audit purposes.
+    # @return [Faraday::Response] the raw response. `200`/`204` on success;
+    #   `422` with `{"code":"has_live_children"}` if the Community is not empty.
+    #
+    # @example
+    #   AtlasRb::Community.tombstone("c-123", nuid: "000000002")
+    def self.tombstone(id, nuid:)
+      connection({}, nuid).post(ROUTE + id + '/tombstone')
+    end
+
+    # Restore a previously tombstoned Community.
+    #
+    # **Operator-only.** Restoration is intentionally not exposed in any
+    # end-user UI; call this from a Rails console session (or a future
+    # admin panel) when the library has decided an object should come back.
+    #
+    # @param id [String] the Community ID.
+    # @param nuid [String] the acting user's NUID.
+    # @return [Faraday::Response] the raw response.
+    #
+    # @example Operator restoring from `bundle exec rails console`
+    #   AtlasRb::Community.restore("c-123", nuid: "000000002")
+    def self.restore(id, nuid:)
+      connection({}, nuid).post(ROUTE + id + '/restore')
+    end
+
     # List the immediate children (sub-Communities and Collections) of a Community.
     #
     # The endpoint returns just the noids; resolve each through

data/lib/atlas_rb/faraday_helper.rb

@@ -23,17 +23,23 @@ module AtlasRb
     #   or `metadata:` without manually serializing.
     # @param nuid [String, nil] optional Northeastern University ID to send in
     #   the `User` header. Defaults to `nil` (no NUID context).
+    # @param idempotency_key [String, nil] optional UUID to send in the
+    #   `Idempotency-Key` header. Used by retry-safe create flows (currently
+    #   `POST /works`, `POST /file_sets`, `POST /files`) to deduplicate replays
+    #   against the originally-created resource. Generated by the caller —
+    #   this gem does not mint keys.
     # @return [Faraday::Connection] a connection that follows redirects and
     #   uses Faraday's default adapter.
     #
     # @example Fetching a community
     #   AtlasRb::Community.connection({}).get('/communities/abc123')
-    def connection(params, nuid=nil)
+    def connection(params, nuid=nil, idempotency_key: nil)
       headers = {
         "Content-Type" => "application/json",
         "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
       }
       headers["User"] = "NUID #{nuid}" if nuid
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
       Faraday.new(
         url: ENV.fetch("ATLAS_URL", nil),
@@ -53,6 +59,9 @@ module AtlasRb
     # `Faraday::Multipart::FilePart` instances.
     #
     # @param nuid [String, nil] optional NUID for the `User` header.
+    # @param idempotency_key [String, nil] optional UUID to send in the
+    #   `Idempotency-Key` header. See {#connection} for semantics; the
+    #   `POST /files` (Blob) create flow uses this transport.
     # @return [Faraday::Connection] a multipart-aware connection.
     #
     # @example Posting a binary blob
@@ -63,11 +72,12 @@ module AtlasRb
     #                                               "scan.pdf")
     #   }
     #   AtlasRb::Blob.multipart({}).post('/files/', payload)
-    def multipart(nuid=nil)
+    def multipart(nuid=nil, idempotency_key: nil)
       headers = {
         "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
       }
       headers["User"] = "NUID #{nuid}" if nuid
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
       Faraday.new(
         url: ENV.fetch("ATLAS_URL", nil),

data/lib/atlas_rb/file_set.rb

@@ -31,14 +31,24 @@ module AtlasRb
     # @param classification [String] role tag for the FileSet — e.g.
     #   `"primary"`, `"supplemental"`, `"thumbnail"`. The exact set is
     #   defined by the Atlas server.
+    # @param idempotency_key [String, nil] optional UUID. A repeat call with
+    #   the same key returns the originally-created FileSet instead of
+    #   creating a new one. See {AtlasRb::Work.create} for full semantics.
     # @return [Hash] the created `"file_set"` payload, including its `"id"`
     #   which can then be passed to {.update} to attach a binary.
     #
     # @example
     #   fs = AtlasRb::FileSet.create("w-789", "primary")
     #   AtlasRb::FileSet.update(fs["id"], "/tmp/article.pdf")
-    def self.create(id, classification)
-      AtlasRb::Mash.new(JSON.parse(connection({ work_id: id, classification: classification }).post(ROUTE)&.body))["file_set"]
+    #
+    # @example Retry-safe bulk-deposit create
+    #   key = SecureRandom.uuid
+    #   AtlasRb::FileSet.create("w-789", "primary", idempotency_key: key)
+    def self.create(id, classification, idempotency_key: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({ work_id: id, classification: classification }, nil,
+                   idempotency_key: idempotency_key).post(ROUTE)&.body
+      ))["file_set"]
     end
 
     # Delete a FileSet.

data/lib/atlas_rb/work.rb

@@ -26,6 +26,33 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(connection({}).get(ROUTE + id)&.body))["work"]
     end
 
+    # List Works, paginated.
+    #
+    # Wraps `GET /works`. Returns the full pagination envelope rather than a
+    # bare array so callers can page through results — the shape matches
+    # {AtlasRb::Community.children} and {AtlasRb::Collection.children}.
+    #
+    # @param in_progress [Boolean, nil] when set, filter to Works whose
+    #   `in_progress` flag matches. Omit (or pass `nil`) for "all works".
+    # @param page [Integer, nil] 1-indexed page number.
+    # @param per_page [Integer, nil] page size override.
+    # @return [AtlasRb::Mash] `{ "works" => [...], "pagination" => {...} }`.
+    #   Each entry in `"works"` is a Work summary (`id`, `title`,
+    #   `description`, `in_progress`).
+    #
+    # @example Find stuck deposits
+    #   AtlasRb::Work.list(in_progress: true)
+    #
+    # @example Page through all works
+    #   AtlasRb::Work.list(page: 2, per_page: 50)
+    def self.list(in_progress: nil, page: nil, per_page: nil)
+      params = {}
+      params[:in_progress] = in_progress unless in_progress.nil?
+      params[:page]        = page        if page
+      params[:per_page]    = per_page    if per_page
+      AtlasRb::Mash.new(JSON.parse(connection(params).get(ROUTE)&.body))
+    end
+
     # Create a new Work in an existing Collection.
     #
     # **Note**: unlike {Community.create} and {Collection.create}, the `id`
@@ -36,6 +63,14 @@ module AtlasRb
     # @param xml_path [String, nil] optional path to a MODS XML file. When
     #   given, the Work is created and immediately patched with the metadata
     #   in the file.
+    # @param idempotency_key [String, nil] optional UUID. A repeat call with
+    #   the same key returns the originally-created Work instead of creating
+    #   a new one (or `410` if it has since been tombstoned, or `410` with
+    #   no body if it has been hard-deleted). Keys are scoped to the acting
+    #   user and only apply to the initial `POST /works` — the optional
+    #   follow-up PATCH/GET when `xml_path` is given do not carry the key.
+    #   The caller (e.g. Cerberus's Solid Queue job) generates and persists
+    #   the UUID; this gem does not mint keys.
     # @return [Hash] the created Work payload (post-update if `xml_path` was
     #   supplied).
     #
@@ -44,8 +79,14 @@ module AtlasRb
     #
     # @example Work seeded from MODS
     #   AtlasRb::Work.create("col-456", "/tmp/work-mods.xml")
-    def self.create(id, xml_path = nil)
-      result = AtlasRb::Mash.new(JSON.parse(connection({ collection_id: id }).post(ROUTE)&.body))["work"]
+    #
+    # @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)
+      result = AtlasRb::Mash.new(JSON.parse(
+        connection({ collection_id: id }, nil, idempotency_key: idempotency_key).post(ROUTE)&.body
+      ))["work"]
       return result unless xml_path.present?
 
       update(result["id"], xml_path)
@@ -63,6 +104,64 @@ module AtlasRb
       connection({}).delete(ROUTE + id)
     end
 
+    # Tombstone (withdraw) a Work.
+    #
+    # The Work remains in Atlas storage along with its FileSets and Blobs,
+    # but is marked as withdrawn: search and show pages return a withdrawn
+    # stub for every user. Unlike Communities and Collections, Works are
+    # always tombstoneable regardless of how many files they hold — the
+    # FileSets and Blobs ride along.
+    #
+    # @param id [String] the Work ID.
+    # @param nuid [String] the acting user's NUID, stamped on the resource
+    #   as `tombstoned_by` for audit purposes.
+    # @return [Faraday::Response] the raw response.
+    #
+    # @example
+    #   AtlasRb::Work.tombstone("w-789", nuid: "000000002")
+    def self.tombstone(id, nuid:)
+      connection({}, nuid).post(ROUTE + id + '/tombstone')
+    end
+
+    # Mark a Work complete.
+    #
+    # Cerberus's bulk-deposit job calls this once it has confirmed all
+    # expected children (FileSets / Blobs) are deposited. Atlas's monitoring
+    # query `GET /works?in_progress=true` then drops this Work from the
+    # "stuck" list.
+    #
+    # Idempotent on the server: calling `complete` on an already-complete
+    # Work is a no-op — Atlas simply re-saves with `in_progress: false`.
+    # Atlas does not currently stamp a `completed_by` audit field; the
+    # `nuid:` parameter is plumbed through for parity with the other
+    # lifecycle bindings and in case Atlas adds completion audit later.
+    #
+    # @param id [String] the Work ID.
+    # @param nuid [String, nil] optional NUID of the acting user.
+    # @return [Faraday::Response] the raw response. Status `200` on success.
+    #
+    # @example
+    #   AtlasRb::Work.complete("w-789")
+    def self.complete(id, nuid: nil)
+      connection({}, nuid).post(ROUTE + id + '/complete')
+    end
+
+    # Restore a previously tombstoned Work.
+    #
+    # **Operator-only.** Restoration is intentionally not exposed in any
+    # end-user UI; call this from a Rails console session (or a future
+    # admin panel) when the library has decided an object should come back.
+    #
+    # @param id [String] the Work ID.
+    # @param nuid [String] the acting user's NUID.
+    # @return [Faraday::Response] the raw response.
+    #
+    # @example Operator restoring from `bundle exec rails console`
+    #   AtlasRb::Work.restore("w-789", nuid: "000000002")
+    def self.restore(id, nuid:)
+      connection({}, nuid).post(ROUTE + id + '/restore')
+    end
+
     # Replace a Work's metadata by uploading a MODS XML document.
     #
     # @param id [String] the Work ID.

metadata

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