appnigma-sdk 2.0.0 → 2.2.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.
Files changed (168) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +14 -0
  3. data/README.md +592 -26
  4. data/exe/appnigma +8 -0
  5. data/lib/appnigma/actions.rb +33 -0
  6. data/lib/appnigma/checks.rb +13 -0
  7. data/lib/appnigma/client.rb +30 -13
  8. data/lib/appnigma/command.rb +154 -0
  9. data/lib/appnigma/command_files.rb +46 -0
  10. data/lib/appnigma/connect_fields.rb +83 -0
  11. data/lib/appnigma/connections.rb +72 -3
  12. data/lib/appnigma/constants.rb +57 -0
  13. data/lib/appnigma/end_customers.rb +29 -0
  14. data/lib/appnigma/errors.rb +44 -6
  15. data/lib/appnigma/features.rb +19 -0
  16. data/lib/appnigma/files.rb +26 -0
  17. data/lib/appnigma/generated/api/default_api.rb +2149 -380
  18. data/lib/appnigma/generated/api_client.rb +1 -1
  19. data/lib/appnigma/generated/api_error.rb +1 -1
  20. data/lib/appnigma/generated/api_model_base.rb +1 -1
  21. data/lib/appnigma/generated/configuration.rb +1 -1
  22. data/lib/appnigma/generated/models/action_entry.rb +1 -1
  23. data/lib/appnigma/generated/models/check_logic_input.rb +276 -0
  24. data/lib/appnigma/generated/models/check_logic_output.rb +193 -0
  25. data/lib/appnigma/generated/models/client_event.rb +309 -0
  26. data/lib/appnigma/generated/models/client_event_delivery.rb +306 -0
  27. data/lib/appnigma/generated/models/client_event_type.rb +44 -0
  28. data/lib/appnigma/generated/models/client_webhook.rb +346 -0
  29. data/lib/appnigma/generated/models/connect_end_customer_input.rb +243 -0
  30. data/lib/appnigma/generated/models/connect_end_customer_output.rb +294 -0
  31. data/lib/appnigma/generated/models/connect_field.rb +308 -0
  32. data/lib/appnigma/generated/models/connection_status.rb +1 -1
  33. data/lib/appnigma/generated/models/create_connection_link_input.rb +1 -1
  34. data/lib/appnigma/generated/models/create_connection_link_output.rb +1 -1
  35. data/lib/appnigma/generated/models/create_logic_input.rb +273 -0
  36. data/lib/appnigma/generated/models/create_logic_input_trigger.rb +104 -0
  37. data/lib/appnigma/generated/models/create_logic_input_trigger_any_of.rb +257 -0
  38. data/lib/appnigma/generated/models/create_logic_input_trigger_any_of1.rb +238 -0
  39. data/lib/appnigma/generated/models/create_logic_output.rb +230 -0
  40. data/lib/appnigma/generated/models/create_portal_link_input.rb +2 -18
  41. data/lib/appnigma/generated/models/create_portal_link_output.rb +1 -1
  42. data/lib/appnigma/generated/models/create_webhook_input.rb +187 -0
  43. data/lib/appnigma/generated/models/create_webhook_output.rb +204 -0
  44. data/lib/appnigma/generated/models/crm_company.rb +1 -1
  45. data/lib/appnigma/generated/models/crm_company_get_output.rb +1 -1
  46. data/lib/appnigma/generated/models/crm_company_list_output.rb +1 -1
  47. data/lib/appnigma/generated/models/crm_company_write_output.rb +1 -1
  48. data/lib/appnigma/generated/models/crm_contact.rb +1 -1
  49. data/lib/appnigma/generated/models/crm_contact_get_output.rb +1 -1
  50. data/lib/appnigma/generated/models/crm_contact_list_output.rb +1 -1
  51. data/lib/appnigma/generated/models/crm_contact_write_output.rb +1 -1
  52. data/lib/appnigma/generated/models/crm_create_input.rb +1 -1
  53. data/lib/appnigma/generated/models/crm_custom_field.rb +1 -1
  54. data/lib/appnigma/generated/models/crm_deal.rb +1 -1
  55. data/lib/appnigma/generated/models/crm_deal_create_input.rb +1 -1
  56. data/lib/appnigma/generated/models/crm_deal_get_output.rb +1 -1
  57. data/lib/appnigma/generated/models/crm_deal_list_output.rb +1 -1
  58. data/lib/appnigma/generated/models/crm_deal_write_output.rb +1 -1
  59. data/lib/appnigma/generated/models/crm_email.rb +1 -1
  60. data/lib/appnigma/generated/models/crm_get_input.rb +1 -1
  61. data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
  62. data/lib/appnigma/generated/models/crm_list_input.rb +1 -1
  63. data/lib/appnigma/generated/models/crm_phone.rb +1 -1
  64. data/lib/appnigma/generated/models/crm_update_input.rb +1 -1
  65. data/lib/appnigma/generated/models/delete_end_customer_input.rb +178 -0
  66. data/lib/appnigma/generated/models/delete_end_customer_output.rb +286 -0
  67. data/lib/appnigma/generated/models/delete_end_customer_output_connections_inner.rb +238 -0
  68. data/lib/appnigma/generated/models/delete_end_customer_output_logic_folder.rb +255 -0
  69. data/lib/appnigma/generated/models/delete_end_customer_output_steps_inner.rb +257 -0
  70. data/lib/appnigma/generated/models/delete_webhook_input.rb +189 -0
  71. data/lib/appnigma/generated/models/delete_webhook_output.rb +228 -0
  72. data/lib/appnigma/generated/models/discard_logic_input.rb +292 -0
  73. data/lib/appnigma/generated/models/discard_logic_output.rb +254 -0
  74. data/lib/appnigma/generated/models/disconnect_connection_input.rb +216 -0
  75. data/lib/appnigma/generated/models/disconnect_connection_output.rb +294 -0
  76. data/lib/appnigma/generated/models/edit_logic_input.rb +368 -0
  77. data/lib/appnigma/generated/models/edit_logic_output.rb +298 -0
  78. data/lib/appnigma/generated/models/encrypted_fields.rb +357 -0
  79. data/lib/appnigma/generated/models/end_customer.rb +17 -3
  80. data/lib/appnigma/generated/models/end_customer_connection.rb +1 -1
  81. data/lib/appnigma/generated/models/function_entry.rb +1 -1
  82. data/lib/appnigma/generated/models/function_owner.rb +1 -1
  83. data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
  84. data/lib/appnigma/generated/models/function_owner_one_of1.rb +1 -1
  85. data/lib/appnigma/generated/models/get_alerts_output.rb +180 -0
  86. data/lib/appnigma/generated/models/get_connect_key_output.rb +256 -0
  87. data/lib/appnigma/generated/models/get_connection_input.rb +1 -1
  88. data/lib/appnigma/generated/models/get_connection_output.rb +34 -7
  89. data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
  90. data/lib/appnigma/generated/models/get_logic_go_live_status_input.rb +247 -0
  91. data/lib/appnigma/generated/models/get_logic_go_live_status_output.rb +296 -0
  92. data/lib/appnigma/generated/models/get_logic_input.rb +247 -0
  93. data/lib/appnigma/generated/models/get_logic_output.rb +240 -0
  94. data/lib/appnigma/generated/models/get_logic_output_file.rb +204 -0
  95. data/lib/appnigma/generated/models/get_platform_input.rb +188 -0
  96. data/lib/appnigma/generated/models/get_platform_output.rb +326 -0
  97. data/lib/appnigma/generated/models/get_sync_output.rb +207 -0
  98. data/lib/appnigma/generated/models/go_live_logic_input.rb +316 -0
  99. data/lib/appnigma/generated/models/go_live_logic_output.rb +281 -0
  100. data/lib/appnigma/generated/models/json_value.rb +1 -1
  101. data/lib/appnigma/generated/models/list_actions_output.rb +1 -1
  102. data/lib/appnigma/generated/models/list_connections_output.rb +3 -3
  103. data/lib/appnigma/generated/models/list_events_input.rb +302 -0
  104. data/lib/appnigma/generated/models/list_events_output.rb +193 -0
  105. data/lib/appnigma/generated/models/list_features_output.rb +179 -0
  106. data/lib/appnigma/generated/models/list_features_output_features_inner.rb +229 -0
  107. data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
  108. data/lib/appnigma/generated/models/list_logic_input.rb +162 -0
  109. data/lib/appnigma/generated/models/list_logic_output.rb +209 -0
  110. data/lib/appnigma/generated/models/list_logic_runs_input.rb +275 -0
  111. data/lib/appnigma/generated/models/list_logic_runs_output.rb +193 -0
  112. data/lib/appnigma/generated/models/list_platforms_output.rb +1 -1
  113. data/lib/appnigma/generated/models/list_record_changes_input.rb +375 -0
  114. data/lib/appnigma/generated/models/list_record_changes_output.rb +193 -0
  115. data/lib/appnigma/generated/models/list_webhooks_output.rb +180 -0
  116. data/lib/appnigma/generated/models/logic_check_problem.rb +203 -0
  117. data/lib/appnigma/generated/models/logic_conditional.rb +3 -3
  118. data/lib/appnigma/generated/models/logic_draft.rb +257 -0
  119. data/lib/appnigma/generated/models/logic_entry.rb +441 -0
  120. data/lib/appnigma/generated/models/logic_entry_failure.rb +205 -0
  121. data/lib/appnigma/generated/models/logic_folder_problem.rb +218 -0
  122. data/lib/appnigma/generated/models/logic_run.rb +483 -0
  123. data/lib/appnigma/generated/models/logic_test_call.rb +269 -0
  124. data/lib/appnigma/generated/models/platform_entry.rb +63 -6
  125. data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +1 -1
  126. data/lib/appnigma/generated/models/platform_request_input.rb +1 -1
  127. data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
  128. data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
  129. data/lib/appnigma/generated/models/ran_as.rb +1 -1
  130. data/lib/appnigma/generated/models/record_change.rb +231 -0
  131. data/lib/appnigma/generated/models/record_change_record.rb +105 -0
  132. data/lib/appnigma/generated/models/run_action_input.rb +1 -1
  133. data/lib/appnigma/generated/models/run_action_output.rb +1 -1
  134. data/lib/appnigma/generated/models/run_input.rb +1 -1
  135. data/lib/appnigma/generated/models/run_output.rb +1 -1
  136. data/lib/appnigma/generated/models/sdk_error.rb +1 -1
  137. data/lib/appnigma/generated/models/sdk_error_error.rb +3 -3
  138. data/lib/appnigma/generated/models/sdk_error_error_details.rb +81 -6
  139. data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
  140. data/lib/appnigma/generated/models/set_alerts_input.rb +197 -0
  141. data/lib/appnigma/generated/models/set_alerts_output.rb +180 -0
  142. data/lib/appnigma/generated/models/set_sync_input.rb +177 -0
  143. data/lib/appnigma/generated/models/set_sync_output.rb +207 -0
  144. data/lib/appnigma/generated/models/switch_logic_off_input.rb +200 -0
  145. data/lib/appnigma/generated/models/switch_logic_off_output.rb +315 -0
  146. data/lib/appnigma/generated/models/switch_logic_on_input.rb +200 -0
  147. data/lib/appnigma/generated/models/switch_logic_on_output.rb +315 -0
  148. data/lib/appnigma/generated/models/sync_health.rb +231 -0
  149. data/lib/appnigma/generated/models/test_logic_input.rb +355 -0
  150. data/lib/appnigma/generated/models/test_logic_output.rb +418 -0
  151. data/lib/appnigma/generated/models/test_logic_output_error.rb +231 -0
  152. data/lib/appnigma/generated/models/update_logic_input.rb +359 -0
  153. data/lib/appnigma/generated/models/update_logic_output.rb +205 -0
  154. data/lib/appnigma/generated/version.rb +1 -1
  155. data/lib/appnigma/generated.rb +77 -1
  156. data/lib/appnigma/logic.rb +176 -0
  157. data/lib/appnigma/names.rb +4 -4
  158. data/lib/appnigma/platforms.rb +11 -1
  159. data/lib/appnigma/portal.rb +8 -5
  160. data/lib/appnigma/records.rb +46 -0
  161. data/lib/appnigma/schema_type.rb +149 -0
  162. data/lib/appnigma/sync.rb +30 -0
  163. data/lib/appnigma/types_printer.rb +154 -0
  164. data/lib/appnigma/verify_webhook.rb +107 -0
  165. data/lib/appnigma/version.rb +2 -2
  166. data/lib/appnigma/webhooks.rb +79 -0
  167. data/lib/appnigma.rb +1 -0
  168. metadata +95 -3
