@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/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'
@@ -0,0 +1,2 @@
1
+ export { Fingerly } from '../generated/Fingerly';
2
+
@@ -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
+ }