vigilhq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b773ff979e7c20af37f68c5a9ce3f625e58a397c80f186c8931e583be5fd9113
+  data.tar.gz: 0564f2a5d2c0cb5aeb23dccebf99c062c78261ac967f4b32f4e2d7c84efff33d
+SHA512:
+  metadata.gz: ff35ed4deb9f2907be7270a3eb79e81414a08ea2eb9af0c85b72f873d41664d2c872201c2e501bef7ee8550e9da54421366970a04f1febb2dadb17963b869bf6
+  data.tar.gz: 35b19c88297ac5561635bf2ef50716b1d6c0604abe7632c380d3fe2cd012fb420f60f0b62fea22a072ef19f3f78cb2fb7f53c5f0bbd235c874a91dfc4ac6434c

data/lib/vigil/client.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "openssl"
+require "time"
+
+module Vigil
+  class Client
+    # Official Ruby client for the Vigil compliance screening API.
+    #
+    # @example
+    #   client = Vigil::Client.new(api_key: "vgl_sk_live_...")
+    #   result = client.screen("Osama bin Laden")
+    #   puts result.status          # "match"
+    #   puts result.recommendation  # "block"
+
+    attr_reader :api_key, :base_url
+
+    def initialize(api_key:, base_url: "https://api.vigilhq.dev", signing_secret: nil, timeout: 30)
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @signing_secret = signing_secret
+      @conn = Faraday.new(url: @base_url) do |f|
+        f.request :json
+        f.response :json
+        f.options.timeout = timeout
+        f.headers["Authorization"] = "Bearer #{api_key}"
+        f.headers["User-Agent"] = "vigil-ruby/#{VERSION}"
+        f.headers["Content-Type"] = "application/json"
+      end
+    end
+
+    # ── Core Screening ──────────────────────────────────
+
+    def screen(entity, context: "onboarding", entity_type: nil, date_of_birth: nil, nationality: nil, id_number: nil)
+      payload = { entity: entity, context: context }
+      payload[:entity_type] = entity_type if entity_type
+      payload[:date_of_birth] = date_of_birth if date_of_birth
+      payload[:nationality] = nationality if nationality
+      payload[:id_number] = id_number if id_number
+
+      data = post("/v1/screen", payload)
+      parse_screen_response(data)
+    end
+
+    def get_screening(screening_id)
+      data = get("/v1/screen/#{screening_id}")
+      parse_screen_response(data)
+    end
+
+    def list_screenings(limit: 50, offset: 0, status: nil)
+      params = { limit: limit, offset: offset }
+      params[:status] = status if status
+      data = get("/v1/screenings", params)
+      results = data.is_a?(Array) ? data : (data["results"] || [])
+      results.map { |r| parse_screen_response(r) }
+    end
+
+    # ── Batch Screening ─────────────────────────────────
+
+    def batch_screen(entities)
+      data = post("/v1/screen/batch", { entities: entities })
+      BatchJob.new(**symbolize(data))
+    end
+
+    def get_batch_job(job_id)
+      data = get("/v1/screen/batch/#{job_id}")
+      BatchJob.new(**symbolize(data))
+    end
+
+    # ── Monitoring ──────────────────────────────────────
+
+    def add_monitor(entity, **kwargs)
+      post("/v1/monitor/entities", { entity: entity, **kwargs })
+    end
+
+    def list_monitors
+      get("/v1/monitor/entities")
+    end
+
+    def remove_monitor(monitor_id)
+      delete("/v1/monitor/entities/#{monitor_id}")
+    end
+
+    # ── Watchlist Info ──────────────────────────────────
+
+    def list_watchlists
+      data = get("/v1/lists")
+      sources = data.is_a?(Array) ? data : (data["sources"] || [])
+      sources.map { |s| WatchlistSource.new(**symbolize(s)) }
+    end
+
+    # ── API Keys ────────────────────────────────────────
+
+    def create_key(name)
+      post("/v1/keys", { name: name })
+    end
+
+    def list_keys
+      get("/v1/keys")
+    end
+
+    def revoke_key(key_id)
+      delete("/v1/keys/#{key_id}")
+    end
+
+    # ── Webhooks ────────────────────────────────────────
+
+    def create_webhook(url, events: nil)
+      payload = { url: url }
+      payload[:events] = events if events
+      post("/v1/webhooks", payload)
+    end
+
+    def list_webhooks
+      get("/v1/webhooks")
+    end
+
+    def delete_webhook(webhook_id)
+      delete("/v1/webhooks/#{webhook_id}")
+    end
+
+    private
+
+    def sign_headers(method, path, body = "")
+      return {} unless @signing_secret
+
+      ts = (Time.now.to_f * 1000).to_i.to_s
+      body_hash = OpenSSL::Digest::SHA256.hexdigest(body)
+      payload = "#{ts}.#{method.upcase}.#{path}.#{body_hash}"
+      sig = OpenSSL::HMAC.hexdigest("SHA256", @signing_secret, payload)
+      { "X-Vigil-Timestamp" => ts, "X-Vigil-Signature" => sig }
+    end
+
+    def handle_error(response)
+      case response.status
+      when 401 then raise AuthError
+      when 403 then raise IPNotAllowedError
+      when 404 then raise NotFoundError
+      when 429
+        retry_after = (response.headers["retry-after"] || "60").to_i
+        raise RateLimitError.new(retry_after: retry_after)
+      when 400..599
+        body = response.body
+        msg = body.is_a?(Hash) ? body.dig("error", "message") || body.to_s : body.to_s
+        code = body.is_a?(Hash) ? body.dig("error", "code") || "UNKNOWN" : "UNKNOWN"
+        raise Error.new(msg, status_code: response.status, code: code)
+      end
+    end
+
+    def get(path, params = nil)
+      resp = @conn.get(path, params) do |req|
+        sign_headers("GET", path).each { |k, v| req.headers[k] = v }
+      end
+      handle_error(resp) if resp.status >= 400
+      resp.body
+    end
+
+    def post(path, payload)
+      body = payload.to_json
+      resp = @conn.post(path) do |req|
+        req.body = body
+        sign_headers("POST", path, body).each { |k, v| req.headers[k] = v }
+      end
+      handle_error(resp) if resp.status >= 400
+      resp.body
+    end
+
+    def delete(path)
+      resp = @conn.delete(path) do |req|
+        sign_headers("DELETE", path).each { |k, v| req.headers[k] = v }
+      end
+      handle_error(resp) if resp.status >= 400
+    end
+
+    def parse_screen_response(data)
+      data = symbolize(data)
+      data[:sanctions] = SanctionsResult.new(**symbolize(data[:sanctions])) if data[:sanctions].is_a?(Hash)
+      data[:pep] = PepResult.new(**symbolize(data[:pep])) if data[:pep].is_a?(Hash)
+      data[:matches] = (data[:matches] || []).map { |m| MatchDetail.new(**symbolize(m)) }
+      ScreenResponse.new(**data)
+    end
+
+    def symbolize(hash)
+      return hash unless hash.is_a?(Hash)
+      hash.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/vigil/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Vigil
+  class Error < StandardError
+    attr_reader :status_code, :code
+
+    def initialize(message, status_code: 0, code: "UNKNOWN")
+      @status_code = status_code
+      @code = code
+      super("[#{code}] #{message}")
+    end
+  end
+
+  class AuthError < Error
+    def initialize(message = "Invalid or missing API key")
+      super(message, status_code: 401, code: "UNAUTHORIZED")
+    end
+  end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: 60)
+      @retry_after = retry_after
+      super(message, status_code: 429, code: "RATE_LIMIT_EXCEEDED")
+    end
+  end
+
+  class NotFoundError < Error
+    def initialize(message = "Resource not found")
+      super(message, status_code: 404, code: "NOT_FOUND")
+    end
+  end
+
+  class IPNotAllowedError < Error
+    def initialize(message = "IP not allowed")
+      super(message, status_code: 403, code: "IP_NOT_ALLOWED")
+    end
+  end
+end

