@belvador/api 0.3.0 → 0.5.0

package/README.md

@@ -56,4 +56,17 @@ try {
   `edge.belvador.dev` directly, so the data never passes the API gateway; it falls back to the gateway
   when the token may not hold a ticket.
 
+## Command line
+
+`belvador-api privacy pull` writes a project's privacy policy as the JSON the Belvador SDKs accept
+(`privacyPolicy()`, SDK 0.6.0+), so a build can ship the same rules your node applies:
+
+```sh
+BELVADOR_TOKEN=blv_svc_… npx -p @belvador/api belvador-api privacy pull --project 42 --out belvador-privacy.json
+```
+
+`--project` is the project's number (the end of its DSN). The token needs `projects:read`; it is read
+only from `BELVADOR_TOKEN` and never printed. Exit codes: 0 written, 1 refused by the API (the code is
+printed), 2 wrong usage.
+
 Node ≥ 20.10, Bun, Deno and modern browsers (any runtime with `fetch` and `AbortSignal.any`). MIT licensed.

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+// packages/api/bin/belvador-api.ts
+import { writeFileSync } from "node:fs";
+
+// packages/api/bin/run.ts
+import { BelvadorApiError, createClient, TOKEN_PATTERN } from "@belvador/api";
+var USAGE = `Usage: belvador-api privacy pull --project <numeric project id> [--out <file>] [--base-url <url>]
+
+  privacy pull   Write the project's privacy policy as JSON (for init({ privacyPolicy })).
+                 Reads BELVADOR_TOKEN: a token that can read the project (scope projects:read).
+  --out <file>   Write to a file instead of stdout.
+`;
+function isPolicy(v) {
+  if (!v || typeof v !== "object")
+    return false;
+  const p = v;
+  return typeof p.schema === "number" && typeof p.version === "number" && typeof p.mode === "string" && Array.isArray(p.rules) && Array.isArray(p.allowlist);
+}
+function flags(args) {
+  const out = new Map;
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--"))
+      return `unexpected argument ${a}`;
+    const eq = a.indexOf("=");
+    const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+    const value = eq > 0 ? a.slice(eq + 1) : args[++i];
+    if (!["project", "out", "base-url"].includes(name))
+      return `unknown option --${name}`;
+    if (value === undefined || value === "" || value.startsWith("--"))
+      return `--${name} needs a value`;
+    out.set(name, value);
+  }
+  return out;
+}
+async function run(argv, deps) {
+  const [group, command, ...rest] = argv;
+  if (group === "--help" || group === "-h" || group === "help") {
+    deps.stdout(USAGE);
+    return 0;
+  }
+  if (group !== "privacy" || command !== "pull") {
+    deps.stderr(USAGE);
+    return 2;
+  }
+  const opts = flags(rest);
+  if (typeof opts === "string") {
+    deps.stderr(`belvador-api: ${opts}
+
+${USAGE}`);
+    return 2;
+  }
+  const raw = opts.get("project");
+  if (!raw) {
+    deps.stderr(`belvador-api: --project is required
+
+${USAGE}`);
+    return 2;
+  }
+  if (!/^[1-9][0-9]{0,15}$/.test(raw)) {
+    deps.stderr(`belvador-api: --project is the project's numeric id (the number at the end of the project DSN, or GET /v1/projects)
+`);
+    return 2;
+  }
+  const project = Number(raw);
+  const token = deps.env["BELVADOR_TOKEN"]?.trim();
+  if (!token) {
+    deps.stderr(`belvador-api: BELVADOR_TOKEN is not set
+`);
+    return 2;
+  }
+  if (!TOKEN_PATTERN.test(token)) {
+    deps.stderr(`belvador-api: BELVADOR_TOKEN is not a Belvador token (blv_pat_, blv_svc_ or blv_oat_)
+`);
+    return 2;
+  }
+  let policy;
+  try {
+    const baseUrl = opts.get("base-url");
+    const client = (deps.client ?? createClient)({ token, ...baseUrl ? { baseUrl } : {}, userAgent: "belvador-api-cli" });
+    const res = await client.call("privacy.get", { project_id: project });
+    policy = res.data?.policy;
+  } catch (e) {
+    if (e instanceof BelvadorApiError) {
+      const hint = e.code === "API_SCOPE_INSUFFICIENT" && e.scope ? ` (needs ${e.scope})` : "";
+      deps.stderr(`belvador-api: ${e.code}${hint}${e.requestId ? ` · request ${e.requestId}` : ""}
+`);
+      return 1;
+    }
+    deps.stderr(`belvador-api: ${e instanceof TypeError ? e.message : "request failed"}
+`);
+    return 1;
+  }
+  if (!isPolicy(policy)) {
+    deps.stderr(`belvador-api: the API answered without a privacy policy
+`);
+    return 1;
+  }
+  const text = `${JSON.stringify({ schema: policy.schema, version: policy.version, mode: policy.mode, rules: policy.rules, allowlist: policy.allowlist }, null, 2)}
+`;
+  const out = opts.get("out");
+  if (out) {
+    deps.writeFile(out, text);
+    deps.stderr(`belvador-api: wrote privacy policy v${policy.version} (${policy.rules.length} rules) to ${out}
+`);
+  } else {
+    deps.stdout(text);
+  }
+  return 0;
+}
+
+// packages/api/bin/belvador-api.ts
+process.exitCode = await run(process.argv.slice(2), {
+  env: process.env,
+  stdout: (t) => process.stdout.write(t),
+  stderr: (t) => process.stderr.write(t),
+  writeFile: (path, text) => writeFileSync(path, text, { mode: 420 })
+});

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.3.0";
+export declare const CLIENT_VERSION = "0.5.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.3.0";
+export const CLIENT_VERSION = "0.5.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/operations.gen.d.ts

