@regressionbot/sdk 2.2.1 → 2.4.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
@@ -25,7 +25,7 @@ Unlike traditional visual diffing libraries, RegressionBot is designed for moder
25
25
  - **Auto-Discovery**: Scan sitemaps with glob patterns and limits.
26
26
  - **RegressionBot Summaries**: Plain-English change descriptions for every regression, generated on-demand via the API.
27
27
  - **Intent-Aware Verdicts**: Describe what a run is meant to change, and every regression comes back judged as intentional, a bug, or noise.
28
- - **Scheduled Checks**: Run a saved project unattended, hourly, daily, or weekly — and at a set UTC hour.
28
+ - **Scheduled Checks**: Run a saved project unattended, daily or weekly — and at a set UTC hour.
29
29
  - **Project-Based Baselines**: Save and reuse test configurations; share visual history across environments.
30
30
  - **Auto-Approval**: Automatically promote screenshots to baselines on jobs that pass your criteria.
31
31
  - **Zero Infrastructure**: No browser maintenance or server provisioning — RegressionBot handles it all.
@@ -74,6 +74,56 @@ the builder, intent-aware verdicts, environment gates, baseline policies, and
74
74
  scheduling. `scheduleHourUtc` needs API 2.7.0 or later — on an older API the
75
75
  field is accepted and ignored, and the schedule stays anchored to its first run.
76
76
 
77
+ ### 2.4.0
78
+
79
+ Needs API 2.9.0 or later. On an older API the new fields are simply absent.
80
+
81
+ - **`'hourly'` is gone from `ProjectSchedule`.** The API stopped accepting it on
82
+ 2026-08-20 and rejects it outright, so code that sends it already fails at runtime;
83
+ now it fails at compile time instead. Use `'daily'` (with `scheduleHourUtc`) or
84
+ `'weekly'`. Kept as a minor release because no working call can depend on it.
85
+ - **Environment labels.** `environment` and `baseEnvironment` on a project
86
+ (`updateProject`, `getProject`) and on each run's status and summary, so a run reads
87
+ "staging vs production" instead of a bare URL. A label only: never resets baselines.
88
+ - **A standing `intent` on a project**, which scheduled runs are judged against.
89
+ - **`runSummary`** on the job summary: a short AI reading of the whole run.
90
+ - **`changeGroup`** on each regression (`structural`, `edited`, `metadata`,
91
+ `cosmetic`), the same grouping the digest email uses.
92
+ - **New change detail:** `attribute-edit` and `font-failed` change types, and `label`,
93
+ `attributes` and `valueOnly` on a change.
94
+ - **`project`, `origin`, `baseOrigin`, `totalUrls` and `completedCount`** on the job status.
95
+ - **Deprecated:** `visualMatchScore`, `overallScore`, `domAssistSkipReason`,
96
+ `elementsChanged` and a summary item's `verdict`. All still typed; none measure what
97
+ their names say under the DOM engine.
98
+
99
+ ### 2.3.0
100
+
101
+ Needs API 2.9.0 or later. On an older API the verdict fields are simply absent, with
102
+ one exception called out below.
103
+
104
+ - **`RESOLVED` is a terminal status, and `waitForCompletion` now stops on it.** A run
105
+ reaches `APPROVED` only when every page carrying a diff was approved; decide them all
106
+ and reject one and it lands on `RESOLVED` instead. The old terminal check knew
107
+ `COMPLETED` and `APPROVED` only, so a triaged run with a single rejection polled until
108
+ the caller gave up. API 2.9.0 made that the common way such a run ends.
109
+ - **`approvePage(url, variantName, note?)` and `rejectPage(...)`** decide one page and
110
+ leave the rest of the job alone. The optional `note` records what the verdict missed,
111
+ and is worth sending when you are overruling it. Both refuse a url without a
112
+ `variantName`: the API gates its per-page path on having both, and a half-identified
113
+ page falls through to approving the whole job.
114
+ - **`approve(where)` throws if it reaches an API that does not support the filter.**
115
+ This is the exception. An older API reads `jobId`, ignores the rest of the body, and
116
+ approves EVERY page — including the ones the verdict called bugs — while answering
117
+ like a success. `skippedUrlsCount` is the tell: the filter path always reports it,
118
+ even as 0, and no other path reports it at all. The error says plainly that the
119
+ baselines have already moved, because by then they have.
120
+ - **Verdict and triage fields typed.** On a regression: `basis`, `coveredBy`,
121
+ `reasoning` and a deprecated `judgedAt`. On a page a person decided: `triageStatus`,
122
+ `triagedAt`, `triagedBy`, `triagedVerdict` and `triageNote`. On the job:
123
+ `intentAssessment.decision` and `intentProvided`.
124
+ - **`comparisonMode`** on the job status says whether the run compared two live origins
125
+ or one origin against a stored baseline.
126
+
77
127
  ### 2.2.1
78
128
 
79
129
  - **A builder run with no `check()` or `scan()` no longer invents a home path.** It
@@ -262,6 +312,16 @@ Two things to know before you rely on it:
262
312
  - **`changes` absent is not "nothing changed".** It means the document comparison could not
263
313
  run on that page — check `domAssistSkipReason`.
264
314
 
315
+ Each change also carries a `type` beyond the ones above — `attribute-edit` for a reader-facing
316
+ attribute (`href`, `alt`, `aria-label`, …; see `c.attributes`) and `font-failed` for a web font
317
+ that didn't load. A change with no words of its own (`style-only`, `attribute-edit`,
318
+ `image-change`) may carry a short `label` naming the element instead, and a date-only edit
319
+ ("Sep 17" → "Sep 23") is reported with `valueOnly: 'date'` without counting as a change.
320
+
321
+ Every regression also carries a `changeGroup` — `structural`, `edited`, `metadata`,
322
+ `cosmetic`, or (on older results) `unmeasured`/`date` — the same grouping the digest email
323
+ uses, so you can filter a run down to one kind of change without re-deriving the rule.
324
+
265
325
  `box` gives you the location in the capture, in CSS pixels from the top-left of the