data/lib/vigil/types.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Vigil
+  # Immutable struct-like classes for API responses
+  ScreenResponse = Struct.new(
+    :id, :status, :risk_score, :risk_level,
+    :sanctions, :pep, :matches, :recommendation,
+    :screening_time_ms, :created_at, :narrative, :adverse_media,
+    keyword_init: true
+  )
+
+  SanctionsResult = Struct.new(:match, :lists_checked, :last_updated, keyword_init: true)
+  PepResult = Struct.new(:match, keyword_init: true)
+
+  MatchDetail = Struct.new(
+    :entity_id, :source, :source_entity_id, :matched_name,
+    :entity_type, :score, :programs, :aliases,
+    :date_of_birth, :nationality, :match_reasons,
+    keyword_init: true
+  )
+
+  BatchJob = Struct.new(:job_id, :status, :total, :completed, :results, keyword_init: true)
+  WatchlistSource = Struct.new(:code, :name, :entity_count, :last_ingested_at, :is_active, keyword_init: true)
+end

data/lib/vigil.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "vigil/client"
+require_relative "vigil/types"
+require_relative "vigil/errors"
+
+module Vigil
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: vigilhq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vigil
+bindir: bin
+cert_chain: []
+date: 2026-02-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Screen entities against global sanctions, PEP lists, and trust networks
+  with one API call.
+email: sales@vigilhq.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/vigil.rb
+- lib/vigil/client.rb
+- lib/vigil/errors.rb
+- lib/vigil/types.rb
+homepage: https://vigilhq.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://vigilhq.dev
+  source_code_uri: https://github.com/ymatagne/vigil
+  documentation_uri: https://vigilhq.dev/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Official Ruby SDK for the Vigil compliance screening API
+test_files: []