illustration-search 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,451 @@
+import { z } from 'zod';
+
+declare const imageResultSchema: z.ZodObject<{
+    attribution: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    author: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    author_url: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    avg_color: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    cacheable: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    height: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
+    id: z.ZodString;
+    license: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    license_url: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    provider: z.ZodString;
+    query: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    raw: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    score: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
+    source_page_url: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    thumbnail_url: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    title: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    url: z.ZodString;
+    width: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
+}, z.core.$strip>;
+type ImageResult = z.infer<typeof imageResultSchema>;
+type ImageResultInput = z.input<typeof imageResultSchema>;
+
+/**
+ * The front door: `search(query, options)`, the TS twin of `illustration.search`.
+ *
+ * Layer 1 only. Rerank, dedupe and curation (illustration's Layer 2) are model
+ * and numpy territory and stay on the Python side; caching is the application's
+ * (a browser has no content-addressed store, the server relay's side does).
+ *
+ * `media` is accepted now so the signature has room for video (illustration#33);
+ * `"video"` raises until video sources are registered on the Python side and
+ * exported.
+ */
+
+type MediaType = 'image' | 'video';
+interface SearchOptions {
+    /** Results wanted **per source** (default `CONSTANTS.defaults.n`). */
+    readonly n?: number;
+    /** A source name, a list of names, or omitted for the default set. */
+    readonly source?: string | readonly string[];
+    readonly orientation?: 'landscape' | 'portrait' | 'square' | (string & {});
+    readonly size?: 'large' | 'medium' | 'small' | (string & {});
+    /** Exclude mature content where the provider supports it (default `true`). */
+    readonly safe?: boolean;
+    /** `commercial` | `all-cc` | `modification` | `all` (providers with licence filtering). */
+    readonly licenseType?: string;
+    /** A named colour or `#hex` (Pexels, Pixabay). */
+    readonly color?: string;
+    /** `photo` | `illustration` | `vector` (providers map or skip what they lack). */
+    readonly contentType?: 'photo' | 'illustration' | 'vector' | (string & {});
+    /** The licence gate: `false` (default) = none; `true` = the default commercial-safe
+     *  allowlist; an iterable of codes = keep only those. Aggregators disclaim licence
+     *  accuracy, so gate when commercial use matters. */
+    readonly licenseAllow?: boolean | Iterable<string>;
+    /** Per-source native params, e.g. `{ pexels: { color: 'blue' } }` (the escape hatch). */
+    readonly providerParams?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /** The caller's keys by provider name. The facade never reads storage. */
+    readonly credentials?: Readonly<Record<string, string | null | undefined>>;
+    /** `'caller'` (default): keyed providers need `credentials`. `'transport'`: the
+     *  `fetch` you pass is a relay that adds keys itself — none required, none sent. */
+    readonly auth?: 'caller' | 'transport';
+    /** `"image"` (default). `"video"` is reserved for illustration#33. */
+    readonly media?: MediaType;
+    /** The transport seam (default `globalThis.fetch`). */
+    readonly fetch?: typeof globalThis.fetch;
+    readonly signal?: AbortSignal;
+    /** Sent as `Api-User-Agent`; Wikimedia etiquette asks for a descriptive one. */
+    readonly userAgent?: string;
+}
+/** Search for up to `n` images per source. Per-source lists are concatenated in
+ *  source order (up to `n × sources`); the licence gate is applied over the whole. */
+declare function search(query: string, opts?: SearchOptions): Promise<ImageResult[]>;
+
+/**
+ * The declared half of a source, as exported by `illustration export-schema`.
+ *
+ * Everything a Python `RetrievalSource` subclass *declares* (endpoint, parameter
+ * names, paging caps, fixed params, auth style, canonical→native parameter names,
+ * `SourceInfo`) arrives here as data (`src/generated/sources.ts`). What it *codes*
+ * (`coerce` functions, `_items`, `_normalize`, a `_query_params` override) is
+ * ported by hand in `src/providers/` and pinned by the parity fixtures.
+ */
+interface SourceInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly requires_key: boolean;
+    readonly homepage: string | null;
+    readonly default_cacheable: boolean;
+    readonly license_note: string;
+    readonly rate_limit: string;
+    readonly tags: readonly string[];
+}
+/** How the key travels: a header (`Authorization: <key>`), a query param (`key=`), or not at all. */
+interface AuthRecord {
+    readonly kind: 'none' | 'header' | 'query';
+    readonly name: string | null;
+    /** Template with `{key}` where the raw key goes. */
+    readonly format: string | null;
+}
+/** A canonical parameter's native name and guard; `coerce: true` means the Python
+ *  side transforms the value and the provider module must do the same. */
+interface ParamRecord {
+    readonly name: string | null;
+    readonly choices: readonly string[] | null;
+    readonly coerce: boolean;
+}
+interface SourceRecord {
+    readonly name: string;
+    readonly endpoint: string;
+    readonly query_param: string;
+    readonly page_param: string;
+    readonly per_page_param: string;
+    readonly max_per_page: number;
+    readonly min_per_page: number;
+    readonly fixed_params: Readonly<Record<string, unknown>>;
+    readonly auth: AuthRecord;
+    /** Keyed by canonical parameter name; `null` = explicitly unsupported (degrades). */
+    readonly params: Readonly<Record<string, ParamRecord | null>>;
+    readonly info: SourceInfo;
+    readonly env_var: string | null;
+    readonly console_url: string | null;
+}
+
+/**
+ * Canonical → native parameter translation, mirroring `illustration.translation`.
+ *
+ * A `paramMap` value may be a string (rename), a spec object (`name`, optional
+ * `choices` guard, optional `coerce`), a bare function (`coerce`, same name), or
+ * `null` (explicitly unsupported: the parameter degrades). A canonical key
+ * absent from the map is unsupported too. A `null`/`undefined` *value* is an
+ * unset filter and is skipped, not dropped.
+ */
+type Coerce = (value: unknown) => unknown;
+interface ParamSpec {
+    readonly name?: string;
+    readonly choices?: ReadonlySet<string> | readonly string[];
+    readonly coerce?: Coerce;
+}
+type ParamMapValue = string | ParamSpec | Coerce | null;
+type ParamMap = Readonly<Record<string, ParamMapValue>>;
+interface Translation {
+    readonly native: Record<string, unknown>;
+    readonly dropped: string[];
+}
+type ParamTranslator = (canonical: Readonly<Record<string, unknown>>) => Translation;
+/** Build a translator from a `paramMap`. Unsupported parameters are dropped
+ *  silently (Python's `on_unsupported="ignore"`, the façade's setting). */
+declare function makeParamTranslator(paramMap: ParamMap): ParamTranslator;
+
+/**
+ * A source = its declared record (generated) + its coded hooks (a provider module),
+ * and the one search template every source runs through — the TS twin of
+ * `illustration.base.RetrievalSource`.
+ *
+ * `searchSource` is the template method: it enforces the credential check,
+ * canonical→native translation, pagination capped by `max_pages`, and per-item
+ * normalisation that *skips* a malformed item rather than failing the search.
+ * Provider modules supply hooks; they never re-implement the template.
+ *
+ * Transport is one argument, `fetch` (default `globalThis.fetch`). A server relay
+ * is a `fetch` that rewrites the URL; nothing else changes.
+ */
+
+type Json = Record<string, unknown>;
+/** The coded half of a source. */
+interface SourceHooks {
+    /** Canonical→native spec; `coerce` functions live here because they cannot be data. */
+    readonly paramMap: ParamMap;
+    /** Extract the raw result items from a decoded response. */
+    items(response: Json): Iterable<Json>;
+    /** Map one raw item to an `ImageResult`. Throw to have the item skipped. */
+    normalize(item: Json, query: string): ImageResult;
+    /** Every param that depends on the query (the query itself and paging).
+     *  Override when the request *shape* changes with the query (Wikimedia). */
+    queryParams?(query: string, page: number, perPage: number): Record<string, unknown>;
+    /** Native pagination params for a 1-based page. Override for offset models. */
+    pageParams?(page: number, perPage: number): Record<string, unknown>;
+}
+interface RetrievalSource extends SourceHooks {
+    readonly name: string;
+    readonly record: SourceRecord;
+    readonly translate: ParamTranslator;
+    queryParams(query: string, page: number, perPage: number): Record<string, unknown>;
+    pageParams(page: number, perPage: number): Record<string, unknown>;
+}
+/** The generated record for `name`, or throw: a provider module cannot exist
+ *  without its Python twin having been exported. */
+declare function sourceRecord(name: string): SourceRecord;
+/** Bind a provider module's hooks to its generated record. */
+declare function defineSource(name: string, hooks: SourceHooks): RetrievalSource;
+/** Fill schema defaults and validate: what the Python side's `ImageResult(...)`
+ *  constructor does. Undefined fields take their defaults (`null`, `[]`, `{}`). */
+declare function makeResult(fields: Partial<ImageResult> & Pick<ImageResult, 'provider' | 'id' | 'url'>): ImageResult;
+interface SearchSourceOptions {
+    /** Results wanted (default `CONSTANTS.defaults.n`). */
+    readonly n?: number;
+    /** The caller's key for a keyed provider. */
+    readonly apiKey?: string | null;
+    /** Who supplies the credential. `'caller'` (default): a keyed provider needs `apiKey`
+     *  here, and it is attached to the request. `'transport'`: the `fetch` you pass (a
+     *  server relay) adds the key itself — no pre-flight check, nothing attached. */
+    readonly auth?: 'caller' | 'transport';
+    /** Provider-native params merged last, overriding translated ones (the escape hatch). */
+    readonly nativeParams?: Readonly<Record<string, unknown>> | null;
+    /** Canonical filters (`orientation`, `size`, `safe`, …), translated per source. */
+    readonly canonical?: Readonly<Record<string, unknown>>;
+    /** The transport seam. A relay is a `fetch` that rewrites the URL. */
+    readonly fetch?: typeof globalThis.fetch;
+    readonly signal?: AbortSignal;
+    /** Sent as `Api-User-Agent` (a browser cannot set `User-Agent`; Wikimedia honours this one). */
+    readonly userAgent?: string;
+}
+/** The per-page clamp: at least `min_per_page`, at most `max_per_page`, ideally `n`. */
+declare function perPageFor(record: SourceRecord, n: number): number;
+/** Search one source and return up to `n` normalised results. */
+declare function searchSource(source: RetrievalSource, query: string, opts?: SearchSourceOptions): Promise<ImageResult[]>;
+
+/**
+ * The source registry, mirroring `illustration.registry`: the open-closed seam.
+ *
+ * The four built-in sources are registered at import. Adding a provider means
+ * exporting it on the Python side (so its record and fixtures exist), writing its
+ * hooks module under `providers/`, and calling `registerSource` — the façade is
+ * untouched.
+ */
+
+declare function registerSource(source: RetrievalSource): RetrievalSource;
+declare function getSource(name: string): RetrievalSource;
+/** Registered source names, in registration order. */
+declare function listSources(): string[];
+/** The sources a bare `search(q)` fans out to (`DFLT_SOURCES` on the Python side). */
+declare function defaultSources(): string[];
+
+/**
+ * Licence normalisation and the allowlist gate, mirroring `illustration.licensing`
+ * and `illustration.schema.license_allowlist`.
+ *
+ * The alias table is generated data, not re-typed here. The transform is the
+ * same three steps in the same order as Python, because the order is what makes
+ * `cc-0` reachable (the version strip would otherwise eat its `-0`), and the
+ * invariant is the same: **a restriction token is never dropped**. The Python
+ * side's `license_normalization_cases` are replayed in `parity.test.ts`.
+ */
+
+/** The default commercial-safe allowlist (`DFLT_LICENSE_ALLOWLIST` on the Python side). */
+declare const DEFAULT_LICENSE_ALLOWLIST: readonly string[];
+/** Fold a provider's licence spelling onto one canonical, comparable code.
+ *  `null` for null/blank: an absent licence is never a code. */
+declare function normalizeLicense(value: string | null | undefined): string | null;
+/** Keep only results whose licence is on the allowlist; unknown is not allowed.
+ *  Both sides are normalised, so provider dialects match without enumeration. */
+declare function licenseAllowlist<T extends Pick<ImageResult, 'license'>>(results: Iterable<T>, opts?: {
+    allow?: Iterable<string> | null;
+}): T[];
+
+/**
+ * The error tree, mirroring `illustration.errors`.
+ *
+ * Every error names the provider and, for a missing key, says how to supply one
+ * and where to get one. Key *values* never appear in a message.
+ */
+declare class IllustrationError extends Error {
+    constructor(message: string);
+}
+declare class UnknownSourceError extends IllustrationError {
+    readonly source: string;
+    constructor(source: string, known: readonly string[]);
+}
+declare class MissingCredentialError extends IllustrationError {
+    readonly provider: string;
+    constructor(provider: string, opts?: {
+        envVar?: string | null;
+        consoleUrl?: string | null;
+    });
+}
+declare class ProviderError extends IllustrationError {
+    readonly provider: string;
+    readonly status: number | null;
+    constructor(provider: string, message: string, status?: number | null);
+}
+declare class RateLimitError extends ProviderError {
+}
+
+/** One record per source registered on the Python side, in registration order. */
+declare const SOURCE_RECORDS: readonly SourceRecord[];
+
+/** Rights fields, licence tables, façade defaults and credential lookups. */
+declare const CONSTANTS: {
+    readonly canonical_params: readonly ["orientation", "size", "safe", "license_type", "color", "content_type"];
+    readonly default_license_allowlist: readonly ["by", "by-sa", "cc0", "pdm", "pexels-license", "pixabay-license"];
+    readonly defaults: {
+        readonly http_timeout_s: 30;
+        readonly max_pages: 25;
+        readonly n: 10;
+        readonly sources: readonly ["openverse"];
+    };
+    readonly license_aliases: {
+        readonly "cc-0": "cc0";
+        readonly "cc-pdm": "pdm";
+        readonly "cc-publicdomain": "pdm";
+        readonly "cc-zero": "cc0";
+        readonly pd: "pdm";
+        readonly "pdm-owner": "pdm";
+        readonly "public-domain": "pdm";
+        readonly "public-domain-mark": "pdm";
+        readonly publicdomain: "pdm";
+        readonly zero: "cc0";
+    };
+    readonly license_normalization_cases: readonly [{
+        readonly input: null;
+        readonly output: null;
+    }, {
+        readonly input: "";
+        readonly output: null;
+    }, {
+        readonly input: "   ";
+        readonly output: null;
+    }, {
+        readonly input: "by-sa";
+        readonly output: "by-sa";
+    }, {
+        readonly input: "BY";
+        readonly output: "by";
+    }, {
+        readonly input: "  BY  ";
+        readonly output: "by";
+    }, {
+        readonly input: "cc0";
+        readonly output: "cc0";
+    }, {
+        readonly input: "CC0 1.0";
+        readonly output: "cc0";
+    }, {
+        readonly input: "cc-0";
+        readonly output: "cc0";
+    }, {
+        readonly input: "cc-zero";
+        readonly output: "cc0";
+    }, {
+        readonly input: "cc-by-sa-4.0";
+        readonly output: "by-sa";
+    }, {
+        readonly input: "CC BY-SA 4.0";
+        readonly output: "by-sa";
+    }, {
+        readonly input: "cc-by-nc-nd-2.0";
+        readonly output: "by-nc-nd";
+    }, {
+        readonly input: "cc_by_3.0";
+        readonly output: "by";
+    }, {
+        readonly input: "Pexels License";
+        readonly output: "pexels-license";
+    }, {
+        readonly input: "Pixabay License";
+        readonly output: "pixabay-license";
+    }, {
+        readonly input: "public domain";
+        readonly output: "pdm";
+    }, {
+        readonly input: "Public Domain Mark";
+        readonly output: "pdm";
+    }, {
+        readonly input: "pdm";
+        readonly output: "pdm";
+    }, {
+        readonly input: "cc-pdm";
+        readonly output: "pdm";
+    }, {
+        readonly input: "sampling+";
+        readonly output: "sampling+";
+    }, {
+        readonly input: "by-nc";
+        readonly output: "by-nc";
+    }, {
+        readonly input: "CC-BY-SA-v2.5";
+        readonly output: "by-sa";
+    }];
+    readonly provider_console_urls: {
+        readonly pexels: "https://www.pexels.com/api/new/";
+        readonly pixabay: "https://pixabay.com/api/docs/";
+    };
+    readonly provider_env_vars: {
+        readonly pexels: "PEXELS_API_KEY";
+        readonly pixabay: "PIXABAY_API_KEY";
+    };
+    readonly restriction_tokens: readonly ["nc", "nd", "sampling"];
+    readonly rights_fields: readonly ["license", "license_url", "attribution", "source_page_url", "author", "author_url", "cacheable"];
+};
+
+/**
+ * Openverse (anonymous tier, no key): 800M+ CC / public-domain images.
+ * Twin of `illustration/providers/openverse.py`; pinned by `schema/fixtures/openverse.expected.json`.
+ */
+declare const openverse: RetrievalSource;
+
+/**
+ * Wikimedia Commons (no key): 140M+ free media files with deep per-file metadata.
+ * Twin of `illustration/providers/wikimedia.py`; pinned by `schema/fixtures/wikimedia.expected.json`.
+ *
+ * Quirks carried over: `query.pages` (a list under formatversion 2) is sorted by search `index`;
+ * pagination is offset-based (`gsroffset`); a `Category:…` query routes to the category-members
+ * generator and a `File:…` query to an exact-title lookup (which *drops* `generator`, expressed
+ * as a `null` value the request builder removes); the `Artist` field is HTML; non-images in the
+ * File namespace are dropped by MIME during normalisation.
+ */
+declare const wikimedia: RetrievalSource;
+
+/**
+ * Pexels (key required, raw value in `Authorization`): curated stock photos under the Pexels License.
+ * Twin of `illustration/providers/pexels.py`; pinned by `schema/fixtures/pexels.expected.json`.
+ */
+declare const pexels: RetrievalSource;
+
+/**
+ * Pixabay (key required, as the `key=` query param): free commercial-use images whose licence
+ * permits caching and self-hosting. Twin of `illustration/providers/pixabay.py`; pinned by
+ * `schema/fixtures/pixabay.expected.json`.
+ */
+declare const pixabay: RetrievalSource;
+
+/**
+ * illustration-search — text-to-image retrieval over open-media corpora, in the browser.
+ *
+ * The TypeScript twin of the Python `illustration` package. The result schema,
+ * rights fields, licence tables and provider registry are generated from the
+ * Python side (`schema/` at the repo root); the provider code is ported by hand
+ * and pinned to it by fixtures.
+ *
+ * ```ts
+ * import { search } from 'illustration-search';
+ * const hits = await search('stormy harbour at dusk', { n: 5 });           // Openverse, no key
+ * const stock = await search('harbour', { source: ['pexels', 'pixabay'],  // the caller's own keys
+ *                                         credentials: { pexels, pixabay } });
+ * ```
+ *
+ * Every hit carries `license`, `license_url`, `attribution`, `source_page_url`,
+ * `author`, `author_url` and `cacheable` (`RIGHTS_FIELDS`). Whether a hit may be
+ * used, and whom to credit, is answered from those; the facade never stores bytes.
+ */
+
+/** The seven fields that answer "may we ship this, and whom must we credit?". */
+declare const RIGHTS_FIELDS: readonly ["license", "license_url", "attribution", "source_page_url", "author", "author_url", "cacheable"];
+type RightsField = (typeof RIGHTS_FIELDS)[number];
+
+export { type AuthRecord, CONSTANTS, DEFAULT_LICENSE_ALLOWLIST, IllustrationError, type ImageResult, type ImageResultInput, type Json, type MediaType, MissingCredentialError, type ParamMap, type ParamRecord, type ParamSpec, type ParamTranslator, ProviderError, RIGHTS_FIELDS, RateLimitError, type RetrievalSource, type RightsField, SOURCE_RECORDS, type SearchOptions, type SearchSourceOptions, type SourceHooks, type SourceInfo, type SourceRecord, type Translation, UnknownSourceError, defaultSources, defineSource, getSource, imageResultSchema, licenseAllowlist, listSources, makeParamTranslator, makeResult, normalizeLicense, openverse, perPageFor, pexels, pixabay, registerSource, search, searchSource, sourceRecord, wikimedia };