@regressionbot/sdk 1.2.3 → 2.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/types.d.ts CHANGED
@@ -9,23 +9,143 @@ export interface ProjectScan {
9
9
  exclude?: string[];
10
10
  };
11
11
  }
12
+ /**
13
+ * Credentials for reaching an origin behind an environment gate — basic auth,
14
+ * a bypass header, or a session cookie. Write-only: the API never returns these,
15
+ * only a `{ configured: true }` presence flag.
16
+ */
17
+ export interface EnvGate {
18
+ basic?: {
19
+ username: string;
20
+ password: string;
21
+ };
22
+ headers?: Record<string, string>;
23
+ cookies?: Array<{
24
+ name: string;
25
+ value: string;
26
+ }>;
27
+ }
28
+ /** How a project's baseline advances between runs. Absent means `approved`. */
29
+ export type BaselinePolicy = 'approved' | 'rolling';
30
+ /** Frequency at which a project runs unattended. */
31
+ export type ProjectSchedule = 'hourly' | 'daily' | 'weekly';
32
+ /**
33
+ * A saved project as the API returns it.
34
+ *
35
+ * This is a read shape. To change a project, pass {@link ProjectConfigUpdate}
36
+ * to updateProject() — the two differ, because gate credentials are written as
37
+ * an {@link EnvGate} but read back only as a presence flag.
38
+ */
12
39
  export interface ProjectConfig {
13
- orgId?: string;
14
40
  name: string;
15
- testOrigin?: string;
41
+ testOrigin: string;
16
42
  baseOrigin?: string;
17
43
  sitemapUrl?: string;
18
44
  paths?: ProjectPath[];
19
45
  scans?: ProjectScan[];
20
- devices?: string[];
46
+ devices: string[];
21
47
  masks?: string[];
48
+ /** CSS injected before screenshotting, to hide dynamic widgets. Max 4096 characters. */
49
+ customCss?: string;
50
+ /** Presence flag only — the stored credential is never returned. */
51
+ testAuth?: {
52
+ configured: true;
53
+ };
54
+ /** Presence flag only — the stored credential is never returned. */
55
+ baseAuth?: {
56
+ configured: true;
57
+ };
58
+ /** Pages captured in parallel, 1–20. Absent means the API's default of 4. */
22
59
  concurrency?: number;
23
- createdAt?: string;
24
- updatedAt?: string;
60
+ /** Extra instructions handed to the model that writes change summaries. Max 1000 characters. */
61
+ aiPromptInstructions?: string;
62
+ /** Diff percentage below which a regression is skipped by the AI pass. Defaults to 0.01. */
63
+ aiSummaryThreshold?: number;
64
+ /**
65
+ * `approved` (default): a person accepts a run and its captures become the baseline.
66
+ * `rolling`: every completed managed run advances it, and those runs auto-approve.
67
+ */
68
+ baselinePolicy?: BaselinePolicy;
69
+ /** Set when the project runs unattended. Absent means it only runs when triggered. */
70
+ schedule?: ProjectSchedule;
71
+ /**
72
+ * The UTC hour, 0–23, at which a `daily` or `weekly` project runs — `3` is 03:00 UTC.
73
+ * Absent means the slot anchors to whenever the first sweep picked the project up.
74
+ */
75
+ scheduleHourUtc?: number;
76
+ /**
77
+ * The API key recorded when the schedule was set; every scheduled run is attributed
78
+ * to it. Absent if the schedule was set without an API key, in which case AI
79
+ * summaries are skipped for those runs.
80
+ */
81
+ scheduleKeyId?: string;
82
+ /** When the scheduler last started a run. The next run is due one interval after this. */
83
+ lastScheduledRunAt?: string;
84
+ createdAt: string;
85
+ updatedAt: string;
25
86
  lastRunAt?: string;
26
87
  lastJobId?: string;
88
+ baselineVersion?: string;
27
89
  baselineInvalidatedAt?: string;
28
90
  }
