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

package/dist/mod.d.cts

@@ -1,59 +1,151 @@
-import { Context, Federation, KvStore, MessageQueue } from "@fedify/fedify";
-import { Actor } from "@fedify/fedify/vocab";
+import { Context, KvStore, MessageQueue } from "@fedify/fedify";
+import { Actor } from "@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 {
+  /**
+   * Key-value store for persisting relay data such as follower information
+   * and cryptographic keys.
+   */
   kv: KvStore;
-  domain?: string;
+  /**
+   * The origin URL where the relay is hosted.
+   * Must be a full URL including the protocol (e.g., `"https://relay.example.com"`).
+   */
+  origin: string;
+  /**
+   * Display name for the relay actor.
+   * Defaults to `"ActivityPub Relay"`.
+   */
+  name?: string;
+  /**
+   * Factory function for creating a document loader to fetch remote
+   * ActivityPub objects.
+   */
   documentLoaderFactory?: DocumentLoaderFactory;
+  /**
+   * Factory function for creating an authenticated document loader
+   * that signs HTTP requests when fetching remote objects.
+   */
   authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory;
-  federation?: Federation<void>;
+  /**
+   * Message queue for background activity processing.
+   * Recommended for production to handle activity forwarding asynchronously.
+   */
   queue?: MessageQueue;
+  /**
+   * Handler function that determines whether to approve or reject
+   * subscription requests from remote actors.
+   * Return `true` to approve or `false` to reject.
+   */
+  subscriptionHandler: SubscriptionRequestHandler;
 }
 /**
- * Base interface for ActivityPub relay implementations.
+ * Internal storage format for follower data in KV store.
+ * Contains JSON-LD representation of the actor.
+ * Exported for internal package use but not re-exported from mod.ts.
+ *
+ * @internal
  */
-interface Relay {
-  readonly domain: string;
-  fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
-}
+
 /**
- * A Mastodon-compatible ActivityPub relay implementation.
- * This relay follows Mastodon's relay protocol for maximum compatibility
- * with Mastodon instances.
+ * A follower of the relay with validated Actor instance.
+ * This is the public API type returned by follower query methods.
  *
  * @since 2.0.0
  */
