apertur-sdk 0.1.0

data/lib/apertur/resources/keys.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Manage API keys within a project.
+    class Keys
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List all API keys for a project.
+      #
+      # @param project_id [String] the project ID
+      # @return [Array<Hash>] list of API keys
+      def list(project_id)
+        @http.request(:get, "/api/v1/projects/#{project_id}/keys")
+      end
+
+      # Create a new API key.
+      #
+      # @param project_id [String] the project ID
+      # @param options [Hash] key configuration (e.g. +name+, +scopes+)
+      # @return [Hash] the created key, including the plaintext secret (shown only once)
+      def create(project_id, **options)
+        @http.request(:post, "/api/v1/projects/#{project_id}/keys", body: options)
+      end
+
+      # Update an existing API key.
+      #
+      # @param project_id [String] the project ID
+      # @param key_id [String] the key ID
+      # @param options [Hash] fields to update
+      # @return [Hash] the updated key
+      def update(project_id, key_id, **options)
+        @http.request(:patch, "/api/v1/projects/#{project_id}/keys/#{key_id}", body: options)
+      end
+
+      # Delete an API key.
+      #
+      # @param project_id [String] the project ID
+      # @param key_id [String] the key ID
+      # @return [nil]
+      def delete(project_id, key_id)
+        @http.request(:delete, "/api/v1/projects/#{project_id}/keys/#{key_id}")
+      end
+
+      # Set the destinations and long-polling configuration for a key.
+      #
+      # @param key_id [String] the key ID
+      # @param destination_ids [Array<String>] destination IDs to associate
+      # @param long_polling_enabled [Boolean] whether to enable long-polling (default: false)
+      # @return [Hash] the updated key-destinations mapping
+      def set_destinations(key_id, destination_ids, long_polling_enabled: false)
+        body = { destination_ids: destination_ids }
+        body[:long_polling_enabled] = long_polling_enabled unless long_polling_enabled.nil?
+        @http.request(:put, "/api/v1/keys/#{key_id}/destinations", body: body)
+      end
+    end
+  end
+end

data/lib/apertur/resources/polling.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Poll upload sessions for new images and download them.
+    #
+    # Provides a blocking polling loop ({#poll_and_process}) that fetches,
+    # downloads, and acknowledges new images automatically.
+    class Polling
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List pending (un-acknowledged) images in a session.
+      #
+      # @param uuid [String] the session UUID
+      # @return [Hash] poll result containing an +images+ array
+      def list(uuid)
+        @http.request(:get, "/api/v1/upload-sessions/#{uuid}/poll")
+      end
+
+      # Download an image from a session.
+      #
+      # @param uuid [String] the session UUID
+      # @param image_id [String] the image ID
+      # @return [String] raw binary image data
+      def download(uuid, image_id)
+        @http.request_raw(:get, "/api/v1/upload-sessions/#{uuid}/images/#{image_id}")
+      end
+
+      # Acknowledge (mark as processed) an image.
+      #
+      # @param uuid [String] the session UUID
+      # @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")
+      end
+
+      # Blocking polling loop that fetches, downloads, and acknowledges images.
+      #
+      # Calls the provided block for each new image. The loop runs until the
+      # calling thread is interrupted or the block raises an exception.
+      #
+      # @param uuid [String] the session UUID
+      # @param interval [Numeric] seconds between poll cycles (default: 3)
+      # @yield [image, data] called for each new image
+      # @yieldparam image [Hash] image metadata from the poll response
+      # @yieldparam data [String] raw binary image data
+      # @return [void]
+      def poll_and_process(uuid, interval: 3, &handler)
+        raise ArgumentError, "A block is required" unless block_given?
+
+        loop do
+          result = list(uuid)
+          images = result["images"] || []
+
+          images.each do |image|
+            data = download(uuid, image["id"])
+            handler.call(image, data)
+            ack(uuid, image["id"])
+          end
+
+          sleep(interval)
+        end
+      end
+    end
+  end
+end

