[INTER-2569] Finishing touches before V4

[TheUnderScorer]

• Removed references to unused error codes
• Fixed broken docs and coverage workflow
• Use description instead of localizedDescription for obtaining error message.
• Updated @fingerprintjs/changesets-native-dependency-format to v0.2.0

After the first successful deployment, the unused gh-pages branch can be removed.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	91.25% (-0.7% 🔻)	240/263
🟢	Branches	87.45% (-2.25% 🔻)	209/239
🟢	Functions	84.21% (-1.5% 🔻)	48/57
🟢	Lines	90.87% (-0.73% 🔻)	229/252

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	utils.ts	98.57% (-1.43% 🔻)	97.37% (-2.63% 🔻)	90% (-10% 🔻)	98.48% (-1.52% 🔻)

Test suite run success

91 tests passing in 6 suites.

Report generated by 🧪jest coverage report action from df2e2c8

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	91.25	87.44	84.21	90.87
🟢	src	91.25	87.44	84.21	90.87
🟢	FingerprintClient.ts	100	90	100	100	22,41,54
🔴	FingerprintClient.web.ts	0	0	0	0	6-64
🟡	FingerprintContext.ts	66.66	100	0	66.66	6
🟢	FingerprintProvider.tsx	100	100	100	100
🟡	errors.ts	75	50	50	75	3,120
🟢	getOptionsCacheKey.ts	84	83.33	100	83.33	10,33,43,52
🔴	index.ts	0	0	0	0
🟢	tags.ts	94.11	93.75	100	94.11	28
🔴	types.ts	0	0	0	0
🟢	unwrapError.ts	100	88.46	100	100	18-19,40
🟢	unwrapError.web.ts	100	100	100	100
🔴	useFingerprint.ts	0	0	0	0	24-28
🟢	usePromiseStore.ts	100	100	100	100
🟢	useVisitorData.ts	95.91	85.71	90	95.74	166-167
🟢	utils.ts	98.57	97.36	90	98.48	10
🔴	src/specs	0	0	0	0
🔴	NativeRNFingerprint.ts	0	0	0	0

[github-actions]

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

@fingerprint/react-native@4.0.0

Major Changes

• Dropped React Native Old Architecture support. The native module is now a TurboModule (New Architecture only) exposed via a Codegen spec.

  Migrated the project to Strict TypeScript API.

  This is a breaking change: the SDK now requires React Native >= 0.80 (Expo SDK >= 54) with the New Architecture enabled. (e83c165)