266
326
  full-page image, so it indexes straight into `currentUrl` if you want to crop:
267
327
 
@@ -309,7 +369,6 @@ intent-aware too:
309
369
 
310
370
  ```typescript
311
371
  const job = await rb.runProject('marketing-site-v2', {
312
- testOrigin: process.env.VERCEL_PREVIEW_URL,
313
372
  runContext: { changeDescription: 'Restyle the pricing table' },
314
373
  });
315
374
  ```
@@ -333,7 +392,11 @@ const job = await rb
333
392
 
334
393
  ### Progress Tracking
335
394
 
336
- Pass a callback to `waitForCompletion` to receive status updates while the job runs:
395
+ `waitForCompletion` returns on `COMPLETED`, `APPROVED` or `RESOLVED`, and throws on
396
+ `FAILED`. `APPROVED` means every page carrying a diff was approved; `RESOLVED` means
397
+ they were all decided and at least one was rejected.
398
+
399
+ Pass a callback to receive status updates while the job runs:
337
400
 
338
401
  ```typescript
339
402
  const status = await job.waitForCompletion(3000, (s) => {
@@ -361,6 +424,34 @@ const result = await job.approve();
361
424
  console.log(`Approved ${result.approvedUrlsCount} URLs.`);
362
425
  ```
363
426
 
427
+ When the run carried an intent (`.withContext()`), approve only the pages the
428
+ verdict cleared and leave the flagged ones for a person:
429
+
430
+ ```typescript
431
+ const summary = await job.getSummary();
432
+ if (summary.intentAssessment.decision !== 'pass') {
433
+ const result = await job.approve({ decision: ['intentional', 'noise'] });
434
+ console.log(`Approved ${result.approvedUrlsCount}, ${result.skippedUrlsCount} left for review.`);
435
+ }
436
+ ```
437
+
438
+ `intentAssessment.decision` is `pass`, `review`, `fail`, or `not_judged` when the
439
+ run carried no intent. Each regression's `verdict` carries `reasoning`, `basis`
440
+ (`measured` or `described`) and, for `intentional`, the words of the intent it
441
+ `coveredBy`. Both need API 2.9.0 or later.
442
+
443
+ To decide one page at a time, name the page and the device:
444
+
445
+ ```typescript
446
+ await job.rejectPage('https://example.com/pricing', 'Desktop Chrome', 'the nav lost a link');
447
+ await job.approvePage('https://example.com/pricing', 'iPhone 12');
448
+ ```
449
+
450
+ The third argument is a note, and it is worth sending when you are overruling the
451
+ verdict — approving a page it called a bug, or rejecting one it cleared. What you
452
+ write is stored on that page as `triageNote`, beside `triageStatus`, `triagedAt`,
453
+ `triagedBy` and the `triagedVerdict` you overruled.
454
+
364
455
  ### Saved Projects
365
456
 
366
457
  Projects let you save a test configuration in the RegressionBot dashboard and trigger runs against it without re-specifying every option.
@@ -374,10 +465,10 @@ console.log(projects.map(p => p.name));
374
465
  const project = await rb.getProject('marketing-site-v2');
375
466
  console.log(project);
376
467
 
377
- // Trigger a run from a saved project, optionally overriding fields
378
- const job = await rb.runProject('marketing-site-v2', {
379
- testOrigin: process.env.VERCEL_PREVIEW_URL,
380
- });
468
+ // Trigger a run from a saved project. Any capture field you pass is checked
469
+ // against the saved config and rejected if it differs; leave it out to use
470
+ // the saved value. Change the config with updateProject().
471
+ const job = await rb.runProject('marketing-site-v2');
381
472
 
382
473
  const status = await job.waitForCompletion();
383
474
  const summary = await job.getSummary();
@@ -418,7 +509,7 @@ combination. Live-vs-live projects store no baseline and are exempt.
418
509
  // Turn on a daily unattended check
419
510
  await rb.updateProject('marketing-site-v2', {
420
511
  baselinePolicy: 'rolling',
421
- schedule: 'daily', // 'hourly' | 'daily' | 'weekly'
512
+ schedule: 'daily', // 'daily' | 'weekly'
422
513
  });
423
514
 
424
515
  // Or pin it to a UTC hour — this one runs at 03:00 UTC every day
