invoance 0.1.0

data/lib/invoance/errors.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Invoance
+  # Base error for everything the SDK raises — API responses, network
+  # failures, and client-side validation. A single
+  # `rescue Invoance::Error` catches anything the SDK throws.
+  #
+  #   begin
+  #     client.events.ingest(event_type: "user.login", payload: { user_id: "u_42" })
+  #   rescue Invoance::QuotaExceededError
+  #     puts "Upgrade your plan"
+  #   rescue Invoance::TimeoutError
+  #     puts "Request timed out — retrying"
+  #   rescue Invoance::Error => e
+  #     puts "Invoance error: #{e.message}"
+  #   end
+  class Error < StandardError
+    attr_reader :status_code, :error_code, :body, :retry_after_seconds, :request_context
+
+    # @param message [String]
+    # @param status_code [Integer, nil]
+    # @param error_code [String, nil]
+    # @param body [Hash, nil] parsed JSON body (string keys)
+    # @param retry_after_seconds [Numeric, nil]
+    # @param request_context [Hash, nil] { method:, path: }
+    def initialize(message, status_code: nil, error_code: nil, body: nil,
+                   retry_after_seconds: nil, request_context: nil)
+      super(message)
+      @status_code = status_code
+      @error_code = error_code
+      @body = body
+      @retry_after_seconds = retry_after_seconds
+      @request_context = request_context
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class ForbiddenError < Error; end
+  class NotFoundError < Error; end
+
+  # 400 from the server, and also raised client-side for bad input.
+  class ValidationError < Error; end
+
+  class ConflictError < Error; end
+  class QuotaExceededError < Error; end
+  class ServerError < Error; end
+
+  # Raised when the request fails before a response is received —
+  # DNS failure, connection refused, TLS handshake error, etc.
+  class NetworkError < Error; end
+
+  # Raised when the request exceeds the configured timeout.
+  class TimeoutError < Error; end
+
+  # Status-code → error-class map. Anything >= 500 not listed maps to
+  # ServerError; any other unmapped status maps to the base Error.
+  STATUS_ERROR_MAP = {
+    400 => ValidationError,
+    401 => AuthenticationError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    429 => QuotaExceededError
+  }.freeze
+
+  # Raise the appropriate error for a non-2xx response. No-op on 2xx.
+  #
+  # @param status_code [Integer]
+  # @param body [Hash, nil] parsed JSON body (string keys), or nil
+  # @param request_context [Hash, nil] { method:, path: }
+  # @param retry_after_seconds [Numeric, nil]
+  def self.throw_for_status(status_code, body, request_context: nil, retry_after_seconds: nil)
+    return if status_code >= 200 && status_code < 300
+
+    b = body || {}
+    error_code = b["error"] || "unknown"
+    server_message = b["message"]
+
+    message =
+      if server_message
+        server_message
+      elsif status_code == 429 && !retry_after_seconds.nil?
+        "HTTP 429#{describe_request(request_context)} — rate limited, retry after #{retry_after_seconds}s"
+      else
+        "HTTP #{status_code}#{describe_request(request_context)} (no response body)"
+      end
+
+    klass = STATUS_ERROR_MAP[status_code] || (status_code >= 500 ? ServerError : Error)
+
+    raise klass.new(
+      message,
+      status_code: status_code,
+      error_code: error_code,
+      body: b,
+      request_context: request_context,
+      retry_after_seconds: retry_after_seconds
+    )
+  end
+
+  # @api private
+  def self.describe_request(ctx)
+    ctx ? " on #{ctx[:method]} #{ctx[:path]}" : ""
+  end
+end

