@fedify/fedify/dist/testing/mod.d.mts

An ActivityPub server framework

import { Temporal } from "@js-temporal/polyfill";
import { URLPattern } from "urlpattern-polyfill";
import { testDefinitions } from "@fedify/fixture";
import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fedify/webfinger";
import { TracerProvider } from "@opentelemetry/api";
import { DocumentLoader, GetUserAgentOptions } from "@fedify/vocab-runtime";

//#region src/nodeinfo/types.d.ts
/**
 * The type of the result of parsing JSON.
 */
type JsonValue = {
  [key: string]: JsonValue | undefined;
} | JsonValue[] | string | number | boolean | null;
/**
 * A NodeInfo object as defined in the NodeInfo 2.1 schema.
 */
interface NodeInfo {
  /**
   * Metadata about server software in use.
   */
  readonly software: Software;
  /**
   * The protocols supported on this server.  At least one protocol must be
   * supported.
   */
  readonly protocols: readonly Protocol[];
  /**
   * The third party sites this server can connect to via their application API.
   */
  readonly services?: Services;
  /**
   * Whether this server allows open self-registration.  Defaults to `false`.
   */
  readonly openRegistrations?: boolean;
  /**
   * Usage statistics for this server.
   */
  readonly usage: Usage;
  /**
   * Free form key value pairs for software specific values.
   * Clients should not rely on any specific key present.
   */
  readonly metadata?: Readonly<Record<string, JsonValue>>;
}
/**
 * Metadata about server software in use.
 */
interface Software {
  /**
   * The canonical name of this server software.  This must comply with
   * pattern `/^[a-z0-9-]+$/`.
   */
  readonly name: string;
  /**
   * The version of this server software.
   */
  readonly version: string;
  /**
   * The URL of the source code repository of this server software.
   */
  readonly repository?: URL;
  /**
   * The URL of the homepage of this server software.
   */
  readonly homepage?: URL;
}
/**
 * The protocols supported on this server.
 */
type Protocol = "activitypub" | "buddycloud" | "dfrn" | "diaspora" | "libertree" | "ostatus" | "pumpio" | "tent" | "xmpp" | "zot";
/**
 * The third party sites this server can connect to via their application API.
 */
interface Services {
  /**
   * The third party sites this server can retrieve messages from for combined
   * display with regular traffic.
   */
  readonly inbound?: readonly InboundService[];
  /**
   * The third party sites this server can publish messages to on the behalf
   * of a user.
   */
  readonly outbound?: readonly OutboundService[];
}
/**
 * The third party sites this server can retrieve messages from for combined
 * display with regular traffic.
 */
type InboundService = "atom1.0" | "gnusocial" | "imap" | "pnut" | "pop3" | "pumpio" | "rss2.0" | "twitter";
/**
 * The third party sites this server can publish messages to on the behalf
 * of a user.
 */
type OutboundService = "atom1.0" | "blogger" | "buddycloud" | "diaspora" | "dreamwidth" | "drupal" | "facebook" | "friendica" | "gnusocial" | "google" | "insanejournal" | "libertree" | "linkedin" | "livejournal" | "mediagoblin" | "myspace" | "pinterest" | "pnut" | "posterous" | "pumpio" | "redmatrix" | "rss2.0" | "smtp" | "tent" | "tumblr" | "twitter" | "wordpress" | "xmpp";
/**
 * Usage statistics for this server.
 */
interface Usage {
  /**
   * Statistics about the users of this server.
   */
  readonly users: {
    /**
     * The total amount of on this server registered users.  This number
     * has to be an integer greater than or equal to zero.
     */
    readonly total?: number;
    /**
     * The amount of users that signed in at least once in the last 180 days.
     * This number has to be an integer greater than or equal to zero.
     */
    readonly activeHalfyear?: number;
    /**
     * The amount of users that signed in at least once in the last 30 days.
     * This number has to be an integer greater than or equal to zero.
     */
    readonly activeMonth?: number;
  };
  /**
   * The amount of posts that were made by users that are registered on this
   * server.  This number has to be an integer greater than or equal to zero.
   */
  readonly localPosts: number;
  /**
   * The amount of comments that were made by users that are registered on this
   * server.  This number has to be an integer greater than or equal to zero.
   */
  readonly localComments: number;
}
//#endregion
//#region src/nodeinfo/client.d.ts
/**
 * Options for {@link getNodeInfo} function.
 * @since 1.2.0
 */
