tronzap-sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47eb7ea9f4ddd00ae8d660cc3b80423ec34badd0b79282e0a0ee3467018192d4
-  data.tar.gz: 8d8eaaedce42acb5aba146c6cd610af884c3d535002e296593bf4102a30d5777
+  metadata.gz: 3ffa340c958b0a66217f4c255dc615ebb13c8580730bcd276658be3e7178a991
+  data.tar.gz: f464a18b56042ae6e74bde0a194fb464a669891edada491cdd86c967089cc094
 SHA512:
-  metadata.gz: a70751df5acfd943527b15de891f78fd69bd25a245df44086e2c805001c6a31805a854f93c6079f0df0c945ba9f66f82f79750570e9f8385d09c56d5857b8b72
-  data.tar.gz: 3b279e1a68f525fdb795d9c54ec6da604b3d635884e03a869cd983ccadf26df4433b65300d2bce5d94e2e74389b16466470a972f4b46cba55cd7ab85155bc21a
+  metadata.gz: 1e98924e7e7b72f4b4dd8d78b62e8591047a5f0e76795244c071e02f9f324bbf6f07c834e02da72839a813317aa7764ac289cc7c413d74f1b247d16c33046af4
+  data.tar.gz: 9543a6086b456f1a963ccee701add632f0742eb6c39aedab71ada79f6dc96b6cd3be385edba7d38ebfdef0da841f6098ee44812d300279934e7fbdd2f9b31a69