-declare class MastodonRelay implements Relay {
-  #private;
-  constructor(options: RelayOptions);
-  get domain(): string;
-  fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
+interface RelayFollower {
+  /** The actor ID (URL) of the follower. */
+  readonly actorId: string;
+  /** The validated Actor object. */
+  readonly actor: Actor;
+  /** The follower's state. */
+  readonly state: "pending" | "accepted";
 }
 /**
- * A LitePub-compatible ActivityPub relay implementation.
- * This relay follows LitePub's relay protocol and extensions for
- * enhanced federation capabilities.
+ * Public interface for ActivityPub relay implementations.
+ * Use {@link createRelay} to create a relay instance.
  *
  * @since 2.0.0
  */
-declare class LitePubRelay implements Relay {
-  #private;
-  constructor(options: RelayOptions);
-  get domain(): string;
+interface Relay {
+  /**
+   * Handle incoming HTTP requests.
+   *
+   * @param request The incoming HTTP request
+   * @returns The HTTP response
+   */
   fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
+  /**
+   * 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>;
+  /**
+   * Gets the URI of the relay actor.
+   *
+   * @returns The URI of the relay actor
+   */
+  getActorUri(): Promise<URL>;
+  /**
+   * Gets the shared inbox URI of the relay.
+   *
+   * @returns The shared inbox URI
+   */
+  getSharedInboxUri(): Promise<URL>;
 }
+/**
+ * Type predicate to check if a value is valid RelayFollowerData from KV store.
+ * Validates the storage format (JSON-LD), not the deserialized Actor instance.
+ *
+ * @param value The value to check
+ * @returns true if the value is a RelayFollowerData
+ * @internal
+ */
+//#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(),
+ *   origin: "https://relay.example.com",
+ *   subscriptionHandler: async (ctx, actor) => true,
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+declare function createRelay(type: RelayType, options: RelayOptions): Relay;
 //#endregion
-export { LitePubRelay, MastodonRelay, Relay, RelayOptions };
+export { RELAY_SERVER_ACTOR, Relay, RelayFollower, RelayOptions, RelayType, SubscriptionRequestHandler, createRelay };

package/dist/mod.d.ts

@@ -1,59 +1,152 @@
-import { Context, Federation, KvStore, MessageQueue } from "@fedify/fedify";
-import { Actor } from "@fedify/fedify/vocab";
+import { Temporal } from "@js-temporal/polyfill";
+import { Context, KvStore, MessageQueue } from "@fedify/fedify";
+import { Actor } from "@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 {
+  /**
+   * Key-value store for persisting relay data such as follower information
+   * and cryptographic keys.
+   */
   kv: KvStore;
-  domain?: string;
+  /**
+   * The origin URL where the relay is hosted.
+   * Must be a full URL including the protocol (e.g., `"https://relay.example.com"`).
+   */
+  origin: string;
+  /**
+   * Display name for the relay actor.
+   * Defaults to `"ActivityPub Relay"`.
+   */
+  name?: string;
+  /**
+   * Factory function for creating a document loader to fetch remote
+   * ActivityPub objects.
+   */
   documentLoaderFactory?: DocumentLoaderFactory;
+  /**
+   * Factory function for creating an authenticated document loader
+   * that signs HTTP requests when fetching remote objects.
+   */
   authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory;
-  federation?: Federation<void>;
+  /**
+   * Message queue for background activity processing.
+   * Recommended for production to handle activity forwarding asynchronously.
+   */
   queue?: MessageQueue;
+  /**
+   * Handler function that determines whether to approve or reject
+   * subscription requests from remote actors.
+   * Return `true` to approve or `false` to reject.
+   */
+  subscriptionHandler: SubscriptionRequestHandler;
 }
 /**
- * Base interface for ActivityPub relay implementations.
+ * Internal storage format for follower data in KV store.
+ * Contains JSON-LD representation of the actor.
+ * Exported for internal package use but not re-exported from mod.ts.
+ *
+ * @internal
  */
-interface Relay {
-  readonly domain: string;
-  fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
-}
+
 /**
- * A Mastodon-compatible ActivityPub relay implementation.
- * This relay follows Mastodon's relay protocol for maximum compatibility
- * with Mastodon instances.
+ * A follower of the relay with validated Actor instance.
+ * This is the public API type returned by follower query methods.
  *
  * @since 2.0.0
  */
-declare class MastodonRelay implements Relay {
-  #private;
-  constructor(options: RelayOptions);
-  get domain(): string;
-  fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
+interface RelayFollower {
+  /** The actor ID (URL) of the follower. */
+  readonly actorId: string;
+  /** The validated Actor object. */
+  readonly actor: Actor;
+  /** The follower's state. */
+  readonly state: "pending" | "accepted";
 }
 /**
- * A LitePub-compatible ActivityPub relay implementation.
- * This relay follows LitePub's relay protocol and extensions for
- * enhanced federation capabilities.
+ * Public interface for ActivityPub relay implementations.
+ * Use {@link createRelay} to create a relay instance.
  *
  * @since 2.0.0
  */
-declare class LitePubRelay implements Relay {
-  #private;
-  constructor(options: RelayOptions);
-  get domain(): string;
+interface Relay {
+  /**
+   * Handle incoming HTTP requests.
+   *
+   * @param request The incoming HTTP request
+   * @returns The HTTP response
+   */
   fetch(request: Request): Promise<Response>;
-  setSubscriptionHandler(handler: SubscriptionRequestHandler): this;
+  /**
+   * 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>;
+  /**
+   * Gets the URI of the relay actor.
+   *
+   * @returns The URI of the relay actor
+   */
+  getActorUri(): Promise<URL>;
+  /**
+   * Gets the shared inbox URI of the relay.
+   *
+   * @returns The shared inbox URI
+   */
+  getSharedInboxUri(): Promise<URL>;
 }
+/**
+ * Type predicate to check if a value is valid RelayFollowerData from KV store.
+ * Validates the storage format (JSON-LD), not the deserialized Actor instance.
+ *
+ * @param value The value to check
+ * @returns true if the value is a RelayFollowerData
+ * @internal
+ */
+//#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(),
+ *   origin: "https://relay.example.com",
+ *   subscriptionHandler: async (ctx, actor) => true,
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+declare function createRelay(type: RelayType, options: RelayOptions): Relay;
 //#endregion
-export { LitePubRelay, MastodonRelay, Relay, RelayOptions };
+export { RELAY_SERVER_ACTOR, Relay, RelayFollower, RelayOptions, RelayType, SubscriptionRequestHandler, createRelay };