signwell_sdk 0.1.0 → 0.1.2

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.
Files changed (240) hide show
  1. checksums.yaml +4 -4
  2. data/.github/ISSUE_TEMPLATE/bug_report.yml +53 -0
  3. data/.github/ISSUE_TEMPLATE/config.yml +5 -0
  4. data/.github/ISSUE_TEMPLATE/feature_request.yml +35 -0
  5. data/.github/pull_request_template.md +39 -0
  6. data/.github/workflows/ci.yml +45 -0
  7. data/.github/workflows/generator-ownership.yml +53 -0
  8. data/.github/workflows/manual-release.yml +64 -0
  9. data/.github/workflows/release.yml +69 -0
  10. data/.gitignore +39 -0
  11. data/.release-please-manifest.json +3 -0
  12. data/.rspec +2 -0
  13. data/.rubocop.yml +200 -0
  14. data/CONTRIBUTING.md +13 -0
  15. data/Gemfile.lock +15 -25
  16. data/README.md +82 -6
  17. data/docs/{APIApplicationApi.md → ApiApplicationApi.md} +9 -9
  18. data/docs/BulkSendApi.md +4 -4
  19. data/docs/DocumentApi.md +7 -5
  20. data/docs/DocumentFromTemplateResponse.md +1 -1
  21. data/docs/DocumentFromTemplateResponseFieldsInnerInner.md +2 -0
  22. data/docs/DocumentResponse.md +1 -1
  23. data/docs/DocumentResponseFieldsInnerInner.md +2 -0
  24. data/docs/FileInfo.md +1 -1
  25. data/docs/RegionalApi.md +4 -4
  26. data/docs/TemplateApi.md +3 -1
  27. data/docs/WebhookResponse.md +0 -2
  28. data/examples/09_webhook_validation.rb +10 -4
  29. data/lib/signwell_sdk/api/api_application_api.rb +36 -40
  30. data/lib/signwell_sdk/api/bulk_send_api.rb +117 -111
  31. data/lib/signwell_sdk/api/document_api.rb +239 -150
  32. data/lib/signwell_sdk/api/me_api.rb +21 -20
  33. data/lib/signwell_sdk/api/regional_api.rb +48 -29
  34. data/lib/signwell_sdk/api/template_api.rb +117 -85
  35. data/lib/signwell_sdk/api/webhooks_api.rb +50 -46
  36. data/lib/signwell_sdk/api_client.rb +251 -92
  37. data/lib/signwell_sdk/api_error.rb +142 -17
  38. data/lib/signwell_sdk/configuration.rb +43 -53
  39. data/lib/signwell_sdk/{embedded → extras/embedded}/railtie.rb +2 -0
  40. data/lib/signwell_sdk/extras/embedded/view_helpers.rb +281 -0
  41. data/lib/signwell_sdk/{embedded.rb → extras/embedded.rb} +96 -54
  42. data/lib/signwell_sdk/extras/webhook.rb +257 -0
  43. data/lib/signwell_sdk/models/account_info_response.rb +110 -85
  44. data/lib/signwell_sdk/models/account_info_response_active_users_inner.rb +80 -60
  45. data/lib/signwell_sdk/models/account_info_response_preferences.rb +112 -102
  46. data/lib/signwell_sdk/models/additional_fields_inner_inner.rb +227 -145
  47. data/lib/signwell_sdk/models/additional_fields_inner_inner_value.rb +25 -23
  48. data/lib/signwell_sdk/models/additional_files_inner.rb +58 -52
  49. data/lib/signwell_sdk/models/api_application_response.rb +91 -72
  50. data/lib/signwell_sdk/models/api_application_response_owner.rb +80 -58
  51. data/lib/signwell_sdk/models/api_application_response_preferences.rb +67 -62
  52. data/lib/signwell_sdk/models/attachment_request_info.rb +66 -52
  53. data/lib/signwell_sdk/models/attachment_requests_inner.rb +68 -56
  54. data/lib/signwell_sdk/models/bulk_send_create_response.rb +110 -77
  55. data/lib/signwell_sdk/models/bulk_send_csv_request.rb +54 -48
  56. data/lib/signwell_sdk/models/bulk_send_csv_template_response.rb +46 -42
  57. data/lib/signwell_sdk/models/bulk_send_documents_response.rb +146 -102
  58. data/lib/signwell_sdk/models/bulk_send_list_item.rb +147 -97
  59. data/lib/signwell_sdk/models/bulk_send_list_response.rb +99 -72
  60. data/lib/signwell_sdk/models/bulk_send_response.rb +125 -91
  61. data/lib/signwell_sdk/models/bulk_send_response_templates_inner.rb +60 -48
  62. data/lib/signwell_sdk/models/bulk_send_validate_csv_response.rb +91 -77
  63. data/lib/signwell_sdk/models/checkbox_group_info.rb +111 -85
  64. data/lib/signwell_sdk/models/checkbox_groups_inner.rb +105 -82
  65. data/lib/signwell_sdk/models/checkbox_validation.rb +15 -16
  66. data/lib/signwell_sdk/models/completed_pdf_response.rb +24 -22
  67. data/lib/signwell_sdk/models/completed_pdf_url_response.rb +46 -42
  68. data/lib/signwell_sdk/models/copied_contact_info.rb +58 -50
  69. data/lib/signwell_sdk/models/copied_contacts_inner.rb +52 -46
  70. data/lib/signwell_sdk/models/copied_placeholders_inner.rb +57 -53
  71. data/lib/signwell_sdk/models/create_bulk_send_request.rb +107 -92
  72. data/lib/signwell_sdk/models/create_webhook_request.rb +52 -48
  73. data/lib/signwell_sdk/models/date_format.rb +16 -17
  74. data/lib/signwell_sdk/models/detailed_option.rb +60 -54
  75. data/lib/signwell_sdk/models/document_from_template_request.rb +266 -223
  76. data/lib/signwell_sdk/models/document_from_template_response.rb +291 -214
  77. data/lib/signwell_sdk/models/document_from_template_response_fields_inner_inner.rb +226 -139
  78. data/lib/signwell_sdk/models/document_from_template_response_fields_inner_inner_recipient.rb +66 -54
  79. data/lib/signwell_sdk/models/document_from_template_response_recipients_inner.rb +153 -121
  80. data/lib/signwell_sdk/models/document_list_response.rb +99 -72
  81. data/lib/signwell_sdk/models/document_request.rb +251 -214
  82. data/lib/signwell_sdk/models/document_response.rb +293 -216
  83. data/lib/signwell_sdk/models/document_response_attachment_requests_inner.rb +66 -54
  84. data/lib/signwell_sdk/models/document_response_fields_inner_inner.rb +226 -139
  85. data/lib/signwell_sdk/models/document_response_fields_inner_inner_options_inner.rb +51 -49
  86. data/lib/signwell_sdk/models/document_response_fields_inner_inner_recipient.rb +60 -48
  87. data/lib/signwell_sdk/models/document_response_fields_inner_inner_value.rb +25 -23
  88. data/lib/signwell_sdk/models/document_response_recipients_inner.rb +156 -120
  89. data/lib/signwell_sdk/models/document_template_list_response.rb +99 -72
  90. data/lib/signwell_sdk/models/document_template_request.rb +199 -166
  91. data/lib/signwell_sdk/models/document_template_response.rb +240 -181
  92. data/lib/signwell_sdk/models/document_template_response_copied_placeholders_inner.rb +83 -72
  93. data/lib/signwell_sdk/models/document_template_response_placeholders_inner.rb +90 -80
  94. data/lib/signwell_sdk/models/document_template_update_request.rb +142 -125
  95. data/lib/signwell_sdk/models/dropdown_option.rb +24 -22
  96. data/lib/signwell_sdk/models/error_response.rb +45 -45
  97. data/lib/signwell_sdk/models/error_response_meta.rb +67 -55
  98. data/lib/signwell_sdk/models/field_type.rb +27 -29
  99. data/lib/signwell_sdk/models/fields_inner_inner.rb +221 -141
  100. data/lib/signwell_sdk/models/file_format.rb +13 -14
  101. data/lib/signwell_sdk/models/file_info.rb +53 -57
  102. data/lib/signwell_sdk/models/files_inner.rb +58 -52
  103. data/lib/signwell_sdk/models/label_info.rb +45 -45
  104. data/lib/signwell_sdk/models/label_request.rb +46 -42
  105. data/lib/signwell_sdk/models/label_response.rb +52 -46
  106. data/lib/signwell_sdk/models/me_response.rb +122 -76
  107. data/lib/signwell_sdk/models/me_response_contact.rb +114 -85
  108. data/lib/signwell_sdk/models/me_response_user.rb +92 -68
  109. data/lib/signwell_sdk/models/me_response_user_preferences.rb +51 -49
  110. data/lib/signwell_sdk/models/nom151_certificate_response.rb +46 -42
  111. data/lib/signwell_sdk/models/nom151_certificate_response_nom151.rb +138 -82
  112. data/lib/signwell_sdk/models/nom151_url_response.rb +46 -42
  113. data/lib/signwell_sdk/models/pagination_meta.rb +88 -65
  114. data/lib/signwell_sdk/models/placeholders_inner.rb +71 -59
  115. data/lib/signwell_sdk/models/rate_limit_error_response.rb +46 -42
  116. data/lib/signwell_sdk/models/recipients_inner.rb +100 -80
  117. data/lib/signwell_sdk/models/reminder_recipients_inner.rb +45 -45
  118. data/lib/signwell_sdk/models/send_reminder_request.rb +40 -42
  119. data/lib/signwell_sdk/models/template_attachment_requests_inner.rb +65 -55
  120. data/lib/signwell_sdk/models/template_checkbox_groups_inner.rb +102 -81
  121. data/lib/signwell_sdk/models/template_field_values_inner.rb +60 -48
  122. data/lib/signwell_sdk/models/template_field_values_inner_value.rb +25 -23
  123. data/lib/signwell_sdk/models/template_fields_inner_inner.rb +218 -140
  124. data/lib/signwell_sdk/models/template_recipients_inner.rb +106 -84
  125. data/lib/signwell_sdk/models/text_validation.rb +23 -25
  126. data/lib/signwell_sdk/models/update_document_and_send_request.rb +170 -149
  127. data/lib/signwell_sdk/models/update_recipients_map_inner.rb +92 -68
  128. data/lib/signwell_sdk/models/update_recipients_request.rb +43 -43
  129. data/lib/signwell_sdk/models/validation_error_response.rb +43 -43
  130. data/lib/signwell_sdk/models/webhook_response.rb +68 -66
  131. data/lib/signwell_sdk/version.rb +1 -1
  132. data/lib/signwell_sdk.rb +17 -13
  133. data/openapi.yaml +425 -415
  134. data/signwell_sdk.gemspec +25 -6
  135. data/spec/api/api_application_api_spec.rb +16 -14
  136. data/spec/api/bulk_send_api_spec.rb +14 -14
  137. data/spec/api/document_api_spec.rb +17 -21
  138. data/spec/api/me_api_spec.rb +13 -11
  139. data/spec/api/regional_api_spec.rb +14 -12
  140. data/spec/api/template_api_spec.rb +13 -13
  141. data/spec/api/webhooks_api_spec.rb +13 -11
  142. data/spec/models/account_info_response_active_users_inner_spec.rb +12 -11
  143. data/spec/models/account_info_response_preferences_spec.rb +12 -11
  144. data/spec/models/account_info_response_spec.rb +12 -11
  145. data/spec/models/additional_fields_inner_inner_spec.rb +12 -11
  146. data/spec/models/additional_fields_inner_inner_value_spec.rb +10 -10
  147. data/spec/models/additional_files_inner_spec.rb +12 -11
  148. data/spec/models/api_application_response_owner_spec.rb +12 -11
  149. data/spec/models/api_application_response_preferences_spec.rb +12 -11
  150. data/spec/models/api_application_response_spec.rb +11 -10
  151. data/spec/models/attachment_request_info_spec.rb +12 -11
  152. data/spec/models/attachment_requests_inner_spec.rb +12 -11
  153. data/spec/models/bulk_send_create_response_spec.rb +11 -10
  154. data/spec/models/bulk_send_csv_request_spec.rb +12 -11
  155. data/spec/models/bulk_send_csv_template_response_spec.rb +12 -11
  156. data/spec/models/bulk_send_documents_response_spec.rb +12 -11
  157. data/spec/models/bulk_send_list_item_spec.rb +12 -11
  158. data/spec/models/bulk_send_list_response_spec.rb +11 -10
  159. data/spec/models/bulk_send_response_spec.rb +12 -11
  160. data/spec/models/bulk_send_response_templates_inner_spec.rb +12 -11
  161. data/spec/models/bulk_send_validate_csv_response_spec.rb +11 -10
  162. data/spec/models/checkbox_group_info_spec.rb +12 -11
  163. data/spec/models/checkbox_groups_inner_spec.rb +11 -10
  164. data/spec/models/checkbox_validation_spec.rb +11 -10
  165. data/spec/models/completed_pdf_response_spec.rb +10 -10
  166. data/spec/models/completed_pdf_url_response_spec.rb +12 -11
  167. data/spec/models/copied_contact_info_spec.rb +12 -11
  168. data/spec/models/copied_contacts_inner_spec.rb +12 -11
  169. data/spec/models/copied_placeholders_inner_spec.rb +12 -11
  170. data/spec/models/create_bulk_send_request_spec.rb +12 -11
  171. data/spec/models/create_webhook_request_spec.rb +12 -11
  172. data/spec/models/date_format_spec.rb +11 -10
  173. data/spec/models/detailed_option_spec.rb +12 -11
  174. data/spec/models/document_from_template_request_spec.rb +12 -11
  175. data/spec/models/document_from_template_response_fields_inner_inner_recipient_spec.rb +12 -11
  176. data/spec/models/document_from_template_response_fields_inner_inner_spec.rb +18 -11
  177. data/spec/models/document_from_template_response_recipients_inner_spec.rb +12 -11
  178. data/spec/models/document_from_template_response_spec.rb +12 -11
  179. data/spec/models/document_list_response_spec.rb +11 -10
  180. data/spec/models/document_request_spec.rb +12 -11
  181. data/spec/models/document_response_attachment_requests_inner_spec.rb +12 -11
  182. data/spec/models/document_response_fields_inner_inner_options_inner_spec.rb +12 -11
  183. data/spec/models/document_response_fields_inner_inner_recipient_spec.rb +12 -11
  184. data/spec/models/document_response_fields_inner_inner_spec.rb +18 -11
  185. data/spec/models/document_response_fields_inner_inner_value_spec.rb +10 -10
  186. data/spec/models/document_response_recipients_inner_spec.rb +12 -11
  187. data/spec/models/document_response_spec.rb +12 -11
  188. data/spec/models/document_template_list_response_spec.rb +11 -10
  189. data/spec/models/document_template_request_spec.rb +12 -11
  190. data/spec/models/document_template_response_copied_placeholders_inner_spec.rb +11 -10
  191. data/spec/models/document_template_response_placeholders_inner_spec.rb +11 -10
  192. data/spec/models/document_template_response_spec.rb +12 -11
  193. data/spec/models/document_template_update_request_spec.rb +12 -11
  194. data/spec/models/dropdown_option_spec.rb +10 -10
  195. data/spec/models/error_response_meta_spec.rb +12 -11
  196. data/spec/models/error_response_spec.rb +12 -11
  197. data/spec/models/field_type_spec.rb +11 -10
  198. data/spec/models/fields_inner_inner_spec.rb +12 -11
  199. data/spec/models/file_format_spec.rb +11 -10
  200. data/spec/models/file_info_spec.rb +12 -11
  201. data/spec/models/files_inner_spec.rb +12 -11
  202. data/spec/models/label_info_spec.rb +12 -11
  203. data/spec/models/label_request_spec.rb +12 -11
  204. data/spec/models/label_response_spec.rb +12 -11
  205. data/spec/models/me_response_contact_spec.rb +12 -11
  206. data/spec/models/me_response_spec.rb +11 -10
  207. data/spec/models/me_response_user_preferences_spec.rb +12 -11
  208. data/spec/models/me_response_user_spec.rb +11 -10
  209. data/spec/models/nom151_certificate_response_nom151_spec.rb +11 -10
  210. data/spec/models/nom151_certificate_response_spec.rb +12 -11
  211. data/spec/models/nom151_url_response_spec.rb +12 -11
  212. data/spec/models/pagination_meta_spec.rb +12 -11
  213. data/spec/models/placeholders_inner_spec.rb +12 -11
  214. data/spec/models/rate_limit_error_response_spec.rb +12 -11
  215. data/spec/models/recipients_inner_spec.rb +11 -10
  216. data/spec/models/reminder_recipients_inner_spec.rb +12 -11
  217. data/spec/models/send_reminder_request_spec.rb +12 -11
  218. data/spec/models/template_attachment_requests_inner_spec.rb +12 -11
  219. data/spec/models/template_checkbox_groups_inner_spec.rb +11 -10
  220. data/spec/models/template_field_values_inner_spec.rb +12 -11
  221. data/spec/models/template_field_values_inner_value_spec.rb +10 -10
  222. data/spec/models/template_fields_inner_inner_spec.rb +12 -11
  223. data/spec/models/template_recipients_inner_spec.rb +12 -11
  224. data/spec/models/text_validation_spec.rb +11 -10
  225. data/spec/models/update_document_and_send_request_spec.rb +12 -11
  226. data/spec/models/update_recipients_map_inner_spec.rb +11 -10
  227. data/spec/models/update_recipients_request_spec.rb +12 -11
  228. data/spec/models/validation_error_response_spec.rb +12 -11
  229. data/spec/models/webhook_response_spec.rb +12 -17
  230. data/spec/regressions/api_client_spec.rb +481 -0
  231. data/spec/regressions/bulk_send_api_spec.rb +47 -0
  232. data/spec/regressions/embedded_spec.rb +263 -0
  233. data/spec/regressions/generated_resource_helpers_spec.rb +119 -0
  234. data/spec/regressions/response_modes_spec.rb +93 -0
  235. data/spec/regressions/view_helpers_spec.rb +202 -0
  236. data/spec/regressions/webhook_spec.rb +210 -0
  237. data/spec/spec_helper.rb +11 -12
  238. metadata +127 -91
  239. data/lib/signwell_sdk/embedded/view_helpers.rb +0 -132
  240. data/lib/signwell_sdk/webhook.rb +0 -75
