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