atlas_rb 1.3.2 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54691ff87af06d611d63a27333682abfd284c67d6990d0c8400ea2b9b80adb92
-  data.tar.gz: 7d3119d56763694dad36c69ded4cbf975af62d6eb070baf36c0df02f422259f1
+  metadata.gz: a36183e05b8c32292a5b0201db841ad961bcffcd51d546c0203d591cfbcfefce
+  data.tar.gz: 81d85278032e45d983dd5007b25ca3688cea9f23e3c8b5ce94a04727ef5d9497
 SHA512:
-  metadata.gz: 86dc095d2be7db4fdefe997cc6b33fabd0d3c1826804b0521fda48b06d17ec4cd3fde492a3926114965d4354823f55043ea7559d4ce82dcc06a288b7fa8afecd
-  data.tar.gz: c31c2bea0442ec082ede4a2328c6f7471eb02151021c6e08620b4fef5b254996ad424816493e8d955e202f5c5444e800393b85064dc9feb58a61cbaf126a9e08
+  metadata.gz: f4866c59b9c8a8321a0cc440139a5382ac03129e29e0130447da6ade868059dd484bed4029de404a61292058a0f32407266b20f707aa8757e65112d231c57374
+  data.tar.gz: ff821a348a98120bfe12da5f0e0de0594810ab93848f3db20e549951eabb205b330df5954d2e375836dab316d50178e80545cd1b69133165aee46567600f02b7

data/.version

@@ -1 +1 @@
-1.3.2
+1.3.3

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.3.3
+
+### Added — multipage bindings (FileSet ordinality)
+
+Bindings for Atlas's FileSet-ordinality surface (Atlas v0.6.53) — the
+primitive behind multipage Works (postcards, scanned books, photo albums):
+one Work, N ordered page FileSets.
+
+```ruby
+# Ordered create — one FileSet per page
+page = AtlasRb::FileSet.create("w-789", "image", position: 1)
+AtlasRb::FileSet.update(page["id"], "/tmp/page-001.tiff")
+
+# Ordered listing — the read a IIIF manifest assembler needs
+AtlasRb::Work.file_sets("w-789")
+# => [{ "noid" => ..., "position" => 1, "assets" => [...] }, ...]
+
+# Preservation-record view — the Work-level METS physical structMap
+AtlasRb::Work.mets("w-789").mets.pages.map(&:order)
+# => [1, 2, 3]
+```
+
+- `FileSet.create` gains an optional `position:` kwarg — 1-based page
+  order, set at create time only; omitted = unordered (every existing
+  call is unaffected). Sequence validation (contiguity, uniqueness) stays
+  the caller's job — Atlas stores what it is given.
+- `Work.file_sets` wraps `GET /works/<id>/file_sets`: one entry per
+  page-bearing FileSet, `position` ascending with unordered FileSets
+  last, each nesting its downloadable assets (content Blobs + per-page
+  IIIF Delegates). **Unpaginated** by design — the whole page sequence
+  arrives in one call. Grouped sibling of `.assets`, which flattens.
+- `Work.mets` wraps `GET /works/<id>/mets`: the Work-level METS JSON
+  projection; `mets.pages` carries the preserved page order. Atlas builds
+  the document at `Work.complete`, so a never-completed Work has no METS
+  yet — the binding returns `nil` on the 404, matching
+  `User.find_by_nuid`'s convention.
+
 ## 1.3.2
 
 ### Added — `AtlasRb::User` (read-only user directory)

data/Gemfile.lock

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

data/lib/atlas_rb/file_set.rb

@@ -39,6 +39,12 @@ 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 position [Integer, nil] optional 1-based page order within the
+    #   parent Work, for multipage Works (one FileSet per page). Omit for
+    #   unordered FileSets — every non-multipage FileSet stays unordered.
+    #   Set at create time only; Atlas stores what it is given (sequence
+    #   validation — contiguity, uniqueness — is the caller's job, e.g. the
+    #   Cerberus loader rejecting bad manifests before any create).
     # @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.
