illustration-search 0.0.1

package/dist/index.cjs

@@ -0,0 +1,1084 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CONSTANTS: () => CONSTANTS,
+  DEFAULT_LICENSE_ALLOWLIST: () => DEFAULT_LICENSE_ALLOWLIST,
+  IllustrationError: () => IllustrationError,
+  MissingCredentialError: () => MissingCredentialError,
+  ProviderError: () => ProviderError,
+  RIGHTS_FIELDS: () => RIGHTS_FIELDS,
+  RateLimitError: () => RateLimitError,
+  SOURCE_RECORDS: () => SOURCE_RECORDS,
+  UnknownSourceError: () => UnknownSourceError,
+  defaultSources: () => defaultSources,
+  defineSource: () => defineSource,
+  getSource: () => getSource,
+  imageResultSchema: () => imageResultSchema,
+  licenseAllowlist: () => licenseAllowlist,
+  listSources: () => listSources,
+  makeParamTranslator: () => makeParamTranslator,
+  makeResult: () => makeResult,
+  normalizeLicense: () => normalizeLicense,
+  openverse: () => openverse,
+  perPageFor: () => perPageFor,
+  pexels: () => pexels,
+  pixabay: () => pixabay,
+  registerSource: () => registerSource,
+  search: () => search,
+  searchSource: () => searchSource,
+  sourceRecord: () => sourceRecord,
+  wikimedia: () => wikimedia
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var IllustrationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var UnknownSourceError = class extends IllustrationError {
+  constructor(source, known) {
+    super(`Unknown source ${JSON.stringify(source)}. Registered sources: ${known.join(", ")}.`);
+    this.source = source;
+  }
+  source;
+};
+var MissingCredentialError = class extends IllustrationError {
+  constructor(provider, opts = {}) {
+    const where = opts.consoleUrl ? ` Get one at ${opts.consoleUrl}.` : "";
+    const env = opts.envVar ? ` (the Python side reads ${opts.envVar})` : "";
+    super(
+      `${provider} needs an API key: pass it as \`credentials: { ${provider}: "\u2026" }\`${env}.${where}`
+    );
+    this.provider = provider;
+  }
+  provider;
+};
+var ProviderError = class extends IllustrationError {
+  constructor(provider, message, status = null) {
+    super(`${provider}: ${message}${status !== null ? ` (HTTP ${status})` : ""}`);
+    this.provider = provider;
+    this.status = status;
+  }
+  provider;
+  status;
+};
+var RateLimitError = class extends ProviderError {
+};
+
+// src/generated/constants.ts
+var CONSTANTS = {
+  "canonical_params": [
+    "orientation",
+    "size",
+    "safe",
+    "license_type",
+    "color",
+    "content_type"
+  ],
+  "default_license_allowlist": [
+    "by",
+    "by-sa",
+    "cc0",
+    "pdm",
+    "pexels-license",
+    "pixabay-license"
+  ],
+  "defaults": {
+    "http_timeout_s": 30,
+    "max_pages": 25,
+    "n": 10,
+    "sources": [
+      "openverse"
+    ]
+  },
+  "license_aliases": {
+    "cc-0": "cc0",
+    "cc-pdm": "pdm",
+    "cc-publicdomain": "pdm",
+    "cc-zero": "cc0",
+    "pd": "pdm",
+    "pdm-owner": "pdm",
+    "public-domain": "pdm",
+    "public-domain-mark": "pdm",
+    "publicdomain": "pdm",
+    "zero": "cc0"
+  },
+  "license_normalization_cases": [
+    {
+      "input": null,
+      "output": null
+    },
+    {
+      "input": "",
+      "output": null
+    },
+    {
+      "input": "   ",
+      "output": null
+    },
+    {
+      "input": "by-sa",
+      "output": "by-sa"
+    },
+    {
+      "input": "BY",
+      "output": "by"
+    },
+    {
+      "input": "  BY  ",
+      "output": "by"
+    },
+    {
+      "input": "cc0",
+      "output": "cc0"
+    },
+    {
+      "input": "CC0 1.0",
+      "output": "cc0"
+    },
+    {
+      "input": "cc-0",
+      "output": "cc0"
+    },
+    {
+      "input": "cc-zero",
+      "output": "cc0"
+    },
+    {
+      "input": "cc-by-sa-4.0",
+      "output": "by-sa"
+    },
+    {
+      "input": "CC BY-SA 4.0",
+      "output": "by-sa"
+    },
+    {
+      "input": "cc-by-nc-nd-2.0",
+      "output": "by-nc-nd"
+    },
+    {
+      "input": "cc_by_3.0",
+      "output": "by"
+    },
+    {
+      "input": "Pexels License",
+      "output": "pexels-license"
+    },
+    {
+      "input": "Pixabay License",
+      "output": "pixabay-license"
+    },
+    {
+      "input": "public domain",
+      "output": "pdm"
+    },
+    {
+      "input": "Public Domain Mark",
+      "output": "pdm"
+    },
+    {
+      "input": "pdm",
+      "output": "pdm"
+    },
+    {
+      "input": "cc-pdm",
+      "output": "pdm"
+    },
+    {
+      "input": "sampling+",
+      "output": "sampling+"
+    },
+    {
+      "input": "by-nc",
+      "output": "by-nc"
+    },
+    {
+      "input": "CC-BY-SA-v2.5",
+      "output": "by-sa"
+    }
+  ],
+  "provider_console_urls": {
+    "pexels": "https://www.pexels.com/api/new/",
+    "pixabay": "https://pixabay.com/api/docs/"
+  },
+  "provider_env_vars": {
+    "pexels": "PEXELS_API_KEY",
+    "pixabay": "PIXABAY_API_KEY"
+  },
+  "restriction_tokens": [
+    "nc",
+    "nd",
+    "sampling"
+  ],
+  "rights_fields": [
+    "license",
+    "license_url",
+    "attribution",
+    "source_page_url",
+    "author",
+    "author_url",
+    "cacheable"
+  ]
+};
+
+// src/licensing.ts
+var ALIASES = CONSTANTS.license_aliases;
+var DEFAULT_LICENSE_ALLOWLIST = CONSTANTS.default_license_allowlist;
+var VERSION_SUFFIX = /[-_ ]v?\d+(?:\.\d+)*$/;
+var CC_PREFIX = /^cc[-_ ]/;
+var SEPARATORS = /[\s_]+/g;
+function normalizeLicense(value) {
+  if (!value || !value.trim()) return null;
+  let code = value.trim().toLowerCase().replace(SEPARATORS, "-");
+  if (Object.hasOwn(ALIASES, code)) return ALIASES[code];
+  code = code.replace(VERSION_SUFFIX, "");
+  if (Object.hasOwn(ALIASES, code)) return ALIASES[code];
+  code = code.replace(CC_PREFIX, "");
+  return (Object.hasOwn(ALIASES, code) ? ALIASES[code] : code) || null;
+}
+function licenseAllowlist(results, opts = {}) {
+  const allowed = /* @__PURE__ */ new Set();
+  for (const code of opts.allow ?? DEFAULT_LICENSE_ALLOWLIST) {
+    const normalized = normalizeLicense(code);
+    if (normalized !== null) allowed.add(normalized);
+  }
+  const kept = [];
+  for (const result of results) {
+    const code = normalizeLicense(result.license);
+    if (code !== null && allowed.has(code)) kept.push(result);
+  }
+  return kept;
+}
+
+// src/generated/image-result.ts
+var import_zod = require("zod");
+var imageResultSchema = import_zod.z.object({ "attribution": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).describe("Ready-to-render attribution sentence.").default(null), "author": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).default(null), "author_url": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).default(null), "avg_color": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).describe("Dominant-color hint where available.").default(null), "cacheable": import_zod.z.boolean().describe("May the bytes be downloaded/cached to our server?").default(false), "description": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).describe("Alt text / longer description.").default(null), "height": import_zod.z.union([import_zod.z.number().int(), import_zod.z.null()]).default(null), "id": import_zod.z.string().describe("Provider-native identifier."), "license": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).describe("License code or name (e.g. 'by-sa').").default(null), "license_url": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).default(null), "provider": import_zod.z.string().describe("Source/provider name, e.g. 'openverse'."), "query": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).describe("Canonical query that produced this hit.").default(null), "raw": import_zod.z.record(import_zod.z.string(), import_zod.z.any()).describe("Untranslated provider payload.").default({}), "score": import_zod.z.union([import_zod.z.number(), import_zod.z.null()]).describe("Reserved for Layer-2 rerank; None at Layer 1.").default(null), "source_page_url": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).default(null), "tags": import_zod.z.array(import_zod.z.string()).default([]), "thumbnail_url": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).default(null), "title": import_zod.z.union([import_zod.z.string(), import_zod.z.null()]).default(null), "url": import_zod.z.string().describe("Full-resolution image URL."), "width": import_zod.z.union([import_zod.z.number().int(), import_zod.z.null()]).default(null) }).describe("One normalized image hit from any provider.\n\nThe first eight fields plus ``cacheable`` are the cross-provider minimum the\ndesign guarantees; the rest are populated when a provider supplies them.");
+
+// src/generated/sources.ts
+var SOURCE_RECORDS = [
+  {
+    "auth": {
+      "format": null,
+      "kind": "none",
+      "name": null
+    },
+    "console_url": null,
+    "endpoint": "https://api.openverse.org/v1/images/",
+    "env_var": null,
+    "fixed_params": {},
+    "info": {
+      "default_cacheable": true,
+      "description": "800M+ CC / public-domain images aggregated from 50+ sources.",
+      "homepage": "https://openverse.org",
+      "license_note": "Per-result CC/PD license; preserve attribution for BY-family.",
+      "name": "openverse",
+      "rate_limit": "anonymous: 20/min, 200/day",
+      "requires_key": false,
+      "tags": [
+        "open",
+        "cc",
+        "public-domain",
+        "breadth"
+      ]
+    },
+    "max_per_page": 20,
+    "min_per_page": 1,
+    "name": "openverse",
+    "page_param": "page",
+    "params": {
+      "color": null,
+      "content_type": {
+        "choices": [
+          "illustration",
+          "photo"
+        ],
+        "coerce": true,
+        "name": "category"
+      },
+      "license_type": {
+        "choices": null,
+        "coerce": false,
+        "name": "license_type"
+      },
+      "orientation": {
+        "choices": null,
+        "coerce": true,
+        "name": "aspect_ratio"
+      },
+      "safe": {
+        "choices": null,
+        "coerce": true,
+        "name": "mature"
+      },
+      "size": {
+        "choices": [
+          "large",
+          "medium",
+          "small"
+        ],
+        "coerce": false,
+        "name": "size"
+      }
+    },
+    "per_page_param": "page_size",
+    "query_param": "q"
+  },
+  {
+    "auth": {
+      "format": "{key}",
+      "kind": "header",
+      "name": "Authorization"
+    },
+    "console_url": "https://www.pexels.com/api/new/",
+    "endpoint": "https://api.pexels.com/v1/search",
+    "env_var": "PEXELS_API_KEY",
+    "fixed_params": {},
+    "info": {
+      "default_cacheable": true,
+      "description": "Curated high-quality stock photos under the Pexels License.",
+      "homepage": "https://www.pexels.com",
+      "license_note": "Single Pexels License (commercial OK); credit photographer + backlink.",
+      "name": "pexels",
+      "rate_limit": "200/hour, 20,000/month",
+      "requires_key": true,
+      "tags": [
+        "stock",
+        "photos",
+        "keyed"
+      ]
+    },
+    "max_per_page": 80,
+    "min_per_page": 1,
+    "name": "pexels",
+    "page_param": "page",
+    "params": {
+      "color": {
+        "choices": null,
+        "coerce": false,
+        "name": "color"
+      },
+      "content_type": null,
+      "license_type": null,
+      "orientation": {
+        "choices": [
+          "landscape",
+          "portrait",
+          "square"
+        ],
+        "coerce": false,
+        "name": "orientation"
+      },
+      "safe": null,
+      "size": {
+        "choices": [
+          "large",
+          "medium",
+          "small"
+        ],
+        "coerce": false,
+        "name": "size"
+      }
+    },
+    "per_page_param": "per_page",
+    "query_param": "query"
+  },
+  {
+    "auth": {
+      "format": "{key}",
+      "kind": "query",
+      "name": "key"
+    },
+    "console_url": "https://pixabay.com/api/docs/",
+    "endpoint": "https://pixabay.com/api/",
+    "env_var": "PIXABAY_API_KEY",
+    "fixed_params": {},
+    "info": {
+      "default_cacheable": true,
+      "description": "Free commercial-use images; license permits caching + self-hosting.",
+      "homepage": "https://pixabay.com",
+      "license_note": "Single Pixabay Content License; download-to-own-server (no hotlink).",
+      "name": "pixabay",
+      "rate_limit": "100/60s (raisable); responses must be cached 24h",
+      "requires_key": true,
+      "tags": [
+        "stock",
+        "free-commercial",
+        "keyed",
+        "cacheable"
+      ]
+    },
+    "max_per_page": 200,
+    "min_per_page": 3,
+    "name": "pixabay",
+    "page_param": "page",
+    "params": {
+      "color": {
+        "choices": null,
+        "coerce": false,
+        "name": "colors"
+      },
+      "content_type": {
+        "choices": [
+          "illustration",
+          "photo",
+          "vector"
+        ],
+        "coerce": false,
+        "name": "image_type"
+      },
+      "license_type": null,
+      "orientation": {
+        "choices": [
+          "landscape",
+          "portrait",
+          "square"
+        ],
+        "coerce": true,
+        "name": "orientation"
+      },
+      "safe": {
+        "choices": null,
+        "coerce": true,
+        "name": "safesearch"
+      },
+      "size": {
+        "choices": [
+          "large",
+          "medium",
+          "small"
+        ],
+        "coerce": true,
+        "name": "min_width"
+      }
+    },
+    "per_page_param": "per_page",
+    "query_param": "q"
+  },
+  {
+    "auth": {
+      "format": null,
+      "kind": "none",
+      "name": null
+    },
+    "console_url": null,
+    "endpoint": "https://commons.wikimedia.org/w/api.php",
+    "env_var": null,
+    "fixed_params": {
+      "action": "query",
+      "format": "json",
+      "formatversion": "2",
+      "generator": "search",
+      "gsrnamespace": "6",
+      "iiprop": "url|extmetadata|size|mime|user",
+      "iiurlwidth": "320",
+      "prop": "imageinfo"
+    },
+    "info": {
+      "default_cacheable": true,
+      "description": "140M+ free media files with deep per-file metadata; no key.",
+      "homepage": "https://commons.wikimedia.org",
+      "license_note": "Per-file license varies (CC/PD; some share-alike) \u2014 gate for commercial use.",
+      "name": "wikimedia",
+      "rate_limit": "etiquette-bound (descriptive User-Agent required)",
+      "requires_key": false,
+      "tags": [
+        "open",
+        "historical",
+        "editorial",
+        "breadth",
+        "no-key"
+      ]
+    },
+    "max_per_page": 50,
+    "min_per_page": 1,
+    "name": "wikimedia",
+    "page_param": "page",
+    "params": {
+      "color": null,
+      "content_type": null,
+      "license_type": null,
+      "orientation": null,
+      "safe": null,
+      "size": null
+    },
+    "per_page_param": "page_size",
+    "query_param": "gsrsearch"
+  }
+];
+
+// src/translation.ts
+function makeParamTranslator(paramMap) {
+  return (canonical) => {
+    const native = {};
+    const dropped = [];
+    for (const [key, value] of Object.entries(canonical)) {
+      if (value === null || value === void 0) continue;
+      const spec = Object.hasOwn(paramMap, key) ? paramMap[key] : null;
+      if (spec === null || spec === void 0) {
+        dropped.push(key);
+        continue;
+      }
+      const applied = applySpec(key, value, spec);
+      if (applied === null) {
+        dropped.push(key);
+        continue;
+      }
+      native[applied.name] = applied.value;
+    }
+    return { native, dropped };
+  };
+}
+function applySpec(key, value, spec) {
+  if (typeof spec === "string") return { name: spec, value };
+  if (typeof spec === "function") return { name: key, value: spec(value) };
+  const name = spec.name ?? key;
+  if (spec.choices !== void 0) {
+    const choices = spec.choices instanceof Set ? spec.choices : new Set(spec.choices);
+    if (typeof value !== "string" || !choices.has(value)) return null;
+  }
+  return { name, value: spec.coerce ? spec.coerce(value) : value };
+}
+
+// src/source.ts
+function sourceRecord(name) {
+  const record = SOURCE_RECORDS.find((r) => r.name === name);
+  if (!record) {
+    throw new Error(
+      `No exported record for source ${JSON.stringify(name)}: register it on the Python side and run \`illustration export-schema\`.`
+    );
+  }
+  return record;
+}
+function defineSource(name, hooks) {
+  const record = sourceRecord(name);
+  const pageParams = hooks.pageParams?.bind(hooks) ?? ((page, perPage) => ({
+    [record.page_param]: page,
+    [record.per_page_param]: perPage
+  }));
+  const queryParams = hooks.queryParams?.bind(hooks) ?? ((query, page, perPage) => ({
+    [record.query_param]: query,
+    ...pageParams(page, perPage)
+  }));
+  return {
+    ...hooks,
+    name,
+    record,
+    translate: makeParamTranslator(hooks.paramMap),
+    pageParams,
+    queryParams
+  };
+}
+function required(item, key) {
+  const value = item[key];
+  if (value === void 0 || value === null) throw new Error(`item has no ${key}`);
+  return value;
+}
+function makeResult(fields) {
+  const defined = {};
+  for (const [k, v] of Object.entries(fields)) if (v !== void 0) defined[k] = v;
+  return imageResultSchema.parse(defined);
+}
+function perPageFor(record, n) {
+  return Math.max(record.min_per_page, Math.min(n, record.max_per_page));
+}
+async function searchSource(source, query, opts = {}) {
+  if (!query) throw new Error("query must be a non-empty string");
+  const n = opts.n ?? CONSTANTS.defaults.n;
+  const { record } = source;
+  const apiKey = opts.auth === "transport" ? null : opts.apiKey ?? null;
+  if (record.info.requires_key && !apiKey && opts.auth !== "transport") {
+    throw new MissingCredentialError(source.name, {
+      envVar: record.env_var,
+      consoleUrl: record.console_url
+    });
+  }
+  const { native } = source.translate(opts.canonical ?? {});
+  Object.assign(native, opts.nativeParams ?? {});
+  const results = [];
+  const perPage = perPageFor(record, n);
+  let page = 1;
+  while (results.length < n && page <= CONSTANTS.defaults.max_pages) {
+    const params = {
+      ...record.fixed_params,
+      ...native,
+      ...source.queryParams(query, page, perPage)
+    };
+    const response = await get(source, params, { ...opts, apiKey });
+    const items = Array.from(source.items(response));
+    if (items.length === 0) break;
+    for (const item of items) {
+      const normalized = safeNormalize(source, item, query);
+      if (normalized !== null) {
+        results.push(normalized);
+        if (results.length >= n) break;
+      }
+    }
+    if (items.length < perPage) break;
+    page += 1;
+  }
+  return results.slice(0, n);
+}
+function safeNormalize(source, item, query) {
+  try {
+    return source.normalize(item, query);
+  } catch {
+    return null;
+  }
+}
+function requestUrl(source, params, apiKey) {
+  const url = new URL(source.record.endpoint);
+  const merged = { ...params };
+  const { auth } = source.record;
+  if (auth.kind === "query" && apiKey && auth.name) {
+    merged[auth.name] = (auth.format ?? "{key}").replace("{key}", apiKey);
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (value === null || value === void 0) continue;
+    url.searchParams.set(key, String(value));
+  }
+  return url;
+}
+function requestHeaders(source, apiKey, userAgent) {
+  const headers = new Headers({ Accept: "application/json" });
+  if (userAgent) headers.set("Api-User-Agent", userAgent);
+  const { auth } = source.record;
+  if (auth.kind === "header" && apiKey && auth.name) {
+    headers.set(auth.name, (auth.format ?? "{key}").replace("{key}", apiKey));
+  }
+  return headers;
+}
+async function get(source, params, opts) {
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  let response;
+  try {
+    response = await doFetch(requestUrl(source, params, opts.apiKey), {
+      method: "GET",
+      headers: requestHeaders(source, opts.apiKey, opts.userAgent),
+      signal: opts.signal
+    });
+  } catch (e) {
+    throw new ProviderError(source.name, `request failed: ${e.message ?? e}`);
+  }
+  const { status } = response;
+  if (status === 429) throw new RateLimitError(source.name, "rate limit exceeded", 429);
+  if (status === 401 || status === 403) {
+    throw new ProviderError(source.name, "authentication failed (check API key)", status);
+  }
+  if (status >= 400) throw new ProviderError(source.name, await shortBody(response), status);
+  let decoded;
+  try {
+    decoded = await response.json();
+  } catch {
+    throw new ProviderError(source.name, "response was not valid JSON", status);
+  }
+  if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+    throw new ProviderError(source.name, `unexpected response type: ${Array.isArray(decoded) ? "array" : typeof decoded}`, status);
+  }
+  return decoded;
+}
+async function shortBody(response) {
+  try {
+    const text = (await response.text()).trim();
+    return text.length > 200 ? `${text.slice(0, 200)}\u2026` : text || `HTTP ${response.status}`;
+  } catch {
+    return `HTTP ${response.status}`;
+  }
+}
+
+// src/providers/openverse.ts
+var ORIENTATION_TO_ASPECT = {
+  landscape: "wide",
+  portrait: "tall",
+  square: "square"
+};
+var CONTENT_TYPE_TO_CATEGORY = {
+  photo: "photograph",
+  illustration: "illustration"
+};
+var openverse = defineSource("openverse", {
+  paramMap: {
+    orientation: {
+      name: "aspect_ratio",
+      coerce: (o) => ORIENTATION_TO_ASPECT[String(o)] ?? o
+    },
+    size: { name: "size", choices: ["large", "medium", "small"] },
+    safe: { name: "mature", coerce: (safe) => !safe },
+    license_type: "license_type",
+    // content_type: Openverse `category` has no 'vector' → only photo/illustration
+    content_type: {
+      name: "category",
+      choices: ["photo", "illustration"],
+      coerce: (ct) => CONTENT_TYPE_TO_CATEGORY[String(ct)]
+    },
+    color: null
+    // Openverse has no color filter (explicitly unsupported)
+  },
+  items(response) {
+    return response.results ?? [];
+  },
+  normalize(item, query) {
+    const tags = (item.tags ?? []).filter((t) => typeof t === "object" && t !== null && !!t.name).map((t) => String(t.name));
+    const title = item.title ?? null;
+    return makeResult({
+      provider: "openverse",
+      id: String(required(item, "id")),
+      url: String(required(item, "url")),
+      thumbnail_url: item.thumbnail ?? null,
+      width: item.width ?? null,
+      height: item.height ?? null,
+      title,
+      description: title,
+      // Openverse exposes no separate description
+      tags,
+      license: item.license ?? null,
+      license_url: item.license_url ?? null,
+      attribution: item.attribution ?? null,
+      source_page_url: item.foreign_landing_url ?? null,
+      author: item.creator ?? null,
+      author_url: item.creator_url ?? null,
+      cacheable: true,
+      // CC / public-domain media is cacheable (preserve attribution)
+      avg_color: null,
+      query,
+      raw: { ...item }
+    });
+  }
+});
+
+// src/providers/pexels.ts
+var PEXELS_LICENSE = "Pexels License";
+var PEXELS_LICENSE_URL = "https://www.pexels.com/license/";
+var pexels = defineSource("pexels", {
+  paramMap: {
+    orientation: { name: "orientation", choices: ["landscape", "portrait", "square"] },
+    size: { name: "size", choices: ["large", "medium", "small"] },
+    // `safe` is a no-op (curated corpus); `license_type` has no equivalent (single licence).
+    safe: null,
+    license_type: null,
+    color: "color",
+    // a named or #hex colour
+    content_type: null
+    // photos only
+  },
+  items(response) {
+    return response.photos ?? [];
+  },
+  normalize(item, query) {
+    const src = item.src ?? {};
+    const photographer = item.photographer ?? null;
+    const url = src.original || src.large2x || src.large || null;
+    if (!url) throw new Error("item has no image url");
+    return makeResult({
+      provider: "pexels",
+      id: String(required(item, "id")),
+      url,
+      thumbnail_url: src.tiny || src.medium || null,
+      width: item.width ?? null,
+      height: item.height ?? null,
+      title: null,
+      description: item.alt || null,
+      tags: [],
+      // Pexels returns no tags
+      license: PEXELS_LICENSE,
+      license_url: PEXELS_LICENSE_URL,
+      attribution: photographer ? `Photo by ${photographer} on Pexels` : "Photo from Pexels",
+      source_page_url: item.url ?? null,
+      // the Pexels web page
+      author: photographer,
+      author_url: item.photographer_url ?? null,
+      cacheable: true,
+      // Pexels License permits caching for display
+      avg_color: item.avg_color ?? null,
+      query,
+      raw: { ...item }
+    });
+  }
+});
+
+// src/providers/pixabay.ts
+var PIXABAY_LICENSE = "Pixabay License";
+var PIXABAY_LICENSE_URL = "https://pixabay.com/service/license-summary/";
+var ORIENTATION = {
+  landscape: "horizontal",
+  portrait: "vertical",
+  square: "all"
+};
+var SIZE_MIN_WIDTH = { large: 1920, medium: 1280, small: 640 };
+var pixabay = defineSource("pixabay", {
+  paramMap: {
+    orientation: {
+      name: "orientation",
+      choices: ["landscape", "portrait", "square"],
+      coerce: (o) => ORIENTATION[String(o)]
+    },
+    size: {
+      name: "min_width",
+      choices: ["large", "medium", "small"],
+      coerce: (s) => SIZE_MIN_WIDTH[String(s)]
+    },
+    safe: { name: "safesearch", coerce: (safe) => safe ? "true" : "false" },
+    license_type: null,
+    // single Pixabay License
+    color: "colors",
+    content_type: { name: "image_type", choices: ["photo", "illustration", "vector"] }
+  },
+  items(response) {
+    return response.hits ?? [];
+  },
+  normalize(item, query) {
+    const user = item.user ?? null;
+    const tags = String(item.tags ?? "").split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+    const url = item.largeImageURL || item.webformatURL || item.imageURL || null;
+    if (!url) throw new Error("item has no image url");
+    return makeResult({
+      provider: "pixabay",
+      id: String(required(item, "id")),
+      url,
+      thumbnail_url: item.previewURL ?? null,
+      width: item.imageWidth ?? null,
+      height: item.imageHeight ?? null,
+      title: null,
+      description: null,
+      tags,
+      license: PIXABAY_LICENSE,
+      license_url: PIXABAY_LICENSE_URL,
+      attribution: user ? `Image by ${user} on Pixabay` : "Image from Pixabay",
+      source_page_url: item.pageURL ?? null,
+      author: user,
+      author_url: null,
+      cacheable: true,
+      // licence permits caching / self-hosting
+      avg_color: null,
+      query,
+      raw: { ...item }
+    });
+  }
+});
+
+// src/providers/wikimedia.ts
+var import_entities = require("entities");
+var TAG_RE = /<[^>]+>/g;
+var HREF_RE = /href=["']([^"']+)["']/i;
+var CATEGORY_PREFIX = "category:";
+var FILE_PREFIX = "file:";
+function isFileTitle(query) {
+  return query.trim().toLowerCase().startsWith(FILE_PREFIX);
+}
+function isCategory(query) {
+  return query.trim().toLowerCase().startsWith(CATEGORY_PREFIX);
+}
+function categoryTitle(query) {
+  return `Category:${query.trim().slice(CATEGORY_PREFIX.length).trim()}`;
+}
+function fileTitle(query) {
+  return `File:${query.trim().slice(FILE_PREFIX.length).trim()}`;
+}
+function stripHtml(value) {
+  if (!value) return null;
+  const text = (0, import_entities.decodeHTML)(value.replace(TAG_RE, "")).trim();
+  return text || null;
+}
+function firstHref(value) {
+  if (!value) return null;
+  const m = HREF_RE.exec(value);
+  if (!m) return null;
+  const url = m[1];
+  return url.startsWith("//") ? `https:${url}` : url;
+}
+function buildAttribution(author, licenseShort) {
+  if (author && licenseShort) return `${author} / ${licenseShort}, via Wikimedia Commons`;
+  if (author) return `${author}, via Wikimedia Commons`;
+  if (licenseShort) return `${licenseShort}, via Wikimedia Commons`;
+  return null;
+}
+var wikimedia = defineSource("wikimedia", {
+  paramMap: {},
+  // Commons exposes no canonical search-time filters here
+  pageParams(page, perPage) {
+    return { gsrlimit: perPage, gsroffset: (page - 1) * perPage };
+  },
+  queryParams(query, page, perPage) {
+    if (isFileTitle(query)) {
+      return {
+        generator: null,
+        // removed by the request builder; this is a direct lookup
+        titles: query.split("|").filter((part) => part.trim()).map(fileTitle).join("|")
+      };
+    }
+    if (!isCategory(query)) {
+      return { gsrsearch: query, ...this.pageParams(page, perPage) };
+    }
+    return {
+      generator: "categorymembers",
+      gcmtitle: categoryTitle(query),
+      gcmtype: "file",
+      gcmlimit: perPage
+    };
+  },
+  items(response) {
+    const pages = response.query?.pages ?? [];
+    const items = Array.isArray(pages) ? pages : Object.values(pages);
+    return items.sort(
+      (a, b) => (a.index ?? 0) - (b.index ?? 0)
+    );
+  },
+  normalize(item, query) {
+    const info = (item.imageinfo ?? [{}])[0] ?? {};
+    if (!String(info.mime ?? "").startsWith("image/")) throw new Error("not an image file");
+    const em = info.extmetadata ?? {};
+    const emValue = (key) => {
+      const v = em[key];
+      return typeof v === "object" && v !== null && typeof v.value === "string" ? v.value : null;
+    };
+    const artistHtml = emValue("Artist");
+    let title = item.title ?? "";
+    if (title.startsWith("File:")) title = title.slice("File:".length);
+    const licenseShort = emValue("LicenseShortName");
+    return makeResult({
+      provider: "wikimedia",
+      id: String(required(item, "pageid")),
+      url: String(required(info, "url")),
+      thumbnail_url: info.thumburl ?? null,
+      width: info.width ?? null,
+      height: info.height ?? null,
+      title: title || null,
+      description: stripHtml(emValue("ImageDescription")),
+      tags: [],
+      // Commons categories are noisy/HTML; omitted at this layer
+      license: emValue("License") || licenseShort,
+      license_url: emValue("LicenseUrl"),
+      attribution: stripHtml(emValue("Attribution")) || buildAttribution(stripHtml(artistHtml), licenseShort),
+      source_page_url: info.descriptionurl ?? null,
+      author: stripHtml(artistHtml),
+      author_url: firstHref(artistHtml),
+      cacheable: true,
+      // free content; preserve attribution (gate per-file licence)
+      avg_color: null,
+      query,
+      raw: { ...item }
+    });
+  }
+});
+
+// src/registry.ts
+var REGISTRY = /* @__PURE__ */ new Map();
+function registerSource(source) {
+  REGISTRY.set(source.name, source);
+  return source;
+}
+function getSource(name) {
+  const source = REGISTRY.get(name);
+  if (!source) throw new UnknownSourceError(name, listSources());
+  return source;
+}
+function listSources() {
+  return Array.from(REGISTRY.keys());
+}
+function defaultSources() {
+  return [...CONSTANTS.defaults.sources];
+}
+for (const source of [openverse, wikimedia, pexels, pixabay]) registerSource(source);
+
+// src/search.ts
+async function search(query, opts = {}) {
+  if (!query || typeof query !== "string") throw new Error("query must be a non-empty string");
+  const n = opts.n ?? CONSTANTS.defaults.n;
+  if (!(n > 0)) throw new Error(`n must be a positive integer, got ${n}`);
+  const media = opts.media ?? "image";
+  if (media !== "image") {
+    throw new IllustrationError(
+      `no ${media} sources are registered yet (illustration#33); only media: "image" is available`
+    );
+  }
+  const names = resolveSourceNames(opts.source);
+  const canonical = {
+    orientation: opts.orientation ?? null,
+    size: opts.size ?? null,
+    safe: opts.safe ?? true,
+    license_type: opts.licenseType ?? null,
+    color: opts.color ?? null,
+    content_type: opts.contentType ?? null
+  };
+  const perSource = await Promise.all(
+    names.map(
+      (name) => searchSource(getSource(name), query, {
+        n,
+        canonical,
+        apiKey: opts.credentials?.[name] ?? null,
+        auth: opts.auth,
+        nativeParams: opts.providerParams?.[name] ?? null,
+        fetch: opts.fetch,
+        signal: opts.signal,
+        userAgent: opts.userAgent
+      })
+    )
+  );
+  let results = perSource.flat();
+  const allow = opts.licenseAllow === true ? null : opts.licenseAllow ? [...opts.licenseAllow] : void 0;
+  if (opts.licenseAllow === true || allow && allow.length > 0) {
+    results = licenseAllowlist(results, { allow });
+  }
+  return results;
+}
+function resolveSourceNames(source) {
+  if (source === void 0 || source === null) return defaultSources();
+  if (typeof source === "string") return [source];
+  const names = [...source];
+  if (names.length === 0) throw new Error("source list is empty; pass at least one source name");
+  return names;
+}
+
+// src/index.ts
+var RIGHTS_FIELDS = CONSTANTS.rights_fields;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONSTANTS,
+  DEFAULT_LICENSE_ALLOWLIST,
+  IllustrationError,
+  MissingCredentialError,
+  ProviderError,
+  RIGHTS_FIELDS,
+  RateLimitError,
+  SOURCE_RECORDS,
+  UnknownSourceError,
+  defaultSources,
+  defineSource,
+  getSource,
+  imageResultSchema,
+  licenseAllowlist,
+  listSources,
+  makeParamTranslator,
+  makeResult,
+  normalizeLicense,
+  openverse,
+  perPageFor,
+  pexels,
+  pixabay,
+  registerSource,
+  search,
+  searchSource,
+  sourceRecord,
+  wikimedia
+});