appnigma-sdk 2.1.0 → 2.2.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 (168) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +7 -0
  3. data/README.md +567 -26
  4. data/exe/appnigma +8 -0
  5. data/lib/appnigma/actions.rb +33 -0
  6. data/lib/appnigma/checks.rb +13 -0
  7. data/lib/appnigma/client.rb +30 -13
  8. data/lib/appnigma/command.rb +154 -0
  9. data/lib/appnigma/command_files.rb +46 -0
  10. data/lib/appnigma/connect_fields.rb +83 -0
  11. data/lib/appnigma/connections.rb +58 -5
  12. data/lib/appnigma/constants.rb +57 -0
  13. data/lib/appnigma/end_customers.rb +29 -0
  14. data/lib/appnigma/errors.rb +44 -6
  15. data/lib/appnigma/features.rb +19 -0
  16. data/lib/appnigma/files.rb +26 -0
  17. data/lib/appnigma/generated/api/default_api.rb +2103 -402
  18. data/lib/appnigma/generated/api_client.rb +1 -1
  19. data/lib/appnigma/generated/api_error.rb +1 -1
  20. data/lib/appnigma/generated/api_model_base.rb +1 -1
  21. data/lib/appnigma/generated/configuration.rb +1 -1
  22. data/lib/appnigma/generated/models/action_entry.rb +1 -1
  23. data/lib/appnigma/generated/models/check_logic_input.rb +276 -0
  24. data/lib/appnigma/generated/models/check_logic_output.rb +193 -0
  25. data/lib/appnigma/generated/models/client_event.rb +309 -0
  26. data/lib/appnigma/generated/models/client_event_delivery.rb +306 -0
  27. data/lib/appnigma/generated/models/client_event_type.rb +44 -0
  28. data/lib/appnigma/generated/models/client_webhook.rb +346 -0
  29. data/lib/appnigma/generated/models/connect_end_customer_input.rb +243 -0
  30. data/lib/appnigma/generated/models/connect_end_customer_output.rb +294 -0
  31. data/lib/appnigma/generated/models/connect_field.rb +308 -0
  32. data/lib/appnigma/generated/models/connection_status.rb +1 -1
  33. data/lib/appnigma/generated/models/create_connection_link_input.rb +1 -1
  34. data/lib/appnigma/generated/models/create_connection_link_output.rb +1 -1
  35. data/lib/appnigma/generated/models/create_logic_input.rb +273 -0
  36. data/lib/appnigma/generated/models/create_logic_input_trigger.rb +104 -0
  37. data/lib/appnigma/generated/models/create_logic_input_trigger_any_of.rb +257 -0
  38. data/lib/appnigma/generated/models/create_logic_input_trigger_any_of1.rb +238 -0
  39. data/lib/appnigma/generated/models/create_logic_output.rb +230 -0
  40. data/lib/appnigma/generated/models/create_portal_link_input.rb +2 -18
  41. data/lib/appnigma/generated/models/create_portal_link_output.rb +1 -1
  42. data/lib/appnigma/generated/models/create_webhook_input.rb +187 -0
  43. data/lib/appnigma/generated/models/create_webhook_output.rb +204 -0
  44. data/lib/appnigma/generated/models/crm_company.rb +1 -1
  45. data/lib/appnigma/generated/models/crm_company_get_output.rb +1 -1
  46. data/lib/appnigma/generated/models/crm_company_list_output.rb +1 -1
  47. data/lib/appnigma/generated/models/crm_company_write_output.rb +1 -1
  48. data/lib/appnigma/generated/models/crm_contact.rb +1 -1
  49. data/lib/appnigma/generated/models/crm_contact_get_output.rb +1 -1
  50. data/lib/appnigma/generated/models/crm_contact_list_output.rb +1 -1
  51. data/lib/appnigma/generated/models/crm_contact_write_output.rb +1 -1
  52. data/lib/appnigma/generated/models/crm_create_input.rb +1 -1
  53. data/lib/appnigma/generated/models/crm_custom_field.rb +1 -1
  54. data/lib/appnigma/generated/models/crm_deal.rb +1 -1
  55. data/lib/appnigma/generated/models/crm_deal_create_input.rb +1 -1
  56. data/lib/appnigma/generated/models/crm_deal_get_output.rb +1 -1
  57. data/lib/appnigma/generated/models/crm_deal_list_output.rb +1 -1
  58. data/lib/appnigma/generated/models/crm_deal_write_output.rb +1 -1
  59. data/lib/appnigma/generated/models/crm_email.rb +1 -1
  60. data/lib/appnigma/generated/models/crm_get_input.rb +1 -1
  61. data/lib/appnigma/generated/models/crm_labelled.rb +1 -1
  62. data/lib/appnigma/generated/models/crm_list_input.rb +1 -1
  63. data/lib/appnigma/generated/models/crm_phone.rb +1 -1
  64. data/lib/appnigma/generated/models/crm_update_input.rb +1 -1
  65. data/lib/appnigma/generated/models/delete_end_customer_input.rb +178 -0
  66. data/lib/appnigma/generated/models/delete_end_customer_output.rb +286 -0
  67. data/lib/appnigma/generated/models/delete_end_customer_output_connections_inner.rb +238 -0
  68. data/lib/appnigma/generated/models/delete_end_customer_output_logic_folder.rb +255 -0
  69. data/lib/appnigma/generated/models/delete_end_customer_output_steps_inner.rb +257 -0
  70. data/lib/appnigma/generated/models/delete_webhook_input.rb +189 -0
  71. data/lib/appnigma/generated/models/delete_webhook_output.rb +228 -0
  72. data/lib/appnigma/generated/models/discard_logic_input.rb +292 -0
  73. data/lib/appnigma/generated/models/discard_logic_output.rb +254 -0
  74. data/lib/appnigma/generated/models/disconnect_connection_input.rb +1 -1
  75. data/lib/appnigma/generated/models/disconnect_connection_output.rb +18 -5
  76. data/lib/appnigma/generated/models/edit_logic_input.rb +368 -0
  77. data/lib/appnigma/generated/models/edit_logic_output.rb +298 -0
  78. data/lib/appnigma/generated/models/encrypted_fields.rb +357 -0
  79. data/lib/appnigma/generated/models/end_customer.rb +17 -3
  80. data/lib/appnigma/generated/models/end_customer_connection.rb +1 -1
  81. data/lib/appnigma/generated/models/function_entry.rb +1 -1
  82. data/lib/appnigma/generated/models/function_owner.rb +1 -1
  83. data/lib/appnigma/generated/models/function_owner_one_of.rb +1 -1
  84. data/lib/appnigma/generated/models/function_owner_one_of1.rb +1 -1
  85. data/lib/appnigma/generated/models/get_alerts_output.rb +180 -0
  86. data/lib/appnigma/generated/models/get_connect_key_output.rb +256 -0
  87. data/lib/appnigma/generated/models/get_connection_input.rb +1 -1
  88. data/lib/appnigma/generated/models/get_connection_output.rb +34 -7
  89. data/lib/appnigma/generated/models/get_guide_output.rb +1 -1
  90. data/lib/appnigma/generated/models/get_logic_go_live_status_input.rb +247 -0
  91. data/lib/appnigma/generated/models/get_logic_go_live_status_output.rb +296 -0
  92. data/lib/appnigma/generated/models/get_logic_input.rb +247 -0
  93. data/lib/appnigma/generated/models/get_logic_output.rb +240 -0
  94. data/lib/appnigma/generated/models/get_logic_output_file.rb +204 -0
  95. data/lib/appnigma/generated/models/get_platform_input.rb +188 -0
  96. data/lib/appnigma/generated/models/get_platform_output.rb +326 -0
  97. data/lib/appnigma/generated/models/get_sync_output.rb +207 -0
  98. data/lib/appnigma/generated/models/go_live_logic_input.rb +316 -0
  99. data/lib/appnigma/generated/models/go_live_logic_output.rb +281 -0
  100. data/lib/appnigma/generated/models/json_value.rb +1 -1
  101. data/lib/appnigma/generated/models/list_actions_output.rb +1 -1
  102. data/lib/appnigma/generated/models/list_connections_output.rb +3 -3
  103. data/lib/appnigma/generated/models/list_events_input.rb +302 -0
  104. data/lib/appnigma/generated/models/list_events_output.rb +193 -0
  105. data/lib/appnigma/generated/models/list_features_output.rb +179 -0
  106. data/lib/appnigma/generated/models/list_features_output_features_inner.rb +229 -0
  107. data/lib/appnigma/generated/models/list_functions_output.rb +1 -1
  108. data/lib/appnigma/generated/models/list_logic_input.rb +162 -0
  109. data/lib/appnigma/generated/models/list_logic_output.rb +209 -0
  110. data/lib/appnigma/generated/models/list_logic_runs_input.rb +275 -0
  111. data/lib/appnigma/generated/models/list_logic_runs_output.rb +193 -0
  112. data/lib/appnigma/generated/models/list_platforms_output.rb +1 -1
  113. data/lib/appnigma/generated/models/list_record_changes_input.rb +375 -0
  114. data/lib/appnigma/generated/models/list_record_changes_output.rb +193 -0
  115. data/lib/appnigma/generated/models/list_webhooks_output.rb +180 -0
  116. data/lib/appnigma/generated/models/logic_check_problem.rb +203 -0
  117. data/lib/appnigma/generated/models/logic_conditional.rb +3 -3
  118. data/lib/appnigma/generated/models/logic_draft.rb +257 -0
  119. data/lib/appnigma/generated/models/logic_entry.rb +441 -0
  120. data/lib/appnigma/generated/models/logic_entry_failure.rb +205 -0
  121. data/lib/appnigma/generated/models/logic_folder_problem.rb +218 -0
  122. data/lib/appnigma/generated/models/logic_run.rb +483 -0
  123. data/lib/appnigma/generated/models/logic_test_call.rb +269 -0
  124. data/lib/appnigma/generated/models/platform_entry.rb +63 -6
  125. data/lib/appnigma/generated/models/platform_entry_coverage_inner.rb +1 -1
  126. data/lib/appnigma/generated/models/platform_request_input.rb +1 -1
  127. data/lib/appnigma/generated/models/platform_request_input_body.rb +1 -1
  128. data/lib/appnigma/generated/models/platform_request_output.rb +1 -1
  129. data/lib/appnigma/generated/models/ran_as.rb +1 -1
  130. data/lib/appnigma/generated/models/record_change.rb +231 -0
  131. data/lib/appnigma/generated/models/record_change_record.rb +105 -0
  132. data/lib/appnigma/generated/models/run_action_input.rb +1 -1
  133. data/lib/appnigma/generated/models/run_action_output.rb +1 -1
  134. data/lib/appnigma/generated/models/run_input.rb +1 -1
  135. data/lib/appnigma/generated/models/run_output.rb +1 -1
  136. data/lib/appnigma/generated/models/sdk_error.rb +1 -1
  137. data/lib/appnigma/generated/models/sdk_error_error.rb +3 -3
  138. data/lib/appnigma/generated/models/sdk_error_error_details.rb +81 -6
  139. data/lib/appnigma/generated/models/sdk_problem.rb +1 -1
  140. data/lib/appnigma/generated/models/set_alerts_input.rb +197 -0
  141. data/lib/appnigma/generated/models/set_alerts_output.rb +180 -0
  142. data/lib/appnigma/generated/models/set_sync_input.rb +177 -0
  143. data/lib/appnigma/generated/models/set_sync_output.rb +207 -0
  144. data/lib/appnigma/generated/models/switch_logic_off_input.rb +200 -0
  145. data/lib/appnigma/generated/models/switch_logic_off_output.rb +315 -0
  146. data/lib/appnigma/generated/models/switch_logic_on_input.rb +200 -0
  147. data/lib/appnigma/generated/models/switch_logic_on_output.rb +315 -0
  148. data/lib/appnigma/generated/models/sync_health.rb +231 -0
  149. data/lib/appnigma/generated/models/test_logic_input.rb +355 -0
  150. data/lib/appnigma/generated/models/test_logic_output.rb +418 -0
  151. data/lib/appnigma/generated/models/test_logic_output_error.rb +231 -0
  152. data/lib/appnigma/generated/models/update_logic_input.rb +359 -0
  153. data/lib/appnigma/generated/models/update_logic_output.rb +205 -0
  154. data/lib/appnigma/generated/version.rb +1 -1
  155. data/lib/appnigma/generated.rb +75 -1
  156. data/lib/appnigma/logic.rb +176 -0
  157. data/lib/appnigma/names.rb +4 -4
  158. data/lib/appnigma/platforms.rb +11 -1
  159. data/lib/appnigma/portal.rb +8 -5
  160. data/lib/appnigma/records.rb +46 -0
  161. data/lib/appnigma/schema_type.rb +149 -0
  162. data/lib/appnigma/sync.rb +30 -0
  163. data/lib/appnigma/types_printer.rb +154 -0
  164. data/lib/appnigma/verify_webhook.rb +107 -0
  165. data/lib/appnigma/version.rb +2 -2
  166. data/lib/appnigma/webhooks.rb +79 -0
  167. data/lib/appnigma.rb +1 -0
  168. metadata +93 -3
