@fedify/vocab-runtime 2.4.0-dev.1567 → 2.4.0-dev.1570

package/dist/mod.d.cts

@@ -1,35 +1,210 @@
 /// <reference lib="esnext.temporal" />
-import { a as DocumentLoaderOptions, c as getDocumentLoader, d as FetchError, f as GetUserAgentOptions, h as logRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as getUserAgent, n as DocumentLoader, o as GetDocumentLoaderOptions, p as createActivityPubRequest, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as CreateRequestOptions } from "./docloader-DnUMWHaJ.cjs";
+import { Logger } from "@logtape/logtape";
 import { TracerProvider } from "@opentelemetry/api";
 
 //#region src/contexts.d.ts
 declare const preloadedContexts: Record<string, unknown>;
 //#endregion
-//#region src/key.d.ts
+//#region src/request.d.ts
 /**
-* Parsed `did:key` verification method.
-*
-* @since 2.4.0
+* Error thrown when fetching a JSON-LD document failed.
 */
-interface DidKeyVerificationMethod {
+declare class FetchError extends Error {
   /**
-  * The DID URL identifying the verification method.
+  * The URL that failed to fetch.
   */
-  readonly id: URL;
+  url: URL;
   /**
-  * The controller DID.
+  * The HTTP response that failed, if available.
   */
-  readonly controller: URL;
+  response?: Response;
+  /**
+  * Constructs a new `FetchError`.
+  *
+  * @param url The URL that failed to fetch.
+  * @param message Error message.
+  * @param response The failed HTTP response, if available.
+  */
+  constructor(url: URL | string, message?: string, response?: Response);
+}
+/**
+* Options for creating a request.
+* @internal
+*/
+interface CreateRequestOptions {
+  userAgent?: GetUserAgentOptions | string;
+}
+/**
+* Creates a request for the given URL.
+* @param url The URL to create the request for.
+* @param options The options for the request.
+* @returns The created request.
+* @internal
+*/
+declare function createActivityPubRequest(url: string, options?: CreateRequestOptions): Request;
+/**
+* Options for making `User-Agent` string.
+* @see {@link getUserAgent}
+* @since 1.3.0
+*/
+interface GetUserAgentOptions {
   /**
-  * The Ed25519 public key encoded as a Multibase Multikey value.
+  * An optional software name and version, e.g., `"Hollo/1.0.0"`.
   */
-  readonly publicKeyMultibase: string;
+  software?: string | null;
   /**
-  * The Ed25519 public key.
+  * An optional URL to append to the user agent string.
+  * Usually the URL of the ActivityPub instance.
   */
-  readonly publicKey: CryptoKey;
+  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
+*/
+declare function getUserAgent({
+  software,
+  url
+}?: GetUserAgentOptions): string;
+/**
+* Logs the request.
+* @param request The request to log.
+* @internal
+*/
+declare function logRequest(logger: Logger, request: Request): void;
+//#endregion
+//#region src/docloader.d.ts
+/**
+* A remote JSON-LD document and its context fetched by
+* a {@link DocumentLoader}.
+*/
+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;
+}
+/**
+* Options for {@link DocumentLoader}.
+* @since 1.8.0
+*/
+interface DocumentLoaderOptions {
+  /**
+  * An `AbortSignal` for cancellation.
+  * @since 1.8.0
+  */
+  signal?: AbortSignal;
+}
+/**
+* A JSON-LD document loader that fetches documents from the Web.
+* @param url The URL of the document to load.
+* @param options The options for the document loader.
+* @returns The loaded remote document.
+*/
+type DocumentLoader = (url: string, options?: DocumentLoaderOptions) => 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
+*/
+type DocumentLoaderFactory = (options?: DocumentLoaderFactoryOptions) => DocumentLoader;
+/**
+* Options for {@link DocumentLoaderFactory}.
+* @see {@link DocumentLoaderFactory}
+* @see {@link AuthenticatedDocumentLoaderFactory}
+* @since 1.4.0
+*/
+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;
+  /**
+  * The maximum number of redirections to follow.
+  * @default `20`
+  * @since 2.2.0
+  */
+  maxRedirection?: number;
+}
+/**
+* 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
+*/
+type AuthenticatedDocumentLoaderFactory = (identity: {
+  keyId: URL;
+  privateKey: CryptoKey;
+}, options?: DocumentLoaderFactoryOptions) => DocumentLoader;
+/**
+* Gets a {@link RemoteDocument} from the given response.
+* @param url The URL of the document to load.
+* @param response The response to get the document from.
+* @param fetch The function to fetch the document.
+* @returns The loaded remote document.
+* @throws {FetchError} If the response is not OK.
+* @internal
+*/
+declare function getRemoteDocument(url: string, response: Response, fetch: (url: string, options?: DocumentLoaderOptions) => Promise<RemoteDocument>): Promise<RemoteDocument>;
+/**
+* Options for {@link getDocumentLoader}.
+* @since 1.3.0
+*/
+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.skipPreloadedContexts` 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
+*/
+declare function getDocumentLoader({
+  allowPrivateAddress,
+  maxRedirection,
+  skipPreloadedContexts,
+  userAgent
+}?: GetDocumentLoaderOptions): DocumentLoader;
+//#endregion
+//#region src/key.d.ts
+/**
 * Imports a PEM-SPKI formatted public key.
 * @param pem The PEM-SPKI formatted public key.
 * @returns The imported public key.
@@ -62,34 +237,6 @@ declare function importPkcs1(pem: string): Promise<CryptoKey>;
 */
 declare function importPem(pem: string): Promise<CryptoKey>;
 /**
-* Imports an Ed25519 `did:key` DID.
-*
-* @param did The `did:key` DID.
-* @returns The imported Ed25519 public key.
-* @throws {TypeError} If the DID is malformed or uses an unsupported key type.
-* @since 2.4.0
-*/
-declare function importDidKey(did: string | URL): Promise<CryptoKey>;
-/**
-* Exports an Ed25519 public key as a `did:key` DID.
-*
-* @param key The Ed25519 public key.
-* @returns The `did:key` DID.
-* @throws {TypeError} If the key is invalid or unsupported.
-* @since 2.4.0
-*/
-declare function exportDidKey(key: CryptoKey): Promise<string>;
-/**
-* Parses an Ed25519 `did:key` verification method DID URL.
-*
-* @param didUrl The `did:key` DID URL.
-* @returns The parsed verification method.
-* @throws {TypeError} If the DID URL is malformed, unsupported, or its
-*                     fragment does not identify the same key as the DID.
-* @since 2.4.0
-*/
-declare function parseDidKeyVerificationMethod(didUrl: string | URL): Promise<DidKeyVerificationMethod>;
-/**
 * Imports a [Multibase]-encoded public key.
 *
 * [Multibase]: https://www.w3.org/TR/vc-data-integrity/#multibase-0
@@ -314,22 +461,6 @@ declare class UrlError extends Error {
   constructor(message: string);
 }
 /**
-* Parses a JSON-LD `@id` value as an IRI.
-*/
-declare function parseJsonLdId(id: string | undefined, base?: string | URL): URL | undefined;
-/**
-* Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
-*/
-declare function parseIri(iri: string | URL, base?: string | URL): URL;
-/**
-* Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
-*/
-declare function formatIri(iri: string | URL): string;
-/**
-* Checks whether two IRIs have the same origin.
-*/
-declare function haveSameIriOrigin(left: URL, right: URL): boolean;
-/**
 * Validates a URL to prevent SSRF attacks.
 */
 declare function validatePublicUrl(url: string): Promise<void>;
@@ -337,4 +468,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
 declare function isValidPublicIPv6Address(address: string): boolean;
 declare function expandIPv6Address(address: string): string;
 //#endregion
-export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, canParseDecimal, createActivityPubRequest, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, getDocumentLoader, getRemoteDocument, getUserAgent, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseIri, parseJsonLdId, preloadedContexts, validatePublicUrl };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, canParseDecimal, createActivityPubRequest, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportMultibaseKey, exportSpki, getDocumentLoader, getRemoteDocument, getUserAgent, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, preloadedContexts, validatePublicUrl };

package/dist/mod.d.ts

@@ -1,35 +1,210 @@
 /// <reference lib="esnext.temporal" />
-import { a as DocumentLoaderOptions, c as getDocumentLoader, d as FetchError, f as GetUserAgentOptions, h as logRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as getUserAgent, n as DocumentLoader, o as GetDocumentLoaderOptions, p as createActivityPubRequest, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as CreateRequestOptions } from "./docloader-xRGn1azD.js";
+import { Logger } from "@logtape/logtape";
 import { TracerProvider } from "@opentelemetry/api";
 
 //#region src/contexts.d.ts
 declare const preloadedContexts: Record<string, unknown>;
 //#endregion
-//#region src/key.d.ts
+//#region src/request.d.ts
 /**
-* Parsed `did:key` verification method.
-*
-* @since 2.4.0
+* Error thrown when fetching a JSON-LD document failed.
 */
-interface DidKeyVerificationMethod {
+declare class FetchError extends Error {
   /**
-  * The DID URL identifying the verification method.
+  * The URL that failed to fetch.
   */
-  readonly id: URL;
+  url: URL;
   /**
-  * The controller DID.
+  * The HTTP response that failed, if available.
   */
-  readonly controller: URL;
+  response?: Response;
+  /**
+  * Constructs a new `FetchError`.
+  *
+  * @param url The URL that failed to fetch.
+  * @param message Error message.
+  * @param response The failed HTTP response, if available.
+  */
+  constructor(url: URL | string, message?: string, response?: Response);
+}
+/**
+* Options for creating a request.
+* @internal
+*/
+interface CreateRequestOptions {
+  userAgent?: GetUserAgentOptions | string;
+}
+/**
+* Creates a request for the given URL.
+* @param url The URL to create the request for.
+* @param options The options for the request.
+* @returns The created request.
+* @internal
+*/
+declare function createActivityPubRequest(url: string, options?: CreateRequestOptions): Request;
+/**
+* Options for making `User-Agent` string.
+* @see {@link getUserAgent}
+* @since 1.3.0
+*/
+interface GetUserAgentOptions {
   /**
-  * The Ed25519 public key encoded as a Multibase Multikey value.
+  * An optional software name and version, e.g., `"Hollo/1.0.0"`.
   */
-  readonly publicKeyMultibase: string;
+  software?: string | null;
   /**
-  * The Ed25519 public key.
+  * An optional URL to append to the user agent string.
+  * Usually the URL of the ActivityPub instance.
   */
-  readonly publicKey: CryptoKey;
+  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
+*/
+declare function getUserAgent({
+  software,
+  url
+}?: GetUserAgentOptions): string;
+/**
+* Logs the request.
+* @param request The request to log.
+* @internal
+*/
+declare function logRequest(logger: Logger, request: Request): void;
+//#endregion
+//#region src/docloader.d.ts
+/**
+* A remote JSON-LD document and its context fetched by
+* a {@link DocumentLoader}.
+*/
+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;
+}
+/**
+* Options for {@link DocumentLoader}.
+* @since 1.8.0
+*/
+interface DocumentLoaderOptions {
+  /**
+  * An `AbortSignal` for cancellation.
+  * @since 1.8.0
+  */
+  signal?: AbortSignal;
+}
+/**
+* A JSON-LD document loader that fetches documents from the Web.
+* @param url The URL of the document to load.
+* @param options The options for the document loader.
+* @returns The loaded remote document.
+*/
+type DocumentLoader = (url: string, options?: DocumentLoaderOptions) => 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
+*/
+type DocumentLoaderFactory = (options?: DocumentLoaderFactoryOptions) => DocumentLoader;
+/**
+* Options for {@link DocumentLoaderFactory}.
+* @see {@link DocumentLoaderFactory}
+* @see {@link AuthenticatedDocumentLoaderFactory}
+* @since 1.4.0
+*/
+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;
+  /**
+  * The maximum number of redirections to follow.
+  * @default `20`
+  * @since 2.2.0
+  */
+  maxRedirection?: number;
+}
+/**
+* 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
+*/
+type AuthenticatedDocumentLoaderFactory = (identity: {
+  keyId: URL;
+  privateKey: CryptoKey;
+}, options?: DocumentLoaderFactoryOptions) => DocumentLoader;
+/**
+* Gets a {@link RemoteDocument} from the given response.
+* @param url The URL of the document to load.
+* @param response The response to get the document from.
+* @param fetch The function to fetch the document.
+* @returns The loaded remote document.
+* @throws {FetchError} If the response is not OK.
+* @internal
+*/
+declare function getRemoteDocument(url: string, response: Response, fetch: (url: string, options?: DocumentLoaderOptions) => Promise<RemoteDocument>): Promise<RemoteDocument>;
+/**
+* Options for {@link getDocumentLoader}.
+* @since 1.3.0
+*/
+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.skipPreloadedContexts` 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
+*/
+declare function getDocumentLoader({
+  allowPrivateAddress,
+  maxRedirection,
+  skipPreloadedContexts,
+  userAgent
+}?: GetDocumentLoaderOptions): DocumentLoader;
+//#endregion
+//#region src/key.d.ts
+/**
 * Imports a PEM-SPKI formatted public key.
 * @param pem The PEM-SPKI formatted public key.
 * @returns The imported public key.
@@ -62,34 +237,6 @@ declare function importPkcs1(pem: string): Promise<CryptoKey>;
 */
 declare function importPem(pem: string): Promise<CryptoKey>;
 /**
-* Imports an Ed25519 `did:key` DID.
-*
-* @param did The `did:key` DID.
-* @returns The imported Ed25519 public key.
-* @throws {TypeError} If the DID is malformed or uses an unsupported key type.
-* @since 2.4.0
-*/
-declare function importDidKey(did: string | URL): Promise<CryptoKey>;
-/**
-* Exports an Ed25519 public key as a `did:key` DID.
-*
-* @param key The Ed25519 public key.
-* @returns The `did:key` DID.
-* @throws {TypeError} If the key is invalid or unsupported.
-* @since 2.4.0
-*/
-declare function exportDidKey(key: CryptoKey): Promise<string>;
-/**
-* Parses an Ed25519 `did:key` verification method DID URL.
-*
-* @param didUrl The `did:key` DID URL.
-* @returns The parsed verification method.
-* @throws {TypeError} If the DID URL is malformed, unsupported, or its
-*                     fragment does not identify the same key as the DID.
-* @since 2.4.0
-*/
-declare function parseDidKeyVerificationMethod(didUrl: string | URL): Promise<DidKeyVerificationMethod>;
-/**
 * Imports a [Multibase]-encoded public key.
 *
 * [Multibase]: https://www.w3.org/TR/vc-data-integrity/#multibase-0
@@ -314,22 +461,6 @@ declare class UrlError extends Error {
   constructor(message: string);
 }
 /**
-* Parses a JSON-LD `@id` value as an IRI.
-*/
-declare function parseJsonLdId(id: string | undefined, base?: string | URL): URL | undefined;
-/**
-* Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
-*/
-declare function parseIri(iri: string | URL, base?: string | URL): URL;
-/**
-* Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
-*/
-declare function formatIri(iri: string | URL): string;
-/**
-* Checks whether two IRIs have the same origin.
-*/
-declare function haveSameIriOrigin(left: URL, right: URL): boolean;
-/**
 * Validates a URL to prevent SSRF attacks.
 */
 declare function validatePublicUrl(url: string): Promise<void>;
@@ -337,4 +468,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
 declare function isValidPublicIPv6Address(address: string): boolean;
 declare function expandIPv6Address(address: string): string;
 //#endregion
-export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, canParseDecimal, createActivityPubRequest, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, getDocumentLoader, getRemoteDocument, getUserAgent, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseIri, parseJsonLdId, preloadedContexts, validatePublicUrl };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, canParseDecimal, createActivityPubRequest, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportMultibaseKey, exportSpki, getDocumentLoader, getRemoteDocument, getUserAgent, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, preloadedContexts, validatePublicUrl };