alpr-sdk 0.1.1

data/lib/alpr/page.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Alpr
+  # One page of a list: its items, and the cursor of the next page.
+  class Page
+    # @return [Array] the items of the page
+    attr_reader :items
+    # @return [String, nil] the cursor to ask the next page with; nil on the last page
+    attr_reader :next_cursor
+
+    def initialize(items:, next_cursor:)
+      @items = items.freeze
+      @next_cursor = next_cursor.nil? || next_cursor.to_s.empty? ? nil : next_cursor.to_s
+      freeze
+    end
+
+    # Builds a page from the API's hash ({"data": [...], "next": cursor}), each
+    # item through the block.
+    def self.from_hash(data, next_key = "next", &item)
+      new(items: (data["data"] || []).map(&item), next_cursor: data[next_key])
+    end
+
+    # Walks pages from the cursor +first+ (the newest page when nil) until the
+    # last one, yielding every item and ending at the first error; +fetch+
+    # answers the Page of the cursor it is given. A cursor that does not move
+    # would ask for the same page forever, so it ends the walk too.
+    def self.iterate(first, &fetch)
+      Enumerator.new do |yielder|
+        cursor = first.nil? || first.to_s.empty? ? nil : first.to_s
+        loop do
+          result = fetch.call(cursor)
+          result.items.each { |item| yielder << item }
+          break if result.next_cursor.nil? || result.next_cursor == cursor
+
+          cursor = result.next_cursor
+        end
+      end
+    end
+  end
+end

data/lib/alpr/params.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+module Alpr
+  # The body of photos:detect.
+  class PhotosDetectParams < Params
+    MEMBERS = %i[image image_mode lpr_confidence min_ocr_confidence].freeze
+
+    # A foto, JPEG ou PNG.
+    # @return [String (the bytes)]
+    attr_reader :image
+
+    # Só NONE é aceito.
+    # @return [String ("NONE"), nil]
+    attr_reader :image_mode
+
+    # Piso de confiança do detector de placas.
+    # @return [Float, nil]
+    attr_reader :lpr_confidence
+
+    # Piso de confiança da leitura dos caracteres.
+    # @return [Float, nil]
+    attr_reader :min_ocr_confidence
+
+    def initialize(image:, image_mode: nil, lpr_confidence: nil, min_ocr_confidence: nil)
+      @image = image
+      @image_mode = image_mode
+      @lpr_confidence = lpr_confidence
+      @min_ocr_confidence = min_ocr_confidence
+      freeze
+    end
+
+    # The multipart/form-data body as the API reads it: the photo as a file,
+    # the rest as text fields, an optional one left unset left out.
+    def to_form
+      form = Form.new
+      form.file("image", @image)
+      form.text("image_mode", @image_mode) unless @image_mode.nil?
+      form.text("lpr_confidence", @lpr_confidence) unless @lpr_confidence.nil?
+      form.text("min_ocr_confidence", @min_ocr_confidence) unless @min_ocr_confidence.nil?
+      form
+    end
+  end
+
+  # The body of photos:ocr.
+  class PhotosOCRParams < Params
+    MEMBERS = %i[image].freeze
+
+    # A imagem da placa já recortada, JPEG ou PNG.
+    # @return [String (the bytes)]
+    attr_reader :image
+
+    def initialize(image:)
+      @image = image
+      freeze
+    end
+
+    # The multipart/form-data body as the API reads it: the photo as a file,
+    # the rest as text fields, an optional one left unset left out.
+    def to_form
+      form = Form.new
+      form.file("image", @image)
+      form
+    end
+  end
+
+  # The body of photos:recognize.
+  class PhotosRecognizeParams < Params
+    MEMBERS = %i[image image_mode lpr_confidence min_ocr_confidence].freeze
+
+    # A foto, JPEG ou PNG.
+    # @return [String (the bytes)]
+    attr_reader :image
+
+    # Só NONE é aceito.
+    # @return [String ("NONE"), nil]
+    attr_reader :image_mode
+
+    # Piso de confiança do detector de placas.
+    # @return [Float, nil]
+    attr_reader :lpr_confidence
+
+    # Piso de confiança da leitura dos caracteres.
+    # @return [Float, nil]
+    attr_reader :min_ocr_confidence
+
+    def initialize(image:, image_mode: nil, lpr_confidence: nil, min_ocr_confidence: nil)
+      @image = image
+      @image_mode = image_mode
+      @lpr_confidence = lpr_confidence
+      @min_ocr_confidence = min_ocr_confidence
+      freeze
+    end
+
+    # The multipart/form-data body as the API reads it: the photo as a file,
+    # the rest as text fields, an optional one left unset left out.
+    def to_form
+      form = Form.new
+      form.file("image", @image)
+      form.text("image_mode", @image_mode) unless @image_mode.nil?
+      form.text("lpr_confidence", @lpr_confidence) unless @lpr_confidence.nil?
+      form.text("min_ocr_confidence", @min_ocr_confidence) unless @min_ocr_confidence.nil?
+      form
+    end
+  end
+end

