apertur-sdk 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43690cd24afff7146d8e06a8fa97981242ac044b9f681c594101f648f3771016
-  data.tar.gz: e9e4f5fd4d7097ae37a482fe44acf6277ea5bfe47abc730363ad86e1e4719aa2
+  metadata.gz: 8e13b276ea448173ed53e96ce31df30060b576c768acd1012bc9df6df2030375
+  data.tar.gz: ed633c8bd5e7509b7ef7f7a98e63fa2b8912048ca141e9230e184cff16eca960
 SHA512:
-  metadata.gz: 242ce180cfb7061f9e232bfafb3c469fd4c7bb47b0ddf194150d97a17f734f25b224ece23e3cff1ee21b15bdc6eb04572a65b8a0e1de740748f8194a0520a4fb
-  data.tar.gz: a672905ff810166a17076d8db8df271002489399b08ed56f9b156135f7550f2d1493bf8c78ee2c49f401fd519ce30c671d6af358485bb085c9b604d1b1238388
+  metadata.gz: 617cd4b37d3da2fffe8292367cbd336d42076fed098eaa72e77360b1440911b73ba22bb664b104bf73c7d8bc41279c2d3656ae113ba7630ca4c598de3c3b44e9
+  data.tar.gz: 3806c669fb2bcb4eac40c7d4ecebed20a98993a6a19e82d13c2f290277e6b47b4d21122d9f525197cf2b65e17fb1d61bb31487e0fd2b5a066a762fa8bdc2dc8a

data/README.md

@@ -64,7 +64,15 @@ client.sessions.list(page: 1, page_size: 20)
 client.sessions.recent(limit: 5)
 client.sessions.qr("uuid", format: "png", size: 300)
 client.sessions.verify_password("uuid", "secret")
+
+# Delivery status returns:
+#   { "status" => "pending|active|completed|expired",
+#     "files" => [...], "lastChanged" => "<ISO 8601>" }
 client.sessions.delivery_status("uuid")
+
+# Long-poll: server holds up to 5 min until something changes. Passing
+# `poll_from:` widens the per-request read timeout to 360 s automatically.
+client.sessions.delivery_status("uuid", poll_from: "2026-04-18T12:34:56Z")
 ```
 
 ### Upload

data/lib/apertur/http_client.rb

@@ -25,9 +25,11 @@ module Apertur
     # @param body [Hash, nil] request body to be serialized as JSON
     # @param query [Hash, nil] query parameters
     # @param headers [Hash] additional request headers
+    # @param read_timeout [Integer, Float, nil] override the per-request
+    #   read timeout (seconds). Defaults to the connection default (60s).
     # @return [Hash, Array, nil] parsed JSON response, or nil for 204
     # @raise [Apertur::Error] on API errors
-    def request(method, path, body: nil, query: nil, headers: {})
+    def request(method, path, body: nil, query: nil, headers: {}, read_timeout: nil)
       uri = build_uri(path, query)
       req = build_request(method, uri, headers)
 
@@ -36,7 +38,7 @@ module Apertur
         req.body = body.is_a?(String) ? body : JSON.generate(body)
       end
 
-      response = execute(uri, req)
+      response = execute(uri, req, read_timeout: read_timeout)
       handle_response(response)
     end
 
@@ -119,12 +121,14 @@ module Apertur
 
     # @param uri [URI]
     # @param req [Net::HTTPRequest]
+    # @param read_timeout [Integer, Float, nil] optional override for
+    #   +Net::HTTP#read_timeout+ (seconds).
     # @return [Net::HTTPResponse]
-    def execute(uri, req)
+    def execute(uri, req, read_timeout: nil)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = (uri.scheme == "https")
       http.open_timeout = 30
-      http.read_timeout = 60
+      http.read_timeout = read_timeout || 60
       http.request(req)
     end
 

data/lib/apertur/resources/sessions.rb

@@ -102,10 +102,33 @@ module Apertur
 
       # Get the delivery status for a session.
       #
+      # Returns a hash with the following shape:
+      #
+      #   {
+      #     "status"      => "pending" | "active" | "completed" | "expired",
+      #     "files"       => [ { "record_id" => ..., "filename" => ..., "size_bytes" => ...,
+      #                          "destinations" => [ { "destination_id" => ..., "status" => ..., ... } ] } ],
+      #     "lastChanged" => "<ISO 8601>"
+      #   }
+      #
+      # When +poll_from+ (ISO 8601 timestamp) is provided, the server long-polls for
+      # up to 5 minutes waiting for something to change before responding. This call
+      # automatically widens the read timeout to 360 s (6 min) in that case so the
+      # server releases first under the happy path.
+      #
       # @param uuid [String] the session UUID
-      # @return [Array<Hash>] delivery status records
-      def delivery_status(uuid)
-        @http.request(:get, "/api/v1/upload-sessions/#{uuid}/delivery-status")
+      # @param poll_from [String, nil] ISO 8601 timestamp; when set, enables long-poll mode
+      # @return [Hash] delivery status snapshot
+      def delivery_status(uuid, poll_from: nil)
+        query = {}
+        query["pollFrom"] = poll_from if poll_from
+        read_timeout = poll_from ? 360 : nil
+        @http.request(
+          :get,
+          "/api/v1/upload-sessions/#{uuid}/delivery-status",
+          query: query,
+          read_timeout: read_timeout,
+        )
       end
     end
   end

data/lib/apertur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apertur
-  VERSION = "0.1.0"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apertur-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.5
 platform: ruby
 authors:
 - Apertur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-04-18 00:00:00.000000000 Z
 dependencies: []
 description: Official Ruby client for the Apertur image upload and delivery API. Supports
   session management, image uploads (including client-side encryption), polling, destinations,