appnigma-sdk 1.0.0 → 2.0.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 +147 -35
- data/lib/appnigma/checks.rb +29 -5
- data/lib/appnigma/client.rb +20 -12
- data/lib/appnigma/connections.rb +25 -5
- data/lib/appnigma/constants.rb +14 -8
- data/lib/appnigma/errors.rb +31 -5
- data/lib/appnigma/generated/api/default_api.rb +253 -20
- 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/connection_status.rb +3 -2
- data/lib/appnigma/generated/models/create_connection_link_input.rb +2 -13
- data/lib/appnigma/generated/models/create_connection_link_output.rb +1 -1
- data/lib/appnigma/generated/models/create_portal_link_input.rb +177 -0
- data/lib/appnigma/generated/models/create_portal_link_output.rb +205 -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 +2 -13
- 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 +2 -13
- 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 +2 -13
- data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
- data/lib/appnigma/generated/models/crm_list_input.rb +2 -13
- data/lib/appnigma/generated/models/crm_phone.rb +1 -1
- data/lib/appnigma/generated/models/crm_update_input.rb +2 -13
- data/lib/appnigma/generated/models/end_customer.rb +247 -0
- data/lib/appnigma/generated/models/end_customer_connection.rb +239 -0
- data/lib/appnigma/generated/models/function_entry.rb +74 -5
- 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 +18 -17
- data/lib/appnigma/generated/models/get_connection_input.rb +216 -0
- data/lib/appnigma/generated/models/get_connection_output.rb +18 -5
- data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
- 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 +193 -0
- data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
- data/lib/appnigma/generated/models/list_platforms_output.rb +1 -1
- data/lib/appnigma/generated/models/logic_conditional.rb +247 -0
- data/lib/appnigma/generated/models/platform_entry.rb +1 -1
- data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +1 -1
- data/lib/appnigma/generated/models/platform_request_input.rb +2 -13
- 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/run_action_input.rb +2 -13
- data/lib/appnigma/generated/models/run_action_output.rb +1 -1
- data/lib/appnigma/generated/models/run_input.rb +37 -24
- 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 +12 -3
- data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
- data/lib/appnigma/generated/version.rb +1 -1
- data/lib/appnigma/generated.rb +8 -1
- data/lib/appnigma/portal.rb +21 -0
- data/lib/appnigma/transport.rb +4 -4
- data/lib/appnigma/version.rb +2 -2
- metadata +9 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b52aba7ed80e5bdfbc22ade56d649b1b11464cafa70243807bb4b3609f58efda
|
|
4
|
+
data.tar.gz: d814d25d0d3fe960cce4484d75acfffa4f536039de9bb2558d7f516d601ed55c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: e2fc85df3937ca7be1e558779ff5fdea910a8e5af787ce53de5bfc7bf694fa88d1d516dc5a3783e42c14d416bceec80ee60d0f18e6d035698f0462e1002649a2
|
|
7
|
+
data.tar.gz: 891a5d6d5e257dfd811c428586a3c114ce29200708635d554992eedad1b4e6d57e79a5d32df65cef6063ba06c8e3f711a6fc6dce2d0f29671dc9357037b903d8
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [2.0.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v1.0.0...ruby-v2.0.0) (2026-11-01)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* a failed logic run answers LOGIC_FAILED with status 422 and its own error class, instead of 500
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* 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))
|
|
13
|
+
* 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))
|
|
14
|
+
* portal.createLink, a link that opens the custom logic portal for one end customer ([912c788](https://github.com/Appnigma/ap-sdks/commit/912c7881c165e87933aa030e914468722f1af9fc))
|
|
15
|
+
* run a function by its id, and the catalog by end customer ([912c788](https://github.com/Appnigma/ap-sdks/commit/912c7881c165e87933aa030e914468722f1af9fc))
|
|
16
|
+
|
|
3
17
|
## [1.0.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v0.2.1...ruby-v1.0.0) (2026-10-26)
|
|
4
18
|
|
|
5
19
|
|
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,64 @@ 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`.
|
|
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
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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.
|
|
92
132
|
|
|
93
133
|
## CRM data in one shape: crm
|
|
94
134
|
|
|
95
135
|
`crm.contacts`, `crm.companies` and `crm.deals` read and write an end
|
|
96
136
|
customer's CRM in one shape, whichever CRM they use. Each has `list`, `get`,
|
|
97
137
|
`create` and `update`, and each takes `end_customer_id:` and `platform:`.
|
|
98
|
-
`end_customer_id` is your own id for your customer,
|
|
99
|
-
|
|
138
|
+
`end_customer_id` is your own id for your customer, as it is: an email, a UUID,
|
|
139
|
+
`ACME Inc / EU`. 1 to 255 characters, with no control characters and not only
|
|
140
|
+
spaces, kept exactly as you send it, so ids that differ only in case or spaces
|
|
141
|
+
are different end customers.
|
|
100
142
|
|
|
101
143
|
```ruby
|
|
102
144
|
page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "attio", limit: 50)
|
|
@@ -207,35 +249,58 @@ once, because only you know whether repeating it is harmless.
|
|
|
207
249
|
## Your own functions: catalog
|
|
208
250
|
|
|
209
251
|
Your microserver can also hold functions written for you.
|
|
210
|
-
`catalog` lists them, with the platform each one is for and the JSON
|
|
211
|
-
its input and output. Leave `platform:` out for every platform,
|
|
212
|
-
or name one to narrow the list.
|
|
252
|
+
`catalog` lists them, with the platform each one is for, its id, and the JSON
|
|
253
|
+
Schema of its input and output. Leave `platform:` out for every platform,
|
|
254
|
+
or name one to narrow the list. Name an `end_customer_id:` to narrow it to
|
|
255
|
+
your own functions and that end customer's; left out, every end customer's
|
|
256
|
+
functions are listed too.
|
|
213
257
|
|
|
214
258
|
```ruby
|
|
215
|
-
client.catalog(platform: "hubspot")[:functions].each do |function|
|
|
216
|
-
puts "#{function[:platform]} #{function[:name]} #{function[:description]}"
|
|
259
|
+
client.catalog(platform: "hubspot", end_customer_id: "lawfirm-123")[:functions].each do |function|
|
|
260
|
+
puts "#{function[:id]} #{function[:platform]} #{function[:name]} #{function[:description]}"
|
|
217
261
|
end
|
|
218
262
|
```
|
|
219
263
|
|
|
220
264
|
A function's `owner` is `{ type: "customer" }` when every end customer can use
|
|
221
|
-
it, or `{ type: "end_customer",
|
|
222
|
-
for one of them
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
265
|
+
it, or `{ type: "end_customer", logic_folder_key: "..." }` when it was written
|
|
266
|
+
for one of them, named by the logic folder key `connections.get` answers for
|
|
267
|
+
them. An end customer's functions are their versions of yours, which keep your
|
|
268
|
+
function's id, and their own. `input_schema` and
|
|
269
|
+
`output_schema` are JSON Schema, as written. Each function has one live
|
|
270
|
+
version: a change to it replaces it when the change goes live. Until a
|
|
271
|
+
function has gone live for you, the list is empty, not an error.
|
|
272
|
+
|
|
273
|
+
`id` is what `run` takes as `function_id:`. It stays the same when the
|
|
274
|
+
function's name or version changes, and it is `nil` for a function that went
|
|
275
|
+
live before functions had ids. `always_on` is `true` for a function that also
|
|
276
|
+
runs by itself, and `conditionals` says when; it is empty when the function is
|
|
277
|
+
not always on. A conditional with `object`, `operation` and `timing`, such as
|
|
278
|
+
`{ object: "deal", operation: "write", timing: "before" }`, runs it before or
|
|
279
|
+
after a `crm` read or write of that object; one with `action` and `timing`
|
|
280
|
+
runs it around one of the platform's ready-made actions, such as
|
|
281
|
+
`get-call-transcript`; and `{}` runs it after every `crm` call and action on
|
|
282
|
+
its platform.
|
|
283
|
+
|
|
284
|
+
Always-on logic runs around your `crm` calls and actions. Before a call it can
|
|
285
|
+
change what the call sends, and when it fails the call stops with
|
|
286
|
+
`LOGIC_FAILED`: an `Appnigma::LogicFailedError`, never tried again, with
|
|
287
|
+
nothing written or returned. After a call it runs in the background, and never
|
|
288
|
+
slows or fails the call. The docs explain it, with an example of each kind:
|
|
289
|
+
https://docs.appnigma.ai/sdk/always-on-logic.
|
|
226
290
|
|
|
227
291
|
## Your own functions: run
|
|
228
292
|
|
|
229
|
-
`run` calls one of them, by platform and name, for one
|
|
230
|
-
is checked against the function's shape before
|
|
231
|
-
missing field is an `Appnigma::InputError`
|
|
232
|
-
patterns, such as an email or a fixed
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
`ran_as[:version]` is
|
|
293
|
+
`run` calls one of them, by platform and either its name or its id, for one
|
|
294
|
+
end customer. The input is checked against the function's shape before
|
|
295
|
+
anything runs, so a wrong or missing field is an `Appnigma::InputError`
|
|
296
|
+
listing every problem. Formats and patterns, such as an email or a fixed
|
|
297
|
+
layout for a code, are checked by the function itself, so those refusals
|
|
298
|
+
arrive from it with the same code. The answer is
|
|
299
|
+
`{ output: ..., ran_as: ... }`: the output in the shape the function declared,
|
|
300
|
+
with its keys as the function wrote them, and whose function ran.
|
|
301
|
+
`ran_as[:owner]` is `"end_customer"` when the end customer has their own
|
|
302
|
+
version of it and it ran, `"customer"` when yours did; `ran_as[:version]` is
|
|
303
|
+
the version that ran.
|
|
239
304
|
|
|
240
305
|
```ruby
|
|
241
306
|
result = client.run(
|
|
@@ -245,18 +310,30 @@ result = client.run(
|
|
|
245
310
|
input: { "invoiceId" => "inv_1042", "amount" => 1250 }
|
|
246
311
|
)
|
|
247
312
|
puts "deal #{result[:output]["dealId"]}, ran as #{result[:ran_as][:owner]} v#{result[:ran_as][:version]}"
|
|
313
|
+
|
|
314
|
+
# Or by the id catalog gives it.
|
|
315
|
+
client.run(end_customer_id: "lawfirm-123", platform: "hubspot", function_id: "lg_7f3a9c2d41b8",
|
|
316
|
+
input: { "invoiceId" => "inv_1042", "amount" => 1250 })
|
|
248
317
|
```
|
|
249
318
|
|
|
250
|
-
`platform`
|
|
251
|
-
|
|
252
|
-
|
|
319
|
+
`platform` is required: the same name can exist on two platforms and mean two
|
|
320
|
+
different things. So is one of `function_name` and `function_id`, never both;
|
|
321
|
+
both, or neither, is an `Appnigma::InputError` raised before the call. A name
|
|
322
|
+
finds your own function, and the end customer's version of it runs instead
|
|
323
|
+
when they have one. An id finds the end customer's own version first, then
|
|
324
|
+
yours; an id only another end customer has is an `Appnigma::NotFoundError`.
|
|
325
|
+
What runs is always the function's live version. A function that is always on can be run
|
|
326
|
+
this way too: it runs once, whatever its `conditionals` say, and sets off no
|
|
327
|
+
other function. A name or id that exists only on another platform is an
|
|
253
328
|
`Appnigma::NotFoundError` whose `details["platforms"]` says which. A function
|
|
254
329
|
that was live and was removed from your logic is retired: calling it is an
|
|
255
330
|
`Appnigma::RetiredError` with `FUNCTION_RETIRED`, whose `details` name the
|
|
256
331
|
function and when it was retired. A platform that is not switched on for you
|
|
257
332
|
is an `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`. When the function's
|
|
258
333
|
platform refuses what it sent, it is an `Appnigma::PlatformRefusedError`
|
|
259
|
-
carrying the platform's reason.
|
|
334
|
+
carrying the platform's reason. When the function itself fails, it is an
|
|
335
|
+
`Appnigma::LogicFailedError` whose `message` is what the function threw, with
|
|
336
|
+
no logic named; a write it made before it failed stays made.
|
|
260
337
|
|
|
261
338
|
`run` is made once and never retried: it is your own function, and only you
|
|
262
339
|
know whether running it twice is harmless. If it fails with a network or
|
|
@@ -275,6 +352,38 @@ live right now.
|
|
|
275
352
|
File.write("appnigma-guide.md", client.guide[:guide])
|
|
276
353
|
```
|
|
277
354
|
|
|
355
|
+
## The custom logic portal: portal
|
|
356
|
+
|
|
357
|
+
The portal is a page, inside your product, where one end customer sees their
|
|
358
|
+
own logic, edits it, puts it live and keeps the keys it reads in Settings. They
|
|
359
|
+
only ever see and change their own. It is switched on per company; until it is,
|
|
360
|
+
the call is an `Appnigma::AuthError` with `PORTAL_NOT_ENABLED`.
|
|
361
|
+
|
|
362
|
+
Your server asks for the link, never your page, because the call needs your
|
|
363
|
+
key. A link works once and expires after 15 minutes, so ask for a new one each
|
|
364
|
+
time you show the portal.
|
|
365
|
+
|
|
366
|
+
```ruby
|
|
367
|
+
link = client.portal.create_link(end_customer_id: "lawfirm-123")
|
|
368
|
+
puts "show it in an iframe, or open it in a new tab: #{link[:url]}"
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
Show the link's `url` in an iframe on one of your sites, or open it in a new
|
|
372
|
+
tab. Only the sites on your company's list can show it in an iframe; write to
|
|
373
|
+
support@appnigma.ai to add yours. A session lasts an hour. When the link was
|
|
374
|
+
already used, or the session ends, the portal tells your page with a message,
|
|
375
|
+
so your page can ask your server for a new link:
|
|
376
|
+
|
|
377
|
+
```js
|
|
378
|
+
const portalOrigin = new URL(portalUrl).origin; // the url your server sent
|
|
379
|
+
window.addEventListener("message", (event) => {
|
|
380
|
+
if (event.origin !== portalOrigin) return;
|
|
381
|
+
if (event.data?.type === "appnigma.portal.link-expired" || event.data?.type === "appnigma.portal.session-ended") {
|
|
382
|
+
showPortal(); // your code: ask your server for a new link and set the iframe's src
|
|
383
|
+
}
|
|
384
|
+
});
|
|
385
|
+
```
|
|
386
|
+
|
|
278
387
|
## Telling failures apart
|
|
279
388
|
|
|
280
389
|
Every failure is an exception you can rescue by class. All of them inherit
|
|
@@ -285,13 +394,14 @@ your key or a token.
|
|
|
285
394
|
|
|
286
395
|
| Class | When | Extra field |
|
|
287
396
|
| --- | --- | --- |
|
|
288
|
-
| `Appnigma::InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting
|
|
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. | |
|
|
397
|
+
| `Appnigma::InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting, a bad end customer id, or a `run` given both `function_name` and `function_id` or neither, before any call. | `problems`, a list of `{ field:, problem: }` |
|
|
398
|
+
| `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, the platform or the custom logic portal is not switched on for you (`PLATFORM_NOT_ENABLED`, `PORTAL_NOT_ENABLED`), or the end customer's connection lacks a scope a write needs (`MISSING_SCOPES`, with `details["missing"]`). Also raised at start with no key. | |
|
|
290
399
|
| `Appnigma::NotFoundError` | 404. No connection for that end customer on that platform, no such function, or no such record (`RECORD_NOT_FOUND`). When the function exists on another platform, `details["platforms"]` names it. | |
|
|
291
400
|
| `Appnigma::ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
|
|
292
401
|
| `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
|
|
293
402
|
| `Appnigma::RetiredError` | 410 with `FUNCTION_RETIRED`. The function was live and was removed from your logic; it will not answer again. | |
|
|
294
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` |
|
|
404
|
+
| `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
405
|
| `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
406
|
| `Appnigma::ServerError` | Any 5xx, after the retries. Also any answer that is not JSON. | |
|
|
297
407
|
| `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 +419,8 @@ rescue Appnigma::ReconnectError
|
|
|
309
419
|
puts "ask the end customer to connect again"
|
|
310
420
|
rescue Appnigma::PlatformRefusedError => e
|
|
311
421
|
puts "the CRM refused it: #{e.message}"
|
|
422
|
+
rescue Appnigma::LogicFailedError => e
|
|
423
|
+
puts "your logic failed: #{e.message} #{e.logic_ids}"
|
|
312
424
|
rescue Appnigma::RateLimitError => e
|
|
313
425
|
puts "wait #{e.retry_after_seconds} seconds"
|
|
314
426
|
rescue Appnigma::ServerError => e
|
|
@@ -339,9 +451,9 @@ reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409, 410
|
|
|
339
451
|
or 422 is never retried, because the same call would be refused the same way.
|
|
340
452
|
By default a call is made up to three times.
|
|
341
453
|
|
|
342
|
-
`connections.create_link`, `run`, `request` with a
|
|
343
|
-
and a `crm` create with nothing to match on are the
|
|
344
|
-
once, never retried. Every call to
|
|
454
|
+
`connections.create_link`, `portal.create_link`, `run`, `request` with a
|
|
455
|
+
method other than `GET`, and a `crm` create with nothing to match on are the
|
|
456
|
+
exceptions: each is made once, never retried. Every call to
|
|
345
457
|
`create_link` makes a new link, and a repeat after a lost answer would leave a
|
|
346
458
|
working link nobody saw; `run` is your own function, and whether a repeat is
|
|
347
459
|
harmless is yours to know; a create with nothing to match on could make a
|
data/lib/appnigma/checks.rb
CHANGED
|
@@ -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) &&
|
|
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.
|
data/lib/appnigma/client.rb
CHANGED
|
@@ -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.
|
|
36
|
-
#
|
|
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
|
|
47
|
-
#
|
|
48
|
-
|
|
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
|
|
55
|
-
|
|
56
|
-
|
|
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
|
|
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
|
data/lib/appnigma/connections.rb
CHANGED
|
@@ -5,7 +5,8 @@ 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` and `client.connections.get`, and the
|
|
9
|
+
# list of them all, `client.connections.list`.
|
|
9
10
|
class Connections
|
|
10
11
|
def initialize(client)
|
|
11
12
|
@client = client
|
|
@@ -19,13 +20,32 @@ module Appnigma
|
|
|
19
20
|
@client.call(:create_connection_link, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
|
|
20
21
|
end
|
|
21
22
|
|
|
22
|
-
# Whether one end customer is connected on one platform
|
|
23
|
-
#
|
|
24
|
-
#
|
|
23
|
+
# Whether one end customer is connected on one platform, and the key of
|
|
24
|
+
# their logic folder. The id may be any text, so it travels in the body
|
|
25
|
+
# of POST /connections/get (19.2); it is checked here first, by the
|
|
26
|
+
# server's own rule, so a bad one is refused before any call. A read, so
|
|
27
|
+
# it is retried.
|
|
25
28
|
def get(end_customer_id:, platform:, timeout_ms: nil)
|
|
26
29
|
Checks.end_customer_id!(end_customer_id)
|
|
27
30
|
Checks.platform!(platform)
|
|
28
|
-
|
|
31
|
+
body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform)
|
|
32
|
+
@client.call(:get_connection, body, timeout_ms: timeout_ms)
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
# Your end customers, a page at a time, in id order, each with every
|
|
36
|
+
# connection of theirs (19.3). `platform` and `status` list the end
|
|
37
|
+
# customers with at least one connection that matches; `limit` is 1 to
|
|
38
|
+
# 100, 50 when left out; `cursor` is the `next` of the previous page. A
|
|
39
|
+
# platform that is not text and a status outside the four are refused
|
|
40
|
+
# here first, with the server's words. Only the values given travel, in
|
|
41
|
+
# the query. A read, so it is retried.
|
|
42
|
+
def list(platform: nil, status: nil, limit: nil, cursor: nil, timeout_ms: nil)
|
|
43
|
+
opts = {}
|
|
44
|
+
opts[:platform] = Checks.platform!(platform) unless platform.nil?
|
|
45
|
+
opts[:status] = Checks.connection_status!(status) unless status.nil?
|
|
46
|
+
opts[:limit] = limit unless limit.nil?
|
|
47
|
+
opts[:cursor] = cursor unless cursor.nil?
|
|
48
|
+
@client.call(:list_connections, opts: opts, timeout_ms: timeout_ms)
|
|
29
49
|
end
|
|
30
50
|
end
|
|
31
51
|
end
|
data/lib/appnigma/constants.rb
CHANGED
|
@@ -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
|
-
#
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
#
|
|
51
|
-
|
|
52
|
-
|
|
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
|
data/lib/appnigma/errors.rb
CHANGED
|
@@ -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
|
-
#
|
|
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
|
-
#
|
|
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)
|