@fingerprint/node-sdk 7.0.0-test.0

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './serverApiClient'
+export {
+  ErrorResponse,
+  Event,
+  EventRuleAction,
+  EventUpdate,
+  GetEventOptions,
+  Options,
+  Region,
+  SearchEventsFilter,
+  SearchEventsResponse,
+} from './types'
+export * from './sealedResults'
+export * from './errors/unsealError'
+export * from './webhook'
+export * from './errors/apiErrors'

package/src/sealedResults.ts

@@ -0,0 +1,94 @@
+import { createDecipheriv } from 'crypto'
+import { inflateRaw } from 'zlib'
+import { promisify } from 'util'
+import { Event } from './types'
+import { UnsealAggregateError, UnsealError } from './errors/unsealError'
+import { Buffer } from 'buffer'
+
+const asyncInflateRaw = promisify(inflateRaw)
+
+export enum DecryptionAlgorithm {
+  Aes256Gcm = 'aes-256-gcm',
+}
+
+export interface DecryptionKey {
+  key: Buffer
+  algorithm: DecryptionAlgorithm | `${DecryptionAlgorithm}`
+}
+
+const SEALED_HEADER = Buffer.from([0x9e, 0x85, 0xdc, 0xed])
+
+function isEventResponse(data: unknown): data is Event {
+  return Boolean(data && typeof data === 'object' && 'event_id' in data && 'timestamp' in data)
+}
+
+/**
+ * @private
+ * */
+export function parseEventsResponse(unsealed: string): Event {
+  const json = JSON.parse(unsealed)
+
+  if (!isEventResponse(json)) {
+    throw new Error('Sealed data is not valid events response')
+  }
+
+  return json
+}
+
+/**
+ * Decrypts the sealed response with the provided keys.
+ * The SDK will try to decrypt the result with each key until it succeeds.
+ * To learn more about sealed results visit: https://dev.fingerprint.com/docs/sealed-client-results
+ * @throws UnsealAggregateError
+ * @throws Error
+ */
+export async function unsealEventsResponse(sealedData: Buffer, decryptionKeys: DecryptionKey[]): Promise<Event> {
+  const unsealed = await unseal(sealedData, decryptionKeys)
+
+  return parseEventsResponse(unsealed)
+}
+
+/**
+ * @private
+ * */
+export async function unseal(sealedData: Buffer, decryptionKeys: DecryptionKey[]) {
+  if (sealedData.subarray(0, SEALED_HEADER.length).toString('hex') !== SEALED_HEADER.toString('hex')) {
+    throw new Error('Invalid sealed data header')
+  }
+
+  const errors = new UnsealAggregateError([])
+
+  for (const decryptionKey of decryptionKeys) {
+    switch (decryptionKey.algorithm) {
+      case DecryptionAlgorithm.Aes256Gcm:
+        try {
+          return await unsealAes256Gcm(sealedData, decryptionKey.key)
+        } catch (e) {
+          errors.addError(new UnsealError(decryptionKey, e as Error))
+          continue
+        }
+
+      default:
+        throw new Error(`Unsupported decryption algorithm: ${decryptionKey.algorithm}`)
+    }
+  }
+
+  throw errors
+}
+
+async function unsealAes256Gcm(sealedData: Buffer, decryptionKey: Buffer) {
+  const nonceLength = 12
+  const nonce = sealedData.subarray(SEALED_HEADER.length, SEALED_HEADER.length + nonceLength)
+
+  const authTagLength = 16
+  const authTag = sealedData.subarray(-authTagLength)
+
+  const ciphertext = sealedData.subarray(SEALED_HEADER.length + nonceLength, -authTagLength)
+
+  const decipher = createDecipheriv('aes-256-gcm', decryptionKey, nonce).setAuthTag(authTag)
+  const compressed = Buffer.concat([decipher.update(ciphertext), decipher.final()])
+
+  const payload = await asyncInflateRaw(compressed)
+
+  return payload.toString()
+}