@@ -138,6 +138,34 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "coverage.get": {
+        readonly method: "GET";
+        readonly path: "/v1/coverage";
+        readonly pathParams: readonly [];
+        readonly scope: "coverage: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 "coverage.set": {
+        readonly method: "PUT";
+        readonly path: "/v1/projects/{project_id}/coverage-expectations";
+        readonly pathParams: readonly ["project_id"];
+        readonly scope: "coverage: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 "destinations.create": {
         readonly method: "POST";
         readonly path: "/v1/destinations";
@@ -744,6 +772,56 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "metrics.names": {
+        readonly method: "GET";
+        readonly path: "/v1/metrics/names";
+        readonly pathParams: readonly [];
+        readonly scope: "metrics:read";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "q/metrics/names";
+        };
+        readonly defaults: {};
+    };
+    readonly "metrics.query": {
+        readonly method: "GET";
+        readonly path: "/v1/metrics/query";
+        readonly pathParams: readonly [];
+        readonly scope: "metrics:read";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "q/metrics/query";
+            readonly window: true;
+        };
+        readonly defaults: {};
+    };
+    readonly "metrics.series": {
+        readonly method: "GET";
+        readonly path: "/v1/metrics/series";
+        readonly pathParams: readonly [];
+        readonly scope: "metrics:read";
+        readonly kind: "node";
+        readonly sensitivity: "normal";
+        readonly idempotency: "none";
+        readonly ifMatch: false;
+        readonly paged: true;
+        readonly status: 200;
+        readonly node: {
+            readonly path: "q/metrics/series";
+            readonly list: "series";
+        };
+        readonly defaults: {};
+    };
     readonly "monitors.backtest": {
         readonly method: "POST";
         readonly path: "/v1/monitors/backtest";
@@ -1175,6 +1253,34 @@ export declare const OPERATIONS: {
         readonly node: null;
         readonly defaults: {};
     };
+    readonly "privacy.get": {
+        readonly method: "GET";
+        readonly path: "/v1/projects/{project_id}/privacy";
+        readonly pathParams: readonly ["project_id"];
+        readonly scope: "projects: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 "privacy.set": {
+        readonly method: "PUT";
+        readonly path: "/v1/projects/{project_id}/privacy";
+        readonly pathParams: readonly ["project_id"];
+        readonly scope: "privacy:write";
+        readonly kind: "write";
+        readonly sensitivity: "approval";
+        readonly idempotency: "optional";
+        readonly ifMatch: false;
+        readonly paged: false;
+        readonly status: 200;
+        readonly node: null;
+        readonly defaults: {};
+    };
     readonly "project_keys.create": {
         readonly method: "POST";
         readonly path: "/v1/projects/{project_id}/keys";
@@ -1335,7 +1441,7 @@ export declare const OPERATIONS: {
         readonly pathParams: readonly ["project_id", "group"];
         readonly scope: "privacy:write";
         readonly kind: "write";
-        readonly sensitivity: "normal";
+        readonly sensitivity: "approval";
         readonly idempotency: "none";
         readonly ifMatch: false;
         readonly paged: false;
@@ -1864,7 +1970,7 @@ export interface OperationParams {
         is_enabled: boolean;
         notify_all: boolean;
         destination_ids: Array<string>;
-        monitor_kinds?: Array<"missed" | "failed" | "timeout" | "unknown" | "count" | "assertion" | "deadline" | "stalled">;
+        monitor_kinds?: Array<"missed" | "failed" | "timeout" | "unknown" | "count" | "assertion" | "deadline" | "stalled" | "metric">;
         slo_severities?: Array<"page" | "ticket">;
         policy_id?: string | null;
     };
@@ -1889,6 +1995,23 @@ export interface OperationParams {
         limit?: number;
         cursor?: string;
     };
+    /** What each app is expected to send (surface × signal × environment) against what Belvador saw: `verified`, `stale`, `problem` or `unknown`, the verified rate, and signals seen but not declared. Same numbers as the Coverage page. */
+    "coverage.get": {
+        project_id?: number;
+        environment?: string;
+    };
+    /** Replace a project's coverage expectations (one per environment × surface). `config_source: code` locks them in the app; send `ui` once to hand them back. Members and up. */
+    "coverage.set": {
+        project_id: number;
+        config_source?: "ui" | "code";
+        expectations: Array<{
+            environment: string;
+            surface: "browser" | "server" | "worker" | "job" | "edge_function" | "database" | "uptime";
+            signals: Array<"errors" | "traces" | "logs" | "metrics" | "check_ins" | "web_vitals" | "probes">;
+            stale_after_hours?: number;
+            note?: string;
+        }>;
+    };
     /** Start adding a Telegram, Slack, email, webhook, PagerDuty or incident.io destination; a person enters its secrets. */
     "destinations.create": {
         provider: "telegram" | "slack" | "email" | "webhook" | "pagerduty" | "incident_io";
@@ -1994,7 +2117,7 @@ export interface OperationParams {
     "ingest_keys.create": {
         project_id: number;
         name: string;
-        scopes: Array<"traces" | "logs" | "errors" | "monitors">;
+        scopes: Array<"traces" | "logs" | "metrics" | "errors" | "monitors">;
         environments: Array<string>;
         expires_at: string | null;
     };
@@ -2205,6 +2328,32 @@ export interface OperationParams {
     "members.remove": {
         user_id: string;
     };
+    /** The metric catalog of one project (name, type, kind, unit, series count, last seen) and the node's series and name caps with the metrics it is dropping points for. */
+    "metrics.names": {
+        project: number;
+        environment?: string;
+        q?: string;
+    };
+    /** One metric aggregated per step (avg, sum, min, max, count, rate, p50–p99) in a window of at most 7 days, optionally grouped by up to two attributes (≤ 50 groups, ≤ 10,000 points), with exemplar trace ids. */
+    "metrics.query": {
+        project: number;
+        name: string;
+        aggregation: "avg" | "sum" | "min" | "max" | "count" | "rate" | "p50" | "p90" | "p95" | "p99";
+        start?: string;
+        end?: string;
+        step?: number;
+        attrs?: string;
+        group_by?: string;
+        environment?: string;
+    };
+    /** The time series of one metric (attributes, service, environment, first and last seen), 100 per page. */
+    "metrics.series": {
+        project?: number;
+        name?: string;
+        environment?: string;
+        attrs?: string;
+        cursor?: string;
+    };
     /** 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;
@@ -2325,6 +2474,26 @@ export interface OperationParams {
             environments: Array<string>;
             severity: "critical" | "high" | "medium" | "low";
             recovery_threshold: number;
+        } | {
+            type: "metric";
+            metric_query: {
+                name: string;
+                aggregation: "avg" | "sum" | "min" | "max" | "count" | "rate" | "p50" | "p90" | "p95" | "p99";
+                filter: Array<{
+                    k: string;
+                    op: "=" | "!=" | "exists";
+                    v?: string;
+                }>;
+                group_by: 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;
         };
     }));
     /** Delete a monitor; `confirm_slug` must repeat its slug. */
@@ -2345,7 +2514,7 @@ export interface OperationParams {
         limit?: number;
         cursor?: string;
         project_id?: number;
-        type?: "job" | "count" | "assertion" | "deadline" | "progress";
+        type?: "job" | "count" | "assertion" | "deadline" | "progress" | "metric";
     };
     /** Occurrences of a deadline monitor (pending, on time, late, missed, failed, cancelled), newest due first. */
     "monitors.occurrences": {
@@ -2444,6 +2613,26 @@ export interface OperationParams {
             environments: Array<string>;
             severity: "critical" | "high" | "medium" | "low";
             recovery_threshold: number;
+        } | {
+            type: "metric";
+            metric_query: {
+                name: string;
+                aggregation: "avg" | "sum" | "min" | "max" | "count" | "rate" | "p50" | "p90" | "p95" | "p99";
+                filter: Array<{
+                    k: string;
+                    op: "=" | "!=" | "exists";
+                    v?: string;
+                }>;
+                group_by: 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;
         };
     }));
     /** Start a backup now (at most once per 10 minutes). */
@@ -2544,6 +2733,27 @@ export interface OperationParams {
         monitor_id: string;
         grace_hours: number;
     };
+    /** A project's privacy policy (mode, rules, strict allowlist, version), the built-in detectors that are off, whether user ids are pseudonymised, the last 20 versions and what the node applies and counted in the last 24 h. */
+    "privacy.get": {
+        project_id: number;
+    };
+    /** Replace a project's privacy policy (rules are applied in order on the node before anything is stored). Always needs an admin's approval; loosening (a rule removed or changed, strict off, allowlist grown) also needs their fresh authenticator code and emails owners. */
+    "privacy.set": {
+        project_id: number;
+        expected_version: number;
+        mode: "standard" | "strict";
+        rules: Array<{
+            id: string;
+            selector: string;
+            type: "pattern" | "anything" | "creditcard" | "ip" | "email" | "phone_e164";
+            method: "remove" | "replace" | "mask" | "hash";
+            pattern?: string;
+            ignore_case?: boolean;
+            replace_with?: string;
+            enabled?: boolean;
+        }>;
+        allowlist: Array<string>;
+    };
     /** Add a DSN key. */
     "project_keys.create": {
         project_id: number;

package/dist/operations.gen.js

@@ -114,6 +114,34 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "coverage.get": {
+        method: "GET",
+        path: "/v1/coverage",
+        pathParams: [],
+        scope: "coverage:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "coverage.set": {
+        method: "PUT",
+        path: "/v1/projects/{project_id}/coverage-expectations",
+        pathParams: ["project_id"],
+        scope: "coverage:write",
+        kind: "write",
+        sensitivity: "normal",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
     "destinations.create": {
         method: "POST",
         path: "/v1/destinations",
@@ -688,6 +716,48 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "metrics.names": {
+        method: "GET",
+        path: "/v1/metrics/names",
+        pathParams: [],
+        scope: "metrics:read",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: { path: "q/metrics/names" },
+        defaults: {},
+    },
+    "metrics.query": {
+        method: "GET",
+        path: "/v1/metrics/query",
+        pathParams: [],
+        scope: "metrics:read",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: { path: "q/metrics/query", window: true },
+        defaults: {},
+    },
+    "metrics.series": {
+        method: "GET",
+        path: "/v1/metrics/series",
+        pathParams: [],
+        scope: "metrics:read",
+        kind: "node",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: true,
+        status: 200,
+        node: { path: "q/metrics/series", list: "series" },
+        defaults: {},
+    },
     "monitors.backtest": {
         method: "POST",
         path: "/v1/monitors/backtest",
@@ -1108,6 +1178,34 @@ export const OPERATIONS = {
         node: null,
         defaults: {},
     },
+    "privacy.get": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/privacy",
+        pathParams: ["project_id"],
+        scope: "projects:read",
+        kind: "read",
+        sensitivity: "normal",
+        idempotency: "none",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
+    "privacy.set": {
+        method: "PUT",
+        path: "/v1/projects/{project_id}/privacy",
+        pathParams: ["project_id"],
+        scope: "privacy:write",
+        kind: "write",
+        sensitivity: "approval",
+        idempotency: "optional",
+        ifMatch: false,
+        paged: false,
+        status: 200,
+        node: null,
+        defaults: {},
+    },
     "project_keys.create": {
         method: "POST",
         path: "/v1/projects/{project_id}/keys",
@@ -1268,7 +1366,7 @@ export const OPERATIONS = {
         pathParams: ["project_id", "group"],
         scope: "privacy:write",
         kind: "write",
-        sensitivity: "normal",
+        sensitivity: "approval",
         idempotency: "none",
         ifMatch: false,
         paged: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/api",
-  "version": "0.3.0",
+  "version": "0.5.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)",
@@ -15,6 +15,9 @@
   ],
   "type": "module",
   "sideEffects": false,
+  "bin": {
+    "belvador-api": "dist/cli.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {