@fedify/fedify@1.3.0-dev.492+450a6939

Built and signed on GitHub Actions

Built and signed on GitHub Actions

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248
import type { NodeInfo } from "../nodeinfo/types.ts";
import type { Actor } from "../vocab/actor.ts";
import type { Activity, CryptographicKey } from "../vocab/mod.ts";
import type { Object } from "../vocab/vocab.ts";
import type { PageItems } from "./collection.ts";
import type { Context, InboxContext, RequestContext } from "./context.ts";
import type { SenderKeyPair } from "./send.ts";

/**
 * A callback that dispatches a {@link NodeInfo} object.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 */
export type NodeInfoDispatcher<TContextData> = (
  context: RequestContext<TContextData>,
) => NodeInfo | Promise<NodeInfo>;

/**
 * A callback that dispatches an {@link Actor} object.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @param context The request context.
 * @param identifier The actor's internal identifier or username.
 */
export type ActorDispatcher<TContextData> = (
  context: RequestContext<TContextData>,
  identifier: string,
) => Actor | null | Promise<Actor | null>;

/**
 * A callback that dispatches key pairs for an actor.
 *
 * @typeParam 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
 */
export 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.
 * @typeParam 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
 */
export type ActorHandleMapper<TContextData> = (
  context: Context<TContextData>,
  username: string,
) => string | null | Promise<string | null>;

/**
 * A callback that dispatches an object.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @typeParam TObject The type of object to dispatch.
 * @typeParam TParam The parameter names of the requested URL.
 * @since 0.7.0
 */
export type ObjectDispatcher<
  TContextData,
  TObject extends Object,
  TParam extends string,
> = (
  context: RequestContext<TContextData>,
  values: Record<TParam, string>,
) => TObject | null | Promise<TObject | null>;

/**
 * A callback that dispatches a collection.
 *
 * @typeParam TItem The type of items in the collection.
 * @typeParam TContext The type of the context. {@link Context} or
 *                     {@link RequestContext}.
 * @typeParam TContextData The context data to pass to the `TContext`.
 * @typeParam 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.
 */
export 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.
 *
 * @typeParam 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.
 */
export 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.
 *
 * @typeParam TContext The type of the context. {@link Context} or
 *                     {@link RequestContext}.
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @typeParam 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.
 */
export 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.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @typeParam TActivity The type of activity to listen for.
 * @param context The inbox context.
 * @param activity The activity that was received.
 */
export type InboxListener<TContextData, TActivity extends Activity> = (
  context: InboxContext<TContextData>,
  activity: TActivity,
) => void | Promise<void>;

/**
 * A callback that handles errors in an inbox.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @param context The inbox context.
 */
export type InboxErrorHandler<TContextData> = (
  context: Context<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.
 *
 * @typeParam 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
 */
export type SharedInboxKeyDispatcher<TContextData> = (
  context: Context<TContextData>,
) =>
  | SenderKeyPair
  | { identifier: string }
  | { username: string }
  | { handle: string }
  | null
  | Promise<
    | SenderKeyPair
    | { identifier: string }
    | { username: string }
    | { handle: string }
    | null
  >;

/**
 * A callback that handles errors during outbox processing.
 *
 * @param error The error that occurred.
 * @param activity The activity that caused the error.  If it is `null`, the
 *                 error occurred during deserializing the activity.
 * @since 0.6.0
 */
export type OutboxErrorHandler = (
  error: Error,
  activity: Activity | null,
) => void | Promise<void>;

/**
 * A callback that determines if a request is authorized or not.
 *
 * @typeParam 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.
 * @param signedKey The key that was used to sign the request, or `null` if
 *                  the request was not signed or the signature was invalid.
 * @param signedKeyOwner The actor that owns the key that was used to sign the
 *                       request, or `null` if the request was not signed or the
 *                       signature was invalid, or if the key is not associated
 *                       with an actor.
 * @returns `true` if the request is authorized, `false` otherwise.
 * @since 0.7.0
 */
export type AuthorizePredicate<TContextData> = (
  context: RequestContext<TContextData>,
  identifier: string,
  signedKey: CryptographicKey | null,
  signedKeyOwner: Actor | null,
) => boolean | Promise<boolean>;

/**
 * A callback that determines if a request is authorized or not.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @typeParam TParam The parameter names of the requested URL.
 * @param context The request context.
 * @param values The parameters of the requested URL.
 * @param signedKey The key that was used to sign the request, or `null` if
 *                  the request was not signed or the signature was invalid.
 * @param signedKeyOwner The actor that owns the key that was used to sign the
 *                       request, or `null` if the request was not signed or the
 *                       signature was invalid, or if the key is not associated
 *                       with an actor.
 * @returns `true` if the request is authorized, `false` otherwise.
 * @since 0.7.0
 */
export type ObjectAuthorizePredicate<TContextData, TParam extends string> = (
  context: RequestContext<TContextData>,
  values: Record<TParam, string>,
  signedKey: CryptographicKey | null,
  signedKeyOwner: Actor | null,
) => boolean | Promise<boolean>;