91
+ /**
92
+ * The fields updateProject() accepts.
93
+ *
94
+ * Changing anything that decides what a capture looks like — testOrigin,
95
+ * baseOrigin, sitemapUrl, paths, scans, devices, masks, customCss, or a gate
96
+ * credential — invalidates the stored baselines, and the next run re-captures
97
+ * them instead of comparing. Everything else leaves baselines alone.
98
+ * Re-sending an identical value is not a change.
99
+ */
100
+ export interface ProjectConfigUpdate {
101
+ testOrigin?: string;
102
+ baseOrigin?: string;
103
+ sitemapUrl?: string;
104
+ paths?: ProjectPath[];
105
+ scans?: ProjectScan[];
106
+ devices?: string[];
107
+ masks?: string[];
108
+ /** Max 4096 characters. */
109
+ customCss?: string;
110
+ /** Credentials for the test origin's environment gate. Pass null to clear. */
111
+ testAuth?: EnvGate | null;
112
+ /** Credentials for the base origin's environment gate. Pass null to clear. */
113
+ baseAuth?: EnvGate | null;
114
+ /**
115
+ * Pages captured in parallel, 1–20. Rejected outside that range. Leave it unset to
116
+ * take the API's default of 4 — the load lands on the site being captured.
117
+ */
118
+ concurrency?: number;
119
+ /** Max 1000 characters. */
120
+ aiPromptInstructions?: string;
121
+ aiSummaryThreshold?: number;
122
+ baselinePolicy?: BaselinePolicy;
123
+ /**
124
+ * Run this project unattended at this frequency. Requires `baselinePolicy: 'rolling'`
125
+ * on a managed project — the API rejects the combination without it, because on the
126
+ * approved policy an unapproved change is re-reported on every subsequent run.
127
+ * Live-vs-live projects store no baseline and are exempt. Pass null to remove.
128
+ *
129
+ * Without `scheduleHourUtc` the first run starts at the next hourly sweep and the
130
+ * cadence anchors to it.
131
+ */
132
+ schedule?: ProjectSchedule | null;
133
+ /**
134
+ * Pin a `daily` or `weekly` schedule to this UTC hour, 0–23 — `3` means 03:00 UTC.
135
+ * The first run waits for the hour too, rather than firing immediately and settling
136
+ * into the hour from the following day. Hours only, because the scheduler sweeps once
137
+ * an hour; UTC only, because RegressionBot has no timezone to convert from.
138
+ *
139
+ * Rejected on an `hourly` schedule, which already runs every hour, and rejected if the
140
+ * project has no schedule to apply it to — either one already set, or one sent in the
141
+ * same update. Clearing the schedule with
142
+ * `schedule: null` clears this too, so re-enabling later cannot resurrect an hour
143
+ * nobody asked for on that run. Pass null to clear it on its own.
144
+ *
145
+ * A missed slot waits for the next one rather than catching up.
146
+ */
147
+ scheduleHourUtc?: number | null;
148
+ }
29
149
  export interface VRConfig {
30
150
  apiKey?: string;
31
151
  apiUrl?: string;
@@ -52,57 +172,197 @@ export declare const Viewports: {
52
172
  readonly height: 667;
53
173
  };
54
174
  };
