@maschinenlesbar.org/ckan-cli 0.0.6 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/dist/src/cli/commands/catalogue.d.ts +1 -2
  2. package/dist/src/cli/commands/catalogue.js +11 -3
  3. package/dist/src/cli/commands/portal.d.ts +0 -1
  4. package/dist/src/cli/commands/portal.js +13 -12
  5. package/dist/src/cli/index.d.ts +0 -1
  6. package/dist/src/cli/index.js +0 -1
  7. package/dist/src/cli/io.d.ts +0 -1
  8. package/dist/src/cli/io.js +0 -1
  9. package/dist/src/cli/program.d.ts +0 -1
  10. package/dist/src/cli/program.js +2 -3
  11. package/dist/src/cli/run.d.ts +0 -1
  12. package/dist/src/cli/run.js +9 -2
  13. package/dist/src/cli/shared.d.ts +10 -15
  14. package/dist/src/cli/shared.js +29 -54
  15. package/dist/src/client/client.d.ts +7 -6
  16. package/dist/src/client/client.js +38 -22
  17. package/dist/src/client/engine.d.ts +28 -6
  18. package/dist/src/client/engine.js +40 -30
  19. package/dist/src/client/errors.d.ts +7 -1
  20. package/dist/src/client/errors.js +7 -1
  21. package/dist/src/client/http.d.ts +0 -1
  22. package/dist/src/client/http.js +41 -33
  23. package/dist/src/client/index.d.ts +6 -5
  24. package/dist/src/client/index.js +4 -4
  25. package/dist/src/client/portals-list.d.ts +0 -1
  26. package/dist/src/client/portals-list.js +0 -1
  27. package/dist/src/client/portals.d.ts +35 -2
  28. package/dist/src/client/portals.js +48 -3
  29. package/dist/src/client/query.d.ts +0 -1
  30. package/dist/src/client/query.js +0 -1
  31. package/dist/src/client/types.d.ts +0 -1
  32. package/dist/src/client/types.js +0 -1
  33. package/dist/src/client/validate.d.ts +55 -0
  34. package/dist/src/client/validate.js +119 -0
  35. package/dist/src/index.d.ts +0 -1
  36. package/dist/src/index.js +0 -1
  37. package/package.json +2 -1
  38. package/dist/src/cli/commands/catalogue.d.ts.map +0 -1
  39. package/dist/src/cli/commands/catalogue.js.map +0 -1
  40. package/dist/src/cli/commands/portal.d.ts.map +0 -1
  41. package/dist/src/cli/commands/portal.js.map +0 -1
  42. package/dist/src/cli/index.d.ts.map +0 -1
  43. package/dist/src/cli/index.js.map +0 -1
  44. package/dist/src/cli/io.d.ts.map +0 -1
  45. package/dist/src/cli/io.js.map +0 -1
  46. package/dist/src/cli/program.d.ts.map +0 -1
  47. package/dist/src/cli/program.js.map +0 -1
  48. package/dist/src/cli/run.d.ts.map +0 -1
  49. package/dist/src/cli/run.js.map +0 -1
  50. package/dist/src/cli/shared.d.ts.map +0 -1
  51. package/dist/src/cli/shared.js.map +0 -1
  52. package/dist/src/client/client.d.ts.map +0 -1
  53. package/dist/src/client/client.js.map +0 -1
  54. package/dist/src/client/engine.d.ts.map +0 -1
  55. package/dist/src/client/engine.js.map +0 -1
  56. package/dist/src/client/errors.d.ts.map +0 -1
  57. package/dist/src/client/errors.js.map +0 -1
  58. package/dist/src/client/http.d.ts.map +0 -1
  59. package/dist/src/client/http.js.map +0 -1
  60. package/dist/src/client/index.d.ts.map +0 -1
  61. package/dist/src/client/index.js.map +0 -1
  62. package/dist/src/client/portals-list.d.ts.map +0 -1
  63. package/dist/src/client/portals-list.js.map +0 -1
  64. package/dist/src/client/portals.d.ts.map +0 -1
  65. package/dist/src/client/portals.js.map +0 -1
  66. package/dist/src/client/query.d.ts.map +0 -1
  67. package/dist/src/client/query.js.map +0 -1
  68. package/dist/src/client/types.d.ts.map +0 -1
  69. package/dist/src/client/types.js.map +0 -1
  70. package/dist/src/index.d.ts.map +0 -1
  71. package/dist/src/index.js.map +0 -1
@@ -1,4 +1,3 @@
1
- import type { Command } from "commander";
1
+ import { type Command } from "commander";
2
2
  import type { CliDeps } from "../io.js";
3
3
  export declare function registerCatalogueCommands(program: Command, deps: CliDeps): void;
