mcp-rule34 0.1.0

package/dist/rule34/client.js

@@ -0,0 +1,811 @@
+// src/errors.ts
+var Rule34Error = class extends Error {
+  constructor(code, text, details = {}) {
+    super(`[${code}] ${text}`);
+    this.code = code;
+    this.details = details;
+    this.name = "Rule34Error";
+  }
+  code;
+  details;
+};
+var ISSUES_URL = "https://github.com/smeet666/mcp-rule34/issues";
+function invalidInput(message, hint) {
+  return new Rule34Error("invalid_input", message, hint ? { hint } : {});
+}
+function missingCredentials(url) {
+  return new Rule34Error(
+    "invalid_input",
+    "rule34.xxx answered that this request carries no valid API credentials.",
+    {
+      url,
+      hint: "Set RULE34_USER_ID and RULE34_API_KEY in the env block of this server's entry in your MCP client configuration. Both are shown under 'API Access Credentials' at https://rule34.xxx/index.php?page=account&s=options once you are signed in. The site issues one key per person, so use your own rather than sharing one."
+    }
+  );
+}
+function notFound(url) {
+  return new Rule34Error("not_found", "rule34.xxx has nothing at this address.", {
+    url,
+    status: 404,
+    hint: "Check the post id. Ids come from a search; they are not stable to guess by hand."
+  });
+}
+function rateLimited(url, retryAfterMs) {
+  return new Rule34Error(
+    "rate_limited",
+    "rule34.xxx is refusing requests from this client for now (HTTP 429). This does NOT mean the search found nothing.",
+    {
+      url,
+      status: 429,
+      retryAfterMs,
+      hint: "Wait before asking again. If it keeps happening, raise RULE34_MIN_INTERVAL_MS in your MCP client configuration to slow this server down."
+    }
+  );
+}
+function parseFailure(url, what) {
+  return new Rule34Error(
+    "parse_failure",
+    `The request was answered, but not with the document this route publishes (${what}).`,
+    { url, hint: `Please report this, with the query you used, at ${ISSUES_URL}` }
+  );
+}
+function upstreamFailure(url, message) {
+  return new Rule34Error("network_error", `rule34.xxx reported a failure: ${message}`, {
+    url,
+    hint: "This is the site's own message. Waiting and asking again is usually the only remedy."
+  });
+}
+
+// src/rule34/cache.ts
+var TtlLruCache = class {
+  constructor(maxEntries, ttlMs) {
+    this.maxEntries = maxEntries;
+    this.ttlMs = ttlMs;
+  }
+  maxEntries;
+  ttlMs;
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (Date.now() >= entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.maxEntries <= 0 || this.ttlMs <= 0) {
+      return;
+    }
+    this.store.delete(key);
+    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next();
+      if (oldest.done) {
+        break;
+      }
+      this.store.delete(oldest.value);
+    }
+  }
+  /** The keys currently held, in least recently used order. */
+  keys() {
+    return [...this.store.keys()];
+  }
+  get size() {
+    return this.store.size;
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/rule34/rateLimiter.ts
+var DEFAULT_MAX_INTERVAL_MS = 3e4;
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  /** Tail of the queue: each task chains onto the previous one. */
+  tail = Promise.resolve();
+  lastStart = 0;
+  constructor(options) {
+    this.baseIntervalMs = Math.max(0, options.minIntervalMs);
+    this.maxIntervalMs = Math.max(
+      this.baseIntervalMs,
+      options.maxIntervalMs ?? DEFAULT_MAX_INTERVAL_MS
+    );
+    this.intervalMs = this.baseIntervalMs;
+  }
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /** Queue a task. Tasks run in call order, one at a time. */
+  schedule(task) {
+    const run = this.tail.then(async () => task());
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /**
+   * Wait for this request's slot, then claim it.
+   *
+   * Called once per upstream request rather than once per task, because a task
+   * runs a whole retry chain: stamping only its start would let the next task
+   * follow the chain's last request with no gap at all.
+   */
+  async beforeRequest() {
+    await this.waitForSlot();
+    this.lastStart = Date.now();
+  }
+  /** Called after the site answers that it is being asked too often. */
+  penalize() {
+    const next = this.intervalMs === 0 ? 500 : this.intervalMs * 2;
+    this.intervalMs = Math.min(this.maxIntervalMs, next);
+  }
+  /** Called after a success, so one push-back does not slow things down forever. */
+  relax() {
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
+  }
+  async waitForSlot() {
+    if (this.intervalMs === 0 || this.lastStart === 0) {
+      return;
+    }
+    const elapsed = Date.now() - this.lastStart;
+    const remaining = Math.min(this.intervalMs, this.intervalMs - elapsed);
+    if (remaining > 0) {
+      await sleep(remaining);
+    }
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/rule34/urls.ts
+var API_URL = "https://api.rule34.xxx/index.php";
+var SITE_URL = "https://rule34.xxx/index.php";
+var MAX_LIMIT = 1e3;
+var MEDIA_TOKENS = {
+  image: ["-video", "-animated"],
+  animated: ["animated", "-video"],
+  video: ["video"],
+  any: []
+};
+var SORT_TOKENS = {
+  score: "sort:score:desc",
+  id: "sort:id:desc",
+  updated: "sort:updated:desc",
+  random: "sort:random"
+};
+var MAX_TAGS = 10;
+function normalizeTag(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    throw invalidInput(
+      "A tag is required.",
+      "Pass the tag to search for, such as 'black hair' or 'asuka langley sohryu'."
+    );
+  }
+  if (trimmed.startsWith("-")) {
+    throw invalidInput(
+      `"${trimmed}" starts with '-', which means "without this tag" on rule34.xxx.`,
+      "This tool searches for a tag. Pass the tag itself, without the leading dash."
+    );
+  }
+  if (trimmed.includes(":")) {
+    throw invalidInput(
+      `"${trimmed}" carries a ':', which rule34.xxx reads as a filter rather than as a tag.`,
+      "Filters are separate arguments here: use 'rating', 'sort' and 'media_type'."
+    );
+  }
+  return trimmed.replace(/\s+/g, "_").toLowerCase();
+}
+function normalizeList(raw, argument) {
+  const tags = (raw ?? []).map(normalizeTag);
+  if (tags.length > MAX_TAGS) {
+    throw invalidInput(
+      `'${argument}' holds ${tags.length} tags, and this tool searches at most ${MAX_TAGS} at a time.`,
+      "Search on the tags that narrow the most, then look through the results."
+    );
+  }
+  return tags;
+}
+function normalizeSearch(search) {
+  const required = normalizeList(search.tags, "tags");
+  if (required.length === 0) {
+    throw invalidInput(
+      "At least one tag is required.",
+      "Pass the tags to search for, such as ['asuka langley sohryu', 'black hair']."
+    );
+  }
+  const alternatives = normalizeList(search.anyOf, "any_of");
+  const excluded = normalizeList(search.exclude, "exclude");
+  const contradiction = required.find((tag) => excluded.includes(tag));
+  if (contradiction) {
+    throw invalidInput(
+      `'${contradiction}' is both required and excluded, so no post can match.`,
+      "Remove it from one of the two lists."
+    );
+  }
+  return { required, alternatives, excluded };
+}
+function buildSearchQuery(search) {
+  const { required, alternatives, excluded } = normalizeSearch(search);
+  const tokens = [...required];
+  if (alternatives.length === 1) {
+    tokens.push(...alternatives);
+  } else if (alternatives.length > 1) {
+    tokens.push(`( ${alternatives.join(" ~ ")} )`);
+  }
+  tokens.push(...excluded.map((tag) => `-${tag}`), ...MEDIA_TOKENS[search.mediaType ?? "any"]);
+  if (search.rating) {
+    tokens.push(`rating:${search.rating}`);
+  }
+  if (search.sort) {
+    tokens.push(SORT_TOKENS[search.sort]);
+  }
+  return tokens.join(" ");
+}
+function buildPostSearchUrl(search, credentials) {
+  if (!Number.isInteger(search.limit) || search.limit < 1 || search.limit > MAX_LIMIT) {
+    throw invalidInput(
+      `limit must be a whole number between 1 and ${MAX_LIMIT}, and ${search.limit} is not.`,
+      `rule34.xxx serves at most ${MAX_LIMIT} posts in one request.`
+    );
+  }
+  if (!Number.isInteger(search.page) || search.page < 1) {
+    throw invalidInput(`page must be a whole number from 1 upwards, and ${search.page} is not.`);
+  }
+  const query = encodeURIComponent(buildSearchQuery(search));
+  const pid = search.page - 1;
+  return `${API_URL}?page=dapi&s=post&q=index&tags=${query}&limit=${search.limit}&pid=${pid}&api_key=${encodeURIComponent(credentials.apiKey)}&user_id=${encodeURIComponent(credentials.userId)}`;
+}
+function buildTagLookupUrl(tag, credentials) {
+  return `${API_URL}?page=dapi&s=tag&q=index&name=${encodeURIComponent(normalizeTag(tag))}&api_key=${encodeURIComponent(credentials.apiKey)}&user_id=${encodeURIComponent(credentials.userId)}`;
+}
+function readPostPageUrl(raw) {
+  let parsed;
+  try {
+    parsed = new URL(raw.trim());
+  } catch {
+    throw invalidInput(
+      `"${raw}" is not a URL.`,
+      "Pass a link to a post's page, such as https://rule34.xxx/index.php?page=post&s=view&id=2195419"
+    );
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (host !== "rule34.xxx" && !host.endsWith(".rule34.xxx")) {
+    throw invalidInput(
+      `"${raw}" is not a rule34.xxx address.`,
+      "This tool reads posts on rule34.xxx. A link elsewhere names no post it holds."
+    );
+  }
+  if (parsed.searchParams.get("page") !== "post" || parsed.searchParams.get("s") !== "view") {
+    throw invalidInput(
+      `"${raw}" is a rule34.xxx address, but not a post's page.`,
+      "A post's page looks like https://rule34.xxx/index.php?page=post&s=view&id=2195419"
+    );
+  }
+  const id = Number(parsed.searchParams.get("id"));
+  if (!Number.isInteger(id) || id < 1) {
+    throw invalidInput(`"${raw}" carries no post id.`);
+  }
+  return id;
+}
+function resolvePostRef(ref) {
+  const fromUrl = ref.url === void 0 ? null : readPostPageUrl(ref.url);
+  const fromId = ref.id;
+  if (fromId !== void 0) {
+    if (!Number.isInteger(fromId) || fromId < 1) {
+      throw invalidInput(`id must be a whole number from 1 upwards, and ${fromId} is not.`);
+    }
+    if (fromUrl !== null && fromUrl !== fromId) {
+      throw invalidInput(
+        `'id' names post ${fromId} and 'url' names post ${fromUrl}, so they cannot both be read.`,
+        "Pass one of the two, or make them agree."
+      );
+    }
+    return fromId;
+  }
+  if (fromUrl !== null) {
+    return fromUrl;
+  }
+  throw invalidInput(
+    "Either 'id' or 'url' must be given.",
+    "Pass the numeric post id, or a link to the post's page on rule34.xxx."
+  );
+}
+function buildPostByIdXmlUrl(id, credentials) {
+  return `${API_URL}?page=dapi&s=post&q=index&id=${id}${credentialsQuery(credentials)}`;
+}
+function buildPostByIdJsonUrl(id, credentials) {
+  return `${API_URL}?page=dapi&s=post&q=index&id=${id}&json=1&fields=tag_info${credentialsQuery(credentials)}`;
+}
+function credentialsQuery(credentials) {
+  return `&api_key=${encodeURIComponent(credentials.apiKey)}&user_id=${encodeURIComponent(credentials.userId)}`;
+}
+function buildPostPageUrl(id) {
+  return `${SITE_URL}?page=post&s=view&id=${id}`;
+}
+function redactCredentials(url) {
+  return url.replace(/([?&]api_key=)[^&]*/gi, "$1REDACTED");
+}
+
+// src/rule34/http.ts
+var BACKOFF_BASE_MS = 2e3;
+var BACKOFF_FACTOR = 2;
+var BACKOFF_MAX_MS = 3e4;
+function backoffDelay(attempt, random = Math.random) {
+  const uncapped = BACKOFF_BASE_MS * BACKOFF_FACTOR ** attempt;
+  const capped = Math.min(BACKOFF_MAX_MS, uncapped);
+  return Math.round(capped * (0.5 + random() * 0.5));
+}
+async function fetchXml(url, deps) {
+  const { config, limiter, logger } = deps;
+  const doFetch = deps.fetchImpl ?? fetch;
+  const safeUrl = redactCredentials(url);
+  return await limiter.schedule(async () => {
+    let lastError;
+    let askedWaitMs = null;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+      if (attempt > 0) {
+        const delay = Math.min(askedWaitMs ?? backoffDelay(attempt - 1), BACKOFF_MAX_MS);
+        askedWaitMs = null;
+        logger.info(`retry ${attempt}/${config.maxRetries} in ${delay}ms for ${safeUrl}`);
+        await sleep(delay);
+      }
+      let status;
+      let body;
+      let retryAfterMs = null;
+      try {
+        await limiter.beforeRequest();
+        const response = await doFetch(url, {
+          headers: {
+            "User-Agent": config.userAgent,
+            Accept: "application/xml,text/xml;q=0.9,*/*;q=0.8"
+          },
+          redirect: "follow",
+          signal: AbortSignal.timeout(config.timeoutMs)
+        });
+        status = response.status;
+        retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+        body = await response.text();
+      } catch (error) {
+        lastError = asTransportError(error, safeUrl);
+        logger.debug(`${lastError.code} for ${safeUrl}: ${lastError.message}`);
+        continue;
+      }
+      if (status === 429) {
+        limiter.penalize();
+        logger.info(`rate limited on ${safeUrl}, interval now ${limiter.currentIntervalMs}ms`);
+        askedWaitMs = retryAfterMs;
+        lastError = rateLimited(safeUrl, retryAfterMs ?? backoffDelay(attempt));
+        continue;
+      }
+      if (status === 404) {
+        throw notFound(safeUrl);
+      }
+      if (status >= 500) {
+        lastError = new Rule34Error("network_error", `rule34.xxx returned HTTP ${status}.`, {
+          url: safeUrl,
+          status
+        });
+        continue;
+      }
+      if (status >= 400) {
+        throw new Rule34Error("network_error", `rule34.xxx refused the request (HTTP ${status}).`, {
+          url: safeUrl,
+          status
+        });
+      }
+      limiter.relax();
+      return body;
+    }
+    throw lastError ?? new Rule34Error("network_error", `Could not fetch ${safeUrl}.`, {
+      url: safeUrl
+    });
+  });
+}
+function parseRetryAfter(raw) {
+  if (!raw) {
+    return null;
+  }
+  const seconds = Number(raw.trim());
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1e3);
+  }
+  const when = Date.parse(raw);
+  if (Number.isNaN(when)) {
+    return null;
+  }
+  return Math.max(0, when - Date.now());
+}
+function asTransportError(error, safeUrl) {
+  if (error instanceof Rule34Error) {
+    return error;
+  }
+  const name = error instanceof Error ? error.name : "";
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new Rule34Error("timeout", "rule34.xxx did not answer in time.", {
+      url: safeUrl,
+      hint: "Raise RULE34_TIMEOUT_MS if this happens often on a slow connection."
+    });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new Rule34Error("network_error", `Could not reach rule34.xxx: ${message}`, {
+    url: safeUrl
+  });
+}
+
+// src/rule34/parsers/postDetail.ts
+var TYPES = {
+  tag: "general",
+  artist: "artist",
+  copyright: "copyright",
+  character: "character",
+  metadata: "metadata"
+};
+function parsePostDetail(body, url, id) {
+  const safeUrl = redactCredentials(url);
+  if (body.trim() === "") {
+    throw notFound(safeUrl);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw parseFailure(safeUrl, "the response is not JSON");
+  }
+  if (typeof parsed === "string") {
+    if (/authenticat/i.test(parsed)) {
+      throw missingCredentials(safeUrl);
+    }
+    throw upstreamFailure(safeUrl, parsed);
+  }
+  if (!Array.isArray(parsed)) {
+    throw parseFailure(safeUrl, "the response is not a list of posts");
+  }
+  const [raw] = parsed;
+  if (raw === void 0) {
+    throw notFound(safeUrl);
+  }
+  if (raw === null || typeof raw !== "object") {
+    throw parseFailure(safeUrl, "the first entry is not a post");
+  }
+  return readPost(raw, id);
+}
+function readPost(raw, askedFor) {
+  const id = readInteger(raw.id) ?? askedFor;
+  const tags = readString(raw.tags).split(/\s+/).filter((tag) => tag !== "");
+  return {
+    id,
+    postUrl: buildPostPageUrl(id),
+    fileUrl: readString(raw.file_url),
+    sampleUrl: readText(raw.sample_url),
+    previewUrl: readText(raw.preview_url),
+    width: readInteger(raw.width) ?? 0,
+    height: readInteger(raw.height) ?? 0,
+    md5: readString(raw.hash),
+    score: readInteger(raw.score) ?? 0,
+    rating: readString(raw.rating),
+    tags,
+    tagDetails: readTagDetails(raw.tag_info),
+    source: readText(raw.source),
+    // This route writes 0 where the XML writes an empty string, and 0 is a post
+    // id that belongs to somebody else.
+    parentId: nonZero(readInteger(raw.parent_id)),
+    owner: readText(raw.owner),
+    commentCount: readInteger(raw.comment_count),
+    status: readString(raw.status),
+    hasNotes: raw.has_notes === true,
+    changedAtUnix: readInteger(raw.change)
+  };
+}
+function readTagDetails(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => {
+    const info = entry ?? {};
+    const type = readString(info.type);
+    return {
+      name: readString(info.tag),
+      // A word this site has not documented is carried as it came: naming it
+      // something else would state a kind the site never wrote.
+      type: TYPES[type] ?? type,
+      postCount: readInteger(info.count) ?? 0
+    };
+  });
+}
+function nonZero(value) {
+  return value === null || value === 0 ? null : value;
+}
+function readString(value) {
+  return typeof value === "string" ? value : "";
+}
+function readText(value) {
+  const trimmed = readString(value).trim();
+  return trimmed === "" ? null : trimmed;
+}
+function readInteger(value) {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  const trimmed = readString(value).trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// src/rule34/parsers/document.ts
+import { XMLParser } from "fast-xml-parser";
+var parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  // Attribute values are converted one field at a time by each parser, so that
+  // an empty `parent_id` stays empty instead of becoming a number.
+  parseAttributeValue: false,
+  trimValues: true
+});
+function readDocument(xml, safeUrl) {
+  if (xml.trim() === "") {
+    throw parseFailure(safeUrl, "the response was empty");
+  }
+  let document;
+  try {
+    document = parser.parse(xml);
+  } catch (error) {
+    throw parseFailure(safeUrl, error instanceof Error ? error.message : "unreadable XML");
+  }
+  if (document === null || typeof document !== "object") {
+    throw parseFailure(safeUrl, "the response is not an XML document");
+  }
+  const parsed = document;
+  const failure = parsed.error;
+  if (failure !== void 0) {
+    const message = typeof failure === "string" ? failure : String(failure);
+    if (/authenticat/i.test(message)) {
+      throw missingCredentials(safeUrl);
+    }
+    throw upstreamFailure(safeUrl, message);
+  }
+  return parsed;
+}
+function toArray(value) {
+  if (value === void 0 || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+function readText2(value) {
+  const trimmed = value?.trim() ?? "";
+  return trimmed === "" ? null : trimmed;
+}
+function readInteger2(value) {
+  const trimmed = value?.trim() ?? "";
+  if (trimmed === "") {
+    return null;
+  }
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// src/rule34/parsers/posts.ts
+var RATINGS = {
+  e: "explicit",
+  q: "questionable",
+  s: "safe"
+};
+function parsePostList(xml, url) {
+  const safeUrl = redactCredentials(url);
+  const document = readDocument(xml, safeUrl);
+  const posts = document.posts;
+  if (posts === void 0 || posts === null || typeof posts !== "object") {
+    throw parseFailure(safeUrl, "no <posts> element");
+  }
+  const attributes = posts;
+  const total = readInteger2(attributes["@_count"]);
+  if (total === null) {
+    throw parseFailure(safeUrl, "the <posts> element carries no count");
+  }
+  return {
+    total,
+    offset: readInteger2(attributes["@_offset"]) ?? 0,
+    posts: toArray(attributes.post).map(readPost2)
+  };
+}
+function readPost2(attributes) {
+  const id = readInteger2(attributes["@_id"]) ?? 0;
+  const rating = attributes["@_rating"]?.trim() ?? "";
+  return {
+    id,
+    postUrl: buildPostPageUrl(id),
+    fileUrl: attributes["@_file_url"] ?? "",
+    sampleUrl: readText2(attributes["@_sample_url"]),
+    previewUrl: readText2(attributes["@_preview_url"]),
+    width: readInteger2(attributes["@_width"]) ?? 0,
+    height: readInteger2(attributes["@_height"]) ?? 0,
+    md5: attributes["@_md5"] ?? "",
+    score: readInteger2(attributes["@_score"]) ?? 0,
+    // An unknown letter is carried as it came: naming it would state a rating
+    // the site never wrote.
+    rating: RATINGS[rating] ?? rating,
+    tags: (attributes["@_tags"] ?? "").split(/\s+/).filter((tag) => tag !== ""),
+    source: readText2(attributes["@_source"]),
+    // The attribute is present and empty on a post with no parent, and 0 is a
+    // post id that belongs to somebody else.
+    parentId: readInteger2(attributes["@_parent_id"]),
+    creatorId: readInteger2(attributes["@_creator_id"]),
+    status: attributes["@_status"] ?? "",
+    hasChildren: attributes["@_has_children"] === "true",
+    hasComments: attributes["@_has_comments"] === "true",
+    hasNotes: attributes["@_has_notes"] === "true",
+    createdAt: readDate(attributes["@_created_at"]),
+    changedAtUnix: readInteger2(attributes["@_change"])
+  };
+}
+function readDate(value) {
+  const trimmed = value?.trim() ?? "";
+  if (trimmed === "") {
+    return null;
+  }
+  const parsed = Date.parse(trimmed);
+  return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
+}
+
+// src/rule34/parsers/tags.ts
+var TYPES2 = {
+  0: "general",
+  1: "artist",
+  3: "copyright",
+  4: "character",
+  5: "metadata"
+};
+function parseTagList(xml, url) {
+  const safeUrl = redactCredentials(url);
+  const document = readDocument(xml, safeUrl);
+  const tags = document.tags;
+  if (tags !== void 0 && tags !== null && typeof tags === "object") {
+    return toArray(tags.tag).map(readTag);
+  }
+  const lone = document.tag;
+  if (lone !== void 0 && lone !== null && typeof lone === "object") {
+    const attributes = lone;
+    return attributes["@_name"] === void 0 ? [] : [readTag(attributes)];
+  }
+  throw parseFailure(safeUrl, "no <tags> element");
+}
+function readTag(attributes) {
+  const typeCode = readInteger2(attributes["@_type"]);
+  return {
+    id: readInteger2(attributes["@_id"]) ?? 0,
+    name: attributes["@_name"] ?? "",
+    postCount: readInteger2(attributes["@_count"]) ?? 0,
+    // A number this site has not documented is left unnamed: calling it
+    // something would state a kind the site never wrote.
+    type: (typeCode === null ? void 0 : TYPES2[typeCode]) ?? "unknown",
+    typeCode,
+    ambiguous: attributes["@_ambiguous"] === "true"
+  };
+}
+
+// src/rule34/client.ts
+var Rule34Client = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.limiter = new RateLimiter({ minIntervalMs: deps.config.minIntervalMs });
+    this.cache = new TtlLruCache(deps.config.cacheMaxEntries, deps.config.cacheTtlMs);
+  }
+  deps;
+  limiter;
+  cache;
+  /** The addresses currently held, for a diagnostic to look at. */
+  cacheKeys() {
+    return this.cache.keys();
+  }
+  async searchPosts(search) {
+    const url = buildPostSearchUrl(search, this.credentials());
+    const { body, cached } = await this.read(url);
+    return { data: parsePostList(body, url), cached };
+  }
+  /**
+   * One post, read from both formats the API publishes.
+   *
+   * Neither format carries everything: the publication date and the uploader's
+   * numeric id come from the XML, and the uploader's name, the comment count
+   * and the tag types come from the JSON. Reading one of them would leave out
+   * what the other holds, so a fiche costs two reads of the site.
+   */
+  async getPost(ref) {
+    const credentials = this.credentials();
+    const id = resolvePostRef(ref);
+    const jsonUrl = buildPostByIdJsonUrl(id, credentials);
+    const json = await this.read(jsonUrl);
+    const detail = parsePostDetail(json.body, jsonUrl, id);
+    const xmlUrl = buildPostByIdXmlUrl(id, credentials);
+    const xml = await this.read(xmlUrl);
+    const [fromXml] = parsePostList(xml.body, xmlUrl).posts;
+    return {
+      data: {
+        ...detail,
+        createdAt: fromXml?.createdAt ?? null,
+        creatorId: fromXml?.creatorId ?? null,
+        hasComments: fromXml?.hasComments ?? (detail.commentCount ?? 0) > 0,
+        hasChildren: fromXml?.hasChildren ?? false
+      },
+      cached: json.cached && xml.cached
+    };
+  }
+  /** The tag under this exact name, or nothing when the site holds no such tag. */
+  async lookupTag(name) {
+    const url = buildTagLookupUrl(name, this.credentials());
+    const { body, cached } = await this.read(url);
+    const [tag] = parseTagList(body, url);
+    return { data: tag ?? null, cached };
+  }
+  /**
+   * Which of these names the site does not hold as a tag.
+   *
+   * A search of several tags that finds nothing says nothing about which tag
+   * emptied it, and a misspelled name is indistinguishable from a combination
+   * the site genuinely has nothing for. Each distinct name costs one request,
+   * which is why this is worth spending only once a search has come back empty.
+   */
+  async findUnknownTags(names) {
+    const distinct = [...new Set(names.map(normalizeTag))];
+    const unknown = [];
+    for (const name of distinct) {
+      const { data } = await this.lookupTag(name);
+      if (data === null) {
+        unknown.push(name);
+      }
+    }
+    return unknown;
+  }
+  credentials() {
+    const credentials = this.deps.config.credentials;
+    if (!credentials) {
+      throw invalidInput(
+        "This server has no rule34.xxx API credentials, so it cannot ask the site anything.",
+        "Set RULE34_USER_ID and RULE34_API_KEY in the env block of this server's entry in your MCP client configuration. Both are shown under 'API Access Credentials' at https://rule34.xxx/index.php?page=account&s=options once you are signed in. The site issues one key per person, so use your own rather than sharing one."
+      );
+    }
+    return credentials;
+  }
+  /**
+   * Fetch one address, remembering the answer under it.
+   *
+   * The key is the address without the key in it: two searches differ by their
+   * query and never by their credentials, and holding the secret in a second
+   * place buys nothing.
+   */
+  async read(url) {
+    const key = redactCredentials(url);
+    const remembered = this.cache.get(key);
+    if (remembered !== void 0) {
+      this.deps.logger.debug(`cache hit for ${key}`);
+      return { body: remembered, cached: true };
+    }
+    const body = await fetchXml(url, {
+      config: this.deps.config,
+      limiter: this.limiter,
+      logger: this.deps.logger,
+      fetchImpl: this.deps.fetchImpl
+    });
+    this.cache.set(key, body);
+    return { body, cached: false };
+  }
+};
+export {
+  Rule34Client
+};
+//# sourceMappingURL=client.js.map