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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +14 -0
- data/README.md +592 -26
- data/exe/appnigma +8 -0
- data/lib/appnigma/actions.rb +33 -0
- data/lib/appnigma/checks.rb +13 -0
- data/lib/appnigma/client.rb +30 -13
- data/lib/appnigma/command.rb +154 -0
- data/lib/appnigma/command_files.rb +46 -0
- data/lib/appnigma/connect_fields.rb +83 -0
- data/lib/appnigma/connections.rb +72 -3
- data/lib/appnigma/constants.rb +57 -0
- data/lib/appnigma/end_customers.rb +29 -0
- data/lib/appnigma/errors.rb +44 -6
- data/lib/appnigma/features.rb +19 -0
- data/lib/appnigma/files.rb +26 -0
- data/lib/appnigma/generated/api/default_api.rb +2149 -380
- data/lib/appnigma/generated/api_client.rb +1 -1
- data/lib/appnigma/generated/api_error.rb +1 -1
- data/lib/appnigma/generated/api_model_base.rb +1 -1
- data/lib/appnigma/generated/configuration.rb +1 -1
- data/lib/appnigma/generated/models/action_entry.rb +1 -1
- data/lib/appnigma/generated/models/check_logic_input.rb +276 -0
- data/lib/appnigma/generated/models/check_logic_output.rb +193 -0
- data/lib/appnigma/generated/models/client_event.rb +309 -0
- data/lib/appnigma/generated/models/client_event_delivery.rb +306 -0
- data/lib/appnigma/generated/models/client_event_type.rb +44 -0
- data/lib/appnigma/generated/models/client_webhook.rb +346 -0
- data/lib/appnigma/generated/models/connect_end_customer_input.rb +243 -0
- data/lib/appnigma/generated/models/connect_end_customer_output.rb +294 -0
- data/lib/appnigma/generated/models/connect_field.rb +308 -0
- data/lib/appnigma/generated/models/connection_status.rb +1 -1
- data/lib/appnigma/generated/models/create_connection_link_input.rb +1 -1
- data/lib/appnigma/generated/models/create_connection_link_output.rb +1 -1
- data/lib/appnigma/generated/models/create_logic_input.rb +273 -0
- data/lib/appnigma/generated/models/create_logic_input_trigger.rb +104 -0
- data/lib/appnigma/generated/models/create_logic_input_trigger_any_of.rb +257 -0
- data/lib/appnigma/generated/models/create_logic_input_trigger_any_of1.rb +238 -0
- data/lib/appnigma/generated/models/create_logic_output.rb +230 -0
- data/lib/appnigma/generated/models/create_portal_link_input.rb +2 -18
- data/lib/appnigma/generated/models/create_portal_link_output.rb +1 -1
- data/lib/appnigma/generated/models/create_webhook_input.rb +187 -0
- data/lib/appnigma/generated/models/create_webhook_output.rb +204 -0
- data/lib/appnigma/generated/models/crm_company.rb +1 -1
- data/lib/appnigma/generated/models/crm_company_get_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_company_list_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_company_write_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_contact.rb +1 -1
- data/lib/appnigma/generated/models/crm_contact_get_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_contact_list_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_contact_write_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_create_input.rb +1 -1
- data/lib/appnigma/generated/models/crm_custom_field.rb +1 -1
- data/lib/appnigma/generated/models/crm_deal.rb +1 -1
- data/lib/appnigma/generated/models/crm_deal_create_input.rb +1 -1
- data/lib/appnigma/generated/models/crm_deal_get_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_deal_list_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_deal_write_output.rb +1 -1
- data/lib/appnigma/generated/models/crm_email.rb +1 -1
- data/lib/appnigma/generated/models/crm_get_input.rb +1 -1
- data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
- data/lib/appnigma/generated/models/crm_list_input.rb +1 -1
- data/lib/appnigma/generated/models/crm_phone.rb +1 -1
- data/lib/appnigma/generated/models/crm_update_input.rb +1 -1
- data/lib/appnigma/generated/models/delete_end_customer_input.rb +178 -0
- data/lib/appnigma/generated/models/delete_end_customer_output.rb +286 -0
- data/lib/appnigma/generated/models/delete_end_customer_output_connections_inner.rb +238 -0
- data/lib/appnigma/generated/models/delete_end_customer_output_logic_folder.rb +255 -0
- data/lib/appnigma/generated/models/delete_end_customer_output_steps_inner.rb +257 -0
- data/lib/appnigma/generated/models/delete_webhook_input.rb +189 -0
- data/lib/appnigma/generated/models/delete_webhook_output.rb +228 -0
- data/lib/appnigma/generated/models/discard_logic_input.rb +292 -0
- data/lib/appnigma/generated/models/discard_logic_output.rb +254 -0
- data/lib/appnigma/generated/models/disconnect_connection_input.rb +216 -0
- data/lib/appnigma/generated/models/disconnect_connection_output.rb +294 -0
- data/lib/appnigma/generated/models/edit_logic_input.rb +368 -0
- data/lib/appnigma/generated/models/edit_logic_output.rb +298 -0
- data/lib/appnigma/generated/models/encrypted_fields.rb +357 -0
- data/lib/appnigma/generated/models/end_customer.rb +17 -3
- data/lib/appnigma/generated/models/end_customer_connection.rb +1 -1
- data/lib/appnigma/generated/models/function_entry.rb +1 -1
- data/lib/appnigma/generated/models/function_owner.rb +1 -1
- data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
- data/lib/appnigma/generated/models/function_owner_one_of1.rb +1 -1
- data/lib/appnigma/generated/models/get_alerts_output.rb +180 -0
- data/lib/appnigma/generated/models/get_connect_key_output.rb +256 -0
- data/lib/appnigma/generated/models/get_connection_input.rb +1 -1
- data/lib/appnigma/generated/models/get_connection_output.rb +34 -7
- data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
- data/lib/appnigma/generated/models/get_logic_go_live_status_input.rb +247 -0
- data/lib/appnigma/generated/models/get_logic_go_live_status_output.rb +296 -0
- data/lib/appnigma/generated/models/get_logic_input.rb +247 -0
- data/lib/appnigma/generated/models/get_logic_output.rb +240 -0
- data/lib/appnigma/generated/models/get_logic_output_file.rb +204 -0
- data/lib/appnigma/generated/models/get_platform_input.rb +188 -0
- data/lib/appnigma/generated/models/get_platform_output.rb +326 -0
- data/lib/appnigma/generated/models/get_sync_output.rb +207 -0
- data/lib/appnigma/generated/models/go_live_logic_input.rb +316 -0
- data/lib/appnigma/generated/models/go_live_logic_output.rb +281 -0
- data/lib/appnigma/generated/models/json_value.rb +1 -1
- data/lib/appnigma/generated/models/list_actions_output.rb +1 -1
- data/lib/appnigma/generated/models/list_connections_output.rb +3 -3
- data/lib/appnigma/generated/models/list_events_input.rb +302 -0
- data/lib/appnigma/generated/models/list_events_output.rb +193 -0
- data/lib/appnigma/generated/models/list_features_output.rb +179 -0
- data/lib/appnigma/generated/models/list_features_output_features_inner.rb +229 -0
- data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
- data/lib/appnigma/generated/models/list_logic_input.rb +162 -0
- data/lib/appnigma/generated/models/list_logic_output.rb +209 -0
- data/lib/appnigma/generated/models/list_logic_runs_input.rb +275 -0
- data/lib/appnigma/generated/models/list_logic_runs_output.rb +193 -0
- data/lib/appnigma/generated/models/list_platforms_output.rb +1 -1
- data/lib/appnigma/generated/models/list_record_changes_input.rb +375 -0
- data/lib/appnigma/generated/models/list_record_changes_output.rb +193 -0
- data/lib/appnigma/generated/models/list_webhooks_output.rb +180 -0
- data/lib/appnigma/generated/models/logic_check_problem.rb +203 -0
- data/lib/appnigma/generated/models/logic_conditional.rb +3 -3
- data/lib/appnigma/generated/models/logic_draft.rb +257 -0
- data/lib/appnigma/generated/models/logic_entry.rb +441 -0
- data/lib/appnigma/generated/models/logic_entry_failure.rb +205 -0
- data/lib/appnigma/generated/models/logic_folder_problem.rb +218 -0
- data/lib/appnigma/generated/models/logic_run.rb +483 -0
- data/lib/appnigma/generated/models/logic_test_call.rb +269 -0
- data/lib/appnigma/generated/models/platform_entry.rb +63 -6
- data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +1 -1
- data/lib/appnigma/generated/models/platform_request_input.rb +1 -1
- data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
- data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
- data/lib/appnigma/generated/models/ran_as.rb +1 -1
- data/lib/appnigma/generated/models/record_change.rb +231 -0
- data/lib/appnigma/generated/models/record_change_record.rb +105 -0
- data/lib/appnigma/generated/models/run_action_input.rb +1 -1
- data/lib/appnigma/generated/models/run_action_output.rb +1 -1
- data/lib/appnigma/generated/models/run_input.rb +1 -1
- data/lib/appnigma/generated/models/run_output.rb +1 -1
- data/lib/appnigma/generated/models/sdk_error.rb +1 -1
- data/lib/appnigma/generated/models/sdk_error_error.rb +3 -3
- data/lib/appnigma/generated/models/sdk_error_error_details.rb +81 -6
- data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
- data/lib/appnigma/generated/models/set_alerts_input.rb +197 -0
- data/lib/appnigma/generated/models/set_alerts_output.rb +180 -0
- data/lib/appnigma/generated/models/set_sync_input.rb +177 -0
- data/lib/appnigma/generated/models/set_sync_output.rb +207 -0
- data/lib/appnigma/generated/models/switch_logic_off_input.rb +200 -0
- data/lib/appnigma/generated/models/switch_logic_off_output.rb +315 -0
- data/lib/appnigma/generated/models/switch_logic_on_input.rb +200 -0
- data/lib/appnigma/generated/models/switch_logic_on_output.rb +315 -0
- data/lib/appnigma/generated/models/sync_health.rb +231 -0
- data/lib/appnigma/generated/models/test_logic_input.rb +355 -0
- data/lib/appnigma/generated/models/test_logic_output.rb +418 -0
- data/lib/appnigma/generated/models/test_logic_output_error.rb +231 -0
- data/lib/appnigma/generated/models/update_logic_input.rb +359 -0
- data/lib/appnigma/generated/models/update_logic_output.rb +205 -0
- data/lib/appnigma/generated/version.rb +1 -1
- data/lib/appnigma/generated.rb +77 -1
- data/lib/appnigma/logic.rb +176 -0
- data/lib/appnigma/names.rb +4 -4
- data/lib/appnigma/platforms.rb +11 -1
- data/lib/appnigma/portal.rb +8 -5
- data/lib/appnigma/records.rb +46 -0
- data/lib/appnigma/schema_type.rb +149 -0
- data/lib/appnigma/sync.rb +30 -0
- data/lib/appnigma/types_printer.rb +154 -0
- data/lib/appnigma/verify_webhook.rb +107 -0
- data/lib/appnigma/version.rb +2 -2
- data/lib/appnigma/webhooks.rb +79 -0
- data/lib/appnigma.rb +1 -0
- 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.
|
|
98
|
-
|
|
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
|
|
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.
|
|
349
|
-
|
|
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
|
|
399
|
-
| `Appnigma::NotFoundError` | 404. No connection for that end customer on that platform, no such function,
|
|
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`,
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
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.
|
|
471
|
-
|
|
472
|
-
|
|
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
|
|
495
|
-
`Appnigma::ERROR_CODES`, `Appnigma::OBJECTS`,
|
|
496
|
-
|
|
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
|
|