invoance 0.1.0

data/lib/invoance/resources/documents.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "../validate"
+
+module Invoance
+  module Resources
+    # Documents resource — client.documents.*
+    class Documents
+      # @param http [Invoance::Http]
+      def initialize(http)
+        @http = http
+      end
+
+      # POST /document/anchor — Anchor a document hash.
+      #
+      # @param document_hash [String] hex SHA-256 (validated)
+      # @return [Hash] AnchorDocumentResponse
+      def anchor(document_hash:, document_ref: nil, event_type: nil, original_bytes_b64: nil,
+                 metadata: nil, trace_id: nil, idempotency_key: nil)
+        Validate.assert_sha256_hex("document_hash", document_hash)
+        body = { "document_hash" => document_hash }
+        body["document_ref"] = document_ref unless document_ref.nil?
+        body["event_type"] = event_type unless event_type.nil?
+        body["original_bytes_b64"] = original_bytes_b64 unless original_bytes_b64.nil?
+        body["metadata"] = metadata unless metadata.nil?
+        body["trace_id"] = trace_id unless trace_id.nil?
+        @http.post("/document/anchor", body, idempotency_key)
+      end
+
+      # Convenience helper — reads a file (path String or raw bytes String),
+      # computes the SHA-256 hash, base64-encodes the bytes, then anchors.
+      #
+      # @param file [String] a filesystem path OR raw file bytes
+      # @param is_path [Boolean] whether `file` is a path (default: true).
+      #   When bytes are passed directly, set is_path: false.
+      # @param skip_original [Boolean] omit uploading the original bytes
+      # @return [Hash] AnchorDocumentResponse
+      def anchor_file(file:, is_path: true, document_ref: nil, event_type: nil,
+                      metadata: nil, trace_id: nil, idempotency_key: nil, skip_original: false)
+        content =
+          if is_path
+            File.binread(file)
+          else
+            file.dup.force_encoding(Encoding::BINARY)
+          end
+
+        document_hash = Digest::SHA256.hexdigest(content)
+        ref = document_ref || (is_path ? File.basename(file) : nil)
+        # Strict Base64 (no line breaks) via stdlib pack — avoids depending on
+        # the `base64` gem, which left Ruby's default gems in 3.4+.
+        original_b64 = skip_original ? nil : [content].pack("m0")
+
+        anchor(
+          document_hash: document_hash,
+          document_ref: ref,
+          event_type: event_type,
+          metadata: metadata,
+          idempotency_key: idempotency_key,
+          original_bytes_b64: original_b64,
+          trace_id: trace_id
+        )
+      end
+
+      # GET /document — Paginated document listing.
+      # @return [Hash] ListDocumentsResponse
+      def list(page: nil, limit: nil, date_from: nil, date_to: nil, document_ref: nil)
+        @http.get("/document", {
+                    "page" => page,
+                    "limit" => limit,
+                    "date_from" => date_from,
+                    "date_to" => date_to,
+                    "document_ref" => document_ref
+                  })
+      end
+
+      # GET /document/:event_id — Retrieve a single document.
+      # @return [Hash] DocumentEvent
+      def get(event_id)
+        @http.get("/document/#{event_id}")
+      end
+
+      # GET /document/:event_id/original — Download the original file.
+      # @return [String] raw binary bytes
+      def get_original(event_id)
+        @http.get_bytes("/document/#{event_id}/original")
+      end
+
+      # POST /document/:event_id/verify — Hash verification.
+      # @return [Hash] VerifyDocumentResponse
+      def verify(event_id, document_hash:)
+        Validate.assert_sha256_hex("document_hash", document_hash)
+        @http.post("/document/#{event_id}/verify", { "document_hash" => document_hash })
+      end
+    end
+  end
+end

data/lib/invoance/resources/events.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../validate"
+
+module Invoance
+  module Resources
+    # Events resource — client.events.*
+    class Events
+      # @param http [Invoance::Http]
+      def initialize(http)
+        @http = http
+      end
+
+      # POST /events — Ingest a compliance event.
+      #
+      # @param event_type [String]
+      # @param payload [Hash]
+      # @param event_time [String, nil]
+      # @param trace_id [String, nil]
+      # @param idempotency_key [String, nil]
+      # @return [Hash] IngestEventResponse
+      def ingest(event_type:, payload:, event_time: nil, trace_id: nil, idempotency_key: nil)
+        body = { "event_type" => event_type, "payload" => payload }
+        body["event_time"] = event_time if event_time
+        body["trace_id"] = trace_id if trace_id
+        @http.post("/events", body, idempotency_key)
+      end
+
+      # GET /events — Paginated event listing.
+      #
+      # @return [Hash] ListEventsResponse
+      def list(page: nil, limit: nil, date_from: nil, date_to: nil, event_type: nil)
+        @http.get("/events", {
+                    "page" => page,
+                    "limit" => limit,
+                    "date_from" => date_from,
+                    "date_to" => date_to,
+                    "event_type" => event_type
+                  })
+      end
+
+      # GET /events/:event_id — Retrieve a single event.
+      # @return [Hash] ComplianceEvent
+      def get(event_id)
+        @http.get("/events/#{event_id}")
+      end
+
+      # POST /events/:event_id/verify — Hash verification.
+      #
+      # Provide EITHER payload_hash (hex SHA-256) OR payload (raw JSON).
+      # Passing neither raises {Invoance::ValidationError}.
+      #
+      # @return [Hash] VerifyEventResponse
+      def verify(event_id, payload_hash: nil, payload: nil)
+        if payload_hash.nil? && payload.nil?
+          raise ValidationError, "events.verify requires either `payload_hash` or `payload`"
+        end
+
+        body = {}
+        unless payload_hash.nil?
+          Validate.assert_sha256_hex("payload_hash", payload_hash)
+          body["payload_hash"] = payload_hash
+        end
+        body["payload"] = payload unless payload.nil?
+
+        @http.post("/events/#{event_id}/verify", body)
+      end
+    end
+  end
+end