@@ -438,15 +529,44 @@ console.log(project.schedule, project.scheduleHourUtc, project.lastScheduledRunA
438
529
 
439
530
  Without `scheduleHourUtc` the first run starts at the next hourly sweep and the cadence
440
531
  anchors to it. With it, the first run waits for that hour as well. Hours only, since the
441
- scheduler sweeps once an hour, and UTC only. It is rejected on an `hourly` schedule, and
442
- rejected on a project with no schedule to apply it to. Clearing the schedule clears the
443
- hour with it, and a missed slot waits for the next one rather than catching up.
532
+ scheduler sweeps once an hour, and UTC only. It is rejected on a project with no schedule
533
+ to apply it to. Clearing the schedule clears the hour with it, and a missed slot waits
534
+ for the next one rather than catching up.
444
535
 
445
536
  Setting a schedule, its hour, or a baseline policy does **not** invalidate
446
537
  baselines — only changes that affect what a capture looks like (`testOrigin`,
447
538
  `baseOrigin`, `sitemapUrl`, `paths`, `scans`, `devices`, `masks`, `customCss`) do that.
448
539
  Billing is per comparison, so cost scales with frequency.
449
540
 
541
+ A scheduled run has no PR or commit to draw an intent from, so give the project a standing
542
+ `intent` instead — every scheduled run is judged against it:
543
+
544
+ ```typescript
545
+ await rb.updateProject('marketing-site-v2', {
546
+ intent: 'Content is edited in the CMS daily; navigation, pricing and layout must not change.',
547
+ });
548
+ ```
549
+
550
+ Without one, a scheduled run's `intentAssessment.decision` reads `not_judged`. Runs started
551
+ by a caller keep their own `runContext` and are never judged against the project's `intent`.
552
+ Pass `null` or an empty string to remove it. Does not invalidate baselines.
553
+
554
+ ### Environment Labels
555
+
556
+ Label which environment a project's origins are — `environment` for `testOrigin`,
557
+ `baseEnvironment` for `baseOrigin` on a live-vs-live project — so runs, emails and the
558
+ dashboard read "staging vs production" instead of a bare URL:
559
+
560
+ ```typescript
561
+ await rb.updateProject('marketing-site-v2', { environment: 'staging' });
562
+
563
+ const project = await rb.getProject('marketing-site-v2');
564
+ console.log(project.environment); // 'staging'
565
+ ```
566
+
567
+ A label only: 1–24 letters, digits, spaces or hyphens, stored lower-case. It never resets
568
+ baselines and never changes a run. Pass `null` or an empty string to remove it.
569
+
450
570
  ### Reconnecting to an Existing Job
451
571
 
452
572
  If you have a job ID from a previous run (e.g., stored in CI state), you can attach to it without re-running the test:
@@ -534,6 +654,17 @@ Promote the current screenshots of a job to be the new baselines.
534
654
  npx @regressionbot/sdk approve <jobId>
535
655
  ```
536
656
 
657
+ When the run carried an intent, `--decision` approves only the pages whose verdict is in
658
+ the list and leaves the rest pending:
659
+ ```bash
660
+ npx @regressionbot/sdk approve <jobId> --decision intentional,noise
661
+ ```
662
+
663
+ It prints how many changed pages were left for a person. Treat a number above zero as a
664
+ build that is not done: those are the pages the verdict did not clear, plus any it never
665
+ assessed. An unknown value stops the command rather than being sent, because an API that
666
+ does not understand the filter approves the whole job instead.
667
+
537
668
  ## Examples & Integrations
538
669
 
539
670
  Check out the [examples/](./examples/) directory for real-world integration guides:
package/dist/cli.d.ts CHANGED
@@ -1,8 +1,16 @@
1
1
  #!/usr/bin/env node
2
- import { PageResult, RunContext } from './types';
2
+ import { PageResult, RunContext, VerdictDecision } from './types';
3
3
  declare function printRegression(r: PageResult): void;
4
4
  type FailOn = 'any' | 'unintended';
5
5
  declare function parseFailOn(raw: unknown): FailOn;
6
+ /**
7
+ * `--decision intentional,noise` -> the approve filter, or undefined for no filter.
8
+ *
9
+ * Validated here rather than at the API, because the failure is asymmetric: a typo the API
10
+ * rejects costs a round trip, but a typo that reached a filter-blind API would approve the
11
+ * whole job. Unknown values stop the command.
12
+ */
13
+ declare function parseDecisions(raw: unknown): VerdictDecision[] | undefined;
6
14
  /**
7
15
  * Whether one regression should fail the build under `--fail-on unintended`.
8
16
  *
@@ -25,4 +33,4 @@ declare function selectBlocking(regressions: PageResult[], failOn: FailOn): {
25
33
  };
26
34
  declare function buildRunContext(options: any): RunContext | undefined;
27
35
  declare function parseArgs(args: string[]): any;
28
- export { parseArgs, parseFailOn, isBlocking, selectBlocking, buildRunContext, printRegression };
36
+ export { parseArgs, parseFailOn, parseDecisions, isBlocking, selectBlocking, buildRunContext, printRegression };
package/dist/cli.js CHANGED
@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
36
36
  Object.defineProperty(exports, "__esModule", { value: true });
37
37
  exports.parseArgs = parseArgs;
38
38
  exports.parseFailOn = parseFailOn;
39
+ exports.parseDecisions = parseDecisions;
39
40
  exports.isBlocking = isBlocking;
40
41
  exports.selectBlocking = selectBlocking;
41
42
  exports.buildRunContext = buildRunContext;
@@ -52,6 +53,8 @@ function formatSummary(items) {
52
53
  }
53
54
  function printRegression(r) {
54
55
  console.log(`- ${r.url} [${r.variantName}] (Score: ${r.visualMatchScore.toFixed(2)})`);
56
+ if (r.changeGroup)
57
+ console.log(` Group: ${r.changeGroup}`);
55
58
  if (r.diffUrl)
56
59
  console.log(` Diff: ${r.diffUrl}`);
57
60
  if (r.verdict) {
@@ -83,6 +86,27 @@ function parseFailOn(raw) {
83
86
  return raw;
84
87
  throw new UsageError("--fail-on takes 'any' or 'unintended'.");
85
88
  }
89
+ const DECISIONS = ['intentional', 'bug', 'noise', 'needs_review'];
90
+ /**
91
+ * `--decision intentional,noise` -> the approve filter, or undefined for no filter.
92
+ *
93
+ * Validated here rather than at the API, because the failure is asymmetric: a typo the API
94
+ * rejects costs a round trip, but a typo that reached a filter-blind API would approve the
95
+ * whole job. Unknown values stop the command.
96
+ */
97
+ function parseDecisions(raw) {
98
+ if (raw === undefined)
99
+ return undefined;
100
+ if (typeof raw !== 'string' || !raw.trim()) {
101
+ throw new UsageError(`--decision takes a comma-separated list of: ${DECISIONS.join(', ')}.`);
102
+ }
103
+ const wanted = raw.split(',').map(d => d.trim()).filter(Boolean);
104
+ const bad = wanted.filter(d => !DECISIONS.includes(d));
105
+ if (bad.length > 0) {
106
+ throw new UsageError(`--decision does not take ${bad.join(', ')}. Use: ${DECISIONS.join(', ')}.`);
107
+ }
108
+ return wanted;
109
+ }
86
110
  /**
87
111
  * Whether one regression should fail the build under `--fail-on unintended`.
88
112
  *
@@ -185,7 +209,7 @@ async function main() {
185
209
  else if (command === 'approve') {
186
210
  if (!param)
187
211
  throw new Error('Job ID is required for approve command.');
188
- await approveJob(param);
212
+ await approveJob(param, parseDecisions(argv['decision']));
189
213
  }
190
214
  else if (command.startsWith('http')) {
191
215
  // Implicit test command
@@ -214,6 +238,8 @@ Usage:
214
238
  Use --download to save the diff image locally.
215
239
  Use --download-full to save baseline and current images too.
216
240
  npx regressionbot approve <jobId> Approve a job's results as new baselines.
241
+ Use --decision to approve only what the verdict
242
+ cleared, e.g. --decision intentional,noise.
217
243
 
218
244
  Options for <url>:
219
245
  --project <id> Required project ID.
@@ -406,11 +432,25 @@ Errors: ${summary.errorCount}
406
432
  });
407
433
  }
408
434
  }
409
- async function approveJob(jobId) {
410
- console.log(`Approving baselines for job: ${jobId}...`);
435
+ async function approveJob(jobId, decision) {
411
436
  const job = sdk.job(jobId);
412
- const res = await job.approve();
437
+ if (!decision) {
438
+ console.log(`Approving every page in job: ${jobId}...`);
439
+ const res = await job.approve();
440
+ console.log(`Success! ${res.message}`);
441
+ return;
442
+ }
443
+ console.log(`Approving pages the verdict called ${decision.join(' or ')} in job: ${jobId}...`);
444
+ const res = await job.approve({ decision });
413
445
  console.log(`Success! ${res.message}`);
446
+ // Left pending on purpose, and the reason a CI step should not go green here: these are
447
+ // the changed pages the verdict did not clear, plus any it never assessed.
448
+ if (res.skippedUrlsCount) {
449
+ console.log(`${res.skippedUrlsCount} changed page(s) left for a person to decide.`);
450
+ }
451
+ if (res.conflictedUrls?.length) {
452
+ console.log(`${res.conflictedUrls.length} page(s) skipped: another job moved their baseline first.`);
453
+ }
414
454
  }
415
455
  // Only run when invoked as a command, so the pure helpers below can be imported and
416
456
  // tested without the CLI executing on require.
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { VRConfig, Viewport, Viewports, JobStatus, JobSummary, JobProgress, PageResult, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, Change, ChangeType, StyleDelta, ChangeBox } from './types';
1
+ import { VRConfig, Viewport, Viewports, JobStatus, JobSummary, JobProgress, PageResult, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, ApproveWhere, Change, ChangeType, StyleDelta, ChangeBox } from './types';
2
2
  import { sanitizeFilename, sanitizeUrlToPath } from './security';
3
3
  export { sanitizeFilename, sanitizeUrlToPath, Viewports };
4
- export type { PageResult, JobProgress, JobStatus, JobSummary, Viewport, VRConfig, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, Change, ChangeType, StyleDelta, ChangeBox };
4
+ export type { PageResult, JobProgress, JobStatus, JobSummary, Viewport, VRConfig, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, ApproveWhere, Change, ChangeType, StyleDelta, ChangeBox };
5
5
  export declare class RegressionBot {
6
6
  private apiKey;
7
7
  private apiUrl;
@@ -24,6 +24,10 @@ export declare class RegressionBot {
24
24
  listProjects(): Promise<ProjectConfig[]>;
25
25
  /**
26
26
  * Trigger a new job run using a saved project configuration.
27
+ *
28
+ * Capture fields passed here are not overrides: the API compares each one to the
29
+ * saved config and rejects the run if it differs. Omit a field to use the saved
30
+ * value; change the saved value with updateProject().
27
31
  */
28
32
  runProject(projectName: string, options?: {
29
33
  testOrigin?: string;
@@ -108,7 +112,22 @@ export declare class JobHandle {
108
112
  constructor(sdk: RegressionBot, jobId: string);
109
113
  getStatus(): Promise<JobStatus>;
110
114
  getSummary(): Promise<JobSummary>;
111
- approve(): Promise<ApproveResult>;
115
+ /**
116
+ * Promote this job's captures to baselines. Pass `where` to approve only the pages whose
117
+ * verdict is in the list — `{ decision: ['intentional', 'noise'] }` approves what the verdict
118
+ * cleared and leaves the flagged pages for a person.
119
+ */
120
+ approve(where?: ApproveWhere): Promise<ApproveResult>;
121
+ /**
122
+ * Approve one page's capture, leaving the rest of the job alone.
123
+ *
124
+ * `note` records what the verdict missed, and is worth sending when you are overruling it —
125
+ * approving a page it called a bug, or rejecting one it cleared.
126
+ */
127
+ approvePage(url: string, variantName: string, note?: string): Promise<ApproveResult>;
128
+ /** Reject one page, leaving its baseline where it is. See `approvePage` for `note`. */
129
+ rejectPage(url: string, variantName: string, note?: string): Promise<ApproveResult>;
130
+ private decidePage;
112
131
  /**
113
132
  * Generate AI summaries on-demand for all regressions in a completed job.
114
133
  */
@@ -122,7 +141,7 @@ export declare class JobHandle {
122
141
  baseDir?: string;
123
142
  }): Promise<void>;
124
143
  /**
125
- * Poll until the job reaches a terminal state (COMPLETED, APPROVED, or FAILED).
144
+ * Poll until the job reaches a terminal state (COMPLETED, APPROVED, RESOLVED or FAILED).
126
145
  * @param intervalMs Polling interval in milliseconds. Defaults to 2000.
127
146
  * @param callback Optional callback invoked on each status poll.
128
147
  * @param options.waitForSummaries If true, keeps polling until AI summaries are fully populated before returning.
package/dist/index.js CHANGED
@@ -48,6 +48,10 @@ class RegressionBot {
48
48
  }
49
49
  /**
50
50
  * Trigger a new job run using a saved project configuration.
51
+ *
52
+ * Capture fields passed here are not overrides: the API compares each one to the
53
+ * saved config and rejects the run if it differs. Omit a field to use the saved
54
+ * value; change the saved value with updateProject().
51
55
  */
52
56
  async runProject(projectName, options = {}) {
53
57
  const res = await this._request(`/project/${encodeURIComponent(projectName)}/run`, 'POST', options);
@@ -209,8 +213,58 @@ class JobHandle {
209
213
  async getSummary() {
210
214
  return this.sdk._request(`/job/${encodeURIComponent(this.jobId)}/summary`);
211
215
  }
212
- async approve() {
213
- return this.sdk._request('/approve', 'POST', { jobId: this.jobId });
216
+ /**
217
+ * Promote this job's captures to baselines. Pass `where` to approve only the pages whose
218
+ * verdict is in the list — `{ decision: ['intentional', 'noise'] }` approves what the verdict
219
+ * cleared and leaves the flagged pages for a person.
220
+ */
221
+ async approve(where) {
222
+ const result = await this.sdk._request('/approve', 'POST', {
223
+ jobId: this.jobId,
224
+ ...(where ? { where } : {}),
225
+ });
226
+ // An API that predates the filter reads `jobId` and ignores everything else, so a body
227
+ // it does not understand approves EVERY page — including the ones the verdict called
228
+ // bugs — and answers like a success. The tell is `skippedUrlsCount`: the filter path
229
+ // always reports it, even as 0, and no other path reports it at all.
230
+ //
231
+ // Thrown after the fact because that is when it can be known, and the message has to
232
+ // say so: the baselines have already moved, and someone has to look.
233
+ if (where && result.skippedUrlsCount === undefined) {
234
+ throw new Error('approve(where) reached an API that does not support the filter, so EVERY page in '
235
+ + `job ${this.jobId} was approved and its baselines have already moved. Check the `
236
+ + 'job and re-reject anything that should not have been promoted. Upgrade the API '
237
+ + 'to 2.9.0 or later, or decide the pages one at a time with approvePage and '
238
+ + 'rejectPage.');
239
+ }
240
+ return result;
241
+ }
242
+ /**
243
+ * Approve one page's capture, leaving the rest of the job alone.
244
+ *
245
+ * `note` records what the verdict missed, and is worth sending when you are overruling it —
246
+ * approving a page it called a bug, or rejecting one it cleared.
247
+ */
248
+ async approvePage(url, variantName, note) {
249
+ return this.decidePage('approve', url, variantName, note);
250
+ }
251
+ /** Reject one page, leaving its baseline where it is. See `approvePage` for `note`. */
252
+ async rejectPage(url, variantName, note) {
253
+ return this.decidePage('reject', url, variantName, note);
254
+ }
255
+ async decidePage(action, url, variantName, note) {
256
+ // Both halves are required together: `url` without `variantName` matches nothing, and the
257
+ // API answers that with a whole-job approval rather than an error.
258
+ if (!url || !variantName) {
259
+ throw new Error('approvePage and rejectPage need both a url and a variantName.');
260
+ }
261
+ return this.sdk._request('/approve', 'POST', {
262
+ jobId: this.jobId,
263
+ url,
264
+ variantName,
265
+ action,
266
+ ...(note ? { note } : {}),
267
+ });
214
268
  }
215
269
  /**
216
270
  * Generate AI summaries on-demand for all regressions in a completed job.
@@ -285,7 +339,7 @@ class JobHandle {
285
339
  }
286
340
  }
287
341
  /**
288
- * Poll until the job reaches a terminal state (COMPLETED, APPROVED, or FAILED).
342
+ * Poll until the job reaches a terminal state (COMPLETED, APPROVED, RESOLVED or FAILED).
289
343
  * @param intervalMs Polling interval in milliseconds. Defaults to 2000.
290
344
  * @param callback Optional callback invoked on each status poll.
291
345
  * @param options.waitForSummaries If true, keeps polling until AI summaries are fully populated before returning.
@@ -295,7 +349,10 @@ class JobHandle {
295
349
  const status = await this.getStatus();
296
350
  if (callback)
297
351
  callback(status);
298
- if (status.status === 'COMPLETED' || status.status === 'APPROVED') {
352
+ // RESOLVED is terminal too: every page carrying a diff was decided and at least one
353
+ // was rejected. Omitting it polled until the caller's timeout on any run with a
354
+ // rejection, which this release made the common way a triaged run ends.
355
+ if (status.status === 'COMPLETED' || status.status === 'APPROVED' || status.status === 'RESOLVED') {
299
356
  if (options?.waitForSummaries) {
300
357
  if (status.summaryStatus !== 'PENDING' && status.summaryStatus !== 'PROCESSING') {
301
358
  return status;
package/dist/types.d.ts CHANGED
@@ -28,7 +28,7 @@ export interface EnvGate {
28
28
  /** How a project's baseline advances between runs. Absent means `approved`. */
29
29
  export type BaselinePolicy = 'approved' | 'rolling';
30
30
  /** Frequency at which a project runs unattended. */
31
- export type ProjectSchedule = 'hourly' | 'daily' | 'weekly';
31
+ export type ProjectSchedule = 'daily' | 'weekly';
32
32
  /**
33
33
  * A saved project as the API returns it.
34
34
  *
@@ -81,6 +81,16 @@ export interface ProjectConfig {
81
81
  scheduleKeyId?: string;
82
82
  /** When the scheduler last started a run. The next run is due one interval after this. */
83
83
  lastScheduledRunAt?: string;
84
+ /** The standing intent scheduled runs are judged against. Absent means scheduled runs are not judged. */
85
+ intent?: string;
86
+ /**
87
+ * Which environment `testOrigin` is: "production", "staging", "preview", "development",
88
+ * or the team's own word. A label only, shown in emails, the dashboard and MCP; never
89
+ * resets baselines. Absent when unset.
90
+ */
91
+ environment?: string;
92
+ /** Live-vs-live projects only: which environment `baseOrigin` is. */
93
+ baseEnvironment?: string;
84
94
  createdAt: string;
85
95
  updatedAt: string;
86
96
  lastRunAt?: string;
@@ -136,15 +146,37 @@ export interface ProjectConfigUpdate {
136
146
  * into the hour from the following day. Hours only, because the scheduler sweeps once
137
147
  * an hour; UTC only, because RegressionBot has no timezone to convert from.
138
148
  *
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
149
+ * Rejected if the project has no schedule to apply it to — either one already set, or
150
+ * one sent in the same update. Clearing the schedule with
142
151
  * `schedule: null` clears this too, so re-enabling later cannot resurrect an hour
143
152
  * nobody asked for on that run. Pass null to clear it on its own.
144
153
  *
145
154
  * A missed slot waits for the next one rather than catching up.
146
155
  */
147
156
  scheduleHourUtc?: number | null;
157
+ /**
158
+ * The API key the scheduled runs are attributed to. Ignored when the request itself
159
+ * carries an API key — that key is recorded instead. Required, and checked against the
160
+ * organisation's keys, when a schedule is set by a caller holding no key (the dashboard).
161
+ */
162
+ scheduleKeyId?: string;
163
+ /**
164
+ * A standing intent for scheduled runs, which have no PR to draw one from. Say what the
165
+ * pages are expected to do between checks and what must not change; every scheduled run
166
+ * is judged against it. Without one a scheduled run reports
167
+ * `intentAssessment.decision: 'not_judged'`. Runs started by a caller are never judged
168
+ * against it. Trimmed; pass null or an empty string to remove. Does not invalidate
169
+ * baselines. Max 1000 characters.
170
+ */
171
+ intent?: string | null;
172
+ /**
173
+ * Which environment `testOrigin` is: production, staging, preview, development, or your
174
+ * own word (1-24 letters, digits, spaces, hyphens; stored lower-case). A label only:
175
+ * never resets baselines and never changes a run. Pass null or an empty string to remove.
176
+ */
177
+ environment?: string | null;
178
+ /** Live-vs-live projects only, which environment `baseOrigin` is. Same rules as `environment`. */
179
+ baseEnvironment?: string | null;
148
180
  }
149
181
  export interface VRConfig {
150
182
  apiKey?: string;
@@ -180,12 +212,28 @@ export interface RegionVerdict {
180
212
  confidence: number;
181
213
  reasoning: string;
182
214
  }
183
- /** The rolled-up verdict for one result, plus the per-region verdicts behind it. */
215
+ /**
216
+ * How one page's change measures against the intent the run was given. Present only when the
217
+ * job carried a {@link RunContext}. A verdict is a recommendation: {@link Job.approve} and
218
+ * rejecting remain the only actions that move a baseline.
219
+ */
184
220
  export interface ResultVerdict {
185
221
  decision: VerdictDecision;
222
+ /** The confidence in the decision, 0–1. */
186
223
  minConfidence: number;
224
+ /** One sentence saying why. */
225
+ reasoning?: string;
226
+ /**
227
+ * For `intentional` only: the words of the intent, quoted verbatim, that name this change.
228
+ * An intentional verdict whose quoted words are not in the intent is downgraded to
229
+ * `needs_review` before it is stored.
230
+ */
231
+ coveredBy?: string;
232
+ /** When the decision was made. */
233
+ judgedAt?: string;
234
+ /** @deprecated Equal to `minConfidence`. Kept for older clients. */
187
235
  avgConfidence: number;
188
- /** Keyed by region label (A, B, C…). Empty when the verdict came from the text-only pass. */
236
+ /** @deprecated Always empty. Kept for older clients. */
189
237
  regions: Record<string, RegionVerdict>;
190
238
  /**
191
239
  * What the judgement was made from.
@@ -208,6 +256,10 @@ export interface ResultVerdict {
208
256
  * content pushed by a change elsewhere — both are consequences, not edits.
209
257
  */
210
258
  export type ChangeType = 'text-edit' | 'insert' | 'delete' | 'style-only' | 'image-change' | 'move' | 'move-with-edit' | 'sticky-reposition' | 'reflow-displacement'
259
+ /** A reader-facing attribute changed (a link target, alt text, an aria-label). See `Change.attributes`. */
260
+ | 'attribute-edit'
261
+ /** A web font failed to load for this capture. */
262
+ | 'font-failed'
211
263
  /**
212
264
  * The six metadata types: the page's head or its structured data changed while nothing
213
265
  * visible moved — a title edited, a canonical rewritten, a JSON-LD block dropped. They
@@ -232,8 +284,7 @@ export interface Change {
232
284
  type: ChangeType;
233
285
  /**
234
286
  * Tag name only, lowercase, e.g. `div` — not a CSS selector and not unique on the page.
235
- * For a metadata type, the field that changed instead. For something you can query
236
- * with, see `PageResult.elementsChanged`.
287
+ * For a metadata type, the field that changed instead.
237
288
  */
238
289
  element: string;
239
290
  /**
@@ -246,8 +297,29 @@ export interface Change {
246
297
  before?: string;
247
298
  /** The text after the edit. Absent on a delete. Clipped the same way as `before`. */
248
299
  after?: string;
300
+ /**
301
+ * On a change with no words of its own (`style-only`, `attribute-edit`, `image-change`):
302
+ * what a reader calls the element, its text or an image's alt text, up to 40 characters
303
+ * ("Apply now"). Absent on a large element such as a section, whose text would not name
304
+ * it, and when the page's changes left no room in the field's size budget: a label never
305
+ * displaces a change.
306
+ */
307
+ label?: string;
249
308
  /** Changed computed styles, keyed by CSS property name. */
250
309
  style?: Record<string, StyleDelta>;
310
+ /**
311
+ * On an `attribute-edit`: each changed reader-facing attribute (href, alt, title,
312
+ * aria-label, placeholder, role, type, value) as name to [before, after]. A same-origin
313
+ * link is compared as its path, so a preview's own host is not a change.
314
+ */
315
+ attributes?: Record<string, StyleDelta>;
316
+ /**
317
+ * Present as `"date"` when every changed word belongs to a date or time ("Sep 17" to
318
+ * "Sep 23", "3 hours ago"). The edit is reported but does not count toward the page
319
+ * having changed, so a page can list one and still read unchanged. Numbers, prices and
320
+ * percentages are never labelled this way.
321
+ */
322
+ valueOnly?: 'date';
251
323
  /**
252
324
  * Where it sits in the current capture.
253
325
  *
@@ -282,6 +354,7 @@ export interface RegressionbotSummaryItem {
282
354
  label: string;
283
355
  /** Single-sentence description of what changed in that region. */
284
356
  text: string;
357
+ /** @deprecated Never set on current results. To be removed after 2026-10-28. */
285
358
  verdict?: RegionVerdict;
286
359
  }
287
360
  /**
@@ -319,12 +392,23 @@ export interface PageResult {
319
392
  * page whose baseline predates metadata capture, which is silence rather than "no".
320
393
  */
321
394
  metadataChanged?: true;
395
+ /**
396
+ * Which group this page's change belongs to — `structural`, `edited`, `metadata`,
397
+ * `unmeasured`, `date` or `cosmetic` — so a caller can filter a run to one kind of
398
+ * change without re-deriving the rule. The same value the digest email groups on.
399
+ * Present only on a page that counts as a change. `unmeasured` and `date` occur only
400
+ * on results from before 2026-09-28.
401
+ */
402
+ changeGroup?: 'structural' | 'edited' | 'metadata' | 'unmeasured' | 'date' | 'cosmetic';
322
403
  /**
323
404
  * Percentage of pixels that differed from the baseline. Not a change test on its own:
324
405
  * 0 does not mean identical — see `changed`.
325
406
  */
326
407
  diffPercentage: number;
327
- /** Perceptual similarity 0-100 (SSIM). */
408
+ /**
409
+ * @deprecated Deprecated 2026-09-29. 100 minus `diffPercentage`; it no longer measures
410
+ * how alike two pictures look. Kept for existing callers. Read `changed` and `changes`.
411
+ */
328
412
  visualMatchScore: number;
329
413
  /** True when this capture became a baseline because none existed to compare against. */
330
414
  isNewBaseline: boolean;
@@ -337,6 +421,14 @@ export interface PageResult {
337
421
  * the run carried a {@link RunContext}, and only once summaryStatus is COMPLETE.
338
422
  */
339
423
  verdict?: ResultVerdict;
424
+ /** A person's Approve or Reject on this page, written by {@link Job.approve} or the dashboard. */
425
+ triageStatus?: 'PENDING' | 'APPROVING' | 'APPROVED' | 'REJECTED';
426
+ triagedAt?: string;
427
+ triagedBy?: string;
428
+ /** The verdict's decision at the moment of the click; null when the page had none. */
429
+ triagedVerdict?: VerdictDecision | null;
430
+ /** Optional, from the person, when their action disagreed with the verdict. */
431
+ triageNote?: string;
340
432
  /**
341
433
  * The exact edits the engine computed from the two documents — element, text before,
342
434
  * text after, changed styles. Absent when the DOM comparison could not run on the page,
@@ -350,12 +442,13 @@ export interface PageResult {
350
442
  * not necessarily all of them.
351
443
  */
352
444
  changes?: Change[];
353
- /** Selectors of the elements that changed, when the DOM comparison could identify them. */
445
+ /** @deprecated Dropped 2026-09-28; already never set before that. Use `changes` instead. */
354
446
  elementsChanged?: string[];
355
447
  /**
356
- * Set when the DOM comparison could not run. The result is a plain pixel diff with
357
- * no semantic change types, so treat its classifications as absent rather than as
358
- * "nothing structural changed".
448
+ * @deprecated Only on results from before 2026-09-28, when the pixel engine compared a
449
+ * page without its DOM. To be removed after 2026-10-28, when the last of those expire.
450
+ * The result is a plain pixel diff with no semantic change types, so treat its
451
+ * classifications as absent rather than as "nothing structural changed".
359
452
  */
360
453
  domAssistSkipReason?: string;
361
454
  /** Pre-signed URL for the stored baseline screenshot. */
@@ -381,7 +474,16 @@ export interface JobProgress {
381
474
  export type SummaryStatus = 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'FAILED';
382
475
  export interface JobStatus {
383
476
  jobId: string;
384
- status: 'INITIALIZING' | 'PROCESSING' | 'FINISHING' | 'SUMMARIZING' | 'COMPLETED' | 'APPROVED' | 'FAILED';
477
+ /** The project's environment when the run started. A label only. Absent when the project has none. */
478
+ environment?: string;
479
+ /** Live-vs-live runs only: the environment of the base origin. Absent otherwise. */
480
+ baseEnvironment?: string;
481
+ /**
482
+ * Terminal states are COMPLETED, APPROVED, RESOLVED and FAILED. APPROVED means every page
483
+ * carrying a diff was approved; RESOLVED means they were all decided and at least one was
484
+ * rejected. RESOLVED was missing here, and waitForCompletion polled past it forever.
485
+ */
486
+ status: 'INITIALIZING' | 'PROCESSING' | 'FINISHING' | 'SUMMARIZING' | 'COMPLETED' | 'APPROVED' | 'RESOLVED' | 'FAILED';
385
487
  /**
386
488
  * PENDING means not yet started, COMPLETE that regressionbotSummary is populated
387
489
  * (or that nothing needed one). Poll until COMPLETE before reading summaries.
@@ -389,20 +491,41 @@ export interface JobStatus {
389
491
  summaryStatus: SummaryStatus;
390
492
  error: string | null;
391
493
  progress: JobProgress;
494
+ /** The project whose configuration this run used, when it had one. */
495
+ project?: string;
496
+ /** The origin that was captured as "current". */
497
+ origin?: string;
498
+ /** The second origin, captured as the comparison. Present only in live-vs-live mode. */
499
+ baseOrigin?: string;
392
500
  executionTime: number;
393
501
  createdAt: string;
502
+ /** Whether the run carried an intent. Without one no page gets a verdict. */
503
+ intentProvided?: boolean;
504
+ /** Whether this run compared two live origins or one origin against a stored baseline. */
505
+ comparisonMode?: 'live-vs-live' | 'managed';
506
+ /** Page-checks the run made, and how many finished. Mirrors `progress`. */
507
+ totalUrls?: number;
508
+ completedCount?: number;
394
509
  /** Partial or complete results. Fills in as workers finish. */
395
510
  results: PageResult[];
396
511
  }
397
512
  export interface JobSummary {
398
513
  jobId: string;
514
+ /** The project's environment when the run started. A label only. Absent when the project has none. */
515
+ environment?: string;
516
+ /** Live-vs-live runs only: the environment of the base origin. Absent otherwise. */
517
+ baseEnvironment?: string;
399
518
  /** getSummary() throws until the job reaches one of these. */
400
- status: 'COMPLETED' | 'APPROVED' | 'FAILED';
519
+ status: 'COMPLETED' | 'APPROVED' | 'RESOLVED' | 'FAILED';
401
520
  summaryStatus: SummaryStatus;
402
521
  error: string | null;
403
522
  totalUrls: number;
404
523
  completedCount: number;
405
- /** Overall quality score 0–100 across all tested pages. */
524
+ /**
525
+ * @deprecated Deprecated 2026-09-29. 100 minus the average `diffPercentage` over the
526
+ * job's pages, an errored page counting as 100: not a similarity score. Kept for
527
+ * existing callers. Read `regressionCount` and each regression's `changes`.
528
+ */
406
529
  overallScore: number;
407
530
  executionTime: number;
408
531
  regressionCount: number;
@@ -424,6 +547,13 @@ export interface JobSummary {
424
547
  variantName: string;
425
548
  errorMessage: string;
426
549
  }>;
550
+ /**
551
+ * An AI summary of the whole run, two or three sentences, written once when the run
552
+ * finished from the exact edits in `regressions` (the same text opens the scheduled-run
553
+ * email). Null when nothing changed or none could be written. The changes are the
554
+ * record; this is a reading of them.
555
+ */
556
+ runSummary: string | null;
427
557
  /** Whole-job roll-up of how the changes line up with the run's stated intent. */
428
558
  intentAssessment: IntentAssessment;
429
559
  /** The intent this run was given, echoed back. */
@@ -448,6 +578,12 @@ export interface RunContext {
448
578
  scope?: string[];
449
579
  }
450
580
  export interface IntentAssessment {
581
+ /**
582
+ * The one field a CI step reads. `fail`: a page contradicts the intent. `review`: a page
583
+ * needs a person, or was never assessed. `pass`: every changed page is accounted for.
584
+ * `not_judged`: the run carried no intent, so nothing was assessed.
585
+ */
586
+ decision: 'pass' | 'review' | 'fail' | 'not_judged';
451
587
  /** False when the run carried no RunContext, in which case the counts are all zero. */
452
588
  intentProvided: boolean;
453
589
  bugCount: number;
@@ -459,14 +595,22 @@ export interface IntentAssessment {
459
595
  /** One line summarising the job, safe to print straight into CI output. */
460
596
  summary: string;
461
597
  }
598
+ /** Approve only the pages whose verdict is in the list. A job-level filter. */
599
+ export interface ApproveWhere {
600
+ decision: VerdictDecision[];
601
+ }
462
602
  export interface ApproveResult {
463
603
  message: string;
464
604
  jobId: string;
465
605
  approvedUrlsCount: number;
606
+ /** With `where` only: changed pages left pending because their verdict was outside the list or absent. */
607
+ skippedUrlsCount?: number;
466
608
  /** Present when some captures could not be promoted. */
467
609
  failedCount?: number;
468
610
  /** Pages skipped because another job updated their baseline first. */
469
611
  conflictedUrls?: string[];
612
+ /** One page only: what approvePage or rejectPage wrote on that page's result. */
613
+ triageStatus?: 'APPROVED' | 'REJECTED';
470
614
  }
471
615
  export interface JobAiSummary {
472
616
  message: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@regressionbot/sdk",
3
- "version": "2.2.1",
3
+ "version": "2.4.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": {