• Migrated the SDK to Fingerprint API v4 and realigned the public API with @fingerprint/react. This is a breaking change on every platform (web, iOS, Android).

  Renamed API

  • FingerprintJsProProvider → FingerprintProvider.
  • FingerprintJsProAgent (constructed with new) → start(options), returning a client with a single get(options) method (getVisitorId/getVisitorData are removed).
  • Added useFingerprint() to read the client from context.

  Single options object

  • getData(tags, linkedId, options) → getData({ tags, linkedId, timeout }).
  • useVisitorData now returns a discriminated union (data/isLoading/isFetched/error), and getData always throws on error. The throwOnError option is removed. immediate defaults to false.

  Grouped provider/start options

  • Platform-only options are nested: android (allowUseOfLocationData, locationTimeoutMillis), ios (allowUseOfLocationData), web (storageKeyPrefix, urlHashing, cache). locationTimeoutMillisAndroid moves to android.locationTimeoutMillis.
  • endpointUrl + fallbackEndpointUrls are replaced by a single endpoints (string or string[]).

  snake_case response

  • The response is now the flat, snake_case FingerprintResponse (visitor_id, event_id, suspect_score?, sealed_result), matching the Server API v4 and JS agent. requestId is replaced by event_id, confidence is removed, and suspect_score is a new optional Smart Signals value; sealedResult is renamed to sealed_result. The nested extended fields (ipLocation, firstSeenAt, etc.) and the extendedResponseFormat option are removed (v4 always returns the flat format).

  Single error type

  • The ~28 error classes are replaced by a single FingerprintError ({ name, code, event_id }) plus an isFingerprintError type guard. Discriminate on error.code (e.g. too_many_requests).
  • Every network failure reports code: 'network_error' on all platforms. The platform-specific network_unavailable (Android), network_connection and network_abort (web) codes are not emitted.

  Web

  • The web implementation now uses @fingerprint/agent (v4) instead of @fingerprintjs/fingerprintjs-pro-spa. Install @fingerprint/agent as the web peer dependency.
  • ️Caching is available only on web and is disabled by default. To enable caching on web, pass the JavaScript agent cache option:

    <FingerprintProvider
      apiKey={'your-fpjs-public-api-key'}
      region={'eu'}
      web={{cache: {storage: 'sessionStorage', duration: 'optimize-cost'}}}
    >
      <App />
    </FingerprintProvider>

  iOS:

  • The new version floor for iOS is 15.1.

  Android:

  • The new version floor for Android is Android 7.0 (API level 24+).

  Migration

  Provider

  - import { FingerprintJsProProvider } from '@fingerprint/react-native'
  + import { FingerprintProvider } from '@fingerprint/react-native'
  
  - <FingerprintJsProProvider apiKey="PUBLIC_API_KEY" region="eu">
  + <FingerprintProvider apiKey="PUBLIC_API_KEY" region="eu">
      <App />
  - </FingerprintJsProProvider>
  + </FingerprintProvider>

  Hook (useVisitorData)

  - const { isLoading, error, data, getData } = useVisitorData()
  + const { isLoading, isFetched, error, data, getData } = useVisitorData()
  
    // positional args + opt-in throwing → single options object, always throws
  - await getData({ userAction: 'login' }, 'user_1234', { timeout: 5000, throwOnError: true })
  + await getData({ tags: { userAction: 'login' }, linkedId: 'user_1234', timeout: 5000 })
  
  - data?.visitorId
  - data?.confidence.score
  + data?.visitor_id
  + data?.suspect_score

  Imperative client

  - import { FingerprintJsProAgent } from '@fingerprint/react-native'
  + import { start } from '@fingerprint/react-native'
  
  - const client = new FingerprintJsProAgent({ apiKey: 'PUBLIC_API_KEY', region: 'eu' })
  - const visitorId = await client.getVisitorId()
  - const data = await client.getVisitorData()
  + const fp = start({ apiKey: 'PUBLIC_API_KEY', region: 'eu' })
  + const result = await fp.get()
  + result.visitor_id

  Provider / start options

    {
      apiKey: 'PUBLIC_API_KEY',
      region: 'eu',
  -   endpointUrl: 'https://metrics.example.com',
  -   fallbackEndpointUrls: ['https://metrics2.example.com'],
  +   endpoints: ['https://metrics.example.com', 'https://metrics2.example.com'],
  -   extendedResponseFormat: true,
  -   allowUseOfLocationData: true,
  -   locationTimeoutMillisAndroid: 5000,
  +   android: { allowUseOfLocationData: true, locationTimeoutMillis: 5000 },
  +   ios: { allowUseOfLocationData: true },
    }

  Errors

  - import { TooManyRequestError } from '@fingerprint/react-native'
  + import { isFingerprintError } from '@fingerprint/react-native'
  
    try {
      await fp.get()
    } catch (error) {
  -   if (error instanceof TooManyRequestError) {
  +   if (isFingerprintError(error) && error.code === 'too_many_requests') {
        // handle rate limiting
      }
    }

  Web peer dependency

  - npm install @fingerprintjs/fingerprintjs-pro-spa
  + npm install @fingerprint/agent

  --- (64f1dfb)

Minor Changes

• Added experimental support for Swift Package Manager. The library now ships with its own Package.swift.

  If you are on React Native >= 0.87, you can run:

  cd ios
  # deintegrate will remove CocoaPods from your project
  npx react-native spm --deintegrate

  to consume the library via Swift Package Manager. (7af274f)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: ~> 4.1.0
• Fingerprint Android SDK Version Range: >= 4.1.0 and < 4.2.0

[kevinmia]

Overall lgtm! Just left a single comment that might be worth addressing and seems straightforward. Feel free to move forward with this PR as needed