@belvador/api 0.1.0 → 0.3.0

package/README.md

@@ -44,6 +44,10 @@ try {
   Create one in Settings → API tokens. The client never puts the token in an error message.
 - **Errors** are RFC 9457 problem+json, surfaced as `BelvadorApiError` with a stable `code`,
   `status`, `scope` (for `API_SCOPE_INSUFFICIENT`), `retryAfter` and `requestId`.
+- **Approvals**: sensitive operations (keys, members, tokens, alert destinations, node changes) throw
+  `APPROVAL_REQUIRED` with `e.approval` = `{ id, url, expiresAt, state }`. A person opens `url` on
+  belvador.dev and approves with their authenticator code; call again with the same `idempotencyKey`
+  (or `call("approvals.get", { approval_id })`) to read the outcome. Only https `/approve/<id>` links are kept.
 - **Retries**: reads, and writes sent with an `idempotencyKey`, are retried on 429 / 502–504 and network
   errors (`retries`, default 2), honouring `Retry-After` up to 10 s. `NODE_OFFLINE` is not retried.
 - **Scopes**: `await belvador.scopes()` returns the token's effective scopes (the `Belvador-Scopes` header).

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { OPERATIONS, type OperationId, type OperationMeta, type OperationParams } from "./operations.gen.js";
-export declare const CLIENT_VERSION = "0.1.0";
+export declare const CLIENT_VERSION = "0.3.0";
 export declare const DEFAULT_BASE_URL = "https://api.belvador.dev";
 /** Personal (`blv_pat_`), service (`blv_svc_`) or OAuth access (`blv_oat_`) token. */
 export declare const TOKEN_PATTERN: RegExp;

package/dist/client.js

@@ -1,7 +1,7 @@
 import { BelvadorApiError, errorFrom } from "./errors.js";
 import { nodeErrorWord, nodeReadRequest, nodeRefusal, nodeWindowMissing, NODE_REFUSAL_STATUS, reshapeNodeAnswer, } from "./node-wire.gen.js";
 import { OPERATIONS } from "./operations.gen.js";
-export const CLIENT_VERSION = "0.1.0";
+export const CLIENT_VERSION = "0.3.0";
 export const DEFAULT_BASE_URL = "https://api.belvador.dev";
 /** Personal (`blv_pat_`), service (`blv_svc_`) or OAuth access (`blv_oat_`) token. */
 export const TOKEN_PATTERN = /^blv_(pat|svc|oat)_[A-Za-z0-9_-]{20,200}$/;
@@ -170,7 +170,9 @@ class Client {
             method: meta.method,
             headers,
             ...(parts.body !== undefined ? { body: JSON.stringify(parts.body) } : {}),
-        }, meta.method === "GET" || !!opts.idempotencyKey, opts.signal);
+        }, 
+        // Reads are safe to retry, including a read that posts a JSON body (a backtest).
+        meta.method === "GET" || meta.scope.endsWith(":read") || !!opts.idempotencyKey, opts.signal);
         this.#noteScopes(res);
         if (res.status === 401)
             this.#ticket = null;

package/dist/errors.d.ts

@@ -20,6 +20,11 @@ export declare class BelvadorApiError extends Error {
         pointer: string;
         code: string;
     }> | undefined;
+    /**
+     * `APPROVAL_REQUIRED` (403): the approval a person gives on belvador.dev. Retry the same call
+     * with the same Idempotency-Key after they approved to get the stored result.
+     */
+    readonly approval: Approval | undefined;
     constructor(code: string, status: number, extra?: {
         title?: string;
         detail?: string;
@@ -30,7 +35,17 @@ export declare class BelvadorApiError extends Error {
             pointer: string;
             code: string;
         }>;
+        approval?: Approval;
     });
 }
+export type ApprovalState = "pending" | "approved" | "executed" | "rejected" | "expired" | "failed";
+export type Approval = {
+    id: string;
+    url: string;
+    expiresAt: string;
+    state: ApprovalState;
+};
+/** Approval members of a problem body; only an https `/approve/<id>` link is accepted. */
+export declare function approvalFrom(body: Record<string, unknown>): Approval | undefined;
 /** An error answer → BelvadorApiError (problem+json fields, scope challenge, Retry-After). */
 export declare function errorFrom(res: Response): Promise<BelvadorApiError>;

package/dist/errors.js