interface GetNodeInfoOptions {
  /**
   * Whether to directly fetch the NodeInfo document from the given URL.
   * Otherwise, the NodeInfo document will be fetched from the `.well-known`
   * location of the given URL.
   *
   * Turned off by default.
   */
  direct?: boolean;
  /**
   * How strictly to parse the NodeInfo document.
   *
   *  -  `"strict"`: Parse the NodeInfo document strictly.  If the document is
   *     invalid, `undefined` is returned.  This is the default.
   *  -  `"best-effort"`: Try to parse the NodeInfo document even if it is
   *     invalid.
   *  -  `"none"`: Do not parse the NodeInfo document.  The function will return
   *     the raw JSON value.
   */
  parse?: "strict" | "best-effort" | "none";
  /**
   * The options for making `User-Agent` header.
   * 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} to generate
   * the `User-Agent` header value.
   * @since 1.3.0
   */
  userAgent?: GetUserAgentOptions | string;
}
//#endregion
//#region src/sig/key.d.ts
/**
 * Detailed fetch failure information from {@link fetchKeyDetailed}.
 * @since 2.1.0
 */
type FetchKeyErrorResult = {
  readonly status: number;
  readonly response: Response;
} | {
  readonly error: Error;
};
//#endregion
//#region src/sig/owner.d.ts
/**
 * Options for {@link getKeyOwner}.
 * @since 0.8.0
 */
interface GetKeyOwnerOptions {
  /**
   * The document loader to use for fetching the key and its owner.
   */
  documentLoader?: DocumentLoader;
  /**
   * The context loader to use for JSON-LD context retrieval.
   */
  contextLoader?: DocumentLoader;
  /**
   * The OpenTelemetry tracer provider to use for tracing.  If omitted,
   * the global tracer provider is used.
   * @since 1.3.0
   */
  tracerProvider?: TracerProvider;
}
//#endregion
//#region src/sig/http.d.ts
/**
 * The reason why {@link verifyRequestDetailed} could not verify a request.
 * @since 2.1.0
 */
type VerifyRequestFailureReason = {
  readonly type: "keyFetchError";
  readonly keyId: URL;
  readonly result: FetchKeyErrorResult;
} | {
  readonly type: "invalidSignature";
  readonly keyId?: URL;
} | {
  readonly type: "noSignature";
};
//#endregion
//#region src/federation/collection.d.ts
/**
 * A page of items.
 */
interface PageItems<TItem> {
  readonly prevCursor?: string | null;
  readonly nextCursor?: string | null;
  readonly items: readonly TItem[];
}
//#endregion
//#region src/federation/send.d.ts
/**
 * A key pair for an actor who sends an activity.
 * @since 0.10.0
 */
interface SenderKeyPair {
  /**
   * The actor's private key to sign the request.
   */
  readonly privateKey: CryptoKey;
  /**
   * The public key ID that corresponds to the private key.
   */
  readonly keyId: URL;
}
/**
 * An error that is thrown when an activity fails to send to a remote inbox.
 * It contains structured information about the failure, including the HTTP
 * status code, the inbox URL, and the response body.
 * @since 2.0.0
 */
declare class SendActivityError extends Error {
  /**
   * The inbox URL that the activity was being sent to.
   */
  readonly inbox: URL;
  /**
   * The HTTP status code returned by the inbox.
   */
  readonly statusCode: number;
  /**
   * The response body from the inbox, if any.  Note that this may be
   * truncated to a maximum of 1 KiB to prevent excessive memory consumption
   * when remote servers return large error pages (e.g., Cloudflare error pages).
   * If truncated, the string will end with `"… (truncated)"`.
   */
  readonly responseBody: string;
  /**
   * Creates a new {@link SendActivityError}.
   * @param inbox The inbox URL.
   * @param statusCode The HTTP status code.
   * @param message The error message.
   * @param responseBody The response body.
   */
  constructor(inbox: URL, statusCode: number, message: string, responseBody: string);
}
//#endregion
//#region src/federation/callback.d.ts
/**
 * A callback that dispatches a {@link NodeInfo} object.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 */
type NodeInfoDispatcher<TContextData> = (context: RequestContext<TContextData>) => NodeInfo | Promise<NodeInfo>;
/**
 * A callback that dispatches a array of {@link Link}.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param resource The URL queried via WebFinger.
 * @returns Links related to the queried resource.
 */
type WebFingerLinksDispatcher<TContextData> = (context: RequestContext<TContextData>, resource: URL) => readonly Link$1[] | Promise<readonly Link$1[]>;
/**
 * A callback that dispatches an {@link Actor} object or a {@link Tombstone}.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The request context.
 * @param identifier The actor's internal identifier or username.
 */