data/lib/apertur/resources/sessions.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Manage upload sessions.
+    #
+    # Upload sessions represent a time-limited context in which one or more
+    # images can be uploaded. Each session has a unique UUID, optional password
+    # protection, and configurable constraints.
+    class Sessions
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # Create a new upload session.
+      #
+      # @param destination_ids [Array<String>, nil] destination IDs to deliver images to
+      # @param long_polling [Boolean, nil] whether to enable long-polling on this session
+      # @param tags [Array<String>, nil] tags to attach to the session
+      # @param expires_in_hours [Integer, nil] hours until the session expires
+      # @param expires_at [String, nil] ISO 8601 expiry timestamp
+      # @param max_images [Integer, nil] maximum number of images allowed
+      # @param allowed_mime_types [Array<String>, nil] allowed MIME types for uploads
+      # @param max_image_dimension [Integer, nil] maximum image dimension in pixels
+      # @param password [String, nil] optional password to protect the session
+      # @return [Hash] the created session details including +uuid+ and +upload_url+
+      def create(**options)
+        @http.request(:post, "/api/v1/upload-sessions", body: options)
+      end
+
+      # Retrieve an existing upload session by UUID.
+      #
+      # @param uuid [String] the session UUID
+      # @return [Hash] session details
+      def get(uuid)
+        @http.request(:get, "/api/v1/upload/#{uuid}/session")
+      end
+
+      # Update an existing upload session.
+      #
+      # @param uuid [String] the session UUID
+      # @param options [Hash] fields to update (same options as {#create})
+      # @return [Hash] the updated session
+      def update(uuid, **options)
+        @http.request(:patch, "/api/v1/upload-sessions/#{uuid}", body: options)
+      end
+
+      # List upload sessions with pagination.
+      #
+      # @param page [Integer, nil] page number
+      # @param page_size [Integer, nil] number of results per page
+      # @return [Hash] paginated list with +data+ and pagination metadata
+      def list(**params)
+        query = {}
+        query["page"] = params[:page].to_s if params[:page]
+        query["pageSize"] = params[:page_size].to_s if params[:page_size]
+        @http.request(:get, "/api/v1/sessions", query: query)
+      end
+
+      # List recent upload sessions.
+      #
+      # @param limit [Integer, nil] maximum number of sessions to return
+      # @return [Array<Hash>] recent sessions
+      def recent(**params)
+        query = {}
+        query["limit"] = params[:limit].to_s if params[:limit]
+        @http.request(:get, "/api/v1/sessions/recent", query: query)
+      end
+
+      # Get the QR code image for an upload session.
+      #
+      # @param uuid [String] the session UUID
+      # @param format [String, nil] image format (e.g. "png", "svg")
+      # @param size [Integer, nil] QR code size in pixels
+      # @param style [String, nil] QR code style
+      # @param fg [String, nil] foreground color
+      # @param bg [String, nil] background color
+      # @param border_size [Integer, nil] border size in pixels
+      # @param border_color [String, nil] border color
+      # @return [String] raw binary image data
+      def qr(uuid, **options)
+        query = {}
+        query["format"] = options[:format] if options[:format]
+        query["size"] = options[:size].to_s if options[:size]
+        query["style"] = options[:style] if options[:style]
+        query["fg"] = options[:fg] if options[:fg]
+        query["bg"] = options[:bg] if options[:bg]
+        query["borderSize"] = options[:border_size].to_s if options[:border_size]
+        query["borderColor"] = options[:border_color] if options[:border_color]
+        @http.request_raw(:get, "/api/v1/upload-sessions/#{uuid}/qr", query: query)
+      end
+
+      # Verify a session password.
+      #
+      # @param uuid [String] the session UUID
+      # @param password [String] the password to verify
+      # @return [Hash] result with +valid+ boolean
+      def verify_password(uuid, password)
+        @http.request(:post, "/api/v1/upload/#{uuid}/verify-password", body: { password: password })
+      end
+
+      # Get the delivery status for a session.
+      #
+      # @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")
+      end
+    end
+  end
+end

