velix-sdk 0.1.0.pre.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40da25499d3ae666cd66289c246ee35de7f530b7531cf7a6c4573951dd44b10a
+  data.tar.gz: 15670d812a8dc1a27e8eaf53aa34619d93aee1b72c7f0a0936ef25550beb9ce3
+SHA512:
+  metadata.gz: 97aa391c0f9fbf9f8d46af5503c48f8fc0571b73deea523f63056f7dec0fe3111a989dcdff421b9a5b5841ef2f8f72292ee3735a3d588041106ffb716c39223d
+  data.tar.gz: d3006602956f427a885e59e378e4a93885ce4f3147ea15ac99267797182f256769260bc2e4c25bb718e5adb9298904a6fe497c76a7109a95207b17849f0186d3

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+Todas as mudanças notáveis deste projeto são documentadas neste arquivo.
+
+O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/)
+e este projeto adere a [Semantic Versioning](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+### Fixed
+
+- Retry deixou de reenviar cegamente qualquer `5xx`. Requisições não
+  idempotentes (`POST`, `PATCH`, `PUT`, `DELETE`) só são retentadas quando o
+  status é `429` ou `503` (`RETRYABLE_STATUSES`), casos em que o servidor
+  garante que a requisição original não foi processada. Isso elimina o risco
+  de duplicar `checkin`/`enroll` em erro `500`.
+- Erros de parse do corpo da resposta deixaram de ser engolidos
+  silenciosamente (`JSON.parse rescue {}`). Agora um corpo malformado
+  propaga um `Velix::VelixError` estruturado em vez de virar `{}` e esconder
+  a mensagem de erro original.
+
+## [0.1.0.pre.alpha1] - pré-release
+
+### Added
+
+- Cliente HTTP baseado em `Net::HTTP` (stdlib, zero dependências de runtime).
+- Autenticação via header `x-api-key`.
+- Módulos `checkin`, `persons`, `events`, `tenants`.
+- Retry com backoff exponencial para status retentáveis.

data/README.md

@@ -0,0 +1,170 @@
+# velix-sdk — Ruby SDK ![version](https://img.shields.io/badge/version-0.1.0--alpha1-orange)
+
+> ⚠️ **Alpha / pre-release.** This SDK targets the real API-key-protected surface of the
+> VELIX backend (`/v1/api/*`, see `public-api.yaml` task #593). Only six endpoints exist
+> today; everything else (Velix Time included) is intentionally not implemented. Do not
+> use in production integrations yet.
+
+Official Ruby SDK for the VELIX Biometrics platform — facial access control B2B SaaS.
+
+## Requirements
+
+- Ruby 3.1+
+- Zero runtime dependencies (uses stdlib `net/http`)
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "velix-sdk", "~> 0.1.0.pre"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install velix-sdk
+```
+
+## Quick Start
+
+```ruby
+require "velix"
+
+client = Velix::Client.new(
+  api_url: ENV["VELIX_API_URL"],
+  api_key: ENV["VELIX_API_KEY"]
+)
+
+result = client.checkin.identify(image_base64: frame_base64)
+puts result.matched ? "GRANTED" : "DENIED"
+```
+
+Auth is sent as `x-api-key: vlx_<hex>` on every request (the API also accepts
+`Authorization: Bearer vlx_<hex>` as an alternative, but the SDK always uses the
+`x-api-key` header).
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VELIX_API_URL` | Yes | API base URL (`https://api.velixbiometrics.com`) |
+| `VELIX_API_KEY` | Yes | Integrator API key (`vlx_...`) |
+
+## Modules
+
+The API-key surface has exactly six real endpoints, one per method below. There is no
+list/update/delete for persons, events, or tenants under `/v1/api/*` — do not expect
+those methods.
+
+| Module | Method | Endpoint | Scope |
+|--------|--------|----------|-------|
+| `client.onboarding` | `create()` | `POST /v1/api/onboarding` | `onboarding:write` |
+| `client.checkin` | `identify()` | `POST /v1/api/checkin/identify` | `checkin:write` |
+| `client.lgpd` | `create_deletion_request()` | `POST /v1/api/deletion-request` | `lgpd:write` |
+| `client.me` | `find()` | `GET /v1/api/me/{personId}` | `me:read` |
+| `client.events` | `create_guest()` | `POST /v1/api/events/{id}/guests` | `events:write` |
+| `client.events` | `get_guest()` | `GET /v1/api/events/{id}/guests/{guestId}` | `events:read` |
+
+`client.time` exists only as a stub that raises `NotImplementedError` — Velix Time has
+no endpoint under `/v1/api/*` yet (see spec note "Velix Time — COBERTURA PARCIAL").
+
+## Onboarding Module
+
+```ruby
+result = client.onboarding.create(
+  name: "João Silva",
+  frames: [frame1_base64, frame2_base64, frame3_base64], # min 1, tenant-configured minimum
+  email: "joao@company.com",
+  external_id: "EMP-001" # upserts by external key when provided
+)
+# result.person_id         => "uuid"
+# result.identity_id       => "uuid"
+# result.enrolled          => true
+# result.frames_processed  => 3
+# result.frames_results    => [...]
+```
+
+## Checkin Module
+
+```ruby
+result = client.checkin.identify(
+  image_base64: frame_base64,
+  top_k: 3,
+  liveness: {
+    token: challenge_token, # from GET /v1/public/checkin/{tenantSlug}/liveness/challenge
+    samples: [{ action: "center", image_base64: sample_base64 }]
+  }
+)
+# result.matched       => true
+# result.person_id     => "uuid"
+# result.quality_score => 0.92
+```
+
+Liveness score is never returned by the API — only `matched`/`quality_score` are
+exposed, by design.
+
+## LGPD Module
+
+```ruby
+result = client.lgpd.create_deletion_request(person_id: "uuid")
+# result.protocol_number => "PROTO-123"
+```
+
+## Me Module
+
+```ruby
+person = client.me.find("uuid")
+# person.id, person.name, person.email, person.phone, person.photo_url, person.created_at
+```
+
+## Events Module
+
+```ruby
+guest = client.events.create_guest("event-uuid", name: "Ana", email: "ana@empresa.com")
+# guest.id, guest.event_id, guest.status, guest.category_id
+
+guest = client.events.get_guest("event-uuid", "guest-uuid")
+```
+
+## Error Handling
+
+```ruby
+begin
+  result = client.checkin.identify(image_base64: frame)
+rescue Velix::AuthError
+  puts "Invalid API key"
+rescue Velix::BiometricError => e
+  puts "Face not recognized: #{e.message}"
+rescue Velix::RateLimitError => e
+  puts "Rate limit: #{e.message}"
+rescue Velix::VelixError => e
+  puts "HTTP #{e.status}: #{e.message}"
+end
+```
+
+## Running Tests
+
+```bash
+bundle exec rspec                        # all tests
+bundle exec rspec spec/checkin_spec.rb   # single file
+bundle exec rspec --format documentation # verbose
+```
+
+## Local Development
+
+```bash
+git clone <repo>
+bundle install
+bundle exec rspec
+```
+
+## Get an API Key
+
+Access the dashboard at **velixbiometrics.com** → Settings → API Keys → New Key.

data/lib/velix/client.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "config"
+require_relative "error"
+require_relative "retry"
+require_relative "modules/onboarding"
+require_relative "modules/checkin"
+require_relative "modules/lgpd"
+require_relative "modules/me"
+require_relative "modules/events"
+require_relative "modules/time"
+
+module Velix
+  class Client
+    include Velix::Retry
+
+    USER_AGENT = "velix-ruby-sdk/0.1.0.pre.alpha1"
+
+    def initialize(api_url:, api_key:, timeout: 30, max_retries: 3)
+      @config = Config.new(api_url: api_url, api_key: api_key,
+                           timeout: timeout, max_retries: max_retries)
+    end
+
+    def onboarding = @onboarding ||= Modules::Onboarding.new(self)
+    def checkin    = @checkin    ||= Modules::Checkin.new(self)
+    def lgpd       = @lgpd       ||= Modules::Lgpd.new(self)
+    def me         = @me         ||= Modules::Me.new(self)
+    def events     = @events     ||= Modules::Events.new(self)
+
+    # Velix Time has no endpoint under /v1/api/* yet — see modules/time.rb.
+    def time = @time ||= Modules::Time.new(self)
+
+    def get(path, params = {})
+      uri = build_uri(path, params)
+      request(Net::HTTP::Get.new(uri))
+    end
+
+    def post(path, body = {})
+      uri = build_uri(path)
+      req = Net::HTTP::Post.new(uri)
+      req.body = body.to_json
+      request(req)
+    end
+
+    def put(path, body = {})
+      uri = build_uri(path)
+      req = Net::HTTP::Put.new(uri)
+      req.body = body.to_json
+      request(req)
+    end
+
+    def patch(path, body = {})
+      uri = build_uri(path)
+      req = Net::HTTP::Patch.new(uri)
+      req.body = body.to_json
+      request(req)
+    end
+
+    def delete(path)
+      uri = build_uri(path)
+      request(Net::HTTP::Delete.new(uri))
+    end
+
+    private
+
+    def build_uri(path, params = {})
+      uri = URI.join(@config.api_url, path)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def request(req)
+      req["x-api-key"] = @config.api_key
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = USER_AGENT
+
+      with_retry(max_retries: @config.max_retries, method: req.method) do
+        uri = req.uri
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @config.timeout
+        http.read_timeout = @config.timeout
+
+        response = http.request(req)
+        handle_response(response)
+      end
+    end
+
+    def handle_response(response)
+      body = parse_body(response.body)
+      # Envelope de erro real: {"success":false,"error":{"code":"...","message":"..."}}.
+      # body["message"] no nível raiz não existe — ficava sempre no fallback
+      # genérico, mascarando a mensagem real da API.
+      message = body.is_a?(Hash) ? body.dig("error", "message") || body["message"] : nil
+
+      case response.code.to_i
+      when 200, 201, 204
+        body.is_a?(Hash) && body.key?("data") ? body["data"] : body
+      when 401, 403
+        raise AuthError.new(message || "Unauthorized", status: response.code.to_i)
+      when 404
+        raise NotFoundError.new(message || "Not found", status: 404)
+      when 422
+        raise BiometricError.new(message || "Unprocessable", status: 422)
+      when 429
+        raise RateLimitError.new(message || "Rate limit exceeded", status: 429)
+      when 500..599
+        raise ServerError.new(message || "Server error", status: response.code.to_i)
+      else
+        raise VelixError.new(message || "Unexpected error", status: response.code.to_i)
+      end
+    end
+
+    # Parse errors are never swallowed: a malformed body on an error
+    # response must still surface as a structured VelixError instead of
+    # silently becoming an empty hash (which hides the real failure and
+    # nils out the error message).
+    def parse_body(raw)
+      return {} if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise VelixError.new("Failed to parse response body: #{e.message}", status: nil, code: "invalid_json")
+    end
+  end
+end

data/lib/velix/config.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Velix
+  Config = Data.define(:api_url, :api_key, :timeout, :max_retries) do
+    def initialize(api_url:, api_key:, timeout: 30, max_retries: 3)
+      super
+    end
+  end
+end

data/lib/velix/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Velix
+  class VelixError < StandardError
+    attr_reader :status, :code
+
+    def initialize(message, status: nil, code: nil)
+      super(message)
+      @status = status
+      @code = code
+    end
+  end
+
+  class AuthError < VelixError; end
+  class NotFoundError < VelixError; end
+  class RateLimitError < VelixError; end
+  class BiometricError < VelixError; end
+  class ServerError < VelixError; end
+end

data/lib/velix/modules/checkin.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Velix
+  module Modules
+    # POST /v1/api/checkin/identify — scope checkin:write
+    #
+    # Liveness score is never returned by the API by design (security rule) —
+    # this endpoint's response only ever reports `matched`, never a raw
+    # liveness/confidence score.
+    class Checkin
+      Result = Data.define(:matched, :person_id, :quality_score, :message)
+
+      def initialize(client)
+        @client = client
+      end
+
+      # image_base64: main frame, required
+      # images: optional array of extra base64 frames
+      # top_k: optional integer 1..10
+      # liveness: optional { token:, samples: [{ action:, image_base64: }] }
+      # location: optional { latitude:, longitude:, accuracy: }
+      def identify(image_base64:, images: nil, top_k: nil, liveness: nil, location: nil)
+        body = { imageBase64: image_base64 }
+        body[:images] = images if images
+        body[:topK] = top_k if top_k
+        body[:liveness] = serialize_liveness(liveness) if liveness
+        body[:location] = location if location
+
+        resp = @client.post("/v1/api/checkin/identify", body)
+
+        Result.new(
+          matched: resp["matched"],
+          person_id: resp["person_id"],
+          quality_score: resp["quality_score"],
+          message: resp["message"]
+        )
+      end
+
+      private
+
+      # Maps idiomatic Ruby keys (token:, samples: [{ action:, image_base64: }])
+      # onto the wire's literal camelCase field names (token, samples[].action,
+      # samples[].imageBase64) as defined by LivenessBlock/LivenessSample in
+      # the spec.
+      def serialize_liveness(liveness)
+        {
+          token: liveness[:token],
+          samples: Array(liveness[:samples]).map do |sample|
+            { action: sample[:action], imageBase64: sample[:image_base64] || sample[:imageBase64] }
+          end
+        }
+      end
+    end
+  end
+end

data/lib/velix/modules/events.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Velix
+  module Modules
+    # /v1/api/events/{id}/guests — Velix Events guest endpoints.
+    #
+    # Only two operations exist in the real API: creating a guest
+    # (events:write) and reading one back (events:read). There is no
+    # list/find/create/update/delete-event or update-config endpoint under
+    # the API-key surface — do not add methods for those without a
+    # corresponding spec entry.
+    class Events
+      Guest = Data.define(:id, :event_id, :name, :email, :status, :category_id)
+
+      def initialize(client)
+        @client = client
+      end
+
+      # cpf, phone, birth_date, category_id, companion_of are optional.
+      def create_guest(event_id, name:, email:, cpf: nil, phone: nil, birth_date: nil,
+                        category_id: nil, companion_of: nil)
+        body = { name: name, email: email }
+        body[:cpf] = cpf if cpf
+        body[:phone] = phone if phone
+        body[:birthDate] = birth_date if birth_date
+        body[:categoryId] = category_id if category_id
+        body[:companionOf] = companion_of if companion_of
+
+        resp = @client.post("/v1/api/events/#{event_id}/guests", body)
+        build_guest(resp)
+      end
+
+      def get_guest(event_id, guest_id)
+        resp = @client.get("/v1/api/events/#{event_id}/guests/#{guest_id}")
+        build_guest(resp)
+      end
+
+      private
+
+      def build_guest(resp)
+        Guest.new(
+          id: resp["id"],
+          event_id: resp["eventId"],
+          name: resp["name"],
+          email: resp["email"],
+          status: resp["status"],
+          category_id: resp["categoryId"]
+        )
+      end
+    end
+  end
+end

data/lib/velix/modules/lgpd.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Velix
+  module Modules
+    # POST /v1/api/deletion-request — scope lgpd:write
+    class Lgpd
+      Result = Data.define(:protocol_number, :message)
+
+      def initialize(client)
+        @client = client
+      end
+
+      def create_deletion_request(person_id:)
+        resp = @client.post("/v1/api/deletion-request", { person_id: person_id })
+
+        Result.new(protocol_number: resp["protocol_number"], message: resp["message"])
+      end
+    end
+  end
+end

data/lib/velix/modules/me.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Velix
+  module Modules
+    # GET /v1/api/me/{personId} — scope me:read
+    class Me
+      Result = Data.define(:id, :name, :email, :phone, :photo_url, :created_at)
+
+      def initialize(client)
+        @client = client
+      end
+
+      def find(person_id)
+        resp = @client.get("/v1/api/me/#{person_id}")
+
+        Result.new(
+          id: resp["id"],
+          name: resp["name"],
+          email: resp["email"],
+          phone: resp["phone"],
+          photo_url: resp["photo_url"],
+          created_at: resp["created_at"]
+        )
+      end
+    end
+  end
+end

data/lib/velix/modules/onboarding.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Velix
+  module Modules
+    # POST /v1/api/onboarding — scope onboarding:write
+    class Onboarding
+      Result = Data.define(:person_id, :identity_id, :enrolled, :frames_processed,
+                            :frames_results, :embedding_id, :message)
+
+      def initialize(client)
+        @client = client
+      end
+
+      # frames: array of base64 jpeg strings (no data URI prefix), min 1
+      def create(name:, frames:, email: nil, phone: nil, document: nil, document_type: nil,
+                 external_id: nil, metadata: nil, role: nil, access_groups: nil)
+        body = { name: name, frames: frames }
+        body[:email] = email if email
+        body[:phone] = phone if phone
+        body[:document] = document if document
+        body[:document_type] = document_type if document_type
+        body[:external_id] = external_id if external_id
+        body[:metadata] = metadata if metadata
+        body[:role] = role if role
+        body[:access_groups] = access_groups if access_groups
+
+        resp = @client.post("/v1/api/onboarding", body)
+
+        Result.new(
+          person_id: resp["person_id"],
+          identity_id: resp["identity_id"],
+          enrolled: resp["enrolled"],
+          frames_processed: resp["frames_processed"],
+          frames_results: resp["frames_results"],
+          embedding_id: resp["embedding_id"],
+          message: resp["message"]
+        )
+      end
+    end
+  end
+end

data/lib/velix/modules/time.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Velix
+  module Modules
+    # Velix Time (ponto/punch) has NO endpoint exposed under the API-key
+    # surface (`/v1/api/*`) as of the current public-api.yaml spec. The
+    # `time:read`/`time:write` scopes exist on ApplicationApiKey but no
+    # controller is mounted for them yet (see spec note "Velix Time —
+    # COBERTURA PARCIAL"). Do not implement calls against guessed endpoints.
+    #
+    # This stub exists only so that any accidental `client.time` call fails
+    # loudly instead of silently hitting a nonexistent/wrong endpoint.
+    class Time
+      def initialize(client)
+        @client = client
+      end
+
+      def method_missing(name, *)
+        raise NotImplementedError,
+              "Velix::Modules::Time##{name} is not implemented — Velix Time has no endpoint " \
+              "under /v1/api/* yet (see public-api.yaml, task #616 follow-up)."
+      end
+
+      def respond_to_missing?(*)
+        true
+      end
+    end
+  end
+end

data/lib/velix/retry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Velix
+  module Retry
+    RETRYABLE_STATUSES = [429, 503].freeze
+    IDEMPOTENT_METHODS = %w[GET].freeze
+
+    # Retries are only safe for:
+    # - idempotent HTTP methods (GET), regardless of status
+    # - RETRYABLE_STATUSES (429/503), where the server guarantees the
+    #   request was not processed, even for non-idempotent methods (POST)
+    #
+    # Any other 5xx on a non-idempotent method (POST/PATCH/PUT/DELETE) is
+    # raised immediately — retrying could duplicate a checkin/enroll.
+    def with_retry(max_retries:, method: "GET")
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue RateLimitError, ServerError => e
+        raise unless retryable?(method, e.status)
+        raise if attempts >= max_retries
+
+        wait = (2**(attempts - 1)) + rand
+        sleep(wait)
+        retry
+      end
+    end
+
+    private
+
+    def retryable?(method, status)
+      IDEMPOTENT_METHODS.include?(method.to_s.upcase) || RETRYABLE_STATUSES.include?(status)
+    end
+  end
+end

data/lib/velix.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "velix/client"
+
+module Velix
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: velix-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.alpha1
+platform: ruby
+authors:
+- Velix Biometrics
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-03 00:00:00.000000000 Z
+dependencies: []
+description: Integre controle de acesso biométrico VELIX em aplicações Ruby.
+email:
+- dev@velixbiometrics.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/velix.rb
+- lib/velix/client.rb
+- lib/velix/config.rb
+- lib/velix/error.rb
+- lib/velix/modules/checkin.rb
+- lib/velix/modules/events.rb
+- lib/velix/modules/lgpd.rb
+- lib/velix/modules/me.rb
+- lib/velix/modules/onboarding.rb
+- lib/velix/modules/time.rb
+- lib/velix/retry.rb
+homepage: https://velixbiometrics.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://velixbiometrics.com
+  source_code_uri: https://github.com/VELIX-Biometrics/sdk-velix-ruby
+  changelog_uri: https://github.com/VELIX-Biometrics/sdk-velix-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: SDK oficial do VELIX para Ruby
+test_files: []