apertur-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43690cd24afff7146d8e06a8fa97981242ac044b9f681c594101f648f3771016
+  data.tar.gz: e9e4f5fd4d7097ae37a482fe44acf6277ea5bfe47abc730363ad86e1e4719aa2
+SHA512:
+  metadata.gz: 242ce180cfb7061f9e232bfafb3c469fd4c7bb47b0ddf194150d97a17f734f25b224ece23e3cff1ee21b15bdc6eb04572a65b8a0e1de740748f8194a0520a4fb
+  data.tar.gz: a672905ff810166a17076d8db8df271002489399b08ed56f9b156135f7550f2d1493bf8c78ee2c49f401fd519ce30c671d6af358485bb085c9b604d1b1238388

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Apertur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# Apertur Ruby SDK
+
+Official Ruby client for the [Apertur](https://apertur.ca) image upload and delivery API.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "apertur-sdk"
+```
+
+Or install directly:
+
+```sh
+gem install apertur-sdk
+```
+
+## Quick Start
+
+```ruby
+require "apertur"
+
+client = Apertur::Client.new(api_key: "aptr_test_your_key_here")
+
+# Create an upload session
+session = client.sessions.create(max_images: 10)
+puts session["uuid"]
+
+# Upload an image
+result = client.upload.image(session["uuid"], "/path/to/photo.jpg")
+
+# Upload with encryption
+server_key = client.encryption.get_server_key
+client.upload.image_encrypted(
+  session["uuid"],
+  "/path/to/photo.jpg",
+  server_key["publicKey"]
+)
+```
+
+## Authentication
+
+The SDK accepts an API key (prefixed `aptr_` or `aptr_test_`) or an OAuth token. The environment is auto-detected from the key prefix:
+
+- `aptr_test_*` keys target the sandbox at `https://sandbox.api.aptr.ca`
+- `aptr_*` keys target production at `https://api.aptr.ca`
+
+You can override the base URL:
+
+```ruby
+client = Apertur::Client.new(api_key: "aptr_...", base_url: "http://localhost:3000")
+```
+
+## Resources
+
+### Sessions
+
+```ruby
+client.sessions.create(max_images: 5, expires_in_hours: 24)
+client.sessions.get("uuid")
+client.sessions.update("uuid", max_images: 10)
+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")
+client.sessions.delivery_status("uuid")
+```
+
+### Upload
+
+```ruby
+# Multipart upload from file path
+client.upload.image("uuid", "/path/to/image.jpg")
+
+# Upload from IO
+File.open("photo.png", "rb") do |f|
+  client.upload.image("uuid", f, filename: "photo.png", mime_type: "image/png")
+end
+
+# Encrypted upload
+client.upload.image_encrypted("uuid", "/path/to/image.jpg", public_key_pem)
+```
+
+### Uploads
+
+```ruby
+client.uploads.list(page: 1, page_size: 20)
+client.uploads.recent(limit: 10)
+```
+
+### Polling
+
+```ruby
+# One-shot poll
+result = client.polling.list("uuid")
+data = client.polling.download("uuid", image_id)
+client.polling.ack("uuid", image_id)
+
+# Blocking loop
+client.polling.poll_and_process("uuid", interval: 3) do |image, data|
+  File.binwrite("downloads/#{image['id']}.jpg", data)
+end
+```
+
+### Destinations
+
+```ruby
+client.destinations.list("project_id")
+client.destinations.create("project_id", type: "s3", bucket: "my-bucket")
+client.destinations.update("project_id", "dest_id", bucket: "other-bucket")
+client.destinations.delete("project_id", "dest_id")
+client.destinations.test("project_id", "dest_id")
+```
+
+### Keys
+
+```ruby
+client.keys.list("project_id")
+client.keys.create("project_id", name: "My Key")
+client.keys.update("project_id", "key_id", name: "Renamed Key")
+client.keys.delete("project_id", "key_id")
+client.keys.set_destinations("key_id", ["dest_1", "dest_2"], long_polling_enabled: true)
+```
+
+### Webhooks
+
+```ruby
+client.webhooks.list("project_id")
+client.webhooks.create("project_id", url: "https://example.com/hook", events: ["upload.completed"])
+client.webhooks.update("project_id", "webhook_id", url: "https://example.com/hook2")
+client.webhooks.delete("project_id", "webhook_id")
+client.webhooks.test("project_id", "webhook_id")
+client.webhooks.deliveries("project_id", "webhook_id", page: 1, limit: 20)
+client.webhooks.retry_delivery("project_id", "webhook_id", "delivery_id")
+```
+
+### Encryption
+
+```ruby
+server_key = client.encryption.get_server_key
+```
+
+### Stats
+
+```ruby
+stats = client.stats.get
+```
+
+## Webhook Signature Verification
+
+```ruby
+# Simple webhook
+Apertur::Signature.verify_webhook(request_body, signature_header, secret)
+
+# Event webhook with timestamp
+Apertur::Signature.verify_event(request_body, timestamp_header, signature_header, secret)
+
+# Svix-style webhook
+Apertur::Signature.verify_svix(request_body, svix_id, svix_timestamp, svix_signature, secret)
+```
+
+## Client-Side Encryption
+
+```ruby
+encrypted = Apertur::Crypto.encrypt_image(raw_bytes, public_key_pem)
+# => { "encrypted_key" => "...", "iv" => "...", "encrypted_data" => "...", "algorithm" => "RSA-OAEP+AES-256-GCM" }
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.sessions.get("nonexistent")
+rescue Apertur::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue Apertur::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue Apertur::RateLimitError => e
+  puts "Rate limited, retry after #{e.retry_after}s"
+rescue Apertur::ValidationError => e
+  puts "Invalid request: #{e.message}"
+rescue Apertur::Error => e
+  puts "API error #{e.status_code}: #{e.message}"
+end
+```
+
+## Requirements
+
+- Ruby >= 3.0
+- No external dependencies (uses `net/http`, `json`, and `openssl` from stdlib)
+
+## License
+
+MIT

data/lib/apertur/client.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Apertur
+  # Main client for the Apertur API.
+  #
+  # Provides access to all API resources through lazily initialized accessors.
+  # Automatically detects the environment (live vs. sandbox) from the API key
+  # prefix and selects the appropriate base URL.
+  #
+  # @example
+  #   client = Apertur::Client.new(api_key: "aptr_test_abc123")
+  #   session = client.sessions.create(max_images: 5)
+  #   puts session["uuid"]
+  class Client
+    DEFAULT_BASE_URL = "https://api.aptr.ca"
+    SANDBOX_BASE_URL = "https://sandbox.api.aptr.ca"
+
+    # @return [String] the environment this client targets ("live" or "test")
+    attr_reader :env
+
+    # @return [Apertur::Resources::Sessions]
+    attr_reader :sessions
+
+    # @return [Apertur::Resources::Upload]
+    attr_reader :upload
+
+    # @return [Apertur::Resources::Uploads]
+    attr_reader :uploads
+
+    # @return [Apertur::Resources::Polling]
+    attr_reader :polling
+
+    # @return [Apertur::Resources::Destinations]
+    attr_reader :destinations
+
+    # @return [Apertur::Resources::Keys]
+    attr_reader :keys
+
+    # @return [Apertur::Resources::Webhooks]
+    attr_reader :webhooks
+
+    # @return [Apertur::Resources::Encryption]
+    attr_reader :encryption
+
+    # @return [Apertur::Resources::Stats]
+    attr_reader :stats
+
+    # Create a new Apertur API client.
+    #
+    # @param api_key [String, nil] an API key (prefixed +aptr_+ or +aptr_test_+)
+    # @param oauth_token [String, nil] an OAuth bearer token (alternative to api_key)
+    # @param base_url [String, nil] override the base URL; auto-detected from the
+    #   key prefix when nil
+    # @raise [ArgumentError] if neither +api_key+ nor +oauth_token+ is provided
+    def initialize(api_key: nil, oauth_token: nil, base_url: nil)
+      token = api_key || oauth_token
+      raise ArgumentError, "Either api_key or oauth_token must be provided" if token.nil? || token.empty?
+
+      @env = token.start_with?("aptr_test_") ? "test" : "live"
+
+      resolved_url = base_url || (@env == "test" ? SANDBOX_BASE_URL : DEFAULT_BASE_URL)
+      http = HttpClient.new(resolved_url, token)
+
+      @sessions     = Resources::Sessions.new(http)
+      @upload       = Resources::Upload.new(http)
+      @uploads      = Resources::Uploads.new(http)
+      @polling      = Resources::Polling.new(http)
+      @destinations = Resources::Destinations.new(http)
+      @keys         = Resources::Keys.new(http)
+      @webhooks     = Resources::Webhooks.new(http)
+      @encryption   = Resources::Encryption.new(http)
+      @stats        = Resources::Stats.new(http)
+    end
+  end
+end

data/lib/apertur/crypto.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "securerandom"
+
+module Apertur
+  # Image encryption utilities for client-side encryption before upload.
+  #
+  # Uses AES-256-GCM for symmetric encryption and RSA-OAEP (SHA-256) to
+  # wrap the AES key with the server's public key.
+  module Crypto
+    module_function
+
+    # Encrypt image data for secure upload.
+    #
+    # Generates a random AES-256-GCM key and IV, encrypts the image data,
+    # then wraps the AES key with the provided RSA public key using OAEP
+    # padding with SHA-256.
+    #
+    # @param image_data [String] raw image bytes
+    # @param public_key_pem [String] RSA public key in PEM format
+    # @return [Hash] a Hash with the following String keys:
+    #   - +"encrypted_key"+ - Base64-encoded RSA-wrapped AES key
+    #   - +"iv"+ - Base64-encoded initialization vector
+    #   - +"encrypted_data"+ - Base64-encoded ciphertext with appended GCM auth tag
+    #   - +"algorithm"+ - the encryption algorithm identifier ("RSA-OAEP+AES-256-GCM")
+    def encrypt_image(image_data, public_key_pem)
+      # Generate random AES-256 key and 12-byte IV
+      aes_key = SecureRandom.random_bytes(32)
+      iv = SecureRandom.random_bytes(12)
+
+      # Encrypt image with AES-256-GCM
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.encrypt
+      cipher.key = aes_key
+      cipher.iv = iv
+
+      encrypted = cipher.update(image_data) + cipher.final
+      auth_tag = cipher.auth_tag
+      encrypted_with_tag = encrypted + auth_tag
+
+      # Wrap AES key with RSA-OAEP (SHA-256)
+      # Uses OpenSSL::PKey::PKey#encrypt (available in Ruby 3.0+) which
+      # allows specifying the OAEP digest algorithm.
+      pub_key = OpenSSL::PKey::RSA.new(public_key_pem)
+      wrapped_key = pub_key.encrypt(aes_key, {
+        "rsa_padding_mode" => "oaep",
+        "rsa_oaep_md" => "sha256"
+      })
+
+      {
+        "encrypted_key" => Base64.strict_encode64(wrapped_key),
+        "iv" => Base64.strict_encode64(iv),
+        "encrypted_data" => Base64.strict_encode64(encrypted_with_tag),
+        "algorithm" => "RSA-OAEP+AES-256-GCM"
+      }
+    end
+  end
+end

data/lib/apertur/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Apertur
+  # Base error class for all Apertur API errors.
+  #
+  # @attr_reader [Integer, nil] status_code the HTTP status code
+  # @attr_reader [String, nil] code the error code returned by the API
+  class Error < StandardError
+    attr_reader :status_code, :code
+
+    # @param message [String] the error message
+    # @param status_code [Integer, nil] the HTTP status code
+    # @param code [String, nil] the API error code
+    def initialize(message, status_code: nil, code: nil)
+      super(message)
+      @status_code = status_code
+      @code = code
+    end
+  end
+
+  # Raised when the API returns a 401 Unauthorized response.
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super(message, status_code: 401, code: "AUTHENTICATION_FAILED")
+    end
+  end
+
+  # Raised when the API returns a 404 Not Found response.
+  class NotFoundError < Error
+    def initialize(message = "Not found")
+      super(message, status_code: 404, code: "NOT_FOUND")
+    end
+  end
+
+  # Raised when the API returns a 429 Too Many Requests response.
+  #
+  # @attr_reader [Integer, nil] retry_after seconds to wait before retrying
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    # @param message [String] the error message
+    # @param retry_after [Integer, nil] seconds to wait before retrying
+    def initialize(message = "Rate limit exceeded", retry_after: nil)
+      super(message, status_code: 429, code: "RATE_LIMIT")
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised when the API returns a 400 Bad Request response.
+  class ValidationError < Error
+    def initialize(message = "Validation failed")
+      super(message, status_code: 400, code: "VALIDATION_ERROR")
+    end
+  end
+end

data/lib/apertur/http_client.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module Apertur
+  # Low-level HTTP wrapper around Net::HTTP for communicating with the Apertur API.
+  #
+  # Handles JSON serialization, Bearer token authentication, multipart uploads,
+  # and error mapping.
+  class HttpClient
+    # @param base_url [String] the API base URL (e.g. "https://api.aptr.ca")
+    # @param token [String] the Bearer token (API key or OAuth token)
+    def initialize(base_url, token)
+      @base_url = base_url.chomp("/")
+      @token = token
+    end
+
+    # Perform an API request and return the parsed JSON response.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :put, :delete)
+    # @param path [String] the API path (e.g. "/api/v1/stats")
+    # @param body [Hash, nil] request body to be serialized as JSON
+    # @param query [Hash, nil] query parameters
+    # @param headers [Hash] additional request headers
+    # @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: {})
+      uri = build_uri(path, query)
+      req = build_request(method, uri, headers)
+
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = body.is_a?(String) ? body : JSON.generate(body)
+      end
+
+      response = execute(uri, req)
+      handle_response(response)
+    end
+
+    # Perform an API request and return the raw response body as a binary String.
+    #
+    # @param method [Symbol] HTTP method
+    # @param path [String] the API path
+    # @param query [Hash, nil] query parameters
+    # @return [String] raw response body (binary)
+    # @raise [Apertur::Error] on API errors
+    def request_raw(method, path, query: nil)
+      uri = build_uri(path, query)
+      req = build_request(method, uri)
+
+      response = execute(uri, req)
+      handle_error(response) unless response.is_a?(Net::HTTPSuccess)
+      response.body
+    end
+
+    # Perform a multipart/form-data upload request.
+    #
+    # @param path [String] the API path
+    # @param file_data [String] raw file bytes
+    # @param filename [String] the filename to use in the multipart part
+    # @param mime_type [String] the MIME type of the file
+    # @param fields [Hash] additional form fields
+    # @param headers [Hash] additional request headers
+    # @return [Hash, Array, nil] parsed JSON response
+    # @raise [Apertur::Error] on API errors
+    def request_multipart(path, file_data, filename:, mime_type:, fields: {}, headers: {})
+      uri = build_uri(path)
+      boundary = "AperturRubySDK#{SecureRandom.hex(16)}"
+
+      body = build_multipart_body(boundary, file_data, filename, mime_type, fields)
+
+      req = build_request(:post, uri, headers)
+      req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      req.body = body
+
+      response = execute(uri, req)
+      handle_response(response)
+    end
+
+    private
+
+    # @param path [String]
+    # @param query [Hash, nil]
+    # @return [URI]
+    def build_uri(path, query = nil)
+      url = "#{@base_url}#{path}"
+      if query && !query.empty?
+        params = query.reject { |_, v| v.nil? }.map { |k, v| "#{URI.encode_www_form_component(k)}=#{URI.encode_www_form_component(v)}" }
+        url += "?#{params.join("&")}" unless params.empty?
+      end
+      URI.parse(url)
+    end
+
+    # @param method [Symbol]
+    # @param uri [URI]
+    # @param extra_headers [Hash]
+    # @return [Net::HTTPRequest]
+    def build_request(method, uri, extra_headers = {})
+      klass = case method
+              when :get    then Net::HTTP::Get
+              when :post   then Net::HTTP::Post
+              when :patch  then Net::HTTP::Patch
+              when :put    then Net::HTTP::Put
+              when :delete then Net::HTTP::Delete
+              else raise ArgumentError, "Unsupported HTTP method: #{method}"
+              end
+
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{@token}" if @token && !@token.empty?
+      req["User-Agent"] = "apertur-sdk-ruby/#{Apertur::VERSION}"
+      req["Accept"] = "application/json"
+
+      extra_headers.each { |k, v| req[k] = v }
+      req
+    end
+
+    # @param uri [URI]
+    # @param req [Net::HTTPRequest]
+    # @return [Net::HTTPResponse]
+    def execute(uri, req)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 30
+      http.read_timeout = 60
+      http.request(req)
+    end
+
+    # @param response [Net::HTTPResponse]
+    # @return [Hash, Array, nil]
+    def handle_response(response)
+      handle_error(response) unless response.is_a?(Net::HTTPSuccess)
+
+      return nil if response.code == "204" || response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    end
+
+    # @param response [Net::HTTPResponse]
+    # @raise [Apertur::Error]
+    def handle_error(response)
+      body = begin
+               JSON.parse(response.body)
+             rescue StandardError
+               {}
+             end
+
+      message = body["message"] || "HTTP #{response.code}"
+      code = body["code"]
+
+      case response.code.to_i
+      when 401
+        raise AuthenticationError, message
+      when 404
+        raise NotFoundError, message
+      when 429
+        retry_after = response["Retry-After"]&.to_i
+        raise RateLimitError.new(message, retry_after: retry_after)
+      when 400
+        raise ValidationError, message
+      else
+        raise Error.new(message, status_code: response.code.to_i, code: code)
+      end
+    end
+
+    # @param boundary [String]
+    # @param file_data [String]
+    # @param filename [String]
+    # @param mime_type [String]
+    # @param fields [Hash]
+    # @return [String]
+    def build_multipart_body(boundary, file_data, filename, mime_type, fields)
+      parts = []
+
+      fields.each do |key, value|
+        parts << "--#{boundary}\r\n" \
+                 "Content-Disposition: form-data; name=\"#{key}\"\r\n" \
+                 "\r\n" \
+                 "#{value}\r\n"
+      end
+
+      parts << "--#{boundary}\r\n" \
+               "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n" \
+               "Content-Type: #{mime_type}\r\n" \
+               "\r\n"
+
+      body = parts.join.b
+      body << file_data.b
+      body << "\r\n--#{boundary}--\r\n".b
+      body
+    end
+  end
+end

data/lib/apertur/resources/destinations.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Manage delivery destinations within a project.
+    #
+    # Destinations define where uploaded images are delivered (e.g. cloud
+    # storage buckets, webhooks, etc.).
+    class Destinations
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List all destinations for a project.
+      #
+      # @param project_id [String] the project ID
+      # @return [Array<Hash>] list of destinations
+      def list(project_id)
+        @http.request(:get, "/api/v1/projects/#{project_id}/destinations")
+      end
+
+      # Create a new destination.
+      #
+      # @param project_id [String] the project ID
+      # @param config [Hash] destination configuration
+      # @return [Hash] the created destination
+      def create(project_id, **config)
+        @http.request(:post, "/api/v1/projects/#{project_id}/destinations", body: config)
+      end
+
+      # Update an existing destination.
+      #
+      # @param project_id [String] the project ID
+      # @param dest_id [String] the destination ID
+      # @param config [Hash] fields to update
+      # @return [Hash] the updated destination
+      def update(project_id, dest_id, **config)
+        @http.request(:patch, "/api/v1/projects/#{project_id}/destinations/#{dest_id}", body: config)
+      end
+
+      # Delete a destination.
+      #
+      # @param project_id [String] the project ID
+      # @param dest_id [String] the destination ID
+      # @return [nil]
+      def delete(project_id, dest_id)
+        @http.request(:delete, "/api/v1/projects/#{project_id}/destinations/#{dest_id}")
+      end
+
+      # Send a test payload to a destination.
+      #
+      # @param project_id [String] the project ID
+      # @param dest_id [String] the destination ID
+      # @return [Hash] test result
+      def test(project_id, dest_id)
+        @http.request(:post, "/api/v1/projects/#{project_id}/destinations/#{dest_id}/test")
+      end
+    end
+  end
+end

data/lib/apertur/resources/encryption.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Apertur
+  module Resources
+    # Retrieve server-side encryption keys.
+    class Encryption
+      # @param http [Apertur::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # Get the server's public encryption key.
+      #
+      # The returned key is used for client-side image encryption before upload.
+      #
+      # @return [Hash] server key details including the PEM-encoded public key
+      def get_server_key
+        @http.request(:get, "/api/v1/encryption/server-key")
+      end
+    end
+  end
+end