logseal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5a6004e9884c8794c64dfb5071e98d30d113dbadc7569e3acc38b8ea4985de5
+  data.tar.gz: 865c789da10735a16729ba40e7d761d245663b3e9c6c8202e31dfc0b0211d133
+SHA512:
+  metadata.gz: 4b1dad1ae610793fc31e690554d37c8fa9e1c55b7e8ecc74aaca8c646edaca3a3ef870f312ebacae72199184f7f7aeb606f0acb1f753894b33e451eb938d8943
+  data.tar.gz: 01350f3dc8c5f72df2f7adbae0e6af54604010dde63a73ecd30b14b3ea38b21d02e9427c1693ddcbb67a41e9774aaf7aef38b494f8400d9c292b0eb6b302a66a

data/README.md

@@ -0,0 +1,174 @@
+# logseal
+
+Official Ruby SDK for [LogSeal](https://logseal.io) — Audit logging for B2B SaaS.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "logseal"
+```
+
+Or install directly:
+
+```bash
+gem install logseal
+```
+
+## Quick Start
+
+```ruby
+require "logseal"
+
+client = LogSeal.new(api_key: "sk_test_...")
+
+# Emit an event (batched, non-blocking)
+client.emit(
+  action: "document.published",
+  organization_id: "org_acme",
+  actor: { id: "user_123", name: "Jane Smith", email: "jane@acme.com" },
+  targets: [{ type: "document", id: "doc_456", name: "Q3 Report" }],
+  metadata: { previous_status: "draft" }
+)
+
+# Emit and wait for confirmation
+event = client.emit_sync(
+  action: "user.deleted",
+  organization_id: "org_acme",
+  actor: { id: "admin_1" },
+  targets: [{ type: "user", id: "user_123" }]
+)
+puts "Event ID: #{event['id']}"
+
+# Graceful shutdown (flushes remaining events)
+at_exit { client.shutdown }
+```
+
+## Configuration
+
+```ruby
+client = LogSeal.new(
+  api_key: "sk_live_...",          # Required
+  base_url: "https://api.logseal.io", # Optional override
+  batch_size: 100,                 # Events to buffer before auto-flushing
+  flush_interval: 5,              # Seconds between automatic flushes
+  max_retries: 3                  # Retry attempts on 429 / 5xx responses
+)
+```
+
+## Querying Events
+
+```ruby
+# Paginated list
+page = client.events.list(
+  organization_id: "org_acme",
+  action: "document.published",
+  limit: 50
+)
+
+page["data"].each do |event|
+  puts "#{event['action']} by #{event.dig('actor', 'name')}"
+end
+
+# Auto-paginate through all results
+client.events.list_all(organization_id: "org_acme") do |event|
+  puts event["action"]
+end
+
+# Or use as an Enumerator
+client.events.list_all(organization_id: "org_acme").each_with_index do |event, i|
+  break if i >= 1000
+  puts event["action"]
+end
+```
+
+## Organizations
+
+```ruby
+orgs = client.organizations.list
+org = client.organizations.create(external_id: "acme", name: "Acme Corp")
+org = client.organizations.get("org_123")
+```
+
+## Event Schemas
+
+```ruby
+schemas = client.schemas.list
+schema = client.schemas.create(
+  action: "document.updated",
+  description: "Fired when a document is modified",
+  target_types: ["document"]
+)
+schema = client.schemas.update("sch_123", description: "Updated desc")
+client.schemas.delete("sch_123")
+```
+
+## Viewer Tokens
+
+```ruby
+token = client.viewer_tokens.create(organization_id: "org_acme", expires_in: 3600)
+# Pass token["token"] to your frontend for the embeddable viewer
+```
+
+## Webhooks
+
+```ruby
+webhooks = client.webhooks.list
+webhook = client.webhooks.create(url: "https://example.com/webhooks/logseal", events: ["*"])
+puts "Secret: #{webhook['secret']}" # Only returned on creation
+
+client.webhooks.update("whk_123", enabled: false)
+client.webhooks.delete("whk_123")
+```
+
+## Exports
+
+```ruby
+export = client.exports.create(
+  organization_id: "org_acme",
+  format: "csv",
+  filters: { after: "2024-01-01" }
+)
+
+# Poll until complete
+completed = client.exports.poll(export["id"], timeout: 120)
+puts "Download: #{completed['download_url']}"
+```
+
+## Verification
+
+```ruby
+result = client.events.verify(organization_id: "org_acme")
+puts result["status"] # "valid", "broken", or "tampered"
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.emit_sync(action: "test", organization_id: "o", actor: { id: "u" })
+rescue LogSeal::Error => e
+  puts "[#{e.type}] #{e.code}: #{e.message}"
+  puts "HTTP status: #{e.status_code}"
+end
+```
+
+All API errors are raised as `LogSeal::Error`:
+
+| Method | Description |
+|--------|-------------|
+| `type` | Error category (`authentication_error`, `validation_error`, etc.) |
+| `code` | Machine-readable code (`invalid_api_key`, `missing_required_field`, etc.) |
+| `message` | Human-readable description |
+| `param` | Request parameter that caused the error (if applicable) |
+| `status_code` | HTTP status code |
+
+## Requirements
+
+- Ruby 3.0+
+- Faraday 2.x
+
+## License
+
+MIT

data/lib/logseal/client.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "concurrent-ruby" if defined?(Concurrent)
+
+module LogSeal
+  # Main client for the LogSeal audit-logging API.
+  #
+  #   client = LogSeal::Client.new(api_key: "sk_test_...")
+  #   client.emit(action: "user.login", organization_id: "org_acme", actor: { id: "user_1" })
+  #   client.shutdown
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://api.logseal.io"
+    DEFAULT_BATCH_SIZE = 100
+    DEFAULT_FLUSH_INTERVAL = 5 # seconds
+    DEFAULT_MAX_RETRIES = 3
+
+    attr_reader :events, :organizations, :schemas, :viewer_tokens, :webhooks, :exports
+
+    # @param api_key [String] Your LogSeal API key.
+    # @param base_url [String] Override the API base URL.
+    # @param batch_size [Integer] Events to buffer before auto-flushing.
+    # @param flush_interval [Integer] Seconds between automatic flushes.
+    # @param max_retries [Integer] Retry attempts on 429 / 5xx responses.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, batch_size: DEFAULT_BATCH_SIZE,
+                   flush_interval: DEFAULT_FLUSH_INTERVAL, max_retries: DEFAULT_MAX_RETRIES)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url
+      @batch_size = batch_size
+      @flush_interval = flush_interval
+      @queue = []
+      @mutex = Mutex.new
+
+      @conn = Faraday.new(url: @base_url) do |f|
+        f.request :retry, max: max_retries, interval: 1, backoff_factor: 2,
+                          retry_statuses: [429, 500, 502, 503, 504]
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+        f.headers["Content-Type"] = "application/json"
+        f.headers["User-Agent"] = "logseal-ruby/#{VERSION}"
+      end
+
+      @events = Resources::Events.new(self)
+      @organizations = Resources::Organizations.new(self)
+      @schemas = Resources::Schemas.new(self)
+      @viewer_tokens = Resources::ViewerTokens.new(self)
+      @webhooks = Resources::Webhooks.new(self)
+      @exports = Resources::Exports.new(self)
+
+      start_flush_thread
+    end
+
+    # Queue an event for batched delivery.
+    #
+    #   client.emit(
+    #     action: "document.published",
+    #     organization_id: "org_acme",
+    #     actor: { id: "user_123", name: "Jane Smith" },
+    #     targets: [{ type: "document", id: "doc_456" }],
+    #     metadata: { previous_status: "draft" }
+    #   )
+    #
+    # @return [Hash] +{ status: "queued" }+
+    def emit(action:, organization_id:, actor:, targets: nil, metadata: nil,
+             context: nil, occurred_at: nil, idempotency_key: nil)
+      event = { action:, organization_id:, actor:, targets:, metadata:,
+                context:, occurred_at:, idempotency_key: }
+      validate_event!(event)
+
+      @mutex.synchronize { @queue << event }
+      flush if @queue.size >= @batch_size
+
+      { status: "queued" }
+    end
+
+    # Emit a single event and wait for server confirmation.
+    #
+    # @return [Hash] The created event record.
+    def emit_sync(action:, organization_id:, actor:, **opts)
+      event = { action:, organization_id:, actor:, **opts }
+      validate_event!(event)
+      request(:post, "/v1/events", body: format_event(event))
+    end
+
+    # Flush all queued events immediately.
+    #
+    # @return [Integer] Number of events accepted.
+    def flush
+      batch = @mutex.synchronize do
+        return 0 if @queue.empty?
+        events = @queue.dup
+        @queue.clear
+        events
+      end
+
+      body = { events: batch.map { |e| format_event(e) } }
+      begin
+        resp = request(:post, "/v1/events/batch", body:)
+        resp["accepted"] || 0
+      rescue StandardError
+        @mutex.synchronize { @queue.unshift(*batch) }
+        raise
+      end
+    end
+
+    # Flush remaining events and stop the background thread.
+    def shutdown
+      @flush_thread&.kill
+      @flush_thread = nil
+      flush
+    end
+
+    # @api private
+    def request(method, path, body: nil, params: nil)
+      response = @conn.run_request(method, path, body ? JSON.generate(body) : nil, nil) do |req|
+        req.params.update(params) if params
+      end
+
+      data = response.body.empty? ? {} : JSON.parse(response.body)
+
+      unless response.success?
+        err = data["error"] || {}
+        raise Error.new(
+          type: err["type"] || "internal_error",
+          code: err["code"] || "unknown",
+          message: err["message"] || "Unknown error",
+          param: err["param"],
+          doc_url: err["doc_url"],
+          status_code: response.status
+        )
+      end
+
+      data
+    end
+
+    private
+
+    def start_flush_thread
+      @flush_thread = Thread.new do
+        loop do
+          sleep @flush_interval
+          flush
+        rescue StandardError
+          # Swallow — errors surface on next explicit flush
+        end
+      end
+      @flush_thread.abort_on_exception = false
+    end
+
+    def validate_event!(event)
+      raise Error.new(type: "validation_error", code: "missing_required_field",
+                      message: "The 'action' field is required.", param: "action") if event[:action].nil? || event[:action].empty?
+
+      actor = event[:actor]
+      raise Error.new(type: "validation_error", code: "missing_required_field",
+                      message: "The 'actor[:id]' field is required.", param: "actor.id") if actor.nil? || actor[:id].nil? || actor[:id].to_s.empty?
+
+      raise Error.new(type: "validation_error", code: "missing_required_field",
+                      message: "The 'organization_id' field is required.", param: "organization_id") if event[:organization_id].nil? || event[:organization_id].empty?
+    end
+
+    def format_event(event)
+      payload = {
+        action: event[:action],
+        organization_id: event[:organization_id],
+        actor: event[:actor].compact,
+      }
+      payload[:targets] = event[:targets].map(&:compact) if event[:targets]
+      payload[:metadata] = event[:metadata] if event[:metadata]
+      if event[:context]
+        payload[:context] = {
+          ip_address: event[:context][:ip_address],
+          user_agent: event[:context][:user_agent],
+          request_id: event[:context][:request_id],
+        }.compact
+      end
+      payload[:occurred_at] = event[:occurred_at] if event[:occurred_at]
+      payload[:idempotency_key] = event[:idempotency_key] if event[:idempotency_key]
+      payload
+    end
+  end
+end

data/lib/logseal/error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LogSeal
+  # Raised when the LogSeal API returns an error response.
+  #
+  #   begin
+  #     client.events.get("bad_id")
+  #   rescue LogSeal::Error => e
+  #     puts e.type        # => "not_found_error"
+  #     puts e.code        # => "event_not_found"
+  #     puts e.message     # => "Event not found"
+  #     puts e.status_code # => 404
+  #   end
+  class Error < StandardError
+    attr_reader :type, :code, :param, :doc_url, :status_code
+
+    def initialize(type:, code:, message:, param: nil, doc_url: nil, status_code: 400)
+      super(message)
+      @type = type
+      @code = code
+      @param = param
+      @doc_url = doc_url
+      @status_code = status_code
+    end
+
+    def to_s
+      "[#{type}] #{code}: #{super}"
+    end
+  end
+end

data/lib/logseal/resources/events.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module LogSeal
+  module Resources
+    class Events
+      def initialize(client)
+        @client = client
+      end
+
+      # List events with filtering and pagination.
+      #
+      #   page = client.events.list(organization_id: "org_acme", action: "user.login", limit: 50)
+      #   page["data"].each { |e| puts e["action"] }
+      def list(organization_id:, action: nil, action_prefix: nil, actor_id: nil,
+               target_type: nil, target_id: nil, after: nil, before: nil,
+               search: nil, limit: nil, cursor: nil)
+        params = { organization_id: }.compact
+        params[:action] = action if action
+        params[:action_prefix] = action_prefix if action_prefix
+        params[:actor_id] = actor_id if actor_id
+        params[:target_type] = target_type if target_type
+        params[:target_id] = target_id if target_id
+        params[:after] = after if after
+        params[:before] = before if before
+        params[:search] = search if search
+        params[:limit] = limit if limit
+        params[:cursor] = cursor if cursor
+
+        @client.request(:get, "/v1/events", params:)
+      end
+
+      # Retrieve a single event by ID.
+      def get(event_id)
+        @client.request(:get, "/v1/events/#{event_id}")
+      end
+
+      # Verify hash-chain integrity.
+      def verify(organization_id:, after: nil, before: nil)
+        body = { organization_id: }
+        body[:after] = after if after
+        body[:before] = before if before
+        @client.request(:post, "/v1/events/verify", body:)
+      end
+
+      # Verify a specific sequence range.
+      def verify_range(organization_id:, from_sequence:, to_sequence:)
+        @client.request(:post, "/v1/events/verify-range", body: {
+          organization_id:, from_sequence:, to_sequence:
+        })
+      end
+
+      # Retrieve the Merkle proof for an event.
+      def get_proof(event_id)
+        @client.request(:get, "/v1/events/#{event_id}/proof")
+      end
+
+      # Auto-paginate through all matching events.
+      #
+      #   client.events.list_all(organization_id: "org_acme") do |event|
+      #     puts "#{event['action']} by #{event.dig('actor', 'name')}"
+      #   end
+      #
+      # @return [Enumerator] if no block is given.
+      def list_all(**params, &block)
+        return enum_for(:list_all, **params) unless block
+
+        cursor = nil
+        loop do
+          page = list(**params, cursor:)
+          page["data"].each(&block)
+          cursor = page["next_cursor"]
+          break unless page["has_more"] && cursor
+        end
+      end
+    end
+  end
+end

data/lib/logseal/resources/exports.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LogSeal
+  module Resources
+    class Exports
+      def initialize(client)
+        @client = client
+      end
+
+      # Start a new export job.
+      def create(organization_id:, format:, filters: nil)
+        body = { organization_id:, format: }
+        body[:filters] = filters if filters
+        @client.request(:post, "/v1/exports", body:)
+      end
+
+      # Check the status of an export job.
+      def get(id)
+        @client.request(:get, "/v1/exports/#{id}")
+      end
+
+      # Poll an export until it completes or fails.
+      #
+      # @param id [String] The export job ID.
+      # @param interval [Numeric] Seconds between polls (default 1).
+      # @param timeout [Numeric] Maximum seconds to wait (default 60).
+      # @return [Hash] The completed or failed export.
+      def poll(id, interval: 1, timeout: 60)
+        deadline = Time.now + timeout
+        loop do
+          export = get(id)
+          return export if %w[completed failed].include?(export["status"])
+          raise Error.new(type: "internal_error", code: "export_timeout",
+                          message: "Export did not complete within the timeout period.") if Time.now >= deadline
+          sleep interval
+        end
+      end
+    end
+  end
+end

data/lib/logseal/resources/organizations.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LogSeal
+  module Resources
+    class Organizations
+      def initialize(client)
+        @client = client
+      end
+
+      # List all organizations.
+      def list
+        @client.request(:get, "/v1/organizations")
+      end
+
+      # Create a new organization.
+      def create(external_id:, name: nil)
+        body = { external_id: }
+        body[:name] = name if name
+        @client.request(:post, "/v1/organizations", body:)
+      end
+
+      # Retrieve an organization by ID.
+      def get(id)
+        @client.request(:get, "/v1/organizations/#{id}")
+      end
+    end
+  end
+end

data/lib/logseal/resources/schemas.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module LogSeal
+  module Resources
+    class Schemas
+      def initialize(client)
+        @client = client
+      end
+
+      def list
+        @client.request(:get, "/v1/schemas")
+      end
+
+      def create(action:, description: nil, target_types: nil, metadata_schema: nil)
+        body = { action: }
+        body[:description] = description if description
+        body[:target_types] = target_types if target_types
+        body[:metadata_schema] = metadata_schema if metadata_schema
+        @client.request(:post, "/v1/schemas", body:)
+      end
+
+      def get(id)
+        @client.request(:get, "/v1/schemas/#{id}")
+      end
+
+      def update(id, **fields)
+        @client.request(:patch, "/v1/schemas/#{id}", body: fields)
+      end
+
+      def delete(id)
+        @client.request(:delete, "/v1/schemas/#{id}")
+      end
+    end
+  end
+end

data/lib/logseal/resources/viewer_tokens.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LogSeal
+  module Resources
+    class ViewerTokens
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a short-lived viewer token for the embeddable log viewer.
+      def create(organization_id:, expires_in: nil)
+        body = { organization_id: }
+        body[:expires_in] = expires_in if expires_in
+        @client.request(:post, "/v1/viewer-tokens", body:)
+      end
+    end
+  end
+end

data/lib/logseal/resources/webhooks.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LogSeal
+  module Resources
+    class Webhooks
+      def initialize(client)
+        @client = client
+      end
+
+      def list
+        @client.request(:get, "/v1/webhooks")
+      end
+
+      # Create a new webhook. The signing +secret+ is only returned once.
+      def create(url:, organization_id: nil, events: nil, enabled: nil)
+        body = { url: }
+        body[:organization_id] = organization_id if organization_id
+        body[:events] = events if events
+        body[:enabled] = enabled unless enabled.nil?
+        @client.request(:post, "/v1/webhooks", body:)
+      end
+
+      def get(id)
+        @client.request(:get, "/v1/webhooks/#{id}")
+      end
+
+      def update(id, **fields)
+        @client.request(:patch, "/v1/webhooks/#{id}", body: fields)
+      end
+
+      def delete(id)
+        @client.request(:delete, "/v1/webhooks/#{id}")
+      end
+    end
+  end
+end

data/lib/logseal/version.rb

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

data/lib/logseal.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "logseal/version"
+require_relative "logseal/error"
+require_relative "logseal/client"
+require_relative "logseal/resources/events"
+require_relative "logseal/resources/organizations"
+require_relative "logseal/resources/schemas"
+require_relative "logseal/resources/viewer_tokens"
+require_relative "logseal/resources/webhooks"
+require_relative "logseal/resources/exports"
+
+module LogSeal
+  class << self
+    # Convenience constructor.
+    #
+    #   client = LogSeal.new(api_key: "sk_test_...")
+    def new(**kwargs)
+      Client.new(**kwargs)
+    end
+  end
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: logseal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- LogSeal
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: Audit logging for B2B SaaS — emit, query, verify, and export audit events.
+email: support@logseal.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/logseal.rb
+- lib/logseal/client.rb
+- lib/logseal/error.rb
+- lib/logseal/resources/events.rb
+- lib/logseal/resources/exports.rb
+- lib/logseal/resources/organizations.rb
+- lib/logseal/resources/schemas.rb
+- lib/logseal/resources/viewer_tokens.rb
+- lib/logseal/resources/webhooks.rb
+- lib/logseal/version.rb
+homepage: https://github.com/LogSeal/logseal-sdks/tree/main/packages/ruby
+licenses:
+- MIT
+metadata: {}
+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.4.1
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for LogSeal
+test_files: []