perata-sdk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ce69fcabc384e43ef9a829c444ced516fb44a64d82daf72fd4d8b7b9ad6dab9
-  data.tar.gz: 43e9821c4ad1cd264bfe59fb8b3fdafabf6d44d31755d067e1e626d21fba753a
+  metadata.gz: ffb21818636a4985aed2e37bed5c804482d4e33f36d59ac855170d95747dac5b
+  data.tar.gz: 2201ef7ba61a245ccf70aed0c7d48d11999f81fd8025a84acaf551ccec09441b
 SHA512:
-  metadata.gz: 74f8e47737ccb716ff1c9d18354c97eb7260f016ade4b5c4ee4d5b3caa4ba4b676f943c1cf60d089f33eb76f63b5f724983edacc1179021e4cc2b2031adea0c2
-  data.tar.gz: f3e2c307da8270f8db0c41d28b1d4b78bd283e65a83c63d6e6d789c466c65be78976f7c1ce080be492f01e9fd189c1cfefee3c08f3daae08d3caf2507f773f92
+  metadata.gz: e9d0be391bcc52e48eeee7fca3ac3ded3bd246aaf5aa595f7c568a231ed6195e7b70cb01bd12df25f2731d3e4ceece23f3c03cf7b9e7f233896f09ebb917e062
+  data.tar.gz: daee592161aed12eaabe847b9d8f43b4651ea18d8cf1ab98decf477343c1153fc356cc78d8443594c694c55cbab2c32b9a2226105b97bf5ab0982333db9749ee

data/README.md

@@ -38,15 +38,36 @@ end
 | `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:`. 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
 
@@ -63,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.3.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

@@ -64,6 +64,8 @@ module Perata
     attr_reader :refunds
     # @return [SubscriptionsService]
     attr_reader :subscriptions
+    # @return [UsageService]
+    attr_reader :usage
     # @return [WebhooksService]
     attr_reader :webhooks
 
@@ -91,6 +93,7 @@ module Perata
       @products = ProductsService.new(self)
       @refunds = RefundsService.new(self)
       @subscriptions = SubscriptionsService.new(self)
+      @usage = UsageService.new(self)
       @webhooks = WebhooksService.new(self)
     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

data/lib/perata/models.rb

@@ -1693,6 +1693,45 @@ module Perata
     end
   end
 
+  # UsageError is a resource of Peráta's API.
+  class UsageError < Model
+    MEMBERS = %i[error fields message record].freeze
+
+    # Código do erro: invalid_credential, invalid_request, conflict, unsupported_media_type, body_too_large, rate_limited ou unavailable.
+    # @return [String]
+    attr_reader :error
+
+    # Em invalid_request, o que há de errado em cada campo do evento.
+    # @return [Hash{String => Array<String>}, nil]
+    attr_reader :fields
+
+    # O que explica a recusa, em inglês.
+    # @return [String, nil]
+    attr_reader :message
+
+    # Posição, a partir de 1, do evento do lote que causou a recusa (invalid_request e conflict); o lote inteiro foi revertido.
+    # @return [Integer, nil]
+    attr_reader :record
+
+    def initialize(error:, fields: nil, message: nil, record: nil)
+      @error = error
+      @fields = fields
+      @message = message
+      @record = record
+      freeze
+    end
+
+    # Builds a UsageError from the API's JSON.
+    def self.from_hash(data)
+      new(
+        error: data.fetch("error"),
+        fields: data["fields"],
+        message: data["message"],
+        record: data["record"]
+      )
+    end
+  end
+
   # WebhookBenefit is a resource of Peráta's API.
   class WebhookBenefit < Model
     MEMBERS = %i[created_at description id modified_at name status type visibility].freeze
@@ -2208,4 +2247,29 @@ module Perata
       )
     end
   end
+
+  # What usage.ingest answers.
+  class UsageIngestReceipt < Model
+    MEMBERS = %i[created replayed].freeze
+
+    # @return [Integer]
+    attr_reader :created
+
+    # @return [Integer]
+    attr_reader :replayed
+
+    def initialize(created:, replayed:)
+      @created = created
+      @replayed = replayed
+      freeze
+    end
+
+    # Builds a UsageIngestReceipt from the API's JSON.
+    def self.from_hash(data)
+      new(
+        created: data.fetch("created"),
+        replayed: data.fetch("replayed")
+      )
+    end
+  end
 end

data/lib/perata/params.rb

@@ -346,6 +346,7 @@ module Perata
     # @return [String]
     attr_reader :email
 
+    # Até 120 caracteres, sem barra (/) nem caracteres de controle.
     # @return [String, nil]
     attr_reader :external_id
 
@@ -376,7 +377,7 @@ module Perata
     # @return [String, nil]
     attr_reader :email
 
-    # Só pode ser definido uma vez.
+    # Só pode ser definido uma vez. Até 120 caracteres, sem barra (/) nem caracteres de controle.
     # @return [String, nil]
     attr_reader :external_id
 
@@ -559,7 +560,7 @@ module Perata
     # @return [String, nil]
     attr_reader :email
 
-    # Só pode ser definido uma vez.
+    # Só pode ser definido uma vez. Até 120 caracteres, sem barra (/) nem caracteres de controle.
     # @return [String, nil]
     attr_reader :external_id
 
@@ -590,6 +591,7 @@ module Perata
     # @return [Integer]
     attr_reader :amount_cents
 