@@ -49,18 +55,25 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @return [Hash] the created `"file_set"` payload, including its `"id"`
-    #   which can then be passed to {.update} to attach a binary.
+    #   which can then be passed to {.update} to attach a binary, and its
+    #   `"position"` (`nil` when unordered).
     #
     # @example
     #   fs = AtlasRb::FileSet.create("w-789", "primary")
     #   AtlasRb::FileSet.update(fs["id"], "/tmp/article.pdf")
     #
+    # @example Multipage ingest — one ordered FileSet per page
+    #   page = AtlasRb::FileSet.create("w-789", "image", position: 1)
+    #   AtlasRb::FileSet.update(page["id"], "/tmp/page-001.tiff")
+    #
     # @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, nuid: nil, on_behalf_of: nil)
+    def self.create(id, classification, position: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+      params = { work_id: id, classification: classification }
+      params[:position] = position if position
       AtlasRb::Mash.new(JSON.parse(
-        connection({ work_id: id, classification: classification }, nuid,
+        connection(params, nuid,
                    on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
       ))["file_set"]
     end

data/lib/atlas_rb/work.rb

@@ -371,6 +371,78 @@ module AtlasRb
       ).map { |entry| AtlasRb::Mash.new(entry) }
     end
 
+    # List a Work's page FileSets in order, each with its assets.
+    #
+    # Wraps `GET /works/<id>/file_sets` — the ordered, grouped sibling of
+    # {.assets} (which flattens FileSet membership away). One entry per
+    # page-bearing FileSet, sorted `position` ascending with unordered
+    # (`null`-position) FileSets last; metadata and derivative-container
+    # FileSets are excluded as entries. Each entry nests its downloadable
+    # assets — the page's content Blobs plus any per-page IIIF Delegates —
+    # in the same polymorphic shape {.assets} returns.
+    #
+    # This is the read a IIIF Presentation manifest assembler needs: the
+    # response is **unpaginated** by design, so the whole page sequence
+    # arrives in one call.
+    #
+    # @param id [String] the Work 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 [Array<AtlasRb::Mash>] one entry per page FileSet, in page
+    #   order: `{ "noid", "type", "position", "tombstoned", "assets" => [...] }`.
+    #
+    # @example Assemble manifest canvases in page order
+    #   AtlasRb::Work.file_sets("w-789").each do |page|
+    #     iiif = page.assets.find { |a| a["uri"] }
+    #     add_canvas(order: page.position, image: iiif&.uri)
+    #   end
+    def self.file_sets(id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/file_sets')&.body
+      ).map { |entry| AtlasRb::Mash.new(entry) }
+    end
+
+    # Fetch the Work-level METS structural metadata (page order).
+    #
+    # Wraps `GET /works/<id>/mets` — the JSON projection of the Work's METS
+    # document, whose physical structMap is the preservation record of page
+    # order. The page sequence surfaces under `"mets" => "pages"` (one entry
+    # per page: `noid` / `order` / `label`). Atlas builds the document when
+    # the Work is completed ({.complete}) and rebuilds it on page changes
+    # thereafter, so a Work that has never been completed has no METS yet —
+    # Atlas answers `404` and this binding returns `nil` (matching
+    # {User.find_by_nuid}'s missing-resource convention).
+    #
+    # For runtime page listing (e.g. manifest assembly) prefer {.file_sets},
+    # which needs no completion and carries each page's assets; this read is
+    # the preservation-record view.
+    #
+    # @param id [String] the Work 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 [Hash, nil] the `"work"` object, already unwrapped: `{ "id",
+    #   "mets" => { "created_at_iso", "agent", "files", "structure_label",
+    #   "pages" => [...] } }` — or `nil` when the Work has no METS yet
+    #   (never completed) or does not exist.
+    #
+    # @example
+    #   AtlasRb::Work.mets("w-789").mets.pages.map(&:order)
+    #   # => [1, 2, 3]
+    def self.mets(id, nuid: nil, on_behalf_of: nil)
+      response = connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/mets')
+      return nil if response.status == 404
+
+      AtlasRb::Mash.new(JSON.parse(response.body))["work"]
+    end
+
     # Fetch the Work's MODS representation in the requested format.
     #
     # @param id [String] the Work ID.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.3.3
 platform: ruby
 authors:
 - David Cliff