@daybook/feedback 1.4.3 → 1.5.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,403 +1,463 @@
1
- # `@daybook/feedback`
2
-
3
- In-app feedback for the web. The reporter points at what is wrong and says what happened; everything
4
- a triager needs is captured without asking them.
5
-
6
- 9 KB gzipped, no dependencies.
7
-
8
- ## Install
9
-
10
- ### Script tag — no build step
11
-
12
- ```html
13
- <script src="https://daybook.team/sdk/v1/feedback.js"></script>
14
- <script>
15
- var pm = DaybookFeedback.init({
16
- ingestKey: 'pmi_…',
17
- reporter: { externalId: user.id, email: user.email },
18
- })
19
- </script>
20
- ```
21
-
22
- The `/sdk/v1/` path is versioned on purpose. A script tag points at a URL forever, so what is there
23
- stays compatible with what `/ingest/v1` accepts; a breaking change would appear at `/sdk/v2/` beside
24
- it rather than replacing it under everybody's feet.
25
-
26
- ### JavaScript, as a module
27
-
28
- ```
29
- npm install @daybook/feedback
30
- ```
31
-
32
- ```js
33
- import { init } from '@daybook/feedback'
34
-
35
- const pm = init({
36
- ingestKey: 'pmi_…', // per-environment, write-only, safe to ship
37
- app: { version: '1.4.0' },
38
- reporter: { externalId: user.id, email: user.email },
39
- })
40
- ```
41
-
42
- ### React
43
-
44
- Mount it once, near the root — not per route, or each navigation starts a second widget.
45
-
46
- ```tsx
47
- // FeedbackWidget.tsx
48
- import { useEffect } from 'react'
49
- import { init } from '@daybook/feedback'
50
-
51
- export function FeedbackWidget({ user }: { user: { id: string; email: string } | null }) {
52
- useEffect(() => {
53
- const pm = init({
54
- ingestKey: import.meta.env.VITE_FEEDBACK_KEY,
55
- surface: 'web-app',
56
- reporter: user ? { externalId: user.id, email: user.email } : undefined,
57
- })
58
-
59
- // Strict mode runs effects twice in development. stop() is what makes that harmless —
60
- // without it you get two launchers, and the first one holds the events.
61
- return () => pm.stop()
62
- }, [user?.id])
63
-
64
- return null
65
- }
66
- ```
67
-
68
- Render `<FeedbackWidget user={user} />` once in your layout. It draws nothing itself: the widget
69
- attaches to `document.body`, so it is not affected by a parent's `overflow` or stacking context.
70
-
71
- ### Vue
72
-
73
- ```ts
74
- // useFeedback.ts
75
- import { onMounted, onUnmounted, watch, type Ref } from 'vue'
76
- import { init, type DaybookFeedback } from '@daybook/feedback'
77
-
78
- export function useFeedback(user: Ref<{ id: string; email: string } | null>) {
79
- let pm: DaybookFeedback | null = null
80
-
81
- // Mounted rather than created in setup(), so it does nothing during SSR — the widget needs a
82
- // document. Whoever is signed in *now* is passed to init: a watcher with `immediate: true`
83
- // would fire during setup, before this runs, and identify() on nothing is silently no-op.
84
- onMounted(() => {
85
- pm = init({
86
- ingestKey: import.meta.env.VITE_FEEDBACK_KEY,
87
- surface: 'web-app',
88
- reporter: user.value
89
- ? { externalId: user.value.id, email: user.value.email }
90
- : undefined,
91
- })
92
- })
93
-
94
- // identify() re-handshakes, so signing in and out is reflected without remounting — which
95
- // matters because an approval granted to that person is only seen at the next handshake.
96
- watch(user, next => pm?.identify(
97
- next ? { externalId: next.id, email: next.email } : null))
98
-
99
- onUnmounted(() => pm?.stop())
100
- }
101
- ```
102
-
103
- Call `useFeedback(user)` once, from `App.vue`.
104
-
105
- A launcher appears bottom-right. `F` opens the picker, `Esc` backs out, `Cmd/Ctrl+Enter` sends.
106
-
107
- The key is the only thing you have to supply. Reports go to Daybook's own API by default — where
108
- they are received is ours to keep working, not a hostname for you to paste and then keep in step
109
- with us. Pass `apiUrl` only to point at something that is not Daybook: a self-hosted install, or a
110
- local API while you are developing.
111
-
112
- ## Allow your domain first
113
-
114
- The widget only runs on domains you have listed. In Daybook, open **Project settings → Feedback
115
- widget**, and add your origin to an environment. That is the whole step — it works the moment you
116
- save it. There is nothing to verify, because the list only ever *narrows* what a key already
117
- permits: it cannot grant anyone access to anything.
118
-
119
- `localhost` is an origin like any other. Put it on the **development** environment and you are
120
- working in a minute.
121
-
122
- **Or let your assistant do all of it.** If you have Daybook connected as an MCP server in the
123
- project you are adding the widget to, `get_feedback_install` returns the package, the snippet for
124
- your framework, the components you can file against, and — most usefully — a `blockers` list saying
125
- what is still unconfigured. `allow_feedback_domain` and `create_feedback_key` do the two steps that
126
- need doing. That path exists because the SDK fails quietly by design: without it an assistant sets
127
- everything up, sees no error, and has no way to tell a working install from a silent one.
128
-
129
- On a domain that is not listed, the handshake returns `403 origin_not_allowed` and the widget quietly
130
- does not appear — which is also what it does on a revoked key and on a dead network. A feedback
131
- button must never break the page it is on.
132
-
133
- ## One key, many surfaces
134
-
135
- One key serves a whole product. Each install says which part of it it is:
136
-
137
- ```js
138
- init({ ingestKey: 'pmi_…', surface: 'mobile-web' })
139
- ```
140
-
141
- `surface` is a component key from your project. The key still fixes the project and the environment
142
- — the parts that must not be forgeable — so this only routes *within* a project you already write
143
- to. An unknown value falls back to the key's own component rather than failing: losing the
144
- attribution is not a reason to lose the report.
145
-
146
- ## Who is reporting
147
-
148
- `init` takes a `reporter`, and `identify()` updates it once the host app knows who signed in:
149
-
150
- ```js
151
- const pm = init({ … })
152
-
153
- pm.identify({ externalId: user.id, email: user.email, name: user.name })
154
- pm.identify(null) // signing out
155
- ```
156
-
157
- That is enough for most installs. But **a browser saying who it is, is a claim** — anybody viewing
158
- the page can type any address into the console. If your integration is set to require it, your
159
- *backend* signs the identity:
160
-
161
- ```js
162
- // On your server. The identity secret never reaches a browser.
163
- const signature = crypto
164
- .createHmac('sha256', process.env.DAYBOOK_IDENTITY_SECRET)
165
- .update(user.id)
166
- .digest('hex')
167
- ```
168
-
169
- ```js
170
- // In the page, with the signature your server produced.
171
- init({ …, reporter: { externalId: user.id, email: user.email }, signature })
172
- ```
173
-
174
- `pm.authenticate(signature)` sets it later, for an app that fetches it after boot.
175
-
176
- Same shape as Intercom's and Crisp's identity verification, deliberately — if you have done one of
177
- those, you have done this.
178
-
179
- ### Or sign in with Daybook
180
-
181
- A third mode, for when the reporter already has a Daybook account — an internal tool, or your own
182
- team dogfooding. Then there is no secret to configure at all:
183
-
184
- ```js
185
- const pm = init({ ingestKey: 'pmi_…' })
186
-
187
- // It opens a popup, so a real click has to trigger it — a call at startup is blocked.
188
- document.querySelector('#feedback-signin')
189
- ?.addEventListener('click', () => pm.signIn())
190
- ```
191
-
192
- In React, hold the instance in a `useRef` and call it from your own button's `onClick`; in Vue,
193
- return `() => pm?.signIn()` from the composable. In this mode the reporter is settled by the
194
- sign-in, so nothing needs `reporter` or `identify()`.
195
-
196
- They approve a short consent screen, and we authenticate them rather than taking your word for it.
197
-
198
- **Not for a product whose reporters are your customers.** They would have to create an account with
199
- us to report a bug, which is how feedback stops arriving.
200
-
201
- ## Approval
202
-
203
- Separately from *how* an identity is established, the integration decides *who may file*: **Open**
204
- (anyone, anonymously), **Identified** (anyone who says who they are), or **Approved** (only people
205
- somebody let in). Under Approved, a new reporter sees "Feedback
206
- access pending approval" instead of the launcher until a maintainer approves them, and a blocked one
207
- sees nothing at all.
208
-
209
- `onReady` tells the host app which of those happened, if you would rather say it in your own words:
210
-
211
- ```js
212
- init({ …, onReady: h => console.log(h.reporterStatus) }) // Approved | Pending | Blocked | Anonymous
213
- ```
214
-
215
- ## What it captures
216
-
217
- The reason this exists rather than a form: the questions that follow "it looks wrong" — which browser,
218
- which build, what errored just before — are all answerable at the moment of capture, and unanswerable
219
- three days later when the reporter has moved on.
220
-
221
- - **The element**, as a CSS selector plus the click position as a fraction of that element's bounding
222
- box. Not page pixels: an anchor recorded on a desktop layout has to still mean something on a phone.
223
- An 80-character text snapshot comes too, so a human can find the thing after a redesign breaks the
224
- selector, and the page it was on. Where nothing readable identifies the element — no test id, no
225
- stable id, only generated class names — the selector falls back to its position in the tree, so a
226
- pin always names an element.
227
-
228
- **More than one, when one is not enough** (1.4). After the first pin the composer offers *Add
229
- another pin*; the reporter's message, kind and files stay as they were. Pins are numbered on the
230
- page, in the panel and in the screenshot, so "pin 2" in a message means something. On the wire
231
- `context.anchor` is still the first pin — exactly what earlier versions sent — and
232
- `context.anchors` carries all of them when there is more than one.
233
- - **Page and device** — route, title, referrer, locale, timezone, viewport with DPR, and a readable
234
- browser and OS rather than a raw user-agent string.
235
- - **Breadcrumbs** — the last 40 navigations, clicks, console errors and failed or slow requests.
236
- - **The page itself**, as `page-snapshot.json`: the markup with its classes and attributes, the
237
- computed style of the pinned element and its ancestors, everything floating over the page at that
238
- moment, what had focus, where the page was scrolled to, and which stylesheets were readable.
239
-
240
- This is the half of a report a screenshot cannot give you, and it needs no permission — it is the
241
- page's own state, read by script that is already running on it. A picture is for a person; most
242
- feedback now passes an assistant first, and to an assistant a PNG is nearly opaque where a DOM is
243
- the whole answer.
244
-
245
- It obeys `redact` exactly as everything else does: field values are described rather than
246
- reproduced, and `data-daybook-private` subtrees are replaced by a marker. Script bodies are
247
- dropped, attributes and text are capped, and the whole thing truncates rather than growing.
248
-
249
- **What it does carry is the page's visible text**, because that is what the page is. On screens
250
- showing personal data, decide whether that belongs in a report — `dom: false` turns it off, and
251
- `data-daybook-private` withholds a subtree without turning the whole thing off.
252
- - **A screenshot**, if the reporter ticks "Capture the screen" and consents to the browser's share
253
- prompt. The widget hides itself for the frame, so the picture is of the page underneath rather
254
- than of the form that was just filled in — and every element the reporter pinned is ringed in the
255
- picture, numbered when there is more than one.
256
-
257
- The ring is the difference between a report you can act on and one you have to reconstruct. A
258
- selector and a text snapshot tell you which node; they do not tell you which of the forty things
259
- on that screen the sentence is about. It is drawn in the widget's own layer, never on your page:
260
- no style of yours is touched, nothing reflows, and there is no undo to get wrong. The rest of the
261
- page is left exactly as it was — no dimming — because the screenshot is also the record of what
262
- the page looked like, and a report about a colour should not arrive with the colours changed.
263
-
264
- `screenshots` decides what the composer offers, and takes three values:
265
-
266
- | Value | The composer |
267
- |---|---|
268
- | `true` (default) | offers the capture, ticked |
269
- | `'optional'` | offers the capture, not ticked |
270
- | `false` | does not offer it at all |
271
-
272
- There is no setting that shows the control and then ignores it. A tick box that does nothing is
273
- worse than no tick box.
274
-
275
- ## Where it sits
276
-
277
- `placement` puts the widget in a corner: `bottom-right` (the default), `bottom-left`, `top-right`
278
- or `top-left`. Set here it overrides the corner chosen in the workspace's own settings, which is
279
- the right way round — the workspace owner is choosing a default for every install, and whoever
280
- writes this line is looking at the page.
281
-
282
- ```js
283
- init({ ingestKey: '...', placement: 'bottom-left' })
284
- ```
285
-
286
- ### It moves out of your other buttons' way
287
-
288
- Most pages already have something in the bottom-right corner: a chat bubble, a back-to-top arrow,
289
- a cookie notice. The widget looks at what is painted in the corner it is about to occupy and stacks
290
- above it rather than on it — including things that are not there yet, like a back-to-top button that
291
- appears once the reporter scrolls, which is re-checked on scroll and whenever the page changes.
292
-
293
- There is no list of selectors involved and there will not be one: what a chat bubble and a
294
- back-to-top button have in common is not a class name, it is being fixed, painted and small in the
295
- corner. Anything larger than a quarter of the viewport is treated as scenery — a modal backdrop is
296
- not something to politely stack above — and if getting clear would mean moving more than a third of
297
- the way up the page, it stays put and overlaps instead.
298
-
299
- Turn it off with `avoidOverlap: false` if your page positions things by measuring ours, or if the
300
- movement bothers you more than the overlap would.
301
-
302
- ## Moving the panel
303
-
304
- The composer is dragged by its header, and lands against whichever side of the window it is let go
305
- nearest — only that axis pins, so dragging it to the left edge halfway down leaves it halfway down.
306
- A double-click on the header puts it back.
307
-
308
- **A drag lasts for one report.** Sending resets it, so does closing, and the next report opens where
309
- `placement` says. It used to be remembered across visits, which sounds helpful and is not: the
310
- widget then turns up somewhere different on every page, and the somewhere is wherever it was last
311
- shoved aside — a position chosen to be temporary.
312
-
313
- The confirmation always appears at home, never where the panel was dragged to. The reporter moved
314
- the panel to see what was under it; putting the receipt back over that same spot answers a question
315
- nobody asked and covers the thing they moved it for.
316
-
317
- It closes on the cross or on Cancel, and on nothing else — not Escape, not a click on the page
318
- behind it. Every one of those gestures gets pressed while a report is being written, and each of
319
- them used to throw the words away.
320
-
321
- ## Redaction
322
-
323
- On by default, and it runs before anything leaves the device — the server cannot undo a leak that has
324
- already crossed the wire.
325
-
326
- - Input values are described, never reproduced: `[7 chars]`, or `[redacted]` when the field name
327
- suggests a secret.
328
- - Query strings are stripped from every captured URL.
329
- - Emails, JWTs, bearer tokens and long digit runs are masked in console text.
330
- - Password fields and anything you mark `data-daybook-private` are blurred before a screenshot is taken.
331
-
332
- ```html
333
- <div data-daybook-private>Card ending 4242</div>
334
- ```
335
-
336
- Turn it off with `redact: false` only if you are certain about what is on screen.
337
-
338
- ## Offline
339
-
340
- A report written the moment something breaks is frequently written the moment the network is also
341
- broken. Failed sends are queued in `localStorage` and retried on the next visit, carrying an
342
- idempotency key so a retry the server already received returns the original rather than filing a
343
- duplicate. 4xx responses other than 429 are not retried — a client that retries a rejected body
344
- forever becomes a denial of service against its own backend.
345
-
346
- ## Without the UI
347
-
348
- ```js
349
- const pm = init({ … })
350
-
351
- pm.open() // your own "Report a problem" menu item
352
- await pm.report('Checkout threw', { // a caught error, no user present
353
- kind: 'bug',
354
- context: { orderId: '123' },
355
- })
356
- ```
357
-
358
- `report()` takes no screenshot: there is nobody there to consent to a screen share.
359
-
360
- ## The look is set in Daybook, not in code
361
-
362
- Everything about the widget's appearance lives on the integration, so it is changed on the Feedback
363
- widget page in Daybook and takes effect on every install of that key without a deploy:
364
-
365
- | | |
366
- |---|---|
367
- | Button style | `pill`, `pill-icon`, `icon`, `text`, `outline` |
368
- | Button text | Anything up to 24 characters. Defaults to "Feedback" |
369
- | Colour scheme | `auto` (the default), `light`, `dark` |
370
- | Corner | Bottom right by default — and `placement` in `init()` overrides it |
371
- | Accent | Any CSS colour |
372
-
373
- **Auto is the default and is the one to keep.** The widget is a guest on your page, and your page is
374
- already light or dark for that reader; following their own setting is almost always right. Pin it
375
- only when your app is one or the other regardless of the system.
376
-
377
- The five button styles exist because one button cannot be right for every page. A product with its
378
- own bold chat bubble does not want a second bold pill beside it; a spare documentation site does not
379
- want a filled button at all; a dense application usually wants the smallest possible mark. All five
380
- keep the same hit area in the same corner, so nothing else about the widget changes with the choice.
381
-
382
- If you are building your own settings screen, `previewLauncher(element, theme)` draws the real
383
- button — the real stylesheet, in a shadow root — so a preview cannot drift from the thing it
384
- previews.
385
-
386
- ## Theming, but not styling
387
-
388
- The widget renders in a shadow root. A host page's `* { }` reset, its `button { all: unset }`, or its
389
- own stacking context cannot reach in — which matters because the page someone is reporting a problem
390
- on is exactly the page whose CSS you should not trust.
391
-
392
- So it is themed from Daybook rather than from your stylesheet: accent colour, corner radius, position
393
- and launcher label are set on the integration and arrive with the handshake, which means changing
394
- them needs no redeploy of your site. Anything not on that list is not settable, on purpose.
395
-
396
- ## Limits
397
-
398
- Two, and they are different things. A **burst limit** of 60 reports a minute per install stops a
399
- leaked key becoming a write loop. A **period quota** belongs to the whole Daybook project and is what
400
- runs out at the end of a month; the integrations screen shows how much of it is spent.
401
-
402
- Attachments go through the API rather than straight to storage, capped per environment — 8 MB by
403
- default, which is generous for a screenshot.
1
+ # `@daybook/feedback`
2
+
3
+ In-app feedback for the web. The reporter points at what is wrong and says what happened; everything
4
+ a triager needs is captured without asking them.
5
+
6
+ 9 KB gzipped, no dependencies.
7
+
8
+ ## Install
9
+
10
+ ### Script tag — no build step
11
+
12
+ ```html
13
+ <script src="https://daybook.team/sdk/v1/feedback.js"></script>
14
+ <script>
15
+ var pm = DaybookFeedback.init({
16
+ ingestKey: 'pmi_…',
17
+ reporter: { externalId: user.id, email: user.email },
18
+ })
19
+ </script>
20
+ ```
21
+
22
+ The `/sdk/v1/` path is versioned on purpose. A script tag points at a URL forever, so what is there
23
+ stays compatible with what `/ingest/v1` accepts; a breaking change would appear at `/sdk/v2/` beside
24
+ it rather than replacing it under everybody's feet.
25
+
26
+ ### JavaScript, as a module
27
+
28
+ ```
29
+ npm install @daybook/feedback
30
+ ```
31
+
32
+ ```js
33
+ import { init } from '@daybook/feedback'
34
+
35
+ const pm = init({
36
+ ingestKey: 'pmi_…', // per-environment, write-only, safe to ship
37
+ app: { version: '1.4.0' },
38
+ reporter: { externalId: user.id, email: user.email },
39
+ })
40
+ ```
41
+
42
+ ### React
43
+
44
+ Mount it once, near the root — not per route, or each navigation starts a second widget.
45
+
46
+ ```tsx
47
+ // FeedbackWidget.tsx
48
+ import { useEffect } from 'react'
49
+ import { init } from '@daybook/feedback'
50
+
51
+ export function FeedbackWidget({ user }: { user: { id: string; email: string } | null }) {
52
+ useEffect(() => {
53
+ const pm = init({
54
+ ingestKey: import.meta.env.VITE_FEEDBACK_KEY,
55
+ surface: 'web-app',
56
+ reporter: user ? { externalId: user.id, email: user.email } : undefined,
57
+ })
58
+
59
+ // Strict mode runs effects twice in development. stop() is what makes that harmless —
60
+ // without it you get two launchers, and the first one holds the events.
61
+ return () => pm.stop()
62
+ }, [user?.id])
63
+
64
+ return null
65
+ }
66
+ ```
67
+
68
+ Render `<FeedbackWidget user={user} />` once in your layout. It draws nothing itself: the widget
69
+ attaches to `document.body`, so it is not affected by a parent's `overflow` or stacking context.
70
+
71
+ ### Vue
72
+
73
+ ```ts
74
+ // useFeedback.ts
75
+ import { onMounted, onUnmounted, watch, type Ref } from 'vue'
76
+ import { init, type DaybookFeedback } from '@daybook/feedback'
77
+
78
+ export function useFeedback(user: Ref<{ id: string; email: string } | null>) {
79
+ let pm: DaybookFeedback | null = null
80
+
81
+ // Mounted rather than created in setup(), so it does nothing during SSR — the widget needs a
82
+ // document. Whoever is signed in *now* is passed to init: a watcher with `immediate: true`
83
+ // would fire during setup, before this runs, and identify() on nothing is silently no-op.
84
+ onMounted(() => {
85
+ pm = init({
86
+ ingestKey: import.meta.env.VITE_FEEDBACK_KEY,
87
+ surface: 'web-app',
88
+ reporter: user.value
89
+ ? { externalId: user.value.id, email: user.value.email }
90
+ : undefined,
91
+ })
92
+ })
93
+
94
+ // identify() re-handshakes, so signing in and out is reflected without remounting — which
95
+ // matters because an approval granted to that person is only seen at the next handshake.
96
+ watch(user, next => pm?.identify(
97
+ next ? { externalId: next.id, email: next.email } : null))
98
+
99
+ onUnmounted(() => pm?.stop())
100
+ }
101
+ ```
102
+
103
+ Call `useFeedback(user)` once, from `App.vue`.
104
+
105
+ A launcher appears bottom-right. `F` opens the picker, `Esc` backs out, `Cmd/Ctrl+Enter` sends.
106
+
107
+ The key is the only thing you have to supply. Reports go to Daybook's own API by default — where
108
+ they are received is ours to keep working, not a hostname for you to paste and then keep in step
109
+ with us. Pass `apiUrl` only to point at something that is not Daybook: a self-hosted install, or a
110
+ local API while you are developing.
111
+
112
+ ## Allow your domain first
113
+
114
+ The widget only runs on domains you have listed. In Daybook, open **Project settings → Feedback
115
+ widget**, and add your origin to an environment. That is the whole step — it works the moment you
116
+ save it. There is nothing to verify, because the list only ever *narrows* what a key already
117
+ permits: it cannot grant anyone access to anything.
118
+
119
+ `localhost` is an origin like any other. Put it on the **development** environment and you are
120
+ working in a minute.
121
+
122
+ **Or let your assistant do all of it.** If you have Daybook connected as an MCP server in the
123
+ project you are adding the widget to, `get_feedback_install` returns the package, the snippet for
124
+ your framework, the components you can file against, and — most usefully — a `blockers` list saying
125
+ what is still unconfigured. `allow_feedback_domain` and `create_feedback_key` do the two steps that
126
+ need doing. That path exists because the SDK fails quietly by design: without it an assistant sets
127
+ everything up, sees no error, and has no way to tell a working install from a silent one.
128
+
129
+ On a domain that is not listed, the handshake returns `403 origin_not_allowed` and the widget quietly
130
+ does not appear — which is also what it does on a revoked key and on a dead network. A feedback
131
+ button must never break the page it is on.
132
+
133
+ ## One key, many surfaces
134
+
135
+ One key serves a whole product. Each install says which part of it it is:
136
+
137
+ ```js
138
+ init({ ingestKey: 'pmi_…', surface: 'mobile-web' })
139
+ ```
140
+
141
+ `surface` is a component key from your project. The key still fixes the project and the environment
142
+ — the parts that must not be forgeable — so this only routes *within* a project you already write
143
+ to. An unknown value falls back to the key's own component rather than failing: losing the
144
+ attribution is not a reason to lose the report.
145
+
146
+ ## Who is reporting
147
+
148
+ `init` takes a `reporter`, and `identify()` updates it once the host app knows who signed in:
149
+
150
+ ```js
151
+ const pm = init({ … })
152
+
153
+ pm.identify({ externalId: user.id, email: user.email, name: user.name })
154
+ pm.identify(null) // signing out
155
+ ```
156
+
157
+ That is enough for most installs. But **a browser saying who it is, is a claim** — anybody viewing
158
+ the page can type any address into the console. If your integration is set to require it, your
159
+ *backend* signs the identity:
160
+
161
+ ```js
162
+ // On your server. The identity secret never reaches a browser.
163
+ const signature = crypto
164
+ .createHmac('sha256', process.env.DAYBOOK_IDENTITY_SECRET)
165
+ .update(user.id)
166
+ .digest('hex')
167
+ ```
168
+
169
+ ```js
170
+ // In the page, with the signature your server produced.
171
+ init({ …, reporter: { externalId: user.id, email: user.email }, signature })
172
+ ```
173
+
174
+ `pm.authenticate(signature)` sets it later, for an app that fetches it after boot.
175
+
176
+ Same shape as Intercom's and Crisp's identity verification, deliberately — if you have done one of
177
+ those, you have done this.
178
+
179
+ ### Or sign in with Daybook
180
+
181
+ A third mode, for when the reporter already has a Daybook account — an internal tool, or your own
182
+ team dogfooding. Then there is no secret to configure at all:
183
+
184
+ ```js
185
+ const pm = init({ ingestKey: 'pmi_…' })
186
+
187
+ // It opens a popup, so a real click has to trigger it — a call at startup is blocked.
188
+ document.querySelector('#feedback-signin')
189
+ ?.addEventListener('click', () => pm.signIn())
190
+ ```
191
+
192
+ In React, hold the instance in a `useRef` and call it from your own button's `onClick`; in Vue,
193
+ return `() => pm?.signIn()` from the composable. In this mode the reporter is settled by the
194
+ sign-in, so nothing needs `reporter` or `identify()`.
195
+
196
+ They approve a short consent screen, and we authenticate them rather than taking your word for it.
197
+
198
+ **Not for a product whose reporters are your customers.** They would have to create an account with
199
+ us to report a bug, which is how feedback stops arriving.
200
+
201
+ ## Approval
202
+
203
+ Separately from *how* an identity is established, the integration decides *who may file*: **Open**
204
+ (anyone, anonymously), **Identified** (anyone who says who they are), or **Approved** (only people
205
+ somebody let in). Under Approved, a new reporter sees "Feedback
206
+ access pending approval" instead of the launcher until a maintainer approves them, and a blocked one
207
+ sees nothing at all.
208
+
209
+ `onReady` tells the host app which of those happened, if you would rather say it in your own words:
210
+
211
+ ```js
212
+ init({ …, onReady: h => console.log(h.reporterStatus) }) // Approved | Pending | Blocked | Anonymous
213
+ ```
214
+
215
+ ## What it captures
216
+
217
+ The reason this exists rather than a form: the questions that follow "it looks wrong" — which browser,
218
+ which build, what errored just before — are all answerable at the moment of capture, and unanswerable
219
+ three days later when the reporter has moved on.
220
+
221
+ - **The element**, as a CSS selector plus the click position as a fraction of that element's bounding
222
+ box. Not page pixels: an anchor recorded on a desktop layout has to still mean something on a phone.
223
+ An 80-character text snapshot comes too, so a human can find the thing after a redesign breaks the
224
+ selector, and the page it was on. Where nothing readable identifies the element — no test id, no
225
+ stable id, only generated class names — the selector falls back to its position in the tree, so a
226
+ pin always names an element.
227
+
228
+ **More than one, when one is not enough** (1.4). After the first pin the composer offers *Add
229
+ another pin*; the reporter's message, kind and files stay as they were. Pins are numbered on the
230
+ page, in the panel and in the screenshot, so "pin 2" in a message means something. On the wire
231
+ `context.anchor` is still the first pin — exactly what earlier versions sent — and
232
+ `context.anchors` carries all of them when there is more than one.
233
+ - **Page and device** — route, title, referrer, locale, timezone, viewport with DPR, and a readable
234
+ browser and OS rather than a raw user-agent string.
235
+ - **Breadcrumbs** — the last 40 navigations, clicks, console errors and failed or slow requests.
236
+ - **The page itself**, as `page-snapshot.json`: the markup with its classes and attributes, the
237
+ computed style of the pinned element and its ancestors, everything floating over the page at that
238
+ moment, what had focus, where the page was scrolled to, and which stylesheets were readable.
239
+
240
+ This is the half of a report a screenshot cannot give you, and it needs no permission — it is the
241
+ page's own state, read by script that is already running on it. A picture is for a person; most
242
+ feedback now passes an assistant first, and to an assistant a PNG is nearly opaque where a DOM is
243
+ the whole answer.
244
+
245
+ It obeys `redact` exactly as everything else does: field values are described rather than
246
+ reproduced, `data-daybook-private` subtrees are replaced by a marker, and credentials found in text
247
+ and attributes read `[masked: GitHub token]`. Whatever the reporter blurred is withheld as
248
+ `data-daybook-blurred`. Script bodies are dropped, attributes and text are capped, and the whole
249
+ thing truncates rather than growing.
250
+
251
+ **What it does carry is the page's visible text**, because that is what the page is. On screens
252
+ showing personal data, decide whether that belongs in a report — `dom: false` turns it off, and
253
+ `data-daybook-private` withholds a subtree without turning the whole thing off.
254
+ - **A screenshot**, if the reporter ticks "Capture the screen" and consents to the browser's share
255
+ prompt. The widget hides itself for the frame, so the picture is of the page underneath rather
256
+ than of the form that was just filled in — and every element the reporter pinned is ringed in the
257
+ picture, numbered when there is more than one.
258
+
259
+ The ring is the difference between a report you can act on and one you have to reconstruct. A
260
+ selector and a text snapshot tell you which node; they do not tell you which of the forty things
261
+ on that screen the sentence is about. It is drawn in the widget's own layer, never on your page:
262
+ no style of yours is touched, nothing reflows, and there is no undo to get wrong. The rest of the
263
+ page is left exactly as it was — no dimming — because the screenshot is also the record of what
264
+ the page looked like, and a report about a colour should not arrive with the colours changed.
265
+
266
+ Except where it must not show: private elements, credentials, and anything the reporter blurred
267
+ are covered before the frame is taken — see [Redaction](#redaction).
268
+
269
+ `screenshots` decides what the composer offers, and takes three values:
270
+
271
+ | Value | The composer |
272
+ |---|---|
273
+ | `true` (default) | offers the capture, ticked |
274
+ | `'optional'` | offers the capture, not ticked |
275
+ | `false` | does not offer it at all |
276
+
277
+ There is no setting that shows the control and then ignores it. A tick box that does nothing is
278
+ worse than no tick box.
279
+
280
+ ## Where it sits
281
+
282
+ `placement` puts the widget in a corner: `bottom-right` (the default), `bottom-left`, `top-right`
283
+ or `top-left`. Set here it overrides the corner chosen in the workspace's own settings, which is
284
+ the right way round — the workspace owner is choosing a default for every install, and whoever
285
+ writes this line is looking at the page.
286
+
287
+ ```js
288
+ init({ ingestKey: '...', placement: 'bottom-left' })
289
+ ```
290
+
291
+ ### It moves out of your other buttons' way
292
+
293
+ Most pages already have something in the bottom-right corner: a chat bubble, a back-to-top arrow,
294
+ a cookie notice. The widget looks at what is painted in the corner it is about to occupy and stacks
295
+ above it rather than on it — including things that are not there yet, like a back-to-top button that
296
+ appears once the reporter scrolls, which is re-checked on scroll and whenever the page changes.
297
+
298
+ There is no list of selectors involved and there will not be one: what a chat bubble and a
299
+ back-to-top button have in common is not a class name, it is being fixed, painted and small in the
300
+ corner. Anything larger than a quarter of the viewport is treated as scenery — a modal backdrop is
301
+ not something to politely stack above — and if getting clear would mean moving more than a third of
302
+ the way up the page, it stays put and overlaps instead.
303
+
304
+ Turn it off with `avoidOverlap: false` if your page positions things by measuring ours, or if the
305
+ movement bothers you more than the overlap would.
306
+
307
+ ## Moving the panel
308
+
309
+ The composer is dragged by its header, and lands against whichever side of the window it is let go
310
+ nearest — only that axis pins, so dragging it to the left edge halfway down leaves it halfway down.
311
+ A double-click on the header puts it back.
312
+
313
+ **A drag lasts for one report.** Sending resets it, so does closing, and the next report opens where
314
+ `placement` says. It used to be remembered across visits, which sounds helpful and is not: the
315
+ widget then turns up somewhere different on every page, and the somewhere is wherever it was last
316
+ shoved aside — a position chosen to be temporary.
317
+
318
+ The confirmation always appears at home, never where the panel was dragged to. The reporter moved
319
+ the panel to see what was under it; putting the receipt back over that same spot answers a question
320
+ nobody asked and covers the thing they moved it for.
321
+
322
+ It closes on the cross or on Cancel, and on nothing else — not Escape, not a click on the page
323
+ behind it. Every one of those gestures gets pressed while a report is being written, and each of
324
+ them used to throw the words away.
325
+
326
+ ## Redaction
327
+
328
+ On by default, and it runs before anything leaves the device — the server cannot undo a leak that has
329
+ already crossed the wire.
330
+
331
+ - Input values are described, never reproduced: `[7 chars]`, or `[redacted]` when the field name
332
+ suggests a secret.
333
+ - Query strings are stripped from every captured URL.
334
+ - Emails, JWTs, bearer tokens and long digit runs are masked in console text.
335
+ - Password fields and anything you mark `data-daybook-private` are blurred before a screenshot is taken.
336
+ - Credentials on the page are found and masked without anybody marking them (1.5) — below.
337
+
338
+ ```html
339
+ <div data-daybook-private>Card ending 4242</div>
340
+ ```
341
+
342
+ Turn it off with `redact: false` only if you are certain about what is on screen. It does not turn
343
+ off what the reporter blurs: that was their decision, made while looking at the page.
344
+
345
+ ### Credentials nobody marked
346
+
347
+ `data-daybook-private` covers what you foresaw. What nobody foresees is the settings screen that shows
348
+ a new API key once, a link whose query string still carries a token, a debug panel printing a JWT —
349
+ and the reporter, looking straight at it, rarely thinks of the key as part of the page they are
350
+ reporting. So the page's text, its attributes (links, `data-*`, `title`, a labelled `<meta>`), the
351
+ console lines, a pin's text and the page address are all read for credentials before anything is
352
+ sent. What is found becomes `[masked: GitHub token]` in the snapshot and a solid grey bar over
353
+ exactly those characters in the screenshot, and the report's `context.redaction` says how many.
354
+
355
+ Recognised on their own, because their prefix is not something prose contains for any other reason:
356
+
357
+ | | |
358
+ |---|---|
359
+ | Daybook API keys | `pmk_` and 64 hex characters |
360
+ | OpenAI, Anthropic | `sk-…`, `sk-proj-…`, `sk-ant-…` with a generated body |
361
+ | Stripe | `sk_live_…`, `sk_test_…`, `rk_live_…` — not the publishable `pk_` |
362
+ | GitHub | `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_` |
363
+ | Slack | `xoxb-`, `xoxa-`, `xoxp-`, `xoxr-`, `xoxs-` |
364
+ | AWS | access key ids, `AKIA…` and `ASIA…` |
365
+ | JWTs | `eyJ….eyJ….…` |
366
+ | Private keys | a `-----BEGIN … PRIVATE KEY-----` block |
367
+
368
+ Everything else needs two things together: a label right in front of it — `key`, `token`, `secret`,
369
+ `password`, `api`, `auth`, as part of a longer name too (`api_key=`, `"client_secret":`,
370
+ `X-Api-Key:`, a `<dt>API key</dt>` before the `<dd>`) — and a value that looks generated: `Bearer`
371
+ or `Basic` followed by one, or a long hex or base64 run.
372
+
373
+ **What is left alone matters as much.** A forty-character commit hash is not a secret, and neither is
374
+ a UUID — even after the word "key", because an idempotency key is a UUID. Neither is `key:
375
+ MyComponentHeaderTitle`, `const apiKey = process.env.API_KEY`, `sk-fading-circle` (SpinKit's CSS),
376
+ `Bearer YOUR_TOKEN_HERE`, or ordinary sentences about keys and tokens. A generated value is told
377
+ from a written one by measure, not by guess: random characters mix both cases and digits and seldom
378
+ run three lowercase letters together, and names do the opposite. Run over 300,000 lines of Daybook's
379
+ own front end, docs and backend, the rules found one thing — and it was a key.
380
+
381
+ Text painted into a canvas, an image of text, and the inside of another component's shadow root are
382
+ not read. A blur covers those.
383
+
384
+ ### What the reporter blurs
385
+
386
+ The composer offers **Blur something** beside *Add another pin*, and it is the same gesture: click an
387
+ element, or drag across an area — a corner of a chart, half a table. What a click would blur is shown
388
+ blurred under the pointer first, every blur stays on the page while the report is written, each is
389
+ listed in the panel with its own remove, and Esc backs out.
390
+
391
+ A blur applies to the screenshot exactly as the reporter saw it, and the element is blurred for the
392
+ frame the way a private one is. In the page snapshot the subtree is withheld as
393
+ `<section data-daybook-blurred>[withheld]</section>`; for an area, every element drawn wholly inside
394
+ it and every piece of text drawn under it. A pin on something blurred is sent without its text.
395
+
396
+ Nothing about a blur goes on the wire but a count: no selector, no text. It holds with `redact: false`.
397
+
398
+ ## Offline
399
+
400
+ A report written the moment something breaks is frequently written the moment the network is also
401
+ broken. Failed sends are queued in `localStorage` and retried on the next visit, carrying an
402
+ idempotency key so a retry the server already received returns the original rather than filing a
403
+ duplicate. 4xx responses other than 429 are not retried — a client that retries a rejected body
404
+ forever becomes a denial of service against its own backend.
405
+
406
+ ## Without the UI
407
+
408
+ ```js
409
+ const pm = init({ … })
410
+
411
+ pm.open() // your own "Report a problem" menu item
412
+ await pm.report('Checkout threw', { // a caught error, no user present
413
+ kind: 'bug',
414
+ context: { orderId: '123' },
415
+ })
416
+ ```
417
+
418
+ `report()` takes no screenshot: there is nobody there to consent to a screen share.
419
+
420
+ ## The look is set in Daybook, not in code
421
+
422
+ Everything about the widget's appearance lives on the integration, so it is changed on the Feedback
423
+ widget page in Daybook and takes effect on every install of that key without a deploy:
424
+
425
+ | | |
426
+ |---|---|
427
+ | Button style | `pill`, `pill-icon`, `icon`, `text`, `outline` |
428
+ | Button text | Anything up to 24 characters. Defaults to "Feedback" |
429
+ | Colour scheme | `auto` (the default), `light`, `dark` |
430
+ | Corner | Bottom right by default — and `placement` in `init()` overrides it |
431
+ | Accent | Any CSS colour |
432
+
433
+ **Auto is the default and is the one to keep.** The widget is a guest on your page, and your page is
434
+ already light or dark for that reader; following their own setting is almost always right. Pin it
435
+ only when your app is one or the other regardless of the system.
436
+
437
+ The five button styles exist because one button cannot be right for every page. A product with its
438
+ own bold chat bubble does not want a second bold pill beside it; a spare documentation site does not
439
+ want a filled button at all; a dense application usually wants the smallest possible mark. All five
440
+ keep the same hit area in the same corner, so nothing else about the widget changes with the choice.
441
+
442
+ If you are building your own settings screen, `previewLauncher(element, theme)` draws the real
443
+ button — the real stylesheet, in a shadow root — so a preview cannot drift from the thing it
444
+ previews.
445
+
446
+ ## Theming, but not styling
447
+
448
+ The widget renders in a shadow root. A host page's `* { }` reset, its `button { all: unset }`, or its
449
+ own stacking context cannot reach in — which matters because the page someone is reporting a problem
450
+ on is exactly the page whose CSS you should not trust.
451
+
452
+ So it is themed from Daybook rather than from your stylesheet: accent colour, corner radius, position
453
+ and launcher label are set on the integration and arrive with the handshake, which means changing
454
+ them needs no redeploy of your site. Anything not on that list is not settable, on purpose.
455
+
456
+ ## Limits
457
+
458
+ Two, and they are different things. A **burst limit** of 60 reports a minute per install stops a
459
+ leaked key becoming a write loop. A **period quota** belongs to the whole Daybook project and is what
460
+ runs out at the end of a month; the integrations screen shows how much of it is spent.
461
+
462
+ Attachments go through the API rather than straight to storage, capped per environment — 8 MB by
463
+ default, which is generous for a screenshot.