@fingerly/next 0.2.1 → 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
@@ -1,23 +1,112 @@
1
- # @fingerly/next
1
+ <p align="center">
2
+ <a href="https://fingerly.io">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/logo-dark.svg">
5
+ <img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/logo-light.svg" alt="Fingerly" height="44">
6
+ </picture>
7
+ </a>
8
+ </p>
9
+
10
+ <p align="center"><b>Fingerly for Next.js</b><br>The React binding, with Next's configuration, client boundary and Server Action handling built in.</p>
11
+
12
+ <p align="center">
13
+ <a href="https://www.npmjs.com/package/@fingerly/next"><img src="https://img.shields.io/npm/v/@fingerly/next?style=flat-square" alt="npm version"></a>
14
+ <a href="https://www.npmjs.com/package/@fingerly/next"><img src="https://img.shields.io/npm/dm/@fingerly/next?style=flat-square" alt="npm downloads"></a>
15
+ <a href="https://github.com/fingerly-io/sdks/blob/main/client/web/next/LICENSE"><img src="https://img.shields.io/npm/l/@fingerly/next?style=flat-square" alt="Apache-2.0 licence"></a>
16
+ <img src="https://img.shields.io/badge/next.js-15%2B-blue?style=flat-square" alt="Next.js 15 or newer">
17
+ </p>
18
+
19
+ <p align="center"><img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/banner.webp" alt="Fingerly" width="100%"></p>
20
+
21
+ ## What is this
22
+
23
+ `@fingerly/next` is the Next.js integration. It wraps
24
+ [`@fingerly/react`](https://www.npmjs.com/package/@fingerly/react) and adds the
25
+ three things that are actually about Next: where the configuration comes from,
26
+ where the client boundary sits, and how an identification reaches a Server
27
+ Action. [Fingerly](https://fingerly.io) helps you protect signups, logins and
28
+ payments from fraud and abuse.
29
+
30
+ > **Not for apps.** This binding runs the browser SDK, which collects nothing
31
+ > that identifies the device inside an app's web view (`WKWebView`, Android
32
+ > `WebView`, Capacitor, Cordova, Ionic, React Native WebView, Flutter WebView,
33
+ > Electron) and answers there with an empty `visitorId`. Use the Fingerly iOS or
34
+ > Android SDK, or the React Native, Flutter or Lynx bridge, in an app; see
35
+ > section 3.3 of the
36
+ > [privacy notes](https://github.com/fingerly-io/sdks/blob/main/docs/privacy.md).
37
+
38
+ ## Getting started
39
+
40
+ 1. **Get a key.** Create a public SDK key in the dashboard
41
+ ([how keys work](https://docs.fingerly.io/docs/api-keys)).
42
+ 2. **Install.**
43
+
44
+ ```sh
45
+ npm install @fingerly/next
46
+ # or: pnpm add @fingerly/next
47
+ # or: yarn add @fingerly/next
48
+ ```
49
+
50
+ 3. **Add the provider, then identify.**
51
+
52
+ ```tsx
53
+ // app/layout.tsx (a Server Component)
54
+ import { FingerlyProvider } from '@fingerly/next'
55
+
56
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
57
+ return (
58
+ <html>
59
+ <body>
60
+ {/* consent="granted" only once you have consent (or know none is required here; see Consent below) */}
61
+ <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY} consent="granted">
62
+ {children}
63
+ </FingerlyProvider>
64
+ </body>
65
+ </html>
66
+ )
67
+ }
68
+ ```
69
+
70
+ ```tsx
71
+ 'use client'
72
+ import { useIdentify } from '@fingerly/next'
73
+
74
+ export function Checkout() {
75
+ const { identify, isLoading } = useIdentify()
76
+ …
77
+ }
78
+ ```
79
+
80
+ 4. **Decide on your backend.** Send the `requestId` that `await identify()`
81
+ resolves with to your server and act on its decision; see
82
+ [Decide on your backend](#decide-on-your-backend).
2
83
 
3
- Next.js integration. It wraps [`@fingerly/react`](../react/README.md) and adds
4
- the three things that are actually about Next: where the configuration comes
5
- from, where the client boundary sits, and how an identification reaches a
6
- Server Action.
7
-
8
- Requires Next **15 or newer** and React **19** (App Router or Pages Router).
9
- Tested against Next 16.
10
-
11
- ```
12
- pnpm add @fingerly/next
13
- ```
84
+ The package is marked `'use client'`, so the provider is a client boundary and
85
+ your layout does not have to become one. Pages Router is the same component in
86
+ `_app.tsx`.
14
87
 
15
- **Not for apps.** This binding runs the browser SDK, which collects nothing
16
- inside an app's web view (Capacitor, Cordova, Ionic, React Native WebView,
17
- `WKWebView`, Android `WebView`, Electron). Use the Fingerly iOS or Android SDK
18
- in an app; see [docs/privacy.md §3.3](../../../docs/privacy.md).
88
+ Mounting it collects nothing. When to identify stays the page's decision.
19
89
 
20
- ## Configure
90
+ ## Contents
91
+
92
+ - [Configure the key](#configure-the-key)
93
+ - [Identify](#identify)
94
+ - [Consent](#consent)
95
+ - [First-party endpoints](#first-party-endpoints)
96
+ - [Options](#options)
97
+ - [Carry it into a Server Action](#carry-it-into-a-server-action)
98
+ - [Decide on your backend](#decide-on-your-backend)
99
+ - [The two entries](#the-two-entries)
100
+ - [Errors](#errors)
101
+ - [What this does not do](#what-this-does-not-do)
102
+ - [More](#more)
103
+ - [TypeScript](#typescript)
104
+ - [Requirements](#requirements)
105
+ - [Documentation](#documentation)
106
+ - [Help](#help)
107
+ - [Licence](#licence)
108
+
109
+ ## Configure the key
21
110
 
22
111
  Read the key in a Server Component and pass it down:
23
112
 
@@ -46,41 +135,56 @@ Either way the key is a **public** SDK key, scoped to the origins you list
46
135
  against it. A **secret** key is refused by the API whenever a request carries
47
136
  an `Origin`, so the mistake either route invites cannot silently work.
48
137
 
49
- ## Add the provider
138
+ ## Identify
139
+
140
+ The hooks are `@fingerly/react`'s, re-exported so you install one package
141
+ (`useIdentify`, `useFingerly`, `createFingerlyStore`):
50
142
 
51
143
  ```tsx
52
- // app/layout.tsx (still a Server Component)
53
- import { FingerlyProvider } from '@fingerly/next'
144
+ 'use client'
145
+ import { useIdentify } from '@fingerly/next'
54
146
 
55
- export default function RootLayout({ children }: { children: React.ReactNode }) {
56
- return (
57
- <html>
58
- <body>
59
- {/* consent="granted" only once you have consent (or know none is required here; see docs/privacy.md §4) */}
60
- <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY} consent="granted">
61
- {children}
62
- </FingerlyProvider>
63
- </body>
64
- </html>
65
- )
147
+ export function Checkout() {
148
+ const { identify, isLoading } = useIdentify()
149
+ …
66
150
  }
67
151
  ```
68
152
 
69
- The package is marked `'use client'`, so the provider is a client boundary and
70
- your layout does not have to become one. Pages Router is the same component in
71
- `_app.tsx`.
153
+ Send the `requestId` that `await identify()` resolves with to your backend and
154
+ act on its decision (see [Decide on your backend](#decide-on-your-backend)).
155
+ `isSuspicious`, `suspectScore` and `suspectLevel` are a UI hint only; never gate
156
+ an action on them in the page.
72
157
 
73
- Mounting it collects nothing. When to identify stays the page's decision.
158
+ `identify()` runs one collection pass (a 350 ms budget by default) and posts
159
+ once, in a single round trip to `POST /api/v1/ingest`, resolving with the
160
+ server's answer: `requestId`, `visitorId`, `identifiable`, and `suspectScore`
161
+ and `suspectLevel` unless the key hides them. Each report carries a single-use
162
+ freshness ticket held in memory only; when none is held, the ticket request
163
+ runs in parallel with collection and never holds up or fails `identify()`.
74
164
 
75
- Consent defaults to `pending`, and nothing is collected or sent until it is
76
- `granted`. A site with a consent banner passes the banner's answer instead of
77
- `"granted"`, as below.
165
+ `visitorId` is `""` (and `visitorIsNew` is `false`) whenever `identifiable` is
166
+ `false`, inside an app's web view, or when the server declines to name a
167
+ high-risk visitor it has not seen before. To inspect the raw `SignalReport`
168
+ locally without submitting anything, call
169
+ `(await useFingerly().client()).collect()`.
170
+
171
+ `useIdentify({ immediate: true })` is safe in a Next app for the reason it is
172
+ safe anywhere: it runs in an effect, and effects do not run during a server
173
+ render. The page renders on the server, collects after hydration, and every
174
+ component that asks shares the one identification.
78
175
 
79
- ### Waiting for consent
176
+ The full surface (`immediate`, `suspend`, `tag`, `incognitoDetection`,
177
+ `refresh`, and everything you get back) is documented in the
178
+ [React binding's README](https://github.com/fingerly-io/sdks/tree/main/client/web/react#readme).
80
179
 
81
- Consent defaults to `pending`. When identification needs the visitor's consent
82
- first, pass `consent` with what your consent tool says now. It is a prop rather than an environment
83
- variable, because it is the visitor's decision rather than the deployment's:
180
+ ## Consent
181
+
182
+ Consent defaults to `pending`, and nothing is collected or sent until it is
183
+ `granted`. A site with a consent banner passes the banner's answer instead of
184
+ `"granted"`. When identification needs the visitor's consent first, pass
185
+ `consent` with what your consent tool says now. It is a prop rather than an
186
+ environment variable, because it is the visitor's decision rather than the
187
+ deployment's:
84
188
 
85
189
  ```tsx
86
190
  'use client'
@@ -95,29 +199,66 @@ While it is not `granted` nothing is collected or sent,
95
199
  `useIdentify({ immediate: true })` and `<FingerlyRequestId />` wait, and a
96
200
  manual `identify()` fails with a `ConsentError`. Once it becomes `granted` the
97
201
  waiting identification runs, once. The details are in the
98
- [React binding's README](../react/README.md#waiting-for-consent).
202
+ [React binding's README](https://github.com/fingerly-io/sdks/tree/main/client/web/react#consent).
99
203
 
100
- ## Identify
204
+ Pass `granted` only once you have consent, or know none is required here. See
205
+ section 4 of the
206
+ [privacy notes](https://github.com/fingerly-io/sdks/blob/main/docs/privacy.md),
207
+ [privacy and consent](https://docs.fingerly.io/docs/privacy-and-consent) and
208
+ [consent tools](https://docs.fingerly.io/docs/consent-tools).
101
209
 
102
- The hooks are `@fingerly/react`'s, re-exported so you install one package:
210
+ ## First-party endpoints
103
211
 
104
- ```tsx
105
- 'use client'
106
- import { useIdentify } from '@fingerly/next'
212
+ Serving the SDK's submissions from your own origin is what gets them past
213
+ content blockers. The proxy for it lives in `@fingerly/node`, because it holds a
214
+ server secret and has to forward the visitor's real address rather than your
215
+ server's. Create a proxy in the dashboard, put it in the route file for the path
216
+ it issued, and give the provider `endpoints="/k7x2qm4a"`:
107
217
 
108
- export function Checkout() {
109
- const { identify, isSuspicious, suspectLevel, isLoading } = useIdentify()
110
- …
218
+ ```ts
219
+ // app/k7x2qm4a/route.ts
220
+ import { Fingerly } from '@fingerly/node'
221
+
222
+ // Built on the first request rather than at import, so `next build` does not
223
+ // need the proxy key.
224
+ let proxy: ((request: Request) => Promise<Response>) | undefined
225
+
226
+ export function POST(request: Request) {
227
+ proxy ??= Fingerly.createProxy({
228
+ proxyKey: process.env.FINGERLY_PROXY_KEY!,
229
+ // The last X-Forwarded-For entry is the address your own server or load
230
+ // balancer saw. Read a CDN's client-IP header instead only when traffic
231
+ // can reach this app through that CDN alone.
232
+ clientIp: (req) => req.headers.get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? '',
233
+ })
234
+ return proxy(request)
111
235
  }
112
236
  ```
113
237
 
114
- `useIdentify({ immediate: true })` is safe in a Next app for the reason it is
115
- safe anywhere: it runs in an effect, and effects do not run during a server
116
- render. The page renders on the server, collects after hydration, and every
117
- component that asks shares the one identification.
238
+ Pass the path as a string. An array works too, and is compared by its
239
+ contents, so `endpoints={['/k7x2qm4a']}` does not start a new identification
240
+ when the layout renders again.
241
+
242
+ `@fingerly/next/server` also re-exports the proxy factory from `@fingerly/node`
243
+ as `createFingerlyProxy` (with its `FingerlyProxyOptions` type). See
244
+ [proxy integrations](https://docs.fingerly.io/docs/proxy-integrations) and the
245
+ [Node SDK](https://docs.fingerly.io/docs/sdks/node).
118
246
 
119
- The full surface (`immediate`, `suspend`, `tag`, `refresh`) is documented in
120
- the [React binding's README](../react/README.md).
247
+ ## Options
248
+
249
+ `<FingerlyProvider>` props:
250
+
251
+ | Prop | Type | Notes |
252
+ | --- | --- | --- |
253
+ | `apiKey` | `string` | A public SDK key. Overrides `NEXT_PUBLIC_FINGERLY_API_KEY`. |
254
+ | `endpoints` | `string \| string[]` | Ordered first-party ingestion paths or URLs, compared by contents. Overrides `NEXT_PUBLIC_FINGERLY_ENDPOINTS`, which is a JSON array of strings. |
255
+ | `fallbackToDefaultEndpoint` | `boolean` | Opt into the Fingerly API after the custom endpoints fail. |
256
+ | `consent` | `'pending' \| 'granted' \| 'denied'` | Defaults to `pending`. Never read from the environment. |
257
+ | `incognitoDetection` | `'standard' \| 'extended'` | Defaults to `standard`, which checks for private browsing without writing to the visitor's storage; `extended` adds a further check on Chromium browsers inside the same budget. |
258
+ | `apiVersion` | `string` | API route version. Defaults to `v1`. |
259
+
260
+ `<FingerlyRequestId />` takes `name` (the field name), `tag` and `immediate`
261
+ (on by default). The remaining options are `@fingerly/react`'s.
121
262
 
122
263
  ## Carry it into a Server Action
123
264
 
@@ -129,11 +270,13 @@ travel with the submission:
129
270
  import { FingerlyRequestId } from '@fingerly/next'
130
271
  import { signUp } from './actions'
131
272
 
132
- export default function Page() {
273
+ // attemptId: a random value your server issued for this form and keeps in the
274
+ // visitor's session (for example in an HttpOnly cookie).
275
+ export default function Page({ attemptId }: { attemptId: string }) {
133
276
  return (
134
277
  <form action={signUp}>
135
278
  <input name="email" />
136
- <FingerlyRequestId />
279
+ <FingerlyRequestId tag={`signup:${attemptId}`} />
137
280
  <button>Create account</button>
138
281
  </form>
139
282
  )
@@ -143,94 +286,184 @@ export default function Page() {
143
286
  ```ts
144
287
  // app/signup/actions.ts
145
288
  'use server'
289
+ import { cookies, headers } from 'next/headers'
146
290
  import { readRequestId } from '@fingerly/next/server'
291
+ import { decide } from '@/lib/fingerly' // the check below
147
292
 
148
293
  export async function signUp(formData: FormData) {
149
294
  const requestId = readRequestId(formData)
150
- // correlate the signup with the identification, or proceed without one
295
+ if (!requestId) return { error: 'Please try again.' }
296
+
297
+ const attemptId = (await cookies()).get('signup_attempt')?.value ?? ''
298
+ const clientIp = (await headers()).get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? ''
299
+
300
+ const decision = await decide(requestId, `signup:${attemptId}`, clientIp)
301
+ if (decision === 'refuse') return { error: 'Please try again.' }
302
+ if (decision === 'challenge') return { challenge: true }
303
+ // allow, or queue for review
151
304
  }
152
305
  ```
153
306
 
307
+ ## Decide on your backend
308
+
309
+ The `requestId` in the form is untrusted form input until your backend has
310
+ verified it: whoever submits the form chooses its value. Read the event with
311
+ the secret key and run the checks described in
312
+ [server-side verification](https://docs.fingerly.io/docs/server-side-verification):
313
+
314
+ ```ts
315
+ // lib/fingerly.ts (server only)
316
+ import { BlockList } from 'node:net'
317
+ import { Fingerly, FingerlyAPIError } from '@fingerly/node'
318
+
319
+ const fingerly = new Fingerly({ secretKey: process.env.FINGERLY_SECRET_KEY })
320
+ const MAX_AGE_MS = 2 * 60 * 1000
321
+
322
+ // expectedTag comes from your server session, never from the form. clientIp is
323
+ // the address of this form post, as your platform resolves it.
324
+ export async function decide(requestId: string, expectedTag: string, clientIp: string) {
325
+ let event
326
+ try {
327
+ event = await fingerly.events.get(requestId) // 1. it exists
328
+ } catch (error) {
329
+ if (error instanceof FingerlyAPIError && error.isPending) return 'retry'
330
+ if (error instanceof FingerlyAPIError && error.code === 'event_not_found') return 'refuse'
331
+ throw error
332
+ }
333
+ if (event.tag !== expectedTag) return 'refuse' // 2. this action
334
+ if (Date.now() - Date.parse(event.occurred_at) > MAX_AGE_MS) return 'refuse' // 3. recent
335
+ if (!event.identifiable || event.suspect_score === null) return 'refuse' // 4. identifiable and scored
336
+ if (event.suspect_level === 'high') return 'review' // 5. your policy
337
+ // 6. another network than this post: step up (for example a second factor)
338
+ if (!event.ip_network || !inNetwork(clientIp, event.ip_network)) return 'challenge'
339
+ if (event.suspect_level === 'medium') return 'challenge'
340
+ return 'allow'
341
+ }
342
+
343
+ // ip_network is the /24 (IPv4) or /40 (IPv6) the identification came from;
344
+ // the API never returns the address itself.
345
+ function inNetwork(ip: string, cidr: string): boolean {
346
+ const [base = '', bits = '0'] = cidr.split('/')
347
+ const type = base.includes(':') ? 'ipv6' : 'ipv4'
348
+ const list = new BlockList()
349
+ list.addSubnet(base, Number(bits), type)
350
+ return list.check(ip, type)
351
+ }
352
+ ```
353
+
354
+ One event can back more than one decision inside the recency window. For a
355
+ flow that must be single use, record the `requestId` with the outcome and refuse
356
+ one you have already seen.
357
+
154
358
  `<FingerlyRequestId />` identifies on mount and renders a hidden field. It is in
155
359
  the server-rendered HTML **empty** rather than absent, which is deliberate: a
156
360
  form submitted before the SDK finished, or with JavaScript disabled, is a
157
361
  normal event, and the server can tell it apart from a form that never carried a
158
- field at all.
362
+ field at all. Turn `immediate` off in a form that identifies at submit time
363
+ instead.
159
364
 
160
365
  `readRequestId()` returns `null` for all of those cases rather than throwing:
161
366
  what to do about an unidentified submission is a policy your server owns. It
162
- also refuses anything that is not a short opaque token: the field arrives from
163
- the page, which means it arrives from whoever is driving the browser, and a
164
- server that joins or logs it unchecked is one hand-written `<input>` away from
165
- storing what the visitor typed.
367
+ also refuses anything that is not a short opaque token (at most 128 characters
368
+ of letters, digits, `_` and `-`): the field arrives from the page, which means
369
+ it arrives from whoever is driving the browser, and a server that joins or logs
370
+ it unchecked is one hand-written `<input>` away from storing what the visitor
371
+ typed.
166
372
 
167
373
  Both halves agree on the field name through one exported constant,
168
- `REQUEST_ID_FIELD`. Pass `name` to `<FingerlyRequestId />` and the same `name` to
169
- `readRequestId()` if you need a different one.
374
+ `REQUEST_ID_FIELD` (`fingerly_request_id`). Pass `name` to
375
+ `<FingerlyRequestId />` and the same `name` to `readRequestId()` if you need a
376
+ different one.
170
377
 
171
- ## The two entries, and why
378
+ ## The two entries
172
379
 
173
380
  | Import | Runs | Contains |
174
381
  | --- | --- | --- |
175
382
  | `@fingerly/next` | the browser | provider, field, hooks (a `'use client'` module) |
176
- | `@fingerly/next/server` | the server | `readRequestId`, `REQUEST_ID_FIELD` (no React) |
383
+ | `@fingerly/next/server` | the server | `readRequestId`, `REQUEST_ID_FIELD`, `createFingerlyProxy` (no React) |
177
384
 
178
385
  A Server Action that imported `readRequestId` from the main entry would get a
179
386
  client reference rather than a function: the import succeeds and the call fails
180
387
  at runtime, which is the worst way to learn about a boundary. Hence the split.
181
388
 
182
- ## Running the demo
389
+ ## Errors
183
390
 
184
- `demo/` is a real Next application: a Server Component layout, a client page,
185
- and a Server Action reading the field back:
391
+ The error types are `@fingerly/react`'s (`ConsentError`, `TransportError`,
392
+ `FingerlyServerError`), documented in the
393
+ [React binding's README](https://github.com/fingerly-io/sdks/tree/main/client/web/react#errors).
394
+ Two things are particular to this package:
186
395
 
187
- ```
396
+ - A missing key is reported once on the console and the page keeps rendering;
397
+ `identify()` then fails with the SDK's own message about a missing key.
398
+ - A `NEXT_PUBLIC_FINGERLY_ENDPOINTS` that is not a non-empty JSON array of
399
+ strings is reported once and ignored, rather than thrown from a render.
400
+
401
+ ## What this does not do
402
+
403
+ **It does not proxy the API itself.** See [First-party endpoints](#first-party-endpoints):
404
+ the proxy comes from `@fingerly/node`.
405
+
406
+ **It does not read events back.** `identify()` resolves in one round trip with
407
+ the server's client-facing answer (`visitorId`, `identifiable`, and
408
+ `suspectScore` and `suspectLevel` unless the key hides them), so there is
409
+ nothing to fetch afterwards in the page. Reading full stored events and their
410
+ risk signals on your backend is `@fingerly/node`'s job (see
411
+ [server-side verification](https://docs.fingerly.io/docs/server-side-verification)).
412
+
413
+ ## More
414
+
415
+ <details>
416
+ <summary>Running the demo</summary>
417
+
418
+ `demo/` (in the
419
+ [repository](https://github.com/fingerly-io/sdks/tree/main/client/web/next)) is
420
+ a real Next application: a Server Component layout, a client page, and a Server
421
+ Action reading the field back:
422
+
423
+ ```sh
188
424
  pnpm --filter @fingerly/next demo # http://localhost:4178
189
425
  ```
190
426
 
191
- It collects and submits nothing until you give it somewhere to submit: put `FINGERLY_API_KEY`, `FINGERLY_ENDPOINT` and `FINGERLY_SUBMIT=true` in
192
- `demo/.env.local` (gitignored), with a key whose allowed origins include the
193
- port you are running it on. Then the identification produces a real
194
- `requestId`, the hidden field carries it, and the action prints the one it
195
- read.
427
+ Put `FINGERLY_API_KEY` and `FINGERLY_ENDPOINT` in `demo/.env.local` (gitignored),
428
+ with a key whose allowed origins include the port you are running it on. Then
429
+ the identification produces a real `requestId`, the hidden field carries it, and
430
+ the action prints the one it read.
196
431
 
197
- Open it twice, in an ordinary window and a private one, and watch the incognito
198
- card change.
432
+ </details>
199
433
 
200
- ## What this deliberately does not do
434
+ ## TypeScript
201
435
 
202
- **It does not proxy the API itself.** Serving the SDK's submissions from your
203
- own origin is what gets them past content blockers, and the proxy for it lives
204
- in `@fingerly/node`, because it holds a server secret and has to forward the
205
- visitor's real address rather than your server's. Create a proxy in the
206
- dashboard, put it in the route file for the path it issued, and give the
207
- provider `endpoints="/k7x2qm4a"`:
436
+ Types ship with the package, for both entries. The main entry exports
437
+ `FingerlyNextProviderProps`, `FingerlyRequestIdProps`, `FingerlyReactOptions`,
438
+ `FingerlyState`, `FingerlyStore`, `UseIdentifyOptions`, `UseIdentifyReturn`,
439
+ `IdentifyAnswer`, `IdentifyOptions`, `IdentifyResult`, `IncognitoDetection`,
440
+ `ConsentState`, `SuspectLevel`, `SignalReport` and `Confidence`, and the values
441
+ `FingerlyProvider`, `FingerlyRequestId`, `useIdentify`, `useFingerly`,
442
+ `createFingerlyStore`, `ConsentError`, `TransportError`, `FingerlyServerError`
443
+ and `REQUEST_ID_FIELD`. `@fingerly/next/server` exports `readRequestId`,
444
+ `REQUEST_ID_FIELD`, `createFingerlyProxy` and `FingerlyProxyOptions`. Both
445
+ entries ship ES module and CommonJS builds.
208
446
 
209
- ```ts
210
- // app/k7x2qm4a/route.ts
211
- import { Fingerly } from '@fingerly/node'
447
+ ## Requirements
212
448
 
213
- // Built on the first request rather than at import, so `next build` does not
214
- // need the proxy key.
215
- let proxy: ((request: Request) => Promise<Response>) | undefined
449
+ Next **15 or newer** and React **19** (App Router or Pages Router). Tested
450
+ against Next 16. The browser SDK it wraps needs ES2020 with `fetch` and
451
+ `AbortController`: every current version of Chrome, Edge, Firefox and Safari.
452
+ The `@fingerly/next/server` entry depends on `@fingerly/node`, which is
453
+ installed with it.
216
454
 
217
- export function POST(request: Request) {
218
- proxy ??= Fingerly.createProxy({
219
- proxyKey: process.env.FINGERLY_PROXY_KEY!,
220
- // The last X-Forwarded-For entry is the address your own server or load
221
- // balancer saw. Read a CDN's client-IP header instead only when traffic
222
- // can reach this app through that CDN alone.
223
- clientIp: (req) => req.headers.get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? '',
224
- })
225
- return proxy(request)
226
- }
227
- ```
455
+ ## Documentation
228
456
 
229
- Pass the path as a string. An array works too, and is compared by its
230
- contents, so `endpoints={['/k7x2qm4a']}` does not start a new identification
231
- when the layout renders again.
457
+ The Next.js guide is at
458
+ [docs.fingerly.io](https://docs.fingerly.io/docs/sdks/nextjs). The React binding
459
+ underneath is [`@fingerly/react`](https://www.npmjs.com/package/@fingerly/react).
460
+
461
+ ## Help
462
+
463
+ Open an issue on [fingerly-io/sdks](https://github.com/fingerly-io/sdks/issues),
464
+ or write to [support@fingerly.io](mailto:support@fingerly.io). Security issues:
465
+ [security@fingerly.io](mailto:security@fingerly.io).
466
+
467
+ ## Licence
232
468
 
233
- **It does not read events back.** It does not need to: `identify()` resolves
234
- with the server's answer (`visitorId`, and `suspectScore` and `suspectLevel`
235
- unless the key hides them), so there is nothing to fetch afterwards. Reading stored
236
- events for reporting is `@fingerly/node`'s job.
469
+ [Apache-2.0](https://github.com/fingerly-io/sdks/blob/main/client/web/next/LICENSE). Fingerly is a product of Badele LLC.
package/dist/index.cjs CHANGED
@@ -79,7 +79,7 @@ function FingerlyProvider(props) {
79
79
  ...props.apiVersion === void 0 ? {} : { apiVersion: props.apiVersion },
80
80
  ...endpoints === void 0 ? {} : { endpoints },
81
81
  ...props.fallbackToDefaultEndpoint === void 0 ? {} : { fallbackToDefaultEndpoint: props.fallbackToDefaultEndpoint },
82
- ...props.submit === void 0 ? {} : { submit: props.submit },
82
+ ...props.incognitoDetection === void 0 ? {} : { incognitoDetection: props.incognitoDetection },
83
83
  ...props.consent === void 0 ? {} : { consent: props.consent },
84
84
  children: props.children
85
85
  }
@@ -94,8 +94,8 @@ var REQUEST_ID_FIELD = "fingerly_request_id";
94
94
 
95
95
  // src/field.tsx
96
96
  var import_jsx_runtime2 = require("react/jsx-runtime");
97
- function FingerlyRequestId({ name, immediate = true } = {}) {
98
- const { requestId } = (0, import_react2.useIdentify)({ immediate });
97
+ function FingerlyRequestId({ name, immediate = true, tag } = {}) {
98
+ const { requestId } = (0, import_react2.useIdentify)({ immediate, ...tag === void 0 ? {} : { tag } });
99
99
  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
100
100
  "input",
101
101
  {
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { ConsentState } from '@fingerly/react';
2
- export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, SignalReport, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
1
+ import { IncognitoDetection, ConsentState } from '@fingerly/react';
2
+ export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyAnswer, IdentifyOptions, IdentifyResult, IncognitoDetection, SignalReport, SuspectLevel, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
3
3
  import { ReactNode } from 'react';
4
4
  export { R as REQUEST_ID_FIELD } from './field-name-CAkWsUa5.cjs';
5
5
 
@@ -16,8 +16,8 @@ interface FingerlyNextProviderProps {
16
16
  endpoints?: string | readonly string[];
17
17
  /** Opt into the Fingerly API after custom endpoints fail. */
18
18
  fallbackToDefaultEndpoint?: boolean;
19
- /** Collect and score without submitting anything. */
20
- submit?: boolean;
19
+ /** Opt-in extended incognito probe control (`'standard'` or `'extended'`). */
20
+ incognitoDetection?: IncognitoDetection;
21
21
  /**
22
22
  * Whether the visitor has agreed to be identified. Defaults to `pending`.
23
23
  *
@@ -44,6 +44,14 @@ interface FingerlyRequestIdProps {
44
44
  * that identifies at submit time instead.
45
45
  */
46
46
  immediate?: boolean;
47
+ /**
48
+ * Correlation tag echoed on the event, such as `signup:${attemptId}` where
49
+ * `attemptId` is a random value your server issued with this form. The
50
+ * backend compares the event's `tag` with the one it expects, so a
51
+ * `requestId` from another page or session is refused. Never put a
52
+ * personal identifier in a tag.
53
+ */
54
+ tag?: string;
47
55
  }
48
56
  /**
49
57
  * A hidden input carrying this page's `requestId`.
@@ -63,6 +71,6 @@ interface FingerlyRequestIdProps {
63
71
  *
64
72
  * Read it back with `readRequestId(formData)` from `@fingerly/next/server`.
65
73
  */
66
- declare function FingerlyRequestId({ name, immediate }?: FingerlyRequestIdProps): ReactNode;
74
+ declare function FingerlyRequestId({ name, immediate, tag }?: FingerlyRequestIdProps): ReactNode;
67
75
 
68
76
  export { type FingerlyNextProviderProps, FingerlyProvider, FingerlyRequestId, type FingerlyRequestIdProps };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { ConsentState } from '@fingerly/react';
2
- export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, SignalReport, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
1
+ import { IncognitoDetection, ConsentState } from '@fingerly/react';
2
+ export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyAnswer, IdentifyOptions, IdentifyResult, IncognitoDetection, SignalReport, SuspectLevel, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
3
3
  import { ReactNode } from 'react';
4
4
  export { R as REQUEST_ID_FIELD } from './field-name-CAkWsUa5.js';
5
5
 
@@ -16,8 +16,8 @@ interface FingerlyNextProviderProps {
16
16
  endpoints?: string | readonly string[];
17
17
  /** Opt into the Fingerly API after custom endpoints fail. */
18
18
  fallbackToDefaultEndpoint?: boolean;
19
- /** Collect and score without submitting anything. */
20
- submit?: boolean;
19
+ /** Opt-in extended incognito probe control (`'standard'` or `'extended'`). */
20
+ incognitoDetection?: IncognitoDetection;
21
21
  /**
22
22
  * Whether the visitor has agreed to be identified. Defaults to `pending`.
23
23
  *
@@ -44,6 +44,14 @@ interface FingerlyRequestIdProps {
44
44
  * that identifies at submit time instead.
45
45
  */
46
46
  immediate?: boolean;
47
+ /**
48
+ * Correlation tag echoed on the event, such as `signup:${attemptId}` where
49
+ * `attemptId` is a random value your server issued with this form. The
50
+ * backend compares the event's `tag` with the one it expects, so a
51
+ * `requestId` from another page or session is refused. Never put a
52
+ * personal identifier in a tag.
53
+ */
54
+ tag?: string;
47
55
  }
48
56
  /**
49
57
  * A hidden input carrying this page's `requestId`.
@@ -63,6 +71,6 @@ interface FingerlyRequestIdProps {
63
71
  *
64
72
  * Read it back with `readRequestId(formData)` from `@fingerly/next/server`.
65
73
  */
66
- declare function FingerlyRequestId({ name, immediate }?: FingerlyRequestIdProps): ReactNode;
74
+ declare function FingerlyRequestId({ name, immediate, tag }?: FingerlyRequestIdProps): ReactNode;
67
75
 
68
76
  export { type FingerlyNextProviderProps, FingerlyProvider, FingerlyRequestId, type FingerlyRequestIdProps };
package/dist/index.js CHANGED
@@ -4,7 +4,9 @@ import {
4
4
  } from "./chunk-2RV4QBLR.js";
5
5
 
6
6
  // src/provider.tsx
7
- import { FingerlyProvider as ReactFingerlyProvider } from "@fingerly/react";
7
+ import {
8
+ FingerlyProvider as ReactFingerlyProvider
9
+ } from "@fingerly/react";
8
10
  import { jsx } from "react/jsx-runtime";
9
11
  function fromEnvironment() {
10
12
  const apiKey = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_API_KEY;
@@ -49,7 +51,7 @@ function FingerlyProvider(props) {
49
51
  ...props.apiVersion === void 0 ? {} : { apiVersion: props.apiVersion },
50
52
  ...endpoints === void 0 ? {} : { endpoints },
51
53
  ...props.fallbackToDefaultEndpoint === void 0 ? {} : { fallbackToDefaultEndpoint: props.fallbackToDefaultEndpoint },
52
- ...props.submit === void 0 ? {} : { submit: props.submit },
54
+ ...props.incognitoDetection === void 0 ? {} : { incognitoDetection: props.incognitoDetection },
53
55
  ...props.consent === void 0 ? {} : { consent: props.consent },
54
56
  children: props.children
55
57
  }
@@ -59,8 +61,8 @@ function FingerlyProvider(props) {
59
61
  // src/field.tsx
60
62
  import { useIdentify } from "@fingerly/react";
61
63
  import { jsx as jsx2 } from "react/jsx-runtime";
62
- function FingerlyRequestId({ name, immediate = true } = {}) {
63
- const { requestId } = useIdentify({ immediate });
64
+ function FingerlyRequestId({ name, immediate = true, tag } = {}) {
65
+ const { requestId } = useIdentify({ immediate, ...tag === void 0 ? {} : { tag } });
64
66
  return /* @__PURE__ */ jsx2(
65
67
  "input",
66
68
  {
package/dist/server.d.cts CHANGED
@@ -25,6 +25,13 @@ export { ProxyOptions as FingerlyProxyOptions, createProxy as createFingerlyProx
25
25
  * }
26
26
  * ```
27
27
  *
28
+ * The value is still untrusted after this: it only has the right shape. Read
29
+ * the event with `fingerly.events.get(requestId)` and a secret key, and check
30
+ * that it exists, that its `tag` is the one this action expects, that it is
31
+ * recent, and that its `ip_network` contains the address of this request,
32
+ * before acting on it. See
33
+ * https://docs.fingerly.io/docs/server-side-verification.
34
+ *
28
35
  * Returns null rather than throwing when the field is missing, empty or
29
36
  * malformed, because all three mean the same thing to the caller: this
30
37
  * submission has no identification attached. A form submitted before the SDK
package/dist/server.d.ts CHANGED
@@ -25,6 +25,13 @@ export { ProxyOptions as FingerlyProxyOptions, createProxy as createFingerlyProx
25
25
  * }
26
26
  * ```
27
27
  *
28
+ * The value is still untrusted after this: it only has the right shape. Read
29
+ * the event with `fingerly.events.get(requestId)` and a secret key, and check
30
+ * that it exists, that its `tag` is the one this action expects, that it is
31
+ * recent, and that its `ip_network` contains the address of this request,
32
+ * before acting on it. See
33
+ * https://docs.fingerly.io/docs/server-side-verification.
34
+ *
28
35
  * Returns null rather than throwing when the field is missing, empty or
29
36
  * malformed, because all three mean the same thing to the caller: this
30
37
  * submission has no identification attached. A form submitted before the SDK
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/next",
3
- "version": "0.2.1",
3
+ "version": "0.4.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -32,8 +32,8 @@
32
32
  ],
33
33
  "sideEffects": false,
34
34
  "dependencies": {
35
- "@fingerly/node": "0.2.0",
36
- "@fingerly/react": "0.2.0"
35
+ "@fingerly/node": "0.4.0",
36
+ "@fingerly/react": "0.4.0"
37
37
  },
38
38
  "peerDependencies": {
39
39
  "next": ">=15",
@@ -49,7 +49,7 @@
49
49
  "tsup": "^8.3.5",
50
50
  "typescript": "^5.7.2",
51
51
  "vitest": "^2.1.8",
52
- "@fingerly/web-js": "0.2.0"
52
+ "@fingerly/web-js": "0.4.0"
53
53
  },
54
54
  "scripts": {
55
55
  "build": "tsup",