incognia_api 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a52bbb4d602bec60845df1106450e7d4642f55cc993635fe67abf05bb1e4faf3
-  data.tar.gz: 88daa93221f7d5901ae3235e7da5175a0a2542e7778543f713687b34d4c49d28
+  metadata.gz: 485a9d5fcf16b98a5ca942d1d4fe47e876f25f60a70193d7bcb70110aebd725a
+  data.tar.gz: 97a539a4a8a7a7d30ab63e12f6969b34580386fa76e93dee106ffd9a8371f253
 SHA512:
-  metadata.gz: ee85936265c871bb6d76a1b10f4c2959d7e2ce9bc3c5df5eba102e5f4a3a1b2b33f35b79636db0b12e79955177dd8733d70e4e5cb8c32a47560f112ac6f3839f
-  data.tar.gz: a9c0b9a25f6b06931d6bc14e0fabb6d4e068d774e9c526e28bf6a66ac5d125b8c2549bee872f6f8e50d6a4781a3ca79a7338ce11e50784963d891c623fec62f0
+  metadata.gz: f282bbcc8499cbc2bcae7ad4aaa151dc785a7c1e86e40ebeabe91de440ba51b28d9de06c2e4db9a9870381d3ba6fc6ebbd4e71e9dfdd61c821b085a18fd6cf2e
+  data.tar.gz: bffdaf58ca5335190f1a7b4a11ad1a2e0254f47a75366a60b54f3e6697b58c79f2ba531e49f0195068c768327e205b06016120b38369da35cbf77db1bbbf763f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [2.2.0] - 2025-09-16
+
+- Add support for passing an optional person_id parameter to HTTP request helpers
+
 ## [2.1.0] - 2025-05-09
 
 - Add support for passing an optional location parameter to register logins and payments

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    incognia_api (2.1.0)
+    incognia_api (2.2.0)
       faraday (~> 1.10)
       faraday_middleware (~> 1.2)
 

data/README.md

@@ -6,7 +6,7 @@ Incognia Ruby library provides easy access to the Incogia API from Ruby
 applications. It includes:
 
 - Basic Access Token management (with transparent token refresh)
-- API resounces dinamically built from API responses
+- API resources dinamically built from API responses
 
 For more information on how to integrate Incognia APIs, refer to one of the
 following guides:
@@ -69,14 +69,35 @@ assessment = Incognia::Api.register_signup(
 It also supports optional parameters, for example:
 
 ```ruby
-address = Incognia::Address.new(line: "West 34th Street, New York City, NY 10001")
+# address may include any or all of the following formats: address line, coordinates, or structured address
+address = Incognia::Address.new(
+  line: "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200", 
+  coordinates: {lat: -23.589339, lng: -46.659043}, 
+  structured: 
+  {
+    locale: "pt-BR",
+    country_name: "Brasil",
+    country_code: "BR",
+    state: "SP",
+    city: "São Paulo",
+    borough: "",
+    neighborhood: "Bela Vista",
+    street: "Av. Paulista",
+    number: "1578",
+    complements: "Andar 2",
+    postal_code: "01310-200"
+  }
+)
+# Person id: either a valid SSN (USA) or CPF (Brazil). Only numerical characters must be provided as value.
+person_id = Incognia::PersonId.new(type: "cpf", value: "12345678901")
 request_token = "WlMksW+jh5GPhqWBorsV8yDihoSHHpmt+DpjJ7eYxpHhuO/5tuHTuA..."
 external_id = "7b02736a-7718-4b83-8982-f68fb6f501fa"
 
 assessment = Incognia::Api.register_signup(
   request_token: request_token,
   address: address,
-  external_id: external_id
+  external_id: external_id,
+  person_id: person_id
 )
 
 # => #<OpenStruct id="...", device_id="...", risk_assessment="..", evidence=...>
@@ -102,14 +123,29 @@ assessment = Incognia::Api.register_login(
 It also supports optional parameters, for example:
 
 ```ruby
+timestamp = Date.parse("2025-04-23T12:12:12-03:00")
+location = Incognia::Location.new(latitude: -23.589339, longitude: -46.659043, collected_at: timestamp)
+# These are all also valid timestamps for Location.timestamp
+timestamp1 = Time.new(2025, 4, 23, 12, 12, 12, "-03:00")
+timestamp2 = DateTime.parse("2025-04-23T12:12:12-03:00")
+timestamp3 = "2025-04-23T12:12:12-03:00"
+timestamp4 = Time.now()
+
+# Person id: either a valid SSN (USA) or CPF (Brazil). Only numerical characters must be provided as value.
+person_id = Incognia::PersonId.new(type: "cpf", value: "12345678901")
+external_id = 'some-external-identifier'
+
+# Mandatory fields
 request_token = "WlMksW+jh5GPhqWBorsV8yDihoSHHpmt+DpjJ7eYxpHhuO/5tuHTuA..."
 account_id = 'account-identifier-123'
-external_id = 'some-external-identifier'
+
 
 assessment = Incognia::Api.register_login(
   request_token: request_token,
   account_id: account_id,
   external_id: external_id,
+  person_id: person_id,
+  location: location,
   eval: false # can be used to register a new login without evaluating it
 )
 
@@ -182,9 +218,17 @@ payment_methods = [
   }
 ]
 
