@fingerprint/node-sdk 7.0.0-test.0

package/.npmignore

@@ -0,0 +1,9 @@
+# Ignore everything
+*
+
+# Recursively allow files under subtree
+!dist/**
+!src/**
+!package.json
+!.npmignore
+!README.md

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2021 FingerprintJS, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,598 @@
+/**
+ * Fingerprint Server Node.js SDK v7.0.0-test.0 - Copyright (c) FingerprintJS, Inc, 2026 (https://fingerprint.com)
+ * Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) license.
+ */
+
+'use strict';
+
+var crypto = require('crypto');
+var zlib = require('zlib');
+var util = require('util');
+var buffer = require('buffer');
+
+exports.Region = void 0;
+(function (Region) {
+    Region["EU"] = "EU";
+    Region["AP"] = "AP";
+    Region["Global"] = "Global";
+})(exports.Region || (exports.Region = {}));
+
+var version = "7.0.0-test.0";
+
+const apiVersion = 'v4';
+const euRegionUrl = 'https://eu.api.fpjs.io/';
+const apRegionUrl = 'https://ap.api.fpjs.io/';
+const globalRegionUrl = 'https://api.fpjs.io/';
+function getIntegrationInfo() {
+    return `fingerprint-pro-server-node-sdk/${version}`;
+}
+function serializeQueryStringParams(params) {
+    const entries = [];
+    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) {
+    switch (region) {
+        case exports.Region.EU:
+            return euRegionUrl;
+        case exports.Region.AP:
+            return apRegionUrl;
+        case exports.Region.Global:
+            return globalRegionUrl;
+        default:
+            throw new Error('Unsupported region');
+    }
+}
+/**
+ * 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
+ */
+function getRequestPath({ 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: _, }) {
+    // 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 = `${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 = {
+        ...(queryParams ?? {}),
+        ii: getIntegrationInfo(),
+    };
+    const url = new URL(getServerApiUrl(region ?? exports.Region.Global));
+    url.pathname = formattedPath;
+    url.search = serializeQueryStringParams(queryStringParameters);
+    return url.toString();
+}
+
+class SdkError extends Error {
+    response;
+    constructor(message, response, cause) {
+        super(message, { cause });
+        this.response = response;
+        this.name = this.constructor.name;
+    }
+}
+class RequestError extends SdkError {
+    // HTTP Status code
+    statusCode;
+    // API error code
+    errorCode;
+    // API error response
+    responseBody;
+    // Raw HTTP response
+    response;
+    constructor(message, body, statusCode, errorCode, response) {
+        super(message, response);
+        this.responseBody = body;
+        this.response = response;
+        this.errorCode = errorCode;
+        this.statusCode = statusCode;
+    }
+    static unknown(response) {
+        return new RequestError('Unknown error', undefined, response.status, response.statusText, response);
+    }
+    static fromErrorResponse(body, response) {
+        return new RequestError(body.error.message, body, response.status, body.error.code, response);
+    }
+}
+/**
+ * Error that indicate that the request was throttled.
+ * */
+class TooManyRequestsError extends RequestError {
+    constructor(body, response) {
+        super(body.error.message, body, 429, body.error.code, response);
+    }
+}
+
+function isErrorResponse(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        'error' in value &&
+        typeof value.error === 'object' &&
+        value.error &&
+        'code' in value.error &&
+        'message' in value.error);
+}
+
+function toError(e) {
+    if (e && typeof e === 'object' && 'message' in e) {
+        return e;
+    }
+    return new Error(String(e));
+}
+
+class FingerprintServerApiClient {
+    region;
+    apiKey;
+    fetch;
+    defaultHeaders;
+    /**
+     * FingerprintJS server API client used to fetch data from FingerprintJS
+     * @constructor
+     * @param {Options} options - Options for FingerprintJS server API client
+     */
+    constructor(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 ?? exports.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)
+     *    }
+     *  })
+     * ```
+     * */
+    async getEvent(eventId, options) {
+        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.
+     *       }
+     *     }
+     *   })
+     * ```
+     */
+    async updateEvent(body, eventId) {
+        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)
+     *     }
+     *   })
+     * ```
+     */
+    async deleteVisitorData(visitorId) {
+        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) {
+        return this.callApi({
+            path: '/events',
+            method: 'get',
+            queryParams: filter,
+        });
+    }
+    async callApi(options) {
+        const url = getRequestPath({
+            ...options,
+            region: this.region,
+        });
+        let 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);
+        }
+        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;
+            }
+            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;
+        }
+        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);
+    }
+}
+
+class UnsealError extends Error {
+    key;
+    error;
+    constructor(key, error) {
+        let msg = `Unable to decrypt sealed data`;
+        if (error) {
+            msg = msg.concat(`: ${error.message}`);
+        }
+        super(msg);
+        this.key = key;
+        this.error = error;
+        this.name = 'UnsealError';
+    }
+}
+class UnsealAggregateError extends Error {
+    errors;
+    constructor(errors) {
+        super('Unable to decrypt sealed data');
+        this.errors = errors;
+        this.name = 'UnsealAggregateError';
+    }
+    addError(error) {
+        this.errors.push(error);
+    }
+    toString() {
+        return this.errors.map((e) => e.toString()).join('\n');
+    }
+}
+
+const asyncInflateRaw = util.promisify(zlib.inflateRaw);
+exports.DecryptionAlgorithm = void 0;
+(function (DecryptionAlgorithm) {
+    DecryptionAlgorithm["Aes256Gcm"] = "aes-256-gcm";
+})(exports.DecryptionAlgorithm || (exports.DecryptionAlgorithm = {}));
+const SEALED_HEADER = buffer.Buffer.from([0x9e, 0x85, 0xdc, 0xed]);
+function isEventResponse(data) {
+    return Boolean(data && typeof data === 'object' && 'event_id' in data && 'timestamp' in data);
+}
+/**
+ * @private
+ * */
+function parseEventsResponse(unsealed) {
+    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
+ */
+async function unsealEventsResponse(sealedData, decryptionKeys) {
+    const unsealed = await unseal(sealedData, decryptionKeys);
+    return parseEventsResponse(unsealed);
+}
+/**
+ * @private
+ * */
+async function unseal(sealedData, decryptionKeys) {
+    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 exports.DecryptionAlgorithm.Aes256Gcm:
+                try {
+                    return await unsealAes256Gcm(sealedData, decryptionKey.key);
+                }
+                catch (e) {
+                    errors.addError(new UnsealError(decryptionKey, e));
+                    continue;
+                }
+            default:
+                throw new Error(`Unsupported decryption algorithm: ${decryptionKey.algorithm}`);
+        }
+    }
+    throw errors;
+}
+async function unsealAes256Gcm(sealedData, decryptionKey) {
+    const nonceLength = 12;
+    const nonce = sealedData.subarray(SEALED_HEADER.length, SEALED_HEADER.length + nonceLength);
+    const authTag = sealedData.subarray(-16);
+    const ciphertext = sealedData.subarray(SEALED_HEADER.length + nonceLength, -16);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', decryptionKey, nonce).setAuthTag(authTag);
+    const compressed = buffer.Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    const payload = await asyncInflateRaw(compressed);
+    return payload.toString();
+}
+
+function isValidHmacSignature(signature, data, secret) {
+    return signature === crypto.createHmac('sha256', secret).update(data).digest('hex');
+}
+/**
+ * Verifies the HMAC signature extracted from the "fpjs-event-signature" header of the incoming request. This is a part of the webhook signing process, which is available only for enterprise customers.
+ * If you wish to enable it, please contact our support: https://fingerprint.com/support
+ *
+ * @param {IsValidWebhookSignatureParams} params
+ * @param {string} params.header - The value of the "fpjs-event-signature" header.
+ * @param {Buffer} params.data - The raw data of the incoming request.
+ * @param {string} params.secret - The secret key used to sign the request.
+ *
+ * @return {boolean} true if the signature is valid, false otherwise.
+ *
+ * @example
+ * ```javascript
+ * // Webhook endpoint handler
+ * export async function POST(request: Request) {
+ *   try {
+ *     const secret = process.env.WEBHOOK_SIGNATURE_SECRET;
+ *     const header = request.headers.get("fpjs-event-signature");
+ *     const data = Buffer.from(await request.arrayBuffer());
+ *
+ *     if (!isValidWebhookSignature({ header, data, secret })) {
+ *       return Response.json(
+ *         { message: "Webhook signature is invalid." },
+ *         { status: 403 },
+ *       );
+ *     }
+ *
+ *     return Response.json({ message: "Webhook received." });
+ *   } catch (error) {
+ *     return Response.json({ error }, { status: 500 });
+ *   }
+ * }
+ * ```
+ */
+function isValidWebhookSignature(params) {
+    const { header, data, secret } = params;
+    const signatures = header.split(',');
+    for (const signature of signatures) {
+        const [version, hash] = signature.split('=');
+        if (version === 'v1' && isValidHmacSignature(hash, data, secret)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+exports.FingerprintServerApiClient = FingerprintServerApiClient;
+exports.RequestError = RequestError;
+exports.SdkError = SdkError;
+exports.TooManyRequestsError = TooManyRequestsError;
+exports.UnsealAggregateError = UnsealAggregateError;
+exports.UnsealError = UnsealError;
+exports.isValidWebhookSignature = isValidWebhookSignature;
+exports.parseEventsResponse = parseEventsResponse;
+exports.unseal = unseal;
+exports.unsealEventsResponse = unsealEventsResponse;