type ActorDispatcher<TContextData> = (context: RequestContext<TContextData>, identifier: string) => Actor | Tombstone | null | Promise<Actor | Tombstone | null>;
/**
 * A callback that dispatches key pairs for an actor.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The context.
 * @param identifier The actor's internal identifier or username.
 * @returns The key pairs.
 * @since 0.10.0
 */
type ActorKeyPairsDispatcher<TContextData> = (context: Context<TContextData>, identifier: string) => CryptoKeyPair[] | Promise<CryptoKeyPair[]>;
/**
 * A callback that maps a WebFinger username to the corresponding actor's
 * internal identifier, or `null` if the username is not found.
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The context.
 * @param username The WebFinger username.
 * @returns The actor's internal identifier, or `null` if the username is not
 *          found.
 * @since 0.15.0
 */
type ActorHandleMapper<TContextData> = (context: Context<TContextData>, username: string) => string | null | Promise<string | null>;
/**
 * A callback that maps a WebFinger query to the corresponding actor's
 * internal identifier or username, or `null` if the query is not found.
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The request context.
 * @param resource The URL that was queried through WebFinger.
 * @returns The actor's internal identifier or username, or `null` if the query
 *          is not found.
 * @since 1.4.0
 */
type ActorAliasMapper<TContextData> = (context: RequestContext<TContextData>, resource: URL) => {
  identifier: string;
} | {
  username: string;
} | null | Promise<{
  identifier: string;
} | {
  username: string;
} | null>;
/**
 * A callback that dispatches an object.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @template TObject The type of object to dispatch.
 * @template TParam The parameter names of the requested URL.
 * @since 0.7.0
 */
type ObjectDispatcher<TContextData, TObject extends Object$1, TParam extends string> = (context: RequestContext<TContextData>, values: Record<TParam, string>) => TObject | null | Promise<TObject | null>;
/**
 * A callback that dispatches a collection.
 *
 * @template TItem The type of items in the collection.
 * @template TContext The type of the context. {@link Context} or
 *                     {@link RequestContext}.
 * @template TContextData The context data to pass to the `TContext`.
 * @template TFilter The type of the filter, if any.
 * @param context The context.
 * @param identifier The internal identifier or the username of the collection
 *                   owner.
 * @param cursor The cursor to start the collection from, or `null` to dispatch
 *               the entire collection without pagination.
 * @param filter The filter to apply to the collection, if any.
 */
type CollectionDispatcher<TItem, TContext extends Context<TContextData>, TContextData, TFilter> = (context: TContext, identifier: string, cursor: string | null, filter?: TFilter) => PageItems<TItem> | null | Promise<PageItems<TItem> | null>;
/**
 * A callback that counts the number of items in a collection.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The context.
 * @param identifier The internal identifier or the username of the collection
 *                   owner.
 * @param filter The filter to apply to the collection, if any.
 */
type CollectionCounter<TContextData, TFilter> = (context: RequestContext<TContextData>, identifier: string, filter?: TFilter) => number | bigint | null | Promise<number | bigint | null>;
/**
 * A callback that returns a cursor for a collection.
 *
 * @template TContext The type of the context. {@link Context} or
 *                     {@link RequestContext}.
 * @template TContextData The context data to pass to the {@link Context}.
 * @template TFilter The type of the filter, if any.
 * @param context The context.
 * @param identifier The internal identifier or the username of the collection
 *                   owner.
 * @param filter The filter to apply to the collection, if any.
 */
type CollectionCursor<TContext extends Context<TContextData>, TContextData, TFilter> = (context: TContext, identifier: string, filter?: TFilter) => string | null | Promise<string | null>;
/**
 * A callback that listens for activities in an inbox.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @template TActivity The type of activity to listen for.
 * @param context The inbox context.
 * @param activity The activity that was received.
 */
type InboxListener<TContextData, TActivity extends Activity> = (context: InboxContext<TContextData>, activity: TActivity) => void | Promise<void>;
/**
 * A callback that listens for activities in an outbox.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @template TActivity The type of activity to listen for.
 * @param context The outbox context.
 * @param activity The activity that was received.
 * @since 2.2.0
 */
type OutboxListener<TContextData, TActivity extends Activity> = (context: OutboxContext<TContextData>, activity: TActivity) => void | Promise<void>;
/**
 * The reason why an incoming activity could not be verified.
 *
 * Unlike inbox listeners registered through {@link InboxListenerSetters.on},
 * unverified activity handlers are called only when the activity payload could
 * be parsed but its HTTP signatures could not be verified.
 *
 * @since 2.1.0
 */