package/src/serverApiClient.ts

@@ -0,0 +1,321 @@
+import { AllowedMethod, getRequestPath, GetRequestPathOptions, SuccessJsonOrVoid } from './urlUtils'
+import {
+  Event,
+  EventUpdate,
+  FingerprintApi,
+  GetEventOptions,
+  Options,
+  Region,
+  SearchEventsFilter,
+  SearchEventsResponse,
+} from './types'
+import { paths } from './generatedApiTypes'
+import { RequestError, SdkError, TooManyRequestsError } from './errors/apiErrors'
+import { isErrorResponse } from './errors/handleErrorResponse'
+import { toError } from './errors/toError'
+
+export class FingerprintServerApiClient implements FingerprintApi {
+  public readonly region: Region
+
+  public readonly apiKey: string
+
+  protected readonly fetch: typeof fetch
+
+  private readonly defaultHeaders: Record<string, string>
+
+  /**
+   * FingerprintJS server API client used to fetch data from FingerprintJS
+   * @constructor
+   * @param {Options} options - Options for FingerprintJS server API client
+   */
+  constructor(options: Readonly<Options>) {
+    if (!options.apiKey) {
+      throw Error('Api key is not set')
+    }
+
+    // These type assertions are safe because the Options type allows the
+    // region or authentication mode to be specified as a string or an enum value.
+    // The resulting JS from using the enum value or the string is identical.
+    this.region = (options.region as Region) ?? Region.Global
+
+    this.apiKey = options.apiKey
+    this.fetch = options.fetch ?? fetch
+
+    this.defaultHeaders = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...options.defaultHeaders,
+    }
+  }
+
+  /**
+   * Retrieves a specific identification event with the information from each activated product — Identification and all active [Smart signals](https://dev.fingerprint.com/docs/smart-signals-overview).
+   *
+   * @param eventId - identifier of the event
+   * @param {object|undefined} options - Optional `getEvent` operation options
+   * @param {string|undefined} options.ruleset_id - Optional ruleset ID to evaluate against the event
+   *
+   * @returns {Promise<Event>} - promise with event response. For more information, see the [Server API documentation](https://dev.fingerprint.com/reference/getevent).
+   *
+   * @example
+   * ```javascript Handling an event
+   * client
+   *  .getEvent('<eventId>')
+   *  .then((event) => console.log(event))
+   *  .catch((error) => {
+   *    if (error instanceof RequestError) {
+   *       console.log(error.statusCode, error.message)
+   *       // Access raw response in error
+   *       console.log(error.response)
+   *     }
+   *   })
+   * ```
+   *
+   * @example Handling an event with rule_action
+   * ```javascript
+   * client
+   *  .getEvent('<eventId>', { ruleset_id: '<rulesetId>' })
+   *  .then((event) => {
+   *    const ruleAction = event.rule_action
+   *    if (ruleAction?.type === 'block') {
+   *      console.log('Blocked by rule:', ruleAction.rule_id, ruleAction.status_code)
+   *    }
+   *  })
+   *  .catch((error) => {
+   *    if (error instanceof RequestError) {
+   *      console.log(error.statusCode, error.message)
+   *    }
+   *  })
+   * ```
+   * */
+  public async getEvent(eventId: string, options?: GetEventOptions): Promise<Event> {
+    if (!eventId) {
+      throw new TypeError('eventId is not set')
+    }
+
+    return this.callApi({
+      path: '/events/{event_id}',
+      pathParams: [eventId],
+      method: 'get',
+      queryParams: options,
+    })
+  }
+
+  /**
+   * Update an event with a given event ID
+   * @description Change information in existing events specified by `eventId` or *flag suspicious events*.
+   *
+   * When an event is created, it is assigned `linkedId` and `tag` submitted through the JS agent parameters. This information might not be available on the client so the Server API allows for updating the attributes after the fact.
+   *
+   * **Warning** It's not possible to update events older than one month.
+   *
+   * @param body - Data to update the event with.
+   * @param eventId The unique event [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id).
+   *
+   * @return {Promise<void>}
+   *
+   * @example
+   * ```javascript
+   * const body = {
+   *  linked_id: 'linked_id',
+   *  suspect: false,
+   * }
+   *
+   * client
+   *   .updateEvent(body, '<eventId>')
+   *   .then(() => {
+   *     // Event was successfully updated
+   *   })
+   *  .catch((error) => {
+   *    if (error instanceof RequestError) {
+   *       console.log(error.statusCode, error.message)
+   *       // Access raw response in error
+   *       console.log(error.response)
+   *
+   *       if(error.statusCode === 409) {
+   *          // Event is not mutable yet, wait a couple of seconds and retry the update.
+   *       }
+   *     }
+   *   })
+   * ```
+   */
+  public async updateEvent(body: EventUpdate, eventId: string): Promise<void> {
+    if (!body) {
+      throw new TypeError('body is not set')
+    }
+
+    if (!eventId) {
+      throw new TypeError('eventId is not set')
+    }
+
+    return this.callApi({
+      path: '/events/{event_id}',
+      pathParams: [eventId],
+      method: 'patch',
+      body: JSON.stringify(body),
+    })
+  }
+
+  /**
+   * Delete data by visitor ID
+   * Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. All delete requests are queued:
+   * Recent data (10 days or newer) belonging to the specified visitor will be deleted within 24 hours. * Data from older (11 days or more) identification events  will be deleted after 90 days.
+   * If you are interested in using this API, please [contact our support team](https://fingerprint.com/support/) to activate it for you. Otherwise, you will receive a 403.
+   *
+   * @param visitorId The [visitor ID](https://dev.fingerprint.com/docs/js-agent#visitorid) you want to delete.*
+   *
+   * @return {Promise<void>} Promise that resolves when the deletion request is successfully queued
+   *
+   * @example
+   * ```javascript
+   * client
+   *   .deleteVisitorData('<visitorId>')
+   *   .then(() => {
+   *     // Data deletion request was successfully queued
+   *   })
+   *  .catch((error) => {
+   *    if (error instanceof RequestError) {
+   *       console.log(error.statusCode, error.message)
+   *       // Access raw response in error
+   *       console.log(error.response)
+   *     }
+   *   })
+   * ```
+   */
+  public async deleteVisitorData(visitorId: string): Promise<void> {
+    if (!visitorId) {
+      throw new TypeError('visitorId is not set')
+    }
+
+    return this.callApi({
+      path: '/visitors/{visitor_id}',
+      pathParams: [visitorId],
+      method: 'delete',
+    })
+  }
+
+  /**
+   * Search for identification events, including Smart Signals, using
+   * multiple filtering criteria. If you don't provide `start` or `end`
+   * parameters, the default search range is the last 7 days.
+   *
+   * Please note that events include mobile signals (e.g. `rootApps`) even if
+   * the request originated from a non-mobile platform. We recommend you
+   * **ignore** mobile signals for such requests.
+   *
+   * @param {SearchEventsFilter} filter - Events filter
+   * @param {number} filter.limit - Limit the number of events returned. Must be greater than 0.
+   * @param {string|undefined} filter.pagination_key - Use `pagination_key` to get the next page of results.
+   * @param {string|undefined} filter.visitor_id - Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Identification. Filter for events matching this `visitor_id`.
+   * @param {string|undefined} filter.bot - Filter events by the bot detection result, specifically:
+   *             - events where any kind of bot was detected.
+   *             - events where a good bot was detected.
+   *             - events where a bad bot was detected.
+   *             - events where no bot was detected.
+   *
+   *             Allowed values: `all`, `good`, `bad`, `none`.
+   * @param {string|undefined} filter.ip_address - Filter events by IP address range. The range can be as specific as a
+   *             single IP (/32 for IPv4 or /128 for IPv6).
+   *             All ip_address filters must use CIDR notation, for example,
+   *             10.0.0.0/24, 192.168.0.1/32
+   * @param {string|undefined} filter.linked_id - Filter events by your custom identifier.
+   *             You can use [linked IDs](https://dev.fingerprint.com/reference/get-function#linkedid) to
+   *             associate identification requests with your own identifier, for
+   *             example, session ID, purchase ID, or transaction ID. You can then
+   *             use this `linked_id` parameter to retrieve all events associated
+   *             with your custom identifier.
+   * @param {string|undefined} filter.url - Filter events by the URL (`url` property) associated with the event.
+   * @param {string|undefined} filter.origin - Filter events by the origin field of the event. Origin could be the website domain or mobile app bundle ID (eg: com.foo.bar)
+   * @param {number|undefined} filter.start - Filter events with a timestamp greater than the start time, in Unix time (milliseconds).
+   * @param {number|undefined} filter.end - Filter events with a timestamp smaller than the end time, in Unix time (milliseconds).
+   * @param {boolean|undefined} filter.reverse - Sort events in reverse timestamp order.
+   * @param {boolean|undefined} filter.suspect - Filter events previously tagged as suspicious via the [Update API](https://dev.fingerprint.com/reference/updateevent).
+   * @param {boolean|undefined} filter.vpn - Filter events by VPN Detection result.
+   * @param {boolean|undefined} filter.virtual_machine - Filter events by Virtual Machine Detection result.
+   * @param {boolean|undefined} filter.tampering - Filter events by Browser Tampering Detection result.
+   * @param {boolean|undefined} filter.anti_detect_browser - Filter events by Anti-detect Browser Detection result.
+   * @param {boolean|undefined} filter.incognito - Filter events by Browser Incognito Detection result.
+   * @param {boolean|undefined} filter.privacy_settings - Filter events by Privacy Settings Detection result.
+   * @param {boolean|undefined} filter.jailbroken - Filter events by Jailbroken Device Detection result.
+   * @param {boolean|undefined} filter.frida - Filter events by Frida Detection result.
+   * @param {boolean|undefined} filter.factory_reset - Filter events by Factory Reset Detection result.
+   * @param {boolean|undefined} filter.cloned_app - Filter events by Cloned App Detection result.
+   * @param {boolean|undefined} filter.emulator - Filter events by Android Emulator Detection result.
+   * @param {boolean|undefined} filter.root_apps - Filter events by Rooted Device Detection result.
+   * @param {'high'|'medium'|'low'|undefined} filter.vpn_confidence - Filter events by VPN Detection result confidence level.
+   * @param {number|undefined} filter.min_suspect_score - Filter events with Suspect Score result above a provided minimum threshold.
+   * @param {boolean|undefined} filter.developer_tools - Filter events by Developer Tools detection result.
+   * @param {boolean|undefined} filter.location_spoofing - Filter events by Location Spoofing detection result.
+   * @param {boolean|undefined} filter.mitm_attack - Filter events by MITM (Man-in-the-Middle) Attack detection result.
+   * @param {boolean|undefined} filter.proxy - Filter events by Proxy detection result.
+   * @param {string|undefined} filter.sdk_version - Filter events by a specific SDK version associated with the identification event (`sdk.version` property).
+   * @param {string|undefined} filter.sdk_platform - Filter events by the SDK Platform associated with the identification event (`sdk.platform` property).
+   * @param {string[]|undefined} filter.environment - Filter for events by providing one or more environment IDs (`environment_id` property).
+   * */
+  async searchEvents(filter: SearchEventsFilter): Promise<SearchEventsResponse> {
+    return this.callApi({
+      path: '/events',
+      method: 'get',
+      queryParams: filter,
+    })
+  }
+
+  private async callApi<Path extends keyof paths, Method extends AllowedMethod<Path>>(
+    options: GetRequestPathOptions<Path, Method> & { headers?: Record<string, string>; body?: BodyInit }
+  ): Promise<SuccessJsonOrVoid<Path, Method>> {
+    const url = getRequestPath({
+      ...options,
+      region: this.region,
+    })
+
+    let response: Response
+    try {
+      response = await this.fetch(url, {
+        method: options.method.toUpperCase(),
+        headers: {
+          ...this.defaultHeaders,
+          ...options.headers,
+        },
+        body: options.body,
+      })
+    } catch (e) {
+      throw new SdkError('Network or fetch error', undefined, e as Error)
+    }
+
+    const contentType = response.headers.get('content-type') ?? ''
+    const isJson = contentType.includes('application/json')
+
+    if (response.ok) {
+      const hasNoBody = response.status === 204 || response.headers.get('content-length') === '0'
+
+      if (hasNoBody) {
+        return undefined as SuccessJsonOrVoid<Path, Method>
+      }
+
+      if (!isJson) {
+        throw new SdkError('Expected JSON response but received non-JSON content type', response)
+      }
+
+      let data
+      try {
+        data = await response.clone().json()
+      } catch (e) {
+        throw new SdkError('Failed to parse JSON response', response, toError(e))
+      }
+      return data as SuccessJsonOrVoid<Path, Method>
+    }
+
+    let errPayload
+    try {
+      errPayload = await response.clone().json()
+    } catch (e) {
+      throw new SdkError('Failed to parse JSON response', response, toError(e))
+    }
+    if (isErrorResponse(errPayload)) {
+      if (response.status === 429) {
+        throw new TooManyRequestsError(errPayload, response)
+      }
+      throw new RequestError(errPayload.error.message, errPayload, response.status, errPayload.error.code, response)
+    }
+    throw RequestError.unknown(response)
+  }
+}

