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.
Files changed (80) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +25 -0
  3. data/README.md +230 -97
  4. data/lib/appnigma/checks.rb +29 -5
  5. data/lib/appnigma/client.rb +38 -37
  6. data/lib/appnigma/connections.rb +25 -5
  7. data/lib/appnigma/constants.rb +15 -8
  8. data/lib/appnigma/crm.rb +63 -6
  9. data/lib/appnigma/errors.rb +45 -4
  10. data/lib/appnigma/generated/api/default_api.rb +824 -129
  11. data/lib/appnigma/generated/api_client.rb +1 -1
  12. data/lib/appnigma/generated/api_error.rb +1 -1
  13. data/lib/appnigma/generated/api_model_base.rb +1 -1
  14. data/lib/appnigma/generated/configuration.rb +1 -1
  15. data/lib/appnigma/generated/models/action_entry.rb +341 -0
  16. data/lib/appnigma/generated/models/connection_status.rb +3 -2
  17. data/lib/appnigma/generated/models/create_connection_link_input.rb +2 -13
  18. data/lib/appnigma/generated/models/create_connection_link_output.rb +2 -2
  19. data/lib/appnigma/generated/models/{post_output.rb → create_portal_link_input.rb} +20 -46
  20. data/lib/appnigma/generated/models/{pull_output_records_inner.rb → create_portal_link_output.rb} +37 -37
  21. data/lib/appnigma/generated/models/crm_company.rb +1 -1
  22. data/lib/appnigma/generated/models/crm_company_get_output.rb +1 -1
  23. data/lib/appnigma/generated/models/crm_company_list_output.rb +1 -1
  24. data/lib/appnigma/generated/models/crm_company_write_output.rb +177 -0
  25. data/lib/appnigma/generated/models/crm_contact.rb +1 -1
  26. data/lib/appnigma/generated/models/crm_contact_get_output.rb +1 -1
  27. data/lib/appnigma/generated/models/crm_contact_list_output.rb +1 -1
  28. data/lib/appnigma/generated/models/crm_contact_write_output.rb +177 -0
  29. data/lib/appnigma/generated/models/crm_create_input.rb +245 -0
  30. data/lib/appnigma/generated/models/crm_custom_field.rb +1 -1
  31. data/lib/appnigma/generated/models/crm_deal.rb +1 -1
  32. data/lib/appnigma/generated/models/{post_input.rb → crm_deal_create_input.rb} +48 -92
  33. data/lib/appnigma/generated/models/crm_deal_get_output.rb +1 -1
  34. data/lib/appnigma/generated/models/crm_deal_list_output.rb +1 -1
  35. data/lib/appnigma/generated/models/crm_deal_write_output.rb +177 -0
  36. data/lib/appnigma/generated/models/crm_email.rb +1 -1
  37. data/lib/appnigma/generated/models/crm_get_input.rb +2 -13
  38. data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
  39. data/lib/appnigma/generated/models/crm_list_input.rb +2 -13
  40. data/lib/appnigma/generated/models/crm_phone.rb +1 -1
  41. data/lib/appnigma/generated/models/{pull_input.rb → crm_update_input.rb} +67 -112
  42. data/lib/appnigma/generated/models/end_customer.rb +247 -0
  43. data/lib/appnigma/generated/models/end_customer_connection.rb +239 -0
  44. data/lib/appnigma/generated/models/function_entry.rb +74 -5
  45. data/lib/appnigma/generated/models/function_owner.rb +1 -1
  46. data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
  47. data/lib/appnigma/generated/models/function_owner_one_of1.rb +18 -17
  48. data/lib/appnigma/generated/models/get_connection_input.rb +216 -0
  49. data/lib/appnigma/generated/models/get_connection_output.rb +18 -5
  50. data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
  51. data/lib/appnigma/generated/models/json_value.rb +1 -1
  52. data/lib/appnigma/generated/models/list_actions_output.rb +179 -0
  53. data/lib/appnigma/generated/models/{pull_output.rb → list_connections_output.rb} +23 -21
  54. data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
  55. data/lib/appnigma/generated/models/list_platforms_output.rb +179 -0
  56. data/lib/appnigma/generated/models/logic_conditional.rb +247 -0
  57. data/lib/appnigma/generated/models/platform_entry.rb +269 -0
  58. data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +219 -0
  59. data/lib/appnigma/generated/models/platform_request_input.rb +2 -13
  60. data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
  61. data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
  62. data/lib/appnigma/generated/models/ran_as.rb +4 -6
  63. data/lib/appnigma/generated/models/run_action_input.rb +266 -0
  64. data/lib/appnigma/generated/models/run_action_output.rb +178 -0
  65. data/lib/appnigma/generated/models/run_input.rb +39 -26
  66. data/lib/appnigma/generated/models/run_output.rb +1 -1
  67. data/lib/appnigma/generated/models/sdk_error.rb +1 -1
  68. data/lib/appnigma/generated/models/sdk_error_error.rb +3 -3
  69. data/lib/appnigma/generated/models/sdk_error_error_details.rb +41 -3
  70. data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
  71. data/lib/appnigma/generated/version.rb +1 -1
  72. data/lib/appnigma/generated.rb +21 -7
  73. data/lib/appnigma/names.rb +9 -0
  74. data/lib/appnigma/platforms.rb +18 -0
  75. data/lib/appnigma/portal.rb +21 -0
  76. data/lib/appnigma/retry.rb +3 -3
  77. data/lib/appnigma/transport.rb +4 -4
  78. data/lib/appnigma/version.rb +2 -2
  79. metadata +23 -7
  80. 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: b52aba7ed80e5bdfbc22ade56d649b1b11464cafa70243807bb4b3609f58efda