type UnverifiedActivityReason = VerifyRequestFailureReason;
/**
 * A callback that handles activities whose signatures could not be verified.
 *
 * Returning a {@link Response} overrides Fedify's default `401 Unauthorized`
 * response.  Returning `void` keeps the default behavior.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The request context.
 * @param activity The incoming activity that could be parsed.
 * @param reason The reason why signature verification failed.
 * @since 2.1.0
 */
type UnverifiedActivityHandler<TContextData> = (context: RequestContext<TContextData>, activity: Activity, reason: UnverifiedActivityReason) => void | Response | Promise<void | Response>;
/**
 * A callback that handles errors in an inbox.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The inbox context.
 */
type InboxErrorHandler<TContextData> = (context: Context<TContextData>, error: Error) => void | Promise<void>;
/**
 * A callback that handles errors in an outbox listener.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The outbox context.
 * @param error The error that occurred.
 * @since 2.2.0
 */
type OutboxListenerErrorHandler<TContextData> = (context: OutboxContext<TContextData>, error: Error) => void | Promise<void>;
/**
 * A callback that dispatches the key pair for the authenticated document loader
 * of the {@link Context} passed to the shared inbox listener.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The context.
 * @returns The username or the internal identifier of the actor or the key pair
 *          for the authenticated document loader of the {@link Context} passed
 *          to the shared inbox listener.  If `null` is returned, the request is
 *          not authorized.
 * @since 0.11.0
 */
type SharedInboxKeyDispatcher<TContextData> = (context: Context<TContextData>) => SenderKeyPair | {
  identifier: string;
} | {
  username: string;
} | null | Promise<SenderKeyPair | {
  identifier: string;
} | {
  username: string;
} | null>;
/**
 * A callback that handles permanent delivery failures when sending activities
 * to remote inboxes.
 *
 * This handler is called when an inbox returns an HTTP status code that
 * indicates permanent failure (such as `410 Gone` or `404 Not Found`),
 * allowing the application to clean up followers that are no longer reachable.
 *
 * Unlike {@link OutboxErrorHandler}, which is called for every delivery failure
 * (including retries), this handler is called only once for permanent failures,
 * after which delivery is not retried.
 *
 * If any errors are thrown in this callback, they are caught, logged,
 * and ignored.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The context.
 * @param values The delivery failure information.
 * @since 2.0.0
 */
type OutboxPermanentFailureHandler<TContextData> = (context: Context<TContextData>, values: {
  /** The inbox URL that failed. */readonly inbox: URL; /** The activity that failed to deliver. */
  readonly activity: Activity; /** The error that occurred. */
  readonly error: SendActivityError; /** The HTTP status code returned by the inbox. */
  readonly statusCode: number;
  /**
   * The actor IDs that were supposed to receive the activity at this inbox.
   */
  readonly actorIds: readonly URL[];
}) => void | Promise<void>;
/**
 * A callback that determines if a request is authorized or not.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The request context.
 * @param identifier The internal identifier of the actor that is being
 *                   requested.
 * @returns `true` if the request is authorized, `false` otherwise.
 * @since 0.7.0
 */
type AuthorizePredicate<TContextData> = (context: RequestContext<TContextData>, identifier: string) => boolean | Promise<boolean>;
/**
 * A callback that determines if a request is authorized or not.
 *
 * @template TContextData The context data to pass to the {@link Context}.
 * @template TParam The parameter names of the requested URL.
 * @param context The request context.
 * @param values The parameters of the requested URL.
 * @returns `true` if the request is authorized, `false` otherwise.
 * @since 0.7.0
 */
type ObjectAuthorizePredicate<TContextData, TParam extends string> = (context: RequestContext<TContextData>, values: Record<TParam, string>) => boolean | Promise<boolean>;
/**
 * A callback that dispatches a custom collection.
 *
 * @template TItem The type of items in the collection.
 * @template TParams The parameter names of the requested URL.
 * @template TContext The type of the context. {@link Context} or
 *                     {@link RequestContext}.
 * @template TContextData The context data to pass to the `TContext`.
 * @template TFilter The type of the filter, if any.
 * @param context The context.
 * @param values The parameters of the requested URL.
 * @param cursor The cursor to start the collection from, or `null` to dispatch
 *               the entire collection without pagination.
 * @since 1.8.0
 */
