Class: Api2Convert::Client

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

Overview

The API2Convert client — convert, compress and transform files with one call.

#convert hides the multi-step job lifecycle (create -> upload -> start -> poll -> download). For full control, use #jobs and the other resources.

Quick start:

client = Api2Convert::Client.new("YOUR_API_KEY")
client.convert("invoice.docx", "pdf").save("invoice.pdf")

Constant Summary collapse

URL_RE =

Matches a source that is a public URL (sent as a remote input) rather than a local path. Anchored and linear — ReDoS-safe against a pathological input.

%r{\Ahttps?://}i

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key = "", base_url: nil, timeout: nil, max_retries: nil, poll_interval: nil, poll_max_interval: nil, poll_timeout: nil, http_sender: nil, sleeper: nil, rng: nil) ⇒ Client

Build the client. api_key falls back to the API2CONVERT_API_KEY environment variable when empty.

Options: base_url, timeout, max_retries, poll_interval, poll_max_interval, poll_timeout. For testing, inject http_sender (an object responding to call(request)), sleeper (a proc) and rng (a proc).



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/api2convert/client.rb', line 24

def initialize(api_key = "", base_url: nil, timeout: nil, max_retries: nil,
               poll_interval: nil, poll_max_interval: nil, poll_timeout: nil,
               http_sender: nil, sleeper: nil, rng: nil)
  api_key = api_key.to_s
  api_key = ENV["API2CONVERT_API_KEY"].to_s if api_key.empty?
  if api_key.empty?
    raise ArgumentError,
          "No API key provided. Pass it to the constructor or set the " \
          "API2CONVERT_API_KEY environment variable."
  end

  config = Config.create(
    api_key,
    base_url: base_url, timeout: timeout, max_retries: max_retries,
    poll_interval: poll_interval, poll_max_interval: poll_max_interval,
    poll_timeout: poll_timeout
  )
  sender = http_sender || Http::NetHttpSender.new(timeout: config.timeout)
  @transport = Http::Transport.new(sender, config, sleeper: sleeper, rng: rng)

  uploader = Upload::FileUploader.new(@transport)
  @jobs = Resource::Jobs.new(@transport, uploader)
  @conversions = Resource::Conversions.new(@transport)
  @presets = Resource::Presets.new(@transport)
  @stats = Resource::Stats.new(@transport)
  @contracts = Resource::Contracts.new(@transport)
end

Instance Attribute Details

#contracts ⇒ Object (readonly)

Returns the value of attribute contracts.



89
90
91
 
# File 'lib/api2convert/client.rb', line 89

def contracts
  @contracts
end

#conversions ⇒ Object (readonly)

Returns the value of attribute conversions.



89
90
91
 
# File 'lib/api2convert/client.rb', line 89

def conversions
  @conversions
end

#jobs ⇒ Object (readonly)

Returns the value of attribute jobs.



89
90
91
 
# File 'lib/api2convert/client.rb', line 89

def jobs
  @jobs
end

#presets ⇒ Object (readonly)

Returns the value of attribute presets.



89
90
91
 
# File 'lib/api2convert/client.rb', line 89

def presets
  @presets
end

#stats ⇒ Object (readonly)

Returns the value of attribute stats.



89
90
91
 
# File 'lib/api2convert/client.rb', line 89

def stats
  @stats
end

Class Method Details

.webhooks ⇒ Object

Webhook verifier — usable without a configured client.



92
93
94
 
# File 'lib/api2convert/client.rb', line 92

def self.webhooks
  Webhook::Verifier.new
end

Instance Method Details

#close ⇒ Object

No persistent connection is held (the transport opens per request), so this is a no-op provided for symmetry with the sibling SDKs.



98
99
100
 
# File 'lib/api2convert/client.rb', line 98

def close
  nil
end

#convert(source, to, options = nil, category: nil, timeout: nil, output_index: nil, filename: nil, download_password: nil) ⇒ Result::ConversionResult

Convert a file and wait for the result.

Hand it a local path, a public URL, or an open IO, name the target format, and get back a result you can save. options are the target-specific conversion options (discover them via #options). A download_password is remembered and applied automatically on download.

Returns:



60
61
62
63
64
65
 
# File 'lib/api2convert/client.rb', line 60

def convert(source, to, options = nil, category: nil, timeout: nil,
            output_index: nil, filename: nil, download_password: nil)
  job = start_conversion(source, to, options, category, nil, filename, download_password)
  done = @jobs.wait(job.id, timeout)
  Result::ConversionResult.new(done, @transport, output_index.nil? ? 0 : output_index, download_password)
end

#convert_async(source, to, options = nil, callback: nil, category: nil, filename: nil, download_password: nil) ⇒ Model::Job

Start a conversion without waiting.

Pass a callback URL to be notified (sets notify_status), or poll later with client.jobs.get(job.id) / client.jobs.wait(job.id).

Returns:



73
74
75
76
 
# File 'lib/api2convert/client.rb', line 73

def convert_async(source, to, options = nil, callback: nil, category: nil,
                  filename: nil, download_password: nil)
  start_conversion(source, to, options, category, callback, filename, download_password)
end

#download(output, download_password = nil) ⇒ Object

A Result::FileDownload for an output file. A download_password is remembered and sent automatically on download (overridable per call).



80
81
82
 
# File 'lib/api2convert/client.rb', line 80

def download(output, download_password = nil)
  Result::FileDownload.new(@transport, output, download_password)
end

#inspect ⇒ Object

Redacted representation. The default #inspect would recurse into the transport and its config and dump the API key in cleartext, so it is overridden to surface only the (non-secret) base URL.



105
106
107
 
# File 'lib/api2convert/client.rb', line 105

def inspect
  "#<#{self.class.name} base_url=#{@transport.config.base_url.inspect}>"
end

#options(target, category = nil) ⇒ Object

Discover the valid options (type / enum / default / range) for a target.



85
86
87
 
# File 'lib/api2convert/client.rb', line 85

def options(target, category = nil)
  @conversions.options(target, category)
end

#to_s ⇒ Object 



109
110
111
 
# File 'lib/api2convert/client.rb', line 109

def to_s
  inspect
end