data/Gemfile.lock CHANGED
@@ -3,48 +3,39 @@ PATH
3
3
  specs:
4
4
  signwell_sdk (0.1.0)
5
5
  faraday (>= 1.0.1, < 3.0)
6
- faraday-multipart
7
- marcel
6
+ faraday-multipart (~> 1.0, >= 1.0.0)
7
+ marcel (~> 1.0, >= 1.0.0)
8
8
 
9
9
  GEM
10
10
  remote: https://rubygems.org/
11
11
  specs:
12
- addressable (2.8.9)
13
- public_suffix (>= 2.0.2, < 8.0)
14
12
  ast (2.4.3)
15
- bigdecimal (4.0.1)
16
13
  diff-lcs (1.6.2)
17
- faraday (2.14.1)
14
+ faraday (2.14.4)
18
15
  faraday-net_http (>= 2.0, < 3.5)
19
16
  json
20
17
  logger
21
18
  faraday-multipart (1.2.0)
22
19
  multipart-post (~> 2.0)
23
- faraday-net_http (3.4.2)
20
+ faraday-net_http (3.4.4)
24
21
  net-http (~> 0.5)
25
- json (2.19.1)
26
- json-schema (6.2.0)
27
- addressable (~> 2.8)
28
- bigdecimal (>= 3.1, < 5)
29
- language_server-protocol (3.17.0.5)
22
+ json (3.0.2)
23
+ language_server-protocol (3.17.0.6)
30
24
  lint_roller (1.1.0)
