atlas_rb 0.0.92 → 0.0.95

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ecdf5a4da61e030d7220fc9094a43bd91a850eaa1c599179d75c3d5381b300a
-  data.tar.gz: eea705d4f0601b112b2182848241c5439ef4beb10b87e87939e73ea70eb30907
+  metadata.gz: 2f04b74aca7b48fdba1f279e1b818cacc6e34be23c96a12b90c7cdd201ee0904
+  data.tar.gz: 9aeefc94a12ac0d8798e4fbf0d5edd5a9d6dacf9a6ec540184e2617b0cb0d5cc
 SHA512:
-  metadata.gz: 4aa3b1a2367bde1309f589eebf0bf9bf8ff9f744dc1cdf5648c820cd4d38b4e2afa496a9b50308947f00cb9ceab4d10df4e92018d7715ad7928aa415fb556e0c
-  data.tar.gz: b006492ee9c5adde683c863d06cf7cbd233848709e6aa6176e0e6b2fbd663f81f70166b0e7da4889a9005e47c7ecd3cc39e7aa58bde32461b15b4448b18d786d
+  metadata.gz: e028b1c2439beff9c27bc2f6a98082f7b76ebe86b7a16620c0a3d8aadfe5bc2463093e4c70f7d91198cf04a38100c4ea311f3415195743640aeb833b7847df3b
+  data.tar.gz: 4730752d8d3df7ec5715d7ae0bc71c892944a3ee215659f611d4216be171a284f3d71bf3413b2d4db17404641691f4c18836d7246b0d8045e0128552e22e069b

data/.version

@@ -1 +1 @@
-0.0.92
+0.0.95

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (0.0.92)
+    atlas_rb (0.0.95)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -11,7 +11,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.6.1)
-    faraday (2.14.1)
+    faraday (2.14.2)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger

data/lib/atlas_rb/collection.rb

@@ -125,7 +125,12 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body))
     end
 
-    # Patch individual metadata fields without uploading a full MODS document.
+    # Patch individual descriptive-metadata fields without uploading a
+    # full MODS document.
+    #
+    # Scoped to user-authored descriptive metadata only. Programmatic
+    # writes of machine-set Delegate URIs (thumbnails) have their own
+    # purpose-specific endpoint — see {.set_thumbnails}.
     #
     # @param id [String] the Collection ID.
     # @param values [Hash] field-level metadata updates.
@@ -137,6 +142,33 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body))
     end
 
+    # Attach the three thumbnail/preview Delegate URIs to a Collection.
+    #
+    # Collection-level mirror of {Work.set_thumbnails}. Atlas dispatches
+    # each non-blank URI to its matching Delegate role
+    # (`thumbnail_image` / `thumbnail_image_2x` / `preview_image`) via
+    # `DelegateUpdater`. Missing keys are left untouched.
+    #
+    # @param id [String] the Collection ID.
+    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
+    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
+    # @param preview [String, nil] IIIF URI for the ~500w preview image.
+    # @return [AtlasRb::Mash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Collection.set_thumbnails(
+    #     "col-456",
+    #     thumbnail:    "https://iiif.example.edu/iiif/3/c.jp2/full/!85,85/0/default.jpg",
+    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/c.jp2/full/!170,170/0/default.jpg",
+    #     preview:      "https://iiif.example.edu/iiif/3/c.jp2/full/500,/0/default.jpg"
+    #   )
+    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil)
+      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}).patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+      ))
+    end
+
     # Fetch the Collection's MODS representation in the requested format.
     #
     # @param id [String] the Collection ID.

data/lib/atlas_rb/community.rb

@@ -130,7 +130,12 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body))
     end
 
-    # Patch individual metadata fields without uploading a full MODS document.
+    # Patch individual descriptive-metadata fields without uploading a
+    # full MODS document.
+    #
+    # Scoped to user-authored descriptive metadata only. Programmatic
+    # writes of machine-set Delegate URIs (thumbnails) have their own
+    # purpose-specific endpoint — see {.set_thumbnails}.
     #
     # @param id [String] the Community ID.
     # @param values [Hash] field-level metadata updates (shape determined by
