tronzap-sdk 1.0.0 → 1.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 (39) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +70 -0
  3. data/README.es.md +145 -15
  4. data/README.md +143 -14
  5. data/README.pt-br.md +145 -14
  6. data/README.ru.md +141 -13
  7. data/lib/tronzap/client.rb +157 -6
  8. data/lib/tronzap/coerce.rb +8 -0
  9. data/lib/tronzap/errors.rb +74 -17
  10. data/lib/tronzap/models/bulk_rejected_row.rb +30 -0
  11. data/lib/tronzap/models/direct_recharge_rate.rb +1 -1
  12. data/lib/tronzap/models/energy_rate.rb +12 -8
  13. data/lib/tronzap/models/enums.rb +15 -1
  14. data/lib/tronzap/models/subscription_params.rb +28 -0
  15. data/lib/tronzap/requests/aml_check.rb +17 -6
  16. data/lib/tronzap/requests/bulk_calculate.rb +40 -0
  17. data/lib/tronzap/requests/bulk_create.rb +52 -0
  18. data/lib/tronzap/requests/bulk_history.rb +28 -0
  19. data/lib/tronzap/requests/bulk_item.rb +29 -0
  20. data/lib/tronzap/requests/bulk_lookup.rb +48 -0
  21. data/lib/tronzap/requests/bulk_report.rb +55 -0
  22. data/lib/tronzap/requests/start_subscription.rb +54 -0
  23. data/lib/tronzap/requests/subscription_history.rb +35 -0
  24. data/lib/tronzap/requests/subscription_lookup.rb +48 -0
  25. data/lib/tronzap/requests/validation.rb +8 -0
  26. data/lib/tronzap/response_decoder.rb +53 -15
  27. data/lib/tronzap/responses/aml_check.rb +1 -1
  28. data/lib/tronzap/responses/bulk_calculation.rb +44 -0
  29. data/lib/tronzap/responses/bulk_history.rb +28 -0
  30. data/lib/tronzap/responses/bulk_order.rb +87 -0
  31. data/lib/tronzap/responses/calculation.rb +5 -3
  32. data/lib/tronzap/responses/energy_estimate.rb +6 -4
  33. data/lib/tronzap/responses/service_rates.rb +3 -2
  34. data/lib/tronzap/responses/subscription.rb +73 -0
  35. data/lib/tronzap/responses/subscription_history.rb +28 -0
  36. data/lib/tronzap/responses/subscription_plan.rb +52 -0
  37. data/lib/tronzap/version.rb +1 -1
  38. data/lib/tronzap.rb +17 -0
  39. metadata +18 -1
@@ -2,10 +2,11 @@
2
2
 
3
3
  require "digest"
4
4
  require "json"
5
+ require "openssl"
5
6
 
6
7
  module Tronzap
7
- # Client for the {https://docs.tronzap.com/ TronZap API}: buy TRON energy and bandwidth, activate addresses and
8
- # run AML checks.
8
+ # Client for the {https://docs.tronzap.com/ TronZap API}: buy TRON energy and bandwidth, activate addresses, run
9
+ # AML checks, manage energy subscriptions and place bulk energy orders.
9
10
  #
10
11
  # A client is immutable and safe to share between threads. Create one per set of credentials.
11
12
  #
@@ -157,7 +158,7 @@ module Tronzap
157
158
  post("/v1/aml-checks", {}) { Responses::AmlService.list_from_api(_1) }
158
159
  end
159
160
 
160
- # Starts an AML screening of an address or a transaction.
161
+ # Starts an AML screening of an address or a transaction. A hash check without a direction sends +deposit+.
161
162
  #
162
163
  # @overload create_aml_check(request)
163
164
  # @param request [Requests::AmlCheck] see {Requests::AmlCheck.for_address} and {Requests::AmlCheck.for_hash}
@@ -191,6 +192,150 @@ module Tronzap
191
192
  post("/v1/aml-checks/history", body) { Responses::AmlHistory.from_api(_1) }
192
193
  end
193
194
 
