Class: Invoance::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/invoance/client.rb

Overview

Top-level SDK client.

# Reads INVOANCE_API_KEY / INVOANCE_BASE_URL from env automatically
client = Invoance::Client.new

# Or pass explicitly to override
client = Invoance::Client.new(api_key: "inv_live_abc123")

event = client.events.ingest(event_type: "user.login", payload: { user_id: "u_42" })

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: nil, api_version: "v1", timeout: 30, idempotency_key: nil, extra_headers: {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String, nil) (defaults to: nil)
  • base_url (String, nil) (defaults to: nil)
  • api_version (String) (defaults to: "v1")
  • timeout (Numeric) (defaults to: 30) —

    seconds

  • idempotency_key (String, nil) (defaults to: nil)
  • extra_headers (Hash) (defaults to: {}) 


31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/invoance/client.rb', line 31

def initialize(api_key: nil, base_url: nil, api_version: "v1", timeout: 30,
               idempotency_key: nil, extra_headers: {})
  @config = Config.new(
    api_key: api_key,
    base_url: base_url,
    api_version: api_version,
    timeout: timeout,
    idempotency_key: idempotency_key,
    extra_headers: extra_headers
  )
  @http = Http.new(@config)

  @events = Resources::Events.new(@http)
  @documents = Resources::Documents.new(@http)
  @attestations = Resources::Attestations.new(@http)
  @traces = Resources::Traces.new(@http)
  @audit = Resources::Audit.new(@http)
end

Instance Attribute Details

#attestations ⇒ Object (readonly)

Returns the value of attribute attestations.



23
24
25
 
# File 'lib/invoance/client.rb', line 23

def attestations
  @attestations
end

#audit ⇒ Object (readonly)

Returns the value of attribute audit.



23
24
25
 
# File 'lib/invoance/client.rb', line 23

def audit
  @audit
end

#documents ⇒ Object (readonly)

Returns the value of attribute documents.



23
24
25
 
# File 'lib/invoance/client.rb', line 23

def documents
  @documents
end

#events ⇒ Object (readonly)

Returns the value of attribute events.



23
24
25
 
# File 'lib/invoance/client.rb', line 23

def events
  @events
end

#traces ⇒ Object (readonly)

Returns the value of attribute traces.



23
24
25
 
# File 'lib/invoance/client.rb', line 23

def traces
  @traces
end

Instance Method Details

#base_url ⇒ String

The resolved base URL in use.

Returns:

  • (String) 


52
53
54
 
# File 'lib/invoance/client.rb', line 52

def base_url
  @config.base_url
end

#me ⇒ Hash

Introspect the API key via GET /v1/me. Requires no scope, so it works for any valid key. Raises like every other resource call.

Returns:

  • (Hash) —

    { "valid" =>, "organization" =>, "tenant" =>, "api_key" =>, "limits" => } (string keys, wire JSON as-is)



61
62
63
 
# File 'lib/invoance/client.rb', line 61

def me
  @http.get("/me")
end

#validate ⇒ Hash

Call the scope-free introspection endpoint (GET /v1/me) to confirm the API key works. NEVER raises.

Returns:

  • (Hash) —

    { "valid" =>, "reason" =>, "base_url" => }



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/invoance/client.rb', line 69

def validate
  base = @config.base_url
  begin
    me
    { "valid" => true, "reason" => nil, "base_url" => base }
  rescue AuthenticationError
    { "valid" => false,
      "reason" => "Authentication failed — check INVOANCE_API_KEY",
      "base_url" => base }
  rescue ForbiddenError
    { "valid" => true,
      "reason" => "API key authenticated but the request was blocked (IP access rules)",
      "base_url" => base }
  rescue QuotaExceededError
    { "valid" => true,
      "reason" => "API key authenticated but currently rate limited",
      "base_url" => base }
  rescue NetworkError, TimeoutError => e
    { "valid" => false, "reason" => "Server unreachable: #{e.message}", "base_url" => base }
  rescue Error => e
    { "valid" => false, "reason" => e.message, "base_url" => base }
  end
end