@nasebanal/cli 0.2.0 → 0.3.0

package/README.md

@@ -32,16 +32,13 @@ small summary (counts, coverage-free metrics, the first failures, and for JUnit
 the per-test cases) and reports it to a NASEBANAL Assurance project. The same line works in a pipeline and on a
 laptop; in CI it needs only a token:
 
-Only these tool / kind pairs are accepted; anything else is refused before
-anything is read or sent (the API enforces the same list):
-
-| `--kind` | `--tool` | Report format |
-|---|---|---|
-| `unit` | `vitest`, `pytest` | JUnit XML |
-| `e2e` | `playwright` | JUnit XML |
-| `contract` | `specmatic` | JUnit XML |
-| `security` | `zap` | JUnit XML |
-| `load` | `locust` | Locust CSV |
+The **kind** is one of a fixed set of perspectives (`unit`, `e2e`, `contract`,
+`security`, `load`); the **tool** is a free label (`vitest`, `pytest`, `playwright`,
+`specmatic`, `zap`, `locust`, or `trivy`, `k6`, `cypress`...). What a result
+means is carried by its kind and its numbers, so a scanner or runner can be swapped
+without a change in Assurance. The CLI reads **JUnit XML** (any tool) and
+**Locust CSV**; for a tool that writes something else, convert it to JUnit or give the
+numbers with `--metric` (for a scanner: `critical`, `high`, `medium`, `low`, `info`).
 
 ```bash
 export NB_TOKEN=nbpat_…        # a PAT or service-account token (no browser needed)
@@ -50,6 +47,17 @@ export NB_TOKEN=nbpat_…        # a PAT or service-account token (no browser ne
 nb assurance report upload --file report/junit.xml --kind unit --tool pytest
 nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --suite web
 
+# Specmatic: the JUnit XML, plus its HTML report for the API coverage (coverage_pct = operations exercised / operations in the spec)
+nb assurance report upload --file specmatic/junit/TEST-junit-jupiter.xml --kind contract --tool specmatic \
+  --coverage-report specmatic/report/test/html/index.html
+
+# One repository, several API versions: label the result (the version is part of the suite's identity, so v1 and v2 of the same name sit side by side)
+nb assurance report upload --file specmatic/v2/junit.xml --kind contract --tool specmatic --api-version v2
+# unit tests hold for every version: leave --api-version out
+
+# Extra numbers for the suite (repeatable), e.g. ZAP's findings by severity - what the Assurance security gate reads
+nb assurance report upload --file zap/report/baseline-junit.xml --kind security --tool zap --metric high=0 --metric medium=3 --metric low=2
+
 # Locust (--csv <prefix>): the *_stats.csv, with its *_failures / *_exceptions / *_stats_history siblings
 nb assurance report upload --dir locust/logs/20261001_090000
 ```
@@ -108,27 +116,67 @@ release bundles a fixed set of API contract versions, recorded in
 ### Releasing (maintainers)
 
 Published to npmjs.org through npm **trusted publishing** (OIDC): no npm token is
