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.
Files changed (69) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +11 -0
  3. data/README.md +90 -69
  4. data/lib/appnigma/client.rb +21 -28
  5. data/lib/appnigma/constants.rb +1 -0
  6. data/lib/appnigma/crm.rb +63 -6
  7. data/lib/appnigma/errors.rb +15 -0
  8. data/lib/appnigma/generated/api/default_api.rb +523 -61
  9. data/lib/appnigma/generated/api_client.rb +1 -1
  10. data/lib/appnigma/generated/api_error.rb +1 -1
  11. data/lib/appnigma/generated/api_model_base.rb +1 -1
  12. data/lib/appnigma/generated/configuration.rb +1 -1
  13. data/lib/appnigma/generated/models/action_entry.rb +341 -0
  14. data/lib/appnigma/generated/models/connection_status.rb +1 -1
  15. data/lib/appnigma/generated/models/create_connection_link_input.rb +1 -1
  16. data/lib/appnigma/generated/models/create_connection_link_output.rb +2 -2
  17. data/lib/appnigma/generated/models/crm_company.rb +1 -1
  18. data/lib/appnigma/generated/models/crm_company_get_output.rb +1 -1
  19. data/lib/appnigma/generated/models/crm_company_list_output.rb +1 -1
  20. data/lib/appnigma/generated/models/{post_output.rb → crm_company_write_output.rb} +20 -46
  21. data/lib/appnigma/generated/models/crm_contact.rb +1 -1
  22. data/lib/appnigma/generated/models/crm_contact_get_output.rb +1 -1
  23. data/lib/appnigma/generated/models/crm_contact_list_output.rb +1 -1
  24. data/lib/appnigma/generated/models/crm_contact_write_output.rb +177 -0
  25. data/lib/appnigma/generated/models/crm_create_input.rb +256 -0
  26. data/lib/appnigma/generated/models/crm_custom_field.rb +1 -1
  27. data/lib/appnigma/generated/models/crm_deal.rb +1 -1
  28. data/lib/appnigma/generated/models/{post_input.rb → crm_deal_create_input.rb} +48 -81
  29. data/lib/appnigma/generated/models/crm_deal_get_output.rb +1 -1
  30. data/lib/appnigma/generated/models/crm_deal_list_output.rb +1 -1
  31. data/lib/appnigma/generated/models/crm_deal_write_output.rb +177 -0
  32. data/lib/appnigma/generated/models/crm_email.rb +1 -1
  33. data/lib/appnigma/generated/models/crm_get_input.rb +1 -1
  34. data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
  35. data/lib/appnigma/generated/models/crm_list_input.rb +1 -1
  36. data/lib/appnigma/generated/models/crm_phone.rb +1 -1
  37. data/lib/appnigma/generated/models/{pull_input.rb → crm_update_input.rb} +66 -100
  38. data/lib/appnigma/generated/models/function_entry.rb +1 -1
  39. data/lib/appnigma/generated/models/function_owner.rb +1 -1
  40. data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
  41. data/lib/appnigma/generated/models/function_owner_one_of1.rb +1 -1
  42. data/lib/appnigma/generated/models/get_connection_output.rb +1 -1
  43. data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
  44. data/lib/appnigma/generated/models/json_value.rb +1 -1
  45. data/lib/appnigma/generated/models/{pull_output_records_inner.rb → list_actions_output.rb} +21 -47
  46. data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
  47. data/lib/appnigma/generated/models/list_platforms_output.rb +179 -0
  48. data/lib/appnigma/generated/models/platform_entry.rb +269 -0
  49. data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +219 -0
  50. data/lib/appnigma/generated/models/platform_request_input.rb +1 -1
  51. data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
  52. data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
  53. data/lib/appnigma/generated/models/ran_as.rb +4 -6
  54. data/lib/appnigma/generated/models/run_action_input.rb +277 -0
  55. data/lib/appnigma/generated/models/{pull_output.rb → run_action_output.rb} +21 -34
  56. data/lib/appnigma/generated/models/run_input.rb +3 -3
  57. data/lib/appnigma/generated/models/run_output.rb +1 -1
  58. data/lib/appnigma/generated/models/sdk_error.rb +1 -1
  59. data/lib/appnigma/generated/models/sdk_error_error.rb +3 -3
  60. data/lib/appnigma/generated/models/sdk_error_error_details.rb +32 -3
  61. data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
  62. data/lib/appnigma/generated/version.rb +1 -1
  63. data/lib/appnigma/generated.rb +14 -7
  64. data/lib/appnigma/names.rb +9 -0
  65. data/lib/appnigma/platforms.rb +18 -0
  66. data/lib/appnigma/retry.rb +3 -3
  67. data/lib/appnigma/version.rb +2 -2
  68. metadata +15 -7
  69. 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: 4e72996c156750c03593d82ddb050a5cd8beeadd4446011aa49491cb795e4c16