data/lib/alpr/services.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+module Alpr
+  # The API's cameras.
+  class CamerasService
+    def initialize(client)
+      @client = client
+    end
+
+    # Listar as câmeras.
+    #
+    # @return [Array<Camera>]
+    def list(api_key: nil)
+      data = @client.request("GET", "/api/v1/cameras", api_key: api_key)
+      (data["data"] || []).map { |item| Camera.from_hash(item) }
+    end
+  end
+
+  # The API's photos.
+  class PhotosService
+    def initialize(client)
+      @client = client
+    end
+
+    # Localizar as placas de uma foto.
+    #
+    # @param params [PhotosDetectParams, Hash]
+    # @return [PhotoDetection]
+    def detect(params, api_key: nil)
+      data = @client.request("POST", "/api/v1/detect", form: PhotosDetectParams.coerce(params).to_form, api_key: api_key)
+      PhotoDetection.from_hash(data)
+    end
+
+    # Ler uma placa já recortada.
+    #
+    # @param params [PhotosOCRParams, Hash]
+    # @return [PlateReading]
+    def ocr(params, api_key: nil)
+      data = @client.request("POST", "/api/v1/ocr", form: PhotosOCRParams.coerce(params).to_form, api_key: api_key)
+      PlateReading.from_hash(data)
+    end
+
+    # Ler as placas de uma foto.
+    #
+    # @param params [PhotosRecognizeParams, Hash]
+    # @return [PhotoRecognition]
+    def recognize(params, api_key: nil)
+      data = @client.request("POST", "/api/v1/recognize", form: PhotosRecognizeParams.coerce(params).to_form, api_key: api_key)
+      PhotoRecognition.from_hash(data)
+    end
+  end
+
+  # The API's recognitions.
+  class RecognitionsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Imagem de uma leitura.
+    #
+    # @return [DetectionImageLink]
+    def image(id, api_key: nil)
+      data = @client.request("GET", "/api/v1/detections/#{Alpr.segment(id)}/image", api_key: api_key)
+      DetectionImageLink.from_hash(data)
+    end
+
+    # Listar as leituras. One page; +list_iter+ walks every page. +before+ is the
+    # cursor the previous page answered as +next_cursor+; nil asks for the newest page.
+    #
+    # @return [Page<Recognition>]
+    def list(before: nil, plate: nil, camera: nil, source: nil, api_key: nil)
+      query = { "before" => before, "plate" => plate, "camera" => camera, "source" => source }
+      data = @client.request("GET", "/api/v1/recognitions", query: query, api_key: api_key)
+      Page.from_hash(data, "next") { |item| Recognition.from_hash(item) }
+    end
+
+    # Walks every page of recognitions:list from the cursor +before+ (the newest when
+    # nil), item by item, until the last page; it ends at the first error.
+    #
+    # @return [Enumerator<Recognition>]
+    def list_iter(before: nil, plate: nil, camera: nil, source: nil, api_key: nil, &block)
+      items = Page.iterate(before) do |at|
+        list(before: at, plate: plate, camera: camera, source: source, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+end

data/lib/alpr/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+module Alpr
+  # This SDK's version.
+  VERSION = "0.1.1"
+
+  # The contract this SDK was generated from.
+  API_VERSION = "1.0.0"
+
+  # Alpr.sh's API. The workspace is the API key's: alpr_live_….
+  DEFAULT_BASE_URL = "https://alpr.sh"
+end

data/lib/alpr/webhooks.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+require "json"
+require "openssl"
+
+# Verifying the webhooks Alpr.sh sends.
+module Alpr
+  # How far from now a webhook's timestamp may be, in seconds.
+  WEBHOOK_TOLERANCE = 300
+
+  # How many signatures a request may list: one for the secret in use and one
+  # for each secret still signing during a rotation.
+  MAX_WEBHOOK_SIGNATURES = 6
+
+  # A request Alpr.sh did not sign, or signed too long ago.
+  class WebhookVerificationError < StandardError
+    def initialize(message = "alpr: webhook signature does not verify")
+      super
+    end
+  end
+
+  # A verified body that is not an event, or not the event its name says.
+  class WebhookParseError < StandardError; end
+
+  # What every webhook event answers. +event_name+ is the event's name:
+  # recognition.created.
+  module WebhookEvent
+    # @return [String]
+    def event_name
+      @event
+    end
+  end
+
+  # The payload of
+  # * alert.triggered
+  class AlertTriggeredWebhookEvent < WebhookAlertTriggered
+    include WebhookEvent
+
+    TYPES = %w[alert.triggered].freeze
+  end
+
+  # The payload of
+  # * recognition.created
+  class RecognitionCreatedWebhookEvent < WebhookRecognitionCreated
+    include WebhookEvent
+
+    TYPES = %w[recognition.created].freeze
+  end
+
+  # The payload of
+  # * webhook.test
+  class TestWebhookEvent < WebhookTest
+    include WebhookEvent
+
+    TYPES = %w[webhook.test].freeze
+  end
+
+  # An event of a name this SDK does not know yet; its body is kept as it was
+  # sent.
+  class UnknownWebhookEvent < Model
+    include WebhookEvent
+
+    MEMBERS = %i[event id body].freeze
+
+    # @return [String] the event's name
+    attr_reader :event
+    # @return [String] the id the body carries, or an empty string
+    attr_reader :id
+    # @return [Hash] the whole body, decoded
+    attr_reader :body
+
+    def initialize(event:, id:, body:)
+      @event = event
+      @id = id
+      @body = body
+      freeze
+    end
+  end
+
+  # Checks a webhook Alpr.sh sent and answers its event.
+  #
+  # Alpr.sh signs the headers X-Alprsh-Timestamp and X-Alprsh-Delivery-Id and
+  # the body: X-Alprsh-Signature carries "sha256=" and the hex HMAC-SHA256 of
+  # "{timestamp}.{delivery-id}.{body}" under the endpoint's secret (the whole
+  # whsec_… text, as it is), and more than one signature while a secret is
+  # rotated -- one matching is enough. Pass the body exactly as it arrived,
+  # before parsing it, and deduplicate by the X-Alprsh-Delivery-Id header.
+  # +headers+ is a hash of the request's headers, in any case (a value may be a
+  # list, one a header line), or a Rack env. +now+ is for tests.
+  #
+  # @return [AlertTriggeredWebhookEvent, RecognitionCreatedWebhookEvent, TestWebhookEvent, UnknownWebhookEvent]
+  # @raise [WebhookVerificationError] the signature does not verify
+  # @raise [WebhookParseError] the body is not an event
+  # @raise [ArgumentError] the secret is empty
+  def self.verify_webhook(secret, headers, body, now: Time.now)
+    verify_webhook_signature(secret, headers, body, now: now)
+    webhook_event(body.to_s.b.force_encoding(Encoding::UTF_8))
+  end
+
+  # Checks a webhook's signature as verify_webhook does, without reading its
+  # body.
+  #
+  # @return [nil]
+  # @raise [WebhookVerificationError] the signature does not verify
+  # @raise [ArgumentError] the secret is empty
+  def self.verify_webhook_signature(secret, headers, body, now: Time.now)
+    raise ArgumentError, "alpr: the webhook secret is empty" if secret.to_s.empty?
+
+    delivery_id = webhook_header(headers, "x-alprsh-delivery-id").first.to_s
+    stamp = webhook_header(headers, "x-alprsh-timestamp").first.to_s
+    # Only ASCII digits: the signer never sends a sign, a space or other digits.
+    raise WebhookVerificationError if delivery_id.empty? || !stamp.match?(/\A[0-9]+\z/)
+    raise WebhookVerificationError if (now.to_r - stamp.to_i).abs > WEBHOOK_TOLERANCE
+
+    listed = webhook_header(headers, "x-alprsh-signature").join(",").split(",", -1)
+    raise WebhookVerificationError if listed.empty? || listed.size > MAX_WEBHOOK_SIGNATURES
+
+    expected = OpenSSL::HMAC.digest("SHA256", secret.to_s.b, "#{stamp}.#{delivery_id}.".b + body.to_s.b)
+    matched = false
+    listed.each do |signature|
+      # One malformed signature refuses the request. Every listed signature is
+      # compared, in constant time.
+      encoded = signature.strip[/\Asha256=([0-9a-fA-F]{64})\z/, 1]
+      raise WebhookVerificationError if encoded.nil?
+
+      matched = true if OpenSSL.fixed_length_secure_compare([encoded].pack("H*"), expected)
+    end
+    raise WebhookVerificationError unless matched
+
+    nil
+  end
+
+  # A verified body as the event its name says.
+  def self.webhook_event(raw)
+    body = begin
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise WebhookParseError, "alpr: the webhook body is not an event: #{e.message}"
+    end
+    raise WebhookParseError, "alpr: the webhook body is not an event" unless body.is_a?(Hash) && body["event"].is_a?(String) && !body["event"].empty?
+
+    name = body["event"]
+    begin
+      case name
+      when *AlertTriggeredWebhookEvent::TYPES then AlertTriggeredWebhookEvent.from_hash(body)
+      when *RecognitionCreatedWebhookEvent::TYPES then RecognitionCreatedWebhookEvent.from_hash(body)
+      when *TestWebhookEvent::TYPES then TestWebhookEvent.from_hash(body)
+      else UnknownWebhookEvent.new(event: name, id: body["id"].is_a?(String) ? body["id"] : "", body: body)
+      end
+    rescue KeyError, TypeError, ArgumentError => e
+      raise WebhookParseError, "alpr: the webhook body is not a #{name} event: #{e.message}"
+    end
+  end
+  private_class_method :webhook_event
+
+  # The values of a header, looked up in any case; a Rack env's
+  # HTTP_X_ALPRSH_DELIVERY_ID names x-alprsh-delivery-id. A header sent as
+  # several lines has several values.
+  def self.webhook_header(headers, name)
+    values = []
+    headers.each do |key, value|
+      values.concat(Array(value).map(&:to_s)) if key.to_s.downcase.tr("_", "-").delete_prefix("http-") == name
+    end
+    values
+  end
+  private_class_method :webhook_header
+end

data/lib/alpr.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+# Alpr.sh's SDK for Ruby, generated from Alpr.sh's API contract.
+#
+#   alpr = Alpr::Client.new(ENV.fetch("ALPR_API_KEY"))
+#   result = alpr.photos.recognize({ image: File.binread("photo.jpg") })
+#   alpr.recognitions.list_iter(plate: "BRA2E19").each { |reading| puts reading.captured_at }
+module Alpr
+  # A path parameter, escaped.
+  def self.segment(value)
+    value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { |char| format("%%%02X", char.ord) }
+  end
+end
+
+require_relative "alpr/version"
+require_relative "alpr/error"
+require_relative "alpr/model"
+require_relative "alpr/multipart"
+require_relative "alpr/models"
+require_relative "alpr/params"
+require_relative "alpr/page"
+require_relative "alpr/services"
+require_relative "alpr/client"
+require_relative "alpr/webhooks"

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: alpr-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Alpr.sh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/alpr.rb
+- lib/alpr/client.rb
+- lib/alpr/error.rb
+- lib/alpr/model.rb
+- lib/alpr/models.rb
+- lib/alpr/multipart.rb
+- lib/alpr/page.rb
+- lib/alpr/params.rb
+- lib/alpr/services.rb
+- lib/alpr/version.rb
+- lib/alpr/webhooks.rb
+homepage: https://alpr.sh
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://alpr.sh
+  source_code_uri: https://github.com/alpr-sh/sdk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Alpr.sh''s SDK for Ruby: license-plate recognition from photos, readings,
+  cameras and webhooks.'
+test_files: []