package/src/types.ts

@@ -0,0 +1,90 @@
+import { components, operations, paths } from './generatedApiTypes'
+
+export enum Region {
+  EU = 'EU',
+  AP = 'AP',
+  Global = 'Global',
+}
+
+/**
+ * Options for FingerprintJS server API client
+ */
+export interface Options {
+  /**
+   * Secret API key
+   */
+  apiKey: string
+  /**
+   * Region of the FingerprintJS service server
+   */
+  region?: Region | `${Region}`
+
+  /**
+   * Optional fetch implementation
+   * */
+  fetch?: typeof fetch
+
+  /**
+   * Optional default headers
+   */
+  defaultHeaders?: Record<string, string>
+}
+
+export type ErrorResponse = components['schemas']['ErrorResponse']
+
+/**
+ * More info: https://dev.fingerprintjs.com/docs/server-api#query-parameters
+ */
+export type SearchEventsFilter = paths['/events']['get']['parameters']['query']
+export type SearchEventsResponse = components['schemas']['EventSearch']
+
+/**
+ * More info: https://dev.fingerprint.com/reference/server-api-v4-get-event
+ */
+export type Event = components['schemas']['Event']
+
+export type GetEventOptions = paths['/events/{event_id}']['get']['parameters']['query']
+
+export type EventUpdate = components['schemas']['EventUpdate']
+
+export type EventRuleAction = components['schemas']['EventRuleAction']
+
+// Extract just the `path` parameters as a tuple of strings
+type ExtractPathParamStrings<Path> = Path extends { parameters: { path: infer P } }
+  ? P extends Record<string, any>
+    ? [P[keyof P]] // We extract the path parameter values as a tuple of strings
+    : []
+  : []
+
+// Utility type to extract query parameters from an operation and differentiate required/optional
+export type ExtractQueryParams<Path> = Path extends { parameters: { query?: infer Q } }
+  ? undefined extends Q // Check if Q can be undefined (meaning it's optional)
+    ? Q | undefined // If so, it's optional
+    : Q // Otherwise, it's required
+  : never // If no query parameters, return never
+
+// Utility type to extract request body from an operation (for POST, PUT, etc.)
+type ExtractRequestBody<Path> = Path extends { requestBody: { content: { 'application/json': infer B } } } ? B : never
+
+// Utility type to extract the response type for 200 status code
+type ExtractResponse<Path> = Path extends { responses: { 200: { content: { 'application/json': infer R } } } }
+  ? R
+  : void
+
+// Extracts args to given API method
+type ApiMethodArgs<Path extends keyof operations> = [
+  // If method has body, extract it as first parameter
+  ...(ExtractRequestBody<operations[Path]> extends never ? [] : [body: ExtractRequestBody<operations[Path]>]),
+  // Next are path params, e.g. for path "/events/{event_id}" it will be one string parameter,
+  ...ExtractPathParamStrings<operations[Path]>,
+  // Last parameter will be the query params, if any
+  ...(ExtractQueryParams<operations[Path]> extends never ? [] : [params: ExtractQueryParams<operations[Path]>]),
+]
+
+type ApiMethod<Path extends keyof operations> = (
+  ...args: ApiMethodArgs<Path>
+) => Promise<ExtractResponse<operations[Path]>>
+
+export type FingerprintApi = {
+  [Operation in keyof operations]: ApiMethod<Operation>
+}