type CustomCollectionDispatcher<TItem, TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>, cursor: string | null) => PageItems<TItem> | null | Promise<PageItems<TItem> | null>;
/**
 * A callback that counts the number of items in a custom collection.
 *
 * @template TParams The parameter names of the requested URL.
 * @template TContextData The context data to pass to the {@link Context}.
 * @param context The context.
 * @param values The parameters of the requested URL.
 * @since 1.8.0
 */
type CustomCollectionCounter<TParam extends string, TContextData> = (context: RequestContext<TContextData>, values: Record<TParam, string>) => number | bigint | null | Promise<number | bigint | null>;
/**
 * A callback that returns a cursor for a custom collection.
 *
 * @template TParams The parameter names of the requested URL.
 * @template TContext The type of the context. {@link Context} or
 *                     {@link RequestContext}.
 * @template TContextData The context data to pass to the {@link Context}.
 * @template TFilter The type of the filter, if any.
 * @param context The context.
 * @param values The parameters of the requested URL.
 * @since 1.8.0
 */
type CustomCollectionCursor<TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>) => string | null | Promise<string | null>;
//#endregion
//#region src/federation/queue.d.ts
interface SenderKeyJwkPair {
  readonly keyId: string;
  readonly privateKey: JsonWebKey;
}
/**
 * A message that represents a task to be processed by the background worker.
 * The concrete type of the message depends on the `type` property.
 *
 * Please do not depend on the concrete types of the messages, as they may
 * change in the future.  You should treat the `Message` type as an opaque
 * type.
 * @since 1.6.0
 */
type Message = FanoutMessage | OutboxMessage | InboxMessage;
interface FanoutMessage {
  readonly type: "fanout";
  readonly id: ReturnType<typeof crypto.randomUUID>;
  readonly baseUrl: string;
  readonly keys: readonly SenderKeyJwkPair[];
  readonly inboxes: Readonly<Record<string, {
    readonly actorIds: readonly string[];
    readonly sharedInbox: boolean;
  }>>;
  readonly activity: unknown;
  readonly activityId?: string;
  readonly activityType: string;
  readonly collectionSync?: string;
  readonly orderingKey?: string;
  /**
   * Whether to apply outgoing JSON-LD wire-format normalization to queued
   * activities that already carry Object Integrity Proofs.
   *
   * `true` is used for proofs Fedify created before fanout, or when callers
   * explicitly request normalization for locally pre-signed activities.
   * `false`/`undefined` preserves existing proofs as-is.
   */
  readonly normalizeExistingProofs?: boolean;
  readonly traceContext: Readonly<Record<string, string>>;
}
interface OutboxMessage {
  readonly type: "outbox";
  readonly id: ReturnType<typeof crypto.randomUUID>;
  readonly baseUrl: string;
  readonly keys: readonly SenderKeyJwkPair[];
  readonly activity: unknown;
  readonly activityId?: string;
  readonly activityType: string;
  readonly inbox: string;
  readonly sharedInbox: boolean;
  readonly actorIds?: readonly string[];
  readonly started: string;
  readonly attempt: number;
  readonly headers: Readonly<Record<string, string>>;
  readonly orderingKey?: string;
  readonly traceContext: Readonly<Record<string, string>>;
}
interface InboxMessage {
  readonly type: "inbox";
  readonly id: ReturnType<typeof crypto.randomUUID>;
  readonly baseUrl: string;
  readonly activity: unknown;
  /**
   * The normalized JSON-LD representation of a signed inbox activity that
   * Fedify already compacted successfully while accepting the request.  Queue
   * workers can reuse this producer-side parse cache under stricter loader or
   * network constraints without changing the raw payload preserved for
   * forwarding.
   *
   * This may exist even when {@link ldSignatureVerified} is `false`, because
   * fallback-authenticated traffic and already-queued backlog items can still
   * depend on the cached normalized form to avoid re-fetching remote custom
   * contexts during worker processing.
   *
   * This is optional for backward compatibility with messages that were
   * queued by older Fedify versions or that were already in a queue before
   * upgrading.
   *
   * Fedify keeps this on the queued message itself instead of an external
   * sidecar because generic queue backends do not provide reliable lifecycle
   * guarantees for auxiliary storage across retries and redeliveries.
   *
   * @internal
   */
  readonly normalizedActivity?: unknown;
  /**
   * Whether the producer actually verified the Linked Data Signature before
   * queueing this message.  This lets workers distinguish verified LDS replay
   * from other authenticated inbox traffic that merely happened to include a
   * signature block.  This provenance marker is separate from the optional
   * normalizedActivity parse cache.
   *
   * `undefined` preserves backward compatibility with older queued messages
   * that predate this marker.
   *
   * @internal
   */
  readonly ldSignatureVerified?: boolean;
  readonly started: string;
  readonly attempt: number;
  readonly identifier: string | null;
  readonly traceContext: Readonly<Record<string, string>>;
}
//#endregion
//#region src/federation/federation.d.ts
/**
 * Options for {@link Federation.startQueue} method.
 * @since 1.0.0
 */
