INTER-1488: Migrate SDK to APIv4

[erayaydin]

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.

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 2eb7507b197e386971990af93e112f94dcc04b10

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

[github-actions[bot]]

Coverage report

St.:grey_question:	Category	Percentage	Covered / Total
🟢	Statements	100% (+4.27% 🔼)	184/184
🟢	Branches	100% (+10.26% 🔼)	62/62
🟢	Functions	100% (+2.22% 🔼)	34/34
🟢	Lines	100% (+4.31% 🔼)	182/182

Test suite run success

74 tests passing in 10 suites.

Report generated by 🧪jest coverage report action from 2eb7507b197e386971990af93e112f94dcc04b10

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	100	100	100	100
🟢	src	100	100	100	100
🟢	index.ts	100	100	100	100
🟢	sealedResults.ts	100	100	100	100
🟢	serverApiClient.ts	100	100	100	100
🟢	types.ts	100	100	100	100
🟢	urlUtils.ts	100	100	100	100
🟢	webhook.ts	100	100	100	100
🟢	src/errors	100	100	100	100
🟢	apiErrors.ts	100	100	100	100
🟢	getRetryAfter.ts	100	100	100	100
🟢	handleErrorResponse.ts	100	100	100	100
🟢	unsealError.ts	100	100	100	100

[github-actions[bot]]

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

@fingerprint/[email protected]

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)