@fedify/interaction-controls 2.4.0-dev.0

package/dist/mod.d.ts

@@ -0,0 +1,321 @@
+/// <reference lib="esnext.temporal" />
+import { Accept, Activity, Actor, Announce, AnnounceAuthorization, AnnounceRequest, Article, ChatMessage, Create, Delete, FeatureAuthorization, FeatureRequest, FeaturedCollection, Like, LikeAuthorization, LikeRequest, Note, Object as Object$1, Question, QuoteAuthorization, QuoteRequest, Reject, ReplyAuthorization, ReplyRequest } from "@fedify/vocab";
+import { DocumentLoader } from "@fedify/vocab-runtime";
+import { Context } from "@fedify/fedify";
+import { Temporal } from "temporal-polyfill";
+
+//#region src/types.d.ts
+type InteractionName = "like" | "reply" | "announce" | "quote" | "feature";
+type InteractionPolicyProperty = "canLike" | "canReply" | "canAnnounce" | "canQuote" | "canFeature";
+interface InteractionControl<TRequest extends Activity, TAuthorization extends Object$1, TInteracting extends Object$1, TTarget extends Object$1, TImpoliteSource extends Object$1> {
+  readonly name: InteractionName;
+  readonly policyProperty: InteractionPolicyProperty;
+  readonly requestTypeId: URL;
+  readonly authorizationTypeId: URL;
+  readonly verifyRequest: <TContextData>(context: Context<TContextData>, options: InteractionRequestVerificationOptions<TRequest>) => Promise<InteractionRequestVerification<TRequest, TInteracting, TTarget>>;
+  readonly evaluatePolicy: <TContextData>(context: Context<TContextData>, options: InteractionPolicyEvaluationOptions<TContextData, TTarget>) => Promise<InteractionPolicyDecision>;
+  readonly createRequest: (options: InteractionRequestCreationOptions<TInteracting, TTarget>) => TRequest;
+  readonly createAuthorization: (options: InteractionAuthorizationCreationOptions<TInteracting, TTarget>) => TAuthorization;
+  readonly verifyAuthorization: <TContextData>(context: Context<TContextData>, options: InteractionAuthorizationVerificationOptions<TContextData, TAuthorization, TInteracting, TTarget>) => Promise<InteractionAuthorizationVerification<TAuthorization>>;
+  readonly createAccept: (options: InteractionAcceptOptions<TRequest, TAuthorization, TInteracting, TTarget>) => Accept;
+  readonly createReject: (options: InteractionRejectOptions<TRequest, TInteracting, TTarget>) => Reject;
+  readonly createRevocation: (options: InteractionRevocationCreationOptions<TAuthorization>) => Delete;
+  readonly recognizeImpolite: (source: TImpoliteSource) => RecognizedImpoliteInteraction<TInteracting, TTarget, TImpoliteSource> | null;
+  readonly getInteractionKey: (input: InteractionKeyInput<TInteracting, TTarget>) => InteractionKey;
+  readonly getAuthorizationKey: (input: InteractionAuthorizationKeyInput<TAuthorization>) => InteractionAuthorizationKey;
+}
+interface InteractionRequestVerificationOptions<TRequest extends Activity> {
+  readonly request: TRequest | URL;
+  readonly documentLoader?: DocumentLoader;
+}
+type InteractionRequestVerification<TRequest extends Activity, TInteracting extends Object$1, TTarget extends Object$1> = {
+  readonly verified: true;
+  readonly request: TRequest;
+  readonly requestId: URL;
+  readonly requester: URL;
+  readonly interactingObject: TInteracting;
+  readonly interactingObjectId: URL;
+  readonly interactionTarget: TTarget;
+  readonly interactionTargetId: URL;
+} | {
+  readonly verified: false;
+  readonly failure: InteractionRequestVerificationFailure;
+  readonly request?: TRequest;
+  readonly requestId?: URL;
+};
+type InteractionRequestVerificationFailure = {
+  readonly category: "unverifiable";
+  readonly type: "notDereferenceable";
+  readonly url: URL;
+  readonly cause?: unknown;
+} | {
+  readonly category: "unverifiable";
+  readonly type: "unauthorizedFetchRequired";
+  readonly url: URL;
+} | {
+  readonly category: "unverifiable";
+  readonly type: "invalidJsonLd";
+  readonly cause?: unknown;
+} | {
+  readonly category: "invalid";
+  readonly type: "wrongType";
+  readonly expectedType: URL;
+  readonly actualTypes: readonly URL[];
+} | {
+  readonly category: "invalid";
+  readonly type: "wrongInstrumentType";
+  readonly expectedTypes: readonly URL[];
+  readonly actualTypes: readonly URL[];
+} | {
+  readonly category: "invalid";
+  readonly type: "wrongObjectType";
+  readonly expectedTypes: readonly URL[];
+  readonly actualTypes: readonly URL[];
+} | {
+  readonly category: "invalid";
+  readonly type: "missingId" | "missingActor" | "missingObject" | "missingObjectId" | "missingInstrument" | "missingInstrumentId";
+} | {
+  readonly category: "invalid";
+  readonly type: "idMismatch" | "objectMismatch" | "instrumentMismatch";
+  readonly expected: URL;
+  readonly actual?: URL;
+} | {
+  readonly category: "unauthorized";
+  readonly type: "requesterMismatch";
+  readonly expected: URL;
+  readonly actual?: URL;
+};
+interface InteractionPolicyEvaluationOptions<TContextData, TTarget extends Object$1> {
+  readonly subject: TTarget;
+  readonly requester: URL;
+  readonly documentLoader?: DocumentLoader;
+  readonly matchesApprovalCollection?: MatchesApprovalCollection<TContextData>;
+}
+type MatchesApprovalCollection<TContextData> = (collection: URL, actor: URL, context: Context<TContextData>) => boolean | Promise<boolean>;
+type InteractionPolicyDecision = {
+  readonly result: "automatic";
+  readonly reason: InteractionPolicyMatchReason;
+} | {
+  readonly result: "manual";
+  readonly reason: InteractionPolicyMatchReason;
+} | {
+  readonly result: "denied";
+  readonly reason: InteractionPolicyDenialReason;
+};
+type InteractionPolicyMatchReason = {
+  readonly type: "self";
+} | {
+  readonly type: "default";
+  readonly default: "publicAutomatic";
+} | {
+  readonly type: "public";
+} | {
+  readonly type: "actor";
+  readonly actor: URL;
+} | {
+  readonly type: "collection";
+  readonly collection: URL;
+};
+type InteractionPolicyDenialReason = {
+  readonly type: "missingPolicy";
+} | {
+  readonly type: "missingRule";
+} | {
+  readonly type: "noMatch";
+} | {
+  readonly type: "unverifiableCollection";
+  readonly collection: URL;
+};
+interface InteractionRequestCreationOptions<TInteracting extends Object$1, TTarget extends Object$1> {
+  readonly id: URL;
+  readonly actor: URL;
+  readonly object: TTarget | URL;
+  readonly instrument: TInteracting | URL;
+  readonly to?: URL | readonly URL[];
+  readonly cc?: URL | readonly URL[];
+}
+interface InteractionAuthorizationCreationOptions<TInteracting extends Object$1, TTarget extends Object$1> {
+  readonly id: URL;
+  readonly attributedTo?: URL;
+  readonly interactingObject: TInteracting | URL;
+  readonly interactionTarget: TTarget | URL;
+}
+interface InteractionAuthorizationVerificationOptions<TContextData, TAuthorization extends Object$1, TInteracting extends Object$1, TTarget extends Object$1> {
+  readonly authorization: TAuthorization | URL;
+  readonly interactingObject: TInteracting | URL;
+  readonly interactionTarget: TTarget | URL;
+  readonly attributedTo?: URL;
+  readonly documentLoader?: DocumentLoader;
+  readonly getRevocation?: GetInteractionAuthorizationRevocation<TContextData>;
+  readonly verifyAuthenticity?: (authorization: TAuthorization, context: Context<TContextData>) => boolean | Promise<boolean>;
+}
+type InteractionAuthorizationVerification<TAuthorization extends Object$1> = {
+  readonly verified: true;
+  readonly authorization: TAuthorization;
+  readonly authorizationId: URL;
+} | {
+  readonly verified: false;
+  readonly failure: InteractionAuthorizationVerificationFailure;
+  readonly authorization?: TAuthorization;
+  readonly authorizationId?: URL;
+};
+type InteractionAuthorizationVerificationFailure = {
+  readonly category: "unverifiable";
+  readonly type: "notDereferenceable";
+  readonly url: URL;
+  readonly cause?: unknown;
+} | {
+  readonly category: "unverifiable";
+  readonly type: "unauthorizedFetchRequired";
+  readonly url: URL;
+} | {
+  readonly category: "unverifiable";
+  readonly type: "invalidJsonLd";
+  readonly cause?: unknown;
+} | {
+  readonly category: "unauthorized";
+  readonly type: "wrongType";
+  readonly expectedType: URL;
+  readonly actualTypes: readonly URL[];
+} | {
+  readonly category: "unauthorized";
+  readonly type: "missingId" | "missingObjectId" | "missingTargetId";
+} | {
+  readonly category: "unauthorized";
+  readonly type: "missingAttribution";
+} | {
+  readonly category: "unauthorized";
+  readonly type: "idMismatch" | "objectMismatch" | "targetMismatch";
+  readonly expected: URL;
+  readonly actual?: URL;
+} | {
+  readonly category: "unauthorized";
+  readonly type: "attributionMismatch";
+  readonly expected: URL;
+  readonly actual?: URL;
+} | {
+  readonly category: "unauthorized";
+  readonly type: "originMismatch";
+  readonly expectedOrigin: string;
+  readonly actualOrigin: string;
+} | {
+  readonly category: "unauthorized";
+  readonly type: "notAuthentic";
+  readonly detail?: string;
+  readonly cause?: unknown;
+} | {
+  readonly category: "revoked";
+  readonly type: "deleted";
+  readonly revoker?: URL;
+  readonly revoked?: Temporal.Instant;
+  readonly activity?: Delete;
+};
+type GetInteractionAuthorizationRevocation<TContextData> = (authorizationId: URL, context: Context<TContextData>) => InteractionAuthorizationRevocation | null | Promise<InteractionAuthorizationRevocation | null>;
+interface InteractionAuthorizationRevocation {
+  readonly revoker?: URL;
+  readonly revoked?: Temporal.Instant;
+  readonly activity?: Delete;
+}
+type InteractionAcceptOptions<TRequest extends Activity, TAuthorization extends Object$1, TInteracting extends Object$1, TTarget extends Object$1> = {
+  readonly mode: "polite";
+  readonly id: URL;
+  readonly actor: URL;
+  readonly request: TRequest | URL;
+  readonly authorization: TAuthorization | URL;
+  readonly to: URL | readonly URL[];
+  readonly cc?: URL | readonly URL[];
+} | {
+  readonly mode: "impolite";
+  readonly id: URL;
+  readonly actor: URL;
+  readonly interactingObject: TInteracting | URL;
+  readonly interactionTarget: TTarget | URL;
+  readonly authorization: TAuthorization | URL;
+  readonly to: URL | readonly URL[];
+  readonly cc?: URL | readonly URL[];
+};
+type InteractionRejectOptions<TRequest extends Activity, TInteracting extends Object$1, TTarget extends Object$1> = {
+  readonly mode: "polite";
+  readonly id: URL;
+  readonly actor: URL;
+  readonly request: TRequest | URL;
+  readonly to: URL | readonly URL[];
+  readonly cc?: URL | readonly URL[];
+} | {
+  readonly mode: "impolite";
+  readonly id: URL;
+  readonly actor: URL;
+  readonly interactingObject: TInteracting | URL;
+  readonly interactionTarget: TTarget | URL;
+  readonly to: URL | readonly URL[];
+  readonly cc?: URL | readonly URL[];
+};
+interface InteractionRevocationCreationOptions<TAuthorization extends Object$1> {
+  readonly id: URL;
+  readonly actor: URL;
+  readonly authorization: TAuthorization | URL;
+  readonly to: URL | readonly URL[];
+  readonly cc?: URL | readonly URL[];
+}
+interface RecognizedImpoliteInteraction<TInteracting extends Object$1, TTarget extends Object$1, TImpoliteSource extends Object$1> {
+  readonly requester: URL;
+  readonly interactingObject: TInteracting;
+  readonly interactingObjectId: URL;
+  readonly interactionTarget?: TTarget;
+  readonly interactionTargetId: URL;
+  readonly source: TImpoliteSource;
+  readonly evidence: ImpoliteInteractionEvidence;
+}
+type ImpoliteInteractionEvidence = {
+  readonly type: "activity";
+  readonly activityType: URL;
+} | {
+  readonly type: "property";
+  readonly property: URL;
+} | {
+  readonly type: "linkRel";
+  readonly rel: URL;
+};
+interface InteractionKeyInput<TInteracting extends Object$1, TTarget extends Object$1> {
+  readonly requester: URL;
+  readonly interactingObject: TInteracting | URL;
+  readonly interactionTarget: TTarget | URL;
+}
+interface InteractionKey {
+  readonly interaction: string;
+  readonly requester: URL;
+  readonly interactingObjectId: URL;
+  readonly interactionTargetId: URL;
+}
+interface InteractionAuthorizationKeyInput<TAuthorization extends Object$1> {
+  readonly authorization: TAuthorization | URL;
+}
+interface InteractionAuthorizationKey {
+  readonly interaction: string;
+  readonly authorizationId: URL;
+}
+//#endregion
+//#region src/announce.d.ts
+declare const announceInteraction: InteractionControl<AnnounceRequest, AnnounceAuthorization, Announce, Object$1, Announce>;
+//#endregion
+//#region src/feature.d.ts
+declare const featureInteraction: InteractionControl<FeatureRequest, FeatureAuthorization, FeaturedCollection, Actor, Object$1>;
+//#endregion
+//#region src/key.d.ts
+declare function formatInteractionKey(key: InteractionKey): string;
+declare function formatAuthorizationKey(key: InteractionAuthorizationKey): string;
+//#endregion
+//#region src/like.d.ts
+declare const likeInteraction: InteractionControl<LikeRequest, LikeAuthorization, Like, Object$1, Like>;
+//#endregion
+//#region src/quote.d.ts
+type QuotePost = Note | Article | Question | ChatMessage;
+type QuoteImpoliteSource = Create | QuotePost;
+declare const quoteInteraction: InteractionControl<QuoteRequest, QuoteAuthorization, QuotePost, Object$1, QuoteImpoliteSource>;
+//#endregion
+//#region src/reply.d.ts
+type ReplyPost = Note | Article | Question | ChatMessage;
+type ReplyImpoliteSource = Create | ReplyPost;
+declare const replyInteraction: InteractionControl<ReplyRequest, ReplyAuthorization, ReplyPost, Object$1, ReplyImpoliteSource>;
+//#endregion
+export { GetInteractionAuthorizationRevocation, ImpoliteInteractionEvidence, InteractionAcceptOptions, InteractionAuthorizationCreationOptions, InteractionAuthorizationKey, InteractionAuthorizationKeyInput, InteractionAuthorizationRevocation, InteractionAuthorizationVerification, InteractionAuthorizationVerificationFailure, InteractionAuthorizationVerificationOptions, InteractionControl, InteractionKey, InteractionKeyInput, InteractionName, InteractionPolicyDecision, InteractionPolicyDenialReason, InteractionPolicyEvaluationOptions, InteractionPolicyMatchReason, InteractionPolicyProperty, InteractionRejectOptions, InteractionRequestCreationOptions, InteractionRequestVerification, InteractionRequestVerificationFailure, InteractionRequestVerificationOptions, InteractionRevocationCreationOptions, MatchesApprovalCollection, type QuoteImpoliteSource, type QuotePost, RecognizedImpoliteInteraction, type ReplyImpoliteSource, type ReplyPost, announceInteraction, featureInteraction, formatAuthorizationKey, formatInteractionKey, likeInteraction, quoteInteraction, replyInteraction };