31
25
  logger (1.7.0)
32
- marcel (1.1.0)
33
- mcp (0.8.0)
34
- json-schema (>= 4.1)
26
+ marcel (1.2.1)
35
27
  multipart-post (2.4.1)
36
28
  net-http (0.9.1)
37
29
  uri (>= 0.11.1)
38
- parallel (1.27.0)
39
- parser (3.3.10.2)
30
+ parallel (2.2.0)
31
+ parser (3.3.12.0)
40
32
  ast (~> 2.4.1)
41
33
  racc
42
34
  prism (1.9.0)
43
- public_suffix (7.0.5)
44
35
  racc (1.8.1)
45
36
  rainbow (3.1.1)
46
- rake (13.3.1)
47
- regexp_parser (2.11.3)
37
+ rake (13.4.2)
38
+ regexp_parser (2.12.0)
48
39
  rspec (3.13.2)
49
40
  rspec-core (~> 3.13.0)
50
41
  rspec-expectations (~> 3.13.0)
@@ -58,19 +49,18 @@ GEM
58
49
  diff-lcs (>= 1.2.0, < 2.0)
59
50
  rspec-support (~> 3.13.0)
60
51
  rspec-support (3.13.7)
61
- rubocop (1.85.1)
62
- json (~> 2.3)
52
+ rubocop (1.91.0)
53
+ json (>= 2.3)
63
54
  language_server-protocol (~> 3.17.0.2)