4
- //# sourceMappingURL=catalogue.d.ts.map
@@ -1,14 +1,23 @@
1
1
  // Commands over the catalogue: datasets, their resources, publishers, themes
2
2
  // and tags.
3
+ import { InvalidArgumentError } from "commander";
4
+ import { facetLimitProblem } from "../../client/validate.js";
3
5
  import { action, collectNonEmpty, parseBoundedInt, parseIntArg, parseNonEmpty, parseOptionValue, renderJson, } from "../shared.js";
4
6
  /**
5
7
  * commander value-parser for a list --limit: 1 or more. CKAN reads `limit=0` as
6
8
  * "no limit" and would send the whole list; leave --limit out for that.
7
9
  */
8
10
  const parseLimit = parseBoundedInt(1, Number.MAX_SAFE_INTEGER);
9
- /** commander value-parser for --facet-limit: a count, or -1 for every value. */
11
+ /**
12
+ * commander value-parser for --facet-limit: a count, or -1 for every value (the
13
+ * library's facetLimitProblem rule).
14
+ */
10
15
  function parseFacetLimit(value) {
11
- return value === "-1" ? -1 : parseIntArg(value);
16
+ const n = /^-\d+$/.test(value) ? Number(value) : parseIntArg(value);
17
+ const reason = facetLimitProblem(n);
18
+ if (reason !== undefined)
19
+ throw new InvalidArgumentError(reason);
20
+ return n;
12
21
  }
13
22
  export function registerCatalogueCommands(program, deps) {
14
23
  program
@@ -105,4 +114,3 @@ export function registerCatalogueCommands(program, deps) {
105
114
  renderJson(deps, global, await client.tagList({ query: opts["query"] }));
106
115
  }));
107
116
  }
108
- //# sourceMappingURL=catalogue.js.map
@@ -1,4 +1,3 @@
1
1
  import type { Command } from "commander";
2
2
  import type { CliDeps } from "../io.js";
3
3
  export declare function registerPortalCommands(program: Command, deps: CliDeps): void;
4
- //# sourceMappingURL=portal.d.ts.map
@@ -1,28 +1,29 @@
1
1
  // Commands about the portal itself rather than its datasets.
2
2
  import { InvalidArgumentError } from "commander";
3
3
  import { action, renderJson, toEngineOptions } from "../shared.js";
4
- import { checkPortal, mapLimit, withCheck } from "../../client/portals.js";
4
+ import { checkPortals } from "../../client/portals.js";
5
5
  import { PORTALS } from "../../client/portals-list.js";
6
- /** How many portals `portals --check` checks at once. */
7
- const CHECK_CONCURRENCY = 6;
6
+ import { isBlank } from "../../client/validate.js";
8
7
  /** commander accumulator for repeatable `key=value` pairs into a record. */
9
8
  function collectKeyValue(value, previous = {}) {
10
9
  const eq = value.indexOf("=");
11
10
  // Throw commander's InvalidArgumentError (not a CkanError) so the failure is
12
11
  // formatted as a usage error with `error:` prefix and help, consistent with
13
12
  // other parse-time flag validation (e.g. `--rows abc`).
14
- if (eq <= 0) {
13
+ const key = value.slice(0, Math.max(eq, 0));
14
+ // A blank key (`=x`, ` =x`) names no parameter: the library refuses it too.
15
+ if (eq < 0 || isBlank(key)) {
15
16
  throw new InvalidArgumentError(`Invalid --param "${value}". Expected key=value.`);
16
17
  }
17
- const key = value.slice(0, eq);
18
18
  // Reject a duplicated key rather than silently overwriting the earlier value.
19
19
  if (Object.prototype.hasOwnProperty.call(previous, key)) {
20
20
  throw new InvalidArgumentError(`Duplicate --param key "${key}".`);
21
21
  }
22
- // A blank value would be dropped (CKAN reads an empty parameter as unset), so
23
- // `--param q=` would silently run the action unfiltered.
22
+ // A blank value is refused by the library as well (CKAN reads an empty
23
+ // parameter as unset, so `--param q=` would run the action unfiltered); here it
24
+ // is a usage error that names the flag.
24
25
  const paramValue = value.slice(eq + 1);
25
- if (paramValue.trim() === "") {
26
+ if (isBlank(paramValue)) {
26
27
  throw new InvalidArgumentError(`Invalid --param "${value}". The value must not be blank.`);
27
28
  }
28
29
  // A computed key in a literal is an own data property, even for `__proto__`.
@@ -59,10 +60,10 @@ export function registerPortalCommands(program, deps) {
59
60
  renderJson(deps, global, PORTALS);
60
61
  return;
61
62
  }
62
- const today = new Date().toISOString().slice(0, 10);
63
- const engine = toEngineOptions(global);
64
- const checked = await mapLimit(PORTALS, CHECK_CONCURRENCY, async (portal) => withCheck(portal, await checkPortal(deps.createClient({ ...engine, baseUrl: portal.url })), today));
63
+ const checked = await checkPortals(PORTALS, {
64
+ engineOptions: toEngineOptions(global),
65
+ createClient: deps.createClient,
66
+ });
65
67
  renderJson(deps, global, checked);
66
68
  });
67
69
  }
