@fingerly/next 0.1.0 → 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/README.md CHANGED
@@ -17,13 +17,13 @@ pnpm add @fingerly/next
17
17
  Read the key in a Server Component and pass it down:
18
18
 
19
19
  ```tsx
20
- // app/layout.tsx — a Server Component
20
+ // app/layout.tsx (a Server Component)
21
21
  <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY}>{children}</FingerlyProvider>
22
22
  ```
23
23
 
24
24
  That is the arrangement that always works, and it is worth understanding why
25
25
  rather than copying. A server render reads `process.env` at runtime, so any
26
- variable name will do — no `NEXT_PUBLIC_` prefix needed — and the value reaches
26
+ variable name will do (no `NEXT_PUBLIC_` prefix needed), and the value reaches
27
27
  the browser through the RSC payload, which is where a public SDK key was
28
28
  always going to end up.
29
29
 
@@ -31,8 +31,9 @@ The provider will also read `NEXT_PUBLIC_FINGERLY_API_KEY` and
31
31
  `NEXT_PUBLIC_FINGERLY_ENDPOINT` itself, but that path has a condition on it:
32
32
  Next inlines `NEXT_PUBLIC_` variables **while compiling**, and it does not
33
33
  compile your dependencies. In a published build the read survives as a
34
- `process.env` lookup, and in a browser there is no `process` — the server
35
- render finds the key, hydration does not, and the page throws. It works if
34
+ `process.env` lookup, and in a browser there is no `process`. The server
35
+ render finds the key, hydration does not, and identification fails (the page
36
+ keeps rendering, and the console says which variable to set). It works if
36
37
  your app lists `@fingerly/next` in `transpilePackages`; the prop above needs no
37
38
  such condition, which is why it is the documented route.
38
39
 
@@ -43,7 +44,7 @@ an `Origin`, so the mistake either route invites cannot silently work.
43
44
  ## Add the provider
44
45
 
45
46
  ```tsx
46
- // app/layout.tsx — still a Server Component
47
+ // app/layout.tsx (still a Server Component)
47
48
  import { FingerlyProvider } from '@fingerly/next'
48
49
 
49
50
  export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -97,11 +98,10 @@ The hooks are `@fingerly/react`'s, re-exported so you install one package:
97
98
 
98
99
  ```tsx
99
100
  'use client'
100
- import { useIdentify, useVerdict } from '@fingerly/next'
101
+ import { useIdentify } from '@fingerly/next'
101
102
 
102
103
  export function Checkout() {
103
- const { identify, isSuspicious, isLoading } = useIdentify()
104
- const { matched } = useVerdict('incognito')
104
+ const { identify, isSuspicious, suspectLevel, isLoading } = useIdentify()
105
105
  …
106
106
  }
107
107
  ```
@@ -111,8 +111,8 @@ safe anywhere: it runs in an effect, and effects do not run during a server
111
111
  render. The page renders on the server, collects after hydration, and every
112
112
  component that asks shares the one identification.
113
113
 
114
- The full surface — `immediate`, `suspend`, `tag`, `refresh`, confidence floors
115
- — is documented in the [React binding's README](../react/README.md).
114
+ The full surface (`immediate`, `suspend`, `tag`, `refresh`) is documented in
115
+ the [React binding's README](../react/README.md).
116
116
 
117
117
  ## Carry it into a Server Action
118
118
 
@@ -152,7 +152,7 @@ form submitted before the SDK finished, or with JavaScript disabled, is a
152
152
  normal event, and the server can tell it apart from a form that never carried a
153
153
  field at all.
154
154
 
155
- `readRequestId()` returns `null` for all of those cases rather than throwing —
155
+ `readRequestId()` returns `null` for all of those cases rather than throwing:
156
156
  what to do about an unidentified submission is a policy your server owns. It
157
157
  also refuses anything that is not a short opaque token: the field arrives from
158
158
  the page, which means it arrives from whoever is driving the browser, and a
@@ -167,8 +167,8 @@ Both halves agree on the field name through one exported constant,
167
167
 
168
168
  | Import | Runs | Contains |
169
169
  | --- | --- | --- |
170
- | `@fingerly/next` | the browser | provider, field, hooks — a `'use client'` module |
171
- | `@fingerly/next/server` | the server | `readRequestId`, `REQUEST_ID_FIELD` — no React |
170
+ | `@fingerly/next` | the browser | provider, field, hooks (a `'use client'` module) |
171
+ | `@fingerly/next/server` | the server | `readRequestId`, `REQUEST_ID_FIELD` (no React) |
172
172
 
173
173
  A Server Action that imported `readRequestId` from the main entry would get a
174
174
  client reference rather than a function: the import succeeds and the call fails
@@ -176,21 +176,20 @@ at runtime, which is the worst way to learn about a boundary. Hence the split.
176
176
 
177
177
  ## Running the demo
178
178
 
179
- `demo/` is a real Next application — a Server Component layout, a client page,
179
+ `demo/` is a real Next application: a Server Component layout, a client page,
180
180
  and a Server Action reading the field back:
181
181
 
182
182
  ```