data/lib/apertur/resources/stats.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Retrieve account usage statistics.
+    class Stats
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # Get current account statistics.
+      #
+      # @return [Hash] usage statistics (uploads, sessions, storage, etc.)
+      def get
+        @http.request(:get, "/api/v1/stats")
+      end
+    end
+  end
+end

data/lib/apertur/resources/upload.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Upload images to a session.
+    #
+    # Supports both plaintext multipart uploads and client-side encrypted
+    # uploads using AES-256-GCM with RSA-OAEP key wrapping.
+    class Upload
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # Upload an image to a session via multipart/form-data.
+      #
+      # @param uuid [String] the session UUID
+      # @param file [String, IO] a file path (String), an IO-like object responding
+      #   to +read+, or raw image bytes (binary String)
+      # @param filename [String] the filename to send (default: "image.jpg")
+      # @param mime_type [String] the MIME type of the image (default: "image/jpeg")
+      # @param source [String, nil] an optional source identifier
+      # @param password [String, nil] session password if the session is protected
+      # @return [Hash] upload result
+      def image(uuid, file, filename: "image.jpg", mime_type: "image/jpeg", source: nil, password: nil)
+        file_data = read_file(file)
+
+        fields = {}
+        fields["source"] = source if source
+
+        headers = {}
+        headers["x-session-password"] = password if password
+
+        @http.request_multipart(
+          "/api/v1/upload/#{uuid}/images",
+          file_data,
+          filename: filename,
+          mime_type: mime_type,
+          fields: fields,
+          headers: headers
+        )
+      end
+
+      # Upload an encrypted image to a session.
+      #
+      # The image is encrypted client-side using AES-256-GCM, with the AES key
+      # wrapped by the server's RSA public key. The encrypted payload is sent as
+      # JSON with the +X-Aptr-Encrypted: default+ header.
+      #
+      # @param uuid [String] the session UUID
+      # @param file [String, IO] a file path, IO, or raw bytes
+      # @param public_key [String] the RSA public key in PEM format
+      # @param filename [String] the filename (default: "image.jpg")
+      # @param mime_type [String] the MIME type (default: "image/jpeg")
+      # @param source [String, nil] optional source identifier
+      # @param password [String, nil] session password if the session is protected
+      # @return [Hash] upload result
+      def image_encrypted(uuid, file, public_key, filename: "image.jpg", mime_type: "image/jpeg", source: nil, password: nil)
+        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"
+        )
+
+        headers = {
+          "X-Aptr-Encrypted" => "default"
+        }
+        headers["x-session-password"] = password if password
+
+        @http.request(:post, "/api/v1/upload/#{uuid}/images", body: payload, headers: headers)
+      end
+
+      private
+
+      # Normalize file input to raw bytes.
+      #
+      # @param file [String, IO] file path, IO object, or raw bytes
+      # @return [String] raw binary data
+      def read_file(file)
+        if file.respond_to?(:read)
+          file.read.b
+        elsif file.is_a?(String) && File.exist?(file) && file.length < 1024
+          # 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.
+          File.binread(file)
+        elsif file.is_a?(String)
+          file.b
+        else
+          raise ArgumentError, "Unsupported file input. Use a file path String, IO object, or raw String bytes."
+        end
+      end
+    end
+  end
+end

data/lib/apertur/resources/uploads.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Browse completed uploads.
+    class Uploads
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List uploads with pagination.
+      #
+      # @param page [Integer, nil] page number
+      # @param page_size [Integer, nil] number of results per page
+      # @return [Hash] paginated list with +data+ and pagination metadata
+      def list(**params)
+        query = {}
+        query["page"] = params[:page].to_s if params[:page]
+        query["pageSize"] = params[:page_size].to_s if params[:page_size]
+        @http.request(:get, "/api/v1/uploads", query: query)
+      end
+
+      # List recent uploads.
+      #
+      # @param limit [Integer, nil] maximum number of uploads to return
+      # @return [Array<Hash>] recent uploads
+      def recent(**params)
+        query = {}
+        query["limit"] = params[:limit].to_s if params[:limit]
+        @http.request(:get, "/api/v1/uploads/recent", query: query)
+      end
+    end
+  end
+end