package/src/urlUtils.ts

@@ -0,0 +1,171 @@
+import { ExtractQueryParams, Region } from './types'
+import { version } from '../package.json'
+import { paths } from './generatedApiTypes'
+
+const apiVersion = 'v4'
+
+const euRegionUrl = 'https://eu.api.fpjs.io/'
+const apRegionUrl = 'https://ap.api.fpjs.io/'
+const globalRegionUrl = 'https://api.fpjs.io/'
+
+type QueryStringScalar = string | number | boolean | null | undefined
+
+type QueryStringParameters = Record<string, QueryStringScalar | string[]> & {
+  api_key?: string
+  ii: string
+}
+
+export function getIntegrationInfo() {
+  return `fingerprint-pro-server-node-sdk/${version}`
+}
+
+function serializeQueryStringParams(params: QueryStringParameters): string {
+  const entries: [string, string][] = []
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null) {
+      continue
+    }
+
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        if (v == null) {
+          continue
+        }
+        entries.push([key, String(v)])
+      }
+    } else {
+      entries.push([key, String(value)])
+    }
+  }
+
+  const urlSearchParams = new URLSearchParams(entries)
+
+  return urlSearchParams.toString()
+}
+
+function getServerApiUrl(region: Region): string {
+  switch (region) {
+    case Region.EU:
+      return euRegionUrl
+    case Region.AP:
+      return apRegionUrl
+    case Region.Global:
+      return globalRegionUrl
+    default:
+      throw new Error('Unsupported region')
+  }
+}
+
+/**
+ * Extracts parameter placeholders into a literal union type.
+ * For example `extractPathParams<'/users/{userId}/posts/{postId}'>` resolves to `"userId" | "postId"
+ */
+type ExtractPathParams<T extends string> = T extends `${string}{${infer Param}}${infer Rest}`
+  ? Param | ExtractPathParams<Rest>
+  : never
+
+type PathParams<Path extends keyof paths> =
+  ExtractPathParams<Path> extends never
+    ? { pathParams?: never }
+    : {
+        pathParams: ExtractPathParams<Path> extends never ? never : string[]
+      }
+
+type QueryParams<Path extends keyof paths, Method extends keyof paths[Path]> =
+  ExtractQueryParams<paths[Path][Method]> extends never
+    ? { queryParams?: any } // No query params
+    : {
+        queryParams?: ExtractQueryParams<paths[Path][Method]> // Optional query params
+      }
+
+type IsNever<Type> = [Exclude<Type, undefined>] extends [never] ? true : false
+export type NonNeverKeys<Type> = {
+  [Key in keyof Type]-?: IsNever<Type[Key]> extends true ? never : Key
+}[keyof Type]
+export type AllowedMethod<Path extends keyof paths> = Extract<Exclude<NonNeverKeys<paths[Path]>, 'parameters'>, string>
+
+type JsonContentOf<Response> = Response extends { content: { 'application/json': infer T } } ? T : never
+
+type UnionJsonFromResponses<Response> = {
+  [StatusCode in keyof Response]: JsonContentOf<Response[StatusCode]>
+}[keyof Response]
+
+type StartingWithSuccessCode<Response> = {
+  [StatusCode in keyof Response]: `${StatusCode & number}` extends `2${number}${number}` ? StatusCode : never
+}[keyof Response]
+
+type SuccessResponses<Response> = Pick<Response, Extract<StartingWithSuccessCode<Response>, keyof Response>>
+
+type OperationOf<Path extends keyof paths, Method extends AllowedMethod<Path>> = paths[Path][Method]
+
+type ResponsesOf<Path extends keyof paths, Method extends AllowedMethod<Path>> =
+  OperationOf<Path, Method> extends { responses: infer Response } ? Response : never
+
+type SuccessJson<Path extends keyof paths, Method extends AllowedMethod<Path>> = UnionJsonFromResponses<
+  SuccessResponses<ResponsesOf<Path, Method>>
+>
+
+export type SuccessJsonOrVoid<Path extends keyof paths, Method extends AllowedMethod<Path>> = [
+  SuccessJson<Path, Method>,
+] extends [never]
+  ? void
+  : SuccessJson<Path, Method>
+
+export type GetRequestPathOptions<Path extends keyof paths, Method extends AllowedMethod<Path>> = {
+  path: Path
+  method: Method
+  region?: Region
+} & PathParams<Path> &
+  QueryParams<Path, Method>
+
+/**
+ * Formats a URL for the FingerprintJS server API by replacing placeholders and
+ * appending query string parameters.
+ *
+ * @internal
+ *
+ * @param {GetRequestPathOptions<Path, Method>} options
+ * @param {Path} options.path - The path of the API endpoint
+ * @param {string[]} [options.pathParams] - Path parameters to be replaced in the path
+ * @param {QueryParams<Path, Method>["queryParams"]} [options.queryParams] - Query string
+ *   parameters to be appended to the URL
+ * @param {Region} options.region - The region of the API endpoint
+ * @param {Method} options.method - The method of the API endpoint
+ *
+ * @returns {string} The formatted URL with parameters replaced and query string
+ *   parameters appended
+ */
+export function getRequestPath<Path extends keyof paths, Method extends AllowedMethod<Path>>({
+  path,
+  pathParams,
+  queryParams,
+  region,
+  // method mention here so that it can be referenced in JSDoc
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  method: _,
+}: GetRequestPathOptions<Path, Method>): string {
+  // Step 1: Extract the path parameters (placeholders) from the path
+  const placeholders = Array.from(path.matchAll(/{(.*?)}/g)).map((match) => match[1])
+
+  // Step 2: Replace the placeholders with provided pathParams
+  let formattedPath: string = `${apiVersion}${path}`
+  placeholders.forEach((placeholder, index) => {
+    if (pathParams?.[index]) {
+      formattedPath = formattedPath.replace(`{${placeholder}}`, pathParams[index])
+    } else {
+      throw new Error(`Missing path parameter for ${placeholder}`)
+    }
+  })
+
+  const queryStringParameters: QueryStringParameters = {
+    ...(queryParams ?? {}),
+    ii: getIntegrationInfo(),
+  }
+
+  const url = new URL(getServerApiUrl(region ?? Region.Global))
+  url.pathname = formattedPath
+  url.search = serializeQueryStringParams(queryStringParameters)
+
+  return url.toString()
+}