import * as dntShim from "../_dnt.shims.js";
import type { KvKey, KvStore } from "../federation/kv.js";
/**
 * A remote JSON-LD document and its context fetched by
 * a {@link DocumentLoader}.
 */
export interface RemoteDocument {
    /**
     * The URL of the context document.
     */
    contextUrl: string | null;
    /**
     * The fetched JSON-LD document.
     */
    document: unknown;
    /**
     * The URL of the fetched document.
     */
    documentUrl: string;
}
/**
 * A JSON-LD document loader that fetches documents from the Web.
 * @param url The URL of the document to load.
 * @returns The loaded remote document.
 */
export type DocumentLoader = (url: string) => Promise<RemoteDocument>;
/**
 * A factory function that creates a {@link DocumentLoader} with options.
 * @param options The options for the document loader.
 * @returns The document loader.
 * @since 1.4.0
 */
export type DocumentLoaderFactory = (options?: DocumentLoaderFactoryOptions) => DocumentLoader;
/**
 * Options for {@link DocumentLoaderFactory}.
 * @see {@link DocumentLoaderFactory}
 * @see {@link AuthenticatedDocumentLoaderFactory}
 * @since 1.4.0
 */
export interface DocumentLoaderFactoryOptions {
    /**
     * Whether to allow fetching private network addresses.
     * Turned off by default.
     * @default `false``
     */
    allowPrivateAddress?: boolean;
    /**
     * Options for making `User-Agent` string.
     * If a string is given, it is used as the `User-Agent` header value.
     * If an object is given, it is passed to {@link getUserAgent} function.
     */
    userAgent?: GetUserAgentOptions | string;
}
/**
 * A factory function that creates an authenticated {@link DocumentLoader} for
 * a given identity.  This is used for fetching documents that require
 * authentication.
 * @param identity The identity to create the document loader for.
 *                 The actor's key pair.
 * @param options The options for the document loader.
 * @returns The authenticated document loader.
 * @since 0.4.0
 */
export type AuthenticatedDocumentLoaderFactory = (identity: {
    keyId: URL;
    privateKey: dntShim.CryptoKey;
}, options?: DocumentLoaderFactoryOptions) => DocumentLoader;
/**
 * Error thrown when fetching a JSON-LD document failed.
 */
export declare class FetchError extends Error {
    /**
     * The URL that failed to fetch.
     */
    url: URL;
    /**
     * Constructs a new `FetchError`.
     *
     * @param url The URL that failed to fetch.
     * @param message Error message.
     */
    constructor(url: URL | string, message?: string);
}
/**
 * Options for {@link getDocumentLoader}.
 * @since 1.3.0
 */
export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
    /**
     * Whether to preload the frequently used contexts.
     */
    skipPreloadedContexts?: boolean;
}
/**
 * Creates a JSON-LD document loader that utilizes the browser's `fetch` API.
 *
 * The created loader preloads the below frequently used contexts by default
 * (unless `options.ignorePreloadedContexts` is set to `true`):
 *
 * - <https://www.w3.org/ns/activitystreams>
 * - <https://w3id.org/security/v1>
 * - <https://w3id.org/security/data-integrity/v1>
 * - <https://www.w3.org/ns/did/v1>
 * - <https://w3id.org/security/multikey/v1>
 * - <https://purl.archive.org/socialweb/webfinger>
 * - <http://schema.org/>
 * @param options Options for the document loader.
 * @returns The document loader.
 * @since 1.3.0
 */
export declare function getDocumentLoader({ allowPrivateAddress, skipPreloadedContexts, userAgent }?: GetDocumentLoaderOptions): DocumentLoader;
/**
 * A JSON-LD document loader that utilizes the browser's `fetch` API.
 *
 * This loader preloads the below frequently used contexts:
 *
 * - <https://www.w3.org/ns/activitystreams>
 * - <https://w3id.org/security/v1>
 * - <https://w3id.org/security/data-integrity/v1>
 * - <https://www.w3.org/ns/did/v1>
 * - <https://w3id.org/security/multikey/v1>
 * - <https://purl.archive.org/socialweb/webfinger>
 * - <http://schema.org/>
 * @param url The URL of the document to load.
 * @param allowPrivateAddress Whether to allow fetching private network
 *                            addresses.  Turned off by default.
 * @returns The remote document.
 * @deprecated Use {@link getDocumentLoader} instead.
 */
export declare function fetchDocumentLoader(url: string, allowPrivateAddress?: boolean): Promise<RemoteDocument>;
/**
 * Options for {@link getAuthenticatedDocumentLoader}.
 * @see {@link getAuthenticatedDocumentLoader}
 * @since 1.3.0
 */
export interface GetAuthenticatedDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
}
/**
 * Gets an authenticated {@link DocumentLoader} for the given identity.
 * Note that an authenticated document loader intentionally does not cache
 * the fetched documents.
 * @param identity The identity to get the document loader for.
 *                 The actor's key pair.
 * @param options The options for the document loader.
 * @returns The authenticated document loader.
 * @throws {TypeError} If the key is invalid or unsupported.
 * @since 0.4.0
 */
export declare function getAuthenticatedDocumentLoader(identity: {
    keyId: URL;
    privateKey: dntShim.CryptoKey;
}, { allowPrivateAddress, userAgent }?: GetAuthenticatedDocumentLoaderOptions): DocumentLoader;
/**
 * The parameters for {@link kvCache} function.
 */
export interface KvCacheParameters {
    /**
     * The document loader to decorate with a cache.
     */
    loader: DocumentLoader;
    /**
     * The key-value store to use for backing the cache.
     */
    kv: KvStore;
    /**
     * The key prefix to use for namespacing the cache.
     * `["_fedify", "remoteDocument"]` by default.
     */
    prefix?: KvKey;
    /**
     * The per-URL cache rules in the array of `[urlPattern, duration]` pairs
     * where `urlPattern` is either a string, a {@link URL}, or
     * a {@link URLPattern} and `duration` is a {@link Temporal.Duration}.
     * The `duration` is allowed to be at most 30 days.
     *
     * By default, 5 minutes for all URLs.
     */
    rules?: [string | URL | dntShim.URLPattern, dntShim.Temporal.Duration][];
}
/**
 * Decorates a {@link DocumentLoader} with a cache backed by a {@link Deno.Kv}.
 * @param parameters The parameters for the cache.
 * @returns The decorated document loader which is cache-enabled.
 */
export declare function kvCache({ loader, kv, prefix, rules }: KvCacheParameters): DocumentLoader;
/**
 * Options for making `User-Agent` string.
 * @see {@link getUserAgent}
 * @since 1.3.0
 */
export interface GetUserAgentOptions {
    /**
     * An optional software name and version, e.g., `"Hollo/1.0.0"`.
     */
    software?: string | null;
    /**
     * An optional URL to append to the user agent string.
     * Usually the URL of the ActivityPub instance.
     */
    url?: string | URL | null;
}
/**
 * Gets the user agent string for the given application and URL.
 * @param options The options for making the user agent string.
 * @returns The user agent string.
 * @since 1.3.0
 */
export declare function getUserAgent({ software, url }?: GetUserAgentOptions): string;
//# sourceMappingURL=docloader.d.ts.map