data/lib/invoance/resources/traces.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Invoance
+  module Resources
+    # Traces resource — client.traces.*
+    class Traces
+      # @param http [Invoance::Http]
+      def initialize(http)
+        @http = http
+      end
+
+      # POST /traces — Create a new trace.
+      # @return [Hash] CreateTraceResponse
+      def create(label:, metadata: nil)
+        body = { "label" => label }
+        body["metadata"] = metadata if metadata
+        @http.post("/traces", body)
+      end
+
+      # GET /traces — Paginated trace listing. status in open|sealed.
+      # @return [Hash] ListTracesResponse
+      def list(page: nil, limit: nil, status: nil)
+        @http.get("/traces", { "page" => page, "limit" => limit, "status" => status })
+      end
+
+      # GET /traces/:trace_id — Trace detail with paginated events.
+      # @return [Hash] TraceDetail
+      def get(trace_id, event_page: nil, event_limit: nil)
+        @http.get("/traces/#{trace_id}", {
+                    "event_page" => event_page,
+                    "event_limit" => event_limit
+                  })
+      end
+
+      # DELETE /traces/:trace_id — Delete an empty open trace.
+      # @return [Hash] DeleteTraceResponse
+      def delete(trace_id)
+        @http.delete("/traces/#{trace_id}")
+      end
+
+      # POST /traces/:trace_id/seal — Seal a trace (async, 202).
+      # @return [Hash] SealTraceResponse
+      def seal(trace_id)
+        @http.post("/traces/#{trace_id}/seal", {})
+      end
+
+      # GET /traces/:trace_id/proof — Export proof bundle as JSON.
+      # @return [Hash] TraceProofBundle
+      def proof(trace_id)
+        @http.get("/traces/#{trace_id}/proof")
+      end
+
+      # GET /traces/:trace_id/proof/pdf — Download proof bundle as PDF.
+      # @return [String] raw binary PDF bytes
+      def proof_pdf(trace_id)
+        @http.get_bytes("/traces/#{trace_id}/proof/pdf")
+      end
+    end
+  end
+end

data/lib/invoance/validate.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Invoance
+  # Shared client-side input validators.
+  # @api private
+  module Validate
+    HEX_SHA256 = /\A[0-9a-f]{64}\z/.freeze
+
+    # Validate that a value is a 64-char lowercase hex SHA-256 digest.
+    # Raises {Invoance::ValidationError} with a helpful message otherwise.
+    #
+    # @param field_name [String]
+    # @param value [Object]
+    # @return [void]
+    def self.assert_sha256_hex(field_name, value)
+      unless value.is_a?(String)
+        raise ValidationError,
+              "#{field_name} must be a string containing a 64-char hex SHA-256 digest " \
+              "(got #{value.class})"
+      end
+      if value.length != 64
+        raise ValidationError, "#{field_name} must be 64 hex chars (got #{value.length} chars)"
+      end
+      unless HEX_SHA256.match?(value)
+        raise ValidationError,
+              "#{field_name} must be lowercase hex [0-9a-f]; \"#{value[0, 16]}…\" is not"
+      end
+    end
+  end
+end

data/lib/invoance/version.rb

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

data/lib/invoance.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Invoance — Official Ruby SDK for the Invoance compliance API.
+#
+#   require "invoance"
+#
+#   client = Invoance::Client.new(api_key: "inv_live_abc123")
+#   event = client.events.ingest(event_type: "user.login", payload: { user_id: "u_42" })
+#
+# Audit-log offline verification helpers live in {Invoance::AuditVerify} and
+# {Invoance::AuditCanonical}; the content-idempotency-key helper is
+# {Invoance::Resources.content_idempotency_key}.
+module Invoance
+end
+
+require_relative "invoance/version"
+require_relative "invoance/errors"
+require_relative "invoance/config"
+require_relative "invoance/validate"
+require_relative "invoance/http"
+require_relative "invoance/audit_canonical"
+require_relative "invoance/audit_verify"
+require_relative "invoance/resources/events"
+require_relative "invoance/resources/documents"
+require_relative "invoance/resources/attestations"
+require_relative "invoance/resources/traces"
+require_relative "invoance/resources/audit"
+require_relative "invoance/client"

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: invoance
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Invoance, Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.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'
+description: 'Official Ruby SDK for the Invoance compliance API. Cryptographic proof
+  infrastructure: sign and verify events, documents, AI attestations, traces, and
+  audit logs. Zero runtime dependencies.'
+email:
+- sdk@invoance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/invoance.rb
+- lib/invoance/audit_canonical.rb
+- lib/invoance/audit_verify.rb
+- lib/invoance/client.rb
+- lib/invoance/config.rb
+- lib/invoance/errors.rb
+- lib/invoance/http.rb
+- lib/invoance/resources/attestations.rb
+- lib/invoance/resources/audit.rb
+- lib/invoance/resources/documents.rb
+- lib/invoance/resources/events.rb
+- lib/invoance/resources/traces.rb
+- lib/invoance/validate.rb
+- lib/invoance/version.rb
+homepage: https://invoance.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://invoance.com
+  source_code_uri: https://github.com/Invoance/invoance-ruby
+  changelog_uri: https://github.com/Invoance/invoance-ruby/blob/main/CHANGELOG.md
+  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.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Invoance compliance API
+test_files: []