appnigma-sdk 0.2.1 → 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 +25 -0
- data/README.md +230 -97
- data/lib/appnigma/checks.rb +29 -5
- data/lib/appnigma/client.rb +38 -37
- data/lib/appnigma/connections.rb +25 -5
- data/lib/appnigma/constants.rb +15 -8
- data/lib/appnigma/crm.rb +63 -6
- data/lib/appnigma/errors.rb +45 -4
- data/lib/appnigma/generated/api/default_api.rb +824 -129
- 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 +341 -0
- 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 +2 -2
- data/lib/appnigma/generated/models/{post_output.rb → create_portal_link_input.rb} +20 -46
- data/lib/appnigma/generated/models/{pull_output_records_inner.rb → create_portal_link_output.rb} +37 -37
- 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 +177 -0
- 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 +177 -0
- data/lib/appnigma/generated/models/crm_create_input.rb +245 -0
- 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/{post_input.rb → crm_deal_create_input.rb} +48 -92
- 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 +177 -0
- 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/{pull_input.rb → crm_update_input.rb} +67 -112
- 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 +179 -0
- data/lib/appnigma/generated/models/{pull_output.rb → list_connections_output.rb} +23 -21
- data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
- data/lib/appnigma/generated/models/list_platforms_output.rb +179 -0
- data/lib/appnigma/generated/models/logic_conditional.rb +247 -0
- data/lib/appnigma/generated/models/platform_entry.rb +269 -0
- data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +219 -0
- 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 +4 -6
- data/lib/appnigma/generated/models/run_action_input.rb +266 -0
- data/lib/appnigma/generated/models/run_action_output.rb +178 -0
- data/lib/appnigma/generated/models/run_input.rb +39 -26
- 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 +41 -3
- data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
- data/lib/appnigma/generated/version.rb +1 -1
- data/lib/appnigma/generated.rb +21 -7
- data/lib/appnigma/names.rb +9 -0
- data/lib/appnigma/platforms.rb +18 -0
- data/lib/appnigma/portal.rb +21 -0
- data/lib/appnigma/retry.rb +3 -3
- data/lib/appnigma/transport.rb +4 -4
- data/lib/appnigma/version.rb +2 -2
- metadata +23 -7
- data/lib/appnigma/generated/models/post_input_record_value.rb +0 -104
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,30 @@
|
|
|
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
|
+
|
|
17
|
+
## [1.0.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v0.2.1...ruby-v1.0.0) (2026-10-26)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
### ⚠ BREAKING CHANGES
|
|
21
|
+
|
|
22
|
+
* `post` and `pull` are removed from all three SDKs. Use `crm.*.create` / `update` / `list` / `get` instead.
|
|
23
|
+
|
|
24
|
+
### Features
|
|
25
|
+
|
|
26
|
+
* crm create and update, platforms.list, and post and pull removed ([#18](https://github.com/Appnigma/ap-sdks/issues/18)) ([1fb8c53](https://github.com/Appnigma/ap-sdks/commit/1fb8c53ba5ccfdcd21ac7c2bbb45f14b98965757))
|
|
27
|
+
|
|
3
28
|
## [0.2.1](https://github.com/Appnigma/ap-sdks/compare/ruby-v0.2.0...ruby-v0.2.1) (2026-10-26)
|
|
4
29
|
|
|
5
30
|
|
data/README.md
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
# appnigma-sdk
|
|
2
2
|
|
|
3
|
-
The gem your product installs to reach its Appnigma microserver. It
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
secret: the key is yours to supply.
|
|
3
|
+
The gem your product installs to reach its Appnigma microserver. It connects
|
|
4
|
+
end customers, reads and writes their contacts, companies and deals in one
|
|
5
|
+
shape whichever CRM they use, runs your own functions, and calls any
|
|
6
|
+
platform's API. One gem for every customer. Nothing about your account is
|
|
7
|
+
inside it, and it holds no secret: the key is yours to supply.
|
|
9
8
|
|
|
10
9
|
- Ruby 3.3 or newer. Tested on 3.3, 3.4 and 4.0.
|
|
11
10
|
- The same calls, error codes and retry rules as the TypeScript package
|
|
@@ -25,7 +24,9 @@ gem "appnigma-sdk", "~> 0.2"
|
|
|
25
24
|
```
|
|
26
25
|
|
|
27
26
|
0.2.0 changed `run` (see CHANGELOG.md): code written for 0.1 that passes
|
|
28
|
-
`version:` fails on 0.2 with `ArgumentError: unknown keyword`.
|
|
27
|
+
`version:` fails on 0.2 with `ArgumentError: unknown keyword`. The release
|
|
28
|
+
after 0.2 removes `post` and `pull`: read and write records with `crm`
|
|
29
|
+
instead.
|
|
29
30
|
|
|
30
31
|
## The key
|
|
31
32
|
|
|
@@ -50,47 +51,6 @@ client = Appnigma::Client.new(key: secrets.fetch("appnigma-sdk-key"))
|
|
|
50
51
|
A client started with no key at all, or with a key that does not start with
|
|
51
52
|
`apn_live_`, raises `Appnigma::AuthError` at once, before any call.
|
|
52
53
|
|
|
53
|
-
## The first call: post a record
|
|
54
|
-
|
|
55
|
-
`post` creates a record or updates the one that already matches. For a
|
|
56
|
-
contact, the match is on `email` unless you name another property with
|
|
57
|
-
`unique_by`. For a company or a deal, `unique_by` is required: name a property
|
|
58
|
-
the platform treats as unique, and include it in `record` with a non-empty
|
|
59
|
-
text value. Because it is an update when the record exists, a repeated call is
|
|
60
|
-
safe.
|
|
61
|
-
|
|
62
|
-
```ruby
|
|
63
|
-
result = client.post(
|
|
64
|
-
end_customer_id: "lawfirm-123",
|
|
65
|
-
platform: "hubspot",
|
|
66
|
-
object: "contact",
|
|
67
|
-
record: { "email" => "jane@firm.com", "firstname" => "Jane", "lastname" => "Doe" }
|
|
68
|
-
)
|
|
69
|
-
puts "#{result[:created] ? "created" : "updated"} #{result[:id]}"
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
`end_customer_id` is your own id for your customer, 1 to 100 characters of
|
|
73
|
-
letters, digits, dot, dash or underscore. `platform` is required, and `post`
|
|
74
|
-
and `pull` work on `hubspot` only for now. `object` is `contact`, `company` or
|
|
75
|
-
`deal`. `record` uses the platform's own property names, as strings.
|
|
76
|
-
|
|
77
|
-
## Reading back: pull
|
|
78
|
-
|
|
79
|
-
`pull` returns one page of records and a marker for the next. `next` is `nil`
|
|
80
|
-
on the last page.
|
|
81
|
-
|
|
82
|
-
```ruby
|
|
83
|
-
after = nil
|
|
84
|
-
loop do
|
|
85
|
-
page = client.pull(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", limit: 100, after: after)
|
|
86
|
-
page[:records].each { |contact| puts "#{contact[:id]} #{contact[:properties]["email"]}" }
|
|
87
|
-
after = page[:next]
|
|
88
|
-
break if after.nil?
|
|
89
|
-
end
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
`limit` is 1 to 100 and defaults to 100.
|
|
93
|
-
|
|
94
54
|
## Connecting an end customer
|
|
95
55
|
|
|
96
56
|
Before calls can work for an end customer, they connect their account on that
|
|
@@ -108,6 +68,8 @@ shows it to the end customer, and they approve on the platform.
|
|
|
108
68
|
most 2048 bytes when written as a JSON string, about 2046 plain characters.
|
|
109
69
|
4. Confirm with `connections.get`. The connection is written before the end
|
|
110
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.
|
|
111
73
|
|
|
112
74
|
```ruby
|
|
113
75
|
link = client.connections.create_link(
|
|
@@ -118,23 +80,65 @@ link = client.connections.create_link(
|
|
|
118
80
|
puts "send the end customer to #{link[:url]} before #{link[:expires_at]}"
|
|
119
81
|
|
|
120
82
|
connection = client.connections.get(end_customer_id: "lawfirm-123", platform: "hubspot")
|
|
121
|
-
puts "ready to
|
|
83
|
+
puts "ready to read and write" if connection[:status] == "connected"
|
|
84
|
+
puts connection[:logic_folder_key] # "ec_3f9a1c7e2b8d4a60"
|
|
122
85
|
```
|
|
123
86
|
|
|
124
|
-
`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
|
|
125
90
|
who is already connected can open a new link to connect again, for example
|
|
126
91
|
after changing HubSpot accounts. An end customer the API has never seen is an
|
|
127
92
|
`Appnigma::NotFoundError`, not a status.
|
|
128
93
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
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
132
|
|
|
133
133
|
## CRM data in one shape: crm
|
|
134
134
|
|
|
135
|
-
`crm.contacts`, `crm.companies` and `crm.deals` read an end
|
|
136
|
-
one shape, whichever CRM they use. Each has `list
|
|
137
|
-
`end_customer_id:` and `platform:`.
|
|
135
|
+
`crm.contacts`, `crm.companies` and `crm.deals` read and write an end
|
|
136
|
+
customer's CRM in one shape, whichever CRM they use. Each has `list`, `get`,
|
|
137
|
+
`create` and `update`, and each takes `end_customer_id:` and `platform:`.
|
|
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.
|
|
138
142
|
|
|
139
143
|
```ruby
|
|
140
144
|
page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "attio", limit: 50)
|
|
@@ -161,8 +165,59 @@ left out.
|
|
|
161
165
|
is exactly what the CRM sent. A platform with no unified data yet for that
|
|
162
166
|
object is an `Appnigma::NotAvailableError` with `DATA_TYPE_NOT_AVAILABLE`;
|
|
163
167
|
reach it with `request` instead. An id that does not exist is an
|
|
164
|
-
`Appnigma::NotFoundError` with `RECORD_NOT_FOUND`. Reads are retried
|
|
165
|
-
|
|
168
|
+
`Appnigma::NotFoundError` with `RECORD_NOT_FOUND`. Reads are retried.
|
|
169
|
+
|
|
170
|
+
### Writing: create and update
|
|
171
|
+
|
|
172
|
+
`create` makes a record and `update` changes one, from the fields you give in
|
|
173
|
+
the shapes they are read in. Both answer the record as `get` reads it.
|
|
174
|
+
|
|
175
|
+
```ruby
|
|
176
|
+
contact = client.crm.contacts.create(
|
|
177
|
+
end_customer_id: "lawfirm-123",
|
|
178
|
+
platform: "hubspot",
|
|
179
|
+
record: { first_name: "Jane", last_name: "Doe", emails: [{ value: "jane@firm.com", type: "work", primary: true }] }
|
|
180
|
+
)[:record]
|
|
181
|
+
|
|
182
|
+
client.crm.contacts.update(end_customer_id: "lawfirm-123", platform: "hubspot", id: contact[:id],
|
|
183
|
+
record: { last_name: "King", owner_id: nil })
|
|
184
|
+
|
|
185
|
+
client.crm.deals.create(end_customer_id: "lawfirm-123", platform: "pipedrive",
|
|
186
|
+
record: { name: "Retainer", amount: 1200, currency: "USD" }, match_key: "inv_1042")
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
- **What you can write.** The fields in the table above, except `id`,
|
|
190
|
+
`platform`, the times, `custom_fields`, `raw` and a deal's `closed_at`, which
|
|
191
|
+
are the CRM's to set. A stage or a pipeline is written as its id.
|
|
192
|
+
- **`nil` clears a field;** a field left out is left alone.
|
|
193
|
+
- **Matching.** A contact with an email, or a company with a domain, updates
|
|
194
|
+
the record the CRM already has with it rather than making a second one. A
|
|
195
|
+
deal has no such field, so pass `match_key:`, a key of your own such as your
|
|
196
|
+
invoice id: the same key updates the same deal.
|
|
197
|
+
- **Repeats.** A create that matches, and an update, are retried like reads,
|
|
198
|
+
because a repeat changes the same record. A create with nothing to match on
|
|
199
|
+
is made once, because a repeat could make a second record.
|
|
200
|
+
- **Refusals.** A field this CRM cannot be told is an `Appnigma::InputError`
|
|
201
|
+
naming it, sent nowhere. A write the end customer's connection lacks the
|
|
202
|
+
scope for is an `Appnigma::AuthError` with `MISSING_SCOPES`, and
|
|
203
|
+
`details["missing"]` names the scopes: the end customer has to connect
|
|
204
|
+
again. A value the CRM itself refuses is an
|
|
205
|
+
`Appnigma::PlatformRefusedError` with its reason.
|
|
206
|
+
|
|
207
|
+
## Which platforms: platforms
|
|
208
|
+
|
|
209
|
+
`platforms.list` names each platform switched on for you, and how much of it
|
|
210
|
+
the shared shapes cover.
|
|
211
|
+
|
|
212
|
+
```ruby
|
|
213
|
+
client.platforms.list[:platforms].each do |platform|
|
|
214
|
+
puts "#{platform[:label]}: #{platform[:support]}"
|
|
215
|
+
end
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`support` is `supported` when `crm` reads and writes it, with `coverage`
|
|
219
|
+
naming each object and its actions, or `experimental` when only `request`
|
|
220
|
+
reaches it so far.
|
|
166
221
|
|
|
167
222
|
## Anything else on the platform: request
|
|
168
223
|
|
|
@@ -188,41 +243,64 @@ The answer is the platform's own: its `status`, its `headers` (content type,
|
|
|
188
243
|
paging and rate limits) and its `body`, parsed from JSON when the platform
|
|
189
244
|
answered JSON and as text otherwise. A refusal from the platform comes back
|
|
190
245
|
the same way, with its status, rather than as an error: check
|
|
191
|
-
`answer[:status]`. A `GET` is retried like
|
|
246
|
+
`answer[:status]`. A `GET` is retried like a read; any other method is made
|
|
192
247
|
once, because only you know whether repeating it is harmless.
|
|
193
248
|
|
|
194
249
|
## Your own functions: catalog
|
|
195
250
|
|
|
196
|
-
|
|
197
|
-
`catalog` lists them, with the platform each one is for and the JSON
|
|
198
|
-
its input and output. Leave `platform:` out for every platform,
|
|
199
|
-
or name one to narrow the list.
|
|
251
|
+
Your microserver can also hold functions written for you.
|
|
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.
|
|
200
257
|
|
|
201
258
|
```ruby
|
|
202
|
-
client.catalog(platform: "hubspot")[:functions].each do |function|
|
|
203
|
-
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]}"
|
|
204
261
|
end
|
|
205
262
|
```
|
|
206
263
|
|
|
207
264
|
A function's `owner` is `{ type: "customer" }` when every end customer can use
|
|
208
|
-
it, or `{ type: "end_customer",
|
|
209
|
-
for one of them
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
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.
|
|
213
290
|
|
|
214
291
|
## Your own functions: run
|
|
215
292
|
|
|
216
|
-
`run` calls one of them, by platform and name, for one
|
|
217
|
-
is checked against the function's shape before
|
|
218
|
-
missing field is an `Appnigma::InputError`
|
|
219
|
-
patterns, such as an email or a fixed
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
`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.
|
|
226
304
|
|
|
227
305
|
```ruby
|
|
228
306
|
result = client.run(
|
|
@@ -232,16 +310,30 @@ result = client.run(
|
|
|
232
310
|
input: { "invoiceId" => "inv_1042", "amount" => 1250 }
|
|
233
311
|
)
|
|
234
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 })
|
|
235
317
|
```
|
|
236
318
|
|
|
237
|
-
`platform`
|
|
238
|
-
|
|
239
|
-
|
|
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
|
|
240
328
|
`Appnigma::NotFoundError` whose `details["platforms"]` says which. A function
|
|
241
329
|
that was live and was removed from your logic is retired: calling it is an
|
|
242
330
|
`Appnigma::RetiredError` with `FUNCTION_RETIRED`, whose `details` name the
|
|
243
331
|
function and when it was retired. A platform that is not switched on for you
|
|
244
|
-
is an `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`.
|
|
332
|
+
is an `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`. When the function's
|
|
333
|
+
platform refuses what it sent, it is an `Appnigma::PlatformRefusedError`
|
|
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.
|
|
245
337
|
|
|
246
338
|
`run` is made once and never retried: it is your own function, and only you
|
|
247
339
|
know whether running it twice is harmless. If it fails with a network or
|
|
@@ -250,7 +342,8 @@ server error, decide in your code whether to call again.
|
|
|
250
342
|
## Your own guide
|
|
251
343
|
|
|
252
344
|
One page, written for your company: install, the key, connecting an end
|
|
253
|
-
customer to each platform switched on for you,
|
|
345
|
+
customer to each platform switched on for you, reading and writing records,
|
|
346
|
+
`run`, every
|
|
254
347
|
one of your functions with its fields and an example call, and every error
|
|
255
348
|
with what to do about it. `guide` answers it as markdown, built from what is
|
|
256
349
|
live right now.
|
|
@@ -259,6 +352,38 @@ live right now.
|
|
|
259
352
|
File.write("appnigma-guide.md", client.guide[:guide])
|
|
260
353
|
```
|
|
261
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
|
+
|
|
262
387
|
## Telling failures apart
|
|
263
388
|
|
|
264
389
|
Every failure is an exception you can rescue by class. All of them inherit
|
|
@@ -269,19 +394,21 @@ your key or a token.
|
|
|
269
394
|
|
|
270
395
|
| Class | When | Extra field |
|
|
271
396
|
| --- | --- | --- |
|
|
272
|
-
| `Appnigma::InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting
|
|
273
|
-
| `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, or the
|
|
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. | |
|
|
274
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. | |
|
|
275
400
|
| `Appnigma::ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
|
|
276
401
|
| `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
|
|
277
402
|
| `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` |
|
|
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` |
|
|
278
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 |
|
|
279
406
|
| `Appnigma::ServerError` | Any 5xx, after the retries. Also any answer that is not JSON. | |
|
|
280
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 |
|
|
281
408
|
|
|
282
409
|
```ruby
|
|
283
410
|
begin
|
|
284
|
-
client.
|
|
411
|
+
client.crm.contacts.create(end_customer_id: "lawfirm-123", platform: "hubspot", record: { first_name: "Jane" })
|
|
285
412
|
rescue Appnigma::InputError => e
|
|
286
413
|
e.problems.each { |problem| puts "#{problem[:field]} #{problem[:problem]}" }
|
|
287
414
|
rescue Appnigma::AuthError => e
|
|
@@ -290,6 +417,10 @@ rescue Appnigma::NotFoundError
|
|
|
290
417
|
puts "this end customer is not connected yet"
|
|
291
418
|
rescue Appnigma::ReconnectError
|
|
292
419
|
puts "ask the end customer to connect again"
|
|
420
|
+
rescue Appnigma::PlatformRefusedError => e
|
|
421
|
+
puts "the CRM refused it: #{e.message}"
|
|
422
|
+
rescue Appnigma::LogicFailedError => e
|
|
423
|
+
puts "your logic failed: #{e.message} #{e.logic_ids}"
|
|
293
424
|
rescue Appnigma::RateLimitError => e
|
|
294
425
|
puts "wait #{e.retry_after_seconds} seconds"
|
|
295
426
|
rescue Appnigma::ServerError => e
|
|
@@ -316,16 +447,18 @@ never replaced.
|
|
|
316
447
|
## Retries and time limits
|
|
317
448
|
|
|
318
449
|
A call is tried again only when trying again is safe: the API could not be
|
|
319
|
-
reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409
|
|
320
|
-
is never retried, because the same call would be refused the same way.
|
|
321
|
-
a call is made up to three times.
|
|
450
|
+
reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409, 410
|
|
451
|
+
or 422 is never retried, because the same call would be refused the same way.
|
|
452
|
+
By default a call is made up to three times.
|
|
322
453
|
|
|
323
|
-
`connections.create_link`, `run`,
|
|
324
|
-
|
|
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
|
|
325
457
|
`create_link` makes a new link, and a repeat after a lost answer would leave a
|
|
326
458
|
working link nobody saw; `run` is your own function, and whether a repeat is
|
|
327
|
-
harmless is yours to know
|
|
328
|
-
|
|
459
|
+
harmless is yours to know; a create with nothing to match on could make a
|
|
460
|
+
second record. If one of them fails, decide in your code whether to call
|
|
461
|
+
again.
|
|
329
462
|
|
|
330
463
|
The wait between tries is what the `Retry-After` header says when the server
|
|
331
464
|
sent one, otherwise half a second and then a second, with a little random
|
|
@@ -339,7 +472,7 @@ of time counts as a network failure and is retried like one. Each call can set
|
|
|
339
472
|
its own limit:
|
|
340
473
|
|
|
341
474
|
```ruby
|
|
342
|
-
page = client.
|
|
475
|
+
page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "hubspot", limit: 1, timeout_ms: 10_000)
|
|
343
476
|
puts "one record: #{page[:records].size}"
|
|
344
477
|
```
|
|
345
478
|
|
|
@@ -358,7 +491,7 @@ Per call, as a keyword argument: `timeout_ms:`.
|
|
|
358
491
|
|
|
359
492
|
## What is exported
|
|
360
493
|
|
|
361
|
-
`Appnigma::Client`, `Appnigma::Error` and its
|
|
494
|
+
`Appnigma::Client`, `Appnigma::Error` and its ten subclasses, the constants
|
|
362
495
|
`Appnigma::ERROR_CODES`, `Appnigma::OBJECTS`, `Appnigma::CONNECTION_STATUSES`
|
|
363
496
|
and `Appnigma::PLATFORM_REQUEST_METHODS`, `Appnigma::VERSION`, and
|
|
364
497
|
`Appnigma::API_DESCRIPTION_VERSION`, the version of the published description
|
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.
|