metanova 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,493 @@
+import { CheerioAPI } from 'cheerio';
+
+type MetadataType = "website" | "article" | "image" | "product" | "video" | "playlist" | "audio" | "social_post" | "profile" | "app" | "unknown";
+type MediaKind = "image" | "video" | "audio" | "favicon";
+type MetadataSource = "html" | "openGraph" | "twitter" | "jsonLd" | "oEmbed" | "adapter" | "plugin" | "fallback" | "favicon";
+interface MediaAsset {
+    url: string;
+    kind: MediaKind;
+    source: MetadataSource | string;
+    secureUrl?: string;
+    type?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+    title?: string;
+    poster?: string;
+    score?: number;
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+}
+interface Entity {
+    name?: string;
+    url?: string;
+    logo?: string;
+    sameAs?: string[];
+}
+interface ArticleMetadata {
+    headline?: string;
+    section?: string;
+    tags?: string[];
+    publishedTime?: string;
+    modifiedTime?: string;
+    expirationTime?: string;
+    authors?: Entity[];
+    publisher?: Entity;
+}
+interface ProductMetadata {
+    name?: string;
+    brand?: Entity;
+    sku?: string;
+    price?: string;
+    currency?: string;
+    availability?: string;
+    condition?: string;
+    ratingValue?: number;
+    reviewCount?: number;
+}
+interface ApplicationMetadata {
+    name?: string;
+    category?: string;
+    operatingSystem?: string;
+    price?: string;
+    currency?: string;
+}
+interface VideoMetadata {
+    id?: string;
+    title?: string;
+    channel?: Entity;
+    publishedTime?: string;
+    duration?: string;
+    tags?: string[];
+    category?: string;
+    viewCount?: number;
+}
+interface PlaylistVideo {
+    id: string;
+    title?: string;
+    url: string;
+}
+interface PlaylistMetadata {
+    id?: string;
+    title?: string;
+    channel?: Entity;
+    videos: PlaylistVideo[];
+}
+interface MetadataSourceAttribution {
+    title?: string;
+    description?: string;
+    author?: string;
+    image?: string;
+}
+interface PreviewCard {
+    title?: string;
+    description?: string;
+    image?: string;
+    url: string;
+    siteName?: string;
+    domain?: string;
+    author?: string;
+    type: MetadataType;
+    confidence: number;
+}
+interface RedirectEntry {
+    from: string;
+    to: string;
+    statusCode: number;
+}
+interface ExtractionDiagnostics {
+    originalUrl?: string;
+    finalUrl?: string;
+    canonicalUrl?: string;
+    isShortUrl?: boolean;
+    shortUrlProvider?: string;
+    statusCode?: number;
+    contentType?: string;
+    redirects: RedirectEntry[];
+    sourcesUsed: string[];
+    warnings: string[];
+    trace: string[];
+    adapter?: {
+        matched: boolean;
+        name?: string;
+        confidence?: number;
+    };
+    errors?: string[];
+    selectedImageReason?: string;
+    fetchDurationMs?: number;
+    extractedAt: string;
+}
+interface UnifiedMetadata {
+    ok: boolean;
+    url: string;
+    finalUrl: string;
+    type: MetadataType;
+    title?: string;
+    description?: string;
+    siteName?: string;
+    canonicalUrl?: string;
+    confidence: number;
+    completeness: number;
+    reliability: number;
+    bestImage?: string;
+    images: MediaAsset[];
+    videos: MediaAsset[];
+    audio: MediaAsset[];
+    favicons: MediaAsset[];
+    article?: ArticleMetadata;
+    product?: ProductMetadata;
+    video?: VideoMetadata;
+    playlist?: PlaylistMetadata;
+    author?: Entity;
+    publisher?: Entity;
+    app?: ApplicationMetadata;
+    sources?: MetadataSourceAttribution;
+    raw?: RawMetadataSources;
+    diagnostics: ExtractionDiagnostics;
+    trace: string[];
+}
+interface HtmlMetadata {
+    title?: string;
+    description?: string;
+    keywords?: string[];
+    robots?: string;
+    canonicalUrl?: string;
+    manifestUrl?: string;
+    themeColor?: string;
+    applicationName?: string;
+    favicons: MediaAsset[];
+    imageSrc?: MediaAsset;
+    alternates: Array<{
+        href: string;
+        type?: string;
+        hreflang?: string;
+        title?: string;
+    }>;
+}
+interface OpenGraphMetadata {
+    title?: string;
+    description?: string;
+    type?: string;
+    url?: string;
+    siteName?: string;
+    locale?: string;
+    determiner?: string;
+    images: MediaAsset[];
+    videos: MediaAsset[];
+    audio: MediaAsset[];
+    article?: ArticleMetadata;
+    product?: ProductMetadata;
+    raw: Record<string, string | string[]>;
+}
+interface TwitterMetadata {
+    card?: string;
+    site?: string;
+    creator?: string;
+    title?: string;
+    description?: string;
+    images: MediaAsset[];
+    videos: MediaAsset[];
+    raw: Record<string, string | string[]>;
+}
+type JsonLdNode = Record<string, unknown>;
+interface JsonLdMetadata {
+    nodes: JsonLdNode[];
+    warnings: string[];
+}
+interface OEmbedLink {
+    href: string;
+    type?: string;
+    title?: string;
+}
+interface OEmbedData {
+    type?: string;
+    version?: string;
+    title?: string;
+    author_name?: string;
+    author_url?: string;
+    provider_name?: string;
+    provider_url?: string;
+    thumbnail_url?: string;
+    thumbnail_width?: number;
+    thumbnail_height?: number;
+    html?: string;
+    url?: string;
+    width?: number;
+    height?: number;
+    [key: string]: unknown;
+}
+interface OEmbedMetadata {
+    links: OEmbedLink[];
+    data: OEmbedData[];
+}
+interface EmbeddedDataItem {
+    source: "nextData" | "nuxt" | "initialState" | "preloadedState" | "apollo" | "jsonScript" | "applicationJson" | "youtubeInitialData" | "youtubePlayerResponse";
+    path?: string;
+    data: JsonLdNode;
+}
+interface EmbeddedDataMetadata {
+    items: EmbeddedDataItem[];
+    warnings: string[];
+}
+interface AdapterExtractionResult {
+    source: string;
+    type?: MetadataType;
+    title?: string;
+    description?: string;
+    siteName?: string;
+    canonicalUrl?: string;
+    images?: MediaAsset[];
+    videos?: MediaAsset[];
+    audio?: MediaAsset[];
+    article?: Partial<ArticleMetadata>;
+    product?: Partial<ProductMetadata>;
+    video?: Partial<VideoMetadata>;
+    playlist?: Partial<PlaylistMetadata>;
+    app?: Partial<ApplicationMetadata>;
+    author?: Entity;
+    publisher?: Entity;
+    raw?: Record<string, unknown>;
+    warnings?: string[];
+}
+type PluginExtractionResult = AdapterExtractionResult;
+interface RawMetadataSources {
+    html: HtmlMetadata;
+    openGraph: OpenGraphMetadata;
+    twitter: TwitterMetadata;
+    jsonLd: JsonLdMetadata;
+    embeddedData: EmbeddedDataMetadata;
+    oEmbed: OEmbedMetadata;
+    images: MediaAsset[];
+    videos: MediaAsset[];
+    audio: MediaAsset[];
+    adapters: AdapterExtractionResult[];
+    plugins: PluginExtractionResult[];
+}
+interface ExtractorContext {
+    html: string;
+    url: string;
+    finalUrl: string;
+    $: CheerioAPI;
+    raw: RawMetadataSources;
+    options: ParseMetadataOptions;
+}
+type AdapterContext = ExtractorContext;
+type AdapterRawData = AdapterExtractionResult | Record<string, unknown>;
+interface SiteAdapter<TRawData extends AdapterRawData = AdapterExtractionResult> {
+    name: string;
+    detect?: (url: URL) => boolean;
+    canHandle?: (url: URL) => boolean;
+    extract(context: AdapterContext): TRawData | Promise<TRawData>;
+    normalize?: (rawData: TRawData, context: AdapterContext) => AdapterExtractionResult | Promise<AdapterExtractionResult>;
+}
+interface CustomExtractor {
+    name: string;
+    extract(context: ExtractorContext): PluginExtractionResult | Promise<PluginExtractionResult>;
+}
+type ImageScorer = (image: MediaAsset, context: ImageScoringContext) => number;
+interface ImageScoringContext {
+    index: number;
+    images: MediaAsset[];
+}
+interface MetaNovaPluginApi {
+    addAdapter(adapter: SiteAdapter): void;
+    addExtractor(name: string, extractor: CustomExtractor["extract"]): void;
+    addImageScorer(scorer: ImageScorer): void;
+}
+interface MetaNovaPlugin {
+    name: string;
+    setup(api: MetaNovaPluginApi): void;
+}
+interface MetaNovaCacheEntry {
+    html: string;
+    finalUrl?: string;
+    statusCode?: number;
+    contentType?: string;
+    redirects?: RedirectEntry[];
+}
+interface MetaNovaCache {
+    get(url: string): MetaNovaCacheEntry | undefined | Promise<MetaNovaCacheEntry | undefined>;
+    set(url: string, entry: MetaNovaCacheEntry): void | Promise<void>;
+}
+interface ParseMetadataOptions {
+    includeRaw?: boolean;
+    plugins?: MetaNovaPlugin[];
+    adapters?: SiteAdapter[];
+    imageScorers?: ImageScorer[];
+}
+interface FetchMetadataOptions extends ParseMetadataOptions {
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+    maxRedirects?: number;
+    maxBytes?: number;
+    userAgent?: string;
+    accept?: string;
+    acceptLanguage?: string;
+    acceptEncoding?: string;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+    cache?: MetaNovaCache;
+    allowedProtocols?: string[];
+    allowLocalhost?: boolean;
+    allowPrivateNetwork?: boolean;
+    fetchOEmbed?: boolean;
+}
+
+declare function createPreviewCard(metadata: UnifiedMetadata): PreviewCard;
+
+interface MetaNovaRuntime {
+    use(plugin: MetaNovaPlugin): MetaNovaRuntime;
+    fetchMetadata(url: string, options?: FetchMetadataOptions): Promise<UnifiedMetadata>;
+    parseMetadata(html: string, url: string, options?: ParseMetadataOptions): UnifiedMetadata;
+    parseMetadataAsync(html: string, url: string, options?: ParseMetadataOptions): Promise<UnifiedMetadata>;
+    createPreviewCard: typeof createPreviewCard;
+}
+declare const MetaNova: MetaNovaRuntime;
+
+declare function fetchMetadata(url: string, options?: FetchMetadataOptions): Promise<UnifiedMetadata>;
+
+declare function parseMetadata(html: string, url: string, options?: ParseMetadataOptions): UnifiedMetadata;
+declare function parseMetadataAsync(html: string, url: string, options?: ParseMetadataOptions): Promise<UnifiedMetadata>;
+
+interface ValidateUrlOptions {
+    allowedProtocols?: string[];
+}
+interface ShortUrlInfo {
+    isShortUrl: boolean;
+    provider?: string;
+}
+declare function validateUrl(input: string, options?: ValidateUrlOptions): URL;
+declare function resolveUrl(url: string, baseUrl?: string): string;
+declare function normalizeUrl(input: string, options?: ValidateUrlOptions): string;
+declare function detectShortUrl(input: string | URL): ShortUrlInfo;
+declare function resolveCanonicalUrl(canonicalUrl: string | undefined, baseUrl: string): string | undefined;
+
+interface NormalizeContext {
+    url?: string;
+    finalUrl?: string;
+    diagnostics?: ExtractionDiagnostics;
+    imageScorers?: ImageScorer[];
+    includeRaw?: boolean;
+}
+declare function normalizeMetadata(rawSources: RawMetadataSources, context?: NormalizeContext): UnifiedMetadata;
+
+declare function scoreImages(images: MediaAsset[], customScorers?: ImageScorer[]): MediaAsset[];
+
+interface ConfidenceEngineInput {
+    title?: string;
+    description?: string;
+    bestImage?: MediaAsset;
+    canonicalUrl?: string;
+    author?: Entity;
+    hasStructuredData: boolean;
+    rawSources: RawMetadataSources;
+    sourcesUsed: string[];
+    warnings: string[];
+}
+interface CompletenessInput {
+    title?: string;
+    description?: string;
+    bestImage?: MediaAsset;
+    canonicalUrl?: string;
+    siteName?: string;
+    author?: Entity;
+    publisher?: Entity;
+    type?: string;
+    publishedTime?: string;
+    mediaCount: number;
+}
+interface ReliabilityInput {
+    confidence: number;
+    completeness: number;
+    adapterMatched: boolean;
+    bestImage?: MediaAsset;
+    warnings: string[];
+}
+declare function calculateConfidence(input: ConfidenceEngineInput): number;
+declare function calculateCompleteness(input: CompletenessInput): number;
+declare function calculateReliability(input: ReliabilityInput): number;
+
+interface MediaDiscoveryResult {
+    images: MediaAsset[];
+    videos: MediaAsset[];
+    audio: MediaAsset[];
+    trace: string[];
+}
+declare function discoverMedia(rawSources: RawMetadataSources, finalUrl: string): MediaDiscoveryResult;
+
+declare function extractHtmlMetadata(html: string): HtmlMetadata;
+
+declare function extractEmbeddedData(html: string): EmbeddedDataMetadata;
+
+declare function extractJsonLd(html: string): JsonLdMetadata;
+
+declare function extractImages(html: string, baseUrl: string): MediaAsset[];
+declare function extractVideos(html: string, baseUrl: string): MediaAsset[];
+declare function extractAudio(html: string, baseUrl: string): MediaAsset[];
+
+declare function extractOEmbed(html: string, url: string): OEmbedMetadata;
+
+declare function extractOpenGraph(html: string): OpenGraphMetadata;
+
+declare function extractTwitterCards(html: string): TwitterMetadata;
+
+type PlatformRawData = AdapterExtractionResult & {
+    platform?: string;
+    identifiers?: Record<string, string | undefined>;
+};
+declare const youtubeAdapter: SiteAdapter<PlatformRawData>;
+declare const redditAdapter: SiteAdapter<PlatformRawData>;
+declare const pinterestAdapter: SiteAdapter<PlatformRawData>;
+declare const behanceAdapter: SiteAdapter<PlatformRawData>;
+declare const tiktokAdapter: SiteAdapter<PlatformRawData>;
+declare const facebookAdapter: SiteAdapter<PlatformRawData>;
+declare const twitterAdapter: SiteAdapter<PlatformRawData>;
+declare const instagramAdapter: SiteAdapter<PlatformRawData>;
+declare const defaultAdapters: SiteAdapter[];
+
+declare function createDiagnostics(): ExtractionDiagnostics;
+declare function addWarning(diagnostics: ExtractionDiagnostics, warning: string): ExtractionDiagnostics;
+
+declare const DEFAULT_BROWSER_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+declare const DEFAULT_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7";
+declare const DEFAULT_ACCEPT_LANGUAGE = "en-US,en;q=0.9";
+declare const DEFAULT_ACCEPT_ENCODING = "gzip, deflate, br";
+interface FetchedPage {
+    url: string;
+    originalUrl: string;
+    finalUrl: string;
+    isShortUrl: boolean;
+    shortUrlProvider?: string;
+    html: string;
+    bytes?: Uint8Array;
+    statusCode: number;
+    contentType?: string;
+    redirects: RedirectEntry[];
+    headers: Record<string, string>;
+}
+declare function fetchPage(inputUrl: string, options?: FetchMetadataOptions): Promise<FetchedPage>;
+interface RedirectResolution {
+    originalUrl: string;
+    finalUrl: string;
+    redirects: RedirectEntry[];
+    isShortUrl: boolean;
+    shortUrlProvider?: string;
+}
+declare function resolveRedirects(inputUrl: string, options?: FetchMetadataOptions): Promise<RedirectResolution>;
+
+declare class SecurityError extends Error {
+    constructor(message: string);
+}
+declare function assertSafeRequestUrl(input: string, options?: FetchMetadataOptions): Promise<string>;
+
+interface MetaNovaRegistry {
+    adapters: SiteAdapter[];
+    extractors: CustomExtractor[];
+    imageScorers: ImageScorer[];
+}
+declare function registerGlobalPlugin(plugin: MetaNovaPlugin): void;
+declare function createRegistry(options?: ParseMetadataOptions): MetaNovaRegistry;
+
+export { type AdapterContext, type AdapterExtractionResult, type AdapterRawData, type ApplicationMetadata, type ArticleMetadata, type CompletenessInput, type ConfidenceEngineInput, type CustomExtractor, DEFAULT_ACCEPT, DEFAULT_ACCEPT_ENCODING, DEFAULT_ACCEPT_LANGUAGE, DEFAULT_BROWSER_USER_AGENT, type EmbeddedDataItem, type EmbeddedDataMetadata, type Entity, type ExtractionDiagnostics, type ExtractorContext, type FetchMetadataOptions, type FetchedPage, type HtmlMetadata, type ImageScorer, type ImageScoringContext, type JsonLdMetadata, type JsonLdNode, type MediaAsset, type MediaDiscoveryResult, type MediaKind, MetaNova, type MetaNovaCache, type MetaNovaCacheEntry, type MetaNovaPlugin, type MetaNovaPluginApi, type MetaNovaRegistry, type MetadataSource, type MetadataSourceAttribution, type MetadataType, type OEmbedData, type OEmbedLink, type OEmbedMetadata, type OpenGraphMetadata, type ParseMetadataOptions, type PlaylistMetadata, type PlaylistVideo, type PluginExtractionResult, type PreviewCard, type ProductMetadata, type RawMetadataSources, type RedirectEntry, type RedirectResolution, type ReliabilityInput, SecurityError, type SiteAdapter, type TwitterMetadata, type UnifiedMetadata, type VideoMetadata, addWarning, assertSafeRequestUrl, behanceAdapter, calculateCompleteness, calculateConfidence, calculateReliability, createDiagnostics, createPreviewCard, createRegistry, MetaNova as default, defaultAdapters, detectShortUrl, discoverMedia, extractAudio, extractEmbeddedData, extractHtmlMetadata, extractImages, extractJsonLd, extractOEmbed, extractOpenGraph, extractTwitterCards, extractVideos, facebookAdapter, fetchMetadata, fetchPage, instagramAdapter, normalizeMetadata, normalizeUrl, parseMetadata, parseMetadataAsync, pinterestAdapter, redditAdapter, registerGlobalPlugin, resolveCanonicalUrl, resolveRedirects, resolveUrl, scoreImages, tiktokAdapter, twitterAdapter, validateUrl, youtubeAdapter };