apertur-sdk 0.1.0 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43690cd24afff7146d8e06a8fa97981242ac044b9f681c594101f648f3771016
-  data.tar.gz: e9e4f5fd4d7097ae37a482fe44acf6277ea5bfe47abc730363ad86e1e4719aa2
+  metadata.gz: eefd130f1dc0dfc251471d88510fb28d2464ddfe23b8a3c5055404708d1118a4
+  data.tar.gz: e33c04ea6e50216fe7988d2d5fd05e0327de309bbd26d6956098a86ef07afa4e
 SHA512:
-  metadata.gz: 242ce180cfb7061f9e232bfafb3c469fd4c7bb47b0ddf194150d97a17f734f25b224ece23e3cff1ee21b15bdc6eb04572a65b8a0e1de740748f8194a0520a4fb
-  data.tar.gz: a672905ff810166a17076d8db8df271002489399b08ed56f9b156135f7550f2d1493bf8c78ee2c49f401fd519ce30c671d6af358485bb085c9b604d1b1238388
+  metadata.gz: '08c21fe268c9ddf93ddd2aa5d44e7a0312051287b272b639a7b131212384ef91c7020f13ae7ac86a7818ce6372a6e7a0fccbf8247df0102b4e5d20ae3f341685'
+  data.tar.gz: 62d086c9c4ab7c9122831fc579e5224764ed892874df7a686ed603ad7eeed2a7c8f50c2c1d41511c72c5922eb243ddd2345b140c9f1f32219a34b7eade389ed1

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/polling.rb

@@ -35,7 +35,9 @@ module Apertur
       # @param image_id [String] the image ID
       # @return [Hash] acknowledgement status
       def ack(uuid, image_id)
-        @http.request(:post, "/api/v1/upload-sessions/#{uuid}/images/#{image_id}/ack")
+        # The server requires a JSON body on this endpoint; sending none
+        # results in a 500. An empty object is sufficient.
+        @http.request(:post, "/api/v1/upload-sessions/#{uuid}/images/#{image_id}/ack", body: {})
       end
 
       # Blocking polling loop that fetches, downloads, and acknowledges images.

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/resources/upload.rb

@@ -59,18 +59,31 @@ module Apertur
         file_data = read_file(file)
         encrypted = Apertur::Crypto.encrypt_image(file_data, public_key)
 
-        payload = encrypted.merge(
-          "filename" => filename,
-          "mimeType" => mime_type,
-          "source" => source || "sdk"
+        # The server's "default" encryption mode expects a multipart file
+        # upload whose body is the JSON-serialized EncryptedPayload (camelCase
+        # keys), which it then decrypts with its private key. Sending a JSON
+        # request body instead yields a 500 ("No file uploaded").
+        payload_json = JSON.generate(
+          "encryptedKey" => encrypted["encrypted_key"],
+          "iv" => encrypted["iv"],
+          "encryptedData" => encrypted["encrypted_data"],
+          "algorithm" => encrypted["algorithm"]
         )
 
-        headers = {
-          "X-Aptr-Encrypted" => "default"
-        }
+        fields = {}
+        fields["source"] = source if source
+
+        headers = { "X-Aptr-Encrypted" => "default" }
         headers["x-session-password"] = password if password
 
-        @http.request(:post, "/api/v1/upload/#{uuid}/images", body: payload, headers: headers)
+        @http.request_multipart(
+          "/api/v1/upload/#{uuid}/images",
+          payload_json,
+          filename: "#{filename}.enc",
+          mime_type: "application/octet-stream",
+          fields: fields,
+          headers: headers
+        )
       end
 
       private
@@ -82,7 +95,7 @@ module Apertur
       def read_file(file)
         if file.respond_to?(:read)
           file.read.b
-        elsif file.is_a?(String) && File.exist?(file) && file.length < 1024
+        elsif file.is_a?(String) && looks_like_path?(file) && File.exist?(file)
           # Treat short strings that point to existing files as paths.
           # Raw image bytes will almost never be < 1024 bytes AND match an
           # existing filename, so this heuristic is safe in practice.
@@ -93,6 +106,17 @@ module Apertur
           raise ArgumentError, "Unsupported file input. Use a file path String, IO object, or raw String bytes."
         end
       end
+
+      # Heuristic: does this String plausibly name a file path (as opposed to
+      # raw image bytes)? Must be short and contain no NUL byte. Calling
+      # File.exist? on binary image data that contains a NUL byte raises
+      # "ArgumentError: path name contains null byte", so we must guard it.
+      #
+      # @param str [String]
+      # @return [Boolean]
+      def looks_like_path?(str)
+        str.length < 1024 && !str.include?("\x00")
+      end
     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.6"
 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.6
 platform: ruby
 authors:
 - Apertur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-06-14 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,