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.
data/README.md ADDED
@@ -0,0 +1,1462 @@
1
+ [![TurboDocx](https://raw.githubusercontent.com/TurboDocx/SDK/main/packages/js-sdk/banner.png)](https://www.turbodocx.com)
2
+
3
+ <div align="center">
4
+
5
+ # turbodocx-sdk (Ruby)
6
+
7
+ **Official Ruby SDK for TurboDocx**
8
+
9
+ The most developer-friendly **DocuSign & PandaDoc alternative** for **e-signatures** and **document generation**. Send documents for signature and automate document workflows programmatically.
10
+
11
+ [![Gem Version](https://img.shields.io/gem/v/turbodocx-sdk.svg)](https://rubygems.org/gems/turbodocx-sdk)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
13
+ [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-agentskills.io-8A2BE2)](https://agentskills.io)
14
+ [![Quickstart Skill](https://skills.sh/b/TurboDocx/quickstart)](https://github.com/TurboDocx/quickstart)
15
+
16
+ [Documentation](https://docs.turbodocx.com/docs) • [API Reference](https://docs.turbodocx.com/docs/SDKs/) • [Examples](#examples) • [Discord](https://discord.gg/NYKwz4BcpX)
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ## Skip the boilerplate — let an agent scaffold it for you
23
+
24
+ Have an AI coding agent (Claude Code, Cursor, Copilot, Codex, Gemini CLI, OpenCode) install this SDK, configure your env, write working route handlers, and wire them into your app:
25
+
26
+ ```bash
27
+ npx skills add TurboDocx/quickstart
28
+ ```
29
+
30
+ Then run `/turbodocx-sdk` inside your agent — or one of the focused shortcuts:
31
+
32
+ | Shortcut | What it scaffolds |
33
+ |---|---|
34
+ | `/turbodocx-sdk turbosign` | Send documents for e-signature, check status, download signed PDF |
35
+ | `/turbodocx-sdk deliverable` | Generate documents from templates with variable substitution |
36
+ | `/turbodocx-sdk turbopartner` | Provision and manage customer organizations (partner accounts) |
37
+ | `/turbodocx-sdk turbowebhooks` | Subscribe to `signature.document.completed` events + verify HMAC |
38
+ | `/turbodocx-sdk turboquote` | Build and send sales quotes with line items, bundles, and price books |
39
+
40
+ The skill auto-detects your framework (Rails, Sinatra, Rack, …) and follows your existing project conventions. Source: [github.com/TurboDocx/quickstart](https://github.com/TurboDocx/quickstart).
41
+
42
+ ---
43
+
44
+ ## Why TurboDocx?
45
+
46
+ A modern, developer-first alternative to legacy e-signature platforms:
47
+
48
+ | Looking for... | TurboDocx offers |
49
+ |----------------|------------------|
50
+ | DocuSign API alternative | Simple REST API, transparent pricing |
51
+ | PandaDoc alternative | Document generation + e-signatures in one SDK |
52
+ | HelloSign/Dropbox Sign alternative | Full API access, modern DX |
53
+ | Adobe Sign alternative | Quick integration, developer-friendly docs |
54
+ | SignNow alternative | Predictable costs, responsive support |
55
+ | Documint alternative | DOCX/PDF generation from templates |
56
+ | WebMerge alternative | Data-driven document automation |
57
+
58
+ **Other platforms we compare to:** SignRequest, SignEasy, Zoho Sign, Eversign, SignWell, Formstack Documents
59
+
60
+ ### TurboDocx Ecosystem
61
+
62
+ | Package | Description |
63
+ |---------|-------------|
64
+ | [@turbodocx/html-to-docx](https://github.com/turbodocx/html-to-docx) | Convert HTML to DOCX - fastest JS library |
65
+ | [@turbodocx/n8n-nodes-turbodocx](https://github.com/turbodocx/n8n-nodes-turbodocx) | n8n community nodes for TurboDocx |
66
+ | [TurboDocx Writer](https://appsource.microsoft.com/product/office/WA200007397) | Microsoft Word add-in |
67
+
68
+ ---
69
+
70
+ ## Features
71
+
72
+ - **Production-Ready** — Battle-tested, processing thousands of documents daily
73
+ - **Zero runtime dependencies** — Pure Ruby stdlib (`net/http`, `json`, `openssl`); nothing else to install
74
+ - **Idiomatic Ruby** — snake_case methods, keyword arguments, typed exception hierarchy
75
+ - **Static class pattern** — `configure` once, then call class methods; no instantiation required
76
+ - **Five modules** — TurboSign (e-signatures), Deliverable (document generation), TurboPartner (partner portal), TurboWebhooks (signature webhook), TurboQuote (CPQ)
77
+
78
+ ---
79
+
80
+ ## Installation
81
+
82
+ Add to your `Gemfile`:
83
+
84
+ ```ruby
85
+ gem "turbodocx-sdk"
86
+ ```
87
+
88
+ Then run:
89
+
90
+ ```bash
91
+ bundle install
92
+ ```
93
+
94
+ Or install directly:
95
+
96
+ ```bash
97
+ gem install turbodocx-sdk
98
+ ```
99
+
100
+ ---
101
+
102
+ ## Install via AI Agent Skill
103
+
104
+ Let an AI coding agent set up this SDK for you with the [TurboDocx Quickstart Agent Skill](https://github.com/TurboDocx/quickstart):
105
+
106
+ ```bash
107
+ npx skills add TurboDocx/quickstart
108
+ ```
109
+
110
+ Works with Claude Code, GitHub Copilot, Cursor, OpenCode, and other AI coding agents. The skill detects your language, installs the gem, and generates working integration code.
111
+
112
+ ---
113
+
114
+ ## Quick Start
115
+
116
+ ```ruby
117
+ require "turbodocx_sdk"
118
+
119
+ # 1. Configure with your API key and sender information
120
+ TurboDocxSdk::TurboSign.configure(
121
+ api_key: ENV["TURBODOCX_API_KEY"],
122
+ org_id: ENV["TURBODOCX_ORG_ID"],
123
+ sender_email: ENV["TURBODOCX_SENDER_EMAIL"], # REQUIRED
124
+ sender_name: ENV["TURBODOCX_SENDER_NAME"] # OPTIONAL
125
+ )
126
+
127
+ # 2. Send a document for signature
128
+ result = TurboDocxSdk::TurboSign.send_signature(
129
+ # Request-hash keys are camelCase — the SDK forwards the hash to the API
130
+ # as-is and does NOT convert snake_case. (Only method keyword args like
131
+ # configure(api_key:, sender_email:) are snake_case.)
132
+ fileLink: "https://example.com/contract.pdf",
133
+ documentName: "Partnership Agreement",
134
+ recipients: [
135
+ { name: "John Doe", email: "john@example.com", signingOrder: 1 }
136
+ ],
137
+ fields: [
138
+ {
139
+ type: "signature",
140
+ recipientEmail: "john@example.com",
141
+ template: { anchor: "{signature1}", placement: "replace",
142
+ size: { width: 100, height: 30 } }
143
+ }
144
+ ]
145
+ )
146
+
147
+ puts "Document ID: #{result['documentId']}"
148
+ ```
149
+
150
+ ---
151
+
152
+ ## Configuration
153
+
154
+ ```ruby
155
+ require "turbodocx_sdk"
156
+
157
+ TurboDocxSdk::TurboSign.configure(
158
+ api_key: "your-api-key", # REQUIRED
159
+ org_id: "your-org-id", # REQUIRED
160
+ sender_email: "you@company.com", # REQUIRED — reply-to for signature emails
161
+ sender_name: "Your Company" # OPTIONAL but strongly recommended
162
+ )
163
+ ```
164
+
165
+ **Important:** `sender_email` is **REQUIRED**. It is used as the reply-to address for signature request emails and recorded as the sender in the audit trail. An API key has no mailbox of its own, so the API rejects a send without it rather than mailing from an unmonitored address. `sender_name` is optional — it defaults to the name of your API key.
166
+
167
+ ### Environment Variables
168
+
169
+ ```bash
170
+ # .env
171
+ TURBODOCX_API_KEY=your-api-key
172
+ TURBODOCX_ORG_ID=your-org-id
173
+ TURBODOCX_SENDER_EMAIL=you@company.com
174
+ TURBODOCX_SENDER_NAME=Your Company Name
175
+ ```
176
+
177
+ ---
178
+
179
+ ## API Reference
180
+
181
+ ### TurboSign
182
+
183
+ #### `configure(api_key:, org_id:, sender_email:, sender_name: nil, base_url: nil)`
184
+
185
+ Configure the TurboSign module. `sender_email` is required.
186
+
187
+ #### `create_signature_review_link(request)`
188
+
189
+ Upload a document for review **without** sending signature emails. Returns a preview URL you can share manually. Accepts the same request hash as `send_signature` (`file`, `fileLink`, `deliverableId`, or `templateId` as document source).
190
+
191
+ ```ruby
192
+ result = TurboDocxSdk::TurboSign.create_signature_review_link(
193
+ fileLink: "https://example.com/contract.pdf",
194
+ recipients: [
195
+ { name: "John Doe", email: "john@example.com", signingOrder: 1 }
196
+ ],
197
+ fields: [
198
+ { type: "signature", page: 1, x: 100, y: 500, width: 200, height: 50, recipientEmail: "john@example.com" }
199
+ ],
200
+ documentName: "Service Agreement", # Optional
201
+ documentDescription: "Q4 Contract", # Optional
202
+ ccEmails: ["legal@acme.com"] # Optional
203
+ )
204
+
205
+ puts "Preview URL: #{result['previewUrl']}"
206
+ puts "Document ID: #{result['documentId']}"
207
+ ```
208
+
209
+ #### `send_signature(request)`
210
+
211
+ Upload a document and send it for signature. Recipients are emailed their signing links unless you pass `sendEmail: false`.
212
+
213
+ Pass `fileName:` alongside `file:` to name the stored file: any non-empty name up to 255 characters, with or without an extension. Without it (or with an empty one) the file keeps the uploaded part's name: `document.<ext>` for an IO, or a file path's basename when it ends in `.pdf`, `.docx` or `.pptx` (otherwise `document.<ext>`). The document's display name is `documentName` when given, otherwise the stored file name up to its first `.`.
214
+
215
+ The request hash uses **camelCase** keys (`fileLink`, `documentName`, and inner `recipients`/`fields` keys like `signingOrder`/`recipientEmail`) — the SDK forwards them to the API unchanged and does not convert snake_case. Fields bind to a recipient via `recipientEmail`.
216
+
217
+ ```ruby
218
+ result = TurboDocxSdk::TurboSign.send_signature(
219
+ fileLink: "https://example.com/contract.pdf",
220
+ recipients: [
221
+ { name: "Alice", email: "alice@example.com", signingOrder: 1 },
222
+ { name: "Bob", email: "bob@example.com", signingOrder: 2 }
223
+ ],
224
+ fields: [
225
+ { type: "signature", page: 1, x: 100, y: 500, width: 200, height: 50, recipientEmail: "alice@example.com" },
226
+ { type: "signature", page: 1, x: 100, y: 600, width: 200, height: 50, recipientEmail: "bob@example.com" }
227
+ ]
228
+ )
229
+
230
+ # The created recipients come back on the send result — each carries id, name and email.
231
+ # Signing links are emailed to them; they are not returned here.
232
+ result["recipients"].each do |r|
233
+ puts "#{r['name']} <#{r['email']}> — #{r['id']}"
234
+ end
235
+
236
+ # For signing progress afterwards, use get_recipients.
237
+ ```
238
+
239
+ The document source can also be raw bytes or a local file path (`file: File.binread("contract.pdf")` or `file: "contract.pdf"` — the file type is detected from magic bytes), a TurboDocx deliverable (`deliverableId:`), or a TurboSign template (`templateId:`).
240
+
241
+ #### Send a template set up in TurboDocx (signer roles)
242
+
243
+ Upload a PDF as a template in TurboDocx, add its signers as roles (e.g. "Client", "Countersigner"),
244
+ drag their fields onto the page and save the signature setup. Then send it by naming each
245
+ recipient's `role`. The fields saved for that role come with it, so `fields` can be left out.
246
+
247
+ ```ruby
248
+ # The role keys come from the template (also shown under "Use via API" on the template page)
249
+ setup = TurboDocxSdk::TurboSign.get_template_signature_setup("your-template-id")
250
+ setup["roles"].each { |r| puts "#{r['key']} (saved signer: #{r['hasSavedSigner']})" }
251
+ # client (saved signer: false)
252
+ # countersigner (saved signer: true)
253
+
254
+ TurboDocxSdk::TurboSign.send_signature(
255
+ templateId: "your-template-id",
256
+ recipients: [
257
+ { role: "client", name: "Jane Doe", email: "jane@client.com" }
258
+ # "countersigner" left out: the signer saved on the template is used
259
+ ]
260
+ )
261
+ ```
262
+
263
+ - Roles sign in the order saved on the template; recipients without a `role` sign after them.
264
+ - A role left out uses the template's saved signer. If it has none, the API returns a 400 naming the role.
265
+ - An unknown role raises `TurboDocxSdk::ValidationError` listing the template's roles (`e.code == "UnknownSignerRole"`).
266
+ - Any `fields` you pass are added to the template's (for example an extra witness signature).
267
+ - Roles work on PDF templates. Without roles, `send_signature` needs `fields`: a send without them gets a 400 `FieldsRequired`. A review link (`create_signature_review_link`) can be created with no fields; you place them in the preview.
268
+ - `get_template_signature_setup` throws `TurboDocxSdk::NotFoundError` (404, code `SignatureSetupNotFound`) when the template has no saved signature setup, or is not a template in your organization.
269
+ - `role` works the same way on `create_signature_review_link` and `create_embedded_signature`.
270
+
271
+ #### `send_reminder(document_id, recipient_ids = nil)`
272
+
273
+ Send a standalone reminder to whoever's turn it is to sign. It is independent of the automatic
274
+ reminder cadence — it works even when reminders are disabled or the cap is spent, does not
275
+ consume that cap, and only emails signers at the CURRENT signing order. Omit the recipient ids
276
+ to remind everyone eligible; do **not** pass an empty array, which the API rejects.
277
+
278
+ Recipients verified with `external_idv` or `override` sign only through a single-use `create_signing_url` link and are never emailed: they come back as `skipped_requires_single_use_url`. Naming only such recipients raises `TurboDocxSdk::ConflictError` (409) with code `RecipientRequiresSingleUseUrl`.
279
+
280
+ ```ruby
281
+ result = TurboDocxSdk::TurboSign.send_reminder("doc-uuid")
282
+
283
+ result["results"].each do |r|
284
+ # status is "sent", or a "skipped_*" reason (e.g. "skipped_wrong_order")
285
+ puts "#{r['recipientId']}: #{r['status']}"
286
+ end
287
+ ```
288
+
289
+ Reminders and expiration can also be scheduled when you send. `send_signature` accepts optional
290
+ `remindersEnabled` / `reminderDelay` / `reminderInterval` / `maxReminders` and `expirationEnabled`
291
+ / `expireAfter` / `expirationWarning` / `expirationWarningInterval` options — both features are
292
+ off by default, so omitting them preserves the original send behavior. These are camelCase like
293
+ every other send key, and each duration takes a `{ value:, unit: }` shape. The deadline is frozen
294
+ onto the document at send time and is then readable via `get_status(...)["expiresAt"]`.
295
+
296
+ ```ruby
297
+ TurboDocxSdk::TurboSign.send_signature(
298
+ fileLink: "https://example.com/contract.pdf",
299
+ remindersEnabled: true,
300
+ reminderDelay: { value: 3, unit: "days" },
301
+ expirationEnabled: true,
302
+ expireAfter: { value: 14, unit: "days" }
303
+ # ...recipients, fields, etc.
304
+ )
305
+ ```
306
+
307
+ #### `get_status(document_id)`
308
+
309
+ Check the document-level status. For per-recipient detail, use `get_recipients`.
310
+
311
+ ```ruby
312
+ status = TurboDocxSdk::TurboSign.get_status("doc-uuid")
313
+ puts "Status: #{status['status']}" # "under_review" | "completed" | "voided" | "expired" | ...
314
+ # "expiresAt" is the signing-window deadline (ISO 8601), or nil when expiration is off.
315
+ puts "Expires: #{status['expiresAt'] || 'never'}"
316
+ ```
317
+
318
+ #### `get_recipients(document_id)`
319
+
320
+ See who the document went to, who has signed, who you are still waiting on, and who sent it.
321
+
322
+ ```ruby
323
+ result = TurboDocxSdk::TurboSign.get_recipients("doc-uuid")
324
+
325
+ sender = result["document"]["sentBy"]
326
+ puts "Sent by #{sender['name']} <#{sender['email']}>"
327
+
328
+ summary = result["summary"]
329
+ puts "#{summary['completed']} of #{summary['total']} signed, waiting on #{summary['waitingOn']}"
330
+
331
+ result["recipients"].each do |r|
332
+ # "pending" | "viewed" | "completed" | "voided" | "expired"
333
+ puts "#{r['name']} <#{r['email']}>: #{r['effectiveStatus']}"
334
+ puts " signed #{r['signedOn']}" if r["signedOn"]
335
+ puts " emailed #{r['delivery']['totalSent']}x"
336
+ end
337
+
338
+ # Who are we chasing?
339
+ chasing = result["recipients"].select { |r| %w[pending viewed].include?(r["effectiveStatus"]) }
340
+ ```
341
+
342
+ **Two status fields, and they differ on purpose:**
343
+
344
+ | Field | Values | Use it for |
345
+ |---|---|---|
346
+ | `status` | `pending`, `viewed`, `completed` | The raw database value |
347
+ | `effectiveStatus` | `pending`, `viewed`, `completed`, `voided`, `expired` | Display |
348
+
349
+ The database has no per-recipient declined/voided/expired state, so on a voided or expired
350
+ document an unsigned signer still reads `pending` in `status`. `effectiveStatus` layers the
351
+ document's outcome on top — that's the one to show a user. A completed signature is never
352
+ revoked: someone who signed before the document was voided still reads `completed`.
353
+
354
+ `summary` counts by `effectiveStatus`, and `waitingOn` (pending + viewed) drops to zero once
355
+ the document is terminal.
356
+
357
+ **`delivery`** is that recipient's email history — `firstSentOn`, `lastSentOn`, `totalSent`,
358
+ `reminderCount`, `lastRemindedAt`, `warningCount`, `lastWarningAt`. It counts the signature
359
+ request, resends, reminders, expiry warnings and terminal notices. CC notifications are
360
+ excluded, since a CC address is not a signer.
361
+
362
+ Two `delivery` fields are easy to misread:
363
+
364
+ | Field | What it actually means |
365
+ |---|---|
366
+ | `reminderCount` | **Automatic (scheduled) reminders only** — the counter `maxReminders` caps. A manual "remind now" does **not** increment it (it must not consume the cap budget), though it does land in `totalSent`. So it can read `0` while reminder emails have genuinely been sent. |
367
+ | `lastRemindedAt` | **When the reminder cadence clock was last reset** — not necessarily when a reminder was sent. The initial signature-request send, each scheduled reminder, each manual "remind now" and each expiry warning all stamp it. A freshly-sent document therefore normally reads a non-null `lastRemindedAt` alongside `reminderCount` of `0`. |
368
+
369
+ `warningCount` and `lastWarningAt` are touched only by an expiry warning.
370
+
371
+ #### `download(document_id)`
372
+
373
+ Download the signed document as raw bytes.
374
+
375
+ ```ruby
376
+ pdf_bytes = TurboDocxSdk::TurboSign.download("doc-uuid")
377
+ File.binwrite("signed-contract.pdf", pdf_bytes)
378
+ ```
379
+
380
+ #### `void_document(document_id, reason)`
381
+
382
+ Cancel a signature request.
383
+
384
+ ```ruby
385
+ TurboDocxSdk::TurboSign.void_document("doc-uuid", "Contract terms changed")
386
+ ```
387
+
388
+ #### `resend_email(document_id, recipient_ids)`
389
+
390
+ Resend signature emails to specific recipients.
391
+
392
+ Recipients verified with `external_idv` or `override` are skipped (they sign only through a single-use `create_signing_url` link), and naming only such recipients raises `TurboDocxSdk::ConflictError` (409) with code `RecipientRequiresSingleUseUrl`.
393
+
394
+ ```ruby
395
+ TurboDocxSdk::TurboSign.resend_email("doc-uuid", ["recipient-uuid-1"])
396
+ ```
397
+
398
+ #### `get_audit_trail(document_id)`
399
+
400
+ Get the complete audit trail for a document, including all events and timestamps.
401
+
402
+ ```ruby
403
+ audit = TurboDocxSdk::TurboSign.get_audit_trail("doc-uuid")
404
+
405
+ puts "Document: #{audit['document']['name']}"
406
+
407
+ audit["auditTrail"].each do |entry|
408
+ puts "#{entry['actionType']} at #{entry['timestamp']}"
409
+ puts " By: #{entry['user']['name']} (#{entry['user']['email']})" if entry["user"]
410
+ puts " Recipient: #{entry['recipient']['name']}" if entry["recipient"]
411
+ end
412
+ ```
413
+
414
+ The audit trail includes a cryptographic hash chain for tamper-evidence verification.
415
+
416
+ ---
417
+
418
+ ### Deliverable (Document Generation)
419
+
420
+ The `Deliverable` module generates documents from TurboDocx templates with variable substitution, and manages/downloads the resulting deliverables.
421
+
422
+ #### Configuration
423
+
424
+ ```ruby
425
+ require "turbodocx_sdk"
426
+
427
+ TurboDocxSdk::Deliverable.configure(
428
+ api_key: ENV["TURBODOCX_API_KEY"], # REQUIRED (or access_token)
429
+ org_id: ENV["TURBODOCX_ORG_ID"] # REQUIRED
430
+ # base_url: "https://api.turbodocx.com" # optional
431
+ )
432
+ ```
433
+
434
+ `Deliverable` does **not** require `sender_email` — it never sends signature emails.
435
+
436
+ #### `generate_deliverable(request)`
437
+
438
+ Generate a new document from a template with variable substitution. Request-hash keys are camelCase (`templateId`).
439
+
440
+ ```ruby
441
+ result = TurboDocxSdk::Deliverable.generate_deliverable(
442
+ "templateId" => "template-uuid",
443
+ "name" => "Q3 Statement of Work",
444
+ "variables" => [
445
+ { "placeholder" => "{ClientName}", "text" => "Acme Corp" },
446
+ { "placeholder" => "{StartDate}", "text" => "2026-08-01" }
447
+ ],
448
+ "description" => "SOW for Acme", # Optional
449
+ "tags" => ["sow", "acme"] # Optional
450
+ )
451
+
452
+ deliverable = result["results"]["deliverable"]
453
+ puts "Deliverable ID: #{deliverable['id']}"
454
+ ```
455
+
456
+ #### `list_deliverables(options = nil)`
457
+
458
+ List deliverables with pagination, search, and tag filtering.
459
+
460
+ ```ruby
461
+ page = TurboDocxSdk::Deliverable.list_deliverables(limit: 25, offset: 0, query: "sow", show_tags: true)
462
+ puts "Total: #{page['totalRecords']}"
463
+ page["results"].each { |d| puts d["name"] }
464
+ ```
465
+
466
+ #### `get_deliverable_details(id, options = nil)`
467
+
468
+ Get full details of a single deliverable, including variables, fonts, and template info.
469
+
470
+ ```ruby
471
+ deliverable = TurboDocxSdk::Deliverable.get_deliverable_details("deliverable-uuid", show_tags: true)
472
+ puts deliverable["name"]
473
+ ```
474
+
475
+ #### `update_deliverable_info(id, request)`
476
+
477
+ Update a deliverable's name, description, or tags. **Note:** when `tags` is provided, all existing tags are replaced.
478
+
479
+ ```ruby
480
+ TurboDocxSdk::Deliverable.update_deliverable_info("deliverable-uuid",
481
+ "name" => "Q3 SOW (final)",
482
+ "description" => "Signed-off version"
483
+ )
484
+ ```
485
+
486
+ #### `delete_deliverable(id)`
487
+
488
+ Soft-delete a deliverable.
489
+
490
+ ```ruby
491
+ TurboDocxSdk::Deliverable.delete_deliverable("deliverable-uuid")
492
+ ```
493
+
494
+ #### `download_source_file(deliverable_id)`
495
+
496
+ Download the original source file (DOCX or PPTX) as raw bytes.
497
+
498
+ ```ruby
499
+ docx_bytes = TurboDocxSdk::Deliverable.download_source_file("deliverable-uuid")
500
+ File.binwrite("sow.docx", docx_bytes)
501
+ ```
502
+
503
+ #### `download_pdf(deliverable_id)`
504
+
505
+ Download the PDF version as raw bytes.
506
+
507
+ ```ruby
508
+ pdf_bytes = TurboDocxSdk::Deliverable.download_pdf("deliverable-uuid")
509
+ File.binwrite("sow.pdf", pdf_bytes)
510
+ ```
511
+
512
+ #### Generate, then send for signature
513
+
514
+ `Deliverable` pairs naturally with `TurboSign` — generate a document, then send it without downloading:
515
+
516
+ ```ruby
517
+ result = TurboDocxSdk::Deliverable.generate_deliverable(
518
+ "templateId" => "template-uuid",
519
+ "name" => "Consulting Agreement",
520
+ "variables" => [{ "placeholder" => "{ClientName}", "text" => "Acme Corp" }]
521
+ )
522
+
523
+ TurboDocxSdk::TurboSign.send_signature(
524
+ deliverableId: result["results"]["deliverable"]["id"],
525
+ recipients: [{ name: "John Doe", email: "john@example.com", signingOrder: 1 }],
526
+ fields: [
527
+ { type: "signature", recipientEmail: "john@example.com",
528
+ template: { anchor: "{signature1}", placement: "replace", size: { width: 100, height: 30 } } }
529
+ ]
530
+ )
531
+ ```
532
+
533
+ ---
534
+
535
+ ### TurboPartner (Partner API)
536
+
537
+ The `TurboPartner` module provides partner portal operations for managing organizations, users, API keys, and audit logs.
538
+
539
+ #### Configuration
540
+
541
+ ```ruby
542
+ require "turbodocx_sdk"
543
+
544
+ TurboDocxSdk::TurboPartner.configure(
545
+ partner_api_key: ENV["TURBODOCX_PARTNER_API_KEY"], # Must start with TDXP-
546
+ partner_id: ENV["TURBODOCX_PARTNER_ID"] # UUID format
547
+ )
548
+ ```
549
+
550
+ **Environment Variables:**
551
+
552
+ ```bash
553
+ TURBODOCX_PARTNER_API_KEY=TDXP-your-partner-api-key
554
+ TURBODOCX_PARTNER_ID=your-partner-uuid
555
+ ```
556
+
557
+ #### Organization Management
558
+
559
+ ```ruby
560
+ # Create an organization
561
+ org = TurboDocxSdk::TurboPartner.create_organization(
562
+ name: "Acme Corp",
563
+ features: { maxUsers: 50, hasTDAI: true }
564
+ )
565
+ puts "Org ID: #{org['data']['id']}"
566
+
567
+ # List organizations
568
+ orgs = TurboDocxSdk::TurboPartner.list_organizations(limit: 10, search: "acme")
569
+
570
+ # Get organization details (includes features + usage tracking)
571
+ details = TurboDocxSdk::TurboPartner.get_organization_details("org-uuid")
572
+
573
+ # Update organization
574
+ TurboDocxSdk::TurboPartner.update_organization_info("org-uuid", name: "New Name")
575
+
576
+ # Delete organization
577
+ TurboDocxSdk::TurboPartner.delete_organization("org-uuid")
578
+
579
+ # Update entitlements
580
+ TurboDocxSdk::TurboPartner.update_organization_entitlements("org-uuid",
581
+ features: { maxUsers: 100, hasTDAI: true }
582
+ )
583
+
584
+ # Read the org's TurboSign display preferences
585
+ # (returns only the partner-settable keys, with defaults applied)
586
+ prefs = TurboDocxSdk::TurboPartner.get_organization_preferences("org-uuid")["data"]["preferences"]
587
+ prefs["lockedFieldsBackground"] # => true by default
588
+
589
+ # Update them — pass only the keys you want to change; every other organization
590
+ # setting is preserved. Hash keys stay camelCase: they are the API contract, not
591
+ # Ruby names, and a snake_case key is dropped by the backend allowlist.
592
+ TurboDocxSdk::TurboPartner.update_organization_preferences("org-uuid",
593
+ "lockedFieldsBackground" => false
594
+ )
595
+ ```
596
+
597
+ **Partner-settable display preferences**
598
+
599
+ | Key | Default | Effect |
600
+ |-----|---------|--------|
601
+ | `hideSignatureOutline` | `false` | Hide the outline/label drawn around signed fields |
602
+ | `hideSignatureHash` | `false` | Hide the verification hash printed on signed fields |
603
+ | `lockedFieldsBackground` | `true` | Grey box behind locked fields (`false` = plain text) |
604
+ | `allowDownloadBeforeSigning` | `false` | When enabled, a signer can download the unsigned PDF from the signing page before they sign it (for example, to review it with their legal team). Defaults to off. |
605
+
606
+ #### Organization User Management
607
+
608
+ ```ruby
609
+ # List users
610
+ users = TurboDocxSdk::TurboPartner.list_organization_users("org-uuid")
611
+
612
+ # Add a user
613
+ TurboDocxSdk::TurboPartner.add_user_to_organization("org-uuid",
614
+ email: "user@example.com", role: "contributor"
615
+ )
616
+
617
+ # Update role
618
+ TurboDocxSdk::TurboPartner.update_organization_user_role("org-uuid", "user-uuid",
619
+ role: "admin"
620
+ )
621
+
622
+ # Remove user
623
+ TurboDocxSdk::TurboPartner.remove_user_from_organization("org-uuid", "user-uuid")
624
+
625
+ # Resend the org invitation email
626
+ TurboDocxSdk::TurboPartner.resend_organization_invitation_to_user("org-uuid", "user-uuid")
627
+ ```
628
+
629
+ #### Organization API Key Management
630
+
631
+ ```ruby
632
+ # List keys
633
+ keys = TurboDocxSdk::TurboPartner.list_organization_api_keys("org-uuid")
634
+
635
+ # Create key (full value returned only on creation)
636
+ key = TurboDocxSdk::TurboPartner.create_organization_api_key("org-uuid",
637
+ name: "Production Key", role: "admin"
638
+ )
639
+ puts "Key: #{key['data']['key']}" # TDX-... (only shown once)
640
+
641
+ # Update key
642
+ TurboDocxSdk::TurboPartner.update_organization_api_key("org-uuid", "key-uuid", name: "Renamed Key")
643
+
644
+ # Revoke key
645
+ TurboDocxSdk::TurboPartner.revoke_organization_api_key("org-uuid", "key-uuid")
646
+ ```
647
+
648
+ #### Partner API Keys & Partner Portal Users
649
+
650
+ ```ruby
651
+ # Create a scoped partner API key (full key value returned only on creation)
652
+ key = TurboDocxSdk::TurboPartner.create_partner_api_key(
653
+ name: "Read-Only Key",
654
+ scopes: ["org:read", "audit:read"]
655
+ )
656
+
657
+ # List / update / revoke partner API keys
658
+ TurboDocxSdk::TurboPartner.list_partner_api_keys(limit: 10)
659
+ TurboDocxSdk::TurboPartner.update_partner_api_key("key-uuid", name: "Renamed")
660
+ TurboDocxSdk::TurboPartner.revoke_partner_api_key("key-uuid")
661
+
662
+ # Add a user to the partner portal.
663
+ # `permissions` is all-or-nothing: every one of the seven keys must be present.
664
+ # A partial permissions hash is rejected with a 400.
665
+ TurboDocxSdk::TurboPartner.add_user_to_partner_portal(
666
+ email: "ops@company.com",
667
+ role: "member", # partner roles: "admin" | "member" | "viewer"
668
+ permissions: {
669
+ canManageOrgs: true,
670
+ canManageOrgUsers: true,
671
+ canManagePartnerUsers: false,
672
+ canManageOrgAPIKeys: false,
673
+ canManagePartnerAPIKeys: false,
674
+ canUpdateEntitlements: false,
675
+ canViewAuditLogs: true
676
+ }
677
+ )
678
+
679
+ # List / update / remove / re-invite partner portal users
680
+ TurboDocxSdk::TurboPartner.list_partner_portal_users(search: "ops")
681
+
682
+ # The `permissions` object is optional on update — but if you send it, send all
683
+ # seven keys. There is no partial permissions update.
684
+ TurboDocxSdk::TurboPartner.update_partner_user_permissions("user-uuid",
685
+ permissions: {
686
+ canManageOrgs: false,
687
+ canManageOrgUsers: true,
688
+ canManagePartnerUsers: false,
689
+ canManageOrgAPIKeys: false,
690
+ canManagePartnerAPIKeys: false,
691
+ canUpdateEntitlements: false,
692
+ canViewAuditLogs: true
693
+ }
694
+ )
695
+ TurboDocxSdk::TurboPartner.remove_user_from_partner_portal("user-uuid")
696
+ TurboDocxSdk::TurboPartner.resend_partner_portal_invitation_to_user("user-uuid")
697
+ ```
698
+
699
+ **Partner permissions** — all seven keys are required whenever `permissions` is sent (booleans):
700
+
701
+ | Key | Grants |
702
+ |:----|:-------|
703
+ | `canManageOrgs` | Create / update / delete organizations |
704
+ | `canManageOrgUsers` | Manage users inside organizations |
705
+ | `canManagePartnerUsers` | Manage partner portal users |
706
+ | `canManageOrgAPIKeys` | Manage organization API keys |
707
+ | `canManagePartnerAPIKeys` | Manage partner API keys |
708
+ | `canUpdateEntitlements` | Update organization entitlements |
709
+ | `canViewAuditLogs` | Read the partner audit log |
710
+
711
+ **Role enums are different for orgs and partners** — do not mix them:
712
+
713
+ | Scope | Valid roles |
714
+ |:------|:------------|
715
+ | Org users, org API keys | `admin`, `contributor`, `user`, `viewer` |
716
+ | Partner portal users | `admin`, `member`, `viewer` |
717
+
718
+ #### Audit Logs
719
+
720
+ ```ruby
721
+ logs = TurboDocxSdk::TurboPartner.get_partner_audit_logs(
722
+ action: "org.created",
723
+ startDate: "2025-01-01",
724
+ endDate: "2025-12-31",
725
+ limit: 100
726
+ )
727
+
728
+ logs["data"]["results"].each do |entry|
729
+ puts "#{entry['action']} - #{entry['createdOn']}"
730
+ end
731
+ ```
732
+
733
+ #### All 25 Methods
734
+
735
+ | Category | Methods |
736
+ |:---------|:--------|
737
+ | **Organizations** | `create_organization`, `list_organizations`, `get_organization_details`, `update_organization_info`, `delete_organization`, `update_organization_entitlements` |
738
+ | **Org display preferences** | `get_organization_preferences`, `update_organization_preferences` |
739
+ | **Org Users** | `add_user_to_organization`, `list_organization_users`, `update_organization_user_role`, `remove_user_from_organization`, `resend_organization_invitation_to_user` |
740
+ | **Org API Keys** | `create_organization_api_key`, `list_organization_api_keys`, `update_organization_api_key`, `revoke_organization_api_key` |
741
+ | **Partner API Keys** | `create_partner_api_key`, `list_partner_api_keys`, `update_partner_api_key`, `revoke_partner_api_key` |
742
+ | **Partner Users** | `add_user_to_partner_portal`, `list_partner_portal_users`, `update_partner_user_permissions`, `remove_user_from_partner_portal`, `resend_partner_portal_invitation_to_user` |
743
+ | **Audit Logs** | `get_partner_audit_logs` |
744
+
745
+ ---
746
+
747
+ ### TurboWebhooks (Signature Webhook)
748
+
749
+ The `TurboWebhooks` module manages your organization's **signature webhook** — a single subscription to TurboDocx signature events. It also pairs with the `TurboDocxSdk.verify_webhook_signature` helper for incoming webhook receivers.
750
+
751
+ > **One webhook per org.** The SDK manages a single fixed-name webhook (`signature`) per org so SDK-managed and UI-managed webhooks stay in sync — what you create here also appears in the dashboard's Signature Webhooks settings page. To manage multiple webhooks per org, call the REST API directly.
752
+ >
753
+ > **Requires administrator role.** All webhook routes require an admin TDX- API key.
754
+
755
+ #### The 7 signature events
756
+
757
+ Use the `TurboDocxSdk::WebhookEvent` constants instead of hand-writing the wire strings — a typo becomes a `NameError` rather than a webhook that silently never fires.
758
+
759
+ | Event | Constant | Fires when |
760
+ |---|---|---|
761
+ | `signature.document.sent` | `WebhookEvent::SENT` | The document is dispatched to recipients |
762
+ | `signature.document.viewed` | `WebhookEvent::VIEWED` | A recipient opens the document for the first time |
763
+ | `signature.document.recipient_signed` | `WebhookEvent::RECIPIENT_SIGNED` | Any individual signer completes their signature — fires **once per signer**, and carries `is_final_signer` + `remaining_signers` |
764
+ | `signature.document.signed` | `WebhookEvent::SIGNED` | A signer signs but the document is **not yet complete** (document-level partial progress) |
765
+ | `signature.document.completed` | `WebhookEvent::COMPLETED` | All recipients have signed and the signed PDF is finalized |
766
+ | `signature.document.finalization_failed` | `WebhookEvent::FINALIZATION_FAILED` | The signed PDF fails to finalize (e.g. a KMS signing error); the document is **not** completed |
767
+ | `signature.document.voided` | `WebhookEvent::VOIDED` | The document is voided or cancelled |
768
+
769
+ On every signature, `recipient_signed` fires first, then **exactly one** document-level event:
770
+
771
+ ```
772
+ Recipient signs
773
+ │
774
+ ├─ signature.document.recipient_signed (always — one per signer)
775
+ │
776
+ └─ more signers remaining?
777
+ ├─ yes → signature.document.signed (partial progress)
778
+ └─ no → signature.document.completed (finalized OK)
779
+ or signature.document.finalization_failed (finalization failed)
780
+ ```
781
+
782
+ > **`signed` never fires on the final signature.** To detect "the whole document is done", subscribe to `completed` (or to `recipient_signed` and check `is_final_signer: true`) — **not** `signed`.
783
+ >
784
+ > **A single-signer document never emits `signed` at all.** It emits `recipient_signed` (with `is_final_signer: true`), then `completed`.
785
+
786
+ `TurboDocxSdk::WebhookEvent::ALL` is a frozen array of all 7 wire strings if you want to subscribe to everything. `events:` stays an array of plain strings, so the backend can add events without a gem release.
787
+
788
+ #### Configuration
789
+
790
+ ```ruby
791
+ require "turbodocx_sdk"
792
+
793
+ TurboDocxSdk::TurboWebhooks.configure(
794
+ api_key: ENV["TURBODOCX_API_KEY"],
795
+ org_id: ENV["TURBODOCX_ORG_ID"]
796
+ # base_url: "https://api.turbodocx.com" # optional
797
+ )
798
+ ```
799
+
800
+ Unlike `TurboSign`, `TurboWebhooks` does NOT require `sender_email` — webhook routes don't send signature emails.
801
+
802
+ #### Create the signature webhook (save the secret immediately)
803
+
804
+ ```ruby
805
+ Events = TurboDocxSdk::WebhookEvent
806
+
807
+ created = TurboDocxSdk::TurboWebhooks.create_webhook(
808
+ urls: ["https://your-server.example.com/webhooks/turbodocx"], # HTTPS only, 1-10 urls
809
+ events: [
810
+ Events::SENT,
811
+ Events::VIEWED,
812
+ Events::RECIPIENT_SIGNED,
813
+ Events::COMPLETED,
814
+ Events::VOIDED
815
+ ]
816
+ # ...or subscribe to everything: events: TurboDocxSdk::WebhookEvent::ALL
817
+ )
818
+
819
+ # `secret` is shown ONCE here. Store it securely; it cannot be retrieved later.
820
+ puts "Save this secret: #{created['secret']}"
821
+ ```
822
+
823
+ If the signature webhook already exists, `create_webhook` raises `TurboDocxSdk::ConflictError` (409). Either update the existing one with `update_webhook` or `delete_webhook` first.
824
+
825
+ #### Get, update, delete
826
+
827
+ ```ruby
828
+ webhook = TurboDocxSdk::TurboWebhooks.get_webhook
829
+ # webhook["deliveryStats"] and webhook["availableEvents"] are included
830
+
831
+ # Only the keywords you pass are sent; the rest are left untouched.
832
+ TurboDocxSdk::TurboWebhooks.update_webhook(is_active: false)
833
+ TurboDocxSdk::TurboWebhooks.update_webhook(
834
+ urls: ["https://new-endpoint.example.com/webhooks/turbodocx"],
835
+ events: ["signature.document.completed"]
836
+ )
837
+ TurboDocxSdk::TurboWebhooks.delete_webhook
838
+ ```
839
+
840
+ > **`urls` and `events` can never be empty.** They stay `min(1)` on the backend even on update, so `urls: []` is a 400, not a "clear this field" instruction — and there is no way to remove every URL from a webhook. `update_webhook` raises `TurboDocxSdk::ValidationError` before hitting the wire if you pass an empty or `nil` array. To leave a field unchanged, just omit the keyword. `urls` accepts **1-10** entries.
841
+
842
+ #### Test deliveries and replay
843
+
844
+ ```ruby
845
+ tested = TurboDocxSdk::TurboWebhooks.test_webhook(
846
+ event_type: "signature.document.completed",
847
+ payload: { "documentId" => "doc-xyz", "status" => "completed" }
848
+ )
849
+ puts tested["summary"] # { "total" => ..., "successful" => ..., "failed" => ... }
850
+
851
+ deliveries = TurboDocxSdk::TurboWebhooks.list_webhook_deliveries(limit: 10)
852
+ replayed = TurboDocxSdk::TurboWebhooks.replay_webhook_delivery(deliveries["results"][0]["id"])
853
+ ```
854
+
855
+ `list_webhook_deliveries` accepts `limit:`, `offset:`, `event_type:`, `is_delivered:`, and `http_status:` filters. `notify_webhook(event_type:, payload:)` is also available and currently behaves identically to `test_webhook` — prefer `test_webhook` in new code.
856
+
857
+ #### Rotate the secret
858
+
859
+ ```ruby
860
+ rotated = TurboDocxSdk::TurboWebhooks.regenerate_webhook_secret
861
+ # rotated["secret"] is the new secret. Old signatures will fail immediately.
862
+ ```
863
+
864
+ #### Aggregate stats
865
+
866
+ ```ruby
867
+ stats = TurboDocxSdk::TurboWebhooks.get_webhook_stats(days: 30)
868
+ puts stats["summary"]["successRate"]
869
+ puts stats["eventBreakdown"]
870
+ ```
871
+
872
+ #### Verify incoming webhook signatures
873
+
874
+ Webhook deliveries from TurboDocx are signed with HMAC-SHA256 over `"#{timestamp}.#{raw_body}"` using your webhook secret. Use the free module function `TurboDocxSdk.verify_webhook_signature` in your receiver:
875
+
876
+ ```ruby
877
+ # In your Rack/Rails webhook handler:
878
+ # CRITICAL: read the RAW body bytes. Do NOT parse-then-reserialize JSON first —
879
+ # the signature is over the exact bytes; re-serialization breaks verification.
880
+ raw_body = request.body.read
881
+ signature = request.get_header("HTTP_X_TURBODOCX_SIGNATURE") || ""
882
+ timestamp = request.get_header("HTTP_X_TURBODOCX_TIMESTAMP") || ""
883
+ secret = ENV["TURBODOCX_WEBHOOK_SECRET"]
884
+
885
+ unless TurboDocxSdk.verify_webhook_signature(
886
+ payload: raw_body,
887
+ signature_header: signature,
888
+ timestamp_header: timestamp,
889
+ secret: secret
890
+ )
891
+ return [401, {}, ["invalid signature"]]
892
+ end
893
+
894
+ event = JSON.parse(raw_body)
895
+ # ... process event ...
896
+ [200, {}, ["ok"]]
897
+ ```
898
+
899
+ By default the helper enforces a 300-second timestamp tolerance to prevent replay attacks. Override with `tolerance_seconds: N` (`0` disables the check — not recommended in production; a negative value, NaN, `Infinity` or a non-number such as `"300"` fails closed and rejects every delivery). The `X-TurboDocx-Timestamp` header must be digits only. Comparison uses constant-time equality.
900
+
901
+ #### All Methods
902
+
903
+ | Category | Methods |
904
+ |:---------|:--------|
905
+ | **Configuration** | `configure` |
906
+ | **Webhook CRUD** | `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook` |
907
+ | **Testing** | `test_webhook`, `notify_webhook` |
908
+ | **Secret** | `regenerate_webhook_secret` |
909
+ | **Deliveries** | `list_webhook_deliveries`, `replay_webhook_delivery`, `get_webhook_stats` |
910
+ | **Receiver helper** | `TurboDocxSdk.verify_webhook_signature` (free module function — no API key needed) |
911
+
912
+ ---
913
+
914
+ ### TurboQuote (CPQ — Configure, Price, Quote)
915
+
916
+ The `TurboQuote` module provides end-to-end sales quoting: manage your product catalog (products, bundles, price books), companies and contacts, and assemble/send quotes with line items.
917
+
918
+ #### Configuration
919
+
920
+ ```ruby
921
+ require "turbodocx_sdk"
922
+
923
+ TurboDocxSdk::TurboQuote.configure(
924
+ api_key: ENV["TURBODOCX_API_KEY"], # REQUIRED (or access_token)
925
+ org_id: ENV["TURBODOCX_ORG_ID"] # REQUIRED
926
+ # base_url: "https://api.turbodocx.com" # optional
927
+ )
928
+ ```
929
+
930
+ `TurboQuote` does **not** require `sender_email` — use `api_key` + `org_id` only.
931
+
932
+ #### All 68 Methods
933
+
934
+ | Group | Methods |
935
+ |---|---|
936
+ | **Configuration** | `configure` |
937
+ | **Quotes** | `create_quote`, `get_quote`, `list_quotes`, `update_quote`, `delete_quote`, `duplicate_quote` |
938
+ | **Quote status transitions** | `send_quote`, `decline_quote`, `void_quote`, `handle_expired_quote` |
939
+ | **Quote extras** | `send_quote_with_deliverable`, `apply_price_book`, `remove_price_book`, `download_quote_pdf` |
940
+ | **Line items** | `add_line_items`, `add_bundle_line_items`, `list_line_items`, `update_line_item`, `remove_line_item` |
941
+ | **Products** | `create_product`, `bulk_create_products`, `get_product`, `list_products`, `update_product`, `delete_product`, `duplicate_product`, `get_product_primary_images` |
942
+ | **Bundles** | `create_bundle`, `bulk_create_bundles`, `get_bundle`, `list_bundles`, `update_bundle`, `delete_bundle`, `duplicate_bundle` |
943
+ | **Price books** | `create_price_book`, `bulk_create_price_books`, `get_price_book`, `list_price_books`, `update_price_book`, `delete_price_book`, `duplicate_price_book`, `list_price_book_products` |
944
+ | **Quote templates** | `get_template`, `get_template_by_id`, `list_templates`, `create_template`, `update_template`, `delete_template` |
945
+ | **Types / categories** | `create_type`, `bulk_create_types`, `list_types`, `update_type`, `delete_type` |
946
+ | **Companies** | `create_company`, `bulk_create_companies`, `get_company`, `list_companies`, `update_company`, `delete_company`, `list_company_contacts` |
947
+ | **Contacts** | `create_contact`, `bulk_create_contacts`, `list_contacts`, `update_contact`, `delete_contact` |
948
+ | **Quote number config (admin)** | `get_quote_number_config`, `update_quote_number_config` |
949
+ | **Convenience** | `create_and_send` |
950
+
951
+ #### Create a quote, add line items, and send
952
+
953
+ ```ruby
954
+ require "turbodocx_sdk"
955
+
956
+ TurboDocxSdk::TurboQuote.configure(
957
+ api_key: ENV["TURBODOCX_API_KEY"],
958
+ org_id: ENV["TURBODOCX_ORG_ID"]
959
+ )
960
+
961
+ # 1. Create the quote
962
+ quote = TurboDocxSdk::TurboQuote.create_quote(
963
+ "name" => "Professional Services Q3 2026",
964
+ "companyId" => "company-uuid",
965
+ "contactId" => "contact-uuid",
966
+ "currency" => "USD",
967
+ "termDays" => 90, # optional; defaults to 60, max 3650
968
+ "validUntil" => "2026-09-30"
969
+ )
970
+ puts "Quote number: #{quote['quoteNumber']}"
971
+
972
+ # 2. Add a product line item with a percent discount
973
+ # (single hash is auto-wrapped into an array; 1-50 items per call)
974
+ # productId, productName, unitPrice and billingFrequency are all REQUIRED.
975
+ # productId may be nil for an ad-hoc item, but the key must be present.
976
+ items = TurboDocxSdk::TurboQuote.add_line_items(quote["id"],
977
+ "productId" => "product-uuid",
978
+ "productName" => "Consulting Service",
979
+ "unitPrice" => 500,
980
+ "billingFrequency" => TurboDocxSdk::BillingFrequency::MONTHLY,
981
+ "quantity" => 3,
982
+ "discountType" => TurboDocxSdk::DiscountType::PERCENT,
983
+ "discountPercent" => 10
984
+ )
985
+ puts "Line item ID: #{items[0]['id']}"
986
+
987
+ # 3. Send the quote
988
+ sent = TurboDocxSdk::TurboQuote.send_quote(quote["id"])
989
+ puts sent["message"]
990
+ ```
991
+
992
+ #### Scheduling reminders and expiration on send
993
+
994
+ `send_quote` and `send_quote_with_deliverable` accept the same eight optional
995
+ reminder/expiration keys as `send_signature` — `remindersEnabled` / `reminderDelay` /
996
+ `reminderInterval` / `maxReminders` and `expirationEnabled` / `expireAfter` /
997
+ `expirationWarning` / `expirationWarningInterval`. They're camelCase like every other send key,
998
+ each duration takes a `{ value:, unit: }` shape, and they ride flat on the JSON body alongside
999
+ `ccEmails` / `validUntil`. Both features are off by default, so omitting them preserves the
1000
+ original send behavior.
1001
+
1002
+ **Quote expiry is pinned to `validUntil`.** When expiration is on, `expireAfter` is ignored —
1003
+ the quote already carries its own deadline — though `expirationEnabled` still toggles the
1004
+ feature. The reminder and expiration-warning cadence applies (layered over your org defaults)
1005
+ and must fit within `validUntil`, or the send is rejected.
1006
+
1007
+ ```ruby
1008
+ TurboDocxSdk::TurboQuote.send_quote(quote["id"],
1009
+ "ccEmails" => ["legal@acme.com"],
1010
+ "validUntil" => "2026-09-30",
1011
+ "remindersEnabled" => true,
1012
+ "reminderDelay" => { "value" => 2, "unit" => "days" },
1013
+ "reminderInterval" => { "value" => 3, "unit" => "days" },
1014
+ "maxReminders" => 4,
1015
+ "expirationEnabled" => true,
1016
+ "expirationWarning" => { "value" => 2, "unit" => "days" }
1017
+ )
1018
+ ```
1019
+
1020
+ #### Sender identity — "Prepared by"
1021
+
1022
+ The quote's **"Prepared by"** name and email are resolved by the server, not by whoever
1023
+ downloads or sends the quote. Precedence: the org **quote template's** sender fields first,
1024
+ then the quote's **creator**.
1025
+
1026
+ A quote created with an **API key** has no mailbox of its own — so its sender email can only
1027
+ come from the quote template. **If your org's quote template has no sender email set,
1028
+ `create_quote` (and `duplicate_quote`) raise `ValidationError` (`400 SenderEmailRequired`)** for
1029
+ an API-key caller. Set a sender email on the template once (via `update_template`) and every
1030
+ subsequent create/duplicate/send resolves cleanly. Human (JWT) callers are never blocked — their
1031
+ own email is the fallback.
1032
+
1033
+ `get_quote` returns the resolved identity under `"preparedBy"` — **prefer it over `"creator"`**
1034
+ for any customer-facing display (`"creator"` may be the internal API service account). The
1035
+ `"email"` key may be absent for an API-created quote:
1036
+
1037
+ ```ruby
1038
+ quote = TurboDocxSdk::TurboQuote.get_quote(quote_id)
1039
+ prepared = quote["preparedBy"] || {}
1040
+ puts prepared["name"] # e.g. "Acme Billing Integration" or the template sender
1041
+ puts prepared["email"] # may be nil — render a placeholder
1042
+ ```
1043
+
1044
+ #### Quote terms and auto-renewal
1045
+
1046
+ `termDays` defaults to **60** and accepts up to **3650** (10 years). The special value **`-1`** means auto-renewal, and it is the only case where `renewalPeriod` is allowed — in fact it is then **required**:
1047
+
1048
+ ```ruby
1049
+ # Auto-renewing quote: termDays == -1 REQUIRES renewalPeriod
1050
+ TurboDocxSdk::TurboQuote.create_quote(
1051
+ "name" => "Managed Services (auto-renew)",
1052
+ "companyId" => "company-uuid",
1053
+ "contactId" => "contact-uuid",
1054
+ "termDays" => -1,
1055
+ "renewalPeriod" => TurboDocxSdk::RenewalPeriod::MONTHLY # weekly | monthly | quarterly | annually
1056
+ )
1057
+ ```
1058
+
1059
+ For any other `termDays`, `renewalPeriod` must be omitted (or `nil`) — sending it is a 400.
1060
+
1061
+ #### Handling an expired quote
1062
+
1063
+ `handle_expired_quote` voids or declines an expired **sent** quote and creates a duplicate carrying the new validity date. All three keys are required, and `action` accepts **only** `"void"` or `"decline"`:
1064
+
1065
+ ```ruby
1066
+ replacement = TurboDocxSdk::TurboQuote.handle_expired_quote(quote["id"],
1067
+ "action" => "void", # "void" or "decline" — nothing else is accepted
1068
+ "reason" => "Pricing refreshed for Q4", # REQUIRED, max 190 chars
1069
+ "newValidUntil" => "2026-12-31" # REQUIRED, ISO 8601
1070
+ )
1071
+ puts replacement["quoteNumber"] # the new duplicate quote
1072
+ ```
1073
+
1074
+ #### Download a quote as PDF
1075
+
1076
+ ```ruby
1077
+ pdf_bytes = TurboDocxSdk::TurboQuote.download_quote_pdf(quote["id"])
1078
+ File.binwrite("quote.pdf", pdf_bytes)
1079
+ ```
1080
+
1081
+ #### Create and send in one call
1082
+
1083
+ ```ruby
1084
+ result = TurboDocxSdk::TurboQuote.create_and_send(
1085
+ "name" => "Enterprise License",
1086
+ "companyId" => "company-uuid",
1087
+ "contactId" => "contact-uuid",
1088
+ "items" => [
1089
+ { "productId" => "product-uuid", "productName" => "Platform License",
1090
+ "unitPrice" => 1200, "quantity" => 5, "billingFrequency" => "annual" }
1091
+ ]
1092
+ # "bundleItems" => [...], # optional bundle line items
1093
+ # "send" => {...} # optional send options
1094
+ )
1095
+ puts result["quote"]["status"] # "sent"
1096
+ ```
1097
+
1098
+ #### Bulk create (CSV-style imports)
1099
+
1100
+ Six catalog resources support bulk creation: `bulk_create_products`, `bulk_create_bundles`, `bulk_create_price_books`, `bulk_create_companies`, `bulk_create_contacts`, and `bulk_create_types`. Each takes an **array of row hashes** (same field shapes as the corresponding single `create_*` method); the SDK wraps them in the `{ "rows" => [...] }` envelope the API expects.
1101
+
1102
+ ```ruby
1103
+ # Every product row requires name, categoryId, listPrice and billingFrequency.
1104
+ # `categoryId` is a TurboQuote type UUID — there is no `categoryName` shorthand;
1105
+ # resolve or create the category first (`list_types` / `create_type`) and pass its ID.
1106
+ category = TurboDocxSdk::TurboQuote.create_type(
1107
+ "name" => "Plans",
1108
+ "categoryType" => TurboDocxSdk::CategoryType::PRODUCT_CATEGORY
1109
+ )
1110
+
1111
+ report = TurboDocxSdk::TurboQuote.bulk_create_products([
1112
+ { "name" => "Basic Plan", "categoryId" => category["id"], "listPrice" => 10, "billingFrequency" => "monthly" },
1113
+ { "name" => "Premium Plan", "categoryId" => category["id"], "listPrice" => 100, "billingFrequency" => "monthly" }
1114
+ ])
1115
+
1116
+ puts "Imported: #{report['imported']}"
1117
+
1118
+ report["failed"].each do |f|
1119
+ puts "Row #{f['row']} failed: #{f['reason']}" # "row" is 1-indexed
1120
+ end
1121
+
1122
+ report["adjusted"].each do |a|
1123
+ puts "Row #{a['row']} adjusted: #{a['reason']}" # server tweaked the row (e.g. defaults)
1124
+ end
1125
+ ```
1126
+
1127
+ Bulk-create semantics:
1128
+
1129
+ - **Partial success** — a failed row does NOT raise and does NOT roll back earlier rows; it is reported in `"failed"` with a 1-indexed `"row"` and a `"reason"`. Server-adjusted rows appear in `"adjusted"`.
1130
+ - **500-row cap** per request — the API returns a 400 (`ValidationError`) above the cap. The SDK does not validate rows or the cap client-side.
1131
+ - **Roles** — available to administrator and contributor API keys.
1132
+
1133
+ #### Quote number configuration (admin only)
1134
+
1135
+ Read and update the org-wide quote-number format. Both methods return `{ "format" => {...}, "currentFloor" => Integer }`.
1136
+
1137
+ ```ruby
1138
+ config = TurboDocxSdk::TurboQuote.get_quote_number_config
1139
+ puts config["format"]["prefix"]
1140
+ puts config["currentFloor"]
1141
+
1142
+ # update_quote_number_config takes the FULL format hash — all keys required, camelCase
1143
+ updated = TurboDocxSdk::TurboQuote.update_quote_number_config(
1144
+ "prefix" => "Q",
1145
+ "yearToken" => TurboDocxSdk::QuoteNumberYearToken::FOUR, # "none" | "two" | "four"
1146
+ "monthToken" => TurboDocxSdk::QuoteNumberMonthToken::TWO, # "off" | "two"
1147
+ "separator" => "-",
1148
+ "padWidth" => 4, # 0-12
1149
+ "suffix" => "",
1150
+ "startNumber" => 1, # >= 0
1151
+ "resetCadence" => TurboDocxSdk::QuoteNumberResetCadence::YEARLY # "never" | "yearly" | "monthly"
1152
+ )
1153
+ ```
1154
+
1155
+ Non-admin callers receive `TurboDocxSdk::AuthorizationError`.
1156
+
1157
+ ---
1158
+
1159
+ ## Field Types
1160
+
1161
+ | Type | Description |
1162
+ |:-----|:------------|
1163
+ | `signature` | Signature field (draw or type) |
1164
+ | `initial` | Initials field |
1165
+ | `text` | Free-form text input |
1166
+ | `date` | Date stamp |
1167
+ | `checkbox` | Checkbox / agreement |
1168
+ | `full_name` | Full name |
1169
+ | `first_name` | First name |
1170
+ | `last_name` | Last name |
1171
+ | `email` | Email address |
1172
+ | `title` | Job title |
1173
+ | `company` | Company name |
1174
+
1175
+ The `checkbox` type doubles as the **controlling** field for conditional logic (see below).
1176
+
1177
+ ### Conditional (IF/THEN) Fields
1178
+
1179
+ Any field hash may carry an optional `"metadata"` key that drives conditional logic. Set
1180
+ `metadata.fieldKey` on a **controlling** `checkbox` to give it a stable id, then set
1181
+ `metadata.conditional` on a **dependent** field that references that id. Field hashes are passed
1182
+ through verbatim, so the keys stay **camelCase**:
1183
+
1184
+ ```ruby
1185
+ "fields" => [
1186
+ # Controlling checkbox — carries the fieldKey dependents reference
1187
+ {
1188
+ "type" => "checkbox",
1189
+ "recipientEmail" => "john@example.com",
1190
+ "template" => { "anchor" => "{request_changes}", "placement" => "replace", "size" => { "width" => 20, "height" => 20 } },
1191
+ "metadata" => { "fieldKey" => "request_changes" }
1192
+ },
1193
+ # Dependent text field — hidden until the checkbox is checked ("If checked, explain")
1194
+ {
1195
+ "type" => "text",
1196
+ "recipientEmail" => "john@example.com",
1197
+ "isMultiline" => true,
1198
+ "template" => { "anchor" => "{change_details}", "placement" => "replace", "size" => { "width" => 200, "height" => 50 } },
1199
+ "metadata" => {
1200
+ "conditional" => {
1201
+ "controllingFieldKey" => "request_changes", # must equal the checkbox's fieldKey
1202
+ "operator" => "is_checked", # "is_checked" | "is_not_checked"
1203
+ "action" => "show" # "show" (hidden until met) | "unlock" (read-only until met)
1204
+ }
1205
+ }
1206
+ }
1207
+ ]
1208
+ ```
1209
+
1210
+ | `metadata` key | Set on | Meaning |
1211
+ |:---------------|:-------|:--------|
1212
+ | `fieldKey` | controlling `checkbox` | Stable client id (≤100 chars) that dependents reference |
1213
+ | `conditional.controllingFieldKey` | dependent field | Must equal the controlling checkbox's `fieldKey` |
1214
+ | `conditional.operator` | dependent field | `"is_checked"` or `"is_not_checked"` |
1215
+ | `conditional.action` | dependent field | `"show"` (hidden until met) or `"unlock"` (visible but read-only until met) |
1216
+
1217
+ ---
1218
+
1219
+ ## Constants
1220
+
1221
+ The SDK exposes idiomatic constants to avoid hard-coding string literals:
1222
+
1223
+ ```ruby
1224
+ TurboDocxSdk::QuoteStatus::DRAFT # "draft"
1225
+ TurboDocxSdk::QuoteStatus::SENT # "sent"
1226
+ TurboDocxSdk::BillingFrequency::MONTHLY # "monthly"
1227
+ TurboDocxSdk::BillingFrequency::ANNUAL # "annual"
1228
+ TurboDocxSdk::DiscountType::PERCENT # "percent"
1229
+ TurboDocxSdk::DiscountType::AMOUNT # "amount"
1230
+ TurboDocxSdk::Currency::USD # "USD"
1231
+ TurboDocxSdk::LineItemType::PRODUCT # "product"
1232
+ TurboDocxSdk::CategoryType::PRODUCT_CATEGORY # "product_category"
1233
+
1234
+ # Quote number configuration
1235
+ TurboDocxSdk::QuoteNumberYearToken::FOUR # "four"
1236
+ TurboDocxSdk::QuoteNumberMonthToken::TWO # "two"
1237
+ TurboDocxSdk::QuoteNumberResetCadence::NEVER # "never"
1238
+
1239
+ # Partner API key permission scopes
1240
+ TurboDocxSdk::PartnerScope::ORG_READ # "org:read"
1241
+ TurboDocxSdk::PartnerScope::AUDIT_READ # "audit:read"
1242
+ ```
1243
+
1244
+ Each constants module also exposes an `ALL` array of its valid values (e.g. `TurboDocxSdk::DiscountType::ALL`).
1245
+
1246
+ ---
1247
+
1248
+ ## Examples
1249
+
1250
+ For complete, working examples, see the [`examples/`](./examples/) directory:
1251
+
1252
+ - [`turbosign_basic.rb`](./examples/turbosign_basic.rb) — Send a document for signature, poll status, download the signed PDF
1253
+ - [`turbosign_template_roles.rb`](./examples/turbosign_template_roles.rb) — Send a template set up in TurboDocx by naming each signer's role
1254
+ - [`turbowebhooks_crud.rb`](./examples/turbowebhooks_crud.rb) — Create/get/update/delete the signature webhook + verify HMAC signatures
1255
+ - [`turboquote_basic.rb`](./examples/turboquote_basic.rb) — Full quote lifecycle: create company, quote, line items, download PDF, send
1256
+ - [`turboquote_products.rb`](./examples/turboquote_products.rb) — Products and bundles catalog management
1257
+ - [`turboquote_pricebooks.rb`](./examples/turboquote_pricebooks.rb) — Price books with per-product overrides, apply to quote
1258
+
1259
+ ### Sequential Signing
1260
+
1261
+ ```ruby
1262
+ result = TurboDocxSdk::TurboSign.send_signature(
1263
+ fileLink: "https://example.com/contract.pdf",
1264
+ recipients: [
1265
+ { name: "Employee", email: "employee@company.com", signingOrder: 1 },
1266
+ { name: "Manager", email: "manager@company.com", signingOrder: 2 },
1267
+ { name: "HR", email: "hr@company.com", signingOrder: 3 }
1268
+ ],
1269
+ fields: [
1270
+ # Employee signs first
1271
+ { type: "signature", recipientEmail: "employee@company.com", page: 1, x: 100, y: 400, width: 200, height: 50 },
1272
+ { type: "date", recipientEmail: "employee@company.com", page: 1, x: 320, y: 400, width: 100, height: 30 },
1273
+ # Manager signs second
1274
+ { type: "signature", recipientEmail: "manager@company.com", page: 1, x: 100, y: 500, width: 200, height: 50 },
1275
+ # HR signs last
1276
+ { type: "signature", recipientEmail: "hr@company.com", page: 1, x: 100, y: 600, width: 200, height: 50 }
1277
+ ]
1278
+ )
1279
+ ```
1280
+
1281
+ ### Polling for Completion
1282
+
1283
+ ```ruby
1284
+ def wait_for_completion(document_id, max_attempts: 60)
1285
+ max_attempts.times do
1286
+ status = TurboDocxSdk::TurboSign.get_status(document_id)
1287
+
1288
+ return TurboDocxSdk::TurboSign.download(document_id) if status["status"] == "completed"
1289
+ raise "Document was voided" if status["status"] == "voided"
1290
+
1291
+ sleep 30
1292
+ end
1293
+
1294
+ raise "Timeout waiting for signatures"
1295
+ end
1296
+ ```
1297
+
1298
+ ### With Rails
1299
+
1300
+ ```ruby
1301
+ # config/initializers/turbodocx.rb
1302
+ require "turbodocx_sdk"
1303
+
1304
+ TurboDocxSdk::TurboSign.configure(
1305
+ api_key: ENV["TURBODOCX_API_KEY"],
1306
+ org_id: ENV["TURBODOCX_ORG_ID"],
1307
+ sender_email: ENV["TURBODOCX_SENDER_EMAIL"]
1308
+ )
1309
+
1310
+ # app/controllers/contracts_controller.rb
1311
+ class ContractsController < ApplicationController
1312
+ def create
1313
+ result = TurboDocxSdk::TurboSign.send_signature(
1314
+ fileLink: params[:pdf_url],
1315
+ recipients: params[:recipients],
1316
+ fields: params[:fields]
1317
+ )
1318
+ render json: { success: true, document_id: result["documentId"] }
1319
+ rescue TurboDocxSdk::TurboDocxError => e
1320
+ render json: { error: e.message }, status: e.status_code || 500
1321
+ end
1322
+ end
1323
+ ```
1324
+
1325
+ ### With Sinatra
1326
+
1327
+ ```ruby
1328
+ require "sinatra"
1329
+ require "json"
1330
+ require "turbodocx_sdk"
1331
+
1332
+ TurboDocxSdk::TurboSign.configure(
1333
+ api_key: ENV["TURBODOCX_API_KEY"],
1334
+ org_id: ENV["TURBODOCX_ORG_ID"],
1335
+ sender_email: ENV["TURBODOCX_SENDER_EMAIL"]
1336
+ )
1337
+
1338
+ post "/api/send-contract" do
1339
+ body = JSON.parse(request.body.read)
1340
+ result = TurboDocxSdk::TurboSign.send_signature(
1341
+ fileLink: body["pdf_url"],
1342
+ recipients: body["recipients"],
1343
+ fields: body["fields"]
1344
+ )
1345
+ json_response = { success: true, document_id: result["documentId"] }
1346
+ content_type :json
1347
+ json_response.to_json
1348
+ end
1349
+ ```
1350
+
1351
+ ---
1352
+
1353
+ ## Error Handling
1354
+
1355
+ ```ruby
1356
+ require "turbodocx_sdk"
1357
+
1358
+ begin
1359
+ TurboDocxSdk::TurboSign.get_status("invalid-id")
1360
+ rescue TurboDocxSdk::NotFoundError => e
1361
+ puts "Not found: #{e.message}"
1362
+ rescue TurboDocxSdk::AuthenticationError => e
1363
+ puts "Auth failed (#{e.status_code}): #{e.message}"
1364
+ rescue TurboDocxSdk::ValidationError => e
1365
+ puts "Validation error: #{e.message}"
1366
+ rescue TurboDocxSdk::RateLimitError
1367
+ puts "Rate limited — slow down requests"
1368
+ rescue TurboDocxSdk::TurboDocxError => e
1369
+ puts "TurboDocx error (#{e.status_code}): #{e.message}"
1370
+ end
1371
+ ```
1372
+
1373
+ ### Error Hierarchy
1374
+
1375
+ | Class | HTTP Status |
1376
+ |:------|:------------|
1377
+ | `TurboDocxSdk::AuthenticationError` | 401 |
1378
+ | `TurboDocxSdk::AuthorizationError` | 403 |
1379
+ | `TurboDocxSdk::ValidationError` | 400 |
1380
+ | `TurboDocxSdk::NotFoundError` | 404 |
1381
+ | `TurboDocxSdk::ConflictError` | 409 |
1382
+ | `TurboDocxSdk::RateLimitError` | 429 |
1383
+ | `TurboDocxSdk::NetworkError` | (no status) |
1384
+ | `TurboDocxSdk::TurboDocxError` | base class |
1385
+
1386
+ ---
1387
+
1388
+ ### Error Codes
1389
+
1390
+ `code` is **always populated** — an API-supplied code when there is one, otherwise the error
1391
+ class's default (`VALIDATION_ERROR`, `AUTHENTICATION_ERROR`, `AUTHORIZATION_ERROR`,
1392
+ `NOT_FOUND`, `CONFLICT`, `RATE_LIMIT_EXCEEDED`, `NETWORK_ERROR`). Branch on it without a null
1393
+ check.
1394
+
1395
+ The API also returns more specific codes, passed through unchanged:
1396
+
1397
+ | Code | Status | Meaning |
1398
+ |:-----|:-------|:--------|
1399
+ | `SenderEmailRequired` | 400 | No sender email resolvable. TurboSign: set `senderEmail` on the request. TurboQuote: configure one on the org quote template (Quote Settings). |
1400
+ | `SenderNameRequired` | 400 | No sender name resolvable — the API key has no usable name. |
1401
+ | `OptionalNotSupported` | 400 | A `signature` or `initial` field was sent with `required: false`. The signer must always complete those two types. |
1402
+ | `InvalidFieldRequired` | 400 | A field's `required` is not a boolean. Send `true`, `false`, or leave it out (leaving it out means required). |
1403
+ | `NoEditableFieldsForRecipient` | 400 | A recipient has no field they must fill in: all of their fields are read-only or optional. Give each recipient at least one required, editable field. |
1404
+ | `FieldsRequired` | 400 | A send has no fields and no recipient names a `role`. Pass fields, or send a template whose recipients name roles. A review link can be created without fields. |
1405
+ | `FieldPageOutOfRange` | 400 | A field is placed on a page past the end of the document. |
1406
+ | `UnknownSignerRole` | 400 | A recipient's `role` is not one of the template's roles. The message lists them. |
1407
+ | `DuplicateSignerRole` | 400 | More than one recipient was given for the same role. |
1408
+ | `SignerRoleUnfilled` | 400 | A role has no recipient and no signer saved on the template. |
1409
+ | `TemplateHasNoSignerRoles` | 400 | `role` was used on a template with no saved signature setup. |
1410
+ | `RoleRequiresTemplate` | 400 | `role` was used without a `templateId`. |
1411
+ | `TemplateRolesNeedPdfTemplate` | 400 | Roles can only be sent for a PDF signature template. For a Word template, generate a deliverable and send it with `deliverableId`. |
1412
+ | `DuplicateRoleEmail` | 400 | Two roles resolve to the same email address (a recipient you passed or a signer saved on the template), or a recipient without a `role` uses a role's email address. Each signer needs their own email address. |
1413
+ | `SignerHasNoFields` | 400 | On a role send, a signer has no field to sign: neither the template nor your `fields` assigns one to them. Raised when sending (`send_signature`, embedded signing), not for a review link, where fields can be placed in the preview. |
1414
+ | `InvalidRecipient` | 400 | An entry in `recipients` is not an object (for example `null` or a string). |
1415
+ | `SignatureSetupNotFound` | 404 | `get_template_signature_setup` was called for a template with no saved signature setup, or one that is not in your organization. Thrown as `TurboDocxSdk::NotFoundError`. |
1416
+ | `QuoteHasNoLineItems` | 400 | The quote has no line items. Add at least one before sending. |
1417
+ | `QuoteExpired` | 400 | The quote is past its `validUntil` date. |
1418
+ | `QuoteValidUntilRequired` | 400 | The quote has no `validUntil` date set. |
1419
+ | `QuoteNotSendable` | 400 | Only draft quotes can be sent. |
1420
+ | `QuoteContactRequired` | 400 | The quote's contact is missing a name or email. |
1421
+ | `QuoteCustomerInactive` | 400 | The quote's company or contact was deleted or deactivated. |
1422
+
1423
+ Error **messages** carry the actionable reason, not a generic envelope — multiple field errors
1424
+ are joined with `"; "`, e.g. `"name" is not allowed to be empty; "companyId" must be a valid GUID`.
1425
+
1426
+ ## Requirements
1427
+
1428
+ - Ruby 2.7+
1429
+ - Zero runtime dependencies — the SDK uses only the Ruby standard library (`net/http`, `json`, `openssl`)
1430
+
1431
+ ---
1432
+
1433
+ ## Related Packages
1434
+
1435
+ | Package | Description |
1436
+ |:--------|:------------|
1437
+ | [@turbodocx/sdk (JavaScript)](../js-sdk) | JavaScript/TypeScript SDK |
1438
+ | [turbodocx-sdk (Python)](../py-sdk) | Python SDK |
1439
+ | [turbodocx (Go)](../go-sdk) | Go SDK |
1440
+ | [@turbodocx/n8n-nodes-turbodocx](https://www.npmjs.com/package/@turbodocx/n8n-nodes-turbodocx) | n8n community nodes |
1441
+
1442
+ ---
1443
+
1444
+ ## Support
1445
+
1446
+ - [Documentation](https://docs.turbodocx.com/docs)
1447
+ - [Discord](https://discord.gg/NYKwz4BcpX)
1448
+ - [GitHub Issues](https://github.com/TurboDocx/SDK/issues)
1449
+
1450
+ ---
1451
+
1452
+ ## License
1453
+
1454
+ MIT — see [LICENSE](./LICENSE)
1455
+
1456
+ ---
1457
+
1458
+ <div align="center">
1459
+
1460
+ [![TurboDocx](https://raw.githubusercontent.com/TurboDocx/SDK/main/packages/js-sdk/footer.png)](https://www.turbodocx.com)
1461
+
1462
+ </div>