Add Relay interface and make implementation classes internal

- Add public Relay interface with fetch(), listFollowers(), getFollower()
- Update BaseRelay to implement Relay interface (marked @internal)
- Change createRelay() return type from BaseRelay to Relay
- Remove MastodonRelay and LitePubRelay exports from mod.ts
- Update README to document interface-based API

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: sij411

packages/relay/README.md

@@ -263,19 +263,19 @@ Factory function to create a relay instance.
 function createRelay(
   type: "mastodon" | "litepub",
   options: RelayOptions
-): BaseRelay
+): Relay
 ~~~~
 
 **Parameters:**
 
  -  `type`: The type of relay to create (`"mastodon"` or `"litepub"`)
  -  `options`: Configuration options for the relay
 
-**Returns:** A relay instance (`MastodonRelay` or `LitePubRelay`)
+**Returns:** A `Relay` instance
 
-### `BaseRelay`
+### `Relay`
 
-Abstract base class for relay implementations.
+Public interface for ActivityPub relay implementations.
 
 #### Methods
 
@@ -285,21 +285,14 @@ Abstract base class for relay implementations.
  -  `getFollower(actorId: string): Promise<RelayFollower | null>`: Gets
     a specific follower by actor ID
 
-### `MastodonRelay`
+#### Relay types
 
-A Mastodon-compatible ActivityPub relay implementation that extends `BaseRelay`.
+The relay type is specified when calling `createRelay()`:
 
- -  Uses direct activity forwarding
- -  Immediate subscription approval
- -  Compatible with standard ActivityPub implementations
-
-### `LitePubRelay`
-
-A LitePub-compatible ActivityPub relay implementation that extends `BaseRelay`.
-
- -  Uses bidirectional following
- -  Activities wrapped in `Announce`
- -  Two-phase subscription (pending → accepted)
+ -  `"mastodon"`: Mastodon-compatible relay using direct activity forwarding,
+    immediate subscription approval, and LD signatures
+ -  `"litepub"`: LitePub-compatible relay using bidirectional following,
+    activities wrapped in `Announce`, and two-phase subscription
 
 ### `RelayOptions`
 

packages/relay/src/base.ts

@@ -2,6 +2,7 @@ import type { Federation, FederationBuilder } from "@fedify/fedify";
 import { isActor, Object as APObject } from "@fedify/fedify/vocab";
 import {
   isRelayFollowerData,
+  type Relay,
   type RelayFollower,
   type RelayOptions,
 } from "./types.ts";
@@ -10,9 +11,9 @@ import {
  * Abstract base class for relay implementations.
  * Provides common infrastructure for both Mastodon and LitePub relays.
  *
- * @since 2.0.0
+ * @internal
  */
-export abstract class BaseRelay {
+export abstract class BaseRelay implements Relay {
   protected federationBuilder: FederationBuilder<RelayOptions>;
   protected options: RelayOptions;
   protected federation?: Federation<RelayOptions>;
@@ -49,14 +50,11 @@ export abstract class BaseRelay {
     actorId: string,
     data: unknown,
   ): Promise<RelayFollower | null> {
-    // Validate storage format
     if (!isRelayFollowerData(data)) return null;
 
-    // Deserialize and validate actor
     const actor = await APObject.fromJsonLd(data.actor);
     if (!isActor(actor)) return null;
 
-    // Construct and return RelayFollower
     return {
       actorId,
       actor,

packages/relay/src/factory.ts

@@ -1,8 +1,7 @@
-import type { BaseRelay } from "./base.ts";
 import { relayBuilder } from "./builder.ts";
 import { LitePubRelay } from "./litepub.ts";
 import { MastodonRelay } from "./mastodon.ts";
-import type { RelayOptions, RelayType } from "./types.ts";
+import type { Relay, RelayOptions, RelayType } from "./types.ts";
 
 /**
  * Factory function to create a relay instance.
@@ -28,7 +27,7 @@ import type { RelayOptions, RelayType } from "./types.ts";
 export function createRelay(
   type: RelayType,
   options: RelayOptions,
-): BaseRelay {
+): Relay {
   switch (type) {
     case "mastodon":
       return new MastodonRelay(options, relayBuilder);

packages/relay/src/mod.ts

@@ -8,9 +8,8 @@
  * @module
  */
 export { createRelay } from "./factory.ts";
-export { LitePubRelay } from "./litepub.ts";
-export { MastodonRelay } from "./mastodon.ts";
 export {
+  type Relay,
   RELAY_SERVER_ACTOR,
   type RelayFollower,
   type RelayOptions,

packages/relay/src/types.ts

@@ -62,6 +62,37 @@ export interface RelayFollower {
   readonly state: "pending" | "accepted";
 }
 
+/**
+ * Public interface for ActivityPub relay implementations.
+ * Use {@link createRelay} to create a relay instance.
+ *
+ * @since 2.0.0
+ */
+export interface Relay {
+  /**
+   * Handle incoming HTTP requests.
+   *
+   * @param request The incoming HTTP request
+   * @returns The HTTP response
+   */
+  fetch(request: Request): Promise<Response>;
+
+  /**
+   * Lists all followers of the relay.
+   *
+   * @returns An async iterator of follower entries
+   */
+  listFollowers(): AsyncIterableIterator<RelayFollower>;
+
+  /**
+   * Gets a specific follower by actor ID.
+   *
+   * @param actorId The actor ID (URL) of the follower to retrieve
+   * @returns The follower entry if found, null otherwise
+   */
+  getFollower(actorId: string): Promise<RelayFollower | null>;
+}
+
 /**
  * Type predicate to check if a value is valid RelayFollowerData from KV store.
  * Validates the storage format (JSON-LD), not the deserialized Actor instance.