data/lib/apertur/resources/webhooks.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Manage event webhooks within a project.
+    class Webhooks
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List all webhooks for a project.
+      #
+      # @param project_id [String] the project ID
+      # @return [Array<Hash>] list of webhooks
+      def list(project_id)
+        @http.request(:get, "/api/v1/projects/#{project_id}/webhooks")
+      end
+
+      # Create a new webhook.
+      #
+      # @param project_id [String] the project ID
+      # @param config [Hash] webhook configuration (e.g. +url+, +events+, +secret+)
+      # @return [Hash] the created webhook
+      def create(project_id, **config)
+        @http.request(:post, "/api/v1/projects/#{project_id}/webhooks", body: config)
+      end
+
+      # Update an existing webhook.
+      #
+      # @param project_id [String] the project ID
+      # @param webhook_id [String] the webhook ID
+      # @param config [Hash] fields to update
+      # @return [Hash] the updated webhook
+      def update(project_id, webhook_id, **config)
+        @http.request(:patch, "/api/v1/projects/#{project_id}/webhooks/#{webhook_id}", body: config)
+      end
+
+      # Delete a webhook.
+      #
+      # @param project_id [String] the project ID
+      # @param webhook_id [String] the webhook ID
+      # @return [nil]
+      def delete(project_id, webhook_id)
+        @http.request(:delete, "/api/v1/projects/#{project_id}/webhooks/#{webhook_id}")
+      end
+
+      # Send a test event to a webhook.
+      #
+      # @param project_id [String] the project ID
+      # @param webhook_id [String] the webhook ID
+      # @return [Hash] test result
+      def test(project_id, webhook_id)
+        @http.request(:post, "/api/v1/projects/#{project_id}/webhooks/#{webhook_id}/test")
+      end
+
+      # List delivery attempts for a webhook.
+      #
+      # @param project_id [String] the project ID
+      # @param webhook_id [String] the webhook ID
+      # @param page [Integer, nil] page number
+      # @param limit [Integer, nil] number of results per page
+      # @return [Hash] paginated delivery list
+      def deliveries(project_id, webhook_id, **options)
+        query = {}
+        query["page"] = options[:page].to_s if options[:page]
+        query["limit"] = options[:limit].to_s if options[:limit]
+        @http.request(:get, "/api/v1/projects/#{project_id}/webhooks/#{webhook_id}/deliveries", query: query)
+      end
+
+      # Retry a failed delivery attempt.
+      #
+      # @param project_id [String] the project ID
+      # @param webhook_id [String] the webhook ID
+      # @param delivery_id [String] the delivery ID
+      # @return [Hash] retry result
+      def retry_delivery(project_id, webhook_id, delivery_id)
+        @http.request(
+          :post,
+          "/api/v1/projects/#{project_id}/webhooks/#{webhook_id}/deliveries/#{delivery_id}/retry"
+        )
+      end
+    end
+  end
+end