interface FederationStartQueueOptions {
  /**
   * The signal to abort the task queue.
   */
  signal?: AbortSignal;
  /**
   * Starts the task worker only for the specified queue.  If unspecified,
   * which is the default, the task worker starts for all three queues:
   * inbox, outbox, and fanout.
   * @since 1.3.0
   */
  queue?: "inbox" | "outbox" | "fanout";
}
/**
 * A common interface between {@link Federation} and {@link FederationBuilder}.
 * @template TContextData The context data to pass to the {@link Context}.
 * @since 1.6.0
 */
interface Federatable<TContextData> {
  /**
   * Registers a NodeInfo dispatcher.
   * @param path The URI path pattern for the NodeInfo dispatcher.  The syntax
   *             is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have no variables.
   * @param dispatcher A NodeInfo dispatcher callback to register.
   * @throws {RouterError} Thrown if the path pattern is invalid.
   */
  setNodeInfoDispatcher(path: string, dispatcher: NodeInfoDispatcher<TContextData>): void;
  /**
   * Registers a links dispatcher to WebFinger
   * @param dispatcher A links dispatcher callback to register.
   */
  setWebFingerLinksDispatcher(dispatcher: WebFingerLinksDispatcher<TContextData>): void;
  /**
   * Registers an actor dispatcher.
   *
   * @example
   * ``` typescript
   * federation.setActorDispatcher(
   *   "/users/{identifier}",
   *   async (ctx, identifier) => {
   *     return new Person({
   *       id: ctx.getActorUri(identifier),
   *       // ...
   *     });
   *   }
   * );
   * ```
   *
   * @param path The URI path pattern for the actor dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher An actor dispatcher callback to register.  It may return
   *                   an actor, a `Tombstone`, or `null` if the actor is not
   *                   found.
   * @returns An object with methods to set other actor dispatcher callbacks.
   * @throws {RouterError} Thrown if the path pattern is invalid.
   */
  setActorDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: ActorDispatcher<TContextData>): ActorCallbackSetters<TContextData>;
  /**
   * Registers an object dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of object to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param cls The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the object dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one or more variables.
   * @param dispatcher An object dispatcher callback to register.
   */
  setObjectDispatcher<TObject extends Object$1, TParam extends string>(cls: ConstructorWithTypeId<TObject>, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
  /**
   * Registers an object dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of object to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param cls The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the object dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one or more variables.
   * @param dispatcher An object dispatcher callback to register.
   */
  setObjectDispatcher<TObject extends Object$1, TParam extends string>(cls: ConstructorWithTypeId<TObject>, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
  /**
   * Registers an object dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of object to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param cls The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the object dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one or more variables.
   * @param dispatcher An object dispatcher callback to register.
   */
  setObjectDispatcher<TObject extends Object$1, TParam extends string>(cls: ConstructorWithTypeId<TObject>, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
  /**
   * Registers an object dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of object to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param cls The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the object dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one or more variables.
   * @param dispatcher An object dispatcher callback to register.
   */
  setObjectDispatcher<TObject extends Object$1, TParam extends string>(cls: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
  /**
   * Registers an object dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of object to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param cls The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the object dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one or more variables.
   * @param dispatcher An object dispatcher callback to register.
   */
  setObjectDispatcher<TObject extends Object$1, TParam extends string>(cls: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
  /**
   * Registers an object dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of object to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param cls The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the object dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one or more variables.
   * @param dispatcher An object dispatcher callback to register.
   */
  setObjectDispatcher<TObject extends Object$1, TParam extends string>(cls: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
  /**
   * Registers an inbox dispatcher.
   *
   * @param path The URI path pattern for the inbox dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`, and must match
   *             the inbox listener path.
   * @param dispatcher An inbox dispatcher callback to register.
   * @throws {@link RouterError} Thrown if the path pattern is invalid.
   */
  setInboxDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Activity, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
  /**
   * Registers an outbox dispatcher.
   *
   * @example
   * ``` typescript
   * federation.setOutboxDispatcher(
   *   "/users/{identifier}/outbox",
   *   async (ctx, identifier, options) => {
   *     let items: Activity[];
   *     let nextCursor: string;
   *     // ...
   *     return { items, nextCursor };
   *   }
   * );
   * ```
   *
   * @param path The URI path pattern for the outbox dispatcher.  The syntax is
   *             based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher An outbox dispatcher callback to register.
   * @throws {@link RouterError} Thrown if the path pattern is invalid.
   */
  setOutboxDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Activity, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
  /**
   * Assigns the URL path for the outbox and starts setting outbox listeners.
   *
   * @example
   * ``` typescript
   * federation
   *   .setOutboxListeners("/users/{identifier}/outbox")
   *   .on(Activity, async (ctx, activity) => {
   *     await ctx.sendActivity({ identifier: ctx.identifier }, "followers", activity);
   *   })
   *   .authorize(async (ctx, identifier) => {
   *     return ctx.request.headers.get("authorization") === `Bearer ${identifier}`;
   *   });
   * ```
   *
   * @param outboxPath The URI path pattern for the outbox.  The syntax is based
   *                   on URI Template
   *                   ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The
   *                   path must have one variable: `{identifier}`.  If an
   *                   outbox dispatcher is configured, this path must match
   *                   the outbox dispatcher path.
   * @returns An object to register outbox listeners.
   * @throws {RouterError} Thrown if the path pattern is invalid.
   * @since 2.2.0
   */
  setOutboxListeners(outboxPath: `${string}${Rfc6570Expression<"identifier">}${string}`): OutboxListenerSetters<TContextData>;
  /**
   * Registers a following collection dispatcher.
   * @param path The URI path pattern for the following collection.  The syntax
   *             is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher A following collection callback to register.
   * @returns An object with methods to set other following collection
   *          callbacks.
   * @throws {RouterError} Thrown if the path pattern is invalid.
   */
  setFollowingDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Actor | URL, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
  /**
   * Registers a followers collection dispatcher.
   * @param path The URI path pattern for the followers collection.  The syntax
   *             is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher A followers collection callback to register.
   * @returns An object with methods to set other followers collection
   *          callbacks.
   * @throws {@link RouterError} Thrown if the path pattern is invalid.
   */
  setFollowersDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Recipient, Context<TContextData>, TContextData, URL>): CollectionCallbackSetters<Context<TContextData>, TContextData, URL>;
  /**
   * Registers a liked collection dispatcher.
   * @param path The URI path pattern for the liked collection.  The syntax
   *             is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher A liked collection callback to register.
   * @returns An object with methods to set other liked collection
   *          callbacks.
   * @throws {@link RouterError} Thrown if the path pattern is invalid.
   */
  setLikedDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Object$1 | URL, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
  /**
   * Registers a featured collection dispatcher.
   * @param path The URI path pattern for the featured collection.  The syntax
   *             is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher A featured collection callback to register.
   * @returns An object with methods to set other featured collection
   *          callbacks.
   * @throws {@link RouterError} Thrown if the path pattern is invalid.
   */
  setFeaturedDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Object$1, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
  /**
   * Registers a featured tags collection dispatcher.
   * @param path The URI path pattern for the featured tags collection.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
   *             must have one variable: `{identifier}`.
   * @param dispatcher A featured tags collection callback to register.
   * @returns An object with methods to set other featured tags collection
   *          callbacks.
   * @throws {@link RouterError} Thrown if the path pattern is invalid.
   */
  setFeaturedTagsDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher<Hashtag, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
  /**
   * Assigns the URL path for the inbox and starts setting inbox listeners.
   *
   * @example
   * ``` typescript
   * federation
   *   .setInboxListeners("/users/{identifier}/inbox", "/inbox")
   *   .on(Follow, async (ctx, follow) => {
   *     const from = await follow.getActor(ctx);
   *     if (!isActor(from)) return;
   *     // ...
   *   })
   *   .on(Undo, async (ctx, undo) => {
   *     // ...
   *   });
   * ```
   *
   * @param inboxPath The URI path pattern for the inbox.  The syntax is based
   *                  on URI Template
   *                  ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *                  The path must have one variable: `{identifier}`, and must
   *                  match the inbox dispatcher path.
   * @param sharedInboxPath An optional URI path pattern for the shared inbox.
   *                        The syntax is based on URI Template
   *                        ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *                        The path must have no variables.
   * @returns An object to register inbox listeners.
   * @throws {RouterError} Thrown if the path pattern is invalid.
   */
  setInboxListeners(inboxPath: `${string}${Rfc6570Expression<"identifier">}${string}`, sharedInboxPath?: string): InboxListenerSetters<TContextData>;
  /**
   * Registers a collection of objects dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of objects to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param name A unique name for the collection dispatcher.
   * @param itemType The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the collection dispatcher.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *             The path must have one or more variables.
   * @param dispatcher A collection dispatcher callback to register.
   */
  setCollectionDispatcher<TObject extends Object$1, TParam extends string>(name: string | symbol, itemType: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: CustomCollectionDispatcher<TObject, TParam, RequestContext<TContextData>, TContextData>): CustomCollectionCallbackSetters<TParam, RequestContext<TContextData>, TContextData>;
  /**
   * Registers a collection of objects dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of objects to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param name A unique name for the collection dispatcher.
   * @param itemType The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the collection dispatcher.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *             The path must have one or more variables.
   * @param dispatcher A collection dispatcher callback to register.
   */
  setCollectionDispatcher<TObject extends Object$1, TParam extends string>(name: string | symbol, itemType: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: CustomCollectionDispatcher<TObject, TParam, RequestContext<TContextData>, TContextData>): CustomCollectionCallbackSetters<TParam, RequestContext<TContextData>, TContextData>;
  /**
   * Registers a collection of objects dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of objects to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param name A unique name for the collection dispatcher.
   * @param itemType The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the collection dispatcher.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *             The path must have one or more variables.
   * @param dispatcher A collection dispatcher callback to register.
   */
  setCollectionDispatcher<TObject extends Object$1, TParam extends string>(name: string | symbol, itemType: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: CustomCollectionDispatcher<TObject, TParam, RequestContext<TContextData>, TContextData>): CustomCollectionCallbackSetters<TParam, RequestContext<TContextData>, TContextData>;
  /**
   * Registers an ordered collection of objects dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of objects to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param name A unique name for the collection dispatcher.
   * @param itemType The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the collection dispatcher.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *             The path must have one or more variables.
   * @param dispatcher A collection dispatcher callback to register.
   */
  setOrderedCollectionDispatcher<TObject extends Object$1, TParam extends string>(name: string | symbol, itemType: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: CustomCollectionDispatcher<TObject, TParam, RequestContext<TContextData>, TContextData>): CustomCollectionCallbackSetters<TParam, RequestContext<TContextData>, TContextData>;
  /**
   * Registers an ordered collection of objects dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of objects to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param name A unique name for the collection dispatcher.
   * @param itemType The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the collection dispatcher.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *             The path must have one or more variables.
   * @param dispatcher A collection dispatcher callback to register.
   */
  setOrderedCollectionDispatcher<TObject extends Object$1, TParam extends string>(name: string | symbol, itemType: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: CustomCollectionDispatcher<TObject, TParam, RequestContext<TContextData>, TContextData>): CustomCollectionCallbackSetters<TParam, RequestContext<TContextData>, TContextData>;
  /**
   * Registers an ordered collection of objects dispatcher.
   *
   * @template TContextData The context data to pass to the {@link Context}.
   * @template TObject The type of objects to dispatch.
   * @template TParam The parameter names of the requested URL.
   * @param name A unique name for the collection dispatcher.
   * @param itemType The Activity Vocabulary class of the object to dispatch.
   * @param path The URI path pattern for the collection dispatcher.
   *             The syntax is based on URI Template
   *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
   *             The path must have one or more variables.
   * @param dispatcher A collection dispatcher callback to register.
   */
  setOrderedCollectionDispatcher<TObject extends Object$1, TParam extends string>(name: string | symbol, itemType: ConstructorWithTypeId<TObject>, path: `${string}${Rfc6570Expression<TParam>}${string}`, dispatcher: CustomCollectionDispatcher<TObject, TParam, RequestContext<TContextData>, TContextData>): CustomCollectionCallbackSetters<TParam, RequestContext<TContextData>, TContextData>;
  /**
   * Registers a handler for permanent delivery failures.
   *
   * This handler is called when an inbox returns an HTTP status code
   * that indicates permanent failure (`410 Gone`, `404 Not Found`, etc.),
   * allowing the application to clean up followers that are no longer
   * reachable.
   *
   * Unlike `onOutboxError`, which is called for every delivery failure
   * (including retries), this handler is called only once for permanent
   * failures, after which delivery is not retried.
   *
   * @param handler A callback to handle permanent failures.
   * @since 2.0.0
   */
  setOutboxPermanentFailureHandler(