@fingerly/lynx 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -21,7 +21,7 @@
21
21
 
22
22
  ## What is this
23
23
 
24
- `@fingerly/lynx` (`0.3.0`, `v: 3`) is the Fingerly SDK for Lynx. It is a thin Native Module over the Fingerly iOS and Android SDKs; all collection, transport and attestation stay native. You call `identify()` from Lynx background-thread scripting and get back a request ID and a visitor ID to send to your own backend, which decides what to do. [Fingerly](https://fingerly.io) is a device intelligence API that helps you protect signups, logins and payments from fraud and abuse.
24
+ `@fingerly/lynx` (`0.4.0`, `v: 3`) is the Fingerly SDK for Lynx. It is a thin Native Module over the Fingerly iOS and Android SDKs; all collection, transport and attestation stay native. You call `identify()` from Lynx background-thread scripting and get back a request ID and a visitor ID to send to your own backend, which decides what to do. [Fingerly](https://fingerly.io) is a device intelligence API that helps you protect signups, logins and payments from fraud and abuse.
25
25
 
26
26
  Supported: Lynx 4.1 on iOS and Android. Not supported: HarmonyOS, Web, Lynxtron and per-`LynxView` registration.
27
27
 
@@ -31,7 +31,7 @@ Supported: Lynx 4.1 on iOS and Android. Not supported: HarmonyOS, Web, Lynxtron
31
31
  2. **Install the package.**
32
32
 
33
33
  ```sh
34
- pnpm add @fingerly/lynx@^0.3.0
34
+ pnpm add @fingerly/lynx@^0.4.0
35
35
  ```
36
36
 
37
37
  The host app must enable [Lynx Native Library Autolink](https://lynxjs.org/guide/autolink). See [Platform setup](#platform-setup) for the Android and iOS steps.
@@ -39,10 +39,10 @@ Supported: Lynx 4.1 on iOS and Android. Not supported: HarmonyOS, Web, Lynxtron
39
39
  3. **Identify.** Native Modules are available from Lynx background-thread scripting, so call the SDK from an event handler, effect, or other background function.
40
40
 
41
41
  ```ts
42
- import { load } from '@fingerly/lynx'
42
+ import { ConsentState, load } from '@fingerly/lynx'
43
43
 
44
44
  // consent: only once you have consent (or another lawful basis)
45
- const fingerly = await load({ apiKey: 'fly_pk_production_…', consent: 'granted' })
45
+ const fingerly = await load({ apiKey: 'fly_pk_production_…', consent: ConsentState.Granted })
46
46
  const result = await fingerly.identify({ tag: 'checkout' })
47
47
 
48
48
  // Send result.requestId to your backend and make the decision there.
@@ -52,6 +52,7 @@ Supported: Lynx 4.1 on iOS and Android. Not supported: HarmonyOS, Web, Lynxtron
52
52
 
53
53
  - [Platform setup](#platform-setup)
54
54
  - [Identify](#identify)
55
+ - [Named values](#named-values)
55
56
  - [Consent](#consent)
56
57
  - [Erasure](#erasure)
57
58
  - [Why there is no JavaScript fallback](#why-there-is-no-javascript-fallback)
@@ -70,7 +71,7 @@ The package's `lynx.lib.json` registers the `Fingerly` Native Module. The host a
70
71
  | --- | --- |
71
72
  | Apply `org.lynxsdk.library-settings` in `settings.gradle` and `org.lynxsdk.library-build` in the app module, then sync and rebuild. | Install `cocoapods-lynx-library`, add `plugin 'cocoapods-lynx-library'` and `use_lynx_library!` to the Podfile, run `pod install`, then rebuild. |
72
73
 
73
- The Android module depends on `io.fingerly:fingerly:0.3.0` from Fingerly's Maven repository (`mavenLocal()` is also configured, for local artifact staging). Android hosts add Fingerly's repository to the repositories in `settings.gradle`:
74
+ The Android module depends on `io.fingerly:fingerly:0.4.0` from Fingerly's Maven repository (`mavenLocal()` is also configured, for local artifact staging). Android hosts add Fingerly's repository to the repositories in `settings.gradle`:
74
75
 
75
76
  ```groovy
76
77
  maven { url 'https://maven.fingerly.io' }
@@ -78,7 +79,7 @@ maven { url 'https://maven.fingerly.io' }
78
79
 
79
80
  ## Identify
80
81
 
81
- `load` reports `lynx-ios` or `lynx-android`, so the server selects the correct native risk profile and applies the right mobile checks. On any other platform it throws a `FingerlyError`. For production Android keys, configure `AllowedAndroidSigners` (64-hex SHA-256 signing certificate digests) alongside `AllowedAndroidPackages` in the dashboard.
82
+ `load` reports `lynx-ios` or `lynx-android` (`SdkPlatform.LynxIos`, `SdkPlatform.LynxAndroid`), so the server selects the correct native risk profile and applies the right mobile checks. On any other platform it throws a `FingerlyError`. For production Android keys, configure `AllowedAndroidSigners` (64-hex SHA-256 signing certificate digests) alongside `AllowedAndroidPackages` in the dashboard.
82
83
 
83
84
  `identify()` submits a single-pass `v: 3` identification (`1-RTT` steady state through cached `next_attestation` challenge offers) and resolves with what the server said: `requestId`, `visitorId` and, by default, `suspectScore` and `suspectLevel`.
84
85
 
@@ -106,19 +107,47 @@ const version = nativeVersion()
106
107
 
107
108
  Failures are surfaced as `FingerlyError`. `status` is populated only for a positive HTTP status returned by the native transport. When the server asked for a pause with `Retry-After`, `retryAfterMs` carries it: wait at least that long before identifying again. It is undefined when no wait was named.
108
109
 
110
+ ## Named values
111
+
112
+ The fixed strings the API returns and the module accepts have names, the same objects `@fingerly/web-js` exports. Each is an `as const` object with a same-named type, and a member is its value in PascalCase, word by word (`SuspectLevel.High` is `'high'`, `Signal.FingerprintSuppressed` is `'fingerprint_suppressed'`):
113
+
114
+ ```ts
115
+ import { EventState, SuspectLevel } from '@fingerly/lynx'
116
+
117
+ const result = await fingerly.identify({ tag: 'checkout' })
118
+
119
+ if (result.state === EventState.Unavailable) {
120
+ // The network lookup could not run, so the check was not scored.
121
+ }
122
+ if (result.suspectLevel === SuspectLevel.High) {
123
+ // Show a step-up screen while your backend makes the decision.
124
+ }
125
+ ```
126
+
127
+ | Constant | Members | Where it appears |
128
+ | --- | --- | --- |
129
+ | `SuspectLevel` | `Low`, `Medium`, `High` | `suspectLevel` on the `identify()` answer. |
130
+ | `EventState` | `Enriched`, `Unavailable`, `Pending` | `state` on the `identify()` answer. An answer is never `Pending`, which only a server-side event read reports. |
131
+ | `ConsentState` | `Granted`, `Pending`, `Denied` | The `consent` option on `load`, `setConsent`, `consent` and `ConsentError.state`. |
132
+ | `SdkPlatform` | `LynxIos`, `LynxAndroid`, and the other SDKs' platforms | What the module reports itself as, and the SDK named on the event your backend reads. |
133
+ | `Signal` | Every signal group and detector the server reports, such as `Signal.Jailbreak` and `Signal.VpnPublic` | Triggers on the event your backend reads and in webhooks. The signals never reach the device. |
134
+ | `Confidence` | `Low`, `Medium`, `High` | A trigger's `confidence` on the event your backend reads. |
135
+
136
+ Comparing with the plain string compiles as well. The module hands on the server's values as they came, so a value a newer server adds reaches the app unchanged rather than being dropped.
137
+
109
138
  ## Consent
110
139
 
111
140
  The SDK identifies nobody until it is told consent is `'granted'`. The usual pattern is to load it at launch with the default `'pending'` and pass on the answer from your consent tool when it arrives:
112
141
 
113
142
  ```ts
114
- import { ConsentError, load } from '@fingerly/lynx'
143
+ import { ConsentError, ConsentState, load } from '@fingerly/lynx'
115
144
 
116
145
  const fingerly = await load({ apiKey: 'fly_pk_production_…' }) // consent is 'pending'
117
146
 
118
147
  // From your consent tool's callback:
119
- fingerly.setConsent(accepted ? 'granted' : 'denied')
148
+ fingerly.setConsent(accepted ? ConsentState.Granted : ConsentState.Denied)
120
149
 
121
- fingerly.consent // 'granted', 'pending' or 'denied'
150
+ fingerly.consent // ConsentState.Granted, ConsentState.Pending or ConsentState.Denied
122
151
  ```
123
152
 
124
153
  | Option / method | What it does |
@@ -127,7 +156,7 @@ fingerly.consent // 'granted', 'pending' or 'denied'
127
156
  | `setConsent(state)` | Records the decision. Synchronous and safe to call repeatedly. |
128
157
  | `consent` | The state last given to the native SDK, read-only. |
129
158
 
130
- The default is `'pending'`, so an integration that never mentions consent identifies nobody. Pass `consent: 'granted'` to `load` only when you already have consent, or another lawful basis. Anything other than the three states throws a `TypeError`.
159
+ The default is `'pending'`, so an integration that never mentions consent identifies nobody. Pass `consent: ConsentState.Granted` to `load` only when you already have consent, or another lawful basis. Anything other than the three states throws a `TypeError`.
131
160
 
132
161
  Until consent is `'granted'`, the native SDK runs no source, touches no container storage or attestation key state, and sends nothing. `identify()` and `collect()` reject with `ConsentError`, a subclass of `FingerlyError` with `code: 'consent_required'` and the refusing `state`:
133
162
 
@@ -136,7 +165,7 @@ try {
136
165
  await fingerly.identify()
137
166
  } catch (error) {
138
167
  if (error instanceof ConsentError) {
139
- // error.state is 'pending' or 'denied'; nothing was collected or sent
168
+ // error.state is ConsentState.Pending or ConsentState.Denied; nothing was collected or sent
140
169
  }
141
170
  }
142
171
  ```
@@ -168,12 +197,12 @@ JavaScript cannot inspect the filesystem, loaded Mach-O or ELF images, debugger
168
197
 
169
198
  ## Native SDK dependencies
170
199
 
171
- Both native dependencies are at `0.3.0`.
200
+ Both native dependencies are at `0.4.0`.
172
201
 
173
202
  <details>
174
203
  <summary><b>iOS</b></summary>
175
204
 
176
- `pod install` downloads the matching `Fingerly.xcframework` (`0.3.0`) from `https://maven.fingerly.io/ios/` and verifies its SHA-256 checksum, so the Podfile needs no separate entry for the native SDK. The same binary is published as a Swift package at [sdk-ios](https://github.com/fingerly-io/sdk-ios).
205
+ `pod install` downloads the matching `Fingerly.xcframework` (`0.4.0`) from `https://maven.fingerly.io/ios/` and verifies its SHA-256 checksum, so the Podfile needs no separate entry for the native SDK. The same binary is published as a Swift package at [sdk-ios](https://github.com/fingerly-io/sdk-ios).
177
206
 
178
207
  The Play Integrity project number passed to `load` is ignored on iOS.
179
208
 
@@ -182,32 +211,32 @@ The Play Integrity project number passed to `load` is ignored on iOS.
182
211
  <details>
183
212
  <summary><b>Android</b></summary>
184
213
 
185
- The module resolves `io.fingerly:fingerly:0.3.0` from `https://maven.fingerly.io`, added to the host's repositories as shown in [Platform setup](#platform-setup).
214
+ The module resolves `io.fingerly:fingerly:0.4.0` from `https://maven.fingerly.io`, added to the host's repositories as shown in [Platform setup](#platform-setup).
186
215
 
187
- **Installed-app checks are opt-in (`io.fingerly:fingerly-app-checks:0.3.0`).** Core `io.fingerly:fingerly:0.3.0` declares zero `<queries>` entries in its manifest, because Google Play treats installed-app visibility as personal and sensitive data. If your app can justify package visibility for the 17 root managers, hooking frameworks and dual-space cloners in its Play review, add `io.fingerly:fingerly-app-checks:0.3.0` to your app's Android module and declare "App activity: Installed apps" in the Data safety form. The module finds the artifact and registers its provider on every `load`, so there is no native code to write:
216
+ **Installed-app checks are opt-in (`io.fingerly:fingerly-app-checks:0.4.0`).** Core `io.fingerly:fingerly:0.4.0` declares zero `<queries>` entries in its manifest, because Google Play treats installed-app visibility as personal and sensitive data. If your app can justify package visibility for the 17 root managers, hooking frameworks and dual-space cloners in its Play review, add `io.fingerly:fingerly-app-checks:0.4.0` to your app's Android module and declare "App activity: Installed apps" in the Data safety form. The module finds the artifact and registers its provider on every `load`, so there is no native code to write:
188
217
 
189
218
  ```kotlin
190
219
  // the app module's build.gradle.kts
191
220
  dependencies {
192
- implementation("io.fingerly:fingerly-app-checks:0.3.0")
221
+ implementation("io.fingerly:fingerly-app-checks:0.4.0")
193
222
  }
194
223
  ```
195
224
 
196
225
  Without it, the report carries no installed-app fields and nothing about other apps leaves the device; whether the app itself runs inside a cloner is still reported.
197
226
 
198
- **Play Integrity (optional, `io.fingerly:fingerly-play-integrity:0.3.0`).** To add Google Play Integrity Standard tokens bound to the `v: 3` `statementDigest`, add the artifact to your app's Android module and pass your Google Cloud project number, the one linked to the app in Play Console, to `load`. The module finds the artifact and registers its provider with that project number:
227
+ **Play Integrity (optional, `io.fingerly:fingerly-play-integrity:0.4.0`).** To add Google Play Integrity Standard tokens bound to the `v: 3` `statementDigest`, add the artifact to your app's Android module and pass your Google Cloud project number, the one linked to the app in Play Console, to `load`. The module finds the artifact and registers its provider with that project number:
199
228
 
200
229
  ```kotlin
201
230
  // the app module's build.gradle.kts
202
231
  dependencies {
203
- implementation("io.fingerly:fingerly-play-integrity:0.3.0")
232
+ implementation("io.fingerly:fingerly-play-integrity:0.4.0")
204
233
  }
205
234
  ```
206
235
 
207
236
  ```ts
208
237
  const fingerly = await load({
209
238
  apiKey: 'fly_pk_production_…',
210
- consent: 'granted',
239
+ consent: ConsentState.Granted,
211
240
  playIntegrityCloudProjectNumber: 123456789012,
212
241
  })
213
242
  ```
@@ -28,12 +28,12 @@ dependencies {
28
28
  implementation("org.lynxsdk.lynx:lynx:4.1.0")
29
29
  implementation("org.lynxsdk.lynx:service-api:4.1.0")
30
30
  annotationProcessor("org.lynxsdk.lynx:lynx-processor:4.1.0")
31
- implementation("io.fingerly:fingerly:0.3.0")
31
+ implementation("io.fingerly:fingerly:0.4.0")
32
32
 
33
33
  // The opt-in artifacts. `compileOnly` so the module can construct their providers when the
34
34
  // host app links them, without adding `<queries>` or Play Services to an app that does not.
35
- compileOnly("io.fingerly:fingerly-app-checks:0.3.0")
36
- compileOnly("io.fingerly:fingerly-play-integrity:0.3.0")
35
+ compileOnly("io.fingerly:fingerly-app-checks:0.4.0")
36
+ compileOnly("io.fingerly:fingerly-play-integrity:0.4.0")
37
37
 
38
38
  testImplementation("junit:junit:4.13.2")
39
39
  }
@@ -1,6 +1,6 @@
1
1
  {
2
- "version": "0.3.0",
3
- "url": "https://maven.fingerly.io/ios/Fingerly-0.3.0.xcframework.zip",
4
- "sha256": "b3288cc4539b6c5b8bae226854a586473b2457489e69b2ac1f26e9f84f6add27",
2
+ "version": "0.4.0",
3
+ "url": "https://maven.fingerly.io/ios/Fingerly-0.4.0.xcframework.zip",
4
+ "sha256": "962dcded8374e162a095c9373d7044e66532a327a002889347c547868cc64460",
5
5
  "team_id": "XGXX88HRR5"
6
6
  }
@@ -21,7 +21,7 @@ end
21
21
 
22
22
  Pod::Spec.new do |s|
23
23
  s.name = 'fingerly-lynx'
24
- s.version = package['version'] || '0.3.0'
24
+ s.version = package['version'] || '0.4.0'
25
25
  s.summary = 'Fingerly native bridge for Lynx'
26
26
  s.homepage = 'https://fingerly.io'
27
27
  s.license = { :type => 'Apache-2.0', :file => '../LICENSE' }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/lynx",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -28,7 +28,7 @@
28
28
  "README.md"
29
29
  ],
30
30
  "dependencies": {
31
- "@fingerly/types": "0.3.0"
31
+ "@fingerly/types": "0.4.0"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@lynx-js/autolink-codegen": "0.6.0",
package/src/index.ts CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  import { requireFingerly } from '../generated/Fingerly'
4
4
 
5
+ import { ConsentState, SdkPlatform } from '@fingerly/types'
5
6
  import type {
6
7
  MobileFingerlyOptions,
7
8
  MobileIdentifyOptions,
8
9
  NativeIdentifyResult,
9
- SdkPlatform,
10
10
  SignalReport,
11
11
  } from '@fingerly/types'
12
12
 
@@ -34,13 +34,6 @@ interface FingerlyNativeModule {
34
34
  sdkVersion(): string
35
35
  }
36
36
 
37
- /**
38
- * Whether the user has agreed to be identified. Spelled as in `@fingerly/core`
39
- * and the native SDKs; declared here so this package builds against any copy of
40
- * `@fingerly/types`, including one that predates consent.
41
- */
42
- export type ConsentState = 'granted' | 'pending' | 'denied'
43
-
44
37
  export interface FingerlyOptions extends MobileFingerlyOptions {
45
38
  /**
46
39
  * The consent to start from, `pending` when omitted. Call `setConsent` once
@@ -115,7 +108,7 @@ export class ConsentError extends FingerlyError {
115
108
 
116
109
  const CONSENT_REQUIRED = 'consent_required'
117
110
 
118
- const CONSENT_STATES: readonly ConsentState[] = ['granted', 'pending', 'denied']
111
+ const CONSENT_STATES: readonly ConsentState[] = Object.values(ConsentState)
119
112
 
120
113
  function isConsentState(value: unknown): value is ConsentState {
121
114
  return CONSENT_STATES.includes(value as ConsentState)
@@ -156,14 +149,14 @@ function refusedConsent(record: Record<string, unknown> | undefined, message: st
156
149
  const fromNative = record?.state
157
150
  if (isConsentState(fromNative)) return fromNative
158
151
  const fromMessage = /\(consent is (\w+)\)/.exec(message)?.[1]
159
- return isConsentState(fromMessage) ? fromMessage : 'pending'
152
+ return isConsentState(fromMessage) ? fromMessage : ConsentState.Pending
160
153
  }
161
154
 
162
155
  /**
163
156
  * The consent last handed to the native SDK. Module state because the native
164
157
  * bridge keeps one client per process, shared by every `FingerlyClient` here.
165
158
  */
166
- let currentConsent: ConsentState = 'pending'
159
+ let currentConsent: ConsentState = ConsentState.Pending
167
160
 
168
161
  const MISSING_NATIVE_MODULE =
169
162
  '@fingerly/lynx could not find its Fingerly native module. Enable Lynx Native ' +
@@ -187,8 +180,8 @@ function nativeModule(): FingerlyNativeModule {
187
180
 
188
181
  function platformName(): SdkPlatform {
189
182
  const platform = typeof SystemInfo === 'undefined' ? undefined : SystemInfo?.platform
190
- if (platform === 'Android') return 'lynx-android'
191
- if (platform === 'iOS') return 'lynx-ios'
183
+ if (platform === 'Android') return SdkPlatform.LynxAndroid
184
+ if (platform === 'iOS') return SdkPlatform.LynxIos
192
185
  throw new FingerlyError(
193
186
  `@fingerly/lynx supports iOS and Android only; received ${platform ?? 'an unknown platform'}.`,
194
187
  )
@@ -391,7 +384,7 @@ export class FingerlyClient {
391
384
  * here, or `pending` when there is none, replaces what the native SDK held.
392
385
  */
393
386
  export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
394
- const consent = options.consent ?? 'pending'
387
+ const consent = options.consent ?? ConsentState.Pending
395
388
  assertConsentState(consent)
396
389
  const playIntegrity = options.playIntegrityCloudProjectNumber
397
390
  assertCloudProjectNumber(playIntegrity)
@@ -449,8 +442,22 @@ export function nativeVersion(): string | undefined {
449
442
  }
450
443
  }
451
444
 
452
- export type {
445
+ // Runtime constants for the fixed values the API returns and the module
446
+ // accepts, the same objects `@fingerly/core` and `@fingerly/web-js` export, so
447
+ // `result.suspectLevel === SuspectLevel.High` reads the same in every
448
+ // JavaScript SDK. Each is also the type of its values. They are names for
449
+ // strings, not a filter: the module hands on the server's values as they came,
450
+ // so one a newer server adds still reaches the app unchanged.
451
+ export {
453
452
  Confidence,
453
+ ConsentState,
454
+ EventState,
455
+ SdkPlatform,
456
+ Signal,
457
+ SuspectLevel,
458
+ } from '@fingerly/types'
459
+
460
+ export type {
454
461
  EngineIdentity,
455
462
  IdentifyResult,
456
463
  IdentifySubmission,
@@ -462,9 +469,8 @@ export type {
462
469
  MobileIdentifyOptions,
463
470
  NativeIdentifyResult,
464
471
  RiskSignal,
465
- SdkPlatform,
472
+ SignalName,
466
473
  SignalOutcome,
467
474
  SignalReport,
468
475
  SignalStatus,
469
- SuspectLevel,
470
476
  } from '@fingerly/types'
package/types/index.d.ts CHANGED
@@ -12,9 +12,20 @@ export {
12
12
  load,
13
13
  nativeVersion,
14
14
  } from '../src/index';
15
- export type {
15
+ /**
16
+ * Named constants for the fixed values the API returns and the module accepts,
17
+ * the same objects `@fingerly/web-js` exports. Each is also the type of its
18
+ * values.
19
+ */
20
+ export {
16
21
  Confidence,
17
22
  ConsentState,
23
+ EventState,
24
+ SdkPlatform,
25
+ Signal,
26
+ SuspectLevel,
27
+ } from '../src/index';
28
+ export type {
18
29
  EngineIdentity,
19
30
  FingerlyOptions,
20
31
  IdentifyOptions,
@@ -29,9 +40,8 @@ export type {
29
40
  NativeIdentifyResult,
30
41
  RawReportResult,
31
42
  RiskSignal,
32
- SdkPlatform,
43
+ SignalName,
33
44
  SignalOutcome,
34
45
  SignalReport,
35
46
  SignalStatus,
36
- SuspectLevel,
37
47
  } from '../src/index';