alpr-sdk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4fe27e01fe43c79174d04f2bb769b5cd3f487e3a54278a68e4ea626727de4f79
+  data.tar.gz: 35388b593ab3f741564794a6d63110c6a1d64441b0d9b785b445e7f52c8323f5
+SHA512:
+  metadata.gz: 80c64ff501bbdde4d6eaacdd13a4ffc9b5e64c62e1cabf288c8af6dfde159170787feb5e88f97ea4018b970b5df950d4a690b3ba9f31a267222766f3c891b15c
+  data.tar.gz: 45928fcb7090f97919284f67b96f4f3f6132905e65e76920379daa270acc44ce1afe91ae28b95b15206376e7c5f8aee6b82e9956b8b150aa27bf9e3b01d74548

data/README.md

@@ -0,0 +1,119 @@
+# Alpr.sh SDK para Ruby
+
+SDK oficial da API da Alpr.sh para Ruby 3.1+, sem dependências: só `net/http`, `json` e `openssl`. É gerado a partir do contrato da API (`openapi.json`, na raiz de [alpr-sh/sdk](https://github.com/alpr-sh/sdk)) por `generator/`. Não edite os arquivos desta pasta: regenere.
+
+```sh
+gem install alpr-sdk
+```
+
+## Começando
+
+A chave de API (`alpr_live_…`) é a do espaço de trabalho e diz quais escopos as chamadas podem usar. Não há ambiente de teste.
+
+```ruby
+require "alpr"
+
+alpr = Alpr::Client.new(ENV.fetch("ALPR_API_KEY")) # alpr_live_…
+
+# Ler as placas de uma foto.
+result = alpr.photos.recognize({ image: File.binread("foto.jpg"), lpr_confidence: 0.5 })
+result.plates.each { |plate| puts "#{plate.plate} (#{plate.conf})" }
+
+# Percorrer as leituras, da mais nova para a mais antiga, página a página.
+alpr.recognitions.list_iter(plate: "BRA2E19").each do |reading|
+  puts "#{reading.captured_at} #{reading.plate}"
+end
+
+# Listar as câmeras do espaço.
+alpr.cameras.list.each { |camera| puts camera.name }
+
+# O link temporário da imagem de uma leitura.
+image = alpr.recognitions.image("det_123")
+puts image.image_url, image.expires_in
+```
+
+## A foto
+
+A foto é uma `String` com os **bytes** do arquivo (`File.binread`), nunca o caminho. O SDK envia `multipart/form-data` e dá nome e tipo ao arquivo pelos primeiros bytes: JPEG (`FF D8 FF`) vai como `photo.jpg` (`image/jpeg`), PNG como `photo.png` (`image/png`) e qualquer outra coisa como `photo` (`application/octet-stream`), para a API recusar. O corpo é a classe de parâmetros do método (`Alpr::PhotosRecognizeParams.new(image: bytes, lpr_confidence: 0.5)`) ou um `Hash` com os mesmos nomes; um campo opcional não informado não é enviado.
+
+`lpr_confidence` e `min_ocr_confidence` são números de 0 a 1 (`ocr` só aceita `image`).
+
+## Leituras e páginas
+
+`alpr.recognitions.list(before: nil, plate: nil, camera: nil, source: nil)` devolve uma página (`Alpr::Page`, com `items` e `next_cursor`, que é `nil` na última). `list_iter` aceita os mesmos argumentos, devolve um `Enumerator` (ou recebe um bloco) e percorre todas as páginas a partir do cursor `before:` dado (sem ele, da leitura mais nova), seguindo `next_cursor` até o fim. Ele para se o cursor não avançar e no primeiro erro.
+
+```ruby
+page = alpr.recognitions.list(camera: "cam_1")
+page = alpr.recognitions.list(camera: "cam_1", before: page.next_cursor) if page.next_cursor
+```
+
+## Recursos
+
+| Serviço | Métodos |
+|---|---|
+| `alpr.cameras` | `list` |
+| `alpr.photos` | `detect`, `ocr`, `recognize` |
+| `alpr.recognitions` | `image`, `list`, `list_iter` |
+
+Os modelos são objetos imutáveis com leitores em snake_case (`result.credits_remaining`, `plate.coordinate_left`). Um campo opcional que a API não enviou, ou que veio `null`, é `nil`. Todo método aceita `api_key:` para usar outra chave numa chamada. `Alpr::Client.new` aceita `base_url:`, `timeout:` (30 segundos) e `transport:`.
+
+O `base_url` precisa ser `https`; `http` só vale para `localhost`, `127.0.0.0/8` e `::1`, e qualquer outro endereço levanta `ArgumentError`, para a chave nunca viajar em texto puro. Redirecionamentos nunca são seguidos: um 3xx é um `Alpr::Error`. Não há repetição automática de chamadas.
+
+## Erros
+
+Uma recusa da API levanta `Alpr::Error`, com `status`, `code`, `message`, `fields` (vazio, a não ser que a resposta traga o objeto `fields`) e, num 429, `retry_after` em segundos (do cabeçalho `Retry-After`). Uma resposta de erro que não é JSON também é um erro, só com o `status`.
+
+| Status | `code` |
+|---|---|
+| 401 | `invalid_api_key` |
+| 403 | `insufficient_scope` |
+| 402 | `insufficient_credits` |
+| 400 | `missing image`, `invalid_image`, `invalid_option` |
+| 413 | `image_too_large` |
+| 422 | `no_plate` |
+| 404 | `not_found`, `image_unavailable` |
+| 429 | `rate_limited` (com `retry_after`) |
+| 503 | `engine_unavailable`, `storage_unavailable` |
+
+```ruby
+begin
+  alpr.photos.recognize({ image: bytes })
+rescue Alpr::Error => e
+  sleep e.retry_after if e.code == "rate_limited"
+  warn "#{e.status} #{e.code}: #{e.message}"
+end
+```
+
+## Webhooks
+
+A Alpr.sh assina cada entrega com três cabeçalhos (a busca ignora maiúsculas):
+
+- `X-Alprsh-Delivery-Id`: o id da entrega;
+- `X-Alprsh-Timestamp`: segundos Unix do envio;
+- `X-Alprsh-Signature`: `sha256=` e o HMAC-SHA256 em hexadecimal (64 caracteres) de `timestamp + "." + delivery-id + "." + corpo`, com o segredo do endpoint (`whsec_…`) **inteiro, como está**, sem decodificar.
+
+Durante a rotação do segredo o cabeçalho traz mais de uma assinatura, numa linha separada por vírgulas ou em várias linhas; basta uma conferir (no máximo 6; uma assinatura malformada recusa a requisição). O timestamp precisa ter só dígitos ASCII e estar a no máximo 300 segundos (`Alpr::WEBHOOK_TOLERANCE`) de agora. Passe o corpo cru, exatamente como chegou, e verifique antes de interpretar; os cabeçalhos podem vir num `Hash` (um valor pode ser uma lista, uma linha de cabeçalho cada) ou no env do Rack.
+
+```ruby
+begin
+  event = Alpr.verify_webhook(ENV.fetch("ALPR_WEBHOOK_SECRET"), request.headers, request.raw_post)
+rescue Alpr::WebhookVerificationError
+  head :bad_request
+  return
+end
+
+case event
+when Alpr::RecognitionCreatedWebhookEvent then puts event.plate, event.captured_at
+when Alpr::AlertTriggeredWebhookEvent then puts event.rule_name, event.recognition_id
+when Alpr::TestWebhookEvent then puts event.sent_at
+when Alpr::UnknownWebhookEvent then puts event.event_name # um evento que esta versão ainda não conhece: event.body é o JSON
+end
+```
+
+`Alpr.verify_webhook` confere a assinatura e interpreta o corpo; `Alpr.verify_webhook_signature` só confere a assinatura. Um segredo vazio levanta `ArgumentError` (erro de configuração, não de assinatura); uma assinatura que não confere levanta `Alpr::WebhookVerificationError`; um corpo assinado que não é um evento (não é um objeto, ou não tem `event` em texto) levanta `Alpr::WebhookParseError`.
+
+O evento é tipado e traz os campos da carga direto, sem `data` nem `type`: `event_name`, `id`, `tenant_id`, `plate`… Um evento de nome desconhecido é um `Alpr::UnknownWebhookEvent` (com `event`, `id` e o corpo todo em `body`), não um erro.
+
+**Deduplique as entregas pelo cabeçalho `X-Alprsh-Delivery-Id`.** O `id` do corpo é o da leitura ou do alerta, não o da entrega.
+
+Versão do SDK: 0.1.1 · contrato da API: 1.0.0

data/lib/alpr/client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+require "ipaddr"
+require "json"
+require "net/http"
+require "uri"
+
+module Alpr
+  # The standard library's HTTP, so the SDK depends on nothing. A transport is
+  # anything that answers +call(method, url, headers, body, timeout)+ with
+  # +[status, headers in lower case, body]+. Redirects are never followed: the
+  # API key must not travel, and a 3xx is an Alpr::Error.
+  class NetHTTPTransport
+    def call(method, url, headers, body, timeout)
+      uri = URI(url)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                          open_timeout: timeout, read_timeout: timeout, write_timeout: timeout) do |http|
+        response = http.send_request(method, uri.request_uri, body, headers)
+        [response.code.to_i, response.each_header.to_h, response.body.to_s]
+      end
+    end
+  end
+
+  # Alpr.sh's API with one workspace's API key.
+  #
+  # The key (+alpr_live_…+) says the workspace and the scopes the calls may use.
+  #
+  #   alpr = Alpr::Client.new(ENV.fetch("ALPR_API_KEY"))
+  #   result = alpr.photos.recognize({ image: File.binread("photo.jpg") })
+  #   alpr.recognitions.list_iter { |reading| puts reading.plate }
+  class Client
+    # @return [CamerasService]
+    attr_reader :cameras
+    # @return [PhotosService]
+    attr_reader :photos
+    # @return [RecognitionsService]
+    attr_reader :recognitions
+
+    # 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
+      @cameras = CamerasService.new(self)
+      @photos = PhotosService.new(self)
+      @recognitions = RecognitionsService.new(self)
+    end
+
+    # Calls the API and answers the JSON it sent, parsed (nil for a 204); a
+    # refusal raises Alpr::Error. +form+ is the multipart body of a call that
+    # sends a photo, +api_key+ another key for this call.
+    def request(method, path, query: nil, form: nil, api_key: nil)
+      url = @base_url + path
+      values = (query || {}).reject { |_, value| value.nil? || value == "" }
+      url += "?#{URI.encode_www_form(values)}" unless values.empty?
+      headers = {
+        "Authorization" => "Bearer #{api_key.nil? || api_key.empty? ? @api_key : api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "alpr-ruby/#{VERSION}"
+      }
+      data = nil
+      unless form.nil?
+        data = form.body
+        headers["Content-Type"] = form.content_type
+      end
+      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 || raw.to_s.empty?
+
+      JSON.parse(raw.to_s.dup.force_encoding(Encoding::UTF_8))
+    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, "alpr: 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/alpr/error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Alpr
+  # A request the API refused.
+  #
+  # +code+ is the API's: invalid_api_key, insufficient_scope,
+  # insufficient_credits, missing image, invalid_image, invalid_option,
+  # image_too_large, no_plate, not_found, image_unavailable, rate_limited,
+  # engine_unavailable or storage_unavailable. +message+ is the API's
+  # explanation, +fields+ says, when the API names them, what is wrong with
+  # each field (usually empty), and +retry_after+ is how many seconds to wait
+  # on a 429.
+  class Error < StandardError
+    attr_reader :status, :code, :message, :fields, :retry_after
+
+    def initialize(status, code, message = "", fields = {}, retry_after = nil)
+      @status = status
+      @code = code
+      @message = message
+      @fields = fields
+      @retry_after = retry_after
+      super(message.empty? ? "alpr: #{status} #{code}" : "alpr: #{status} #{code}: #{message}")
+    end
+
+    # What Ruby prints for an error nobody rescued: the status and code too.
+    def detailed_message(highlight: false, **)
+      highlight ? "\e[1m#{self} (#{self.class.name})\e[m" : "#{self} (#{self.class.name})"
+    end
+
+    # The error a response with a status of 300 or more is.
+    def self.from_response(status, headers, body)
+      data = begin
+        loaded = JSON.parse(body.to_s.empty? ? "{}" : body.to_s.dup.force_encoding(Encoding::UTF_8))
+        loaded.is_a?(Hash) ? loaded : {}
+      rescue JSON::ParserError
+        {} # A refusal without a JSON body is still a refusal.
+      end
+      retry_after = headers["retry-after"].to_s
+      fields = data["fields"].is_a?(Hash) ? data["fields"] : {}
+      new(status, data["error"].to_s, data["message"].to_s, fields,
+          retry_after.match?(/\A[0-9]+\z/) ? retry_after.to_i : nil)
+    end
+  end
+end

data/lib/alpr/model.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Alpr
+  # What every resource and every body shares: its members, read as a hash and
+  # compared by value.
+  module Value
+    def to_h
+      self.class::MEMBERS.to_h { |name| [name, instance_variable_get(:"@#{name}")] }
+    end
+
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_h.map { |name, value| "#{name}=#{value.inspect}" }.join(", ")}>"
+    end
+    alias to_s inspect
+  end
+
+  # A resource the API answers, built from its JSON and frozen.
+  class Model
+    include Value
+  end
+
+  # The body of a write: built with keyword arguments, sent with the API's
+  # names, an optional field left unset left out.
+  class Params
+    include Value
+
+    # The params as they are, or built from a hash of their names.
+    def self.coerce(params)
+      case params
+      when self then params
+      when Hash then new(**params.transform_keys(&:to_sym))
+      else raise ArgumentError, "alpr: #{name} is built from a Hash, not #{params.class}"
+      end
+    end
+  end
+end