@@ -143,6 +148,33 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body))
     end
 
+    # Attach the three thumbnail/preview Delegate URIs to a Community.
+    #
+    # Community-level mirror of {Work.set_thumbnails}. Atlas dispatches
+    # each non-blank URI to its matching Delegate role
+    # (`thumbnail_image` / `thumbnail_image_2x` / `preview_image`) via
+    # `DelegateUpdater`. Missing keys are left untouched.
+    #
+    # @param id [String] the Community ID.
+    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
+    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
+    # @param preview [String, nil] IIIF URI for the ~500w preview image.
+    # @return [AtlasRb::Mash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Community.set_thumbnails(
+    #     "c-123",
+    #     thumbnail:    "https://iiif.example.edu/iiif/3/m.jp2/full/!85,85/0/default.jpg",
+    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/m.jp2/full/!170,170/0/default.jpg",
+    #     preview:      "https://iiif.example.edu/iiif/3/m.jp2/full/500,/0/default.jpg"
+    #   )
+    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil)
+      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}).patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+      ))
+    end
+
     # Fetch the Community's MODS representation in the requested format.
     #
     # @param id [String] the Community ID.

data/lib/atlas_rb/delegate.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # A server-managed derivative asset attached to a {Work} — thumbnails,
+  # previews, and other generated representations.
+  #
+  # Unlike a {Blob}, a Delegate is not user-uploaded binary content; it is
+  # produced and addressed by Atlas itself. Each Delegate exposes a `uri`
+  # pointing at the underlying bytes plus enough metadata
+  # (`mime_type`, `original_filename`, `label`, `use`) for clients to
+  # render or link to it without fetching the bytes first.
+  #
+  # Lookups accept either the resource NOID or the `valkyrie_id`: Atlas
+  # redirects NOIDs to `/delegates/:valkyrie_id` and Faraday transparently
+  # follows the redirect.
+  #
+  # See also: {Work}, {Blob}.
+  class Delegate < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
+    ROUTE = "/delegates/"
+
+    # Fetch a single Delegate by NOID or `valkyrie_id`.
+    #
+    # @param id [String] the Delegate's NOID or `valkyrie_id`.
+    # @return [AtlasRb::Mash] the `"delegate"` object, already unwrapped —
+    #   includes `id`, `valkyrie_id`, `use`, `uri`, `mime_type`,
+    #   `original_filename`, `label`, and tombstone fields.
+    #
+    # @example
+    #   AtlasRb::Delegate.find("d-555")
+    def self.find(id)
+      AtlasRb::Mash.new(JSON.parse(connection({}).get(ROUTE + id)&.body))["delegate"]
+    end
+  end
+end

data/lib/atlas_rb/work.rb

@@ -177,7 +177,13 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body))
     end
 
-    # Patch individual metadata fields without uploading a full MODS document.
+    # Patch individual descriptive-metadata fields without uploading a
+    # full MODS document.
+    #
+    # Scoped to user-authored descriptive metadata only. Programmatic
+    # writes of machine-set Delegate URIs (thumbnails, image
+    # derivatives) have their own purpose-specific endpoints — see
+    # {.set_thumbnails} and {.set_image_derivatives}.
     #
     # @param id [String] the Work ID.
     # @param values [Hash] field-level metadata updates.
@@ -189,19 +195,86 @@ module AtlasRb
       AtlasRb::Mash.new(JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body))
     end
 
