appnigma-sdk 0.2.1 → 1.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 +11 -0
- data/README.md +90 -69
- data/lib/appnigma/client.rb +21 -28
- data/lib/appnigma/constants.rb +1 -0
- data/lib/appnigma/crm.rb +63 -6
- data/lib/appnigma/errors.rb +15 -0
- data/lib/appnigma/generated/api/default_api.rb +523 -61
- 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 +1 -1
- data/lib/appnigma/generated/models/create_connection_link_input.rb +1 -1
- data/lib/appnigma/generated/models/create_connection_link_output.rb +2 -2
- 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/{post_output.rb → crm_company_write_output.rb} +20 -46
- 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 +256 -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 -81
- 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 +1 -1
- data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
- data/lib/appnigma/generated/models/crm_list_input.rb +1 -1
- data/lib/appnigma/generated/models/crm_phone.rb +1 -1
- data/lib/appnigma/generated/models/{pull_input.rb → crm_update_input.rb} +66 -100
- data/lib/appnigma/generated/models/function_entry.rb +1 -1
- data/lib/appnigma/generated/models/function_owner.rb +1 -1
- data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
- data/lib/appnigma/generated/models/function_owner_one_of1.rb +1 -1
- data/lib/appnigma/generated/models/get_connection_output.rb +1 -1
- 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/{pull_output_records_inner.rb → list_actions_output.rb} +21 -47
- 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/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 +1 -1
- data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
- data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
- data/lib/appnigma/generated/models/ran_as.rb +4 -6
- data/lib/appnigma/generated/models/run_action_input.rb +277 -0
- data/lib/appnigma/generated/models/{pull_output.rb → run_action_output.rb} +21 -34
- data/lib/appnigma/generated/models/run_input.rb +3 -3
- 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 +32 -3
- data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
- data/lib/appnigma/generated/version.rb +1 -1
- data/lib/appnigma/generated.rb +14 -7
- data/lib/appnigma/names.rb +9 -0
- data/lib/appnigma/platforms.rb +18 -0
- data/lib/appnigma/retry.rb +3 -3
- data/lib/appnigma/version.rb +2 -2
- metadata +15 -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: dcfba5cb315befdc793a14a4d2c51f906ff53c158df45fb8efac0d81a68fe5fb
|
|
4
|
+
data.tar.gz: 275e4997aebeca6e3ad53d8f082b30d71ac7823eec327c0de4980b91d9232752
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: c93b5f5778a9fe7a74e979c1f834c4798ccfc9363f2ad1152df67713cfc26a4ce9b42304153bbf8292b8ddabae16d04f96cf7859591d16aba08adbe5347e99b8
|
|
7
|
+
data.tar.gz: b52eb1c088777116383c6ed41faac540190f21a32542f0402add3cbe4c56e913486927567024316c4b4d4957ced96df862d60cd6298679d22800bd73487f51fc
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.0.0](https://github.com/Appnigma/ap-sdks/compare/ruby-v0.2.1...ruby-v1.0.0) (2026-10-26)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* `post` and `pull` are removed from all three SDKs. Use `crm.*.create` / `update` / `list` / `get` instead.
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* 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))
|
|
13
|
+
|
|
3
14
|
## [0.2.1](https://github.com/Appnigma/ap-sdks/compare/ruby-v0.2.0...ruby-v0.2.1) (2026-10-26)
|
|
4
15
|
|
|
5
16
|
|
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
|
|
@@ -118,7 +78,7 @@ link = client.connections.create_link(
|
|
|
118
78
|
puts "send the end customer to #{link[:url]} before #{link[:expires_at]}"
|
|
119
79
|
|
|
120
80
|
connection = client.connections.get(end_customer_id: "lawfirm-123", platform: "hubspot")
|
|
121
|
-
puts "ready to
|
|
81
|
+
puts "ready to read and write" if connection[:status] == "connected"
|
|
122
82
|
```
|
|
123
83
|
|
|
124
84
|
`status` is `connected`, `needs_reconnect` or `disconnected`. An end customer
|
|
@@ -132,9 +92,11 @@ the request would reach the wrong route. Do not use them as end customer ids.
|
|
|
132
92
|
|
|
133
93
|
## CRM data in one shape: crm
|
|
134
94
|
|
|
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:`.
|
|
95
|
+
`crm.contacts`, `crm.companies` and `crm.deals` read and write an end
|
|
96
|
+
customer's CRM in one shape, whichever CRM they use. Each has `list`, `get`,
|
|
97
|
+
`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.
|
|
138
100
|
|
|
139
101
|
```ruby
|
|
140
102
|
page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "attio", limit: 50)
|
|
@@ -161,8 +123,59 @@ left out.
|
|
|
161
123
|
is exactly what the CRM sent. A platform with no unified data yet for that
|
|
162
124
|
object is an `Appnigma::NotAvailableError` with `DATA_TYPE_NOT_AVAILABLE`;
|
|
163
125
|
reach it with `request` instead. An id that does not exist is an
|
|
164
|
-
`Appnigma::NotFoundError` with `RECORD_NOT_FOUND`. Reads are retried
|
|
165
|
-
|
|
126
|
+
`Appnigma::NotFoundError` with `RECORD_NOT_FOUND`. Reads are retried.
|
|
127
|
+
|
|
128
|
+
### Writing: create and update
|
|
129
|
+
|
|
130
|
+
`create` makes a record and `update` changes one, from the fields you give in
|
|
131
|
+
the shapes they are read in. Both answer the record as `get` reads it.
|
|
132
|
+
|
|
133
|
+
```ruby
|
|
134
|
+
contact = client.crm.contacts.create(
|
|
135
|
+
end_customer_id: "lawfirm-123",
|
|
136
|
+
platform: "hubspot",
|
|
137
|
+
record: { first_name: "Jane", last_name: "Doe", emails: [{ value: "jane@firm.com", type: "work", primary: true }] }
|
|
138
|
+
)[:record]
|
|
139
|
+
|
|
140
|
+
client.crm.contacts.update(end_customer_id: "lawfirm-123", platform: "hubspot", id: contact[:id],
|
|
141
|
+
record: { last_name: "King", owner_id: nil })
|
|
142
|
+
|
|
143
|
+
client.crm.deals.create(end_customer_id: "lawfirm-123", platform: "pipedrive",
|
|
144
|
+
record: { name: "Retainer", amount: 1200, currency: "USD" }, match_key: "inv_1042")
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- **What you can write.** The fields in the table above, except `id`,
|
|
148
|
+
`platform`, the times, `custom_fields`, `raw` and a deal's `closed_at`, which
|
|
149
|
+
are the CRM's to set. A stage or a pipeline is written as its id.
|
|
150
|
+
- **`nil` clears a field;** a field left out is left alone.
|
|
151
|
+
- **Matching.** A contact with an email, or a company with a domain, updates
|
|
152
|
+
the record the CRM already has with it rather than making a second one. A
|
|
153
|
+
deal has no such field, so pass `match_key:`, a key of your own such as your
|
|
154
|
+
invoice id: the same key updates the same deal.
|
|
155
|
+
- **Repeats.** A create that matches, and an update, are retried like reads,
|
|
156
|
+
because a repeat changes the same record. A create with nothing to match on
|
|
157
|
+
is made once, because a repeat could make a second record.
|
|
158
|
+
- **Refusals.** A field this CRM cannot be told is an `Appnigma::InputError`
|
|
159
|
+
naming it, sent nowhere. A write the end customer's connection lacks the
|
|
160
|
+
scope for is an `Appnigma::AuthError` with `MISSING_SCOPES`, and
|
|
161
|
+
`details["missing"]` names the scopes: the end customer has to connect
|
|
162
|
+
again. A value the CRM itself refuses is an
|
|
163
|
+
`Appnigma::PlatformRefusedError` with its reason.
|
|
164
|
+
|
|
165
|
+
## Which platforms: platforms
|
|
166
|
+
|
|
167
|
+
`platforms.list` names each platform switched on for you, and how much of it
|
|
168
|
+
the shared shapes cover.
|
|
169
|
+
|
|
170
|
+
```ruby
|
|
171
|
+
client.platforms.list[:platforms].each do |platform|
|
|
172
|
+
puts "#{platform[:label]}: #{platform[:support]}"
|
|
173
|
+
end
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
`support` is `supported` when `crm` reads and writes it, with `coverage`
|
|
177
|
+
naming each object and its actions, or `experimental` when only `request`
|
|
178
|
+
reaches it so far.
|
|
166
179
|
|
|
167
180
|
## Anything else on the platform: request
|
|
168
181
|
|
|
@@ -188,12 +201,12 @@ The answer is the platform's own: its `status`, its `headers` (content type,
|
|
|
188
201
|
paging and rate limits) and its `body`, parsed from JSON when the platform
|
|
189
202
|
answered JSON and as text otherwise. A refusal from the platform comes back
|
|
190
203
|
the same way, with its status, rather than as an error: check
|
|
191
|
-
`answer[:status]`. A `GET` is retried like
|
|
204
|
+
`answer[:status]`. A `GET` is retried like a read; any other method is made
|
|
192
205
|
once, because only you know whether repeating it is harmless.
|
|
193
206
|
|
|
194
207
|
## Your own functions: catalog
|
|
195
208
|
|
|
196
|
-
|
|
209
|
+
Your microserver can also hold functions written for you.
|
|
197
210
|
`catalog` lists them, with the platform each one is for and the JSON Schema of
|
|
198
211
|
its input and output. Leave `platform:` out for every platform,
|
|
199
212
|
or name one to narrow the list.
|
|
@@ -241,7 +254,9 @@ function's live version. A name that exists only on another platform is an
|
|
|
241
254
|
that was live and was removed from your logic is retired: calling it is an
|
|
242
255
|
`Appnigma::RetiredError` with `FUNCTION_RETIRED`, whose `details` name the
|
|
243
256
|
function and when it was retired. A platform that is not switched on for you
|
|
244
|
-
is an `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`.
|
|
257
|
+
is an `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`. When the function's
|
|
258
|
+
platform refuses what it sent, it is an `Appnigma::PlatformRefusedError`
|
|
259
|
+
carrying the platform's reason.
|
|
245
260
|
|
|
246
261
|
`run` is made once and never retried: it is your own function, and only you
|
|
247
262
|
know whether running it twice is harmless. If it fails with a network or
|
|
@@ -250,7 +265,8 @@ server error, decide in your code whether to call again.
|
|
|
250
265
|
## Your own guide
|
|
251
266
|
|
|
252
267
|
One page, written for your company: install, the key, connecting an end
|
|
253
|
-
customer to each platform switched on for you,
|
|
268
|
+
customer to each platform switched on for you, reading and writing records,
|
|
269
|
+
`run`, every
|
|
254
270
|
one of your functions with its fields and an example call, and every error
|
|
255
271
|
with what to do about it. `guide` answers it as markdown, built from what is
|
|
256
272
|
live right now.
|
|
@@ -270,18 +286,19 @@ your key or a token.
|
|
|
270
286
|
| Class | When | Extra field |
|
|
271
287
|
| --- | --- | --- |
|
|
272
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: }` |
|
|
273
|
-
| `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled,
|
|
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. | |
|
|
274
290
|
| `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
291
|
| `Appnigma::ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
|
|
276
292
|
| `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
|
|
277
293
|
| `Appnigma::RetiredError` | 410 with `FUNCTION_RETIRED`. The function was live and was removed from your logic; it will not answer again. | |
|
|
294
|
+
| `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` |
|
|
278
295
|
| `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
296
|
| `Appnigma::ServerError` | Any 5xx, after the retries. Also any answer that is not JSON. | |
|
|
280
297
|
| `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
298
|
|
|
282
299
|
```ruby
|
|
283
300
|
begin
|
|
284
|
-
client.
|
|
301
|
+
client.crm.contacts.create(end_customer_id: "lawfirm-123", platform: "hubspot", record: { first_name: "Jane" })
|
|
285
302
|
rescue Appnigma::InputError => e
|
|
286
303
|
e.problems.each { |problem| puts "#{problem[:field]} #{problem[:problem]}" }
|
|
287
304
|
rescue Appnigma::AuthError => e
|
|
@@ -290,6 +307,8 @@ rescue Appnigma::NotFoundError
|
|
|
290
307
|
puts "this end customer is not connected yet"
|
|
291
308
|
rescue Appnigma::ReconnectError
|
|
292
309
|
puts "ask the end customer to connect again"
|
|
310
|
+
rescue Appnigma::PlatformRefusedError => e
|
|
311
|
+
puts "the CRM refused it: #{e.message}"
|
|
293
312
|
rescue Appnigma::RateLimitError => e
|
|
294
313
|
puts "wait #{e.retry_after_seconds} seconds"
|
|
295
314
|
rescue Appnigma::ServerError => e
|
|
@@ -316,16 +335,18 @@ never replaced.
|
|
|
316
335
|
## Retries and time limits
|
|
317
336
|
|
|
318
337
|
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.
|
|
338
|
+
reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409, 410
|
|
339
|
+
or 422 is never retried, because the same call would be refused the same way.
|
|
340
|
+
By default a call is made up to three times.
|
|
322
341
|
|
|
323
|
-
`connections.create_link`, `run`,
|
|
324
|
-
are the exceptions: each is made
|
|
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
|
|
325
345
|
`create_link` makes a new link, and a repeat after a lost answer would leave a
|
|
326
346
|
working link nobody saw; `run` is your own function, and whether a repeat is
|
|
327
|
-
harmless is yours to know
|
|
328
|
-
|
|
347
|
+
harmless is yours to know; a create with nothing to match on could make a
|
|
348
|
+
second record. If one of them fails, decide in your code whether to call
|
|
349
|
+
again.
|
|
329
350
|
|
|
330
351
|
The wait between tries is what the `Retry-After` header says when the server
|
|
331
352
|
sent one, otherwise half a second and then a second, with a little random
|
|
@@ -339,7 +360,7 @@ of time counts as a network failure and is retried like one. Each call can set
|
|
|
339
360
|
its own limit:
|
|
340
361
|
|
|
341
362
|
```ruby
|
|
342
|
-
page = client.
|
|
363
|
+
page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "hubspot", limit: 1, timeout_ms: 10_000)
|
|
343
364
|
puts "one record: #{page[:records].size}"
|
|
344
365
|
```
|
|
345
366
|
|
|
@@ -358,7 +379,7 @@ Per call, as a keyword argument: `timeout_ms:`.
|
|
|
358
379
|
|
|
359
380
|
## What is exported
|
|
360
381
|
|
|
361
|
-
`Appnigma::Client`, `Appnigma::Error` and its
|
|
382
|
+
`Appnigma::Client`, `Appnigma::Error` and its ten subclasses, the constants
|
|
362
383
|
`Appnigma::ERROR_CODES`, `Appnigma::OBJECTS`, `Appnigma::CONNECTION_STATUSES`
|
|
363
384
|
and `Appnigma::PLATFORM_REQUEST_METHODS`, `Appnigma::VERSION`, and
|
|
364
385
|
`Appnigma::API_DESCRIPTION_VERSION`, the version of the published description
|
data/lib/appnigma/client.rb
CHANGED
|
@@ -7,6 +7,7 @@ require_relative "retry"
|
|
|
7
7
|
require_relative "transport"
|
|
8
8
|
require_relative "connections"
|
|
9
9
|
require_relative "crm"
|
|
10
|
+
require_relative "platforms"
|
|
10
11
|
|
|
11
12
|
module Appnigma
|
|
12
13
|
# What a customer creates. The key comes from `key:` or from the
|
|
@@ -15,12 +16,12 @@ module Appnigma
|
|
|
15
16
|
# before any call.
|
|
16
17
|
#
|
|
17
18
|
# Every call takes keyword arguments in Ruby style and answers a Hash with
|
|
18
|
-
# symbol keys in Ruby style, except inside content that is not ours (a
|
|
19
|
-
# record's
|
|
20
|
-
# which comes back exactly as it was sent. Every call
|
|
21
|
-
# `timeout_ms:`, the time limit of one attempt.
|
|
19
|
+
# symbol keys in Ruby style, except inside content that is not ours (a CRM
|
|
20
|
+
# record's raw form and custom field names, a function's input and output,
|
|
21
|
+
# a platform's answer), which comes back exactly as it was sent. Every call
|
|
22
|
+
# also takes `timeout_ms:`, the time limit of one attempt.
|
|
22
23
|
class Client
|
|
23
|
-
attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms, :connections, :crm
|
|
24
|
+
attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms, :connections, :crm, :platforms
|
|
24
25
|
|
|
25
26
|
# `transport` is for tests; a customer never passes it.
|
|
26
27
|
def initialize(key: nil, timeout_ms: DEFAULT_TIMEOUT_MS, max_retries: DEFAULT_MAX_RETRIES,
|
|
@@ -34,29 +35,12 @@ module Appnigma
|
|
|
34
35
|
# A write whose repeat is not harmless gets one attempt. create_link
|
|
35
36
|
# makes a new link every time; run is your own function, and only you
|
|
36
37
|
# know whether running it twice is harmless; request with a method
|
|
37
|
-
# other than GET may change the platform
|
|
38
|
-
#
|
|
38
|
+
# other than GET may change the platform; a crm create with nothing to
|
|
39
|
+
# match on could make a second record. A crm create that matches, and
|
|
40
|
+
# a crm update, are retried because a repeat changes the same record.
|
|
39
41
|
@one_attempt = Retry::Policy.new(max_retries: 0, max_retry_wait_ms: @max_retry_wait_ms)
|
|
40
42
|
@transport = transport || Transport.new(base_url: @base_url, key: @key)
|
|
41
|
-
|
|
42
|
-
@crm = Crm.new(self)
|
|
43
|
-
end
|
|
44
|
-
|
|
45
|
-
# Creates a record in the end customer's HubSpot, or updates the one that
|
|
46
|
-
# already matches on `unique_by` (email for a contact unless you name
|
|
47
|
-
# another property; required for a company and a deal).
|
|
48
|
-
def post(end_customer_id:, platform:, object:, record:, unique_by: nil, timeout_ms: nil)
|
|
49
|
-
body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, object: object, record: record,
|
|
50
|
-
unique_by: unique_by)
|
|
51
|
-
call(:post_record, body, timeout_ms: timeout_ms)
|
|
52
|
-
end
|
|
53
|
-
|
|
54
|
-
# One page of records and a marker for the next; `next` is nil on the
|
|
55
|
-
# last page. `limit` is 1 to 100.
|
|
56
|
-
def pull(end_customer_id:, platform:, object:, limit: nil, after: nil, timeout_ms: nil)
|
|
57
|
-
body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, object: object, limit: limit,
|
|
58
|
-
after: after)
|
|
59
|
-
call(:pull_records, body, timeout_ms: timeout_ms)
|
|
43
|
+
start_groups
|
|
60
44
|
end
|
|
61
45
|
|
|
62
46
|
# One of your own functions, by platform and name: its live version runs,
|
|
@@ -96,11 +80,20 @@ module Appnigma
|
|
|
96
80
|
read_answer(answer)
|
|
97
81
|
end
|
|
98
82
|
|
|
99
|
-
# Used by Connections
|
|
100
|
-
|
|
83
|
+
# Used by Connections and Crm: the policy for a call made once, and the
|
|
84
|
+
# one for a call that is retried.
|
|
85
|
+
attr_reader :one_attempt, :policy
|
|
101
86
|
|
|
102
87
|
private
|
|
103
88
|
|
|
89
|
+
# The calls grouped by what they reach: `connections`, `crm` and
|
|
90
|
+
# `platforms`.
|
|
91
|
+
def start_groups
|
|
92
|
+
@connections = Connections.new(self)
|
|
93
|
+
@crm = Crm.new(self)
|
|
94
|
+
@platforms = Platforms.new(self)
|
|
95
|
+
end
|
|
96
|
+
|
|
104
97
|
# A success whose body is not JSON is a server error: a proxy page or an
|
|
105
98
|
# empty body is never handed back as data.
|
|
106
99
|
def read_answer(answer)
|
data/lib/appnigma/constants.rb
CHANGED
data/lib/appnigma/crm.rb
CHANGED
|
@@ -5,22 +5,57 @@ require_relative "names"
|
|
|
5
5
|
module Appnigma
|
|
6
6
|
# An end customer's CRM data in one shape, whichever CRM they use:
|
|
7
7
|
# `client.crm.contacts`, `client.crm.companies` and `client.crm.deals`,
|
|
8
|
-
# each with `list` and `
|
|
8
|
+
# each with `list`, `get`, `create` and `update`.
|
|
9
9
|
class Crm
|
|
10
10
|
attr_reader :contacts, :companies, :deals
|
|
11
11
|
|
|
12
12
|
def initialize(client)
|
|
13
|
-
@contacts = Objects.new(client, list: :list_crm_contacts, get: :get_crm_contact
|
|
14
|
-
|
|
15
|
-
@
|
|
13
|
+
@contacts = Objects.new(client, list: :list_crm_contacts, get: :get_crm_contact, create: :create_crm_contact,
|
|
14
|
+
update: :update_crm_contact, matches_on: ->(record, _key) { Crm.email?(record) })
|
|
15
|
+
@companies = Objects.new(client, list: :list_crm_companies, get: :get_crm_company,
|
|
16
|
+
create: :create_crm_company, update: :update_crm_company,
|
|
17
|
+
matches_on: ->(record, _key) { Crm.domain?(Crm.field(record, :domain)) })
|
|
18
|
+
@deals = Objects.new(client, list: :list_crm_deals, get: :get_crm_deal, create: :create_crm_deal,
|
|
19
|
+
update: :update_crm_deal, matches_on: ->(_record, key) { Crm.text?(key) })
|
|
16
20
|
end
|
|
17
21
|
|
|
18
|
-
#
|
|
22
|
+
# A record's field, whether it was given as a symbol or a string, in
|
|
23
|
+
# Ruby's name or the wire's.
|
|
24
|
+
def self.field(record, name)
|
|
25
|
+
return nil unless record.is_a?(Hash)
|
|
26
|
+
|
|
27
|
+
[name, name.to_s, Names.to_camel(name), Names.to_camel(name).to_sym].each do |key|
|
|
28
|
+
return record[key] if record.key?(key)
|
|
29
|
+
end
|
|
30
|
+
nil
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
def self.text?(value)
|
|
34
|
+
value.is_a?(String) && !value.strip.empty?
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# As the server reads a domain to match on: something with a dot once any
|
|
38
|
+
# scheme, `www.` and path are taken off.
|
|
39
|
+
def self.domain?(value)
|
|
40
|
+
return false unless value.is_a?(String)
|
|
41
|
+
|
|
42
|
+
value.strip.downcase.sub(%r{\Ahttps?://}, "").sub(/\Awww\./, "").split(%r{[/?#]}).first.to_s.include?(".")
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
def self.email?(record)
|
|
46
|
+
emails = field(record, :emails)
|
|
47
|
+
emails.is_a?(Array) && text?(field(emails.first, :value))
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# The reads and writes of one CRM object.
|
|
19
51
|
class Objects
|
|
20
|
-
def initialize(client, list:, get:)
|
|
52
|
+
def initialize(client, list:, get:, create:, update:, matches_on:)
|
|
21
53
|
@client = client
|
|
22
54
|
@list = list
|
|
23
55
|
@get = get
|
|
56
|
+
@create = create
|
|
57
|
+
@update = update
|
|
58
|
+
@matches_on = matches_on
|
|
24
59
|
end
|
|
25
60
|
|
|
26
61
|
# One page of records and a marker for the next; pass `next` as
|
|
@@ -35,6 +70,28 @@ module Appnigma
|
|
|
35
70
|
body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, id: id)
|
|
36
71
|
@client.call(@get, body, timeout_ms: timeout_ms)
|
|
37
72
|
end
|
|
73
|
+
|
|
74
|
+
# Creates a record from the fields given, in the shapes they are read
|
|
75
|
+
# in, and answers it as `get` reads it. A contact with an email, a
|
|
76
|
+
# company with a domain, or a deal with a `match_key` of your own
|
|
77
|
+
# updates the record that already has it, so the call is retried like
|
|
78
|
+
# a read; with nothing to match on it is made once, because a repeat
|
|
79
|
+
# could make a second record.
|
|
80
|
+
def create(end_customer_id:, platform:, record:, match_key: nil, timeout_ms: nil)
|
|
81
|
+
body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform,
|
|
82
|
+
record: Names.record_keys(record), match_key: match_key)
|
|
83
|
+
policy = @matches_on.call(record, match_key) ? @client.policy : @client.one_attempt
|
|
84
|
+
@client.call(@create, body, policy: policy, timeout_ms: timeout_ms)
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
# Changes the fields given on the record with this id, and answers it as
|
|
88
|
+
# `get` reads it. `nil` clears a field; a field left out is left alone.
|
|
89
|
+
# Sending the same values again changes nothing, so it is retried.
|
|
90
|
+
def update(end_customer_id:, platform:, id:, record:, timeout_ms: nil)
|
|
91
|
+
body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, id: id,
|
|
92
|
+
record: Names.record_keys(record))
|
|
93
|
+
@client.call(@update, body, timeout_ms: timeout_ms)
|
|
94
|
+
end
|
|
38
95
|
end
|
|
39
96
|
end
|
|
40
97
|
end
|
data/lib/appnigma/errors.rb
CHANGED
|
@@ -48,6 +48,20 @@ module Appnigma
|
|
|
48
48
|
# Any other 409: the platform cannot give this yet.
|
|
49
49
|
class NotAvailableError < Error; end
|
|
50
50
|
|
|
51
|
+
# 422 PLATFORM_REFUSED: the end customer's platform refused the call, and
|
|
52
|
+
# `message` is its reason. Never tried again: the same call would be
|
|
53
|
+
# refused the same way. `platform_status` is the status the platform
|
|
54
|
+
# answered, or nil.
|
|
55
|
+
class PlatformRefusedError < Error
|
|
56
|
+
attr_reader :platform_status
|
|
57
|
+
|
|
58
|
+
def initialize(**args)
|
|
59
|
+
super
|
|
60
|
+
status = details["status"]
|
|
61
|
+
@platform_status = status.is_a?(Integer) ? status : nil
|
|
62
|
+
end
|
|
63
|
+
end
|
|
64
|
+
|
|
51
65
|
# 429. `retry_after_seconds` is what the server's Retry-After header said,
|
|
52
66
|
# or nil when it sent none.
|
|
53
67
|
class RateLimitError < Error
|
|
@@ -88,6 +102,7 @@ module Appnigma
|
|
|
88
102
|
403 => AuthError,
|
|
89
103
|
404 => NotFoundError,
|
|
90
104
|
410 => RetiredError,
|
|
105
|
+
422 => PlatformRefusedError,
|
|
91
106
|
429 => RateLimitError
|
|
92
107
|
}.freeze
|
|
93
108
|
|