From a4085e7eef2a4a1314e44ddc6e976918478839d9 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Mon, 18 Nov 2024 17:10:57 +0100 Subject: [PATCH 1/5] chore: add description to enum docs --- docs/BotdBotResult.md | 5 +++++ docs/ErrorCode.md | 19 +++++++++++++++++++ docs/VPNConfidence.md | 1 + template/enum_outer_doc.mustache | 10 ++++++++++ 4 files changed, 35 insertions(+) create mode 100644 template/enum_outer_doc.mustache diff --git a/docs/BotdBotResult.md b/docs/BotdBotResult.md index 3439ac9..727f15f 100644 --- a/docs/BotdBotResult.md +++ b/docs/BotdBotResult.md @@ -1,6 +1,11 @@ # BotdBotResult + Bot detection result: + * `notDetected` - the visitor is not a bot + * `good` - good bot detected, such as Google bot, Baidu Spider, AlexaBot and so on + * `bad` - bad bot detected, such as Selenium, Puppeteer, Playwright, headless browsers, and so on + ## Enum diff --git a/docs/ErrorCode.md b/docs/ErrorCode.md index e118c89..c107451 100644 --- a/docs/ErrorCode.md +++ b/docs/ErrorCode.md @@ -1,6 +1,25 @@ # ErrorCode + Error code: + * `RequestCannotBeParsed` - the query parameters or JSON payload contains some errors + that prevented us from parsing it (wrong type/surpassed limits). + * `TokenRequired` - `Auth-API-Key` header is missing or empty. + * `TokenNotFound` - no Fingerprint application found for specified secret key. + * `SubscriptionNotActive` - Fingerprint application is not active. + * `WrongRegion` - server and application region differ. + * `FeatureNotEnabled` - this feature (for example, Delete API) is not enabled for your application. + * `RequestNotFound` - the specified request ID was not found. It never existed, expired, or it has been deleted. + * `VisitorNotFound` - The specified visitor ID was not found. It never existed or it may have already been deleted. + * `TooManyRequests` - the limit on secret API key requests per second has been exceeded. + * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded. + * `StateNotReady` - The event specified with request id is + not ready for updates yet. Try again. + This error happens in rare cases when update API is called immediately + after receiving the request id on the client. In case you need to send + information right away, we recommend using the JS agent API instead. + * `Failed` - internal server error. + ## Enum diff --git a/docs/VPNConfidence.md b/docs/VPNConfidence.md index 6c6cfe3..8e95209 100644 --- a/docs/VPNConfidence.md +++ b/docs/VPNConfidence.md @@ -1,6 +1,7 @@ # VPNConfidence + A confidence rating for the VPN detection result — "low", "medium", or "high". Depends on the combination of results returned from all VPN detection methods. ## Enum diff --git a/template/enum_outer_doc.mustache b/template/enum_outer_doc.mustache new file mode 100644 index 0000000..0f2f0fa --- /dev/null +++ b/template/enum_outer_doc.mustache @@ -0,0 +1,10 @@ +# {{classname}} +{{#unescapedDescription}} + {{{.}}} + +{{/unescapedDescription}} +## Enum + +{{#allowableValues}}{{#enumVars}} +* `{{name}}` (value: `{{{value}}}`) +{{/enumVars}}{{/allowableValues}} From 0812c433b0ca08349b7e214030c45857ecc6d451 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Mon, 18 Nov 2024 17:12:18 +0100 Subject: [PATCH 2/5] chore: fix model docs formatting --- docs/Velocity.md | 17 ++++++++++++++++- docs/VelocityIntervals.md | 3 ++- docs/WebhookVelocity.md | 17 ++++++++++++++++- template/pojo_doc.mustache | 2 +- 4 files changed, 35 insertions(+), 4 deletions(-) diff --git a/docs/Velocity.md b/docs/Velocity.md index 2343fc6..47962ed 100644 --- a/docs/Velocity.md +++ b/docs/Velocity.md @@ -2,7 +2,22 @@ # Velocity -Sums key data points for a specific `visitorId`, `ipAddress` and `linkedId` at three distinct time intervals: 5 minutes, 1 hour, and 24 hours as follows: - Number of distinct IP addresses associated to the visitor ID. - Number of distinct linked IDs associated with the visitor ID. - Number of distinct countries associated with the visitor ID. - Number of identification events associated with the visitor ID. - Number of identification events associated with the detected IP address. - Number of distinct IP addresses associated with the provided linked ID. - Number of distinct visitor IDs associated with the provided linked ID. The `24h` interval of `distinctIp`, `distinctLinkedId`, `distinctCountry`, `distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted if the number of `events` for the visitor ID in the last 24 hours (`events.intervals.['24h']`) is higher than 20.000. +Sums key data points for a specific `visitorId`, `ipAddress` and `linkedId` at three distinct time +intervals: 5 minutes, 1 hour, and 24 hours as follows: + +- Number of distinct IP addresses associated to the visitor ID. +- Number of distinct linked IDs associated with the visitor ID. +- Number of distinct countries associated with the visitor ID. +- Number of identification events associated with the visitor ID. +- Number of identification events associated with the detected IP address. +- Number of distinct IP addresses associated with the provided linked ID. +- Number of distinct visitor IDs associated with the provided linked ID. + +The `24h` interval of `distinctIp`, `distinctLinkedId`, `distinctCountry`, +`distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted +if the number of `events` for the visitor ID in the last 24 +hours (`events.intervals.['24h']`) is higher than 20.000. + ## Properties diff --git a/docs/VelocityIntervals.md b/docs/VelocityIntervals.md index e4ed630..41a688d 100644 --- a/docs/VelocityIntervals.md +++ b/docs/VelocityIntervals.md @@ -2,7 +2,8 @@ # VelocityIntervals -Is absent if the velocity data could not be generated for the visitor ID. +Is absent if the velocity data could not be generated for the visitor ID. + ## Properties diff --git a/docs/WebhookVelocity.md b/docs/WebhookVelocity.md index 41c4947..841b599 100644 --- a/docs/WebhookVelocity.md +++ b/docs/WebhookVelocity.md @@ -2,7 +2,22 @@ # WebhookVelocity -Sums key data points for a specific `visitorId`, `ipAddress` and `linkedId` at three distinct time intervals: 5 minutes, 1 hour, and 24 hours as follows: - Number of distinct IP addresses associated to the visitor ID. - Number of distinct linked IDs associated with the visitor ID. - Number of distinct countries associated with the visitor ID. - Number of identification events associated with the visitor ID. - Number of identification events associated with the detected IP address. - Number of distinct IP addresses associated with the provided linked ID. - Number of distinct visitor IDs associated with the provided linked ID. The `24h` interval of `distinctIp`, `distinctLinkedId`, `distinctCountry`, `distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted if the number of `events` for the visitor ID in the last 24 hours (`events.intervals.['24h']`) is higher than 20.000. +Sums key data points for a specific `visitorId`, `ipAddress` and `linkedId` at three distinct time +intervals: 5 minutes, 1 hour, and 24 hours as follows: + +- Number of distinct IP addresses associated to the visitor ID. +- Number of distinct linked IDs associated with the visitor ID. +- Number of distinct countries associated with the visitor ID. +- Number of identification events associated with the visitor ID. +- Number of identification events associated with the detected IP address. +- Number of distinct IP addresses associated with the provided linked ID. +- Number of distinct visitor IDs associated with the provided linked ID. + +The `24h` interval of `distinctIp`, `distinctLinkedId`, `distinctCountry`, +`distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted +if the number of `events` for the visitor ID in the last 24 +hours (`events.intervals.['24h']`) is higher than 20.000. + ## Properties diff --git a/template/pojo_doc.mustache b/template/pojo_doc.mustache index 99f6613..ee0791b 100644 --- a/template/pojo_doc.mustache +++ b/template/pojo_doc.mustache @@ -1,7 +1,7 @@ # {{classname}} {{#description}} -{{{description}}} +{{{unescapedDescription}}} {{/description}} ## Properties From 817b4443db7d9eea45ac36d3843335762ead01b5 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Fri, 22 Nov 2024 16:35:48 +0100 Subject: [PATCH 3/5] feat: rename `Webhook` class to `WebhookValidation` --- .changeset/chilly-dryers-fail.md | 6 ++++++ README.md | 4 ++-- .../example/WebhookSignatureSample.java | 4 ++-- .../sdk/{Webhook.java => WebhookValidation.java} | 2 +- ...WebhookTest.java => WebhookValidationTest.java} | 14 +++++++------- template/README.mustache | 4 ++-- 6 files changed, 20 insertions(+), 14 deletions(-) create mode 100644 .changeset/chilly-dryers-fail.md rename sdk/src/main/java/com/fingerprint/sdk/{Webhook.java => WebhookValidation.java} (98%) rename sdk/src/test/java/com/fingerprint/{WebhookTest.java => WebhookValidationTest.java} (67%) diff --git a/.changeset/chilly-dryers-fail.md b/.changeset/chilly-dryers-fail.md new file mode 100644 index 0000000..9549a7c --- /dev/null +++ b/.changeset/chilly-dryers-fail.md @@ -0,0 +1,6 @@ +--- +"fingerprint-pro-server-api-java-sdk": major +--- + +Rename `Webhook` class to `WebhookValidation`. +Right now, `Webhook` class points to the actual data model. diff --git a/README.md b/README.md index 4afa7a6..eddc50a 100644 --- a/README.md +++ b/README.md @@ -240,7 +240,7 @@ This SDK provides utility method for verifying the HMAC signature of the incomin Here is an example implementation using Spring Boot: ```java -import com.fingerprint.sdk.Webhook; +import com.fingerprint.sdk.WebhookValidation; @RestController class WebhookController { @@ -257,7 +257,7 @@ class WebhookController { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Missing fpjs-event-signature header"); } - final boolean isValidSignature = Webhook.isValidWebhookSignature(signature, webhook, secret); + final boolean isValidSignature = WebhookValidation.isValidWebhookSignature(signature, webhook, secret); if (!isValidSignature) { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Webhook signature is not valid"); } diff --git a/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java b/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java index 7702f70..ac42ebc 100644 --- a/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java +++ b/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java @@ -1,6 +1,6 @@ package com.fingerprint.example; -import com.fingerprint.sdk.Webhook; +import com.fingerprint.sdk.WebhookValidation; import java.nio.charset.StandardCharsets; import java.security.NoSuchAlgorithmException; @@ -13,7 +13,7 @@ public static void main(String... args) { final byte[] data = "data".getBytes(StandardCharsets.UTF_8); try { - boolean isSignatureValid = Webhook.isValidWebhookSignature(header, data, secret); + boolean isSignatureValid = WebhookValidation.isValidWebhookSignature(header, data, secret); if (isSignatureValid) { System.out.println("Webhook signature is valid"); } else { diff --git a/sdk/src/main/java/com/fingerprint/sdk/Webhook.java b/sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java similarity index 98% rename from sdk/src/main/java/com/fingerprint/sdk/Webhook.java rename to sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java index daf2098..b804b0c 100644 --- a/sdk/src/main/java/com/fingerprint/sdk/Webhook.java +++ b/sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java @@ -8,7 +8,7 @@ import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; -public class Webhook { +public class WebhookValidation { /** * Verifies the HMAC signature extracted from the "fpjs-event-signature" header of the incoming request. diff --git a/sdk/src/test/java/com/fingerprint/WebhookTest.java b/sdk/src/test/java/com/fingerprint/WebhookValidationTest.java similarity index 67% rename from sdk/src/test/java/com/fingerprint/WebhookTest.java rename to sdk/src/test/java/com/fingerprint/WebhookValidationTest.java index 9e1b5e9..0e26863 100644 --- a/sdk/src/test/java/com/fingerprint/WebhookTest.java +++ b/sdk/src/test/java/com/fingerprint/WebhookValidationTest.java @@ -1,6 +1,6 @@ package com.fingerprint; -import com.fingerprint.sdk.Webhook; +import com.fingerprint.sdk.WebhookValidation; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.TestInstance; @@ -9,7 +9,7 @@ import java.security.NoSuchAlgorithmException; @TestInstance(TestInstance.Lifecycle.PER_CLASS) -public class WebhookTest { +public class WebhookValidationTest { private static final String validHeader = "v1=1b2c16b75bd2a870c114153ccda5bcfca63314bc722fa160d690de133ccbb9db"; private static final String secret = "secret"; @@ -17,32 +17,32 @@ public class WebhookTest { @Test public void validHeaderTest() throws NoSuchAlgorithmException { - boolean result = Webhook.isValidWebhookSignature(validHeader, data, secret); + boolean result = WebhookValidation.isValidWebhookSignature(validHeader, data, secret); Assertions.assertTrue(result); } @Test public void invalidHeaderTest() throws NoSuchAlgorithmException { - boolean result = Webhook.isValidWebhookSignature("v2=wrong", data, secret); + boolean result = WebhookValidation.isValidWebhookSignature("v2=wrong", data, secret); assert !result; } @Test public void headerWithoutVersionTest() throws NoSuchAlgorithmException { - boolean result = Webhook.isValidWebhookSignature("secretonly", data, secret); + boolean result = WebhookValidation.isValidWebhookSignature("secretonly", data, secret); assert !result; } @Test public void emptySecretTest() throws NoSuchAlgorithmException { Assertions.assertThrows(IllegalArgumentException.class, () -> { - Webhook.isValidWebhookSignature("v1=value", data, ""); + WebhookValidation.isValidWebhookSignature("v1=value", data, ""); }); } @Test public void emptyDataTest() throws NoSuchAlgorithmException { - boolean result = Webhook.isValidWebhookSignature(validHeader, "".getBytes(), secret); + boolean result = WebhookValidation.isValidWebhookSignature(validHeader, "".getBytes(), secret); assert !result; } diff --git a/template/README.mustache b/template/README.mustache index d155423..1950339 100644 --- a/template/README.mustache +++ b/template/README.mustache @@ -267,7 +267,7 @@ This SDK provides utility method for verifying the HMAC signature of the incomin Here is an example implementation using Spring Boot: ```java -import com.fingerprint.sdk.Webhook; +import com.fingerprint.sdk.WebhookValidation; @RestController class WebhookController { @@ -284,7 +284,7 @@ class WebhookController { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Missing fpjs-event-signature header"); } - final boolean isValidSignature = Webhook.isValidWebhookSignature(signature, webhook, secret); + final boolean isValidSignature = WebhookValidation.isValidWebhookSignature(signature, webhook, secret); if (!isValidSignature) { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Webhook signature is not valid"); } From f49c1c2cd754af8e1f763559886d30ce69567a39 Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Fri, 22 Nov 2024 16:42:08 +0100 Subject: [PATCH 4/5] feat: rename IsValidWebhookSignature to isSignatureValid in `WebhookValidation --- .changeset/silly-pigs-refuse.md | 5 +++++ README.md | 2 +- .../fingerprint/example/WebhookSignatureSample.java | 2 +- .../java/com/fingerprint/sdk/WebhookValidation.java | 2 +- .../java/com/fingerprint/WebhookValidationTest.java | 10 +++++----- template/README.mustache | 2 +- 6 files changed, 14 insertions(+), 9 deletions(-) create mode 100644 .changeset/silly-pigs-refuse.md diff --git a/.changeset/silly-pigs-refuse.md b/.changeset/silly-pigs-refuse.md new file mode 100644 index 0000000..1d913e0 --- /dev/null +++ b/.changeset/silly-pigs-refuse.md @@ -0,0 +1,5 @@ +--- +"fingerprint-pro-server-api-java-sdk": major +--- + +Rename `IsValidWebhookSignature` to `isSignatureValid` in `WebhookValidation` diff --git a/README.md b/README.md index eddc50a..afcf83f 100644 --- a/README.md +++ b/README.md @@ -257,7 +257,7 @@ class WebhookController { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Missing fpjs-event-signature header"); } - final boolean isValidSignature = WebhookValidation.isValidWebhookSignature(signature, webhook, secret); + final boolean isValidSignature = WebhookValidation.isSignatureValid(signature, webhook, secret); if (!isValidSignature) { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Webhook signature is not valid"); } diff --git a/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java b/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java index ac42ebc..6de4e57 100644 --- a/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java +++ b/examples/src/main/java/com/fingerprint/example/WebhookSignatureSample.java @@ -13,7 +13,7 @@ public static void main(String... args) { final byte[] data = "data".getBytes(StandardCharsets.UTF_8); try { - boolean isSignatureValid = WebhookValidation.isValidWebhookSignature(header, data, secret); + boolean isSignatureValid = WebhookValidation.isSignatureValid(header, data, secret); if (isSignatureValid) { System.out.println("Webhook signature is valid"); } else { diff --git a/sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java b/sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java index b804b0c..a6ba033 100644 --- a/sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java +++ b/sdk/src/main/java/com/fingerprint/sdk/WebhookValidation.java @@ -20,7 +20,7 @@ public class WebhookValidation { * @throws NoSuchAlgorithmException in case HMAC-SHA-256 isn't available * @throws IllegalArgumentException if an invalid key is provided */ - public static boolean isValidWebhookSignature(String header, byte[] data, String secret) throws NoSuchAlgorithmException { + public static boolean isSignatureValid(String header, byte[] data, String secret) throws NoSuchAlgorithmException { String[] signatures = header.split(","); for (String signature : signatures) { String[] parts = signature.split("="); diff --git a/sdk/src/test/java/com/fingerprint/WebhookValidationTest.java b/sdk/src/test/java/com/fingerprint/WebhookValidationTest.java index 0e26863..8521cfb 100644 --- a/sdk/src/test/java/com/fingerprint/WebhookValidationTest.java +++ b/sdk/src/test/java/com/fingerprint/WebhookValidationTest.java @@ -17,32 +17,32 @@ public class WebhookValidationTest { @Test public void validHeaderTest() throws NoSuchAlgorithmException { - boolean result = WebhookValidation.isValidWebhookSignature(validHeader, data, secret); + boolean result = WebhookValidation.isSignatureValid(validHeader, data, secret); Assertions.assertTrue(result); } @Test public void invalidHeaderTest() throws NoSuchAlgorithmException { - boolean result = WebhookValidation.isValidWebhookSignature("v2=wrong", data, secret); + boolean result = WebhookValidation.isSignatureValid("v2=wrong", data, secret); assert !result; } @Test public void headerWithoutVersionTest() throws NoSuchAlgorithmException { - boolean result = WebhookValidation.isValidWebhookSignature("secretonly", data, secret); + boolean result = WebhookValidation.isSignatureValid("secretonly", data, secret); assert !result; } @Test public void emptySecretTest() throws NoSuchAlgorithmException { Assertions.assertThrows(IllegalArgumentException.class, () -> { - WebhookValidation.isValidWebhookSignature("v1=value", data, ""); + WebhookValidation.isSignatureValid("v1=value", data, ""); }); } @Test public void emptyDataTest() throws NoSuchAlgorithmException { - boolean result = WebhookValidation.isValidWebhookSignature(validHeader, "".getBytes(), secret); + boolean result = WebhookValidation.isSignatureValid(validHeader, "".getBytes(), secret); assert !result; } diff --git a/template/README.mustache b/template/README.mustache index 1950339..136a183 100644 --- a/template/README.mustache +++ b/template/README.mustache @@ -284,7 +284,7 @@ class WebhookController { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Missing fpjs-event-signature header"); } - final boolean isValidSignature = WebhookValidation.isValidWebhookSignature(signature, webhook, secret); + final boolean isValidSignature = WebhookValidation.isSignatureValid(signature, webhook, secret); if (!isValidSignature) { return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Webhook signature is not valid"); } From b388380a933b8405339c0cc1ebbca5527dba6e7b Mon Sep 17 00:00:00 2001 From: Ilya Taratukhin Date: Fri, 22 Nov 2024 16:52:28 +0100 Subject: [PATCH 5/5] chore: exit pre-release mode --- .changeset/pre.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/pre.json b/.changeset/pre.json index 3fddb34..b008904 100644 --- a/.changeset/pre.json +++ b/.changeset/pre.json @@ -1,5 +1,5 @@ { - "mode": "pre", + "mode": "exit", "tag": "develop", "initialVersions": { "fingerprint-pro-server-api-java-sdk": "6.2.0"