Class: Transloadit

Inherits:
Object
  • Object
show all
Defined in:
lib/transloadit.rb,
lib/transloadit/version.rb

Overview

Implements the Transloadit REST API in Ruby. Check the README for usage instructions.

Defined Under Namespace

Modules: Exception Classes: ApiModel, Assembly, Request, Response, Step, Template

Constant Summary collapse

VERSION = 
"3.1.0"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Transloadit

Creates a new instance of the Transloadit API.

Parameters:

  • options (Hash) (defaults to: {}) —

    a hash of options, which can be any of:

Options Hash (options):

  • :key (String) —

    your auth key from the credentials page (required)

  • :secret (String) —

    your auth secret from the credentials page, for signing requests (optional)



46
47
48
49
50
51
52
53
 
# File 'lib/transloadit.rb', line 46

def initialize(options = {})
  self.key = options[:key]
  self.secret = options[:secret]
  self.duration = options[:duration] || 5 * 60
  self.max_size = options[:max_size]

  _ensure_key_provided
end

Instance Attribute Details

#duration ⇒ Integer

Returns the duration in seconds that signed API requests generated from this instance remain valid.

Returns:

  • (Integer) —

    the duration in seconds that signed API requests generated from this instance remain valid



31
32
33
 
# File 'lib/transloadit.rb', line 31

def duration
  @duration
end

#key ⇒ String

Returns your Transloadit auth key.

Returns:

  • (String) —

    your Transloadit auth key



24
25
26
 
# File 'lib/transloadit.rb', line 24

def key
  @key
end

#max_size ⇒ Object

Returns the value of attribute max_size.



33
34
35
 
# File 'lib/transloadit.rb', line 33

def max_size
  @max_size
end

#secret ⇒ String

Returns your Transloadit auth secret, for signing requests.

Returns:

  • (String) —

    your Transloadit auth secret, for signing requests



27
28
29
 
# File 'lib/transloadit.rb', line 27

def secret
  @secret
end

Instance Method Details

#assembly(options = {}) ⇒ Object

Creates a Transloadit::Assembly ready to be sent to the REST API.

Parameters:

  • options (Hash) (defaults to: {}) —

    additional parameters to send with the assembly submission; for a full list of parameters, see the official documentation on templates.

Options Hash (options):

  • :steps (Step, Array<Step>) —

    the steps to perform in this assembly

  • :notify_url (String) —

    A URL to be POSTed when the assembly has finished processing

  • :template_id (String) —

    the ID of a template to use instead of specifying options here directly



83
84
85
 
# File 'lib/transloadit.rb', line 83

def assembly(options = {})
  Transloadit::Assembly.new(self, options)
end

#bill(month = Date.today.month, year = Date.today.year) ⇒ Object

Gets user billing reports for specified month and year. Defaults to current month or year if corresponding param is not specified.

Parameters:

  • month (Integer) (defaults to: Date.today.month) —

    the month for which billing reports should be retrieved. defaults to current month if not specified.

  • year (Integer) (defaults to: Date.today.year) —

    the year for which billing reports should be retrieved. defaults to current year if not specified.



106
107
108
109
110
111
112
 
# File 'lib/transloadit.rb', line 106

def bill(month = Date.today.month, year = Date.today.year)
  # convert month to 2 digit format
  month = format "%02d", month
  path = "bill/#{year}-#{month}"

  Transloadit::Request.new(path, secret).get({auth: to_hash})
end

#inspect ⇒ String

Returns a human-readable version of the Transloadit.

Returns:

  • (String) —

    a human-readable version of the Transloadit.



117
118
119
 
# File 'lib/transloadit.rb', line 117

def inspect
  to_hash.inspect
end

#signed_smart_cdn_url(workspace:, template:, input:, expire_at_ms: nil, url_params: {}) ⇒ String

Returns Signed Smart CDN URL.

Parameters:

  • workspace (String) —

    Workspace slug

  • template (String) —

    Template slug or template ID

  • input (String) —

    Input value that is provided as ‘$Transloadit.fieldsfields.input` in the template

  • url_params (Hash) (defaults to: {}) —

    Additional parameters for the URL query string (optional)

  • expire_at_ms (Integer) (defaults to: nil) —

    Expiration time as Unix timestamp in milliseconds (optional)

Returns:

  • (String) —

    Signed Smart CDN URL

Raises:

  • (ArgumentError) 


144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/transloadit.rb', line 144

def signed_smart_cdn_url(
  workspace:,
  template:,
  input:,
  expire_at_ms: nil,
  url_params: {}
)
  raise ArgumentError, "workspace is required" if workspace.nil? || workspace.empty?
  raise ArgumentError, "template is required" if template.nil? || template.empty?
  raise ArgumentError, "input is required" if input.nil?

  workspace_slug = CGI.escape(workspace)
  template_slug = CGI.escape(template)
  input_field = CGI.escape(input)

  expire_at = expire_at_ms || (Time.now.to_i * 1000 + 60 * 60 * 1000) # 1 hour default

  query_params = {}
  url_params.each do |key, value|
    next if value.nil?
    Array(value).each do |val|
      next if val.nil?
      (query_params[key.to_s] ||= []) << val.to_s
    end
  end

  query_params["auth_key"] = [key]
  query_params["exp"] = [expire_at.to_s]

  # Sort parameters to ensure consistent ordering
  sorted_params = query_params.sort.flat_map do |key, values|
    values.map { |v| "#{CGI.escape(key)}=#{CGI.escape(v)}" }
  end.join("&")

  string_to_sign = "#{workspace_slug}/#{template_slug}/#{input_field}?#{sorted_params}"

  signature = OpenSSL::HMAC.hexdigest("sha256", secret, string_to_sign)

  final_params = "#{sorted_params}&sig=#{CGI.escape("sha256:#{signature}")}"
  "https://#{workspace_slug}.tlcdn.com/#{template_slug}/#{input_field}?#{final_params}"
end

#step(name, robot, options = {}) ⇒ Step

Creates a Transloadit::Step describing a step in an upload assembly.

Parameters:

  • name (String) —

    the name to give the step

  • robot (String) —

    the robot to use in this step (e.g., ‘/image/resize’)

  • options (Hash) (defaults to: {}) —

    a hash of options to customize the robot’s operation; see the online documentation for robot-specific options

Returns:

  • (Step) —

    the created Step



65
66
67
 
# File 'lib/transloadit.rb', line 65

def step(name, robot, options = {})
  Transloadit::Step.new(name, robot, options)
end

#template(options = {}) ⇒ Object

Creates a Transloadit::Template instance ready to interact with its corresponding REST API.

See the Transloadit documentation for further information on Templates and available endpoints.



93
94
95
 
# File 'lib/transloadit.rb', line 93

def template(options = {})
  Transloadit::Template.new(self, options)
end

#to_hash ⇒ Hash

Returns a Transloadit-compatible Hash of the instance’s contents.

Returns:

  • (Hash) —

    a Transloadit-compatible Hash of the instance’s contents



124
125
126
127
128
129
 
# File 'lib/transloadit.rb', line 124

def to_hash
  result = {key: key}
  result.update(max_size: max_size) unless max_size.nil?
  result.update(expires: _generate_expiry) unless secret.nil?
  result
end

#to_json ⇒ String

Returns JSON-encoded String containing the object’s hash contents.

Returns:

  • (String) —

    JSON-encoded String containing the object’s hash contents



134
135
136
 
# File 'lib/transloadit.rb', line 134

def to_json
  MultiJson.dump(to_hash)
end