@fedify/relay 2.0.0-dev.1908 → 2.0.0-dev.85

package/dist/mod.cjs

@@ -1,3 +1,6 @@
+
+        const { Temporal } = require("@js-temporal/polyfill");
+      
 //#region rolldown:runtime
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -23,180 +26,194 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const __fedify_fedify = __toESM(require("@fedify/fedify"));
 const __fedify_fedify_vocab = __toESM(require("@fedify/fedify/vocab"));
+const __logtape_logtape = __toESM(require("@logtape/logtape"));
 
-//#region src/relay.ts
+//#region src/types.ts
 const RELAY_SERVER_ACTOR = "relay";
 /**
-* A Mastodon-compatible ActivityPub relay implementation.
-* This relay follows Mastodon's relay protocol for maximum compatibility
-* with Mastodon instances.
+* Type predicate to check if a value is a valid RelayFollower.
+* Provides both runtime validation and compile-time type narrowing.
 *
-* @since 2.0.0
+* @param value The value to check
+* @returns true if the value is a RelayFollower
 */
-var MastodonRelay = class {
-	#federation;
-	#options;
-	#subscriptionHandler;
-	constructor(options) {
-		this.#options = options;
-		this.#federation = options.federation ?? (0, __fedify_fedify.createFederation)({
-			kv: options.kv,
-			queue: options.queue,
-			documentLoaderFactory: options.documentLoaderFactory,
-			authenticatedDocumentLoaderFactory: options.authenticatedDocumentLoaderFactory
-		});
-		this.#federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
-			if (identifier !== RELAY_SERVER_ACTOR) return null;
-			const keys = await ctx.getActorKeyPairs(identifier);
-			return new __fedify_fedify_vocab.Service({
-				id: ctx.getActorUri(identifier),
-				preferredUsername: identifier,
-				name: "ActivityPub Relay",
-				summary: "Mastodon-compatible ActivityPub relay server",
-				inbox: ctx.getInboxUri(),
-				followers: ctx.getFollowersUri(identifier),
-				url: ctx.getActorUri(identifier),
-				publicKey: keys[0].cryptographicKey,
-				assertionMethods: keys.map((k) => k.multikey)
-			});
-		}).setKeyPairsDispatcher(async (_ctx, identifier) => {
-			if (identifier !== RELAY_SERVER_ACTOR) return [];
-			const rsaPairJson = await options.kv.get([
-				"keypair",
-				"rsa",
-				identifier
-			]);
-			const ed25519PairJson = await options.kv.get([
-				"keypair",
-				"ed25519",
-				identifier
-			]);
-			if (rsaPairJson == null || ed25519PairJson == null) {
-				const rsaPair$1 = await (0, __fedify_fedify.generateCryptoKeyPair)("RSASSA-PKCS1-v1_5");
-				const ed25519Pair$1 = await (0, __fedify_fedify.generateCryptoKeyPair)("Ed25519");
-				await options.kv.set([
-					"keypair",
-					"rsa",
-					identifier
-				], {
-					privateKey: await (0, __fedify_fedify.exportJwk)(rsaPair$1.privateKey),
-					publicKey: await (0, __fedify_fedify.exportJwk)(rsaPair$1.publicKey)
-				});
-				await options.kv.set([
-					"keypair",
-					"ed25519",
-					identifier
-				], {
-					privateKey: await (0, __fedify_fedify.exportJwk)(ed25519Pair$1.privateKey),
-					publicKey: await (0, __fedify_fedify.exportJwk)(ed25519Pair$1.publicKey)
-				});
-				return [rsaPair$1, ed25519Pair$1];
-			}
-			const rsaPair = {
-				privateKey: await (0, __fedify_fedify.importJwk)(rsaPairJson.privateKey, "private"),
-				publicKey: await (0, __fedify_fedify.importJwk)(rsaPairJson.publicKey, "public")
-			};
-			const ed25519Pair = {
-				privateKey: await (0, __fedify_fedify.importJwk)(ed25519PairJson.privateKey, "private"),
-				publicKey: await (0, __fedify_fedify.importJwk)(ed25519PairJson.publicKey, "public")
-			};
-			return [rsaPair, ed25519Pair];
+function isRelayFollower(value) {
+	if (!value || typeof value !== "object") return false;
+	const obj = value;
+	return "actor" in obj && "state" in obj && typeof obj.state === "string" && (obj.state === "pending" || obj.state === "accepted");
+}
+
+//#endregion
+//#region src/builder.ts
+const relayBuilder = (0, __fedify_fedify.createFederationBuilder)();
+relayBuilder.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
+	if (identifier !== RELAY_SERVER_ACTOR) return null;
+	const keys = await ctx.getActorKeyPairs(identifier);
+	return new __fedify_fedify_vocab.Application({
+		id: ctx.getActorUri(identifier),
+		preferredUsername: identifier,
+		name: ctx.data.name ?? "ActivityPub Relay",
+		inbox: ctx.getInboxUri(),
+		followers: ctx.getFollowersUri(identifier),
+		following: ctx.getFollowingUri(identifier),
+		url: ctx.getActorUri(identifier),
+		publicKey: keys[0].cryptographicKey,
+		assertionMethods: keys.map((k) => k.multikey)
+	});
+}).setKeyPairsDispatcher(async (ctx, identifier) => {
+	if (identifier !== RELAY_SERVER_ACTOR) return [];
+	const rsaPairJson = await ctx.data.kv.get([
+		"keypair",
+		"rsa",
+		identifier
+	]);
+	const ed25519PairJson = await ctx.data.kv.get([
+		"keypair",
+		"ed25519",
+		identifier
+	]);
+	if (rsaPairJson == null || ed25519PairJson == null) {
+		const rsaPair$1 = await (0, __fedify_fedify.generateCryptoKeyPair)("RSASSA-PKCS1-v1_5");
+		const ed25519Pair$1 = await (0, __fedify_fedify.generateCryptoKeyPair)("Ed25519");
+		await ctx.data.kv.set([
+			"keypair",
+			"rsa",
+			identifier
+		], {
+			privateKey: await (0, __fedify_fedify.exportJwk)(rsaPair$1.privateKey),
+			publicKey: await (0, __fedify_fedify.exportJwk)(rsaPair$1.publicKey)
 		});
-		this.#federation.setFollowersDispatcher("/users/{identifier}/followers", async (_ctx, identifier) => {
-			if (identifier !== RELAY_SERVER_ACTOR) return null;
-			const activityIds = await options.kv.get(["followers"]) ?? [];
-			const actors = [];
-			for (const activityId of activityIds) {
-				const actorJson = await options.kv.get(["follower", activityId]);
-				const actor = await __fedify_fedify_vocab.Object.fromJsonLd(actorJson);
-				if (!(0, __fedify_fedify_vocab.isActor)(actor)) continue;
-				actors.push(actor);
-			}
-			return { items: actors };
-		});
-		this.#federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(__fedify_fedify_vocab.Follow, async (ctx, follow) => {
-			if (follow.id == null || follow.objectId == null) return;
-			const parsed = ctx.parseUri(follow.objectId);
-			const isPublicFollow = follow.objectId.href === "https://www.w3.org/ns/activitystreams#Public";
-			if (!isPublicFollow && parsed?.type !== "actor") return;
-			const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
-			const recipient = await follow.getActor(ctx);
-			if (recipient == null || recipient.id == null || recipient.preferredUsername == null || recipient.inboxId == null) return;
-			let approved = false;
-			if (this.#subscriptionHandler) approved = await this.#subscriptionHandler(ctx, recipient);
-			if (approved) {
-				const followers = await options.kv.get(["followers"]) ?? [];
-				followers.push(follow.id.href);
-				await options.kv.set(["followers"], followers);
-				await options.kv.set(["follower", follow.id.href], await recipient.toJsonLd());
-				await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, recipient, new __fedify_fedify_vocab.Accept({
-					id: new URL(`#accepts`, relayActorUri),
-					actor: relayActorUri,
-					object: follow
-				}));
-			} else await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, recipient, new __fedify_fedify_vocab.Reject({
-				id: new URL(`#rejects`, relayActorUri),
-				actor: relayActorUri,
-				object: follow
-			}));
-		}).on(__fedify_fedify_vocab.Undo, async (ctx, undo) => {
-			const activity = await undo.getObject(ctx);
-			if (activity instanceof __fedify_fedify_vocab.Follow) {
-				if (activity.id == null || activity.actorId == null) return;
-				const activityId = activity.id.href;
-				const followers = await options.kv.get(["followers"]) ?? [];
-				const updatedFollowers = followers.filter((id) => id !== activityId);
-				await options.kv.set(["followers"], updatedFollowers);
-				options.kv.delete(["follower", activityId]);
-			} else console.warn("Unsupported object type ({type}) for Undo activity: {object}", {
-				type: activity?.constructor.name,
-				object: activity
-			});
-		}).on(__fedify_fedify_vocab.Create, async (ctx, create) => {
-			const sender = await create.getActor(ctx);
-			const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
-			await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
-				skipIfUnsigned: true,
-				excludeBaseUris,
-				preferSharedInbox: true
-			});
-		}).on(__fedify_fedify_vocab.Delete, async (ctx, deleteActivity) => {
-			const sender = await deleteActivity.getActor(ctx);
-			const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
-			await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
-				skipIfUnsigned: true,
-				excludeBaseUris,
-				preferSharedInbox: true
-			});
-		}).on(__fedify_fedify_vocab.Move, async (ctx, deleteActivity) => {
-			const sender = await deleteActivity.getActor(ctx);
-			const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
-			await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
-				skipIfUnsigned: true,
-				excludeBaseUris,
-				preferSharedInbox: true
-			});
-		}).on(__fedify_fedify_vocab.Update, async (ctx, deleteActivity) => {
-			const sender = await deleteActivity.getActor(ctx);
-			const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
-			await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
-				skipIfUnsigned: true,
-				excludeBaseUris,
-				preferSharedInbox: true
-			});
+		await ctx.data.kv.set([
+			"keypair",
+			"ed25519",
+			identifier
+		], {
+			privateKey: await (0, __fedify_fedify.exportJwk)(ed25519Pair$1.privateKey),
+			publicKey: await (0, __fedify_fedify.exportJwk)(ed25519Pair$1.publicKey)
 		});