+location = Incognia::Location.new(latitude: -23.589339, longitude: -46.659043, collected_at: "2025-04-23T12:12:12-03:00")
+
+# Person id: either a valid SSN (USA) or CPF (Brazil). Only numerical characters must be provided as value.
+person_id = Incognia::PersonId.new(type: "cpf", value: "12345678901")
+external_id = 'some-external-identifier'
+
 assessment = Incognia::Api.register_payment(
   request_token: 'request-token',
   account_id: 'account-id',
+  location: location,
+  person_id: person_id,
   external_id: 'external-id',
   addresses: addresses,
   payment_value: payment_value,
@@ -198,21 +242,25 @@ assessment = Incognia::Api.register_payment(
 
 This method registers a feedback event for the given identifiers (optional arguments), returning true when success.
 
-The `occurred_at` argument should be a _Time_, _DateTime_ or an date in **RFC 3339** format.
+The `occurred_at` argument should be a _Time_, _DateTime_ or a date in **RFC 3339** format.
 
-The `expires_at` argument should be a _Time_, _DateTime_ or an date in **RFC 3339** format.
+The `expires_at` argument should be a _Time_, _DateTime_ or a date in **RFC 3339** format.
 
 
 ```ruby
 request_token = 'request-token'
 account_id = 'account-id'
 occurred_at = DateTime.parse('2024-07-22T15:20:00Z')
+# person id: optional
+person_id = Incognia::PersonId.new(type: "cpf", value: "12345678901")
+
 
 success = Incognia::Api.register_feedback(
   event: Incognia::Constants::FeedbackEvent::ACCOUNT_TAKEOVER,
   occurred_at: occurred_at,
   request_token: request_token,
-  account_id: account_id
+  account_id: account_id,
+  person_id: person_id
 )
 
 # => true

data/lib/incognia_api/api.rb

@@ -9,10 +9,11 @@ module Incognia
       # business layer: uses the Client.instance to build domain objects
       # raises missing parameters errors
 
-      def register_signup(request_token: nil, address: nil, **opts)
+      def register_signup(request_token: nil, address: nil, person_id: nil, **opts)
         params = { request_token: request_token }.compact
         params.merge!(opts)
         params.merge!(address.to_hash) if address
+        params.merge!(person_id: person_id.to_hash) if person_id
 
         response = connection.request(
           :post,
@@ -23,13 +24,14 @@ module Incognia
         SignupAssessment.from_hash(response.body) if response.success?
       end
 
-      def register_login(account_id:, request_token: nil, location: nil, **opts)
+      def register_login(account_id:, request_token: nil, location: nil, person_id: nil, **opts)
         params = {
           type: :login,
           account_id: account_id,
           request_token: request_token
         }.compact
         params.merge!(location: location.to_hash) if location
+        params.merge!(person_id: person_id.to_hash) if person_id
         params.merge!(opts)
 
         response = connection.request(
@@ -41,11 +43,12 @@ module Incognia
         LoginAssessment.from_hash(response.body) if response.success?
       end
 
-      def register_feedback(event:, occurred_at: nil, expires_at: nil, **ids)
+      def register_feedback(event:, occurred_at: nil, expires_at: nil, person_id: nil, **ids)
         occurred_at = occurred_at.to_datetime.rfc3339 if occurred_at.respond_to? :to_datetime
         expires_at = expires_at.to_datetime.rfc3339 if expires_at.respond_to? :to_datetime
 
         params = { event: event, occurred_at: occurred_at, expires_at: expires_at }.compact
+        params.merge!(person_id: person_id.to_hash) if person_id
         params.merge!(ids)
 
         response = connection.request(
@@ -57,13 +60,14 @@ module Incognia
         response.success?
       end
 
-      def register_payment(account_id:, request_token: nil, location: nil, **opts)
+      def register_payment(account_id:, request_token: nil, location: nil, person_id: nil, **opts)
         params = {
           type: :payment,
           account_id: account_id,
           request_token: request_token
         }.compact
         params.merge!(location: location.to_hash) if location
+        params.merge!(person_id: person_id.to_hash) if person_id
         params.merge!(opts)
 
         response = connection.request(

data/lib/incognia_api/person_id.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Incognia
+  class PersonId
+    attr_reader :type, :value
+
+    def initialize(type:, value:)
+      @type  = type
+      @value = value
+    end
+
+    def to_hash
+      { type: type, value: value }
+    end
+  end
+end

data/lib/incognia_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Incognia
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/lib/incognia_api.rb

@@ -7,6 +7,7 @@ require_relative "incognia_api/util"
 require_relative "incognia_api/address"
 require_relative "incognia_api/api"
 require_relative "incognia_api/location"
+require_relative "incognia_api/person_id"
 
 require_relative "incognia_api/resources/api_resource"
 require_relative "incognia_api/resources/signup_assessment"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: incognia_api
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Guilherme Cavalcanti
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-09 00:00:00.000000000 Z
+date: 2025-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -46,7 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
-- ".github/workflows/codeql.yml"
+- ".github/workflows/codeql.yaml"
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".rspec"
@@ -66,6 +66,7 @@ files:
 - lib/incognia_api/configuration.rb
 - lib/incognia_api/constants/feedback_event.rb
 - lib/incognia_api/location.rb
+- lib/incognia_api/person_id.rb
 - lib/incognia_api/resources/api_resource.rb
 - lib/incognia_api/resources/credentials.rb
 - lib/incognia_api/resources/login_assessment.rb