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.



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

def contracts
  @contracts
end

#conversions ⇒ Object (readonly)

Returns the value of attribute conversions.



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

def conversions
  @conversions
end

#jobs ⇒ Object (readonly)

Returns the value of attribute jobs.



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

def jobs
  @jobs
end

#presets ⇒ Object (readonly)

Returns the value of attribute presets.



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

def presets
  @presets
end

#stats ⇒ Object (readonly)

Returns the value of attribute stats.



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

def stats
  @stats
end

Class Method Details

.webhooks ⇒ Object

Webhook verifier — usable without a configured client.



102
103
104
 
# File 'lib/api2convert/client.rb', line 102

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.



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

def close
  nil
end

#convert(source, to, options = nil, category: nil, timeout: nil, output_index: nil, filename: nil, download_password: nil, output_targets: 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.

A Model::CloudInput imports the source straight from customer storage (a started job, like a remote URL). Pass output_targets (a list of Model::OutputTarget) to deliver the output(s) to customer storage instead of producing a downloadable file — the job then completes with no local output and the returned result is not downloaded (calling output/save on it would have nothing to fetch). Output targets are attached to the conversion's output_target and never merged into options.

Returns:



67
68
69
70
71
72
73
74
 
# File 'lib/api2convert/client.rb', line 67

def convert(source, to, options = nil, category: nil, timeout: nil,
            output_index: nil, filename: nil, download_password: nil,
            output_targets: nil)
  job = start_conversion(source, to, options, category, nil, filename,
                         download_password, output_targets)
  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, output_targets: 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:



82
83
84
85
86
 
# File 'lib/api2convert/client.rb', line 82

def convert_async(source, to, options = nil, callback: nil, category: nil,
                  filename: nil, download_password: nil, output_targets: nil)
  start_conversion(source, to, options, category, callback, filename,
                   download_password, output_targets)
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).



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

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.



115
116
117
 
# File 'lib/api2convert/client.rb', line 115

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.



95
96
97
 
# File 'lib/api2convert/client.rb', line 95

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

#to_s ⇒ Object 



119
120
121
 
# File 'lib/api2convert/client.rb', line 119

def to_s
  inspect
end