appnigma-sdk 1.0.0 → 2.1.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 (77) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +21 -0
  3. data/README.md +172 -35
  4. data/lib/appnigma/checks.rb +29 -5
  5. data/lib/appnigma/client.rb +20 -12
  6. data/lib/appnigma/connections.rb +41 -5
  7. data/lib/appnigma/constants.rb +14 -8
  8. data/lib/appnigma/errors.rb +31 -5
  9. data/lib/appnigma/generated/api/default_api.rb +321 -20
  10. data/lib/appnigma/generated/api_client.rb +1 -1
  11. data/lib/appnigma/generated/api_error.rb +1 -1
  12. data/lib/appnigma/generated/api_model_base.rb +1 -1
  13. data/lib/appnigma/generated/configuration.rb +1 -1
  14. data/lib/appnigma/generated/models/action_entry.rb +1 -1
  15. data/lib/appnigma/generated/models/connection_status.rb +3 -2
  16. data/lib/appnigma/generated/models/create_connection_link_input.rb +2 -13
  17. data/lib/appnigma/generated/models/create_connection_link_output.rb +1 -1
  18. data/lib/appnigma/generated/models/create_portal_link_input.rb +177 -0
  19. data/lib/appnigma/generated/models/create_portal_link_output.rb +205 -0
  20. data/lib/appnigma/generated/models/crm_company.rb +1 -1
  21. data/lib/appnigma/generated/models/crm_company_get_output.rb +1 -1
  22. data/lib/appnigma/generated/models/crm_company_list_output.rb +1 -1
  23. data/lib/appnigma/generated/models/crm_company_write_output.rb +1 -1
  24. data/lib/appnigma/generated/models/crm_contact.rb +1 -1
  25. data/lib/appnigma/generated/models/crm_contact_get_output.rb +1 -1
  26. data/lib/appnigma/generated/models/crm_contact_list_output.rb +1 -1
  27. data/lib/appnigma/generated/models/crm_contact_write_output.rb +1 -1
  28. data/lib/appnigma/generated/models/crm_create_input.rb +2 -13
  29. data/lib/appnigma/generated/models/crm_custom_field.rb +1 -1
  30. data/lib/appnigma/generated/models/crm_deal.rb +1 -1
  31. data/lib/appnigma/generated/models/crm_deal_create_input.rb +2 -13
  32. data/lib/appnigma/generated/models/crm_deal_get_output.rb +1 -1
  33. data/lib/appnigma/generated/models/crm_deal_list_output.rb +1 -1
  34. data/lib/appnigma/generated/models/crm_deal_write_output.rb +1 -1
  35. data/lib/appnigma/generated/models/crm_email.rb +1 -1
  36. data/lib/appnigma/generated/models/crm_get_input.rb +2 -13
  37. data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
  38. data/lib/appnigma/generated/models/crm_list_input.rb +2 -13
  39. data/lib/appnigma/generated/models/crm_phone.rb +1 -1
  40. data/lib/appnigma/generated/models/crm_update_input.rb +2 -13
  41. data/lib/appnigma/generated/models/disconnect_connection_input.rb +216 -0
  42. data/lib/appnigma/generated/models/disconnect_connection_output.rb +281 -0
  43. data/lib/appnigma/generated/models/end_customer.rb +247 -0
  44. data/lib/appnigma/generated/models/end_customer_connection.rb +239 -0
  45. data/lib/appnigma/generated/models/function_entry.rb +74 -5
  46. data/lib/appnigma/generated/models/function_owner.rb +1 -1
  47. data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
  48. data/lib/appnigma/generated/models/function_owner_one_of1.rb +18 -17
  49. data/lib/appnigma/generated/models/get_connection_input.rb +216 -0
  50. data/lib/appnigma/generated/models/get_connection_output.rb +18 -5
  51. data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
  52. data/lib/appnigma/generated/models/json_value.rb +1 -1
  53. data/lib/appnigma/generated/models/list_actions_output.rb +1 -1
  54. data/lib/appnigma/generated/models/list_connections_output.rb +193 -0
  55. data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
  56. data/lib/appnigma/generated/models/list_platforms_output.rb +1 -1
  57. data/lib/appnigma/generated/models/logic_conditional.rb +247 -0
  58. data/lib/appnigma/generated/models/platform_entry.rb +1 -1
  59. data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +1 -1
  60. data/lib/appnigma/generated/models/platform_request_input.rb +2 -13
  61. data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
  62. data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
  63. data/lib/appnigma/generated/models/ran_as.rb +1 -1
  64. data/lib/appnigma/generated/models/run_action_input.rb +2 -13
  65. data/lib/appnigma/generated/models/run_action_output.rb +1 -1
  66. data/lib/appnigma/generated/models/run_input.rb +37 -24
  67. data/lib/appnigma/generated/models/run_output.rb +1 -1
  68. data/lib/appnigma/generated/models/sdk_error.rb +1 -1
  69. data/lib/appnigma/generated/models/sdk_error_error.rb +3 -3
  70. data/lib/appnigma/generated/models/sdk_error_error_details.rb +12 -3
  71. data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
  72. data/lib/appnigma/generated/version.rb +1 -1
  73. data/lib/appnigma/generated.rb +10 -1
  74. data/lib/appnigma/portal.rb +21 -0
  75. data/lib/appnigma/transport.rb +4 -4
  76. data/lib/appnigma/version.rb +2 -2
  77. metadata +11 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dcfba5cb315befdc793a14a4d2c51f906ff53c158df45fb8efac0d81a68fe5fb
