aho-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 72d0e9a4889740cb021e3df8a786d25ac7e0005ed8161d77c38cb8de84e8d92a
+  data.tar.gz: bce01a4cdb564cca550f17956aead22aa2e56c3e7a862b1ffd5649fbbb3113b0
+SHA512:
+  metadata.gz: ab85b572852b0e5ae5247a489685332cd52be3cb2a444cc9b41f9e5c195d678e71aeee995109e074adda5db0f1a383db302ed73ba24e3f1c972a0b6be1bd7c78
+  data.tar.gz: 4588cfed2ef06d2edc5c2da651694e70439f4613a19b37fd5690e1f05704102a109b9fc4560f0593d52582289b9b2c88e73b5538b7f492ead25824ecc779cf77

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-27
+
+### Added
+
+- Initial release
+- Issuer client for credential issuance
+- Holder client for wallet management
+- Verifier client for presentation verification
+- Account client for account management
+- Pagination support
+- Comprehensive error handling

data/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Aho
+
+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,278 @@
+# AhoSdk Ruby SDK
+
+Official Ruby SDK for the [Aho](https://aho.com) Verifiable Credentials API.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'aho-sdk'
+```
+
+Or install directly:
+
+```bash
+gem install aho-sdk
+```
+
+## Quick Start
+
+```ruby
+require 'aho-sdk'
+
+# Initialize the Issuer client
+issuer = AhoSdk::Issuer.new(api_key: ENV['AHO_ISSUER_API_KEY'])
+
+# Issue a credential
+credential = issuer.credentials.create(
+  schema_uuid: 'your-schema-uuid',
+  subject_identifier: 'user@example.com',
+  claims: {
+    name: 'Jane Doe',
+    role: 'Engineer'
+  }
+)
+
+puts credential['uuid']
+```
+
+## Clients
+
+The SDK provides the following clients:
+
+| Client | Purpose | API Key Type |
+|--------|---------|--------------|
+| `AhoSdk::Account` | Manage account settings, domains, and API keys | Account API Key |
+| `AhoSdk::System` | System health and status endpoints | System API Key |
+| `AhoSdk::Holder` | Manage holder credentials and presentations | Holder API Key |
+| `AhoSdk::Verifier` | Create presentation requests and verify credentials | Verifier API Key |
+| `AhoSdk::Issuer` | Issue and manage verifiable credentials | Issuer API Key |
+| `AhoSdk::Schemas` | Browse and retrieve credential schemas | Schemas API Key |
+| `AhoSdk::Public` | Public endpoints (no authentication required) | None (public) |
+
+## Usage Examples
+
+### Issuing Credentials
+
+```ruby
+issuer = AhoSdk::Issuer.new(api_key: ENV['AHO_ISSUER_API_KEY'])
+
+# List all schemas
+schemas = issuer.schemas.list
+schemas.data.each { |s| puts s['name'] }
+
+# Create a schema
+schema = issuer.schemas.create(
+  name: 'EmployeeBadge',
+  claims: [
+    { name: 'employee_id', type: 'string', required: true },
+    { name: 'department', type: 'string', required: true },
+    { name: 'hire_date', type: 'date', required: false }
+  ]
+)
+
+# Issue a credential
+credential = issuer.credentials.create(
+  schema_uuid: schema['uuid'],
+  subject_identifier: 'jane.doe@company.com',
+  claims: {
+    employee_id: 'EMP-12345',
+    department: 'Engineering',
+    hire_date: '2024-01-15'
+  }
+)
+
+# Revoke a credential
+issuer.credentials.revoke(uuid: credential['uuid'], reason: 'Employee departed')
+```
+
+### Verifying Credentials
+
+```ruby
+verifier = AhoSdk::Verifier.new(api_key: ENV['AHO_VERIFIER_API_KEY'])
+
+# Create a presentation request
+request = verifier.requests.create(
+  name: 'Employment Verification',
+  query_format: 'dcql',
+  credentials: [
+    {
+      id: 'employee_badge',
+      format: 'vc+sd-jwt',
+      claims: [
+        { path: ['employee_id'] },
+        { path: ['department'] }
+      ]
+    }
+  ]
+)
+
+# Get the QR code for the request (supports :png, :svg formats)
+qr = verifier.requests.qr_code(uuid: request['uuid'], output_format: :svg)
+
+# List responses to the request
+responses = verifier.responses.list(request_uuid: request['uuid'])
+```
+
+### Managing Holder Credentials
+
+```ruby
+holder = AhoSdk::Holder.new(api_key: ENV['AHO_HOLDER_API_KEY'])
+
+# List credentials
+credentials = holder.credentials.list(status: 'active')
+
+# Create a presentation (selective disclosure)
+presentation = holder.presentations.create(
+  credential_uuid: 'credential-uuid',
+  disclosed_claims: ['name', 'department']
+)
+```
+
+### Account Management
+
+```ruby
+account = AhoSdk::Account.new(api_key: ENV['AHO_API_KEY'])
+
+# Manage domains
+domains = account.domains.list
+account.domains.verify(id: domain['id'])
+
+# Manage signing keys
+keys = account.signing_keys.list
+account.signing_keys.rotate(id: key['id'])
+
+# Configure webhooks
+account.webhooks.create(
+  url: 'https://your-app.com/webhooks/aho',
+  events: ['credential.issued', 'credential.revoked']
+)
+```
+
+## Pagination
+
+List methods return `Page` objects with built-in iteration:
+
+```ruby
+# Iterate through all pages automatically
+issuer.credentials.list.each do |credential|
+  puts credential['uuid']
+end
+
+# Or handle pages manually
+page = issuer.credentials.list(per_page: 50)
+while page
+  page.data.each { |c| puts c['uuid'] }
+  page = page.next_page
+end
+
+# Collect all items
+all_credentials = issuer.credentials.list.to_a
+```
+
+## File Uploads
+
+For endpoints that accept file uploads:
+
+```ruby
+# Upload a file
+issuer.media.upload(
+  file: File.open('document.pdf'),
+  metadata: { description: 'Employee contract' }
+)
+
+# The SDK auto-detects MIME types from file extensions
+# You can also pass a path string:
+issuer.media.upload(file: '/path/to/document.pdf')
+```
+
+## Binary Responses
+
+Some endpoints return binary data (images, PDFs):
+
+```ruby
+# Get QR code as PNG
+png_data = verifier.requests.qr_code(uuid: '...', output_format: :png)
+File.binwrite('qr.png', png_data)
+
+# Get QR code as SVG
+svg_data = verifier.requests.qr_code(uuid: '...', output_format: :svg)
+File.write('qr.svg', svg_data)
+```
+
+## Error Handling
+
+```ruby
+begin
+  issuer.credentials.create(invalid_params)
+rescue AhoSdk::ValidationError => e
+  # 422 - Validation failed
+  e.field_errors.each do |error|
+    puts "#{error['field']}: #{error['hint']}"
+  end
+rescue AhoSdk::AuthenticationError => e
+  # 401 - Invalid API key
+  puts "Check your API key"
+rescue AhoSdk::NotFoundError => e
+  # 404 - Resource not found
+  puts "Resource not found: #{e.message}"
+rescue AhoSdk::RateLimitError => e
+  # 429 - Rate limited (SDK auto-retries with exponential backoff)
+  puts "Retry after #{e.retry_after} seconds"
+rescue AhoSdk::ApiError => e
+  # Other API errors
+  puts "Error #{e.status_code}: #{e.message}"
+  puts "Request ID: #{e.request_id}"
+end
+```
+
+### Error Classes
+
+| Error Class | HTTP Status | Description |
+|-------------|-------------|-------------|
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `ForbiddenError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | Resource conflict |
+| `ValidationError` | 422 | Request validation failed |
+| `RateLimitError` | 429 | Rate limit exceeded |
+| `ServerError` | 5xx | Server-side error |
+| `NetworkError` | - | Connection/timeout error |
+| `ApiError` | * | Base class for all API errors |
+
+## Rate Limiting
+
+The SDK automatically handles rate limits with exponential backoff:
+
+- **Idempotent methods** (GET, DELETE, PUT): Auto-retry up to 3 times
+- **Non-idempotent methods** (POST, PATCH): Only retry with idempotency key
+
+```ruby
+# Use idempotency keys for safe retries on POST/PATCH
+issuer.credentials.create(
+  schema_uuid: '...',
+  claims: { ... },
+  idempotency_key: 'unique-request-id'
+)
+```
+
+## Configuration
+
+```ruby
+# Custom configuration
+issuer = AhoSdk::Issuer.new(
+  api_key: ENV['AHO_ISSUER_API_KEY'],
+  base_url: 'https://api.aho.com',  # Custom base URL
+  timeout: 60,                       # Request timeout in seconds
+  logger: Logger.new(STDOUT)         # Enable debug logging
+)
+```
+
+## Requirements
+
+- Ruby 3.1+
+
+## License
+
+MIT

data/lib/aho_sdk/account.rb

@@ -0,0 +1,226 @@
+# 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 account settings, domains, and API keys
+  #
+  # @example
+  #   client = AhoSdk::Account.new(api_key: ENV["AHO_ACCOUNT_API_KEY"])
+  #   client.api_keys.list
+  #   client.domains.list
+  #   client.signing_keys.list
+  #   client.webhooks.list
+  #
+  class Account
+    # @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)
+      @api_keys = ApiKeysResource.new(@client)
+      @domains = DomainsResource.new(@client)
+      @signing_keys = SigningKeysResource.new(@client)
+      @webhooks = WebhooksResource.new(@client)
+    end
+
+    # @return [ApiKeysResource]
+    attr_reader :api_keys
+    # @return [DomainsResource]
+    attr_reader :domains
+    # @return [SigningKeysResource]
+    attr_reader :signing_keys
+    # @return [WebhooksResource]
+    attr_reader :webhooks
+
+
+    # Api_keys resource operations
+    # @api private
+    class ApiKeysResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # List API keys
+      #
+      # @return [Hash]
+      def list
+        @client.get("/api/v1/account/api_keys")
+      end
+
+      # Create/regenerate API key
+      #
+      # @return [Hash]
+      def create(body: nil, idempotency_key: nil)
+        @client.post("/api/v1/account/api_keys", body: body, idempotency_key: idempotency_key)
+      end
+
+      # Revoke API key
+      #
+      # @return [Hash]
+      def delete(id:)
+        @client.delete("/api/v1/account/api_keys/#{id}")
+      end
+    end
+
+    # Domains resource operations
+    # @api private
+    class DomainsResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # Register a domain
+      #
+      # @return [Hash]
+      def create(body: nil, idempotency_key: nil)
+        @client.post("/api/v1/account/domains", body: body, idempotency_key: idempotency_key)
+      end
+
+      # List domains
+      #
+      # @return [Hash]
+      def list(txt_status: nil, fully_verified: nil, primary: nil, page: nil, per_page: nil)
+        fetch_page = ->(p) {
+          response = @client.get("/api/v1/account/domains", params: { txt_status: txt_status, fully_verified: fully_verified, primary: primary, page: p, per_page: per_page })
+          Page.new(data: response[:data], meta: response[:meta], fetch_next: fetch_page)
+        }
+        fetch_page.call(page)
+      end
+
+      # Get domain details
+      #
+      # @return [Hash]
+      def get(id:)
+        @client.get("/api/v1/account/domains/#{id}")
+      end
+
+      # Delete a domain
+      #
+      # @return [Hash]
+      def delete(id:)
+        @client.delete("/api/v1/account/domains/#{id}")
+      end
+
+      # Verify domain
+      #
+      # @return [Hash]
+      def verify(id:, idempotency_key: nil)
+        @client.post("/api/v1/account/domains/#{id}/verify", idempotency_key: idempotency_key)
+      end
+    end
+
+    # Signing_keys resource operations
+    # @api private
+    class SigningKeysResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # Generate a signing key
+      #
+      # @return [Hash]
+      def create(body: nil, idempotency_key: nil)
+        @client.post("/api/v1/account/signing_keys", body: body, idempotency_key: idempotency_key)
+      end
+
+      # List signing keys
+      #
+      # @return [Hash]
+      def list(status: nil, algorithm: nil, usable: nil, page: nil, per_page: nil)
+        fetch_page = ->(p) {
+          response = @client.get("/api/v1/account/signing_keys", params: { status: status, algorithm: algorithm, usable: usable, page: p, per_page: per_page })
+          Page.new(data: response[:data], meta: response[:meta], fetch_next: fetch_page)
+        }
+        fetch_page.call(page)
+      end
+
+      # Get signing key details
+      #
+      # @return [Hash]
+      def get(id:)
+        @client.get("/api/v1/account/signing_keys/#{id}")
+      end
+
+      # Rotate a signing key
+      #
+      # @return [Hash]
+      def rotate(id:, body: nil, idempotency_key: nil)
+        @client.post("/api/v1/account/signing_keys/#{id}/rotate", body: body, idempotency_key: idempotency_key)
+      end
+
+      # Revoke a signing key
+      #
+      # @return [Hash]
+      def revoke(id:, idempotency_key: nil)
+        @client.post("/api/v1/account/signing_keys/#{id}/revoke", idempotency_key: idempotency_key)
+      end
+
+      # Download X.509 certificate
+      #
+      # @return [Hash]
+      def certificate(id:, domain: nil)
+        @client.get("/api/v1/account/signing_keys/#{id}/certificate", params: { domain: domain })
+      end
+    end
+
+    # Webhooks resource operations
+    # @api private
+    class WebhooksResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # List webhooks
+      #
+      # @return [Hash]
+      def list
+        @client.get("/api/v1/account/webhooks")
+      end
+
+      # Create webhook
+      #
+      # @return [Hash]
+      def create(body: nil, idempotency_key: nil)
+        @client.post("/api/v1/account/webhooks", body: body, idempotency_key: idempotency_key)
+      end
+
+      # Get webhook details
+      #
+      # @return [Hash]
+      def get
+        @client.get("/api/v1/account/webhooks/primary")
+      end
+
+      # Update webhook
+      #
+      # @return [Hash]
+      def update(body: nil, idempotency_key: nil)
+        @client.patch("/api/v1/account/webhooks/primary", body: body, idempotency_key: idempotency_key)
+      end
+
+      # Delete webhook
+      #
+      # @return [Hash]
+      def delete
+        @client.delete("/api/v1/account/webhooks/primary")
+      end
+
+      # Test webhook
+      #
+      # @return [Hash]
+      def test(idempotency_key: nil)
+        @client.post("/api/v1/account/webhooks/primary/test", idempotency_key: idempotency_key)
+      end
+    end
+  end
+end

data/lib/aho_sdk/cursor_page.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Auto-generated by bin/generate_sdks.rb - DO NOT EDIT
+
+module AhoSdk
+  # Cursor-paginated response with lazy iteration support
+  #
+  # @example Iterate through all pages
+  #   page = issuer.credentials.list
+  #   page.each do |credential|
+  #     puts credential[:uuid]
+  #   end
+  #
+  # @example Manual pagination
+  #   page = issuer.credentials.list
+  #   while page
+  #     page.data.each { |c| puts c[:uuid] }
+  #     page = page.next_page
+  #   end
+  #
+  class CursorPage
+    include Enumerable
+
+    attr_reader :data, :meta
+
+    # @param data [Array<Hash>] Items on this page
+    # @param meta [Hash] Pagination metadata (cursor, has_more, next_cursor)
+    # @param fetch_next [Proc] Lambda to fetch the next page given a cursor
+    def initialize(data:, meta:, fetch_next:)
+      @data = data
+      @meta = meta
+      @fetch_next = fetch_next
+    end
+
+    # Iterate through all items across all pages (lazy loading)
+    # @yield [Hash] Each item
+    # @return [Enumerator] if no block given
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      page = self
+      loop do
+        page.data.each(&block)
+        page = page.next_page
+        break if page.nil?
+      end
+    end
+
+    # Fetch the next page
+    # @return [CursorPage, nil] Next page or nil if this is the last page
+    def next_page
+      return nil unless has_more?
+
+      cursor = next_cursor
+      return nil if cursor.nil?
+
+      @fetch_next.call(cursor)
+    end
+
+    # @return [Boolean] true if there are more pages
+    def has_more?
+      meta[:has_more] || meta["has_more"] || false
+    end
+
+    # @return [String, nil] Cursor for the next page
+    def next_cursor
+      meta[:next_cursor] || meta["next_cursor"]
+    end
+
+    # @return [String, nil] Cursor for the current page (if provided)
+    def cursor
+      meta[:cursor] || meta["cursor"]
+    end
+
+    # @return [Integer] Number of items per page (if provided)
+    def per_page
+      meta[:per_page] || meta["per_page"]
+    end
+
+    # @return [Integer] Number of items on this page
+    def size
+      data.size
+    end
+
+    alias_method :length, :size
+  end
+end