@belvador/api 0.3.0 → 0.4.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.4.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.4.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";
@@ -1175,6 +1203,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 +1391,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;
@@ -1889,6 +1945,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";
@@ -2544,6 +2617,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",
@@ -1108,6 +1136,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 +1324,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.4.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": {