64
55
  lint_roller (~> 1.1.0)
65
- mcp (~> 0.6)
66
- parallel (~> 1.10)
56
+ parallel (>= 1.10)
67
57
  parser (>= 3.3.0.2)
68
58
  rainbow (>= 2.2.2, < 4.0)
69
59
  regexp_parser (>= 2.9.3, < 3.0)
70
60
  rubocop-ast (>= 1.49.0, < 2.0)
71
61
  ruby-progressbar (~> 1.7)
72
62
  unicode-display_width (>= 2.4.0, < 4.0)
73
- rubocop-ast (1.49.1)
63
+ rubocop-ast (1.50.0)
74
64
  parser (>= 3.3.7.2)
75
65
  prism (~> 1.7)
76
66
  ruby-progressbar (1.13.0)
data/README.md CHANGED
@@ -58,6 +58,50 @@ document = api.create_document(request)
58
58
  puts document.id
59
59
  ```
60
60
 
61
+ Status errors are available under `SignWell::Errors`. HTTP 403 responses raise `PermissionDeniedError`, with `ForbiddenError` kept as an additive alias. Transport failures raise `ApiConnectionError`, with `TransportError` kept as an additive alias. Local required-argument validation uses Ruby's native `ArgumentError`.
62
+
63
+ ## Binary Responses
64
+
65
+ Some endpoints return a downloaded file by default and JSON when a mode flag is enabled.
66
+
67
+ ```ruby
68
+ bulk_send = SignWell::Resources::BulkSendApi.new
69
+ documents = SignWell::Resources::DocumentApi.new
70
+ regional = SignWell::Resources::RegionalApi.new
71
+
72
+ csv_file = bulk_send.get_bulk_send_csv_template(['00000000-0000-0000-0000-000000000000'])
73
+ csv_json = bulk_send.get_bulk_send_csv_template(
74
+ ['00000000-0000-0000-0000-000000000000'],
75
+ base64: true
76
+ )
77
+
78
+ pdf_file = documents.get_completed_pdf('doc_123')
79
+ pdf_url = documents.get_completed_pdf('doc_123', url_only: true)
80
+
81
+ certificate_file = regional.get_nom151_certificate('doc_123')
82
+ certificate_url = regional.get_nom151_certificate('doc_123', url_only: true)
83
+ certificate_object = regional.get_nom151_certificate('doc_123', object_only: true)
84
+ ```
85
+
86
+ Downloaded files are returned as `Tempfile` objects by default. Set `config.return_binary_data = true` if you want binary response bodies returned as strings.
87
+
88
+ ## Rate Limits
89
+
90
+ A 429 raises `SignWell::Errors::RateLimitError`, which carries the throttling headers on `error.rate_limit`:
91
+
92
+ ```ruby
93
+ begin
94
+ documents.create_document(body)
95
+ rescue SignWell::Errors::RateLimitError => e
96
+ e.rate_limit.limit # => 100
97
+ e.rate_limit.remaining # => 0
98
+ e.rate_limit.reset_at # => 2026-09-20 21:55:00 UTC
99
+ e.rate_limit.retry_after # => 30
100
+ end
101
+ ```
102
+
103
+ `reset` is in seconds either way, but it means two different things: an absolute epoch when the server sends a timestamp (what SignWell sends) or a large number, and a delay from now when it sends a small one. **`reset_at` is set only when `reset` is absolute** — so check it rather than guessing, and prefer `retry_after` / `retry_after_at` when you just want a sleep. Any field the response did not carry is `nil`.
104
+
61
105
  ## Embedded Signing
62
106
 
63
107
  The embedded API lets you integrate document signing directly into your app via an iframe, instead of redirecting users to SignWell. The `SignWell::Embedded` helper simplifies both the backend (creating documents, extracting URLs) and the frontend (rendering the iframe).
@@ -67,24 +111,26 @@ The embedded API lets you integrate document signing directly into your app via
67
111
  ```ruby
68
112
  doc = SignWell::Embedded.create_signing_document(
69
113
  name: 'NDA',
70
- file_url: 'https://example.com/nda.pdf',
114
+ files: [{ name: 'nda.pdf', file_url: 'https://example.com/nda.pdf' }],
71
115
  recipients: [{ name: 'Jane Doe', email: 'jane@example.com' }],
72
116
  fields: [[{ x: 20, y: 60, page: 1, type: 'signature' }]]
73
117
  )
74
118
 
75
119
  # Get the signing URL for the first recipient
76
- signing_url = SignWell::Embedded.signing_url(doc)
120
+ signing_url = SignWell::Embedded.embedded_signing_url(doc)
77
121
 
78
122
  # Or get all signing URLs as { email => url }
79
- urls = SignWell::Embedded.signing_urls(doc)
123
+ urls = SignWell::Embedded.embedded_signing_urls(doc)
80
124
  ```
81
125
 
126
+ Embedded signing documents must provide fields for every recipient, set `with_signature_page: true`, or use `text_tags: true`. The helper validates that shape before making the API request so invalid fieldless signing documents fail locally instead of returning a `422` response.
127
+
82
128
  ### Backend: Create a draft for embedded requesting (field placement)
83
129
 
84
130
  ```ruby
85
131
  doc = SignWell::Embedded.create_requesting_document(
86
132
  name: 'Contract',
87
- file_url: 'https://example.com/contract.pdf',
133
+ files: [{ name: 'contract.pdf', file_url: 'https://example.com/contract.pdf' }],
88
134
  recipients: [{ name: 'Jane Doe', email: 'jane@example.com' }]
89
135
  )
90
136
 
@@ -106,7 +152,7 @@ doc = SignWell::Embedded.create_signing_document_from_template(
106
152
  recipients: [{ placeholder_name: 'Signer 1', name: 'Jane Doe', email: 'jane@example.com' }]
107
153
  )
108
154
 
109
- signing_url = SignWell::Embedded.signing_url(doc)
155
+ signing_url = SignWell::Embedded.embedded_signing_url(doc)
110
156
  ```
111
157
 
112
158
  ### Frontend: JavaScript
@@ -131,10 +177,40 @@ If you use Rails, view helpers are available automatically:
131
177
 
132
178
  ```erb
133
179
  <%= signwell_embed_script_tag %>
134
- <%= signwell_signing_iframe(url: @signing_url, events: { completed: 'onComplete' }) %>
180
+ <%= signwell_signing_iframe(url: @signing_url, events: { completed: 'SignWellHandlers.onComplete' }) %>
135
181
  <%= signwell_requesting_iframe(url: @edit_url) %>
136
182
  ```
137
183
 
184
+ Embed helpers only accept HTTPS SignWell URLs by default and reject credentialed URLs, `http:`, `javascript:`, and arbitrary hosts before rendering script output. For non-production SignWell environments, pass exact hostnames through `allowed_embed_hosts`. Redirect URLs must be HTTPS and credential-free; pass `allowed_redirect_hosts` to restrict redirects to your app host.
185
+
186
+ ## Webhooks
187
+
188
+ ```ruby
189
+ payload = JSON.parse(request.body.read)
190
+ event = payload['event']
191
+
192
+ SignWell::Webhook.verify_event!(
193
+ event: event,
194
+ webhook_id: ENV.fetch('SIGNWELL_WEBHOOK_ID'),
195
+ tolerance_seconds: 300
196
+ )
197
+ ```
198
+
199
+ Use replay-aware verification when webhook processing has side effects:
200
+
201
+ ```ruby
202
+ REPLAY_STORE = SignWell::Webhook::MemoryReplayStore.new
203
+
204
+ SignWell::Webhook.verify_event_once!(
205
+ event: event,
206
+ webhook_id: ENV.fetch('SIGNWELL_WEBHOOK_ID'),
207
+ tolerance_seconds: 300,
208
+ replay_store: REPLAY_STORE
209
+ )
210
+ ```
211
+
212
+ `verify_event` and `verify_event_once` return `false` instead of raising. The in-memory replay store is intended for local development and single-process examples; production apps should back replay protection with Redis, a database, or another shared atomic insert.
213
+
138
214
  ## Documentation
139
215
 
140
216
  For the full API reference (all resources, models, and methods), see the documentation on gemdocs:
@@ -1,11 +1,11 @@
1
- # SignWell::Resources::APIApplicationApi
1
+ # SignWell::Resources::ApiApplicationApi
2
2
 
3
3
  All URIs are relative to *https://www.signwell.com*
4
4
 
5
5
  | Method | HTTP request | Description |
6
6
  | ------ | ------------ | ----------- |
7
- | [**delete_api_application**](APIApplicationApi.md#delete_api_application) | **DELETE** /api/v1/api_applications/{id} | Delete API Application |
8
- | [**get_api_application**](APIApplicationApi.md#get_api_application) | **GET** /api/v1/api_applications/{id} | Get API Application |
7
+ | [**delete_api_application**](ApiApplicationApi.md#delete_api_application) | **DELETE** /api/v1/api_applications/{id} | Delete API Application |
8
+ | [**get_api_application**](ApiApplicationApi.md#get_api_application) | **GET** /api/v1/api_applications/{id} | Get API Application |
9
9
 
10
10
 
11
11
  ## delete_api_application
@@ -29,14 +29,14 @@ SignWell.configure do |config|
29
29
  # config.api_key_prefix['X-Api-Key'] = 'Bearer'
30
30
  end
31
31
 
32
- api_instance = SignWell::Resources::APIApplicationApi.new
32
+ api_instance = SignWell::Resources::ApiApplicationApi.new
33
33
  id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String |
34
34
 
35
35
  begin
36
36
  # Delete API Application
37
37
  api_instance.delete_api_application(id)
38
38
  rescue SignWell::Errors::ApiError => e
39
- puts "Error when calling APIApplicationApi->delete_api_application: #{e}"
39
+ puts "Error when calling ApiApplicationApi->delete_api_application: #{e}"
40
40
  end
41
41
  ```
42
42
 
@@ -54,7 +54,7 @@ begin
54
54
  p headers # => { ... }
55
55
  p data # => nil
56
56
  rescue SignWell::Errors::ApiError => e
57
- puts "Error when calling APIApplicationApi->delete_api_application_with_http_info: #{e}"
57
+ puts "Error when calling ApiApplicationApi->delete_api_application_with_http_info: #{e}"
58
58
  end
59
59
  ```
60
60
 
@@ -99,7 +99,7 @@ SignWell.configure do |config|
99
99
  # config.api_key_prefix['X-Api-Key'] = 'Bearer'
100
100
  end
101
101
 
102
- api_instance = SignWell::Resources::APIApplicationApi.new
102
+ api_instance = SignWell::Resources::ApiApplicationApi.new
103
103
  id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String |
104
104
 
105
105
  begin
@@ -107,7 +107,7 @@ begin
107
107
  result = api_instance.get_api_application(id)
108
108
  p result
109
109
  rescue SignWell::Errors::ApiError => e
110
- puts "Error when calling APIApplicationApi->get_api_application: #{e}"
110
+ puts "Error when calling ApiApplicationApi->get_api_application: #{e}"
111
111
  end
112
112
  ```
113
113
 
@@ -125,7 +125,7 @@ begin
125
125
  p headers # => { ... }
126
126
  p data # => <ApiApplicationResponse>
127
127
  rescue SignWell::Errors::ApiError => e
128
- puts "Error when calling APIApplicationApi->get_api_application_with_http_info: #{e}"
128
+ puts "Error when calling ApiApplicationApi->get_api_application_with_http_info: #{e}"
129
129
  end
130
130
  ```
131
131
 
data/docs/BulkSendApi.md CHANGED
@@ -156,7 +156,7 @@ end
156
156
 
157
157
  ## get_bulk_send_csv_template
158
158
 
159
- > File get_bulk_send_csv_template(template_ids, opts)
159
+ > Models::BulkSendCsvTemplateResponse or File get_bulk_send_csv_template(template_ids, opts)
160
160
 
161
161
  Get Bulk Send CSV Template
162
162
 
@@ -194,7 +194,7 @@ end
194
194
 
195
195
  This returns an Array which contains the response data, status code and headers.
196
196
 
197
- > <Array(File, Integer, Hash)> get_bulk_send_csv_template_with_http_info(template_ids, opts)
197
+ > <Array(Models::BulkSendCsvTemplateResponse or File, Integer, Hash)> get_bulk_send_csv_template_with_http_info(template_ids, opts)
198
198
 
199
199
  ```ruby
200
200
  begin
@@ -202,7 +202,7 @@ begin
202
202
  data, status_code, headers = api_instance.get_bulk_send_csv_template_with_http_info(template_ids, opts)
203
203
  p status_code # => 2xx
204
204
  p headers # => { ... }
205
- p data # => File
205
+ p data # => Models::BulkSendCsvTemplateResponse or File
206
206
  rescue SignWell::Errors::ApiError => e
207
207
  puts "Error when calling BulkSendApi->get_bulk_send_csv_template_with_http_info: #{e}"
208
208
  end
@@ -217,7 +217,7 @@ end
217
217
 
218
218
  ### Return type
219
219
 
220
- **File**
220
+ **Models::BulkSendCsvTemplateResponse or File**
221
221
 
222
222
  ### Authorization
223
223
 
data/docs/DocumentApi.md CHANGED
@@ -229,7 +229,7 @@ nil (empty response body)
229
229
 
230
230
  ## get_completed_pdf
231
231
 
232
- > <CompletedPdfResponse> get_completed_pdf(id, opts)
232
+ > Models::CompletedPdfUrlResponse or File get_completed_pdf(id, opts)
233
233
 
234
234
  Completed PDF
235
235
 
@@ -269,7 +269,7 @@ end
269
269
 
270
270
  This returns an Array which contains the response data, status code and headers.
271
271
 
272
- > <Array(<CompletedPdfResponse>, Integer, Hash)> get_completed_pdf_with_http_info(id, opts)
272
+ > <Array(Models::CompletedPdfUrlResponse or File, Integer, Hash)> get_completed_pdf_with_http_info(id, opts)
273
273
 
274
274
  ```ruby
275
275
  begin
@@ -277,7 +277,7 @@ begin
277
277
  data, status_code, headers = api_instance.get_completed_pdf_with_http_info(id, opts)
278
278
  p status_code # => 2xx
279
279
  p headers # => { ... }
280
- p data # => <CompletedPdfResponse>
280
+ p data # => Models::CompletedPdfUrlResponse or File
281
281
  rescue SignWell::Errors::ApiError => e
282
282
  puts "Error when calling DocumentApi->get_completed_pdf_with_http_info: #{e}"
283
283
  end
@@ -294,7 +294,7 @@ end
294
294
 
295
295
  ### Return type
296
296
 
297
- [**CompletedPdfResponse**](CompletedPdfResponse.md)
297
+ **Models::CompletedPdfUrlResponse or File**
298
298
 
299
299
  ### Authorization
300
300
 
@@ -401,7 +401,8 @@ end
401
401
  api_instance = SignWell::Resources::DocumentApi.new
402
402
  opts = {
403
403
  page: 56, # Integer |
404
- limit: 56 # Integer |
404
+ limit: 56, # Integer |
405
+ query: 'query_example' # String | Raw API filter query. Use AND between filters, for example: \"name:Classic AND status:completed\".
405
406
  }
406
407
 
407
408
  begin
@@ -437,6 +438,7 @@ end
437
438
  | ---- | ---- | ----------- | ----- |
438
439
  | **page** | **Integer** | | [optional][default to 1] |
439
440
  | **limit** | **Integer** | | [optional][default to 10] |
441
+ | **query** | **String** | Raw API filter query. Use AND between filters, for example: \&quot;name:Classic AND status:completed\&quot;. | [optional] |
440
442
 
441
443
  ### Return type
442
444
 
@@ -19,7 +19,7 @@
19
19
  | **created_at** | **Time** | | [optional] |
20
20
  | **updated_at** | **Time** | | [optional] |
21
21
  | **recipients** | [**Array&lt;DocumentFromTemplateResponseRecipientsInner&gt;**](DocumentFromTemplateResponseRecipientsInner.md) | | [optional] |
22
- | **status** | **String** | | [optional] |
22
+ | **status** | **String** | Possible values: Draft, Created, Sending, Sent, Pending, Viewed, Completed, Manually completed, Declined, Canceled, Bounced, Blocked, Error, Expired | [optional] |
23
23
  | **reminders** | **Boolean** | | [optional] |
24
24
  | **archived** | **Boolean** | | [optional] |
25
25
  | **embedded_signing** | **Boolean** | | [optional] |
@@ -12,6 +12,7 @@
12
12
  | **name** | **String** | | [optional] |
13
13
  | **date_format** | [**DateFormat**](DateFormat.md) | | [optional] |
14
14
  | **fixed_width** | **Boolean** | | [optional] |
15
+ | **formula** | **String** | | [optional] |
15
16
  | **label** | **String** | | [optional] |
16
17
  | **lock_sign_date** | **Boolean** | | [optional] |
17
18
  | **required** | **Boolean** | | [optional] |
@@ -41,6 +42,7 @@ instance = SignWell::Models::DocumentFromTemplateResponseFieldsInnerInner.new(
41
42
  name: null,
42
43
  date_format: null,
43
44
  fixed_width: null,
45
+ formula: null,
44
46
  label: null,
45
47
  lock_sign_date: null,
46
48
  required: null,
@@ -17,7 +17,7 @@
17
17
  | **created_at** | **Time** | | [optional] |
18
18
  | **updated_at** | **Time** | | [optional] |
19
19
  | **recipients** | [**Array&lt;DocumentResponseRecipientsInner&gt;**](DocumentResponseRecipientsInner.md) | | [optional] |
20
- | **status** | **String** | | [optional] |
20
+ | **status** | **String** | Possible values: Draft, Created, Sending, Sent, Pending, Viewed, Completed, Manually completed, Declined, Canceled, Bounced, Blocked, Error, Expired | [optional] |
21
21
  | **reminders** | **Boolean** | | [optional] |
22
22
  | **archived** | **Boolean** | | [optional] |
23
23
  | **embedded_signing** | **Boolean** | | [optional] |
@@ -12,6 +12,7 @@
12
12
  | **name** | **String** | | [optional] |
13
13
  | **date_format** | [**DateFormat**](DateFormat.md) | | [optional] |
14
14
  | **fixed_width** | **Boolean** | | [optional] |
15
+ | **formula** | **String** | | [optional] |
15
16
  | **label** | **String** | | [optional] |
16
17
  | **lock_sign_date** | **Boolean** | | [optional] |
17
18
  | **required** | **Boolean** | | [optional] |
@@ -41,6 +42,7 @@ instance = SignWell::Models::DocumentResponseFieldsInnerInner.new(
41
42
  name: null,
42
43
  date_format: null,
43
44
  fixed_width: null,
45
+ formula: null,
44
46
  label: null,
45
47
  lock_sign_date: null,
46
48
  required: null,
data/docs/FileInfo.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Name | Type | Description | Notes |
6
6
  | ---- | ---- | ----------- | ----- |
7
- | **name** | **String** | File name | |
7
+ | **name** | **String** | File name | [optional] |
8
8
  | **pages_number** | **Integer** | Number of pages in the file | |
9
9
 
10
10
  ## Example
data/docs/RegionalApi.md CHANGED
@@ -9,7 +9,7 @@ All URIs are relative to *https://www.signwell.com*
9
9
 
10
10
  ## get_nom151_certificate
11
11
 
12
- > <Nom151UrlResponse> get_nom151_certificate(id, opts)
12
+ > Models::Nom151UrlResponse, Models::Nom151CertificateResponse, or File get_nom151_certificate(id, opts)
13
13
 
14
14
  MX – NOM-151 Certificate
15
15
 
@@ -48,7 +48,7 @@ end
48
48
 
49
49
  This returns an Array which contains the response data, status code and headers.
50
50
 
51
- > <Array(<Nom151UrlResponse>, Integer, Hash)> get_nom151_certificate_with_http_info(id, opts)
51
+ > <Array(Models::Nom151UrlResponse, Models::Nom151CertificateResponse, or File, Integer, Hash)> get_nom151_certificate_with_http_info(id, opts)
52
52
 
53
53
  ```ruby