+		return [rsaPair$1, ed25519Pair$1];
 	}
-	get domain() {
-		return this.#options.domain || "localhost";
+	const rsaPair = {
+		privateKey: await (0, __fedify_fedify.importJwk)(rsaPairJson.privateKey, "private"),
+		publicKey: await (0, __fedify_fedify.importJwk)(rsaPairJson.publicKey, "public")
+	};
+	const ed25519Pair = {
+		privateKey: await (0, __fedify_fedify.importJwk)(ed25519PairJson.privateKey, "private"),
+		publicKey: await (0, __fedify_fedify.importJwk)(ed25519PairJson.publicKey, "public")
+	};
+	return [rsaPair, ed25519Pair];
+});
+async function getFollowerActors(ctx) {
+	const actors = [];
+	for await (const { value } of ctx.data.kv.list(["follower"])) {
+		if (!isRelayFollower(value)) continue;
+		if (value.state !== "accepted") continue;
+		const actor = await __fedify_fedify_vocab.Object.fromJsonLd(value.actor);
+		if (!(0, __fedify_fedify_vocab.isActor)(actor)) continue;
+		actors.push(actor);
 	}
-	fetch(request) {
-		return this.#federation.fetch(request, { contextData: void 0 });
+	return actors;
+}
+async function dispatchRelayActors(ctx, identifier) {
+	if (identifier !== RELAY_SERVER_ACTOR) return null;
+	const actors = await getFollowerActors(ctx);
+	return { items: actors };
+}
+relayBuilder.setFollowersDispatcher("/users/{identifier}/followers", dispatchRelayActors);
+relayBuilder.setFollowingDispatcher("/users/{identifier}/following", dispatchRelayActors);
+
+//#endregion
+//#region src/base.ts
+/**
+* Abstract base class for relay implementations.
+* Provides common infrastructure for both Mastodon and LitePub relays.
+*
+* @since 2.0.0
+*/
+var BaseRelay = class {
+	federationBuilder;
+	options;
+	federation;
+	constructor(options, relayBuilder$1) {
+		this.options = options;
+		this.federationBuilder = relayBuilder$1;
 	}
-	setSubscriptionHandler(handler) {
-		this.#subscriptionHandler = handler;
-		return this;
+	async fetch(request) {
+		if (this.federation == null) {
+			this.federation = await this.federationBuilder.build(this.options);
+			this.setupInboxListeners();
+		}
+		return await this.federation.fetch(request, { contextData: this.options });
 	}
 };
+
+//#endregion
+//#region src/follow.ts
+/**
+* Validate Follow activity and return follower actor if valid.
+* This validation is common to both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param follow The Follow activity to validate
+* @returns The follower Actor if valid, null otherwise
+*/
+async function validateFollowActivity(ctx, follow) {
+	if (follow.id == null || follow.objectId == null) return null;
+	const parsed = ctx.parseUri(follow.objectId);
+	const isPublicFollow = follow.objectId.href === "https://www.w3.org/ns/activitystreams#Public";
+	if (!isPublicFollow && parsed?.type !== "actor") return null;
+	const follower = await follow.getActor(ctx);
+	if (follower == null || follower.id == null || follower.preferredUsername == null || follower.inboxId == null) return null;
+	return follower;
+}
+/**
+* Send Accept or Reject response for a Follow activity.
+* This is common to both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param follow The Follow activity being responded to
+* @param follower The actor who sent the Follow
+* @param approved Whether the follow was approved
+*/
+async function sendFollowResponse(ctx, follow, follower, approved) {
+	const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
+	const Activity = approved ? __fedify_fedify.Accept : __fedify_fedify.Reject;
+	const action = approved ? "accepts" : "rejects";
+	await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Activity({
+		id: new URL(`#${action}`, relayActorUri),
+		actor: relayActorUri,
+		object: follow
+	}));
+}
+/**
+* Handle Undo activity for Follow.
+* This logic is identical for both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param undo The Undo activity to handle
+* @param logger The logger instance to use for warnings
+*/
+async function handleUndoFollow(ctx, undo, logger$2) {
+	const activity = await undo.getObject({
+		crossOrigin: "trust",
+		...ctx
+	});
+	if (activity instanceof __fedify_fedify.Follow) {
+		if (activity.id == null || activity.actorId == null) return;
+		await ctx.data.kv.delete(["follower", activity.actorId.href]);
+	} else logger$2.warn("Unsupported object type ({type}) for Undo activity: {object}", {
+		type: activity?.constructor.name,
+		object: activity
+	});
+}
+
+//#endregion
+//#region src/litepub.ts
+const logger$1 = (0, __logtape_logtape.getLogger)([
+	"fedify",
+	"relay",
+	"litepub"
+]);
 /**
 * A LitePub-compatible ActivityPub relay implementation.
 * This relay follows LitePub's relay protocol and extensions for
@@ -204,26 +221,137 @@ var MastodonRelay = class {
 *
 * @since 2.0.0
 */
-var LitePubRelay = class {
-	#federation;
-	#options;
-	#subscriptionHandler;
-	constructor(options) {
-		this.#options = options;
-		this.#federation = (0, __fedify_fedify.createFederation)({ kv: options.kv });
+var LitePubRelay = class extends BaseRelay {
+	async #announceToFollowers(ctx, activity) {
+		const sender = await activity.getActor(ctx);
+		const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
+		const announce = new __fedify_fedify.Announce({
+			id: new URL(`/announce#${crypto.randomUUID()}`, ctx.origin),
+			actor: ctx.getActorUri(RELAY_SERVER_ACTOR),
+			object: activity.objectId,
+			to: __fedify_fedify.PUBLIC_COLLECTION,
+			published: Temporal.Now.instant()
+		});
+		await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", announce, {
+			excludeBaseUris,
+			preferSharedInbox: true
+		});
 	}
-	get domain() {
-		return this.#options.domain || "localhost";
+	setupInboxListeners() {
+		if (this.federation != null) this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(__fedify_fedify.Follow, async (ctx, follow) => {
+			const follower = await validateFollowActivity(ctx, follow);
+			if (!follower || !follower.id) return;
+			const existingFollow = await ctx.data.kv.get(["follower", follower.id.href]);
+			if (existingFollow?.state === "pending") return;
+			const approved = await this.options.subscriptionHandler(ctx, follower);
+			if (approved) {
+				await ctx.data.kv.set(["follower", follower.id.href], {
+					actor: await follower.toJsonLd(),
+					state: "pending"
+				});
+				await sendFollowResponse(ctx, follow, follower, approved);
+				const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
+				await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new __fedify_fedify.Follow({
+					actor: relayActorUri,
+					object: follower.id,
+					to: follower.id
+				}));
+			} else await sendFollowResponse(ctx, follow, follower, approved);
+		}).on(__fedify_fedify.Accept, async (ctx, accept) => {
+			const follow = await accept.getObject({
+				crossOrigin: "trust",
+				...ctx
+			});
+			if (!(follow instanceof __fedify_fedify.Follow)) return;
+			const relayActorId = follow.actorId;
+			if (relayActorId == null) return;
+			const followerActor = await accept.getActor();
+			if (!(0, __fedify_fedify.isActor)(followerActor) || !followerActor.id) return;
+			const parsed = ctx.parseUri(relayActorId);
+			if (parsed == null || parsed.type !== "actor") return;
+			const followerData = await ctx.data.kv.get(["follower", followerActor.id.href]);
+			if (followerData == null) return;
+			const updatedFollowerData = {
+				...followerData,
+				state: "accepted"
+			};
+			await ctx.data.kv.set(["follower", followerActor.id.href], updatedFollowerData);
+		}).on(__fedify_fedify.Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, logger$1)).on(__fedify_fedify.Create, async (ctx, create) => await this.#announceToFollowers(ctx, create)).on(__fedify_fedify.Update, async (ctx, update) => await this.#announceToFollowers(ctx, update)).on(__fedify_fedify.Move, async (ctx, move) => await this.#announceToFollowers(ctx, move)).on(__fedify_fedify.Delete, async (ctx, deleteActivity) => await this.#announceToFollowers(ctx, deleteActivity)).on(__fedify_fedify.Announce, async (ctx, announce) => await this.#announceToFollowers(ctx, announce));
 	}
-	fetch(request) {
-		return this.#federation.fetch(request, { contextData: void 0 });
+};
+
+//#endregion
+//#region src/mastodon.ts
+const logger = (0, __logtape_logtape.getLogger)([
+	"fedify",
+	"relay",
+	"mastodon"
+]);
+/**
+* A Mastodon-compatible ActivityPub relay implementation.
+* This relay follows Mastodon's relay protocol for compatibility
+* with Mastodon instances.
+*
+* @since 2.0.0
+*/
+var MastodonRelay = class extends BaseRelay {
+	async #forwardToFollowers(ctx, activity) {
+		const sender = await activity.getActor(ctx);
+		const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
+		await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
+			skipIfUnsigned: true,
+			excludeBaseUris,
+			preferSharedInbox: true
+		});
 	}