175
+ export type VerdictDecision = 'intentional' | 'bug' | 'noise' | 'needs_review';
176
+ /** How one labelled region of a diff was judged against the run's stated intent. */
177
+ export interface RegionVerdict {
178
+ decision: VerdictDecision;
179
+ /** 0–1. */
180
+ confidence: number;
181
+ reasoning: string;
182
+ }
183
+ /** The rolled-up verdict for one result, plus the per-region verdicts behind it. */
184
+ export interface ResultVerdict {
185
+ decision: VerdictDecision;
186
+ minConfidence: number;
187
+ avgConfidence: number;
188
+ /** Keyed by region label (A, B, C…). Empty when the verdict came from the text-only pass. */
189
+ regions: Record<string, RegionVerdict>;
190
+ /**
191
+ * What the judgement was made from.
192
+ *
193
+ * `measured` — the exact edits from the document diff were in front of the model.
194
+ * `described` — only a generated sentence about the change was, because the DOM engine
195
+ * could not run on that page. Absent on the vision path, which reads the images.
196
+ *
197
+ * Worth more than the confidence numbers when deciding how much weight to give a
198
+ * verdict: a `described` one was reached without seeing what actually changed.
199
+ */
200
+ basis?: 'measured' | 'described';
201
+ }
202
+ /**
203
+ * The kinds of change the document diff reports.
204
+ *
205
+ * `move` and `move-with-edit` are distinguished because an element that only shifted is
206
+ * usually a knock-on effect, while one that shifted *and* changed is usually the cause.
207
+ * `sticky-reposition` is a move of a positioned element, and `reflow-displacement` is
208
+ * content pushed by a change elsewhere — both are consequences, not edits.
209
+ */
210
+ export type ChangeType = 'text-edit' | 'insert' | 'delete' | 'style-only' | 'image-change' | 'move' | 'move-with-edit' | 'sticky-reposition' | 'reflow-displacement';
211
+ /** One changed CSS property, as `[from, to]`. */
212
+ export type StyleDelta = [from: string, to: string];
213
+ /** A rectangle in the capture, in CSS pixels. See {@link Change.box}. */
214
+ export interface ChangeBox {
215
+ x: number;
216
+ y: number;
217
+ w: number;
218
+ h: number;
219
+ }
220
+ /**
221
+ * One change on a page, computed by diffing the two documents rather than described by a
222
+ * model. This is the exact answer to "what changed" — read it before the prose summary.
223
+ */
224
+ export interface Change {
225
+ type: ChangeType;
226
+ /**
227
+ * Tag name only, lowercase, e.g. `div` — not a CSS selector and not unique on the page.
228
+ * For something you can query with, see `PageResult.elementsChanged`.
229
+ */
230
+ element: string;
231
+ /** The text before the edit. Absent on an insert. */
232
+ before?: string;
233
+ /** The text after the edit. Absent on a delete. */
234
+ after?: string;
235
+ /** Changed computed styles, keyed by CSS property name. */
236
+ style?: Record<string, StyleDelta>;
237
+ /**
238
+ * Where it sits in the current capture.
239
+ *
240
+ * CSS pixels, which equal image pixels here because captures pin `deviceScaleFactor`
241
+ * to 1, and measured from the top-left of the **full-page** capture rather than the
242
+ * viewport — so it indexes straight into `currentUrl` with no scroll offset to add.
243
+ *
244
+ * Absent on a delete, and absent whenever the element's position cannot be trusted:
245
+ * an out-of-flow element reports a viewport-relative rect that would point at empty
246
+ * space in a full-page image, so the box is omitted rather than sent wrong.
247
+ */
248
+ box?: ChangeBox;
249
+ /**
250
+ * Where it was in the baseline, in the same coordinate space, present only when it
251
+ * differs from `box` in position or size. Subtract for the move vector
252
+ * (`box.x - boxBefore.x`); compare `w`/`h` for a resize.
253
+ */
254
+ boxBefore?: ChangeBox;
255
+ }
55
256
  export interface RegressionbotSummaryItem {
257
+ /** Region letter (A, B, C…), or an empty string for a whole-page change. */
56
258
  label: string;
259
+ /** Single-sentence description of what changed in that region. */
57
260
  text: string;
261
+ verdict?: RegionVerdict;
58
262
  }
59
263
  /**
60
264
  * Result for a single URL + device comparison.
61
265
  *
62
- * Returned by both getStatus() and getSummary(). Pre-signed image URLs
63
- * (baselineUrl, currentUrl, diffUrl) are only populated by getSummary() —
64
- * they are absent when reading results from getStatus().
266
+ * Returned by getStatus() and, split across `regressions`/`matches`, by
267
+ * getSummary(). Both endpoints pre-sign the image URLs; a URL is null when
268
+ * that image does not exist for this result (no baseline yet, no diff, …).
65
269
  */
