turbodocx-sdk 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,418 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "net/http"
4
+ require "uri"
5
+ require "json"
6
+ require "securerandom"
7
+ require "stringio"
8
+ require_relative "errors"
9
+ require_relative "response_normalizer"
10
+ require_relative "client_context"
11
+
12
+ module TurboDocxSdk
13
+ # Low-level HTTP client for the TurboDocx API.
14
+ #
15
+ # Handles authentication, error mapping, response unwrapping, and
16
+ # the response normalizer pipeline.
17
+ class HttpClient
18
+ DEFAULT_BASE_URL = "https://api.turbodocx.com"
19
+
20
+ # @param api_key [String, nil]
21
+ # @param access_token [String, nil]
22
+ # @param base_url [String, nil]
23
+ # @param org_id [String, nil]
24
+ # @param sender_email [String, nil]
25
+ # @param sender_name [String, nil]
26
+ # @param skip_sender_validation [Boolean]
27
+ # @raise [AuthenticationError] if no API key or access token is provided
28
+ # @raise [ValidationError] if senderEmail is missing and validation is not skipped
29
+ def initialize(
30
+ api_key: nil,
31
+ access_token: nil,
32
+ base_url: nil,
33
+ org_id: nil,
34
+ sender_email: nil,
35
+ sender_name: nil,
36
+ skip_sender_validation: false,
37
+ client_context: nil
38
+ )
39
+ @api_key = api_key || ENV["TURBODOCX_API_KEY"]
40
+ @access_token = access_token
41
+ @base_url = base_url || ENV["TURBODOCX_BASE_URL"] || DEFAULT_BASE_URL
42
+ @org_id = org_id || ENV["TURBODOCX_ORG_ID"]
43
+ @sender_email = sender_email || ENV["TURBODOCX_SENDER_EMAIL"]
44
+ @sender_name = sender_name || ENV["TURBODOCX_SENDER_NAME"]
45
+ # Resolved client-context headers (User-Agent, X-Timezone, ...), computed once.
46
+ @context_headers = ClientContext.resolve_headers(client_context)
47
+
48
+ unless @api_key || @access_token
49
+ raise AuthenticationError, "API key or access token is required"
50
+ end
51
+
52
+ unless @sender_email || skip_sender_validation
53
+ raise ValidationError,
54
+ "senderEmail is required. It is used as the reply-to address for signature requests " \
55
+ "and recorded as the sender in the audit trail. The API rejects sends without it."
56
+ end
57
+ end
58
+
59
+ # @return [Hash] sender email and name configuration
60
+ def sender_config
61
+ { "senderEmail" => @sender_email, "senderName" => @sender_name }
62
+ end
63
+
64
+ # GET request.
65
+ # @param path [String]
66
+ # @param params [Hash, nil] query params (values may be String or Array<String>)
67
+ # @return [Object] parsed, unwrapped, normalized response
68
+ # @raise [AuthenticationError] on 401 response
69
+ # @raise [NotFoundError] on 404 response
70
+ # @raise [RateLimitError] on 429 response
71
+ # @raise [ValidationError] on 400 response
72
+ # @raise [NetworkError] on connection failure
73
+ def get(path, params = nil)
74
+ url = build_url(path, params)
75
+ request = Net::HTTP::Get.new(url)
76
+ apply_headers(request)
77
+ execute(request, url)
78
+ end
79
+
80
+ # POST request with JSON body.
81
+ # @param path [String]
82
+ # @param data [Hash, nil] request body
83
+ # @return [Object] parsed, unwrapped, normalized response
84
+ # @raise [ValidationError] on 400 response
85
+ # @raise [AuthenticationError] on 401 response
86
+ # @raise [NotFoundError] on 404 response
87
+ # @raise [RateLimitError] on 429 response
88
+ # @raise [NetworkError] on connection failure
89
+ def post(path, data = nil)
90
+ url = build_url(path)
91
+ request = Net::HTTP::Post.new(url)
92
+ apply_headers(request)
93
+ if data
94
+ request.body = JSON.generate(data)
95
+ end
96
+ execute(request, url)
97
+ end
98
+
99
+ # PATCH request with JSON body.
100
+ # @param path [String]
101
+ # @param data [Hash, nil] request body
102
+ # @return [Object] parsed, unwrapped, normalized response
103
+ # @raise [ValidationError] on 400 response
104
+ # @raise [AuthenticationError] on 401 response
105
+ # @raise [NotFoundError] on 404 response
106
+ # @raise [RateLimitError] on 429 response
107
+ # @raise [NetworkError] on connection failure
108
+ def patch(path, data = nil)
109
+ url = build_url(path)
110
+ request = Net::HTTP::Patch.new(url)
111
+ apply_headers(request)
112
+ if data
113
+ request.body = JSON.generate(data)
114
+ end
115
+ execute(request, url)
116
+ end
117
+
118
+ # DELETE request.
119
+ # @param path [String]
120
+ # @return [Object] parsed, unwrapped, normalized response
121
+ # @raise [AuthenticationError] on 401 response
122
+ # @raise [NotFoundError] on 404 response
123
+ # @raise [RateLimitError] on 429 response
124
+ # @raise [NetworkError] on connection failure
125
+ def delete(path)
126
+ url = build_url(path)
127
+ request = Net::HTTP::Delete.new(url)
128
+ apply_headers(request)
129
+ execute(request, url)
130
+ end
131
+
132
+ # GET returning raw binary (for PDF downloads etc.).
133
+ # @param path [String]
134
+ # @param params [Hash, nil] query params
135
+ # @return [String] raw response body bytes
136
+ # @raise [AuthenticationError] on 401 response
137
+ # @raise [NotFoundError] on 404 response
138
+ # @raise [NetworkError] on connection failure
139
+ def get_raw(path, params = nil)
140
+ url = build_url(path, params)
141
+ request = Net::HTTP::Get.new(url)
142
+ apply_headers(request, content_type: false)
143
+ execute_raw(request, url)
144
+ end
145
+
146
+ # POST with multipart/form-data.
147
+ # @param path [String]
148
+ # @param form_data [Hash] keys are field names, values are strings or
149
+ # Hashes with :io, :filename, :content_type for file parts.
150
+ # @return [Object] parsed, unwrapped, normalized response
151
+ # @raise [ValidationError] on 400 response
152
+ # @raise [AuthenticationError] on 401 response
153
+ # @raise [NetworkError] on connection failure
154
+ def post_form_data(path, form_data)
155
+ request_form_data("POST", path, form_data)
156
+ end
157
+
158
+ # PATCH with multipart/form-data.
159
+ # @param path [String]
160
+ # @param form_data [Hash] keys are field names, values are strings or
161
+ # Hashes with :io, :filename, :content_type for file parts.
162
+ # @return [Object] parsed, unwrapped, normalized response
163
+ # @raise [ValidationError] on 400 response
164
+ # @raise [AuthenticationError] on 401 response
165
+ # @raise [NetworkError] on connection failure
166
+ def patch_form_data(path, form_data)
167
+ request_form_data("PATCH", path, form_data)
168
+ end
169
+
170
+ # Upload a file (used by TurboSign).
171
+ # @param api_path [String]
172
+ # @param file [String, IO] file path or IO-like object
173
+ # @param field_name [String] form field name for the file
174
+ # @param additional_data [Hash, nil] extra form fields
175
+ # @return [Object] parsed, unwrapped, normalized response
176
+ # @raise [ValidationError] if the file input type is unsupported or on 400 response
177
+ # @raise [AuthenticationError] on 401 response
178
+ # @raise [NetworkError] on connection failure
179
+ def upload_file(api_path, file, field_name: "file", additional_data: nil)
180
+ parts = {}
181
+
182
+ if file.is_a?(String)
183
+ # file path
184
+ content = File.binread(file)
185
+ mime, ext = detect_file_type(content)
186
+ parts[field_name] = { io: StringIO.new(content), filename: part_file_name(File.basename(file), ext), content_type: mime }
187
+ elsif file.respond_to?(:read)
188
+ content = file.read
189
+ mime, ext = detect_file_type(content)
190
+ # the API checks this extension; fileName is a form field
191
+ parts[field_name] = { io: StringIO.new(content), filename: "document.#{ext}", content_type: mime }
192
+ else
193
+ raise ValidationError, "Unsupported file input type: #{file.class}"
194
+ end
195
+
196
+ if additional_data
197
+ additional_data.each do |key, value|
198
+ parts[key.to_s] = value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value.to_s
199
+ end
200
+ end
201
+
202
+ post_form_data(api_path, parts)
203
+ end
204
+
205
+ private
206
+
207
+ def build_url(path, params = nil)
208
+ url_str = "#{@base_url}#{path}"
209
+ if params && !params.empty?
210
+ query_parts = []
211
+ params.each do |key, value|
212
+ if value.is_a?(Array)
213
+ value.each { |v| query_parts << "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(v)}" }
214
+ else
215
+ query_parts << "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(value)}"
216
+ end
217
+ end
218
+ url_str += "?#{query_parts.join("&")}"
219
+ end
220
+ URI.parse(url_str)
221
+ end
222
+
223
+ def apply_headers(request, content_type: true)
224
+ # Client-context headers (User-Agent, X-Timezone, Accept-Language,
225
+ # X-Forwarded-For, X-Device-Fingerprint) describe the calling environment so
226
+ # the signature audit trail records real device/location. Set them first so
227
+ # the SDK's own protocol headers below always win over caller context.
228
+ @context_headers.each { |key, value| request[key] = value }
229
+
230
+ request["Content-Type"] = "application/json" if content_type
231
+ if @access_token
232
+ request["Authorization"] = "Bearer #{@access_token}"
233
+ elsif @api_key
234
+ request["Authorization"] = "Bearer #{@api_key}"
235
+ end
236
+ request["x-rapiddocx-org-id"] = @org_id if @org_id
237
+ end
238
+
239
+ def execute(request, url)
240
+ response = http_request(request, url)
241
+ handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
242
+
243
+ content_type = response["content-type"]
244
+ if content_type && content_type.include?("application/json")
245
+ json_data = JSON.parse(response.body)
246
+ ResponseNormalizer.normalize(smart_unwrap(json_data))
247
+ else
248
+ response.body
249
+ end
250
+ rescue TurboDocxError
251
+ raise
252
+ rescue StandardError => e
253
+ raise NetworkError, "Network request failed: #{e.message}"
254
+ end
255
+
256
+ def execute_raw(request, url)
257
+ response = http_request(request, url)
258
+ handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
259
+ response.body
260
+ rescue TurboDocxError
261
+ raise
262
+ rescue StandardError => e
263
+ raise NetworkError, "Network request failed: #{e.message}"
264
+ end
265
+
266
+ def http_request(request, url)
267
+ http = Net::HTTP.new(url.host, url.port)
268
+ http.use_ssl = url.scheme == "https"
269
+ http.request(request)
270
+ end
271
+
272
+ def request_form_data(method, path, form_data)
273
+ url = build_url(path)
274
+ boundary = "----TurboDocxSdk#{SecureRandom.hex(16)}"
275
+
276
+ body = build_multipart_body(form_data, boundary)
277
+
278
+ klass = method == "PATCH" ? Net::HTTP::Patch : Net::HTTP::Post
279
+ request = klass.new(url)
280
+ # Reuse apply_headers (context + auth + org) without its JSON Content-Type,
281
+ # then set the multipart Content-Type with the boundary.
282
+ apply_headers(request, content_type: false)
283
+ request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
284
+ request.body = body
285
+
286
+ execute_multipart(request, url)
287
+ rescue TurboDocxError
288
+ raise
289
+ rescue StandardError => e
290
+ raise NetworkError, "Form data request failed: #{e.message}"
291
+ end
292
+
293
+ def build_multipart_body(form_data, boundary)
294
+ parts = []
295
+ form_data.each do |key, value|
296
+ if value.is_a?(Array)
297
+ # Multiple parts under the same field name (e.g. multiple images)
298
+ value.each { |item| append_part(parts, key, item, boundary) }
299
+ else
300
+ append_part(parts, key, value, boundary)
301
+ end
302
+ end
303
+ parts << "--#{boundary}--\r\n"
304
+ parts.join
305
+ end
306
+
307
+ def append_part(parts, key, value, boundary)
308
+ if value.is_a?(Hash) && value.key?(:io)
309
+ # File part
310
+ parts << "--#{boundary}\r\n"
311
+ parts << "Content-Disposition: form-data; name=\"#{key}\"; filename=\"#{value[:filename]}\"\r\n"
312
+ parts << "Content-Type: #{value[:content_type]}\r\n\r\n"
313
+ io = value[:io]
314
+ io.rewind if io.respond_to?(:rewind)
315
+ parts << io.read
316
+ parts << "\r\n"
317
+ else
318
+ # Text part
319
+ parts << "--#{boundary}\r\n"
320
+ parts << "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n"
321
+ parts << value.to_s
322
+ parts << "\r\n"
323
+ end
324
+ end
325
+
326
+ def execute_multipart(request, url)
327
+ response = http_request(request, url)
328
+ handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
329
+ json_data = JSON.parse(response.body)
330
+ ResponseNormalizer.normalize(smart_unwrap(json_data))
331
+ end
332
+
333
+ # Smart unwrap: if response has ONLY a "data" key, extract its value.
334
+ def smart_unwrap(data)
335
+ if data.is_a?(Hash)
336
+ keys = data.keys
337
+ if keys.length == 1 && keys[0] == "data"
338
+ return data["data"]
339
+ end
340
+ end
341
+ data
342
+ end
343
+
344
+ def handle_error_response(response)
345
+ message = "HTTP #{response.code}: #{response.message}"
346
+ api_code = nil
347
+ begin
348
+ error_data = JSON.parse(response.body)
349
+ # The API reports failures in a few shapes; read all of them so the caller always gets
350
+ # the actionable reason rather than a generic envelope.
351
+ #
352
+ # Per-field/per-row reasons live under data.errors[] (validation) or a top-level
353
+ # errors[] (bulk). These say what to fix; the envelope message does not.
354
+ details = error_data.dig("data", "errors") || error_data["errors"] || []
355
+ field_errors = details.filter_map { |d| d["message"] if d.is_a?(Hash) && d["message"] }
356
+
357
+ # `error` may be a nested object ({"message","code"} — the TurboQuote surface) rather
358
+ # than a string; using it blindly would surface the inspected Hash.
359
+ raw_error = error_data["error"]
360
+ nested_message = raw_error["message"] if raw_error.is_a?(Hash)
361
+ error_string = raw_error if raw_error.is_a?(String)
362
+
363
+ message = if field_errors.any?
364
+ field_errors.join("; ")
365
+ else
366
+ error_data["message"] || nested_message || error_string || message
367
+ end
368
+
369
+ # The specific reason code, so callers can branch on it rather than only on the HTTP
370
+ # class. It appears as `code`, `type`, nested `error.code`, or `error` as a bare string
371
+ # alongside `message` — that last only counts as a code when a separate message exists,
372
+ # since alone the string IS the message.
373
+ nested_code = raw_error["code"] if raw_error.is_a?(Hash)
374
+ api_code = error_data["code"] || error_data["type"] || nested_code ||
375
+ (error_string if error_data["message"] && error_string)
376
+ rescue StandardError
377
+ # If response is not JSON, use status text
378
+ end
379
+
380
+ code = response.code.to_i
381
+ case code
382
+ when 400 then raise ValidationError.new(message, code: api_code)
383
+ when 401 then raise AuthenticationError.new(message, code: api_code)
384
+ when 403 then raise AuthorizationError.new(message, code: api_code)
385
+ when 404 then raise NotFoundError.new(message, code: api_code)
386
+ when 409 then raise ConflictError.new(message, code: api_code)
387
+ when 429 then raise RateLimitError.new(message, code: api_code)
388
+ else raise TurboDocxError.new(message, status_code: code, code: api_code)
389
+ end
390
+ end
391
+
392
+ # Extensions the API accepts on an uploaded part (it checks the part's own name).
393
+ SUPPORTED_UPLOAD_EXTENSIONS = %w[.pdf .docx .pptx].freeze
394
+
395
+ # The caller's file name when its extension is one the API accepts, else document.<ext>.
396
+ def part_file_name(name, ext)
397
+ SUPPORTED_UPLOAD_EXTENSIONS.include?(File.extname(name).downcase) ? name : "document.#{ext}"
398
+ end
399
+
400
+ # @return [Array(String, String)] the mime type and file extension
401
+ def detect_file_type(content)
402
+ bytes = content.bytes
403
+ # PDF: %PDF
404
+ if bytes[0] == 0x25 && bytes[1] == 0x50 && bytes[2] == 0x44 && bytes[3] == 0x46
405
+ return ["application/pdf", "pdf"]
406
+ end
407
+ # ZIP-based (DOCX, PPTX): PK
408
+ if bytes[0] == 0x50 && bytes[1] == 0x4B
409
+ snippet = content[0, [content.length, 2000].min]
410
+ if snippet.include?("ppt/")
411
+ return ["application/vnd.openxmlformats-officedocument.presentationml.presentation", "pptx"]
412
+ end
413
+ return ["application/vnd.openxmlformats-officedocument.wordprocessingml.document", "docx"]
414
+ end
415
+ ["application/octet-stream", "bin"]
416
+ end
417
+ end
418
+ end
@@ -0,0 +1,89 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "set"
4
+
5
+ module TurboDocxSdk
6
+ # Normalizes MySQL type quirks in API responses.
7
+ #
8
+ # MySQL returns tinyint(1) as 0/1 and decimal columns as strings.
9
+ # This normalizer converts them to proper Ruby types so consumers
10
+ # get booleans and floats instead of integers and strings.
11
+ #
12
+ # Field names use camelCase to match the API JSON keys.
13
+ module ResponseNormalizer
14
+ BOOLEAN_FIELDS = Set.new(%w[
15
+ isActive
16
+ isDefault
17
+ showInCatalog
18
+ showInQuoteBuilder
19
+ showItemsToEndUser
20
+ syncWithProducts
21
+ isPrimaryAdmin
22
+ canManageOrgs
23
+ canManageOrgUsers
24
+ canManagePartnerUsers
25
+ canManageOrgAPIKeys
26
+ canManagePartnerAPIKeys
27
+ canUpdateEntitlements
28
+ canViewAuditLogs
29
+ hasFileDownload
30
+ hasGDrive
31
+ hasWrike
32
+ hasSalesforce
33
+ hasConnectWise
34
+ rdWatermark
35
+ hasKnowledgeBase
36
+ hasAI
37
+ hasTurboSign
38
+ hasTurboQuote
39
+ ]).freeze
40
+
41
+ DECIMAL_FIELDS = Set.new(%w[
42
+ listPrice
43
+ cost
44
+ unitPrice
45
+ discountPercent
46
+ subtotal
47
+ grandTotal
48
+ subtotalMonthly
49
+ subtotalQuarterly
50
+ subtotalAnnual
51
+ subtotalOneTime
52
+ taxAmount
53
+ taxRate
54
+ bundleDiscountPercent
55
+ totalListPrice
56
+ totalFinalPrice
57
+ totalCost
58
+ finalPrice
59
+ marginPercent
60
+ ]).freeze
61
+
62
+ # Recursively normalize a parsed JSON structure (hashes with string keys
63
+ # and arrays). Returns a new structure; does not mutate the input.
64
+ def self.normalize(data)
65
+ case data
66
+ when nil then nil
67
+ when Array then data.map { |item| normalize(item) }
68
+ when Hash
69
+ result = {}
70
+ data.each do |key, value|
71
+ str_key = key.to_s
72
+ if BOOLEAN_FIELDS.include?(str_key) && (value == 0 || value == 1)
73
+ result[str_key] = value == 1
74
+ elsif DECIMAL_FIELDS.include?(str_key) && value.is_a?(String)
75
+ parsed = Float(value) rescue nil
76
+ result[str_key] = parsed.nil? ? value : parsed
77
+ elsif value.is_a?(Hash) || value.is_a?(Array)
78
+ result[str_key] = normalize(value)
79
+ else
80
+ result[str_key] = value
81
+ end
82
+ end
83
+ result
84
+ else
85
+ data
86
+ end
87
+ end
88
+ end
89
+ end