-	setSubscriptionHandler(handler) {
-		this.#subscriptionHandler = handler;
-		return this;
+	setupInboxListeners() {
+		if (this.federation != null) this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(__fedify_fedify.Follow, async (ctx, follow) => {
+			const follower = await validateFollowActivity(ctx, follow);
+			if (!follower || !follower.id) return;
+			const approved = await this.options.subscriptionHandler(ctx, follower);
+			if (approved) await ctx.data.kv.set(["follower", follower.id.href], {
+				actor: await follower.toJsonLd(),
+				state: "accepted"
+			});
+			await sendFollowResponse(ctx, follow, follower, approved);
+		}).on(__fedify_fedify.Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, logger)).on(__fedify_fedify.Create, async (ctx, create) => await this.#forwardToFollowers(ctx, create)).on(__fedify_fedify.Delete, async (ctx, deleteActivity) => await this.#forwardToFollowers(ctx, deleteActivity)).on(__fedify_fedify.Move, async (ctx, move) => await this.#forwardToFollowers(ctx, move)).on(__fedify_fedify.Update, async (ctx, update) => await this.#forwardToFollowers(ctx, update)).on(__fedify_fedify.Announce, async (ctx, announce) => await this.#forwardToFollowers(ctx, announce));
 	}
 };
 