66
270
  export interface PageResult {
67
271
  url: string;
68
- /** Device variant tested (e.g. "desktop_chrome", "iphone_12"). */
272
+ /** Whether the capture and comparison succeeded. */
273
+ status: 'SUCCESS' | 'ERROR';
274
+ /** Device variant tested (e.g. "Desktop Chrome", "iPhone 12"). */
69
275
  variantName: string;
70
- /** Percentage of pixels that differed from the baseline (0 = identical). */
276
+ /**
277
+ * Whether this page is considered changed. Read this rather than deriving it from
278
+ * `diffPercentage` — it is the same rule the API uses to split `regressions` from
279
+ * `matches`, and a text edit that moved no pixels is changed at 0.00%.
280
+ *
281
+ * Required, not optional: both endpoints compute it on every result rather than
282
+ * copying it from storage, so it cannot be missing from a response. The SDK targets
283
+ * the hosted API at api.regressionbot.com, so there is no older deployment that
284
+ * could omit it.
285
+ */
286
+ changed: boolean;
287
+ /**
288
+ * Set when the document diff found a content change. Present only when true, and the
289
+ * reason a page can be `changed` at a `diffPercentage` of 0.
290
+ */
291
+ contentChanged?: true;
292
+ /**
293
+ * Percentage of pixels that differed from the baseline. Not a change test on its own:
294
+ * 0 does not mean identical — see `changed`.
295
+ */
71
296
  diffPercentage: number;
72
- /** Raw count of differing pixels. */
73
- diffCount: number;
74
297
  /** Perceptual similarity 0-100 (SSIM). */
75
298
  visualMatchScore: number;
299
+ /** True when this capture became a baseline because none existed to compare against. */
300
+ isNewBaseline: boolean;
301
+ /** Why the capture or comparison failed. Present when status is ERROR. */
302
+ errorMessage?: string;
76
303
  /** Plain-English description of what visually changed, generated by RegressionBot. */
77
304
  regressionbotSummary?: RegressionbotSummaryItem[];
305
+ /**
306
+ * Whether the change was judged intentional, a bug, or noise. Only produced when
307
+ * the run carried a {@link RunContext}, and only once summaryStatus is COMPLETE.
308
+ */
309
+ verdict?: ResultVerdict;
310
+ /**
311
+ * The exact edits the engine computed from the two documents — element, text before,
312
+ * text after, changed styles. Absent when the DOM comparison could not run on the page,
313
+ * which is not the same as nothing having changed.
314
+ *
315
+ * Prefer this over `regressionbotSummary`: it is measured rather than described, so it
316
+ * carries no confidence and can be quoted directly.
317
+ *
318
+ * Truncated on a busy page: at most 40 changes, and fewer if they would exceed the
319
+ * API's 8 KB budget for this field. Treat the list as the most significant changes,
320
+ * not necessarily all of them.
321
+ */
322
+ changes?: Change[];
323
+ /** Selectors of the elements that changed, when the DOM comparison could identify them. */
324
+ elementsChanged?: string[];
325
+ /**
326
+ * Set when the DOM comparison could not run. The result is a plain pixel diff with
327
+ * no semantic change types, so treat its classifications as absent rather than as
328
+ * "nothing structural changed".
329
+ */
330
+ domAssistSkipReason?: string;
78
331
  /** Pre-signed URL for the stored baseline screenshot. */
79
- baselineUrl?: string;
332
+ baselineUrl: string | null;
80
333
  /** Pre-signed URL for the newly captured screenshot. */
81
- currentUrl?: string;
334
+ currentUrl: string | null;
82
335
  /** Pre-signed URL for the side-by-side annotated diff image. */
83
- diffUrl?: string;
336
+ diffUrl: string | null;
84
337
  }
85
338
  export interface JobProgress {
86
339
  total: number;
87
340
  completed: number;
88
341
  percent: string;
89
342
  }