data/lib/invoance/http.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+require "openssl"
+
+require_relative "errors"
+require_relative "version"
+
+module Invoance
+  # Low-level HTTP transport using stdlib net/http. Zero external
+  # dependencies. Network-level failures are raised as {Invoance::Error}
+  # subclasses (NetworkError / TimeoutError) so a single rescue is
+  # exhaustive.
+  #
+  # @api private
+  class Http
+    # @param config [Invoance::Config]
+    def initialize(config)
+      @config = config
+      @base_headers = {
+        "Authorization" => "Bearer #{config.api_key}",
+        "Accept" => "application/json",
+        "Content-Type" => "application/json",
+        "User-Agent" => "invoance-ruby/#{Invoance::VERSION}"
+      }.merge(config.extra_headers)
+    end
+
+    # GET returning parsed JSON (Hash with string keys).
+    def get(path, params = nil)
+      uri = build_uri(path, params)
+      ctx = { method: "GET", path: path }
+      resp = do_request(Net::HTTP::Get.new(uri), uri, ctx, headers: @base_headers)
+      handle(resp, ctx)
+    end
+
+    # POST returning parsed JSON. Sends Idempotency-Key when available.
+    def post(path, body = nil, idempotency_key = nil)
+      uri = build_uri(path)
+      ctx = { method: "POST", path: path }
+      headers = @base_headers.dup
+      idem = idempotency_key || @config.idempotency_key
+      headers["Idempotency-Key"] = idem if idem
+      req = Net::HTTP::Post.new(uri)
+      req.body = JSON.generate(body) unless body.nil?
+      resp = do_request(req, uri, ctx, headers: headers)
+      handle(resp, ctx)
+    end
+
+    # PUT returning parsed JSON.
+    def put(path, body = nil)
+      uri = build_uri(path)
+      ctx = { method: "PUT", path: path }
+      req = Net::HTTP::Put.new(uri)
+      req.body = JSON.generate(body) unless body.nil?
+      resp = do_request(req, uri, ctx, headers: @base_headers)
+      handle(resp, ctx)
+    end
+
+    # DELETE returning parsed JSON.
+    def delete(path)
+      uri = build_uri(path)
+      ctx = { method: "DELETE", path: path }
+      resp = do_request(Net::HTTP::Delete.new(uri), uri, ctx, headers: @base_headers)
+      handle(resp, ctx)
+    end
+
+    # GET returning raw bytes (binary String). Sets
+    # Accept: application/octet-stream and drops Content-Type.
+    def get_bytes(path)
+      uri = build_uri(path)
+      ctx = { method: "GET", path: path }
+      headers = @base_headers.dup
+      headers["Accept"] = "application/octet-stream"
+      headers.delete("Content-Type")
+      resp = do_request(Net::HTTP::Get.new(uri), uri, ctx, headers: headers)
+
+      unless success?(resp)
+        body = parse_json_body(resp)
+        Invoance.throw_for_status(resp.code.to_i, body,
+                                  request_context: ctx,
+                                  retry_after_seconds: parse_retry_after(resp["retry-after"]))
+      end
+
+      body = resp.body || ""
+      body.dup.force_encoding(Encoding::BINARY)
+    end
+
+    # GET returning the decoded JSON value untyped (used by attestations raw).
+    def get_raw(path)
+      get(path)
+    end
+
+    private
+
+    def build_uri(path, params = nil)
+      base = "#{@config.base_url}/#{@config.api_version}#{path}"
+      uri = URI.parse(base)
+      if params
+        pairs = params.reject { |_, v| v.nil? }.map { |k, v| [k.to_s, v.to_s] }
+        uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+      end
+      uri
+    end
+
+    def do_request(req, uri, ctx, headers:)
+      headers.each { |k, v| req[k] = v }
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+      http.write_timeout = @config.timeout if http.respond_to?(:write_timeout=)
+
+      begin
+        http.request(req)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error => e
+        raise TimeoutError.new(
+          "Request timed out after #{@config.timeout}s on #{ctx[:method]} #{ctx[:path]}",
+          request_context: ctx
+        )
+      rescue SocketError, SystemCallError, OpenSSL::SSL::SSLError, IOError => e
+        raise NetworkError.new(
+          "Network failure on #{ctx[:method]} #{ctx[:path]}: #{e.message}",
+          request_context: ctx
+        )
+      end
+    end
+
+    def handle(resp, ctx)
+      body = parse_json_body(resp)
+      Invoance.throw_for_status(resp.code.to_i, body,
+                                request_context: ctx,
+                                retry_after_seconds: parse_retry_after(resp["retry-after"]))
+      body
+    end
+
+    def parse_json_body(resp)
+      raw = resp.body
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def success?(resp)
+      code = resp.code.to_i
+      code >= 200 && code < 300
+    end
+
+    # Parse the Retry-After header: numeric seconds, or an HTTP-date
+    # converted to a delta from now (floored at 0). Returns nil if absent
+    # or unparseable.
+    def parse_retry_after(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      s = value.to_s.strip
+      if s.match?(/\A\d+(\.\d+)?\z/)
+        seconds = s.to_f
+        return seconds if seconds >= 0
+      end
+
+      begin
+        ts = Time.httpdate(s)
+        delta = ts.to_f - Time.now.to_f
+        return delta.negative? ? 0.0 : delta
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/invoance/resources/attestations.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+require_relative "../validate"
+require_relative "../audit_verify"
+
+module Invoance
+  module Resources
+    # AI Attestations resource — client.attestations.*
+    class Attestations
+      # @param http [Invoance::Http]
+      def initialize(http)
+        @http = http
+      end
+
+      # POST /ai/attestations — Anchor an AI attestation.
+      #
+      # The body is NESTED and field order matters for the server's hashing
+      # (type, payload, context, subject) — do not reorder.
+      #
+      # @param type [String]
+      # @param input [Object]
+      # @param output [Object]
+      # @param model_provider [String, nil]
+      # @param model_name [String, nil]
+      # @param model_version [String, nil]
+      # @param subject [Hash, nil] user_id/session_id + arbitrary extra keys
+      # @param trace_id [String, nil]
+      # @param idempotency_key [String, nil]
+      # @return [Hash] IngestAttestationResponse
+      def ingest(type:, input:, output:, model_provider: nil, model_name: nil,
+                 model_version: nil, subject: nil, trace_id: nil, idempotency_key: nil)
+        body = {
+          "type" => type,
+          "payload" => { "input" => input, "output" => output },
+          "context" => {
+            "model_provider" => model_provider,
+            "model_name" => model_name,
+            "model_version" => model_version
+          }
+        }
+
+        unless subject.nil?
+          s = symbolize_subject(subject)
+          user_id = s.delete(:user_id)
+          session_id = s.delete(:session_id)
+          subj = {}
+          subj["user_id"] = user_id unless user_id.nil?
+          subj["session_id"] = session_id unless session_id.nil?
+          # Pass through any remaining extra keys, preserving their string form.
+          s.each { |k, v| subj[k.to_s] = v }
+          body["subject"] = subj unless subj.empty?
+        end
+
+        body["trace_id"] = trace_id unless trace_id.nil?
+
+        @http.post("/ai/attestations", body, idempotency_key)
+      end
+
+      # GET /ai/attestations — Paginated attestation listing.
+      # @return [Hash] ListAttestationsResponse
+      def list(page: nil, limit: nil, date_from: nil, date_to: nil,
+               attestation_type: nil, model_provider: nil)
+        @http.get("/ai/attestations", {
+                    "page" => page,
+                    "limit" => limit,
+                    "date_from" => date_from,
+                    "date_to" => date_to,
+                    "attestation_type" => attestation_type,
+                    "model_provider" => model_provider
+                  })
+      end
+
+      # GET /ai/attestations/:id — Retrieve a single attestation.
+      # @return [Hash] AiAttestation
+      def get(attestation_id)
+        @http.get("/ai/attestations/#{attestation_id}")
+      end
+
+      # POST /ai/attestations/:id/verify — Hash verification.
+      # @return [Hash] VerifyAttestationResponse
+      def verify(attestation_id, content_hash:)
+        Validate.assert_sha256_hex("content_hash", content_hash)
+        @http.post("/ai/attestations/#{attestation_id}/verify",
+                   { "content_hash" => content_hash })
+      end
+
+      # GET /ai/attestations/:id/raw — Retrieve the canonical JSON payload.
+      # @return [Hash]
+      def get_raw(attestation_id)
+        @http.get_raw("/ai/attestations/#{attestation_id}/raw")
+      end
+
+      # Verify by raw payload — hashes client-side, then calls verify.
+      #
+      # Accepts the canonical JSON stored in Invoance as a raw String or a
+      # Hash. Key ORDER is PRESERVED (not sorted) because the backend hashes
+      # using serde_json struct field order (type, payload, context, subject).
+      #
+      # * String input: JSON.parse preserves object key order into an
+      #   insertion-ordered Hash, and JSON.generate preserves it — giving
+      #   compact order-preserving JSON (= JS JSON.stringify(JSON.parse(s))).
+      # * Hash input: JSON.generate preserves insertion order — pass the keys
+      #   already in the correct order.
+      #
+      # @param attestation_id [String]
+      # @param payload [String, Hash]
+      # @return [Hash] VerifyAttestationResponse
+      def verify_payload(attestation_id, payload)
+        canonical =
+          if payload.is_a?(String)
+            JSON.generate(JSON.parse(payload))
+          else
+            JSON.generate(payload)
+          end
+
+        content_hash = Digest::SHA256.hexdigest(canonical)
+        verify(attestation_id, content_hash: content_hash)
+      end
+
+      # Verify the Ed25519 signature of an attestation — fully client-side.
+      #
+      # Fetches the attestation, then verifies the signature against
+      # signed_payload using public_key. Requires no trust in the server.
+      #
+      # @param attestation_id [String]
+      # @return [Hash] { "valid" =>, "reason" =>, "attestation" =>, "signed_data" => }
+      def verify_signature(attestation_id)
+        att = get(attestation_id)
+
+        signed_payload_bytes = hex_to_bytes(att["signed_payload"].to_s)
+        signature_bytes = hex_to_bytes(att["signature"].to_s)
+        public_key_bytes = hex_to_bytes(att["public_key"].to_s)
+
+        valid = false
+        reason = nil
+        begin
+          valid = AuditVerify.ed25519_verify(signed_payload_bytes, signature_bytes, public_key_bytes)
+          reason = "Signature does not match signed_payload + public_key" unless valid
+        rescue StandardError => e
+          valid = false
+          reason = e.message
+        end
+
+        signed_data =
+          begin
+            JSON.parse(signed_payload_bytes.dup.force_encoding(Encoding::UTF_8))
+          rescue JSON::ParserError
+            nil
+          end
+
+        { "valid" => valid, "reason" => reason, "attestation" => att, "signed_data" => signed_data }
+      end
+
+      private
+
+      def hex_to_bytes(hex)
+        [hex].pack("H*")
+      end
+
+      def symbolize_subject(subject)
+        subject.each_with_object({}) do |(k, v), out|
+          key = k.is_a?(String) ? k.to_sym : k
+          out[key] = v
+        end
+      end
+    end
+  end
+end

data/lib/invoance/resources/audit.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "time"
+
+module Invoance
+  module Resources
+    # Deep-sort all Hash keys (alphabetically) then compact-serialize.
+    # Matches Node's stableStringify: no null-stripping, no schema forcing.
+    # @api private
+    def self.stable_stringify(value)
+      JSON.generate(sort_deep_for_stable(value))
+    end
+
+    # @api private
+    def self.sort_deep_for_stable(v)
+      case v
+      when Array
+        v.map { |x| sort_deep_for_stable(x) }
+      when Hash
+        v.keys.map(&:to_s).sort.each_with_object({}) do |k, out|
+          orig = v.key?(k) ? k : k.to_sym
+          out[k] = sort_deep_for_stable(v[orig])
+        end
+      else
+        v
+      end
+    end
+
+    # Derive a stable Idempotency-Key from an event body (safe-retry helper).
+    #
+    # @param body [Hash]
+    # @return [String]
+    def self.content_idempotency_key(body)
+      "idem_" + Digest::SHA256.hexdigest(stable_stringify(body))
+    end
+
+    # Audit Logs resource — client.audit.*
+    #
+    # Five sub-resources: events, orgs, streams, portal_sessions, exports.
+    class Audit
+      # audit.events.*
+      class Events
+        def initialize(http)
+          @http = http
+        end
+
+        # POST /audit/events — append one signed event.
+        # The ledger REQUIRES an Idempotency-Key; derive a content-stable one
+        # when none is provided.
+        # @return [Hash]
+        def ingest(organization_id:, action:, actor:, occurred_at: nil, targets: nil,
+                   context: nil, metadata: nil, idempotency_key: nil)
+          body = {
+            "organization_id" => organization_id,
+            "action" => action,
+            "occurred_at" => occurred_at || Time.now.utc.iso8601,
+            "actor" => actor,
+            "targets" => targets.nil? ? [] : targets
+          }
+          body["context"] = context if context
+          body["metadata"] = metadata if metadata
+          idem = idempotency_key || Resources.content_idempotency_key(body)
+          @http.post("/audit/events", body, idem)
+        end
+
+        # GET /audit/events — keyset-paginated listing.
+        # @return [Hash] ListAuditEventsResponse
+        def list(organization_id: nil, actions: nil, actor_id: nil, target_id: nil,
+                 range_start: nil, range_end: nil, limit: nil, cursor: nil)
+          @http.get("/audit/events", {
+                      "organization_id" => organization_id,
+                      "actions" => actions,
+                      "actor_id" => actor_id,
+                      "target_id" => target_id,
+                      "range_start" => range_start,
+                      "range_end" => range_end,
+                      "limit" => limit,
+                      "cursor" => cursor
+                    })
+        end
+
+        # GET /audit/events/:id
+        # @return [Hash] AuditEvent
+        def get(event_id)
+          @http.get("/audit/events/#{event_id}")
+        end
+
+        # GET /audit/events/:id/verify — server-side verify (pinned key).
+        # @return [Hash]
+        def verify(event_id)
+          @http.get("/audit/events/#{event_id}/verify")
+        end
+      end
+
+      # audit.orgs.*
+      class Orgs
+        def initialize(http)
+          @http = http
+        end
+
+        # POST /audit/orgs
+        def create(organization_id:, name: nil)
+          body = { "organization_id" => organization_id }
+          body["name"] = name if name
+          @http.post("/audit/orgs", body)
+        end
+
+        # GET /audit/orgs
+        def list
+          @http.get("/audit/orgs")
+        end
+
+        # GET /audit/orgs/:org_id/integrity
+        def integrity(organization_id)
+          @http.get("/audit/orgs/#{organization_id}/integrity")
+        end
+
+        # PUT /audit/orgs/:org_id/retention
+        def set_retention(organization_id, days)
+          @http.put("/audit/orgs/#{organization_id}/retention", { "days" => days })
+        end
+      end
+
+      # audit.streams.*
+      class Streams
+        def initialize(http)
+          @http = http
+        end
+
+        # POST /audit/orgs/:org_id/streams — create a webhook stream.
+        # The signing secret is returned ONCE.
+        def create(organization_id, url:, type: "webhook")
+          @http.post("/audit/orgs/#{organization_id}/streams", {
+                       "type" => type,
+                       "url" => url
+                     })
+        end
+
+        # GET /audit/orgs/:org_id/streams
+        def list(organization_id)
+          @http.get("/audit/orgs/#{organization_id}/streams")
+        end
+
+        # DELETE /audit/orgs/:org_id/streams/:stream_id
+        def delete(organization_id, stream_id)
+          @http.delete("/audit/orgs/#{organization_id}/streams/#{stream_id}")
+        end
+
+        # POST /audit/orgs/:org_id/streams/:stream_id/test
+        def test(organization_id, stream_id)
+          @http.post("/audit/orgs/#{organization_id}/streams/#{stream_id}/test")
+        end
+      end
+
+      # audit.portal_sessions.*
+      class PortalSessions
+        def initialize(http)
+          @http = http
+        end
+
+        # POST /audit/portal_sessions — mint a one-time hosted-viewer link.
+        def create(organization_id:, intent:, session_duration_seconds: nil,
+                   link_duration_seconds: nil)
+          body = { "organization_id" => organization_id, "intent" => intent }
+          body["session_duration_seconds"] = session_duration_seconds unless session_duration_seconds.nil?
+          body["link_duration_seconds"] = link_duration_seconds unless link_duration_seconds.nil?
+          @http.post("/audit/portal_sessions", body)
+        end
+      end
+
+      # audit.exports.*
+      class Exports
+        def initialize(http)
+          @http = http
+        end
+
+        # POST /audit/exports — queue an async CSV/NDJSON export job.
+        # @param format [String] "csv" or "ndjson"
+        def create(organization_id:, format:, filters: nil)
+          body = { "organization_id" => organization_id, "format" => format }
+          body["filters"] = filters if filters
+          @http.post("/audit/exports", body)
+        end
+
+        # GET /audit/exports/:id — poll a job.
+        def get(export_id)
+          @http.get("/audit/exports/#{export_id}")
+        end
+      end
+
+      attr_reader :events, :orgs, :streams, :portal_sessions, :exports
+
+      def initialize(http)
+        @events = Events.new(http)
+        @orgs = Orgs.new(http)
+        @streams = Streams.new(http)
+        @portal_sessions = PortalSessions.new(http)
+        @exports = Exports.new(http)
+      end
+    end
+  end
+end