-    # List the {FileSet}s and {Blob}s attached to a Work.
+    # Attach the three thumbnail/preview Delegate URIs to a Work.
+    #
+    # Purpose-specific PATCH for the `thumbnail_image` /
+    # `thumbnail_image_2x` / `preview_image` Delegate roles. Atlas
+    # dispatches each URI to its matching role via `DelegateUpdater`.
+    # Distinct from {.metadata} — these are machine-set IIIF URIs, not
+    # user-authored descriptive content. Missing keys are left
+    # untouched server-side; only the URIs you pass are upserted.
+    #
+    # @param id [String] the Work ID.
+    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
+    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
+    # @param preview [String, nil] IIIF URI for the ~500w preview image.
+    # @return [AtlasRb::Mash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Work.set_thumbnails(
+    #     "w-789",
+    #     thumbnail:    "https://iiif.example.edu/iiif/3/abc.jp2/full/!85,85/0/default.jpg",
+    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/abc.jp2/full/!170,170/0/default.jpg",
+    #     preview:      "https://iiif.example.edu/iiif/3/abc.jp2/full/500,/0/default.jpg"
+    #   )
+    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil)
+      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}).patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+      ))
+    end
+
+    # Attach the three image-derivative Delegate URIs to a Work.
+    #
+    # Sibling of {.set_thumbnails} for the `small_image` /
+    # `medium_image` / `large_image` Delegate roles. Atlas dispatches
+    # each URI to its matching role via `DelegateUpdater`. The
+    # resulting Delegates are downloadable and surface through
+    # {.assets} for the downloads UI. Missing keys are left untouched
+    # server-side; only the URIs you pass are upserted.
+    #
+    # @param id [String] the Work ID.
+    # @param small [String, nil] IIIF URI for the small derivative.
+    # @param medium [String, nil] IIIF URI for the medium derivative.
+    # @param large [String, nil] IIIF URI for the large derivative.
+    # @return [AtlasRb::Mash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Work.set_image_derivatives(
+    #     "w-789",
+    #     small:  "https://iiif.example.edu/iiif/3/abc.jp2/full/800,/0/default.jpg",
+    #     medium: "https://iiif.example.edu/iiif/3/abc.jp2/full/1600,/0/default.jpg",
+    #     large:  "https://iiif.example.edu/iiif/3/abc.jp2/full/full/0/default.jpg"
+    #   )
+    def self.set_image_derivatives(id, small: nil, medium: nil, large: nil)
+      body = { small: small, medium: medium, large: large }.compact
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}).patch(ROUTE + id + '/image_derivatives', JSON.dump(body))&.body
+      ))
+    end
+
+    # List the assets attached to a Work — {Blob}s and {Delegate}s alike.
     #
     # Useful for building download UIs — the response includes enough to
-    # render each file's display name, size, and download URL.
+    # render each entry's display name, size or `uri`, and download URL.
+    # The shape is polymorphic: Blob-backed entries carry fields like
+    # `size`, while Delegate-backed entries carry `uri`. Callers should
+    # duck-type on the field they need rather than expecting a single
+    # schema.
     #
     # @param id [String] the Work ID.
-    # @return [Array<AtlasRb::Mash>] the listing from `GET /works/<id>/files`,
-    #   one entry per attached file.
+    # @return [Array<AtlasRb::Mash>] the listing from `GET /works/<id>/assets`,
+    #   one entry per attached asset.
     #
     # @example
-    #   AtlasRb::Work.files("w-789").each { |f| puts f.label }
+    #   AtlasRb::Work.assets("w-789").each { |a| puts a.label }
+    def self.assets(id)
+      JSON.parse(connection({}).get(ROUTE + id + '/assets')&.body).map { |entry| AtlasRb::Mash.new(entry) }
+    end
+
+    # @deprecated Use {.assets} instead. Will be removed in the next release.
     def self.files(id)
-      JSON.parse(connection({}).get(ROUTE + id + '/files')&.body).map { |entry| AtlasRb::Mash.new(entry) }
+      assets(id)
     end
 
     # Fetch the Work's MODS representation in the requested format.

data/lib/atlas_rb.rb

@@ -13,6 +13,7 @@ require_relative "atlas_rb/collection"
 require_relative "atlas_rb/work"
 require_relative "atlas_rb/file_set"
 require_relative "atlas_rb/blob"
+require_relative "atlas_rb/delegate"
 require_relative "atlas_rb/user"
 
 # Ruby client for the Atlas API — Northeastern University's institutional

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 0.0.92
+  version: 0.0.95
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -118,6 +118,7 @@ files:
 - lib/atlas_rb/blob.rb
 - lib/atlas_rb/collection.rb
 - lib/atlas_rb/community.rb
+- lib/atlas_rb/delegate.rb
 - lib/atlas_rb/faraday_helper.rb
 - lib/atlas_rb/file_set.rb
 - lib/atlas_rb/mash.rb