webfetch-core

webfetch-core

License-aware federated image search primitives for agents, CLIs, servers, and apps.

Install

npm install webfetch-core

Usage

import { searchImages, downloadImage } from "webfetch-core";

const results = await searchImages("apollo 11 moon", {
  licensePolicy: "safe-only",
  providers: ["wikimedia", "nasa", "openverse"],
  maxPerProvider: 5,
});

const top = results.candidates[0];
if (top) {
  const downloaded = await downloadImage(top.url);
  console.log(downloaded.cachedPath, downloaded.sha256);
}

License Tags

Core distinguishes open licenses from platform and editorial licenses:

• Open/commercial reusable: CC0, PUBLIC_DOMAIN, CC_BY, CC_BY_SA
• Platform-license: UNSPLASH_LICENSE, PEXELS_LICENSE, PIXABAY_LICENSE
• Context/editorial: EDITORIAL_LICENSED, PRESS_KIT_ALLOWLIST
• Exploration only: UNKNOWN

Use licensePolicy: "open-only" when only Creative Commons/public-domain assets are acceptable.

Migration Notes

Unsplash, Pexels, and Pixabay are no longer represented as CC0. They now return UNSPLASH_LICENSE, PEXELS_LICENSE, and PIXABAY_LICENSE so callers can separate platform terms from Creative Commons/public-domain results.

Policy behavior:

• open-only: allows CC0, PUBLIC_DOMAIN, CC_BY, and CC_BY_SA.
• safe-only: allows open tags plus platform licenses, editorial licenses, and press-kit allowlist results; rejects UNKNOWN.
• prefer-safe: keeps unsafe results but ranks safe results first.
• any: returns all results, including UNKNOWN.

Update exhaustive License switches and persisted test fixtures before upgrading cached results produced by older builds.