@belvador/api 0.1.0 → 0.2.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.2.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.2.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}$/;

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/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";
@@ -1560,6 +1574,10 @@ 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;

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/api",
-  "version": "0.1.0",
+  "version": "0.2.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)",