183
183
  pnpm --filter @fingerly/next demo # http://localhost:4178
184
184
  ```
185
185
 
186
- It collects and scores locally and submits nothing until you give it somewhere
187
- to submit: put `FINGERLY_API_KEY`, `FINGERLY_ENDPOINT` and `FINGERLY_SUBMIT=true` in
186
+ It collects and submits nothing until you give it somewhere to submit: put `FINGERLY_API_KEY`, `FINGERLY_ENDPOINT` and `FINGERLY_SUBMIT=true` in
188
187
  `demo/.env.local` (gitignored), with a key whose allowed origins include the
189
188
  port you are running it on. Then the identification produces a real
190
189
  `requestId`, the hidden field carries it, and the action prints the one it
191
190
  read.
192
191
 
193
- Open it twice — an ordinary window and a private one — and watch the incognito
192
+ Open it twice, in an ordinary window and a private one, and watch the incognito
194
193
  card change.
195
194
 
196
195
  ## What this deliberately does not do
@@ -199,11 +198,34 @@ card change.
199
198
  own origin is what gets them past content blockers, and the proxy for it lives
200
199
  in `@fingerly/node`, because it holds a server secret and has to forward the
201
200
  visitor's real address rather than your server's. Create a proxy in the
202
- dashboard, put `Fingerly.createProxy(...)` in the route file for the path it
203
- issued (such as `app/k7x2qm4a/route.ts`), and give the provider
204
- `endpoints="/k7x2qm4a"`.
201
+ dashboard, put it in the route file for the path it issued, and give the
202
+ provider `endpoints="/k7x2qm4a"`:
203
+
204
+ ```ts
205
+ // app/k7x2qm4a/route.ts
206
+ import { Fingerly } from '@fingerly/node'
207
+
208
+ // Built on the first request rather than at import, so `next build` does not
209
+ // need the proxy key.
210
+ let proxy: ((request: Request) => Promise<Response>) | undefined
211
+
212
+ export function POST(request: Request) {
213
+ proxy ??= Fingerly.createProxy({
214
+ proxyKey: process.env.FINGERLY_PROXY_KEY!,
215
+ // The last X-Forwarded-For entry is the address your own server or load
216
+ // balancer saw. Read a CDN's client-IP header instead only when traffic
217
+ // can reach this app through that CDN alone.
218
+ clientIp: (req) => req.headers.get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? '',
219
+ })
220
+ return proxy(request)
221
+ }
222
+ ```
223
+
224
+ Pass the path as a string. An array works too, and is compared by its
225
+ contents, so `endpoints={['/k7x2qm4a']}` does not start a new identification
226
+ when the layout renders again.
205
227
 
206
228
  **It does not read events back.** It does not need to: `identify()` resolves
207
- with the server's verdict — `visitorId`, `suspectScore`, `suspectLevel` and the
208
- triggers behind them — so there is nothing to fetch afterwards. Reading stored
229
+ with the server's answer (`visitorId`, and `suspectScore` and `suspectLevel`
230
+ unless the key hides them), so there is nothing to fetch afterwards. Reading stored
209
231
  events for reporting is `@fingerly/node`'s job.
package/dist/index.cjs CHANGED
@@ -29,8 +29,7 @@ __export(index_exports, {
29
29
  TransportError: () => import_react4.TransportError,
30
30
  createFingerlyStore: () => import_react3.createFingerlyStore,
31
31
  useFingerly: () => import_react3.useFingerly,
32
- useIdentify: () => import_react3.useIdentify,
33
- useVerdict: () => import_react3.useVerdict
32
+ useIdentify: () => import_react3.useIdentify
34
33
  });
35
34
  module.exports = __toCommonJS(index_exports);
36
35
 
@@ -41,34 +40,45 @@ function fromEnvironment() {
41
40
  const apiKey = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_API_KEY;
42
41
  const endpoint = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_ENDPOINT;
43
42
  const endpointsRaw = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_ENDPOINTS;
44
- let endpoints;
45
- if (endpointsRaw) {
46
- const parsed = JSON.parse(endpointsRaw);
47
- if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some((value) => typeof value !== "string")) {
48
- throw new Error("NEXT_PUBLIC_FINGERLY_ENDPOINTS must be a non-empty JSON array of strings");
49
- }
50
- endpoints = parsed;
51
- }
43
+ const endpoints = endpointsRaw ? parsedEndpoints(endpointsRaw) : void 0;
52
44
  return {
53
45
  ...apiKey === void 0 || apiKey === "" ? {} : { apiKey },
54
46
  ...endpoint === void 0 || endpoint === "" ? {} : { endpoint },
55
47
  ...endpoints === void 0 ? {} : { endpoints }
56
48
  };
57
49
  }
50
+ var parsedFrom;
51
+ var parsed;
52
+ function parsedEndpoints(raw) {
53
+ if (raw === parsedFrom) return parsed;
54
+ parsedFrom = raw;
55
+ parsed = void 0;
56
+ try {
57
+ const value = JSON.parse(raw);
58
+ if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string")) parsed = value;
59
+ } catch {
60
+ }
61
+ if (parsed === void 0) {
62
+ console.error("[fingerly] NEXT_PUBLIC_FINGERLY_ENDPOINTS must be a non-empty JSON array of strings; it is ignored.");
63
+ }
64
+ return parsed;
65
+ }
66
+ var reportedMissingKey = false;
58
67
  function FingerlyProvider(props) {
59
68
  const environment = fromEnvironment();
60
69
  const apiKey = props.apiKey ?? environment.apiKey;
61
70
  const endpoints = props.endpoints ?? environment.endpoints;
62
71
  const endpoint = endpoints === void 0 ? props.endpoint ?? environment.endpoint : void 0;
63
- if (!apiKey) {
64
- throw new Error(
65
- "No Fingerly key. Pass one from a Server Component, which is the arrangement that always works:\n\n // app/layout.tsx\n <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY}>\n\nReading it here instead works only where this package is compiled by your app - an app that lists it in `transpilePackages` and sets NEXT_PUBLIC_FINGERLY_API_KEY. A published build cannot rely on that: Next inlines NEXT_PUBLIC_ variables while compiling, and a dependency it does not compile keeps a `process.env` lookup that is undefined in a browser."
72
+ if (!apiKey && !reportedMissingKey) {
73
+ reportedMissingKey = true;
74
+ console.error(
75
+ "[fingerly] No Fingerly key. Pass one from a Server Component, which is the arrangement that always works:\n\n // app/layout.tsx\n <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY}>\n\nReading it here instead works only where this package is compiled by your app - an app that lists it in `transpilePackages` and sets NEXT_PUBLIC_FINGERLY_API_KEY. A published build cannot rely on that: Next inlines NEXT_PUBLIC_ variables while compiling, and a dependency it does not compile keeps a `process.env` lookup that is undefined in a browser."
66
76
  );
67
77
  }
68
78
  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
69
79
  import_react.FingerlyProvider,
70
80
  {
71
- apiKey,
81
+ apiKey: apiKey ?? "",
72
82
  ...endpoint === void 0 ? {} : { endpoint },
73
83
  ...props.apiVersion === void 0 ? {} : { apiVersion: props.apiVersion },
74
84
  ...endpoints === void 0 ? {} : { endpoints },
@@ -114,6 +124,5 @@ var import_react4 = require("@fingerly/react");
114
124
  TransportError,
115
125
  createFingerlyStore,
116
126
  useFingerly,
117
- useIdentify,
118
- useVerdict
127
+ useIdentify
119
128
  });
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { ConsentState } from '@fingerly/react';
2
- export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, IdentifyTrigger, SignalReport, TransportError, UseIdentifyOptions, UseIdentifyReturn, UseVerdictReturn, Verdict, VerdictName, Verdicts, createFingerlyStore, useFingerly, useIdentify, useVerdict } from '@fingerly/react';
2
+ export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, SignalReport, 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
 
@@ -31,29 +31,6 @@ interface FingerlyNextProviderProps {
31
31
  consent?: ConsentState;
32
32
  children?: ReactNode;
33
33
  }
34
- /**
35
- * Make the client available to every component below, in either router.
36
- *
37
- * ```tsx
38
- * // app/layout.tsx - a Server Component, which is the point: this is a
39
- * // client boundary and nothing above it has to become one.
40
- * export default function RootLayout({ children }) {
41
- * return (
42
- * <html><body>
43
- * <FingerlyProvider>{children}</FingerlyProvider>
44
- * </body></html>
45
- * )
46
- * }
47
- * ```
48
- *
49
- * The key comes from `NEXT_PUBLIC_FINGERLY_API_KEY` unless a prop overrides it.
50
- * `NEXT_PUBLIC_` is the right prefix and not a compromise: this is a public
51
- * SDK key, scoped to the origins listed against it, and it is *meant* to be
52
- * readable in the page. A secret key is refused by the API whenever a request
53
- * carries an `Origin`, so the mistake this prefix invites cannot silently work.
54
- *
55
- * Nothing is collected on mount. When to identify stays the page's decision.
56
- */
57
34
  declare function FingerlyProvider(props: FingerlyNextProviderProps): ReactNode;
58
35
 
59
36
  interface FingerlyRequestIdProps {
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { ConsentState } from '@fingerly/react';
2
- export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, IdentifyTrigger, SignalReport, TransportError, UseIdentifyOptions, UseIdentifyReturn, UseVerdictReturn, Verdict, VerdictName, Verdicts, createFingerlyStore, useFingerly, useIdentify, useVerdict } from '@fingerly/react';
2
+ export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, SignalReport, 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
 
@@ -31,29 +31,6 @@ interface FingerlyNextProviderProps {
31
31
  consent?: ConsentState;
32
32
  children?: ReactNode;
33
33
  }
34
- /**
35
- * Make the client available to every component below, in either router.
36
- *
37
- * ```tsx
38
- * // app/layout.tsx - a Server Component, which is the point: this is a
39
- * // client boundary and nothing above it has to become one.
40
- * export default function RootLayout({ children }) {
41
- * return (
42
- * <html><body>
43
- * <FingerlyProvider>{children}</FingerlyProvider>
44
- * </body></html>
45
- * )
46
- * }
47
- * ```
48
- *
49
- * The key comes from `NEXT_PUBLIC_FINGERLY_API_KEY` unless a prop overrides it.
50
- * `NEXT_PUBLIC_` is the right prefix and not a compromise: this is a public
51
- * SDK key, scoped to the origins listed against it, and it is *meant* to be
52
- * readable in the page. A secret key is refused by the API whenever a request
53
- * carries an `Origin`, so the mistake this prefix invites cannot silently work.
54
- *
55
- * Nothing is collected on mount. When to identify stays the page's decision.
56
- */
57
34
  declare function FingerlyProvider(props: FingerlyNextProviderProps): ReactNode;
58
35
 
59
36
  interface FingerlyRequestIdProps {
package/dist/index.js CHANGED
@@ -10,34 +10,45 @@ function fromEnvironment() {
10
10
  const apiKey = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_API_KEY;
11
11
  const endpoint = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_ENDPOINT;
12
12
  const endpointsRaw = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_ENDPOINTS;
13
- let endpoints;
14
- if (endpointsRaw) {
15
- const parsed = JSON.parse(endpointsRaw);
16
- if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some((value) => typeof value !== "string")) {
17
- throw new Error("NEXT_PUBLIC_FINGERLY_ENDPOINTS must be a non-empty JSON array of strings");
18
- }
19
- endpoints = parsed;
20
- }
13
+ const endpoints = endpointsRaw ? parsedEndpoints(endpointsRaw) : void 0;
21
14
  return {
22
15
  ...apiKey === void 0 || apiKey === "" ? {} : { apiKey },
23
16
  ...endpoint === void 0 || endpoint === "" ? {} : { endpoint },
24
17
  ...endpoints === void 0 ? {} : { endpoints }
25
18
  };
26
19
  }
20
+ var parsedFrom;
21
+ var parsed;
22
+ function parsedEndpoints(raw) {
23
+ if (raw === parsedFrom) return parsed;
24
+ parsedFrom = raw;
25
+ parsed = void 0;
26
+ try {
27
+ const value = JSON.parse(raw);
28
+ if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string")) parsed = value;
29
+ } catch {
30
+ }
31
+ if (parsed === void 0) {
32
+ console.error("[fingerly] NEXT_PUBLIC_FINGERLY_ENDPOINTS must be a non-empty JSON array of strings; it is ignored.");
33
+ }
34
+ return parsed;
35
+ }
36
+ var reportedMissingKey = false;
27
37
  function FingerlyProvider(props) {
28
38
  const environment = fromEnvironment();
29
39
  const apiKey = props.apiKey ?? environment.apiKey;
30
40
  const endpoints = props.endpoints ?? environment.endpoints;
31
41
  const endpoint = endpoints === void 0 ? props.endpoint ?? environment.endpoint : void 0;
32
- if (!apiKey) {
33
- throw new Error(
34
- "No Fingerly key. Pass one from a Server Component, which is the arrangement that always works:\n\n // app/layout.tsx\n <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY}>\n\nReading it here instead works only where this package is compiled by your app - an app that lists it in `transpilePackages` and sets NEXT_PUBLIC_FINGERLY_API_KEY. A published build cannot rely on that: Next inlines NEXT_PUBLIC_ variables while compiling, and a dependency it does not compile keeps a `process.env` lookup that is undefined in a browser."
42
+ if (!apiKey && !reportedMissingKey) {
43
+ reportedMissingKey = true;
44
+ console.error(
45
+ "[fingerly] No Fingerly key. Pass one from a Server Component, which is the arrangement that always works:\n\n // app/layout.tsx\n <FingerlyProvider apiKey={process.env.FINGERLY_API_KEY}>\n\nReading it here instead works only where this package is compiled by your app - an app that lists it in `transpilePackages` and sets NEXT_PUBLIC_FINGERLY_API_KEY. A published build cannot rely on that: Next inlines NEXT_PUBLIC_ variables while compiling, and a dependency it does not compile keeps a `process.env` lookup that is undefined in a browser."
35
46
  );
36
47
  }
37
48
  return /* @__PURE__ */ jsx(
38
49
  ReactFingerlyProvider,
39
50
  {
40
- apiKey,
51
+ apiKey: apiKey ?? "",
41
52
  ...endpoint === void 0 ? {} : { endpoint },
42
53
  ...props.apiVersion === void 0 ? {} : { apiVersion: props.apiVersion },
43
54
  ...endpoints === void 0 ? {} : { endpoints },
@@ -66,7 +77,7 @@ function FingerlyRequestId({ name, immediate = true } = {}) {
66
77
  }
67
78
 
68
79
  // src/index.ts
69
- import { useFingerly, useIdentify as useIdentify2, useVerdict, createFingerlyStore, FingerlyServerError } from "@fingerly/react";
80
+ import { useFingerly, useIdentify as useIdentify2, createFingerlyStore, FingerlyServerError } from "@fingerly/react";
70
81
  import { ConsentError, TransportError } from "@fingerly/react";
71
82
  export {
72
83
  ConsentError,
@@ -77,6 +88,5 @@ export {
77
88
  TransportError,
78
89
  createFingerlyStore,
79
90
  useFingerly,
80
- useIdentify2 as useIdentify,
81
- useVerdict
91
+ useIdentify2 as useIdentify
82
92
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/next",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -32,8 +32,8 @@
32
32
  ],
33
33
  "sideEffects": false,
34
34
  "dependencies": {
35
- "@fingerly/react": "0.1.0",
36
- "@fingerly/node": "0.1.0"
35
+ "@fingerly/node": "0.1.1",
36
+ "@fingerly/react": "0.1.1"
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.1.0"
52
+ "@fingerly/web-js": "0.1.1"
53
53
  },
54
54
  "scripts": {
55
55
  "build": "tsup",