Add support for Risk Intelligence Retrieve endpoint (#12)

* Bump version, add response types, reorganize files

* wip client

* Add support for Risk Intelligence retrieve, add tests

* Call risk intelligence retrieve regardless of captcha state in example

* Simplify example in readme

* Make example print error on missing risk intelligence

* Update to Node 22.x in CI

* Add missing API error codes

Author: gzuidhof

.github/workflows/ci.yml

@@ -16,10 +16,10 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Use Node.js 18.x
+      - name: Use Node.js 22.x
         uses: actions/setup-node@v3
         with:
-          node-version: 18.x
+          node-version: 22.x
           cache: "npm"
           cache-dependency-path: "package-lock.json"
 

.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
         with:
-          node-version: '20.x'
+          node-version: '22.x'
           registry-url: 'https://registry.npmjs.org'
       - run: npm install -g npm@latest
       - run: npm ci

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0
+
+* Adds support for the Risk Intelligence Retrieve API.
+* Update dev dependencies.
+* Internal rename of `SiteverifyErrorCode` to `APIErrorCode`.
+* Rename of `VerifyClientErrorCode` to `ClientErrorCode`.
+
 ## 0.2.0
 
 * Add support for *Risk Intelligence* data in siteverify responses.

README.md

@@ -79,6 +79,34 @@ console.log(result.wasAbleToVerify()); // false
 console.log(result.shouldAccept()); // false
 ```
 
+### Retrieving Risk Intelligence
+
+You can retrieve risk intelligence data for a given token. This provides detailed information about the risk profile of a request, including network data, geolocation, browser details, and risk scores.
+
+```javascript
+const result = await frcClient.retrieveRiskIntelligence("RISK_INTELLIGENCE_TOKEN_HERE");
+
+// Check if we were able to retrieve the risk intelligence data
+if (result.wasAbleToRetrieve()) {
+  // Check if the token is valid and data was retrieved successfully
+  if (result.isValid()) {
+    const response = result.getResponse();
+    console.log("Risk Intelligence Data:", response.data);
+  } else {
+    // Token was invalid or expired
+    const error = result.getResponseError();
+    console.log("Error:", error?.error_code, error?.detail);
+  }
+} else {
+  // Network issue or configuration problem
+  if (result.isClientError()) {
+    console.log("Configuration error - check your API key");
+  } else {
+    console.log("Network issue or service temporarily unavailable");
+  }
+}
+```
+
 ### Configuration
 
 ### Configuration

etc/server-sdk.api.md

@@ -4,6 +4,9 @@
 
 ```ts
 
+// @public (undocumented)
+export type ClientErrorCode = typeof FAILED_TO_ENCODE_ERROR_CODE | typeof REQUEST_FAILED_ERROR_CODE | typeof REQUEST_FAILED_TIMEOUT_ERROR_CODE | typeof FAILED_DUE_TO_CLIENT_ERROR_CODE | typeof FAILED_TO_DECODE_RESPONSE_ERROR_CODE;
+
 // @public
 export const FAILED_DUE_TO_CLIENT_ERROR_CODE = "request_failed_due_to_client_error";
 
@@ -16,6 +19,12 @@ export const FAILED_TO_ENCODE_ERROR_CODE = "failed_to_encode_request";
 // @public
 export class FriendlyCaptchaClient {
     constructor(opts: FriendlyCaptchaOptions);
+    // @internal
+    getSiteverifyEndpoint(): string;
+    retrieveRiskIntelligence(token: string, opts?: {
+        timeout?: number;
+        sitekey?: string;
+    }): Promise<RiskIntelligenceRetrieveResult>;
     verifyCaptchaResponse(response: string, opts?: {
         timeout?: number;
         sitekey?: string;
@@ -24,10 +33,12 @@ export class FriendlyCaptchaClient {
 
 // @public
 export interface FriendlyCaptchaOptions {
+    apiEndpoint?: string;
     apiKey: string;
     fetch?: typeof globalThis.fetch;
     // (undocumented)
     sitekey?: string;
+    // @deprecated (undocumented)
     siteverifyEndpoint?: string;
     strict?: boolean;
 }
@@ -38,6 +49,76 @@ export const REQUEST_FAILED_ERROR_CODE = "request_failed";
 // @public
 export const REQUEST_FAILED_TIMEOUT_ERROR_CODE = "request_failed_due_to_timeout";
 
+// @public (undocumented)
+export interface RiskIntelligenceRetrieveErrorResponse {
+    // (undocumented)
+    error: RiskIntelligenceRetrieveErrorResponseErrorData;
+    // (undocumented)
+    success: false;
+}
+
+// @public (undocumented)
+export interface RiskIntelligenceRetrieveErrorResponseErrorData {
+    // (undocumented)
+    detail: string;
+    // Warning: (ae-forgotten-export) The symbol "APIErrorCode" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    error_code: APIErrorCode;
+}
+
+// Warning: (ae-internal-missing-underscore) The name "RiskIntelligenceRetrieveRequest" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal
+export interface RiskIntelligenceRetrieveRequest {
+    sitekey?: string;
+    token: string;
+}
+
+// @public (undocumented)
+export type RiskIntelligenceRetrieveResponse = RiskIntelligenceRetrieveSuccessResponse | RiskIntelligenceRetrieveErrorResponse;
+
+// @public
+export interface RiskIntelligenceRetrieveResponseData {
+    // (undocumented)
+    event_id: string;
+    // Warning: (ae-forgotten-export) The symbol "RiskIntelligenceData" needs to be exported by the entry point index.d.ts
+    risk_intelligence: RiskIntelligenceData;
+    token: RiskIntelligenceTokenData;
+}
+
+// @public
+export class RiskIntelligenceRetrieveResult {
+    // (undocumented)
+    clientErrorType: ClientErrorCode | null;
+    // (undocumented)
+    getResponse(): RiskIntelligenceRetrieveResponse | null;
+    // (undocumented)
+    getResponseError(): RiskIntelligenceRetrieveErrorResponseErrorData | null;
+    isClientError(): boolean;
+    // (undocumented)
+    isValid(): boolean;
+    response: RiskIntelligenceRetrieveResponse | null;
+    status: number;
+    wasAbleToRetrieve(): boolean;
+}
+
+// @public (undocumented)
+export interface RiskIntelligenceRetrieveSuccessResponse {
+    // (undocumented)
+    data: RiskIntelligenceRetrieveResponseData;
+    // (undocumented)
+    success: true;
+}
+
+// @public
+export interface RiskIntelligenceTokenData {
+    expires_at: string;
+    num_uses: number;
+    origin: string;
+    timestamp: string;
+}
+
 // @public (undocumented)
 export interface SiteverifyErrorResponse {
     // (undocumented)
@@ -50,10 +131,8 @@ export interface SiteverifyErrorResponse {
 export interface SiteverifyErrorResponseErrorData {
     // (undocumented)
     detail: string;
-    // Warning: (ae-forgotten-export) The symbol "SiteverifyErrorCode" needs to be exported by the entry point index.d.ts
-    //
     // (undocumented)
-    error_code: SiteverifyErrorCode;
+    error_code: APIErrorCode;
 }
 
 // Warning: (ae-internal-missing-underscore) The name "SiteverifyRequest" should be prefixed with an underscore because the declaration is marked as @internal
@@ -75,8 +154,9 @@ export interface SiteverifyResponseChallengeData {
 
 // @public (undocumented)
 export interface SiteverifyResponseData {
-    // (undocumented)
     challenge: SiteverifyResponseChallengeData;
+    event_id: string;
+    risk_intelligence: RiskIntelligenceData | null;
 }
 
 // @public (undocumented)
@@ -87,16 +167,16 @@ export interface SiteverifySuccessResponse {
     success: true;
 }
 
-// @public (undocumented)
-export type VerifyClientErrorCode = typeof FAILED_TO_ENCODE_ERROR_CODE | typeof REQUEST_FAILED_ERROR_CODE | typeof REQUEST_FAILED_TIMEOUT_ERROR_CODE | typeof FAILED_DUE_TO_CLIENT_ERROR_CODE | typeof FAILED_TO_DECODE_RESPONSE_ERROR_CODE;
+// @public @deprecated (undocumented)
+export type VerifyClientErrorCode = ClientErrorCode;
 
 // @public
 export class VerifyResult {
     constructor(strict: boolean);
     // (undocumented)
-    clientErrorType: VerifyClientErrorCode | null;
+    clientErrorType: ClientErrorCode | null;
     // (undocumented)
-    getErrorCode(): VerifyClientErrorCode | null;
+    getErrorCode(): ClientErrorCode | null;
     // (undocumented)
     getResponse(): SiteverifyResponse | null;
     // (undocumented)