@siteqwality/cli 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @siteqwality/cli
 
-Version 0.1.2, Node.js 22+. Install:
+Version 0.1.4, Node.js 22+. Install:
 
 ```sh
 npm install --save-dev @siteqwality/cli
@@ -42,10 +42,24 @@ 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.
+`ack` requires `--by` because an API key does not identify a member. The server checks that the member belongs to the account. Acknowledgment 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.
 
+## On-call
+
+On-call commands read schedules with an account API key that has `read:incidents`. They never change a schedule.
+
+```sh
+export SITEQWALITY_API_KEY='your-incident-api-key'
+npx siteqwality oncall now
+npx siteqwality oncall now --schedule "$SCHEDULE_ID" --at 2026-10-21T09:00:00Z
+npx siteqwality oncall shifts "$SCHEDULE_ID" --since 2026-10-21T00:00:00Z --until 2026-11-04T00:00:00Z
+npx siteqwality oncall mine --user "$MEMBER_ID"
+```
+
+`now` lists who is on call on every schedule, or, with `--schedule`, one schedule's current shift with who is next. `shifts` returns a schedule's timeline with overrides applied and gaps included, 14 days by default and at most 90. `mine` lists one member's shifts across every schedule for the next 14 days; `--user` is required because an API key does not identify a member. Times are RFC 3339.
+
 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
@@ -58,7 +72,7 @@ Unchanged injected pairs can be processed repeatedly. If injected JavaScript cha
 
 ## Upload and deletion
 
-Uploads follow the Phase 4 API contract:
+Each upload runs these steps:
 
 1. Create the app-scoped release.
 2. Presign at most 50 maps per batch, with unique filenames and Debug IDs. Declare exact gzip byte sizes and JSON/gzip headers.
@@ -68,7 +82,7 @@ Uploads follow the Phase 4 API contract:
 
 Both raw JSON and gzip output are limited to 32 MiB per map. The client retries network failures, timeouts, HTTP 408/429 and 5xx responses with bounded backoff. It respects `Retry-After` up to 30 seconds and fails for longer requested waits. A storage 403 triggers a fresh presign and re-upload, bounded by `--retries`. Other permanent failures stop the command. An incomplete or mismatched presign/confirmation response fails closed. Failed uploads may leave pending server records; retrying gets new IDs. Earlier confirmed batches may remain ready, but no local map is removed when a later batch fails.
 
-Confirmation proves storage and metadata acceptance. It does not prove live symbolication. Backend deployment and an integrated SDK/API smoke test are separate release gates.
+Confirmation means the map is stored and its metadata accepted. To check symbolication end to end, open a new error from that release in Site Qwality.
 
 ## JavaScript API
 

package/bin/siteqwality.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
 import { Command, InvalidArgumentError } from 'commander';
-import { ApiClient, IncidentClient, injectDirectory, uploadDirectory } from '../src/index.js';
+import {
+  ApiClient,
+  IncidentClient,
+  OnCallClient,
+  injectDirectory,
+  uploadDirectory,
+} from '../src/index.js';
 
 const program = new Command()
   .name('siteqwality')
-  .version('0.1.2')
-  .description('Site Qwality source maps, releases and incidents');
+  .version('0.1.4')
+  .description('Site Qwality source maps, releases, incidents and on-call');
 const integer = (value) => {
   if (!/^\d+$/.test(value)) throw new InvalidArgumentError('Expected an integer');
   return Number(value);
@@ -120,6 +126,34 @@ accountAuthenticated(
       }),
     );
   });
+const oncall = program.command('oncall').description('See who is on call and when');
+accountAuthenticated(
+  oncall
+    .command('now')
+    .description('Who is on call now: every schedule, or one with its next shift'),
+)
+  .option('--schedule <uuid>', 'Only this schedule, with who is next')
+  .option('--at <time>', 'RFC 3339 instant instead of now')
+  .action(async (opts) =>
+    print(
+      await new OnCallClient(options(opts)).onCallNow({ scheduleId: opts.schedule, at: opts.at }),
+    ),
+  );
+accountAuthenticated(
+  oncall.command('shifts <schedule>').description("A schedule's shifts, gaps included"),
+)
+  .option('--since <time>', 'RFC 3339 start; defaults to now')
+  .option('--until <time>', 'RFC 3339 end; defaults to 14 days later, at most 90')
+  .action(async (schedule, opts) =>
+    print(await new OnCallClient(options(opts)).listShifts(schedule, opts)),
+  );
+accountAuthenticated(oncall.command('mine').description("A member's shifts across every schedule"))
+  .requiredOption('--user <uuid>', 'Member UUID, required for API keys')
+  .option('--since <time>', 'RFC 3339 start; defaults to now')
+  .option('--until <time>', 'RFC 3339 end; defaults to 14 days later, at most 90')
+  .action(async (opts) =>
+    print(await new OnCallClient(options(opts)).listMemberShifts(opts.user, opts)),
+  );
 try {
   await program.parseAsync();
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siteqwality/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Site Qwality source maps, releases and incident tooling",
   "type": "module",
   "engines": {

package/src/index.d.ts

@@ -126,4 +126,42 @@ export class IncidentClient {
   ): Promise<Incident>;
 }
 
+export interface OnCallShift {
+  schedule_id?: string;
+  schedule_name?: string;
+  user_id?: string;
+  source: 'override' | 'layer' | 'gap';
+  layer_id?: string;
+  layer_number?: number;
+  override_id?: string;
+  starts_at?: string;
+  ends_at?: string;
+}
+export interface OnCallNow {
+  schedule_id: string;
+  at: string;
+  timezone: string;
+  on_call: OnCallShift;
+  next?: OnCallShift;
+}
+export class OnCallClient {
+  constructor(options: AccountApiOptions);
+  onCallNow(options: { scheduleId: string; at?: string }): Promise<OnCallNow>;
+  onCallNow(options?: { at?: string }): Promise<OnCallShift[]>;
+  listShifts(
+    scheduleId: string,
+    range?: { since?: string; until?: string },
+  ): Promise<{
+    schedule_id: string;
+    since: string;
+    until: string;
+    timezone: string;
+    shifts: OnCallShift[];
+  }>;
+  listMemberShifts(
+    userId: string,
+    range?: { since?: string; until?: string },
+  ): Promise<OnCallShift[]>;
+}
+
 export function sourceMapReference(code: string): string | undefined;

package/src/index.js

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

package/src/oncall.js

@@ -0,0 +1,41 @@
+import { AuthenticatedClient, isUuid } from './api.js';
+
+const DAY_MS = 86_400_000;
+const uuid = (id, name) => {
+  if (!isUuid(id)) throw new Error(`A valid ${name} UUID is required`);
+  return id;
+};
+const instant = (value, name) => {
+  if (value === undefined) return undefined;
+  const ms = typeof value === 'string' ? Date.parse(value) : Number.NaN;
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(value) || Number.isNaN(ms))
+    throw new Error(`${name} must be an RFC 3339 time, for example 2026-10-21T09:00:00Z`);
+  return new Date(ms).toISOString();
+};
+const query = (params) => {
+  const entries = Object.entries(params).filter(([, v]) => v !== undefined);
+  return entries.length ? `?${new URLSearchParams(entries)}` : '';
+};
+
+export class OnCallClient extends AuthenticatedClient {
+  /** Who is on call now (or at `at`): one schedule with its next shift, or every schedule. */
+  onCallNow({ scheduleId, at } = {}) {
+    const when = instant(at, 'at');
+    if (scheduleId === undefined) return this.accountApi(`/on_call${query({ since: when })}`);
+    uuid(scheduleId, 'schedule');
+    return this.accountApi(`/on_call_schedule/${scheduleId}/on_call${query({ at: when })}`);
+  }
+  /** A schedule's shifts, gaps included; the API allows at most 90 days. */
+  listShifts(scheduleId, { since, until } = {}) {
+    uuid(scheduleId, 'schedule');
+    const range = { since: instant(since, 'since'), until: instant(until, 'until') };
+    return this.accountApi(`/on_call_schedule/${scheduleId}/shifts${query(range)}`);
+  }
+  /** One member's shifts across every schedule, from now for 14 days unless given. */
+  listMemberShifts(userId, { since, until } = {}) {
+    uuid(userId, 'member');
+    const start = instant(since, 'since') ?? new Date().toISOString();
+    const end = instant(until, 'until') ?? new Date(Date.parse(start) + 14 * DAY_MS).toISOString();
+    return this.accountApi(`/on_call${query({ user_id: userId, since: start, until: end })}`);
+  }
+}