-stored anywhere. The `Release` workflow (`.github/workflows/release.yml`) is
-registered as this package's Trusted Publisher on npmjs.com (repo
-`nasebanal/nb-cli`, workflow `release.yml`, no environment).
-
-1. Bump `version` in `package.json` (PR to `main`, squash-merge). If the pinned
-   contracts changed, update `spec-versions.json` in the same PR — the specs host
-   serves only the latest version, so a stale pin fails `sync-specs` with a 404.
-   Check https://api-specs.nasebanal.com/specs/released.json
-2. Tag the merge commit: `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag must
-   equal `package.json`'s version or the workflow fails.
-3. The workflow type-checks, tests and runs `npm publish --provenance`.
+stored anywhere, and none is needed to run the release script - what gates a release is
+**write access to this repository** (the script pushes a branch and a tag; the `Release`
+workflow then publishes, and npm accepts that only from this repo's `release.yml`). It does
+not work from a fork.
+
+Two commands, split by the PR merge (which stays yours; the script never merges):
+
+```bash
+bin/release.sh prepare 0.3.0   # before the merge: checks, version bump, tests, opens the release PR
+# ... review and merge the PR ...
+git checkout main && git pull
+bin/release.sh publish         # after the merge: tags v0.3.0 (asks first), waits for the workflow, checks npm
+```
+
+Add `--dry-run` to either to do every check and print what it would do, writing nothing.
+
+What it checks, and why:
+
+- **Pinned contracts equal `released.json`.** The specs host serves only the latest
+  version, so a stale `spec-versions.json` fails `sync-specs` with a 404 (it happened for
+  `account` 1.4.0 -> 1.5.0). `prepare` stops and lists the differences;
+  `prepare <version> --sync-pins` adopts the released versions in the release PR.
+  Check https://api-specs.nasebanal.com/specs/released.json
+- **Tag equals `package.json`'s version**, or the workflow fails.
+- **The version is newer than `main`'s and not on npm yet**, and the tag does not exist.
+- If the tag is pushed but the version is not on npm (the workflow failed), `publish` says
+  so and prints the `gh run rerun <id> --failed` to carry on - **do not tag again**.
+
+By hand (what the script does): bump `version` in `package.json` and `package-lock.json`
+(PR to `main`, squash-merge), tag the merge commit (`git tag vX.Y.Z && git push origin vX.Y.Z`),
+and the workflow type-checks, tests and runs `npm publish --provenance`.
+
+#### One-time setup: the Trusted Publisher on npmjs.com
+
+Trusted publishing must be switched on by hand, once per package, by a maintainer of
+`@nasebanal/cli` (npm only allows it for a package that already exists, so the first version,
+0.1.0, was published by hand). On https://www.npmjs.com/package/@nasebanal/cli/access ->
+**Trusted Publisher** -> **GitHub Actions**:
+
+| Field | Value |
+|---|---|
+| Organization or user | `nasebanal` |
+| Repository | `nb-cli` |
+| Workflow filename | `release.yml` (the file name only, exact case) |
+| Environment name | empty (the workflow uses none) |
+| Allowed actions | **tick "Allow `npm publish`"**; leave "Allow `npm dist-tag`" unticked |
+
+Without that tick the publish fails with `npm error 404 ... could not be found or you do not
+have permission` on the `PUT` - npm answers 404 for "not allowed", which reads like a missing
+package. (This is how the first run of the workflow, for 0.2.0, failed: the setup was not done.)
 
 Notes:
 
 - A manual `npm publish` needs `--@nasebanal:registry=https://registry.npmjs.org/`
   if your `~/.npmrc` maps the `@nasebanal` scope to GitHub Packages (that mapping
   outranks `publishConfig.registry`; `publishConfig` also pins the scoped key as a
-  safeguard). npm also requires a passkey (WebAuthn) 2FA for interactive publishes.
+  safeguard). npm also requires a passkey (WebAuthn) 2FA for interactive publishes. The
+  same override is needed for `npm view @nasebanal/cli` against the public registry.
 - A freshly published version can 404 on the package document for a few minutes
   while npm's cache catches up; `npm view` with `--prefer-online` or a retry is
-  enough.
+  enough (the script retries for you).
 
 ### From source (contributors)
 

package/dist/reports/specmatic.js

