anyfreebook-cli 0.0.0-stage → 0.1.0

package/src/api.js

@@ -0,0 +1,189 @@
+/**
+ * HTTP client for the ANYFREEBOOK public API (v1).
+ *
+ * Zero dependencies: Node's global fetch plus AbortSignal.timeout().
+ * Every failure mode is converted into a CliError so the caller never has to
+ * deal with a raw network exception.
+ */
+
+import { apiError, networkError } from './errors.js';
+import { USER_AGENT } from './config.js';
+
+export class ApiClient {
+  constructor({ base, apiKey = '', timeoutMs = 20000, fetchImpl = globalThis.fetch } = {}) {
+    if (typeof fetchImpl !== 'function') {
+      throw new Error('No fetch implementation available. Node 18 or newer is required.');
+    }
+    this.base = String(base || '').replace(/\/+$/, '');
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+  }
+
+  /** Headers for every API request. The API key is only sent when present. */
+  headers() {
+    const headers = {
+      accept: 'application/json',
+      'user-agent': USER_AGENT,
+    };
+    if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`;
+    return headers;
+  }
+
+  buildUrl(pathname, params = {}) {
+    const url = new URL(`${this.base}/${String(pathname).replace(/^\/+/, '')}`);
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null || value === '') continue;
+      url.searchParams.set(key, String(value));
+    }
+    return url;
+  }
+
+  /** Perform a GET request and return the decoded JSON body. */
+  async request(pathname, params = {}) {
+    const url = this.buildUrl(pathname, params);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: 'GET',
+        headers: this.headers(),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (err) {
+      throw this.#networkFailure(err, url);
+    }
+
+    let text = '';
+    try {
+      text = await response.text();
+    } catch (err) {
+      throw networkError(`The connection to ${this.base} broke while reading the response.`, {
+        code: 'network',
+        hint: 'Try again, or increase the timeout with --timeout <ms>.',
+      });
+    }
+
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = null;
+      }
+    }
+
+    if (!response.ok) throw this.#httpFailure(response, data, text);
+
+    if (data === null) {
+      throw apiError(`The API returned a non-JSON response (HTTP ${response.status}).`, {
+        status: response.status,
+        hint: 'Check that --api-base points at an ANYFREEBOOK API v1 base URL.',
+      });
+    }
+
+    return data;
+  }
+
+  /** GET /search */
+  async search({ q, page = 1, source = 'all', limit = 20 } = {}) {
+    return this.request('search', { q, page, source, limit });
+  }
+
+  /** GET /resolve */
+  async resolve({ title, author } = {}) {
+    return this.request('resolve', { title, author });
+  }
+
+  /** GET /health */
+  async health() {
+    return this.request('health');
+  }
+
+  #networkFailure(err, url) {
+    const name = err && err.name ? err.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError') {
+      return networkError(`Request to ${url.host} timed out after ${this.timeoutMs} ms.`, {
+        code: 'timeout',
+        hint: 'Raise the timeout with --timeout <ms>, or check that the API is responding.',
+      });
+    }
+    const cause = (err && (err.cause || err)) || {};
+    const code = cause.code ? ` (${cause.code})` : '';
+    return networkError(`Could not reach the ANYFREEBOOK API at ${this.base}${code}.`, {
+      code: 'network',
+      hint:
+        'Check your internet connection. If the API runs elsewhere, point the CLI at it with ' +
+        '--api-base <url> or the ANYFREEBOOK_API_BASE environment variable.',
+    });
+  }
+
+  #httpFailure(response, data, text) {
+    const status = response.status;
+    const serverMessage =
+      (data && typeof data === 'object' && typeof data.error === 'string' && data.error) ||
+      (data && typeof data === 'object' && typeof data.message === 'string' && data.message) ||
+      '';
+
+    if (status === 401) {
+      return apiError('The API rejected the request as unauthorized (HTTP 401).', {
+        status,
+        code: 'unauthorized',
+        hint:
+          'Set ANYFREEBOOK_API_KEY=<your-key> or pass --api-key <your-key>. ' +
+          'No key is needed for the anonymous tier, so try again without one; ' +
+          'use --json if you want the failure as JSON.',
+      });
+    }
+
+    if (status === 429) {
+      const retryAfter = parseRetryAfter(response.headers && response.headers.get('retry-after'));
+      const seconds = retryAfter === null ? 'a short while' : `${retryAfter} second${retryAfter === 1 ? '' : 's'}`;
+      return apiError(`Rate limited by the API (HTTP 429). Retry after ${seconds}.`, {
+        status,
+        code: 'rate_limited',
+        exitCode: 2,
+        retryAfter,
+        hint: 'Slow down and retry shortly.',
+      });
+    }
+
+    if (status === 400) {
+      return apiError(serverMessage || 'The API rejected the request (HTTP 400).', {
+        status,
+        code: 'bad_request',
+      });
+    }
+
+    if (status === 404) {
+      return apiError(serverMessage || 'The API has no such endpoint (HTTP 404).', {
+        status,
+        code: 'not_found',
+        hint: 'Check --api-base; the public base URL is https://anyfreebook.com/api/v1.',
+      });
+    }
+
+    if (status >= 500) {
+      return apiError(
+        serverMessage || `The API failed to handle the request (HTTP ${status}).`,
+        { status, code: 'server_error', hint: 'This is a problem on the API side. Try again shortly.' },
+      );
+    }
+
+    return apiError(serverMessage || `Unexpected API response (HTTP ${status}).`, {
+      status,
+      code: 'http_error',
+      ...(text ? {} : {}),
+    });
+  }
+}
+
+function parseRetryAfter(value) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds));
+  const asDate = Date.parse(value);
+  if (!Number.isNaN(asDate)) {
+    return Math.max(0, Math.round((asDate - Date.now()) / 1000));
+  }
+  return null;
+}

package/src/cli.js

@@ -0,0 +1,241 @@
+/**
+ * Entry point: argument parsing, dispatch and top-level error handling.
+ *
+ * The CLI never prints a stack trace. Every failure becomes a short message
+ * and an exit code.
+ */
+
+import { ApiClient } from './api.js';
+import { resolveConfig, VERSION } from './config.js';
+import { CliError, EXIT_ERROR, errorPayload, toCliError, usageError } from './errors.js';
+import { createStyler, resolveColor } from './format.js';
+import { downloadCommand } from './commands/download.js';
+import { healthCommand } from './commands/health.js';
+import { resolveCommand } from './commands/resolve.js';
+import { searchCommand } from './commands/search.js';
+
+const COMMANDS = {
+  search: searchCommand,
+  download: downloadCommand,
+  resolve: resolveCommand,
+  health: healthCommand,
+};
+
+const VALUE_OPTIONS = new Set([
+  '--api-base',
+  '--api-key',
+  '--timeout',
+  '--limit',
+  '--page',
+  '--source',
+  '--format',
+  '--out',
+  '--author',
+]);
+
+const BOOLEAN_OPTIONS = new Set([
+  '--json',
+  '--no-color',
+  '--free-only',
+  '--force',
+  '--dry-run',
+  '--help',
+  '--version',
+]);
+
+const SHORT_OPTIONS = { '-h': '--help', '-v': '--version' };
+
+function toCamel(option) {
+  return option
+    .replace(/^--/, '')
+    .replace(/-([a-z0-9])/g, (_, chr) => chr.toUpperCase());
+}
+
+/** Parse argv into `{ _: [...], ...flags }`. */
+export function parseArgs(argv) {
+  const opts = { _: [] };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    if (raw === '--') {
+      opts._.push(...argv.slice(index + 1));
+      break;
+    }
+    if (raw.length > 1 && raw.startsWith('-')) {
+      let key = raw;
+      let inline;
+      const equals = raw.indexOf('=');
+      if (equals > -1) {
+        key = raw.slice(0, equals);
+        inline = raw.slice(equals + 1);
+      }
+      if (SHORT_OPTIONS[key]) key = SHORT_OPTIONS[key];
+
+      if (VALUE_OPTIONS.has(key)) {
+        const value = inline !== undefined ? inline : argv[(index += 1)];
+        if (value === undefined) throw usageError(`Option ${key} requires a value.`);
+        opts[toCamel(key)] = value;
+      } else if (BOOLEAN_OPTIONS.has(key)) {
+        if (inline !== undefined) throw usageError(`Option ${key} does not take a value.`);
+        opts[toCamel(key)] = true;
+      } else {
+        throw usageError(
+          `Unknown option: ${key}.`,
+          'Run `anyfreebook --help` to see the supported options.',
+        );
+      }
+    } else {
+      opts._.push(raw);
+    }
+  }
+
+  return opts;
+}
+
+export const GENERAL_HELP = `anyfreebook ${VERSION} — search 7 open-access book sources, download only what is verifiably public domain.
+
+Usage:
+  anyfreebook search <query> [options]
+  anyfreebook download <query> [options]
+  anyfreebook resolve <title> [--author <name>] [options]
+  anyfreebook health [options]
+
+Global options:
+  --api-base <url>    API base URL            (env ANYFREEBOOK_API_BASE)
+  --api-key <key>     API key, optional      (env ANYFREEBOOK_API_KEY)
+  --timeout <ms>      Request timeout        (default 20000)
+  --json              Print raw JSON to stdout, nothing else
+  --no-color          Disable ANSI colour    (NO_COLOR is honoured too)
+  --help, -h          Show this help
+  --version, -v       Show the version
+
+Exit codes:
+  0  success
+  1  request or usage error
+  2  rate limited (HTTP 429)
+
+Docs: https://anyfreebook.com
+`;
+
+export const COMMAND_HELP = {
+  search: `
+Search — fan one query out across Project Gutenberg, Open Library, the Internet
+Archive, Google Books, PubMed Central, DOAJ and LibriVox.
+
+  anyfreebook search <query> [options]
+
+  --limit <n>        Results per page (default 10, max 50)
+  --page <n>         Page number (default 1)
+  --source <name>    all | gutenberg | openlibrary | archive | googlebooks |
+                     pubmed | doaj | librivox   (default all)
+  --format <fmt>     Keep only results offering epub | pdf | txt | html
+  --free-only        Keep only results with a verified free download
+`,
+  download: `
+Download — search, then write verified public-domain books to a folder.
+
+  anyfreebook download <query> [options]
+
+  --limit <n>        Results to consider (default 5, max 50)
+  --source <name>    all | gutenberg | openlibrary | archive | googlebooks |
+                     pubmed | doaj | librivox   (default all)
+  --format <fmt>     epub | pdf | txt | html (default: best available —
+                     epub > pdf > txt > html)
+  --out <dir>        Destination folder (default ./books)
+  --force            Overwrite files that already exist
+  --dry-run          Show what would be downloaded; write nothing
+  --free-only        Accepted for symmetry; downloads are always limited to
+                     tier=download results
+`,
+  resolve: `
+Resolve — the authoritative legal status of one title.
+
+  anyfreebook resolve <title> [--author <name>] [options]
+
+  --author <name>    Author, to disambiguate between editions
+`,
+  health: `
+Health — check that the API is reachable.
+
+  anyfreebook health [options]
+`,
+};
+
+function helpFor(command) {
+  return command && COMMAND_HELP[command]
+    ? `${GENERAL_HELP}${COMMAND_HELP[command]}`
+    : GENERAL_HELP;
+}
+
+export async function main(argv = [], env = process.env) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    const error = toCliError(err);
+    process.stderr.write(`error: ${error.message}\n`);
+    if (error.hint) process.stderr.write(`hint: ${error.hint}\n`);
+    process.exitCode = error.exitCode;
+    return;
+  }
+
+  if (opts.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  const command = opts._[0];
+  if (!command) {
+    if (opts.help) {
+      process.stdout.write(helpFor(null));
+      return;
+    }
+    process.stderr.write(`error: No command given.\n\n${helpFor(null)}`);
+    process.exitCode = EXIT_ERROR;
+    return;
+  }
+
+  const handler = COMMANDS[command];
+  if (!handler) {
+    process.stderr.write(
+      `error: Unknown command "${command}". Known commands: ${Object.keys(COMMANDS).join(', ')}.\n\n${helpFor(null)}`,
+    );
+    process.exitCode = EXIT_ERROR;
+    return;
+  }
+
+  if (opts.help) {
+    process.stdout.write(helpFor(command));
+    return;
+  }
+
+  const config = resolveConfig(opts, env);
+  const color = resolveColor({ noColor: Boolean(opts.noColor), env, stream: process.stdout });
+  const style = createStyler({ color });
+
+  const ctx = {
+    api: new ApiClient(config),
+    config,
+    style,
+    env,
+    json: Boolean(opts.json),
+    width: process.stdout.columns || 100,
+    out: process.stdout,
+    err: process.stderr,
+  };
+
+  try {
+    await handler(opts, ctx);
+  } catch (err) {
+    const error = toCliError(err);
+    if (ctx.json) {
+      process.stdout.write(`${JSON.stringify(errorPayload(error), null, 2)}\n`);
+    } else {
+      process.stderr.write(`error: ${error.message}\n`);
+      if (error.hint) process.stderr.write(`hint: ${error.hint}\n`);
+    }
+    process.exitCode = error.exitCode;
+  }
+}
+
+export { CliError };