perata-sdk 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e636bdc22e1cf5cb23c0d1b1f93f3154362b6ada48dcc56e780847de36f578f7
-  data.tar.gz: a29323a115321b71d10b6031b7170c6fda3e7d23e192ba1463e29afcc519d51f
+  metadata.gz: ffb21818636a4985aed2e37bed5c804482d4e33f36d59ac855170d95747dac5b
+  data.tar.gz: 2201ef7ba61a245ccf70aed0c7d48d11999f81fd8025a84acaf551ccec09441b
 SHA512:
-  metadata.gz: 5b88a3f310e277f889147d95801565704b294120a2d6dc0f9809ced9c214753c8638b3b50e5deeb94fb2c785d811fe1759de836246b41e7652352c7aa4b92532
-  data.tar.gz: b3f215424482e048dc8c24ef20262938d3f1808795573f91c9c4684529f3bd17b6992625d484106c5ebc40f92c258cdfe1a6319839e244926e7f10842300dd08
+  metadata.gz: e9d0be391bcc52e48eeee7fca3ac3ded3bd246aaf5aa595f7c568a231ed6195e7b70cb01bd12df25f2731d3e4ceece23f3c03cf7b9e7f233896f09ebb917e062
+  data.tar.gz: daee592161aed12eaabe847b9d8f43b4651ea18d8cf1ab98decf477343c1153fc356cc78d8443594c694c55cbab2c32b9a2226105b97bf5ab0982333db9749ee

data/README.md

@@ -22,24 +22,52 @@ end
 
 | Serviço | Métodos |
 |---|---|
-| `perata.checkouts` | `create` |
+| `perata.benefits` | `create`, `delete`, `get`, `list`, `list_iter`, `list_grants`, `list_grants_iter`, `update` |
+| `perata.checkout_links` | `create`, `delete`, `get`, `list`, `list_iter`, `update` |
+| `perata.checkouts` | `create`, `get`, `update` |
 | `perata.customer_sessions` | `create` |
-| `perata.customers` | `create`, `get`, `list`, `list_iter` |
-| `perata.orders` | `list`, `list_iter` |
+| `perata.customers` | `create`, `delete`, `get`, `get_external`, `get_state`, `list`, `list_iter`, `update`, `update_external` |
+| `perata.discounts` | `create`, `delete`, `get`, `list`, `list_iter`, `update` |
+| `perata.disputes` | `get`, `list`, `list_iter` |
+| `perata.events` | `list`, `list_iter` |
+| `perata.meters` | `get`, `list`, `list_iter` |
+| `perata.orders` | `get`, `get_invoice`, `get_receipt`, `list`, `list_iter` |
 | `perata.payment_methods` | `detach`, `list`, `list_iter` |
 | `perata.payments` | `get`, `list`, `list_iter` |
 | `perata.prices` | `create`, `list`, `list_iter` |
-| `perata.products` | `create`, `get`, `list`, `list_iter` |
-| `perata.refunds` | `create` |
-| `perata.subscriptions` | `cancel`, `get`, `list`, `list_iter` |
+| `perata.products` | `archive`, `create`, `get`, `list`, `list_iter`, `update` |
+| `perata.refunds` | `create`, `list`, `list_iter` |
+| `perata.subscriptions` | `cancel`, `get`, `list`, `list_iter`, `update` |
+| `perata.usage` | `ingest` |
+| `perata.webhooks` | `create_endpoint`, `delete_endpoint`, `get_endpoint`, `list_deliveries`, `list_deliveries_iter`, `list_endpoints`, `list_endpoints_iter`, `update_endpoint` |
 
 Os modelos são objetos imutáveis com leitores em snake_case (`payment.amount_cents`). O corpo de uma escrita é a classe de parâmetros do método (`Perata::ProductsCreateParams.new(name: "Curso")`) ou um `Hash` com os mesmos nomes; um campo opcional não informado fica fora do JSON. Os métodos `_iter` devolvem um `Enumerator` que percorre todas as páginas a partir de `page:` (ou recebem um bloco).
 