343
+ /** Progress of the asynchronous AI summary pass. */
344
+ export type SummaryStatus = 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'FAILED';
90
345
  export interface JobStatus {
91
346
  jobId: string;
92
347
  status: 'INITIALIZING' | 'PROCESSING' | 'FINISHING' | 'SUMMARIZING' | 'COMPLETED' | 'APPROVED' | 'FAILED';
93
- summaryStatus?: 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'NONE';
94
- error?: string;
95
- progress?: JobProgress;
96
- executionTime?: number;
97
- createdAt?: string;
98
- /** Partial or complete results. Present once workers start completing. Pre-signed image URLs are not included — call getSummary() for those. */
99
- results?: PageResult[];
348
+ /**
349
+ * PENDING means not yet started, COMPLETE that regressionbotSummary is populated
350
+ * (or that nothing needed one). Poll until COMPLETE before reading summaries.
351
+ */
352
+ summaryStatus: SummaryStatus;
353
+ error: string | null;
354
+ progress: JobProgress;
355
+ executionTime: number;
356
+ createdAt: string;
357
+ /** Partial or complete results. Fills in as workers finish. */
358
+ results: PageResult[];
100
359
  }
101
360
  export interface JobSummary {
102
361
  jobId: string;
103
- status: string;
104
- summaryStatus?: 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'NONE';
105
- error?: string | null;
362
+ /** getSummary() throws until the job reaches one of these. */
363
+ status: 'COMPLETED' | 'APPROVED' | 'FAILED';
364
+ summaryStatus: SummaryStatus;
365
+ error: string | null;
106
366
  totalUrls: number;
107
367
  completedCount: number;
108
368
  /** Overall quality score 0–100 across all tested pages. */
@@ -112,9 +372,9 @@ export interface JobSummary {
112
372
  matchCount: number;
113
373
  newBaselineCount: number;
114
374
  errorCount: number;
115
- /** Pages where a visual regression was detected. Includes pre-signed image URLs. */
375
+ /** Pages where a visual regression was detected. */
116
376
  regressions: PageResult[];
117
- /** Pages that matched the baseline. Includes pre-signed image URLs. */
377
+ /** Pages that matched the baseline. */
118
378
  matches: PageResult[];
119
379
  /** Pages captured for the first time — no baseline existed to compare against. */
120
380
  newBaselines: Array<{
@@ -127,6 +387,49 @@ export interface JobSummary {
127
387
  variantName: string;
128
388
  errorMessage: string;
129
389
  }>;
390
+ /** Whole-job roll-up of how the changes line up with the run's stated intent. */
391
+ intentAssessment: IntentAssessment;
392
+ /** The intent this run was given, echoed back. */
393
+ runContext?: RunContext;
394
+ }
395
+ /**
396
+ * What a run is testing. Supplying it lets RegressionBot judge each change as
397
+ * intentional, a bug, or noise, rather than just reporting that pixels moved.
398
+ */
399
+ export interface RunContext {
400
+ /** Short description of what this run is testing. */
401
+ changeDescription?: string;
402
+ gitCommitSha?: string;
403
+ /** Git commit subject line. */
404
+ gitCommitMessage?: string;
405
+ prTitle?: string;
406
+ /** Markdown. Truncated to 2000 characters by the API. */
407
+ prDescription?: string;
408
+ /** Explicit list of expected visual changes. */
409
+ expectedChanges?: string[];
410
+ /** Files or component names changed. */
411
+ scope?: string[];
412
+ }
413
+ export interface IntentAssessment {
414
+ /** False when the run carried no RunContext, in which case the counts are all zero. */
415
+ intentProvided: boolean;
416
+ bugCount: number;
417
+ intentionalCount: number;
418
+ noiseCount: number;
419
+ needsReviewCount: number;
420
+ /** True when every regression is accounted for by the stated intent. */
421
+ allAccountedFor: boolean;
422
+ /** One line summarising the job, safe to print straight into CI output. */
423
+ summary: string;
424
+ }
425
+ export interface ApproveResult {
426
+ message: string;
427
+ jobId: string;
428
+ approvedUrlsCount: number;
429
+ /** Present when some captures could not be promoted. */
430
+ failedCount?: number;
431
+ /** Pages skipped because another job updated their baseline first. */
432
+ conflictedUrls?: string[];
130
433
  }
131
434
  export interface JobAiSummary {
132
435
  message: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@regressionbot/sdk",
3
- "version": "1.2.3",
3
+ "version": "2.1.0",
4
4
  "description": "The official SDK for regressionbot.com - the simplest way to automate visual regression testing.",
5
5
  "homepage": "https://regressionbot.com",
6
6
  "repository": {