open-alex-wrapper 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,1880 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/export.ts
+var export_exports = {};
+__export(export_exports, {
+  exportToFile: () => exportToFile,
+  flatten: () => flatten
+});
+async function exportToFile(source, path, opts = {}) {
+  const format = opts.format ?? inferFormat(path);
+  const stream = (0, import_node_fs.createWriteStream)(path, { encoding: "utf8" });
+  const write = makeWriter(stream);
+  let count = 0;
+  try {
+    if (format === "jsonl") {
+      for await (const item of source) {
+        await write(JSON.stringify(item) + "\n");
+        count++;
+      }
+    } else if (format === "json") {
+      await write("[");
+      let first = true;
+      for await (const item of source) {
+        await write((first ? "" : ",\n") + JSON.stringify(item));
+        first = false;
+        count++;
+      }
+      await write("]\n");
+    } else {
+      let headers = null;
+      for await (const item of source) {
+        const row = opts.flatten === false ? item : flatten(item);
+        if (!headers) {
+          headers = Object.keys(row);
+          await write(headers.map(csvCell).join(",") + "\n");
+        }
+        await write(headers.map((h) => csvCell(row[h])).join(",") + "\n");
+        count++;
+      }
+    }
+  } finally {
+    await endStream(stream);
+  }
+  return { path, count };
+}
+function makeWriter(stream) {
+  return (s) => new Promise((resolve, reject) => {
+    stream.write(s, (err) => {
+      if (err) reject(err);
+    });
+    if (stream.writableNeedDrain) stream.once("drain", resolve);
+    else resolve();
+  });
+}
+function endStream(stream) {
+  return new Promise((resolve, reject) => {
+    stream.end((err) => err ? reject(err) : resolve());
+  });
+}
+function inferFormat(path) {
+  const p = path.toLowerCase();
+  if (p.endsWith(".jsonl") || p.endsWith(".ndjson")) return "jsonl";
+  if (p.endsWith(".csv")) return "csv";
+  if (p.endsWith(".json")) return "json";
+  return "jsonl";
+}
+function flatten(obj, prefix = "", out = {}) {
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      flatten(v, key, out);
+    } else {
+      out[key] = v;
+    }
+  }
+  return out;
+}
+function csvCell(value) {
+  if (value === null || value === void 0) return "";
+  const s = typeof value === "object" ? JSON.stringify(value) : String(value);
+  if (/[",\n\r]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+  return s;
+}
+var import_node_fs;
+var init_export = __esm({
+  "src/export.ts"() {
+    "use strict";
+    import_node_fs = require("fs");
+  }
+});
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  parseArgs: () => parseArgs,
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+
+// src/cache.ts
+var LRUCache = class {
+  constructor(maxEntries = 1e3) {
+    this.maxEntries = maxEntries;
+  }
+  maxEntries;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.map.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt !== 0 && entry.expiresAt < Date.now()) {
+      this.map.delete(key);
+      return void 0;
+    }
+    this.map.delete(key);
+    this.map.set(key, entry);
+    return entry.value;
+  }
+  set(key, value, ttlMs) {
+    if (this.map.has(key)) this.map.delete(key);
+    this.map.set(key, { value, expiresAt: ttlMs > 0 ? Date.now() + ttlMs : 0 });
+    while (this.map.size > this.maxEntries) {
+      const oldest = this.map.keys().next().value;
+      if (oldest === void 0) break;
+      this.map.delete(oldest);
+    }
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+
+// src/config.ts
+var NOOP_LOGGER = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+var DEFAULT_RETRY = {
+  maxRetries: 5,
+  baseDelayMs: 500,
+  maxDelayMs: 2e4,
+  retryOnStatus: [429, 500, 502, 503, 504]
+};
+var PKG_VERSION = "0.1.0";
+function resolveConfig(config = {}) {
+  const env = typeof process !== "undefined" ? process.env : {};
+  const apiKey = config.apiKey ?? env.OPENALEX_API_KEY;
+  const mailto = config.mailto ?? env.OPENALEX_MAILTO;
+  const globalFetch = typeof fetch !== "undefined" ? fetch : void 0;
+  const fetchImpl = config.fetch ?? globalFetch;
+  if (!fetchImpl) {
+    throw new Error(
+      "No fetch implementation available. Use Node 18+, or pass `fetch` in the config."
+    );
+  }
+  let cache;
+  if (config.cache === true) cache = new LRUCache();
+  else if (config.cache && typeof config.cache === "object") cache = config.cache;
+  let throttle;
+  if (config.throttle === true) throttle = { maxRequestsPerSecond: 10 };
+  else if (config.throttle && typeof config.throttle === "object") {
+    throttle = {
+      maxRequestsPerSecond: config.throttle.maxRequestsPerSecond ?? 10,
+      minRemainingUsd: config.throttle.minRemainingUsd
+    };
+  }
+  const ua = [`open-alex-wrapper/${PKG_VERSION}`, config.userAgent, mailto ? `mailto:${mailto}` : void 0].filter(Boolean).join(" ");
+  return {
+    apiKey,
+    mailto,
+    baseUrl: (config.baseUrl ?? "https://api.openalex.org").replace(/\/+$/, ""),
+    userAgent: ua,
+    timeoutMs: config.timeoutMs ?? 6e4,
+    retry: { ...DEFAULT_RETRY, ...config.retry },
+    concurrency: Math.max(1, config.concurrency ?? 8),
+    dailyBudgetUsd: config.dailyBudgetUsd,
+    onBudgetWarning: config.onBudgetWarning,
+    cache,
+    cacheTtlMs: config.cacheTtlMs ?? 3e5,
+    throttle,
+    fetch: fetchImpl,
+    logger: config.logger ?? NOOP_LOGGER
+  };
+}
+
+// src/errors.ts
+var OpenAlexError = class extends Error {
+  status;
+  url;
+  body;
+  constructor(message, ctx = {}) {
+    super(message, ctx.cause !== void 0 ? { cause: ctx.cause } : void 0);
+    this.name = new.target.name;
+    this.status = ctx.status;
+    this.url = ctx.url;
+    this.body = ctx.body;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends OpenAlexError {
+};
+var NotFoundError = class extends OpenAlexError {
+};
+var ValidationError = class extends OpenAlexError {
+};
+var RateLimitError = class extends OpenAlexError {
+  retryAfterMs;
+  constructor(message, ctx = {}) {
+    super(message, ctx);
+    this.retryAfterMs = ctx.retryAfterMs;
+  }
+};
+var ServerError = class extends OpenAlexError {
+};
+var TimeoutError = class extends OpenAlexError {
+};
+var NetworkError = class extends OpenAlexError {
+};
+var BudgetExceededError = class extends OpenAlexError {
+  spentUsd;
+  limitUsd;
+  wouldSpendUsd;
+  constructor(message, info) {
+    super(message);
+    this.spentUsd = info.spentUsd;
+    this.limitUsd = info.limitUsd;
+    this.wouldSpendUsd = info.wouldSpendUsd;
+  }
+};
+function errorForStatus(status, message, ctx = {}) {
+  const full = { ...ctx, status };
+  if (status === 401 || status === 403) return new AuthenticationError(message, full);
+  if (status === 404) return new NotFoundError(message, full);
+  if (status === 400 || status === 422) return new ValidationError(message, full);
+  if (status === 429) return new RateLimitError(message, full);
+  if (status >= 500) return new ServerError(message, full);
+  return new OpenAlexError(message, full);
+}
+
+// src/budget.ts
+var PRICING_USD = {
+  get: 0,
+  list: 1e-4,
+  search: 1e-3,
+  download: 0.01,
+  autocomplete: 1e-4
+};
+var FREE_DAILY_USD_WITH_KEY = 1;
+var FREE_DAILY_USD_WITHOUT_KEY = 0.1;
+var BASIC_PAGING_MAX_RESULTS = 1e4;
+function estimateExtractionCost(input) {
+  const perPage = clampPerPage(input.perPage ?? 200);
+  const strategy = input.strategy ?? "cursor";
+  const price = PRICING_USD[input.requestType];
+  const cappedByBasicPaging = strategy === "basic" && input.count > BASIC_PAGING_MAX_RESULTS;
+  const fetchableResults = strategy === "basic" ? Math.min(input.count, BASIC_PAGING_MAX_RESULTS) : input.count;
+  const pageCalls = fetchableResults === 0 ? 0 : Math.ceil(fetchableResults / perPage);
+  const pagesCostUsd = round6(pageCalls * price);
+  const probeCostUsd = round6(price);
+  return {
+    requestType: input.requestType,
+    matchingResults: input.count,
+    fetchableResults,
+    perPage,
+    pageCalls,
+    pagesCostUsd,
+    probeCostUsd,
+    totalCostUsd: round6(pagesCostUsd + probeCostUsd),
+    cappedByBasicPaging,
+    note: cappedByBasicPaging ? `Basic paging reaches only the first ${BASIC_PAGING_MAX_RESULTS.toLocaleString()} results; use cursor paging (the default) for the full ${input.count.toLocaleString()}.` : void 0
+  };
+}
+function clampPerPage(n) {
+  if (!Number.isFinite(n)) return 200;
+  return Math.max(1, Math.min(200, Math.floor(n)));
+}
+function parseUsageHeaders(headers) {
+  const map = normalizeHeaders(headers);
+  const raw = {};
+  for (const [k, v] of map) {
+    if (k.toLowerCase().startsWith("x-ratelimit")) raw[k.toLowerCase()] = v;
+  }
+  const num = (key) => {
+    const v = map.get(key);
+    if (v === void 0) return void 0;
+    const n = Number(String(v).replace(/[$,\s]/g, ""));
+    return Number.isFinite(n) ? n : void 0;
+  };
+  return {
+    costUsd: num("x-ratelimit-cost-usd"),
+    costRequiredUsd: num("x-ratelimit-cost-required-usd"),
+    remainingUsd: num("x-ratelimit-remaining-usd"),
+    limitUsd: num("x-ratelimit-limit-usd"),
+    prepaidRemainingUsd: num("x-ratelimit-prepaid-remaining-usd"),
+    creditsUsed: num("x-ratelimit-credits-used"),
+    creditsRemaining: num("x-ratelimit-remaining"),
+    creditsLimit: num("x-ratelimit-limit"),
+    resetSeconds: num("x-ratelimit-reset"),
+    raw
+  };
+}
+function normalizeHeaders(headers) {
+  const out = /* @__PURE__ */ new Map();
+  if (!headers) return out;
+  if (headers instanceof Map) {
+    for (const [k, v] of headers) out.set(k.toLowerCase(), String(v));
+    return out;
+  }
+  if (typeof headers.forEach === "function" && !Array.isArray(headers)) {
+    ;
+    headers.forEach((v, k) => out.set(k.toLowerCase(), v));
+    return out;
+  }
+  for (const [k, v] of Object.entries(headers)) {
+    if (v === void 0) continue;
+    out.set(k.toLowerCase(), Array.isArray(v) ? v.join(",") : String(v));
+  }
+  return out;
+}
+function emptyByType() {
+  const zero = () => ({ calls: 0, results: 0, estimatedCostUsd: 0 });
+  return { get: zero(), list: zero(), search: zero(), download: zero(), autocomplete: zero() };
+}
+var UsageTracker = class {
+  constructor(hasApiKey, dailyBudgetUsd) {
+    this.hasApiKey = hasApiKey;
+    this.dailyBudgetUsd = dailyBudgetUsd;
+  }
+  hasApiKey;
+  dailyBudgetUsd;
+  byType = emptyByType();
+  estimatedSpentUsd = 0;
+  reportedRemainingUsd = null;
+  reportedLimitUsd = null;
+  prepaidRemainingUsd = null;
+  creditsRemaining = null;
+  resetSeconds = null;
+  lastRequestCostUsd = null;
+  lastRawUsageHeaders = {};
+  /** The daily allowance in effect: OpenAlex-reported, else soft cap, else free tier. */
+  get dailyLimitUsd() {
+    if (this.reportedLimitUsd !== null) return this.reportedLimitUsd;
+    if (this.dailyBudgetUsd !== void 0) return this.dailyBudgetUsd;
+    return this.hasApiKey ? FREE_DAILY_USD_WITH_KEY : FREE_DAILY_USD_WITHOUT_KEY;
+  }
+  /** Authoritative spend today if headers seen (limit − remaining), else estimate. */
+  get spentUsd() {
+    if (this.reportedLimitUsd !== null && this.reportedRemainingUsd !== null) {
+      return round6(this.reportedLimitUsd - this.reportedRemainingUsd);
+    }
+    return round6(this.estimatedSpentUsd);
+  }
+  get remainingUsd() {
+    if (this.reportedRemainingUsd !== null) return this.reportedRemainingUsd;
+    return round6(Math.max(0, this.dailyLimitUsd - this.spentUsd));
+  }
+  /** Record one completed request. Called by the HTTP layer. */
+  record(type, opts = {}) {
+    const bucket = this.byType[type];
+    bucket.calls += 1;
+    bucket.results += opts.results ?? 0;
+    const modelled = PRICING_USD[type];
+    bucket.estimatedCostUsd = round6(bucket.estimatedCostUsd + modelled);
+    this.estimatedSpentUsd = round6(this.estimatedSpentUsd + modelled);
+    if (opts.headers) {
+      const p = parseUsageHeaders(opts.headers);
+      if (Object.keys(p.raw).length) this.lastRawUsageHeaders = p.raw;
+      if (p.remainingUsd !== void 0) this.reportedRemainingUsd = p.remainingUsd;
+      if (p.limitUsd !== void 0) this.reportedLimitUsd = p.limitUsd;
+      if (p.prepaidRemainingUsd !== void 0) this.prepaidRemainingUsd = p.prepaidRemainingUsd;
+      if (p.creditsRemaining !== void 0) this.creditsRemaining = p.creditsRemaining;
+      if (p.resetSeconds !== void 0) this.resetSeconds = p.resetSeconds;
+      if (p.costUsd !== void 0) this.lastRequestCostUsd = p.costUsd;
+    }
+  }
+  /**
+   * Throw {@link BudgetExceededError} if spending `additionalUsd` more would
+   * cross the soft cap. Only enforced when `dailyBudgetUsd` was configured.
+   */
+  assertWithinBudget(additionalUsd) {
+    if (this.dailyBudgetUsd === void 0) return;
+    const projected = this.spentUsd + additionalUsd;
+    if (projected > this.dailyBudgetUsd) {
+      throw new BudgetExceededError(
+        `This request would spend ~$${round6(projected).toFixed(
+          6
+        )}, over the configured daily budget of $${this.dailyBudgetUsd.toFixed(2)}.`,
+        { spentUsd: this.spentUsd, limitUsd: this.dailyBudgetUsd, wouldSpendUsd: round6(additionalUsd) }
+      );
+    }
+  }
+  /** Immutable point-in-time view of usage. */
+  snapshot() {
+    const reportedSpent = this.reportedLimitUsd !== null && this.reportedRemainingUsd !== null ? round6(this.reportedLimitUsd - this.reportedRemainingUsd) : null;
+    return {
+      totalCalls: Object.values(this.byType).reduce((a, b) => a + b.calls, 0),
+      estimatedSpentUsd: round6(this.estimatedSpentUsd),
+      reportedSpentUsd: reportedSpent,
+      reportedRemainingUsd: this.reportedRemainingUsd,
+      prepaidRemainingUsd: this.prepaidRemainingUsd,
+      creditsRemaining: this.creditsRemaining,
+      resetSeconds: this.resetSeconds,
+      lastRequestCostUsd: this.lastRequestCostUsd,
+      dailyLimitUsd: this.dailyLimitUsd,
+      spentUsd: this.spentUsd,
+      remainingUsd: this.remainingUsd,
+      byType: structuredCloneSafe(this.byType),
+      hasApiKey: this.hasApiKey
+    };
+  }
+  /** The last set of raw `x-ratelimit-*` headers OpenAlex sent (for debugging). */
+  get lastUsageHeaders() {
+    return { ...this.lastRawUsageHeaders };
+  }
+  /** Human-readable multi-line budget report. */
+  report() {
+    const s = this.snapshot();
+    const lines = [
+      "OpenAlex usage report",
+      `  API key:            ${s.hasApiKey ? "yes" : "no (anonymous)"}`,
+      `  Total API calls:    ${s.totalCalls}`,
+      `  Spend today:        $${s.spentUsd.toFixed(6)}${s.reportedSpentUsd !== null ? " (reported by OpenAlex)" : " (estimated)"}`,
+      `  Daily limit:        $${s.dailyLimitUsd.toFixed(4)}`,
+      `  Remaining:          $${s.remainingUsd.toFixed(6)}`
+    ];
+    if (s.prepaidRemainingUsd !== null)
+      lines.push(`  Prepaid remaining:  $${s.prepaidRemainingUsd.toFixed(4)}`);
+    if (s.creditsRemaining !== null)
+      lines.push(`  Credits remaining:  ${s.creditsRemaining}`);
+    if (s.resetSeconds !== null)
+      lines.push(`  Budget resets in:   ${formatDuration(s.resetSeconds)}`);
+    lines.push("  By type:");
+    for (const type of Object.keys(s.byType)) {
+      const b = s.byType[type];
+      if (b.calls === 0) continue;
+      lines.push(
+        `    ${type.padEnd(12)} ${String(b.calls).padStart(6)} calls  $${b.estimatedCostUsd.toFixed(6)}`
+      );
+    }
+    return lines.join("\n");
+  }
+  reset() {
+    this.byType = emptyByType();
+    this.estimatedSpentUsd = 0;
+    this.reportedRemainingUsd = null;
+    this.reportedLimitUsd = null;
+    this.prepaidRemainingUsd = null;
+    this.creditsRemaining = null;
+    this.resetSeconds = null;
+    this.lastRequestCostUsd = null;
+    this.lastRawUsageHeaders = {};
+  }
+};
+function formatDuration(seconds) {
+  const s = Math.max(0, Math.floor(seconds));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor(s % 3600 / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  if (m > 0) return `${m}m ${s % 60}s`;
+  return `${s}s`;
+}
+function round6(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+function structuredCloneSafe(v) {
+  return JSON.parse(JSON.stringify(v));
+}
+
+// src/throttle.ts
+var REAL_CLOCK = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((r) => setTimeout(r, ms))
+};
+var Throttle = class {
+  constructor(opts, clock = REAL_CLOCK) {
+    this.opts = opts;
+    this.clock = clock;
+  }
+  opts;
+  clock;
+  nextAllowedAt = 0;
+  /**
+   * Wait until the next request is allowed to start. Enforces the target rate
+   * and multiplies spacing when the remaining budget fraction is low.
+   */
+  async gate(state) {
+    if (this.opts.minRemainingUsd !== void 0 && state.remainingUsd < this.opts.minRemainingUsd) {
+      throw new BudgetExceededError(
+        `Auto-throttle floor hit: remaining budget $${state.remainingUsd.toFixed(6)} is below the configured floor $${this.opts.minRemainingUsd.toFixed(6)}.`,
+        {
+          spentUsd: Math.max(0, state.dailyLimitUsd - state.remainingUsd),
+          limitUsd: state.dailyLimitUsd,
+          wouldSpendUsd: 0
+        }
+      );
+    }
+    let spacing = this.opts.maxRequestsPerSecond > 0 ? 1e3 / this.opts.maxRequestsPerSecond : 0;
+    const frac = state.dailyLimitUsd > 0 ? state.remainingUsd / state.dailyLimitUsd : 1;
+    if (frac < 0.1) spacing *= 4;
+    else if (frac < 0.25) spacing *= 2;
+    const now = this.clock.now();
+    const wait = Math.max(0, this.nextAllowedAt - now);
+    this.nextAllowedAt = Math.max(now, this.nextAllowedAt) + spacing;
+    if (wait > 0) await this.clock.sleep(wait);
+  }
+};
+
+// src/http.ts
+var Semaphore = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  active = 0;
+  waiters = [];
+  async run(fn) {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+  acquire() {
+    if (this.active < this.max) {
+      this.active += 1;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+  release() {
+    const next = this.waiters.shift();
+    if (next) next();
+    else this.active -= 1;
+  }
+};
+var HttpClient = class {
+  constructor(config, usage) {
+    this.config = config;
+    this.usage = usage;
+    this.semaphore = new Semaphore(config.concurrency);
+    if (config.throttle) this.throttle = new Throttle(config.throttle);
+  }
+  config;
+  usage;
+  semaphore;
+  firedWarnings = /* @__PURE__ */ new Set();
+  throttle;
+  async gateThrottle() {
+    if (!this.throttle) return;
+    const s = this.usage.snapshot();
+    await this.throttle.gate({ remainingUsd: s.remainingUsd, dailyLimitUsd: s.dailyLimitUsd });
+  }
+  /** Build the full request URL plus a redacted variant (api_key hidden). */
+  buildUrl(path, params = {}) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== "") qs.set(k, v);
+    }
+    if (this.config.mailto) qs.set("mailto", this.config.mailto);
+    const redactedQs = new URLSearchParams(qs);
+    if (this.config.apiKey) {
+      qs.set("api_key", this.config.apiKey);
+      redactedQs.set("api_key", "REDACTED");
+    }
+    const base = `${this.config.baseUrl}/${encodeURI(path)}`;
+    const q = qs.toString();
+    const rq = redactedQs.toString();
+    return {
+      url: q ? `${base}?${q}` : base,
+      redacted: rq ? `${base}?${rq}` : base
+    };
+  }
+  /** Cache key excludes api_key so a shared cache isn't keyed to a secret. */
+  cacheKey(path, params) {
+    const { redacted } = this.buildUrl(path, params);
+    return redacted;
+  }
+  async request(opts) {
+    const params = opts.params ?? {};
+    const { url, redacted } = this.buildUrl(opts.path, params);
+    const useCache = this.config.cache && !opts.noCache;
+    const key = useCache ? this.cacheKey(opts.path, params) : void 0;
+    if (useCache && key) {
+      const cached = await this.config.cache.get(key);
+      if (cached !== void 0) {
+        this.config.logger.debug(`cache hit ${redacted}`);
+        return {
+          data: cached,
+          status: 200,
+          headers: new Headers(),
+          url: redacted,
+          cached: true
+        };
+      }
+    }
+    this.usage.assertWithinBudget(PRICING_USD[opts.requestType]);
+    await this.gateThrottle();
+    const response = await this.semaphore.run(() => this.fetchWithRetry(url, redacted, opts));
+    const results = countResults(response.data);
+    this.usage.record(opts.requestType, { results, headers: response.headers });
+    this.maybeWarnBudget();
+    if (useCache && key) {
+      await this.config.cache.set(key, response.data, this.config.cacheTtlMs);
+    }
+    return { ...response, url: redacted };
+  }
+  async fetchWithRetry(url, redacted, opts) {
+    const res = await this.sendWithRetry(url, redacted, { signal: opts.signal });
+    const data = await res.json();
+    return { data, status: res.status, headers: res.headers, url: redacted, cached: false };
+  }
+  /** Shared GET-with-retry core: returns the ok `Response` or throws typed. */
+  async sendWithRetry(url, redacted, opts) {
+    const { retry } = this.config;
+    let attempt = 0;
+    while (true) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+      const signal = opts.signal ? anySignal([opts.signal, controller.signal]) : controller.signal;
+      try {
+        this.config.logger.debug(`GET ${redacted} (attempt ${attempt + 1})`);
+        const res = await this.config.fetch(url, {
+          method: "GET",
+          headers: { Accept: "application/json, */*", "User-Agent": this.config.userAgent },
+          signal
+        });
+        if (res.ok) return res;
+        const body = await safeReadBody(res);
+        const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+        const err = errorForStatus(res.status, describe(res.status, body, redacted), {
+          url: redacted,
+          body,
+          ...res.status === 429 ? { retryAfterMs } : {}
+        });
+        if (this.shouldRetry(res.status, attempt)) {
+          await sleep(this.backoff(attempt, retryAfterMs));
+          attempt += 1;
+          continue;
+        }
+        throw err;
+      } catch (e) {
+        if (e instanceof OpenAlexError) throw e;
+        const isAbort = e?.name === "AbortError";
+        if (attempt < retry.maxRetries) {
+          this.config.logger.warn(`${isAbort ? "timeout" : "network error"}, retrying: ${redacted}`);
+          await sleep(this.backoff(attempt));
+          attempt += 1;
+          continue;
+        }
+        if (isAbort) {
+          throw new TimeoutError(`Request timed out after ${this.config.timeoutMs}ms`, {
+            url: redacted,
+            cause: e
+          });
+        }
+        throw new NetworkError(`Network request failed: ${e?.message ?? e}`, {
+          url: redacted,
+          cause: e
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  }
+  /** Append api_key + mailto to any absolute URL (for the content host, etc.). */
+  authorizeUrl(rawUrl) {
+    const u = new URL(rawUrl);
+    const r = new URL(rawUrl);
+    if (this.config.mailto) {
+      u.searchParams.set("mailto", this.config.mailto);
+      r.searchParams.set("mailto", this.config.mailto);
+    }
+    if (this.config.apiKey) {
+      u.searchParams.set("api_key", this.config.apiKey);
+      r.searchParams.set("api_key", "REDACTED");
+    }
+    return { url: u.toString(), redacted: r.toString() };
+  }
+  /**
+   * Download a binary resource (e.g. a full-text PDF/XML from the content host).
+   * Budget-asserted and usage-recorded like any other request.
+   */
+  async download(opts) {
+    this.usage.assertWithinBudget(PRICING_USD[opts.requestType]);
+    await this.gateThrottle();
+    const redacted = opts.redacted ?? opts.url;
+    const res = await this.semaphore.run(
+      () => this.sendWithRetry(opts.url, redacted, { signal: opts.signal })
+    );
+    this.usage.record(opts.requestType, { headers: res.headers });
+    this.maybeWarnBudget();
+    const contentType = res.headers.get("content-type") ?? void 0;
+    if (opts.dest) {
+      if (!res.body) throw new OpenAlexError("No response body to write", { url: redacted });
+      const [{ Readable }, { pipeline }, { createWriteStream: createWriteStream2 }] = await Promise.all([
+        import("stream"),
+        import("stream/promises"),
+        import("fs")
+      ]);
+      await pipeline(Readable.fromWeb(res.body), createWriteStream2(opts.dest));
+      return { path: opts.dest, status: res.status, headers: res.headers, contentType };
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return { bytes, status: res.status, headers: res.headers, contentType };
+  }
+  shouldRetry(status, attempt) {
+    return attempt < this.config.retry.maxRetries && this.config.retry.retryOnStatus.includes(status);
+  }
+  backoff(attempt, retryAfterMs) {
+    const { baseDelayMs, maxDelayMs } = this.config.retry;
+    if (retryAfterMs !== void 0) return Math.min(retryAfterMs, maxDelayMs);
+    const exp = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+    return Math.round(exp / 2 + Math.random() * (exp / 2));
+  }
+  maybeWarnBudget() {
+    const cb = this.config.onBudgetWarning;
+    if (!cb) return;
+    const { spentUsd, dailyLimitUsd } = this.usage.snapshot();
+    if (!dailyLimitUsd) return;
+    const ratio = spentUsd / dailyLimitUsd;
+    for (const threshold of [0.8, 1]) {
+      if (ratio >= threshold && !this.firedWarnings.has(threshold)) {
+        this.firedWarnings.add(threshold);
+        cb({ spentUsd, limitUsd: dailyLimitUsd, ratio });
+      }
+    }
+  }
+};
+function countResults(data) {
+  if (data && typeof data === "object" && Array.isArray(data.results)) {
+    return data.results.length;
+  }
+  return 0;
+}
+function describe(status, body, url) {
+  const msg = body && typeof body === "object" && "message" in body ? String(body.message) : body && typeof body === "object" && "error" in body ? String(body.error) : void 0;
+  return `OpenAlex request failed (${status})${msg ? `: ${msg}` : ""} [${url}]`;
+}
+async function safeReadBody(res) {
+  try {
+    const text = await res.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  } catch {
+    return void 0;
+  }
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const secs = Number(value);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+  const date = Date.parse(value);
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const s of signals) {
+    if (s.aborted) {
+      controller.abort();
+      break;
+    }
+    s.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  return controller.signal;
+}
+
+// src/pagination.ts
+function resolveStrategy(opts) {
+  if (opts.resume) return "cursor";
+  if (opts.strategy === "cursor" || opts.strategy === "basic") return opts.strategy;
+  return opts.parallel ? "basic" : "cursor";
+}
+async function* streamPages(runner, baseParams, opts = {}) {
+  const strategy = resolveStrategy(opts);
+  if (strategy === "cursor") {
+    yield* cursorPages(runner, baseParams, opts);
+  } else if (opts.parallel) {
+    yield* parallelBasicPages(runner, baseParams, opts);
+  } else {
+    yield* sequentialBasicPages(runner, baseParams, opts);
+  }
+}
+async function* streamItems(runner, baseParams, opts = {}) {
+  let emitted = 0;
+  const max = opts.maxResults ?? Infinity;
+  for await (const page of streamPages(runner, baseParams, opts)) {
+    for (const item of page.results) {
+      if (emitted >= max) return;
+      yield item;
+      emitted += 1;
+    }
+    if (emitted >= max) return;
+  }
+}
+async function* cursorPages(runner, baseParams, opts) {
+  const perPage = clampPerPage(opts.perPage ?? 200);
+  const fetchOpts = { requestType: opts.requestType, signal: opts.signal };
+  const maxResults = opts.maxResults ?? Infinity;
+  const maxPages = opts.maxPages ?? Infinity;
+  const saved = opts.resume?.load();
+  let cursor = saved?.cursor ?? "*";
+  let emitted = saved?.emitted ?? 0;
+  let pages = 0;
+  while (cursor && pages < maxPages && emitted < maxResults) {
+    const page = await runner.fetchList(
+      { ...baseParams, "per-page": String(perPage), cursor },
+      fetchOpts
+    );
+    pages += 1;
+    emitted += page.results.length;
+    if (page.results.length === 0) {
+      cursor = null;
+    } else {
+      cursor = page.meta.next_cursor ?? null;
+    }
+    opts.resume?.save({ cursor, emitted });
+    opts.onProgress?.({ emitted, page: pages, total: page.meta.count ?? null });
+    yield page;
+  }
+  if (cursor === null) opts.resume?.clear();
+}
+async function* sequentialBasicPages(runner, baseParams, opts) {
+  const perPage = clampPerPage(opts.perPage ?? 200);
+  const fetchOpts = { requestType: opts.requestType, signal: opts.signal };
+  const lastAllowedPage = Math.floor(BASIC_PAGING_MAX_RESULTS / perPage);
+  const maxPages = Math.min(opts.maxPages ?? Infinity, lastAllowedPage);
+  const maxResults = opts.maxResults ?? Infinity;
+  let emitted = 0;
+  for (let page = 1; page <= maxPages; page++) {
+    const result = await runner.fetchList(
+      { ...baseParams, "per-page": String(perPage), page: String(page) },
+      fetchOpts
+    );
+    emitted += result.results.length;
+    opts.onProgress?.({ emitted, page, total: result.meta.count ?? null });
+    yield result;
+    if (result.results.length < perPage || emitted >= maxResults) break;
+  }
+}
+async function* parallelBasicPages(runner, baseParams, opts) {
+  const perPage = clampPerPage(opts.perPage ?? 200);
+  const fetchOpts = { requestType: opts.requestType, signal: opts.signal };
+  const lastAllowedPage = Math.floor(BASIC_PAGING_MAX_RESULTS / perPage);
+  const first = await runner.fetchList(
+    { ...baseParams, "per-page": String(perPage), page: "1" },
+    fetchOpts
+  );
+  let emitted = first.results.length;
+  opts.onProgress?.({ emitted, page: 1, total: first.meta.count ?? null });
+  yield first;
+  const count = first.meta.count ?? first.results.length;
+  if (count > BASIC_PAGING_MAX_RESULTS) {
+    runner.logger.warn(
+      `parallelBasicPages: ${count.toLocaleString()} results exceed the ${BASIC_PAGING_MAX_RESULTS.toLocaleString()} basic-paging cap; only the first ${BASIC_PAGING_MAX_RESULTS.toLocaleString()} are returned. Use strategy:'cursor' for the full set.`
+    );
+  }
+  const neededPages = Math.ceil(Math.min(count, BASIC_PAGING_MAX_RESULTS) / perPage);
+  const totalPages = Math.min(neededPages, lastAllowedPage, opts.maxPages ?? Infinity);
+  if (totalPages <= 1 || first.results.length < perPage) return;
+  const promises = [];
+  for (let page = 2; page <= totalPages; page++) {
+    promises.push(
+      runner.fetchList({ ...baseParams, "per-page": String(perPage), page: String(page) }, fetchOpts)
+    );
+  }
+  let pageNum = 1;
+  for (const p of promises) {
+    const page = await p;
+    pageNum += 1;
+    emitted += page.results.length;
+    opts.onProgress?.({ emitted, page: pageNum, total: count });
+    yield page;
+    if (page.results.length === 0) break;
+  }
+}
+
+// src/query.ts
+var PAGINATION_DEFAULT_PER_PAGE = 200;
+var QueryBuilder = class _QueryBuilder {
+  constructor(runner, state = { filters: {}, extra: {} }) {
+    this.runner = runner;
+    this.state = state;
+  }
+  runner;
+  state;
+  /** The entity type this query targets (e.g. 'works'). */
+  get entityType() {
+    return this.runner.entityType;
+  }
+  clone(patch) {
+    return new _QueryBuilder(this.runner, {
+      ...this.state,
+      ...patch,
+      filters: patch.filters ?? this.state.filters,
+      extra: patch.extra ?? this.state.extra
+    });
+  }
+  // --- chainable builders --------------------------------------------------
+  /** Merge filters. Array values are OR'd; use `not`/`gt`/`lt` helpers. */
+  filter(filters) {
+    return this.clone({ filters: { ...this.state.filters, ...filters } });
+  }
+  /** Full-text relevance search across the entity's default searchable fields. */
+  search(term) {
+    return this.clone({ search: term });
+  }
+  /** Search within a specific field, e.g. `.searchField('title', 'crispr')`. */
+  searchField(field, term) {
+    return this.clone({ filters: { ...this.state.filters, [`${field}.search`]: term } });
+  }
+  sort(spec) {
+    let s;
+    if (typeof spec === "string") s = spec;
+    else if (Array.isArray(spec)) s = spec.join(",");
+    else s = Object.entries(spec).map(([k, v]) => `${k}:${v}`).join(",");
+    return this.clone({ sort: s });
+  }
+  /** Trim the response to specific fields (cheaper, faster payloads). */
+  select(fields) {
+    const arr = Array.isArray(fields) ? fields : fields.split(",").map((f) => f.trim());
+    return this.clone({ select: arr });
+  }
+  /** Random sample of `n` results (optionally deterministic via `seed`). */
+  sample(n, seed) {
+    return this.clone({ sampleN: n, seed: seed ?? this.state.seed });
+  }
+  seed(seed) {
+    return this.clone({ seed });
+  }
+  perPage(n) {
+    return this.clone({ perPage: clampPerPage(n) });
+  }
+  /** Aggregate counts by a field (or two comma-separated fields). */
+  groupBy(field) {
+    return this.clone({ groupBy: Array.isArray(field) ? field.join(",") : field });
+  }
+  /** Escape hatch: set any raw query parameter (advanced/semantic search, …). */
+  param(key, value) {
+    return this.clone({ extra: { ...this.state.extra, [key]: String(value) } });
+  }
+  // --- introspection -------------------------------------------------------
+  /** The OpenAlex query params this builder will send (no paging keys). */
+  toParams() {
+    const p = { ...this.state.extra };
+    const filter = serializeFilters(this.state.filters);
+    if (filter) p.filter = filter;
+    if (this.state.search) p.search = this.state.search;
+    if (this.state.sort) p.sort = this.state.sort;
+    if (this.state.select?.length) p.select = this.state.select.join(",");
+    if (this.state.groupBy) p.group_by = this.state.groupBy;
+    if (this.state.sampleN !== void 0) {
+      p.sample = String(this.state.sampleN);
+      if (this.state.seed !== void 0) p.seed = String(this.state.seed);
+    }
+    return p;
+  }
+  get requestType() {
+    if (this.state.search || this.state.extra.search) return "search";
+    for (const k of Object.keys(this.state.filters)) {
+      if (k.endsWith(".search") || k === "default.search") return "search";
+    }
+    return "list";
+  }
+  // --- terminal operations -------------------------------------------------
+  /** Fetch a single page. */
+  async get(opts = {}) {
+    const params = this.toParams();
+    if (opts.perPage !== void 0) params["per-page"] = String(clampPerPage(opts.perPage));
+    else if (this.state.perPage !== void 0) params["per-page"] = String(this.state.perPage);
+    if (opts.page !== void 0) params.page = String(opts.page);
+    return this.runner.fetchList(params, { requestType: this.requestType });
+  }
+  /** Fetch just the first matching entity, or `null`. */
+  async first() {
+    const res = await this.get({ perPage: 1 });
+    return res.results[0] ?? null;
+  }
+  /** Total number of matching results (one cheap probe call). */
+  async count() {
+    const res = await this.runner.fetchList(
+      { ...this.toParams(), "per-page": "1" },
+      { requestType: this.requestType }
+    );
+    return res.meta.count;
+  }
+  /** Async-iterate every matching page. */
+  paginate(opts = {}) {
+    return streamPages(this.runner, this.toParams(), this.streamOpts(opts));
+  }
+  /** Async-iterate every matching entity across all pages. */
+  all(opts = {}) {
+    return streamItems(this.runner, this.toParams(), this.streamOpts(opts));
+  }
+  /** Collect all matching entities into an array (respecting `maxResults`). */
+  async toArray(opts = {}) {
+    const out = [];
+    for await (const item of this.all(opts)) out.push(item);
+    return out;
+  }
+  /**
+   * Stream all results using the cost-optimal strategy: one cheap count, then
+   * parallel basic paging when ≤10k results (fastest) or cursor streaming above.
+   */
+  async *streamOptimized(opts = {}) {
+    const est = await this.estimateCost({ perPage: opts.perPage ?? 200, strategy: "cursor" });
+    const parallel = est.matchingResults <= BASIC_PAGING_MAX_RESULTS;
+    yield* this.all({ ...opts, perPage: opts.perPage ?? 200, parallel });
+  }
+  /** Run a `group_by` aggregation and return the buckets. */
+  async groups(field) {
+    const b = field ? this.groupBy(field) : this;
+    const res = await b.get({ perPage: 200 });
+    return res.group_by ?? [];
+  }
+  /** Estimate the dollar cost of extracting *all* matching results. */
+  async estimateCost(opts = {}) {
+    const count = await this.count();
+    return estimateExtractionCost({
+      count,
+      requestType: this.requestType,
+      perPage: opts.perPage ?? this.state.perPage ?? PAGINATION_DEFAULT_PER_PAGE,
+      strategy: opts.strategy ?? "cursor"
+    });
+  }
+  /** Stream all matching results to a file (JSONL / CSV / JSON). */
+  async export(path, opts = {}) {
+    const { exportToFile: exportToFile2 } = await Promise.resolve().then(() => (init_export(), export_exports));
+    return exportToFile2(this.all(opts), path, opts);
+  }
+  streamOpts(opts) {
+    return {
+      ...opts,
+      perPage: opts.perPage ?? this.state.perPage ?? PAGINATION_DEFAULT_PER_PAGE,
+      requestType: opts.requestType ?? this.requestType
+    };
+  }
+};
+function serializeScalar(v) {
+  if (typeof v === "boolean") return v ? "true" : "false";
+  return String(v);
+}
+function serializeFilterValue(v) {
+  return Array.isArray(v) ? v.map(serializeScalar).join("|") : serializeScalar(v);
+}
+function serializeFilters(filters) {
+  const entries = Object.entries(filters);
+  if (entries.length === 0) return void 0;
+  return entries.map(([k, v]) => `${k}:${serializeFilterValue(v)}`).join(",");
+}
+
+// src/ids.ts
+var OPENALEX_ID = /^[WASITCPFKGDL]\d{4,}$/i;
+var ORCID = /^(\d{4}-){3}\d{3}[\dX]$/i;
+var ISSN = /^\d{4}-\d{3}[\dX]$/i;
+var WIKIDATA = /^Q\d+$/i;
+var DOI = /^10\.\d{4,9}\/\S+$/;
+var KNOWN_PREFIX = /^(openalex|doi|mag|orcid|ror|issn|issn_l|wikidata|pmid|pmcid):/i;
+function normalizeId(input) {
+  const id = input.trim();
+  if (!id) return id;
+  if (KNOWN_PREFIX.test(id)) return id;
+  const url = tryUrl(id);
+  if (url) {
+    const host = url.hostname.replace(/^www\./, "");
+    const last = url.pathname.split("/").filter(Boolean).pop() ?? "";
+    if (host.endsWith("openalex.org")) return last;
+    if (host.endsWith("doi.org")) return `doi:${decodeURIComponent(url.pathname.slice(1))}`;
+    if (host.endsWith("orcid.org")) return `orcid:${last}`;
+    if (host.endsWith("ror.org")) return `ror:${last}`;
+    if (host.endsWith("wikidata.org")) return `wikidata:${last}`;
+    if (host.endsWith("ncbi.nlm.nih.gov") && url.pathname.includes("/pmc/"))
+      return `pmcid:${last}`;
+    if (host.endsWith("ncbi.nlm.nih.gov") || host.includes("pubmed"))
+      return `pmid:${last}`;
+    return last || id;
+  }
+  if (OPENALEX_ID.test(id)) return id.toUpperCase().charAt(0) + id.slice(1);
+  if (DOI.test(id)) return `doi:${id}`;
+  if (ORCID.test(id)) return `orcid:${id}`;
+  if (ISSN.test(id)) return `issn:${id}`;
+  if (WIKIDATA.test(id)) return `wikidata:${id.toUpperCase()}`;
+  return id;
+}
+function tryUrl(s) {
+  if (!/^https?:\/\//i.test(s)) return null;
+  try {
+    return new URL(s);
+  } catch {
+    return null;
+  }
+}
+
+// src/entities.ts
+var EntityEndpoint = class {
+  constructor(http, entityType) {
+    this.http = http;
+    this.entityType = entityType;
+  }
+  http;
+  entityType;
+  get logger() {
+    return this.http.config.logger;
+  }
+  get defaultConcurrency() {
+    return this.http.config.concurrency;
+  }
+  /** Low-level list fetch used by the query builder & paginators. */
+  async fetchList(params, opts = {}) {
+    const res = await this.http.request({
+      path: this.entityType,
+      params,
+      requestType: opts.requestType ?? "list",
+      noCache: opts.noCache,
+      signal: opts.signal
+    });
+    return res.data;
+  }
+  /** Start a fresh query. */
+  query() {
+    return new QueryBuilder(this);
+  }
+  // --- fluent proxies (each returns a QueryBuilder) ------------------------
+  filter(filters) {
+    return this.query().filter(filters);
+  }
+  search(term) {
+    return this.query().search(term);
+  }
+  searchField(field, term) {
+    return this.query().searchField(field, term);
+  }
+  sort(spec) {
+    return this.query().sort(spec);
+  }
+  select(fields) {
+    return this.query().select(fields);
+  }
+  sample(n, seed) {
+    return this.query().sample(n, seed);
+  }
+  groupBy(field) {
+    return this.query().groupBy(field);
+  }
+  perPage(n) {
+    return this.query().perPage(n);
+  }
+  param(key, value) {
+    return this.query().param(key, value);
+  }
+  // --- terminal proxies over the whole collection --------------------------
+  count() {
+    return this.query().count();
+  }
+  all(opts) {
+    return this.query().all(opts);
+  }
+  paginate(opts) {
+    return this.query().paginate(opts);
+  }
+  toArray(opts) {
+    return this.query().toArray(opts);
+  }
+  groups(field) {
+    return this.query().groups(field);
+  }
+  estimateCost(opts) {
+    return this.query().estimateCost(opts);
+  }
+  export(path, opts) {
+    return this.query().export(path, opts);
+  }
+  // --- single & batch retrieval --------------------------------------------
+  /**
+   * Fetch one entity by any supported ID: OpenAlex ID, DOI, ORCID, ROR, ISSN,
+   * Wikidata QID, PMID, MAG, or a full URL (all normalized automatically).
+   */
+  async get(id, opts = {}) {
+    const params = {};
+    if (opts.select) params.select = toCsv(opts.select);
+    const res = await this.http.request({
+      path: `${this.entityType}/${normalizeId(id)}`,
+      params,
+      requestType: "get",
+      noCache: opts.noCache
+    });
+    return res.data;
+  }
+  /**
+   * Fetch many entities by OpenAlex ID in as few calls as possible, batching
+   * into `ids.openalex` OR-filters (default 50 per request) run in parallel.
+   * Order is not guaranteed. For mixed external IDs, call {@link get} per ID.
+   */
+  async getMany(ids, opts = {}) {
+    if (ids.length === 0) return [];
+    const chunkSize = Math.min(Math.max(1, opts.chunkSize ?? 50), 100);
+    const select = opts.select ? toCsv(opts.select) : void 0;
+    const normalized = ids.map((id) => normalizeId(id));
+    const chunks = chunk(normalized, chunkSize);
+    const pages = await Promise.all(
+      chunks.map((c) => {
+        let q = this.query().filter({ "ids.openalex": c });
+        if (select) q = q.select(select);
+        return q.get({ perPage: chunkSize });
+      })
+    );
+    return pages.flatMap((p) => p.results);
+  }
+  /** A single random entity (optionally trimmed with `select`). */
+  async random(opts = {}) {
+    const params = {};
+    if (opts.select) params.select = toCsv(opts.select);
+    const res = await this.http.request({
+      path: `${this.entityType}/random`,
+      params,
+      requestType: "get",
+      noCache: true
+    });
+    return res.data;
+  }
+  /** Typeahead suggestions for this entity type. */
+  async autocomplete(q) {
+    const res = await this.http.request({
+      path: `autocomplete/${this.entityType}`,
+      params: { q },
+      requestType: "autocomplete"
+    });
+    return res.data.results;
+  }
+};
+function toCsv(v) {
+  return Array.isArray(v) ? v.join(",") : v;
+}
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+// src/works.ts
+var CONTENT_BASE_URL = "https://content.openalex.org";
+var WorksEndpoint = class extends EntityEndpoint {
+  constructor(http) {
+    super(http, "works");
+  }
+  /** Works that **cite** the given work (incoming citations). */
+  citedBy(workId) {
+    return this.filter({ cites: normalizeId(workId) });
+  }
+  /** Works the given work **cites** — its references (outgoing citations). */
+  references(workId) {
+    return this.filter({ cited_by: normalizeId(workId) });
+  }
+  /** Works OpenAlex considers related to the given work. */
+  related(workId) {
+    return this.filter({ related_to: normalizeId(workId) });
+  }
+  /** Only works that have a downloadable cached PDF. */
+  withPdf() {
+    return this.filter({ "has_content.pdf": true });
+  }
+  /** Only works that have a downloadable TEI-XML (Grobid) parse. */
+  withXml() {
+    return this.filter({ "has_content.grobid_xml": true });
+  }
+  /** The content-host URL for a work's full text (api_key redacted). */
+  fulltextUrl(workId, format = "pdf") {
+    return this.http.authorizeUrl(this.rawFulltextUrl(workId, format)).redacted;
+  }
+  /**
+   * Download a work's cached full text (PDF or TEI-XML). Costs $0.01/call and
+   * is budget-tracked. Pass `dest` to stream to a file, otherwise get bytes.
+   */
+  async downloadFulltext(workId, opts = {}) {
+    const { url, redacted } = this.http.authorizeUrl(
+      this.rawFulltextUrl(workId, opts.format ?? "pdf")
+    );
+    const res = await this.http.download({
+      url,
+      redacted,
+      requestType: "download",
+      dest: opts.dest,
+      signal: opts.signal
+    });
+    return { bytes: res.bytes, path: res.path, contentType: res.contentType };
+  }
+  rawFulltextUrl(workId, format) {
+    const id = bareWorkId(normalizeId(workId));
+    const ext = format === "xml" ? "grobid-xml" : "pdf";
+    return `${CONTENT_BASE_URL}/works/${id}.${ext}`;
+  }
+  /**
+   * One-hop citation neighbourhood: the work plus its references and citers.
+   * Bounded by `limit` on each side to keep the cost predictable.
+   */
+  async citationGraph(workId, opts = {}) {
+    const limit = opts.limit ?? 50;
+    const select = opts.select;
+    const [seed, references, citedBy] = await Promise.all([
+      this.get(workId, select ? { select } : {}),
+      this.references(workId).toArray({ maxResults: limit, perPage: Math.min(limit, 200) }),
+      this.citedBy(workId).toArray({ maxResults: limit, perPage: Math.min(limit, 200) })
+    ]);
+    return { seed, references, citedBy };
+  }
+};
+function bareWorkId(normalized) {
+  const m = /(W\d+)/i.exec(normalized);
+  return m ? m[1].toUpperCase() : normalized;
+}
+
+// src/snapshot.ts
+var SNAPSHOT_BASE_URL = "https://openalex.s3.amazonaws.com";
+var SNAPSHOT_S3_URI = "s3://openalex";
+var SnapshotClient = class {
+  baseUrl;
+  format;
+  fetchImpl;
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl ?? SNAPSHOT_BASE_URL).replace(/\/+$/, "");
+    this.format = opts.format ?? "jsonl";
+    const globalFetch = typeof fetch !== "undefined" ? fetch : void 0;
+    const impl = opts.fetch ?? globalFetch;
+    if (!impl) throw new OpenAlexError("No fetch available for SnapshotClient (Node 18+ or pass `fetch`).");
+    this.fetchImpl = impl;
+  }
+  /** Convert an `s3://openalex/KEY` URL to a public HTTPS URL. */
+  s3ToHttps(s3Url) {
+    const m = /^s3:\/\/([^/]+)\/(.+)$/.exec(s3Url);
+    if (!m) return s3Url;
+    if (m[1] === "openalex") return `${this.baseUrl}/${m[2]}`;
+    return `https://${m[1]}.s3.amazonaws.com/${m[2]}`;
+  }
+  manifestUrl(entity) {
+    return `${this.baseUrl}/data/${this.format}/${entity}/manifest.json`;
+  }
+  combinedManifestUrl() {
+    return `${this.baseUrl}/data/${this.format}/manifest.json`;
+  }
+  /** `aws s3 sync` command to download the whole snapshot or one entity. */
+  awsSyncCommand(entity, dest = "openalex-snapshot") {
+    if (!entity) return `aws s3 sync "${SNAPSHOT_S3_URI}" "${dest}" --no-sign-request`;
+    const key = `data/${this.format}/${entity}`;
+    return `aws s3 sync "${SNAPSHOT_S3_URI}/${key}" "${dest}/${key}" --no-sign-request`;
+  }
+  /** Fetch and normalize an entity's manifest. */
+  async manifest(entity) {
+    const url = this.manifestUrl(entity);
+    const raw = await this.getJson(url);
+    const files = (raw.files ?? []).map((f) => this.toFileEntry(f));
+    return {
+      entity: raw.entity ?? entity,
+      format: raw.format ?? this.format,
+      date: raw.date,
+      recordCount: raw.record_count ?? files.reduce((a, f) => a + f.recordCount, 0),
+      contentLength: raw.content_length ?? files.reduce((a, f) => a + f.contentLength, 0),
+      files
+    };
+  }
+  /** Per-entity totals from the combined manifest (no per-file list). */
+  async totals() {
+    const raw = await this.getJson(this.combinedManifestUrl());
+    return (raw.entities ?? []).map((e) => ({
+      entity: e.entity,
+      recordCount: e.record_count,
+      contentLength: e.content_length
+    }));
+  }
+  /** Totals for a single entity (cheap-ish: reads combined manifest). */
+  async entityTotals(entity) {
+    return (await this.totals()).find((t) => t.entity === entity);
+  }
+  /**
+   * Compare a filtered API extraction against downloading the whole snapshot.
+   * Pass the {@link CostEstimate} from `query.estimateCost()` plus the entity.
+   */
+  async plan(apiEstimate, entity, opts = {}) {
+    let totals;
+    if (opts.fetchTotals !== false) {
+      try {
+        totals = await this.entityTotals(entity);
+      } catch {
+        totals = void 0;
+      }
+    }
+    const apiCostUsd = apiEstimate.totalCostUsd;
+    const fraction = totals ? apiEstimate.matchingResults / totals.recordCount : void 0;
+    const recommendSnapshot = apiCostUsd >= 1 || fraction !== void 0 && fraction > 0.2;
+    const rationale = recommendSnapshot ? `Your extraction (${apiEstimate.matchingResults.toLocaleString()} results) would cost ~$${apiCostUsd.toFixed(
+      4
+    )} via the API` + (totals ? `, and covers ${((fraction ?? 0) * 100).toFixed(1)}% of all ${entity}. The full ${entity} snapshot (${fmtBytes(
+      totals.contentLength
+    )}, ${totals.recordCount.toLocaleString()} records) is free.` : `. The full ${entity} snapshot is free.`) : `Only ${apiEstimate.matchingResults.toLocaleString()} results (~$${apiCostUsd.toFixed(
+      4
+    )}) \u2014 cheaper/faster to pull the filtered subset via the API than to download the whole ${entity} snapshot.`;
+    return {
+      entity,
+      apiResults: apiEstimate.matchingResults,
+      apiCalls: apiEstimate.pageCalls,
+      apiCostUsd,
+      snapshotCostUsd: 0,
+      snapshotRecords: totals?.recordCount,
+      snapshotBytes: totals?.contentLength,
+      awsCommand: this.awsSyncCommand(entity, opts.dest),
+      recommendation: recommendSnapshot ? "snapshot" : "api",
+      rationale
+    };
+  }
+  /**
+   * Stream entities straight from the public snapshot (gunzip + NDJSON), at $0.
+   * Reads the manifest, then each gzipped part over HTTPS.
+   */
+  async *stream(entity, opts = {}) {
+    const manifest = await this.manifest(entity);
+    const startPart = opts.startPart ?? 0;
+    const endPart = opts.maxParts !== void 0 ? Math.min(manifest.files.length, startPart + opts.maxParts) : manifest.files.length;
+    const maxRecords = opts.maxRecords ?? Infinity;
+    let emitted = 0;
+    for (let i = startPart; i < endPart; i++) {
+      const file = manifest.files[i];
+      let recordsThisPart = 0;
+      for await (const record of streamGzippedNdjson(this.fetchImpl, file.httpsUrl, opts.signal)) {
+        recordsThisPart++;
+        if (opts.filter && !opts.filter(record)) continue;
+        yield record;
+        emitted++;
+        if (emitted >= maxRecords) {
+          opts.onPart?.({ index: i, total: manifest.files.length, url: file.httpsUrl, records: recordsThisPart });
+          return;
+        }
+      }
+      opts.onPart?.({ index: i, total: manifest.files.length, url: file.httpsUrl, records: recordsThisPart });
+    }
+  }
+  toFileEntry(f) {
+    return {
+      s3Url: f.url,
+      httpsUrl: this.s3ToHttps(f.url),
+      contentLength: f.meta?.content_length ?? 0,
+      recordCount: f.meta?.record_count ?? 0
+    };
+  }
+  async getJson(url) {
+    const res = await this.fetchImpl(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+      throw new OpenAlexError(`Snapshot request failed (${res.status}) [${url}]`, {
+        status: res.status,
+        url
+      });
+    }
+    return await res.json();
+  }
+};
+async function* streamGzippedNdjson(fetchImpl, url, signal) {
+  const res = await fetchImpl(url, signal ? { signal } : {});
+  if (!res.ok || !res.body) {
+    throw new OpenAlexError(`Snapshot part failed (${res.status}) [${url}]`, { status: res.status, url });
+  }
+  const textStream = res.body.pipeThrough(new DecompressionStream("gzip")).pipeThrough(new TextDecoderStream());
+  const reader = textStream.getReader();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += value;
+      let nl;
+      while ((nl = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (line.trim()) yield JSON.parse(line);
+      }
+    }
+    if (buffer.trim()) yield JSON.parse(buffer);
+  } finally {
+    reader.releaseLock();
+  }
+}
+function fmtBytes(n) {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let v = n;
+  let u = 0;
+  while (v >= 1024 && u < units.length - 1) {
+    v /= 1024;
+    u++;
+  }
+  return `${v.toFixed(v >= 10 || u === 0 ? 0 : 1)} ${units[u]}`;
+}
+
+// src/planner.ts
+async function planExtraction(snapshot, query, opts = {}) {
+  const perPage = opts.perPage ?? 200;
+  const est = await query.estimateCost({ perPage, strategy: "cursor" });
+  const count = est.matchingResults;
+  const withinBasic = count <= BASIC_PAGING_MAX_RESULTS;
+  let strategy = withinBasic ? "parallel-basic" : "cursor";
+  let useSnapshot = false;
+  let snapshotAwsCommand;
+  const threshold = opts.snapshotThresholdUsd ?? 1;
+  if (est.totalCostUsd >= threshold) {
+    const plan = await snapshot.plan(est, query.entityType);
+    snapshotAwsCommand = plan.awsCommand;
+    useSnapshot = plan.recommendation === "snapshot";
+    if (useSnapshot) strategy = "snapshot";
+  }
+  const dollars = `$${est.totalCostUsd.toFixed(4)}`;
+  const rationale = useSnapshot ? `~${count.toLocaleString()} results \u2248 ${dollars} via API \u2014 download the free snapshot instead.` : withinBasic ? `${count.toLocaleString()} results fit basic paging (\u226410k): parallel page fetches at per-page ${perPage} are fastest (~${dollars}).` : `${count.toLocaleString()} results exceed 10k: cursor streaming at per-page ${perPage} (~${dollars}).`;
+  return {
+    entity: query.entityType,
+    matchingResults: count,
+    requestType: est.requestType,
+    recommendedPerPage: perPage,
+    recommendedStrategy: strategy,
+    estimate: est,
+    useSnapshot,
+    snapshotAwsCommand,
+    rationale
+  };
+}
+
+// src/ngrams.ts
+async function fetchNgrams(http, workId) {
+  const res = await http.request({
+    path: `works/${normalizeId(workId)}/ngrams`,
+    requestType: "get"
+  });
+  return res.data;
+}
+
+// src/client.ts
+var OpenAlexClient = class {
+  config;
+  http;
+  /** Live spend/budget tracker, updated from every response. */
+  usage;
+  /** Free bulk-data snapshot bridge (manifest, cost comparison, streaming). */
+  snapshot;
+  works;
+  authors;
+  sources;
+  institutions;
+  topics;
+  keywords;
+  publishers;
+  funders;
+  constructor(config = {}) {
+    this.config = resolveConfig(config);
+    this.usage = new UsageTracker(Boolean(this.config.apiKey), this.config.dailyBudgetUsd);
+    this.http = new HttpClient(this.config, this.usage);
+    this.snapshot = new SnapshotClient({ fetch: this.config.fetch });
+    this.works = new WorksEndpoint(this.http);
+    this.authors = new EntityEndpoint(this.http, "authors");
+    this.sources = new EntityEndpoint(this.http, "sources");
+    this.institutions = new EntityEndpoint(this.http, "institutions");
+    this.topics = new EntityEndpoint(this.http, "topics");
+    this.keywords = new EntityEndpoint(this.http, "keywords");
+    this.publishers = new EntityEndpoint(this.http, "publishers");
+    this.funders = new EntityEndpoint(this.http, "funders");
+  }
+  /** Cross-entity typeahead. Optionally scope with `entityType`. */
+  async autocomplete(q, entityType) {
+    const path = entityType ? `autocomplete/${entityType}` : "autocomplete";
+    const res = await this.http.request({
+      path,
+      params: { q },
+      requestType: "autocomplete"
+    });
+    return res.data.results;
+  }
+  /** N-grams for a Work. */
+  ngrams(workId) {
+    return fetchNgrams(this.http, workId);
+  }
+  /**
+   * Decide API vs free snapshot for a query: estimates the API cost, then
+   * compares against downloading the whole entity's snapshot ($0).
+   */
+  async snapshotPlan(query) {
+    const estimate = await query.estimateCost();
+    return this.snapshot.plan(estimate, query.entityType);
+  }
+  /**
+   * Cost-optimal plan for extracting a query: recommends per-page, cursor-vs-
+   * parallel strategy, and whether the free snapshot beats the API.
+   */
+  planExtraction(query, opts) {
+    return planExtraction(this.snapshot, query, opts);
+  }
+  /** Escape hatch: issue a raw GET against any path with any params. */
+  async request(path, params = {}, opts = {}) {
+    const res = await this.http.request({
+      path,
+      params,
+      requestType: opts.requestType ?? "list",
+      noCache: opts.noCache
+    });
+    return res.data;
+  }
+  /** Point-in-time usage snapshot. */
+  usageSnapshot() {
+    return this.usage.snapshot();
+  }
+  /** Human-readable spend/budget report. */
+  usageReport() {
+    return this.usage.report();
+  }
+  /** Reset the session usage counters (does not affect OpenAlex's daily total). */
+  resetUsage() {
+    this.usage.reset();
+  }
+};
+
+// src/cli.ts
+var ENTITIES = [
+  "works",
+  "authors",
+  "sources",
+  "institutions",
+  "topics",
+  "keywords",
+  "publishers",
+  "funders"
+];
+function parseArgs(argv) {
+  const _ = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next === void 0 || next.startsWith("--")) {
+          flags[key] = true;
+        } else {
+          flags[key] = next;
+          i++;
+        }
+      }
+    } else {
+      _.push(a);
+    }
+  }
+  return { _, flags };
+}
+async function runCli(argv, deps = {}) {
+  const out = deps.stdout ?? ((s) => process.stdout.write(s + "\n"));
+  const err = deps.stderr ?? ((s) => process.stderr.write(s + "\n"));
+  const { _, flags } = parseArgs(argv);
+  const cmd = _[0];
+  if (!cmd || flags.help || cmd === "help") {
+    out(HELP);
+    return 0;
+  }
+  const client = deps.client ?? new OpenAlexClient({
+    apiKey: str(flags["api-key"]),
+    mailto: str(flags.mailto)
+  });
+  const json = Boolean(flags.json);
+  try {
+    if (cmd === "snapshot") return await snapshotCmd(_, flags, client, out, json);
+    if (cmd === "fulltext") return await fulltextCmd(_, flags, client, out);
+    if (cmd === "get") return await getCmd(_, flags, client, out);
+    if (ENTITIES.includes(cmd)) {
+      return await entityCmd(cmd, flags, client, out, json);
+    }
+    err(`Unknown command: ${cmd}`);
+    out(HELP);
+    return 1;
+  } catch (e) {
+    err(`Error: ${e.message}`);
+    return 1;
+  }
+}
+function endpoint(client, entity) {
+  const ep = client[entity];
+  if (!ep) throw new Error(`Unknown entity: ${entity}. One of: ${ENTITIES.join(", ")}`);
+  return ep;
+}
+function buildQuery(client, entity, flags) {
+  let q = endpoint(client, entity).query();
+  if (str(flags.filter)) q = q.param("filter", str(flags.filter));
+  if (str(flags.search)) q = q.search(str(flags.search));
+  if (str(flags.select)) q = q.select(str(flags.select));
+  if (str(flags.sort)) q = q.sort(str(flags.sort));
+  if (str(flags["per-page"])) q = q.perPage(Number(flags["per-page"]));
+  return q;
+}
+async function entityCmd(entity, flags, client, out, json) {
+  const q = buildQuery(client, entity, flags);
+  const limit = flags.limit !== void 0 ? Number(flags.limit) : void 0;
+  const parallel = Boolean(flags.parallel);
+  if (flags.count) {
+    const n = await q.count();
+    out(json ? JSON.stringify({ count: n }) : `${n}`);
+    return 0;
+  }
+  if (flags.estimate) {
+    const e = await q.estimateCost();
+    out(json ? JSON.stringify(e, null, 2) : formatEstimate(e));
+    return 0;
+  }
+  if (str(flags.export)) {
+    const res = await q.export(str(flags.export), { maxResults: limit, parallel });
+    out(json ? JSON.stringify(res) : `Wrote ${res.count} ${entity} to ${res.path}`);
+    return 0;
+  }
+  const items = await q.toArray({ maxResults: limit ?? 25, parallel });
+  out(JSON.stringify(items, null, json ? 0 : 2));
+  return 0;
+}
+async function getCmd(_, flags, client, out) {
+  const entity = _[1];
+  const id = _[2];
+  if (!entity || !id) throw new Error("usage: oaw get <entity> <id> [--select ...]");
+  const ep = endpoint(client, entity);
+  const item = await ep.get(id, str(flags.select) ? { select: str(flags.select) } : {});
+  out(JSON.stringify(item, null, 2));
+  return 0;
+}
+async function snapshotCmd(_, flags, client, out, json) {
+  const sub = _[1];
+  if (sub === "totals") {
+    const entity = _[2];
+    if (entity) {
+      const t = await client.snapshot.entityTotals(entity);
+      out(json ? JSON.stringify(t) : formatTotals(t));
+    } else {
+      const ts = await client.snapshot.totals();
+      out(json ? JSON.stringify(ts, null, 2) : ts.map(formatTotals).join("\n"));
+    }
+    return 0;
+  }
+  if (sub === "plan") {
+    const entity = _[2];
+    if (!entity) throw new Error("usage: oaw snapshot plan <entity> [--filter ...]");
+    const plan = await client.snapshotPlan(buildQuery(client, entity, flags));
+    out(json ? JSON.stringify(plan, null, 2) : formatPlan(plan));
+    return 0;
+  }
+  if (sub === "stream") {
+    const entity = _[2];
+    if (!entity) throw new Error("usage: oaw snapshot stream <entity> [--limit N] [--export FILE]");
+    const limit = flags.limit !== void 0 ? Number(flags.limit) : 10;
+    const gen = client.snapshot.stream(entity, { maxRecords: limit });
+    if (str(flags.export)) {
+      const { exportToFile: exportToFile2 } = await Promise.resolve().then(() => (init_export(), export_exports));
+      const res = await exportToFile2(gen, str(flags.export));
+      out(`Wrote ${res.count} ${entity} to ${res.path}`);
+      return 0;
+    }
+    for await (const rec of gen) out(JSON.stringify(rec));
+    return 0;
+  }
+  throw new Error("usage: oaw snapshot <totals|plan|stream> [entity] [flags]");
+}
+async function fulltextCmd(_, flags, client, out) {
+  const id = _[1];
+  if (!id) throw new Error("usage: oaw fulltext <workId> [--format pdf|xml] [--out FILE]");
+  const format = flags.format === "xml" ? "xml" : "pdf";
+  const dest = str(flags.out);
+  if (!dest) {
+    out(client.works.fulltextUrl(id, format));
+    return 0;
+  }
+  const res = await client.works.downloadFulltext(id, { format, dest });
+  out(`Saved ${format.toUpperCase()} to ${res.path}`);
+  return 0;
+}
+function str(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function formatEstimate(e) {
+  return `results:   ${e.matchingResults.toLocaleString()}
+api calls: ${e.pageCalls}
+est. cost: $${e.totalCostUsd.toFixed(4)}` + (e.cappedByBasicPaging ? "  (basic-paging capped at 10k)" : "");
+}
+function formatTotals(t) {
+  if (!t) return "(unknown entity)";
+  const gb = (t.contentLength / 1e9).toFixed(1);
+  return `${t.entity.padEnd(14)} ${t.recordCount.toLocaleString().padStart(14)} records   ${gb} GB`;
+}
+function formatPlan(p) {
+  return `recommendation: ${p.recommendation.toUpperCase()}
+${p.rationale}
+api cost: ~$${p.apiCostUsd.toFixed(4)}   snapshot: $0
+bulk download: ${p.awsCommand}`;
+}
+var HELP = `oaw: OpenAlex CLI (open-alex-wrapper)
+
+Usage:
+  oaw <entity> [flags]                 query an entity (works, authors, sources,
+                                       institutions, topics, keywords, publishers, funders)
+  oaw get <entity> <id> [--select ..]  fetch one entity by any ID/DOI/ORCID/...
+  oaw snapshot totals [entity]         snapshot record counts & sizes
+  oaw snapshot plan <entity> [flags]   API $ cost vs free snapshot
+  oaw snapshot stream <entity> [flags] stream the free snapshot ($0)
+  oaw fulltext <workId> [flags]        download full text (PDF/XML) or print its URL
+
+Query flags:
+  --filter "k:v,k2:v2"   raw OpenAlex filter    --search "text"
+  --select id,title      trim fields            --sort field:desc
+  --per-page N           page size (\u2264200)       --limit N   cap results
+  --parallel             fast parallel paging    --export FILE  write JSONL/CSV/JSON
+  --count                just the match count    --estimate  dollar cost estimate
+
+Global flags:
+  --api-key KEY   (or OPENALEX_API_KEY)   --mailto you@x.com   --json   --help`;
+function isMain() {
+  const entry = process.argv[1] ?? "";
+  return /(?:^|[\\/])(cli|oaw)(\.(c|m)?js)?$/.test(entry);
+}
+if (isMain()) {
+  runCli(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (e) => {
+      process.stderr.write(`Fatal: ${e.message}
+`);
+      process.exit(1);
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseArgs,
+  runCli
+});
+//# sourceMappingURL=cli.cjs.map