-As escritas aceitam `idempotency_key:`, e todas aceitam `api_key:` para usar a chave de outra organização numa chamada. `Perata::Client.new` aceita `base_url:`, `timeout:` (30 segundos) e `transport:`.
+As escritas aceitam `idempotency_key:`, e todas aceitam `api_key:` para usar a chave de outra organização numa chamada. `Perata::Client.new` aceita `base_url:`, `timeout:` (30 segundos) e `transport:`. Um POST sem chave de idempotência é enviado com uma `Idempotency-Key` própria (UUID v4 aleatório, uma por chamada); passe a sua para poder repetir a mesma operação com segurança.
+
+## Consumo (ingestão de eventos)
+
+A ingestão de consumo usa outra credencial: a de uma fonte de ingestão (**Configurações › Fontes de ingestão**), `pus_test_…` em teste e `pus_live_…` em produção. Monte um cliente com ela; a chave de API da organização (`prk_…`) é recusada aqui com 401, e uma credencial de um ambiente nunca escreve no outro.
+
+```ruby
+usage = Perata::Client.new(ENV.fetch("PERATA_USAGE_KEY")) # pus_test_… ou pus_live_…
+
+receipt = usage.usage.ingest({ events: [{
+  customer_id: customer_id,
+  external_event_id: "requisicao-001", # a mesma fonte repetindo o id com o mesmo conteúdo é replay
+  input_tokens: "1200",
+  output_tokens: "300",
+  cached_tokens: "0",
+  occurred_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ") # segundos inteiros, até 90 dias atrás
+}] })
+# receipt.created, receipt.replayed
+```
+
+De 1 a 100 eventos por chamada, até 64 KiB, todos gravados ou nenhum. Não há `Idempotency-Key` aqui: a identidade de um evento é o `external_event_id` da fonte, e repetir uma chamada é seguro (`replayed`); o mesmo id com outro conteúdo responde 409 (`conflict`), e um evento inválido, 422 (`invalid_request`) com `record` dizendo qual, a partir de 1.
 
 ## Erros
 
-Uma recusa da API levanta `Perata::Error`, com `status`, `code` (`invalid_request`, `not_found`…), `message`, `fields` (o problema de cada campo) e, num 429, `retry_after` em segundos.
+Uma recusa da API levanta `Perata::Error`, com `status`, `code` (`invalid_request`, `not_found`…), `message`, `fields` (o problema de cada campo), `record` (na ingestão, o evento recusado) e, num 429, `retry_after` em segundos.
 
 ## Webhooks
 
@@ -56,4 +84,4 @@ A assinatura é a do Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webh
 
 O evento é tipado: um tipo para cada dado que o webhook carrega (`OrderWebhookEvent` traz um `Order`, `DisputeWebhookEvent` a disputa, `IdentifiersWebhookEvent` os identificadores…), e o `type` diz o que aconteceu; um tipo que esta versão do SDK ainda não conhece chega como `UnknownWebhookEvent`, com os dados como vieram. Durante a rotação do segredo o cabeçalho traz mais de uma assinatura, e basta uma conferir. `Perata.verify_webhook_signature` só confere a assinatura.
 
-Versão do SDK: 0.2.0 · contrato da API: 0.1.0
+Versão do SDK: 0.4.0 · contrato da API: 0.1.0

data/lib/perata/client.rb

@@ -2,8 +2,10 @@
 
 # Code generated by sdk/generator. DO NOT EDIT.
 
+require "ipaddr"
 require "json"
 require "net/http"
+require "securerandom"
 require "uri"
 
 module Perata
@@ -30,12 +32,24 @@ module Perata
   #   product = perata.products.create({ name: "Curso" })
   #   perata.products.list_iter { |product| puts product.name }
   class Client
+    # @return [BenefitsService]
+    attr_reader :benefits
+    # @return [CheckoutLinksService]
+    attr_reader :checkout_links
     # @return [CheckoutsService]
     attr_reader :checkouts
     # @return [CustomerSessionsService]
     attr_reader :customer_sessions
     # @return [CustomersService]
     attr_reader :customers
+    # @return [DiscountsService]
+    attr_reader :discounts
+    # @return [DisputesService]
+    attr_reader :disputes
+    # @return [EventsService]
+    attr_reader :events
+    # @return [MetersService]
+    attr_reader :meters
     # @return [OrdersService]
     attr_reader :orders
     # @return [PaymentMethodsService]
@@ -50,15 +64,28 @@ module Perata
     attr_reader :refunds
     # @return [SubscriptionsService]
     attr_reader :subscriptions
+    # @return [UsageService]
+    attr_reader :usage
+    # @return [WebhooksService]
+    attr_reader :webhooks
 
+    # The base URL must be https; http is accepted only for localhost,
+    # 127.0.0.0/8 and ::1, and any other raises ArgumentError.
     def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, transport: NetHTTPTransport.new)
       @api_key = api_key
       @base_url = base_url.chomp("/")
+      check_base_url!(@base_url)
       @timeout = timeout
       @transport = transport