195
+ # Subscription plans on sale, in the order the API lists them.
196
+ #
197
+ # @return [Array<Responses::SubscriptionPlan>]
198
+ # @raise [Error]
199
+ def get_subscriptions
200
+ post("/v1/subscriptions", {}) { Responses::SubscriptionPlan.list_from_api(_1) }
201
+ end
202
+
203
+ # Subscribes an address to a plan from {#get_subscriptions}. Starting a subscription charges the plan's initial
204
+ # price.
205
+ #
206
+ # @overload start_subscription(request)
207
+ # @param request [Requests::StartSubscription]
208
+ # @overload start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0,
209
+ # external_id: nil, activate_address: false)
210
+ # @return [Responses::Subscription]
211
+ # @raise [ArgumentError, Error]
212
+ def start_subscription(request = nil, **params)
213
+ body = build(Requests::StartSubscription, request, params).body
214
+ post("/v1/subscription/start", body) { Responses::Subscription.from_api(_1) }
215
+ end
216
+
217
+ # The current state of a subscription, by its TronZap ID or by your external ID.
218
+ #
219
+ # @overload check_subscription(request)
220
+ # @param request [Requests::SubscriptionLookup]
221
+ # @overload check_subscription(id: nil, external_id: nil)
222
+ # @return [Responses::Subscription]
223
+ # @raise [ArgumentError, Error]
224
+ def check_subscription(request = nil, **params)
225
+ body = build(Requests::SubscriptionLookup, request, params).body
226
+ post("/v1/subscription/check", body) { Responses::Subscription.from_api(_1) }
227
+ end
228
+
229
+ # Stops a subscription, by its TronZap ID or by your external ID. A subscription with a transactions limit
230
+ # cannot be stopped and fails with {ErrorCode::CANNOT_STOP_SUBSCRIPTION}.
231
+ #
232
+ # @overload stop_subscription(request)
233
+ # @param request [Requests::SubscriptionLookup]
234
+ # @overload stop_subscription(id: nil, external_id: nil)
235
+ # @return [Responses::Subscription]
236
+ # @raise [ArgumentError, Error]
237
+ def stop_subscription(request = nil, **params)
238
+ body = build(Requests::SubscriptionLookup, request, params).body
239
+ post("/v1/subscription/stop", body) { Responses::Subscription.from_api(_1) }
240
+ end
241
+
242
+ # One page of your subscriptions, newest first.
243
+ #
244
+ # @overload get_subscription_history(request)
245
+ # @param request [Requests::SubscriptionHistory]
246
+ # @overload get_subscription_history(page: 1, per_page: 10, status: nil)
247
+ # @return [Responses::SubscriptionHistory]
248
+ # @raise [ArgumentError, Error]
249
+ def get_subscription_history(request = nil, **params)
250
+ body = build(Requests::SubscriptionHistory, request, params).body
251
+ post("/v1/subscriptions/history", body) { Responses::SubscriptionHistory.from_api(_1) }
252
+ end
253
+
254
+ # Validates and prices the rows of a bulk energy order. The calculation is valid for 10 minutes; nothing is
255
+ # charged. Invalid rows do not fail the request: they come back in {Responses::BulkCalculation#rejected} with
256
+ # their row number. When no row is valid, the call raises {BulkNoValidItemsError}.
257
+ #
258
+ # @overload bulk_calculate(request)
259
+ # @param request [Requests::BulkCalculate]
260
+ # @overload bulk_calculate(items:, duration: 1)
261
+ # @param items [Array<Requests::BulkItem, Hash>] at most 10 000 rows with +address+ and +amount+
262
+ # @return [Responses::BulkCalculation]
263
+ # @raise [ArgumentError, Error]
264
+ def bulk_calculate(request = nil, **params)
265
+ body = build(Requests::BulkCalculate, request, params).body
266
+ post("/v1/bulk/calculate", body) { Responses::BulkCalculation.from_api(_1) }
267
+ end
268
+
269
+ # Starts a bulk order from a calculation. Each address is charged when it is processed, and inactive addresses
270
+ # are skipped without a charge. If the price changed since the calculation, the order is not started and the
271
+ # call raises {BulkPriceChangedError}: confirm the new total of its calculation, then start the order with that
272
+ # calculation's ID. Repeating a call with the same ID or external ID returns the order already started.
273
+ #
274
+ # @overload bulk_create(request)
275
+ # @param request [Requests::BulkCreate]
276
+ # @overload bulk_create(id:, external_id: nil, force: false, max_price_increase: nil, webhook_url: nil)
277
+ # @return [Responses::BulkOrder]
278
+ # @raise [ArgumentError, Error]
279
+ def bulk_create(request = nil, **params)
280
+ body = build(Requests::BulkCreate, request, params).body
281
+ post("/v1/bulk/create", body) { Responses::BulkOrder.from_api(_1) }
282
+ end
283
+
284
+ # The status and progress of a bulk order, by its TronZap ID or by your external ID.
285
+ #
286
+ # @overload bulk_check(request)
287
+ # @param request [Requests::BulkLookup]
288
+ # @overload bulk_check(id: nil, external_id: nil)
289
+ # @return [Responses::BulkOrder]
290
+ # @raise [ArgumentError, Error]
291
+ def bulk_check(request = nil, **params)
292
+ body = build(Requests::BulkLookup, request, params).body
293
+ post("/v1/bulk/check", body) { Responses::BulkOrder.from_api(_1) }
294
+ end
295
+
296
+ # One page of your bulk orders, newest first.
297
+ #
298
+ # @overload get_bulk_history(request)
299
+ # @param request [Requests::BulkHistory]
300
+ # @overload get_bulk_history(page: 1, per_page: 10)
301
+ # @return [Responses::BulkHistory]
302
+ # @raise [ArgumentError, Error]
303
+ def get_bulk_history(request = nil, **params)
304
+ body = build(Requests::BulkHistory, request, params).body
305
+ post("/v1/bulk/history", body) { Responses::BulkHistory.from_api(_1) }
306
+ end
307
+
308
+ # The per-address report of a bulk order as CSV with a header line and the columns +row+, +address+, +amount+,
309
+ # +status+, +reason+, +charged+ and +transaction_id+. Rows the calculation rejected are not included.
310
+ #
311
+ # @overload bulk_report(request)
312
+ # @param request [Requests::BulkReport]
313
+ # @overload bulk_report(id: nil, external_id: nil, status: nil)
314
+ # @return [String] the CSV, in UTF-8
315
+ # @raise [ArgumentError, Error]
316
+ def bulk_report(request = nil, **params)
317
+ response = request(post_request("/v1/bulk/report", build(Requests::BulkReport, request, params).body))
318
+ return ResponseDecoder.text(response.body) if ResponseDecoder.csv?(response)
319
+
320
+ ResponseDecoder.decode(response) { nil }
321
+ raise InvalidResponseError.new("Expected a CSV report", status: response.status.to_i,
322
+ response_body: ResponseDecoder.text(response.body))
323
+ end
324
+
325
+ # Checks the +X-Signature+ header of a bulk order webhook: the SHA-256 of the raw body followed by your API
326
+ # secret, in hex.
327
+ #
328
+ # @param body [String] the raw request body, exactly as received
329
+ # @param signature [String, nil] the value of the +X-Signature+ header
330
+ # @return [Boolean] whether the signature matches the body and your API secret
331
+ def verify_webhook_signature(body, signature)
332
+ raise ArgumentError, "body must be a String" unless body.is_a?(String)
333
+ return false unless signature.is_a?(String)
334
+
335
+ expected = Digest::SHA256.hexdigest(body.b + config.api_secret.b)
336
+ OpenSSL.secure_compare(expected, signature.strip.downcase)
337
+ end
338
+
194
339
  # @return [String] a description that leaves out the credentials