54
54
  begin
@@ -56,7 +56,7 @@ begin
56
56
  data, status_code, headers = api_instance.get_nom151_certificate_with_http_info(id, opts)
57
57
  p status_code # => 2xx
58
58
  p headers # => { ... }
59
- p data # => <Nom151UrlResponse>
59
+ p data # => Models::Nom151UrlResponse, Models::Nom151CertificateResponse, or File
60
60
  rescue SignWell::Errors::ApiError => e
61
61
  puts "Error when calling RegionalApi->get_nom151_certificate_with_http_info: #{e}"
62
62
  end
@@ -72,7 +72,7 @@ end
72
72
 
73
73
  ### Return type
74
74
 
75
- [**Nom151UrlResponse**](Nom151UrlResponse.md)
75
+ **Models::Nom151UrlResponse, Models::Nom151CertificateResponse, or File**
76
76
 
77
77
  ### Authorization
78
78
 
data/docs/TemplateApi.md CHANGED
@@ -247,7 +247,8 @@ end
247
247
  api_instance = SignWell::Resources::TemplateApi.new
248
248
  opts = {
249
249
  page: 56, # Integer |
250
- limit: 56 # Integer |
250
+ limit: 56, # Integer |
251
+ query: 'query_example' # String | Raw API filter query. Use AND between filters, for example: \"name:Classic AND status:Available\".
251
252
  }
252
253
 
253
254
  begin
@@ -283,6 +284,7 @@ end
283
284
  | ---- | ---- | ----------- | ----- |
284
285
  | **page** | **Integer** | | [optional][default to 1] |
285
286
  | **limit** | **Integer** | | [optional][default to 10] |
287
+ | **query** | **String** | Raw API filter query. Use AND between filters, for example: \&quot;name:Classic AND status:Available\&quot;. | [optional] |
286
288
 
287
289
  ### Return type
288
290
 
@@ -6,7 +6,6 @@
6
6
  | ---- | ---- | ----------- | ----- |
7
7
  | **id** | **String** | | |
8
8
  | **callback_url** | **String** | | |
9
- | **event** | **String** | | [optional] |
10
9
  | **api_application_id** | **String** | | [optional] |
11
10
 
12
11
  ## Example
@@ -17,7 +16,6 @@ require 'signwell_sdk'
17
16
  instance = SignWell::Models::WebhookResponse.new(
18
17
  id: null,
19
18
  callback_url: null,
20
- event: null,
21
19
  api_application_id: null
22
20
  )
23
21
  ```
@@ -3,9 +3,14 @@
3
3
  # Webhook Signature Validation
4
4
  #
5
5
  # When SignWell sends a webhook to your endpoint, each payload includes
6
- # a `hash` field with an HMAC-SHA256 signature. Use SignWell::Webhook.verify_event
6
+ # an `event.hash` field with an HMAC-SHA256 signature. Use SignWell::Webhook.verify_event
7
7
  # to validate the signature before processing the event.
8
8
  #
9
+ # The webhook payload has this structure:
10
+ # { "event": { "type": "...", "time": ..., "hash": "..." }, "data": { ... } }
11
+ #
12
+ # You must pass `payload['event']` (not the full payload) to verify_event.
13
+ #
9
14
  # Your webhook ID is available in the SignWell dashboard (Settings > Webhooks).
10
15
 
11
16
  require 'signwell_sdk'
@@ -13,7 +18,8 @@ require 'sinatra'
13
18
  require 'json'
14
19
 
15
20
  post '/webhooks/signwell' do
16
- event = JSON.parse(request.body.read)
21
+ payload = JSON.parse(request.body.read)
22
+ event = payload['event']
17
23
 
18
24
  unless SignWell::Webhook.verify_event(event: event, webhook_id: ENV['SIGNWELL_WEBHOOK_ID'])
19
25
  halt 401, 'Invalid signature'
@@ -21,9 +27,9 @@ post '/webhooks/signwell' do
21
27
 
22
28
  case event['type']
23
29
  when 'document_completed'
24
- puts "Document #{event.dig('data', 'id')} completed"
30
+ puts "Document #{payload.dig('data', 'id')} completed"
25
31
  when 'document_declined'
26
- puts "Document #{event.dig('data', 'id')} declined"
32
+ puts "Document #{payload.dig('data', 'id')} declined"
27
33
  end
28
34
 
29
35
  status 200