+      @benefits = BenefitsService.new(self)
+      @checkout_links = CheckoutLinksService.new(self)
       @checkouts = CheckoutsService.new(self)
       @customer_sessions = CustomerSessionsService.new(self)
       @customers = CustomersService.new(self)
+      @discounts = DiscountsService.new(self)
+      @disputes = DisputesService.new(self)
+      @events = EventsService.new(self)
+      @meters = MetersService.new(self)
       @orders = OrdersService.new(self)
       @payment_methods = PaymentMethodsService.new(self)
       @payments = PaymentsService.new(self)
@@ -66,6 +93,8 @@ module Perata
       @products = ProductsService.new(self)
       @refunds = RefundsService.new(self)
       @subscriptions = SubscriptionsService.new(self)
+      @usage = UsageService.new(self)
+      @webhooks = WebhooksService.new(self)
     end
 
     # Calls the API and answers what it wrapped in +data+; a refusal raises
@@ -84,11 +113,35 @@ module Perata
         data = JSON.generate(body)
         headers["Content-Type"] = "application/json"
       end
+      # A POST is sent with a key of its own, one a call, unless the caller gave one.
+      idempotency_key = SecureRandom.uuid if (idempotency_key.nil? || idempotency_key.empty?) && method == "POST"
       headers["Idempotency-Key"] = idempotency_key if idempotency_key && !idempotency_key.empty?
       status, response_headers, raw = @transport.call(method, url, headers, data, @timeout)
       raise Error.from_response(status, response_headers, raw) if status >= 300
 
+      return nil if status == 204
+
       JSON.parse(raw).fetch("data")
     end
+
+    private
+
+    def check_base_url!(base_url)
+      uri = begin
+        URI.parse(base_url)
+      rescue URI::InvalidURIError
+        nil
+      end
+      scheme = uri&.scheme.to_s.downcase
+      host = uri&.hostname.to_s.downcase
+      loopback = host == "localhost" || begin
+        IPAddr.new(host).loopback?
+      rescue IPAddr::Error
+        false
+      end
+      return if scheme == "https" || (scheme == "http" && loopback)
+
+      raise ArgumentError, "perata: the base URL must be https (http is accepted only for localhost, 127.0.0.0/8 and ::1), so the API key is never sent in clear text"
+    end
   end
 end

data/lib/perata/error.rb

@@ -6,19 +6,22 @@ module Perata
   # A request the API refused.
   #
   # +code+ is the API's: invalid_credential, forbidden, not_found,
-  # invalid_request, conflict, idempotency_conflict, body_too_large or
-  # unavailable. +message+ is the API's explanation, +fields+ says, for
-  # invalid_request, what is wrong with each field, and +retry_after+ is how
-  # many seconds to wait on a 429.
+  # invalid_request, conflict, idempotency_conflict, unsupported_media_type, body_too_large, rate_limited or
+  # unavailable.
+  # +message+ is the API's explanation, +fields+ says, for invalid_request,
+  # what is wrong with each field, +record+ is, for the usage ingestion, the
+  # position (from 1) in the batch of the event the API refused (0 for any other
+  # error), and +retry_after+ is how many seconds to wait on a 429.
   class Error < StandardError
-    attr_reader :status, :code, :message, :fields, :retry_after
+    attr_reader :status, :code, :message, :fields, :retry_after, :record
 
-    def initialize(status, code, message = "", fields = {}, retry_after = nil)
+    def initialize(status, code, message = "", fields = {}, retry_after = nil, record = 0)
       @status = status
       @code = code
       @message = message
       @fields = fields
       @retry_after = retry_after
+      @record = record
       super(message.empty? ? "perata: #{status} #{code}" : "perata: #{status} #{code}: #{message}")
     end
 
@@ -35,9 +38,12 @@ module Perata
       rescue JSON::ParserError
         {} # A refusal without a JSON body is still a refusal.
       end
+      # Every error is the problem itself (error, message, fields). Servers from before
+      # that document wrapped the usage ingestion's errors in data: still read.
+      data = data["data"] if !data.key?("error") && data["data"].is_a?(Hash)
       retry_after = headers["retry-after"].to_s
       new(status, data["error"].to_s, data["message"].to_s, data["fields"] || {},
-          retry_after.match?(/\A\d+\z/) ? retry_after.to_i : nil)
+          retry_after.match?(/\A\d+\z/) ? retry_after.to_i : nil, data["record"].is_a?(Integer) ? data["record"] : 0)
     end
   end
 end