+//#endregion
+//#region src/factory.ts
+/**
+* Factory function to create a relay instance.
+*
+* @param type The type of relay to create ("mastodon" or "litepub")
+* @param options Configuration options for the relay
+* @returns A relay instance
+*
+* @example
+* ```ts
+* import { createRelay } from "@fedify/relay";
+* import { MemoryKvStore } from "@fedify/fedify";
+*
+* const relay = createRelay("mastodon", {
+*   kv: new MemoryKvStore(),
+*   domain: "relay.example.com",
+*   subscriptionHandler: async (ctx, actor) => true,
+* });
+* ```
+*
+* @since 2.0.0
+*/
+function createRelay(type, options) {
+	switch (type) {
+		case "mastodon": return new MastodonRelay(options, relayBuilder);
+		case "litepub": return new LitePubRelay(options, relayBuilder);
+	}
+}
+
 //#endregion
 exports.LitePubRelay = LitePubRelay;
-exports.MastodonRelay = MastodonRelay;
+exports.MastodonRelay = MastodonRelay;
+exports.RELAY_SERVER_ACTOR = RELAY_SERVER_ACTOR;
+exports.createRelay = createRelay;
+exports.isRelayFollower = isRelayFollower;
+exports.relayBuilder = relayBuilder;

package/dist/mod.d.cts

