wiki-entity 0.7.0 → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,370 @@
+/** Statement rank as modelled by Wikibase. */
+type WikidataRank = "preferred" | "normal" | "deprecated";
+/**
+ * A globe coordinate claim value.
+ * @see https://www.wikidata.org/wiki/Help:Data_type#Geographic_coordinates
+ */
+interface WikidataGlobeCoordinateValue {
+    latitude: number;
+    longitude: number;
+    precision?: number | null;
+    globe?: string;
+    altitude?: number | null;
+}
+/**
+ * A point in time claim value. `time` uses a signed, zero padded year, so
+ * BCE dates start with `-`.
+ * @see https://www.wikidata.org/wiki/Help:Dates
+ */
+interface WikidataTimeValue {
+    time: string;
+    precision: number;
+    timezone?: number;
+    before?: number;
+    after?: number;
+    calendarmodel?: string;
+}
+/** A quantity claim value. Bounds are absent for exact quantities. */
+interface WikidataQuantityValue {
+    amount: string;
+    unit?: string;
+    upperBound?: string;
+    lowerBound?: string;
+}
+interface WikidataMonolingualTextValue {
+    text: string;
+    language: string;
+}
+/**
+ * The simplified value of a claim. `value` is a scalar for the common data
+ * types and the raw Wikibase object for structured ones (time, quantity,
+ * globe-coordinate); `value_string` then carries a readable rendering.
+ */
+interface WikidataPropertyValue {
+    datatype: string;
+    value: string | number | WikidataTimeValue | WikidataQuantityValue | WikidataGlobeCoordinateValue;
+    rank?: WikidataRank;
+    pageid?: number;
+    value_string?: string;
+    label?: string;
+    description?: string;
+    qualifiers?: WikidataEntityClaims | null;
+}
+interface WikidataBaseEntity {
+    id: string;
+    label?: string;
+    description?: string;
+    [index: string]: unknown;
+}
+interface WikidataProperty extends WikidataBaseEntity {
+    values: WikidataPropertyValue[];
+}
+type WikidataEntityClaims = Record<string, WikidataProperty>;
+interface WikidataEntity extends WikidataBaseEntity {
+    pageid?: number;
+    /** Wikibase datatype, present on property (`P…`) entities only. */
+    datatype?: string;
+    aliases?: string[];
+    sitelinks?: Record<string, string>;
+    claims?: WikidataEntityClaims;
+    labels?: Record<string, string>;
+    descriptions?: Record<string, string>;
+    redirectsToId?: string;
+    redirectsFromId?: string;
+}
+type WikidataEntities = Record<string, WikidataEntity>;
+interface WikiEntity extends WikidataEntity {
+    extract?: string;
+    types?: string[];
+    redirects?: string[];
+    categories?: string[];
+}
+type WikiEntities = Record<string, WikiEntity>;
+type ParamClaimsType = "none" | "all" | "item" | "property";
+/** Entity props the Wikibase API can return. */
+declare const WIKIDATA_PROPS: readonly ["info", "sitelinks", "aliases", "labels", "descriptions", "claims", "datatype"];
+type WikidataProp = (typeof WIKIDATA_PROPS)[number];
+interface WikidataEntitiesParams {
+    /** Wikidata entity ids, e.g. `["Q42"]`. Max 500. */
+    ids?: string[];
+    /** Wikipedia article titles, resolved against `language`. Max 500. */
+    titles?: string[];
+    /** Which props to fetch. Defaults to all of them. */
+    props?: WikidataProp[];
+    /** Language of `titles` and of the resulting `label`/`description`. */
+    language?: string;
+    /**
+     * Resolve Wikidata entity redirects to their target. Default: `true`.
+     *
+     * This is about *Wikidata items* that were merged into another item. For
+     * Wikipedia redirect titles see {@link WikiEntitiesParams.redirects}.
+     */
+    followEntityRedirects?: boolean;
+    /** How deeply to resolve claim values. Default: `"none"`. */
+    claims?: ParamClaimsType;
+    /** Per request timeout in milliseconds. */
+    httpTimeout?: number;
+    /** Extra languages to populate `WikiEntity.labels` with. */
+    languages?: string[];
+    /** Cancellation signal propagated to every underlying request. */
+    signal?: AbortSignal;
+}
+interface WikiEntitiesParams extends WikidataEntitiesParams {
+    /** Number of sentences in the Wikipedia extract. `0`/absent: no extract. */
+    extract?: number;
+    /**
+     * `true` to resolve DBpedia ontology types, or an array of prefixes to keep.
+     * Known prefixes: `dbo`, `schema`, `foaf`, `owl`, `dul`, `geo`, `wikidata`.
+     */
+    types?: boolean | string[];
+    /**
+     * Fetch the titles of *Wikipedia articles* that redirect to this entity.
+     * Unrelated to {@link WikidataEntitiesParams.followEntityRedirects}.
+     */
+    redirects?: boolean;
+    /** Fetch Wikipedia article categories. */
+    categories?: boolean;
+    /** Fetch the Wikipedia `pageid`. Default: `true`. */
+    wikiPageId?: boolean;
+}
+
+/** Coarse entity category, encoded as a single letter. */
+declare enum SimpleEntityType {
+    EVENT = "E",
+    ORG = "O",
+    PERSON = "H",
+    PLACE = "P",
+    PRODUCT = "R",
+    WORK = "W"
+}
+/** Claim values keyed by property id, e.g. `{ P31: ["Q5"] }`. */
+type SimpleEntityData = {
+    [prop: string]: string[];
+};
+type SimpleEntity = {
+    /** Language the entity was resolved in. Always set. */
+    lang: string;
+    /** Wikidata item id. Always set. */
+    wikiDataId: string;
+    name?: string;
+    description?: string;
+    about?: string;
+    wikiPageId?: number;
+    wikiPageTitle?: string;
+    type?: SimpleEntityType;
+    types?: string[];
+    countryCodes?: string[];
+    data?: SimpleEntityData;
+    categories?: string[];
+    redirectsToId?: string;
+    redirectsFromId?: string;
+};
+
+type ConvertToSimpleEntityOptions = {
+    /** Used when no type could be detected. */
+    defaultType?: SimpleEntityType;
+};
+/**
+ * Flatten a {@link WikiEntity} into the compact {@link SimpleEntity} shape.
+ *
+ * The entity type is resolved from the DBpedia ontology types first, then from
+ * the `P31` claims, and finally from the extract's opening sentence.
+ */
+declare function convertToSimpleEntity(wikiEntity: WikiEntity, lang: string, options?: ConvertToSimpleEntityOptions): SimpleEntity;
+
+type SimplifyEntityOptionsType = {
+    labels?: boolean;
+    descriptions?: boolean;
+    aliases?: boolean;
+    sitelinks?: boolean;
+    claims?: boolean;
+    /** Keep statements Wikidata marks as deprecated. Default: `false`. */
+    keepDeprecatedClaims?: boolean;
+};
+/**
+ * One entity exactly as `action=wbgetentities` returns it. Every field is
+ * optional: the API only sends the props that were asked for.
+ */
+interface WikibaseEntityJson {
+    id?: string;
+    pageid?: number;
+    /** Present on property (`P…`) entities only. */
+    datatype?: string;
+    labels?: Record<string, {
+        value?: string;
+        language?: string;
+    }>;
+    descriptions?: Record<string, {
+        value?: string;
+        language?: string;
+    }>;
+    aliases?: Record<string, {
+        value?: string;
+        language?: string;
+    }[]>;
+    sitelinks?: Record<string, {
+        title?: string;
+        badges?: string[];
+    }>;
+    claims?: Record<string, unknown[]>;
+    redirectsToId?: string;
+    redirectsFromId?: string;
+}
+declare function simplifyEntity(lang: string, data: WikibaseEntityJson, options?: SimplifyEntityOptionsType): WikidataEntity;
+
+/** One Wikipedia article, with whatever extras were requested. */
+type WikipediaPage = {
+    pageid: number;
+    title: string;
+    /** Lead-section summary, when `extract` was requested. */
+    extract?: string;
+    /** Non-hidden category titles, when `categories` was requested. */
+    categories?: string[];
+    /** Titles of articles redirecting here, when `redirects` was requested. */
+    redirects?: string[];
+};
+interface QueryPagesOptions {
+    /** Wikipedia language code, e.g. `"en"`. */
+    lang: string;
+    titles: readonly string[];
+    /** Number of sentences of the lead section to extract. */
+    extract?: number;
+    /** Include the titles of articles redirecting to each page. */
+    redirects?: boolean;
+    /** Include the article's (non hidden) categories. */
+    categories?: boolean;
+    /** Follow redirects, so `titles` pointing at a redirect resolve to its target. */
+    followRedirects?: boolean;
+    httpTimeout?: number;
+    signal?: AbortSignal;
+}
+interface ResolvedTitle {
+    /** The final page title, after normalisation and redirect resolution. */
+    title: string;
+    /** `true` when at least one hop was an actual page redirect. */
+    redirected: boolean;
+}
+interface QueryPagesResult {
+    pages: WikipediaPage[];
+    /** Requested title -> where it ended up. */
+    resolved: Map<string, ResolvedTitle>;
+    /**
+     * Maps each *resolved* page title back to the title that was requested, after
+     * MediaWiki normalisation and redirect resolution.
+     */
+    requestedTitleOf: Map<string, string>;
+}
+/**
+ * Query Wikipedia pages by title, transparently batching, paging through
+ * `continue` responses and mapping the results back to the requested titles.
+ */
+declare function queryPages(options: QueryPagesOptions): Promise<QueryPagesResult>;
+
+/**
+ * Point type lookups at a different SPARQL endpoint (a DBpedia mirror, or a
+ * local Virtuoso instance).
+ */
+declare function setDbpediaEndpoint(url: string): void;
+declare function getDbpediaEndpoint(): string;
+interface EntityTypesOptions {
+    /** Keep only these prefixes, e.g. `["dbo", "schema"]`. Default: all of them. */
+    prefixes?: string[] | undefined;
+    httpTimeout?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Look up ontology types for several English Wikipedia titles at once.
+ *
+ * Resolving them one request per entity floods the public DBpedia endpoint, so
+ * the titles are batched into a single `VALUES` query per group.
+ *
+ * @returns A map keyed by the passed-in names. Names DBpedia knows nothing
+ * about are absent from the map.
+ */
+declare function getEntityTypesByNames(names: readonly string[], prefixesOrOptions?: string[] | EntityTypesOptions): Promise<Map<string, string[]>>;
+
+/**
+ * Override the `User-Agent` sent with every request. Wikimedia asks clients to
+ * identify themselves with an app name and a contact URL or e-mail.
+ *
+ * @example
+ * setUserAgent("MyApp/1.0 (https://myapp.example; me@myapp.example)");
+ */
+declare function setUserAgent(ua: string): void;
+/** The `User-Agent` currently sent with every request. */
+declare function getUserAgent(): string;
+
+/** Base class for every error thrown by this package. */
+declare class WikiEntityError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A transport level failure: non 2xx status, network error or timeout. */
+declare class HttpError extends WikiEntityError {
+    readonly url: string;
+    readonly status?: number | undefined;
+    /** Milliseconds requested by a `Retry-After` response header, if any. */
+    readonly retryAfter: number | undefined;
+    constructor(message: string, url: string, status?: number | undefined, options?: {
+        cause?: unknown;
+        retryAfter?: number;
+    });
+    /**
+     * `true` when retrying the very same request may succeed: rate limiting,
+     * server errors and transport failures.
+     */
+    get retryable(): boolean;
+}
+/** The request succeeded but the MediaWiki/SPARQL endpoint reported an error. */
+declare class ApiError extends WikiEntityError {
+    readonly code?: string | undefined;
+    readonly url?: string | undefined;
+    constructor(message: string, code?: string | undefined, url?: string | undefined);
+}
+
+/**
+ * Fetch entities from Wikidata, optionally enriched with data from Wikipedia
+ * (page id, extract, redirects, categories) and DBpedia (ontology types).
+ *
+ * Results follow the order of the requested `ids`/`titles`; entities that do
+ * not exist are omitted.
+ *
+ * @example
+ * const [europe] = await getEntities({ language: "en", titles: ["Europe"] });
+ */
+declare function getEntities(params: WikiEntitiesParams): Promise<WikiEntity[]>;
+/**
+ * {@link getEntities} followed by {@link convertToSimpleEntity}, in one call.
+ *
+ * The language is taken from `params`, so it cannot drift from the one the
+ * entities were fetched in — passing a different language to
+ * `convertToSimpleEntity` by hand silently mixes languages, because `name` and
+ * `about` come from the fetch while `wikiPageTitle` is read from the sitelinks
+ * of whatever language you passed.
+ *
+ * @example
+ * const entities = await getSimpleEntities({
+ *   language: "en",
+ *   ids: ["Q937"],
+ *   types: true,
+ *   extract: 2
+ * });
+ */
+declare function getSimpleEntities(params: WikiEntitiesParams, options?: ConvertToSimpleEntityOptions): Promise<SimpleEntity[]>;
+interface MapRedirectsOptions {
+    httpTimeout?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Resolve Wikipedia redirect titles to the articles they point at.
+ *
+ * @returns A map of `redirectTitle -> targetTitle`, containing only the titles
+ * that actually are redirects.
+ *
+ * @example
+ * await mapRedirects(["Brashov"], "ro"); // { Brashov: "Brașov" }
+ */
+declare function mapRedirects(titles: string[], lang: string, options?: MapRedirectsOptions): Promise<Record<string, string>>;
+
+export { ApiError, type ConvertToSimpleEntityOptions, type EntityTypesOptions, HttpError, type MapRedirectsOptions, type ParamClaimsType, type QueryPagesOptions, type QueryPagesResult, type ResolvedTitle, type SimpleEntity, type SimpleEntityData, SimpleEntityType, type SimplifyEntityOptionsType, type WikiEntities, type WikiEntitiesParams, type WikiEntity, WikiEntityError, type WikibaseEntityJson, type WikidataBaseEntity, type WikidataEntities, type WikidataEntitiesParams, type WikidataEntity, type WikidataEntityClaims, type WikidataGlobeCoordinateValue, type WikidataMonolingualTextValue, type WikidataProp, type WikidataProperty, type WikidataPropertyValue, type WikidataQuantityValue, type WikidataRank, type WikidataTimeValue, type WikipediaPage, convertToSimpleEntity, getDbpediaEndpoint, getEntities, getEntityTypesByNames, getSimpleEntities, getUserAgent, mapRedirects, queryPages, setDbpediaEndpoint, setUserAgent, simplifyEntity };