4
+ data.tar.gz: d814d25d0d3fe960cce4484d75acfffa4f536039de9bb2558d7f516d601ed55c
5
5
  SHA512:
6
- metadata.gz: 1a837ce176625edb9dbf5b0150c4f742dbd830e662594099b2b49c619a0568c9e395579479a408cbf2464ffb3182014a07857c9454c56880072de897798f898d
7
- data.tar.gz: 53ea5d5c768d972cdfd2d33fbd5c31688c93bf3a589b2b30ccc7472c812576c9cf0a6b0c2ee63335d81378ac92a214876fa5bbba489fbf35fe71aadbd427c4d5
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 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
@@ -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 post and pull" if connection[:status] == "connected"
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`. An end customer
87
+ `status` is `pending`, `connected`, `needs_reconnect` or `disconnected`.
88
+ `pending` is an end customer who was sent a connect link and has not approved
89
+ yet: they exist from the moment the link is made. An end customer
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
- The id travels in the URL for this call, so an id that is only `.` or `..` is
130
- refused before the call with `Appnigma::InputError`: a URL drops those, and
131
- the request would reach the wrong route. Do not use them as end customer ids.
94
+ `logic_folder_key` is where this end customer's own functions go in your logic
95
+ repo: `src/logic/end-customers/<logic_folder_key>/<platform>/`. It is one key
96
+ per end customer, the same on every platform, and the Microserver page shows
97
+ it next to them with a copy button. It is `nil` only for a connection made
98
+ before the key existed, until Appnigma has filled it in.
99
+
100
+ An id outside the rule below is refused before the call with
101
+ `Appnigma::InputError`, the same refusal the server would give.
102
+
103
+ ## Listing your end customers: connections.list
104
+
105
+ `connections.list` answers your end customers one page at a time, in id order:
106
+ each with their `end_customer_id`, their `logic_folder_key`,
107
+ `has_custom_logic` (`true` when a function written for them is live) and every
108
+ connection of theirs, with its `platform`, `status` and `connected_at` (ISO
109
+ 8601 in UTC, `nil` while pending). Give `platform:` or `status:` to keep only
110
+ the end customers with at least one connection that matches; each entry still
111
+ lists all of their connections. `limit:` is 1 to 100, 50 if left out; `next`
112
+ is `nil` on the last page, otherwise pass it back as `cursor:`, exactly as it
113
+ came. It is the list to build your own integrations screen from, and the way
114
+ to find who must connect again:
115
+
116
+ ```ruby
117
+ page = client.connections.list(status: "needs_reconnect")
118
+ page[:end_customers].each do |end_customer|
119
+ lost = end_customer[:connections].select { |c| c[:status] == "needs_reconnect" }.map { |c| c[:platform] }
120
+ puts "#{end_customer[:end_customer_id]} must connect again on #{lost.join(', ')}"
121
+ end
122
+
123
+ # More pages, while there is one.
124
+ client.connections.list(status: "needs_reconnect", cursor: page[:next]) if page[:next]
125
+ ```
126
+
127
+ A `platform:` that is not switched on for your company is an
128
+ `Appnigma::AuthError` with `PLATFORM_NOT_ENABLED`; a `status:` outside the
129
+ four, a `limit:` outside 1 to 100, or a `cursor:` this list did not give you
130
+ is an `Appnigma::InputError` naming the field. An empty list is not an error.
131
+ Reads are retried.
132
132
 
133
133
  ## CRM data in one shape: crm
134
134
 
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:`.
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 like
165
- `pull`.
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 `pull`; any other method is made
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
- Beyond `post` and `pull`, your microserver can hold functions written for you.
197
- `catalog` lists them, with the platform each one is for and the JSON Schema of
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", end_customer_id: "..." }` when it was written
209
- for one of them. `input_schema` and `output_schema` are JSON Schema, as
210
- written. Each function has one live version: a change to it replaces it when
211
- the change goes live. Until a function has gone live for you, the list is
212
- empty, not an error.
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 end customer. The input
217
- is checked against the function's shape before anything runs, so a wrong or
218
- missing field is an `Appnigma::InputError` listing every problem. Formats and
219
- patterns, such as an email or a fixed layout for a code, are checked by the
220
- function itself, so those refusals arrive from it with the same code. The
221
- answer is `{ output: ..., ran_as: ... }`: the output in the shape the function
222
- declared, with its keys as the function wrote them, and whose function ran.
223
- `ran_as[:owner]` is `"end_customer"` when the end customer has a function of
224
- their own by that name and it ran, `"customer"` when yours did;
225
- `ran_as[:version]` is the version that ran.
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` and `function_name` are both required: the same name can exist on
238
- two platforms and mean two different things. What runs is always the
239
- function's live version. A name that exists only on another platform is an
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, `post`, `pull` and `run`, every
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 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. | |
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.post(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", record: {})
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 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.
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`, and `request` with a method other than `GET`
324
- are the exceptions: each is made once, never retried. Every call to
454
+ `connections.create_link`, `portal.create_link`, `run`, `request` with a
455
+ method other than `GET`, and a `crm` create with nothing to match on are the
456
+ exceptions: each is made once, never retried. Every call to
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. If either fails, decide in your code whether to
328
- call again.
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.pull(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", limit: 1, timeout_ms: 10_000)
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 nine subclasses, the constants
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
@@ -49,21 +49,45 @@ module Appnigma
49
49
  refuse("max_retry_wait_ms", "must be a number of milliseconds from 0 to #{MAX_TIMER_MS}")
50
50
  end
51
51
 
52
+ # The server's own rule, applied first so a bad id is refused with the
53
+ # same words before any call. A string that is not valid in its encoding
54
+ # (a lone surrogate, say) is not text and is refused the same way.
52
55
  def end_customer_id!(value)
53
- unless value.is_a?(String) && value.match?(END_CUSTOMER_ID_PATTERN)
54
- refuse("end_customer_id",
55
- END_CUSTOMER_ID_RULE)
56
- end
57
- refuse("end_customer_id", END_CUSTOMER_ID_PATH_RULE) if END_CUSTOMER_ID_PATH_UNSAFE.include?(value)
56
+ refuse("end_customer_id", END_CUSTOMER_ID_RULE) unless value.is_a?(String) && end_customer_id?(value)
58
57
  value
59
58
  end
60
59
 
60
+ def end_customer_id?(value)
61
+ value.valid_encoding? &&
62
+ value.length.between?(1, END_CUSTOMER_ID_MAX_LENGTH) &&
63
+ !value.match?(END_CUSTOMER_ID_FORBIDDEN_PATTERN) &&
64
+ !value.match?(END_CUSTOMER_ID_ONLY_SPACES_PATTERN)
65
+ end
66
+
61
67
  def platform!(value)
62
68
  return value if value.is_a?(String) && !value.empty?
63
69
 
64
70
  refuse("platform", "must be a platform key, such as hubspot")
65
71
  end
66
72
 
73
+ # `run` names its function by name or by id, never both, as the server
74
+ # requires. A nil counts as left out, since a nil is never sent.
75
+ def function_name_or_id!(function_name, function_id)
76
+ if function_name.nil? && function_id.nil?
77
+ refuse("function_name", "is required, or function_id")
78
+ elsif !function_name.nil? && !function_id.nil?
79
+ refuse("function_id", "must be left out when function_name is sent: send one or the other")
80
+ end
81
+ end
82
+
83
+ # 19.3: a status outside the four is refused before any call, with the
84
+ # server's words.
85
+ def connection_status!(value)
86
+ return value if CONNECTION_STATUSES.include?(value)
87
+
88
+ refuse("status", "must be one of #{CONNECTION_STATUSES.join(", ")}")
89
+ end
90
+
67
91
  # The setting if there is one, else production. An empty setting counts
68
92
  # as none. Only https, or http to this machine, so a key never crosses a
69
93
  # network unencrypted.