68
- //# sourceMappingURL=portal.js.map
@@ -1,3 +1,2 @@
1
1
  #!/usr/bin/env node
2
2
  export {};
3
- //# sourceMappingURL=index.d.ts.map
@@ -5,4 +5,3 @@ import { run } from "./run.js";
5
5
  handleOutputErrors();
6
6
  const exitCode = await run(process.argv.slice(2));
7
7
  process.exitCode = exitCode;
8
- //# sourceMappingURL=index.js.map
@@ -29,4 +29,3 @@ export interface OutputStreams {
29
29
  */
30
30
  export declare function handleOutputErrors(streams?: OutputStreams, exit?: (code: number) => void): void;
31
31
  export declare const defaultIO: CliIO;
32
- //# sourceMappingURL=io.d.ts.map
@@ -27,4 +27,3 @@ export const defaultIO = {
27
27
  out: (text) => process.stdout.write(text + "\n"),
28
28
  err: (text) => process.stderr.write(text + "\n"),
29
29
  };
30
- //# sourceMappingURL=io.js.map
@@ -4,4 +4,3 @@ export declare const VERSION: string;
4
4
  /** Default dependencies: real client + real stdout/stderr + real environment. */
5
5
  export declare const defaultDeps: CliDeps;
6
6
  export declare function buildProgram(deps?: CliDeps): Command;
7
- //# sourceMappingURL=program.d.ts.map
@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
6
6
  import { Command, InvalidArgumentError, Option } from "commander";
7
7
  import { defaultIO } from "./io.js";
8
8
  import { CkanClient } from "../client/client.js";
9
- import { DEFAULT_BASE_URL, MAX_RETRIES } from "../client/engine.js";
9
+ import { DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS } from "../client/engine.js";
10
10
  import { MAX_TIMEOUT_MS } from "../client/http.js";
11
11
  import { redactUrl } from "../client/errors.js";
12
12
  import { parseBaseUrl, parseBoundedInt, parseHeaderValue, parseIntArg, parsePortal } from "./shared.js";
@@ -52,7 +52,7 @@ export function buildProgram(deps = defaultDeps) {
52
52
  .conflicts("baseUrl"))
53
53
  .option("--timeout <ms>", "per-request timeout in milliseconds", parseBoundedInt(0, MAX_TIMEOUT_MS))
54
54
  .option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
55
- .option("--max-retries <n>", "retries for transient 429/503 responses (0..10; each waits the server's Retry-After, up to 30 s)", parseBoundedInt(0, MAX_RETRIES))
55
+ .option("--max-retries <n>", `retries for transient 429/503 responses (0..${MAX_RETRIES}; each waits the server's Retry-After, up to ${MAX_RETRY_AFTER_MS / 1000} s)`, parseBoundedInt(0, MAX_RETRIES))
56
56
  .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
57
57
  .option("--compact", "print JSON on a single line instead of pretty-printed")
58
58
  .showHelpAfterError();
@@ -93,4 +93,3 @@ export function buildProgram(deps = defaultDeps) {
93
93
  program.allowExcessArguments(true);
94
94
  return program;
95
95
  }
96
- //# sourceMappingURL=program.js.map
@@ -1,3 +1,2 @@
1
1
  import type { CliDeps } from "./io.js";
2
2
  export declare function run(argv: string[], deps?: CliDeps): Promise<number>;
3
- //# sourceMappingURL=run.d.ts.map
@@ -3,7 +3,9 @@
3
3
  // captured output and exit code without spawning a subprocess.
4
4
  import { CommanderError } from "commander";
5
5
  import { buildProgram, defaultDeps } from "./program.js";
6
- import { CkanApiError, CkanError } from "../client/errors.js";
6
+ import { CkanApiError, CkanError, CkanValidationError } from "../client/errors.js";
7
+ /** The exit code of a usage error: commander's own for a rejected option value. */
8
+ const USAGE_EXIT = 1;
7
9
  /**
8
10
  * Apply exitOverride + output redirection to every command in the tree.
9
11
  * commander does not propagate these to subcommands, so a parse error on a
@@ -30,6 +32,12 @@ export async function run(argv, deps = defaultDeps) {
30
32
  // Help/version requests exit 0; genuine parse errors carry their own code.
31
33
  return err.exitCode;
32
34
  }
35
+ if (err instanceof CkanValidationError) {
36
+ // An input the library refused before any request (a rule the commander
37
+ // parsers do not see, e.g. one across parameters): a usage error.
38
+ deps.io.err(`Error: ${err.message}`);
39
+ return USAGE_EXIT;
40
+ }
33
41
  if (err instanceof CkanApiError) {
34
42
  deps.io.err(`Error: ${err.message}`);
35
43
  // Map a few notable statuses to distinct exit codes for scripting.
@@ -45,4 +53,3 @@ export async function run(argv, deps = defaultDeps) {
45
53
  return 1;
46
54
  }
47
55
  }
48
- //# sourceMappingURL=run.js.map
@@ -3,17 +3,14 @@ import { type EngineOptions } from "../client/engine.js";
3
3
  /** commander value-parser: a non-negative integer. */
4
4
  export declare function parseIntArg(value: string): number;
5
5
  /**
6
- * commander value-parser: a value that is not blank. A blank filter would
7
- * otherwise be dropped and the command would silently run unfiltered.
6
+ * commander value-parser: a value that is not blank (the library's blankProblem
7
+ * rule, reported as a usage error before the client is built).
8
8
  */
9
9
  export declare function parseNonEmpty(value: string): string;
10
10
  /**
11
- * commander value-parser for a value that ends up in an HTTP header (`--user-agent`).
12
- * Node's HTTP layer throws an opaque "Invalid character in header content" at request
13
- * time for a CR/LF (or any other C0 control or DEL) and for any character above
14
- * U+00FF, which surfaced as "Unexpected error". Reject those here as a usage error,
15
- * along with a blank value. Tab is allowed, as in HTTP. Checked by char code so the
16
- * source stays free of control bytes.
11
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
12
+ * the library's headerValueProblem rule (not blank, no control characters but tab,
13
+ * nothing above U+00FF), reported as a usage error.
17
14
  */
18
15
  export declare function parseHeaderValue(value: string): string;
19
16
  /**
@@ -27,14 +24,13 @@ export declare function parseHeaderValue(value: string): string;
27
24
  export declare function parseOptionValue(value: string): string;
28
25
  /** commander accumulator for a repeatable option whose values are checked by parseOptionValue. */
29
26
  export declare function collectNonEmpty(value: string, previous?: string[]): string[];
30
- /** Build a commander value-parser for a non-negative integer within [min, max]. */
27
+ /** Build a commander value-parser for a non-negative integer within [min, max] (the library's intRangeProblem). */
31
28
  export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
32
29
  /**
33
- * commander value-parser for --base-url: reject a non-http(s) scheme at parse
34
- * time so `file:`, `ftp:`, etc. fail fast with a usage error rather than only
35
- * being caught later in the transport. The default transport also re-checks the
36
- * scheme per hop (and RequestEngine.buildUrl guards it for custom transports),
37
- * but this surfaces the mistake up front and independently of the transport.
30
+ * commander value-parser for --base-url (and CKAN_BASE_URL, via the preAction hook
31
+ * in program.ts): the library's baseUrlProblem rule (not blank, no whitespace, an
32
+ * absolute http(s) URL, no query string or fragment), reported as a usage error
33
+ * before the client is built.
38
34
  */
39
35
  export declare function parseBaseUrl(value: string): string;
40
36
  /** commander value-parser for --portal: the URL of a portal in the built-in list. */
@@ -77,4 +73,3 @@ export interface ActionContext {
77
73
  * the trailing options object and command instance to recover the positionals.
78
74
  */
79
75
  export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
80
- //# sourceMappingURL=shared.d.ts.map
@@ -4,6 +4,7 @@ import { InvalidArgumentError } from "commander";
4
4
  import { isBidiControl } from "../client/engine.js";
5
5
  import { CkanError } from "../client/errors.js";
6
6
  import { findPortal } from "../client/portals.js";
7
+ import { baseUrlProblem, blankProblem, countProblem, headerValueProblem, intRangeProblem } from "../client/validate.js";
7
8
  import { PORTALS } from "../client/portals-list.js";
8
9
  /** commander value-parser: a non-negative integer. */
9
10
  export function parseIntArg(value) {
@@ -14,41 +15,32 @@ export function parseIntArg(value) {
14
15
  throw new InvalidArgumentError("Expected a non-negative integer.");
15
16
  }
16
17
  const n = Number(value);
17
- // Reject magnitudes that cannot be represented exactly (silent precision loss).
18
- if (!Number.isSafeInteger(n)) {
19
- throw new InvalidArgumentError("Expected a non-negative integer.");
20
- }
18
+ // The library's count rule; it also rejects magnitudes that cannot be
19
+ // represented exactly (silent precision loss).
20
+ const reason = countProblem(n);
21
+ if (reason !== undefined)
22
+ throw new InvalidArgumentError(reason);
21
23
  return n;
22
24
  }
23
25
  /**
24
- * commander value-parser: a value that is not blank. A blank filter would
25
- * otherwise be dropped and the command would silently run unfiltered.
26
+ * commander value-parser: a value that is not blank (the library's blankProblem
27
+ * rule, reported as a usage error before the client is built).
26
28
  */
27
29
  export function parseNonEmpty(value) {
28
- if (value.trim() === "") {
29
- throw new InvalidArgumentError("Expected a non-empty value.");
30
- }
30
+ const reason = blankProblem(value);
31
+ if (reason !== undefined)
32
+ throw new InvalidArgumentError(reason);
31
33
  return value;
32
34
  }
33
35
  /**
34
- * commander value-parser for a value that ends up in an HTTP header (`--user-agent`).
35
- * Node's HTTP layer throws an opaque "Invalid character in header content" at request
36
- * time for a CR/LF (or any other C0 control or DEL) and for any character above
37
- * U+00FF, which surfaced as "Unexpected error". Reject those here as a usage error,
38
- * along with a blank value. Tab is allowed, as in HTTP. Checked by char code so the
39
- * source stays free of control bytes.
36
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
37
+ * the library's headerValueProblem rule (not blank, no control characters but tab,
38
+ * nothing above U+00FF), reported as a usage error.
40
39
  */
41
40
  export function parseHeaderValue(value) {
42
- parseNonEmpty(value);
43
- for (let i = 0; i < value.length; i++) {
44
- const c = value.charCodeAt(i);
45
- if ((c < 0x20 && c !== 0x09) || c === 0x7f) {
46
- throw new InvalidArgumentError("Value contains control characters.");
47
- }
48
- if (c > 0xff) {
49
- throw new InvalidArgumentError("Value contains characters outside Latin-1 (above U+00FF).");
50
- }
51
- }
41
+ const reason = headerValueProblem(value);
42
+ if (reason !== undefined)
43
+ throw new InvalidArgumentError(reason);
52
44
  return value;
53
45
  }
54
46
  /**
@@ -69,43 +61,27 @@ export function parseOptionValue(value) {
69
61
  export function collectNonEmpty(value, previous = []) {
70
62
  return previous.concat([parseOptionValue(value)]);
71
63
  }
72
- /** Build a commander value-parser for a non-negative integer within [min, max]. */
64
+ /** Build a commander value-parser for a non-negative integer within [min, max] (the library's intRangeProblem). */
73
65
  export function parseBoundedInt(min, max) {
66
+ const problem = intRangeProblem(min, max);
74
67
  return (value) => {
75
68
  const n = parseIntArg(value);
76
- if (n < min)
77
- throw new InvalidArgumentError(`Must be >= ${min}.`);
78
- if (n > max)
79
- throw new InvalidArgumentError(`Must be <= ${max}.`);
69
+ const reason = problem(n);
70
+ if (reason !== undefined)
71
+ throw new InvalidArgumentError(reason);
80
72
  return n;
81
73
  };
82
74
  }
83
75
  /**
84
- * commander value-parser for --base-url: reject a non-http(s) scheme at parse
85
- * time so `file:`, `ftp:`, etc. fail fast with a usage error rather than only
86
- * being caught later in the transport. The default transport also re-checks the
87
- * scheme per hop (and RequestEngine.buildUrl guards it for custom transports),
88
- * but this surfaces the mistake up front and independently of the transport.
76
+ * commander value-parser for --base-url (and CKAN_BASE_URL, via the preAction hook
77
+ * in program.ts): the library's baseUrlProblem rule (not blank, no whitespace, an
78
+ * absolute http(s) URL, no query string or fragment), reported as a usage error
79
+ * before the client is built.
89
80
  */
90
81
  export function parseBaseUrl(value) {
91
- let url;
92
- try {
93
- url = new URL(value);
94
- }
95
- catch {
96
- throw new InvalidArgumentError("Expected an absolute http(s) URL.");
97
- }
98
- if (url.protocol !== "http:" && url.protocol !== "https:") {
99
- throw new InvalidArgumentError(`Unsupported scheme "${url.protocol}". Expected an http(s) URL.`);
100
- }
101
- if (/[?#]/.test(value)) {
102
- throw new InvalidArgumentError("Expected a site URL without a query string or fragment.");
103
- }
104
- // `new URL` trims, but the value is used as given: a trailing space would land in
105
- // the request path (`/404%20/api/3/...`) or the host.
106
- if (value !== value.trim()) {
107
- throw new InvalidArgumentError("A base URL cannot have surrounding whitespace.");
108
- }
82
+ const reason = baseUrlProblem(value);
83
+ if (reason !== undefined)
84
+ throw new InvalidArgumentError(reason);
109
85
  return value;
110
86
  }
111
87
  /** commander value-parser for --portal: the URL of a portal in the built-in list. */
@@ -194,4 +170,3 @@ export function action(deps, fn) {
194
170
  await fn({ client, global, opts: command.opts() }, positionals);
195
171
  };
196
172
  }
197
- //# sourceMappingURL=shared.js.map
@@ -4,8 +4,9 @@ import type { Group, GroupListParams, JsonValue, License, ListParams, Organizati
4
4
  /**
5
5
  * The site root of a CKAN instance, from what a user is likely to paste: portals
6
6
  * document their API as `<site>/api/3/action`, so that suffix (or `/api/3`) is
7
- * dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it. A
8
- * query string or fragment is refused.
7
+ * dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it.
8
+ * A base URL that breaks the rules of `validateBaseUrl` (blank, whitespace, not
9
+ * an http(s) URL, a query string or fragment) throws CkanValidationError.
9
10
  */
10
11
  export declare function siteRoot(baseUrl: string): string;
11
12
  export declare class CkanClient {
@@ -31,7 +32,8 @@ export declare class CkanClient {
31
32
  * several as CKAN's `fq_list` (each its own Solr filter query; all must
32
33
  * match). `fq_list` is only used for two or more, because CKAN splits a lone
33
34
  * `fq_list` value into characters. Facet fields go out as the JSON list CKAN
34
- * expects in `facet.field`.
35
+ * expects in `facet.field`. A blank `q`, `sort`, filter or facet field is
36
+ * refused (CkanValidationError), never sent or dropped.
35
37
  */
36
38
  packageSearch(params?: PackageSearchParams): Promise<PackageSearchResult>;
37
39
  /** A single dataset by id or name. */
@@ -42,7 +44,7 @@ export declare class CkanClient {
42
44
  groupShow(id: string): Promise<Group>;
43
45
  /** A single resource (distribution) by id. */
44
46
  resourceShow(id: string): Promise<Resource>;
45
- /** Dataset names, paged with limit/offset (a positive limit; omit it for all). */
47
+ /** Dataset names, paged with limit/offset (a positive limit, omit it for all; a non-negative offset). */
46
48
  packageList(params?: ListParams): Promise<string[]>;
47
49
  /**
48
50
  * Organization names, or full objects with `all_fields`. See `groupOrOrgList`
@@ -51,7 +53,7 @@ export declare class CkanClient {
51
53
  organizationList(params?: GroupListParams): Promise<JsonValue[]>;
52
54
  /** Group names, or full objects with `all_fields` (paged like organizationList). */
53
55
  groupList(params?: GroupListParams): Promise<JsonValue[]>;
54
- /** Tags, optionally only those containing a substring. */
56
+ /** Tags, optionally only those containing a substring (a blank one is refused). */
55
57
  tagList(params?: TagListParams): Promise<string[]>;
56
58
  /** The licences this portal offers. */
57
59
  licenseList(): Promise<License[]>;
@@ -74,4 +76,3 @@ export declare class CkanClient {
74
76
  */
75
77
  private show;
76
78
  }
77
- //# sourceMappingURL=client.d.ts.map
@@ -1,7 +1,8 @@
1
1
  // CkanClient — a typed client over the open (no-auth) read endpoints of any CKAN
2
2
  // Action API (`<site>/api/3/action`).
3
- import { DEFAULT_BASE_URL, RequestEngine, sanitizeServerText } from "./engine.js";
4
- import { CkanError, CkanParseError, describeCkanError, redactUrl } from "./errors.js";
3
+ import { DEFAULT_BASE_URL, RequestEngine, sanitizeServerText, validateBaseUrl } from "./engine.js";
4
+ import { CkanError, CkanParseError, CkanValidationError, describeCkanError, redactUrl } from "./errors.js";
5
+ import { assertValid, blankProblem, countProblem, facetLimitProblem } from "./validate.js";
5
6
  const ACTION = "/api/3/action";
6
7
  /**
7
8
  * CKAN action names are always `[a-z0-9_]+`. Restricting to that allowlist closes
@@ -22,18 +23,20 @@ function entryKey(entry) {
22
23
  return JSON.stringify(entry);
23
24
  }
24
25
  /**
25
- * Drop undefined (and empty-string) values so only the parameters the caller
26
- * actually set are sent. An empty string filter (e.g. `tags --query ""`) is
27
- * treated as "no filter" rather than forwarded as `query=`.
26
+ * Drop undefined values so only the parameters the caller actually set are sent,
27
+ * and refuse a blank parameter name, a blank value or a list with a blank entry
28
+ * (CkanValidationError). CKAN reads an empty parameter as "not given", so a blank
29
+ * filter such as `tagList({ query: "" })` would silently return everything.
28
30
  */
29
31
  function prune(params) {
30
32
  // A null-prototype object, so a `__proto__` key is kept as a parameter instead
31
33
  // of setting the prototype (and being lost).
32
34
  const out = Object.create(null);
33
35
  for (const [k, v] of Object.entries(params)) {
34
- if (v === undefined || v === "")
36
+ if (v === undefined)
35
37
  continue;
36
- out[k] = v;
38
+ assertValid("parameter name", k, blankProblem);
39
+ out[k] = assertValid(k, v, blankProblem);
37
40
  }
38
41
  return out;
39
42
  }
@@ -62,22 +65,24 @@ function assertLimit(limit) {
62
65
  if (limit === undefined)
63
66
  return;
64
67
  if (!Number.isSafeInteger(limit) || limit < 1) {
65
- throw new CkanError(`Invalid limit: expected a positive integer, got ${String(limit)}. Leave it out for the whole list.`);
68
+ throw new CkanValidationError(`Invalid limit: expected a positive integer, got ${String(limit)}. Leave it out for the whole list.`);
66
69
  }
67
70
  }
71
+ /** Check an optional count or offset (`rows`, `start`, `offset`): see countProblem. */
72
+ function assertCount(name, value) {
73
+ if (value !== undefined)
74
+ assertValid(name, value, countProblem);
75
+ }
68
76
  /**
69
77
  * The site root of a CKAN instance, from what a user is likely to paste: portals
70
78
  * document their API as `<site>/api/3/action`, so that suffix (or `/api/3`) is
71
- * dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it. A
72
- * query string or fragment is refused.
79
+ * dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it.
80
+ * A base URL that breaks the rules of `validateBaseUrl` (blank, whitespace, not
81
+ * an http(s) URL, a query string or fragment) throws CkanValidationError.
73
82
  */
74
83
  export function siteRoot(baseUrl) {
75
- // The API path is appended to the base URL, so a query string or fragment in it
76
- // would end up in front of `/api/3/action` and break every request.
77
- if (/[?#]/.test(baseUrl)) {
78
- throw new CkanError(`The base URL must not contain a query string or fragment: ${redactUrl(baseUrl)}`);
79
- }
80
- return baseUrl.replace(/\/+$/, "").replace(/\/api\/3(\/action)?$/, "");
84
+ // Checked before the suffix strip: a trailing space would hide the suffix from it.
85
+ return validateBaseUrl(baseUrl).replace(/\/api\/3(\/action)?$/, "");
81
86
  }
82
87
  export class CkanClient {
83
88
  engine;
@@ -132,10 +137,19 @@ export class CkanClient {
132
137
  * several as CKAN's `fq_list` (each its own Solr filter query; all must
133
138
  * match). `fq_list` is only used for two or more, because CKAN splits a lone
134
139
  * `fq_list` value into characters. Facet fields go out as the JSON list CKAN
135
- * expects in `facet.field`.
140
+ * expects in `facet.field`. A blank `q`, `sort`, filter or facet field is
141
+ * refused (CkanValidationError), never sent or dropped.
136
142
  */
137
- packageSearch(params = {}) {
138
- const fq = (params.fq ?? []).filter((f) => f !== "");
143
+ async packageSearch(params = {}) {
144
+ assertValid("q", params.q, blankProblem);
145
+ assertValid("fq", params.fq, blankProblem);
146
+ assertValid("sort", params.sort, blankProblem);
147
+ assertValid("facet_field", params.facet_field, blankProblem);
148
+ assertCount("rows", params.rows);
149
+ assertCount("start", params.start);
150
+ if (params.facet_limit !== undefined)
151
+ assertValid("facet_limit", params.facet_limit, facetLimitProblem);
152
+ const fq = params.fq ?? [];
139
153
  const facetFields = params.facet_field ?? [];
140
154
  return this.typed("package_search", {
141
155
  q: params.q,
@@ -164,9 +178,10 @@ export class CkanClient {
164
178
  resourceShow(id) {
165
179
  return this.show("resource_show", id);
166
180
  }
167
- /** Dataset names, paged with limit/offset (a positive limit; omit it for all). */
181
+ /** Dataset names, paged with limit/offset (a positive limit, omit it for all; a non-negative offset). */
168
182
  async packageList(params = {}) {
169
183
  assertLimit(params.limit);
184
+ assertCount("offset", params.offset);
170
185
  return this.typed("package_list", { limit: params.limit, offset: params.offset }, Array.isArray, "an array");
171
186
  }
172
187
  /**
@@ -180,7 +195,7 @@ export class CkanClient {
180
195
  groupList(params = {}) {
181
196
  return this.groupOrOrgList("group_list", params);
182
197
  }
183
- /** Tags, optionally only those containing a substring. */
198
+ /** Tags, optionally only those containing a substring (a blank one is refused). */
184
199
  tagList(params = {}) {
185
200
  return this.typed("tag_list", { query: params.query }, Array.isArray, "an array");
186
201
  }
@@ -202,6 +217,8 @@ export class CkanClient {
202
217
  */
203
218
  async groupOrOrgList(action, params) {
204
219
  assertLimit(params.limit);
220
+ // Before the first request, and before the all_fields pager steps on from it.
221
+ assertCount("offset", params.offset);
205
222
  if (!params.all_fields) {
206
223
  return this.typed(action, { limit: params.limit, offset: params.offset }, Array.isArray, "an array");
207
224
  }
@@ -240,4 +257,3 @@ export class CkanClient {
240
257
  return this.typed(action, { id }, isObject, "a JSON object");
241
258
  }
242
259
  }
243
- //# sourceMappingURL=client.js.map
@@ -13,30 +13,44 @@ export interface EngineOptions {
13
13
  baseUrl?: string;
14
14
  /** Swappable transport. Defaults to the built-in node http/https transport. */
15
15
  transport?: Transport;
16
- /** Value of the User-Agent header. */
16
+ /**
17
+ * Value of the User-Agent header. Must be sendable (see `assertHeaderValue`):
18
+ * not blank, no control characters but tab, nothing above U+00FF.
19
+ */
17
20
  userAgent?: string;
18
- /** Per-request timeout in milliseconds (0 disables; capped at `MAX_TIMEOUT_MS`, 2^31 - 1 ms). */
21
+ /** Per-request timeout in milliseconds, 0 to `MAX_TIMEOUT_MS` (2^31 - 1 ms); 0 disables. */
19
22
  timeoutMs?: number;
20
23
  /**
21
24
  * Number of automatic retries for transient (429/503) responses. Each waits the
22
25
  * response's `Retry-After` (up to `MAX_RETRY_AFTER_MS`; a longer one is not
23
- * retried), or else `retryDelayMs * attempt`.
26
+ * retried), or else `retryDelayMs * attempt`. 0 to `MAX_RETRIES`; defaults to 2.
24
27
  */
25
28
  maxRetries?: number;
26
29
  /** Base backoff between retries in milliseconds (grows linearly); used without a Retry-After. */
27
30
  retryDelayMs?: number;
28
- /** Number of HTTP redirects (301/302/303/307/308) to follow. Defaults to 5. */
31
+ /** Number of HTTP redirects (301/302/303/307/308) to follow, 0 to `MAX_REDIRECTS`. Defaults to 5. */
29
32
  maxRedirects?: number;
30
33
  /**
31
34
  * Hard cap on response body size in bytes (defends against memory exhaustion
32
35
  * from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit.
36
+ *
37
+ * Every numeric option must be a non-negative safe integer within its range;
38
+ * the constructor throws CkanValidationError otherwise (a negative or NaN
39
+ * timeout or cap would silently switch that guard off).
33
40
  */
34
41
  maxResponseBytes?: number;
35
42
  /** Injectable sleep, primarily for deterministic tests. */
36
43
  sleep?: (ms: number) => Promise<void>;
37
44
  }
38
- /** Most automatic retries the CLI's --max-retries accepts. */
45
+ /** Most automatic retries the engine performs (`maxRetries`, the CLI's --max-retries). */
39
46
  export declare const MAX_RETRIES = 10;
47
+ /** Most redirects the engine follows (`maxRedirects`). */
48
+ export declare const MAX_REDIRECTS = 10;
49
+ /**
50
+ * Check a value for an HTTP header (headerValueProblem) and return it, or throw
51
+ * CkanValidationError `Invalid <name>: …`.
52
+ */
53
+ export declare function assertHeaderValue(name: string, value: string): string;
40
54
  /**
41
55
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
42
56
  * server asks for longer, the engine does not retry at all and surfaces the error at
@@ -82,6 +96,15 @@ export declare function isBidiControl(code: number): boolean;
82
96
  * Written as a char-code filter so no raw control byte appears in this source.
83
97
  */
84
98
  export declare function sanitizeServerText(text: string): string;
99
+ /**
100
+ * Check a base URL (baseUrlProblem: not blank, no whitespace or control
101
+ * characters, an absolute http(s) URL, no query string or fragment) and return it
102
+ * without trailing slashes. Throws CkanValidationError `Invalid base URL: …` — a
103
+ * configuration mistake, not a CkanNetworkError. The RequestEngine and CkanClient
104
+ * constructors call it, so a custom transport never sees a bad base URL; the
105
+ * default transport still re-checks the scheme on every hop.
106
+ */
107
+ export declare function validateBaseUrl(raw: string): string;
85
108
  export declare class RequestEngine {
86
109
  private readonly baseUrl;
87
110
  private readonly transport;
@@ -104,4 +127,3 @@ export declare class RequestEngine {
104
127
  getJson<T>(path: string, query?: QueryParams): Promise<T>;
105
128
  private toApiError;
106
129
  }
107
- //# sourceMappingURL=engine.d.ts.map