195
340
  def inspect
196
341
  "#<#{self.class.name} base_url=#{config.base_url.inspect}>"
@@ -214,16 +359,22 @@ module Tronzap
214
359
  end
215
360
 
216
361
  def post(path, payload, &)
362
+ ResponseDecoder.decode(request(post_request(path, payload)), &)
363
+ end
364
+
365
+ def post_request(path, payload)
217
366
  body = JSON.generate(payload)
218
- request = HttpAdapter::Request.new(
367
+ HttpAdapter::Request.new(
219
368
  http_method: :post,
220
369
  url: "#{config.base_url}#{path}",
221
370
  headers: headers(body),
222
371
  body: body,
223
372
  timeout: config.timeout
224
373
  )
225
- response = HttpAdapter.translate_errors { config.adapter.call(request) }
226
- ResponseDecoder.decode(response, &)
374
+ end
375
+
376
+ def request(http_request)
377
+ HttpAdapter.translate_errors { config.adapter.call(http_request) }
227
378
  end
228
379
 
229
380
  def headers(body)
@@ -53,6 +53,10 @@ module Tronzap
53
53
  number.to_i
54
54
  end
55
55
 
56
+ def optional_integer(value, name)
57
+ value.nil? ? nil : integer(value, name)
58
+ end
59
+
56
60
  def decimal(value, name)
57
61
  optional_decimal(value, name) || BigDecimal(0)
58
62
  end
@@ -105,6 +109,10 @@ module Tronzap
105
109
  object(value, name).to_h { |key, amount| [key.to_s.freeze, to_decimal(amount, "#{name}.#{key}")] }.freeze
106
110
  end
107
111
 
112
+ def integer_map(value, name)
113
+ object(value, name).to_h { |key, count| [key.to_s.freeze, integer(count, "#{name}.#{key}")] }.freeze
114
+ end
115
+
108
116
  def timestamp(value, name)
109
117
  case value
110
118
  when nil then nil
@@ -27,19 +27,62 @@ module Tronzap
27
27
  # @return [String] the raw response body
28
28
  attr_reader :response_body
29
29
 
30
+ # @return [Object, nil] the +result+ the API sent along with the error, as parsed JSON (numbers as +Integer+ or
31
+ # +BigDecimal+), or +nil+. {ErrorCode::BULK_PRICE_CHANGED} and {ErrorCode::BULK_NO_VALID_ITEMS} carry it;
32
+ # {BulkPriceChangedError} and {BulkNoValidItemsError} also expose it typed.
33
+ attr_reader :result
34
+
35
+ # @return [Float, nil] seconds to wait before retrying, from the +Retry-After+ header or the +retry_after+ field,
36
+ # or +nil+ when the API sent neither. {ErrorCode::RATE_LIMITED} carries it.
37
+ attr_reader :retry_after
38
+
30
39
  # @param message [String] the error message from the API
31
40
  # @param code [Integer] the numeric error code
32
41
  # @param status [Integer] the HTTP status of the response
33
42
  # @param response_body [String] the raw response body
34
43
  # @param error_key [String, nil] the error key
35
44
  # @param request_id [String, nil] the request ID
36
- def initialize(message, code:, status:, response_body:, error_key: nil, request_id: nil)
45
+ # @param result [Object, nil] the +result+ sent with the error
46
+ # @param retry_after [Float, nil] seconds to wait before retrying
47
+ def initialize(message, code:, status:, response_body:, error_key: nil, request_id: nil, result: nil,
48
+ retry_after: nil)
37
49
  super(message)
38
50
  @code = code
39
51
  @status = status
40
52
  @response_body = response_body
41
53
  @error_key = error_key
42
54
  @request_id = request_id
55
+ @result = result
56
+ @retry_after = retry_after
57
+ end
58
+ end
59
+
60
+ # The price of a bulk order changed since its calculation, so the order was not started:
61
+ # {ErrorCode::BULK_PRICE_CHANGED}. Confirm the new total of {#calculation}, then start the order with its ID.
62
+ class BulkPriceChangedError < ApiError
63
+ # @return [Responses::BulkCalculation] the new calculation, valid for 10 minutes
64
+ attr_reader :calculation
65
+
66
+ # @param message [String] the error message from the API
67
+ # @param calculation [Responses::BulkCalculation] the new calculation
68
+ # @param options [Hash] the keyword arguments of {ApiError#initialize}
69
+ def initialize(message, calculation:, **)
70
+ super(message, **)
71
+ @calculation = calculation
72
+ end
73
+ end
74
+
75
+ # No row of a bulk calculation is valid: {ErrorCode::BULK_NO_VALID_ITEMS}. Fix the rows in {#rejected}.
76
+ class BulkNoValidItemsError < ApiError
77
+ # @return [Array<Models::BulkRejectedRow>] the rejected rows with their row numbers and reasons
78
+ attr_reader :rejected
79
+
80
+ # @param message [String] the error message from the API
81
+ # @param rejected [Array<Models::BulkRejectedRow>] the rejected rows
82
+ # @param options [Hash] the keyword arguments of {ApiError#initialize}
83
+ def initialize(message, rejected:, **)
84
+ super(message, **)
85
+ @rejected = rejected
43
86
  end
44
87
  end
45
88
 
@@ -51,19 +94,8 @@ module Tronzap
51
94
  # @return [String] the raw response body
52
95
  attr_reader :response_body
53
96
 
54
- # @param message [String] the error message
55
- # @param status [Integer] the HTTP status of the response
56
- # @param response_body [String] the raw response body
57
- def initialize(message, status:, response_body:)
58
- super(message)
59
- @status = status
60
- @response_body = response_body
61
- end
62
- end
63
-
64
- # The API answered with HTTP 429: too many requests. Back off and retry.
65
- class RateLimitError < HttpError
66
- # @return [Float, nil] seconds the API asked to wait before retrying, from the +Retry-After+ header
97
+ # @return [Float, nil] seconds to wait before retrying, from the +Retry-After+ header or the +retry_after+ field,
98
+ # or +nil+ when the server sent neither
67
99
  attr_reader :retry_after
68
100
 
69
101
  # @param message [String] the error message
@@ -71,11 +103,18 @@ module Tronzap
71
103
  # @param response_body [String] the raw response body
72
104
  # @param retry_after [Float, nil] seconds to wait before retrying
73
105
  def initialize(message, status:, response_body:, retry_after: nil)
74
- super(message, status: status, response_body: response_body)
106
+ super(message)
107
+ @status = status
108
+ @response_body = response_body
75
109
  @retry_after = retry_after
76
110
  end
77
111
  end
78
112
 
113
+ # HTTP 429 without an API payload, for example from a proxy. Back off and retry.
114
+ #
115
+ # A rate limit reported by the API arrives as {ApiError} with {ErrorCode::RATE_LIMITED}.
116
+ class RateLimitError < HttpError; end
117
+
79
118
  # The API answered with HTTP 401 or 403: check the API token and secret.
80
119
  class UnauthorizedError < HttpError; end
81
120
 
@@ -123,7 +162,8 @@ module Tronzap
123
162
  WALLET_NOT_FOUND = 5
124
163
  # Insufficient funds: top up the account or request a smaller amount.
125
164
  INSUFFICIENT_FUNDS = 6
126
- # Invalid TRON address: it should be a valid 34-character TRON address.
165
+ # Invalid TRON address: it should be a valid 34-character TRON address. Also reported when the address already
166
+ # has an active subscription.
127
167
  INVALID_TRON_ADDRESS = 10
128
168
  # Invalid energy amount.
129
169
  INVALID_ENERGY_AMOUNT = 11
@@ -132,7 +172,7 @@ module Tronzap
132
172
  # Transaction or subscription not found: check the transaction ID or external ID. The API reports this code
133
173
  # under the key +subscription_not_found+.
134
174
  TRANSACTION_NOT_FOUND = 20
135
- # The subscription cannot be stopped right now.
175
+ # Cannot stop subscription, for example because it has a transactions limit.
136
176
  CANNOT_STOP_SUBSCRIPTION = 21
137
177
  # Address not activated: activate it first with an address activation transaction.
138
178
  ADDRESS_NOT_ACTIVATED = 24
@@ -144,6 +184,23 @@ module Tronzap
144
184
  SERVICE_NOT_AVAILABLE = 35
145
185
  # Invalid bandwidth amount.
146
186
  INVALID_BANDWIDTH_AMOUNT = 50
187
+ # Bulk order not found: check the order ID or external ID. A calculation that was never started is not an order.
188
+ BULK_NOT_FOUND = 90
189
+ # Bulk calculation expired: call {Client#bulk_calculate} again; a calculation is valid for 10 minutes.
190
+ BULK_EXPIRED = 91
191
+ # The price changed since the calculation: confirm the new total of {BulkPriceChangedError#calculation}, then
192
+ # start the order with its ID.
193
+ BULK_PRICE_CHANGED = 92
194
+ # Too many items: send at most 10 000 rows in one calculation.
195
+ BULK_TOO_MANY_ITEMS = 93
196
+ # No valid items: fix the rows in {BulkNoValidItemsError#rejected}.
197
+ BULK_NO_VALID_ITEMS = 94
198
+ # The resource cannot be ordered in bulk: only energy can.
199
+ BULK_RESOURCE_NOT_SUPPORTED = 95
200
+ # The request body is too large (HTTP 413): send fewer rows in one calculation.
201
+ PAYLOAD_TOO_LARGE = 96
202
+ # Too many requests (HTTP 429): wait {ApiError#retry_after} seconds, when given, and retry.
203
+ RATE_LIMITED = 429
147
204
  # Internal server error. Contact support if it persists.
148
205
  INTERNAL_SERVER_ERROR = 500
149
206
  end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tronzap
4
+ module Models
5
+ # A row of a bulk calculation that was rejected and will not be ordered.
6
+ #
7
+ # @!attribute [r] row
8
+ # @return [Integer] the position of the row in the request, starting at 1
9
+ # @!attribute [r] address
10
+ # @return [String] the address as it was sent
11
+ # @!attribute [r] reason
12
+ # @return [String] why the row was rejected, for example +invalid_address+, +invalid_amount+ or +duplicate+
13
+ BulkRejectedRow = Data.define(:row, :address, :reason) do
14
+ # @api private
15
+ def self.from_api(value)
16
+ data = Coerce.object(value, "rejected row")
17
+ new(
18
+ row: Coerce.integer(data["row"], "row"),
19
+ address: Coerce.text(data["address"], "address"),
20
+ reason: Coerce.text(data["reason"], "reason")
21
+ )
22
+ end
23
+
24
+ # @api private
25
+ def self.list_from_api(value)
26
+ Coerce.list(value, "rejected") { from_api(_1) }
27
+ end
28
+ end
29
+ end
30
+ end
@@ -11,7 +11,7 @@ module Tronzap
11
11
  # @!attribute [r] max_energy
12
12
  # @return [Integer] largest energy amount this rate applies to
13
13
  # @!attribute [r] price
14
- # @return [BigDecimal] price per unit of energy, in TRX
14
+ # @return [BigDecimal] price per 1000 units of energy, in TRX
15
15
  # @!attribute [r] price_32k
16
16
  # @return [BigDecimal] price of 32 000 energy, in TRX
17
17
  # @!attribute [r] price_65k
@@ -2,7 +2,7 @@
2
2
 
3
3
  module Tronzap
4
4
  module Models
5
- # An energy price tier. Energy is priced per unit.
5
+ # An energy price tier. Energy is priced per 1000 units: 65000 energy at a {price} of 0.03 costs 1.95.
6
6
  #
7
7
  # @!attribute [r] duration
8
8
  # @return [Integer] rental duration in hours
@@ -11,11 +11,13 @@ module Tronzap
11
11
  # @!attribute [r] max_amount
12
12
  # @return [Integer] largest amount this tier applies to
13
13
  # @!attribute [r] min_energy
14
- # @return [Integer] smallest energy amount this tier applies to
14
+ # @deprecated Use {#min_amount}.
15
+ # @return [Integer] the same value as {#min_amount}
15
16
  # @!attribute [r] max_energy
16
- # @return [Integer] largest energy amount this tier applies to
17
+ # @deprecated Use {#max_amount}.
18
+ # @return [Integer] the same value as {#max_amount}
17
19
  # @!attribute [r] price
18
- # @return [BigDecimal] price per unit of energy, in TRX
20
+ # @return [BigDecimal] price per 1000 units of energy, in TRX
19
21
  # @!attribute [r] price_32k
20
22
  # @return [BigDecimal] price of 32 000 energy, in TRX
21
23
  # @!attribute [r] price_65k
@@ -27,12 +29,14 @@ module Tronzap
27
29
  # @api private
28
30
  def self.from_api(value)
29
31
  data = Coerce.object(value, "energy rate")
32
+ min_amount = Coerce.integer(data["min_amount"], "min_amount")
33
+ max_amount = Coerce.integer(data["max_amount"], "max_amount")
30
34
  new(
31
35
  duration: Coerce.integer(data["duration"], "duration"),
32
- min_amount: Coerce.integer(data["min_amount"], "min_amount"),
33
- max_amount: Coerce.integer(data["max_amount"], "max_amount"),
34
- min_energy: Coerce.integer(data["min_energy"], "min_energy"),
35
- max_energy: Coerce.integer(data["max_energy"], "max_energy"),
36
+ min_amount: min_amount,
37
+ max_amount: max_amount,
38
+ min_energy: min_amount,
39
+ max_energy: max_amount,
36
40
  price: Coerce.decimal(data["price"], "price"),
37
41
  price_32k: Coerce.decimal(data["price_32k"], "price_32k"),
38
42
  price_65k: Coerce.decimal(data["price_65k"], "price_65k"),
@@ -14,7 +14,9 @@ module Tronzap
14
14
  # What an AML check screens: a wallet address or a transaction hash.
15
15
  AML_CHECK_TYPES = %i[address hash].freeze
16
16
 
17
- # Directions of a screened transaction: incoming (+:deposit+) or outgoing (+:withdrawal+) funds.
17
+ # Which side of a screened transaction you are on; the risk is scored for the counterparty. +:deposit+: the
18
+ # funds were sent to your address, the screened address is yours and the sender is scored. +:withdrawal+: you
19
+ # sent the funds, the screened address is the external recipient's and the recipient is scored.
18
20
  AML_DIRECTIONS = %i[deposit withdrawal].freeze
19
21
 
20
22
  # AML check states.
@@ -22,5 +24,17 @@ module Tronzap
22
24
 
23
25
  # AML risk levels.
24
26
  AML_RISK_LEVELS = %i[low medium high].freeze
27
+
28
+ # Subscription states: +:new+ → +:pending+ → +:active+, then +:stopped+ or +:expired+; +:error+ when it could
29
+ # not be started.
30
+ SUBSCRIPTION_STATUSES = %i[new pending error active stopped expired].freeze
31
+
32
+ # Bulk order states: a calculation is +:draft+; a started order is +:processing+, then +:completed+ (every row
33
+ # delivered), +:partial+ (some rows delivered) or +:failed+ (none delivered).
34
+ BULK_STATUSES = %i[draft processing completed partial failed].freeze
35
+
36
+ # Row results in a bulk order report. +:in_review+ rows wait for a manual check; +:pending+ rows are not
37
+ # processed yet.
38
+ BULK_ROW_STATUSES = %i[delivered failed in_review skipped pending].freeze
25
39
  end
26
40
  end
@@ -0,0 +1,28 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tronzap
4
+ module Models
5
+ # The parameters a subscription was started with.
6
+ #
7
+ # @!attribute [r] address
8
+ # @return [String] the TRON address the subscription serves
9
+ # @!attribute [r] duration_days
10
+ # @return [Integer] how many days the subscription runs, 0 for no time limit
11
+ # @!attribute [r] transactions_limit
12
+ # @return [Integer] how many transactions the subscription covers, 0 for no limit
13
+ # @!attribute [r] activate_address
14
+ # @return [Boolean] whether activating the address was requested
15
+ SubscriptionParams = Data.define(:address, :duration_days, :transactions_limit, :activate_address) do
16
+ # @api private
17
+ def self.from_api(value)
18
+ data = Coerce.object(value, "params")
19
+ new(
20
+ address: Coerce.text(data["address"], "params.address"),
21
+ duration_days: Coerce.integer(data["duration"], "params.duration"),
22
+ transactions_limit: Coerce.integer(data["transactions_limit"], "params.transactions_limit"),
23
+ activate_address: Coerce.boolean(data["activate_address"], "params.activate_address")
24
+ )
25
+ end
26
+ end
27
+ end
28
+ end
@@ -9,17 +9,21 @@ module Tronzap
9
9
  # @!attribute [r] network
10
10
  # @return [String] the network code, for example +TRX+, +BTC+ or +ETH+
11
11
  # @!attribute [r] address
12
- # @return [String] the wallet address
12
+ # @return [String] the address to screen; for a hash check, the recipient address of the transaction, where
13
+ # the funds were received
13
14
  # @!attribute [r] transaction_hash
14
15
  # @return [String, nil] the transaction hash, required when {type} is +:hash+
15
16
  # @!attribute [r] direction
16
- # @return [Symbol, nil] the transaction direction for a hash check, one of {Models::AML_DIRECTIONS}
17
+ # @return [Symbol, nil] for a hash check, which side of the transaction you are on, one of
18
+ # {Models::AML_DIRECTIONS}: +:deposit+ if the funds were sent to your address (+address+ is yours),
19
+ # +:withdrawal+ if you sent them (+address+ is the external recipient's). The risk is scored for the
20
+ # counterparty. When omitted for a hash check, the SDK sends +deposit+.
17
21
  AmlCheck = Data.define(:type, :network, :address, :transaction_hash, :direction) do
18
22
  # @param type [Symbol, String] +:address+ or +:hash+
19
23
  # @param network [String]
20
24
  # @param address [String]
21
25
  # @param transaction_hash [String, nil]
22
- # @param direction [Symbol, String, nil] +:deposit+ or +:withdrawal+
26
+ # @param direction [Symbol, String, nil] +:deposit+ or +:withdrawal+; a hash check without one sends +deposit+
23
27
  # @raise [ArgumentError]
24
28
  def initialize(type:, network:, address:, transaction_hash: nil, direction: nil)
25
29
  type = Validation.one_of(type, Models::AML_CHECK_TYPES, "type")
@@ -46,10 +50,16 @@ module Tronzap
46
50
 
47
51
  # Screens a transaction.
48
52
  #
53
+ # +address+ is the recipient address of the transaction, where the funds were received. +direction+ says
54
+ # which side of the transaction you are on: +:deposit+ if the funds were sent to your address (+address+ is
55
+ # yours), +:withdrawal+ if you sent them (+address+ is the external recipient's). The risk is scored for the
56
+ # counterparty: the sender of a deposit, the recipient of a withdrawal. Without a direction the SDK sends
57
+ # +deposit+.
58
+ #
49
59
  # @param network [String] the network code, for example +BTC+
50
- # @param address [String]
60
+ # @param address [String] the recipient address of the transaction
51
61
  # @param transaction_hash [String]
52
- # @param direction [Symbol, String, nil] +:deposit+ or +:withdrawal+
62
+ # @param direction [Symbol, String, nil] +:deposit+ (the default) or +:withdrawal+
53
63
  # @return [AmlCheck]
54
64
  def self.for_hash(network, address, transaction_hash, direction: nil)
55
65
  new(type: :hash, network: network, address: address, transaction_hash: transaction_hash,
@@ -60,7 +70,8 @@ module Tronzap
60
70
  def body
61
71
  body = { "type" => type.name, "network" => network, "address" => address }
62
72
  body["hash"] = transaction_hash if transaction_hash
63
- body["direction"] = direction.name if direction
73
+ sent_direction = direction || (:deposit if type == :hash)
74
+ body["direction"] = sent_direction.name if sent_direction
64
75
  body
65
76
  end
66
77
  end
@@ -0,0 +1,40 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tronzap
4
+ module Requests
5
+ # The rows of a bulk energy order to validate and price.
6
+ #
7
+ # @!attribute [r] items
8
+ # @return [Array<BulkItem>] the rows, at most 10 000
9
+ # @!attribute [r] duration
10
+ # @return [Integer] rental duration in hours, one of the durations {Client#get_services} lists
11
+ BulkCalculate = Data.define(:items, :duration) do
12
+ # @param items [Array<BulkItem, Hash>] the rows, as {BulkItem}s or hashes with +address+ and +amount+
13
+ # @param duration [Integer]
14
+ # @raise [ArgumentError]
15
+ def initialize(items:, duration: 1)
16
+ raise ArgumentError, "items is required" unless items.is_a?(Array) && !items.empty?
17
+
18
+ super(
19
+ items: items.map { |item| item(item) }.freeze,
20
+ duration: Validation.positive_integer(duration, "duration")
21
+ )
22
+ end
23
+
24
+ # @api private
25
+ def body
26
+ { "resource" => "energy", "duration" => duration, "items" => items.map(&:body) }
27
+ end
28
+
29
+ private
30
+
31
+ def item(value)
32
+ case value
33
+ when BulkItem then value
34
+ when Hash then BulkItem.new(**value.transform_keys(&:to_sym))
35
+ else raise ArgumentError, "items must hold BulkItems or hashes, got #{value.inspect}"
36
+ end
37
+ end
38
+ end
39
+ end
40
+ end
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tronzap
4
+ module Requests
5
+ # A bulk order to start from a calculation.
6
+ #
7
+ # @!attribute [r] id
8
+ # @return [String] the {Responses::BulkCalculation#id} of the calculation to start
9
+ # @!attribute [r] external_id
10
+ # @return [String, nil] your own ID for the order, unique per account. Starting an order again with the same
11
+ # external ID returns the order already started.
12
+ # @!attribute [r] force
13
+ # @return [Boolean] whether to buy even if the price rises while the order runs, within {max_price_increase}.
14
+ # When +false+, an address whose price rose is skipped.
15
+ # @!attribute [r] max_price_increase
16
+ # @return [Integer, nil] the allowed price increase in percent, 0 to 100, used only with {force}. The API
17
+ # default of 20 applies when it is +nil+.
18
+ # @!attribute [r] webhook_url
19
+ # @return [String, nil] a public +https+ URL called once when the order becomes final. Check its
20
+ # +X-Signature+ header with {Client#verify_webhook_signature}.
21
+ BulkCreate = Data.define(:id, :external_id, :force, :max_price_increase, :webhook_url) do
22
+ # @param id [String]
23
+ # @param external_id [String, nil]
24
+ # @param force [Boolean]
25
+ # @param max_price_increase [Integer, nil]
26
+ # @param webhook_url [String, nil]
27
+ # @raise [ArgumentError]
28
+ def initialize(id:, external_id: nil, force: false, max_price_increase: nil, webhook_url: nil)
29
+ unless max_price_increase.nil?
30
+ max_price_increase = Validation.non_negative_integer(max_price_increase, "max_price_increase")
31
+ end
32
+ super(
33
+ id: Validation.string(id, "id"),
34
+ external_id: Validation.optional_string(external_id, "external_id"),
35
+ force: Validation.boolean(force, "force"),
36
+ max_price_increase: max_price_increase,
37
+ webhook_url: Validation.optional_string(webhook_url, "webhook_url")
38
+ )
39
+ end
40
+
41
+ # @api private
42
+ def body
43
+ body = { "id" => id }
44
+ body["force"] = true if force
45
+ body["max_price_increase"] = max_price_increase if max_price_increase
46
+ body["webhook_url"] = webhook_url if webhook_url
47
+ body["external_id"] = external_id if external_id
48
+ body
49
+ end
50
+ end
51
+ end
52
+ end