aho-sdk 0.1.0

data/lib/aho_sdk/holder.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Auto-generated by bin/generate_sdks.rb - DO NOT EDIT
+
+require_relative "http_client"
+require_relative "page"
+require_relative "cursor_page"
+
+module AhoSdk
+  # Manage holder credentials and presentations
+  #
+  # @example
+  #   client = AhoSdk::Holder.new(api_key: ENV["AHO_HOLDER_API_KEY"])
+  #   client.credentials.list
+  #   client.presentations.list
+  #
+  class Holder
+    # @param api_key [String] API key for authentication
+    # @param base_url [String] Base URL (default: https://aho.com)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param logger [Logger] Optional logger for debugging
+    def initialize(api_key:, base_url: "https://aho.com", timeout: 30, logger: nil)
+      @client = HttpClient.new(api_key: api_key, base_url: base_url, timeout: timeout, logger: logger)
+      @credentials = CredentialsResource.new(@client)
+      @presentations = PresentationsResource.new(@client)
+    end
+
+    # @return [CredentialsResource]
+    attr_reader :credentials
+    # @return [PresentationsResource]
+    attr_reader :presentations
+
+
+    # Credentials resource operations
+    # @api private
+    class CredentialsResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # List holder credentials
+      #
+      # @return [Hash]
+      def list(page: nil, per_page: nil, status: nil, sort: nil, direction: nil)
+        fetch_page = ->(p) {
+          response = @client.get("/api/v1/holder/credentials", params: { page: p, per_page: per_page, status: status, sort: sort, direction: direction })
+          Page.new(data: response[:data], meta: response[:meta], fetch_next: fetch_page)
+        }
+        fetch_page.call(page)
+      end
+
+      # Get credential details
+      #
+      # @return [Hash]
+      def get(uuid:)
+        @client.get("/api/v1/holder/credentials/#{uuid}")
+      end
+    end
+
+    # Presentations resource operations
+    # @api private
+    class PresentationsResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # List holder presentations
+      #
+      # @return [Hash]
+      def list(page: nil, per_page: nil, status: nil, credential_uuid: nil, sort: nil, direction: nil)
+        fetch_page = ->(p) {
+          response = @client.get("/api/v1/holder/presentations", params: { page: p, per_page: per_page, status: status, credential_uuid: credential_uuid, sort: sort, direction: direction })
+          Page.new(data: response[:data], meta: response[:meta], fetch_next: fetch_page)
+        }
+        fetch_page.call(page)
+      end
+
+      # Create a credential presentation
+      #
+      # @return [Hash]
+      def create(body: nil, idempotency_key: nil)
+        @client.post("/api/v1/holder/presentations", body: body, idempotency_key: idempotency_key)
+      end
+
+      # Get presentation details
+      #
+      # @return [Hash]
+      def get(uuid:)
+        @client.get("/api/v1/holder/presentations/#{uuid}")
+      end
+
+      # Revoke a presentation
+      #
+      # @return [Hash]
+      def delete(uuid:)
+        @client.delete("/api/v1/holder/presentations/#{uuid}")
+      end
+    end
+  end
+end

data/lib/aho_sdk/http_client.rb