data/exe/appnigma ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ # The `appnigma` command: `appnigma types` and `appnigma guide` (24.3).
5
+ require "appnigma"
6
+ require "appnigma/command"
7
+
8
+ exit Appnigma::Command.run(ARGV)
@@ -0,0 +1,33 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "names"
4
+
5
+ module Appnigma
6
+ # Ready-made actions on the end customer's platform, such as Gong's
7
+ # `get-call-transcript`: `client.actions.list` and `client.actions.run`
8
+ # (24.3). The list reads, so it is retried; an action may change the
9
+ # platform, and only you know whether a repeat is harmless, so a run is made
10
+ # once.
11
+ class Actions
12
+ def initialize(client)
13
+ @client = client
14
+ end
15
+
16
+ # Every action on the platforms switched on for you, with the JSON Schema
17
+ # of its `input` and `output`, passed through as written, and the `scopes`
18
+ # the end customer's connection must have. `platform` narrows the list to
19
+ # one platform.
20
+ def list(platform: nil, timeout_ms: nil)
21
+ @client.call(:list_actions, opts: { platform: platform }.compact, timeout_ms: timeout_ms)
22
+ end
23
+
24
+ # Runs one action for one end customer. The input is checked against the
25
+ # action's shape before it runs; the answer's `output` is in the shape the
26
+ # action declares, passed through as the action returned it. Made once,
27
+ # never retried.
28
+ def run(end_customer_id:, platform:, action:, input:, timeout_ms: nil)
29
+ body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, action: action, input: input)
30
+ @client.call(:run_action, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
31
+ end
32
+ end
33
+ end
@@ -70,6 +70,19 @@ module Appnigma
70
70
  refuse("platform", "must be a platform key, such as hubspot")
71
71
  end
72
72
 
73
+ # 24.1: `connections.connect`'s fields, a Hash of text values. Which
74
+ # fields a platform takes is the server's check. Never quotes a value,
75
+ # since one is a key.
76
+ def connect_fields!(value)
77
+ return value if value.is_a?(Hash) && value.all? { |name, item| text_field?(name, item) }
78
+
79
+ refuse("fields", "must be a Hash of text values, by the names platforms.list gives")
80
+ end
81
+
82
+ def text_field?(name, item)
83
+ (name.is_a?(String) || name.is_a?(Symbol)) && item.is_a?(String)
84
+ end
85
+
73
86
  # `run` names its function by name or by id, never both, as the server
74
87
  # requires. A nil counts as left out, since a nil is never sent.
75
88
  def function_name_or_id!(function_name, function_id)
@@ -5,10 +5,17 @@ require_relative "checks"
5
5
  require_relative "names"
6
6
  require_relative "retry"
7
7
  require_relative "transport"
8
+ require_relative "actions"
8
9
  require_relative "connections"
9
10
  require_relative "crm"
11
+ require_relative "end_customers"
12
+ require_relative "features"
13
+ require_relative "logic"
10
14
  require_relative "platforms"
11
15
  require_relative "portal"
16
+ require_relative "records"
17
+ require_relative "sync"
18
+ require_relative "webhooks"
12
19
 
13
20
  module Appnigma
14
21
  # What a customer creates. The key comes from `key:` or from the
@@ -22,7 +29,15 @@ module Appnigma
22
29
  # a platform's answer), which comes back exactly as it was sent. Every call
23
30
  # also takes `timeout_ms:`, the time limit of one attempt.
24
31
  class Client
25
- attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms, :connections, :crm, :platforms, :portal
32
+ GROUPS = {
33
+ actions: Actions, alerts: Alerts, connections: Connections, crm: Crm, end_customers: EndCustomers,
34
+ events: Events, features: Features, logic: Logic, platforms: Platforms, portal: Portal, records: Records,
35
+ sync: Sync, webhooks: Webhooks
36
+ }.freeze
37
+
38
+ attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms,
39
+ :actions, :alerts, :connections, :crm, :end_customers, :events, :features, :logic, :platforms,
40
+ :portal, :records, :sync, :webhooks
26
41
 
27
42
  # `transport` is for tests; a customer never passes it.
28
43
  def initialize(key: nil, timeout_ms: DEFAULT_TIMEOUT_MS, max_retries: DEFAULT_MAX_RETRIES,
@@ -36,9 +51,13 @@ module Appnigma
36
51
  # A write whose repeat is not harmless gets one attempt. Each
37
52
  # create_link, the connect link's and the portal's, makes a new link
38
53
  # every time; run is your own function, and only you
39
- # know whether running it twice is harmless; request with a method
54
+ # know whether running it twice is harmless; an action may change the
55
+ # platform, so actions.run is made once too; request with a method
40
56
  # other than GET may change the platform; a crm create with nothing to
41
- # match on could make a second record. A crm create that matches, and
57
+ # match on could make a second record; a logic create, update, discard
58
+ # or check sent again after a lost answer would clash with its own
59
+ # first attempt, and a go-live would hide a real clash behind its own
60
+ # commit. A crm create that matches, and
42
61
  # a crm update, are retried because a repeat changes the same record.
43
62
  @one_attempt = Retry::Policy.new(max_retries: 0, max_retry_wait_ms: @max_retry_wait_ms)
44
63
  @transport = transport || Transport.new(base_url: @base_url, key: @key)
@@ -79,27 +98,25 @@ module Appnigma
79
98
  end
80
99
 
81
100
  # One call: through the transport, under the given retry policy, and
82
- # into the answer or the error for its status. Used by Connections and
83
- # Crm as well.
101
+ # into the answer or the error for its status. Used by the groups as
102
+ # well.
84
103
  def call(operation, *args, policy: @policy, timeout_ms: nil, opts: {})
85
104
  attempt_ms = timeout_ms.nil? ? @timeout_ms : Checks.timeout_ms!(timeout_ms)
86
105
  answer = Retry.with_retries(policy) { @transport.attempt(operation, *args, timeout_ms: attempt_ms, opts: opts) }
87
106
  read_answer(answer)
88
107
  end
89
108
 
90
- # Used by Connections and Crm: the policy for a call made once, and the
91
- # one for a call that is retried.
109
+ # Used by the groups: the policy for a call made once, and the one for a
110
+ # call that is retried.
92
111
  attr_reader :one_attempt, :policy
93
112
 
94
113
  private
95
114
 
96
- # The calls grouped by what they reach: `connections`, `crm`,
97
- # `platforms` and `portal`.
115
+ # The calls grouped by what they reach: `actions`, `alerts`,
116
+ # `connections`, `crm`, `end_customers`, `events`, `features`, `logic`,
117
+ # `platforms`, `portal`, `records`, `sync` and `webhooks`.
98
118
  def start_groups
99
- @connections = Connections.new(self)
100
- @crm = Crm.new(self)
101
- @platforms = Platforms.new(self)
102
- @portal = Portal.new(self)
119
+ GROUPS.each { |name, group| instance_variable_set(:"@#{name}", group.new(self)) }
103
120
  end
104
121
 
105
122
  # A success whose body is not JSON is a server error: a proxy page or an
@@ -0,0 +1,154 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "constants"
4
+ require_relative "checks"
5
+ require_relative "errors"
6
+ require_relative "command_files"
7
+
8
+ module Appnigma
9
+ # The words and flags given to the `appnigma` command.
10
+ class CommandArguments
11
+ VALUE_FLAGS = %w[--key --out].freeze
12
+
13
+ # The arguments, or nil for anything it does not know.
14
+ def self.parse(argv)
15
+ arguments = new
16
+ remaining = argv.dup
17
+ until remaining.empty?
18
+ return nil unless arguments.read(remaining.shift, remaining)
19
+ end
20
+ arguments
21
+ end
22
+
23
+ def initialize
24
+ @values = {}
25
+ @words = []
26
+ @help = false
27
+ end
28
+
29
+ def help?
30
+ @help
31
+ end
32
+
33
+ def key
34
+ @values["key"]
35
+ end
36
+
37
+ def out
38
+ @values["out"]
39
+ end
40
+
41
+ def subcommand
42
+ @words.size == 1 ? @words.first : nil
43
+ end
44
+
45
+ # One argument, taking the next as its value when it is a flag that has
46
+ # one. False for anything it does not know.
47
+ def read(argument, remaining)
48
+ name, separator, value = argument.partition("=")
49
+ return @help = true if argument == "--help"
50
+ return @values[name.delete_prefix("--")] = value if VALUE_FLAGS.include?(name) && !separator.empty?
51
+ return @values[name.delete_prefix("--")] = remaining.shift if VALUE_FLAGS.include?(name) && !remaining.empty?
52
+ return false if argument.start_with?("-")
53
+
54
+ @words << argument
55
+ end
56
+ end
57
+
58
+ # The `appnigma` command (24.3), as the TypeScript package has it: `types`
59
+ # writes an RBS file describing your functions and actions, `guide` the
60
+ # markdown guide for your developers. Same flags, messages and exit codes.
61
+ class Command
62
+ SUBCOMMANDS = {
63
+ "types" => [:write_types_file, DEFAULT_TYPES_FILE_NAME],
64
+ "guide" => [:write_guide_file, DEFAULT_GUIDE_FILE_NAME]
65
+ }.freeze
66
+
67
+ USAGE = [
68
+ "Usage: appnigma <types | guide> [--key apn_live_...] [--out <file>]",
69
+ "",
70
+ " types Writes an RBS file describing your Appnigma functions and actions, by",
71
+ " platform, as types for what you send and what comes back. Default",
72
+ " ./#{DEFAULT_TYPES_FILE_NAME}.",
73
+ " guide Writes the guide for your developers: install, the key, connecting an end",
74
+ " customer, every call, your functions with an example each, every error.",
75
+ " Default ./#{DEFAULT_GUIDE_FILE_NAME}.",
76
+ "",
77
+ "Run either again whenever a function goes live.",
78
+ "",
79
+ " --key Your SDK key. Defaults to #{KEY_ENV_NAME}.",
80
+ " --out Where to write.",
81
+ " --help This text."
82
+ ].join("\n")
83
+
84
+ NOTHING_WRITTEN = "Nothing was written."
85
+
86
+ NO_KEY = "No key was given. Pass --key, or set #{KEY_ENV_NAME}. #{NOTHING_WRITTEN}".freeze
87
+
88
+ # Runs the command and answers its exit code. The key comes from --key or
89
+ # the environment; the address only from the environment.
90
+ def self.run(argv, stdout: $stdout.method(:puts), stderr: $stderr.method(:puts))
91
+ new(stdout, stderr).run(argv)
92
+ end
93
+
94
+ def initialize(stdout, stderr)
95
+ @stdout = stdout
96
+ @stderr = stderr
97
+ end
98
+
99
+ def run(argv)
100
+ arguments = CommandArguments.parse(argv)
101
+ return say(@stdout, USAGE, 0) if arguments&.help?
102
+ return say(@stderr, USAGE, 1) unless SUBCOMMANDS.key?(arguments&.subcommand)
103
+
104
+ key = arguments.key || ENV.fetch(KEY_ENV_NAME, nil)
105
+ return say(@stderr, NO_KEY, 1) if key.to_s.empty?
106
+
107
+ write(arguments, key)
108
+ end
109
+
110
+ private
111
+
112
+ def say(stream, line, code)
113
+ stream.call(line)
114
+ code
115
+ end
116
+
117
+ def write(arguments, key)
118
+ method, default_out = SUBCOMMANDS.fetch(arguments.subcommand)
119
+ report(CommandFiles.public_send(method, key: key, out_path: arguments.out || default_out))
120
+ rescue StandardError => e
121
+ say(@stderr, describe_failure(e), 1)
122
+ end
123
+
124
+ def report(result)
125
+ @stdout.call(describe_result(result))
126
+ unread = result.actions_unread_because
127
+ if unread
128
+ @stderr.call("Your actions could not be read (#{unread}), so the file has your functions only. " \
129
+ "Run it again to add them.")
130
+ end
131
+ 0
132
+ end
133
+
134
+ def describe_failure(error)
135
+ case error
136
+ when AuthError then "Your key was refused (#{error.code}): #{error.message}. #{NOTHING_WRITTEN}"
137
+ when NetworkError
138
+ base_url = Checks.base_url!(ENV.fetch(API_URL_ENV_NAME, nil))
139
+ "Could not reach the Appnigma API at #{base_url}: #{error.message}. #{NOTHING_WRITTEN}"
140
+ when Error then "The Appnigma API refused the request (#{error.code}): #{error.message}. #{NOTHING_WRITTEN}"
141
+ else "#{error.message} #{NOTHING_WRITTEN}"
142
+ end
143
+ end
144
+
145
+ def describe_result(result)
146
+ actions = result.action_count.positive? ? " and #{plural(result.action_count, "action")}" : ""
147
+ "Wrote #{plural(result.function_count, "function")}#{actions} to #{result.path}"
148
+ end
149
+
150
+ def plural(count, word)
151
+ "#{count} #{word}#{"s" unless count == 1}"
152
+ end
153
+ end
154
+ end
@@ -0,0 +1,46 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "client"
4
+ require_relative "files"
5
+ require_relative "types_printer"
6
+
7
+ module Appnigma
8
+ # The two files the `appnigma` command writes (24.3), read with the
9
+ # customer's key. Nothing touches the disk until the server has answered: a
10
+ # refused key, an unreachable server or an error leaves the project as it
11
+ # was, and the error says why.
12
+ module CommandFiles
13
+ # Each of the customer's functions is a level-four heading in the guide's
14
+ # functions section.
15
+ FUNCTION_HEADING = /^#### `/
16
+
17
+ module_function
18
+
19
+ # The functions, then the actions. Actions come from another of our
20
+ # services, so when only they cannot be read the file is written with the
21
+ # functions alone and the result says why: an outage there never stops a
22
+ # customer's types.
23
+ def write_types_file(key:, out_path:, now: Time.now)
24
+ client = Client.new(key: key)
25
+ functions = client.catalog[:functions]
26
+ actions, unread_because = read_actions(client)
27
+ text = TypesPrinter.print_types_file(functions, now, actions)
28
+ Files::WriteResult.new(path: Files.write_atomically(out_path, text), function_count: functions.size,
29
+ action_count: actions.size, actions_unread_because: unread_because)
30
+ end
31
+
32
+ # The actions, or none and why.
33
+ def read_actions(client)
34
+ [client.actions.list[:actions], nil]
35
+ rescue Error => e
36
+ [[], "#{e.code}: #{e.message}"]
37
+ end
38
+
39
+ # The guide as the server wrote it, whole.
40
+ def write_guide_file(key:, out_path:)
41
+ guide = Client.new(key: key).guide[:guide]
42
+ Files::WriteResult.new(path: Files.write_atomically(out_path, guide),
43
+ function_count: guide.scan(FUNCTION_HEADING).size, action_count: 0)
44
+ end
45
+ end
46
+ end
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "openssl"
5
+ require_relative "constants"
6
+ require_relative "errors"
7
+
8
+ module Appnigma
9
+ # `connections.connect`'s fields, encrypted before they leave the
10
+ # customer's server, so they are never readable between it and ours
11
+ # (24.1). A one-time AES-256-GCM key encrypts the fields' JSON text, bound
12
+ # to the platform and the end customer; RSA-OAEP with SHA-256 encrypts
13
+ # that key to the public key the server answers GET /connect-key with.
14
+ # OpenSSL, from the standard library, so there is no dependency. The
15
+ # format is written out in the API description's connectEndCustomer, and
16
+ # the shared test data in openapi/test-data/ holds this gem to it byte for
17
+ # byte.
18
+ module ConnectFields
19
+ # The key, read once and kept on the client.
20
+ Key = Struct.new(:key_id, :public_key, keyword_init: true)
21
+
22
+ OAEP = { rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256" }.freeze
23
+
24
+ module_function
25
+
26
+ # GET /connect-key's answer as a key to encrypt to. One that is not an
27
+ # RSA public key is the server's failure, raised as a ServerError.
28
+ def import_key(answer)
29
+ public_key = OpenSSL::PKey.read(answer.fetch(:public_key).to_s.unpack1("m0"))
30
+ unless public_key.is_a?(OpenSSL::PKey::RSA)
31
+ raise ServerError.new(code: "INTERNAL_ERROR",
32
+ message: "The Appnigma API answered GET /connect-key with a key that is not RSA")
33
+ end
34
+
35
+ Key.new(key_id: answer.fetch(:key_id), public_key: public_key)
36
+ rescue ArgumentError, KeyError, OpenSSL::PKey::PKeyError
37
+ raise ServerError.new(code: "INTERNAL_ERROR",
38
+ message: "The Appnigma API answered GET /connect-key with a key that could not be read")
39
+ end
40
+
41
+ # The label, a zero byte, the platform, a zero byte and the end customer
42
+ # id, as UTF-8: fields encrypted for one end customer or platform do not
43
+ # decrypt for another.
44
+ def binding_bytes(platform:, end_customer_id:)
45
+ "#{CONNECT_FIELDS_BINDING_LABEL}\0#{platform}\0#{end_customer_id}".b
46
+ end
47
+
48
+ # The fields as compact JSON, written as the TypeScript and Python
49
+ # packages write them.
50
+ def fields_text(fields)
51
+ JSON.generate(fields)
52
+ end
53
+
54
+ # With a given AES key and IV (`nonce`), so a test can compare the ciphertext byte
55
+ # for byte with the shared test data. The 16-byte tag goes after the
56
+ # encrypted bytes, which is where the server reads it.
57
+ def encrypt_with(plaintext, platform:, end_customer_id:, key:, aes_key:, nonce:)
58
+ aad = binding_bytes(platform: platform, end_customer_id: end_customer_id)
59
+ {
60
+ "keyId" => key.key_id,
61
+ "wrappedKey" => [key.public_key.encrypt(aes_key, OAEP)].pack("m0"),
62
+ "iv" => [nonce].pack("m0"),
63
+ "ciphertext" => [aes_gcm(plaintext, aes_key, nonce, aad)].pack("m0")
64
+ }
65
+ end
66
+
67
+ def aes_gcm(plaintext, aes_key, nonce, aad)
68
+ cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
69
+ cipher.key = aes_key
70
+ cipher.iv = nonce
71
+ cipher.auth_data = aad
72
+ cipher.update(plaintext.encode("UTF-8")) + cipher.final + cipher.auth_tag
73
+ end
74
+
75
+ # A new AES key and IV every time, including the one resend after
76
+ # CONNECT_KEY_CHANGED.
77
+ def encrypt(fields, platform:, end_customer_id:, key:)
78
+ encrypt_with(fields_text(fields), platform: platform, end_customer_id: end_customer_id, key: key,
79
+ aes_key: OpenSSL::Random.random_bytes(CONNECT_FIELDS_AES_KEY_BYTES),
80
+ nonce: OpenSSL::Random.random_bytes(CONNECT_FIELDS_IV_BYTES))
81
+ end
82
+ end
83
+ end
@@ -1,16 +1,21 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "checks"
4
+ require_relative "connect_fields"
4
5
  require_relative "names"
5
6
 
6
7
  module Appnigma
7
8
  # Connecting an end customer to their account on a platform:
8
- # `client.connections.create_link`, `client.connections.get` and
9
- # `client.connections.disconnect`, and the list of them all,
10
- # `client.connections.list`.
9
+ # `client.connections.create_link`, `client.connections.connect`,
10
+ # `client.connections.get` and `client.connections.disconnect`, and the
11
+ # list of them all, `client.connections.list`.
11
12
  class Connections
12
13
  def initialize(client)
13
14
  @client = client
15
+ # 24.1: the key `connect` encrypts the fields to, read once and kept.
16
+ # The mutex makes connects on several threads at once share one read.
17
+ @connect_key = nil
18
+ @connect_key_lock = Mutex.new
14
19
  end
15
20
 
16
21
  # A link to the connect page for one end customer on one platform. It
@@ -21,11 +26,39 @@ module Appnigma
21
26
  @client.call(:create_connection_link, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
22
27
  end
23
28
 
29
+ # Connect one end customer with the details they typed into your own
30
+ # form, for a platform whose `connection_type` in `platforms.list` is
31
+ # `fields` (24.1). `fields` is keyed by each field's `name` there, and is
32
+ # sent exactly as given: its keys are the API's names, never renamed.
33
+ # Call it from your server, never the browser. The details are tried on
34
+ # the platform before the answer comes back, which can take up to 25
35
+ # seconds. Made once, never retried: after TIMED_OUT the connection may
36
+ # still have been made, so read it with `get` rather than calling again.
37
+ #
38
+ # The details are encrypted to our key before they leave your server,
39
+ # and never sent readable. CONNECT_KEY_CHANGED means nothing was tried,
40
+ # so the key is read again and the details sent once more, encrypted
41
+ # anew; a second one is raised.
42
+ def connect(end_customer_id:, platform:, fields:, timeout_ms: nil)
43
+ Checks.end_customer_id!(end_customer_id)
44
+ Checks.platform!(platform)
45
+ Checks.connect_fields!(fields)
46
+ begin
47
+ send_connect(end_customer_id, platform, fields, timeout_ms)
48
+ rescue NotAvailableError => e
49
+ raise unless e.code == CONNECT_KEY_CHANGED_ERROR_CODE
50
+
51
+ @connect_key = nil
52
+ send_connect(end_customer_id, platform, fields, timeout_ms)
53
+ end
54
+ end
55
+
24
56
  # Whether one end customer is connected on one platform, and the key of
25
57
  # their logic folder. The id may be any text, so it travels in the body
26
58
  # of POST /connections/get (19.2); it is checked here first, by the
27
59
  # server's own rule, so a bad one is refused before any call. A read, so
28
- # it is retried.
60
+ # it is retried. `sync` is how noticing changes has been going for this
61
+ # account (24.13), nil until it has been read once.
29
62
  def get(end_customer_id:, platform:, timeout_ms: nil)
30
63
  Checks.end_customer_id!(end_customer_id)
31
64
  Checks.platform!(platform)
@@ -33,7 +66,7 @@ module Appnigma
33
66
  @client.call(:get_connection, body, timeout_ms: timeout_ms)
34
67
  end
35
68
 
36
- # Your end customers, a page at a time, in id order, each with every
69
+ # Your end customers, a page at a time, in logic folder key order, each with every
37
70
  # connection of theirs (19.3). `platform` and `status` list the end
38
71
  # customers with at least one connection that matches; `limit` is 1 to
39
72
  # 100, 50 when left out; `cursor` is the `next` of the previous page. A
@@ -63,5 +96,25 @@ module Appnigma
63
96
  body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform)
64
97
  @client.call(:disconnect_connection, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
65
98
  end
99
+
100
+ private
101
+
102
+ def send_connect(end_customer_id, platform, fields, timeout_ms)
103
+ encrypted = ConnectFields.encrypt(fields, platform: platform, end_customer_id: end_customer_id,
104
+ key: read_connect_key(timeout_ms))
105
+ body = { "endCustomerId" => end_customer_id, "platform" => platform, "encryptedFields" => encrypted }
106
+ @client.call(:connect_end_customer, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
107
+ end
108
+
109
+ # A read, so it is retried. A read that fails is not kept, so the next
110
+ # connect asks again.
111
+ def read_connect_key(timeout_ms)
112
+ @connect_key_lock.synchronize do
113
+ if @connect_key.nil?
114
+ @connect_key = ConnectFields.import_key(@client.call(:get_connect_key, timeout_ms: timeout_ms))
115
+ end
116
+ @connect_key
117
+ end
118
+ end
66
119
  end
67
120
  end
@@ -9,6 +9,11 @@ module Appnigma
9
9
  # Where the client calls: production.
10
10
  DEFAULT_BASE_URL = "https://engine.appnigma.ai"
11
11
 
12
+ # Where the `appnigma` command writes, unless `--out` says otherwise (24.3).
13
+ # RBS files live under `sig/`, where Steep and RubyMine look for them.
14
+ DEFAULT_TYPES_FILE_NAME = "sig/appnigma_types.rbs"
15
+ DEFAULT_GUIDE_FILE_NAME = "appnigma-guide.md"
16
+
12
17
  # Points the client at a local or staging server for our own testing. Read
13
18
  # from the environment, never a client setting, and never in the README: a
14
19
  # customer always calls production.
@@ -20,12 +25,25 @@ module Appnigma
20
25
 
21
26
  ROUTE_BASE = "/sdk/v1"
22
27
 
28
+ # 24.1: how `connections.connect` encrypts the fields, as the server reads
29
+ # them. The label starts the bytes the encryption is bound to.
30
+ CONNECT_FIELDS_BINDING_LABEL = "appnigma-connect-fields-v1"
31
+ CONNECT_FIELDS_AES_KEY_BYTES = 32
32
+ CONNECT_FIELDS_IV_BYTES = 12
33
+ # The server replaced the key the fields were encrypted to: read it again,
34
+ # encrypt again and send once more, once.
35
+ CONNECT_KEY_CHANGED_ERROR_CODE = "CONNECT_KEY_CHANGED"
36
+
23
37
  REQUEST_ID_HEADER = "x-request-id"
24
38
  RETRY_AFTER_HEADER = "retry-after"
25
39
 
26
40
  # How long one attempt may take before it counts as a network failure.
27
41
  DEFAULT_TIMEOUT_MS = 30_000
28
42
 
43
+ # 24.7: logic.edit runs an agent and logic.test a sandbox, either past the
44
+ # default; a call's own timeout_ms still wins.
45
+ LOGIC_SLOW_CALL_TIMEOUT_MS = 180_000
46
+
29
47
  # The same ceiling the TypeScript package applies, so the two READMEs show
30
48
  # the same numbers.
31
49
  MAX_TIMER_MS = 2_147_483_647
@@ -46,6 +64,21 @@ module Appnigma
46
64
  # The one 422 that is your own logic failing, not the platform refusing.
47
65
  LOGIC_FAILED_ERROR_CODE = "LOGIC_FAILED"
48
66
 
67
+ # 24.11: the one 422 that is the address sent, not the platform refusing.
68
+ WEBHOOK_ADDRESS_REFUSED_ERROR_CODE = "WEBHOOK_ADDRESS_REFUSED"
69
+
70
+ # 24.11: what the server can tell your server, in the server's order.
71
+ CLIENT_EVENT_TYPES = %w[connection.dropped connection.restored go_live.finished go_live.failed logic.failed
72
+ records.changed].freeze
73
+
74
+ # 24.11: verify_webhook refuses a signature older than this, or this far in
75
+ # the future, so a message caught on the way cannot be sent again later.
76
+ WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300
77
+
78
+ # This gem's own code for a webhook whose signature did not check out. Not
79
+ # from the server, which never sends it.
80
+ WEBHOOK_SIGNATURE_ERROR_CODE = "WEBHOOK_SIGNATURE_INVALID"
81
+
49
82
  # 19.2: an end customer id is any text of the customer's, 1 to 255
50
83
  # characters (code points, as the server and its database count), with no
51
84
  # control character and not only spaces. Checked before `connections.get`,
@@ -77,14 +110,38 @@ module Appnigma
77
110
  PLATFORM_ERROR
78
111
  TIMED_OUT
79
112
  LOGIC_FAILED
113
+ CONNECT_LOGIN_REJECTED
114
+ CONNECT_KEY_CHANGED
80
115
  INTERNAL_ERROR
81
116
  RECORD_NOT_FOUND
82
117
  DATA_TYPE_NOT_AVAILABLE
83
118
  ACTION_NOT_FOUND
84
119
  MISSING_SCOPES
120
+ LOGIC_NOT_FOUND
121
+ END_CUSTOMER_LOGIC_NOT_AVAILABLE
122
+ DRAFT_CHANGED
123
+ LOGIC_NAME_TAKEN
124
+ TOO_MANY_DRAFTS
125
+ PLATFORM_NOT_CONNECTED
126
+ NOTHING_TO_GO_LIVE
127
+ FILE_CHANGED
128
+ SETTINGS_MISSING
129
+ LOGIC_CHECK_FAILED
130
+ REPO_ACCESS_REFUSED
131
+ LOGIC_NOT_ALWAYS_ON
132
+ PORTAL_NOT_AVAILABLE
133
+ WEBHOOK_ADDRESS_REFUSED
134
+ WEBHOOK_LIMIT_REACHED
135
+ WEBHOOK_EXISTS
136
+ WEBHOOK_NOT_FOUND
137
+ SYNC_NOT_ENABLED
85
138
  ].freeze
86
139
 
87
140
  OBJECTS = %w[contact company deal].freeze
141
+
142
+ # 24.13: the shape of time the server takes for `since`: seconds and their
143
+ # fractions optional, a time zone required.
144
+ ZONED_TIME_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})\z/
88
145
  CONNECTION_STATUSES = %w[pending connected needs_reconnect disconnected].freeze
89
146
  PLATFORM_REQUEST_METHODS = %w[GET POST PUT PATCH DELETE].freeze
90
147
  end
@@ -0,0 +1,29 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "checks"
4
+ require_relative "names"
5
+
6
+ module Appnigma
7
+ # An end customer who left your product: `client.end_customers.delete`
8
+ # (24.10).
9
+ class EndCustomers
10
+ def initialize(client)
11
+ @client = client
12
+ end
13
+
14
+ # Remove everything of one end customer: every connection, login first,
15
+ # then their connect links, settings, drafts, logic switches and portal
16
+ # links; an open portal session of theirs ends. Their folder in your logic
17
+ # repo stays, and the answer names it. The answer says what each
18
+ # connection and each step did; `completed` is false when a login could
19
+ # not be removed, or they connected again meanwhile, and calling again
20
+ # finishes it. A repeat, or an id the API has nothing for, is
21
+ # `already_gone` everywhere, never an error, so the call is retried like a
22
+ # read. The id travels in the body and is checked here first.
23
+ def delete(end_customer_id:, timeout_ms: nil)
24
+ Checks.end_customer_id!(end_customer_id)
25
+ body = Names.camel_keys(end_customer_id: end_customer_id)
26
+ @client.call(:delete_end_customer, body, timeout_ms: timeout_ms)
27
+ end
28
+ end
29
+ end