data/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this project are documented in this file. The format is b
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.1.0] - 2026-10-09
+
+### Added
+
+- Energy subscriptions: `Client#get_subscriptions`, `#start_subscription`, `#check_subscription`,
+  `#stop_subscription` and `#get_subscription_history`, with the requests `Requests::StartSubscription`,
+  `Requests::SubscriptionLookup` and `Requests::SubscriptionHistory`, the results `Responses::SubscriptionPlan`,
+  `Responses::Subscription` and `Responses::SubscriptionHistory`, `Models::SubscriptionParams` and
+  `Models::SUBSCRIPTION_STATUSES`. `get_subscriptions` returns the plans in the API's order, each with its key as
+  `subscription_id`.
+- The example program lists subscription plans and history, checks `TRONZAP_SUBSCRIPTION_ID`, and with purchases
+  allowed and `TRONZAP_SUBSCRIPTION_PLAN` set starts a one-day subscription and always stops it.
+
+### Changed
+
+- A hash AML check without a `direction` now sends `deposit` explicitly instead of leaving the direction to the API.
+  An address check still sends a direction only when one is given.
+- The documentation of AML checks: for a hash check, `address` is the recipient address of the transaction, and
+  `direction` says which side you are on (`:deposit` if the funds were sent to your address, `:withdrawal` if you
+  sent them); the risk is scored for the counterparty.
+- The documentation of error codes 10 and 21: `INVALID_TRON_ADDRESS` is also reported when the address already has
+  an active subscription, and `CANNOT_STOP_SUBSCRIPTION` covers, for example, a subscription with a transactions
+  limit.
+
+### Deprecated
+
+- `Models::EnergyRate#min_energy` and `#max_energy`: use `#min_amount` and `#max_amount`. They now hold the same
+  values, read from the API's `min_amount` and `max_amount`.
+- `Responses::Calculation#energy`: use `#amount`. It now holds the same value, read from the API's `amount`.
+- `Responses::EnergyEstimate#energy`: use `#amount`. It now holds the same value, read from the API's `amount`.
+
+### Fixed
+
+- The documentation of `get_services` prices: energy, like bandwidth, is priced per 1000 units, so a purchase costs
+  `price × amount / 1000`. It was described as priced per unit.
+- `Models::DirectRechargeRate#price` is the price of 1000 units of energy as well, not of one unit.
+
 ## [1.0.0] - 2026-10-06
 
 First release of the official Ruby SDK for the [TronZap API](https://docs.tronzap.com/).
@@ -20,4 +59,6 @@ First release of the official Ruby SDK for the [TronZap API](https://docs.tronza
 - An error hierarchy under `Tronzap::Error` that separates API, HTTP, response and network failures, with the HTTP
   status, API error code, error key, request ID and raw response body.
 
+[Unreleased]: https://github.com/tron-energy-market/tronzap-sdk-ruby/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/tron-energy-market/tronzap-sdk-ruby/releases/tag/v1.1.0
 [1.0.0]: https://github.com/tron-energy-market/tronzap-sdk-ruby/releases/tag/v1.0.0

data/README.es.md

@@ -57,7 +57,7 @@ begin
 
   transaction = client.create_energy_transaction(
     address: "TRecipientAddress",
-    energy: estimate.energy,
+    energy: estimate.amount,
     duration: 1,
     external_id: "order-42",
     activate_address: true
@@ -185,6 +185,11 @@ bibliotecas HTTP debe traducirlos el adaptador, como en el ejemplo anterior.
 | `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Iniciar una verificación AML |
 | `check_aml_status(id)` | `/v1/aml-checks/check` | Estado y resultado de una verificación AML |
 | `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | Historial paginado de verificaciones AML |
+| `get_subscriptions` | `/v1/subscriptions` | Planes de suscripción y precios |
+| `start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0, external_id: nil, activate_address: false)` | `/v1/subscription/start` | Suscribir una dirección a un plan |
+| `check_subscription(id: nil, external_id: nil)` | `/v1/subscription/check` | Estado de una suscripción, por id o id externo |
+| `stop_subscription(id: nil, external_id: nil)` | `/v1/subscription/stop` | Detener una suscripción |
+| `get_subscription_history(page: 1, per_page: 10, status: nil)` | `/v1/subscriptions/history` | Historial paginado de suscripciones |
 
 Los métodos con parámetros aceptan argumentos de palabra clave o un objeto de
 solicitud de `Tronzap::Requests`, así que una solicitud se puede construir, validar
@@ -197,11 +202,13 @@ client.create_energy_transaction(request)
 
 Una solicitud se valida al crearse, así que una solicitud inválida lanza
 `ArgumentError` y nunca llega a la API. Las cantidades deben ser `Integer`
-positivos. Los valores por defecto coinciden con la API: `duration` es 1 hora y el
-historial AML empieza en la página 1 con 10 elementos.
+positivos. Los valores por defecto coinciden con la API: `duration` es 1 hora y los
+historiales AML y de suscripciones empiezan en la página 1 con 10 elementos. La
+excepción es `start_subscription`, donde `duration_days` y `transactions_limit`
+valen 0 por defecto, lo que significa sin límite.
 
 Los resultados son objetos `Data` inmutables en `Tronzap::Responses` y
-`Tronzap::Models`, no hashes: `transaction.status`, `estimate.energy`. Las
+`Tronzap::Models`, no hashes: `transaction.status`, `estimate.amount`. Las
 colecciones están congeladas y nunca son `nil`, y los valores que la API puede
 omitir son `nil`.
 
@@ -232,10 +239,10 @@ client.create_resource_bundle_transaction(
 client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
 ```
 
-El precio de la energía es por unidad y el del ancho de banda por 1000 unidades:
-en `get_services`, `EnergyRate#price` × 65000 es el coste de 65000 de energía,
-mientras que 345 de ancho de banda con un `BandwidthRate#price` de 1 cuestan
-0.345.
+En `get_services`, los precios de la energía y del ancho de banda son ambos por
+1000 unidades, así que una compra cuesta `price × amount / 1000`: 65000 de energía
+con un `EnergyRate#price` de 0.03 cuestan 1.95, y 345 de ancho de banda con un
+`BandwidthRate#price` de 1 cuestan 0.345.
 
 Actualmente la API informa un paquete de recursos con `service` igual a `:energy`,
 no `:resource_bundle`. Consulta `params.amounts` para saber qué recursos contiene
@@ -268,10 +275,51 @@ if result.status == :completed
 end
 ```
 
+En una verificación por hash, `address` es la dirección del destinatario de la
+transacción, donde se recibieron los fondos, y `direction` indica en qué lado
+estás: `:deposit` si los fondos llegaron a tu dirección (`address` es tu
+dirección), `:withdrawal` si los enviaste tú (`address` es la dirección del
+destinatario externo). El riesgo se calcula para la contraparte: el remitente en
+un deposit, el destinatario en un withdrawal. Sin `direction`, el SDK envía
+`deposit`.
+
 `risk_score` es `nil` hasta que termina la verificación. Una verificación
 completada puede tener una puntuación de 0, que no es lo mismo que no tener
 puntuación todavía.
 
+### Suscripciones
+
+Una suscripción mantiene una dirección abastecida de energía para cada transacción
+hasta que se detiene o se agotan sus días o transacciones. Elija un plan de
+`get_subscriptions` y pase su `subscription_id`, como `"unlimited_energy"`, no su
+`id` numérico. Iniciar una suscripción cobra el precio inicial del plan.
+
+```ruby
+client.get_subscriptions.each do |plan|
+  puts "#{plan.subscription_id} #{plan.initial_price.to_s("F")} #{plan.price.to_s("F")}"
+end
+
+subscription = client.start_subscription(
+  subscription_id: "unlimited_energy",
+  address: "TRecipientAddress",
+  duration_days: 30,       # 0 para no limitar el tiempo
+  transactions_limit: 0,   # 0 para no limitar
+  external_id: "subscription-42"
+)
+
+subscription = client.check_subscription(external_id: "subscription-42")
+
+subscription = client.stop_subscription(id: subscription.id)
+
+history = client.get_subscription_history(status: :active)
+```
+
+Iniciar, consultar y detener devuelven la suscripción con sus `params`; el
+historial devuelve en su lugar los contadores de uso `transactions_used`,
+`energy_used` y `total_price`, y deja `params` en `nil`. Los estados de una
+suscripción están en `Tronzap::Models::SUBSCRIPTION_STATUSES`. Una suscripción con
+límite de transacciones no se puede detener (`CANNOT_STOP_SUBSCRIPTION`).
+
 ## Gestión de errores
 
 Todo fallo de una llamada a la API es un `Tronzap::Error`. Captura una subclase
@@ -343,11 +391,11 @@ como `Tronzap::HttpError`.
 | 2 | `INVALID_SERVICE_OR_PARAMS` | Servicio o parámetros inválidos |
 | 5 | `WALLET_NOT_FOUND` | Billetera interna no encontrada. Contacta con soporte. |
 | 6 | `INSUFFICIENT_FUNDS` | Fondos insuficientes |
-| 10 | `INVALID_TRON_ADDRESS` | Dirección TRON inválida |
+| 10 | `INVALID_TRON_ADDRESS` | Dirección TRON inválida, o la dirección ya tiene una suscripción activa |
 | 11 | `INVALID_ENERGY_AMOUNT` | Cantidad de energía inválida |
 | 12 | `INVALID_DURATION` | Duración inválida |
 | 20 | `TRANSACTION_NOT_FOUND` | Transacción/suscripción no encontrada |
-| 21 | `CANNOT_STOP_SUBSCRIPTION` | No se puede detener la suscripción |
+| 21 | `CANNOT_STOP_SUBSCRIPTION` | No se puede detener la suscripción, p. ej. tiene límite de transacciones |
 | 24 | `ADDRESS_NOT_ACTIVATED` | Dirección no activada |
 | 25 | `ADDRESS_ALREADY_ACTIVATED` | Dirección ya activada |
 | 30 | `AML_CHECK_NOT_FOUND` | Verificación AML no encontrada |

data/README.md

@@ -57,7 +57,7 @@ begin
 
   transaction = client.create_energy_transaction(
     address: "TRecipientAddress",
-    energy: estimate.energy,
+    energy: estimate.amount,
     duration: 1,
     external_id: "order-42",
     activate_address: true
@@ -185,6 +185,11 @@ libraries need to be translated by the adapter, as above.
 | `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Start an AML screening |
 | `check_aml_status(id)` | `/v1/aml-checks/check` | Status and result of an AML check |
 | `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | Paginated AML check history |
+| `get_subscriptions` | `/v1/subscriptions` | Subscription plans and prices |
+| `start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0, external_id: nil, activate_address: false)` | `/v1/subscription/start` | Subscribe an address to a plan |
+| `check_subscription(id: nil, external_id: nil)` | `/v1/subscription/check` | Status of a subscription, by id or external id |
+| `stop_subscription(id: nil, external_id: nil)` | `/v1/subscription/stop` | Stop a subscription |
+| `get_subscription_history(page: 1, per_page: 10, status: nil)` | `/v1/subscriptions/history` | Paginated subscription history |
 
 Methods with parameters take either keyword arguments or a request object from
 `Tronzap::Requests`, so a request can be built, validated and passed around before
@@ -197,11 +202,12 @@ client.create_energy_transaction(request)
 
 A request is validated when it is created, so an invalid one raises
 `ArgumentError` and never reaches the API. Amounts must be positive `Integer`s.
-Defaults match the API: `duration` is 1 hour, and AML history starts at page 1
-with 10 items.
+Defaults match the API: `duration` is 1 hour, and AML and subscription history
+start at page 1 with 10 items. The exception is `start_subscription`, where
+`duration_days` and `transactions_limit` default to 0, which means no limit.
 
 Results are immutable `Data` objects in `Tronzap::Responses` and
-`Tronzap::Models`, not hashes: `transaction.status`, `estimate.energy`. Collections
+`Tronzap::Models`, not hashes: `transaction.status`, `estimate.amount`. Collections
 are frozen and never `nil`, and values the API may omit are `nil`.
 
 ### Buying resources
@@ -231,9 +237,9 @@ client.create_resource_bundle_transaction(
 client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
 ```
 
-Energy prices are per unit, bandwidth prices are per 1000 units: in
-`get_services`, `EnergyRate#price` × 65000 is the cost of 65000 energy, while 345
-bandwidth at a `BandwidthRate#price` of 1 costs 0.345.
+Energy and bandwidth prices in `get_services` are both per 1000 units, so a
+purchase costs `price × amount / 1000`: 65000 energy at an `EnergyRate#price` of
+0.03 costs 1.95, and 345 bandwidth at a `BandwidthRate#price` of 1 costs 0.345.
 
 The API currently reports a resource bundle with `service` equal to `:energy`, not
 `:resource_bundle`. Read `params.amounts` to see which resources a transaction
@@ -266,9 +272,49 @@ if result.status == :completed
 end
 ```
 
+For a hash check, `address` is the recipient address of the transaction, where
+the funds were received, and `direction` says which side you are on: `:deposit`
+if the funds were sent to your address (`address` is your address), `:withdrawal`
+if you sent them (`address` is the external recipient's address). The risk is
+scored for the counterparty: the sender of a deposit, the recipient of a
+withdrawal. Without a `direction`, the SDK sends `deposit`.
+
 `risk_score` is `nil` until screening finishes. A completed check can have a score
 of 0, which is not the same as having no score yet.
 
+### Subscriptions
+
+A subscription keeps an address supplied with energy for every transaction until
+it is stopped or runs out of days or transactions. Pick a plan from
+`get_subscriptions` and pass its `subscription_id`, such as `"unlimited_energy"`,
+not its numeric `id`. Starting a subscription charges the plan's initial price.
+
+```ruby
+client.get_subscriptions.each do |plan|
+  puts "#{plan.subscription_id} #{plan.initial_price.to_s("F")} #{plan.price.to_s("F")}"
+end
+
+subscription = client.start_subscription(
+  subscription_id: "unlimited_energy",
+  address: "TRecipientAddress",
+  duration_days: 30,       # 0 for no time limit
+  transactions_limit: 0,   # 0 for no limit
+  external_id: "subscription-42"
+)
+
+subscription = client.check_subscription(external_id: "subscription-42")
+
+subscription = client.stop_subscription(id: subscription.id)
+
+history = client.get_subscription_history(status: :active)
+```
+
+Start, check and stop return the subscription with its `params`; the history
+returns the usage counters `transactions_used`, `energy_used` and `total_price`
+instead, and leaves `params` `nil`. A subscription moves through the statuses in
+`Tronzap::Models::SUBSCRIPTION_STATUSES`. A subscription with a transactions limit
+cannot be stopped (`CANNOT_STOP_SUBSCRIPTION`).
+
 ## Error handling
 
 Every failure of an API call is a `Tronzap::Error`. Rescue a subclass to handle
@@ -340,11 +386,11 @@ a non-zero code is always reported as `Tronzap::ApiError`, never as
 | 2 | `INVALID_SERVICE_OR_PARAMS` | Invalid service or parameters |
 | 5 | `WALLET_NOT_FOUND` | Internal wallet not found. Contact support. |
 | 6 | `INSUFFICIENT_FUNDS` | Insufficient funds |
-| 10 | `INVALID_TRON_ADDRESS` | Invalid TRON address |
+| 10 | `INVALID_TRON_ADDRESS` | Invalid TRON address, or the address already has an active subscription |
 | 11 | `INVALID_ENERGY_AMOUNT` | Invalid energy amount |
 | 12 | `INVALID_DURATION` | Invalid duration |
 | 20 | `TRANSACTION_NOT_FOUND` | Transaction/subscription not found |
-| 21 | `CANNOT_STOP_SUBSCRIPTION` | Cannot stop subscription |
+| 21 | `CANNOT_STOP_SUBSCRIPTION` | Cannot stop subscription, e.g. it has a transactions limit |
 | 24 | `ADDRESS_NOT_ACTIVATED` | Address not activated |
 | 25 | `ADDRESS_ALREADY_ACTIVATED` | Address already activated |
 | 30 | `AML_CHECK_NOT_FOUND` | AML check not found |

data/README.pt-br.md

@@ -57,7 +57,7 @@ begin
 
   transaction = client.create_energy_transaction(
     address: "TRecipientAddress",
-    energy: estimate.energy,
+    energy: estimate.amount,
     duration: 1,
     external_id: "order-42",
     activate_address: true
@@ -184,6 +184,11 @@ outras bibliotecas HTTP precisam ser traduzidos pelo adaptador, como acima.
 | `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Iniciar uma verificação AML |
 | `check_aml_status(id)` | `/v1/aml-checks/check` | Status e resultado de uma verificação AML |
 | `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | Histórico paginado de verificações AML |
+| `get_subscriptions` | `/v1/subscriptions` | Planos de assinatura e preços |
+| `start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0, external_id: nil, activate_address: false)` | `/v1/subscription/start` | Assinar um plano para um endereço |
+| `check_subscription(id: nil, external_id: nil)` | `/v1/subscription/check` | Status de uma assinatura, por id ou id externo |
+| `stop_subscription(id: nil, external_id: nil)` | `/v1/subscription/stop` | Parar uma assinatura |
+| `get_subscription_history(page: 1, per_page: 10, status: nil)` | `/v1/subscriptions/history` | Histórico paginado de assinaturas |
 
 Os métodos com parâmetros aceitam argumentos nomeados ou um objeto de requisição de
 `Tronzap::Requests`, então uma requisição pode ser montada, validada e repassada
@@ -196,11 +201,13 @@ client.create_energy_transaction(request)
 
 Uma requisição é validada ao ser criada, então uma requisição inválida lança
 `ArgumentError` e nunca chega à API. As quantidades devem ser valores `Integer`
-positivos. Os padrões coincidem com a API: `duration` é 1 hora e o histórico AML
-começa na página 1 com 10 itens.
+positivos. Os padrões coincidem com a API: `duration` é 1 hora e os históricos AML
+e de assinaturas começam na página 1 com 10 itens. A exceção é
+`start_subscription`, em que `duration_days` e `transactions_limit` valem 0 por
+padrão, o que significa sem limite.
 
 Os resultados são objetos `Data` imutáveis em `Tronzap::Responses` e
-`Tronzap::Models`, não hashes: `transaction.status`, `estimate.energy`. As coleções
+`Tronzap::Models`, não hashes: `transaction.status`, `estimate.amount`. As coleções
 são congeladas e nunca são `nil`, e os valores que a API pode omitir são `nil`.
 
 ### Comprar recursos
@@ -230,9 +237,10 @@ client.create_resource_bundle_transaction(
 client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
 ```
 
-O preço da energia é por unidade e o da largura de banda é por 1000 unidades: em
-`get_services`, `EnergyRate#price` × 65000 é o custo de 65000 de energia, enquanto
-345 de largura de banda com um `BandwidthRate#price` de 1 custam 0.345.
+Em `get_services`, os preços da energia e da largura de banda são ambos por 1000
+unidades, então uma compra custa `price × amount / 1000`: 65000 de energia com um
+`EnergyRate#price` de 0.03 custam 1.95, e 345 de largura de banda com um
+`BandwidthRate#price` de 1 custam 0.345.
 
 Atualmente a API informa um pacote de recursos com `service` igual a `:energy`, e
 não `:resource_bundle`. Consulte `params.amounts` para saber quais recursos uma
@@ -265,9 +273,50 @@ if result.status == :completed
 end
 ```
 
+Em uma verificação por hash, `address` é o endereço do destinatário da
+transação, onde os fundos foram recebidos, e `direction` indica de que lado você
+está: `:deposit` se os fundos chegaram ao seu endereço (`address` é o seu
+endereço), `:withdrawal` se foi você quem enviou (`address` é o endereço do
+destinatário externo). O risco é calculado para a contraparte: o remetente em um
+deposit, o destinatário em um withdrawal. Sem `direction`, o SDK envia
+`deposit`.
+
 `risk_score` é `nil` até a verificação terminar. Uma verificação concluída pode
 ter pontuação 0, o que não é o mesmo que ainda não ter pontuação.
 
+### Assinaturas
+
+Uma assinatura mantém um endereço abastecido de energia para cada transação até
+ser parada ou esgotar seus dias ou transações. Escolha um plano de
+`get_subscriptions` e passe o seu `subscription_id`, como `"unlimited_energy"`, não
+o `id` numérico. Iniciar uma assinatura cobra o preço inicial do plano.
+
+```ruby
+client.get_subscriptions.each do |plan|
+  puts "#{plan.subscription_id} #{plan.initial_price.to_s("F")} #{plan.price.to_s("F")}"
+end
+
+subscription = client.start_subscription(
+  subscription_id: "unlimited_energy",
+  address: "TRecipientAddress",
+  duration_days: 30,       # 0 para não limitar o tempo
+  transactions_limit: 0,   # 0 para não limitar
+  external_id: "subscription-42"
+)
+
+subscription = client.check_subscription(external_id: "subscription-42")
+
+subscription = client.stop_subscription(id: subscription.id)
+
+history = client.get_subscription_history(status: :active)
+```
+
+Iniciar, consultar e parar retornam a assinatura com seus `params`; o histórico
+retorna em vez disso os contadores de uso `transactions_used`, `energy_used` e
+`total_price`, e deixa `params` como `nil`. Os status de uma assinatura estão em
+`Tronzap::Models::SUBSCRIPTION_STATUSES`. Uma assinatura com limite de transações
+não pode ser parada (`CANNOT_STOP_SUBSCRIPTION`).
+
 ## Tratamento de erros
 
 Toda falha de uma chamada à API é um `Tronzap::Error`. Capture uma subclasse para
@@ -339,11 +388,11 @@ diferente de zero é sempre informado como `Tronzap::ApiError`, nunca como
 | 2 | `INVALID_SERVICE_OR_PARAMS` | Serviço ou parâmetros inválidos |
 | 5 | `WALLET_NOT_FOUND` | Carteira interna não encontrada. Contate o suporte. |
 | 6 | `INSUFFICIENT_FUNDS` | Saldo insuficiente |
-| 10 | `INVALID_TRON_ADDRESS` | Endereço TRON inválido |
+| 10 | `INVALID_TRON_ADDRESS` | Endereço TRON inválido, ou o endereço já tem uma assinatura ativa |
 | 11 | `INVALID_ENERGY_AMOUNT` | Quantidade de energia inválida |
 | 12 | `INVALID_DURATION` | Duração inválida |
 | 20 | `TRANSACTION_NOT_FOUND` | Transação/assinatura não encontrada |
-| 21 | `CANNOT_STOP_SUBSCRIPTION` | Não é possível interromper a assinatura |
+| 21 | `CANNOT_STOP_SUBSCRIPTION` | Não é possível interromper a assinatura, p. ex. ela tem limite de transações |
 | 24 | `ADDRESS_NOT_ACTIVATED` | Endereço não ativado |
 | 25 | `ADDRESS_ALREADY_ACTIVATED` | Endereço já ativado |
 | 30 | `AML_CHECK_NOT_FOUND` | Verificação AML não encontrada |

data/README.ru.md

@@ -57,7 +57,7 @@ begin
 
   transaction = client.create_energy_transaction(
     address: "TRecipientAddress",
-    energy: estimate.energy,
+    energy: estimate.amount,
     duration: 1,
     external_id: "order-42",
     activate_address: true
@@ -185,6 +185,11 @@ HTTP-библиотек адаптер должен преобразовать
 | `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Запустить AML-проверку |
 | `check_aml_status(id)` | `/v1/aml-checks/check` | Статус и результат AML-проверки |
 | `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | История AML-проверок с пагинацией |
+| `get_subscriptions` | `/v1/subscriptions` | Планы подписок и цены |
+| `start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0, external_id: nil, activate_address: false)` | `/v1/subscription/start` | Подписать адрес на план |
+| `check_subscription(id: nil, external_id: nil)` | `/v1/subscription/check` | Статус подписки по id или внешнему id |
+| `stop_subscription(id: nil, external_id: nil)` | `/v1/subscription/stop` | Остановить подписку |
+| `get_subscription_history(page: 1, per_page: 10, status: nil)` | `/v1/subscriptions/history` | История подписок с пагинацией |
 
 Методы с параметрами принимают либо именованные аргументы, либо объект запроса из
 `Tronzap::Requests`, поэтому запрос можно создать, проверить и передать дальше до
@@ -198,10 +203,12 @@ client.create_energy_transaction(request)
 Запрос проверяется при создании, поэтому невалидный запрос вызывает
 `ArgumentError` и никогда не доходит до API. Количества должны быть
 положительными `Integer`. Значения по умолчанию совпадают с API: `duration` —
-1 час, история AML начинается со страницы 1 по 10 элементов.
+1 час, история AML и подписок начинается со страницы 1 по 10 элементов.
+Исключение — `start_subscription`: `duration_days` и `transactions_limit` по
+умолчанию равны 0, что означает отсутствие ограничения.
 
 Результаты — неизменяемые объекты `Data` в `Tronzap::Responses` и
-`Tronzap::Models`, а не хеши: `transaction.status`, `estimate.energy`. Коллекции
+`Tronzap::Models`, а не хеши: `transaction.status`, `estimate.amount`. Коллекции
 заморожены и никогда не бывают `nil`, а значения, которые API может не прислать,
 равны `nil`.
 
@@ -232,9 +239,9 @@ client.create_resource_bundle_transaction(
 client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
 ```
 
-Цена энергии указана за единицу, цена bandwidth — за 1000 единиц: в
-`get_services` `EnergyRate#price` × 65000 — это стоимость 65000 энергии, а 345
-bandwidth при `BandwidthRate#price`, равном 1, стоят 0.345.
+В `get_services` цены энергии и bandwidth указаны за 1000 единиц, поэтому покупка
+стоит `price × amount / 1000`: 65000 энергии при `EnergyRate#price`, равном 0.03,
+стоят 1.95, а 345 bandwidth при `BandwidthRate#price`, равном 1, стоят 0.345.
 
 Сейчас API возвращает пакет ресурсов с `service`, равным `:energy`, а не
 `:resource_bundle`. Состав покупки смотрите в `params.amounts`.
@@ -266,9 +273,50 @@ if result.status == :completed
 end
 ```
 
+Для проверки по hash `address` — это адрес получателя средств в транзакции, а
+`direction` указывает, на какой стороне транзакции вы: `:deposit`, если средства
+пришли на ваш адрес (`address` — ваш адрес), `:withdrawal`, если их отправили вы
+(`address` — адрес внешнего получателя). Риск оценивается для контрагента: для
+deposit — для отправителя, для withdrawal — для получателя. Без `direction` SDK
+отправляет `deposit`.
+
 `risk_score` равен `nil`, пока проверка не завершится. У завершённой проверки score
 может быть равен 0, и это не то же самое, что отсутствие результата.
 
+### Подписки
+
+Подписка обеспечивает адрес энергией для каждой транзакции, пока её не
+остановят или не закончатся её дни или транзакции. Выберите план из
+`get_subscriptions` и передайте его `subscription_id`, например
+`"unlimited_energy"`, а не числовой `id`. Запуск подписки списывает начальную
+цену плана.
+
+```ruby
+client.get_subscriptions.each do |plan|
+  puts "#{plan.subscription_id} #{plan.initial_price.to_s("F")} #{plan.price.to_s("F")}"
+end
+
+subscription = client.start_subscription(
+  subscription_id: "unlimited_energy",
+  address: "TRecipientAddress",
+  duration_days: 30,       # 0 — без ограничения по времени
+  transactions_limit: 0,   # 0 — без ограничения
+  external_id: "subscription-42"
+)
+
+subscription = client.check_subscription(external_id: "subscription-42")
+
+subscription = client.stop_subscription(id: subscription.id)
+
+history = client.get_subscription_history(status: :active)
+```
+
+Запуск, проверка и остановка возвращают подписку с её `params`, а история
+вместо них — счётчики использования `transactions_used`, `energy_used` и
+`total_price`, и `params` в ней равен `nil`. Статусы подписки перечислены в
+`Tronzap::Models::SUBSCRIPTION_STATUSES`. Подписку с лимитом транзакций
+остановить нельзя (`CANNOT_STOP_SUBSCRIPTION`).
+
 ## Обработка ошибок
 
 Любой сбой вызова API — исключение `Tronzap::Error`. Перехватывайте подкласс, чтобы
@@ -339,11 +387,11 @@ end
 | 2 | `INVALID_SERVICE_OR_PARAMS` | Неверный сервис или параметры |
 | 5 | `WALLET_NOT_FOUND` | Внутренний кошелёк не найден. Обратитесь в поддержку. |
 | 6 | `INSUFFICIENT_FUNDS` | Недостаточно средств |
-| 10 | `INVALID_TRON_ADDRESS` | Неверный адрес TRON |
+| 10 | `INVALID_TRON_ADDRESS` | Неверный адрес TRON, или у адреса уже есть активная подписка |
 | 11 | `INVALID_ENERGY_AMOUNT` | Неверное количество энергии |
 | 12 | `INVALID_DURATION` | Неверная длительность |
 | 20 | `TRANSACTION_NOT_FOUND` | Транзакция/подписка не найдена |
-| 21 | `CANNOT_STOP_SUBSCRIPTION` | Невозможно остановить подписку |
+| 21 | `CANNOT_STOP_SUBSCRIPTION` | Невозможно остановить подписку, например, у неё есть лимит транзакций |
 | 24 | `ADDRESS_NOT_ACTIVATED` | Адрес не активирован |
 | 25 | `ADDRESS_ALREADY_ACTIVATED` | Адрес уже активирован |
 | 30 | `AML_CHECK_NOT_FOUND` | AML-проверка не найдена |

data/lib/tronzap/client.rb

@@ -4,8 +4,8 @@ require "digest"
 require "json"
 
 module Tronzap
-  # Client for the {https://docs.tronzap.com/ TronZap API}: buy TRON energy and bandwidth, activate addresses and
-  # run AML checks.
+  # Client for the {https://docs.tronzap.com/ TronZap API}: buy TRON energy and bandwidth, activate addresses, run
+  # AML checks and manage energy subscriptions.
   #
   # A client is immutable and safe to share between threads. Create one per set of credentials.
   #
@@ -157,7 +157,7 @@ module Tronzap
       post("/v1/aml-checks", {}) { Responses::AmlService.list_from_api(_1) }
     end
 
-    # Starts an AML screening of an address or a transaction.
+    # Starts an AML screening of an address or a transaction. A hash check without a direction sends +deposit+.
     #
     # @overload create_aml_check(request)
     #   @param request [Requests::AmlCheck] see {Requests::AmlCheck.for_address} and {Requests::AmlCheck.for_hash}
@@ -191,6 +191,65 @@ module Tronzap
       post("/v1/aml-checks/history", body) { Responses::AmlHistory.from_api(_1) }
     end
 
+    # Subscription plans on sale, in the order the API lists them.
+    #
+    # @return [Array<Responses::SubscriptionPlan>]
+    # @raise [Error]
+    def get_subscriptions
+      post("/v1/subscriptions", {}) { Responses::SubscriptionPlan.list_from_api(_1) }
+    end
+
+    # Subscribes an address to a plan from {#get_subscriptions}. Starting a subscription charges the plan's initial
+    # price.
+    #
+    # @overload start_subscription(request)
+    #   @param request [Requests::StartSubscription]
+    # @overload start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0,
+    #                              external_id: nil, activate_address: false)
+    # @return [Responses::Subscription]
+    # @raise [ArgumentError, Error]
+    def start_subscription(request = nil, **params)
+      body = build(Requests::StartSubscription, request, params).body
+      post("/v1/subscription/start", body) { Responses::Subscription.from_api(_1) }
+    end
+
+    # The current state of a subscription, by its TronZap ID or by your external ID.
+    #
+    # @overload check_subscription(request)
+    #   @param request [Requests::SubscriptionLookup]
+    # @overload check_subscription(id: nil, external_id: nil)
+    # @return [Responses::Subscription]
+    # @raise [ArgumentError, Error]
+    def check_subscription(request = nil, **params)
+      body = build(Requests::SubscriptionLookup, request, params).body
+      post("/v1/subscription/check", body) { Responses::Subscription.from_api(_1) }
+    end
+
+    # Stops a subscription, by its TronZap ID or by your external ID. A subscription with a transactions limit
+    # cannot be stopped and fails with {ErrorCode::CANNOT_STOP_SUBSCRIPTION}.
+    #
+    # @overload stop_subscription(request)
+    #   @param request [Requests::SubscriptionLookup]
+    # @overload stop_subscription(id: nil, external_id: nil)
+    # @return [Responses::Subscription]
+    # @raise [ArgumentError, Error]
+    def stop_subscription(request = nil, **params)
+      body = build(Requests::SubscriptionLookup, request, params).body
+      post("/v1/subscription/stop", body) { Responses::Subscription.from_api(_1) }
+    end
+
+    # One page of your subscriptions, newest first.
+    #
+    # @overload get_subscription_history(request)
+    #   @param request [Requests::SubscriptionHistory]
+    # @overload get_subscription_history(page: 1, per_page: 10, status: nil)
+    # @return [Responses::SubscriptionHistory]
+    # @raise [ArgumentError, Error]
+    def get_subscription_history(request = nil, **params)
+      body = build(Requests::SubscriptionHistory, request, params).body
+      post("/v1/subscriptions/history", body) { Responses::SubscriptionHistory.from_api(_1) }
+    end
+
     # @return [String] a description that leaves out the credentials
     def inspect
       "#<#{self.class.name} base_url=#{config.base_url.inspect}>"

data/lib/tronzap/coerce.rb

@@ -53,6 +53,10 @@ module Tronzap
       number.to_i
     end
 
+    def optional_integer(value, name)
+      value.nil? ? nil : integer(value, name)
+    end
+
     def decimal(value, name)
       optional_decimal(value, name) || BigDecimal(0)
     end

data/lib/tronzap/errors.rb

@@ -123,7 +123,8 @@ module Tronzap
     WALLET_NOT_FOUND = 5
     # Insufficient funds: top up the account or request a smaller amount.
     INSUFFICIENT_FUNDS = 6
-    # Invalid TRON address: it should be a valid 34-character TRON address.
+    # Invalid TRON address: it should be a valid 34-character TRON address. Also reported when the address already
+    # has an active subscription.
     INVALID_TRON_ADDRESS = 10
     # Invalid energy amount.
     INVALID_ENERGY_AMOUNT = 11
@@ -132,7 +133,7 @@ module Tronzap
     # Transaction or subscription not found: check the transaction ID or external ID. The API reports this code
     # under the key +subscription_not_found+.
     TRANSACTION_NOT_FOUND = 20
-    # The subscription cannot be stopped right now.
+    # Cannot stop subscription, for example because it has a transactions limit.
     CANNOT_STOP_SUBSCRIPTION = 21
     # Address not activated: activate it first with an address activation transaction.
     ADDRESS_NOT_ACTIVATED = 24