{"id":19167162,"url":"https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk","last_synced_at":"2025-04-07T07:03:02.334Z","repository":{"id":40247879,"uuid":"387000645","full_name":"fingerprintjs/fingerprintjs-pro-server-api-node-sdk","owner":"fingerprintjs","description":"Node.js wrapper for FingerprintJS Server API ","archived":false,"fork":false,"pushed_at":"2025-04-02T13:31:35.000Z","size":2122,"stargazers_count":23,"open_issues_count":6,"forks_count":7,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-02T23:55:44.920Z","etag":null,"topics":["api-wrapper","audio-fingerprinting","browser","browser-fingerprint","browser-fingerprinting","detection","fingerprint","fingerprinting","fingerprintjs","fingerprintjs-pro","fraud","fraud-detection","identification","javascript","nodejs","nodejs-server","visitor-identification"],"latest_commit_sha":null,"homepage":"https://dev.fingerprintjs.com/docs/server-api","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fingerprintjs.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-17T17:30:54.000Z","updated_at":"2025-04-02T13:12:11.000Z","dependencies_parsed_at":"2024-01-31T07:35:28.792Z","dependency_job_id":"ee36e50d-c1b1-4297-889c-075e3f1e37b1","html_url":"https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk","commit_stats":{"total_commits":189,"total_committers":8,"mean_commits":23.625,"dds":0.6507936507936508,"last_synced_commit":"2c5e999ec11886f36168bc1f311564fdbfa2b1b4"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fingerprintjs","download_url":"https://codeload.github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608150,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","audio-fingerprinting","browser","browser-fingerprint","browser-fingerprinting","detection","fingerprint","fingerprinting","fingerprintjs","fingerprintjs-pro","fraud","fraud-detection","identification","javascript","nodejs","nodejs-server","visitor-identification"],"created_at":"2024-11-09T09:36:01.236Z","updated_at":"2025-04-07T07:03:02.297Z","avatar_url":"https://github.com/fingerprintjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://fingerprint.com\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://fingerprintjs.github.io/home/resources/logo_light.svg\" /\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://fingerprintjs.github.io/home/resources/logo_dark.svg\" /\u003e\n      \u003cimg src=\"https://fingerprintjs.github.io/home/resources/logo_dark.svg\" alt=\"Fingerprint logo\" width=\"312px\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/actions/workflows/build.yml\"\u003e\u003cimg src=\"https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/actions/workflows/build.yml/badge.svg\" alt=\"Build status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://fingerprintjs.github.io/fingerprintjs-pro-server-api-node-sdk/coverage\"\u003e\u003cimg src=\"https://fingerprintjs.github.io/fingerprintjs-pro-server-api-node-sdk/coverage/badges.svg\" alt=\"coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-server-api\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@fingerprintjs/fingerprintjs-pro-server-api.svg\" alt=\"Current NPM version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-server-api\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@fingerprintjs/fingerprintjs-pro-server-api.svg\" alt=\"Monthly downloads from NPM\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/39EpE2neBg\"\u003e\u003cimg src=\"https://img.shields.io/discord/852099967190433792?style=logo\u0026label=Discord\u0026logo=Discord\u0026logoColor=white\" alt=\"Discord server\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Fingerprint Server API Node.js SDK\n\n[Fingerprint](https://fingerprint.com) is a device intelligence platform offering 99.5% accurate visitor identification.\n\nThe Fingerprint Server Node SDK is an easy way to interact with the Fingerprint [Server API](https://dev.fingerprint.com/reference/pro-server-api) from your Node application. You can retrieve visitor history or individual identification events.\n\n## Requirements\n\nTypeScript support:\n\n- TypeScript 4.5.5 or higher\n\nSupported runtimes:\n\n- Node.js 18 LTS or higher (we support all [Node LTS releases before end-of-life](https://nodejs.dev/en/about/releases/)).\n- Deno and Bun might work but are not actively tested.\n- \"Edge\" runtimes might work with some modifications but are not actively tested. \u003cdetails\u003e\n  \u003csummary\u003eSee \"edge\" runtimes compatibility\u003c/summary\u003e\n\n  This SDK can be made compatible with JavaScript \"edge\" runtimes that do not support all Node APIs, for example, [Vercel Edge Runtime](https://edge-runtime.vercel.app/), or [Cloudflare Workers](https://developers.cloudflare.com/workers/).\n\n  To make it work, replace the SDK's built-in `fetch` function (which relies on Node APIs) with the runtime's native `fetch` function. Pass the function into the constructor with proper binding:\n\n  ```js\n  const client = new FingerprintJsServerApiClient({\n    region: Region.EU,\n    apiKey: apiKey,\n    fetch: fetch.bind(globalThis),\n  })\n  ```\n\n\u003c/details\u003e\n\n## How to install\n\nInstall the package using your favorite package manager:\n\n- NPM:\n\n  ```sh\n  npm i @fingerprintjs/fingerprintjs-pro-server-api\n  ```\n\n- Yarn:\n  ```sh\n  yarn add @fingerprintjs/fingerprintjs-pro-server-api\n  ```\n- pnpm:\n  ```sh\n  pnpm i @fingerprintjs/fingerprintjs-pro-server-api\n  ```\n\n## Getting started\n\nInitialize the client instance and use it to make API requests. You need to specify your Fingerprint [Secret API key](https://dev.fingerprint.com/docs/quick-start-guide#4-get-smart-signals-to-your-server) and the region of your Fingerprint workspace.\n\n```ts\nimport {\n  FingerprintJsServerApiClient,\n  Region,\n} from '@fingerprintjs/fingerprintjs-pro-server-api'\n\nconst client = new FingerprintJsServerApiClient({\n  apiKey: '\u003cSECRET_API_KEY\u003e',\n  region: Region.Global,\n})\n\n// Get visit history of a specific visitor\nclient.getVisits('\u003cvisitorId\u003e').then((visitorHistory) =\u003e {\n  console.log(visitorHistory)\n})\n\n// Get a specific identification event\nclient.getEvent('\u003crequestId\u003e').then((event) =\u003e {\n  console.log(event)\n})\n\n// Search for identification events\nclient\n  .searchEvents({\n    limit: 10,\n//    pagination_key: previousSearchResult.paginationKey,\n    suspect: true,\n  })\n  .then((events) =\u003e {\n    console.log(events)\n  })\n```\n\nSee the [Examples](https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/tree/main/example) folder for more detailed examples.\n\n### Error handling\n\nThe Server API methods can throw `RequestError`.\nWhen handling errors, you can check for it like this:\n\n```typescript\nimport {\n  RequestError,\n  FingerprintJsServerApiClient,\n  TooManyRequestsError,\n} from '@fingerprintjs/fingerprintjs-pro-server-api'\n\nconst client = new FingerprintJsServerApiClient({\n  apiKey: '\u003cSECRET_API_KEY\u003e',\n  region: Region.Global,\n})\n\n// Handling getEvent errors\ntry {\n  const event = await client.getEvent(requestId)\n  console.log(JSON.stringify(event, null, 2))\n} catch (error) {\n  if (error instanceof RequestError) {\n    console.log(error.responseBody) // Access parsed response body\n    console.log(error.response) // You can also access the raw response\n    console.log(`error ${error.statusCode}: `, error.message)\n  } else {\n    console.log('unknown error: ', error)\n  }\n}\n\n// Handling getVisits errors\ntry {\n  const visitorHistory = await client.getVisits(visitorId, {\n    limit: 10,\n  })\n  console.log(JSON.stringify(visitorHistory, null, 2))\n} catch (error) {\n  if (error instanceof RequestError) {\n    console.log(error.status, error.error)\n    if (error instanceof TooManyRequestsError) {\n      retryLater(error.retryAfter) // Needs to be implemented on your side\n    }\n  } else {\n    console.error('unknown error: ', error)\n  }\n\n  // You can also check for specific error instance\n  // if(error instanceof VisitorsError403) {\n  //    Handle 403 error...\n  // }\n}\n```\n\n### Webhooks\n\n#### Webhook types\n\nWhen handling [Webhooks](https://dev.fingerprint.com/docs/webhooks) coming from Fingerprint, you can cast the payload as the built-in `VisitWebhook` type:\n\n```ts\nimport { VisitWebhook } from '@fingerprintjs/fingerprintjs-pro-server-api'\n\nconst visit = visitWebhookBody as unknown as VisitWebhook\n```\n\n#### Webhook signature validation\n\nCustomers on the Enterprise plan can enable [Webhook signatures](https://dev.fingerprint.com/docs/webhooks-security) to cryptographically verify the authenticity of incoming webhooks.\nThis SDK provides a utility method for verifying the HMAC signature of the incoming webhook request.\n\nTo learn more, see [example/validateWebhookSignature.mjs](example/validateWebhookSignature.mjs) or read the [API Reference](https://fingerprintjs.github.io/fingerprintjs-pro-server-api-node-sdk/functions/isValidWebhookSignature.html).\n\n### Sealed results\n\nCustomers on the Enterprise plan can enable [Sealed results](https://dev.fingerprint.com/docs/sealed-client-results) to receive the full device intelligence result on the client and unseal it on the server. This SDK provides utility methods for decoding sealed results.\n\nTo learn more, see [example/unsealResult.mjs](https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/tree/main/example/unsealResult.mjs) or the [API Reference](https://fingerprintjs.github.io/fingerprintjs-pro-server-api-node-sdk/functions/unsealEventsResponse.html).\n\n### Deleting visitor data\n\nCustomers on the Enterprise plan can [Delete all data associated with a specific visitor](https://dev.fingerprint.com/reference/deletevisitordata) to comply with privacy regulations. See [example/deleteVisitor.mjs](https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/tree/main/example/deleteVisitor.mjs) or the [API Reference](https://fingerprintjs.github.io/fingerprintjs-pro-server-api-node-sdk/classes/FingerprintJsServerApiClient.html#deleteVisitorData).\n\n## API Reference\n\nSee the full [API reference](https://fingerprintjs.github.io/fingerprintjs-pro-server-api-node-sdk/).\n\n## Support and feedback\n\nTo report problems, ask questions, or provide feedback, please use [Issues](https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/issues). If you need private support, you can email us at [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com).\n\n## License\n\nThis project is licensed under the [MIT license](https://github.com/fingerprintjs/fingerprintjs-pro-server-api-node-sdk/tree/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffingerprintjs%2Ffingerprintjs-pro-server-api-node-sdk/lists"}