@@ -0,0 +1,420 @@
+# frozen_string_literal: true
+
+# Auto-generated by bin/generate_sdks.rb - DO NOT EDIT
+
+require "net/http"
+require "json"
+require "uri"
+require "securerandom"
+
+module AhoSdk
+  # HTTP client with retry logic, credential redaction, and error handling
+  class HttpClient
+    DEFAULT_TIMEOUT = 30 # seconds
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_DELAY = 1.0 # seconds
+
+    # Only retry idempotent methods to prevent duplicate operations
+    IDEMPOTENT_METHODS = %i[get delete put head options].freeze
+
+    # @param api_key [String, nil] API key for authentication (nil for public endpoints)
+    # @param base_url [String] Base URL for the API
+    # @param timeout [Integer] Request timeout in seconds
+    # @param max_retries [Integer] Maximum number of retries on rate limit (default: 3)
+    # @param retry_delay [Float] Base delay in seconds for exponential backoff (default: 1.0)
+    # @param logger [Logger, nil] Optional logger for debugging
+    def initialize(api_key:, base_url: "https://aho.com", timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, retry_delay: DEFAULT_RETRY_DELAY, logger: nil)
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+      @retry_delay = retry_delay
+      @logger = logger
+    end
+
+    def get(path, params: {}, accept: "application/json")
+      request(:get, path, params: params, accept: accept)
+    end
+
+    def post(path, body: nil, params: {}, accept: "application/json", idempotency_key: nil)
+      request(:post, path, body: body, params: params, accept: accept, idempotency_key: idempotency_key)
+    end
+
+    def patch(path, body: nil, params: {}, accept: "application/json", idempotency_key: nil)
+      request(:patch, path, body: body, params: params, accept: accept, idempotency_key: idempotency_key)
+    end
+
+    def put(path, body: nil, params: {}, accept: "application/json", idempotency_key: nil)
+      request(:put, path, body: body, params: params, accept: accept, idempotency_key: idempotency_key)
+    end
+
+    def delete(path, params: {}, accept: "application/json")
+      request(:delete, path, params: params, accept: accept)
+    end
+
+    def head(path, params: {})
+      request(:head, path, params: params, accept: "*/*")
+    end
+
+    def options(path, params: {})
+      request(:options, path, params: params, accept: "*/*")
+    end
+
+    # POST with multipart/form-data for file uploads
+    # @param path [String] API path
+    # @param files [Hash] File parameters { param_name: File or String path }
+    # @param fields [Hash] Additional form fields
+    # @param params [Hash] Query parameters
+    # @param idempotency_key [String, nil] Optional idempotency key
+    def post_multipart(path, files: {}, fields: {}, params: {}, idempotency_key: nil)
+      multipart_request(:post, path, files: files, fields: fields, params: params, idempotency_key: idempotency_key)
+    end
+
+    # PATCH with multipart/form-data for file uploads
+    def patch_multipart(path, files: {}, fields: {}, params: {}, idempotency_key: nil)
+      multipart_request(:patch, path, files: files, fields: fields, params: params, idempotency_key: idempotency_key)
+    end
+
+    # PUT with multipart/form-data for file uploads
+    def put_multipart(path, files: {}, fields: {}, params: {}, idempotency_key: nil)
+      multipart_request(:put, path, files: files, fields: fields, params: params, idempotency_key: idempotency_key)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: {}, accept: "application/json", idempotency_key: nil)
+      uri = build_uri(path, params)
+      req = build_request(method, uri, body, accept, idempotency_key: idempotency_key)
+
+      log_request(method, uri)
+
+      retries = 0
+      begin
+        execute_request(uri, req, accept)
+      rescue RateLimitError => e
+        raise unless IDEMPOTENT_METHODS.include?(method) && retries < @max_retries
+
+        retries += 1
+        delay = e.retry_after || (@retry_delay * (2**(retries - 1)))
+        log_retry(method, uri, retries, delay)
+        sleep(delay)
+        retry
+      end
+    end
+
+    def multipart_request(method, path, files:, fields:, params: {}, idempotency_key: nil)
+      uri = build_uri(path, params)
+      req = build_multipart_request(method, uri, files, fields, idempotency_key: idempotency_key)
+
+      log_request(method, uri)
+
+      retries = 0
+      begin
+        execute_request(uri, req, "application/json")
+      rescue RateLimitError => e
+        raise unless IDEMPOTENT_METHODS.include?(method) && retries < @max_retries
+
+        retries += 1
+        delay = e.retry_after || (@retry_delay * (2**(retries - 1)))
+        log_retry(method, uri, retries, delay)
+        sleep(delay)
+        retry
+      end
+    end
+
+    def execute_request(uri, req, accept)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      response = http.request(req)
+      handle_response(response, accept)
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError, e.message
+    end
+
+    def build_uri(path, params)
+      uri = URI.parse("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(flatten_params(params)) if params.any?
+      uri
+    end
+
+    # Flatten nested arrays for query params: { status: ['a', 'b'] } => [['status[]', 'a'], ['status[]', 'b']]
+    def flatten_params(params)
+      params.compact.flat_map do |key, value|
+        case value
+        when Array
+          value.map { |v| [ "#{key}[]", v ] }
+        else
+          [ [ key, value ] ]
+        end
+      end
+    end
+
+    def build_request(method, uri, body, accept, idempotency_key: nil)
+      klass = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }[method]
+
+      req = klass.new(uri)
+      req["X-API-Key"] = @api_key if @api_key
+      req["Content-Type"] = "application/json"
+      req["Accept"] = accept
+      req["User-Agent"] = "aho-sdk/#{VERSION} ruby/#{RUBY_VERSION}"
+      req["Idempotency-Key"] = idempotency_key if idempotency_key
+      req.body = body.to_json if body
+      req
+    end
+
+    def build_multipart_request(method, uri, files, fields, idempotency_key: nil)
+      klass = {
+        post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
+        put: Net::HTTP::Put
+      }[method]
+
+      boundary = "----RubyMultipartClient#{SecureRandom.hex(16)}"
+
+      req = klass.new(uri)
+      req["X-API-Key"] = @api_key if @api_key
+      req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "aho-sdk/#{VERSION} ruby/#{RUBY_VERSION}"
+      req["Idempotency-Key"] = idempotency_key if idempotency_key
+      req.body = build_multipart_body(boundary, files, fields)
+      req
+    end
+
+    def build_multipart_body(boundary, files, fields)
+      parts = []
+
+      # Add regular form fields
+      fields.each do |name, value|
+        parts << "--#{boundary}\r\n"
+        parts << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
+        parts << "#{value}\r\n"
+      end
+
+      # Add file fields
+      files.each do |name, file_or_path|
+        file, filename, content_type = normalize_file(file_or_path)
+
+        parts << "--#{boundary}\r\n"
+        parts << "Content-Disposition: form-data; name=\"#{name}\"; filename=\"#{filename}\"\r\n"
+        parts << "Content-Type: #{content_type}\r\n\r\n"
+        parts << file.read
+        parts << "\r\n"
+
+        file.close if file.respond_to?(:close) && file_or_path.is_a?(String)
+      end
+
+      parts << "--#{boundary}--\r\n"
+      parts.join
+    end
+
+    def normalize_file(file_or_path)
+      case file_or_path
+      when String
+        # Path string - open file
+        file = File.open(file_or_path, "rb")
+        filename = File.basename(file_or_path)
+        content_type = mime_type_for(filename)
+        [ file, filename, content_type ]
+      when Hash
+        # Hash with file, filename, content_type
+        file = file_or_path[:file]
+        file = File.open(file, "rb") if file.is_a?(String)
+        filename = file_or_path[:filename] || (file.respond_to?(:path) ? File.basename(file.path) : "file")
+        content_type = file_or_path[:content_type] || mime_type_for(filename)
+        [ file, filename, content_type ]
+      else
+        # File object
+        filename = file_or_path.respond_to?(:path) ? File.basename(file_or_path.path) : "file"
+        content_type = mime_type_for(filename)
+        [ file_or_path, filename, content_type ]
+      end
+    end
+
+    # Auto-detect MIME type from file extension
+    MIME_TYPES = {
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif",
+      ".webp" => "image/webp",
+      ".svg" => "image/svg+xml",
+      ".pdf" => "application/pdf",
+      ".zip" => "application/zip",
+      ".gz" => "application/gzip",
+      ".json" => "application/json",
+      ".xml" => "application/xml",
+      ".txt" => "text/plain",
+      ".html" => "text/html",
+      ".css" => "text/css",
+      ".js" => "application/javascript"
+    }.freeze
+
+    def mime_type_for(filename)
+      ext = File.extname(filename).downcase
+      MIME_TYPES[ext] || "application/octet-stream"
+    end
+
+    # Log request with credentials redacted
+    def log_request(method, uri)
+      return unless @logger
+
+      @logger.debug { "[AhoSdk] #{method.upcase} #{uri}" }
+    end
+
+    def log_retry(method, uri, attempt, delay)
+      return unless @logger
+
+      @logger.warn { "[AhoSdk] Retry #{attempt}/#{@max_retries} for #{method.upcase} #{uri} after #{delay}s" }
+    end
+
+    # Binary content types that should return raw bytes
+    BINARY_CONTENT_TYPES = %w[
+      image/png image/jpeg image/gif image/webp image/svg+xml
+      application/pdf application/octet-stream application/zip application/gzip
+    ].freeze
+
+    def handle_response(response, accept)
+      body = response.body.to_s
+      request_id = response["X-Request-Id"]
+      content_type = response["Content-Type"]&.split(";")&.first&.strip
+
+      case response.code.to_i
+      when 200..299
+        return nil if body.empty?
+
+        # Return raw bytes for binary content types
+        if binary_content_type?(content_type) || binary_content_type?(accept)
+          return response.body
+        end
+
+        JSON.parse(body, symbolize_names: true)
+      when 400
+        raise BadRequestError.new(body, response.code.to_i, request_id)
+      when 401
+        raise AuthenticationError.new(body, response.code.to_i, request_id)
+      when 403
+        raise ForbiddenError.new(body, response.code.to_i, request_id)
+      when 404
+        raise NotFoundError.new(body, response.code.to_i, request_id)
+      when 409
+        raise ConflictError.new(body, response.code.to_i, request_id)
+      when 422
+        raise ValidationError.new(body, response.code.to_i, request_id)
+      when 429
+        raise RateLimitError.new(body, response.code.to_i, request_id, response["Retry-After"]&.to_f)
+      when 500..599
+        raise ServerError.new(body, response.code.to_i, request_id)
+      else
+        raise ApiError.new(body, response.code.to_i, request_id)
+      end
+    end
+
+    def binary_content_type?(content_type)
+      return false unless content_type
+
+      BINARY_CONTENT_TYPES.any? { |bin_type| content_type.start_with?(bin_type) } ||
+        content_type.start_with?("image/")
+    end
+  end
+
+  # Base error class for API errors
+  class ApiError < StandardError
+    attr_reader :status_code, :request_id, :error_code, :details, :raw_body
+
+    def initialize(body, status_code, request_id = nil)
+      @status_code = status_code
+      @request_id = request_id
+      @raw_body = body
+
+      begin
+        parsed = JSON.parse(body, symbolize_names: true)
+        error = parsed[:error] || parsed
+        @error_code = error[:code]
+        @details = normalize_details(error[:details])
+        super(error[:message] || body)
+      rescue JSON::ParserError
+        @error_code = "unknown"
+        @details = []
+        super(body)
+      end
+    end
+
+    private
+
+    # Normalize details to array of FieldError-like hashes
+    # API can return: string, array of strings, array of FieldError objects, hash, or nil
+    def normalize_details(details)
+      case details
+      when nil
+        []
+      when String
+        [ { field: "_base", issue: "error", hint: details } ]
+      when Array
+        details.map do |item|
+          case item
+          when String
+            { field: "_base", issue: "error", hint: item }
+          when Hash
+            item
+          else
+            { field: "_base", issue: "error", hint: item.to_s }
+          end
+        end
+      when Hash
+        # Legacy format: { field_name: [errors] }
+        details.flat_map do |field, errors|
+          Array(errors).map { |e| { field: field.to_s, issue: "validation_failed", hint: e } }
+        end
+      else
+        [ { field: "_base", issue: "error", hint: details.to_s } ]
+      end
+    end
+  end
+
+  class BadRequestError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class ForbiddenError < ApiError; end
+  class NotFoundError < ApiError; end
+  class ConflictError < ApiError; end
+  class ServerError < ApiError; end
+
+  class ValidationError < ApiError
+    # Returns array of { field:, issue:, hint: } hashes
+    def field_errors
+      details || []
+    end
+
+    # Group errors by field name for convenience
+    def errors_by_field
+      field_errors.group_by { |e| e[:field] }
+    end
+  end
+
+  class RateLimitError < ApiError
+    attr_reader :retry_after
+
+    def initialize(body, status_code, request_id, retry_after)
+      super(body, status_code, request_id)
+      @retry_after = retry_after
+    end
+  end
+
+  class NetworkError < StandardError
+    attr_reader :status_code
+
+    def initialize(message)
+      @status_code = 0
+      super(message)
+    end
+  end
+end