4
- data.tar.gz: c799bb5d090ae298307d3cbf4a962a5572873cb9aa468e7bfed2648e25696040
3
+ metadata.gz: dcfba5cb315befdc793a14a4d2c51f906ff53c158df45fb8efac0d81a68fe5fb
4
+ data.tar.gz: 275e4997aebeca6e3ad53d8f082b30d71ac7823eec327c0de4980b91d9232752
5
5
  SHA512:
6
- metadata.gz: 1a837ce176625edb9dbf5b0150c4f742dbd830e662594099b2b49c619a0568c9e395579479a408cbf2464ffb3182014a07857c9454c56880072de897798f898d
7
- data.tar.gz: 53ea5d5c768d972cdfd2d33fbd5c31688c93bf3a589b2b30ccc7472c812576c9cf0a6b0c2ee63335d81378ac92a214876fa5bbba489fbf35fe71aadbd427c4d5
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 sends
4
- records to an end customer's HubSpot, reads them back, reads contacts,
5
- companies and deals in one shape whichever CRM they use, runs your own
6
- functions, calls any platform's API, and connects end customers. One gem for
7
- every customer. Nothing about your account is inside it, and it holds no
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 post and pull" if connection[:status] == "connected"
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 customer's CRM in
136
- one shape, whichever CRM they use. Each has `list` and `get`, and each takes
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 like
165
- `pull`.
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 `pull`; any other method is made
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
- Beyond `post` and `pull`, your microserver can hold functions written for you.
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, `post`, `pull` and `run`, every
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, or the platform is not switched on for you. Also raised at start with no key. | |
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.post(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", record: {})
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 or 410
320
- is never retried, because the same call would be refused the same way. By default
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`, and `request` with a method other than `GET`
324
- are the exceptions: each is made once, never retried. Every call to
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. If either fails, decide in your code whether to
328
- call again.
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.pull(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", limit: 1, timeout_ms: 10_000)
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 nine subclasses, the constants
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
@@ -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 properties, a function's input and output, a platform's answer),
20
- # which comes back exactly as it was sent. Every call also takes
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. post is retried because the
38
- # server updates the record that matches.
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
- @connections = Connections.new(self)
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 for the one call that is never retried.
100
- attr_reader :one_attempt
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)
@@ -67,6 +67,7 @@ module Appnigma
67
67
  CONNECTION_NEEDS_RECONNECT
68
68
  RATE_LIMITED
69
69
  PLATFORM_RATE_LIMITED
70
+ PLATFORM_REFUSED
70
71
  PLATFORM_ERROR
71
72
  TIMED_OUT
72
73
  LOGIC_FAILED
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 `get`. Reads, so they are retried.
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
- @companies = Objects.new(client, list: :list_crm_companies, get: :get_crm_company)
15
- @deals = Objects.new(client, list: :list_crm_deals, get: :get_crm_deal)
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
- # The two reads of one CRM object.
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
@@ -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