INTER-1488: Migrate SDK to APIv4 #217

erayaydin · 2025-10-14T12:05:32Z

This PR upgrades the Server SDK to the Server API v4. It removes Server APIv3 specific behavior and aligns the SDK with the new events format shared by Server API and Webhooks.

❓ Why?

Server API v3 is deprecated on Oct 31, 2025 and will be sunset on Oct 31, 2026.
v4 standardizes responses (no data/products/result nesting), switches to Bearer auth, unifies Webhooks & Server API event formats, and deprecates /visitors in favor of /v4/events.

⚙️ What Changed?

Endpoints & paths
- GET /events/search -> GET /v4/events
- GET /visitors -> removed, migrate to GET /v4/events
- Request builder now constructs /v4/* URLs.
Authentication
- Replace Auth-Api-Key custom header and apiKey query param with Authorization: Bearer <secret_api_key>.
- Remove AuthenticationMode option.
Names
- request_id -> event_id
- Use snake_case in request and response models (e.g., linked_id, pagination_key)
Responses
- Remove legacy top-level nesting
- Align types with unified events schema
Search and Examples
- Implement GET /v4/events with filters.
- Update examples and mocked responses
Update Event
- PUT /events -> PATCH /v4/event/:event_id
- Body fields now snake_case
Docs
- README updated for v4

⚠️ Breaking Changes

Auth: only Bearer is supported. Query and custom header API key modes and AuthenticationMode option are removed.
Endpoints/Signatures:
- getEvent(requestId) -> getEvent(eventId)
- updateEvent(body, eventId) now use snake_case fields
Models: v3 style top-level nesting removed. Consumers must map to the v4 unified event format.

📦 Migration Guide (SDK Consumers)

Remove authenticationMode option when initializing FingerprintJsServerApiClient.

const client = new FingerprintJsServerApiClient({
  apiKey: '<SECRET_API_KEY>',
  region: Region.Global,
-  authenticationMode: AuthenticationMode.AuthHeader
})

When triggering getEvent() function, use eventId parameter name instead of requestId.

- client.getEvent(requestId: "<request-id>")
+ client.getEvent(eventId: "<request-id>")

Use snake_case fields when updating an event.

client.updateEvent({
- linkedId: "linkedId"
+ linked_id: "linkedId"
}, "<event-id>")

Use tags instead of tag for updating an event.

client.updateEvent({
- tag: {
+ tags: {
    key: 'value',
  }, 
}, "<event-id>")

When triggering updateEvent() function, use eventId parameter name instead of requestId.

client.updateEvent(
  {},
- requestId: "<request-id>"
+ eventId: "<event-id>"
)

Removed deprecated getVisitorHistory() function.
Removed getVisits() function. Use searchEvents() function.

- client.getVisits('<visitorId>')
+ client.searchEvents({ visitor_id: "<visitorId>" })

Removed getRelatedVisitors() function.
Removed VisitorHistoryFilter, ErrorPlainResponse, VisitorsResponse, RelatedVisitorsResponse, RelatedVisitorsFilter, Webhook, EventsUpdateRequest types.

- Switch base URLs to APIv4 (`https://{region}.api.fpjs.io/v4`) and add `apiVersion` handling in URL builder. - Use `Authorization: Bearer <secret-api-key>` only. Remove custom header and query api authorization. - Event API renamed and updated. Use `event_id` instead of `request_id`. Also use `PATCH` for event update instead of `PUT` method. - Add new examples, mocked responses, and update `sync.sh` script. - README reworked for v4 - Package renamed to `@fingerprint/fingerprint-server-sdk`. Updated description and subpackages (example). - Regenerated types and OpenAPI schema. - Updated unit and mock tests for v4 URLs. BREAKING CHANGES: - Only **Bearer auth** is supported; query and custom-header API-key modes are removed. `AuthenticationMode` option is deleted. - Event endpoint and signatures changes: - Use `client.getEvent(eventId)` instead of `requestId` Related-Task: INTER-1488

changeset-bot · 2025-10-14T12:05:37Z

🦋 Changeset detected

Latest commit: c073aeb

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Remove `Accept: application/json` testing header for `updateEvent` function. Related-Task: INTER-1488

Fix updateEventTests test expected method to `PATCH`. Related-Task: INTER-1488

github-actions · 2025-10-14T12:29:01Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	90.72% (-5% 🔻)	176/194
🟢	Branches	82.54% (-7.2% 🔻)	52/63
🟢	Functions	97.14% (-0.63% 🔻)	34/35
🟢	Lines	90.63% (-5.06% 🔻)	174/192

Show files with reduced coverage 🔻

St.^❔	File	Statements	Branches	Functions	Lines
🟢	urlUtils.ts	90% (-5.24% 🔻)	73.33% (-14.17% 🔻)	100%	89.74% (-5.38% 🔻)
🟢	serverApiClient.ts	84.44% (-5.11% 🔻)	70.59% (-2.14% 🔻)	100% (+10% 🔼)	84.44% (-5.11% 🔻)
🟢	`...` / getRetryAfter.ts	100%	50% (-50% 🔻)	100%	100%
🔴	responseUtils.ts	0% (-100% 🔻)	100%	0% (-100% 🔻)	0% (-100% 🔻)

Test suite run success

56 tests passing in 9 suites.

Report generated by 🧪jest coverage report action from c073aeb

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	90.72	82.53	97.14	90.62
🟢	src	88.53	82.35	95.65	88.46
🟢	index.ts	100	100	100	100
🔴	responseUtils.ts	0	100	0	0	1-8
🟢	sealedResults.ts	100	100	100	100
🟢	serverApiClient.ts	84.44	70.58	100	84.44	24,64,115,119,163,256,270
🟢	types.ts	100	100	100	100
🟢	urlUtils.ts	90	73.33	100	89.74	33,43,60,161
🟡	utils.ts	75	100	100	75	6
🟢	webhook.ts	100	100	100	100
🟢	src/errors	100	83.33	100	100
🟢	apiErrors.ts	100	100	100	100
🟢	getRetryAfter.ts	100	50	100	100	2-3
🟢	handleErrorResponse.ts	100	100	100	100
🟢	unsealError.ts	100	100	100	100

Removed unnecessary commented line. Related-Task: INTER-1488

Expands `searchEvents` JSDoc with new filters. Also its align parameter names.

readme.md

necipallef · 2025-10-21T16:04:52Z

Sharing feedback (more to come later):

[nitpick]: This line needs a closing quote. This mistake was already there before your PR, let's address it in your PR
I think we can safely remove getVisitorHistory example. This used to be a separate endpoint, that's why it had example, it is not the case any more.
The changelog file is still not mentioning the change to installation method. The command to install the library has changed because the package name is changed. This should be in the changelog.
The release says v8.0.0, it should be v7.0.0
The release is actually saying @fingerprint/fingerprint-server-sdk@8.0.0 instead of just v8.0.0. IMO we should fix this before we release. This was a mistake that's done in all previous releases, not something this PR breaks, but something I want to see fixed.

I will try to wrap up my review ASAP, and share more if there is more. Thank you! @erayaydin

src/serverApiClient.ts

src/urlUtils.ts

example/.env.example

necipallef · 2025-10-22T00:00:54Z

src/serverApiClient.ts

   *
   * @param body - Data to update the event with.
-   * @param requestId The unique event [identifier](https://dev.fingerprint.com/docs/js-agent#requestid).
+   * @param eventId The unique event [identifier](https://dev.fingerprint.com/docs/js-agent#eventid).


the link anchor is not found

necipallef · 2025-10-22T00:04:40Z

src/types.ts

+export type EventsGetResponse = paths['/events/{event_id}']['get']['responses']['200']['content']['application/json']

 /**
 * More info: https://dev.fingerprintjs.com/docs/webhooks#identification-webhook-object-format


Incorrect anchor. It should be https://dev.fingerprint.com/docs/webhooks#webhook-payload-format instead.

Add `fingerprint-server-sdk-smoke-tests` to changeset ignore list. Related-Task: INTER-1488

Explicitly mention about package name change in changeset file. Related-Task: INTER-1488

Use correct `patch` method instead of `put` for updating an event. Related-Task: INTER-1488

Replace strict `response.status === 200` checks with `response.ok` in fetch handlers. Related-Task: INTER-1488

Added a new `callApi()` function to handle request building and `fetch` usage in one place. Replaced all direct `fetch` calls with `callApi`. Introduced `defaultHeaders` options to the client, it's include `Authorization` header and allow extra headers and override of `Authorization` header. Made `region` optional in `GetRequestPathOptions` and it's default to `Region.Global` in `getRequestPath` function. Related-Task: INTER-1488

Remove `isEmptyValue` helper function and use direct `== null` checks to skip `undefined` or `null` values. Related-Task: INTER-1488

Use correct `EVENT_ID` placeholder for the example `.env.example` dotenv file. Related-Task: INTER-1488

Add `IsNever` and `NonNeverKeys` utility types to filter out `never` type keys. Introduce and export `AllowedMethod` that excludes specific `parameters` and any `never` type methods. Use this `AllowedMethod` type for `GetRequestPathOptions` type and `getRequestPath` functions. Update related signatures. Related-Task: INTER-1488

Use `options.method.toUpperCase()` when calling `fetch` to ensure standard HTTP method casing and avoid test fails. Change `AllowedMethod` to make a string literal union. Related-Task: INTER-1488

Extend `callApi` to accept an optional `body?: BodyInit` and forward it to `fetch`. Fix `updateEvent` to send `body`. Related-Task: INTER-1488

Removed unnecessary visitor detail tests. Related-Task: INTER-1488

Fix missing quote for `linked_id` in `searchEvents.mjs` example file. Related-Task: INTER-1488

necipallef · 2025-10-22T14:44:29Z

Can we also update this line from any to unknown? I found a few more any usage in types, I leave them up to you @erayaydin but I at least insist on changing this line.

src/serverApiClient.ts

Removed redundant `await` keyword in `callApi` function. Related-Task: INTER-1488

ilfa · 2025-10-22T17:40:31Z

readme.md


 #### Webhook types

 When handling [Webhooks](https://dev.fingerprint.com/docs/webhooks) coming from Fingerprint, you can cast the payload as the built-in `VisitWebhook` type:


Suggested change

When handling [Webhooks](https://dev.fingerprint.com/docs/webhooks) coming from Fingerprint, you can cast the payload as the built-in `VisitWebhook` type:

When handling [Webhooks](https://dev.fingerprint.com/reference/posteventwebhook#/) coming from Fingerprint, you can cast the payload as the built-in `Event` type:

Not sure about the link, but it should be more relevant.

ilfa · 2025-10-22T17:42:10Z

readme.md

+import { Event } from '@fingerprint/fingerprint-server-sdk'

-const visit = visitWebhookBody as unknown as VisitWebhook
+const visit = visitWebhookBody as unknown as Event


Suggested change

const visit = visitWebhookBody as unknown as Event

const visit = eventWebhookBody as unknown as Event

Centralize response parsing and error handling in `callApi` function. Throw consistent `SdkError`, `RequestError`, or `TooManyRequestsError` depends on the case. Added `SuccessJsonOrVoid<Path, Method>` to automatically resolve the potential/correct return type for success responses. Simplify all public methods. Related-Task: INTER-1488

Removed `handleErrorResponse` and moved all error logic into `callApi`. Exported `isErrorResponse` to detect valid error payloads. Added `createResponse` helper for creating mock Response object with headers. Related-Task: INTER-1488

necipallef · 2025-10-23T17:08:39Z

src/serverApiClient.ts

-      return jsonResponse as RelatedVisitorsResponse
+    let errPayload
+    try {
+      // TODO: Use ErrorJson<Path, Method> instead of ErrorResponse type. It requires generic error classes without error.message and error.code


Is it intentional to keep this Todo item? Also, the ErrorJson type is not used anywhere

erayaydin · 2025-10-27T10:58:29Z

We also need to update the unsealed data snapshot example here. We should create an unsealed data example for Server API v4.

Fixes webhook example and description in the `readme.md` file. Related-Task: INTER-1488

Use `Event` type instead of duplicated `EventsGetResponse` type. Update sealedResults snapshot and example base64 sealed result value. Fix reference links. Related-Task: INTER-1488

Removes unnecessary `ErrorJson` type from the project. Related-Task: INTER-1488

github-actions · 2025-10-29T12:31:15Z

🚀 Following releases will be created using changesets from this PR:

@fingerprint/fingerprint-server-sdk@8.0.0

Major Changes

Server APIv3 -> Server APIv4 migration
- Switch all endpoints to /v4/*.
- Remove authenticationMode option when initializing FingerprintJsServerApiClient.
- Rename request_id to event_id.
- Use snake_case fields when updating an event.
- Use PATCH method when updating an event.
- Examples, tests, and docs updated.
BREAKING CHANGES
- authenticationMode option removed.
- Endpoints and method signatures changed.
  - Use eventId instead of requestId when triggering updateEvent() function.
  - Use eventId instead of requestId when triggering getEvent() function.
- Removed getVisits() function.
- Removed getRelatedVisitors() function.
- Removed VisitorHistoryFilter, ErrorPlainResponse, VisitorsResponse, RelatedVisitorsResponse,
  RelatedVisitorsFilter, Webhook, EventsUpdateRequest types.
- Use tags instead of tag for updating an event.
- Response models changed. (ce2854d)
change package name to @fingerprint/fingerprint-server-sdk (385b01b)

erayaydin · 2025-10-29T12:35:41Z

Superseded by #218

erayaydin self-assigned this Oct 14, 2025

erayaydin added documentation Improvements or additions to documentation enhancement New feature or request labels Oct 14, 2025

erayaydin added 2 commits October 14, 2025 15:26

feat: remove accept header for updateEvent

42cd278

Remove `Accept: application/json` testing header for `updateEvent` function. Related-Task: INTER-1488

test: fix update event test expected method

a928611

Fix updateEventTests test expected method to `PATCH`. Related-Task: INTER-1488

erayaydin added 5 commits October 14, 2025 16:02

chore: remove unnecessary commented line

558c352

Removed unnecessary commented line. Related-Task: INTER-1488

docs: expand searchEvents JSDoc with new filters

c6a02cd

Expands `searchEvents` JSDoc with new filters. Also its align parameter names.

docs: fix example naming for error handling

696acb3

chore: update OpenAPI schema version

3840e16

chore: add changeset file for changes

ce2854d

erayaydin marked this pull request as ready for review October 15, 2025 12:42

erayaydin requested review from JuroUhlar, Orkuncakilkaya, ilfa, makma and mcnulty-fp as code owners October 15, 2025 12:42

necipallef reviewed Oct 15, 2025

View reviewed changes

readme.md Outdated Show resolved Hide resolved

erayaydin added 2 commits October 15, 2025 16:29

docs: update package name for badges

41876b5

docs: use correct package name for installation

29e8497