@@ -1,46 +1,90 @@
-import { Context, Federation, KvStore, MessageQueue } from "@fedify/fedify";
+import { Context, Federation, FederationBuilder, KvStore, MessageQueue } from "@fedify/fedify";
 import { Actor } from "@fedify/fedify/vocab";
 import { AuthenticatedDocumentLoaderFactory, DocumentLoaderFactory } from "@fedify/vocab-runtime";
 
-//#region src/relay.d.ts
-
+//#region src/types.d.ts
+declare const RELAY_SERVER_ACTOR = "relay";
+/**
+ * Supported relay types.
+ */
+type RelayType = "mastodon" | "litepub";
 /**
  * Handler for subscription requests (Follow/Undo activities).
  */
-type SubscriptionRequestHandler = (ctx: Context<void>, clientActor: Actor) => Promise<boolean>;
+type SubscriptionRequestHandler = (ctx: Context<RelayOptions>, clientActor: Actor) => Promise<boolean>;
 /**
  * Configuration options for the ActivityPub relay.
  */
 interface RelayOptions {
   kv: KvStore;
   domain?: string;
+  name?: string;
   documentLoaderFactory?: DocumentLoaderFactory;
   authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory;
-  federation?: Federation<void>;
   queue?: MessageQueue;
+  subscriptionHandler: SubscriptionRequestHandler;
+}
+interface RelayFollower {
+  readonly actor: unknown;
+  readonly state: "pending" | "accepted";
 }
 /**
- * Base interface for ActivityPub relay implementations.
+ * Type predicate to check if a value is a valid RelayFollower.
+ * Provides both runtime validation and compile-time type narrowing.
+ *
+ * @param value The value to check
+ * @returns true if the value is a RelayFollower
  */