+    # Obrigatório no preço recorrente; o preço one_time não tem intervalo.
     # @return [String ("month", "year"), nil]
     attr_reader :interval
 
@@ -761,6 +763,143 @@ module Perata
     end
   end
 
+  # The body of usage.ingest.
+  class UsageIngestParams < Params
+    MEMBERS = %i[events].freeze
+
+    # @return [Array<UsageIngestEvent>]
+    attr_reader :events
+
+    def initialize(events:)
+      @events = events
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["events"] = Perata.wire(@events)
+      wire
+    end
+  end
+
+  # Opcional. O custo de atender o evento para o vendedor, em metadata._cost; alimenta Análises › Custos e as margens.
+  class UsageIngestEventCost < Params
+    MEMBERS = %i[amount currency].freeze
+
+    # Custo em centavos, como string decimal com até seis casas.
+    # @return [String]
+    attr_reader :amount
+
+    # Moeda do custo. Apenas brl.
+    # @return [String ("brl")]
+    attr_reader :currency
+
+    def initialize(amount:, currency:)
+      @amount = amount
+      @currency = currency
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["amount"] = @amount
+      wire["currency"] = @currency
+      wire
+    end
+  end
+
+  # Opcional. O modelo e o fornecedor que atenderam o evento, em metadata._llm; os contadores continuam nos campos de tokens.
+  class UsageIngestEventLlm < Params
+    MEMBERS = %i[model vendor].freeze
+
+    # Modelo que atendeu o evento.
+    # @return [String]
+    attr_reader :model
+
+    # Fornecedor do modelo.
+    # @return [String]
+    attr_reader :vendor
+
+    def initialize(model:, vendor:)
+      @model = model
+      @vendor = vendor
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["model"] = @model
+      wire["vendor"] = @vendor
+      wire
+    end
+  end
+
+  # One item of events in UsageIngestParams.
+  class UsageIngestEvent < Params
+    MEMBERS = %i[_cost _llm cached_tokens customer_id external_event_id input_tokens occurred_at output_tokens parent_id].freeze
+
+    # Opcional. O custo de atender o evento para o vendedor, em metadata._cost; alimenta Análises › Custos e as margens.
+    # @return [UsageIngestEventCost, nil]
+    attr_reader :_cost
+
+    # Opcional. O modelo e o fornecedor que atenderam o evento, em metadata._llm; os contadores continuam nos campos de tokens.
+    # @return [UsageIngestEventLlm, nil]
+    attr_reader :_llm
+
+    # @return [String]
+    attr_reader :cached_tokens
+
+    # @return [String]
+    attr_reader :customer_id
+
+    # @return [String]
+    attr_reader :external_event_id
+
+    # @return [String]
+    attr_reader :input_tokens
+
+    # @return [String]
+    attr_reader :occurred_at
+
+    # @return [String]
+    attr_reader :output_tokens
+
+    # Opcional. O evento pai, pelo id da Peráta ou pelo external_event_id que a mesma fonte enviou; o pai precisa chegar antes, inclusive antes no mesmo lote.
+    # @return [String, nil]
+    attr_reader :parent_id
+
+    def initialize(_cost: nil, _llm: nil, cached_tokens:, customer_id:, external_event_id:, input_tokens:, occurred_at:, output_tokens:, parent_id: nil)
+      @_cost = _cost
+      @_llm = _llm
+      @cached_tokens = cached_tokens
+      @customer_id = customer_id
+      @external_event_id = external_event_id
+      @input_tokens = input_tokens
+      @occurred_at = occurred_at
+      @output_tokens = output_tokens
+      @parent_id = parent_id
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["_cost"] = Perata.wire(@_cost) unless @_cost.nil?
+      wire["_llm"] = Perata.wire(@_llm) unless @_llm.nil?
+      wire["cached_tokens"] = @cached_tokens
+      wire["customer_id"] = @customer_id
+      wire["external_event_id"] = @external_event_id
+      wire["input_tokens"] = @input_tokens
+      wire["occurred_at"] = @occurred_at
+      wire["output_tokens"] = @output_tokens
+      wire["parent_id"] = @parent_id unless @parent_id.nil?
+      wire
+    end
+  end
+
   # The body of webhooks:create_endpoint.
   class WebhooksCreateEndpointParams < Params
     MEMBERS = %i[description events format url].freeze

data/lib/perata/services.rb

@@ -730,6 +730,22 @@ module Perata
     end
   end
 
+  # The API's usage.
+  class UsageService
+    def initialize(client)
+      @client = client
+    end
+
+    # Ingerir lote atômico de eventos de uso. Autentica com a credencial de uma fonte de ingestão (pus_test_… ou pus_live_…), não com a chave de API da organização.
+    #
+    # @param params [UsageIngestParams, Hash]
+    # @return [UsageIngestReceipt]
+    def ingest(params, api_key: nil)
+      data = @client.request("POST", "/api/v1/usage/token-events", body: UsageIngestParams.coerce(params).to_wire, api_key: api_key)
+      UsageIngestReceipt.from_hash(data)
+    end
+  end
+
   # The API's webhooks.
   class WebhooksService
     def initialize(client)

data/lib/perata/version.rb

@@ -4,7 +4,7 @@
 
 module Perata
   # This SDK's version.
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 
   # The contract this SDK was generated from.
   API_VERSION = "0.1.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perata-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Peráta
@@ -45,7 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: 'Peráta''s SDK for Ruby: products, customers, checkouts, payments, subscriptions
   and webhooks.'