atlas_rb 1.27.4 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98ed27c0812607ce56681c0dd9b3ab4c17fc1224c7e3c36bf0aa5b4deb7527e9
-  data.tar.gz: 401ebcc7d93621d999c2b6441f0e470ee6b68c2081e0eb104e5f059330310004
+  metadata.gz: c3b06407e57e241d5ddcd1a8ebef36efbe6c3e5c778e4d6fbdd09826694a8716
+  data.tar.gz: 3164c9a3a4a67944846a5fe81af5eda1095a757210db01bed15eafb6fb2ea369
 SHA512:
-  metadata.gz: 604f5e4183097244b9759cbf0caf188abf45ca936a7f9a07f3a476a4cb05dee0aa23f65357114bbdd9525e85d2c6ae746f0dba330f05cc4f3b978ae077778900
-  data.tar.gz: e9d53ba6883acc6decc743d4e480a682918c7f6db19e550e97d5455836a31250a29430ba846df03fab075cd410cff11b6c01ffe257522898c47c9f27d708b723
+  metadata.gz: ca3e4e74dce382bf33b72d9a294779576249ac3f949e6821647dd9a79bbb50b6cf5719c98198263ceae99c4412fb5ff0a77ec568a44bd19bca8ac6833d1f6eb2
+  data.tar.gz: 32ebc73d97471c1fb8419bd4c2b2e9f61b0a81780b0f0cc842edad6c7adddcdb3e100e8c66119c8198b0afaadb23c306e909d8d1a8463aedd99a9bf2a8788beb

data/.version

@@ -1 +1 @@
-1.27.4
+1.28.0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.28.0
+
+Requires an Atlas that stores the preview image's size and placeholder (0.6.234
+or later). An older Atlas ignores the new keys.
+
+### Added — the preview's size and placeholder on `Resource.set_thumbnails`
+
+`preview_width:`, `preview_height:` and `preview_placeholder:` ride the PATCH
+body beside `preview:`. Each is optional, and a `nil` is not sent. Atlas writes
+them only with a `preview` URI and clears them when a `preview` arrives without
+them, so pass them on every preview write. A malformed value, or one sent
+without `preview`, raises `ResourceError` with status 422 and an `error` code.
+
+`Work.find`, `Collection.find` and `Community.find` return the three keys
+beside `"preview"`, each `nil` when Atlas holds none.
+
 ## 1.27.4
 
 Requires an Atlas that serves `GET /works/:id/health_check` (0.6.232 or later).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.27.4)
+    atlas_rb (1.28.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -16,7 +16,7 @@ GEM
     base64 (0.3.0)
     connection_pool (2.5.5)
     diff-lcs (1.6.1)
-    faraday (2.15.0)
+    faraday (2.15.1)
       faraday-net_http (>= 2.0, < 3.6)
       json
       logger

data/lib/atlas_rb/collection.rb

@@ -32,6 +32,9 @@ module AtlasRb
     #   omitted.
     # @return [Hash, nil] the `"collection"` object, already unwrapped from the
     #   JSON response, or `nil` when the Collection does not exist (`404`).
+    #   The preview image rides beside it: `"preview"` is its URI, and
+    #   `"preview_width"`, `"preview_height"` and `"preview_placeholder"` (base64
+    #   of a ~16px-wide JPEG) describe it. Each is `nil` when Atlas holds none.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #

data/lib/atlas_rb/community.rb

@@ -30,6 +30,9 @@ module AtlasRb
     #   omitted.
     # @return [Hash, nil] the `"community"` object from the JSON response,
     #   already unwrapped, or `nil` when the Community does not exist (`404`).
+    #   The preview image rides beside it: `"preview"` is its URI, and
+    #   `"preview_width"`, `"preview_height"` and `"preview_placeholder"` (base64
+    #   of a ~16px-wide JPEG) describe it. Each is `nil` when Atlas holds none.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #

data/lib/atlas_rb/resource_writes.rb

@@ -136,19 +136,39 @@ module AtlasRb
     #
     # Only the URIs you pass are upserted; an omitted key is left untouched.
     #
+    # The preview's size and placeholder are written only with `preview`, and
+    # Atlas answers `422` for one sent without it. A `preview` sent without them
+    # clears the stored ones, so pass them on every preview write.
+    #
     # @param id [String] the resource's NOID.
     # @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.
+    # @param preview_width [Integer, nil] pixel width of the image `preview`
+    #   serves. Send it with `preview_height`.
+    # @param preview_height [Integer, nil] pixel height of the image `preview`
+    #   serves. Send it with `preview_width`.
+    # @param preview_placeholder [String, nil] base64 of a ~16px-wide JPEG of
+    #   that image, at most 2048 characters. The bytes only, not a data URI.
     # @param nuid [String, nil] optional acting user's NUID.
     # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
     #   header.
     # @return [AtlasRb::Mash] the resource, unwrapped from its type key.
     # @raise [AtlasRb::NotFoundError] on `404` — the write did not happen.
     # @raise [AtlasRb::StaleResourceError] on an optimistic-lock conflict.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx.
-    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil, on_behalf_of: nil)
-      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, including the `422`
+    #   whose `error` names a malformed size or placeholder.
+    #
+    # @example A preview with its size and placeholder
+    #   AtlasRb::Resource.set_thumbnails("w-789", preview: uri,
+    #                                    preview_width: 500, preview_height: 375,
+    #                                    preview_placeholder: Base64.strict_encode64(tiny_jpeg))
+    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil,
+                            preview_width: nil, preview_height: nil, preview_placeholder: nil,
+                            nuid: nil, on_behalf_of: nil)
+      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview,
+               preview_width: preview_width, preview_height: preview_height,
+               preview_placeholder: preview_placeholder }.compact
       unwrap(write_resource(
                connection({}, nuid, on_behalf_of: on_behalf_of)
                  .patch('/resources/' + id + '/thumbnails', JSON.dump(body))

data/lib/atlas_rb/work.rb

@@ -29,6 +29,9 @@ module AtlasRb
     #   {AtlasRb.config}.default_on_behalf_of when omitted.
     # @return [Hash, nil] the `"work"` object, already unwrapped from the JSON
     #   response, or `nil` when the Work does not exist (`404`).
+    #   The preview image rides beside it: `"preview"` is its URI, and
+    #   `"preview_width"`, `"preview_height"` and `"preview_placeholder"` (base64
+    #   of a ~16px-wide JPEG) describe it. Each is `nil` when Atlas holds none.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #

metadata

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