data/README.md CHANGED
@@ -94,15 +94,78 @@ after changing HubSpot accounts. An end customer the API has never seen is an
94
94
  `logic_folder_key` is where this end customer's own functions go in your logic
95
95
  repo: `src/logic/end-customers/<logic_folder_key>/<platform>/`. It is one key
96
96
  per end customer, the same on every platform, and the Microserver page shows
97
- it next to them with a copy button. It is `nil` only for a connection made
98
- before the key existed, until Appnigma has filled it in.
97
+ it next to them with a copy button.
98
+
99
+ `sync` says how noticing changes has been going for this account (see
100
+ [sync](#noticing-changes-in-your-end-customers-accounts-sync)): `last_checked_at`,
101
+ the last read that failed as `last_failed_at` and `last_failed_code`
102
+ (`DELIVERY_FAILED` when none of your webhooks took a page of changes), and
103
+ `recovered`, true once every object read well again after a failure. It is
104
+ nil until the account has been read once.
99
105
 
100
106
  An id outside the rule below is refused before the call with
101
107
  `Appnigma::InputError`, the same refusal the server would give.
102
108
 
109
+ ### Connecting from your own form: connections.connect
110
+
111
+ Some platforms log in with details the end customer types, such as a forum
112
+ address and an API key, instead of approving on the platform's own screen.
113
+ `platforms.list` says which: their `connection_type` is `fields`, and `fields`
114
+ lists the boxes to draw. For those you can ask in your own form, and no page
115
+ of ours opens.
116
+
117
+ 1. Read the platform's `fields` from `platforms.list`. Draw one box for each:
118
+ `label` and `help_text` say what to type, `input_type` is `password` for a
119
+ secret, and `prefix`, when there is one, is shown before the box.
120
+ 2. Send what they typed with `connections.connect`, keyed by each field's
121
+ `name` exactly as `platforms.list` gives it, such as `"apiKey"`: those keys
122
+ are sent as they are, never renamed. Call it from your server, never the
123
+ browser. The SDK encrypts them before they leave your server, to a key only
124
+ Appnigma can decrypt with, so they are never readable on the way.
125
+ 3. The details are tried on the platform before the answer comes back, which
126
+ can take up to 25 seconds. It answers as `connections.get` does.
127
+
128
+ ```ruby
129
+ discourse = client.platforms.list[:platforms].find { |entry| entry[:platform] == "discourse" }
130
+ puts discourse[:connection_type], (discourse[:fields] || []).map { |field| field[:name] }.inspect
131
+
132
+ connected = client.connections.connect(
133
+ end_customer_id: "lawfirm-123",
134
+ platform: "discourse",
135
+ fields: { "host" => "forum.lawfirm.example", "username" => "system", "apiKey" => "the key they typed" }
136
+ )
137
+ puts connected[:status] # "connected"
138
+ ```
139
+
140
+ When it is refused, nothing is kept, not even a pending connection, and an
141
+ earlier connection of theirs is left as it was:
142
+
143
+ - `Appnigma::InputError` with `INVALID_INPUT`: a field is missing, is one the
144
+ platform does not ask for, or is a host that is not public. `problems` names
145
+ each field as `fields.<name>`, never its value, so you can show it by its
146
+ box. A platform whose `connection_type` is `oauth` is refused naming
147
+ `platform`; use `create_link` for it.
148
+ - `Appnigma::PlatformRefusedError` with `CONNECT_LOGIN_REJECTED`: the platform
149
+ did not accept the details. Ask them to check and type them again.
150
+ - `Appnigma::NotAvailableError` with `CONNECT_KEY_CHANGED`: we replaced the
151
+ key the details are encrypted to. The SDK reads the new one and sends once
152
+ more by itself, so you only see this if the key changed again during that
153
+ call. Send it again.
154
+ - `Appnigma::ServerError` with `PLATFORM_ERROR`: the platform could not be
155
+ reached. Try again in a minute.
156
+ - `Appnigma::ServerError` with `TIMED_OUT`: the answer took too long, and the
157
+ connection may still have been made. Read it with `connections.get` before
158
+ asking them again. Do the same when your own `timeout_ms` ends the call
159
+ first.
160
+
161
+ It is made once, never retried, and connecting again replaces their earlier
162
+ login. A connect link from `create_link` still works for these platforms: our
163
+ page asks for the same details.
164
+
103
165
  ## Listing your end customers: connections.list
104
166
 
105
- `connections.list` answers your end customers one page at a time, in id order:
167
+ `connections.list` answers your end customers one page at a time, in the order
168
+ of their `logic_folder_key`:
106
169
  each with their `end_customer_id`, their `logic_folder_key`,
107
170
  `has_custom_logic` (`true` when a function written for them is live) and every
108
171
  connection of theirs, with its `platform`, `status` and `connected_at` (ISO
@@ -110,7 +173,7 @@ connection of theirs, with its `platform`, `status` and `connected_at` (ISO
110
173
  the end customers with at least one connection that matches; each entry still
111
174
  lists all of their connections. `limit:` is 1 to 100, 50 if left out; `next`
112
175
  is `nil` on the last page, otherwise pass it back as `cursor:`, exactly as it
113
- came. It is the list to build your own integrations screen from, and the way
176
+ came: it is opaque, so never read it or build one. It is the list to build your own integrations screen from, and the way
114
177
  to find who must connect again:
115
178
 
116
179
  ```ruby
@@ -130,6 +193,55 @@ four, a `limit:` outside 1 to 100, or a `cursor:` this list did not give you
130
193
  is an `Appnigma::InputError` naming the field. An empty list is not an error.
131
194
  Reads are retried.
132
195
 
196
+ ### Disconnecting an end customer
197
+
198
+ When an end customer leaves a platform, for example they remove it from your
199
+ Integrations page, disconnect them. Their login on that platform is removed
200
+ and the connection is deleted, so `connections.get` then raises
201
+ `Appnigma::NotFoundError` with `END_CUSTOMER_NOT_FOUND`. Their other platforms
202
+ are left alone, and a new link connects them again from the start. An end customer who was sent a link and never finished is
203
+ disconnected the same way.
204
+
205
+ ```ruby
206
+ removed = client.connections.disconnect(end_customer_id: "lawfirm-123", platform: "hubspot")
207
+ puts removed[:status] # "disconnected"
208
+ ```
209
+
210
+ The answer is their id, the platform, `status` `disconnected` and their
211
+ `logic_folder_key`, which comes from their id and so is the same if they
212
+ connect again.
213
+
214
+ Disconnecting an end customer who is not connected, or disconnecting twice,
215
+ raises `Appnigma::NotFoundError` with `END_CUSTOMER_NOT_FOUND`. The call is
216
+ made once and never retried: if its answer is lost and you call again, that
217
+ `END_CUSTOMER_NOT_FOUND` means the first call worked. When the login cannot be
218
+ removed just now, it raises `Appnigma::ServerError` with `INTERNAL_ERROR`,
219
+ nothing is changed, and you can call again. The id rules above apply here too.
220
+
221
+ ### Removing an end customer: end_customers.delete
222
+
223
+ When an end customer leaves your product altogether, remove them. Every
224
+ connection of theirs goes, each login first; then their connect links,
225
+ settings, drafts, logic switches and portal links; and any portal session they
226
+ have open ends. Their folder in your logic repo is yours and is left as it is.
227
+
228
+ ```ruby
229
+ gone = client.end_customers.delete(end_customer_id: "lawfirm-123")
230
+ puts gone[:completed], gone[:logic_folder][:path]
231
+ ```
232
+
233
+ The answer says what happened to each connection, `done`, `already_gone` or
234
+ `failed` with a `detail`, and to each kind of row, `connect_links`,
235
+ `settings`, `drafts`, `switches` and `portal_links`, each `done` with a
236
+ `count`, `already_gone` or `skipped`. `logic_folder` names the folder's
237
+ `path`, with `kept` always true and a note. `completed` is false when a login
238
+ could not be removed just now, or they connected again while this ran: that
239
+ connection is `failed`, every step is `skipped`, nothing of theirs is lost,
240
+ and calling again finishes it. Calling again, or naming an end customer the
241
+ API has nothing for, answers `already_gone` everywhere, never an error. Because
242
+ a repeat is harmless, the call is tried again like a read. The id rules above
243
+ apply here too.
244
+
133
245
  ## CRM data in one shape: crm
134
246
 
135
247
  `crm.contacts`, `crm.companies` and `crm.deals` read and write an end
@@ -211,14 +323,50 @@ the shared shapes cover.
211
323
 
212
324
  ```ruby
213
325
  client.platforms.list[:platforms].each do |platform|
214
- puts "#{platform[:label]}: #{platform[:support]}"
326
+ puts "#{platform[:label]}: #{platform[:logo_url]}, #{platform[:support]}, #{platform[:connection_type]}"
215
327
  end
216
328
  ```
217
329
 
330
+ `logo_url` is the platform's logo, ready to use as an image's `src`, or `nil`
331
+ when there is none. `platforms.get` answers one platform the same way:
332
+
333
+ ```ruby
334
+ hubspot = client.platforms.get(platform: "hubspot")
335
+ ```
336
+
218
337
  `support` is `supported` when `crm` reads and writes it, with `coverage`
219
338
  naming each object and its actions, or `experimental` when only `request`
220
339
  reaches it so far.
221
340
 
341
+ `connection_type` says how an end customer connects it: `oauth`, on the
342
+ platform's own screen through a link from `connections.create_link`, with
343
+ `fields` as `[]`; or `fields`, with details they type, which `fields` lists
344
+ for your own form and `connections.connect` sends. Each field has `name`,
345
+ `label`, `input_type` (`text` or `password`), `help_text`, `required` and
346
+ `prefix`. `fields` is `nil` when we could not read them just now; ask again
347
+ in a minute.
348
+
349
+ ## Your integrations page: features
350
+
351
+ A page where your users see which integrations they can turn on, and which
352
+ they already have, is three calls from your server:
353
+
354
+ 1. `features.list` says which features are on for your company, as
355
+ `{ name:, enabled: }`, so the page can hide what is off: the calls of a
356
+ feature that is off are refused. `portal` is the custom logic portal;
357
+ `sync` is noticing changes in end customers' accounts.
358
+ 2. `platforms.list` gives each platform to show, with its `label` and
359
+ `logo_url`.
360
+ 3. `connections.list` with `status: "connected"` gives who already has which
361
+ platform.
362
+
363
+ ```ruby
364
+ features = client.features.list[:features]
365
+ portal_on = features.any? { |feature| feature[:name] == "portal" && feature[:enabled] }
366
+ platforms = client.platforms.list[:platforms]
367
+ page = client.connections.list(status: "connected")
368
+ ```
369
+
222
370
  ## Anything else on the platform: request
223
371
 
224
372
  `request` calls the end customer's platform's own API, for anything the shared
@@ -246,6 +394,42 @@ the same way, with its status, rather than as an error: check
246
394
  `answer[:status]`. A `GET` is retried like a read; any other method is made
247
395
  once, because only you know whether repeating it is harmless.
248
396
 
397
+ ## Ready-made actions on the platform: actions
398
+
399
+ Actions are ready-made jobs on the end customer's platform that we write and
400
+ keep up to date, such as reading a Gong call's transcript. `actions.list`
401
+ names every action on the platforms switched on for you, with the JSON Schema
402
+ of its `input` and `output`, passed through as written, and the `scopes` the
403
+ end customer's connection must have.
404
+
405
+ ```ruby
406
+ client.actions.list(platform: "gong")[:actions].each do |action|
407
+ puts action[:platform], action[:name], action[:description]
408
+ end
409
+ ```
410
+
411
+ `actions.run` runs one for one end customer. The input is checked against the
412
+ action's shape before it runs, so a wrong or missing field is an
413
+ `Appnigma::InputError` naming it as `input.<field>`. The answer's `output` is
414
+ in the shape the action declares, passed through as the action returned it,
415
+ with string keys.
416
+
417
+ ```ruby
418
+ output = client.actions.run(
419
+ end_customer_id: "lawfirm-123",
420
+ platform: "gong",
421
+ action: "get-call-transcript",
422
+ input: { "callId" => "7782342274025937895" }
423
+ )[:output]
424
+ output["transcript"].each { |part| puts part["speakerId"], part["sentences"] }
425
+ ```
426
+
427
+ A name the platform has no action for is an `Appnigma::NotFoundError` with
428
+ `ACTION_NOT_FOUND`. When the end customer's connection was not given a scope
429
+ the action needs, it is an `Appnigma::AuthError` with `MISSING_SCOPES`, and
430
+ `details["missing"]` names the scopes. A run is made once and never retried;
431
+ the list is retried like `catalog`.
432
+
249
433
  ## Your own functions: catalog
250
434
 
251
435
  Your microserver can also hold functions written for you.
@@ -339,14 +523,56 @@ no logic named; a write it made before it failed stays made.
339
523
  know whether running it twice is harmless. If it fails with a network or
340
524
  server error, decide in your code whether to call again.
341
525
 
526
+ ## Types for your functions
527
+
528
+ One command writes an RBS file into your project describing your functions
529
+ and the actions you can run, by platform: a record type for the input of each
530
+ and one for its output, and a union of the names on each platform. Steep and
531
+ RubyMine read it.
532
+
533
+ ```sh
534
+ bundle exec appnigma types
535
+ ```
536
+
537
+ It reads your key from `APPNIGMA_SDK_KEY`, or `--key`. It writes
538
+ `sig/appnigma_types.rbs` in the current folder, or wherever `--out` says. Run
539
+ it again whenever a function goes live. With a wrong key it says so and writes
540
+ nothing.
541
+
542
+ The file marks fields that may be left out with `?`, which needs rbs 3.5 or
543
+ newer. Ruby 3.3 ships rbs 3.4: run `gem install rbs` there first.
544
+
545
+ Use the types in your own signatures. The gem's own methods stay untyped, so
546
+ `run` and `actions.run` still accept any name and any input; the types are for
547
+ what you build and what you read back:
548
+
549
+ ```rbs
550
+ class InvoiceSync
551
+ def send_invoice: (AppnigmaTypes::hubspot_invoice_to_deal_input) -> AppnigmaTypes::hubspot_invoice_to_deal_output
552
+ end
553
+ ```
554
+
555
+ Each type is named by the platform and the function in lowercase with
556
+ underscores, and actions end in `_action_input` and `_action_output`. A field
557
+ keeps the name the function gave it, as a string key: the input is sent and
558
+ the output comes back with string keys.
559
+
342
560
  ## Your own guide
343
561
 
344
562
  One page, written for your company: install, the key, connecting an end
345
563
  customer to each platform switched on for you, reading and writing records,
346
564
  `run`, every
347
565
  one of your functions with its fields and an example call, and every error
348
- with what to do about it. `guide` answers it as markdown, built from what is
349
- live right now.
566
+ with what to do about it.
567
+
568
+ ```sh
569
+ bundle exec appnigma guide
570
+ ```
571
+
572
+ It reads your key the same way `appnigma types` does and writes
573
+ `appnigma-guide.md` in the current folder, or wherever `--out` says. Run it
574
+ again whenever a function goes live. A program can fetch the same markdown
575
+ with `guide`, built from what is live right now:
350
576
 
351
577
  ```ruby
352
578
  File.write("appnigma-guide.md", client.guide[:guide])
@@ -368,6 +594,20 @@ link = client.portal.create_link(end_customer_id: "lawfirm-123")
368
594
  puts "show it in an iframe, or open it in a new tab: #{link[:url]}"
369
595
  ```
370
596
 
597
+ An end customer must have a connection. One you disconnected from their last
598
+ platform, or never connected, raises `Appnigma::NotFoundError` with
599
+ `END_CUSTOMER_NOT_FOUND` until they connect again.
600
+
601
+ A link with no end customer is for you. It shows your own logic, which you can
602
+ start, edit and put live there, and a list of your end customers below.
603
+ Opening one shows exactly what that end customer's own link shows, and a bar
604
+ takes you back. While you have more than one end customer, every portal link,
605
+ yours or theirs, is an `Appnigma::AuthError` with `PORTAL_NOT_AVAILABLE`.
606
+
607
+ ```ruby
608
+ yours = client.portal.create_link
609
+ ```
610
+
371
611
  Show the link's `url` in an iframe on one of your sites, or open it in a new
372
612
  tab. Only the sites on your company's list can show it in an iframe; write to
373
613
  support@appnigma.ai to add yours. A session lasts an hour. When the link was
@@ -384,6 +624,323 @@ window.addEventListener("message", (event) => {
384
624
  });
385
625
  ```
386
626
 
627
+ ## Your own logic screen: logic
628
+
629
+ Build a page in your product where logic is listed, opened, changed, checked,
630
+ tried and put live. Changes are drafts kept on our side: nothing reaches your repo
631
+ until `go_live`. Without `end_customer_id:`, or with `nil`,
632
+ each call is about your own logic; with an id, that end customer's. `list` is
633
+ the one exception: given nothing, it lists yours and every end customer's.
634
+
635
+ ```ruby
636
+ # Your logic and every end customer's: whose each is, whether it is on, and where it stands.
637
+ listed = client.logic.list
638
+ listed[:logic].each do |entry|
639
+ puts [entry[:owner], entry[:end_customer_id], entry[:platform], entry[:name], entry[:status], entry[:on]].join(" ")
640
+ end
641
+ # An end customer whose whole folder their last go-live kept back, and why:
642
+ # what is live of theirs is the version before, not what is on main.
643
+ listed[:folder_problems].each { |kept| puts [kept[:end_customer_id], kept[:reason]].join(" ") }
644
+
645
+ # One logic: its file on main and the draft we keep of it.
646
+ opened = client.logic.get(platform: "hubspot", name: "round-deal-amount")
647
+
648
+ # Save the whole file, on the revision it was opened at: the draft's, or 0
649
+ # for the first change to a file on main, with that file's sha.
650
+ saved = client.logic.update(
651
+ platform: "hubspot",
652
+ name: "round-deal-amount",
653
+ source: editor_text,
654
+ revision: opened[:draft] ? opened[:draft][:revision] : 0,
655
+ base_sha: opened[:draft] ? nil : opened[:file][:sha]
656
+ )
657
+
658
+ # The check going live runs first, by line and column. Without source, the saved draft.
659
+ client.logic.check(platform: "hubspot", name: "round-deal-amount")[:problems].each do |problem|
660
+ puts "#{problem[:line]}:#{problem[:column]} #{problem[:message]}"
661
+ end
662
+ ```
663
+
664
+ Start a new one from our template, around a read or a write of a `crm`
665
+ object, or around an action (`{ action: "get-call-transcript", timing: "after" }`).
666
+ It stays a draft until it goes live. Discard a draft on the revision you last
667
+ had: a file on main goes back to what main holds, and a new logic is gone.
668
+
669
+ ```ruby
670
+ created = client.logic.create(
671
+ platform: "hubspot",
672
+ name: "tag-new-deals",
673
+ trigger: { object: "deal", operation: "write", timing: "before" }
674
+ )
675
+ client.logic.discard(platform: "hubspot", name: "tag-new-deals", revision: created[:draft][:revision])
676
+ ```
677
+
678
+ A save or a discard on an older revision is refused with `DRAFT_CHANGED`, and
679
+ nothing is written over: `error.draft` is the draft now, or `nil` if it was
680
+ discarded. Show it, and save again on its revision.
681
+
682
+ ```ruby
683
+ begin
684
+ client.logic.update(platform: "hubspot", name: "round-deal-amount", source: editor_text, revision: revision)
685
+ rescue Appnigma::NotAvailableError => e
686
+ raise unless e.code == "DRAFT_CHANGED"
687
+
688
+ show_newer(e.draft)
689
+ end
690
+ ```
691
+
692
+ Reading, checking and trying an end customer's logic always work. Changing it
693
+ needs the custom logic portal switched on for you, and only one end customer:
694
+ with more, `create`, `update`, `edit`, `discard` and `go_live` for an end
695
+ customer are an `Appnigma::AuthError` with `END_CUSTOMER_LOGIC_NOT_AVAILABLE`.
696
+ Your own logic can still be changed.
697
+
698
+ ### Asking for a change, and trying it
699
+
700
+ `edit` takes what to change in plain words and writes it, from the draft or,
701
+ when there is none, from the file on main. The new file is saved as the draft
702
+ only when it passes the check; it never goes live, that is still `go_live`.
703
+ When it fails the check nothing is saved, and the answer has `saved` false,
704
+ the `problems` by line and column, and the file that was written as
705
+ `rejected_source`. Send `revision:` to change only the draft you last had, and
706
+ `requested_by:` to keep who asked on the call's record. Each prompt is on its
707
+ own: nothing remembers an earlier one.
708
+
709
+ ```ruby
710
+ edited = client.logic.edit(
711
+ platform: "hubspot",
712
+ name: "round-deal-amount",
713
+ prompt: "Round the amount to the nearest 10",
714
+ requested_by: current_user.email
715
+ )
716
+ if edited[:saved]
717
+ puts edited[:summary], edited[:draft][:revision]
718
+ else
719
+ edited[:problems].each { |problem| puts problem[:line], problem[:message] }
720
+ end
721
+ ```
722
+
723
+ `test` runs it once on the `input:` you send, in a sandbox with no internet:
724
+ the `source:` you send, else the draft, else the file on main (`ran_on` says
725
+ which). It sees only the `settings:` you send, never an end customer's. Every
726
+ call it makes through `hubspot`, `http` or `fetch` is listed in `calls` and
727
+ answered empty, so no end customer's data is read or changed. `output` is what
728
+ it answered, or `error` how it failed, as a live call would; `ran` false with
729
+ `problems` when the file failed the check, and `finished` false with `logs`
730
+ when it gave no answer. A file that imports another file of your repo cannot
731
+ be tried on its own. When every test machine is busy, it is an
732
+ `Appnigma::RateLimitError` with `RATE_LIMITED` and the seconds to wait.
733
+
734
+ ```ruby
735
+ tried = client.logic.test(platform: "hubspot", name: "round-deal-amount", input: { "amount" => 1234.56 })
736
+ p tried[:error] || tried[:output], tried[:calls]
737
+ ```
738
+
739
+ ### Putting it live
740
+
741
+ `go_live` checks the draft at the revision you last had, commits it to your
742
+ repo's main branch through our GitHub app, and starts the go-live a push gets.
743
+ It answers once committed, with `state` `"checking"`, and is made once: the
744
+ client never repeats it. Follow it with `go_live_status`: `checking`, `live`
745
+ with the version now live, `failed` with `reason` and `still_live`, or `none`.
746
+ The first read that sees it live settles it, and `logic.list` reads too, so a
747
+ poll can go from `checking` to `none`; `none` carries the version and
748
+ `logic_id` live now, so compare the version with the one before.
749
+
750
+ ```ruby
751
+ going = client.logic.go_live(platform: "hubspot", name: "round-deal-amount", revision: saved[:revision])
752
+ status = client.logic.go_live_status(platform: "hubspot", name: "round-deal-amount")
753
+ puts status[:reason], status[:still_live] if status[:state] == "failed"
754
+ ```
755
+
756
+ When it does not go live:
757
+
758
+ - `FILE_CHANGED`, an `Appnigma::NotAvailableError`: the file on main changed
759
+ since the draft began. Open it again and save on top, or send
760
+ `replace_latest: true` to put yours live over it.
761
+ - `SETTINGS_MISSING`, an `Appnigma::NotAvailableError`: an end customer's
762
+ logic reads settings they have not set, named in `e.details["names"]`. Send
763
+ `ignore_missing_settings: true` to put it live anyway.
764
+ - `NOTHING_TO_GO_LIVE`, an `Appnigma::NotAvailableError`: there is no draft.
765
+ - `LOGIC_CHECK_FAILED`, an `Appnigma::PlatformRefusedError`: the draft would
766
+ not pass the checks; `e.details["checkProblems"]` lists them by line, as
767
+ `check` does.
768
+ - `REPO_ACCESS_REFUSED`, an `Appnigma::AuthError`: our GitHub app may not push
769
+ to your repo's main branch. Not retried: check its access.
770
+
771
+ ### Switches and runs
772
+
773
+ Switch an always-on logic off, for one end customer or, without
774
+ `end_customer_id:`, for everyone, by the `logic_id` `logic.list` gives it.
775
+ Nothing is pushed: the next call reads the switch. `switch_on` takes it away.
776
+ Everyone's switch and an end customer's are separate, so switching one end
777
+ customer on while everyone's is off answers `runs` `false` with `reason`
778
+ `"switched_off_for_everyone"`. A logic that is not always-on is an
779
+ `Appnigma::NotAvailableError` with `LOGIC_NOT_ALWAYS_ON`. Switches work
780
+ however many end customers you have.
781
+
782
+ `runs` lists what an always-on logic did on each call, newest first: ids and
783
+ codes only, never the call's data or a message. Pass `next_cursor` back as
784
+ `cursor:` for the next page; it is `nil` on the last.
785
+
786
+ ```ruby
787
+ rounding = listed[:logic].find { |entry| entry[:always_on] }
788
+ client.logic.switch_off(logic_id: rounding[:logic_id], end_customer_id: "lawfirm-123")
789
+ client.logic.switch_on(logic_id: rounding[:logic_id], end_customer_id: "lawfirm-123")
790
+
791
+ page = client.logic.runs(logic_id: rounding[:logic_id], limit: 10)
792
+ page[:runs].each { |run| puts run.values_at(:ran_at, :end_customer_id, :outcome, :error_code).join(" ") }
793
+ ```
794
+
795
+ ## Hearing what happened: webhooks, events and alerts
796
+
797
+ Appnigma can tell your server when something happens, so you do not learn
798
+ of it from the next call that fails. Five things are told: an end customer's
799
+ connection dropped (`connection.dropped`) or came back
800
+ (`connection.restored`), a change went live (`go_live.finished`) or did not
801
+ (`go_live.failed`), and always-on logic failed (`logic.failed`). Each event
802
+ holds ids and codes only, never a record or a message. A sixth type,
803
+ `records.changed`, carries the records the sync noticed changed; the sync
804
+ section below says how it differs.
805
+
806
+ Give up to five `https://` addresses on the public internet. The `secret`
807
+ comes back once, in this answer, and never again, so keep it where your
808
+ server can read it:
809
+
810
+ ```ruby
811
+ made = client.webhooks.create(url: "https://api.acme.example/appnigma/events")
812
+ puts "store this: #{made[:secret]} and this id: #{made[:webhook][:webhook_id]}"
813
+ ```
814
+
815
+ Each event is a POST of JSON `{ id, type, createdAt, data }` with two
816
+ headers: `Appnigma-Event-Id`, the event's id, and `Appnigma-Signature`,
817
+ `t=<unix seconds>,v1=<hex>`. `Appnigma.verify_webhook` checks the signature
818
+ on the body exactly as it arrived, before anything parses it, refuses one
819
+ more than 300 seconds old, and hands back the event with its keys in Ruby
820
+ style. It raises `Appnigma::WebhookSignatureError` when the message is not
821
+ from us:
822
+
823
+ ```ruby
824
+ require "sinatra"
825
+ require "appnigma"
826
+
827
+ post "/appnigma/events" do
828
+ event = Appnigma.verify_webhook(request.body.read, request.env["HTTP_APPNIGMA_SIGNATURE"],
829
+ ENV.fetch("APPNIGMA_WEBHOOK_SECRET"))
830
+ if event[:type] == "connection.dropped"
831
+ puts "#{event[:data][:end_customer_id]} must connect again on #{event[:data][:platform]}"
832
+ end
833
+ 204
834
+ rescue Appnigma::WebhookSignatureError
835
+ 400
836
+ end
837
+ ```
838
+
839
+ The same event can arrive twice, so drop an `id` you have already handled.
840
+ Answer 2xx within 10 seconds and do slow work after answering; anything else
841
+ is tried again, 10 tries over about 8 hours. A webhook whose every send
842
+ failed for 3 days is switched off: `client.webhooks.list` shows it with
843
+ `state` `"switched_off"`. Delete it with
844
+ `client.webhooks.delete(webhook_id: ...)` and create it again to start over,
845
+ which gives it a new secret. An address that is not `https://`, holds a user
846
+ name or password, or resolves to a private network is an
847
+ `Appnigma::InputError` with `WEBHOOK_ADDRESS_REFUSED`, and
848
+ `details["reason"]` says which; a sixth webhook is `WEBHOOK_LIMIT_REACHED`,
849
+ and the same address twice `WEBHOOK_EXISTS`.
850
+
851
+ Every event but `records.changed` is also kept for 30 days for you to read,
852
+ newest first, each with how it went at every webhook. Give `type:` or `since:` to narrow it, and pass
853
+ `next_cursor` back as `cursor:` for the next page:
854
+
855
+ ```ruby
856
+ page = client.events.list(type: "connection.dropped")
857
+ page[:events].each do |event|
858
+ puts "#{event[:created_at]} #{event[:data]} #{event[:deliveries].map { |delivery| delivery[:state] }}"
859
+ end
860
+ ```
861
+
862
+ Alerts choose which types are sent to your webhooks. Every type is sent until
863
+ you choose; `events.list` keeps every type but `records.changed` either way. `alerts.set` replaces
864
+ the list, and an empty list sends nothing:
865
+
866
+ ```ruby
867
+ client.alerts.set(events: %w[connection.dropped go_live.failed logic.failed])
868
+ puts client.alerts.get[:events]
869
+ ```
870
+
871
+ ## Noticing changes in your end customers' accounts: sync
872
+
873
+ Switch it on and every 5 minutes Appnigma asks each connected HubSpot and
874
+ Pipedrive account for the contacts, companies and deals changed since it
875
+ last asked, from the moment it is first read. Records your own `crm.*`
876
+ writes changed are left out, so you never hear your own changes back. No
877
+ record is kept, only how far each account has been read. Each read counts
878
+ against that end customer's own API limits, and an account that asks us to
879
+ slow down is left alone until it says we may go on.
880
+
881
+ ```ruby
882
+ sync = client.sync.set(on: true)
883
+ puts sync[:on], sync[:platforms]
884
+ puts client.sync.get[:platforms]
885
+ ```
886
+
887
+ `sync.get` reads the switch and lists the platforms it covers; a platform not
888
+ listed has no way to ask for changes by time. Off stops the reading; on again
889
+ carries on from where it stopped. While the feature is not switched on for
890
+ your company, `features.list` shows `sync` off and `sync.set(on: true)` is an
891
+ `Appnigma::AuthError` with `SYNC_NOT_ENABLED`; switching off is never refused.
892
+
893
+ ### Taking the changes: records.changed
894
+
895
+ What the sync notices is posted to your webhooks as `records.changed`, signed
896
+ like every event: one post per page of up to 100 changes of one object for
897
+ one end customer. `Appnigma.verify_webhook` hands back `data` with
898
+ `end_customer_id`, `platform`, `object` and `changes`, each change
899
+ `record_id`, `updated_at` and `record`, the record in Ruby names as `crm.*`
900
+ answers it. Answer 2xx from any one webhook and that page is done. When none
901
+ does, nothing is kept: the next run reads those records from the platform
902
+ again and posts them again, so a change made while your server was down
903
+ still arrives once it is back. Alerts switch the type off like any other,
904
+ and it is never in `events.list`, because no record is ever kept.
905
+
906
+ ```ruby
907
+ if event[:type] == "records.changed"
908
+ event[:data][:changes].each do |change|
909
+ puts "#{event[:data][:object]} #{change[:record_id]} #{change[:updated_at]}"
910
+ end
911
+ end
912
+ ```
913
+
914
+ A change can arrive more than once. Drop one whose `record_id` and
915
+ `updated_at` you have already applied, and apply one only when its
916
+ `updated_at` is newer than what you hold: fields are never merged, so the
917
+ newest state of the record wins, and a later write of yours stays yours.
918
+ Your own `crm.*` writes never come back. Always-on logic with
919
+ `{ object, operation: "change", timing: "after" }` runs on each change before
920
+ it is sent; a change it failed on is left out, once, and `logic.failed` says so.
921
+
922
+ ### Asking for the changes: records.changes
923
+
924
+ The same changes, read from one account since a time you keep, a page at a
925
+ time, whether the switch is on or off. Keep `since:` yourself and move it to
926
+ the latest `updated_at` you applied; pass `next_cursor` back as `cursor:`
927
+ with the same `since:`. `object:` is `contact`, `company` or `deal`, and
928
+ `since:` is ISO 8601 with a time zone. A read, so it is retried.
929
+ Your own `crm.*` writes are left out for 7 days after you make them, so a
930
+ `since` further back can answer some of them.
931
+
932
+ ```ruby
933
+ page = client.records.changes(end_customer_id: "lawfirm-123", platform: "hubspot", object: "deal",
934
+ since: "2026-11-11T09:00:00Z")
935
+ page[:changes].each do |change|
936
+ puts "#{change[:record_id]} #{change[:updated_at]} #{change[:record][:amount]}"
937
+ end
938
+ ```
939
+
940
+ A platform that cannot list changes by time, such as `attio`, is an
941
+ `Appnigma::InputError` naming `platform`; the feature off for your company is
942
+ an `Appnigma::AuthError` with `SYNC_NOT_ENABLED`.
943
+
387
944
  ## Telling failures apart
388
945
 
389
946
  Every failure is an exception you can rescue by class. All of them inherit
@@ -394,16 +951,17 @@ your key or a token.
394
951
 
395
952
  | Class | When | Extra field |
396
953
  | --- | --- | --- |
397
- | `Appnigma::InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting, a bad end customer id, or a `run` given both `function_name` and `function_id` or neither, before any call. | `problems`, a list of `{ field:, problem: }` |
398
- | `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, the platform or the custom logic portal is not switched on for you (`PLATFORM_NOT_ENABLED`, `PORTAL_NOT_ENABLED`), or the end customer's connection lacks a scope a write needs (`MISSING_SCOPES`, with `details["missing"]`). Also raised at start with no key. | |
399
- | `Appnigma::NotFoundError` | 404. No connection for that end customer on that platform, no such function, or no such record (`RECORD_NOT_FOUND`). When the function exists on another platform, `details["platforms"]` names it. | |
954
+ | `Appnigma::InputError` | 400. A field is wrong or missing. Also 422 with `WEBHOOK_ADDRESS_REFUSED`: an address `webhooks.create` will not send to, with `details["reason"]`. Also raised locally for a bad setting, a bad end customer id, or a `run` given both `function_name` and `function_id` or neither, before any call. | `problems`, a list of `{ field:, problem: }` |
955
+ | `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, the platform, the custom logic portal or the sync is not switched on for you (`PLATFORM_NOT_ENABLED`, `PORTAL_NOT_ENABLED`, `SYNC_NOT_ENABLED`), no portal link while you have more than one end customer (`PORTAL_NOT_AVAILABLE`), the end customer's connection lacks a scope a write or an action needs (`MISSING_SCOPES`, with `details["missing"]`), or an end customer's logic cannot be changed while you have more than one (`END_CUSTOMER_LOGIC_NOT_AVAILABLE`), or our GitHub app may not push to your logic repo (`REPO_ACCESS_REFUSED`). Also raised at start with no key. | |
956
+ | `Appnigma::NotFoundError` | 404. No connection for that end customer on that platform, no such function, no such action (`ACTION_NOT_FOUND`), no such record (`RECORD_NOT_FOUND`), no such logic (`LOGIC_NOT_FOUND`), or no such webhook of yours (`WEBHOOK_NOT_FOUND`). When the function exists on another platform, `details["platforms"]` names it. | |
400
957
  | `Appnigma::ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
401
- | `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
958
+ | `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. Or a logic draft was saved since your revision (`DRAFT_CHANGED`), the name is taken (`LOGIC_NAME_TAKEN`), there are too many drafts (`TOO_MANY_DRAFTS`), or the end customer has not connected that platform (`PLATFORM_NOT_CONNECTED`). Or a go-live found no draft (`NOTHING_TO_GO_LIVE`), a file changed on main (`FILE_CHANGED`) or settings not set (`SETTINGS_MISSING`, with `details["names"]`), or a switch named logic that is not always-on (`LOGIC_NOT_ALWAYS_ON`). Or the key `connections.connect` encrypted to was replaced twice during the call (`CONNECT_KEY_CHANGED`). Or you have five webhooks already (`WEBHOOK_LIMIT_REACHED`), or one at that address (`WEBHOOK_EXISTS`, with `details["webhookId"]`). | `draft`, with `DRAFT_CHANGED`: the draft now, or `nil` |
402
959
  | `Appnigma::RetiredError` | 410 with `FUNCTION_RETIRED`. The function was live and was removed from your logic; it will not answer again. | |
403
- | `Appnigma::PlatformRefusedError` | 422 with `PLATFORM_REFUSED`. The end customer's platform refused the call; `message` is its reason. Never retried: fix what you sent. | `platform_status`, the status the platform answered, or `nil` |
960
+ | `Appnigma::PlatformRefusedError` | 422 with `PLATFORM_REFUSED`. The end customer's platform refused the call; `message` is its reason. Also 422 with `CONNECT_LOGIN_REJECTED`: the platform did not accept the details sent to `connections.connect`. Also 422 with `LOGIC_CHECK_FAILED`: a draft `go_live` sent would not pass the checks, listed in `details["checkProblems"]`. Never retried: fix what you sent. | `platform_status`, the status the platform answered, or `nil` |
404
961
  | `Appnigma::LogicFailedError` | 422 with `LOGIC_FAILED`. One of your functions, or always-on logic around the call, failed. Always-on logic before a `crm.*` call or an action stops it, so nothing was written or returned, and `message` names the logic and its id; a function called with `run` may have written before it failed, and `message` is what it threw. Never retried: the same call fails the same way until the logic changes. | `logic_ids`, the ids of the always-on logic the server named; empty on `run` |
405
962
  | `Appnigma::RateLimitError` | 429, after the retries. Too many calls, or the platform asked us to slow down. | `retry_after_seconds`, or `nil` when the server named no wait |
406
963
  | `Appnigma::ServerError` | Any 5xx, after the retries. Also any answer that is not JSON. | |
964
+ | `Appnigma::WebhookSignatureError` | Raised by `Appnigma.verify_webhook`, never by a call, with `WEBHOOK_SIGNATURE_INVALID`: the header is missing or malformed, the signature is too old, or it does not match the body and secret. Answer 400. | `reason`: `missing_header`, `malformed_header`, `too_old`, `mismatch`, `body_not_raw`, `missing_secret` or `not_an_event` |
407
965
  | `Appnigma::NetworkError` | The API could not be reached, or an attempt ran out of time, after the retries. `status` and `request_id` are `nil`. | `cause`, the underlying exception |
408
966
 
409
967
  ```ruby
@@ -451,14 +1009,20 @@ reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409, 410
451
1009
  or 422 is never retried, because the same call would be refused the same way.
452
1010
  By default a call is made up to three times.
453
1011
 
454
- `connections.create_link`, `portal.create_link`, `run`, `request` with a
455
- method other than `GET`, and a `crm` create with nothing to match on are the
456
- exceptions: each is made once, never retried. Every call to
457
- `create_link` makes a new link, and a repeat after a lost answer would leave a
458
- working link nobody saw; `run` is your own function, and whether a repeat is
459
- harmless is yours to know; a create with nothing to match on could make a
460
- second record. If one of them fails, decide in your code whether to call
461
- again.
1012
+ `connections.create_link`, `connections.connect`, `connections.disconnect`, `portal.create_link`, `run`,
1013
+ `webhooks.create`, `webhooks.delete`,
1014
+ `actions.run`, `request` with a method other than `GET`, a `crm` create
1015
+ with nothing to match on, and `logic.create`, `logic.update`, `logic.discard`,
1016
+ `logic.check`, `logic.go_live`, `logic.edit` and `logic.test` are the exceptions: each is made once, never retried.
1017
+ Every call to `create_link` makes a new link, and a repeat after a lost answer
1018
+ would leave a working link nobody saw; `run` is your own function, and whether
1019
+ a repeat is harmless is yours to know; an action may change the platform; a
1020
+ create with nothing to match on could make a second record; a logic save sent again after a lost answer would
1021
+ clash with its own first attempt, and a go-live sent again would hide a real
1022
+ clash behind its own commit; an edit sent again would change the draft twice,
1023
+ and a test sent again takes a second test machine; a webhook created again
1024
+ would find its own address taken and its secret gone. If one of them fails,
1025
+ decide in your code whether to call again.
462
1026
 
463
1027
  The wait between tries is what the `Retry-After` header says when the server
464
1028
  sent one, otherwise half a second and then a second, with a little random
@@ -467,9 +1031,10 @@ longer than `max_retry_wait_ms` is not waited for: the call fails at once with
467
1031
  an `Appnigma::RateLimitError` that carries the wait, so your code decides what
468
1032
  to do with half a minute rather than sitting through it.
469
1033
 
470
- Every attempt has a time limit, 30 seconds by default. An attempt that runs out
471
- of time counts as a network failure and is retried like one. Each call can set
472
- its own limit:
1034
+ Every attempt has a time limit, 30 seconds by default; `logic.edit` and
1035
+ `logic.test` wait three minutes, or the client's limit if it is longer. An
1036
+ attempt that runs out of time counts as a network failure and is retried like
1037
+ one. Each call can set its own limit:
473
1038
 
474
1039
  ```ruby
475
1040
  page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "hubspot", limit: 1, timeout_ms: 10_000)
@@ -491,9 +1056,10 @@ Per call, as a keyword argument: `timeout_ms:`.
491
1056
 
492
1057
  ## What is exported
493
1058
 
494
- `Appnigma::Client`, `Appnigma::Error` and its ten subclasses, the constants
495
- `Appnigma::ERROR_CODES`, `Appnigma::OBJECTS`, `Appnigma::CONNECTION_STATUSES`
496
- and `Appnigma::PLATFORM_REQUEST_METHODS`, `Appnigma::VERSION`, and
1059
+ `Appnigma::Client`, `Appnigma.verify_webhook`, `Appnigma::Error` and its
1060
+ twelve subclasses, the constants `Appnigma::ERROR_CODES`, `Appnigma::OBJECTS`,
1061
+ `Appnigma::CONNECTION_STATUSES`, `Appnigma::PLATFORM_REQUEST_METHODS` and
1062
+ `Appnigma::CLIENT_EVENT_TYPES`, `Appnigma::VERSION`, and
497
1063
  `Appnigma::API_DESCRIPTION_VERSION`, the version of the published description
498
1064
  of the API that this version of the gem was generated from.
499
1065