@@ -17,6 +17,11 @@ export class BelvadorApiError extends Error {
     requestId;
     /** Field errors: JSON pointers into the request with a code. */
     errors;
+    /**
+     * `APPROVAL_REQUIRED` (403): the approval a person gives on belvador.dev. Retry the same call
+     * with the same Idempotency-Key after they approved to get the stored result.
+     */
+    approval;
     constructor(code, status, extra = {}) {
         super(extra.title ? `${code}: ${extra.title}` : extra.detail ? `${code}: ${extra.detail}` : code);
         this.code = code;
@@ -27,8 +32,35 @@ export class BelvadorApiError extends Error {
         this.retryAfter = extra.retryAfter;
         this.requestId = extra.requestId;
         this.errors = extra.errors;
+        this.approval = extra.approval;
     }
 }
+const APPROVAL_STATES = ["pending", "approved", "executed", "rejected", "expired", "failed"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Approval members of a problem body; only an https `/approve/<id>` link is accepted. */
+export function approvalFrom(body) {
+    const id = body["approval_id"];
+    const url = body["approval_url"];
+    const exp = body["expires_at"];
+    const state = body["state"];
+    if (typeof id !== "string" || !UUID.test(id) || typeof url !== "string" || url.length > 300)
+        return undefined;
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const local = u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+    if ((u.protocol !== "https:" && !local) || !u.pathname.endsWith(`/approve/${id}`))
+        return undefined;
+    if (typeof exp !== "string" || Number.isNaN(Date.parse(exp)))
+        return undefined;
+    if (typeof state !== "string" || !APPROVAL_STATES.includes(state))
+        return undefined;
+    return { id, url: u.toString(), expiresAt: exp, state: state };
+}
 const str = (v, max = 500) => typeof v === "string" && v ? v.slice(0, max) : undefined;
 /** An error answer → BelvadorApiError (problem+json fields, scope challenge, Retry-After). */
 export async function errorFrom(res) {
@@ -69,5 +101,8 @@ export async function errorFrom(res) {
         extra.requestId = requestId;
     if (errors?.length)
         extra.errors = errors;
+    const approval = approvalFrom(body);
+    if (approval)
+        extra.approval = approval;
     return new BelvadorApiError(code, res.status, extra);
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { CLIENT_VERSION, createClient, DEFAULT_BASE_URL, requestParts, SCOPES_HEADER, TOKEN_PATTERN, type ApiResult, type BelvadorClient, type CallOptions, type ClientOptions, type Page, type PagedOperationId, } from "./client.js";
-export { BelvadorApiError } from "./errors.js";
+export { BelvadorApiError, type Approval, type ApprovalState } from "./errors.js";
 export { API_VERSION, OPERATIONS, type HttpMethod, type OperationId, type OperationMeta, type OperationParams, } from "./operations.gen.js";

package/dist/node-wire.gen.d.ts

@@ -26,6 +26,9 @@ export declare const NODE_REFUSAL_STATUS: {
     readonly QUERY_WINDOW_REQUIRED: 400;
     readonly QUERY_WINDOW_TOO_LARGE: 400;
     readonly INVALID_INPUT: 400;
+    readonly OCCURRENCE_LIMIT: 409;
+    readonly OCCURRENCE_DUE_INVALID: 400;
+    readonly MONITOR_SELECTOR_INVALID: 400;
     readonly UNAVAILABLE: 503;
 };
 export type NodeRefusalCode = keyof typeof NODE_REFUSAL_STATUS;

package/dist/node-wire.gen.js

@@ -66,6 +66,9 @@ export const NODE_REFUSAL_STATUS = {
     QUERY_WINDOW_REQUIRED: 400,
     QUERY_WINDOW_TOO_LARGE: 400,
     INVALID_INPUT: 400,
+    OCCURRENCE_LIMIT: 409,
+    OCCURRENCE_DUE_INVALID: 400,
+    MONITOR_SELECTOR_INVALID: 400,
     UNAVAILABLE: 503,
 };
 const refuse = (code, extra = {}) => ({
@@ -85,6 +88,14 @@ export function nodeRefusal(status, error) {
         return refuse("NODE_BUSY", { retryAfter: 2 });
     if (error === "query_timeout")
         return refuse("QUERY_TIMEOUT");
+    if (error === "occurrence_limit")
+        return refuse("OCCURRENCE_LIMIT");
+    if (error === "due_out_of_range")
+        return refuse("OCCURRENCE_DUE_INVALID");
+    if (error === "selector_invalid")
+        return refuse("MONITOR_SELECTOR_INVALID");
+    if (error === "unknown_monitor")
+        return refuse("NOT_FOUND");
     if (status === 503 || status === 504 || status === 502)
         return refuse("NODE_OFFLINE");
     if (status === 400 || status === 422) {

package/dist/operations.gen.d.ts

@@ -110,6 +110,20 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "approvals.get": {
+        readonly method: "GET";
+        readonly path: "/v1/approvals/{approval_id}";
+        readonly pathParams: readonly ["approval_id"];
+        readonly scope: "org:read";
+        readonly kind: "read";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
     readonly "audit.list": {
         readonly method: "GET";
         readonly path: "/v1/audit-log";
@@ -269,6 +283,132 @@ export declare const OPERATIONS: {
         };
         readonly defaults: {};
     };
+    readonly "incident_rules.delete": {
+        readonly method: "DELETE";
+        readonly path: "/v1/incident-rules/{rule_id}";
+        readonly pathParams: readonly ["rule_id"];
+        readonly scope: "alerts:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incident_rules.list": {
+        readonly method: "GET";
+        readonly path: "/v1/incident-rules";
+        readonly pathParams: readonly [];
+        readonly scope: "alerts:read";
+        readonly kind: "read";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incident_rules.save": {
+        readonly method: "POST";
+        readonly path: "/v1/incident-rules";
+        readonly pathParams: readonly [];
+        readonly scope: "alerts:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "optional";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incidents.acknowledge": {
+        readonly method: "POST";
+        readonly path: "/v1/incidents/{incident_id}/ack";
+        readonly pathParams: readonly ["incident_id"];
+        readonly scope: "incidents:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "optional";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incidents.get": {
+        readonly method: "GET";
+        readonly path: "/v1/incidents/{incident_id}";
+        readonly pathParams: readonly ["incident_id"];
+        readonly scope: "incidents:read";
+        readonly kind: "read";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incidents.list": {
+        readonly method: "GET";
+        readonly path: "/v1/incidents";
+        readonly pathParams: readonly [];
+        readonly scope: "incidents:read";
+        readonly kind: "read";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: true;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incidents.note": {
+        readonly method: "POST";
+        readonly path: "/v1/incidents/{incident_id}/notes";
+        readonly pathParams: readonly ["incident_id"];
+        readonly scope: "incidents:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "optional";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incidents.resolve": {
+        readonly method: "POST";
+        readonly path: "/v1/incidents/{incident_id}/resolve";
+        readonly pathParams: readonly ["incident_id"];
+        readonly scope: "incidents:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "optional";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "incidents.update": {
+        readonly method: "PATCH";
+        readonly path: "/v1/incidents/{incident_id}";
+        readonly pathParams: readonly ["incident_id"];
+        readonly scope: "incidents:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
     readonly "ingest_keys.create": {
         readonly method: "POST";
         readonly path: "/v1/projects/{project_id}/ingest-keys";
@@ -506,6 +646,62 @@ export declare const OPERATIONS: {
         };
         readonly defaults: {};
     };
+    readonly "maintenance.create": {
+        readonly method: "POST";
+        readonly path: "/v1/maintenance-windows";
+        readonly pathParams: readonly [];
+        readonly scope: "monitors:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "required";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 201;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "maintenance.delete": {
+        readonly method: "DELETE";
+        readonly path: "/v1/maintenance-windows/{window_id}";
+        readonly pathParams: readonly ["window_id"];
+        readonly scope: "monitors:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "maintenance.list": {
+        readonly method: "GET";
+        readonly path: "/v1/maintenance-windows";
+        readonly pathParams: readonly [];
+        readonly scope: "monitors:read";
+        readonly kind: "read";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: true;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "maintenance.update": {
+        readonly method: "PATCH";
+        readonly path: "/v1/maintenance-windows/{window_id}";
+        readonly pathParams: readonly ["window_id"];
+        readonly scope: "monitors:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
     readonly "members.change_role": {
         readonly method: "PATCH";
         readonly path: "/v1/members/{user_id}";
@@ -548,6 +744,22 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "monitors.backtest": {
+        readonly method: "POST";
+        readonly path: "/v1/monitors/backtest";
+        readonly pathParams: readonly [];
+        readonly scope: "monitors:read";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "q/monitors/backtest";
+        };
+        readonly defaults: {};
+    };
     readonly "monitors.create": {
         readonly method: "POST";
         readonly path: "/v1/monitors";
@@ -618,6 +830,23 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "monitors.occurrences": {
+        readonly method: "GET";
+        readonly path: "/v1/monitors/{monitor_id}/occurrences";
+        readonly pathParams: readonly ["monitor_id"];
+        readonly scope: "monitors:read";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: true;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "q/monitors/{monitor_id}/occurrences";
+            readonly list: "occurrences";
+        };
+        readonly defaults: {};
+    };
     readonly "monitors.set_muted": {
         readonly method: "PUT";
         readonly path: "/v1/monitors/{monitor_id}/mute";
@@ -646,6 +875,22 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "monitors.signal": {
+        readonly method: "GET";
+        readonly path: "/v1/monitors/{monitor_id}/signal";
+        readonly pathParams: readonly ["monitor_id"];
+        readonly scope: "monitors:read";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "q/monitors/{monitor_id}/signal";
+        };
+        readonly defaults: {};
+    };
     readonly "monitors.update": {
         readonly method: "PATCH";
         readonly path: "/v1/monitors/{monitor_id}";
@@ -814,6 +1059,80 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "notification_policies.delete": {
+        readonly method: "DELETE";
+        readonly path: "/v1/notification-policies/{policy_id}";
+        readonly pathParams: readonly ["policy_id"];
+        readonly scope: "alerts:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "notification_policies.list": {
+        readonly method: "GET";
+        readonly path: "/v1/notification-policies";
+        readonly pathParams: readonly [];
+        readonly scope: "alerts:read";
+        readonly kind: "read";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "notification_policies.save": {
+        readonly method: "POST";
+        readonly path: "/v1/notification-policies";
+        readonly pathParams: readonly [];
+        readonly scope: "alerts:write";
+        readonly kind: "write";
+        readonly sensitivity: "normal";
+        readonly idempotency: "optional";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
+    readonly "occurrences.cancel": {
+        readonly method: "DELETE";
+        readonly path: "/v1/occurrences/{monitor_slug}/{occurrence_id}";
+        readonly pathParams: readonly ["monitor_slug", "occurrence_id"];
+        readonly scope: "monitors:write";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "w/monitors/occurrences/cancel";
+        };
+        readonly defaults: {};
+    };
+    readonly "occurrences.create": {
+        readonly method: "POST";
+        readonly path: "/v1/occurrences";
+        readonly pathParams: readonly [];
+        readonly scope: "monitors:write";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "w/monitors/occurrences";
+        };
+        readonly defaults: {};
+    };
     readonly "ping_tokens.reset": {
         readonly method: "POST";
         readonly path: "/v1/monitors/{monitor_id}/ping-tokens/reset";
@@ -1545,8 +1864,9 @@ export interface OperationParams {
         is_enabled: boolean;
         notify_all: boolean;
         destination_ids: Array<string>;
-        monitor_kinds?: Array<"missed" | "failed" | "timeout" | "unknown">;
+        monitor_kinds?: Array<"missed" | "failed" | "timeout" | "unknown" | "count" | "assertion" | "deadline" | "stalled">;
         slo_severities?: Array<"page" | "ticket">;
+        policy_id?: string | null;
     };
     /** Turn a rule on or off. */
     "alert_rules.set_enabled": {
@@ -1560,14 +1880,18 @@ export interface OperationParams {
         state?: "open" | "resolved" | "all";
         monitor_id?: string;
     };
+    /** State of an approval this token asked for (admins: any in the workspace): pending, approved, executed, rejected, expired or failed, with its result ids. */
+    "approvals.get": {
+        approval_id: string;
+    };
     /** Audit log, newest first (admins). */
     "audit.list": {
         limit?: number;
         cursor?: string;
     };
-    /** Start adding a Telegram, Slack, email or webhook destination; a person enters its secrets. */
+    /** Start adding a Telegram, Slack, email, webhook, PagerDuty or incident.io destination; a person enters its secrets. */
     "destinations.create": {
-        provider: "telegram" | "slack" | "email" | "webhook";
+        provider: "telegram" | "slack" | "email" | "webhook" | "pagerduty" | "incident_io";
         name: string;
         project_ids: Array<number>;
         locale: "vi" | "en";
@@ -1614,6 +1938,58 @@ export interface OperationParams {
         issue_id: number;
         cursor?: string;
     };
+    /** Delete an incident rule; open incidents stay as they are. */
+    "incident_rules.delete": {
+        rule_id: string;
+    };
+    /** Rules that turn alerts into incidents: match, grouping, window and recovery wait. */
+    "incident_rules.list": Record<string, never>;
+    /** Create (`rule_id` null) or replace an incident rule. Admins. */
+    "incident_rules.save": {
+        rule_id: string | null;
+        input: {
+            name: string;
+            is_enabled: boolean;
+            position?: number;
+            project_ids: Array<number>;
+            environments: Array<string>;
+            kinds: Array<"monitor" | "uptime" | "slo" | "issue">;
+            min_severity: "critical" | "high" | "medium" | "low";
+            group_by: "monitor" | "project_env";
+            window_minutes: number;
+            recovery_hold_minutes: number;
+        };
+    };
+    /** Take ownership of an open incident; stops its escalation. Members and up. */
+    "incidents.acknowledge": {
+        incident_id: string;
+    };
+    /** One incident with its linked alerts, timeline (notes included) and message deliveries (`accepted` = the provider took it; only a person acknowledges). */
+    "incidents.get": {
+        incident_id: string;
+    };
+    /** Incidents (INC-n): state, severity and peak, owner, linked alert count; newest first. */
+    "incidents.list": {
+        limit?: number;
+        cursor?: string;
+        state?: "active" | "resolved" | "all";
+    };
+    /** Add a note to the incident timeline (plain text, ≤ 2,000 characters). */
+    "incidents.note": {
+        incident_id: string;
+        note: string;
+    };
+    /** Close an incident by hand with a reason (1–500 characters); it is labelled "not verified". */
+    "incidents.resolve": {
+        incident_id: string;
+        note: string;
+    };
+    /** Rename an incident or assign it to a member (`owner_user_id: null` clears it). */
+    "incidents.update": {
+        incident_id: string;
+        title?: string;
+        owner_user_id?: string | null;
+    };
     /** Create an OTLP ingest key (`bvi_`). */
     "ingest_keys.create": {
         project_id: number;
@@ -1762,6 +2138,59 @@ export interface OperationParams {
         order?: "asc" | "desc";
         cursor?: string;
     };
+    /** Hold back monitor notifications during a one-off or weekly window (workspace, projects or monitors); monitors keep evaluating and recording. */
+    "maintenance.create": Record<string, never> & ((Record<string, unknown>) & ({
+        kind: "once";
+        starts_at: string;
+        scope: "workspace" | "project" | "monitor";
+        project_ids: Array<number>;
+        monitor_ids: Array<string>;
+        timezone: string;
+        duration_minutes: number;
+        reason: string;
+    } | {
+        kind: "weekly";
+        weekdays: Array<number>;
+        start_time: string;
+        scope: "workspace" | "project" | "monitor";
+        project_ids: Array<number>;
+        monitor_ids: Array<string>;
+        timezone: string;
+        duration_minutes: number;
+        reason: string;
+    }));
+    /** Delete a maintenance window; notifications resume at once. */
+    "maintenance.delete": {
+        window_id: string;
+    };
+    /** Maintenance windows and whether each is active now. */
+    "maintenance.list": {
+        limit?: number;
+        cursor?: string;
+    };
+    /** Replace a maintenance window's scope, times and reason. */
+    "maintenance.update": {
+        window_id: string;
+    } & ((Record<string, unknown>) & ({
+        kind: "once";
+        starts_at: string;
+        scope: "workspace" | "project" | "monitor";
+        project_ids: Array<number>;
+        monitor_ids: Array<string>;
+        timezone: string;
+        duration_minutes: number;
+        reason: string;
+    } | {
+        kind: "weekly";
+        weekdays: Array<number>;
+        start_time: string;
+        scope: "workspace" | "project" | "monitor";
+        project_ids: Array<number>;
+        monitor_ids: Array<string>;
+        timezone: string;
+        duration_minutes: number;
+        reason: string;
+    }));
     /** Change a member's role. */
     "members.change_role": {
         user_id: string;
@@ -1776,10 +2205,55 @@ export interface OperationParams {
     "members.remove": {
         user_id: string;
     };
-    /** Create a cron or heartbeat monitor. A heartbeat monitor returns its ping token once. */
-    "monitors.create": {
+    /** How often count/assertion settings would have alerted over the last 30 days of stored data (same rule as the live evaluator). */
+    "monitors.backtest": {
+        project: number;
+        settings: {
+            type: "count";
+            selector: {
+                signal: "event" | "check_in" | "span" | "log";
+                match: Array<{
+                    key: string;
+                    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                    value?: string | number | boolean | Array<string>;
+                }>;
+            };
+            window_minutes: number;
+            comparator: "lt" | "gt" | "outside";
+            threshold: number;
+            threshold_high: number | null;
+            missing_data: "alert" | "keep" | "resolve" | "treat_as_zero";
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "assertion";
+            selector: {
+                signal: "event" | "check_in" | "span" | "log";
+                match: Array<{
+                    key: string;
+                    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                    value?: string | number | boolean | Array<string>;
+                }>;
+            };
+            assert: Array<{
+                key: string;
+                op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                value?: string | number | boolean | Array<string>;
+            }>;
+            window_minutes: number;
+            threshold: number;
+            missing_data: "alert" | "keep" | "resolve" | "treat_as_zero";
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        };
+    };
+    /** Create a cron or heartbeat monitor, or a signal monitor (`settings.type`: count, assertion, deadline, progress). A heartbeat monitor returns its ping token once. */
+    "monitors.create": Record<string, never> & (({
         project_id: number;
         slug: string;
+    }) & ({
         name: string;
         mode?: "check_in" | "heartbeat";
         kind: "crontab" | "interval" | "on_demand";
@@ -1797,7 +2271,62 @@ export interface OperationParams {
         failure_threshold: number;
         recovery_threshold: number;
         expected_environments: Array<string>;
-    };
+    } | {
+        name: string;
+        settings: {
+            type: "count";
+            selector: {
+                signal: "event" | "check_in" | "span" | "log";
+                match: Array<{
+                    key: string;
+                    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                    value?: string | number | boolean | Array<string>;
+                }>;
+            };
+            window_minutes: number;
+            comparator: "lt" | "gt" | "outside";
+            threshold: number;
+            threshold_high: number | null;
+            missing_data: "alert" | "keep" | "resolve" | "treat_as_zero";
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "assertion";
+            selector: {
+                signal: "event" | "check_in" | "span" | "log";
+                match: Array<{
+                    key: string;
+                    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                    value?: string | number | boolean | Array<string>;
+                }>;
+            };
+            assert: Array<{
+                key: string;
+                op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                value?: string | number | boolean | Array<string>;
+            }>;
+            window_minutes: number;
+            threshold: number;
+            missing_data: "alert" | "keep" | "resolve" | "treat_as_zero";
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "deadline";
+            occurrence_grace_minutes: number;
+            progress_timeout_minutes: number | null;
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "progress";
+            progress_timeout_minutes: number;
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        };
+    }));
     /** Delete a monitor; `confirm_slug` must repeat its slug. */
     "monitors.delete": {
         monitor_id: string;
@@ -1811,11 +2340,19 @@ export interface OperationParams {
     "monitors.get": {
         monitor_id: string;
     };
-    /** Cron and heartbeat monitors. */
+    /** Monitors of every type (cron, heartbeat, count, assertion, deadline, progress); `type` narrows the list. */
     "monitors.list": {
         limit?: number;
         cursor?: string;
         project_id?: number;
+        type?: "job" | "count" | "assertion" | "deadline" | "progress";
+    };
+    /** Occurrences of a deadline monitor (pending, on time, late, missed, failed, cancelled), newest due first. */
+    "monitors.occurrences": {
+        monitor_id: string;
+        state?: "open" | "finished" | "all";
+        environment?: string;
+        cursor?: string;
     };
     /** Mute or unmute a monitor's alerts. */
     "monitors.set_muted": {
@@ -1827,9 +2364,15 @@ export interface OperationParams {
         monitor_id: string;
         until: string | "forever" | null;
     };
-    /** Replace a monitor's schedule, margins and thresholds. */
+    /** A signal monitor's minute counts (count/assertion) for up to 24 h per environment, and its open runs (progress, deadline). */
+    "monitors.signal": {
+        monitor_id: string;
+        hours?: number;
+    };
+    /** Replace a monitor's schedule, margins and thresholds, or a signal monitor's settings (the type stays). */
     "monitors.update": {
         monitor_id: string;
+    } & ((Record<string, unknown>) & ({
         name: string;
         mode?: "check_in" | "heartbeat";
         kind: "crontab" | "interval" | "on_demand";
@@ -1847,7 +2390,62 @@ export interface OperationParams {
         failure_threshold: number;
         recovery_threshold: number;
         expected_environments: Array<string>;
-    };
+    } | {
+        name: string;
+        settings: {
+            type: "count";
+            selector: {
+                signal: "event" | "check_in" | "span" | "log";
+                match: Array<{
+                    key: string;
+                    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                    value?: string | number | boolean | Array<string>;
+                }>;
+            };
+            window_minutes: number;
+            comparator: "lt" | "gt" | "outside";
+            threshold: number;
+            threshold_high: number | null;
+            missing_data: "alert" | "keep" | "resolve" | "treat_as_zero";
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "assertion";
+            selector: {
+                signal: "event" | "check_in" | "span" | "log";
+                match: Array<{
+                    key: string;
+                    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                    value?: string | number | boolean | Array<string>;
+                }>;
+            };
+            assert: Array<{
+                key: string;
+                op: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "in" | "exists" | "not_exists" | "prefix";
+                value?: string | number | boolean | Array<string>;
+            }>;
+            window_minutes: number;
+            threshold: number;
+            missing_data: "alert" | "keep" | "resolve" | "treat_as_zero";
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "deadline";
+            occurrence_grace_minutes: number;
+            progress_timeout_minutes: number | null;
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        } | {
+            type: "progress";
+            progress_timeout_minutes: number;
+            environments: Array<string>;
+            severity: "critical" | "high" | "medium" | "low";
+            recovery_threshold: number;
+        };
+    }));
     /** Start a backup now (at most once per 10 minutes). */
     "node.backup_now": Record<string, never>;
     /** Cancel a scheduled node deletion. */
@@ -1891,6 +2489,48 @@ export interface OperationParams {
     "node.upgrade": {
         node_id: string;
     };
+    /** Delete a policy (not the default); its rules fall back to the default policy. */
+    "notification_policies.delete": {
+        policy_id: string;
+    };
+    /** Notification policies: quiet hours, digest, fallback chain and escalation. */
+    "notification_policies.list": Record<string, never>;
+    /** Create (`policy_id` null) or replace a policy. Critical and high are never held; chains use existing destinations only. Admins. */
+    "notification_policies.save": {
+        policy_id: string | null;
+        is_default: boolean;
+        input: {
+            name: string;
+            timezone: string;
+            quiet_hours: {
+                days: Array<number>;
+                start: string;
+                end: string;
+            } | null;
+            quiet_severities: Array<"medium" | "low">;
+            digest: "off" | "hourly" | "daily";
+            digest_at: string | null;
+            digest_severities: Array<"medium" | "low">;
+            fallback: Array<string>;
+            escalate_after_minutes: number | null;
+            escalation: Array<string>;
+        };
+    };
+    /** Cancel a pending occurrence (the app moved or dropped the job); a cancelled occurrence never alerts. */
+    "occurrences.cancel": {
+        monitor_slug: string;
+        occurrence_id: string;
+        project: number;
+        environment?: string;
+    };
+    /** Register one run a deadline monitor expects (`due_at` within 35 days); the same id again moves its due time while it is pending. */
+    "occurrences.create": {
+        project: number;
+        monitor_slug: string;
+        occurrence_id: string;
+        due_at: string;
+        environment?: string;
+    };
     /** Suspected leak: stop every live ping token and issue a new one. */
     "ping_tokens.reset": {
         monitor_id: string;

package/dist/operations.gen.js

@@ -86,6 +86,20 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "approvals.get": {
+        method: "GET",
+        path: "/v1/approvals/{approval_id}",
+        pathParams: ["approval_id"],
+        scope: "org:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
     "audit.list": {
         method: "GET",
         path: "/v1/audit-log",
@@ -240,6 +254,132 @@ export const OPERATIONS = {
         node: { path: "q/issues/{issue_id}/events", list: "events" },
         defaults: {},
     },
+    "incident_rules.delete": {
+        method: "DELETE",
+        path: "/v1/incident-rules/{rule_id}",
+        pathParams: ["rule_id"],
+        scope: "alerts:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incident_rules.list": {
+        method: "GET",
+        path: "/v1/incident-rules",
+        pathParams: [],
+        scope: "alerts:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incident_rules.save": {
+        method: "POST",
+        path: "/v1/incident-rules",
+        pathParams: [],
+        scope: "alerts:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incidents.acknowledge": {
+        method: "POST",
+        path: "/v1/incidents/{incident_id}/ack",
+        pathParams: ["incident_id"],
+        scope: "incidents:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incidents.get": {
+        method: "GET",
+        path: "/v1/incidents/{incident_id}",
+        pathParams: ["incident_id"],
+        scope: "incidents:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incidents.list": {
+        method: "GET",
+        path: "/v1/incidents",
+        pathParams: [],
+        scope: "incidents:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: true,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incidents.note": {
+        method: "POST",
+        path: "/v1/incidents/{incident_id}/notes",
+        pathParams: ["incident_id"],
+        scope: "incidents:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incidents.resolve": {
+        method: "POST",
+        path: "/v1/incidents/{incident_id}/resolve",
+        pathParams: ["incident_id"],
+        scope: "incidents:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "incidents.update": {
+        method: "PATCH",
+        path: "/v1/incidents/{incident_id}",
+        pathParams: ["incident_id"],
+        scope: "incidents:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
     "ingest_keys.create": {
         method: "POST",
         path: "/v1/projects/{project_id}/ingest-keys",
@@ -450,6 +590,62 @@ export const OPERATIONS = {
         node: { path: "q/logs", list: "logs", window: true },
         defaults: {},
     },
+    "maintenance.create": {
+        method: "POST",
+        path: "/v1/maintenance-windows",
+        pathParams: [],
+        scope: "monitors:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "required",
+        ifMatch: false,
+        paged: false,
+        status: 201,
+        node: null,
+        defaults: {},
+    },
+    "maintenance.delete": {
+        method: "DELETE",
+        path: "/v1/maintenance-windows/{window_id}",
+        pathParams: ["window_id"],
+        scope: "monitors:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "maintenance.list": {
+        method: "GET",
+        path: "/v1/maintenance-windows",
+        pathParams: [],
+        scope: "monitors:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: true,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "maintenance.update": {
+        method: "PATCH",
+        path: "/v1/maintenance-windows/{window_id}",
+        pathParams: ["window_id"],
+        scope: "monitors:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
     "members.change_role": {
         method: "PATCH",
         path: "/v1/members/{user_id}",
@@ -492,6 +688,20 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "monitors.backtest": {
+        method: "POST",
+        path: "/v1/monitors/backtest",
+        pathParams: [],
+        scope: "monitors:read",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: { path: "q/monitors/backtest" },
+        defaults: {},
+    },
     "monitors.create": {
         method: "POST",
         path: "/v1/monitors",
@@ -562,6 +772,20 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "monitors.occurrences": {
+        method: "GET",
+        path: "/v1/monitors/{monitor_id}/occurrences",
+        pathParams: ["monitor_id"],
+        scope: "monitors:read",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: true,
+        status: 200,
+        node: { path: "q/monitors/{monitor_id}/occurrences", list: "occurrences" },
+        defaults: {},
+    },
     "monitors.set_muted": {
         method: "PUT",
         path: "/v1/monitors/{monitor_id}/mute",
@@ -590,6 +814,20 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "monitors.signal": {
+        method: "GET",
+        path: "/v1/monitors/{monitor_id}/signal",
+        pathParams: ["monitor_id"],
+        scope: "monitors:read",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: { path: "q/monitors/{monitor_id}/signal" },
+        defaults: {},
+    },
     "monitors.update": {
         method: "PATCH",
         path: "/v1/monitors/{monitor_id}",
@@ -758,6 +996,76 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "notification_policies.delete": {
+        method: "DELETE",
+        path: "/v1/notification-policies/{policy_id}",
+        pathParams: ["policy_id"],
+        scope: "alerts:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "notification_policies.list": {
+        method: "GET",
+        path: "/v1/notification-policies",
+        pathParams: [],
+        scope: "alerts:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "notification_policies.save": {
+        method: "POST",
+        path: "/v1/notification-policies",
+        pathParams: [],
+        scope: "alerts:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "occurrences.cancel": {
+        method: "DELETE",
+        path: "/v1/occurrences/{monitor_slug}/{occurrence_id}",
+        pathParams: ["monitor_slug", "occurrence_id"],
+        scope: "monitors:write",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: { path: "w/monitors/occurrences/cancel" },
+        defaults: {},
+    },
+    "occurrences.create": {
+        method: "POST",
+        path: "/v1/occurrences",
+        pathParams: [],
+        scope: "monitors:write",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: { path: "w/monitors/occurrences" },
+        defaults: {},
+    },
     "ping_tokens.reset": {
         method: "POST",
         path: "/v1/monitors/{monitor_id}/ping-tokens/reset",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/api",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Typed client for the Belvador API (api.belvador.dev, OpenAPI 3.1): every operation by operationId, problem+json errors, retries, and node reads straight from the edge with short-lived tickets.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",