-interface Relay {
-  readonly domain: string;
-  fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
-}
+declare function isRelayFollower(value: unknown): value is RelayFollower;
+//#endregion
+//#region src/builder.d.ts
+declare const relayBuilder: FederationBuilder<RelayOptions>;
+//#endregion
+//#region src/base.d.ts
 /**
- * A Mastodon-compatible ActivityPub relay implementation.
- * This relay follows Mastodon's relay protocol for maximum compatibility
- * with Mastodon instances.
+ * Abstract base class for relay implementations.
+ * Provides common infrastructure for both Mastodon and LitePub relays.
  *
  * @since 2.0.0
  */
-declare class MastodonRelay implements Relay {
-  #private;
-  constructor(options: RelayOptions);
-  get domain(): string;
+declare abstract class BaseRelay {
+  protected federationBuilder: FederationBuilder<RelayOptions>;
+  protected options: RelayOptions;
+  protected federation?: Federation<RelayOptions>;
+  constructor(options: RelayOptions, relayBuilder: FederationBuilder<RelayOptions>);
   fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
+  /**
+   * Set up inbox listeners for handling ActivityPub activities.
+   * Each relay type implements this method with protocol-specific logic.
+   */
+  protected abstract setupInboxListeners(): void;
 }
+//#endregion
+//#region src/factory.d.ts
+/**
+ * Factory function to create a relay instance.
+ *
+ * @param type The type of relay to create ("mastodon" or "litepub")
+ * @param options Configuration options for the relay
+ * @returns A relay instance
+ *
+ * @example
+ * ```ts
+ * import { createRelay } from "@fedify/relay";
+ * import { MemoryKvStore } from "@fedify/fedify";
+ *
+ * const relay = createRelay("mastodon", {
+ *   kv: new MemoryKvStore(),
+ *   domain: "relay.example.com",
+ *   subscriptionHandler: async (ctx, actor) => true,
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+declare function createRelay(type: RelayType, options: RelayOptions): BaseRelay;
+//#endregion
+//#region src/litepub.d.ts
 /**
  * A LitePub-compatible ActivityPub relay implementation.
  * This relay follows LitePub's relay protocol and extensions for
@@ -48,12 +92,22 @@ declare class MastodonRelay implements Relay {
  *
  * @since 2.0.0
  */
-declare class LitePubRelay implements Relay {
+declare class LitePubRelay extends BaseRelay {
   #private;
-  constructor(options: RelayOptions);
-  get domain(): string;
-  fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
+  protected setupInboxListeners(): void;
+}
+//#endregion
+//#region src/mastodon.d.ts
+/**
+ * A Mastodon-compatible ActivityPub relay implementation.
+ * This relay follows Mastodon's relay protocol for compatibility
+ * with Mastodon instances.
+ *
+ * @since 2.0.0
+ */
+declare class MastodonRelay extends BaseRelay {
+  #private;
+  protected setupInboxListeners(): void;
 }
 //#endregion
-export { LitePubRelay, MastodonRelay, Relay, RelayOptions };
+export { LitePubRelay, MastodonRelay, RELAY_SERVER_ACTOR, RelayFollower, RelayOptions, RelayType, SubscriptionRequestHandler, createRelay, isRelayFollower, relayBuilder };