@@ -0,0 +1,69 @@
+/**
+ * Specmatic's API coverage -> the `coverage_pct` metric of a `contract` suite.
+ *
+ * `specmatic test` writes JUnit XML (the pass/fail counts) and an HTML report. The coverage - how many of
+ * the spec's operations a test actually exercised - is only in that report, as the JSON the page renders
+ * from (`const report = {...}`, a CTRF-style document: `results.summary.extra.executionDetails[]` with a
+ * `coverageMetrics` per spec). This reads the number out of either that HTML file or a plain JSON copy of
+ * the same document, so the spec-derived coverage reaches Assurance without the spec itself being uploaded.
+ *
+ * The HTML embedding is Specmatic's own, not a documented interface: when it changes the parse fails with
+ * a message naming the file, and the upload (without coverage) is still one flag away.
+ */
+/** The end index (exclusive) of the JSON object that starts at `start`, honouring strings and escapes. */
+function objectEnd(text, start) {
+    let depth = 0;
+    let inString = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            if (c === "\\")
+                i++;
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"')
+            inString = true;
+        else if (c === "{")
+            depth++;
+        else if (c === "}" && --depth === 0)
+            return i + 1;
+    }
+    throw new Error("unterminated JSON object");
+}
+function reportJson(text) {
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith("{"))
+        return JSON.parse(trimmed);
+    const marker = "const report = ";
+    const at = text.indexOf(marker);
+    if (at < 0)
+        throw new Error("no embedded report found");
+    const start = at + marker.length;
+    return JSON.parse(text.slice(start, objectEnd(text, start)));
+}
+export function parseSpecmaticCoverage(text) {
+    let doc;
+    try {
+        doc = reportJson(text);
+    }
+    catch (err) {
+        throw new Error(`Cannot read the Specmatic report (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const details = doc?.results?.summary?.extra?.executionDetails;
+    if (!Array.isArray(details) || details.length === 0) {
+        throw new Error("The Specmatic report has no executionDetails (was it written by `specmatic test`?)");
+    }
+    let covered = 0;
+    let total = 0;
+    for (const d of details) {
+        const m = d.coverageMetrics;
+        if (!m)
+            continue;
+        covered += m.coveredOperations ?? 0;
+        total += m.totalOperationsWithFilters ?? m.totalOperations ?? 0;
+    }
+    if (total <= 0)
+        throw new Error("The Specmatic report lists no operations to cover");
+    return { coverage_pct: Math.round((covered / total) * 1000) / 10, covered, total };
+}

package/dist/reports/upload.js

@@ -21,37 +21,61 @@ import { printJson } from "../output.js";
 import { detectCi } from "./ci.js";
 import { parseJunit } from "./junit.js";
 import { summariseLocust } from "./locust.js";
+import { parseSpecmaticCoverage } from "./specmatic.js";
 export const SUITE_KINDS = ["unit", "e2e", "load", "contract", "security"];
 /**
- * The tools Assurance accepts, per kind of suite. The CLI filters here, on the CI
- * runner, so only reports that match are ever sent; the API enforces the same list
- * (nb-assurance-api `ALLOWED_TOOLS`) because the CLI is not the only possible client.
- * Keep the two in step with the `tool` enum in nb-api-specs' assurance package.
+ * The tool is a label (nb-assurance-api `TOOL_PATTERN`): what a result means is carried by its kind and its
+ * numbers, so any scanner or runner can be reported without a change here, as long as its report is
+ * JUnit XML (or the numbers are given with --metric). Only the formats this CLI can read matter.
  */
-export const ALLOWED_TOOLS = {
-    unit: ["vitest", "pytest"],
-    e2e: ["playwright"],
-    contract: ["specmatic"],
-    security: ["zap"],
-    load: ["locust"],
-};
-/** Tools whose report is not JUnit XML. Every other allowed tool writes JUnit. */
+const TOOL_PATTERN = /^[a-z0-9][a-z0-9._-]{0,49}$/;
+/** Tools whose report is not JUnit XML; every other tool is read as JUnit. */
 const NON_JUNIT_TOOLS = { locust: "locust" };
 /**
  * Check a kind / tool / format combination before anything is parsed or sent.
- * Returns the normalised (lower-case) tool name; throws a message naming what is supported.
+ * Returns the normalised (lower-case) tool label; throws a message naming what is wrong.
  */
 export function checkSuite(kind, tool, format) {
     const name = tool.trim().toLowerCase();
-    if (!ALLOWED_TOOLS[kind].includes(name)) {
-        throw new Error(`Tool '${tool}' is not supported for kind '${kind}'. Supported: ${ALLOWED_TOOLS[kind].join(", ")}`);
+    if (!TOOL_PATTERN.test(name)) {
+        throw new Error(`Tool '${tool}' is not a label: use lower-case letters, digits, '.', '_' and '-' (up to 50), e.g. vitest or trivy`);
     }
     const expected = NON_JUNIT_TOOLS[name] ?? "junit";
     if (format !== expected) {
         throw new Error(`Tool '${name}' reports in ${expected} format, but --format is ${format}`);
     }
+    if (kind === "load" && name !== "locust" && format !== "junit")
+        throw new Error("Only locust reports are read as CSV");
     return name;
 }
+/** The same label rule as the API (`utils/apiVersion.ts` in nb-assurance-api): checked here so a typo fails before anything is sent. */
+const API_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+const METRIC_KEY = /^[a-z][a-z0-9_]{0,39}$/;
+const MAX_METRICS = 20;
+/** `--metric high=0 --metric medium=3`: extra numbers for the suite (the API keeps at most 20). */
+export function parseMetrics(pairs) {
+    const out = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        const key = eq < 0 ? pair : pair.slice(0, eq).trim();
+        const raw = eq < 0 ? "" : pair.slice(eq + 1).trim();
+        const value = Number(raw);
+        if (!METRIC_KEY.test(key) || raw === "" || !Number.isFinite(value)) {
+            throw new Error(`--metric '${pair}' must be <key>=<number> with a snake_case key (e.g. high=0)`);
+        }
+        out[key] = value;
+    }
+    if (Object.keys(out).length > MAX_METRICS)
+        throw new Error(`At most ${MAX_METRICS} --metric values per suite`);
+    return out;
+}
+export function checkApiVersion(label) {
+    const v = label.trim();
+    if (!API_VERSION_PATTERN.test(v)) {
+        throw new Error(`--api-version '${label}' is not a version label: use letters, digits, '.', '_' and '-' (up to 32), e.g. v1 or 2026-10`);
+    }
+    return v;
+}
 const MAX_FAILURES = 20;
 /** Per-test cases: the API accepts this many (MAX_CASES), each message up to 2000 characters. */
 export const MAX_CASES = 5000;
@@ -207,10 +231,13 @@ export function buildReportUploadCommand() {
         .description("Report a test result file (JUnit XML or Locust CSV) to an Assurance project")
         .option("--file <path>", "the report file (JUnit XML, or Locust *_stats.csv)")
         .option("--dir <dir>", "a Locust output directory (uses its *_stats.csv)")
+        .option("--coverage-report <path>", "specmatic: its report (the HTML or a JSON copy); adds the API coverage as the coverage_pct metric")
         .option("--format <format>", "junit | locust (default: from the file name)")
         .option("--kind <kind>", `what the suite proves: ${SUITE_KINDS.join(" | ")} (locust: load)`)
-        .option("--tool <name>", "the producing tool, e.g. vitest, pytest, playwright, specmatic (locust: locust)")
+        .option("--tool <label>", "the producing tool, a free label, e.g. vitest, pytest, playwright, specmatic, zap, trivy (locust: locust)")
         .option("--suite <name>", "tells apart several suites of one kind in a run (e.g. api, web)")
+        .option("--metric <key=value>", "an extra number for the suite, repeatable (e.g. --metric high=0 --metric medium=3; for security: critical, high, medium, low, info)", (v, all = []) => [...all, v])
+        .option("--api-version <label>", "the API version the result is for (e.g. v1, v2), part of the suite's identity next to its kind and name; leave it out for results that hold for every version, such as unit tests")
         .option("--project <name>", "project name (CI: the repository); found, or created if missing")
         .option("--repo <repo>", "repository recorded on a newly created project (CI: detected)")
         .option("--run-key <key>", "identity of the pipeline run (CI: detected); all jobs of a run share it")
@@ -240,6 +267,7 @@ export function buildReportUploadCommand() {
         const maxFailRatio = Number(ratioRaw);
         if (!Number.isFinite(maxFailRatio) || maxFailRatio < 0 || maxFailRatio > 1)
             fail("--max-fail-ratio must be a number between 0 and 1");
+        const apiVersion = opts.apiVersion === undefined ? undefined : checkApiVersion(opts.apiVersion);
         const parsed = parseReport({
             format,
             kind,
@@ -249,6 +277,25 @@ export function buildReportUploadCommand() {
             maxFailRatio,
             file,
         });
+        if (opts.coverageReport !== undefined) {
+            if (kind !== "contract" || checkedTool !== "specmatic")
+                fail("--coverage-report is only for --kind contract --tool specmatic");
+            if (!existsSync(opts.coverageReport))
+                fail(`File not found: ${opts.coverageReport}`);
+            const cov = parseSpecmaticCoverage(readFileSync(opts.coverageReport, "utf8"));
+            parsed.suite.metrics = { ...parsed.suite.metrics, coverage_pct: cov.coverage_pct };
+            parsed.note += `, API coverage ${cov.coverage_pct}% (${cov.covered}/${cov.total} operations)`;
+        }
+        if (apiVersion !== undefined)
+            parsed.suite.api_version = apiVersion;
+        if (opts.metric !== undefined && opts.metric.length > 0) {
+            const extra = parseMetrics(opts.metric);
+            const merged = { ...parsed.suite.metrics, ...extra };
+            if (Object.keys(merged).length > MAX_METRICS)
+                fail(`At most ${MAX_METRICS} metrics per suite`);
+            parsed.suite.metrics = merged;
+            parsed.note += `, metrics ${Object.entries(extra).map(([k, v]) => `${k}=${v}`).join(" ")}`;
+        }
         const ci = detectCi(process.env);
         const runKey = opts.runKey ?? ci.runKey ?? fail("Cannot determine the run key; pass --run-key");
         const project = opts.project ?? ci.project ?? fail("Cannot determine the project name; pass --project <name>");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nasebanal/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "gcloud-style command-line interface for NASEBANAL APIs, generated from nb-api-specs OpenAPI contracts.",
   "license": "MIT",
   "type": "module",

package/specs/account.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: NASEBANAL Account API
   description: Centralized user and billing management API for NASEBANAL applications. Manages user profiles, per-service subscriptions, Stripe billing, and Personal Access Tokens (PAT).
-  version: 1.5.0
+  version: 1.5.1
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com
@@ -149,7 +149,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -171,7 +178,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: array
                     items:
@@ -197,7 +211,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     $ref: "#/components/schemas/ServiceSubscription"
         "401":
@@ -217,7 +238,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -247,7 +275,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     allOf:
                       - $ref: "#/components/schemas/ApiToken"
@@ -278,7 +313,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -319,7 +361,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     $ref: "#/components/schemas/NotificationInbox"
         "401":
@@ -337,7 +386,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -366,7 +422,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -394,7 +457,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -427,7 +497,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -455,7 +532,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -495,7 +579,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     $ref: "#/components/schemas/ServiceAccount"
         "401":
@@ -531,7 +622,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     $ref: "#/components/schemas/ServiceAccount"
         "401":
@@ -563,7 +661,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -600,7 +705,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -645,7 +757,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     allOf:
                       - $ref: "#/components/schemas/ApiToken"
@@ -689,7 +808,14 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -761,7 +887,14 @@ components:
           format: date-time
     UserResponse:
       type: object
+      required:
+        - success
+        - data
       properties:
+        success:
+          type: boolean
+          enum:
+            - true
         data:
           $ref: "#/components/schemas/User"
     UpdateProfileInput:

package/specs/recorder.yaml

@@ -30,7 +30,7 @@ info:
 
     Publicly shared graphs can be embedded in external sites (blogs, portfolios, etc.) via iframe without authentication.
 
-    **Endpoint:** `GET /shared/{lang}/{id}/embed`
+    **Endpoint:** `GET https://growth.nasebanal.com/{lang}/recorder/shared/{id}/embed` (served by NASEBANAL Growth, not by this API)
 
     | Parameter | Type | Required | Description |
     |-----------|------|----------|-------------|
@@ -43,11 +43,11 @@ info:
 
     **iframe example:**
     ```html
-    <iframe src=\"https://recorder.nasebanal.com/shared/ja/{id}/embed\" width=\"100%\" height=\"500\" frameborder=\"0\"></iframe>
+    <iframe src=\"https://growth.nasebanal.com/ja/recorder/shared/{id}/embed\" width=\"100%\" height=\"500\" frameborder=\"0\"></iframe>
     ```
 
     **Note:** The embed displays a snapshot of the data at the time the SNS share was created. To update the data, recreate the SNS share.
-  version: 1.5.0
+  version: 1.7.0
   license:
     name: MIT
 servers:
@@ -124,9 +124,19 @@ paths:
       parameters:
         - name: name
           in: query
-          description: Filter by record name
+          description: "Filter by record name. A name is unique only per owner: a tag shared with you can have the same name as one of your own, and this then matches both. Use `tag_id` to pick exactly one tag."
           schema:
             type: string
+        - name: tag_id
+          in: query
+          description: Filter by tag id; repeat the parameter for several tags. An id names exactly one tag, so unlike `name` it cannot mix in a same-named tag of another owner. When `tag_id` is given, `name` is ignored. An id of a tag you cannot read (neither yours nor shared with you) matches nothing.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: integer
+              minimum: 1
         - name: start_date
           in: query
           description: Filter by start date (ISO 8601)
@@ -1450,17 +1460,22 @@ paths:
   /records/stats:
     get:
       summary: Get record statistics
-      description: Get aggregated statistics for records with a specific name
+      description: Get aggregated statistics for the records of one tag, picked by `name` or, unambiguously, by `tag_id`. Send one of the two.
       operationId: getRecordStats
       tags:
         - Statistics
       parameters:
         - name: name
           in: query
-          required: true
-          description: Record name to get statistics for
+          description: Record name to get statistics for. A name is unique only per owner, so a tag shared with you can share it with one of your own; prefer `tag_id`.
           schema:
             type: string
+        - name: tag_id
+          in: query
+          description: Id of the tag to get statistics for. When given, `name` is ignored. An id of a tag you cannot read matches nothing.
+          schema:
+            type: integer
+            minimum: 1
       responses:
         "200":
           description: Statistics for the specified record name
@@ -2184,6 +2199,45 @@ components:
             - imported
             - created
             - updated
+    SeriesKind:
+      type: string
+      enum:
+        - raw
+        - diff
+        - diff_pct
+        - sum
+        - bmi
+        - annual_income
+      description: "Stable code of a derived series — not the display suffix (`/Diff` etc.). `diff` difference from the previous record, `diff_pct` percent change from the previous record, `sum` running total, `bmi` BMI (body-weight category), `annual_income` annual income (currency category). The raw tag is `raw`: it is the default on the referencing side and never appears in a `derived_series` list."
+    DerivedSeries:
+      type: object
+      description: "A series derived from a tag. No row of its own: it is derived from the tag's settings (`derived_config`, `category`). Identified by the source tag's `id` plus `kind` — no name in it, so a rename cannot break a reference."
+      properties:
+        kind:
+          $ref: "#/components/schemas/SeriesKind"
+        label:
+          type: string
+          description: Display name (e.g. `Body Weight/BMI`). Not an identifier.
+        unit:
+          type: string
+          nullable: true
+        data_type:
+          type: string
+          enum:
+            - decimal
+            - integer
+            - time
+        chart_type:
+          type: string
+          enum:
+            - line
+            - smooth
+            - step
+      required:
+        - kind
+        - label
+        - data_type
+        - chart_type
     Tag:
       type: object
       properties:
@@ -2213,6 +2267,11 @@ components:
         is_hidden:
           type: integer
           description: 0 = visible, 1 = hidden
+        derived_series:
+          type: array
+          description: Derived series this tag can produce. Excludes the raw series (`raw`).
+          items:
+            $ref: "#/components/schemas/DerivedSeries"
         data_type_options:
           type: array
           description: "Which `data_type` this tag may be changed to, and why not for the rest. A change is safe exactly when no stored value changes meaning, which depends on the direction and on what is already stored — so this is server-computed rather than re-derived per client, and it carries a reason per option because the reason differs per option. A tag shared in from another user lists only its current type, not selectable: the recipient does not own the master data."
@@ -2487,6 +2546,10 @@ components:
         virtual_tag_key:
           type: string
           nullable: true
+        tag_kind:
+          allOf:
+            - $ref: "#/components/schemas/SeriesKind"
+          description: Which series of the `tag_id` tag the goal targets. Absent or `raw` means the raw tag. Successor to `virtual_tag_key`, with no name in it.
         is_hidden:
           type: integer
           description: 0 = visible, 1 = hidden
@@ -2542,6 +2605,10 @@ components:
         virtual_tag_key:
           type: string
           description: Virtual tag key
+        tag_kind:
+          allOf:
+            - $ref: "#/components/schemas/SeriesKind"
+          description: Which series of the `tag_id` tag the goal targets. Absent or `raw` means the raw tag. Successor to `virtual_tag_key`, with no name in it.
       required:
         - tag_id
         - goal_type
@@ -2569,6 +2636,10 @@ components:
           type: string
         virtual_tag_key:
           type: string
+        tag_kind:
+          allOf:
+            - $ref: "#/components/schemas/SeriesKind"
+          description: Which series of the `tag_id` tag the goal targets. Absent or `raw` means the raw tag. Successor to `virtual_tag_key`, with no name in it.
     ErrorResponse:
       type: object
       properties:

package/specs/target.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: NASEBANAL - Target API
   description: "Target API for NASEBANAL. Provides hierarchical target management: users define goals and organize them in a tree structure. Parent-child links are persisted via `targets.parent_target_id` (authoritative since migration 0017); a legacy cell-based storage layer is kept in sync best-effort for backward compatibility. Targets can be shared with other users (read/write, optionally including the subtree and linked Recorder data), and ownership of a personal target subtree can be transferred to a recipient via an email-approved migration flow. Supports user authentication via Auth0 JWT and Personal Access Tokens (PAT)."
-  version: 1.4.1
+  version: 1.5.0
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com
@@ -1019,7 +1019,11 @@ components:
         recorder_tag:
           type: string
           nullable: true
-          description: Optional tag linking to the Recorder app
+          description: Name of the linked Recorder tag, or a derived series key such as `Body Weight/BMI~` (a name, not a tag row, so it has no id). Kept alongside `recorder_tag_id` for derived keys and for clients that predate it.
+        recorder_tag_id:
+          type: integer
+          nullable: true
+          description: Id of the linked Recorder tag, for a real tag (never for a derived series key). Unlike the name it stays valid when the tag is renamed or its ownership is transferred, and it tells apart same-named tags of different owners. NULL for a target linked only by name; clients prefer the id when it is set and fall back to `recorder_tag`.
         recorder_goal_id:
           type: integer
           nullable: true
@@ -1362,7 +1366,11 @@ components:
         recorder_tag:
           type: string
           nullable: true
-          description: Tag to link with Recorder app
+          description: Tag to link with Recorder app, by name. Send the name together with `recorder_tag_id` for a real tag; for a derived series key (`Body Weight/BMI~`) this is the only field.
+        recorder_tag_id:
+          type: integer
+          nullable: true
+          description: Id of the Recorder tag to link, for a real tag. Send it together with `recorder_tag`; send `null` for both to unlink.
         recorder_goal_id:
           type: integer
           nullable: true