@fingerly/svelte 0.0.0-stage → 0.1.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.
@@ -0,0 +1,86 @@
1
+ /**
2
+ * The two things a component asks for: the identification, and one verdict.
3
+ *
4
+ * Named `useIdentify` and `useVerdict` to match the Vue, React and Next
5
+ * bindings rather than to follow any Svelte convention. An SDK whose four
6
+ * bindings answer the same question under four different names makes its own
7
+ * documentation harder to read than the code it documents. What is Svelte's
8
+ * here is the *shape*: reactive objects read as plain properties, no refs, no
9
+ * `$` prefix, no subscription.
10
+ */
11
+ import type { Confidence, Verdict, Verdicts } from '@fingerly/web-js';
12
+ import type { Fingerly } from './state.svelte.js';
13
+ export type VerdictName = keyof Verdicts;
14
+ export interface UseIdentifyOptions {
15
+ /**
16
+ * Identify as soon as the component mounts.
17
+ *
18
+ * Safe to pass in every component that wants it: the context holds one
19
+ * shared identification, so the second and third callers get the first
20
+ * one's answer rather than starting their own submission.
21
+ *
22
+ * It runs in an `$effect`, which is what makes it server-safe - effects do
23
+ * not run during SSR, so a SvelteKit page using this renders on the server
24
+ * and collects on the client without a guard of its own.
25
+ *
26
+ * It waits for consent. While `consent` is `pending` or `denied` nothing is
27
+ * started, and the identification begins once it becomes `granted`.
28
+ */
29
+ immediate?: boolean;
30
+ /**
31
+ * The customer's own correlation value, echoed back on the finished event.
32
+ *
33
+ * Accepts a getter as well as a string, so it can be
34
+ * `() => page.params.orderId` and be read at the moment of submission
35
+ * rather than at the moment the component initialised.
36
+ */
37
+ tag?: string | (() => string | undefined);
38
+ }
39
+ /**
40
+ * The shared identification, optionally started on mount.
41
+ *
42
+ * ```svelte
43
+ * <script lang="ts">
44
+ * import { useIdentify } from '@fingerly/svelte'
45
+ * const fingerly = useIdentify({ immediate: true })
46
+ * </script>
47
+ *
48
+ * {#if fingerly.isReady && fingerly.isSuspicious}
49
+ * <p>Something about this session is unusual.</p>
50
+ * {/if}
51
+ * ```
52
+ *
53
+ * Returns the same object `setupFingerly()` created, so `fingerly.verdicts` in a
54
+ * template re-renders when the answer arrives.
55
+ */
56
+ export declare function useIdentify(options?: UseIdentifyOptions): Fingerly;
57
+ export interface UseVerdictReturn {
58
+ /** True only when the verdict fired *and* met the confidence floor. */
59
+ readonly matched: boolean;
60
+ /** The verdict itself, or null before the first identification. */
61
+ readonly verdict: Verdict | null;
62
+ readonly confidence: Confidence | null;
63
+ /** Why, strongest first. Empty before identification, never null. */
64
+ readonly reasons: readonly string[];
65
+ }
66
+ /**
67
+ * Watch one verdict.
68
+ *
69
+ * ```svelte
70
+ * <script lang="ts">
71
+ * const incognito = useVerdict('incognito')
72
+ * </script>
73
+ *
74
+ * {#if incognito.matched}Private window ({incognito.confidence}){/if}
75
+ * ```
76
+ *
77
+ * `min` defaults to `medium`. A `low`-confidence verdict is a single weak tell
78
+ * - one removable flag, or one countermeasure a privacy-conscious real user
79
+ * might equally be running - and defaulting to acting on it would make this a
80
+ * false-positive generator. Pass `min: 'low'` deliberately if the intent is to
81
+ * observe rather than to block.
82
+ */
83
+ export declare function useVerdict(name: VerdictName | (() => VerdictName), options?: {
84
+ min?: Confidence | (() => Confidence);
85
+ }): UseVerdictReturn;
86
+ //# sourceMappingURL=hooks.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hooks.svelte.d.ts","sourceRoot":"","sources":["../src/hooks.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAGrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,MAAM,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAA;AAExC,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,QAAQ,CA8FtE;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;IACtC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,EACvC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,CAAA;CAAO,GACtD,gBAAgB,CA+BlB"}
@@ -0,0 +1,164 @@
1
+ /**
2
+ * The two things a component asks for: the identification, and one verdict.
3
+ *
4
+ * Named `useIdentify` and `useVerdict` to match the Vue, React and Next
5
+ * bindings rather than to follow any Svelte convention. An SDK whose four
6
+ * bindings answer the same question under four different names makes its own
7
+ * documentation harder to read than the code it documents. What is Svelte's
8
+ * here is the *shape*: reactive objects read as plain properties, no refs, no
9
+ * `$` prefix, no subscription.
10
+ */
11
+ import { useFingerly } from './context.js';
12
+ /**
13
+ * The shared identification, optionally started on mount.
14
+ *
15
+ * ```svelte
16
+ * <script lang="ts">
17
+ * import { useIdentify } from '@fingerly/svelte'
18
+ * const fingerly = useIdentify({ immediate: true })
19
+ * </script>
20
+ *
21
+ * {#if fingerly.isReady && fingerly.isSuspicious}
22
+ * <p>Something about this session is unusual.</p>
23
+ * {/if}
24
+ * ```
25
+ *
26
+ * Returns the same object `setupFingerly()` created, so `fingerly.verdicts` in a
27
+ * template re-renders when the answer arrives.
28
+ */
29
+ export function useIdentify(options = {}) {
30
+ const fingerly = useFingerly();
31
+ const resolveTag = (override) => override ?? (typeof options.tag === 'function' ? options.tag() : options.tag);
32
+ // Wrapped rather than handed back as-is, so that `tag` applies to every call
33
+ // this component makes and not only to the one `immediate` starts. The
34
+ // getters below forward to the shared state, so the reactivity is the same
35
+ // object's - what is per-component here is the tag, and nothing else.
36
+ const identify = (callOptions = {}) => {
37
+ const tag = resolveTag(callOptions.tag);
38
+ return fingerly.identify({
39
+ ...(tag === undefined ? {} : { tag }),
40
+ ...(callOptions.force === undefined ? {} : { force: callOptions.force }),
41
+ });
42
+ };
43
+ const refresh = (callOptions = {}) => identify({ ...callOptions, force: true });
44
+ if (options.immediate) {
45
+ $effect(() => {
46
+ // Reading `consent` is what makes this effect run again when a banner is
47
+ // accepted after mount. Once: the shared state memoises the run, so
48
+ // consent flipping back and forth afterwards submits nothing more.
49
+ if (fingerly.consent !== 'granted')
50
+ return;
51
+ // The rejection is swallowed rather than left to become an unhandled
52
+ // one: the failure is already in `fingerly.error`, which is where a
53
+ // component that opted into `immediate` will look for it. A caller who
54
+ // wants to await the outcome calls identify() themselves.
55
+ void identify().catch(() => undefined);
56
+ });
57
+ }
58
+ return {
59
+ get requestId() {
60
+ return fingerly.requestId;
61
+ },
62
+ get visitorId() {
63
+ return fingerly.visitorId;
64
+ },
65
+ get visitorIsNew() {
66
+ return fingerly.visitorIsNew;
67
+ },
68
+ get visitorConfidence() {
69
+ return fingerly.visitorConfidence;
70
+ },
71
+ get identifiable() {
72
+ return fingerly.identifiable;
73
+ },
74
+ get duplicate() {
75
+ return fingerly.duplicate;
76
+ },
77
+ get state() {
78
+ return fingerly.state;
79
+ },
80
+ get reason() {
81
+ return fingerly.reason;
82
+ },
83
+ get suspectScore() {
84
+ return fingerly.suspectScore;
85
+ },
86
+ get suspectLevel() {
87
+ return fingerly.suspectLevel;
88
+ },
89
+ get triggers() {
90
+ return fingerly.triggers;
91
+ },
92
+ get verdicts() {
93
+ return fingerly.verdicts;
94
+ },
95
+ get report() {
96
+ return fingerly.report;
97
+ },
98
+ get error() {
99
+ return fingerly.error;
100
+ },
101
+ get isLoading() {
102
+ return fingerly.isLoading;
103
+ },
104
+ get isReady() {
105
+ return fingerly.isReady;
106
+ },
107
+ get isSuspicious() {
108
+ return fingerly.isSuspicious;
109
+ },
110
+ get consent() {
111
+ return fingerly.consent;
112
+ },
113
+ setConsent: fingerly.setConsent,
114
+ identify,
115
+ refresh,
116
+ client: fingerly.client,
117
+ };
118
+ }
119
+ const RANK = { low: 0, medium: 1, high: 2 };
120
+ /** One array for every un-identified verdict, rather than one per read. */
121
+ const NO_REASONS = Object.freeze([]);
122
+ /**
123
+ * Watch one verdict.
124
+ *
125
+ * ```svelte
126
+ * <script lang="ts">
127
+ * const incognito = useVerdict('incognito')
128
+ * </script>
129
+ *
130
+ * {#if incognito.matched}Private window ({incognito.confidence}){/if}
131
+ * ```
132
+ *
133
+ * `min` defaults to `medium`. A `low`-confidence verdict is a single weak tell
134
+ * - one removable flag, or one countermeasure a privacy-conscious real user
135
+ * might equally be running - and defaulting to acting on it would make this a
136
+ * false-positive generator. Pass `min: 'low'` deliberately if the intent is to
137
+ * observe rather than to block.
138
+ */
139
+ export function useVerdict(name, options = {}) {
140
+ const fingerly = useFingerly();
141
+ // Getters accepted as well as values, because this is called once when the
142
+ // component initialises and its arguments may be props that change after
143
+ // that. A plain value read here would be the value that prop had at
144
+ // initialisation, forever.
145
+ const which = $derived(typeof name === 'function' ? name() : name);
146
+ const floor = $derived((typeof options.min === 'function' ? options.min() : options.min) ?? 'medium');
147
+ const verdict = $derived(fingerly.verdicts ? fingerly.verdicts[which] : null);
148
+ const matched = $derived(verdict !== null && verdict.value && RANK[verdict.confidence] >= RANK[floor]);
149
+ return {
150
+ get verdict() {
151
+ return verdict;
152
+ },
153
+ get confidence() {
154
+ return verdict?.confidence ?? null;
155
+ },
156
+ get reasons() {
157
+ return verdict?.reasons ?? NO_REASONS;
158
+ },
159
+ get matched() {
160
+ return matched;
161
+ },
162
+ };
163
+ }
164
+ //# sourceMappingURL=hooks.svelte.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hooks.svelte.js","sourceRoot":"","sources":["../src/hooks.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AA+B1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE;IAC1D,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAE9B,MAAM,UAAU,GAAG,CAAC,QAAiB,EAAsB,EAAE,CAC3D,QAAQ,IAAI,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAE/E,6EAA6E;IAC7E,uEAAuE;IACvE,2EAA2E;IAC3E,sEAAsE;IACtE,MAAM,QAAQ,GAAyB,CAAC,WAAW,GAAG,EAAE,EAAE,EAAE;QAC1D,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QACvC,OAAO,QAAQ,CAAC,QAAQ,CAAC;YACvB,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;YACrC,GAAG,CAAC,WAAW,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC;SACzE,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,MAAM,OAAO,GAAwB,CAAC,WAAW,GAAG,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,GAAG,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAEpG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,EAAE;YACX,yEAAyE;YACzE,oEAAoE;YACpE,mEAAmE;YACnE,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS;gBAAE,OAAM;YAC1C,qEAAqE;YACrE,oEAAoE;YACpE,uEAAuE;YACvE,0DAA0D;YAC1D,KAAK,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACxC,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO;QACL,IAAI,SAAS;YACX,OAAO,QAAQ,CAAC,SAAS,CAAA;QAC3B,CAAC;QACD,IAAI,SAAS;YACX,OAAO,QAAQ,CAAC,SAAS,CAAA;QAC3B,CAAC;QACD,IAAI,YAAY;YACd,OAAO,QAAQ,CAAC,YAAY,CAAA;QAC9B,CAAC;QACD,IAAI,iBAAiB;YACnB,OAAO,QAAQ,CAAC,iBAAiB,CAAA;QACnC,CAAC;QACD,IAAI,YAAY;YACd,OAAO,QAAQ,CAAC,YAAY,CAAA;QAC9B,CAAC;QACD,IAAI,SAAS;YACX,OAAO,QAAQ,CAAC,SAAS,CAAA;QAC3B,CAAC;QACD,IAAI,KAAK;YACP,OAAO,QAAQ,CAAC,KAAK,CAAA;QACvB,CAAC;QACD,IAAI,MAAM;YACR,OAAO,QAAQ,CAAC,MAAM,CAAA;QACxB,CAAC;QACD,IAAI,YAAY;YACd,OAAO,QAAQ,CAAC,YAAY,CAAA;QAC9B,CAAC;QACD,IAAI,YAAY;YACd,OAAO,QAAQ,CAAC,YAAY,CAAA;QAC9B,CAAC;QACD,IAAI,QAAQ;YACV,OAAO,QAAQ,CAAC,QAAQ,CAAA;QAC1B,CAAC;QACD,IAAI,QAAQ;YACV,OAAO,QAAQ,CAAC,QAAQ,CAAA;QAC1B,CAAC;QACD,IAAI,MAAM;YACR,OAAO,QAAQ,CAAC,MAAM,CAAA;QACxB,CAAC;QACD,IAAI,KAAK;YACP,OAAO,QAAQ,CAAC,KAAK,CAAA;QACvB,CAAC;QACD,IAAI,SAAS;YACX,OAAO,QAAQ,CAAC,SAAS,CAAA;QAC3B,CAAC;QACD,IAAI,OAAO;YACT,OAAO,QAAQ,CAAC,OAAO,CAAA;QACzB,CAAC;QACD,IAAI,YAAY;YACd,OAAO,QAAQ,CAAC,YAAY,CAAA;QAC9B,CAAC;QACD,IAAI,OAAO;YACT,OAAO,QAAQ,CAAC,OAAO,CAAA;QACzB,CAAC;QACD,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,QAAQ;QACR,OAAO;QACP,MAAM,EAAE,QAAQ,CAAC,MAAM;KACxB,CAAA;AACH,CAAC;AAYD,MAAM,IAAI,GAA+B,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;AAEvE,2EAA2E;AAC3E,MAAM,UAAU,GAAsB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CACxB,IAAuC,EACvC,UAAqD,EAAE;IAEvD,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAE9B,2EAA2E;IAC3E,yEAAyE;IACzE,oEAAoE;IACpE,2BAA2B;IAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAClE,MAAM,KAAK,GAAG,QAAQ,CACpB,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,QAAQ,CAC9E,CAAA;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAC1F,MAAM,OAAO,GAAG,QAAQ,CACtB,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAC7E,CAAA;IAED,OAAO;QACL,IAAI,OAAO;YACT,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,IAAI,UAAU;YACZ,OAAO,OAAO,EAAE,UAAU,IAAI,IAAI,CAAA;QACpC,CAAC;QACD,IAAI,OAAO;YACT,OAAO,OAAO,EAAE,OAAO,IAAI,UAAU,CAAA;QACvC,CAAC;QACD,IAAI,OAAO;YACT,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * @fingerly/svelte - Svelte 5 bindings for the Fingerly SDK.
3
+ *
4
+ * One state per app, held in Svelte's context, read as plain reactive
5
+ * properties. See the README for the whole surface with examples.
6
+ *
7
+ * Requires Svelte 5: the state is built with runes, which is what lets a
8
+ * component read `fingerly.verdicts` and re-render, with no store and no `$`
9
+ * prefix at the call site.
10
+ */
11
+ export { FINGERLY_KEY, setupFingerly, useFingerly } from './context.js';
12
+ export { createFingerly, FingerlyServerError } from './state.svelte.js';
13
+ export type { Fingerly, FingerlyOptions } from './state.svelte.js';
14
+ export { useIdentify, useVerdict } from './hooks.svelte.js';
15
+ export type { UseIdentifyOptions, UseVerdictReturn, VerdictName } from './hooks.svelte.js';
16
+ export type { FingerlyWebEvent, Confidence, ConsentState, IdentifyResult, IntegrityReport, Lie, SignalOutcome, SignalReport, SignalStatus, Verdict, Verdicts, } from '@fingerly/web-js';
17
+ export { ConsentError, TransportError } from '@fingerly/web-js';
18
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAEvE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC3D,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAI1F,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,GAAG,EACH,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,QAAQ,GACT,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}
package/dist/index.js ADDED
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @fingerly/svelte - Svelte 5 bindings for the Fingerly SDK.
3
+ *
4
+ * One state per app, held in Svelte's context, read as plain reactive
5
+ * properties. See the README for the whole surface with examples.
6
+ *
7
+ * Requires Svelte 5: the state is built with runes, which is what lets a
8
+ * component read `fingerly.verdicts` and re-render, with no store and no `$`
9
+ * prefix at the call site.
10
+ */
11
+ export { FINGERLY_KEY, setupFingerly, useFingerly } from './context.js';
12
+ export { createFingerly, FingerlyServerError } from './state.svelte.js';
13
+ export { useIdentify, useVerdict } from './hooks.svelte.js';
14
+ export { ConsentError, TransportError } from '@fingerly/web-js';
15
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAEvE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAGvE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAkB3D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}
@@ -0,0 +1,135 @@
1
+ /**
2
+ * The shared state, in runes.
3
+ *
4
+ * A `.svelte.ts` module rather than a plain one, which is what lets `$state`
5
+ * live outside a component: the file is compiled by the Svelte compiler in the
6
+ * consuming app, so the fields below are reactive wherever they are read.
7
+ * That is the whole reason this binding needs no store, no subscription and no
8
+ * `$` prefix at the call site - a component reads `fingerly.verdicts` and
9
+ * re-renders when it changes.
10
+ *
11
+ * One state per app, not one per component. Identification is a *page-level*
12
+ * event: three components asking whether the visitor is suspicious should
13
+ * produce one submission and one answer, not three. Per-component state would
14
+ * bill the customer three times for one page load and hand the three
15
+ * components three different `requestId`s for one visitor.
16
+ */
17
+ import { type ConsentState, type FingerlyClient, type IdentifyResult, type IdentifyTrigger, type SignalReport, type Verdicts } from '@fingerly/web-js';
18
+ /** Options for [[createFingerly]] and [[setupFingerly]]. */
19
+ export interface FingerlyOptions {
20
+ /** The SDK key from the dashboard. A public key is safe in a page. */
21
+ apiKey: string;
22
+ /** Origin of the API. Defaults to production. */
23
+ /** API route version. Defaults to v1. */
24
+ apiVersion?: string;
25
+ endpoint?: string;
26
+ endpoints?: string | readonly string[];
27
+ fallbackToDefaultEndpoint?: boolean;
28
+ /**
29
+ * Collect and score without submitting anything.
30
+ *
31
+ * For a page that wants the local verdicts and nothing else. Everything
32
+ * the server decides comes back empty: no `requestId`, no `visitorId` and
33
+ * no `suspectScore`. That is the honest answer rather than a gap - nothing
34
+ * was sent, so nobody scored it, and a zero here would read as "scored,
35
+ * found nothing".
36
+ */
37
+ submit?: boolean;
38
+ /**
39
+ * Whether the visitor has agreed to be identified. Defaults to `pending`.
40
+ *
41
+ * Leave it `pending` while identification waits on a consent banner, then
42
+ * call [[Fingerly.setConsent]] when it is answered, or pass `granted`
43
+ * once you have consent (or another lawful basis). Until then nothing is
44
+ * collected or sent: `useIdentify({ immediate: true })` waits, and a manual
45
+ * `identify()` fails with a `ConsentError` in `error`.
46
+ */
47
+ consent?: ConsentState;
48
+ }
49
+ /** What a component reads. Every field is reactive; none of them is settable. */
50
+ export interface Fingerly {
51
+ readonly requestId: string | null;
52
+ /**
53
+ * Who the server decided this is. Null under `submit: false`, and null
54
+ * before the first identification - never empty-string, so a template can
55
+ * ask `fingerly.visitorId` without also asking whether it means anything.
56
+ */
57
+ readonly visitorId: string | null;
58
+ /** True when the server had never seen this visitor before. */
59
+ readonly visitorIsNew: boolean;
60
+ /** How sure the server is of `visitorId`, 0-100. */
61
+ readonly visitorConfidence: number;
62
+ /** False when the signals were too thin to identify anybody. */
63
+ readonly identifiable: boolean;
64
+ /** True when this submission had already been answered. */
65
+ readonly duplicate: boolean;
66
+ /** The server's disposition of the check. */
67
+ readonly state: string | null;
68
+ /** Why, when `state` needs explaining. */
69
+ readonly reason: string | null;
70
+ /**
71
+ * The server's score, 0-100, or null when it did not score.
72
+ *
73
+ * Null and zero are different answers: null is "not scored", zero is
74
+ * "scored, nothing found". Do not collapse them with `?? 0`.
75
+ */
76
+ readonly suspectScore: number | null;
77
+ /** The score as a band - `low`, `medium`, `high`. Null when unscored. */
78
+ readonly suspectLevel: string | null;
79
+ /** What the server scored on. Empty when it found nothing. */
80
+ readonly triggers: readonly IdentifyTrigger[];
81
+ readonly verdicts: Verdicts | null;
82
+ readonly report: SignalReport | null;
83
+ readonly error: Error | null;
84
+ readonly isLoading: boolean;
85
+ /** True once an identification has completed, successfully or not. */
86
+ readonly isReady: boolean;
87
+ /**
88
+ * True when the verdicts contain anything worth acting on.
89
+ *
90
+ * Deliberately conservative: it requires `medium` confidence or better,
91
+ * because a `low`-confidence verdict is one weak tell and blocking on it
92
+ * would be blocking real users. Anything more nuanced should read `verdicts`
93
+ * directly - this is the "should I even look?" flag, not a policy.
94
+ */
95
+ readonly isSuspicious: boolean;
96
+ /**
97
+ * Whether the visitor has agreed to be identified, as last set here or on
98
+ * the client. Automatic identification waits for `granted`.
99
+ */
100
+ readonly consent: ConsentState;
101
+ /**
102
+ * Record the visitor's consent, as the consent tool reports it.
103
+ *
104
+ * Usable before the client exists - during SSR, or before anything has
105
+ * identified - and forwarded to it once it does. Setting `granted` is what
106
+ * starts any `useIdentify({ immediate: true })` that was waiting for it.
107
+ * The client's own `setConsent()` does the same.
108
+ */
109
+ setConsent(state: ConsentState): void;
110
+ /** Collect, score and submit. Reuses a completed run unless `force`. */
111
+ identify(options?: {
112
+ tag?: string;
113
+ force?: boolean;
114
+ }): Promise<IdentifyResult>;
115
+ /** Identify again from scratch, ignoring any previous result. */
116
+ refresh(options?: {
117
+ tag?: string;
118
+ }): Promise<IdentifyResult>;
119
+ /** The underlying client, built on first use. */
120
+ client(): Promise<FingerlyClient>;
121
+ }
122
+ /** Thrown when the SDK is asked to collect somewhere there is no browser. */
123
+ export declare class FingerlyServerError extends Error {
124
+ readonly name = "FingerlyServerError";
125
+ constructor();
126
+ }
127
+ /**
128
+ * Build the state.
129
+ *
130
+ * Nothing is collected here. Creating it only makes the client reachable - a
131
+ * factory that fingerprinted as it ran would collect during a server render
132
+ * and take the choice of *when* away from the page that knows.
133
+ */
134
+ export declare function createFingerly(options: FingerlyOptions): Fingerly;
135
+ //# sourceMappingURL=state.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"state.svelte.d.ts","sourceRoot":"","sources":["../src/state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,kBAAkB,CAAA;AAEzB,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACtC,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB;AAED,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;IACrC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC9E,iEAAiE;IACjE,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC5D,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;CAClC;AAED,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAwB;;CAQ/C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CA4LjE"}
@@ -0,0 +1,211 @@
1
+ /**
2
+ * The shared state, in runes.
3
+ *
4
+ * A `.svelte.ts` module rather than a plain one, which is what lets `$state`
5
+ * live outside a component: the file is compiled by the Svelte compiler in the
6
+ * consuming app, so the fields below are reactive wherever they are read.
7
+ * That is the whole reason this binding needs no store, no subscription and no
8
+ * `$` prefix at the call site - a component reads `fingerly.verdicts` and
9
+ * re-renders when it changes.
10
+ *
11
+ * One state per app, not one per component. Identification is a *page-level*
12
+ * event: three components asking whether the visitor is suspicious should
13
+ * produce one submission and one answer, not three. Per-component state would
14
+ * bill the customer three times for one page load and hand the three
15
+ * components three different `requestId`s for one visitor.
16
+ */
17
+ import { load, } from '@fingerly/web-js';
18
+ /** Thrown when the SDK is asked to collect somewhere there is no browser. */
19
+ export class FingerlyServerError extends Error {
20
+ name = 'FingerlyServerError';
21
+ constructor() {
22
+ super('Fingerly collects signals from a browser and cannot run during server-side rendering. ' +
23
+ 'Call identify() from an $effect, or pass { immediate: true } to useIdentify(), ' +
24
+ 'which already waits for the client.');
25
+ }
26
+ }
27
+ /**
28
+ * Build the state.
29
+ *
30
+ * Nothing is collected here. Creating it only makes the client reachable - a
31
+ * factory that fingerprinted as it ran would collect during a server render
32
+ * and take the choice of *when* away from the page that knows.
33
+ */
34
+ export function createFingerly(options) {
35
+ let requestId = $state(null);
36
+ let visitorId = $state(null);
37
+ let visitorIsNew = $state(false);
38
+ let visitorConfidence = $state(0);
39
+ let identifiable = $state(false);
40
+ let duplicate = $state(false);
41
+ let checkState = $state(null);
42
+ let reason = $state(null);
43
+ let suspectScore = $state(null);
44
+ let suspectLevel = $state(null);
45
+ let triggers = $state([]);
46
+ let verdicts = $state(null);
47
+ let report = $state(null);
48
+ let error = $state(null);
49
+ let isLoading = $state(false);
50
+ let consent = $state(options.consent ?? 'pending');
51
+ const isReady = $derived(report !== null || error !== null);
52
+ const isSuspicious = $derived(verdicts === null
53
+ ? false
54
+ : Object.values(verdicts).some((verdict) => verdict.value && verdict.confidence !== 'low'));
55
+ let clientPromise;
56
+ let loaded;
57
+ let current;
58
+ const mirrorConsent = (next) => {
59
+ consent = next;
60
+ };
61
+ const client = () => {
62
+ if (typeof window === 'undefined')
63
+ return Promise.reject(new FingerlyServerError());
64
+ // Built once and memoised. `load()` is cheap today but is the documented
65
+ // place for future warm-up work, and warming up per component would undo
66
+ // it.
67
+ clientPromise ??= load({
68
+ apiKey: options.apiKey,
69
+ ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
70
+ ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
71
+ ...(options.endpoints === undefined ? {} : { endpoints: options.endpoints }),
72
+ ...(options.fallbackToDefaultEndpoint === undefined ? {} : { fallbackToDefaultEndpoint: options.fallbackToDefaultEndpoint }),
73
+ consent,
74
+ }).then((fingerly) => {
75
+ // Caught up before anything can identify through it: setConsent() may
76
+ // have been called while load() was settling.
77
+ if (fingerly.consent !== consent)
78
+ fingerly.setConsent(consent);
79
+ // And followed from here on, so a consent tool holding the client itself
80
+ // moves this state - and whatever is waiting on it - as well.
81
+ fingerly.onConsentChange(mirrorConsent);
82
+ loaded = fingerly;
83
+ return fingerly;
84
+ });
85
+ return clientPromise;
86
+ };
87
+ const setConsent = (next) => {
88
+ // The client first, so it validates the value and has it before an effect
89
+ // reacting to the state below asks it to identify.
90
+ loaded?.setConsent(next);
91
+ mirrorConsent(next);
92
+ };
93
+ const identify = (identifyOptions = {}) => {
94
+ if (typeof window === 'undefined')
95
+ return Promise.reject(new FingerlyServerError());
96
+ // One promise for the page, in flight or already settled, which is what
97
+ // makes `useIdentify({ immediate: true })` safe in as many components as
98
+ // want it.
99
+ //
100
+ // Memoising the promise rather than the report also settles a case the Vue
101
+ // binding had to learn: under `submit: false` there is no requestId, so a
102
+ // cache keyed on one never engages and every component re-collects the
103
+ // whole fingerprint. A promise has an identity either way.
104
+ if (current && !identifyOptions.force)
105
+ return current;
106
+ isLoading = true;
107
+ error = null;
108
+ const run = client()
109
+ .then((fingerly) => fingerly.identify({
110
+ ...(identifyOptions.tag === undefined ? {} : { tag: identifyOptions.tag }),
111
+ ...(options.submit === undefined ? {} : { submit: options.submit }),
112
+ }))
113
+ .then((result) => {
114
+ requestId = result.requestId === '' ? null : result.requestId;
115
+ visitorId = result.visitorId === '' ? null : result.visitorId;
116
+ visitorIsNew = result.visitorIsNew;
117
+ visitorConfidence = result.visitorConfidence;
118
+ identifiable = result.identifiable;
119
+ duplicate = result.duplicate;
120
+ checkState = result.state === '' ? null : result.state;
121
+ reason = result.reason === '' ? null : result.reason;
122
+ suspectScore = result.suspectScore;
123
+ suspectLevel = result.suspectLevel;
124
+ triggers = result.triggers;
125
+ verdicts = result.verdicts;
126
+ report = result.report;
127
+ return result;
128
+ })
129
+ .catch((cause) => {
130
+ error = cause instanceof Error ? cause : new Error(String(cause));
131
+ // Forgotten, so the next caller retries rather than being handed a
132
+ // rejected promise forever.
133
+ if (current === run)
134
+ current = undefined;
135
+ // Rethrown as well as stored: a caller that awaited identify() should
136
+ // be able to try/catch it, and a component that only reads `error`
137
+ // should not have to.
138
+ throw error;
139
+ })
140
+ .finally(() => {
141
+ isLoading = false;
142
+ });
143
+ current = run;
144
+ return run;
145
+ };
146
+ const refresh = (refreshOptions = {}) => identify({ ...refreshOptions, force: true });
147
+ // Getters rather than fields: reading through one is what subscribes the
148
+ // caller's template to the rune behind it. Returning the values directly
149
+ // would hand out a snapshot taken at the moment this function ran.
150
+ return {
151
+ get requestId() {
152
+ return requestId;
153
+ },
154
+ get visitorId() {
155
+ return visitorId;
156
+ },
157
+ get visitorIsNew() {
158
+ return visitorIsNew;
159
+ },
160
+ get visitorConfidence() {
161
+ return visitorConfidence;
162
+ },
163
+ get identifiable() {
164
+ return identifiable;
165
+ },
166
+ get duplicate() {
167
+ return duplicate;
168
+ },
169
+ get state() {
170
+ return checkState;
171
+ },
172
+ get reason() {
173
+ return reason;
174
+ },
175
+ get suspectScore() {
176
+ return suspectScore;
177
+ },
178
+ get suspectLevel() {
179
+ return suspectLevel;
180
+ },
181
+ get triggers() {
182
+ return triggers;
183
+ },
184
+ get verdicts() {
185
+ return verdicts;
186
+ },
187
+ get report() {
188
+ return report;
189
+ },
190
+ get error() {
191
+ return error;
192
+ },
193
+ get isLoading() {
194
+ return isLoading;
195
+ },
196
+ get isReady() {
197
+ return isReady;
198
+ },
199
+ get isSuspicious() {
200
+ return isSuspicious;
201
+ },
202
+ get consent() {
203
+ return consent;
204
+ },
205
+ setConsent,
206
+ identify,
207
+ refresh,
208
+ client,
209
+ };
210
+ }
211
+ //# sourceMappingURL=state.svelte.js.map