@fingerly/lynx 0.0.0-stage → 0.1.1
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/LICENSE +202 -0
- package/README.md +183 -2
- package/android/build.gradle.kts +25 -0
- package/android/gradle/wrapper/gradle-wrapper.jar +0 -0
- package/android/gradle/wrapper/gradle-wrapper.properties +7 -0
- package/android/gradle.properties +2 -0
- package/android/gradlew +251 -0
- package/android/gradlew.bat +94 -0
- package/android/settings.gradle.kts +21 -0
- package/android/src/main/AndroidManifest.xml +3 -0
- package/android/src/main/java/io/fingerly/lynx/Fingerly.java +118 -0
- package/android/src/main/java/io/fingerly/lynx/generated/FingerlySpec.java +31 -0
- package/generated/Fingerly.ts +66 -0
- package/ios/fetch-fingerly-xcframework.sh +52 -0
- package/ios/fingerly-binary.json +4 -0
- package/ios/fingerly-lynx.podspec +36 -0
- package/ios/src/Fingerly.h +12 -0
- package/ios/src/Fingerly.m +119 -0
- package/ios/src/generated/FingerlySpec.h +18 -0
- package/ios/src/generated/FingerlySpec.m +2 -0
- package/lynx.lib.json +12 -0
- package/package.json +43 -3
- package/src/index.ts +409 -0
- package/types/index.d.ts +2 -0
- package/types/platform-native-module.d.ts +9 -0
package/src/index.ts
ADDED
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
'background only'
|
|
2
|
+
|
|
3
|
+
import { requireFingerly } from '../generated/Fingerly'
|
|
4
|
+
|
|
5
|
+
import type {
|
|
6
|
+
MobileFingerlyOptions,
|
|
7
|
+
MobileIdentifyOptions,
|
|
8
|
+
NativeIdentifyResult,
|
|
9
|
+
SdkPlatform,
|
|
10
|
+
SignalReport,
|
|
11
|
+
} from '@fingerly/types'
|
|
12
|
+
|
|
13
|
+
declare const SystemInfo: { platform?: string } | undefined
|
|
14
|
+
|
|
15
|
+
interface FingerlyNativeModule {
|
|
16
|
+
configure(apiKey: string, endpoint: string, platform: string, consent: ConsentState): void
|
|
17
|
+
setConsent(state: ConsentState): void
|
|
18
|
+
identify(
|
|
19
|
+
tag: string | null,
|
|
20
|
+
submit: boolean,
|
|
21
|
+
automatic: boolean,
|
|
22
|
+
success: (json: string) => void,
|
|
23
|
+
failure: (error: string) => void,
|
|
24
|
+
): void
|
|
25
|
+
collect(success: (json: string) => void, failure: (error: string) => void): void
|
|
26
|
+
/** Optional because a native module built before it existed does not have it. */
|
|
27
|
+
deleteStoredIdentity?(success: () => void, failure: (error: string) => void): void
|
|
28
|
+
sdkVersion(): string
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Whether the user has agreed to be identified. Spelled as in `@fingerly/core`
|
|
33
|
+
* and the native SDKs; declared here so this package builds against any copy of
|
|
34
|
+
* `@fingerly/types`, including one that predates consent.
|
|
35
|
+
*/
|
|
36
|
+
export type ConsentState = 'granted' | 'pending' | 'denied'
|
|
37
|
+
|
|
38
|
+
export interface FingerlyOptions extends MobileFingerlyOptions {
|
|
39
|
+
/**
|
|
40
|
+
* The consent to start from, `pending` when omitted. Call `setConsent` once
|
|
41
|
+
* your consent tool has an answer. Until consent is `granted`, `identify()`
|
|
42
|
+
* and `collect()` reject with a `ConsentError` and the native SDK runs no
|
|
43
|
+
* source and sends nothing. Pass `granted` only once the user has agreed, or
|
|
44
|
+
* where another lawful basis applies.
|
|
45
|
+
*/
|
|
46
|
+
consent?: ConsentState
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface IdentifyOptions extends MobileIdentifyOptions {
|
|
50
|
+
/**
|
|
51
|
+
* True for a call the app makes on its own rather than in answer to the
|
|
52
|
+
* user: on start, on a timer, on returning to the foreground. It joins an
|
|
53
|
+
* identification already in flight instead of starting another, and waits
|
|
54
|
+
* out a transient failure instead of repeating it at once. False when
|
|
55
|
+
* omitted. On Android it has no effect until the native Android SDK
|
|
56
|
+
* supports it.
|
|
57
|
+
*/
|
|
58
|
+
automatic?: boolean
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* What `identify({ submit: false })` resolves with. Nothing was sent, so nobody
|
|
63
|
+
* answered, and the raw report is all there is.
|
|
64
|
+
*/
|
|
65
|
+
export interface RawReportResult {
|
|
66
|
+
report: SignalReport
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export class FingerlyError extends Error {
|
|
70
|
+
// Widened to `string` so a subclass can name itself.
|
|
71
|
+
override readonly name: string = 'FingerlyError'
|
|
72
|
+
|
|
73
|
+
constructor(
|
|
74
|
+
message: string,
|
|
75
|
+
readonly status?: number,
|
|
76
|
+
/**
|
|
77
|
+
* How long the server asked the app to wait, in milliseconds, from its
|
|
78
|
+
* `Retry-After`, when the native SDK gave up on a 429 or 503 that named
|
|
79
|
+
* one. Undefined when no wait was named, and on Android until the native
|
|
80
|
+
* Android bridge passes the header on.
|
|
81
|
+
*/
|
|
82
|
+
readonly retryAfterMs?: number,
|
|
83
|
+
) {
|
|
84
|
+
super(message)
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* A call refused because consent is not `granted`: nothing was collected or
|
|
90
|
+
* sent. `code` is the string every Fingerly SDK uses for this failure. Also a
|
|
91
|
+
* `FingerlyError`, so existing handlers keep catching everything this package
|
|
92
|
+
* throws.
|
|
93
|
+
*/
|
|
94
|
+
export class ConsentError extends FingerlyError {
|
|
95
|
+
override readonly name: string = 'ConsentError'
|
|
96
|
+
readonly code = 'consent_required'
|
|
97
|
+
|
|
98
|
+
constructor(readonly state: ConsentState) {
|
|
99
|
+
super(`Fingerly needs consent before it can identify this visitor (consent is ${state})`)
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const CONSENT_REQUIRED = 'consent_required'
|
|
104
|
+
|
|
105
|
+
const CONSENT_STATES: readonly ConsentState[] = ['granted', 'pending', 'denied']
|
|
106
|
+
|
|
107
|
+
function isConsentState(value: unknown): value is ConsentState {
|
|
108
|
+
return CONSENT_STATES.includes(value as ConsentState)
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Loud rather than lenient, as the browser SDK is: a consent tool's `true` or
|
|
113
|
+
* `'accepted'` is a wiring mistake to report, not a state to guess at.
|
|
114
|
+
*/
|
|
115
|
+
function assertConsentState(state: unknown): asserts state is ConsentState {
|
|
116
|
+
if (!isConsentState(state)) {
|
|
117
|
+
throw new TypeError(
|
|
118
|
+
`Fingerly consent must be 'granted', 'pending' or 'denied' (received ${JSON.stringify(state)})`,
|
|
119
|
+
)
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* The state behind a native `consent_required` failure. iOS sends it as
|
|
125
|
+
* `state`; Android sends only the message, which ends with it in a fixed form.
|
|
126
|
+
* Unreadable is `pending`, as the native SDKs read an unknown state.
|
|
127
|
+
*/
|
|
128
|
+
function refusedConsent(record: Record<string, unknown> | undefined, message: string): ConsentState {
|
|
129
|
+
const fromNative = record?.state
|
|
130
|
+
if (isConsentState(fromNative)) return fromNative
|
|
131
|
+
const fromMessage = /\(consent is (\w+)\)/.exec(message)?.[1]
|
|
132
|
+
return isConsentState(fromMessage) ? fromMessage : 'pending'
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* The consent last handed to the native SDK. Module state because the native
|
|
137
|
+
* bridge keeps one client per process, shared by every `FingerlyClient` here.
|
|
138
|
+
*/
|
|
139
|
+
let currentConsent: ConsentState = 'pending'
|
|
140
|
+
|
|
141
|
+
const MISSING_NATIVE_MODULE =
|
|
142
|
+
'@fingerly/lynx could not find its Fingerly native module. Enable Lynx Native ' +
|
|
143
|
+
'Library Autolink, run `pod install` for iOS or sync Gradle for Android, ' +
|
|
144
|
+
'then rebuild the native app. This SDK cannot safely collect a partial ' +
|
|
145
|
+
'fingerprint from JavaScript because that could report a compromised device as clean.'
|
|
146
|
+
|
|
147
|
+
function optionalNativeModule(): FingerlyNativeModule | undefined {
|
|
148
|
+
try {
|
|
149
|
+
return requireFingerly() as FingerlyNativeModule
|
|
150
|
+
} catch {
|
|
151
|
+
return undefined
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function nativeModule(): FingerlyNativeModule {
|
|
156
|
+
const native = optionalNativeModule()
|
|
157
|
+
if (!native) throw new FingerlyError(MISSING_NATIVE_MODULE)
|
|
158
|
+
return native
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function platformName(): SdkPlatform {
|
|
162
|
+
const platform = typeof SystemInfo === 'undefined' ? undefined : SystemInfo?.platform
|
|
163
|
+
if (platform === 'Android') return 'lynx-android'
|
|
164
|
+
if (platform === 'iOS') return 'lynx-ios'
|
|
165
|
+
throw new FingerlyError(
|
|
166
|
+
`@fingerly/lynx supports iOS and Android only; received ${platform ?? 'an unknown platform'}.`,
|
|
167
|
+
)
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
function parseNativeError(raw: unknown): FingerlyError {
|
|
171
|
+
if (raw instanceof FingerlyError) return raw
|
|
172
|
+
|
|
173
|
+
let value: unknown = raw
|
|
174
|
+
if (typeof raw === 'string') {
|
|
175
|
+
try {
|
|
176
|
+
value = JSON.parse(raw)
|
|
177
|
+
} catch {
|
|
178
|
+
return new FingerlyError(raw)
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
const record =
|
|
183
|
+
typeof value === 'object' && value !== null
|
|
184
|
+
? (value as Record<string, unknown>)
|
|
185
|
+
: undefined
|
|
186
|
+
const message =
|
|
187
|
+
typeof record?.message === 'string'
|
|
188
|
+
? record.message
|
|
189
|
+
: value instanceof Error
|
|
190
|
+
? value.message
|
|
191
|
+
: String(value)
|
|
192
|
+
|
|
193
|
+
if (record?.code === CONSENT_REQUIRED) return new ConsentError(refusedConsent(record, message))
|
|
194
|
+
|
|
195
|
+
const parsed =
|
|
196
|
+
typeof record?.code === 'number'
|
|
197
|
+
? record.code
|
|
198
|
+
: typeof record?.code === 'string' && record.code.trim() !== ''
|
|
199
|
+
? Number(record.code)
|
|
200
|
+
: undefined
|
|
201
|
+
const status =
|
|
202
|
+
typeof parsed === 'number' && Number.isInteger(parsed) && parsed > 0 ? parsed : undefined
|
|
203
|
+
|
|
204
|
+
const wait = record?.retryAfterMs
|
|
205
|
+
const retryAfterMs =
|
|
206
|
+
typeof wait === 'number' && Number.isFinite(wait) && wait >= 0 ? wait : undefined
|
|
207
|
+
|
|
208
|
+
return new FingerlyError(message, status, retryAfterMs)
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function invokeNative(
|
|
212
|
+
operation: (success: (json: string) => void, failure: (error: string) => void) => void,
|
|
213
|
+
): Promise<string> {
|
|
214
|
+
return new Promise((resolve, reject) => {
|
|
215
|
+
try {
|
|
216
|
+
operation(resolve, (error) => reject(parseNativeError(error)))
|
|
217
|
+
} catch (error) {
|
|
218
|
+
reject(parseNativeError(error))
|
|
219
|
+
}
|
|
220
|
+
})
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* The native JSON as an object, or a `FingerlyError`.
|
|
225
|
+
*
|
|
226
|
+
* A `SyntaxError`, or a `TypeError` from spreading `null`, would escape a
|
|
227
|
+
* handler that checks `instanceof FingerlyError`, which is the one every
|
|
228
|
+
* caller writes.
|
|
229
|
+
*/
|
|
230
|
+
function parseNative(raw: string): Record<string, unknown> {
|
|
231
|
+
let parsed: unknown
|
|
232
|
+
try {
|
|
233
|
+
parsed = JSON.parse(raw)
|
|
234
|
+
} catch {
|
|
235
|
+
throw new FingerlyError('The SDK produced an unreadable report')
|
|
236
|
+
}
|
|
237
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
238
|
+
throw new FingerlyError('The SDK produced an unreadable report')
|
|
239
|
+
}
|
|
240
|
+
return parsed as Record<string, unknown>
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
244
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
// Named rather than spread, so what reaches the app is what the server said and
|
|
248
|
+
// nothing else: a signal name, a conclusion or an unscored reason in the native
|
|
249
|
+
// JSON is left behind here.
|
|
250
|
+
const SERVER_FIELDS = [
|
|
251
|
+
'requestId',
|
|
252
|
+
'visitorId',
|
|
253
|
+
'visitorIsNew',
|
|
254
|
+
'visitorConfidence',
|
|
255
|
+
'identifiable',
|
|
256
|
+
'duplicate',
|
|
257
|
+
'state',
|
|
258
|
+
'suspectScore',
|
|
259
|
+
'suspectLevel',
|
|
260
|
+
'report',
|
|
261
|
+
] as const
|
|
262
|
+
|
|
263
|
+
function pick(source: Record<string, unknown>, fields: readonly string[]): Record<string, unknown> {
|
|
264
|
+
const picked: Record<string, unknown> = {}
|
|
265
|
+
for (const field of fields) {
|
|
266
|
+
// An explicit null survives: an unscored check is null, not absent and not 0.
|
|
267
|
+
if (source[field] !== undefined) picked[field] = source[field]
|
|
268
|
+
}
|
|
269
|
+
return picked
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
// A native build may write null or leave the key out. The types promise null,
|
|
273
|
+
// so an answer the server did not give reads the same on both platforms: never
|
|
274
|
+
// undefined, and never an invented 0 or false.
|
|
275
|
+
const NULLABLE_FIELDS = [
|
|
276
|
+
'visitorIsNew',
|
|
277
|
+
'visitorConfidence',
|
|
278
|
+
'identifiable',
|
|
279
|
+
'duplicate',
|
|
280
|
+
'suspectScore',
|
|
281
|
+
'suspectLevel',
|
|
282
|
+
] as const
|
|
283
|
+
|
|
284
|
+
function serverAnswer(parsed: Record<string, unknown>): NativeIdentifyResult {
|
|
285
|
+
const answer = pick(parsed, SERVER_FIELDS)
|
|
286
|
+
for (const field of NULLABLE_FIELDS) {
|
|
287
|
+
if (answer[field] === undefined) answer[field] = null
|
|
288
|
+
}
|
|
289
|
+
return answer as unknown as NativeIdentifyResult
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
function rawReport(parsed: Record<string, unknown>): RawReportResult {
|
|
293
|
+
if (!isRecord(parsed.report)) throw new FingerlyError('The SDK produced an unreadable report')
|
|
294
|
+
return { report: parsed.report as unknown as SignalReport }
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
export class FingerlyClient {
|
|
298
|
+
/** The consent last given to the native SDK, by `load` or `setConsent`. */
|
|
299
|
+
get consent(): ConsentState {
|
|
300
|
+
return currentConsent
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* Record the user's answer. Synchronous and safe to repeat; applies to the
|
|
305
|
+
* next call and to any call in flight, which then rejects with a
|
|
306
|
+
* `ConsentError` instead of submitting. Throws a `TypeError` for anything
|
|
307
|
+
* that is not one of the three states.
|
|
308
|
+
*/
|
|
309
|
+
setConsent(state: ConsentState): void {
|
|
310
|
+
assertConsentState(state)
|
|
311
|
+
const native = nativeModule()
|
|
312
|
+
try {
|
|
313
|
+
native.setConsent(state)
|
|
314
|
+
} catch (error) {
|
|
315
|
+
throw parseNativeError(error)
|
|
316
|
+
}
|
|
317
|
+
currentConsent = state
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/**
|
|
321
|
+
* Collects and submits, and resolves with the server's answer. With
|
|
322
|
+
* `submit: false` nothing is sent and only the raw report comes back.
|
|
323
|
+
* Rejects with a `ConsentError` while consent is not `granted`.
|
|
324
|
+
*/
|
|
325
|
+
identify(options: IdentifyOptions & { submit: false }): Promise<RawReportResult>
|
|
326
|
+
identify(options?: IdentifyOptions & { submit?: true }): Promise<NativeIdentifyResult>
|
|
327
|
+
identify(options: IdentifyOptions): Promise<NativeIdentifyResult | RawReportResult>
|
|
328
|
+
async identify(options: IdentifyOptions = {}): Promise<NativeIdentifyResult | RawReportResult> {
|
|
329
|
+
const native = nativeModule()
|
|
330
|
+
const raw = await invokeNative((success, failure) =>
|
|
331
|
+
native.identify(
|
|
332
|
+
options.tag ?? null,
|
|
333
|
+
options.submit !== false,
|
|
334
|
+
options.automatic === true,
|
|
335
|
+
success,
|
|
336
|
+
failure,
|
|
337
|
+
),
|
|
338
|
+
)
|
|
339
|
+
const parsed = parseNative(raw)
|
|
340
|
+
return options.submit === false ? rawReport(parsed) : serverAnswer(parsed)
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/** Submits nothing, but still needs consent: rejects with a `ConsentError` without it. */
|
|
344
|
+
async collect(): Promise<SignalReport> {
|
|
345
|
+
const native = nativeModule()
|
|
346
|
+
const raw = await invokeNative((success, failure) => native.collect(success, failure))
|
|
347
|
+
return parseNative(raw) as unknown as SignalReport
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* Loading collects and sends nothing, whatever the consent. The consent passed
|
|
353
|
+
* here, or `pending` when there is none, replaces what the native SDK held.
|
|
354
|
+
*/
|
|
355
|
+
export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
|
|
356
|
+
const consent = options.consent ?? 'pending'
|
|
357
|
+
assertConsentState(consent)
|
|
358
|
+
|
|
359
|
+
const native = nativeModule()
|
|
360
|
+
try {
|
|
361
|
+
native.configure(options.apiKey, options.endpoint ?? '', platformName(), consent)
|
|
362
|
+
} catch (error) {
|
|
363
|
+
throw parseNativeError(error)
|
|
364
|
+
}
|
|
365
|
+
currentConsent = consent
|
|
366
|
+
return new FingerlyClient()
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Delete the install record the native SDK keeps on the device, for a user's
|
|
371
|
+
* erasure request or account deletion. Needs no `load` and no consent, and
|
|
372
|
+
* sends nothing; resolves once no record remains, including when there was
|
|
373
|
+
* none. The next consented identification starts a new record, so set consent
|
|
374
|
+
* to `'denied'` first to stop identifying as well. Rejects with a
|
|
375
|
+
* `FingerlyError` when the delete fails or the native SDK predates this call.
|
|
376
|
+
*/
|
|
377
|
+
export async function deleteStoredIdentity(): Promise<void> {
|
|
378
|
+
const native = nativeModule()
|
|
379
|
+
const remove = native.deleteStoredIdentity
|
|
380
|
+
if (typeof remove !== 'function') {
|
|
381
|
+
throw new FingerlyError('deleteStoredIdentity is not available in the native Fingerly SDK')
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
await new Promise<void>((resolve, reject) => {
|
|
385
|
+
try {
|
|
386
|
+
remove.call(native, () => resolve(), (error) => reject(parseNativeError(error)))
|
|
387
|
+
} catch (error) {
|
|
388
|
+
reject(parseNativeError(error))
|
|
389
|
+
}
|
|
390
|
+
})
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
export function nativeVersion(): string | undefined {
|
|
394
|
+
try {
|
|
395
|
+
return optionalNativeModule()?.sdkVersion()
|
|
396
|
+
} catch {
|
|
397
|
+
return undefined
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
export type {
|
|
402
|
+
IntegrityReport,
|
|
403
|
+
Lie,
|
|
404
|
+
NativeIdentifyResult,
|
|
405
|
+
SdkPlatform,
|
|
406
|
+
SignalOutcome,
|
|
407
|
+
SignalReport,
|
|
408
|
+
SignalStatus,
|
|
409
|
+
} from '@fingerly/types'
|
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** @lynxmodule */
|
|
2
|
+
export declare class Fingerly {
|
|
3
|
+
configure(apiKey: string, endpoint: string, platform: string, consent: string): void;
|
|
4
|
+
setConsent(state: string): void;
|
|
5
|
+
identify(tag: string | null, submit: boolean, automatic: boolean, success: (json: string) => void, failure: (error: string) => void): void;
|
|
6
|
+
collect(success: (json: string) => void, failure: (error: string) => void): void;
|
|
7
|
+
deleteStoredIdentity(success: () => void, failure: (error: string) => void): void;
|
|
8
|
+
sdkVersion(): string;
|
|
9
|
+
}
|