data/lib/apertur/signature.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Apertur
+  # Webhook signature verification utilities.
+  #
+  # Provides constant-time signature verification for three webhook formats
+  # used by the Apertur platform.
+  module Signature
+    module_function
+
+    # Verify an image delivery webhook signature.
+    #
+    # The signature header is formatted as +sha256=<hex>+ and is computed as
+    # +HMAC-SHA256(body, secret)+.
+    #
+    # @param body [String] the raw request body
+    # @param signature [String] the signature header value (e.g. "sha256=abc123...")
+    # @param secret [String] the webhook signing secret
+    # @return [Boolean] true if the signature is valid
+    def verify_webhook(body, signature, secret)
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
+      sig = signature.start_with?("sha256=") ? signature[7..] : signature
+      secure_compare(expected, sig)
+    end
+
+    # Verify an event webhook signature (HMAC SHA256 method).
+    #
+    # The signed payload is +"\#{timestamp}.\#{body}"+ and the signature header
+    # is formatted as +sha256=<hex>+.
+    #
+    # @param body [String] the raw request body
+    # @param timestamp [String] the X-Apertur-Timestamp header value
+    # @param signature [String] the X-Apertur-Signature header value
+    # @param secret [String] the webhook signing secret
+    # @return [Boolean] true if the signature is valid
+    def verify_event(body, timestamp, signature, secret)
+      signature_base = "#{timestamp}.#{body}"
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, signature_base)
+      sig = signature.start_with?("sha256=") ? signature[7..] : signature
+      secure_compare(expected, sig)
+    end
+
+    # Verify an event webhook signature (Svix method).
+    #
+    # The signed payload is +"\#{svix_id}.\#{timestamp}.\#{body}"+ and the
+    # signing key is the secret decoded from hex. The signature header is
+    # formatted as +v1,<base64>+.
+    #
+    # @param body [String] the raw request body
+    # @param svix_id [String] the svix-id header value
+    # @param timestamp [String] the svix-timestamp header value
+    # @param signature [String] the svix-signature header value (e.g. "v1,base64...")
+    # @param secret [String] the webhook signing secret (hex-encoded)
+    # @return [Boolean] true if the signature is valid
+    def verify_svix(body, svix_id, timestamp, signature, secret)
+      signature_base = "#{svix_id}.#{timestamp}.#{body}"
+      key = [secret].pack("H*")
+      expected = OpenSSL::HMAC.digest("SHA256", key, signature_base)
+      expected_b64 = [expected].pack("m0")
+      sig = signature.start_with?("v1,") ? signature[3..] : signature
+      secure_compare(expected_b64, sig)
+    end
+
+    # Constant-time string comparison to prevent timing attacks.
+    #
+    # @param a [String]
+    # @param b [String]
+    # @return [Boolean]
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/apertur/version.rb

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

data/lib/apertur.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "apertur/version"
+require_relative "apertur/errors"
+require_relative "apertur/http_client"
+require_relative "apertur/signature"
+require_relative "apertur/crypto"
+require_relative "apertur/resources/sessions"
+require_relative "apertur/resources/upload"
+require_relative "apertur/resources/uploads"
+require_relative "apertur/resources/polling"
+require_relative "apertur/resources/destinations"
+require_relative "apertur/resources/keys"
+require_relative "apertur/resources/webhooks"
+require_relative "apertur/resources/encryption"
+require_relative "apertur/resources/stats"
+require_relative "apertur/client"
+
+# Ruby SDK for the Apertur image upload API.
+#
+# @example Quick start
+#   require "apertur"
+#
+#   client = Apertur::Client.new(api_key: "aptr_test_abc123")
+#   session = client.sessions.create(max_images: 5)
+#   client.upload.image(session["uuid"], "/path/to/photo.jpg")
+#
+# @example Verify a webhook signature
+#   Apertur::Signature.verify_webhook(request_body, signature_header, secret)
+#
+# @see Apertur::Client
+# @see Apertur::Signature
+# @see Apertur::Crypto
+module Apertur; end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: apertur-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Apertur
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-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,
+  webhooks, and more.
+email:
+- support@aptr.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/apertur.rb
+- lib/apertur/client.rb
+- lib/apertur/crypto.rb
+- lib/apertur/errors.rb
+- lib/apertur/http_client.rb
+- lib/apertur/resources/destinations.rb
+- lib/apertur/resources/encryption.rb
+- lib/apertur/resources/keys.rb
+- lib/apertur/resources/polling.rb
+- lib/apertur/resources/sessions.rb
+- lib/apertur/resources/stats.rb
+- lib/apertur/resources/upload.rb
+- lib/apertur/resources/uploads.rb
+- lib/apertur/resources/webhooks.rb
+- lib/apertur/signature.rb
+- lib/apertur/version.rb
+homepage: https://github.com/Apertur-dev/apertur-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Apertur-dev/apertur-ruby
+  source_code_uri: https://github.com/Apertur-dev/apertur-ruby
+  changelog_uri: https://github.com/Apertur-dev/apertur-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.apertur.ca
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for the Apertur API
+test_files: []