Class: Invoance::Resources::Documents

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

Overview

Documents resource — client.documents.*

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ Documents

Returns a new instance of Documents.

Parameters:



12
13
14
 
# File 'lib/invoance/resources/documents.rb', line 12

def initialize(http)
  @http = http
end

Instance Method Details

#anchor(document_hash:, document_ref: nil, event_type: nil, original_bytes_b64: nil, metadata: nil, trace_id: nil, idempotency_key: nil) ⇒ Hash

POST /document/anchor — Anchor a document hash.

Parameters:

  • document_hash (String) —

    hex SHA-256 (validated)

Returns:

  • (Hash) —

    AnchorDocumentResponse



20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/invoance/resources/documents.rb', line 20

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

#anchor_file(file:, is_path: true, document_ref: nil, event_type: nil, metadata: nil, trace_id: nil, idempotency_key: nil, skip_original: false) ⇒ Hash

Convenience helper — reads a file (path String or raw bytes String), computes the SHA-256 hash, base64-encodes the bytes, then anchors.

Parameters:

  • file (String) —

    a filesystem path OR raw file bytes

  • is_path (Boolean) (defaults to: true) —

    whether file is a path (default: true). When bytes are passed directly, set is_path: false.

  • skip_original (Boolean) (defaults to: false) —

    omit uploading the original bytes

Returns:

  • (Hash) —

    AnchorDocumentResponse



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/invoance/resources/documents.rb', line 40

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(event_id) ⇒ Hash

GET /document/:event_id — Retrieve a single document.

Returns:

  • (Hash) —

    DocumentEvent



80
81
82
 
# File 'lib/invoance/resources/documents.rb', line 80

def get(event_id)
  @http.get("/document/#{event_id}")
end

#get_original(event_id) ⇒ String

GET /document/:event_id/original — Download the original file.

Returns:

  • (String) —

    raw binary bytes



86
87
88
 
# File 'lib/invoance/resources/documents.rb', line 86

def get_original(event_id)
  @http.get_bytes("/document/#{event_id}/original")
end

#list(page: nil, limit: nil, date_from: nil, date_to: nil, document_ref: nil) ⇒ Hash

GET /document — Paginated document listing.

Returns:

  • (Hash) —

    ListDocumentsResponse



68
69
70
71
72
73
74
75
76
 
# File 'lib/invoance/resources/documents.rb', line 68

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

#verify(event_id, document_hash:) ⇒ Hash

POST /document/:event_id/verify — Hash verification.

Returns:

  • (Hash) —

    VerifyDocumentResponse



92
93
94
95
 
# File 'lib/invoance/resources/documents.rb', line 92

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