@siteqwality/cli 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @siteqwality/cli
 
-Version 0.1.1, Node.js 22+. Install:
+Version 0.1.2, Node.js 22+. Install:
 
 ```sh
 npm install --save-dev @siteqwality/cli
@@ -26,6 +26,26 @@ Store the key in your CI secret store. Mutations require `write:rum`; release li
 
 Authenticated commands accept `--app <uuid>`, `--api-url <url>`, `--retries <count>` (default 2, range 0 to 5), and `--timeout <ms>` (default 30000, maximum 300000). Upload also accepts `--release <version>`, `--commit <sha>`, `--env <environment>`, `--concurrency <count>` (default 4, range 1 to 16), and `--delete-after`. Explicit flags override environment defaults. JSON results go to stdout, errors to stderr with exit code 1. Keys are intentionally not accepted as command-line flags.
 
+## Incidents
+
+Incident commands use an account API key with `read:incidents` for listing and `write:incidents` for changes. They do not need a RUM application or `--app`.
+
+```sh
+export SITEQWALITY_API_KEY='your-incident-api-key'
+npx siteqwality incidents list --status active --limit 50 --offset 0
+npx siteqwality incidents ack "$INCIDENT_ID" --by "$MEMBER_ID"
+npx siteqwality incidents resolve "$INCIDENT_ID" --message 'Service recovered'
+npx siteqwality incidents update "$INCIDENT_ID" --title 'Checkout unavailable' --severity critical
+npx siteqwality incidents update "$INCIDENT_ID" --service "$SERVICE_ID"
+npx siteqwality incidents update "$INCIDENT_ID" --clear-service
+```
+
+`list` defaults to active incidents and returns `{ data, total }` for one page. Status is `active`, `resolved` or `all`; limit is 1 to 100. Increase `--offset` to fetch later pages.
+
+`ack` requires `--by` because an API key does not identify a member. The server checks that the member belongs to the account. Acknowledgement stops escalation. `resolve` always posts a public resolution for published incidents and emails their subscribers by default; `--no-notify-subscribers` suppresses the email. `update` changes only the supplied title, severity or service, without setting lifecycle status. Moving an incident to a service can start its escalation policy.
+
+All four commands accept `--api-url`, `--timeout` and `--retries`. Only reads retry transient failures. Incident mutations make one request even if `--retries` is set, so an ambiguous failure cannot repeat a page or public update. Inspect the incident before retrying a failed mutation. HTTP 400, 403, 404 and 409 errors return a nonzero exit code without printing response bodies or the API key.
+
 Upload creates the release idempotently before presigning. With no release it uses the reserved `__debug_id__` release. `releases deploy <version>` requires an existing release and records server time. It does not deploy application files or configure the browser SDK's release value.
 
 ## Injection

package/bin/siteqwality.js

@@ -1,22 +1,28 @@
 #!/usr/bin/env node
 import { Command, InvalidArgumentError } from 'commander';
-import { ApiClient, injectDirectory, uploadDirectory } from '../src/index.js';
+import { ApiClient, IncidentClient, injectDirectory, uploadDirectory } from '../src/index.js';
 
 const program = new Command()
   .name('siteqwality')
-  .version('0.1.1')
-  .description('Site Qwality Debug ID source maps and releases');
+  .version('0.1.2')
+  .description('Site Qwality source maps, releases and incidents');
 const integer = (value) => {
   if (!/^\d+$/.test(value)) throw new InvalidArgumentError('Expected an integer');
   return Number(value);
 };
-function authenticated(command) {
+function accountAuthenticated(command) {
   return command
-    .option('--app <uuid>', 'Application UUID', process.env.SITEQWALITY_APP_ID)
     .option('--api-url <url>', 'Site Qwality API base URL', process.env.SITEQWALITY_API_URL)
     .option('--retries <count>', 'Transient retries per request, 0 to 5', integer, 2)
     .option('--timeout <ms>', 'Request timeout, 1 to 300000 milliseconds', integer, 30000);
 }
+function authenticated(command) {
+  return accountAuthenticated(command).option(
+    '--app <uuid>',
+    'Application UUID',
+    process.env.SITEQWALITY_APP_ID,
+  );
+}
 function options(command) {
   return {
     ...command,
@@ -67,6 +73,53 @@ authenticated(
 authenticated(releases.command('list').description('List releases, newest created first')).action(
   async (opts) => print(await new ApiClient(options(opts)).listReleases()),
 );
+const incidents = program.command('incidents').description('List and manage account incidents');
+accountAuthenticated(
+  incidents.command('list').description('List one page, with the total matching count'),
+)
+  .option('--status <status>', 'active, resolved or all', 'active')
+  .option('--limit <count>', 'Page size, 1 to 100', integer, 50)
+  .option('--offset <count>', 'Row offset', integer, 0)
+  .action(async (opts) => print(await new IncidentClient(options(opts)).listIncidents(opts)));
+accountAuthenticated(
+  incidents
+    .command('ack <incident>')
+    .description('Acknowledge as an account member and stop escalation'),
+)
+  .requiredOption('--by <uuid>', 'Acknowledging member UUID, required for API keys')
+  .action(async (id, opts) =>
+    print(await new IncidentClient(options(opts)).acknowledgeIncident(id, opts.by)),
+  );
+accountAuthenticated(
+  incidents
+    .command('resolve <incident>')
+    .description('Resolve; published incidents get a public resolution'),
+)
+  .option('--message <text>', 'Public resolution text')
+  .option(
+    '--no-notify-subscribers',
+    'Suppress subscriber email; the public resolution is still posted',
+  )
+  .action(async (id, opts) =>
+    print(await new IncidentClient(options(opts)).resolveIncident(id, opts)),
+  );
+accountAuthenticated(
+  incidents.command('update <incident>').description('Change title, severity or service'),
+)
+  .option('--title <text>', 'Incident title')
+  .option('--severity <severity>', 'minor, major or critical')
+  .option('--service <uuid>', 'Move to a service, which may start paging')
+  .option('--clear-service', 'Detach the incident from its service')
+  .action(async (id, opts) => {
+    if (opts.service && opts.clearService) throw new Error('Choose --service or --clear-service');
+    print(
+      await new IncidentClient(options(opts)).updateIncident(id, {
+        title: opts.title,
+        severity: opts.severity,
+        serviceId: opts.clearService ? null : opts.service,
+      }),
+    );
+  });
 try {
   await program.parseAsync();
 } catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@siteqwality/cli",
-  "version": "0.1.1",
-  "description": "Site Qwality release and Debug ID source-map tooling",
+  "version": "0.1.2",
+  "description": "Site Qwality source maps, releases and incident tooling",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/api.js

@@ -31,11 +31,10 @@ export class HttpError extends Error {
     this.retryAfter = retryAfter;
   }
 }
-export class ApiClient {
+export class AuthenticatedClient {
   constructor(options = {}) {
     const base = safeUrl(options.apiBase || 'https://api.siteqwality.com');
     if (base.search) throw new Error('API base must not contain query parameters');
-    if (!isUuid(options.app)) throw new Error('A valid application UUID is required');
     if (
       typeof options.apiKey !== 'string' ||
       !options.apiKey.trim() ||
@@ -43,7 +42,6 @@ export class ApiClient {
     )
       throw new Error('An API key is required');
     this.base = base.href.replace(/\/+$/, '');
-    this.app = options.app;
     this.key = options.apiKey;
     this.retries = options.retries ?? 2;
     this.retryDelayMs = options.retryDelayMs ?? 500;
@@ -55,7 +53,7 @@ export class ApiClient {
     if (!Number.isInteger(this.timeoutMs) || this.timeoutMs < 1 || this.timeoutMs > 300_000)
       throw new Error('Invalid request timeout');
   }
-  async request(url, init, json = false) {
+  async request(url, init, json = false, retries = this.retries) {
     for (let attempt = 0; ; attempt++) {
       try {
         const response = await fetch(url, {
@@ -75,13 +73,13 @@ export class ApiClient {
         }
         const body = await response.json();
         if (!body || !Object.hasOwn(body, 'data')) throw new Error('Invalid API response envelope');
-        return body.data;
+        return json === 'envelope' ? body : body.data;
       } catch (err) {
         const transient =
           err instanceof HttpError
             ? [408, 429].includes(err.status) || err.status >= 500
             : err instanceof TypeError || err.name === 'TimeoutError';
-        if (!transient || attempt >= this.retries) {
+        if (!transient || attempt >= retries) {
           if (err instanceof HttpError) throw err;
           throw new Error('Request failed or returned an invalid response');
         }
@@ -98,17 +96,28 @@ export class ApiClient {
       }
     }
   }
-  api(suffix, method = 'GET', body) {
+  accountApi(path, method = 'GET', body, envelope = false, retries = this.retries) {
     return this.request(
-      `${this.base}/rum/${this.app}${suffix}`,
+      `${this.base}${path}`,
       {
         method,
         headers: { Authorization: `Bearer ${this.key}`, 'Content-Type': 'application/json' },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
       },
-      true,
+      envelope ? 'envelope' : true,
+      retries,
     );
   }
+}
+export class ApiClient extends AuthenticatedClient {
+  constructor(options = {}) {
+    if (!isUuid(options.app)) throw new Error('A valid application UUID is required');
+    super(options);
+    this.app = options.app;
+  }
+  api(suffix, method = 'GET', body) {
+    return this.accountApi(`/rum/${this.app}${suffix}`, method, body);
+  }
   async createRelease(version, { commit, env } = {}) {
     releaseName(version);
     for (const value of [commit, env])

package/src/incidents.js

@@ -0,0 +1,67 @@
+import { AuthenticatedClient, isUuid } from './api.js';
+
+const uuid = (id, name) => {
+  if (!isUuid(id)) throw new Error(`A valid ${name} UUID is required`);
+  return id;
+};
+const choice = (value, choices, name) => {
+  if (!choices.includes(value)) throw new Error(`${name} must be ${choices.join(', ')}`);
+  return value;
+};
+
+export class IncidentClient extends AuthenticatedClient {
+  async listIncidents({ status = 'active', limit = 50, offset = 0 } = {}) {
+    choice(status, ['active', 'resolved', 'all'], 'status');
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+      throw new Error('limit must be 1 to 100');
+    if (!Number.isSafeInteger(offset) || offset < 0)
+      throw new Error('offset must be a non-negative integer');
+    const query = new URLSearchParams({ status, limit: String(limit), offset: String(offset) });
+    const result = await this.accountApi(`/incident?${query}`, 'GET', undefined, true);
+    if (!Array.isArray(result.data) || !Number.isSafeInteger(result.total) || result.total < 0)
+      throw new Error('Invalid incident list response');
+    return { data: result.data, total: result.total };
+  }
+  acknowledgeIncident(id, acknowledgedBy) {
+    uuid(id, 'incident');
+    uuid(acknowledgedBy, 'acknowledging member');
+    return this.accountApi(
+      `/incident/${id}/acknowledge`,
+      'POST',
+      { acknowledged_by: acknowledgedBy },
+      false,
+      0,
+    );
+  }
+  resolveIncident(id, { message, notifySubscribers = true } = {}) {
+    uuid(id, 'incident');
+    if (message !== undefined && (typeof message !== 'string' || !message.trim()))
+      throw new Error('Resolution message must not be blank');
+    if (typeof notifySubscribers !== 'boolean')
+      throw new Error('notifySubscribers must be boolean');
+    return this.accountApi(
+      `/incident/${id}/resolve`,
+      'POST',
+      {
+        ...(message === undefined ? {} : { message }),
+        notify_subscribers: notifySubscribers,
+      },
+      false,
+      0,
+    );
+  }
+  updateIncident(id, { title, severity, serviceId } = {}) {
+    uuid(id, 'incident');
+    const body = {};
+    if (title !== undefined) {
+      if (typeof title !== 'string' || !title.trim()) throw new Error('Title must not be blank');
+      body.title = title;
+    }
+    if (severity !== undefined)
+      body.severity = choice(severity, ['minor', 'major', 'critical'], 'severity');
+    if (serviceId !== undefined)
+      body.service_id = serviceId === null ? null : uuid(serviceId, 'service');
+    if (!Object.keys(body).length) throw new Error('Choose a title, severity or service change');
+    return this.accountApi(`/incident/${id}`, 'PUT', body, false, 0);
+  }
+}

package/src/index.d.ts

@@ -9,14 +9,16 @@ export interface SourceMap {
   debugId?: string;
   [key: string]: unknown;
 }
-export interface ApiOptions {
-  app: string;
+export interface AccountApiOptions {
   apiKey: string;
   apiBase?: string;
   retries?: number;
   retryDelayMs?: number;
   timeoutMs?: number;
 }
+export interface ApiOptions extends AccountApiOptions {
+  app: string;
+}
 export interface ReleaseMetadata {
   commit?: string;
   env?: string;
@@ -93,4 +95,35 @@ export class ApiClient {
   put(url: string, headers: Record<string, string>, body: Uint8Array): Promise<void>;
 }
 
+export interface Incident {
+  id: string;
+  title: string;
+  severity: 'minor' | 'major' | 'critical';
+  status: 'investigating' | 'identified' | 'monitoring' | 'resolved';
+  responder_status: 'triggered' | 'acknowledged' | 'resolved';
+  service_id: string | null;
+  [key: string]: unknown;
+}
+export class IncidentClient {
+  constructor(options: AccountApiOptions);
+  listIncidents(options?: {
+    status?: 'active' | 'resolved' | 'all';
+    limit?: number;
+    offset?: number;
+  }): Promise<{ data: Incident[]; total: number }>;
+  acknowledgeIncident(id: string, acknowledgedBy: string): Promise<Incident>;
+  resolveIncident(
+    id: string,
+    options?: { message?: string; notifySubscribers?: boolean },
+  ): Promise<Incident>;
+  updateIncident(
+    id: string,
+    changes: {
+      title?: string;
+      severity?: 'minor' | 'major' | 'critical';
+      serviceId?: string | null;
+    },
+  ): Promise<Incident>;
+}
+
 export function sourceMapReference(code: string): string | undefined;

package/src/index.js

@@ -1,6 +1,7 @@
 export { inject, validateMap } from './inject.js';
 export { injectDirectory, collectPairs } from './files.js';
 export { ApiClient } from './api.js';
+export { IncidentClient } from './incidents.js';
 export { uploadMaps, uploadDirectory } from './upload.js';
 
 export { sourceMapReference } from './comments.js';