4
- data.tar.gz: 275e4997aebeca6e3ad53d8f082b30d71ac7823eec327c0de4980b91d9232752
3
+ metadata.gz: 29ce20f9b3c34290aaa8a7b272d70f2602b59159a3e0c145a22d89ad194fe227
4
+ data.tar.gz: 6a52f3f9fce3ee1e01d6d14e080614d9ab40f8389c8d28cb79dd34039825ad66
5
5
  SHA512:
6
- metadata.gz: c93b5f5778a9fe7a74e979c1f834c4798ccfc9363f2ad1152df67713cfc26a4ce9b42304153bbf8292b8ddabae16d04f96cf7859591d16aba08adbe5347e99b8
7
- data.tar.gz: b52eb1c088777116383c6ed41faac540190f21a32542f0402add3cbe4c56e913486927567024316c4b4d4957ced96df862d60cd6298679d22800bd73487f51fc
6
+ metadata.gz: 7f2f4605cf9948fb94f668b7816be2ebb0beed17b636b6b592e2c77654091a4a6f9e2b312cd860edf1b0f0ce117c404b7a48932d54718ed2a555d73591d3f033
7
+ data.tar.gz: e88ba3f06238f6631a647cf2dffb771488ab1007f0ad378cb2415292368873afe64778ff3389bb72b14c6c56e24487b6c17dc6313dad3c6c23a10a8049616a21
data/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.1.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v2.0.0...ruby-v2.1.0) (2026-11-03)
4
+
5
+
6
+ ### Features
7
+
8
+ * connections.disconnect removes an end customer's connection ([#34](https://github.com/Appnigma/ap-sdks/issues/34)) ([2aaf027](https://github.com/Appnigma/ap-sdks/commit/2aaf027b6667407dcf49747171f882ee9fc1603f))
9
+
10
+ ## [2.0.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v1.0.0...ruby-v2.0.0) (2026-11-01)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * a failed logic run answers LOGIC_FAILED with status 422 and its own error class, instead of 500
16
+
17
+ ### Features
18
+
19
+ * a failed logic run answers LOGIC_FAILED with status 422 and its own error class, instead of 500 ([912c788](https://github.com/Appnigma/ap-sdks/commit/912c7881c165e87933aa030e914468722f1af9fc))
20
+ * end customer ids of any text up to 255 characters, with logicFolderKey, the pending connection status and connections.list ([912c788](https://github.com/Appnigma/ap-sdks/commit/912c7881c165e87933aa030e914468722f1af9fc))
21
+ * portal.createLink, a link that opens the custom logic portal for one end customer ([912c788](https://github.com/Appnigma/ap-sdks/commit/912c7881c165e87933aa030e914468722f1af9fc))
22
+ * run a function by its id, and the catalog by end customer ([912c788](https://github.com/Appnigma/ap-sdks/commit/912c7881c165e87933aa030e914468722f1af9fc))
23
+
3
24
  ## [1.0.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v0.2.1...ruby-v1.0.0) (2026-10-26)
4
25
 
5
26
 
data/README.md CHANGED
@@ -68,6 +68,8 @@ shows it to the end customer, and they approve on the platform.
68
68
  most 2048 bytes when written as a JSON string, about 2046 plain characters.
69
69
  4. Confirm with `connections.get`. The connection is written before the end
70
70
  customer lands, so the answer is already there.
71
+ 5. To see everyone at once, with every connection of theirs, use
72
+ `connections.list` below.
71
73
 
72
74
  ```ruby
73
75
  link = client.connections.create_link(
@@ -79,24 +81,89 @@ puts "send the end customer to #{link[:url]} before #{link[:expires_at]}"
79
81
 
80
82
  connection = client.connections.get(end_customer_id: "lawfirm-123", platform: "hubspot")
81
83
  puts "ready to read and write" if connection[:status] == "connected"
84
+ puts connection[:logic_folder_key] # "ec_3f9a1c7e2b8d4a60"
82
85
  ```
83
86
 
84
- `status` is `connected`, `needs_reconnect` or `disconnected`. An end customer
87
+ `status` is `pending`, `connected`, `needs_reconnect` or `disconnected`.
88
+ `pending` is an end customer who was sent a connect link and has not approved
89
+ yet: they exist from the moment the link is made. An end customer
85
90
  who is already connected can open a new link to connect again, for example
86
91
  after changing HubSpot accounts. An end customer the API has never seen is an
87
92
  `Appnigma::NotFoundError`, not a status.
88
93
 
89
- The id travels in the URL for this call, so an id that is only `.` or `..` is
90
- refused before the call with `Appnigma::InputError`: a URL drops those, and
91
- the request would reach the wrong route. Do not use them as end customer ids.
94
+ `logic_folder_key` is where this end customer's own functions go in your logic
95
+ repo: `src/logic/end-customers/<logic_folder_key>/<platform>/`. It is one key
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.
99
+
100
+ An id outside the rule below is refused before the call with
101
+ `Appnigma::InputError`, the same refusal the server would give.
102
+
103
+ ## Listing your end customers: connections.list
104
+
105
+ `connections.list` answers your end customers one page at a time, in id order:
106
+ each with their `end_customer_id`, their `logic_folder_key`,
107
+ `has_custom_logic` (`true` when a function written for them is live) and every
108
+ connection of theirs, with its `platform`, `status` and `connected_at` (ISO
109
+ 8601 in UTC, `nil` while pending). Give `platform:` or `status:` to keep only
110
+ the end customers with at least one connection that matches; each entry still
111
+ lists all of their connections. `limit:` is 1 to 100, 50 if left out; `next`
112
+ 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
114
+ to find who must connect again:
115
+
116
+ ```ruby
117
+ page = client.connections.list(status: "needs_reconnect")
118
+ page[:end_customers].each do |end_customer|
119
+ lost = end_customer[:connections].select { |c| c[:status] == "needs_reconnect" }.map { |c| c[:platform] }
120
+ puts "#{end_customer[:end_customer_id]} must connect again on #{lost.join(', ')}"
121
+ end
122
+
123
+ # More pages, while there is one.
124
+ client.connections.list(status: "needs_reconnect", cursor: page[:next]) if page[:next]
125
+ ```
126
+
127
+ A `platform:` that is not switched on for your company is an
128
+ `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`; a `status:` outside the
129
+ four, a `limit:` outside 1 to 100, or a `cursor:` this list did not give you
130
+ is an `Appnigma::InputError` naming the field. An empty list is not an error.
131
+ Reads are retried.
132
+
133
+ ### Disconnecting an end customer
134
+
135
+ When an end customer leaves a platform, for example they remove it from your
136
+ Integrations page, disconnect them. Their login on that platform is removed
137
+ and the connection is deleted, so `connections.get` then raises
138
+ `Appnigma::NotFoundError` with `END_CUSTOMER_NOT_FOUND`. Their other platforms
139
+ 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
140
+ disconnected the same way.
141
+
142
+ ```ruby
143
+ removed = client.connections.disconnect(end_customer_id: "lawfirm-123", platform: "hubspot")
144
+ puts removed[:status] # "disconnected"
145
+ ```
146
+
147
+ The answer is their id, the platform, `status` `disconnected` and their
148
+ `logic_folder_key`, which comes from their id and so is the same if they
149
+ connect again.
150
+
151
+ Disconnecting an end customer who is not connected, or disconnecting twice,
152
+ raises `Appnigma::NotFoundError` with `END_CUSTOMER_NOT_FOUND`. The call is
153
+ made once and never retried: if its answer is lost and you call again, that
154
+ `END_CUSTOMER_NOT_FOUND` means the first call worked. When the login cannot be
155
+ removed just now, it raises `Appnigma::ServerError` with `INTERNAL_ERROR`,
156
+ nothing is changed, and you can call again. The id rules above apply here too.
92
157
 
93
158
  ## CRM data in one shape: crm
94
159
 
95
160
  `crm.contacts`, `crm.companies` and `crm.deals` read and write an end
96
161
  customer's CRM in one shape, whichever CRM they use. Each has `list`, `get`,
97
162
  `create` and `update`, and each takes `end_customer_id:` and `platform:`.
98
- `end_customer_id` is your own id for your customer, 1 to 100 characters of
99
- letters, digits, dot, dash or underscore.
163
+ `end_customer_id` is your own id for your customer, as it is: an email, a UUID,
164
+ `ACME Inc / EU`. 1 to 255 characters, with no control characters and not only
165
+ spaces, kept exactly as you send it, so ids that differ only in case or spaces
166
+ are different end customers.
100
167
 
101
168
  ```ruby
102
169
  page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "attio", limit: 50)
@@ -207,35 +274,58 @@ once, because only you know whether repeating it is harmless.
207
274
  ## Your own functions: catalog
208
275
 
209
276
  Your microserver can also hold functions written for you.
210
- `catalog` lists them, with the platform each one is for and the JSON Schema of
211
- its input and output. Leave `platform:` out for every platform,
212
- or name one to narrow the list.
277
+ `catalog` lists them, with the platform each one is for, its id, and the JSON
278
+ Schema of its input and output. Leave `platform:` out for every platform,
279
+ or name one to narrow the list. Name an `end_customer_id:` to narrow it to
280
+ your own functions and that end customer's; left out, every end customer's
281
+ functions are listed too.
213
282
 
214
283
  ```ruby
215
- client.catalog(platform: "hubspot")[:functions].each do |function|
216
- puts "#{function[:platform]} #{function[:name]} #{function[:description]}"
284
+ client.catalog(platform: "hubspot", end_customer_id: "lawfirm-123")[:functions].each do |function|
285
+ puts "#{function[:id]} #{function[:platform]} #{function[:name]} #{function[:description]}"
217
286
  end
218
287
  ```
219
288
 
220
289
  A function's `owner` is `{ type: "customer" }` when every end customer can use
221
- it, or `{ type: "end_customer", end_customer_id: "..." }` when it was written
222
- for one of them. `input_schema` and `output_schema` are JSON Schema, as
223
- written. Each function has one live version: a change to it replaces it when
224
- the change goes live. Until a function has gone live for you, the list is
225
- empty, not an error.
290
+ it, or `{ type: "end_customer", logic_folder_key: "..." }` when it was written
291
+ for one of them, named by the logic folder key `connections.get` answers for
292
+ them. An end customer's functions are their versions of yours, which keep your
293
+ function's id, and their own. `input_schema` and
294
+ `output_schema` are JSON Schema, as written. Each function has one live
295
+ version: a change to it replaces it when the change goes live. Until a
296
+ function has gone live for you, the list is empty, not an error.
297
+
298
+ `id` is what `run` takes as `function_id:`. It stays the same when the
299
+ function's name or version changes, and it is `nil` for a function that went
300
+ live before functions had ids. `always_on` is `true` for a function that also
301
+ runs by itself, and `conditionals` says when; it is empty when the function is
302
+ not always on. A conditional with `object`, `operation` and `timing`, such as
303
+ `{ object: "deal", operation: "write", timing: "before" }`, runs it before or
304
+ after a `crm` read or write of that object; one with `action` and `timing`
305
+ runs it around one of the platform's ready-made actions, such as
306
+ `get-call-transcript`; and `{}` runs it after every `crm` call and action on
307
+ its platform.
308
+
309
+ Always-on logic runs around your `crm` calls and actions. Before a call it can
310
+ change what the call sends, and when it fails the call stops with
311
+ `LOGIC_FAILED`: an `Appnigma::LogicFailedError`, never tried again, with
312
+ nothing written or returned. After a call it runs in the background, and never
313
+ slows or fails the call. The docs explain it, with an example of each kind:
314
+ https://docs.appnigma.ai/sdk/always-on-logic.
226
315
 
227
316
  ## Your own functions: run
228
317
 
229
- `run` calls one of them, by platform and name, for one end customer. The input
230
- is checked against the function's shape before anything runs, so a wrong or
231
- missing field is an `Appnigma::InputError` listing every problem. Formats and
232
- patterns, such as an email or a fixed layout for a code, are checked by the
233
- function itself, so those refusals arrive from it with the same code. The
234
- answer is `{ output: ..., ran_as: ... }`: the output in the shape the function
235
- declared, with its keys as the function wrote them, and whose function ran.
236
- `ran_as[:owner]` is `"end_customer"` when the end customer has a function of
237
- their own by that name and it ran, `"customer"` when yours did;
238
- `ran_as[:version]` is the version that ran.
318
+ `run` calls one of them, by platform and either its name or its id, for one
319
+ end customer. The input is checked against the function's shape before
320
+ anything runs, so a wrong or missing field is an `Appnigma::InputError`
321
+ listing every problem. Formats and patterns, such as an email or a fixed
322
+ layout for a code, are checked by the function itself, so those refusals
323
+ arrive from it with the same code. The answer is
324
+ `{ output: ..., ran_as: ... }`: the output in the shape the function declared,
325
+ with its keys as the function wrote them, and whose function ran.
326
+ `ran_as[:owner]` is `"end_customer"` when the end customer has their own
327
+ version of it and it ran, `"customer"` when yours did; `ran_as[:version]` is
328
+ the version that ran.
239
329
 
240
330
  ```ruby
241
331
  result = client.run(
@@ -245,18 +335,30 @@ result = client.run(
245
335
  input: { "invoiceId" => "inv_1042", "amount" => 1250 }
246
336
  )
247
337
  puts "deal #{result[:output]["dealId"]}, ran as #{result[:ran_as][:owner]} v#{result[:ran_as][:version]}"
338
+
339
+ # Or by the id catalog gives it.
340
+ client.run(end_customer_id: "lawfirm-123", platform: "hubspot", function_id: "lg_7f3a9c2d41b8",
341
+ input: { "invoiceId" => "inv_1042", "amount" => 1250 })
248
342
  ```
249
343
 
250
- `platform` and `function_name` are both required: the same name can exist on
251
- two platforms and mean two different things. What runs is always the
252
- function's live version. A name that exists only on another platform is an
344
+ `platform` is required: the same name can exist on two platforms and mean two
345
+ different things. So is one of `function_name` and `function_id`, never both;
346
+ both, or neither, is an `Appnigma::InputError` raised before the call. A name
347
+ finds your own function, and the end customer's version of it runs instead
348
+ when they have one. An id finds the end customer's own version first, then
349
+ yours; an id only another end customer has is an `Appnigma::NotFoundError`.
350
+ What runs is always the function's live version. A function that is always on can be run
351
+ this way too: it runs once, whatever its `conditionals` say, and sets off no
352
+ other function. A name or id that exists only on another platform is an
253
353
  `Appnigma::NotFoundError` whose `details["platforms"]` says which. A function
254
354
  that was live and was removed from your logic is retired: calling it is an
255
355
  `Appnigma::RetiredError` with `FUNCTION_RETIRED`, whose `details` name the
256
356
  function and when it was retired. A platform that is not switched on for you
257
357
  is an `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`. When the function's
258
358
  platform refuses what it sent, it is an `Appnigma::PlatformRefusedError`
259
- carrying the platform's reason.
359
+ carrying the platform's reason. When the function itself fails, it is an
360
+ `Appnigma::LogicFailedError` whose `message` is what the function threw, with
361
+ no logic named; a write it made before it failed stays made.
260
362
 
261
363
  `run` is made once and never retried: it is your own function, and only you
262
364
  know whether running it twice is harmless. If it fails with a network or
@@ -275,6 +377,38 @@ live right now.
275
377
  File.write("appnigma-guide.md", client.guide[:guide])
276
378
  ```
277
379
 
380
+ ## The custom logic portal: portal
381
+
382
+ The portal is a page, inside your product, where one end customer sees their
383
+ own logic, edits it, puts it live and keeps the keys it reads in Settings. They
384
+ only ever see and change their own. It is switched on per company; until it is,
385
+ the call is an `Appnigma::AuthError` with `PORTAL_NOT_ENABLED`.
386
+
387
+ Your server asks for the link, never your page, because the call needs your
388
+ key. A link works once and expires after 15 minutes, so ask for a new one each
389
+ time you show the portal.
390
+
391
+ ```ruby
392
+ link = client.portal.create_link(end_customer_id: "lawfirm-123")
393
+ puts "show it in an iframe, or open it in a new tab: #{link[:url]}"
394
+ ```
395
+
396
+ Show the link's `url` in an iframe on one of your sites, or open it in a new
397
+ tab. Only the sites on your company's list can show it in an iframe; write to
398
+ support@appnigma.ai to add yours. A session lasts an hour. When the link was
399
+ already used, or the session ends, the portal tells your page with a message,
400
+ so your page can ask your server for a new link:
401
+
402
+ ```js
403
+ const portalOrigin = new URL(portalUrl).origin; // the url your server sent
404
+ window.addEventListener("message", (event) => {
405
+ if (event.origin !== portalOrigin) return;
406
+ if (event.data?.type === "appnigma.portal.link-expired" || event.data?.type === "appnigma.portal.session-ended") {
407
+ showPortal(); // your code: ask your server for a new link and set the iframe's src
408
+ }
409
+ });
410
+ ```
411
+
278
412
  ## Telling failures apart
279
413
 
280
414
  Every failure is an exception you can rescue by class. All of them inherit
@@ -285,13 +419,14 @@ your key or a token.
285
419
 
286
420
  | Class | When | Extra field |
287
421
  | --- | --- | --- |
288
- | `Appnigma::InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting or a bad end customer id, before any call. | `problems`, a list of `{ field:, problem: }` |
289
- | `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, the platform is not switched on for you, or the end customer's connection lacks a scope a write needs (`MISSING_SCOPES`, with `details["missing"]`). Also raised at start with no key. | |
422
+ | `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: }` |
423
+ | `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. | |
290
424
  | `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. | |
291
425
  | `Appnigma::ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
292
426
  | `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
293
427
  | `Appnigma::RetiredError` | 410 with `FUNCTION_RETIRED`. The function was live and was removed from your logic; it will not answer again. | |
294
428
  | `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` |
429
+ | `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` |
295
430
  | `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 |
296
431
  | `Appnigma::ServerError` | Any 5xx, after the retries. Also any answer that is not JSON. | |
297
432
  | `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 |
@@ -309,6 +444,8 @@ rescue Appnigma::ReconnectError
309
444
  puts "ask the end customer to connect again"
310
445
  rescue Appnigma::PlatformRefusedError => e
311
446
  puts "the CRM refused it: #{e.message}"
447
+ rescue Appnigma::LogicFailedError => e
448
+ puts "your logic failed: #{e.message} #{e.logic_ids}"
312
449
  rescue Appnigma::RateLimitError => e
313
450
  puts "wait #{e.retry_after_seconds} seconds"
314
451
  rescue Appnigma::ServerError => e
@@ -339,9 +476,9 @@ reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409, 410
339
476
  or 422 is never retried, because the same call would be refused the same way.
340
477
  By default a call is made up to three times.
341
478
 
342
- `connections.create_link`, `run`, `request` with a method other than `GET`,
343
- and a `crm` create with nothing to match on are the exceptions: each is made
344
- once, never retried. Every call to
479
+ `connections.create_link`, `connections.disconnect`, `portal.create_link`, `run`, `request` with a
480
+ method other than `GET`, and a `crm` create with nothing to match on are the
481
+ exceptions: each is made once, never retried. Every call to
345
482
  `create_link` makes a new link, and a repeat after a lost answer would leave a
346
483
  working link nobody saw; `run` is your own function, and whether a repeat is
347
484
  harmless is yours to know; a create with nothing to match on could make a
@@ -49,21 +49,45 @@ module Appnigma
49
49
  refuse("max_retry_wait_ms", "must be a number of milliseconds from 0 to #{MAX_TIMER_MS}")
50
50
  end
51
51
 
52
+ # The server's own rule, applied first so a bad id is refused with the
53
+ # same words before any call. A string that is not valid in its encoding
54
+ # (a lone surrogate, say) is not text and is refused the same way.
52
55
  def end_customer_id!(value)
53
- unless value.is_a?(String) && value.match?(END_CUSTOMER_ID_PATTERN)
54
- refuse("end_customer_id",
55
- END_CUSTOMER_ID_RULE)
56
- end
57
- refuse("end_customer_id", END_CUSTOMER_ID_PATH_RULE) if END_CUSTOMER_ID_PATH_UNSAFE.include?(value)
56
+ refuse("end_customer_id", END_CUSTOMER_ID_RULE) unless value.is_a?(String) && end_customer_id?(value)
58
57
  value
59
58
  end
60
59
 
60
+ def end_customer_id?(value)
61
+ value.valid_encoding? &&
62
+ value.length.between?(1, END_CUSTOMER_ID_MAX_LENGTH) &&
63
+ !value.match?(END_CUSTOMER_ID_FORBIDDEN_PATTERN) &&
64
+ !value.match?(END_CUSTOMER_ID_ONLY_SPACES_PATTERN)
65
+ end
66
+
61
67
  def platform!(value)
62
68
  return value if value.is_a?(String) && !value.empty?
63
69
 
64
70
  refuse("platform", "must be a platform key, such as hubspot")
65
71
  end
66
72
 
73
+ # `run` names its function by name or by id, never both, as the server
74
+ # requires. A nil counts as left out, since a nil is never sent.
75
+ def function_name_or_id!(function_name, function_id)
76
+ if function_name.nil? && function_id.nil?
77
+ refuse("function_name", "is required, or function_id")
78
+ elsif !function_name.nil? && !function_id.nil?
79
+ refuse("function_id", "must be left out when function_name is sent: send one or the other")
80
+ end
81
+ end
82
+
83
+ # 19.3: a status outside the four is refused before any call, with the
84
+ # server's words.
85
+ def connection_status!(value)
86
+ return value if CONNECTION_STATUSES.include?(value)
87
+
88
+ refuse("status", "must be one of #{CONNECTION_STATUSES.join(", ")}")
89
+ end
90
+
67
91
  # The setting if there is one, else production. An empty setting counts
68
92
  # as none. Only https, or http to this machine, so a key never crosses a
69
93
  # network unencrypted.
@@ -8,6 +8,7 @@ require_relative "transport"
8
8
  require_relative "connections"
9
9
  require_relative "crm"
10
10
  require_relative "platforms"
11
+ require_relative "portal"
11
12
 
12
13
  module Appnigma
13
14
  # What a customer creates. The key comes from `key:` or from the
@@ -21,7 +22,7 @@ module Appnigma
21
22
  # a platform's answer), which comes back exactly as it was sent. Every call
22
23
  # also takes `timeout_ms:`, the time limit of one attempt.
23
24
  class Client
24
- attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms, :connections, :crm, :platforms
25
+ attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms, :connections, :crm, :platforms, :portal
25
26
 
26
27
  # `transport` is for tests; a customer never passes it.
27
28
  def initialize(key: nil, timeout_ms: DEFAULT_TIMEOUT_MS, max_retries: DEFAULT_MAX_RETRIES,
@@ -32,8 +33,9 @@ module Appnigma
32
33
  @max_retries = Checks.max_retries!(max_retries)
33
34
  @max_retry_wait_ms = Checks.max_retry_wait_ms!(max_retry_wait_ms)
34
35
  @policy = Retry::Policy.new(max_retries: @max_retries, max_retry_wait_ms: @max_retry_wait_ms)
35
- # A write whose repeat is not harmless gets one attempt. create_link
36
- # makes a new link every time; run is your own function, and only you
36
+ # A write whose repeat is not harmless gets one attempt. Each
37
+ # create_link, the connect link's and the portal's, makes a new link
38
+ # every time; run is your own function, and only you
37
39
  # know whether running it twice is harmless; request with a method
38
40
  # other than GET may change the platform; a crm create with nothing to
39
41
  # match on could make a second record. A crm create that matches, and
@@ -43,17 +45,22 @@ module Appnigma
43
45
  start_groups
44
46
  end
45
47
 
46
- # One of your own functions, by platform and name: its live version runs,
47
- # and the answer's `ran_as` says whose it was. Made once, never retried.
48
- def run(end_customer_id:, platform:, function_name:, input:, timeout_ms: nil)
48
+ # One of your own functions, by platform and either `function_name` or
49
+ # `function_id`, never both: its live version runs, and the answer's
50
+ # `ran_as` says whose it was. Made once, never retried.
51
+ def run(end_customer_id:, platform:, input:, function_name: nil, function_id: nil, timeout_ms: nil)
52
+ Checks.function_name_or_id!(function_name, function_id)
49
53
  body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, function_name: function_name,
50
- input: input)
54
+ function_id: function_id, input: input)
51
55
  call(:run_function, body, policy: @one_attempt, timeout_ms: timeout_ms)
52
56
  end
53
57
 
54
- # Your own functions, with their shapes. `platform` narrows the list.
55
- def catalog(platform: nil, timeout_ms: nil)
56
- call(:list_functions, opts: platform.nil? ? {} : { platform: platform }, timeout_ms: timeout_ms)
58
+ # Your own functions, with their ids and shapes. `platform` narrows the
59
+ # list to one platform; `end_customer_id` to your own functions and that
60
+ # end customer's.
61
+ def catalog(platform: nil, end_customer_id: nil, timeout_ms: nil)
62
+ opts = { platform: platform, end_customer_id: end_customer_id }.compact
63
+ call(:list_functions, opts: opts, timeout_ms: timeout_ms)
57
64
  end
58
65
 
59
66
  # The guide for your developers, as markdown, written for your company
@@ -86,12 +93,13 @@ module Appnigma
86
93
 
87
94
  private
88
95
 
89
- # The calls grouped by what they reach: `connections`, `crm` and
90
- # `platforms`.
96
+ # The calls grouped by what they reach: `connections`, `crm`,
97
+ # `platforms` and `portal`.
91
98
  def start_groups
92
99
  @connections = Connections.new(self)
93
100
  @crm = Crm.new(self)
94
101
  @platforms = Platforms.new(self)
102
+ @portal = Portal.new(self)
95
103
  end
96
104
 
97
105
  # A success whose body is not JSON is a server error: a proxy page or an
@@ -5,7 +5,9 @@ require_relative "names"
5
5
 
6
6
  module Appnigma
7
7
  # Connecting an end customer to their account on a platform:
8
- # `client.connections.create_link` and `client.connections.get`.
8
+ # `client.connections.create_link`, `client.connections.get` and
9
+ # `client.connections.disconnect`, and the list of them all,
10
+ # `client.connections.list`.
9
11
  class Connections
10
12
  def initialize(client)
11
13
  @client = client
@@ -19,13 +21,47 @@ module Appnigma
19
21
  @client.call(:create_connection_link, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
20
22
  end
21
23
 
22
- # Whether one end customer is connected on one platform. The id travels
23
- # in the path, so it is checked here first: a bad one is refused as the
24
- # server would refuse it, and never becomes a wrong route.
24
+ # Whether one end customer is connected on one platform, and the key of
25
+ # their logic folder. The id may be any text, so it travels in the body
26
+ # of POST /connections/get (19.2); it is checked here first, by the
27
+ # server's own rule, so a bad one is refused before any call. A read, so
28
+ # it is retried.
25
29
  def get(end_customer_id:, platform:, timeout_ms: nil)
26
30
  Checks.end_customer_id!(end_customer_id)
27
31
  Checks.platform!(platform)
28
- @client.call(:get_connection, end_customer_id, platform, timeout_ms: timeout_ms)
32
+ body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform)
33
+ @client.call(:get_connection, body, timeout_ms: timeout_ms)
34
+ end
35
+
36
+ # Your end customers, a page at a time, in id order, each with every
37
+ # connection of theirs (19.3). `platform` and `status` list the end
38
+ # customers with at least one connection that matches; `limit` is 1 to
39
+ # 100, 50 when left out; `cursor` is the `next` of the previous page. A
40
+ # platform that is not text and a status outside the four are refused
41
+ # here first, with the server's words. Only the values given travel, in
42
+ # the query. A read, so it is retried.
43
+ def list(platform: nil, status: nil, limit: nil, cursor: nil, timeout_ms: nil)
44
+ opts = {}
45
+ opts[:platform] = Checks.platform!(platform) unless platform.nil?
46
+ opts[:status] = Checks.connection_status!(status) unless status.nil?
47
+ opts[:limit] = limit unless limit.nil?
48
+ opts[:cursor] = cursor unless cursor.nil?
49
+ @client.call(:list_connections, opts: opts, timeout_ms: timeout_ms)
50
+ end
51
+
52
+ # Remove one end customer's connection on one platform: their login is
53
+ # removed and the connection deleted, so `get` then raises
54
+ # END_CUSTOMER_NOT_FOUND. One who was sent a link and never finished is
55
+ # removed the same way. The id travels in the body of
56
+ # POST /connections/disconnect, as for `get`, and is checked here first by
57
+ # the same rule. Made once, never retried: a repeat after a lost answer
58
+ # would find the connection gone and raise END_CUSTOMER_NOT_FOUND, which
59
+ # then means the first call worked.
60
+ def disconnect(end_customer_id:, platform:, timeout_ms: nil)
61
+ Checks.end_customer_id!(end_customer_id)
62
+ Checks.platform!(platform)
63
+ body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform)
64
+ @client.call(:disconnect_connection, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
29
65
  end
30
66
  end
31
67
  end
@@ -43,13 +43,18 @@ module Appnigma
43
43
  # The one 409 that sends an end customer through the connect flow again.
44
44
  RECONNECT_ERROR_CODE = "CONNECTION_NEEDS_RECONNECT"
45
45
 
46
- # An end customer id is 1 to 100 of letters, digits, dot, dash or underscore.
47
- END_CUSTOMER_ID_PATTERN = /\A[A-Za-z0-9._-]{1,100}\z/
48
- END_CUSTOMER_ID_RULE = "must be 1 to 100 characters: letters, digits, dot, dash or underscore"
49
-
50
- # `.` and `..` fit the pattern but cannot travel in a URL path.
51
- END_CUSTOMER_ID_PATH_UNSAFE = [".", ".."].freeze
52
- END_CUSTOMER_ID_PATH_RULE = "cannot be only dots, it travels in the URL path"
46
+ # The one 422 that is your own logic failing, not the platform refusing.
47
+ LOGIC_FAILED_ERROR_CODE = "LOGIC_FAILED"
48
+
49
+ # 19.2: an end customer id is any text of the customer's, 1 to 255
50
+ # characters (code points, as the server and its database count), with no
51
+ # control character and not only spaces. Checked before `connections.get`,
52
+ # which posts it, so a bad one is refused with the server's words before
53
+ # any call.
54
+ END_CUSTOMER_ID_MAX_LENGTH = 255
55
+ END_CUSTOMER_ID_FORBIDDEN_PATTERN = /\p{Cc}/
56
+ END_CUSTOMER_ID_ONLY_SPACES_PATTERN = /\A +\z/
57
+ END_CUSTOMER_ID_RULE = "must be 1 to 255 characters, with no control characters and not only spaces"
53
58
 
54
59
  # The server's error codes (the API description, 18.2). This gem keeps its
55
60
  # own copy: it is published on its own. A test compares it with the
@@ -61,6 +66,7 @@ module Appnigma
61
66
  SDK_KEY_CANCELLED
62
67
  MICROSERVER_NOT_ENABLED
63
68
  PLATFORM_NOT_ENABLED
69
+ PORTAL_NOT_ENABLED
64
70
  END_CUSTOMER_NOT_FOUND
65
71
  FUNCTION_NOT_FOUND
66
72
  FUNCTION_RETIRED
@@ -79,6 +85,6 @@ module Appnigma
79
85
  ].freeze
80
86
 
81
87
  OBJECTS = %w[contact company deal].freeze
82
- CONNECTION_STATUSES = %w[connected needs_reconnect disconnected].freeze
88
+ CONNECTION_STATUSES = %w[pending connected needs_reconnect disconnected].freeze
83
89
  PLATFORM_REQUEST_METHODS = %w[GET POST PUT PATCH DELETE].freeze
84
90
  end
@@ -21,8 +21,9 @@ module Appnigma
21
21
  end
22
22
 
23
23
  # 400. The server names each field it could not accept, as `problems`:
24
- # a list of `{ field:, problem: }`. Also raised locally for a bad setting
25
- # or a bad end customer id, before any call.
24
+ # a list of `{ field:, problem: }`. Also raised locally for a bad setting,
25
+ # a bad end customer id, or a `run` naming its function both by name and
26
+ # by id or neither, before any call.
26
27
  class InputError < Error
27
28
  attr_reader :problems
28
29
 
@@ -62,6 +63,22 @@ module Appnigma
62
63
  end
63
64
  end
64
65
 
66
+ # 422 LOGIC_FAILED: one of your functions, or always-on logic around the
67
+ # call, failed. Always-on logic before a call stopped it, so nothing was
68
+ # written or returned, `message` names the logic and its id, and `logic_ids`
69
+ # lists the ids the server named; a function `run` called may have written
70
+ # before it failed, `message` is what it threw, and `logic_ids` is empty. The
71
+ # same call fails the same way until the logic or what it is given changes,
72
+ # so it is never tried again.
73
+ class LogicFailedError < Error
74
+ attr_reader :logic_ids
75
+
76
+ def initialize(**args)
77
+ super
78
+ @logic_ids = Errors.read_logic_ids(details)
79
+ end
80
+ end
81
+
65
82
  # 429. `retry_after_seconds` is what the server's Retry-After header said,
66
83
  # or nil when it sent none.
67
84
  class RateLimitError < Error
@@ -95,14 +112,13 @@ module Appnigma
95
112
  PROBLEM_KEYS = %w[field problem].freeze
96
113
 
97
114
  # Every status the server's table names; any other is a ServerError. 409
98
- # is chosen by code as well, in error_class.
115
+ # and 422 are chosen by code as well, in error_class.
99
116
  CLASS_BY_STATUS = {
100
117
  400 => InputError,
101
118
  401 => AuthError,
102
119
  403 => AuthError,
103
120
  404 => NotFoundError,
104
121
  410 => RetiredError,
105
- 422 => PlatformRefusedError,
106
122
  429 => RateLimitError
107
123
  }.freeze
108
124
 
@@ -118,9 +134,11 @@ module Appnigma
118
134
  end
119
135
 
120
136
  # Only CONNECTION_NEEDS_RECONNECT asks for a reconnect; any other 409 is
121
- # something the platform cannot give yet.
137
+ # something the platform cannot give yet. A 422 is the platform refusing
138
+ # the call, unless it is LOGIC_FAILED: your own logic failing.
122
139
  def error_class(status, code)
123
140
  return code == RECONNECT_ERROR_CODE ? ReconnectError : NotAvailableError if status == 409
141
+ return code == LOGIC_FAILED_ERROR_CODE ? LogicFailedError : PlatformRefusedError if status == 422
124
142
 
125
143
  CLASS_BY_STATUS.fetch(status, ServerError)
126
144
  end
@@ -141,6 +159,14 @@ module Appnigma
141
159
  }
142
160
  end
143
161
 
162
+ # The server names one logic as `logicId`, or several as `logicIds`.
163
+ def read_logic_ids(details)
164
+ ids = details["logicIds"]
165
+ return ids.grep(String) if ids.is_a?(Array)
166
+
167
+ details["logicId"].is_a?(String) ? [details["logicId"]] : []
168
+ end
169
+
144
170
  def read_problems(details)
145
171
  list = details["problems"]
146
172
  return [] unless list.is_a?(Array)