@maschinenlesbar.org/marktstammdatenregister-cli 0.0.8 → 0.2.0

package/dist/src/client/client.d.ts

@@ -1,11 +1,21 @@
 import { type EngineOptions } from "./engine.js";
-import type { FilterColumn, UnitCategory, UnitPage, UnitQuery } from "./types.js";
+import type { CountQuery, FilterColumn, UnitCategory, UnitPage, UnitQuery } from "./types.js";
 /** Largest `page` the client (and the CLI's `--page`) accepts. */
 export declare const MAX_PAGE = 1000000;
 /** Largest `pageSize` the client (and the CLI's `--page-size`) accepts. */
 export declare const MAX_PAGE_SIZE = 5000;
-/** Options for the MaStR client (engine options only — the API needs no auth). */
-export type MastrClientOptions = EngineOptions;
+/** Options for the MaStR client: the engine options (the API needs no auth) plus one of its own. */
+export interface MastrClientOptions extends EngineOptions {
+    /**
+     * Send filters without checking their FilterNames and dropdown codes against the
+     * category's columns, and so without the one `filterColumns()` request per category that
+     * check costs. Default `false`: a name the category doesn't have, or a code its dropdown
+     * doesn't list, is a `MastrValidationError`, because the register ignores an unknown name
+     * (the unfiltered set) and answers an unknown code with 0 rows. The shape check and the
+     * name normalisation apply either way.
+     */
+    allowUnknownFilters?: boolean;
+}
 /**
  * Parse a MaStR Microsoft-AJAX date string (`"/Date(1548979200000)/"`) into a Date.
  * The offset form `"/Date(1548979200000+0100)/"` is accepted too; its milliseconds
@@ -19,17 +29,47 @@ export declare function parseMsDate(value: string): Date | null;
  */
 export declare function isoifyDates<T>(value: T): T;
 export declare class MastrClient {
+    #private;
     private readonly engine;
     constructor(options?: MastrClientOptions);
+    /** The category's filter columns, fetched on first use and kept; a failed fetch is not kept. */
+    private columnsOf;
+    /**
+     * The filter as it is sent: FilterNames normalised (`normalizeFilter`), the shape checked
+     * (`filterProblem`), then — unless `allowUnknownFilters` — the names and dropdown codes
+     * checked against the category's columns (`resolveFilter`, one cached `filterColumns()`
+     * request), all before the unit request.
+     */
+    private checkedFilter;
     /**
      * Fetch one page of units for a category. Sends the full Kendo param set —
      * `sort`, `page`, `pageSize`, `group`, `filter` — always, because the server
      * rejects a request with `group`/`filter` missing ("Die Anfrage ist Null.").
-     * An unknown category, a `page` outside 1..`MAX_PAGE`, a `pageSize` outside
-     * 1..`MAX_PAGE_SIZE` or a filter the register would misread (e.g. `~or~`, see
-     * {@link validateFilter}) is rejected with a `MastrValidationError` before any request.
+     * An unknown category or query key, a `page` outside 1..`MAX_PAGE`, a `pageSize`
+     * outside 1..`MAX_PAGE_SIZE`, a blank `sort` ({@link sortProblem}) or a filter the
+     * register would misread (e.g. `~or~`, see {@link validateFilter}) is rejected with a
+     * `MastrValidationError` before any request. A filter's FilterNames and `eq`/`neq`
+     * dropdown codes are then checked against the category's columns (one cached
+     * `filterColumns()` request, skipped with `allowUnknownFilters`) before the unit request;
+     * the filter is sent normalised (see `normalizeFilter`, `resolveFilter`).
      */
     units(category: UnitCategory, query?: UnitQuery): Promise<UnitPage>;
+    /**
+     * The register's second error envelope, `{"Error":true,"Message":…,"Type":"danger"}`
+     * (HTTP 200), as a MastrApiError: its answer to a filter value it can't read. It used to
+     * surface as "Unexpected response shape … expected a numeric Total", which reads like a
+     * broken server or client and doesn't say what to fix.
+     */
+    private registerRejected;
+    /**
+     * The number of units in a category that match `filter` (all units without one).
+     * Fetches a single row (`page=1`, `pageSize=1`) and returns the envelope's
+     * `Total`, which counts every match regardless of the page. `sort` is forwarded:
+     * an unknown sort key makes the register answer 0. Paging options are refused
+     * (`countQueryProblem`), as are the inputs `units()` refuses, all with a
+     * `MastrValidationError` before any request.
+     */
+    count(category: UnitCategory, query?: CountQuery): Promise<number>;
     /** Electricity-generation units (`Stromerzeugung`). */
     stromerzeugung(query?: UnitQuery): Promise<UnitPage>;
     /** Electricity-consumption units (`Stromverbrauch`). */
@@ -45,4 +85,3 @@ export declare class MastrClient {
      */
     filterColumns(category: UnitCategory): Promise<FilterColumn[]>;
 }
-//# sourceMappingURL=client.d.ts.map

package/dist/src/client/client.js

@@ -9,9 +9,10 @@
 //   const c = new MastrClient();
 //   const page = await c.stromerzeugung({ pageSize: 10, filter: "Energieträger~eq~'2495'" });
 //   page.total; // total solar units
-import { RequestEngine, describeMastrErrors } from "./engine.js";
+import { RequestEngine, describeMastrErrors, optionsObject } from "./engine.js";
 import { MastrApiError, MastrParseError, MastrValidationError } from "./errors.js";
-import { validateFilter } from "./filter.js";
+import { normalizeFilter, resolveFilter, validateFilter } from "./filter.js";
+import { COUNT_IGNORED_KEYS, assertValid, countQueryProblem, sortProblem } from "./validate.js";
 const SERVICE = "/Einheit/EinheitJson";
 /** Map a category to the PascalCase suffix used in the endpoint names. */
 const CATEGORY_SUFFIX = {
@@ -41,6 +42,43 @@ function checkPaging(name, value, max) {
         throw new MastrValidationError(`Invalid ${name}: expected an integer from 1 to ${max}, got ${typeof value === "string" ? JSON.stringify(value) : String(value)}.`);
     }
 }
+/** A query as given (null counts as none), or a MastrValidationError for a non-object. */
+function queryObject(query) {
+    if (query === undefined || query === null)
+        return {};
+    if (typeof query !== "object" || Array.isArray(query)) {
+        throw new MastrValidationError(`Invalid query: expected an object, got ${Array.isArray(query) ? "an array" : `a ${typeof query}`}.`);
+    }
+    return query;
+}
+/** The UnitQuery keys; any other key is refused (a misspelled `filtr` was ignored: the unfiltered set). */
+const UNIT_QUERY_KEYS = ["page", "pageSize", "sort", "filter"];
+/** The CountQuery keys (`page`/`pageSize` get their own message, see countQueryProblem). */
+const COUNT_QUERY_KEYS = ["sort", "filter", ...COUNT_IGNORED_KEYS];
+/**
+ * Throw for a query key that isn't one of `allowed`. A JavaScript caller's typo (`filtr`,
+ * `Filter`) or a key from parsed JSON (`__proto__`) was ignored silently, and the call
+ * answered with the whole unfiltered register.
+ */
+function assertQueryKeys(query, allowed) {
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || allowed.includes(key))
+            continue;
+        const lower = key.toLowerCase();
+        const hint = allowed.find((name) => name.toLowerCase() === lower || editHint(lower, name.toLowerCase()));
+        throw new MastrValidationError(`Invalid query: unknown key ${JSON.stringify(key)}` +
+            (hint === undefined ? `; the keys are ${allowed.join(", ")}.` : ` (did you mean ${hint}?).`));
+    }
+}
+/** True when `a` and `b` differ by one inserted, dropped or changed character. */
+function editHint(a, b) {
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    let i = 0;
+    while (i < a.length && a[i] === b[i])
+        i++;
+    return a.slice(i + 1) === b.slice(i + 1) || a.slice(i + 1) === b.slice(i) || a.slice(i) === b.slice(i + 1);
+}
 /**
  * Parse a MaStR Microsoft-AJAX date string (`"/Date(1548979200000)/"`) into a Date.
  * The offset form `"/Date(1548979200000+0100)/"` is accepted too; its milliseconds
@@ -90,29 +128,69 @@ function shapeError(path, expected) {
 }
 export class MastrClient {
     engine;
+    #allowUnknownFilters;
+    /** Each category's filter columns, fetched once per client for the filter check. */
+    #columns = new Map();
     constructor(options = {}) {
-        this.engine = new RequestEngine(options);
+        const { allowUnknownFilters, ...engineOptions } = optionsObject(options);
+        if (allowUnknownFilters !== undefined && typeof allowUnknownFilters !== "boolean") {
+            throw new MastrValidationError(`Invalid allowUnknownFilters: expected a boolean, got ${typeof allowUnknownFilters}.`);
+        }
+        this.engine = new RequestEngine(engineOptions);
+        this.#allowUnknownFilters = allowUnknownFilters === true;
+    }
+    /** The category's filter columns, fetched on first use and kept; a failed fetch is not kept. */
+    columnsOf(category) {
+        let columns = this.#columns.get(category);
+        if (columns === undefined) {
+            columns = this.filterColumns(category);
+            this.#columns.set(category, columns);
+            columns.catch(() => this.#columns.delete(category));
+        }
+        return columns;
+    }
+    /**
+     * The filter as it is sent: FilterNames normalised (`normalizeFilter`), the shape checked
+     * (`filterProblem`), then — unless `allowUnknownFilters` — the names and dropdown codes
+     * checked against the category's columns (`resolveFilter`, one cached `filterColumns()`
+     * request), all before the unit request.
+     */
+    async checkedFilter(category, spec) {
+        const filter = normalizeFilter(spec);
+        validateFilter(filter);
+        if (this.#allowUnknownFilters)
+            return filter;
+        return resolveFilter(filter, await this.columnsOf(category), category);
     }
     /**
      * Fetch one page of units for a category. Sends the full Kendo param set —
      * `sort`, `page`, `pageSize`, `group`, `filter` — always, because the server
      * rejects a request with `group`/`filter` missing ("Die Anfrage ist Null.").
-     * An unknown category, a `page` outside 1..`MAX_PAGE`, a `pageSize` outside
-     * 1..`MAX_PAGE_SIZE` or a filter the register would misread (e.g. `~or~`, see
-     * {@link validateFilter}) is rejected with a `MastrValidationError` before any request.
+     * An unknown category or query key, a `page` outside 1..`MAX_PAGE`, a `pageSize`
+     * outside 1..`MAX_PAGE_SIZE`, a blank `sort` ({@link sortProblem}) or a filter the
+     * register would misread (e.g. `~or~`, see {@link validateFilter}) is rejected with a
+     * `MastrValidationError` before any request. A filter's FilterNames and `eq`/`neq`
+     * dropdown codes are then checked against the category's columns (one cached
+     * `filterColumns()` request, skipped with `allowUnknownFilters`) before the unit request;
+     * the filter is sent normalised (see `normalizeFilter`, `resolveFilter`).
      */
     async units(category, query = {}) {
         const suffix = categorySuffix(category);
+        query = queryObject(query);
+        assertQueryKeys(query, UNIT_QUERY_KEYS);
         checkPaging("page", query.page, MAX_PAGE);
         checkPaging("pageSize", query.pageSize, MAX_PAGE_SIZE);
-        if (query.filter !== undefined)
-            validateFilter(query.filter);
+        if (query.sort !== undefined)
+            assertValid("sort", query.sort, sortProblem);
+        // The register ignores a FilterName it doesn't match exactly and answers with the
+        // unfiltered set, so the filter is normalised and checked first (checkedFilter).
+        const filter = query.filter === undefined ? undefined : await this.checkedFilter(category, query.filter);
         const params = {
             sort: query.sort ?? "",
             page: query.page ?? DEFAULT_PAGE,
             pageSize: query.pageSize ?? DEFAULT_PAGE_SIZE,
             group: "",
-            filter: query.filter ?? "",
+            filter: filter ?? "",
         };
         const path = `${SERVICE}/GetErweiterteOeffentlicheEinheit${suffix}`;
         const res = await this.engine.getJson(path, params);
@@ -126,10 +204,12 @@ export class MastrClient {
             throw new MastrApiError({
                 url: this.engine.buildUrl(path, params),
                 method: "GET",
-                body: JSON.stringify(res),
-                detail: describeMastrErrors(res["Errors"]),
+                body: this.engine.scrub(JSON.stringify(res)),
+                detail: describeMastrErrors(res["Errors"], (text) => this.engine.scrub(text)),
             });
         }
+        if (res["Error"] === true)
+            throw this.registerRejected(path, params, res);
         const total = res["Total"];
         if (typeof total !== "number" || !Number.isSafeInteger(total) || total < 0) {
             throw shapeError(path, "a numeric Total");
@@ -140,8 +220,56 @@ export class MastrClient {
             return { total, data: [] };
         if (!Array.isArray(data))
             throw shapeError(path, "a Data array");
+        // A page can't hold more rows than match, nor more than were asked for: such a reply
+        // would print rows next to `"total": 0` (and the CLI's "0 results" note), or a page
+        // larger than --page-size.
+        if (data.length > total) {
+            throw shapeError(path, `a Total of at least the ${data.length} rows on the page, got ${total}`);
+        }
+        const pageSize = query.pageSize ?? DEFAULT_PAGE_SIZE;
+        if (data.length > pageSize) {
+            throw shapeError(path, `at most ${pageSize} rows (the pageSize), got ${data.length}`);
+        }
         return { total, data: data };
     }
+    /**
+     * The register's second error envelope, `{"Error":true,"Message":…,"Type":"danger"}`
+     * (HTTP 200), as a MastrApiError: its answer to a filter value it can't read. It used to
+     * surface as "Unexpected response shape … expected a numeric Total", which reads like a
+     * broken server or client and doesn't say what to fix.
+     */
+    registerRejected(path, query, res) {
+        const message = typeof res["Message"] === "string" ? describeMastrErrors(res["Message"], (t) => this.engine.scrub(t)) : undefined;
+        return new MastrApiError({
+            url: this.engine.buildUrl(path, query),
+            method: "GET",
+            body: this.engine.scrub(JSON.stringify(res)),
+            detail: `the register rejected the request${message === undefined ? "" : ` (${message})`}. It answers so ` +
+                "to a filter value it can't read: a dropdown label instead of its code (the Value from " +
+                "`mastr filters` / filterColumns()), a decimal comma ('4999,999'; use a point), an exponent " +
+                "or text in a number column, an invalid date, a boolean other than '1'/'0', or null/nn on a " +
+                "column that isn't text",
+        });
+    }
+    /**
+     * The number of units in a category that match `filter` (all units without one).
+     * Fetches a single row (`page=1`, `pageSize=1`) and returns the envelope's
+     * `Total`, which counts every match regardless of the page. `sort` is forwarded:
+     * an unknown sort key makes the register answer 0. Paging options are refused
+     * (`countQueryProblem`), as are the inputs `units()` refuses, all with a
+     * `MastrValidationError` before any request.
+     */
+    async count(category, query = {}) {
+        query = queryObject(query);
+        assertQueryKeys(query, COUNT_QUERY_KEYS);
+        assertValid("count query", query, countQueryProblem);
+        const q = { page: 1, pageSize: 1 };
+        if (query.sort !== undefined)
+            q.sort = query.sort;
+        if (query.filter !== undefined)
+            q.filter = query.filter;
+        return (await this.units(category, q)).total;
+    }
     /** Electricity-generation units (`Stromerzeugung`). */
     stromerzeugung(query) {
         return this.units("stromerzeugung", query);
@@ -166,12 +294,14 @@ export class MastrClient {
     async filterColumns(category) {
         const path = `${SERVICE}/GetFilterColumnsErweiterteOeffentlicheEinheit${categorySuffix(category)}`;
         const res = await this.engine.getJson(path);
+        if (isObject(res) && res["Error"] === true)
+            throw this.registerRejected(path, undefined, res);
         if (isObject(res) && res["Errors"] !== undefined && res["Errors"] !== null) {
             throw new MastrApiError({
                 url: this.engine.buildUrl(path),
                 method: "GET",
-                body: JSON.stringify(res),
-                detail: describeMastrErrors(res["Errors"]),
+                body: this.engine.scrub(JSON.stringify(res)),
+                detail: describeMastrErrors(res["Errors"], (text) => this.engine.scrub(text)),
             });
         }
         if (!Array.isArray(res) || !res.every(isObject)) {
@@ -180,4 +310,3 @@ export class MastrClient {
         return res;
     }
 }
-//# sourceMappingURL=client.js.map

package/dist/src/client/engine.d.ts

@@ -7,35 +7,53 @@ export interface RawResponse {
     status: number;
 }
 export interface EngineOptions {
-    /** Base URL of the API. Defaults to the canonical marktstammdatenregister.de base. */
+    /**
+     * Base URL of the API. Defaults to the canonical marktstammdatenregister.de base.
+     * A value that breaks a rule of {@link validateBaseUrl} (blank, whitespace or
+     * control characters, not an absolute http(s) URL, a query or fragment) throws a
+     * MastrValidationError.
+     */
     baseUrl?: string;
     /** Swappable transport. Defaults to the built-in node http/https transport. */
     transport?: Transport;
-    /** Value of the User-Agent header. */
+    /**
+     * Value of the User-Agent header: not blank, Latin-1 without control characters
+     * (tab is fine), else a MastrValidationError.
+     */
     userAgent?: string;
-    /** Extra headers sent on every request. */
+    /** Extra headers sent on every request; names must be tokens, values follow the `userAgent` rule. */
     defaultHeaders?: Record<string, string>;
     /**
      * Time limit per request in milliseconds, covering the whole response body, not
-     * only idle gaps (0 disables; capped at MAX_TIMEOUT_MS, 2^31 - 1 ms).
+     * only idle gaps: an integer 0..`MAX_TIMEOUT_MS` (2^31 - 1 ms); 0 disables.
+     * Defaults to 30000.
      */
     timeoutMs?: number;
     /**
-     * Number of automatic retries for transient (429/503) responses. Each waits the
-     * response's `Retry-After` (up to `MAX_RETRY_AFTER_MS`; a longer one is not
-     * retried), or else `retryDelayMs * attempt`.
+     * Number of automatic retries for transient (429/503) responses and reset
+     * connections (`isTransientNetworkError`), an integer
+     * 0..`MAX_RETRIES` (10); defaults to 2. Each waits `retryDelayMs * attempt`, or the
+     * response's `Retry-After` when that is longer. A `Retry-After` above
+     * `MAX_RETRY_AFTER_MS` is not retried: the MastrApiError names the requested wait.
      */
     maxRetries?: number;
-    /** Base backoff between retries in milliseconds (grows linearly); used without a Retry-After. */
+    /**
+     * Base backoff between retries in milliseconds (grows linearly: `retryDelayMs * attempt`),
+     * an integer 0..`MAX_RETRY_AFTER_MS` (30 000). Defaults to 200. It is also the floor: a
+     * `Retry-After` can make a wait longer, never shorter.
+     */
     retryDelayMs?: number;
     /**
      * Hard cap on response body size in bytes (defends against memory exhaustion
-     * from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit.
+     * from a hostile/buggy endpoint), a non-negative integer. Defaults to 100 MiB;
+     * set to 0 for no limit.
      */
     maxResponseBytes?: number;
     /** Injectable sleep, primarily for deterministic tests. */
     sleep?: (ms: number) => Promise<void>;
 }
+/** Most retries `maxRetries` may ask for (each may wait up to `MAX_RETRY_AFTER_MS`). */
+export declare const MAX_RETRIES = 10;
 /**
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
  * server asks for longer, the engine does not retry at all and surfaces the error at
@@ -80,30 +98,93 @@ export declare function isBidiControl(code: number): boolean;
  * Written as a code-point filter so no raw control byte appears in this source.
  */
 export declare function sanitizeServerText(text: string): string;
+/**
+ * Longest server text (in characters) an error message keeps: a hostile or buggy body
+ * must not flood stderr or a CI log with one huge line. `MastrApiError.body` keeps the
+ * full text.
+ */
+export declare const MAX_DETAIL_LENGTH = 500;
 /**
  * Describe a Kendo `Errors` value for an error message: a string as is; otherwise
  * (a ModelState object such as `{"": {"errors": ["Invalid filter"]}}`, or an array)
  * every string found in it, sanitised, blanks and repeats dropped, joined "; ".
- * Returns `undefined` when nothing readable is left.
+ * Returns `undefined` when nothing readable is left. `clean` runs on each raw string
+ * first (the engine passes its credential scrubber).
+ */
+export declare function describeMastrErrors(errors: unknown, clean?: (text: string) => string): string | undefined;
+/**
+ * Check a base URL against every rule of {@link baseUrlProblem} — blank, whitespace
+ * or control characters, not an absolute URL, a scheme other than `http:`/`https:`,
+ * a query or fragment — and return it with trailing slashes stripped. A bad value
+ * throws a MastrValidationError (`Invalid baseUrl: <reason>`): it is a configuration
+ * error, not a transport failure. The default transport still gates the scheme per
+ * request, but the engine may be handed a custom transport that does no such check,
+ * so the configured value is checked here, on the raw string.
+ */
+export declare function validateBaseUrl(raw: string): string;
+/**
+ * Check a value bound for an HTTP header (`headerValueProblem`) and return it, or
+ * throw a MastrValidationError (`Invalid <name>: <reason>`). The engine runs it on
+ * `userAgent` and every `defaultHeaders` value before any request.
+ */
+export declare function assertHeaderValue(name: string, value: string): string;
+/**
+ * True for a failure caused by a reset or aborted connection, which the engine retries —
+ * whichever transport raised it (a Node error, fetch's TypeError with an undici cause), the
+ * code anywhere in the `cause` chain. A refused connection, a DNS failure or a timeout is
+ * not transient in that sense and is not retried.
  */
-export declare function describeMastrErrors(errors: unknown): string | undefined;
+export declare function isTransientNetworkError(err: unknown): boolean;
+/**
+ * Throw for a key that is not an option name. A JavaScript caller's typo (`timeout` for
+ * `timeoutMs`) was ignored silently and the default applied; TypeScript catches it at
+ * compile time, JavaScript does not. `extra` names options a wrapper (the client) adds.
+ */
+export declare function assertKnownOptions(options: object, extra?: readonly string[]): void;
+/** Engine options as given, or a MastrValidationError for a non-object (null counts as none). */
+export declare function optionsObject<T extends object>(options: T | null | undefined): T;
 export declare class RequestEngine {
-    private readonly baseUrl;
+    #private;
     private readonly transport;
     private readonly userAgent;
-    private readonly defaultHeaders;
     private readonly timeoutMs;
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly maxResponseBytes;
     private readonly sleep;
     constructor(options?: EngineOptions);
+    /**
+     * `text` without the base URL's credentials: server text (an error body that echoes the
+     * request URL) and transport text (fetch's "Failed to fetch <url>") can carry them. The
+     * client runs it on the `Errors` envelopes it turns into errors.
+     */
+    scrub(text: string): string;
+    /**
+     * A transport failure as the `cause` of the error the engine raises: the original when its
+     * text carries no credentials, otherwise a copy with them scrubbed (message, `code` and the
+     * cause chain kept), so logging the error with its causes can't reveal the base URL's
+     * password.
+     */
+    private scrubCause;
     /** Build a fully-qualified URL from a path and optional query parameters. */
     buildUrl(path: string, query?: QueryParams): string;
+    /**
+     * Call the transport under the overall deadline (`timeoutMs`): the request gets an
+     * AbortSignal that fires at the deadline, and the call rejects then whether the transport
+     * stops or not — a custom transport (fetch, a node:http wrapper) that ignores `timeoutMs`
+     * can't hang the caller. A synchronous throw becomes a rejection.
+     */
+    private callTransport;
     /**
      * Perform a GET with Accept negotiation and transient-error retries. Redirects
      * are NOT followed — the canonical host answers directly, so a 3xx (e.g. a bad
      * base URL bouncing to a portal page) surfaces as an error.
+     *
+     * The engine enforces the transport contract itself, so it holds for a custom
+     * transport too: `timeoutMs` (an AbortSignal deadline), `maxResponseBytes` (checked on
+     * the body it gets back), any byte-array body, `Headers`/`Map`/any-case headers. Whatever
+     * a transport throws becomes a `MastrNetworkError`, and so does a malformed response; a
+     * reset connection (`isTransientNetworkError`) is retried like a 503.
      */
     request(path: string, query?: QueryParams, accept?: string): Promise<RawResponse>;
     /**
@@ -112,6 +193,6 @@ export declare class RequestEngine {
      * `MastrParseError`, never a silent `null`.
      */
     getJson<T>(path: string, query?: QueryParams): Promise<T>;
+    /** The MastrApiError for a non-2xx answer; `note` is appended to the detail. */
     private toApiError;
 }
-//# sourceMappingURL=engine.d.ts.map