@prson/login-sdk 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.
package/dist/bind.d.ts ADDED
@@ -0,0 +1,224 @@
1
+ /**
2
+ * DOM binding helpers — drive a `session.request(...)` from a
3
+ * page's existing form elements.
4
+ *
5
+ * Two entry points:
6
+ *
7
+ * * [`bindInput`] — for a single `<input>` / `<textarea>` /
8
+ * `<select>` element. Reads the element's `type`, `name`,
9
+ * `placeholder`, `required`, `min`/`max`/`minlength`/`maxlength`
10
+ * /`pattern`, and (for `<select>`) `<option>` children. Returns
11
+ * a controller whose `.request()` method synthesises a single
12
+ * `kind: "input"` request and, on a successful wallet reply,
13
+ * writes the value back into the element and dispatches
14
+ * `input` + `change` events so reactive frameworks pick it up.
15
+ *
16
+ * * [`bindForm`] — for a `<form>` (or any container holding
17
+ * inputs). Walks descendant `<input>`/`<textarea>`/`<select>`
18
+ * elements in document order, synthesises one
19
+ * `kind: "input-form"` request carrying every field, opens
20
+ * a single wallet drawer that paginates prev / next / send,
21
+ * fills every element on reply, and (when the bind target is
22
+ * a `<form>`) calls `requestSubmit()` so the page's existing
23
+ * submit handlers fire.
24
+ *
25
+ * Neither helper auto-fires. The host wires the controller's
26
+ * `.request()` to whatever trigger they prefer — a button click,
27
+ * focus, route change, etc. Keeps the SDK out of UX decisions
28
+ * about WHEN to ask.
29
+ */
30
+ import type { PrsonLoginSession } from "./session.js";
31
+ import type { LoginResponse, RequestOptions } from "./requests.js";
32
+ export interface BindController {
33
+ /**
34
+ * Synthesise a request from the bound element + send it. Resolves
35
+ * with whatever the wallet replied (already written into the
36
+ * element(s) on success). Multiple concurrent calls share the
37
+ * same controller; the wallet's queue / rate-limit policy
38
+ * decides whether the second one is accepted.
39
+ */
40
+ request(opts?: RequestOptions & {
41
+ reason?: string;
42
+ }): Promise<LoginResponse>;
43
+ /** Drop any per-bind state. The helpers are stateless today, but
44
+ * the contract is reserved for future expansion (e.g. a
45
+ * focus-triggered auto-bind). */
46
+ dispose(): void;
47
+ }
48
+ /**
49
+ * Bind to a single input-shaped element. Accepted nodes:
50
+ *
51
+ * * `<input>` (type ∈ text/search/email/tel/url/number/password
52
+ * — falls back to `text` for unsupported types like `date`),
53
+ * * `<textarea>` (treated as a `text` input),
54
+ * * `<select>` (with `<option>` children).
55
+ *
56
+ * The element's `aria-label`, label-for, or closest `<label>` text
57
+ * becomes the wallet's prompt label. `placeholder` rides through.
58
+ * Numeric / pattern constraints become wallet-side validation.
59
+ *
60
+ * Reply: the wallet's `value` is written via `element.value = ...`
61
+ * + `input` + `change` events. For `<select>`, the value is matched
62
+ * against the option `value` attributes.
63
+ */
64
+ export declare function bindInput(session: PrsonLoginSession, element: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement): BindController;
65
+ /**
66
+ * Bind to a `<form>` or any container element. Walks descendant
67
+ * input-shaped elements in document order, sends ONE
68
+ * `kind: "input-form"` request, and on reply fills every matching
69
+ * field + dispatches events.
70
+ *
71
+ * Field name resolution:
72
+ *
73
+ * 1. `element.name` — the canonical key.
74
+ * 2. `element.id` — fallback for label-less inputs.
75
+ * 3. `_field_<index>` — synthetic fallback so the reply still
76
+ * finds its target.
77
+ *
78
+ * If the bound container IS a `<form>`, a successful reply also
79
+ * fires `form.requestSubmit()` so the host's existing submit
80
+ * handler picks up. Containers that aren't forms skip the submit
81
+ * step.
82
+ *
83
+ * Buttons/checkboxes/hidden inputs are ignored on purpose — they
84
+ * don't fit the kiosk-input shape and confuse the wallet drawer.
85
+ */
86
+ export declare function bindForm(session: PrsonLoginSession, container: HTMLElement): BindController;
87
+ /**
88
+ * Fields whose value must never travel over the live channel: password
89
+ * inputs and anything marked `autocomplete` current-password /
90
+ * new-password / one-time-code. Anyone who scans a sign-in code first
91
+ * holds the phone end of the channel, so the SDK neither mirrors these
92
+ * values to the phone nor lets the phone fill them: bindInput refuses,
93
+ * bindForm and remote navigation skip them.
94
+ */
95
+ export declare function isSensitiveField(el: Element): boolean;
96
+ export interface RemoteNavController {
97
+ /**
98
+ * Stop pushing focus events to the wallet + stop listening for
99
+ * inbound nav/value/logout commands. The session itself stays
100
+ * live; only the helper detaches.
101
+ */
102
+ dispose(): void;
103
+ }
104
+ export interface RemoteNavOptions {
105
+ /**
106
+ * Root to scan for tabbable inputs. Defaults to `document.body`.
107
+ * Limit to a region (e.g. a checkout form) if the page has
108
+ * unrelated inputs you don't want the wallet to step through.
109
+ */
110
+ root?: HTMLElement;
111
+ /**
112
+ * Override the default tab order. By default we use a generous
113
+ * `:is(input, textarea, select)` filter excluding hidden / disabled
114
+ * / readonly / type=hidden / type=submit. Return your own
115
+ * NodeList-like array to take full control.
116
+ */
117
+ collectFields?: () => Array<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>;
118
+ }
119
+ /**
120
+ * Wire up **remote navigation**. Pushes the page's currently-focused
121
+ * input to the wallet (metadata + current value) and applies inbound
122
+ * `nav` / `value` / `logout` commands as the user interacts with the
123
+ * wallet's persistent navigation banner.
124
+ *
125
+ * Wiring summary:
126
+ *
127
+ * * `focusin` on any tabbable input → `session._sendFocus(focus)`.
128
+ * * `focusout` on the same → `session._sendFocus(null)`.
129
+ * * `input` on the focused element → push the new value to the
130
+ * wallet so the phone mirror stays in sync if the user typed on
131
+ * the desktop. Debounced to one frame to avoid flooding.
132
+ * * Inbound `nav: "prev" | "next"` → move DOM focus along the
133
+ * tabbable-input order from the focused element.
134
+ * * Inbound `nav: "submit"` → `form.requestSubmit()` on the closest
135
+ * enclosing form.
136
+ * * Inbound `value` → write to the focused element + dispatch
137
+ * `input` + `change`. Reactive frameworks pick it up.
138
+ * * Inbound `logout` → session already torn down by the dispatcher;
139
+ * helper just detaches.
140
+ *
141
+ * Call this once after `signIn()` resolves when you passed
142
+ * `remoteNavigation: true`. The returned controller's `dispose()` is
143
+ * idempotent and runs on `signed_out` automatically.
144
+ */
145
+ export declare function enableRemoteNavigation(session: PrsonLoginSession, opts?: RemoteNavOptions): RemoteNavController;
146
+ /**
147
+ * Options for [`bindMouse`].
148
+ */
149
+ export interface BindMouseOptions extends RequestOptions {
150
+ /**
151
+ * Input mode the wallet should default to. The wallet UI may still
152
+ * surface a toggle to switch mid-session — frames received then
153
+ * carry the actual mode in `mouse.mode`. Defaults to `"touch"`.
154
+ */
155
+ mode?: "touch" | "magic";
156
+ /** Cursor diameter in CSS pixels. Default 28. */
157
+ size?: number;
158
+ /**
159
+ * Cursor background colour (any CSS colour). Default a translucent
160
+ * blue that's visible on both light and dark pages.
161
+ */
162
+ color?: string;
163
+ /**
164
+ * Optional reason shown in the wallet drawer ("Tap to control the
165
+ * page", etc.).
166
+ */
167
+ reason?: string;
168
+ /**
169
+ * Initial cursor position. Defaults to viewport centre. Pass
170
+ * `{ x: 0, y: 0 }` to anchor in the top-left.
171
+ */
172
+ initialPosition?: {
173
+ x: number;
174
+ y: number;
175
+ };
176
+ /**
177
+ * Optional callback fired on every applied frame. Useful for
178
+ * sites that want to highlight the hovered element or show a
179
+ * trail. Receives the cursor's new viewport coordinates.
180
+ */
181
+ onMove?: (pos: {
182
+ x: number;
183
+ y: number;
184
+ }) => void;
185
+ /**
186
+ * Optional click handler — receives the element under the cursor
187
+ * at the moment of the click. The default behaviour (dispatching
188
+ * a synthetic `click` event on that element) still runs unless
189
+ * the callback returns `false`.
190
+ */
191
+ onClick?: (target: Element | null) => void | boolean;
192
+ }
193
+ /**
194
+ * Bind a virtual mouse to the session. Opens a `kind: "mouse"`
195
+ * request on the wallet, then subscribes to the streamed
196
+ * `mouse-update` envelopes and applies them to a CSS-positioned
197
+ * cursor on top of the page.
198
+ *
199
+ * Two modes (the wallet may toggle them mid-session):
200
+ *
201
+ * * `"touch"` — the phone is a touchpad. Drag = move (delta in
202
+ * CSS px), tap = click, double-tap = double-click, two-finger
203
+ * drag = scroll.
204
+ * * `"magic"` — phone gyro + accelerometer drive a "magic wand".
205
+ * Tap on the phone = click; swipe up/down = scroll.
206
+ *
207
+ * The cursor is a `<div>` fixed-positioned at z-index `2147483647`
208
+ * (the max 32-bit signed int — same trick browser extension
209
+ * overlays use to outrank page chrome). `pointer-events: none` so
210
+ * it never intercepts real clicks; we use `elementFromPoint` +
211
+ * synthetic events to forward clicks to the page underneath.
212
+ *
213
+ * Returns a [`BindController`] — call `dispose()` to detach the
214
+ * cursor and stop applying frames. The wallet drawer stays open
215
+ * until the user closes it; disposing the controller silently
216
+ * drops further frames but doesn't tell the wallet to stop.
217
+ *
218
+ * @example
219
+ * const mouse = bindMouse(session, { mode: "touch" });
220
+ * await mouse.request();
221
+ * // later
222
+ * mouse.dispose();
223
+ */
224
+ export declare function bindMouse(session: PrsonLoginSession, opts?: BindMouseOptions): BindController;